@makaio/framework 1.0.0-dev-1779046984397

package/dist/types-CD1LJwPc.d.mts

@@ -0,0 +1,1009 @@
+import { z } from "zod";
+import { 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, AgentSchemas, AgentSubjects, JsonValue, McpRuntimeSessionContext, McpSessionContext, McpToolState, Message, MessageBlock, MessageDeliveryMode, MessageDeliveryMode as MessageDeliveryMode$1, MessageInput, MessageOutcome, ProviderContext, ReasoningLevelMap as ReasoningLevelMap$1, SendMessageResultInnerResult, SessionContext, SystemPrompt, ToolListItem } from "@makaio/framework/contracts";
+import { DeferredPromise, TimeoutConfig, TrackedTimeoutConfig } from "@makaio/framework/utils";
+import * as _$emittery from "emittery";
+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 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;
+};
+/**
+ * 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;
+}
+/**
+ * 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
+declare class MessageHandle {
+  readonly messageId: string;
+  readonly message: NormalizedMessageInput;
+  readonly deliveryMode: MessageDeliveryMode;
+  protected readonly deferredCompletion: DeferredPromise<MessageResult>;
+  protected readonly deferredAcknowledgement: DeferredPromise<boolean>;
+  state: MessageState;
+  private isAcknowledged;
+  private completionResult;
+  /** 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?;
+  /** 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>);
+  /**
+   * 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);
+  /**
+   * 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>;
+  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;
+  /**
+   * Mark message turn as completed
+   * @param result - The result message or null if no result available
+   */
+  markCompleted(result: MessageResult): void;
+  waitForAcknowledgment(timeoutMs?: number): Promise<boolean>;
+  waitForCompletion(timeoutMs?: number): Promise<MessageResult>;
+}
+//#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;
+/**
+ * Public options bag used by connectors when creating a message handle.
+ */
+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>;
+}
+/**
+ * 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. */
+  private readonly scopedBus;
+  /** 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): _$emittery.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>;
+  /**
+   * 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.
+   *
+   * Centralizes the pattern used by all connectors:
+   * 1. Generate messageId (use provided or generate UUID)
+   * 2. Create MessageHandle instance
+   * 3. Set adapterSessionId
+   * 4. Call onMessageSent callback
+   * @param message - Normalized user message
+   * @param options - Optional message options (id, delivery mode, history, and turn context)
+   * @returns Initialized MessageHandle ready for enqueueing
+   */
+  protected createMessageHandle(message: NormalizedMessageInput, options?: MessageHandleOptions): MessageHandle;
+  /**
+   * Signal that MCP tools have changed and should be refreshed at the next turn boundary.
+   *
+   * Called by the AIAgent layer when receiving MCP bus events (`mcp.tools.updated`,
+   * `mcp.tools.enabled`). Connectors that support direct-inject tool refresh (e.g.,
+   * `BaseStreamConnector`) override this to set an internal pending-refresh flag.
+   * The default implementation is a no-op so connectors that do not manage MCP tools
+   * directly are unaffected.
+   */
+  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;
+  /** 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;
+  /**
+   * Unresolved provider context (credential refs, not plaintext).
+   * Connectors resolve credentials locally via `resolveConnectorCredentials()`.
+   */
+  providerContext: ProviderContext;
+  /** 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[];
+  /** Provider-specific configuration (non-credential settings). Adapters merge with defaults. */
+  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;
+  /**
+   * 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;
+}
+/**
+ * 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/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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+  /**
+   * Unresolved provider context (credential refs, not plaintext).
+   *
+   * Passed through from the factory input so connectors can call
+   * `resolveConnectorCredentials()` locally during initialization.
+   * Connectors must NOT read plaintext credentials from this field —
+   * they must resolve refs via `resolveConnectorCredentials()`.
+   */
+  providerContext?: ProviderContext;
+  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;
+  /** 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;
+  /** 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;
+}
+/**
+ * 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;
+  /**
+   * Unresolved provider context (credential refs, not plaintext).
+   * Set by the orchestrator before forwarding the startAgent request.
+   * Connectors resolve credentials locally via `resolveConnectorCredentials()`.
+   */
+  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;
+  /** 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[];
+  /** 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[];
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * JSON Schema for structured output.
+   * When present and the adapter declares `structuredOutput` capability,
+   * the adapter enforces this schema at the model level.
+   * Ignored by adapters that lack the capability.
+   */
+  responseSchema?: Record<string, unknown>;
+}
+/**
+ * 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 {
+  /**
+   * 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>;
+}
+/**
+ * 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.
+ */
+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;
+}
+//#endregion
+export { MessageHandle as A, ISessionToolLedger as B, SendMessageRequestPayload as C, IAdapterConfigFactory as D, ConfigFactoryInput as E, ProcessingState as F, SessionToolLedger as H, SendMessageOptions as I, AIModel as L, normalizeMessageInput as M, MessageResult as N, AIAgentConnector as O, MessageState as P, AIReasoningLevel$1 as R, NormalizedCallUsage as S, StartAgentOptions as T, ToolLedgerEntry as U, LedgerSessionContext as V, ConnectorSendMessageOptions as _, AgentCwdChangeRequestPayload as a, ExecutionContext as b, AgentInterruptRequestPayload as c, AgentMcpServersSetResponsePayload as d, AgentModelChangeRequestPayload as f, BaseAgentConnectorConfig as g, AgentStartResult as h, AgentCredentialChangeResponsePayload as i, NormalizedMessageInput as j, MessageDeliveryMode$1 as k, AgentInterruptResponsePayload as l, AgentSendMessageOptions as m, AgentContext as n, AgentCwdChangeResponsePayload as o, AgentModelChangeResponsePayload as p, AgentCredentialChangeRequestPayload as r, AgentIdentity as s, AIAgentConfig as t, AgentMcpServersSetRequestPayload as u, ConnectorStartOptions as v, SendMessageResponsePayload as w, GetCapabilitiesResponsePayload as x, ContextWindowInput as y, ReasoningLevelMap$1 as z };