@salesforce/sfdx-agent-sdk 0.66.0 → 0.67.0

package/CHANGELOG.md

@@ -3,6 +3,11 @@
 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.67.0] - 2026-09-02
+
+### Features
+- **agent-sdk,harness-mastra,harness-claude,harness-openai**: classify context-window overflow as a typed CONTEXT_LENGTH_EXCEEDED error @W-24074717@ ([#788](https://github.com/forcedotcom/agentic-dx/pull/788))
+
 ## [0.66.0] - 2026-09-02
 
 _No changes — released alongside dependent packages._

package/README.md

@@ -779,6 +779,7 @@ from `AgentSDKErrorType`:
 | `AGENT_NOT_FOUND`                | `AgentManager.getAgent()`, `AgentManager.destroyAgent()`, `AgentManager.recoverAgent()` (id neither live nor a restore-failure)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `CHAT_SESSION_NOT_FOUND`         | `Agent.getChatSession()`, `Agent.destroyChatSession()`, `Agent.cloneChatSession()`, `Agent.compactChatSession()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `COMPACTION_FAILED`              | `Agent.compactChatSession()` when the harness's underlying summarization call rejects. The original error is attached as `cause`; the source session is left intact.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `CONTEXT_LENGTH_EXCEEDED`        | A turn's prompt exceeds the model's context window and the provider rejects it (Anthropic/Bedrock HTTP 400 `invalid_request_error` with a token-count message; OpenAI `invalid_prompt`). Surfaces **in-stream** as the `error` on an `ErrorEvent` whose `code` is `'context-window-exceeded'` (both mapped from one classification, so `error instanceof AgentSDKError && err.type === CONTEXT_LENGTH_EXCEEDED` ⟺ `code === 'context-window-exceeded'`), with the actionable message _"context window limit reached — compact this chat or start a new one."_ and the raw provider error on `.cause`. Classified uniformly by all three harnesses. Recover by compacting (`Agent.compactChatSession()`) or starting a new chat. Build/branch on it via the exported `CONTEXT_LENGTH_EXCEEDED_CODE`, `createContextLengthExceededError()`, and `isContextWindowOverflowMessage()` helpers.                                                                                                                                                                                                                                                                                                                                                     |
 | `DISPOSED`                       | `Agent` and `ChatSession` methods called after the owner has been destroyed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `INCOMPATIBLE_HARNESS`           | `createAgentManager()` when the factory advertises an unsupported `protocolVersion`, or the constructed harness reports a `protocolVersion` that differs from the factory's                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `INVALID_MESSAGE_CONTENT`        | `ChatSession.chat()` / harness `stream()` when a message part is not valid as input (a `tool-call`/`tool-result` part, or non-base64-string file data); also `ChatSession.setSessionContext()` / harness `setSessionContext()` when the object exceeds a harness's size / nesting bounds (Mastra: 256 KiB serialized, depth 200). `getSessionContext()` never throws on a corrupt stored slot — it soft-skips to `{}` and logs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

package/dist/chat-session.d.ts

@@ -487,6 +487,26 @@ export declare class DefaultChatSession implements ChatSession {
      *   input-side counts at all.
      */
     getContextUsage(): ContextUsage;
+    /**
+     * The last-step context numerator — the sum of all three input-bearing usage
+     * fields, or `undefined` when ALL three are absent (a fresh session or a turn
+     * with a gateway usage gap). This is the single definition of "how full is the
+     * context" shared by {@link getContextUsage} (as `usedFraction`'s numerator)
+     * and {@link contextUsageLogFields} (as the log's `contextTokens`), so the two
+     * can't drift. The cache fields are load-bearing on Bedrock-Claude — see the
+     * SDK ARCHITECTURE note on the `usedFraction` numerator.
+     */
+    private effectiveInputTokens;
+    /**
+     * Compact context-window fields for the `chat-stream-completed` log record —
+     * the fraction (rounded to a percent), the token amount that fraction is over,
+     * and the window it is out of. Empty when the turn reported no input-side usage
+     * (so the completion log stays unchanged pre-first-turn / post-`clearHistory()`).
+     * Shares {@link getContextUsage}'s last-step numerator via
+     * {@link effectiveInputTokens}, read from the same `latestUsage` snapshot
+     * `wrapEventStream` captures.
+     */
+    private contextUsageLogFields;
     /**
      * @requirements
      * - IF `message` is a `string`, it MUST be formatted into a standard `Message` object array containing exactly one message.

package/dist/chat-session.js

@@ -304,6 +304,13 @@ export class DefaultChatSession {
                 durationMs,
                 usage: finishUsage,
             }, finishedAt);
+            // Fold the post-turn context-window occupancy onto the existing
+            // completion log — % and token amount, so an operator can watch a
+            // thread approach its limit (and correlate with a later
+            // `context-window-exceeded` failure) without subscribing to
+            // telemetry or adding a separate, noisier log line. Reuses the
+            // `getContextUsage()` snapshot (last-step semantics), so it is
+            // present only once a step reported usage; omitted otherwise.
             this.logBus.emitLog({
                 level: 'info',
                 message: 'Chat stream completed',
@@ -313,6 +320,7 @@ export class DefaultChatSession {
                     threadId: this.threadId,
                     durationMs,
                     ...(finishUsage !== undefined ? { usage: finishUsage } : {}),
+                    ...this.contextUsageLogFields(),
                 },
             }, finishedAt);
         }
@@ -431,11 +439,7 @@ export class DefaultChatSession {
     getContextUsage() {
         this.assertNotDisposed();
         const contextWindow = this.getContextWindow();
-        const { inputTokens, cachedInputTokens, cacheWriteInputTokens } = this.latestUsage;
-        const allInputUndefined = inputTokens === undefined && cachedInputTokens === undefined && cacheWriteInputTokens === undefined;
-        const effectiveInputTokens = allInputUndefined
-            ? undefined
-            : (inputTokens ?? 0) + (cachedInputTokens ?? 0) + (cacheWriteInputTokens ?? 0);
+        const effectiveInputTokens = this.effectiveInputTokens();
         const usedFraction = effectiveInputTokens === undefined
             ? undefined
             : Math.min(1, Math.max(0, effectiveInputTokens / contextWindow));
@@ -445,6 +449,42 @@ export class DefaultChatSession {
         // all primitives, so a shallow copy is sufficient.
         return { usage: { ...this.latestUsage }, contextWindow, usedFraction };
     }
+    /**
+     * The last-step context numerator — the sum of all three input-bearing usage
+     * fields, or `undefined` when ALL three are absent (a fresh session or a turn
+     * with a gateway usage gap). This is the single definition of "how full is the
+     * context" shared by {@link getContextUsage} (as `usedFraction`'s numerator)
+     * and {@link contextUsageLogFields} (as the log's `contextTokens`), so the two
+     * can't drift. The cache fields are load-bearing on Bedrock-Claude — see the
+     * SDK ARCHITECTURE note on the `usedFraction` numerator.
+     */
+    effectiveInputTokens() {
+        const { inputTokens, cachedInputTokens, cacheWriteInputTokens } = this.latestUsage;
+        if (inputTokens === undefined && cachedInputTokens === undefined && cacheWriteInputTokens === undefined) {
+            return undefined;
+        }
+        return (inputTokens ?? 0) + (cachedInputTokens ?? 0) + (cacheWriteInputTokens ?? 0);
+    }
+    /**
+     * Compact context-window fields for the `chat-stream-completed` log record —
+     * the fraction (rounded to a percent), the token amount that fraction is over,
+     * and the window it is out of. Empty when the turn reported no input-side usage
+     * (so the completion log stays unchanged pre-first-turn / post-`clearHistory()`).
+     * Shares {@link getContextUsage}'s last-step numerator via
+     * {@link effectiveInputTokens}, read from the same `latestUsage` snapshot
+     * `wrapEventStream` captures.
+     */
+    contextUsageLogFields() {
+        const contextTokens = this.effectiveInputTokens();
+        if (contextTokens === undefined)
+            return {};
+        const contextWindow = this.getContextWindow();
+        return {
+            contextTokens,
+            contextWindow,
+            contextUsedPercent: Math.round(Math.min(1, Math.max(0, contextTokens / contextWindow)) * 100),
+        };
+    }
     /**
      * @requirements
      * - IF `message` is a `string`, it MUST be formatted into a standard `Message` object array containing exactly one message.

package/dist/errors.d.ts

@@ -2,6 +2,7 @@ export declare const AgentSDKErrorType: {
     readonly AGENT_NOT_FOUND: 'AGENT_NOT_FOUND';
     readonly CHAT_SESSION_NOT_FOUND: 'CHAT_SESSION_NOT_FOUND';
     readonly COMPACTION_FAILED: 'COMPACTION_FAILED';
+    readonly CONTEXT_LENGTH_EXCEEDED: 'CONTEXT_LENGTH_EXCEEDED';
     readonly DISPOSED: 'DISPOSED';
     readonly INCOMPATIBLE_HARNESS: 'INCOMPATIBLE_HARNESS';
     readonly INVALID_MCP_AUTH_CONFIG: 'INVALID_MCP_AUTH_CONFIG';
@@ -20,3 +21,40 @@ export declare class AgentSDKError extends Error {
     readonly type: AgentSDKErrorType;
     constructor(message: string, type: AgentSDKErrorType, options?: ErrorOptions);
 }
+/**
+ * Canonical machine-readable `ErrorEvent.code` for a context-window overflow —
+ * the prompt for the next turn exceeds the model's context window and the
+ * provider rejects it (Anthropic/Bedrock HTTP 400 `invalid_request_error` with a
+ * token-count message; OpenAI `invalid_prompt`). Shipped first on the Mastra
+ * harness (#782); this constant is the single source every harness now stamps so
+ * the wire code can't drift, and it maps 1:1 to
+ * {@link AgentSDKErrorType.CONTEXT_LENGTH_EXCEEDED} (the typed error carried on
+ * the same {@link ErrorEvent}'s `error`; a deferred pre-flight guard would throw
+ * that same typed error before the turn). Both wires (native `/events`, AG-UI)
+ * relay `code` verbatim, so the value is a contract — do not rename it.
+ */
+export declare const CONTEXT_LENGTH_EXCEEDED_CODE: 'context-window-exceeded';
+/**
+ * Actionable, consumer-facing message for a context-window overflow. Carried as
+ * the {@link AgentSDKError} message so the same text surfaces in-stream (on
+ * `ErrorEvent.error`) today, and would surface identically once the deferred
+ * pre-flight guard in `ChatSession.chat()` lands. The underlying provider error
+ * is preserved on `.cause`.
+ */
+export declare const CONTEXT_LENGTH_EXCEEDED_MESSAGE: 'context window limit reached — compact this chat or start a new one.';
+/**
+ * Whether `message` looks like a provider context-window-overflow rejection.
+ * Harnesses call this on the provider error's message text to decide whether to
+ * classify a failure as {@link AgentSDKErrorType.CONTEXT_LENGTH_EXCEEDED}.
+ */
+export declare function isContextWindowOverflowMessage(message: string): boolean;
+/**
+ * Builds the canonical typed context-window-overflow error. Every harness sets
+ * this as the `error` on an `ErrorEvent` whose `code` is
+ * {@link CONTEXT_LENGTH_EXCEEDED_CODE}; a deferred pre-flight guard in
+ * `ChatSession.chat()` would throw this same typed error when the next turn would
+ * clearly overflow — so the in-stream and pre-flight overflow signals are one
+ * typed error, not two. The provider error (when known) rides on `.cause` so its
+ * detail survives.
+ */
+export declare function createContextLengthExceededError(cause?: unknown): AgentSDKError;

package/dist/errors.js

@@ -6,6 +6,7 @@ export const AgentSDKErrorType = {
     AGENT_NOT_FOUND: 'AGENT_NOT_FOUND',
     CHAT_SESSION_NOT_FOUND: 'CHAT_SESSION_NOT_FOUND',
     COMPACTION_FAILED: 'COMPACTION_FAILED',
+    CONTEXT_LENGTH_EXCEEDED: 'CONTEXT_LENGTH_EXCEEDED',
     DISPOSED: 'DISPOSED',
     INCOMPATIBLE_HARNESS: 'INCOMPATIBLE_HARNESS',
     INVALID_MCP_AUTH_CONFIG: 'INVALID_MCP_AUTH_CONFIG',
@@ -27,4 +28,52 @@ export class AgentSDKError extends Error {
         this.type = type;
     }
 }
+/**
+ * Canonical machine-readable `ErrorEvent.code` for a context-window overflow —
+ * the prompt for the next turn exceeds the model's context window and the
+ * provider rejects it (Anthropic/Bedrock HTTP 400 `invalid_request_error` with a
+ * token-count message; OpenAI `invalid_prompt`). Shipped first on the Mastra
+ * harness (#782); this constant is the single source every harness now stamps so
+ * the wire code can't drift, and it maps 1:1 to
+ * {@link AgentSDKErrorType.CONTEXT_LENGTH_EXCEEDED} (the typed error carried on
+ * the same {@link ErrorEvent}'s `error`; a deferred pre-flight guard would throw
+ * that same typed error before the turn). Both wires (native `/events`, AG-UI)
+ * relay `code` verbatim, so the value is a contract — do not rename it.
+ */
+export const CONTEXT_LENGTH_EXCEEDED_CODE = 'context-window-exceeded';
+/**
+ * Actionable, consumer-facing message for a context-window overflow. Carried as
+ * the {@link AgentSDKError} message so the same text surfaces in-stream (on
+ * `ErrorEvent.error`) today, and would surface identically once the deferred
+ * pre-flight guard in `ChatSession.chat()` lands. The underlying provider error
+ * is preserved on `.cause`.
+ */
+export const CONTEXT_LENGTH_EXCEEDED_MESSAGE = 'context window limit reached — compact this chat or start a new one.';
+/**
+ * Provider overflow-message patterns, shared across harnesses so the recognition
+ * of a context-window rejection can't drift between the three implementations.
+ * Matches the token-count / context-length phrasings Anthropic/Bedrock
+ * (`ValidationException`) and OpenAI (`invalid_prompt`) use.
+ */
+const CONTEXT_WINDOW_OVERFLOW_PATTERNS = /input is too long|prompt is too long|too many (input )?tokens|maximum context length|context (window|length)|exceed(s|ed)? (the )?(maximum )?context/i;
+/**
+ * Whether `message` looks like a provider context-window-overflow rejection.
+ * Harnesses call this on the provider error's message text to decide whether to
+ * classify a failure as {@link AgentSDKErrorType.CONTEXT_LENGTH_EXCEEDED}.
+ */
+export function isContextWindowOverflowMessage(message) {
+    return CONTEXT_WINDOW_OVERFLOW_PATTERNS.test(message);
+}
+/**
+ * Builds the canonical typed context-window-overflow error. Every harness sets
+ * this as the `error` on an `ErrorEvent` whose `code` is
+ * {@link CONTEXT_LENGTH_EXCEEDED_CODE}; a deferred pre-flight guard in
+ * `ChatSession.chat()` would throw this same typed error when the next turn would
+ * clearly overflow — so the in-stream and pre-flight overflow signals are one
+ * typed error, not two. The provider error (when known) rides on `.cause` so its
+ * detail survives.
+ */
+export function createContextLengthExceededError(cause) {
+    return new AgentSDKError(CONTEXT_LENGTH_EXCEEDED_MESSAGE, AgentSDKErrorType.CONTEXT_LENGTH_EXCEEDED, cause !== undefined ? { cause } : undefined);
+}
 //# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export type { ModelConnectivityInfo, ProviderHint } from './types/model-connecti
 export type { LlmRequestEvent, LlmResponseEvent, McpToolCallCompletedEvent, WireCommunicationEvent, WireCommunicationEventCallback, WireMonitoringNotSupportedEvent, } from './types/wire-communication-event.js';
 export { WireCommunicationFileWriter, type WireCommunicationEmitter, type WireCommunicationFileWriterOptions, } from './wire-communication-file-writer.js';
 export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './harness/index.js';
-export { AgentSDKError, AgentSDKErrorType } from './errors.js';
+export { AgentSDKError, AgentSDKErrorType, CONTEXT_LENGTH_EXCEEDED_CODE, CONTEXT_LENGTH_EXCEEDED_MESSAGE, createContextLengthExceededError, isContextWindowOverflowMessage, } from './errors.js';
 export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent, ChatStreamErrorEvent, ChatStreamStartedEvent, ChatStreamTrigger, LlmRetryEvent, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, McpServerStatusChangedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalPolicyResolvedEvent, ToolApprovalRequestedEvent, ToolApprovalResolvedEvent, ToolExecutionCompletedEvent, ToolExecutionStartedEvent, } from './types/telemetry-events.js';
 export type { LogLevel, LogRecord, Unsubscribe } from '@salesforce/agentic-common';
 export type { EnvironmentFields } from '@salesforce/agentic-common';

package/dist/index.js

@@ -20,7 +20,7 @@ export {} from './chat-session.js';
 export { ApiKeyConnectivityResolver } from './api-key-connectivity-resolver.js';
 export { WireCommunicationFileWriter, } from './wire-communication-file-writer.js';
 // ── Errors ───────────────────────────────────────────────────────────
-export { AgentSDKError, AgentSDKErrorType } from './errors.js';
+export { AgentSDKError, AgentSDKErrorType, CONTEXT_LENGTH_EXCEEDED_CODE, CONTEXT_LENGTH_EXCEEDED_MESSAGE, createContextLengthExceededError, isContextWindowOverflowMessage, } from './errors.js';
 export { readEnvironmentContext, resolveFeatureId } from '@salesforce/agentic-common';
 // ── MCP Auth ────────────────────────────────────────────────────────
 export { resolveMcpServerHeaders, isSalesforcePlatformMcpUrl } from './mcp-auth.js';

package/dist/types/events.d.ts

@@ -247,9 +247,23 @@ export type StepFinishEvent = {
 /** An error occurred during streaming. */
 export type ErrorEvent = {
     type: 'error';
-    /** The error that occurred. */
+    /**
+     * The error that occurred. For a classified failure this is a typed
+     * {@link AgentSDKError} whose `type` maps 1:1 to {@link code} — e.g. a
+     * context-window overflow carries `AgentSDKErrorType.CONTEXT_LENGTH_EXCEEDED`
+     * with `code === 'context-window-exceeded'`. An unrecognized provider error
+     * surfaces as a plain `Error` with no `code`.
+     */
     error: Error;
-    /** Machine-readable error code (e.g., `'insufficient-tokens'`). */
+    /**
+     * 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'`).
+     * `undefined` when the harness could not classify the error.
+     */
     code?: string;
 };
 /** The entire stream has completed. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.66.0",
+  "version": "0.67.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -47,9 +47,9 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.62.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.65.0",
-    "@salesforce/sfdx-agent-harness-openai": "0.31.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.63.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.66.0",
+    "@salesforce/sfdx-agent-harness-openai": "0.32.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.27",