@salesforce/sfdx-agent-sdk 0.77.0 → 0.79.0

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 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.79.0] - 2026-09-14
+
+### Features
+- add ChatSession.cancelTurn() with abort-persistence barrier @W-23559264@ ([#810](https://github.com/forcedotcom/agentic-dx/pull/810))
+
+## [0.78.0] - 2026-09-09
+
+_No changes — released alongside dependent packages._
+
 ## [0.77.0] - 2026-09-08
 
 ### Fixes

package/README.md

@@ -170,6 +170,7 @@ A single conversation thread.
 | `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. `{ remember: true }` ("Allow always") appends an `allow` rule to `AgentConfig.toolPolicies` and persists it before settling. Control message on the existing turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `declineToolCall`   | `(toolCallId: string, options?: DeclineToolCallOptions) => Promise<void>` | Decline a pending tool call. `{ remember: true }` ("Deny always") appends a `deny` rule and persists it before settling. `{ reason: { kind: 'organization-policy', modelMessage? } }` delivers a terminal policy explanation to the model and error result without persisting a remembered user rule. Control message on the existing turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `cancelTurn`        | `() => Promise<void>`                                                     | Stop the in-flight turn (including one suspended awaiting a tool approval) and resolve only **after** the harness abort teardown AND its transcript-persistence flush complete. Fires an SDK-owned per-turn signal composed with any caller `abortSignal`, so it works with or without one. The turn's `eventStream` ends with exactly one `FinishEvent(finishReason: 'cancelled')` preceded by an `ErrorEvent` whose canonical `code` is `'cancelled'` (no harness-specific `'abort'`/`'aborted'`). Because the returned promise is a persistence barrier, a subsequent `getMessageHistory()` is deterministic with **no polling**. Idempotent / safe no-op with no turn in flight; owns no wall-clock timeout (wrap it if you need one).                                                        |
 | `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -764,7 +765,7 @@ type ContextUsage = {
   usedFraction: number | undefined;
 };
 
-type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'other';
+type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'max-steps' | 'cancelled' | 'other';
 ```
 
 **Tracking context-window utilization.** `ChatSession.getContextUsage()` always returns a populated `ContextUsage` —

package/dist/chat-session.d.ts

@@ -87,7 +87,10 @@ export type ChatSessionParentBuses = {
  *     cleared, but the underlying harness turn keeps running until it settles, so the harness rejects
  *     the new turn until then. **To release a turn deterministically, abort it (via the turn's
  *     `abortSignal`) rather than merely abandoning its stream** — abort settles the coordinator, so the
- *     next `chat()` is admitted cleanly.
+ *     next `chat()` is admitted cleanly. {@link ChatSession.cancelTurn} is the first-class verb for this:
+ *     it fires an SDK-owned per-turn signal (composed with any caller `abortSignal`) and resolves only
+ *     after teardown + transcript-persistence flush, so a subsequent `getMessageHistory()` is
+ *     deterministic without polling.
  */
 export interface ChatSession {
     /** Returns the unique session/thread identifier. */
@@ -182,6 +185,35 @@ export interface ChatSession {
      *   terminal error result. Policy reasons require `remember: false` and are never persisted.
      */
     declineToolCall(toolCallId: string, options?: DeclineToolCallOptions): Promise<void>;
+    /**
+     * Stop the turn currently in flight — including one suspended awaiting a
+     * tool approval — and resolve only after the harness has fully settled the
+     * abort teardown, INCLUDING flushing whatever transcript persistence that
+     * harness performs. That persistence barrier is the point of the returned
+     * promise: once it resolves, {@link getMessageHistory} deterministically
+     * reflects the settled transcript with NO polling.
+     *
+     * Cancellation fires an SDK-owned per-turn `AbortController` that composes
+     * with any caller-supplied `options.abortSignal` — so it works whether or
+     * not the caller passed a signal, and a caller aborting their own signal has
+     * the identical effect. The turn's `eventStream` ends with exactly one
+     * terminal `FinishEvent(finishReason: 'cancelled')`, preceded by an
+     * `ErrorEvent` whose canonical `code` is `'cancelled'` on every harness — no
+     * cancelled turn surfaces `finishReason: 'error'`, and callers never branch
+     * on harness-specific `'abort'` / `'aborted'`.
+     *
+     * Idempotent and a safe no-op: calling it with no turn in flight, or a
+     * second time, does nothing harmful. It owns no wall-clock timeout — a
+     * consumer that needs one wraps the call itself.
+     *
+     * The cancelled turn's terminal `ErrorEvent` + `FinishEvent('cancelled')`
+     * still flow on the turn's own `eventStream`. As with any turn, drain (or
+     * abandon via `break` / `.return()`) that stream so the session's
+     * one-turn-at-a-time guard clears before the next {@link chat} — a
+     * `subscribe()`-only consumer that never iterates the returned stream can
+     * otherwise see `SESSION_BUSY` on the next `chat()` until it does.
+     */
+    cancelTurn(): Promise<void>;
     /**
      * Retrieve message history for this session.
      *
@@ -371,6 +403,25 @@ export declare class DefaultChatSession implements ChatSession {
      * mutate this flag. See the interface-level "Failure handling" notes.
      */
     private turnActive;
+    /**
+     * SDK-owned abort controller for the turn started by the most recent
+     * {@link chat}. Its signal is composed (via `AbortSignal.any`) with any
+     * caller-supplied `options.abortSignal` and handed to `harness.stream()`, so
+     * {@link cancelTurn} can stop the turn whether or not the caller passed a
+     * signal, and a caller-fired signal reaches the harness the same way.
+     * `undefined` before the first `chat()`. Aborting a controller whose turn has
+     * already settled is a harmless no-op, which is what makes `cancelTurn`
+     * idempotent without extra bookkeeping.
+     */
+    private turnAbortController;
+    /**
+     * The current turn's settle barrier, taken from the harness's
+     * {@link HarnessStreamResult.settled}. {@link cancelTurn} awaits it so the
+     * returned promise resolves only after the harness abort teardown AND its
+     * transcript-persistence flush have completed. `undefined` when no turn has
+     * run, when the harness didn't supply one, or on a pre-stream failure.
+     */
+    private turnSettled;
     /**
      * @param harness - The agent harness managing thread and message lifecycle.
      * @param agentId - ID of the agent this session belongs to.
@@ -394,6 +445,18 @@ export declare class DefaultChatSession implements ChatSession {
      *   before returning a stream result.
      */
     chat(message: string | MessagePart[], options?: ChatOptions): Promise<ChatStreamResult>;
+    /**
+     * @requirements
+     * - MUST fire `this.turnAbortController` so the SDK-owned per-turn signal (composed with any
+     *   caller-supplied `options.abortSignal`) reaches the harness and tears the turn down.
+     * - MUST await `this.turnSettled` (the harness settle barrier) so it resolves only after the
+     *   abort teardown AND its transcript-persistence flush have completed.
+     * - MUST be a safe no-op when no turn has ever run (`turnAbortController` undefined) and be
+     *   idempotent on repeat calls / an already-settled turn (aborting a settled controller and
+     *   awaiting an already-resolved barrier are both no-ops).
+     * - MUST NOT own a wall-clock timeout.
+     */
+    cancelTurn(): Promise<void>;
     /**
      * @requirements
      * - MUST delegate to `this.harness.submitToolResult()`, passing `this.agentId` and `this.threadId`.

package/dist/chat-session.js

@@ -6,6 +6,16 @@ import { backfillCreatedAt, EventBus, LogBus, RealClock, UUIDGenerator, } from '
 import { resolveToolDeclineModelMessage } from './harness/tool-decline.js';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
 import { createTelemetryBus, } from './types/telemetry-events.js';
+/**
+ * Composes the SDK-owned per-turn abort signal with the caller's (if any) into
+ * one signal handed to `harness.stream()`, so firing EITHER aborts the turn.
+ * With no caller signal, the SDK signal is passed through unchanged. Uses
+ * `AbortSignal.any`, which yields an already-aborted signal when either input is
+ * already aborted — preserving the harness's abort-at-entry handling.
+ */
+function composeAbortSignals(own, caller) {
+    return caller === undefined ? own : AbortSignal.any([own, caller]);
+}
 /**
  * Default implementation of {@link ChatSession} that delegates all operations
  * to an {@link AgentHarness}. The session holds its agent ID and thread ID
@@ -98,6 +108,25 @@ export class DefaultChatSession {
      * mutate this flag. See the interface-level "Failure handling" notes.
      */
     turnActive = false;
+    /**
+     * SDK-owned abort controller for the turn started by the most recent
+     * {@link chat}. Its signal is composed (via `AbortSignal.any`) with any
+     * caller-supplied `options.abortSignal` and handed to `harness.stream()`, so
+     * {@link cancelTurn} can stop the turn whether or not the caller passed a
+     * signal, and a caller-fired signal reaches the harness the same way.
+     * `undefined` before the first `chat()`. Aborting a controller whose turn has
+     * already settled is a harmless no-op, which is what makes `cancelTurn`
+     * idempotent without extra bookkeeping.
+     */
+    turnAbortController = undefined;
+    /**
+     * The current turn's settle barrier, taken from the harness's
+     * {@link HarnessStreamResult.settled}. {@link cancelTurn} awaits it so the
+     * returned promise resolves only after the harness abort teardown AND its
+     * transcript-persistence flush have completed. `undefined` when no turn has
+     * run, when the harness didn't supply one, or on a pre-stream failure.
+     */
+    turnSettled = undefined;
     /**
      * @param harness - The agent harness managing thread and message lifecycle.
      * @param agentId - ID of the agent this session belongs to.
@@ -144,9 +173,24 @@ export class DefaultChatSession {
         // cannot slip past the guard.
         this.assertNotBusy();
         this.turnActive = true;
+        // SDK-owned per-turn signal composed with the caller's (if any) so
+        // cancelTurn() can stop this turn regardless of whether the caller passed
+        // one. Set before the `await` so a cancelTurn() racing this call still
+        // aborts the right controller.
+        const turnAbort = new AbortController();
+        this.turnAbortController = turnAbort;
+        const abortSignal = composeAbortSignals(turnAbort.signal, options?.abortSignal);
         const startedAt = this.emitChatStreamStarted('chat');
+        const streamPromise = this.harness.stream(this.agentId, this.threadId, message, { ...options, abortSignal });
+        // Derive the settle barrier synchronously from the stream promise — before
+        // the `await` — so a `cancelTurn()` that races this `chat()` still awaits the
+        // real teardown + persistence flush rather than an `undefined` (an immediate
+        // resolve that would skip the barrier). On a pre-stream rejection there is no
+        // turn to settle, so the barrier resolves; the rejection itself surfaces on
+        // the awaited `streamPromise` below.
+        this.turnSettled = streamPromise.then((result) => result.settled, () => undefined);
         try {
-            const result = await this.harness.stream(this.agentId, this.threadId, message, options);
+            const result = await streamPromise;
             return {
                 textStream: result.textStream,
                 eventStream: this.wrapEventStream(result.eventStream, startedAt),
@@ -160,6 +204,30 @@ export class DefaultChatSession {
             throw err;
         }
     }
+    /**
+     * @requirements
+     * - MUST fire `this.turnAbortController` so the SDK-owned per-turn signal (composed with any
+     *   caller-supplied `options.abortSignal`) reaches the harness and tears the turn down.
+     * - MUST await `this.turnSettled` (the harness settle barrier) so it resolves only after the
+     *   abort teardown AND its transcript-persistence flush have completed.
+     * - MUST be a safe no-op when no turn has ever run (`turnAbortController` undefined) and be
+     *   idempotent on repeat calls / an already-settled turn (aborting a settled controller and
+     *   awaiting an already-resolved barrier are both no-ops).
+     * - MUST NOT own a wall-clock timeout.
+     */
+    async cancelTurn() {
+        this.assertNotDisposed();
+        const controller = this.turnAbortController;
+        if (controller === undefined) {
+            // No turn has ever started on this session — nothing to cancel.
+            return;
+        }
+        controller.abort();
+        // Resolve only after the harness has settled teardown and flushed
+        // persistence. `settled` never rejects; absence (a harness that didn't
+        // supply one) degrades to abort-without-barrier.
+        await this.turnSettled;
+    }
     /**
      * @requirements
      * - MUST delegate to `this.harness.submitToolResult()`, passing `this.agentId` and `this.threadId`.

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

@@ -1,6 +1,6 @@
 import type { LogRecord, Unsubscribe } from '@salesforce/agentic-common';
 import type { McpServerInfo, McpAuthProviders } from '../mcp-config.js';
-import type { ChatStreamResult } from '../types/events.js';
+import type { HarnessStreamResult } from '../types/events.js';
 import type { Message, MessagePart } from '../types/messages.js';
 import type { TelemetryEventCallback } from '../types/telemetry-events.js';
 import type { ToolDeclineReason, ToolResultInfo } from '../types/tools.js';
@@ -367,8 +367,10 @@ export interface AgentHarness {
     compactThread(agentId: string, threadId: string): Promise<string>;
     /**
      * Stream a response from the agent for the given message.
-     * Returns a {@link ChatStreamResult} providing multiple ways to consume
-     * the stream (text-only or full events).
+     * Returns a {@link HarnessStreamResult} — a {@link ChatStreamResult} (text-only
+     * or full-event consumption) plus an optional internal `settled` promise the
+     * SDK uses as the {@link ChatSession.cancelTurn} persistence barrier. The
+     * `settled` field is off the consumer surface; see {@link HarnessStreamResult}.
      *
      * @param agentId - ID of the agent to invoke.
      * @param threadId - ID of the conversation thread.
@@ -377,7 +379,7 @@ export interface AgentHarness {
      *   passing `tool-call` / `tool-result` parts is a programmer error and harnesses reject it.
      * @param options - Per-call streaming options.
      */
-    stream(agentId: string, threadId: string, message: string | MessagePart[], options?: StreamOptions): Promise<ChatStreamResult>;
+    stream(agentId: string, threadId: string, message: string | MessagePart[], options?: StreamOptions): Promise<HarnessStreamResult>;
     /**
      * Feed the result of a **consumer-executed (client-side) tool** back into the
      * conversation. Implements the consumer-facing

package/dist/harness/public.d.ts

@@ -42,6 +42,7 @@
  * is "harness-only" vs. "consumer-AND-harness", not "harness vs. consumer."
  */
 export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './index.js';
+export type { HarnessStreamResult } from '../types/events.js';
 export type { AgentHooks } from '../types/redaction.js';
 export { SUPPORTED_PROTOCOL_VERSIONS } from './agent-harness.js';
 export { mcpServerConfigEqual } from '../mcp-config.js';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { Message, MessagePart, MessageRole, ImagePart, FilePart } from './types/messages.js';
 export type { JsonValue, SessionContext } from './types/session-context.js';
-export type { ChatEvent, StartEvent, TextDeltaEvent, ReasoningDeltaEvent, ToolCallEvent, ToolCallDeltaEvent, ToolApprovalRequestEvent, ToolResultEvent, ToolProgressEvent, StepStartEvent, StepFinishEvent, ErrorEvent, FinishEvent, ChatStreamResult, } from './types/events.js';
+export type { ChatEvent, StartEvent, TextDeltaEvent, ReasoningDeltaEvent, ToolCallEvent, ToolCallDeltaEvent, ToolApprovalRequestEvent, ToolResultEvent, ToolProgressEvent, StepStartEvent, StepFinishEvent, ErrorEvent, FinishEvent, ChatStreamResult, HarnessStreamResult, } from './types/events.js';
 export type { DeclineToolCallOptions, Decision, ToolDeclineReason, ToolDefinition, ToolCallInfo, ToolMatcher, ToolPolicyRule, ToolResultInfo, } from './types/tools.js';
 export { BUILT_IN_TOOL_POLICIES, SKILL_BRIDGE_SERVER_ID, definePolicy, matcherMatches, resolveToolApprovalPolicy, } from './policy-resolver.js';
 export type { ResolverResult, ResolverTiers, ToolInvocation } from './policy-resolver.js';

package/dist/types/events.d.ts

@@ -258,10 +258,14 @@ export type ErrorEvent = {
     /**
      * Stable, machine-readable classification of the error, when the harness
      * recognized it — consumers branch on this instead of string-matching
-     * `error.message`. The cross-harness value in use today is
-     * `'context-window-exceeded'` (the {@link AgentSDKErrorType.CONTEXT_LENGTH_EXCEEDED}
-     * overflow signal, emitted uniformly by every harness). Other values are
-     * harness-specific (e.g. `'network-error'`, `'abort'`, `'tool-approval-timeout'`).
+     * `error.message`. Two cross-harness values are emitted uniformly by every
+     * harness: `'context-window-exceeded'` (the
+     * {@link AgentSDKErrorType.CONTEXT_LENGTH_EXCEEDED} overflow signal) and
+     * `'cancelled'` (the canonical code paired with a terminal
+     * `FinishEvent(finishReason: 'cancelled')` when a turn is stopped by
+     * {@link ChatSession.cancelTurn} or a caller-fired `abortSignal` — callers
+     * no longer branch on harness-specific `'abort'` / `'aborted'`). Other values
+     * are harness-specific (e.g. `'network-error'`, `'tool-approval-timeout'`).
      * `undefined` when the harness could not classify the error.
      */
     code?: string;
@@ -291,3 +295,29 @@ export type ChatStreamResult = {
      */
     textStream: AsyncGenerator<string>;
 };
+/**
+ * The result a harness's {@link AgentHarness.stream} returns to the SDK — a
+ * {@link ChatStreamResult} plus an optional internal `settled` promise. A
+ * harness-contract type (reachable from both `@salesforce/sfdx-agent-sdk` and
+ * `/harness`, like {@link AgentHarness}), NOT the consumer-facing result:
+ * `ChatSession.chat()` returns a plain {@link ChatStreamResult} that never
+ * carries `settled`. The SDK reads `settled` off the harness result and consumes
+ * it internally (the {@link ChatSession.cancelTurn} barrier); consumer code never
+ * sees the field.
+ */
+export type HarnessStreamResult = ChatStreamResult & {
+    /**
+     * Resolves once the turn has fully settled — its single per-turn sink has
+     * ended (natural `finish` or an abort/teardown) AND any persistence flush
+     * that settling entails has completed (the harness's transcript save is on
+     * disk). This is the barrier {@link ChatSession.cancelTurn} awaits so a
+     * subsequent `getMessages()` is deterministic with no polling.
+     *
+     * Optional so a harness that hasn't wired it still satisfies the contract:
+     * the SDK's `cancelTurn()` still aborts the turn, it just can't await the
+     * persistence barrier. All production harnesses populate it. It never
+     * rejects — a failed teardown still resolves it (the turn is over either
+     * way).
+     */
+    settled?: Promise<void>;
+};

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
 export type { Message, MessageRole, MessagePart, TextPart, ReasoningPart, ToolCallPart, ToolResultPart, } from './messages.js';
-export type { ChatEvent, StartEvent, TextDeltaEvent, ReasoningDeltaEvent, ToolCallEvent, ToolApprovalRequestEvent, ToolResultEvent, StepStartEvent, StepFinishEvent, ErrorEvent, FinishEvent, ChatStreamResult, } from './events.js';
+export type { ChatEvent, StartEvent, TextDeltaEvent, ReasoningDeltaEvent, ToolCallEvent, ToolApprovalRequestEvent, ToolResultEvent, StepStartEvent, StepFinishEvent, ErrorEvent, FinishEvent, ChatStreamResult, HarnessStreamResult, } from './events.js';
 export type { ToolDefinition, ToolCallInfo, ToolResultInfo } from './tools.js';
 export type { UsageMetadata, FinishReason } from './usage.js';
 export type { ModelConnectivityInfo, ProviderHint } from './model-connectivity-info.js';

package/dist/types/usage.d.ts

@@ -172,6 +172,10 @@ export type ContextUsage = {
  * - `max-steps` — The agentic loop was terminated because it reached the maximum step count.
  *   The model wanted to continue (e.g., it was requesting more tool calls) but the loop was forcibly stopped.
  *   This is distinct from `tool-calls` which in a step-finish context indicates normal mid-loop progress.
+ * - `cancelled` — The turn was stopped by an explicit cancellation — {@link ChatSession.cancelTurn} or the
+ *   caller aborting the turn's `abortSignal`. Distinct from `error`: a cancel is an intentional stop, not a
+ *   failure. The terminal `FinishEvent` for a cancelled turn always carries this reason (never `error`), and the
+ *   accompanying `ErrorEvent.code` is the canonical `'cancelled'` on every harness.
  * - `other` — Provider-specific reason that doesn't map to the standard values.
  */
-export type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'max-steps' | 'other';
+export type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'max-steps' | 'cancelled' | 'other';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.77.0",
+  "version": "0.79.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -48,9 +48,9 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.73.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.76.0",
-    "@salesforce/sfdx-agent-harness-openai": "0.42.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.75.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.78.0",
+    "@salesforce/sfdx-agent-harness-openai": "0.44.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.11",
     "@vitest/eslint-plugin": "^1.6.27",