@gajae-code/coding-agent 0.17.2 → 0.17.4

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

@@ -17,6 +17,7 @@ import type { AttemptScope } from "@gajae-code/agent-core/attempt-scope";
 import { type CompactionResult, type EmergencyCompactionSample } from "@gajae-code/agent-core/compaction";
 import type { AssistantMessage, AttemptScopeRef, Effort, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, TextContent, ToolCall, ToolChoice, Usage, UsageReport } from "@gajae-code/ai/core";
 import { type BtwTextExchange } from "./btw-contract";
+import { type SessionWorkLease } from "./session-work-lease";
 export interface ForkContextSeedMetadata {
     sourceSessionId: string;
     parentMessageCount: number;
@@ -96,7 +97,7 @@ import { type AgentRegistry } from "../registry/agent-registry";
 import type { LazyService } from "../runtime/lazy-service";
 import type { NetworkPrewarmRuntime } from "../runtime/network-prewarm-service";
 import type { WorkspaceTreeRuntime } from "../runtime/workspace-tree-service";
-import { MCPManager } from "../runtime-mcp/manager";
+import { type ExactMcpServerControlResult, MCPManager } from "../runtime-mcp/manager";
 import type { NotificationSessionController } from "../sdk/bus/session-control";
 import type { SecretObfuscator } from "../secrets/obfuscator";
 import { type DiscoverableTool, type DiscoverableToolSearchIndex } from "../tool-discovery/tool-index";
@@ -196,6 +197,47 @@ export type AgentSessionEvent = AgentEvent | {
     goal: Goal | null;
     state?: GoalModeState;
 };
+export type QueuedInputDelivery = "steer" | "followUp";
+export type QueuedInputQueuePolicy = "respect-mode" | "sequential";
+export type QueuedInputRemovalReason = "cancelled" | "removed";
+export interface QueuedInputAdmission {
+    submissionId: string;
+    delivery: QueuedInputDelivery;
+    queuePolicy: QueuedInputQueuePolicy;
+}
+export type QueuedInputExecution = {
+    submissionId: string;
+    delivery: QueuedInputDelivery;
+    disposition: "joined-current-run" | "promoted-to-run";
+    attemptScope: AttemptScopeRef;
+} | {
+    submissionId: string;
+    delivery: QueuedInputDelivery;
+    disposition: "removed";
+    reason: QueuedInputRemovalReason;
+};
+export type QueuedInputTerminal = {
+    submissionId: string;
+    delivery: QueuedInputDelivery;
+    disposition: "completed";
+    attemptScope: AttemptScopeRef;
+} | {
+    submissionId: string;
+    delivery: QueuedInputDelivery;
+    disposition: "removed";
+    reason: QueuedInputRemovalReason;
+};
+/**
+ * Lifecycle receipt for one explicitly queued `submitUserMessage` submission.
+ */
+export interface QueuedInputSubmission {
+    readonly submissionId: string;
+    readonly admitted: Promise<QueuedInputAdmission>;
+    readonly execution: Promise<QueuedInputExecution>;
+    readonly terminal: Promise<QueuedInputTerminal>;
+    /** Remove the submission if it is still queued. Returns false after execution or removal. */
+    readonly cancel: () => boolean;
+}
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
 export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime" | "endTime" | "metadata">;
@@ -439,6 +481,30 @@ export interface PromptOptions {
     /** Internal host capability; ordinary package callers cannot construct the branded value. */
     sdkRunCapability?: unknown;
 }
+export interface SendUserMessageOptions {
+    deliverAs?: QueuedInputDelivery;
+    /** Preserve a busy SDK dispatch as queued work across an admission fence. */
+    queuedAtDispatch?: boolean;
+    /** Delivery ordering for a tracked or SDK-queued submission. */
+    queuePolicy?: QueuedInputQueuePolicy;
+    onPreflightAccepted?: () => void;
+    onPreflightAcceptCommit?: () => void | Promise<void>;
+    /** Internal SDK ownership callback. */
+    onQueuedPromoted?: (promotion: {
+        startsOwnRun?: boolean;
+        removed?: boolean;
+    }) => void;
+    /** Internal dispatch disposition used before actual queue consumption. */
+    onDispatchDisposition?: (promotion: {
+        startsOwnRun: boolean;
+    }) => void;
+    preflightSignal?: AbortSignal;
+    sdkRunCapability?: unknown;
+}
+export interface TrackedSendUserMessageOptions extends SendUserMessageOptions {
+    deliverAs: QueuedInputDelivery;
+    trackSubmission: true;
+}
 /** Result from a handoff operation. */
 export interface HandoffResult {
     document: string;
@@ -614,11 +680,58 @@ export declare class StreamingEditFileCache {
     has(path: string): boolean;
     get totalBytes(): number;
 }
+/**
+ * Startup phase of the session-owned exact-config MCP manager.
+ *
+ * `not-started` and `no-servers-declared` are distinguishable only because the
+ * snapshot reads the declared server list from the exact config; the manager
+ * alone reports an empty name list in both cases.
+ */
+export type ExactMcpStartupState = "not-started" | "no-servers-declared" | "in-flight" | "settled";
+/**
+ * Per-server state.
+ *
+ * `unavailable` covers a server the config declares that the manager has no
+ * live record of. A tools-only manager erases a server from its own bookkeeping
+ * when the connection fails, so a failed server and one whose startup has not
+ * reached it are indistinguishable from here; both surface as `unavailable`
+ * rather than being dropped from the table.
+ */
+export type ExactMcpServerState = "connecting" | "connected" | "disconnected" | "unavailable";
+export type ExactMcpServerDisplayState = ExactMcpServerState | "suspended";
+/**
+ * Transport a server is declared with. Taken from the config's own
+ * discriminator, never from a live connection: `getConnection` throws on a
+ * tools-only manager, so the declaration is the only source available here.
+ */
+export type ExactMcpTransport = "stdio" | "http" | "sse" | "unknown";
+export interface ExactMcpServerStatus {
+    readonly name: string;
+    readonly transport: ExactMcpTransport;
+    readonly state: ExactMcpServerDisplayState;
+    readonly toolCount: number;
+}
+/**
+ * Whitelisted status shape for the TUI `/mcp` command. Every field here is
+ * either a server name the operator already supplied or a derived enum/count;
+ * pool keys, endpoints, commands, env, headers, tokens, and raw exception text
+ * have no field to travel in.
+ */
+export interface ExactMcpStatusSnapshot {
+    readonly startup: ExactMcpStartupState;
+    readonly servers: readonly ExactMcpServerStatus[];
+}
+export type ExactMcpControlAction = "suspend" | "resume" | "reconnect";
+export interface ExactMcpControlResult extends ExactMcpServerControlResult {
+    readonly action: ExactMcpControlAction;
+}
 export interface DefaultFallbackRuntimeState {
     chain: ConfiguredFallbackChain;
     controller: FallbackChainRuntimeState;
     exhaustedLastTurn: boolean;
 }
+/** A lost continuation may only settle the emitter/session pair that opened it. */
+export declare function isCurrentWorkflowGateContinuation(currentSessionId: string, expectedSessionId: string, currentEmitter: WorkflowGateEmitter | undefined, expectedEmitter: WorkflowGateEmitter): boolean;
 export declare class AgentSession {
     #private;
     readonly agent: Agent;
@@ -760,7 +873,9 @@ export declare class AgentSession {
      * Remove all listeners, flush pending writes, and disconnect from agent.
      * Call this when completely done with the session.
      */
-    dispose(): Promise<void>;
+    dispose(options?: {
+        sessionShutdownReason?: "detached_idle";
+    }): Promise<void>;
     /** Join the retained teardown owner without allocating another public deadline. */
     awaitDisposeCompletion(): Promise<void>;
     setDisposeTimeoutForTests(timeoutMs: number): void;
@@ -919,6 +1034,21 @@ export declare class AgentSession {
      * Get all configured tool names (built-in via --tools or default, plus custom tools).
      */
     getAllToolNames(): string[];
+    get hasExactMcpControls(): boolean;
+    /**
+     * Exact-config MCP status for the TUI `/mcp` command.
+     *
+     * Returns `undefined` unless this session holds the exact-config capability,
+     * so a session built outside the root interactive entry point cannot read MCP
+     * state through it. Data comes only from the session-owned tools-only manager
+     * and the call never starts a deferred MCP startup or mutates connections.
+     */
+    getExactMcpStatusSnapshot(): Promise<ExactMcpStatusSnapshot | undefined>;
+    /**
+     * Apply one session-local exact-config control. Selection persistence is
+     * deliberately bypassed: suppression is runtime state, not user authority.
+     */
+    controlExactMcpServer(action: ExactMcpControlAction, name: string): Promise<ExactMcpControlResult | undefined>;
     getSelectedMCPToolNames(): string[];
     isToolDiscoveryEnabled(): boolean;
     getDiscoverableTools(filter?: {
@@ -947,7 +1077,11 @@ export declare class AgentSession {
      * Replace MCP tools in the registry and recompute the visible MCP tool set immediately.
      * This allows /mcp add/remove/reauth to take effect without restarting the session.
      */
-    refreshMCPTools(mcpTools: CustomTool[]): Promise<void>;
+    refreshMCPTools(mcpTools: CustomTool[], options?: {
+        selectedMCPToolNames?: string[];
+        activeMCPToolNames?: string[];
+        persistMCPSelection?: boolean;
+    }): Promise<void>;
     /**
      * Refresh plugin sub-skill tools after workflow/sub-skill activation or phase changes.
      */
@@ -963,6 +1097,8 @@ export declare class AgentSession {
      * to avoid racing against the delivery turn.
      */
     get hasPostPromptWork(): boolean;
+    /** The host-liveness lease shared by admission, execution, and recovery work. */
+    get sessionWorkLease(): SessionWorkLease;
     /** Stable resource ownership identifier for the active prompt run. */
     get activePromptHandle(): string | undefined;
     /** All messages including custom types like BashExecutionMessage */
@@ -1107,24 +1243,14 @@ export declare class AgentSession {
      * @param content User message content (string or content array)
      * @param options.deliverAs Delivery mode: "steer" or "followUp"
      */
-    sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
-        deliverAs?: "steer" | "followUp";
-        /** Preserve a busy SDK dispatch as queued work across an admission fence. */
-        queuedAtDispatch?: boolean;
-        onPreflightAccepted?: () => void;
-        onPreflightAcceptCommit?: () => void | Promise<void>;
-        /** Fired when a queued submission (steering or follow-up) is promoted to its own run (SDK ownership correlation). */
-        onQueuedPromoted?: (promotion: {
-            startsOwnRun?: boolean;
-            removed?: boolean;
-        }) => void;
-        /** Internal dispatch disposition used before actual queue consumption. */
-        onDispatchDisposition?: (promotion: {
-            startsOwnRun: boolean;
-        }) => void;
-        preflightSignal?: AbortSignal;
-        sdkRunCapability?: unknown;
-    }): Promise<void>;
+    sendUserMessage(content: string | (TextContent | ImageContent)[], options?: SendUserMessageOptions): Promise<void>;
+    /**
+     * Queue one steer or follow-up and return a stable lifecycle handle for that
+     * exact submission. Unlike `sendUserMessage`, this method resolves when the
+     * queue admission receipt is available; use the returned promises to await
+     * execution and the owning terminal boundary.
+     */
+    submitUserMessage(content: string | (TextContent | ImageContent)[], options: TrackedSendUserMessageOptions): Promise<QueuedInputSubmission>;
     /**
      * Clear queued messages and return them.
      * Useful for restoring to editor when user aborts.
@@ -1257,6 +1383,18 @@ export declare class AgentSession {
     rebindTerminalAbortSteeringSnapshot(token: number): void;
     discardTerminalAbortSteeringSnapshot(token: number): void;
     getTerminalTurnEpoch(): number | undefined;
+    /**
+     * Tool call ids the run resource ledger currently holds for `handle` (#5637).
+     *
+     * The authoritative answer to "is a tool running?": AgentLoop reserves the
+     * `kind: "tool"` lease SYNCHRONOUSLY inside its dispatch loop, before the
+     * tool's `execute` is invoked, and the lease settles when the call really
+     * ends — whereas `tool_execution_start` only reaches an extension after an
+     * asynchronous fanout. Strictly read-only: it takes a snapshot and never
+     * claims, reserves, seals or quarantines. An unknown run reads as empty,
+     * matching `RunResourceLedger.pending`.
+     */
+    pendingToolExecutions(handle: string): readonly string[];
     abortPromptAndWait(handle: string, options: {
         graceMs: number;
         terminal?: {
@@ -1386,6 +1524,15 @@ export declare class AgentSession {
      * must not mutate the persisted configured intent.
      */
     setDefaultFallbackRuntimeModel(selector: string): void;
+    /** Install a runtime-only durable fallback without changing saved session intent. */
+    installRecoveredDefaultFallbackChain(entries: readonly string[], identity: string | undefined, activeIndex: number, skips: Array<{
+        selector: string;
+        reason: string;
+    }>, options?: {
+        emitResolutionEvent?: boolean;
+    }): void;
+    markStartupRecoveryBindingsRequired(): void;
+    hasRecoveredDefaultFallbackChain(): boolean;
     /**
      * Seed default fallback state after guarded auth-aware model resolution skips chain entries.
      * The configured chain's role, origin, and identity are retained by the controller.

package/dist/types/session/fallback-chain-controller.d.ts

@@ -97,15 +97,15 @@ export interface CompactionCandidateFailure {
     readonly model: string;
     readonly message: string;
 }
+export declare function sanitizeCompactionCandidateFailureMessage(message: string): string;
 /**
  * Error for an auto-compaction run whose every candidate failed.
  *
- * The candidate chain starts at the session model and ends on a same-provider
- * largest-context fallback, so surfacing only the final error named a model
- * the user never chose and hid that their own model had already failed the
- * same way. The message leads with the first failure (the one the user can act
- * on), then lists every candidate that was tried with its own error. `cause`
- * is the final error so callers that classify by type keep the same object.
+ * The candidate chain starts at the session model and includes only explicitly
+ * configured role candidates. The message leads with the first failure (the
+ * one the user can act on), then lists every candidate that was tried with its
+ * own error. `cause` is the final error so callers that classify by type keep
+ * the same object.
  */
 export declare function describeCompactionCandidateFailures(failures: readonly CompactionCandidateFailure[], lastError: unknown): Error;
 export declare function effectiveFallbackDelay(baseDelayMs: number, maxDelayMs: number, attemptK: number, random?: () => number): number;

package/dist/types/session/fold-coordinator.d.ts

@@ -35,7 +35,17 @@ import type { AsyncJob, FoldReason } from "../async/job-manager";
  */
 export declare const FOLD_WAKE_MERGE_WINDOW_MS = 800;
 /** The wait kinds that can be folded. `task`/`subagent` awaits are a non-goal. */
-export type FoldWaitKind = "bash-managed" | "client-terminal" | "bash-pty";
+export type FoldWaitKind = "bash-managed" | "client-terminal" | "bash-pty" | "job-await";
+/**
+ * Whether a wait may be picked as the implicit fold target by the chord and
+ * the SDK `bash.background` control. A `job-await` watches jobs that are
+ * already in the background, so "move the foreground bash into a background
+ * job" has nothing to move; it folds only when the `job` tool's own steer
+ * watcher names it explicitly. Keeping it out of implicit targeting also stops
+ * a `job poll` registered after a foreground bash from taking the chord away
+ * from the command the user is actually watching.
+ */
+export declare function isImplicitFoldTarget(adapter: FoldAdapter): boolean;
 /** Outcome of settling the foreground caller. Exactly one party may settle it. */
 export type ForegroundSettleOutcome = "resolved" | "already-settled";
 /**
@@ -178,9 +188,13 @@ export declare class FoldCoordinator {
     constructor(deps: FoldCoordinatorDeps);
     /** Register a foldable wait. The most recently registered wait is the default target. */
     registerParticipant(adapter: FoldAdapter): () => void;
-    /** Whether any wait is currently foldable, for the key-availability gate. */
+    /** Whether any implicitly targetable wait is currently foldable, for the key-availability gate. */
     hasFoldableParticipant(): boolean;
-    /** Deterministic target: newest registration wins, so the chord folds what the user is watching. */
+    /**
+     * Deterministic implicit target: newest implicitly targetable registration
+     * wins, so the chord folds what the user is watching. `job-await` waits are
+     * skipped; they fold only through an explicit adapter.
+     */
     resolveTarget(): FoldAdapter | undefined;
     /**
      * T1. Synchronous prologue then async durability tail.

package/dist/types/session/internal/managed-session-storage.d.ts

@@ -117,12 +117,18 @@ export interface ScrubbedProtocolRemnantReapResult {
  * or detached receipts retained as evidence) are never touched. A proven
  * concurrent disappearance (ENOENT) is benign; all other I/O failures are
  * returned and logged once without aborting scope preparation.
+ *
+ * Stranded replacement staging that aliases its own published destination is
+ * reaped by the same pass. That entry is neither zero-length nor single-link,
+ * so the terminal-remnant filters above can never reach it, yet leaving it in
+ * place bricks resume for the session it aliases.
  */
 export declare function reapScrubbedProtocolRemnantsSync(directory: string, minAgeMs?: number): ScrubbedProtocolRemnantReapResult;
 /**
  * Async twin of {@link reapScrubbedProtocolRemnantsSync} with the same safety
  * filters (terminal remnant prefix, zero-length, single-link, non-symlink,
- * older than the age gate), yielding between bounded batches. Long-lived
+ * older than the age gate, plus stranded staging that aliases its own
+ * published destination), yielding between bounded batches. Long-lived
  * processes reap per-session descendant directories through this path so a
  * legacy oversized directory cannot starve timers or sibling subagents while
  * it is being drained (issue #4394).

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

@@ -658,7 +658,44 @@ export declare const RESUME_TRANSCRIPT_MAX_BYTES: number;
  * source exactly at the advertised limit.
  */
 export declare const BOUNDED_RESUME_TRANSCRIPT_MAX_BYTES: number;
-export declare const SESSION_OVERSIZED_RECOVERY_MESSAGE = "The selected session transcript is too large to resume safely. Use `gjc export <session-file>` to export its content into a new session, or remove/archive it after confirming its content is no longer needed.";
+/**
+ * Recovery actions offered when a live transcript is at or past the managed
+ * per-file cap.
+ *
+ * Constrained three ways, and every command named here satisfies all three:
+ *
+ * 1. **It must exist.** `gjc export <session-file>` was advised for both limits
+ *    and is not a subcommand, so following it literally started a fresh agent
+ *    that read "export" as a prompt while the session stayed unwritable. (The
+ *    root `--export` flag renders HTML and exits; it yields no resumable
+ *    session.)
+ * 2. **It must be reachable on every surface that renders the message.** These
+ *    strings reach ACP/text consumers through `AgentSession`, and the ACP
+ *    registry is filtered to definitions carrying `handle`
+ *    (`slash-commands/acp-builtins.ts`), so a `handleTui`-only command such as
+ *    `/new` is a different dead end rather than a fix.
+ * 3. **It must not drop the retained near-limit entries.** A failed append is
+ *    kept in memory with a full rewrite armed, and a rejected managed rewrite
+ *    likewise retains its resident entries; both messages promise the work
+ *    persists on the next successful write. `/compact` and `/clear` keep the
+ *    manager — and therefore that pending debt — alive; a session switch closes
+ *    the writer without paying it.
+ *
+ * Every near-limit error class MUST interpolate this constant rather than
+ * restate the advice. `SessionNearLimitRewriteError` restated it and thereby
+ * reintroduced `gjc export <session-file>` after #5621 removed it (#5691).
+ *
+ * `session-recovery-guidance.test.ts` pins all three constraints against the
+ * CLI, builtin, and ACP registries, for every near-limit error class.
+ */
+export declare const SESSION_LIMIT_RECOVERY_ACTIONS = "compact the session (`/compact`), or clear its context (`/clear`) if compaction cannot reclaim enough";
+/**
+ * Oversized-resume guidance. This surface is reached *before* a session is
+ * opened, so it deliberately does not reuse {@link SESSION_LIMIT_RECOVERY_ACTIONS}:
+ * an in-session command there would act on whichever session the user resumes
+ * next, never on the transcript that was just rejected.
+ */
+export declare const SESSION_OVERSIZED_RECOVERY_MESSAGE = "The selected session transcript is too large to resume safely. Resume a different session, or remove/archive this transcript after confirming its content is no longer needed.";
 export declare class SessionAppendPersistenceError extends Error {
     readonly phase: SessionAppendPersistenceFailurePhase;
     readonly entryId: string;
@@ -692,6 +729,28 @@ export declare class SessionNearLimitAppendError extends Error {
         entryRetained: boolean;
     });
 }
+/**
+ * Typed near-limit rewrite outcome (follow-up to #4566).
+ *
+ * A managed atomic rewrite (`#writeEntriesAtomicallySync`) whose serialized
+ * transcript crosses the per-file cap cannot be published: the managed store
+ * rejects the bytes with `content_too_large`. Unlike the append path there is
+ * no appended entry here — the whole live transcript is the payload — so this
+ * error carries the rejected rewrite size and the cap instead of append
+ * fields, and every rewrite/flush/close caller can point at compaction or
+ * export as the continuation path.
+ */
+export declare class SessionNearLimitRewriteError extends Error {
+    readonly code: "near_limit_rewrite";
+    /** Serialized transcript size (bytes) rejected by the managed store. */
+    readonly transcriptBytes: number;
+    /** Managed per-file cap in force when the rewrite was rejected. */
+    readonly capBytes: number;
+    constructor(details: {
+        transcriptBytes: number;
+        capBytes: number;
+    });
+}
 export declare class SessionManagedStorageError extends Error {
     readonly code = "managed_storage_unsupported";
     constructor();
@@ -1037,6 +1096,7 @@ export declare const SessionManagerTestHooks: {
     afterForkTranscriptPublished?: () => void | Promise<void>;
     beforeEphemeralArtifactManagerInstall?: (dir: string) => void | Promise<void>;
     beforePersistPatchFence?: (attempt: number) => void;
+    beforeLivePickerStarFence?: () => void;
     beforeStrictMissingCheck?: (filePath: string, storage: SessionStorage) => void;
     beforeManagedResumeAcceptance?: (filePath: string, storage: SessionStorage) => void;
     beforeManagedResumeReturn?: (filePath: string, storage: SessionStorage) => void;
@@ -1421,6 +1481,9 @@ export declare class SessionManager {
     getSessionName(): string | undefined;
     isSessionStarred(): boolean;
     setSessionStarred(starred: boolean): Promise<boolean>;
+    setSessionStarredForPicker(session: SessionInfo, starred: boolean): Promise<void>;
+    /** Update only a picker candidate's metadata, without opening a runtime or publishing a resume breadcrumb. */
+    static setSessionStarredForPicker(session: SessionInfo, starred: boolean, explicitSessionDir?: string): Promise<void>;
     setSessionName(name: string, source?: "auto" | "user"): Promise<boolean>;
     _persist(entry: SessionEntry): void;
     /** Append a configured fallback chain as child of current leaf, then advance leaf. Returns entry id. */

package/dist/types/session/session-work-lease.d.ts

@@ -0,0 +1,14 @@
+/**
+ * One authoritative, reference-counted lease for work that still needs a
+ * session host. Each admitted work state owns one handle and releases that
+ * handle at its terminal boundary; the host only observes whether any handle
+ * remains held.
+ */
+export interface SessionWorkLeaseHandle {
+    release(): void;
+}
+export interface SessionWorkLease {
+    acquire(): SessionWorkLeaseHandle;
+    isHeld(): boolean;
+}
+export declare function createSessionWorkLease(): SessionWorkLease;

package/dist/types/setup/model-onboarding-guidance.d.ts

@@ -1,4 +1,4 @@
-export declare const MODEL_ONBOARDING_API_PROVIDER_COMMAND = "/provider add --compat <openai|anthropic> --provider <id> --base-url <url> --api-key-env <ENV> --model <model>";
+export declare const MODEL_ONBOARDING_API_PROVIDER_COMMAND = "/provider add --compat <openai|anthropic> --provider <id> --base-url <url> --api-key-env <ENV> (--model <model> | --discover)";
 export declare const MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND = "/provider add --preset <id>";
 export declare const MODEL_ONBOARDING_SETUP_COMMAND = "gjc setup provider";
 export declare const MODEL_ONBOARDING_OAUTH_COMMAND = "/provider login [provider-id] or /login [provider-id]";

package/dist/types/setup/provider-onboarding.d.ts

@@ -1,3 +1,4 @@
+import { type AuthStorage } from "@gajae-code/ai/core";
 import { type ModelsConfig, type ProviderDiscovery } from "../config/models-config-schema";
 export type ProviderCompatibility = "openai" | "anthropic";
 export type ProviderSetupApi = "openai-responses" | "openai-completions" | "anthropic-messages";
@@ -11,6 +12,37 @@ export interface ProviderSetupInput {
     models?: string[];
     modelsPath?: string;
     force?: boolean;
+    /**
+     * Opt into live OpenAI `/v1/models` discovery for an OpenAI-compatible
+     * custom provider. Manual `--model` ids may be omitted when set; the
+     * runtime auto-discovers the catalog on refresh and merges it without
+     * duplicates.
+     *
+     * When no manual models are given, setup probes the endpoint before
+     * writing config so an unreachable endpoint, rejected credential, or
+     * empty catalog fails the setup loudly instead of writing a provider
+     * that can never serve a model. There is deliberately no skip flag: the
+     * pre-write probe is the enforcement point, and the wizard's
+     * interactive probe is a preview only (inputs may have changed since).
+     */
+    discover?: boolean;
+    /** Probe override for tests; defaults to the live endpoint probe. */
+    probeDiscovery?: (input: ProviderDiscoveryProbeInput) => Promise<ProviderDiscoveryProbeResult>;
+    /**
+     * Cancel discovery and persistence until the atomic config rename is
+     * invoked. Later cancellation does not undo a committed provider.
+     * Combined with the shared deadline inside the probe; callers that omit
+     * it get deadline-only probe behavior.
+     */
+    discoverySignal?: AbortSignal;
+    /**
+     * Live credential authority for literal-key persistence. Interactive
+     * callers pass the active session registry's AuthStorage so the
+     * subsequent targeted online refresh authenticates from the same
+     * authority that stored the key. When omitted, onboarding falls back
+     * to a short-lived store at the agent DB path (headless/CLI behavior).
+     */
+    authStorage?: ProviderSetupCredentialStore;
 }
 export interface ProviderSetupResult {
     providerId: string;
@@ -21,11 +53,18 @@ export interface ProviderSetupResult {
     modelsPath: string;
     redactedApiKey: string;
     credentialSource: "literal" | "env";
+    /** True when the provider persists a `discovery:` block (live catalog). */
+    discoveryEnabled: boolean;
+    /** The persisted discovery type, when any (e.g. `openai-models-list`). */
+    discoveryType?: string;
     preset?: string;
     presetName?: string;
 }
 type ProviderConfig = NonNullable<NonNullable<ModelsConfig["providers"]>[string]>;
 type ProviderCompatConfig = NonNullable<ProviderConfig["compat"]>;
+type ProviderSetupCredentialStore = Pick<AuthStorage, "set" | "remove" | "exportSnapshot"> & {
+    peekApiKey?: (provider: string) => Promise<string | undefined>;
+};
 interface ProviderPreset {
     id: string;
     aliases: readonly string[];
@@ -54,8 +93,49 @@ export declare function parseProviderCompatibility(value: string): ProviderCompa
 export declare function findProviderPreset(value: string | undefined): ProviderPreset | undefined;
 export declare function formatProviderPresetList(): string;
 export declare function parseModelList(values: readonly string[]): string[];
-export declare function redactSecret(secret: string): string;
+export declare function redactSecret(_secret: string): string;
 export declare function validateModelApi(modelApi: Readonly<Record<string, string>> | undefined, models: readonly string[], presetId: string): void;
 export declare function addApiCompatibleProvider(input: ProviderSetupInput): Promise<ProviderSetupResult>;
+export interface ProviderDiscoveryProbeInput {
+    baseUrl: string;
+    apiKeyEnv?: string;
+    apiKey?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface ProviderDiscoveryProbeResult {
+    models: string[];
+    endpoint: string;
+}
+/**
+ * Probe an OpenAI-compatible `/v1/models` endpoint and return the sorted
+ * model ids. Used by the Add-custom-provider wizard so gateway catalogs
+ * (LiteLLM and friends) do not need manual transcription.
+ *
+ * Credential handling: an `apiKeyEnv` name resolves through the trusted
+ * credential env only (never `cwd/.env`); a literal `apiKey` is used as-is.
+ * Errors name the redacted endpoint only — the key material never appears
+ * in messages, and callers must not log the request headers.
+ */
+export declare function probeOpenAIModelsList(input: ProviderDiscoveryProbeInput): Promise<ProviderDiscoveryProbeResult>;
+export interface DiscoveryCatalogRefresher {
+    refresh(mode: "offline" | "online" | "online-if-uncached", credentialSessionId?: string): Promise<void>;
+    refreshProvider(providerId: string, strategy?: "offline" | "online" | "online-if-uncached", credentialSessionId?: string): Promise<void>;
+    getProviderDiscoveryState(providerId: string): {
+        status: string;
+        error?: string;
+    } | undefined;
+}
+/**
+ * Reload static config offline, then refresh only the newly added discovery
+ * provider online so freshly requested live catalogs are selectable
+ * immediately (including alongside manual models). Preset-managed
+ * discovery is excluded by callers: presets resolve lazily at runtime.
+ * Returns a recovery hint instead of reporting unconditional success when
+ * the live catalog stays unavailable: the config is saved and valid, but
+ * the user needs to know the catalog did not populate and how to recover
+ * (wait for the next refresh, or re-add with explicit `--model` ids).
+ */
+export declare function reloadAndRefreshDiscoveryCatalog(registry: DiscoveryCatalogRefresher, providerId: string, credentialSessionId?: string): Promise<string | null>;
 export declare function formatProviderSetupResult(result: ProviderSetupResult): string;
 export {};