@deepstrike/sdk 0.2.21 → 0.2.23

package/dist/governance.d.ts

@@ -29,7 +29,28 @@ export interface GovernancePolicy {
         windowMs: number;
     }[];
     constraints?: GovernanceConstraint[];
+    /** I5: when true (default), the runner pre-filters denied tools out of the schema passed to the
+     *  provider — the model never sees them and never tries to call them, eliminating the rollback
+     *  turn the kernel would otherwise produce. The denied tool names are also surfaced as a single
+     *  line on the system slot so the model knows not to plan around them. Set to false to fall
+     *  back to the v0.2.22 rollback-based behavior (useful for measuring the delta or when the
+     *  agent should learn the denial via a real attempt). */
+    surfaceDeniedInSystem?: boolean;
 }
+/** I5: walk the tool list and bucket each tool into `allowed` / `denied` based on a declarative
+ *  policy. A tool is denied when:
+ *    - the tool name appears in `vetoes`
+ *    - a `rules[i].pattern` matches the tool name and the rule's `action === "deny"`
+ *    - or `defaultAction === "deny"` and no `allow` rule matches
+ *  `ask_user` is treated as allowed at the schema layer — the runtime decides at call time.
+ *  Pattern matching is exact match or a glob with a single trailing `*` (so `"write_*"` denies
+ *  `write_file` and `write_db`). Pure — no side effects. */
+export declare function governanceFilterSchema<T extends {
+    name: string;
+}>(tools: T[], policy: GovernancePolicy | undefined): {
+    allowed: T[];
+    denied: string[];
+};
 export type GovernanceConstraint = {
     kind: "required";
     tool: string;

package/dist/governance.js

@@ -32,6 +32,38 @@ export class Governance {
         return this.inner.evaluate(toolName, argsJson);
     }
 }
+/** I5: walk the tool list and bucket each tool into `allowed` / `denied` based on a declarative
+ *  policy. A tool is denied when:
+ *    - the tool name appears in `vetoes`
+ *    - a `rules[i].pattern` matches the tool name and the rule's `action === "deny"`
+ *    - or `defaultAction === "deny"` and no `allow` rule matches
+ *  `ask_user` is treated as allowed at the schema layer — the runtime decides at call time.
+ *  Pattern matching is exact match or a glob with a single trailing `*` (so `"write_*"` denies
+ *  `write_file` and `write_db`). Pure — no side effects. */
+export function governanceFilterSchema(tools, policy) {
+    if (!policy)
+        return { allowed: tools, denied: [] };
+    const vetoes = new Set(policy.vetoes ?? []);
+    const allowed = [];
+    const denied = [];
+    const matches = (pat, name) => pat === name || (pat.endsWith("*") && name.startsWith(pat.slice(0, -1)));
+    for (const tool of tools) {
+        if (vetoes.has(tool.name)) {
+            denied.push(tool.name);
+            continue;
+        }
+        let action = policy.defaultAction ?? "allow";
+        for (const r of policy.rules ?? []) {
+            if (matches(r.pattern, tool.name))
+                action = r.action;
+        }
+        if (action === "deny")
+            denied.push(tool.name);
+        else
+            allowed.push(tool);
+    }
+    return { allowed, denied };
+}
 /**
  * Convert a declarative {@link GovernancePolicy} into the `load_governance_policy`
  * kernel event payload (snake_case wire fields). Pure — no side effects.

package/dist/harness/harness.d.ts

@@ -5,6 +5,14 @@ export interface Criterion {
     text: string;
     required: boolean;
     weight?: number;
+    /** I3.3 (A4): optional stable identifier from the host's contract layer (e.g. an
+     *  `acceptance[].id` field). The harness does not interpret it; it just threads it through to
+     *  `verdictFn` so the host can dispatch per-criterion deterministic checks by id. */
+    id?: string;
+    /** I3.3 (A4): host hint — when true, the host has a deterministic check for this criterion
+     *  and would short-circuit the LLM eval. The harness still defers to the host's `verdictFn`
+     *  for the actual decision; this is purely a transparency field on the request. */
+    machineCheckable?: boolean;
 }
 export interface CriterionResult {
     criterion: string;
@@ -83,6 +91,14 @@ export declare class SinglePassHarness {
     run(request: HarnessRequest): Promise<HarnessOutcome>;
     stream(request: HarnessRequest): AsyncIterable<StreamEvent>;
 }
+/**
+ * @deprecated I3.4 (A1): prefer {@link HarnessLoop} with `verdictFn` for host-defined judgment.
+ * `EvalLoopHarness.stream()` does NOT honor the `gate` passed via `request.gate` (only `.run()`
+ * does), which is a long-standing footgun for streaming hosts. `HarnessLoop` runs the eval loop
+ * uniformly across both stream and run, accepts an optional `verdictFn` for short-circuiting the
+ * built-in LLM eval, and otherwise mirrors `EvalLoopHarness`'s behavior. New code should use
+ * `HarnessLoop`; existing call sites can migrate by switching the class + (if applicable)
+ * passing a `verdictFn` for the same gate logic. Slated for removal in a future major. */
 export declare class EvalLoopHarness {
     private runner;
     private gate;
@@ -91,15 +107,29 @@ export declare class EvalLoopHarness {
     run(request: HarnessRequest): Promise<HarnessOutcome>;
     stream(request: HarnessRequest): AsyncIterable<StreamEvent>;
 }
+/** I3.2 (A2/A3): host-supplied judgment for each attempt's result. Returning a `Verdict` short-
+ *  circuits the built-in LLM eval (no `evalProvider.stream` call); returning `undefined` defers to
+ *  the built-in eval (enables hybrid judgment: machine-checkable items deterministic, subjective
+ *  items LLM). Pure addition — when not set, HarnessLoop.stream() is byte-equivalent to its prior
+ *  behavior. The closure owns its own context (doc reader, deterministic checks, etc.); the SDK
+ *  is intentionally agnostic about what it inspects. */
+export type VerdictFn = (ctx: {
+    goal: string;
+    criteria: Criterion[];
+    attempt: number;
+    result: string;
+}) => Verdict | undefined | Promise<Verdict | undefined>;
 export interface HarnessLoopOptions {
     maxAttempts?: number;
     skillDir?: string;
+    verdictFn?: VerdictFn;
 }
 export declare class HarnessLoop {
     private runner;
     private evalProvider;
     private maxAttempts;
     private skillDir?;
+    private verdictFn?;
     constructor(runner: RuntimeRunner, evalProvider: import("../types.js").LLMProvider, options?: HarnessLoopOptions);
     run(request: HarnessRequest): Promise<HarnessOutcome>;
     stream(request: HarnessRequest): AsyncIterable<HarnessEvent>;

package/dist/harness/harness.js

@@ -26,6 +26,14 @@ export class SinglePassHarness {
         yield* this.runner.run({ sessionId: crypto.randomUUID(), goal: request.goal, criteria: request.criteria?.map(c => c.text), extensions: request.extensions });
     }
 }
+/**
+ * @deprecated I3.4 (A1): prefer {@link HarnessLoop} with `verdictFn` for host-defined judgment.
+ * `EvalLoopHarness.stream()` does NOT honor the `gate` passed via `request.gate` (only `.run()`
+ * does), which is a long-standing footgun for streaming hosts. `HarnessLoop` runs the eval loop
+ * uniformly across both stream and run, accepts an optional `verdictFn` for short-circuiting the
+ * built-in LLM eval, and otherwise mirrors `EvalLoopHarness`'s behavior. New code should use
+ * `HarnessLoop`; existing call sites can migrate by switching the class + (if applicable)
+ * passing a `verdictFn` for the same gate logic. Slated for removal in a future major. */
 export class EvalLoopHarness {
     runner;
     gate;
@@ -53,11 +61,13 @@ export class HarnessLoop {
     evalProvider;
     maxAttempts;
     skillDir;
+    verdictFn;
     constructor(runner, evalProvider, options = {}) {
         this.runner = runner;
         this.evalProvider = evalProvider;
         this.maxAttempts = options.maxAttempts ?? 3;
         this.skillDir = options.skillDir;
+        this.verdictFn = options.verdictFn;
     }
     async run(request) {
         let last;
@@ -125,28 +135,38 @@ export class HarnessLoop {
                 }
             }
             yield { type: "supervising" };
-            // #6 (0.5.0): the eval/verdict compute is the kernel's stateless free functions (was the
-            // EvalPipeline state machine). Build the eval prompt, call the eval LLM, parse the verdict.
-            const evalMsgs = kernel.buildEvalMessages(request.goal, criteria, lastResult, attempt, true);
-            let evalText = "";
-            const evalContext = {
-                systemText: evalMsgs.filter((m) => m.role === "system").map((m) => m.content).join("\n\n"),
-                turns: evalMsgs.filter((m) => m.role !== "system"),
-            };
-            for await (const evt of this.evalProvider.stream(evalContext, [], undefined)) {
-                if (evt.type === "text_delta")
-                    evalText += evt.delta;
+            // I3.2 (A2/A3): host-supplied `verdictFn` short-circuits the LLM eval. When it returns a
+            // Verdict, use it; when it returns undefined, defer to the built-in eval (hybrid path).
+            let verdict;
+            let skillCandidate;
+            if (this.verdictFn) {
+                verdict = await this.verdictFn({ goal: request.goal, criteria, attempt, result: lastResult });
+            }
+            if (!verdict) {
+                // #6 (0.5.0): the eval/verdict compute is the kernel's stateless free functions (was the
+                // EvalPipeline state machine). Build the eval prompt, call the eval LLM, parse the verdict.
+                const evalMsgs = kernel.buildEvalMessages(request.goal, criteria, lastResult, attempt, true);
+                let evalText = "";
+                const evalContext = {
+                    systemText: evalMsgs.filter((m) => m.role === "system").map((m) => m.content).join("\n\n"),
+                    turns: evalMsgs.filter((m) => m.role !== "system"),
+                };
+                for await (const evt of this.evalProvider.stream(evalContext, [], undefined)) {
+                    if (evt.type === "text_delta")
+                        evalText += evt.delta;
+                }
+                const parsed = kernel.parseVerdict(evalText);
+                verdict = {
+                    passed: parsed.passed,
+                    overallScore: parsed.overallScore,
+                    feedback: parsed.feedback,
+                    details: parsed.details ?? [],
+                };
+                skillCandidate = parsed.skillCandidate;
             }
-            const parsed = kernel.parseVerdict(evalText);
-            const verdict = {
-                passed: parsed.passed,
-                overallScore: parsed.overallScore,
-                feedback: parsed.feedback,
-                details: parsed.details ?? [],
-            };
             if (verdict.passed) {
-                if (parsed.skillCandidate && this.skillDir) {
-                    const { name, description, whenToUse, content } = parsed.skillCandidate;
+                if (skillCandidate && this.skillDir) {
+                    const { name, description, whenToUse, content } = skillCandidate;
                     const fm = ["---", `name: ${name}`, `description: ${description}`,
                         whenToUse ? `when_to_use: ${whenToUse}` : null, "---", ""]
                         .filter(Boolean).join("\n");

package/dist/index.d.ts

@@ -71,8 +71,8 @@ export type { PermissionDecision, Permission } from "./safety/permissions.js";
 export { Governance, governancePolicyToKernelEvent } from "./governance.js";
 export type { GovernanceVerdict, GovernancePolicy, GovernanceConstraint } from "./governance.js";
 export { SinglePassHarness, EvalLoopHarness, HarnessLoop } from "./harness/harness.js";
-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 { HarnessRequest, HarnessOutcome, HarnessLoopOptions, QualityGate, CriterionResult, HarnessEvent, VerdictFn } 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, CacheBreakpointStrategy, } 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, workflowNodeSpecToKernel, submitWorkflowNodesToKernel, submitWorkflowToKernel, submitWorkflowNodesTool, startWorkflowTool, fanoutSynthesize, generateAndFilter, verifyRules, genEval, } from "./types/agent.js";
 export type { AcceptanceCriterion, VerificationContract, ContractCheckResult, } from "./collaboration/contract.js";

package/dist/providers/anthropic.js

@@ -77,19 +77,24 @@ export class AnthropicProvider {
      * (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) {
+    buildTools(tools, anchorCache, strategy) {
+        // Tool cache_control is emitted under "default" and "tools-only". "system-only",
+        // "frozen-prefix", and "none" all skip it.
+        const emitOnLastTool = anchorCache &&
+            (strategy === "default" || strategy === "tools-only");
         return tools.map((t, i) => ({
             name: t.name,
             description: t.description,
             input_schema: JSON.parse(t.parameters),
-            ...(anchorCache && i === tools.length - 1 ? { cache_control: { type: "ephemeral" } } : {}),
+            ...(emitOnLastTool && i === tools.length - 1 ? { cache_control: { type: "ephemeral" } } : {}),
         }));
     }
     async complete(context, tools, extensions) {
         if (this.circuit.isOpen())
             throw new Error("Circuit breaker open");
-        const system = this.buildSystem(context);
-        const msgs = this.buildMessages(context);
+        const strategy = resolveCacheBreakpointStrategy(extensions);
+        const system = this.buildSystem(context, strategy);
+        const msgs = this.buildMessages(context, strategy);
         assertCacheBudget(system, tools.length);
         const requestExtensions = this.requestExtensions(extensions);
         let lastErr;
@@ -101,7 +106,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, !Array.isArray(system)) } : {}),
+                    ...(tools.length ? { tools: this.buildTools(tools, !Array.isArray(system), strategy) } : {}),
                 }, extensions);
                 this.circuit.recordSuccess();
                 let content = "";
@@ -129,10 +134,16 @@ export class AnthropicProvider {
         throw lastErr;
     }
     async *stream(context, tools, extensions, _state, signal) {
-        const system = this.buildSystem(context);
-        const msgs = this.buildMessages(context);
+        const strategy = resolveCacheBreakpointStrategy(extensions);
+        const system = this.buildSystem(context, strategy);
+        const msgs = this.buildMessages(context, strategy);
         assertCacheBudget(system, tools.length);
         const requestExtensions = this.requestExtensions(extensions);
+        const builtTools = tools.length ? this.buildTools(tools, !Array.isArray(system), strategy) : undefined;
+        // I1: capture which slots will carry cache_control so cache_read_input_tokens can be
+        // attributed pro-rata when the response arrives. Honest annotation: Anthropic returns one
+        // scalar (no per-slot breakdown), so this is an estimate, not authoritative.
+        const slotBp = countCacheControlSlots(system, builtTools, msgs);
         const toolBlocks = {};
         const nativeBlocks = {};
         let finalText = "";
@@ -143,7 +154,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, !Array.isArray(system)) } : {}),
+            ...(builtTools ? { tools: builtTools } : {}),
         }, extensions, signal);
         let uncachedInput = 0;
         let cacheReadTokens = 0;
@@ -165,6 +176,7 @@ export class AnthropicProvider {
                     // 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;
+                    const bySlot = estimateCacheReadBySlot(cacheReadTokens, slotBp);
                     yield {
                         type: "usage",
                         totalTokens: inputTokens + outputTokens,
@@ -172,6 +184,7 @@ export class AnthropicProvider {
                         outputTokens,
                         cacheReadInputTokens: cacheReadTokens,
                         cacheCreationInputTokens: cacheCreationTokens,
+                        ...(bySlot ? { cacheReadInputTokensBySlot: bySlot } : {}),
                     };
                 }
             }
@@ -235,7 +248,7 @@ export class AnthropicProvider {
             ? this.client.beta.messages.stream(params, opts)
             : this.client.messages.stream(params, opts));
     }
-    buildSystem(context) {
+    buildSystem(context, strategy) {
         // 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
@@ -245,23 +258,27 @@ export class AnthropicProvider {
         if (!context.systemStable && !context.systemKnowledge) {
             return context.systemText || undefined;
         }
+        // System cache_control is emitted under "default" and "system-only". Other strategies
+        // keep the text-block structure for protocol parity but omit cache_control.
+        const emitOnSystemBlocks = strategy === "default" || strategy === "system-only";
+        const cc = { type: "ephemeral" };
         const blocks = [];
         if (context.systemStable) {
-            blocks.push({ type: "text", text: context.systemStable, cache_control: { type: "ephemeral" } });
+            blocks.push({ type: "text", text: context.systemStable, ...(emitOnSystemBlocks ? { cache_control: cc } : {}) });
         }
         if (context.systemKnowledge) {
-            blocks.push({ type: "text", text: context.systemKnowledge, cache_control: { type: "ephemeral" } });
+            blocks.push({ type: "text", text: context.systemKnowledge, ...(emitOnSystemBlocks ? { cache_control: cc } : {}) });
         }
         return blocks.length ? blocks : undefined;
     }
-    buildMessages(context) {
+    buildMessages(context, strategy) {
         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);
+        applyMessageCacheControl(msgs, context.frozenPrefixLen, strategy);
         if (context.stateTurn) {
             // Render through toAnthropicMessages so assistant tool_use blocks and
             // tool-role tool_result parts are serialized correctly — toAnthropicContent
@@ -282,6 +299,70 @@ export class AnthropicProvider {
         this.nativeAssistantBlocks.set(assistantReplayKey(message), blocks);
     }
 }
+/** Recognised cache-breakpoint strategy values; any other input (incl. undefined) falls to `"default"`. */
+const CACHE_BREAKPOINT_STRATEGIES = new Set([
+    "default", "tools-only", "system-only", "frozen-prefix", "none",
+]);
+/** Pull `cacheBreakpointStrategy` from per-call extensions; unrecognised values → `"default"`. */
+function resolveCacheBreakpointStrategy(extensions) {
+    const raw = extensions?.cacheBreakpointStrategy;
+    if (typeof raw === "string" && CACHE_BREAKPOINT_STRATEGIES.has(raw)) {
+        return raw;
+    }
+    return "default";
+}
+/**
+ * I1: count which slots of the outgoing request carry a `cache_control` breakpoint. Used to
+ * pro-rata-attribute the response's `cache_read_input_tokens` (a single scalar with no per-slot
+ * breakdown) across the slots that contributed to the cache hit. Returns whether each slot has
+ * any breakpoint — not the actual count, since pro-rata only needs the contributing slot set.
+ */
+function countCacheControlSlots(system, builtTools, msgs) {
+    const sysBp = Array.isArray(system) && system.some(b => b?.cache_control != null);
+    const toolBp = !!builtTools && builtTools.some(t => t?.cache_control != null);
+    let msgBp = false;
+    for (const m of msgs) {
+        if (Array.isArray(m.content)) {
+            if (m.content.some(b => b?.cache_control != null)) {
+                msgBp = true;
+                break;
+            }
+        }
+    }
+    return { system: sysBp, tools: toolBp, messages: msgBp };
+}
+/**
+ * I1: split the response's `cache_read_input_tokens` evenly across the slots that carried a
+ * cache_control breakpoint on the request. Returns undefined when there's no cache read or no
+ * contributing slot — in those cases the consumer is better off seeing the field absent than
+ * seeing all zeros. The remainder (if the total doesn't divide evenly) lands on the first
+ * contributing slot to keep the sum exact.
+ */
+function estimateCacheReadBySlot(cacheRead, slotBp) {
+    if (cacheRead <= 0)
+        return undefined;
+    const count = (slotBp.system ? 1 : 0) + (slotBp.tools ? 1 : 0) + (slotBp.messages ? 1 : 0);
+    if (count === 0)
+        return undefined;
+    const share = Math.floor(cacheRead / count);
+    const remainder = cacheRead - share * count;
+    const out = {};
+    let firstDone = false;
+    const give = () => {
+        if (!firstDone) {
+            firstDone = true;
+            return share + remainder;
+        }
+        return share;
+    };
+    if (slotBp.system)
+        out.system = give();
+    if (slotBp.tools)
+        out.tools = give();
+    if (slotBp.messages)
+        out.messages = give();
+    return out;
+}
 /** Anthropic accepts at most this many cache_control breakpoints per request. */
 const MAX_CACHE_BREAKPOINTS = 4;
 /**
@@ -324,15 +405,21 @@ function assertCacheBudget(system, toolCount) {
  * cache_control attaches to the last content block of each target, promoting a bare
  * string body to a text block.
  */
-function applyMessageCacheControl(msgs, frozenPrefixLen) {
+function applyMessageCacheControl(msgs, frozenPrefixLen, strategy) {
     if (!msgs.length)
         return;
+    // Message-level cache_control is emitted under "default" and "frozen-prefix" only.
+    // "tools-only", "system-only", and "none" skip the history entirely.
+    if (strategy === "tools-only" || strategy === "system-only" || strategy === "none")
+        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 {
+    else if (strategy === "default") {
+        // Rolling fallback is part of the default strategy only — `"frozen-prefix"` deliberately
+        // skips it so a verify can isolate the deep-anchor contribution from the rolling pair.
         for (let i = msgs.length - 2; i >= 0 && targets.size < MESSAGE_CACHE_BREAKPOINTS; i--) {
             if (msgs[i].role === "user")
                 targets.add(i);

package/dist/runtime/runner.d.ts

@@ -36,6 +36,16 @@ export interface TurnMetrics {
     inputTokens: number;
     /** Tokens served from the prompt cache this turn (Anthropic `cache_read_input_tokens`). */
     cacheReadTokens: number;
+    /** I1: per-slot attribution of `cacheReadTokens`. Anthropic reports a single cache-read total,
+     *  not a per-block breakdown — this field is a pro-rata estimate over the slots that actually
+     *  carried a `cache_control` breakpoint on the request. Missing / empty when the provider does
+     *  not honor `cache_control` (OpenAI-family auto-cache) or when no breakpoints were placed.
+     *  Useful for diagnosing which slot is buying the cache hit when comparing strategies. */
+    cacheReadTokensBySlot?: {
+        system?: number;
+        tools?: number;
+        messages?: number;
+    };
     /** Tokens written to the prompt cache this turn (Anthropic `cache_creation_input_tokens`). */
     cacheCreationTokens: number;
 }
@@ -60,6 +70,17 @@ export interface RuntimeOptions {
     maxTurns?: number;
     timeoutMs?: number;
     agentId?: string;
+    /** I4: optional run-start memory pre-fetch hook. The runner calls this ONCE per run, before the
+     *  first LLM turn, with the request's goal and (optional) run-spec. Each returned query string
+     *  becomes a `dreamStore.search(agentId, q, 5)` and the resulting hits are paged into the
+     *  context's knowledge partition before turn 1, so the model sees them on first call. Returning
+     *  `undefined` / empty array is a no-op. Requires `dreamStore` + `agentId`; missing either ⇒
+     *  silently skipped (errs-open). Bench memory-recall shows -57% turns / -55% dollars when
+     *  relevant memories land on turn 1 instead of being discovered via the meta-tool on turn 3+. */
+    preQueryMemory?: (ctx: {
+        goal: string;
+        runSpec?: AgentRunSpec;
+    }) => Promise<string[] | undefined> | string[] | undefined;
     systemPrompt?: string;
     initialMemory?: string[];
     skillDir?: string;