@strands-agents/sdk 1.16.0 → 1.17.0

package/dist/src/context-manager/methods/truncate.js.map

@@ -1 +1 @@
-{"version":3,"file":"truncate.js","sourceRoot":"","sources":["../../../../src/context-manager/methods/truncate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"truncate.js","sourceRoot":"","sources":["../../../../src/context-manager/methods/truncate.ts"],"names":[],"mappings":"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"}

package/dist/src/context-manager/modes/agentic/agentic-context.d.ts

@@ -8,11 +8,11 @@ import type { MiddlewareInputHandler } from '../../../middleware/types.js';
 export declare const summarizeContextTool: import("../../../index.js").InvokableTool<{
     keepRecent?: number | undefined;
     summaryRatio?: number | undefined;
-    messageType?: "tools" | "messages" | "all" | undefined;
+    messageType?: "tools" | "all" | "messages" | undefined;
 }, string>;
 export declare const truncateContextTool: import("../../../index.js").InvokableTool<{
     keepRecent?: number | undefined;
-    messageType?: "tools" | "messages" | "all" | undefined;
+    messageType?: "tools" | "all" | "messages" | undefined;
 }, string>;
 export declare function createTokenUsageMiddleware(): MiddlewareInputHandler<InvokeModelContext>;
 export declare const pinContextTool: import("../../../index.js").InvokableTool<{

package/dist/src/context-manager/retrieval-tool.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Retrieval tool for accessing stashed (L1) content.
+ *
+ * Registered automatically when the ContextManager has storage configured.
+ *
+ * @internal
+ */
+import type { Tool } from '../tools/tool.js';
+import { Message } from '../types/messages.js';
+import type { Stash } from './stash.js';
+export declare const RETRIEVAL_TOOL_NAME = "retrieve_context";
+/**
+ * Creates the retrieval tool for the given stash.
+ *
+ * @param stash - The stash instance to retrieve from
+ * @param maxResultTokens - Maximum tokens in the retrieval result
+ * @returns A Tool that can retrieve stashed content
+ *
+ * @internal
+ */
+export declare function createRetrievalTool(stash: Stash, maxResultTokens?: number): Tool;
+/**
+ * Tracks toolUseIds from retrieval tool invocations so their results
+ * can be excluded from stashing (prevents retrieval loops).
+ *
+ * @internal
+ */
+export declare function trackRetrievalToolUseIds(message: Message, skipSet: Set<string>): void;
+//# sourceMappingURL=retrieval-tool.d.ts.map

package/dist/src/context-manager/retrieval-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-tool.d.ts","sourceRoot":"","sources":["../../../src/context-manager/retrieval-tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAgB,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC,eAAO,MAAM,mBAAmB,qBAAqB,CAAA;AAkBrD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CA2ChF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAOrF"}

package/dist/src/context-manager/retrieval-tool.js

@@ -0,0 +1,98 @@
+/**
+ * Retrieval tool for accessing stashed (L1) content.
+ *
+ * Registered automatically when the ContextManager has storage configured.
+ *
+ * @internal
+ */
+import { z } from 'zod';
+import { tool } from '../tools/tool-factory.js';
+import { isSearchableContent, searchContent } from '../vended-plugins/context-offloader/search.js';
+import { Message, ToolUseBlock } from '../types/messages.js';
+export const RETRIEVAL_TOOL_NAME = 'retrieve_context';
+const DEFAULT_MAX_RESULT_TOKENS = 10_000;
+const CHARS_PER_TOKEN = 4;
+const retrievalInputSchema = z.object({
+    reference: z.string().describe('The reference key from the offload placeholder.'),
+    pattern: z.string().optional().describe('Regex or keyword to grep for. Returns matching lines with context.'),
+    line_range: z
+        .object({
+        start: z.number().int().min(1).describe('First line to return (1-indexed).'),
+        end: z.number().int().min(1).describe('Last line to return (1-indexed).'),
+    })
+        .optional()
+        .describe('Return only this span of lines.'),
+    context_lines: z.number().int().min(0).optional().describe('Lines of context around each match (default: 5).'),
+});
+/**
+ * Creates the retrieval tool for the given stash.
+ *
+ * @param stash - The stash instance to retrieve from
+ * @param maxResultTokens - Maximum tokens in the retrieval result
+ * @returns A Tool that can retrieve stashed content
+ *
+ * @internal
+ */
+export function createRetrievalTool(stash, maxResultTokens) {
+    const maxChars = (maxResultTokens ?? DEFAULT_MAX_RESULT_TOKENS) * CHARS_PER_TOKEN;
+    return tool({
+        name: RETRIEVAL_TOOL_NAME,
+        description: 'Retrieve content that was offloaded from context.\n\n' +
+            'When content is offloaded (truncated, dropped, or summarized), the original is ' +
+            'persisted and a reference key is left in its place. Use this tool with that ' +
+            'reference to access the original content.\n\n' +
+            'Options:\n' +
+            '  - pattern: regex/keyword to find matching lines with context\n' +
+            '  - line_range: { start, end } to read a specific span\n' +
+            '  - Without pattern/line_range: returns the full original content\n\n' +
+            'Examples:\n' +
+            '  { reference: "1_toolu_abc_0", pattern: "error" }\n' +
+            '  { reference: "1_toolu_abc_0", line_range: { start: 10, end: 25 } }\n' +
+            '  { reference: "1_toolu_abc_0" }',
+        inputSchema: retrievalInputSchema,
+        callback: async (input) => {
+            const result = await stash.retrieve(input.reference);
+            if (!result) {
+                return `Error: reference not found: ${input.reference}`;
+            }
+            if (!input.pattern && !input.line_range) {
+                return result.data;
+            }
+            const text = extractText(result.data);
+            if (!text || !isSearchableContent('text/plain')) {
+                return `Error: cannot search non-text content. Omit pattern/line_range to retrieve full content.`;
+            }
+            const contextLines = input.context_lines ?? 5;
+            return searchContent(text, { pattern: input.pattern, line_range: input.line_range, context_lines: contextLines }, maxChars);
+        },
+    });
+}
+/**
+ * Tracks toolUseIds from retrieval tool invocations so their results
+ * can be excluded from stashing (prevents retrieval loops).
+ *
+ * @internal
+ */
+export function trackRetrievalToolUseIds(message, skipSet) {
+    if (message.role !== 'assistant')
+        return;
+    for (const block of message.content) {
+        if (block instanceof ToolUseBlock && block.name === RETRIEVAL_TOOL_NAME) {
+            skipSet.add(block.toolUseId);
+        }
+    }
+}
+function extractText(data) {
+    if (typeof data === 'string')
+        return data;
+    if (data && typeof data === 'object') {
+        if ('text' in data && typeof data.text === 'string') {
+            return data.text;
+        }
+        if ('json' in data) {
+            return JSON.stringify(data.json, null, 2);
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=retrieval-tool.js.map

package/dist/src/context-manager/retrieval-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-tool.js","sourceRoot":"","sources":["../../../src/context-manager/retrieval-tool.ts"],"names":[],"mappings":"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"}

package/dist/src/context-manager/stash.d.ts

@@ -0,0 +1,107 @@
+/**
+ * L1 stash: durable storage for offloaded context content.
+ *
+ * When the ContextManager offloads content from the context window, the
+ * original is persisted here so the agent can retrieve it on demand via the
+ * retrieval tool.
+ *
+ * @internal
+ */
+import { type Storage } from '../storage/storage.js';
+import { Message } from '../types/messages.js';
+import type { ContentBlock } from '../types/messages.js';
+import type { JSONValue } from '../types/json.js';
+/** @internal */
+export declare const STASH_PREFIX = "context";
+/** Format stash refs for display in placeholders. Returns '' when refs is empty. */
+export declare function formatStashRefs(refs: string[]): string;
+/**
+ * Wraps a Storage backend with key management and content framing for the
+ * ContextManager's L1 stash.
+ *
+ * @internal
+ */
+export declare class Stash {
+    private readonly _storage;
+    private readonly _baseStorage;
+    private readonly _sessionId;
+    /** Name of the base storage constructor, for diagnostic logging. */
+    readonly storageTypeName: string;
+    constructor(storage: Storage, sessionId: string, agentId: string);
+    /**
+     * Store a serialized block and return a deterministic reference key.
+     *
+     * Keys are deterministic (`<id>_<blockIndex>`) so they can be recomputed
+     * via {@link refsFor} after a process restart or snapshot restore.
+     *
+     * @param id - Identifier component for the key (e.g. toolUseId)
+     * @param blockIndex - Index of the block within the tool result
+     * @param data - Serialized bytes to persist
+     * @returns Reference key for retrieval
+     */
+    store(id: string, blockIndex: number, data: Uint8Array): Promise<string>;
+    /**
+     * Compute the deterministic reference keys for a content block.
+     *
+     * For a {@link ToolResultBlock}, returns one key per inner content item
+     * (`<toolUseId>_<i>`). For any other block, returns a single key
+     * (`<trackingId>_<blockIndex>`).
+     *
+     * @param block - The content block
+     * @param message - The message containing the block
+     * @param blockIndex - Index of the block within the message
+     * @returns Array of reference keys
+     */
+    refsFor(block: ContentBlock, message: Message, blockIndex: number): string[];
+    /**
+     * Eagerly stash all content from a message on arrival.
+     * Called via MessageAddedEvent so content is persisted before any strategy runs.
+     *
+     * @param message - The message whose content should be persisted
+     * @param skipToolUseIds - ToolUseIds to skip (e.g. retrieval tool results)
+     */
+    storeMessage(message: Message, skipToolUseIds?: ReadonlySet<string>): Promise<void>;
+    /**
+     * Retrieve previously stashed content as its serialized JSON form.
+     *
+     * @param reference - Key returned by a previous store call
+     * @returns The deserialized block data (from `toJSON()`), or null if not found
+     */
+    retrieve(reference: string): Promise<{
+        data: unknown;
+    } | null>;
+    /**
+     * List all stashed references.
+     */
+    list(): Promise<string[]>;
+    /**
+     * Delete a stashed entry.
+     */
+    delete(reference: string): Promise<void>;
+    /**
+     * Delete all entries in this stash instance.
+     */
+    clear(): Promise<void>;
+    /**
+     * Delete all stash data for this session across all agents.
+     *
+     * Unlike {@link clear}, which is scoped to this agent's namespace,
+     * this scans `context/<sessionId>/` on the base storage to catch data
+     * from every agent that wrote to the session.
+     */
+    clearSession(): Promise<void>;
+    /**
+     * Serialize all stash entries into a plain object for snapshot persistence.
+     *
+     * @returns Map of reference keys to their stored JSON values
+     */
+    takeSnapshot(): Promise<Record<string, JSONValue>>;
+    /**
+     * Restore stash entries from a previously captured snapshot.
+     *
+     * @param entries - Map of reference keys to their JSON values (from {@link takeSnapshot})
+     */
+    loadSnapshot(entries: Record<string, JSONValue>): Promise<void>;
+    private _storeToolResult;
+}
+//# sourceMappingURL=stash.d.ts.map

package/dist/src/context-manager/stash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stash.d.ts","sourceRoot":"","sources":["../../../src/context-manager/stash.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAiC,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAA;AACnF,OAAO,EAAE,OAAO,EAAkE,MAAM,sBAAsB,CAAA;AAC9G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAGjD,gBAAgB;AAChB,eAAO,MAAM,YAAY,YAAY,CAAA;AAUrC,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAItD;AAED;;;;;GAKG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IAEnC,oEAAoE;IACpE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;gBAEpB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAOhE;;;;;;;;;;OAUG;IACG,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAM9E;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAO5E;;;;;;OAMG;IACG,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBzF;;;;;OAKG;IACG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAMpE;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAI/B;;OAEG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK9C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;;;;;OAMG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnC;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAYxD;;;;OAIG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;YAIvD,gBAAgB;CAM/B"}

package/dist/src/context-manager/stash.js

@@ -0,0 +1,186 @@
+/**
+ * L1 stash: durable storage for offloaded context content.
+ *
+ * When the ContextManager offloads content from the context window, the
+ * original is persisted here so the agent can retrieve it on demand via the
+ * retrieval tool.
+ *
+ * @internal
+ */
+import { namespace as namespaceStorage } from '../storage/storage.js';
+import { Message, ToolResultBlock, ToolUseBlock, CachePointBlock, ReasoningBlock } from '../types/messages.js';
+import { logger } from '../logging/logger.js';
+/** @internal */
+export const STASH_PREFIX = 'context';
+function encode(value) {
+    return new TextEncoder().encode(JSON.stringify(value));
+}
+function decode(bytes) {
+    return JSON.parse(new TextDecoder().decode(bytes));
+}
+/** Format stash refs for display in placeholders. Returns '' when refs is empty. */
+export function formatStashRefs(refs) {
+    if (refs.length === 0)
+        return '';
+    if (refs.length === 1)
+        return ` ref: ${refs[0]}`;
+    return ` refs: ${refs.join(', ')}`;
+}
+/**
+ * Wraps a Storage backend with key management and content framing for the
+ * ContextManager's L1 stash.
+ *
+ * @internal
+ */
+export class Stash {
+    _storage;
+    _baseStorage;
+    _sessionId;
+    /** Name of the base storage constructor, for diagnostic logging. */
+    storageTypeName;
+    constructor(storage, sessionId, agentId) {
+        this._baseStorage = storage;
+        this._sessionId = sessionId;
+        this._storage = namespaceStorage(storage, `${STASH_PREFIX}/${sessionId}/scopes/agent/${agentId}`);
+        this.storageTypeName = storage.constructor.name || 'unknown';
+    }
+    /**
+     * Store a serialized block and return a deterministic reference key.
+     *
+     * Keys are deterministic (`<id>_<blockIndex>`) so they can be recomputed
+     * via {@link refsFor} after a process restart or snapshot restore.
+     *
+     * @param id - Identifier component for the key (e.g. toolUseId)
+     * @param blockIndex - Index of the block within the tool result
+     * @param data - Serialized bytes to persist
+     * @returns Reference key for retrieval
+     */
+    async store(id, blockIndex, data) {
+        const key = `${id}_${blockIndex}`;
+        await this._storage.write(key, data);
+        return key;
+    }
+    /**
+     * Compute the deterministic reference keys for a content block.
+     *
+     * For a {@link ToolResultBlock}, returns one key per inner content item
+     * (`<toolUseId>_<i>`). For any other block, returns a single key
+     * (`<trackingId>_<blockIndex>`).
+     *
+     * @param block - The content block
+     * @param message - The message containing the block
+     * @param blockIndex - Index of the block within the message
+     * @returns Array of reference keys
+     */
+    refsFor(block, message, blockIndex) {
+        if (block instanceof ToolResultBlock) {
+            return Array.from({ length: block.content.length }, (_, index) => `${block.toolUseId}_${index}`);
+        }
+        return [`${message.trackingId}_${blockIndex}`];
+    }
+    /**
+     * Eagerly stash all content from a message on arrival.
+     * Called via MessageAddedEvent so content is persisted before any strategy runs.
+     *
+     * @param message - The message whose content should be persisted
+     * @param skipToolUseIds - ToolUseIds to skip (e.g. retrieval tool results)
+     */
+    async storeMessage(message, skipToolUseIds) {
+        for (let blockIndex = 0; blockIndex < message.content.length; blockIndex++) {
+            const block = message.content[blockIndex];
+            if (block instanceof ToolResultBlock) {
+                if (skipToolUseIds?.has(block.toolUseId))
+                    continue;
+                await this._storeToolResult(block).catch((error) => {
+                    logger.debug(`toolUseId=<${block.toolUseId}>, error=<${error}> | failed to stash tool result`);
+                });
+            }
+            else if (block instanceof ToolUseBlock || block instanceof CachePointBlock || block instanceof ReasoningBlock) {
+                continue;
+            }
+            else {
+                try {
+                    await this.store(message.trackingId, blockIndex, encode(block.toJSON()));
+                }
+                catch (error) {
+                    logger.debug(`trackingId=<${message.trackingId}>, error=<${error}> | failed to stash block`);
+                }
+            }
+        }
+    }
+    /**
+     * Retrieve previously stashed content as its serialized JSON form.
+     *
+     * @param reference - Key returned by a previous store call
+     * @returns The deserialized block data (from `toJSON()`), or null if not found
+     */
+    async retrieve(reference) {
+        const bytes = await this._storage.read(reference);
+        if (bytes === null)
+            return null;
+        return { data: decode(bytes) };
+    }
+    /**
+     * List all stashed references.
+     */
+    async list() {
+        return this._storage.list('');
+    }
+    /**
+     * Delete a stashed entry.
+     */
+    async delete(reference) {
+        await this._storage.delete(reference);
+        logger.debug(`reference=<${reference}> | stash entry deleted`);
+    }
+    /**
+     * Delete all entries in this stash instance.
+     */
+    async clear() {
+        const keys = await this.list();
+        await Promise.all(keys.map((key) => this.delete(key)));
+    }
+    /**
+     * Delete all stash data for this session across all agents.
+     *
+     * Unlike {@link clear}, which is scoped to this agent's namespace,
+     * this scans `context/<sessionId>/` on the base storage to catch data
+     * from every agent that wrote to the session.
+     */
+    async clearSession() {
+        const prefix = `${STASH_PREFIX}/${this._sessionId}/`;
+        const keys = await this._baseStorage.list(prefix);
+        await Promise.all(keys.map((key) => this._baseStorage.delete(key)));
+    }
+    /**
+     * Serialize all stash entries into a plain object for snapshot persistence.
+     *
+     * @returns Map of reference keys to their stored JSON values
+     */
+    async takeSnapshot() {
+        const keys = await this.list();
+        const results = await Promise.all(keys.map((key) => this.retrieve(key).then((result) => [key, result])));
+        const entries = {};
+        for (const [key, result] of results) {
+            if (result) {
+                entries[key] = result.data;
+            }
+        }
+        return entries;
+    }
+    /**
+     * Restore stash entries from a previously captured snapshot.
+     *
+     * @param entries - Map of reference keys to their JSON values (from {@link takeSnapshot})
+     */
+    async loadSnapshot(entries) {
+        await Promise.all(Object.entries(entries).map(([key, data]) => this._storage.write(key, encode(data))));
+    }
+    async _storeToolResult(block) {
+        for (let blockIndex = 0; blockIndex < block.content.length; blockIndex++) {
+            const item = block.content[blockIndex];
+            await this.store(block.toolUseId, blockIndex, encode(item.toJSON()));
+        }
+    }
+}
+//# sourceMappingURL=stash.js.map

package/dist/src/context-manager/stash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stash.js","sourceRoot":"","sources":["../../../src/context-manager/stash.ts"],"names":[],"mappings":"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"}

package/dist/src/context-manager/strategies/offload/base.d.ts

@@ -1,12 +1,11 @@
 /**
  * Base offload strategy and shared infrastructure.
- *
- * @internal
  */
-import { Message, TextBlock, ToolResultBlock } from '../../../types/messages.js';
+import { Message, ToolResultBlock } from '../../../types/messages.js';
 import type { ContentBlock } from '../../../types/messages.js';
 import type { LocalAgent } from '../../../types/agent.js';
 import type { ContextStrategy, ContextState } from '../../types.js';
+import type { Stash } from '../../stash.js';
 /**
  * Target for offload operations. This union is intentionally extensible — new
  * string-literal members can be added freely as new content categories emerge.
@@ -17,6 +16,8 @@ import type { ContextStrategy, ContextState } from '../../types.js';
  * - `"userText"` — text blocks in user messages (excluding tool results)
  * - `string[]` — tool results from specific tools, namespaced with `tool::` (e.g. `['tool::bash']`); prefix with `!` to exclude
  * - `"*"` — all content in the context window (tool results + text blocks)
+ *
+ * @experimental
  */
 export type OffloadTarget = '*' | 'toolResults' | 'toolResultErrors' | 'assistantText' | 'userText' | string[];
 /**
@@ -30,6 +31,8 @@ export type OffloadTarget = '*' | 'toolResults' | 'toolResultErrors' | 'assistan
  * When multiple strategies target the same content, they don't conflict — strategies
  * run as an ordered pipeline, and once an earlier strategy shrinks a block, it falls
  * below the next strategy's threshold and gets skipped automatically.
+ *
+ * @experimental
  */
 export interface OffloadConditions {
     /** Token threshold above which individual blocks are offloaded. */
@@ -100,10 +103,11 @@ export declare abstract class BaseOffloadStrategy implements ContextStrategy {
     protected readonly _removalRatio: number;
     protected readonly _includeFilter: Set<string> | undefined;
     protected readonly _excludeFilter: Set<string> | undefined;
+    protected _stash: Stash | undefined;
     constructor(target?: OffloadTarget, conditions?: OffloadConditions);
     /** Whether this strategy operates at message-level (batch) vs per-block. */
     protected get _isMessageLevel(): boolean;
-    init(agent: LocalAgent): void;
+    init(agent: LocalAgent, stash?: Stash): void;
     apply(context: ContextState): Promise<boolean>;
     /** Per-block execution: walk each message, transform individual blocks above threshold. */
     private _applyPerBlock;
@@ -118,7 +122,7 @@ export declare abstract class BaseOffloadStrategy implements ContextStrategy {
     /** Collect eligible messages for message-level operations, respecting preserveRecent, head-pin, and threshold. */
     protected _getEligibleMessages(context: ContextState): Promise<Message[]>;
     /** Transform a block. Return the replacement, or null to skip. */
-    protected abstract _replaceBlock(block: TextBlock | ToolResultBlock, tokens: number, message: Message, agent: LocalAgent): Promise<ContentBlock | null>;
+    protected abstract _replaceBlock(block: ContentBlock, tokens: number, message: Message, agent: LocalAgent, stashRefs: string[]): Promise<ContentBlock | null>;
 }
 /**
  * Last-resort strategy that recomputes utilization and drops the oldest 20% of messages
@@ -133,7 +137,7 @@ export declare class EmergencyTruncateStrategy extends BaseOffloadStrategy {
     readonly name = "offload:emergency-truncate";
     protected readonly _removalRatio = 0.2;
     constructor();
-    init(): void;
+    init(_agent: LocalAgent, stash?: Stash): void;
     apply(context: ContextState): Promise<boolean>;
     protected _replaceBlock(): Promise<ContentBlock | null>;
 }

package/dist/src/context-manager/strategies/offload/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../../../src/context-manager/strategies/offload/base.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,eAAe,EAAgB,MAAM,4BAA4B,CAAA;AAC9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAEnE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GAAG,GAAG,GAAG,aAAa,GAAG,kBAAkB,GAAG,eAAe,GAAG,UAAU,GAAG,MAAM,EAAE,CAAA;AAE9G;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D,8DAA8D;IAC9D,IAAI,CAAC,UAAU,EAAE,iBAAiB,GAAG,eAAe,CAAA;CACrD;AAQD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAWzE;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,EAC1C,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,GACzC,OAAO,CAYT;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAMjG;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,EAC1C,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,GACzC,OAAO,CAYT;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,OAAO,EAAE,EACnB,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,EAC1C,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,GACzC,OAAO,EAAE,CAMX;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,CAyBtF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAoBlH;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,CAgB3D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG;IAAE,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,CA4BrH;AAID,yEAAyE;AACzE,8BAAsB,mBAAoB,YAAW,eAAe;IAClE,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAE9B,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAA;IACrD,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACjD,SAAS,CAAC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5D,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAC1C,SAAS,CAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAM;IAC9C,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IAC1D,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;gBAE9C,MAAM,CAAC,EAAE,aAAa,EAAE,UAAU,CAAC,EAAE,iBAAiB;IAelE,4EAA4E;IAC5E,SAAS,KAAK,eAAe,IAAI,OAAO,CAEvC;IAED,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAUvB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IASpD,2FAA2F;YAC7E,cAAc;IAyB5B,wFAAwF;cACxE,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAuBzE,wFAAwF;IACxF,SAAS,CAAC,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAI3D,oFAAoF;IACpF,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO;IAW/G,4CAA4C;cAC5B,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,OAAO,EAAE,EACnB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,OAAO,CAAC;IAqBnB,kHAAkH;cAClG,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAyC/E,kEAAkE;IAClE,SAAS,CAAC,QAAQ,CAAC,aAAa,CAC9B,KAAK,EAAE,SAAS,GAAG,eAAe,EAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;CAChC;AAID;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,SAAQ,mBAAmB;IAChE,QAAQ,CAAC,IAAI,gCAA+B;IAC5C,mBAA4B,aAAa,OAAM;;IAMtC,IAAI,IAAI,IAAI;IAIN,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;cAQ7C,aAAa,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;CAG9D"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../../../src/context-manager/strategies/offload/base.ts"],"names":[],"mappings":"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"}

package/dist/src/context-manager/strategies/offload/base.js

@@ -1,11 +1,10 @@
 /**
  * Base offload strategy and shared infrastructure.
- *
- * @internal
  */
 import { logger } from '../../../logging/logger.js';
 import { MessageAddedEvent } from '../../../hooks/events.js';
-import { Message, TextBlock, ToolResultBlock, ToolUseBlock } from '../../../types/messages.js';
+import { Message, TextBlock, ToolResultBlock, ToolUseBlock, CachePointBlock, ReasoningBlock, } from '../../../types/messages.js';
+import { RETRIEVAL_TOOL_NAME } from '../../retrieval-tool.js';
 // --- Shared helpers ---
 function finiteOrUndefined(value) {
     return typeof value === 'number' && Number.isFinite(value) ? Math.max(0, value) : undefined;
@@ -202,6 +201,7 @@ export class BaseOffloadStrategy {
     _removalRatio = 0.3;
     _includeFilter;
     _excludeFilter;
+    _stash;
     constructor(target, conditions) {
         if (Array.isArray(target) && target.length === 0) {
             throw new Error('Empty array target matches nothing — provide at least one target');
@@ -218,7 +218,8 @@ export class BaseOffloadStrategy {
     get _isMessageLevel() {
         return this._utilizationThreshold !== undefined;
     }
-    init(agent) {
+    init(agent, stash) {
+        this._stash = stash;
         if (this._isMessageLevel)
             return;
         if (this._preserveRecent > 0)
@@ -230,6 +231,8 @@ export class BaseOffloadStrategy {
         });
     }
     async apply(context) {
+        if (context.stash)
+            this._stash = context.stash;
         if (this._isMessageLevel) {
             if (context.utilization < this._utilizationThreshold)
                 return false;
@@ -279,12 +282,22 @@ export class BaseOffloadStrategy {
     }
     /** Whether a block is eligible for offload given the current target and filters. */
     _blockMatchesTarget(block, message, toolNameMap) {
+        if (block instanceof ToolUseBlock)
+            return false;
+        if (block instanceof CachePointBlock)
+            return false;
+        if (block instanceof ReasoningBlock)
+            return false;
         if (block instanceof TextBlock)
             return targetMatchesMessage(this._target, message);
         if (block instanceof ToolResultBlock) {
+            if (this._stash && toolNameMap.get(block.toolUseId) === RETRIEVAL_TOOL_NAME)
+                return false;
             return (this._target === undefined ||
                 toolMatchesTarget(block, this._target, toolNameMap, this._includeFilter, this._excludeFilter));
         }
+        if (this._target === '*' || this._target === undefined)
+            return true;
         return false;
     }
     /** Process eligible blocks in a message. */
@@ -298,10 +311,9 @@ export class BaseOffloadStrategy {
             const tokens = await agent.model.countTokens([new Message({ role: message.role, content: [block] })]);
             if (tokens <= effectiveThreshold)
                 continue;
-            const replacement = await this._replaceBlock(block, tokens, message, agent);
+            const stashRefs = this._stash?.refsFor(block, message, blockIndex) ?? [];
+            const replacement = await this._replaceBlock(block, tokens, message, agent, stashRefs);
             if (replacement && replacement !== block) {
-                // Intentional in-place mutation: per-block replacement shrinks existing message content
-                // rather than constructing a new Message (unlike message-level removal which uses new objects).
                 ;
                 message.content[blockIndex] = replacement;
                 acted = true;
@@ -357,8 +369,8 @@ export class EmergencyTruncateStrategy extends BaseOffloadStrategy {
     constructor() {
         super('*');
     }
-    init() {
-        // No eager hooks — this only fires on overflow
+    init(_agent, stash) {
+        this._stash = stash;
     }
     async apply(context) {
         if (context.messages.length <= 3)