System Architecture
A single Rust binary. Three layers: the kernel, the daemon, and drivers. No runtime dependencies.
The Kernel
Statically linked. Seven primitives built on Unix-inspired filesystem operations. Boots from .ostk/ and begins tracking.
KERNEL_SUBSYSTEMS
The Daemon
ostk listen starts the kernel daemon — a long-lived anchor process that holds the socket, the process table, and the scheduler.
SESSION_MGMT
Agents run as managed sessions. Each has its own context, heartbeat, and drain snapshot.
SCHEDULER_TICK
Background task wakes the scheduler on a timer. Inspects fleet state, dispatches work, reaps dead sessions.
CRASH_RECOVERY
Drain snapshots at every turn boundary. On restart, fold(audit.jsonl) reconstructs fleet and rehydrates sessions.
CLIENT_MULTIPLEX
TUI, MCP clients, CLI one-shots, and IDE extensions attach/detach via kernel socket. Sessions persist.
The daemon is a cache, not a ledger. Source of truth is the filesystem — audit.jsonl, gen_table.jsonl, drain snapshots. A restart reconstructs identical state from disk.
→ SESSION_TOPOLOGY
Write Interception
Default: ostk intercepts at the tool layer. Agents call kernel primitives (file:edit, file:write, file:create) that apply policy, locking, and version tracking before bytes hit disk. No LD_PRELOAD, no ptrace, no kqueue observer.
Tool-layer interception has one honest limitation: if an agent escapes the tool path — by invoking a shell that writes directly — the kernel never sees it. ostk addresses this two ways:
- Process sandbox (always on): the
nonosubsystem enforces filesystem restrictions at the OS layer — Landlock on Linux, Seatbelt on macOS. Agents physically cannot write outside their allowed paths, regardless of how they try. Implemented insrc/kernel/sandbox.rs. - FUSE passthrough (optional):
ostk mount(built with--features fuse) mounts a FUSE filesystem that mirrors the project tree and logs every write op through the kernel. Optional because FUSE adds dependencies; off by default. Implemented insrc/fuse/passthrough.rs.
Tool-layer covers the expected path; the OS sandbox covers the escape path; FUSE is the observability upgrade for users who want every byte logged regardless of how it got written. No single interception layer is load-bearing on its own.
FCP Drivers
Drivers extend the kernel with domain capabilities via the File Context Protocol — MCP servers that let LLMs interact with complex file formats through a verb-based DSL.