@deepstrike/sdk 0.2.70 → 0.2.72

package/README.md

@@ -4,7 +4,7 @@
   </a>
 </p>
 
-# DeepStrike Node.js SDK
+# DeepStrike Node.js SDK (0.2.72)
 
 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.
 
@@ -40,11 +40,8 @@ The correct platform package is selected automatically via `optionalDependencies
 
 ```typescript
 import {
-  FileSessionLog,
-  LocalExecutionPlane,
-  RuntimeRunner,
+  createAgent,
   OpenAIResponsesProvider,
-  collectText,
   tool,
 } from "@deepstrike/sdk"
 
@@ -56,71 +53,90 @@ const add = tool("add", "Add two numbers.", {
   required: ["x", "y"],
 }, async ({ x, y }) => String(Number(x) + Number(y)))
 
-const plane = new LocalExecutionPlane().register(add)
-const runner = new RuntimeRunner({
+const agent = createAgent({
+  name: "math",
   provider,
-  executionPlane: plane,
-  sessionLog: new FileSessionLog(".deepstrike/sessions"),
-  maxTokens: 4096,
+  tools: [add],
 })
 
-const result = await collectText(runner.run({
-  sessionId: "math-1",
-  goal: "What is 17 + 28?",
-}))
-console.log(result)
+const result = await agent.run("What is 17 + 28?")
+console.log(result.output)
 ```
 
-Same-session continuity is explicit via `sessionId`:
+Same-session continuity is explicit via `agent.session()`:
 
 ```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?" }))
+const session = agent.session("chat-1")
+await session.run("My name is Ada.")
+const reply = await session.run("What is my name?")
+console.log(reply.output)
 ```
 
-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.
+Session persistence and recovery are configured on the Agent; applications use `session.resume()` rather than rebuilding a runner.
 
 ### 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:
+The root export is the **Agent intent layer** — what you reach for to define and run an Agent, author a tool, or pick a provider. Advanced machinery lives behind subpaths, so the common surface stays small and tree-shakeable:
 
 | Import | Contains |
 |--------|----------|
-| `@deepstrike/sdk` | `runAgent` · `runFanout` · `RuntimeRunner` · `tool` · `LocalExecutionPlane` · `InMemorySessionLog`/`FileSessionLog` · `AnthropicProvider`/`OpenAIProvider`/`OpenAIResponsesProvider` · `createProvider` · `Governance` · `AgentPool` · `operationAbortSignal` · core types |
+| `@deepstrike/sdk` | `createAgent` · `Agent`/`RunResult` · `tool` · `AnthropicProvider`/`OpenAIProvider`/`OpenAIResponsesProvider` · `createProvider` · core types |
 | `@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` | `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 |
+| `@deepstrike/sdk/runtime` | RuntimeRunner, SessionLog, runtime projections, and host execution helpers |
+| `@deepstrike/sdk/evals` | Public evaluation language: `judge`, criteria, verdicts, and schemas |
+| `@deepstrike/sdk/advanced` | Kernel diagnostics and low-level orchestration escape hatches |
+
+> **Migration from 0.2.71:** see [`MIGRATION-v0.2.71-to-v0.2.72.md`](../MIGRATION-v0.2.71-to-v0.2.72.md) for the AgentDefinition, message, runtime binding, workflow and package changes.
 
-> **Migration from 0.2.x:** the kernel-lowering converters (`*ToKernel`), low-level prompt/eval builders, and the `OpenAIChatProvider` alias are no longer exported from root; backend providers, planes, memory, harness, and OS utilities moved to the subpaths above. See [`MIGRATION-v0.2.30.md`](./MIGRATION-v0.2.30.md).
+The recipes below the Agent section that mention `RuntimeRunner` are advanced implementation examples. Import it from `@deepstrike/sdk/advanced`; application code should use the Agent and Session methods shown above.
 
 ### Recipes — the canonical entry points
 
-Most apps need one of three shapes. Start with the facades and drop down to `RuntimeRunner` only when you need streaming, signals, memory, or governance hooks.
+Most apps start with one executable Agent. Streaming, sessions, memory, delegation, governance, and workflows are exposed from the Agent and Session objects.
 
 ```typescript
-import { runAgent, runFanout } from "@deepstrike/sdk"
+import { createAgent } from "@deepstrike/sdk"
 
-// 1) Single agent — one prompt, one model, the text back.
-const answer = await runAgent({ provider, goal: "What is 17 + 28?", tools: [add] })
+const agent = createAgent({ name: "researcher", provider, tools: [add] })
+const answer = await agent.run("What is 17 + 28?")
+console.log(answer.output)
 
-// 2) Parallel fan-out → synthesize — N workers, then a synthesis pass, over the kernel-gated DAG.
-//    Bootstraps and tears down its own kernel, so it's safe from a stateless request handler.
-const { synthesis } = await runFanout({
-  provider,
-  tasks: [
-    "Summarize the security posture of the auth module",
-    "Summarize the data-retention posture",
-  ],
-  synthesize: "Combine the worker findings into one risk summary.",
+for await (const event of agent.stream("Summarize the auth module")) {
+  if (event.type === "text_delta") process.stdout.write(event.delta)
+}
+
+const delegated = await agent.delegate({ goal: "Check the data-retention posture" })
+console.log(delegated.output)
+```
+
+For parallel work and dependency graphs, use `agent.workflow(...)`. Kernel scheduling and run isolation remain internal to the Agent facade.
+
+### Multimodal input
+
+Pass image or audio parts through `AgentRunOptions.attachments`. The runner persists them with the
+session and avoids injecting the same attachment twice when a session continues or resumes:
+
+```typescript
+const session = agent.session("conversation-1")
+
+await session.run("先看看这张图", {
+  attachments: [{
+    type: "image",
+    source: { kind: "url", url: "https://storage.example.com/signed/image.png" },
+    mediaType: "image/png",
+  }],
 })
 
-// 3) Full control — sub-agents, governance, signals, streaming, resume → use RuntimeRunner directly.
+await session.run("继续解释其中的内容")
 ```
 
-`runFanout` is sugar over the **standalone `runWorkflow`** path: with no active `run()`, `runner.runWorkflow(spec)` auto-bootstraps a kernel that owns the DAG (governed · resumable), drives it, and tears it down — exactly what a Vercel/Lambda handler needs. See [Dynamic workflows](#dynamic-workflows). For parallel work you can also give each worker its own `RuntimeRunner`; `RuntimeRunner` carries per-run state, so **never share one instance across concurrent runs** — use a fresh instance per worker (or the `AgentPool` primitive).
+The current public `ContentPart` contract supports text, image, audio, and tool-result parts.
+Video and file attachments require an explicit content-type extension and provider conversion.
 
 ### Deploying to serverless / bundlers
 
@@ -308,7 +324,7 @@ Providers take an **options object** and share a `CircuitBreaker`. `extensions`
 `OpenAIProvider` with an options object — no more positional `baseURL` hole:
 
 ```typescript
-import { OpenAIProvider } from "@deepstrike/sdk"
+import { OpenAIProvider } from "@deepstrike/sdk/advanced"
 
 const provider = new OpenAIProvider({
   apiKey,
@@ -479,7 +495,7 @@ No configuration is required. Pass a `PayloadStore` through `RuntimeOptions.payl
 ## Tools
 
 ```typescript
-import { tool } from "@deepstrike/sdk"
+import { tool } from "@deepstrike/sdk/advanced"
 import { readFile } from "@deepstrike/sdk/workflow"
 
 plane.register(tool("search", "Search.", schema, async (args) => ...))
@@ -646,7 +662,7 @@ Session events: `memory_written`, `memory_queried`, `memory_validation_failed`,
 Every run loads `governancePolicy` into the kernel via `load_governance_policy`. The kernel enforces rules **before** tools execute:
 
 ```typescript
-import type { GovernancePolicy } from "@deepstrike/sdk"
+import type { GovernancePolicy } from "@deepstrike/sdk/advanced"
 
 const policy: GovernancePolicy = {
   rules: [
@@ -680,7 +696,7 @@ Default when omitted: allow-all (`DEFAULT_NATIVE_GOVERNANCE_POLICY`).
 `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"
+import { Governance } from "@deepstrike/sdk/advanced"
 
 const gov = new Governance("allow")
 gov.addPermissionRule("danger.*", "deny")

package/dist/advanced/public.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Advanced escape hatch for runtime authors, diagnostics, and compatibility with the
+ * implementation-oriented test harness. Ordinary applications should use the root Agent API.
+ */
+export * from "../index.js";
+export { RuntimeRunner, collectText } from "../runtime/runner.js";
+export type { RuntimeOptions } from "../runtime/runner.js";
+export { runAgent, runFanout } from "../runtime/facade.js";
+export type { RunAgentOptions, RunFanoutOptions } from "../runtime/facade.js";
+export { LocalExecutionPlane } from "../runtime/execution-plane.js";
+export type { ExecutionPlane, RunContext } from "../runtime/execution-plane.js";
+export { InMemorySessionLog, FileSessionLog } from "../runtime/session-log.js";
+export type { SessionLog, SessionEvent, SessionEventKind } from "../runtime/session-log.js";
+export * from "../types/agent.js";
+export * from "../runtime/run-group.js";
+export * from "../runtime/event-stream.js";
+export * from "../runtime/reliability.js";
+export * from "../runtime/turn-policy.js";
+export * from "../runtime/reactive-session.js";
+export * from "../runtime/reaction-checkpoint.js";
+export { projectAgentRun, projectAgentContext, projectAgentCapabilities, projectAgentGovernance, projectAgentDelegation } from "../agent-ir.js";
+export type { AgentDescriptor } from "../agent-ir.js";
+export { FileKernelJournal, InMemoryKernelJournal, JournalCasConflictError, JournalIntegrityError, JournalIoError, diagnoseKernelJournal, } from "../runtime/public.js";
+export type { CheckpointCandidate, InstalledCheckpoint, JournalAppendReceipt, JournalEntry, JournalHead, JournalPruneReceipt, JournalRecordInput, KernelJournal, KernelJournalDiagnosis, ContextPrepared, ContextPrepareJson, ContextVerifyJson, ContextProviderPreparationRequest, EvolutionRuntime, EvolutionStore, InvocationOutcome, ModelInvocation, ProviderAttempt, ProviderAttemptRecord, ProviderAttemptStatus, UsageAccountingPolicy, ModelUsageSettlement, } from "../runtime/public.js";

package/dist/advanced/public.js

@@ -0,0 +1,18 @@
+/**
+ * Advanced escape hatch for runtime authors, diagnostics, and compatibility with the
+ * implementation-oriented test harness. Ordinary applications should use the root Agent API.
+ */
+export * from "../index.js";
+export { RuntimeRunner, collectText } from "../runtime/runner.js";
+export { runAgent, runFanout } from "../runtime/facade.js";
+export { LocalExecutionPlane } from "../runtime/execution-plane.js";
+export { InMemorySessionLog, FileSessionLog } from "../runtime/session-log.js";
+export * from "../types/agent.js";
+export * from "../runtime/run-group.js";
+export * from "../runtime/event-stream.js";
+export * from "../runtime/reliability.js";
+export * from "../runtime/turn-policy.js";
+export * from "../runtime/reactive-session.js";
+export * from "../runtime/reaction-checkpoint.js";
+export { projectAgentRun, projectAgentContext, projectAgentCapabilities, projectAgentGovernance, projectAgentDelegation } from "../agent-ir.js";
+export { FileKernelJournal, InMemoryKernelJournal, JournalCasConflictError, JournalIntegrityError, JournalIoError, diagnoseKernelJournal, } from "../runtime/public.js";

package/dist/agent-facade.d.ts

@@ -0,0 +1,96 @@
+import { type AgentOptions, type ModelRef } from "./agent.js";
+import { type SessionLog } from "./runtime/session-log.js";
+import { type ExecutionPlane } from "./runtime/execution-plane.js";
+import { type RuntimeOptions } from "./runtime/runner.js";
+import type { LLMProvider, StreamEvent, TokenUsage, ContentPart } from "./types.js";
+import type { RegisteredTool } from "./tools/index.js";
+import type { MemoryRecord, MemoryRecall, MemoryScope, MemoryStore, MemoryKind } from "./memory/protocols.js";
+import type { WorkflowSpec, WorkflowOutcome, KernelAgentRole } from "./types/agent.js";
+export interface AgentDefinition extends Omit<AgentOptions, "model" | "name"> {
+    name?: string;
+    /** Public model identity. Runtime resolves this through a provider binding. */
+    model?: ModelRef;
+    /** Optional host binding retained for local/custom execution. */
+    provider?: LLMProvider;
+    tools?: RegisteredTool[];
+    executionPlane?: ExecutionPlane;
+    sessionLog?: SessionLog;
+    maxTokens?: number;
+    memoryStore?: MemoryStore;
+    memoryScope?: MemoryScope;
+    runtimeOptions?: Pick<RuntimeOptions, "memoryPolicy" | "governancePolicy" | "signalSource" | "signalPolicy" | "resourceQuota" | "onPermissionRequest" | "payloadStore" | "runGroup" | "subAgentOrchestrator" | "reducers" | "providerFor" | "initialMemory" | "skillCatalog" | "knowledgeSource" | "contextManager">;
+}
+export interface AgentRunOptions {
+    session?: SessionRef;
+    maxTurns?: number;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+    onPermissionRequest?: RuntimeOptions["onPermissionRequest"];
+    /** Multimodal user input attached to this run and persisted in the session log. */
+    attachments?: ContentPart[];
+}
+export interface SessionRef {
+    id: string;
+}
+export interface RunResult<T = string> {
+    output: T;
+    runId: string;
+    sessionId: string;
+    status: "completed" | "partial" | "failed" | "cancelled";
+    usage?: TokenUsage;
+    outputValidation?: {
+        ok: boolean;
+        errors: string[];
+    };
+}
+export interface AgentSession extends SessionRef {
+    run(goal: string, options?: Omit<AgentRunOptions, "session">): Promise<RunResult>;
+    stream(goal: string, options?: Omit<AgentRunOptions, "session">): AsyncIterable<StreamEvent>;
+    resume(options?: Omit<AgentRunOptions, "session">): AsyncIterable<StreamEvent>;
+    interrupt(reason?: "user" | "deadline" | "lease_lost" | "host_shutdown"): void;
+}
+export interface MemoryInput {
+    name: string;
+    content: string;
+    description?: string;
+    kind?: MemoryKind;
+    confidence?: number;
+    pinned?: boolean;
+    ttlDays?: number;
+}
+export interface RecallOptions {
+    topK?: number;
+    kinds?: MemoryKind[];
+    minScore?: number;
+}
+export interface DelegationRequest {
+    goal: string;
+    role?: KernelAgentRole;
+    /** Optional declared handoff target. When handoffs are declared, this is required and allowlisted. */
+    target?: import("./handoff-target.js").AgentRef;
+}
+export interface DelegationResult {
+    output: string;
+    status: "completed" | "partial" | "failed";
+    nodeId?: string;
+}
+/** The executable host handle created from an AgentDefinition. */
+export interface AgentRuntime {
+    readonly name: string;
+    readonly definition: Readonly<AgentDefinition>;
+    run(goal: string, options?: AgentRunOptions): Promise<RunResult>;
+    stream(goal: string, options?: AgentRunOptions): AsyncIterable<StreamEvent>;
+    session(id?: string): AgentSession;
+    remember(input: MemoryInput): Promise<MemoryRecord>;
+    recall(query: string, options?: RecallOptions): Promise<MemoryRecall[]>;
+    delegate(request: DelegationRequest): Promise<DelegationResult>;
+    workflow(spec: WorkflowSpec, options?: {
+        session?: SessionRef;
+    }): Promise<WorkflowOutcome>;
+    listen(options?: {
+        session?: SessionRef;
+        leaseMs?: number;
+    }): Promise<RunResult | null>;
+    close(): Promise<void>;
+}
+export declare function createAgent(definition: AgentDefinition): AgentRuntime;

package/dist/agent-facade.js

@@ -0,0 +1,317 @@
+import { normalizeAgent } from "./agent-ir.js";
+import { InMemorySessionLog } from "./runtime/session-log.js";
+import { LocalExecutionPlane } from "./runtime/execution-plane.js";
+import { RuntimeRunner } from "./runtime/runner.js";
+import { extractJsonValue, schemaInstruction, validateAgainstSchema } from "./runtime/output-schema.js";
+import { McpProxyPlane } from "./runtime/mcp-proxy-plane.js";
+import { EnvCredentialVault } from "./runtime/credential-vault.js";
+import { agentRefName } from "./handoff-target.js";
+import { createTextKnowledgeSource } from "./knowledge/public.js";
+function sessionId(ref) {
+    return ref?.id ?? `session-${crypto.randomUUID()}`;
+}
+function statusFromDone(status) {
+    if (status === "completed" || status === "done")
+        return "completed";
+    if (status === "cancelled" || status === "user" || status === "deadline" || status === "lease_lost" || status === "host_shutdown")
+        return "cancelled";
+    if (status === "failed" || status === "error")
+        return "failed";
+    return "partial";
+}
+function mergeGuardrailPolicies(base, guardrails) {
+    const policies = [base, ...(guardrails ?? []).map(guardrail => guardrail.policy)].filter((policy) => policy !== undefined);
+    if (!policies.length)
+        return undefined;
+    return {
+        ...(policies.some(policy => policy.defaultAction === "deny") ? { defaultAction: "deny" } : {}),
+        rules: policies.flatMap(policy => policy.rules ?? []),
+        vetoes: [...new Set(policies.flatMap(policy => policy.vetoes ?? []))],
+        rateLimits: policies.flatMap(policy => policy.rateLimits ?? []),
+        constraints: policies.flatMap(policy => policy.constraints ?? []),
+        ...(policies.some(policy => policy.surfaceDeniedInSystem === false) ? { surfaceDeniedInSystem: false } : {}),
+    };
+}
+class AgentSessionImpl {
+    owner;
+    id;
+    constructor(owner, id) {
+        this.owner = owner;
+        this.id = id;
+    }
+    run(goal, options) {
+        return this.owner.run(goal, { ...options, session: { id: this.id } });
+    }
+    stream(goal, options) {
+        return this.owner.stream(goal, { ...options, session: { id: this.id } });
+    }
+    resume(options) {
+        return this.owner.resume(this.id, options);
+    }
+    interrupt(reason = "user") {
+        this.owner.interrupt(reason);
+    }
+}
+class AgentRuntimeImpl {
+    name;
+    definition;
+    sessionLog;
+    activeRunner = null;
+    mcpPlane;
+    mcpConnection;
+    constructor(definition) {
+        this.definition = Object.freeze({ ...definition });
+        this.name = normalizeAgent(definition).name;
+        this.sessionLog = definition.sessionLog ?? new InMemorySessionLog();
+    }
+    session(id = `session-${crypto.randomUUID()}`) {
+        return new AgentSessionImpl(this, id);
+    }
+    async remember(input) {
+        const store = this.definition.memoryStore;
+        const scope = this.definition.memoryScope;
+        if (!store || !scope)
+            throw new Error("agent memory requires memoryStore and memoryScope");
+        const now = Date.now();
+        const record = {
+            record_id: crypto.randomUUID(),
+            scope,
+            name: input.name,
+            kind: input.kind ?? "reference",
+            content: input.content,
+            description: input.description ?? "",
+            provenance: { author: "host", trust: "user_asserted", evidence_refs: [] },
+            created_at: now,
+            updated_at: now,
+            recall_count: 0,
+            confidence: input.confidence ?? 1,
+            links: [],
+            pinned: input.pinned ?? false,
+            ...(input.ttlDays !== undefined ? { ttl_days: input.ttlDays } : {}),
+        };
+        await store.put(this.name, record);
+        return record;
+    }
+    async recall(query, options = {}) {
+        const store = this.definition.memoryStore;
+        const scope = this.definition.memoryScope;
+        if (!store || !scope)
+            throw new Error("agent memory requires memoryStore and memoryScope");
+        const request = {
+            scope,
+            query,
+            top_k: options.topK ?? 8,
+            kinds: options.kinds ?? [],
+            ...(options.minScore !== undefined ? { min_score: options.minScore } : {}),
+        };
+        return store.search(this.name, request);
+    }
+    async delegate(request) {
+        const handoffs = this.definition.handoffs ?? [];
+        if (handoffs.length) {
+            if (!request.target)
+                throw new Error(`agent "${this.name}" requires an explicit handoff target`);
+            const targetName = agentRefName(request.target);
+            const allowed = handoffs.some(handoff => {
+                return agentRefName(handoff.agent) === targetName;
+            });
+            if (!allowed)
+                throw new Error(`agent "${this.name}" cannot hand off to "${targetName}"`);
+        }
+        const spec = {
+            nodes: [{
+                    task: { goal: request.goal },
+                    role: request.role ?? "explore",
+                    isolation: "read_only",
+                    contextInheritance: "system_only",
+                }],
+        };
+        const outcome = await this.workflow(spec);
+        const node = outcome.nodeOutcomes[0];
+        const nodeId = node?.nodeId;
+        return {
+            output: nodeId ? outcome.outputs[nodeId] ?? "" : "",
+            status: node?.status === "completed" ? "completed" : node?.status === "failed" ? "failed" : "partial",
+            ...(nodeId ? { nodeId } : {}),
+        };
+    }
+    async workflow(spec, options = {}) {
+        const runner = this.createRunner({});
+        await this.prepareMcp();
+        this.activeRunner = runner;
+        try {
+            return await runner.runWorkflow(spec, { sessionId: sessionId(options.session) });
+        }
+        finally {
+            this.activeRunner = null;
+        }
+    }
+    async listen(options = {}) {
+        const source = this.definition.runtimeOptions?.signalSource;
+        if (!source)
+            throw new Error("agent signals require runtimeOptions.signalSource");
+        const claim = await source.claimSignal(this.name, options.leaseMs);
+        if (!claim)
+            return null;
+        const payload = claim.signal.payload;
+        const goal = typeof payload.goal === "string"
+            ? payload.goal
+            : typeof payload.summary === "string"
+                ? payload.summary
+                : JSON.stringify(payload);
+        try {
+            const result = await this.run(goal, options.session ? { session: options.session } : {});
+            await source.ackSignal(claim);
+            return result;
+        }
+        catch (error) {
+            await source.nackSignal(claim);
+            throw error;
+        }
+    }
+    stream(goal, options = {}) {
+        const session = sessionId(options.session);
+        const owner = this;
+        return (async function* () {
+            const runner = owner.createRunner(options);
+            await owner.prepareMcp();
+            owner.activeRunner = runner;
+            const abort = () => runner.interrupt("user");
+            if (options.signal) {
+                if (options.signal.aborted)
+                    runner.interrupt("user");
+                else
+                    options.signal.addEventListener("abort", abort, { once: true });
+            }
+            const stream = runner.run({ sessionId: session, goal, ...(options.attachments?.length ? { attachments: options.attachments } : {}) });
+            yield* owner.clearRunnerAfter(stream, options.signal, abort);
+        })();
+    }
+    async run(goal, options = {}) {
+        const session = sessionId(options.session);
+        const events = [];
+        for await (const event of this.stream(goal, { ...options, session: { id: session } }))
+            events.push(event);
+        const done = [...events].reverse().find(event => event.type === "done");
+        const error = [...events].reverse().find(event => event.type === "error");
+        const persisted = await this.sessionLog.read(session);
+        const started = [...persisted].reverse().find(entry => entry.event.kind === "run_started");
+        const usageEvent = [...events].reverse().find(event => event.type === "usage");
+        const output = events.filter(event => event.type === "text_delta").map(event => String(event.delta ?? "")).join("");
+        const outputValidation = this.definition.outputSchema
+            ? validateAgainstSchema(extractJsonValue(output), this.definition.outputSchema)
+            : undefined;
+        return {
+            output,
+            runId: started?.event.kind === "run_started" ? started.event.run_id : `run-${crypto.randomUUID()}`,
+            sessionId: session,
+            status: error || outputValidation && !outputValidation.ok ? "failed" : statusFromDone(done?.status ?? "partial"),
+            ...(outputValidation ? { outputValidation } : {}),
+            ...(usageEvent?.totalTokens !== undefined ? {
+                usage: {
+                    inputTokens: usageEvent.inputTokens ?? 0,
+                    outputTokens: usageEvent.outputTokens ?? 0,
+                    totalTokens: usageEvent.totalTokens,
+                },
+            } : {}),
+        };
+    }
+    async *resume(id, options = {}) {
+        const runner = this.createRunner(options);
+        await this.prepareMcp();
+        this.activeRunner = runner;
+        yield* this.clearRunnerAfter(runner.wake(id), options.signal, () => runner.interrupt("user"));
+    }
+    interrupt(reason = "user") {
+        this.activeRunner?.interrupt(reason);
+    }
+    async close() {
+        await this.mcpConnection;
+        await this.mcpPlane?.disconnect();
+        this.mcpPlane = undefined;
+        this.mcpConnection = undefined;
+    }
+    async prepareMcp() {
+        if (!this.mcpPlane || this.mcpConnection) {
+            await this.mcpConnection;
+            return;
+        }
+        this.mcpConnection = this.mcpPlane.connect();
+        await this.mcpConnection;
+    }
+    createRunner(options) {
+        const model = this.definition.model;
+        const provider = this.definition.provider
+            ?? (typeof model === "string" ? this.definition.runtimeOptions?.providerFor?.(model) : undefined);
+        if (!provider) {
+            throw new Error(`agent "${this.name}" has no runtime provider binding for model ${typeof this.definition.model === "string" ? this.definition.model : "(unresolved)"}`);
+        }
+        if (this.definition.executionPlane && this.definition.mcpServers?.length) {
+            throw new Error("agent mcpServers cannot be combined with a custom executionPlane");
+        }
+        const plane = this.definition.executionPlane
+            ?? (this.definition.mcpServers?.length
+                ? (() => {
+                    const servers = Object.fromEntries(this.definition.mcpServers.map(server => {
+                        if (server.transport.kind !== "stdio") {
+                            throw new Error(`agent MCP transport "${server.transport.kind}" is not supported by the local runtime`);
+                        }
+                        if (server.auth && Object.keys(server.auth).length > 0) {
+                            throw new Error(`agent MCP server "${server.name ?? server.transport.command}" auth requires an explicit CredentialVault binding`);
+                        }
+                        return [server.name ?? server.transport.command, {
+                                command: server.transport.command,
+                                ...(server.transport.args ? { args: server.transport.args } : {}),
+                            }];
+                    }));
+                    this.mcpPlane ??= new McpProxyPlane({ servers, vault: new EnvCredentialVault() });
+                    return this.mcpPlane;
+                })()
+                : (this.definition.tools ?? []).reduce((current, currentTool) => current.register(currentTool), new LocalExecutionPlane()));
+        if (this.definition.mcpServers?.length && this.definition.tools?.length) {
+            plane.register(...this.definition.tools);
+        }
+        const runtime = {
+            provider,
+            ...(mergeGuardrailPolicies(this.definition.runtimeOptions?.governancePolicy, this.definition.guardrails)
+                ? { governancePolicy: mergeGuardrailPolicies(this.definition.runtimeOptions?.governancePolicy, this.definition.guardrails) }
+                : {}),
+            ...(this.definition.capabilityFilter ? { capabilityFilter: this.definition.capabilityFilter } : {}),
+            executionPlane: plane,
+            sessionLog: this.sessionLog,
+            maxTokens: this.definition.maxTokens ?? 32_000,
+            ...(this.definition.instructions || this.definition.outputSchema ? {
+                systemPrompt: [
+                    this.definition.instructions,
+                    this.definition.outputSchema ? schemaInstruction(this.definition.outputSchema) : undefined,
+                ].filter((part) => Boolean(part)).join("\n\n"),
+            } : {}),
+            ...(options.maxTurns !== undefined ? { maxTurns: options.maxTurns } : {}),
+            ...(this.definition.memoryStore ? { memoryStore: this.definition.memoryStore } : {}),
+            ...(this.definition.memoryScope ? { memoryScope: this.definition.memoryScope } : {}),
+            ...(this.definition.skills?.length ? { skillCatalog: this.definition.skills } : {}),
+            ...(!this.definition.runtimeOptions?.knowledgeSource && this.definition.knowledge?.some(item => item.source.kind === "text") ? {
+                knowledgeSource: createTextKnowledgeSource(this.definition.knowledge
+                    .filter((item) => item.source.kind === "text")
+                    .map(item => ({ id: item.id, name: item.name, content: item.source.content }))),
+            } : {}),
+            agentId: this.name,
+            ...(this.definition.runtimeOptions ?? {}),
+            ...(options.onPermissionRequest ? { onPermissionRequest: options.onPermissionRequest } : {}),
+        };
+        return new RuntimeRunner(runtime);
+    }
+    async *clearRunnerAfter(stream, signal, abort) {
+        try {
+            yield* stream;
+        }
+        finally {
+            if (signal && abort)
+                signal.removeEventListener("abort", abort);
+            this.activeRunner = null;
+        }
+    }
+}
+export function createAgent(definition) {
+    return new AgentRuntimeImpl(definition);
+}