@deepstrike/sdk 0.2.52 → 0.2.61

package/dist/runtime/session-repair.d.ts

@@ -8,7 +8,7 @@ export { REPLAY_CONTENT_MAX_BYTES as RECOVERY_CONTENT_MAX_BYTES } from "./replay
  * Content is sanitized and token_count backfilled, but the stored
  * `provider_replay` envelope is passed through verbatim — this layer is
  * provider-neutral and must never synthesize protocol-specific replay shapes
- * (e.g. Anthropic `native_blocks`). Legacy reconstruction for a given protocol
+ * (e.g. Anthropic `native_blocks`). Canonical replay seeding for a given protocol
  * is the responsibility of that provider's `seedProviderReplay`.
  */
 export declare function normalizeLlmCompleted(event: Extract<SessionEvent, {

package/dist/runtime/session-repair.js

@@ -9,7 +9,7 @@ function estimateTokenCount(text) {
  * Content is sanitized and token_count backfilled, but the stored
  * `provider_replay` envelope is passed through verbatim — this layer is
  * provider-neutral and must never synthesize protocol-specific replay shapes
- * (e.g. Anthropic `native_blocks`). Legacy reconstruction for a given protocol
+ * (e.g. Anthropic `native_blocks`). Canonical replay seeding for a given protocol
  * is the responsibility of that provider's `seedProviderReplay`.
  */
 export function normalizeLlmCompleted(event, maxBytes) {

package/dist/runtime/sub-agent-orchestrator.d.ts

@@ -13,7 +13,7 @@ export interface SubAgentRunContext {
         evalProvider: import("../types.js").LLMProvider;
         maxAttempts?: number;
     };
-    /** M5 v2.1: set when this child is a workflow node (spawned by the workflow driver). Propagated to
+    /** workflow-node: set when this child is a workflow node (spawned by the workflow driver). Propagated to
      *  the child runner so a nested `start_workflow` FLATTENS to the parent kernel rather than
      *  auto-pivoting into its own bootstrap (which would fragment the one-kernel/one-quota governance). */
     isWorkflowNode?: boolean;

package/dist/runtime/sub-agent-orchestrator.js

@@ -53,7 +53,7 @@ function deriveMetaTools(permitted, opts) {
     const metaTools = new Set();
     if (permitted.has("skill") && opts.skillDir)
         metaTools.add("skill");
-    if (permitted.has("memory") && opts.dreamStore)
+    if (permitted.has("memory") && opts.memoryStore)
         metaTools.add("memory");
     if (permitted.has("knowledge") && opts.knowledgeSource)
         metaTools.add("knowledge");
@@ -67,7 +67,7 @@ function availableMetaTools(opts) {
     const metaTools = new Set();
     if (opts.skillDir)
         metaTools.add("skill");
-    if (opts.dreamStore)
+    if (opts.memoryStore)
         metaTools.add("memory");
     if (opts.knowledgeSource)
         metaTools.add("knowledge");
@@ -129,20 +129,16 @@ export class SubAgentOrchestrator {
             systemPrompt,
             sessionLog: ctx.sessionLog,
             skillDir: metaTools.has("skill") ? ctx.parentOpts.skillDir : undefined,
-            dreamStore: metaTools.has("memory") ? ctx.parentOpts.dreamStore : undefined,
+            memoryStore: metaTools.has("memory") ? ctx.parentOpts.memoryStore : undefined,
             knowledgeSource: metaTools.has("knowledge") ? ctx.parentOpts.knowledgeSource : undefined,
             enablePlanTool: metaTools.has("update_plan") ? ctx.parentOpts.enablePlanTool : undefined,
             // Nested vehicle: the child joins the inherited runGroup for lineage/settlement only — it
             // must NOT re-reserve budget axes the parent already holds (that double-reserve squeezed the
             // child's grant to 0 and the kernel stripped its first-turn tools).
             nestedGroupVehicle: true,
-            // The child runs under ITS OWN spec, never the parent's: the spread above would otherwise
-            // leak the parent's `runSpec` (identity, capability filter — and a LoopDriver's armed
-            // `loopRound`, giving every child a phantom pace tool). A loop-node iteration carries its
-            // own minimal spec to arm the pacing trap (DW-3); everything else runs spec-less as before.
-            runSpec: ctx.spec.loopRound
-                ? { identity: ctx.spec.identity, role: ctx.spec.role, goal: ctx.spec.goal, loopRound: ctx.spec.loopRound }
-                : undefined,
+            // The child always runs under its own canonical spec, never the parent's. This preserves its
+            // capability ceiling, exposure baseline, identity, and optional loop pacing in one shape.
+            runSpec: ctx.spec,
         });
         // #2-B-ii: when the parent preempts this node (kernel `AgentPreempted`), interrupt the child —
         // cancelling its in-flight LLM call. Handle an already-aborted signal too (creation race).
@@ -258,7 +254,7 @@ export function attemptOutcomeToLoopResult(outcome) {
 /** Canonical single-node root workflow for harness / coordinator use. */
 export async function spawnStandalone(parentOpts, parentSessionId, spec, orchestrator = defaultSubAgentOrchestrator, contextInput) {
     if (spec.tokenBudget !== undefined || spec.maxTurns !== undefined || spec.maxWallMs !== undefined) {
-        throw new Error("spawnStandalone cannot represent per-node resource caps under canonical ABI v3");
+        throw new Error("spawnStandalone cannot represent per-node resource caps under the canonical ABI");
     }
     const { RuntimeRunner } = await import("./runner.js");
     let captured;
@@ -272,6 +268,7 @@ export async function spawnStandalone(parentOpts, parentSessionId, spec, orchest
                     ...ctx.manifest,
                     agent_id: spec.identity.agentId,
                     parent_session_id: parentSessionId,
+                    permitted_capability_ids: spec.capabilityFilter?.allowedIds ?? [],
                 },
                 ...(contextInput ? { contextInput } : {}),
             });

package/dist/runtime/workflow-control-flow.d.ts

@@ -12,10 +12,6 @@ export declare function dependencyOutputsNote(inputAgentIds: string[] | undefine
 export declare function classifyInstruction(labels: string[]): string;
 /** Build a tournament judge's goal: the controller's criterion + the two candidates to compare. */
 export declare function judgeGoal(criterion: string, leftOutput: string, rightOutput: string): string;
-/** Extract a loop stop signal from a loop iteration's output. Returns the `loopContinue` value, or
- *  `undefined` when the agent gave no clear signal (⇒ the kernel runs the loop to `max_iters`).
- *  Accepts `{loop_continue: bool}` or, leniently, `{done: bool}` (continue = !done). */
-export declare function extractLoopContinue(text: string): boolean | undefined;
 /** Extract the chosen branch label from a classifier's output. Prefers `{branch: "..."}`; falls back
  *  to a bare label string that exactly matches one of the valid labels. Returns `undefined` when no
  *  recognizable choice was made (the kernel then prunes every branch — a safe "none matched"). */

package/dist/runtime/workflow-control-flow.js

@@ -45,22 +45,6 @@ export function judgeGoal(criterion, leftOutput, rightOutput) {
         `criterion above.\n\n[CANDIDATE left]\n${leftOutput}\n\n[CANDIDATE right]\n${rightOutput}\n\n` +
         `Respond with ONLY a JSON object: {"winner": "left"} or {"winner": "right"}.`);
 }
-/** Extract a loop stop signal from a loop iteration's output. Returns the `loopContinue` value, or
- *  `undefined` when the agent gave no clear signal (⇒ the kernel runs the loop to `max_iters`).
- *  Accepts `{loop_continue: bool}` or, leniently, `{done: bool}` (continue = !done). */
-export function extractLoopContinue(text) {
-    const v = extractJsonValue(text);
-    if (v && typeof v === "object" && !Array.isArray(v)) {
-        const o = v;
-        if (typeof o.loop_continue === "boolean")
-            return o.loop_continue;
-        if (typeof o.loopContinue === "boolean")
-            return o.loopContinue;
-        if (typeof o.done === "boolean")
-            return !o.done;
-    }
-    return undefined;
-}
 /** Extract the chosen branch label from a classifier's output. Prefers `{branch: "..."}`; falls back
  *  to a bare label string that exactly matches one of the valid labels. Returns `undefined` when no
  *  recognizable choice was made (the kernel then prunes every branch — a safe "none matched"). */

package/dist/session.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public user-session descriptor. This is distinct from persisted `SessionData` and the runtime
+ * `SessionLog`: it carries caller-visible continuity metadata, not messages or journal events.
+ */
+export interface Session {
+    id: string;
+    userId?: string;
+    state?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
+}

package/dist/session.js

@@ -0,0 +1 @@
+export {};

package/dist/skill.d.ts

@@ -0,0 +1,17 @@
+/** spc_001 §2.4: public Skill contract, built directly on `SKILL.md`-style frontmatter files. */
+export interface Skill {
+    name: string;
+    description?: string;
+    instructions?: string;
+    resources?: unknown[];
+    scripts?: unknown[];
+    tools?: unknown[];
+    mcpServers?: unknown[];
+    knowledge?: unknown[];
+    metadata?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
+}
+/** Loads one skill by name from a skill directory, reusing the existing frontmatter scanner and
+ *  body reader — does not reimplement directory scanning. Returns `null` if the skill file is
+ *  absent (mirrors `readSkillFile`'s own not-found signal). */
+export declare function loadSkill(skillDir: string, name: string): Promise<Skill | null>;

package/dist/skill.js

@@ -0,0 +1,16 @@
+import { readSkillFile, scanSkillDir } from "./skills/loader.js";
+/** Loads one skill by name from a skill directory, reusing the existing frontmatter scanner and
+ *  body reader — does not reimplement directory scanning. Returns `null` if the skill file is
+ *  absent (mirrors `readSkillFile`'s own not-found signal). */
+export async function loadSkill(skillDir, name) {
+    const body = await readSkillFile(skillDir, name);
+    if (body === null)
+        return null;
+    const metas = await scanSkillDir(skillDir);
+    const meta = metas.find(m => m.name === name);
+    return {
+        name: meta?.name ?? name,
+        description: meta?.description,
+        instructions: body,
+    };
+}

package/dist/skills/loader.d.ts

@@ -4,6 +4,9 @@ export interface SkillMetadata {
     whenToUse?: string;
     effort?: number;
     estimatedTokens?: number;
+    /** Optional structured grants supplied by the SDK caller. They are not parsed from simple
+     *  SKILL.md frontmatter: the canonical kernel validates their attenuation at activation. */
+    capabilityGrants?: Array<Record<string, unknown>>;
     /** P1-B tool gating: tool ids this skill needs. When the skill is active, the kernel narrows the
      *  exposed toolset to `stable-core ∪ allowedTools`. Parsed from `allowed_tools:` frontmatter
      *  (comma-separated or `[a, b]`). Absent ⇒ the skill does not narrow (back-compat). */

package/dist/tools/errors.d.ts

@@ -52,8 +52,6 @@ export declare function formatToolError(err: unknown): string;
  * - body throws any other `Error` → `{success:false, code: error.code ?? "internal", error: error.message}`
  * - body throws a non-Error → `{success:false, code:"internal", error: formatToolError(...)}`
  *
- * The classic `tool()` factory is unchanged. `safeTool` is opt-in: import and switch one tool at
- * a time. Designed for the consumer-side pattern users had to hand-roll to escape the legacy
- * `String(err)` foot-gun.
+ * `safeTool` is opt-in and returns a structured error envelope instead of `String(err)`.
  */
 export declare function safeTool<T = unknown>(name: string, description: string, parameters: Record<string, unknown>, fn: (args: Record<string, unknown>, ctx?: ToolExecContext) => Promise<ToolEnvelope<T> | T> | ToolEnvelope<T> | T): RegisteredTool;

package/dist/tools/errors.js

@@ -84,9 +84,7 @@ export function formatToolError(err) {
  * - body throws any other `Error` → `{success:false, code: error.code ?? "internal", error: error.message}`
  * - body throws a non-Error → `{success:false, code:"internal", error: formatToolError(...)}`
  *
- * The classic `tool()` factory is unchanged. `safeTool` is opt-in: import and switch one tool at
- * a time. Designed for the consumer-side pattern users had to hand-roll to escape the legacy
- * `String(err)` foot-gun.
+ * `safeTool` is opt-in and returns a structured error envelope instead of `String(err)`.
  */
 export function safeTool(name, description, parameters, fn) {
     const wrapped = async (args, ctx) => {

package/dist/tools/index.d.ts

@@ -17,6 +17,9 @@ export interface ToolExecContext {
 export interface RegisteredTool {
     schema: ToolSchema;
     execute(args: Record<string, unknown>, ctx?: ToolExecContext): Promise<string> | AsyncIterable<ToolChunk>;
+    /** spc_001: vendor-specific extension bag, keyed by provider name. Preserved through
+     *  normalization/lowering, never flattened into portable fields. */
+    providerOptions?: Record<string, unknown>;
 }
 export declare function tool(name: string, description: string, parameters: Record<string, unknown>, fn: (args: Record<string, unknown>, ctx?: ToolExecContext) => Promise<string> | string): RegisteredTool;
 export declare function streamingTool(name: string, description: string, parameters: Record<string, unknown>, fn: (args: Record<string, unknown>, ctx?: ToolExecContext) => AsyncIterable<ToolChunk>): RegisteredTool;

package/dist/types/agent.d.ts

@@ -46,8 +46,7 @@ export interface AgentRunSpec {
      *  advertised before any skill activates, so `exposed = meta ∪ ((baseline ∪ stableCore ∪
      *  ⋃ activeSkills.allowed_tools) ∩ ceiling)`. That makes narrow→wide progressive disclosure
      *  expressible: a tool can be reachable after `skill(x)` without being advertised beforehand.
-     *  Absent ⇒ legacy behavior (ceiling + errs-open skill narrowing). `[]` is meaningful and
-     *  distinct from absent: the minimal surface (meta-tools + stable-core only). Entries outside
+     *  Absent and `[]` both mean the minimal surface (meta-tools + stable-core only). Entries outside
      *  the ceiling silently intersect away. Lowered from `RuntimeOptions.baselineToolIds`. */
     exposureBaseline?: string[];
     /** M1/G3: per-agent model preference (e.g. "opus"/"sonnet"/"haiku"); the host resolves it to a
@@ -68,6 +67,9 @@ export interface AgentRunSpec {
      *  parent's meta-tool availability (same mechanism trusted workflow nodes use) — the child's surface
      *  is a subset of the parent's, never a privilege escalation. */
     toolAccess?: "inherit" | "filtered";
+    /** spc_001: vendor-specific extension bag, keyed by provider name (e.g. `{ openai: {...} }`).
+     *  Preserved through normalization/lowering, never flattened into portable fields. */
+    providerOptions?: Record<string, unknown>;
 }
 /** Kernel process-table observation (Phase 3 canonical spawn signal). */
 export interface AgentProcessChangedObservation {
@@ -87,7 +89,7 @@ export interface LoopResult {
     finalMessage?: Message;
     turnsUsed: number;
     totalTokensUsed: number;
-    /** A#2 v2 loop stop signal: a loop iteration sets `false` to end the loop before `max_iters`.
+    /** loop-control loop stop signal: a loop iteration sets `false` to end the loop before `max_iters`.
      *  `undefined` (every non-loop result) ⇒ no opinion → run to the cap. Sent only when set. */
     loopContinue?: boolean;
     /** A#2 classify routing: a classifier node reports the chosen branch label here; the kernel runs
@@ -96,8 +98,8 @@ export interface LoopResult {
     /** A#2 tournament verdict: a judge reports the winning entrant's agent id here. Sent only when set. */
     tournamentWinner?: string;
     /** ③ loop-agent pacing: the kernel-adjudicated after-round decision, surfaced by the orchestrator
-     *  from the child's done event. For a loop-node iteration this is the PRIMARY continuation
-     *  vocabulary (stop → loopContinue=false); the legacy text-sniffed signal is the fallback.
+     *  from the child's done event. For a loop-node iteration this is the only continuation
+     *  vocabulary (stop → loopContinue=false).
      *  SDK-internal — stripped by `subAgentResultToKernel`. */
     paceDecision?: import("../runtime/kernel-step.js").PaceDecision;
     /** Two-axis AttemptLoop result. Serialized alongside `termination` so hosts can observe judge
@@ -162,6 +164,14 @@ export type WorkflowTaskSpec = {
 export type NodeTrust = "trusted" | "quarantined";
 export type WorkflowDependencyPolicy = "all_success" | "accept_partial" | "all_terminal" | "optional";
 export type WorkflowNodeStatus = "completed" | "completed_partial" | "failed" | "skipped_upstream_failed";
+/** Host-observed, deterministic scheduling inputs for one workflow node. They never originate
+ * from model-authored workflow tools. */
+export interface SchedulingFactors {
+    deadlineUrgency?: number;
+    processPriority?: number;
+    resourcePressure?: number;
+    budgetPressure?: number;
+}
 export declare function workflowNodeStatusFromTermination(termination: TerminationReason | string): WorkflowNodeStatus;
 /** One node in a declarative workflow DAG (camelCase host shape). */
 export interface WorkflowNodeSpec {
@@ -178,7 +188,7 @@ export interface WorkflowNodeSpec {
     /** G2: make this a deterministic *reduce* node — it runs no LLM agent. The runner routes it to the
      *  registered reducer of this name, over its `dependsOn` nodes' outputs (dedupe / filter / merge). */
     reducer?: string;
-    /** A#2 v2: make this a *loop* node — re-run its agent up to `maxIters` times. An iteration may end
+    /** loop-control: make this a *loop* node — re-run its agent up to `maxIters` times. An iteration may end
      *  the loop early by reporting `loopContinue: false` (the runner solicits this from the agent). */
     loop?: {
         maxIters: number;
@@ -202,6 +212,8 @@ export interface WorkflowNodeSpec {
     maxTurns?: number;
     /** O3: cap this node's child run at `maxWallMs` wall-clock milliseconds. */
     maxWallMs?: number;
+    /** Host-only scheduling facts used with the configured deterministic scheduler policy. */
+    schedulingFactors?: SchedulingFactors;
     /** Indices of nodes this node depends on. */
     dependsOn?: number[];
     /** How dependency terminal states gate this node. Defaults to `all_success`. */
@@ -270,7 +282,7 @@ export interface WorkflowSpawnInfo {
         left: string;
         right: string;
     };
-    /** A#2 v2: present only for a *loop* iteration spawn — the loop's `max_iters`. Marks the spawn as a
+    /** loop-control: present only for a *loop* iteration spawn — the loop's `max_iters`. Marks the spawn as a
      *  loop iteration so the runner solicits + reports a `loopContinue` stop signal. */
     loop_max_iters?: number;
     /** A#2: present only for a *classify* spawn — the branch labels the classifier must choose among.
@@ -315,10 +327,10 @@ export declare function workflowSpecToKernel(spec: WorkflowSpec): Record<string,
  *  (true loop-until-done / dynamic fan-out). Give it to nodes meant to fan out; the runner intercepts
  *  the call and routes the nodes to the parent kernel (the child's own kernel holds no workflow). */
 export declare const submitWorkflowNodesTool: ToolSchema;
-/** M5 v1 (flatten): the tool an agent calls to **author a sub-workflow** — a cohesive DAG of nodes
+/** workflow authoring: the tool an agent calls to **author a sub-workflow** — a cohesive DAG of nodes
  *  (incl. loop/classify/tournament/reduce) composed onto the running workflow. Mechanically it lowers
  *  to the same append path as `submit_workflow_nodes` (a `WorkflowSpec` is a node batch), but reads as
- *  "write a harness" rather than "append nodes". v2 adds top-level bootstrap (the `LoadWorkflow`
+ *  "write a harness" rather than "append nodes". Top-level bootstrap uses (the `LoadWorkflow`
  *  kernel syscall) so a plain run can start a workflow from scratch. */
 export declare const startWorkflowTool: ToolSchema;
 /** Build a sub-agent run spec for a kernel-generated workflow node. */

package/dist/types/agent.js

@@ -36,7 +36,7 @@ export function agentRunSpecToKernel(spec) {
             ...(spec.loopRound.defaultAction !== undefined ? { default_action: spec.loopRound.defaultAction } : {}),
         };
     }
-    // Exposure baseline: `undefined` ⇒ omit the field entirely (kernel `None` = legacy behavior);
+    // Exposure baseline: `undefined` ⇒ omit the field entirely (kernel canonical default);
     // `[]` ⇒ send `[]` (kernel `Some([])` = the minimal surface). The unset/minimal distinction is
     // load-bearing, so this is deliberately NOT the `length > 0` idiom `allowedToolIds` uses.
     if (spec.exposureBaseline !== undefined)
@@ -240,6 +240,7 @@ function nodeKindToKernel(n) {
  *  whole spec) and `submit_workflow_nodes` (R3-1 runtime append) so the two encodings never drift. */
 export function workflowNodeSpecToKernel(n) {
     const kind = nodeKindToKernel(n);
+    const schedulingFactors = schedulingFactorsToKernel(n.schedulingFactors);
     return {
         task: workflowTaskToKernel(n.task),
         role: n.role,
@@ -256,16 +257,41 @@ export function workflowNodeSpecToKernel(n) {
         // O3: per-node turn / wall-clock caps (additive; omitted when unset).
         ...(n.maxTurns != null ? { max_turns: n.maxTurns } : {}),
         ...(n.maxWallMs != null ? { max_wall_ms: n.maxWallMs } : {}),
+        ...(schedulingFactors ? { scheduling_factors: schedulingFactors } : {}),
         ...(n.dependsOn && n.dependsOn.length ? { depends_on: n.dependsOn } : {}),
         dep_policy: n.depPolicy ?? "all_success",
     };
 }
+function schedulingFactorsToKernel(factors) {
+    if (factors === undefined)
+        return undefined;
+    const allowed = new Set(["deadlineUrgency", "processPriority", "resourcePressure", "budgetPressure"]);
+    const unknown = Object.keys(factors).filter(key => !allowed.has(key));
+    if (unknown.length > 0)
+        throw new TypeError(`unknown scheduling factor(s): ${unknown.join(", ")}`);
+    const out = {};
+    for (const [host, kernel] of Object.entries({
+        deadlineUrgency: "deadline_urgency",
+        processPriority: "process_priority",
+        resourcePressure: "resource_pressure",
+        budgetPressure: "budget_pressure",
+    })) {
+        const value = factors[host];
+        if (value !== undefined) {
+            if (!Number.isSafeInteger(value) || value < 0) {
+                throw new RangeError(`schedulingFactors.${host} must be a non-negative safe integer`);
+            }
+            out[kernel] = value;
+        }
+    }
+    return out;
+}
 /** Map a host `WorkflowSpec` to the canonical workflow-root JSON. */
 export function workflowSpecToKernel(spec) {
     return { nodes: spec.nodes.map(workflowNodeSpecToKernel) };
 }
 /** Shared JSON-Schema for a workflow-node batch (a DAG). Used by both `submit_workflow_nodes`
- *  (append) and `start_workflow` (M5 v1: author a sub-workflow), so the two tools never drift. */
+ *  (append) and `start_workflow` (workflow authoring: author a sub-workflow), so the two tools never drift. */
 const workflowNodesArraySchema = {
     type: "array",
     description: "Workflow nodes (a DAG); each runs as a gated sub-agent. A node may declare ONE control-flow kind " +
@@ -391,10 +417,10 @@ export const submitWorkflowNodesTool = {
         required: ["nodes"],
     }),
 };
-/** M5 v1 (flatten): the tool an agent calls to **author a sub-workflow** — a cohesive DAG of nodes
+/** workflow authoring: the tool an agent calls to **author a sub-workflow** — a cohesive DAG of nodes
  *  (incl. loop/classify/tournament/reduce) composed onto the running workflow. Mechanically it lowers
  *  to the same append path as `submit_workflow_nodes` (a `WorkflowSpec` is a node batch), but reads as
- *  "write a harness" rather than "append nodes". v2 adds top-level bootstrap (the `LoadWorkflow`
+ *  "write a harness" rather than "append nodes". Top-level bootstrap uses (the `LoadWorkflow`
  *  kernel syscall) so a plain run can start a workflow from scratch. */
 export const startWorkflowTool = {
     name: "start_workflow",

package/dist/types.d.ts

@@ -26,8 +26,70 @@ export interface ToolResultPart {
     callId: string;
     output: string;
     isError: boolean;
+    /** Structured tool output. Provider boundaries normalize this into one canonical block list
+     * and reject `output` when it disagrees with the deterministic text projection. */
+    contentParts?: ToolOutputBlock[];
 }
 export type ContentPart = TextPart | ImagePart | AudioPart | ToolResultPart;
+/**
+ * spc_011-B-05: canonical multimodal content, additive alongside `ContentPart` during the
+ * migration. `ContentBlockImage`/`ContentBlockAudio`/etc.
+ * are distinctly named (not reusing `ImagePart`/`AudioPart`) since those names are already taken
+ * by `ContentPart`'s variants with a different shape (`url?/data?` inline vs `source: MediaSource`).
+ */
+export type MediaSource = {
+    kind: "url";
+    url: string;
+} | {
+    kind: "base64";
+    data: string;
+} | {
+    kind: "fileId";
+    id: string;
+    /** Endpoint that issued this provider-owned reference. An omitted affinity constrains the
+     * reference to the already-resolved current endpoint. */
+    affinity?: {
+        providerId: string;
+        endpointId: string;
+    };
+} | {
+    kind: "object";
+    handle: string;
+    owner?: string;
+    payloadRef?: string;
+};
+export interface ContentBlockText {
+    type: "text";
+    text: string;
+}
+export interface ContentBlockImage {
+    type: "image";
+    source: MediaSource;
+    mediaType?: string;
+    providerOptions?: Record<string, unknown>;
+}
+export interface ContentBlockAudio {
+    type: "audio";
+    source: MediaSource;
+    mediaType?: string;
+    providerOptions?: Record<string, unknown>;
+}
+export interface ContentBlockVideo {
+    type: "video";
+    source: MediaSource;
+    mediaType?: string;
+    providerOptions?: Record<string, unknown>;
+}
+export interface ContentBlockFile {
+    type: "file";
+    source: MediaSource;
+    filename?: string;
+    mediaType?: string;
+    providerOptions?: Record<string, unknown>;
+}
+/** Legal content returned by a tool. Deliberately excludes ToolResult, so nesting is
+ * unrepresentable in the canonical type. */
+export type ToolOutputBlock = ContentBlockText | ContentBlockImage | ContentBlockAudio | ContentBlockVideo | ContentBlockFile;
 export interface Message {
     role: "system" | "user" | "assistant" | "tool";
     /** Plain-text content. When `contentParts` is present, this holds only the text segments. */
@@ -50,11 +112,16 @@ export interface ToolResult {
     isFatal?: boolean;
     errorKind?: ToolErrorKind;
     tokenCount?: number;
+    /** spc_012-N-01: same additive contract as `ToolResultPart.contentParts` (see there). */
+    contentParts?: ToolOutputBlock[];
 }
 export interface ToolSchema {
     name: string;
     description: string;
     parameters: string;
+    /** spc_001: vendor-specific extension bag, keyed by provider name. Preserved through
+     *  normalization/lowering, never flattened into portable fields. */
+    providerOptions?: Record<string, unknown>;
 }
 export interface StreamEvent {
     type: string;
@@ -84,19 +151,20 @@ export interface UsageEvent extends StreamEvent {
     cacheReadInputTokens?: number;
     /** Prompt tokens written to cache this request (billed ~1.25x). Subset of inputTokens. */
     cacheCreationInputTokens?: number;
-    /** I1: per-slot pro-rata attribution of `cacheReadInputTokens`. Estimated, not authoritative —
-     *  Anthropic returns a single cache-read total, so the SDK divides it evenly across the slots
-     *  that carried a `cache_control` breakpoint on the request. Missing when the provider doesn't
-     *  honor `cache_control` (OpenAI-family auto-cache) or when no breakpoints were placed. */
+    cacheTelemetryStatus?: CacheTelemetryStatus;
+    cacheTelemetrySource?: CacheTelemetrySource;
+    /** Reserved for provider-authoritative per-slot data. DeepStrike does not estimate this field. */
     cacheReadInputTokensBySlot?: {
         system?: number;
         tools?: number;
         messages?: number;
     };
-    /** Provider stop reason for the response — `max_tokens` (Anthropic) / `length` (OpenAI) flag an
-     *  output-cap truncation, which drives the kernel's max-output-tokens recovery. Absent when the
-     *  provider doesn't report one. */
-    stopReason?: string;
+    /** Canonical provider stop reason. `max_tokens` drives the kernel's output-cap recovery. */
+    stopReason?: "end_turn" | "tool_use" | "max_tokens" | "stop_sequence" | "content_filter" | "other";
+    /** Original provider spelling for diagnostics only. RuntimeRunner never forwards it to Kernel. */
+    rawStopReason?: string;
+    /** Normalized postflight usage parsed from this same raw provider response. */
+    providerUsage?: ProviderUsage;
 }
 export type ToolChunk = string | {
     type: "text";
@@ -122,7 +190,7 @@ export interface ToolDeltaEvent extends StreamEvent {
     type: "tool_delta";
     callId: string;
     name: string;
-    /** Backward-compatible text projection when the chunk carries text. */
+    /** Text projection when the chunk carries text. */
     delta?: string;
     chunk: Exclude<ToolChunk, string>;
 }
@@ -141,6 +209,9 @@ export interface ToolResultEvent extends StreamEvent {
     isError: boolean;
     isFatal?: boolean;
     errorKind?: ToolErrorKind;
+    /** spc_012-N-02: structured multimodal blocks when the tool returned non-text content
+     *  (e.g. an MCP screenshot). `content` stays the text projection; see `ToolResultPart.contentParts`. */
+    contentParts?: ToolOutputBlock[];
 }
 /** R3-1: a workflow node's agent called the `submit_workflow_nodes` tool. The runner intercepts it
  *  (it cannot apply to the child's own kernel — the workflow lives in the parent) and surfaces the
@@ -206,12 +277,11 @@ export interface ToolAuditFailedEvent extends StreamEvent {
 }
 /** Kernel session-entropy measurement at a completed turn boundary. "Entropy" = session
  *  disorder: repetition, tool failures, rollbacks, context pressure. The component vector is
- *  the contract; `score` is a versioned default fold (`scoreVersion`). All normalized
+ *  the contract; `score` is the canonical default fold. All normalized
  *  components are in [0, 1]. */
 export interface EntropySample {
     turn: number;
     score: number;
-    scoreVersion: number;
     /** Context pressure after this boundary's eviction pass. */
     rho: number;
     /** Consecutive-identical-turn streak, normalized against the RepeatFuse deny rung. */
@@ -262,6 +332,44 @@ export interface TokenUsage {
     /** Prompt tokens written to cache (billed ~1.25x). Subset of inputTokens. */
     cacheCreationInputTokens?: number;
 }
+/** Raw postflight token facts normalized across provider wire shapes. */
+export interface ProviderUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens?: number;
+    cacheCreationInputTokens?: number;
+    cacheTelemetryStatus?: CacheTelemetryStatus;
+    cacheTelemetrySource?: CacheTelemetrySource;
+    /** Output tokens spent on hidden reasoning (OpenAI `completion_tokens_details.reasoning_tokens` /
+     *  Responses `output_tokens_details.reasoning_tokens`). A SUBSET of `outputTokens`, not additional
+     *  — vendors that don't report a separate count (Anthropic, Gemini via this SDK) leave this unset
+     *  rather than guessing. */
+    reasoningTokens?: number;
+}
+export type CacheTelemetryStatus = "measured" | "unavailable";
+export type CacheTelemetrySource = "anthropic_usage" | "openai_prompt_details" | "deepseek_prompt_cache" | "gemini_usage";
+/** Node-side mirror of the reserved Rust `context::measurement` types — where a
+ *  preflight token count came from. Field names/shape intentionally match the Rust
+ *  `MeasurementSource` enum (`kind`-tagged, snake_case variant names) so the two sides can be
+ *  compared/round-tripped without a translation layer. A-00R removed the non-durable adaptive
+ *  scheduler producer; the shape remains for the native provider meter implementations. */
+export type MeasurementSource = {
+    kind: "native";
+    provider: string;
+} | {
+    kind: "local_exact";
+    tokenizer: string;
+} | {
+    kind: "heuristic";
+};
+export type MeasurementConfidence = "exact" | "high_confidence" | "low_confidence";
+/** A single preflight token-count fact for a candidate render, for a specific provider/model —
+ *  the Node counterpart of Rust's `PromptMeasurement` (spc_011-C-02). */
+export interface PromptMeasurement {
+    inputTokens: number;
+    source: MeasurementSource;
+    confidence: MeasurementConfidence;
+}
 export interface ProviderToolSpec {
     name: string;
     description: string;
@@ -326,9 +434,8 @@ export interface ProviderDescriptor {
 }
 /** Provider-native fields required to replay a turn across requests (thinking blocks, reasoning_content, etc.). */
 export interface ProviderReplay {
-    schema_version?: 1 | 2;
     provider?: string;
-    protocol?: ProviderProtocol;
+    protocol: ProviderProtocol;
     model?: string;
     /** Anthropic-style assistant content blocks (thinking, text, tool_use). */
     native_blocks?: Array<Record<string, unknown>>;
@@ -409,12 +516,23 @@ export interface LLMProvider {
      * candidate) before issuing the request. Seed any persisted replay first.
      */
     assessReplayability?(context: RenderedContext, extensions?: Record<string, unknown>): ReplayabilityAssessment;
+    /**
+     * spc_011-C-02/03: preflight token count via the provider's own native counting endpoint
+     * (Anthropic `messages.countTokens` and Gemini `countTokens`),
+     * where the vendor offers one. Optional — providers without a native endpoint simply omit it,
+     * and callers fall back to `FallbackEstimator` (Rust `context::token_engine`, spc_011-C-01) or
+     * a local tokenizer. Not currently invoked by any dispatch loop (nothing in the Rust kernel
+     * emits `EffectKind::MeasurePrompt` yet — see its doc comment); this method exists so the
+     * capability remains directly callable, but no dispatch trigger is enabled until request
+     * fingerprinting and durable measurement semantics are defined.
+     */
+    countTokens?(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>, state?: ProviderRunState): Promise<PromptMeasurement>;
     complete(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>): Promise<Message>;
     stream(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>, state?: ProviderRunState, 
     /** #2-B-ii: when provided, a preempting `InterruptNow` (or `interrupt()`) aborts the in-flight
      *  request. SDK-client providers should forward it to the client (`{ signal }`); the runner also
      *  breaks the consume loop on abort, so providers that ignore it still stop processing immediately
-     *  (only the socket lingers). Optional ⇒ backward-compatible; providers may ignore it. */
+     *  (only the socket lingers). */
     signal?: AbortSignal): AsyncIterable<StreamEvent>;
 }
 /**
@@ -425,10 +543,10 @@ export interface AsyncSummarizer {
     summarize(archived: Message[], action: string): Promise<string>;
 }
 /**
- * Long-term memory summarizer for semantic `page_out` events (Layer 5 contract).
- * The kernel emits `page_out { tier_hint: "semantic" }`; the SDK persists an LLM summary to DreamStore.
+ * Durable-memory summarizer for semantic `page_out` events (Layer 5 contract).
+ * The kernel emits `page_out { tier_hint: "semantic" }`; the SDK persists an LLM summary to MemoryStore.
  */
-export interface DreamSummarizer {
+export interface MemorySummarizer {
     summarize(archived: Message[], context: {
         action?: string;
     }): Promise<string>;