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

package/dist/types/modes/rpc/rpc-mode.d.ts

@@ -35,7 +35,41 @@ export type RpcSessionChangeResult = {
 };
 export type RpcSessionChangeSession = Pick<AgentSession, "newSession" | "switchSession" | "branch">;
 export type RpcSkillCommandSession = Pick<AgentSession, "promptCustomMessage" | "skills" | "skillsSettings">;
-export declare function tryRunRpcSkillCommand(session: RpcSkillCommandSession, text: string): Promise<boolean>;
+export type RpcSkillCommandResult = {
+    agentInvoked: true;
+};
+export declare function tryRunRpcSkillCommand(session: RpcSkillCommandSession, text: string): Promise<RpcSkillCommandResult | false>;
+export declare function reportLocalOnlyPromptResult(input: {
+    id: string | undefined;
+    prompt: Promise<boolean>;
+    output: (obj: object) => void;
+    onError: (error: Error) => void;
+    hasExtensionAgentMessageTask?: () => boolean;
+    waitForExtensionAgentMessageTasks?: () => Promise<void>;
+}): void;
+/**
+ * Tracks extension-originated messages while an RPC prompt is executing.
+ * A slash command can resolve the outer prompt as local-only while also
+ * scheduling agent work through pi.sendUserMessage() or pi.sendMessage()
+ * with triggerTurn; that prompt must not report agentInvoked:false to the host.
+ */
+export declare class RpcExtensionUserMessageTracker {
+    #private;
+    markAgentMessageTask(): void;
+    trackAgentMessageTask(task: Promise<unknown>): void;
+    watchPrompt<T>(startPrompt: () => Promise<T>): {
+        prompt: Promise<T>;
+        hasAgentMessageTask: () => boolean;
+        waitForAgentMessageTasks: () => Promise<void>;
+    };
+}
+export declare function watchAndReportLocalOnlyPromptResult(input: {
+    id: string | undefined;
+    startPrompt: () => Promise<boolean>;
+    output: (obj: object) => void;
+    onError: (error: Error) => void;
+    extensionUserMessageTracker: RpcExtensionUserMessageTracker;
+}): void;
 export type RpcSubagentResetRegistry = Pick<RpcSubagentRegistry, "clear">;
 export declare function handleRpcSessionChange(session: RpcSessionChangeSession, command: RpcSessionChangeCommand, subagentRegistry?: RpcSubagentResetRegistry): Promise<RpcSessionChangeResult>;
 export declare function requestRpcEditor(pendingRequests: Map<string, PendingExtensionRequest>, output: RpcOutput, title: string, prefill?: string, dialogOptions?: ExtensionUIDialogOptions, editorOptions?: {

package/dist/types/modes/rpc/rpc-types.d.ts

@@ -10,7 +10,7 @@ import type { Effort, ImageContent, Model } from "@oh-my-pi/pi-ai";
 import type { BashResult } from "../../exec/bash-executor";
 import type { ContextUsage } from "../../extensibility/extensions/types";
 import type { AgentSessionEvent, SessionStats } from "../../session/agent-session";
-import type { FileEntry } from "../../session/session-manager";
+import type { FileEntry } from "../../session/session-entries";
 import type { AvailableSlashCommandSource } from "../../slash-commands/available-commands";
 import type { AgentProgress, SubagentEventPayload, SubagentLifecyclePayload, SubagentProgressPayload } from "../../task";
 import type { TodoPhase } from "../../tools/todo";
@@ -208,6 +208,11 @@ export interface RpcAvailableCommandsUpdateFrame {
     type: "available_commands_update";
     commands: RpcAvailableSlashCommand[];
 }
+export interface RpcPromptResultFrame {
+    type: "prompt_result";
+    id?: string;
+    agentInvoked: boolean;
+}
 export interface RpcHandoffResult {
     savedPath?: string;
 }
@@ -239,6 +244,9 @@ export type RpcResponse = {
     type: "response";
     command: "prompt";
     success: true;
+    data?: {
+        agentInvoked: boolean;
+    };
 } | {
     id?: string;
     type: "response";

package/dist/types/modes/runtime-init.d.ts

@@ -11,6 +11,10 @@ export interface InitializeExtensionsOptions {
     onShutdown?: () => void;
     /** Optional UI context (rpc supplies one; print runs headless). */
     uiContext?: ExtensionUIContext;
+    /** Optional lifecycle hook for extension-originated messages that can start an agent turn. */
+    markAgentInvokingMessage?: () => void;
+    /** Optional lifecycle hook for extension-originated sends whose success/failure determines turn ownership. */
+    trackAgentInvokingMessage?: (task: Promise<unknown>) => void;
 }
 /**
  * Initialize the session's extension runner with the standard action set

package/dist/types/modes/theme/theme.d.ts

@@ -246,6 +246,8 @@ export declare function getThemeByName(name: string): Promise<Theme | undefined>
 export declare var theme: Theme;
 /** Get the name of the currently active theme. */
 export declare function getCurrentThemeName(): string | undefined;
+/** Returns unstyled `text` before `initTheme()` assigns the global theme; use only for early-render paths. */
+export declare function fgOrPlain(color: ThemeColor, text: string, styledText?: string): string;
 export declare function initTheme(enableWatcher?: boolean, symbolPreset?: SymbolPreset, colorBlindMode?: boolean, darkTheme?: string, lightTheme?: string): Promise<void>;
 export declare function setTheme(name: string, enableWatcher?: boolean): Promise<{
     success: boolean;
@@ -289,6 +291,14 @@ export declare function setColorBlindMode(enabled: boolean): Promise<void>;
  */
 export declare function getColorBlindMode(): boolean;
 export declare function onThemeChange(callback: () => void): void;
+/**
+ * Monotonic counter bumped on any theme-affecting change that should invalidate
+ * cached renders: theme swaps and reloads (including the invalid-theme dark
+ * fallback), theme previews, symbol-preset changes, and color-blind-mode
+ * changes — everything that routes through {@link notifyThemeChange}. Consumers
+ * key cached renders on it so the next render re-shapes their output.
+ */
+export declare function getThemeEpoch(): number;
 /**
  * Get available symbol presets.
  */
@@ -304,8 +314,9 @@ export declare function stopThemeWatcher(): void;
  */
 export declare function getResolvedThemeColors(themeName?: string): Promise<Record<string, string>>;
 /**
- * Check if a theme is a "light" theme by analyzing its background color luminance.
- * Loads theme JSON synchronously (built-in or custom file) and resolves userMessageBg.
+ * Check if a theme is a "light" theme by analyzing its status-line background
+ * luminance. Loads theme JSON synchronously (built-in or custom file on disk)
+ * for callers in synchronous flows (settings migration, setup wizard).
  */
 export declare function isLightTheme(themeName?: string): boolean;
 /**

package/dist/types/modes/types.d.ts

@@ -12,7 +12,8 @@ import type { MCPManager } from "../mcp";
 import type { PlanApprovalDetails } from "../plan-mode/approved-plan";
 import type { AgentSession } from "../session/agent-session";
 import type { HistoryStorage } from "../session/history-storage";
-import type { SessionContext, SessionManager } from "../session/session-manager";
+import type { SessionContext } from "../session/session-context";
+import type { SessionManager } from "../session/session-manager";
 import type { ShakeMode } from "../session/shake-types";
 import type { LspStartupServerInfo } from "../tools";
 import type { EventBus } from "../utils/event-bus";
@@ -74,6 +75,7 @@ export interface InteractiveModeContext {
     btwContainer: Container;
     omfgContainer: Container;
     errorBannerContainer: Container;
+    modelCycleContainer: Container;
     editor: CustomEditor;
     editorContainer: Container;
     hookWidgetContainerAbove: Container;
@@ -171,6 +173,7 @@ export interface InteractiveModeContext {
     showStatus(message: string, options?: {
         dim?: boolean;
     }): void;
+    showModelCycleTrack(track: string): void;
     showError(message: string): void;
     showPinnedError(message: string): void;
     clearPinnedError(): void;
@@ -284,7 +287,9 @@ export interface InteractiveModeContext {
     showProviderSetup(): Promise<void>;
     showHookConfirm(title: string, message: string): Promise<boolean>;
     showDebugSelector(): Promise<void>;
-    showAgentHub(): void;
+    showAgentHub(options?: {
+        requireContent?: boolean;
+    }): void;
     resetObserverRegistry(): void;
     handleCtrlC(): void;
     handleCtrlD(): void;
@@ -307,6 +312,7 @@ export interface InteractiveModeContext {
     registerExtensionShortcuts(): void;
     handlePlanModeCommand(initialPrompt?: string): Promise<void>;
     handleGoalModeCommand(rest?: string): Promise<void>;
+    handleGuidedGoalCommand(rest?: string): Promise<void>;
     handleLoopCommand(args?: string): Promise<void>;
     disableLoopMode(): void;
     pauseLoop(): void;

package/dist/types/modes/utils/ui-helpers.d.ts

@@ -2,7 +2,7 @@ import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, ImageContent, Message } from "@oh-my-pi/pi-ai";
 import { type Component } from "@oh-my-pi/pi-tui";
 import type { InteractiveModeContext } from "../../modes/types";
-import type { SessionContext } from "../../session/session-manager";
+import type { SessionContext } from "../../session/session-context";
 interface RenderInitialMessagesOptions {
     preserveExistingChat?: boolean;
     clearTerminalHistory?: boolean;

package/dist/types/registry/agent-registry.d.ts

@@ -30,6 +30,8 @@ export interface AgentRef {
     sessionFile: string | null;
     createdAt: number;
     lastActivity: number;
+    /** Short gist of what the agent is currently doing (latest intent or tool), for the work-aware roster. Display-only. */
+    activity?: string;
 }
 export type RegistryEvent = {
     type: "registered";
@@ -58,6 +60,21 @@ export declare class AgentRegistry {
     static resetGlobalForTests(): void;
     register(input: RegisterInput): AgentRef;
     setStatus(id: string, status: AgentStatus): void;
+    /**
+     * Record a short activity gist for the work-aware roster. Display-only and
+     * read on demand (`irc list`, peer roster), so it emits no event — keeping
+     * the per-tool-call update rate off the registry listener path (same as
+     * `attachSession`, which also bumps `lastActivity` without emitting). Only a
+     * `running` agent has current work: a heartbeat for any other status is
+     * dropped, so a late progress flush can't resurrect activity on a ref that
+     * `setStatus` just cleared. Every running heartbeat refreshes `lastActivity`
+     * — even when the gist text is unchanged — so the roster's "active … ago" and
+     * recency sort track real work, not just the last status change.
+     * The gist is normalized to one bounded line (`oneLineLabel`) so model-derived
+     * intent text can neither break the roster nor smuggle terminal escapes —
+     * every caller is safe without sanitizing at its own call site.
+     */
+    setActivity(id: string, activity: string): void;
     attachSession(id: string, session: AgentSession, sessionFile?: string | null): void;
     detachSession(id: string): void;
     unregister(id: string): void;

package/dist/types/secrets/obfuscator.d.ts

@@ -1,5 +1,5 @@
 import type { Context, Message, Tool } from "@oh-my-pi/pi-ai";
-import type { SessionContext } from "../session/session-manager";
+import type { SessionContext } from "../session/session-context";
 export interface SecretEntry {
     type: "plain" | "regex";
     content: string;

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

@@ -46,7 +46,9 @@ import type { CheckpointState } from "../tools/checkpoint";
 import { type TodoItem, type TodoPhase } from "../tools/todo";
 import type { ClientBridge } from "./client-bridge";
 import { type CustomMessage } from "./messages";
-import type { BranchSummaryEntry, NewSessionOptions, SessionContext, SessionManager } from "./session-manager";
+import type { SessionContext } from "./session-context";
+import type { BranchSummaryEntry, NewSessionOptions } from "./session-entries";
+import type { SessionManager } from "./session-manager";
 import type { ShakeMode, ShakeResult } from "./shake-types";
 import { ToolChoiceQueue } from "./tool-choice-queue";
 import { YieldQueue } from "./yield-queue";
@@ -215,6 +217,10 @@ export interface AgentSessionConfig {
     asyncJobManager?: AsyncJobManager;
     /** Agent identity (registry id like "Main" or "Alice") used for IRC routing. */
     agentId?: string;
+    /** Whether this session is the top-level agent or a subagent. Drives eager-task
+     *  prelude gating so a top-level session created with a custom `agentId` still
+     *  receives the always-mode reminder. Defaults to "main". */
+    agentKind?: "main" | "sub";
     /**
      * Override the provider-facing session ID for all API requests from this session.
      * When absent, `sessionManager.getSessionId()` is used. Needed when benchmark or
@@ -605,12 +611,18 @@ export declare class AgentSession {
      * - Streaming: queue as steer/follow-up or store for next turn
      * - Not streaming + triggerTurn: appends to state/session, starts new turn unless the client cannot own it
      * - Not streaming + no trigger: appends to state/session, no turn
+     *
+     * @returns true iff this call synchronously started a new turn (awaited
+     * `agent.prompt`); false when the message was queued/appended without a turn
+     * — including when `triggerTurn` is downgraded because the client defers
+     * agent-initiated turns. Callers that must mirror the resulting `agent_end`
+     * use this to avoid acting on a turn that never ran.
      */
     sendCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: {
         triggerTurn?: boolean;
         deliverAs?: "steer" | "followUp" | "nextTurn";
         queueChipText?: string;
-    }): Promise<void>;
+    }): Promise<boolean>;
     /**
      * Send a user message to the agent.
      * When deliverAs is set, queue the message instead of starting a new turn.

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

@@ -30,6 +30,7 @@ export declare class IndexedSessionStorage implements SessionStorage {
     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(src: string, dst: string): Promise<void>;
     unlink(path: string): Promise<void>;
     deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
@@ -49,11 +50,9 @@ declare class IndexedSessionStorageWriter implements SessionStorageWriter {
         flags?: "a" | "w";
         onError?: (err: Error) => void;
     });
-    writeLineSync(line: string): void;
-    writeLine(line: string): Promise<void>;
+    append(line: string): Promise<void>;
     flush(): Promise<void>;
-    fsync(): Promise<void>;
-    fsyncSync(): void;
+    isOpen(): boolean;
     close(): Promise<void>;
     getError(): Error | undefined;
 }

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

@@ -0,0 +1,39 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { ServiceTier } from "@oh-my-pi/pi-ai";
+import { type CompactionEntry, type SessionEntry } from "./session-entries";
+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>;
+}
+/** Lists session model strings to try when restoring, in fallback order. */
+export declare function getRestorableSessionModels(models: Readonly<Record<string, string>>, lastModelChangeRole: string | undefined): string[];
+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;

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

@@ -0,0 +1,159 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { ImageContent, MessageAttribution, ServiceTier, TextContent } from "@oh-my-pi/pi-ai";
+export declare const CURRENT_SESSION_VERSION = 3;
+export declare const EPHEMERAL_MODEL_CHANGE_ROLE = "fallback";
+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 UsageStatistics {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    premiumRequests: number;
+    cost: number;
+}

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

@@ -0,0 +1,69 @@
+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 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[]>;
+export declare function resolveResumableSession(sessionArg: string, cwd: string, sessionDir?: string, storage?: SessionStorage): Promise<ResolvedSessionMatch | undefined>;

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

@@ -0,0 +1,16 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import { BlobStore } from "./blob-store";
+import type { FileEntry } from "./session-entries";
+import { type SessionStorage } from "./session-storage";
+/** 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[]>;