@prometheus-ai/agent 0.5.3 → 0.5.8

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

@@ -14,12 +14,12 @@
  */
 import { type Agent, type AgentEvent, type AgentMessage, type AgentState, type AgentTool, ThinkingLevel } from "@prometheus-ai/agent-core";
 import { type CompactionResult, type ShakeConfig } from "@prometheus-ai/agent-core/compaction";
-import type { AssistantMessage, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, TextContent, ToolChoice, UsageReport } from "@prometheus-ai/ai";
+import type { AssistantMessage, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ResetCreditAccountStatus, ResetCreditRedeemOutcome, ResetCreditTarget, ServiceTier, SimpleStreamOptions, TextContent, ToolChoice, UsageReport } from "@prometheus-ai/ai";
 import { Effort } from "@prometheus-ai/ai";
 import type { InMemorySnapshotStore } from "@prometheus-ai/hashline";
 import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager } from "../async";
 import type { Rule } from "../capability/rule";
-import { type ModelRegistry } from "../config/model-registry";
+import type { ModelRegistry } from "../config/model-registry";
 import { type ResolvedModelRoleValue } from "../config/model-resolver";
 import { type PromptTemplate } from "../config/prompt-templates";
 import type { Settings, SkillsSettings } from "../config/settings";
@@ -36,9 +36,9 @@ import { type FileSlashCommand } from "../extensibility/slash-commands";
 import { GoalRuntime } from "../goals/runtime";
 import type { Goal, GoalModeState } from "../goals/state";
 import type { HindsightSessionState } from "../hindsight/state";
+import { type IrcMessage } from "../irc/bus";
 import { type MnemopiSessionState } from "../mnemopi/state";
 import type { PlanModeState } from "../plan-mode/state";
-import { type AgentRegistry } from "../registry/agent-registry";
 import { type SecretObfuscator } from "../secrets/obfuscator";
 import { type ConfiguredThinkingLevel } from "../thinking";
 import { type DiscoverableTool, type DiscoverableToolSearchIndex } from "../tool-discovery/tool-index";
@@ -46,7 +46,9 @@ import type { CheckpointState } from "../tools/checkpoint";
 import { type TodoItem, type TodoPhase } from "../tools/todo";
 import type { ClientBridge } from "./client-bridge";
 import { type CustomMessage } from "./messages";
-import type { BranchSummaryEntry, NewSessionOptions, SessionContext, SessionManager } from "./session-manager";
+import type { SessionContext } from "./session-context";
+import type { BranchSummaryEntry, NewSessionOptions } from "./session-entries";
+import type { SessionManager } from "./session-manager";
 import type { ShakeMode, ShakeResult } from "./shake-types";
 import { ToolChoiceQueue } from "./tool-choice-queue";
 import { YieldQueue } from "./yield-queue";
@@ -54,10 +56,10 @@ import { YieldQueue } from "./yield-queue";
 export type AgentSessionEvent = AgentEvent | {
     type: "auto_compaction_start";
     reason: "threshold" | "overflow" | "idle" | "incomplete";
-    action: "context-full" | "handoff" | "shake";
+    action: "context-full" | "handoff" | "shake" | "snapcompact";
 } | {
     type: "auto_compaction_end";
-    action: "context-full" | "handoff" | "shake";
+    action: "context-full" | "handoff" | "shake" | "snapcompact";
     result: CompactionResult | undefined;
     aborted: boolean;
     willRetry: boolean;
@@ -116,6 +118,7 @@ export type AgentSessionEvent = AgentEvent | {
 };
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
+export type CommandMetadataChangedListener = () => void | Promise<void>;
 export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime">;
 export interface AsyncJobSnapshot {
     running: AsyncJobSnapshotItem[];
@@ -127,6 +130,8 @@ export interface AgentSessionConfig {
     agent: Agent;
     sessionManager: SessionManager;
     settings: Settings;
+    /** Whether the caller explicitly requested yolo/auto-approve behavior for this session. */
+    autoApprove?: boolean;
     /** Models to cycle through with Ctrl+P (from --models flag) */
     scopedModels?: Array<{
         model: Model;
@@ -212,8 +217,8 @@ export interface AgentSessionConfig {
     asyncJobManager?: AsyncJobManager;
     /** Agent identity (registry id like "Main" or "Alice") used for IRC routing. */
     agentId?: string;
-    /** Shared agent registry (for forwarding IRC observations to the main session UI). */
-    agentRegistry?: AgentRegistry;
+    /** Whether this session is the top-level agent or a subagent. Defaults to "main". */
+    agentKind?: "main" | "sub";
     /**
      * Override the provider-facing session ID for all API requests from this session.
      * When absent, `sessionManager.getSessionId()` is used. Needed when benchmark or
@@ -294,8 +299,16 @@ export interface SessionStats {
     premiumRequests: number;
     cost: number;
 }
-export declare const ANTHROPIC_TOOL_CALL_BATCH_CAP = 4;
-export declare function resolveToolCallBatchCapForModel(model: Model | undefined): number | undefined;
+export interface FreshSessionResult {
+    previousSessionId: string;
+    sessionId: string;
+    closedProviderSessions: number;
+}
+/** Entry returned by {@link AgentSession.clearQueue} / {@link AgentSession.popLastQueuedMessage}. */
+export type RestoredQueuedMessage = {
+    text: string;
+    images?: ImageContent[];
+};
 export declare class AgentSession {
     #private;
     readonly agent: Agent;
@@ -308,6 +321,8 @@ export declare class AgentSession {
     constructor(config: AgentSessionConfig);
     /** Model registry for API key resolution and model discovery */
     get modelRegistry(): ModelRegistry;
+    get asyncJobManager(): AsyncJobManager | undefined;
+    getAgentId(): string | undefined;
     /** Advance the tool-choice queue and return the next directive for the upcoming LLM call. */
     nextToolChoice(): ToolChoice | undefined;
     /**
@@ -330,6 +345,8 @@ export declare class AgentSession {
     getMnemopiSessionState(): MnemopiSessionState | undefined;
     /** TTSR manager for time-traveling stream rules */
     get ttsrManager(): TtsrManager | undefined;
+    /** Secret obfuscator, when secrets are configured; /share redaction reuses it. */
+    get obfuscator(): SecretObfuscator | undefined;
     /** Whether a TTSR abort is pending (stream was aborted to inject rules) */
     get isTtsrAbortPending(): boolean;
     /** Whether the plan-mode → compaction transition's expected internal abort is
@@ -344,16 +361,6 @@ export declare class AgentSession {
     /** Unconditionally clear the silent-abort flag. Idempotent: safe when the
      *  flag was never set OR was already consumed by `#handleAgentEvent`. */
     clearPlanCompactAbortPending(): void;
-    /** Register a compact display string for a custom message that the caller is
-     *  about to dispatch via `promptCustomMessage` / `sendCustomMessage`.
-     *  Returns a stable tag the caller MUST embed in
-     *  `CustomMessage.details.__pendingDisplayTag` so the agent-side
-     *  `message_start` handler can remove the matching display entry when the
-     *  queued message is consumed.
-     *
-     *  Does NOT push to the agent's steering/followUp queue — that happens
-     *  separately inside `sendCustomMessage`. */
-    enqueueCustomMessageDisplay(text: string, mode: "steer" | "followUp"): string;
     getAsyncJobSnapshot(options?: {
         recentLimit?: number;
     }): AsyncJobSnapshot | null;
@@ -373,11 +380,26 @@ export declare class AgentSession {
      * Multiple listeners can be added. Returns unsubscribe function for this listener.
      */
     subscribe(listener: AgentSessionEventListener): () => void;
+    subscribeCommandMetadataChanged(listener: CommandMetadataChangedListener): () => void;
+    /** True once dispose() has begun; deferred background work (e.g. the deferred
+     *  MCP discovery task in sdk.ts) must not touch the session past this point. */
+    get isDisposed(): boolean;
+    /**
+     * Synchronously mark the session as disposing so new work is rejected
+     * immediately: Python/eval starts throw, queued asides are dropped, and the
+     * aside provider is detached. Idempotent; `dispose()` runs it first.
+     *
+     * Wrappers that await other teardown before delegating to `dispose()` MUST
+     * call this before their first await — otherwise work started in that async
+     * gap slips past the disposal guards.
+     */
+    beginDispose(): void;
     /**
      * Remove all listeners, flush pending writes, and disconnect from agent.
      * Call this when completely done with the session.
      */
     dispose(): Promise<void>;
+    freshSession(): FreshSessionResult | undefined;
     /** Full agent state */
     get state(): AgentState;
     /** Current model (may be undefined if not yet selected) */
@@ -393,6 +415,7 @@ export declare class AgentSession {
     get serviceTier(): ServiceTier | undefined;
     /** Whether agent is currently streaming a response */
     get isStreaming(): boolean;
+    get isAborting(): boolean;
     /** Wait until streaming and deferred recovery work are fully settled. */
     waitForIdle(): Promise<void>;
     drainAsyncJobDeliveriesForAcp(options?: {
@@ -420,6 +443,14 @@ export declare class AgentSession {
      */
     getAllToolNames(): string[];
     isMCPDiscoveryEnabled(): boolean;
+    /**
+     * Flip MCP discovery on after deferred discovery learns the real tool count.
+     * UI sessions resolve `tools.discoveryMode: "auto"` before MCP servers
+     * connect, so a large MCP toolset discovered later must be able to upgrade
+     * the session from the force-activate path to the discovery path. One-way:
+     * discovery is never downgraded mid-session.
+     */
+    enableMCPDiscovery(): void;
     getSelectedMCPToolNames(): string[];
     activateDiscoveredMCPTools(toolNames: string[]): Promise<string[]>;
     isToolDiscoveryEnabled(): boolean;
@@ -475,6 +506,13 @@ export declare class AgentSession {
     /** All messages including custom types like BashExecutionMessage */
     get messages(): AgentMessage[];
     buildDisplaySessionContext(): SessionContext;
+    /**
+     * Full-history transcript for TUI display: every path entry in
+     * chronological order with compactions rendered inline at the point they
+     * fired (instead of replacing prior history). Display-only — NEVER feed
+     * the result to `agent.replaceMessages` or a provider.
+     */
+    buildTranscriptSessionContext(): SessionContext;
     /** Convert session messages using the same pre-LLM pipeline as the active session. */
     convertMessagesToLlm(messages: AgentMessage[], signal?: AbortSignal): Promise<Message[]>;
     /** Apply session-level stream hooks to a direct side request. */
@@ -531,6 +569,8 @@ export declare class AgentSession {
     setSlashCommands(slashCommands: FileSlashCommand[]): void;
     /** Custom commands (TypeScript slash commands and MCP prompts) */
     get customCommands(): ReadonlyArray<LoadedCustomCommand>;
+    /** MCP prompt commands only, for command-list metadata. */
+    get mcpPromptCommands(): ReadonlyArray<LoadedCustomCommand>;
     /** Update the MCP prompt commands list. Called when server prompts are (re)loaded. */
     setMCPPromptCommands(commands: LoadedCustomCommand[]): void;
     /**
@@ -542,8 +582,17 @@ export declare class AgentSession {
      * @throws Error if streaming and no streamingBehavior specified
      * @throws Error if no model selected or no API key available (when not streaming)
      */
-    prompt(text: string, options?: PromptOptions): Promise<void>;
-    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice">): Promise<void>;
+    /**
+     * Returns `false` when the command was fully handled locally (extension or
+     * custom-TS command consumed without calling the LLM). Returns `true` when
+     * the prompt was forwarded to the agent — either directly or queued as a
+     * steer/follow-up. Callers that render a UI or manage turn lifecycle (e.g.
+     * the ACP agent) use this to know whether to expect an `agent_end` event.
+     */
+    prompt(text: string, options?: PromptOptions): Promise<boolean>;
+    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice"> & {
+        queueChipText?: string;
+    }): Promise<void>;
     /**
      * Queue a steering message to interrupt the agent mid-run.
      */
@@ -560,11 +609,15 @@ export declare class AgentSession {
      * - Streaming: queue as steer/follow-up or store for next turn
      * - Not streaming + triggerTurn: appends to state/session, starts new turn unless the client cannot own it
      * - Not streaming + no trigger: appends to state/session, no turn
+     *
+     * @returns true iff this call synchronously started a new turn (awaited
+     * `agent.prompt`); false when the message was queued/appended without a turn.
      */
     sendCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: {
         triggerTurn?: boolean;
         deliverAs?: "steer" | "followUp" | "nextTurn";
-    }): Promise<void>;
+        queueChipText?: string;
+    }): Promise<boolean>;
     /**
      * Send a user message to the agent.
      * When deliverAs is set, queue the message instead of starting a new turn.
@@ -575,20 +628,13 @@ export declare class AgentSession {
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
     }): Promise<void>;
-    /**
-     * Clear queued messages and return them.
-     * Useful for restoring to editor when user aborts.
-     */
+    /** Clear queued messages and return them (text plus any attached images). */
     clearQueue(): {
-        steering: string[];
-        followUp: string[];
+        steering: RestoredQueuedMessage[];
+        followUp: RestoredQueuedMessage[];
     };
-    /** Number of pending messages (includes steering, follow-up, and next-turn messages) */
+    /** Number of pending displayable messages (includes steering, follow-up, and next-turn messages) */
     get queuedMessageCount(): number;
-    /** Get pending messages (read-only). Returns the public text-only view;
-     *  internal `{text, tag?}` records are mapped to `.text` so callers
-     *  (`updatePendingMessagesDisplay`, `restoreQueuedMessagesToEditor`) see
-     *  the unchanged historical shape. */
     getQueuedMessages(): {
         steering: readonly string[];
         followUp: readonly string[];
@@ -596,10 +642,8 @@ export declare class AgentSession {
     /**
      * Pop the last queued message (steering first, then follow-up).
      * Used by dequeue keybinding to restore messages to editor one at a time.
-     * Returns the popped entry's `.text`; the tag (if any) dies with the
-     * record — no orphan state can outlive the queue entry.
      */
-    popLastQueuedMessage(): string | undefined;
+    popLastQueuedMessage(): RestoredQueuedMessage | undefined;
     get skillsSettings(): SkillsSettings | undefined;
     /** Skills loaded by SDK (empty if --no-skills or skills: [] was passed) */
     get skills(): readonly Skill[];
@@ -609,9 +653,15 @@ export declare class AgentSession {
     setTodoPhases(phases: TodoPhase[]): void;
     /**
      * Abort current operation and wait for agent to become idle.
+     *
+     * `reason` (e.g. `USER_INTERRUPT_LABEL`) rides the agent's `AbortController`
+     * and surfaces verbatim on the aborted assistant message's `errorMessage`, so
+     * the transcript can distinguish a deliberate user interrupt from an opaque
+     * abort. Omit it for internal/lifecycle aborts.
      */
     abort(options?: {
         goalReason?: "interrupted" | "internal";
+        reason?: string;
     }): Promise<void>;
     /**
      * Start a new session, optionally with initial messages and parent tracking.
@@ -634,7 +684,10 @@ export declare class AgentSession {
     fork(): Promise<boolean>;
     /**
      * Set model directly.
-     * Validates API key and saves to the active session. Persists settings only when requested.
+     * Validates that a credential source is configured (synchronously, without
+     * refreshing OAuth or running command-backed key programs) and saves to the
+     * active session. Persists settings only when requested. The concrete key is
+     * resolved lazily per request, so switching never blocks the event loop.
      * @throws Error if no API key available for the model
      */
     setModel(model: Model, role?: string, options?: {
@@ -644,7 +697,9 @@ export declare class AgentSession {
     }): Promise<void>;
     /**
      * Set model temporarily (for this session only).
-     * Validates API key, saves to session log but NOT to settings.
+     * Validates that a credential source is configured (synchronously, without
+     * refreshing OAuth or running command-backed key programs), saves to session
+     * log but NOT to settings.
      * @throws Error if no API key available for the model
      */
     setModelTemporary(model: Model, thinkingLevel?: ThinkingLevel, options?: {
@@ -681,7 +736,8 @@ export declare class AgentSession {
      */
     cycleRoleModels(roleOrder: readonly string[], direction?: "forward" | "backward"): Promise<RoleModelCycleResult | undefined>;
     /**
-     * Get all available models with valid API keys.
+     * Get all available models with valid API keys, filtered by `enabledModels` when configured.
+     * See {@link filterAvailableModelsByEnabledPatterns} for supported pattern forms and limitations.
      */
     getAvailableModels(): Model[];
     /**
@@ -830,9 +886,11 @@ export declare class AgentSession {
      * @param command The bash command to execute
      * @param onChunk Optional streaming callback for output
      * @param options.excludeFromContext If true, command output won't be sent to LLM (!! prefix)
+     * @param options.useUserShell If true, allow caller to request configured user-shell routing
      */
     executeBash(command: string, onChunk?: (chunk: string) => void, options?: {
         excludeFromContext?: boolean;
+        useUserShell?: boolean;
     }): Promise<BashResult>;
     /**
      * Record a bash execution result in session history.
@@ -879,27 +937,33 @@ export declare class AgentSession {
     /** Whether there are pending Python messages waiting to be flushed */
     get hasPendingPythonMessages(): boolean;
     /**
-     * Generate an ephemeral reply to a background message (e.g. an IRC ping from
-     * another agent) using this session's current model + system prompt + history.
+     * Deliver an IRC message into this session (recipient side; called by the
+     * IrcBus). Emits the `irc_message` session event for UI cards and injects
+     * the rendered message into the model's context as an `irc:incoming`
+     * custom message:
      *
-     * The incoming message is queued for injection into the recipient's persisted
-     * history immediately so timeouts/abort still preserve delivery. The reply is
-     * computed via a side-channel `streamSimple` call (analogous to `/btw`) so it
-     * never blocks on the recipient's in-flight tool calls. When a reply is
-     * generated, it is queued separately. Injection happens immediately when the
-     * session is idle, otherwise it is deferred until streaming ends.
-     */
-    respondAsBackground(args: {
-        from: string;
-        message: string;
-        awaitReply?: boolean;
-        signal?: AbortSignal;
-    }): Promise<{
-        replyText: string | null;
-    }>;
+     * - mid-turn → queued on the aside channel and folded in at the next step
+     *   boundary (non-interrupting, like async-result deliveries) → "injected";
+     * - idle → starts a real turn with the message so the recipient wakes
+     *   → "woken".
+     *
+     * Never blocks on the recipient's turn: the wake turn is fire-and-forget.
+     *
+     * When the sender expects a reply (`send await:true`) and this session is
+     * mid-turn with async execution disabled, the next step boundary may be
+     * gated on the sender's own batch finishing (blocking task spawns), so a
+     * real reply turn can never happen in time. In that case an ephemeral
+     * side-channel auto-reply is generated from the current context (the old
+     * `respondAsBackground` path) and sent back over the bus on this agent's
+     * behalf.
+     */
+    deliverIrcMessage(msg: IrcMessage, opts?: {
+        expectsReply?: boolean;
+    }): Promise<"injected" | "woken">;
     /**
      * Emit an IRC relay observation event on this session for UI rendering only.
-     * Does not persist the record to history. Public so other sessions can forward.
+     * Does not persist the record to history. Called by the IrcBus to surface
+     * agent↔agent traffic on the main session.
      */
     emitIrcRelayObservation(record: CustomMessage): void;
     /**
@@ -908,14 +972,13 @@ export declare class AgentSession {
      * does not block on, or interfere with, any in-flight main turn.  The
      * session's history and persisted state are NOT modified by this call.
      *
-     * Used by `respondAsBackground` (IRC) and `BtwController` (`/btw`) to share
+     * Used by `BtwController` (`/btw`) and `OmfgController` (`/omfg`) to share
      * the snapshot + stream pipeline.  The snapshot includes any in-flight
      * streaming assistant text so the model sees the half-finished response
      * rather than missing context.
      */
     runEphemeralTurn(args: {
         promptText: string;
-        images?: ImageContent[];
         onTextDelta?: (delta: string) => void;
         signal?: AbortSignal;
         dedupeReply?: boolean;
@@ -990,6 +1053,19 @@ export declare class AgentSession {
         contextWindow?: number;
     }): ContextUsage | undefined;
     fetchUsageReports(signal?: AbortSignal): Promise<UsageReport[] | null>;
+    /**
+     * Redeem one saved Codex rate-limit reset for a specific account, injecting
+     * the provider base URL like {@link AgentSession.fetchUsageReports}. Powers
+     * the `/usage reset` command and auto-redeem. Never throws for business
+     * outcomes — inspect the returned `code`.
+     */
+    redeemResetCredit(target: ResetCreditTarget, signal?: AbortSignal): Promise<ResetCreditRedeemOutcome>;
+    /**
+     * List saved Codex rate-limit resets per stored account, fetched live from
+     * the dedicated credits endpoint (bypasses the usage cache). Powers the
+     * `/usage reset` account selector.
+     */
+    listResetCredits(signal?: AbortSignal): Promise<ResetCreditAccountStatus[]>;
     /**
      * Export session to HTML.
      * @param outputPath Optional output path (defaults to session directory)
@@ -1015,12 +1091,6 @@ export declare class AgentSession {
      * Includes user messages, assistant text, thinking blocks, tool calls, and tool results.
      */
     formatSessionAsText(): string;
-    /**
-     * Format the conversation as compact context for subagents.
-     * Includes only user messages and assistant text responses.
-     * Excludes: system prompt, tool definitions, tool calls/results, thinking blocks.
-     */
-    formatCompactContext(): string;
     /**
      * Check if extensions have handlers for a specific event type.
      */

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

@@ -10,7 +10,8 @@ export declare class AgentStorage {
     private constructor();
     /**
      * Returns singleton instance for the given database path, creating if needed.
-     * Retries on SQLITE_BUSY with exponential backoff.
+     * 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
      */

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

@@ -9,5 +9,9 @@ export declare function getAuthBrokerTokenFilePath(): string;
  * (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>;

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

@@ -2,5 +2,5 @@
  * Re-exports from @prometheus-ai/ai.
  * All credential storage types and the AuthStorage class now live in the ai package.
  */
-export type { ApiKeyCredential, AuthCredential, AuthCredentialEntry, AuthCredentialStore, AuthStorageData, AuthStorageOptions, OAuthCredential, SerializedAuthStorage, SnapshotResponse, StoredAuthCredential, } from "@prometheus-ai/ai";
+export type { ApiKeyCredential, AuthCredential, AuthCredentialEntry, AuthCredentialStore, AuthStorageData, AuthStorageOptions, CredentialOrigin, CredentialOriginKind, OAuthAccountIdentity, OAuthCredential, ResetCreditAccountStatus, ResetCreditRedeemOutcome, ResetCreditTarget, SerializedAuthStorage, SnapshotResponse, StoredAuthCredential, } from "@prometheus-ai/ai";
 export { AuthBrokerClient, AuthStorage, DEFAULT_SNAPSHOT_CACHE_TTL_MS, REMOTE_REFRESH_SENTINEL, RemoteAuthCredentialStore, readAuthBrokerSnapshotCache, SqliteAuthCredentialStore, writeAuthBrokerSnapshotCache, } from "@prometheus-ai/ai";

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 "@prometheus-ai/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/indexed-session-storage.d.ts

@@ -30,6 +30,7 @@ export declare class IndexedSessionStorage implements SessionStorage {
     readText(path: string): Promise<string>;
     readTextSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
     writeText(path: string, content: string): Promise<void>;
+    writeTextAtomic(path: string, content: string): Promise<void>;
     rename(src: string, dst: string): Promise<void>;
     unlink(path: string): Promise<void>;
     deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
@@ -49,10 +50,9 @@ declare class IndexedSessionStorageWriter implements SessionStorageWriter {
         flags?: "a" | "w";
         onError?: (err: Error) => void;
     });
-    writeLineSync(line: string): void;
-    writeLine(line: string): Promise<void>;
+    append(line: string): Promise<void>;
     flush(): Promise<void>;
-    fsync(): Promise<void>;
+    isOpen(): boolean;
     close(): Promise<void>;
     getError(): Error | undefined;
 }