@strands-agents/sdk 0.2.2 → 0.4.0

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

@@ -0,0 +1,144 @@
+import { promises as fs } from 'fs';
+import { join, dirname } from 'path';
+import { SessionError } from '../errors.js';
+import { validateIdentifier } from './validation.js';
+const MANIFEST = 'manifest.json';
+const SNAPSHOT_LATEST = 'snapshot_latest.json';
+const IMMUTABLE_HISTORY = 'immutable_history';
+const SNAPSHOT_REGEX = /snapshot_(\d+)\.json$/;
+const SCHEMA_VERSION = '1.0';
+const DEFAULT_SNAPSHOT_ID = '1';
+/**
+ * File-based implementation of SnapshotStorage for persisting session snapshots
+ */
+export class FileStorage {
+    /** Base directory path */
+    _baseDir;
+    /**
+     * Creates new FileStorage instance
+     * @param baseDir - Base directory path for storing snapshots
+     */
+    constructor(baseDir) {
+        this._baseDir = baseDir;
+    }
+    /**
+     * Generates file path for session scope snapshots
+     */
+    _getPath(location, filename) {
+        validateIdentifier(location.sessionId);
+        validateIdentifier(location.scopeId);
+        return join(this._baseDir, location.sessionId, 'scopes', location.scope, location.scopeId, 'snapshots', filename);
+    }
+    /**
+     * Saves snapshot to file, optionally marking as latest
+     */
+    async saveSnapshot(params) {
+        await this._writeJSON(this._getHistorySnapshotPath(params.location, params.snapshotId), params.snapshot);
+        if (params.isLatest) {
+            await this._writeJSON(this._getLatestSnapshotPath(params.location), params.snapshot);
+        }
+    }
+    /**
+     * Loads snapshot by ID or latest if null
+     */
+    async loadSnapshot(params) {
+        const path = params.snapshotId === undefined
+            ? this._getLatestSnapshotPath(params.location)
+            : this._getHistorySnapshotPath(params.location, params.snapshotId);
+        return this._readJSON(path);
+    }
+    /**
+     * Checks if an error is a file not found error (ENOENT)
+     */
+    _isFileNotFoundError(error) {
+        return error !== null && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
+    }
+    /**
+     * Lists all snapshot IDs for a session scope.
+     *
+     * TODO: Add pagination support for long-running agents with many snapshots.
+     * Future signature could be:
+     * ```typescript
+     * listSnapshots(params: {
+     *   sessionId: string
+     *   scope: Scope
+     *   limit?: number        // Max results to return (e.g., 100)
+     *   startAfter?: string   // Snapshot ID to start after (for cursor-based pagination)
+     * }): Promise<{ snapshotIds: string[]; nextToken?: string }>
+     * ```
+     */
+    async listSnapshotIds(params) {
+        const dirPath = this._getPath(params.location, IMMUTABLE_HISTORY);
+        try {
+            const files = await fs.readdir(dirPath);
+            return files
+                .map((file) => file.match(SNAPSHOT_REGEX)?.[1])
+                .filter((id) => id !== undefined)
+                .sort((a, b) => parseInt(a) - parseInt(b));
+        }
+        catch (error) {
+            if (this._isFileNotFoundError(error)) {
+                return [];
+            }
+            throw new SessionError(`Failed to list snapshots for session ${params.location.sessionId}`, { cause: error });
+        }
+    }
+    /**
+     * Loads manifest or returns default if not found
+     */
+    async loadManifest(params) {
+        const path = this._getPath(params.location, MANIFEST);
+        const manifest = await this._readJSON(path);
+        return (manifest ?? {
+            schemaVersion: SCHEMA_VERSION,
+            nextSnapshotId: DEFAULT_SNAPSHOT_ID,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    /**
+     * Saves manifest to file
+     */
+    async saveManifest(params) {
+        const path = this._getPath(params.location, MANIFEST);
+        await this._writeJSON(path, params.manifest);
+    }
+    /**
+     * Writes JSON data to file atomically
+     */
+    async _writeJSON(path, data) {
+        try {
+            await fs.mkdir(dirname(path), { recursive: true });
+            const tmpPath = `${path}.tmp`;
+            await fs.writeFile(tmpPath, JSON.stringify(data, null, 2), 'utf8');
+            await fs.rename(tmpPath, path);
+        }
+        catch (error) {
+            throw new SessionError(`Failed to write file ${path}`, { cause: error });
+        }
+    }
+    /**
+     * Reads and parses JSON from file
+     */
+    async _readJSON(path) {
+        try {
+            const content = await fs.readFile(path, 'utf8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            if (this._isFileNotFoundError(error)) {
+                return null;
+            }
+            if (error instanceof SyntaxError) {
+                throw new SessionError(`Invalid JSON in file ${path}`, { cause: error });
+            }
+            throw new SessionError(`File system error reading ${path}`, { cause: error });
+        }
+    }
+    _getLatestSnapshotPath(location) {
+        return this._getPath(location, SNAPSHOT_LATEST);
+    }
+    _getHistorySnapshotPath(location, snapshotId) {
+        return this._getPath(location, `${IMMUTABLE_HISTORY}/snapshot_${String(snapshotId).padStart(5, '0')}.json`);
+    }
+}
+//# sourceMappingURL=file-storage.js.map

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

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

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

@@ -0,0 +1,19 @@
+/**
+ * Session management module for conversation persistence and restoration.
+ *
+ * Provides snapshot-based session management with pluggable storage backends.
+ * Supports conversation history, state persistence, and branching.
+ *
+ * @example
+ * ```typescript
+ * import { FileStorage, SnapshotStorage } from '@strands/agents/session'
+ *
+ * const storage = new FileStorage('./sessions')
+ * await storage.saveSnapshot({ sessionId, scope, isLatest: true, snapshot })
+ * ```
+ */
+export type { Scope, Snapshot, SnapshotManifest, SnapshotTriggerCallback } from './types.js';
+export type { SessionStorage, SnapshotStorage, SnapshotLocation } from './storage.js';
+export { FileStorage } from './file-storage.js';
+export { S3Storage, type S3StorageConfig } from './s3-storage.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAG5F,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/src/session/index.js

@@ -0,0 +1,18 @@
+/**
+ * Session management module for conversation persistence and restoration.
+ *
+ * Provides snapshot-based session management with pluggable storage backends.
+ * Supports conversation history, state persistence, and branching.
+ *
+ * @example
+ * ```typescript
+ * import { FileStorage, SnapshotStorage } from '@strands/agents/session'
+ *
+ * const storage = new FileStorage('./sessions')
+ * await storage.saveSnapshot({ sessionId, scope, isLatest: true, snapshot })
+ * ```
+ */
+// Storage implementations
+export { FileStorage } from './file-storage.js';
+export { S3Storage } from './s3-storage.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,0BAA0B;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,SAAS,EAAwB,MAAM,iBAAiB,CAAA"}

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

@@ -0,0 +1,93 @@
+import { S3Client } from '@aws-sdk/client-s3';
+import type { SnapshotStorage, SnapshotLocation } from './storage.js';
+import type { Snapshot, SnapshotManifest } from './types.js';
+/**
+ * Configuration options for S3Storage
+ */
+export type S3StorageConfig = {
+    /** S3 bucket name */
+    bucket: string;
+    /** Optional key prefix for all objects */
+    prefix?: string;
+    /** AWS region (default: us-east-1). Cannot be used with s3Client */
+    region?: string;
+    /** Pre-configured S3 client. Cannot be used with region */
+    s3Client?: S3Client;
+};
+/**
+ * S3-based implementation of SnapshotStorage for persisting session snapshots
+ */
+export declare class S3Storage implements SnapshotStorage {
+    /** S3 client instance */
+    private readonly _s3;
+    /** S3 bucket name */
+    private readonly _bucket;
+    /** Key prefix for all objects */
+    private readonly _prefix;
+    /**
+     * Creates new S3Storage instance
+     * @param config - Configuration options
+     */
+    constructor(config: S3StorageConfig);
+    /**
+     * Generates S3 key path for session scope snapshots
+     */
+    private _getKey;
+    /**
+     * Saves snapshot to S3, optionally marking as latest
+     */
+    saveSnapshot(params: {
+        location: SnapshotLocation;
+        snapshotId: string;
+        isLatest: boolean;
+        snapshot: Snapshot;
+    }): Promise<void>;
+    /**
+     * Loads snapshot by ID or latest if undefined
+     */
+    loadSnapshot(params: {
+        location: SnapshotLocation;
+        snapshotId?: string;
+    }): Promise<Snapshot | null>;
+    /**
+     * Lists all snapshot IDs for a session scope.
+     *
+     * TODO: Add pagination support for long-running agents with many snapshots.
+     * Future signature could be:
+     * ```typescript
+     * listSnapshots(params: {
+     *   sessionId: string
+     *   scope: Scope
+     *   limit?: number        // Max results to return (e.g., 100)
+     *   startAfter?: string   // Snapshot ID to start after (for cursor-based pagination)
+     * }): Promise<{ snapshotIds: string[]; nextToken?: string }>
+     * ```
+     */
+    listSnapshotIds(params: {
+        location: SnapshotLocation;
+    }): Promise<string[]>;
+    /**
+     * Loads manifest or returns default if not found
+     */
+    loadManifest(params: {
+        location: SnapshotLocation;
+    }): Promise<SnapshotManifest>;
+    /**
+     * Saves manifest to S3
+     */
+    saveManifest(params: {
+        location: SnapshotLocation;
+        manifest: SnapshotManifest;
+    }): Promise<void>;
+    /**
+     * Writes JSON data to S3
+     */
+    private _writeJSON;
+    /**
+     * Reads and parses JSON from S3
+     */
+    private _readJSON;
+    private _getLatestSnapshotKey;
+    private _getHistorySnapshotKey;
+}
+//# sourceMappingURL=s3-storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"s3-storage.d.ts","sourceRoot":"","sources":["../../../src/session/s3-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAA4D,MAAM,oBAAoB,CAAA;AAEvG,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAW5D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB,CAAA;AAED;;GAEG;AACH,qBAAa,SAAU,YAAW,eAAe;IAC/C,yBAAyB;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAU;IAC9B,qBAAqB;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,iCAAiC;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAEhC;;;OAGG;gBACS,MAAM,EAAE,eAAe;IAUnC;;OAEG;IACH,OAAO,CAAC,OAAO;IAOf;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QACzB,QAAQ,EAAE,gBAAgB,CAAA;QAC1B,UAAU,EAAE,MAAM,CAAA;QAClB,QAAQ,EAAE,OAAO,CAAA;QACjB,QAAQ,EAAE,QAAQ,CAAA;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjB;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAQzG;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgBhF;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAarF;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrG;;OAEG;YACW,UAAU;IAexB;;OAEG;YACW,SAAS;IAiBvB,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,sBAAsB;CAG/B"}

package/dist/src/session/s3-storage.js

@@ -0,0 +1,150 @@
+import { S3Client, PutObjectCommand, GetObjectCommand, ListObjectsV2Command } from '@aws-sdk/client-s3';
+import { SessionError } from '../errors.js';
+import { validateIdentifier } from './validation.js';
+const MANIFEST = 'manifest.json';
+const SNAPSHOT_LATEST = 'snapshot_latest.json';
+const IMMUTABLE_HISTORY = 'immutable_history/';
+const SNAPSHOT_REGEX = /snapshot_(\d+)\.json$/;
+const SCHEMA_VERSION = '1.0';
+const DEFAULT_SNAPSHOT_ID = '1';
+/**
+ * S3-based implementation of SnapshotStorage for persisting session snapshots
+ */
+export class S3Storage {
+    /** S3 client instance */
+    _s3;
+    /** S3 bucket name */
+    _bucket;
+    /** Key prefix for all objects */
+    _prefix;
+    /**
+     * Creates new S3Storage instance
+     * @param config - Configuration options
+     */
+    constructor(config) {
+        if (config.s3Client && config.region) {
+            throw new SessionError('Cannot specify both s3Client and region. Configure region in the S3Client instead.');
+        }
+        this._bucket = config.bucket;
+        this._prefix = config.prefix ?? '';
+        this._s3 = config.s3Client ?? new S3Client({ region: config.region ?? 'us-east-1' });
+    }
+    /**
+     * Generates S3 key path for session scope snapshots
+     */
+    _getKey(location, path) {
+        validateIdentifier(location.sessionId);
+        validateIdentifier(location.scopeId);
+        const base = this._prefix ? `${this._prefix}/` : '';
+        return `${base}${location.sessionId}/scopes/${location.scope}/${location.scopeId}/snapshots/${path}`;
+    }
+    /**
+     * Saves snapshot to S3, optionally marking as latest
+     */
+    async saveSnapshot(params) {
+        await this._writeJSON(this._getHistorySnapshotKey(params.location, params.snapshotId), params.snapshot);
+        if (params.isLatest) {
+            await this._writeJSON(this._getLatestSnapshotKey(params.location), params.snapshot);
+        }
+    }
+    /**
+     * Loads snapshot by ID or latest if undefined
+     */
+    async loadSnapshot(params) {
+        const key = params.snapshotId === undefined
+            ? this._getLatestSnapshotKey(params.location)
+            : this._getHistorySnapshotKey(params.location, params.snapshotId);
+        return this._readJSON(key);
+    }
+    /**
+     * Lists all snapshot IDs for a session scope.
+     *
+     * TODO: Add pagination support for long-running agents with many snapshots.
+     * Future signature could be:
+     * ```typescript
+     * listSnapshots(params: {
+     *   sessionId: string
+     *   scope: Scope
+     *   limit?: number        // Max results to return (e.g., 100)
+     *   startAfter?: string   // Snapshot ID to start after (for cursor-based pagination)
+     * }): Promise<{ snapshotIds: string[]; nextToken?: string }>
+     * ```
+     */
+    async listSnapshotIds(params) {
+        const prefix = this._getKey(params.location, IMMUTABLE_HISTORY);
+        try {
+            const response = await this._s3.send(new ListObjectsV2Command({ Bucket: this._bucket, Prefix: prefix }));
+            return (response.Contents ?? [])
+                .map((obj) => obj.Key?.match(SNAPSHOT_REGEX)?.[1])
+                .filter((id) => id !== undefined)
+                .map((id) => String(parseInt(id)))
+                .sort((a, b) => parseInt(a) - parseInt(b));
+        }
+        catch (error) {
+            throw new SessionError(`Failed to list snapshots for session ${params.location.sessionId}`, { cause: error });
+        }
+    }
+    /**
+     * Loads manifest or returns default if not found
+     */
+    async loadManifest(params) {
+        const key = this._getKey(params.location, MANIFEST);
+        const manifest = await this._readJSON(key);
+        return (manifest ?? {
+            schemaVersion: SCHEMA_VERSION,
+            nextSnapshotId: DEFAULT_SNAPSHOT_ID,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    /**
+     * Saves manifest to S3
+     */
+    async saveManifest(params) {
+        const key = this._getKey(params.location, MANIFEST);
+        await this._writeJSON(key, params.manifest);
+    }
+    /**
+     * Writes JSON data to S3
+     */
+    async _writeJSON(key, data) {
+        try {
+            await this._s3.send(new PutObjectCommand({
+                Bucket: this._bucket,
+                Key: key,
+                Body: JSON.stringify(data, null, 2),
+                ContentType: 'application/json',
+            }));
+        }
+        catch (error) {
+            throw new SessionError(`Failed to write S3 object ${key}`, { cause: error });
+        }
+    }
+    /**
+     * Reads and parses JSON from S3
+     */
+    async _readJSON(key) {
+        try {
+            const response = await this._s3.send(new GetObjectCommand({ Bucket: this._bucket, Key: key }));
+            const body = await response.Body?.transformToString();
+            if (!body)
+                return null;
+            return JSON.parse(body);
+        }
+        catch (error) {
+            if (error && typeof error === 'object' && 'name' in error && error.name === 'NoSuchKey') {
+                return null;
+            }
+            if (error instanceof SyntaxError) {
+                throw new SessionError(`Invalid JSON in S3 object ${key}`, { cause: error });
+            }
+            throw new SessionError(`S3 error reading ${key}`, { cause: error });
+        }
+    }
+    _getLatestSnapshotKey(location) {
+        return this._getKey(location, SNAPSHOT_LATEST);
+    }
+    _getHistorySnapshotKey(location, snapshotId) {
+        return this._getKey(location, `${IMMUTABLE_HISTORY}snapshot_${String(snapshotId).padStart(5, '0')}.json`);
+    }
+}
+//# sourceMappingURL=s3-storage.js.map

package/dist/src/session/s3-storage.js.map

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

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

@@ -0,0 +1,91 @@
+import type { Scope, Snapshot, SnapshotManifest } from './types.js';
+/**
+ * Identifies the location of a snapshot within the storage hierarchy.
+ */
+export type SnapshotLocation = {
+    /** Session identifier */
+    sessionId: string;
+    /** Scope of the snapshot (agent or multi-agent) */
+    scope: Scope;
+    /** Scope-specific identifier (agentId or multiAgentId) */
+    scopeId: string;
+};
+/**
+ * SessionStorage configuration for pluggable storage backends.
+ * Allows users to configure snapshot and transcript storage independently.
+ *
+ * @example
+ * ```typescript
+ * const storage: SessionStorage = {
+ *   snapshot: new S3Storage({ bucket: 'my-bucket' })
+ * }
+ * ```
+ */
+export type SessionStorage = {
+    snapshot: SnapshotStorage;
+};
+/**
+ * Interface for snapshot persistence.
+ * Implementations provide storage backends (S3, filesystem, etc.).
+ *
+ * File layout convention:
+ * ```
+ * sessions/<session_id>/
+ *   scopes/
+ *     agent/<scope_id>/
+ *       snapshots/
+ *         snapshot_latest.json
+ *         manifest.json
+ *         immutable_history/
+ *           snapshot_00001.json
+ *           snapshot_00002.json
+ * ```
+ */
+export interface SnapshotStorage {
+    /**
+     * Persists a snapshot to storage.
+     */
+    saveSnapshot(params: {
+        location: SnapshotLocation;
+        snapshotId: string;
+        isLatest: boolean;
+        snapshot: Snapshot;
+    }): Promise<void>;
+    /**
+     * Loads a snapshot from storage.
+     */
+    loadSnapshot(params: {
+        location: SnapshotLocation;
+        snapshotId?: string;
+    }): Promise<Snapshot | null>;
+    /**
+     * Lists all available snapshot IDs for a session scope.
+     *
+     * TODO: Add pagination support for long-running agents with many snapshots.
+     * Future signature could be:
+     * ```typescript
+     * listSnapshots(params: {
+     *   location: SnapshotLocation
+     *   limit?: number        // Max results to return (e.g., 100)
+     *   startAfter?: string   // Snapshot ID to start after (for cursor-based pagination)
+     * }): Promise<{ snapshotIds: string[]; nextToken?: string }>
+     * ```
+     */
+    listSnapshotIds(params: {
+        location: SnapshotLocation;
+    }): Promise<string[]>;
+    /**
+     * Loads the snapshot manifest.
+     */
+    loadManifest(params: {
+        location: SnapshotLocation;
+    }): Promise<SnapshotManifest>;
+    /**
+     * Saves the snapshot manifest.
+     */
+    saveManifest(params: {
+        location: SnapshotLocation;
+        manifest: SnapshotManifest;
+    }): Promise<void>;
+}
+//# sourceMappingURL=storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/session/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEnE;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,mDAAmD;IACnD,KAAK,EAAE,KAAK,CAAA;IACZ,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,eAAe,CAAA;CAE1B,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE;QACnB,QAAQ,EAAE,gBAAgB,CAAA;QAC1B,UAAU,EAAE,MAAM,CAAA;QAClB,QAAQ,EAAE,OAAO,CAAA;QACjB,QAAQ,EAAE,QAAQ,CAAA;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjB;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAA;IAEnG;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAE1E;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAE/E;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChG"}

package/dist/src/session/storage.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storage.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../../src/session/storage.ts"],"names":[],"mappings":""}

package/dist/src/session/types.d.ts

@@ -0,0 +1,49 @@
+import type { AgentData } from '../types/agent.js';
+export type { Snapshot, Scope } from '../agent/snapshot.js';
+/**
+ * Manifest tracks snapshot metadata and ID allocation.
+ * Stored alongside snapshots to manage versioning.
+ */
+export interface SnapshotManifest {
+    /** Schema version for forward/backward compatibility */
+    schemaVersion: string;
+    /** Next available snapshot ID for allocation */
+    nextSnapshotId: string;
+    /** ISO 8601 timestamp of last manifest update */
+    updatedAt: string;
+}
+/**
+ * Parameters passed to SnapshotTriggerCallback to determine when to create snapshots.
+ */
+export interface SnapshotTriggerParams {
+    /** Number of agent invocations (turns) since session started */
+    turnCount: number;
+    /** Timestamp (ms) of last immutable snapshot creation, undefined if no snapshot yet */
+    lastSnapshotAt?: number;
+    /** Current agent data including messages and state */
+    agentData: AgentData;
+}
+/**
+ * Callback function to determine when to create immutable snapshots.
+ * Called after each agent invocation to decide if a snapshot should be saved.
+ *
+ * @param params - Snapshot trigger parameters
+ * @returns true to create a snapshot, false to skip
+ *
+ * @example
+ * ```ts
+ * // Snapshot every 5 turns
+ * const trigger: SnapshotTriggerCallback = ({ turnCount }) => turnCount % 5 === 0
+ *
+ * // Snapshot every 60 seconds
+ * const trigger: SnapshotTriggerCallback = ({ lastSnapshotAt }) => {
+ *   if (!lastSnapshotAt) return false
+ *   return Date.now() - lastSnapshotAt > 60000
+ * }
+ *
+ * // Snapshot when conversation exceeds 10 messages
+ * const trigger: SnapshotTriggerCallback = ({ agentData }) => agentData.messages.length > 10
+ * ```
+ */
+export type SnapshotTriggerCallback = (params: SnapshotTriggerParams) => boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/session/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/session/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAGlD,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAA;AAE3D;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAA;IACrB,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAA;IACtB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAA;IACjB,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,sDAAsD;IACtD,SAAS,EAAE,SAAS,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,MAAM,EAAE,qBAAqB,KAAK,OAAO,CAAA"}

package/dist/src/session/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/session/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/session/types.ts"],"names":[],"mappings":""}

package/dist/src/session/validation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Validates that an identifier contains only allowed characters.
+ * Allowed characters: lowercase letters (a-z), numbers (0-9), hyphens (-), and underscores (_)
+ *
+ * @param id - The identifier to validate
+ * @returns The validated identifier
+ * @throws Error if identifier contains invalid characters
+ */
+export declare function validateIdentifier(id: string): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/src/session/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/session/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAMrD"}

package/dist/src/session/validation.js

@@ -0,0 +1,16 @@
+/**
+ * Validates that an identifier contains only allowed characters.
+ * Allowed characters: lowercase letters (a-z), numbers (0-9), hyphens (-), and underscores (_)
+ *
+ * @param id - The identifier to validate
+ * @returns The validated identifier
+ * @throws Error if identifier contains invalid characters
+ */
+export function validateIdentifier(id) {
+    const validPattern = /^[a-z0-9_-]+$/;
+    if (!validPattern.test(id)) {
+        throw new Error(`Identifier '${id}' can only contain lowercase letters, numbers, hyphens, and underscores`);
+    }
+    return id;
+}
+//# sourceMappingURL=validation.js.map

package/dist/src/session/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/session/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAU;IAC3C,MAAM,YAAY,GAAG,eAAe,CAAA;IACpC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,eAAe,EAAE,yEAAyE,CAAC,CAAA;IAC7G,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC"}

package/dist/src/structured-output/__tests__/context.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.test.d.ts.map