@strands-agents/sdk 1.8.0 → 1.10.0

package/dist/src/storage/in-memory-storage.d.ts

@@ -0,0 +1,64 @@
+import type { Storage } from './storage.js';
+/**
+ * In-memory {@link Storage} backend backed by a `Map`.
+ *
+ * Useful for testing and for serverless environments where disk access is unavailable.
+ * Content does not survive process restarts — for persistence use {@link LocalFileStorage}
+ * or {@link S3Storage}.
+ *
+ * This is a plain unbounded store with no eviction. Consumers that need eviction
+ * (e.g. the ContextOffloader plugin) manage it themselves.
+ *
+ * Keys are normalized identically to {@link LocalFileStorage}: slash runs are collapsed,
+ * leading/trailing slashes are stripped, and `..` segments are rejected.
+ *
+ * @example
+ * ```typescript
+ * const storage = new InMemoryStorage()
+ * await storage.write('memory/notes.json', new TextEncoder().encode('[]'))
+ * const bytes = await storage.read('memory/notes.json')
+ * ```
+ */
+export declare class InMemoryStorage implements Storage {
+    private readonly _store;
+    /**
+     * Stores `data` under `key`, overwriting any existing value.
+     * Bytes are copied on write to prevent aliasing with the caller's buffer.
+     *
+     * @param key - Opaque, `/`-separated key identifying the value
+     * @param data - Raw bytes to persist
+     * @throws {@link StorageError} if the key is empty or contains `..` segments
+     */
+    write(key: string, data: Uint8Array): Promise<void>;
+    /**
+     * Retrieves the bytes previously stored under `key`.
+     * Returns a copy to prevent aliasing with the internal buffer.
+     *
+     * @param key - The key to read
+     * @returns The stored bytes, or `null` if no value exists for `key`
+     * @throws {@link StorageError} if the key is empty or contains `..` segments
+     */
+    read(key: string): Promise<Uint8Array | null>;
+    /**
+     * Deletes the value stored under `key`. A no-op if the key does not exist.
+     *
+     * @param key - The key to delete
+     * @throws {@link StorageError} if the key is empty or contains `..` segments
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Lists the keys whose names begin with `prefix`, sorted lexicographically.
+     *
+     * @param prefix - Key prefix to match. An empty string matches all keys.
+     * @returns The matching keys, sorted ascending
+     * @throws {@link StorageError} if the prefix contains `..` segments
+     */
+    list(prefix: string): Promise<string[]>;
+    /** Returns a prefixed view of this storage without mutating the original. */
+    namespace(prefix: string): Storage;
+    /**
+     * Removes all stored entries. Useful for resetting state between tests.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=in-memory-storage.d.ts.map

package/dist/src/storage/in-memory-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-storage.d.ts","sourceRoot":"","sources":["../../../src/storage/in-memory-storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAI3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IAEvD;;;;;;;OAOG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD;;;;;;;OAOG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAMnD;;;;;OAKG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC;;;;;;OAMG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAS7C,6EAA6E;IAC7E,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIlC;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/src/storage/in-memory-storage.js

@@ -0,0 +1,85 @@
+import { namespace, normalizeKey, normalizePrefix } from './storage.js';
+/**
+ * In-memory {@link Storage} backend backed by a `Map`.
+ *
+ * Useful for testing and for serverless environments where disk access is unavailable.
+ * Content does not survive process restarts — for persistence use {@link LocalFileStorage}
+ * or {@link S3Storage}.
+ *
+ * This is a plain unbounded store with no eviction. Consumers that need eviction
+ * (e.g. the ContextOffloader plugin) manage it themselves.
+ *
+ * Keys are normalized identically to {@link LocalFileStorage}: slash runs are collapsed,
+ * leading/trailing slashes are stripped, and `..` segments are rejected.
+ *
+ * @example
+ * ```typescript
+ * const storage = new InMemoryStorage()
+ * await storage.write('memory/notes.json', new TextEncoder().encode('[]'))
+ * const bytes = await storage.read('memory/notes.json')
+ * ```
+ */
+export class InMemoryStorage {
+    _store = new Map();
+    /**
+     * Stores `data` under `key`, overwriting any existing value.
+     * Bytes are copied on write to prevent aliasing with the caller's buffer.
+     *
+     * @param key - Opaque, `/`-separated key identifying the value
+     * @param data - Raw bytes to persist
+     * @throws {@link StorageError} if the key is empty or contains `..` segments
+     */
+    async write(key, data) {
+        this._store.set(normalizeKey(key), data.slice());
+    }
+    /**
+     * Retrieves the bytes previously stored under `key`.
+     * Returns a copy to prevent aliasing with the internal buffer.
+     *
+     * @param key - The key to read
+     * @returns The stored bytes, or `null` if no value exists for `key`
+     * @throws {@link StorageError} if the key is empty or contains `..` segments
+     */
+    async read(key) {
+        const value = this._store.get(normalizeKey(key));
+        if (value === undefined)
+            return null;
+        return value.slice();
+    }
+    /**
+     * Deletes the value stored under `key`. A no-op if the key does not exist.
+     *
+     * @param key - The key to delete
+     * @throws {@link StorageError} if the key is empty or contains `..` segments
+     */
+    async delete(key) {
+        this._store.delete(normalizeKey(key));
+    }
+    /**
+     * Lists the keys whose names begin with `prefix`, sorted lexicographically.
+     *
+     * @param prefix - Key prefix to match. An empty string matches all keys.
+     * @returns The matching keys, sorted ascending
+     * @throws {@link StorageError} if the prefix contains `..` segments
+     */
+    async list(prefix) {
+        const normalized = normalizePrefix(prefix);
+        const keys = [];
+        for (const key of this._store.keys()) {
+            if (key.startsWith(normalized))
+                keys.push(key);
+        }
+        return keys.sort();
+    }
+    /** Returns a prefixed view of this storage without mutating the original. */
+    namespace(prefix) {
+        return namespace(this, prefix);
+    }
+    /**
+     * Removes all stored entries. Useful for resetting state between tests.
+     */
+    clear() {
+        this._store.clear();
+    }
+}
+//# sourceMappingURL=in-memory-storage.js.map

package/dist/src/storage/in-memory-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-storage.js","sourceRoot":"","sources":["../../../src/storage/in-memory-storage.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAEvE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,eAAe;IACT,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAA;IAEvD;;;;;;;OAOG;IACH,KAAK,CAAC,KAAK,CAAC,GAAW,EAAE,IAAgB;QACvC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;IAClD,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAA;QAChD,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAA;QACpC,OAAO,KAAK,CAAC,KAAK,EAAE,CAAA;IACtB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAA;IACvC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,CAAC,MAAc;QACvB,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,CAAA;QAC1C,MAAM,IAAI,GAAa,EAAE,CAAA;QACzB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YACrC,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAChD,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,EAAE,CAAA;IACpB,CAAC;IAED,6EAA6E;IAC7E,SAAS,CAAC,MAAc;QACtB,OAAO,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAChC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;CACF"}

package/dist/src/storage/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Unified storage module.
+ *
+ * Provides the {@link Storage} interface and shipped implementations for persisting
+ * raw bytes under string keys. All SDK subsystems that need persistence — sessions,
+ * memory, context offloading, transcripts — consume this interface.
+ *
+ * @example
+ * ```typescript
+ * import { LocalFileStorage, InMemoryStorage } from '@strands-agents/sdk/storage'
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { Storage } from './storage.js';
+export { InMemoryStorage } from './in-memory-storage.js';
+export { LocalFileStorage } from './local-file-storage.js';
+export { S3Storage } from './s3-storage.js';
+export type { S3StorageConfig } from './s3-storage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/src/storage/index.js

@@ -0,0 +1,18 @@
+/**
+ * Unified storage module.
+ *
+ * Provides the {@link Storage} interface and shipped implementations for persisting
+ * raw bytes under string keys. All SDK subsystems that need persistence — sessions,
+ * memory, context offloading, transcripts — consume this interface.
+ *
+ * @example
+ * ```typescript
+ * import { LocalFileStorage, InMemoryStorage } from '@strands-agents/sdk/storage'
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { InMemoryStorage } from './in-memory-storage.js';
+export { LocalFileStorage } from './local-file-storage.js';
+export { S3Storage } from './s3-storage.js';
+//# sourceMappingURL=index.js.map

package/dist/src/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/src/storage/local-file-storage.d.ts

@@ -0,0 +1,81 @@
+import type { Sandbox } from '../sandbox/base.js';
+import type { Storage } from './storage.js';
+/**
+ * Local-filesystem {@link Storage} backend.
+ *
+ * Persists each key as a file under a base directory, mapping the key's `/` segments
+ * onto directory segments. On the host filesystem, writes are atomic (write to a
+ * scratch sibling, then rename) so a crash mid-write never leaves a partially written
+ * file. When bound to a {@link Sandbox} via {@link forSandbox}, all I/O is routed
+ * through that sandbox instead of the host's `node:fs` (atomicity depends on the
+ * sandbox implementation).
+ *
+ * @example
+ * ```typescript
+ * import { LocalFileStorage } from '@strands-agents/sdk/storage'
+ *
+ * const storage = new LocalFileStorage('./.strands/')
+ * await storage.write('sessions/abc/snapshot.json', bytes)
+ * ```
+ */
+export declare class LocalFileStorage implements Storage {
+    private readonly _baseDir;
+    private readonly _sandbox;
+    /**
+     * @param baseDir - Root directory under which keys are stored. Defaults to `./.strands/`.
+     * @param sandbox - Optional sandbox to route I/O through. Usually set via {@link forSandbox}.
+     */
+    constructor(baseDir?: string, sandbox?: Sandbox);
+    /**
+     * Returns a storage instance whose I/O is routed through `sandbox`.
+     *
+     * Instances already bound to a sandbox return themselves unchanged.
+     *
+     * @param sandbox - Sandbox to route the returned instance's I/O through
+     * @returns A new `LocalFileStorage` with the same base directory, routed through `sandbox`
+     */
+    forSandbox(sandbox: Sandbox): LocalFileStorage;
+    /**
+     * Stores `data` under `key`, overwriting any existing value.
+     *
+     * @param key - Opaque, `/`-separated key identifying the value
+     * @param data - Raw bytes to persist
+     * @throws {@link StorageError} if the key is invalid or the write fails
+     */
+    write(key: string, data: Uint8Array): Promise<void>;
+    /**
+     * Retrieves the bytes previously stored under `key`.
+     *
+     * @param key - The key to read
+     * @returns The stored bytes, or `null` if no value exists for `key`
+     * @throws {@link StorageError} if the key is invalid or the read fails
+     */
+    read(key: string): Promise<Uint8Array | null>;
+    /**
+     * Deletes the value stored under `key`. A no-op if the key does not exist.
+     *
+     * @param key - The key to delete
+     * @throws {@link StorageError} if the key is invalid or the delete fails
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Lists the keys whose names begin with `prefix`, sorted lexicographically.
+     *
+     * @param prefix - Key prefix to match. An empty string matches all keys.
+     * @returns The matching keys, sorted ascending
+     * @throws {@link StorageError} if the prefix is invalid or the listing fails
+     */
+    list(prefix: string): Promise<string[]>;
+    private _pathFor;
+    private _listKeysHost;
+    private _listKeysSandbox;
+    /**
+     * Returns a prefixed view of this storage without mutating the original.
+     * The returned view preserves `forSandbox` for single-level namespacing;
+     * nested `.namespace()` calls on the view do not carry sandbox routing.
+     */
+    namespace(prefix: string): Storage & {
+        forSandbox(sandbox: Sandbox): Storage;
+    };
+}
+//# sourceMappingURL=local-file-storage.d.ts.map

package/dist/src/storage/local-file-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-storage.d.ts","sourceRoot":"","sources":["../../../src/storage/local-file-storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAgB3C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,gBAAiB,YAAW,OAAO;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAE9C;;;OAGG;gBACS,OAAO,GAAE,MAAsB,EAAE,OAAO,CAAC,EAAE,OAAO;IAK9D;;;;;;;OAOG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB;IAK9C;;;;;;OAMG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BzD;;;;;;OAMG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAqBnD;;;;;OAKG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBxC;;;;;;OAMG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAa7C,OAAO,CAAC,QAAQ;YAKF,aAAa;YA2Bb,gBAAgB;IA2B9B;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG;QAAE,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE;CAO/E"}

package/dist/src/storage/local-file-storage.js

@@ -0,0 +1,244 @@
+import { StorageError } from '../errors.js';
+import { namespace, normalizeKey, normalizePrefix } from './storage.js';
+/**
+ * Returns true if the error represents a missing or non-directory path (ENOENT or ENOTDIR).
+ *
+ * @param error - The caught error to inspect
+ * @returns Whether the error is a filesystem not-found error
+ */
+function isNotFoundError(error) {
+    if (error === null || typeof error !== 'object' || !('code' in error))
+        return false;
+    return error.code === 'ENOENT' || error.code === 'ENOTDIR';
+}
+/**
+ * Local-filesystem {@link Storage} backend.
+ *
+ * Persists each key as a file under a base directory, mapping the key's `/` segments
+ * onto directory segments. On the host filesystem, writes are atomic (write to a
+ * scratch sibling, then rename) so a crash mid-write never leaves a partially written
+ * file. When bound to a {@link Sandbox} via {@link forSandbox}, all I/O is routed
+ * through that sandbox instead of the host's `node:fs` (atomicity depends on the
+ * sandbox implementation).
+ *
+ * @example
+ * ```typescript
+ * import { LocalFileStorage } from '@strands-agents/sdk/storage'
+ *
+ * const storage = new LocalFileStorage('./.strands/')
+ * await storage.write('sessions/abc/snapshot.json', bytes)
+ * ```
+ */
+export class LocalFileStorage {
+    _baseDir;
+    _sandbox;
+    /**
+     * @param baseDir - Root directory under which keys are stored. Defaults to `./.strands/`.
+     * @param sandbox - Optional sandbox to route I/O through. Usually set via {@link forSandbox}.
+     */
+    constructor(baseDir = './.strands/', sandbox) {
+        this._baseDir = baseDir;
+        this._sandbox = sandbox;
+    }
+    /**
+     * Returns a storage instance whose I/O is routed through `sandbox`.
+     *
+     * Instances already bound to a sandbox return themselves unchanged.
+     *
+     * @param sandbox - Sandbox to route the returned instance's I/O through
+     * @returns A new `LocalFileStorage` with the same base directory, routed through `sandbox`
+     */
+    forSandbox(sandbox) {
+        if (this._sandbox)
+            return this;
+        return new LocalFileStorage(this._baseDir, sandbox);
+    }
+    /**
+     * Stores `data` under `key`, overwriting any existing value.
+     *
+     * @param key - Opaque, `/`-separated key identifying the value
+     * @param data - Raw bytes to persist
+     * @throws {@link StorageError} if the key is invalid or the write fails
+     */
+    async write(key, data) {
+        const normalized = normalizeKey(key);
+        const path = this._pathFor(normalized);
+        if (this._sandbox) {
+            try {
+                await this._sandbox.writeFile(path, data);
+            }
+            catch (error) {
+                throw new StorageError(`Failed to write '${normalized}' to sandbox storage`, { cause: error });
+            }
+            return;
+        }
+        let tmpPath;
+        try {
+            const { mkdir, writeFile, rename } = await import('node:fs/promises');
+            const { dirname } = await import('node:path');
+            await mkdir(dirname(path), { recursive: true });
+            const { randomUUID } = await import('node:crypto');
+            tmpPath = `${path}.__strands_tmp_${randomUUID()}`;
+            await writeFile(tmpPath, data);
+            await rename(tmpPath, path);
+        }
+        catch (error) {
+            if (tmpPath) {
+                const { rm } = await import('node:fs/promises');
+                await rm(tmpPath, { force: true }).catch(() => { });
+            }
+            throw new StorageError(`Failed to write '${normalized}' to local storage`, { cause: error });
+        }
+    }
+    /**
+     * Retrieves the bytes previously stored under `key`.
+     *
+     * @param key - The key to read
+     * @returns The stored bytes, or `null` if no value exists for `key`
+     * @throws {@link StorageError} if the key is invalid or the read fails
+     */
+    async read(key) {
+        const normalized = normalizeKey(key);
+        const path = this._pathFor(normalized);
+        if (this._sandbox) {
+            try {
+                return await this._sandbox.readFile(path);
+            }
+            catch (error) {
+                if (isNotFoundError(error))
+                    return null;
+                throw new StorageError(`Failed to read '${normalized}' from sandbox storage`, { cause: error });
+            }
+        }
+        try {
+            const { readFile } = await import('node:fs/promises');
+            const content = await readFile(path);
+            return new Uint8Array(content);
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw new StorageError(`Failed to read '${normalized}' from local storage`, { cause: error });
+        }
+    }
+    /**
+     * Deletes the value stored under `key`. A no-op if the key does not exist.
+     *
+     * @param key - The key to delete
+     * @throws {@link StorageError} if the key is invalid or the delete fails
+     */
+    async delete(key) {
+        const normalized = normalizeKey(key);
+        const path = this._pathFor(normalized);
+        if (this._sandbox) {
+            try {
+                await this._sandbox.removeFile(path);
+            }
+            catch (error) {
+                if (!isNotFoundError(error)) {
+                    throw new StorageError(`Failed to delete '${normalized}' from sandbox storage`, { cause: error });
+                }
+            }
+            return;
+        }
+        try {
+            const { rm } = await import('node:fs/promises');
+            await rm(path, { force: true });
+        }
+        catch (error) {
+            throw new StorageError(`Failed to delete '${normalized}' from local storage`, { cause: error });
+        }
+    }
+    /**
+     * Lists the keys whose names begin with `prefix`, sorted lexicographically.
+     *
+     * @param prefix - Key prefix to match. An empty string matches all keys.
+     * @returns The matching keys, sorted ascending
+     * @throws {@link StorageError} if the prefix is invalid or the listing fails
+     */
+    async list(prefix) {
+        const normalized = normalizePrefix(prefix);
+        const base = this._baseDir.replace(/\/$/, '');
+        // Narrow the walk to the deepest directory the prefix fully specifies
+        const lastSlash = normalized.lastIndexOf('/');
+        const dirPortion = lastSlash >= 0 ? normalized.slice(0, lastSlash) : '';
+        const startDir = dirPortion ? `${base}/${dirPortion}` : base;
+        const keys = this._sandbox
+            ? await this._listKeysSandbox(startDir, dirPortion)
+            : await this._listKeysHost(startDir, dirPortion);
+        return keys.filter((key) => key.startsWith(normalized)).sort();
+    }
+    _pathFor(key) {
+        const base = this._baseDir.replace(/\/$/, '');
+        return `${base}/${key}`;
+    }
+    async _listKeysHost(dir, keyPrefix) {
+        const { readdir } = await import('node:fs/promises');
+        const walk = async (walkDir, walkPrefix) => {
+            let entries;
+            try {
+                entries = await readdir(walkDir, { withFileTypes: true });
+            }
+            catch (error) {
+                if (isNotFoundError(error))
+                    return [];
+                throw new StorageError(`Failed to list local storage under '${walkPrefix}'`, { cause: error });
+            }
+            const found = [];
+            for (const entry of entries) {
+                if (!entry.isDirectory() && entry.name.includes('.__strands_tmp'))
+                    continue;
+                const childKey = walkPrefix ? `${walkPrefix}/${entry.name}` : entry.name;
+                if (entry.isDirectory()) {
+                    found.push(...(await walk(`${walkDir}/${entry.name}`, childKey)));
+                }
+                else {
+                    found.push(childKey);
+                }
+            }
+            return found;
+        };
+        return walk(dir, keyPrefix);
+    }
+    async _listKeysSandbox(dir, keyPrefix) {
+        const sandbox = this._sandbox;
+        const walk = async (walkDir, walkPrefix) => {
+            let entries;
+            try {
+                entries = await sandbox.listFiles(walkDir);
+            }
+            catch (error) {
+                if (isNotFoundError(error))
+                    return [];
+                throw new StorageError(`Failed to list sandbox storage under '${walkPrefix}'`, { cause: error });
+            }
+            const found = [];
+            for (const entry of entries) {
+                if (!entry.isDir && entry.name.includes('.__strands_tmp'))
+                    continue;
+                const childKey = walkPrefix ? `${walkPrefix}/${entry.name}` : entry.name;
+                if (entry.isDir) {
+                    found.push(...(await walk(`${walkDir}/${entry.name}`, childKey)));
+                }
+                else {
+                    found.push(childKey);
+                }
+            }
+            return found;
+        };
+        return walk(dir, keyPrefix);
+    }
+    /**
+     * Returns a prefixed view of this storage without mutating the original.
+     * The returned view preserves `forSandbox` for single-level namespacing;
+     * nested `.namespace()` calls on the view do not carry sandbox routing.
+     */
+    namespace(prefix) {
+        const view = namespace(this, prefix);
+        return {
+            ...view,
+            forSandbox: (sandbox) => namespace(this.forSandbox(sandbox), prefix),
+        };
+    }
+}
+//# sourceMappingURL=local-file-storage.js.map

package/dist/src/storage/local-file-storage.js.map

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

package/dist/src/storage/s3-storage.d.ts

@@ -0,0 +1,73 @@
+import type { Storage } from './storage.js';
+/** Configuration for {@link S3Storage}. */
+export interface S3StorageConfig {
+    /** Optional key prefix prepended to every key (a leading namespace within the bucket). */
+    prefix?: string;
+    /** AWS region override. When omitted, the SDK's standard resolution chain applies. Cannot be combined with `s3Client`. */
+    region?: string;
+    /** Pre-configured S3 client. Cannot be combined with `region`. */
+    s3Client?: import('@aws-sdk/client-s3').S3Client;
+}
+/**
+ * Amazon S3 {@link Storage} backend.
+ *
+ * Stores each key as an S3 object under an optional prefix. The AWS SDK is loaded
+ * lazily on first use and declared as an optional peer dependency, so consumers that
+ * never construct an `S3Storage` are not required to install `@aws-sdk/client-s3`.
+ *
+ * @example
+ * ```typescript
+ * import { S3Storage } from '@strands-agents/sdk/storage'
+ *
+ * const storage = new S3Storage('my-bucket', { prefix: 'agents/' })
+ * await storage.write('sessions/abc/snapshot.json', bytes)
+ * ```
+ */
+export declare class S3Storage implements Storage {
+    private readonly _bucket;
+    private readonly _prefix;
+    private readonly _region;
+    private _client;
+    /**
+     * @param bucket - Target S3 bucket name
+     * @param config - Optional prefix, region, or pre-configured client
+     * @throws {@link StorageError} if both `region` and `s3Client` are provided
+     */
+    constructor(bucket: string, config?: S3StorageConfig);
+    /**
+     * Stores `data` under `key`, overwriting any existing value.
+     *
+     * @param key - Opaque, `/`-separated key identifying the value
+     * @param data - Raw bytes to persist
+     * @throws {@link StorageError} if the key is invalid or the upload fails
+     */
+    write(key: string, data: Uint8Array): Promise<void>;
+    /**
+     * Retrieves the bytes previously stored under `key`.
+     *
+     * @param key - The key to read
+     * @returns The stored bytes, or `null` if no value exists for `key`
+     * @throws {@link StorageError} if the key is invalid or the download fails
+     */
+    read(key: string): Promise<Uint8Array | null>;
+    /**
+     * Deletes the value stored under `key`. A no-op if the key does not exist.
+     *
+     * @param key - The key to delete
+     * @throws {@link StorageError} if the key is invalid or the delete request fails
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Lists the keys whose names begin with `prefix`, sorted lexicographically.
+     *
+     * @param prefix - Key prefix to match. An empty string matches all keys.
+     * @returns The matching keys, sorted ascending
+     * @throws {@link StorageError} if the prefix is invalid or the list request fails
+     */
+    list(prefix: string): Promise<string[]>;
+    private _getClient;
+    /** Returns a prefixed view of this storage without mutating the original. */
+    namespace(prefix: string): Storage;
+    private _objectKey;
+}
+//# sourceMappingURL=s3-storage.d.ts.map

package/dist/src/storage/s3-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-storage.d.ts","sourceRoot":"","sources":["../../../src/storage/s3-storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAK3C,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0HAA0H;IAC1H,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,oBAAoB,EAAE,QAAQ,CAAA;CACjD;AAID;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAU,YAAW,OAAO;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,OAAO,CAAmD;IAElE;;;;OAIG;gBACS,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe;IAUpD;;;;;;OAMG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAWzD;;;;;;OAMG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAkBnD;;;;;OAKG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxC;;;;;;OAMG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YA6B/B,UAAU;IAOxB,6EAA6E;IAC7E,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIlC,OAAO,CAAC,UAAU;CAGnB"}