@deepstrike/sdk 0.2.10 → 0.2.12

package/README.md

@@ -145,6 +145,44 @@ Spool, page-out, signals, processes, budgets, and memory events land in `Session
 
 ---
 
+## Dynamic workflows
+
+Instead of planning **and** executing a hard task in one long context window, hand the kernel a declarative DAG and let it spawn a fresh-context sub-agent per node. The kernel owns the control flow (gate · budget · suspend-on-join · resume); your SDK runs the agents. See the [top-level overview](../README.md#the-six-harness-patterns-as-first-class-kernel-nodes) for the full pattern catalog.
+
+```ts
+// One fresh-context verifier per rule (no inherited author context → can't rubber-stamp),
+// then a skeptic that reviews their flags. The kernel spawns the 3 verifiers as one gated
+// batch, suspends on the join, and runs the skeptic once they complete.
+const outcome = await runner.runWorkflow({
+  nodes: [
+    { task: "Rule: money is integer cents — violated?", role: "verify" },
+    { task: "Rule: all errors propagate — violated?",    role: "verify" },
+    { task: "Rule: timestamps are UTC — violated?",       role: "verify" },
+    { task: "Skeptic: which flags are real violations?",  role: "verify", dependsOn: [0, 1, 2] },
+  ],
+})
+// → { completed: ["wf-node0", … ], failed: [] }
+```
+
+A node's `kind` selects the control-flow shape; the same executor drives them all, every spawn passing the syscall gate:
+
+| Node `kind` | Behavior |
+|---|---|
+| `{ type: "spawn" }` (default) | Run the node's agent once |
+| `{ type: "loop", maxIters }` | Re-run until the agent signals it's done, capped at `maxIters` |
+| `{ type: "classify", branches }` | The classifier's result selects one branch; the rest are pruned |
+| `{ type: "tournament", entrants }` | Generate N entrants, then a pairwise-judge bracket to one winner |
+| `{ type: "reduce", reducer }` | **Tokenless host-compute** — a pure function (`dedupe_lines` / `merge_json_arrays` / `concat` / `count`, or your own via the `reducers` runner option) over the node's dependency outputs |
+
+### 0.2.11 capabilities
+
+- **Runtime fan-out** — give a node the `submitWorkflowNodesTool` and its agent can append nodes to the live DAG mid-run (true loop-until-done; one verifier per claim it discovers). Recorded and replayed on `resumeWorkflow`.
+- **Quarantine, no escape** — set `trust: "quarantined"` on a node that reads untrusted content; it's denied write-capable isolation in-kernel, and any nodes it submits are coerced to quarantined too (no privilege escalation).
+- **Structured output** — set `outputSchema` on a node; the runner instructs the agent, validates the result against the JSON-Schema subset, and re-runs once with the errors on mismatch. A node that never conforms fails (its dependents starve).
+- **Budget as signal** — with a `maxWorkflowNodes` / `maxConcurrentSubagents` quota installed, each spawned node's goal carries its remaining headroom so a coordinator can size its fan-out to fit.
+
+---
+
 ## Providers
 
 | Class | Backend | Notes |

package/dist/harness/harness.d.ts

@@ -26,6 +26,8 @@ export interface HarnessOutcome {
     overallScore?: number;
     feedback?: string;
     details?: CriterionResult[];
+    /** R3-1: nodes the agent submitted via `submit_workflow_nodes` while running under the harness. */
+    submittedNodes?: import("../types/agent.js").WorkflowNodeSpec[];
 }
 export interface Verdict {
     passed: boolean;
@@ -55,6 +57,9 @@ export type HarnessEvent = {
     callId: string;
     content: string;
     isError: boolean;
+} | {
+    type: "workflow_nodes_submitted";
+    nodes: import("../types/agent.js").WorkflowNodeSpec[];
 } | {
     type: "supervising";
 } | {

package/dist/harness/harness.js

@@ -61,8 +61,14 @@ export class HarnessLoop {
     }
     async run(request) {
         let last;
-        for await (const evt of this.stream(request))
+        // R3-1: collect nodes the agent submitted while running under the harness, so dynamic fan-out
+        // works in harness mode too (not just the plain streaming path).
+        const submittedNodes = [];
+        for await (const evt of this.stream(request)) {
             last = evt;
+            if (evt.type === "workflow_nodes_submitted")
+                submittedNodes.push(...evt.nodes);
+        }
         const done = last?.type === "done" ? last : undefined;
         return {
             result: "",
@@ -73,6 +79,7 @@ export class HarnessLoop {
             overallScore: done?.verdict.overallScore,
             feedback: done?.verdict.feedback,
             details: done?.verdict.details,
+            ...(submittedNodes.length ? { submittedNodes } : {}),
         };
     }
     async *stream(request) {
@@ -107,6 +114,10 @@ export class HarnessLoop {
                     const tr = evt;
                     yield { type: "tool_result", callId: tr.callId, content: tr.content, isError: tr.isError };
                 }
+                else if (evt.type === "workflow_nodes_submitted") {
+                    const ws = evt;
+                    yield { type: "workflow_nodes_submitted", nodes: ws.nodes };
+                }
                 else if (evt.type === "done") {
                     const d = evt;
                     lastIterations = d.iterations;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { RuntimeRunner, collectText } from "./runtime/runner.js";
 export type { RuntimeOptions, SchedulerBudget } from "./runtime/runner.js";
+export { builtinReducers, resolveReducer } from "./runtime/reducers.js";
+export type { Reducer, ReducerRegistry, ReducerInput } from "./runtime/reducers.js";
 export type { MemoryPolicy, MemoryWriteRateLimit, ResourceQuota } from "./kernel.js";
 export { KernelPrimitivesDashboard } from "./runtime/kernel-primitives-dashboard.js";
 export { FilteredExecutionPlane } from "./runtime/filtered-plane.js";
@@ -27,9 +29,10 @@ export { RemoteVpcPlane } from "./runtime/remote-vpc-plane.js";
 export type { RemoteVpcOptions } from "./runtime/remote-vpc-plane.js";
 export { AnthropicProvider } from "./providers/anthropic.js";
 export { OpenAIChatProvider, OpenAIProvider } from "./providers/openai.js";
-export { DeepSeekProvider } from "./providers/deepseek.js";
-export { KimiProvider } from "./providers/kimi.js";
-export { QwenProvider } from "./providers/qwen.js";
+export { DeepSeekProvider, DeepSeekAnthropicProvider } from "./providers/deepseek.js";
+export { KimiProvider, KimiAnthropicProvider } from "./providers/kimi.js";
+export { QwenProvider, QwenAnthropicProvider } from "./providers/qwen.js";
+export { GLMProvider, GLMAnthropicProvider } from "./providers/glm.js";
 export { GeminiProvider } from "./providers/gemini.js";
 export { MiniMaxAnthropicProvider, MiniMaxOpenAIProvider } from "./providers/minimax.js";
 export { OllamaProvider } from "./providers/ollama.js";
@@ -61,7 +64,7 @@ export { SinglePassHarness, EvalLoopHarness, HarnessLoop } from "./harness/harne
 export type { HarnessRequest, HarnessOutcome, HarnessLoopOptions, QualityGate } from "./harness/harness.js";
 export type { Message, ToolCall, ToolResult, ToolSchema, ContentPart, TextPart, ImagePart, AudioPart, StreamEvent, TextDelta, ThinkingDelta, ToolCallEvent, ToolChunk, ToolDeltaEvent, ToolSuspendEvent, ToolResultEvent, DoneEvent, ErrorEvent, PermissionRequestEvent, PermissionResolvedEvent, PermissionResponse, LLMProvider, RetryConfig, TokenUsage, ProviderToolSpec, ProviderRunState, ProviderReplay, RenderedContext, ReplayabilityAssessment, } from "./types.js";
 export type { AgentCapabilityFilter, AgentIdentity, AgentIsolation, AgentRunSpec, AgentProcessChangedObservation, ContextInheritance, KernelAgentRole, LoopResult, MilestoneCheckResult, MilestoneContract, MilestonePhase, MilestonePolicy, SubAgentResult, TerminationReason, WorkflowSpec, WorkflowNodeSpec, WorkflowTaskSpec, WorkflowSpawnInfo, } from "./types/agent.js";
-export { agentIdentitySub, agentRunSpecToKernel, milestoneCheckFail, milestoneCheckPass, milestoneCheckResultToKernel, subAgentResultToKernel, workflowSpecToKernel, fanoutSynthesize, generateAndFilter, verifyRules, } from "./types/agent.js";
+export { agentIdentitySub, agentRunSpecToKernel, milestoneCheckFail, milestoneCheckPass, milestoneCheckResultToKernel, subAgentResultToKernel, workflowSpecToKernel, workflowNodeSpecToKernel, submitWorkflowNodesToKernel, submitWorkflowNodesTool, fanoutSynthesize, generateAndFilter, verifyRules, } from "./types/agent.js";
 export type { AcceptanceCriterion, VerificationContract, ContractCheckResult, } from "./collaboration/contract.js";
 export { ContractBuilder, formatContractForSystemPrompt, contractToCriteriaStrings, } from "./collaboration/contract.js";
 export { AgentPool } from "./collaboration/pool.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 // ── Runtime (Layer 1.5) ────────────────────────────────────────────────────
 export { RuntimeRunner, collectText } from "./runtime/runner.js";
+export { builtinReducers, resolveReducer } from "./runtime/reducers.js";
 export { KernelPrimitivesDashboard } from "./runtime/kernel-primitives-dashboard.js";
 export { FilteredExecutionPlane } from "./runtime/filtered-plane.js";
 export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "./runtime/sub-agent-orchestrator.js";
@@ -16,9 +17,10 @@ export { RemoteVpcPlane } from "./runtime/remote-vpc-plane.js";
 // ── Providers ─────────────────────────────────────────────────────────────
 export { AnthropicProvider } from "./providers/anthropic.js";
 export { OpenAIChatProvider, OpenAIProvider } from "./providers/openai.js";
-export { DeepSeekProvider } from "./providers/deepseek.js";
-export { KimiProvider } from "./providers/kimi.js";
-export { QwenProvider } from "./providers/qwen.js";
+export { DeepSeekProvider, DeepSeekAnthropicProvider } from "./providers/deepseek.js";
+export { KimiProvider, KimiAnthropicProvider } from "./providers/kimi.js";
+export { QwenProvider, QwenAnthropicProvider } from "./providers/qwen.js";
+export { GLMProvider, GLMAnthropicProvider } from "./providers/glm.js";
 export { GeminiProvider } from "./providers/gemini.js";
 export { MiniMaxAnthropicProvider, MiniMaxOpenAIProvider } from "./providers/minimax.js";
 export { OllamaProvider } from "./providers/ollama.js";
@@ -41,7 +43,7 @@ export { PermissionManager, PermissionMode } from "./safety/permissions.js";
 export { Governance, governancePolicyToKernelEvent } from "./governance.js";
 // ── Harness ────────────────────────────────────────────────────────────────
 export { SinglePassHarness, EvalLoopHarness, HarnessLoop } from "./harness/harness.js";
-export { agentIdentitySub, agentRunSpecToKernel, milestoneCheckFail, milestoneCheckPass, milestoneCheckResultToKernel, subAgentResultToKernel, workflowSpecToKernel, fanoutSynthesize, generateAndFilter, verifyRules, } from "./types/agent.js";
+export { agentIdentitySub, agentRunSpecToKernel, milestoneCheckFail, milestoneCheckPass, milestoneCheckResultToKernel, subAgentResultToKernel, workflowSpecToKernel, workflowNodeSpecToKernel, submitWorkflowNodesToKernel, submitWorkflowNodesTool, fanoutSynthesize, generateAndFilter, verifyRules, } from "./types/agent.js";
 export { ContractBuilder, formatContractForSystemPrompt, contractToCriteriaStrings, } from "./collaboration/contract.js";
 export { AgentPool } from "./collaboration/pool.js";
 export { KERNEL_ROLE_MAP } from "./collaboration/pool.js";

package/dist/providers/anthropic.d.ts

@@ -20,6 +20,13 @@ export declare class AnthropicProvider implements LLMProvider {
     descriptor(): ProviderDescriptor;
     peekProviderReplay(message: Pick<Message, "content" | "toolCalls">): ProviderReplay | undefined;
     seedProviderReplay(message: Pick<Message, "content" | "toolCalls">, replay: ProviderReplay): void;
+    /**
+     * Build tool definitions. A cache breakpoint is anchored on the final tool
+     * only when the system blocks won't carry one (`anchorCache`). When structured
+     * system blocks are present, their breakpoints already cache the tools prefix
+     * (tools render before system), so a redundant tool breakpoint would only burn
+     * one of Anthropic's 4 cache_control slots — slots the message history needs.
+     */
     private buildTools;
     complete(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>): Promise<Message>;
     stream(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>): AsyncIterable<StreamEvent>;

package/dist/providers/anthropic.js

@@ -1,7 +1,7 @@
 import Anthropic from "@anthropic-ai/sdk";
 import { assistantReplayKey } from "../runtime/provider-replay.js";
 import { withServerRuntimeGuard } from "../runtime/server.js";
-import { CircuitBreaker, normalizeToolCall, omitExtensionKeys, toAnthropicMessages } from "./base.js";
+import { CircuitBreaker, normalizeToolCall, omitExtensionKeys, toAnthropicContent, toAnthropicMessages } from "./base.js";
 const CLAUDE_POLICIES = {
     "claude-opus-4-1": { maxTurns: 50 },
     "claude-opus-4-7": { maxTurns: 50 },
@@ -70,12 +70,19 @@ export class AnthropicProvider {
         if (blocks.length)
             this.nativeAssistantBlocks.set(assistantReplayKey(message), blocks);
     }
-    buildTools(tools) {
+    /**
+     * Build tool definitions. A cache breakpoint is anchored on the final tool
+     * only when the system blocks won't carry one (`anchorCache`). When structured
+     * system blocks are present, their breakpoints already cache the tools prefix
+     * (tools render before system), so a redundant tool breakpoint would only burn
+     * one of Anthropic's 4 cache_control slots — slots the message history needs.
+     */
+    buildTools(tools, anchorCache) {
         return tools.map((t, i) => ({
             name: t.name,
             description: t.description,
             input_schema: JSON.parse(t.parameters),
-            ...(i === tools.length - 1 ? { cache_control: { type: "ephemeral" } } : {}),
+            ...(anchorCache && i === tools.length - 1 ? { cache_control: { type: "ephemeral" } } : {}),
         }));
     }
     async complete(context, tools, extensions) {
@@ -83,6 +90,7 @@ export class AnthropicProvider {
             throw new Error("Circuit breaker open");
         const system = this.buildSystem(context);
         const msgs = this.buildMessages(context);
+        assertCacheBudget(system, tools.length);
         const requestExtensions = this.requestExtensions(extensions);
         let lastErr;
         for (let i = 0; i < this.maxRetries; i++) {
@@ -93,7 +101,7 @@ export class AnthropicProvider {
                     max_tokens: typeof extensions?.max_tokens === "number" ? extensions.max_tokens : 8096,
                     ...(system ? { system } : {}),
                     messages: msgs,
-                    ...(tools.length ? { tools: this.buildTools(tools) } : {}),
+                    ...(tools.length ? { tools: this.buildTools(tools, !Array.isArray(system)) } : {}),
                 }, extensions);
                 this.circuit.recordSuccess();
                 let content = "";
@@ -123,6 +131,7 @@ export class AnthropicProvider {
     async *stream(context, tools, extensions) {
         const system = this.buildSystem(context);
         const msgs = this.buildMessages(context);
+        assertCacheBudget(system, tools.length);
         const requestExtensions = this.requestExtensions(extensions);
         const toolBlocks = {};
         const nativeBlocks = {};
@@ -134,17 +143,36 @@ export class AnthropicProvider {
             max_tokens: typeof extensions?.max_tokens === "number" ? extensions.max_tokens : 8096,
             ...(system ? { system } : {}),
             messages: msgs,
-            ...(tools.length ? { tools: this.buildTools(tools) } : {}),
+            ...(tools.length ? { tools: this.buildTools(tools, !Array.isArray(system)) } : {}),
         }, extensions);
-        let totalTokens = 0;
+        let uncachedInput = 0;
+        let cacheReadTokens = 0;
+        let cacheCreationTokens = 0;
+        let outputTokens = 0;
         for await (const evt of stream) {
             if (evt.type === "message_start" || evt.type === "message_delta") {
                 const usage = evt.usage ?? evt.message?.usage;
                 if (usage) {
-                    const inputTokens = usage.input_tokens ?? 0;
-                    const outputTokens = usage.output_tokens ?? 0;
-                    totalTokens = inputTokens + outputTokens;
-                    yield { type: "usage", totalTokens, inputTokens, outputTokens };
+                    // input + cache counts are cumulative and pinned at message_start; a
+                    // later message_delta may omit them (null), so Math.max keeps the
+                    // running totals from being clobbered back to zero.
+                    uncachedInput = Math.max(uncachedInput, usage.input_tokens ?? 0);
+                    cacheReadTokens = Math.max(cacheReadTokens, usage.cache_read_input_tokens ?? 0);
+                    cacheCreationTokens = Math.max(cacheCreationTokens, usage.cache_creation_input_tokens ?? 0);
+                    outputTokens = Math.max(outputTokens, usage.output_tokens ?? 0);
+                    // inputTokens is the FULL prompt size (uncached + cache read + cache
+                    // write). The kernel reads it as the authoritative prompt size for
+                    // context-pressure/compaction — excluding cached tokens would make a
+                    // cache-heavy turn look tiny and suppress compaction until a 413.
+                    const inputTokens = uncachedInput + cacheReadTokens + cacheCreationTokens;
+                    yield {
+                        type: "usage",
+                        totalTokens: inputTokens + outputTokens,
+                        inputTokens,
+                        outputTokens,
+                        cacheReadInputTokens: cacheReadTokens,
+                        cacheCreationInputTokens: cacheCreationTokens,
+                    };
                 }
             }
             else if (evt.type === "content_block_start") {
@@ -206,6 +234,12 @@ export class AnthropicProvider {
             : this.client.messages.stream(params));
     }
     buildSystem(context) {
+        // B3 note: the system shape is content-driven — 0 blocks (string), 1 block
+        // (stable only), or 2 blocks (stable + knowledge). The first turn `systemKnowledge`
+        // appears, the block count rises 1→2, which is a one-time prompt-cache invalidation
+        // (the knowledge prefix didn't exist to cache before). It is byte-stable thereafter;
+        // dynamic per-turn knowledge belongs in the uncached tail, not this block. An empty
+        // knowledge string is intentionally never emitted (the API rejects empty text blocks).
         if (!context.systemStable && !context.systemKnowledge) {
             return context.systemText || undefined;
         }
@@ -220,6 +254,18 @@ export class AnthropicProvider {
     }
     buildMessages(context) {
         const msgs = toAnthropicMessages(context.turns, message => this.nativeAssistantBlocks.get(assistantReplayKey(message)));
+        // Cache breakpoints anchor on the stable history; the volatile State turn is
+        // appended AFTER them as the uncached tail (so the history prefix re-reads
+        // across turns). On un-rebuilt bindings stateTurn is absent and the state is
+        // already inside `turns` — rendered as-is above. `frozenPrefixLen` (P1-E) pins
+        // the deep breakpoint at the compaction boundary; absent ⇒ rolling-pair fallback.
+        applyMessageCacheControl(msgs, context.frozenPrefixLen);
+        if (context.stateTurn) {
+            msgs.push({
+                role: context.stateTurn.role === "assistant" ? "assistant" : "user",
+                content: toAnthropicContent(context.stateTurn),
+            });
+        }
         if (msgs.length === 0) {
             msgs.push({ role: "user", content: "Proceed." });
         }
@@ -233,6 +279,79 @@ export class AnthropicProvider {
         this.nativeAssistantBlocks.set(assistantReplayKey(message), blocks);
     }
 }
+/** Anthropic accepts at most this many cache_control breakpoints per request. */
+const MAX_CACHE_BREAKPOINTS = 4;
+/**
+ * Number of rolling cache breakpoints to spend on the message history. Anthropic
+ * allows 4 cache_control breakpoints total; the static system/tools prefix
+ * consumes up to 2 (systemStable + systemKnowledge), leaving 2 for the history.
+ */
+const MESSAGE_CACHE_BREAKPOINTS = 2;
+/**
+ * Regression guard: fail loudly if the static (system + tools) breakpoints plus
+ * the rolling message budget could exceed Anthropic's hard limit, instead of
+ * letting the API reject the request with an opaque 400. Uses the worst-case
+ * message count (`MESSAGE_CACHE_BREAKPOINTS`), so it can only fire if a future
+ * change adds a system partition or raises the message budget.
+ */
+function assertCacheBudget(system, toolCount) {
+    const systemBreakpoints = Array.isArray(system) ? system.length : 0;
+    const toolBreakpoints = toolCount > 0 && !Array.isArray(system) ? 1 : 0;
+    const worstCase = systemBreakpoints + toolBreakpoints + MESSAGE_CACHE_BREAKPOINTS;
+    if (worstCase > MAX_CACHE_BREAKPOINTS) {
+        throw new Error(`Anthropic cache_control budget exceeded: ${systemBreakpoints} system + ${toolBreakpoints} tool + ${MESSAGE_CACHE_BREAKPOINTS} message > ${MAX_CACHE_BREAKPOINTS}`);
+    }
+}
+/**
+ * Place the (≤2) message-history cache breakpoints. The final message always gets
+ * one — it writes the current full prefix for the next turn to read. The second is
+ * placed by one of two strategies:
+ *
+ *   • **Deep anchor (P1-E)** — when `frozenPrefixLen` marks a distinct frozen prefix
+ *     (the compaction boundary), pin the second breakpoint there. It is byte-stable
+ *     across turns, so `[0..frozen]` is re-read cheaply every turn and is immune to
+ *     the 20-block lookback miss that strikes heavy tool turns (>20 blocks/turn); the
+ *     tail breakpoint then writes only the incremental `[frozen..tail]`.
+ *   • **Rolling fallback** — otherwise (older binding / no compaction yet / whole
+ *     render hot), roll the second breakpoint to the nearest preceding user turn, the
+ *     previous turn's read anchor (Anthropic's 20-block lookback bridges light turns).
+ *
+ * Without any of this the cached prefix stops at the end of `system` and every turn
+ * re-bills the entire tool-result history at full price (~quadratic cumulative cost).
+ * cache_control attaches to the last content block of each target, promoting a bare
+ * string body to a text block.
+ */
+function applyMessageCacheControl(msgs, frozenPrefixLen) {
+    if (!msgs.length)
+        return;
+    const targets = new Set([msgs.length - 1]);
+    if (typeof frozenPrefixLen === "number" && frozenPrefixLen >= 1 && frozenPrefixLen < msgs.length) {
+        // Deep anchor at the frozen-prefix boundary (last frozen turn). Fixed between compactions.
+        targets.add(frozenPrefixLen - 1);
+    }
+    else {
+        for (let i = msgs.length - 2; i >= 0 && targets.size < MESSAGE_CACHE_BREAKPOINTS; i--) {
+            if (msgs[i].role === "user")
+                targets.add(i);
+        }
+    }
+    for (const idx of targets)
+        markLastBlockCacheable(msgs[idx]);
+}
+/** Attach an ephemeral cache breakpoint to a message's final content block. */
+function markLastBlockCacheable(msg) {
+    const cache_control = { type: "ephemeral" };
+    if (typeof msg.content === "string") {
+        if (!msg.content)
+            return; // don't synthesize an empty (API-rejected) text block
+        msg.content = [{ type: "text", text: msg.content, cache_control }];
+        return;
+    }
+    if (Array.isArray(msg.content) && msg.content.length) {
+        const last = msg.content[msg.content.length - 1];
+        last.cache_control = cache_control;
+    }
+}
 /**
  * Reconstruct Anthropic assistant content blocks from a neutral transcript when
  * no provider replay was persisted. Only meaningful for tool-use turns: a plain

package/dist/providers/base.d.ts

@@ -16,12 +16,50 @@ export declare class CircuitBreaker {
  */
 export declare const INTERNAL_EXTENSION_KEYS: readonly string[];
 export declare function omitExtensionKeys(extensions: Record<string, unknown> | undefined, keys: readonly string[]): Record<string, unknown>;
+/**
+ * Cached-prompt-token count from an OpenAI-compatible usage object. Covers the
+ * standard `prompt_tokens_details.cached_tokens` (OpenAI, Qwen, MiniMax, GLM,
+ * Kimi) and DeepSeek's `prompt_cache_hit_tokens`. These caches bill reads only,
+ * so there is no separate cache-creation count. The figure is a subset of
+ * `prompt_tokens` (the full prompt), surfaced for cost visibility — it must not
+ * be subtracted from the input count the kernel uses for context accounting.
+ */
+export declare function openAICachedPromptTokens(usage: unknown): number;
+/**
+ * Prompt-cache hit rate for one usage record: the fraction of the full prompt
+ * served from cache this request (`cacheReadInputTokens / inputTokens`, clamped to
+ * [0,1]). Returns 0 when the prompt size is unknown. This is the headline metric
+ * for the prefix-cache work (P0-A) — across a long, append-only session it should
+ * climb and stay high; a sustained drop means the cacheable prefix is drifting.
+ */
+export declare function cacheHitRate(usage: {
+    inputTokens?: number;
+    cacheReadInputTokens?: number;
+}): number;
+/**
+ * Deterministic short key for OpenAI's `prompt_cache_key` — groups requests that
+ * share a cacheable prefix (same system prompt + tool set) onto the same cache
+ * routing, improving automatic prefix-cache hit rates without any caller input.
+ * FNV-1a over the parts; stable across processes, no crypto dependency.
+ */
+export declare function stablePromptCacheKey(parts: string[]): string;
 export declare function normalizeToolCall(id: string, name: string, args: unknown): {
     id: string;
     name: string;
     arguments: string;
 } | null;
 export declare function toAnthropicContent(msg: Message): string | Array<Record<string, unknown>>;
+/**
+ * History turns with the volatile State turn appended as the latest turn, for
+ * providers that render it inline (OpenAI-family, Gemini, Ollama). Appending
+ * (rather than prepending) keeps the history a byte-stable prefix so these
+ * providers' automatic prefix caches (OpenAI / Gemini implicit / Ollama KV) hit
+ * across turns — the volatile state is the uncached tail. Anthropic does the
+ * equivalent explicitly (append after the cache breakpoint — see
+ * AnthropicProvider.buildMessages). When `stateTurn` is absent (un-rebuilt
+ * binding) the State turn is still inside `turns`, so this returns `turns` as-is.
+ */
+export declare function turnsWithStateAppended(context: RenderedContext): Message[];
 /** Convert RenderedContext.turns to Anthropic messages array.
  *  `turns` contains only user / assistant / tool roles — no system filtering needed. */
 export declare function toAnthropicMessages(turns: Message[], nativeReplay?: (message: Message) => Array<Record<string, unknown>> | undefined): Array<Record<string, unknown>>;

package/dist/providers/catalog.js

@@ -1,12 +1,12 @@
 import { AnthropicProvider } from "./anthropic.js";
 import { OpenAIChatProvider } from "./openai.js";
-import { DeepSeekProvider } from "./deepseek.js";
-import { KimiProvider } from "./kimi.js";
+import { DeepSeekProvider, DeepSeekAnthropicProvider } from "./deepseek.js";
+import { KimiProvider, KimiAnthropicProvider } from "./kimi.js";
 import { OpenAIResponsesProvider } from "./openai-responses.js";
 import { MiniMaxAnthropicProvider, MiniMaxOpenAIProvider } from "./minimax.js";
-import { QwenProvider } from "./qwen.js";
+import { QwenProvider, QwenAnthropicProvider } from "./qwen.js";
 import { GeminiProvider } from "./gemini.js";
-import { GLMProvider } from "./glm.js";
+import { GLMProvider, GLMAnthropicProvider } from "./glm.js";
 import { endpointProfiles, getModelProfile, modelProfiles } from "./profiles.js";
 export function createProvider(options) {
     const profile = isModelProfileId(options.model) ? getModelProfile(options.model) : undefined;
@@ -48,18 +48,30 @@ export function createProvider(options) {
     if (providerId === "minimax" && endpoint.protocol === "openai-chat") {
         return new MiniMaxOpenAIProvider(options.apiKey, model, options.retry, baseURL);
     }
+    if (providerId === "deepseek" && endpoint.protocol === "anthropic-messages") {
+        return new DeepSeekAnthropicProvider(options.apiKey, model, options.retry, baseURL);
+    }
     if (providerId === "deepseek" && endpoint.protocol === "openai-chat") {
         return new DeepSeekProvider(options.apiKey, model, options.retry, baseURL);
     }
+    if (providerId === "kimi" && endpoint.protocol === "anthropic-messages") {
+        return new KimiAnthropicProvider(options.apiKey, model, options.retry, baseURL);
+    }
     if (providerId === "kimi" && endpoint.protocol === "openai-chat") {
         return new KimiProvider(options.apiKey, model, options.retry, baseURL);
     }
+    if (providerId === "qwen" && endpoint.protocol === "anthropic-messages") {
+        return new QwenAnthropicProvider(options.apiKey, model, options.retry, baseURL);
+    }
     if (providerId === "qwen" && endpoint.protocol === "openai-chat") {
         return new QwenProvider(options.apiKey, model, options.retry, baseURL);
     }
     if (providerId === "gemini" && endpoint.protocol === "gemini") {
         return new GeminiProvider(options.apiKey, model, options.retry, baseURL);
     }
+    if (providerId === "glm" && endpoint.protocol === "anthropic-messages") {
+        return new GLMAnthropicProvider(options.apiKey, model, options.retry, baseURL);
+    }
     if (providerId === "glm" && endpoint.protocol === "openai-chat") {
         return new GLMProvider(options.apiKey, model, options.retry, baseURL);
     }
@@ -82,11 +94,11 @@ function defaultEndpointForProvider(providerId) {
         anthropic: "anthropic.messages",
         openai: "openai.chat",
         minimax: "minimax.anthropic",
-        deepseek: "deepseek.openai",
-        kimi: "kimi.openai",
-        qwen: "qwen.dashscope",
+        deepseek: "deepseek.anthropic",
+        kimi: "kimi.anthropic",
+        qwen: "qwen.anthropic",
         gemini: "gemini.google",
-        glm: "glm.openai",
+        glm: "glm.anthropic",
     };
     return defaults[providerId];
 }

package/dist/providers/deepseek.d.ts

@@ -1,5 +1,17 @@
 import type { Message, ProviderDescriptor, RenderedContext, ToolSchema, StreamEvent, RuntimePolicy } from "../types.js";
+import { AnthropicProvider } from "./anthropic.js";
 import { OpenAIChatProvider } from "./openai.js";
+/**
+ * DeepSeek over its Anthropic-compatible endpoint.
+ */
+export declare class DeepSeekAnthropicProvider extends AnthropicProvider {
+    constructor(apiKey: string, model?: string, retry?: {
+        maxRetries: number;
+        baseDelay: number;
+    }, baseURL?: string);
+    protected providerName(): string;
+    runtimePolicy(): RuntimePolicy;
+}
 export declare class DeepSeekProvider extends OpenAIChatProvider {
     constructor(apiKey: string, model?: string, retry?: {
         maxRetries: number;

package/dist/providers/deepseek.js

@@ -1,15 +1,32 @@
+import { AnthropicProvider } from "./anthropic.js";
 import { OpenAIChatProvider } from "./openai.js";
 import { endpointProfiles } from "./profiles.js";
-import { omitExtensionKeys } from "./base.js";
-const DEEPSEEK_BASE = endpointProfiles["deepseek.openai"].baseURL;
+import { omitExtensionKeys, openAICachedPromptTokens } from "./base.js";
 const DEEPSEEK_POLICIES = {
     "deepseek-chat": { maxTurns: 25 },
     "deepseek-reasoner": { maxTurns: 50 },
     "deepseek-v4-flash": { maxTurns: 20 },
     "deepseek-v4-pro": { maxTurns: 35 },
 };
+/**
+ * DeepSeek over its Anthropic-compatible endpoint.
+ */
+export class DeepSeekAnthropicProvider extends AnthropicProvider {
+    constructor(apiKey, model = "deepseek-v4-flash", retry, baseURL = endpointProfiles["deepseek.anthropic"].baseURL) {
+        super(apiKey, model, retry, {
+            baseURL,
+            authMode: "api-key",
+        });
+    }
+    providerName() {
+        return "deepseek";
+    }
+    runtimePolicy() {
+        return DEEPSEEK_POLICIES[this.model] ?? {};
+    }
+}
 export class DeepSeekProvider extends OpenAIChatProvider {
-    constructor(apiKey, model = "deepseek-v4-flash", retry, baseURL = DEEPSEEK_BASE) {
+    constructor(apiKey, model = "deepseek-v4-flash", retry, baseURL = endpointProfiles["deepseek.openai"].baseURL) {
         super(apiKey, model, retry, baseURL);
     }
     runtimePolicy() {
@@ -103,11 +120,13 @@ export class DeepSeekProvider extends OpenAIChatProvider {
         let totalTokens = 0;
         let inputTokens = 0;
         let outputTokens = 0;
+        let cacheReadTokens = 0;
         for await (const chunk of stream) {
             if (chunk.usage) {
                 totalTokens = chunk.usage.total_tokens;
                 inputTokens = chunk.usage.prompt_tokens ?? 0;
                 outputTokens = chunk.usage.completion_tokens ?? 0;
+                cacheReadTokens = openAICachedPromptTokens(chunk.usage);
                 continue;
             }
             const choice = chunk.choices[0];
@@ -173,7 +192,7 @@ export class DeepSeekProvider extends OpenAIChatProvider {
             yield { type: "tool_call", id: tb.id, name: tb.name, arguments: args };
         }
         if (totalTokens > 0)
-            yield { type: "usage", totalTokens, inputTokens, outputTokens };
+            yield { type: "usage", totalTokens, inputTokens, outputTokens, ...(cacheReadTokens > 0 ? { cacheReadInputTokens: cacheReadTokens } : {}) };
     }
     rememberDeepSeekReplay(content, toolCalls, reasoningContent, nativeToolCalls) {
         if (typeof reasoningContent !== "string" || !reasoningContent.trim())