@deepstrike/sdk 0.2.52 → 0.2.61

package/dist/runtime/canonical-kernel-step.js

@@ -1,5 +1,4 @@
 import { createHash, randomUUID } from "node:crypto";
-import { getKernel } from "../kernel.js";
 import { JournalCasConflictError, MAX_CHAIN_POSITION as JOURNAL_MAX_CHAIN_POSITION, } from "./kernel-journal.js";
 import { encodeCanonicalContentParts, kernelMessageToSdk, renderedContextToSdk, } from "./kernel-step.js";
 export const MAX_CHAIN_POSITION = JOURNAL_MAX_CHAIN_POSITION;
@@ -12,6 +11,21 @@ function totalUsageTokens(terminal) {
     const output = Number(usage.output_tokens ?? 0);
     return Number.isSafeInteger(input + output) ? input + output : 0;
 }
+function canonicalProviderFailureKind(kind) {
+    switch (kind) {
+        case "transport":
+        case "rate_limit":
+        case "model_unavailable":
+            return "transport_exhausted";
+        case "auth":
+        case "invalid_request":
+        case "modality":
+        case "protocol":
+            return "protocol_error";
+        default:
+            return "unknown";
+    }
+}
 export function canonicalUnsupportedEffectResolution(effectId, effectKind) {
     return {
         kind: "resolve_effect",
@@ -343,7 +357,6 @@ export class CanonicalKernelHost {
     }
     async transition(input, options = {}) {
         const inputJson = JSON.stringify({
-            abi_version: getKernel().kernelAbiVersion(),
             operation_id: this.operationId,
             input_id: options.inputId ?? `node-input-${randomUUID()}`,
             observed_at_ms: options.observedAtMs ?? String(Date.now()),
@@ -591,7 +604,7 @@ function logicalRunSpec(raw, goal) {
         ...(raw.metadata && typeof raw.metadata === "object" ? { metadata: raw.metadata } : {}),
     };
 }
-function canonicalWorkflowSpec(raw) {
+function canonicalWorkflowSpec(raw, allowHostSchedulingFactors = false) {
     const nodes = Array.isArray(raw.nodes) ? raw.nodes.map(asObject) : [];
     const nodeIds = nodes.map((_node, index) => `wf-node${index}`);
     return {
@@ -614,6 +627,9 @@ function canonicalWorkflowSpec(raw) {
                 unsupported.push("max_turns");
             if (node.max_wall_ms !== undefined || node.maxWallMs !== undefined)
                 unsupported.push("max_wall_ms");
+            const schedulingFactors = node.scheduling_factors ?? node.schedulingFactors;
+            if (schedulingFactors !== undefined && !allowHostSchedulingFactors)
+                unsupported.push("scheduling_factors");
             const inheritance = node.context_inheritance ?? node.contextInheritance;
             if (unsupported.length > 0) {
                 throw new CanonicalKernelRejectedError(JSON.stringify({
@@ -634,16 +650,20 @@ function canonicalWorkflowSpec(raw) {
                 : [];
             const modelHint = node.model_hint ?? node.modelHint;
             const outputSchema = node.output_schema ?? node.outputSchema;
+            const canonicalSchedulingFactors = schedulingFactors === undefined
+                ? undefined
+                : canonicalSchedulingFactorsForHost(schedulingFactors);
             const runSpec = logicalRunSpec({
                 goal,
                 ...(node.role ? { role: node.role } : {}),
                 ...(node.isolation ? { isolation: node.isolation } : {}),
                 ...(inheritance ? { context_inheritance: inheritance } : {}),
-                ...((modelHint !== undefined || outputSchema !== undefined)
+                ...((modelHint !== undefined || outputSchema !== undefined || canonicalSchedulingFactors !== undefined)
                     ? {
                         metadata: {
                             ...(modelHint !== undefined ? { model_hint: modelHint } : {}),
                             ...(outputSchema !== undefined ? { output_schema: outputSchema } : {}),
+                            ...(canonicalSchedulingFactors !== undefined ? { scheduling_factors: canonicalSchedulingFactors } : {}),
                         },
                     }
                     : {}),
@@ -661,6 +681,24 @@ function canonicalWorkflowSpec(raw) {
         }),
     };
 }
+function canonicalSchedulingFactorsForHost(value) {
+    const raw = asObject(value);
+    const allowed = new Set(["deadline_urgency", "process_priority", "resource_pressure", "budget_pressure"]);
+    const unknown = Object.keys(raw).filter(key => !allowed.has(key));
+    if (unknown.length > 0)
+        throw new TypeError(`unknown scheduling factor(s): ${unknown.join(", ")}`);
+    const factors = {};
+    for (const key of allowed) {
+        const factor = raw[key];
+        if (factor === undefined)
+            continue;
+        if (!Number.isSafeInteger(factor) || factor < 0) {
+            throw new RangeError(`scheduling_factors.${key} must be a non-negative safe integer`);
+        }
+        factors[key] = factor;
+    }
+    return factors;
+}
 function sha256(value) {
     return `sha256:${createHash("sha256").update(value).digest("hex")}`;
 }
@@ -675,8 +713,7 @@ function providerStopReason(value) {
 }
 /**
  * Canonical operation runtime used by the Node host.
- * Every durable transition below is one of the canonical ABI's five input classes; no legacy
- * envelope or synthesized host transaction reaches core or storage.
+ * Every durable transition below is one of the canonical contract's five input classes.
  */
 export class CanonicalRunnerRuntime {
     options;
@@ -802,7 +839,7 @@ export class CanonicalRunnerRuntime {
             kind: "start_operation",
             entry: {
                 kind: "workflow",
-                spec: canonicalWorkflowSpec(specValue),
+                spec: canonicalWorkflowSpec(specValue, true),
             },
             initial_context: this.initialContext,
         });
@@ -856,7 +893,8 @@ export class CanonicalRunnerRuntime {
             }
             case "provider_error": {
                 const message = String(event.message ?? "");
-                const contextOverflow = /context|token.*limit|too long/i.test(message);
+                const hasStructuredKind = typeof event.error_kind === "string";
+                const contextOverflow = event.error_kind === "context_overflow";
                 input = contextOverflow
                     ? {
                         kind: "resolve_effect",
@@ -866,7 +904,7 @@ export class CanonicalRunnerRuntime {
                             result: { kind: "provider", outcome: { kind: "context_overflow" } },
                         },
                     }
-                    : this.failedEffect(event, "transport_exhausted", message, true);
+                    : this.failedEffect(event, hasStructuredKind ? canonicalProviderFailureKind(event.error_kind) : "transport_exhausted", message, typeof event.retryable === "boolean" ? event.retryable : true);
                 break;
             }
             case "tool_results": {
@@ -1425,9 +1463,6 @@ export class CanonicalRunnerRuntime {
             delete asObject(execution.entropy_watch).threshold;
             delete asObject(execution.entropy_watch).hysteresis;
         }
-        if (config.tool_dispatch_gate !== undefined) {
-            this.featurePolicy().tool_dispatch_gate = config.tool_dispatch_gate;
-        }
         if (config.knowledge_budget_ratio !== undefined) {
             const context = asObject(this.config.context_policy);
             context.knowledge_budget_ppm = Math.round(Number(config.knowledge_budget_ratio) * 1_000_000);

package/dist/runtime/context-policy.d.ts

@@ -1,35 +1,33 @@
-export declare const CONTEXT_POLICY_VERSION: 1;
 export declare const PPM_SCALE: 1000000;
-export interface ContextPressureThresholdsV1 {
+export interface ContextPressureThresholds {
     snip: number;
     micro: number;
     collapse: number;
     auto: number;
     renewal: number;
 }
-export interface ContextPolicyV1 {
-    pressureThresholds: ContextPressureThresholdsV1;
+export interface ContextPolicy {
+    pressureThresholds: ContextPressureThresholds;
     targetAfterCompress: number;
     preserveRecentTurns: number;
     renewalCarryover: number;
     collapseOldAssistantNarration: boolean;
     idleMicroCompactMinutes: number;
 }
-export interface ContextPolicyWireV1 {
-    version: typeof CONTEXT_POLICY_VERSION;
-    pressure_thresholds_ppm: ContextPressureThresholdsV1;
+export interface ContextPolicyWire {
+    pressure_thresholds_ppm: ContextPressureThresholds;
     target_after_compress_ppm: number;
     preserve_recent_turns: number;
     renewal_carryover_ppm: number;
     collapse_old_assistant_narration: boolean;
     idle_micro_compact_minutes: number;
 }
-export interface ContextPolicyOverridesV1 extends Partial<Omit<ContextPolicyV1, "pressureThresholds">> {
-    pressureThresholds?: Partial<ContextPressureThresholdsV1>;
+export interface ContextPolicyOverrides extends Partial<Omit<ContextPolicy, "pressureThresholds">> {
+    pressureThresholds?: Partial<ContextPressureThresholds>;
 }
-export declare const DEFAULT_CONTEXT_POLICY_V1: Readonly<ContextPolicyV1>;
+export declare const DEFAULT_CONTEXT_POLICY: Readonly<ContextPolicy>;
 /** Resolve ergonomic partial SDK options into one complete, atomically validated policy. */
-export declare function contextPolicyV1(overrides?: ContextPolicyOverridesV1): ContextPolicyV1;
+export declare function contextPolicy(overrides?: ContextPolicyOverrides): ContextPolicy;
 /** Convert the public ratio-based policy to the canonical integer-only ABI wire shape. */
-export declare function normalizeContextPolicyV1(policy: ContextPolicyV1): ContextPolicyWireV1;
+export declare function normalizeContextPolicy(policy: ContextPolicy): ContextPolicyWire;
 export declare function ratioToPpm(value: number, field?: string): number;

package/dist/runtime/context-policy.js

@@ -1,6 +1,5 @@
-export const CONTEXT_POLICY_VERSION = 1;
 export const PPM_SCALE = 1_000_000;
-export const DEFAULT_CONTEXT_POLICY_V1 = Object.freeze({
+export const DEFAULT_CONTEXT_POLICY = Object.freeze({
     pressureThresholds: Object.freeze({ snip: 0.70, micro: 0.80, collapse: 0.90, auto: 0.95, renewal: 0.98 }),
     targetAfterCompress: 0.65,
     preserveRecentTurns: 2,
@@ -9,20 +8,20 @@ export const DEFAULT_CONTEXT_POLICY_V1 = Object.freeze({
     idleMicroCompactMinutes: 60,
 });
 /** Resolve ergonomic partial SDK options into one complete, atomically validated policy. */
-export function contextPolicyV1(overrides = {}) {
+export function contextPolicy(overrides = {}) {
     const policy = {
-        ...DEFAULT_CONTEXT_POLICY_V1,
+        ...DEFAULT_CONTEXT_POLICY,
         ...overrides,
         pressureThresholds: {
-            ...DEFAULT_CONTEXT_POLICY_V1.pressureThresholds,
+            ...DEFAULT_CONTEXT_POLICY.pressureThresholds,
             ...overrides.pressureThresholds,
         },
     };
-    normalizeContextPolicyV1(policy);
+    normalizeContextPolicy(policy);
     return policy;
 }
 /** Convert the public ratio-based policy to the canonical integer-only ABI wire shape. */
-export function normalizeContextPolicyV1(policy) {
+export function normalizeContextPolicy(policy) {
     const pressure_thresholds_ppm = {
         snip: ratioToPpm(policy.pressureThresholds.snip, "pressureThresholds.snip"),
         micro: ratioToPpm(policy.pressureThresholds.micro, "pressureThresholds.micro"),
@@ -44,7 +43,6 @@ export function normalizeContextPolicyV1(policy) {
         throw new TypeError("collapseOldAssistantNarration must be boolean");
     }
     return {
-        version: CONTEXT_POLICY_VERSION,
         pressure_thresholds_ppm,
         target_after_compress_ppm,
         preserve_recent_turns: policy.preserveRecentTurns,

package/dist/runtime/durable-content.d.ts

@@ -0,0 +1,50 @@
+/** Provider-neutral durable content ABI.
+ *
+ * This is deliberately separate from provider-facing ContentPart. Durable records carry only
+ * portable content and explicit payload locators; protocol adapters decide how to serialize it.
+ */
+export declare class DurableContentError extends Error {
+    constructor(message: string);
+}
+export type DurableSource = {
+    kind: "url";
+    url: string;
+} | {
+    kind: "base64";
+    data: string;
+} | {
+    kind: "file_id";
+    id: string;
+    affinity: {
+        provider_id: string;
+        endpoint_id: string;
+    };
+} | {
+    kind: "object";
+    handle: string;
+    owner: string;
+    payload_ref: string;
+};
+export type DurableContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image" | "audio" | "video" | "file";
+    source: DurableSource;
+    media_type?: string;
+    provider_options?: Record<string, unknown>;
+};
+export interface DurableContent {
+    blocks: DurableContentBlock[];
+}
+export interface DurableToolResult extends DurableContent {
+    call_id: string;
+    is_error: boolean;
+}
+import type { ToolOutputBlock } from "../types.js";
+export declare function decodeDurableContent(value: unknown): DurableContent;
+export declare function decodeDurableToolResult(value: unknown): DurableToolResult;
+export declare function encodeDurableContent(content: DurableContent): Record<string, unknown>;
+export declare function encodeDurableToolResult(result: DurableToolResult): Record<string, unknown>;
+export declare function toolOutputBlocksToDurable(blocks: readonly ToolOutputBlock[]): DurableContentBlock[];
+export declare function durableBlocksToToolOutput(blocks: readonly DurableContentBlock[]): ToolOutputBlock[];

package/dist/runtime/durable-content.js

@@ -0,0 +1,159 @@
+/** Provider-neutral durable content ABI.
+ *
+ * This is deliberately separate from provider-facing ContentPart. Durable records carry only
+ * portable content and explicit payload locators; protocol adapters decide how to serialize it.
+ */
+export class DurableContentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DurableContentError";
+    }
+}
+const CONTENT_KEYS = new Set(["blocks"]);
+const TOOL_RESULT_KEYS = new Set(["call_id", "is_error", "blocks"]);
+const SOURCE_KEYS = {
+    url: new Set(["kind", "url"]),
+    base64: new Set(["kind", "data"]),
+    file_id: new Set(["kind", "id", "affinity"]),
+    object: new Set(["kind", "handle", "owner", "payload_ref"]),
+};
+function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new DurableContentError(`${label} must be an object`);
+    return value;
+}
+function exactKeys(value, allowed, label) {
+    for (const key of Object.keys(value))
+        if (!allowed.has(key))
+            throw new DurableContentError(`${label} has unknown field ${key}`);
+}
+function requiredString(value, label) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new DurableContentError(`${label} must be a non-empty string`);
+    return value;
+}
+function requiredBoolean(value, label) {
+    if (typeof value !== "boolean")
+        throw new DurableContentError(`${label} must be a boolean`);
+    return value;
+}
+function base64(value, label) {
+    const data = requiredString(value, label);
+    if (data.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(data)) {
+        throw new DurableContentError(`${label} is not valid base64`);
+    }
+    return data;
+}
+function source(value, label) {
+    const raw = object(value, `${label} source`);
+    const kind = raw.kind;
+    if (kind !== "url" && kind !== "base64" && kind !== "file_id" && kind !== "object")
+        throw new DurableContentError(`${label} source kind is invalid`);
+    exactKeys(raw, SOURCE_KEYS[kind], `${label} source`);
+    if (kind === "url")
+        return { kind, url: requiredString(raw.url, `${label} URL`) };
+    if (kind === "base64")
+        return { kind, data: base64(raw.data, `${label} base64 data`) };
+    if (kind === "file_id") {
+        const id = requiredString(raw.id, `${label} file id`);
+        const a = object(raw.affinity, `${label} affinity`);
+        exactKeys(a, new Set(["provider_id", "endpoint_id"]), `${label} affinity`);
+        return {
+            kind,
+            id,
+            affinity: {
+                provider_id: requiredString(a.provider_id, `${label} affinity provider_id`),
+                endpoint_id: requiredString(a.endpoint_id, `${label} affinity endpoint_id`),
+            },
+        };
+    }
+    return {
+        kind,
+        handle: requiredString(raw.handle, `${label} object handle`),
+        owner: requiredString(raw.owner, `${label} object owner`),
+        payload_ref: requiredString(raw.payload_ref, `${label} payload_ref`),
+    };
+}
+function block(value, index) {
+    const raw = object(value, `content block ${index}`);
+    const type = raw.type;
+    if (type === "text") {
+        exactKeys(raw, new Set(["type", "text"]), `content block ${index}`);
+        return { type, text: typeof raw.text === "string" ? raw.text : (() => { throw new DurableContentError(`content block ${index} text must be a string`); })() };
+    }
+    if (type === "tool_result")
+        throw new DurableContentError("nested tool_result blocks are forbidden");
+    if (type !== "image" && type !== "audio" && type !== "video" && type !== "file")
+        throw new DurableContentError(`unknown content block type: ${String(type)}`);
+    exactKeys(raw, new Set(["type", "source", "media_type", "provider_options"]), `content block ${index}`);
+    const mediaType = raw.media_type === undefined ? undefined : requiredString(raw.media_type, `content block ${index} media_type`);
+    let providerOptions;
+    if (raw.provider_options !== undefined)
+        providerOptions = object(raw.provider_options, `content block ${index} provider_options`);
+    return {
+        type,
+        source: source(raw.source, `content block ${index}`),
+        ...(mediaType === undefined ? {} : { media_type: mediaType }),
+        ...(providerOptions === undefined ? {} : { provider_options: providerOptions }),
+    };
+}
+function blocks(value) {
+    if (!Array.isArray(value))
+        throw new DurableContentError("content blocks must be an array");
+    return value.map(block);
+}
+export function decodeDurableContent(value) {
+    const raw = object(value, "durable content");
+    exactKeys(raw, CONTENT_KEYS, "durable content");
+    return { blocks: blocks(raw.blocks) };
+}
+export function decodeDurableToolResult(value) {
+    const raw = object(value, "durable tool result");
+    exactKeys(raw, TOOL_RESULT_KEYS, "durable tool result");
+    return { call_id: requiredString(raw.call_id, "tool result call_id"), is_error: requiredBoolean(raw.is_error, "tool result is_error"), blocks: blocks(raw.blocks) };
+}
+export function encodeDurableContent(content) {
+    const decoded = decodeDurableContent(content);
+    return { blocks: decoded.blocks };
+}
+export function encodeDurableToolResult(result) {
+    const decoded = decodeDurableToolResult(result);
+    return { call_id: decoded.call_id, is_error: decoded.is_error, blocks: decoded.blocks };
+}
+export function toolOutputBlocksToDurable(blocks) {
+    return blocks.map((part, index) => {
+        if (part.type === "text")
+            return { type: "text", text: part.text };
+        const source = part.source;
+        const durableSource = source.kind === "fileId"
+            ? {
+                kind: "file_id",
+                id: source.id,
+                affinity: source.affinity
+                    ? { provider_id: source.affinity.providerId, endpoint_id: source.affinity.endpointId }
+                    : (() => { throw new DurableContentError(`tool output block ${index} fileId source requires endpoint affinity`); })(),
+            }
+            : source.kind === "base64" ? { kind: "base64", data: source.data }
+                : source.kind === "url" ? { kind: "url", url: source.url }
+                    : {
+                        kind: "object",
+                        handle: source.handle,
+                        owner: source.owner ?? (() => { throw new DurableContentError(`tool output block ${index} object source requires owner`); })(),
+                        payload_ref: source.payloadRef ?? (() => { throw new DurableContentError(`tool output block ${index} object source requires payloadRef`); })(),
+                    };
+        return { type: part.type, source: durableSource, ...(part.mediaType ? { media_type: part.mediaType } : {}), ...(part.providerOptions ? { provider_options: part.providerOptions } : {}) };
+    });
+}
+export function durableBlocksToToolOutput(blocks) {
+    return blocks.map((part) => {
+        if (part.type === "text")
+            return part;
+        const source = part.source;
+        const sdkSource = source.kind === "file_id"
+            ? { kind: "fileId", id: source.id, affinity: { providerId: source.affinity.provider_id, endpointId: source.affinity.endpoint_id } }
+            : source.kind === "base64" ? source
+                : source.kind === "url" ? source
+                    : { kind: "object", handle: source.handle, owner: source.owner, payloadRef: source.payload_ref };
+        return { type: part.type, source: sdkSource, ...(part.media_type ? { mediaType: part.media_type } : {}), ...(part.provider_options ? { providerOptions: part.provider_options } : {}) };
+    });
+}

package/dist/runtime/execution-plane.d.ts

@@ -1,6 +1,6 @@
 import type { ToolCall, ToolSchema, StreamEvent, ToolSuspendEvent, PermissionRequestEvent, PermissionResponse } from "../types.js";
 import type { RegisteredTool } from "../tools/index.js";
-import type { DreamStore, MemoryScope } from "../memory/protocols.js";
+import type { MemoryStore, MemoryScope } from "../memory/protocols.js";
 import type { KnowledgeSource } from "../knowledge/source.js";
 import type { OperationContext } from "./reliability.js";
 export interface RunContext {
@@ -9,7 +9,7 @@ export interface RunContext {
     agentId?: string;
     memoryScope?: MemoryScope;
     skillDir?: string;
-    dreamStore?: DreamStore;
+    memoryStore?: MemoryStore;
     knowledgeSource?: KnowledgeSource;
     onToolSuspend?: (event: ToolSuspendEvent) => Promise<unknown> | unknown;
     onPermissionRequest?: (event: PermissionRequestEvent) => Promise<PermissionResponse | boolean> | PermissionResponse | boolean;

package/dist/runtime/execution-plane.js

@@ -29,8 +29,8 @@ export class LocalExecutionPlane {
         for (const c of memoryCalls) {
             const args = tryParseJson(c.arguments);
             const topK = typeof args?.top_k === "number" ? args.top_k : 5;
-            const entries = (ctx.dreamStore && ctx.agentId && ctx.memoryScope)
-                ? await ctx.dreamStore.search(ctx.agentId, {
+            const entries = (ctx.memoryStore && ctx.agentId && ctx.memoryScope)
+                ? await ctx.memoryStore.search(ctx.agentId, {
                     scope: ctx.memoryScope,
                     query: String(args?.query ?? ""),
                     top_k: topK,

package/dist/runtime/kernel-event-log.js

@@ -91,7 +91,6 @@ export function kernelObservationToSessionEvent(obs, turn, opts = {}) {
                 kind: "entropy_sample",
                 turn: t,
                 score: obs.score ?? 0,
-                score_version: obs.score_version ?? 0,
                 rho: obs.rho ?? 0,
                 repeat_pressure: obs.repeat_pressure ?? 0,
                 failure_rate: obs.failure_rate ?? 0,

package/dist/runtime/kernel-step.d.ts

@@ -194,7 +194,6 @@ export interface KernelObservation {
     /** nodes_rejected. */
     node_index?: number;
     score?: number;
-    score_version?: number;
     rho?: number;
     repeat_pressure?: number;
     failure_rate?: number;

package/dist/runtime/kernel-step.js

@@ -1,4 +1,4 @@
-const CANONICAL_CONTENT_PARTS_PREFIX = "[[deepstrike-content-parts:v1]]";
+const CANONICAL_CONTENT_PARTS_PREFIX = "[[deepstrike-content-parts]]";
 export function encodeCanonicalContentParts(parts) {
     return `${CANONICAL_CONTENT_PARTS_PREFIX}${Buffer.from(JSON.stringify(parts)).toString("base64url")}`;
 }
@@ -43,6 +43,9 @@ export function skillMetadataToKernel(skill) {
     // P1-B: forward declared tool ids (additive; omitted when empty so existing skills' wire is unchanged).
     if (skill.allowedTools?.length)
         out.allowed_tools = skill.allowedTools;
+    // SPC-015-01: structured grants are caller-supplied rather than inferred from scalar frontmatter.
+    if (skill.capabilityGrants?.length)
+        out.capability_grants = skill.capabilityGrants;
     return out;
 }
 export function messageToKernelMessage(message) {
@@ -153,7 +156,6 @@ export function entropySampleFromObservation(obs) {
     return {
         turn: obs.turn ?? 0,
         score: obs.score ?? 0,
-        scoreVersion: obs.score_version ?? 0,
         rho: obs.rho ?? 0,
         repeatPressure: obs.repeat_pressure ?? 0,
         failureRate: obs.failure_rate ?? 0,

package/dist/runtime/mcp-proxy-plane.d.ts

@@ -1,7 +1,31 @@
-import type { ToolCall, ToolSchema, StreamEvent } from "../types.js";
+import type { ToolCall, ToolSchema, StreamEvent, ToolOutputBlock } from "../types.js";
 import type { RegisteredTool } from "../tools/index.js";
 import type { ExecutionPlane, RunContext } from "./execution-plane.js";
 import type { CredentialVault } from "./credential-vault.js";
+/** Raw MCP `tools/call` response `content` block shapes we accept (text/image/audio). */
+export interface McpContentBlock {
+    type: string;
+    text?: string;
+    data?: string;
+    mimeType?: string;
+}
+/**
+ * spc_012-N-02: pure conversion, unit-testable without spawning a subprocess. Prior behavior
+ * silently dropped every non-`"text"` block (INV-012-01 violation — an MCP tool returning a
+ * screenshot lost the image with no trace). `output` stays the text projection for backward
+ * available as the text projection — when non-text blocks exist the projection
+ * carries an explicit `[modality]` placeholder, so text-only providers (spc_012-N-04) degrade visibly instead
+ * of swallowing the block. `contentParts` is populated (and only populated) when the response
+ * actually contains a non-text block, so pure-text tool calls see zero behavior change.
+ */
+export declare function mcpResultToToolOutput(result: {
+    content?: McpContentBlock[];
+    isError?: boolean;
+}): {
+    output: string;
+    isError: boolean;
+    contentParts?: ToolOutputBlock[];
+};
 export interface McpServerConfig {
     /** Executable to run (e.g. "npx", "python3", "/usr/local/bin/my-mcp-server"). */
     command: string;

package/dist/runtime/mcp-proxy-plane.js

@@ -3,6 +3,41 @@ import { createInterface } from "node:readline";
 import { LocalExecutionPlane } from "./execution-plane.js";
 import { formatToolError } from "../tools/errors.js";
 import { operationAbortSignal } from "./reliability.js";
+/**
+ * spc_012-N-02: pure conversion, unit-testable without spawning a subprocess. Prior behavior
+ * silently dropped every non-`"text"` block (INV-012-01 violation — an MCP tool returning a
+ * screenshot lost the image with no trace). `output` stays the text projection for backward
+ * available as the text projection — when non-text blocks exist the projection
+ * carries an explicit `[modality]` placeholder, so text-only providers (spc_012-N-04) degrade visibly instead
+ * of swallowing the block. `contentParts` is populated (and only populated) when the response
+ * actually contains a non-text block, so pure-text tool calls see zero behavior change.
+ */
+export function mcpResultToToolOutput(result) {
+    const blocks = result.content ?? [];
+    const hasNonText = blocks.some(c => c.type !== "text");
+    if (!hasNonText) {
+        const text = blocks
+            .filter(c => c.type === "text")
+            .map(c => c.text ?? "")
+            .join("\n");
+        return { output: text || JSON.stringify(result), isError: result.isError ?? false };
+    }
+    const output = blocks
+        .map(c => (c.type === "text" ? c.text ?? "" : `[${c.type}]`))
+        .join("\n");
+    const contentParts = blocks.map(c => {
+        if (c.type === "text")
+            return { type: "text", text: c.text ?? "" };
+        if (c.type === "image") {
+            return { type: "image", source: { kind: "base64", data: c.data ?? "" }, mediaType: c.mimeType };
+        }
+        if (c.type === "audio") {
+            return { type: "audio", source: { kind: "base64", data: c.data ?? "" }, mediaType: c.mimeType ?? "audio/wav" };
+        }
+        return { type: "text", text: JSON.stringify(c) };
+    });
+    return { output, isError: result.isError ?? false, contentParts };
+}
 class McpConnection {
     serverName;
     config;
@@ -106,11 +141,7 @@ class McpConnection {
         try {
             const args = JSON.parse(call.arguments || "{}");
             const result = await this.request("tools/call", { name: call.name, arguments: args }, signal);
-            const text = (result.content ?? [])
-                .filter(c => c.type === "text")
-                .map(c => c.text ?? "")
-                .join("\n");
-            return { output: text || JSON.stringify(result), isError: result.isError ?? false };
+            return mcpResultToToolOutput(result);
         }
         catch (err) {
             return { output: formatToolError(err), isError: true };
@@ -215,7 +246,14 @@ export class McpProxyPlane {
         });
         for (const settled of await Promise.all(tasks)) {
             for (const { call, result } of settled) {
-                yield { type: "tool_result", callId: call.id, name: call.name, content: result.output, isError: result.isError };
+                yield {
+                    type: "tool_result",
+                    callId: call.id,
+                    name: call.name,
+                    content: result.output,
+                    isError: result.isError,
+                    contentParts: result.contentParts,
+                };
             }
         }
     }

package/dist/runtime/output-schema.d.ts

@@ -2,7 +2,7 @@ export interface SchemaValidation {
     ok: boolean;
     errors: string[];
 }
-type JsonSchema = Record<string, unknown>;
+export type JsonSchema = Record<string, unknown>;
 /** Validate `value` against `schema` (the supported subset). `path` is for error messages. */
 export declare function validateAgainstSchema(value: unknown, schema: JsonSchema, path?: string): SchemaValidation;
 /** The instruction appended to a node's goal so its agent produces schema-conforming JSON. */
@@ -11,4 +11,3 @@ export declare function schemaInstruction(schema: JsonSchema): string;
 export declare function schemaRetryInstruction(schema: JsonSchema, errors: string[]): string;
 /** Best-effort extraction of a JSON value from agent output (raw, fenced, or embedded). */
 export declare function extractJsonValue(text: string): unknown;
-export {};

package/dist/runtime/provider-replay.d.ts

@@ -1,5 +1,9 @@
 import type { LLMProvider, Message, ProviderDescriptor, ProviderReplay, RenderedContext, ReplayabilityAssessment, ToolCall } from "../types.js";
 import type { SessionEvent } from "./session-log.js";
+export declare class ProviderReplayProtocolMismatchError extends Error {
+    readonly code: "provider_replay_protocol_mismatch";
+    constructor(provider: string, storedProtocol: string, resolvedProtocol: string);
+}
 export declare function assistantReplayKey(message: Pick<Message, "content" | "toolCalls">): string;
 /**
  * A stored replay may only be seeded into a provider speaking the same wire
@@ -7,7 +11,7 @@ export declare function assistantReplayKey(message: Pick<Message, "content" | "t
  * incompatible envelope is skipped so B re-serializes neutral context instead
  * of replaying A's protocol-specific shape.
  */
-export declare function isReplayCompatibleWithProvider(replay: ProviderReplay, descriptor: ProviderDescriptor | undefined): boolean;
+export declare function isReplayCompatibleWithProvider(replay: Partial<ProviderReplay>, descriptor: ProviderDescriptor | undefined): boolean;
 export declare function seedProviderReplayFromEvents(provider: LLMProvider, events: Array<{
     event: SessionEvent;
 }>): void;