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

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
@@ -357,16 +363,6 @@ export declare class AgentSession {
     /** Unconditionally clear the silent-abort flag. Idempotent: safe when the
      *  flag was never set OR was already consumed by `#handleAgentEvent`. */
     clearPlanCompactAbortPending(): void;
-    /** Register a compact display string for a custom message that the caller is
-     *  about to dispatch via `promptCustomMessage` / `sendCustomMessage`.
-     *  Returns a stable tag the caller MUST embed in
-     *  `CustomMessage.details.__pendingDisplayTag` so the agent-side
-     *  `message_start` handler can remove the matching display entry when the
-     *  queued message is consumed.
-     *
-     *  Does NOT push to the agent's steering/followUp queue — that happens
-     *  separately inside `sendCustomMessage`. */
-    enqueueCustomMessageDisplay(text: string, mode: "steer" | "followUp"): string;
     getAsyncJobSnapshot(options?: {
         recentLimit?: number;
     }): AsyncJobSnapshot | null;
@@ -421,6 +417,7 @@ export declare class AgentSession {
     get serviceTier(): ServiceTier | undefined;
     /** Whether agent is currently streaming a response */
     get isStreaming(): boolean;
+    get isAborting(): boolean;
     /** Wait until streaming and deferred recovery work are fully settled. */
     waitForIdle(): Promise<void>;
     drainAsyncJobDeliveriesForAcp(options?: {
@@ -595,7 +592,9 @@ export declare class AgentSession {
      * the ACP agent) use this to know whether to expect an `agent_end` event.
      */
     prompt(text: string, options?: PromptOptions): Promise<boolean>;
-    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice">): Promise<void>;
+    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice"> & {
+        queueChipText?: string;
+    }): Promise<void>;
     /**
      * Queue a steering message to interrupt the agent mid-run.
      */
@@ -612,11 +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";
-    }): Promise<void>;
+        queueChipText?: string;
+    }): Promise<boolean>;
     /**
      * Send a user message to the agent.
      * When deliverAs is set, queue the message instead of starting a new turn.
@@ -627,22 +633,13 @@ export declare class AgentSession {
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
     }): Promise<void>;
-    /**
-     * Clear queued messages and return them (text plus any attached images).
-     * Useful for restoring to editor when user aborts. The internal entry
-     * arrays are handed out as-is — a `tag` (if any) is inert once the record
-     * leaves the queue.
-     */
+    /** Clear queued messages and return them (text plus any attached images). */
     clearQueue(): {
         steering: RestoredQueuedMessage[];
         followUp: RestoredQueuedMessage[];
     };
-    /** Number of pending messages (includes steering, follow-up, and next-turn messages) */
+    /** Number of pending displayable messages (includes steering, follow-up, and next-turn messages) */
     get queuedMessageCount(): number;
-    /** Get pending messages (read-only). Returns the public text-only view;
-     *  internal `{text, tag?}` records are mapped to `.text` so callers
-     *  (`updatePendingMessagesDisplay`, `restoreQueuedMessagesToEditor`) see
-     *  the unchanged historical shape. */
     getQueuedMessages(): {
         steering: readonly string[];
         followUp: readonly string[];
@@ -650,8 +647,6 @@ export declare class AgentSession {
     /**
      * Pop the last queued message (steering first, then follow-up).
      * Used by dequeue keybinding to restore messages to editor one at a time.
-     * Returns the popped entry's text and images; the tag (if any) dies with
-     * the record — no orphan state can outlive the queue entry.
      */
     popLastQueuedMessage(): RestoredQueuedMessage | undefined;
     get skillsSettings(): SkillsSettings | undefined;
@@ -673,13 +668,6 @@ export declare class AgentSession {
         goalReason?: "interrupted" | "internal";
         reason?: string;
     }): Promise<void>;
-    /**
-     * Abort active work, then immediately resume the agent so queued steer/follow-up
-     * messages drain instead of waiting for another natural turn boundary.
-     */
-    interruptAndFlushQueuedMessages(options?: {
-        reason?: string;
-    }): Promise<void>;
     /**
      * Start a new session, optionally with initial messages and parent tracking.
      * Clears all messages and starts a new session.
@@ -701,7 +689,10 @@ export declare class AgentSession {
     fork(): Promise<boolean>;
     /**
      * Set model directly.
-     * Validates API key and saves to the active session. Persists settings only when requested.
+     * Validates that a credential source is configured (synchronously, without
+     * refreshing OAuth or running command-backed key programs) and saves to the
+     * active session. Persists settings only when requested. The concrete key is
+     * resolved lazily per request, so switching never blocks the event loop.
      * @throws Error if no API key available for the model
      */
     setModel(model: Model, role?: string, options?: {
@@ -711,7 +702,9 @@ export declare class AgentSession {
     }): Promise<void>;
     /**
      * Set model temporarily (for this session only).
-     * Validates API key, saves to session log but NOT to settings.
+     * Validates that a credential source is configured (synchronously, without
+     * refreshing OAuth or running command-backed key programs), saves to session
+     * log but NOT to settings.
      * @throws Error if no API key available for the model
      */
     setModelTemporary(model: Model, thinkingLevel?: ThinkingLevel, options?: {

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

@@ -10,7 +10,8 @@ export declare class AgentStorage {
     private constructor();
     /**
      * Returns singleton instance for the given database path, creating if needed.
-     * Retries on SQLITE_BUSY with exponential backoff.
+     * Retries on the `SQLITE_BUSY` family (including `SQLITE_BUSY_RECOVERY`) with
+     * exponential backoff. See issue #2421.
      * @param dbPath - Path to the SQLite database file (defaults to config path)
      * @returns AgentStorage instance for the given path
      */

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,10 +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>;
+    isOpen(): boolean;
     close(): Promise<void>;
     getError(): Error | undefined;
 }

package/dist/types/session/messages.d.ts

@@ -16,13 +16,11 @@ export interface SkillPromptDetails {
     path: string;
     args?: string;
     lineCount: number;
-    /** Internal: tag used by AgentSession to remove the pending-display chip
-     *  from `#steeringMessages` / `#followUpMessages` when the agent consumes
-     *  this message. Not surfaced to renderers; the `__` prefix signals
-     *  "private". Optional — non-streaming skill prompts never set it. Stripped
-     *  from persisted `details` by `SessionManager.appendCustomMessageEntry`
-     *  via the `INTERNAL_DETAILS_FIELDS` allowlist below. */
-    __pendingDisplayTag?: string;
+    /** Internal: compact label shown for a queued custom message. Optional —
+     *  non-streaming skill prompts never set it. Stripped from persisted
+     *  `details` by `SessionManager.appendCustomMessageEntry` via the
+     *  `INTERNAL_DETAILS_FIELDS` allowlist below. */
+    __queueChipText?: string;
 }
 /** Sentinel value for `AssistantMessage.errorMessage` indicating that the abort
  *  was an *expected internal transition* (plan-mode → execution compaction)
@@ -55,16 +53,16 @@ export declare function shouldRenderAbortReason(errorMessage: string | undefined
  *  `shouldRenderAbortReason` before rendering when user interrupts should stay
  *  visually quiet. */
 export declare function resolveAbortLabel(errorMessage: string | undefined, retryAttempt?: number): string;
-/** Extract the optional `__pendingDisplayTag` field from a CustomMessage's
+/** Extract the optional `__queueChipText` field from a CustomMessage's
  *  `details` blob. Safe over `unknown`; returns undefined when the field is
  *  absent or non-string. */
-export declare function readPendingDisplayTag(details: unknown): string | undefined;
+export declare function readQueueChipText(details: unknown): string | undefined;
 /** Explicit allowlist of `details` field names that are AgentSession-internal
  *  transient bookkeeping and MUST be removed before SessionManager persists
  *  the CustomMessageEntry to disk. Scoped intentionally narrow: only fields
  *  declared here are stripped. Adding a new entry is a deliberate, reviewed
  *  change — unrelated future payload fields are never silently dropped. */
-export declare const INTERNAL_DETAILS_FIELDS: readonly ["__pendingDisplayTag"];
+export declare const INTERNAL_DETAILS_FIELDS: readonly ["__queueChipText"];
 /** Return a `details` copy with every key in `INTERNAL_DETAILS_FIELDS`
  *  removed. Returns the input unchanged when there is nothing to strip
  *  (null/non-object, or no listed fields present) so callers don't pay a

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[]>;