jeopi-cli 16.2.14 → 16.2.15

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

@@ -0,0 +1,97 @@
+import { type AuthCredential, type AuthCredentialStore, type StoredAuthCredential } from "jeopi-ai";
+import type { RawSettings as Settings } from "../config/settings";
+/**
+ * Unified SQLite storage for agent settings, model usage, and auth credentials.
+ * Delegates auth credential operations to AuthCredentialStore from jeopi-ai.
+ * Uses singleton pattern per database path; access via AgentStorage.open().
+ */
+export declare class AgentStorage {
+    #private;
+    private constructor();
+    /**
+     * Returns singleton instance for the given database path, creating if needed.
+     * 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
+     */
+    static open(dbPath?: string): Promise<AgentStorage>;
+    /** @internal Reset all singletons and close their databases — test-only. */
+    static resetInstance(): void;
+    /**
+     * Reads legacy settings persisted in the agent.db `settings` table.
+     * The canonical settings store is `config.yml`; this accessor only
+     * exists so the config loader can migrate values from older installs.
+     * @returns Settings object, or null if no settings are stored
+     */
+    getSettings(): Settings | null;
+    /**
+     * Records model usage, updating the last-used timestamp.
+     * @param modelKey - Model key in "provider/modelId" format
+     */
+    recordModelUsage(modelKey: string): void;
+    /**
+     * Gets model keys ordered by most recently used.
+     * Results are cached until recordModelUsage is called.
+     * @returns Array of model keys ("provider/modelId") in MRU order
+     */
+    getModelUsageOrder(): string[];
+    /**
+     * Checks if any auth credentials exist in storage.
+     * @returns True if at least one credential is stored
+     */
+    hasAuthCredentials(): boolean;
+    /**
+     * Returns the underlying {@link AuthCredentialStore} so callers that need
+     * the lower-level pi-ai abstraction (e.g. `findAnthropicAuth(store)`) can
+     * reuse this storage's open database connection instead of opening their
+     * own.
+     */
+    get authStore(): AuthCredentialStore;
+    /**
+     * Lists auth credentials, optionally filtered by provider.
+     * Only returns active (non-disabled) credentials by default.
+     * @param provider - Optional provider name to filter by
+     * @param includeDisabled - If true, includes disabled credentials
+     * @returns Array of stored credentials with their database IDs
+     */
+    listAuthCredentials(provider?: string, includeDisabled?: boolean): StoredAuthCredential[];
+    /**
+     * Atomically replaces all credentials for a provider.
+     * Useful for OAuth token refresh where old tokens should be discarded.
+     * @param provider - Provider name (e.g., "anthropic", "openai")
+     * @param credentials - New credentials to store
+     * @returns Array of newly stored credentials with their database IDs
+     */
+    replaceAuthCredentialsForProvider(provider: string, credentials: AuthCredential[]): StoredAuthCredential[];
+    /**
+     * Updates an existing auth credential by ID.
+     * @param id - Database row ID of the credential to update
+     * @param credential - New credential data
+     */
+    updateAuthCredential(id: number, credential: AuthCredential): void;
+    /**
+     * Disables an auth credential by ID with a persisted cause.
+     * @param id - Database row ID of the credential to disable
+     * @param disabledCause - Human-readable cause stored with the disabled row
+     */
+    deleteAuthCredential(id: number, disabledCause: string): void;
+    /**
+     * Disables all auth credentials for a provider with a persisted cause.
+     * @param provider - Provider name whose credentials should be disabled
+     * @param disabledCause - Human-readable cause stored with the disabled rows
+     */
+    deleteAuthCredentialsForProvider(provider: string, disabledCause: string): void;
+    /**
+     * Gets a cached value by key. Returns null if not found or expired.
+     */
+    getCache(key: string): string | null;
+    /**
+     * Sets a cached value with expiry time (unix seconds).
+     */
+    setCache(key: string, value: string, expiresAtSec: number): void;
+    /**
+     * Deletes expired cache entries. Call periodically for cleanup.
+     */
+    cleanExpiredCache(): void;
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Manages artifact storage for a session.
+ *
+ * Artifacts are stored with sequential IDs in the session's artifact directory.
+ * The directory is created lazily on first write.
+ *
+ * Subagents do not own their own `ArtifactManager`. The parent's instance is
+ * adopted via `SessionManager.adoptArtifactManager`, so the whole parent +
+ * subagent tree shares one ID space and one directory.
+ */
+export declare class ArtifactManager {
+    #private;
+    /**
+     * @param dir Directory that will hold artifact files. Created lazily on first save.
+     */
+    constructor(dir: string);
+    /**
+     * Artifact directory path.
+     * Directory may not exist until first artifact is saved.
+     */
+    get dir(): string;
+    /**
+     * Atomically allocate next artifact ID.
+     * IDs are sequential within the session.
+     */
+    allocateId(): number;
+    /**
+     * Allocate a new artifact path and ID without writing content.
+     *
+     * @param toolType Tool name for file extension (e.g., "bash", "read")
+     */
+    allocatePath(toolType: string): Promise<{
+        id: string;
+        path: string;
+    }>;
+    /**
+     * Save content as an artifact and return the artifact ID.
+     *
+     * @param content Full content to save
+     * @param toolType Tool name for file extension (e.g., "bash", "read")
+     * @returns Artifact ID (numeric string)
+     */
+    save(content: string, toolType: string): Promise<string>;
+    /**
+     * Check if an artifact exists.
+     * @param id Artifact ID (numeric string)
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * List all artifact files in the directory.
+     * Returns empty array if directory doesn't exist.
+     */
+    listFiles(): Promise<string[]>;
+    /**
+     * Get the full path to an artifact file.
+     * Returns null if artifact doesn't exist.
+     *
+     * @param id Artifact ID (numeric string)
+     */
+    getPath(id: string): Promise<string | null>;
+}

package/dist/types/session/auth-broker-config.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Resolve auth-broker connection configuration for the local jeopi client.
+ *
+ * This is a thin coding-agent wrapper around the shared resolver in
+ * `jeopi-ai/auth-broker/discover` that preserves the process-lifetime
+ * memoization expected by the CLI and injects the full `resolveConfigValue`
+ * (including `!command` config indirection) from coding-agent's config layer.
+ *
+ * Precedence (highest first):
+ *   1. `JEOPI_AUTH_BROKER_URL` / `JEOPI_AUTH_BROKER_TOKEN` env vars.
+ *   2. `auth.broker.url` / `auth.broker.token` in `~/.jeopi/agent/config.yml`
+ *      (hidden from the settings UI; `!command` resolution supported).
+ *   3. Token file `~/.jeopi/auth-broker.token` (paired with URL from env or config).
+ *
+ * Returns null when no broker URL is configured — caller falls back to the
+ * local SQLite store.
+ *
+ * Reads config.yml directly (instead of going through `Settings.init`) because
+ * `discoverAuthStorage` runs before the settings singleton is initialized in
+ * `runRootCommand`, and we want hand-edited config entries to be honoured at
+ * boot without forcing a startup reorder.
+ */
+import { type AuthBrokerClientConfig, type DiscoverAuthStorageOptions, getAuthBrokerTokenFilePath } from "jeopi-ai/auth-broker/discover";
+import type { AuthStorage } from "./auth-storage";
+export { type AuthBrokerClientConfig, getAuthBrokerTokenFilePath };
+/**
+ * Read broker configuration. Returns null when the URL is missing
+ * (broker disabled — local store is used). Throws when URL is set but no
+ * token is available — the caller cannot fall back silently because the
+ * user explicitly asked to use the broker.
+ *
+ * Successful resolutions (including "no broker configured") are memoized for
+ * the process lifetime; failures are not, so a missing token can be fixed and
+ * retried. Concurrent callers share one in-flight resolution.
+ */
+export declare function resolveAuthBrokerConfig(): Promise<AuthBrokerClientConfig | null>;
+/**
+ * Create an AuthStorage instance, using the broker when configured and falling
+ * back to the local SQLite store otherwise. Delegates to the shared resolver in
+ * pi-ai so the CLI, subagents, and the catalog generator all see the same
+ * credentials.
+ *
+ * Default `agentDir` is the current configured agent directory.
+ */
+export declare function discoverAuthStorage(agentDir?: string, options?: Omit<DiscoverAuthStorageOptions, "agentDir" | "configValueResolver">): Promise<AuthStorage>;

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

@@ -0,0 +1,7 @@
+/**
+ * Re-exports from jeopi-ai.
+ * All credential storage types and the AuthStorage class now live in the ai package.
+ */
+export type { ApiKeyCredential, AuthCredential, AuthCredentialEntry, AuthCredentialStore, AuthStorageData, AuthStorageOptions, CredentialOrigin, CredentialOriginKind, OAuthAccountIdentity, OAuthCredential, ResetCreditAccountStatus, ResetCreditRedeemOutcome, ResetCreditTarget, SerializedAuthStorage, StoredAuthCredential, } from "jeopi-ai";
+export { AuthStorage, REMOTE_REFRESH_SENTINEL, SqliteAuthCredentialStore } from "jeopi-ai";
+export type { SnapshotResponse } from "jeopi-ai/auth-broker/types";

package/dist/types/session/blob-store.d.ts

@@ -0,0 +1,68 @@
+export interface BlobPutOptions {
+    /** Optional file extension for a sidecar hardlink/copy that OS openers can type-detect. */
+    extension?: string;
+}
+export interface BlobPutResult {
+    hash: string;
+    /** Canonical content-addressed path, always `<dir>/<sha256-hex>`. */
+    path: string;
+    /** Path with the requested extension when supplied, otherwise the canonical path. */
+    displayPath: string;
+    get ref(): string;
+}
+export declare function blobExtensionForImageMimeType(mimeType: string | undefined): string | undefined;
+export declare class BlobStore {
+    readonly dir: string;
+    constructor(dir: string);
+    /**
+     * Write binary data to the blob store.
+     * @returns SHA-256 hex hash of the data
+     */
+    put(data: Buffer, options?: BlobPutOptions): Promise<BlobPutResult>;
+    /**
+     * Synchronous variant of {@link put}. Use on persistence hot paths where the caller
+     * cannot afford the microtask hops of the async version (e.g. OOM-safe session writes).
+     * Returns once the bytes are in the kernel page cache.
+     */
+    putSync(data: Buffer, options?: BlobPutOptions): BlobPutResult;
+    /** Read blob by hash, returns Buffer or null if not found. */
+    get(hash: string): Promise<Buffer | null>;
+    /** Synchronous variant of {@link get}. */
+    getSync(hash: string): Buffer | null;
+    /** Check if a blob exists. */
+    has(hash: string): Promise<boolean>;
+}
+/** Check if a data string is a blob reference. */
+export declare function isBlobRef(data: string): boolean;
+/** Extract the SHA-256 hash from a blob reference string. */
+export declare function parseBlobRef(data: string): string | null;
+/** Identify provider transport image data URLs so persistence can externalize and restore them losslessly. */
+export declare function isImageDataUrl(data: string): boolean;
+/**
+ * Externalize a provider image data URL to the blob store, returning a blob reference.
+ * The full data URL string is preserved so transport-native history can be reconstructed on resume.
+ */
+export declare function externalizeImageDataUrl(blobStore: BlobStore, dataUrl: string): Promise<string>;
+/** Synchronous variant of {@link externalizeImageDataUrl}. */
+export declare function externalizeImageDataUrlSync(blobStore: BlobStore, dataUrl: string): string;
+/**
+ * Externalize an image's base64 data to the blob store, returning a blob reference.
+ * If the data is already a blob reference, returns it unchanged.
+ */
+export declare function externalizeImageData(blobStore: BlobStore, base64Data: string, mimeType?: string): Promise<string>;
+/** Synchronous variant of {@link externalizeImageData}. */
+export declare function externalizeImageDataSync(blobStore: BlobStore, base64Data: string, mimeType?: string): string;
+/**
+ * Resolve an externalized provider image data URL back to its original string.
+ * If the data is not a blob reference, returns it unchanged.
+ * If the blob is missing, logs a warning and returns the reference as-is.
+ */
+export declare function resolveImageDataUrl(blobStore: BlobStore, data: string): Promise<string>;
+/**
+ * Resolve a blob reference back to base64 data.
+ * If the data is not a blob reference, returns it unchanged.
+ * If the blob is missing, logs a warning and returns a placeholder.
+ */
+export declare function resolveImageData(blobStore: BlobStore, data: string): Promise<string>;
+/** Synchronous variant of {@link resolveImageData}. */
+export declare function resolveImageDataSync(blobStore: BlobStore, data: string): string;

package/dist/types/session/client-bridge.d.ts

@@ -0,0 +1,88 @@
+/**
+ * ClientBridge — abstraction over capabilities provided by an external client
+ * (e.g. ACP editor host) that the agent can route through instead of operating
+ * directly on the local filesystem / spawning local subprocesses.
+ *
+ * When `undefined`, tools fall back to local IO. When populated (currently
+ * only by `AcpAgent`), tools route requests through the client so it can
+ * surface unsaved buffer state, render terminals in the IDE, or gate
+ * destructive operations behind user permission prompts.
+ */
+export interface ClientBridgeCapabilities {
+    /** Client implements `fs/read_text_file`. */
+    readTextFile?: boolean;
+    /** Client implements `fs/write_text_file`. */
+    writeTextFile?: boolean;
+    /** Client implements the `terminal/*` family. */
+    terminal?: boolean;
+    /** Client implements `session/request_permission`. */
+    requestPermission?: boolean;
+}
+export interface ClientBridgePermissionToolCall {
+    toolCallId: string;
+    toolName: string;
+    title: string;
+    kind?: string;
+    status?: "pending" | "in_progress" | "completed" | "failed";
+    rawInput?: unknown;
+    content?: unknown[];
+    locations?: {
+        path: string;
+        line?: number;
+    }[];
+}
+export type ClientBridgePermissionOptionKind = "allow_once" | "allow_always" | "reject_once" | "reject_always";
+export interface ClientBridgePermissionOption {
+    optionId: string;
+    name: string;
+    kind: ClientBridgePermissionOptionKind;
+}
+export type ClientBridgePermissionOutcome = {
+    outcome: "cancelled";
+} | {
+    outcome: "selected";
+    optionId: string;
+    kind?: ClientBridgePermissionOptionKind;
+};
+export interface ClientBridgeTerminalExitStatus {
+    exitCode?: number | null;
+    signal?: string | null;
+}
+export interface ClientBridgeTerminalOutput {
+    output: string;
+    truncated: boolean;
+    exitStatus?: ClientBridgeTerminalExitStatus | null;
+}
+export interface ClientBridgeTerminalHandle {
+    terminalId: string;
+    waitForExit(): Promise<ClientBridgeTerminalExitStatus>;
+    currentOutput(): Promise<ClientBridgeTerminalOutput>;
+    kill(): Promise<void>;
+    release(): Promise<void>;
+}
+export interface ClientBridgeCreateTerminalParams {
+    command: string;
+    args?: string[];
+    env?: Array<{
+        name: string;
+        value: string;
+    }>;
+    cwd?: string;
+    outputByteLimit?: number;
+}
+export interface ClientBridge {
+    readonly capabilities: ClientBridgeCapabilities;
+    /** ACP v1 clients cannot show server-initiated turns as busy after prompt response. */
+    readonly deferAgentInitiatedTurns?: boolean;
+    readTextFile?(params: {
+        path: string;
+        line?: number;
+        limit?: number;
+    }): Promise<string>;
+    writeTextFile?(params: {
+        path: string;
+        content: string;
+    }): Promise<void>;
+    createTerminal?(params: ClientBridgeCreateTerminalParams): Promise<ClientBridgeTerminalHandle>;
+    requestPermission?(toolCall: ClientBridgePermissionToolCall, options: ClientBridgePermissionOption[], signal?: AbortSignal): Promise<ClientBridgePermissionOutcome>;
+}

package/dist/types/session/codex-auto-reset.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Pure decision predicate for auto-redeeming a saved OpenAI Codex rate-limit
+ * reset, plus the process-wide coordinator that serializes attempts.
+ *
+ * WHY THIS IS REACTIVE-ONLY (never proactive):
+ * The only trustworthy "blocked right now" signal is a live 429 /
+ * `usage_limit_reached` from a request authenticated as the session's active
+ * Codex credential. The session hook calls this predicate from the usage-limit
+ * branch of the retry pipeline, *after* free remedies (sibling-account switch)
+ * fail and *before* model fallback. A proactive surface (the status-line usage
+ * poll) cannot be used: at `used_percent < 100` the account is not actually
+ * limited, so redeeming would be a credit-wasting no-op; at exactly 100 the
+ * user may be idle, so the freshly-reset weekly window would tick away with
+ * nobody working. Saved resets are a scarce, ~monthly, effectively
+ * irreversible resource — every gate here is biased to precision over recall:
+ * we would rather miss a redeem than waste a credit.
+ *
+ * THE DECISION-2 TRAP (status MUST NOT be used to find the blocker):
+ * `openai-codex.ts` applies the top-level `rate_limit.limit_reached` flag to
+ * BOTH the primary (5h) and secondary (weekly) `buildUsageLimit` calls, so when
+ * an account is blocked, *both* limit entries carry `status: "exhausted"`
+ * regardless of which window is actually at 100%. Only `amount.usedFraction`
+ * disambiguates which window is the real blocker. This module therefore keys
+ * eligibility off exact limit ids (`openai-codex:primary` /
+ * `openai-codex:secondary`) and `usedFraction`, never off `status`.
+ *
+ * ANTI-WASTE GATES (in evaluation order): the policy must not be set to "no";
+ * the active model must be Codex (not Spark — a Spark block lives on a
+ * separate meter and it is unknown whether a credit even resets it); a fresh
+ * usage report for the active account must confirm `limitReached`; the WEEKLY
+ * (secondary) window must be genuinely exhausted — a 5h-only block self-heals
+ * within the hour, so a credit spent there buys nothing; the natural reset must be far
+ * enough away to justify spending a ~30-day credit yet within one plausible
+ * window length; a credit must be verifiably available above the reserve; and
+ * the same block episode must not have been attempted already (debounce +
+ * per-account cooldown). All of this is pure — no fetches, no IO. The only
+ * stateful piece is the {@link CodexAutoRedeemCoordinator} container, whose
+ * read-only views are passed in so the predicate itself stays deterministic.
+ */
+import type { OAuthAccountIdentity, ResetCreditTarget, UsageReport } from "jeopi-ai";
+import type { CodexAutoRedeemMode } from "../config/settings-schema";
+/** Weekly window counts as exhausted at `usedFraction >= 0.999` (used_percent >= 99.9). */
+export declare const WEEKLY_EXHAUSTED_MIN_FRACTION = 0.999;
+/** A weekly reset can never be more than one window length (7d) away; +1h slack for skew. */
+export declare const MAX_PLAUSIBLE_REMAINING_MS: number;
+/** Report must be no older than the 5-min usage cache TTL plus slack. */
+export declare const REPORT_FRESHNESS_MS: number;
+/** Per-account cooldown that catches blockKey drift across a minute boundary. */
+export declare const ATTEMPT_COOLDOWN_MS = 60000;
+/** Minute bucket for blockKey, absorbing `reset_after_seconds`-derived jitter. */
+export declare const DEBOUNCE_BUCKET_MS = 60000;
+export declare function shouldEvaluateCodexAutoRedeem(mode: CodexAutoRedeemMode): boolean;
+export declare function shouldPromptCodexAutoRedeem(mode: CodexAutoRedeemMode): boolean;
+export type CodexAutoRedeemSkipReason = "disabled" | "wrong-provider" | "spark-model" | "no-identity" | "no-report" | "stale-report" | "not-limit-reached" | "weekly-not-exhausted" | "no-reset-time" | "reset-too-soon" | "reset-implausible" | "credits-unknown" | "reserve" | "already-attempted" | "cooldown";
+export interface CodexAutoRedeemInput {
+    nowMs: number;
+    /** `this.model.provider`. */
+    provider: string;
+    /** `this.model.id`. */
+    modelId: string;
+    settings: {
+        autoRedeem: boolean;
+        minBlockedMinutes: number;
+        keepCredits: number;
+    };
+    /** `getOAuthAccountIdentity("openai-codex", sessionId)`, captured at hook entry before any await. */
+    identity: OAuthAccountIdentity | undefined;
+    /** `session.fetchUsageReports()` (≤5-min cache). */
+    reports: UsageReport[] | null;
+    attemptedBlockKeys: ReadonlySet<string>;
+    lastAttemptAtByAccount: ReadonlyMap<string, number>;
+}
+export interface CodexAutoRedeemRedeemDecision {
+    redeem: true;
+    target: ResetCreditTarget;
+    accountKey: string;
+    blockKey: string;
+    weeklyResetAtMs: number;
+    remainingMs: number;
+    availableCount: number;
+}
+export type CodexAutoRedeemDecision = CodexAutoRedeemRedeemDecision | {
+    redeem: false;
+    reason: CodexAutoRedeemSkipReason;
+};
+/**
+ * Decide whether to auto-redeem a saved Codex reset for the active account.
+ *
+ * Pure: every gate below is a function of the snapshot inputs only. Order
+ * matters — cheapest / most-decisive gates first so the common "not eligible"
+ * paths short-circuit before any account/report matching.
+ */
+export declare function evaluateCodexAutoRedeem(input: CodexAutoRedeemInput): CodexAutoRedeemDecision;
+/**
+ * Process-wide (NOT per-session) coordinator state. Parallel subagent sessions
+ * share the same Codex accounts and must not race a double-spend, so this is a
+ * single shared container, not a per-session field.
+ *
+ * - `attemptedBlockKeys`: one attempt EVER per block episode, regardless of
+ *   outcome — recorded before calling the consume so exceptions can't re-enter.
+ * - `lastAttemptAtByAccount`: per-account cooldown timestamps (epoch ms),
+ *   catching blockKey drift across a minute boundary.
+ * - `inFlightByAccount`: serializes per account — a second session for the same
+ *   account adopts the in-flight promise instead of starting a second consume.
+ */
+export interface CodexAutoRedeemCoordinator {
+    attemptedBlockKeys: Set<string>;
+    lastAttemptAtByAccount: Map<string, number>;
+    inFlightByAccount: Map<string, Promise<boolean>>;
+}
+export declare const defaultCodexAutoRedeemCoordinator: CodexAutoRedeemCoordinator;

package/dist/types/session/compact-modes.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Manual `/compact` subcommands. Kept in a dependency-free leaf module so the
+ * slash-command registry, the interactive controllers, and `AgentSession`
+ * can all import the mode metadata + parser without pulling in the heavy
+ * `agent-session` module graph (which would form an import cycle through the
+ * slash-command registry) — same rationale as `shake-types.ts`.
+ *
+ * Each mode is a one-off override layered on top of the configured
+ * `compaction.*` settings for a single invocation; it never mutates settings.
+ * Adding a mode is a single entry here: the command surface (autocomplete +
+ * ACP hint), the parser, and the engine override all read this table.
+ */
+/** Subcommand selecting a one-off compaction mode for manual `/compact`. */
+export type CompactMode = "soft" | "remote" | "snapcompact";
+/**
+ * Per-invocation overrides merged over the configured `compaction.*` settings.
+ * Narrowed to the two knobs the modes actually flip; the result stays
+ * assignable to the full `CompactionSettings`.
+ */
+export interface CompactionOverride {
+    strategy?: "context-full" | "snapcompact";
+    remoteEnabled?: boolean;
+}
+export interface CompactModeDef {
+    readonly name: CompactMode;
+    /** One-line description surfaced in autocomplete + help. */
+    readonly description: string;
+    /** Settings overrides applied on top of `compaction.*` for this run. */
+    readonly overrides: CompactionOverride;
+    /**
+     * When true, the mode produces no LLM summary, so trailing focus text is
+     * meaningless and rejected by the parser (snapcompact archives history into
+     * images without a directed summary).
+     */
+    readonly rejectsFocus?: boolean;
+    /**
+     * When true, the mode explicitly demands a remote path; the engine warns and
+     * falls back to a local summary if neither a remote endpoint nor a
+     * provider-native compaction path is available.
+     */
+    readonly requiresRemote?: boolean;
+}
+export declare const COMPACT_MODES: readonly CompactModeDef[];
+/** Resolve a subcommand token (case-insensitive) to its mode definition. */
+export declare function findCompactMode(name: string): CompactModeDef | undefined;
+/** Parsed `/compact` arguments: an optional mode plus optional focus text. */
+export interface ParsedCompactArgs {
+    mode?: CompactMode;
+    instructions?: string;
+}
+/**
+ * Split `/compact` args into a leading mode subcommand + focus instructions.
+ *
+ * Backward compatible: when the first token is not a known mode, the entire
+ * argument string is treated as focus instructions (the historical behavior).
+ * A recognized mode with `rejectsFocus` and trailing text is an error.
+ */
+export declare function parseCompactArgs(args: string): ParsedCompactArgs | {
+    error: string;
+};

package/dist/types/session/exit-diagnostics.d.ts

@@ -0,0 +1,48 @@
+import type { SessionEntry } from "./session-entries";
+export declare const TOOL_EXECUTION_START_CUSTOM_TYPE = "tool_execution_start";
+export declare const SESSION_EXIT_CUSTOM_TYPE = "session_exit";
+/**
+ * Compact projection of tool-call arguments persisted with the start marker.
+ * The assistant message already carries the full arguments; this exists only
+ * so `appendArgumentSummary` can name the command/path in resume warnings
+ * without duplicating whole argument payloads into the session JSONL.
+ */
+export interface ToolArgumentSummary {
+    command?: string;
+    path?: string;
+}
+/** Persisted marker written before a tool implementation starts running. */
+export interface ToolExecutionStartData {
+    toolCallId: string;
+    toolName: string;
+    args?: ToolArgumentSummary;
+    intent?: string;
+    startedAt: string;
+}
+/** Tool call left without a matching toolResult at the end of a branch. */
+export interface PendingToolCallDiagnostic {
+    toolCallId?: string;
+    toolName: string;
+    args?: unknown;
+    intent?: string;
+    assistantTimestamp?: number;
+    startedAt?: string;
+}
+/** Session shutdown marker written during normal and fatal process teardown. */
+export interface SessionExitData {
+    reason: string;
+    kind: "normal" | "signal" | "fatal" | "process_exit";
+    recordedAt: string;
+    pendingToolCalls?: PendingToolCallDiagnostic[];
+}
+/**
+ * Project full tool-call arguments down to the fields the pending-tool-call
+ * resume warning actually renders (`command`/`path`), truncated. Returns
+ * `undefined` when the arguments carry neither, so callers can omit `args`
+ * entirely instead of persisting an empty object.
+ */
+export declare function summarizeToolArguments(args: unknown): ToolArgumentSummary | undefined;
+/** Finds tool calls left pending at the end of a session branch. */
+export declare function collectPendingToolCalls(entries: readonly SessionEntry[]): PendingToolCallDiagnostic[];
+/** Builds the resume warning shown when a prior branch ended mid-tool-call. */
+export declare function describePendingToolCalls(entries: readonly SessionEntry[]): string | undefined;

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

@@ -0,0 +1,30 @@
+export interface HistoryEntry {
+    id: number;
+    prompt: string;
+    created_at: number;
+    cwd?: string;
+    /** ID of the session the prompt was submitted from, if known. */
+    sessionId?: string;
+}
+export declare class HistoryStorage {
+    #private;
+    private constructor();
+    static open(dbPath?: string): HistoryStorage;
+    /** @internal Reset the singleton and close its database — test-only. */
+    static resetInstance(): void;
+    /**
+     * Register a resolver that supplies the current session ID for prompts added
+     * without an explicit `sessionId`. Evaluated synchronously at `add()` time so
+     * batched writes capture the session active when the prompt was submitted.
+     */
+    setSessionResolver(resolver: () => string | undefined): void;
+    add(prompt: string, cwd?: string, sessionId?: string): Promise<void>;
+    getRecent(limit: number): HistoryEntry[];
+    search(query: string, limit: number): HistoryEntry[];
+    /**
+     * IDs of the sessions whose stored prompts match `query`, ordered by prompt
+     * recency and de-duplicated. Used to augment session ranking in the resume
+     * picker with prompts that the 4KB session-list prefix never sees.
+     */
+    matchingSessionIds(query: string, limit?: number): string[];
+}