@strands-agents/sdk 1.0.0 → 1.1.0

package/dist/src/vended-plugins/context-offloader/index.js

@@ -0,0 +1,21 @@
+/**
+ * Context offloading plugin for Strands Agents.
+ *
+ * This module provides the ContextOffloader plugin and Storage backends for
+ * automatically offloading oversized tool results to external storage, replacing
+ * them with truncated previews and actionable storage references.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@strands-agents/sdk'
+ * import { ContextOffloader, InMemoryStorage } from '@strands-agents/sdk/vended-plugins/context-offloader'
+ *
+ * const agent = new Agent({
+ *   model,
+ *   plugins: [new ContextOffloader({ storage: new InMemoryStorage() })],
+ * })
+ * ```
+ */
+export { ContextOffloader } from './plugin.js';
+export { InMemoryStorage, FileStorage, S3Storage } from './storage.js';
+//# sourceMappingURL=index.js.map

package/dist/src/vended-plugins/context-offloader/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/vended-plugins/context-offloader/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAG9C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA"}

package/dist/src/vended-plugins/context-offloader/plugin.d.ts

@@ -0,0 +1,48 @@
+import type { Plugin } from '../../plugins/plugin.js';
+import type { Tool } from '../../tools/tool.js';
+import type { LocalAgent } from '../../types/agent.js';
+import type { Storage } from './storage.js';
+/** Configuration for the {@link ContextOffloader} plugin. */
+export interface ContextOffloaderConfig {
+    /** Storage backend for persisting offloaded content. */
+    storage: Storage;
+    /** Token threshold above which tool results are offloaded. Defaults to 2,500. */
+    maxResultTokens?: number;
+    /** Number of tokens to keep as an inline preview. Defaults to 1,000. */
+    previewTokens?: number;
+    /** Whether to register the `retrieve_offloaded_content` tool. Defaults to true. */
+    includeRetrievalTool?: boolean;
+}
+/**
+ * Plugin that offloads oversized tool results to reduce context consumption.
+ *
+ * When a tool result exceeds the configured token threshold, this plugin stores
+ * each content block to a storage backend and replaces the in-context result with
+ * a truncated text preview plus per-block storage references.
+ *
+ * @example
+ * ```typescript
+ * import { ContextOffloader, InMemoryStorage } from '@strands-agents/sdk/vended-plugins/context-offloader'
+ *
+ * const agent = new Agent({
+ *   model,
+ *   plugins: [new ContextOffloader({ storage: new InMemoryStorage() })],
+ * })
+ * ```
+ */
+export declare class ContextOffloader implements Plugin {
+    readonly name = "strands:context-offloader";
+    private readonly _storage;
+    private readonly _maxResultTokens;
+    private readonly _previewTokens;
+    private readonly _includeRetrievalTool;
+    private _retrievalTool;
+    constructor(config: ContextOffloaderConfig);
+    initAgent(agent: LocalAgent): void;
+    getTools(): Tool[];
+    private _createRetrievalTool;
+    private _storeBlock;
+    private _buildPreviewText;
+    private _handleToolResult;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/src/vended-plugins/context-offloader/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../../src/vended-plugins/context-offloader/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAA;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAUtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAmE3C,6DAA6D;AAC7D,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,OAAO,EAAE,OAAO,CAAA;IAChB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mFAAmF;IACnF,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAiB,YAAW,MAAM;IAC7C,QAAQ,CAAC,IAAI,+BAA8B;IAE3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAC/C,OAAO,CAAC,cAAc,CAAkB;gBAE5B,MAAM,EAAE,sBAAsB;IAc1C,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAIlC,QAAQ,IAAI,IAAI,EAAE;IAQlB,OAAO,CAAC,oBAAoB;YAoBd,WAAW;IAiCzB,OAAO,CAAC,iBAAiB;YA4BX,iBAAiB;CA4DhC"}

package/dist/src/vended-plugins/context-offloader/plugin.js

@@ -0,0 +1,244 @@
+import { AfterToolCallEvent } from '../../hooks/events.js';
+import { TextBlock, JsonBlock, ToolResultBlock, Message } from '../../types/messages.js';
+import { ImageBlock, VideoBlock, DocumentBlock } from '../../types/media.js';
+import { tool } from '../../tools/tool-factory.js';
+import { z } from 'zod';
+import { logger } from '../../logging/logger.js';
+const CHARS_PER_TOKEN = 4;
+const DEFAULT_MAX_RESULT_TOKENS = 2_500;
+const DEFAULT_PREVIEW_TOKENS = 1_000;
+const RETRIEVAL_TOOL_NAME = 'retrieve_offloaded_content';
+function slicePreview(text, previewTokens) {
+    const maxChars = previewTokens * CHARS_PER_TOKEN;
+    if (text.length <= maxChars)
+        return text;
+    return text.slice(0, maxChars);
+}
+function getBytes(block) {
+    if (block instanceof ImageBlock && block.source.type === 'imageSourceBytes') {
+        return block.source.bytes;
+    }
+    if (block instanceof VideoBlock && block.source.type === 'videoSourceBytes') {
+        return block.source.bytes;
+    }
+    if (block instanceof DocumentBlock) {
+        if (block.source.type === 'documentSourceBytes')
+            return block.source.bytes;
+        if (block.source.type === 'documentSourceText')
+            return new TextEncoder().encode(block.source.text);
+    }
+    return undefined;
+}
+function decodeStoredContent(content, contentType, reference) {
+    if (contentType.startsWith('text/')) {
+        return new TextDecoder().decode(content);
+    }
+    if (contentType === 'application/json') {
+        const text = new TextDecoder().decode(content);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    // Return native content blocks for binary types so the agent sees the actual content.
+    // FunctionTool._wrapInToolResult passes ImageBlock/VideoBlock/DocumentBlock through as-is
+    // at runtime, even though the callback type signature only accepts JSONValue.
+    if (contentType.startsWith('image/')) {
+        const format = contentType.split('/').pop();
+        return new ImageBlock({
+            format: format,
+            source: { bytes: content },
+        });
+    }
+    if (contentType.startsWith('video/')) {
+        const format = contentType.split('/').pop();
+        return new VideoBlock({
+            format: format,
+            source: { bytes: content },
+        });
+    }
+    if (contentType.startsWith('application/')) {
+        const format = contentType.split('/').pop();
+        return new DocumentBlock({
+            format: format,
+            name: reference,
+            source: { bytes: content },
+        });
+    }
+    return new TextDecoder('utf-8', { fatal: false }).decode(content);
+}
+/**
+ * Plugin that offloads oversized tool results to reduce context consumption.
+ *
+ * When a tool result exceeds the configured token threshold, this plugin stores
+ * each content block to a storage backend and replaces the in-context result with
+ * a truncated text preview plus per-block storage references.
+ *
+ * @example
+ * ```typescript
+ * import { ContextOffloader, InMemoryStorage } from '@strands-agents/sdk/vended-plugins/context-offloader'
+ *
+ * const agent = new Agent({
+ *   model,
+ *   plugins: [new ContextOffloader({ storage: new InMemoryStorage() })],
+ * })
+ * ```
+ */
+export class ContextOffloader {
+    name = 'strands:context-offloader';
+    _storage;
+    _maxResultTokens;
+    _previewTokens;
+    _includeRetrievalTool;
+    _retrievalTool;
+    constructor(config) {
+        const maxResultTokens = config.maxResultTokens ?? DEFAULT_MAX_RESULT_TOKENS;
+        const previewTokens = config.previewTokens ?? DEFAULT_PREVIEW_TOKENS;
+        if (maxResultTokens <= 0)
+            throw new Error('maxResultTokens must be positive');
+        if (previewTokens < 0)
+            throw new Error('previewTokens must be non-negative');
+        if (previewTokens >= maxResultTokens)
+            throw new Error('previewTokens must be less than maxResultTokens');
+        this._storage = config.storage;
+        this._maxResultTokens = maxResultTokens;
+        this._previewTokens = previewTokens;
+        this._includeRetrievalTool = config.includeRetrievalTool ?? true;
+    }
+    initAgent(agent) {
+        agent.addHook(AfterToolCallEvent, (event) => this._handleToolResult(event));
+    }
+    getTools() {
+        if (!this._includeRetrievalTool)
+            return [];
+        if (!this._retrievalTool) {
+            this._retrievalTool = this._createRetrievalTool();
+        }
+        return [this._retrievalTool];
+    }
+    _createRetrievalTool() {
+        const storage = this._storage;
+        return tool({
+            name: RETRIEVAL_TOOL_NAME,
+            description: 'Retrieve offloaded content by reference. Use this tool when you see a placeholder with a reference (ref: ...) and need the full content. Only use this as a fallback if the data cannot be accessed using your existing tools.',
+            inputSchema: z.object({
+                reference: z.string().describe('The reference string from the offload placeholder.'),
+            }),
+            callback: async (input) => {
+                try {
+                    const result = await storage.retrieve(input.reference);
+                    return decodeStoredContent(result.content, result.contentType, input.reference);
+                }
+                catch {
+                    return `Error: reference not found: ${input.reference}`;
+                }
+            },
+        });
+    }
+    async _storeBlock(block, key) {
+        if (block instanceof TextBlock && block.text) {
+            const ref = await this._storage.store(key, new TextEncoder().encode(block.text), 'text/plain');
+            return { ref, contentType: 'text/plain', description: `text, ${block.text.length.toLocaleString()} chars` };
+        }
+        if (block instanceof JsonBlock) {
+            const jsonStr = JSON.stringify(block.json, null, 2);
+            const jsonBytes = new TextEncoder().encode(jsonStr);
+            const ref = await this._storage.store(key, jsonBytes, 'application/json');
+            return { ref, contentType: 'application/json', description: `json, ${jsonBytes.length.toLocaleString()} bytes` };
+        }
+        if (block instanceof ImageBlock || block instanceof VideoBlock || block instanceof DocumentBlock) {
+            const bytes = getBytes(block);
+            const contentType = block instanceof ImageBlock
+                ? `image/${block.format}`
+                : block instanceof VideoBlock
+                    ? `video/${block.format}`
+                    : `application/${block.format}`;
+            const label = block instanceof DocumentBlock ? block.name : contentType;
+            if (bytes) {
+                const ref = await this._storage.store(key, bytes, contentType);
+                return { ref, contentType, description: `${label}, ${bytes.length.toLocaleString()} bytes` };
+            }
+            return { ref: '', contentType, description: `${label}, 0 bytes` };
+        }
+        logger.warn('unsupported content block type encountered during offloading, skipping');
+        return { ref: '', contentType: 'unknown', description: 'unknown block type' };
+    }
+    _buildPreviewText(content, references, tokenCount, fullText) {
+        const preview = fullText ? slicePreview(fullText, this._previewTokens) : '';
+        const refLines = references
+            .filter((r) => r.ref)
+            .map((r) => `  ${r.ref} (${r.description})`)
+            .join('\n');
+        let guidance = 'Tool result was offloaded to external storage due to size.\n' +
+            'Use the preview below to answer if possible.\n' +
+            'Use your available tools to selectively access the data you need.';
+        if (this._includeRetrievalTool) {
+            guidance += '\nYou can also use retrieve_offloaded_content with a reference to get the full content.';
+        }
+        return (`[Offloaded: ${content.length} blocks, ~${tokenCount.toLocaleString()} tokens]\n` +
+            `${guidance}\n\n` +
+            `${preview}\n\n` +
+            `[Stored references:]\n${refLines}`);
+    }
+    async _handleToolResult(event) {
+        if (event.result.status === 'error')
+            return;
+        // Skip results from the retrieval tool to prevent circular offloading
+        if (this._includeRetrievalTool && event.toolUse.name === RETRIEVAL_TOOL_NAME)
+            return;
+        const content = event.result.content;
+        const toolUseId = event.result.toolUseId;
+        const tokenCount = await event.agent.model.countTokens([new Message({ role: 'user', content: [event.result] })]);
+        if (tokenCount <= this._maxResultTokens)
+            return;
+        // Extract text preview from text/JSON blocks
+        const textParts = [];
+        for (const block of content) {
+            if (block instanceof TextBlock && block.text)
+                textParts.push(block.text);
+            else if (block instanceof JsonBlock)
+                textParts.push(JSON.stringify(block.json, null, 2));
+        }
+        const fullText = textParts.join('\n');
+        // Store each content block to the storage backend
+        let references;
+        try {
+            references = await Promise.all(content.map((block, i) => this._storeBlock(block, `${toolUseId}_${i}`)));
+        }
+        catch (err) {
+            logger.warn(`tool_use_id=<${toolUseId}> | failed to offload tool result, keeping original`, err);
+            return;
+        }
+        logger.debug(`tool_use_id=<${toolUseId}>, blocks=<${references.length}>, tokens=<${tokenCount}> | tool result offloaded`);
+        // Build replacement content: preview text + media placeholders
+        const newContent = [
+            new TextBlock(this._buildPreviewText(content, references, tokenCount, fullText)),
+        ];
+        for (let i = 0; i < content.length; i++) {
+            const block = content[i];
+            const ref = references[i]?.ref ?? '';
+            if (block instanceof TextBlock || block instanceof JsonBlock)
+                continue;
+            const bytes = getBytes(block);
+            const size = bytes ? bytes.length : 0;
+            let label;
+            if (block instanceof ImageBlock)
+                label = `image: ${block.format}`;
+            else if (block instanceof VideoBlock)
+                label = `video: ${block.format}`;
+            else if (block instanceof DocumentBlock)
+                label = `document: ${block.format}, ${block.name}`;
+            if (label) {
+                newContent.push(new TextBlock(`[${label}, ${size} bytes${ref ? ` | ref: ${ref}` : ''}]`));
+            }
+        }
+        event.result = new ToolResultBlock({
+            toolUseId: event.result.toolUseId,
+            status: event.result.status,
+            content: newContent,
+        });
+    }
+}
+//# sourceMappingURL=plugin.js.map

package/dist/src/vended-plugins/context-offloader/plugin.js.map

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

package/dist/src/vended-plugins/context-offloader/storage.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Storage backends for offloaded tool result content.
+ *
+ * This module defines the {@link Storage} interface and provides three built-in
+ * implementations: {@link InMemoryStorage}, {@link FileStorage}, and {@link S3Storage}.
+ * Each content block from a tool result is stored individually with its content type preserved.
+ */
+/**
+ * Backend for storing and retrieving offloaded content blocks.
+ *
+ * Implement this interface to create custom storage backends (e.g., Redis, DynamoDB).
+ * The SDK ships three built-in implementations: {@link InMemoryStorage},
+ * {@link FileStorage}, and {@link S3Storage}.
+ */
+export interface Storage {
+    /**
+     * Store content and return a reference identifier.
+     *
+     * @param key - Unique key for this content block
+     * @param content - Raw content bytes to store
+     * @param contentType - MIME type of the content (e.g., "text/plain", "image/png")
+     * @returns Reference string for later retrieval
+     */
+    store(key: string, content: Uint8Array, contentType?: string): Promise<string>;
+    /**
+     * Retrieve previously stored content by reference.
+     *
+     * @param reference - Reference returned by a previous {@link store} call
+     * @returns Content bytes and content type
+     * @throws Error if the reference is not found
+     */
+    retrieve(reference: string): Promise<{
+        content: Uint8Array;
+        contentType: string;
+    }>;
+}
+/**
+ * In-memory storage backend.
+ *
+ * Useful for testing and serverless environments where disk access is not available.
+ * Content accumulates for the lifetime of this instance; call {@link clear} to free memory.
+ */
+export declare class InMemoryStorage implements Storage {
+    private _store;
+    private _counter;
+    /** {@inheritdoc} */
+    store(key: string, content: Uint8Array, contentType?: string): Promise<string>;
+    /** {@inheritdoc} */
+    retrieve(reference: string): Promise<{
+        content: Uint8Array;
+        contentType: string;
+    }>;
+    /** Remove all stored content. */
+    clear(): void;
+}
+/**
+ * File-based storage backend.
+ *
+ * Stores offloaded content as files on disk. File extensions are derived from the
+ * content type. A `.metadata.json` sidecar file tracks content types across restarts.
+ * References are file paths preserving the configured artifact directory form.
+ *
+ * @param artifactDir - Directory path where artifact files will be stored
+ */
+export declare class FileStorage implements Storage {
+    private static readonly METADATA_FILE;
+    private readonly _artifactDir;
+    private _counter;
+    private _contentTypes;
+    private _metadataLoaded;
+    private _metadataWriteChain;
+    constructor(artifactDir?: string);
+    private static _extensionFor;
+    private _ensureDir;
+    private _loadMetadata;
+    private _saveMetadata;
+    /** {@inheritdoc} */
+    store(key: string, content: Uint8Array, contentType?: string): Promise<string>;
+    /** {@inheritdoc} */
+    retrieve(reference: string): Promise<{
+        content: Uint8Array;
+        contentType: string;
+    }>;
+}
+/**
+ * S3-based storage backend.
+ *
+ * Stores offloaded content as S3 objects. Content type is preserved as S3 object metadata.
+ * References are `s3://` URIs for direct access via AWS CLI or SDK.
+ *
+ * @param bucket - S3 bucket name
+ * @param options - Optional configuration (prefix, region, pre-configured S3Client)
+ */
+export declare class S3Storage implements Storage {
+    private readonly _bucket;
+    private readonly _prefix;
+    private _client;
+    private readonly _region;
+    private _counter;
+    constructor(bucket: string, options?: {
+        prefix?: string;
+        region?: string;
+        s3Client?: import('@aws-sdk/client-s3').S3Client;
+    });
+    private _getClient;
+    /** {@inheritdoc} */
+    store(key: string, content: Uint8Array, contentType?: string): Promise<string>;
+    /** {@inheritdoc} */
+    retrieve(reference: string): Promise<{
+        content: Uint8Array;
+        contentType: string;
+    }>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/src/vended-plugins/context-offloader/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../../src/vended-plugins/context-offloader/storage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE9E;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACnF;AASD;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,MAAM,CAAkE;IAChF,OAAO,CAAC,QAAQ,CAAI;IAEpB,oBAAoB;IACd,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,GAAE,MAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAOlG,oBAAoB;IACd,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAQxF,iCAAiC;IACjC,KAAK,IAAI,IAAI;CAGd;AAED;;;;;;;;GAQG;AACH,qBAAa,WAAY,YAAW,OAAO;IACzC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAmB;IACxD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,mBAAmB,CAAmC;gBAElD,WAAW,GAAE,MAAsB;IAI/C,OAAO,CAAC,MAAM,CAAC,aAAa;YAKd,UAAU;YAUV,aAAa;YAWb,aAAa;IAM3B,oBAAoB;IACd,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,GAAE,MAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBlG,oBAAoB;IACd,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CAoBzF;AAED;;;;;;;;GAQG;AACH,qBAAa,SAAU,YAAW,OAAO;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,OAAO,CAAmD;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAI;gBAGlB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,oBAAoB,EAAE,QAAQ,CAAA;KAAE;YAQpF,UAAU;IAOxB,oBAAoB;IACd,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,GAAE,MAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBlG,oBAAoB;IACd,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CAgCzF"}

package/dist/src/vended-plugins/context-offloader/storage.js

@@ -0,0 +1,204 @@
+/**
+ * Storage backends for offloaded tool result content.
+ *
+ * This module defines the {@link Storage} interface and provides three built-in
+ * implementations: {@link InMemoryStorage}, {@link FileStorage}, and {@link S3Storage}.
+ * Each content block from a tool result is stored individually with its content type preserved.
+ */
+function sanitizeId(rawId) {
+    return rawId
+        .replace(/\.\./g, '_')
+        .replace(/[/\\]/g, '_')
+        .replace(/[^\w\-.]/g, '_');
+}
+/**
+ * In-memory storage backend.
+ *
+ * Useful for testing and serverless environments where disk access is not available.
+ * Content accumulates for the lifetime of this instance; call {@link clear} to free memory.
+ */
+export class InMemoryStorage {
+    _store = new Map();
+    _counter = 0;
+    /** {@inheritdoc} */
+    async store(key, content, contentType = 'text/plain') {
+        this._counter++;
+        const reference = `mem_${this._counter}_${key}`;
+        this._store.set(reference, { content, contentType });
+        return reference;
+    }
+    /** {@inheritdoc} */
+    async retrieve(reference) {
+        const entry = this._store.get(reference);
+        if (!entry) {
+            throw new Error(`Reference not found: ${reference}`);
+        }
+        return entry;
+    }
+    /** Remove all stored content. */
+    clear() {
+        this._store.clear();
+    }
+}
+/**
+ * File-based storage backend.
+ *
+ * Stores offloaded content as files on disk. File extensions are derived from the
+ * content type. A `.metadata.json` sidecar file tracks content types across restarts.
+ * References are file paths preserving the configured artifact directory form.
+ *
+ * @param artifactDir - Directory path where artifact files will be stored
+ */
+export class FileStorage {
+    static METADATA_FILE = '.metadata.json';
+    _artifactDir;
+    _counter = 0;
+    _contentTypes = {};
+    _metadataLoaded = false;
+    _metadataWriteChain = Promise.resolve();
+    constructor(artifactDir = './artifacts') {
+        this._artifactDir = artifactDir;
+    }
+    static _extensionFor(contentType) {
+        if (contentType === 'text/plain')
+            return '.txt';
+        return `.${contentType.split('/').pop()}`;
+    }
+    async _ensureDir() {
+        const fs = await import('node:fs/promises');
+        await fs.mkdir(this._artifactDir, { recursive: true });
+        if (!this._metadataLoaded) {
+            this._contentTypes = await this._loadMetadata(fs);
+            this._metadataLoaded = true;
+        }
+        return fs;
+    }
+    async _loadMetadata(fs) {
+        const path = await import('node:path');
+        const metadataPath = path.join(this._artifactDir, FileStorage.METADATA_FILE);
+        try {
+            const raw = await fs.readFile(metadataPath, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return {};
+        }
+    }
+    async _saveMetadata(fs) {
+        const path = await import('node:path');
+        const metadataPath = path.join(this._artifactDir, FileStorage.METADATA_FILE);
+        await fs.writeFile(metadataPath, JSON.stringify(this._contentTypes), 'utf-8');
+    }
+    /** {@inheritdoc} */
+    async store(key, content, contentType = 'text/plain') {
+        const fs = await this._ensureDir();
+        const path = await import('node:path');
+        const sanitizedKey = sanitizeId(key);
+        const timestampMs = Date.now();
+        this._counter++;
+        const ext = FileStorage._extensionFor(contentType);
+        const filename = `${timestampMs}_${this._counter}_${sanitizedKey}${ext}`;
+        this._contentTypes[filename] = contentType;
+        this._metadataWriteChain = this._metadataWriteChain.then(() => this._saveMetadata(fs));
+        await this._metadataWriteChain;
+        const filePath = path.join(this._artifactDir, filename);
+        await fs.writeFile(filePath, content);
+        return filePath;
+    }
+    /** {@inheritdoc} */
+    async retrieve(reference) {
+        const fs = await this._ensureDir();
+        const path = await import('node:path');
+        const filePath = path.resolve(this._artifactDir, reference);
+        const resolvedDir = path.resolve(this._artifactDir);
+        if (!filePath.startsWith(resolvedDir)) {
+            throw new Error(`Reference not found: ${reference}`);
+        }
+        const filename = path.basename(filePath);
+        try {
+            const content = await fs.readFile(filePath);
+            const contentType = this._contentTypes[filename] ?? 'application/octet-stream';
+            return { content: new Uint8Array(content), contentType };
+        }
+        catch {
+            throw new Error(`Reference not found: ${reference}`);
+        }
+    }
+}
+/**
+ * S3-based storage backend.
+ *
+ * Stores offloaded content as S3 objects. Content type is preserved as S3 object metadata.
+ * References are `s3://` URIs for direct access via AWS CLI or SDK.
+ *
+ * @param bucket - S3 bucket name
+ * @param options - Optional configuration (prefix, region, pre-configured S3Client)
+ */
+export class S3Storage {
+    _bucket;
+    _prefix;
+    _client;
+    _region;
+    _counter = 0;
+    constructor(bucket, options) {
+        this._bucket = bucket;
+        this._prefix = options?.prefix ? options.prefix.replace(/\/+$/, '') + '/' : '';
+        this._client = options?.s3Client;
+        this._region = options?.region ?? 'us-east-1';
+    }
+    async _getClient() {
+        if (this._client)
+            return this._client;
+        const { S3Client } = await import('@aws-sdk/client-s3');
+        this._client = new S3Client({ region: this._region });
+        return this._client;
+    }
+    /** {@inheritdoc} */
+    async store(key, content, contentType = 'text/plain') {
+        const client = await this._getClient();
+        const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+        const sanitizedKey = sanitizeId(key);
+        const timestampMs = Date.now();
+        this._counter++;
+        const s3Key = `${this._prefix}${timestampMs}_${this._counter}_${sanitizedKey}`;
+        await client.send(new PutObjectCommand({
+            Bucket: this._bucket,
+            Key: s3Key,
+            Body: content,
+            ContentType: contentType,
+        }));
+        return `s3://${this._bucket}/${s3Key}`;
+    }
+    /** {@inheritdoc} */
+    async retrieve(reference) {
+        const client = await this._getClient();
+        const { GetObjectCommand } = await import('@aws-sdk/client-s3');
+        // Accept both s3:// URIs and raw keys
+        let s3Key = reference;
+        const uriMatch = reference.match(/^s3:\/\/([^/]+)\/(.+)$/);
+        if (uriMatch?.[1] && uriMatch[2]) {
+            if (uriMatch[1] !== this._bucket) {
+                throw new Error(`Reference not found: ${reference} (bucket mismatch)`);
+            }
+            s3Key = uriMatch[2];
+        }
+        try {
+            const response = await client.send(new GetObjectCommand({
+                Bucket: this._bucket,
+                Key: s3Key,
+            }));
+            const body = await response.Body?.transformToByteArray();
+            if (!body)
+                throw new Error(`Reference not found: ${reference}`);
+            const contentType = response.ContentType ?? 'application/octet-stream';
+            return { content: new Uint8Array(body), contentType };
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'NoSuchKey') {
+                throw new Error(`Reference not found: ${reference}`);
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=storage.js.map