@salesforce/sfdx-agent-harness-claude 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to `@salesforce/sfdx-agent-harness-claude` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.19.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))
+
+## [0.18.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.17.0] - 2026-06-15
 
 ### Fixes

package/README.md

@@ -15,37 +15,39 @@ npm install @salesforce/sfdx-agent-sdk @salesforce/sfdx-agent-harness-claude
 ## Quick start
 
 ```ts
-import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
-import { ClaudeHarnessFactory, DirectClaudeTransportResolver } from '@salesforce/sfdx-agent-harness-claude';
+import { createAgentManager, DefaultAgentConnectivityResolver } from '@salesforce/sfdx-agent-sdk';
+import { ClaudeHarnessFactory } from '@salesforce/sfdx-agent-harness-claude';
 
 const harnessFactory = new ClaudeHarnessFactory({
-  resolver: new DirectClaudeTransportResolver(() => process.env.ANTHROPIC_API_KEY!),
   permissionMode: 'bypassPermissions',
 });
 
-const manager = await createAgentManager('/path/to/storage', harnessFactory);
+const manager = await createAgentManager('/path/to/storage', harnessFactory, {
+  connectivityResolver: new DefaultAgentConnectivityResolver(),
+});
 ```
 
+Connectivity (gateway URL, JWT, headers, native model id) is resolved by an `AgentConnectivityResolver` on the SDK and
+handed to the harness as a `ModelConnectivityInfo` bag. The harness factory itself owns harness-only concerns
+(permission mode, tool-approval timeout, bypass list, query defaults). For BYOK / direct-Anthropic / LLMG-Express
+deployments use `ApiKeyConnectivityResolver`; for non-Salesforce hosts implement your own resolver. See the
+[`@salesforce/sfdx-agent-sdk` README](../sfdx-agent-sdk/README.md) for the full resolver surface.
+
 See the [`@salesforce/sfdx-agent-sdk` README](../sfdx-agent-sdk/README.md) for the full consumer-facing API. For
 internal architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ## Public API
 
-| Export                                           | Kind      | Description                                                                                                                                                          |
-| ------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ClaudeHarnessFactory`                           | class     | `HarnessFactory` that produces a Claude-backed `AgentHarness` bound to a storage root.                                                                               |
-| `ClaudeHarnessFactoryConfig`                     | interface | Configuration for `ClaudeHarnessFactory` (`resolver`, `permissionMode`, optional `queryDefaults`, `toolApprovalTimeoutMs`, `bypassApprovalTools`).                   |
-| `ClaudeHarnessPermissionMode`                    | type      | Narrowed permission mode: `'bypassPermissions' \| 'acceptEdits' \| 'plan'`.                                                                                          |
-| `ClaudeAgentHarness`                             | type      | Branded `AgentHarness` subtype carrying the Claude-specific config inference. Inferred at `manager.createAgent` automatically — annotation rarely needed.            |
-| `ClaudeAgentConfig`                              | type      | `AgentConfig` extended with Claude-only fields (`skillSearch`, `toolSearch`).                                                                                        |
-| `ClaudeSkillSearchConfig`                        | type      | Shape of `ClaudeAgentConfig.skillSearch` (`topK`). Opts the in-process `skill_bridge` MCP server into search-on-demand mode.                                         |
-| `ClaudeToolSearchConfig`                         | type      | Shape of `ClaudeAgentConfig.toolSearch` (`alwaysActive`). Stamps `_meta['anthropic/alwaysLoad']` on matching tools so they bypass Claude tool-search deferral.       |
-| `ClaudeTransportResolver`                        | interface | Strategy for resolving transport env, auth, and native model ID for the subprocess.                                                                                  |
-| `ClaudeTransportResolverResult`                  | type      | Return type of `ClaudeTransportResolver.resolve()` (`env` + `nativeModelId`).                                                                                        |
-| `ClaudeQueryDefaults`                            | type      | Consumer-overridable defaults for the Claude `query()` call (excludes `model`).                                                                                      |
-| `DirectClaudeTransportResolver`                  | class     | Resolver for direct Anthropic API access (sets `ANTHROPIC_API_KEY`). Suitable for local dev with a personal API key; not the production path.                        |
-| `SalesforceBedrockClaudeTransportResolver`       | class     | Resolver that routes the Claude subprocess through the Salesforce LLM Gateway's Bedrock proxy. Canonical production path for Salesforce developer-tooling consumers. |
-| `SalesforceBedrockClaudeTransportResolverConfig` | interface | Configuration for `SalesforceBedrockClaudeTransportResolver` (`gatewayBaseUrl`, optional `modelIdMap`, `appContext`, `featureId`, `ideContext`).                     |
+| Export                        | Kind      | Description                                                                                                                                                    |
+| ----------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ClaudeHarnessFactory`        | class     | `HarnessFactory` that produces a Claude-backed `AgentHarness` bound to a storage root.                                                                         |
+| `ClaudeHarnessFactoryConfig`  | interface | Configuration for `ClaudeHarnessFactory` (`permissionMode`, optional `queryDefaults`, `toolApprovalTimeoutMs`, `bypassApprovalTools`, `dispatcher`).           |
+| `ClaudeHarnessPermissionMode` | type      | Narrowed permission mode: `'bypassPermissions' \| 'acceptEdits' \| 'plan'`.                                                                                    |
+| `ClaudeAgentHarness`          | type      | Branded `AgentHarness` subtype carrying the Claude-specific config inference. Inferred at `manager.createAgent` automatically — annotation rarely needed.      |
+| `ClaudeAgentConfig`           | type      | `AgentConfig` extended with Claude-only fields (`skillSearch`, `toolSearch`).                                                                                  |
+| `ClaudeSkillSearchConfig`     | type      | Shape of `ClaudeAgentConfig.skillSearch` (`topK`). Opts the in-process `skill_bridge` MCP server into search-on-demand mode.                                   |
+| `ClaudeToolSearchConfig`      | type      | Shape of `ClaudeAgentConfig.toolSearch` (`alwaysActive`). Stamps `_meta['anthropic/alwaysLoad']` on matching tools so they bypass Claude tool-search deferral. |
+| `ClaudeQueryDefaults`         | type      | Consumer-overridable defaults for the Claude `query()` call (excludes `model`).                                                                                |
 
 ### Permission modes
 
@@ -61,6 +63,19 @@ provide. For human-in-the-loop gating, set `StreamOptions.requireToolApproval: t
 installs a `PreToolUse` SDK hook for that turn that gates every tool call through the SDK's `tool-approval-request` flow
 regardless of the factory-pinned permission mode.
 
+### HTTPS proxy routing
+
+The harness honors `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` (either casing) for the host-side MCP HTTP transport via
+`@salesforce/agentic-common`'s `resolveProxyDispatcher()`. When either proxy var is set at factory `create()` time, the
+harness wraps the transport `fetch` with an undici-backed routing function — no `globalThis` mutation. When no proxy
+env is set, `fetch` runs unwrapped (zero overhead).
+
+The Claude subprocess inherits `HTTPS_PROXY` from the host env separately and is unaffected by the host-side wrapping.
+Subprocess-side proxy routing follows whatever env was set when the subprocess spawned.
+
+**Snapshot timing.** `HTTPS_PROXY` / `HTTP_PROXY` are captured at `create()` time and pinned for the harness's lifetime;
+`NO_PROXY` is re-evaluated per request. Set the proxy env vars before constructing the factory's first harness.
+
 ### Skill search
 
 `AgentConfig.skills` is a cross-harness field; both Mastra and Claude surface configured skills to the model. By default
@@ -201,65 +216,25 @@ afterwards.
 > (which `break` does inside `for await`) finalizes the harness's source generator before the terminal event can reach
 > you. Settle in-line and keep iterating; the loop exits naturally when the terminal `finish` arrives.
 
-### Using the Salesforce Bedrock resolver
+### Connectivity (gateway URL, auth, native model id)
 
-The canonical production path for Salesforce developer-tooling consumers. Routes the Claude subprocess through the
-Salesforce LLM Gateway's Bedrock proxy using an org JWT for auth.
+The Claude harness reads connectivity per-spawn from a `ModelConnectivityInfo` bag the SDK hands it. The bag carries the
+gateway base URL, the native model id (e.g. `anthropic.claude-sonnet-4-6`), the provider hint (`bedrock-anthropic` or
+`anthropic`), and a `getHeaders()` callback the harness invokes once per subprocess spawn. JWT rotation rides on that
+callback — the next `stream()` call reads the rotated JWT through the same closure without rebuilding anything.
 
-```ts
-import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
-import { ClaudeHarnessFactory, SalesforceBedrockClaudeTransportResolver } from '@salesforce/sfdx-agent-harness-claude';
+The SDK ships two bundled resolvers and a documented extension point — see the
+[`@salesforce/sfdx-agent-sdk` README](../sfdx-agent-sdk/README.md):
 
-const harnessFactory = new ClaudeHarnessFactory({
-  resolver: new SalesforceBedrockClaudeTransportResolver({
-    // Pick the gateway URL for your environment — e.g. test:
-    gatewayBaseUrl: 'https://test.api.salesforce.com/ai/gpt/v1',
-    // No `modelIdMap` needed in the common case: the LLM Gateway's invoke API
-    // accepts the gateway-prefixed canonical id (`llmgateway__Bedrock*`) for
-    // every Anthropic Claude model, and the SDK's `Model.name` is already that
-    // canonical id, so the resolver's default passthrough is correct. Set the
-    // map only if your consumer needs to translate to a different shape (e.g.
-    // a self-hosted Bedrock proxy that expects the bare-native ids).
-    // Optional: override the `x-client-feature-id` header. Defaults to `orgJwt.getFeatureId()`.
-    featureId: 'EinsteinGptForDevelopers',
-    // Optional: getter for the `x-aip-user-ctx-tag` header. Invoked on every `resolve()`;
-    // returning `undefined` (or omitting the option) drops the header. Use when the tag is
-    // derived from post-JWT-mint state that changes between turns.
-    ideContext: () => orgEntitlement.ideUserContext,
-  }),
-  permissionMode: 'bypassPermissions',
-});
+- **`DefaultAgentConnectivityResolver`** — Salesforce-org gateway path. Targets the LLM Gateway's pass-through Bedrock
+  endpoint (`/invoke-with-response-stream`) using an org JWT.
+- **`ApiKeyConnectivityResolver`** — direct-Anthropic / OpenAI-direct / LLMG-Express. Constructor takes
+  `{ getApiKey, baseUrl, providerHint, ... }`.
+- **Custom `AgentConnectivityResolver`** — for deployments neither bundled resolver covers, implement the SDK's
+  `AgentConnectivityResolver` interface and pass it to `createAgentManager({ ..., connectivityResolver })`.
 
-const manager = await createAgentManager('/path/to/storage', harnessFactory);
-```
-
-JWT refresh works the same as elsewhere in the harness: each `resolve()` call eagerly reads `orgJwt.getValue()` /
-`orgJwt.getTenantKey()` and freezes the result into the static subprocess headers. `Agent.updateAgentConfig({})` runs
-`harness.updateAgent`, the resolver re-reads the fresh JWT on the next `stream()`, and the next subprocess spawns with
-the new headers — connected MCP clients are preserved through the rotation.
-
-### Using a custom resolver
-
-For deployment topologies neither built-in resolver covers (alternative gateways, custom auth flows, etc.), implement
-the `ClaudeTransportResolver` interface directly.
-
-```ts
-import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
-import { ClaudeHarnessFactory } from '@salesforce/sfdx-agent-harness-claude';
-import type { ClaudeTransportResolver } from '@salesforce/sfdx-agent-harness-claude';
-
-const resolver: ClaudeTransportResolver = {
-  async resolve(orgJwt, modelId) {
-    return {
-      env: { ANTHROPIC_API_KEY: '...' },
-      nativeModelId: 'anthropic.claude-sonnet-4-6',
-    };
-  },
-};
-
-const harnessFactory = new ClaudeHarnessFactory({ resolver, permissionMode: 'bypassPermissions' });
-const manager = await createAgentManager('/path/to/storage', harnessFactory);
-```
+The harness factory itself takes no resolver, gateway URL, or auth field — those concerns live entirely on the
+connectivity resolver.
 
 ### Per-server MCP reconnect (eager semantics)
 
@@ -287,7 +262,6 @@ reject.
 
 ```ts
 const harnessFactory = new ClaudeHarnessFactory({
-  resolver: new DirectClaudeTransportResolver(() => process.env.ANTHROPIC_API_KEY!),
   permissionMode: 'bypassPermissions',
   queryDefaults: {
     maxTurns: 5,
@@ -307,11 +281,10 @@ across harnesses.
 `ClaudeQueryDefaults` does not strip). It blocks the model from emitting `tool_use` for the named built-ins entirely.
 
 ```ts
-import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
-import { ClaudeHarnessFactory, SalesforceBedrockClaudeTransportResolver } from '@salesforce/sfdx-agent-harness-claude';
+import { createAgentManager, DefaultAgentConnectivityResolver } from '@salesforce/sfdx-agent-sdk';
+import { ClaudeHarnessFactory } from '@salesforce/sfdx-agent-harness-claude';
 
 const harnessFactory = new ClaudeHarnessFactory({
-  resolver: new SalesforceBedrockClaudeTransportResolver({ gatewayBaseUrl: '...' }),
   permissionMode: 'bypassPermissions',
   // Suppress the built-in `AskUserQuestion` so the cross-harness consumer
   // tool below is the only ask-the-user surface the model sees on Claude
@@ -321,7 +294,9 @@ const harnessFactory = new ClaudeHarnessFactory({
   },
 });
 
-const manager = await createAgentManager('/path/to/storage', harnessFactory);
+const manager = await createAgentManager('/path/to/storage', harnessFactory, {
+  connectivityResolver: new DefaultAgentConnectivityResolver(),
+});
 const agent = await manager.createAgent(projectRoot, {
   instructions: '...',
   tools: [
@@ -360,7 +335,6 @@ additional tool names out of the gate.
 
 ```ts
 const harnessFactory = new ClaudeHarnessFactory({
-  resolver: new SalesforceBedrockClaudeTransportResolver({ gatewayBaseUrl: '...' }),
   permissionMode: 'bypassPermissions',
   // Even when `requireToolApproval: true`, calls to these tools bypass the
   // PreToolUse hook. They still emit `tool-call` / `tool-result` ChatEvents,

package/dist/claude-harness-factory.d.ts

@@ -1,5 +1,4 @@
-import type { HarnessFactory } from '@salesforce/sfdx-agent-sdk';
-import type { ClaudeTransportResolver } from './claude-transport-resolver.js';
+import type { HarnessFactory, ProviderHint } from '@salesforce/sfdx-agent-sdk';
 import type { ClaudeQueryDefaults } from './claude-query-options-builder.js';
 import { type ClaudeAgentHarness } from './claude-harness.js';
 /**
@@ -13,7 +12,6 @@ import { type ClaudeAgentHarness } from './claude-harness.js';
  */
 export type ClaudeHarnessPermissionMode = 'bypassPermissions' | 'acceptEdits' | 'plan';
 export interface ClaudeHarnessFactoryConfig {
-    resolver: ClaudeTransportResolver;
     permissionMode: ClaudeHarnessPermissionMode;
     queryDefaults?: ClaudeQueryDefaults;
     /**
@@ -42,6 +40,14 @@ export declare class ClaudeHarnessFactory implements HarnessFactory<ClaudeAgentH
     private readonly config;
     readonly harnessId = "claude";
     readonly protocolVersion = 1;
+    /**
+     * The Claude CLI binary speaks Anthropic-shaped protocols only — both the
+     * Bedrock pass-through (`'bedrock-anthropic'`) and direct Anthropic API
+     * (`'anthropic'`). Routing it at a non-Anthropic model is a programming
+     * error caught at `createAgent` / `updateAgentConfig` by the manager's
+     * G8 validation.
+     */
+    readonly supportedProviderHints: readonly ProviderHint[];
     constructor(config: ClaudeHarnessFactoryConfig);
     create(storageRootFolder: string): Promise<ClaudeAgentHarness>;
 }

package/dist/claude-harness-factory.js

@@ -2,19 +2,30 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+import { createProxyAwareFetch, resolveProxyDispatcher } from '@salesforce/agentic-common';
 import { ClaudeQueryEnvBuilder } from './claude-query-env-builder.js';
 import { ClaudeQueryOptionsBuilder } from './claude-query-options-builder.js';
 import { ClaudeHarness } from './claude-harness.js';
+import { buildMcpClients } from './mcp-client-factory.js';
 const DEFAULT_TOOL_APPROVAL_TIMEOUT_MS = 600_000;
 export class ClaudeHarnessFactory {
     config;
     harnessId = 'claude';
     protocolVersion = 1;
+    /**
+     * The Claude CLI binary speaks Anthropic-shaped protocols only — both the
+     * Bedrock pass-through (`'bedrock-anthropic'`) and direct Anthropic API
+     * (`'anthropic'`). Routing it at a non-Anthropic model is a programming
+     * error caught at `createAgent` / `updateAgentConfig` by the manager's
+     * G8 validation.
+     */
+    supportedProviderHints = ['anthropic', 'bedrock-anthropic'];
     constructor(config) {
         this.config = config;
     }
     async create(storageRootFolder) {
-        const envBuilder = new ClaudeQueryEnvBuilder(this.config.resolver, storageRootFolder);
+        const innerFetch = createProxyAwareFetch(resolveProxyDispatcher());
+        const envBuilder = new ClaudeQueryEnvBuilder(storageRootFolder);
         const permissionDefaults = {
             permissionMode: this.config.permissionMode,
             ...(this.config.permissionMode === 'bypassPermissions'
@@ -27,7 +38,11 @@ export class ClaudeHarnessFactory {
         // under issue #529 — every event flows through the single
         // `initial` sink.
         const optionsBuilder = new ClaudeQueryOptionsBuilder({ ...permissionDefaults, ...this.config.queryDefaults }, new Set(this.config.bypassApprovalTools ?? []));
-        return new ClaudeHarness(envBuilder, optionsBuilder, this.config.toolApprovalTimeoutMs ?? DEFAULT_TOOL_APPROVAL_TIMEOUT_MS, storageRootFolder);
+        // Bind `innerFetch` into the mcp-client factory closure so every
+        // call site inside `ClaudeHarness` (createAgent, reconnect, updateAgent)
+        // routes MCP HTTP transports through the same proxy-aware fetch.
+        const mcpClientFactory = (config, orgJwt) => buildMcpClients(config, orgJwt, innerFetch);
+        return new ClaudeHarness(envBuilder, optionsBuilder, this.config.toolApprovalTimeoutMs ?? DEFAULT_TOOL_APPROVAL_TIMEOUT_MS, storageRootFolder, { mcpClientFactory });
     }
 }
 //# sourceMappingURL=claude-harness-factory.js.map

package/dist/claude-harness-factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude-harness-factory.js","sourceRoot":"","sources":["../src/claude-harness-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,aAAa,EAA2B,MAAM,qBAAqB,CAAC;AAa7E,MAAM,gCAAgC,GAAG,OAAO,CAAC;AA6BjD,MAAM,OAAO,oBAAoB;IAIA;IAHpB,SAAS,GAAG,QAAQ,CAAC;IACrB,eAAe,GAAG,CAAC,CAAC;IAE7B,YAA6B,MAAkC;QAAlC,WAAM,GAAN,MAAM,CAA4B;IAAG,CAAC;IAEnE,KAAK,CAAC,MAAM,CAAC,iBAAyB;QAClC,MAAM,UAAU,GAAG,IAAI,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;QACtF,MAAM,kBAAkB,GAAG;YACvB,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc;YAC1C,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,mBAAmB;gBAClD,CAAC,CAAC,EAAE,+BAA+B,EAAE,IAAa,EAAE;gBACpD,CAAC,CAAC,EAAE,CAAC;SACZ,CAAC;QACF,iEAAiE;QACjE,iEAAiE;QACjE,iEAAiE;QACjE,0DAA0D;QAC1D,kBAAkB;QAClB,MAAM,cAAc,GAAG,IAAI,yBAAyB,CAChD,EAAE,GAAG,kBAAkB,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,EACvD,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,mBAAmB,IAAI,EAAE,CAAC,CACjD,CAAC;QACF,OAAO,IAAI,aAAa,CACpB,UAAU,EACV,cAAc,EACd,IAAI,CAAC,MAAM,CAAC,qBAAqB,IAAI,gCAAgC,EACrE,iBAAiB,CACpB,CAAC;IACN,CAAC;CACJ"}
+{"version":3,"file":"claude-harness-factory.js","sourceRoot":"","sources":["../src/claude-harness-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAG3F,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,aAAa,EAA2B,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAa1D,MAAM,gCAAgC,GAAG,OAAO,CAAC;AA4BjD,MAAM,OAAO,oBAAoB;IAYA;IAXpB,SAAS,GAAG,QAAQ,CAAC;IACrB,eAAe,GAAG,CAAC,CAAC;IAC7B;;;;;;OAMG;IACM,sBAAsB,GAA4B,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAAC;IAE9F,YAA6B,MAAkC;QAAlC,WAAM,GAAN,MAAM,CAA4B;IAAG,CAAC;IAEnE,KAAK,CAAC,MAAM,CAAC,iBAAyB;QAClC,MAAM,UAAU,GAAG,qBAAqB,CAAC,sBAAsB,EAAE,CAAC,CAAC;QACnE,MAAM,UAAU,GAAG,IAAI,qBAAqB,CAAC,iBAAiB,CAAC,CAAC;QAChE,MAAM,kBAAkB,GAAG;YACvB,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc;YAC1C,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,mBAAmB;gBAClD,CAAC,CAAC,EAAE,+BAA+B,EAAE,IAAa,EAAE;gBACpD,CAAC,CAAC,EAAE,CAAC;SACZ,CAAC;QACF,iEAAiE;QACjE,iEAAiE;QACjE,iEAAiE;QACjE,0DAA0D;QAC1D,kBAAkB;QAClB,MAAM,cAAc,GAAG,IAAI,yBAAyB,CAChD,EAAE,GAAG,kBAAkB,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,EACvD,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,mBAAmB,IAAI,EAAE,CAAC,CACjD,CAAC;QACF,iEAAiE;QACjE,yEAAyE;QACzE,iEAAiE;QACjE,MAAM,gBAAgB,GAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAChE,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;QAChD,OAAO,IAAI,aAAa,CACpB,UAAU,EACV,cAAc,EACd,IAAI,CAAC,MAAM,CAAC,qBAAqB,IAAI,gCAAgC,EACrE,iBAAiB,EACjB,EAAE,gBAAgB,EAAE,CACvB,CAAC;IACN,CAAC;CACJ"}

package/dist/claude-harness.d.ts

@@ -1,8 +1,7 @@
 import { type Clock, type LogRecord, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
-import { type AgentHarness, type ChatStreamResult, type HarnessAgentConfig, type McpServerInfo, type Message, type MessagePart, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo } from '@salesforce/sfdx-agent-sdk';
+import { type AgentHarness, type ChatStreamResult, type HarnessAgentConfig, type McpServerInfo, type Message, type MessagePart, type ModelConnectivityInfo, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
 import { type AgentHooks, type WithAgentConfig } from '@salesforce/sfdx-agent-sdk/harness';
 import type { ClaudeAgentConfig } from './claude-config.js';
-import { type LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
 import type { ClaudeQueryEnvBuilder } from './claude-query-env-builder.js';
 import type { ClaudeQueryOptionsBuilder } from './claude-query-options-builder.js';
 import { buildMcpClients } from './mcp-client-factory.js';
@@ -35,6 +34,20 @@ import { ThreadContextStore } from './thread-context-store.js';
 export type ClaudeAgentHarness = WithAgentConfig<AgentHarness & {
     readonly harnessId: 'claude';
 }, ClaudeAgentConfig>;
+/**
+ * Construction options for {@link ClaudeHarness}. Internal — consumers
+ * configure the harness via {@link ClaudeHarnessFactory}. The factory threads
+ * `mcpClientFactory` (bound with the proxy-aware `innerFetch`); tests pass
+ * stubs (`clock`, `idGenerator`, `sessionStore`, `mcpClientFactory`,
+ * `threadContextStore`) directly.
+ */
+export interface ClaudeHarnessOptions {
+    clock?: Clock;
+    idGenerator?: UniqueIDGenerator;
+    sessionStore?: DiskBackedSessionStore;
+    mcpClientFactory?: typeof buildMcpClients;
+    threadContextStore?: ThreadContextStore;
+}
 export declare class ClaudeHarness implements ClaudeAgentHarness {
     private readonly envBuilder;
     private readonly optionsBuilder;
@@ -71,13 +84,52 @@ export declare class ClaudeHarness implements ClaudeAgentHarness {
      * collaborators on this constructor.
      */
     private readonly mcpClientFactory;
+    private readonly storageRootFolder;
     private shuttingDown;
-    constructor(envBuilder: ClaudeQueryEnvBuilder, optionsBuilder: ClaudeQueryOptionsBuilder, toolApprovalTimeoutMs: number, storageRootFolder: string, idGenerator?: UniqueIDGenerator, clock?: Clock, sessionStore?: DiskBackedSessionStore, mcpClientFactory?: typeof buildMcpClients, threadContextStore?: ThreadContextStore);
+    constructor(envBuilder: ClaudeQueryEnvBuilder, optionsBuilder: ClaudeQueryOptionsBuilder, toolApprovalTimeoutMs: number, storageRootFolder: string, opts?: ClaudeHarnessOptions);
     private coordinatorKey;
+    /**
+     * Returns a per-thread debug-log file path under the SDK storage root when a
+     * wire-communication consumer is subscribed; otherwise `undefined`. Callers pass the
+     * returned path as `query({ options: { debugFile } })` so the Claude subprocess writes
+     * its debug log to a file we own — and emit a `WireMonitoringNotSupportedEvent`
+     * pointing at the path immediately, before the subprocess starts.
+     *
+     * The path is **per-thread** (not per-turn): turns within the same conversation share
+     * a single file, accumulating wire data via the SDK's append-on-write behavior. A
+     * banner line written by {@link writeTurnBanner} delimits each turn within the file.
+     *
+     * Listener-count gating: relies on the wire-communication chain
+     * (`harness.wireBus → router slice → manager.wireBus`) being wired with
+     * `forwardWhileSubscribed`, so a consumer-less manager leaves
+     * `wireBus.listenerCount === 0` and this method returns `undefined` (no file written,
+     * no debug overhead in the subprocess).
+     */
+    private maybeAllocateWireDebugLogPath;
+    /**
+     * Append a turn-start banner to the per-thread wire-debug log file so consumers
+     * grepping the accumulated content can find each turn's boundary. The Claude SDK
+     * appends to `debugFile` across `query()` calls with no separator of its own; this
+     * banner makes turn boundaries explicit and version-stable.
+     */
+    private writeTurnBanner;
     shutdown(): Promise<void>;
     onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
     onLog(callback: (record: LogRecord) => void): Unsubscribe;
-    createAgent(agentId: string, projectRoot: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
+    /**
+     * The Claude harness emits `WireMonitoringNotSupportedEvent` (one per stream) when at
+     * least one consumer is subscribed at stream-start. The Claude Agent SDK runs the model
+     * client in a subprocess with no programmatic seam for HTTP-level monitoring, so per-call
+     * `LlmRequestEvent` / `LlmResponseEvent` (Mastra's contract) are not produced here;
+     * instead, the harness writes the subprocess's debug log to a file under the SDK storage
+     * root and points at it from the event's `message` field.
+     *
+     * **Subscribe-before-stream**: subscriptions added mid-stream miss the in-flight
+     * subprocess on Claude — the listener-count check happens once at `stream()` start. The
+     * next subprocess spawn (next `chat()` call) will pick up the subscriber.
+     */
+    onWireCommunication(callback: WireCommunicationEventCallback): Unsubscribe;
+    createAgent(agentId: string, projectRoot: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
         hooks?: AgentHooks;
     }): Promise<void>;
@@ -146,7 +198,7 @@ export declare class ClaudeHarness implements ClaudeAgentHarness {
      * `state.threads` is intentionally untouched — sessions are config-
      * independent, so an `updateAgent` cannot invalidate them.
      */
-    updateAgent(agentId: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
+    updateAgent(agentId: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
         hooks?: AgentHooks;
     }): Promise<void>;