@cuylabs/agent-core 4.9.0 → 5.0.0

package/dist/sandbox/types.d.ts

@@ -0,0 +1,79 @@
+import type { ToolHost } from "../tool/host/types.js";
+/**
+ * Preview endpoint exposed by a managed sandbox environment.
+ */
+export interface SandboxPreview {
+    /** The internal port inside the environment. */
+    port: number;
+    /** Publicly reachable URL for the preview. */
+    url: string;
+    /** Optional user-facing label. */
+    label?: string;
+}
+/**
+ * Snapshot handle returned by a sandbox implementation.
+ */
+export interface SandboxSnapshotResult {
+    /** Provider-specific snapshot identifier. */
+    id: string;
+    /** Optional display label or description. */
+    label?: string;
+    /** Provider-specific metadata for later restore flows. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Metadata describing a managed sandbox session.
+ */
+export interface SandboxSessionMetadata {
+    /** Implementation kind such as "docker", "local", or "cloud". */
+    kind?: string;
+    /** Human-readable label for logs or dashboards. */
+    label?: string;
+    /** Working directory exposed through the embedded ToolHost. */
+    workingDirectory?: string;
+    /** Extra environment details suitable for prompts or UI surfaces. */
+    environmentDetails?: string;
+    /** Preview endpoints exposed by the environment. */
+    previews?: readonly SandboxPreview[];
+    /** Session expiration timestamp when managed by a lease/timeout system. */
+    expiresAt?: number;
+    /** Initial timeout/lease duration in milliseconds. */
+    timeoutMs?: number;
+    /** Provider-specific metadata. */
+    [key: string]: unknown;
+}
+/**
+ * Managed execution environment used by host-backed tools.
+ *
+ * A SandboxSession owns environment lifecycle concerns such as start/stop,
+ * snapshots, timeout extension, and preview URLs, while exposing a `ToolHost`
+ * for the actual file/shell operations tools perform.
+ */
+export interface SandboxSession {
+    /** Stable identifier for the environment session. */
+    readonly id: string;
+    /** Tool execution surface exposed by the environment. */
+    readonly host: ToolHost;
+    /** Optional metadata about the environment. */
+    readonly metadata?: SandboxSessionMetadata;
+    /** Stop and clean up the environment. */
+    stop(): Promise<void>;
+    /** Create a restorable snapshot when supported by the provider. */
+    snapshot?(): Promise<SandboxSnapshotResult>;
+    /** Extend the environment lease/timeout when supported. */
+    extendTimeout?(additionalMs: number): Promise<{
+        expiresAt: number;
+    } | void>;
+    /** Return a preview URL for an exposed port when supported. */
+    getPreviewUrl?(port: number): string | undefined;
+}
+/**
+ * Factory/connector surface for sandbox implementations.
+ *
+ * Providers may support only `connect`, only `create`, or both.
+ */
+export interface SandboxProvider<TConnectOptions = unknown, TCreateOptions = TConnectOptions> {
+    connect?(options: TConnectOptions): Promise<SandboxSession>;
+    create?(options: TCreateOptions): Promise<SandboxSession>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sandbox/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACrC,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAC3C,yCAAyC;IACzC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC5C,2DAA2D;IAC3D,aAAa,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAC5E,+DAA+D;IAC/D,aAAa,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAClD;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAC9B,eAAe,GAAG,OAAO,EACzB,cAAc,GAAG,eAAe;IAEhC,OAAO,CAAC,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,MAAM,CAAC,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC3D"}

package/dist/sessions/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sessions Module
+ *
+ * Session history, tree reconstruction, compaction entries, and pluggable
+ * session-store contracts.
+ */
+export type { EntryBase, SessionHeader, SerializedMessage, MessageEntry, CompactionEntry, MetadataEntry, BranchEntry, ConfigChangeEntry, SessionEntry, FileEntry, SessionInfo, SessionStore, } from "./types.js";
+export { SESSION_FORMAT_VERSION } from "./types.js";
+export { generateEntryId, parseJSONL, toJSONL, toJSONLBatch, serializeMessage, deserializeMessage, createMessageEntry, createMetadataEntry, extractSessionInfo, getLeafId, buildEntryPath, buildMessagesFromEntries, buildRecentMessagesFromEntries, buildRecentMessagesFromEntryMap, type BuildRecentMessagesOptions, } from "./utils.js";
+export { InMemorySessionStore } from "./store/memory.js";
+export { LocalSessionTurnLock, type ReleaseSessionTurnLock, type SessionTurnLock, type SessionTurnLockAcquireOptions, } from "./store/lock.js";
+export { SessionManager, getDefaultSessionManager, configureDefaultSessionManager, type CreateSessionOptions, type RecentMessagesOptions, type SessionContext, } from "./manager/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sessions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sessions/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAEV,SAAS,EACT,aAAa,EACb,iBAAiB,EAEjB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,SAAS,EAET,WAAW,EAEX,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAGpD,OAAO,EACL,eAAe,EACf,UAAU,EACV,OAAO,EACP,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,wBAAwB,EACxB,8BAA8B,EAC9B,+BAA+B,EAC/B,KAAK,0BAA0B,GAChC,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EACL,oBAAoB,EACpB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,6BAA6B,GACnC,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,8BAA8B,EAC9B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC"}

package/dist/{storage → sessions}/index.js

@@ -1,8 +1,7 @@
 import {
-  FileStorage,
+  InMemorySessionStore,
   LocalSessionTurnLock,
-  MemoryStorage,
-  STORAGE_VERSION,
+  SESSION_FORMAT_VERSION,
   SessionManager,
   buildEntryPath,
   buildMessagesFromEntries,
@@ -14,23 +13,18 @@ import {
   deserializeMessage,
   extractSessionInfo,
   generateEntryId,
-  getDataDir,
   getDefaultSessionManager,
-  getGitRootHash,
   getLeafId,
-  getProjectId,
-  getProjectSessionsDir,
-  getSessionsDir,
   parseJSONL,
   serializeMessage,
   toJSONL,
   toJSONLBatch
-} from "../chunk-H3GRHFFG.js";
+} from "../chunk-EDKZOPUV.js";
+import "../chunk-CGP6UNCQ.js";
 export {
-  FileStorage,
+  InMemorySessionStore,
   LocalSessionTurnLock,
-  MemoryStorage,
-  STORAGE_VERSION,
+  SESSION_FORMAT_VERSION,
   SessionManager,
   buildEntryPath,
   buildMessagesFromEntries,
@@ -42,13 +36,8 @@ export {
   deserializeMessage,
   extractSessionInfo,
   generateEntryId,
-  getDataDir,
   getDefaultSessionManager,
-  getGitRootHash,
   getLeafId,
-  getProjectId,
-  getProjectSessionsDir,
-  getSessionsDir,
   parseJSONL,
   serializeMessage,
   toJSONL,

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

@@ -0,0 +1,11 @@
+import type { SessionStore } 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 session store.
+ */
+export declare function configureDefaultSessionManager(store: SessionStore): SessionManager;
+//# sourceMappingURL=default.d.ts.map

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

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

package/dist/sessions/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/sessions/manager/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sessions/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/sessions/manager/session-manager.d.ts

@@ -0,0 +1,67 @@
+import type { Message } from "../../types/index.js";
+import type { CompactionCutReason, CompactionReason, CompactionTrigger } from "../../types/compaction.js";
+import type { AgentContextCompactionPhase } from "../../types/events.js";
+import { type AgentContextFragmentInput } from "../../context/fragments/index.js";
+import type { FileEntry, SessionHeader, SessionInfo, SessionStore } from "../types.js";
+import type { CreateSessionOptions, RecentMessagesOptions, SessionContext } from "./types.js";
+/**
+ * Manages session lifecycle with tree-structured entries.
+ */
+export declare class SessionManager {
+    private store;
+    private currentSessionId;
+    private currentLeafId;
+    private entriesCache;
+    private idsCache;
+    private entriesByIdCache;
+    constructor(store?: SessionStore);
+    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;
+        phase?: AgentContextCompactionPhase;
+        trigger?: CompactionTrigger;
+        reason?: CompactionReason;
+        cutReason?: CompactionCutReason;
+        readFiles?: string[];
+        modifiedFiles?: string[];
+    }): Promise<string>;
+    replaceWithCompaction(options: {
+        summary: string;
+        displaySummary?: boolean;
+        messages: Message[];
+        tokensBefore: number;
+        tokensAfter: number;
+        phase?: AgentContextCompactionPhase;
+        trigger?: CompactionTrigger;
+        reason?: CompactionReason;
+        cutReason?: CompactionCutReason;
+        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>;
+    getStore(): SessionStore;
+}
+//# sourceMappingURL=session-manager.d.ts.map

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

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

package/dist/sessions/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/sessions/manager/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/sessions/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/sessions/store/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/sessions/store/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../../src/sessions/store/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/sessions/store/memory.d.ts

@@ -0,0 +1,22 @@
+/**
+ * In-Memory Session Store
+ *
+ * In-memory implementation of SessionStore.
+ * Useful for testing and ephemeral sessions.
+ */
+import type { SessionStore, SessionHeader, SessionEntry, FileEntry, SessionInfo } from "../types.js";
+/**
+ * In-memory session store
+ */
+export declare class InMemorySessionStore implements SessionStore {
+    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/sessions/store/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/sessions/store/memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,SAAS,EACT,WAAW,EACZ,MAAM,aAAa,CAAC;AAGrB;;GAEG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD,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/sessions/types.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Session Types
+ *
+ * Core types for session history with tree structure support.
+ * Designed for append-only event sourcing with branching.
+ */
+import type { AgentContextFragmentMessageMetadata } from "../context/fragments/types.js";
+import type { CompactionCutReason, CompactionReason, CompactionTrigger } from "../types/compaction.js";
+import type { AgentContextCompactionPhase } from "../types/events.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";
+    /** Runtime phase that performed compaction */
+    phase?: AgentContextCompactionPhase;
+    /** Lifecycle source that requested compaction */
+    trigger?: CompactionTrigger;
+    /** Operational reason for compaction */
+    reason?: CompactionReason;
+    /** 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;
+    /** Safe cut boundary reason when conversation messages were removed */
+    cutReason?: CompactionCutReason;
+    /** 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 store interface
+ * Pluggable backend for session persistence
+ */
+export interface SessionStore {
+    /**
+     * 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 session history format version
+ */
+export declare const SESSION_FORMAT_VERSION = 1;
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/sessions/utils.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Session Utilities
+ *
+ * Helper functions for session history 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 the persisted session 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