@deepstrike/sdk 0.2.71 → 0.2.72

package/dist/runtime-language.js

@@ -0,0 +1,51 @@
+/**
+ * SPC-028-01: the normative vocabulary for the four runtime language layers.
+ *
+ * Terms are names, not a second semantic authority. The registry is consumed by
+ * conformance tests and documentation tooling so each term has one primary layer.
+ */
+export const RUNTIME_VOCABULARY = {
+    version: "0.2.72",
+    public: [
+        "Agent", "Model", "Run", "Session", "Tool", "Skill", "Memory", "Knowledge",
+        "MCPServer", "Handoff", "Workflow", "Guardrail", "Eval", "Dataset", "Evaluator",
+        "Output", "Usage",
+    ],
+    host: [
+        "AgentSpec", "Context", "ContextPlan", "Capability", "ModelRoute", "Invocation",
+        "ProviderAttempt", "Measurement", "Evidence", "Artifact", "Evaluation", "Promotion",
+        "ExecutionPlane",
+    ],
+    kernel: [
+        "Operation", "Intent", "Decision", "Effect", "Fact", "Settlement", "Task", "Capability",
+        "Budget", "Journal", "Checkpoint", "StateTransition",
+    ],
+    provider: [
+        "Model", "Provider", "Endpoint", "Protocol", "Route", "Adapter", "Request", "Response",
+        "Usage", "ReplayEvidence",
+    ],
+    primaryDomain: {
+        Model: "public",
+        Usage: "public",
+        Capability: "host",
+        Route: "host",
+    },
+    verbs: {
+        resolve: "select or answer a runtime object at a boundary",
+        render: "project semantic state into model-facing input",
+        encode: "map semantic input into a wire request",
+        execute: "perform one physical provider or external call",
+        decode: "extract semantic output and retained wire evidence",
+        normalize: "map vendor data into the controlled runtime vocabulary",
+        settle: "apply accounting policy to an observed measurement",
+    },
+};
+/** Returns all layer terms while preserving the registry's primary-domain order. */
+export function runtimeVocabularyTerms() {
+    return [
+        ...RUNTIME_VOCABULARY.public,
+        ...RUNTIME_VOCABULARY.host,
+        ...RUNTIME_VOCABULARY.kernel,
+        ...RUNTIME_VOCABULARY.provider,
+    ];
+}

package/dist/skill.d.ts

@@ -1,13 +1,39 @@
+export interface SkillResource {
+    name: string;
+    uri?: string;
+    content?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SkillScript {
+    name: string;
+    command: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+export type SkillTool = string | {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+};
+export type SkillMCPServer = string | {
+    name: string;
+    transport: Record<string, unknown>;
+};
+export type SkillKnowledge = string | {
+    name: string;
+    content?: string;
+    source?: unknown;
+};
 /** 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[];
+    resources?: SkillResource[];
+    scripts?: SkillScript[];
+    tools?: SkillTool[];
+    mcpServers?: SkillMCPServer[];
+    knowledge?: SkillKnowledge[];
     metadata?: Record<string, unknown>;
     providerOptions?: Record<string, unknown>;
 }

package/dist/types/agent.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderMessage, ToolSchema } from "../types.js";
+import type { ModelMessage, ToolSchema } from "../types.js";
 export type KernelAgentRole = "explore" | "plan" | "implement" | "verify" | "custom";
 export type AgentIsolation = "shared" | "read_only" | "worktree" | "remote";
 export type ContextInheritance = "none" | "system_only" | "full";
@@ -86,7 +86,7 @@ export interface AgentProcessChangedObservation {
 }
 export interface LoopResult {
     termination: TerminationReason | string;
-    finalMessage?: ProviderMessage;
+    finalMessage?: ModelMessage;
     turnsUsed: number;
     totalTokensUsed: number;
     /** loop-control loop stop signal: a loop iteration sets `false` to end the loop before `max_iters`.
@@ -163,6 +163,13 @@ export type WorkflowTaskSpec = {
 /** W3 trust level for a workflow node. */
 export type NodeTrust = "trusted" | "quarantined";
 export type WorkflowDependencyPolicy = "all_success" | "accept_partial" | "all_terminal" | "optional";
+export type WorkflowContextInclude = "dependency_outputs" | "memory" | "knowledge";
+export type WorkflowDependencyMode = "full" | "summary" | "reference";
+export interface WorkflowContextPolicy {
+    include?: WorkflowContextInclude[];
+    dependencyMode?: WorkflowDependencyMode;
+    maxTokens?: number;
+}
 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. */
@@ -175,8 +182,14 @@ export interface SchedulingFactors {
 export declare function workflowNodeStatusFromTermination(termination: TerminationReason | string): WorkflowNodeStatus;
 /** One node in a declarative workflow DAG (camelCase host shape). */
 export interface WorkflowNodeSpec {
+    /** Stable public workflow step key; host-only metadata for lowering and diagnostics. */
+    nodeId?: string;
     task: WorkflowTaskSpec;
     role: KernelAgentRole;
+    /** Public workflow binding retained by the host while lowering the node to a kernel agent run. */
+    agent?: string;
+    /** Host context contract; dependency data is narrowed before entering the child goal. */
+    context?: WorkflowContextPolicy;
     isolation?: AgentIsolation;
     contextInheritance?: ContextInheritance;
     modelHint?: string;
@@ -228,7 +241,7 @@ export interface KernelWorkflowNodeOutcome {
     status: WorkflowNodeStatus;
     termination?: TerminationReason;
     output?: {
-        role: ProviderMessage["role"];
+        role: ModelMessage["role"];
         content: string;
         tool_calls?: Array<{
             id: string;
@@ -241,7 +254,7 @@ export interface WorkflowNodeOutcome {
     nodeId: string;
     status: WorkflowNodeStatus;
     termination?: TerminationReason;
-    output?: ProviderMessage;
+    output?: ModelMessage;
 }
 /** A control-plane request rejected before any workflow effect started. */
 export interface ControlRequestRejection {

package/dist/types.d.ts

@@ -84,7 +84,8 @@ export interface ContentBlockFile {
 /** Legal content returned by a tool. Deliberately excludes ToolExecutionResult, so nesting is
  * unrepresentable in the canonical type. */
 export type ToolOutputBlock = ContentBlockText | ContentBlockImage | ContentBlockAudio | ContentBlockVideo | ContentBlockFile;
-export interface ProviderMessage {
+/** Semantic message consumed by the model invocation layer. Provider wire messages are adapter-local. */
+export interface ModelMessage {
     role: "system" | "user" | "assistant" | "tool";
     /** Plain-text content. When `contentParts` is present, this holds only the text segments. */
     content: string;
@@ -92,6 +93,17 @@ export interface ProviderMessage {
     contentParts?: ContentPart[];
     toolCalls?: ToolCall[];
 }
+/** Stored durable representation. It references the semantic message without becoming a second content authority. */
+export interface StoredMessage extends ModelMessage {
+    readonly messageId?: string;
+    readonly createdAt?: number;
+}
+/** Host execution representation; contentParts remains the structured content authority. */
+export interface RuntimeMessage extends ModelMessage {
+    readonly messageId?: string;
+}
+/** Provider wire representation is adapter-owned and intentionally opaque at the SDK boundary. */
+export type WireMessage = Readonly<Record<string, unknown>>;
 export interface ToolCall {
     id: string;
     name: string;
@@ -478,7 +490,7 @@ export interface RenderedContext {
     /** Knowledge (memory retrievals, skill definitions, artifacts). Anthropic system[1] with cache_control. */
     systemKnowledge?: string;
     /** History turns only — the stable, cacheable message prefix. */
-    turns: ProviderMessage[];
+    turns: ModelMessage[];
     /**
      * Volatile State turn (task_state + signals), rebuilt every call. Providers
      * render it after the cacheable history (Anthropic: after the cache breakpoint;
@@ -486,7 +498,7 @@ export interface RenderedContext {
      * older binding that has not been rebuilt — then the State turn is still inside
      * `turns[0]` and providers render `turns` as-is.
      */
-    stateTurn?: ProviderMessage;
+    stateTurn?: ModelMessage;
     /**
      * P1-E: count of leading `turns` forming the frozen prefix — byte-stable until the next
      * compaction. The Anthropic provider pins a deep cache breakpoint at this boundary (a long-lived
@@ -531,7 +543,7 @@ export interface LLMProvider {
      */
     runtimePolicy?(): RuntimePolicy;
     /** Read provider-native replay fields captured after the most recent assistant turn. */
-    peekProviderReplay?(message: Pick<ProviderMessage, "content" | "toolCalls">): ProviderReplay | undefined;
+    peekProviderReplay?(message: Pick<ModelMessage, "content" | "toolCalls">): ProviderReplay | undefined;
     /**
      * P4-S1: read the transport facts captured during the most recent execution (HTTP rung count,
      * wire response id). Optional — a provider without it simply omits the telemetry and the
@@ -540,7 +552,7 @@ export interface LLMProvider {
      */
     peekTransportTelemetry?(): ProviderTransportTelemetry | undefined;
     /** Restore provider-native replay fields when rebuilding history from SessionLog. */
-    seedProviderReplay?(message: Pick<ProviderMessage, "content" | "toolCalls">, replay: ProviderReplay): void;
+    seedProviderReplay?(message: Pick<ModelMessage, "content" | "toolCalls">, replay: ProviderReplay): void;
     /**
      * Pre-flight query: would this history validate against this provider with the
      * given extensions, without sending the request? Returns the tool-call ids
@@ -554,13 +566,11 @@ export interface LLMProvider {
      * (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.
+     * a local tokenizer. The host runner invokes this capability during provider request
+     * preparation and binds the resulting measurement to the prepared request fingerprint.
      */
     countTokens?(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>, state?: ProviderRunState): Promise<PromptMeasurement>;
-    complete(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>): Promise<ProviderMessage>;
+    complete(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>): Promise<ModelMessage>;
     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
@@ -573,14 +583,14 @@ export interface LLMProvider {
  * Produces a richer LLM-generated summary that replaces the rule-based one on next wake.
  */
 export interface AsyncSummarizer {
-    summarize(archived: ProviderMessage[], action: string): Promise<string>;
+    summarize(archived: ModelMessage[], action: string): Promise<string>;
 }
 /**
  * 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 MemorySummarizer {
-    summarize(archived: ProviderMessage[], context: {
+    summarize(archived: ModelMessage[], context: {
         action?: string;
     }): Promise<string>;
 }

package/dist/workflow/definition.d.ts

@@ -0,0 +1,19 @@
+import type { Agent } from "../agent.js";
+import type { AgentRef } from "../handoff-target.js";
+import type { WorkflowContextPolicy, WorkflowDependencyPolicy, WorkflowOutcome, WorkflowSpec } from "../types/agent.js";
+export interface WorkflowStep {
+    agent: Agent | AgentRef;
+    input: string;
+    dependsOn?: string[];
+    dependencyPolicy?: WorkflowDependencyPolicy;
+    context?: WorkflowContextPolicy;
+    metadata?: Record<string, unknown>;
+}
+export interface WorkflowDefinition {
+    name?: string;
+    steps: Record<string, WorkflowStep>;
+    metadata?: Record<string, unknown>;
+}
+export declare function lowerWorkflowDefinition(definition: WorkflowDefinition): WorkflowSpec;
+export type WorkflowResult = WorkflowOutcome;
+export declare function createWorkflow(definition: WorkflowDefinition): WorkflowDefinition;

package/dist/workflow/definition.js

@@ -0,0 +1,29 @@
+import { agentRefName } from "../handoff-target.js";
+export function lowerWorkflowDefinition(definition) {
+    const entries = Object.entries(definition.steps);
+    const indexById = new Map(entries.map(([nodeId], index) => [nodeId, index]));
+    return {
+        nodes: entries.map(([nodeId, step]) => ({
+            ...(() => {
+                const dependsOn = step.dependsOn?.map(dependencyId => {
+                    const index = indexById.get(dependencyId);
+                    if (index === undefined)
+                        throw new Error(`workflow step "${nodeId}" depends on unknown step "${dependencyId}"`);
+                    return index;
+                });
+                return dependsOn ? { dependsOn } : {};
+            })(),
+            nodeId,
+            task: { goal: step.input },
+            role: "implement",
+            isolation: "read_only",
+            contextInheritance: "system_only",
+            dependencyPolicy: step.dependencyPolicy,
+            context: step.context,
+            agent: agentRefName(step.agent),
+        })),
+    };
+}
+export function createWorkflow(definition) {
+    return Object.freeze({ ...definition, steps: Object.freeze({ ...definition.steps }) });
+}

package/dist/workflow/public.d.ts

@@ -3,8 +3,10 @@ export type { SubAgentRunContext } from "../runtime/sub-agent-orchestrator.js";
 export { builtinReducers, resolveReducer } from "../runtime/reducers.js";
 export type { Reducer, ReducerRegistry, ReducerInput } from "../runtime/reducers.js";
 export { FileWorkflowStore } from "../runtime/workflow-store.js";
+export { createWorkflow, lowerWorkflowDefinition } from "./definition.js";
+export type { WorkflowDefinition, WorkflowStep, WorkflowResult } from "./definition.js";
 export { submitWorkflowNodesTool, startWorkflowTool, generateAndFilter, verifyRules, genEval, milestoneCheckPass, milestoneCheckFail, MILESTONE_UNVERIFIED_REASON, } from "../types/agent.js";
-export type { AgentCapabilityFilter, AgentIdentity, AgentIsolation, AgentRunSpec, AgentProcessChangedObservation, ContextInheritance, KernelAgentRole, LoopResult, MilestoneCheckResult, MilestoneContract, MilestonePhase, MilestonePolicy, SubAgentResult, TerminationReason, WorkflowSpawnInfo, WorkflowTaskSpec, WorkflowDependencyPolicy, WorkflowNodeStatus, WorkflowNodeOutcome, WorkflowOutcome, } from "../types/agent.js";
+export type { AgentCapabilityFilter, AgentIdentity, AgentIsolation, AgentRunSpec, AgentProcessChangedObservation, ContextInheritance, KernelAgentRole, LoopResult, MilestoneCheckResult, MilestoneContract, MilestonePhase, MilestonePolicy, SubAgentResult, TerminationReason, WorkflowSpawnInfo, WorkflowTaskSpec, WorkflowDependencyPolicy, WorkflowContextInclude, WorkflowDependencyMode, WorkflowContextPolicy, WorkflowNodeStatus, WorkflowNodeOutcome, WorkflowOutcome, } from "../types/agent.js";
 export type { AcceptanceCriterion, VerificationContract, ContractCheckResult } from "../collaboration/contract.js";
 export { ContractBuilder, formatContractForSystemPrompt, contractToCriteriaStrings } from "../collaboration/contract.js";
 export type { AgentRole, IsolatedVerifierContext, CoordinatorConfig } from "../collaboration/pool.js";

package/dist/workflow/public.js

@@ -5,6 +5,7 @@
 export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "../runtime/sub-agent-orchestrator.js";
 export { builtinReducers, resolveReducer } from "../runtime/reducers.js";
 export { FileWorkflowStore } from "../runtime/workflow-store.js";
+export { createWorkflow, lowerWorkflowDefinition } from "./definition.js";
 export { submitWorkflowNodesTool, startWorkflowTool, generateAndFilter, verifyRules, genEval, milestoneCheckPass, milestoneCheckFail, MILESTONE_UNVERIFIED_REASON, } from "../types/agent.js";
 export { ContractBuilder, formatContractForSystemPrompt, contractToCriteriaStrings } from "../collaboration/contract.js";
 export { HandoffBus } from "../collaboration/handoff.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.2.71",
+  "version": "0.2.72",
   "description": "DeepStrike Node.js SDK",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -38,6 +38,14 @@
     "./advanced": {
       "types": "./dist/advanced/public.d.ts",
       "import": "./dist/advanced/public.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/public.d.ts",
+      "import": "./dist/runtime/public.js"
+    },
+    "./evals": {
+      "types": "./dist/evals/public.d.ts",
+      "import": "./dist/evals/public.js"
     }
   },
   "typesVersions": {
@@ -62,6 +70,12 @@
       ],
       "advanced": [
         "./dist/advanced/public.d.ts"
+      ],
+      "runtime": [
+        "./dist/runtime/public.d.ts"
+      ],
+      "evals": [
+        "./dist/evals/public.d.ts"
       ]
     }
   },
@@ -80,7 +94,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.99.0",
-    "@deepstrike/core": "0.2.71",
+    "@deepstrike/core": "0.2.72",
     "@google/generative-ai": "^0.24.1",
     "openai": "^7.5.0"
   },

package/dist/compat/anthropic/mcp.d.ts

@@ -1,15 +0,0 @@
-import type { MCPServer } from "../../mcp-server.js";
-/** spc_007 §3: minimal Anthropic/Claude-style MCP server config shape (the per-server object in
- *  a Claude Desktop-style `mcpServers` map — `{ command, args, env }`), not a live SDK type
- *  import — this adapter reads a serialized config (e.g.
- *  `__fixtures__/anthropic-mcp-config.json`). */
-export interface AnthropicMcpConfigJson {
-    name?: string;
-    command: string;
-    args?: string[];
-    env?: Record<string, string>;
-}
-/** Anthropic MCP config → DeepStrike `MCPServer` (spc_001-07). Anthropic's config format is
- *  always a subprocess launch (stdio transport) — there is no http/sse/custom variant to map
- *  from. Pure Surface→Surface mapping, produces only `MCPServer`. */
-export declare function fromAnthropicMcpConfig(json: AnthropicMcpConfigJson): MCPServer;

package/dist/compat/anthropic/mcp.js

@@ -1,10 +0,0 @@
-/** Anthropic MCP config → DeepStrike `MCPServer` (spc_001-07). Anthropic's config format is
- *  always a subprocess launch (stdio transport) — there is no http/sse/custom variant to map
- *  from. Pure Surface→Surface mapping, produces only `MCPServer`. */
-export function fromAnthropicMcpConfig(json) {
-    return {
-        name: json.name,
-        transport: { kind: "stdio", command: json.command, args: json.args },
-        ...(json.env ? { metadata: { env: json.env } } : {}),
-    };
-}

package/dist/compat/openai/agent.d.ts

@@ -1,34 +0,0 @@
-import { Agent } from "../../agent.js";
-/** spc_007 §2: minimal OpenAI Agents SDK agent-definition shape this adapter accepts. Field
- *  names/shape mirror the doc's §2 table left column, not any live OpenAI SDK type import — this
- *  adapter reads a serialized agent definition (e.g. `__fixtures__/openai-agent.json`), not a
- *  running SDK object. */
-export interface OpenAiAgentJson {
-    name: string;
-    instructions?: string;
-    model?: string;
-    tools?: Array<{
-        type?: string;
-        name: string;
-        description?: string;
-        parameters?: Record<string, unknown>;
-    }>;
-    handoffs?: Array<{
-        agent: string;
-        description?: string;
-    }>;
-    /** OpenAI-specific: no common `Agent` field for this (spc_007 §2's "Guardrails" row lowers to
-     *  governance policy, not a Canonical IR field) — preserved under `providerOptions.openai`
-     *  rather than silently dropped (spc_001 §3: "Unknown fields → never silently discarded"). */
-    guardrails?: unknown[];
-}
-/** spc_007 §2: OpenAI Agent → DeepStrike `Agent` (spc_001's Canonical Agent IR entry object).
- *  Pure Surface→Surface mapping — produces only `Agent`, never a Kernel-internal type
- *  (`Tcb`/`Capability`/etc.), matching this doc's own boundary ("Adapter 代码不得进入 Kernel
- *  crate").
- *
- *  A JSON tool definition carries no executable body, so each mapped tool's `execute` is a
- *  placeholder that throws — this adapter only reconstructs declarative shape (name/description/
- *  schema/count), never behavior; wiring a real implementation back onto an OpenAI-sourced tool
- *  definition is a separate, later concern outside this card. */
-export declare function fromOpenAiAgent(json: OpenAiAgentJson): Agent;

package/dist/compat/openai/agent.js

@@ -1,24 +0,0 @@
-import { Agent } from "../../agent.js";
-import { tool } from "../../tools/index.js";
-/** spc_007 §2: OpenAI Agent → DeepStrike `Agent` (spc_001's Canonical Agent IR entry object).
- *  Pure Surface→Surface mapping — produces only `Agent`, never a Kernel-internal type
- *  (`Tcb`/`Capability`/etc.), matching this doc's own boundary ("Adapter 代码不得进入 Kernel
- *  crate").
- *
- *  A JSON tool definition carries no executable body, so each mapped tool's `execute` is a
- *  placeholder that throws — this adapter only reconstructs declarative shape (name/description/
- *  schema/count), never behavior; wiring a real implementation back onto an OpenAI-sourced tool
- *  definition is a separate, later concern outside this card. */
-export function fromOpenAiAgent(json) {
-    const tools = (json.tools ?? []).map(t => tool(t.name, t.description ?? "", t.parameters ?? { type: "object", properties: {} }, async () => {
-        throw new Error(`tool "${t.name}" has no execution binding — fromOpenAiAgent only carries declarative shape`);
-    }));
-    return new Agent({
-        name: json.name,
-        instructions: json.instructions,
-        model: json.model,
-        tools,
-        handoffs: json.handoffs,
-        ...(json.guardrails ? { providerOptions: { openai: { guardrails: json.guardrails } } } : {}),
-    });
-}