@gajae-code/coding-agent 0.10.2 → 0.11.1

package/dist/types/{sdk.d.ts → sdk/session.d.ts}

@@ -1,30 +1,30 @@
-import { type AgentTelemetryConfig, type ThinkingLevel } from "@gajae-code/agent-core";
+import { type AgentTelemetryConfig, ThinkingLevel } from "@gajae-code/agent-core";
 import { type AuthCredentialSelector, type Model, type ProviderSessionState } from "@gajae-code/ai";
-import { createAppendOnlyContextManager, providerSupportsAppendOnlyAuto, resolveAppendOnlyMode } from "./append-only-mode";
-import { type Rule } from "./capability/rule";
-import { ModelRegistry } from "./config/model-registry";
-import { type ScopedModelSelection } from "./config/model-resolver";
-import { type PromptTemplate } from "./config/prompt-templates";
-import { Settings, type SkillsSettings } from "./config/settings";
-import type { BashRestrictionProfile } from "./tools/bash-allowed-prefixes";
-import "./discovery";
-import type { CustomCommandsLoadResult } from "./extensibility/custom-commands";
-import type { CustomTool } from "./extensibility/custom-tools/types";
-import { type ExtensionFactory, type ExtensionUIContext, type LoadExtensionsResult, type ToolDefinition } from "./extensibility/extensions";
-import { type ConstrainedPluginHook } from "./extensibility/gjc-plugins/constrained-hooks";
-import { type Skill, type SkillWarning } from "./extensibility/skills";
-import type { FileSlashCommand } from "./extensibility/slash-commands";
-import type { HindsightSessionState } from "./hindsight/state";
-import { type LocalProtocolOptions } from "./internal-urls";
-import { AgentRegistry } from "./registry/agent-registry";
-import { MCPManager } from "./runtime-mcp";
-import { AgentSession, type ForkContextSeed } from "./session/agent-session";
-import { AuthStorage } from "./session/auth-storage";
-import { SessionManager } from "./session/session-manager";
-import { type BuildSystemPromptResult } from "./system-prompt";
-import { BashTool, BUILTIN_TOOLS, createTools, EditTool, EvalTool, FindTool, HIDDEN_TOOLS, type LspStartupServerInfo, loadSshTool, ReadTool, ResolveTool, SearchTool, type Tool, type ToolSession, WebSearchTool, WriteTool } from "./tools";
-import { EventBus } from "./utils/event-bus";
-import { type WorkspaceTree } from "./workspace-tree";
+import { createAppendOnlyContextManager, providerSupportsAppendOnlyAuto, resolveAppendOnlyMode } from "../append-only-mode";
+import { type Rule } from "../capability/rule";
+import { ModelRegistry } from "../config/model-registry";
+import { type ScopedModelSelection } from "../config/model-resolver";
+import { type PromptTemplate } from "../config/prompt-templates";
+import { Settings, type SkillsSettings } from "../config/settings";
+import type { BashRestrictionProfile } from "../tools/bash-allowed-prefixes";
+import "../discovery";
+import type { CustomCommandsLoadResult } from "../extensibility/custom-commands";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+import { type ExtensionFactory, type ExtensionUIContext, type LoadExtensionsResult, type ToolDefinition } from "../extensibility/extensions";
+import { type ConstrainedPluginHook } from "../extensibility/gjc-plugins/constrained-hooks";
+import { type Skill, type SkillWarning } from "../extensibility/skills";
+import type { FileSlashCommand } from "../extensibility/slash-commands";
+import type { HindsightSessionState } from "../hindsight/state";
+import { type LocalProtocolOptions } from "../internal-urls";
+import { AgentRegistry } from "../registry/agent-registry";
+import { MCPManager } from "../runtime-mcp";
+import { AgentSession, type ForkContextSeed } from "../session/agent-session";
+import { AuthStorage } from "../session/auth-storage";
+import { SessionManager } from "../session/session-manager";
+import { type BuildSystemPromptResult } from "../system-prompt";
+import { BashTool, BUILTIN_TOOLS, createTools, EditTool, EvalTool, FindTool, HIDDEN_TOOLS, type LspStartupServerInfo, loadSshTool, ReadTool, ResolveTool, SearchTool, type Tool, type ToolSession, WebSearchTool, WriteTool } from "../tools";
+import { EventBus } from "../utils/event-bus";
+import { type WorkspaceTree } from "../workspace-tree";
 export interface CreateAgentSessionOptions {
     /** Working directory for project-local discovery. Default: getProjectDir() */
     cwd?: string;
@@ -100,8 +100,12 @@ export interface CreateAgentSessionOptions {
     slashCommands?: FileSlashCommand[];
     /** @deprecated MCP runtime discovery is quarantined and ignored. */
     enableMCP?: boolean;
-    /** Existing MCP manager to reuse (skips discovery, propagates to toolSession). */
+    /** Existing MCP manager to reuse (skips discovery, propagates to toolSession).
+     * Mutually exclusive with mcpConfigPath. */
     mcpManager?: MCPManager;
+    /** Load MCP tools for a top-level session only from this caller-owned absolute config file path.
+     * Mutually exclusive with mcpManager. */
+    mcpConfigPath?: string;
     /** Enable LSP integration (tool, formatting, diagnostics, warmup). Default: true */
     enableLsp?: boolean;
     /** Skip Python kernel availability check and prelude warmup */
@@ -144,6 +148,8 @@ export interface CreateAgentSessionOptions {
     settings?: Settings;
     /** Whether UI is available (enables interactive tools like ask). Default: false */
     hasUI?: boolean;
+    /** Whether this host mode can own a notification session endpoint. Default: true. */
+    notificationHostModeSupported?: boolean;
     /**
      * Opt-in OpenTelemetry instrumentation forwarded to the underlying Agent.
      * Passing `{}` enables the loop's GenAI-semantic-convention spans. See
@@ -169,24 +175,24 @@ export interface CreateAgentSessionResult {
     extensionsResult: LoadExtensionsResult;
     /** Update tool UI context (interactive mode) */
     setToolUIContext: (uiContext: ExtensionUIContext, hasUI: boolean) => void;
-    /** MCP manager for server lifecycle management (undefined if MCP disabled) */
+    /** MCP manager for server lifecycle management (undefined if MCP disabled or an exact tools-only config is session-owned) */
     mcpManager?: MCPManager;
     /** Warning if session was restored with a different model than saved */
     modelFallbackMessage?: string;
-    /** LSP servers detected for startup; warmup may continue in the background */
+    /** LSP servers configured for lazy startup in interactive mode */
     lspServers?: LspStartupServerInfo[];
     /** Shared event bus for tool/extension communication */
     eventBus: EventBus;
 }
-export type { PromptTemplate } from "./config/prompt-templates";
-export { Settings, type SkillsSettings } from "./config/settings";
-export type { CustomCommand, CustomCommandFactory } from "./extensibility/custom-commands/types";
-export type { CustomTool, CustomToolFactory } from "./extensibility/custom-tools/types";
-export type * from "./extensibility/extensions";
-export type { Skill } from "./extensibility/skills";
-export type { FileSlashCommand } from "./extensibility/slash-commands";
-export type { Tool } from "./tools";
-export { buildDirectoryTree, buildWorkspaceTree, type DirectoryTree, type WorkspaceTree } from "./workspace-tree";
+export type { PromptTemplate } from "../config/prompt-templates";
+export { Settings, type SkillsSettings } from "../config/settings";
+export type { CustomCommand, CustomCommandFactory } from "../extensibility/custom-commands/types";
+export type { CustomTool, CustomToolFactory } from "../extensibility/custom-tools/types";
+export type * from "../extensibility/extensions";
+export type { Skill } from "../extensibility/skills";
+export type { FileSlashCommand } from "../extensibility/slash-commands";
+export type { Tool } from "../tools";
+export { buildDirectoryTree, buildWorkspaceTree, type DirectoryTree, type WorkspaceTree } from "../workspace-tree";
 export { BashTool, BUILTIN_TOOLS, createTools, EditTool, EvalTool, FindTool, HIDDEN_TOOLS, loadSshTool, ReadTool, ResolveTool, SearchTool, type ToolSession, WebSearchTool, WriteTool, };
 /**
  * Create an AuthStorage instance.

package/dist/types/sdk/startup-capability.d.ts

@@ -0,0 +1,50 @@
+export type SdkStartupPhase = "registration" | "startup";
+export type SdkStartupReason = "disabled" | "ineligible" | "factory_absent" | "runner_absent" | "pending" | "failed";
+export interface SdkStartupFailure {
+    phase: SdkStartupPhase;
+    reason: SdkStartupReason;
+    message: string;
+}
+export type SdkStartupResult = {
+    status: "started";
+} | {
+    status: "failed";
+    failure: SdkStartupFailure;
+};
+/** Internal symbols for lifecycle-only SDK startup construction and bus wiring. */
+export declare const lifecycleStartupCapabilityOption: unique symbol;
+export declare function attachLifecycleStartupCapability(api: object, capability: SdkStartupCapability): void;
+export declare function lifecycleStartupCapabilityForApi(api: object): SdkStartupCapability | undefined;
+export interface SdkStartupRollbackResult {
+    endpointGeneration: number | null;
+    fenced: boolean;
+    runtimeRemoved: boolean;
+    hostStopped: boolean;
+    brokerRegistrationReleased: boolean;
+}
+/** Internal lifecycle-only proof recorder. Fields become true only after their operation completes. */
+export declare class SdkStartupRollbackTracker {
+    #private;
+    get generation(): number | undefined;
+    get result(): SdkStartupRollbackResult;
+    recordGeneration(generation: number): void;
+    recordAbsent(): void;
+    recordStop(generation: number, result: Pick<SdkStartupRollbackResult, "runtimeRemoved" | "hostStopped" | "brokerRegistrationReleased">): void;
+}
+/** Redact untrusted startup errors before they cross the lifecycle boundary. */
+export declare function sanitizeSdkStartupMessage(value: unknown, knownSecrets?: Iterable<unknown>): string;
+/** Convert every lifecycle bootstrap outcome to the public, bounded failure shape. */
+export declare function normalizeSdkStartupFailure(phase: SdkStartupPhase, reason: SdkStartupReason, error?: unknown, knownSecrets?: Iterable<unknown>): SdkStartupFailure;
+/** Session-owned, exactly-once lifecycle bootstrap completion. */
+export declare class SdkStartupCapability {
+    #private;
+    readonly rollback?: SdkStartupRollbackTracker | undefined;
+    get cancelled(): boolean;
+    cancel(): void;
+    constructor(rollback?: SdkStartupRollbackTracker | undefined);
+    normalizeFailure(phase: SdkStartupPhase, reason: SdkStartupReason, error?: unknown): SdkStartupFailure;
+    get result(): SdkStartupResult | undefined;
+    get promise(): Promise<SdkStartupResult>;
+    settleStarted(): SdkStartupResult;
+    settleFailure(failure: SdkStartupFailure): SdkStartupResult;
+}

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

@@ -1,7 +1,7 @@
 /**
  * AgentSession - Core abstraction for agent lifecycle and session management.
  *
- * This class is shared between all run modes (interactive, print, rpc).
+ * This class is shared by interactive, print, ACP, and SDK-hosted session callers.
  * It encapsulates:
  * - Agent state access
  * - Event subscription with automatic session persistence
@@ -12,7 +12,7 @@
  *
  * Modes use this class and add their own I/O layer on top.
  */
-import { type Agent, type AgentEvent, type AgentMessage, type AgentState, type AgentTool, type ResolvedThinkingLevel, type StablePrefixSnapshot, ThinkingLevel } from "@gajae-code/agent-core";
+import { type Agent, type AgentContext, type AgentEvent, type AgentLoopConfig, type AgentMessage, type AgentState, type AgentTool, type MidRunMaintenanceOutcome, type StablePrefixSnapshot, ThinkingLevel } from "@gajae-code/agent-core";
 import { type CompactionResult, type EmergencyCompactionSample } from "@gajae-code/agent-core/compaction";
 import type { AssistantMessage, Effort, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, TextContent, ToolCall, ToolChoice, Usage, UsageReport } from "@gajae-code/ai";
 export interface ForkContextSeedMetadata {
@@ -60,23 +60,26 @@ import type { LoadedCustomCommand } from "../extensibility/custom-commands";
 import type { CustomTool } from "../extensibility/custom-tools/types";
 import type { ExtensionRunner } from "../extensibility/extensions";
 import type { CompactOptions, ContextUsage } from "../extensibility/extensions/types";
-import type { Skill, SkillWarning } from "../extensibility/skills";
+import { type Skill, type SkillWarning } from "../extensibility/skills";
 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 { WorkflowGateEmitter } from "../modes/shared/agent-wire/unattended-session";
+import { type WorkflowGateEmitter } from "../modes/shared/agent-wire/workflow-gate-broker";
 import type { PlanModeState } from "../plan-mode/state";
 import { type AgentRegistry } from "../registry/agent-registry";
 import { type DiscoverableMCPSearchIndex, type DiscoverableMCPTool } from "../runtime-mcp/discoverable-tool-metadata";
 import { 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";
 import type { AskAnswerSource, ToolSession } from "../tools";
 import type { CheckpointState } from "../tools/checkpoint";
 import { type TodoItem, type TodoPhase } from "../tools/todo-write";
 import { type WorkspaceTree } from "../workspace-tree";
-import type { ClientBridge } from "./client-bridge";
+import { type DefaultModelSelectionResult } from "./default-model-selection";
+export { DefaultModelSelectionRecoveryError } from "./default-model-selection";
+import type { ClientBridge, ClientBridgePermissionOption, ClientBridgePermissionOutcome, ClientBridgePermissionToolCall } from "./client-bridge";
 import { type ContributionPrepOptions, type ContributionPrepResult } from "./contribution-prep";
 import { type CustomMessage } from "./messages";
 import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, SessionContext, SessionManager, SessionManagerCloseOutcome } from "./session-manager";
@@ -111,14 +114,16 @@ export type AgentSessionEvent = AgentEvent | {
     attempt: number;
     finalError?: string;
 } | {
-    type: "retry_fallback_applied";
+    type: "model_fallback_switched";
+    eventId: string;
     from: string;
     to: string;
+    reason: string;
     role: string;
-} | {
-    type: "retry_fallback_succeeded";
-    model: string;
-    role: string;
+    scope: string;
+    activeIndex: number;
+    chainLength: number;
+    attemptsUsed: number;
 } | {
     type: "ttsr_triggered";
     rules: Rule[];
@@ -164,6 +169,8 @@ export interface AgentSessionConfig {
     agent: Agent;
     sessionManager: SessionManager;
     settings: Settings;
+    /** Shared Gate-A-eligible notification session controller, when this host supports it. */
+    notificationSessionController?: NotificationSessionController;
     /** Models to cycle through with Alt+N (from --models flag) */
     scopedModels?: ScopedModelSelection[];
     /** Initial session thinking selector. */
@@ -202,7 +209,7 @@ export interface AgentSessionConfig {
     /** Current session message-to-LLM conversion pipeline */
     convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
     /** System prompt builder that can consider tool availability. Returns ordered provider-facing blocks. */
-    rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => Promise<{
+    rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>, candidateModel?: Model) => Promise<{
         systemPrompt: string[];
     }>;
     /** Initial workspace tree snapshot used for the first volatile per-turn context message. */
@@ -268,6 +275,7 @@ export interface AgentSessionConfig {
     /** Optional provider-facing cache identity, distinct from logical session identity. */
     providerCacheSessionId?: string;
 }
+type MidRunMaintenanceLifecycle = Parameters<NonNullable<AgentLoopConfig["maintainContext"]>>[1];
 /** Options for AgentSession.prompt() */
 export interface PromptOptions {
     /** Whether to expand file-based prompt templates (default: true) */
@@ -286,6 +294,11 @@ export interface PromptOptions {
     attribution?: MessageAttribution;
     /** Skip pre-send compaction checks for this prompt (internal use for maintenance flows). */
     skipCompactionCheck?: boolean;
+    /**
+     * Invoked after all prompt preflight checks pass and immediately before agent execution begins.
+     * Cancellation before this callback rejects the prompt.
+     */
+    onPreflightAccepted?: () => void;
 }
 /** Result from a handoff operation. */
 export interface HandoffResult {
@@ -303,17 +316,18 @@ export interface ModelCycleResult {
     /** Whether cycling through scoped models (--models flag) or all available */
     isScoped: boolean;
 }
+export type ModelChangeCause = "user-selection" | "profile-activation" | "fallback-switch" | "restore" | "rollback" | "startup-override" | "temporary-operation";
+export type TemporaryModelReason = "plan-mode" | "context-promotion" | "temporary-cycle" | "profile-preview" | "extension-temporary" | "other";
+/** Opaque handle for a non-destructive temporary provider-session scope. */
+export interface TemporaryProviderSessionScope {
+    readonly reason: TemporaryModelReason;
+}
 /** Result from cycleRoleModels() */
 export interface RoleModelCycleResult {
     model: Model;
     thinkingLevel: ThinkingLevel | undefined;
     role: string;
 }
-export interface DefaultModelSelectionResult {
-    readonly provider: string;
-    readonly modelId: string;
-    readonly thinkingLevel: ResolvedThinkingLevel;
-}
 /** Session statistics for /session command */
 export interface SessionStats {
     sessionFile: string | undefined;
@@ -394,6 +408,7 @@ export declare class AgentSession {
     readonly agent: Agent;
     readonly sessionManager: SessionManager;
     readonly settings: Settings;
+    readonly notificationSessionController: NotificationSessionController | undefined;
     readonly taskDepth: number;
     readonly yieldQueue: YieldQueue;
     readonly configWarnings: string[];
@@ -435,6 +450,12 @@ export declare class AgentSession {
     setStandingResolveHandler(handler: ((input: unknown) => Promise<unknown> | unknown) | null): void;
     /** Provider-scoped mutable state store for transport/session caches. */
     get providerSessionState(): Map<string, ProviderSessionState>;
+    /** Suspend provider state without closing it while a temporary model is active. */
+    beginTemporaryProviderSessionScope(reason: TemporaryModelReason): TemporaryProviderSessionScope;
+    /** Restore a temporary scope, unwinding any auto-owned scopes above it. */
+    restoreTemporaryProviderSessionScope(token: TemporaryProviderSessionScope): boolean;
+    /** Promote a temporary scope. The suspended provider state is permanently closed. */
+    commitTemporaryProviderSessionScope(token: TemporaryProviderSessionScope): boolean;
     buildForkContextSeed(options: ForkContextSeedOptions): Promise<ForkContextSeed>;
     getHindsightSessionState(): HindsightSessionState | undefined;
     setHindsightSessionState(state: HindsightSessionState | undefined): HindsightSessionState | undefined;
@@ -567,6 +588,12 @@ export declare class AgentSession {
      * no fold target exists.
      */
     hasForegroundBashBackgroundRequestHandler(): boolean;
+    /** Set the SDK permission policy used by guarded ACP tool execution. */
+    setSdkPermissionMode(mode: "prompt" | "allow" | "deny"): void;
+    /** Current SDK permission policy for guarded ACP tool execution. */
+    get sdkPermissionMode(): "prompt" | "allow" | "deny";
+    /** Register or clear the SDK reverse permission provider for this session. */
+    setSdkPermissionProvider(provider: ((toolCall: ClientBridgePermissionToolCall, options: ClientBridgePermissionOption[], signal?: AbortSignal) => Promise<ClientBridgePermissionOutcome>) | undefined): void;
     /**
      * Ask the active managed foreground bash call to return as a background job.
      * Returns false when no supported foreground tool is currently backgroundable.
@@ -613,10 +640,6 @@ export declare class AgentSession {
      * This allows /mcp add/remove/reauth to take effect without restarting the session.
      */
     refreshMCPTools(mcpTools: CustomTool[]): Promise<void>;
-    /**
-     * Replace RPC host-owned tools and refresh the active tool set before the next model call.
-     */
-    refreshRpcHostTools(rpcTools: AgentTool[]): Promise<void>;
     /**
      * Refresh plugin sub-skill tools after workflow/sub-skill activation or phase changes.
      */
@@ -657,7 +680,25 @@ export declare class AgentSession {
     get scopedModels(): ReadonlyArray<ScopedModelSelection>;
     /** Prompt templates */
     getPlanModeState(): PlanModeState | undefined;
+    /** Live SDK configuration values exposed through the session query surface. */
+    getSdkConfigItems(): Record<string, string>;
     setPlanModeState(state: PlanModeState | undefined): void;
+    invokeSkill(name: string, args?: string): Promise<{
+        name: string;
+        path: string;
+        args?: string;
+        lineCount?: number;
+    }>;
+    setSdkPlanMode(on: boolean): PlanModeState | undefined;
+    operateGoal(op: "create" | "get" | "resume" | "pause" | "complete" | "drop", objective?: string): Promise<unknown>;
+    getTranscript(): Array<{
+        id: string;
+        role: string;
+        textSummary: string;
+        ts: string;
+        body: string;
+    }>;
+    getTranscriptBody(entryId: string): string | undefined;
     getGoalModeState(): GoalModeState | undefined;
     setGoalModeState(state: GoalModeState | undefined): void;
     getWorkflowGateEmitter(): WorkflowGateEmitter | undefined;
@@ -738,6 +779,7 @@ export declare class AgentSession {
      */
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
+        onPreflightAccepted?: () => void;
     }): Promise<void>;
     /**
      * Clear queued messages and return them.
@@ -749,6 +791,12 @@ export declare class AgentSession {
     };
     /** Number of pending messages (includes steering, follow-up, and next-turn messages) */
     get queuedMessageCount(): number;
+    /** Typed pending-message counts per queue (steering, follow-up, next-turn). */
+    get pendingMessageCounts(): {
+        steering: number;
+        followUp: number;
+        nextTurn: number;
+    };
     /** Whether the agent has queued steering messages that a `user_interrupt`
      *  abort would resume into (steer-on-interrupt). Drives the Esc-on-steer UX:
      *  the first Esc consumes the steer and auto-continues, a second Esc aborts. */
@@ -779,6 +827,14 @@ export declare class AgentSession {
     getTodoPhases(): TodoPhase[];
     setTodoPhases(phases: TodoPhase[]): void;
     applyCompactionPostAppendForTests(compactionEntryId: string, firstKeptEntryId: string, fromExtension?: boolean): Promise<CompactionEntry | undefined>;
+    /** Read-only test seam for active mid-run EventStream drain barriers. */
+    get activeMidRunBarrierCountForTests(): number;
+    /** Read-only test seam for active mid-run maintenance invocations. */
+    get activeMidRunMaintenanceCountForTests(): number;
+    /** Test seam: drive the cooperative mid-run maintenance checkpoint directly. */
+    runMidRunMaintenanceForTests(context: AgentContext, lifecycle?: MidRunMaintenanceLifecycle): Promise<MidRunMaintenanceOutcome>;
+    /** Test seam: estimate mid-run context tokens for a given context view. */
+    estimateMidRunContextTokensForTests(messages: readonly AgentMessage[]): number;
     /**
      * Abort current operation and wait for agent to become idle.
      */
@@ -824,9 +880,28 @@ export declare class AgentSession {
     setModel(model: Model, role?: string, options?: {
         selector?: string;
         thinkingLevel?: ThinkingLevel;
+        cause?: ModelChangeCause;
     }): Promise<void>;
     setActiveModelProfile(name: string | undefined): void;
     getActiveModelProfile(): string | undefined;
+    /** Return the persisted configured fallback selectors for a model role. */
+    getConfiguredModelChain(role: string): readonly string[] | undefined;
+    /** Persist the configured fallback selectors for a model role. */
+    setConfiguredModelChain(role: string, entries: readonly string[], origin: string, identity?: string, explicitHead?: boolean): void;
+    /**
+     * Replace only the in-memory default fallback controller. Used when startup
+     * falls through an unavailable persisted chain to the global default, which
+     * must not mutate the persisted configured intent.
+     */
+    setDefaultFallbackRuntimeModel(selector: string): void;
+    /**
+     * 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.
+     */
+    seedDefaultFallbackResolution(activeIndex: number, skips: Array<{
+        selector: string;
+        reason: string;
+    }>): void;
     /**
      * The model selector ("provider/id") that resume restores as the session
      * default — the latest session-log `model_change` with role="default".
@@ -858,7 +933,13 @@ export declare class AgentSession {
      */
     setModelTemporary(model: Model, thinkingLevel?: ThinkingLevel, options?: {
         persistAsSessionDefault?: boolean;
-    }): Promise<void>;
+        cause?: ModelChangeCause;
+        reason?: TemporaryModelReason;
+        providerSessionScope?: TemporaryProviderSessionScope;
+        signal?: AbortSignal;
+    }): Promise<TemporaryProviderSessionScope | void>;
+    /** Set a durable per-session model from a control surface without exposing credential errors. */
+    setModelTemporaryForControl(model: Model, expectedSessionId?: string): Promise<boolean>;
     setDefaultModelSelection(model: Model, thinkingLevel: ThinkingLevel | undefined): Promise<DefaultModelSelectionResult>;
     /**
      * Cycle to next/previous model.
@@ -885,6 +966,17 @@ export declare class AgentSession {
      * Saves the effective metadata-clamped level to the session, and to settings when requested.
      */
     setThinkingLevel(level: ThinkingLevel | undefined, persist?: boolean): void;
+    /**
+     * Set thinking level from a control surface. Global changes are durable or rolled back.
+     */
+    setThinkingLevelForControl(level: ThinkingLevel, persist: boolean): Promise<void>;
+    getThinkingScopeForControl(): "session" | "global config";
+    getThinkingVisibility(): "visible" | "hidden";
+    setThinkingVisibility(visibility: "visible" | "hidden", persist?: boolean): void;
+    /**
+     * Set thinking visibility from a control surface. Global changes are durable or rolled back.
+     */
+    setThinkingVisibilityForControl(visibility: "visible" | "hidden", persist: boolean): Promise<void>;
     /**
      * Cycle to next thinking level.
      * @returns New level, or undefined if model doesn't support thinking
@@ -1190,6 +1282,7 @@ export declare class AgentSession {
         estimateCount: number;
     };
     fetchUsageReports(signal?: AbortSignal): Promise<UsageReport[] | null>;
+    fetchUsageReportsForControl(): Promise<UsageReport[] | null>;
     /**
      * Export session to HTML.
      * @param outputPath Optional output path (defaults to session directory)

package/dist/types/session/default-model-selection.d.ts

@@ -0,0 +1,25 @@
+import type { ResolvedThinkingLevel } from "@gajae-code/agent-core";
+export type DefaultModelSelectionRollbackStage = "durable" | "session" | "live";
+export declare const DEFAULT_MODEL_SELECTION_RECOVERY_MESSAGE = "Default model selection could not be completed after durable selection.";
+export type DefaultModelSelectionRecovery = {
+    readonly message: string;
+    readonly rollback: {
+        readonly disposition: "restored" | "partial" | "unknown";
+        readonly failures: readonly {
+            readonly stage: DefaultModelSelectionRollbackStage;
+            readonly message: string;
+        }[];
+    };
+};
+export interface DefaultModelSelectionResult {
+    readonly provider: string;
+    readonly modelId: string;
+    readonly thinkingLevel: ResolvedThinkingLevel;
+}
+export declare function parseDefaultModelSelectionRecovery(value: unknown): DefaultModelSelectionRecovery | undefined;
+export declare class DefaultModelSelectionRecoveryError extends Error {
+    readonly name = "DefaultModelSelectionRecoveryError";
+    readonly code = "default_model_selection_recovery";
+    readonly recovery: DefaultModelSelectionRecovery;
+    constructor(_message: string, recovery: DefaultModelSelectionRecovery);
+}

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

@@ -0,0 +1,52 @@
+export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "other";
+/** Immutable configured fallback intent. Transient attempt state never belongs here. */
+export interface ConfiguredFallbackChain {
+    role: string;
+    entries: readonly string[];
+    origin: string;
+    identity?: string;
+    explicitHead: boolean;
+}
+export interface FallbackFailure {
+    selector: string;
+    triggerClass: FallbackTriggerClass;
+    reason: string;
+}
+export type FallbackFailureResult = "retry" | "advance" | "exhausted";
+/**
+ * In-memory policy state for one fallback-chain scope. A controller is deliberately
+ * not serializable: configured chain intent is durable, current position is not.
+ */
+export declare class FallbackChainController {
+    #private;
+    readonly chain: ConfiguredFallbackChain;
+    readonly maxAttempts: number;
+    activeIndex: number;
+    attemptsUsed: number;
+    tried: FallbackFailure[];
+    skips: Array<{
+        selector: string;
+        reason: string;
+    }>;
+    exhaustedForTurn: boolean;
+    constructor(chain: ConfiguredFallbackChain, maxAttempts: number);
+    currentSelector(): string | undefined;
+    onResolutionSkip(reason: string): boolean;
+    /** Charge an upstream request at its concrete transport boundary. */
+    onAttemptStarted(): void;
+    /** Start a logically new request without losing its sticky selected entry. */
+    resetAttemptBudget(): void;
+    /** Seed a controller from auth-aware resolution without charging requests. */
+    seedResolution(activeIndex: number, skips: Array<{
+        selector: string;
+        reason: string;
+    }>): void;
+    onAttemptFailure(triggerClass: FallbackTriggerClass, reason: string): FallbackFailureResult;
+    advance(): boolean;
+    isExhausted(): boolean;
+    resetForNewTurn(): void;
+    resetSticky(): void;
+}
+export declare function cappedExponentialWithFullJitter(baseDelayMs: number, maxDelayMs: number, attemptK: number, random?: () => number): number;
+/** Retry-After is intentionally uncapped. */
+export declare function effectiveFallbackDelay(baseDelayMs: number, maxDelayMs: number, attemptK: number, retryAfterMs: number | undefined, random?: () => number): number;