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

package/dist/types-CJ_QZ1yW.d.mts

@@ -1,1487 +0,0 @@
-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, 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, 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>;
-  /** Monotonically-increasing turn counter for MCP ledger bookkeeping. */
-  private _currentTurnNumber;
-  /** Pending canonical turn number staged by {@link setCanonicalTurnNumber}. */
-  private _pendingCanonicalTurnNumber;
-  /** 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;
-  /**
-   * Gracefully close the agent session.
-   * Unlike abort(), this doesn't trigger AbortController errors.
-   * Use this for normal shutdown; use abort() for emergency termination.
-   */
-  abstract close(): Promise<void>;
-  /**
-   * Get session ID, waiting for provider to generate it if not yet available.
-   * @returns Session ID from provider
-   */
-  abstract getAdapterSessionId(): Promise<string>;
-  /**
-   * Provider-confirmed adapter session ID, or `undefined` when unconfirmed.
-   * Default returns `this.adapterSessionId`; Claude connectors override to
-   * defer until `system.init` confirms the provider-side session.
-   * @returns Confirmed ID or `undefined`
-   */
-  getConfirmedAdapterSessionId(): string | undefined;
-  /**
-   * 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/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;
-}
-/**
- * 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/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/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;
-  /**
-   * 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 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 { NormalizedMessageInput as $, PreparedAdapterAuthRuntime as A, ResolvedAdapterAuth as B, NormalizedCallUsage as C, AdapterAuthLeaseHandle as D, StartAgentOptions as E, AdapterAuthError as F, resolveBoundProviderAuth as G, ResolvedConnectorAuthDelivery as H, AdapterAuthErrorReason as I, IAdapterConfigFactory as J, AdapterProviderDefinition as K, BindProviderAuthOptions as L, SuppliedAdapterAuthRuntime as M, applySuppliedAdapterAuthRuntime as N, AdapterAuthRuntimePreparer as O, prepareAdapterAuthRuntime as P, markCompletedWithFinalResult as Q, BoundProviderAuthContext as R, GetCapabilitiesResponsePayload as S, SendMessageResponsePayload as T, bindProviderAuth as U, ResolvedAuthCredentialValues as V, getOptionalAuthCredentialFields as W, MessageDeliveryMode$1 as X, AIAgentConnector as Y, MessageHandle as Z, BaseAgentConnectorConfig as _, AgentCredentialChangeResponsePayload as a, AIModel as at, ContextWindowInput as b, AgentIdentity as c, ISessionToolLedger as ct, AgentMcpServersSetRequestPayload as d, ToolLedgerEntry as dt, normalizeMessageInput as et, AgentMcpServersSetResponsePayload as f, AgentStartResult as g, AgentSendMessageOptions as h, AgentCredentialChangeRequestPayload as i, SendMessageOptions as it, ResolvedAdapterRuntimeConfig as j, BoundAdapterRuntimeConfig as k, AgentInterruptRequestPayload as l, LedgerSessionContext as lt, AgentModelChangeResponsePayload as m, AgentConnectorConfigOverrides as n, MessageState as nt, AgentCwdChangeRequestPayload as o, AIReasoningLevel$1 as ot, AgentModelChangeRequestPayload as p, ConfigFactoryInput as q, AgentContext as r, ProcessingState as rt, AgentCwdChangeResponsePayload as s, ReasoningLevelMap$1 as st, AIAgentConfig as t, MessageResult as tt, AgentInterruptResponsePayload as u, SessionToolLedger as ut, ConnectorSendMessageOptions as v, SendMessageRequestPayload as w, ExecutionContext as x, ConnectorStartOptions as y, ResolveAuthCredentialRefs as z };