@oh-my-pi-zen/pi-coding-agent 16.3.6-zen.1

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

@@ -0,0 +1,65 @@
+import type { SessionStorage, SessionStorageStat, SessionStorageWriter, WriteTextAtomicOptions } from "./session-storage";
+import { type SessionTitleUpdate } from "./session-title-slot";
+export interface SessionStorageIndexEntry {
+    path: string;
+    size: number;
+    mtimeMs: number;
+    title?: string;
+    titleSource?: SessionTitleUpdate["source"];
+    titleUpdatedAt?: string;
+}
+export interface SessionStorageBackend {
+    init(): Promise<void>;
+    loadIndex(): Promise<Iterable<SessionStorageIndexEntry>>;
+    readFull(path: string): Promise<string | null>;
+    readSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
+    writeFull(path: string, content: string, mtimeMs: number, title?: SessionTitleUpdate): Promise<void>;
+    append(path: string, line: string, mtimeMs: number): Promise<void>;
+    updateSessionTitle(path: string, title: SessionTitleUpdate, mtimeMs: number): Promise<void>;
+    truncate(path: string, mtimeMs: number): Promise<void>;
+    remove(paths: string[]): Promise<void>;
+    move(src: string, dst: string, mtimeMs: number): Promise<void>;
+}
+export declare class IndexedSessionStorage implements SessionStorage {
+    #private;
+    constructor(backend: SessionStorageBackend);
+    initialize(): Promise<void>;
+    refresh(): Promise<void>;
+    drain(): Promise<void>;
+    ensureDirSync(_dir: string): void;
+    existsSync(path: string): boolean;
+    writeTextSync(path: string, content: string): void;
+    updateSessionTitle(path: string, title: 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(path: string, content: string, options?: WriteTextAtomicOptions): Promise<void>;
+    rename(src: string, dst: 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;
+    _writerClosed(writer: IndexedSessionStorageWriter): void;
+    _truncateForWriter(path: string): number;
+    _queueTruncate(path: string, mtimeMs: number, getError?: () => Error | undefined): Promise<void>;
+    _appendForWriter(path: string, line: string): number;
+    _queueAppend(path: string, line: string, mtimeMs: number, getError?: () => Error | undefined): Promise<void>;
+}
+declare class IndexedSessionStorageWriter implements SessionStorageWriter {
+    #private;
+    constructor(storage: IndexedSessionStorage, path: string, options?: {
+        flags?: "a" | "w";
+        onError?: (err: Error) => void;
+    });
+    append(line: string): Promise<void>;
+    flush(): Promise<void>;
+    isOpen(): boolean;
+    close(): Promise<void>;
+    getError(): Error | undefined;
+}
+export {};

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

@@ -0,0 +1,220 @@
+/**
+ * Custom message types and transformers for the coding agent.
+ *
+ * Extends the base AgentMessage type with coding-agent specific message types,
+ * and provides a transformer to convert them to LLM-compatible messages.
+ */
+import type { AgentMessage } from "@oh-my-pi-zen/pi-agent-core";
+import { type BranchSummaryMessage, type CompactionSummaryMessage } from "@oh-my-pi-zen/pi-agent-core/compaction/messages";
+import type { AssistantMessage, ImageContent, Message, MessageAttribution, TextContent } from "@oh-my-pi-zen/pi-ai";
+export { type BranchSummaryMessage, type CompactionSummaryMessage, createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "@oh-my-pi-zen/pi-agent-core/compaction/messages";
+import type { OutputMeta } from "../tools/output-meta";
+export declare const SKILL_PROMPT_MESSAGE_TYPE = "skill-prompt";
+export declare const LSP_LATE_DIAGNOSTIC_MESSAGE_TYPE = "lsp-late-diagnostic";
+export declare const BACKGROUND_TAN_DISPATCH_MESSAGE_TYPE = "background-tan-dispatch";
+/** Custom message type for hidden interrupted-thinking continuity context. */
+export declare const INTERRUPTED_THINKING_MESSAGE_TYPE = "interrupted-thinking";
+/** Metadata persisted with a hidden interrupted-thinking continuity message. */
+export interface InterruptedThinkingDetails {
+    interruptedAt: number;
+    provider: AssistantMessage["provider"];
+    model: string;
+    blockCount: number;
+}
+/** Pure helper result for persisting interrupted thinking outside the assistant turn. */
+export interface DemotedInterruptedThinking {
+    reasoning: string;
+    strippedContent: AssistantMessage["content"];
+    blockCount: number;
+}
+/**
+ * Demote a trailing run of *incomplete* interrupted-thinking from an assistant
+ * message — reasoning that was still streaming when the user aborted.
+ *
+ * A block joins the run only when it is a non-empty `thinking` block with no
+ * `thinkingSignature`. A signed/complete thinking block (Anthropic signature,
+ * OpenAI reasoning item id) is safely replayable, so it ends the run and stays
+ * in place — as do `redactedThinking` encrypted blobs, text, tool calls,
+ * empty-thinking blocks, and trailing empty text placeholders.
+ */
+export declare function demoteInterruptedThinking(message: Pick<AssistantMessage, "content">): DemotedInterruptedThinking | undefined;
+/** Details persisted on a `/tan` background-dispatch breadcrumb. */
+export interface BackgroundTanDispatchDetails {
+    jobId: string;
+    work: string;
+    /** Forked clone session file, named `<agentId>.jsonl`; the Agent Hub reads its transcript. */
+    sessionFile: string;
+}
+export interface SkillPromptDetails {
+    name: string;
+    path: string;
+    args?: string;
+    lineCount: number;
+    /** 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)
+ *  and must NOT surface as a red "Operation aborted" line. Distinct from
+ *  `undefined` (default) so user-cancel aborts with no errorMessage still
+ *  render normally. Persists through SessionManager so history replay
+ *  branches identically.
+ *
+ *  Consumers: `AgentSession.#handleAgentEvent` (stamper) writes this value;
+ *  `EventController.#handleMessageEnd`, `AssistantMessageComponent`,
+ *  `ui-helpers.addMessageToChat` (renderers), `AgentHubOverlayComponent
+ *  #buildTranscriptLines`, `runPrintMode`, and `AcpAgent#replayAssistantMessage`
+ *  (fallback error emission) read it via `isSilentAbort`. */
+export declare const SILENT_ABORT_MARKER = "__omp.silent_abort__";
+/** Type-guard for silent aborts. Renderers MUST call this helper so structured
+ *  `errorId` and legacy persisted marker messages stay in lockstep. */
+export declare function isSilentAbort(message: Pick<AssistantMessage, "errorId" | "errorMessage">): boolean;
+/** Reason threaded through `AbortController.abort(reason)` when the user aborts
+ *  the turn with Esc (see `AgentSession.abort`). The agent keeps it on the
+ *  aborted assistant message's `errorMessage` so queued follow-ups/tool-result
+ *  placeholders can distinguish a deliberate interrupt from a bare lifecycle
+ *  abort, but interactive renderers suppress this redundant transcript line. */
+export declare const USER_INTERRUPT_LABEL = "Interrupted by user";
+export declare function isUserInterruptAbort(message: Pick<AssistantMessage, "errorId" | "errorMessage">): boolean;
+export declare function shouldRenderAbortReason(message: Pick<AssistantMessage, "errorId" | "errorMessage">): boolean;
+/** Sentinel `errorMessage` the agent stamps on any abort that carried no custom
+ *  reason (bare `abort()`). Renderers treat it as "no specific reason given". */
+export declare const GENERIC_ABORT_SENTINEL = "Request was aborted";
+/** Resolve the operator-facing label for an aborted assistant turn. A custom
+ *  abort reason threaded onto `errorMessage` is returned verbatim; aborts with
+ *  no threaded reason fall back to the retry-aware generic label. Call
+ *  `shouldRenderAbortReason` before rendering when user interrupts should stay
+ *  visually quiet. */
+export declare function resolveAbortLabel(message: Pick<AssistantMessage, "errorId" | "errorMessage">, retryAttempt?: number): string;
+/** 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 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 ["__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
+ *  clone cost on the common path. */
+export declare function stripInternalDetailsFields<T>(details: T | undefined): T | undefined;
+export declare function wrapSteeringForModel(messages: AgentMessage[]): AgentMessage[];
+/**
+ * Strip image content blocks from `message` in place. Returns the count of
+ * images removed across `content` (every role that carries `ImageContent`) and
+ * any tool-result `details.images` payload. Callers MUST rewrite session
+ * entries (`SessionManager.rewriteEntries`) and replay them through
+ * `Agent.replaceMessages` afterwards so persisted state and provider-side
+ * caches stay aligned with the mutated tree — `stripImagesFromMessage` is a
+ * pure local mutation and intentionally does neither.
+ */
+export declare function stripImagesFromMessage(message: AgentMessage): number;
+/**
+ * Message type for bash executions via the ! command.
+ */
+export interface BashExecutionMessage {
+    role: "bashExecution";
+    command: string;
+    output: string;
+    exitCode: number | undefined;
+    cancelled: boolean;
+    truncated: boolean;
+    meta?: OutputMeta;
+    timestamp: number;
+    /** If true, this message is excluded from LLM context (!! prefix) */
+    excludeFromContext?: boolean;
+}
+/**
+ * Message type for user-initiated Python executions via the $ command.
+ * Shares the same kernel session as eval's Python backend.
+ */
+export interface PythonExecutionMessage {
+    role: "pythonExecution";
+    code: string;
+    output: string;
+    exitCode: number | undefined;
+    cancelled: boolean;
+    truncated: boolean;
+    meta?: OutputMeta;
+    timestamp: number;
+    /** If true, this message is excluded from LLM context ($$ prefix) */
+    excludeFromContext?: boolean;
+}
+/**
+ * Message type for extension-injected messages via sendMessage().
+ */
+export interface CustomMessage<T = unknown> {
+    role: "custom";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    display: boolean;
+    details?: T;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    timestamp: number;
+}
+/**
+ * Legacy hook message type (pre-extensions). Kept for session migration.
+ */
+export interface HookMessage<T = unknown> {
+    role: "hookMessage";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    display: boolean;
+    details?: T;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    timestamp: number;
+}
+/**
+ * Message type for auto-read file mentions via @filepath syntax.
+ */
+export interface FileMentionMessage {
+    role: "fileMention";
+    files: Array<{
+        path: string;
+        content: string;
+        lineCount?: number;
+        /** File size in bytes, if known. */
+        byteSize?: number;
+        /** Why the file contents were omitted from auto-read. */
+        skippedReason?: "tooLarge" | "binary";
+        image?: ImageContent;
+    }>;
+    timestamp: number;
+}
+declare module "@oh-my-pi-zen/pi-agent-core" {
+    interface CustomAgentMessages {
+        bashExecution: BashExecutionMessage;
+        pythonExecution: PythonExecutionMessage;
+        custom: CustomMessage;
+        hookMessage: HookMessage;
+        branchSummary: BranchSummaryMessage;
+        compactionSummary: CompactionSummaryMessage;
+        fileMention: FileMentionMessage;
+    }
+}
+/**
+ * Convert a BashExecutionMessage to user message text for LLM context.
+ */
+export declare function bashExecutionToText(msg: BashExecutionMessage): string;
+/**
+ * Convert a PythonExecutionMessage to user message text for LLM context.
+ */
+export declare function pythonExecutionToText(msg: PythonExecutionMessage): string;
+export declare function sanitizeRehydratedOpenAIResponsesAssistantMessage(message: AssistantMessage): AssistantMessage;
+/**
+ * Transform AgentMessages (including custom types) to LLM-compatible Messages.
+ *
+ * This is used by:
+ * - Agent's transormToLlm option (for prompt calls and queued messages)
+ * - Compaction's generateSummary (for summarization)
+ * - Custom extensions and tools
+ */
+export declare function convertToLlm(messages: AgentMessage[]): Message[];

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

@@ -0,0 +1 @@
+export {};

package/dist/types/session/provider-image-budget.d.ts

@@ -0,0 +1,3 @@
+import type { Context, Model } from "@oh-my-pi-zen/pi-ai";
+/** Drops oldest transient image blocks so outgoing vision requests fit the active provider's image cap. */
+export declare function clampProviderContextImages(context: Context, model: Model): Context;

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

@@ -0,0 +1,51 @@
+import { IndexedSessionStorage } from "./indexed-session-storage";
+/**
+ * Minimal subset of the `bun:redis` `RedisClient` surface used by
+ * {@link RedisSessionStorage}. Keeping the contract narrow (and accepting any
+ * client that conforms) lets callers swap in test doubles or shared clients
+ * without dragging the entire Bun typings into this module.
+ */
+export interface RedisSessionStorageClient {
+    get(key: string): Promise<string | null>;
+    getrange(key: string, start: number, end: number): Promise<string>;
+    strlen(key: string): Promise<number>;
+    set(key: string, value: string): Promise<unknown>;
+    append(key: string, value: string): Promise<number>;
+    del(...keys: string[]): Promise<number>;
+    rename(src: string, dst: string): Promise<unknown>;
+    scan(cursor: string, ...args: string[]): Promise<[string, string[]]>;
+    hset(key: string, field: string, value: string): Promise<unknown>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    hdel(key: string, ...fields: string[]): Promise<unknown>;
+}
+export interface RedisSessionStorageOptions {
+    /** A connected `bun:redis` RedisClient (or any compatible adapter). */
+    client: RedisSessionStorageClient;
+    /**
+     * Key prefix applied to every Redis key this storage owns. Default `omp:sessions:`.
+     * Trailing colon is preserved verbatim — set to a project-scoped prefix to share
+     * one Redis instance between multiple agents.
+     */
+    prefix?: string;
+    /**
+     * Maximum number of keys returned per SCAN batch when warming the metadata index.
+     * Default 500.
+     */
+    scanCount?: number;
+}
+/**
+ * Redis-backed implementation of {@link SessionStorage}. Each session JSONL
+ * file maps to a Redis STRING key, with per-key metadata (mtime) tracked in a
+ * single sibling HASH. This process keeps only a metadata index (`size`,
+ * `mtimeMs`) in memory so synchronous `existsSync` / `statSync` /
+ * `listFilesSync` calls remain available without mirroring full content.
+ */
+export declare class RedisSessionStorage extends IndexedSessionStorage {
+    /**
+     * Warm the metadata index with every existing session key under the configured
+     * prefix and return the ready-to-use storage. Must be awaited before passing
+     * the storage into `SessionManager.create()` so synchronous lookups (session
+     * resume, recent sessions, EPERM-backup recovery) see the existing keyspace.
+     */
+    static create(options: RedisSessionStorageOptions): Promise<RedisSessionStorage>;
+}

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

@@ -0,0 +1,44 @@
+import type { AgentMessage } from "@oh-my-pi-zen/pi-agent-core";
+import { type ServiceTierByFamily } from "@oh-my-pi-zen/pi-ai";
+import { type CompactionEntry, type SessionEntry } from "./session-entries";
+export interface SessionContext {
+    messages: AgentMessage[];
+    thinkingLevel?: string;
+    /** Configured thinking selector (`"auto"` or a concrete level) from the latest change. */
+    configuredThinkingLevel?: string;
+    serviceTier?: ServiceTierByFamily;
+    /** 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>;
+    /**
+     * Array parallel to messages, indicating which assistant turns should
+     * have their prompt-cache misses suppressed/explained (because a model,
+     * compaction, or plan-mode transition directly preceded them).
+     * Only populated in transcript mode.
+     */
+    cacheMissExplainedAt?: boolean[];
+}
+/** 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 display transcript instead of the LLM context. By default this
+     * preserves every path entry with compactions inline; set
+     * `collapseCompactedHistory` for the live TUI surface to render only the
+     * latest compacted tail.
+     */
+    transcript?: boolean;
+    /** In transcript mode, elide entries replaced by the latest compaction. */
+    collapseCompactedHistory?: boolean;
+}
+export declare function buildSessionContext(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>, options?: BuildSessionContextOptions): SessionContext;

package/dist/types/session/session-dump-format.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Plain-text / markdown session formatting for `/dump` and `/advisor dump raw`.
+ *
+ * Renders a prelude (system prompt, model/thinking config, tool inventory)
+ * followed by the message history as per-message markdown headings: `## User`,
+ * `## Assistant` (with `<thinking>` blocks and `### Tool Call: <name>` + YAML
+ * args), `### Tool Result: <name>`, and the execution/summary sections.
+ */
+import type { AgentMessage, ThinkingLevel } from "@oh-my-pi-zen/pi-agent-core";
+import type { Model, ToolExample } from "@oh-my-pi-zen/pi-ai";
+/** Minimal tool shape for dump output (matches AgentTool fields used by formatSessionDumpText). */
+export interface SessionDumpToolInfo {
+    name: string;
+    description: string;
+    parameters: unknown;
+    examples?: readonly ToolExample[];
+}
+export interface FormatSessionDumpTextOptions {
+    messages: readonly AgentMessage[];
+    systemPrompt?: readonly string[] | null;
+    model?: Model | null;
+    thinkingLevel?: ThinkingLevel | string | null;
+    tools?: readonly SessionDumpToolInfo[];
+    inlineToolDescriptors?: boolean;
+}
+/**
+ * Format messages and session metadata as markdown/plain text (same as
+ * AgentSession.formatSessionAsText / /dump).
+ */
+export declare function formatSessionDumpText(options: FormatSessionDumpTextOptions): string;

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

@@ -0,0 +1,197 @@
+import type { AgentMessage } from "@oh-my-pi-zen/pi-agent-core";
+import type { ImageContent, MessageAttribution, ServiceTierByFamily, TextContent } from "@oh-my-pi-zen/pi-ai";
+export declare const CURRENT_SESSION_VERSION = 3;
+export declare const SESSION_TITLE_SLOT_BYTES = 256;
+export declare const SESSION_TITLE_SLOT_ENTRY_TYPE = "title";
+export declare const TITLE_CHANGE_ENTRY_TYPE = "title_change";
+export type SessionTitleSource = "auto" | "user";
+/** Fixed-width first-line slot carrying the mutable current session title. */
+export interface SessionTitleSlotEntry {
+    type: typeof SESSION_TITLE_SLOT_ENTRY_TYPE;
+    v: 1;
+    title: string;
+    source?: SessionTitleSource;
+    updatedAt: string;
+    pad: string;
+}
+export declare const EPHEMERAL_MODEL_CHANGE_ROLE = "fallback";
+export interface SessionHeader {
+    type: "session";
+    version?: number;
+    id: string;
+    title?: string;
+    titleSource?: SessionTitleSource;
+    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;
+    /**
+     * The user-configured selector at the time of this change: `"auto"` when auto
+     * mode was active, otherwise the concrete level. Absent on entries written
+     * before auto-mode persistence existed; readers fall back to `thinkingLevel`.
+     */
+    configured?: 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: ServiceTierByFamily | 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;
+}
+/** Append-only audit entry recording a session title change. */
+export interface TitleChangeEntry extends SessionEntryBase {
+    type: typeof TITLE_CHANGE_ENTRY_TYPE;
+    title: string;
+    previousTitle?: string;
+    source: SessionTitleSource;
+    trigger?: string;
+}
+declare module "@oh-my-pi-zen/pi-agent-core/compaction/entries" {
+    interface CustomCompactionSessionEntries {
+        titleChange: TitleChangeEntry;
+    }
+}
+/** 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;
+    /** Spawn allowlist the subagent ran with ("" = none, "*" = any, else CSV); absent on pre-spawns files. */
+    spawns?: string;
+    /** The agent's `readSummarize` setting (`false` = read summarization disabled); absent uses the session default. */
+    readSummarize?: boolean;
+}
+/** 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 | TitleChangeEntry | TtsrInjectionEntry | MCPToolSelectionEntry | SessionInitEntry | ModeChangeEntry;
+/** Raw logical file entry after loaders strip any fixed-width title slot. */
+export type FileEntry = SessionHeader | SessionEntry;
+/** Physical JSONL entry before slot-aware loaders fold the title slot. */
+export type RawFileEntry = SessionTitleSlotEntry | FileEntry;
+/** 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-history-format.d.ts

@@ -0,0 +1,49 @@
+export interface HistoryFormatOptions {
+    /** Optional H1 prepended to the transcript. */
+    title?: string;
+    /** Render assistant thinking blocks (default: elided). */
+    includeThinking?: boolean;
+    /** Render tool intent comment before tool call lines. */
+    includeToolIntent?: boolean;
+    /** Render watched-session roles as inline `**agent**:` / `**user**:` labels (collapsing consecutive same-role messages) instead of `## ` headings, so a primary transcript embedded inside an advisor turn stays visually distinct. */
+    watchedRoles?: boolean;
+    /**
+     * Expand the primary agent's injected constraint context — plan mode's rules
+     * (`plan-mode-context`) and the approved plan it implements
+     * (`plan-mode-reference`) — verbatim instead of as a truncated one-liner,
+     * wrapped in a `<primary-context>` tag so a reviewer reads it as the primary's
+     * instructions, not its own. The advisor sets this: a truncated rule (plan
+     * mode's "NEVER create files … except the plan file") makes it raise false
+     * blockers. See {@link PRIMARY_CONTEXT_CUSTOM_TYPES}. Other custom messages
+     * still collapse to a one-liner.
+     */
+    expandPrimaryContext?: boolean;
+    /**
+     * Append the full unified diff (from a tool result's `details.diff`) below
+     * edit/apply_patch tool lines, instead of just the path. The advisor sets
+     * this so it sees what changed without re-reading the file.
+     */
+    expandEditDiffs?: boolean;
+}
+/**
+ * Hidden custom messages that inject the primary agent's operative *constraints*
+ * — plan mode's rules and the approved plan it implements. A reviewer (the
+ * advisor) must read these verbatim; truncating them hides load-bearing
+ * exceptions (e.g. plan mode permits exactly one plan file). Every other custom
+ * type stays a one-liner.
+ *
+ * Deliberately excludes `goal-mode-context`: its body carries live budget
+ * counters (tokens/seconds used) that change every turn, so it can neither be
+ * deduped against a prior copy nor expanded each turn without flooding the
+ * reviewer — and its constraints don't drive the file-write misreads this
+ * targets.
+ */
+export declare const PRIMARY_CONTEXT_CUSTOM_TYPES: ReadonlySet<string>;
+/**
+ * Format a session's message array as a concise markdown transcript.
+ *
+ * `messages` is the session's in-memory message array (or the read-only
+ * equivalent loaded from a session file) — the same shapes
+ * `session-dump-format.ts` consumes.
+ */
+export declare function formatSessionHistoryMarkdown(messages: unknown[], opts?: HistoryFormatOptions): string;