@makaio/framework 1.0.0-dev-1783282710723 → 1.0.0-dev-1783439621927

package/dist/adapters/index.d.mts

@@ -1,10 +1,10 @@
-import { A as MessageHandle, B as ReasoningLevelMap, C as SendMessageRequestPayload, D as IAdapterConfigFactory, E as ConfigFactoryInput, F as MessageState, H as LedgerSessionContext, I as ProcessingState, L as SendMessageOptions, M as NormalizedMessageInput, N as normalizeMessageInput, O as AIAgentConnector, P as MessageResult, R as AIModel, S as NormalizedCallUsage, T as StartAgentOptions, U as SessionToolLedger, V as ISessionToolLedger, W as ToolLedgerEntry, _ as ConnectorSendMessageOptions, a as AgentCwdChangeRequestPayload, b as ExecutionContext, c as AgentInterruptRequestPayload, d as AgentMcpServersSetResponsePayload, f as AgentModelChangeRequestPayload, g as BaseAgentConnectorConfig, h as AgentStartResult, i as AgentCredentialChangeResponsePayload, j as markCompletedWithFinalResult, k as MessageDeliveryMode, l as AgentInterruptResponsePayload, m as AgentSendMessageOptions, n as AgentContext, o as AgentCwdChangeResponsePayload, p as AgentModelChangeResponsePayload, r as AgentCredentialChangeRequestPayload, s as AgentIdentity, t as AIAgentConfig, u as AgentMcpServersSetRequestPayload, v as ConnectorStartOptions, w as SendMessageResponsePayload, x as GetCapabilitiesResponsePayload, y as ContextWindowInput, z as AIReasoningLevel } from "../types-Cse8s_cD.mjs";
-import { _ as LogImporterConfig, a as CompactionMetadata, b as StorageMessagePayload, c as ExternalToolIdentifiers, d as ImportMetadata, f as ImportSegment, g as LogImporter, h as LogImportTestConfig, l as ExternalToolMeta, m as LogImportSessionContext, n as LogOrchestratorConfig, o as DiscoveryMetadata, p as ImportSegmentLineage, r as ParseFileResult, s as ExternalToolIdentifier, u as ImportCursorPosition, v as NormalizedEvent, x as toImportSegment, y as ProcessLogFileResult } from "../base-orchestrator-Cw0vpNgB.mjs";
+import { A as MessageHandle, B as ReasoningLevelMap, C as SendMessageRequestPayload, D as IAdapterConfigFactory, E as ConfigFactoryInput, F as MessageState, H as LedgerSessionContext, I as ProcessingState, L as SendMessageOptions, M as NormalizedMessageInput, N as normalizeMessageInput, O as AIAgentConnector, P as MessageResult, R as AIModel, S as NormalizedCallUsage, T as StartAgentOptions, U as SessionToolLedger, V as ISessionToolLedger, W as ToolLedgerEntry, _ as ConnectorSendMessageOptions, a as AgentCwdChangeRequestPayload, b as ExecutionContext, c as AgentInterruptRequestPayload, d as AgentMcpServersSetResponsePayload, f as AgentModelChangeRequestPayload, g as BaseAgentConnectorConfig, h as AgentStartResult, i as AgentCredentialChangeResponsePayload, j as markCompletedWithFinalResult, k as MessageDeliveryMode, l as AgentInterruptResponsePayload, m as AgentSendMessageOptions, n as AgentContext, o as AgentCwdChangeResponsePayload, p as AgentModelChangeResponsePayload, r as AgentCredentialChangeRequestPayload, s as AgentIdentity, t as AIAgentConfig, u as AgentMcpServersSetRequestPayload, v as ConnectorStartOptions, w as SendMessageResponsePayload, x as GetCapabilitiesResponsePayload, y as ContextWindowInput, z as AIReasoningLevel } from "../types-N_BOtTqt.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-ODRyDBzu.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, ProviderContext, ProviderDefinitionInput, ReasoningLevelMap as ReasoningLevelMap$1, ResponseSchemaDescriptor, SendMessageRequest, SendMessageResponse, SessionContext, SessionMessageBlock, StartAgentRequest, StartAgentResponse, StepType, SystemPrompt, ToolListItem } from "@makaio/framework/contracts";
+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, 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";
@@ -69,6 +69,15 @@ interface LogImportRegistration {
   LogDiscoveryOrchestratorClass?: LogOrchestratorConstructor;
   /** Glob pattern for log files. */
   logFilePattern: string;
+  /**
+   * Stable client application id (e.g., `'claude-code'`) whose native hooks
+   * observe the sessions this importer ingests.
+   *
+   * Enables client-agnostic framework components to resolve the importer for
+   * a `client.session.*` event without hard-coding importer names. Any string
+   * is valid — framework logic never hard-codes specific client ids.
+   */
+  clientId?: string;
 }
 //#endregion
 //#region adapters/core/src/types/provider-definition.d.ts
@@ -257,6 +266,7 @@ interface AIAdapterCapabilityRegistry {
   session: {
     resume: boolean;
     fork: boolean;
+    forkAtMessage: boolean;
   };
   chat: {
     inTurnMessages: boolean;
@@ -1404,7 +1414,7 @@ declare const ScopedToolApprovalSchema: {
     agentId: z.ZodString;
     adapterId: z.ZodString;
     adapterName: z.ZodString;
-    adapterSessionId: z.ZodString;
+    adapterSessionId: z.ZodOptional<z.ZodString>;
     messageId: z.ZodOptional<z.ZodString>;
     turnId: z.ZodOptional<z.ZodString>;
     clientId: z.ZodOptional<z.ZodString>;
@@ -1541,7 +1551,9 @@ type ConnectorEventHandlers<TMessage, TDiscriminator extends string> = { [K in D
  * Emit function type for global bus emissions.
  * Matches the signature of AIAgent.emitGlobal.
  */
-type EmitGlobalFn = <S extends SubjectDefinition>(subject: S, payload: Omit<ExtractSubjectPayload<S>, keyof AgentContext>) => Promise<void>;
+type EmitGlobalFn = <S extends SubjectDefinition>(subject: S, payload: Omit<ExtractSubjectPayload<S>, keyof AgentContext> & {
+  turnId?: string;
+}) => Promise<void>;
 /**
  * Configuration for MessageLifecycleTracker.
  */
@@ -1549,6 +1561,11 @@ interface MessageLifecycleTrackerConfig {
   /** Function to emit events to global bus with auto-enrichment */
   emitGlobal: EmitGlobalFn;
 }
+/** Options for tracking a connector message handle. */
+interface MessageLifecycleTrackOptions {
+  /** Turn ID captured before connector dispatch, if the request belongs to a session turn. */
+  turnId: string | undefined;
+}
 /**
  * Tracks message lifecycle and emits corresponding events.
  *
@@ -1597,8 +1614,9 @@ declare class MessageLifecycleTracker {
    * - user_message.acknowledged
    * - agent.turn.started
    * @param handle - The message handle being acknowledged
+   * @param turnId - Turn ID captured when the handle was registered
    */
-  acknowledge(handle: MessageHandle): void;
+  acknowledge(handle: MessageHandle, turnId?: string): void;
   /**
    * Complete a message - marks turn end.
    *
@@ -1607,8 +1625,9 @@ declare class MessageLifecycleTracker {
    * - user_message.completed (always, with outcome)
    * @param handle - The message handle being completed
    * @param result - The completion result with outcome
+   * @param turnId - Turn ID captured when the handle was registered
    */
-  complete(handle: MessageHandle, result: MessageResult): void;
+  complete(handle: MessageHandle, result: MessageResult, turnId?: string): void;
   /**
    * Wire up a message handle for lifecycle tracking.
    *
@@ -1619,8 +1638,9 @@ declare class MessageLifecycleTracker {
    * @param handle - The message handle to track
    * @param onTerminal - Optional callback for any terminal outcome (emits agent.complete)
    * @param transformTerminal - Optional async transform applied before public completion resolves
+   * @param options - Optional tracking metadata captured before connector dispatch
    */
-  track(handle: MessageHandle, onTerminal?: (messageId: string, result: MessageResult) => void, transformTerminal?: (result: MessageResult) => Promise<MessageResult>): void;
+  track(handle: MessageHandle, onTerminal?: (messageId: string, result: MessageResult, turnId: string | undefined) => void, transformTerminal?: (result: MessageResult) => Promise<MessageResult>, options?: MessageLifecycleTrackOptions): void;
 }
 //#endregion
 //#region adapters/core/src/agent/tool-call-tracker.d.ts
@@ -1730,6 +1750,15 @@ declare abstract class AIAgent<TBus extends ScopedBus<string> = ScopedBus<string
   private latestMessageCompletion?;
   /** Current content block index within the turn, reset on each turn start */
   private currentBlockIndex;
+  /**
+   * 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.
+   */
+  private pendingStartMode;
   /** Normalized config with defaults applied */
   protected readonly config: SetRequired<AIAgentConfig<TBus, TConnector>, 'globalBus'>;
   /** Available models for context window lookup */
@@ -1772,7 +1801,23 @@ declare abstract class AIAgent<TBus extends ScopedBus<string> = ScopedBus<string
    * @throws Error if already initialized
    */
   init(): Promise<void>;
-  protected emitStart(event?: Omit<AgentStarted, 'agentId' | 'adapterId' | 'adapterName' | 'adapterSessionId' | 'model' | 'cwd'>): Promise<void>;
+  /**
+   * Emit `agent.started` with the pending start mode (consume-on-read).
+   *
+   * 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.
+   *
+   * 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.
@@ -1796,7 +1841,7 @@ declare abstract class AIAgent<TBus extends ScopedBus<string> = ScopedBus<string
    * @param payload - The base payload to enrich
    * @returns Payload with AgentContext fields and optional messageId added
    */
-  protected enrichPayload<T extends object>(payload: T): Promise<T & AgentContext & {
+  protected enrichPayload<T extends object>(payload: T): Promise<T & AgentIdentity & {
     messageId?: string;
   }>;
   /**
@@ -2003,46 +2048,46 @@ declare abstract class AIAgent<TBus extends ScopedBus<string> = ScopedBus<string
   /**
    * Ensure the connector is initialized, throwing if not.
    * @returns The initialized connector instance
-   * @throws Error if connector is not initialized
    */
   private ensureConnector;
   /**
-   * Determine whether to use native session resume or fresh with history.
-   *
-   * Native resume: SDK manages history, don't inject messageHistory, preserve cache.
-   * Fresh with history: Create new session, inject messageHistory.
-   *
-   * Override in adapter-specific agents if needed.
+   * 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 adapter-specific agents that can resume SDK sessions.
+   * 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.
    *
-   * Ensures the agent is initialized (idempotent) before delegating to the connector.
-   * Runs PreUserMessage hooks before sending the message.
-   * Uses sessionContext signals to decide between native resume and fresh with history.
-   * HookAbortError propagates to caller.
+   * 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 the agent without sending a message (idle creation).
-   * Ensures init() is called, then delegates to connector.initialize().
+   * 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.
    */
-  initialize(options?: StartAgentOptions): Promise<void>;
+  initialize(options?: StartAgentOptions): Promise<string | undefined>;
   protected onBeforeEmitCompletion(): Promise<void>;
-  protected onMessageHandle(messageHandle: MessageHandle): Promise<void>;
+  protected onMessageHandle(messageHandle: MessageHandle, turnId?: string): Promise<void>;
   /**
    * Abort the agent immediately (panic mode).
    * Triggers AbortController which may cause provider errors.
@@ -2262,6 +2307,7 @@ declare class AgentEventBridge {
 /**
  * Runtime dependencies for AgentTurnExecutor.
  */
+type AgentMessageHandleCallback = (messageHandle: MessageHandle, turnId: string | undefined) => Promise<void>;
 interface AgentTurnExecutorConfig {
   /** Stable agent identifier. */
   agentId: string;
@@ -2277,8 +2323,26 @@ interface AgentTurnExecutorConfig {
   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: (messageHandle: MessageHandle) => Promise<void>;
+  onMessageHandle: AgentMessageHandleCallback;
   /** Side-effect callback to mark agent status active before dispatch. */
   onBeforeDispatch?: () => void | Promise<void>;
   /** When true, PreUserMessage hooks are skipped. */
@@ -2299,10 +2363,51 @@ declare class AgentTurnExecutor {
   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
@@ -2349,6 +2454,43 @@ type AgentCreationOptions = Omit<Partial<Pick<StartAgentRequestPayload, 'model'
   adapterSessionId?: string;
   resumeAdapterSessionId?: string; /** Unresolved provider context (credential refs, not plaintext). */
   providerContext?: ProviderContext;
+  /**
+   * Source Makaio session ID when mode is 'fork'.
+   * Forwarded verbatim from the fork-mode startAgent request.
+   */
+  sourceSessionId?: string;
+  /**
+   * Provider-native source session ID when mode is 'fork'.
+   * Forwarded verbatim from the fork-mode startAgent request.
+   */
+  sourceAdapterSessionId?: string;
+  /**
+   * Optional provider-native checkpoint message ID for the fork point.
+   * Forwarded verbatim from the fork-mode startAgent request.
+   */
+  forkPointMessageId?: string;
+  /**
+   * Optional working directory override for the forked session.
+   * Forwarded verbatim from the fork-mode startAgent request.
+   */
+  targetWorkingDirectory?: string;
+  /**
+   * Orchestrator-assembled session context carrying fork directives,
+   * native-locality decisions, and other session-scoped metadata.
+   *
+   * Present when the session orchestrator attaches context to a startAgent
+   * request (e.g. fork-mode locality evaluation).
+   */
+  sessionContext?: SessionContext;
+  /**
+   * Provider-native fork directive assembled from the startAgent fork-mode fields.
+   *
+   * Present when the adapter is started in fork mode and a native fork is feasible.
+   * When `mode` is 'fork', `buildNativeForkDirective()` constructs this from the
+   * individual fork fields above. When pre-built (e.g. from rehydration), it is
+   * passed through directly.
+   */
+  nativeFork?: NativeForkDirective;
 };
 /**
  * Cumulative usage totals tracked per agent.
@@ -2605,8 +2747,6 @@ interface AgentPayloadEmitterConfig {
   getLastKnownAdapterSessionId: () => string | undefined;
   /** Persist latest adapterSessionId after resolution. */
   setLastKnownAdapterSessionId: (adapterSessionId: string | undefined) => void;
-  /** Async fallback to wait for adapter session ID. */
-  getAdapterSessionId: () => Promise<string>;
   /** Live event metadata defaults resolved from current runtime state. */
   getEventMetadataDefaults: () => AgentPayloadEventMetadata;
 }
@@ -2620,6 +2760,33 @@ declare class AgentPayloadEmitter {
    * @param config - Config controlling agent-context enrichment and global emissions
    */
   constructor(config: AgentPayloadEmitterConfig);
+  /**
+   * Resolve the confirmed adapter session ID from synchronous sources.
+   *
+   * `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.
+   *
+   * 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.
+   *
+   * 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`
+   */
+  private resolveConfirmedAdapterSessionId;
+  /**
+   * 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 resolveEventMetadata;
   /**
    * Enrich payload with agent context fields.
    * @param payload - Base payload to enrich
@@ -2627,7 +2794,7 @@ declare class AgentPayloadEmitter {
    * @param options - Enrichment controls for optional analytics metadata defaults
    * @returns Enriched payload with agent context
    */
-  enrichPayload<T extends object>(payload: T, overrideMessageId?: string, options?: EmitGlobalOptions): Promise<T & AgentContext & AgentPayloadEventFields>;
+  enrichPayload<T extends object>(payload: T, overrideMessageId?: string, options?: EmitGlobalOptions): Promise<T & AgentIdentity & AgentPayloadEventFields>;
   /**
    * Emit enriched payload to global bus.
    * @param subject - Subject definition to emit
@@ -2636,6 +2803,7 @@ declare class AgentPayloadEmitter {
    */
   emitGlobal<S extends SubjectDefinition>(subject: S, payload: Omit<ExtractSubjectPayload<S>, keyof AgentContext> & {
     messageId?: string;
+    turnId?: string;
   }, options?: EmitGlobalOptions): Promise<void>;
 }
 //#endregion
@@ -2962,18 +3130,16 @@ declare abstract class AIAdapter<TBus extends ScopedBus<string> = ScopedBus<stri
    */
   private handleSessionClosedByService;
   /**
-   * Handle agent.usage - aggregate and emit session totals.
-   * @param ctx - Event context with usage payload
+   * Reconcile registry adapterSessionId on first confirmed agent.started (idle fork starts).
+   * @param ctx - Event context with started payload
    */
-  private handleUsage;
+  private handleStartedReconcileRegistry;
   /**
-   * Initialize adapter - call after construction.
-   * Creates scoped bus, sets up handlers, and emits adapter.initialized event.
-   * Safe to call multiple times - subsequent calls are no-ops.
-   *
-   * Note: Agents are NOT eagerly rehydrated on startup. They are rehydrated
-   * on-demand when messages arrive (lazy rehydration via handleRehydrateAgent).
+   * Handle agent.usage — aggregate and emit session totals.
+   * @param ctx - Event context with usage payload
    */
+  private handleUsage;
+  /** Initialize adapter (idempotent). Creates scoped bus, sets up handlers, emits adapter.initialized. */
   init(): Promise<void>;
   /** Hook for subclass initialization. Override to perform async setup (connections, auth, etc.). */
   protected onInit(): Promise<void>;
@@ -3342,6 +3508,28 @@ interface ConformanceTestConfig<TBus extends ScopedBus<string> = ScopedBus<strin
      * **Free-Tier Adapters**: `false` (no usage tracking)
      */
     supportsUsageMetrics?: boolean;
+    /**
+     * Supports provider-native session resume.
+     *
+     * When enabled, the adapter can resume a prior provider session by its
+     * `adapterSessionId` without injecting the full message history. The SDK
+     * manages conversation state natively.
+     *
+     * **Claude Code**: `true` (resumes via Claude Agent SDK session IDs)
+     * **Stateless Adapters**: `false` (always replay history)
+     */
+    nativeResume?: boolean;
+    /**
+     * Supports provider-native session fork.
+     *
+     * When enabled, the adapter can branch from an existing provider session
+     * at an optional message checkpoint, creating a diverging conversation
+     * without replaying history into a fresh session.
+     *
+     * **Claude Code**: `true` (forks via Claude Agent SDK branching API)
+     * **Stateless Adapters**: `false` (always replay history for fork)
+     */
+    nativeFork?: boolean;
   };
   /**
    * Test configuration and environment options.
@@ -4211,4 +4399,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, type FromGlobalToolApprovalFn, type GeneratedCapabilityProperties, type HarnessRequester, type IAdapterConfigFactory, type ISessionToolLedger, type ImportCursorPosition, ImportCursorPositionSchema, ImportCursorStorageNamespace, ImportCursorStorageSubjects, type ImportMetadata, type ImportSegment, type ImportSegmentLineage, type LedgerSessionContext, type LogImportConfig, type LogImportOrchestrator, type LogImportRegistration, type LogImportSessionContext, type LogImportTestConfig, type LogImporter, type LogImporterConfig, type LogImporterConstructor, type LogOrchestratorConfig, type LogOrchestratorConstructor, MAKAIO_CONFORMANCE_PRIMARY_MODEL_ENV, MAKAIO_CONFORMANCE_PROVIDER_DEFINITIONS_ENV, MAKAIO_CONFORMANCE_PROVIDER_ENV, MAKAIO_CONFORMANCE_SECONDARY_MODEL_ENV, type McpIntegrationStrategy, type McpSessionResources, type McpToolChange, type MergeResult, type MergeScopedToolApprovalOptions, type MessageDeliveryMode, MessageHandle, MessageLifecycleTracker, type MessageResult, type MessageState, type NormalizedCallUsage, type NormalizedEvent, type NormalizedMessageInput, type ParseFileResult, type PauseResult, type PlatformDefaults, ProceduralAgentConnector, type ProceduralConnectorSession, ProceduralConnectorTurn, type ProceduralTurnConfig, type ProceduralTurnState, type ProcessLogFileResult, type ProcessQueueCallbacks, type ProcessingState, type QueueableTurn, type ReasoningLevelMap, type ResolveConformanceTestPresetOptions, type ResolveHints, type ResolvedConformanceTestPreset, type ScopedBusFor, type ScopedToolApprovalRequest, type ScopedToolApprovalResponse, ScopedToolApprovalSchema, type SendMessageOptions, type SendMessageRequest, type SendMessageResponse, type SerializedContextBlock, SessionLifecycle, SessionToolLedger, type ShouldUseNativeResumeFn, type StartAgentOptions, type StartAgentRequest, type StartAgentResponse, type StorageMessagePayload, type SyncDiscriminatedHandler, type SyncDiscriminatedHandlersConfig, type SyncDiscriminatedHandlersMap, type SyncTypedEmitFn, type TestModelRef, type ToGlobalToolApprovalFn, type ToolApprovalContext, ToolCallTracker, type ToolCompletedEvent, ToolCompletedEventSchema, type ToolLedgerEntry, type ToolStartedEvent, ToolStartedEventSchema, type TurnEvent, type TurnState, type TurnSubjects, TurnTracker, type TurnTrackerOptions, type TurnTrackerSerializedState, TurnTrackerSerializedStateSchema, type TypedEmitFn, UserMessageQueue, type ValidCapability, type WireSessionConfig, type WireSessionSubjects, cleanEnvForAdapter, createAdapterNamespace, createTestProviderContext, createToolApprovalHandler, defineDiscriminatedHandlers, defineDiscriminatedHandlersSync, extractMcpCallTarget, formatContextBlockAsText, formatContextBlocksAsText, formatMessageHistoryAsTranscript, isMcpCallTool, isTextLikeMimeType, markCompletedWithFinalResult, mergeScopedToolApproval, normalizeEnvValue, normalizeMessageInput, normalizeMimeType, parseAIAdapterCapabilities, processDiscriminatedItems, processDiscriminatedItemsSync, processQueueMessages, registerAgentBusHandlers, registerMemoryImportCursorStorage, resolveConformanceTestPreset, resolveDisabledNativeTools, resolvePresetCredentials, resolveRequiredSessionId, resolveTestConfig, safeJsonStringify, serializeBlockToText, serializeTurnContext, toImportSegment };
+export { AIAdapter, type AIAdapterCapabilities, type AIAdapterCapability, type AIAdapterCapabilityRegistry, type AIAdapterConfig, type AIAdapterConstructorConfig, type AIAdapterContext, type AIAdapterDefinition, type AIAdapterInitOptions, type AIAdapterPromptFailureResult, type AIAdapterPromptOptions, type AIAdapterPromptResult, type AIAdapterPromptSuccessResult, AIAgent, type AIAgentConfig, AIAgentConnector, type AIModel, type AIReasoningLevel, type AdapterNamespace, type AdapterProviderDefinition, type AgentBusHandlerRegistrarConfig, type AgentCompleteEvent, AgentCompleteEventSchema, AgentConnectorLifecycleManager, type AgentConnectorLifecycleManagerConfig, type AgentContext, AgentEventBridge, type AgentEventBridgeConfig, type AgentIdentity, AgentLifecycleEmitter, type AgentLifecycleEmitterConfig, AgentPayloadEmitter, type AgentPayloadEmitterConfig, type AgentRuntimeCreationResult, AgentRuntimeMutationManager, type AgentRuntimeMutationManagerConfig, type AgentSendMessageOptions, type AgentStartResult, type AgentStartedEvent, AgentStartedEventSchema, AgentTurnExecutor, type AgentTurnExecutorConfig, type AgentUsageTotals, type BaseAgentConnectorConfig, BaseConnectorSession, BaseConnectorTurn, BaseLogImporter, type CompactionMetadata, type ConfigFactoryInput, type ConformanceEnvReader, type ConformanceTestConfig, type ConnectorSendMessageOptions, type ConnectorSessionConfig, type ConnectorStartOptions, type CreateConformanceTestConfigOptions, type CreateTestAgentOptions, type DiscoveryMetadata, type DiscriminatedHandler, type DiscriminatedHandlersConfig, type DiscriminatedHandlersMap, type ErrorEvent, ErrorEventSchema, type ExecutionContext, type ExternalToolIdentifier, type ExternalToolIdentifiers, type ExternalToolMeta, type FromGlobalToolApprovalFn, type GeneratedCapabilityProperties, type HarnessRequester, type IAdapterConfigFactory, type ISessionToolLedger, type ImportCursorPosition, ImportCursorPositionSchema, ImportCursorStorageNamespace, ImportCursorStorageSubjects, type ImportMetadata, type ImportSegment, type ImportSegmentLineage, type 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 QueueableTurn, type ReasoningLevelMap, type ResolveConformanceTestPresetOptions, type ResolveHints, type ResolvedConformanceTestPreset, type ScopedBusFor, type ScopedToolApprovalRequest, type ScopedToolApprovalResponse, ScopedToolApprovalSchema, type SendMessageOptions, type SendMessageRequest, type SendMessageResponse, type SerializedContextBlock, SessionLifecycle, SessionToolLedger, type ShouldUseNativeResumeFn, type StartAgentOptions, type StartAgentRequest, type StartAgentResponse, type StorageMessagePayload, type SyncDiscriminatedHandler, type SyncDiscriminatedHandlersConfig, type SyncDiscriminatedHandlersMap, type SyncTypedEmitFn, type TestModelRef, type ToGlobalToolApprovalFn, type ToolApprovalContext, ToolCallTracker, type ToolCompletedEvent, ToolCompletedEventSchema, type ToolLedgerEntry, type ToolStartedEvent, ToolStartedEventSchema, type TurnEvent, type TurnState, type TurnSubjects, TurnTracker, type TurnTrackerOptions, type TurnTrackerSerializedState, TurnTrackerSerializedStateSchema, type TypedEmitFn, UserMessageQueue, type ValidCapability, type WireSessionConfig, type WireSessionSubjects, cleanEnvForAdapter, createAdapterNamespace, createTestProviderContext, createToolApprovalHandler, defineDiscriminatedHandlers, defineDiscriminatedHandlersSync, extractMcpCallTarget, formatContextBlockAsText, formatContextBlocksAsText, formatMessageHistoryAsTranscript, isMcpCallTool, isTextLikeMimeType, markCompletedWithFinalResult, mergeScopedToolApproval, normalizeEnvValue, normalizeMessageInput, normalizeMimeType, parseAIAdapterCapabilities, processDiscriminatedItems, processDiscriminatedItemsSync, processQueueMessages, registerAgentBusHandlers, registerMemoryImportCursorStorage, resolveConformanceTestPreset, resolveDisabledNativeTools, resolvePresetCredentials, resolveRequiredSessionId, resolveTestConfig, safeJsonStringify, serializeBlockToText, serializeTurnContext, toImportSegment };