@deepstrike/sdk 0.2.71 → 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.
 
@@ -87,9 +87,11 @@ The root export is the **Agent intent layer** — what you reach for to define a
 | `@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/advanced` | RuntimeRunner, SessionLog, execution planes, kernel diagnostics, and low-level orchestration escape hatches |
+| `@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.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).
+> **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.
 
 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.
 
@@ -114,6 +116,28 @@ 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",
+  }],
+})
+
+await session.run("继续解释其中的内容")
+```
+
+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
 
 `@deepstrike/core` is a native N-API addon; its platform binary ships via `optionalDependencies`. Bundlers (Next.js/Vercel, webpack, esbuild) don't trace `.node` files by default, so the function fails at runtime with `Cannot find module '@deepstrike/core'`. Tell your bundler to treat the package as external and trace its files:

package/dist/advanced/public.d.ts

@@ -18,3 +18,7 @@ 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

@@ -14,3 +14,5 @@ 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

@@ -1,21 +1,24 @@
-import { type AgentOptions } from "./agent.js";
+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 } from "./types.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;
-    provider: LLMProvider;
+    /** 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">;
+    runtimeOptions?: Pick<RuntimeOptions, "memoryPolicy" | "governancePolicy" | "signalSource" | "signalPolicy" | "resourceQuota" | "onPermissionRequest" | "payloadStore" | "runGroup" | "subAgentOrchestrator" | "reducers" | "providerFor" | "initialMemory" | "skillCatalog" | "knowledgeSource" | "contextManager">;
 }
 export interface AgentRunOptions {
     session?: SessionRef;
@@ -23,6 +26,8 @@ export interface AgentRunOptions {
     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;
@@ -33,6 +38,10 @@ export interface RunResult<T = 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>;
@@ -57,13 +66,16 @@ export interface RecallOptions {
 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;
 }
-export interface ExecutableAgent {
+/** 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>;
@@ -79,5 +91,6 @@ export interface ExecutableAgent {
         session?: SessionRef;
         leaseMs?: number;
     }): Promise<RunResult | null>;
+    close(): Promise<void>;
 }
-export declare function createAgent(definition: AgentDefinition): ExecutableAgent;
+export declare function createAgent(definition: AgentDefinition): AgentRuntime;

package/dist/agent-facade.js

@@ -1,6 +1,12 @@
+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()}`;
 }
@@ -13,6 +19,19 @@ function statusFromDone(status) {
         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;
@@ -33,16 +52,16 @@ class AgentSessionImpl {
         this.owner.interrupt(reason);
     }
 }
-class ExecutableAgentImpl {
+class AgentRuntimeImpl {
     name;
     definition;
     sessionLog;
     activeRunner = null;
+    mcpPlane;
+    mcpConnection;
     constructor(definition) {
-        if (!definition.provider)
-            throw new TypeError("createAgent requires a provider");
         this.definition = Object.freeze({ ...definition });
-        this.name = definition.name ?? "agent";
+        this.name = normalizeAgent(definition).name;
         this.sessionLog = definition.sessionLog ?? new InMemorySessionLog();
     }
     session(id = `session-${crypto.randomUUID()}`) {
@@ -88,6 +107,17 @@ class ExecutableAgentImpl {
         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 },
@@ -107,6 +137,7 @@ class ExecutableAgentImpl {
     }
     async workflow(spec, options = {}) {
         const runner = this.createRunner({});
+        await this.prepareMcp();
         this.activeRunner = runner;
         try {
             return await runner.runWorkflow(spec, { sessionId: sessionId(options.session) });
@@ -140,17 +171,21 @@ class ExecutableAgentImpl {
     }
     stream(goal, options = {}) {
         const session = sessionId(options.session);
-        const runner = this.createRunner(options);
-        this.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 });
-        return this.clearRunnerAfter(stream, options.signal, abort);
+        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);
@@ -163,11 +198,15 @@ class ExecutableAgentImpl {
         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 ? "failed" : statusFromDone(done?.status ?? "partial"),
+            status: error || outputValidation && !outputValidation.ok ? "failed" : statusFromDone(done?.status ?? "partial"),
+            ...(outputValidation ? { outputValidation } : {}),
             ...(usageEvent?.totalTokens !== undefined ? {
                 usage: {
                     inputTokens: usageEvent.inputTokens ?? 0,
@@ -179,24 +218,83 @@ class ExecutableAgentImpl {
     }
     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.tools ?? []).reduce((current, currentTool) => current.register(currentTool), new LocalExecutionPlane());
+            ?? (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: this.definition.provider,
+            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 ? { systemPrompt: this.definition.instructions } : {}),
+            ...(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 } : {}),
@@ -215,5 +313,5 @@ class ExecutableAgentImpl {
     }
 }
 export function createAgent(definition) {
-    return new ExecutableAgentImpl(definition);
+    return new AgentRuntimeImpl(definition);
 }

package/dist/agent-ir.d.ts

@@ -1,3 +1,4 @@
+import type { AgentDefinition } from "./agent-facade.js";
 import { Agent, type AgentOptions, type ModelRef } from "./agent.js";
 import type { Guardrail } from "./guardrail.js";
 import type { Handoff } from "./handoff-target.js";
@@ -15,7 +16,7 @@ export interface AgentToolDefinition {
 }
 /** 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"> {
+export interface AgentDescriptor extends Omit<AgentOptions, "tools"> {
     tools?: Array<RegisteredTool | AgentToolDefinition>;
 }
 export interface AgentToolIR {
@@ -85,19 +86,24 @@ export interface AgentSpec {
     guardrails?: Guardrail[];
     metadata?: Record<string, unknown>;
     /** Declared capabilities. This descriptive view grants nothing by itself. */
-    capabilities: AgentCapabilityIR[];
+    readonly 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[];
+    readonly 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;
+export declare function normalizeAgent(agent: Agent | AgentDefinition | AgentDescriptor): 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;
+/** Detached projections; callers can adapt them without changing AgentSpec authority. */
+export declare function projectAgentRun(spec: AgentSpec): AgentLoweringInputs["run"];
+export declare function projectAgentContext(spec: AgentSpec): AgentLoweringInputs["context"];
+export declare function projectAgentCapabilities(spec: AgentSpec): AgentLoweringInputs["capabilities"];
+export declare function projectAgentGovernance(spec: AgentSpec): AgentLoweringInputs["governance"];
+export declare function projectAgentDelegation(spec: AgentSpec): AgentLoweringInputs["delegation"];

package/dist/agent-ir.js

@@ -37,7 +37,7 @@ export function normalizeAgent(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 } : {}) });
+    return new Agent({ ...options, name: options.name ?? "agent", ...(tools ? { tools } : {}) });
 }
 function lowerTool(tool) {
     let parameters;
@@ -88,17 +88,7 @@ export function lowerAgent(agent) {
     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 } : {}),
@@ -113,22 +103,48 @@ export function lowerAgent(agent) {
         ...(handoffs.length ? { handoffs } : {}),
         ...(guardrails.length ? { guardrails } : {}),
         ...(agent.metadata ? { metadata: clone(agent.metadata) } : {}),
-        capabilities,
+        get capabilities() { return declaredCapabilities(this); },
         ...(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 },
+        get effectiveCapabilities() {
+            return declaredCapabilities(this).filter(capability => capabilityAllowed(capability, this.capabilityFilter));
         },
+        extensions,
+    };
+}
+/** Detached projections; callers can adapt them without changing AgentSpec authority. */
+export function projectAgentRun(spec) {
+    return { name: spec.name, ...(spec.model !== undefined ? { model: clone(spec.model) } : {}) };
+}
+export function projectAgentContext(spec) {
+    return {
+        ...(spec.description !== undefined ? { description: spec.description } : {}),
+        ...(spec.instructions !== undefined ? { instructions: spec.instructions } : {}),
+        ...(spec.outputSchema !== undefined ? { outputSchema: clone(spec.outputSchema) } : {}),
+        knowledge: clone(spec.knowledge ?? []),
     };
 }
+export function projectAgentCapabilities(spec) {
+    return {
+        tools: clone(spec.tools),
+        mcpServers: clone(spec.mcpServers ?? []),
+        skills: clone(spec.skills ?? []),
+        effective: clone(spec.effectiveCapabilities),
+    };
+}
+export function projectAgentGovernance(spec) {
+    return { guardrails: clone(spec.guardrails ?? []) };
+}
+export function projectAgentDelegation(spec) {
+    return { handoffs: clone(spec.handoffs ?? []) };
+}
+function declaredCapabilities(spec) {
+    return [
+        ...spec.tools.map(tool => ({ kind: "tool", id: tool.name, description: tool.description })),
+        ...(spec.mcpServers ?? []).map(server => ({
+            kind: "mcp_server",
+            id: server.name ?? server.transport.kind,
+            description: server.name ?? `${server.transport.kind} MCP server`,
+        })),
+        ...(spec.skills ?? []).map(skill => ({ kind: "skill", id: skill.name, description: skill.description ?? "" })),
+    ];
+}

package/dist/canonical-prefix-allowlist.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SPC-028-03: names that retain the Canonical prefix for ABI/runtime reasons.
+ * New provider-neutral types should use a domain and representation name instead.
+ */
+export declare const CANONICAL_PREFIX_ALLOWLIST: readonly ["CanonicalAdapterInput", "CanonicalCheckpoint", "CanonicalCommit", "CanonicalKernel", "CanonicalKernelHost", "CanonicalKernelInput", "CanonicalKernelInstance", "CanonicalKernelRebuildRequiredError", "CanonicalKernelRejectedError", "CanonicalMessage", "CanonicalMessageBlock", "CanonicalPlannedStep", "CanonicalPreparation", "CanonicalPrepared", "CanonicalRejected", "CanonicalRenderedContext", "CanonicalReplayed", "CanonicalRestoreCost", "CanonicalRunnerRuntime", "CanonicalRunnerRuntimeOptions", "CanonicalStopReason", "CanonicalToolResult", "CanonicalTransition", "CanonicalTransitionOptions"];
+export type AllowedCanonicalPrefixName = typeof CANONICAL_PREFIX_ALLOWLIST[number];

package/dist/canonical-prefix-allowlist.js

@@ -0,0 +1,30 @@
+/**
+ * SPC-028-03: names that retain the Canonical prefix for ABI/runtime reasons.
+ * New provider-neutral types should use a domain and representation name instead.
+ */
+export const CANONICAL_PREFIX_ALLOWLIST = [
+    "CanonicalAdapterInput",
+    "CanonicalCheckpoint",
+    "CanonicalCommit",
+    "CanonicalKernel",
+    "CanonicalKernelHost",
+    "CanonicalKernelInput",
+    "CanonicalKernelInstance",
+    "CanonicalKernelRebuildRequiredError",
+    "CanonicalKernelRejectedError",
+    "CanonicalMessage",
+    "CanonicalMessageBlock",
+    "CanonicalPlannedStep",
+    "CanonicalPreparation",
+    "CanonicalPrepared",
+    "CanonicalRejected",
+    "CanonicalRenderedContext",
+    "CanonicalReplayed",
+    "CanonicalRestoreCost",
+    "CanonicalRunnerRuntime",
+    "CanonicalRunnerRuntimeOptions",
+    "CanonicalStopReason",
+    "CanonicalToolResult",
+    "CanonicalTransition",
+    "CanonicalTransitionOptions",
+];

package/dist/evals/public.d.ts

@@ -0,0 +1,50 @@
+/** Public evaluation language. Runtime evidence remains available through the runtime subpath. */
+export { judge, buildEvalMessages, parseVerdict, verdictOutputSchema } from "../runtime/eval.js";
+export type { Criterion, Verdict, VerdictDetail, JudgeArgs } from "../runtime/eval.js";
+export interface DatasetCase {
+    id: string;
+    input: string;
+    expected?: unknown;
+    metadata?: Record<string, unknown>;
+}
+export interface Dataset {
+    name?: string;
+    cases: DatasetCase[];
+}
+export interface Evaluator {
+    name: string;
+    evaluate(input: {
+        testCase: DatasetCase;
+        output: string;
+    }): Promise<number> | number;
+}
+export interface EvalResult {
+    caseId: string;
+    output: string;
+    scores: Record<string, number>;
+}
+/** Optional execution evidence kept separate from the stable score/result contract. */
+export interface EvalTrace {
+    caseId: string;
+    executedInput: string;
+    contextBinding?: Record<string, unknown>;
+    route?: unknown;
+    measurement?: unknown;
+    artifactSet?: unknown;
+}
+export interface EvalRun {
+    runId: string;
+    results: EvalResult[];
+    completed: boolean;
+    traces?: EvalTrace[];
+}
+export declare function evaluate(agent: {
+    run(input: string): Promise<{
+        output: string;
+    }>;
+}, options: {
+    dataset: Dataset;
+    evaluators: Evaluator[];
+    runId?: string;
+    includeTrace?: boolean;
+}): Promise<EvalRun>;

package/dist/evals/public.js

@@ -0,0 +1,25 @@
+/** Public evaluation language. Runtime evidence remains available through the runtime subpath. */
+export { judge, buildEvalMessages, parseVerdict, verdictOutputSchema } from "../runtime/eval.js";
+export async function evaluate(agent, options) {
+    const results = [];
+    const traces = [];
+    for (const testCase of options.dataset.cases) {
+        const output = await agent.run(testCase.input);
+        const scores = {};
+        for (const evaluator of options.evaluators)
+            scores[evaluator.name] = await evaluator.evaluate({ testCase, output: output.output });
+        results.push({ caseId: testCase.id, output: output.output, scores });
+        if (options.includeTrace) {
+            const evidence = output;
+            traces.push({
+                caseId: testCase.id,
+                executedInput: testCase.input,
+                ...(testCase.metadata ? { contextBinding: testCase.metadata } : {}),
+                ...(evidence.route !== undefined ? { route: evidence.route } : {}),
+                ...(evidence.usage !== undefined ? { measurement: evidence.usage } : {}),
+                ...(evidence.artifacts !== undefined ? { artifactSet: evidence.artifacts } : {}),
+            });
+        }
+    }
+    return { runId: options.runId ?? crypto.randomUUID(), results, completed: true, ...(options.includeTrace ? { traces } : {}) };
+}

package/dist/guardrail.d.ts

@@ -1,6 +1,9 @@
-/** Public guardrail declaration. Execution/lowering belongs to a later governance card. */
+import type { GovernancePolicy } from "./governance.js";
+/** Public guardrail declaration. A policy-bearing guardrail lowers into host governance. */
 export interface Guardrail {
     name: string;
     description?: string;
     metadata?: Record<string, unknown>;
+    /** Optional executable governance policy. A descriptive guardrail without this field is inert. */
+    policy?: GovernancePolicy;
 }

package/dist/handoff-target.d.ts

@@ -3,6 +3,8 @@ import type { JsonSchema } from "./runtime/output-schema.js";
 export type AgentRef = string | {
     name: string;
 };
+/** Canonical lowering primitive shared by handoff authorization and workflow nodes. */
+export declare function agentRefName(ref: AgentRef): string;
 export interface Handoff {
     agent: AgentRef;
     description?: string;

package/dist/handoff-target.js

@@ -1 +1,7 @@
-export {};
+/** Canonical lowering primitive shared by handoff authorization and workflow nodes. */
+export function agentRefName(ref) {
+    const name = typeof ref === "string" ? ref : ref.name;
+    if (!name)
+        throw new Error("agent reference requires a non-empty name");
+    return name;
+}