@salesforce/sfdx-agent-sdk 0.15.0 → 0.16.0

package/README.md

@@ -47,7 +47,8 @@ for await (const event of eventStream) {
     process.stdout.write(event.text);
   } else if (event.type === 'error') {
     console.error(event.error.message);
-    break;
+    // Don't break — the SDK invariant guarantees a synthetic
+    // `FinishEvent('error')` follows; the loop exits naturally next tick.
   }
 }
 
@@ -152,31 +153,33 @@ keeps unparameterized call sites working.
 
 A single conversation thread.
 
-| Method              | Signature                                                                             | Description                                                                   |
-| ------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `getId`             | `() => string`                                                                        | Session/thread identifier.                                                    |
-| `chat`              | `(message: string, options?: ChatOptions) => Promise<ChatStreamResult>`               | Send a message and stream the response.                                       |
-| `submitToolResult`  | `(toolResult: ToolResultInfo) => Promise<ChatStreamResult>`                           | Return a consumer-executed tool result and resume the stream.                 |
-| `approveToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<ChatStreamResult>` | Approve a pending tool call.                                                  |
-| `declineToolCall`   | `(toolCallId: string) => Promise<ChatStreamResult>`                                   | Decline a pending tool call.                                                  |
-| `getMessageHistory` | `() => Promise<Message[]>`                                                            | Retrieve all messages in chronological order.                                 |
-| `clearHistory`      | `() => Promise<void>`                                                                 | Delete all messages.                                                          |
-| `getContextUsage`   | `() => ContextUsage`                                                                  | Snapshot of how much of the model's context window the most recent turn used. |
-| `addContext`        | `(message: string \| Message[]) => Promise<void>`                                     | Inject context without triggering an LLM response.                            |
-| `subscribe`         | `(callback: (event: ChatEvent) => void) => void`                                      | Register a real-time event listener.                                          |
-| `unsubscribe`       | `(callback: (event: ChatEvent) => void) => void`                                      | Remove a listener.                                                            |
-| `onTelemetry`       | `(callback: TelemetryEventCallback) => Unsubscribe`                                   | Subscribe to telemetry scoped to this session.                                |
-| `onLog`             | `(callback: (record: LogRecord) => void) => Unsubscribe`                              | Subscribe to logs scoped to this session.                                     |
-| `dispose`           | `() => void`                                                                          | Release session-level event resources. Idempotent.                            |
+| Method              | Signature                                                                 | Description                                                                                                                |
+| ------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `getId`             | `() => string`                                                            | Session/thread identifier.                                                                                                 |
+| `chat`              | `(message: string, options?: ChatOptions) => Promise<ChatStreamResult>`   | Send a message and stream the response. The returned `eventStream` is the single iterator for the entire chat turn.        |
+| `submitToolResult`  | `(toolResult: ToolResultInfo) => Promise<void>`                           | Return a consumer-executed tool result. Control message on the existing turn — post-resume events flow on the same stream. |
+| `approveToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<void>` | Approve a pending tool call. Control message on the existing turn — post-resume events flow on the same stream.            |
+| `declineToolCall`   | `(toolCallId: string) => Promise<void>`                                   | Decline a pending tool call. Control message on the existing turn — post-resume events flow on the same stream.            |
+| `getMessageHistory` | `() => Promise<Message[]>`                                                | Retrieve all messages in chronological order.                                                                              |
+| `clearHistory`      | `() => Promise<void>`                                                     | Delete all messages.                                                                                                       |
+| `getContextUsage`   | `() => ContextUsage`                                                      | Snapshot of how much of the model's context window the most recent turn used.                                              |
+| `addContext`        | `(message: string \| Message[]) => Promise<void>`                         | Inject context without triggering an LLM response.                                                                         |
+| `subscribe`         | `(callback: (event: ChatEvent) => void) => void`                          | Register a real-time event listener.                                                                                       |
+| `unsubscribe`       | `(callback: (event: ChatEvent) => void) => void`                          | Remove a listener.                                                                                                         |
+| `onTelemetry`       | `(callback: TelemetryEventCallback) => Unsubscribe`                       | Subscribe to telemetry scoped to this session.                                                                             |
+| `onLog`             | `(callback: (record: LogRecord) => void) => Unsubscribe`                  | Subscribe to logs scoped to this session.                                                                                  |
+| `dispose`           | `() => void`                                                              | Release session-level event resources. Idempotent.                                                                         |
 
 ### `ChatStreamResult`
 
-Returned by `chat()`, `submitToolResult()`, `approveToolCall()`, and `declineToolCall()`.
+Returned by `chat()`. The single `eventStream` covers the entire chat turn — including post-resume events from
+`submitToolResult` / `approveToolCall` / `declineToolCall`. Settle methods return `Promise<void>`; the consumer keeps
+iterating the same `eventStream` until it sees a terminal `finish` event.
 
-| Property      | Type                        | Description                             |
-| ------------- | --------------------------- | --------------------------------------- |
-| `eventStream` | `AsyncGenerator<ChatEvent>` | Full lifecycle event stream.            |
-| `textStream`  | `AsyncGenerator<string>`    | Convenience stream of text-only tokens. |
+| Property      | Type                        | Description                                                                  |
+| ------------- | --------------------------- | ---------------------------------------------------------------------------- |
+| `eventStream` | `AsyncGenerator<ChatEvent>` | Full lifecycle event stream for the turn (one stream per `chat()` call).     |
+| `textStream`  | `AsyncGenerator<string>`    | Convenience stream of text-only tokens, derived from the same `eventStream`. |
 
 ### `ChatEvent`
 
@@ -560,17 +563,17 @@ try {
 
 #### Streaming method failures
 
-The four streaming methods on `ChatSession` — `chat()`, `submitToolResult()`, `approveToolCall()`, and
-`declineToolCall()` — share a single failure contract. Subscribers registered via `subscribe()` are guaranteed to
+`chat()` opens a turn; `submitToolResult()` / `approveToolCall()` / `declineToolCall()` are control messages on the
+existing turn. All four share a single failure contract. Subscribers registered via `subscribe()` are guaranteed to
 receive a terminal event for every turn:
 
-- **Pre-stream failure** (the harness rejects before producing a stream): subscribers receive an `ErrorEvent` followed
-  by a `FinishEvent(finishReason: 'error')`, and the returned promise then rejects with the original error. Wrap the
-  call in `try/catch` if you need to handle this in the caller.
-- **In-stream failure** (the stream yields an `error` event or the underlying generator throws): the `eventStream`
-  yields the `ErrorEvent` (synthesizing one from a thrown exception if needed) and, if no `FinishEvent` was already
-  emitted, appends a synthetic `FinishEvent(finishReason: 'error')` at the end. The returned promise resolves normally;
-  iterate the stream to observe the failure.
+- **Pre-stream failure** (the harness rejects before producing a stream, or a settle call rejects before it routes the
+  decision): subscribers receive an `ErrorEvent` followed by a `FinishEvent(finishReason: 'error')`, and the returned
+  promise then rejects with the original error. Wrap the call in `try/catch` if you need to handle this in the caller.
+- **In-stream failure** (the active `eventStream` yields an `error` event or the underlying generator throws): the
+  stream yields the `ErrorEvent` (synthesizing one from a thrown exception if needed) and, if no `FinishEvent` was
+  already emitted, appends a synthetic `FinishEvent(finishReason: 'error')` at the end. The originating `chat()` promise
+  resolves normally; iterate the stream to observe the failure.
 - **Calling a disposed session** throws `AgentSDKError('DISPOSED')` synchronously without notifying subscribers.
 
 ### MCP Server Configuration
@@ -613,99 +616,158 @@ reparsing namespaced tool names. `annotations` is `undefined` when the source di
 `requireToolApproval` accepts a `boolean` (`true` is shorthand for `'serial'`) or one of the mode strings exposed via
 the `ToolApprovalMode` type alias (`'serial' | 'batch'`):
 
-- **`'serial'`** (the safe default) — each stream surfaces one `tool-approval-request` at a time. The next request, if
-  any, appears on the continuation stream returned by `approveToolCall` / `declineToolCall`. Works with both consumer
-  iterator patterns below.
-- **`'batch'`** — when the model emits parallel `tool_use` blocks, all approval-requests surface on the same stream so
-  the consumer can render a batch-approval card. **Pattern A iterators only** — a `break`-on-first-approval loop will
-  miss the subsequent approvals and hang the chat. Opt into `'batch'` only after the consumer iterator collects all
-  approvals before settling.
+- **`'serial'`** (the safe default) — `tool-approval-request` events surface one at a time. The next request (if any)
+  arrives later on the same `eventStream` after the consumer settles the current one.
+- **`'batch'`** — when the model emits parallel `tool_use` blocks, all approval-requests for that batch surface on the
+  same `eventStream` together, so the consumer can render a batch-approval card. The consumer must gather all approvals
+  before settling — a `break`-on-first-approval loop will hang the turn because Mastra/Claude won't continue emitting
+  tool-results until the consumer has settled the entire batch.
 
 The SDK also exports `resolveToolApprovalMode(value)` — the canonical
 `boolean | ToolApprovalMode | undefined → ToolApprovalMode | undefined` normalizer harness implementations should use to
 dispatch (`undefined` / `false` → `undefined`, `true` → `'serial'`, strings pass through). Reject unknown strings via
 `throw` instead of reimplementing the boolean-vs-string branch — the helper's defensive throw catches `as any` consumers
-passing invalid values that would otherwise silently degrade to "approval gating on but no broker allocated."
+passing invalid values that would otherwise silently degrade to "approval gating on but no coordinator allocated."
+
+#### Single stream per turn
 
-> **Glossary:** _Pattern A_ = "collect-all-then-settle" (iterate until natural park, gather all approval-requests, then
-> call `approveToolCall`/`declineToolCall`). _Pattern B_ = "return-on-first-approval" (settle the first approval
-> mid-iteration, then re-iterate the continuation stream). `'serial'` works with either; `'batch'` requires Pattern A.
+Issue [#529](https://github.com/forcedotcom/agentic-dx/issues/529) settled the harness contract: **one `eventStream` per
+chat turn.** Settle calls (`approveToolCall` / `declineToolCall` / `submitToolResult`) return `Promise<void>` and behave
+as control messages on the existing turn; the post-resume events (`tool-result`, follow-up `text-delta`, `step-finish`,
+terminal `finish`) flow through the **same** `eventStream` the `chat()` call returned. The consumer should iterate that
+one stream until it sees a terminal `finish` event, calling `approveToolCall` / `declineToolCall` / `submitToolResult`
+in-line as approval-requests / consumer-tool-calls arrive.
 
-#### Pattern B — return on first approval (works with `'serial'`)
+#### Pattern: settle in-line, continue iterating
+
+The same shape works for `'serial'` and `'batch'` mode:
 
 ```typescript
 const { eventStream } = await session.chat('Run the deployment', {
-  requireToolApproval: true, // or 'serial'
+  requireToolApproval: true, // or 'serial' / 'batch'
 });
 
 for await (const event of eventStream) {
   if (event.type === 'tool-approval-request') {
     const approved = await promptUser(event);
-    const continuation = approved
-      ? await session.approveToolCall(event.toolCall.toolCallId)
-      : await session.declineToolCall(event.toolCall.toolCallId);
-    for await (const e of continuation.eventStream) {
-      // process continuation
+    if (approved) {
+      await session.approveToolCall(event.toolCall.toolCallId);
+    } else {
+      await session.declineToolCall(event.toolCall.toolCallId);
     }
-    break; // safe: serial mode surfaces at most one approval per stream
+    // Do NOT break — keep iterating; tool-result and follow-up text arrive on the same stream.
+  } else if (event.type === 'tool-call' && event.serverName === undefined && isConsumerTool(event.toolName)) {
+    // Consumer-executed tool: run locally, return the result via submitToolResult.
+    const result = await runLocally(event.args);
+    await session.submitToolResult({
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      result,
+    });
+  } else if (event.type === 'text-delta') {
+    process.stdout.write(event.text);
+  } else if (event.type === 'finish') {
+    // Don't break on `'error'` directly — the SDK invariant guarantees an
+    // `error` event is followed by a synthetic `FinishEvent('error')` so
+    // the loop exits naturally on the next iteration. Breaking on `error`
+    // would finalize the iterator before the synthetic `finish` lands and
+    // bypass any per-turn cleanup the harness wires onto the source's
+    // close/return path.
+    break;
   }
 }
 ```
 
-#### Pattern A — collect all approvals, then settle (required for `'batch'`)
+#### Pattern variant: batch-collect approvals before settling
+
+Same single-stream loop, just gather the batch before deciding (useful for "approve these N tools?" UI cards under
+`requireToolApproval: 'batch'`):
 
 ```typescript
 const { eventStream } = await session.chat('Run the deployment', {
   requireToolApproval: 'batch',
 });
 
-const requests: ToolApprovalRequestEvent[] = [];
+const pendingBatch: ToolApprovalRequestEvent[] = [];
+
 for await (const event of eventStream) {
   if (event.type === 'tool-approval-request') {
-    requests.push(event); // do NOT break — collect the whole parallel batch
+    pendingBatch.push(event);
+    // Heuristic: settle the batch on a quiet window OR after the expected count.
+    // Don't break — the harness needs us to settle so it can continue.
+    continue;
   }
-  if (event.type === 'finish' || event.type === 'error') break;
-}
-
-// Render a batch-approval card; settle each decision.
-const decisions = await promptUserForBatch(requests);
-let continuation: ChatStreamResult | undefined;
-for (const event of requests) {
-  continuation = decisions.get(event.toolCall.toolCallId)
-    ? await session.approveToolCall(event.toolCall.toolCallId)
-    : await session.declineToolCall(event.toolCall.toolCallId);
-}
-if (continuation) {
-  for await (const e of continuation.eventStream) {
-    // process the model's follow-up turn
+  if (event.type === 'tool-call') {
+    // The harness emits `tool-approval-request` BEFORE `tool-call` in batch mode.
+    // Once we see a tool-call, the batch for this assistant message is complete.
+    if (pendingBatch.length > 0) {
+      const decisions = await promptUserForBatch(pendingBatch);
+      await Promise.all(
+        pendingBatch.map((req) =>
+          decisions.get(req.toolCall.toolCallId)
+            ? session.approveToolCall(req.toolCall.toolCallId)
+            : session.declineToolCall(req.toolCall.toolCallId),
+        ),
+      );
+      pendingBatch.length = 0;
+    }
+  } else if (event.type === 'text-delta') {
+    process.stdout.write(event.text);
+  } else if (event.type === 'finish') {
+    // Don't break on `'error'` directly — the SDK invariant guarantees an
+    // `error` event is followed by a synthetic `FinishEvent('error')` so
+    // the loop exits naturally on the next iteration. Breaking on `error`
+    // would finalize the iterator before the synthetic `finish` lands and
+    // bypass any per-turn cleanup the harness wires onto the source's
+    // close/return path.
+    break;
   }
 }
 ```
 
-#### `textStream` and `'batch'` mode
-
-`ChatStreamResult.textStream` is empty on the initial stream when `requireToolApproval: 'batch'` surfaces approval
-requests — the model emitted `tool_use` blocks, not text. Read text deltas from the continuation stream returned by
-`approveToolCall` / `declineToolCall` (the model's follow-up turn after tool execution).
+> **AsyncIterator gotcha:** the `for await` loop is the supported way to drain `eventStream`. If you instead drive the
+> iterator manually (`iter.next()`), call **at most one** `next()` at a time and `await` the result before the next
+> call. Calling `iter.next()` twice without awaiting the first orphans the first request — JS settles `.next()` calls
+> FIFO, so the next yielded value satisfies the orphaned request and is invisible to the caller. Stick to `for await`
+> unless you have a specific reason not to.
 
 ### Consumer-Executed Tools
 
+Tools declared via `AgentConfig.tools` (no `execute` function) run on the consumer side: the model emits a `tool-call`
+event, the consumer runs the tool locally, then calls `session.submitToolResult(...)` to feed the result back.
+`submitToolResult` returns `Promise<void>`; the model's follow-up turn (and any subsequent `tool-call`s) flows through
+the same `eventStream`:
+
 ```typescript
+const { eventStream } = await session.chat('Look up the customer record for tenant T-42.');
+
 for await (const event of eventStream) {
-  if (event.type === 'tool-call' && event.toolName === 'my-tool') {
+  if (event.type === 'tool-call' && event.toolName === 'lookup_customer') {
     const result = await runLocally(event.args);
-    const continuation = await session.submitToolResult({
+    await session.submitToolResult({
       toolCallId: event.toolCallId,
       toolName: event.toolName,
       result,
     });
-    for await (const e of continuation.eventStream) {
-      // process continuation
-    }
+    // Do NOT break — the model's follow-up turn (text, more tool-calls, finish) arrives on the same stream.
+  } else if (event.type === 'text-delta') {
+    process.stdout.write(event.text);
+  } else if (event.type === 'finish') {
+    // Don't break on `'error'` directly — the SDK invariant guarantees an
+    // `error` event is followed by a synthetic `FinishEvent('error')` so
+    // the loop exits naturally on the next iteration. Breaking on `error`
+    // would finalize the iterator before the synthetic `finish` lands and
+    // bypass any per-turn cleanup the harness wires onto the source's
+    // close/return path.
+    break;
   }
 }
 ```
 
+When `requireToolApproval: true` is also set, consumer-executed tools bypass the approval gate by construction (per
+`StreamOptions.requireToolApproval` JSDoc). They surface as a normal `tool-call` event without a preceding
+`tool-approval-request`. Built-in / MCP tools still gate normally.
+
 ### Connectivity Resolution
 
 #### `ResolvedConnectivity`
@@ -843,15 +905,33 @@ The SDK ships no harness implementation. Consumers pick one by passing a `Harnes
 [`@salesforce/sfdx-agent-harness-mastra`](../sfdx-agent-harness-mastra); additional harnesses can ship as independent
 npm packages that depend on this SDK as a `peerDependency`.
 
-Harness authors implement two interfaces and can compose one helper class, all exported from this package:
-
-| Export                        | Role                                                                                                                                                                                                                                  |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `HarnessFactory<H>`           | Construct a harness of type `H` bound to a storage root. Declares `harnessId` and `protocolVersion`. Default `H = AgentHarness`.                                                                                                      |
-| `AgentHarness`                | Runtime contract: agent / thread / stream / tool / message lifecycle. Declares its own `harnessId` and `protocolVersion`.                                                                                                             |
-| `SUPPORTED_PROTOCOL_VERSIONS` | Readonly list of harness protocol versions this SDK accepts. `createAgentManager` checks both the factory and the constructed harness.                                                                                                |
-| `HarnessBusOwner`             | Composition helper owning telemetry + log buses with `dispose()` semantics. Reuse it instead of reimplementing bus plumbing.                                                                                                          |
-| `lowerStreamInput`            | Validates a `MessagePart[]` and lowers each input part to your runtime's content-block shape. Use it in `stream()` so multimodal caps and `MULTIMODAL_NOT_SUPPORTED` / `INVALID_MESSAGE_CONTENT` semantics match every other harness. |
+### Two import surfaces
+
+This package publishes two ESM entry points:
+
+- **`@salesforce/sfdx-agent-sdk`** — consumer surface. Everything an application calling `createAgentManager` needs:
+  `Agent`, `ChatSession`, `ChatEvent`, `MessagePart`, `AgentConfig`, `AgentSDKError`, etc. The harness contract
+  interfaces (`AgentHarness`, `HarnessFactory`, `WithAgentConfig`, `ConfigOf`) also appear here as **type-only**
+  references so consumer code can write `AgentManager<H extends AgentHarness>` without reaching into the
+  harness-implementation surface.
+- **`@salesforce/sfdx-agent-sdk/harness`** — harness-implementation surface. Harness authors import the contract types
+  and the helpers from here. Consumer applications cannot reach these symbols from the bare specifier — the bundler / TS
+  resolver errors at the import site, which is the right outcome for any consumer who reaches for a primitive they don't
+  need.
+
+> **Build-tool requirement:** the `/harness` subpath is resolved via the `package.json` `exports` field, which requires
+> `moduleResolution: "node16" | "nodenext" | "bundler"` in `tsconfig.json`. Legacy `"node"` resolution silently won't
+> see the subpath. Modern bundlers (Vite, esbuild, Webpack 5+, tsup, Rollup with `@rollup/plugin-node-resolve` v15+)
+> resolve it natively. This is a harness-author concern only; consumer applications never touch the subpath.
+
+| Export                        | Surface                                     | Role                                                                                                                                                                                                                                    |
+| ----------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `HarnessFactory<H>`           | Type only on bare; value+type on `/harness` | Construct a harness of type `H` bound to a storage root. Declares `harnessId` and `protocolVersion`. Default `H = AgentHarness`.                                                                                                        |
+| `AgentHarness`                | Type only on bare; type on `/harness`       | Runtime contract: agent / thread / stream / tool / message lifecycle. Declares its own `harnessId` and `protocolVersion`.                                                                                                               |
+| `SUPPORTED_PROTOCOL_VERSIONS` | `/harness` only                             | Readonly list of harness protocol versions this SDK accepts. `createAgentManager` checks both the factory and the constructed harness.                                                                                                  |
+| `HarnessBusOwner`             | `/harness` only                             | Composition helper owning telemetry + log buses with `dispose()` semantics. Reuse it instead of reimplementing bus plumbing.                                                                                                            |
+| `lowerStreamInput`            | `/harness` only                             | Validates a `MessagePart[]` and lowers each input part to your runtime's content-block shape. Use it in `stream()` so multimodal caps and `MULTIMODAL_NOT_SUPPORTED` / `INVALID_MESSAGE_CONTENT` semantics match every other harness.   |
+| `GenSink<T>`                  | `/harness` only                             | Buffered async-generator wrapper for routing `ChatEvent`s to a consumer's `ChatStreamResult.eventStream`. Single-iteration: calling `generator()` twice throws — sinks have one waiter slot and one buffer, two iterators race on both. |
 
 Minimal skeleton:
 
@@ -861,7 +941,7 @@ import {
   type HarnessFactory,
   HarnessBusOwner,
   SUPPORTED_PROTOCOL_VERSIONS,
-} from '@salesforce/sfdx-agent-sdk';
+} from '@salesforce/sfdx-agent-sdk/harness';
 
 class MyHarness implements AgentHarness {
   readonly harnessId = 'my-harness';

package/dist/chat-session.d.ts

@@ -62,11 +62,17 @@ export interface ChatSession {
      *
      * "Client-side tool" means a tool you declared in {@link AgentConfig.tools}
      * without an `execute` function — the SDK registers its name + schema with the
-     * model but does not run it. When the model calls one, the chat eventStream
-     * emits a `tool-call` event and ends with `finishReason: 'tool-calls'`. Your
-     * application runs the tool however it likes (HTTP call, DB query, UI prompt,
-     * etc.) and calls this method with the result; the agent loop resumes and
-     * produces its next turn on the returned `ChatStreamResult.eventStream`.
+     * model but does not run it. When the model calls one, the chat `eventStream`
+     * emits a `tool-call` event. Your application runs the tool however it likes
+     * (HTTP call, DB query, UI prompt, etc.) and calls this method with the result;
+     * the agent loop resumes and the post-resume events (`tool-result`, model
+     * follow-up text, terminal `finish`) arrive on the **same** `eventStream`
+     * the original {@link chat} call returned. The consumer keeps iterating it.
+     *
+     * Returns `Promise<void>` once the harness has accepted the result. The
+     * promise rejects on pre-stream failure (the `chat()`-returned subscribers
+     * still observe `ErrorEvent` + `FinishEvent` before the rejection so the
+     * subscribe-side contract holds).
      *
      * Use this method ONLY for client-side tools. Tools provided via
      * {@link AgentConfig.mcpServers} are executed by the harness — their results
@@ -74,23 +80,22 @@ export interface ChatSession {
      * Human-in-the-loop approval of harness-executed tools uses
      * {@link approveToolCall} / {@link declineToolCall}, not this method.
      *
-     * On pre-stream failure, subscribers are notified with `ErrorEvent` + `FinishEvent` before
-     * the returned promise rejects. See the interface-level "Failure handling" notes for details.
-     *
      * @param toolResult - The completed tool execution result. `toolCallId` and
      *   `toolName` MUST match the values from the originating `tool-call` event.
      */
-    submitToolResult(toolResult: ToolResultInfo): Promise<ChatStreamResult>;
+    submitToolResult(toolResult: ToolResultInfo): Promise<void>;
     /**
      * Approve a pending tool call, allowing the harness to execute it.
      * Called after receiving a `tool-approval-request` event from the stream.
      *
-     * Returns a `ChatStreamResult` containing the continuation stream — the harness
-     * executes the approved tool, generates the model's follow-up response, and
-     * streams both the text and events back to the caller.
+     * Returns `Promise<void>` once the harness has accepted the approval. The
+     * harness then executes the tool and emits the resulting events
+     * (`tool-result`, model follow-up text, terminal `finish`) on the **same**
+     * `eventStream` the original {@link chat} call returned. The consumer keeps
+     * iterating it.
      *
-     * On pre-stream failure, subscribers are notified with `ErrorEvent` + `FinishEvent` before
-     * the returned promise rejects. See the interface-level "Failure handling" notes for details.
+     * The promise rejects on pre-stream failure; subscribers still observe
+     * `ErrorEvent` + `FinishEvent` on the chat stream before the rejection.
      *
      * @param toolCallId - ID of the pending tool call to approve.
      * @param options - Optional approval metadata.
@@ -101,21 +106,20 @@ export interface ChatSession {
      */
     approveToolCall(toolCallId: string, options?: {
         remember?: boolean;
-    }): Promise<ChatStreamResult>;
+    }): Promise<void>;
     /**
      * Decline a pending tool call. The stream resumes with the model
-     * acknowledging the decline and potentially suggesting alternatives.
+     * acknowledging the decline and potentially suggesting alternatives —
+     * those events arrive on the **same** `eventStream` the original
+     * {@link chat} call returned.
      *
-     * Returns a `ChatStreamResult` containing the continuation stream — the harness
-     * cancels the pending tool call, generates the model's acknowledgement response,
-     * and streams both the text and events back to the caller.
-     *
-     * On pre-stream failure, subscribers are notified with `ErrorEvent` + `FinishEvent` before
-     * the returned promise rejects. See the interface-level "Failure handling" notes for details.
+     * Returns `Promise<void>` once the harness has accepted the decline. The
+     * promise rejects on pre-stream failure; subscribers still observe
+     * `ErrorEvent` + `FinishEvent` on the chat stream before the rejection.
      *
      * @param toolCallId - ID of the pending tool call to decline.
      */
-    declineToolCall(toolCallId: string): Promise<ChatStreamResult>;
+    declineToolCall(toolCallId: string): Promise<void>;
     /**
      * Retrieve message history for this session.
      *
@@ -246,7 +250,7 @@ export declare class DefaultChatSession implements ChatSession {
      * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
      *   before returning a stream result.
      */
-    submitToolResult(toolResult: ToolResultInfo): Promise<ChatStreamResult>;
+    submitToolResult(toolResult: ToolResultInfo): Promise<void>;
     /**
      * @requirements
      * - MUST yield each event from the provided `stream`.
@@ -290,7 +294,7 @@ export declare class DefaultChatSession implements ChatSession {
      */
     approveToolCall(toolCallId: string, _options?: {
         remember?: boolean;
-    }): Promise<ChatStreamResult>;
+    }): Promise<void>;
     /**
      * @requirements
      * - MUST delegate to `this.harness.declineToolCall()`, passing `this.agentId`, `this.threadId`, and `toolCallId`.
@@ -302,7 +306,7 @@ export declare class DefaultChatSession implements ChatSession {
      * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
      *   before returning a stream result.
      */
-    declineToolCall(toolCallId: string): Promise<ChatStreamResult>;
+    declineToolCall(toolCallId: string): Promise<void>;
     /**
      * @requirements
      * - MUST delegate to `this.harness.getMessages()`, passing `this.agentId` and `this.threadId`.
@@ -395,5 +399,18 @@ export declare class DefaultChatSession implements ChatSession {
      * measures real elapsed time even for pre-stream rejections.
      */
     private notifyPreStreamError;
+    /**
+     * issue #529 contract change: a settle call (`approveToolCall` /
+     * `declineToolCall` / `submitToolResult`) rejected. The settle's
+     * Promise is the consumer's primary failure surface, but subscribers
+     * registered via {@link ChatSession.subscribe} also expect to observe
+     * `error + finish` events so a UI bound to the chat stream can
+     * render the failure. Emit those without firing
+     * `chat-stream-error` telemetry — chat-stream-* telemetry is owned
+     * by the chat() lifecycle, not by settle calls (issue #529: one
+     * chat-stream-started/completed/error pair per turn, not per
+     * settle).
+     */
+    private notifySettleRejection;
     private assertNotDisposed;
 }

package/dist/chat-session.js

@@ -109,16 +109,16 @@ export class DefaultChatSession {
      */
     async submitToolResult(toolResult) {
         this.assertNotDisposed();
-        const startedAt = this.emitChatStreamStarted('submit-tool-result');
+        // issue #529 contract change: settle calls are control messages on the
+        // existing chat() turn's stream — they don't open a new stream and
+        // they don't emit chat-stream-started/completed. The post-resume
+        // events flow through the harness's existing turn sink, which the
+        // consumer's chat()-returned eventStream is already iterating.
         try {
-            const result = await this.harness.submitToolResult(this.agentId, this.threadId, toolResult);
-            return {
-                textStream: result.textStream,
-                eventStream: this.wrapEventStream(result.eventStream, startedAt),
-            };
+            await this.harness.submitToolResult(this.agentId, this.threadId, toolResult);
         }
         catch (err) {
-            this.notifyPreStreamError(err, startedAt);
+            this.notifySettleRejection(err);
             throw err;
         }
     }
@@ -246,19 +246,17 @@ export class DefaultChatSession {
      */
     async approveToolCall(toolCallId, _options) {
         this.assertNotDisposed();
-        const startedAt = this.emitChatStreamStarted('approve-tool-call');
+        // issue #529 contract change: see `submitToolResult` for the rationale.
+        // Settle is a control message on the existing turn; events flow on
+        // the chat()-returned stream.
         try {
-            const result = await this.harness.approveToolCall(this.agentId, this.threadId, toolCallId);
-            this.emitToolApprovalResolved(toolCallId, true);
-            return {
-                textStream: result.textStream,
-                eventStream: this.wrapEventStream(result.eventStream, startedAt),
-            };
+            await this.harness.approveToolCall(this.agentId, this.threadId, toolCallId);
         }
         catch (err) {
-            this.notifyPreStreamError(err, startedAt);
+            this.notifySettleRejection(err);
             throw err;
         }
+        this.emitToolApprovalResolved(toolCallId, true);
     }
     /**
      * @requirements
@@ -273,19 +271,15 @@ export class DefaultChatSession {
      */
     async declineToolCall(toolCallId) {
         this.assertNotDisposed();
-        const startedAt = this.emitChatStreamStarted('decline-tool-call');
+        // issue #529 contract change: see `submitToolResult` for the rationale.
         try {
-            const result = await this.harness.declineToolCall(this.agentId, this.threadId, toolCallId);
-            this.emitToolApprovalResolved(toolCallId, false);
-            return {
-                textStream: result.textStream,
-                eventStream: this.wrapEventStream(result.eventStream, startedAt),
-            };
+            await this.harness.declineToolCall(this.agentId, this.threadId, toolCallId);
         }
         catch (err) {
-            this.notifyPreStreamError(err, startedAt);
+            this.notifySettleRejection(err);
             throw err;
         }
+        this.emitToolApprovalResolved(toolCallId, false);
     }
     /**
      * @requirements
@@ -527,6 +521,23 @@ export class DefaultChatSession {
             error,
         });
     }
+    /**
+     * issue #529 contract change: a settle call (`approveToolCall` /
+     * `declineToolCall` / `submitToolResult`) rejected. The settle's
+     * Promise is the consumer's primary failure surface, but subscribers
+     * registered via {@link ChatSession.subscribe} also expect to observe
+     * `error + finish` events so a UI bound to the chat stream can
+     * render the failure. Emit those without firing
+     * `chat-stream-error` telemetry — chat-stream-* telemetry is owned
+     * by the chat() lifecycle, not by settle calls (issue #529: one
+     * chat-stream-started/completed/error pair per turn, not per
+     * settle).
+     */
+    notifySettleRejection(err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.chatEventBus.emit({ type: 'error', error });
+        this.chatEventBus.emit({ type: 'finish', finishReason: 'error' });
+    }
     assertNotDisposed() {
         if (this.disposed) {
             throw new AgentSDKError('ChatSession has been disposed.', AgentSDKErrorType.DISPOSED);

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

@@ -238,49 +238,56 @@ export interface AgentHarness {
     stream(agentId: string, threadId: string, message: string | MessagePart[], options?: StreamOptions): Promise<ChatStreamResult>;
     /**
      * Feed the result of a **consumer-executed (client-side) tool** back into the
-     * conversation and resume stream generation. Implements the consumer-facing
+     * conversation. Implements the consumer-facing
      * {@link ChatSession.submitToolResult} contract: see that JSDoc for the
      * full consumer-level semantics.
      *
      * Called only for tools declared in {@link HarnessAgentConfig.tools} (no
      * `execute` function). Tools provided via `mcpServers` are executed by the
-     * harness directly and never reach this method. The harness resumes the
-     * suspended agentic loop from the most recent `stream()` call on the given
-     * thread, feeds `toolResult` into the loop, and returns a continuation
-     * stream the consumer iterates for the model's next turn.
+     * harness directly and never reach this method.
+     *
+     * Returns `Promise<void>` once the harness has accepted the tool result
+     * (the parked bridge handler resolved). Post-resume events
+     * (`tool-result`, model follow-up text, terminal `finish`) flow through
+     * the SAME `ChatStreamResult.eventStream` returned by the most recent
+     * {@link stream} call on the thread — the consumer is still iterating
+     * that stream and sees the events arrive.
      *
      * @param agentId - ID of the agent.
      * @param threadId - ID of the conversation thread.
      * @param toolResult - The completed tool execution result; `toolCallId`
      *   matches the id from the originating `tool-call` event.
      */
-    submitToolResult(agentId: string, threadId: string, toolResult: ToolResultInfo): Promise<ChatStreamResult>;
+    submitToolResult(agentId: string, threadId: string, toolResult: ToolResultInfo): Promise<void>;
     /**
      * Approve a pending tool call, allowing the harness to execute it.
      * Called after receiving a `tool-approval-request` event.
      *
-     * Returns a `ChatStreamResult` containing the continuation stream — the harness
-     * executes the approved tool, generates the model's follow-up response, and
-     * streams both the text and events back to the caller.
+     * Returns `Promise<void>` once the harness has accepted the approval
+     * (the parked PreToolUse hook resolved on Claude; the resume call was
+     * dispatched on Mastra). Post-resume events flow through the SAME
+     * `ChatStreamResult.eventStream` returned by the most recent
+     * {@link stream} call on the thread.
      *
      * @param agentId - ID of the agent.
      * @param threadId - ID of the conversation thread (needed for harness-internal state lookup).
      * @param toolCallId - ID of the tool call to approve.
      */
-    approveToolCall(agentId: string, threadId: string, toolCallId: string): Promise<ChatStreamResult>;
+    approveToolCall(agentId: string, threadId: string, toolCallId: string): Promise<void>;
     /**
-     * Decline a pending tool call. The harness resumes the stream with the
-     * model acknowledging the decline and potentially suggesting alternatives.
+     * Decline a pending tool call. The harness resumes the agentic loop with
+     * the model acknowledging the decline and potentially suggesting
+     * alternatives.
      *
-     * Returns a `ChatStreamResult` containing the continuation stream — the harness
-     * cancels the pending tool call, generates the model's acknowledgement response,
-     * and streams both the text and events back to the caller.
+     * Returns `Promise<void>` once the harness has accepted the decline.
+     * Post-resume events flow through the SAME `ChatStreamResult.eventStream`
+     * returned by the most recent {@link stream} call on the thread.
      *
      * @param agentId - ID of the agent.
      * @param threadId - ID of the conversation thread.
      * @param toolCallId - ID of the tool call to decline.
      */
-    declineToolCall(agentId: string, threadId: string, toolCallId: string): Promise<ChatStreamResult>;
+    declineToolCall(agentId: string, threadId: string, toolCallId: string): Promise<void>;
     /**
      * Retrieve message history for a thread.
      *

package/dist/harness/gen-sink.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Buffered async-generator wrapper used by `AgentHarness` implementations to
+ * deliver `ChatEvent`s to a consumer's `ChatStreamResult.eventStream`.
+ *
+ * The buffer holds events pushed before the consumer starts iterating, so the
+ * harness can begin populating the sink eagerly without coordinating with the
+ * consumer's `for await` loop. Events pushed after iteration starts unblock
+ * the awaiting consumer via an internal Promise waiter.
+ *
+ * # Single-iteration invariant
+ *
+ * `generator()` may be called **at most once** per sink. Sinks are stateful
+ * (single waiter slot, single buffer); two iterators on the same sink race on
+ * both, so two iterators is always a bug. Calling `generator()` a second time
+ * throws — the alternative (silently allowing the second call to share the
+ * buffer / waiter with the first) produced the deadlock-class bug catalogued
+ * in [issue #529](https://github.com/forcedotcom/agentic-dx/issues/529)
+ * Finding 4. Surface failures at construction-time, not at deadlock-time.
+ *
+ * # `isEnded()`
+ *
+ * Exposes the closed state for routing logic that needs to skip pushes onto
+ * a sink that's already been retired. Routing for a closed sink should
+ * silently no-op with a debug log rather than throw — the late event is
+ * upstream noise, not a programmer error.
+ *
+ * Exported from the public `index.ts` so third-party `AgentHarness`
+ * implementations in sibling packages can reuse it.
+ */
+export declare class GenSink<T> {
+    private readonly buffered;
+    private ended;
+    private waiter;
+    private generated;
+    push(event: T): void;
+    end(): void;
+    isEnded(): boolean;
+    generator(): AsyncGenerator<T, void>;
+    private iterate;
+    private wake;
+}

package/dist/harness/gen-sink.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Buffered async-generator wrapper used by `AgentHarness` implementations to
+ * deliver `ChatEvent`s to a consumer's `ChatStreamResult.eventStream`.
+ *
+ * The buffer holds events pushed before the consumer starts iterating, so the
+ * harness can begin populating the sink eagerly without coordinating with the
+ * consumer's `for await` loop. Events pushed after iteration starts unblock
+ * the awaiting consumer via an internal Promise waiter.
+ *
+ * # Single-iteration invariant
+ *
+ * `generator()` may be called **at most once** per sink. Sinks are stateful
+ * (single waiter slot, single buffer); two iterators on the same sink race on
+ * both, so two iterators is always a bug. Calling `generator()` a second time
+ * throws — the alternative (silently allowing the second call to share the
+ * buffer / waiter with the first) produced the deadlock-class bug catalogued
+ * in [issue #529](https://github.com/forcedotcom/agentic-dx/issues/529)
+ * Finding 4. Surface failures at construction-time, not at deadlock-time.
+ *
+ * # `isEnded()`
+ *
+ * Exposes the closed state for routing logic that needs to skip pushes onto
+ * a sink that's already been retired. Routing for a closed sink should
+ * silently no-op with a debug log rather than throw — the late event is
+ * upstream noise, not a programmer error.
+ *
+ * Exported from the public `index.ts` so third-party `AgentHarness`
+ * implementations in sibling packages can reuse it.
+ */
+export class GenSink {
+    buffered = [];
+    ended = false;
+    waiter = null;
+    generated = false;
+    push(event) {
+        if (this.ended)
+            return;
+        this.buffered.push(event);
+        this.wake();
+    }
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.wake();
+    }
+    isEnded() {
+        return this.ended;
+    }
+    generator() {
+        // Synchronous guard. Must live outside the async generator body —
+        // async generators are lazy (the body does not execute until the
+        // first `next()`), so a `throw` inside the body would not surface
+        // at the second `generator()` call site as expected.
+        if (this.generated) {
+            throw new Error('GenSink.generator(): sinks are single-iteration. ' +
+                'Two iterators on one sink race on the buffer and waiter slot. ' +
+                'See https://github.com/forcedotcom/agentic-dx/issues/529 (Finding 4).');
+        }
+        this.generated = true;
+        return this.iterate();
+    }
+    async *iterate() {
+        while (true) {
+            if (this.buffered.length > 0) {
+                yield this.buffered.shift();
+                continue;
+            }
+            if (this.ended)
+                return;
+            await new Promise((resolve) => {
+                this.waiter = { resolve };
+            });
+        }
+    }
+    wake() {
+        const w = this.waiter;
+        if (w) {
+            this.waiter = null;
+            w.resolve();
+        }
+    }
+}
+//# sourceMappingURL=gen-sink.js.map

package/dist/harness/index.d.ts

@@ -2,3 +2,4 @@ export type { AgentHarness, WithAgentConfig, ConfigOf } from './agent-harness.js
 export type { HarnessFactory } from './harness-factory.js';
 export type { AgentConfig, StreamOptions } from './harness-config.js';
 export { toHarnessConfig, DEFAULT_MAX_STEPS } from './harness-config.js';
+export { GenSink } from './gen-sink.js';

package/dist/harness/index.js

@@ -3,4 +3,5 @@
  * See LICENSE.txt for license terms.
  */
 export { toHarnessConfig, DEFAULT_MAX_STEPS } from './harness-config.js';
+export { GenSink } from './gen-sink.js';
 //# sourceMappingURL=index.js.map

package/dist/harness/public.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Harness-implementation public surface.
+ *
+ * This module is reachable as `@salesforce/sfdx-agent-sdk/harness` —
+ * **never** import directly from `dist/` or via deep relative paths.
+ *
+ * # When to import from here
+ *
+ * Use this surface when implementing an `AgentHarness` (e.g.
+ * `@salesforce/sfdx-agent-harness-claude`,
+ * `@salesforce/sfdx-agent-harness-mastra`). It re-exports both the
+ * harness contract types (`AgentHarness`, `HarnessFactory`) and the
+ * harness-implementation helpers consumer applications must not touch
+ * (`HarnessBusOwner`, `GenSink`, `lowerStreamInput`,
+ * `SUPPORTED_PROTOCOL_VERSIONS`).
+ *
+ * # Why this is a separate subpath
+ *
+ * Consumer applications (anything that calls `createAgentManager` and
+ * iterates `ChatStreamResult`) import from the bare specifier:
+ *
+ *     import { createAgentManager, Agent } from '@salesforce/sfdx-agent-sdk';
+ *
+ * Harness implementations import from the subpath:
+ *
+ *     import { HarnessBusOwner, GenSink } from '@salesforce/sfdx-agent-sdk/harness';
+ *
+ * The split makes the boundary mechanical: a consumer who tries to import
+ * `HarnessBusOwner` from the bare specifier gets an immediate
+ * "not exported" error from the bundler / TS resolver, instead of
+ * accidentally reaching for a primitive they shouldn't be using.
+ *
+ * Type-only references to the contract interface (`AgentHarness`,
+ * `HarnessFactory`) ALSO appear on the bare specifier so consumer code
+ * that needs `AgentManager<H extends AgentHarness>` typing still works
+ * without a subpath import — but their runtime / constructible
+ * counterparts live only here.
+ *
+ * Symbols that consumers and harnesses both need (`AgentConfig`,
+ * `StreamOptions`, `DEFAULT_MAX_STEPS`, `resolveToolApprovalMode`,
+ * `ChatEvent` types, `Message` types, `MCPConfiguration`, etc.) stay on
+ * the bare specifier. The split is "harness-only" vs. "consumer-AND-harness",
+ * not "harness vs. consumer."
+ */
+export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './index.js';
+export { SUPPORTED_PROTOCOL_VERSIONS } from './agent-harness.js';
+export { HarnessBusOwner } from './harness-bus-owner.js';
+export { lowerStreamInput, type InputMessagePart } from './stream-input.js';
+export { GenSink } from './gen-sink.js';

package/dist/harness/public.js

@@ -0,0 +1,10 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export { SUPPORTED_PROTOCOL_VERSIONS } from './agent-harness.js';
+// ── Harness-implementation helpers ──────────────────────────────────
+export { HarnessBusOwner } from './harness-bus-owner.js';
+export { lowerStreamInput } from './stream-input.js';
+export { GenSink } from './gen-sink.js';
+//# sourceMappingURL=public.js.map

package/dist/index.d.ts

@@ -14,9 +14,6 @@ export { type Agent } from './agent.js';
 export { type ChatSession, type ChatOptions } from './chat-session.js';
 export type { AgentConnectivityResolver, ResolvedConnectivity } from './agent-connectivity-resolver.js';
 export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './harness/index.js';
-export { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
-export { HarnessBusOwner } from './harness/harness-bus-owner.js';
-export { lowerStreamInput, type InputMessagePart } from './harness/stream-input.js';
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
 export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent, ChatStreamErrorEvent, ChatStreamStartedEvent, ChatStreamTrigger, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, McpServerStatusChangedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalRequestedEvent, ToolApprovalResolvedEvent, ToolExecutionCompletedEvent, ToolExecutionStartedEvent, } from './types/telemetry-events.js';
 export type { LogLevel, LogRecord, Unsubscribe } from '@salesforce/agentic-common';

package/dist/index.js

@@ -10,9 +10,6 @@ export { inferSfApiEnv, SfApiEnv } from '@salesforce/agentic-common';
 export { createAgentManager } from './agent-manager.js';
 export {} from './agent.js';
 export {} from './chat-session.js';
-export { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
-export { HarnessBusOwner } from './harness/harness-bus-owner.js';
-export { lowerStreamInput } from './harness/stream-input.js';
 // ── Errors ───────────────────────────────────────────────────────────
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
 // ── MCP Auth ────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./harness": {
+      "types": "./dist/harness/public.d.ts",
+      "default": "./dist/harness/public.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -35,13 +39,13 @@
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@salesforce/agentic-common": "0.7.0",
-    "@salesforce/llm-gateway-sdk": "0.11.0"
+    "@salesforce/agentic-common": "0.8.0",
+    "@salesforce/llm-gateway-sdk": "0.12.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.11.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.14.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.12.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.15.0",
     "@types/node": "^22.19.17",
     "@vitest/coverage-istanbul": "^4.1.7",
     "@vitest/eslint-plugin": "^1.6.17",