@guangnao/agent-os 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 guangnao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# @guangnao/agent-os
+
+A **microkernel operating system for LLM agents** — not a framework, not a library.
+
+The distinguishing line: the kernel **owns execution and resources**, and a process
+(an "agent") affects the world **only through capability-mediated syscalls**. That
+boundary — not the vocabulary — is what makes this a *system*.
+
+- **Metered by construction** — every LLM/tool call is charged to a per-process budget (tokens, $, tool-calls, wall-clock, memory). Over budget → the kernel kills it.
+- **Least privilege** — a process holds no ambient authority, only unforgeable capabilities you delegate. Attenuate and pass them like file descriptors.
+- **Let it crash** — link/monitor + OTP-style supervisors restart flaky agents.
+- **Deterministic** — record/replay driver I/O and a virtual clock reproduce a run byte-for-byte.
+- **Batteries included** — LLM (OpenAI-compatible), tools, KV, cross-node gateway, worker-thread offload, and a WASM sandbox drivers; a ready-made ReAct agent.
+
+## Install
+
+```bash
+npm install @guangnao/agent-os
+```
+
+ESM-only, types bundled. Node ≥ 18.
+
+## Quick start — a real LLM agent in ~30 lines
+
+A ReAct agent that thinks → calls a tool → observes → answers, with every LLM and
+tool call metered by the kernel. Point it at any OpenAI-compatible endpoint
+(DeepSeek below).
+
+```ts
+import { Kernel, llmDriver, toolDriver, openaiChat, reactAgent } from '@guangnao/agent-os'
+import type { ProcessImage, ToolSchema, AgentResult, BootGrant } from '@guangnao/agent-os'
+
+// 1. Tools are plain functions; the agent reaches them through a metered device.
+const tools = {
+  calc: ({ op, a, b }: { op: string; a: number; b: number }) =>
+    ({ result: op === 'mul' ? a * b : op === 'add' ? a + b : a - b }),
+}
+const schemas: ToolSchema[] = [{
+  name: 'calc', description: 'arithmetic on two numbers',
+  parameters: { type: 'object', required: ['op', 'a', 'b'], properties: {
+    op: { type: 'string', enum: ['add', 'sub', 'mul'] }, a: { type: 'number' }, b: { type: 'number' },
+  } },
+}]
+
+// 2. Boot a kernel; register the drivers (the only way out to the world).
+const k = new Kernel()
+k.registerDriver(llmDriver(openaiChat({
+  apiKey: process.env.DEEPSEEK_API_KEY!,
+  baseUrl: 'https://api.deepseek.com/v1',
+  model: 'deepseek-chat',
+})))
+k.registerDriver(toolDriver(tools))
+
+// 3. init delegates the llm + tools devices to a ReAct agent and awaits its answer.
+const init: ProcessImage = { name: 'init', async main(sys) {
+  const g = (await sys.recv<BootGrant>()).body
+  const { cap } = await sys.spawn(
+    reactAgent({ task: 'What is 23 * 19? Use calc, then give just the number.', tools: schemas }),
+    { link: true, quota: { tokens: 200_000, usd: 1, toolCalls: 20, mem: 100_000 } },
+  )
+  await sys.send(cap, {}, { caps: [                       // delegate caps like fds
+    sys.derive(g.devices['llm']!,   ['open']),
+    sys.derive(g.devices['tools']!, ['open']),
+    sys.selfCap(),
+  ] })
+  const r = (await sys.recv<AgentResult>()).body
+  console.log(r.answer, `(${r.steps} steps)`)              // → 437 (2 steps)
+} }
+
+await k.boot(init, { grant: ['llm', 'tools'], quota: { tokens: 2_000_000, usd: 10, children: 4 } })
+```
+
+A process is just `{ name, async main(sys, args) }`. It holds no kernel object — only
+`sys`, the syscall surface. Everything it can do (spawn, send, open a device, remember,
+read an LLM) is a syscall, charged and capability-checked.
+
+## Architecture (microkernel, 3 rings)
+
+```
+Ring 2 · Userland   — agents + services: pure main(sys) bodies, syscalls only
+──────────────────── the syscall ABI (the only boundary)
+Ring 1 · Services   — drivers (LLM/tools/memory), supervisors, name service
+────────────────────
+Ring 0 · Kernel     — PIDs · syscall dispatch · scheduler · accounting · cap table
+                      · IPC switch · supervision mechanism · event log
+```
+
+| Subsystem | What it is | Agent twist |
+|---|---|---|
+| **Process** | kernel-owned PCB + PID; the kernel runs/parks/kills it | not an object you `new` |
+| **Scheduler** | cooperative, by **reductions** (syscall budget per quantum) + priority/EDF deadlines | schedules **token/tool cost**, not CPU time |
+| **Accounting** | hierarchical (cgroup) quotas: tokens, tool calls, $, wall-clock, memory, children | parent's budget bounds its whole subtree |
+| **Capabilities** | unforgeable handles; attenuate + delegate; no ambient authority | least-privilege, confused-deputy-proof |
+| **IPC** | mailboxes + a switch; caps ride on messages (fd-passing) | the only way agents share data |
+| **Memory (MMU)** | context window = paged address space; watermark evict → lossy summary → recall; OOM | pluggable keyword/vector recall |
+| **Supervision** | link/monitor → `Down` (kernel) + restart strategies (userland) | OTP "let it crash" |
+| **Drivers** | LLM/tools/memory/net behind one `open/read/write` | swap a vendor = swap a driver; metered at the chokepoint |
+| **Event log** | every syscall/charge/fault, stamped | `ps`/`top`, audit, deterministic replay |
+
+## Driver standard library
+
+| Driver | Purpose |
+|---|---|
+| `llmDriver(chat)` | LLM device; wrap any `ChatFn` |
+| `openaiChat(cfg)` | a `ChatFn` for any OpenAI-compatible API (OpenAI, DeepSeek, …); pass `onDelta` on a request for SSE token streaming |
+| `toolDriver(tools)` | expose plain functions as a metered tool device |
+| `kvDriver()` | a shared key-value store device |
+| `gatewayDriver(forward)` | cross-node IPC over a **trusted** channel (in-process / private link) |
+| `secureGatewayDriver(forward, key)` | cross-node IPC over a **hostile wire** — HMAC-sealed, replay-protected |
+| `workerDriver(tasks)` | offload CPU tasks to real `worker_threads` (isolated heap, another core) |
+| `wasmDriver(modules)` | run untrusted **compute** in a zero-import WebAssembly sandbox |
+
+## Beyond the basics
+
+- **Deterministic record/replay** — journal driver I/O; replay reproduces a run exactly.
+- **Virtual clock** — discrete-event time; sleeps cost zero real time, traces are byte-identical.
+- **Snapshot / migration** — `kernel.snapshot(pid)` → durable state (context + mailbox + budget); `kernel.restore(snap, image)` resumes it on any kernel (live migration across nodes).
+- **Event-sourcing store** — `MemoryStore` / `FileStore` persist every event + I/O; rebuild a replayable journal from disk.
+- **Vector recall** — context page-in via `KeywordRecaller` (default) or `VectorRecaller(embed)`.
+- **Supervisors & name service** — `supervisor({ strategy, children })` (`one_for_one` / `one_for_all` / `rest_for_one`) and a capability broker.
+
+## Security & operations
+
+- **Authenticated transport** — off-machine messages are HMAC-SHA256 sealed over a canonical `(to, nonce, body)` encoding; `kernel.ingress()` verifies in constant time and drops replays. **Capabilities never cross the wire** — a verified peer can address a pid, never forge authority over one.
+- **Crash recovery** — `Kernel.replayFrom(store)` rebuilds a kernel that replays persisted driver I/O, reproducing a run exactly with no live calls. The event-sourcing log *is* the recovery mechanism.
+- **Backpressure** — `quota.maxMailbox` bounds an inbox; a full one parks senders until the consumer drains it (no drops, order preserved).
+- **Metrics** — `kernel.metrics()` and `kernel.metricsText()` (Prometheus exposition) over the whole event history.
+- **ABI versioning** — `ABI_VERSION` is stamped into snapshots; `restore` refuses an incompatible version rather than silently resuming mismatched state.
+- **Tested for robustness** — property tests (accounting conservation/atomicity, capability attenuation), adversarial tests (malicious-driver quota-kill), and chaos tests (spawn/kill churn) run on a seeded PRNG.
+
+## Performance
+
+Single-core, cooperative kernel — these are one-core ceilings. Reproduce with `npm run bench`:
+
+```
+IPC round-trips      ~530k /s   send → recv → send → recv
+Process spawn+exit   ~135k /s   spawn → notify → exit (O(caps-owned) revoke — flat under load)
+Context switches     ~2.1M /s   sys.yield (O(1) dispatch — flat to thousands of procs)
+Fan-in recv          ~1.2M /s   32 senders → 1 deep mailbox (O(1) dequeue — flat under load)
+Driver reads         ~840k /s   syscall + driver dispatch + accounting
+Memory remember      ~2.2M /s   context write
+Memory recall        ~1.6M /s   keyword page-in
+Memory under paging  ~900k /s   write at the mem ceiling (O(1) amortized — flat vs resident size)
+
+Parallel I/O         ~16×       16 latency-bound reads: sys.readAll vs sequential
+```
+
+`sys.readAll(handle, reqs)` fires every request concurrently under a single park —
+a ReAct turn's N tool calls become one network-bound wait, not N — while staying
+fully metered and replay-deterministic (op ids are assigned in order).
+
+*(Apple M-series, Node 25; indicative, not a controlled benchmark.)*
+
+## Real network + true isolation
+
+- **TCP transport** — `serveTcp(env => kernel.ingress(env))` + `dialTcp(host, port)` move HMAC-sealed envelopes over real sockets between kernels on different ports/machines. Authentic frames are delivered; tampered/forged ones are dropped at ingress.
+- **Sandboxed agents** — `sandbox(code)` runs untrusted agent logic in a real worker thread (separate V8 isolate + heap). It holds no reference to `sys`, the cap table, or kernel memory; its only authority is a mediated syscall RPC through a trusted reference-monitor shim (allow-listed syscalls + the usual capability/quota checks). It can't read kernel memory, forge a capability, or call a syscall it wasn't granted.
+
+### Honest scope
+
+Production-shaped but young — naming it straight:
+
+- **Distributed** has authenticated envelopes + replay guard + a real TCP transport, but no built-in service discovery, failure detector, or partition handling yet.
+- **WASM sandbox** confines *compute*; the agent-process isolation story is `sandbox()` (worker-thread), not WASM-of-the-whole-agent.
+- **Migration** serializes a process's context + mailbox + budget, not its JS stack — so it migrates message-loop state machines, not arbitrary suspended call stacks.
+
+## Requirements
+
+- Node ≥ 18, ESM (`"type": "module"` or `.mjs`).
+- TypeScript optional but recommended — full types ship with the package.
+
+## License
+
+MIT

package/dist/abi/capability.d.ts

@@ -0,0 +1,45 @@
+import type { Pid, CapRef, DriverName } from './ids';
+/** What a capability governs. */
+export type Resource = {
+    readonly kind: 'process';
+    readonly pid: Pid;
+} | {
+    readonly kind: 'remote';
+    readonly node: string;
+    readonly pid: Pid;
+} | {
+    readonly kind: 'device';
+    readonly driver: DriverName;
+} | {
+    readonly kind: 'spawn';
+} | {
+    readonly kind: 'budget';
+    readonly grant: BudgetGrant;
+};
+/** A transferable resource grant a parent carves off its own account for a child. */
+export interface BudgetGrant {
+    readonly tokens?: number;
+    readonly toolCalls?: number;
+    readonly wallMs?: number;
+    readonly usd?: number;
+    readonly children?: number;
+}
+/** Fine-grained operations a capability may permit. Attenuation = dropping rights. */
+export type Right = 'send' | 'monitor' | 'open' | 'read' | 'write' | 'spawn' | 'kill';
+/** A constraint carried by a capability and checked on every use. Caveats only ATTENUATE: they ride down the
+ *  derivation chain (a child inherits its parent's), so a holder can't `derive` one away. `expires` = the cap
+ *  is invalid once the kernel clock passes `at` — a TTL / temporary delegation. */
+export type Caveat = {
+    readonly kind: 'expires';
+    readonly at: number;
+};
+/** Kernel-side capability record. Holders never see this — only the CapRef handle. */
+export interface Capability {
+    readonly ref: CapRef;
+    owner: Pid;
+    readonly resource: Resource;
+    readonly rights: ReadonlySet<Right>;
+    readonly caveats: readonly Caveat[];
+    revoked: boolean;
+}
+export declare const hasRight: (cap: Capability, r: Right) => boolean;

package/dist/abi/driver.d.ts

@@ -0,0 +1,23 @@
+import type { Pid } from './ids';
+/** Cost a driver op incurs against the caller's account (the kernel charges it). */
+export interface DriverCost {
+    readonly tokens?: number;
+    readonly toolCalls?: number;
+    readonly usd?: number;
+    readonly reductions?: number;
+}
+export interface DriverResult<T = unknown> {
+    readonly value: T;
+    readonly cost?: DriverCost;
+}
+/** A driver instance, opened per process. */
+export interface DriverHandle {
+    read?(req: unknown): Promise<DriverResult>;
+    write?(data: unknown): Promise<DriverResult>;
+    close?(): Promise<void>;
+}
+export interface Driver {
+    readonly name: string;
+    /** Open a per-process handle. `owner` lets the driver scope/meter per caller. */
+    open(owner: Pid, params?: unknown): Promise<DriverHandle>;
+}

package/dist/abi/ids.d.ts

@@ -0,0 +1,20 @@
+export type Pid = number & {
+    readonly __pid: unique symbol;
+};
+export type CapRef = string & {
+    readonly __cap: unique symbol;
+};
+export type MsgId = string & {
+    readonly __msg: unique symbol;
+};
+export type SegId = string & {
+    readonly __seg: unique symbol;
+};
+export type DriverName = string & {
+    readonly __drv: unique symbol;
+};
+export declare function newSegId(): SegId;
+/** Mint a fresh, hard-to-guess capability handle (holder presents it; authority lives kernel-side). */
+export declare function newCapRef(): CapRef;
+export declare function newMsgId(): MsgId;
+export declare const drv: (name: string) => DriverName;

package/dist/abi/index.d.ts

@@ -0,0 +1,11 @@
+export type { Pid, CapRef, MsgId, SegId, DriverName } from './ids';
+export { newCapRef, newMsgId, newSegId, drv } from './ids';
+/** The syscall-ABI contract version. Snapshots carry it; restore rejects a mismatch, so a process
+ *  state serialized under one ABI can't be silently resumed under an incompatible one. */
+export declare const ABI_VERSION = 1;
+export type { Segment, Pager } from './memory';
+export type { Resource, Right, Capability, BudgetGrant } from './capability';
+export { hasRight } from './capability';
+export type { Message, SendOptions } from './message';
+export type { Sys, ProcessImage, SpawnOptions, Quota, ExitReason, LogLevel, Down, Term, } from './syscall';
+export type { Driver, DriverHandle, DriverResult, DriverCost } from './driver';

package/dist/abi/memory.d.ts

@@ -0,0 +1,20 @@
+import type { SegId } from './ids';
+export interface Segment {
+    readonly id: SegId;
+    readonly body: unknown;
+    readonly tokens: number;
+    readonly pinned: boolean;
+    readonly summary?: boolean;
+}
+/** Pluggable paging policy. The kernel calls it under memory pressure; an
+ *  implementation may summarize via an LLM driver (async) or just drop. */
+export interface Pager {
+    /**
+     * Free at least `need` tokens from `resident` (unpinned, oldest-first is typical).
+     * Return the segments to evict, and optionally one summary segment to leave behind.
+     */
+    pageOut(resident: readonly Segment[], need: number): Promise<{
+        readonly evict: readonly SegId[];
+        readonly summary?: Omit<Segment, 'id'>;
+    }>;
+}

package/dist/abi/message.d.ts

@@ -0,0 +1,18 @@
+import type { Pid, MsgId, CapRef } from './ids';
+export interface Message<T = unknown> {
+    readonly id: MsgId;
+    readonly from: Pid;
+    readonly to: Pid;
+    readonly body: T;
+    /** Capabilities handed to the receiver (fd-passing). Empty for most messages. */
+    readonly caps: readonly CapRef[];
+    /** Correlates a reply to a request (RPC). */
+    readonly corr?: MsgId;
+    /** Wall-clock deadline; the kernel drops the message if delivered late. */
+    readonly deadline?: number;
+}
+export interface SendOptions {
+    readonly caps?: readonly CapRef[];
+    readonly corr?: MsgId;
+    readonly deadline?: number;
+}

package/dist/abi/syscall.d.ts

@@ -0,0 +1,158 @@
+import type { Pid, CapRef, SegId } from './ids';
+import type { Right, Resource } from './capability';
+import type { Message, SendOptions } from './message';
+import type { Segment } from './memory';
+/** Lifetime resource limits enforced by the kernel at syscall time. */
+export interface Quota {
+    readonly tokens?: number;
+    readonly toolCalls?: number;
+    readonly wallMs?: number;
+    readonly usd?: number;
+    readonly children?: number;
+    readonly mem?: number;
+    readonly maxMailbox?: number;
+}
+export type ExitReason = {
+    readonly kind: 'normal';
+} | {
+    readonly kind: 'killed';
+    readonly by: Pid;
+} | {
+    readonly kind: 'quota';
+    readonly resource: keyof Quota;
+} | {
+    readonly kind: 'fault';
+    readonly error: string;
+} | {
+    readonly kind: 'deadline';
+} | {
+    readonly kind: 'shutdown';
+};
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Kernel→process notification that a monitored/linked process died. */
+export interface Down {
+    readonly $: 'down';
+    readonly pid: Pid;
+    readonly reason: ExitReason;
+}
+/** Kernel→process graceful-stop request (SIGTERM): handle it in your recv loop (clean up, then exit). */
+export interface Term {
+    readonly $: 'term';
+    readonly from: Pid;
+}
+export interface SpawnOptions<Args = unknown> {
+    readonly args?: Args;
+    /** Caps handed to the child at birth (subset/derivations of yours — no ambient authority). */
+    readonly caps?: readonly CapRef[];
+    /** Budget carved from YOUR account for the child (parent pays for children). */
+    readonly quota?: Quota;
+    /** If true, the parent is linked: child death sends a Down to the parent. Default false. */
+    readonly link?: boolean;
+    /** Scheduling priority — higher runs sooner. Default 0. */
+    readonly priority?: number;
+    /** Soft deadline: ms from spawn by which it must finish, else it's killed (reason 'deadline'). */
+    readonly deadline?: number;
+}
+export interface ProcessImage<Args = unknown> {
+    readonly name: string;
+    /** Process body. Runs until it returns (→ normal exit) or calls sys.exit(). */
+    main(sys: Sys, args: Args): Promise<void>;
+}
+export interface Sys {
+    /** Own pid. */
+    self(): Pid;
+    /** A fresh cap to yourself — your "return address" — with send + monitor rights: the holder can reply
+     *  AND be notified (a Down) when you die, so brokers like the name service can drop stale entries. No kill. */
+    selfCap(): CapRef;
+    /** Block until a message arrives (process goes 'waiting', descheduled, costs nothing while blocked). */
+    recv<T = unknown>(): Promise<Message<T>>;
+    /** Send to a process/handle you hold a 'send'/'write' cap for. May delegate caps (fd-passing). */
+    send(target: CapRef, body: unknown, opts?: SendOptions): Promise<void>;
+    /** Publish THIS process under a well-known name so peers can find it without knowing its pid. First-come:
+     *  throws if a LIVE process already holds the name. Auto-cleared when this process exits. */
+    register(name: string): void;
+    /** Withdraw a name you registered (no-op if you don't hold it). */
+    unregister(name: string): void;
+    /** Resolve a name to a SEND-only cap for the service (least privilege — no kill/monitor), or undefined if
+     *  no live process holds it. */
+    lookup(name: string): Promise<CapRef | undefined>;
+    /** Address a process on ANOTHER node: returns a SEND-only proxy cap for (node, pid). send() to it egresses a
+     *  sealed envelope to that node's ingress. Addressing only — authority never crosses the wire; the remote
+     *  node still enforces its own local checks. Requires a route (kernel.connect) and a transportKey. */
+    dial(node: string, pid: Pid): CapRef;
+    /** Spawn an image the peer node published (registerImage) by NAME, and get a SEND proxy to the new remote
+     *  process. The spawned process boots with a `reply` proxy back to you, so the two can converse over the wire. */
+    spawnRemote(node: string, name: string, args?: unknown): Promise<CapRef>;
+    /** Create a child with exactly the caps + budget you give it. Returns its pid + a cap to talk to it. */
+    spawn<A>(image: ProcessImage<A>, opts?: SpawnOptions<A>): Promise<{
+        readonly pid: Pid;
+        readonly cap: CapRef;
+    }>;
+    /** Terminate self. Never returns. */
+    exit(reason?: ExitReason): Promise<never>;
+    /** Weaken a cap you hold to a subset of rights; send the result to delegate least privilege. */
+    derive(cap: CapRef, rights: readonly Right[]): CapRef;
+    /** Weaken a cap further with rights AND/OR a caveat (e.g. expiresInMs → a TTL cap). Restrictions only:
+     *  the caveat is inherited by any later derivation, so a delegate can't strip the expiry. */
+    attenuate(cap: CapRef, opts: {
+        readonly rights?: readonly Right[];
+        readonly expiresInMs?: number;
+    }): CapRef;
+    /** Invalidate a cap you minted (and any derivations) — revocation is transitive. */
+    revoke(cap: CapRef): void;
+    /** Open a device cap → a handle cap with read/write rights. */
+    open(device: CapRef): Promise<CapRef>;
+    read<T = unknown>(handle: CapRef, req?: unknown): Promise<T>;
+    /** Batch-read one handle: issue every request CONCURRENTLY (one park), each metered + journaled
+     *  in order. The parallel-I/O primitive — N tool calls become one network-bound wait, not N. */
+    readAll<T = unknown>(handle: CapRef, reqs: readonly unknown[]): Promise<T[]>;
+    write(handle: CapRef, data: unknown): Promise<void>;
+    /** Watch a process; receive a Down message when it dies (one-way, no restart — that's the supervisor's job). */
+    monitor(target: CapRef): Promise<void>;
+    /** Block until the target (you hold a 'monitor' cap for) exits; return its ExitReason. The ergonomic
+     *  reaper — wait for a specific child and learn why it died (vs monitor()'s async Down). Returns at once
+     *  if it already exited. */
+    waitpid(target: CapRef): Promise<ExitReason>;
+    /** Kill a process you hold a 'kill' cap for (supervision policy — one_for_all/rest_for_one). SIGKILL. */
+    signal(target: CapRef, reason?: ExitReason): Promise<void>;
+    /** SIGSTOP — pause a process (needs a 'kill' cap): it stays alive but isn't scheduled until resume(). */
+    suspend(target: CapRef): Promise<void>;
+    /** SIGCONT — resume a process you suspended. */
+    resume(target: CapRef): Promise<void>;
+    /** SIGTERM — ask a process to stop GRACEFULLY: delivers a { $: 'term' } message it handles in recv then exits. */
+    term(target: CapRef): Promise<void>;
+    /** Write a segment into your context. Pinned segments survive paging. May page out / OOM-kill. */
+    remember(body: unknown, opts?: {
+        tokens?: number;
+        pin?: boolean;
+    }): Promise<SegId>;
+    /** The resident working set — what you'd feed the LLM right now. */
+    workingSet(): readonly Segment[];
+    /** Page matching segments back in from swap (a page fault resolved from long-term memory). */
+    recall(query: string, k?: number): Promise<readonly Segment[]>;
+    /** Free a segment (resident or swapped). */
+    forget(id: SegId): void;
+    /** Pin/unpin a segment against eviction. */
+    pin(id: SegId, on?: boolean): void;
+    sleep(ms: number): Promise<void>;
+    /** Voluntarily yield the rest of this quantum (cooperative preemption point). */
+    yield(): Promise<void>;
+    /** Adjust own scheduling: change priority and/or (re)set a relative deadline (ms from now). */
+    sched(opts: {
+        readonly priority?: number;
+        readonly deadline?: number;
+    }): void;
+    /** Remaining lifetime budget. */
+    budget(): Readonly<Quota>;
+    /** Current kernel time (ms). The kernel's clock — virtual under a VirtualClock — so userland timing
+     *  (e.g. a supervisor's restart-intensity window) stays deterministic and replayable. Use this, not
+     *  Date.now(). */
+    now(): number;
+    log(level: LogLevel, msg: string, fields?: Record<string, unknown>): void;
+    /** Register a callback to run when THIS process terminates (any reason — normal, fault, kill, deadline).
+     *  For releasing EXTERNAL resources the kernel can't see (worker threads, child processes, timers): a
+     *  process that's killed mid-`main` never returns, so a `finally` won't fire — this hook still does. */
+    onCleanup(fn: () => void): void;
+}
+/** Re-export the resource shape so userland can describe caps it derives. */
+export type { Resource };

package/dist/drivers/gateway.d.ts

@@ -0,0 +1,8 @@
+import type { Driver } from '../abi/index';
+import { type SealedEnvelope } from '../kernel/transport';
+/** `forward(toPid, body)` ships a message to the peer node; returns whether it was delivered.
+ *  TRUSTED transport: no authentication — use only in-process or over a private channel. */
+export declare function gatewayDriver(forward: (to: number, body: unknown) => boolean, name?: string): Driver;
+/** AUTHENTICATED transport: seals each message (HMAC + nonce) before it hits the wire, so a
+ *  hostile network can't forge, tamper, or replay it. The peer kernel verifies via `ingress()`. */
+export declare function secureGatewayDriver(forward: (env: SealedEnvelope) => boolean, key: string, name?: string): Driver;

package/dist/drivers/index.d.ts

@@ -0,0 +1,8 @@
+export { llmDriver } from './llm';
+export type { ChatFn, LlmRequest, LlmReply, ChatMessage, ToolCallReq, ToolSchema } from './llm';
+export { toolDriver } from './tools';
+export type { ToolFn, ToolCall } from './tools';
+export { kvDriver } from './kv';
+export { gatewayDriver, secureGatewayDriver } from './gateway';
+export { workerDriver } from './worker';
+export { wasmDriver } from './wasm';

package/dist/drivers/kv.d.ts

@@ -0,0 +1,2 @@
+import type { Driver } from '../abi/index';
+export declare function kvDriver(name?: string): Driver;

package/dist/drivers/llm.d.ts

@@ -0,0 +1,46 @@
+import type { Driver } from '../abi/index';
+export interface ChatMessage {
+    readonly role: 'system' | 'user' | 'assistant' | 'tool';
+    readonly content: string;
+    readonly toolCalls?: readonly ToolCallReq[];
+    readonly toolCallId?: string;
+    readonly name?: string;
+    /** Multimodal side-channel (additive): image URLs (http or `data:` base64) attached to a user turn.
+     *  The kernel/context treat a message as its text `content`; only the LLM adapter reads `images` and
+     *  emits provider image parts (vision). Text-only backends ignore it. Rides verbatim on the stored
+     *  segment, so it survives paging and follow-up turns. */
+    readonly images?: readonly string[];
+}
+export interface ToolCallReq {
+    readonly id: string;
+    readonly name: string;
+    readonly args: unknown;
+}
+export interface ToolSchema {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters: Record<string, unknown>;
+}
+export interface LlmRequest {
+    readonly messages: readonly ChatMessage[];
+    readonly tools?: readonly ToolSchema[];
+    readonly maxTokens?: number;
+    /** Optional side-channel: a streaming backend calls this with each text delta as it arrives.
+     *  Purely observational (live UI) — the syscall still resolves once with the full reply, so
+     *  metering, journaling and replay are unchanged. Non-streaming backends ignore it. */
+    readonly onDelta?: (text: string) => void;
+    /** Optional abort signal: a backend passes it to its HTTP call so an in-flight request can be
+     *  cancelled (e.g. the user interrupts). Side-channel; non-HTTP backends ignore it. */
+    readonly signal?: AbortSignal;
+}
+export interface LlmReply {
+    readonly text?: string;
+    readonly toolCalls?: readonly ToolCallReq[];
+    readonly usage?: {
+        readonly promptTokens?: number;
+        readonly completionTokens?: number;
+        readonly usd?: number;
+    };
+}
+export type ChatFn = (req: LlmRequest) => Promise<LlmReply>;
+export declare function llmDriver(chat: ChatFn, name?: string): Driver;

package/dist/drivers/tools.d.ts

@@ -0,0 +1,7 @@
+import type { Driver } from '../abi/index';
+export type ToolFn = (input: unknown) => unknown | Promise<unknown>;
+export interface ToolCall {
+    readonly tool: string;
+    readonly input?: unknown;
+}
+export declare function toolDriver(tools: Record<string, ToolFn>, name?: string): Driver;

package/dist/drivers/wasm.d.ts

@@ -0,0 +1,2 @@
+import type { Driver } from '../abi/index';
+export declare function wasmDriver(modules: Record<string, Uint8Array>, name?: string): Driver;

package/dist/drivers/worker.d.ts

@@ -0,0 +1,3 @@
+import type { Driver } from '../abi/index';
+/** Each `read({task, input})` runs `tasks[task]` on its own OS thread; resolves to `{value, tid}`. */
+export declare function workerDriver(tasks: Record<string, string>, name?: string): Driver;

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+export { Kernel, KernelError } from './kernel/kernel';
+export type { KernelConfig, BootOptions, BootGrant, ProcessSnapshot } from './kernel/kernel';
+export { EventLog } from './kernel/log';
+export type { KEvent, StampedEvent } from './kernel/log';
+export { QuotaExceeded } from './kernel/account';
+export { CapError } from './kernel/captable';
+export { DefaultPager, estTokens, KeywordRecaller, Bm25Recaller, VectorRecaller, hashEmbed } from './kernel/memory';
+export type { Recaller, EmbedFn } from './kernel/memory';
+export { Journal } from './kernel/journal';
+export type { KernelMode } from './kernel/journal';
+export { MemoryStore, FileStore, journalFromStore, eventsFromStore } from './kernel/store';
+export type { Store, StoreRecord } from './kernel/store';
+export { seal, verify, freshNonce, NonceGuard } from './kernel/transport';
+export type { SealedEnvelope } from './kernel/transport';
+export { serveTcp, dialTcp } from './net/tcp';
+export { RealClock, VirtualClock } from './kernel/clock';
+export type { Clock, Timer } from './kernel/clock';
+export type { Pid, CapRef, MsgId, SegId, DriverName, Sys, ProcessImage, SpawnOptions, Quota, ExitReason, LogLevel, Down, Message, SendOptions, Resource, Right, Capability, BudgetGrant, Driver, DriverHandle, DriverResult, DriverCost, Segment, Pager, } from './abi/index';
+export { newCapRef, newMsgId, drv, hasRight, ABI_VERSION } from './abi/index';
+export { supervisor } from './userland/supervisor';
+export type { SupervisorSpec, ChildSpec, RestartStrategy, RestartKind } from './userland/supervisor';
+export { nursery } from './userland/nursery';
+export type { Scope } from './userland/nursery';
+export { nameService, register, lookup } from './userland/nameservice';
+export { reactAgent, conversationAgent } from './userland/agent';
+export type { AgentSpec, AgentResult, ReflectVerdict } from './userland/agent';
+export { sandbox, DEFAULT_ALLOW } from './userland/sandbox';
+export { LongMemory } from './userland/longmem';
+export type { Lesson, MemoryPersist } from './userland/longmem';
+export { llmDistiller, parseLessons, learn } from './userland/distill';
+export type { Distiller } from './userland/distill';
+export { PersonaRegistry, instantiate } from './userland/persona';
+export type { Persona, PersonaPersist } from './userland/persona';
+export { forgePrompt, refinePrompt, forgeFromMemory } from './userland/promptsmith';
+export type { ForgeBrief } from './userland/promptsmith';
+export { tournament, evolve, meteredFitness } from './userland/evolve';
+export type { Candidate, Scored, Scorer } from './userland/evolve';
+export { PromptExpert } from './userland/expert';
+export type { ExpertOptions } from './userland/expert';
+export { llmDriver, toolDriver, kvDriver, gatewayDriver, secureGatewayDriver, workerDriver, wasmDriver } from './drivers/index';
+export type { ChatFn, LlmRequest, LlmReply, ChatMessage, ToolCallReq, ToolSchema, ToolFn, ToolCall, } from './drivers/index';