@deepstrike/sdk 0.2.4 → 0.2.6

package/README.md

@@ -1,6 +1,8 @@
 # DeepStrike Node.js SDK
 
-Runtime framework built on a Rust kernel. The kernel handles loop control, context compression, skill routing, governance, signal prioritization — the SDK handles all I/O.
+Runtime framework built on a Rust kernel. The kernel owns loop control, context compression, governance, signal routing, and memory paging — the SDK owns all I/O (LLM calls, tool execution, disk, long-term memory).
+
+Node.js is the reference SDK for the **Agent OS native profile**: declarative governance and in-kernel signal routing are enabled by default on every run.
 
 ## Install
 
@@ -24,9 +26,9 @@ Pre-built native addons are available for the following platforms:
 | Linux ARM64 (musl / Alpine) | `@deepstrike/core-linux-arm64-musl` |
 | Windows x64 | `@deepstrike/core-win32-x64-msvc` |
 
-The correct platform package is selected and installed automatically via `optionalDependencies`. No postinstall download is required.
+The correct platform package is selected automatically via `optionalDependencies`.
 
-> **Note:** `@deepstrike/core` is the low-level native addon package and is not intended for direct use. It is an internal dependency automatically managed by `@deepstrike/sdk`. Direct installation is only relevant when building from Rust source.
+> **Note:** `@deepstrike/core` is the low-level N-API binding and is managed as an internal dependency of `@deepstrike/sdk`. When developing against a local kernel build, run `npm run test:local-core` from this directory to rebuild the native module from `../crates/deepstrike-node`.
 
 ---
 
@@ -65,14 +67,14 @@ const result = await collectText(runner.run({
 console.log(result)
 ```
 
-Same-session conversation continuity is explicit via `sessionId`:
+Same-session continuity is explicit via `sessionId`:
 
 ```typescript
 await collectText(runner.run({ sessionId: "chat-1", goal: "My name is Ada." }))
 const reply = await collectText(runner.run({ sessionId: "chat-1", goal: "What is my name?" }))
 ```
 
-Use `InMemorySessionLog` for process-local sessions or `FileSessionLog` when event replay should survive restarts. `wake(sessionId)` resumes from the event log without inserting a duplicate user start event.
+Use `InMemorySessionLog` for process-local sessions or `FileSessionLog` when replay should survive restarts. `wake(sessionId)` resumes from the event log without inserting a duplicate `run_started` event.
 
 Streaming:
 
@@ -87,6 +89,62 @@ for await (const event of runner.run({ sessionId: "readme-1", goal: "Summarize R
 
 ---
 
+## Architecture
+
+```text
+┌─────────────────────────────────────────────────────────┐
+│  RuntimeRunner (Layer 1.5)                              │
+│  LLMProvider · ExecutionPlane · SessionLog · DreamStore │
+└───────────────────────────┬─────────────────────────────┘
+                            │ step(JSON event) ↔ actions / observations
+┌───────────────────────────▼─────────────────────────────┐
+│  @deepstrike/core KernelRuntime                         │
+│  P1 Syscall · P2 Sched · P3 MM · Proc · IPC             │
+└─────────────────────────────────────────────────────────┘
+```
+
+The runner drives a single loop:
+
+1. Kernel returns an **action** — `call_provider`, `execute_tool`, `evaluate_milestone`, or `done`.
+2. SDK executes the action (stream LLM, run tools, call milestone verifier).
+3. SDK feeds the result back as a kernel **event** (`provider_result`, `tool_results`, …).
+4. Kernel **observations** (compression, page-out, spool, signals, …) are drained into `SessionLog`.
+
+Kernel session events carry an optional `category` tag (`syscall` · `sched` · `mm` · `proc` · `ipc`) for diagnostics and OS snapshot rebuilds.
+
+### What Agent OS gives you
+
+The mechanisms above are not internal refactors — they change what you can build without custom runner code:
+
+**Kernel-mediated runtime (M0–M4)**  
+Tool calls, spawns, compression, and signals pass through one kernel gate with an explicit lifecycle (Ready / Running / Blocked / Suspended). You implement I/O; the kernel decides *when* and *whether*. Node, Python, and Rust share the same decision path, so `wake(sessionId)` and cross-language tooling see consistent behavior.
+
+**Longer, sturdier sessions (Layer-1 spool + semantic page-out)**  
+Oversized tool results (> 50 KB) stay in context as a preview plus a `.spool/` reference — the model reads the full payload on demand via ordinary file tools. When pressure triggers semantic eviction, the SDK summarizes archived content into `DreamStore` and satisfies `page_in_requested` on the way back in. Long tasks survive token pressure instead of failing mid-run.
+
+**Safety and governance by default (OS native profile)**  
+Every run loads declarative `governancePolicy` (deny / ask_user / rate-limit / param rules) and in-kernel signal routing (`attentionPolicy`, default queue 64). Dangerous tools, external interrupts, and approval flows are policy — not ad-hoc `if` checks in your handlers.
+
+**Long-term memory as syscalls (Phase-7)**  
+`writeMemory` and `queryMemory` run outside the main tool loop: kernel validation before `DreamStore.commit`, search → `selectMemories` → `memory_retrieval_result` on query. Failed writes emit `memory_validation_failed` for audit; good memory is durable without polluting history.
+
+**Multi-agent and multi-signal orchestration**  
+Sub-agents register in the kernel process table (`agent_process_changed`); parent runs suspend explicitly until `sub_agent_completed`. Signals get disposition (Interrupt / Queue / Observe / Dropped) in-kernel, so gateways, cron, and heartbeats compose with the main loop instead of racing it.
+
+**Observable like an OS log**  
+Spool, page-out, signals, processes, budgets, and memory events land in `SessionLog` with categories. Rebuild an OS snapshot (`pageOutCount`, `spoolCount`, `processByAgent`, memory counters) from one event stream — replay still strips audit events when reconstructing LLM messages.
+
+| You need… | Use… |
+|---|---|
+| Policy before tools run | `governancePolicy` (default: allow-all native profile) |
+| External interrupts | `signalSource` + in-kernel `attentionPolicy` |
+| Huge tool output | Automatic Layer-1 spool; optional custom `resultSpool` |
+| Durable recall across runs | `DreamStore` + semantic `page_out` via `dreamSummarizer` |
+| Programmatic memory I/O | `runner.writeMemory()` / `runner.queryMemory()` |
+| Debug / compliance | `SessionLog` events + OS snapshot helpers |
+
+---
+
 ## Providers
 
 | Class | Backend | Notes |
@@ -103,7 +161,7 @@ for await (const event of runner.run({ sessionId: "readme-1", goal: "Summarize R
 
 All providers accept `RetryConfig` for exponential backoff and share a `CircuitBreaker`.
 
-`extensions` are forwarded by every provider in both `complete()` and `stream()` while SDK-owned structural fields such as `model`, `messages`, `tools`, and streaming flags remain protected. Provider-specific controls still keep their native spellings: for example Anthropic `thinking` / `betas`, OpenAI Responses `reasoning`, Gemini `generationConfig`, Ollama `think` / `options`, DeepSeek `thinking` + `reasoningEffort`, and Qwen `enableThinking` + `thinkingBudget`.
+`extensions` are forwarded by every provider in both `complete()` and `stream()` while SDK-owned structural fields such as `model`, `messages`, `tools`, and streaming flags remain protected.
 
 OpenAI can also be selected through the provider catalog:
 
@@ -138,39 +196,120 @@ const runner = new RuntimeRunner({
 ```
 
 - `memory(query)` / `knowledge(query)` meta-tool results → **history** (tool results)
-- External signals → **Slot 3** via `push_signal()`, cleared after each render
+- Inbound signals are routed by the in-kernel attention policy and rendered into **Slot 3**
 - Anthropic: Slots 1–2 get separate `cache_control` breakpoints
 
-Full reference: [docs/context-partition-compression.md](../docs/context-partition-compression.md)
+Full reference: [docs/concepts/context-slots-compression.md](../docs/concepts/context-slots-compression.md)
 
 ---
 
 ## Runtime options
 
 ```typescript
-const plane = new LocalExecutionPlane()
+import {
+  DEFAULT_NATIVE_GOVERNANCE_POLICY,
+  DEFAULT_NATIVE_ATTENTION_POLICY,
+} from "@deepstrike/sdk"
+
 const runner = new RuntimeRunner({
   provider,
   executionPlane: plane,
   sessionLog: new FileSessionLog(".deepstrike/sessions"),
-  maxTokens: 4096,            // context window size
-  maxTurns: 25,               // max turns (default 25)
-  timeoutMs: 60_000,          // timeout in ms
-  extensions: { temperature: 0.1 },  // provider-native controls, passed through to the LLM
-  skillDir: "./skills",       // skill .md files directory
-  knowledgeSource: myKS,      // KnowledgeSource implementation
-  signalSource: rx,           // SignalSource for external signals
-  dreamStore: myStore,        // DreamStore for long-term memory
-  agentId: "my-agent",        // required with dreamStore for memory meta-tool
-  initialMemory: ["..."],     // preloaded blocks → Slot 2 (systemKnowledge)
-  subAgentHarness: {          // optional: sub-agents run through HarnessLoop
-    evalProvider,
-    maxAttempts: 3,
+
+  // Scheduler budget
+  maxTokens: 128_000,
+  maxTurns: 25,
+  timeoutMs: 60_000,
+  schedulerBudget: { maxWallMs: 300_000 },
+
+  // Resource quotas (M2) — enforced at the kernel syscall trap. Opt-in; omit for unbounded.
+  resourceQuota: {
+    maxConcurrentSubagents: 4,                       // deny spawn while at cap
+    maxSpawnDepth: 2,                                // deny spawn past nesting depth
+    memoryWritesPerWindow: { maxWrites: 20, windowMs: 60_000 }, // rate-limit writeMemory
   },
-  governance: gov,            // Governance pipeline instance
+
+  // Long-term memory policy (set_memory_policy) — opt-in, kernel-enforced; omit for defaults.
+  memoryPolicy: {
+    memoryPath: "./.memory",     // where the SDK persists/scans memories (SDK-consumed)
+    staleWarningDays: 30,        // flag recalled memories older than this (SDK-consumed)
+    retrievalTopK: 5,            // kernel caps query_memory requested_k to this
+    validationEnabled: true,     // false → admit writes without validation
+    maxContentBytes: 10_000,     // override write_memory content-size limit
+    maxNameLength: 100,          // override write_memory name-length limit
+  },
+
+  // Agent OS native profile (defaults shown)
+  governancePolicy: DEFAULT_NATIVE_GOVERNANCE_POLICY,
+  attentionPolicy: DEFAULT_NATIVE_ATTENTION_POLICY, // SignalRouter queue size 64
+
+  // Host I/O
+  extensions: { temperature: 0.1 },
+  skillDir: "./skills",
+  knowledgeSource: myKS,
+  signalSource: gw,
+  dreamStore: myStore,
+  agentId: "my-agent",
+  initialMemory: ["..."],
+
+  // Memory paging & compression (SDK-side I/O)
+  compressionStore: archiveStore,       // persist compressed transcript slices
+  asyncSummarizer: mySummarizer,        // upgrade rule-based compression summaries
+  dreamProvider: dreamLlm,              // LLM for idle dream() synthesis
+  dreamSummarizer: myDreamSummarizer,   // LLM for semantic page_out → DreamStore
+
+  // Sub-agents
+  runSpec: { role: "orchestrator", isolation: "process" },
+  milestoneContract: myContract,
+  milestonePolicy: "require_verifier",
+  onMilestoneEvaluate: async ({ phaseId, criteria }) => ({ passed: true, phaseId }),
+  subAgentHarness: { evalProvider, maxAttempts: 3 },
+
+  // Governance UX (AskUser path)
+  onPermissionRequest: async (req) => ({ approved: true }),
+
+  // Diagnostics
+  enableDiagnosticsDashboard: true,     // CLI view grouped by Syscall / Sched / MM
 })
 ```
 
+| Option | Purpose |
+|--------|---------|
+| `governancePolicy` | Declarative deny / ask_user / rate-limit / param rules loaded into the kernel before `start_run` |
+| `attentionPolicy` | In-kernel signal router queue size (default 64) |
+| `resourceQuota` | M2 declarative limits — `maxConcurrentSubagents` / `maxSpawnDepth` / `memoryWritesPerWindow` — enforced at the kernel syscall trap (`set_resource_quota`); over-quota spawns roll back, over-rate writes surface as `memory_validation_failed` |
+| `memoryPolicy` | Long-term memory config sent as `set_memory_policy` and **kernel-enforced**: `validationEnabled: false` admits writes without validation, `maxContentBytes` / `maxNameLength` override validation limits, `retrievalTopK` caps `query_memory` breadth; `memoryPath` / `staleWarningDays` are SDK-consumed (requires `dreamStore` + `agentId` to enable memory) |
+| `onPermissionRequest` | Resolves `tool_gated` + `suspended` → kernel `resume` with approved/denied call IDs |
+| `compressionStore` | Writes archived messages on `compressed` observations |
+| `asyncSummarizer` | Background LLM summary after compression; stored as `summary_upgraded` |
+| `dreamSummarizer` | Summarizes `page_out { tier_hint: "semantic" }` into `DreamStore` during a run |
+| `dreamProvider` | Separate LLM for `dream()` idle consolidation (falls back to `provider`) |
+
+Rebuild an OS diagnostics snapshot from session events:
+
+```typescript
+import { rebuildOsSnapshotFromSessionEvents } from "@deepstrike/sdk"
+
+const events = (await sessionLog.read(sessionId)).map(e => e.event)
+const snap = rebuildOsSnapshotFromSessionEvents(events)
+// snap.pageOutCount, snap.spoolCount, snap.signals, snap.processByAgent, …
+```
+
+---
+
+## Large result spool (Layer 1)
+
+When a single tool result exceeds **50 KB**, the kernel keeps a short preview in context and emits `large_result_spooled`. The SDK writes the full payload to `.spool/` under the process cwd (SHA-256 keyed files) and logs `spool_ref` in the session.
+
+The model can retrieve full content via ordinary read tools — `LocalExecutionPlane` transparently resolves paths under `.spool/`:
+
+```typescript
+// Kernel context shows a preview + spool reference.
+// LLM calls read_file({ path: ".spool/abc123…" }) → full content returned.
+```
+
+No configuration is required; customize the directory by passing a `resultSpool` instance when constructing `RuntimeRunner` (see tests under `tests/runtime/large-result-spool.test.ts`).
+
 ---
 
 ## Tools
@@ -179,10 +318,28 @@ const runner = new RuntimeRunner({
 import { tool, readFile } from "@deepstrike/sdk"
 
 plane.register(tool("search", "Search.", schema, async (args) => ...))
-plane.register(readFile)     // built-in: read files from disk
+plane.register(readFile)     // built-in: read files from disk (also resolves .spool/ refs)
 plane.unregister("search")
 ```
 
+Execution planes:
+
+| Plane | Use case |
+|-------|----------|
+| `LocalExecutionPlane` | In-process tools (default) |
+| `FilteredExecutionPlane` | Capability-filtered sub-agent tools |
+| `ProcessSandboxPlane` | OS subprocess isolation |
+| `McpProxyPlane` | MCP server tools |
+| `RemoteVpcPlane` | Remote execution |
+
+Mount capabilities on an active run:
+
+```typescript
+runner.mountTool(schema)
+runner.mountSkill("summarize", "Summarize text")
+runner.unmountCapability("tool", "search")
+```
+
 ---
 
 ## Skills
@@ -214,9 +371,11 @@ effort: 1
 
 ## Knowledge
 
-Implement `KnowledgeSource` to connect any RAG system. The kernel injects a `knowledge` meta-tool that the LLM calls on demand. **Runtime retrieval results land in history** as tool results.
+Implement `KnowledgeSource` to connect any RAG system. The kernel injects a `knowledge` meta-tool that the LLM calls on demand. Runtime retrieval results land in **history** as tool results.
 
-To inject durable knowledge at startup (Slot 2, cacheable on Anthropic), use `initialMemory` or kernel `add_knowledge_message`.
+To inject durable knowledge at startup (Slot 2, cacheable on Anthropic), use `initialMemory` or `runner.pushKnowledge()`.
+
+Before tool execution the kernel may emit `page_in_requested`; the SDK satisfies it from `DreamStore`, `KnowledgeSource`, and a local semantic page-out cache, then feeds `page_in` back to the kernel.
 
 ```typescript
 const runner = new RuntimeRunner({
@@ -238,7 +397,7 @@ const runner = new RuntimeRunner({
 
 ### WorkingMemory (SDK-side scratch pad)
 
-`WorkingMemory` is an SDK helper — not the kernel `working` partition (removed). Kernel task state lives in `task_state` and renders into Slot 3 (`turns[0]`).
+`WorkingMemory` is an SDK helper — not the kernel working partition. Kernel task state lives in `task_state` and renders into Slot 3 (`turns[0]`).
 
 ```typescript
 import { WorkingMemory } from "@deepstrike/sdk"
@@ -248,7 +407,7 @@ mem.get("step")  // 1
 mem.clear()
 ```
 
-### DreamStore (long-term memory + dreaming pipeline)
+### DreamStore (long-term memory)
 
 ```typescript
 import type { DreamStore } from "@deepstrike/sdk"
@@ -266,32 +425,91 @@ const runner = new RuntimeRunner({
   sessionLog: new FileSessionLog(".deepstrike/sessions"),
   maxTokens: 4096,
   dreamStore: new MyStore(),
-  agentId: "my-agent",  // enables `memory` meta-tool
+  agentId: "my-agent",  // enables `memory` meta-tool + semantic page-out archival
 })
+```
+
+Three memory paths:
 
-// In-session: LLM calls memory(query) → DreamStore.search() → history tool result
-// Preload:    initialMemory → Slot 2 (systemKnowledge)
-// Post-session: trigger memory consolidation
+| Path | When | What happens |
+|------|------|--------------|
+| In-session `memory(query)` | LLM calls meta-tool | `DreamStore.search()` → history tool result |
+| `initialMemory` | Run start | Injected into Slot 2 (`systemKnowledge`) |
+| Semantic `page_out` | Kernel evicts with `tier_hint: "semantic"` | SDK summarizes via `dreamSummarizer` / `dreamProvider` → `DreamStore.commit()` |
+| `dream(agentId)` | Explicit idle call | `IdlePipeline` batch-consolidates past sessions |
+
+```typescript
+// Post-session batch consolidation
 const result = await runner.dream("my-agent", Date.now())
 ```
 
+### Phase-7 memory syscalls (`writeMemory` / `queryMemory`)
+
+Kernel-validated long-term memory I/O outside the main tool loop:
+
+```typescript
+await runner.writeMemory({
+  metadata: {
+    name: "prefers-small-tests",
+    description: "User prefers focused unit tests",
+    kind: "feedback",
+    created_at: Date.now(),
+    updated_at: Date.now(),
+  },
+  content: "User prefers focused unit tests for SDK behavior.",
+}, { sessionId: "my-session" })
+
+const hits = await runner.queryMemory({
+  current_context: "Need testing preferences",
+  active_tools: [],
+  already_surfaced: [],
+  top_k: 5,
+}, { sessionId: "my-session" })
+```
+
+Session events: `memory_written`, `memory_queried`, `memory_validation_failed`, `memory_retrieval_result`.
+
 ---
 
 ## Governance
 
-### SDK PermissionManager
+### In-kernel declarative policy (preferred)
+
+Every run loads `governancePolicy` into the kernel via `load_governance_policy`. The kernel enforces rules **before** tools execute:
 
 ```typescript
-import { PermissionManager, PermissionMode } from "@deepstrike/sdk"
+import type { GovernancePolicy } from "@deepstrike/sdk"
+
+const policy: GovernancePolicy = {
+  rules: [
+    { pattern: "read_file", action: "allow" },
+    { pattern: "write_file", action: "ask_user" },
+    { pattern: "run_command", action: "ask_user" },
+    { pattern: "*", action: "deny" },
+  ],
+  rateLimits: [{ tool: "api_call", maxCalls: 10, windowMs: 60_000 }],
+}
 
-const pm = new PermissionManager(PermissionMode.DEFAULT)
-pm.grant("fs", "read")
-pm.grantWithApproval("db", "write", "Needs DBA approval")
-pm.revoke("db", "drop")
-pm.evaluate("fs", "read")  // { allowed: true, ... }
+const runner = new RuntimeRunner({
+  provider,
+  executionPlane: plane,
+  sessionLog,
+  governancePolicy: policy,
+  onPermissionRequest: async (req) => {
+    console.log(`Approve ${req.toolName}?`, req.arguments)
+    return { approved: true }
+  },
+})
 ```
 
-### Kernel Governance (full pipeline)
+- `deny` → tool rejected with `tool_denied`
+- `ask_user` → `tool_gated` + `suspended`; resolve via `onPermissionRequest`, then kernel `resume`
+
+Default when omitted: allow-all (`DEFAULT_NATIVE_GOVERNANCE_POLICY`).
+
+### Standalone Governance class
+
+`Governance` wraps the native governance evaluator for SDK-side use (tests, custom gates). It is **not** wired automatically into `RuntimeRunner` — use `governancePolicy` for run-time enforcement.
 
 ```typescript
 import { Governance } from "@deepstrike/sdk"
@@ -299,45 +517,65 @@ import { Governance } from "@deepstrike/sdk"
 const gov = new Governance("allow")
 gov.addPermissionRule("danger.*", "deny")
 gov.blockTool("rm_rf")
-gov.setRateLimit("api_call", 10, 60_000)
-gov.requireParam("write_file", "path")
-gov.allowParamValues("set_mode", "mode", ["read", "write"])
-gov.limitParamRange("sleep", "seconds", 0, 10)
-
-const runner = new RuntimeRunner({
-  provider,
-  executionPlane: plane,
-  sessionLog: new FileSessionLog(".deepstrike/sessions"),
-  maxTokens: 4096,
-  governance: gov,
-})
-// Every tool call goes through: Permission → Veto → RateLimit → Constraint → Audit
+gov.evaluate("read_file", '{"path":"x"}')
 ```
 
+### SDK PermissionManager
+
+`PermissionManager` is a separate SDK-side permission layer for apps that manage their own approval UX outside the kernel loop.
+
 ---
 
 ## Signals
 
+Inbound signals are routed by the in-kernel attention policy (default queue size 64):
+
+| Urgency | Typical disposition |
+|---------|-------------------|
+| `critical` / `high` | `interrupt_now` — may yield a new `call_provider` action |
+| `normal` / `low` | `queue` — buffered; no action until dequeued |
+| queue full | `dropped` |
+
 ```typescript
 import { SignalGateway, ScheduledPrompt } from "@deepstrike/sdk"
 
 const gw = new SignalGateway()
 gw.schedule(new ScheduledPrompt("standup", Date.now() + 3600_000))
-gw.ingest({ kind: "interrupt", urgency: "critical", payload: {} })
+gw.ingest({ kind: "alert", urgency: "normal", payload: { goal: "Check deploy" } })
 
 const runner = new RuntimeRunner({
   provider,
   executionPlane: plane,
-  sessionLog: new FileSessionLog(".deepstrike/sessions"),
-  maxTokens: 4096,
+  sessionLog,
   signalSource: gw,
+  attentionPolicy: { maxQueueSize: 64 },
 })
-// kind="interrupt" → immediately stops the running runner
 
-runner.interrupt() // also works directly
+runner.interrupt() // cooperative abort → kernel timeout path
 gw.destroy()
 ```
 
+Each routed signal produces a `signal_disposed` session event (`category: "ipc"`).
+
+---
+
+## Sub-agents
+
+Spawn isolated child agents through the kernel process table:
+
+```typescript
+for await (const evt of runner.spawnSubAgent({
+  role: "researcher",
+  isolation: "process",
+  goal: "Find three sources on topic X",
+  criteria: ["At least 3 URLs"],
+})) {
+  if (evt.type === "done") console.log(evt.status)
+}
+```
+
+Requires an active parent run (`run()` / `wake()` in progress). The kernel emits `agent_process_changed`; the default `SubAgentOrchestrator` runs the child with a filtered execution plane and feeds `sub_agent_completed` back.
+
 ---
 
 ## Harness (evaluation framework)
@@ -345,30 +583,20 @@ gw.destroy()
 ```typescript
 import { SinglePassHarness, EvalLoopHarness, HarnessLoop } from "@deepstrike/sdk"
 
-// 1. SinglePass — run once, always passes
 const outcome = await new SinglePassHarness(runner).run({ goal: "Say hello" })
 
-// 2. EvalLoop — retry until QualityGate passes
 const harness = new EvalLoopHarness(runner, {
   async evaluate(_req, out) { return out.result.includes("hello") },
 }, 3)
 
-// 3. HarnessLoop — LLM-as-judge with feedback injection + skill extraction
 const loop = new HarnessLoop(runner, evalProvider, { maxAttempts: 3, skillDir: "./skills" })
 
-// Sub-agents: pass subAgentHarness on RuntimeRunner to auto-evaluate spawned children
 const runnerWithHarness = new RuntimeRunner({
   provider,
   executionPlane: plane,
   sessionLog,
   subAgentHarness: { evalProvider, maxAttempts: 3 },
 })
-for await (const event of loop.runStreaming({
-  goal: "Write a haiku",
-  criteria: [{ text: "Must be 3 lines", required: true }],
-})) {
-  if (event.type === "done") console.log(event.verdict.passed, event.verdict.feedback)
-}
 ```
 
 ---
@@ -387,4 +615,12 @@ for await (const event of loop.runStreaming({
 | `done` | `iterations`, `totalTokens`, `status` |
 | `error` | `message` |
 
-`status`: `completed` · `max_turns` · `token_budget` · `timeout` · `user_abort` · `error`
+`status`: `completed` · `max_turns` · `token_budget` · `timeout` · `user_abort` · `error` · `milestone_pending`
+
+---
+
+## Further reading
+
+- [SDK OS parity matrix](../docs/sdk-os-parity.md)
+- [Kernel ABI reference](../docs/reference/kernel-abi.md)
+- [Context slots & compression](../docs/concepts/context-slots-compression.md)

package/dist/collaboration/modes/creator-verifier.d.ts

@@ -35,8 +35,6 @@ export declare class CreatorVerifierMode {
         maxAttempts?: number;
         /** Stable orchestration session for kernel lineage audit. */
         coordinatorSessionId?: string;
-        /** Opt out of kernel spawn path and use legacy independent runner sessions. */
-        useLegacyRunners?: boolean;
     });
     run(contract: VerificationContract): Promise<ContractOutcome>;
     /** Aggregate drift metrics across all runs through this mode instance. */
@@ -64,7 +62,6 @@ export declare class OrchestrationMode {
     constructor(pool: AgentPool, options?: {
         maxAttempts?: number;
         coordinatorSessionId?: string;
-        useLegacyRunners?: boolean;
     });
     run(goal: string): Promise<ContractOutcome & {
         contract: VerificationContract;

package/dist/collaboration/modes/creator-verifier.js

@@ -30,9 +30,7 @@ export class CreatorVerifierMode {
     }
     async run(contract) {
         this._total++;
-        if (!this.options.useLegacyRunners) {
-            this.pool.ensureCoordinator(this.options.coordinatorSessionId);
-        }
+        this.pool.ensureCoordinator(this.options.coordinatorSessionId);
         const harness = new ContractDrivenHarness(this.pool, contract, {
             maxAttempts: this.options.maxAttempts ?? 3,
         });
@@ -81,9 +79,7 @@ export class OrchestrationMode {
         this.inner = new CreatorVerifierMode(pool, options);
     }
     async run(goal) {
-        if (!this.options.useLegacyRunners) {
-            this.pool.ensureCoordinator(this.options.coordinatorSessionId);
-        }
+        this.pool.ensureCoordinator(this.options.coordinatorSessionId);
         // Step 1: orchestrator produces a VerificationContract
         const contractJson = await this.pool.orchestrate(goal);
         const contract = this._parseContract(contractJson, goal);

package/dist/governance.d.ts

@@ -15,3 +15,39 @@ export declare class Governance {
     evaluate(toolName: string, argsJson: string): GovernanceVerdict;
 }
 export type { GovernanceVerdict };
+type GovernancePolicyAction = "allow" | "deny" | "ask_user";
+export interface GovernancePolicy {
+    defaultAction?: GovernancePolicyAction;
+    rules?: {
+        pattern: string;
+        action: GovernancePolicyAction;
+    }[];
+    vetoes?: string[];
+    rateLimits?: {
+        tool: string;
+        maxCalls: number;
+        windowMs: number;
+    }[];
+    constraints?: GovernanceConstraint[];
+}
+export type GovernanceConstraint = {
+    kind: "required";
+    tool: string;
+    path: string;
+} | {
+    kind: "enum";
+    tool: string;
+    path: string;
+    values: string[];
+} | {
+    kind: "range";
+    tool: string;
+    path: string;
+    min?: number;
+    max?: number;
+};
+/**
+ * Convert a declarative {@link GovernancePolicy} into the `load_governance_policy`
+ * kernel event payload (snake_case wire fields). Pure — no side effects.
+ */
+export declare function governancePolicyToKernelEvent(policy: GovernancePolicy): Record<string, unknown>;

package/dist/governance.js

@@ -32,3 +32,25 @@ export class Governance {
         return this.inner.evaluate(toolName, argsJson);
     }
 }
+/**
+ * Convert a declarative {@link GovernancePolicy} into the `load_governance_policy`
+ * kernel event payload (snake_case wire fields). Pure — no side effects.
+ */
+export function governancePolicyToKernelEvent(policy) {
+    return {
+        kind: "load_governance_policy",
+        ...(policy.defaultAction ? { default_action: policy.defaultAction } : {}),
+        rules: (policy.rules ?? []).map(r => ({ tool_pattern: r.pattern, action: r.action })),
+        vetoed_tools: policy.vetoes ?? [],
+        rate_limits: (policy.rateLimits ?? []).map(rl => ({
+            tool: rl.tool,
+            max_calls: rl.maxCalls,
+            window_ms: rl.windowMs,
+        })),
+        constraints: (policy.constraints ?? []).map(c => c.kind === "enum"
+            ? { kind: "enum", tool: c.tool, path: c.path, values: c.values }
+            : c.kind === "range"
+                ? { kind: "range", tool: c.tool, path: c.path, ...(c.min !== undefined ? { min: c.min } : {}), ...(c.max !== undefined ? { max: c.max } : {}) }
+                : { kind: "required", tool: c.tool, path: c.path }),
+    };
+}