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

package/dist/adapters/stream-session/index.d.mts

@@ -0,0 +1,1414 @@
+import { z } from "zod";
+import { EventMessagePayload, ScopedSubjectDefinition } from "@makaio/framework/core";
+import { ScopedBus } from "@makaio/framework/bus";
+import { AgentToolApproveRequest, AgentToolApproveResponse, McpSessionContext, SessionMessageBlock, ToolExecuteResult, ToolExecutionContextOverrides, ToolListItem } from "@makaio/framework/contracts";
+import { AIAgent, AIAgentConnector, AIReasoningLevel as AIReasoningLevel$1, AgentCompleteEvent, AgentCompleteEventSchema, AgentStartedEvent, AgentStartedEvent as AgentStartedEvent$1, AgentStartedEventSchema, BaseAgentConnectorConfig, BaseConnectorSession, ConnectorSendMessageOptions, ErrorEvent, ErrorEvent as ErrorEvent$1, ErrorEventSchema, LedgerSessionContext, MessageHandle, MessageResult, NormalizedCallUsage, NormalizedMessageInput, ProceduralAgentConnector, ProceduralConnectorSession, ProceduralConnectorTurn, ToolApprovalContext, ToolCompletedEvent, ToolCompletedEvent as ToolCompletedEvent$1, ToolCompletedEventSchema, ToolStartedEvent, ToolStartedEvent as ToolStartedEvent$1, ToolStartedEventSchema, UserMessageQueue, WireSessionConfig, WireSessionSubjects } from "@makaio/framework/adapters";
+
+//#region adapters/shared/stream-session/src/tool-handling/tool-result.d.ts
+/**
+ * Shared tool result types and content bounding utility.
+ *
+ * These types and functions are identical across all stream-based adapter
+ * implementations and are extracted here to avoid duplication.
+ */
+/**
+ * Tool-specific fields extracted from a normalized tool call.
+ *
+ * Identity context (agentId, adapterId, etc.) is intentionally excluded —
+ * the connector injects those when forwarding to the global bus.
+ */
+interface ToolCallPayload {
+  /** Name of the tool to call */
+  toolName: string;
+  /** Parsed arguments for the tool */
+  args: Record<string, unknown>;
+  /** Unique identifier for this tool call */
+  toolCallId: string;
+}
+declare const MAX_TOOL_RESULT_CONTENT_CHARS = 8000;
+/**
+ * Bound tool result content before injecting it back into model context.
+ *
+ * Tool outputs (filesystem, grep, etc.) can be very large and cause
+ * context-window overflows in recursive tool-call turns. Keep full payload
+ * on emitted events, but cap what is sent back to the model.
+ * @param content - Serialized tool result payload
+ * @returns Content truncated to context-safe size
+ */
+declare function boundToolResultContent(content: string): string;
+//#endregion
+//#region adapters/shared/stream-session/src/namespaces/schemas/tool-calls.d.ts
+/**
+ * Public contract for a single tool-call function payload.
+ *
+ * Matches both the Anthropic ToolUseBlock.input structure and the
+ * OpenAI ChatCompletionMessageToolCall.Function structure.
+ */
+interface ToolCallFunction {
+  /** Name of the function to call. */
+  name: string;
+  /** JSON-encoded arguments for the function. */
+  arguments: string;
+}
+/**
+ * Public contract for a single tool call.
+ *
+ * Contains only the fields common to both Anthropic and OpenAI adapters.
+ * The Anthropic adapter extends this with `blockIndex`.
+ */
+interface ToolCall {
+  /** Unique identifier for this tool call. */
+  id: string;
+  /** Type of tool (always 'function' for now). */
+  type: 'function';
+  /** Function call details. */
+  function: ToolCallFunction;
+}
+/**
+ * Public contract for a tool-calls event.
+ *
+ * Emitted when the model requests tool / function execution.
+ */
+interface ToolCallsEvent {
+  /** Discriminator for tool call events. */
+  eventType: 'tool_calls';
+  /** Array of requested tool calls. */
+  toolCalls: ToolCall[];
+}
+/**
+ * Schema for a single tool call function.
+ *
+ * Matches both the Anthropic ToolUseBlock.input structure and the
+ * OpenAI ChatCompletionMessageToolCall.Function structure.
+ */
+declare const ToolCallFunctionSchema: z.ZodObject<{
+  name: z.ZodString;
+  arguments: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Schema for a single tool call.
+ *
+ * Contains only the fields common to both Anthropic and OpenAI adapters.
+ * The Anthropic adapter extends this with `blockIndex` via `.extend()`.
+ *
+ * Adapter-specific schemas may extend this via `.extend()`.
+ */
+declare const ToolCallSchema: z.ZodObject<{
+  id: z.ZodString;
+  type: z.ZodLiteral<"function">;
+  function: z.ZodObject<{
+    name: z.ZodString;
+    arguments: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Schema for a tool calls event.
+ *
+ * Emitted when the model requests tool / function execution.
+ * Both adapters emit this event with the same structure, except the
+ * Anthropic adapter's individual `ToolCall` entries also carry `blockIndex`.
+ */
+declare const ToolCallsEventSchema: z.ZodObject<{
+  eventType: z.ZodLiteral<"tool_calls">;
+  toolCalls: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"function">;
+    function: z.ZodObject<{
+      name: z.ZodString;
+      arguments: z.ZodString;
+    }, z.core.$strip>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+//#endregion
+//#region adapters/shared/stream-session/src/tool-handling/tool-approval.d.ts
+/**
+ * Extract tool-specific fields from a normalized tool call.
+ *
+ * The `function.arguments` field is a JSON string assembled from streaming
+ * delta fragments. This function parses it to recover the structured args.
+ * @param toolCall - Normalized tool call from the stream-bridge tool_calls event
+ * @param adapterLabel - Short label used in error logs (e.g. 'AnthropicSdkAgent'). Defaults to 'Adapter'.
+ * @returns Tool-specific payload without identity context
+ */
+declare function extractToolCallPayload(toolCall: ToolCall, adapterLabel?: string): ToolCallPayload;
+/**
+ * Transform a normalized tool call into an AgentToolApproveRequest.
+ *
+ * Combines the extracted tool payload with full adapter identity context.
+ * @param toolCall - Normalized tool call from the stream-bridge tool_calls event
+ * @param context - Adapter context providing identity fields
+ * @param adapterLabel - Short label used in error logs (e.g. 'AnthropicSdkAgent'). Defaults to 'Adapter'.
+ * @returns Global tool approval request ready for AgentSubjects.toolApprove
+ */
+declare function toGlobalToolApproval(toolCall: ToolCall, context: ToolApprovalContext, adapterLabel?: string): AgentToolApproveRequest;
+/**
+ * Apply approved argument overrides directly to the tool call payload.
+ *
+ * Approval handlers can transform tool input via `updatedInput`. When present,
+ * the modified args must replace the original JSON string before execution.
+ * @param toolCall - Tool call object to update in place
+ * @param approval - Allow-branch approval response from AgentSubjects.toolApprove
+ */
+declare function applyApprovedArgs(toolCall: ToolCall, approval: Extract<AgentToolApproveResponse, {
+  action: 'allow';
+}>): void;
+//#endregion
+//#region adapters/shared/stream-session/src/tool-handling/tool-registry.d.ts
+/**
+ * Load tools from ToolRegistry via MakaioBus.
+ *
+ * Fetches available tools from the central ToolRegistry.
+ * Returns raw ToolListItem[] for maximum flexibility so each adapter can
+ * convert to its own SDK-specific format.
+ *
+ * Does not throw on failure — an agent can still operate without tools,
+ * so errors are logged and an empty array is returned.
+ * @param adapterId - Adapter instance ID for logging/routing
+ * @param adapterName - Adapter type name
+ * @returns List of available tools, or empty array if fetch fails
+ */
+declare function loadToolsFromRegistry(adapterId: string, adapterName: string): Promise<ToolListItem[]>;
+/**
+ * Filter tools to only those with an inputSchema defined.
+ *
+ * Most LLM SDKs require a JSON Schema for function calling parameters.
+ * Tools without inputSchema cannot be used with native function calling.
+ * @param tools - Tools from the registry
+ * @returns Tools that have a defined inputSchema
+ */
+declare function filterToolsWithSchema(tools: ToolListItem[]): (ToolListItem & {
+  inputSchema: Record<string, unknown>;
+})[];
+//#endregion
+//#region adapters/shared/stream-session/src/tool-handling/tool-execution.d.ts
+/**
+ * Minimal SDK event emitter interface for tool lifecycle events.
+ *
+ * Both adapter SdkEventMessage discriminated unions include ToolStartedEvent
+ * and ToolCompletedEvent. Using a structural union here avoids the shared
+ * package depending on adapter-specific namespaces.
+ */
+type ToolLifecycleEmitter = (event: ToolStartedEvent$1 | ToolCompletedEvent$1) => Promise<void>;
+/**
+ * Execute a tool via Bus RPC.
+ *
+ * Routes tool execution through the ToolRegistry via MakaioBus.
+ * Emits tool_started before execution and tool_completed after (on both
+ * success and failure paths). On bus error the error is re-thrown after
+ * the tool_completed failure event is emitted.
+ * @param toolCall - The normalized tool call to execute
+ * @param emitSdkEvent - Callback to emit SDK lifecycle events
+ * @param contextOverrides - Execution context (cwd, env, sessionId, agentId, turnId)
+ * @returns Tool execution result
+ */
+declare function executeTool(toolCall: ToolCall, emitSdkEvent: ToolLifecycleEmitter, contextOverrides: ToolExecutionContextOverrides): Promise<ToolExecuteResult>;
+//#endregion
+//#region adapters/shared/stream-session/src/tool-handling/handle-tool-calls.d.ts
+/**
+ * Callbacks needed by {@link handleToolCalls}. Adapter-agnostic.
+ */
+type HandleToolCallsCallbacks = {
+  /** Emit SDK lifecycle events (tool_started, tool_completed). */emitSdkEvent: ToolLifecycleEmitter;
+  /**
+   * Request tool approval via the scoped bus routed to the global bus.
+   * @param payload - Tool call payload enriched with optional reasoning
+   * @returns Global approval response
+   */
+  requestToolApproval: (payload: ToolCallPayload & {
+    reasoning?: string;
+  }) => Promise<AgentToolApproveResponse>;
+  /**
+   * Record an mcp_call invocation in the session tool ledger.
+   *
+   * Optional. When present, called after each successful mcp_call execution
+   * with the resolved target tool name. The connector binds this callback to
+   * its ledger and captures the current turn number in the closure, so it
+   * always reflects the turn in progress when the call is recorded.
+   * @param toolFullName - Namespaced target tool name extracted from mcp_call args
+   */
+  recordMcpCall?: (toolFullName: string) => void;
+};
+/**
+ * Adapter-specific result formatter for tool call outcomes.
+ * @param toolCallId - The tool call ID for correlation
+ * @param content - Serialized result content (already bounded)
+ * @param isError - Whether the result represents an error
+ * @returns SDK-specific result value
+ */
+type ToolResultBuilder<TResult> = (toolCallId: string, content: string, isError: boolean) => TResult;
+/**
+ * Process tool calls from a model response: approve, execute, and format results.
+ *
+ * Shared orchestration across all stream-based adapters. Each adapter provides
+ * a `buildResult` factory to format results in its SDK-specific type.
+ *
+ * **Mutation:** When approval modifies tool arguments, entries in `toolCalls`
+ * are mutated in place via {@link applyApprovedArgs}.
+ * @param toolCalls - Tool calls from the model (entries may be mutated when approval modifies args)
+ * @param callbacks - Approval and lifecycle event callbacks
+ * @param contextOverrides - Execution context (session, agent, turn)
+ * @param buildResult - Adapter-specific result formatter
+ * @param adapterLabel - Adapter name for logging
+ * @returns Formatted tool results for injection back into the conversation
+ */
+declare function handleToolCalls<TResult>(toolCalls: ToolCall[], callbacks: HandleToolCallsCallbacks, contextOverrides: ToolExecutionContextOverrides, buildResult: ToolResultBuilder<TResult>, adapterLabel: string): Promise<TResult[]>;
+//#endregion
+//#region adapters/shared/stream-session/src/namespaces/schemas/turn-state.d.ts
+/**
+ * Public turn-state contract for stream-session adapters.
+ *
+ * Both Anthropic SDK and OpenAI Node adapters share these states.
+ * Neither uses a 'paused' state — they abort and restart instead.
+ */
+type StreamSessionTurnState = 'idle' | 'turn_started' | 'step_started' | 'step_finished' | 'turn_finished';
+/**
+ * Public payload contract for turn-state transitions.
+ */
+interface TurnStateChanged {
+  /** The adapter instance identifier. */
+  adapterId: string;
+  /** The agent this turn belongs to. */
+  agentId: string;
+  /** The state being left. */
+  oldState: StreamSessionTurnState;
+  /** The state being entered. */
+  newState: StreamSessionTurnState;
+  /** Unix timestamp (ms) when the transition occurred. */
+  timestamp: number;
+}
+/**
+ * Shared turn state schema for stream-session adapters.
+ */
+declare const StreamSessionTurnStateSchema: z.ZodEnum<{
+  idle: "idle";
+  turn_started: "turn_started";
+  step_started: "step_started";
+  step_finished: "step_finished";
+  turn_finished: "turn_finished";
+}>;
+/**
+ * Schema for a turn state change event.
+ * Emitted by adapters whenever the turn state machine transitions.
+ * @param adapterId - The adapter instance identifier.
+ * @param agentId - The agent this turn belongs to.
+ * @param oldState - The state being left.
+ * @param newState - The state being entered.
+ * @param timestamp - Unix timestamp (ms) when the transition occurred.
+ */
+declare const TurnStateChangedSchema: z.ZodObject<{
+  adapterId: z.ZodString;
+  agentId: z.ZodString;
+  oldState: z.ZodEnum<{
+    idle: "idle";
+    turn_started: "turn_started";
+    step_started: "step_started";
+    step_finished: "step_finished";
+    turn_finished: "turn_finished";
+  }>;
+  newState: z.ZodEnum<{
+    idle: "idle";
+    turn_started: "turn_started";
+    step_started: "step_started";
+    step_finished: "step_finished";
+    turn_finished: "turn_finished";
+  }>;
+  timestamp: z.ZodNumber;
+}, z.core.$strip>;
+//#endregion
+//#region adapters/shared/stream-session/src/namespaces/schemas/reasoning.d.ts
+/**
+ * Base schema for a reasoning delta event.
+ *
+ * Emitted during streaming when the model outputs incremental reasoning /
+ * thinking content. Both Anthropic (extended thinking) and OpenAI-compatible
+ * reasoning models emit this event.
+ *
+ * Adapter-specific schemas may extend this via `.extend()`.
+ */
+declare const ReasoningDeltaEventSchema: z.ZodObject<{
+  eventType: z.ZodLiteral<"reasoning_delta">;
+  content: z.ZodString;
+}, z.core.$strip>;
+/** Inferred reasoning delta event type. */
+type ReasoningDeltaEvent = z.infer<typeof ReasoningDeltaEventSchema>;
+/**
+ * Base schema for a reasoning complete event.
+ *
+ * Emitted when the full reasoning / thinking content has been assembled from
+ * all streaming deltas. Does NOT include the Anthropic-specific `signature`
+ * field — the Anthropic adapter extends this schema with `.extend()`.
+ *
+ * Adapter-specific schemas may extend this via `.extend()`.
+ */
+declare const ReasoningCompleteEventSchema: z.ZodObject<{
+  eventType: z.ZodLiteral<"reasoning_complete">;
+  content: z.ZodString;
+}, z.core.$strip>;
+/** Inferred reasoning complete event type. */
+type ReasoningCompleteEvent = z.infer<typeof ReasoningCompleteEventSchema>;
+//#endregion
+//#region adapters/shared/stream-session/src/namespaces/schemas/message.d.ts
+/**
+ * Base schema for a tool call embedded in a message complete event.
+ *
+ * Contains only the fields common to both Anthropic and OpenAI adapters.
+ * The Anthropic adapter's version additionally carries `blockIndex`.
+ */
+declare const MessageToolCallSchema: z.ZodObject<{
+  id: z.ZodString;
+  type: z.ZodLiteral<"function">;
+  function: z.ZodObject<{
+    name: z.ZodString;
+    arguments: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+/** Inferred base message tool call type. */
+type MessageToolCall = z.infer<typeof MessageToolCallSchema>;
+/**
+ * Base schema for a message complete event.
+ *
+ * Emitted when a full assistant message has been assembled from streaming
+ * chunks. The `finish_reason` and `tool_calls` fields are left open for
+ * each adapter to specialise via `.extend()`, since the allowed values
+ * differ between providers.
+ *
+ * Adapter-specific schemas MUST extend this schema and narrow:
+ * - `finish_reason` to their provider-specific enum
+ * - `tool_calls` to their adapter-specific tool-call schema (if needed)
+ */
+declare const MessageCompleteEventSchema: z.ZodObject<{
+  eventType: z.ZodLiteral<"message_complete">;
+  content: z.ZodNullable<z.ZodString>;
+  reasoning: z.ZodOptional<z.ZodString>;
+  tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"function">;
+    function: z.ZodObject<{
+      name: z.ZodString;
+      arguments: z.ZodString;
+    }, z.core.$strip>;
+  }, z.core.$strip>>>;
+  finish_reason: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** Inferred base message complete event type. */
+type MessageCompleteEvent = z.infer<typeof MessageCompleteEventSchema>;
+//#endregion
+//#region adapters/shared/stream-session/src/session/types.d.ts
+/**
+ * Union of SDK event types emitted directly by the base stream session.
+ *
+ * Adapter configs use a broader union (`SdkEventMessage`) that includes all
+ * adapter-specific events. Since `AgentStartedEvent` and `ErrorEvent` are
+ * members of every adapter's `SdkEventMessage` union, a function accepting
+ * the broader union satisfies this narrower parameter type via contravariance.
+ */
+type BaseSessionEmitEvent = AgentStartedEvent$1 | ErrorEvent$1;
+/**
+ * Minimal typed envelope for the `message_complete` SDK event returned
+ * from `bus.once()` inside the base stream session.
+ *
+ * Both adapter namespaces wrap their SDK events in an envelope with the same
+ * shape (event, agentId?, adapterId?, ...). The base session only
+ * needs `event.eventType` for dispatch and passes the full payload to
+ * `applyMessageComplete` which is implemented by each adapter subclass.
+ */
+interface StreamSdkEventEnvelope {
+  /** Inner SDK event discriminated by `eventType`. */
+  event: {
+    eventType: string;
+  } & Record<string, unknown>;
+  /** Agent ID from the envelope for bus filter matching. */
+  agentId?: string;
+  /** Adapter ID from the envelope for bus filter matching. */
+  adapterId?: string;
+  /** Adapter name from the envelope. */
+  adapterName?: string;
+  /** Session ID from the envelope. */
+  sessionId?: string;
+  /** Adapter-local session ID from the envelope for turn correlation. */
+  adapterSessionId?: string;
+}
+/**
+ * Shared configuration interface for stream-based connector sessions.
+ *
+ * Contains all fields common to the Anthropic SDK and OpenAI Node session
+ * configurations. SDK-specific fields (`client`, tool-list types) remain
+ * in each adapter's own config type which extends this interface.
+ * @typeParam TBus - Scoped bus type for the adapter namespace
+ */
+interface StreamSessionConfig<TBus extends ScopedBus<string> = ScopedBus<string>> {
+  /** Scoped bus for the adapter namespace. */
+  bus: TBus;
+  /** Stable adapter instance identifier. */
+  adapterId: string;
+  /** Human-readable adapter name used in log messages and bus events. */
+  adapterName: string;
+  /** Agent ID for tool execution attribution and bus subject filtering. */
+  agentId: string;
+  /** Makaio session ID for tool execution context. Stable across turns. */
+  sessionId?: string;
+  /** Working directory for tool execution context. */
+  cwd: string;
+  /** Initial model identifier; mutable per turn via `updateModel()`. */
+  model: string;
+  /** Reasoning effort level for reasoning-capable models. */
+  reasoningEffort?: AIReasoningLevel$1;
+  /**
+   * Timeout in milliseconds before the streaming API call is considered
+   * failed. A single retry is attempted before the error propagates.
+   */
+  streamStartTimeoutMs?: number;
+  /** Environment variables forwarded to tool execution. */
+  env: Record<string, string>;
+  /** Resolved system prompt string prepended to the message array. */
+  systemPrompt?: string;
+  /**
+   * Emit a typed SDK lifecycle event to the connector bus.
+   * Adapter configs narrow this to their full `SdkEventMessage` union.
+   * The base session only emits `agent_started` and `error` events,
+   * both of which are members of every adapter's `SdkEventMessage` union.
+   */
+  emitSdkEvent: (event: BaseSessionEmitEvent) => Promise<void>;
+  /** Handle a connector-level error. */
+  handleError: (error: Error, rethrow: boolean) => void;
+  /** Called synchronously when a new turn is about to start. */
+  onTurnStart?: (handle: MessageHandle) => void;
+  /** Called when a turn reaches a terminal state (completed or error). */
+  onTurnComplete?: (handle: MessageHandle, result: MessageResult) => void;
+  /** Optional low-level event logger for adapter observability. */
+  logLowLevelEvent?: (event: unknown) => void;
+  /**
+   * Directory restrictions for file-system tool execution.
+   * Forwarded as `constraints.allowedDirectories` in every tool call.
+   * - `undefined`: no directory restriction
+   * - `[]`: deny all filesystem paths
+   * - non-empty array: allow-list to these directories
+   */
+  allowedDirectories?: string[];
+  /**
+   * Record one mcp_call invocation in the session tool ledger.
+   *
+   * When present, the session forwards this to `HandleToolCallsCallbacks` so
+   * the shared `handleToolCalls` function can record mcp_call invocations.
+   * The connector binds it as a closure over its ledger and current turn number,
+   * so no turn-number threading is needed at the session level.
+   * @param toolFullName - The namespaced target tool name from the mcp_call args
+   */
+  recordMcpCall?: (toolFullName: string) => void;
+}
+//#endregion
+//#region adapters/shared/stream-session/src/session/base-stream-session.d.ts
+/**
+ * Turn contract required by `BaseStreamSession`.
+ *
+ * Stream sessions depend on the core procedural turn lifecycle plus an abort
+ * signal accessor used by `runTurnIteration`.
+ */
+interface StreamSessionTurn extends ProceduralConnectorTurn {
+  /**
+   * Get the current abort signal for this turn.
+   * @returns AbortSignal for stream cancellation
+   */
+  getAbortSignal(): AbortSignal;
+}
+/**
+ * Abstract base class for stream-based AI connector sessions.
+ *
+ * Captures the shared session lifecycle logic between the Anthropic SDK and
+ * OpenAI Node adapters. Both adapters use an identical queue-based turn model:
+ *
+ * 1. `processQueue` — dequeues messages and dispatches to `startNewTurn`
+ * 2. `startNewTurn` — initialises a new turn, wires the finally-cleanup, and
+ *    fires the async `queueMicrotask` loop
+ * 3. `runTurn` → `runTurnIteration` — the agentic loop; executes streaming
+ *    API calls and recurses when tool calls are returned
+ * 4. `executeStreamingStep` — the stream-start-timeout wrapper; delegates the
+ *    actual API call to the abstract `executeApiCall` hook
+ * 5. `applyMessageComplete` — abstract; each adapter appends the assistant
+ *    response in its own wire format and handles tool recursion
+ *
+ * ## Generic type parameters
+ * @typeParam TConfig - Adapter session config extending `StreamSessionConfig`
+ * @typeParam TTurn - Adapter turn type extending `ProceduralConnectorTurn`
+ * @typeParam TMessageCompleteEvent - Adapter-specific `MessageCompleteEvent`
+ *   extension; defaults to the shared base schema type
+ */
+declare abstract class BaseStreamSession<TConfig extends StreamSessionConfig<ScopedBus<string>>, TTurn extends StreamSessionTurn, TMessageCompleteEvent extends MessageCompleteEvent = MessageCompleteEvent> extends BaseConnectorSession<TConfig> {
+  /**
+   * Maximum number of tool-call recursion steps per turn.
+   * Subclasses reference this in `applyMessageComplete`.
+   */
+  protected static readonly MAX_TOOL_CALL_ITERATIONS = 8;
+  /** Active turn reference; overwritten on each new turn. */
+  protected currentTurn: TTurn | undefined;
+  /** Assembled last assistant message content; reset on each new turn. */
+  protected lastAssistantMessage: string | undefined;
+  /** Runtime model used for subsequent API calls; set from config.model. */
+  protected currentModel: string;
+  /** Runtime working directory for tool execution; set from config.cwd. */
+  protected currentCwd: string;
+  /** Pending public-turn history compactions waiting for canonical completion. */
+  private readonly pendingAssistantHistoryCompactions;
+  /**
+   * Initialize a stream session with connector runtime config.
+   * @param config - Session configuration (bus identity, model/cwd defaults, and adapter hooks).
+   */
+  constructor(config: TConfig);
+  /**
+   * Create the adapter-specific turn instance for `handle`.
+   * @param handle - The message handle this turn will process
+   * @returns A new turn instance
+   */
+  protected abstract createTurn(handle: MessageHandle): TTurn;
+  /**
+   * Build (or rebuild) the adapter-specific messages array from the message
+   * handle's history and optional merged content from superseded messages.
+   * @param handle - The message handle containing history and current message
+   * @param mergedContent - Text content from superseded/merged messages
+   */
+  protected abstract buildMessages(handle: MessageHandle, mergedContent?: string[]): void;
+  /**
+   * Return the current adapter-specific conversation history length.
+   *
+   * Used to checkpoint the boundary immediately after a user turn has been
+   * materialized, so structured-output retries can later compact provisional
+   * assistant/retry blocks back to the canonical public completion.
+   * @returns Number of provider-native messages currently in history
+   */
+  protected abstract getConversationHistoryLength(): number;
+  /**
+   * Replace all assistant-side history for a turn with the canonical assistant
+   * message emitted by the `MessageHandle`.
+   * @param startIndex - History index immediately after the user turn input
+   * @param endIndex - Exclusive history boundary for provisional assistant/retry blocks
+   * @param assistantMessage - Canonical assistant message for that turn
+   */
+  protected abstract replaceAssistantTurnHistory(startIndex: number, endIndex: number, assistantMessage: string): void;
+  /**
+   * Execute the adapter-specific streaming API call.
+   *
+   * Called inside `executeStreamingStep` after the stream-start timeout is
+   * armed. Implementors must operate on the provided turn instance rather than
+   * reading `this.currentTurn` directly so superseded turns cannot mutate the
+   * active turn state.
+   * @param turn - Captured turn instance for this run loop
+   * @param abortSignal - Combined abort signal (turn abort + stream timeout)
+   * @param adapterSessionId - Turn-scoped adapter session ID for event correlation
+   */
+  protected abstract executeApiCall(turn: TTurn, abortSignal: AbortSignal, adapterSessionId: string): Promise<void>;
+  /**
+   * Return the bus subject to `once()` on for the `message_complete` event.
+   *
+   * Each adapter listens on its own namespace subject (e.g.
+   * `AnthropicSdkConnectorSubjects.sdk.event`).
+   * @returns The bus subject for the adapter's SDK event stream
+   */
+  protected abstract getSdkEventSubject(): ScopedSubjectDefinition<string>;
+  /**
+   * Apply a `message_complete` event to the messages array and recurse for
+   * tool calls.
+   *
+   * Called in `runTurnIteration` after `message_complete` is received from
+   * the bus. Implementations append the assistant message in the adapter's
+   * wire format, check the tool-call finish reason, and call
+   * `runTurnIteration` again when tools need executing.
+   * @param result - The parsed `message_complete` event payload
+   * @param currentHandle - The active message handle
+   * @param toolCallIteration - Current recursion depth (for iteration guard)
+   * @param turn - Captured turn instance for this run loop
+   */
+  protected abstract applyMessageComplete(result: TMessageCompleteEvent, currentHandle: MessageHandle, toolCallIteration: number, turn: TTurn): Promise<void>;
+  /**
+   * Classify an SDK-level error into the appropriate error type.
+   *
+   * The base class re-throws whatever this returns; adapters map SDK-specific
+   * error shapes (e.g. Anthropic's `APIError`, OpenAI's `APIError`) to
+   * normalised error instances.
+   * @param error - The raw error caught from the API call or stream
+   * @returns A normalised `Error` instance
+   */
+  protected abstract classifyError(error: unknown): Error;
+  /**
+   * Process messages from the queue.
+   *
+   * Creates a new turn or handles immediate injection via abort+restart.
+   * @param queue - The user message queue to drain
+   */
+  processQueue(queue: UserMessageQueue): Promise<void>;
+  /**
+   * Start a new turn for the given message handle.
+   *
+   * Orchestrates the full turn setup: session ID rotation, message building,
+   * turn creation, acknowledgment, and the async `queueMicrotask` loop.
+   * Turn finalisation is always in the `finally` block so the connector state
+   * machine always reaches a terminal state.
+   * @param handle - The message handle to process
+   * @param mergedContent - Optional content from superseded/merged messages
+   */
+  protected startNewTurn(handle: MessageHandle, mergedContent?: string[]): Promise<void>;
+  /**
+   * Handle a turn-level error from the `queueMicrotask` body.
+   *
+   * Branches on whether the turn was paused (immediate-mode abort or
+   * shutdown) and either returns silently, completes the handle with an
+   * error result, or delegates to the connector error handler.
+   * @param error - The caught error
+   * @param turn - The captured turn reference for pause-state checks
+   * @param handle - The message handle to finalise on non-abort errors
+   */
+  private handleTurnError;
+  /**
+   * Run a turn — the agentic loop entry point.
+   * @param turn - Captured turn instance for this run loop
+   * @param currentHandle - The handle to track supersedence
+   */
+  protected runTurn(turn: TTurn, currentHandle: MessageHandle): Promise<void>;
+  /**
+   * Wait for the SDK `message_complete` event emitted by stream processing.
+   *
+   * Uses `bus.once` with AbortSignal support to avoid dangling listeners on
+   * abort. Namespace-scoped buses are shared across connector instances, so
+   * the filter includes both the event type and adapter identity to prevent
+   * concurrent agents from satisfying each other's waiter.
+   * @param abortSignal - Abort signal for the current turn
+   * @param adapterSessionId - Adapter-local session ID bound to the turn
+   * @returns Promise resolving to the SDK event envelope
+   */
+  protected createMessageCompletePromise(abortSignal: AbortSignal, adapterSessionId: string): Promise<{
+    payload: StreamSdkEventEnvelope;
+  }>;
+  /**
+   * Execute one streaming API step with stream-start-timeout protection.
+   *
+   * Arms a timeout that aborts the stream connection attempt if no bytes
+   * arrive within `streamStartTimeoutMs` (default: 30 s). On timeout a
+   * single retry is attempted by `runTurnIteration`. Delegates the actual
+   * API call to the abstract `executeApiCall` hook.
+   * @param turn - Captured turn instance for this run loop
+   * @param abortSignal - Turn-level abort signal
+   * @param adapterSessionId - Turn-scoped adapter session ID for event correlation
+   */
+  protected executeStreamingStep(turn: TTurn, abortSignal: AbortSignal, adapterSessionId: string): Promise<void>;
+  /**
+   * Run one iteration of the agentic loop.
+   *
+   * Fires the streaming step, waits for the `message_complete` event, then
+   * delegates to `applyMessageComplete`. Handles abort signals, stream-start
+   * timeouts (with a single retry), and SDK-level errors uniformly.
+   * @param turn - Captured turn instance for this run loop
+   * @param currentHandle - The handle to track supersedence
+   * @param toolCallIteration - Current tool recursion depth (default: 0)
+   */
+  protected runTurnIteration(turn: TTurn, currentHandle: MessageHandle, toolCallIteration?: number): Promise<void>;
+  /**
+   * Build the tool execution constraints object from session config.
+   *
+   * Returns `{ allowedDirectories }` when `config.allowedDirectories` is set,
+   * or `undefined` when no directory restrictions are configured. Both
+   * concrete adapter sessions call this in `applyMessageComplete` to avoid
+   * duplicating the conditional spread.
+   * @returns Typed constraints for `ToolExecutionContextOverrides`, or `undefined`
+   */
+  protected buildToolConstraints(): {
+    allowedDirectories: string[];
+  } | undefined;
+  /**
+   * Update the model used for subsequent API calls.
+   *
+   * Called by the connector's `changeModelInPlace()` to sync the session
+   * with the connector-level model without requiring a full session swap.
+   * @param model - New model identifier
+   */
+  updateModel(model: string): void;
+  /**
+   * Update the working directory used for subsequent tool executions.
+   *
+   * Called by the connector's `changeCwdInPlace()` to sync the session
+   * with the connector-level cwd without requiring a full session swap.
+   * @param cwd - New working directory path
+   */
+  updateCwd(cwd: string): void;
+  /**
+   * Get the current turn for state inspection.
+   * @returns The current turn or `undefined` if no turn is active
+   */
+  getCurrentTurn(): TTurn | undefined;
+  /**
+   * Returns true when a newer turn has replaced the captured turn.
+   * @param turn - Captured turn reference
+   * @returns Whether this turn has been superseded
+   */
+  protected isTurnSuperseded(turn: TTurn): boolean;
+  /**
+   * Unified early-exit guard for stale turns and superseded handles.
+   * @param turn - Captured turn reference
+   * @param currentHandle - Active message handle
+   * @returns True when iteration must stop
+   */
+  protected shouldAbortTurnProcessing(turn: TTurn, currentHandle: MessageHandle): boolean;
+  /**
+   * Close any unresolved public-turn history compactions before a new public
+   * turn appends its user message.
+   * @param endIndex - Exclusive boundary before the new public turn starts
+   */
+  private closePendingAssistantHistoryCompactions;
+  /**
+   * Remove a completed history compaction from the pending set.
+   * @param compaction - Pending compaction handle to remove
+   */
+  private removePendingAssistantHistoryCompaction;
+}
+//#endregion
+//#region adapters/shared/stream-session/src/connector/base-stream-connector.d.ts
+/**
+ * Minimal session contract required by BaseStreamConnector.
+ *
+ * Extends `ProceduralConnectorSession` with the lifecycle methods that the
+ * connector delegates to: `abort` (used by interrupt/close), `updateModel` and
+ * `updateCwd` for in-place mutation without a full session swap.
+ */
+interface StreamConnectorSession extends ProceduralConnectorSession {
+  /** Abort the active turn, cancelling any in-flight API call. */
+  abort(): Promise<void>;
+  /**
+   * Update the model used for subsequent API calls.
+   * @param model - New model identifier
+   */
+  updateModel(model: string): void;
+  /**
+   * Update the working directory used for subsequent tool executions.
+   * @param cwd - New working directory path
+   */
+  updateCwd(cwd: string): void;
+  /**
+   * Update the session's tool set for the next API call.
+   * Optional — not all adapters support mid-session tool updates.
+   * @param tools - New tool list in generic `ToolListItem` format; session converts internally
+   */
+  updateTools?(tools: ToolListItem[]): void;
+  /**
+   * Update the reasoning effort level used for subsequent API calls.
+   * Optional — only adapters that pass reasoning per-request implement this seam.
+   * @param level - New reasoning effort level
+   */
+  updateReasoning?(level: AIReasoningLevel$1): void;
+}
+/**
+ * Config shape required by `BaseStreamConnector`.
+ *
+ * Extends `BaseAgentConnectorConfig` and widens `mcpSessionContext` to include
+ * the full {@link McpSessionContext} shape so the stream connector can
+ * re-resolve the session via the bus (which requires `sessionId`, `profileId`,
+ * and `projectId`). The orchestrator always supplies a full `McpSessionContext`;
+ * `LedgerSessionContext` is retained in the union for standalone/test connectors
+ * that do not need bus re-resolve.
+ * @typeParam TBus - Scoped bus type for the adapter namespace
+ * @typeParam TProviderConfig - Provider-specific config object
+ */
+type BaseStreamConnectorConfig<TBus extends ScopedBus<string> = ScopedBus<string>, TProviderConfig extends object = object> = Omit<BaseAgentConnectorConfig<TBus, TProviderConfig>, 'mcpSessionContext'> & {
+  /**
+   * MCP session context resolved by the orchestrator.
+   * May be the full {@link McpSessionContext} (with `sessionId`/`servers` for
+   * bus re-resolve) or a bare `LedgerSessionContext` for standalone connectors.
+   * The connector discriminates at runtime via `'sessionId' in ctx`.
+   */
+  mcpSessionContext?: McpSessionContext | LedgerSessionContext;
+};
+/**
+ * Abstract base class for stream-based AI adapter connectors.
+ *
+ * Captures the shared connector lifecycle logic between the Anthropic SDK and
+ * OpenAI Node adapters. Both connectors follow an identical pattern:
+ *
+ * - Lazy single-session initialisation via `ensureSession` / `initializeSession`
+ * - Tool fetching on first turn (delegated to the abstract `fetchTools` hook)
+ * - `sendMessage` → `processUserMessages` delegation to `ProceduralAgentConnector`
+ * - In-place model and cwd mutation via `changeModelInPlace` / `changeCwdInPlace`
+ *
+ * Concrete subclasses must implement the following abstract hooks:
+ * - `fetchTools()` — fetch adapter-specific tools and cache them internally
+ * - `createSession()` — construct the concrete session instance
+ * - `getTurnSubjects()` — return adapter-specific turn lifecycle subjects
+ *
+ * Subclasses may override `afterSessionCreated()` for extra post-creation wiring
+ * (e.g. Anthropic sets tools on the session after construction).
+ * @typeParam TBus - Scoped bus type for the adapter namespace
+ * @typeParam TSession - Concrete session type; must satisfy `StreamConnectorSession`
+ * @typeParam TConfig - Connector config type extending `BaseStreamConnectorConfig<TBus>`
+ */
+declare abstract class BaseStreamConnector<TBus extends ScopedBus<string>, TSession extends StreamConnectorSession, TConfig extends BaseStreamConnectorConfig<TBus>> extends ProceduralAgentConnector<TBus, TConfig> {
+  /** Session manages Turn lifecycle. Initialised lazily on first message. */
+  private session?;
+  /** Message queue for serialising async send operations. */
+  private readonly userMessageQueue;
+  /** MCP tools resolved for direct injection into the session. */
+  protected mcpDirectTools: ToolListItem[];
+  /**
+   * Fresh MCP session context fetched via bus during `refreshTools()`.
+   *
+   * When set, `prepareMcpDirectTools()` reads from this cache instead of the
+   * startup snapshot in `config.mcpSessionContext`, ensuring that mid-session
+   * tool refreshes reflect the current registry state rather than the state
+   * at connector construction time.
+   */
+  private mcpSessionContextCache?;
+  /**
+   * Flag set via `markToolRefreshPending()` by the AIAgent layer on MCP bus events.
+   * Checked at turn boundaries to trigger `refreshTools()`.
+   *
+   * Refreshing mid-turn would mutate the tool set while the LLM is actively
+   * generating tool calls against the current set, risking inconsistent state.
+   * Instead, the refresh is deferred to the next turn boundary:
+   *
+   * - Consumed in `onTurnStarted` (primary) so the next turn uses updated tools
+   *   immediately, before the API call is made.
+   * - Consumed in `onTurnFinished` (safety net) for updates that arrive
+   *   mid-turn, ensuring the turn after that also picks up the updated tools.
+   */
+  protected hasPendingToolRefresh: boolean;
+  /**
+   * Set to `true` by `refreshTools()` when MCP direct-inject tools have been
+   * re-prepared but the canonical turn number for the next turn is not yet known.
+   *
+   * Flushed to the tool ledger in `onTurnStarted`, after `consumeTurnNumber()`
+   * has committed the real canonical value, ensuring `recordInjection` is always
+   * called with the correct turn number rather than a speculative `currentTurnNumber + 1`.
+   */
+  private hasPendingLedgerInjection;
+  /**
+   * Marks that MCP tools have changed and should be refreshed at the next turn boundary.
+   *
+   * Called by the AIAgent layer when receiving MCP bus events (`mcp.tools.updated`,
+   * `mcp.tools.enabled`). The connector will call `refreshTools()` before processing
+   * the next queued message.
+   */
+  markToolRefreshPending(): void;
+  /**
+   * Fetch adapter-specific tools from the bus and cache them internally.
+   *
+   * Called once before the first session is created. Implementations store
+   * the result in their own typed field (e.g. `this.anthropicTools`) which is
+   * then passed to `createSession()`.
+   */
+  protected abstract fetchTools(): Promise<void>;
+  /**
+   * Construct and return the concrete session instance.
+   *
+   * Called by `initializeSession` after tools have been fetched. The session
+   * config should be fully populated from `this.config`, `this.cwd`,
+   * `this.model`, and the previously fetched tools.
+   * @returns The initialised adapter-specific session
+   */
+  protected abstract createSession(): TSession;
+  /**
+   * Perform any adapter-specific post-creation wiring on the session.
+   *
+   * Called immediately after `createSession()` and before `wireSessionEvents()`.
+   * The default implementation is a no-op — override only when the adapter
+   * needs extra wiring beyond what `createSession()` already handles.
+   * @param _session - The freshly created session instance
+   */
+  protected afterSessionCreated(_session: TSession): void;
+  /**
+   * Return the adapter's namespace-specific turn subjects for `wireSessionEvents`.
+   *
+   * Forwarded to `ProceduralAgentConnector.wireSessionEvents` which subscribes
+   * to turn lifecycle events and updates connector processing state.
+   * @returns Turn subject definitions for this adapter's namespace
+   */
+  protected abstract getTurnSubjects(): WireSessionSubjects<TBus['namespace']>;
+  /**
+   * Get the active session instance.
+   * @returns The session or `undefined` if not yet initialised
+   */
+  protected getSession(): TSession | undefined;
+  /**
+   * Ensure the session is initialised and return it.
+   *
+   * No-op if the session already exists (idempotent). Creates and wires the
+   * session on first call by delegating to `initializeSession`.
+   * @returns The initialised session as `ProceduralConnectorSession`
+   */
+  protected ensureSession(): Promise<ProceduralConnectorSession>;
+  /**
+   * Get the user message queue for this connector.
+   * @returns The `UserMessageQueue` instance shared across all turns
+   */
+  protected getSessionQueue(): UserMessageQueue;
+  /**
+   * Initialise the session for SDK lifecycle management.
+   *
+   * Fetches tools (once via `fetchToolsViaBus`), prepares MCP direct-inject
+   * tools, constructs the concrete session via `createSession`, runs optional
+   * adapter-specific post-creation wiring via `afterSessionCreated`, wires turn
+   * events to the connector state machine via `wireSessionEvents`, pushes any
+   * MCP direct-inject tools into the session via `updateTools`, then records
+   * the initial injection set in the tool ledger at the correct turn number
+   * (1 for fresh sessions; the staged canonical turn for connector swaps).
+   */
+  private initializeSession;
+  /**
+   * Convert MCP direct-inject tools from the session context to the generic
+   * `ToolListItem` format and cache in `this.mcpDirectTools`.
+   *
+   * Called during `initializeSession()` after `fetchToolsViaBus()`, and again
+   * by `refreshTools()` when the tool set may have changed. Reads from
+   * `mcpSessionContextCache` when available (populated by a bus re-resolve),
+   * falling back to the startup snapshot in `config.mcpSessionContext`.
+   * No-op when neither source is present.
+   */
+  protected prepareMcpDirectTools(): void;
+  /**
+   * Fetch tools from the bus if not already loaded.
+   *
+   * Guards with a `this.session` check so tools are only fetched once per
+   * connector lifetime. Delegates to the abstract `fetchTools` hook which each
+   * adapter implements to populate its own typed tools field.
+   */
+  protected fetchToolsViaBus(): Promise<void>;
+  /**
+   * Re-prepare MCP direct-inject tools for the next turn.
+   *
+   * Called at turn boundary when `hasPendingToolRefresh` is true (set via
+   * `markToolRefreshPending()`). When a full `McpSessionContext` (with
+   * `sessionId`) is available, issues a `McpSubjects['session.resolve']` bus
+   * call to fetch the latest tool state from the registry, updating
+   * `mcpSessionContextCache` so `prepareMcpDirectTools()` reads fresh data.
+   * If the bus call fails, logs a warning and falls back to the previous cache
+   * (or the startup snapshot) so the connector remains operational.
+   *
+   * Subclasses that manage native adapter-format tools (e.g. Anthropic, OpenAI)
+   * override this to: (1) re-fetch their native tools, (2) call
+   * `super.refreshTools()` to re-prepare `mcpDirectTools` and arm the ledger
+   * flag, then (3) push the updated tool list to the active session via
+   * `this.getSession()?.updateTools?.(this.mcpDirectTools)`.
+   *
+   * Unlike `fetchTools()` which runs once before session creation,
+   * `refreshTools()` operates on a live session and may be called multiple
+   * times during a connector's lifetime.
+   */
+  protected refreshTools(): Promise<void>;
+  /**
+   * Re-resolve the MCP session context from the bus and update the cache.
+   *
+   * Only fires when the startup config holds a full `McpSessionContext` (i.e.
+   * it has a `sessionId`). Standalone connectors created without a session skip
+   * this and continue to use the existing cache or startup snapshot.
+   * On bus failure the warning is logged and the cache is left unchanged so
+   * the connector can continue with the last known good tool set.
+   */
+  private resolveAndCacheMcpContext;
+  /**
+   * Wire turn-boundary hooks into the session lifecycle.
+   *
+   * - `onTurnStarted`: commit the canonical turn number via `consumeTurnNumber`,
+   *   refresh tools if a pending update arrived while idle or during the previous
+   *   turn (primary refresh path), then flush any pending ledger injection so
+   *   `recordInjection` is always called with the real turn number. The order
+   *   matters: consumeTurnNumber → refreshTools → recordInjection, because
+   *   `refreshTools` sets `hasPendingLedgerInjection`.
+   * - `onTurnFinished`: safety-net refresh for updates that arrive mid-turn,
+   *   before draining the queue so the following turn uses the updated tool set.
+   * @returns Wire session configuration with the turn hooks
+   */
+  protected getWireSessionConfig(): WireSessionConfig;
+  /**
+   * Resolve the runtime system prompt to a plain string for the SDK API.
+   *
+   * - `string` mode: use as-is
+   * - Append mode: use `content` directly (stream-based adapters have no base
+   *   prompt to append to)
+   * @returns Resolved prompt string, or `undefined` if no prompt is set
+   */
+  protected resolveSystemPrompt(): string | undefined;
+  /**
+   * Send a message to the agent.
+   * @param message - The normalised message to send
+   * @param options - Optional send message options
+   * @returns A handle for tracking the message
+   */
+  sendMessage(message: NormalizedMessageInput, options?: ConnectorSendMessageOptions): Promise<MessageHandle>;
+  /**
+   * Abort the agent and clean up resources.
+   *
+   * Note: Session-closed event emission is handled by the adapter's AIAgent
+   * layer, not by the connector.
+   */
+  abort(): void;
+  /**
+   * Gracefully close the session.
+   */
+  close(): Promise<void>;
+  /**
+   * Perform an in-place model update without swapping the connector.
+   *
+   * Stream-based adapters are stateless — the session caches `config.model` at
+   * construction but must be synced here so the next turn uses the new model.
+   *
+   * **Mutation contract:** Implementations MUST NOT mutate `this.model`.
+   * The caller owns the connector-level `model` field update after this returns.
+   * @param newModel - The model identifier to switch to
+   * @returns Always `true` — stateless APIs never require a full connector swap
+   */
+  changeModelInPlace(newModel: string): Promise<boolean>;
+  /**
+   * Perform an in-place working-directory update without swapping the connector.
+   *
+   * Stream-based adapters are stateless — cwd is only used for tool execution
+   * context, not for persistent session state.
+   *
+   * **Mutation contract:** Implementations MUST NOT mutate `this.cwd`.
+   * The caller owns the connector-level `cwd` field update after this returns.
+   * @param newCwd - The working directory path to switch to
+   * @returns Always `true` — stateless APIs never require a full connector swap
+   */
+  changeCwdInPlace(newCwd: string): Promise<boolean>;
+  /**
+   * Perform an in-place reasoning effort update without swapping the connector.
+   *
+   * Stream-based adapters pass `reasoning_effort` (or equivalent) per-request.
+   * The session's `currentReasoningEffort` field is updated so the next API
+   * call uses the new level without requiring a full connector swap.
+   *
+   * **Mutation contract:** Implementations MUST NOT mutate `this.currentReasoningEffort`.
+   * The caller owns the connector-level field update after this returns `true`.
+   * @param newLevel - The new reasoning effort level to apply
+   * @returns Always `true` — stateless APIs never require a full connector swap
+   */
+  changeReasoningInPlace(newLevel: AIReasoningLevel$1): Promise<boolean>;
+  /**
+   * Interrupt the current turn by aborting the active API request.
+   */
+  interrupt(): Promise<void>;
+  /**
+   * Get the adapter session ID.
+   *
+   * Stream-based adapters use a locally-generated UUID (stateless APIs provide
+   * no server-side session identity).
+   * @returns The local session UUID
+   */
+  getAdapterSessionId(): Promise<string>;
+  /**
+   * Initialise `adapterSessionId` from config or generate a fresh UUID.
+   *
+   * Call this at the end of each concrete constructor after `super()`. The
+   * nullish-assignment guard ensures the swap case (where the base constructor
+   * already populated `adapterSessionId` from config) is preserved.
+   */
+  protected initAdapterSessionId(): void;
+}
+//#endregion
+//#region adapters/shared/stream-session/src/agent/base-stream-agent.d.ts
+/**
+ * Extract the bus namespace from a connector via the same conditional type used by
+ * `AIAgent.subscribeConnector` and `AIAgent.createConnectorEventMapping`.
+ *
+ * Using the identical conditional type expression ensures TypeScript resolves the
+ * constraint at call sites without a namespace mismatch error.
+ * @typeParam TConnector - Connector type extending `AIAgentConnector<ScopedBus<string>>`
+ */
+type ConnectorNamespace<TConnector extends AIAgentConnector<ScopedBus<string>>> = TConnector extends AIAgentConnector<infer TBus> ? TBus['namespace'] : never;
+type ToolCallArgs = Record<string, unknown>;
+/**
+ * A manually typed subject definition for event (non-request) subjects.
+ *
+ * Uses a structural interface rather than `SubjectDefinition<SubjectRecord, ...>` to
+ * avoid the incompatibility that arises when the full namespace `SubjectRecord` contains
+ * a mix of event and request subjects (e.g., `tool_approval` is a request). By defining
+ * only the `$meta` fields we care about, concrete subjects that extend `ScopedSubjectDefinition`
+ * are still assignable here as long as they carry event payloads.
+ *
+ * `HandlerForSubjectDefinition<EventSubjectDef<N>>` resolves to
+ * `EventHandler<Record<string, unknown>>` — a concrete, non-`never` handler type —
+ * enabling the base class wire methods to use typed handler parameters.
+ * @typeParam TNamespace - The adapter bus namespace string
+ */
+type EventSubjectDef<TNamespace extends string> = {
+  readonly $meta: {
+    readonly payload: EventMessagePayload<Record<string, unknown>>;
+    readonly namespace: TNamespace;
+    readonly isRequest: false;
+    readonly local: boolean;
+    readonly channel: boolean;
+  };
+  readonly subject: string;
+};
+/**
+ * Adapter-specific subjects for stream-based agent wiring.
+ *
+ * Groups all connector scoped subjects used during event wiring into a single spec
+ * type parameter. Subjects whose payloads differ between adapters (chunk, usage,
+ * toolCalls, reasoningComplete) carry a generic `EventSubjectDef`. Concrete adapters
+ * supply fully typed subjects when implementing `getConnectorSubjects()` — the typed
+ * subjects extend `EventSubjectDef` so TypeScript can resolve handler signatures.
+ * @typeParam TNamespace - The adapter bus namespace string literal
+ */
+interface StreamAdapterSubjectSpec<TNamespace extends string> {
+  /**
+   * Streaming chunk subject. Payload differs per adapter:
+   * - Anthropic: `{ eventType, index, delta }` (delta.text for text_delta)
+   * - OpenAI: `{ eventType, id, choices }` (choices[0].delta.content)
+   */
+  readonly chunk: EventSubjectDef<TNamespace>;
+  /**
+   * Token usage subject. Payload differs per adapter:
+   * - Anthropic: has `cache_read_input_tokens` / `cache_creation_input_tokens`
+   * - OpenAI: has `prompt_tokens_details` / `completion_tokens_details`
+   */
+  readonly usage: EventSubjectDef<TNamespace>;
+  /**
+   * Tool calls subject. Payload differs per adapter:
+   * - Anthropic: each tool call entry carries a provider `blockIndex`
+   * - OpenAI: base ToolCall without blockIndex
+   */
+  readonly toolCalls: EventSubjectDef<TNamespace>;
+  /**
+   * Reasoning complete subject. Payload differs per adapter:
+   * - Anthropic: base + `signature` field (for native history round-trip)
+   * - OpenAI: base only
+   */
+  readonly reasoningComplete: EventSubjectDef<TNamespace>;
+  /** Assembled message complete event — `content` field is shared across adapters. */
+  readonly messageComplete: EventSubjectDef<TNamespace>;
+  /** Incremental reasoning content delta — payload is shared across adapters. */
+  readonly reasoningDelta: EventSubjectDef<TNamespace>;
+  /** Tool execution started lifecycle event — payload is shared across adapters. */
+  readonly toolStarted: EventSubjectDef<TNamespace>;
+  /** Tool execution completed lifecycle event — payload is shared across adapters. */
+  readonly toolCompleted: EventSubjectDef<TNamespace>;
+  /** Agent turn started lifecycle event — payload is shared across adapters. */
+  readonly agentStarted: EventSubjectDef<TNamespace>;
+  /** Agent turn completed lifecycle event — payload is shared across adapters. */
+  readonly agentComplete: EventSubjectDef<TNamespace>;
+  /** Connector-level error event — payload is shared across adapters. */
+  readonly error: EventSubjectDef<TNamespace>;
+}
+/**
+ * Abstract base class for stream-based AI adapter agents.
+ *
+ * Captures the shared event-wiring logic between the Anthropic SDK and
+ * OpenAI Node agent implementations. Both agents follow an identical two-tier
+ * fan-out pattern:
+ *
+ * 1. `wireSdkEvents()` routes the sdk.event catch-all to typed semantic subjects
+ * (adapter-specific — kept abstract to avoid complex generics with `createConnectorEventMapping`).
+ * 2. `wireSemanticEvents()` wires semantic subjects to global `agent.*` subjects
+ * (shared — implemented here; delegates adapter-specific parts to abstract hooks).
+ *
+ * Abstract hooks that subclasses must implement:
+ * - `wireSdkEvents()` — routes sdk.event to semantic subjects (adapter-specific).
+ * - `getConnectorSubjects()` — returns the semantic subject spec for this adapter.
+ * - `extractChunkText(payload)` — extracts text from adapter-specific chunk events.
+ * - `extractUsagePayload(payload)` — maps adapter-specific usage to `NormalizedCallUsage`.
+ * - `emitUsageContextWindowUpdate(payload)` — emits context window status after usage tracking.
+ * - `reserveToolCallBlockIndex(tc)` — assigns block index for a tool call.
+ * - `afterToolCallStepEmitted(blockIndex)` — post-emission book-keeping for tool_calls.
+ * - `getFallbackToolCompletedBlockIndex()` — fallback index when map lookup misses.
+ * - `afterToolCompletedStepEmitted(resolvedBlockIndex)` — post-emission book-keeping for tool_completed.
+ * - `buildReasoningBlock(payload)` — constructs the reasoning `SessionMessageBlock`.
+ * - `wireToolApprovalRpc(connector)` — wires the adapter's tool_approval RPC to the global bus.
+ * @typeParam TBus - Scoped bus for the adapter namespace
+ * @typeParam TConnector - Concrete connector type extending `AIAgentConnector<TBus>`
+ * @typeParam TSpec - Subject spec whose namespace matches `ConnectorNamespace<TConnector>`
+ */
+declare abstract class BaseStreamAgent<TBus extends ScopedBus<string>, TConnector extends AIAgentConnector<TBus>, TSpec extends StreamAdapterSubjectSpec<ConnectorNamespace<TConnector>>> extends AIAgent<TBus, TConnector> {
+  /**
+   * Track toolCallId → blockIndex for correlation between step.started and step.finished.
+   *
+   * Both adapters emit parallel tool calls (all at once in the tool_calls event),
+   * but results arrive asynchronously in separate tool_completed events, potentially
+   * out of order. This map ensures each tool's step.finished uses the same blockIndex
+   * as its step.started, maintaining correlation regardless of arrival order.
+   *
+   * Pattern:
+   * 1. tool_calls event: reserve blockIndex per toolCallId, store in map
+   * 2. tool_completed event: lookup stored blockIndex, emit step.finished, delete from map
+   */
+  protected toolBlockIndexMap: Map<string, number>;
+  /**
+   * Track tool call IDs whose completion already arrived.
+   *
+   * Some providers can deliver `tool_completed` before `tool_calls` under
+   * race conditions. Mark completed IDs so late `tool_calls` can be ignored
+   * instead of emitting out-of-order step.started/tool.use events.
+   */
+  protected completedToolIds: Set<string>;
+  /**
+   * Stash tool call args keyed by toolCallId.
+   *
+   * Args are available when `tool_calls` fires (parsed from function arguments)
+   * but must be forwarded to `tool_completed` which arrives separately.
+   * Entries are removed after emission to prevent unbounded growth.
+   */
+  protected toolCallArgsMap: Map<string, ToolCallArgs>;
+  private resetPerTurnToolTracking;
+  /**
+   * Tier 1: Route sdk.event catch-all to typed semantic subjects.
+   *
+   * Implement by calling `this.createConnectorEventMapping(connectorSubjects.sdk.event, 'eventType', { ... }, 'event')`
+   * using the adapter's own typed connector subjects. This is kept adapter-specific to avoid
+   * complex generic type constraints when calling `createConnectorEventMapping` from a generic context.
+   */
+  protected abstract wireSdkEvents(): void;
+  /**
+   * Return the semantic subject spec for this adapter's connector namespace.
+   *
+   * Called once during `wireEvents()`. The returned subjects are used to subscribe
+   * to connector events and emit to global `agent.*` subjects.
+   * @returns Subject spec for this adapter's connector namespace
+   */
+  protected abstract getConnectorSubjects(): TSpec;
+  /**
+   * Extract plain text from an adapter-specific chunk event payload.
+   *
+   * - Anthropic: checks `delta.type === 'text_delta'` and returns `delta.text`
+   * - OpenAI: returns `choices[0]?.delta?.content ?? ''`
+   * @param payload - Raw chunk event payload (cast from the connector's chunk event type)
+   * @returns Plain text string, or empty string when the chunk carries no text content
+   */
+  protected abstract extractChunkText(payload: Record<string, unknown>): string;
+  /**
+   * Map an adapter-specific usage event payload to the shared `NormalizedCallUsage` format.
+   *
+   * - Anthropic: reads `cache_read_input_tokens`, `cache_creation_input_tokens`
+   * - OpenAI: reads `prompt_tokens_details.cached_tokens`, `completion_tokens_details.reasoning_tokens`
+   * @param payload - Raw usage event payload (cast from the connector's usage event type)
+   * @returns Normalized usage metrics ready for `trackUsage()`
+   */
+  protected abstract extractUsagePayload(payload: Record<string, unknown>): NormalizedCallUsage;
+  /**
+   * Emit the context window update after processing a usage event.
+   *
+   * Adapters differ in which fields provide the cached token count and the default
+   * max context window size. Called from `wireUsageEvents` after `trackUsage()`.
+   * @param payload - Raw usage event payload (same object passed to `extractUsagePayload`)
+   */
+  protected abstract emitUsageContextWindowUpdate(payload: Record<string, unknown>): Promise<void>;
+  /**
+   * Reserve a block index for a tool call from the tool_calls event.
+   *
+   * - Anthropic: returns `(tc as AnthropicToolCall).blockIndex` (provider-native; no counter mutation).
+   * - OpenAI: returns `this.getBlockIndex()` and increments the internal counter.
+   *
+   * Called once per tool call in `wireToolEvents` before emitting step.started.
+   * @param tc - The tool call entry from the tool_calls event payload
+   * @returns The block index to use for this tool call's step.started / step.finished pair
+   */
+  protected abstract reserveToolCallBlockIndex(tc: ToolCall): number;
+  /**
+   * Perform adapter-specific book-keeping after a tool call's step.started has been emitted.
+   *
+   * - Anthropic: calls `reconcileInternalBlockIndex(blockIndex)` to keep the internal
+   *   block index counter in sync with provider-native indices.
+   * - OpenAI: no-op (the counter was already incremented inside `reserveToolCallBlockIndex`).
+   * @param blockIndex - The block index that was just emitted for this tool call
+   */
+  protected abstract afterToolCallStepEmitted(blockIndex: number): void;
+  /**
+   * Return the fallback block index when `toolBlockIndexMap` has no entry for a toolCallId.
+   *
+   * Used only when a tool_completed event arrives without a matching tool_calls entry
+   * (out-of-order delivery or state mismatch).
+   *
+   * - Anthropic: `this.getBlockIndex()` (also increments the internal counter for monotonicity)
+   * - OpenAI: `-1` (sentinel indicating unknown index)
+   * @returns Fallback block index for unresolvable toolCallId map lookups
+   */
+  protected abstract getFallbackToolCompletedBlockIndex(): number;
+  /**
+   * Perform adapter-specific book-keeping after a tool_completed step.finished has been emitted.
+   *
+   * - Anthropic: calls `reconcileInternalBlockIndex(resolvedBlockIndex)`.
+   * - OpenAI: no-op.
+   * @param resolvedBlockIndex - The block index used for this tool's step.finished
+   */
+  protected abstract afterToolCompletedStepEmitted(resolvedBlockIndex: number): void;
+  /**
+   * Build the `SessionMessageBlock` for a reasoning step from the reasoning_complete payload.
+   *
+   * - Anthropic: `{ type: 'reasoning', content, metadata: { signature } }` when `signature` is set
+   * - OpenAI: `{ type: 'reasoning', content }` (no metadata)
+   * @param payload - Raw reasoning complete event payload (cast from the connector's event type)
+   * @returns A reasoning block suitable for `emitStepFinished`
+   */
+  protected abstract buildReasoningBlock(payload: Record<string, unknown>): SessionMessageBlock;
+  /**
+   * Register the tool approval RPC handler for this adapter's connector.
+   *
+   * Wires the adapter-scoped `tool_approval` subject to the global
+   * `AgentSubjects.toolApprove` via the adapter-specific `registerToolApprovalHandler`
+   * factory (generated by `createToolApprovalHandler`). Called during `wireEvents()`.
+   * @param connector - The adapter connector to register the tool approval handler on
+   */
+  protected abstract wireToolApprovalRpc(connector: TConnector): void;
+  /**
+   * Wire connector events to global agent.* subjects.
+   *
+   * Entry point called by `AIAgent.init()` after connector creation.
+   * Follows a two-tier fan-out pattern:
+   * 1. `wireSdkEvents()` — abstract, routes sdk.event to typed semantic subjects.
+   * 2. `wireSemanticEvents()` — shared, wires semantic subjects to global agent.* subjects.
+   * @param connector - The adapter connector to wire events from
+   */
+  protected wireEvents(connector: TConnector): void;
+  /**
+   * Wire semantic subjects to global agent.* subjects.
+   *
+   * Delegates to individual wire methods grouped by event category.
+   * @param connector - The adapter connector to subscribe on
+   * @param subjects - The adapter's connector subjects from `getConnectorSubjects()`
+   */
+  private wireSemanticEvents;
+  /**
+   * Wire message streaming and completion events.
+   *
+   * - `chunk` → `agent.message_delta` (adapter-specific text via `extractChunkText`)
+   * - `message_complete` → `agent.message` + step.started/step.finished for text content
+   * @param connector - The adapter connector to subscribe on
+   * @param subjects - The adapter's connector subjects
+   */
+  private wireMessageEvents;
+  /**
+   * Wire token usage tracking events.
+   *
+   * Delegates payload parsing to `extractUsagePayload` and context window emission
+   * to `emitUsageContextWindowUpdate` (both adapter-specific).
+   * @param connector - The adapter connector to subscribe on
+   * @param subjects - The adapter's connector subjects
+   */
+  private wireUsageEvents;
+  /**
+   * Wire tool lifecycle events (tool_calls, tool_started, tool_completed).
+   *
+   * - `tool_calls` → per-tool `agent.step.started` + `agent.tool.use`
+   * - `tool_started` → `agent.tool.started`
+   * - `tool_completed` → `agent.step.finished` + `agent.tool.completed`
+   * @param connector - The adapter connector to subscribe on
+   * @param subjects - The adapter's connector subjects
+   */
+  private wireToolEvents;
+  /**
+   * Wire reasoning streaming and completion events.
+   *
+   * - `reasoning_delta` → `agent.reasoning_delta`
+   * - `reasoning_complete` → `agent.reasoning` + step.started/step.finished
+   * @param connector - The adapter connector to subscribe on
+   * @param subjects - The adapter's connector subjects
+   */
+  private wireReasoningEvents;
+  /**
+   * Wire agent lifecycle events (agent_started, agent_complete, error).
+   *
+   * - `agent_started` → clears per-turn tool tracking and calls `emitStart()`
+   * - `agent_complete` → clears per-turn tool tracking
+   * - `error` → calls `emitError()` to stash error metadata for next `emitCompletion`
+   *
+   * Note: `agent_complete` emission is handled by `AIAgent` via `onMessageHandle()`
+   * when the connector calls `markCompleted()`. We subscribe only for state reset.
+   * @param connector - The adapter connector to subscribe on
+   * @param subjects - The adapter's connector subjects
+   */
+  private wireLifecycleEvents;
+}
+//#endregion
+export { type AgentCompleteEvent, AgentCompleteEventSchema, type AgentStartedEvent, AgentStartedEventSchema, type BaseSessionEmitEvent, BaseStreamAgent, BaseStreamConnector, type BaseStreamConnectorConfig, BaseStreamSession, type ErrorEvent, ErrorEventSchema, type HandleToolCallsCallbacks, MAX_TOOL_RESULT_CONTENT_CHARS, type MessageCompleteEvent, MessageCompleteEventSchema, type MessageToolCall, MessageToolCallSchema, type ReasoningCompleteEvent, ReasoningCompleteEventSchema, type ReasoningDeltaEvent, ReasoningDeltaEventSchema, type StreamAdapterSubjectSpec, type StreamConnectorSession, type StreamSdkEventEnvelope, type StreamSessionConfig, type StreamSessionTurnState, StreamSessionTurnStateSchema, type ToolCall, type ToolCallFunction, ToolCallFunctionSchema, type ToolCallPayload, ToolCallSchema, type ToolCallsEvent, ToolCallsEventSchema, type ToolCompletedEvent, ToolCompletedEventSchema, type ToolExecutionContextOverrides, type ToolLifecycleEmitter, type ToolResultBuilder, type ToolStartedEvent, ToolStartedEventSchema, type TurnStateChanged, TurnStateChangedSchema, applyApprovedArgs, boundToolResultContent, executeTool, extractToolCallPayload, filterToolsWithSchema, handleToolCalls, loadToolsFromRegistry, toGlobalToolApproval };