MODULAR_STACK // CLIENT_LIBRARY

libostk

The official userspace client library for interacting with the ostk kernel and daemons. Designed for application developers building wrappers, IDE extensions, or automated CI/CD runners.

License: MIT | Target: Rust (native) & node/python (via IPC bindings)

OVERVIEW

libostk acts as the programmatic gateway to the ostk daemon. Instead of invoking CLI commands via subprocess spawning (which degrades performance and compromises security), tools like Claude Code, Cursor extensions, or Windmill integrations link against libostk to establish low-latency IPC channels, read real-time audits, and negotiate sandboxing capability pins.

Key Responsibilities

Establishing JSON-RPC 2.0 communication over Unix Domain Sockets (.ostk/ostk.sock).
Tailing the audit.jsonl log using robust inode-rotation detection.
Parsing unstructured console lines using envelope heuristics.
Injecting caller identities (e.g., Discord username, Github action run ID) for strict audit attribution.

JSON-RPC IPC PROTOCOL

The ostk daemon listens on a UNIX domain socket located at .ostk/ostk.sock relative to the project root. If the socket does not exist or fails to respond, clients can spawn the daemon on demand by invoking ostk boot.

JSON-RPC 2.0 EXAMPLES

// Request: Register Caller & Request Read Permissions
{
  "jsonrpc": "2.0",
  "method": "kernel.negotiate",
  "params": {
    "caller_id": {
      "driver": "windmill",
      "identity": "[email protected]",
      "run_id": "job_948f93"
    },
    "requested_pins": ["read_file", "execute_url"]
  },
  "id": 1
}

// Response: Negotiated Permissions & Session Token
{
  "jsonrpc": "2.0",
  "result": {
    "session_id": "sess_88f2b38a",
    "granted_pins": ["read_file"],
    "denied_pins": ["execute_url"],
    "trust_tier": "T2"
  },
  "id": 1
}

AUDIT TAILING WITH INODE TRACKING

Security tools must follow the audit tail without dropping frames. Because log-rotation (renaming/compressing log files) causes traditional file polling to fail, the libostk Rust module audit_tail listens for file system modification events and verifies inodes.

AUDIT TAIL RUST INTERFACE

pub struct AuditTail {
    path: PathBuf,
    current_inode: u64,
    reader: BufReader<File>,
}

impl AuditTail {
    pub fn new(path: PathBuf) -> io::Result<Self>;
    
    /// Fetches the next event. If the file is rotated or replaced, 
    /// the tailer detects the inode change, re-opens the path,
    /// and flushes any remaining bytes from the stale inode.
    pub fn next_line(&mut self) -> io::Result<Option<String>>;
}

ENVELOPE PARSING

The client contains a presentation-only envelope parser designed for styling CLI outputs. It matches the pattern [keyword] k:v .... Note that this parser is strictly for presentation and HUD views; it MUST NOT produce events for the state dispatcher.

// Raw console line:
[fs_ops] action:write target:/src/lib.rs size:124B actor:[email protected]

// libostk parses this into:
Envelope {
    subsystem: "fs_ops",
    fields: {
        "action": "write",
        "target": "/src/lib.rs",
        "size": "124B",
        "actor": "[email protected]"
    }
}