@makaio/framework 1.0.0-dev-1783705652236 → 1.0.0-dev-1783973359164

package/dist/adapters/index.d.mts

@@ -1,10 +1,10 @@
-import { A as MessageDeliveryMode, B as AIReasoningLevel, C as NormalizedCallUsage, D as ConfigFactoryInput, E as StartAgentOptions, F as MessageResult, G as ToolLedgerEntry, H as ISessionToolLedger, I as MessageState, L as ProcessingState, M as markCompletedWithFinalResult, N as NormalizedMessageInput, O as IAdapterConfigFactory, P as normalizeMessageInput, R as SendMessageOptions, S as GetCapabilitiesResponsePayload, T as SendMessageResponsePayload, U as LedgerSessionContext, V as ReasoningLevelMap, W as SessionToolLedger, _ as BaseAgentConnectorConfig, a as AgentCredentialChangeResponsePayload, b as ContextWindowInput, c as AgentIdentity, d as AgentMcpServersSetRequestPayload, f as AgentMcpServersSetResponsePayload, g as AgentStartResult, h as AgentSendMessageOptions, i as AgentCredentialChangeRequestPayload, j as MessageHandle, k as AIAgentConnector, l as AgentInterruptRequestPayload, m as AgentModelChangeResponsePayload, n as AgentConnectorConfigOverrides, o as AgentCwdChangeRequestPayload, p as AgentModelChangeRequestPayload, r as AgentContext, s as AgentCwdChangeResponsePayload, t as AIAgentConfig, u as AgentInterruptResponsePayload, v as ConnectorSendMessageOptions, w as SendMessageRequestPayload, x as ExecutionContext, y as ConnectorStartOptions, z as AIModel } from "../types-BrUOVfwe.mjs";
-import { S as toImportSegment, _ as LogImporter, a as CompactionMetadata, b as ProcessLogFileResult, c as ExternalToolIdentifiers, d as ImportMetadata, f as ImportSegment, g as LogImportTestConfig, h as LogImportSessionContext, l as ExternalToolMeta, m as ImportSegmentTurn, n as LogOrchestratorConfig, o as DiscoveryMetadata, p as ImportSegmentLineage, r as ParseFileResult, s as ExternalToolIdentifier, u as ImportCursorPosition, v as LogImporterConfig, x as StorageMessagePayload, y as NormalizedEvent } from "../base-orchestrator-J1WKAUkF.mjs";
+import { $ as NormalizedMessageInput, C as NormalizedCallUsage, D as AdapterAuthLeaseHandle, E as StartAgentOptions, J as IAdapterConfigFactory, K as AdapterProviderDefinition, O as AdapterAuthRuntimePreparer, Q as markCompletedWithFinalResult, S as GetCapabilitiesResponsePayload, T as SendMessageResponsePayload, X as MessageDeliveryMode, Y as AIAgentConnector, Z as MessageHandle, _ as BaseAgentConnectorConfig, a as AgentCredentialChangeResponsePayload, at as AIModel, b as ContextWindowInput, c as AgentIdentity, ct as ISessionToolLedger, d as AgentMcpServersSetRequestPayload, dt as ToolLedgerEntry, et as normalizeMessageInput, f as AgentMcpServersSetResponsePayload, g as AgentStartResult, h as AgentSendMessageOptions, i as AgentCredentialChangeRequestPayload, it as SendMessageOptions, j as ResolvedAdapterRuntimeConfig, k as BoundAdapterRuntimeConfig, l as AgentInterruptRequestPayload, lt as LedgerSessionContext, m as AgentModelChangeResponsePayload, n as AgentConnectorConfigOverrides, nt as MessageState, o as AgentCwdChangeRequestPayload, ot as AIReasoningLevel, p as AgentModelChangeRequestPayload, q as ConfigFactoryInput, r as AgentContext, rt as ProcessingState, s as AgentCwdChangeResponsePayload, st as ReasoningLevelMap, t as AIAgentConfig, tt as MessageResult, u as AgentInterruptResponsePayload, ut as SessionToolLedger, v as ConnectorSendMessageOptions, w as SendMessageRequestPayload, x as ExecutionContext, y as ConnectorStartOptions } from "../types-DvKaEOOn.mjs";
+import { S as toImportSegment, _ as LogImporter, a as CompactionMetadata, b as ProcessLogFileResult, c as ExternalToolIdentifiers, d as ImportMetadata, f as ImportSegment, g as LogImportTestConfig, h as LogImportSessionContext, l as ExternalToolMeta, m as ImportSegmentTurn, n as LogOrchestratorConfig, o as DiscoveryMetadata, p as ImportSegmentLineage, r as ParseFileResult, s as ExternalToolIdentifier, u as ImportCursorPosition, v as LogImporterConfig, x as StorageMessagePayload, y as NormalizedEvent } from "../base-orchestrator-BiShpVKL.mjs";
 import { z } from "zod";
 import * as _$_makaio_core0 from "@makaio/framework/core";
 import { CreateBusNamespaceOptions, ExtractSubjectPayload, FilterablePayloadIntersection, HandlerForSubjectDefinition, RegistrableBusNamespaceDefinition, 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, NativeForkDirective, ProviderContext, ProviderDefinitionInput, ReasoningLevelMap as ReasoningLevelMap$1, RequestCorrelationContext, ResponseSchemaDescriptor, SendMessageRequest, SendMessageResponse, SessionContext, SessionMessageBlock, StartAgentRequest, StartAgentResponse, StartMode, StepType, SystemPrompt, ToolListItem } from "@makaio/framework/contracts";
+import { AIReasoningLevel as AIReasoningLevel$1, AdapterClientRef, AdapterDefinitionContract, AdapterProviderAuth, AdapterProviderRef, AdapterSubjects, AgentSchemas, AgentStarted, AgentSubjects, AgentToolApproveRequest, AgentToolApproveResponse, BlockData, HarnessDefinition, HarnessSubjects, JsonValue, McpResolvedServer, McpRuntimeSessionContext, McpSessionContext, McpToolState, Message, MessageInput, NativeForkDirective, ProtocolId, ProviderContext, ProviderDefinitionInput, ReasoningLevelMap as ReasoningLevelMap$1, RequestCorrelationContext, ResponseSchemaDescriptor, SendMessageRequest, SendMessageResponse, SessionContext, SessionMessageBlock, StartAgentRequest, StartAgentResponse, StartMode, StepType, SystemPrompt, ToolListItem } from "@makaio/framework/contracts";
 import * as _$_makaio_storage_core0 from "@makaio/framework/storage";
 import * as _$_makaio_ai_adapters_core0 from "@makaio/framework/adapters";
 import * as _$type_fest0 from "type-fest";
@@ -80,56 +80,6 @@ interface LogImportRegistration {
   clientId?: 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.
@@ -147,7 +97,7 @@ interface PlatformDefaults {
  * ```typescript
  * await adapter.init({
  *   defaultModel: "claude-3.5-sonnet",
- *   providerOptions: { apiKey: process.env.API_KEY }
+ *   providerOptions: { baseUrl: "https://api.example.com" }
  * });
  * ```
  * @see {@link AIAdapterPromptOptions} for per-message config
@@ -156,7 +106,7 @@ interface PlatformDefaults {
 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. */
+  /** Provider-specific non-secret config (base URLs, defaults, etc.). Type explicitly in adapter implementations. */
   providerOptions?: unknown;
   adapterId?: string;
   /**
@@ -177,6 +127,8 @@ interface AIAdapterInitOptions {
   definitionProviders?: AdapterProviderDefinition[];
   /** Client identifier for the application this adapter belongs to (e.g., 'claude-code', 'codex'). Omit for API-only adapters. */
   clientId?: string;
+  /** Trusted non-serializable normalized auth preparer injected by the host. */
+  prepareAuthRuntime?: AdapterAuthRuntimePreparer;
 }
 //#endregion
 //#region adapters/core/src/utils/safeJsonStringify.d.ts
@@ -564,47 +516,43 @@ type InjectedTestFields<TBus extends ScopedBus<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.
+   * Refs-only normalized provider context for conformance tests.
    *
-   * Falls back to a minimal sentinel (empty `credentialRefs`) when no definition
-   * is provided.
+   * A missing definition or auth method remains the closed unresolved state.
    */
-  providerContext: ProviderContext;
+  providerContext: ProviderContext; /** Exact selected adapter/provider protocol for endpoint resolution. */
+  providerProtocol?: ProtocolId; /** Exact selected adapter/provider auth declaration. */
+  adapterProviderAuth?: AdapterProviderAuth; /** Other compatible auth declarations contributing to environment scrubbing. */
+  compatibleProviderAuths: AdapterProviderAuth[];
 };
 /** Result type: options merged with injected fields (handles undefined options) */
-type ResolvedTestConfig<TOptions, TBus extends ScopedBus<string>> = (TOptions extends undefined ? object : TOptions) & InjectedTestFields<TBus>;
+type TestConfigOptionsInput = Omit<CreateTestAgentOptions, 'providerContext'> & {
+  providerContext?: unknown;
+};
+type ResolvedTestConfig<TBus extends ScopedBus<string>> = Omit<TestConfigOptionsInput, 'providerContext'> & InjectedTestFields<TBus>;
 /**
- * Build an unresolved provider context for conformance tests.
+ * Build a normalized 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.
+ * Explicit fields use their first declared environment source hint. Definitions
+ * without a selectable provider-owned method remain unresolved; tests for
+ * client-owned auth provide a context explicitly.
  * @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
+ * @returns Fresh refs-only provider context per call.
  */
-declare function createTestProviderContext(definition?: ProviderDefinitionInput, ambientCredentialDefinitions?: readonly ProviderDefinitionInput[]): ProviderContext;
+declare function createTestProviderContext(definition?: 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
+ * When `testProviderDefinition` is supplied, normalized auth refs and endpoint overrides
+ * are built from the definition's auth methods 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
+ * @param adapterProviderRefs - Exact adapter/provider declarations under test
  * @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>;
+declare function resolveTestConfig<TBus extends ScopedBus<string>>(options: TestConfigOptionsInput | undefined, bus: TBus, testProviderDefinition?: ProviderDefinitionInput, adapterProviderRefs?: readonly AdapterProviderRef[]): ResolvedTestConfig<TBus>;
 //#endregion
 //#region adapters/core/src/utils/resolveConformanceTestPreset.d.ts
 /** Default environment variable for selecting a conformance provider preset. */
@@ -623,8 +571,8 @@ type ConformanceEnvReader = (name: string) => string | undefined;
 interface ResolveConformanceTestPresetOptions {
   /** Adapter name used in configuration error messages. */
   adapterName: string;
-  /** Provider ID used when no env override is supplied. */
-  defaultProviderId: string;
+  /** Test provider definition ID used when no environment override is supplied. */
+  testProviderDefinitionId: string;
   /** Provider IDs accepted by this adapter's conformance config. */
   providerIds: readonly string[];
   /** Full provider definitions supplied by the conformance harness. */
@@ -658,7 +606,7 @@ interface ResolvedConformanceTestPreset {
 /**
  * Resolve a conformance test provider preset from defaults plus MAKAIO_CONFORMANCE_* overrides.
  *
- * Provider, primary model, secondary model, credentials, and endpoint overrides
+ * Provider, primary model, secondary model, authentication, 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
@@ -751,6 +699,8 @@ interface ConnectorSessionConfig<TBus extends ScopedBus<string> = ScopedBus<stri
   cwd: string;
   model: string;
   env: Record<string, string>;
+  /** Auth-free environment safe for bus-routable tool and MCP contexts. */
+  contextEnv?: Readonly<Record<string, string>>;
 }
 /**
  * Interface for turn-like objects that support pause/abort operations.
@@ -1557,17 +1507,6 @@ declare function normalizeMimeType(mimeType: string | undefined | null): string;
  */
 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.
@@ -1694,6 +1633,19 @@ declare class MessageLifecycleTracker {
   private readonly pendingTrackedHandles;
   /** Current turnId from the session orchestrator (set at sendMessage entry, cleared on completion) */
   private currentTurnId?;
+  /**
+   * Per-handle turnIds captured at {@link track} time. `currentTurnId` is a
+   * shared field that a concurrent `sendMessage` overwrites while an earlier
+   * turn is still streaming, so enrichment resolves the turnId from the
+   * active handle; the shared field only covers the window between
+   * `setCurrentTurnId` and `track`.
+   *
+   * Explicitly-undefined turnIds are recorded too (map presence, not value,
+   * gates the fallback): a handle intentionally tracked without a turn
+   * (e.g. `start()`) must keep its events turn-less instead of inheriting a
+   * later queued turn's id from the shared field.
+   */
+  private readonly handleTurnIds;
   /** Emit function injected from AIAgent */
   private readonly emitGlobal;
   constructor(config: MessageLifecycleTrackerConfig);
@@ -1720,9 +1672,15 @@ declare class MessageLifecycleTracker {
    */
   clearCurrentTurnId(): void;
   /**
-   * Get the current turnId being processed.
+   * Get the turnId of the turn that is actually executing.
    * Used by enrichPayload() to add turnId to intermediate events.
-   * @returns The current turnId or undefined if not set
+   *
+   * Resolves from the active handle's captured turnId so that a concurrent
+   * `sendMessage` (which overwrites the shared `currentTurnId` before its
+   * handle is promoted) cannot mislabel — or, downstream, drop — events of
+   * the still-streaming turn. Falls back to the shared field for the window
+   * between `setCurrentTurnId` and `track`, when no handle is active yet.
+   * @returns The executing turn's turnId or undefined if not set
    */
   getCurrentTurnId(): string | undefined;
   /**
@@ -1821,28 +1779,38 @@ declare class ToolCallTracker {
   /**
    * Register a tool.use event. Returns correlation ID to use.
    * If nativeId provided, uses that. Otherwise generates UUID.
+   * @param messageId - Message that owns this pending call
    * @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;
+  register(messageId: string, 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 messageId - Message whose pending calls may be resolved
    * @param hints - Available hints for correlation
    * @returns Correlation result with strategy metadata
    */
-  resolve(hints: ResolveHints): ResolveResult;
+  resolve(messageId: string, hints: ResolveHints): ResolveResult;
   /**
    * Clear all pending entries.
-   * Call on turn end to prevent stale entries from leaking across turns.
+   * Reserved for fatal agent teardown; normal terminal messages use {@link clearMessage}.
    */
-  clear(): void;
+  clearAll(): void;
+  /**
+   * Clear pending entries owned by one terminal message.
+   * @param messageId - Message whose correlation state reached a terminal outcome
+   */
+  clearMessage(messageId: string): void;
 }
 //#endregion
 //#region adapters/core/src/agent/agent-event-bridge.d.ts
+type MessageOwnedPayload<T> = Omit<T, keyof AgentContext> & {
+  messageId: string;
+};
 /**
  * Dependencies for AgentEventBridge.
  */
@@ -1852,15 +1820,15 @@ interface AgentEventBridgeConfig {
   /** 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>;
+  emitToolUse: (payload: MessageOwnedPayload<ExtractSubjectPayload<typeof AgentSubjects.tool.use>>) => Promise<void>;
   /** Emit tool.output payload. */
-  emitToolOutput: (payload: Omit<ExtractSubjectPayload<typeof AgentSubjects.tool.output>, keyof AgentContext>) => Promise<void>;
+  emitToolOutput: (payload: MessageOwnedPayload<ExtractSubjectPayload<typeof AgentSubjects.tool.output>>) => 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>;
+  emitStepStarted: (payload: Omit<ExtractSubjectPayload<typeof AgentSubjects.step.started>, keyof AgentContext> | MessageOwnedPayload<ExtractSubjectPayload<typeof AgentSubjects.step.started>>) => Promise<void>;
   /** Emit step.finished payload. */
-  emitStepFinished: (payload: Omit<ExtractSubjectPayload<typeof AgentSubjects.step.finished>, keyof AgentContext>) => Promise<void>;
+  emitStepFinished: (payload: Omit<ExtractSubjectPayload<typeof AgentSubjects.step.finished>, keyof AgentContext> | MessageOwnedPayload<ExtractSubjectPayload<typeof AgentSubjects.step.finished>>) => Promise<void>;
   /** Correlation tracker for tool.use -\> tool.output. */
   toolCallTracker: ToolCallTracker;
   /** Current content block index getter. */
@@ -1916,19 +1884,21 @@ declare class AgentEventBridge {
   emitContextWindowUpdate(input: ContextWindowInput): Promise<void>;
   /**
    * Emit tool.use event with correlation tracking.
+   * @param messageId - Message that owns the tool call
    * @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>;
+  emitToolUse(messageId: string, toolName: string, args?: Record<string, unknown>, nativeId?: string): Promise<string>;
   /**
    * Emit tool.output event with best-effort correlation resolution.
+   * @param messageId - Message that owns the tool output
    * @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>;
+  emitToolOutput(messageId: string, output: string, hints: ResolveHints): Promise<ToolOutputResult>;
   /**
    * Emit step.started for the current block index.
    * @param stepType - Block step type
@@ -1936,603 +1906,611 @@ declare class AgentEventBridge {
    * @param content - Optional immediate block content
    */
   emitStepStarted(stepType: StepType, blockData?: BlockData, content?: SessionMessageBlock): Promise<void>;
+  /**
+   * Emit step.started with an explicit originating message identity.
+   * @param messageId - Message that owns the step
+   * @param stepType - Block step type
+   * @param blockData - Optional step metadata
+   * @param content - Optional immediate block content
+   */
+  emitStepStartedForMessage(messageId: string, stepType: StepType, blockData?: BlockData, content?: SessionMessageBlock): Promise<void>;
+  /**
+   * Emit step.started with optional explicit message ownership.
+   * @param messageId - Optional message that owns the step.
+   * @param stepType - Semantic step kind.
+   * @param blockData - Optional block metadata.
+   * @param content - Optional initial block content.
+   */
+  private emitOwnedStepStarted;
   /**
    * Emit step.finished and advance block index.
    * @param stepType - Completed step type
    * @param content - Final block content
    */
   emitStepFinished(stepType: StepType, content: SessionMessageBlock): Promise<void>;
+  /**
+   * Emit step.finished with an explicit originating message identity and advance the block index.
+   * @param messageId - Message that owns the step
+   * @param stepType - Completed step type
+   * @param content - Final block content
+   */
+  emitStepFinishedForMessage(messageId: string, stepType: StepType, content: SessionMessageBlock): Promise<void>;
+  /**
+   * Emit step.finished with optional explicit message ownership and advance the block index.
+   * @param messageId - Optional message that owns the step.
+   * @param stepType - Semantic step kind.
+   * @param content - Completed block content.
+   */
+  private emitOwnedStepFinished;
 }
 //#endregion
-//#region adapters/core/src/agent/ai-agent.d.ts
+//#region adapters/core/src/factory/create-adapter-namespace.d.ts
 /**
- * Abstract base class for AI agents.
+ * Adapter namespace extends BusNamespace with additional metadata for adapters.
  *
- * 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
+ * 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
  */
-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 (emission is lazy — safe as field initializer). */
-  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;
+type AdapterNamespace<Domain extends string = string> = Omit<BusNamespace<Domain>, 'subjects'> & {
+  /** Original namespace definition for registration on host-provided bus instances. */readonly definition: RegistrableBusNamespaceDefinition;
+};
+/**
+ * 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> & {
+  readonly definition: RegistrableBusNamespaceDefinition;
+};
+//#endregion
+//#region adapters/core/src/agent/agent-turn-executor.d.ts
+/**
+ * Runtime dependencies for AgentTurnExecutor.
+ */
+type AgentMessageHandleCallback = (messageHandle: MessageHandle, turnId: string | undefined) => Promise<void>;
+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;
   /**
-   * Start mode for the next `emitStart()` call (consume-on-read).
+   * Whether the agent config carries a concrete resume target
+   * (`resumeAdapterSessionId`).
    *
-   * Set before dispatch; {@link emitStart} reads and clears the slot so
-   * subsequent calls within the same dispatch (e.g. Copilot SDK sub-turns)
-   * fall back to `'rotation'`. The `undefined` initial value is safe —
-   * every first-start path sets the mode before the connector fires.
+   * Used by {@link AgentTurnExecutor.deriveStartMode} to distinguish
+   * native-attach starts (resume target, no sessionContext) from
+   * truly sessionless/ephemeral starts (no resume target, no context).
    */
-  private pendingStartMode;
-  /** Normalized config with defaults applied */
-  protected readonly config: SetRequired<AIAgentConfig<TBus, TConnector>, 'globalBus'>;
-  /** Available models for context window lookup */
-  protected readonly availableModels?: AIModel[];
+  hasResumeTarget: () => boolean;
   /**
-   * Create an AIAgent instance.
+   * Set the start mode on the owning agent before connector dispatch.
    *
-   * Note: Does NOT create the connector yet - call init() after construction.
-   * @param config - Agent configuration
+   * The turn executor computes the mode from session context signals and
+   * calls this so `emitStart()` can include it in the `agent.started`
+   * payload when the connector fires its lifecycle event.
+   * @param mode - Derived start mode for this turn
    */
-  constructor(config: AIAgentConfig<TBus, TConnector>);
-  private getAgentContextBase;
-  private getEventMetadataDefaults;
-  /** @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;
+  setPendingStartMode: (mode: StartMode) => void;
+  /** Completion/lifecycle tracker hook. */
+  onMessageHandle: AgentMessageHandleCallback;
+  /** Side-effect callback to mark agent status active before dispatch. */
+  onBeforeDispatch?: () => void | Promise<void>;
+  /** Serialize the complete pre-hook-to-send boundary with credential mutations. */
+  runDispatch?: <T>(dispatch: () => Promise<T>) => Promise<T>;
+  /** 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 hasResumeTarget;
+  private readonly setPendingStartMode;
+  private readonly onMessageHandle;
+  private readonly onBeforeDispatch?;
+  private readonly runDispatch;
+  private readonly ephemeral;
+  constructor(config: AgentTurnExecutorConfig);
   /**
-   * Initialize the agent.
+   * Derive the {@link StartMode} from session context, resume decision, and
+   * resume-target presence.
    *
-   * 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>;
-  /**
-   * Emit `agent.started` with the pending start mode (consume-on-read).
+   * Decision table (evaluated top-to-bottom, first match wins):
    *
-   * Reads and clears {@link pendingStartMode}; subsequent calls within
-   * the same dispatch fall back to `'rotation'`.
-   * @param event - Optional additional fields to merge into the payload
-   */
-  protected emitStart(event?: Omit<AgentStarted, 'agentId' | 'adapterId' | 'adapterName' | 'adapterSessionId' | 'model' | 'cwd' | 'startMode'>): Promise<void>;
-  /**
-   * Set the start mode for the next `emitStart()` invocation.
+   * | sessionContext | nativeFork | hasResumeTarget | useNativeResume | isFirstTurn | Mode       |
+   * |----------------|------------|-----------------|-----------------|-------------|------------|
+   * | present        | yes        | —               | —               | —           | `fork`     |
+   * | absent         | —          | yes             | —               | —           | `resume`   |
+   * | absent         | —          | no              | —               | —           | `fresh`    |
+   * | present        | no         | —               | true            | —           | `resume`   |
+   * | present        | no         | —               | false           | true        | `fresh`    |
+   * | present        | no         | —               | false           | false       | `rotation` |
    *
-   * Called by the turn executor or `initialize()` before dispatching to
-   * the connector. The value is consumed (cleared) by the first
-   * `emitStart()` call, enforcing the one-shot invariant.
-   * @param mode - The start mode to embed in the next `agent.started` event
-   */
-  setPendingStartMode(mode: StartMode): 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.
+   * The `hasResumeTarget` rule distinguishes native-attach starts (concrete
+   * provider session to reconnect to, but no orchestrator session context) from
+   * truly sessionless/ephemeral starts. Without this signal, both cases
+   * collapsed to `'fresh'` — causing SDK SessionStart hooks to run
+   * initialization logic on a resumed conversation.
    *
-   * No longer emits `agent.error` — all terminal events flow through `agent.complete`.
-   * @param result - Error payload from the connector
+   * `hasResumeTarget` fires only when sessionContext is absent. Once the
+   * orchestrator supplies context (turn 2+), rules 4-6 take over and the
+   * resume target on the config has no further effect on mode derivation.
+   * @param sessionContext - Session context signals from the orchestrator
+   * @param useNativeResume - Whether native resume was selected for this turn
+   * @param hasResumeTarget - Whether a concrete resume target
+   *   (`resumeAdapterSessionId`) exists on the agent config
+   * @returns The derived start mode
    */
-  protected emitError(result: Pick<z.infer<typeof AgentSchemas.complete>, 'error' | 'errorCategory'>): void;
+  static deriveStartMode(sessionContext: SessionContext | undefined, useNativeResume: boolean, hasResumeTarget?: boolean): StartMode;
   /**
-   * 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')
+   * Derive the start mode for the given resolved session context, stash it
+   * as the pending mode for the next lifecycle start emission, and return
+   * the native-resume decision shared by the dispatch that follows.
+   * @param sessionContext - Session context after pre-user-message hooks
+   * @returns Whether the connector should rely on native resume
    */
-  protected emitSessionClosed(reason?: string): void;
+  private deriveAndSetPendingStartMode;
   /**
-   * Enrich a payload with agent context fields.
-   * @param payload - The base payload to enrich
-   * @returns Payload with AgentContext fields and optional messageId added
+   * Execute the turn pipeline for agent.sendMessage.
+   * @param payload - agent.sendMessage request payload
+   * @returns Resolved messageId from connector handle
    */
-  protected enrichPayload<T extends object>(payload: T): Promise<T & AgentIdentity & {
-    messageId?: string;
+  executeSendMessage(payload: SendMessageRequestPayload): Promise<{
+    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<ToolOutputResult>;
-  /**
-   * 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)
+   * 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
    */
-  protected emitStepStarted(stepType: StepType, blockData?: BlockData, content?: SessionMessageBlock): Promise<void>;
+  executeStart(message: NormalizedMessageInput | MessageInput, options: StartAgentOptions | undefined, systemPrompt: StartAgentOptions['systemPrompt'], responseSchema?: ResponseSchemaDescriptor): Promise<AgentStartResult>;
   /**
-   * 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)
+   * 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
    */
-  protected emitStepFinished(stepType: StepType, content: SessionMessageBlock): Promise<void>;
+  private resolvePreUserMessageTurn;
   /**
-   * Get the current block index (for adapters that need to track it externally).
-   * @returns Current block index within the turn
+   * Fire PostUserMessage hooks without blocking the turn.
+   * @param messageId - Message ID for correlation
    */
-  protected getBlockIndex(): number;
+  private firePostUserMessageHooks;
   /**
-   * Increment block index (for adapters using SDK-provided indices).
-   * Call after emitting step.finished if managing index externally.
+   * Enforce the connector contract for an orchestrator-assigned message identity.
+   * @param expectedMessageId - Canonical caller identity, when one was supplied.
+   * @param handle - Connector handle returned for the dispatched message.
+   * @param connector - Connector that owns fatal teardown for a violated dispatch contract.
+   * @param operation - Connector operation that produced the handle.
    */
-  protected incrementBlockIndex(): void;
+  private assertCanonicalMessageId;
+}
+//#endregion
+//#region adapters/core/src/agent/connector-runtime.d.ts
+/** Connector instance paired with its explicit client config lease. */
+interface ConnectorRuntimeHandle<TConnector extends Pick<AIAgentConnector, 'close'>> {
+  /** Live connector instance. */
+  readonly connector: TConnector;
+  /** Lease whose lifetime exactly matches this connector. */
+  readonly lease?: AdapterAuthLeaseHandle;
+}
+/** Dependencies for creating one managed connector runtime. */
+interface CreateConnectorRuntimeOptions<TBus extends ScopedBus<string>, TConnector extends AIAgentConnector<TBus>, TConfig extends BaseAgentConnectorConfig<TBus> = BaseAgentConnectorConfig<TBus>> {
+  /** Refs-only config emitted by the common adapter factory. */
+  readonly config: BoundAdapterRuntimeConfig<TBus, TConfig>;
+  /** Adapter connector constructor. */
+  readonly connectorFactory: (config: ResolvedAdapterRuntimeConfig<TBus, TConfig>) => TConnector | Promise<TConnector>;
+  /** Optional user-message callback attached only after auth preparation. */
+  readonly onMessageSent?: (handle: MessageHandle) => void;
+  /** Trusted host-local auth preparer; defaults to DirectChannel + client lease. */
+  readonly prepareAuthRuntime?: AdapterAuthRuntimePreparer<TBus, TConfig>;
+}
+//#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 owned by one terminal message. */
+  clearMessageToolCalls: (messageId: string) => void;
+}
+/**
+ * Stateful lifecycle emitter for AIAgent terminal/start/session events.
+ */
+declare class AgentLifecycleEmitter {
+  private static readonly COMPLETION_DEDUP_LIMIT;
+  /** Tracks whether session.closed has been emitted (emit only once). */
+  private sessionClosedEmitted;
+  /** Terminal messages already emitted; overlapping handles must not share a mutable turn guard. */
+  private readonly completedMessageIds;
+  private readonly completedMessageOrder;
+  private readonly config;
+  constructor(config: AgentLifecycleEmitterConfig);
   /**
-   * 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
+   * Emit `agent.started`.
+   * @param event - Start payload without auto-enriched AgentContext fields
    */
-  protected sendMessage(ctx: RequestContext<SendMessageRequestPayload, SendMessageResponsePayload>): Promise<void>;
+  emitStart(event: Omit<AgentStarted, 'agentId' | 'adapterId' | 'adapterName' | 'adapterSessionId'>): Promise<void>;
   /**
-   * Handle agent.interrupt request.
-   * Delegates to the connector's native interrupt behavior.
-   * @param ctx - Request context with interrupt payload
+   * Emit a terminal completion event for one message handle.
+   * @param result - Completion payload without AgentContext fields
    */
-  private handleInterrupt;
+  emitCompletion(result: Omit<z.infer<typeof AgentSchemas.complete>, keyof AgentContext>): Promise<void>;
   /**
-   * 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
+   * Emit `agent.session.closed` once for this agent lifecycle.
+   * @param reason - Optional closure reason
    */
-  protected addConnectorWiringCleanup(cleanup: () => void): void;
+  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;
+  /** 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;
   /**
-   * 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
+   * Create a payload emitter with context resolution dependencies.
+   * @param config - Config controlling agent-context enrichment and global emissions
    */
-  protected addBusHandlerCleanup(cleanup: () => void): void;
+  constructor(config: AgentPayloadEmitterConfig);
   /**
-   * Replace the current connector with a fresh one.
+   * Resolve the confirmed adapter session ID from synchronous sources.
    *
-   * 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
+   * `getConnectorAdapterSessionId` delegates to `getConfirmedAdapterSessionId()`
+   * which returns `undefined` for unconfirmed fork sessions — the provider has
+   * not yet assigned the child session ID. For non-fork sessions (fresh, resume,
+   * non-Claude adapters) the locally-determined ID is authoritative and returned
+   * immediately.
    *
-   * This ensures the agent always has a working connector, even if factory or wiring fails.
+   * The `lastKnownAdapterSessionId` bridges connector swaps: when the old
+   * connector is gone and the new one is not yet wired, the cached value carries
+   * the confirmed ID from the previous connector.
    *
-   * 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
+   * No async fallback is used. `connector.getAdapterSessionId()` may resolve
+   * with a provisional placeholder for fork sessions. Enrichment must never
+   * stamp unconfirmed IDs — omitting the field is safe since R8 schemas allow
+   * it optional.
+   * @returns Confirmed adapter session ID or `undefined`
    */
-  swapConnector(configOverrides?: AgentConnectorConfigOverrides): Promise<void>;
+  private resolveConfirmedAdapterSessionId;
   /**
-   * Build config factory input from agent config with optional overrides.
-   *
-   * Delegates to {@link buildConfigFactoryInput} with live connector-derived
-   * values (reasoning effort) and the agent's error sink.
-   * @param overrides - Optional field overrides (e.g., cwd, model, adapterSessionId)
-   * @returns ConfigFactoryInput ready for config factory
+   * Resolve event metadata fields, merging caller-provided values over live defaults.
+   * @param payload - Payload fields that may carry metadata overrides
+   * @param includeMetadata - Whether to include analytics metadata at all
+   * @returns Resolved metadata fields
    */
-  private buildConfigInput;
+  private resolveEventMetadata;
   /**
-   * 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;
-  /**
-   * 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
+   * 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
    */
-  private ensureConnector;
+  enrichPayload<T extends object>(payload: T, overrideMessageId?: string, options?: EmitGlobalOptions): Promise<T & AgentIdentity & AgentPayloadEventFields>;
   /**
-   * Determine whether to use native session resume (SDK manages history) or
-   * fresh-with-history (new session, injected messageHistory).
-   * @param sessionContext - Context signals from SessionOrchestrator
-   * @returns true if native resume should be used
+   * 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
    */
-  protected shouldUseNativeResume(sessionContext?: SessionContext): boolean;
+  emitGlobal<S extends SubjectDefinition>(subject: S, payload: Omit<ExtractSubjectPayload<S>, keyof AgentContext> & {
+    messageId?: string;
+    turnId?: 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;
+  /** Makaio session identity for canonical turn-number observation. */
+  sessionId?: 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;
+  /** Apply an `agent.cwd.change` payload. */
+  onCwdChange: (payload: AgentCwdChangeRequestPayload) => Promise<AgentCwdChangeResponsePayload>;
+  /** Apply an `agent.model.change` payload. */
+  onModelChange: (payload: AgentModelChangeRequestPayload) => Promise<AgentModelChangeResponsePayload>;
+  /** Apply an `agent.mcp.servers.set` payload. */
+  onMcpServersSet: (payload: AgentMcpServersSetRequestPayload) => Promise<AgentMcpServersSetResponsePayload>;
+  /** Apply an `agent.credential.change` payload. */
+  onCredentialChange: (payload: AgentCredentialChangeRequestPayload) => Promise<AgentCredentialChangeResponsePayload>;
+  /** Observe the canonical session turn number. */
+  onTurnStarted: (turnNumber: number) => void;
+  /** Mark connector tools stale after an MCP catalog mutation. */
+  onMcpToolsChanged: () => 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
+/** 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;
+  /** Agent-wide exclusivity boundary for connector-affecting operations. */
+  runExclusive: <T>(action: () => Promise<T>) => Promise<T>;
+  /** Swap connector while the caller already owns the agent-wide runtime barrier. */
+  swapConnectorUnlocked: (configOverrides?: AgentConnectorConfigOverrides, beforeCommit?: ConnectorSwapCommitGuard) => 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
+/** Coordinate every runtime mutation through one agent-wide exclusivity seam. */
+declare class AgentRuntimeMutationManager {
+  private readonly agentId;
+  private readonly globalBus;
+  private readonly getConnector;
+  private readonly runExclusive;
+  private readonly swapConnectorUnlocked;
+  private readonly emitCwdChanged;
+  private readonly mcpServersMutationManager;
+  private readonly modelMutationManager;
+  private readonly credentialChangeManager;
+  private readonly credentialChangeSequencer;
   /**
-   * Whether this adapter supports native session resume. Override in concrete agents.
-   * @returns true if native resume is supported
+   * Create the agent-level runtime mutation coordinator.
+   * @param config - Runtime collaborators and the shared exclusivity function
    */
-  protected supportsNativeResume(): boolean;
+  constructor(config: AgentRuntimeMutationManagerConfig);
   /**
-   * Whether this adapter supports provider-native session fork.
-   * Override in concrete agents that can branch from an existing provider session.
-   * @returns true if native fork is supported
+   * Handle `agent.cwd.change` through the shared runtime barrier.
+   * @param payload - CWD change request payload
+   * @returns CWD mutation response payload
    */
-  protected supportsNativeFork(): boolean;
+  handleCwdChange(payload: AgentCwdChangeRequestPayload): Promise<AgentCwdChangeResponsePayload>;
   /**
-   * Start the agent with an initial message.
-   *
-   * Ensures the agent is initialized (idempotent), runs PreUserMessage hooks,
-   * and 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
+   * Apply one CWD change while the agent-wide runtime barrier is held.
+   * @param payload - CWD change request payload
+   * @returns CWD mutation response payload
    */
-  start(message: NormalizedMessageInput | MessageInput, options?: StartAgentOptions): Promise<AgentStartResult>;
+  private handleCwdChangeUnlocked;
+  /** Apply all staged replacements while the enclosing turn barrier is held. */
+  private applyStagedMutationsUnlocked;
   /**
-   * Initialize idle (no message). Returns confirmed adapter session ID or `undefined`
-   * when the provider has not yet confirmed (idle fork sessions).
-   * @param options - Optional initialization options (system prompt, sessionContext)
-   * @returns Confirmed adapter session ID, or `undefined` for unconfirmed fork sessions.
+   * Serialize staged mutations and the complete turn pre-hook-to-send boundary.
+   * @param dispatch - Turn dispatch work that must observe one connector generation
+   * @returns Dispatch result
    */
-  initialize(options?: StartAgentOptions): Promise<string | undefined>;
-  protected onBeforeEmitCompletion(): Promise<void>;
-  protected onMessageHandle(messageHandle: MessageHandle, turnId?: string): Promise<void>;
+  runTurnDispatch<T>(dispatch: () => Promise<T>): Promise<T>;
   /**
-   * 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
+   * Handle `agent.mcp.servers.set` through the shared runtime barrier.
+   * @param payload - MCP server replacement request payload
+   * @returns MCP mutation response payload
    */
-  abort(): void;
+  handleMcpServersSet(payload: AgentMcpServersSetRequestPayload): Promise<AgentMcpServersSetResponsePayload>;
   /**
-   * 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
+   * Handle `agent.model.change` through the shared runtime barrier.
+   * @param payload - Model/provider/reasoning mutation request
+   * @returns Model mutation response payload
    */
-  getAdapterSessionId(): Promise<string>;
+  handleModelChange(payload: AgentModelChangeRequestPayload): Promise<AgentModelChangeResponsePayload>;
   /**
-   * 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
+   * Handle credential rotation through the same turn/mutation barrier.
+   * @param payload - Credential change request payload
+   * @returns Credential mutation response payload
    */
-  complete(): Promise<MessageResult | null>;
+  handleCredentialChanged(payload: AgentCredentialChangeRequestPayload): Promise<AgentCredentialChangeResponsePayload>;
   /**
-   * 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
+   * Persist committed runtime fields and require an affirmative storage result.
+   * @param changes - CWD/model/provider mutations to persist
    */
-  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;
+  private persistRuntimeMutation;
 }
 //#endregion
-//#region adapters/core/src/factory/create-adapter-namespace.d.ts
+//#region adapters/core/src/agent/mcp-call-extractor.d.ts
 /**
- * Adapter namespace extends BusNamespace with additional metadata for adapters.
+ * Utilities for identifying and extracting target information from `mcp_call`
+ * tool invocations.
  *
- * 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
+ * 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
  */
-type AdapterNamespace<Domain extends string = string> = Omit<BusNamespace<Domain>, 'subjects'> & {
-  /** Original namespace definition for registration on host-provided bus instances. */readonly definition: RegistrableBusNamespaceDefinition;
-};
 /**
- * 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;
+ * Extract the target MCP tool name from parsed `mcp_call` arguments.
  *
- * // Get scoped bus with type-safe filtering
- * const bus = await ClaudeCodeNamespace.scopedBus();
- * bus.withFilter({ content: 'test' }); // ✅ Type-checked
+ * 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.
  *
- * // 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
- * });
+ * Uses the canonical {@link MCP_CALL_TOOL_NAME} constant so the comparison
+ * stays in sync with the toolset definition automatically.
  *
- * // 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),
- * });
- * ```
+ * 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 createAdapterNamespace<N extends string, Schemas extends SchemaRecord>(domain: N, schemas: Schemas, options?: CreateBusNamespaceOptions): BusNamespace<N, SubjectRecordFromSchemaRecord<Schemas>, FilterablePayloadIntersection<SubjectRecordFromSchemaRecord<Schemas>>, Schemas> & {
-  readonly definition: RegistrableBusNamespaceDefinition;
-};
+declare function isMcpCallTool(toolName: string): boolean;
 //#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-turn-executor.d.ts
+//#region adapters/core/src/agent/request-correlation.d.ts
+/** Exact Factory Gateway headers accepted by its content-free usage boundary. */
+declare const FactoryUsageCorrelationHeaders: {
+  readonly sessionId: "x-factory-session-id";
+  readonly turnId: "x-factory-turn-id";
+  readonly messageId: "x-factory-message-id";
+  readonly llmCallId: "x-factory-llm-call-id";
+  readonly executionId: "x-factory-execution-id";
+  readonly frameId: "x-factory-frame-id";
+};
+type ProviderRequestCorrelation = RequestCorrelationContext & {
+  llmCallId: string;
+};
 /**
- * Runtime dependencies for AgentTurnExecutor.
+ * Bind caller correlation to identifiers owned by the active runtime request.
+ * Runtime values always win, preventing stale or spoofed session/message IDs.
+ * @param context - Optional orchestrator-supplied workflow correlation
+ * @param runtime - IDs known by the connector for this concrete API request
+ * @returns Fully bound correlation including one LLM-call ID
  */
-type AgentMessageHandleCallback = (messageHandle: MessageHandle, turnId: string | undefined) => Promise<void>;
-interface AgentTurnExecutorConfig {
-  /** Stable agent identifier. */
-  agentId: string;
-  /** Stable adapter identifier. */
-  adapterId: string;
-  /** Optional Makaio session identifier. */
+declare function bindProviderRequestCorrelation(context: RequestCorrelationContext | undefined, runtime: {
   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;
-  /**
-   * Whether the agent config carries a concrete resume target
-   * (`resumeAdapterSessionId`).
-   *
-   * Used by {@link AgentTurnExecutor.deriveStartMode} to distinguish
-   * native-attach starts (resume target, no sessionContext) from
-   * truly sessionless/ephemeral starts (no resume target, no context).
-   */
-  hasResumeTarget: () => boolean;
-  /**
-   * Set the start mode on the owning agent before connector dispatch.
-   *
-   * The turn executor computes the mode from session context signals and
-   * calls this so `emitStart()` can include it in the `agent.started`
-   * payload when the connector fires its lifecycle event.
-   * @param mode - Derived start mode for this turn
-   */
-  setPendingStartMode: (mode: StartMode) => void;
-  /** Completion/lifecycle tracker hook. */
-  onMessageHandle: AgentMessageHandleCallback;
-  /** 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;
+  messageId: string;
+  llmCallId: string;
+}): ProviderRequestCorrelation;
 /**
- * Shared start/send-message execution pipeline for AIAgent.
+ * Project a validated correlation context to the Factory Gateway allowlist.
+ *
+ * No arbitrary metadata or headers can cross this boundary. Callers must also
+ * explicitly opt into the `factory-v1` transport mode before using the result.
+ * @param correlation - Content-free runtime and workflow identifiers
+ * @returns Header record accepted by the Factory Gateway usage boundary
  */
-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 hasResumeTarget;
-  private readonly setPendingStartMode;
-  private readonly onMessageHandle;
-  private readonly onBeforeDispatch?;
-  private readonly ephemeral;
-  constructor(config: AgentTurnExecutorConfig);
-  /**
-   * Derive the {@link StartMode} from session context, resume decision, and
-   * resume-target presence.
-   *
-   * Decision table (evaluated top-to-bottom, first match wins):
-   *
-   * | sessionContext | nativeFork | hasResumeTarget | useNativeResume | isFirstTurn | Mode       |
-   * |----------------|------------|-----------------|-----------------|-------------|------------|
-   * | present        | yes        | —               | —               | —           | `fork`     |
-   * | absent         | —          | yes             | —               | —           | `resume`   |
-   * | absent         | —          | no              | —               | —           | `fresh`    |
-   * | present        | no         | —               | true            | —           | `resume`   |
-   * | present        | no         | —               | false           | true        | `fresh`    |
-   * | present        | no         | —               | false           | false       | `rotation` |
-   *
-   * The `hasResumeTarget` rule distinguishes native-attach starts (concrete
-   * provider session to reconnect to, but no orchestrator session context) from
-   * truly sessionless/ephemeral starts. Without this signal, both cases
-   * collapsed to `'fresh'` — causing SDK SessionStart hooks to run
-   * initialization logic on a resumed conversation.
-   *
-   * `hasResumeTarget` fires only when sessionContext is absent. Once the
-   * orchestrator supplies context (turn 2+), rules 4-6 take over and the
-   * resume target on the config has no further effect on mode derivation.
-   * @param sessionContext - Session context signals from the orchestrator
-   * @param useNativeResume - Whether native resume was selected for this turn
-   * @param hasResumeTarget - Whether a concrete resume target
-   *   (`resumeAdapterSessionId`) exists on the agent config
-   * @returns The derived start mode
-   */
-  static deriveStartMode(sessionContext: SessionContext | undefined, useNativeResume: boolean, hasResumeTarget?: boolean): StartMode;
-  /**
-   * Derive the start mode for the given resolved session context, stash it
-   * as the pending mode for the next lifecycle start emission, and return
-   * the native-resume decision shared by the dispatch that follows.
-   * @param sessionContext - Session context after pre-user-message hooks
-   * @returns Whether the connector should rely on native resume
-   */
-  private deriveAndSetPendingStartMode;
-  /**
-   * 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;
-}
+declare function buildFactoryUsageCorrelationHeaders(correlation: ProviderRequestCorrelation): Record<string, string>;
 //#endregion
 //#region adapters/core/src/adapter/types.d.ts
 /** Payload type for adapter.startAgent requests. */
@@ -2637,6 +2615,8 @@ interface AIAdapterConfig<TBus extends ScopedBus<string> = ScopedBus<string>> {
   definitionProviders?: readonly AdapterProviderDefinition[];
   /** Client identifier for the application this adapter belongs to (e.g., 'claude-code', 'codex'). Omit for API-only adapters. */
   clientId?: string;
+  /** Trusted non-serializable normalized auth preparer injected by the host. */
+  prepareAuthRuntime?: AdapterAuthRuntimePreparer<TBus>;
 }
 /**
  * Full constructor config including factory injections.
@@ -2665,6 +2645,17 @@ interface AIAdapterConstructorConfig<TBus extends ScopedBus<string>, TConnector
 }
 //#endregion
 //#region adapters/core/src/agent/agent-connector-lifecycle-manager.d.ts
+/** Sanitized lifecycle diagnostic emitted after a replacement became primary. */
+interface ConnectorCleanupDiagnostic {
+  /** Stable machine-readable failure category. */
+  readonly code: 'previous-connector-cleanup-failed';
+  /** Lifecycle stage whose cleanup failed. */
+  readonly stage: 'swap-old-runtime';
+  /** Agent owning the replacement connector. */
+  readonly agentId: string;
+}
+/** Final async guard run after the replacement is ready but before it becomes primary. */
+type ConnectorSwapCommitGuard = () => void | Promise<void>;
 /**
  * Dependencies for connector lifecycle management.
  */
@@ -2681,20 +2672,24 @@ interface AgentConnectorLifecycleManagerConfig<TBus extends ScopedBus<string>, T
   connectorFactory: (config: BaseAgentConnectorConfig<TBus> & {
     adapterId: string;
   }) => Promise<TConnector> | TConnector;
+  /** Trusted host-local auth preparer shared by every connector generation. */
+  prepareAuthRuntime?: AdapterAuthRuntimePreparer<TBus>;
   /** 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 current connector plus its explicit client config lease. */
+  getConnectorRuntime: () => ConnectorRuntimeHandle<TConnector>;
+  /** Replace active connector and lease together on successful swap. */
+  setConnectorRuntime: (runtime: ConnectorRuntimeHandle<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;
+  /** Publish a sanitized cleanup diagnostic without exposing connector errors. */
+  reportCleanupFailure: (diagnostic: ConnectorCleanupDiagnostic) => void | Promise<void>;
 }
 /**
  * Manages connector lifecycle for AIAgent.
@@ -2725,448 +2720,432 @@ declare class AgentConnectorLifecycleManager<TBus extends ScopedBus<string>, TCo
    *
    * Uses create-before-close pattern with rollback to preserve availability.
    * @param configOverrides - Optional runtime override fields
+   * @param beforeCommit - Final guard after replacement initialization and before publication
    */
-  swapConnector(configOverrides?: AgentConnectorConfigOverrides): 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>;
+  swapConnector(configOverrides?: AgentConnectorConfigOverrides, beforeCommit?: ConnectorSwapCommitGuard): 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).
+   * Build and materialize the replacement connector runtime.
+   * @param currentConnector - Active connector whose runtime values provide defaults
+   * @param configOverrides - Optional requested runtime changes
+   * @returns Prepared replacement connector and auth lease
    */
-  resetTurnState(): void;
+  private createReplacementRuntime;
   /**
-   * Emit terminal completion event with deferred error-category propagation.
-   * @param result - Completion payload without AgentContext fields
+   * Wire and initialize a replacement, restoring the current wiring on failure.
+   * @param newRuntime - Replacement connector and auth lease
+   * @param oldWiringCleanups - Wiring still owned by the active connector
+   * @param beforeCommit - Optional final publication guard
+   * @returns Provider-confirmed session ID, when the replacement has one
    */
-  emitCompletion(result: Omit<z.infer<typeof AgentSchemas.complete>, keyof AgentContext>): Promise<void>;
+  private initializeReplacement;
   /**
-   * Stash error metadata for the next completion emission.
-   * @param result - Error payload from connector/runtime error handler
+   * Run superseded connector wiring cleanups without failing the committed swap.
+   * @param cleanups - Previous connector wiring cleanups
    */
-  emitError(result: Pick<z.infer<typeof AgentSchemas.complete>, 'error' | 'errorCategory'>): void;
+  private runWiringCleanups;
   /**
-   * Emit `agent.session.closed` once for this agent lifecycle.
-   * @param reason - Optional closure reason
+   * Close the superseded runtime and publish only a sanitized diagnostic on failure.
+   * @param currentRuntime - Superseded connector and auth lease
    */
-  emitSessionClosed(reason?: string): void;
+  private closePreviousRuntime;
 }
 //#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;
-}
+//#region adapters/core/src/agent/ai-agent.d.ts
 /**
- * Dependencies for AgentPayloadEmitter.
+ * 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
  */
-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;
-  /** 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;
+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;
+  /** Connector and auth lease are replaced and released as one lifecycle unit. */
+  private connectorRuntime;
+  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 (emission is lazy — safe as field initializer). */
+  protected readonly lifecycleTracker: MessageLifecycleTracker;
+  /** Tracks tool.use → tool.output correlation across adapters. */
+  protected readonly toolCallTracker: ToolCallTracker;
+  /** Event-focused helper for usage/tool/step emissions. */
+  protected readonly eventBridge: AgentEventBridge;
+  /** 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;
+  /** Serialized connector replacement and runtime-config publication owner. */
+  private readonly connectorSwapCoordinator;
+  /** 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;
   /**
-   * Create a payload emitter with context resolution dependencies.
-   * @param config - Config controlling agent-context enrichment and global emissions
+   * Start mode for the next `emitStart()` call (consume-on-read).
+   *
+   * Set before dispatch; {@link emitStart} reads and clears the slot so
+   * subsequent calls within the same dispatch (e.g. Copilot SDK sub-turns)
+   * fall back to `'rotation'`. The `undefined` initial value is safe —
+   * every first-start path sets the mode before the connector fires.
    */
-  constructor(config: AgentPayloadEmitterConfig);
+  private pendingStartMode;
+  /** Normalized config with defaults applied */
+  protected readonly config: SetRequired<AIAgentConfig<TBus, TConnector>, 'globalBus'>;
+  /** Available models for context window lookup */
+  protected readonly availableModels?: AIModel[];
   /**
-   * Resolve the confirmed adapter session ID from synchronous sources.
+   * Create an AIAgent instance.
    *
-   * `getConnectorAdapterSessionId` delegates to `getConfirmedAdapterSessionId()`
-   * which returns `undefined` for unconfirmed fork sessions — the provider has
-   * not yet assigned the child session ID. For non-fork sessions (fresh, resume,
-   * non-Claude adapters) the locally-determined ID is authoritative and returned
-   * immediately.
+   * Note: Does NOT create the connector yet - call init() after construction.
+   * @param config - Agent configuration
+   */
+  constructor(config: AIAgentConfig<TBus, TConnector>);
+  /**
+   * Create the connector lifecycle collaborator bound to this agent instance.
+   * @param emitGlobal - Enriched global event emitter
+   * @param setLastKnownAdapterSessionId - Sink for the latest confirmed provider session
+   * @returns Connector lifecycle manager for this agent
+   */
+  private createConnectorLifecycleManager;
+  private getEventMetadataDefaults;
+  /** @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.
    *
-   * The `lastKnownAdapterSessionId` bridges connector swaps: when the old
-   * connector is gone and the new one is not yet wired, the cached value carries
-   * the confirmed ID from the previous connector.
+   * 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>;
+  /**
+   * Emit `agent.started` with the pending start mode (consume-on-read).
    *
-   * No async fallback is used. `connector.getAdapterSessionId()` may resolve
-   * with a provisional placeholder for fork sessions. Enrichment must never
-   * stamp unconfirmed IDs — omitting the field is safe since R8 schemas allow
-   * it optional.
-   * @returns Confirmed adapter session ID or `undefined`
+   * Reads and clears {@link pendingStartMode}; subsequent calls within
+   * the same dispatch fall back to `'rotation'`.
+   * @param event - Optional additional fields to merge into the payload
    */
-  private resolveConfirmedAdapterSessionId;
+  protected emitStart(event?: Omit<AgentStarted, 'agentId' | 'adapterId' | 'adapterName' | 'adapterSessionId' | 'model' | 'cwd' | 'startMode'>): Promise<void>;
   /**
-   * Resolve event metadata fields, merging caller-provided values over live defaults.
-   * @param payload - Payload fields that may carry metadata overrides
-   * @param includeMetadata - Whether to include analytics metadata at all
-   * @returns Resolved metadata fields
+   * Set the start mode for the next `emitStart()` invocation.
+   *
+   * Called by the turn executor or `initialize()` before dispatching to
+   * the connector. The value is consumed (cleared) by the first
+   * `emitStart()` call, enforcing the one-shot invariant.
+   * @param mode - The start mode to embed in the next `agent.started` event
    */
-  private resolveEventMetadata;
+  setPendingStartMode(mode: StartMode): void;
+  protected emitCompletion(result: Omit<z.infer<typeof AgentSchemas.complete>, keyof AgentContext>): Promise<void>;
   /**
-   * 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
+   * 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')
    */
-  enrichPayload<T extends object>(payload: T, overrideMessageId?: string, options?: EmitGlobalOptions): Promise<T & AgentIdentity & AgentPayloadEventFields>;
+  protected emitSessionClosed(reason?: string): void;
   /**
-   * 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
+   * Enrich a payload with agent context fields.
+   * @param payload - The base payload to enrich
+   * @returns Payload with AgentContext fields and optional messageId added
    */
-  emitGlobal<S extends SubjectDefinition>(subject: S, payload: Omit<ExtractSubjectPayload<S>, keyof AgentContext> & {
+  protected enrichPayload<T extends object>(payload: T): Promise<T & AgentIdentity & {
     messageId?: string;
-    turnId?: 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;
-  adapterSessionId: string;
-  resumeAdapterSessionId: string;
-  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);
+  }>;
+  /**
+   * 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 a tool.use event for an explicitly identified originating message.
+   * @param messageId - Message that owns the tool call
+   * @param toolName - Name of the tool being invoked
+   * @param args - Tool arguments
+   * @param nativeId - Provider-native tool call identifier
+   * @returns Correlation identifier used for the call
+   */
+  protected emitToolUse(messageId: string, toolName: string, args?: Record<string, unknown>, nativeId?: string): Promise<string>;
+  /**
+   * Emit a tool.output event for an explicitly identified originating message.
+   * @param messageId - Message that owns the tool call
+   * @param output - Tool output content
+   * @param hints - Provider correlation hints
+   * @returns Resolved tool-call metadata
+   */
+  protected emitToolOutput(messageId: string, output: string, hints: ResolveHints): Promise<ToolOutputResult>;
+  /**
+   * 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>;
   /**
-   * Handle `agent.cwd.change` request.
-   * @param payload - CWD change request payload
-   * @returns CWD mutation response payload
+   * Get the current block index (for adapters that need to track it externally).
+   * @returns Current block index within the turn
    */
-  handleCwdChange(payload: AgentCwdChangeRequestPayload): Promise<AgentCwdChangeResponsePayload>;
+  protected getBlockIndex(): number;
   /**
-   * 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.
+   * Increment block index (for adapters using SDK-provided indices).
+   * Call after emitting step.finished if managing index externally.
    */
-  applyStagedMutations(): Promise<void>;
+  protected incrementBlockIndex(): void;
   /**
-   * Handle `agent.mcp.servers.set` request.
-   * @param payload - MCP server replacement request payload
-   * @returns MCP mutation response payload
+   * 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
    */
-  handleMcpServersSet(payload: AgentMcpServersSetRequestPayload): Promise<AgentMcpServersSetResponsePayload>;
+  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;
   /**
-   * Handle `agent.model.change` request.
+   * Replace the current connector with a fresh one.
    *
-   * Implements a four-branch decision tree based on the presence of `newModel`
-   * and `reasoningEffort` in the request payload:
+   * Serializes the complete create-before-close pattern with rollback for safety:
+   * 1. Create new connector first (old connector still alive)
+   * 2. Wire and initialize the replacement (accumulate cleanups separately)
+   * 3. Run the final guard and commit any selected managed account
+   * 4. Synchronously publish the ready replacement, then close the old runtime
+   * 5. On any pre-publication failure: close the replacement, restore old wiring, and roll back account selection
    *
-   * - 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
+   * 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)
+   * @param beforeCommit - Optional guard executed before replacing the active connector
+   * @throws Error if connector is currently processing a turn
    */
-  handleModelChange(payload: AgentModelChangeRequestPayload): Promise<AgentModelChangeResponsePayload>;
+  swapConnector(configOverrides?: AgentConnectorConfigOverrides, beforeCommit?: ConnectorSwapCommitGuard): Promise<void>;
   /**
-   * 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
+   * Build config factory input from agent config with optional overrides.
+   *
+   * Delegates to {@link buildConfigFactoryInput} with live connector-derived
+   * values (reasoning effort) and the agent's error sink.
+   * @param overrides - Optional field overrides (e.g., cwd, model, adapterSessionId)
+   * @returns ConfigFactoryInput ready for config factory
    */
-  private handleReasoningOnlyChange;
+  private buildConfigInput;
   /**
-   * Execute the model-swap path, settling the connector then resolving reasoning.
+   * Create the onMessageSent callback for connector factories.
    *
-   * **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
+   * Returns a callback that emits user_message.sent events to the global bus.
+   * @returns Callback function for connector config
+   */
+  private createOnMessageSent;
+  /**
+   * 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
    */
-  private handleModelSwap;
+  protected subscribeConnector<Subject extends ScopedSubjectDefinition<TConnector extends AIAgentConnector<infer TBus> ? TBus['namespace'] : never>>(connector: TConnector, subject: Subject, handler: HandlerForSubjectDefinition<Subject>, options?: OnOptions): void;
   /**
-   * Resolve the reasoning effort to apply after a model change.
+   * Clean up resources and emit session closed event.
    *
-   * 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.
+   * 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
+   */
+  private ensureConnector;
+  /**
+   * Determine whether to use native session resume (SDK manages history) or
+   * fresh-with-history (new session, injected messageHistory).
+   * @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 concrete agents.
+   * @returns true if native resume is supported
+   */
+  protected supportsNativeResume(): boolean;
+  /**
+   * Whether this adapter supports provider-native session fork.
+   * Override in concrete agents that can branch from an existing provider session.
+   * @returns true if native fork is supported
+   */
+  protected supportsNativeFork(): boolean;
+  /**
+   * Start the agent with an initial message.
    *
-   * 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
+   * Ensures the agent is initialized (idempotent), runs PreUserMessage hooks,
+   * and 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 idle (no message). Returns confirmed adapter session ID or `undefined`
+   * when the provider has not yet confirmed (idle fork sessions).
+   * @param options - Optional initialization options (system prompt, sessionContext)
+   * @returns Confirmed adapter session ID, or `undefined` for unconfirmed fork sessions.
    */
-  private confirmConnectorSwap;
+  initialize(options?: StartAgentOptions): Promise<string | undefined>;
+  protected onBeforeEmitCompletion(): Promise<void>;
+  protected onMessageHandle(messageHandle: MessageHandle, turnId?: string): Promise<void>;
   /**
-   * Compare provider contexts using the full public-bus shape.
+   * Abort the agent immediately (panic mode).
+   * Triggers AbortController which may cause provider errors.
+   * Use close() for graceful shutdown instead.
    *
-   * 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
+   * Emits session.closed event (once per session) then delegates
+   * to the underlying connector's abort method.
+   * @throws Error if connector is not initialized
    */
-  private hasProviderContextChanged;
+  abort(): void;
   /**
-   * 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
+   * 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
    */
-  private haveEqualStringRecords;
+  getAdapterSessionId(): Promise<string>;
   /**
-   * Handle a credential rotation request.
+   * Complete the agent session by waiting for all messages to finish.
    *
-   * 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
+   * 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
    */
-  handleCredentialChanged(payload: AgentCredentialChangeRequestPayload): Promise<AgentCredentialChangeResponsePayload>;
+  complete(): Promise<MessageResult | null>;
   /**
-   * Persist runtime field updates to agent storage.
-   * @param changes - CWD/model/provider mutations to persist
+   * 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
    */
-  private persistRuntimeMutation;
+  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/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/agent/request-correlation.d.ts
-/** Exact Factory Gateway headers accepted by its content-free usage boundary. */
-declare const FactoryUsageCorrelationHeaders: {
-  readonly sessionId: "x-factory-session-id";
-  readonly turnId: "x-factory-turn-id";
-  readonly messageId: "x-factory-message-id";
-  readonly llmCallId: "x-factory-llm-call-id";
-  readonly executionId: "x-factory-execution-id";
-  readonly frameId: "x-factory-frame-id";
-};
-type ProviderRequestCorrelation = RequestCorrelationContext & {
-  llmCallId: string;
-};
-/**
- * Bind caller correlation to identifiers owned by the active runtime request.
- * Runtime values always win, preventing stale or spoofed session/message IDs.
- * @param context - Optional orchestrator-supplied workflow correlation
- * @param runtime - IDs known by the connector for this concrete API request
- * @returns Fully bound correlation including one LLM-call ID
- */
-declare function bindProviderRequestCorrelation(context: RequestCorrelationContext | undefined, runtime: {
-  sessionId?: string;
-  messageId: string;
-  llmCallId: string;
-}): ProviderRequestCorrelation;
+//#region adapters/core/src/factory/adapter-context.d.ts
 /**
- * Project a validated correlation context to the Factory Gateway allowlist.
+ * Context provided to adapter implementations.
  *
- * No arbitrary metadata or headers can cross this boundary. Callers must also
- * explicitly opt into the `factory-v1` transport mode before using the result.
- * @param correlation - Content-free runtime and workflow identifiers
- * @returns Header record accepted by the Factory Gateway usage boundary
+ * Contains shared infrastructure and configuration that all adapters need:
+ * - Adapter name and capabilities from config
+ * - Local event bus for emitting events
  */
-declare function buildFactoryUsageCorrelationHeaders(correlation: ProviderRequestCorrelation): Record<string, string>;
+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/adapter/ai-adapter.d.ts
 /**
@@ -3219,6 +3198,8 @@ declare abstract class AIAdapter<TBus extends ScopedBus<string> = ScopedBus<stri
   protected platformDefaults?: PlatformDefaults;
   /** Provider definitions for model lookup. Injected by runtime. */
   protected readonly definitionProviders: readonly AdapterProviderDefinition[];
+  /** Trusted host-local normalized auth preparation strategy. */
+  protected readonly prepareAuthRuntime?: AdapterAuthRuntimePreparer<TBus>;
   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> & {
@@ -3230,7 +3211,6 @@ declare abstract class AIAdapter<TBus extends ScopedBus<string> = ScopedBus<stri
   }) => 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>);
@@ -3510,9 +3490,11 @@ interface CreateConformanceTestConfigOptions {
  * 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'> & {
+type CreateTestAgentOptions = Omit<BaseAgentConnectorConfig, 'bus' | 'agentId' | 'adapterName' | 'model' | 'cwd' | 'providerContext'> & {
+  agentId?: string;
   adapterName?: string;
-  model?: string; /** Override the default test provider context when testing endpoint/credential behavior. */
+  model?: string;
+  cwd?: 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>> {
@@ -3791,7 +3773,7 @@ interface ConformanceTestConfig<TBus extends ScopedBus<string> = ScopedBus<strin
    * 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
+   * provider definition's explicit auth method source hints. Used by orchestration tests that
    * call `startAgent` directly (bypassing the conformance `createConnector` path
    * where `resolveTestConfig` handles credential ref building).
    *
@@ -3809,6 +3791,40 @@ interface ConformanceTestConfig<TBus extends ScopedBus<string> = ScopedBus<strin
   cleanup?: () => Promise<void> | void;
 }
 //#endregion
+//#region adapters/core/src/testing/conformance-connector-runtime-registry.d.ts
+/**
+ * Own every connector runtime created by one conformance test configuration.
+ *
+ * The registry routes connector creation through the same normalized auth,
+ * binary, and client-config lease path as production. It replaces the public
+ * connector `close()` method with an idempotent managed close, so a test that
+ * closes its connector releases the lease immediately while `closeAll()` can
+ * still clean up abandoned connectors at suite teardown.
+ */
+declare class ConformanceConnectorRuntimeRegistry<TBus extends ScopedBus<string>, TConnector extends AIAgentConnector<TBus>> {
+  private readonly runtimes;
+  /**
+   * Create a connector through the production runtime preparation seam.
+   * @param options - Bound config and adapter connector factory
+   * @returns Managed connector with lease-aware idempotent `close()`
+   */
+  create<TConfig extends BaseAgentConnectorConfig<TBus>>(options: CreateConnectorRuntimeOptions<TBus, TConnector, TConfig>): Promise<TConnector>;
+  /**
+   * Close every connector still owned by this configuration.
+   * @throws The single close failure, or an AggregateError containing all failures
+   */
+  closeAll(): Promise<void>;
+}
+//#endregion
+//#region adapters/core/src/testing/provider-context.d.ts
+/**
+ * Build a resolved provider context that deliberately requires no authentication.
+ * @param providerConfigId - Provider config identity for the test
+ * @param definitionId - Provider definition identity for the test
+ * @returns Fresh normalized no-auth provider context
+ */
+declare function createNoAuthTestProviderContext(providerConfigId?: string, definitionId?: string): ProviderContext;
+//#endregion
 //#region adapters/core/src/session/utilities.d.ts
 /**
  * Manages session lifecycle and abort handling.
@@ -4516,4 +4532,4 @@ declare const ToolCompletedEventSchema: z.ZodObject<{
 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, FactoryUsageCorrelationHeaders, type FromGlobalToolApprovalFn, type GeneratedCapabilityProperties, type HarnessRequester, type IAdapterConfigFactory, type ISessionToolLedger, type ImportCursorPosition, ImportCursorPositionSchema, ImportCursorStorageNamespace, ImportCursorStorageSubjects, type ImportMetadata, type ImportSegment, type ImportSegmentLineage, type ImportSegmentTurn, 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 ProviderRequestCorrelation, type QueueableTurn, type ReasoningLevelMap, type ResolveConformanceTestPresetOptions, type ResolveHints, type ResolvedConformanceTestPreset, SESSION_CLOSED_QUEUE_ERROR, 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, bindProviderRequestCorrelation, buildFactoryUsageCorrelationHeaders, cleanEnvForAdapter, createAdapterNamespace, createTestProviderContext, createToolApprovalHandler, defineDiscriminatedHandlers, defineDiscriminatedHandlersSync, extractMcpCallTarget, formatContextBlockAsText, formatContextBlocksAsText, formatMessageHistoryAsTranscript, isMcpCallTool, isTextLikeMimeType, markCompletedWithFinalResult, mergeScopedToolApproval, normalizeEnvValue, normalizeMessageInput, normalizeMimeType, parseAIAdapterCapabilities, processDiscriminatedItems, processDiscriminatedItemsSync, processQueueMessages, registerAgentBusHandlers, registerMemoryImportCursorStorage, rejectQueuedHandles, resolveConformanceTestPreset, resolveDisabledNativeTools, resolvePresetCredentials, resolveRequiredSessionId, resolveTestConfig, safeJsonStringify, serializeBlockToText, serializeTurnContext, toImportSegment };
+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, ConformanceConnectorRuntimeRegistry, 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, FactoryUsageCorrelationHeaders, type FromGlobalToolApprovalFn, type GeneratedCapabilityProperties, type HarnessRequester, type IAdapterConfigFactory, type ISessionToolLedger, type ImportCursorPosition, ImportCursorPositionSchema, ImportCursorStorageNamespace, ImportCursorStorageSubjects, type ImportMetadata, type ImportSegment, type ImportSegmentLineage, type ImportSegmentTurn, 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 ProviderRequestCorrelation, type QueueableTurn, type ReasoningLevelMap, type ResolveConformanceTestPresetOptions, type ResolveHints, type ResolvedConformanceTestPreset, SESSION_CLOSED_QUEUE_ERROR, 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, bindProviderRequestCorrelation, buildFactoryUsageCorrelationHeaders, cleanEnvForAdapter, createAdapterNamespace, createNoAuthTestProviderContext, createTestProviderContext, createToolApprovalHandler, defineDiscriminatedHandlers, defineDiscriminatedHandlersSync, extractMcpCallTarget, formatContextBlockAsText, formatContextBlocksAsText, formatMessageHistoryAsTranscript, isMcpCallTool, isTextLikeMimeType, markCompletedWithFinalResult, mergeScopedToolApproval, normalizeEnvValue, normalizeMessageInput, normalizeMimeType, parseAIAdapterCapabilities, processDiscriminatedItems, processDiscriminatedItemsSync, processQueueMessages, registerAgentBusHandlers, registerMemoryImportCursorStorage, rejectQueuedHandles, resolveConformanceTestPreset, resolveDisabledNativeTools, resolveRequiredSessionId, resolveTestConfig, safeJsonStringify, serializeBlockToText, serializeTurnContext, toImportSegment };