@makaio/framework 1.0.0-dev-1785407933303 → 1.0.0-dev-1786014320559

package/dist/types-ClpEaoAm.d.mts

@@ -0,0 +1,2917 @@
+import { z } from "zod";
+import { DeferredPromise, TimeoutConfig, TrackedTimeoutConfig } from "@makaio/framework/utils";
+import { AuthenticationError, ExtractSubjectPayload, ExtractSubjectResponse, HandlerForSubjectDefinition, ScopedSubjectDefinition, SubjectRecord } from "@makaio/framework/core";
+import { IFilteredBus, IMakaioBus, OnOptions, ScopedBus } from "@makaio/framework/bus";
+import { AIModel, AIReasoningLevel, AIReasoningLevel as AIReasoningLevel$1, AdapterAuthBinding, AdapterAuthConstant, AdapterProviderAuth, AdapterProviderDefinitionContract, AgentSchemas, AgentSubjects, AuthCredentialRef, CacheStrategy, ConnectorTeardownResult, JsonValue, McpRuntimeSessionContext, McpSessionContext, McpToolState, Message, MessageBlock, MessageDeliveryMode, MessageDeliveryMode as MessageDeliveryMode$1, MessageInput, MessageOutcome, NativeForkDirective, ProtocolId, ProviderContext, ReasoningLevelMap as ReasoningLevelMap$1, RequestCorrelationContext, ResolvedProviderAuth, ResponseSchemaDescriptor, SendMessageResultInnerResult, SessionContext, StructuredOutputValidation, SystemPrompt, TeardownEvidence, ToolListItem } from "@makaio/framework/contracts";
+import { ClientExecutionContext } from "@makaio/framework/contracts/client";
+import { SetRequired } from "type-fest";
+
+//#region adapters/core/src/agent/session-tool-ledger.d.ts
+/**
+ * Single tool tracked in the session ledger.
+ * Accumulates injection, discovery, and call history across the session lifetime.
+ */
+interface ToolLedgerEntry {
+  /** Namespaced tool name, e.g. "github__create_issue" */
+  readonly fullName: string;
+  /** Original tool name without server prefix, e.g. "create_issue" */
+  readonly originalName: string;
+  /** MCP server that provides the tool, e.g. "github" */
+  readonly serverName: string;
+  /** Whether the tool is currently in the direct-injection set */
+  injected: boolean;
+  /** Turn number when this tool was last included in the injection set */
+  lastInjectedAtTurn: number | undefined;
+  /** Whether the model has seen this tool via mcp_discover or mcp_call */
+  discovered: boolean;
+  /** Turn number when this tool was first discovered (set once, never overwritten) */
+  firstDiscoveredAtTurn: number | undefined;
+  /** Total number of mcp_call invocations across the session */
+  callCount: number;
+  /** Turn number of the most recent mcp_call invocation */
+  lastCalledAtTurn: number | undefined;
+}
+/**
+ * Narrowed view of McpSessionContext that the ledger needs.
+ * Decouples the ledger from the full session context shape.
+ */
+interface LedgerSessionContext {
+  /** Tools resolved for direct injection in this session */
+  readonly directTools: readonly McpToolState[];
+  /** Tools available for discovery (not direct-injected) */
+  readonly discoverableTools: readonly McpToolState[];
+}
+/**
+ * Public contract for the session-scoped tool ledger.
+ * Tracks injection, discovery, and call state for all MCP tools during a session.
+ */
+interface ISessionToolLedger {
+  /**
+   * Replace the current injection set with the provided list.
+   * Tools not in the new list have their `injected` flag cleared (eviction sweep).
+   * @param tools - The new set of directly-injected tools
+   * @param turnNumber - The current turn number
+   */
+  recordInjection(tools: readonly ToolListItem[], turnNumber: number): void;
+  /**
+   * Record that the model discovered a tool.
+   * Applies first-discovery semantics: `firstDiscoveredAtTurn` is set only once.
+   * @param toolFullName - The namespaced tool name, e.g. "github__create_issue"
+   * @param turnNumber - The current turn number
+   */
+  recordDiscovery(toolFullName: string, turnNumber: number): void;
+  /**
+   * Record one mcp_call invocation for a tool.
+   * Implies discovery: also sets `discovered` and `firstDiscoveredAtTurn` if unset.
+   * @param toolFullName - The namespaced tool name, e.g. "github__create_issue"
+   * @param turnNumber - The current turn number
+   */
+  recordCall(toolFullName: string, turnNumber: number): void;
+  /**
+   * Return all entries where `injected === true`.
+   * @returns Snapshot of currently-injected tool entries
+   */
+  getInjectedTools(): readonly ToolLedgerEntry[];
+  /**
+   * Return the total call count for a tool, or 0 if not tracked.
+   * @param toolFullName - The namespaced tool name
+   * @returns Call count (0 for unknown tools)
+   */
+  getCallCount(toolFullName: string): number;
+  /**
+   * Return a single ledger entry by full name, or undefined if not tracked.
+   * @param toolFullName - The namespaced tool name
+   * @returns The entry, or undefined
+   */
+  getEntry(toolFullName: string): ToolLedgerEntry | undefined;
+  /**
+   * Return all tracked entries regardless of state.
+   * @returns Snapshot of all ledger entries
+   */
+  getAllEntries(): readonly ToolLedgerEntry[];
+  /**
+   * Phase 2 seam: suggest the optimal injection set for the next turn.
+   * Phase 1 pass-through: returns `context.directTools` mapped to ToolListItem format.
+   * @param context - Current session context providing direct and discoverable tools
+   * @param currentTurnNumber - The current turn number (for future scoring heuristics)
+   * @returns Suggested list of tools to inject for the next turn
+   */
+  suggestInjectionSet(context: LedgerSessionContext, currentTurnNumber: number): Promise<readonly ToolListItem[]>;
+}
+/**
+ * Agent-scoped ledger that tracks every MCP tool's injection, discovery, and
+ * call history within a single agent lifecycle.
+ *
+ * One instance is created per agent factory call and discarded when
+ * the agent is torn down. If the adapter switches connectors mid-session
+ * (e.g. model swap), the same ledger is passed to the new connector so
+ * history is preserved across the connector boundary.
+ *
+ * Follows the same plain-class, no-bus pattern as {@link ToolCallTracker}.
+ */
+declare class SessionToolLedger implements ISessionToolLedger {
+  private readonly entries;
+  /**
+   * Upsert an entry for the given full name, creating it if absent.
+   * @param fullName - Namespaced tool name
+   * @returns The existing or newly-created entry (mutable reference)
+   */
+  private upsert;
+  /**
+   * Replace the current injection set with the provided list.
+   * Tools absent from the new list have their `injected` flag cleared (eviction sweep).
+   * @param tools - The new set of directly-injected tools
+   * @param turnNumber - The current turn number
+   */
+  recordInjection(tools: readonly ToolListItem[], turnNumber: number): void;
+  /**
+   * Record that the model discovered a tool.
+   * Applies first-discovery semantics: `firstDiscoveredAtTurn` is only set once.
+   * @param toolFullName - The namespaced tool name, e.g. "github__create_issue"
+   * @param turnNumber - The current turn number
+   */
+  recordDiscovery(toolFullName: string, turnNumber: number): void;
+  /**
+   * Record one mcp_call invocation for a tool.
+   * Implies discovery: also sets `discovered` and `firstDiscoveredAtTurn` if unset.
+   * @param toolFullName - The namespaced tool name, e.g. "github__create_issue"
+   * @param turnNumber - The current turn number
+   */
+  recordCall(toolFullName: string, turnNumber: number): void;
+  /**
+   * Return all entries where `injected === true`.
+   * @returns Snapshot of currently-injected tool entries
+   */
+  getInjectedTools(): readonly ToolLedgerEntry[];
+  /**
+   * Return the total call count for a tool, or 0 if not tracked.
+   * @param toolFullName - The namespaced tool name
+   * @returns Call count (0 for unknown tools)
+   */
+  getCallCount(toolFullName: string): number;
+  /**
+   * Return a single ledger entry by full name, or undefined if not tracked.
+   * @param toolFullName - The namespaced tool name
+   * @returns The entry, or undefined
+   */
+  getEntry(toolFullName: string): ToolLedgerEntry | undefined;
+  /**
+   * Return all tracked entries regardless of state.
+   * @returns Snapshot of all ledger entries
+   */
+  getAllEntries(): readonly ToolLedgerEntry[];
+  /**
+   * Phase 1 pass-through: return `context.directTools` mapped to ToolListItem format.
+   * Phase 2 will replace this with a scoring heuristic that factors in call history
+   * and discovery patterns.
+   * @param context - Current session context providing direct and discoverable tools
+   * @param _currentTurnNumber - The current turn number (reserved for Phase 2 scoring heuristics)
+   * @returns Suggested list of tools to inject for the next turn
+   */
+  suggestInjectionSet(context: LedgerSessionContext, _currentTurnNumber: number): Promise<readonly ToolListItem[]>;
+}
+//#endregion
+//#region node_modules/emittery/index.d.ts
+/**
+Removes an event subscription.
+*/
+type UnsubscribeFunction = () => void;
+//#endregion
+//#region adapters/core/src/message-handle/types.d.ts
+/**
+ * Result of a message operation.
+ */
+type MessageResult = {
+  result?: SendMessageResultInnerResult | null;
+  error?: Error | string;
+  outcome: MessageOutcome; /** Present when outcome='superseded': the messageId that replaced this one */
+  supersededBy?: string; /** Present when outcome='merged': the messageId this was folded into */
+  mergedInto?: string;
+  /**
+   * Structured-output validation result for this turn.
+   * Present only when a {@link ResponseSchemaDescriptor} was active and validation ran.
+   */
+  structuredOutputValidation?: StructuredOutputValidation;
+};
+/**
+ * Lifecycle states for a queued message.
+ */
+type MessageState = 'queued' | 'acknowledged' | 'completed' | 'cancelled';
+/**
+ * Options for sending a message.
+ */
+interface SendMessageOptions {
+  /**
+   * Custom identifier for message tracking (generated if not provided).
+   */
+  messageId?: string;
+  /**
+   * Controls delivery behavior.
+   * @defaultValue 'enqueue'
+   */
+  deliveryMode?: MessageDeliveryMode;
+}
+/**
+ * Options bag used when creating a message handle.
+ *
+ * Passed to {@link MessageHandle} via `AIAgentConnector.createMessageHandle`.
+ */
+interface MessageHandleOptions {
+  /** Optional stable message identifier; autogenerated when omitted. */
+  messageId?: string;
+  /** Optional delivery semantics for queue processing. */
+  deliveryMode?: MessageDeliveryMode;
+  /** Optional prior conversation messages to materialize for the turn. */
+  messageHistory?: Message[];
+  /** Optional per-turn metadata/context payload for prompt materialization. */
+  turnContext?: Record<string, JsonValue>;
+  /** Content-free transport context that must never be added to model input. */
+  requestCorrelation?: RequestCorrelationContext;
+  /** Caller-expressed caching intent for the injected history prefix. */
+  cacheStrategy?: CacheStrategy;
+  /**
+   * Per-turn structured-output schema descriptor.
+   * When set, the agent's structured-output manager validates the terminal
+   * message against this schema before emitting completion events.
+   */
+  responseSchema?: ResponseSchemaDescriptor;
+  /**
+   * Whether this message handle was created for an internal retry turn.
+   * When `true`, the `onMessageSent` callback is suppressed so no
+   * `user_message.sent` event is emitted for the synthetic retry message.
+   */
+  internalRetry?: boolean;
+  /**
+   * Lifecycle turnId from the session orchestrator. Distinct from
+   * `requestCorrelation.turnId` (transport correlation, which may be present
+   * when no lifecycle turn exists): all user_message lifecycle events for the
+   * handle pair by this value.
+   */
+  turnId?: string;
+  /**
+   * Caller decision on provider-native session resume for this dispatch.
+   * When `false`, the session layer must not arm its pending start-time
+   * resume target for the turn this handle drives (see
+   * `ConnectorSendMessageOptions.useNativeResume` for the full contract).
+   */
+  useNativeResume?: boolean;
+}
+/**
+ * Processing state for agent orchestration.
+ */
+type ProcessingState = 'idle' | 'processing_started' | 'turn_started' | 'step_started' | 'step_finished' | 'turn_finished' | 'processing_finished' | 'active' | 'paused';
+//#endregion
+//#region adapters/core/src/utils/normalizeMessageInput.d.ts
+type NormalizedMessageInput = Required<Message> & {
+  blocks: MessageBlock[];
+  message?: string;
+};
+/**
+ * Normalizes various MessageInput formats into a consistent structure with blocks and optional message text.
+ * @param input - The message input to normalize (string or Message object)
+ * @returns Normalized message with role, blocks array, and optional message text
+ */
+declare function normalizeMessageInput(input: MessageInput): NormalizedMessageInput;
+//#endregion
+//#region adapters/core/src/message-handle/message-handle.d.ts
+type CompletionTransform = (result: MessageResult) => MessageResult | Promise<MessageResult>;
+type CompletionObserver = (result: MessageResult) => void;
+type CompletionNotification = (handle: MessageHandle, result: MessageResult) => void | Promise<void>;
+declare class MessageHandle {
+  readonly messageId: string;
+  readonly message: NormalizedMessageInput;
+  readonly deliveryMode: MessageDeliveryMode;
+  /**
+   * Per-turn structured-output schema descriptor.
+   * When present, the agent validates the terminal message against this
+   * schema before resolving completion and emitting terminal events.
+   */
+  readonly responseSchema?: ResponseSchemaDescriptor | undefined;
+  /**
+   * Internal structured-output retry turns must stay hidden from user-message
+   * lifecycle events while still taking precedence over queued user turns.
+   */
+  readonly internalRetry: boolean;
+  /** Content-free transport correlation for provider requests. */
+  readonly requestCorrelation?: RequestCorrelationContext | undefined;
+  /**
+   * Lifecycle turnId from the session orchestrator (`agent.sendMessage.turnId`).
+   * Distinct from `requestCorrelation.turnId`, which is transport correlation
+   * and may be present when no lifecycle turn exists. All user_message
+   * lifecycle events for this handle (sent/acknowledged/completed) pair by
+   * this value.
+   */
+  readonly turnId?: string | undefined;
+  /**
+   * Caller decision on provider-native session resume for this dispatch.
+   * When `false`, the session layer must not arm its pending start-time
+   * resume target for the turn this handle drives (see
+   * `ConnectorSendMessageOptions.useNativeResume` for the full contract).
+   */
+  readonly useNativeResume?: boolean | undefined;
+  protected readonly deferredCompletion: DeferredPromise<MessageResult>;
+  protected readonly deferredAcknowledgement: DeferredPromise<boolean>;
+  state: MessageState;
+  private isAcknowledged;
+  private completionResult;
+  private completionStarted;
+  private readonly completionTransforms;
+  private readonly completionObservers;
+  /** If this message was merged into another, the winner's messageId */
+  mergedInto?: string;
+  /** If this is the merge winner, messageIds that were folded in */
+  mergedFrom?: string[];
+  /** If this message was superseded by replace/immediate, the replacer's messageId */
+  supersededBy?: string;
+  /** Adapter session ID - resolved when processing starts */
+  private readonly deferredAdapterSessionId;
+  private _adapterSessionId?;
+  /** Curated message history from sessionContext (mutable for merge propagation) */
+  private _messageHistory?;
+  /** Shared cache strategy type from contracts keeps handle options and session context aligned. */
+  private _cacheStrategy?;
+  /** Turn-scoped context from PreUserMessage hooks (mutable for merge propagation) */
+  private _turnContext?;
+  constructor(messageId: string, message: NormalizedMessageInput, deliveryMode: MessageDeliveryMode, /** Curated message history from sessionContext */
+
+  messageHistory?: Message[], /** Turn-scoped context from PreUserMessage hooks */
+
+  turnContext?: Record<string, JsonValue>,
+  /**
+   * Per-turn structured-output schema descriptor.
+   * When present, the agent validates the terminal message against this
+   * schema before resolving completion and emitting terminal events.
+   */
+
+  responseSchema?: ResponseSchemaDescriptor | undefined,
+  /**
+   * Internal structured-output retry turns must stay hidden from user-message
+   * lifecycle events while still taking precedence over queued user turns.
+   */
+
+  internalRetry?: boolean, /** Caller-expressed caching intent for the injected history prefix */
+
+  cacheStrategy?: CacheStrategy, /** Content-free transport correlation for provider requests. */
+
+  requestCorrelation?: RequestCorrelationContext | undefined,
+  /**
+   * Lifecycle turnId from the session orchestrator (`agent.sendMessage.turnId`).
+   * Distinct from `requestCorrelation.turnId`, which is transport correlation
+   * and may be present when no lifecycle turn exists. All user_message
+   * lifecycle events for this handle (sent/acknowledged/completed) pair by
+   * this value.
+   */
+
+  turnId?: string | undefined,
+  /**
+   * Caller decision on provider-native session resume for this dispatch.
+   * When `false`, the session layer must not arm its pending start-time
+   * resume target for the turn this handle drives (see
+   * `ConnectorSendMessageOptions.useNativeResume` for the full contract).
+   */
+
+  useNativeResume?: boolean | undefined);
+  /**
+   * Curated message history from sessionContext
+   * @returns The message history array or undefined if not set
+   */
+  get messageHistory(): Message[] | undefined;
+  /** Set messageHistory (used by merge strategies to propagate history) */
+  set messageHistory(value: Message[] | undefined);
+  /**
+   * Caller-expressed caching intent for the injected history prefix
+   * @returns The cache strategy or undefined if not set
+   */
+  get cacheStrategy(): CacheStrategy | undefined;
+  /** Set cacheStrategy (used by merge strategies to propagate) */
+  set cacheStrategy(value: CacheStrategy | undefined);
+  /**
+   * Turn-scoped context from PreUserMessage hooks
+   * @returns The turn context record or undefined if not set
+   */
+  get turnContext(): Record<string, JsonValue> | undefined;
+  /** Set turnContext (used by merge strategies to propagate context) */
+  set turnContext(value: Record<string, JsonValue> | undefined);
+  /**
+   * Get adapter session ID synchronously (undefined if not yet set)
+   * @returns The adapter session ID or undefined if not yet set
+   */
+  get adapterSessionId(): string | undefined;
+  /**
+   * Set adapter session ID (called by connector when processing starts)
+   */
+  set adapterSessionId(value: string | undefined);
+  /**
+   * Wait for adapter session ID to be set
+   * @returns Promise resolving to session ID when processing starts
+   */
+  waitForAdapterSessionId(): Promise<string>;
+  /**
+   * Whether the message was successfully delivered to the provider.
+   *
+   * Returns `true` only when {@link markAcknowledged} was called with
+   * `delivered = true` (the default). Handles that were completed before
+   * dispatch (merged, superseded, rejected) auto-resolve acknowledgment
+   * with `false`, so this getter returns `false` for them.
+   *
+   * Used by {@link MessageLifecycleTracker} to decide whether
+   * `agent.turn.completed` should pair with an earlier `agent.turn.started`.
+   * @returns `true` when the handle was acknowledged as delivered
+   */
+  get wasDelivered(): boolean;
+  get isProcessed(): boolean;
+  getState(): MessageState;
+  /**
+   * Update message state
+   * @param state - New message state
+   */
+  updateState(state: MessageState): void;
+  /**
+   * Cancel a pending message
+   * @returns True if cancelled, false if already submitted/completed
+   */
+  cancel(): Promise<boolean>;
+  /**
+   * Mark message as acknowledged
+   * @param delivered - Whether message was successfully delivered to provider
+   * (e.g. false if immediate message arrived too late)
+   */
+  markAcknowledged(delivered?: boolean): void;
+  /**
+   * Register a transform that canonicalizes the terminal result before
+   * {@link waitForCompletion} resolves.
+   * @param transform - Transform applied to the raw provider completion result
+   */
+  addCompletionTransform(transform: CompletionTransform): void;
+  /**
+   * Register an observer that runs after all completion transforms have
+   * produced the canonical terminal result, but before completion resolves.
+   * @param observer - Observer called with the final completion result
+   */
+  addCompletionObserver(observer: CompletionObserver): void;
+  /**
+   * Mark message turn as completed
+   * @param result - The result message or null if no result available
+   */
+  markCompleted(result: MessageResult): void;
+  /**
+   * Apply registered completion transforms and publish the canonical result.
+   * @param result - Raw provider completion result
+   */
+  private resolveCompletion;
+  /**
+   * Notify registered completion observers without changing terminal outcome.
+   * @param result - Canonical completion result
+   */
+  private notifyCompletionObservers;
+  waitForAcknowledgment(timeoutMs?: number): Promise<boolean>;
+  waitForCompletion(timeoutMs?: number): Promise<MessageResult>;
+}
+/**
+ * Complete a handle while notifying a callback with the transformed final result.
+ *
+ * `markCompleted()` starts async completion transforms before resolving
+ * waiters. Connector/session layers that cache `lastResult` must observe the
+ * final transformed value, not the raw provider result they pass into
+ * `markCompleted()`.
+ * @param handle - Message handle being completed
+ * @param result - Raw provider completion result
+ * @param onComplete - Optional notification callback receiving the final result
+ * @returns Promise that settles after the final-result callback completes
+ */
+declare function markCompletedWithFinalResult(handle: MessageHandle, result: MessageResult, onComplete?: CompletionNotification): Promise<void>;
+//#endregion
+//#region adapters/core/src/connector/agent-connector.d.ts
+type Forbid<T, K extends PropertyKey> = Omit<T, K> & { [P in K]?: never };
+type ForbiddenKeys = 'agentId' | 'adapterId' | 'adapterSessionId' | 'adapterName' | 'sessionId';
+/** Extract Subjects type parameter from a ScopedBus */
+type ExtractScopedBusSubjects<T> = T extends {
+  withFilter: (...args: unknown[]) => IFilteredBus<string, infer S>;
+} ? S : T extends ScopedBus<string, infer S> ? S : SubjectRecord;
+/**
+ * Abstract base class for AI agent implementations.
+ *
+ * Each adapter provides its own message queue implementation (UserMessageQueue).
+ * This base class provides common infrastructure for state management, bus operations,
+ * and error handling.
+ * @typeParam TBus - Scoped bus type for adapter namespace
+ */
+declare abstract class AIAgentConnector<TBus extends ScopedBus<string> = ScopedBus<string>, TConfig extends BaseAgentConnectorConfig<TBus> = BaseAgentConnectorConfig<TBus>> {
+  /** Unique identifier for this agent instance. */
+  protected readonly agentId: string;
+  /** Session ID from the provider (set after connection/start). */
+  adapterSessionId?: string;
+  /** Makaio session ID for cross-session correlation and approval routing. */
+  protected readonly sessionId?: string;
+  /** Currently active message handle waiting for completion. */
+  protected pendingMessageHandle?: MessageHandle;
+  /** Scoped event bus for adapter-specific emission; global bus owns cross-namespace runtime requests. */
+  private readonly scopedBus;
+  protected readonly globalBus: IMakaioBus;
+  /** Filtered event bus for agent-specific (filtered by agentId) message handling. */
+  private readonly filteredBus;
+  /** Optional error handler callback. */
+  protected readonly errorHandler?: (error: Error, terminate: boolean) => void;
+  /** Deferred promise for interrupt coordination. */
+  protected deferredInterrupt: DeferredPromise<void> | undefined;
+  /**
+   * Raw state emitter stays private so subclasses use updateProcessingState()
+   * and the public subscription methods instead of coupling to Emittery internals.
+   */
+  private readonly emittery;
+  /** Current processing state of the agent. */
+  private processingState;
+  /** Adapter identifier shared across instances of the same adapter type. */
+  readonly adapterId: string;
+  /** Resolved timeout configuration with provenance tracking. */
+  protected readonly timeouts: TrackedTimeoutConfig;
+  protected lastResult: MessageResult | null;
+  protected readonly config: TConfig & {
+    adapterId: string;
+  };
+  /** Model used for this agent (subclasses may update when SDK confirms actual model) */
+  model: string;
+  /** ProviderConfig UUID used during agent creation, carried for runtime introspection */
+  providerConfigId?: string;
+  /** Working directory for agent execution */
+  cwd: string;
+  /** Current reasoning effort level, updated by changeReasoningInPlace. */
+  currentReasoningEffort: AIReasoningLevel | undefined;
+  /**
+   * Reasoning levels supported by the current model, forwarded from the config factory.
+   * `undefined` when the model does not declare reasoning support.
+   */
+  supportedReasoningLevels: BaseAgentConnectorConfig['supportedReasoningLevels'];
+  protected readonly env: Record<string, string>;
+  /** Monotonic turn-number bookkeeping for the MCP tool ledger. */
+  private readonly turnNumbers;
+  /** Adapter type name for event identification. */
+  protected readonly adapterName: string;
+  /** Runtime system prompt from start/initialize options. */
+  protected systemPrompt?: SystemPrompt;
+  protected constructor(config: BaseAgentConnectorConfig<TBus> & {
+    adapterId: string;
+  });
+  /**
+   * Get the current processing state of the agent.
+   * @returns The current processing state
+   */
+  getProcessingState(): ProcessingState;
+  /**
+   * Handle pause after rejection or error.
+   * Subclasses should clear pending messages as appropriate.
+   * @param _reason - Reason for pause ('rejection' | 'error'); available for subclass overrides
+   */
+  protected handlePause(_reason: 'rejection' | 'error'): void;
+  /**
+   * Store runtime system prompt for session creation.
+   * Subclasses may override to apply SDK-specific side effects (e.g., Gemini's setSystemInstruction).
+   * @param prompt - System prompt from start/initialize options
+   */
+  protected captureSystemPrompt(prompt: SystemPrompt | undefined): void;
+  /**
+   * Update the agent's processing state.
+   * State transitions trigger events via emittery.
+   * @param state - New processing state
+   */
+  protected updateProcessingState(state: ProcessingState): Promise<void>;
+  /**
+   * Subscribe to processing state changes (idle ↔ processing transitions).
+   * @param handler - Called with `{ isProcessing: boolean }` on each state change
+   * @returns Unsubscribe function
+   */
+  onProcessingStateChanged(handler: (payload: EmitteryEvents['processingStateChanged']) => Promise<void> | void): UnsubscribeFunction;
+  /**
+   * Wait for a single processing state change matching an optional predicate.
+   * @param predicate - Optional filter, e.g., `(e) => !e.isProcessing` for idle
+   * @returns Promise resolving to `{ isProcessing: boolean }`
+   */
+  onceProcessingStateChanged(predicate?: (eventData: EmitteryEvents['processingStateChanged']) => boolean): Promise<ProcessingState>;
+  /**
+   * Initialize the connector's SDK session without sending a message.
+   * Must set adapterSessionId before returning.
+   * Called by createAgent for idle agent setup.
+   * Implementations MUST be idempotent (no-op if already initialized).
+   * @param options - Optional start options (e.g., systemPrompt for Claude)
+   */
+  abstract initialize(options?: ConnectorStartOptions): Promise<void>;
+  /**
+   * Start agent with initial message.
+   * @param message - Normalized user message (role and content)
+   * @param options - Optional start options (e.g., delivery mode)
+   * @returns Session ID, agent ID, and message handle for tracking
+   */
+  abstract start(message: NormalizedMessageInput, options?: ConnectorStartOptions): Promise<AgentStartResult>;
+  /**
+   * Send a message to the agent.
+   * For initial message, use start() instead.
+   * @param message - Normalized message content
+   * @param options - Send options (e.g., delivery mode, message ID)
+   * @returns Message handle for tracking
+   */
+  abstract sendMessage(message: NormalizedMessageInput, options?: ConnectorSendMessageOptions): Promise<MessageHandle>;
+  /**
+   * Abort the agent and cleanup resources (panic mode).
+   * Triggers AbortController which may cause provider errors.
+   * Use close() for graceful shutdown instead.
+   */
+  abstract abort(): void;
+  /**
+   * Tear this connector down and report what was observed; unlike `abort()` this
+   * triggers no AbortController errors. **Return the class you can prove** — `TeardownEvidenceSchema` says what each
+   * asserts, and only *local* evidence counts: a third-party `dispose`, a wrapper type or the absence of a thrown
+   * error prove no provider-side end. Unobservable ⇒ `detached` with a `detail`;
+   * an unaccounted failed stage ⇒ `unknown`, named. Throwing also means `unknown`.
+   * @returns What this runtime observed about the end of its resources
+   */
+  abstract close(): Promise<ConnectorTeardownResult>;
+  /**
+   * Get session ID, waiting for provider to generate it if not yet available.
+   * @returns Session ID from provider
+   */
+  abstract getAdapterSessionId(): Promise<string>;
+  /**
+   * The provider session ID this connector is currently authoritative on, or
+   * `undefined` when it has none. "Confirmed" means safe to report, not echoed
+   * back by the provider: a seeded ID qualifies when the provider adopts it, and
+   * Claude connectors withhold it only while a fork awaits `system.init`. For
+   * "did the provider commit to it" see {@link movesProviderSessionOnSuppressedResume}.
+   * Samplers (payload enrichment, rotation guards) must not read this accessor
+   * directly — resolve through `providerCommittedAdapterSessionId` in
+   * `agent/agent-adapter-session-movement.ts`, which withholds an armed resume
+   * target that an in-flight dispatch may still abandon.
+   * @returns Currently authoritative provider session ID, or `undefined`
+   */
+  getConfirmedAdapterSessionId(): string | undefined;
+  /**
+   * Whether a dispatch that declines native resume would make this connector
+   * abandon its armed resume target for a fresh provider session.
+   * Narrow honesty query for the movement seam (contract in
+   * `agent/agent-adapter-session-movement.ts`): the executor must know before
+   * dispatching so the session row stops advertising the abandoned target.
+   * Default `false`; connectors that rotate must override.
+   * @returns `true` when declining native resume rotates the provider session
+   */
+  movesProviderSessionOnSuppressedResume(): boolean;
+  /**
+   * Complete the agent session by waiting for all messages to finish.
+   * @returns Last message result or null if no messages processed
+   */
+  abstract complete(): Promise<MessageResult | null>;
+  /**
+   * Create a MessageHandle with standard initialization (messageId, adapterSessionId, onMessageSent).
+   * @param message - Normalized user message
+   * @param options - Optional message options (id, delivery mode, history, and turn context)
+   * @returns Initialized MessageHandle instance
+   */
+  protected createMessageHandle(message: NormalizedMessageInput, options?: MessageHandleOptions): MessageHandle;
+  /** Signal MCP tools changed; connectors with direct-inject refresh override this. */
+  markToolRefreshPending(): void;
+  /**
+   * Stage the canonical orchestrator-assigned turn number for consumption by the next
+   * {@link consumeTurnNumber} call. The counter is monotonically increasing.
+   * @param turnNumber - Canonical 1-based turn number from SessionOrchestrator
+   * @throws RangeError when the value is invalid, regresses, or downgrades a staged value
+   */
+  setCanonicalTurnNumber(turnNumber: number): void;
+  /**
+   * Advance to the next turn number, consuming any pending canonical value.
+   * Orchestrator-staged values win; otherwise the local counter increments by one.
+   * @returns The current turn number after advancement
+   */
+  protected consumeTurnNumber(): number;
+  /**
+   * Current turn number (read-only). Use {@link consumeTurnNumber} to advance.
+   * @returns The current turn number
+   */
+  protected get currentTurnNumber(): number;
+  /**
+   * Staged canonical turn number, or `undefined` if none was staged.
+   * @returns The pending canonical turn number
+   */
+  protected get pendingTurnNumber(): number | undefined;
+  /**
+   * Attempt to change the model without a connector swap.
+   * Subclasses override when the SDK supports in-place model changes.
+   * Base implementation returns false (swap required).
+   *
+   * **Mutation contract:** Implementations MUST NOT mutate `this.model` directly.
+   * The caller (AIAgent.handleModelChange) owns the `this.model` field update after
+   * a successful in-place change. Implementations only configure the SDK-internal model
+   * (e.g., `query.setModel()`, `geminiConfig.setModel()`).
+   * @param _newModel - The model identifier to switch to
+   * @returns true if changed in-place, false if swap needed. Exceptions are caught by the
+   * caller and treated as false (automatic swap fallback), so implementations need not guard.
+   */
+  changeModelInPlace(_newModel: string): Promise<boolean>;
+  /**
+   * Attempt to change the working directory without a connector swap.
+   * Subclasses override when the adapter supports in-place cwd changes (e.g., stateless APIs).
+   * Base implementation returns false (swap required).
+   *
+   * **Mutation contract:** Implementations MUST NOT mutate `this.cwd` directly.
+   * The caller (AIAgent.handleCwdChange) owns the `this.cwd` field update after
+   * a successful in-place change. Implementations only update SDK-internal state.
+   * @param _newCwd - The working directory path to switch to
+   * @returns true if changed in-place, false if swap needed. Exceptions are caught by the
+   * caller and treated as false (automatic swap fallback), so implementations need not guard.
+   */
+  changeCwdInPlace(_newCwd: string): Promise<boolean>;
+  /**
+   * Attempt to change reasoning effort without swapping the connector.
+   *
+   * Override in subclasses that support in-place reasoning changes (e.g., adapters
+   * that pass reasoning parameters per-request rather than at session-creation time).
+   * The base implementation returns `false` so callers fall back to a connector swap.
+   *
+   * **Mutation contract:** Implementations MUST NOT mutate `this.currentReasoningEffort`
+   * directly. The caller owns the `currentReasoningEffort` field update after a successful
+   * in-place change. Implementations only configure the SDK-internal reasoning parameter.
+   * @param _newLevel - The new reasoning effort level to apply
+   * @returns `true` if the change was applied in-place, `false` if a connector swap is needed
+   */
+  changeReasoningInPlace(_newLevel: AIReasoningLevel): Promise<boolean>;
+  /**
+   * Interrupt the current message processing.
+   * @returns Promise that resolves when interrupt is handled
+   */
+  abstract interrupt(): Promise<void>;
+  /**
+   * Marks pending message as failed, calls error handler, resolves completion promise.
+   * @param error - Error that occurred
+   * @param terminate - Whether to abort the agent after handling error
+   * @internal
+   */
+  handleError(error: unknown, terminate?: boolean): void;
+  protected handleToolApprovalDenied(abort: 'not_requested' | 'not_supported' | 'handled', details?: string): void;
+  getAgentId(): string;
+  getAdapterName(): string;
+  /**
+   * Get timeout value for a specific category.
+   * @param category - Timeout category (initialization, acknowledgement, completion, toolApproval, eventWait)
+   * @returns Timeout value in milliseconds
+   */
+  getTimeoutMs(category: keyof typeof this.timeouts.values): number;
+  /**
+   * Request tool approval via the scoped bus with auto-injected metadata.
+   *
+   * Wraps `scopedBus.request()` to automatically include connector identity
+   * (adapterName, agentId, adapterId, adapterSessionId) in the payload.
+   * @param subject - Subject definition for the tool approval request
+   * @param payload - Request payload (metadata fields are forbidden and auto-injected)
+   * @returns Promise resolving to the approval response
+   */
+  protected requestToolApproval<TSubject extends ScopedSubjectDefinition<TBus['namespace']>>(subject: TSubject, payload: Forbid<TSubject['$meta']['payload']['request'], ForbiddenKeys>): Promise<TSubject['$meta']['payload']['response']>;
+  /**
+   * Execute a tool approval request with the shared diagnostics wrapper.
+   *
+   * Handles the common `RequestError`/`NoHandlerError` path by logging a helpful
+   * message via `handleError` and re-throwing so callers can decide whether to
+   * surface the failure or fall back to a denial.
+   * @param subject - Scoped subject definition for the tool approval request
+   * @param payload - Payload that must not include adapter metadata
+   * @returns Tool approval response payload
+   */
+  protected requestToolApprovalWithHandling<TSubject extends ScopedSubjectDefinition<TBus['namespace']>>(subject: TSubject, payload: Forbid<TSubject['$meta']['payload']['request'], ForbiddenKeys>): Promise<TSubject['$meta']['payload']['response']>;
+  /**
+   * Emit an event via the scoped bus with auto-injected metadata.
+   *
+   * Wraps `scopedBus.emit()` to automatically include connector identity
+   * (adapterName, agentId, adapterId, adapterSessionId) in the payload.
+   * @param subject - Subject definition for the event
+   * @param payload - Event payload (metadata fields are forbidden and auto-injected)
+   * @returns Promise that resolves when the event is emitted
+   */
+  protected emit<TSubject extends ScopedSubjectDefinition<TBus['namespace']>>(subject: TSubject, payload: Forbid<TSubject['$meta']['payload'], ForbiddenKeys>): Promise<void>;
+  /**
+   * Subscribe to events on the filtered bus (pre-filtered by agentId).
+   *
+   * Uses `filteredBus` which only delivers events matching this connector's agentId.
+   * @param subject - Subject definition to subscribe to
+   * @param handler - Event handler receiving the event context
+   * @param options - Optional subscription options (e.g., priority)
+   * @returns Unsubscribe function
+   */
+  on<Subject extends ScopedSubjectDefinition<TBus['namespace']>>(subject: Subject, handler: HandlerForSubjectDefinition<Subject>, options?: OnOptions): () => void;
+  /**
+   * Wait for a single event on the filtered bus (pre-filtered by agentId).
+   *
+   * Uses `filteredBus` which only delivers events matching this connector's agentId.
+   * @param subject - Subject definition to wait for
+   * @param options - Optional options (e.g., predicate filter, timeout)
+   * @returns Promise resolving to the event context
+   */
+  once<Subject extends ScopedSubjectDefinition<TBus['namespace']>>(subject: Subject, options?: Parameters<IFilteredBus<TBus['namespace'], ExtractScopedBusSubjects<TBus>>['once']>[1]): Promise<never>;
+  protected logLowLevelEvent(_event: unknown): void;
+}
+//#endregion
+//#region adapters/core/src/connector/teardown-timing.d.ts
+/**
+ * Timing budgets a connector may spend *observing* the end of a resource it is
+ * tearing down.
+ *
+ * These are deliberately not general-purpose timeouts. A teardown reports what
+ * it observed, and observing an end takes a bounded amount of wall-clock time;
+ * the budget below is the boundary between "we watched it end" and "we stopped
+ * watching and can no longer claim it ended".
+ * @packageDocumentation
+ */
+/**
+ * Milliseconds a connector may wait for a resource it just terminated to be
+ * observed as terminated.
+ *
+ * Chosen to match the archive and cancel budgets connectors already apply to
+ * provider round-trips, and deliberately far below the adapter-instance close
+ * budget so a single instance close can still contain several agent teardowns.
+ *
+ * The same budget bounds the confirmation a backend has to acquire for itself
+ * when its termination call reports success but publishes no end event: "did
+ * the resource end" is one question whether it is asked of a process, a
+ * connection, or a superseded generation of either.
+ */
+declare const CONNECTOR_EXIT_OBSERVATION_MS = 2000;
+/**
+ * Milliseconds a teardown may wait for a connector replacement it found in
+ * flight to settle.
+ *
+ * **A liveness ceiling, not a correctness boundary.** It exists so a stop is
+ * never *unbounded*, not so it can only fire on a broken replacement: the waited
+ * region contains awaits no adapter budget covers — config resolution, auth
+ * preparation, connector construction, event wiring, account prepare and commit,
+ * the awaited movement announcement, the previous runtime's lease release — so a
+ * replacement that respects every budget it declares can still lose this race.
+ * **Its expiry may hit a perfectly legal replacement, and that is a specified
+ * normal path rather than an anomaly**, which is safe only because expiry hands
+ * both runtimes back to the replacement instead of closing anything.
+ *
+ * The value is therefore a user-visible-latency decision: every consumer of a
+ * teardown waits for it synchronously, including a session close that holds
+ * until its slowest agent teardown finishes and has no request deadline of its
+ * own to clamp against. Ten seconds is the order at which an interface must show
+ * progress rather than appear hung, and it is deliberately **shorter** than a
+ * legal slow replacement's worst case.
+ *
+ * It is **not** ordered against the deadline of whoever is waiting on the
+ * teardown. The two are related per request by a clamp — the effective wait is
+ * the smaller of this ceiling and what remains of that deadline less one
+ * {@link CONNECTOR_EXIT_OBSERVATION_MS} of margin — and the margin is that
+ * constant rather than a new one because the expiry arm closes nothing: all that
+ * remains after it is a status write and the reply.
+ *
+ * Against the other two budgets the ordering runs from smallest to largest:
+ * {@link CONNECTOR_EXIT_OBSERVATION_MS} (one observation), then
+ * `ADAPTER_INSTANCE_CLOSE_TIMEOUT_MS` (an instance close containing several
+ * observations), then this (one user-visible stop). That last step is an
+ * intentional inversion: an instance shutdown overlapping a replacement times out
+ * and reports `unknown`, and inside that window the replacement owns both
+ * runtimes.
+ */
+declare const SWAP_SETTLEMENT_WAIT_MS = 10000;
+//#endregion
+//#region adapters/core/src/connector/teardown-report.d.ts
+/**
+ * A teardown class plus the failure that capped it.
+ *
+ * The wire-facing {@link ConnectorTeardownResult} carries only the class and a
+ * `detail`, because that is all a consumer needs to decide anything. This shape
+ * adds the original failure for the one caller that must **rethrow** it rather
+ * than report it: eviction's rollback consumer builds an aggregate from the
+ * throw, and returning instead of throwing would delete that signal silently.
+ *
+ * Kept as one type across the runtime, agent and registry layers on purpose. The
+ * contract names the registry's copy an *agent* teardown report, but the fields
+ * are identical at all three, and two names for one shape is how the layers
+ * drift apart.
+ */
+interface TeardownReport extends ConnectorTeardownResult {
+  /**
+   * Failure that made this class `unknown`, when there was one.
+   *
+   * Present only alongside `evidence: 'unknown'`. Never inspected to *derive* a
+   * class — the class is derived where the failure happened, and this field only
+   * carries it to a caller whose contract is to rethrow.
+   */
+  readonly closeError?: unknown;
+}
+/**
+ * Report a teardown that could not be attempted or observed at all.
+ * @param detail - Why nothing is known, for diagnostics.
+ * @param closeError - Failure that produced this class, when one exists.
+ * @returns The `unknown` report.
+ */
+declare function unknownTeardown(detail: string, closeError?: unknown): TeardownReport;
+/**
+ * Combine several teardowns of one logical resource set into one report.
+ *
+ * Class and joined `detail` are the contract's {@link aggregateTeardownResults},
+ * not a restatement of it. What this layer adds is the one field the wire shape
+ * does not carry: the first `closeError`, so a rethrowing caller still has a
+ * failure to throw.
+ * @param reports - Reports from the individual teardowns.
+ * @returns One report standing for all of them.
+ */
+declare function aggregateTeardownReports(reports: readonly TeardownReport[]): TeardownReport;
+/**
+ * Await a teardown and rethrow the failure that capped it, if there was one.
+ *
+ * The bridge for the callers whose contract is still a **throw**: a rollback that
+ * aggregates "the operation failed *and* its cleanup failed" learns the second
+ * half from an exception, and the reporting teardowns below it stopped raising
+ * one. Without this the aggregate would silently lose its cleanup arm — a
+ * connector and its lease left behind with nobody told.
+ *
+ * One helper rather than four call-site copies, because the conversion is the same
+ * everywhere and a missing copy is invisible until something leaks.
+ * @param teardown - Teardown whose report carries the failure, if any
+ * @throws The failure that capped the reported class
+ */
+declare function rethrowTeardownFailure(teardown: Promise<TeardownReport>): Promise<void>;
+//#endregion
+//#region adapters/core/src/connector/teardown-observation.d.ts
+/** Inputs for {@link reportObservedExit}. */
+interface ObservedExitOptions {
+  /**
+   * Promise settled by the runtime's own observation of the end.
+   *
+   * Must be the promise the *existing* listener settles, never a second
+   * subscription: two observations of one event are two things to keep in step,
+   * and the second one is always the one that goes stale.
+   */
+  readonly exited: Promise<unknown>;
+  /**
+   * What was signalled, named for the `detail` a non-observation carries.
+   *
+   * Read by a human triaging a `detached` teardown, so it should name the
+   * resource ("the qwen ACP process", "the tmux pane process") rather than
+   * restating the class.
+   */
+  readonly resource: string;
+}
+/**
+ * Wait for an end to be observed, bounded by the observation budget.
+ *
+ * The bound is what makes the wait admissible at all: a teardown that waited
+ * for an exit that never comes would hang every consumer behind it, and a
+ * consumer that hangs is strictly worse off than one told the end was not
+ * observed. So expiry is a normal answer here, not a failure.
+ *
+ * A **rejected** observation counts as no observation. These promises are built
+ * not to reject, but if one does then what failed is the watching, and a failed
+ * watch has seen nothing.
+ * @param exited - Promise settled by the runtime's own end observation.
+ * @param budgetMs - Milliseconds to watch for; defaults to the wave's budget.
+ * @returns Whether the end was observed inside the budget.
+ */
+declare function exitWasObserved(exited: Promise<unknown>, budgetMs?: number): Promise<boolean>;
+/**
+ * Report the class a signalled resource's own end evidence supports.
+ *
+ * `exited` when the end was watched, `detached` when it was not — never
+ * `unknown`, because nothing failed: the signal was sent and the handle is
+ * gone, and the only missing fact is whether the peer finished before the
+ * budget ran out. A `detail` names the resource so the weaker class is
+ * actionable rather than merely honest.
+ *
+ * The budget is {@link CONNECTOR_EXIT_OBSERVATION_MS} and is not an option: "did
+ * the resource end" is one question with one answer time across the wave, and a
+ * per-call override nobody passed would only be a second place for it to differ.
+ * @param options - Observation promise and resource name.
+ * @returns `exited` on an observed end, `detached` with a `detail` otherwise.
+ */
+declare function reportObservedExit(options: ObservedExitOptions): Promise<ConnectorTeardownResult>;
+/**
+ * Report the class available to a teardown that finds one already finished.
+ *
+ * Every connector with a termination guard reaches this: a panic `abort()` ran,
+ * or a first `close()` already reported, and a second caller arrives with no
+ * observation of its own. It may not borrow the first one's — the class a
+ * teardown reports is a statement about what *it* watched — and it may not claim
+ * `released` either, because the handle being gone says nothing about the peer.
+ * `detached` is what is left, and it is the truth: we stopped holding it and
+ * cannot say more.
+ * @returns `detached`, naming the missing observation.
+ */
+declare function reportRepeatTeardown(): ConnectorTeardownResult;
+/**
+ * Render a failure for a diagnostic `detail` without leaking a stack.
+ *
+ * Kept to the message because these `detail`s travel over the bus and end up in
+ * logs a human reads; a stack there buries the one line that identifies the
+ * stage.
+ * @param error - Failure caught by a best-effort teardown stage.
+ * @returns One-line description.
+ */
+declare function describeTeardownFailure(error: unknown): string;
+/**
+ * Name a best-effort stage that failed, for {@link reportBestEffortStages}.
+ *
+ * For the connectors whose guarded region is interleaved with work that must run
+ * regardless — a `finally` that closes a transport, an MCP unregistration behind a
+ * disposal — and which therefore keep their own `try`/`catch` (and its log line)
+ * and only borrow the naming.
+ * @param stage - What was being released.
+ * @param error - Failure the stage produced.
+ * @returns The stage, named for a report.
+ */
+declare function stageFailure(stage: string, error: unknown): string;
+/**
+ * Run one best-effort teardown stage and name it when it fails.
+ *
+ * Several stages release several different things, so the first failure must not
+ * skip the rest — and yet a stage nobody accounted for must not be reported as one
+ * that succeeded. Returning the stage name instead of throwing is what lets a
+ * caller do both: run everything, then decide the class from what went
+ * unaccounted for.
+ * @param stage - What is being released, for the reported `detail`.
+ * @param run - The release call, which may be a no-op when the resource is absent.
+ * @returns The named failure when the stage failed, `undefined` when it did not.
+ */
+declare function runBestEffortStage(stage: string, run: () => Promise<unknown> | undefined): Promise<string | undefined>;
+/**
+ * Report the class a best-effort teardown with unaccounted stages may claim.
+ *
+ * The taxonomy's rule applied to the one case every such teardown shares: a
+ * connector that could not tell whether its own release landed has no business
+ * claiming it watched anything, so the class is `unknown` and *names* the stage —
+ * a bare `unknown` leaves a human unable to tell which of several handles it was.
+ *
+ * `undefined` means every stage was accounted for, which is deliberately **not** a
+ * class: what a fully accounted teardown may claim differs per connector (an
+ * observed process exit, a `released` in-process object, a `detached` SDK handle)
+ * and only the connector knows which. So the caller keeps that decision and this
+ * only takes the branch the four of them shared.
+ * @param subject - The teardown, named for the report ("Copilot close").
+ * @param failures - Stages named by {@link runBestEffortStage} or {@link stageFailure}.
+ * @returns The `unknown` report, or `undefined` when nothing went unaccounted for.
+ */
+declare function reportBestEffortStages(subject: string, failures: readonly string[]): TeardownReport | undefined;
+/**
+ * Weaken a reported class to the weakest of itself and a ceiling.
+ *
+ * A connector sometimes learns *after* computing its class that something it
+ * held was never proven finished — the canonical case being a superseded
+ * resource generation nobody watched end. The class it may claim is then the
+ * weakest of the two facts, which is the wave's single aggregation rule applied
+ * to a set of two rather than a second rule.
+ *
+ * The reason travels with it: a capped class whose `detail` does not say what
+ * capped it is indistinguishable from a resource that was simply slow.
+ * @param result - Class the teardown computed for what it did observe.
+ * @param ceiling - Strongest class the additional fact permits.
+ * @param detail - Why the ceiling applies, appended to any existing `detail`.
+ * @returns The capped class carrying both reasons.
+ */
+declare function capTeardownEvidence(result: ConnectorTeardownResult, ceiling: TeardownEvidence, detail: string): ConnectorTeardownResult;
+//#endregion
+//#region adapters/core/src/connector/generation-retirement.d.ts
+/** One resource generation taken out of service, with the end still to consume. */
+interface SupersededGeneration {
+  /** Monotonic number of this generation within its connector, for diagnostics. */
+  readonly generation: number;
+  /**
+   * The superseded generation's own end observation.
+   *
+   * `undefined` when the generation exposed none — which is itself a
+   * non-observation and is recorded as one, because "we never had a way to look"
+   * and "we looked and saw nothing" put a consumer in the same position.
+   */
+  readonly exited: Promise<unknown> | undefined;
+}
+/**
+ * Records which of a connector's superseded resource generations were never
+ * observed to end.
+ *
+ * One per connector instance. Deliberately generic: I33 binds every connector
+ * that replaces a resource inside itself, including ones that do not exist yet,
+ * and a rule implemented twice is a rule that will hold in one place.
+ */
+declare class GenerationRetirementLedger {
+  private readonly resource;
+  /** Count of generations taken out of service, used to number them. */
+  private supersededCount;
+  /**
+   * Generations whose end is not (yet) proven — retirement pending or given up on.
+   *
+   * A generation enters the moment it is superseded and leaves only when its end
+   * has actually been observed. That is deliberate: a retirement still in flight
+   * is a resource whose end nobody has proven, and a teardown arriving during one
+   * must not be able to claim an observed class in the window before the wait
+   * expires. Pending and abandoned are the same fact to every consumer — "no
+   * proof" — so they are one set rather than two that could disagree.
+   */
+  private readonly unproven;
+  /**
+   * @param resource - What a generation of this resource is, for the `detail`
+   *   an unretired generation puts on every later teardown. Names the thing
+   *   that may still be running ("qwen ACP process"), because that is what a
+   *   human triaging the capped class needs to go looking for.
+   */
+  constructor(resource: string);
+  /**
+   * Take the live generation out of service and hand back what must be consumed.
+   *
+   * Called at the single choke point through which a connector retires a
+   * generation, so the count cannot drift from the replacements that actually
+   * happened. The caller has already signalled the end; this only opens the
+   * bookkeeping for it.
+   *
+   * The generation counts as **unproven from this moment**, not from the moment a
+   * wait for it expires. Between the two a teardown could otherwise arrive and
+   * claim an observed class for a resource nobody had watched end yet.
+   * @param exited - The superseded generation's own end observation, if it has one.
+   * @returns The generation to retire, to pass to {@link retire} or {@link abandon}.
+   */
+  supersede(exited: Promise<unknown> | undefined): SupersededGeneration;
+  /**
+   * Consume a superseded generation's end inside the observation budget.
+   *
+   * The budget is the same constant a connector spends observing its own
+   * termination, because "did the resource end" is one question whether it is
+   * asked of a connector or of a superseded generation of one.
+   *
+   * Expiry does **not** fail the replacement: a stuck predecessor must not block
+   * a live agent, so the rebuild completes and the non-observation is carried in
+   * the class instead.
+   * @param generation - Generation returned by {@link supersede}.
+   * @returns Whether the generation's end was observed and the generation retired.
+   */
+  retire(generation: SupersededGeneration): Promise<boolean>;
+  /**
+   * Record a generation as unretired without waiting for its end.
+   *
+   * The synchronous half of the split: a connector's `abort()` is synchronous by
+   * contract and cannot await anything, so it signals the end and gives up on
+   * observing it. Capping the class is what keeps that from being a hole —
+   * without it, a synchronous retirement would silently claim what an asynchronous
+   * one has to prove.
+   *
+   * A no-op in effect, because {@link supersede} already booked the generation as
+   * unproven. It is kept as an explicit statement of intent: a caller that never
+   * intends to wait says so, rather than leaving the reader to infer it from the
+   * absence of a `retire`.
+   * @param generation - Generation returned by {@link supersede}.
+   */
+  abandon(generation: SupersededGeneration): void;
+  /**
+   * Apply the ceiling every unproven generation puts on a reported class.
+   *
+   * A no-op while every generation's end was observed, so a connector may call it
+   * unconditionally on its way out and no caller has to remember the rule.
+   * @param result - Class the teardown computed for what it did observe.
+   * @returns The class capped at `detached` while a generation's end is unproven.
+   */
+  capReport(result: ConnectorTeardownResult): ConnectorTeardownResult;
+  /**
+   * Name the generations whose end this connector has not observed.
+   * @returns The diagnostic, or `undefined` when every end was observed.
+   */
+  unretiredDetail(): string | undefined;
+}
+//#endregion
+//#region adapters/core/src/connector/base-connector-session.d.ts
+/**
+ * Configuration for a connector session.
+ * @typeParam TBus - Scoped bus type for adapter namespace
+ */
+interface ConnectorSessionConfig<TBus extends ScopedBus<string> = ScopedBus<string>> {
+  bus: TBus;
+  adapterId: string;
+  adapterName: string;
+  cwd: string;
+  model: string;
+  env: Record<string, string>;
+  /** Auth-free environment safe for bus-routable tool and MCP contexts. */
+  contextEnv?: Readonly<Record<string, string>>;
+}
+/**
+ * Interface for turn-like objects that support pause/abort operations.
+ * Allows base session class to work with different turn implementations.
+ */
+interface PausableTurn {
+  pause(): Promise<unknown>;
+}
+/**
+ * Base abstract class for connector session implementations.
+ *
+ * Sessions manage SDK query lifecycle across multiple turns:
+ * - SDK connection management
+ * - Turn creation and coordination
+ * - Session ID management
+ *
+ * Each adapter implements its own session subclass.
+ * @typeParam TConfig - Configuration type extending ConnectorSessionConfig
+ */
+declare abstract class BaseConnectorSession<TConfig extends ConnectorSessionConfig = ConnectorSessionConfig> {
+  protected readonly config: TConfig;
+  protected readonly bus: TConfig['bus'];
+  protected sessionId?: string;
+  protected currentTurn?: PausableTurn;
+  /**
+   * True once `close()` or `abort()` has begun; gates queue processing.
+   *
+   * ## Shutdown vs queue processing invariant
+   *
+   * Once `close()` or `abort()` begins, no new turn may start.
+   * `processQueue` implementations must refuse to dequeue or start turns
+   * when `this.closing` is `true`, and drain all remaining queued handles
+   * with an error outcome so that callers awaiting `waitForCompletion()`
+   * resolve deterministically instead of hanging.
+   *
+   * A dequeued handle that has entered the start-turn path either starts
+   * its turn before `close()` begins, or is completed with the closing
+   * error at every await point where `close()` can interleave. This is
+   * enforced by {@link completeHandleIfClosing}, which rechecks the flag
+   * after each awaited setup step and completes the handle with the same
+   * error contract used by {@link rejectQueuedHandles}.
+   */
+  protected closing: boolean;
+  constructor(config: TConfig);
+  /**
+   * Recheck the shutdown flag after an awaited setup step in the start path.
+   *
+   * When `close()` sets `this.closing` while the subclass start-turn method
+   * is awaiting an async setup step (schema rotation, query creation, MCP
+   * registration, env resolution), the dequeued handle is no longer in the
+   * queue and {@link rejectQueuedHandles} cannot reach it. This helper
+   * completes the handle with the same error contract so callers see a
+   * consistent shutdown outcome.
+   * @param handle - Dequeued message handle currently being set up
+   * @returns `true` when the session is closing and the handle was completed
+   */
+  protected completeHandleIfClosing(handle: MessageHandle): boolean;
+  /**
+   * Abort the session and cleanup resources.
+   * Pauses the current turn if one is active.
+   */
+  abort(): Promise<void>;
+  /**
+   * Send a message to the provider.
+   * Not used - subclasses should implement processQueue instead.
+   * @param _message - Unused message parameter
+   * @param _options - Unused options parameter
+   */
+  sendMessage(_message: unknown, _options?: unknown): Promise<void>;
+  /**
+   * Get the adapter session ID.
+   * @returns The session ID from the provider
+   */
+  getAdapterSessionId(): Promise<string>;
+}
+//#endregion
+//#region adapters/core/src/connector/base-connector-turn.d.ts
+/**
+ * Result of pausing a turn.
+ * @typeParam TState - Turn state type
+ */
+interface PauseResult<TState = string> {
+  /** The state the turn was in before pausing */
+  stateBeforePause: TState;
+  /** Whether the turn had already ended when pause was requested */
+  turnEnded: boolean;
+}
+/**
+ * Base abstract class for connector turn implementations.
+ *
+ * Turns manage the state machine for a single user message:
+ * - State transitions (idle to turn_started to step_started to ...)
+ * - Pause/resume mechanics
+ * - Safe boundary detection for immediate messages
+ * - Message handle delegation (acknowledgment, completion)
+ *
+ * Each adapter implements its own turn subclass with adapter-specific
+ * state handling and SDK integration.
+ * @typeParam TState - Turn state enum type (string union)
+ */
+declare abstract class BaseConnectorTurn<TState extends string = string> {
+  protected state: TState;
+  protected readonly bus: ScopedBus<string>;
+  protected readonly adapterId: string;
+  protected readonly adapterName: string;
+  protected stateChangedCallback?: (oldState: TState, newState: TState) => Promise<void> | void;
+  /**
+   * Active message handle for this turn.
+   * Subclasses must provide this handle for message lifecycle management.
+   */
+  protected abstract activeMessageHandle: MessageHandle;
+  constructor(bus: ScopedBus<string>, adapterId: string, adapterName: string, initialState: TState);
+  /**
+   * Pause the turn at next safe boundary.
+   * @returns Pause result indicating whether turn already ended
+   */
+  abstract pause(): Promise<PauseResult<TState>>;
+  /**
+   * Resume the paused turn with optional additional message.
+   * @param message - Optional message to inject when resuming
+   */
+  abstract resume(message?: unknown): Promise<void>;
+  /**
+   * Check if turn is currently paused.
+   */
+  abstract isPaused(): boolean;
+  /**
+   * Register callback for state changes.
+   * @param cb - Callback to invoke on state transitions
+   */
+  onStateChanged(cb: (oldState: TState, newState: TState) => Promise<void> | void): void;
+  /**
+   * Transition to new state and notify listeners.
+   * Template method for shared state transition pattern.
+   *
+   * NOTE: Subclasses should use their typed namespace subjects for emission.
+   * This is a template - concrete implementation in adapter-specific Turn classes.
+   * @param newState - New state to transition to
+   */
+  protected transitionTo(newState: TState): Promise<void>;
+  /**
+   * Emit state change event - implemented by subclass with typed subjects.
+   * @param oldState - Previous state
+   * @param newState - New state
+   */
+  protected abstract emitStateChange(oldState: TState, newState: TState): Promise<void>;
+  /**
+   * Get current turn state.
+   * @returns Current turn state
+   */
+  getState(): TState;
+  /**
+   * Get the message handle for this turn.
+   * @returns The message handle for this turn
+   */
+  getMessageHandle(): MessageHandle;
+  /**
+   * Mark message handle as acknowledged.
+   */
+  markAcknowledged(): void;
+  /**
+   * Mark message handle as completed.
+   * @param result - The completion result with outcome and optional result/error
+   */
+  markCompleted(result: {
+    outcome: string;
+    result?: unknown;
+    error?: unknown;
+  }): void;
+}
+//#endregion
+//#region adapters/core/src/connector/procedural-connector-turn.d.ts
+/**
+ * Typed subject references for turn lifecycle events.
+ *
+ * Each adapter provides its namespace-specific subjects when constructing
+ * a ProceduralConnectorTurn. The subjects must all accept the same
+ * TurnStateChangedPayload shape.
+ * @typeParam TSubject - The subject definition type for the adapter's bus
+ */
+interface TurnSubjects<TSubject = ScopedSubjectDefinition> {
+  state_changed: TSubject;
+  turn_started: TSubject;
+  step_started: TSubject;
+  step_finished: TSubject;
+  turn_finished: TSubject;
+}
+/**
+ * Standard turn state type for procedural adapters.
+ *
+ * Procedural adapters (Gemini, OpenAI, Copilot) use abort+restart
+ * rather than true pause/resume. Their state machine is:
+ * idle to turn_started to step_started to step_finished to turn_finished
+ */
+type ProceduralTurnState = 'idle' | 'turn_started' | 'step_started' | 'step_finished' | 'turn_finished';
+/**
+ * Configuration for ProceduralConnectorTurn.
+ * @typeParam TBus - Scoped bus type for the adapter
+ * @typeParam TSubject - Subject definition type
+ */
+interface ProceduralTurnConfig<TBus extends ScopedBus<string>, TSubject> {
+  bus: TBus;
+  adapterId: string;
+  adapterName: string;
+  agentId: string;
+  messageHandle: MessageHandle;
+  turnSubjects: TurnSubjects<TSubject>;
+}
+/**
+ * Base turn implementation for procedural adapters (Gemini, OpenAI, Copilot).
+ *
+ * These adapters share an abort+restart pattern rather than true pause/resume.
+ * This class extracts the common state machine, lifecycle methods, and
+ * message handle delegation that was duplicated across all three.
+ *
+ * Subclasses only need to add adapter-specific behavior:
+ * - Gemini: AbortController for SDK cancellation
+ * - OpenAI: AbortController for SDK cancellation
+ * - Copilot: SDK event handling (handleSdkEvent)
+ * @typeParam TState - Turn state type (defaults to ProceduralTurnState)
+ * @typeParam TBus - Scoped bus type for the adapter
+ * @typeParam TSubject - Subject definition type for emit calls
+ */
+declare class ProceduralConnectorTurn<TState extends string = ProceduralTurnState, TBus extends ScopedBus<string> = ScopedBus<string>, TSubject extends ScopedSubjectDefinition = ScopedSubjectDefinition> extends BaseConnectorTurn<TState> {
+  protected activeMessageHandle: MessageHandle;
+  protected readonly connectorBus: TBus;
+  protected readonly agentId: string;
+  protected readonly turnSubjects: TurnSubjects<TSubject>;
+  protected aborted: boolean;
+  constructor(config: ProceduralTurnConfig<TBus, TSubject>, initialState: TState);
+  /**
+   * Emit state change using adapter-provided turn subjects.
+   * @param oldState - Previous state before transition
+   * @param newState - New state after transition
+   */
+  protected emitStateChange(oldState: TState, newState: TState): Promise<void>;
+  /**
+   * Start the turn.
+   */
+  start(): Promise<void>;
+  /**
+   * Transition to step_started (called when first content arrives).
+   * Allows turn_started to step_started AND step_finished to step_started
+   * (for tool recursion).
+   */
+  markStepStarted(): Promise<void>;
+  /**
+   * Transition to step_finished (called after content block completes).
+   */
+  markStepFinished(): Promise<void>;
+  /**
+   * Mark turn as finished.
+   */
+  markTurnFinished(): Promise<void>;
+  /**
+   * Pause (abort) at next opportunity.
+   * Procedural adapters don't support true pause - caller creates a new turn
+   * with merged content instead.
+   * @returns Pause result indicating turn state
+   */
+  pause(): Promise<PauseResult<TState>>;
+  /**
+   * Resume is not supported for procedural adapters - caller creates new turn.
+   * @param _message - Unused
+   * @throws Error always
+   */
+  resume(_message?: unknown): Promise<void>;
+  /**
+   * Check if turn was aborted.
+   * @returns True if turn was aborted
+   */
+  isPaused(): boolean;
+  /**
+   * Check if turn is completed.
+   * @returns True if turn has finished
+   */
+  isCompleted(): boolean;
+  /**
+   * Check if turn can accept immediate message.
+   * True if turn is active (not finished, not aborted).
+   * @returns True if turn can accept an immediate message
+   */
+  canAcceptImmediate(): boolean;
+}
+//#endregion
+//#region adapters/core/src/session/user-message-queue.d.ts
+/**
+ * Simple FIFO queue for user messages with delivery mode support.
+ *
+ * This queue is owned by adapter Connectors and passed to Sessions for processing.
+ *
+ * Delivery modes:
+ * - 'enqueue': Add to end of queue (default); internal retries are prioritized
+ *   ahead of already queued user turns.
+ * - 'replace': Supersede all unacknowledged messages, add to queue
+ * - 'immediate': Handled by Session (abort/restart), not queue
+ *
+ * Design:
+ * - Connector enqueues messages as they arrive
+ * - Session dequeues messages when ready to process
+ * - Peek allows Session to inspect next message without removing
+ */
+declare class UserMessageQueue {
+  private readonly queue;
+  /**
+   * Add message to queue based on delivery mode.
+   * @param handle - Message handle to enqueue
+   */
+  enqueue(handle: MessageHandle): void;
+  /**
+   * Enqueue an internal retry before ordinary queued user turns while preserving
+   * immediate-mode ordering and FIFO ordering among retries.
+   * @param handle - Internal retry handle to enqueue
+   */
+  private enqueueInternalRetry;
+  /**
+   * Remove all superseded messages from queue.
+   */
+  private removeSuperseded;
+  /**
+   * Remove and return first message from queue.
+   * @returns First message or undefined if queue empty
+   */
+  dequeue(): MessageHandle | undefined;
+  /**
+   * Look at first message without removing.
+   * @returns First message or undefined if queue empty
+   */
+  peek(): MessageHandle | undefined;
+  /**
+   * Check if queue is empty.
+   * @returns True if queue has no messages
+   */
+  isEmpty(): boolean;
+  /**
+   * Get current queue size.
+   * @returns Number of messages in queue
+   */
+  size(): number;
+  /**
+   * Clear all messages from queue.
+   */
+  clear(): void;
+  /**
+   * Find the first immediate message in the queue.
+   * @returns First immediate message or undefined
+   */
+  findImmediate(): MessageHandle | undefined;
+  /**
+   * Remove a specific immediate message from the queue.
+   * @param handle - Handle to remove
+   */
+  removeImmediate(handle: MessageHandle): void;
+  /**
+   * Remove and return all enqueued (non-immediate) messages.
+   * Used when immediate arrives to merge their content.
+   * @returns Array of enqueued message handles in FIFO order
+   */
+  drainEnqueued(): MessageHandle[];
+}
+//#endregion
+//#region adapters/core/src/session/process-queue.d.ts
+/**
+ * Canonical error message used when a queued message cannot be processed
+ * because the session has entered the shutdown path.
+ *
+ * Shared between {@link rejectQueuedHandles} (queue drain) and the per-handle
+ * shutdown gate ({@link BaseConnectorSession.completeHandleIfClosing}) so that
+ * callers see a consistent error contract regardless of whether the handle was
+ * still in the queue or had already been dequeued when `close()` interleaved.
+ */
+declare const SESSION_CLOSED_QUEUE_ERROR = "Session closed before queued message could be processed";
+/**
+ * Minimal turn interface required by processQueue orchestration.
+ *
+ * Any turn implementation (Claude, Gemini, OpenAI, Copilot) that exposes
+ * these methods can participate in the shared processQueue flow.
+ */
+interface QueueableTurn {
+  canAcceptImmediate(): boolean;
+  isCompleted(): boolean;
+  getMessageHandle(): MessageHandle;
+  pause(): Promise<PauseResult>;
+}
+/**
+ * Result of processing an immediate message merge.
+ *
+ * Returned by the `extractMergeContent` callback so that adapters
+ * can collect adapter-specific content (e.g., Gemini collects non-text parts).
+ * The `mergedContent` array is always present; `extra` is an opaque bag
+ * for adapter-specific data that flows through to `startNewTurn`.
+ */
+interface MergeResult {
+  /** Text content collected from superseded/merged messages */
+  mergedContent: string[];
+  /** Adapter-specific merge data (e.g., non-text parts for Gemini) */
+  extra?: unknown;
+}
+/**
+ * Callbacks for adapter-specific behavior during queue processing.
+ * @typeParam TExtra - Type of adapter-specific extra merge data
+ */
+interface ProcessQueueCallbacks<TExtra = unknown> {
+  /**
+   * Get the current turn, if any.
+   * @returns The current turn or undefined
+   */
+  getCurrentTurn: () => QueueableTurn | undefined;
+  /**
+   * Extract text content from a message handle for merge.
+   * Default: `handle.message.message as string`
+   * @param handle - The message handle to extract content from
+   * @returns The text content
+   */
+  extractContent?: (handle: MessageHandle) => string;
+  /**
+   * Called after merge content is collected from superseded/enqueued messages.
+   * Allows adapters to collect additional content (e.g., Gemini's non-text parts).
+   *
+   * If not provided, only text content is collected using `extractContent`.
+   * @param currentHandle - The in-flight message handle being superseded (or undefined)
+   * @param enqueuedHandles - The enqueued handles being merged
+   * @returns Extra merge data to pass through to startNewTurn
+   */
+  collectMergeExtra?: (currentHandle: MessageHandle | undefined, enqueuedHandles: MessageHandle[]) => TExtra;
+  /**
+   * Hook called after merge is collected but before starting the new turn.
+   * Used by Claude to create a fresh query instance.
+   */
+  onBeforeImmediateTurn?: () => Promise<void>;
+  /**
+   * Start a new turn with the given message and optional merge data.
+   *
+   * Returns `void` (or `undefined`) when the turn was started normally.
+   * Returns `false` explicitly when the turn was **not** started (e.g.,
+   * shutdown interleaved during setup and the handle was completed with
+   * an error). `processQueueMessages` propagates this so callers see an
+   * accurate "no turn started" result and can transition to idle.
+   * @param handle - The message handle to process
+   * @param mergedContent - Text content from superseded/merged messages
+   * @param extra - Adapter-specific extra merge data
+   * @returns `false` when the turn was skipped; `void` otherwise
+   */
+  startNewTurn: (handle: MessageHandle, mergedContent?: string[], extra?: TExtra) => Promise<void | false>;
+}
+/**
+ * Shared processQueue orchestration for all session implementations.
+ *
+ * Handles the complete immediate-mode flow:
+ * 1. Detect immediate message while a turn is active
+ * 2. Pause the active turn
+ * 3. Supersede the in-flight message and drain enqueued messages
+ * 4. Collect merged content from all superseded/merged messages
+ * 5. Start a new turn with the immediate message and merged context
+ *
+ * Also handles the normal queue flow:
+ * - Late immediate rejection (immediate arrives after turn finishes)
+ * - Normal enqueue/replace message processing
+ *
+ * Returns `true` when a new turn was started, `false` otherwise.
+ * Callers can use this to decide whether to transition to idle when
+ * the queue drains without starting a new turn (e.g., all-rejection case).
+ * @param queue - The user message queue to process
+ * @param callbacks - Adapter-specific callbacks
+ * @returns True if a new turn was started, false otherwise
+ * @typeParam TExtra - Type of adapter-specific extra merge data
+ */
+declare function processQueueMessages<TExtra = unknown>(queue: UserMessageQueue, callbacks: ProcessQueueCallbacks<TExtra>): Promise<boolean>;
+/**
+ * Drain all remaining handles from the queue and complete each with an error
+ * outcome so callers awaiting `waitForCompletion()` resolve deterministically.
+ *
+ * Used by session implementations during shutdown to prevent queued messages
+ * from hanging indefinitely when the session refuses to start new turns.
+ * @param queue - User message queue to drain
+ * @param message - Error message to attach to each rejected handle
+ */
+declare function rejectQueuedHandles(queue: UserMessageQueue, message?: string): void;
+//#endregion
+//#region adapters/core/src/connector/procedural-agent-connector.d.ts
+/**
+ * Minimal session interface required by ProceduralAgentConnector.
+ *
+ * Any session implementation (OpenAI, Copilot, Gemini) that exposes
+ * these methods can be used with ProceduralAgentConnector's default
+ * wireSessionEvents / processUserMessages / acceptsImmediate.
+ */
+interface ProceduralConnectorSession {
+  /** Process messages from the queue. */
+  processQueue(queue: UserMessageQueue): Promise<void>;
+  /** Get the current turn for state inspection. */
+  getCurrentTurn(): QueueableTurn | undefined;
+}
+/**
+ * Turn subject references for wireSessionEvents.
+ *
+ * Each adapter provides its namespace-specific subjects. The subjects
+ * must accept TurnStateChangedPayload (or compatible shape).
+ * @typeParam TNamespace - The bus namespace string for subject typing
+ */
+interface WireSessionSubjects<TNamespace extends string = string> {
+  turn_started: ScopedSubjectDefinition<TNamespace>;
+  step_started: ScopedSubjectDefinition<TNamespace>;
+  step_finished: ScopedSubjectDefinition<TNamespace>;
+  turn_finished: ScopedSubjectDefinition<TNamespace>;
+}
+/**
+ * Configuration for ProceduralAgentConnector's wireSessionEvents behavior.
+ *
+ * The `onTurnStarted` and `onTurnFinished` hooks allow adapters to inject
+ * logic at turn boundaries. By default both are no-ops.
+ */
+interface WireSessionConfig {
+  /**
+   * Called when a new turn starts (turn_started bus event).
+   *
+   * Executes before the default `updateProcessingState('turn_started')` so
+   * the connector state machine is always updated regardless of this hook.
+   *
+   * Supports async so that turn-start operations with I/O — such as a pending
+   * MCP tool refresh via the bus — can complete before the API call is made.
+   * In-memory operations (recordInjection, consumeTurnNumber) are not affected
+   * by the async signature.
+   */
+  onTurnStarted?: () => Promise<void> | void;
+  /**
+   * Custom handler for turn_finished events.
+   *
+   * When provided, replaces the default turn_finished behavior entirely.
+   * The handler receives a callback to process the queue, which it should
+   * call when the message is considered complete and the queue should drain.
+   * @param drainQueue - Callback that processes the queue or goes idle
+   */
+  onTurnFinished?: (drainQueue: () => Promise<void>) => Promise<void>;
+}
+/**
+ * Abstract base class for procedural (non-event-driven) agent connectors.
+ *
+ * Procedural adapters (OpenAI, Copilot, Gemini) share common patterns:
+ * - wireSessionEvents: subscribe to turn lifecycle events and update processing state
+ * - processUserMessages: initialize session, enqueue, transition to active, process queue
+ * - complete: poll processing state until idle/paused
+ * - start: delegate to sendMessage and return AgentStartResult
+ * - acceptsImmediate: delegate to session's current turn
+ *
+ * Subclasses must implement:
+ * - `getSession()` / `ensureSession()` for session access and lazy initialization
+ * - `getSessionQueue()` for the adapter's UserMessageQueue instance
+ * - `getTurnSubjects()` for namespace-specific turn subjects
+ * - `sendMessage()`, `abort()`, `close()`, `interrupt()`, `getAdapterSessionId()`
+ *
+ * Subclasses may override:
+ * - `getWireSessionConfig()` for custom turn_finished behavior (e.g., Copilot multi-turn)
+ * @typeParam TBus - Scoped bus type for adapter namespace
+ * @typeParam TConfig - Configuration type extending BaseAgentConnectorConfig
+ */
+declare abstract class ProceduralAgentConnector<TBus extends ScopedBus<string> = ScopedBus<string>, TConfig extends BaseAgentConnectorConfig<TBus> = BaseAgentConnectorConfig<TBus>> extends AIAgentConnector<TBus, TConfig> {
+  /** Whether turn event wiring has been setup. */
+  private turnEventsWired;
+  /**
+   * Terminal lifecycle latch. Once a connector starts closing, initialization
+   * that resumes later must not install fresh turn handlers.
+   */
+  private turnEventLifecycleClosed;
+  /**
+   * Unsubscribe functions for the turn subscriptions {@link wireSessionEvents}
+   * installed.
+   *
+   * Held here, at the wiring, because that is the only place that knows what was
+   * subscribed. A subclass owns *when* its connector ends; it cannot own the
+   * undoing of subscriptions it never registered — and every connector on this base
+   * needs them undone, whatever class its teardown reports: a subscription outliving
+   * its connector keeps that connector reachable from the bus, so a later generation
+   * on the same agent id delivers turn events into an object that already closed.
+   */
+  private turnEventCleanups;
+  /** Turn handlers that already started and must settle before provider teardown. */
+  private activeTurnEventHandlers;
+  /**
+   * Get the adapter's session instance (may be undefined if not yet initialized).
+   * @returns The session or undefined
+   */
+  protected abstract getSession(): ProceduralConnectorSession | undefined;
+  /**
+   * Initialize and return the adapter's session.
+   * Must be idempotent (no-op if already initialized).
+   * @returns The initialized session
+   */
+  protected abstract ensureSession(): Promise<ProceduralConnectorSession>;
+  /**
+   * Get the adapter's UserMessageQueue instance.
+   * @returns The message queue
+   */
+  protected abstract getSessionQueue(): UserMessageQueue;
+  /**
+   * Get the adapter's namespace-specific turn subjects for wireSessionEvents.
+   * @returns Turn subject definitions
+   */
+  protected abstract getTurnSubjects(): WireSessionSubjects<TBus['namespace']>;
+  /**
+   * Get optional wire session configuration for custom turn_finished behavior.
+   * Override in subclasses that need non-standard turn_finished handling
+   * (e.g., Copilot multi-turn message completion).
+   * @returns Wire session configuration, or undefined for default behavior
+   */
+  protected getWireSessionConfig(): WireSessionConfig | undefined;
+  /**
+   * Wire Session turn events to Connector state updates.
+   *
+   * Session emits typed events, Connector subscribes and updates processing state.
+   * This maintains separation of concerns - Session does not know about Connector state.
+   *
+   * Default turn_finished behavior: transition through processing_finished to idle,
+   * or drain the queue if messages are pending. Override via `getWireSessionConfig()`.
+   *
+   * Every subscription's unsubscribe function is retained so
+   * {@link unwireSessionEvents} can undo the whole set; a connector that closes
+   * without undoing them stays reachable from the bus for the rest of the process.
+   */
+  protected wireSessionEvents(): void;
+  /**
+   * Run a turn handler only while this connector owns its lifecycle.
+   *
+   * The bus snapshots handlers before it begins invoking them, so unsubscribe
+   * alone cannot stop a snapshotted callback. This second terminal check rejects
+   * that callback when it eventually starts, while the active set lets close
+   * wait for callbacks that started before the terminal latch.
+   * @param handler - Turn callback registered with the scoped bus
+   */
+  private dispatchTurnEvent;
+  /**
+   * Cancel every turn subscription {@link wireSessionEvents} installed.
+   *
+   * **What makes a connector's end total.** §2.2's `released` is the claim that no
+   * callback can arrive afterwards, and a turn subscription is precisely a way for
+   * one to: the bus keeps the closed connector alive, and a later connector
+   * generation on the same agent id emits into the filtered bus both of them are
+   * subscribed to, so the dead one advances its own state machine and touches a
+   * session it already dropped. That is the same defect for a connector reporting
+   * `detached` — it merely has a weaker claim to overstate.
+   *
+   * Idempotent. The separate terminal lifecycle latch decides whether wiring may
+   * be installed again; close paths set that latch before calling this cleanup.
+   */
+  protected unwireSessionEvents(): void;
+  /**
+   * Permanently prevent turn wiring and remove any handlers already installed.
+   *
+   * Close implementations call this before awaiting provider teardown so an
+   * initialization that was already in flight cannot re-wire afterwards.
+   */
+  protected closeTurnEventLifecycle(): Promise<void>;
+  /**
+   * Whether connector initialization lost the terminal close race.
+   * @returns `true` once close permanently claimed the wiring lifecycle
+   */
+  protected get isTurnEventLifecycleClosed(): boolean;
+  /**
+   * Process queued user messages by delegating to Session.
+   *
+   * Shared flow:
+   * 1. Initialize session if not yet created
+   * 2. Enqueue the message
+   * 3. Set adapterSessionId on handle
+   * 4. Transition to active if currently idle/paused
+   * 5. Process queue via session
+   * @param messageHandles - Array of message handles to process
+   * @returns Set of message handles that were processed
+   */
+  protected processUserMessages(messageHandles: MessageHandle[]): Promise<Set<MessageHandle>>;
+  /**
+   * Initialize the connector's SDK session without sending a message.
+   * Must set adapterSessionId before returning.
+   * Called by createAgent for idle agent setup.
+   * Implementations MUST be idempotent (no-op if already initialized).
+   * @param options - Optional start options (e.g., systemPrompt)
+   */
+  initialize(options?: ConnectorStartOptions): Promise<void>;
+  /**
+   * Start session with initial message.
+   * @param message - The initial message to send
+   * @param options - Optional send message options
+   * @returns The agent start result with session ID and message handle
+   */
+  start(message: NormalizedMessageInput, options?: ConnectorSendMessageOptions): Promise<AgentStartResult>;
+  /**
+   * Complete the agent session by waiting for all messages to finish.
+   * @returns Last message result or null if no messages processed
+   */
+  complete(): Promise<MessageResult | null>;
+  /**
+   * Returns true if current turn can accept immediate messages.
+   * @returns True if turn can accept immediate, false otherwise
+   */
+  protected acceptsImmediate(): boolean;
+}
+//#endregion
+//#region adapters/core/src/config/resolve-adapter-auth.d.ts
+/** Stable normalized adapter-auth failure categories. */
+type AdapterAuthErrorReason = 'provider-context-unresolved' | 'binding-missing' | 'binding-ambiguous' | 'client-mismatch' | 'credential-resolution-failed' | 'credential-missing' | 'runtime-bus-missing' | 'native-auth-unavailable';
+/** Typed, credential-free failure at the normalized adapter-auth boundary. */
+declare class AdapterAuthError extends AuthenticationError {
+  readonly reason: AdapterAuthErrorReason;
+  /**
+   * Create a normalized adapter-auth failure.
+   * @param reason - Stable failure category
+   * @param message - Credential-free diagnostic
+   */
+  constructor(reason: AdapterAuthErrorReason, message: string);
+}
+/** Plaintext values produced by the trusted credential resolver. */
+type ResolvedAuthCredentialValues = Readonly<Record<string, string>>;
+/** Resolve normalized credential refs without exposing them outside the trusted consumer. */
+type ResolveAuthCredentialRefs = (credentialRefs: Readonly<Record<string, AuthCredentialRef>>) => Promise<ResolvedAuthCredentialValues>;
+/** Input for binding one normalized provider selection to an adapter declaration. */
+interface BindProviderAuthOptions {
+  /** Resolved provider authentication selection containing refs but no plaintext. */
+  readonly auth: ResolvedProviderAuth;
+  /** Authentication declaration for the selected adapter/provider junction. */
+  readonly adapterProviderAuth: AdapterProviderAuth;
+  /** Other compatible declarations whose environment sinks must also be scrubbed. */
+  readonly compatibleProviderAuths?: readonly AdapterProviderAuth[];
+}
+/** Immutable refs-only adapter binding emitted before connector-local resolution. */
+interface BoundProviderAuthContext {
+  /** Selected normalized provider authentication. */
+  readonly auth: ResolvedProviderAuth;
+  /** The single adapter delivery binding matching the selected method exactly. */
+  readonly binding: AdapterAuthBinding;
+  /** Complete adapter-wide environment variables removed before selected delivery. */
+  readonly scrubEnvVars: readonly string[];
+}
+/**
+ * Select optional field IDs from an explicit normalized auth selection.
+ *
+ * Trusted credential resolvers use this policy to omit only selected optional
+ * refs whose backing secret is unavailable. Keeping it next to the binding
+ * contract guarantees host and container materialization share one rule.
+ * @param bound - Exact provider/auth binding selected for one adapter runtime.
+ * @returns Field IDs whose unavailable refs may be omitted during resolution.
+ */
+declare function getOptionalAuthCredentialFields(bound: BoundProviderAuthContext): readonly string[];
+/** One immutable connector-owned authentication operation. */
+interface ResolvedConnectorAuthDelivery {
+  /** Adapter-specific operation identifier. */
+  readonly target: string;
+  /** Plaintext fields and constant/null suppressions consumed by the operation. */
+  readonly values: Readonly<Record<string, AdapterAuthConstant>>;
+}
+/** Immutable connector-local authentication snapshot. */
+interface ResolvedAdapterAuth {
+  /** Selected plaintext values delivered to a spawned process. */
+  readonly processEnv: Readonly<Record<string, string>>;
+  /** Selected adapter-specific connector operations. */
+  readonly connectorDeliveries: readonly ResolvedConnectorAuthDelivery[];
+  /** Native auth is inherited only for inferred methods. */
+  readonly configInheritance: 'auth-only' | 'empty';
+}
+/**
+ * Bind normalized provider authentication to one exact adapter delivery declaration.
+ *
+ * The result remains refs-only and can therefore travel through adapter configuration
+ * plumbing without exposing plaintext. Every object is cloned by schema parsing and
+ * deeply frozen so connector startup observes one stable selection.
+ * @param options - Selected auth plus selected and compatible adapter declarations.
+ * @returns Immutable refs-only provider auth binding.
+ */
+declare function bindProviderAuth(options: BindProviderAuthOptions): BoundProviderAuthContext;
+/**
+ * Resolve a bound provider auth context into one immutable connector-local snapshot.
+ *
+ * Explicit refs are resolved exactly once. Only required fields must materialize;
+ * unavailable optional fields are omitted from every delivery. Inferred and no-auth
+ * methods never invoke the credential resolver.
+ * @param bound - Immutable refs-only adapter binding.
+ * @param resolveCredentialRefs - Trusted local credential resolver.
+ * @returns Immutable plaintext delivery snapshot.
+ */
+declare function resolveBoundProviderAuth(bound: BoundProviderAuthContext, resolveCredentialRefs: ResolveAuthCredentialRefs): Promise<ResolvedAdapterAuth>;
+//#endregion
+//#region adapters/core/src/config/adapter-auth-runtime.d.ts
+/** Refs-only config emitted by the common adapter factory. */
+type BoundAdapterRuntimeConfig<TBus extends ScopedBus<string> = ScopedBus<string>, TConfig extends BaseAgentConnectorConfig<TBus> = BaseAgentConnectorConfig<TBus>> = TConfig & {
+  /** Adapter instance identifier required by connector factories. */adapterId: string; /** Exact normalized auth selection and adapter delivery binding. */
+  boundProviderAuth?: BoundProviderAuthContext;
+};
+/** Connector-facing config after auth refs and client state have been materialized. */
+type ResolvedAdapterRuntimeConfig<TBus extends ScopedBus<string> = ScopedBus<string>, TConfig extends BaseAgentConnectorConfig<TBus> = BaseAgentConnectorConfig<TBus>> = Omit<TConfig, 'boundProviderAuth'> & {
+  /** Adapter instance identifier required by connector factories. */adapterId: string; /** Selected connector-local auth delivery, including plaintext. */
+  adapterAuth?: ResolvedAdapterAuth; /** Selected managed client binary, when this adapter has a client. */
+  clientExecution?: ClientExecutionContext; /** Auth-free environment safe for routable/shared execution contexts. */
+  contextEnv: Readonly<Record<string, string>>;
+};
+/** Explicit connector-owned client config lease. */
+interface AdapterAuthLeaseHandle {
+  /** Client whose isolated config directory is leased. */
+  readonly clientId: string;
+  /** Connector-unique lease identifier. */
+  readonly leaseId: string;
+  /** Release the lease exactly once. Repeated calls share the same result. */
+  release(): Promise<void>;
+}
+/** Runtime config plus the lease whose lifetime must match its connector. */
+interface PreparedAdapterAuthRuntime<TBus extends ScopedBus<string> = ScopedBus<string>, TConfig extends BaseAgentConnectorConfig<TBus> = BaseAgentConnectorConfig<TBus>> {
+  /** Connector-facing config with one immutable auth snapshot. */
+  readonly config: ResolvedAdapterRuntimeConfig<TBus, TConfig>;
+  /** Explicit lease handle, present only for client-backed adapters. */
+  readonly lease?: AdapterAuthLeaseHandle;
+}
+/** Trusted non-serializable strategy for preparing auth in the current host. */
+type AdapterAuthRuntimePreparer<TBus extends ScopedBus<string> = ScopedBus<string>, TConfig extends BaseAgentConnectorConfig<TBus> = BaseAgentConnectorConfig<TBus>> = (config: BoundAdapterRuntimeConfig<TBus, TConfig>) => Promise<PreparedAdapterAuthRuntime<TBus, TConfig>>;
+/** Host-resolved auth material supplied to a runtime without local secret services. */
+interface SuppliedAdapterAuthRuntime {
+  /** Auth snapshot already compiled against the selected adapter binding by the host. */
+  readonly selectorValidatedAuth: ResolvedAdapterAuth;
+  /** Complete host-compiled adapter auth source/sink scrub union. */
+  readonly scrubEnvVars: readonly string[];
+  /** Non-auth session environment supplied by the host. */
+  readonly sessionEnv?: Readonly<Record<string, string>>;
+  /** Pre-resolved non-auth binary environment supplied by the host. */
+  readonly binaryEnv?: Readonly<Record<string, string>>;
+  /** Environment for an externally-owned config lease or mounted native state. */
+  readonly leaseEnv?: Readonly<Record<string, string>>;
+}
+/**
+ * Prepare the single connector-local auth snapshot and client config lease.
+ *
+ * Explicit credential refs are resolved exactly once through the encrypted
+ * credential channel. The existing session-environment helper remains the
+ * sole merge authority: it scrubs the full adapter set before selected auth
+ * values are applied last. The caller owns the returned lease and must release
+ * it in every connector close or rollback path.
+ * @param config - Refs-only config emitted by the adapter config factory
+ * @returns Connector-facing config and its explicit lease handle
+ */
+declare function prepareAdapterAuthRuntime<TBus extends ScopedBus<string>, TConfig extends BaseAgentConnectorConfig<TBus>>(config: BoundAdapterRuntimeConfig<TBus, TConfig>): Promise<PreparedAdapterAuthRuntime<TBus, TConfig>>;
+/**
+ * Apply host-resolved auth without opening credential channels or owning leases.
+ *
+ * This is the container/bootstrap seam. Its input must already have been
+ * selector-validated with {@link resolveBoundProviderAuth} by the trusted host.
+ * Every supplied non-auth source is merged before the full scrub union, then
+ * only the selected process delivery is injected. Connector deliveries remain
+ * structured values and are never serialized or logged here.
+ * @param config - Connector config containing only non-auth runtime inputs
+ * @param supplied - Host-compiled auth and non-auth environment sources
+ * @returns Connector-facing config with one immutable auth snapshot
+ */
+declare function applySuppliedAdapterAuthRuntime<TBus extends ScopedBus<string>, TConfig extends BaseAgentConnectorConfig<TBus>>(config: BoundAdapterRuntimeConfig<TBus, TConfig>, supplied: SuppliedAdapterAuthRuntime): Promise<ResolvedAdapterRuntimeConfig<TBus, TConfig>>;
+//#endregion
+//#region adapters/core/src/agent/connector-runtime.d.ts
+/** Connector instance paired with its explicit client config lease. */
+interface ConnectorRuntimeHandle<TConnector extends Pick<AIAgentConnector, 'close'>> {
+  /** Live connector instance. */
+  readonly connector: TConnector;
+  /** Lease whose lifetime exactly matches this connector. */
+  readonly lease?: AdapterAuthLeaseHandle;
+}
+/** Dependencies for creating one managed connector runtime. */
+interface CreateConnectorRuntimeOptions<TBus extends ScopedBus<string>, TConnector extends AIAgentConnector<TBus>, TConfig extends BaseAgentConnectorConfig<TBus> = BaseAgentConnectorConfig<TBus>> {
+  /** Refs-only config emitted by the common adapter factory. */
+  readonly config: BoundAdapterRuntimeConfig<TBus, TConfig>;
+  /** Adapter connector constructor. */
+  readonly connectorFactory: (config: ResolvedAdapterRuntimeConfig<TBus, TConfig>) => TConnector | Promise<TConnector>;
+  /** Optional user-message callback attached only after auth preparation. */
+  readonly onMessageSent?: (handle: MessageHandle) => void;
+  /** Sink for connector-owned provider-session rotations; see `BaseAgentConnectorConfig`. */
+  readonly onAdapterSessionMoved?: () => Promise<void>;
+  /** Trusted host-local auth preparer; defaults to DirectChannel + client lease. */
+  readonly prepareAuthRuntime?: AdapterAuthRuntimePreparer<TBus, TConfig>;
+}
+//#endregion
+//#region adapters/core/src/agent/agent-teardown-arbiter.d.ts
+/**
+ * A connector runtime seen only as something that can be closed.
+ *
+ * The arbiter holds handles produced by every agent on one adapter instance, so
+ * it cannot carry their connector types; closing is the whole of what it does
+ * with them.
+ */
+type ClosableConnectorRuntime = ConnectorRuntimeHandle<Pick<AIAgentConnector, 'close'>>;
+/**
+ * How one connector replacement ended, for the teardown waiting on it.
+ *
+ * **In-process only, and deliberately not a wire type.** It carries live runtime
+ * handles, so it cannot cross a transport and no subject may take it as a
+ * payload. Both parties are inside one adapter instance by construction — the map
+ * it travels through is this object's own memory — so this is a boundary being
+ * written down rather than a limitation being accepted. A future cross-process
+ * consumer needs a *reported* form (a class plus a detail), not this one.
+ */
+interface ConnectorReplacementSettlement {
+  /** Which runtime is current once the replacement is over. */
+  readonly outcome: 'committed' | 'rolled-back';
+  /**
+   * Runtimes this replacement started or superseded and could **not** prove
+   * closed.
+   *
+   * The outcome names which runtime is *current*, which is not the same question
+   * as which started resources are still *live*: a committed replacement whose
+   * close of the superseded runtime failed leaves that runtime holding its
+   * connector and its lease, and a rolled-back one whose close of the replacement
+   * failed leaves that one. A waiting teardown closes these too, best-effort, and
+   * aggregates — so the outcome stays two-valued and every consumer keeps one
+   * branch instead of gaining an "unsafe" third arm.
+   */
+  readonly unclosed: readonly ClosableConnectorRuntime[];
+  /**
+   * What the closes this replacement performed **itself** observed.
+   *
+   * The outcome and `unclosed` together say which runtimes still need closing;
+   * neither says how strong the replacement's own closes were. A superseded close
+   * that reports `detached` — the ordinary answer of a process connector that
+   * signalled a kill it did not see land — fails nothing, so it appears in neither
+   * field, and a teardown aggregating only its own closes would then answer for the
+   * agent more strongly than the runtime it inherited the end of ever allowed.
+   *
+   * So the reports travel and the waiting teardown aggregates them with its own.
+   * This is the same rule as everywhere else in this seam: whoever is last
+   * answerable reports, and the weakest class in the set is the answer.
+   */
+  readonly closeReports: readonly TeardownReport[];
+}
+/**
+ * What a replacement learns about its waiter at the instant it settles.
+ *
+ * Two different questions, and a replacement acts on both: *who closes the
+ * runtimes* and *who reports the closes already performed*. They are not the same
+ * question, because a settlement can have no waiter at all — the ordinary case,
+ * with no teardown anywhere — and then nobody abandoned anything and nobody took
+ * the reports either.
+ */
+interface ConnectorSwapHandover {
+  /**
+   * A teardown gave up waiting, making both runtimes this replacement's to close.
+   *
+   * Distinct from the case below: an expired waiter inherits *obligations*, an
+   * absent one never had any.
+   */
+  readonly abandonedByWaiter: boolean;
+  /**
+   * A teardown received this settlement, so its {@link
+   * ConnectorReplacementSettlement.closeReports} are already answered for.
+   *
+   * `false` covers both an absent waiter and an expired one, and the replacement
+   * treats them alike: the reports have no consumer, so they travel to the party
+   * that is still answerable for the agent instead of being discarded.
+   */
+  readonly reportsConsumedByWaiter: boolean;
+}
+/** The admission a replacement holds between the door and its own `finally`. */
+interface ConnectorSwapAdmission {
+  /**
+   * Settle this replacement and learn what became of its waiter.
+   *
+   * Called before the post-settlement work in the `finally` of the very function
+   * that took the admission, so a teardown already waiting can proceed. That
+   * function retires the admission after its post-settlement work finishes.
+   * @param settlement - Which runtime is current, and what could not be proven closed
+   * @returns Who closes what is left, and whether anybody took the reports
+   */
+  settle: (settlement: ConnectorReplacementSettlement) => ConnectorSwapHandover;
+  /**
+   * Retire this replacement from identity-wide visibility after its own
+   * post-settlement obligations finish.
+   *
+   * Settlement removes only current-runtime handover eligibility so a teardown
+   * can proceed. Retirement is deliberately separate: an abandoned waiter makes
+   * the coordinator close inherited runtimes after settlement, and no-entry
+   * disposal must remain `unknown` until those closes finish. Repeated calls are
+   * harmless.
+   */
+  retire: () => void;
+}
+/** What a teardown flight needs from the registry that owns the agent. */
+interface TeardownSubject {
+  /**
+   * Close whichever runtime the agent holds now, and report.
+   *
+   * Called after any replacement has settled, which is what makes "the runtime
+   * current for that outcome" automatic: a committed replacement published its
+   * own, a rolled-back one restored the previous.
+   */
+  readonly closeCurrent: () => Promise<TeardownReport>;
+  /**
+   * Close one runtime a settlement could not prove closed.
+   * @param runtime - Handle reported as unclosed
+   */
+  readonly closeUnclosed: (runtime: ClosableConnectorRuntime) => Promise<TeardownReport>;
+  /**
+   * Give the agent's identity up without closing anything.
+   *
+   * Separate from the closes because the two are separable: an agent stops being
+   * the instance that answers for its ID at the instant this teardown gives up on
+   * it, whatever the connector replacement it abandoned later does with the
+   * runtimes. Only the expiry arm calls it — every other arm reaches
+   * `AIAgent.close()`, which takes the wiring down itself.
+   */
+  readonly releaseIdentity: () => void;
+  /**
+   * Absolute deadline of the request driving this teardown, when it has one.
+   *
+   * Present for an RPC-driven stop, absent for a session close that fans out
+   * over every agent it owns — which is exactly the path where the policy
+   * ceiling stands alone.
+   */
+  readonly deadline?: number | undefined;
+}
+/** Arbitrate teardowns and connector replacements for one adapter instance. */
+declare class AgentTeardownArbiter {
+  /**
+   * Teardowns in flight, keyed by agent.
+   *
+   * Installed **before** any close starts and removed in a `finally`, which is
+   * what makes joining total: a second caller reads the answer the first is
+   * already producing, and a reentrant close triggered by the first one's own
+   * lifecycle event joins the flight that emitted it.
+   */
+  private readonly teardowns;
+  /** The newest replacement eligible to hand a teardown its current runtime. */
+  private readonly swaps;
+  /** Replacements with post-settlement obligations, keyed by agent. */
+  private readonly swapRetirementCounts;
+  /**
+   * Whether a teardown of this agent is in flight.
+   *
+   * "Nothing here" is only true when nothing is in flight, so a caller answering
+   * that question asks this one too rather than reading the registry alone.
+   * @param agentId - Agent to probe
+   * @returns Whether a flight is installed for it
+   */
+  hasTeardownInFlight(agentId: string): boolean;
+  /**
+   * Whether a connector replacement of this agent is in flight.
+   *
+   * **The state an expiry leaves behind.** A teardown that gave up waiting removes
+   * its own flight and its registry entry, while the replacement it abandoned still
+   * holds *both* runtimes and closes neither until it settles. So a caller
+   * answering "nothing on this instance can still be speaking for that identity"
+   * asks this question too: without it, the one answer that frees an identity is
+   * given while two live connectors answer for it.
+   *
+   * **Any** admitted replacement counts until its retirement, not only the newest:
+   * a superseded predecessor holds runtimes and closes them on its own schedule,
+   * so an identity is free only once every replacement admitted on it has finished
+   * its post-settlement obligations.
+   * @param agentId - Agent to probe
+   * @returns Whether a replacement is installed for it
+   */
+  hasReplacementInFlight(agentId: string): boolean;
+  /**
+   * Admit a connector replacement, or refuse it.
+   *
+   * **The door, and the entire boundary between the two acts.** It is a
+   * synchronous prologue with no await between its steps, which is what makes the
+   * two arbitration regions exhaustive: a teardown is either installed before this
+   * instant or it is not, and there is no interval in between for one to arrive
+   * in.
+   *
+   * Refusing costs nothing here — no replacement runtime exists yet, no provider
+   * thread has been started, no lifecycle event has been delivered and no account
+   * transition has been committed. Whatever a producer did *before* reaching the
+   * door is the producer's own to compensate, which every producer already does.
+   * @param agentId - Agent whose connector would be replaced
+   * @param hasConnectorRuntime - Read of the agent's runtime presence, evaluated
+   *   inside the prologue so its refusal is ordered after the teardown read
+   * @returns The admission whose settlement the door must resolve
+   * @throws ConnectorSwapVetoedError When a teardown is in flight, or the agent
+   *   holds no runtime to replace
+   */
+  admitSwap(agentId: string, hasConnectorRuntime: () => boolean): ConnectorSwapAdmission;
+  /**
+   * Run — or join — the single teardown flight for one agent.
+   *
+   * The flight **writes no status**: the four entry points want different
+   * terminal effects, so a plan carried into the flight would make the terminal
+   * status depend on which caller won the race, and applying the effects after a
+   * join would write it twice. Removing status from the flight dissolves both, and
+   * costs nothing because the statuses are already idempotent — `disposed` is
+   * terminal in storage, so the *effective* terminal status is `disposed` whenever
+   * a disposal participated, in either order.
+   *
+   * Reading the replacement map is the flight's **first act after installing its
+   * own entry**, and that order is what makes the arbitration total: a replacement
+   * beginning after the install finds this flight and refuses, one that began
+   * before it is awaited rather than raced.
+   *
+   * **The install happens before the body runs, not after it returns.** An async
+   * function runs synchronously up to its first await, and the body reaches
+   * `closeCurrent()` — and through it `agent.session.closed` — inside that window.
+   * Writing the map with the promise the body returned would leave a synchronously
+   * reentrant teardown unable to see the flight that provoked it, making
+   * reentrancy safe only by the emitter's scheduling rather than by construction.
+   * A deferred promise is what makes the installation first.
+   * @param agentId - Agent being torn down
+   * @param subject - How to close this agent's runtimes, and the caller's deadline
+   * @returns What the teardown observed — the joined answer for a second caller
+   */
+  runTeardown(agentId: string, subject: TeardownSubject): Promise<TeardownReport>;
+  /**
+   * Run the flight body and hand its answer to the installed promise.
+   *
+   * Separated from {@link runTeardown} so the installation stays synchronous: this
+   * is the first thing that may await, and by the time it does the map already
+   * carries the flight. The removal is in a `finally` and therefore runs in the same
+   * synchronous continuation as the settlement, so no joiner can resume and find
+   * the entry still there.
+   * @param agentId - Agent being torn down
+   * @param subject - How to close this agent's runtimes, and the caller's deadline
+   * @param deferred - The promise already installed for this flight
+   */
+  private settleFlight;
+  /**
+   * The flight body: arbitrate against any replacement, then close.
+   * @param agentId - Agent being torn down
+   * @param subject - How to close this agent's runtimes, and the caller's deadline
+   * @returns What the teardown observed
+   */
+  private flyTeardown;
+  /**
+   * Wait for a replacement to settle, bounded by the caller's own budget.
+   *
+   * **The waiter takes its own bound**, because a contract may not claim
+   * boundedness while making a teardown wait on somebody else's discipline. The
+   * effective wait is the smaller of the policy ceiling and what remains of the
+   * caller's deadline less one observation margin; the margin is that constant
+   * because the expiry arm closes nothing, so all that remains after it is a
+   * status write and the reply.
+   *
+   * **What this bound proves, and nothing beyond it:** the wait itself always
+   * expires with at least one observation margin of the caller's budget
+   * unconsumed, so it can never consume the whole outer budget on its own.
+   * Response *reachability* stays best-effort while the post-wait tail is
+   * unbounded — a caller whose deadline expires receives its timeout by bus law,
+   * and from inside here that is indistinguishable from the tail being slow.
+   *
+   * Below the margin the clamp yields a **zero wait**: the teardown does not wait
+   * at all and answers as fast as it can. Marking the abandonment synchronously in
+   * that arm is load-bearing — it must be visible to a door whose own settlement
+   * has already resolved.
+   * @param swap - Replacement entry found in flight
+   * @param deadline - Absolute deadline of the request driving this teardown
+   * @returns The settlement, or `undefined` when the bound expired first
+   */
+  private awaitSettlement;
+}
+//#endregion
+//#region adapters/core/src/adapter/ai-adapter-config.d.ts
+/**
+ * Input provided by agent to the config factory.
+ * Contains partial configuration - adapters provide defaults for missing required fields.
+ *
+ * Includes all runtime options from StartAgentRequest (allowedTools, disallowedTools, etc.)
+ * to ensure they flow through to the connector.
+ */
+interface ConfigFactoryInput<TBus extends ScopedBus<string> = ScopedBus<string>> {
+  /** Scoped bus for adapter-specific events */
+  bus: TBus;
+  /** Global bus for cross-namespace runtime requests */
+  globalBus?: IMakaioBus;
+  /** Unique agent identifier (required - generated by AIAgent) */
+  agentId: string;
+  /** Adapter instance identifier (required - provided by AIAgent from adapter) */
+  adapterId: string;
+  /** Adapter type name (required - provided by AIAgent from adapter) */
+  adapterName: string;
+  /** Refs-only normalized provider selection consumed by the common auth runtime. */
+  providerContext: ProviderContext;
+  /** Exact HTTP protocol declared by the selected adapter/provider reference. */
+  providerProtocol?: ProtocolId;
+  /** Adapter/provider auth metadata selected by `providerContext.definitionId`. */
+  adapterProviderAuth?: AdapterProviderAuth;
+  /** Other adapter/provider auth declarations contributing to the scrub union. */
+  compatibleProviderAuths?: readonly AdapterProviderAuth[];
+  /** Whether this adapter rejects the unresolved provider state. */
+  providerContextRequired?: boolean;
+  /** Provider's session ID for resuming existing conversations */
+  adapterSessionId?: string;
+  /** Makaio session ID for tool execution context and multi-session correlation */
+  sessionId?: string;
+  /** Previous adapter session ID for resume attempts (from recovery). */
+  resumeAdapterSessionId?: string;
+  /** Model to use - optional, adapters provide defaults */
+  model?: string;
+  /** Working directory for agent execution */
+  cwd?: string;
+  /** Environment variables to pass to agent execution */
+  env?: Record<string, string>;
+  /** Reasoning effort for supporting adapters */
+  reasoningEffort?: AIReasoningLevel$1;
+  /** Reasoning levels supported by the resolved model, forwarded to the connector. */
+  supportedReasoningLevels?: ReasoningLevelMap$1;
+  /** Error handler for connector errors */
+  errorHandler?: (error: Error, terminate: boolean) => void;
+  /** Allowed tool names (adapter-specific). Empty array = disable all tools. */
+  allowedTools?: string[];
+  /** Disallowed tool names (adapter-specific). Takes precedence over allowedTools. */
+  disallowedTools?: string[];
+  /** Directory restrictions for file-system tool execution. */
+  allowedDirectories?: string[];
+  /**
+   * Adapter-specific per-call configuration (non-credential settings).
+   *
+   * This receives `startAgent.adapterConfig` at runtime and feeds the existing
+   * `createAdapterConfigFactory` providerConfig merge slot. It is unrelated to
+   * ProviderConfig credential entities, which flow through `providerContext`.
+   */
+  providerConfig?: Record<string, unknown>;
+  runtimeTimeouts?: TimeoutConfig;
+  /** Client identifier for the application this adapter belongs to (e.g., 'claude-code', 'gemini'). */
+  clientId?: string;
+  /** Client profile name for session-scoped config isolation. */
+  clientProfileName?: string;
+  /** Harness identifier used to resolve per-agent tool governance. */
+  harnessId?: string;
+  /**
+   * Resolved MCP session context including upstream server configs.
+   * When present, native-passthrough adapters use `servers` to configure SDK MCP connections.
+   */
+  mcpSessionContext?: LedgerSessionContext | McpRuntimeSessionContext | McpSessionContext;
+  /**
+   * Session-scoped MCP tool ledger.
+   * Passed through unchanged so connectors can track injection and mcp_call usage.
+   */
+  toolLedger?: ISessionToolLedger;
+  /**
+   * When true, the agent is ephemeral (one-shot, not a resume/fork target).
+   *
+   * Ephemeral agents skip PreUserMessage hooks and are never resumed or forked
+   * natively. Connectors should disable session persistence for ephemeral agents
+   * so no transcript is written to the provider's session store.
+   */
+  ephemeral?: boolean;
+  /**
+   * Whether this agent's provider session is this adapter's to publish yet.
+   *
+   * Absent means yes, which is every adapter-owned agent: the adapter is the
+   * only publisher such an agent has. It answers `false` for the window in which
+   * a **caller-owned** start has not handed its key over — the caller reserved
+   * the provider session and settles the key its connector confirms, so an
+   * announcement or an event field from here would publish a key no generation
+   * holds yet, and the observer would settle it under a token that caller's
+   * failure paths cannot name.
+   *
+   * A predicate rather than a flag because the window has an end the adapter can
+   * observe — its own registration — and no new state to keep in step with it.
+   */
+  isProviderKeyPublishable?: () => boolean;
+}
+/**
+ * Interface for adapter-specific configuration factories.
+ *
+ * Transforms partial ConfigFactoryInput into full adapter-specific config.
+ * The key responsibility is applying adapter defaults (especially model).
+ * @example
+ * ```typescript
+ * const OpenAIConfigFactory: IAdapterConfigFactory<OpenAINodeAgentConfig> = {
+ *   getConfig: async (input) => ({
+ *     ...input,
+ *     model: input.model ?? 'gpt-4o',
+ *     providerConfig: { debugMode: true },
+ *   }),
+ * };
+ * ```
+ */
+interface IAdapterConfigFactory<TConfig extends BaseAgentConnectorConfig, TBus extends ScopedBus<string> = ScopedBus<string>> {
+  getConfig(input: ConfigFactoryInput<TBus>): Promise<TConfig>;
+}
+//#endregion
+//#region adapters/core/src/types/provider-definition.d.ts
+/**
+ * Runtime adapter provider definition pairing a serializable provider definition
+ * with optional runtime-only provider configuration metadata.
+ *
+ * Aliases {@link AdapterProviderDefinitionContract} from `@makaio/contracts`,
+ * the single source of truth for the `definition` and `configSchema` fields.
+ * The domain-specific name keeps adapter implementation signatures readable
+ * without creating a second provider-definition contract.
+ *
+ * Each adapter exports an array of these from its `definition.ts` (via `providers`).
+ * The `definition` field contains serializable data (models, endpoints, etc.).
+ * Config schemas are runtime-only — used for UI form generation, never serialized.
+ */
+type AdapterProviderDefinition = AdapterProviderDefinitionContract;
+//#endregion
+//#region adapters/core/src/agent/types.d.ts
+/**
+ * Core agent identity fields.
+ * Used as base for contexts, configs, and request payloads.
+ */
+interface AgentIdentity {
+  /** Unique agent identifier */
+  agentId: string;
+  /** Adapter instance identifier */
+  adapterId: string;
+  /** Adapter type name (e.g., 'claude-code', 'gemini-sdk') */
+  adapterName: string;
+  /** Session identifier for multi-turn conversations */
+  adapterSessionId?: string;
+}
+/**
+ * Runtime options as INPUT - model/cwd optional (adapters provide defaults via configFactory).
+ */
+interface AgentRuntimeInput {
+  /** Model to use (optional - adapter provides default) */
+  model?: string;
+  /** Working directory for agent execution (optional - platform provides default) */
+  cwd?: string;
+  /** Environment variables to pass to agent execution */
+  env?: Record<string, string>;
+  /** Reasoning effort for supporting adapters */
+  reasoningEffort?: AIReasoningLevel$1;
+  /** Allowed tool names. Empty array disables all adapter-visible tools. */
+  allowedTools?: string[];
+  /** Disallowed tool names. Takes precedence over allowedTools. */
+  disallowedTools?: string[];
+}
+/**
+ * Runtime options as RESOLVED config - model/cwd required (after configFactory applies defaults).
+ */
+type AgentRuntimeOptions = SetRequired<AgentRuntimeInput, 'model' | 'cwd'>;
+/**
+ * Common context fields for all agent.* subject emissions.
+ * AIAgent automatically enriches payloads with these fields.
+ */
+type AgentContext = Required<AgentIdentity>;
+/**
+ * Execution context for per-agent processors.
+ * Baked in at processor creation time, eliminating runtime registry lookups.
+ */
+type ExecutionContext = AgentContext;
+interface MinimalAgentConnectorConfig<TBus extends ScopedBus<string> = ScopedBus<string>> {
+  bus: TBus;
+  globalBus?: IMakaioBus;
+}
+/**
+ * Base configuration for AI agent connector instances.
+ */
+interface BaseAgentConnectorConfig<TBus extends ScopedBus<string> = ScopedBus<string>, TProviderConfig extends object = object> extends MinimalAgentConnectorConfig<TBus>, Omit<AgentIdentity, 'adapterId'>, AgentRuntimeOptions {
+  /** Makaio session ID for tool execution context and multi-session correlation */
+  sessionId?: string;
+  errorHandler?: (error: Error, terminate: boolean) => void;
+  /**
+   * Resolved timeout configuration with provenance tracking.
+   * Set by configFactory after merging all timeout layers.
+   */
+  timeouts?: TrackedTimeoutConfig;
+  /**
+   * UUID of the ProviderConfig entity used during agent creation.
+   * Carried on the connector config for runtime introspection and dynamic provider switching.
+   */
+  providerConfigId?: string;
+  /**
+   * Refs-only normalized provider selection retained for runtime introspection.
+   * Plaintext authentication is available only through {@link adapterAuth}.
+   */
+  providerContext?: ProviderContext;
+  /** Exact HTTP protocol selected by the active adapter/provider reference. */
+  providerProtocol?: ProtocolId;
+  providerConfig?: TProviderConfig;
+  /**
+   * Maps supported reasoning levels to provider-native values for the active model.
+   *
+   * Populated by the config factory when the resolved model declares reasoning support.
+   * Absent when the model does not support extended thinking.
+   */
+  supportedReasoningLevels?: ReasoningLevelMap$1;
+  /** Previous adapter session ID for resume attempts. */
+  resumeAdapterSessionId?: string;
+  /**
+   * Provider-native fork directive approved by session orchestration.
+   * When present, native-fork capable connectors should branch from the source
+   * provider session instead of starting fresh with replayed history.
+   */
+  nativeFork?: NativeForkDirective;
+  /** Resolved harness ID for tool policy lookup. */
+  harnessId?: string;
+  /** Client identifier for the application this adapter belongs to (e.g., 'claude-code', 'gemini'). */
+  clientId?: string;
+  /** Client profile name for session-scoped config isolation. */
+  clientProfileName?: string;
+  /**
+   * Auth-free environment safe for bus-routable tool and MCP contexts.
+   *
+   * The central adapter runtime derives this from the same merged inputs as
+   * `env`, but omits the selected process authentication delivery.
+   */
+  contextEnv?: Readonly<Record<string, string>>;
+  /**
+   * Single connector-local normalized auth snapshot.
+   *
+   * Plaintext exists only on this trusted connector config and must never be
+   * emitted, persisted, stringified, or copied back into provider context.
+   */
+  adapterAuth?: ResolvedAdapterAuth;
+  /** Managed client binary selected by the central runtime, when applicable. */
+  clientExecution?: ClientExecutionContext;
+  /** Callback when a user message is enqueued */
+  onMessageSent?: (messageHandle: MessageHandle) => void;
+  /**
+   * Announce that the connector rotated its provider session with no confirmed
+   * successor yet.
+   *
+   * For rotations the executor can predict, the movement seam is driven from the
+   * pre-dispatch check in `AgentTurnExecutor` (see
+   * `agent/agent-adapter-session-movement.ts`). A connector that rotates on a
+   * decision only it can observe — the CLI's immediate-mode restart, which kills
+   * the in-flight subprocess and mints a fresh identity — must announce that
+   * movement itself, and `await` it before the dispatch that abandons the old
+   * provider session (duty 2).
+   *
+   * Injected by the owning agent, so the announcement routes through its
+   * `ConfirmedAdapterSessionTracker` and inherits the seam's retry anchor
+   * (duties 3 and 4) instead of emitting one unrecoverable event.
+   */
+  onAdapterSessionMoved?: () => Promise<void>;
+  /**
+   * Directory restrictions for file-system tool execution.
+   * When set, forwarded as `constraints.allowedDirectories` in every tool call.
+   * Empty array means no restriction; undefined means no restriction.
+   */
+  allowedDirectories?: string[];
+  /**
+   * MCP session context resolved by the orchestrator.
+   * Provides the direct and discoverable tool sets for the current session.
+   * When present, enables MCP tool injection and ledger tracking.
+   *
+   * Intentionally narrowed to LedgerSessionContext — the minimal shape the
+   * ledger needs. Adapters requiring the full McpSessionContext (with
+   * resolution keys / servers) re-declare this field via Omit + intersection
+   * in their own config types (e.g. BaseStreamConnectorConfig, ClaudeAgentConfig).
+   */
+  mcpSessionContext?: LedgerSessionContext | McpRuntimeSessionContext | McpSessionContext;
+  /**
+   * Session-scoped tool ledger for tracking injection, discovery, and call history.
+   * When present, the connector records tool events into this ledger.
+   */
+  toolLedger?: ISessionToolLedger;
+  /**
+   * When true, the connector is handling an ephemeral one-shot agent.
+   *
+   * Ephemeral agents are by contract never resume or fork targets. Connectors
+   * that support session persistence should disable it for ephemeral agents so
+   * no transcript is written to the provider's session store.
+   */
+  ephemeral?: boolean;
+}
+/**
+ * Configuration for creating an AIAgent instance.
+ *
+ * Combines agent identity, runtime input, and factory functions.
+ * model/cwd are optional here - configFactory provides adapter defaults.
+ * @typeParam TBus - The scoped bus type for this adapter
+ * @typeParam TConnector - The connector type (for proper factory return typing)
+ */
+interface AIAgentConfig<TBus extends ScopedBus<string> = ScopedBus<string>, TConnector extends AIAgentConnector<TBus> = AIAgentConnector<TBus>> extends Omit<AgentIdentity, 'adapterSessionId'>, AgentRuntimeInput {
+  /** Adapter-specific session identifier for multi-turn conversations */
+  adapterSessionId?: string;
+  /** Makaio session identifier */
+  sessionId?: string;
+  /** Refs-only normalized provider selection set by session orchestration. */
+  providerContext?: ProviderContext;
+  /** Previous adapter session ID for resume attempts (from recovery). */
+  resumeAdapterSessionId?: string;
+  /** Resolved harness ID for tool policy lookup. */
+  harnessId?: string;
+  /** Client identifier for the application this adapter belongs to (e.g., 'claude-code', 'gemini'). */
+  clientId?: string;
+  /** Client profile name for session-scoped config isolation. */
+  clientProfileName?: string;
+  /** Trusted non-serializable auth preparation strategy injected by the host. */
+  prepareAuthRuntime?: AdapterAuthRuntimePreparer<TBus>;
+  /** Global bus instance (defaults to MakaioBus singleton) */
+  globalBus?: IMakaioBus;
+  /** Scoped bus for adapter-specific events */
+  adapterBus: TBus;
+  /**
+   * Adapter-instance arbiter between teardowns and connector replacements.
+   *
+   * **Required**, and that is the point: the arbiter is what makes "replacements
+   * refuse when they find a teardown, teardowns wait when they find a
+   * replacement" a property of the module rather than a convention. An agent
+   * constructed without one would replace connectors with no arbitration at all,
+   * so it does not compile.
+   */
+  teardownArbiter: AgentTeardownArbiter;
+  /** Adapter capabilities (e.g., ['streaming', 'tools', 'vision']) */
+  capabilities: string[];
+  /** Native tools built into the adapter (e.g., ['shell_command', 'apply_patch']) */
+  nativeTools: string[];
+  /** Available models for this adapter (used for context window lookup) */
+  availableModels?: AIModel[];
+  /** Resolved provider definitions, including adapter-provider auth metadata. */
+  definitionProviders?: readonly AdapterProviderDefinition[];
+  /** Allowed tool names (adapter-specific). Empty array = disable all tools. */
+  allowedTools?: string[];
+  /** Disallowed tool names (adapter-specific). Takes precedence over allowedTools. */
+  disallowedTools?: string[];
+  /** Directory restrictions for file-system tool execution. */
+  allowedDirectories?: string[];
+  /** Per-call adapter-specific JSON config forwarded to the adapter config factory. */
+  adapterConfig?: Record<string, unknown>;
+  /**
+   * MCP session context resolved by the orchestrator.
+   * Passed through to the connector config so adapters can inject direct tools.
+   */
+  mcpSessionContext?: LedgerSessionContext | McpRuntimeSessionContext;
+  /**
+   * Session-scoped ledger tracking MCP injection/discovery/call history.
+   * Created once per agent session and passed through unchanged on connector swaps.
+   */
+  toolLedger?: ISessionToolLedger;
+  /**
+   * When true, PreUserMessage hooks are skipped for this agent.
+   * Use for ephemeral ping agents where session enrichment and context injection
+   * are not needed and would be actively harmful.
+   */
+  ephemeral?: boolean;
+  /**
+   * Native fork directive from the orchestrator.
+   *
+   * When present, the adapter should use the provider's branching API
+   * rather than replaying history into a fresh session.
+   * Populated by AIAdapter.createAgent when the startAgent mode is 'fork'.
+   *
+   * AIAgent forwards this through config-factory input so standardized adapter
+   * config factories can carry it into connector config. Adapter code must not
+   * derive this from raw fork-mode request fields.
+   */
+  nativeFork?: NativeForkDirective;
+  /**
+   * Config factory - transforms partial input into full adapter-specific config.
+   * This is the seam where adapters inject their defaults (especially model).
+   */
+  configFactory: (input: ConfigFactoryInput<TBus>) => Promise<BaseAgentConnectorConfig<TBus> & {
+    adapterId: string;
+  }>;
+  /**
+   * Connector factory - creates connector from full config.
+   * Called AFTER configFactory returns the complete configuration.
+   * Config includes adapterId (passed through from input by config factory).
+   */
+  connectorFactory: (config: BaseAgentConnectorConfig<TBus> & {
+    adapterId: string;
+  }) => TConnector | Promise<TConnector>;
+}
+/**
+ * Result returned from agent.start()
+ */
+interface AgentStartResult {
+  adapterSessionId: string;
+  agentId: string;
+  messageHandle: MessageHandle;
+}
+/**
+ * Options for sending a message to an agent.
+ * Extends SendMessageOptions with curated message history and system prompt configuration.
+ */
+interface AgentSendMessageOptions extends SendMessageOptions {
+  /** Curated message history from orchestration layer */
+  messageHistory?: Message[];
+  /**
+   * System prompt configuration.
+   * - `string`: Replace/set the entire system prompt
+   * - `{ mode: 'append', content: string }`: Append to adapter's default system prompt
+   */
+  systemPrompt?: SystemPrompt;
+  /**
+   * Context signals assembled by SessionOrchestrator.
+   * Used by AIAgent to decide: native resume vs fresh with history.
+   * Hooks inject context via sessionContext.turnContext (set by replacePayload).
+   */
+  sessionContext?: SessionContext;
+  /**
+   * Structured output descriptor for the turn.
+   *
+   * Adapters that declare `structuredOutput` pass this schema to their native
+   * model-level output controls. Other adapters receive an instruction block
+   * and the agent validates the terminal output after completion.
+   *
+   * Validation retries are default-off (`maxRetries: 0`) and fallback
+   * enforcement is a no-op unless the host registers structured-output override
+   * handlers.
+   */
+  responseSchema?: ResponseSchemaDescriptor;
+}
+/**
+ * Options for starting an agent session.
+ * Same as AgentSendMessageOptions - both start() and sendMessage() accept the same options.
+ */
+type StartAgentOptions = AgentSendMessageOptions;
+/**
+ * Options for connector-level message operations.
+ * Extends AgentSendMessageOptions with turnContext for internal AIAgent to Connector communication.
+ * AIAgent extracts sessionContext.turnContext and passes it here.
+ * Inherits responseSchema from AgentSendMessageOptions.
+ */
+interface ConnectorSendMessageOptions extends AgentSendMessageOptions {
+  /**
+   * Content-free provider transport correlation. This is carried on the
+   * message handle and never materialized into the LLM-facing message.
+   */
+  requestCorrelation?: RequestCorrelationContext;
+  /**
+   * Lifecycle turnId from the session orchestrator (`agent.sendMessage.turnId`).
+   * Carried on the message handle so user_message lifecycle events pair by it.
+   * Distinct from `requestCorrelation.turnId`, which is transport correlation
+   * and may be present when no lifecycle turn exists.
+   */
+  turnId?: string;
+  /**
+   * Turn-scoped context assembled by PreUserMessage hooks and the orchestrator.
+   * Extracted from sessionContext.turnContext by AIAgent.
+   * Adapters use this to prepend context blocks to the SDK message.
+   *
+   * ADAPTER CONTRACT: Every adapter MUST materialize turnContext into the
+   * LLM-facing message using serializeTurnContext().
+   */
+  turnContext?: Record<string, JsonValue>;
+  /**
+   * Caller-expressed caching intent for the injected message history.
+   * Adapters map this to provider-specific cache mechanisms.
+   */
+  cacheStrategy?: CacheStrategy;
+  /**
+   * Whether this message is an internal retry turn synthesized by the structured-output
+   * manager. When `true`, the connector suppresses `user_message.sent` so the retry
+   * is not surfaced as a new user message.
+   */
+  internalRetry?: boolean;
+  /**
+   * Caller decision on provider-native session resume for this dispatch.
+   *
+   * The turn pipeline sets this from the agent's native-resume decision. When
+   * `false`, the connector MUST NOT arm its pending start-time resume target
+   * (`resumeAdapterSessionId`) for this dispatch: the caller has replaced the
+   * provider thread with injected `messageHistory`, so natively resuming would
+   * double the conversation context. Honoring connectors discard the
+   * unconsumed resume target and mint a fresh provider session instead.
+   *
+   * When `true` or absent, the connector applies its default resume behavior.
+   * The flag never affects a connector's continuity of its own
+   * provider-confirmed session (intra-generation multi-turn), and it does not
+   * cancel an approved `nativeFork` directive — fork is a separate contract.
+   */
+  useNativeResume?: boolean;
+}
+/**
+ * Options for connector-level start operations.
+ * Same as ConnectorSendMessageOptions.
+ */
+type ConnectorStartOptions = ConnectorSendMessageOptions;
+/** Payload type for `agent.sendMessage` requests. */
+type SendMessageRequestPayload = ExtractSubjectPayload<typeof AgentSubjects.sendMessage>;
+/** Response type for `agent.sendMessage` requests. */
+type SendMessageResponsePayload = ExtractSubjectResponse<typeof AgentSubjects.sendMessage>;
+/** Payload type for `agent.interrupt` requests. */
+type AgentInterruptRequestPayload = ExtractSubjectPayload<typeof AgentSubjects.interrupt>;
+/** Response type for `agent.interrupt` requests. */
+type AgentInterruptResponsePayload = ExtractSubjectResponse<typeof AgentSubjects.interrupt>;
+/** Response type for `agent.getCapabilities` requests. */
+type GetCapabilitiesResponsePayload = ExtractSubjectResponse<typeof AgentSubjects.getCapabilities>;
+/** Payload type for `agent.cwd.change` requests. */
+type AgentCwdChangeRequestPayload = ExtractSubjectPayload<typeof AgentSubjects.cwd.change>;
+/** Response type for `agent.cwd.change` requests. */
+type AgentCwdChangeResponsePayload = ExtractSubjectResponse<typeof AgentSubjects.cwd.change>;
+/** Payload type for `agent.model.change` requests. */
+type AgentModelChangeRequestPayload = ExtractSubjectPayload<typeof AgentSubjects.model.change>;
+/** Response type for `agent.model.change` requests. */
+type AgentModelChangeResponsePayload = ExtractSubjectResponse<typeof AgentSubjects.model.change>;
+/** Payload type for `agent.mcp.servers.set` requests. */
+type AgentMcpServersSetRequestPayload = ExtractSubjectPayload<typeof AgentSubjects.mcp.servers.set>;
+/** Response type for `agent.mcp.servers.set` requests. */
+type AgentMcpServersSetResponsePayload = ExtractSubjectResponse<typeof AgentSubjects.mcp.servers.set>;
+/** Payload type for `agent.credential.change` requests. */
+type AgentCredentialChangeRequestPayload = ExtractSubjectPayload<typeof AgentSubjects.credential.change>;
+/** Response type for `agent.credential.change` requests. */
+type AgentCredentialChangeResponsePayload = ExtractSubjectResponse<typeof AgentSubjects.credential.change>;
+type EmitteryEvents = {
+  processingStateChanged: ProcessingState;
+};
+/**
+ * Normalized usage metrics for a single agent call.
+ * Adapter implementations normalize provider-specific usage data to this format.
+ *
+ * Derived from the `agent.usage` schema, so the mandatory `granularity` field
+ * is part of this type: adapters MUST declare the truthful measurement
+ * granularity of every usage signal they normalize (see
+ * `docs/architecture/adapters/usage-and-provenance.md`).
+ */
+type NormalizedCallUsage = Omit<z.infer<typeof AgentSchemas.usage>, keyof AgentContext | 'model'>;
+/**
+ * Input for context window update emission.
+ * Adapters provide raw metrics, helper calculates percentage and level.
+ */
+interface ContextWindowInput {
+  /** Total tokens in context (input + output for next turn prediction) */
+  currentTokens: number;
+  /** Model's context window limit */
+  maxTokens: number;
+  /** Cached tokens (optional, reduces cost but still in context) */
+  cachedTokens?: number;
+}
+/**
+ * Per-call overrides for connector (re)creation paths.
+ *
+ * Shared by `AIAgent.swapConnector`, config-input assembly, and the connector
+ * lifecycle factory so the override surface cannot drift between them.
+ */
+type AgentConnectorConfigOverrides = Partial<{
+  cwd: string;
+  model: string;
+  providerContext: ProviderContext;
+  adapterSessionId: string;
+  /**
+   * Provider session the replacement generation should native-resume. Key
+   * presence (not value) selects this over the agent config's start-time
+   * resume target, so an explicit `undefined` builds a fresh connector
+   * instead of silently re-resuming a stale start directive.
+   */
+  resumeAdapterSessionId: string | undefined;
+  mcpSessionContext: McpRuntimeSessionContext | McpSessionContext | LedgerSessionContext;
+  /**
+   * Target reasoning effort for the replacement generation. Key presence (not
+   * value) selects this over the live connector's current effort, so an
+   * explicit `undefined` builds a reasoning-less connector. Adapters may
+   * consume reasoning only at construction/start, so the replacement must be
+   * built with its target effort rather than mutated afterwards.
+   */
+  reasoningEffort: AIReasoningLevel$1 | undefined;
+}>;
+//#endregion
+export { bindProviderAuth as $, SessionToolLedger as $t, AgentTeardownArbiter as A, runBestEffortStage as At, PreparedAdapterAuthRuntime as B, MessageHandle as Bt, NormalizedCallUsage as C, ObservedExitOptions as Ct, AdapterProviderDefinition as D, reportBestEffortStages as Dt, StartAgentOptions as E, exitWasObserved as Et, TeardownSubject as F, unknownTeardown as Ft, AdapterAuthError as G, MessageState as Gt, SuppliedAdapterAuthRuntime as H, NormalizedMessageInput as Ht, CreateConnectorRuntimeOptions as I, CONNECTOR_EXIT_OBSERVATION_MS as It, BoundProviderAuthContext as J, AIModel as Jt, AdapterAuthErrorReason as K, ProcessingState as Kt, AdapterAuthLeaseHandle as L, SWAP_SETTLEMENT_WAIT_MS as Lt, ConnectorReplacementSettlement as M, TeardownReport as Mt, ConnectorSwapAdmission as N, aggregateTeardownReports as Nt, ConfigFactoryInput as O, reportObservedExit as Ot, ConnectorSwapHandover as P, rethrowTeardownFailure as Pt, ResolvedConnectorAuthDelivery as Q, LedgerSessionContext as Qt, AdapterAuthRuntimePreparer as R, AIAgentConnector as Rt, GetCapabilitiesResponsePayload as S, SupersededGeneration as St, SendMessageResponsePayload as T, describeTeardownFailure as Tt, applySuppliedAdapterAuthRuntime as U, normalizeMessageInput as Ut, ResolvedAdapterRuntimeConfig as V, markCompletedWithFinalResult as Vt, prepareAdapterAuthRuntime as W, MessageResult as Wt, ResolvedAdapterAuth as X, ReasoningLevelMap$1 as Xt, ResolveAuthCredentialRefs as Y, AIReasoningLevel$1 as Yt, ResolvedAuthCredentialValues as Z, ISessionToolLedger as Zt, BaseAgentConnectorConfig as _, BaseConnectorTurn as _t, AgentCredentialChangeResponsePayload as a, WireSessionSubjects as at, ContextWindowInput as b, ConnectorSessionConfig as bt, AgentIdentity as c, QueueableTurn as ct, AgentMcpServersSetRequestPayload as d, rejectQueuedHandles as dt, ToolLedgerEntry as en, getOptionalAuthCredentialFields as et, AgentMcpServersSetResponsePayload as f, UserMessageQueue as ft, AgentStartResult as g, TurnSubjects as gt, AgentSendMessageOptions as h, ProceduralTurnState as ht, AgentCredentialChangeRequestPayload as i, WireSessionConfig as it, ClosableConnectorRuntime as j, stageFailure as jt, IAdapterConfigFactory as k, reportRepeatTeardown as kt, AgentInterruptRequestPayload as l, SESSION_CLOSED_QUEUE_ERROR as lt, AgentModelChangeResponsePayload as m, ProceduralTurnConfig as mt, AgentConnectorConfigOverrides as n, ProceduralAgentConnector as nt, AgentCwdChangeRequestPayload as o, MergeResult as ot, AgentModelChangeRequestPayload as p, ProceduralConnectorTurn as pt, BindProviderAuthOptions as q, SendMessageOptions as qt, AgentContext as r, ProceduralConnectorSession as rt, AgentCwdChangeResponsePayload as s, ProcessQueueCallbacks as st, AIAgentConfig as t, resolveBoundProviderAuth as tt, AgentInterruptResponsePayload as u, processQueueMessages as ut, ConnectorSendMessageOptions as v, PauseResult as vt, SendMessageRequestPayload as w, capTeardownEvidence as wt, ExecutionContext as x, GenerationRetirementLedger as xt, ConnectorStartOptions as y, BaseConnectorSession as yt, BoundAdapterRuntimeConfig as z, MessageDeliveryMode$1 as zt };