@salesforce/sfdx-agent-sdk 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to `@salesforce/sfdx-agent-sdk` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.23.0] - 2026-06-22
+
+### Features
+- **agentic-common,harnesses**: route HTTPS_PROXY via injectable undici Dispatcher @W-23121596 ([#610](https://github.com/forcedotcom/agentic-dx/pull/610))
+
+### Docs
+- align SDK + agentic-common docs with current public surface (post-PR-#607) ([#608](https://github.com/forcedotcom/agentic-dx/pull/608))
+
+## [0.22.0] - 2026-06-19
+
+### Features
+- **BREAKING** Major refactor to Unify Connectivity via ModelConnectivityInfo @W-22782317 ([#607](https://github.com/forcedotcom/agentic-dx/pull/607))
+
+### Chores
+- **deps-dev**: bump @vitest/eslint-plugin from 1.6.19 to 1.6.20 in the vitest group across 1 directory ([#601](https://github.com/forcedotcom/agentic-dx/pull/601))
+- **deps-dev**: bump eslint from 10.4.1 to 10.5.0 in the eslint group across 1 directory ([#600](https://github.com/forcedotcom/agentic-dx/pull/600))
+- **deps-dev**: bump @types/node from 22.19.20 to 22.19.21 in the dev-dependencies group ([#599](https://github.com/forcedotcom/agentic-dx/pull/599))
+
 ## [0.21.0] - 2026-06-15
 
 ### Fixes

package/README.md

@@ -102,17 +102,18 @@ through a typed `manager.extensions` slot. `createAgentManager` infers `H` from
 explicitly. The `createAgent` config parameter narrows automatically when the harness brands itself with
 `WithAgentConfig` — see "Harness Extensibility" below.
 
-| Property / Method    | Signature                                                                                                                          | Description                                                                                                                                                                                                                                             |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `extensions`         | `H['extensions']`                                                                                                                  | Harness-specific extensions namespace (read-only). Re-exposes the harness's `extensions` slot typed off `H`. Per-agent accessors take the agent id as their first argument. The SDK never reads or interprets this — see "Harness Extensibility" below. |
-| `createAgent`        | `(projectRoot: string, config?: ConfigOf<H> & { agentId?: string }, options?: { abortSignal?: AbortSignal }) => Promise<Agent<H>>` | Create and register a new agent and persist its identity triple. `projectRoot` must be an existing directory. If `agentId` is omitted a UUID is generated. The config type is inferred from the harness — see `ConfigOf<H>`.                            |
-| `getAgent`           | `(agentId: string) => Agent<H>`                                                                                                    | Retrieve a live agent by ID. Throws `AgentSDKError` (`AGENT_NOT_FOUND`) for unknown ids and for ids that are only present in `getRestoreFailures()`.                                                                                                    |
-| `getAgentIds`        | `() => string[]`                                                                                                                   | List all live agent IDs (successful + successfully restored). Failed-restore agents are not included — query `getRestoreFailures()` separately.                                                                                                         |
-| `destroyAgent`       | `(agentId: string) => Promise<void>`                                                                                               | Destroy an agent, remove its identity record from disk, and clear any matching `getRestoreFailures()` entry. Failed-restore-only ids are accepted (no harness call made).                                                                               |
-| `shutdown`           | `() => Promise<void>`                                                                                                              | Destroy all live agents and shut down the harness. Identity files survive (that's the whole point) — restart `createAgentManager` over the same root to bring them back.                                                                                |
-| `onTelemetry`        | `(callback: TelemetryEventCallback) => Unsubscribe`                                                                                | Subscribe to telemetry across all managed agents.                                                                                                                                                                                                       |
-| `onLog`              | `(callback: (record: LogRecord) => void) => Unsubscribe`                                                                           | Subscribe to structured logs across all managed agents. Bridge this into your host logger to observe restore-failure events + soft-skip warnings.                                                                                                       |
-| `getRestoreFailures` | `() => RestoreFailure[]`                                                                                                           | Snapshot of agents the SDK could not restore on this boot. Each entry carries the persisted `{ agentId, projectRoot, config }` plus the underlying error.                                                                                               |
+| Property / Method     | Signature                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `extensions`          | `H['extensions']`                                                                                                                  | Harness-specific extensions namespace (read-only). Re-exposes the harness's `extensions` slot typed off `H`. Per-agent accessors take the agent id as their first argument. The SDK never reads or interprets this — see "Harness Extensibility" below.                                                                                                                                                                                                                  |
+| `createAgent`         | `(projectRoot: string, config?: ConfigOf<H> & { agentId?: string }, options?: { abortSignal?: AbortSignal }) => Promise<Agent<H>>` | Create and register a new agent and persist its identity triple. `projectRoot` must be an existing directory. If `agentId` is omitted a UUID is generated. The config type is inferred from the harness — see `ConfigOf<H>`.                                                                                                                                                                                                                                             |
+| `getAgent`            | `(agentId: string) => Agent<H>`                                                                                                    | Retrieve a live agent by ID. Throws `AgentSDKError` (`AGENT_NOT_FOUND`) for unknown ids and for ids that are only present in `getRestoreFailures()`.                                                                                                                                                                                                                                                                                                                     |
+| `getAgentIds`         | `() => string[]`                                                                                                                   | List all live agent IDs (successful + successfully restored). Failed-restore agents are not included — query `getRestoreFailures()` separately.                                                                                                                                                                                                                                                                                                                          |
+| `destroyAgent`        | `(agentId: string) => Promise<void>`                                                                                               | Destroy an agent, remove its identity record from disk, and clear any matching `getRestoreFailures()` entry. Failed-restore-only ids are accepted (no harness call made).                                                                                                                                                                                                                                                                                                |
+| `shutdown`            | `() => Promise<void>`                                                                                                              | Destroy all live agents and shut down the harness. Identity files survive (that's the whole point) — restart `createAgentManager` over the same root to bring them back.                                                                                                                                                                                                                                                                                                 |
+| `onTelemetry`         | `(callback: TelemetryEventCallback) => Unsubscribe`                                                                                | Subscribe to telemetry across all managed agents.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `onLog`               | `(callback: (record: LogRecord) => void) => Unsubscribe`                                                                           | Subscribe to structured logs across all managed agents. Bridge this into your host logger to observe restore-failure events + soft-skip warnings.                                                                                                                                                                                                                                                                                                                        |
+| `onWireCommunication` | `(callback: WireCommunicationEventCallback) => Unsubscribe`                                                                        | Subscribe to wire-level communication events from the harness. Opt-in diagnostic channel that surfaces outbound LLM requests, responses, and harness-specific monitoring metadata. Subscriber-gated end-to-end — harnesses pay no cost when nobody listens. See "Wire-Communication Events" below for the event-shape catalog and the harness-asymmetric coverage (Mastra emits per-call request/response pairs; Claude emits a per-stream pointer to a debug log file). |
+| `getRestoreFailures`  | `() => RestoreFailure[]`                                                                                                           | Snapshot of agents the SDK could not restore on this boot. Each entry carries the persisted `{ agentId, projectRoot, config }` plus the underlying error.                                                                                                                                                                                                                                                                                                                |
 
 #### `RestoreFailure`
 
@@ -135,24 +136,24 @@ A configured AI agent. Factory for chat sessions. The optional `H` type paramete
 — harness-specific features are reached through `manager.extensions`, not `agent.extensions`. The default `AgentHarness`
 keeps unparameterized call sites working.
 
-| Method                 | Signature                                                                          | Description                                                                                                                               |
-| ---------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `getId`                | `() => string`                                                                     | Agent identifier.                                                                                                                         |
-| `getProjectRoot`       | `() => string`                                                                     | Absolute project path.                                                                                                                    |
-| `getOrgConnectionInfo` | `() => OrgConnectionInfo`                                                          | Org metadata (orgId, alias, instanceUrl, username, env).                                                                                  |
-| `getAgentConfig`       | `() => AgentConfig`                                                                | Current configuration (shallow copy).                                                                                                     |
-| `getMcpServerInfo`     | `() => McpServerInfo[]`                                                            | MCP server status and discovered tools.                                                                                                   |
-| `reconnectMcpServer`   | `(serverName: string) => Promise<void>`                                            | Recover one MCP server without recycling the agent. Semantics vary by harness — observe via `getMcpServerInfo()` and discovery telemetry. |
-| `updateAgentConfig`    | `(config?: AgentConfig, options?: { abortSignal?: AbortSignal }) => Promise<void>` | Merge new config into the live agent.                                                                                                     |
-| `createChatSession`    | `() => Promise<ChatSession>`                                                       | Open a new conversation thread.                                                                                                           |
-| `getChatSession`       | `(sessionId: string) => ChatSession`                                               | Retrieve a session. Throws `AgentSDKError` (`CHAT_SESSION_NOT_FOUND`).                                                                    |
-| `getChatSessionIds`    | `() => string[]`                                                                   | List active session IDs.                                                                                                                  |
-| `destroyChatSession`   | `(sessionId: string) => Promise<void>`                                             | Destroy a session and its history.                                                                                                        |
-| `cloneChatSession`     | `(sourceSessionId: string) => Promise<ChatSession>`                                | Clone a session with its message history.                                                                                                 |
-| `compactChatSession`   | `(sessionId: string) => Promise<ChatSession>`                                      | Compact a session into a summarized new session.                                                                                          |
-| `destroy`              | `() => Promise<void>`                                                              | Destroy the agent and all its sessions.                                                                                                   |
-| `onTelemetry`          | `(callback: TelemetryEventCallback) => Unsubscribe`                                | Subscribe to telemetry scoped to this agent (and its sessions).                                                                           |
-| `onLog`                | `(callback: (record: LogRecord) => void) => Unsubscribe`                           | Subscribe to logs scoped to this agent (and its sessions).                                                                                |
+| Method               | Signature                                                                                                  | Description                                                                                                                                                                                                                                                                                                       |
+| -------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getId`              | `() => string`                                                                                             | Agent identifier.                                                                                                                                                                                                                                                                                                 |
+| `getProjectRoot`     | `() => string`                                                                                             | Absolute project path.                                                                                                                                                                                                                                                                                            |
+| `getOrgConnection`   | `() => OrgConnection \| undefined`                                                                         | The Salesforce `OrgConnection` resolved for this agent (or `undefined` if the connectivity resolver omitted it — non-Salesforce hosts on the BYOK / api-key path return `undefined`).                                                                                                                             |
+| `getAgentConfig`     | `() => AgentConfig`                                                                                        | Current configuration (shallow copy).                                                                                                                                                                                                                                                                             |
+| `getMcpServerInfo`   | `() => McpServerInfo[]`                                                                                    | MCP server status and discovered tools.                                                                                                                                                                                                                                                                           |
+| `reconnectMcpServer` | `(serverName: string) => Promise<void>`                                                                    | Recover one MCP server without recycling the agent. Semantics vary by harness — observe via `getMcpServerInfo()` and discovery telemetry.                                                                                                                                                                         |
+| `updateAgentConfig`  | `(config?: AgentConfig, options?: { abortSignal?: AbortSignal; forceResolve?: boolean }) => Promise<void>` | Merge new config into the live agent. Pass `forceResolve: true` to re-run the connectivity resolver even when the partial config doesn't include `orgAlias` or `modelId` — for consumer-side state changes (BYOK toggle, feature-id flip, rate-limit gate) the resolver reads but the SDK can't observe directly. |
+| `createChatSession`  | `() => Promise<ChatSession>`                                                                               | Open a new conversation thread.                                                                                                                                                                                                                                                                                   |
+| `getChatSession`     | `(sessionId: string) => ChatSession`                                                                       | Retrieve a session. Throws `AgentSDKError` (`CHAT_SESSION_NOT_FOUND`).                                                                                                                                                                                                                                            |
+| `getChatSessionIds`  | `() => string[]`                                                                                           | List active session IDs.                                                                                                                                                                                                                                                                                          |
+| `destroyChatSession` | `(sessionId: string) => Promise<void>`                                                                     | Destroy a session and its history.                                                                                                                                                                                                                                                                                |
+| `cloneChatSession`   | `(sourceSessionId: string) => Promise<ChatSession>`                                                        | Clone a session with its message history.                                                                                                                                                                                                                                                                         |
+| `compactChatSession` | `(sessionId: string) => Promise<ChatSession>`                                                              | Compact a session into a summarized new session.                                                                                                                                                                                                                                                                  |
+| `destroy`            | `() => Promise<void>`                                                                                      | Destroy the agent and all its sessions.                                                                                                                                                                                                                                                                           |
+| `onTelemetry`        | `(callback: TelemetryEventCallback) => Unsubscribe`                                                        | Subscribe to telemetry scoped to this agent (and its sessions).                                                                                                                                                                                                                                                   |
+| `onLog`              | `(callback: (record: LogRecord) => void) => Unsubscribe`                                                   | Subscribe to logs scoped to this agent (and its sessions).                                                                                                                                                                                                                                                        |
 
 ### `ChatSession`
 
@@ -211,6 +212,22 @@ Discriminated union (`event.type`) of streaming events:
 > 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.
 
+#### Per-variant event types
+
+Every `ChatEvent` variant is exported as a named type so consumers can write narrowed callbacks without re-declaring the
+shape: `StartEvent`, `TextDeltaEvent`, `ReasoningDeltaEvent`, `ToolCallEvent`, `ToolCallDeltaEvent`,
+`ToolApprovalRequestEvent`, `ToolResultEvent`, `ToolProgressEvent`, `StepStartEvent`, `StepFinishEvent`, `ErrorEvent`,
+`FinishEvent`. Useful when factoring per-event handlers out of a `for await` loop:
+
+```typescript
+import type { ToolApprovalRequestEvent } from '@salesforce/sfdx-agent-sdk';
+
+function onApprovalRequest(event: ToolApprovalRequestEvent): Promise<boolean> {
+  // typed access to event.toolCall, event.annotations, event.serverName
+  return promptUser(event);
+}
+```
+
 ### Configuration Types
 
 #### `AgentConfig`
@@ -218,7 +235,7 @@ Discriminated union (`event.type`) of streaming events:
 | 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`.                              |
+| `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)` exported from this package.                                    |
 | `name?`         | `string`             | Human-readable agent name.                                                                                                                                                                                                                                                                                                           |
 | `description?`  | `string`             | Agent purpose description.                                                                                                                                                                                                                                                                                                           |
 | `instructions?` | `string`             | System instructions for the agent.                                                                                                                                                                                                                                                                                                   |
@@ -229,10 +246,16 @@ Discriminated union (`event.type`) of streaming events:
 
 #### `StreamOptions`
 
-| 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. |
+| Field                  | Type                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `abortSignal?`         | `AbortSignal`                 | Abort the streaming operation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `requireToolApproval?` | `boolean \| ToolApprovalMode` | 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. |
+| `maxSteps?`            | `number`                      | 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). Must be `>= 1`. Defaults to `DEFAULT_MAX_STEPS` (1024) — high enough to be effectively unlimited for real tasks; the practical ceiling is the context window and cost. The constant is exported so consumers and harness authors share one source of truth.                                                                                                    |
+
+`ToolApprovalMode` is the exported type alias `'serial' | 'batch'` — useful when typing a settings struct that drives
+`requireToolApproval`. Pair with `resolveToolApprovalMode(boolean | ToolApprovalMode | undefined)` (also exported) to
+normalize consumer input the same way the SDK does internally (`undefined` / `false` → `undefined`, `true` → `'serial'`,
+strings pass through, unknown strings throw).
 
 #### `MCPConfiguration`
 
@@ -280,13 +303,13 @@ only `MCPRemoteServerConfig` carries it.
 
 #### `McpServerInfo`
 
-| Field          | Type                                                                     | Description                                                                                                                               |
-| -------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`         | `string`                                                                 | Server identifier.                                                                                                                        |
-| `status`       | `'connected' \| 'connecting' \| 'disabled' \| 'error' \| 'reconnecting'` | Connection state. `'reconnecting'` is reported during an `Agent.reconnectMcpServer(name)` call against a previously-`'connected'` server. |
-| `tools`        | [`McpToolInfo[]`](#mcptoolinfo)                                          | Discovered tools (name + metadata).                                                                                                       |
-| `error?`       | `string`                                                                 | Sanitized human-readable error message when status is `'error'`. Stack frames and file paths are stripped at the harness boundary.        |
-| `errorDetail?` | [`McpServerErrorDetail`](#mcpservererrordetail)                          | Structured failure projection for programmatic routing (category / code / retriable). Populated when status is `'error'`.                 |
+| Field          | Type                                            | Description                                                                                                                                                                                                                                        |
+| -------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`         | `string`                                        | Server identifier.                                                                                                                                                                                                                                 |
+| `status`       | `McpServerStatus`                               | Connection state — exported enum with the values `'connected' \| 'connecting' \| 'disabled' \| 'error' \| 'reconnecting'`. `'reconnecting'` is reported during an `Agent.reconnectMcpServer(name)` call against a previously-`'connected'` server. |
+| `tools`        | [`McpToolInfo[]`](#mcptoolinfo)                 | Discovered tools (name + metadata).                                                                                                                                                                                                                |
+| `error?`       | `string`                                        | Sanitized human-readable error message when status is `'error'`. Stack frames and file paths are stripped at the harness boundary.                                                                                                                 |
+| `errorDetail?` | [`McpServerErrorDetail`](#mcpservererrordetail) | Structured failure projection for programmatic routing (category / code / retriable). Populated when status is `'error'`.                                                                                                                          |
 
 #### `McpServerErrorDetail`
 
@@ -396,6 +419,16 @@ type Message = {
 
 type MessagePart = TextPart | ReasoningPart | ToolCallPart | ToolResultPart | ImagePart | FilePart;
 
+// Plain text and reasoning segments (model chain-of-thought).
+type TextPart = { type: 'text'; text: string };
+type ReasoningPart = { type: 'reasoning'; text: string };
+
+// Tool invocation / result segments persisted on `Message.content`. Extend the
+// `ToolCallInfo` / `ToolResultInfo` shapes with a discriminator. They appear in
+// message history; they are NOT valid input on `chat()` / `addContext()`.
+type ToolCallPart = ToolCallInfo & { type: 'tool-call' };
+type ToolResultPart = ToolResultInfo & { type: 'tool-result' };
+
 // 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 };
@@ -540,17 +573,20 @@ totals, subscribe to `chat-stream-completed` telemetry instead.
 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 |
-| `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)                             |
+| 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                                                                                                                                                                                                                                                                                             |
+| `MODEL_NOT_SUPPORTED_BY_HARNESS` | `AgentManager.createAgent()` / `Agent.updateAgentConfig()` (G8 pre-flight) when the resolved `ModelConnectivityInfo.providerHint` isn't in the harness's `supportedProviderHints`. Surfaces before any harness work runs (no MCP discovery, no subprocess spawn, no language-model construction) so the consumer can branch cleanly on `err.type` and recover without resource cleanup. |
+| `MULTIMODAL_NOT_SUPPORTED`       | `ChatSession.chat()` / harness `stream()` when a file fails pre-stream capability validation (unsupported format, too large, or too many files)                                                                                                                                                                                                                                         |
+| `NOT_SUPPORTED`                  | `ApiKeyConnectivityResolver.resolve()` when the consumer-supplied `getApiKey` returns an empty / nullish value. Surfaces locally so the consumer sees "the resolver returned an empty key" rather than chasing a 401 through provider logs after `Authorization: Bearer ` (no key) lands on the wire.                                                                                   |
+| `TOOL_CALL_NOT_FOUND`            | `ChatSession.approveToolCall()` / `declineToolCall()` / `submitToolResult()` when the supplied `toolCallId` doesn't match any pending tool-call request on the current session. Typically indicates a wrong-id, wrong-session, or already-settled call. Both production harnesses (Mastra, Claude) throw this from their per-turn approval coordinator.                                 |
 
 ```typescript
 import { AgentSDKError, AgentSDKErrorType } from '@salesforce/sfdx-agent-sdk';
@@ -901,15 +937,104 @@ is what actually replaces the value the model sees.
 
 ### Connectivity Resolution
 
+The connectivity surface is the seam between the SDK and whatever-talks-to-the-LLM. It resolves three things per agent:
+which model the harness will use, the wire shape the harness should speak, and how to authenticate each outbound
+request. A bundled default resolver covers the Salesforce-org gateway path; a bundled api-key resolver covers BYOK /
+direct-provider / LLMG-Express; and consumers can implement `AgentConnectivityResolver` directly for anything else.
+
+#### `AgentConnectivityResolver`
+
+The contract every connectivity resolver implements. `createAgentManager` calls `resolve()` once per agent install
+(`createAgent`, boot-time restore, and `Agent.updateAgentConfig` when `orgAlias` / `modelId` / `forceResolve: true` is
+set), then threads the returned `ResolvedConnectivity` through to the harness.
+
+```typescript
+interface AgentConnectivityResolver {
+  resolve(projectRoot: string, config: AgentConfig): Promise<ResolvedConnectivity>;
+}
+```
+
+The bundled `DefaultAgentConnectivityResolver` (used when `createAgentManager`'s `connectivityResolver` option is unset)
+targets the Salesforce LLM Gateway via a self-refreshing JWT. The class is implementation detail — the public entry
+point is implicit via `createAgentManager`.
+
 #### `ResolvedConnectivity`
 
-Returned by `AgentConnectivityResolver.resolve()`. Contains all resolved runtime artifacts for an agent's org.
+Returned by `AgentConnectivityResolver.resolve()`. Three fields, two of them optional for non-Salesforce hosts:
+
+| Field                   | Type                    | Description                                                                                                                                                                                                                         |
+| ----------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelConnectivityInfo` | `ModelConnectivityInfo` | The five-field bag the harness reads to make every outbound LLM request. See below.                                                                                                                                                 |
+| `orgConnection?`        | `OrgConnection`         | Authenticated Salesforce org connection carrying identity and env inference. Optional — non-Salesforce hosts (MuleSoft, Commerce Vibes) omit it.                                                                                    |
+| `orgJwt?`               | `JSONWebToken`          | Self-refreshing JWT for the resolved org. Used for MCP auth injection and any other Salesforce-platform-auth need (identity, future Apex). Optional — non-Salesforce hosts and api-key BYOK hosts that don't need org auth omit it. |
+
+#### `ModelConnectivityInfo`
 
-| Field              | Type               | Description                                                            |
-| ------------------ | ------------------ | ---------------------------------------------------------------------- |
-| `llmGatewayClient` | `LLMGatewayClient` | Pre-configured and authenticated LLM gateway client.                   |
-| `orgConnection`    | `OrgConnection`    | Authenticated org connection carrying identity and env inference.      |
-| `orgJwt`           | `JSONWebToken`     | Self-refreshing JWT for the resolved org, used for MCP auth injection. |
+The connectivity facts a harness needs to make an LLM request. Five fields. Auth-kind branching lives inside
+`getHeaders()` — the harness never inspects whether the auth is a JWT, an API key, or anything else.
+
+| Field           | Type                                    | Description                                                                                                                                                                                                                                                                                                          |
+| --------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `model`         | `Model`                                 | Capability descriptor used for pre-flight multimodal validation and SDK-side context-usage reporting.                                                                                                                                                                                                                |
+| `baseUrl`       | `string`                                | Provider-native or gateway base URL (no trailing slash, no path beyond the API root). Harnesses concat the wire-shape-specific path.                                                                                                                                                                                 |
+| `nativeModelId` | `string`                                | Wire id the provider SDK sets on the request body's `model` field. May differ from `model.name` (e.g. Anthropic-direct expects `claude-sonnet-4-6`; the Salesforce gateway expects `llmgateway__BedrockAnthropicClaude46Sonnet`).                                                                                    |
+| `providerHint`  | `ProviderHint`                          | Wire shape the harness should speak. The manager validates this against the harness's `supportedProviderHints` before any harness work begins; a harness only sees hints it recognizes.                                                                                                                              |
+| `getHeaders`    | `() => Promise<Record<string, string>>` | Returns the FULL header set (Authorization included) for the NEXT outbound request. **Per-call invocation contract.** Mastra harnesses MUST call this on every HTTP call (inside their fetch wrapper); Claude harnesses MUST call this once per subprocess spawn. Caching the returned map across requests is a bug. |
+
+`getHeaders()` is allowed to throw — the harness propagates the throw as a stream-time failure, identical to any other
+transport error.
+
+#### `ProviderHint`
+
+```typescript
+type ProviderHint =
+  | 'anthropic' // Anthropic Messages API direct (api.anthropic.com)
+  | 'bedrock-anthropic' // Anthropic via AWS Bedrock invoke (Salesforce gateway uses this shape)
+  | 'openai' // OpenAI Responses API direct (api.openai.com)
+  | 'openai-responses' // OpenAI Responses API via Salesforce gateway pass-through
+  | 'openai-compatible' // OpenAI-shaped /v1/chat/completions (LLMG Express, LiteLLM, vLLM, third-party gateways)
+  | (string & {}); // Forward-compat tail — harnesses must reject unknown hints
+```
+
+The trailing `string & {}` allows resolvers to return a hint for a future provider without a same-day type bump in the
+SDK. Harnesses that don't recognize a hint MUST throw `AgentSDKError(MODEL_NOT_SUPPORTED_BY_HARNESS)` rather than fall
+through to a wrong-shape builder.
+
+#### `ApiKeyConnectivityResolver`
+
+Bundled api-key resolver covering Anthropic-direct, OpenAI-direct, and any OpenAI-compatible endpoint (LLMG Express,
+LiteLLM, vLLM, third-party gateways). Pass an instance via `createAgentManager`'s `connectivityResolver` option.
+
+```typescript
+import { ApiKeyConnectivityResolver, createAgentManager } from '@salesforce/sfdx-agent-sdk';
+
+const manager = await createAgentManager('/path/to/storage', new MastraHarnessFactory(), {
+  connectivityResolver: new ApiKeyConnectivityResolver({
+    getApiKey: () => process.env.LLMG_EXPRESS_API_KEY!,
+    baseUrl: 'https://express-internal/v1',
+    providerHint: 'openai-compatible',
+  }),
+});
+```
+
+##### `ApiKeyConnectivityResolverConfig`
+
+| Field                | Type                              | Description                                                                                                                                                                                                                                                                     |
+| -------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getApiKey`          | `() => string \| Promise<string>` | Returns the API key. Re-evaluated on every `resolve()` call, and the resulting `getHeaders()` re-invokes it on every header read so a rotating key source (env var, secret store, BYOK toggle) lands without reconstructing the resolver.                                       |
+| `baseUrl`            | `string`                          | Fully-qualified provider URL with API version segment (e.g. `https://api.openai.com/v1`, not `https://api.openai.com`).                                                                                                                                                         |
+| `providerHint`       | `ProviderHint`                    | Wire shape. Must be one a harness in the consumer's setup advertises via `HarnessFactory.supportedProviderHints`.                                                                                                                                                               |
+| `nativeModelIdFor?`  | `(model: Model) => string`        | Optional translator from canonical `model.name` to the endpoint-native model id. Direct-provider endpoints expect their own naming (`claude-sonnet-4-6`); gateway-shaped endpoints accept the canonical `llmgateway__*` id verbatim. Defaults to `model.name`.                  |
+| `connectionFactory?` | `OrgConnectionFactory`            | Optional. When supplied, the resolver mints an org connection + JWT alongside the api-key bag — the BYOK shape (api-key authenticates the LLM; org JWT authenticates MCP servers / identity). Without it, `orgConnection` and `orgJwt` are omitted from `ResolvedConnectivity`. |
+
+The resolver throws `AgentSDKError(NOT_SUPPORTED)` when `getApiKey()` returns empty / nullish so consumers see "the
+resolver returned an empty key" rather than chasing a 401 through provider logs after `Authorization: Bearer ` (no key)
+lands on the wire.
+
+`Model.customHeaders` (a vendor-label map like `{ 'anthropic-version': '2023-06-01' }`) flows through to the resolver's
+header bag. **Reserved auth headers are not overridable**: the resolver spreads `customHeaders` first and writes its own
+`Authorization` / `Content-Type` last, so a `Model` instance whose `customHeaders` includes an `Authorization` key
+silently shadows nothing — the resolver wins.
 
 #### `HarnessAgentConfig`
 
@@ -931,18 +1056,51 @@ Authorization header already exists. For all other URLs, returns headers unmodif
 
 Returns `true` if the URL matches a Salesforce Hosted MCP Server endpoint (prod, dev, test, perf, stage).
 
-### Re-exported from `@salesforce/llm-gateway-sdk`
+### `Workspace`
+
+Convenience helper for validating and normalizing a project path before handing it to `manager.createAgent`. The
+constructor is private; build one through the static async factory:
+
+```typescript
+import { Workspace } from '@salesforce/sfdx-agent-sdk';
+
+const workspace = await Workspace.create('/path/to/project');
+const agent = await manager.createAgent(workspace.projectPath, { instructions: '...' });
+```
+
+`Workspace.create(projectPath)` resolves the path to an absolute, real (symlink-followed) directory and throws if it
+doesn't exist or isn't a directory. The returned instance exposes `projectPath: string`. Pass any string to
+`manager.createAgent` directly if you don't need the validation step — `Workspace` is a convenience, not a requirement.
+
+### Model registry
+
+The `Model` family ships with this package — registered Bedrock-Anthropic Claude and OpenAI GPT variants the SDK
+recognizes today, plus an escape hatch for consumers who need a Claude variant the SDK hasn't released yet.
 
 - `Model` — abstract base class. Returned by `Models.getByName(...)` and accepted as an `AgentConfig.modelId` value.
 - `ModelName` — enum of in-tree model identifiers.
+- `Models` — registry: `Models.getByName(name)`, `Models.getDefault()`.
 - `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
-  Salesforce platform MCP URL). Defaults the unrecognized-`.pc-rnd.` fallback to `SfApiEnv.Test` (`.pc-rnd.` is an
-  internal-only OrgFarm domain — not Prod by definition); pass `{ pcRndFallback: SfApiEnv.Prod }` to override. See the
+- `validateMultimodalFiles(files, model)` — helper harnesses use to enforce per-format / per-model multimodal caps
+  pre-stream. Throws `AgentSDKError(MULTIMODAL_NOT_SUPPORTED)` on a cap-exceeding file.
+- `MultimodalFile`, `SupportedFileFormat`, `MimeType` — supporting types for multimodal validation.
+
+### Re-exported from `@salesforce/agentic-common`
+
+For consumers who name SDK public-type signatures without adding `@salesforce/agentic-common` as a direct dependency.
+
+- `OrgConnection` / `OrgConnectionFactory` — surface on `Agent.getOrgConnection()`.
+- `JSONWebToken` / `JWTOptions` / `RequiredJWTHeaders` / `RequiredJWTPayload` — surface on `ResolvedConnectivity.orgJwt`
+  and `HarnessAgentConfig.orgJwt`.
+- `LogLevel` / `LogRecord` / `Unsubscribe` — surface on `manager.onLog` / `manager.onTelemetry` /
+  `manager.onWireCommunication` callbacks.
+- `SfApiEnv` — Salesforce API environment enum (`dev`, `perf`, `prod`, `stage`, `test`).
+- `inferSfApiEnv(instanceUrl, options?)` — maps an instance URL to a `SfApiEnv`. Useful for consumers that need the
+  mapping without an `OrgConnection` (e.g. building a Salesforce platform MCP URL). Defaults the unrecognized-`.pc-rnd.`
+  fallback to `SfApiEnv.Test` (`.pc-rnd.` is an internal-only OrgFarm domain — not Prod by definition); pass
+  `{ pcRndFallback: SfApiEnv.Prod }` to override. See the
   [`@salesforce/agentic-common` README](../agentic-common/README.md#infersfapienvinstanceurl-options-sfapienv) for the
   full resolution order.
 
@@ -951,6 +1109,112 @@ Returns `true` if the URL matches a Salesforce Hosted MCP Server endpoint (prod,
 The SDK exposes typed `TelemetryEvent` / `LogRecord` streams at the manager, agent, and session scopes. See
 [Telemetry & Logs](#telemetry--logs) below for the event catalog, emit contract, and structured-log table.
 
+### Wire-Communication Events
+
+A separate, opt-in diagnostic channel that surfaces outbound LLM communication. Distinct from `onTelemetry` (SDK-level
+lifecycle and routing) and `onLog` (structured log records): wire-communication events carry the request URL, parsed
+body (where the harness can capture it), response status, and timing — for end-to-end debugging of gateway / provider
+behavior.
+
+Subscribe via `AgentManager.onWireCommunication(callback)`:
+
+```typescript
+const unsubscribe = manager.onWireCommunication((event) => {
+  switch (event.type) {
+    case 'llm-request':
+      // outbound HTTP request to the LLM provider
+      break;
+    case 'llm-response':
+      // matching response (or terminal failure)
+      break;
+    case 'wire-monitoring-not-supported':
+      // harness can't emit per-call events for this stream;
+      // event.message points at the workaround (typically a debug log file path)
+      break;
+  }
+});
+```
+
+**Discriminated union — three variants keyed on `type`:**
+
+| `type`                          | Fields                                                                                                                                                                                                                  |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `llm-request`                   | `timestamp`, `url`, `method`, `model`, `body?`                                                                                                                                                                          |
+| `llm-response`                  | `timestamp`, `model`, `status`, `xClientTraceId?`, `totalDurationMs?`, `timeToFirstTokenMs?`, `usage?` (`inputTokens?`, `outputTokens?`, `totalTokens?`, `reasoningTokens?`), `responseText?`, `error?` ({ `message` }) |
+| `wire-monitoring-not-supported` | `timestamp`, `harnessId`, `message` (free-form text — typically explains why direct wire monitoring isn't available and points at a fallback log file the harness wrote)                                                |
+
+**Privacy contract.** Events MAY contain user prompts, tool arguments, and model output in the `body` field. They are
+**not** flowed to the structured-log channel by default — consumers opt in to wire-level visibility explicitly via
+`onWireCommunication`. Apply your own redaction / scrubbing before persisting or sharing. Note that request HTTP headers
+(e.g. `Authorization`) are **not** captured on the events; the harness's fetch wrapper sees them but doesn't forward
+them onto the channel.
+
+**Subscriber-gated end-to-end.** The chain `harness.wireBus → router slice → manager.wireBus` uses
+`EventBus.forwardWhileSubscribed` (from `@salesforce/agentic-common`), so a manager with zero `onWireCommunication`
+listeners leaves every link cold. Harnesses can read `wireBus.listenerCount > 0` and skip the work entirely — the Claude
+harness in particular skips writing the subprocess's debug log when nobody is listening. Subscribe **before** the
+`chat()` you want to inspect: subscriptions added mid-stream miss the in-flight subprocess on Claude (the listener count
+is captured at stream-start).
+
+**Cross-harness coverage.**
+
+- **Mastra harness**: emits one `llm-request` + one `llm-response` per outbound HTTP call to the LLM provider (every
+  provider — Bedrock-Anthropic, direct Anthropic, OpenAI Responses, OpenAI Chat Completions). The body is captured from
+  the in-process fetch wrapper.
+- **Claude harness**: cannot emit per-call events because the Claude Agent SDK runs the model client in a subprocess
+  with no programmatic HTTP-interception seam. Instead, when at least one consumer is subscribed at stream-start, the
+  harness writes the subprocess's debug log to `${storageRoot}/claude-debug-logs/${agentId}__${threadId}.log` (one file
+  per thread; turns of the same conversation accumulate, separated by greppable `# Turn started: <ISO>` banners) and
+  emits a single `wire-monitoring-not-supported` event whose `message` field embeds the file path. The file is left in
+  place; the consumer is responsible for retention and cleanup.
+
+#### `WireCommunicationFileWriter`
+
+Convenience writer that subscribes to a `WireCommunicationEmitter` (typically the `AgentManager`) and appends each event
+to a Markdown file. Used for debugging sessions where you want a chronological transcript without building one yourself.
+
+```typescript
+import { WireCommunicationFileWriter } from '@salesforce/sfdx-agent-sdk';
+
+const writer = new WireCommunicationFileWriter(manager, {
+  filePath: '/tmp/wire-communication.md',
+  // optional — invoked on appendFile failure; defaults to console.error
+  onError: (err, event) => {
+    /* … */
+  },
+});
+
+// later
+writer.detach();
+```
+
+The output file is plain Markdown with one `### <iso-timestamp> [llm-request]`, `[llm-response]`, or
+`[wire-monitoring-not-supported]` header per event followed by the populated fields. Optional fields are emitted only
+when set — sparse responses do not pad the file with empty `**Field**: N/A` lines. On the Claude harness, the
+`wire-monitoring-not-supported` block links to the per-thread debug log file where raw wire detail can be inspected
+directly.
+
+The same privacy contract applies: the resulting file may contain prompts, tool arguments, and model output. Treat it as
+sensitive and apply your own retention / scrubbing rules before sharing.
+
+##### `WireCommunicationFileWriterOptions`
+
+| Field      | Type                                                    | Description                                                                                                                                                                                                                        |
+| ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `filePath` | `string`                                                | Absolute (or cwd-relative) path the writer appends Markdown to. Required.                                                                                                                                                          |
+| `onError?` | `(error: Error, event: WireCommunicationEvent) => void` | Optional callback invoked when an `appendFile` rejection is observed (disk full, parent directory unwritable, etc.). Without this, write failures are routed to `console.error` so a debugging session can't silently lose events. |
+
+##### `WireCommunicationEmitter`
+
+The shape `WireCommunicationFileWriter` accepts. Anything exposing `onWireCommunication(callback)` works — typically an
+`AgentManager`, but tests may construct a smaller surface.
+
+```typescript
+type WireCommunicationEmitter = {
+  onWireCommunication(callback: (event: WireCommunicationEvent) => void): Unsubscribe;
+};
+```
+
 ### Harness Extensibility
 
 The `AgentHarness` contract is the SDK's lowest-common-denominator surface — every harness implements it, and the SDK
@@ -1161,6 +1425,14 @@ All variants share `{ type: <discriminant>, timestamp: Date }` plus the fields b
 | `mcp-server-discovery-failed`    | `agentId`, `serverName`, `durationMs`, `error`, `errorDetail?` ([`McpServerErrorDetail`](#mcpservererrordetail))  |
 | `mcp-server-status-changed`      | `agentId`, `serverName`, `previousStatus`, `nextStatus`, `error?`                                                 |
 
+Each variant is also exported as a named type so consumers can write narrowed handlers: `AgentCreatedEvent`,
+`AgentDestroyedEvent`, `SessionCreatedEvent`, `SessionDestroyedEvent`, `ChatStreamStartedEvent`,
+`ChatStreamCompletedEvent`, `ChatStreamErrorEvent`, `ToolExecutionStartedEvent`, `ToolExecutionCompletedEvent`,
+`ToolApprovalRequestedEvent`, `ToolApprovalResolvedEvent`, `McpServerDiscoveryStartedEvent`,
+`McpServerDiscoveryCompletedEvent`, `McpServerDiscoveryFailedEvent`, `McpServerStatusChangedEvent`. The
+`ChatStreamTrigger` union (`'chat' | 'submit-tool-result' | 'approve-tool-call' | 'decline-tool-call'`) and
+`TelemetryEventCallback` (the `onTelemetry` argument shape) are exported alongside.
+
 `mcp-server-status-changed` fires on every per-server status transition — emitted in addition to the discovery trio so
 consumers can route on the `(previousStatus, nextStatus)` pair without polling `getMcpServerInfo()`. A reconnect on a
 previously-`connected` server emits, in order: `connected → reconnecting`, then on success `reconnecting → connected`,