@deepstrike/sdk 0.2.20 → 0.2.22

package/dist/index.d.ts

@@ -60,6 +60,7 @@ export type { RegisteredTool } from "./tools/index.js";
 export { scanSkillDir, readSkillFile } from "./skills/loader.js";
 export type { SkillMetadata } from "./skills/loader.js";
 export { WorkingMemory } from "./memory/working.js";
+export { InMemoryDreamStore } from "./memory/in-memory-store.js";
 export type { DreamStore, DreamResult, SessionData, SessionMessage, MemoryEntry, CurationResult, CurationStats, MemoryWriteRequest, MemoryQuery, MemoryRetrieval, MemoryMetadata, MemoryKind, } from "./memory/protocols.js";
 export type { KnowledgeSource } from "./knowledge/source.js";
 export { ScheduledPrompt } from "./signals/scheduled.js";
@@ -71,7 +72,7 @@ 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 { 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/index.js

@@ -42,6 +42,7 @@ export { tool, streamingTool, executeTools, readFile, validateToolArguments } fr
 export { scanSkillDir, readSkillFile } from "./skills/loader.js";
 // ── Memory ─────────────────────────────────────────────────────────────────
 export { WorkingMemory } from "./memory/working.js";
+export { InMemoryDreamStore } from "./memory/in-memory-store.js";
 export { ScheduledPrompt } from "./signals/scheduled.js";
 export { SignalGateway } from "./signals/gateway.js";
 // ── Safety & Governance ────────────────────────────────────────────────────

package/dist/memory/in-memory-store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `InMemoryDreamStore` — a lightweight `DreamStore` implementation backed by per-agent `Map`s.
+ *
+ * Originally lived as `MockDreamStore` in the SDK's test helpers; promoted here so benchmarks,
+ * examples, and downstream consumers can use it without copying the boilerplate.
+ *
+ * Use cases:
+ *   - Benchmark A/B variants where memory is on/off (preload via constructor).
+ *   - Unit tests that exercise `Agent.dream()` or the `memory_query` path without disk I/O.
+ *   - Local development / CI where a persistent memory store isn't needed.
+ *
+ * The `search()` impl is intentionally trivial — it returns the first `topK` memories for the
+ * agent regardless of `query`. The kernel ranks by score before deciding what to surface, so the
+ * order memories were inserted is what callers see. For semantic search, plug in a real store.
+ */
+import type { CurationResult, DreamStore, MemoryEntry, SessionData } from "./protocols.js";
+export declare class InMemoryDreamStore implements DreamStore {
+    private readonly initialMemories;
+    private sessions;
+    private memories;
+    /** Sessions persisted via `saveSession`; exposed for test assertions. */
+    readonly savedSessions: SessionData[];
+    /**
+     * @param initialMemories Optional seed memories applied to every agent that asks for memories
+     *                        for the first time. Useful for benchmark scenarios that preload a fact.
+     */
+    constructor(initialMemories?: MemoryEntry[]);
+    /** Pre-populate sessions for a specific agent (test/benchmark setup). */
+    addSession(agentId: string, session: SessionData): void;
+    /** Pre-populate memories for a specific agent (test/benchmark setup). */
+    addMemories(agentId: string, entries: MemoryEntry[]): void;
+    loadSessions(agentId: string): Promise<SessionData[]>;
+    loadMemories(agentId: string): Promise<MemoryEntry[]>;
+    commit(agentId: string, result: CurationResult, existing: MemoryEntry[]): Promise<void>;
+    search(agentId: string, _query: string, topK?: number): Promise<MemoryEntry[]>;
+    saveSession(data: SessionData): Promise<void>;
+}

package/dist/memory/in-memory-store.js

@@ -0,0 +1,50 @@
+export class InMemoryDreamStore {
+    initialMemories;
+    sessions = new Map();
+    memories = new Map();
+    /** Sessions persisted via `saveSession`; exposed for test assertions. */
+    savedSessions = [];
+    /**
+     * @param initialMemories Optional seed memories applied to every agent that asks for memories
+     *                        for the first time. Useful for benchmark scenarios that preload a fact.
+     */
+    constructor(initialMemories = []) {
+        this.initialMemories = initialMemories;
+    }
+    /** Pre-populate sessions for a specific agent (test/benchmark setup). */
+    addSession(agentId, session) {
+        const list = this.sessions.get(agentId) ?? [];
+        list.push(session);
+        this.sessions.set(agentId, list);
+    }
+    /** Pre-populate memories for a specific agent (test/benchmark setup). */
+    addMemories(agentId, entries) {
+        this.memories.set(agentId, [...(this.memories.get(agentId) ?? []), ...entries]);
+    }
+    async loadSessions(agentId) {
+        return this.sessions.get(agentId) ?? [];
+    }
+    async loadMemories(agentId) {
+        if (this.memories.has(agentId))
+            return this.memories.get(agentId);
+        if (this.initialMemories.length > 0) {
+            this.memories.set(agentId, [...this.initialMemories]);
+            return this.memories.get(agentId);
+        }
+        return [];
+    }
+    async commit(agentId, result, existing) {
+        const kept = existing.filter((_, i) => !result.toRemoveIndices.includes(i));
+        this.memories.set(agentId, [...kept, ...result.toAdd]);
+    }
+    async search(agentId, _query, topK = 5) {
+        const all = await this.loadMemories(agentId);
+        return all.slice(0, topK);
+    }
+    async saveSession(data) {
+        this.savedSessions.push(data);
+        const list = this.sessions.get(data.agentId) ?? [];
+        list.push(data);
+        this.sessions.set(data.agentId, list);
+    }
+}

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,8 +134,9 @@ 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 toolBlocks = {};
@@ -143,7 +149,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, signal);
         let uncachedInput = 0;
         let cacheReadTokens = 0;
@@ -235,7 +241,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 +251,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 +292,18 @@ 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";
+}
 /** Anthropic accepts at most this many cache_control breakpoints per request. */
 const MAX_CACHE_BREAKPOINTS = 4;
 /**
@@ -324,15 +346,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/types.d.ts

@@ -210,6 +210,34 @@ export interface RetryConfig {
  */
 export type ProviderRunState = Record<string, unknown>;
 export type ProviderProtocol = "anthropic-messages" | "openai-chat" | "openai-responses" | "gemini";
+/**
+ * Strategy for placing Anthropic-protocol `cache_control` breakpoints across a request's
+ * static prefix (tools + system blocks) and rolling history (messages). Pass via the
+ * `extensions.cacheBreakpointStrategy` extension on every provider call; the runner already
+ * flows `RuntimeOptions.extensions` through, so setting it once on the runner propagates
+ * to every Anthropic-protocol call.
+ *
+ * Values:
+ *   - `"default"` — current production behavior: a breakpoint on the last tool (when system
+ *     is rendered as a string), one on each system block (when system blocks are present),
+ *     and the rolling message pair (last message + frozen-prefix anchor or last preceding
+ *     user turn).
+ *   - `"tools-only"` — breakpoint on the last tool only. System blocks and history go
+ *     uncached. Useful to isolate the tools-prefix cache contribution.
+ *   - `"system-only"` — breakpoints on system blocks only. No tool, no history caching.
+ *     Useful to isolate the system-prefix cache contribution.
+ *   - `"frozen-prefix"` — breakpoints on the message history only, anchored at
+ *     `frozenPrefixLen` (the compaction boundary, P1-E). Falls back to the last-message
+ *     breakpoint when no frozen prefix is set. No tools, no system caching. Useful to
+ *     stress-test the P1-E deep-anchor design.
+ *   - `"none"` — no `cache_control` anywhere. The baseline for cache-hit attribution.
+ *
+ * Strategies that disable some breakpoints still keep the structural shape (e.g. system
+ * blocks remain text blocks rather than collapsing into a single string), so the only
+ * Δ between variants is which blocks carry `cache_control`. Unrecognised strings fall
+ * back to `"default"`.
+ */
+export type CacheBreakpointStrategy = "default" | "tools-only" | "system-only" | "frozen-prefix" | "none";
 export interface ProviderDescriptor {
     provider: string;
     protocol: ProviderProtocol;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "description": "DeepStrike Node.js SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.99.0",
-    "@deepstrike/core": "0.2.20",
+    "@deepstrike/core": "0.2.22",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },