@deepstrike/sdk 0.2.52 → 0.2.61

package/README.md

@@ -6,9 +6,7 @@
 
 # DeepStrike Node.js SDK
 
-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.
+Build Node.js Agents with providers, typed tools, memory, Skills, delegation, workflows, and durable sessions. The SDK keeps the Agent's long-running work explicit through stream events, SessionLog evidence, tool policies, and host-provided integrations.
 
 ## Install
 
@@ -82,7 +80,7 @@ const reply = await collectText(runner.run({ sessionId: "chat-1", goal: "What is
 
 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.
 
-### Package layout (v0.2.50)
+### Package layout
 
 The root export is the **intent layer** — what you reach for to run an agent, run a workflow, author a tool, or pick a provider (~30 symbols). Advanced machinery lives behind subpaths, so the common surface stays small and tree-shakeable:
 
@@ -92,7 +90,7 @@ The root export is the **intent layer** — what you reach for to run an agent,
 | `@deepstrike/sdk/providers` | backend factories (`deepseek`, `kimi`, `qwen`, `glm`, `minimax`, `gemini`, `ollama`), profiles, `CircuitBreaker` |
 | `@deepstrike/sdk/workflow` | `SubAgentOrchestrator`, `spawnStandalone`, reducers, contracts, handoff/modes, agent + spec types |
 | `@deepstrike/sdk/planes` | `WorktreeExecutionPlane`, `ProcessSandboxPlane`, `McpProxyPlane`, `RemoteVpcPlane`, archive/credential stores |
-| `@deepstrike/sdk/memory` | `DreamStore`, `WorkingMemory`, `InMemoryDreamStore`, `rankMemories`, `extractSessionMemories`, `KnowledgeSource` |
+| `@deepstrike/sdk/memory` | `MemoryStore`, `WorkingMemory`, `InMemoryMemoryStore`, `rankMemories`, `extractSessionMemories`, `KnowledgeSource` |
 | `@deepstrike/sdk/harness` | `AttemptLoop`, body/judge/carry policies, `judge` |
 | `@deepstrike/sdk/os` | profiles, `KernelPrimitivesDashboard`, `primitiveForKind` / `KernelPrimitive`, signals, `PermissionManager`, replay-testing utilities |
 
@@ -161,7 +159,7 @@ for await (const event of runner.run({ sessionId: "readme-1", goal: "Summarize R
 ```text
 ┌─────────────────────────────────────────────────────────┐
 │  RuntimeRunner (Layer 1.5)                              │
-│  LLMProvider · ExecutionPlane · SessionLog · DreamStore │
+│  LLMProvider · ExecutionPlane · SessionLog · MemoryStore │
 └───────────────────────────┬─────────────────────────────┘
                             │ durable prepare / append / commit
 ┌───────────────────────────▼─────────────────────────────┐
@@ -179,7 +177,7 @@ The runner drives one durable operation loop:
 
 Kernel session events carry an optional `category` tag (`syscall` · `sched` · `mm` · `proc` · `ipc`) for diagnostics and OS snapshot rebuilds.
 
-### What Agent OS gives you
+### What this enables
 
 The mechanisms above are not internal refactors — they change what you can build without custom runner code:
 
@@ -187,13 +185,13 @@ The mechanisms above are not internal refactors — they change what you can bui
 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 (external payloads + semantic page-out)**
-The host atomically persists oversized tool results before submitting an `External` result. Core journals only the opaque locator, digest, size, and preview; `read_result` becomes a correlated `LoadPayload` effect. When pressure triggers semantic eviction, the SDK summarizes archived content into `DreamStore`.
+The host atomically persists oversized tool results before submitting an `External` result. Core journals only the opaque locator, digest, size, and preview; `read_result` becomes a correlated `LoadPayload` effect. When pressure triggers semantic eviction, the SDK summarizes archived content into `MemoryStore`.
 
 **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 (`signalPolicy`, 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 happens before `DreamStore.upsert`, while queries call `DreamStore.search` and journal `memory_retrieval_result`. Failed writes emit `memory_validation_failed` for audit; good memory is durable without polluting history.
+`writeMemory` and `queryMemory` run outside the main tool loop: kernel validation happens before `MemoryStore.put`, while queries call `MemoryStore.search` and journal `memory_retrieval_result`. 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.
@@ -206,7 +204,7 @@ Page-out, signals, processes, budgets, and memory events land in `SessionLog` wi
 | Policy before tools run | `governancePolicy` (default: allow-all native profile) |
 | External interrupts | `signalSource` + in-kernel `signalPolicy` |
 | Huge tool output | Canonical external payload; optional custom `payloadStore` |
-| Durable recall across runs | `DreamStore` + semantic `page_out` via `dreamSummarizer` |
+| Durable recall across runs | `MemoryStore` + semantic `page_out` via `memorySummarizer` |
 | Programmatic memory I/O | `runner.writeMemory()` / `runner.queryMemory()` |
 | Debug / compliance | `SessionLog` events + OS snapshot helpers |
 
@@ -214,7 +212,7 @@ Page-out, signals, processes, budgets, and memory events land in `SessionLog` wi
 
 ## Dynamic workflows
 
-Instead of planning **and** executing a hard task in one long context window, hand the kernel a declarative DAG and let it spawn a fresh-context sub-agent per node. The kernel owns the control flow (gate · budget · suspend-on-join · resume); your SDK runs the agents. See the [top-level overview](../README.md#the-six-harness-patterns-as-first-class-kernel-nodes) for the full pattern catalog.
+For a task that needs more than one Agent, describe a DAG and let the runtime run fresh-context specialists under the same budgets, policies, and session evidence as the parent. See the [workflow guide](../docs/en/guides/workflow.md) for the complete pattern catalog.
 
 ```ts
 // One fresh-context verifier per rule (no inherited author context → can't rubber-stamp),
@@ -253,7 +251,7 @@ Dependencies use `dependsOn: number[]`, where each number is a node index, and `
 how upstream terminal states gate the node (`all_success` by default, plus `accept_partial`,
 `all_terminal`, and `optional`).
 
-### Workflow capabilities (v0.2.50)
+### Workflow capabilities
 
 - **Runtime fan-out** — register `submitWorkflowNodesTool` on the parent execution plane and a trusted node can append nodes to the live DAG mid-run (true loop-until-done; one verifier per discovered claim). The tool schema is exported from `@deepstrike/sdk/workflow`, not the package root. Submission events remain audit projections; checkpoint state owns recovery. Governance rejection fails the submitting node instead of acknowledging work that was never appended.
 - **Quarantine, no escape** — set `trust: "quarantined"` on a node that reads untrusted content; it's denied write-capable isolation in-kernel, and any nodes it submits are coerced to quarantined too (no privilege escalation).
@@ -403,7 +401,7 @@ const runner = new RuntimeRunner({
     maxNameLength: 100,          // override write_memory name-length limit
   },
 
-  // Agent OS native profile (defaults shown)
+  // Default governance and signal policy
   governancePolicy: DEFAULT_NATIVE_GOVERNANCE_POLICY,
   signalPolicy: DEFAULT_NATIVE_SIGNAL_POLICY, // SignalRouter queue size 64
   promptBudget: {
@@ -417,15 +415,15 @@ const runner = new RuntimeRunner({
   skillDir: "./skills",
   knowledgeSource: myKS,
   signalSource: gw,
-  dreamStore: myStore,
+  memoryStore: 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
+  memoryProvider: memoryLlm,             // LLM for durable-memory extraction
+  memorySummarizer: myMemorySummarizer,   // LLM for semantic page_out → MemoryStore
 
   // Sub-agents
   runSpec: { role: "orchestrator", isolation: "process" },
@@ -445,16 +443,16 @@ const runner = new RuntimeRunner({
 | Option | Purpose |
 |--------|---------|
 | `governancePolicy` | Declarative deny / ask_user / rate-limit / param rules installed before canonical root start |
-| `signalPolicy` | Versioned in-kernel signal queue/TTL policy (default queue 64) |
+| `signalPolicy` | In-kernel signal queue/TTL policy (default queue 64) |
 | `promptBudget` | Provider-envelope overhead, output reserve, and safety margin deducted from the context window |
 | `resourceQuota` | M2 declarative limits — `maxConcurrentSubagents` / `maxTotalSubagents` / `maxSpawnDepth` / `maxWorkflowNodes` / `memoryWritesPerWindow` — enforced at the kernel syscall trap (`set_resource_quota`); over-quota spawns roll back, over-rate writes surface as `memory_validation_failed` |
-| `memoryPolicy` | Canonical long-term memory policy: `validationEnabled: false` admits writes without validation, `maxContentBytes` / `maxNameLength` override validation limits, `retrievalTopK` caps `query_memory` breadth, and `staleWarningDays` controls stale recall policy. Storage belongs to the configured `dreamStore`. |
+| `memoryPolicy` | Canonical long-term memory policy: `validationEnabled: false` admits writes without validation, `maxContentBytes` / `maxNameLength` override validation limits, `retrievalTopK` caps `query_memory` breadth, and `staleWarningDays` controls stale recall policy. Storage belongs to the configured `memoryStore`. |
 | `onPermissionRequest` | Resolves `tool_gated` + `suspended` → kernel `resume` with approved/denied call IDs |
 | `compressionStore` | Writes archived messages on `compressed` observations |
 | `payloadStore` | Resolves canonical opaque payload locators (default: `.payloads/`) |
 | `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`) |
+| `memorySummarizer` | Summarizes `page_out { tier_hint: "semantic" }` into `MemoryStore` during a run |
+| `memoryProvider` | Separate LLM for durable-memory extraction (falls back to `provider`) |
 
 Rebuild an OS diagnostics snapshot from session events:
 
@@ -574,13 +572,15 @@ mem.get("step")  // 1
 mem.clear()
 ```
 
-### DreamStore (long-term memory)
+### MemoryStore (long-term memory)
 
 ```typescript
-import type { DreamStore } from "@deepstrike/sdk/memory"
+import type { MemoryStore } from "@deepstrike/sdk/memory"
 
-class MyStore implements DreamStore {
-  async upsert(agentId, record) { ... }      // the only durable memory mutation
+class MyStore implements MemoryStore {
+  async put(agentId, record) { ... }         // the durable write path
+  async get(agentId, recordId) { ... }       // Promise<MemoryRecord | null>
+  async delete(agentId, recordId) { ... }    // idempotent deletion
   async search(agentId, query) { ... }       // Promise<MemoryRecall[]>
   async saveSession(session) { ... }         // completed transcript for extraction
 }
@@ -591,7 +591,7 @@ const runner = new RuntimeRunner({
   executionPlane: plane,
   sessionLog: new FileSessionLog(".deepstrike/sessions"),
   maxTokens: 4096,
-  dreamStore: new MyStore(),
+  memoryStore: new MyStore(),
   agentId: "my-agent",
   memoryScope,          // scopes run-start recall, queries, extraction, and semantic page-out
 })
@@ -601,10 +601,10 @@ Four memory paths:
 
 | Path | When | What happens |
 |------|------|--------------|
-| In-session `memory(query)` | LLM calls meta-tool | `DreamStore.search()` → history tool result |
+| In-session `memory(query)` | LLM calls meta-tool | `MemoryStore.search()` → history tool result |
 | `initialMemory` | Run start | Injected into Slot 2 (`systemKnowledge`) |
-| `writeMemory(record)` | Host writes a durable record | Kernel validation / quota / dedup → `DreamStore.upsert()` |
-| Semantic `page_out` | Kernel evicts with `tier_hint: "semantic"` | SDK summarizes via `dreamSummarizer` / `dreamProvider` → gated `writeMemory()` |
+| `writeMemory(record)` | Host writes a durable record | Kernel validation / quota / dedup → `MemoryStore.put()` |
+| Semantic `page_out` | Kernel evicts with `tier_hint: "semantic"` | SDK summarizes via `memorySummarizer` / `memoryProvider` → gated `writeMemory()` |
 
 ### Phase-7 memory syscalls (`writeMemory` / `queryMemory`)
 

package/dist/agent-ir.d.ts

@@ -0,0 +1,103 @@
+import { Agent, type AgentOptions, type ModelRef } from "./agent.js";
+import type { Guardrail } from "./guardrail.js";
+import type { Handoff } from "./handoff-target.js";
+import type { Knowledge } from "./knowledge/public.js";
+import type { MCPServer } from "./mcp-server.js";
+import type { JsonSchema } from "./runtime/output-schema.js";
+import type { Skill } from "./skill.js";
+import type { RegisteredTool } from "./tools/index.js";
+import type { AgentCapabilityFilter } from "./types/agent.js";
+export interface AgentToolDefinition {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
+}
+/** A JSON-friendly Agent definition accepted by `normalizeAgent`.  It is deliberately declarative:
+ * executable tools still enter the SDK through `AgentOptions.tools`. */
+export interface AgentDefinition extends Omit<AgentOptions, "tools"> {
+    tools?: Array<RegisteredTool | AgentToolDefinition>;
+}
+export interface AgentToolIR {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
+}
+export interface AgentMemoryIR {
+    kind: "durable" | "working";
+    namespace?: string;
+}
+export type AgentCapabilityIR = {
+    kind: "tool";
+    id: string;
+    description: string;
+} | {
+    kind: "mcp_server";
+    id: string;
+    description: string;
+} | {
+    kind: "skill";
+    id: string;
+    description: string;
+};
+/** The host-facing lowering destinations. These are declarations, not grants: a runner still
+ * attenuates them through its existing `AgentRunSpec.capabilityFilter` and mounted manifest. */
+export interface AgentLoweringInputs {
+    run: {
+        name: string;
+        model?: ModelRef;
+    };
+    context: {
+        description?: string;
+        instructions?: string;
+        outputSchema?: JsonSchema;
+        knowledge: Knowledge[];
+    };
+    capabilities: {
+        tools: AgentToolIR[];
+        mcpServers: MCPServer[];
+        skills: Skill[];
+        effective: AgentCapabilityIR[];
+    };
+    memory?: AgentMemoryIR;
+    delegation: {
+        handoffs: Handoff[];
+    };
+    governance: {
+        guardrails: Guardrail[];
+    };
+}
+/** spc_015-09: the canonical, provider-neutral Agent IR between public SDK surfaces and host
+ * runtime inputs. It contains neither an execution plan nor a Kernel wire DTO. */
+export interface AgentSpec {
+    name: string;
+    description?: string;
+    instructions?: string;
+    model?: ModelRef;
+    tools: AgentToolIR[];
+    outputSchema?: JsonSchema;
+    mcpServers?: MCPServer[];
+    skills?: Skill[];
+    memory?: AgentMemoryIR;
+    knowledge?: Knowledge[];
+    handoffs?: Handoff[];
+    guardrails?: Guardrail[];
+    metadata?: Record<string, unknown>;
+    /** Declared capabilities. This descriptive view grants nothing by itself. */
+    capabilities: AgentCapabilityIR[];
+    /** Host ceiling copied from the public Agent, when supplied. Empty axes remain non-narrowing. */
+    capabilityFilter?: AgentCapabilityFilter;
+    /** The declarations that survive the supplied local ceiling. Host mounts may narrow further. */
+    effectiveCapabilities: AgentCapabilityIR[];
+    /** Namespace-isolated provider extensions. Unknown namespaces are preserved verbatim. */
+    extensions: Record<string, unknown>;
+    inputs: AgentLoweringInputs;
+}
+/** Normalizes native Agents and JSON-safe descriptor objects into the one public surface used by
+ * lowering. It does not interpret provider namespaces or create executable capabilities. */
+export declare function normalizeAgent(agent: Agent | AgentDefinition): Agent;
+/** Pure: no provider branching, no scheduling, authorization, persistence, or Kernel wire calls.
+ * Providers consume only their own namespace from `extensions`; the host decides whether declared
+ * capabilities survive its existing attenuation filter. */
+export declare function lowerAgent(agent: Agent): AgentSpec;

package/dist/agent-ir.js

@@ -0,0 +1,134 @@
+import { Agent } from "./agent.js";
+import { WorkingMemory } from "./memory/public.js";
+function clone(value) {
+    if (value === undefined || value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(clone);
+    const copy = {};
+    for (const [key, nested] of Object.entries(value))
+        copy[key] = clone(nested);
+    return copy;
+}
+function toolDefinitionToRegisteredTool(tool) {
+    const parameters = clone(tool.parameters ?? { type: "object", properties: {} });
+    if (parameters.type !== "object") {
+        throw new Error(`tool "${tool.name}": parameters must be a JSON Schema with root type "object"`);
+    }
+    return {
+        schema: {
+            name: tool.name,
+            description: tool.description ?? "",
+            parameters: JSON.stringify(parameters),
+        },
+        providerOptions: clone(tool.providerOptions),
+        async execute() {
+            throw new Error(`tool "${tool.name}" has no execution binding — declarative Agent definitions only carry shape`);
+        },
+    };
+}
+function isRegisteredTool(tool) {
+    return "schema" in tool && "execute" in tool;
+}
+/** Normalizes native Agents and JSON-safe descriptor objects into the one public surface used by
+ * lowering. It does not interpret provider namespaces or create executable capabilities. */
+export function normalizeAgent(agent) {
+    if (agent instanceof Agent)
+        return agent;
+    const tools = agent.tools?.map(tool => isRegisteredTool(tool) ? tool : toolDefinitionToRegisteredTool(tool));
+    const { tools: _rawTools, ...options } = agent;
+    return new Agent({ ...options, ...(tools ? { tools } : {}) });
+}
+function lowerTool(tool) {
+    let parameters;
+    try {
+        parameters = JSON.parse(tool.schema.parameters);
+    }
+    catch {
+        throw new Error(`tool "${tool.schema.name}" has invalid JSON Schema parameters`);
+    }
+    if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) {
+        throw new Error(`tool "${tool.schema.name}" parameters must decode to an object`);
+    }
+    return {
+        name: tool.schema.name,
+        description: tool.schema.description,
+        parameters: clone(parameters),
+        ...(tool.providerOptions ? { providerOptions: clone(tool.providerOptions) } : {}),
+    };
+}
+function lowerMemory(memory) {
+    if (!memory)
+        return undefined;
+    if (memory instanceof WorkingMemory)
+        return { kind: "working" };
+    const reference = memory;
+    return {
+        kind: "durable",
+        ...(reference.namespace ? { namespace: reference.namespace } : {}),
+    };
+}
+function capabilityAllowed(capability, filter) {
+    if (!filter)
+        return true;
+    const kind = capability.kind === "mcp_server" ? "mcp_server" : capability.kind;
+    const kindAllowed = !filter.allowedKinds?.length || filter.allowedKinds.includes(kind);
+    const idAllowed = !filter.allowedIds?.length || filter.allowedIds.includes(capability.id);
+    return kindAllowed && idAllowed;
+}
+/** Pure: no provider branching, no scheduling, authorization, persistence, or Kernel wire calls.
+ * Providers consume only their own namespace from `extensions`; the host decides whether declared
+ * capabilities survive its existing attenuation filter. */
+export function lowerAgent(agent) {
+    const tools = (agent.tools ?? []).map(lowerTool);
+    const mcpServers = clone(agent.mcpServers ?? []);
+    const skills = clone(agent.skills ?? []);
+    const knowledge = clone(agent.knowledge ?? []);
+    const handoffs = clone(agent.handoffs ?? []);
+    const guardrails = clone(agent.guardrails ?? []);
+    const memory = lowerMemory(agent.memory);
+    const extensions = clone(agent.providerOptions ?? {});
+    const capabilities = [
+        ...tools.map(tool => ({ kind: "tool", id: tool.name, description: tool.description })),
+        ...mcpServers.map(server => ({
+            kind: "mcp_server",
+            id: server.name ?? server.transport.kind,
+            description: server.name ?? `${server.transport.kind} MCP server`,
+        })),
+        ...skills.map(skill => ({ kind: "skill", id: skill.name, description: skill.description ?? "" })),
+    ];
+    const capabilityFilter = agent.capabilityFilter ? clone(agent.capabilityFilter) : undefined;
+    const effectiveCapabilities = capabilities.filter(capability => capabilityAllowed(capability, capabilityFilter));
+    return {
+        name: agent.name,
+        ...(agent.description ? { description: agent.description } : {}),
+        ...(agent.instructions ? { instructions: agent.instructions } : {}),
+        ...(agent.model ? { model: clone(agent.model) } : {}),
+        tools,
+        ...(agent.outputSchema ? { outputSchema: clone(agent.outputSchema) } : {}),
+        ...(mcpServers.length ? { mcpServers } : {}),
+        ...(skills.length ? { skills } : {}),
+        ...(memory ? { memory } : {}),
+        ...(knowledge.length ? { knowledge } : {}),
+        ...(handoffs.length ? { handoffs } : {}),
+        ...(guardrails.length ? { guardrails } : {}),
+        ...(agent.metadata ? { metadata: clone(agent.metadata) } : {}),
+        capabilities,
+        ...(capabilityFilter ? { capabilityFilter } : {}),
+        effectiveCapabilities,
+        extensions,
+        inputs: {
+            run: { name: agent.name, ...(agent.model ? { model: clone(agent.model) } : {}) },
+            context: {
+                ...(agent.description ? { description: agent.description } : {}),
+                ...(agent.instructions ? { instructions: agent.instructions } : {}),
+                ...(agent.outputSchema ? { outputSchema: clone(agent.outputSchema) } : {}),
+                knowledge,
+            },
+            capabilities: { tools, mcpServers, skills, effective: effectiveCapabilities },
+            ...(memory ? { memory } : {}),
+            delegation: { handoffs },
+            governance: { guardrails },
+        },
+    };
+}

package/dist/agent.d.ts

@@ -0,0 +1,67 @@
+import type { RegisteredTool } from "./tools/index.js";
+import type { Memory, WorkingMemory } from "./memory/public.js";
+import type { MCPServer } from "./mcp-server.js";
+import type { JsonSchema } from "./runtime/output-schema.js";
+import type { Guardrail } from "./guardrail.js";
+import type { Skill } from "./skill.js";
+import type { Knowledge } from "./knowledge/public.js";
+import type { Handoff } from "./handoff-target.js";
+import type { AgentCapabilityFilter } from "./types/agent.js";
+/** A serializable durable-memory binding for agents that are described before a host store exists. */
+export interface MemoryReference {
+    kind?: "durable";
+    namespace?: string;
+}
+export type AgentMemory = Memory | WorkingMemory | MemoryReference;
+/** spc_001 §2.1: dual-mode model reference — either an explicit vendor model name, or a
+ *  capability-based requirement the Host routes to a concrete model. Routing logic for the
+ *  `ModelRequirement` branch is Provider Adapter work, out of scope here (spc_001-06). */
+export type ModelRef = string | ModelRequirement;
+export interface ModelRequirement {
+    capability?: {
+        reasoning?: boolean;
+        vision?: boolean;
+        toolUse?: boolean;
+    };
+    contextWindow?: number;
+    latencyClass?: string;
+    costClass?: string;
+}
+export interface AgentOptions {
+    name: string;
+    description?: string;
+    instructions?: string;
+    model?: ModelRef;
+    /** Optional host capability ceiling. It narrows declarations during Agent IR lowering; it never grants authority. */
+    capabilityFilter?: AgentCapabilityFilter;
+    tools?: RegisteredTool[];
+    mcpServers?: MCPServer[];
+    skills?: Skill[];
+    memory?: AgentMemory;
+    knowledge?: Knowledge[];
+    handoffs?: Handoff[];
+    providerOptions?: Record<string, unknown>;
+    outputSchema?: JsonSchema;
+    metadata?: Record<string, unknown>;
+    guardrails?: Guardrail[];
+}
+/** spc_001 §2.1: public Agent contract — a thin field-storage wrapper today, with lowering to the
+ *  Kernel's `AgentRunSpec`/Canonical Agent IR added incrementally by later cards (spc_001-03+). */
+export declare class Agent {
+    readonly name: string;
+    readonly description?: string;
+    readonly instructions?: string;
+    readonly model?: ModelRef;
+    readonly capabilityFilter?: AgentCapabilityFilter;
+    readonly tools?: RegisteredTool[];
+    readonly mcpServers?: MCPServer[];
+    readonly skills?: Skill[];
+    readonly memory?: AgentMemory;
+    readonly knowledge?: Knowledge[];
+    readonly handoffs?: Handoff[];
+    readonly providerOptions?: Record<string, unknown>;
+    readonly outputSchema?: JsonSchema;
+    readonly metadata?: Record<string, unknown>;
+    readonly guardrails?: Guardrail[];
+    constructor(options: AgentOptions);
+}

package/dist/agent.js

@@ -0,0 +1,36 @@
+/** spc_001 §2.1: public Agent contract — a thin field-storage wrapper today, with lowering to the
+ *  Kernel's `AgentRunSpec`/Canonical Agent IR added incrementally by later cards (spc_001-03+). */
+export class Agent {
+    name;
+    description;
+    instructions;
+    model;
+    capabilityFilter;
+    tools;
+    mcpServers;
+    skills;
+    memory;
+    knowledge;
+    handoffs;
+    providerOptions;
+    outputSchema;
+    metadata;
+    guardrails;
+    constructor(options) {
+        this.name = options.name;
+        this.description = options.description;
+        this.instructions = options.instructions;
+        this.model = options.model;
+        this.capabilityFilter = options.capabilityFilter;
+        this.tools = options.tools;
+        this.mcpServers = options.mcpServers;
+        this.skills = options.skills;
+        this.memory = options.memory;
+        this.knowledge = options.knowledge;
+        this.handoffs = options.handoffs;
+        this.providerOptions = options.providerOptions;
+        this.outputSchema = options.outputSchema;
+        this.metadata = options.metadata;
+        this.guardrails = options.guardrails;
+    }
+}

package/dist/collaboration/harness.js

@@ -10,7 +10,7 @@ export class CreatorVerifierBody {
     }
     async *run(context) {
         const contractBlock = formatContractForSystemPrompt(this.contract);
-        const result = await this.pool.execute("executor", {
+        const result = await this.pool.execute("implement", {
             sessionId: context.sessionId,
             goal: `${contractBlock}\n\n---\n\n${context.goal}`,
             ...(context.contextInput ? { contextInput: context.contextInput } : {}),

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

@@ -9,14 +9,12 @@ export interface CreatorVerifierMetrics {
 /**
  * CreatorVerifierMode — the simplest multi-agent collaboration pattern.
  *
- * By default uses the kernel spawn path via `pool.ensureCoordinator()`.
- * Pass `useLegacyRunners: true` to fall back to independent runner sessions.
+ * Uses the kernel spawn path through an explicitly configured coordinator.
  *
  * Usage:
  * ```ts
  * const pool = new AgentPool()
- *   .add("executor", executorRunner)
- *   .add("verifier", verifierRunner)
+ *   .configureCoordinator(runtimeOptions, sessionId)
  *
  * const mode = new CreatorVerifierMode(pool)
  * const result = await mode.run(contract)
@@ -33,8 +31,6 @@ export declare class CreatorVerifierMode {
     private _failed;
     constructor(pool: AgentPool, options?: {
         maxAttempts?: number;
-        /** Stable orchestration session for kernel lineage audit. */
-        coordinatorSessionId?: string;
     });
     run(contract: VerificationContract): Promise<ContractOutcome>;
     /** Aggregate drift metrics across all runs through this mode instance. */
@@ -61,7 +57,6 @@ export declare class OrchestrationMode {
     private inner;
     constructor(pool: AgentPool, options?: {
         maxAttempts?: number;
-        coordinatorSessionId?: string;
     });
     run(goal: string): Promise<ContractOutcome & {
         contract: VerificationContract;

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

@@ -4,14 +4,12 @@ import { AttemptLoop } from "../../harness/harness.js";
 /**
  * CreatorVerifierMode — the simplest multi-agent collaboration pattern.
  *
- * By default uses the kernel spawn path via `pool.ensureCoordinator()`.
- * Pass `useLegacyRunners: true` to fall back to independent runner sessions.
+ * Uses the kernel spawn path through an explicitly configured coordinator.
  *
  * Usage:
  * ```ts
  * const pool = new AgentPool()
- *   .add("executor", executorRunner)
- *   .add("verifier", verifierRunner)
+ *   .configureCoordinator(runtimeOptions, sessionId)
  *
  * const mode = new CreatorVerifierMode(pool)
  * const result = await mode.run(contract)
@@ -32,7 +30,7 @@ export class CreatorVerifierMode {
     }
     async run(contract) {
         this._total++;
-        this.pool.ensureCoordinator(this.options.coordinatorSessionId);
+        this.pool.ensureCoordinator();
         const loop = new AttemptLoop({
             body: new CreatorVerifierBody(this.pool, contract),
             judge: new StructuredContractJudge(this.pool, contract),
@@ -115,7 +113,7 @@ export class OrchestrationMode {
         this.inner = new CreatorVerifierMode(pool, options);
     }
     async run(goal) {
-        this.pool.ensureCoordinator(this.options.coordinatorSessionId);
+        this.pool.ensureCoordinator();
         // Step 1: orchestrator produces a VerificationContract
         const contractJson = await this.pool.orchestrate(goal);
         const contract = this._parseContract(contractJson, goal);

package/dist/collaboration/pool.d.ts

@@ -1,9 +1,7 @@
-import type { RuntimeOptions, RuntimeRunner } from "../runtime/runner.js";
+import type { RuntimeOptions } from "../runtime/runner.js";
 import type { VerificationContract } from "./contract.js";
 import type { AgentRunSpec, KernelAgentRole, SubAgentResult } from "../types/agent.js";
-/** Legacy pool roles — mapped to kernel AgentRole when using spawn path. */
-export type AgentRole = "orchestrator" | "executor" | "verifier";
-export declare const KERNEL_ROLE_MAP: Record<AgentRole, KernelAgentRole>;
+export type AgentRole = KernelAgentRole;
 export interface IsolatedVerifierContext {
     contract: VerificationContract;
     artifact: string;
@@ -19,26 +17,16 @@ export interface RoleExecutionInput {
     verificationContractId?: string;
 }
 export declare class AgentPool {
-    private runners;
     private coordinator?;
-    add(role: AgentRole, runner: RuntimeRunner): this;
     /** Enable kernel spawn path with lineage recorded under `sessionId`. */
     configureCoordinator(opts: RuntimeOptions, sessionId: string): this;
-    /**
-     * Infer coordinator from a registered runner (executor → orchestrator → verifier).
-     * Idempotent when coordinator is already configured.
-     */
-    ensureCoordinator(sessionId?: string): this;
+    /** Assert that this pool has one canonical kernel coordinator. */
+    ensureCoordinator(): this;
     usesSpawnPath(): boolean;
-    has(role: AgentRole): boolean;
-    get(role: AgentRole): RuntimeRunner;
-    /**
-     * Spawn a kernel-isolated sub-agent. Requires `configureCoordinator()`.
-     * Maps legacy pool roles to kernel roles (executor → implement, etc.).
-     */
-    spawn(role: AgentRole | KernelAgentRole, goal: string, extra?: Partial<Omit<AgentRunSpec, "identity" | "role" | "goal">>): Promise<SubAgentResult>;
-    /** Execute a role in a caller-owned session so AttemptLoop can retain transcript across attempts. */
-    execute(role: AgentRole, input: RoleExecutionInput): Promise<SubAgentResult>;
+    /** Spawn a kernel-isolated sub-agent. Requires `configureCoordinator()`. */
+    spawn(role: KernelAgentRole, goal: string, extra?: Partial<Omit<AgentRunSpec, "identity" | "role" | "goal">>): Promise<SubAgentResult>;
+    /** Execute a role in a caller-owned session while preserving kernel lineage. */
+    execute(role: KernelAgentRole, input: RoleExecutionInput): Promise<SubAgentResult>;
     verify(ctx: IsolatedVerifierContext): Promise<string>;
     orchestrate(goal: string): Promise<string>;
 }