@makaio/framework 1.0.0-dev-1781022866275 → 1.0.0-dev-1781023871421

package/dist/adapters/index.d.mts

@@ -0,0 +1,4202 @@
+import { A as MessageHandle, B as ReasoningLevelMap, C as SendMessageRequestPayload, D as IAdapterConfigFactory, E as ConfigFactoryInput, F as MessageState, H as LedgerSessionContext, I as ProcessingState, L as SendMessageOptions, M as NormalizedMessageInput, N as normalizeMessageInput, O as AIAgentConnector, P as MessageResult, R as AIModel, S as NormalizedCallUsage, T as StartAgentOptions, U as SessionToolLedger, V as ISessionToolLedger, W as ToolLedgerEntry, _ as ConnectorSendMessageOptions, a as AgentCwdChangeRequestPayload, b as ExecutionContext, c as AgentInterruptRequestPayload, d as AgentMcpServersSetResponsePayload, f as AgentModelChangeRequestPayload, g as BaseAgentConnectorConfig, h as AgentStartResult, i as AgentCredentialChangeResponsePayload, j as markCompletedWithFinalResult, k as MessageDeliveryMode, l as AgentInterruptResponsePayload, m as AgentSendMessageOptions, n as AgentContext, o as AgentCwdChangeResponsePayload, p as AgentModelChangeResponsePayload, r as AgentCredentialChangeRequestPayload, s as AgentIdentity, t as AIAgentConfig, u as AgentMcpServersSetRequestPayload, v as ConnectorStartOptions, w as SendMessageResponsePayload, x as GetCapabilitiesResponsePayload, y as ContextWindowInput, z as AIReasoningLevel } from "../types-BCMUtBj1.mjs";
+import { _ as LogImporterConfig, a as CompactionMetadata, b as StorageMessagePayload, c as ExternalToolIdentifiers, d as ImportMetadata, f as ImportSegment, g as LogImporter, h as LogImportTestConfig, l as ExternalToolMeta, m as LogImportSessionContext, n as LogOrchestratorConfig, o as DiscoveryMetadata, p as ImportSegmentLineage, r as ParseFileResult, s as ExternalToolIdentifier, u as ImportCursorPosition, v as NormalizedEvent, x as toImportSegment, y as ProcessLogFileResult } from "../base-orchestrator-wyumsn3b.mjs";
+import { z } from "zod";
+import * as _$_makaio_core0 from "@makaio/framework/core";
+import { CreateBusNamespaceOptions, ExtractSubjectPayload, FilterablePayloadIntersection, HandlerForSubjectDefinition, RequestContext, SchemaRecord, ScopedSubjectDefinition, SubjectDefinition, SubjectRecordFromSchemaRecord } from "@makaio/framework/core";
+import { BusNamespace, IMakaioBus, OnOptions, ScopedBus, ScopedBusFor } from "@makaio/framework/bus";
+import { AIReasoningLevel as AIReasoningLevel$1, AdapterClientRef, AdapterDefinitionContract, AdapterProviderDefinitionContract, AdapterSubjects, AgentSchemas, AgentStarted, AgentSubjects, AgentToolApproveRequest, AgentToolApproveResponse, BlockData, HarnessDefinition, HarnessSubjects, JsonValue, McpResolvedServer, McpRuntimeSessionContext, McpSessionContext, McpToolState, Message, MessageInput, ProviderContext, ProviderDefinitionInput, ReasoningLevelMap as ReasoningLevelMap$1, ResponseSchemaDescriptor, SendMessageRequest, SendMessageResponse, SessionContext, SessionMessageBlock, StartAgentRequest, StartAgentResponse, StepType, SystemPrompt, ToolListItem } from "@makaio/framework/contracts";
+import * as _$_makaio_storage_core0 from "@makaio/framework/storage";
+import * as _$type_fest0 from "type-fest";
+import { JsonObject, SetRequired } from "type-fest";
+import { MessageBlock as MessageBlock$1 } from "@makaio/framework/contracts/shared";
+
+//#region adapters/core/src/log-importer/registry-types.d.ts
+/**
+ * Configuration for log import behavior.
+ *
+ * Shared between runtime config and orchestrator setup.
+ */
+interface LogImportConfig {
+  /** Whether log import is enabled. */
+  enabled: boolean;
+  /** Polling interval for the file watcher in milliseconds. */
+  pollIntervalMs?: number;
+  /** Maximum events to emit per second (rate limiting). */
+  eventsPerSecond?: number;
+  /** Function to check if a session is managed by Makaio (to skip already tracked sessions). */
+  checkMakaioManaged?: (sessionId: string) => Promise<boolean>;
+}
+/**
+ * Minimal interface for log import orchestrators.
+ *
+ * Allows LogImportRegistry to manage lifecycle without coupling
+ * to a specific orchestrator implementation.
+ */
+interface LogImportOrchestrator {
+  /** Whether the orchestrator is running. */
+  isRunning(): boolean;
+  /** Start the orchestrator. */
+  start(): Promise<void>;
+  /** Stop the orchestrator. */
+  stop(): void | Promise<void>;
+  /** Dispose of any resources. */
+  dispose(): void | Promise<void>;
+}
+/** Shared constructor signature for log import orchestrator classes. */
+type LogOrchestratorConstructor = new (config: LogOrchestratorConfig) => LogImportOrchestrator;
+/** Shared constructor signature for log importer classes. */
+type LogImporterConstructor = new (config: LogImporterConfig) => LogImporter<unknown, unknown>;
+/**
+ * Registration metadata for log importers.
+ *
+ * Used by runtimes to wire importers into the LogImportRegistry.
+ * The adapter name is provided by the runtime at registration time via `adapter.name`.
+ */
+interface LogImportRegistration {
+  /** Human-readable name. */
+  displayName: string;
+  /** Log importer class constructor. */
+  LogImporterClass: LogImporterConstructor;
+  /** Optional orchestrator class for full session import mode. */
+  LogOrchestratorClass?: LogOrchestratorConstructor;
+  /**
+   * Optional orchestrator class for shallow discovery mode.
+   *
+   * When present, the runtime uses this class instead of {@link LogOrchestratorClass}
+   * when the adapter's import mode is set to `'discover'`.
+   */
+  LogDiscoveryOrchestratorClass?: LogOrchestratorConstructor;
+  /** Glob pattern for log files. */
+  logFilePattern: string;
+}
+//#endregion
+//#region adapters/core/src/types/provider-definition.d.ts
+/**
+ * Runtime adapter provider definition pairing a serializable provider definition
+ * with optional runtime-only schemas.
+ *
+ * Extends {@link AdapterProviderDefinitionContract} from `@makaio/contracts` which
+ * is the single source of truth for the `definition`, `configSchema`, and
+ * `credentialSchema` fields. All fields are inherited from the contract — this
+ * type exists to give the shape a domain-specific name used throughout
+ * adapter implementation packages and to allow future additions specific to
+ * `ai-adapters-core`.
+ *
+ * Each adapter exports an array of these from its `definition.ts` (via `providers`).
+ * The `definition` field contains serializable data (models, endpoints, etc.).
+ * The schema fields are runtime-only — used for UI form generation, never serialized.
+ * @example
+ * ```typescript
+ * const anthropicProvider: AdapterProviderDefinition = {
+ *   definition: {
+ *     id: 'anthropic',
+ *     name: 'Anthropic',
+ *     endpoints: { anthropic: 'https://api.anthropic.com' },
+ *     defaultModel: 'sonnet',
+ *     availableModels: [...]
+ *   },
+ *   credentialSchema: z.object({
+ *     apiKey: z.string().describe('Anthropic API Key')
+ *   })
+ * };
+ * ```
+ */
+interface AdapterProviderDefinition extends AdapterProviderDefinitionContract {
+  /**
+   * Provider-specific config schema for UI form generation (runtime-only).
+   *
+   * Defines provider-specific configuration fields like debugging flags,
+   * rate limiting options, or provider-specific features.
+   * Not serialized — used for dynamic form generation in the settings UI.
+   */
+  readonly configSchema?: z.ZodObject<z.ZodRawShape>;
+  /**
+   * Provider-specific credential schema for secure credential capture (runtime-only).
+   *
+   * Defines credential fields (apiKey, apiSecret, etc.) for secure input.
+   * Credentials are stored separately via the credential service, never in plain config.
+   * Not serialized — used for dynamic form generation in the settings UI.
+   */
+  readonly credentialSchema?: z.ZodObject<z.ZodRawShape>;
+}
+//#endregion
+//#region adapters/core/src/types/ai-adapter-init-options.d.ts
+/**
+ * Platform-provided defaults injected by the runtime.
+ * These are the lowest priority and will be overridden by request-level values.
+ */
+interface PlatformDefaults {
+  /** Default working directory for agent execution (e.g., os.tmpdir() on Node.js) */
+  cwd?: string;
+  /** Default environment variables */
+  env?: Record<string, string>;
+}
+/**
+ * Initialization options for `AIAdapter.init()`.
+ * @example
+ * ```typescript
+ * await adapter.init({
+ *   defaultModel: "claude-3.5-sonnet",
+ *   providerOptions: { apiKey: process.env.API_KEY }
+ * });
+ * ```
+ * @see {@link AIAdapterPromptOptions} for per-message config
+ * @see [Creating Adapters Guide](../../docs/creating-adapters.md)
+ */
+interface AIAdapterInitOptions {
+  /** Default model when not specified per-message. Provider-specific identifier. */
+  defaultModel?: string;
+  /** Provider-specific config (API keys, base URLs, defaults, etc.). Type explicitly in adapter implementations. */
+  providerOptions?: unknown;
+  adapterId?: string;
+  /**
+   * Platform-provided defaults (cwd, env, etc.).
+   * Lowest priority - overridden by request values.
+   * Injected by runtime during adapter initialization.
+   */
+  platformDefaults?: PlatformDefaults;
+  /**
+   * Log import configuration for external session imports.
+   */
+  logImport?: LogImportConfig;
+  /**
+   * Provider definitions from the adapter definition.
+   * Contains provider definitions with available models for context window lookup.
+   * Injected by runtime during adapter initialization.
+   */
+  definitionProviders?: AdapterProviderDefinition[];
+  /** Client identifier for the application this adapter belongs to (e.g., 'claude-code', 'codex'). Omit for API-only adapters. */
+  clientId?: string;
+}
+//#endregion
+//#region adapters/core/src/utils/safeJsonStringify.d.ts
+/**
+ * Safely serialize a value to JSON string.
+ *
+ * Handles BigInt values, circular references, and non-serializable types
+ * without throwing. Circular nodes are replaced with `'[Circular]'` rather
+ * than aborting the entire serialization. Falls back to `String(value)` when
+ * JSON serialization is not possible at all.
+ * @param value - The value to serialize
+ * @returns JSON string representation or a fallback string on failure
+ */
+declare function safeJsonStringify(value: unknown): string;
+//#endregion
+//#region adapters/core/src/utils/serializeTurnContext.d.ts
+/**
+ * A single serialized context entry ready for adapter-specific formatting.
+ */
+interface SerializedContextBlock {
+  /** XML tag name, e.g. 'skills', 'cwdChange' */
+  readonly tag: string;
+  /** Pre-formatted content (Markdown for skills/catalog, JSON for others) */
+  readonly content: string;
+}
+/**
+ * Format one context block as an XML-tagged text block.
+ * @param tag - Block tag name (sanitized before rendering)
+ * @param content - Block content (XML-escaped before rendering)
+ * @returns XML-tagged text block safe for prompt injection
+ */
+declare function formatContextBlockAsText(tag: string, content: string): string;
+/**
+ * Serialize a MessageHandle's turnContext into ordered text blocks.
+ *
+ * All non-null, non-undefined keys are serialized. The `skillCatalog`,
+ * `skills`, and `contextRules` keys get dedicated markdown formatting;
+ * all other keys are JSON-serialized.
+ *
+ * Each adapter converts these blocks to its wire format:
+ * - Claude SDK: each block → prependContextBlock(msg, tag, content)
+ * - Anthropic/OpenAI: join and prepend to user message
+ * - Gemini: push as requestPart
+ * - CLI/Copilot: prepend to prompt string
+ * - Codex: push as userInput
+ * @param turnContext - The context record from MessageHandle.turnContext
+ * @returns Ordered blocks: skillCatalog, skills, contextRules, then remaining keys alphabetical.
+ *          Empty when turnContext is nullish or empty.
+ */
+declare function serializeTurnContext(turnContext: Record<string, JsonValue | undefined> | undefined): SerializedContextBlock[];
+/**
+ * Format serialized context blocks as XML-tagged text.
+ * Convenience for adapters that prepend context as plain text to the user message.
+ * @param blocks - Blocks from serializeTurnContext()
+ * @returns Single string with each block wrapped in XML tags, separated by newlines.
+ *          Empty string when no blocks.
+ */
+declare function formatContextBlocksAsText(blocks: SerializedContextBlock[]): string;
+//#endregion
+//#region adapters/core/src/types/capabilities.d.ts
+/**
+ * Extensible registry of all known AI adapter capabilities.
+ *
+ * This interface can be extended by external packages (extensions) via declaration merging:
+ * @example
+ * ```typescript
+ * // In a plugin package
+ * declare module '@makaio/framework/adapters' {
+ *   interface AIAdapterCapabilityRegistry {
+ *     customAuth: {
+ *       oauth: boolean;
+ *       saml: boolean;
+ *     };
+ *   }
+ * }
+ *
+ * // Now these work automatically:
+ * caps.hasAll(['customAuth:oauth'])  // ✅ Type-safe
+ * caps.customAuthOauth               // ✅ Auto-generated property
+ * ```
+ */
+interface AIAdapterCapabilityRegistry {
+  systemPrompt: {
+    override: boolean;
+    append: boolean;
+  };
+  session: {
+    resume: boolean;
+    fork: boolean;
+  };
+  chat: {
+    inTurnMessages: boolean;
+  };
+  modelSwitchInSession: boolean;
+  streaming: boolean;
+  tools: boolean;
+  vision: boolean;
+  /**
+   * Adapter supports native structured output (JSON schema enforcement
+   * at the model level via response_format or equivalent).
+   *
+   * Sub-capability:
+   * - `structuredOutput:strict` — adapter enforces strict schema validation
+   *   (no additional properties, all fields required). Corresponds to
+   *   `response_format: { type: 'json_schema', json_schema: { strict: true } }`
+   *   in the OpenAI API.
+   */
+  structuredOutput: {
+    strict: boolean;
+  };
+}
+/**
+ * Recursively builds capability path strings from registry.
+ * Example: `'systemPrompt'` | `'systemPrompt:override'` | `'systemPrompt:append'`
+ * @internal
+ */
+type CapabilityPath<T> = T extends object ? { [K in keyof T]: K extends string ? T[K] extends boolean ? K : T[K] extends object ? `${K}:${CapabilityPath<T[K]>}` | K : K : never }[keyof T] : never;
+/** Union of all valid capability strings from the registry. */
+type ValidCapability = CapabilityPath<AIAdapterCapabilityRegistry>;
+/**
+ * Converts capability path to camelCase property name.
+ * Example: `'session:fork'` → `'sessionFork'`
+ * @internal
+ */
+type PathToPropertyName<S extends string> = S extends `${infer First}:${infer Rest}` ? `${First}${PathToPropertyName<Capitalize<Rest>>}` : S;
+/** Flattens registry into camelCase boolean properties. @internal */
+type GeneratedCapabilityProperties = { [P in ValidCapability as PathToPropertyName<P>]?: boolean };
+/**
+ * Runtime-queryable capabilities object returned by AI adapters.
+ *
+ * Auto-generates boolean properties from {@link AIAdapterCapabilityRegistry}:
+ * - `'systemPrompt'` → `caps.systemPrompt`
+ * - `'systemPrompt:override'` → `caps.systemPromptOverride`
+ * - `'session:fork'` → `caps.sessionFork`
+ * @remarks
+ * Capabilities are **optional and declarative**:
+ * - Adapters declare only what their underlying service supports
+ * - Platform checks capabilities before using optional features
+ * - No "not implemented" exceptions
+ * - Plugin-extendable via declaration merging
+ * @example
+ * ```typescript
+ * const caps = adapter.getCapabilities();
+ *
+ * // Single checks (most common)
+ * if (caps.vision) { ... }
+ * if (caps.tools && caps.vision) { ... }
+ *
+ * // Batch checks (explicit AND/OR)
+ * if (caps.hasAll(['vision', 'tools'])) { ... }
+ * if (caps.hasAny(['session:resume', 'session:fork'])) { ... }
+ * ```
+ * @see {@link AIAdapterCapabilityRegistry} - Schema and plugin extensibility
+ * @see {@link parseAIAdapterCapabilities} - Create instances from strings
+ */
+type AIAdapterCapabilities = GeneratedCapabilityProperties & {
+  /** Check if ALL specified capabilities are present (AND logic) */hasAll(capabilities: ValidCapability[]): boolean; /** Check if ANY of the specified capabilities are present (OR logic) */
+  hasAny(capabilities: ValidCapability[]): boolean;
+};
+type AIAdapterCapability = keyof GeneratedCapabilityProperties;
+//#endregion
+//#region adapters/core/src/utils/capabilities.d.ts
+/**
+ * Parses capability strings into a typed AIAdapterCapabilities object.
+ *
+ * Transforms strings (e.g., from adapter.json) into runtime-queryable object with:
+ * - Auto-generated camelCase boolean properties (`'session:fork'` → `caps.sessionFork`)
+ * - `hasAll()` and `hasAny()` methods for batch checks
+ * @example
+ * ```typescript
+ * const caps = parseAIAdapterCapabilities(['systemPrompt', 'vision', 'session:resume']);
+ *
+ * caps.systemPrompt     // true
+ * caps.sessionResume    // true
+ * caps.hasAll(['vision', 'systemPrompt'])  // true
+ * ```
+ * @param caps - Capability strings declared by the adapter
+ * @returns Capabilities object with auto-generated properties and batch methods
+ * @see {@link AIAdapterCapabilities} - Runtime API
+ * @see {@link AIAdapterCapabilityRegistry} - Schema for custom capabilities
+ */
+declare function parseAIAdapterCapabilities(caps: string[]): AIAdapterCapabilities;
+//#endregion
+//#region adapters/core/src/utils/cleanEnvForAdapter.d.ts
+type AdapterEnv = Record<string, string | undefined>;
+/**
+ * Options for adapter environment cleanup.
+ */
+interface CleanEnvForAdapterOptions {
+  /**
+   * Additional environment variables to remove from the inherited environment.
+   */
+  omitEnvVars?: readonly string[];
+}
+/**
+ * Clean environment variables for adapter child processes.
+ *
+ * Removes variables that should not be inherited by spawned adapter
+ * processes (for example Claude Code SDK and CLI wrappers).
+ *
+ * SEAM: Extend this list as additional problematic environment variables
+ * are discovered across adapter implementations.
+ * @param env - Optional base environment to clean (defaults to `undefined`)
+ * @param options - Additional cleanup options
+ * @returns Cleaned environment object with problematic variables removed.
+ * @example
+ * ```typescript
+ * const session = query({
+ *   options: {
+ *     env: cleanEnvForAdapter(customEnv),
+ *   },
+ * });
+ * ```
+ */
+declare function cleanEnvForAdapter(env?: AdapterEnv, options?: CleanEnvForAdapterOptions): Record<string, string>;
+//#endregion
+//#region adapters/core/src/utils/discriminated-handlers.d.ts
+/**
+ * Type-safe emit function for discriminated handlers.
+ * Each call is validated at compile time to ensure payload matches subject.
+ *
+ * The emit function signature matches AIAgent.emitGlobal, allowing handlers
+ * to emit events without knowing whether they're running in live agent context
+ * or log import context.
+ */
+type TypedEmitFn = <S extends SubjectDefinition>(subject: S, payload: Omit<ExtractSubjectPayload<S>, keyof AgentContext>) => void | Promise<void>;
+/**
+ * Synchronous variant of TypedEmitFn.
+ * Use with processDiscriminatedItemsSync to enforce sync handlers at compile time.
+ */
+type SyncTypedEmitFn = <S extends SubjectDefinition>(subject: S, payload: Omit<ExtractSubjectPayload<S>, keyof AgentContext>) => void;
+/**
+ * Handler function that receives narrowed payload and typed emit.
+ * @typeParam TPayload - The narrowed payload type (discriminated union member)
+ * @typeParam TEmit - The emit function type (defaults to TypedEmitFn)
+ */
+type DiscriminatedHandler<TPayload, TEmit extends TypedEmitFn = TypedEmitFn> = (payload: TPayload, emit: TEmit) => void | Promise<void>;
+/**
+ * Synchronous handler that cannot return a Promise.
+ * Use with processDiscriminatedItemsSync to catch async handlers at compile time.
+ */
+type SyncDiscriminatedHandler<TPayload> = (payload: TPayload, emit: SyncTypedEmitFn) => void;
+/**
+ * Handlers map with discriminator-narrowed payload types.
+ *
+ * Each key is a possible value of the discriminator property,
+ * and each handler receives the narrowed payload type for that discriminator value.
+ * @typeParam TPayload - The full discriminated union type
+ * @typeParam TDiscriminator - The property key used to discriminate union members
+ */
+type DiscriminatedHandlersMap<TPayload extends Record<string, unknown>, TDiscriminator extends keyof TPayload & string> = { [K in TPayload[TDiscriminator] & string]?: DiscriminatedHandler<Extract<TPayload, { [P in TDiscriminator]: K }>> };
+/**
+ * Synchronous handlers map for compile-time async prevention.
+ * Use with defineDiscriminatedHandlersSync and processDiscriminatedItemsSync.
+ */
+type SyncDiscriminatedHandlersMap<TPayload extends Record<string, unknown>, TDiscriminator extends keyof TPayload & string> = { [K in TPayload[TDiscriminator] & string]?: SyncDiscriminatedHandler<Extract<TPayload, { [P in TDiscriminator]: K }>> };
+/**
+ * Configuration returned by defineDiscriminatedHandlers.
+ *
+ * Encapsulates the discriminator key and handler map for use with
+ * processDiscriminatedItems.
+ * @typeParam TPayload - The full discriminated union type
+ * @typeParam TDiscriminator - The property key used to discriminate union members
+ */
+interface DiscriminatedHandlersConfig<TPayload extends Record<string, unknown>, TDiscriminator extends keyof TPayload & string> {
+  discriminator: TDiscriminator;
+  handlers: DiscriminatedHandlersMap<TPayload, TDiscriminator>;
+}
+/**
+ * Synchronous configuration for compile-time async prevention.
+ * Use with defineDiscriminatedHandlersSync and processDiscriminatedItemsSync.
+ */
+interface SyncDiscriminatedHandlersConfig<TPayload extends Record<string, unknown>, TDiscriminator extends keyof TPayload & string> {
+  discriminator: TDiscriminator;
+  handlers: SyncDiscriminatedHandlersMap<TPayload, TDiscriminator>;
+}
+/**
+ * Factory to create typed discriminated handlers.
+ *
+ * This function provides compile-time validation that handlers receive
+ * correctly narrowed payload types based on the discriminator value.
+ * @param discriminator - The property key used to discriminate union members
+ * @param handlers - Map of discriminator values to handler functions
+ * @returns Configuration object for use with processDiscriminatedItems
+ * @example
+ * ```typescript
+ * // Define handlers with full type safety
+ * const handlers = defineDiscriminatedHandlers<BetaContentBlock, 'type'>('type', {
+ *   text: (block, emit) => {
+ *     // block is narrowed to BetaTextBlock
+ *     emit(AgentSubjects.message, { content: block.text });
+ *   },
+ *   thinking: (block, emit) => {
+ *     // block is narrowed to BetaThinkingBlock
+ *     emit(AgentSubjects.reasoning, { content: block.thinking });
+ *   },
+ *   tool_use: (block, emit) => {
+ *     // block is narrowed to BetaToolUseBlock
+ *     emit(AgentSubjects.tool.use, {
+ *       toolName: block.name,
+ *       args: block.input,
+ *       toolCallId: block.id,
+ *     });
+ *   },
+ * });
+ * ```
+ */
+declare function defineDiscriminatedHandlers<TPayload extends Record<string, unknown>, TDiscriminator extends keyof TPayload & string = keyof TPayload & string>(discriminator: TDiscriminator, handlers: DiscriminatedHandlersMap<TPayload, TDiscriminator>): DiscriminatedHandlersConfig<TPayload, TDiscriminator>;
+/**
+ * Factory for sync-only handlers with compile-time async prevention.
+ *
+ * Use this instead of defineDiscriminatedHandlers when handlers will be
+ * used with processDiscriminatedItemsSync. Async handlers will cause
+ * compile-time errors rather than runtime errors.
+ * @param discriminator - Property key used to discriminate payload types
+ * @param handlers - Map of discriminator values to sync handler functions
+ * @returns Config object for processDiscriminatedItemsSync
+ */
+declare function defineDiscriminatedHandlersSync<TPayload extends Record<string, unknown>, TDiscriminator extends keyof TPayload & string = keyof TPayload & string>(discriminator: TDiscriminator, handlers: SyncDiscriminatedHandlersMap<TPayload, TDiscriminator>): SyncDiscriminatedHandlersConfig<TPayload, TDiscriminator>;
+/**
+ * Process items through discriminated handlers.
+ *
+ * Iterates over items (or processes single item), reads discriminator,
+ * and calls appropriate handler with typed emit. Items without a matching
+ * handler are silently skipped.
+ * @param items - Single item or array of items to process
+ * @param config - Handler configuration from defineDiscriminatedHandlers
+ * @param emit - Typed emit function (can be emitGlobal, collection push, etc.)
+ * @example
+ * ```typescript
+ * // Agent usage - emit directly
+ * await processDiscriminatedItems(
+ *   content,
+ *   CONTENT_BLOCK_HANDLERS,
+ *   (subject, payload) => this.emitGlobal(subject, payload),
+ * );
+ *
+ * // Importer usage - collect events with enrichment
+ * const events: NormalizedEvent[] = [];
+ * await processDiscriminatedItems(
+ *   content,
+ *   CONTENT_BLOCK_HANDLERS,
+ *   (subject, payload) => {
+ *     events.push({ subject, payload: { ...basePayload, ...payload } });
+ *   },
+ * );
+ * ```
+ */
+declare function processDiscriminatedItems<TPayload extends Record<string, unknown>, TDiscriminator extends keyof TPayload & string>(items: TPayload | TPayload[], config: DiscriminatedHandlersConfig<TPayload, TDiscriminator>, emit: TypedEmitFn): Promise<void>;
+/**
+ * Synchronous variant of processDiscriminatedItems.
+ *
+ * Two usage modes:
+ * 1. With SyncDiscriminatedHandlersConfig: Full compile-time async prevention
+ * 2. With DiscriminatedHandlersConfig: Runtime-only async detection (for shared handlers)
+ * @param items - Single item or array of items to process
+ * @param config - Handler configuration (sync or async)
+ * @param emit - Synchronous emit function
+ * @throws Error if a handler returns a Promise
+ */
+declare function processDiscriminatedItemsSync<TPayload extends Record<string, unknown>, TDiscriminator extends keyof TPayload & string>(items: TPayload | TPayload[], config: SyncDiscriminatedHandlersConfig<TPayload, TDiscriminator>, emit: SyncTypedEmitFn): void;
+/**
+ * Overload for shared handlers defined with defineDiscriminatedHandlers.
+ * Provides runtime-only async detection (no compile-time safety).
+ * @param items - Single item or array of items to process
+ * @param config - Discriminated handlers config from defineDiscriminatedHandlers
+ * @param emit - Typed emit function for publishing events
+ */
+declare function processDiscriminatedItemsSync<TPayload extends Record<string, unknown>, TDiscriminator extends keyof TPayload & string>(items: TPayload | TPayload[], config: DiscriminatedHandlersConfig<TPayload, TDiscriminator>, emit: SyncTypedEmitFn): void;
+//#endregion
+//#region adapters/core/src/utils/normalizeEnvValue.d.ts
+/**
+ * Normalize blank environment values to `undefined`.
+ * @param value - Raw environment value
+ * @returns Trimmed value when non-empty
+ */
+declare function normalizeEnvValue(value: string | undefined): string | undefined;
+//#endregion
+//#region adapters/core/src/utils/resolveTestConfig.d.ts
+/** Fields injected by resolveTestConfig */
+type InjectedTestFields<TBus extends ScopedBus<string>> = {
+  agentId: string;
+  adapterId: string;
+  adapterName: string;
+  bus: TBus;
+  /**
+   * Unresolved provider context for conformance tests.
+   *
+   * When a `testProviderDefinition` is supplied, credential refs are built
+   * from the definition's `credentialEnvVars` mapping using `env:VAR_NAME`
+   * format. Connectors resolve these refs locally via `resolveConnectorCredentials()`
+   * — which reads from `process.env` for `env:` refs — mirroring the full
+   * credential-resolution chain without requiring a database or bus handlers.
+   *
+   * Falls back to a minimal sentinel (empty `credentialRefs`) when no definition
+   * is provided.
+   */
+  providerContext: ProviderContext;
+};
+/** Result type: options merged with injected fields (handles undefined options) */
+type ResolvedTestConfig<TOptions, TBus extends ScopedBus<string>> = (TOptions extends undefined ? object : TOptions) & InjectedTestFields<TBus>;
+/**
+ * Build an unresolved provider context for conformance tests.
+ *
+ * When a provider definition is supplied, builds credential refs in `env:VAR_NAME`
+ * format from `credentialEnvVars`. Connectors resolve these refs locally via
+ * `resolveConnectorCredentials()`. Otherwise returns a minimal sentinel.
+ * @param definition - Optional provider definition to build credential refs from
+ * @param ambientCredentialDefinitions - Provider definitions whose credential
+ *   env vars should be stripped from ambient subprocess environments
+ * @returns Fresh unresolved provider context per call to prevent cross-test mutation leaks
+ */
+declare function createTestProviderContext(definition?: ProviderDefinitionInput, ambientCredentialDefinitions?: readonly ProviderDefinitionInput[]): ProviderContext;
+/**
+ * Resolves test configuration by adding required fields (bus, agentId, adapterId, adapterName, providerContext).
+ *
+ * When `testProviderDefinition` is supplied, credential refs and endpoint overrides
+ * are built from the definition's `credentialEnvVars` and `endpoints` — so
+ * conformance tests can run against real providers without the full orchestrator.
+ * @param options - Partial test agent options (undefined = empty config)
+ * @param bus - Scoped bus instance for the adapter
+ * @param testProviderDefinition - Optional provider definition for credential ref building
+ * @param ambientCredentialDefinitions - Provider definitions whose credential
+ *   env vars should be stripped from ambient subprocess environments
+ * @returns Complete test config with required fields injected
+ */
+declare function resolveTestConfig<TOptions extends CreateTestAgentOptions | undefined, TBus extends ScopedBus<string>>(options: TOptions, bus: TBus, testProviderDefinition?: ProviderDefinitionInput, ambientCredentialDefinitions?: readonly ProviderDefinitionInput[]): ResolvedTestConfig<TOptions, TBus>;
+//#endregion
+//#region adapters/core/src/utils/resolveConformanceTestPreset.d.ts
+/** Default environment variable for selecting a conformance provider preset. */
+declare const MAKAIO_CONFORMANCE_PROVIDER_ENV = "MAKAIO_CONFORMANCE_PROVIDER";
+/** Default environment variable for overriding the primary conformance model. */
+declare const MAKAIO_CONFORMANCE_PRIMARY_MODEL_ENV = "MAKAIO_CONFORMANCE_PRIMARY_MODEL";
+/** Default environment variable for overriding the secondary conformance model. */
+declare const MAKAIO_CONFORMANCE_SECONDARY_MODEL_ENV = "MAKAIO_CONFORMANCE_SECONDARY_MODEL";
+/** Environment variable used by the conformance runner to pass provider definitions into worker forks. */
+declare const MAKAIO_CONFORMANCE_PROVIDER_DEFINITIONS_ENV = "MAKAIO_CONFORMANCE_PROVIDER_DEFINITIONS";
+/** Reads an environment variable value by name. */
+type ConformanceEnvReader = (name: string) => string | undefined;
+/**
+ * Options for resolving the provider/model preset used by conformance tests.
+ */
+interface ResolveConformanceTestPresetOptions {
+  /** Adapter name used in configuration error messages. */
+  adapterName: string;
+  /** Provider ID used when no env override is supplied. */
+  defaultProviderId: string;
+  /** Provider IDs accepted by this adapter's conformance config. */
+  providerIds: readonly string[];
+  /** Full provider definitions supplied by the conformance harness. */
+  providerDefinitions?: readonly ProviderDefinitionInput[];
+  /** Default reasoning effort to attach to resolved model refs. */
+  reasoningEffort?: TestModelRef['reasoningEffort'];
+  /** Environment reader, injectable for tests. */
+  readEnv?: ConformanceEnvReader;
+  /** Provider override env var name. */
+  providerEnvVar?: string;
+  /** Primary model override env var name. */
+  primaryModelEnvVar?: string;
+  /** Secondary model override env var name. */
+  secondaryModelEnvVar?: string;
+}
+/**
+ * Resolved conformance provider/model preset.
+ */
+interface ResolvedConformanceTestPreset {
+  /** Provider selected for this test run. */
+  provider: ProviderDefinitionInput;
+  /** All accepted provider definitions, including the selected provider. */
+  providers: readonly ProviderDefinitionInput[];
+  /** Provider context derived from the selected provider. */
+  providerContext: ProviderContext;
+  /** Fast/cheap model used by most conformance tests. */
+  primaryModel: TestModelRef;
+  /** Second model used by lifecycle mutation tests. */
+  secondaryModel: TestModelRef;
+}
+/**
+ * Resolve a conformance test provider preset from defaults plus MAKAIO_CONFORMANCE_* overrides.
+ *
+ * Provider, primary model, secondary model, credentials, and endpoint overrides
+ * are resolved together so CI can swap test economics without changing local
+ * OAuth/default behavior.
+ * @param options - Resolver inputs and optional env variable names
+ * @returns Provider/model/context preset for adapter `createTestConfig()`
+ */
+declare function resolveConformanceTestPreset(options: ResolveConformanceTestPresetOptions): ResolvedConformanceTestPreset;
+//#endregion
+//#region adapters/core/src/utils/resolveDisabledNativeTools.d.ts
+/** Result of an optional harness lookup — either unhandled or resolved. */
+type OptionalHarnessResult = Promise<{
+  handled: false;
+} | {
+  handled: true;
+  data: HarnessDefinition;
+}>;
+/**
+ * Minimal requester contract for harness lookups.
+ *
+ * Supports both ID-based lookup (`HarnessSubjects.get`) and adapter-scoped
+ * default lookup (`HarnessSubjects.getDefault`).
+ */
+interface HarnessRequester {
+  requestOptional(subject: typeof HarnessSubjects.get, payload: {
+    id: string;
+  }): OptionalHarnessResult;
+  requestOptional(subject: typeof HarnessSubjects.getDefault, payload: {
+    adapterName?: string;
+    clientId?: string;
+  }): OptionalHarnessResult;
+}
+/**
+ * Resolve SDK-native tool names disabled by the active harness for an adapter.
+ *
+ * When `harnessId` is provided, fetches that specific harness by ID.
+ * Otherwise falls back to the adapter's default harness via `adapterName` and
+ * optional `clientId` so that client-scoped harnesses are considered.
+ *
+ * Uses optional request semantics so callers can run without harness registration
+ * (for example, in lightweight test runtimes).
+ * @param requester - Bus-like requester supporting requestOptional for harness subjects
+ * @param adapterName - Adapter name used to look up the default harness (fallback path)
+ * @param harnessId - Optional explicit harness ID; takes precedence over the default lookup
+ * @param clientId - Optional client identifier for client-scoped default harness lookup
+ * @returns Disabled native tool names, or an empty array when unavailable
+ */
+declare function resolveDisabledNativeTools(requester: HarnessRequester, adapterName: string, harnessId?: string, clientId?: string): Promise<readonly string[]>;
+//#endregion
+//#region adapters/core/src/utils/formatMessageHistoryAsTranscript.d.ts
+/**
+ * Formats message history as a human-readable conversation transcript.
+ *
+ * Converts structured Message[] into plain text format:
+ * ```
+ * User: Hello, my name is Alice
+ * Assistant: Nice to meet you, Alice!
+ * ```
+ *
+ * This avoids exposing JSON structure to the LLM, which can trigger
+ * meta-analysis of the format rather than natural conversation continuation.
+ * @param history - Array of Message objects with role and blocks
+ * @returns Human-readable transcript string
+ */
+declare function formatMessageHistoryAsTranscript(history: Message[]): string;
+//#endregion
+//#region adapters/core/src/utils/serialize-block-to-text.d.ts
+/**
+ * Serialize a {@link MessageBlock} to plain text for contexts where native
+ * block rendering is unavailable — for example, media blocks in text positions,
+ * or history serialization for providers that only accept string content.
+ *
+ * - `text` and `reasoning` blocks return their content verbatim.
+ * - `tool_call` blocks emit a bracketed label followed by JSON-serialized args.
+ * - `tool_output` blocks emit a bracketed label with the call ID and output body.
+ * - `image` and `document` blocks emit a static placeholder.
+ * - `attachment` blocks emit the display name when present, otherwise the file name.
+ * @param block - The message block to serialize.
+ * @returns Plain-text representation of the block.
+ */
+declare function serializeBlockToText(block: MessageBlock$1): string;
+//#endregion
+//#region adapters/core/src/connector/base-connector-session.d.ts
+/**
+ * Configuration for a connector session.
+ * @typeParam TBus - Scoped bus type for adapter namespace
+ */
+interface ConnectorSessionConfig<TBus extends ScopedBus<string> = ScopedBus<string>> {
+  bus: TBus;
+  adapterId: string;
+  adapterName: string;
+  cwd: string;
+  model: string;
+  env: Record<string, string>;
+}
+/**
+ * Interface for turn-like objects that support pause/abort operations.
+ * Allows base session class to work with different turn implementations.
+ */
+interface PausableTurn {
+  pause(): Promise<unknown>;
+}
+/**
+ * Base abstract class for connector session implementations.
+ *
+ * Sessions manage SDK query lifecycle across multiple turns:
+ * - SDK connection management
+ * - Turn creation and coordination
+ * - Session ID management
+ *
+ * Each adapter implements its own session subclass.
+ * @typeParam TConfig - Configuration type extending ConnectorSessionConfig
+ */
+declare abstract class BaseConnectorSession<TConfig extends ConnectorSessionConfig = ConnectorSessionConfig> {
+  protected readonly config: TConfig;
+  protected readonly bus: TConfig['bus'];
+  protected sessionId?: string;
+  protected currentTurn?: PausableTurn;
+  constructor(config: TConfig);
+  /**
+   * Abort the session and cleanup resources.
+   * Pauses the current turn if one is active.
+   */
+  abort(): Promise<void>;
+  /**
+   * Send a message to the provider.
+   * Not used - subclasses should implement processQueue instead.
+   * @param _message - Unused message parameter
+   * @param _options - Unused options parameter
+   */
+  sendMessage(_message: unknown, _options?: unknown): Promise<void>;
+  /**
+   * Get the adapter session ID.
+   * @returns The session ID from the provider
+   */
+  getAdapterSessionId(): Promise<string>;
+}
+//#endregion
+//#region adapters/core/src/connector/base-connector-turn.d.ts
+/**
+ * Result of pausing a turn.
+ * @typeParam TState - Turn state type
+ */
+interface PauseResult<TState = string> {
+  /** The state the turn was in before pausing */
+  stateBeforePause: TState;
+  /** Whether the turn had already ended when pause was requested */
+  turnEnded: boolean;
+}
+/**
+ * Base abstract class for connector turn implementations.
+ *
+ * Turns manage the state machine for a single user message:
+ * - State transitions (idle to turn_started to step_started to ...)
+ * - Pause/resume mechanics
+ * - Safe boundary detection for immediate messages
+ * - Message handle delegation (acknowledgment, completion)
+ *
+ * Each adapter implements its own turn subclass with adapter-specific
+ * state handling and SDK integration.
+ * @typeParam TState - Turn state enum type (string union)
+ */
+declare abstract class BaseConnectorTurn<TState extends string = string> {
+  protected state: TState;
+  protected readonly bus: ScopedBus<string>;
+  protected readonly adapterId: string;
+  protected readonly adapterName: string;
+  protected stateChangedCallback?: (oldState: TState, newState: TState) => Promise<void> | void;
+  /**
+   * Active message handle for this turn.
+   * Subclasses must provide this handle for message lifecycle management.
+   */
+  protected abstract activeMessageHandle: MessageHandle;
+  constructor(bus: ScopedBus<string>, adapterId: string, adapterName: string, initialState: TState);
+  /**
+   * Pause the turn at next safe boundary.
+   * @returns Pause result indicating whether turn already ended
+   */
+  abstract pause(): Promise<PauseResult<TState>>;
+  /**
+   * Resume the paused turn with optional additional message.
+   * @param message - Optional message to inject when resuming
+   */
+  abstract resume(message?: unknown): Promise<void>;
+  /**
+   * Check if turn is currently paused.
+   */
+  abstract isPaused(): boolean;
+  /**
+   * Register callback for state changes.
+   * @param cb - Callback to invoke on state transitions
+   */
+  onStateChanged(cb: (oldState: TState, newState: TState) => Promise<void> | void): void;
+  /**
+   * Transition to new state and notify listeners.
+   * Template method for shared state transition pattern.
+   *
+   * NOTE: Subclasses should use their typed namespace subjects for emission.
+   * This is a template - concrete implementation in adapter-specific Turn classes.
+   * @param newState - New state to transition to
+   */
+  protected transitionTo(newState: TState): Promise<void>;
+  /**
+   * Emit state change event - implemented by subclass with typed subjects.
+   * @param oldState - Previous state
+   * @param newState - New state
+   */
+  protected abstract emitStateChange(oldState: TState, newState: TState): Promise<void>;
+  /**
+   * Get current turn state.
+   * @returns Current turn state
+   */
+  getState(): TState;
+  /**
+   * Get the message handle for this turn.
+   * @returns The message handle for this turn
+   */
+  getMessageHandle(): MessageHandle;
+  /**
+   * Mark message handle as acknowledged.
+   */
+  markAcknowledged(): void;
+  /**
+   * Mark message handle as completed.
+   * @param result - The completion result with outcome and optional result/error
+   */
+  markCompleted(result: {
+    outcome: string;
+    result?: unknown;
+    error?: unknown;
+  }): void;
+}
+//#endregion
+//#region adapters/core/src/connector/procedural-connector-turn.d.ts
+/**
+ * Typed subject references for turn lifecycle events.
+ *
+ * Each adapter provides its namespace-specific subjects when constructing
+ * a ProceduralConnectorTurn. The subjects must all accept the same
+ * TurnStateChangedPayload shape.
+ * @typeParam TSubject - The subject definition type for the adapter's bus
+ */
+interface TurnSubjects<TSubject = ScopedSubjectDefinition> {
+  state_changed: TSubject;
+  turn_started: TSubject;
+  step_started: TSubject;
+  step_finished: TSubject;
+  turn_finished: TSubject;
+}
+/**
+ * Standard turn state type for procedural adapters.
+ *
+ * Procedural adapters (Gemini, OpenAI, Copilot) use abort+restart
+ * rather than true pause/resume. Their state machine is:
+ * idle to turn_started to step_started to step_finished to turn_finished
+ */
+type ProceduralTurnState = 'idle' | 'turn_started' | 'step_started' | 'step_finished' | 'turn_finished';
+/**
+ * Configuration for ProceduralConnectorTurn.
+ * @typeParam TBus - Scoped bus type for the adapter
+ * @typeParam TSubject - Subject definition type
+ */
+interface ProceduralTurnConfig<TBus extends ScopedBus<string>, TSubject> {
+  bus: TBus;
+  adapterId: string;
+  adapterName: string;
+  agentId: string;
+  messageHandle: MessageHandle;
+  turnSubjects: TurnSubjects<TSubject>;
+}
+/**
+ * Base turn implementation for procedural adapters (Gemini, OpenAI, Copilot).
+ *
+ * These adapters share an abort+restart pattern rather than true pause/resume.
+ * This class extracts the common state machine, lifecycle methods, and
+ * message handle delegation that was duplicated across all three.
+ *
+ * Subclasses only need to add adapter-specific behavior:
+ * - Gemini: AbortController for SDK cancellation
+ * - OpenAI: AbortController for SDK cancellation
+ * - Copilot: SDK event handling (handleSdkEvent)
+ * @typeParam TState - Turn state type (defaults to ProceduralTurnState)
+ * @typeParam TBus - Scoped bus type for the adapter
+ * @typeParam TSubject - Subject definition type for emit calls
+ */
+declare class ProceduralConnectorTurn<TState extends string = ProceduralTurnState, TBus extends ScopedBus<string> = ScopedBus<string>, TSubject extends ScopedSubjectDefinition = ScopedSubjectDefinition> extends BaseConnectorTurn<TState> {
+  protected activeMessageHandle: MessageHandle;
+  protected readonly connectorBus: TBus;
+  protected readonly agentId: string;
+  protected readonly turnSubjects: TurnSubjects<TSubject>;
+  protected aborted: boolean;
+  constructor(config: ProceduralTurnConfig<TBus, TSubject>, initialState: TState);
+  /**
+   * Emit state change using adapter-provided turn subjects.
+   * @param oldState - Previous state before transition
+   * @param newState - New state after transition
+   */
+  protected emitStateChange(oldState: TState, newState: TState): Promise<void>;
+  /**
+   * Start the turn.
+   */
+  start(): Promise<void>;
+  /**
+   * Transition to step_started (called when first content arrives).
+   * Allows turn_started to step_started AND step_finished to step_started
+   * (for tool recursion).
+   */
+  markStepStarted(): Promise<void>;
+  /**
+   * Transition to step_finished (called after content block completes).
+   */
+  markStepFinished(): Promise<void>;
+  /**
+   * Mark turn as finished.
+   */
+  markTurnFinished(): Promise<void>;
+  /**
+   * Pause (abort) at next opportunity.
+   * Procedural adapters don't support true pause - caller creates a new turn
+   * with merged content instead.
+   * @returns Pause result indicating turn state
+   */
+  pause(): Promise<PauseResult<TState>>;
+  /**
+   * Resume is not supported for procedural adapters - caller creates new turn.
+   * @param _message - Unused
+   * @throws Error always
+   */
+  resume(_message?: unknown): Promise<void>;
+  /**
+   * Check if turn was aborted.
+   * @returns True if turn was aborted
+   */
+  isPaused(): boolean;
+  /**
+   * Check if turn is completed.
+   * @returns True if turn has finished
+   */
+  isCompleted(): boolean;
+  /**
+   * Check if turn can accept immediate message.
+   * True if turn is active (not finished, not aborted).
+   * @returns True if turn can accept an immediate message
+   */
+  canAcceptImmediate(): boolean;
+}
+//#endregion
+//#region adapters/core/src/session/user-message-queue.d.ts
+/**
+ * Simple FIFO queue for user messages with delivery mode support.
+ *
+ * This queue is owned by adapter Connectors and passed to Sessions for processing.
+ *
+ * Delivery modes:
+ * - 'enqueue': Add to end of queue (default); internal retries are prioritized
+ *   ahead of already queued user turns.
+ * - 'replace': Supersede all unacknowledged messages, add to queue
+ * - 'immediate': Handled by Session (abort/restart), not queue
+ *
+ * Design:
+ * - Connector enqueues messages as they arrive
+ * - Session dequeues messages when ready to process
+ * - Peek allows Session to inspect next message without removing
+ */
+declare class UserMessageQueue {
+  private readonly queue;
+  /**
+   * Add message to queue based on delivery mode.
+   * @param handle - Message handle to enqueue
+   */
+  enqueue(handle: MessageHandle): void;
+  /**
+   * Enqueue an internal retry before ordinary queued user turns while preserving
+   * immediate-mode ordering and FIFO ordering among retries.
+   * @param handle - Internal retry handle to enqueue
+   */
+  private enqueueInternalRetry;
+  /**
+   * Remove all superseded messages from queue.
+   */
+  private removeSuperseded;
+  /**
+   * Remove and return first message from queue.
+   * @returns First message or undefined if queue empty
+   */
+  dequeue(): MessageHandle | undefined;
+  /**
+   * Look at first message without removing.
+   * @returns First message or undefined if queue empty
+   */
+  peek(): MessageHandle | undefined;
+  /**
+   * Check if queue is empty.
+   * @returns True if queue has no messages
+   */
+  isEmpty(): boolean;
+  /**
+   * Get current queue size.
+   * @returns Number of messages in queue
+   */
+  size(): number;
+  /**
+   * Clear all messages from queue.
+   */
+  clear(): void;
+  /**
+   * Find the first immediate message in the queue.
+   * @returns First immediate message or undefined
+   */
+  findImmediate(): MessageHandle | undefined;
+  /**
+   * Remove a specific immediate message from the queue.
+   * @param handle - Handle to remove
+   */
+  removeImmediate(handle: MessageHandle): void;
+  /**
+   * Remove and return all enqueued (non-immediate) messages.
+   * Used when immediate arrives to merge their content.
+   * @returns Array of enqueued message handles in FIFO order
+   */
+  drainEnqueued(): MessageHandle[];
+}
+//#endregion
+//#region adapters/core/src/session/process-queue.d.ts
+/**
+ * Minimal turn interface required by processQueue orchestration.
+ *
+ * Any turn implementation (Claude, Gemini, OpenAI, Copilot) that exposes
+ * these methods can participate in the shared processQueue flow.
+ */
+interface QueueableTurn {
+  canAcceptImmediate(): boolean;
+  isCompleted(): boolean;
+  getMessageHandle(): MessageHandle;
+  pause(): Promise<PauseResult>;
+}
+/**
+ * Result of processing an immediate message merge.
+ *
+ * Returned by the `extractMergeContent` callback so that adapters
+ * can collect adapter-specific content (e.g., Gemini collects non-text parts).
+ * The `mergedContent` array is always present; `extra` is an opaque bag
+ * for adapter-specific data that flows through to `startNewTurn`.
+ */
+interface MergeResult {
+  /** Text content collected from superseded/merged messages */
+  mergedContent: string[];
+  /** Adapter-specific merge data (e.g., non-text parts for Gemini) */
+  extra?: unknown;
+}
+/**
+ * Callbacks for adapter-specific behavior during queue processing.
+ * @typeParam TExtra - Type of adapter-specific extra merge data
+ */
+interface ProcessQueueCallbacks<TExtra = unknown> {
+  /**
+   * Get the current turn, if any.
+   * @returns The current turn or undefined
+   */
+  getCurrentTurn: () => QueueableTurn | undefined;
+  /**
+   * Extract text content from a message handle for merge.
+   * Default: `handle.message.message as string`
+   * @param handle - The message handle to extract content from
+   * @returns The text content
+   */
+  extractContent?: (handle: MessageHandle) => string;
+  /**
+   * Called after merge content is collected from superseded/enqueued messages.
+   * Allows adapters to collect additional content (e.g., Gemini's non-text parts).
+   *
+   * If not provided, only text content is collected using `extractContent`.
+   * @param currentHandle - The in-flight message handle being superseded (or undefined)
+   * @param enqueuedHandles - The enqueued handles being merged
+   * @returns Extra merge data to pass through to startNewTurn
+   */
+  collectMergeExtra?: (currentHandle: MessageHandle | undefined, enqueuedHandles: MessageHandle[]) => TExtra;
+  /**
+   * Hook called after merge is collected but before starting the new turn.
+   * Used by Claude to create a fresh query instance.
+   */
+  onBeforeImmediateTurn?: () => Promise<void>;
+  /**
+   * Start a new turn with the given message and optional merge data.
+   * @param handle - The message handle to process
+   * @param mergedContent - Text content from superseded/merged messages
+   * @param extra - Adapter-specific extra merge data
+   */
+  startNewTurn: (handle: MessageHandle, mergedContent?: string[], extra?: TExtra) => Promise<void>;
+}
+/**
+ * Shared processQueue orchestration for all session implementations.
+ *
+ * Handles the complete immediate-mode flow:
+ * 1. Detect immediate message while a turn is active
+ * 2. Pause the active turn
+ * 3. Supersede the in-flight message and drain enqueued messages
+ * 4. Collect merged content from all superseded/merged messages
+ * 5. Start a new turn with the immediate message and merged context
+ *
+ * Also handles the normal queue flow:
+ * - Late immediate rejection (immediate arrives after turn finishes)
+ * - Normal enqueue/replace message processing
+ *
+ * Returns `true` when a new turn was started, `false` otherwise.
+ * Callers can use this to decide whether to transition to idle when
+ * the queue drains without starting a new turn (e.g., all-rejection case).
+ * @param queue - The user message queue to process
+ * @param callbacks - Adapter-specific callbacks
+ * @returns True if a new turn was started, false otherwise
+ * @typeParam TExtra - Type of adapter-specific extra merge data
+ */
+declare function processQueueMessages<TExtra = unknown>(queue: UserMessageQueue, callbacks: ProcessQueueCallbacks<TExtra>): Promise<boolean>;
+//#endregion
+//#region adapters/core/src/connector/procedural-agent-connector.d.ts
+/**
+ * Minimal session interface required by ProceduralAgentConnector.
+ *
+ * Any session implementation (OpenAI, Copilot, Gemini) that exposes
+ * these methods can be used with ProceduralAgentConnector's default
+ * wireSessionEvents / processUserMessages / acceptsImmediate.
+ */
+interface ProceduralConnectorSession {
+  /** Process messages from the queue. */
+  processQueue(queue: UserMessageQueue): Promise<void>;
+  /** Get the current turn for state inspection. */
+  getCurrentTurn(): QueueableTurn | undefined;
+}
+/**
+ * Turn subject references for wireSessionEvents.
+ *
+ * Each adapter provides its namespace-specific subjects. The subjects
+ * must accept TurnStateChangedPayload (or compatible shape).
+ * @typeParam TNamespace - The bus namespace string for subject typing
+ */
+interface WireSessionSubjects<TNamespace extends string = string> {
+  turn_started: ScopedSubjectDefinition<TNamespace>;
+  step_started: ScopedSubjectDefinition<TNamespace>;
+  step_finished: ScopedSubjectDefinition<TNamespace>;
+  turn_finished: ScopedSubjectDefinition<TNamespace>;
+}
+/**
+ * Configuration for ProceduralAgentConnector's wireSessionEvents behavior.
+ *
+ * The `onTurnStarted` and `onTurnFinished` hooks allow adapters to inject
+ * logic at turn boundaries. By default both are no-ops.
+ */
+interface WireSessionConfig {
+  /**
+   * Called when a new turn starts (turn_started bus event).
+   *
+   * Executes before the default `updateProcessingState('turn_started')` so
+   * the connector state machine is always updated regardless of this hook.
+   *
+   * Supports async so that turn-start operations with I/O — such as a pending
+   * MCP tool refresh via the bus — can complete before the API call is made.
+   * In-memory operations (recordInjection, consumeTurnNumber) are not affected
+   * by the async signature.
+   */
+  onTurnStarted?: () => Promise<void> | void;
+  /**
+   * Custom handler for turn_finished events.
+   *
+   * When provided, replaces the default turn_finished behavior entirely.
+   * The handler receives a callback to process the queue, which it should
+   * call when the message is considered complete and the queue should drain.
+   * @param drainQueue - Callback that processes the queue or goes idle
+   */
+  onTurnFinished?: (drainQueue: () => Promise<void>) => Promise<void>;
+}
+/**
+ * Abstract base class for procedural (non-event-driven) agent connectors.
+ *
+ * Procedural adapters (OpenAI, Copilot, Gemini) share common patterns:
+ * - wireSessionEvents: subscribe to turn lifecycle events and update processing state
+ * - processUserMessages: initialize session, enqueue, transition to active, process queue
+ * - complete: poll processing state until idle/paused
+ * - start: delegate to sendMessage and return AgentStartResult
+ * - acceptsImmediate: delegate to session's current turn
+ *
+ * Subclasses must implement:
+ * - `getSession()` / `ensureSession()` for session access and lazy initialization
+ * - `getSessionQueue()` for the adapter's UserMessageQueue instance
+ * - `getTurnSubjects()` for namespace-specific turn subjects
+ * - `sendMessage()`, `abort()`, `close()`, `interrupt()`, `getAdapterSessionId()`
+ *
+ * Subclasses may override:
+ * - `getWireSessionConfig()` for custom turn_finished behavior (e.g., Copilot multi-turn)
+ * @typeParam TBus - Scoped bus type for adapter namespace
+ * @typeParam TConfig - Configuration type extending BaseAgentConnectorConfig
+ */
+declare abstract class ProceduralAgentConnector<TBus extends ScopedBus<string> = ScopedBus<string>, TConfig extends BaseAgentConnectorConfig<TBus> = BaseAgentConnectorConfig<TBus>> extends AIAgentConnector<TBus, TConfig> {
+  /** Whether turn event wiring has been setup. */
+  private turnEventsWired;
+  /**
+   * Get the adapter's session instance (may be undefined if not yet initialized).
+   * @returns The session or undefined
+   */
+  protected abstract getSession(): ProceduralConnectorSession | undefined;
+  /**
+   * Initialize and return the adapter's session.
+   * Must be idempotent (no-op if already initialized).
+   * @returns The initialized session
+   */
+  protected abstract ensureSession(): Promise<ProceduralConnectorSession>;
+  /**
+   * Get the adapter's UserMessageQueue instance.
+   * @returns The message queue
+   */
+  protected abstract getSessionQueue(): UserMessageQueue;
+  /**
+   * Get the adapter's namespace-specific turn subjects for wireSessionEvents.
+   * @returns Turn subject definitions
+   */
+  protected abstract getTurnSubjects(): WireSessionSubjects<TBus['namespace']>;
+  /**
+   * Get optional wire session configuration for custom turn_finished behavior.
+   * Override in subclasses that need non-standard turn_finished handling
+   * (e.g., Copilot multi-turn message completion).
+   * @returns Wire session configuration, or undefined for default behavior
+   */
+  protected getWireSessionConfig(): WireSessionConfig | undefined;
+  /**
+   * Wire Session turn events to Connector state updates.
+   *
+   * Session emits typed events, Connector subscribes and updates processing state.
+   * This maintains separation of concerns - Session does not know about Connector state.
+   *
+   * Default turn_finished behavior: transition through processing_finished to idle,
+   * or drain the queue if messages are pending. Override via `getWireSessionConfig()`.
+   */
+  protected wireSessionEvents(): void;
+  /**
+   * Process queued user messages by delegating to Session.
+   *
+   * Shared flow:
+   * 1. Initialize session if not yet created
+   * 2. Enqueue the message
+   * 3. Set adapterSessionId on handle
+   * 4. Transition to active if currently idle/paused
+   * 5. Process queue via session
+   * @param messageHandles - Array of message handles to process
+   * @returns Set of message handles that were processed
+   */
+  protected processUserMessages(messageHandles: MessageHandle[]): Promise<Set<MessageHandle>>;
+  /**
+   * Initialize the connector's SDK session without sending a message.
+   * Must set adapterSessionId before returning.
+   * Called by createAgent for idle agent setup.
+   * Implementations MUST be idempotent (no-op if already initialized).
+   * @param options - Optional start options (e.g., systemPrompt)
+   */
+  initialize(options?: ConnectorStartOptions): Promise<void>;
+  /**
+   * Start session with initial message.
+   * @param message - The initial message to send
+   * @param options - Optional send message options
+   * @returns The agent start result with session ID and message handle
+   */
+  start(message: NormalizedMessageInput, options?: ConnectorSendMessageOptions): Promise<AgentStartResult>;
+  /**
+   * Complete the agent session by waiting for all messages to finish.
+   * @returns Last message result or null if no messages processed
+   */
+  complete(): Promise<MessageResult | null>;
+  /**
+   * Returns true if current turn can accept immediate messages.
+   * @returns True if turn can accept immediate, false otherwise
+   */
+  protected acceptsImmediate(): boolean;
+}
+//#endregion
+//#region adapters/core/src/utils/tool-approval.d.ts
+/**
+ * Context required to complete a global tool approval request.
+ *
+ * Provides adapter identity so the approval handler knows which
+ * adapter/agent/session is requesting permission.
+ */
+interface ToolApprovalContext {
+  /** Adapter instance ID */
+  adapterId: string;
+  /** Adapter type name (e.g., 'gemini-sdk', 'openai-node') */
+  adapterName: string;
+  /** Agent ID within the adapter */
+  agentId: string;
+  /** Adapter-side session ID */
+  adapterSessionId: string;
+  /** Makaio session ID — required for approval routing to the owning tab */
+  sessionId: string;
+}
+/**
+ * Options controlling how scoped approval payloads are promoted to the global schema.
+ */
+interface MergeScopedToolApprovalOptions {
+  /**
+   * Allow `payload.sessionId` to satisfy the global request when context lacks one.
+   *
+   * This should stay `false` for connector-scoped RPC handlers, which must rely on
+   * agent context rather than connector-provided session identity. Enable only for
+   * trusted call sites that already hold a canonical global approval payload.
+   */
+  allowPayloadSessionFallback?: boolean;
+  /**
+   * Allow payload identity fields (`agentId`, `adapterId`, `adapterName`,
+   * `adapterSessionId`) to satisfy the global request when context lacks them.
+   *
+   * This should stay `false` for connector-scoped RPC handlers, which must rely on
+   * agent context rather than connector-provided identity. Enable only for trusted
+   * call sites that already hold a canonical global approval payload (e.g., direct
+   * bus invocations that supply the full payload without a live agent context).
+   */
+  allowPayloadIdentityFallback?: boolean;
+}
+/**
+ * Resolve the Makaio session ID required for global tool approval routing.
+ *
+ * Scoped connector payloads may omit `sessionId`; agent context should normally
+ * provide it. Callers may optionally allow a payload fallback when their scoped
+ * payload is already trusted to carry the same value.
+ * @param contextSessionId - Session ID from agent context
+ * @param payloadSessionId - Optional session ID from scoped payload
+ * @param sourceLabel - Short source label used in error messages
+ * @param allowPayloadSessionFallback - Whether trusted callers may reuse the payload session ID
+ * @returns Resolved session ID
+ * @throws Error if session ID is absent from all allowed sources
+ */
+declare function resolveRequiredSessionId(contextSessionId: string | undefined, payloadSessionId: string | undefined, sourceLabel: string, allowPayloadSessionFallback?: boolean): string;
+/**
+ * Merge a scoped tool approval payload with agent context into the global request shape.
+ *
+ * All five identity fields (`sessionId`, `agentId`, `adapterId`, `adapterName`,
+ * `adapterSessionId`) must come from trusted agent context by default. Payload
+ * fallback for each group is enabled via the corresponding option flag.
+ * @param payload - Scoped approval payload emitted by the connector
+ * @param context - Agent context used to enrich the scoped payload
+ * @param sourceLabel - Short source label used in error messages
+ * @param options - Controls whether trusted call sites may reuse payload identity
+ * @returns Global tool approval request with all required identity fields resolved
+ */
+declare function mergeScopedToolApproval(payload: ScopedToolApprovalRequest, context: Partial<ToolApprovalContext>, sourceLabel: string, options?: MergeScopedToolApprovalOptions): AgentToolApproveRequest;
+/**
+ * Scoped tool approval schema for adapter connector buses.
+ *
+ * `sessionId` is optional here because the connector emits the approval request
+ * before the agent layer has enriched it. The agent's `wireToolApprovalRpc`
+ * (or equivalent) injects `sessionId` from its own context before forwarding
+ * to the global `AgentSubjects.toolApprove` subject, where `sessionId` is required.
+ *
+ * Adapters with a genuinely different wire format (e.g., gemini-sdk's callId/name)
+ * should define their own schema rather than extending this one.
+ */
+declare const ScopedToolApprovalSchema: {
+  request: z.ZodObject<{
+    agentId: z.ZodString;
+    adapterId: z.ZodString;
+    adapterName: z.ZodString;
+    adapterSessionId: z.ZodString;
+    messageId: z.ZodOptional<z.ZodString>;
+    turnId: z.ZodOptional<z.ZodString>;
+    clientId: z.ZodOptional<z.ZodString>;
+    providerConfigId: z.ZodOptional<z.ZodString>;
+    occurredAt: z.ZodOptional<z.ZodNumber>;
+    toolName: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    toolCallId: z.ZodString;
+    reasoning: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  response: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"allow">;
+    updatedInput: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    updatedPermissions: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+  }, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"deny">;
+    message: z.ZodString;
+    shouldAbort: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>], "action">;
+};
+/** Scoped tool approval request payload type — `sessionId` is optional at the connector layer. */
+type ScopedToolApprovalRequest = z.infer<typeof ScopedToolApprovalSchema.request>;
+/** Scoped tool approval response payload type — identical to the global response. */
+type ScopedToolApprovalResponse = z.infer<typeof ScopedToolApprovalSchema.response>;
+/**
+ * Transform function signature: SDK payload → AgentToolApproveRequest.
+ * @param payload - SDK-specific tool approval payload
+ * @param context - Resolved tool approval context with adapter identity
+ * @returns Global tool approval request for AgentSubjects.toolApprove
+ */
+type ToGlobalToolApprovalFn<TPayload, TContext = ToolApprovalContext> = (payload: TPayload, context: TContext) => AgentToolApproveRequest;
+/**
+ * Transform function signature: AgentToolApproveResponse → SDK response format.
+ * @param response - Global tool approval response from AgentSubjects.toolApprove
+ * @returns SDK-compatible response format
+ */
+type FromGlobalToolApprovalFn<TResponse> = (response: AgentToolApproveResponse) => TResponse;
+/**
+ * Factory: Create tool approval handler for adapter connector.
+ *
+ * Wires adapter-scoped tool approval subject → AgentSubjects.toolApprove.
+ * Handles lazy context resolution to avoid race conditions with adapterSessionId.
+ *
+ * Used by both test harnesses (createTestConfig) and production (agent.ts).
+ * @param subject - Adapter-scoped subject for tool approval requests
+ * @param toGlobal - Transform SDK payload to global request
+ * @param fromGlobal - Transform global response to SDK format
+ * @returns Handler registration function
+ * @example
+ * ```typescript
+ * // In gemini-sdk/src/tool-handling.ts
+ * export const registerToolApprovalHandler = createToolApprovalHandler(
+ *   GeminiConnectorSubjects.acp.tool_approval,
+ *   toGlobalToolApproval,
+ *   fromGlobalToolApproval,
+ * );
+ * ```
+ */
+declare function createToolApprovalHandler<TPayload, TContext = ToolApprovalContext, TResponse = AgentToolApproveResponse>(subject: ScopedSubjectDefinition<string>, toGlobal: ToGlobalToolApprovalFn<TPayload, TContext>, fromGlobal: FromGlobalToolApprovalFn<TResponse>): (connector: Pick<AIAgentConnector, "on">, context: TContext | (() => Promise<TContext>)) => () => void;
+//#endregion
+//#region adapters/core/src/utils/normalizeMimeType.d.ts
+/**
+ * Normalize a MIME type string for comparison.
+ *
+ * Strips parameters (e.g., "; charset=utf-8") and converts to lowercase.
+ * This ensures that values like "text/plain; charset=utf-8" or
+ * "TEXT/PLAIN" are handled correctly.
+ * Falls back to 'application/octet-stream' if mimeType is null/undefined.
+ * @param mimeType - MIME type string to normalize.
+ * @returns Normalized MIME type string (lowercase, no parameters).
+ */
+declare function normalizeMimeType(mimeType: string | undefined | null): string;
+/**
+ * Check if a MIME type represents text content that can be sent as a document.
+ *
+ * Covers `text/*` and common text-based `application/*` subtypes (JSON, XML,
+ * SQL, GraphQL, JavaScript, TypeScript, YAML, TOML).
+ * @param mimeType - MIME type string (parameters are allowed, e.g., "text/plain; charset=utf-8")
+ * @returns True if the content is text-based.
+ */
+declare function isTextLikeMimeType(mimeType: string | undefined | null): boolean;
+//#endregion
+//#region adapters/core/src/utils/resolvePresetCredentials.d.ts
+/**
+ * Resolve credentials from environment variables using a provider definition's credential mapping.
+ *
+ * Reads `definition.credentialEnvVars` and checks `process.env` for each declared variable.
+ * Only includes fields where the env var is actually set.
+ * @param definition - Provider definition with optional credentialEnvVars mapping
+ * @returns Object mapping credential field names to resolved values, or undefined if none resolved
+ */
+declare function resolvePresetCredentials(definition: ProviderDefinitionInput): Record<string, string> | undefined;
+//#endregion
+//#region adapters/core/src/utils/createConnectorEventMapping.d.ts
+/**
+ * Emit helper passed to handler functions for emitting to global subjects.
+ * Automatically enriches payloads with AgentContext.
+ */
+type ConnectorEmitFn = <S extends SubjectDefinition>(subject: S, payload: Omit<ExtractSubjectPayload<S>, keyof AgentContext>) => Promise<void>;
+/**
+ * Handler function signature for connector event mapping.
+ * Receives the narrowed payload and an emit helper for further emissions.
+ * Can be sync or async — async handlers are awaited.
+ */
+type ConnectorEventHandlerFn<TPayload> = (payload: TPayload, emit: ConnectorEmitFn) => void | Promise<void>;
+/**
+ * Handler value: either a subject definition for passthrough or a handler function.
+ */
+type ConnectorEventHandlerValue<TPayload> = (SubjectDefinition & {
+  $meta: {
+    payload: TPayload;
+  };
+}) | ConnectorEventHandlerFn<TPayload>;
+/**
+ * Discriminator keys type - extracts string keys from the message type.
+ */
+type DiscriminatorKeys<TMessage> = (TMessage extends object ? keyof TMessage : never) & string;
+/**
+ * Discriminator values type - extracts possible values at the discriminator key.
+ */
+type DiscriminatorValues<TMessage, TDiscriminator extends string> = (TMessage extends object ? TMessage[TDiscriminator & keyof TMessage] : never) & string;
+/**
+ * Narrowed message type - extracts the union member matching a discriminator value.
+ */
+type NarrowedMessage<TMessage, TDiscriminator extends string, K extends string> = Extract<TMessage, { [P in TDiscriminator]: K }>;
+/**
+ * Complete handlers record type for connector event mapping.
+ */
+type ConnectorEventHandlers<TMessage, TDiscriminator extends string> = { [K in DiscriminatorValues<TMessage, TDiscriminator>]?: ConnectorEventHandlerValue<NarrowedMessage<TMessage, TDiscriminator, K>> };
+//#endregion
+//#region adapters/core/src/agent/message-lifecycle-tracker.d.ts
+/**
+ * Emit function type for global bus emissions.
+ * Matches the signature of AIAgent.emitGlobal.
+ */
+type EmitGlobalFn = <S extends SubjectDefinition>(subject: S, payload: Omit<ExtractSubjectPayload<S>, keyof AgentContext>) => Promise<void>;
+/**
+ * Configuration for MessageLifecycleTracker.
+ */
+interface MessageLifecycleTrackerConfig {
+  /** Function to emit events to global bus with auto-enrichment */
+  emitGlobal: EmitGlobalFn;
+}
+/**
+ * Tracks message lifecycle and emits corresponding events.
+ *
+ * Responsibilities:
+ * - Track current messageId being processed
+ * - Emit user_message.acknowledged / user_message.completed events
+ * - Emit agent.turn.started / agent.turn.completed events
+ *
+ * This provides a clean separation between message lifecycle tracking
+ * and the core AIAgent functionality.
+ */
+declare class MessageLifecycleTracker {
+  /** Current messageId being processed (set on acknowledgment, cleared on completion) */
+  private currentMessageId?;
+  /** Current turnId from the session orchestrator (set at sendMessage entry, cleared on completion) */
+  private currentTurnId?;
+  /** Emit function injected from AIAgent */
+  private readonly emitGlobal;
+  constructor(config: MessageLifecycleTrackerConfig);
+  /**
+   * Get the current messageId being processed.
+   * Used by enrichPayload() to add messageId to intermediate events.
+   * @returns The current messageId or undefined if no message is being processed
+   */
+  getCurrentMessageId(): string | undefined;
+  /**
+   * Set the current turnId from the session orchestrator.
+   * Called at the start of sendMessage processing.
+   * @param turnId - Turn ID to track, or undefined to clear
+   */
+  setCurrentTurnId(turnId: string | undefined): void;
+  /**
+   * Clear the currently tracked turn ID.
+   */
+  clearCurrentTurnId(): void;
+  /**
+   * Get the current turnId being processed.
+   * Used by enrichPayload() to add turnId to intermediate events.
+   * @returns The current turnId or undefined if not set
+   */
+  getCurrentTurnId(): string | undefined;
+  /**
+   * Acknowledge a message - marks turn start.
+   *
+   * Emits:
+   * - user_message.acknowledged
+   * - agent.turn.started
+   * @param handle - The message handle being acknowledged
+   */
+  acknowledge(handle: MessageHandle): void;
+  /**
+   * Complete a message - marks turn end.
+   *
+   * Emits:
+   * - agent.turn.completed (always, with outcome — paired with agent.turn.started)
+   * - user_message.completed (always, with outcome)
+   * @param handle - The message handle being completed
+   * @param result - The completion result with outcome
+   */
+  complete(handle: MessageHandle, result: MessageResult): void;
+  /**
+   * Wire up a message handle for lifecycle tracking.
+   *
+   * Subscribes to the handle's acknowledgment and completion promises
+   * and emits the appropriate events. When `transformTerminal` is provided,
+   * it is registered on the handle so validation or other post-processing
+   * amends the public completion result before lifecycle events fire.
+   * @param handle - The message handle to track
+   * @param onTerminal - Optional callback for any terminal outcome (emits agent.complete)
+   * @param transformTerminal - Optional async transform applied before public completion resolves
+   */
+  track(handle: MessageHandle, onTerminal?: (messageId: string, result: MessageResult) => void, transformTerminal?: (result: MessageResult) => Promise<MessageResult>): void;
+}
+//#endregion
+//#region adapters/core/src/agent/tool-call-tracker.d.ts
+/**
+ * Hints for resolving tool output to its originating tool.use event.
+ * Adapters provide what they can - strategies try each hint in order.
+ */
+interface ResolveHints {
+  /** Native provider ID (e.g., toolu_* for Claude, call_* for Codex/OpenAI) */
+  nativeId?: string;
+  /** Tool name for FIFO matching when no native ID available */
+  toolName?: string;
+}
+type ResolveStrategy = 'nativeId' | 'toolName' | 'oldest' | 'none';
+interface ResolveResult {
+  correlationId: string | null;
+  strategy: ResolveStrategy;
+  /** Tool name from the matched tool.use call. Undefined when no match was found. */
+  toolName?: string;
+  /** Arguments from the matched tool.use call. Undefined when no match was found. */
+  args?: Record<string, unknown>;
+}
+/**
+ * Tracks tool.use → tool.output correlation across adapters.
+ *
+ * Different adapters have different correlation capabilities:
+ * - Claude Code: toolu_* IDs
+ * - Codex/OpenAI: call_* IDs
+ * - Others: may have nothing
+ *
+ * ToolCallTracker provides a unified interface that:
+ * 1. Uses native IDs when available
+ * 2. Falls back to FIFO by tool name otherwise
+ * 3. Generates UUIDs for adapters without native IDs
+ */
+declare class ToolCallTracker {
+  private pending;
+  /**
+   * Register a tool.use event. Returns correlation ID to use.
+   * If nativeId provided, uses that. Otherwise generates UUID.
+   * @param toolName - Name of the tool being invoked
+   * @param args - Tool arguments (optional, for future correlation strategies)
+   * @param nativeId - Native provider ID if available
+   * @returns Correlation ID to use for this tool call
+   */
+  register(toolName: string, args?: Record<string, unknown>, nativeId?: string): string;
+  /**
+   * Find correlation ID for a tool output.
+   * Tries native ID first, then falls back to FIFO by tool name,
+   * and finally to the oldest pending tool call.
+   * @param hints - Available hints for correlation
+   * @returns Correlation result with strategy metadata
+   */
+  resolve(hints: ResolveHints): ResolveResult;
+  /**
+   * Clear all pending entries.
+   * Call on turn end to prevent stale entries from leaking across turns.
+   */
+  clear(): void;
+}
+//#endregion
+//#region adapters/core/src/agent/ai-agent.d.ts
+interface ToolOutputResolution {
+  toolCallId: string;
+  toolName: string;
+  args?: Record<string, unknown>;
+}
+/**
+ * Abstract base class for AI agents.
+ *
+ * Bridges adapter/agent bus subjects to connector sessions.
+ * @typeParam TBus - The scoped bus type for this adapter
+ * @typeParam TConnector - The connector type this agent wraps
+ */
+declare abstract class AIAgent<TBus extends ScopedBus<string> = ScopedBus<string>, TConnector extends AIAgentConnector<TBus> = AIAgentConnector<TBus>> {
+  /** The underlying connector instance (created in init) */
+  protected connector: TConnector;
+  protected confirmedModel?: string;
+  protected initialModel?: string;
+  /** Cached adapterSessionId from the last connector that had a session — survives connector swaps. */
+  private lastKnownAdapterSessionId?;
+  /** Cleanup functions for bus subscriptions (stable, survive connector swap) */
+  private busHandlerCleanups;
+  /** Whether init() has been called */
+  private initialized;
+  /** Runtime system prompt captured from start/initialize, preserved across connector swaps. */
+  private runtimeSystemPrompt?;
+  /** Tracks message lifecycle and emits turn events. */
+  protected readonly lifecycleTracker: MessageLifecycleTracker;
+  /** Tracks tool.use → tool.output correlation across adapters. */
+  protected readonly toolCallTracker: ToolCallTracker;
+  /** Event-focused helper for usage/tool/step emissions. */
+  private readonly eventBridge;
+  /** Shared turn pipeline for start/sendMessage paths. */
+  private readonly turnExecutor;
+  /** Runtime mutation helper for cwd/model change handlers. */
+  private readonly runtimeMutationManager;
+  /** Connector lifecycle helper for swap/wiring ownership. */
+  private readonly connectorLifecycleManager;
+  /** Payload enrichment and global emission helper. */
+  private readonly payloadEmitter;
+  /** Stateful lifecycle emitter for start/complete/error/session.closed. */
+  private readonly lifecycleEmitter;
+  /** Validates structured output before public terminal results and lifecycle events resolve. */
+  private readonly structuredOutputManager;
+  /** Latest tracked message completion with agent-level terminal transforms applied. */
+  private latestMessageCompletion?;
+  /** Current content block index within the turn, reset on each turn start */
+  private currentBlockIndex;
+  /** Normalized config with defaults applied */
+  protected readonly config: SetRequired<AIAgentConfig<TBus, TConnector>, 'globalBus'>;
+  /** Available models for context window lookup */
+  protected readonly availableModels?: AIModel[];
+  /**
+   * Create an AIAgent instance.
+   *
+   * Note: Does NOT create the connector yet - call init() after construction.
+   * @param config - Agent configuration
+   */
+  constructor(config: AIAgentConfig<TBus, TConnector>);
+  private getEventMetadataDefaults;
+  private createLifecycleEmitter;
+  /**
+   * Create the structured-output manager for this agent.
+   * @returns Configured manager instance
+   */
+  private createStructuredOutputManager;
+  /** @returns Unique agent identifier */
+  get agentId(): string;
+  /** @returns Adapter instance identifier */
+  get adapterId(): string;
+  /** @returns Adapter type name (e.g., 'claude-code', 'gemini-sdk') */
+  get adapterName(): string;
+  /** @returns Adapter capabilities for runtime feature detection */
+  get capabilities(): string[];
+  /** @returns Native tools built into the adapter */
+  get nativeTools(): string[];
+  /** @returns Shared Makaio sessionId */
+  get sessionId(): string | undefined;
+  /** @returns Initial adapter session ID from config (may differ from connector's resolved session ID) */
+  protected get adapterSessionId(): string | undefined;
+  /** @returns Global bus for cross-namespace communication (defaulted in constructor) */
+  protected get globalBus(): IMakaioBus;
+  /**
+   * Initialize the agent.
+   *
+   * Creates the connector via the abstract createConnector() method
+   * and sets up handlers for agent.* subjects with agentId filtering.
+   * @throws Error if already initialized
+   */
+  init(): Promise<void>;
+  protected emitStart(event?: Omit<AgentStarted, 'agentId' | 'adapterId' | 'adapterName' | 'adapterSessionId' | 'model' | 'cwd'>): Promise<void>;
+  protected emitCompletion(result: Omit<z.infer<typeof AgentSchemas.complete>, keyof AgentContext>): Promise<void>;
+  /**
+   * Stash error metadata for the next emitCompletion call.
+   *
+   * The lifecycle tracker emits `agent.complete` with `outcome: 'error'` when the
+   * message handle completes. This method runs first (from the connector's errorHandler)
+   * and stashes `errorCategory` so emitCompletion can include it in the complete payload.
+   *
+   * No longer emits `agent.error` — all terminal events flow through `agent.complete`.
+   * @param result - Error payload from the connector
+   */
+  protected emitError(result: Pick<z.infer<typeof AgentSchemas.complete>, 'error' | 'errorCategory'>): void;
+  /**
+   * Emit agent session closed event. Emits only once per session.
+   * AIAdapter listens to cleanup agent and re-emit as AdapterSubjects.session.closed.
+   * @param reason - Reason for session closure (e.g., 'aborted', 'closed')
+   */
+  protected emitSessionClosed(reason?: string): void;
+  /**
+   * Enrich a payload with agent context fields.
+   * @param payload - The base payload to enrich
+   * @returns Payload with AgentContext fields and optional messageId added
+   */
+  protected enrichPayload<T extends object>(payload: T): Promise<T & AgentContext & {
+    messageId?: string;
+  }>;
+  /**
+   * Emit to a global subject with automatic payload enrichment.
+   * @param subject - The subject to emit to
+   * @param payload - The payload (without AgentContext fields - they're added automatically)
+   */
+  protected emitGlobal<S extends SubjectDefinition>(subject: S, payload: Omit<ExtractSubjectPayload<S>, keyof AgentContext> & {
+    messageId?: string;
+  }): Promise<void>;
+  /**
+   * Track usage and emit to global bus.
+   * AIAdapter aggregates session totals from per-call usage events.
+   * @param normalized - Normalized usage metrics from adapter-specific normalizer
+   */
+  protected trackUsage(normalized: NormalizedCallUsage): Promise<void>;
+  /**
+   * Get context window size for a model.
+   *
+   * Looks up the context window size from availableModels based on model name.
+   * @param modelName - Model name to look up (defaults to confirmedModel or initialModel)
+   * @returns Context window size in tokens, or undefined if not found
+   */
+  protected getContextWindowSize(modelName?: string): number | undefined;
+  /**
+   * Emit context window status for compression trigger decisions.
+   *
+   * Calculates fill percentage and warning level from raw metrics.
+   * Called by subclasses after usage tracking with provider-specific metrics.
+   * @param input - Raw metrics: currentTokens, maxTokens, optional cachedTokens
+   */
+  protected emitContextWindowUpdate(input: ContextWindowInput): Promise<void>;
+  /**
+   * Emit tool.use event with automatic correlation tracking.
+   * Registers the tool call with ToolCallTracker and emits to global bus.
+   * Use this instead of directly emitting to AgentSubjects.tool.use.
+   * @param toolName - Name of the tool being invoked
+   * @param args - Tool arguments
+   * @param nativeId - Native provider ID if available (e.g., toolu_*, call_*)
+   * @returns The correlation ID used (nativeId if provided, else generated UUID)
+   */
+  protected emitToolUse(toolName: string, args?: Record<string, unknown>, nativeId?: string): Promise<string>;
+  /**
+   * Emit tool.output event with automatic correlation resolution.
+   * Resolves the correlation ID from ToolCallTracker using provided hints.
+   * Use this instead of directly emitting to AgentSubjects.tool.output.
+   * @param output - Tool output content
+   * @param hints - Hints for correlation (nativeId and/or toolName)
+   * @returns Resolved toolCallId, toolName (falls back to 'unknown'), and args from the matched tool.use call
+   */
+  protected emitToolOutput(output: string, hints: ResolveHints): Promise<ToolOutputResolution>;
+  /**
+   * Emit step.started event with automatic block index management.
+   * Call this when a content block begins processing.
+   * @param stepType - The type of step (text, reasoning, tool_use)
+   * @param blockData - Optional metadata for the block (e.g., toolName for tool_use)
+   * @param content - Optional content for the step (e.g., tool_call block for tool_use)
+   */
+  protected emitStepStarted(stepType: StepType, blockData?: BlockData, content?: SessionMessageBlock): Promise<void>;
+  /**
+   * Emit step.finished event with content and increment block index.
+   * Call this when a content block completes processing.
+   * @param stepType - The type of step that finished
+   * @param content - The complete content of the step (text, reasoning, tool_call, or tool_output)
+   */
+  protected emitStepFinished(stepType: StepType, content: SessionMessageBlock): Promise<void>;
+  /**
+   * Get the current block index (for adapters that need to track it externally).
+   * @returns Current block index within the turn
+   */
+  protected getBlockIndex(): number;
+  /**
+   * Increment block index (for adapters using SDK-provided indices).
+   * Call after emitting step.finished if managing index externally.
+   */
+  protected incrementBlockIndex(): void;
+  /**
+   * Handle agent.sendMessage request.
+   * The filter has already been applied at subscription time - this method
+   * only receives messages intended for this agent.
+   * Runs PreUserMessage hooks before delegating to the connector's sendMessage method.
+   * Uses sessionContext signals to decide between native resume and fresh with history.
+   * HookAbortError propagates to caller (session layer handles lifecycle).
+   * Subclasses can override for custom handling.
+   * @param ctx - Request context with payload and response methods
+   */
+  protected sendMessage(ctx: RequestContext<SendMessageRequestPayload, SendMessageResponsePayload>): Promise<void>;
+  /**
+   * Handle agent.interrupt request.
+   * Delegates to the connector's native interrupt behavior.
+   * @param ctx - Request context with interrupt payload
+   */
+  private handleInterrupt;
+  /**
+   * Register a cleanup function for connector wiring.
+   * These cleanups are cleared on connector swap but preserved across bus handler changes.
+   * @param cleanup - Cleanup function to register
+   */
+  protected addConnectorWiringCleanup(cleanup: () => void): void;
+  /**
+   * Registers a cleanup function for a global bus subscription.
+   * These survive connector swaps and are cleaned up in close().
+   * @param cleanup - Function to unsubscribe from the bus
+   */
+  protected addBusHandlerCleanup(cleanup: () => void): void;
+  /**
+   * Replace the current connector with a fresh one.
+   *
+   * Uses create-before-close pattern with rollback for safety:
+   * 1. Create new connector first (old connector still alive)
+   * 2. Wire events to new connector (accumulate cleanups separately)
+   * 3. If successful: close old connector, assign new one
+   * 4. If failed: close new connector, restore old wiring, throw
+   *
+   * This ensures the agent always has a working connector, even if factory or wiring fails.
+   *
+   * Preserves runtime overrides across sequential swaps by using current connector values
+   * as baseline for non-overridden fields.
+   * @param configOverrides - Optional config overrides (e.g., new cwd, model)
+   * @throws Error if connector is currently processing a turn
+   */
+  swapConnector(configOverrides?: Partial<{
+    cwd: string;
+    model: string;
+    providerContext: ProviderContext;
+    mcpSessionContext: McpRuntimeSessionContext | McpSessionContext | LedgerSessionContext;
+  }>): Promise<void>;
+  /**
+   * Resolve the supported reasoning levels for a given model name.
+   *
+   * Centralised lookup into `availableModels` so callers do not repeat the
+   * find/optional-chain pattern inline.
+   * @param model - Model name to look up, or `undefined` to return `undefined`
+   * @returns The `supportedReasoningLevels` map for the model, or `undefined`
+   */
+  private getSupportedReasoningLevels;
+  /**
+   * Build config factory input from agent config with optional overrides.
+   *
+   * Explicitly maps AIAgentConfig fields to ConfigFactoryInput — avoids
+   * accidentally forwarding adapter-only fields (capabilities, nativeTools, etc.)
+   * into the factory.
+   * @param overrides - Optional field overrides (e.g., cwd, model, adapterSessionId)
+   * @returns ConfigFactoryInput ready for config factory
+   */
+  private buildConfigInput;
+  /**
+   * Create the onMessageSent callback for connector factories.
+   *
+   * Returns a callback that emits user_message.sent events to the global bus.
+   * @returns Callback function for connector config
+   */
+  private createOnMessageSent;
+  /**
+   * Handle agent.cwd.change request — prefers native in-place change, falls back to connector swap.
+   * @param ctx - Request context with newCwd payload
+   */
+  private handleCwdChange;
+  /**
+   * Handle agent.model.change request — prefers native in-place change, falls back to connector swap.
+   * @param ctx - Request context with newModel payload
+   */
+  private handleModelChange;
+  /**
+   * Handle agent.mcp.servers.set request — rebuilds immediately when idle or stages for the next turn.
+   * @param ctx - Request context with replacement MCP session context
+   */
+  private handleMcpServersSet;
+  /**
+   * Handle agent.credential.change request — defers when a turn is active, otherwise swaps connector.
+   * @param ctx - Request context with credential change payload
+   */
+  private handleCredentialChanged;
+  /**
+   * Wire adapter-specific connector events.
+   * Called automatically during init() and connector swap.
+   * Subclasses implement this to set up their event mappings.
+   * @param connector - Connector instance to wire
+   */
+  protected abstract wireEvents(connector: TConnector): void | Promise<void>;
+  /**
+   * Subscribe to a connector subject and register its cleanup as connector wiring.
+   *
+   * Use this in adapter `wireEvents()` implementations so connector swaps can
+   * remove old listeners before rewiring the new connector.
+   * @param connector - Connector instance to subscribe on
+   * @param subject - Subject definition to subscribe to
+   * @param handler - Subject handler
+   * @param options - Optional bus subscription options
+   */
+  protected subscribeConnector<Subject extends ScopedSubjectDefinition<TConnector extends AIAgentConnector<infer TBus> ? TBus['namespace'] : never>>(connector: TConnector, subject: Subject, handler: HandlerForSubjectDefinition<Subject>, options?: OnOptions): void;
+  /**
+   * Clean up resources and emit session closed event.
+   *
+   * Emits session.closed event (once per session) unless explicitly suppressed,
+   * then unsubscribes from all bus handlers and aborts the connector if available.
+   * @param options - Cleanup options; ephemeral agents suppress session-close lifecycle events because they never join a session.
+   */
+  close(options?: {
+    emitSessionClosed?: boolean;
+  }): Promise<void>;
+  /**
+   * Ensure the connector is initialized, throwing if not.
+   * @returns The initialized connector instance
+   * @throws Error if connector is not initialized
+   */
+  private ensureConnector;
+  /**
+   * Determine whether to use native session resume or fresh with history.
+   *
+   * Native resume: SDK manages history, don't inject messageHistory, preserve cache.
+   * Fresh with history: Create new session, inject messageHistory.
+   *
+   * Override in adapter-specific agents if needed.
+   * @param sessionContext - Context signals from SessionOrchestrator
+   * @returns true if native resume should be used
+   */
+  protected shouldUseNativeResume(sessionContext?: SessionContext): boolean;
+  /**
+   * Whether this adapter supports native session resume.
+   * Override in adapter-specific agents that can resume SDK sessions.
+   * @returns true if native resume is supported
+   */
+  protected supportsNativeResume(): boolean;
+  /**
+   * Start the agent with an initial message.
+   *
+   * Ensures the agent is initialized (idempotent) before delegating to the connector.
+   * Runs PreUserMessage hooks before sending the message.
+   * Uses sessionContext signals to decide between native resume and fresh with history.
+   * HookAbortError propagates to caller.
+   * @param message - User message (normalized or unnormalized)
+   * @param options - Optional start options (e.g., delivery mode, sessionContext)
+   * @returns Session ID, agent ID, and message handle for tracking
+   */
+  start(message: NormalizedMessageInput | MessageInput, options?: StartAgentOptions): Promise<AgentStartResult>;
+  /**
+   * Initialize the agent without sending a message (idle creation).
+   * Ensures init() is called, then delegates to connector.initialize().
+   * @param options - Optional initialization options (system prompt, sessionContext)
+   */
+  initialize(options?: StartAgentOptions): Promise<void>;
+  protected onBeforeEmitCompletion(): Promise<void>;
+  protected onMessageHandle(messageHandle: MessageHandle): Promise<void>;
+  /**
+   * Abort the agent immediately (panic mode).
+   * Triggers AbortController which may cause provider errors.
+   * Use close() for graceful shutdown instead.
+   *
+   * Emits session.closed event (once per session) then delegates
+   * to the underlying connector's abort method.
+   * @throws Error if connector is not initialized
+   */
+  abort(): void;
+  /**
+   * Get session ID, waiting for provider to generate it if not yet available.
+   *
+   * Delegates to the underlying connector's getSessionId method.
+   * @returns Session ID from provider
+   * @throws Error if connector is not initialized
+   */
+  getAdapterSessionId(): Promise<string>;
+  /**
+   * Complete the agent session by waiting for all messages to finish.
+   *
+   * Waits for the connector to finish, then returns the agent-level terminal
+   * result so structured-output transforms are reflected in direct callers.
+   * @returns Last message result or null if no messages processed
+   * @throws Error if connector is not initialized
+   */
+  complete(): Promise<MessageResult | null>;
+  /**
+   * Creates a type-safe event mapping from connector events to scoped subjects or handlers.
+   * @param sourceSubject - The connector subject to subscribe to
+   * @param discriminator - The discriminator key within the message (e.g., 'type')
+   * @param handlers - Map of discriminator values to target subjects or handler functions
+   * @param nestedMessageProp - Property containing the discriminated union (e.g., 'msg'), or undefined for top-level
+   * @returns Unsubscribe function for the connector event mapping subscription
+   */
+  protected createConnectorEventMapping<TSourceSubject extends ScopedSubjectDefinition<TConnector extends AIAgentConnector<infer TBus> ? TBus['namespace'] : never>, TNestedMessageProp extends keyof TSourceSubject['$meta']['payload'] | undefined = undefined, TMessage = (TNestedMessageProp extends keyof TSourceSubject['$meta']['payload'] ? TSourceSubject['$meta']['payload'][TNestedMessageProp] : TSourceSubject['$meta']['payload']), TDiscriminator extends DiscriminatorKeys<TMessage> = DiscriminatorKeys<TMessage>>(sourceSubject: TSourceSubject, discriminator: TDiscriminator, handlers: ConnectorEventHandlers<TMessage, TDiscriminator>, nestedMessageProp?: TNestedMessageProp): () => void;
+}
+//#endregion
+//#region adapters/core/src/factory/create-adapter-namespace.d.ts
+/**
+ * Adapter namespace extends BusNamespace with additional metadata for adapters.
+ *
+ * Provides:
+ * - All BusNamespace features (subjects, scoped bus factory)
+ * - Raw schema access for adapter factory internals
+ * - Domain name for debugging/logging
+ * @typeParam N - Namespace domain string
+ * @typeParam Schemas - Schema record type
+ */
+type AdapterNamespace<Domain extends string = string> = Omit<BusNamespace<Domain>, 'subjects'>;
+/**
+ * Creates an adapter namespace with typed subject definitions.
+ *
+ * **Seam:** Thin wrapper around MakaioBus.registerNamespace that:
+ * - Delegates to bus-core for namespace registration
+ * - Preserves FilterPayload type for type-safe withFilter()
+ * - Provides extension point for future adapter-specific features
+ * @param domain - Namespace domain (e.g., 'adapter:claudeCode')
+ * @param schemas - Record of subject schemas (events and requests)
+ * @param options - Registration and routing options (e.g., busValidationMode for Zod version conflicts)
+ * @returns Adapter namespace with typed subjects and pre-computed FilterPayload
+ * @example
+ * ```typescript
+ * const ClaudeCodeNamespace = createAdapterNamespace('adapter:claudeCode', {
+ *   thinking: z.object({ content: z.string() }),
+ *   getContext: {
+ *     request: z.object({ path: z.string() }),
+ *     response: z.object({ content: z.string() }),
+ *   },
+ * });
+ *
+ * // Access typed subjects
+ * ClaudeCodeNamespace.subjects.thinking;
+ *
+ * // Get scoped bus with type-safe filtering
+ * const bus = await ClaudeCodeNamespace.scopedBus();
+ * bus.withFilter({ content: 'test' }); // ✅ Type-checked
+ *
+ * // For adapters with bundled Zod v3 (e.g., @github/copilot-sdk):
+ * const CopilotNamespace = createAdapterNamespace('adapter:copilot', schemas, {
+ *   busValidationMode: 'skip', // Skip validation due to Zod version conflict
+ * });
+ *
+ * // For adapters with lenient validation (schema drift triggers warnings, not crashes):
+ * const ClaudeNamespace = createAdapterNamespace('adapter:claude-code', schemas, {
+ *   busValidationMode: 'lenient',
+ *   onSchemaViolation: (report) => console.warn(report),
+ * });
+ * ```
+ */
+declare function createAdapterNamespace<N extends string, Schemas extends SchemaRecord>(domain: N, schemas: Schemas, options?: CreateBusNamespaceOptions): BusNamespace<N, SubjectRecordFromSchemaRecord<Schemas>, FilterablePayloadIntersection<SubjectRecordFromSchemaRecord<Schemas>>, Schemas>;
+//#endregion
+//#region adapters/core/src/factory/adapter-context.d.ts
+/**
+ * Context provided to adapter implementations.
+ *
+ * Contains shared infrastructure and configuration that all adapters need:
+ * - Adapter name and capabilities from config
+ * - Local event bus for emitting events
+ */
+interface AIAdapterContext<Scope extends ScopedBus<string>> {
+  /** Unique adapter instance identifier. */
+  adapterId: string;
+  /** Unique adapter name (kebab-case). */
+  name: string;
+  /** Adapter capabilities (unparsed). Use parseAIAdapterCapabilities() to parse. */
+  capabilities: AIAdapterCapability[];
+  /** Scoped bus for adapter-level events. */
+  adapterBus: Scope;
+  /** Global event bus. */
+  globalBus: IMakaioBus;
+}
+//#endregion
+//#region adapters/core/src/agent/agent-event-bridge.d.ts
+/**
+ * Dependencies for AgentEventBridge.
+ */
+interface AgentEventBridgeConfig {
+  /** Emit usage payload (agent context gets added by AIAgent). */
+  emitUsage: (payload: Omit<ExtractSubjectPayload<typeof AgentSubjects.usage>, keyof AgentContext>) => Promise<void>;
+  /** Emit context window status payload. */
+  emitContextWindowUpdated: (payload: Omit<ExtractSubjectPayload<typeof AgentSubjects.contextWindow.updated>, keyof AgentContext>) => Promise<void>;
+  /** Emit tool.use payload. */
+  emitToolUse: (payload: Omit<ExtractSubjectPayload<typeof AgentSubjects.tool.use>, keyof AgentContext>) => Promise<void>;
+  /** Emit tool.output payload. */
+  emitToolOutput: (payload: Omit<ExtractSubjectPayload<typeof AgentSubjects.tool.output>, keyof AgentContext>) => Promise<void>;
+  /** Emit adapter log payload. */
+  emitAdapterLog: (payload: Omit<ExtractSubjectPayload<typeof AdapterSubjects.log>, 'adapterId' | 'adapterName'>) => Promise<void>;
+  /** Emit step.started payload. */
+  emitStepStarted: (payload: Omit<ExtractSubjectPayload<typeof AgentSubjects.step.started>, keyof AgentContext>) => Promise<void>;
+  /** Emit step.finished payload. */
+  emitStepFinished: (payload: Omit<ExtractSubjectPayload<typeof AgentSubjects.step.finished>, keyof AgentContext>) => Promise<void>;
+  /** Correlation tracker for tool.use -\> tool.output. */
+  toolCallTracker: ToolCallTracker;
+  /** Current content block index getter. */
+  getBlockIndex: () => number;
+  /** Increment block index after step completion. */
+  incrementBlockIndex: () => void;
+  /** Resolve model name for usage events. */
+  getUsageModel: () => string | undefined;
+}
+/**
+ * Resolution metadata returned when emitting tool output.
+ */
+interface ToolOutputResult {
+  toolCallId: string;
+  toolName: string;
+  args?: Record<string, unknown>;
+}
+/**
+ * Event-focused helper for AIAgent.
+ *
+ * Keeps event payload formatting, correlation warnings, and block-indexed
+ * step emissions out of the base class while preserving existing behavior.
+ */
+declare class AgentEventBridge {
+  private readonly emitUsagePayload;
+  private readonly emitContextWindowUpdatedPayload;
+  private readonly emitToolUsePayload;
+  private readonly emitToolOutputPayload;
+  private readonly emitAdapterLogPayload;
+  private readonly emitStepStartedPayload;
+  private readonly emitStepFinishedPayload;
+  private readonly toolCallTracker;
+  private readonly getBlockIndex;
+  private readonly incrementBlockIndex;
+  private readonly getUsageModel;
+  /**
+   * Create an event bridge with emission and correlation dependencies.
+   * @param config - Event bridge dependencies (emitters, tracker, and block-index accessors)
+   */
+  constructor(config: AgentEventBridgeConfig);
+  /**
+   * Emit usage event to global bus.
+   * @param normalized - Provider-normalized usage metrics
+   */
+  trackUsage(normalized: NormalizedCallUsage): Promise<void>;
+  /**
+   * Emit context window health signal.
+   * @param input - Raw usage and capacity metrics
+   */
+  emitContextWindowUpdate(input: ContextWindowInput): Promise<void>;
+  /**
+   * Emit tool.use event with correlation tracking.
+   * @param toolName - Tool identifier
+   * @param args - Tool arguments
+   * @param nativeId - Provider-native call ID
+   * @returns Correlation ID for the call
+   */
+  emitToolUse(toolName: string, args?: Record<string, unknown>, nativeId?: string): Promise<string>;
+  /**
+   * Emit tool.output event with best-effort correlation resolution.
+   * @param output - Tool output text
+   * @param hints - Correlation hints from adapter events
+   * @returns Resolved toolCallId, toolName (falls back to 'unknown'), and args from the matched tool.use call
+   */
+  emitToolOutput(output: string, hints: ResolveHints): Promise<ToolOutputResult>;
+  /**
+   * Emit step.started for the current block index.
+   * @param stepType - Block step type
+   * @param blockData - Optional step metadata
+   * @param content - Optional immediate block content
+   */
+  emitStepStarted(stepType: StepType, blockData?: BlockData, content?: SessionMessageBlock): Promise<void>;
+  /**
+   * Emit step.finished and advance block index.
+   * @param stepType - Completed step type
+   * @param content - Final block content
+   */
+  emitStepFinished(stepType: StepType, content: SessionMessageBlock): Promise<void>;
+}
+//#endregion
+//#region adapters/core/src/agent/agent-turn-executor.d.ts
+/**
+ * Runtime dependencies for AgentTurnExecutor.
+ */
+interface AgentTurnExecutorConfig {
+  /** Stable agent identifier. */
+  agentId: string;
+  /** Stable adapter identifier. */
+  adapterId: string;
+  /** Optional Makaio session identifier. */
+  sessionId?: string;
+  /** Capability tags reported by the adapter (e.g. `'structuredOutput'`). */
+  adapterCapabilities?: string[];
+  /** Global bus instance for hooks. */
+  globalBus: IMakaioBus;
+  /** Current connector reference resolver. */
+  getConnector: () => AIAgentConnector;
+  /** Native resume decision function. */
+  shouldUseNativeResume: ShouldUseNativeResumeFn;
+  /** Completion/lifecycle tracker hook. */
+  onMessageHandle: (messageHandle: MessageHandle) => Promise<void>;
+  /** Side-effect callback to mark agent status active before dispatch. */
+  onBeforeDispatch?: () => void | Promise<void>;
+  /** When true, PreUserMessage hooks are skipped. */
+  ephemeral?: boolean;
+}
+/**
+ * Function type for native resume decision.
+ */
+type ShouldUseNativeResumeFn = (sessionContext?: StartAgentOptions['sessionContext']) => boolean;
+/**
+ * Shared start/send-message execution pipeline for AIAgent.
+ */
+declare class AgentTurnExecutor {
+  private readonly agentId;
+  private readonly adapterId;
+  private readonly sessionId?;
+  private readonly adapterCapabilities;
+  private readonly globalBus;
+  private readonly getConnector;
+  private readonly shouldUseNativeResume;
+  private readonly onMessageHandle;
+  private readonly onBeforeDispatch?;
+  private readonly ephemeral;
+  constructor(config: AgentTurnExecutorConfig);
+  /**
+   * Execute the turn pipeline for agent.sendMessage.
+   * @param payload - agent.sendMessage request payload
+   * @returns Resolved messageId from connector handle
+   */
+  executeSendMessage(payload: SendMessageRequestPayload): Promise<{
+    messageId: string;
+  }>;
+  /**
+   * Execute the turn pipeline for agent.start.
+   * @param message - Initial message payload
+   * @param options - Start options from caller
+   * @param systemPrompt - Runtime system prompt chosen by AIAgent
+   * @param responseSchema - Runtime structured output descriptor chosen by AIAgent
+   * @returns Agent start result from connector
+   */
+  executeStart(message: NormalizedMessageInput | MessageInput, options: StartAgentOptions | undefined, systemPrompt: StartAgentOptions['systemPrompt'], responseSchema?: ResponseSchemaDescriptor): Promise<AgentStartResult>;
+  /**
+   * Resolve the pre-user hook result or preserve the caller payload for ephemeral turns.
+   * @param input - Message and context for the outgoing user turn
+   * @returns Message and session context to dispatch to the connector
+   */
+  private resolvePreUserMessageTurn;
+  /**
+   * Fire PostUserMessage hooks without blocking the turn.
+   * @param messageId - Message ID for correlation
+   */
+  private firePostUserMessageHooks;
+}
+//#endregion
+//#region adapters/core/src/adapter/types.d.ts
+/** Payload type for adapter.startAgent requests. */
+type StartAgentRequestPayload = ExtractSubjectPayload<typeof AdapterSubjects.startAgent>;
+/**
+ * Options for creating an agent, derived from a subset of `StartAgentRequestPayload`.
+ * Used by both `handleStartAgent` and the rehydration module.
+ *
+ * `providerContext` is typed directly as `ProviderContext` (not via `Pick` from the
+ * inferred payload type) because Zod loses the `CredentialRef` brand when it infers
+ * through complex union schemas. Using the canonical TypeScript type preserves
+ * the brand and ensures `resolveConnectorCredentials()` receives the correct type.
+ */
+type AgentCreationOptions = Omit<Partial<Pick<StartAgentRequestPayload, 'model' | 'cwd' | 'env' | 'allowedTools' | 'disallowedTools' | 'reasoningEffort' | 'mode' | 'mcpSessionContext' | 'harnessId' | 'clientId' | 'clientProfileName' | 'providerContext' | 'ephemeral'>>, 'providerContext'> & {
+  adapterSessionId?: string; /** Unresolved provider context (credential refs, not plaintext). */
+  providerContext?: ProviderContext;
+};
+/**
+ * Cumulative usage totals tracked per agent.
+ *
+ * Token totals (`totalInputTokens`, `totalOutputTokens`) are fully restored on
+ * rehydration by summing persisted turn history, so they reflect the lifetime
+ * of the session across process restarts.
+ *
+ * `totalCalls` is intentionally **not** restored on rehydration: it is reset to
+ * zero on each process start because the historical number of API calls is not
+ * stored per-turn with sufficient fidelity to reconstruct accurately (one turn
+ * may represent multiple API calls for streaming or multi-step adapters).
+ * Treat `totalCalls` as "calls since last process start", not a lifetime count.
+ */
+interface AgentUsageTotals {
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  totalCalls: number;
+}
+/** Result from creating an agent runtime. */
+interface AgentRuntimeCreationResult {
+  cleanup: () => void;
+}
+/**
+ * Configuration for AIAdapter constructor.
+ * @typeParam TBus - Scoped bus type for adapter-specific events
+ */
+interface AIAdapterConfig<TBus extends ScopedBus<string> = ScopedBus<string>> {
+  /** Unique adapter name (e.g., 'openai-node', 'claude-code'). */
+  name: string;
+  /** Adapter capabilities (e.g., ['streaming', 'tools', 'vision']). */
+  capabilities: string[];
+  /** Native tools built into the adapter (e.g., ['shell_command', 'apply_patch']). */
+  nativeTools?: string[];
+  /** Adapter namespace for creating scoped bus. Bus created lazily in init(). */
+  namespace: AdapterNamespace;
+  /** Optional pre-generated adapter ID. Defaults to UUID. */
+  adapterId?: string;
+  /** Optional global bus override. Defaults to MakaioBus singleton. */
+  globalBus?: IMakaioBus;
+  scopedBus?: TBus;
+  /**
+   * Optional log import configuration.
+   * When enabled, the adapter will watch for external session logs and import them as Makaio events.
+   */
+  logImport?: LogImportConfig;
+  /** Provider definitions for model lookup. Injected by runtime. */
+  definitionProviders?: readonly AdapterProviderDefinition[];
+  /** Client identifier for the application this adapter belongs to (e.g., 'claude-code', 'codex'). Omit for API-only adapters. */
+  clientId?: string;
+}
+/**
+ * Full constructor config including factory injections.
+ *
+ * Replaces the inline intersection type previously used in `AIAdapter`'s
+ * constructor signature.
+ * @typeParam TBus - Scoped bus type for adapter-specific events
+ * @typeParam TConnector - Connector type bridging to the AI SDK
+ * @typeParam TAgent - Agent implementation type (must extend AIAgent)
+ */
+interface AIAdapterConstructorConfig<TBus extends ScopedBus<string>, TConnector extends AIAgentConnector<TBus>, TAgent extends AIAgent<TBus, TConnector>> extends AIAdapterConfig {
+  /** Factory to create agent instances from config. */
+  agentFactory: (agentConfig: AIAgentConfig<TBus, TConnector>) => TAgent;
+  /** Config factory — transforms partial input into full adapter-specific config (includes adapterId). */
+  configFactory: (input: ConfigFactoryInput<TBus>) => Promise<BaseAgentConnectorConfig<TBus> & {
+    adapterId: string;
+  }>;
+  /** Connector factory — creates connector from full config (includes adapterId). */
+  connectorFactory: (config: BaseAgentConnectorConfig<TBus> & {
+    adapterId: string;
+  }) => TConnector | Promise<TConnector>;
+  /** Platform-provided defaults (cwd, env). Injected by runtime. */
+  platformDefaults?: PlatformDefaults;
+  /** Provider definitions for model lookup. Injected by runtime. */
+  definitionProviders?: readonly AdapterProviderDefinition[];
+}
+//#endregion
+//#region adapters/core/src/agent/agent-connector-lifecycle-manager.d.ts
+/**
+ * Dependencies for connector lifecycle management.
+ */
+interface AgentConnectorLifecycleManagerConfig<TBus extends ScopedBus<string>, TConnector extends AIAgentConnector<TBus>> {
+  /** Stable agent identifier (used for diagnostics). */
+  agentId: string;
+  /** Create config input for connector/config factories. */
+  buildConfigInput: (overrides?: Partial<{
+    cwd: string;
+    model: string;
+    providerContext: ProviderContext;
+    adapterSessionId: string;
+    mcpSessionContext: McpRuntimeSessionContext | McpSessionContext | LedgerSessionContext;
+  }>) => ConfigFactoryInput<TBus>;
+  /** Adapter config factory from AIAgent config. */
+  configFactory: (input: ConfigFactoryInput<TBus>) => Promise<BaseAgentConnectorConfig<TBus> & {
+    adapterId: string;
+  }>;
+  /** Connector factory from AIAgent config. */
+  connectorFactory: (config: BaseAgentConnectorConfig<TBus> & {
+    adapterId: string;
+  }) => Promise<TConnector> | TConnector;
+  /** Build onMessageSent callback for connector creation. */
+  createOnMessageSent: () => (handle: MessageHandle) => void;
+  /** Wire adapter-specific events on a connector instance. */
+  wireEvents: (connector: TConnector) => void | Promise<void>;
+  /** Emit idle lifecycle event on processing-state idle transitions. */
+  emitIdle: () => Promise<void>;
+  /** Get current connector for swap guards/baseline values. */
+  getConnector: () => TConnector;
+  /** Replace active connector reference on successful swap. */
+  setConnector: (connector: TConnector) => void;
+  /** Get runtime system prompt to preserve across swaps. */
+  getRuntimeSystemPrompt: () => SystemPrompt | undefined;
+  /** Store latest adapter session ID for enrichment after swaps. */
+  setLastKnownAdapterSessionId: (adapterSessionId: string | undefined) => void;
+}
+/**
+ * Manages connector lifecycle for AIAgent.
+ *
+ * Owns per-connector wiring cleanup registration and swap lifecycle choreography.
+ */
+declare class AgentConnectorLifecycleManager<TBus extends ScopedBus<string>, TConnector extends AIAgentConnector<TBus>> {
+  /** Cleanup functions for connector event wiring (cleared on each connector swap) */
+  private connectorWiringCleanups;
+  private readonly config;
+  constructor(config: AgentConnectorLifecycleManagerConfig<TBus, TConnector>);
+  /**
+   * Register a cleanup function for connector wiring.
+   * @param cleanup - Cleanup function to register
+   */
+  addConnectorWiringCleanup(cleanup: () => void): void;
+  /**
+   * Clear connector wiring cleanups.
+   */
+  clearConnectorWiring(): void;
+  /**
+   * Wire base and adapter-specific connector events.
+   * @param connector - Connector instance to wire
+   */
+  wireAllConnectorEvents(connector: TConnector): Promise<void>;
+  /**
+   * Replace the active connector with a fresh instance.
+   *
+   * Uses create-before-close pattern with rollback to preserve availability.
+   * @param configOverrides - Optional runtime override fields
+   */
+  swapConnector(configOverrides?: Partial<{
+    cwd: string;
+    model: string;
+    providerContext: ProviderContext;
+    mcpSessionContext: McpRuntimeSessionContext | McpSessionContext | LedgerSessionContext;
+  }>): Promise<void>;
+}
+//#endregion
+//#region adapters/core/src/agent/agent-lifecycle-emitter.d.ts
+/**
+ * Dependencies for AgentLifecycleEmitter.
+ */
+interface AgentLifecycleEmitterConfig {
+  /** Stable agent identifier for persistence updates. */
+  agentId: string;
+  /** Global bus for best-effort status updates. */
+  globalBus: IMakaioBus;
+  /** Emit callback for `agent.started`. */
+  emitStarted: (payload: Omit<AgentStarted, 'agentId' | 'adapterId' | 'adapterName' | 'adapterSessionId'>) => Promise<void>;
+  /** Emit callback for `agent.complete`. */
+  emitComplete: (payload: Omit<z.infer<typeof AgentSchemas.complete>, keyof AgentContext>) => Promise<void>;
+  /** Emit callback for `agent.session.closed`. */
+  emitSessionClosed: (payload: {
+    reason?: string;
+  }) => Promise<void>;
+  /** Hook executed before terminal completion emission. */
+  onBeforeEmitCompletion: () => Promise<void>;
+  /** Clear tool-call tracker entries on terminal outcomes. */
+  clearToolCallTracker: () => void;
+}
+/**
+ * Stateful lifecycle emitter for AIAgent terminal/start/session events.
+ */
+declare class AgentLifecycleEmitter {
+  /** Tracks whether session.closed has been emitted (emit only once). */
+  private sessionClosedEmitted;
+  /** Tracks whether agent.started has been emitted (lifecycle invariant). */
+  private agentStartedEmitted;
+  /** Tracks whether agent.complete has been emitted for the current turn. */
+  private agentCompleteEmitted;
+  /** Stashed error category consumed by the next emitCompletion call. */
+  private pendingErrorCategory?;
+  private readonly config;
+  constructor(config: AgentLifecycleEmitterConfig);
+  /**
+   * Emit `agent.started` and reset per-turn lifecycle state.
+   * @param event - Start payload without auto-enriched AgentContext fields
+   */
+  emitStart(event: Omit<AgentStarted, 'agentId' | 'adapterId' | 'adapterName' | 'adapterSessionId'>): Promise<void>;
+  /**
+   * Reset per-turn dedup state so the next completion can fire.
+   *
+   * Called when a new message handle is tracked — guarantees the guard
+   * resets per-turn even for adapters that don't emit `agent.started`
+   * on every turn (e.g., codex emits `thread_started` once per thread).
+   */
+  resetTurnState(): void;
+  /**
+   * Emit terminal completion event with deferred error-category propagation.
+   * @param result - Completion payload without AgentContext fields
+   */
+  emitCompletion(result: Omit<z.infer<typeof AgentSchemas.complete>, keyof AgentContext>): Promise<void>;
+  /**
+   * Stash error metadata for the next completion emission.
+   * @param result - Error payload from connector/runtime error handler
+   */
+  emitError(result: Pick<z.infer<typeof AgentSchemas.complete>, 'error' | 'errorCategory'>): void;
+  /**
+   * Emit `agent.session.closed` once for this agent lifecycle.
+   * @param reason - Optional closure reason
+   */
+  emitSessionClosed(reason?: string): void;
+}
+//#endregion
+//#region adapters/core/src/agent/agent-payload-emitter.d.ts
+interface AgentPayloadEventMetadata {
+  clientId?: string;
+  providerConfigId?: string;
+  occurredAt?: number;
+}
+interface AgentPayloadEventFields extends AgentPayloadEventMetadata {
+  messageId?: string;
+  turnId?: string;
+  sessionId?: string;
+}
+interface EmitGlobalOptions {
+  includeEventMetadata?: boolean;
+}
+/**
+ * Dependencies for AgentPayloadEmitter.
+ */
+interface AgentPayloadEmitterConfig {
+  /** Global bus for outbound emissions. */
+  globalBus: IMakaioBus;
+  /** Stable agent identity fields. */
+  getAgentContextBase: () => Pick<AgentContext, 'agentId' | 'adapterId' | 'adapterName'> & {
+    sessionId?: string;
+  };
+  /** Current messageId from lifecycle tracker, if any. */
+  getCurrentMessageId: () => string | undefined;
+  /** Current turnId from lifecycle tracker, if any. */
+  getCurrentTurnId: () => string | undefined;
+  /** Connector adapterSessionId, if currently available. */
+  getConnectorAdapterSessionId: () => string | undefined;
+  /** Last known adapterSessionId cached across connector swaps. */
+  getLastKnownAdapterSessionId: () => string | undefined;
+  /** Persist latest adapterSessionId after resolution. */
+  setLastKnownAdapterSessionId: (adapterSessionId: string | undefined) => void;
+  /** Async fallback to wait for adapter session ID. */
+  getAdapterSessionId: () => Promise<string>;
+  /** Live event metadata defaults resolved from current runtime state. */
+  getEventMetadataDefaults: () => AgentPayloadEventMetadata;
+}
+/**
+ * Handles agent context enrichment and global bus emissions.
+ */
+declare class AgentPayloadEmitter {
+  private readonly config;
+  /**
+   * Create a payload emitter with context resolution dependencies.
+   * @param config - Config controlling agent-context enrichment and global emissions
+   */
+  constructor(config: AgentPayloadEmitterConfig);
+  /**
+   * Enrich payload with agent context fields.
+   * @param payload - Base payload to enrich
+   * @param overrideMessageId - Explicit messageId override from caller payload
+   * @param options - Enrichment controls for optional analytics metadata defaults
+   * @returns Enriched payload with agent context
+   */
+  enrichPayload<T extends object>(payload: T, overrideMessageId?: string, options?: EmitGlobalOptions): Promise<T & AgentContext & AgentPayloadEventFields>;
+  /**
+   * Emit enriched payload to global bus.
+   * @param subject - Subject definition to emit
+   * @param payload - Payload without AgentContext fields
+   * @param options - Enrichment controls for optional analytics metadata defaults
+   */
+  emitGlobal<S extends SubjectDefinition>(subject: S, payload: Omit<ExtractSubjectPayload<S>, keyof AgentContext> & {
+    messageId?: string;
+  }, options?: EmitGlobalOptions): Promise<void>;
+}
+//#endregion
+//#region adapters/core/src/agent/agent-bus-handler-registrar.d.ts
+/**
+ * Handler bundle required to register all `agent.*` request handlers.
+ */
+interface AgentBusHandlerRegistrarConfig {
+  /** Global bus instance where handlers are registered. */
+  globalBus: IMakaioBus;
+  /** Target agent identity for filter scoping. */
+  agentId: string;
+  /** Handler for `agent.sendMessage`. */
+  onSendMessage: (ctx: RequestContext<SendMessageRequestPayload, SendMessageResponsePayload>) => Promise<void>;
+  /** Handler for `agent.interrupt`. */
+  onInterrupt: (ctx: RequestContext<AgentInterruptRequestPayload, AgentInterruptResponsePayload>) => Promise<void>;
+  /** Provider for `agent.getCapabilities` response payload. */
+  getCapabilities: () => GetCapabilitiesResponsePayload;
+  /** Handler for `agent.cwd.change`. */
+  onCwdChange: (ctx: RequestContext<AgentCwdChangeRequestPayload, AgentCwdChangeResponsePayload>) => Promise<void>;
+  /** Handler for `agent.model.change`. */
+  onModelChange: (ctx: RequestContext<AgentModelChangeRequestPayload, AgentModelChangeResponsePayload>) => Promise<void>;
+  /** Handler for `agent.mcp.servers.set`. */
+  onMcpServersSet: (ctx: RequestContext<AgentMcpServersSetRequestPayload, AgentMcpServersSetResponsePayload>) => Promise<void>;
+  /** Handler for `agent.credential.change`. */
+  onCredentialChange: (ctx: RequestContext<AgentCredentialChangeRequestPayload, AgentCredentialChangeResponsePayload>) => Promise<void>;
+}
+/**
+ * Register all stable `agent.*` bus handlers for a single agent instance.
+ * @param config - Registration configuration with handlers
+ * @returns Cleanup functions for all registrations
+ */
+declare function registerAgentBusHandlers(config: AgentBusHandlerRegistrarConfig): Array<() => void>;
+//#endregion
+//#region adapters/core/src/agent/agent-runtime-mutation-manager-config.d.ts
+/** Connector fields that can be overridden during runtime connector swaps. */
+interface AgentRuntimeConnectorOverrides {
+  cwd: string;
+  model: string;
+  providerContext: ProviderContext;
+  mcpSessionContext: McpRuntimeSessionContext | McpSessionContext | LedgerSessionContext;
+}
+/** Dependencies for runtime mutation handling. */
+interface AgentRuntimeMutationManagerConfig {
+  /** Stable agent identifier. */
+  agentId: string;
+  /** Optional Makaio session identifier. */
+  sessionId?: string;
+  /** Global bus for persistence and events. */
+  globalBus: IMakaioBus;
+  /** Read current connector. */
+  getConnector: () => AIAgentConnector;
+  /** Swap connector with runtime overrides. */
+  swapConnector: (configOverrides?: Partial<AgentRuntimeConnectorOverrides>) => Promise<void>;
+  /** Emit cwd.changed payload. */
+  emitCwdChanged: (payload: Omit<ExtractSubjectPayload<typeof AgentSubjects.cwd.changed>, 'agentId' | 'adapterId' | 'adapterName' | 'adapterSessionId'>) => Promise<void>;
+  /** Emit model.changed payload. */
+  emitModelChanged: (payload: Omit<ExtractSubjectPayload<typeof AgentSubjects.model.changed>, 'agentId' | 'adapterId' | 'adapterName' | 'adapterSessionId'>) => Promise<void>;
+  /** Read the agent's current provider context for no-op detection. */
+  getProviderContext: () => ProviderContext | undefined;
+  /** Persist provider context changes on agent config for sequential swaps. */
+  setProviderContext: (providerContext: ProviderContext) => void;
+  /** Persist reasoning effort changes on agent config for sequential swaps. */
+  setReasoningEffort: (reasoningEffort: AIReasoningLevel$1 | undefined) => void;
+  /** Persist MCP session context changes on agent config for sequential swaps. */
+  setMcpSessionContext: (mcpSessionContext: McpRuntimeSessionContext | McpSessionContext | LedgerSessionContext | undefined) => void;
+  /** Resolve supported reasoning levels for a model from the agent's available models. */
+  resolveSupportedReasoningLevels: (model: string) => ReasoningLevelMap$1 | undefined;
+}
+//#endregion
+//#region adapters/core/src/agent/agent-runtime-mutation-manager.d.ts
+/**
+ * Handles runtime mutation requests for AIAgent (cwd/model/credential changes).
+ */
+declare class AgentRuntimeMutationManager {
+  private readonly agentId;
+  private readonly sessionId?;
+  private readonly globalBus;
+  private readonly getConnector;
+  private readonly swapConnector;
+  private readonly emitCwdChanged;
+  private readonly emitModelChanged;
+  private readonly getProviderContext;
+  private readonly setProviderContext;
+  private readonly setReasoningEffort;
+  private readonly setMcpSessionContext;
+  private readonly resolveSupportedReasoningLevels;
+  private readonly mcpServersMutationManager;
+  private readonly credentialChangeSequencer;
+  private stagedModelChange?;
+  constructor(config: AgentRuntimeMutationManagerConfig);
+  /**
+   * Handle `agent.cwd.change` request.
+   * @param payload - CWD change request payload
+   * @returns CWD mutation response payload
+   */
+  handleCwdChange(payload: AgentCwdChangeRequestPayload): Promise<AgentCwdChangeResponsePayload>;
+  /**
+   * Apply staged runtime mutations before dispatching the next user turn.
+   *
+   * Staged changes are accepted while a turn is active, but they must not touch
+   * the live connector until the next turn boundary. The turn executor calls
+   * this before handing a new message to the connector, when the connector is
+   * expected to be idle.
+   */
+  applyStagedMutations(): Promise<void>;
+  /**
+   * Handle `agent.mcp.servers.set` request.
+   * @param payload - MCP server replacement request payload
+   * @returns MCP mutation response payload
+   */
+  handleMcpServersSet(payload: AgentMcpServersSetRequestPayload): Promise<AgentMcpServersSetResponsePayload>;
+  /**
+   * Handle `agent.model.change` request.
+   *
+   * Implements a four-branch decision tree based on the presence of `newModel`
+   * and `reasoningEffort` in the request payload:
+   *
+   * - Both present   → change model, then apply reasoningEffort (with fallback)
+   * - Model only     → change model, run fallback chain for reasoning
+   * - Effort only    → change reasoning in-place, no model swap logic
+   * - Neither        → no-op (return current state)
+   * @param payload - Model change request payload
+   * @returns Model mutation response payload
+   */
+  handleModelChange(payload: AgentModelChangeRequestPayload): Promise<AgentModelChangeResponsePayload>;
+  /**
+   * Apply an in-place reasoning-effort change when no model swap is requested.
+   * @param connector - The active connector
+   * @param currentModel - Current model identifier
+   * @param previousReasoningEffort - Reasoning effort before this change
+   * @param reasoningEffort - Requested effort level
+   * @returns Model mutation response payload
+   */
+  private handleReasoningOnlyChange;
+  /**
+   * Execute the model-swap path, settling the connector then resolving reasoning.
+   *
+   * **Fallback chain** for reasoning when the request does not specify an effort level:
+   * 1. Previous connector's `currentReasoningEffort` — if supported by the new model
+   * 2. `'medium'` — if supported by the new model
+   * 3. First key declared in the new model's `supportedReasoningLevels`
+   * 4. `undefined` — model does not support reasoning
+   * @param options - Swap options bundle
+   * @returns Model mutation response payload
+   */
+  private handleModelSwap;
+  /**
+   * Resolve the reasoning effort to apply after a model change.
+   *
+   * Fallback chain:
+   * 1. Requested `effort` — if supported by the new model
+   * 2. Previous connector's `currentReasoningEffort` — if supported by the new model
+   * 3. `'medium'` — if supported by the new model
+   * 4. First key declared in `supportedReasoningLevels`
+   * 5. `undefined` — model does not support reasoning
+   * @param requestedEffort - Effort level from the change request (may be absent)
+   * @param previousEffort - Current connector's reasoning effort before the change
+   * @param supportedLevels - Reasoning levels declared by the new model
+   * @returns The resolved reasoning level, or `undefined` if unsupported
+   */
+  private resolveReasoningEffort;
+  /**
+   * Confirm a connector swap when the model itself changes.
+   *
+   * Provider-only swaps skip the dialog because there is no model transition to
+   * explain to the user. Model changes retain the existing warning/edit-history
+   * workflow.
+   * @param currentModel - Active model before the requested swap
+   * @param newModel - Requested target model
+   * @param skipWarning - Whether trusted callers opted out of the warning UI
+   * @returns Proceed/result tuple for the caller
+   */
+  private confirmConnectorSwap;
+  /**
+   * Compare provider contexts using the full public-bus shape.
+   *
+   * Provider switches are not limited to config identity. Endpoint overrides,
+   * credential refs, and env-var mappings all influence connector behaviour, so
+   * callers that mutate any of those fields must force a connector rebuild.
+   * @param current - Persisted agent provider context
+   * @param next - Incoming provider context from the mutation request
+   * @returns True when the effective provider configuration changed
+   */
+  private hasProviderContextChanged;
+  /**
+   * Compare two string-keyed records, treating absent and empty consistently.
+   * @param left - First record
+   * @param right - Second record
+   * @returns True when both records contain the same keys and values
+   */
+  private haveEqualStringRecords;
+  /**
+   * Handle a credential rotation request.
+   *
+   * When a turn is active, returns `{ success: false, reason: 'turn_active' }`.
+   * Otherwise:
+   * 1. Rebuilds provider context from storage (validates providerConfigId)
+   * 2. Fires `credential.activate` so extensions prepare native stores
+   * 3. Swaps the connector with updated providerContext (forces re-resolution)
+   * @param payload - Credential change request payload
+   * @returns Success/failure result
+   */
+  handleCredentialChanged(payload: AgentCredentialChangeRequestPayload): Promise<AgentCredentialChangeResponsePayload>;
+  /**
+   * Persist runtime field updates to agent storage.
+   * @param changes - CWD/model/provider mutations to persist
+   */
+  private persistRuntimeMutation;
+}
+//#endregion
+//#region adapters/core/src/agent/mcp-call-extractor.d.ts
+/**
+ * Utilities for identifying and extracting target information from `mcp_call`
+ * tool invocations.
+ *
+ * The `mcp_call` meta-tool carries its real target as the `tool` field in the
+ * parsed JSON arguments. These helpers centralise that extraction logic so
+ * every consumer (ledger, event bridge, analytics) uses a single, tested path.
+ * @packageDocumentation
+ */
+/**
+ * Extract the target MCP tool name from parsed `mcp_call` arguments.
+ *
+ * Conforms to the `mcp_call` input schema which defines `{ tool: z.string() }`.
+ * Returns `undefined` for any non-conformant argument shape so callers can
+ * skip processing without throwing.
+ * @param args - Parsed JSON arguments object from the tool call
+ * @returns The namespaced target tool name, or `undefined` if not conformant
+ */
+declare function extractMcpCallTarget(args: Record<string, unknown>): string | undefined;
+/**
+ * Check whether a tool call name refers to the `mcp_call` meta-tool.
+ *
+ * Uses the canonical {@link MCP_CALL_TOOL_NAME} constant so the comparison
+ * stays in sync with the toolset definition automatically.
+ *
+ * Callers are responsible for stripping provider-specific prefixes before
+ * calling this function (e.g., Gemini's `default_api.` prefix must be
+ * removed at the call site — see `execute-tool-calls.ts` normalizedToolName).
+ * @param toolName - Normalized tool name from the tool call
+ * @returns `true` if this is an `mcp_call` invocation
+ */
+declare function isMcpCallTool(toolName: string): boolean;
+//#endregion
+//#region adapters/core/src/adapter/ai-adapter.d.ts
+/**
+ * Base class for AI adapters.
+ *
+ * An adapter manages a set of agents, handles adapter.* subjects as RPC endpoints,
+ * and provides clear file-to-subject mapping.
+ *
+ * Three-layer architecture:
+ * - AIAdapter: Handles adapter.* global subjects, owns agent tracking
+ * - AIAgent: Handles agent.* global subjects (filtered by agentId), wraps connector
+ * - AIAgentConnector: Owns adapter-specific namespace, SDK-level bridge
+ *
+ * Subject Ownership:
+ * - `adapter.startAgent` - Creates and starts new agents (owned by AIAdapter)
+ * - `adapter.initialized` - Emitted when adapter is ready (owned by AIAdapter)
+ * - `adapter.session.created` - Emitted after agent starts (owned by AIAdapter)
+ * - `session.agent.added` - Emitted to notify global session service (owned by AIAdapter)
+ * - `agent.*` subjects - Owned by agent instances (see ai-agent.ts)
+ * @typeParam TBus - Scoped bus type for adapter-specific events
+ * @typeParam TConnector - Connector type bridging to the AI SDK
+ * @typeParam TAgent - Agent implementation type (must extend AIAgent)
+ */
+declare abstract class AIAdapter<TBus extends ScopedBus<string> = ScopedBus<string>, TConnector extends AIAgentConnector<TBus> = AIAgentConnector<TBus>, TAgent extends AIAgent<TBus, TConnector> = AIAgent<TBus, TConnector>> {
+  /** Unique identifier for this adapter instance. */
+  readonly adapterId: string;
+  /** Adapter name (e.g., 'openai-node', 'claude-code'). */
+  readonly name: string;
+  /** Adapter capabilities for runtime feature detection. */
+  readonly capabilities: string[];
+  /** Native tools built into the adapter (e.g., ['shell_command', 'apply_patch']). */
+  readonly nativeTools: string[];
+  /** Adapter namespace for creating scoped bus. */
+  protected readonly namespace: AdapterNamespace;
+  /** Global bus for cross-adapter communication. */
+  protected readonly globalBus: IMakaioBus;
+  /** Scoped bus for adapter-specific communication. Created in init(). */
+  protected adapterBus: TBus;
+  /** Registry of active agents with session info and usage totals. */
+  private readonly registry;
+  /** Cleanup functions for bus subscriptions. */
+  private cleanupFns;
+  /** Manages agent rehydration with single-flight deduplication. */
+  private readonly rehydrationManager;
+  /** Tracks whether the adapter has been initialized. */
+  private initialized;
+  /** Client identifier for the application this adapter belongs to (e.g., 'claude-code', 'codex'). */
+  protected readonly clientId?: string;
+  /** Platform-provided defaults (cwd, env) injected by runtime. Lowest priority. */
+  protected platformDefaults?: PlatformDefaults;
+  /** Provider definitions for model lookup. Injected by runtime. */
+  protected readonly definitionProviders: readonly AdapterProviderDefinition[];
+  protected agentFactory: (agentConfig: AIAgentConfig<TBus, TConnector>) => TAgent;
+  /** Config factory - transforms partial input into full adapter-specific config (includes adapterId) */
+  protected configFactory: (input: ConfigFactoryInput<TBus>) => Promise<BaseAgentConnectorConfig<TBus> & {
+    adapterId: string;
+  }>;
+  /** Connector factory - creates connector from full config (includes adapterId) */
+  protected connectorFactory: (config: BaseAgentConnectorConfig<TBus> & {
+    adapterId: string;
+  }) => TConnector | Promise<TConnector>;
+  /**
+   * Create a new AIAdapter instance.
+   * Constructor is synchronous - stores config only. Call init() to complete setup.
+   * @param config - Adapter configuration
+   */
+  protected constructor(config: AIAdapterConstructorConfig<TBus, TConnector, TAgent>);
+  /** Set up RPC handlers and event listeners. */
+  private setupHandlers;
+  /**
+   * Handle agent.session.closed - cleanup agent + re-emit as adapter.session.closed.
+   * @param ctx - Event context with session closed payload
+   */
+  private handleSessionClosed;
+  /**
+   * Handle session.closed - evict agents when their session is closed.
+   * @param ctx - Event context with the closed session's ID
+   */
+  private handleSessionClosedByService;
+  /**
+   * Handle agent.usage - aggregate and emit session totals.
+   * @param ctx - Event context with usage payload
+   */
+  private handleUsage;
+  /**
+   * Initialize adapter - call after construction.
+   * Creates scoped bus, sets up handlers, and emits adapter.initialized event.
+   * Safe to call multiple times - subsequent calls are no-ops.
+   *
+   * Note: Agents are NOT eagerly rehydrated on startup. They are rehydrated
+   * on-demand when messages arrive (lazy rehydration via handleRehydrateAgent).
+   */
+  init(): Promise<void>;
+  /** Hook for subclass initialization. Override to perform async setup (connections, auth, etc.). */
+  protected onInit(): Promise<void>;
+  /**
+   * Create an agent instance.
+   *
+   * Subclasses implement this to instantiate their specific AIAgent subclass.
+   * The agent should NOT be started yet - that's handled by startAgent after creation.
+   * @param agentId - Pre-generated agent ID (use this, don't generate your own)
+   * @param sessionId - Makaio session ID (created or provided based on mode)
+   * @param request - The startAgent request payload
+   * @returns The agent instance (NOT started yet)
+   */
+  protected createAgent(agentId: string, sessionId: string, request: AgentCreationOptions): Promise<TAgent>;
+  /**
+   * Asynchronous cleanup for awaitable shutdown.
+   * Runs cleanup functions, aborts agents, allows subclass cleanup via onClose hook.
+   * @returns Promise that resolves when cleanup is complete
+   */
+  closeAsync(): Promise<void>;
+  /**
+   * Cleanup resources and unsubscribe from bus.
+   * Runs cleanup functions, aborts agents, allows subclass cleanup via onClose hook.
+   */
+  close(): void;
+  /** Hook for subclass cleanup. Override to perform async teardown (close connections, etc.). */
+  protected onClose(): Promise<void>;
+  /**
+   * Get an agent by ID with session info.
+   * @param agentId - Agent identifier
+   * @returns Agent with session info, or undefined if not found
+   */
+  getAgent(agentId: string): (TAgent & {
+    sessionId: string;
+    adapterSessionId: string;
+  }) | undefined;
+  /**
+   * Dispose resources for an agent.
+   *
+   * Aborts the agent and removes it from the tracking map.
+   * @param agentId - Agent identifier
+   * @returns true if agent was found and disposed, false otherwise
+   */
+  disposeAgent(agentId: string): boolean;
+  /**
+   * Get all active agents managed by this adapter.
+   * @returns Array of active agents with session info
+   */
+  getActiveAgents(): Array<TAgent & {
+    sessionId: string;
+    adapterSessionId: string;
+  }>;
+  /**
+   * Check if the adapter has been initialized.
+   * @returns true if init() has been called successfully
+   */
+  isInitialized(): boolean;
+}
+//#endregion
+//#region adapters/core/src/types/ai-adapter-definition.d.ts
+/**
+ * Definition for registering adapters with the runtime.
+ *
+ * Extends {@link AdapterDefinitionContract} with narrowed generic type parameters
+ * so the `providers` array and `createAdapter` factory are typed against the
+ * concrete adapter, connector, and bus types for this implementation.
+ *
+ * Used for dynamic adapter loading and registry.
+ * @typeParam TBus - The scoped bus type for this adapter
+ * @typeParam TConnector - The connector type
+ * @typeParam TAgent - The agent type
+ * @example
+ * ```typescript
+ * export const adapterDefinition: AIAdapterDefinition<OpenAINodeBus, OpenAINodeConnector, OpenAIAgent> = {
+ *   name: 'openai-node',
+ *   displayName: 'OpenAI',
+ *   description: 'OpenAI chat completions with streaming and tool calling',
+ *   createAdapter: (options) => createOpenAINodeAdapter({ adapterId: options?.adapterId }),
+ * };
+ * ```
+ */
+interface AIAdapterDefinition<TBus extends ScopedBus<string> = ScopedBus<string>, TConnector extends AIAgentConnector<TBus> = AIAgentConnector<TBus>, TAgent extends AIAgent<TBus, TConnector> = AIAgent<TBus, TConnector>> extends AdapterDefinitionContract<AIAdapter<TBus, TConnector, TAgent>, AIAdapterInitOptions> {
+  /**
+   * Client packages this adapter can delegate to.
+   *
+   * Each reference names a client extension by stable ID and declares the
+   * compatible client package version range. Runtime initialization still
+   * receives a selected `clientId` through {@link AIAdapterInitOptions}; this
+   * definition field is the adapter-to-client capability declaration.
+   */
+  readonly clients?: readonly AdapterClientRef[];
+  /**
+   * Adapter definitions declare client compatibility through {@link clients}.
+   *
+   * `AIAdapterInitOptions.clientId` remains the runtime-selected client
+   * override passed to adapter factories for existing client-backed adapters.
+   */
+  readonly clientId?: never;
+  /**
+   * Factory that creates and initializes the adapter instance.
+   *
+   * Inherits the typed {@link AIAdapterInitOptions} parameter from the base
+   * contract's `TOptions` generic, carrying platform defaults, log import
+   * config, and provider definitions injected at runtime.
+   * @param options - Optional initialization options injected by the runtime.
+   * @returns The initialized adapter instance.
+   */
+  readonly createAdapter: (options?: AIAdapterInitOptions) => Promise<AIAdapter<TBus, TConnector, TAgent>>;
+}
+//#endregion
+//#region adapters/core/src/types/messaging.d.ts
+/**
+ * Options for `AIAdapter.promptText()`.
+ *
+ * Minimal universal parameters with provider-specific escape hatch.
+ * @example
+ * ```typescript
+ * await adapter.promptText("Build an auth system", {
+ *   model: "gpt-4o",
+ *   sessionId: "user-123-conv-456",
+ *   providerOptions: { temperature: 0.7 }
+ * });
+ * ```
+ * @see {@link AIAdapterPromptResult} for response type
+ * @see `AIAdapter.promptText` for usage
+ * @see [Message Handling Guide](../../docs/message-handling.md)
+ */
+interface AIAdapterPromptOptions {
+  /** Model identifier (provider-specific). Defaults to adapter's configured model if omitted. */
+  model?: string;
+  /** Session ID for conversation continuity. Creates new session if omitted. Check `caps.sessionResume` for persistence support. */
+  sessionId?: string;
+  /** Provider-specific options (temperature, tools, system prompts, etc.). Type explicitly in adapter implementations. */
+  providerOptions?: unknown;
+}
+/**
+ * Successful prompt result with text response.
+ * @see {@link AIAdapterPromptResult} for discriminated union
+ */
+interface AIAdapterPromptSuccessResult {
+  /** Complete text response from AI model. For streaming events, contains final assembled text. */
+  text: string;
+}
+/**
+ * Failed prompt result. Adapters return errors as values rather than throwing.
+ * @see {@link AIAdapterPromptResult} for discriminated union
+ */
+interface AIAdapterPromptFailureResult {
+  /** Error message (string) or Error object describing failure. */
+  error: string | Error;
+}
+/**
+ * Result from `AIAdapter.promptText()`. Discriminated union of success/failure.
+ * @example
+ * ```typescript
+ * const result = await adapter.promptText("Build auth");
+ *
+ * if ('error' in result) {
+ *   console.error('Failed:', result.error);
+ * } else {
+ *   console.debug('Success:', result.text);
+ * }
+ * ```
+ * @see {@link AIAdapterPromptSuccessResult} for success structure
+ * @see {@link AIAdapterPromptFailureResult} for failure structure
+ * @see `AIAdapter.promptText` for usage
+ * @see [Message Handling Guide](../../docs/message-handling.md)
+ */
+type AIAdapterPromptResult = AIAdapterPromptFailureResult | AIAdapterPromptSuccessResult;
+//#endregion
+//#region adapters/core/src/types/mcp-integration.d.ts
+/**
+ * Describes a change to the MCP tool set mid-session.
+ * Delivered to adapters that support mid-session tool changes.
+ */
+interface McpToolChange {
+  /** Tools newly available */
+  readonly added: readonly McpToolState[];
+  /** Tools no longer available */
+  readonly removed: readonly string[];
+}
+/**
+ * Discriminated union of resources an adapter receives from McpService.
+ * Uses Makaio-native types, NOT SDK-specific types.
+ * Each adapter converts to its SDK's format internally.
+ */
+type McpSessionResources = {
+  readonly mode: 'native-passthrough';
+  readonly servers: Record<string, McpResolvedServer>;
+} | {
+  readonly mode: 'tool-injection';
+  readonly tools: readonly ToolListItem[];
+} | {
+  readonly mode: 'observe-only';
+};
+/**
+ * Adapter-specific MCP consumption strategy.
+ *
+ * Each adapter that supports MCP implements this interface to declare
+ * how it consumes MCP tools. Defined in adapter-core to avoid circular
+ * dependencies (McpService imports this interface, adapters implement it).
+ */
+interface McpIntegrationStrategy {
+  /** What this adapter needs from McpService */
+  readonly mode: 'native-passthrough' | 'tool-injection' | 'observe-only';
+  /**
+   * Whether this adapter supports mid-session tool list changes.
+   * If false, deferred injection is used (bridge current turn, native next turn).
+   */
+  readonly supportsMidSessionToolChange: boolean;
+  /**
+   * Called when a session starts. Returns adapter-specific resources.
+   * @param context - Resolved MCP config for this session (post-visibility-chain)
+   * @returns Resources the adapter needs to consume MCP tools
+   */
+  prepareMcpForSession(context: McpSessionContext): Promise<McpSessionResources>;
+  /**
+   * Called when MCP tools change mid-session (server reconnect, dynamic enable).
+   * Only invoked if `supportsMidSessionToolChange` is true.
+   * @param changes - Description of what tools changed
+   */
+  onToolsChanged?(changes: McpToolChange): Promise<void>;
+}
+//#endregion
+//#region adapters/core/src/types/conformance-test-config.d.ts
+/**
+ * Identifies a specific model offering for test execution.
+ *
+ * Resolves to a provider definition ID + model name, optionally with a default
+ * reasoning effort level for tests that exercise reasoning.
+ */
+interface TestModelRef {
+  /** Provider definition ID to test against (e.g., 'anthropic', 'nanogpt'). */
+  definitionId: string;
+  /** Model identifier within the provider (e.g., 'haiku', 'gpt-4o-mini'). */
+  modelName: string;
+  /** Default reasoning effort for tests that exercise reasoning. */
+  reasoningEffort?: AIReasoningLevel$1;
+}
+/**
+ * Provider definitions supplied by the conformance harness.
+ *
+ * Adapter packages should declare provider compatibility by stable provider ID
+ * and let the harness supply full definitions from provider contributions.
+ */
+interface CreateConformanceTestConfigOptions {
+  /** Full provider definitions available to conformance tests. */
+  providerDefinitions?: readonly ProviderDefinitionInput[];
+}
+/**
+ * Options for creating test agent instances.
+ * Omits 'bus' (provided by test config) and makes 'adapterName'/'agentId' optional (factories provide defaults).
+ */
+type CreateTestAgentOptions = Omit<BaseAgentConnectorConfig, 'bus' | 'adapterName' | 'model'> & {
+  adapterName?: string;
+  model?: string; /** Override the default test provider context when testing endpoint/credential behavior. */
+  providerContext?: ProviderContext;
+};
+interface ConformanceTestConfig<TBus extends ScopedBus<string> = ScopedBus<string>, TConnector extends AIAgentConnector<TBus> = AIAgentConnector<TBus>, TAgent extends AIAgent<TBus, TConnector> = AIAgent<TBus, TConnector>> {
+  /**
+   * Factory function for creating fresh agent instances.
+   *
+   * **Important**: Return a **new instance** on each call. The conformance
+   * suite decides when to instantiate based on isolation requirements.
+   *
+   * **DO NOT** instantiate eagerly or return a singleton—tests may run
+   * concurrently or require pristine state.
+   * @returns Fresh connector instance configured for testing
+   * @example
+   * ```typescript
+   * createConnector: () => new ClaudeCodeConnector({
+   *   bus: testBus,
+   *   agentId: `test-${Date.now()}`,
+   *   sessionId: undefined, // Let adapter generate
+   * })
+   * ```
+   */
+  createConnector: (options?: CreateTestAgentOptions) => Promise<TConnector>;
+  /**
+   * Register a tool approval handler scoped to a specific connector.
+   *
+   * The handler will only receive approval requests from the given connector
+   * (filtered by agentId). Returns an unsubscribe function for cleanup.
+   * @param connector - The connector to scope approval handling to
+   * @param context - Optional approval context (e.g., allowed tools, policies)
+   * @returns Unsubscribe function to remove the handler
+   */
+  registerToolApprovalHandler(connector: TConnector, context: ToolApprovalContext | (() => Promise<ToolApprovalContext>)): () => void;
+  /**
+   * Scoped bus instance for the adapter's namespace.
+   *
+   * This bus is used to emit events and handle requests in the adapter's
+   * domain (e.g., 'claude-code', 'codex'). The conformance suite observes
+   * events on this bus to verify behavior.
+   *
+   * **Namespace Isolation**: Each adapter should use a dedicated namespace
+   * to prevent cross-talk between concurrent test suites.
+   * @example
+   * ```typescript
+   * import { MakaioBus } from '@makaio/framework/bus';
+   *
+   * const scopedBus = MakaioBus.scoped('claude-code');
+   * ```
+   */
+  bus: ScopedBus<string>;
+  /**
+   * Optional capability flags indicating adapter-specific features.
+   *
+   * These flags allow conformance tests to:
+   * - Skip tests for unsupported features (e.g., replace mode)
+   * - Verify optional behaviors when supported
+   * - Provide clear capability documentation
+   *
+   * **Default**: All capabilities are `false` (core features only)
+   *
+   * ## When to Enable
+   *
+   * - `supportsReplace`: Adapter implements 'replace' delivery mode
+   * (clears pending queue before enqueuing message)
+   * - `supportsInterrupt`: Adapter exposes `interrupt()` method
+   * (cancels active turn mid-execution)
+   * - `supportsUsageMetrics`: Adapter emits `agent.usage` events
+   * (token counts, cost tracking)
+   * @example Full Capabilities
+   * ```typescript
+   * capabilities: {
+   *   supportsReplace: true,      // Claude Code's replace mode
+   *   supportsInterrupt: true,     // Claude Code's interrupt()
+   *   supportsUsageMetrics: true,  // Usage tracking
+   * }
+   * ```
+   * @example Core Features Only
+   * ```typescript
+   * capabilities: undefined // or omit entirely
+   * // Tests will skip replace, interrupt, tool approval, and usage tests
+   * ```
+   */
+  capabilities?: {
+    /**
+     * Supports 'replace' message delivery mode.
+     *
+     * When enabled, the adapter clears the pending message queue before
+     * enqueuing a new message. This is useful for "superseding" interactions.
+     *
+     * **Claude Code**: `true` (implements replace via MCP SDK)
+     * **Basic Adapters**: `false` (enqueue/immediate only)
+     */
+    supportsReplace?: boolean;
+    /**
+     * Supports `interrupt()` method for cancelling active turns.
+     *
+     * When enabled, the adapter can abort mid-turn execution (e.g., during
+     * a long-running tool call or reasoning phase).
+     *
+     * **Claude Code**: `true` (exposes interrupt via MCP SDK)
+     * **Stateless Adapters**: `false` (no turn state to interrupt)
+     */
+    supportsInterrupt?: boolean;
+    /**
+     * Supports usage metrics via `agent.usage` events.
+     *
+     * When enabled, the adapter emits token counts and cost data after
+     * turns or at session completion.
+     *
+     * **Claude Code**: `true` (exposes MCP usage data)
+     * **Free-Tier Adapters**: `false` (no usage tracking)
+     */
+    supportsUsageMetrics?: boolean;
+  };
+  /**
+   * Test configuration and environment options.
+   *
+   * These options tune test behavior without affecting adapter functionality.
+   * All fields are optional with sensible defaults.
+   * @example
+   * ```typescript
+   * options: {
+   *   defaultTimeout: 30000,               // 30s for slow CI
+   *   fastModel: 'claude-3-haiku-20240307', // Fast model for tests
+   *   tmpDir: '/tmp/conformance-tests',    // Isolated temp directory
+   * }
+   * ```
+   */
+  options?: {
+    /**
+     * Default timeout for tests in milliseconds.
+     *
+     * Applies to async operations like agent.start() and message delivery.
+     * Individual tests can override via Vitest's `{ timeout: ... }`.
+     * @defaultValue 10000 (10 seconds)
+     * @example
+     * ```typescript
+     * defaultTimeout: 30000 // 30s for slow CI environments
+     * ```
+     */
+    defaultTimeout?: number;
+    /**
+     * Maximum concurrent test FILES for this adapter.
+     *
+     * Controls how many conformance test files run simultaneously when using
+     * the programmatic test runner (scripts/test-adapters.ts). Each adapter
+     * can specify its own concurrency based on rate limits or resource constraints.
+     *
+     * **How it works:**
+     * - Test runner creates a per-adapter queue with this concurrency limit
+     * - Test files for this adapter run through the queue
+     * - Multiple adapters can run in parallel, each with its own queue
+     *
+     * **vs testConcurrency:**
+     * - `concurrency`: Limits concurrent TEST FILES
+     * - `testConcurrency`: Limits concurrent OPERATIONS within test helpers
+     * @defaultValue 2 (when not specified)
+     * @example
+     * ```typescript
+     * // Rate-limited API (e.g., Gemini free tier)
+     * concurrency: 1  // Run test files sequentially
+     *
+     * // High-throughput API
+     * concurrency: 4  // Run 4 test files in parallel
+     * ```
+     */
+    concurrency?: number;
+    /**
+     * Cheap/fast model for cost-sensitive test execution.
+     *
+     * Used by most conformance tests that make real API calls.
+     * Derived from the default provider preset's `fastModel` (or `defaultModel` as fallback).
+     *
+     * **Claude**: `{ definitionId: 'anthropic', modelName: 'haiku' }`
+     * **Gemini**: `{ definitionId: 'gemini', modelName: 'gemini-2.5-flash' }`
+     * @example
+     * ```typescript
+     * primaryModel: { definitionId: 'anthropic', modelName: 'haiku' }
+     * ```
+     */
+    primaryModel?: TestModelRef;
+    /**
+     * Secondary model for model-switching tests.
+     *
+     * Used as the target model in model-change conformance tests.
+     * Derived from the default provider preset's `defaultModel`.
+     *
+     * **Claude**: `{ definitionId: 'anthropic', modelName: 'sonnet' }`
+     * **Gemini**: `{ definitionId: 'gemini', modelName: 'gemini-2.5-pro' }`
+     * @example
+     * ```typescript
+     * secondaryModel: { definitionId: 'anthropic', modelName: 'sonnet' }
+     * ```
+     */
+    secondaryModel?: TestModelRef;
+    /**
+     * Temporary directory for file operations during tests.
+     *
+     * Used for tests that create artifacts (logs, cached responses, etc.).
+     * Should be isolated per test suite to prevent collisions.
+     * @defaultValue OS temp dir + random suffix
+     * @example
+     * ```typescript
+     * tmpDir: '/tmp/conformance-tests-claude-code'
+     * ```
+     */
+    tmpDir?: string;
+    /**
+     * Maximum concurrent test operations for this adapter.
+     *
+     * When set, test infrastructure serializes context creation and key
+     * operations through a per-adapter queue. Useful for adapters with
+     * aggressive rate limits (e.g., Gemini free tier).
+     *
+     * **Default**: undefined (no throttling - tests run fully concurrent)
+     * @example
+     * ```typescript
+     * testConcurrency: 1 // Serialize all test operations
+     * ```
+     */
+    testConcurrency?: number;
+  };
+  /**
+   * Factory function for creating full adapter instances (orchestration tests).
+   *
+   * **Orchestration vs Agent Tests:**
+   * - Agent tests (`createAgent`): Direct agent instantiation, bypass session manager
+   * - Orchestration tests (`createAdapter`): Full pipeline via MakaioBus.request()
+   *
+   * When provided, enables orchestration-level conformance tests that verify:
+   * - Bus request/response flow (AdapterSubjects.sendMessage, etc.)
+   * - Session manager lifecycle
+   * - Event transformation pipeline (SDK to Adapter to Global)
+   * - Multi-adapter coordination
+   *
+   * **Important**: Each call should return a fresh instance with unique adapterId
+   * for test isolation. The factory receives optional init options to allow
+   * passing a specific adapterId.
+   * @returns Fresh AIAdapter instance configured for orchestration testing
+   * @example
+   * ```typescript
+   * createAdapter: (options) => createClaudeAdapter({
+   *   adapterId: options?.adapterId ?? `test-${crypto.randomUUID()}`,
+   *   ...options
+   * })
+   * ```
+   */
+  createAdapter?: (options?: AIAdapterInitOptions) => Promise<AIAdapter<TBus, TConnector, TAgent>>;
+  /**
+   * Adapter type name for orchestration tests (e.g., 'claude-code').
+   * Required when createAdapter is provided.
+   */
+  adapterName?: string;
+  /**
+   * Unresolved provider context for the test provider.
+   *
+   * Contains credential refs (e.g. `env:ANTHROPIC_API_KEY`) built from the test
+   * provider definition's `credentialEnvVars`. Used by orchestration tests that
+   * call `startAgent` directly (bypassing the conformance `createConnector` path
+   * where `resolveTestConfig` handles credential ref building).
+   *
+   * The conformance test infrastructure registers a credential channel handler
+   * that resolves `env:` refs from `process.env` so connectors can call
+   * `resolveConnectorCredentials()` without a real credential store.
+   */
+  testProviderContext?: ProviderContext;
+  /**
+   * Optional cleanup hook for adapter-specific test infrastructure.
+   *
+   * Use this for resources created by `createTestConfig()` that outlive
+   * individual connectors/adapters (for example shared test servers).
+   */
+  cleanup?: () => Promise<void> | void;
+}
+//#endregion
+//#region adapters/core/src/session/utilities.d.ts
+/**
+ * Manages session lifecycle and abort handling.
+ *
+ * Provides coordinated abort signal management:
+ * - Idempotent abort()
+ * - Cleanup hook execution
+ * - Termination state tracking
+ *
+ * ## Design Philosophy
+ *
+ * SessionLifecycle is a simple composition utility that encapsulates
+ * abort signal coordination. It avoids inheritance coupling while providing
+ * a clean API for session termination.
+ *
+ * ## Example Usage
+ *
+ * ```typescript
+ * class MySession {
+ *   private lifecycle = new SessionLifecycle();
+ *
+ *   abort() {
+ *     this.lifecycle.abort(() => this.transport.close());
+ *   }
+ *
+ *   async sendMessage(msg: string) {
+ *     if (this.lifecycle.isTerminated) {
+ *       throw new Error('Session terminated');
+ *     }
+ *     // ... send logic
+ *   }
+ *
+ *   getAbortSignal(): AbortSignal {
+ *     return this.lifecycle.signal;
+ *   }
+ * }
+ * ```
+ */
+declare class SessionLifecycle {
+  private readonly abortController;
+  private terminated;
+  /**
+   * Create a new SessionLifecycle
+   * @param abortController - Optional AbortController to use (creates new if not provided)
+   */
+  constructor(abortController?: AbortController);
+  /**
+   * Get abort signal for provider integration
+   * @returns The abort signal
+   */
+  get signal(): AbortSignal;
+  /**
+   * Get termination state
+   * @returns True if session has been terminated
+   */
+  get isTerminated(): boolean;
+  /**
+   * Abort session and run cleanup.
+   * Idempotent - safe to call multiple times.
+   * @param cleanup - Cleanup function (sync or async)
+   */
+  abort(cleanup?: () => void | Promise<void>): void;
+  /**
+   * Register abort listener
+   * @param handler - Callback to invoke when session is aborted
+   */
+  onAbort(handler: () => void): void;
+}
+//#endregion
+//#region adapters/core/src/log-importer/base-importer.d.ts
+/**
+ * Abstract base class for log importers.
+ *
+ * Provides default processLogFile() implementation that composes
+ * extractSessionContext() + processRecords(). Adapters implement
+ * the abstract methods for their specific log format.
+ * @typeParam TRecord - The tool's native log record type
+ * @typeParam TState - The resumable state type
+ */
+declare abstract class BaseLogImporter<TRecord, TState = unknown> implements LogImporter<TRecord, TState> {
+  abstract canHandle(sample: string | JsonObject): boolean | {
+    confidence: number;
+  };
+  abstract getLogDirectory(): string;
+  /**
+   * Parse a single log record from raw input.
+   * @param line - Raw log line or parsed JSON object to parse
+   * @param sourceFilePath - Optional source file path for format-specific context
+   * @returns Parsed record or null when the input does not match the adapter format
+   */
+  abstract parseRecord(line: string | JsonObject, sourceFilePath?: string): TRecord | null;
+  abstract isMakaioManaged(sessionId: string): Promise<boolean>;
+  /**
+   * Extract discovery metadata from a log file without importing full message history.
+   * @param filePath - Absolute path to the source log file
+   * @returns Discovery metadata when parsing succeeds; rejects on unrecoverable read/parse errors
+   */
+  abstract extractDiscoveryMetadata(filePath: string): Promise<DiscoveryMetadata>;
+  abstract extractSessionContext(records: TRecord[]): LogImportSessionContext<TState>;
+  abstract processRecords(records: TRecord[], context: LogImportSessionContext<TState>): NormalizedEvent[];
+  abstract serializeState(state: TState): JsonObject;
+  abstract deserializeState(raw: JsonObject): TState;
+  /**
+   * Process a complete log file in a single call.
+   *
+   * Composes extractSessionContext + processRecords + message extraction.
+   * Adapters that need special handling (fork detection, field normalization)
+   * should override this method.
+   * @param records - All parsed records from the log file
+   * @returns Combined session metadata, events, and message payloads
+   */
+  processLogFile(records: TRecord | TRecord[]): ProcessLogFileResult;
+}
+//#endregion
+//#region adapters/core/src/log-importer/cursor-storage.d.ts
+/**
+ * Zod schema for import cursor position.
+ *
+ * Mirrors the {@link ImportCursorPosition} interface for runtime validation.
+ * Used in storage requests and responses.
+ */
+declare const ImportCursorPositionSchema: z.ZodObject<{
+  filePath: z.ZodString;
+  bytesRead: z.ZodNumber;
+  lastModified: z.ZodString;
+  sessionContext: z.ZodOptional<z.ZodCustom<{
+    model: string | null;
+    cwd: string | null;
+  } & {
+    adapterSessionId: string;
+    sessionEvent: NormalizedEvent;
+    startedEvent: NormalizedEvent;
+    state: _$type_fest0.JsonObject;
+  }, {
+    model: string | null;
+    cwd: string | null;
+  } & {
+    adapterSessionId: string;
+    sessionEvent: NormalizedEvent;
+    startedEvent: NormalizedEvent;
+    state: _$type_fest0.JsonObject;
+  }>>;
+}, z.core.$strip>;
+/**
+ * Import cursor storage namespace.
+ *
+ * Provides bus subjects for tracking import progress within external log files.
+ * Cursors enable resumption from the last successfully processed position
+ * after restarts, preventing duplicate event emission.
+ * @remarks
+ * Storage domain: `storage:importCursor`
+ *
+ * Cursors track byte offsets rather than line numbers for efficiency.
+ * The `lastModified` timestamp enables detection of file truncation/rotation:
+ * if the file's mtime is older than the stored cursor, the file was likely
+ * rotated and should be re-read from the beginning.
+ * @example
+ * ```typescript
+ * import { ImportCursorStorageSubjects } from '@makaio/framework/adapters';
+ *
+ * // Get cursor for file (returns null if not found)
+ * const result = await bus.request(ImportCursorStorageSubjects.get, {
+ *   filePath: '/home/user/.claude/projects/foo/session.jsonl',
+ * });
+ *
+ * if (result.cursor) {
+ *   console.log(`Resuming from byte ${result.cursor.bytesRead}`);
+ * }
+ *
+ * // Update cursor after processing
+ * await bus.request(ImportCursorStorageSubjects.set, {
+ *   filePath: '/home/user/.claude/projects/foo/session.jsonl',
+ *   bytesRead: 12345,
+ *   lastModified: '2025-12-09T10:30:00Z',
+ * });
+ * ```
+ * @see {@link ImportCursorPosition} - Type definition for cursor positions
+ */
+declare const ImportCursorStorageNamespace: _$_makaio_storage_core0.StorageNamespaceDefinition<"importCursor", {
+  /**
+   * Get the cursor position for a log file.
+   *
+   * Subject: `storage:importCursor.get`
+   * Type: Request (RPC)
+   * @returns Cursor position or null if not found
+   */
+  get: {
+    request: z.ZodObject<{
+      filePath: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      cursor: z.ZodNullable<z.ZodObject<{
+        filePath: z.ZodString;
+        bytesRead: z.ZodNumber;
+        lastModified: z.ZodString;
+        sessionContext: z.ZodOptional<z.ZodCustom<{
+          model: string | null;
+          cwd: string | null;
+        } & {
+          adapterSessionId: string;
+          sessionEvent: NormalizedEvent;
+          startedEvent: NormalizedEvent;
+          state: _$type_fest0.JsonObject;
+        }, {
+          model: string | null;
+          cwd: string | null;
+        } & {
+          adapterSessionId: string;
+          sessionEvent: NormalizedEvent;
+          startedEvent: NormalizedEvent;
+          state: _$type_fest0.JsonObject;
+        }>>;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+  /**
+   * Set or update the cursor position for a log file.
+   *
+   * Subject: `storage:importCursor.set`
+   * Type: Request (RPC)
+   */
+  set: {
+    request: z.ZodObject<{
+      filePath: z.ZodString;
+      bytesRead: z.ZodNumber;
+      lastModified: z.ZodString;
+      sessionContext: z.ZodOptional<z.ZodCustom<{
+        model: string | null;
+        cwd: string | null;
+      } & {
+        adapterSessionId: string;
+        sessionEvent: NormalizedEvent;
+        startedEvent: NormalizedEvent;
+        state: _$type_fest0.JsonObject;
+      }, {
+        model: string | null;
+        cwd: string | null;
+      } & {
+        adapterSessionId: string;
+        sessionEvent: NormalizedEvent;
+        startedEvent: NormalizedEvent;
+        state: _$type_fest0.JsonObject;
+      }>>;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Delete the cursor for a log file.
+   *
+   * Subject: `storage:importCursor.delete`
+   * Type: Request (RPC)
+   * @remarks
+   * Useful when a file is detected as rotated/truncated and needs
+   * to be re-read from the beginning.
+   */
+  delete: {
+    request: z.ZodObject<{
+      filePath: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+}, _$_makaio_storage_core0.StorageNamespaceExtensions>;
+/**
+ * Typed subjects for import cursor storage operations.
+ *
+ * Provides type-safe access to cursor storage subjects for bus requests.
+ * @example
+ * ```typescript
+ * // Get cursor
+ * const { cursor } = await bus.request(ImportCursorStorageSubjects.get, {
+ *   filePath: '/path/to/log.jsonl',
+ * });
+ *
+ * // Set cursor
+ * await bus.request(ImportCursorStorageSubjects.set, {
+ *   filePath: '/path/to/log.jsonl',
+ *   bytesRead: 1024,
+ *   lastModified: new Date().toISOString(),
+ * });
+ *
+ * // Delete cursor (on file rotation)
+ * await bus.request(ImportCursorStorageSubjects.delete, {
+ *   filePath: '/path/to/log.jsonl',
+ * });
+ * ```
+ */
+declare const ImportCursorStorageSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSubjectDefinitions<"storage:importCursor", {
+  /**
+   * Get the cursor position for a log file.
+   *
+   * Subject: `storage:importCursor.get`
+   * Type: Request (RPC)
+   * @returns Cursor position or null if not found
+   */
+  get: {
+    request: z.ZodObject<{
+      filePath: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      cursor: z.ZodNullable<z.ZodObject<{
+        filePath: z.ZodString;
+        bytesRead: z.ZodNumber;
+        lastModified: z.ZodString;
+        sessionContext: z.ZodOptional<z.ZodCustom<{
+          model: string | null;
+          cwd: string | null;
+        } & {
+          adapterSessionId: string;
+          sessionEvent: NormalizedEvent;
+          startedEvent: NormalizedEvent;
+          state: _$type_fest0.JsonObject;
+        }, {
+          model: string | null;
+          cwd: string | null;
+        } & {
+          adapterSessionId: string;
+          sessionEvent: NormalizedEvent;
+          startedEvent: NormalizedEvent;
+          state: _$type_fest0.JsonObject;
+        }>>;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+  /**
+   * Set or update the cursor position for a log file.
+   *
+   * Subject: `storage:importCursor.set`
+   * Type: Request (RPC)
+   */
+  set: {
+    request: z.ZodObject<{
+      filePath: z.ZodString;
+      bytesRead: z.ZodNumber;
+      lastModified: z.ZodString;
+      sessionContext: z.ZodOptional<z.ZodCustom<{
+        model: string | null;
+        cwd: string | null;
+      } & {
+        adapterSessionId: string;
+        sessionEvent: NormalizedEvent;
+        startedEvent: NormalizedEvent;
+        state: _$type_fest0.JsonObject;
+      }, {
+        model: string | null;
+        cwd: string | null;
+      } & {
+        adapterSessionId: string;
+        sessionEvent: NormalizedEvent;
+        startedEvent: NormalizedEvent;
+        state: _$type_fest0.JsonObject;
+      }>>;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+  /**
+   * Delete the cursor for a log file.
+   *
+   * Subject: `storage:importCursor.delete`
+   * Type: Request (RPC)
+   * @remarks
+   * Useful when a file is detected as rotated/truncated and needs
+   * to be re-read from the beginning.
+   */
+  delete: {
+    request: z.ZodObject<{
+      filePath: z.ZodString;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      success: z.ZodBoolean;
+    }, z.core.$strip>;
+  };
+}>, "storage:importCursor">;
+//#endregion
+//#region adapters/core/src/log-importer/cursor-memory-handler.d.ts
+/**
+ * Register in-memory import cursor storage handlers.
+ *
+ * Suitable for development, testing, and single-instance deployments.
+ * For production with persistence, implement a file-based or database-backed handler.
+ * @param bus - The bus instance to register handlers on
+ * @returns Cleanup function to unsubscribe all handlers
+ * @example
+ * ```typescript
+ * import { registerMemoryImportCursorStorage } from '@makaio/framework/adapters';
+ *
+ * const cleanup = registerMemoryImportCursorStorage(bus);
+ *
+ * // Later, when shutting down:
+ * cleanup();
+ * ```
+ */
+declare function registerMemoryImportCursorStorage(bus: IMakaioBus): () => void;
+//#endregion
+//#region adapters/core/src/log-importer/turn-tracker.d.ts
+/**
+ * Turn lifecycle state.
+ * @remarks
+ * - `idle`: No active turn, waiting for a turn to start
+ * - `active`: Turn in progress, waiting for completion
+ */
+type TurnState = 'idle' | 'active';
+/**
+ * Synthetic turn event to be emitted during log import.
+ * @remarks
+ * These events are synthesized by the state machine when it detects
+ * turn boundaries (e.g., user message starts a turn, final text completes it).
+ * @see {@link TurnTracker} - State machine that produces these events
+ */
+interface TurnEvent {
+  /** Type of turn event */
+  type: 'turn.started' | 'turn.completed';
+  /** Session ID for this turn (from the record that triggered the transition) */
+  sessionId: string;
+  /** Unique identifier for this turn instance */
+  turnId: string;
+}
+/**
+ * Configuration options for the turn tracker.
+ * @remarks
+ * Adapters provide detection functions specific to their log format:
+ * - Claude Code: `detectTurnStart` triggers on user messages,
+ *   `detectTurnComplete` triggers on final text content blocks
+ * - Copilot: Explicit `turn_start`/`turn_end` events, may bypass this tracker
+ * @typeParam TRecord - The adapter's native log record type
+ * @see {@link TurnTracker} - Uses these options
+ */
+interface TurnTrackerOptions<TRecord> {
+  /**
+   * Detect if a record indicates the start of a turn.
+   * @param record - Log record to check
+   * @returns True if this record starts a new turn
+   * @example
+   * ```typescript
+   * // Claude Code: user message starts a turn
+   * detectTurnStart: (record) => record.type === 'user'
+   * ```
+   */
+  detectTurnStart: (record: TRecord) => boolean;
+  /**
+   * Detect if a record indicates the completion of a turn.
+   * @param record - Log record to check
+   * @returns True if this record completes the current turn
+   * @example
+   * ```typescript
+   * // Claude Code: final text block completes a turn
+   * detectTurnComplete: (record) =>
+   *   record.type === 'assistant' &&
+   *   record.message?.content?.some((b) => b.type === 'text')
+   * ```
+   */
+  detectTurnComplete: (record: TRecord) => boolean;
+  /**
+   * Extract the session ID from a log record.
+   * @param record - Log record to extract session ID from
+   * @returns Session ID string
+   * @example
+   * ```typescript
+   * getSessionId: (record) => record.sessionId
+   * ```
+   */
+  getSessionId: (record: TRecord) => string;
+  /**
+   * Optional custom function to generate turn IDs.
+   * @defaultValue Uses `crypto.randomUUID()`
+   * @remarks
+   * Override this for deterministic testing or custom ID schemes.
+   * @param sessionId - The session ID for context
+   * @returns Unique turn ID string
+   */
+  generateTurnId?: (sessionId: string) => string;
+}
+/**
+ * Serialized form of TurnTracker state for persistence across chunks/restarts.
+ * @remarks
+ * Used by {@link TurnTracker.serialize} and {@link TurnTracker.restore} to
+ * enable incremental log imports that can resume processing.
+ */
+interface TurnTrackerSerializedState {
+  /** Session states keyed by session ID */
+  sessions: Record<string, {
+    state: TurnState;
+    currentTurnId?: string;
+  }>;
+}
+/**
+ * Zod schema for validating serialized TurnTracker state.
+ *
+ * Used by adapter log importers to safely deserialize cursor state
+ * without unsafe `as` casts.
+ * @see {@link TurnTrackerSerializedState} - TypeScript interface this validates
+ */
+declare const TurnTrackerSerializedStateSchema: z.ZodDefault<z.ZodObject<{
+  sessions: z.ZodRecord<z.ZodString, z.ZodObject<{
+    state: z.ZodEnum<{
+      active: "active";
+      idle: "idle";
+    }>;
+    currentTurnId: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
+/**
+ * State machine for tracking turn boundaries during log import.
+ *
+ * ## Purpose
+ *
+ * Some external tools (like Claude Code) don't emit explicit turn start/end events.
+ * This tracker synthesizes these events based on adapter-specific detection logic.
+ *
+ * ## State Transitions
+ *
+ * ```
+ * idle --[turn start detected]--> active (emit turn.started)
+ * active --[turn complete detected]--> idle (emit turn.completed)
+ * ```
+ *
+ * ## Multi-Session Support
+ *
+ * The tracker maintains independent state per session ID, enabling
+ * concurrent processing of multiple sessions from the same log file.
+ * @remarks
+ * - Thread-safe for single-threaded async processing (no mutex needed)
+ * - Stateless between sessions (each session tracked independently)
+ * - Idempotent: processing the same record twice produces consistent results
+ * @typeParam TRecord - The adapter's native log record type
+ * @example
+ * ```typescript
+ * // Create tracker for Claude Code logs
+ * const tracker = new TurnTracker({
+ *   detectTurnStart: (record) => record.type === 'user',
+ *   detectTurnComplete: (record) =>
+ *     record.type === 'assistant' &&
+ *     record.message?.content?.some((b) => b.type === 'text'),
+ *   getSessionId: (record) => record.sessionId,
+ * });
+ *
+ * // Process records
+ * for (const record of records) {
+ *   const turnEvents = tracker.processRecord(record);
+ *   for (const event of turnEvents) {
+ *     // Emit turn.started or turn.completed events
+ *     console.log(event.type, event.turnId);
+ *   }
+ * }
+ * ```
+ * @see {@link TurnTrackerOptions} - Configuration options
+ * @see {@link TurnEvent} - Emitted turn events
+ */
+declare class TurnTracker<TRecord> {
+  private readonly options;
+  private readonly sessions;
+  private readonly generateTurnId;
+  /**
+   * Create a new turn tracker.
+   * @param options - Tracker configuration with detection functions
+   */
+  constructor(options: TurnTrackerOptions<TRecord>);
+  /**
+   * Process a log record and return any turn events that should be emitted.
+   * @param record - Log record to process
+   * @returns Array of turn events (may be empty, one, or two if turn completes and new one starts)
+   * @remarks
+   * ## Transition Rules
+   *
+   * 1. **idle + turn start detected** emits `turn.started`, transitions to active
+   * 2. **active + turn complete detected** emits `turn.completed`, transitions to idle
+   * 3. **active + turn start detected** emits `turn.completed` for previous turn,
+   *    then emits `turn.started` for new turn (implicit completion)
+   * 4. **idle + turn complete detected** is a no-op (no active turn to complete)
+   *
+   * Rule 3 handles cases where a user sends another message before the assistant
+   * finishes responding (rare but possible in log replays).
+   */
+  processRecord(record: TRecord): TurnEvent[];
+  /**
+   * Get the current turn state for a session.
+   * @param sessionId - Session identifier
+   * @returns Current turn state ('idle' if session not tracked)
+   */
+  getState(sessionId: string): TurnState;
+  /**
+   * Get the current turn ID for a session.
+   * @param sessionId - Session identifier
+   * @returns Current turn ID or undefined if no active turn
+   */
+  getCurrentTurnId(sessionId: string): string | undefined;
+  /**
+   * Check if a session has an active turn.
+   * @param sessionId - Session identifier
+   * @returns True if the session has an active (non-idle) turn
+   */
+  hasActiveTurn(sessionId: string): boolean;
+  /**
+   * Reset state for a specific session.
+   * @remarks
+   * Use this when a session is known to be complete or when re-processing.
+   * @param sessionId - Session identifier
+   * @returns True if the session was tracked and removed
+   */
+  resetSession(sessionId: string): boolean;
+  /**
+   * Reset all tracked session state.
+   * @remarks
+   * Use this for cleanup or when starting fresh.
+   */
+  resetAll(): void;
+  /**
+   * Serialize the tracker state for persistence.
+   * @remarks
+   * Use this to save state between chunks or before process shutdown
+   * for incremental log imports.
+   * @returns JSON-serializable state object
+   * @see {@link restore} - Restore state from serialized form
+   */
+  serialize(): TurnTrackerSerializedState;
+  /**
+   * Restore tracker state from a serialized form.
+   * @remarks
+   * Clears all current state before restoring. Use this to resume
+   * processing after a restart or between chunks.
+   * @param serialized - State object from {@link serialize}
+   * @see {@link serialize} - Create serialized state
+   */
+  restore(serialized: TurnTrackerSerializedState): void;
+  /**
+   * Get all currently tracked session IDs.
+   * @returns Array of session IDs being tracked
+   */
+  getTrackedSessions(): string[];
+  /**
+   * Manually complete the current turn for a session.
+   * @remarks
+   * Use this for cleanup when processing ends mid-turn (e.g., end of file
+   * with an incomplete conversation). Does nothing if no active turn.
+   * @param sessionId - Session identifier
+   * @returns Turn completed event or undefined if no active turn
+   */
+  forceCompleteTurn(sessionId: string): TurnEvent | undefined;
+  /**
+   * Get or create session state for a session ID.
+   * @param sessionId - Session identifier
+   * @returns Session state (creates new idle state if not exists)
+   */
+  private getOrCreateSessionState;
+}
+//#endregion
+//#region adapters/core/src/namespaces/schemas/lifecycle.d.ts
+/**
+ * Schema for agent started event.
+ * Emitted when agent begins processing a user message.
+ */
+declare const AgentStartedEventSchema: z.ZodObject<{
+  eventType: z.ZodLiteral<"agent_started">;
+  model: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Schema for agent complete event.
+ * Emitted when agent finishes processing (success or error).
+ */
+declare const AgentCompleteEventSchema: z.ZodObject<{
+  eventType: z.ZodLiteral<"agent_complete">;
+  message: z.ZodOptional<z.ZodString>;
+  error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Schema for error event.
+ * Emitted when an error occurs during processing.
+ */
+declare const ErrorEventSchema: z.ZodObject<{
+  eventType: z.ZodLiteral<"error">;
+  message: z.ZodString;
+  code: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+  type: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type AgentStartedEvent = z.infer<typeof AgentStartedEventSchema>;
+type AgentCompleteEvent = z.infer<typeof AgentCompleteEventSchema>;
+type ErrorEvent = z.infer<typeof ErrorEventSchema>;
+//#endregion
+//#region adapters/core/src/namespaces/schemas/tool-lifecycle.d.ts
+/**
+ * Schema for tool started event.
+ * Emitted when tool execution begins.
+ */
+declare const ToolStartedEventSchema: z.ZodObject<{
+  eventType: z.ZodLiteral<"tool_started">;
+  toolName: z.ZodString;
+  toolCallId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Schema for tool completed event.
+ * Emitted when tool execution finishes (success or failure).
+ */
+declare const ToolCompletedEventSchema: z.ZodObject<{
+  eventType: z.ZodLiteral<"tool_completed">;
+  toolName: z.ZodString;
+  toolCallId: z.ZodString;
+  result: z.ZodString;
+  success: z.ZodBoolean;
+}, z.core.$strip>;
+type ToolStartedEvent = z.infer<typeof ToolStartedEventSchema>;
+type ToolCompletedEvent = z.infer<typeof ToolCompletedEventSchema>;
+//#endregion
+export { AIAdapter, type AIAdapterCapabilities, type AIAdapterCapability, type AIAdapterCapabilityRegistry, type AIAdapterConfig, type AIAdapterConstructorConfig, type AIAdapterContext, type AIAdapterDefinition, type AIAdapterInitOptions, type AIAdapterPromptFailureResult, type AIAdapterPromptOptions, type AIAdapterPromptResult, type AIAdapterPromptSuccessResult, AIAgent, type AIAgentConfig, AIAgentConnector, type AIModel, type AIReasoningLevel, type AdapterNamespace, type AdapterProviderDefinition, type AgentBusHandlerRegistrarConfig, type AgentCompleteEvent, AgentCompleteEventSchema, AgentConnectorLifecycleManager, type AgentConnectorLifecycleManagerConfig, type AgentContext, AgentEventBridge, type AgentEventBridgeConfig, type AgentIdentity, AgentLifecycleEmitter, type AgentLifecycleEmitterConfig, AgentPayloadEmitter, type AgentPayloadEmitterConfig, type AgentRuntimeCreationResult, AgentRuntimeMutationManager, type AgentRuntimeMutationManagerConfig, type AgentSendMessageOptions, type AgentStartResult, type AgentStartedEvent, AgentStartedEventSchema, AgentTurnExecutor, type AgentTurnExecutorConfig, type AgentUsageTotals, type BaseAgentConnectorConfig, BaseConnectorSession, BaseConnectorTurn, BaseLogImporter, type CompactionMetadata, type ConfigFactoryInput, type ConformanceEnvReader, type ConformanceTestConfig, type ConnectorSendMessageOptions, type ConnectorSessionConfig, type ConnectorStartOptions, type CreateConformanceTestConfigOptions, type CreateTestAgentOptions, type DiscoveryMetadata, type DiscriminatedHandler, type DiscriminatedHandlersConfig, type DiscriminatedHandlersMap, type ErrorEvent, ErrorEventSchema, type ExecutionContext, type ExternalToolIdentifier, type ExternalToolIdentifiers, type ExternalToolMeta, type FromGlobalToolApprovalFn, type GeneratedCapabilityProperties, type HarnessRequester, type IAdapterConfigFactory, type ISessionToolLedger, type ImportCursorPosition, ImportCursorPositionSchema, ImportCursorStorageNamespace, ImportCursorStorageSubjects, type ImportMetadata, type ImportSegment, type ImportSegmentLineage, type LedgerSessionContext, type LogImportConfig, type LogImportOrchestrator, type LogImportRegistration, type LogImportSessionContext, type LogImportTestConfig, type LogImporter, type LogImporterConfig, type LogImporterConstructor, type LogOrchestratorConfig, type LogOrchestratorConstructor, MAKAIO_CONFORMANCE_PRIMARY_MODEL_ENV, MAKAIO_CONFORMANCE_PROVIDER_DEFINITIONS_ENV, MAKAIO_CONFORMANCE_PROVIDER_ENV, MAKAIO_CONFORMANCE_SECONDARY_MODEL_ENV, type McpIntegrationStrategy, type McpSessionResources, type McpToolChange, type MergeResult, type MergeScopedToolApprovalOptions, type MessageDeliveryMode, MessageHandle, MessageLifecycleTracker, type MessageResult, type MessageState, type NormalizedCallUsage, type NormalizedEvent, type NormalizedMessageInput, type ParseFileResult, type PauseResult, type PlatformDefaults, ProceduralAgentConnector, type ProceduralConnectorSession, ProceduralConnectorTurn, type ProceduralTurnConfig, type ProceduralTurnState, type ProcessLogFileResult, type ProcessQueueCallbacks, type ProcessingState, type QueueableTurn, type ReasoningLevelMap, type ResolveConformanceTestPresetOptions, type ResolveHints, type ResolvedConformanceTestPreset, type ScopedBusFor, type ScopedToolApprovalRequest, type ScopedToolApprovalResponse, ScopedToolApprovalSchema, type SendMessageOptions, type SendMessageRequest, type SendMessageResponse, type SerializedContextBlock, SessionLifecycle, SessionToolLedger, type ShouldUseNativeResumeFn, type StartAgentOptions, type StartAgentRequest, type StartAgentResponse, type StorageMessagePayload, type SyncDiscriminatedHandler, type SyncDiscriminatedHandlersConfig, type SyncDiscriminatedHandlersMap, type SyncTypedEmitFn, type TestModelRef, type ToGlobalToolApprovalFn, type ToolApprovalContext, ToolCallTracker, type ToolCompletedEvent, ToolCompletedEventSchema, type ToolLedgerEntry, type ToolStartedEvent, ToolStartedEventSchema, type TurnEvent, type TurnState, type TurnSubjects, TurnTracker, type TurnTrackerOptions, type TurnTrackerSerializedState, TurnTrackerSerializedStateSchema, type TypedEmitFn, UserMessageQueue, type ValidCapability, type WireSessionConfig, type WireSessionSubjects, cleanEnvForAdapter, createAdapterNamespace, createTestProviderContext, createToolApprovalHandler, defineDiscriminatedHandlers, defineDiscriminatedHandlersSync, extractMcpCallTarget, formatContextBlockAsText, formatContextBlocksAsText, formatMessageHistoryAsTranscript, isMcpCallTool, isTextLikeMimeType, markCompletedWithFinalResult, mergeScopedToolApproval, normalizeEnvValue, normalizeMessageInput, normalizeMimeType, parseAIAdapterCapabilities, processDiscriminatedItems, processDiscriminatedItemsSync, processQueueMessages, registerAgentBusHandlers, registerMemoryImportCursorStorage, resolveConformanceTestPreset, resolveDisabledNativeTools, resolvePresetCredentials, resolveRequiredSessionId, resolveTestConfig, safeJsonStringify, serializeBlockToText, serializeTurnContext, toImportSegment };