@strands-agents/sdk 1.16.0 → 1.18.0

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

@@ -4,8 +4,23 @@
  * On overflow, runs the strategy pipeline (including an emergency truncation as the final step).
  */
 import type { Plugin } from '../plugins/plugin.js';
+import type { Tool } from '../tools/tool.js';
 import type { LocalAgent } from '../types/agent.js';
 import type { ContextManagerConfig } from './types.js';
+import { Stash } from './stash.js';
+/** @internal */
+export declare const CONTEXT_MANAGER_PRESETS: readonly ["auto", "agentic"];
+/** @internal */
+export type ContextManagerPreset = (typeof CONTEXT_MANAGER_PRESETS)[number];
+/**
+ * Supported values for the `contextManager` parameter.
+ *
+ * - `"auto"`: Managed context with proactive compression + offloading.
+ * - `"agentic"`: Model-driven context management via injected tools.
+ * - {@link ContextManagerConfig}: Custom strategy pipeline and stash configuration.
+ * - `false`: Explicitly disable all context management (no compression, no offloading).
+ */
+export type ContextManagerStrategy = ContextManagerPreset | ContextManagerConfig | false;
 /**
  * Manages context reduction for an agent's conversation.
  *
@@ -13,18 +28,45 @@ import type { ContextManagerConfig } from './types.js';
  * The emergency truncation is always appended as the final strategy — it recomputes
  * utilization and only fires if the window is still overflowing after user strategies.
  *
- * The ContextManager is a first-class agent component — pass it via the
- * `contextManager` parameter on the Agent constructor. When present, it owns
- * overflow recovery — no separate ConversationManager is needed.
+ * Configured through the Agent's `contextManager` parameter — pass a preset
+ * string (`'auto'`, `'agentic'`) or a `ContextManagerConfig`; the Agent
+ * constructs and registers the manager. When present, it owns overflow
+ * recovery and proactive compression — no separate ConversationManager is needed.
  *
  * @experimental
- * @internal
  */
 export declare class ContextManager implements Plugin {
     readonly name = "strands:context-manager";
     private readonly _strategies;
+    private readonly _stashStorage;
+    private readonly _enableRetrievalTool;
+    private readonly _retrievalToolUseIds;
+    private _stash;
+    private _stashIsDurable;
+    private _retrievalTool;
     constructor(config?: ContextManagerConfig);
-    initAgent(agent: LocalAgent): void;
+    /**
+     * Resolves a `ContextManagerStrategy` value into a `ContextManager` instance.
+     *
+     * @param strategy - A preset string, config object, false, or undefined
+     * @returns A ContextManager for preset strings and configs; undefined for false/undefined
+     */
+    static from(strategy: ContextManagerStrategy | undefined): ContextManager | undefined;
+    getTools(): Tool[];
+    initAgent(agent: LocalAgent): Promise<void>;
+    /**
+     * The L1 stash instance, if stash is enabled and the agent has been initialized.
+     *
+     * @returns The stash, or undefined if stash is disabled or initAgent has not run
+     */
+    get stash(): Stash | undefined;
+    /**
+     * Whether the stash is backed by durable storage that survives process restarts.
+     * When true, stash data does not need to be embedded in session snapshots.
+     *
+     * @returns true if the stash storage is not ephemeral
+     */
+    get stashIsDurable(): boolean;
     private _runStrategies;
 }
 //# sourceMappingURL=context-manager.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"context-manager.d.ts","sourceRoot":"","sources":["../../../src/context-manager/context-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAInD,OAAO,KAAK,EAAE,oBAAoB,EAAiC,MAAM,YAAY,CAAA;AAGrF;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,YAAW,MAAM;IAC3C,QAAQ,CAAC,IAAI,6BAA4B;IAEzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;gBAEnC,MAAM,CAAC,EAAE,oBAAoB;IAUzC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;YAkCpB,cAAc;CA2B7B"}
+{"version":3,"file":"context-manager.d.ts","sourceRoot":"","sources":["../../../src/context-manager/context-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAOnD,OAAO,KAAK,EAAE,oBAAoB,EAAiC,MAAM,YAAY,CAAA;AAGrF,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAQlC,gBAAgB;AAChB,eAAO,MAAM,uBAAuB,8BAA+B,CAAA;AAEnE,gBAAgB;AAChB,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3E;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG,oBAAoB,GAAG,oBAAoB,GAAG,KAAK,CAAA;AAExF;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,YAAW,MAAM;IAC3C,QAAQ,CAAC,IAAI,6BAA4B;IAEzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAC/C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAoB;IACzD,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,cAAc,CAAkB;gBAE5B,MAAM,CAAC,EAAE,oBAAoB;IAgBzC;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,sBAAsB,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS;IAuBrF,QAAQ,IAAI,IAAI,EAAE;IASZ,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAuDjD;;;;OAIG;IACH,IAAI,KAAK,IAAI,KAAK,GAAG,SAAS,CAE7B;IAED;;;;;OAKG;IACH,IAAI,cAAc,IAAI,OAAO,CAE5B;YAEa,cAAc;CAkC7B"}

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

@@ -3,10 +3,21 @@
  *
  * On overflow, runs the strategy pipeline (including an emergency truncation as the final step).
  */
-import { AfterModelCallEvent, BeforeModelCallEvent } from '../hooks/events.js';
+import { AfterModelCallEvent, BeforeModelCallEvent, MessageAddedEvent } from '../hooks/events.js';
 import { ContextWindowOverflowError } from '../errors.js';
+import { InMemoryStorage } from '../storage/in-memory-storage.js';
+import { EPHEMERAL } from '../storage/storage.js';
 import { logger } from '../logging/logger.js';
 import { EmergencyTruncateStrategy, Offload } from './strategies/offload/index.js';
+import { resolveStrategies } from './presets.js';
+import { Stash } from './stash.js';
+import { createRetrievalTool, trackRetrievalToolUseIds } from './retrieval-tool.js';
+const AUTO_TRUNCATE_THRESHOLD = 1_500;
+const AGENTIC_TRUNCATE_THRESHOLD = 8_000;
+const TRUNCATE_PREVIEW_TOKENS = 750;
+const AUTO_SUMMARIZE_UTILIZATION = 0.85;
+/** @internal */
+export const CONTEXT_MANAGER_PRESETS = ['auto', 'agentic'];
 /**
  * Manages context reduction for an agent's conversation.
  *
@@ -14,28 +25,94 @@ import { EmergencyTruncateStrategy, Offload } from './strategies/offload/index.j
  * The emergency truncation is always appended as the final strategy — it recomputes
  * utilization and only fires if the window is still overflowing after user strategies.
  *
- * The ContextManager is a first-class agent component — pass it via the
- * `contextManager` parameter on the Agent constructor. When present, it owns
- * overflow recovery — no separate ConversationManager is needed.
+ * Configured through the Agent's `contextManager` parameter — pass a preset
+ * string (`'auto'`, `'agentic'`) or a `ContextManagerConfig`; the Agent
+ * constructs and registers the manager. When present, it owns overflow
+ * recovery and proactive compression — no separate ConversationManager is needed.
  *
  * @experimental
- * @internal
  */
 export class ContextManager {
     name = 'strands:context-manager';
     _strategies;
+    _stashStorage;
+    _enableRetrievalTool;
+    _retrievalToolUseIds = new Set();
+    _stash;
+    _stashIsDurable = false;
+    _retrievalTool;
     constructor(config) {
-        this._strategies = [
-            ...(config?.strategies ?? [
-                Offload.truncate('toolResults').when({ threshold: 2500 }),
-                Offload.summarize('*').when({ threshold: 1000, utilization: 0.85 }),
-            ]),
-            new EmergencyTruncateStrategy(),
-        ];
+        const userStrategies = config?.strategies
+            ? resolveStrategies(config.strategies)
+            : [
+                Offload.truncate('toolResults', { previewTokens: TRUNCATE_PREVIEW_TOKENS }).when({
+                    threshold: AUTO_TRUNCATE_THRESHOLD,
+                }),
+                Offload.summarize('*').when({ utilization: AUTO_SUMMARIZE_UTILIZATION, preserveRecent: 4 }),
+            ];
+        this._strategies = [...userStrategies, new EmergencyTruncateStrategy()];
+        const stashConfig = config?.stash;
+        const stashObj = typeof stashConfig === 'object' ? stashConfig : undefined;
+        this._stashStorage = stashConfig === false ? false : stashObj?.storage;
+        this._enableRetrievalTool = stashConfig !== false && stashObj?.retrievalTool !== false;
     }
-    initAgent(agent) {
+    /**
+     * Resolves a `ContextManagerStrategy` value into a `ContextManager` instance.
+     *
+     * @param strategy - A preset string, config object, false, or undefined
+     * @returns A ContextManager for preset strings and configs; undefined for false/undefined
+     */
+    static from(strategy) {
+        if (strategy === false || strategy === undefined)
+            return undefined;
+        if (strategy === 'auto') {
+            return new ContextManager();
+        }
+        if (strategy === 'agentic') {
+            return new ContextManager({
+                strategies: [
+                    Offload.truncate('toolResults', { previewTokens: TRUNCATE_PREVIEW_TOKENS }).when({
+                        threshold: AGENTIC_TRUNCATE_THRESHOLD,
+                    }),
+                    Offload.summarize('*').when({ utilization: 1, preserveRecent: 4 }),
+                ],
+            });
+        }
+        if (typeof strategy === 'string') {
+            throw new Error(`Unknown contextManager preset: "${strategy}". Valid presets: ${CONTEXT_MANAGER_PRESETS.map((s) => `"${s}"`).join(', ')}`);
+        }
+        return new ContextManager(strategy);
+    }
+    getTools() {
+        if (!this._enableRetrievalTool)
+            return [];
+        if (!this._stash)
+            return [];
+        if (!this._retrievalTool) {
+            this._retrievalTool = createRetrievalTool(this._stash);
+        }
+        return [this._retrievalTool];
+    }
+    async initAgent(agent) {
+        if (this._stashStorage !== false) {
+            const storage = this._stashStorage ?? agent.storage ?? new InMemoryStorage();
+            this._stashIsDurable = !(EPHEMERAL in storage);
+            this._stash = new Stash(storage, agent.sessionId, agent.id);
+        }
+        if (this._stash) {
+            const stash = this._stash;
+            const skipSet = this._retrievalToolUseIds;
+            for (const message of agent.messages) {
+                trackRetrievalToolUseIds(message, skipSet);
+                await stash.storeMessage(message, skipSet);
+            }
+            agent.addHook(MessageAddedEvent, async (event) => {
+                trackRetrievalToolUseIds(event.message, skipSet);
+                await stash.storeMessage(event.message, skipSet);
+            });
+        }
         for (const strategy of this._strategies) {
-            strategy.init?.(agent);
+            strategy.init?.(agent, this._stash);
         }
         agent.addHook(BeforeModelCallEvent, async (event) => {
             await this._runStrategies(event.agent, event.projectedInputTokens);
@@ -52,7 +129,7 @@ export class ContextManager {
                 overflowRetries = 0;
                 return;
             }
-            const acted = await this._runStrategies(event.agent);
+            const acted = await this._runStrategies(event.agent, undefined, true);
             if (!acted) {
                 logger.warn(`agentId=<${event.agent.id}> | no strategy made progress, skipping retry`);
                 return;
@@ -61,17 +138,38 @@ export class ContextManager {
             event.retry = true;
         });
     }
-    async _runStrategies(agent, precomputedInputTokens) {
+    /**
+     * The L1 stash instance, if stash is enabled and the agent has been initialized.
+     *
+     * @returns The stash, or undefined if stash is disabled or initAgent has not run
+     */
+    get stash() {
+        return this._stash;
+    }
+    /**
+     * Whether the stash is backed by durable storage that survives process restarts.
+     * When true, stash data does not need to be embedded in session snapshots.
+     *
+     * @returns true if the stash storage is not ephemeral
+     */
+    get stashIsDurable() {
+        return this._stashIsDurable;
+    }
+    async _runStrategies(agent, precomputedInputTokens, overflow) {
         const messages = agent.messages;
         const inputTokens = precomputedInputTokens ?? (await agent.model.countTokens(messages));
         const strategyContext = {
             messages,
             agent,
             utilization: agent.model.estimateUtilization(inputTokens),
+            ...(overflow ? { overflow: true } : {}),
+            ...(this._stash ? { stash: this._stash } : {}),
         };
         let anyActed = false;
         for (const strategy of this._strategies) {
             try {
+                if (strategy instanceof EmergencyTruncateStrategy && anyActed)
+                    strategyContext.overflow = false;
                 const acted = await strategy.apply(strategyContext);
                 if (acted) {
                     anyActed = true;

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

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

package/dist/src/context-manager/methods/summarize.d.ts

@@ -4,15 +4,21 @@
  * Compresses text via an LLM call. The method is target-agnostic — it operates
  * on any text (a tool result, a range of messages, raw storage content).
  * Strategies handle selection and placement.
- *
- * @internal
  */
 import type { Model } from '../../models/model.js';
 import { Message } from '../../types/messages.js';
 import type { ContentBlock, ToolResultContent } from '../../types/messages.js';
 export declare const SUMMARIZED_PREFIX = "[Summarized:";
+/**
+ * Format a `[Summarized: ...]` marker with an optional summary body.
+ *
+ * @internal
+ */
+export declare function formatSummarized(description: string, tokens: number, summary?: string): string;
 /**
  * Configuration for the summarize method.
+ *
+ * @experimental
  */
 export interface SummarizeConfig {
     /** Model to use for summarization. When omitted, uses the agent's model. */

package/dist/src/context-manager/methods/summarize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"summarize.d.ts","sourceRoot":"","sources":["../../../../src/context-manager/methods/summarize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAa,OAAO,EAA8B,MAAM,yBAAyB,CAAA;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAG9E,eAAO,MAAM,iBAAiB,iBAAiB,CAAA;AAe/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,KAAK,CAAA;IAEb,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,YAAY,EAAE,EACvB,KAAK,EAAE,KAAK,EACZ,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,YAAY,EAAE,CAOtF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,YAAY,EAAE,CAa5E"}
+{"version":3,"file":"summarize.d.ts","sourceRoot":"","sources":["../../../../src/context-manager/methods/summarize.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAa,OAAO,EAA8B,MAAM,yBAAyB,CAAA;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAG9E,eAAO,MAAM,iBAAiB,iBAAiB,CAAA;AAE/C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAG9F;AAeD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,KAAK,CAAA;IAEb,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,YAAY,EAAE,EACvB,KAAK,EAAE,KAAK,EACZ,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,YAAY,EAAE,CAOtF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,YAAY,EAAE,CAa5E"}

package/dist/src/context-manager/methods/summarize.js

@@ -4,12 +4,19 @@
  * Compresses text via an LLM call. The method is target-agnostic — it operates
  * on any text (a tool result, a range of messages, raw storage content).
  * Strategies handle selection and placement.
- *
- * @internal
  */
 import { JsonBlock, Message, TextBlock, ToolResultBlock } from '../../types/messages.js';
 import { logger } from '../../logging/logger.js';
 export const SUMMARIZED_PREFIX = '[Summarized:';
+/**
+ * Format a `[Summarized: ...]` marker with an optional summary body.
+ *
+ * @internal
+ */
+export function formatSummarized(description, tokens, summary) {
+    const header = `${SUMMARIZED_PREFIX} ${description}, ~${tokens.toLocaleString('en-US')} tokens]`;
+    return summary ? `${header}\n\n${summary}` : header;
+}
 // Subject to change as we benchmark summarization quality.
 const DEFAULT_SYSTEM_PROMPT = [
     'You are a summarization assistant. Produce a concise factual summary that preserves:',

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

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

package/dist/src/context-manager/methods/truncate.d.ts

@@ -2,13 +2,13 @@
  * Truncate reduction method.
  *
  * Replaces content with a preview (head, tail, or head-tail).
- *
- * @internal
  */
 import { TextBlock, ToolResultBlock } from '../../types/messages.js';
 export declare const TRUNCATED_PREFIX = "[Truncated:";
 /**
  * Configuration for the truncate method.
+ *
+ * @experimental
  */
 export interface TruncateConfig {
     /** Number of tokens to keep as preview text. Defaults to 1,000. */

package/dist/src/context-manager/methods/truncate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"truncate.d.ts","sourceRoot":"","sources":["../../../../src/context-manager/methods/truncate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAa,SAAS,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAG/E,eAAO,MAAM,gBAAgB,gBAAgB,CAAA;AAK7C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAA;CACvC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,CA+BlG;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,eAAe,CA8BxG;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,SAAS,CAMtF"}
+{"version":3,"file":"truncate.d.ts","sourceRoot":"","sources":["../../../../src/context-manager/methods/truncate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAa,SAAS,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAG/E,eAAO,MAAM,gBAAgB,gBAAgB,CAAA;AAK7C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAA;CACvC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,CA+BlG;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,eAAe,CA8BxG;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,SAAS,CAMtF"}

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

@@ -2,8 +2,6 @@
  * Truncate reduction method.
  *
  * Replaces content with a preview (head, tail, or head-tail).
- *
- * @internal
  */
 import { JsonBlock, TextBlock, ToolResultBlock } from '../../types/messages.js';
 export const TRUNCATED_PREFIX = '[Truncated:';

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":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAG/E,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAA;AAE7C,MAAM,sBAAsB,GAAG,IAAI,CAAA;AACnC,MAAM,eAAe,GAAG,CAAC,CAAA;AAazB;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,UAAkB,EAAE,MAAuB;IACxF,MAAM,aAAa,GACjB,OAAO,MAAM,EAAE,aAAa,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC;QAChF,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC;QACnC,CAAC,CAAC,sBAAsB,CAAA;IAC5B,MAAM,YAAY,GAAG,aAAa,GAAG,eAAe,CAAA;IACpD,MAAM,WAAW,GAAG,MAAM,EAAE,OAAO,IAAI,UAAU,CAAA;IACjD,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAA;IAElC,IAAI,UAAU,IAAI,YAAY,EAAE,CAAC;QAC/B,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,MAAM,SAAS,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,CAAA;IAClE,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,SAAS,CAAC,CAAA;IACtD,MAAM,SAAS,GAAG,YAAY,GAAG,SAAS,CAAA;IAC1C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAA;IACzC,MAAM,IAAI,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAC5D,MAAM,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAA;IACjD,MAAM,MAAM,GAAG,QAAQ,MAAM,CAAC,cAAc,EAAE,oBAAoB,CAAA;IAClE,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAEjE,MAAM,MAAM,GACV,GAAG,gBAAgB,IAAI,UAAU,IAAI,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,eAAe,CAAC,CAAC,cAAc,EAAE,cAAc;QACtJ,OAAO,CAAA;IAET,IAAI,MAAM,CAAC,MAAM,IAAI,UAAU,EAAE,CAAC;QAChC,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAsB,EAAE,MAAuB;IACrF,MAAM,OAAO,GAAa,EAAE,CAAA;IAC5B,MAAM,MAAM,GAAwB,EAAE,CAAA;IAEtC,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,OAAO,YAAY,SAAS,EAAE,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QAC5B,CAAC;aAAM,IAAI,OAAO,YAAY,SAAS,EAAE,CAAC;YACxC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;QAChD,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACtB,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACnC,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAE9D,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,OAAO,KAAK,CAAA;IACd,CAAC;IAED,OAAO,IAAI,eAAe,CAAC;QACzB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO,EAAE,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC;KAC7C,CAAC,CAAA;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAgB,EAAE,MAAuB;IACzE,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,CAAA;IACnD,IAAI,OAAO,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,IAAI,SAAS,CAAC,OAAO,CAAC,CAAA;AAC/B,CAAC"}
+{"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/presets.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Strategy presets — named building blocks that resolve to concrete strategy configurations.
+ *
+ * Preset definitions (thresholds, methods, conditions) are internal defaults and may
+ * change between releases as we tune based on real-world usage data. Treat the preset
+ * name as the stable contract, not its expansion. Use raw `Offload.*` strategies when
+ * you need a specific, pinned configuration.
+ *
+ * @experimental
+ */
+import type { ContextStrategy } from './types.js';
+/**
+ * Known preset name strings accepted in the strategies array.
+ *
+ * Preset names are the stable contract. The strategies they resolve to may change
+ * between releases.
+ *
+ * - `'proactiveSummarization'` — batch summarize oldest messages at 70% utilization
+ * - `'largeToolOffloading'` — truncate tool results over 2500 tokens to a 1000-token preview
+ * - `'overflowProtection'` — truncate oldest messages when the context window is full
+ * - `'staleToolCleanup'` — drop tool results older than 5 messages
+ */
+export declare const STRATEGY_PRESET_NAMES: readonly ["proactiveSummarization", "largeToolOffloading", "overflowProtection", "staleToolCleanup"];
+/** String union of preset names. */
+export type StrategyPresetName = (typeof STRATEGY_PRESET_NAMES)[number];
+/**
+ * Resolves a preset name to its default strategy array.
+ *
+ * @param name - The preset name
+ * @returns The strategy array for the given preset
+ * @internal
+ */
+export declare function resolvePreset(name: StrategyPresetName): ContextStrategy[];
+/**
+ * Resolves a mixed array of strategies and preset names into a flat strategy array.
+ *
+ * @param entries - Array of raw strategies and/or preset name strings
+ * @returns Flattened array of concrete strategies
+ * @internal
+ */
+export declare function resolveStrategies(entries: (ContextStrategy | StrategyPresetName)[]): ContextStrategy[];
+//# sourceMappingURL=presets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../../src/context-manager/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGjD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,sGAKxB,CAAA;AAEV,oCAAoC;AACpC,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEvE;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,kBAAkB,GAAG,eAAe,EAAE,CAYzE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,CAAC,eAAe,GAAG,kBAAkB,CAAC,EAAE,GAAG,eAAe,EAAE,CAatG"}

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

@@ -0,0 +1,71 @@
+/**
+ * Strategy presets — named building blocks that resolve to concrete strategy configurations.
+ *
+ * Preset definitions (thresholds, methods, conditions) are internal defaults and may
+ * change between releases as we tune based on real-world usage data. Treat the preset
+ * name as the stable contract, not its expansion. Use raw `Offload.*` strategies when
+ * you need a specific, pinned configuration.
+ *
+ * @experimental
+ */
+import { Offload } from './strategies/offload/index.js';
+/**
+ * Known preset name strings accepted in the strategies array.
+ *
+ * Preset names are the stable contract. The strategies they resolve to may change
+ * between releases.
+ *
+ * - `'proactiveSummarization'` — batch summarize oldest messages at 70% utilization
+ * - `'largeToolOffloading'` — truncate tool results over 2500 tokens to a 1000-token preview
+ * - `'overflowProtection'` — truncate oldest messages when the context window is full
+ * - `'staleToolCleanup'` — drop tool results older than 5 messages
+ */
+export const STRATEGY_PRESET_NAMES = [
+    'proactiveSummarization',
+    'largeToolOffloading',
+    'overflowProtection',
+    'staleToolCleanup',
+];
+/**
+ * Resolves a preset name to its default strategy array.
+ *
+ * @param name - The preset name
+ * @returns The strategy array for the given preset
+ * @internal
+ */
+export function resolvePreset(name) {
+    // Defaults are tuning decisions, not API promises — adjust freely.
+    switch (name) {
+        case 'proactiveSummarization':
+            return [Offload.summarize('*').when({ utilization: 0.7, preserveRecent: 0.7 })];
+        case 'largeToolOffloading':
+            return [Offload.truncate('toolResults', { previewTokens: 1000 }).when({ threshold: 2500 })];
+        case 'overflowProtection':
+            return [Offload.truncate('*').when({ utilization: 1.0, preserveRecent: 4 })];
+        case 'staleToolCleanup':
+            return [Offload.drop('toolResults').when({ preserveRecent: 5 })];
+    }
+}
+/**
+ * Resolves a mixed array of strategies and preset names into a flat strategy array.
+ *
+ * @param entries - Array of raw strategies and/or preset name strings
+ * @returns Flattened array of concrete strategies
+ * @internal
+ */
+export function resolveStrategies(entries) {
+    const strategies = [];
+    for (const entry of entries) {
+        if (typeof entry === 'string') {
+            if (!STRATEGY_PRESET_NAMES.includes(entry)) {
+                throw new Error(`Unknown strategy preset: "${entry}". Valid presets: ${STRATEGY_PRESET_NAMES.join(', ')}`);
+            }
+            strategies.push(...resolvePreset(entry));
+        }
+        else {
+            strategies.push(entry);
+        }
+    }
+    return strategies;
+}
+//# sourceMappingURL=presets.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","sourceRoot":"","sources":["../../../src/context-manager/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAA;AAEvD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,wBAAwB;IACxB,qBAAqB;IACrB,oBAAoB;IACpB,kBAAkB;CACV,CAAA;AAKV;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAwB;IACpD,mEAAmE;IACnE,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,wBAAwB;YAC3B,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC,CAAC,CAAA;QACjF,KAAK,qBAAqB;YACxB,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QAC7F,KAAK,oBAAoB;YACvB,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,cAAc,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;QAC9E,KAAK,kBAAkB;YACrB,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACpE,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAiD;IACjF,MAAM,UAAU,GAAsB,EAAE,CAAA;IACxC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,IAAI,CAAC,qBAAqB,CAAC,QAAQ,CAAC,KAA2B,CAAC,EAAE,CAAC;gBACjE,MAAM,IAAI,KAAK,CAAC,6BAA6B,KAAK,qBAAqB,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;YAC5G,CAAC;YACD,UAAU,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,KAA2B,CAAC,CAAC,CAAA;QAChE,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACxB,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAA;AACnB,CAAC"}

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;AAOH,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,CAiDhF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAOrF"}