jeopi-cli 16.2.14 → 16.2.15

package/dist/types/session/snapcompact-inline.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Snapcompact inline imaging: per-request transform that swaps the system
+ * prompt, loaded context-file instructions, and/or large historical tool
+ * results for dense PNG frames on vision-capable models.
+ * Runs inside the agent loop's `transformProviderContext` hook — after the
+ * persisted history is converted to the outgoing `Context`, before the
+ * provider stream call. It only ever builds NEW message objects/arrays; the
+ * input context shares `content` array references with the persisted
+ * `SessionMessageEntry` messages, so mutation would leak rendered images
+ * into session.jsonl.
+ *
+ * The swap policy (budget, savings gate, skip rules) lives in
+ * `planInlineSwaps`, shared by the transform and the `/context` savings
+ * estimate (`estimateInlineSavings`) so the two can never disagree.
+ */
+import type { Context, Model } from "jeopi-ai";
+import * as snapcompact from "jeopi-snapcompact";
+export type SnapcompactSystemPromptMode = "none" | "agents-md" | "all";
+export interface SnapcompactInlineOptions {
+    renderSystemPrompt: SnapcompactSystemPromptMode;
+    renderToolResults: boolean;
+    /** Frame variant override; `"auto"`/omitted picks the provider's eval winner. */
+    shape?: snapcompact.ShapeVariantName | "auto";
+}
+/**
+ * Reports the per-tool-result tokens kept off the wire when a swap is applied.
+ * `savedTokens` is `textTokens - frames * shape.frameTokenEstimate` for each
+ * imaged tool result (always > 0; the savings gate guarantees it). Wired to the
+ * append-only savings journal; never throws into the request path.
+ */
+export type SnapcompactSavingsSink = (savings: ReadonlyArray<{
+    toolCallId: string;
+    savedTokens: number;
+}>, model: Model) => void;
+/** Tool-result swap candidate, in context order. */
+export interface InlineToolResultCandidate {
+    /** Stable identifier for rendering cache key and applying the swap. */
+    id: string;
+    /** Token count of the joined text blocks (0 for empty or image-carrying). */
+    textTokens: number;
+    /** Frames needed to render the text (0 = empty, below floor, image-carrying, or error). */
+    frames: number;
+    /** Already carries an image (screenshot etc.) — never re-imaged. */
+    hasImage: boolean;
+    /** Error tool results must stay text-only for provider API validation. */
+    isError?: boolean;
+}
+export interface InlineSystemPromptCandidate {
+    textTokens: number;
+    frames: number;
+}
+export interface InlinePlanInput {
+    options: SnapcompactInlineOptions;
+    shape: snapcompact.Shape;
+    /** Provider image-count budget minus images already present in the context. */
+    budget: number;
+    /** All tool results in context order, INCLUDING the most recent one. */
+    toolResults: readonly InlineToolResultCandidate[];
+    /** Selected prompt text; undefined when system-prompt imaging is off or empty. */
+    systemPrompt: InlineSystemPromptCandidate | undefined;
+    /** Whether a user message exists to carry the prompt frames. */
+    hasUserMessage: boolean;
+}
+export interface InlineSwapPlan {
+    /** Tool results to swap, oldest first. */
+    toolResults: Array<{
+        id: string;
+        textTokens: number;
+        frames: number;
+    }>;
+    /** Set when the system prompt should swap to frames (uses leftover budget). */
+    systemPrompt: InlineSystemPromptCandidate | undefined;
+}
+/**
+ * Decide which content gets swapped for frames. Pure — the same rules drive
+ * the provider-request transform and the /context savings estimate.
+ */
+export declare function planInlineSwaps(input: InlinePlanInput): InlineSwapPlan;
+/**
+ * Minimal structural view of a history message — both pi-ai `Message`s (the
+ * outgoing context) and agent-core `AgentMessage`s (the live session) satisfy
+ * it, so the estimator can read session state without conversion.
+ */
+export interface InlineMessageView {
+    role: string;
+    toolCallId?: string;
+    content?: unknown;
+    isError?: boolean;
+}
+export interface SnapcompactSavingsEstimate {
+    /** Frames only ship on models that accept image input. */
+    visionCapable: boolean;
+    /** Present iff system-prompt imaging is enabled. */
+    systemPrompt?: {
+        applied: boolean;
+        /** Why the prompt stays text when `applied` is false. */
+        reason?: "empty" | "margin" | "budget";
+        textTokens: number;
+        frames: number;
+        /** Estimated billed tokens for the frames (0 when there are none). */
+        imageTokens: number;
+        savedTokens: number;
+        scope: Exclude<SnapcompactSystemPromptMode, "none">;
+    };
+    /** Present iff tool-result imaging is enabled. */
+    toolResults?: {
+        /** Tool results currently in history. */
+        total: number;
+        swapped: number;
+        /** Text tokens of the swapped results only. */
+        textTokens: number;
+        frames: number;
+        imageTokens: number;
+        savedTokens: number;
+    };
+    /** Net estimated wire savings for the next request. */
+    savedTokens: number;
+}
+/**
+ * Estimate what `SnapcompactInlineTransformer.transform` would save on the
+ * NEXT request, given the session's live system prompt and message history.
+ *
+ * Mirrors the transform exactly via `planInlineSwaps`, with one deliberate
+ * difference: `hasUserMessage` is assumed true, because the request being
+ * estimated is always triggered by a user prompt — even when the current
+ * history is still empty.
+ */
+export declare function estimateInlineSavings(input: {
+    options: SnapcompactInlineOptions;
+    model: Model | undefined;
+    systemPrompt: readonly string[];
+    messages: readonly InlineMessageView[];
+}): SnapcompactSavingsEstimate;
+/**
+ * Stateless with respect to the model (passed per call, so mid-session model
+ * switches re-resolve shape and budget); stateful only for the render caches,
+ * which live as long as the session's Agent.
+ */
+export declare class SnapcompactInlineTransformer {
+    #private;
+    private readonly options;
+    private readonly onToolResultSavings?;
+    constructor(options: SnapcompactInlineOptions, onToolResultSavings?: SnapcompactSavingsSink | undefined);
+    transform(context: Context, model: Model): Promise<Context>;
+}

package/dist/types/session/snapcompact-savings-journal.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Append-only journal of snapcompact tool-result savings.
+ *
+ * Snapcompact frames are transient — built per provider request in
+ * `transformProviderContext` and never written to session.jsonl — so the tokens
+ * they keep off the wire would otherwise leave no trace. This records one line
+ * the FIRST time a tool result is imaged in a session:
+ *
+ *   {"ts":<epochMs>,"session":<sessionFile>,"provider":..,"model":..,"toolCallId":..,"savedTokens":..}
+ *
+ * Newline-delimited JSON, opened with O_APPEND so concurrent appenders (parallel
+ * agents/subagents) never interleave a partial line. Writes are fire-and-forget;
+ * a failure is logged at debug and never propagates into the request hot path.
+ *
+ * Readers MUST dedup by (session, toolCallId): a session resumed in a fresh
+ * process re-images the same results and may append a second line. The savings
+ * for a given (session, toolCallId) are stable, so any-per-key is correct.
+ */
+import type { Model } from "jeopi-ai";
+export interface SnapcompactSavingsRecord {
+    /** Epoch milliseconds when the swap was applied. */
+    ts: number;
+    /** Session file path (matches the stats `messages.session_file` key). */
+    session: string;
+    provider: string;
+    model: string;
+    toolCallId: string;
+    savedTokens: number;
+}
+/** `~/.jeopi/.../snapcompact-savings.jsonl`, colocated with stats.db. */
+export declare function snapcompactSavingsJournalPath(): string;
+/**
+ * Appends savings to the journal, deduped by toolCallId for the recorder's
+ * lifetime (one per session). Returns the in-flight append so callers/tests can
+ * await durability; the production transform leaves it floating (fire-and-forget,
+ * and it never rejects — I/O errors are swallowed to debug). `getSession` is read
+ * at write time so a session file assigned late is still captured; a null session
+ * (in-memory / SDK embedding) or non-positive savings skip the write.
+ */
+export type SnapcompactSavingsRecorder = (savings: ReadonlyArray<{
+    toolCallId: string;
+    savedTokens: number;
+}>, model: Model) => Promise<void>;
+export declare function createSnapcompactSavingsRecorder(getSession: () => string | null, journalPath?: string): SnapcompactSavingsRecorder;
+/** Read all journal records. Malformed lines are skipped; a missing file is empty. */
+export declare function readSnapcompactSavingsJournal(journalPath?: string): Promise<SnapcompactSavingsRecord[]>;

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

@@ -0,0 +1,72 @@
+import { IndexedSessionStorage, type SessionStorageBackend } from "./indexed-session-storage";
+/**
+ * Supported `bun:sql` adapter dialects. `Bun.SQL` reports this string on
+ * `client.options.adapter`; we detect it once at construction and pick the
+ * correct DDL / upsert / concat / byte-slice syntax for the underlying engine.
+ */
+export type SqlSessionStorageAdapter = "postgres" | "mysql" | "sqlite";
+/**
+ * Minimal subset of the `Bun.SQL` instance surface used by
+ * {@link SqlSessionStorage}. Bun's SQL client exposes a tagged-template API too,
+ * but this implementation intentionally uses `unsafe(query, values)` because
+ * the table identifier is validated and then inlined while values remain bound
+ * parameters.
+ */
+export interface SqlSessionStorageClient {
+    unsafe(query: string, values?: unknown[]): Promise<unknown[]>;
+    /**
+     * `Bun.SQL` exposes the parsed connection options here. We only consult
+     * `adapter` to pick the dialect; the field is typed as
+     * `string | undefined` so the real `Bun.SQL` instance type slots in
+     * without casting (it reports `string | undefined` across adapters).
+     */
+    options: {
+        adapter?: string;
+        [key: string]: unknown;
+    };
+    end?(): Promise<void>;
+}
+export interface SqlSessionStorageOptions {
+    /** Connected `Bun.SQL` instance (PostgreSQL, MySQL, or SQLite). */
+    client: SqlSessionStorageClient;
+    /**
+     * Override the auto-detected adapter. Useful when the client is wrapped
+     * (e.g. by a pool) and `client.options.adapter` is unreliable.
+     */
+    adapter?: SqlSessionStorageAdapter;
+    /**
+     * Table name to use. Default: `omp_session_files`. Must match
+     * `[A-Za-z_][A-Za-z0-9_]{0,62}` — inlined into prepared statements at
+     * startup, so we accept identifier-safe inputs only (no quoted/dotted
+     * names).
+     */
+    table?: string;
+    /**
+     * If true, run `CREATE TABLE IF NOT EXISTS` during `create()`.
+     * Default: true. Disable when the table is owned by an external
+     * migration.
+     */
+    createTable?: boolean;
+}
+/**
+ * SQL-backed implementation of {@link SessionStorage} using `bun:sql`. Each
+ * session JSONL file maps to a row keyed by `path`; one table stores the file
+ * contents while this process keeps only a metadata index (`size`, `mtimeMs`) in
+ * memory for synchronous `existsSync` / `statSync` / `listFilesSync` calls.
+ *
+ * Works against PostgreSQL, MySQL/MariaDB, and SQLite by selecting the
+ * dialect-correct DDL, upsert, string-concat, byte-length, and byte-slice syntax
+ * at construction.
+ */
+export declare class SqlSessionStorage extends IndexedSessionStorage {
+    #private;
+    constructor(backend: SessionStorageBackend, adapter: SqlSessionStorageAdapter, table: string);
+    /**
+     * Apply the dialect-correct DDL (unless `createTable: false` is set) and warm
+     * the metadata index with every existing row. Must be awaited before passing
+     * the storage into `SessionManager.create()`.
+     */
+    static create(options: SqlSessionStorageOptions): Promise<SqlSessionStorage>;
+    get adapter(): SqlSessionStorageAdapter;
+    get table(): string;
+}

package/dist/types/session/streaming-output.d.ts

@@ -0,0 +1,229 @@
+import type { AgentToolUpdateCallback } from "jeopi-agent-core";
+export declare const DEFAULT_MAX_LINES = 3000;
+export declare const DEFAULT_MAX_BYTES: number;
+export declare const DEFAULT_MAX_COLUMN = 512;
+/**
+ * Default artifact-on-disk cap for {@link OutputSink}.
+ *
+ * `0` means unbounded: by default, `artifact://<id>` references preserve the
+ * complete raw stream instead of a capped head/tail sample.
+ */
+export declare const ARTIFACT_DEFAULT_MAX_BYTES = 0;
+/** Default head budget; the remainder becomes the rolling tail window. */
+export declare const ARTIFACT_DEFAULT_HEAD_BYTES: number;
+export interface OutputSummary {
+    output: string;
+    truncated: boolean;
+    totalLines: number;
+    totalBytes: number;
+    outputLines: number;
+    outputBytes: number;
+    /** Bytes elided from the middle when head-retain mode is active. */
+    elidedBytes?: number;
+    /** Lines elided from the middle when head-retain mode is active. */
+    elidedLines?: number;
+    /** Bytes dropped by the per-line column cap (sum across all lines). */
+    columnDroppedBytes?: number;
+    /** Number of distinct lines that hit the per-line column cap. */
+    columnTruncatedLines?: number;
+    /** Artifact ID for internal URL access (artifact://<id>) when truncated */
+    artifactId?: string;
+}
+export interface OutputSinkOptions {
+    artifactPath?: string;
+    artifactId?: string;
+    /** Tail buffer budget (bytes). Default DEFAULT_MAX_BYTES. */
+    spillThreshold?: number;
+    /**
+     * When > 0, the sink keeps the first `headBytes` of output in addition to
+     * the rolling tail window. Output between the two windows is elided
+     * (middle elision). Default 0 = tail-only behavior.
+     */
+    headBytes?: number;
+    /**
+     * Per-line byte cap. When > 0, lines wider than `maxColumns` bytes are
+     * truncated with an ellipsis at write time; remaining bytes up to the next
+     * `\n` are dropped. Cap state persists across chunks so split-mid-line
+     * writes still respect the budget. Default 0 = no per-line cap.
+     */
+    maxColumns?: number;
+    onChunk?: (chunk: string) => void;
+    /** Minimum ms between onChunk calls. 0 = every chunk (default). */
+    chunkThrottleMs?: number;
+    /**
+     * Optional cap on bytes written to the artifact-on-disk file. When the cap
+     * is hit, the head window is preserved verbatim and subsequent output feeds
+     * a rolling tail window; on close, the sink writes a single
+     * `[ARTIFACT TRUNCATED: …]` notice between them. Default
+     * {@link ARTIFACT_DEFAULT_MAX_BYTES} (unbounded).
+     */
+    artifactMaxBytes?: number;
+    /**
+     * Bytes reserved for the head window of the capped artifact file. The
+     * tail window receives `artifactMaxBytes - artifactHeadBytes`. Default
+     * {@link ARTIFACT_DEFAULT_HEAD_BYTES}; clamped to `[0, artifactMaxBytes]`.
+     */
+    artifactHeadBytes?: number;
+}
+export interface TruncationResult {
+    content: string;
+    truncated?: boolean;
+    truncatedBy?: "lines" | "bytes" | "middle";
+    totalLines: number;
+    totalBytes: number;
+    outputLines?: number;
+    outputBytes?: number;
+    /** Bytes elided from the middle (truncateMiddle only). */
+    elidedBytes?: number;
+    /** Lines elided from the middle (truncateMiddle only). */
+    elidedLines?: number;
+    lastLinePartial?: boolean;
+    firstLineExceedsLimit?: boolean;
+}
+export interface TruncationOptions {
+    /** Maximum number of lines (default: 3000) */
+    maxLines?: number;
+    /** Maximum number of bytes (default: 50KB) */
+    maxBytes?: number;
+    /**
+     * For `truncateMiddle`: bytes reserved for the head window. The tail
+     * window receives `maxBytes - maxHeadBytes`. Default `floor(maxBytes/2)`.
+     */
+    maxHeadBytes?: number;
+    /**
+     * For `truncateMiddle`: lines reserved for the head window. The tail
+     * window receives `maxLines - maxHeadLines`. Default `floor(maxLines/2)`.
+     */
+    maxHeadLines?: number;
+}
+/** Result from byte-level truncation helpers. */
+export interface ByteTruncationResult {
+    text: string;
+    bytes: number;
+}
+export interface TailTruncationNoticeOptions {
+    fullOutputPath?: string;
+    originalContent?: string;
+    suffix?: string;
+}
+export interface HeadTruncationNoticeOptions {
+    startLine?: number;
+    totalFileLines?: number;
+}
+/**
+ * Truncate a string/buffer to fit within a byte limit, keeping the tail.
+ * Handles multi-byte UTF-8 boundaries correctly.
+ */
+export declare function truncateTailBytes(data: string | Uint8Array, maxBytes: number): ByteTruncationResult;
+/**
+ * Truncate a string/buffer to fit within a byte limit, keeping the head.
+ * Handles multi-byte UTF-8 boundaries correctly.
+ */
+export declare function truncateHeadBytes(data: string | Uint8Array, maxBytes: number): ByteTruncationResult;
+/**
+ * Truncate a single line to max characters, appending '…' if truncated.
+ */
+export declare function truncateLine(line: string, maxChars?: number): {
+    text: string;
+    wasTruncated: boolean;
+};
+/** Shared helper to build a no-truncation result. */
+export declare function noTruncResult(content: string, totalLines?: number, totalBytes?: number): TruncationResult;
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Never returns partial lines. If the first line exceeds the byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ *
+ * This implementation avoids Buffer.from(content) for the whole input.
+ * It only computes UTF-8 byteLength for candidate lines that can still fit.
+ */
+export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Truncate content from the tail (keep last N lines/bytes).
+ * May return a partial first line if the last line exceeds the byte limit.
+ *
+ * Also avoids Buffer.from(content) for the whole input.
+ */
+export declare function truncateTail(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Format the inline marker substituted for the elided middle region.
+ * Returned without surrounding newlines so callers can position it freely.
+ */
+export declare function formatMiddleElisionMarker(elidedLines: number, elidedBytes: number): string;
+/**
+ * Truncate content keeping a head window and a tail window, eliding the middle.
+ *
+ * The combined output is `<head>\n<marker>\n<tail>` when truncation is needed.
+ * `maxHeadBytes` defaults to `floor(maxBytes / 2)`; the tail receives the
+ * remainder. Falls back to `truncateTail` / `truncateHead` if either side's
+ * budget is empty or the content already fits.
+ */
+export declare function truncateMiddle(content: string, options?: TruncationOptions): TruncationResult;
+/** Options for {@link enforceInlineByteCap}. */
+export interface InlineByteCapOptions {
+    /** Inline byte budget. Defaults to {@link DEFAULT_MAX_BYTES}. */
+    maxBytes?: number;
+    /**
+     * Persist the full text as a session artifact. When an artifact id is
+     * returned, a `[raw output: artifact://<id>]` footer is appended so the
+     * elided bytes stay recoverable.
+     */
+    saveArtifact?: (full: string) => string | undefined | Promise<string | undefined>;
+}
+/**
+ * Final-defense inline size guard for tool results.
+ *
+ * No-op when `text` fits within `maxBytes` (the common path). Otherwise keeps
+ * ~60% of the budget from the head and ~25% from the tail — cut on line
+ * boundaries, never splitting a multi-byte UTF-8 sequence — with an elision
+ * marker between. The remaining ~15% is slack for the marker and the optional
+ * `[raw output: artifact://<id>]` footer, so the result stays under `maxBytes`.
+ */
+export declare function enforceInlineByteCap(text: string, options: InlineByteCapOptions): Promise<string>;
+export declare class TailBuffer {
+    #private;
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+    append(text: string): void;
+    text(): string;
+    bytes(): number;
+}
+export declare class OutputSink {
+    #private;
+    constructor(options?: OutputSinkOptions);
+    /**
+     * Push a chunk of output. The buffer management and onChunk callback run
+     * synchronously. File sink writes are deferred and serialized internally.
+     */
+    push(chunk: string): void;
+    createInput(): WritableStream<Uint8Array | string>;
+    /**
+     * Replace the in-memory buffer with the given text. Used when an upstream
+     * minimizer rewrites the captured output after the raw bytes have already
+     * been streamed.
+     *
+     * After this call the buffer is authoritative: streaming counters realign
+     * to the replacement, the retained head window is cleared, and head
+     * retention is disabled so subsequent `push()` calls append directly to the
+     * tail buffer instead of repopulating the (now meaningless) head window
+     * — which would otherwise reorder content and trip the middle-elision
+     * branch in `dump()` against stale totals.
+     */
+    replace(text: string): void;
+    dump(notice?: string): Promise<OutputSummary>;
+}
+/**
+ * Format a truncation notice for tail-truncated output (bash, python, ssh).
+ * Returns empty string if not truncated.
+ */
+export declare function formatTailTruncationNotice(truncation: TruncationResult, options?: TailTruncationNoticeOptions): string;
+/**
+ * Format a truncation notice for head-truncated output (read tool).
+ * Returns empty string if not truncated.
+ */
+export declare function formatHeadTruncationNotice(truncation: TruncationResult, options?: HeadTruncationNoticeOptions): string;
+/**
+ * Build an onChunk handler that appends to a TailBuffer and emits a streaming
+ * update (when `onUpdate` is defined) with the buffer's current text.
+ */
+export declare function streamTailUpdates<TDetails, TInput = unknown>(tailBuffer: TailBuffer, onUpdate: AgentToolUpdateCallback<TDetails, TInput> | undefined): (chunk: string) => void;

package/dist/types/session/tool-choice-queue.d.ts

@@ -0,0 +1,94 @@
+import type { ToolChoice } from "jeopi-ai";
+export interface ResolveInfo {
+    /** The ToolChoice that was served to the LLM. */
+    choice: ToolChoice;
+}
+export interface RejectInfo {
+    /** The ToolChoice that was yielded but never (or unsuccessfully) served. */
+    choice: ToolChoice;
+    reason: "aborted" | "error" | "cleared" | "removed" | "unavailable" | "not_invoked";
+}
+/** "requeue" replays the lost yield next turn; "drop" (or void/undefined) discards it. */
+export type RejectOutcome = "requeue" | "drop";
+export interface DirectiveCallbacks {
+    /** Fires when the yield completed; onInvoked directives require the requested tool to run first. */
+    onResolved?: (info: ResolveInfo) => void;
+    /**
+     * Fires when the yield is being discarded. Return "requeue" to replay the
+     * same value at the head of the queue for the next turn. Default: "drop".
+     */
+    onRejected?: (info: RejectInfo) => RejectOutcome | undefined;
+    /**
+     * Handler invoked when the model actually calls the forced tool. The queue
+     * directive carries the real execution logic; the tool's own execute() is
+     * bypassed. Returns the tool result directly.
+     */
+    onInvoked?: (input: unknown) => Promise<unknown> | unknown;
+}
+export interface ToolChoiceDirective {
+    generator: Iterator<ToolChoice>;
+    /** Stable label for targeted removal and debugging (e.g. "user-force"). */
+    label: string;
+    callbacks: DirectiveCallbacks;
+}
+export interface PushOptions {
+    /** Prepend to head instead of appending to tail. Default: false. */
+    now?: boolean;
+    label?: string;
+    /** Lifecycle callbacks for this directive. */
+    onResolved?: DirectiveCallbacks["onResolved"];
+    onRejected?: DirectiveCallbacks["onRejected"];
+    onInvoked?: DirectiveCallbacks["onInvoked"];
+}
+export declare function onceGen(choice: ToolChoice): Generator<ToolChoice, void, unknown>;
+export declare class ToolChoiceQueue {
+    #private;
+    pushOnce(choice: ToolChoice, options?: PushOptions): void;
+    pushSequence(choices: ToolChoice[], options?: PushOptions): void;
+    push(generator: Iterable<ToolChoice>, options?: PushOptions): void;
+    /**
+     * Advance the head directive and return its next yield. Records the value
+     * as in-flight until resolve() or reject() is called.
+     */
+    nextToolChoice(): ToolChoice | undefined;
+    /**
+     * The in-flight yield completed normally. Directives with onInvoked are only
+     * consumed after their requested tool ran; a normal text turn or a different
+     * tool call requeues/rejects the directive instead.
+     */
+    resolve(): void;
+    /**
+     * The in-flight yield was not served, or the turn aborted/errored.
+     * Fires onRejected to let the caller decide: "requeue" replays the exact
+     * lost value at the head of the queue; anything else drops it.
+     */
+    reject(reason: RejectInfo["reason"]): void;
+    /** True if there is an in-flight yield that hasn't been resolved or rejected. */
+    get hasInFlight(): boolean;
+    /** Return the in-flight directive's onInvoked handler and mark it when called. */
+    peekInFlightInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
+    /** Register (or replace by exact id) a non-forcing pending preview invoker. */
+    registerPendingInvoker(id: string, sourceToolName: string, onInvoked: (input: unknown) => Promise<unknown> | unknown): void;
+    /** Drop the pending invoker with this id (e.g. after it resolves). */
+    removePendingInvoker(id: string): void;
+    /** Drop every pending preview invoker without touching hard tool-choice directives. */
+    clearPendingInvokers(): void;
+    /** True when at least one non-forcing pending preview is registered. */
+    get hasPendingInvoker(): boolean;
+    /** The head (most-recently registered) pending invoker's handler, for resolve dispatch. */
+    peekPendingInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
+    /** The head pending preview's stable id + source tool, for building the agent-level
+     *  SoftToolRequirement (the id drives reminder re-injection when the head changes). */
+    peekPendingHead(): {
+        id: string;
+        sourceToolName: string;
+    } | undefined;
+    /** Remove all directives with the given label. Rejects in-flight if it matches. */
+    removeByLabel(label: string): void;
+    /** Empty the queue and reject any in-flight yield. */
+    clear(): void;
+    /** Return the label of the most recently resolved directive, then clear it. */
+    consumeLastServedLabel(): string | undefined;
+    /** For tests/debug: labels of currently queued directives in order. */
+    inspect(): readonly string[];
+}

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

@@ -0,0 +1,88 @@
+/**
+ * Helpers that share one cheap, structural identity for messages — both during
+ * incremental persistence and for the mid-run-compaction ordering check.
+ *
+ * Previously `AgentSession` carried two near-duplicate routines
+ * (`#sessionMessagesReferToSameTurn` + `#messageValueSignature`) that
+ * reconstructed the branch path on every check (O(n²) `unshift`) and
+ * `JSON.stringify`-compared the full message content on every pairwise hit.
+ * Long-running sessions with many subagents fired this thousands of times per
+ * minute and froze the TUI loop (see issue #3629). The persistence key already
+ * encodes a stable logical identity — timestamp + role-specific discriminators
+ * — so the structural compare is now the rare collision tiebreaker (e.g. two
+ * provider responses at the same millisecond with `undefined` responseId),
+ * not the load-bearing check.
+ *
+ * The helpers here keep that identity in one place and expose the planner so
+ * the persistence-ordering logic is unit-testable without standing up an
+ * `AgentSession`.
+ */
+import type { AgentMessage } from "jeopi-agent-core";
+/**
+ * Stable identity for messages that pass through {@link AgentSession}'s
+ * incremental persistence path.
+ *
+ * The discriminators chosen per role are precisely the fields that uniquely
+ * identify a single logical message instance:
+ *
+ * - `assistant` — timestamp + provider + model + responseId + stopReason
+ *   (responseId is the canonical provider-side id when available; the rest
+ *   disambiguate when it is not, e.g. local/dev models).
+ * - `toolResult` — timestamp + toolCallId + toolName (toolCallId is unique
+ *   per execution; toolName guards against synthetic reuse).
+ * - `user` / `developer` — timestamp + attribution (attribution distinguishes
+ *   user-typed vs hook-injected at the same wall-clock millisecond).
+ * - `fileMention` — timestamp.
+ *
+ * Returns `undefined` for message roles that are not persisted through this
+ * path (e.g. `hookMessage`, `custom`, `bashExecution`) — those follow other
+ * append paths in `SessionManager`.
+ */
+export declare function sessionMessagePersistenceKey(message: AgentMessage): string | undefined;
+/**
+ * Slow-path content equality check used when two messages collide on
+ * {@link sessionMessagePersistenceKey}. Only the role's content fields are
+ * compared (no timestamps, no metadata) because the key already pinned all of
+ * those down.
+ *
+ * Most calls into the persistence path never reach this — keys are unique
+ * enough in production that the snapshot lookup short-circuits at the key
+ * level. Restoring the structural compare here preserves the pre-#3629
+ * contract that two messages with the same metadata BUT different content are
+ * distinct (e.g. two assistant turns with `undefined` responseId emitted in
+ * the same wall-clock millisecond, which is exactly how the in-memory test
+ * harness crafts streamed responses).
+ */
+export declare function sameMessageContent(left: AgentMessage, right: AgentMessage): boolean;
+/**
+ * Outcome of {@link planTurnPersistence}.
+ *
+ * `ok` lists the turn-message indices that still need to be appended (in
+ * order). `out-of-order` reports the first message whose later sibling is
+ * already persisted — the caller bails so it does not silently splice a
+ * stale message between newer entries on the live branch.
+ */
+export type TurnPersistencePlan = {
+    kind: "ok";
+    toPersist: readonly number[];
+} | {
+    kind: "out-of-order";
+    messageIndex: number;
+};
+/**
+ * Decide what to do with a turn's messages relative to what's already on the
+ * branch, in a single pass over the pre-computed keys.
+ *
+ * @param turnKeys persistence keys for each turn message, in the order the
+ *   agent loop emitted them. `undefined` slots represent messages with no
+ *   persistence key (skipped silently).
+ * @param persistedKeys the snapshot of persistence keys currently on the
+ *   branch (built once per call from {@link sessionMessagePersistenceKey} for
+ *   each persisted message entry).
+ *
+ * The check is O(n²) over turn messages — but `n` here is the size of one
+ * turn (a handful of tool results), not the size of the branch. That's the
+ * point of this refactor: the expensive O(branch) work happens exactly once,
+ * inside the caller's snapshot loop, not per-comparison.
+ */
+export declare function planTurnPersistence(turnKeys: readonly (string | undefined)[], persistedKeys: ReadonlySet<string>): TurnPersistencePlan;