@oh-my-pi/pi-coding-agent 15.12.3 → 15.13.0

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

@@ -1,297 +1,12 @@
-import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { ImageContent, Message, MessageAttribution, ServiceTier, TextContent } from "@oh-my-pi/pi-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 { SessionStorage } from "./session-storage";
-export declare const CURRENT_SESSION_VERSION = 3;
-export interface SessionHeader {
-    type: "session";
-    version?: number;
-    id: string;
-    title?: string;
-    titleSource?: "auto" | "user";
-    timestamp: string;
-    cwd: string;
-    parentSession?: string;
-}
-export interface NewSessionOptions {
-    parentSession?: string;
-    /** Skip flushing the current session and delete it instead of saving. */
-    drop?: boolean;
-}
-export interface SessionEntryBase {
-    type: string;
-    id: string;
-    parentId: string | null;
-    timestamp: string;
-}
-export interface SessionMessageEntry extends SessionEntryBase {
-    type: "message";
-    message: AgentMessage;
-}
-export interface ThinkingLevelChangeEntry extends SessionEntryBase {
-    type: "thinking_level_change";
-    thinkingLevel?: string | null;
-}
-export interface ModelChangeEntry extends SessionEntryBase {
-    type: "model_change";
-    /** Model in "provider/modelId" format */
-    model: string;
-    /** Role: "default", "smol", "slow", etc. Undefined treated as "default" */
-    role?: string;
-}
-export interface ServiceTierChangeEntry extends SessionEntryBase {
-    type: "service_tier_change";
-    serviceTier: ServiceTier | null;
-}
-export interface CompactionEntry<T = unknown> extends SessionEntryBase {
-    type: "compaction";
-    summary: string;
-    shortSummary?: string;
-    firstKeptEntryId: string;
-    tokensBefore: number;
-    /** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
-    details?: T;
-    /** Hook-provided data to persist across compaction */
-    preserveData?: Record<string, unknown>;
-    /** True if generated by an extension, undefined/false if pi-generated (backward compatible) */
-    fromExtension?: boolean;
-}
-export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {
-    type: "branch_summary";
-    fromId: string;
-    summary: string;
-    /** Extension-specific data (not sent to LLM) */
-    details?: T;
-    /** True if generated by an extension, false if pi-generated */
-    fromExtension?: boolean;
-}
-/**
- * Custom entry for extensions to store extension-specific data in the session.
- * Use customType to identify your extension's entries.
- *
- * Purpose: Persist extension state across session reloads. On reload, extensions can
- * scan entries for their customType and reconstruct internal state.
- *
- * Does NOT participate in LLM context (ignored by buildSessionContext).
- * For injecting content into context, see CustomMessageEntry.
- */
-export interface CustomEntry<T = unknown> extends SessionEntryBase {
-    type: "custom";
-    customType: string;
-    data?: T;
-}
-/** Label entry for user-defined bookmarks/markers on entries. */
-export interface LabelEntry extends SessionEntryBase {
-    type: "label";
-    targetId: string;
-    label: string | undefined;
-}
-/** TTSR injection entry - tracks which time-traveling rules have been injected this session. */
-export interface TtsrInjectionEntry extends SessionEntryBase {
-    type: "ttsr_injection";
-    /** Names of rules that were injected */
-    injectedRules: string[];
-}
-/** Persisted MCP discovery selection state for a session branch. */
-export interface MCPToolSelectionEntry extends SessionEntryBase {
-    type: "mcp_tool_selection";
-    /** MCP tool names selected for visibility in discovery mode. */
-    selectedToolNames: string[];
-}
-/** Session init entry - captures initial context for subagent sessions (debugging/replay). */
-export interface SessionInitEntry extends SessionEntryBase {
-    type: "session_init";
-    /** Full system prompt sent to the model */
-    systemPrompt: string;
-    /** Initial task/user message */
-    task: string;
-    /** Tools available to the agent */
-    tools: string[];
-    /** Output schema if structured output was requested */
-    outputSchema?: unknown;
-}
-/** Mode change entry - tracks agent mode transitions (e.g. plan mode). */
-export interface ModeChangeEntry extends SessionEntryBase {
-    type: "mode_change";
-    /** Current mode name, or "none" when exiting a mode */
-    mode: string;
-    /** Optional mode-specific data (e.g. plan file path) */
-    data?: Record<string, unknown>;
-}
-/**
- * Custom message entry for extensions to inject messages into LLM context.
- * Use customType to identify your extension's entries.
- *
- * Unlike CustomEntry, this DOES participate in LLM context.
- * The content participates in LLM context through convertToLlm().
- * Use details for extension-specific metadata (not sent to LLM).
- *
- * display controls TUI rendering:
- * - false: hidden entirely
- * - true: rendered with distinct styling (different from user messages)
- */
-export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
-    type: "custom_message";
-    customType: string;
-    content: string | (TextContent | ImageContent)[];
-    details?: T;
-    display: boolean;
-    /** Who initiated this message for billing/attribution semantics. */
-    attribution?: MessageAttribution;
-}
-/** Session entry - has id/parentId for tree structure (returned by "read" methods in SessionManager) */
-export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | ServiceTierChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | TtsrInjectionEntry | MCPToolSelectionEntry | SessionInitEntry | ModeChangeEntry;
-/** Raw file entry (includes header) */
-export type FileEntry = SessionHeader | SessionEntry;
-/** Tree node for getTree() - defensive copy of session structure */
-export interface SessionTreeNode {
-    entry: SessionEntry;
-    children: SessionTreeNode[];
-    /** Resolved label for this entry, if any */
-    label?: string;
-}
-export interface SessionContext {
-    messages: AgentMessage[];
-    thinkingLevel?: string;
-    serviceTier?: ServiceTier;
-    /** Model roles: { default: "provider/modelId", small: "provider/modelId", ... } */
-    models: Record<string, string>;
-    /** Names of TTSR rules that have been injected this session */
-    injectedTtsrRules: string[];
-    /** MCP tool names selected through discovery for this session branch. */
-    selectedMCPToolNames: string[];
-    /** Whether this branch contains an explicit persisted MCP selection entry. */
-    hasPersistedMCPToolSelection: boolean;
-    /** Active mode (e.g. "plan") or "none" if no special mode is active */
-    mode: string;
-    /** Mode-specific data from the last mode_change entry */
-    modeData?: Record<string, unknown>;
-}
-export declare const EPHEMERAL_MODEL_CHANGE_ROLE = "fallback";
-/** Lists session model strings to try when restoring, in fallback order. */
-export declare function getRestorableSessionModels(models: Readonly<Record<string, string>>, lastModelChangeRole: string | undefined): string[];
-/**
- * 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;
-}
+import { type BuildSessionContextOptions, type SessionContext } from "./session-context";
+import { type NewSessionOptions, type SessionEntry, type SessionHeader, 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">;
-/** Exported for testing */
-export declare function migrateSessionEntries(entries: FileEntry[]): void;
-/** Exported for compaction.test.ts */
-export declare function parseSessionEntries(content: string): FileEntry[];
-export declare function getLatestCompactionEntry(entries: SessionEntry[]): CompactionEntry | null;
-export interface BuildSessionContextOptions {
-    /**
-     * Build the full-history display transcript instead of the LLM context:
-     * every path entry in chronological order, with each compaction emitted
-     * inline as a `compactionSummary` message at the position it fired rather
-     * than replacing the history before it. Display-only — never send the
-     * result to a provider.
-     */
-    transcript?: boolean;
-}
-/**
- * Build the session context from entries using tree traversal.
- * If leafId is provided, walks from that entry to root.
- * Handles compaction and branch summaries along the path.
- */
-export declare function buildSessionContext(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>, options?: BuildSessionContextOptions): SessionContext;
-/** Exported for testing */
-export declare function loadEntriesFromFile(filePath: string, storage?: SessionStorage): Promise<FileEntry[]>;
-/**
- * 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[]>;
-declare class RecentSessionInfo {
-    #private;
-    readonly path: string;
-    readonly mtime: number;
-    constructor(path: string, mtime: number, header: Record<string, unknown>, firstPrompt?: string);
-    /** Display name. Falls back to a timestamp-based label, never the raw UUID. */
-    get fullName(): string;
-    /**
-     * Display name without an arbitrary length cap. The renderer is responsible for
-     * width-aware truncation so adjacent fields (e.g. the relative time) stay visible.
-     */
-    get name(): string;
-    /** Human-readable relative time (e.g., "2 hours ago") */
-    get timeAgo(): string;
-}
-/**
- * Promote orphaned `<basename>.jsonl.<snowflake>.bak` backups created by
- * `#replaceSessionFileAfterEperm` 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>;
-/** Exported for testing */
-export declare function findMostRecentSession(sessionDir: string, storage?: SessionStorage): Promise<string | null>;
-/** Get recent sessions for display in welcome screen (which reserves WELCOME_SESSION_SLOTS rows) */
-export declare function getRecentSessions(sessionDir: string, limit?: number, storage?: SessionStorage): Promise<RecentSessionInfo[]>;
-/**
- * Manages conversation sessions as append-only trees stored in JSONL files.
- *
- * Each session entry has an id and parentId forming a tree structure. The "leaf"
- * pointer tracks the current position. Appending creates a child of the current leaf.
- * Branching moves the leaf to an earlier entry, allowing new branches without
- * modifying history.
- *
- * Use buildSessionContext() to get the resolved message list for the LLM, which
- * handles compaction summaries and follows the path from root to current leaf.
- */
-export interface UsageStatistics {
-    input: number;
-    output: number;
-    cacheRead: number;
-    cacheWrite: number;
-    premiumRequests: number;
-    cost: number;
-}
-export interface ResolvedSessionMatch {
-    session: SessionInfo;
-    scope: "local" | "global";
-}
-export declare function resolveResumableSession(sessionArg: string, cwd: string, sessionDir?: string, storage?: SessionStorage): Promise<ResolvedSessionMatch | undefined>;
 interface SessionManagerStateSnapshot {
     cwd: string;
     sessionDir: string;
@@ -299,78 +14,81 @@ interface SessionManagerStateSnapshot {
     sessionName: string | undefined;
     titleSource: "auto" | "user" | undefined;
     sessionFile: string | undefined;
-    flushed: boolean;
-    needsFullRewriteOnNextPersist: boolean;
-    fileEntries: FileEntry[];
+    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;
-    private cwd;
-    private sessionDir;
-    private readonly persist;
-    private readonly storage;
     /**
      * Collab replication tap: invoked for every appended entry with the
      * in-memory (pre-blob-externalization) entry, so inline images survive.
-     * Failures are swallowed — a broadcast error must never break persistence.
      */
     onEntryAppended?: (entry: SessionEntry) => void;
     private constructor();
-    /** Puts a binary blob into the blob store and returns the blob reference */
+    /** 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 (used for resume and branching) */
+    /** Switch to a different session file (resume / branch). */
     setSessionFile(sessionFile: string): Promise<void>;
-    /** Start a new session. Closes any existing writer first. */
+    /** Start a new session. Drains and closes any existing writer first. */
     newSession(options?: NewSessionOptions): Promise<string | undefined>;
-    /** Delete a session file and its artifacts. Drains the persist writer first to avoid EPERM on Windows. ENOENT is treated as success. */
+    /** Delete a session file and its artifact directory. ENOENT is treated as success. */
     dropSession(sessionPath: string): Promise<void>;
     /**
-     * Fork the current session, creating a new session file with the same entries.
-     * Returns both the old and new session file paths for artifact copying.
-     * @returns { oldSessionFile, newSessionFile } or undefined if not persisting
+     * 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.
-     * Moves session files and artifacts on disk, updates all internal references,
-     * and rewrites the session header with the new cwd. When provided,
-     * `targetSessionDir` is used instead of deriving the default directory for
-     * the new cwd (for `--continue --session-dir` / `--resume --session-dir`).
+     * 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>;
-    isPersisted(): boolean;
     /**
-     * Force-persist all current entries to disk, even when no assistant message exists yet.
-     * Used by ACP mode where session/new must create a discoverable session immediately.
+     * 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 to disk. Call before switching sessions or on shutdown. */
+    /** Flush pending writes. Call before switching sessions or on shutdown. */
     flush(): Promise<void>;
-    /** Close the persistent writer after flushing all pending data. */
+    /**
+     * Synchronously flush all in-memory entries to disk. Use when the process may
+     * exit before an async flush settles (Ctrl+C in the TUI). Software-crash
+     * durable; not atomic and not power-loss safe — a same-process crash never
+     * lands mid-`writeFileSync`.
+     */
+    flushSync(): void;
+    /** Flush, then close the append writer. */
     close(): Promise<void>;
     getCwd(): string;
-    /** Get usage statistics across all assistant messages in the session. */
     getUsageStatistics(): UsageStatistics;
     /**
      * Open a new per-turn budget window: snapshot the cumulative output baseline,
-     * reset the eval-subagent counter, and set the (optional) ceiling. Called once
-     * per real user message; `total` is null when no `+Nk` directive was present.
+     * reset the eval-subagent counter, and set the (optional) ceiling.
      */
     beginTurnBudget(total: number | null, hard: boolean): void;
-    /** Record output tokens consumed by an eval-spawned subagent in the current turn. */
     recordEvalSubagentOutput(output: number): void;
-    /**
-     * Current turn budget for the eval `budget` helper: the ceiling (null = none),
-     * output tokens spent this turn (main loop + eval-spawned subagents, no
-     * double-count), and whether the ceiling is hard.
-     */
     getTurnBudget(): {
         total: number | null;
         spent: number;
@@ -379,114 +97,67 @@ export declare class SessionManager {
     getSessionDir(): string;
     getSessionId(): string;
     getSessionFile(): string | undefined;
-    /**
-     * Returns the session artifacts directory path (session file path without .jsonl).
-     * Returns null when the session is not persisted to a file.
-     * When this session has adopted an external ArtifactManager (subagent case),
-     * returns that manager's directory so reads/writes land in the shared parent
-     * dir instead of a private (non-existent) subdir.
-     */
     getArtifactsDir(): string | null;
-    /**
-     * Adopt an externally-owned ArtifactManager. Used by subagents to share
-     * the parent session's artifact directory and ID counter.
-     */
     adoptArtifactManager(manager: ArtifactManager): void;
-    /**
-     * Returns the ArtifactManager this session writes through. Lazily creates
-     * one bound to the current session file unless an external manager was
-     * adopted via `adoptArtifactManager`. Returns null only for non-persistent
-     * sessions with no adopted manager.
-     */
     getArtifactManager(): ArtifactManager | null;
-    /**
-     * Allocate a new artifact path and ID for the current session.
-     * Returns an empty object when the session is not persisted.
-     */
     allocateArtifactPath(toolType: string): Promise<{
         id?: string;
         path?: string;
     }>;
-    /**
-     * Save artifact content under the current session and return artifact ID.
-     * Returns an artifact ID for all sessions (file-backed for persistent, in-memory fallback otherwise).
-     */
     saveArtifact(content: string, toolType: string): Promise<string | undefined>;
-    /**
-     * Resolve an artifact ID to an on-disk path for the current session.
-     * Returns null when missing or when the session is not persisted.
-     */
     getArtifactPath(id: string): Promise<string | null>;
-    /**
-     * Persist (or clear) the current editor draft so the next resume of this
-     * session can restore it. Empty text deletes any stale draft. No-op when the
-     * session is not persisted.
-     */
     saveDraft(text: string): Promise<void>;
-    /**
-     * Read and remove the saved draft. Returns the previously-saved text, or
-     * null when no draft is pending. Single-shot: a successful read removes the
-     * sidecar so a subsequent resume does not re-restore the same text.
-     */
     consumeDraft(): Promise<string | null>;
-    /** The source that set the session name: "user" (manual /rename or RPC) or "auto" (generated title). */
+    /** The source that set the session name: "user" (manual/RPC) or "auto" (generated title). */
     get titleSource(): "auto" | "user" | undefined;
     getSessionName(): string | undefined;
     onSessionNameChanged(cb: () => void): () => void;
     /**
      * Set the session display name.
-     * @param source - "user" for explicit renames (/rename command, RPC); "auto" for generated titles.
-     *   Auto-generated titles are silently ignored when the user has already set a 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?: "auto" | "user"): Promise<boolean>;
-    _persist(entry: SessionEntry): void;
     /**
      * Append a foreign (host-authored) entry verbatim, preserving its
-     * `id`/`parentId` — no id minting. Used by collab guests to mirror the
-     * host session into the local replica file.
+     * `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
-     * truncation/rewrite paths, so guests must not share references).
+     * 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 child of current leaf, then advance leaf. Returns entry id.
-     * Does not allow writing CompactionSummaryMessage and BranchSummaryMessage directly.
-     * Reason: we want these to be top-level entries in the session, not message session entries,
-     * so it is easier to find them.
-     * These need to be appended via appendCompaction() and appendBranchSummary() methods.
+    /**
+     * 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): string;
     appendServiceTierChange(serviceTier: ServiceTier | null): string;
-    /** Append a mode change as child of current leaf, then advance leaf. Returns entry id. */
     appendModeChange(mode: string, data?: Record<string, unknown>): string;
     /**
-     * Append a model change as child of current leaf, then advance leaf. Returns entry id.
+     * 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;
-    /** Append session init metadata (for subagent debugging/replay). Returns entry id. */
     appendSessionInit(init: {
         systemPrompt: string;
         task: string;
         tools: string[];
         outputSchema?: unknown;
     }): string;
-    /** Append a compaction summary as child of current leaf, then advance leaf. Returns entry id. */
     appendCompaction<T = unknown>(summary: string, shortSummary: string | undefined, firstKeptEntryId: string, tokensBefore: number, details?: T, fromExtension?: boolean, preserveData?: Record<string, unknown>): string;
-    /** Append a custom entry (for extensions) as child of current leaf, then advance leaf. Returns entry id. */
     appendCustomEntry(customType: string, data?: unknown): string;
     /**
-     * Rewrite the session file after in-place entry updates.
-     * Use sparingly (e.g., pruning old tool outputs).
+     * Rewrite the session file after in-place entry updates (e.g. pruning old tool
+     * outputs). Use sparingly.
      */
     rewriteEntries(): Promise<void>;
     /**
@@ -496,143 +167,95 @@ export declare class SessionManager {
      * @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
-     * @returns Entry id
      */
     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.
-     * @param selectedToolNames MCP tool names selected for this branch
-     * @returns Entry id
      */
     appendMCPToolSelection(selectedToolNames: string[]): string;
-    /**
-     * Append a TTSR injection entry recording which rules were injected.
-     * @param ruleNames Names of rules that were injected
-     * @returns Entry id
-     */
+    /** Append a TTSR injection entry recording which rules were injected. */
     appendTtsrInjection(ruleNames: string[]): string;
-    /**
-     * Get all unique TTSR rule names that have been injected in the current branch.
-     * Scans from root to current leaf for ttsr_injection entries.
-     */
+    /** All unique TTSR rule names injected on the current branch (root → leaf). */
     getInjectedTtsrRules(): string[];
     getLeafId(): string | null;
     getLeafEntry(): SessionEntry | undefined;
     /**
-     * Get the most recent model role from the current session path.
-     * Returns undefined if no model change has been recorded.
+     * 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;
-    /**
-     * Get all direct children of an entry.
-     */
+    /** All direct children of an entry. */
     getChildren(parentId: string): SessionEntry[];
-    /**
-     * Get the label for an entry, if any.
-     */
     getLabel(id: string): string | undefined;
     /**
-     * Set or clear a label on an entry.
-     * Labels are user-defined markers for bookmarking/navigation.
-     * Pass undefined or empty string to clear the label.
+     * Set or clear a label on an entry. Pass undefined/empty to clear.
      */
     appendLabelChange(targetId: string, label: string | undefined): string;
     /**
-     * Walk from entry to root, returning all entries in path order.
-     * Includes all entry types (messages, compaction, model changes, etc.).
-     * Use buildSessionContext() to get the resolved messages for the LLM.
+     * 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 (what gets sent to the LLM), or — with
-     * `{ transcript: true }` — the full-history display transcript.
-     * Uses tree traversal from current leaf.
+     * 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 in-memory entries. */
+    /** Strip stale OpenAI Responses assistant replay metadata from loaded entries. */
     sanitizeLoadedOpenAIResponsesReplayMetadata(): boolean;
-    /**
-     * Get session header.
-     */
     getHeader(): SessionHeader | null;
-    /**
-     * Get all session entries (excludes header). Returns a shallow copy.
-     * The session is append-only: use appendXXX() to add entries, branch() to
-     * change the leaf pointer. Entries cannot be modified or deleted.
-     */
+    /** All session entries (excludes header). Returns a shallow copy. */
     getEntries(): SessionEntry[];
     /**
-     * Get the session as a tree structure. Returns a shallow defensive copy of all entries.
-     * A well-formed session has exactly one root (first entry with parentId === null).
-     * Orphaned entries (broken parent chain) are also returned as roots.
+     * 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[];
     /**
-     * Start a new branch from an earlier entry.
-     * Moves the leaf pointer to the specified entry. The next appendXXX() call
-     * will create a child of that entry, forming a new branch. Existing entries
-     * are not modified or deleted.
+     * 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 pointer to null (before any entries).
-     * The next appendXXX() call will create a new root entry (parentId = null).
-     * Use this when navigating to re-edit the first user message.
-     */
+    /** Reset the leaf to null so the next append creates a new root entry. */
     resetLeaf(): void;
-    /**
-     * Start a new branch with a summary of the abandoned path.
-     * Same as branch(), but also appends a branch_summary entry that captures
-     * context from the abandoned conversation path.
-     */
+    /** 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 the specified leaf.
-     * Useful for extracting a single conversation path from a branched session.
-     * Returns the new session file path, or undefined if not persisting.
+     * 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.
-     */
+    /** 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 session header)
-     * @param sessionDir Optional session directory. If omitted, uses default (~/.omp/agent/sessions/<encoded-cwd>/).
+     * @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;
     /**
-     * Fork a session into the current project directory.
-     * Copies history from another session file while creating a new session file in the current sessionDir.
+     * Fork a session into the current project directory: copy history from another
+     * session file while creating a fresh session file in this sessionDir.
      */
     static forkFrom(sourcePath: string, cwd: string, sessionDir?: string, storage?: SessionStorage, options?: {
         suppressBreadcrumb?: boolean;
     }): Promise<SessionManager>;
     /**
      * Open a specific session file.
-     * @param path Path to session file
-     * @param sessionDir Optional session directory for /new or /branch. If omitted, derives from file's parent.
+     * @param sessionDir Optional dir for /new or /branch; defaults to the file's parent.
      */
     static open(filePath: string, sessionDir?: string, storage?: SessionStorage): Promise<SessionManager>;
-    /**
-     * Continue the most recent session, or create new if none.
-     * @param cwd Working directory
-     * @param sessionDir Optional session directory. If omitted, uses default (~/.omp/agent/sessions/<encoded-cwd>/).
-     */
+    /** 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) */
+    /** Create an in-memory session (no file persistence). */
     static inMemory(cwd?: string, storage?: SessionStorage): SessionManager;
     /**
-     * List all sessions.
-     * @param cwd Working directory (used to compute default session directory)
-     * @param sessionDir Optional session directory. If omitted, uses default (~/.omp/agent/sessions/<encoded-cwd>/).
+     * 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.
-     */
+    /** List all sessions across all project directories. */
     static listAll(storage?: SessionStorage): Promise<SessionInfo[]>;
 }
 export {};