@cuylabs/agent-core 4.8.1 → 4.10.0

package/dist/storage/lock.d.ts

@@ -0,0 +1,18 @@
+export type ReleaseSessionTurnLock = () => void | Promise<void>;
+export interface SessionTurnLockAcquireOptions {
+    /** Abort while waiting for the lock. */
+    signal?: AbortSignal;
+    /** Maximum time to wait for the lock. */
+    timeoutMs?: number;
+}
+export interface SessionTurnLock {
+    acquire(sessionId: string, options?: SessionTurnLockAcquireOptions): Promise<ReleaseSessionTurnLock>;
+    /** Best-effort escape hatch for local runtimes. */
+    clear?(sessionId: string): void;
+}
+export declare class LocalSessionTurnLock implements SessionTurnLock {
+    private readonly locks;
+    acquire(sessionId: string, options?: SessionTurnLockAcquireOptions): Promise<ReleaseSessionTurnLock>;
+    clear(sessionId: string): void;
+}
+//# sourceMappingURL=lock.d.ts.map

package/dist/storage/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEhE,MAAM,WAAW,6BAA6B;IAC5C,wCAAwC;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CACL,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,6BAA6B,GACtC,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACnC,mDAAmD;IACnD,KAAK,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAEpD,OAAO,CACX,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,sBAAsB,CAAC;IAgClC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAG/B"}

package/dist/storage/manager/default.d.ts

@@ -0,0 +1,11 @@
+import type { SessionStorage } from "../types.js";
+import { SessionManager } from "./session-manager.js";
+/**
+ * Get the default session-manager instance.
+ */
+export declare function getDefaultSessionManager(): SessionManager;
+/**
+ * Replace the default session-manager instance with one backed by custom storage.
+ */
+export declare function configureDefaultSessionManager(storage: SessionStorage): SessionManager;
+//# sourceMappingURL=default.d.ts.map

package/dist/storage/manager/default.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default.d.ts","sourceRoot":"","sources":["../../../src/storage/manager/default.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAItD;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,cAAc,CAKzD;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,cAAc,GACtB,cAAc,CAGhB"}

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

@@ -0,0 +1,12 @@
+/**
+ * Session-manager module.
+ *
+ * Split by responsibility:
+ * - `types` defines create/load context contracts
+ * - `session-manager` owns the stateful manager implementation
+ * - `default` owns the process-wide default-manager singleton
+ */
+export type { CreateSessionOptions, RecentMessagesOptions, SessionContext, } from "./types.js";
+export { SessionManager } from "./session-manager.js";
+export { configureDefaultSessionManager, getDefaultSessionManager, } from "./default.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/manager/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,8BAA8B,EAC9B,wBAAwB,GACzB,MAAM,cAAc,CAAC"}

package/dist/storage/manager/session-manager.d.ts

@@ -0,0 +1,57 @@
+import type { Message } from "../../types/index.js";
+import { type AgentContextFragmentInput } from "../../context/fragments/index.js";
+import type { FileEntry, SessionHeader, SessionInfo, SessionStorage } from "../types.js";
+import type { CreateSessionOptions, RecentMessagesOptions, SessionContext } from "./types.js";
+/**
+ * Manages session lifecycle with tree-structured entries.
+ */
+export declare class SessionManager {
+    private storage;
+    private currentSessionId;
+    private currentLeafId;
+    private entriesCache;
+    private idsCache;
+    private entriesByIdCache;
+    constructor(storage?: SessionStorage);
+    create(options: CreateSessionOptions): Promise<string>;
+    load(sessionId: string): Promise<void>;
+    getSessionId(): string | null;
+    getLeafId(): string | null;
+    addMessage(message: Message): Promise<string>;
+    addMessages(messages: Message[]): Promise<string[]>;
+    addContextFragment(contextFragment: AgentContextFragmentInput): Promise<string>;
+    getMessages(leafId?: string): Message[];
+    getRecentMessages(options?: RecentMessagesOptions): Message[];
+    addCompaction(options: {
+        summary: string;
+        displaySummary?: boolean;
+        firstKeptEntryId: string;
+        tokensBefore: number;
+        tokensAfter: number;
+        readFiles?: string[];
+        modifiedFiles?: string[];
+    }): Promise<string>;
+    replaceWithCompaction(options: {
+        summary: string;
+        displaySummary?: boolean;
+        messages: Message[];
+        tokensBefore: number;
+        tokensAfter: number;
+        readFiles?: string[];
+        modifiedFiles?: string[];
+    }): Promise<string>;
+    branch(fromEntryId: string, summary?: string): Promise<string>;
+    switchToLeaf(leafId: string): void;
+    updateMetadata(updates: {
+        title?: string;
+        name?: string;
+    }): Promise<void>;
+    getContext(): SessionContext;
+    getEntries(): FileEntry[];
+    getHeader(): SessionHeader | null;
+    listSessions(): Promise<SessionInfo[]>;
+    deleteSession(sessionId: string): Promise<boolean>;
+    sessionExists(sessionId: string): Promise<boolean>;
+    getStorage(): SessionStorage;
+}
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/storage/manager/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../../src/storage/manager/session-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,kCAAkC,CAAC;AAG1C,OAAO,KAAK,EAGV,SAAS,EAGT,aAAa,EACb,WAAW,EACX,cAAc,EACf,MAAM,aAAa,CAAC;AASrB,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,YAAY,CAAmB;IACvC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,gBAAgB,CAAmC;gBAE/C,OAAO,CAAC,EAAE,cAAc;IAI9B,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBtD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB5C,YAAY,IAAI,MAAM,GAAG,IAAI;IAI7B,SAAS,IAAI,MAAM,GAAG,IAAI;IAIpB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAoB7C,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA4BnD,kBAAkB,CACtB,eAAe,EAAE,yBAAyB,GACzC,OAAO,CAAC,MAAM,CAAC;IAUlB,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE;IAOvC,iBAAiB,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,EAAE;IAQ3D,aAAa,CAAC,OAAO,EAAE;QAC3B,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,gBAAgB,EAAE,MAAM,CAAC;QACzB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;KAC1B,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBb,qBAAqB,CAAC,OAAO,EAAE;QACnC,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,QAAQ,EAAE,OAAO,EAAE,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;KAC1B,GAAG,OAAO,CAAC,MAAM,CAAC;IAiDb,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BpE,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO5B,cAAc,CAAC,OAAO,EAAE;QAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBjB,UAAU,IAAI,cAAc;IA6B5B,UAAU,IAAI,SAAS,EAAE;IAIzB,SAAS,IAAI,aAAa,GAAG,IAAI;IAK3B,YAAY,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAItC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAclD,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxD,UAAU,IAAI,cAAc;CAG7B"}

package/dist/storage/manager/types.d.ts

@@ -0,0 +1,42 @@
+import type { Message, MessageRole } from "../../types/index.js";
+/**
+ * Options for creating a new session.
+ */
+export interface CreateSessionOptions {
+    /** Custom session ID (auto-generated if not provided) */
+    id?: string;
+    /** Working directory */
+    cwd: string;
+    /** Session title */
+    title?: string;
+    /** Parent session ID (if forking) */
+    parentSessionId?: string;
+}
+/**
+ * Session context for LLM calls.
+ */
+export interface SessionContext {
+    /** Messages for LLM context */
+    messages: Message[];
+    /** Current leaf entry ID */
+    leafId: string | null;
+    /** Session metadata */
+    metadata: {
+        id: string;
+        cwd: string;
+        title?: string;
+        name?: string;
+    };
+}
+/**
+ * Options for reading a bounded slice of recent visible session messages.
+ */
+export interface RecentMessagesOptions {
+    /** Maximum number of messages to return. Defaults to all visible messages. */
+    limit?: number;
+    /** Restrict returned messages to these roles. Defaults to all roles. */
+    roles?: readonly MessageRole[];
+    /** Optional leaf entry ID. Defaults to the manager's active leaf. */
+    leafId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/storage/manager/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/storage/manager/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,4BAA4B;IAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uBAAuB;IACvB,QAAQ,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,KAAK,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC/B,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/storage/memory.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Memory Session Storage
+ *
+ * In-memory implementation of SessionStorage.
+ * Useful for testing and ephemeral sessions.
+ */
+import type { SessionStorage, SessionHeader, SessionEntry, FileEntry, SessionInfo } from "./types.js";
+/**
+ * In-memory session storage
+ */
+export declare class MemoryStorage implements SessionStorage {
+    private sessions;
+    create(header: SessionHeader): Promise<void>;
+    append(sessionId: string, entry: SessionEntry): Promise<void>;
+    appendBatch(sessionId: string, entries: SessionEntry[]): Promise<void>;
+    read(sessionId: string): Promise<FileEntry[]>;
+    delete(sessionId: string): Promise<boolean>;
+    exists(sessionId: string): Promise<boolean>;
+    list(): Promise<SessionInfo[]>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/storage/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/storage/memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACZ,SAAS,EACT,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB;;GAEG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,QAAQ,CAAkC;IAE5C,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7D,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAS7C,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI3C,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI3C,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAgB9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/storage/paths.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Default paths for storage
+ *
+ * Follows platform conventions:
+ * - macOS: ~/.cuylabs/
+ * - Linux: $XDG_DATA_HOME/cuylabs/ or ~/.local/share/cuylabs/
+ * - Windows: %APPDATA%/cuylabs/
+ *
+ * Project identification:
+ * - Uses git root commit hash for git repos
+ * - Falls back to encoded path for non-git directories
+ */
+/**
+ * Get the default data directory for cuylabs
+ */
+export declare function getDataDir(appName?: string): string;
+/**
+ * Get the default sessions directory
+ */
+export declare function getSessionsDir(appName?: string): string;
+/**
+ * Get the git root commit hash for a directory.
+ * This is stable across machines and identifies the project uniquely.
+ * Returns null if not a git repo.
+ */
+export declare function getGitRootHash(cwd: string): string | null;
+/**
+ * Get a short project ID for a directory.
+ * - For git repos: uses first 12 chars of root commit hash
+ * - For non-git: uses encoded path
+ */
+export declare function getProjectId(cwd: string): string;
+/**
+ * Get sessions directory for a specific project/cwd
+ */
+export declare function getProjectSessionsDir(cwd: string, appName?: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/storage/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/storage/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,SAAY,GAAG,MAAM,CAoBtD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,SAAY,GAAG,MAAM,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBzD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAahD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,OAAO,SAAY,GAClB,MAAM,CAGR"}

package/dist/storage/types.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Storage Types
+ *
+ * Core types for session storage with tree structure support.
+ * Designed for append-only event sourcing with branching.
+ */
+import type { AgentContextFragmentMessageMetadata } from "../context/fragments/types.js";
+/**
+ * Base interface for all session entries
+ * Supports tree structure via id/parentId
+ */
+export interface EntryBase {
+    /** Unique entry ID (8-char hex) */
+    id: string;
+    /** Parent entry ID (null for first entry after header) */
+    parentId: string | null;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/**
+ * Session header - always first entry in file
+ */
+export interface SessionHeader {
+    type: "header";
+    /** Storage format version */
+    version: number;
+    /** Session ID */
+    id: string;
+    /** Working directory */
+    cwd: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Parent session ID (if forked) */
+    parentSessionId?: string;
+    /** Session title */
+    title?: string;
+}
+/**
+ * Serialized message (dates as ISO strings)
+ */
+export interface SerializedMessage {
+    id: string;
+    role: "user" | "assistant" | "tool" | "system";
+    content: string;
+    createdAt: string;
+    contextFragment?: AgentContextFragmentMessageMetadata;
+    system?: string;
+    finish?: string;
+    tokens?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    cost?: number;
+    error?: {
+        name: string;
+        message: string;
+        code?: string;
+    };
+    /** Tool calls for assistant messages with finish=tool-calls */
+    toolCalls?: Array<{
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+    }>;
+    toolCallId?: string;
+    toolName?: string;
+    result?: unknown;
+}
+/**
+ * Message entry
+ */
+export interface MessageEntry extends EntryBase {
+    type: "message";
+    message: SerializedMessage;
+}
+/**
+ * Compaction/summarization entry
+ * Replaces old messages with a summary
+ */
+export interface CompactionEntry extends EntryBase {
+    type: "compaction";
+    /** Summary of compacted messages */
+    summary: string;
+    /** Whether the summary should be injected into visible session messages */
+    displaySummary?: boolean;
+    /** ID of first entry that was kept (not compacted) */
+    firstKeptEntryId: string;
+    /** Token count before compaction */
+    tokensBefore: number;
+    /** Token count after compaction */
+    tokensAfter: number;
+    /** Files that were read during compacted messages */
+    readFiles?: string[];
+    /** Files that were modified during compacted messages */
+    modifiedFiles?: string[];
+}
+/**
+ * Session info/metadata update
+ */
+export interface MetadataEntry extends EntryBase {
+    type: "metadata";
+    /** Updated title */
+    title?: string;
+    /** User-defined name */
+    name?: string;
+}
+/**
+ * Branch marker - indicates a branch point
+ */
+export interface BranchEntry extends EntryBase {
+    type: "branch";
+    /** ID of the entry we're branching from */
+    branchFromId: string;
+    /** Optional summary of the branch */
+    summary?: string;
+}
+/**
+ * Model/config change entry
+ */
+export interface ConfigChangeEntry extends EntryBase {
+    type: "config_change";
+    /** What changed */
+    change: "model" | "reasoning_level" | "temperature" | "other";
+    /** Previous value */
+    from?: string;
+    /** New value */
+    to: string;
+}
+/**
+ * All entry types (excluding header)
+ */
+export type SessionEntry = MessageEntry | CompactionEntry | MetadataEntry | BranchEntry | ConfigChangeEntry;
+/**
+ * All file entries (including header)
+ */
+export type FileEntry = SessionHeader | SessionEntry;
+/**
+ * Session summary info (lightweight, for listing)
+ */
+export interface SessionInfo {
+    /** Session ID */
+    id: string;
+    /** File path */
+    path: string;
+    /** Working directory */
+    cwd: string;
+    /** Session title */
+    title?: string;
+    /** User-defined name */
+    name?: string;
+    /** Parent session ID (if forked) */
+    parentSessionId?: string;
+    /** Creation time */
+    createdAt: Date;
+    /** Last modified time */
+    updatedAt: Date;
+    /** Number of message entries */
+    messageCount: number;
+    /** First user message (preview) */
+    firstMessage?: string;
+}
+/**
+ * Session storage interface
+ * Pluggable backend for session persistence
+ */
+export interface SessionStorage {
+    /**
+     * Create a new session
+     */
+    create(header: SessionHeader): Promise<void>;
+    /**
+     * Append an entry to a session
+     */
+    append(sessionId: string, entry: SessionEntry): Promise<void>;
+    /**
+     * Append multiple entries atomically
+     */
+    appendBatch(sessionId: string, entries: SessionEntry[]): Promise<void>;
+    /**
+     * Read all entries from a session
+     */
+    read(sessionId: string): Promise<FileEntry[]>;
+    /**
+     * Delete a session
+     */
+    delete(sessionId: string): Promise<boolean>;
+    /**
+     * Check if session exists
+     */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * List all sessions (lightweight info only)
+     */
+    list(): Promise<SessionInfo[]>;
+    /**
+     * Clear all sessions
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Current storage format version
+ */
+export declare const STORAGE_VERSION = 1;
+//# sourceMappingURL=types.d.ts.map

package/dist/storage/types.d.ts.map

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

package/dist/storage/utils.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Storage Utilities
+ *
+ * Helper functions for session storage operations.
+ */
+import type { FileEntry, SessionEntry, SessionInfo, MessageEntry, MetadataEntry, SerializedMessage } from "./types.js";
+import type { Message, MessageRole } from "../types/messages.js";
+import type { Logger } from "../logger/types.js";
+/**
+ * Generate a unique 8-character hex ID
+ * Collision-checked against existing IDs
+ */
+export declare function generateEntryId(existingIds?: Set<string>): string;
+/**
+ * Parse JSONL content into entries
+ * Handles malformed lines gracefully
+ */
+export declare function parseJSONL<T>(content: string, logger?: Logger): T[];
+/**
+ * Serialize entry to JSONL line
+ */
+export declare function toJSONL(entry: FileEntry): string;
+/**
+ * Serialize multiple entries to JSONL
+ */
+export declare function toJSONLBatch(entries: FileEntry[]): string;
+/**
+ * Serialize a Message to storage format
+ */
+export declare function serializeMessage(message: Message): SerializedMessage;
+/**
+ * Deserialize a stored message back to Message
+ */
+export declare function deserializeMessage(serialized: SerializedMessage): Message;
+/**
+ * Create a message entry from a Message
+ */
+export declare function createMessageEntry(message: Message, parentId: string | null, existingIds?: Set<string>): MessageEntry;
+/**
+ * Create a metadata entry
+ */
+export declare function createMetadataEntry(updates: {
+    title?: string;
+    name?: string;
+}, parentId: string | null, existingIds?: Set<string>): MetadataEntry;
+/**
+ * Extract SessionInfo from entries (for listing)
+ */
+export declare function extractSessionInfo(entries: FileEntry[], path: string): SessionInfo | null;
+/**
+ * Get leaf entry ID (last entry in the chain)
+ */
+export declare function getLeafId(entries: FileEntry[]): string | null;
+/**
+ * Build path from root to a specific entry
+ */
+export declare function buildEntryPath(entries: FileEntry[], targetId: string): SessionEntry[];
+/**
+ * Build messages array from entries for a specific leaf
+ * Handles compaction summaries
+ */
+export declare function buildMessagesFromEntries(entries: FileEntry[], leafId?: string): Message[];
+export interface BuildRecentMessagesOptions {
+    leafId?: string;
+    limit?: number;
+    roles?: readonly MessageRole[];
+}
+/**
+ * Build the last N visible messages from a session path without materializing
+ * the full message list when only a bounded suffix is needed.
+ */
+export declare function buildRecentMessagesFromEntries(entries: FileEntry[], options?: BuildRecentMessagesOptions): Message[];
+/**
+ * Build the last N visible messages from an existing entry index.
+ */
+export declare function buildRecentMessagesFromEntryMap(entriesById: ReadonlyMap<string, SessionEntry>, leafId: string | undefined, options?: Omit<BuildRecentMessagesOptions, "leafId">): Message[];
+//# sourceMappingURL=utils.d.ts.map

package/dist/storage/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/storage/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,aAAa,EACb,iBAAiB,EAClB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAMjD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAOjE;AAMD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,CAiBnE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,CAEzD;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,CAmCpE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAyDzE;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACxB,YAAY,CAQd;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAC1C,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACxB,aAAa,CAQf;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,EAAE,EACpB,IAAI,EAAE,MAAM,GACX,WAAW,GAAG,IAAI,CA6CpB;AAMD;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,GAAG,IAAI,CAsC7D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,EAAE,EACpB,QAAQ,EAAE,MAAM,GACf,YAAY,EAAE,CAqBhB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,SAAS,EAAE,EACpB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,EAAE,CAkDX;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,SAAS,EAAE,EACpB,OAAO,GAAE,0BAA+B,GACvC,OAAO,EAAE,CAcX;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EAC9C,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,GAAE,IAAI,CAAC,0BAA0B,EAAE,QAAQ,CAAM,GACvD,OAAO,EAAE,CAwCX"}