@oh-my-pi/pi-coding-agent 17.0.8 → 17.1.0

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

@@ -0,0 +1,228 @@
+import { Agent, type AgentMessage, type AgentTool, type StreamFn } from "@oh-my-pi/pi-agent-core";
+import type { CodexCompactionContext, Context, Message, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions } from "@oh-my-pi/pi-ai";
+import { type AdvisorConfig, type AdvisorRuntimeStatus } from "../advisor/index.js";
+import type { ModelRegistry } from "../config/model-registry.js";
+import type { Settings } from "../config/settings.js";
+import type { PlanModeState } from "../plan-mode/state.js";
+import type { SecretObfuscator } from "../secrets/obfuscator.js";
+import type { AgentSessionEvent } from "./agent-session-events.js";
+import type { ClientBridge } from "./client-bridge.js";
+import type { CustomMessage, CustomMessagePayload } from "./messages.js";
+import { type RetryFallbackSelector } from "./retry-fallback-chains.js";
+import type { SessionManager } from "./session-manager.js";
+import type { YieldQueue } from "./yield-queue.js";
+/** Advisor statistics for the advisor status command. */
+export interface AdvisorStats {
+    configured: boolean;
+    active: boolean;
+    model?: Model;
+    contextWindow: number;
+    contextTokens: number;
+    tokens: {
+        input: number;
+        output: number;
+        reasoning: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+    cost: number;
+    messages: {
+        user: number;
+        assistant: number;
+        total: number;
+    };
+    /** Per-advisor breakdown for every configured advisor. */
+    advisors: PerAdvisorStat[];
+}
+/** One advisor's status, token usage, cost, and message counts. */
+export interface PerAdvisorStat {
+    name: string;
+    status: AdvisorRuntimeStatus;
+    model?: Model;
+    contextWindow: number;
+    contextTokens: number;
+    tokens: AdvisorStats["tokens"];
+    cost: number;
+    messages: AdvisorStats["messages"];
+    sessionId?: string;
+}
+/** Inputs that configure the advisor roster owned by a session. */
+export interface SessionAdvisorsOptions {
+    enabled: boolean;
+    tools?: AgentTool[];
+    watchdogPrompt?: string;
+    sharedInstructions?: string;
+    contextPrompt?: string;
+    configs?: AdvisorConfig[];
+    streamFn?: StreamFn;
+    transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
+}
+/** Options accepted when an advisor injects a primary-session message. */
+export interface AdvisorMessageDeliveryOptions {
+    triggerTurn?: boolean;
+    deliverAs?: "steer" | "followUp" | "nextTurn";
+    queueChipText?: string;
+    acceptTerminalEmptyStop?: boolean;
+}
+/** Session capabilities borrowed by the advisor controller. */
+export interface SessionAdvisorsHost {
+    agent: Agent;
+    sessionManager: SessionManager;
+    settings: Settings;
+    modelRegistry: ModelRegistry;
+    yieldQueue: YieldQueue;
+    obfuscator: SecretObfuscator | undefined;
+    providerSessionState: Map<string, ProviderSessionState>;
+    preferWebsockets: boolean | undefined;
+    onPayload: SimpleStreamOptions["onPayload"] | undefined;
+    onResponse: SimpleStreamOptions["onResponse"] | undefined;
+    onSseEvent: SimpleStreamOptions["onSseEvent"] | undefined;
+    agentKind(): "main" | "sub";
+    isDisposed(): boolean;
+    abortInProgress(): boolean;
+    allowAgentInitiatedTurns(): boolean;
+    planModeState(): PlanModeState | undefined;
+    clientBridge(): ClientBridge | undefined;
+    emitSessionEvent(event: AgentSessionEvent): Promise<void>;
+    emitNotice(level: "info" | "warning" | "error", message: string, source?: string): void;
+    sendCustomMessage(message: CustomMessagePayload, options?: AdvisorMessageDeliveryOptions): Promise<boolean>;
+    extractQueuedAdvisorCards(): CustomMessage[];
+    dropPendingAdvisorCards(): void;
+    preserveAdvisorCard(card: CustomMessage): void;
+    hasPendingNextTurnMessages(): boolean;
+    convertToLlmForSideRequest(messages: AgentMessage[]): Message[];
+    effectiveServiceTier(model: Model): ServiceTier | undefined;
+    resolveContextPromotionTarget(currentModel: Model, contextWindow: number): Promise<Model | undefined>;
+    resolveCompactionModelCandidates(preferredModel: Model | null | undefined, availableModels: Model[]): Model[];
+    resolveRetryFallbackRole(currentSelector: string, currentModel?: Model | null): string | undefined;
+    findRetryFallbackCandidates(role: string, currentSelector: string, currentModel?: Model | null): RetryFallbackSelector[];
+    isRetryFallbackSelectorSuppressed(selector: RetryFallbackSelector): boolean;
+    noteRetryFallbackCooldown(currentSelector: string, retryAfterMs: number | undefined, errorMessage: string): void;
+    createCodexCompactionContext(options: {
+        trigger: CodexCompactionContext["trigger"];
+        reason: CodexCompactionContext["reason"];
+        phase: CodexCompactionContext["phase"];
+    }): CodexCompactionContext;
+    sessionId(): string;
+}
+/** Owns advisor runtimes, delivery policy, context maintenance, and status reporting. */
+export declare class SessionAdvisors {
+    #private;
+    constructor(host: SessionAdvisorsHost, options: SessionAdvisorsOptions);
+    /** Delivers one completed primary turn to every live advisor. */
+    onPrimaryTurnEnd(messages: AgentMessage[], willContinue: boolean | undefined, signal?: AbortSignal): Promise<void>;
+    /** Rebuilds live advisors when role assignments alter their resolved runtime inputs. */
+    onModelRolesChanged(): void;
+    /** Starts configured advisor runtimes when they are eligible. */
+    buildRuntime(seedToCurrent?: boolean): boolean;
+    /** Stops every advisor runtime and starts recorder shutdown. */
+    stopRuntime(): void;
+    /** Detaches and drains recorder feeds before transcript artifacts are removed. */
+    detachAndCloseRecorders(): Promise<void>;
+    /** Re-primes advisor transcript views across a conversation boundary. */
+    resetSessionState(): void;
+    /** Re-primes advisor transcript views after an in-conversation history rewrite. */
+    resetAllRuntimes(): void;
+    /** Whether live runtimes still match the resolved advisor configuration. */
+    runtimeMatchesCurrentConfig(): boolean;
+    /** Whether concern/blocker delivery is inside the post-interrupt immunity window. */
+    isInterruptImmuneTurnActive(): boolean;
+    /** Latest aggregate recorder-close barrier. */
+    recorderClosed(): Promise<void>;
+    /** Whether a user interrupt currently suppresses advisor-driven auto-resume. */
+    get autoResumeSuppressed(): boolean;
+    set autoResumeSuppressed(value: boolean);
+    /** Tracks persistence of a visible advisor card emitted outside the primary loop. */
+    trackCardEvent(processing: Promise<void>): void;
+    /** Waits for all advisor-card persistence handlers currently in flight. */
+    waitForPendingCardEvents(): Promise<void>;
+    /**
+     * Prevent advisor notes from starting hidden primary turns while a headless
+     * caller prints and drains the final primary response.
+     */
+    prepareForHeadlessAdvisorDrain(): void;
+    /**
+     * Wait for active advisor reviews and their emitted card events before a
+     * headless caller disposes the session. Returns `false` and logs work disposal
+     * will abandon when the shared deadline expires or an advisor fails.
+     */
+    waitForAdvisorCatchup(timeoutMs: number): Promise<boolean>;
+    /**
+     * Enable or disable the advisor for this session. The setting is overridden for the session,
+     * and the runtime is started or stopped to match.
+     *
+     * @returns true when the advisor is actively running after the call.
+     */
+    setAdvisorEnabled(enabled: boolean): boolean;
+    /**
+     * Toggle the advisor setting and start/stop the runtime accordingly.
+     *
+     * @returns true when the advisor is actively running after the call.
+     */
+    toggleAdvisorEnabled(): boolean;
+    /**
+     * Replace the live advisor roster from an edited `WATCHDOG.yml` (the `/advisor
+     * configure` save path). Swaps the configs + shared baseline, then rebuilds the
+     * runtimes in place so the change applies without a restart. When the advisor is
+     * disabled the new configs are simply stored for the next enable.
+     *
+     * @returns the number of advisors active after the rebuild.
+     */
+    applyAdvisorConfigs(advisors: AdvisorConfig[], sharedInstructions: string | undefined): number;
+    /**
+     * Whether the advisor setting is enabled for this session.
+     */
+    isAdvisorEnabled(): boolean;
+    /**
+     * Whether a live advisor agent is attached to this session. True only when
+     * `advisor.enabled` is set AND a model resolved for the `advisor` role AND
+     * the advisor applies to this agent kind — i.e. the actual runtime exists,
+     * not merely the setting. Drives the status-line badge and `/dump advisor`.
+     */
+    isAdvisorActive(): boolean;
+    /**
+     * The names of the tools available to advisors this session (the pool a
+     * `/advisor configure` editor lists). The advisor is a full agent, so this is the
+     * full built tool set; a tool whose optional factory returns null (e.g. lsp with
+     * no servers) is absent.
+     */
+    getAdvisorAvailableToolNames(): string[];
+    /**
+     * The live advisor `Agent`, or `undefined` when no advisor runtime is
+     * attached. Surfaced for diagnostics (`/dump advisor` already serializes
+     * its transcript via {@link formatAdvisorHistoryAsText}) and so callers can
+     * verify the advisor inherits the session's provider-shaping options
+     * (`streamFn`, `promptCacheKey`, `providerSessionState`, ...).
+     */
+    getAdvisorAgent(): Agent | undefined;
+    /**
+     * Lightweight advisor status for the status line: returns just the configured
+     * flag and per-advisor name/status without computing token/cost breakdowns.
+     * Avoids re-tokenizing the advisor transcript on every render frame.
+     */
+    getAdvisorStatusOverview(): {
+        configured: boolean;
+        advisors: {
+            name: string;
+            status: AdvisorRuntimeStatus;
+        }[];
+    };
+    /**
+     * Return structured advisor stats for the status command and TUI panel.
+     */
+    getAdvisorStats(): AdvisorStats;
+    /**
+     * Format a concise advisor status line for ACP/text output.
+     */
+    formatAdvisorStatus(): string;
+    /**
+     * Format the advisor agent's own transcript (its system prompt, config,
+     * tools, and the markdown deltas it received plus its thinking/advise/read
+     * calls) as plain text — the advisor-side equivalent of
+     * {@link formatSessionAsText}. Returns null when no advisor is active.
+     */
+    formatAdvisorHistoryAsText(options?: {
+        compact?: boolean;
+    }): string | null;
+}

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

@@ -24,6 +24,12 @@ export interface SessionHeader {
     titleSource?: SessionTitleSource;
     timestamp: string;
     cwd: string;
+    /**
+     * Additional workspace directories beyond `cwd` (multi-root workspace).
+     * Absolute, normalized, deduplicated. Absent on legacy single-cwd sessions.
+     * See {@link SessionWorkspace} in `./session-workspace`.
+     */
+    additionalDirectories?: string[];
     parentSession?: string;
     /** Provider prompt-cache identity inherited by exact-route full forks. */
     providerPromptCacheKey?: string;
@@ -34,6 +40,8 @@ export interface NewSessionOptions {
     providerPromptCacheKey?: string;
     /** Skip flushing the current session and delete it instead of saving. */
     drop?: boolean;
+    /** Additional workspace directories to seed on the new session. */
+    additionalDirectories?: string[];
 }
 export interface SessionEntryBase {
     type: string;

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

@@ -0,0 +1,70 @@
+/** Handoff generation and session transition orchestration. */
+import { type Agent, type AgentMessage, type StreamFn, type ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { Message, Model, ServiceTier, SimpleStreamOptions } from "@oh-my-pi/pi-ai";
+import type { ModelRegistry } from "../config/model-registry.js";
+import type { Settings } from "../config/settings.js";
+import type { ExtensionRunner } from "../extensibility/extensions/index.js";
+import { type SecretObfuscator } from "../secrets/obfuscator.js";
+import type { HandoffResult, SessionHandoffOptions } from "./agent-session-types.js";
+import type { BashSessionTransition } from "./bash-runner.js";
+import type { SessionContext } from "./session-context.js";
+import type { SessionManager } from "./session-manager.js";
+/** Capabilities borrowed from the owning AgentSession. */
+export interface SessionHandoffHost {
+    agent: Agent;
+    sessionManager: SessionManager;
+    settings: Settings;
+    modelRegistry: ModelRegistry;
+    extensionRunner: ExtensionRunner | undefined;
+    sideStreamFn: StreamFn;
+    obfuscator: SecretObfuscator | undefined;
+    model(): Model | undefined;
+    thinkingLevel(): ThinkingLevel | undefined;
+    sessionId(): string;
+    sessionFile(): string | undefined;
+    baseSystemPrompt(): string[];
+    assertVibeSessionTransitionAllowed(action: string): void;
+    setSkipPostTurnMaintenance(timestamp: number | undefined): void;
+    obfuscateTextForProvider(text: string | undefined): string | undefined;
+    deobfuscateFromProvider(text: string): string;
+    convertMessagesToLlm(messages: AgentMessage[], signal?: AbortSignal): Promise<Message[]>;
+    prepareSimpleStreamOptions(options: SimpleStreamOptions, provider?: string): SimpleStreamOptions;
+    effectiveServiceTier(model: Model | undefined): ServiceTier | undefined;
+    flushPendingBash(): Promise<void>;
+    beginBashSessionTransition(): BashSessionTransition;
+    markBashSessionTransition(transition: BashSessionTransition): void;
+    finishBashSessionTransition(transition: BashSessionTransition, success: boolean): void;
+    cancelOwnAsyncJobs(): void;
+    clearCheckpointRuntimeState(): void;
+    clearSessionScopedToolState(): void;
+    clearFreshProviderSessionId(): void;
+    syncAgentSessionId(): void;
+    rekeyMemoryForCurrentSessionId(): void;
+    resetMemoryContextForNewTranscript(): Promise<void>;
+    clearPendingNextTurnMessages(): void;
+    resetTodoCycle(): void;
+    buildDisplaySessionContext(): SessionContext;
+    resetAdvisorRuntimes(): void;
+    syncTodoPhasesFromBranch(): void;
+}
+/** Generates handoff documents and owns the handoff session transition. */
+export declare class SessionHandoff {
+    #private;
+    constructor(host: SessionHandoffHost);
+    /**
+     * Cancel in-progress handoff generation.
+     */
+    abortHandoff(): void;
+    /**
+     * Check if handoff generation is in progress.
+     */
+    get isGeneratingHandoff(): boolean;
+    /**
+     * Generate a handoff document with a oneshot LLM call, then start a new session with it.
+     *
+     * @param customInstructions Optional focus for the handoff document
+     * @param options Handoff execution options
+     * @returns The handoff document text, or undefined if cancelled/failed
+     */
+    handoff(customInstructions?: string, options?: SessionHandoffOptions): Promise<HandoffResult | undefined>;
+}

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

@@ -1,4 +1,4 @@
-import type { ToolResultMessage } from "@oh-my-pi/pi-ai";
+import type { ImageContent, TextContent, ToolResultMessage } from "@oh-my-pi/pi-ai";
 export interface HistoryFormatOptions {
     /** Optional H1 prepended to the transcript. */
     title?: string;
@@ -35,6 +35,11 @@ export interface HistoryFormatOptions {
     toolResultIndex?: ReadonlyMap<string, ToolResultMessage>;
     consumedToolCallIds?: Set<string>;
 }
+export declare function formatExecutionSourcePreview(source: string): string;
+/** Pick the most informative scalar argument of a tool call. */
+export declare function formatToolCallPrimaryArg(name: string, args: Record<string, unknown> | undefined): string;
+export declare function formatToolCallIntentPreview(args: Record<string, unknown> | undefined): string | undefined;
+export declare function formatToolResultErrorPreview(content: string | readonly (TextContent | ImageContent)[]): string;
 /**
  * Hidden custom messages that inject the primary agent's operative *constraints*
  * — plan mode's rules and the approved plan it implements. A reviewer (the

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

@@ -21,9 +21,11 @@ export declare function parseSessionEntries(content: string): FileEntry[];
 export declare function loadEntriesFromFile(filePath: string, storage?: SessionStorage): Promise<FileEntry[]>;
 export declare function resolveBlobRefsInEntries(entries: FileEntry[], blobStore: BlobStore): Promise<void>;
 /**
- * Read-only message view of a session file: load entries, migrate to the
- * current version, resolve blob refs, and build the context along the
- * persisted leaf path (last entry). Does NOT create a writer or take the
- * session lock — safe to call against a file another session is writing.
+ * Read-only transcript view of a session file: load entries, migrate to the
+ * current version, resolve blob refs, and build the display transcript along
+ * the persisted leaf path (last entry). Uses transcript mode (collapsed to the
+ * latest compaction) so failed/aborted tail turns stay visible, unlike the
+ * provider-context builder which drops them. Does NOT create a writer or take
+ * the session lock — safe to call against a file another session is writing.
  */
 export declare function loadSessionMessagesReadOnly(filePath: string): Promise<AgentMessage[]>;

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

@@ -0,0 +1,246 @@
+/** Context maintenance for an active coding-agent session. */
+import { type Agent, type AgentMessage, type AgentTurnEndContext, type StreamFn, type ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import { type CompactionPreparation, type CompactionResult, type ShakeConfig } from "@oh-my-pi/pi-agent-core/compaction";
+import type { AssistantMessage, CodexCompactionContext, Message, Model, ProviderSessionState } from "@oh-my-pi/pi-ai";
+import type { ModelRegistry } from "../config/model-registry.js";
+import type { Settings } from "../config/settings.js";
+import type { ExtensionRunner } from "../extensibility/extensions/index.js";
+import type { CompactOptions, ContextUsage } from "../extensibility/extensions/types.js";
+import type { GoalModeState } from "../goals/state.js";
+import type { MemoryBackendOperationContext } from "../memory-backend/types.js";
+import type { NonMessageTokenSource } from "../modes/utils/context-usage.js";
+import type { ConfiguredThinkingLevel } from "../thinking.js";
+import type { AgentSessionEvent } from "./agent-session-events.js";
+import type { ContextUsageBreakdown, HandoffResult, SessionHandoffOptions } from "./agent-session-types.js";
+import type { SessionContext } from "./session-context.js";
+import type { SessionManager } from "./session-manager.js";
+import type { ShakeMode, ShakeResult } from "./shake-types.js";
+export type CompactionCheckResult = Readonly<{
+    deferredHandoff: boolean;
+    continuationScheduled: boolean;
+    automaticContinuationBlocked?: boolean;
+    historyRewritten?: boolean;
+}>;
+/** Shared no-op result for dispatcher paths that perform no maintenance. */
+export declare const COMPACTION_CHECK_NONE: CompactionCheckResult;
+/** Creates one provider-scoped compaction lifecycle descriptor. */
+export declare function createCodexCompactionContext(options: {
+    trigger: CodexCompactionContext["trigger"];
+    reason: CodexCompactionContext["reason"];
+    phase: CodexCompactionContext["phase"];
+}): CodexCompactionContext;
+/** Capabilities borrowed from the owning AgentSession. */
+export interface SessionMaintenanceHost {
+    agent: Agent;
+    sessionManager: SessionManager;
+    settings: Settings;
+    modelRegistry: ModelRegistry;
+    extensionRunner: ExtensionRunner | undefined;
+    sideStreamFn: StreamFn;
+    providerSessionState: Map<string, ProviderSessionState>;
+    model(): Model | undefined;
+    thinkingLevel(): ThinkingLevel | undefined;
+    isDisposed(): boolean;
+    isStreaming(): boolean;
+    isGeneratingHandoff(): boolean;
+    promptGeneration(): number;
+    sessionId(): string;
+    messages(): AgentMessage[];
+    baseSystemPrompt(): string[];
+    goalModeState(): GoalModeState | undefined;
+    planReferencePath(): string;
+    nonMessageTokenSource(): NonMessageTokenSource;
+    memoryBackendSession(): MemoryBackendOperationContext["session"];
+    emitSessionEvent(event: AgentSessionEvent): Promise<void>;
+    emitNotice(level: "info" | "warning" | "error", message: string, source?: string): void;
+    schedulePostPromptTask(task: (signal: AbortSignal) => Promise<void>, options?: {
+        delayMs?: number;
+        generation?: number;
+        onSkip?: (reason: "aborted" | "stale-generation") => void;
+    }): void;
+    scheduleAgentContinue(options?: {
+        delayMs?: number;
+        generation?: number;
+        shouldContinue?: () => boolean;
+        onSkip?: (reason: "aborted" | "stale-generation" | "session-unavailable" | "should-continue-false" | "post-restore-unavailable") => void;
+        onError?: () => void;
+    }): void;
+    scheduleCompactionContinuation(options: {
+        generation: number;
+        autoContinue: boolean;
+        terminalTextAnswer: boolean;
+        suppressContinuation: boolean;
+    }): boolean;
+    persistTurnMessagesForMidRunCompaction(context: AgentTurnEndContext | undefined): Promise<boolean>;
+    findLastAssistantMessage(): AssistantMessage | undefined;
+    disconnectFromAgent(): void;
+    reconnectToAgent(): void;
+    drainStrandedQueuedMessages(): void;
+    buildDisplaySessionContext(): SessionContext;
+    convertToLlmForSideRequest(messages: AgentMessage[]): Message[];
+    obfuscateTextForProvider(text: string | undefined): string | undefined;
+    obfuscatePreparationForProvider(preparation: CompactionPreparation): CompactionPreparation;
+    closeCodexProviderSessionsForHistoryRewrite(): void;
+    resetCodexProviderAfterCompaction(compaction: CodexCompactionContext): void;
+    resetPlanReference(): void;
+    syncTodoPhasesFromBranch(): void;
+    resetAdvisorRuntimes(): void;
+    rebaseAfterCompaction(): void;
+    getContextBreakdown(options?: {
+        contextWindow?: number;
+        pendingMessages?: AgentMessage[];
+    }): ContextUsageBreakdown | undefined;
+    getContextUsage(options?: {
+        contextWindow?: number;
+    }): ContextUsage | undefined;
+    shake(mode: ShakeMode, options?: {
+        config?: ShakeConfig;
+        signal?: AbortSignal;
+    }): Promise<ShakeResult>;
+    dropImages(): Promise<{
+        removed: number;
+    }>;
+    runHandoff(customInstructions?: string, options?: SessionHandoffOptions): Promise<HandoffResult | undefined>;
+    removeAssistantMessageFromActiveContext(message: AssistantMessage): void;
+    dropPersistedAssistantTurn(message: AssistantMessage): Promise<void>;
+    runRecoveryCompactionWithRollback(reason: "overflow" | "incomplete", message: AssistantMessage, allowDefer: boolean, options: {
+        autoContinue: boolean;
+        triggerContextTokens?: number;
+    }): Promise<CompactionCheckResult>;
+    parseRetryAfterMsFromError(errorMessage: string): number | undefined;
+    setModelTemporary(model: Model, thinkingLevel?: ConfiguredThinkingLevel, options?: {
+        ephemeral?: boolean;
+    }): Promise<void>;
+    abort(options?: {
+        goalReason?: "interrupted" | "internal";
+        reason?: string;
+        preserveCompaction?: boolean;
+    }): Promise<void>;
+    abortHandoff(): void;
+}
+/** Owns compaction, pruning, shake, promotion, and automatic context maintenance. */
+export declare class SessionMaintenance {
+    #private;
+    constructor(host: SessionMaintenanceHost);
+    /** Whether manual or automatic context maintenance is active. */
+    get isCompacting(): boolean;
+    /** Assistant timestamp whose post-turn maintenance must be skipped once. */
+    get skipPostTurnMaintenanceAssistantTimestamp(): number | undefined;
+    set skipPostTurnMaintenanceAssistantTimestamp(timestamp: number | undefined);
+    /**
+     * Strip image content blocks from every message on the current branch and
+     * persist the rewrite. Walks `SessionManager.getBranch()` in place — both
+     * `SessionMessageEntry.message` and `CustomMessageEntry.content` arrays
+     * are mutated, then `rewriteEntries` durably commits the new shape. The
+     * agent's runtime view is rebuilt from the freshly-mutated entries so any
+     * provider sessions caching message identity (Codex Responses) are torn
+     * down to force a clean replay on the next turn.
+     *
+     * No-op when the branch carries no images; returns `{ removed: 0 }` and
+     * skips the disk rewrite.
+     */
+    dropImages(): Promise<{
+        removed: number;
+    }>;
+    /**
+     * Surgically reduce context by dropping heavy content ("shake").
+     *
+     * - `images` delegates to {@link dropImages}.
+     * - `elide` replaces whole tool-call results and large fenced/XML blocks
+     *   with short placeholders that embed an `artifact://` recovery link.
+     *
+     * Mutates the branch in place, persists via `rewriteEntries`, replays the
+     * rebuilt context through the agent, and tears down provider sessions that
+     * cache message identity — same rewrite contract as {@link dropImages}.
+     *
+     * No-op (zero counts) when nothing is eligible.
+     */
+    shake(mode: ShakeMode, opts?: {
+        config?: ShakeConfig;
+        signal?: AbortSignal;
+    }): Promise<ShakeResult>;
+    /**
+     * Manually compact the session context.
+     * Aborts current agent operation first.
+     * @param customInstructions Optional instructions for the compaction summary
+     * @param options Optional callbacks for completion/error handling
+     */
+    compact(customInstructions?: string, options?: CompactOptions): Promise<CompactionResult>;
+    /**
+     * Cancel in-progress context maintenance (manual compaction, auto-compaction, or auto-handoff).
+     */
+    abortCompaction(): void;
+    /** Cancel only automatic maintenance while preserving a manual compaction. */
+    abortAutomaticCompaction(): void;
+    /** Trigger idle compaction through the auto-compaction flow (with UI events). */
+    runIdleCompaction(): Promise<void>;
+    runPrePromptCompactionIfNeeded(messages: AgentMessage[]): Promise<void>;
+    /**
+     * Compact continuing tool-loop runs before the next provider request.
+     *
+     * `onTurnEnd` is the safe boundary: tool results for the just-finished turn
+     * are already paired in `activeMessages`, the live array the agent loop reads
+     * before its next model call. Before compacting, the just-finished turn is
+     * synchronously persisted if async message hooks have not reached the normal
+     * append path yet. Mid-run handoff is suppressed because resetting the session
+     * while the loop owns `activeMessages` would race the next request; handoff
+     * strategy falls back to in-place context-full compaction here.
+     */
+    maintainContextMidRun(activeMessages: AgentMessage[], signal: AbortSignal | undefined, context: AgentTurnEndContext | undefined): Promise<void>;
+    /**
+     * Check if context maintenance or promotion is needed and run it.
+     * Called after agent_end and before prompt submission.
+     *
+     * Four cases (in order):
+     * 1. Input overflow + promotion: promote to larger model, retry without maintenance.
+     * 2. Input overflow + no promotion target: run context maintenance, auto-retry on same model.
+     * 3. Output incomplete (stopReason === "length", e.g. `response.incomplete`): the
+     *    model burned its output budget without producing an actionable deliverable
+     *    (reasoning-only or truncated). Drop the dead turn, try promotion, otherwise
+     *    run compaction/handoff and retry.
+     * 4. Threshold: context over threshold, run context maintenance (no auto-retry).
+     *
+     * @param assistantMessage The assistant message to check
+     * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
+     * @param allowDefer If true, threshold-driven handoff strategy may schedule itself as a
+     *   deferred post-prompt task instead of running inline. Callers running inside the
+     *   `agent_end` handler set this to true so `session.prompt()` resolves cleanly; callers
+     *   on the pre-prompt path (where the next agent turn is about to start) set it to false
+     *   to avoid racing the deferred handoff against the new turn.
+     * @param autoContinue Whether maintenance may schedule the agent-authored continuation prompt.
+     * @returns whether compaction/recovery scheduled a handoff, retry, auto-continue, or
+     *   queued-message drain that already owns the next turn. Callers MUST skip
+     *   `session_stop` and other agent continuations when `continuationScheduled`
+     *   is true.
+     */
+    checkCompaction(assistantMessage: AssistantMessage, skipAbortedCheck?: boolean, allowDefer?: boolean, autoContinue?: boolean): Promise<CompactionCheckResult>;
+    resolveContextPromotionTarget(currentModel: Model, contextWindow: number): Promise<Model | undefined>;
+    resolveCompactionModelCandidates(preferredModel: Model | null | undefined, availableModels: Model[], filter?: (model: Model) => boolean): Model[];
+    /**
+     * Internal: Run auto-compaction with events.
+     *
+     * @param allowDefer If true (default), threshold-driven handoff strategy is allowed to
+     *   schedule itself as a deferred post-prompt task and return a deferred-handoff result
+     *   immediately. The caller MUST treat that as "compaction will happen async — do not
+     *   also schedule `agent.continue()` for this turn", otherwise the deferred handoff
+     *   races a fresh streaming turn (the symptom: "Auto-handoff" loader + assistant
+     *   message still streaming). Callers on a path that is about to start a new agent
+     *   turn (e.g. the pre-prompt check in `#promptWithMessage`) pass `false` to force
+     *   inline execution so the handoff completes before the new turn begins.
+     * @returns whether auto-compaction scheduled a follow-up turn.
+     */
+    runAutoCompaction(reason: "overflow" | "threshold" | "idle" | "incomplete", willRetry: boolean, deferred?: boolean, allowDefer?: boolean, options?: {
+        autoContinue?: boolean;
+        triggerContextTokens?: number;
+        suppressContinuation?: boolean;
+        suppressHandoff?: boolean;
+        phase?: CodexCompactionContext["phase"];
+        terminalTextAnswer?: boolean;
+    }): Promise<CompactionCheckResult>;
+    /**
+     * Toggle auto-compaction setting.
+     */
+    setAutoCompactionEnabled(enabled: boolean): void;
+    /** Whether auto-compaction is enabled */
+    get autoCompactionEnabled(): boolean;
+}

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

@@ -23,6 +23,15 @@ interface SessionManagerStateSnapshot {
     header: SessionHeader;
     entries: SessionEntry[];
 }
+/**
+ * The storage may have published a write that rejected, and an authoritative
+ * repair could not be proven durable. Callers must fail closed until recovery.
+ */
+export declare class SessionPersistenceIndeterminateError extends AggregateError {
+    readonly operationError: Error;
+    readonly recoveryErrors: readonly Error[];
+    constructor(operationError: Error, recoveryErrors: readonly Error[]);
+}
 /**
  * Stores and navigates an append-only conversation journal.
  *
@@ -83,6 +92,21 @@ export declare class SessionManager {
      * session/new must create a discoverable file immediately).
      */
     ensureOnDisk(): Promise<void>;
+    /**
+     * Stage a synchronous group of entry appends and publish the resulting full
+     * journal with one atomic replace. A failed publish removes only the staged
+     * entries, preserves/reparents entries appended concurrently, restores the
+     * prior durable file view, and clears the failed writer latch for retry.
+     *
+     * The callback MUST be synchronous.
+     */
+    appendEntriesAtomically<T>(append: () => T): Promise<T>;
+    /**
+     * Replace an uncertain append tail with the authoritative in-memory journal.
+     * Callers must only use this for monotonic recovery where every retained
+     * entry remains intended (for example, an explicit terminal tombstone).
+     */
+    recoverPersistenceFromCurrentState(): Promise<void>;
     /** Flush pending writes. Call before switching sessions or on shutdown. */
     flush(): Promise<void>;
     /**
@@ -94,6 +118,23 @@ export declare class SessionManager {
     /** Flush, then close the append writer. */
     close(): Promise<void>;
     getCwd(): string;
+    /** Additional workspace directories beyond cwd (multi-root), absolute and normalized. */
+    getAdditionalDirectories(): string[];
+    /**
+     * Add a workspace directory. Normalizes (relative to cwd), dedupes, rejects
+     * the cwd itself, persists to the session header, and triggers an atomic
+     * rewrite so the change survives a crash. Returns the resolved absolute
+     * path or `null` when the directory was already present (no-op).
+     */
+    addWorkspaceDirectory(directory: string): Promise<string | null>;
+    /**
+     * Remove a workspace directory by absolute or cwd-relative path. Persists
+     * the trimmed header. Returns the resolved path that was removed, or
+     * `null` when the directory was not an additional root (no-op).
+     */
+    removeWorkspaceDirectory(directory: string): Promise<string | null>;
+    /** Seed additional directories from settings or a passed list. Also called on resumed sessions with --add-dir; persists the updated header when the session file is already durable. No-op when the normalized list is unchanged (avoids rewriting large session files on every startup). */
+    setAdditionalDirectories(directories: string[]): Promise<void>;
     getUsageStatistics(): UsageStatistics;
     /**
      * Open a new per-turn budget window: snapshot the cumulative output baseline,