@salesforce/sfdx-agent-sdk 0.12.0 → 0.14.0

package/README.md

@@ -181,19 +181,19 @@ Returned by `chat()`, `submitToolResult()`, `approveToolCall()`, and `declineToo
 
 Discriminated union (`event.type`) of streaming events:
 
-| Type                    | Key Fields                                                                    | Description                                                                                                                                                                           |
-| ----------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `start`                 | —                                                                             | Stream has begun.                                                                                                                                                                     |
-| `text-delta`            | `text`                                                                        | Incremental response text.                                                                                                                                                            |
-| `reasoning-delta`       | `text`                                                                        | Chain-of-thought fragment.                                                                                                                                                            |
-| `tool-call`             | `toolCallId`, `toolName`, `args`, `annotations?`, `serverName?`               | Tool invocation. `annotations` is the MCP-spec hints (`readOnlyHint`, `destructiveHint`, …) when the source declared them; `serverName` is set when the tool came from an MCP server. |
-| `tool-approval-request` | `toolCall: ToolCallInfo`, `annotations?`, `serverName?`                       | Engine requests approval before executing a tool. Same `annotations` / `serverName` semantics as `tool-call`.                                                                         |
-| `tool-result`           | `toolCallId`, `toolName`, `result`, `isError?`, `annotations?`, `serverName?` | Tool execution completed. Same `annotations` / `serverName` semantics as `tool-call`.                                                                                                 |
-| `step-start`            | `stepIndex`                                                                   | New LLM invocation step began.                                                                                                                                                        |
-| `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.                                                                                                                              |
+| Type                    | Key Fields                                                                              | Description                                                                                                                                                                                                                                                                                                                      |
+| ----------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start`                 | —                                                                                       | Stream has begun.                                                                                                                                                                                                                                                                                                                |
+| `text-delta`            | `text`                                                                                  | Incremental response text.                                                                                                                                                                                                                                                                                                       |
+| `reasoning-delta`       | `text`                                                                                  | Chain-of-thought fragment.                                                                                                                                                                                                                                                                                                       |
+| `tool-call`             | `toolCallId`, `toolName`, `args`, `annotations?`, `serverName?`                         | Tool invocation. `annotations` is the MCP-spec hints (`readOnlyHint`, `destructiveHint`, …) when the source declared them; `serverName` is set when the tool came from an MCP server.                                                                                                                                            |
+| `tool-approval-request` | `toolCall: ToolCallInfo`, `annotations?`, `serverName?`                                 | Engine requests approval before executing a tool. Same `annotations` / `serverName` semantics as `tool-call`.                                                                                                                                                                                                                    |
+| `tool-result`           | `toolCallId`, `toolName`, `result`, `isError?`, `error?`, `annotations?`, `serverName?` | Tool execution completed. `error` is present when `isError` is true (best-effort: harnesses may synthesize an `Error` from a string payload, so `error.stack` is not guaranteed to point at the tool's throw site; the field may be absent on empty error payloads). Same `annotations` / `serverName` semantics as `tool-call`. |
+| `step-start`            | `stepIndex`                                                                             | New LLM invocation step began.                                                                                                                                                                                                                                                                                                   |
+| `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.                                                                                                                                                                                                                                                                         |
 
 ### Configuration Types
 
@@ -213,10 +213,10 @@ Discriminated union (`event.type`) of streaming events:
 
 #### `StreamOptions`
 
-| Field                  | Type          | Description                                                              |
-| ---------------------- | ------------- | ------------------------------------------------------------------------ |
-| `abortSignal?`         | `AbortSignal` | Abort the streaming operation.                                           |
-| `requireToolApproval?` | `boolean`     | When `true`, emits `tool-approval-request` before native tool execution. |
+| Field                  | Type                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `abortSignal?`         | `AbortSignal`                    | Abort the streaming operation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `requireToolApproval?` | `boolean \| 'serial' \| 'batch'` | Gates native tool execution behind a `tool-approval-request` event. `true` / `'serial'` (the default) emits one approval per stream — safe for any iterator pattern. `'batch'` opts into parallel-approval UX: when the model emits parallel `tool_use` blocks, all approvals surface on the same stream so the consumer can render a batch approval card. **`'batch'` requires Pattern A iterators** (collect-all-approvals-then-settle); a `break`-on-first-approval loop will hang. See "Tool Approval Flow" below. |
 
 #### `MCPConfiguration`
 
@@ -231,6 +231,7 @@ type MCPStdioServerConfig = {
   env?: Record<string, string>;
   enabled?: boolean;
   timeout?: number;
+  alwaysLoad?: boolean;
 };
 
 // Remote server (HTTP/SSE)
@@ -240,9 +241,17 @@ type MCPRemoteServerConfig = {
   headers?: Record<string, string>;
   enabled?: boolean;
   timeout?: number;
+  alwaysLoad?: boolean;
 };
 ```
 
+**`alwaysLoad`** opts a server's tool surface out of the active runtime's tool-search deferral. Default (`undefined` /
+`false`) lets the runtime defer the server's tools behind a tool-search round-trip when the global tool surface is
+large; `true` registers every tool from this server with the model up-front. Useful for small, discovery-critical
+surfaces (≤ a few tools the model needs to find without prompting). The Claude harness honors the flag by stamping
+`_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.
+
 #### `McpServerInfo`
 
 | Field          | Type                                                                     | Description                                                                                                                               |
@@ -269,16 +278,25 @@ event so subscribers can route on it without pattern-matching `error.message`.
 
 #### `McpToolInfo`
 
-Runtime metadata for a single MCP-discovered tool. Optional fields are populated when the underlying harness can supply
-them from its MCP client; harnesses whose runtime does not expose a given field leave it `undefined`. Consumers must
-treat every field except `name` as optional.
-
-| Field          | Type                                        | Description                                                                                          |
-| -------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `name`         | `string`                                    | Tool name as exposed to the LLM, including any harness-applied namespacing.                          |
-| `description?` | `string`                                    | Human-readable description of what the tool does.                                                    |
-| `inputSchema?` | `Record<string, unknown>`                   | Tool input parameters as a [**JSON Schema**](https://json-schema.org/) object (the MCP wire format). |
-| `annotations?` | [`McpToolAnnotations`](#mcptoolannotations) | Behavioral / UI-presentation hints declared by the MCP server.                                       |
+Runtime metadata for a single MCP-discovered tool. The required fields (`name`, `serverName`, `toolName`) are populated
+by every harness; the optional fields are filled when the underlying harness can supply them from its MCP client and
+left `undefined` otherwise. Consumers must treat every optional field as `undefined`-tolerant.
+
+| Field          | Type                                        | Description                                                                                                                                                                                  |
+| -------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`         | `string`                                    | Tool name as exposed to the LLM, including any harness-applied namespacing. **Format is harness-specific** — Mastra: `${server}_${tool}`; Claude: `mcp__${server}__${tool}`. See note below. |
+| `serverName`   | `string`                                    | Logical MCP server name as configured in `AgentConfig.mcpServers`. Use together with `toolName` for harness-agnostic tool lookup.                                                            |
+| `toolName`     | `string`                                    | Bare tool name as declared by the upstream MCP server's `tools/list` response (the un-namespaced form). Identical across harnesses for the same server.                                      |
+| `description?` | `string`                                    | Human-readable description of what the tool does.                                                                                                                                            |
+| `inputSchema?` | `Record<string, unknown>`                   | Tool input parameters as a [**JSON Schema**](https://json-schema.org/) object (the MCP wire format).                                                                                         |
+| `annotations?` | [`McpToolAnnotations`](#mcptoolannotations) | Behavioral / UI-presentation hints declared by the MCP server.                                                                                                                               |
+
+**`name` is harness-specific; use `(serverName, toolName)` for cross-harness lookups.** `name` round-trips against
+`tool-call` / `tool-result` / `tool-approval-request` events on the same harness, so consumers wiring UI to a single
+harness can match on it. Code that needs to identify a tool across both Mastra and Claude — or against
+`getMcpServerInfo()` regardless of which harness was constructed — must match on the `(serverName, toolName)` pair.
+Don't regex `name` to recover the components, and don't try to construct it portably (no helper produces the right
+format on every harness).
 
 **`inputSchema` is a JSON Schema object, not a Zod schema.** It is typed as `Record<string, unknown>` so this package
 incurs no `zod` or `@types/json-schema` dependency. If you need a Zod schema at runtime, convert with a library such as
@@ -335,6 +353,8 @@ type ToolResultInfo = {
   toolName: string;
   result: unknown;
   isError?: boolean;
+  /** Present when isError is true. Best-effort: error.stack is not guaranteed to point at the tool's throw site. */
+  error?: Error;
 };
 ```
 
@@ -348,9 +368,80 @@ type Message = {
   createdAt?: Date;
 };
 
-type MessagePart = TextPart | ReasoningPart | ToolCallPart | ToolResultPart;
+type MessagePart = TextPart | ReasoningPart | ToolCallPart | ToolResultPart | ImagePart | FilePart;
+
+// Multimodal input parts. `data` is base64-encoded bytes with no `data:` URI prefix.
+type ImagePart = { type: 'image'; mimeType: 'image/png' | 'image/jpeg'; data: string; fileName?: string };
+type FilePart = { type: 'file'; mimeType: 'application/pdf'; data: string; fileName?: string };
+```
+
+#### Multimodal input
+
+`ChatSession.chat()` (and the harness `stream()` it delegates to) accept either a plain string or a `MessagePart[]`. Use
+the array form to send images or PDFs alongside text:
+
+```typescript
+import { readFileSync } from 'node:fs';
+import { AgentSDKError, AgentSDKErrorType } from '@salesforce/sfdx-agent-sdk';
+
+// Attach a PNG image alongside a text prompt
+const { eventStream } = await session.chat([
+  { type: 'text', text: 'What does this screenshot show?' },
+  {
+    type: 'image',
+    mimeType: 'image/png',
+    data: readFileSync('screenshot.png').toString('base64'),
+    fileName: 'screenshot.png',
+  },
+]);
+for await (const event of eventStream) {
+  if (event.type === 'text-delta') process.stdout.write(event.text);
+}
+
+// Attach a PDF
+await session.chat([
+  { type: 'text', text: 'Summarise the key findings in this report.' },
+  {
+    type: 'file',
+    mimeType: 'application/pdf',
+    data: readFileSync('report.pdf').toString('base64'),
+    fileName: 'q1-report.pdf',
+  },
+]);
+
+// Inject multimodal context before a chat turn
+await session.addContext([
+  {
+    id: 'ctx-screenshot',
+    role: 'user',
+    content: [
+      { type: 'text', text: 'Reference screenshot from the failing test run:' },
+      { type: 'image', mimeType: 'image/png', data: readFileSync('failure.png').toString('base64') },
+    ],
+  },
+]);
+await session.chat('What component is throwing the null pointer?');
+
+// Handle pre-stream validation errors
+try {
+  await session.chat([{ type: 'image', mimeType: 'image/png', data: base64Png }]);
+} catch (err) {
+  if (err instanceof AgentSDKError) {
+    if (err.type === AgentSDKErrorType.MULTIMODAL_NOT_SUPPORTED) {
+      // Model does not support file attachments, or the file violates a per-model cap
+      // (unsupported format, too large, too many files).
+    }
+    if (err.type === AgentSDKErrorType.INVALID_MESSAGE_CONTENT) {
+      // A part has an invalid type for user input (e.g. a bare tool-result part).
+    }
+  }
+}
 ```
 
+Only input parts (`text`, `image`, `file`) are valid — passing `tool-call` / `tool-result` parts is a programmer error.
+Validation runs before the stream is opened: callers never receive a partial stream followed by an error. The per-model
+formats and caps come from `Model.supportedFormats`, so a file is accepted or rejected identically across harnesses.
+
 ### Usage & Finish Types
 
 ```typescript
@@ -360,6 +451,8 @@ type UsageMetadata = {
   totalTokens?: number;
   reasoningTokens?: number;
   cachedInputTokens?: number;
+  /** Input tokens written to the provider cache. */
+  cacheWriteInputTokens?: number;
 };
 
 type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'other';
@@ -370,15 +463,17 @@ type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error
 The SDK throws `AgentSDKError` for predictable not-found and compatibility conditions. Each error has a `type` property
 from `AgentSDKErrorType`:
 
-| Type                     | Thrown By                                                                                                                                                                   |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AGENT_NOT_FOUND`        | `AgentManager.getAgent()`, `AgentManager.destroyAgent()`                                                                                                                    |
-| `CHAT_SESSION_NOT_FOUND` | `Agent.getChatSession()`, `Agent.destroyChatSession()`, `Agent.cloneChatSession()`, `Agent.compactChatSession()`                                                            |
-| `COMPACTION_FAILED`      | `Agent.compactChatSession()` when the harness's underlying summarization call rejects. The original error is attached as `cause`; the source session is left intact.        |
-| `DISPOSED`               | `Agent` and `ChatSession` methods called after the owner has been destroyed                                                                                                 |
-| `INCOMPATIBLE_HARNESS`   | `createAgentManager()` when the factory advertises an unsupported `protocolVersion`, or the constructed harness reports a `protocolVersion` that differs from the factory's |
-| `MCP_SERVER_DISABLED`    | `Agent.reconnectMcpServer()` when the named server is configured with `enabled: false`                                                                                      |
-| `MCP_SERVER_NOT_FOUND`   | `Agent.reconnectMcpServer()` when the server name is not in the agent's `mcpServers` config                                                                                 |
+| Type                       | Thrown By                                                                                                                                                                   |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AGENT_NOT_FOUND`          | `AgentManager.getAgent()`, `AgentManager.destroyAgent()`                                                                                                                    |
+| `CHAT_SESSION_NOT_FOUND`   | `Agent.getChatSession()`, `Agent.destroyChatSession()`, `Agent.cloneChatSession()`, `Agent.compactChatSession()`                                                            |
+| `COMPACTION_FAILED`        | `Agent.compactChatSession()` when the harness's underlying summarization call rejects. The original error is attached as `cause`; the source session is left intact.        |
+| `DISPOSED`                 | `Agent` and `ChatSession` methods called after the owner has been destroyed                                                                                                 |
+| `INCOMPATIBLE_HARNESS`     | `createAgentManager()` when the factory advertises an unsupported `protocolVersion`, or the constructed harness reports a `protocolVersion` that differs from the factory's |
+| `INVALID_MESSAGE_CONTENT`  | `ChatSession.chat()` / harness `stream()` when a message part is not valid as input (a `tool-call`/`tool-result` part, or non-base64-string file data)                      |
+| `MCP_SERVER_DISABLED`      | `Agent.reconnectMcpServer()` when the named server is configured with `enabled: false`                                                                                      |
+| `MCP_SERVER_NOT_FOUND`     | `Agent.reconnectMcpServer()` when the server name is not in the agent's `mcpServers` config                                                                                 |
+| `MULTIMODAL_NOT_SUPPORTED` | `ChatSession.chat()` / harness `stream()` when a file fails pre-stream capability validation (unsupported format, too large, or too many files)                             |
 
 ```typescript
 import { AgentSDKError, AgentSDKErrorType } from '@salesforce/sfdx-agent-sdk';
@@ -444,33 +539,84 @@ consumers can branch on tool hints (e.g. auto-approve `readOnlyHint`) or group b
 reparsing namespaced tool names. `annotations` is `undefined` when the source did not declare them (per the MCP spec);
 `serverName` is `undefined` when the tool is not from an MCP server.
 
+`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.
+
+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."
+
+> **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 B — return on first approval (works with `'serial'`)
+
 ```typescript
 const { eventStream } = await session.chat('Run the deployment', {
-  requireToolApproval: true,
+  requireToolApproval: true, // or 'serial'
 });
 
 for await (const event of eventStream) {
   if (event.type === 'tool-approval-request') {
-    if (event.annotations?.readOnlyHint) {
-      // Safe read — auto-approve.
-      const continuation = await session.approveToolCall(event.toolCall.toolCallId);
-      for await (const e of continuation.eventStream) {
-        // process continuation
-      }
-    } else {
-      // Route to the user; group/label by event.serverName when set.
-      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
-      }
+    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
     }
+    break; // safe: serial mode surfaces at most one approval per stream
+  }
+}
+```
+
+#### Pattern A — collect all approvals, then settle (required for `'batch'`)
+
+```typescript
+const { eventStream } = await session.chat('Run the deployment', {
+  requireToolApproval: 'batch',
+});
+
+const requests: ToolApprovalRequestEvent[] = [];
+for await (const event of eventStream) {
+  if (event.type === 'tool-approval-request') {
+    requests.push(event); // do NOT break — collect the whole parallel batch
+  }
+  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
   }
 }
 ```
 
+#### `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).
+
 ### Consumer-Executed Tools
 
 ```typescript
@@ -624,12 +770,13 @@ 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.           |
+| 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. |
 
 Minimal skeleton:
 
@@ -716,7 +863,7 @@ All variants share `{ type: <discriminant>, timestamp: Date }` plus the fields b
 | `chat-stream-completed`          | `agentId`, `threadId`, `durationMs`, `usage?`                                                                     |
 | `chat-stream-error`              | `agentId`, `threadId`, `durationMs`, `error`                                                                      |
 | `tool-execution-started`         | `agentId`, `threadId`, `toolCallId`, `toolName`, `annotations?`, `serverName?`                                    |
-| `tool-execution-completed`       | `agentId`, `threadId`, `toolCallId`, `toolName`, `durationMs`, `isError`, `annotations?`, `serverName?`           |
+| `tool-execution-completed`       | `agentId`, `threadId`, `toolCallId`, `toolName`, `durationMs`, `isError`, `error?`, `annotations?`, `serverName?` |
 | `tool-approval-requested`        | `agentId`, `threadId`, `toolCallId`, `toolName`, `annotations?`, `serverName?`                                    |
 | `tool-approval-resolved`         | `agentId`, `threadId`, `toolCallId`, `approved`                                                                   |
 | `mcp-server-discovery-started`   | `agentId`, `serverName`                                                                                           |

package/dist/chat-session.d.ts

@@ -3,7 +3,7 @@ import type { AgentHarness } from './harness/agent-harness.js';
 import type { StreamOptions } from './harness/harness-config.js';
 import type { TelemetrySlice } from './internal/telemetry-router.js';
 import type { ChatEvent, ChatStreamResult } from './types/events.js';
-import type { Message } from './types/messages.js';
+import type { Message, MessagePart } from './types/messages.js';
 import type { TelemetryBus, TelemetryEventCallback } from './types/telemetry-events.js';
 import type { ToolResultInfo } from './types/tools.js';
 /**
@@ -50,10 +50,11 @@ export interface ChatSession {
      * On pre-stream failure, subscribers are notified with `ErrorEvent` + `FinishEvent` before
      * the returned promise rejects. See the interface-level "Failure handling" notes for details.
      *
-     * @param message - User message as a plain string.
+     * @param message - User message: a plain string, or an array of {@link MessagePart}s for
+     *   multi-part input (text plus `image` / `file` attachments).
      * @param options - Per-call options controlling mode, tools, model, etc.
      */
-    chat(message: string, options?: ChatOptions): Promise<ChatStreamResult>;
+    chat(message: string | MessagePart[], options?: ChatOptions): Promise<ChatStreamResult>;
     /**
      * Feed the result of a **consumer-executed (client-side) tool** back into the
      * conversation and resume stream generation.
@@ -196,7 +197,7 @@ export declare class DefaultChatSession implements ChatSession {
      * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
      *   before returning a stream result.
      */
-    chat(message: string, options?: ChatOptions): Promise<ChatStreamResult>;
+    chat(message: string | MessagePart[], options?: ChatOptions): Promise<ChatStreamResult>;
     /**
      * @requirements
      * - MUST delegate to `this.harness.submitToolResult()`, passing `this.agentId` and `this.threadId`.
@@ -223,8 +224,11 @@ export declare class DefaultChatSession implements ChatSession {
      *   continuations within the same chat turn — those are continuations of one logical turn
      *   and the tool start timestamp lives on the session, not the stream. The tracking map is
      *   cleared on every terminal `finish` ChatEvent so stale entries from one turn never bleed
-     *   into the next. An unmatched `tool-result` (no recorded `tool-call` in the session) is
-     *   still skipped.
+     *   into the next, **except** when `finishReason === 'tool-calls'` — under the
+     *   parallel-approval UX (#447) those are per-tool continuation terminators, not turn
+     *   boundaries; the matching `tool-result` may land on a later continuation stream and
+     *   clearing here would lose its start timestamp. An unmatched `tool-result` (no recorded
+     *   `tool-call` in the session) is still skipped.
      *
      * `chat-stream-started` is emitted by the entry-point method (chat / submitToolResult /
      * approveToolCall / declineToolCall) before the harness call so that pre-stream rejections

package/dist/chat-session.js

@@ -118,8 +118,11 @@ export class DefaultChatSession {
      *   continuations within the same chat turn — those are continuations of one logical turn
      *   and the tool start timestamp lives on the session, not the stream. The tracking map is
      *   cleared on every terminal `finish` ChatEvent so stale entries from one turn never bleed
-     *   into the next. An unmatched `tool-result` (no recorded `tool-call` in the session) is
-     *   still skipped.
+     *   into the next, **except** when `finishReason === 'tool-calls'` — under the
+     *   parallel-approval UX (#447) those are per-tool continuation terminators, not turn
+     *   boundaries; the matching `tool-result` may land on a later continuation stream and
+     *   clearing here would lose its start timestamp. An unmatched `tool-result` (no recorded
+     *   `tool-call` in the session) is still skipped.
      *
      * `chat-stream-started` is emitted by the entry-point method (chat / submitToolResult /
      * approveToolCall / declineToolCall) before the harness call so that pre-stream rejections
@@ -141,7 +144,17 @@ export class DefaultChatSession {
                     // Turn boundary — clear any unmatched in-flight tool starts so a stale
                     // entry from one turn cannot pair with an unrelated tool-result on the
                     // next turn. Matched pairs already removed their entry in `deriveToolTelemetry`.
-                    this.toolStartMs.clear();
+                    //
+                    // Skip the clear when `finishReason === 'tool-calls'`. Under the
+                    // parallel-approval UX (#447), a single chat turn can produce multiple
+                    // per-tool continuation streams, each terminated with a synthetic
+                    // `finish('tool-calls')` to honor the "one finish per per-tool stream"
+                    // invariant. Those mid-turn finishes are NOT turn boundaries — clearing
+                    // would lose tracking for tool-calls whose tool-result lands on a later
+                    // continuation stream. Only terminal `FinishReason`s end the turn.
+                    if (event.finishReason !== 'tool-calls') {
+                        this.toolStartMs.clear();
+                    }
                 }
                 if (event.type === 'error')
                     lastError = event.error;
@@ -370,6 +383,7 @@ export class DefaultChatSession {
                 toolName: event.toolName,
                 durationMs: this.clock.now().getTime() - start,
                 isError: event.isError === true,
+                ...(event.error ? { error: event.error } : {}),
                 ...(event.annotations ? { annotations: event.annotations } : {}),
                 ...(event.serverName ? { serverName: event.serverName } : {}),
             });

package/dist/errors.d.ts

@@ -4,8 +4,10 @@ export declare const AgentSDKErrorType: {
     readonly COMPACTION_FAILED: "COMPACTION_FAILED";
     readonly DISPOSED: "DISPOSED";
     readonly INCOMPATIBLE_HARNESS: "INCOMPATIBLE_HARNESS";
+    readonly INVALID_MESSAGE_CONTENT: "INVALID_MESSAGE_CONTENT";
     readonly MCP_SERVER_DISABLED: "MCP_SERVER_DISABLED";
     readonly MCP_SERVER_NOT_FOUND: "MCP_SERVER_NOT_FOUND";
+    readonly MULTIMODAL_NOT_SUPPORTED: "MULTIMODAL_NOT_SUPPORTED";
     readonly NOT_SUPPORTED: "NOT_SUPPORTED";
 };
 export type AgentSDKErrorType = (typeof AgentSDKErrorType)[keyof typeof AgentSDKErrorType];

package/dist/errors.js

@@ -8,8 +8,10 @@ export const AgentSDKErrorType = {
     COMPACTION_FAILED: 'COMPACTION_FAILED',
     DISPOSED: 'DISPOSED',
     INCOMPATIBLE_HARNESS: 'INCOMPATIBLE_HARNESS',
+    INVALID_MESSAGE_CONTENT: 'INVALID_MESSAGE_CONTENT',
     MCP_SERVER_DISABLED: 'MCP_SERVER_DISABLED',
     MCP_SERVER_NOT_FOUND: 'MCP_SERVER_NOT_FOUND',
+    MULTIMODAL_NOT_SUPPORTED: 'MULTIMODAL_NOT_SUPPORTED',
     NOT_SUPPORTED: 'NOT_SUPPORTED',
 };
 export class AgentSDKError extends Error {

package/dist/harness/agent-harness.d.ts

@@ -1,7 +1,7 @@
 import type { LogRecord, Unsubscribe } from '@salesforce/agentic-common';
 import type { McpServerInfo } from '../mcp-config.js';
 import type { ChatStreamResult } from '../types/events.js';
-import type { Message } from '../types/messages.js';
+import type { Message, MessagePart } from '../types/messages.js';
 import type { TelemetryEventCallback } from '../types/telemetry-events.js';
 import type { ToolResultInfo } from '../types/tools.js';
 import type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness-config.js';
@@ -203,10 +203,12 @@ export interface AgentHarness {
      *
      * @param agentId - ID of the agent to invoke.
      * @param threadId - ID of the conversation thread.
-     * @param message - User message as a plain string.
+     * @param message - User message: a plain string, or an array of {@link MessagePart}s for
+     *   multi-part input (text plus `image` / `file` attachments). Only input parts are valid here —
+     *   passing `tool-call` / `tool-result` parts is a programmer error and harnesses reject it.
      * @param options - Per-call streaming options.
      */
-    stream(agentId: string, threadId: string, message: string, options?: StreamOptions): Promise<ChatStreamResult>;
+    stream(agentId: string, threadId: string, message: string | MessagePart[], options?: StreamOptions): Promise<ChatStreamResult>;
     /**
      * Feed the result of a **consumer-executed (client-side) tool** back into the
      * conversation and resume stream generation. Implements the consumer-facing

package/dist/harness/harness-config.d.ts

@@ -85,6 +85,30 @@ export type HarnessAgentConfig = Omit<AgentConfig, 'orgAlias'> & {
  * `test/harness/harness-config.test.ts` that asserts unknown fields survive.
  */
 export declare function toHarnessConfig(config: AgentConfig, orgJwt?: JSONWebToken): HarnessAgentConfig;
+/**
+ * Approval-mode selector for `StreamOptions.requireToolApproval`.
+ *
+ * Distinguishes the legacy "serial" UX (one approval per stream;
+ * consumer settles before the next is surfaced) from the parallel
+ * "batch" UX (all approval-requests for a parallel `tool_use` batch
+ * surface on the same stream so the consumer can render them as a
+ * batch approval card). See `requireToolApproval` for the safety
+ * note on choosing `batch`.
+ */
+export type ToolApprovalMode = 'serial' | 'batch';
+/**
+ * Resolves `StreamOptions.requireToolApproval` to its canonical mode:
+ * `undefined` (gating off), `'serial'`, or `'batch'`. Centralizes the
+ * boolean-vs-string normalization so harnesses don't duplicate the
+ * resolution logic.
+ *
+ * Semantics:
+ * - `undefined` / `false` → `undefined` (no gating).
+ * - `true` → `'serial'` (back-compat shorthand for the original `boolean` shape).
+ * - `'serial'` → `'serial'` (explicit, equivalent to `true`).
+ * - `'batch'` → `'batch'`.
+ */
+export declare function resolveToolApprovalMode(requireToolApproval: boolean | ToolApprovalMode | undefined): ToolApprovalMode | undefined;
 /**
  * Per-call options controlling streaming behavior.
  */
@@ -92,16 +116,36 @@ export type StreamOptions = {
     /** Signal to abort the streaming operation. */
     abortSignal?: AbortSignal;
     /**
-     * When `true`, the harness requires human approval before executing any
+     * When set, the harness requires human approval before executing any
      * native tool (e.g., MCP tools). The stream emits a `tool-approval-request`
      * event and suspends until the consumer calls `approveToolCall()` or
      * `declineToolCall()`.
      *
-     * Does not affect consumer-executed tools (those defined via `AgentConfig.tools`
-     * without an execute handler) — the consumer already controls execution for
-     * those via `submitToolResult()`.
+     * Accepts a `boolean` (back-compatible shorthand) or one of the
+     * approval-mode strings:
+     *
+     * - **`true` or `'serial'`** (the safe default): each chat-stream
+     *   surfaces ONE `tool-approval-request` at a time. The consumer
+     *   settles the approval; the next `tool-approval-request` (if any)
+     *   appears on the continuation stream. Identical to the SDK's
+     *   behavior before parallel-approval UX (#447) — safe for consumers
+     *   whose iterator returns on the first approval-request and
+     *   re-iterates the continuation (Pattern B).
+     *
+     * - **`'batch'`**: when the model emits parallel `tool_use` blocks, the
+     *   broker surfaces ALL approval-requests on the same stream so the
+     *   consumer can render a batch approval UI ("Approve these N tools?").
+     *   Consumers MUST iterate to natural park collecting approvals
+     *   (Pattern A); a `break`-on-first-approval loop will miss the
+     *   subsequent approvals on the same stream and the chat will hang.
+     *   Only opt into `'batch'` after the consumer's iterator collects all
+     *   approvals before settling.
+     *
+     * Does not affect consumer-executed tools (those defined via
+     * `AgentConfig.tools` without an execute handler) — the consumer
+     * already controls execution for those via `submitToolResult()`.
      */
-    requireToolApproval?: boolean;
+    requireToolApproval?: boolean | ToolApprovalMode;
     /**
      * Maximum number of LLM call steps the agent may take per `stream()` invocation.
      * Each step is one LLM call (which may produce text, tool calls, or both).

package/dist/harness/harness-config.js

@@ -24,6 +24,31 @@ export function toHarnessConfig(config, orgJwt) {
     const { orgAlias: _, ...rest } = config;
     return { ...rest, orgJwt };
 }
+/**
+ * Resolves `StreamOptions.requireToolApproval` to its canonical mode:
+ * `undefined` (gating off), `'serial'`, or `'batch'`. Centralizes the
+ * boolean-vs-string normalization so harnesses don't duplicate the
+ * resolution logic.
+ *
+ * Semantics:
+ * - `undefined` / `false` → `undefined` (no gating).
+ * - `true` → `'serial'` (back-compat shorthand for the original `boolean` shape).
+ * - `'serial'` → `'serial'` (explicit, equivalent to `true`).
+ * - `'batch'` → `'batch'`.
+ */
+export function resolveToolApprovalMode(requireToolApproval) {
+    if (requireToolApproval === undefined || requireToolApproval === false)
+        return undefined;
+    if (requireToolApproval === true)
+        return 'serial';
+    if (requireToolApproval === 'serial' || requireToolApproval === 'batch')
+        return requireToolApproval;
+    // Defensive: an `as any` consumer could pass an unknown string. Without
+    // this guard the value flows through to harness checks, which then
+    // silently degrade to "approval gating on but no broker allocated" and
+    // the chat hangs without an error a consumer can debug.
+    throw new Error(`Invalid requireToolApproval value: ${JSON.stringify(requireToolApproval)}. Expected boolean, 'serial', or 'batch'.`);
+}
 /**
  * Default maximum steps for a single agent stream invocation.
  *

package/dist/harness/stream-input.d.ts

@@ -0,0 +1,33 @@
+import { type MultimodalFile } from '@salesforce/llm-gateway-sdk';
+import type { FilePart, ImagePart, MessagePart, TextPart } from '../types/messages.js';
+/**
+ * The subset of {@link MessagePart} that is valid as user `stream()` input: plain `text` plus the
+ * multimodal `image` / `file` attachment parts. The recorded-turn parts (`reasoning`, `tool-call`,
+ * `tool-result`) are output artifacts of a previous turn and are rejected by {@link lowerStreamInput}.
+ */
+export type InputMessagePart = TextPart | ImagePart | FilePart;
+/**
+ * Shared `MessagePart[]` validation + lowering for `AgentHarness.stream()` implementations. Every
+ * harness that accepts multimodal input routes through this so the SDK guarantee — "a file is
+ * accepted or rejected identically regardless of harness" — is enforced in one place instead of
+ * re-derived (and left to drift) per harness. Only the per-part lowering is harness-specific; the
+ * file extraction, capability validation, error mapping, and input-part guard are not.
+ *
+ * Order of operations:
+ *   1. Collect `image` / `file` parts into a {@link MultimodalFile} list and hand them to
+ *      `validateFiles` (per-model + global gateway caps). An {@link LLMGClientError} is mapped to
+ *      `AgentSDKError(MULTIMODAL_NOT_SUPPORTED)`; any other throw propagates unchanged.
+ *   2. Lower each part via `mapPart`. A `reasoning` / `tool-call` / `tool-result` part is not valid
+ *      stream input and throws `AgentSDKError(INVALID_MESSAGE_CONTENT)` before `mapPart` sees it.
+ *
+ * Files are validated before lowering so an over-cap attachment surfaces as `MULTIMODAL_NOT_SUPPORTED`
+ * even when the same message also carries a malformed part. Everything runs synchronously, so a
+ * failure rejects the harness's `stream()` promise pre-stream rather than mid-iteration.
+ *
+ * @param parts - the user message parts to validate and lower.
+ * @param validateFiles - per-harness file validation (e.g. `validateMultimodalFiles(files, model)`)
+ *   that throws `LLMGClientError` on a cap/format violation and no-ops for text-only input.
+ * @param mapPart - lowers one validated input part into the harness's content-block shape.
+ * @returns the lowered blocks, in the original part order.
+ */
+export declare function lowerStreamInput<TBlock>(parts: MessagePart[], validateFiles: (files: readonly MultimodalFile[]) => void, mapPart: (part: InputMessagePart) => TBlock): TBlock[];

package/dist/harness/stream-input.js

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { LLMGClientError } from '@salesforce/llm-gateway-sdk';
+import { AgentSDKError, AgentSDKErrorType } from '../errors.js';
+/**
+ * Shared `MessagePart[]` validation + lowering for `AgentHarness.stream()` implementations. Every
+ * harness that accepts multimodal input routes through this so the SDK guarantee — "a file is
+ * accepted or rejected identically regardless of harness" — is enforced in one place instead of
+ * re-derived (and left to drift) per harness. Only the per-part lowering is harness-specific; the
+ * file extraction, capability validation, error mapping, and input-part guard are not.
+ *
+ * Order of operations:
+ *   1. Collect `image` / `file` parts into a {@link MultimodalFile} list and hand them to
+ *      `validateFiles` (per-model + global gateway caps). An {@link LLMGClientError} is mapped to
+ *      `AgentSDKError(MULTIMODAL_NOT_SUPPORTED)`; any other throw propagates unchanged.
+ *   2. Lower each part via `mapPart`. A `reasoning` / `tool-call` / `tool-result` part is not valid
+ *      stream input and throws `AgentSDKError(INVALID_MESSAGE_CONTENT)` before `mapPart` sees it.
+ *
+ * Files are validated before lowering so an over-cap attachment surfaces as `MULTIMODAL_NOT_SUPPORTED`
+ * even when the same message also carries a malformed part. Everything runs synchronously, so a
+ * failure rejects the harness's `stream()` promise pre-stream rather than mid-iteration.
+ *
+ * @param parts - the user message parts to validate and lower.
+ * @param validateFiles - per-harness file validation (e.g. `validateMultimodalFiles(files, model)`)
+ *   that throws `LLMGClientError` on a cap/format violation and no-ops for text-only input.
+ * @param mapPart - lowers one validated input part into the harness's content-block shape.
+ * @returns the lowered blocks, in the original part order.
+ */
+export function lowerStreamInput(parts, validateFiles, mapPart) {
+    const files = [];
+    for (const part of parts) {
+        if (part.type === 'image' || part.type === 'file') {
+            files.push({ mimeType: part.mimeType, data: part.data });
+        }
+    }
+    try {
+        validateFiles(files);
+    }
+    catch (err) {
+        if (err instanceof LLMGClientError) {
+            throw new AgentSDKError(err.message, AgentSDKErrorType.MULTIMODAL_NOT_SUPPORTED, { cause: err });
+        }
+        throw err;
+    }
+    return parts.map((part) => {
+        if (part.type === 'text' || part.type === 'image' || part.type === 'file') {
+            return mapPart(part);
+        }
+        throw new AgentSDKError(`Message part of type "${part.type}" is not valid stream input; only text, image, and file parts are accepted.`, AgentSDKErrorType.INVALID_MESSAGE_CONTENT);
+    });
+}
+//# sourceMappingURL=stream-input.js.map

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-export type { Message, MessagePart } from './types/messages.js';
+export type { Message, MessagePart, ImagePart, FilePart } from './types/messages.js';
 export type { ChatEvent, StartEvent, TextDeltaEvent, ReasoningDeltaEvent, ToolCallEvent, ToolApprovalRequestEvent, ToolResultEvent, StepStartEvent, StepFinishEvent, ErrorEvent, FinishEvent, ChatStreamResult, } from './types/events.js';
 export type { ToolDefinition, ToolCallInfo, ToolResultInfo } from './types/tools.js';
 export type { FinishReason, UsageMetadata } from './types/usage.js';
-export type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness/harness-config.js';
-export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
+export type { AgentConfig, HarnessAgentConfig, StreamOptions, ToolApprovalMode } from './harness/harness-config.js';
+export { DEFAULT_MAX_STEPS, resolveToolApprovalMode } from './harness/harness-config.js';
 export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpServerInfo, McpServerErrorCategory, McpServerErrorDetail, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
 export { McpServerStatus } from './mcp-config.js';
 export { ModelName } from '@salesforce/llm-gateway-sdk';
@@ -15,6 +15,7 @@ export type { AgentConnectivityResolver, ResolvedConnectivity } from './agent-co
 export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './harness/index.js';
 export { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
 export { HarnessBusOwner } from './harness/harness-bus-owner.js';
+export { lowerStreamInput, type InputMessagePart } from './harness/stream-input.js';
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
 export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent, ChatStreamErrorEvent, ChatStreamStartedEvent, ChatStreamTrigger, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, McpServerStatusChangedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalRequestedEvent, ToolApprovalResolvedEvent, ToolExecutionCompletedEvent, ToolExecutionStartedEvent, } from './types/telemetry-events.js';
 export type { LogLevel, LogRecord, Unsubscribe } from '@salesforce/agentic-common';

package/dist/index.js

@@ -2,7 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
+export { DEFAULT_MAX_STEPS, resolveToolApprovalMode } from './harness/harness-config.js';
 export { McpServerStatus } from './mcp-config.js';
 export { ModelName } from '@salesforce/llm-gateway-sdk';
 export { inferSfApiEnv, SfApiEnv } from '@salesforce/agentic-common';
@@ -12,6 +12,7 @@ export {} from './agent.js';
 export {} from './chat-session.js';
 export { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
 export { HarnessBusOwner } from './harness/harness-bus-owner.js';
+export { lowerStreamInput } from './harness/stream-input.js';
 // ── Errors ───────────────────────────────────────────────────────────
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
 // ── MCP Auth ────────────────────────────────────────────────────────

package/dist/mcp-config.d.ts

@@ -34,6 +34,25 @@ export type MCPStdioServerConfig = {
     enabled?: boolean;
     /** Timeout in milliseconds for individual requests to the server. */
     timeout?: number;
+    /**
+     * Opt the server's tool surface out of the active runtime's tool-search
+     * deferral. When `true`, every tool advertised by this server is
+     * registered with the model up-front instead of sitting behind a
+     * search/load round-trip. Useful for small, discovery-critical surfaces
+     * (e.g. ≤ 10 tools the model needs to find without prompting). Default
+     * (`undefined` / `false`): tools may be deferred when the active runtime
+     * enables tool search.
+     *
+     * **Harness behavior:**
+     * - **Claude harness** — sets `_meta['anthropic/alwaysLoad'] = true` on
+     *   each tool the bridge forwards, equivalent to
+     *   `defer_loading: false` on the API. Skill-bridge and consumer-tool
+     *   tools are always-load regardless of this flag (see
+     *   `@salesforce/sfdx-agent-harness-claude` ARCHITECTURE.md).
+     * - **Mastra harness** — no-op; Mastra eager-loads MCP tools at every
+     *   turn already, so there's no deferral to opt out of.
+     */
+    alwaysLoad?: boolean;
 };
 /** MCP server accessible over HTTP/SSE at a remote URL. */
 export type MCPRemoteServerConfig = {
@@ -46,6 +65,11 @@ export type MCPRemoteServerConfig = {
     enabled?: boolean;
     /** Timeout in milliseconds for individual requests to the server. */
     timeout?: number;
+    /**
+     * Opt the server's tool surface out of the active runtime's tool-search
+     * deferral. See {@link MCPStdioServerConfig.alwaysLoad}.
+     */
+    alwaysLoad?: boolean;
 };
 /** Connection status of a single MCP server. */
 export declare enum McpServerStatus {
@@ -107,8 +131,36 @@ export type McpToolAnnotations = {
  * contract is a non-breaking additive change at that point.
  */
 export type McpToolInfo = {
-    /** Tool name as exposed to the LLM, including any harness-applied namespacing. */
+    /**
+     * Tool name as exposed to the LLM, including any harness-applied namespacing.
+     *
+     * The format is **harness-specific**:
+     * - Mastra: `${serverName}_${toolName}`
+     * - Claude: `mcp__${serverName}__${toolName}`
+     *
+     * Treat `name` as the LLM-facing display string within a single harness —
+     * it round-trips against `tool-call` / `tool-result` /
+     * `tool-approval-request` events on the same harness, so consumers wiring
+     * UI off a single harness can match against it. Cross-harness consumer
+     * code that needs to identify a tool MUST use the {@link serverName} +
+     * {@link toolName} pair below; do NOT regex `name` to recover the
+     * components, and do NOT construct `name` portably (no helper produces
+     * the right format on every harness).
+     */
     name: string;
+    /**
+     * Logical MCP server name as configured in `AgentConfig.mcpServers` (the
+     * map key, not a URL or command). Use together with {@link toolName} for
+     * harness-agnostic tool lookups against `getMcpServerInfo()`.
+     */
+    serverName: string;
+    /**
+     * Bare tool name as declared by the upstream MCP server's `tools/list`
+     * response — the un-namespaced form, identical across harnesses for the
+     * same server. Use together with {@link serverName} for harness-agnostic
+     * tool lookups.
+     */
+    toolName: string;
     /** Human-readable description of what the tool does. */
     description?: string;
     /**

package/dist/types/messages.d.ts

@@ -29,9 +29,10 @@ export type Message = {
 };
 /**
  * Discriminated union of message content parts.
- * Aligned with AI SDK `TextPart`, `ReasoningPart`, `ToolCallPart`, `ToolResultPart`.
+ * Aligned with AI SDK `TextPart`, `ReasoningPart`, `ToolCallPart`, `ToolResultPart`, plus the
+ * multimodal `ImagePart` / `FilePart` inputs.
  */
-export type MessagePart = TextPart | ReasoningPart | ToolCallPart | ToolResultPart;
+export type MessagePart = TextPart | ReasoningPart | ToolCallPart | ToolResultPart | ImagePart | FilePart;
 /** A plain text content segment. */
 export type TextPart = {
     type: 'text';
@@ -58,3 +59,35 @@ export type ToolCallPart = ToolCallInfo & {
 export type ToolResultPart = ToolResultInfo & {
     type: 'tool-result';
 };
+/**
+ * An image attached to a user message. Field names are camelCase on the SDK's public surface;
+ * harnesses translate them to the runtime/wire shape they need (e.g. the Mastra gateway maps
+ * `mimeType` → the gateway's `ChatMessageFile.mimeType`, the Claude harness maps it onto an
+ * Anthropic `image` content block).
+ *
+ * `data` is the base64-encoded file bytes with no `data:` URI prefix. v1 supports base64 input only.
+ */
+export type ImagePart = {
+    type: 'image';
+    /** MIME type of the image. */
+    mimeType: 'image/png' | 'image/jpeg';
+    /** Base64-encoded image bytes (no `data:` URI prefix). */
+    data: string;
+    /** Optional human-readable filename, surfaced to providers that display it. */
+    fileName?: string;
+};
+/**
+ * A file (currently PDF only) attached to a user message. See {@link ImagePart} for the
+ * camelCase-vs-runtime translation contract.
+ *
+ * `data` is the base64-encoded file bytes with no `data:` URI prefix. v1 supports base64 input only.
+ */
+export type FilePart = {
+    type: 'file';
+    /** MIME type of the file. */
+    mimeType: 'application/pdf';
+    /** Base64-encoded file bytes (no `data:` URI prefix). */
+    data: string;
+    /** Optional human-readable filename, surfaced to providers that display it. */
+    fileName?: string;
+};

package/dist/types/telemetry-events.d.ts

@@ -63,6 +63,8 @@ export type ToolExecutionCompletedEvent = Base<'tool-execution-completed'> & {
     toolName: string;
     durationMs: number;
     isError: boolean;
+    /** The error thrown by the tool execution. Present when `isError` is true. */
+    error?: Error;
     /** Annotations declared for the tool, when available. See {@link ToolApprovalRequestEvent.annotations}. */
     annotations?: McpToolAnnotations;
     /** Originating MCP server name, when the tool was discovered through MCP. */
@@ -120,10 +122,12 @@ export type McpServerDiscoveryFailedEvent = Base<'mcp-server-discovery-failed'>
  * then on success `Reconnecting → Connected`, or on failure
  * `Reconnecting → Error`.
  *
- * Emitted by the Mastra harness today. The Claude harness emits it through
- * the per-server discovery telemetry triple (started → completed/failed) but
- * not as a standalone transition event — both harnesses converge on the same
- * `McpServerInfo[]` shape via `getMcpServerInfo()`.
+ * Both the Mastra and Claude harnesses emit this on every per-server
+ * `McpServerStatus` transition they observe (initial discovery success /
+ * failure, reconnect entry, reconnect outcome). Mid-session transport drops
+ * on a `Connected` server are not observable on either harness's underlying
+ * SDK between turns; the next operation that touches the server discovers
+ * the drop and emits the transition then.
  */
 export type McpServerStatusChangedEvent = Base<'mcp-server-status-changed'> & {
     agentId: string;

package/dist/types/tools.d.ts

@@ -86,4 +86,6 @@ export type ToolResultInfo = {
      * the SDK or harness crashing.
      */
     isError?: boolean;
+    /** The error thrown by the tool execution. Present when `isError` is true. Absent on success paths. */
+    error?: Error;
 };

package/dist/types/usage.d.ts

@@ -13,6 +13,8 @@ export type UsageMetadata = {
     reasoningTokens?: number;
     /** Input tokens served from provider cache (reduces cost). */
     cachedInputTokens?: number;
+    /** Input tokens written to the provider cache during this interaction. */
+    cacheWriteInputTokens?: number;
 };
 /**
  * Reason the model stopped generating.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -36,12 +36,12 @@
   ],
   "dependencies": {
     "@salesforce/agentic-common": "0.6.0",
-    "@salesforce/llm-gateway-sdk": "0.8.0"
+    "@salesforce/llm-gateway-sdk": "0.10.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.8.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.11.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.10.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.13.0",
     "@types/node": "^22.19.17",
     "@vitest/coverage-istanbul": "^4.1.7",
     "@vitest/eslint-plugin": "^1.6.17",