jeopi-cli 16.2.14 → 16.2.17

package/dist/types/session/session-listing.d.ts

@@ -0,0 +1,78 @@
+import { type SessionStorage } from "./session-storage";
+/**
+ * Coarse lifecycle status of a session, derived from its last persisted message.
+ *
+ * - `complete` — the last assistant turn ended with no unanswered tool calls, i.e.
+ *   the agent yielded control back to the user.
+ * - `interrupted` — work was cut off mid-flight: a trailing assistant turn with
+ *   pending tool calls, a trailing tool result the agent never continued from, or
+ *   a length-truncated turn.
+ * - `aborted` — the last assistant turn was cancelled by the user.
+ * - `error` — the last assistant turn ended in an error.
+ * - `pending` — a trailing user message with no assistant reply persisted after it.
+ * - `unknown` — status could not be determined (empty/header-only session, or the
+ *   final message was larger than the tail window that was read).
+ */
+export type SessionStatus = "complete" | "interrupted" | "aborted" | "error" | "pending" | "unknown";
+export interface SessionInfo {
+    path: string;
+    id: string;
+    /** Working directory where the session was started. Empty string for old sessions. */
+    cwd: string;
+    title?: string;
+    /** Path to the parent session (if this session was forked). */
+    parentSessionPath?: string;
+    created: Date;
+    modified: Date;
+    messageCount: number;
+    /** File size in bytes on disk; used for compact list rendering. */
+    size: number;
+    firstMessage: string;
+    allMessagesText: string;
+    /**
+     * Coarse lifecycle status from the session's last persisted message. Optional:
+     * synthesized {@link SessionInfo}s (cross-project stubs, tests) leave it unset.
+     */
+    status?: SessionStatus;
+}
+export interface ResolvedSessionMatch {
+    session: SessionInfo;
+    scope: "local" | "global";
+}
+/** Lightweight metadata for a recent session, used in welcome/picker UI. */
+export interface RecentSessionInfo {
+    path: string;
+    name: string;
+    timeAgo: string;
+}
+/**
+ * Promote orphaned `<basename>.jsonl.<snowflake>.bak` backups created by the
+ * EPERM-rewrite path back to their primary path when the primary is missing.
+ * This runs once per session-dir scan, before the main `*.jsonl` glob, so a
+ * crash between the two renames in the EPERM-rewrite path does not leave the
+ * user's last good state stranded outside the loader's view.
+ *
+ * Exported for testing.
+ */
+export declare function recoverOrphanedBackups(sessionDir: string, storage: SessionStorage): Promise<void>;
+/**
+ * List sessions in a resolved session directory (newest first), reading each
+ * file's lifecycle {@link SessionStatus}.
+ */
+export declare function listSessions(sessionDir: string, storage: SessionStorage): Promise<SessionInfo[]>;
+/**
+ * List sessions without repairing orphaned backups or mutating the directory.
+ */
+export declare function listSessionsReadOnly(sessionDir: string, storage: SessionStorage): Promise<SessionInfo[]>;
+/** List all sessions across all project directories (newest first). */
+export declare function listAllSessions(storage?: SessionStorage): Promise<SessionInfo[]>;
+/** Exported for testing */
+export declare function findMostRecentSession(sessionDir: string, storage?: SessionStorage): Promise<string | null>;
+/** Get recent sessions for display in the welcome screen. */
+export declare function getRecentSessions(sessionDir: string, limit?: number, storage?: SessionStorage): Promise<RecentSessionInfo[]>;
+/** Controls cross-directory fallback for resumable session lookup. */
+export interface ResolveResumableSessionOptions {
+    /** Search default global session buckets after the active/custom session directory misses. */
+    allowGlobalFallback?: boolean;
+}
+export declare function resolveResumableSession(sessionArg: string, cwd: string, sessionDir?: string, storageOrOptions?: SessionStorage | ResolveResumableSessionOptions, options?: ResolveResumableSessionOptions): Promise<ResolvedSessionMatch | undefined>;

package/dist/types/session/session-loader.d.ts

@@ -0,0 +1,29 @@
+import type { AgentMessage } from "jeopi-agent-core";
+import { BlobStore } from "./blob-store";
+import { type FileEntry, type SessionTitleSlotEntry } from "./session-entries";
+import { type SessionStorage } from "./session-storage";
+import { type SessionTitleUpdate } from "./session-title-slot";
+/** Parse session JSONL while stripping and folding the optional fixed title slot. */
+export declare function parseSessionContent(content: string): {
+    entries: FileEntry[];
+    titleSlot: SessionTitleUpdate | undefined;
+};
+/** Exported for testing — the ≥8MiB streaming path (works on any file size). */
+export declare function loadEntriesFromFileStream(filePath: string): Promise<{
+    entries: FileEntry[];
+    titleSlot: SessionTitleUpdate | undefined;
+}>;
+/** Read only the fixed-size head window to detect a physical title slot. */
+export declare function readTitleSlotFromFile(filePath: string, storage?: SessionStorage): Promise<SessionTitleSlotEntry | undefined>;
+/** Exported for compaction.test.ts */
+export declare function parseSessionEntries(content: string): FileEntry[];
+/** Exported for testing */
+export declare function loadEntriesFromFile(filePath: string, storage?: SessionStorage): Promise<FileEntry[]>;
+export declare function resolveBlobRefsInEntries(entries: FileEntry[], blobStore: BlobStore): Promise<void>;
+/**
+ * Read-only message view of a session file: load entries, migrate to the
+ * current version, resolve blob refs, and build the context along the
+ * persisted leaf path (last entry). Does NOT create a writer or take the
+ * session lock — safe to call against a file another session is writing.
+ */
+export declare function loadSessionMessagesReadOnly(filePath: string): Promise<AgentMessage[]>;

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

@@ -0,0 +1,306 @@
+import type { ImageContent, Message, MessageAttribution, ServiceTierByFamily, TextContent } from "jeopi-ai";
+import { ArtifactManager } from "./artifacts";
+import { type BlobPutOptions, type BlobPutResult } from "./blob-store";
+import { type BashExecutionMessage, type CustomMessage, type FileMentionMessage, type HookMessage, type PythonExecutionMessage } from "./messages";
+import { type BuildSessionContextOptions, type SessionContext } from "./session-context";
+import { type NewSessionOptions, type SessionEntry, type SessionHeader, type SessionTitleSource, type SessionTreeNode, type UsageStatistics } from "./session-entries";
+import { type SessionInfo } from "./session-listing";
+import { type SessionStorage } from "./session-storage";
+export type ReadonlySessionManager = Pick<SessionManager, "getCwd" | "getSessionDir" | "getSessionId" | "getSessionFile" | "getSessionName" | "getArtifactsDir" | "getArtifactManager" | "allocateArtifactPath" | "saveArtifact" | "getArtifactPath" | "getLeafId" | "getLeafEntry" | "getEntry" | "getLabel" | "getBranch" | "getHeader" | "getEntries" | "getTree" | "getUsageStatistics" | "putBlob" | "putBlobSync">;
+interface SessionManagerStateSnapshot {
+    cwd: string;
+    sessionDir: string;
+    sessionId: string;
+    sessionName: string | undefined;
+    titleSource: SessionTitleSource | undefined;
+    sessionFile: string | undefined;
+    titleUpdatedAt: string;
+    hasTitleSlot: boolean;
+    onDisk: boolean;
+    needsRewrite: boolean;
+    header: SessionHeader;
+    entries: SessionEntry[];
+}
+/**
+ * Stores and navigates an append-only conversation journal.
+ *
+ * A session is a JSONL file: one header line followed by entries. Entries form a
+ * tree by `(id, parentId)`, and the mutable leaf pointer selects which path is
+ * active for future appends and for LLM context construction.
+ *
+ * Durability is software-crash safe but not power-loss safe: appends are handed
+ * to the OS synchronously in-body (so an entry survives an OOM/SIGKILL the
+ * instant `appendMessage` returns) but never `fsync`'d. Full-file rewrites go
+ * through the storage layer's atomic temp-write+rename so a crash mid-rewrite
+ * cannot truncate the prior good file.
+ */
+export declare class SessionManager {
+    #private;
+    /**
+     * Collab replication tap: invoked for every appended entry with the
+     * in-memory (pre-blob-externalization) entry, so inline images survive.
+     */
+    onEntryAppended?: (entry: SessionEntry) => void;
+    private constructor();
+    /** Puts a binary blob into the blob store and returns the blob reference. */
+    putBlob(data: Buffer, options?: BlobPutOptions): Promise<BlobPutResult>;
+    /** Synchronous variant of {@link putBlob} for rebuild-only render paths. */
+    putBlobSync(data: Buffer, options?: BlobPutOptions): BlobPutResult;
+    captureState(): SessionManagerStateSnapshot;
+    restoreState(snapshot: SessionManagerStateSnapshot): void;
+    /** Switch to a different session file (resume / branch). */
+    setSessionFile(sessionFile: string): Promise<void>;
+    /** Start a new session. Drains and closes any existing writer first. */
+    newSession(options?: NewSessionOptions): Promise<string | undefined>;
+    /** Delete a session file and its artifact directory. ENOENT is treated as success. */
+    dropSession(sessionPath: string): Promise<void>;
+    /**
+     * Fork the current session into a new file with the same entries.
+     * @returns the old and new session file paths, or undefined when not persisting.
+     */
+    fork(): Promise<{
+        oldSessionFile: string;
+        newSessionFile: string;
+    } | undefined>;
+    /**
+     * Move the session to a new working directory: relocate the session file and
+     * artifacts on disk, update internal references, and rewrite the header cwd.
+     */
+    moveTo(newCwd: string, targetSessionDir?: string): Promise<void>;
+    /**
+     * Force the session onto disk even with no assistant message yet (ACP
+     * session/new must create a discoverable file immediately).
+     */
+    ensureOnDisk(): Promise<void>;
+    /** Flush pending writes. Call before switching sessions or on shutdown. */
+    flush(): Promise<void>;
+    /**
+     * Synchronously makes the current append-only session durable. Avoid rewriting
+     * an already-current file: large restored sessions can contain GiB of compacted
+     * history, and Ctrl+C must not rebuild the whole JSONL string just to flush.
+     */
+    flushSync(): void;
+    /** Flush, then close the append writer. */
+    close(): Promise<void>;
+    getCwd(): string;
+    getUsageStatistics(): UsageStatistics;
+    /**
+     * Open a new per-turn budget window: snapshot the cumulative output baseline,
+     * reset the eval-subagent counter, and set the (optional) ceiling.
+     */
+    beginTurnBudget(total: number | null, hard: boolean): void;
+    recordEvalSubagentOutput(output: number): void;
+    getTurnBudget(): {
+        total: number | null;
+        spent: number;
+        hard: boolean;
+    };
+    getSessionDir(): string;
+    getSessionId(): string;
+    getSessionFile(): string | undefined;
+    getArtifactsDir(): string | null;
+    adoptArtifactManager(manager: ArtifactManager): void;
+    getArtifactManager(): ArtifactManager | null;
+    allocateArtifactPath(toolType: string): Promise<{
+        id?: string;
+        path?: string;
+    }>;
+    saveArtifact(content: string, toolType: string): Promise<string | undefined>;
+    getArtifactPath(id: string): Promise<string | null>;
+    saveDraft(text: string): Promise<void>;
+    consumeDraft(): Promise<string | null>;
+    /** The source that set the session name: "user" (manual/RPC) or "auto" (generated title). */
+    get titleSource(): SessionTitleSource | undefined;
+    getSessionName(): string | undefined;
+    onSessionNameChanged(cb: () => void): () => void;
+    /**
+     * Set the session display name.
+     * @param source "user" for explicit renames; "auto" for generated titles.
+     *   Auto titles are ignored once the user has set a name.
+     */
+    setSessionName(name: string, source?: SessionTitleSource, trigger?: string): Promise<boolean>;
+    /**
+     * Append a foreign (host-authored) entry verbatim, preserving its
+     * `id`/`parentId`. Used by collab guests to mirror the host session.
+     */
+    ingestReplicatedEntry(entry: SessionEntry): void;
+    /**
+     * Snapshot the session for collab replication: the live header plus a deep
+     * copy of every entry (the host mutates entries in place on rewrite paths, so
+     * guests must not share references).
+     */
+    snapshotForReplication(): {
+        header: SessionHeader;
+        entries: SessionEntry[];
+    };
+    /**
+     * Append a message as a child of the current leaf, then advance the leaf.
+     * CompactionSummaryMessage / BranchSummaryMessage are rejected here — they are
+     * top-level entries via appendCompaction()/branchWithSummary().
+     */
+    appendMessage(message: Message | CustomMessage | HookMessage | BashExecutionMessage | PythonExecutionMessage | FileMentionMessage): string;
+    /** Append a thinking level change as child of current leaf, then advance leaf. Returns entry id. */
+    appendThinkingLevelChange(thinkingLevel?: string, configured?: string): string;
+    appendServiceTierChange(serviceTier: ServiceTierByFamily | null): string;
+    appendModeChange(mode: string, data?: Record<string, unknown>): string;
+    /**
+     * Append a model change as a child of the current leaf, then advance the leaf.
+     * @param model Model in "provider/modelId" format
+     * @param role Optional role (default: "default")
+     */
+    appendModelChange(model: string, role?: string): string;
+    appendSessionInit(init: {
+        systemPrompt: string;
+        task: string;
+        tools: string[];
+        outputSchema?: unknown;
+        spawns?: string;
+        readSummarize?: boolean;
+    }): string;
+    appendCompaction<T = unknown>(summary: string, shortSummary: string | undefined, firstKeptEntryId: string, tokensBefore: number, details?: T, fromExtension?: boolean, preserveData?: Record<string, unknown>): string;
+    appendCustomEntry(customType: string, data?: unknown): string;
+    /**
+     * Rewrite the session file after in-place entry updates (e.g. pruning old tool
+     * outputs). Use sparingly.
+     */
+    rewriteEntries(): Promise<void>;
+    /**
+     * Append a custom message entry (for extensions) that participates in LLM context.
+     * @param customType Hook identifier for filtering on reload
+     * @param content Message content (string or TextContent/ImageContent array)
+     * @param display Whether to show in TUI (true = styled display, false = hidden)
+     * @param details Optional extension-specific metadata (not sent to LLM)
+     * @param attribution Who initiated this message for billing/attribution semantics
+     */
+    appendCustomMessageEntry<T = unknown>(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details?: T, attribution?: MessageAttribution): string;
+    /**
+     * Append an MCP tool selection entry recording the discovery-selected MCP tools.
+     */
+    appendMCPToolSelection(selectedToolNames: string[]): string;
+    /** Append a TTSR injection entry recording which rules were injected. */
+    appendTtsrInjection(ruleNames: string[]): string;
+    /** All unique TTSR rule names injected on the current branch (root → leaf). */
+    getInjectedTtsrRules(): string[];
+    getLeafId(): string | null;
+    getLeafEntry(): SessionEntry | undefined;
+    /**
+     * The most recent model role on the current branch, or undefined when no
+     * model change has been recorded.
+     */
+    getLastModelChangeRole(): string | undefined;
+    getEntry(id: string): SessionEntry | undefined;
+    /** All direct children of an entry. */
+    getChildren(parentId: string): SessionEntry[];
+    getLabel(id: string): string | undefined;
+    /**
+     * Set or clear a label on an entry. Pass undefined/empty to clear.
+     */
+    appendLabelChange(targetId: string, label: string | undefined): string;
+    /**
+     * Walk from an entry to root, returning entries in path order. Includes all
+     * entry types; use buildSessionContext() for the resolved LLM messages.
+     */
+    getBranch(fromId?: string): SessionEntry[];
+    /**
+     * Build the session context (LLM messages), or — with `{ transcript: true }` —
+     * the full-history display transcript, from the current leaf path.
+     */
+    buildSessionContext(options?: BuildSessionContextOptions): SessionContext;
+    /** Strip stale OpenAI Responses assistant replay metadata from loaded entries. */
+    sanitizeLoadedOpenAIResponsesReplayMetadata(): boolean;
+    getHeader(): SessionHeader | null;
+    /** All session entries (excludes header). Returns a shallow copy. */
+    getEntries(): SessionEntry[];
+    /**
+     * The session as a tree. A well-formed session has exactly one root; orphaned
+     * entries (broken parent chain) are returned as roots too.
+     */
+    getTree(): SessionTreeNode[];
+    /**
+     * Move the leaf to an earlier entry so the next append forms a new branch.
+     * Existing entries are never modified or deleted.
+     */
+    branch(branchFromId: string): void;
+    /** Reset the leaf to null so the next append creates a new root entry. */
+    resetLeaf(): void;
+    /** Like branch(), but also records a branch_summary of the abandoned path. */
+    branchWithSummary(branchFromId: string | null, summary: string, details?: unknown, fromExtension?: boolean): string;
+    /**
+     * Create a new session file containing only the path from root to `leafId`.
+     * Returns the new file path, or undefined when not persisting.
+     */
+    createBranchedSession(leafId: string): string | undefined;
+    /** Resolve the canonical default session directory for a cwd. */
+    static getDefaultSessionDir(cwd: string, agentDir?: string, storage?: SessionStorage): string;
+    /**
+     * Create a new session.
+     * @param cwd Working directory (stored in the session header)
+     * @param sessionDir Optional session directory; defaults to the cwd-derived dir.
+     */
+    static create(cwd: string, sessionDir?: string, storage?: SessionStorage): SessionManager;
+    /**
+     * Create a fresh empty session file in the default session directory for
+     * `cwd`, writing only the session header. The returned path can be passed to
+     * `setSessionFile` / `AgentSession.switchSession` when a caller explicitly
+     * needs a brand-new persisted session at a cwd-derived path.
+     */
+    static createEmptySessionFile(cwd: string, storage?: SessionStorage): string;
+    /**
+     * Fork a session into the current project directory: copy history from another
+     * session file while creating a fresh session file in this sessionDir.
+     *
+     * `options.sessionFile` pins the new session's file path (default: an
+     * auto-named `<timestamp>_<id>.jsonl` in `sessionDir`). Callers that register
+     * the fork as a named agent (e.g. `/tan`) pass `<agentId>.jsonl` so the
+     * persisted-subagent scan keys the agent by the same id the live ref uses.
+     */
+    static forkFrom(sourcePath: string, cwd: string, sessionDir?: string, storage?: SessionStorage, options?: {
+        suppressBreadcrumb?: boolean;
+        sessionFile?: string;
+    }): Promise<SessionManager>;
+    /**
+     * Open a specific session file.
+     * @param sessionDir Optional dir for /new or /branch; defaults to the file's parent.
+     * @param options.initialCwd Cwd to use when the file is empty or missing.
+     */
+    static open(filePath: string, sessionDir?: string, storage?: SessionStorage, options?: {
+        initialCwd?: string;
+        suppressBreadcrumb?: boolean;
+    }): Promise<SessionManager>;
+    /**
+     * Lock-free peek for cold subagent revival: returns the recorded working
+     * directory (session header) and the latest `session_init` contract (system
+     * prompt / tools / output schema) WITHOUT taking the single-writer lock that
+     * {@link open} acquires — the caller re-opens for the actual revive. Returns
+     * null when the file can't be read; `init` is null for files written before
+     * `session_init` was recorded (no faithful contract to rebuild from).
+     */
+    static peekSessionInit(filePath: string, storage?: SessionStorage): Promise<{
+        cwd: string;
+        init: {
+            systemPrompt: string;
+            task: string;
+            tools: string[];
+            outputSchema?: unknown;
+            spawns?: string;
+            readSummarize?: boolean;
+        } | null;
+    } | null>;
+    /** Continue the most recent session, or create a new one if none exists. */
+    static continueRecent(cwd: string, sessionDir?: string, storage?: SessionStorage): Promise<SessionManager>;
+    /** Create an in-memory session (no file persistence). */
+    static inMemory(cwd?: string, storage?: SessionStorage): SessionManager;
+    /**
+     * List sessions for a project directory.
+     * @param sessionDir Optional dir; defaults to the cwd-derived dir.
+     */
+    static list(cwd: string, sessionDir?: string, storage?: SessionStorage): Promise<SessionInfo[]>;
+    /** List all sessions across all project directories. */
+    static listAll(storage?: SessionStorage): Promise<SessionInfo[]>;
+}
+/**
+ * If the current session was created by `/move` and contains no real
+ * user/assistant messages, delete it so empty move sessions don't accumulate.
+ */
+export declare function cleanupEmptyMoveSession(sessionManager: SessionManager, movedFromEmptySessionFile: string | undefined): Promise<void>;
+export {};

package/dist/types/session/session-migrations.d.ts

@@ -0,0 +1,12 @@
+import { type FileEntry } from "./session-entries";
+/** Generate a unique short ID (8 hex chars, collision-checked) */
+export declare function generateId(byId: {
+    has(id: string): boolean;
+}): string;
+/**
+ * Run all necessary migrations to bring entries to current version.
+ * Mutates entries in place. Returns true if any migration was applied.
+ */
+export declare function migrateToCurrentVersion(entries: FileEntry[]): boolean;
+/** Exported for testing */
+export declare function migrateSessionEntries(entries: FileEntry[]): void;

package/dist/types/session/session-paths.d.ts

@@ -0,0 +1,25 @@
+import type { SessionStorage } from "./session-storage";
+export declare function resolveManagedSessionRoot(sessionDir: string, cwd: string): string | undefined;
+/**
+ * Compute the default session directory for a cwd.
+ * Classifies cwd by canonical location so symlink/alias paths resolve to the
+ * same home-relative or temp-root directory names as their real targets.
+ */
+export declare function computeDefaultSessionDir(cwd: string, storage: SessionStorage, sessionsRoot?: string): string;
+/**
+ * Write a breadcrumb linking the current terminal to a session file.
+ * The breadcrumb contains the cwd and session path so --continue can
+ * find "this terminal's last session" even when running concurrent instances.
+ */
+export declare function writeTerminalBreadcrumb(cwd: string, sessionFile: string): void;
+export interface TerminalBreadcrumb {
+    cwd: string;
+    sessionFile: string;
+}
+/**
+ * Read the raw terminal breadcrumb for the current terminal.
+ * Returns the recorded cwd + session file (verified to exist) regardless of
+ * whether the recorded cwd still matches the current one. Callers decide how
+ * to interpret a cwd mismatch (e.g. a moved/renamed worktree).
+ */
+export declare function readTerminalBreadcrumbEntry(): Promise<TerminalBreadcrumb | null>;

package/dist/types/session/session-persistence.d.ts

@@ -0,0 +1,12 @@
+import { type BlobStore } from "./blob-store";
+import type { FileEntry } from "./session-entries";
+export declare function isImageBlock(value: unknown): value is {
+    type: "image";
+    data: string;
+    mimeType?: string;
+};
+export declare function isImageDataPayload(value: unknown): value is {
+    data: string;
+    mimeType?: string;
+};
+export declare function prepareEntryForPersistence(entry: FileEntry, blobStore: BlobStore): FileEntry;

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

@@ -0,0 +1,101 @@
+import { type SessionTitleUpdate } from "./session-title-slot";
+export interface SessionStorageStat {
+    size: number;
+    mtimeMs: number;
+    mtime: Date;
+}
+export interface SessionStorageWriter {
+    /**
+     * Append one newline-terminated line. File and memory storage perform the
+     * write synchronously in-body; indexed backends queue in call order.
+     *
+     * `line` MUST include the trailing newline.
+     */
+    append(line: string): Promise<void>;
+    /** Resolve once all queued appends complete. No fsync. */
+    flush(): Promise<void>;
+    /** False once close() has begun/finished. */
+    isOpen(): boolean;
+    close(): Promise<void>;
+    getError(): Error | undefined;
+}
+export interface SessionStorage {
+    ensureDirSync(dir: string): void;
+    existsSync(path: string): boolean;
+    writeTextSync(path: string, content: string): void;
+    /**
+     * Update the current session title through the storage backend.
+     *
+     * File-like backends rewrite the fixed-width JSONL title slot; indexed
+     * backends can store the semantic title fields and synthesize the slot when
+     * reading.
+     */
+    updateSessionTitle(path: string, update: SessionTitleUpdate): Promise<void>;
+    statSync(path: string): SessionStorageStat;
+    listFilesSync(dir: string, pattern: string): string[];
+    exists(path: string): Promise<boolean>;
+    readText(path: string): Promise<string>;
+    /** Read the requested UTF-8 byte windows from the head and tail of the file. */
+    readTextSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
+    writeText(path: string, content: string): Promise<void>;
+    writeTextAtomic(path: string, content: string): Promise<void>;
+    rename(path: string, nextPath: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
+    openWriter(path: string, options?: {
+        flags?: "a" | "w";
+        onError?: (err: Error) => void;
+    }): SessionStorageWriter;
+}
+export declare class FileSessionStorage implements SessionStorage {
+    #private;
+    ensureDirSync(dir: string): void;
+    existsSync(path: string): boolean;
+    writeTextSync(fpath: string, content: string): void;
+    updateSessionTitle(fpath: string, update: SessionTitleUpdate): Promise<void>;
+    statSync(path: string): SessionStorageStat;
+    listFilesSync(dir: string, pattern: string): string[];
+    exists(path: string): Promise<boolean>;
+    readText(path: string): Promise<string>;
+    readTextSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
+    writeText(path: string, content: string): Promise<void>;
+    writeTextAtomic(fpath: string, content: string): Promise<void>;
+    rename(path: string, nextPath: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    openWriter(path: string, options?: {
+        flags?: "a" | "w";
+        onError?: (err: Error) => void;
+    }): SessionStorageWriter;
+    /**
+     * Delete a session file and its artifacts directory.
+     * Artifacts are stored in a sibling directory with the same name minus .jsonl extension.
+     */
+    deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
+}
+export declare class MemorySessionStorage implements SessionStorage {
+    #private;
+    ensureDirSync(_dir: string): void;
+    existsSync(path: string): boolean;
+    writeTextSync(path: string, content: string): void;
+    updateSessionTitle(path: string, update: SessionTitleUpdate): Promise<void>;
+    /**
+     * Internal O(1) append used by {@link MemorySessionStorageWriter}. Lazily
+     * creates the entry. External callers should go through `openWriter()`
+     * rather than touching the mirror directly.
+     */
+    appendSync(path: string, chunk: string): void;
+    statSync(path: string): SessionStorageStat;
+    listFilesSync(dir: string, pattern: string): string[];
+    exists(path: string): Promise<boolean>;
+    readText(path: string): Promise<string>;
+    readTextSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
+    writeText(path: string, content: string): Promise<void>;
+    writeTextAtomic(path: string, content: string): Promise<void>;
+    rename(path: string, nextPath: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    deleteSessionWithArtifacts(_sessionPath: string): Promise<void>;
+    openWriter(path: string, options?: {
+        flags?: "a" | "w";
+        onError?: (err: Error) => void;
+    }): SessionStorageWriter;
+}

package/dist/types/session/session-title-slot.d.ts

@@ -0,0 +1,19 @@
+import { type SessionTitleSlotEntry, type SessionTitleSource } from "./session-entries";
+/** Semantic title update persisted by session storage backends. */
+export interface SessionTitleUpdate {
+    title?: string;
+    source?: SessionTitleSource;
+    updatedAt: string;
+}
+/** Parse a physical title slot JSONL line. Returns undefined for legacy headers. */
+export declare function parseTitleSlotLine(line: string): SessionTitleSlotEntry | undefined;
+/** Parse the fixed-width title slot from a physical session body. */
+export declare function parseTitleSlotFromContent(content: string): SessionTitleSlotEntry | undefined;
+/** Convert a parsed title slot to the semantic storage update shape. */
+export declare function titleUpdateFromSlot(slot: SessionTitleSlotEntry | undefined): SessionTitleUpdate | undefined;
+/** Serialize the fixed-width first-line title slot, exactly 256 UTF-8 bytes including newline. */
+export declare function serializeTitleSlot(options: SessionTitleUpdate): string;
+/** Replace the physical fixed-width title slot in a full session body. */
+export declare function overlayTitleSlotContent(content: string, update: SessionTitleUpdate): string;
+/** Replace the physical fixed-width title slot in a prefix byte window. */
+export declare function overlayTitleSlotPrefix(prefix: string, prefixBytes: number, update: SessionTitleUpdate): string;

package/dist/types/session/settings-stream-fn.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Settings-aware stream wrapper shared by the main agent (sdk.ts) and the
+ * advisor agent (AgentSession.#buildAdvisorRuntime).
+ *
+ * verbosity, stream watchdog budgets, per-provider in-flight caps, and the loop
+ * guard out of `Settings`
+ * per request, layering them onto whatever options the caller passed. Before
+ * this helper existed, advisor turns called bare `streamSimple` while the main
+ * turn went through an inline closure that read these settings — so an advisor on
+ * OpenRouter never saw `providers.openrouterVariant`, breaking sticky routing
+ * and OpenRouter response-cache hits across advisor calls.
+ */
+import type { StreamFn } from "jeopi-agent-core";
+import { type Settings } from "../config/settings";
+/**
+ * Build a {@link StreamFn} that reads provider routing/guard settings from
+ * `settings` per call and forwards to `base` (defaults to `streamSimple`).
+ *
+ * Caller-supplied `streamOptions` always win — the helper only fills holes.
+ */
+export declare function createSettingsAwareStreamFn(settings: Settings, base?: StreamFn): StreamFn;

package/dist/types/session/shake-types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Public shape of the `shake` operation, kept in a dependency-free leaf module
+ * so slash-command registries and controllers can import `formatShakeSummary`
+ * without pulling in the heavy `agent-session` module graph (which would form
+ * an import cycle through the slash-command registry).
+ */
+/** Mode selector for `AgentSession.shake`. */
+export type ShakeMode = "elide" | "images";
+/** Outcome of an `AgentSession.shake` run. */
+export interface ShakeResult {
+    mode: ShakeMode;
+    /** Whole tool-call results dropped. */
+    toolResultsDropped: number;
+    /** Large fenced/XML blocks dropped. */
+    blocksDropped: number;
+    /** Image blocks removed (images mode only). */
+    imagesDropped?: number;
+    /** Estimated context tokens reclaimed. */
+    tokensFreed: number;
+    /** Session artifact holding the dropped originals, when persisted. */
+    artifactId?: string;
+}
+/** One-line operator summary of a {@link ShakeResult} (shared by TUI + ACP). */
+export declare function formatShakeSummary(result: ShakeResult): string;