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

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

@@ -0,0 +1,225 @@
+import { type Agent, type AgentMessage, type ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { AssistantMessage, CodexCompactionContext, Model, ToolChoice } from "@oh-my-pi/pi-ai";
+import type { ModelRegistry } from "../config/model-registry.js";
+import type { Settings } from "../config/settings.js";
+import type { ConfiguredThinkingLevel } from "../thinking.js";
+import type { AgentSessionEvent } from "./agent-session-events.js";
+import type { InitialRetryFallbackState } from "./agent-session-types.js";
+import { type RetryFallbackSelector } from "./retry-fallback-chains.js";
+import type { SessionManager } from "./session-manager.js";
+/** Result shape shared with automatic maintenance recovery. */
+export interface RecoveryCompactionResult {
+    deferredHandoff: boolean;
+    continuationScheduled: boolean;
+    automaticContinuationBlocked?: boolean;
+    historyRewritten?: boolean;
+}
+/** Capabilities borrowed from the owning AgentSession. */
+export interface TurnRecoveryHost {
+    agent: Agent;
+    sessionManager: SessionManager;
+    settings: Settings;
+    modelRegistry: ModelRegistry;
+    configWarnings: string[];
+    model(): Model | undefined;
+    thinkingLevel(): ThinkingLevel | undefined;
+    configuredThinkingLevel(): ConfiguredThinkingLevel | undefined;
+    setThinkingLevel(level: ConfiguredThinkingLevel | undefined): void;
+    isDisposed(): boolean;
+    isStreaming(): boolean;
+    isCompacting(): boolean;
+    abortInProgress(): boolean;
+    streamingEditAbortTriggered(): boolean;
+    promptGeneration(): number;
+    sessionId(): string;
+    emitSessionEvent(event: AgentSessionEvent): Promise<void>;
+    scheduleAgentContinue(options: {
+        delayMs?: number;
+        generation?: number;
+    }): void;
+    waitForSessionMessagePersistence(message: AssistantMessage): Promise<void>;
+    appendSessionMessage(message: AssistantMessage): void;
+    sessionMessageAlreadyPersisted(message: AssistantMessage): boolean;
+    setModelWithProviderSessionReset(model: Model): void;
+    resetCurrentResponsesProviderSession(reason: string): void;
+    maybeAutoRedeemCodexReset(): Promise<boolean>;
+    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<RecoveryCompactionResult>;
+    withBashBranchTransition<T>(operation: () => T): T;
+}
+/** Construction-time retry state restored from model selection. */
+export interface TurnRecoveryOptions {
+    initialRetryFallback?: InitialRetryFallbackState;
+}
+/** Owns terminal-stop recovery, automatic retries, and fallback routing. */
+export declare class TurnRecovery {
+    #private;
+    constructor(host: TurnRecoveryHost, options?: TurnRecoveryOptions);
+    /** Current automatic retry attempt. */
+    get attempt(): number;
+    /** Promise settled when the active retry saga finishes. */
+    get retryPromise(): Promise<void> | undefined;
+    /** Resolved selector while fallback routing owns the current model. */
+    get retryFallbackModel(): string | undefined;
+    /** Resets per-prompt recovery counters and terminal-stop acceptance. */
+    resetForNewPrompt(): void;
+    /** Sets whether one terminal empty stop is accepted for the current prompt. */
+    setAcceptTerminalEmptyStop(accept: boolean): void;
+    /** Closes a successful retry saga and annotates recovered persisted errors. */
+    onAssistantSettledSuccessfully(message: AssistantMessage): Promise<void>;
+    /** Closes a failed retry saga when no compaction continuation took ownership. */
+    onErrorSettledWithoutRetry(message: AssistantMessage, compaction: RecoveryCompactionResult): Promise<void>;
+    /** Persists an otherwise skipped terminal empty error turn. */
+    persistTerminalEmptyErrorTurn(message: AssistantMessage): Promise<void>;
+    /** Handles empty terminal assistant turns and schedules bounded recovery. */
+    handleEmptyAssistantStop(message: AssistantMessage): Promise<boolean>;
+    /** Classifies suspicious terminal stops and schedules bounded recovery. */
+    handleUnexpectedAssistantStop(message: AssistantMessage): Promise<boolean>;
+    /** Removes a persisted failed assistant turn after its persistence slot settles. */
+    dropPersistedAssistantTurn(message: AssistantMessage): Promise<void>;
+    /** Runs recovery compaction and restores the failed turn when no rewrite occurs. */
+    runRecoveryCompactionWithRollback(reason: "overflow" | "incomplete", message: AssistantMessage, allowDefer: boolean, options: {
+        autoContinue: boolean;
+        triggerContextTokens?: number;
+    }): Promise<RecoveryCompactionResult>;
+    /** Restores the configured primary after fallback cooldown expiry. */
+    maybeRestoreRetryFallbackPrimary(): Promise<void>;
+    /** Applies automatic retry, credential rotation, and model fallback policy. */
+    handleRetryableError(message: AssistantMessage, options?: {
+        allowModelFallback?: boolean;
+        fireworksFastFallback?: boolean;
+        hardErrorFallback?: boolean;
+        preserveFailedTurn?: boolean;
+    }): Promise<boolean>;
+    /** Prompts after transient overlap with a prior agent run. */
+    promptAgentWithIdleRetry(messages: AgentMessage[], options?: {
+        toolChoice?: ToolChoice;
+    }): Promise<void>;
+    /** Parses provider retry and rate-limit reset hints into a delay. */
+    parseRetryAfterMsFromError(errorMessage: string): number | undefined;
+    /** Resolve the pending retry promise */
+    resolveRetry(): void;
+    removeAssistantMessageFromActiveContext(assistantMessage: AssistantMessage, reason?: string): void;
+    /**
+     * Drop an assistant turn from BOTH the live agent context and the persisted
+     * session branch (reparenting the leaf to the turn's parent), so a discarded
+     * turn does not resurface on reload. Used for empty/reasoning-only stops and
+     * the Gemini header-runaway interrupt, which must not replay a partial,
+     * loop-fueling thinking block.
+     */
+    discardAssistantTurn(assistantMessage: AssistantMessage): void;
+    /**
+     * Retry an empty, reason-less provider abort: a turn with no content that
+     * carries the generic sentinel (bare `abort()`), whether the provider
+     * finalized it as `stopReason: "aborted"` or leaked it as `stopReason:
+     * "error"` (a stalled/dropped stream reported as an error rather than an
+     * abort — issue #5375). Only fires while the session is neither aborting nor
+     * tearing down. A user/lifecycle abort (`#abortInProgress`), a dispose-driven
+     * abort (`#isDisposed`), or a session-induced streaming-edit guard abort
+     * (`StreamingEditGuard.abortTriggered` — auto-generated-file guard or failed-patch
+     * preview) is deliberate and MUST settle the turn instead: routing it through
+     * retry would orphan `#retryPromise` on a continuation the guard skips
+     * (hanging the in-flight `prompt()`) or silently undo the guard's intended
+     * abort. Deliberate user interrupts (`UserInterrupt`) and silent aborts carry
+     * their own marker, not the generic sentinel, so they never match here.
+     */
+    isRetryableReasonlessAbort(message: AssistantMessage): boolean;
+    /**
+     * Check if an error is retryable (transient errors or usage limits).
+     * Context overflow is NOT retryable (handled by compaction instead).
+     * Usage-limit errors are retryable because the retry handler performs credential switching.
+     */
+    isRetryableError(message: AssistantMessage): boolean;
+    /**
+     * Resume a stalled turn after every emitted tool call has produced a result.
+     * Cursor calls must also carry the server-execution marker. The failed
+     * assistant/tool-result pair stays in context so completed side effects are
+     * continued from rather than replayed.
+     */
+    canResumeResolvedStreamStall(message: AssistantMessage): boolean;
+    /** Checks whether a provider error represents a classifier refusal. */
+    isClassifierRefusal(message: AssistantMessage): boolean;
+    /** Clears fallback ownership after an explicit model change. */
+    clearActiveRetryFallback(): void;
+    /** Checks whether a fallback selector remains in cooldown. */
+    isRetryFallbackSelectorSuppressed(selector: RetryFallbackSelector): boolean;
+    /** Records the cooldown that should suppress a failing selector. */
+    noteRetryFallbackCooldown(currentSelector: string, retryAfterMs: number | undefined, errorMessage: string): void;
+    /**
+     * Map the failing model selector to the chain key that owns it, by
+     * specificity: an exact model-selector key, then a `provider/*` wildcard,
+     * then a model role whose current assignment matches, then `default`.
+     * Model-oriented keys win over roles so a chain follows the model across
+     * role reassignments.
+     */
+    resolveRetryFallbackRole(currentSelector: string, currentModel?: Model | null | undefined): string | undefined;
+    /** Finds fallback candidates that follow the active selector. */
+    findRetryFallbackCandidates(role: string, currentSelector: string, currentModel?: Model | null | undefined): RetryFallbackSelector[];
+    applyRetryFallbackCandidate(role: string, selector: RetryFallbackSelector, currentSelector: string, options?: {
+        pinFallback?: boolean;
+        apiKey?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * True when the current turn failed on a Fireworks Fast (`-fast`) model in a
+     * way that should degrade to the reliable base (Standard) model. Fast is a
+     * speed-optimized router with no SLA, so any *pre-content* failure — a
+     * transient overload/5xx or a hard "router/model not found / unsupported" —
+     * is worth retrying on the base id. Skips failures the base model shares:
+     * context overflow (compaction's job), usage limits and auth errors (same
+     * account/key), and turns that already emitted a tool call (replaying would
+     * duplicate work). Requires the base model to exist in the registry.
+     */
+    isFireworksFastFallbackEligible(message: AssistantMessage): boolean;
+    /**
+     * True when a turn failed with a hard (non-retryable) provider error but a
+     * configured `retry.fallbackChains` entry covers the active model: the same
+     * model is not worth retrying, yet a DIFFERENT model is a fresh chance, so
+     * the chain is consulted before the error becomes final. Skips failures a
+     * model switch cannot fix or must not replay: cancellations (abort-flavored
+     * errors are not model faults), context overflow (compaction's job),
+     * classifier refusals (chain consult is handled on the retryable path with
+     * `pinFallback`), and turns that already emitted a tool call (replaying
+     * could duplicate work).
+     */
+    isHardErrorFallbackEligible(message: AssistantMessage): boolean;
+    /**
+     * Cancel in-progress retry.
+     */
+    abortRetry(): void;
+    /** Whether auto-retry is currently in progress */
+    get isRetrying(): boolean;
+    /** Whether auto-retry is enabled */
+    get autoRetryEnabled(): boolean;
+    /**
+     * Toggle auto-retry setting.
+     */
+    setAutoRetryEnabled(enabled: boolean): void;
+    /**
+     * Manually retry the last failed assistant turn.
+     * Removes the error message from active agent state when present and
+     * re-attempts with a fresh retry budget.
+     *
+     * A stream that stalls or aborts mid-tool-call ends the turn with
+     * `stopReason: "error" | "aborted"` and then appends one synthetic
+     * {@link isSyntheticToolResultMessage tool_result} per emitted tool call to
+     * preserve the provider's tool_use/tool_result pairing (see
+     * `createAbortedToolResult` in `agent-loop.ts`). Those placeholders trail the
+     * failed assistant turn, so the retry lookback walks back over them before
+     * checking the assistant message; it strips both the placeholders and the
+     * failed turn before re-attempting.
+     *
+     * A restored session deliberately omits failed assistant turns from provider
+     * context. In that case, the persisted display transcript remains the source
+     * of truth for whether the current branch has a retryable failed tail.
+     *
+     * @returns true if retry was initiated, false if no failed turn to retry or agent is busy
+     */
+    retry(): Promise<boolean>;
+}

package/dist/types/system-prompt.d.ts

@@ -72,6 +72,8 @@ export interface BuildSystemPromptOptions {
     skillsSettings?: SkillsSettings;
     /** Working directory. Default: getProjectDir() */
     cwd?: string;
+    /** Additional workspace directories beyond cwd (multi-root), absolute. Injected into the project prompt. */
+    additionalWorkspaceRoots?: string[];
     /** Pre-loaded context files (skips discovery if provided). */
     contextFiles?: Array<{
         path: string;

package/dist/types/task/executor.d.ts

@@ -17,6 +17,7 @@ import type { HindsightSessionState } from "../hindsight/state.js";
 import type { LocalProtocolOptions } from "../internal-urls/index.js";
 import type { MCPManager } from "../mcp/manager.js";
 import type { MnemopiSessionState } from "../mnemopi/state.js";
+import { type AgentReviver } from "../registry/agent-lifecycle.js";
 import type { AgentSession } from "../session/agent-session.js";
 import type { ArtifactManager } from "../session/artifacts.js";
 import type { AuthStorage } from "../session/auth-storage.js";
@@ -44,6 +45,8 @@ export declare function buildBudgetNotice(requests: number, budget: number): str
 /** Options for subagent execution */
 export interface ExecutorOptions {
     cwd: string;
+    /** Additional workspace directories to seed on the subagent session (multi-root). */
+    additionalDirectories?: string[];
     worktree?: string;
     agent: AgentDefinition;
     task: string;
@@ -249,7 +252,7 @@ export declare function finalizeSubagentLifecycle(args: {
     keepAlive: boolean;
     isolated: boolean;
     agentIdleTtlMs: number;
-    reviveSession: (() => Promise<AgentSession>) | null;
+    reviveSession: AgentReviver | null;
 }): Promise<void>;
 /** Options for {@link runSubagentFollowUpTurn}. */
 export interface FollowUpTurnOptions {

package/dist/types/task/output-manager.d.ts

@@ -3,13 +3,15 @@
  *
  * The first allocation of a given name keeps the name as-is; subsequent
  * allocations of the same name get a `-2`, `-3`, … suffix. On resume, scans
- * existing output files so previously written outputs are never overwritten.
+ * existing output and child-session files so prior state is never overwritten.
  */
 export declare class AgentOutputManager {
     #private;
     constructor(getArtifactsDir: () => string | null, options?: {
         parentPrefix?: string;
     });
+    /** Reserve final IDs discovered outside the output directory scan. */
+    reserve(ids: Iterable<string>): Promise<void>;
     /**
      * Allocate a unique ID.
      *

package/dist/types/task/types.d.ts

@@ -83,6 +83,7 @@ export declare const taskItemSchema: import("arktype/internal/variants/object.ts
     name?: string | undefined;
     agent: import("arktype/internal/attributes.ts").Default<string, "task">;
     task: string;
+    model?: string | string[] | undefined;
     outputSchema?: string | boolean | object | null | undefined;
     schemaMode?: "permissive" | "strict" | undefined;
 }, {}>;
@@ -94,6 +95,8 @@ export interface TaskItem {
     agent?: string;
     /** The work; required by the schema. */
     task?: string;
+    /** Explicit model selector or fallback chain for this spawn, including optional reasoning suffixes. */
+    model?: string | string[];
     /** Caller-provided output schema; its presence overrides the selected agent's schema. */
     outputSchema?: unknown;
     /** Validation behavior for a caller-provided or inherited output schema. */
@@ -105,6 +108,7 @@ export declare const taskSchema: import("arktype/internal/variants/object.ts").O
     name?: string | undefined;
     agent: import("arktype/internal/attributes.ts").Default<string, "task">;
     task: string;
+    model?: string | string[] | undefined;
     outputSchema?: string | boolean | object | null | undefined;
     schemaMode?: "permissive" | "strict" | undefined;
     isolated?: boolean | undefined;
@@ -113,6 +117,7 @@ declare const ALL_TASK_SCHEMAS: readonly [import("arktype/internal/variants/obje
     name?: string | undefined;
     agent: import("arktype/internal/attributes.ts").Default<string, "task">;
     task: string;
+    model?: string | string[] | undefined;
     outputSchema?: string | boolean | object | null | undefined;
     schemaMode?: "permissive" | "strict" | undefined;
     isolated?: boolean | undefined;
@@ -120,6 +125,7 @@ declare const ALL_TASK_SCHEMAS: readonly [import("arktype/internal/variants/obje
     name?: string | undefined;
     agent: import("arktype/internal/attributes.ts").Default<string, "task">;
     task: string;
+    model?: string | string[] | undefined;
     outputSchema?: string | boolean | object | null | undefined;
     schemaMode?: "permissive" | "strict" | undefined;
 }, {}>, import("arktype/internal/variants/object.ts").ObjectType<{
@@ -128,6 +134,7 @@ declare const ALL_TASK_SCHEMAS: readonly [import("arktype/internal/variants/obje
         name?: string | undefined;
         agent: import("arktype/internal/attributes.ts").Default<string, "task">;
         task: string;
+        model?: string | string[] | undefined;
         outputSchema?: string | boolean | object | null | undefined;
         schemaMode?: "permissive" | "strict" | undefined;
         isolated?: boolean | undefined;
@@ -138,6 +145,7 @@ declare const ALL_TASK_SCHEMAS: readonly [import("arktype/internal/variants/obje
         name?: string | undefined;
         agent: import("arktype/internal/attributes.ts").Default<string, "task">;
         task: string;
+        model?: string | string[] | undefined;
         outputSchema?: string | boolean | object | null | undefined;
         schemaMode?: "permissive" | "strict" | undefined;
     }[];
@@ -168,6 +176,8 @@ export interface TaskParams {
     agent?: string;
     /** The work (flat form). */
     task?: string;
+    /** Explicit model selector or fallback chain for the spawn, including optional reasoning suffixes. */
+    model?: string | string[];
     /** Caller-provided output schema; its presence overrides the selected agent's schema. */
     outputSchema?: unknown;
     /** Validation behavior for a caller-provided or inherited output schema. */
@@ -291,6 +301,8 @@ export interface AgentProgress {
     modelOverride?: string | string[];
     /** Resolved model display string in the form `<provider>/<id>`, optionally suffixed with `:<thinkingLevel>` when the level was set explicitly. Undefined when the model could not be resolved. */
     resolvedModel?: string;
+    /** True when {@link resolvedModel} is the target of an active retry fallback (not the originally configured model). Lets observer-only UIs (collab guests, Agent Hub rows with no live session) flag the fallback and keep the provider. */
+    resolvedModelIsFallback?: boolean;
     /** Data extracted by registered subprocess tool handlers (keyed by tool name) */
     extractedToolData?: Record<string, unknown[]>;
     /**
@@ -357,6 +369,8 @@ export interface SingleResult {
     modelOverride?: string | string[];
     /** Resolved model display string in the form `<provider>/<id>`, optionally suffixed with `:<thinkingLevel>` when the level was set explicitly. Omitted from tool-result JSON when undefined to keep wire payloads small. */
     resolvedModel?: string;
+    /** True when {@link resolvedModel} is the target of an active retry fallback. Mirrors {@link AgentProgress.resolvedModelIsFallback} onto the settled result. */
+    resolvedModelIsFallback?: boolean;
     error?: string;
     aborted?: boolean;
     abortReason?: string;

package/dist/types/tools/approval.d.ts

@@ -16,6 +16,7 @@ export interface ResolvedApproval {
     tier: ToolTier;
     reason?: string;
     override: boolean;
+    source?: "tool" | "user" | "mode";
 }
 /**
  * Evaluate a tool's own approval declaration against `args` and return the

package/dist/types/tools/browser/launch.d.ts

@@ -14,6 +14,7 @@ export declare const BROWSER_PROTOCOL_TIMEOUT_MS = 60000;
 export declare function loadPuppeteer(): Promise<typeof Puppeteer>;
 export declare function loadPuppeteerInWorker(safeDir: string): Promise<typeof Puppeteer>;
 export declare function ensureChromiumExecutable(): Promise<string | undefined>;
+/** Options shared by headless Chromium consumers. */
 export interface LaunchHeadlessOptions {
     headless: boolean;
     viewport?: {
@@ -21,6 +22,10 @@ export interface LaunchHeadlessOptions {
         height: number;
         deviceScaleFactor?: number;
     };
+    /** Additional Chromium arguments merged with the centralized launch defaults. */
+    args?: readonly string[];
+    /** Additional exact Puppeteer default arguments to suppress. */
+    ignoreDefaultArgs?: readonly string[];
 }
 export declare function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promise<Browser>;
 export declare function applyViewport(page: Page, viewport?: {

package/dist/types/tools/hub/jobs.d.ts

@@ -55,7 +55,7 @@ export declare function noMatchingJobsResult(session: ToolSession, ids: string[]
 /** Bare `wait` with no running jobs and nobody who could message: nothing to block on. */
 export declare function nothingToWaitForResult(session: ToolSession): AgentToolResult<CoordinationDetails>;
 /** `cancel`: kill the named jobs; returns immediately with outcomes + snapshots. */
-export declare function executeCancel(session: ToolSession, manager: AsyncJobManager, ownerId: string | undefined, ids: string[]): AgentToolResult<CoordinationDetails>;
+export declare function executeCancel(session: ToolSession, manager: AsyncJobManager, ownerId: string | undefined, ids: string[]): Promise<AgentToolResult<CoordinationDetails>>;
 /** `jobs`: read-only snapshot of every job plus the jobless running-agent roster. */
 export declare function executeJobsSnapshot(session: ToolSession, manager: AsyncJobManager, ownerId: string | undefined): AgentToolResult<CoordinationDetails>;
 /** Pending-call frame for job ops (wait/cancel/jobs). */

package/dist/types/tools/image-gen.d.ts

@@ -1,7 +1,8 @@
 import { type Model } from "@oh-my-pi/pi-ai";
 import { type ModelRegistry } from "../config/model-registry.js";
 import type { CustomTool } from "../extensibility/custom-tools/types.js";
-export type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter" | "xai";
+import { type ImageProvider } from "./image-providers.js";
+export type { ImageProvider } from "./image-providers.js";
 export type ImageProviderPreference = ImageProvider | "auto";
 declare const responseModalitySchema: import("arktype/internal/variants/string.ts").StringType<"IMAGE" | "TEXT", {}>;
 export declare const imageGenSchema: import("arktype/internal/variants/object.ts").ObjectType<{
@@ -59,9 +60,8 @@ interface InlineImageData {
     mimeType: string;
 }
 export declare function isImageProviderPreference(value: unknown): value is ImageProviderPreference;
-/** Set the preferred image provider from settings */
-export declare function setPreferredImageProvider(provider: ImageProviderPreference): void;
+/** Set the configured image-provider priority from settings; invalid IDs are dropped. */
+export declare function setImageProviderOrder(providers: readonly string[]): void;
 export declare const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails>;
 export declare function getImageGenTools(_modelRegistry?: ModelRegistry, _activeModel?: Model): Promise<Array<CustomTool<typeof imageGenSchema, ImageGenToolDetails>>>;
 export declare function getImageGenToolsWithRegistry(_modelRegistry: ModelRegistry, _activeModel?: Model): Promise<Array<CustomTool<typeof imageGenSchema, ImageGenToolDetails>>>;
-export {};

package/dist/types/tools/image-providers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Image Generation Providers
+ *
+ * Leaf module (no runtime deps) shared by the image_gen tool, the settings
+ * schema, and settings migrations — mirrors `web/search/types.ts` so the
+ * provider list, auto order, and settings choices never drift apart.
+ */
+/** Image generation backends, in settings/tool vocabulary. */
+export type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter" | "xai";
+/** Auto-resolution fallback order when no configured entry or session provider matches. */
+export declare const AUTO_IMAGE_PROVIDER_ORDER: readonly ImageProvider[];
+/** Settings choices for `providers.imageOrder` (labels shared with the retired single-preference enum). */
+export declare const IMAGE_PROVIDER_CHOICES: readonly [{
+    readonly value: "openai";
+    readonly label: "OpenAI";
+    readonly description: "OPENAI_API_KEY (gpt-image-2) or active GPT model; falls back to a connected Codex subscription";
+}, {
+    readonly value: "openai-codex";
+    readonly label: "OpenAI Codex (ChatGPT)";
+    readonly description: "Uses a connected Codex / ChatGPT subscription — no OPENAI_API_KEY needed";
+}, {
+    readonly value: "antigravity";
+    readonly label: "Antigravity";
+    readonly description: "Requires google-antigravity OAuth";
+}, {
+    readonly value: "xai";
+    readonly label: "xAI Grok Imagine";
+    readonly description: "Requires xAI Grok OAuth or XAI_API_KEY";
+}, {
+    readonly value: "gemini";
+    readonly label: "Gemini";
+    readonly description: "Requires GEMINI_API_KEY";
+}, {
+    readonly value: "openrouter";
+    readonly label: "OpenRouter";
+    readonly description: "Requires OPENROUTER_API_KEY";
+}];
+export declare function isImageProviderId(value: unknown): value is ImageProvider;

package/dist/types/tools/index.d.ts

@@ -13,11 +13,13 @@ import type { LocalProtocolOptions } from "../internal-urls/index.js";
 import type { MCPManager } from "../mcp/index.js";
 import type { MnemopiSessionState } from "../mnemopi/state.js";
 import type { PlanModeState } from "../plan-mode/state.js";
+import type { AgentLifecycleManager } from "../registry/agent-lifecycle.js";
 import type { AgentRegistry } from "../registry/agent-registry.js";
 import type { ArtifactManager } from "../session/artifacts.js";
 import type { ClientBridge } from "../session/client-bridge.js";
 import type { CustomMessage } from "../session/messages.js";
 import type { UsageStatistics } from "../session/session-entries.js";
+import type { SessionManager } from "../session/session-manager.js";
 import type { ToolChoiceQueue } from "../session/tool-choice-queue.js";
 import type { AgentOutputManager } from "../task/output-manager.js";
 import { type StructuredSubagentSchemaMode } from "../task/types.js";
@@ -105,6 +107,8 @@ export interface DeferredDiagnosticsEntry {
 export interface ToolSession {
     /** Current working directory */
     cwd: string;
+    /** Additional workspace directories beyond cwd (multi-root), forwarded to subagents. */
+    additionalDirectories?: string[];
     /** Whether UI is available */
     hasUI: boolean;
     /**
@@ -176,6 +180,8 @@ export interface ToolSession {
     getEvalSessionId?: () => string | null;
     /** Get session file */
     getSessionFile: () => string | null;
+    /** Parent session journal used by tools that persist runtime lifecycle state. */
+    sessionManager?: Pick<SessionManager, "appendCustomEntry" | "ensureOnDisk" | "flush" | "getBranch" | "getEntries">;
     /** Get eval kernel owner ID for session-scoped retained-kernel cleanup. */
     getEvalKernelOwnerId?: () => string | null;
     /** Reject new eval work once session disposal has started. */
@@ -200,6 +206,8 @@ export interface ToolSession {
     xdevRegistry?: XdevRegistry;
     /** Agent registry for IRC routing across live sessions. */
     agentRegistry?: AgentRegistry;
+    /** Idle→parked→revive lifecycle owner; lets the hub kill a non-job-backed agent registration. Default: AgentLifecycleManager.global(). */
+    agentLifecycle?: () => AgentLifecycleManager;
     /** Get artifacts directory for artifact:// URLs */
     getArtifactsDir?: () => string | null;
     /** Get the ArtifactManager backing this session (shared across parent + subagents). */

package/dist/types/tools/path-utils.d.ts

@@ -236,6 +236,14 @@ export declare function partitionExistingPaths(items: string[], cwd: string, spl
     basePath: string;
 }): Promise<PartitionedPaths>;
 export declare function resolveReadPath(filePath: string, cwd: string): string;
+/**
+ * Find a unique workspace entry whose trailing path matches a missing authored path.
+ * Returns `null` for no match, ambiguity, timeout, or scan failure.
+ */
+export declare function findUniqueWorkspaceSuffix(rawPath: string, cwd: string, signal?: AbortSignal): Promise<{
+    absolutePath: string;
+    displayPath: string;
+} | null>;
 /** Local file materialized from a readable external URL for shared tool-scope resolution. */
 export interface ResolvedExternalSearchUrl {
     /** Absolute or cwd-relative file path to search. */

package/dist/types/tools/report-tool-issue.d.ts

@@ -5,16 +5,21 @@
  * `xd://report_issue`, and the system prompt tells the model to write
  * `<tool>: <concise description>` there when auto-QA is enabled.
  *
- * Enabled by default; gated behind PI_AUTO_QA=1 / `dev.autoqa` so a user who
- * flips the setting off short-circuits injection entirely.
+ * Enabled by default (`dev.autoqa` defaults to true); `PI_AUTO_QA=0` or an
+ * explicit `dev.autoqa: false` short-circuits injection entirely. When the
+ * user is only enabled by default (never configured `dev.autoqa` themselves),
+ * a persisted `dev.autoqaConsent: "denied"` also disables injection so a "No"
+ * in the consent dialog fully turns the feature off.
  * Records grievances to a local SQLite database; never throws from the device
  * dispatch path.
  *
- * Before the first record lands, the user's consent is checked. If they've
- * never been asked (`dev.autoqaConsent === "unset"`) the process-global
- * consent handler — wired by `InteractiveMode` to a Yes/No popup — is invoked
- * exactly once and the decision is persisted. Subsequent calls (including from
- * subagents) read the cached decision without prompting.
+ * Nothing is written until consent resolves. If the user has never been asked
+ * (`dev.autoqaConsent === "unset"`) the process-global consent handler —
+ * wired by `InteractiveMode` to a Yes/No popup — is invoked exactly once and
+ * the decision is persisted; a denial (or dismissal) drops the pending report
+ * without touching the database. Subsequent calls (including from subagents)
+ * read the cached decision without prompting. `PI_AUTO_QA_PUSH=1` bypasses
+ * the dialog for headless environments.
  *
  * When the user grants consent, push is automatically active against the
  * bundled endpoint (`dev.autoqaPush.endpoint`, default `qa.omp.sh`). Each
@@ -42,6 +47,14 @@ export declare function isReportIssueToolCall(toolCall: {
 }): boolean;
 /** Call preview for an `xd://report_issue` write. */
 export declare function renderReportIssueDeviceCall(content: unknown, uiTheme: Theme): Component;
+/**
+ * Whether Auto-QA is active for this session.
+ *
+ * Precedence: `PI_AUTO_QA` env flag > explicit `dev.autoqa` setting >
+ * default-on unless the user previously denied consent. The denial veto only
+ * applies to the default: explicitly configuring `dev.autoqa: true` re-enables
+ * injection (recording still no-ops until consent is granted).
+ */
 export declare function isAutoQaEnabled(settings?: Settings): boolean;
 /**
  * Resolver for the user's "share grievances?" consent.
@@ -82,8 +95,8 @@ export declare function __resetAutoQaConsentForTests(): void;
 export declare function resolveAutoQaConsent(settings: Settings | undefined): Promise<boolean>;
 /**
  * Open (or return the cached handle for) the auto-QA SQLite database at
- * `~/.omp/agent/autoqa.db`, creating the schema lazily. Returns `null` when
- * the agent data dir cannot be resolved.
+ * `~/.omp/autoqa.db` (XDG: `$XDG_DATA_HOME/omp/autoqa.db`), creating the
+ * schema lazily. Returns `null` when the path cannot be resolved or opened.
  */
 export declare function openAutoQaDb(): Database | null;
 export interface FlushResult {
@@ -127,6 +140,8 @@ export declare function __resetAutoQaFlushStateForTests(): void;
  * Flush queued grievances to the configured backend.
  */
 export declare function flushGrievances(db?: Database, settings?: Settings, options?: FlushOptions): Promise<FlushResult>;
+/** Test-only: await the last consent → insert → flush pipeline. */
+export declare function __awaitAutoQaRecordPipelineForTests(): Promise<void>;
 /**
  * Execute `write xd://report_issue`. `text` must be either:
  * - `<tool>: <concise description>` on one line, or

package/dist/types/tools/todo.d.ts

@@ -5,17 +5,21 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types.js
 import type { Theme } from "../modes/theme/theme.js";
 import type { ToolSession } from "../sdk.js";
 import type { SessionEntry } from "../session/session-entries.js";
-export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned";
+export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned" | "blocked";
 /** Operation names accepted by the todo tool and echoed in successful result details. */
-export type TodoOperation = "init" | "start" | "done" | "rm" | "drop" | "append" | "view";
+export type TodoOperation = "init" | "start" | "done" | "rm" | "drop" | "block" | "unblock" | "append" | "view";
 export interface TodoItem {
     content: string;
     status: TodoStatus;
+    /** When `status === "blocked"`, an optional note on what the task is waiting for. */
+    blocker?: string;
 }
 export interface TodoPhase {
     name: string;
     tasks: TodoItem[];
 }
+/** Whether an unknown value is a persisted todo phase. */
+export declare function isTodoPhase(value: unknown): value is TodoPhase;
 export interface TodoCompletionTransition {
     phase: string;
     content: string;
@@ -28,7 +32,7 @@ export interface TodoToolDetails {
     completedTasks?: TodoCompletionTransition[];
 }
 declare const todoSchema: import("arktype/internal/variants/object.ts").ObjectType<{
-    op: "append" | "done" | "drop" | "init" | "rm" | "start" | "view";
+    op: "append" | "block" | "done" | "drop" | "init" | "rm" | "start" | "unblock" | "view";
     list?: {
         phase: string;
         items: string[];
@@ -36,6 +40,7 @@ declare const todoSchema: import("arktype/internal/variants/object.ts").ObjectTy
     task?: string | undefined;
     phase?: string | undefined;
     items?: string[] | undefined;
+    reason?: string | undefined;
 }, {}>;
 type TodoParams = TodoSchema;
 type TodoSchema = typeof todoSchema.infer;
@@ -107,7 +112,7 @@ export declare class TodoTool implements AgentTool<typeof todoSchema, TodoToolDe
     readonly summary = "Write a structured todo list to track progress within a session";
     readonly description: string;
     readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
-        op: "append" | "done" | "drop" | "init" | "rm" | "start" | "view";
+        op: "append" | "block" | "done" | "drop" | "init" | "rm" | "start" | "unblock" | "view";
         list?: {
             phase: string;
             items: string[];
@@ -115,6 +120,7 @@ export declare class TodoTool implements AgentTool<typeof todoSchema, TodoToolDe
         task?: string | undefined;
         phase?: string | undefined;
         items?: string[] | undefined;
+        reason?: string | undefined;
     }, {}>;
     readonly concurrency = "exclusive";
     readonly strict = true;