@salesforce/sfdx-agent-sdk 0.14.0 → 0.16.0

package/README.md

@@ -47,7 +47,8 @@ for await (const event of eventStream) {
     process.stdout.write(event.text);
   } else if (event.type === 'error') {
     console.error(event.error.message);
-    break;
+    // Don't break — the SDK invariant guarantees a synthetic
+    // `FinishEvent('error')` follows; the loop exits naturally next tick.
   }
 }
 
@@ -152,30 +153,33 @@ keeps unparameterized call sites working.
 
 A single conversation thread.
 
-| Method              | Signature                                                                             | Description                                                   |
-| ------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `getId`             | `() => string`                                                                        | Session/thread identifier.                                    |
-| `chat`              | `(message: string, options?: ChatOptions) => Promise<ChatStreamResult>`               | Send a message and stream the response.                       |
-| `submitToolResult`  | `(toolResult: ToolResultInfo) => Promise<ChatStreamResult>`                           | Return a consumer-executed tool result and resume the stream. |
-| `approveToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<ChatStreamResult>` | Approve a pending tool call.                                  |
-| `declineToolCall`   | `(toolCallId: string) => Promise<ChatStreamResult>`                                   | Decline a pending tool call.                                  |
-| `getMessageHistory` | `() => Promise<Message[]>`                                                            | Retrieve all messages in chronological order.                 |
-| `clearHistory`      | `() => Promise<void>`                                                                 | Delete all messages.                                          |
-| `addContext`        | `(message: string \| Message[]) => Promise<void>`                                     | Inject context without triggering an LLM response.            |
-| `subscribe`         | `(callback: (event: ChatEvent) => void) => void`                                      | Register a real-time event listener.                          |
-| `unsubscribe`       | `(callback: (event: ChatEvent) => void) => void`                                      | Remove a listener.                                            |
-| `onTelemetry`       | `(callback: TelemetryEventCallback) => Unsubscribe`                                   | Subscribe to telemetry scoped to this session.                |
-| `onLog`             | `(callback: (record: LogRecord) => void) => Unsubscribe`                              | Subscribe to logs scoped to this session.                     |
-| `dispose`           | `() => void`                                                                          | Release session-level event resources. Idempotent.            |
+| Method              | Signature                                                                 | Description                                                                                                                |
+| ------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `getId`             | `() => string`                                                            | Session/thread identifier.                                                                                                 |
+| `chat`              | `(message: string, options?: ChatOptions) => Promise<ChatStreamResult>`   | Send a message and stream the response. The returned `eventStream` is the single iterator for the entire chat turn.        |
+| `submitToolResult`  | `(toolResult: ToolResultInfo) => Promise<void>`                           | Return a consumer-executed tool result. Control message on the existing turn — post-resume events flow on the same stream. |
+| `approveToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<void>` | Approve a pending tool call. Control message on the existing turn — post-resume events flow on the same stream.            |
+| `declineToolCall`   | `(toolCallId: string) => Promise<void>`                                   | Decline a pending tool call. Control message on the existing turn — post-resume events flow on the same stream.            |
+| `getMessageHistory` | `() => Promise<Message[]>`                                                | Retrieve all messages in chronological order.                                                                              |
+| `clearHistory`      | `() => Promise<void>`                                                     | Delete all messages.                                                                                                       |
+| `getContextUsage`   | `() => ContextUsage`                                                      | Snapshot of how much of the model's context window the most recent turn used.                                              |
+| `addContext`        | `(message: string \| Message[]) => Promise<void>`                         | Inject context without triggering an LLM response.                                                                         |
+| `subscribe`         | `(callback: (event: ChatEvent) => void) => void`                          | Register a real-time event listener.                                                                                       |
+| `unsubscribe`       | `(callback: (event: ChatEvent) => void) => void`                          | Remove a listener.                                                                                                         |
+| `onTelemetry`       | `(callback: TelemetryEventCallback) => Unsubscribe`                       | Subscribe to telemetry scoped to this session.                                                                             |
+| `onLog`             | `(callback: (record: LogRecord) => void) => Unsubscribe`                  | Subscribe to logs scoped to this session.                                                                                  |
+| `dispose`           | `() => void`                                                              | Release session-level event resources. Idempotent.                                                                         |
 
 ### `ChatStreamResult`
 
-Returned by `chat()`, `submitToolResult()`, `approveToolCall()`, and `declineToolCall()`.
+Returned by `chat()`. The single `eventStream` covers the entire chat turn — including post-resume events from
+`submitToolResult` / `approveToolCall` / `declineToolCall`. Settle methods return `Promise<void>`; the consumer keeps
+iterating the same `eventStream` until it sees a terminal `finish` event.
 
-| Property      | Type                        | Description                             |
-| ------------- | --------------------------- | --------------------------------------- |
-| `eventStream` | `AsyncGenerator<ChatEvent>` | Full lifecycle event stream.            |
-| `textStream`  | `AsyncGenerator<string>`    | Convenience stream of text-only tokens. |
+| Property      | Type                        | Description                                                                  |
+| ------------- | --------------------------- | ---------------------------------------------------------------------------- |
+| `eventStream` | `AsyncGenerator<ChatEvent>` | Full lifecycle event stream for the turn (one stream per `chat()` call).     |
+| `textStream`  | `AsyncGenerator<string>`    | Convenience stream of text-only tokens, derived from the same `eventStream`. |
 
 ### `ChatEvent`
 
@@ -193,23 +197,28 @@ Discriminated union (`event.type`) of streaming events:
 | `step-finish`           | `stepIndex`, `finishReason`, `usage?`                                                   | Step completed with per-step token usage.                                                                                                                                                                                                                                                                                        |
 | `error`                 | `error`, `code?`                                                                        | Mid-stream error (yielded, not thrown).                                                                                                                                                                                                                                                                                          |
 | `finish`                | `finishReason`, `usage?`                                                                | Stream completed with aggregate token usage.                                                                                                                                                                                                                                                                                     |
-| `unmapped-chunk`        | `chunkType`, `rawChunk`                                                                 | Unrecognized harness event, preserved for observability.                                                                                                                                                                                                                                                                         |
+
+> **Diagnostic logging.** The `ChatEvent` union is the harness-agnostic public stream — it never carries
+> harness-internal chunk shapes. When a harness encounters a chunk type its adapter does not recognize (typically after
+> an upstream Mastra / Claude SDK upgrade), the chunk is skipped on the public stream and surfaced via `LogBus.debug`
+> with `chunkType` and `rawChunk` in the record's `context`. Subscribe via `manager.onLog` (or `agent.onLog` /
+> `session.onLog`) at debug level to observe these. Production consumers do not need to filter for unrecognized chunks.
 
 ### Configuration Types
 
 #### `AgentConfig`
 
-| Field           | Type               | Description                                                                                                                                                                                                                                                                                                                          |
-| --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `orgAlias?`     | `string`           | Salesforce org alias or username. Falls back to project/default org.                                                                                                                                                                                                                                                                 |
-| `modelId?`      | `ModelName`        | LLM model identifier (e.g. `'llmgateway__OpenAIGPT5'`).                                                                                                                                                                                                                                                                              |
-| `name?`         | `string`           | Human-readable agent name.                                                                                                                                                                                                                                                                                                           |
-| `description?`  | `string`           | Agent purpose description.                                                                                                                                                                                                                                                                                                           |
-| `instructions?` | `string`           | System instructions for the agent.                                                                                                                                                                                                                                                                                                   |
-| `tools?`        | `ToolDefinition[]` | Consumer-executed tool schemas.                                                                                                                                                                                                                                                                                                      |
-| `mcpServers?`   | `MCPConfiguration` | MCP server connections.                                                                                                                                                                                                                                                                                                              |
-| `skills?`       | `string[]`         | Each entry is either an individual skill folder (containing `SKILL.md`) or a parent folder containing skill subfolders. Relative and absolute paths supported; forms can be mixed in the same array.                                                                                                                                 |
-| `rules?`        | `string[]`         | Each entry is either an individual `.md` rule file or a directory of `.md` rule files (scanned one level deep, alphabetical, non-`.md` skipped). Bodies are composed verbatim into the agent's effective system prompt; YAML frontmatter is optional and stripped if present. Matches Claude Code's `.claude/rules/*.md` convention. |
+| Field           | Type                 | Description                                                                                                                                                                                                                                                                                                                          |
+| --------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `orgAlias?`     | `string`             | Salesforce org alias or username. Falls back to project/default org.                                                                                                                                                                                                                                                                 |
+| `modelId?`      | `ModelName \| Model` | LLM model selector. Pass a `ModelName` enum value for an in-tree model (e.g. `'llmgateway__OpenAIGPT5'`), or a pre-built `Model` instance to opt into a Bedrock-Anthropic Claude variant the SDK has not yet released — see `createClaudeModel(gatewayId, overrides)` in `@salesforce/llm-gateway-sdk`.                              |
+| `name?`         | `string`             | Human-readable agent name.                                                                                                                                                                                                                                                                                                           |
+| `description?`  | `string`             | Agent purpose description.                                                                                                                                                                                                                                                                                                           |
+| `instructions?` | `string`             | System instructions for the agent.                                                                                                                                                                                                                                                                                                   |
+| `tools?`        | `ToolDefinition[]`   | Consumer-executed tool schemas.                                                                                                                                                                                                                                                                                                      |
+| `mcpServers?`   | `MCPConfiguration`   | MCP server connections.                                                                                                                                                                                                                                                                                                              |
+| `skills?`       | `string[]`           | Each entry is either an individual skill folder (containing `SKILL.md`) or a parent folder containing skill subfolders. Relative and absolute paths supported; forms can be mixed in the same array.                                                                                                                                 |
+| `rules?`        | `string[]`           | Each entry is either an individual `.md` rule file or a directory of `.md` rule files (scanned one level deep, alphabetical, non-`.md` skipped). Bodies are composed verbatim into the agent's effective system prompt; YAML frontmatter is optional and stripped if present. Matches Claude Code's `.claude/rules/*.md` convention. |
 
 #### `StreamOptions`
 
@@ -241,6 +250,12 @@ type MCPRemoteServerConfig = {
   headers?: Record<string, string>;
   enabled?: boolean;
   timeout?: number;
+  reconnectionOptions?: {
+    maxRetries?: number;
+    initialReconnectionDelay?: number;
+    maxReconnectionDelay?: number;
+    reconnectionDelayGrowFactor?: number;
+  };
   alwaysLoad?: boolean;
 };
 ```
@@ -252,6 +267,14 @@ surfaces (≤ a few tools the model needs to find without prompting). The Claude
 `_meta['anthropic/alwaysLoad'] = true` on each forwarded tool (equivalent to `defer_loading: false` on the Claude API).
 The Mastra harness eager-loads all MCP tools regardless, so the flag is a no-op there.
 
+**`reconnectionOptions`** tunes the HTTP MCP transport's retry / backoff behavior. Forwarded to the underlying SDK
+transport on both harnesses (Claude's `@modelcontextprotocol/sdk` `StreamableHTTPClientTransport` and Mastra's
+`@mastra/mcp` `HttpServerDefinition`, which is itself typed off the same MCP SDK shape). Each field is optional;
+unspecified fields fall back to the MCP SDK's built-in defaults — `maxRetries: 2`, `initialReconnectionDelay: 1000` ms,
+`maxReconnectionDelay: 30000` ms, `reconnectionDelayGrowFactor: 1.5`. Partial overrides are merged with those defaults
+at the harness boundary so a consumer setting only `maxRetries` doesn't zero out the others. No-op for stdio servers —
+only `MCPRemoteServerConfig` carries it.
+
 #### `McpServerInfo`
 
 | Field          | Type                                                                     | Description                                                                                                                               |
@@ -375,6 +398,13 @@ type ImagePart = { type: 'image'; mimeType: 'image/png' | 'image/jpeg'; data: st
 type FilePart = { type: 'file'; mimeType: 'application/pdf'; data: string; fileName?: string };
 ```
 
+`createdAt` is **required-on-read, optional-on-write**:
+
+- Messages returned from `ChatSession.getMessageHistory()` always have `createdAt` populated, and the array is sorted
+  ascending by `createdAt`. Consumer code can read `msg.createdAt` directly.
+- Consumers constructing `Message` literals for `ChatSession.addContext()` may omit `createdAt`; the SDK backfills the
+  current time before forwarding to the harness. Pass an explicit value to override.
+
 #### Multimodal input
 
 `ChatSession.chat()` (and the harness `stream()` it delegates to) accept either a plain string or a `MessagePart[]`. Use
@@ -409,7 +439,8 @@ await session.chat([
   },
 ]);
 
-// Inject multimodal context before a chat turn
+// Inject multimodal context before a chat turn. `createdAt` is omitted —
+// the SDK backfills it before forwarding to the harness.
 await session.addContext([
   {
     id: 'ctx-screenshot',
@@ -455,9 +486,52 @@ type UsageMetadata = {
   cacheWriteInputTokens?: number;
 };
 
+type ContextUsage = {
+  /**
+   * Last per-step usage reading observed on this session. Pre-first-turn and
+   * immediately after `clearHistory()` this is `{}` (every token field undefined).
+   */
+  usage: UsageMetadata;
+  /** The model's total context-window size in tokens. Always populated. */
+  contextWindow: number;
+  /**
+   * `(usage.inputTokens + usage.cachedInputTokens + usage.cacheWriteInputTokens) / contextWindow`,
+   * clamped to [0, 1]. Cached prompt tokens are summed in because they occupy the
+   * model's context window — on Bedrock-Claude, the bulk of the prompt is reported
+   * via `cachedInputTokens` / `cacheWriteInputTokens`, not `inputTokens`. `undefined`
+   * when ALL three input-bearing fields are missing.
+   */
+  usedFraction: number | undefined;
+};
+
 type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'other';
 ```
 
+**Tracking context-window utilization.** `ChatSession.getContextUsage()` always returns a populated `ContextUsage` —
+even pre-first-turn, where `usage` is `{}` and `usedFraction` is `undefined`, but `contextWindow` is always available.
+Use it to decide when to compact a thread:
+
+```typescript
+const ctx = session.getContextUsage();
+if (ctx.usedFraction !== undefined && ctx.usedFraction > 0.8) {
+  await agent.compactChatSession(session.getId());
+}
+```
+
+Render a context-usage indicator that distinguishes "no reading yet" from a real measurement:
+
+```typescript
+const ctx = session.getContextUsage();
+const limit = ctx.contextWindow.toLocaleString(); // always available
+const used = ctx.usage.inputTokens?.toLocaleString() ?? '—';
+const pct = ctx.usedFraction !== undefined ? `${Math.round(ctx.usedFraction * 100)}%` : '—';
+return `${used} / ${limit} tokens (${pct})`;
+```
+
+The snapshot uses **last-step** semantics, not the per-turn billing aggregate — `finish.usage` sums all steps in a turn
+and double-counts persistent context, which is the wrong denominator for "how full is my context." For per-turn billing
+totals, subscribe to `chat-stream-completed` telemetry instead.
+
 ### Error Handling
 
 The SDK throws `AgentSDKError` for predictable not-found and compatibility conditions. Each error has a `type` property
@@ -489,17 +563,17 @@ try {
 
 #### Streaming method failures
 
-The four streaming methods on `ChatSession` — `chat()`, `submitToolResult()`, `approveToolCall()`, and
-`declineToolCall()` — share a single failure contract. Subscribers registered via `subscribe()` are guaranteed to
+`chat()` opens a turn; `submitToolResult()` / `approveToolCall()` / `declineToolCall()` are control messages on the
+existing turn. All four share a single failure contract. Subscribers registered via `subscribe()` are guaranteed to
 receive a terminal event for every turn:
 
-- **Pre-stream failure** (the harness rejects before producing a stream): subscribers receive an `ErrorEvent` followed
-  by a `FinishEvent(finishReason: 'error')`, and the returned promise then rejects with the original error. Wrap the
-  call in `try/catch` if you need to handle this in the caller.
-- **In-stream failure** (the stream yields an `error` event or the underlying generator throws): the `eventStream`
-  yields the `ErrorEvent` (synthesizing one from a thrown exception if needed) and, if no `FinishEvent` was already
-  emitted, appends a synthetic `FinishEvent(finishReason: 'error')` at the end. The returned promise resolves normally;
-  iterate the stream to observe the failure.
+- **Pre-stream failure** (the harness rejects before producing a stream, or a settle call rejects before it routes the
+  decision): subscribers receive an `ErrorEvent` followed by a `FinishEvent(finishReason: 'error')`, and the returned
+  promise then rejects with the original error. Wrap the call in `try/catch` if you need to handle this in the caller.
+- **In-stream failure** (the active `eventStream` yields an `error` event or the underlying generator throws): the
+  stream yields the `ErrorEvent` (synthesizing one from a thrown exception if needed) and, if no `FinishEvent` was
+  already emitted, appends a synthetic `FinishEvent(finishReason: 'error')` at the end. The originating `chat()` promise
+  resolves normally; iterate the stream to observe the failure.
 - **Calling a disposed session** throws `AgentSDKError('DISPOSED')` synchronously without notifying subscribers.
 
 ### MCP Server Configuration
@@ -542,99 +616,158 @@ reparsing namespaced tool names. `annotations` is `undefined` when the source di
 `requireToolApproval` accepts a `boolean` (`true` is shorthand for `'serial'`) or one of the mode strings exposed via
 the `ToolApprovalMode` type alias (`'serial' | 'batch'`):
 
-- **`'serial'`** (the safe default) — each stream surfaces one `tool-approval-request` at a time. The next request, if
-  any, appears on the continuation stream returned by `approveToolCall` / `declineToolCall`. Works with both consumer
-  iterator patterns below.
-- **`'batch'`** — when the model emits parallel `tool_use` blocks, all approval-requests surface on the same stream so
-  the consumer can render a batch-approval card. **Pattern A iterators only** — a `break`-on-first-approval loop will
-  miss the subsequent approvals and hang the chat. Opt into `'batch'` only after the consumer iterator collects all
-  approvals before settling.
+- **`'serial'`** (the safe default) — `tool-approval-request` events surface one at a time. The next request (if any)
+  arrives later on the same `eventStream` after the consumer settles the current one.
+- **`'batch'`** — when the model emits parallel `tool_use` blocks, all approval-requests for that batch surface on the
+  same `eventStream` together, so the consumer can render a batch-approval card. The consumer must gather all approvals
+  before settling — a `break`-on-first-approval loop will hang the turn because Mastra/Claude won't continue emitting
+  tool-results until the consumer has settled the entire batch.
 
 The SDK also exports `resolveToolApprovalMode(value)` — the canonical
 `boolean | ToolApprovalMode | undefined → ToolApprovalMode | undefined` normalizer harness implementations should use to
 dispatch (`undefined` / `false` → `undefined`, `true` → `'serial'`, strings pass through). Reject unknown strings via
 `throw` instead of reimplementing the boolean-vs-string branch — the helper's defensive throw catches `as any` consumers
-passing invalid values that would otherwise silently degrade to "approval gating on but no broker allocated."
+passing invalid values that would otherwise silently degrade to "approval gating on but no coordinator allocated."
+
+#### Single stream per turn
+
+Issue [#529](https://github.com/forcedotcom/agentic-dx/issues/529) settled the harness contract: **one `eventStream` per
+chat turn.** Settle calls (`approveToolCall` / `declineToolCall` / `submitToolResult`) return `Promise<void>` and behave
+as control messages on the existing turn; the post-resume events (`tool-result`, follow-up `text-delta`, `step-finish`,
+terminal `finish`) flow through the **same** `eventStream` the `chat()` call returned. The consumer should iterate that
+one stream until it sees a terminal `finish` event, calling `approveToolCall` / `declineToolCall` / `submitToolResult`
+in-line as approval-requests / consumer-tool-calls arrive.
 
-> **Glossary:** _Pattern A_ = "collect-all-then-settle" (iterate until natural park, gather all approval-requests, then
-> call `approveToolCall`/`declineToolCall`). _Pattern B_ = "return-on-first-approval" (settle the first approval
-> mid-iteration, then re-iterate the continuation stream). `'serial'` works with either; `'batch'` requires Pattern A.
+#### Pattern: settle in-line, continue iterating
 
-#### Pattern B — return on first approval (works with `'serial'`)
+The same shape works for `'serial'` and `'batch'` mode:
 
 ```typescript
 const { eventStream } = await session.chat('Run the deployment', {
-  requireToolApproval: true, // or 'serial'
+  requireToolApproval: true, // or 'serial' / 'batch'
 });
 
 for await (const event of eventStream) {
   if (event.type === 'tool-approval-request') {
     const approved = await promptUser(event);
-    const continuation = approved
-      ? await session.approveToolCall(event.toolCall.toolCallId)
-      : await session.declineToolCall(event.toolCall.toolCallId);
-    for await (const e of continuation.eventStream) {
-      // process continuation
+    if (approved) {
+      await session.approveToolCall(event.toolCall.toolCallId);
+    } else {
+      await session.declineToolCall(event.toolCall.toolCallId);
     }
-    break; // safe: serial mode surfaces at most one approval per stream
+    // Do NOT break — keep iterating; tool-result and follow-up text arrive on the same stream.
+  } else if (event.type === 'tool-call' && event.serverName === undefined && isConsumerTool(event.toolName)) {
+    // Consumer-executed tool: run locally, return the result via submitToolResult.
+    const result = await runLocally(event.args);
+    await session.submitToolResult({
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      result,
+    });
+  } else if (event.type === 'text-delta') {
+    process.stdout.write(event.text);
+  } else if (event.type === 'finish') {
+    // Don't break on `'error'` directly — the SDK invariant guarantees an
+    // `error` event is followed by a synthetic `FinishEvent('error')` so
+    // the loop exits naturally on the next iteration. Breaking on `error`
+    // would finalize the iterator before the synthetic `finish` lands and
+    // bypass any per-turn cleanup the harness wires onto the source's
+    // close/return path.
+    break;
   }
 }
 ```
 
-#### Pattern A — collect all approvals, then settle (required for `'batch'`)
+#### Pattern variant: batch-collect approvals before settling
+
+Same single-stream loop, just gather the batch before deciding (useful for "approve these N tools?" UI cards under
+`requireToolApproval: 'batch'`):
 
 ```typescript
 const { eventStream } = await session.chat('Run the deployment', {
   requireToolApproval: 'batch',
 });
 
-const requests: ToolApprovalRequestEvent[] = [];
+const pendingBatch: ToolApprovalRequestEvent[] = [];
+
 for await (const event of eventStream) {
   if (event.type === 'tool-approval-request') {
-    requests.push(event); // do NOT break — collect the whole parallel batch
+    pendingBatch.push(event);
+    // Heuristic: settle the batch on a quiet window OR after the expected count.
+    // Don't break — the harness needs us to settle so it can continue.
+    continue;
   }
-  if (event.type === 'finish' || event.type === 'error') break;
-}
-
-// Render a batch-approval card; settle each decision.
-const decisions = await promptUserForBatch(requests);
-let continuation: ChatStreamResult | undefined;
-for (const event of requests) {
-  continuation = decisions.get(event.toolCall.toolCallId)
-    ? await session.approveToolCall(event.toolCall.toolCallId)
-    : await session.declineToolCall(event.toolCall.toolCallId);
-}
-if (continuation) {
-  for await (const e of continuation.eventStream) {
-    // process the model's follow-up turn
+  if (event.type === 'tool-call') {
+    // The harness emits `tool-approval-request` BEFORE `tool-call` in batch mode.
+    // Once we see a tool-call, the batch for this assistant message is complete.
+    if (pendingBatch.length > 0) {
+      const decisions = await promptUserForBatch(pendingBatch);
+      await Promise.all(
+        pendingBatch.map((req) =>
+          decisions.get(req.toolCall.toolCallId)
+            ? session.approveToolCall(req.toolCall.toolCallId)
+            : session.declineToolCall(req.toolCall.toolCallId),
+        ),
+      );
+      pendingBatch.length = 0;
+    }
+  } else if (event.type === 'text-delta') {
+    process.stdout.write(event.text);
+  } else if (event.type === 'finish') {
+    // Don't break on `'error'` directly — the SDK invariant guarantees an
+    // `error` event is followed by a synthetic `FinishEvent('error')` so
+    // the loop exits naturally on the next iteration. Breaking on `error`
+    // would finalize the iterator before the synthetic `finish` lands and
+    // bypass any per-turn cleanup the harness wires onto the source's
+    // close/return path.
+    break;
   }
 }
 ```
 
-#### `textStream` and `'batch'` mode
-
-`ChatStreamResult.textStream` is empty on the initial stream when `requireToolApproval: 'batch'` surfaces approval
-requests — the model emitted `tool_use` blocks, not text. Read text deltas from the continuation stream returned by
-`approveToolCall` / `declineToolCall` (the model's follow-up turn after tool execution).
+> **AsyncIterator gotcha:** the `for await` loop is the supported way to drain `eventStream`. If you instead drive the
+> iterator manually (`iter.next()`), call **at most one** `next()` at a time and `await` the result before the next
+> call. Calling `iter.next()` twice without awaiting the first orphans the first request — JS settles `.next()` calls
+> FIFO, so the next yielded value satisfies the orphaned request and is invisible to the caller. Stick to `for await`
+> unless you have a specific reason not to.
 
 ### Consumer-Executed Tools
 
+Tools declared via `AgentConfig.tools` (no `execute` function) run on the consumer side: the model emits a `tool-call`
+event, the consumer runs the tool locally, then calls `session.submitToolResult(...)` to feed the result back.
+`submitToolResult` returns `Promise<void>`; the model's follow-up turn (and any subsequent `tool-call`s) flows through
+the same `eventStream`:
+
 ```typescript
+const { eventStream } = await session.chat('Look up the customer record for tenant T-42.');
+
 for await (const event of eventStream) {
-  if (event.type === 'tool-call' && event.toolName === 'my-tool') {
+  if (event.type === 'tool-call' && event.toolName === 'lookup_customer') {
     const result = await runLocally(event.args);
-    const continuation = await session.submitToolResult({
+    await session.submitToolResult({
       toolCallId: event.toolCallId,
       toolName: event.toolName,
       result,
     });
-    for await (const e of continuation.eventStream) {
-      // process continuation
-    }
+    // Do NOT break — the model's follow-up turn (text, more tool-calls, finish) arrives on the same stream.
+  } else if (event.type === 'text-delta') {
+    process.stdout.write(event.text);
+  } else if (event.type === 'finish') {
+    // Don't break on `'error'` directly — the SDK invariant guarantees an
+    // `error` event is followed by a synthetic `FinishEvent('error')` so
+    // the loop exits naturally on the next iteration. Breaking on `error`
+    // would finalize the iterator before the synthetic `finish` lands and
+    // bypass any per-turn cleanup the harness wires onto the source's
+    // close/return path.
+    break;
   }
 }
 ```
 
+When `requireToolApproval: true` is also set, consumer-executed tools bypass the approval gate by construction (per
+`StreamOptions.requireToolApproval` JSDoc). They surface as a normal `tool-call` event without a preceding
+`tool-approval-request`. Built-in / MCP tools still gate normally.
+
 ### Connectivity Resolution
 
 #### `ResolvedConnectivity`
@@ -669,7 +802,11 @@ Returns `true` if the URL matches a Salesforce Hosted MCP Server endpoint (prod,
 
 ### Re-exported from `@salesforce/llm-gateway-sdk`
 
-- `ModelName` — enum of supported model identifiers
+- `Model` — abstract base class. Returned by `Models.getByName(...)` and accepted as an `AgentConfig.modelId` value.
+- `ModelName` — enum of in-tree model identifiers.
+- `createClaudeModel(gatewayId, overrides?)` — escape-hatch factory for opting into a Bedrock-Anthropic Claude variant
+  the SDK has not released yet (`AgentConfig.modelId` accepts the returned instance directly).
+- `ClaudeModelOverrides` — optional caps for `createClaudeModel`.
 - `SfApiEnv` — Salesforce API environment enum (`dev`, `perf`, `prod`, `stage`, `test`)
 - `inferSfApiEnv(instanceUrl, options?)` — maps an instance URL to a `SfApiEnv`. Re-exported from
   `@salesforce/agentic-common` for consumers that need the mapping without an `OrgConnection` (e.g. building a
@@ -768,15 +905,33 @@ The SDK ships no harness implementation. Consumers pick one by passing a `Harnes
 [`@salesforce/sfdx-agent-harness-mastra`](../sfdx-agent-harness-mastra); additional harnesses can ship as independent
 npm packages that depend on this SDK as a `peerDependency`.
 
-Harness authors implement two interfaces and can compose one helper class, all exported from this package:
-
-| Export                        | Role                                                                                                                                                                                                                                  |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `HarnessFactory<H>`           | Construct a harness of type `H` bound to a storage root. Declares `harnessId` and `protocolVersion`. Default `H = AgentHarness`.                                                                                                      |
-| `AgentHarness`                | Runtime contract: agent / thread / stream / tool / message lifecycle. Declares its own `harnessId` and `protocolVersion`.                                                                                                             |
-| `SUPPORTED_PROTOCOL_VERSIONS` | Readonly list of harness protocol versions this SDK accepts. `createAgentManager` checks both the factory and the constructed harness.                                                                                                |
-| `HarnessBusOwner`             | Composition helper owning telemetry + log buses with `dispose()` semantics. Reuse it instead of reimplementing bus plumbing.                                                                                                          |
-| `lowerStreamInput`            | Validates a `MessagePart[]` and lowers each input part to your runtime's content-block shape. Use it in `stream()` so multimodal caps and `MULTIMODAL_NOT_SUPPORTED` / `INVALID_MESSAGE_CONTENT` semantics match every other harness. |
+### Two import surfaces
+
+This package publishes two ESM entry points:
+
+- **`@salesforce/sfdx-agent-sdk`** — consumer surface. Everything an application calling `createAgentManager` needs:
+  `Agent`, `ChatSession`, `ChatEvent`, `MessagePart`, `AgentConfig`, `AgentSDKError`, etc. The harness contract
+  interfaces (`AgentHarness`, `HarnessFactory`, `WithAgentConfig`, `ConfigOf`) also appear here as **type-only**
+  references so consumer code can write `AgentManager<H extends AgentHarness>` without reaching into the
+  harness-implementation surface.
+- **`@salesforce/sfdx-agent-sdk/harness`** — harness-implementation surface. Harness authors import the contract types
+  and the helpers from here. Consumer applications cannot reach these symbols from the bare specifier — the bundler / TS
+  resolver errors at the import site, which is the right outcome for any consumer who reaches for a primitive they don't
+  need.
+
+> **Build-tool requirement:** the `/harness` subpath is resolved via the `package.json` `exports` field, which requires
+> `moduleResolution: "node16" | "nodenext" | "bundler"` in `tsconfig.json`. Legacy `"node"` resolution silently won't
+> see the subpath. Modern bundlers (Vite, esbuild, Webpack 5+, tsup, Rollup with `@rollup/plugin-node-resolve` v15+)
+> resolve it natively. This is a harness-author concern only; consumer applications never touch the subpath.
+
+| Export                        | Surface                                     | Role                                                                                                                                                                                                                                    |
+| ----------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `HarnessFactory<H>`           | Type only on bare; value+type on `/harness` | Construct a harness of type `H` bound to a storage root. Declares `harnessId` and `protocolVersion`. Default `H = AgentHarness`.                                                                                                        |
+| `AgentHarness`                | Type only on bare; type on `/harness`       | Runtime contract: agent / thread / stream / tool / message lifecycle. Declares its own `harnessId` and `protocolVersion`.                                                                                                               |
+| `SUPPORTED_PROTOCOL_VERSIONS` | `/harness` only                             | Readonly list of harness protocol versions this SDK accepts. `createAgentManager` checks both the factory and the constructed harness.                                                                                                  |
+| `HarnessBusOwner`             | `/harness` only                             | Composition helper owning telemetry + log buses with `dispose()` semantics. Reuse it instead of reimplementing bus plumbing.                                                                                                            |
+| `lowerStreamInput`            | `/harness` only                             | Validates a `MessagePart[]` and lowers each input part to your runtime's content-block shape. Use it in `stream()` so multimodal caps and `MULTIMODAL_NOT_SUPPORTED` / `INVALID_MESSAGE_CONTENT` semantics match every other harness.   |
+| `GenSink<T>`                  | `/harness` only                             | Buffered async-generator wrapper for routing `ChatEvent`s to a consumer's `ChatStreamResult.eventStream`. Single-iteration: calling `generator()` twice throws — sinks have one waiter slot and one buffer, two iterators race on both. |
 
 Minimal skeleton:
 
@@ -786,7 +941,7 @@ import {
   type HarnessFactory,
   HarnessBusOwner,
   SUPPORTED_PROTOCOL_VERSIONS,
-} from '@salesforce/sfdx-agent-sdk';
+} from '@salesforce/sfdx-agent-sdk/harness';
 
 class MyHarness implements AgentHarness {
   readonly harnessId = 'my-harness';

package/dist/agent-connectivity-resolver.d.ts

@@ -1,4 +1,4 @@
-import { type JSONWebToken, type LLMGatewayClient, type LLMGatewayClientFactory } from '@salesforce/llm-gateway-sdk';
+import { Model, type JSONWebToken, type LLMGatewayClient, type LLMGatewayClientFactory } from '@salesforce/llm-gateway-sdk';
 import { type OrgConnection, type OrgConnectionFactory } from '@salesforce/agentic-common';
 import type { AgentConfig } from './harness/harness-config.js';
 /**
@@ -60,3 +60,18 @@ export declare class DefaultAgentConnectivityResolver implements AgentConnectivi
      */
     resolve(projectRoot: string, config: AgentConfig): Promise<ResolvedConnectivity>;
 }
+/**
+ * Resolves an `AgentConfig.modelId` value (which may be a {@link ModelName} enum value, a
+ * pre-built {@link Model} instance, or `undefined`) to a concrete {@link Model}.
+ *
+ * The enum branch goes through the strict {@link Models.getByName} registry; the live
+ * instance branch passes the consumer-built model through unchanged. A persisted-and-restored
+ * `Model` instance arrives here as a plain object (the JSON round-trip drops its prototype),
+ * and is rehydrated via {@link createClaudeModel} for Bedrock-Anthropic Claude variants — the
+ * single use case the consumer-built escape hatch was added for. Any other persisted shape is
+ * a programming error and throws.
+ *
+ * Exported for use by `Agent.updateAgentConfig`, which performs the same resolution when
+ * comparing previous and next models without re-running the full connectivity resolver.
+ */
+export declare function resolveAgentConfigModel(modelId: AgentConfig['modelId']): Model;