@salesforce/sfdx-agent-sdk 0.75.0 → 0.76.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.76.0] - 2026-09-08
+
+### Features
+- **agent-sdk**: self-describing usage fields on getContextUsage + telemetry @W-24125085@ ([#802](https://github.com/forcedotcom/agentic-dx/pull/802))
+
 ## [0.75.0] - 2026-09-08
 
 _No changes — released alongside dependent packages._

package/README.md

@@ -725,18 +725,40 @@ type UsageMetadata = {
 
 type ContextUsage = {
   /**
-   * Last per-step usage reading observed on this session. Pre-first-turn and
-   * immediately after `clearHistory()` this is `{}` (every token field undefined).
+   * Legacy alias for `lastStepUsage` (identical value). Retained so existing
+   * callers don't break; new consumers should read `lastStepUsage`. `{}`
+   * pre-first-turn / post-`clearHistory()`.
    */
   usage: UsageMetadata;
+  /**
+   * The last model step's usage — the "how full is my context" reading.
+   * ≡ `usage`. Always populated; `{}` pre-first-turn / post-`clearHistory()`.
+   */
+  lastStepUsage: UsageMetadata;
+  /**
+   * The whole-turn aggregate (`finish.usage`) from the last completed turn — the
+   * billing/throughput total. Sums every step and can exceed `contextWindow`, so
+   * it is NOT an occupancy reading; read `stepCount` to interpret it. Absent
+   * pre-first-turn, after `clearHistory()`, and when the turn produced no
+   * `finish.usage`.
+   */
+  turnUsage?: UsageMetadata;
+  /** Model steps in the last completed turn. Absent pre-first-turn / post-`clearHistory()`. */
+  stepCount?: number;
   /** The model's total context-window size in tokens. Always populated. */
   contextWindow: number;
   /**
-   * `(usage.inputTokens + usage.cachedInputTokens + usage.cacheWriteInputTokens) / contextWindow`,
-   * clamped to [0, 1]. Cached prompt tokens are summed in because they occupy the
-   * model's context window — on Bedrock-Claude, the bulk of the prompt is reported
-   * via `cachedInputTokens` / `cacheWriteInputTokens`, not `inputTokens`. `undefined`
-   * when ALL three input-bearing fields are missing.
+   * The raw numerator behind `usedFraction` — the last step's effective input
+   * `(inputTokens ?? 0) + (cachedInputTokens ?? 0) + (cacheWriteInputTokens ?? 0)`.
+   * `undefined` under the same condition as `usedFraction`.
+   */
+  contextTokens: number | undefined;
+  /**
+   * `contextTokens / contextWindow`, clamped to [0, 1]. Cached prompt tokens are
+   * summed into `contextTokens` because they occupy the model's context window —
+   * on Bedrock-Claude, the bulk of the prompt is reported via `cachedInputTokens`
+   * / `cacheWriteInputTokens`, not `inputTokens`. `undefined` when ALL three
+   * input-bearing fields are missing.
    */
   usedFraction: number | undefined;
 };
@@ -765,9 +787,17 @@ const pct = ctx.usedFraction !== undefined ? `${Math.round(ctx.usedFraction * 10
 return `${used} / ${limit} tokens (${pct})`;
 ```
 
-The snapshot uses **last-step** semantics, not the per-turn billing aggregate — `finish.usage` sums all steps in a turn
-and double-counts persistent context, which is the wrong denominator for "how full is my context." For per-turn billing
-totals, subscribe to `chat-stream-completed` telemetry instead.
+Occupancy (`contextTokens` / `usedFraction`) uses **last-step** semantics, not the per-turn billing aggregate —
+`finish.usage` sums all steps in a turn and double-counts persistent context, which is the wrong denominator for "how
+full is my context." When you do want the per-turn total, read `turnUsage` (and `stepCount` to interpret it) on the same
+snapshot, or subscribe to `chat-stream-completed` telemetry — both carry the identical aggregate.
+
+> **`usage` is deprecated.** `usage` still works and is unchanged, but it is marked `@deprecated` (W-24125085) — read
+> the explicit names instead: `lastStepUsage` for occupancy, `turnUsage` + `stepCount` for the per-turn total. The alias
+> points at different measurements per surface, which is exactly the ambiguity the explicit names remove: on
+> `ContextUsage` / the REST `context-usage` response `usage` aliases the **last step**, while on `chat-stream-completed`
+> telemetry it aliases the **whole-turn aggregate**. Removal is gated on a future major once consumers have migrated
+> (W-24125086).
 
 ### Error Handling
 

package/dist/chat-session.d.ts

@@ -193,16 +193,22 @@ export interface ChatSession {
     /**
      * Snapshot of how much of the model's context window the most recent
      * turn used. Always returns a `ContextUsage` — pre-first-turn and
-     * immediately after `clearHistory()`, `usage` is `{}` and `usedFraction`
-     * is `undefined`, but `contextWindow` is always populated from the
-     * agent's currently-bound model.
+     * immediately after `clearHistory()`, `usage` / `lastStepUsage` are `{}`,
+     * `turnUsage` / `stepCount` are absent, and `usedFraction` / `contextTokens`
+     * are `undefined`, but `contextWindow` is always populated from the agent's
+     * currently-bound model.
      *
-     * `usage` carries the **last per-step** reading from the model — the
-     * size of the prompt the model saw on its most recent invocation,
-     * which is the right "how full is my context" answer for deciding
-     * when to call `compactThread()`. This is **not** the per-turn billing
-     * aggregate; consumers who want billing totals should subscribe to
-     * `chat-stream-completed` telemetry.
+     * Two self-describing measurements (Phase 2, W-24125085), with `usage`
+     * retained as the legacy alias for the last-step reading:
+     *
+     * - **`lastStepUsage`** (≡ `usage`) — the **last per-step** reading from the
+     *   model, the size of the prompt the model saw on its most recent
+     *   invocation. The right "how full is my context" answer for deciding when
+     *   to call `compactThread()`; `usedFraction` / `contextTokens` derive from it.
+     * - **`turnUsage`** (+ `stepCount`) — the whole-turn billing/throughput
+     *   aggregate (`finish.usage`). It sums every step and can exceed
+     *   `contextWindow`, so it is **not** an occupancy reading. Equivalent to the
+     *   per-turn total on `chat-stream-completed` telemetry.
      *
      * The `contextWindow` is read live from the agent's currently-bound
      * model, so it reflects any `Agent.updateAgentConfig()` model swap
@@ -339,6 +345,19 @@ export declare class DefaultChatSession implements ChatSession {
      * thread starts unprimed.
      */
     private latestUsage;
+    /**
+     * The whole-turn aggregate (`finish.usage`) and model-step count from the
+     * last COMPLETED turn, retained as session state so {@link getContextUsage}
+     * can return them as `turnUsage` / `stepCount` (Phase 1 counted `stepCount`
+     * as a `wrapEventStream` local; Phase 2, W-24125085, promotes both to
+     * session state — mirroring {@link latestUsage}). Set in `wrapEventStream`'s
+     * natural-completion branch (never on an errored / abandoned turn), read by
+     * `getContextUsage`, and reset by `clearHistory()`. `latestTurnUsage` is
+     * `undefined` (not `{}`) pre-first-turn so `turnUsage` is *absent* rather
+     * than empty; `latestStepCount` is `0` so `stepCount` is likewise omitted.
+     */
+    private latestTurnUsage;
+    private latestStepCount;
     private disposed;
     /**
      * True while a turn started by {@link chat} is in flight — from the `chat()`
@@ -459,8 +478,10 @@ export declare class DefaultChatSession implements ChatSession {
     /**
      * @requirements
      * - MUST delegate to `this.harness.clearMessages()`, passing `this.agentId` and `this.threadId`.
-     * - MUST reset `latestUsage` to `{}` so the next `getContextUsage()` reports a fresh
-     *   "no reading yet" snapshot until the next turn produces one.
+     * - MUST reset `latestUsage` to `{}` and drop the retained per-turn state
+     *   (`latestTurnUsage` / `latestStepCount`) so the next `getContextUsage()`
+     *   reports a fresh "no reading yet" snapshot (`turnUsage` / `stepCount`
+     *   absent) until the next turn produces one.
      */
     clearHistory(): Promise<void>;
     /**

package/dist/chat-session.js

@@ -72,6 +72,19 @@ export class DefaultChatSession {
      * thread starts unprimed.
      */
     latestUsage = {};
+    /**
+     * The whole-turn aggregate (`finish.usage`) and model-step count from the
+     * last COMPLETED turn, retained as session state so {@link getContextUsage}
+     * can return them as `turnUsage` / `stepCount` (Phase 1 counted `stepCount`
+     * as a `wrapEventStream` local; Phase 2, W-24125085, promotes both to
+     * session state — mirroring {@link latestUsage}). Set in `wrapEventStream`'s
+     * natural-completion branch (never on an errored / abandoned turn), read by
+     * `getContextUsage`, and reset by `clearHistory()`. `latestTurnUsage` is
+     * `undefined` (not `{}`) pre-first-turn so `turnUsage` is *absent* rather
+     * than empty; `latestStepCount` is `0` so `stepCount` is likewise omitted.
+     */
+    latestTurnUsage = undefined;
+    latestStepCount = 0;
     disposed = false;
     /**
      * True while a turn started by {@link chat} is in flight — from the `chat()`
@@ -311,12 +324,34 @@ export class DefaultChatSession {
             }, finishedAt);
         }
         else {
+            // Retain the turn's aggregate + step count as session state so a later
+            // `getContextUsage()` can return `turnUsage` / `stepCount` (the last-step
+            // `latestUsage` is already retained per step-finish). Only the natural-
+            // completion branch runs this — an errored or abandoned turn leaves the
+            // last COMPLETED turn's figures in place, matching the completion log,
+            // which is likewise emitted only here. COPY `finishUsage` on retain so the
+            // retained state does NOT alias the object the emit sites below forward by
+            // reference: otherwise a telemetry/log subscriber mutating the emitted
+            // `turnUsage` would corrupt `latestTurnUsage` and surface on a later
+            // `getContextUsage()` (which spreads on read, carrying the mutation).
+            this.latestTurnUsage = finishUsage === undefined ? undefined : { ...finishUsage };
+            this.latestStepCount = stepCount;
             this.telemetryBus.emitTelemetry({
                 type: 'chat-stream-completed',
                 agentId: this.agentId,
                 threadId: this.threadId,
                 durationMs,
+                // Self-describing usage on telemetry (W-24125085, Phase 2): `usage`
+                // stays as the legacy alias for the whole-turn aggregate, now also
+                // named `turnUsage`; `lastStepUsage` carries the last-step reading
+                // (spread so consumer mutation can't leak into retained state); and
+                // `stepCount` makes the aggregate interpretable. Omitted-when-absent
+                // for `stepCount` only — `usage`/`turnUsage` keep the prior field's
+                // always-present shape (both are `finishUsage`, so they stay ≡).
                 usage: finishUsage,
+                turnUsage: finishUsage,
+                lastStepUsage: { ...this.latestUsage },
+                ...(stepCount > 0 ? { stepCount } : {}),
             }, finishedAt);
             // Fold the turn's usage + post-turn context-window occupancy onto the
             // existing completion log so an operator can read both without
@@ -334,11 +369,14 @@ export class DefaultChatSession {
             // step reports, and `contextUsageLogFields()` stays empty pre-first-turn /
             // post-`clearHistory()`.
             //
-            // `turnUsage` forwards `finishUsage` BY REFERENCE (unlike `lastStepUsage`,
-            // which spreads `latestUsage`): `finishUsage` is a turn-local value discarded
-            // when this method returns, so no consumer can observe mutation of it;
-            // `latestUsage` is retained session state a later `getContextUsage()` reads,
-            // so it must be copied.
+            // Both emit sites (this log and the telemetry event above) forward
+            // `turnUsage`/`usage` as `finishUsage` BY REFERENCE. That stays safe because
+            // `finishUsage` is a turn-local value discarded when this method returns — the
+            // retained `latestTurnUsage` is a COPY of it (see above), so it does not alias
+            // `finishUsage` and no consumer can corrupt session state by mutating the
+            // emitted object. `lastStepUsage` instead spreads `latestUsage` (retained
+            // session state a later `getContextUsage()` reads), so it is copied at the
+            // emit site.
             this.logBus.emitLog({
                 level: 'info',
                 message: 'Chat stream completed',
@@ -434,13 +472,17 @@ export class DefaultChatSession {
     /**
      * @requirements
      * - MUST delegate to `this.harness.clearMessages()`, passing `this.agentId` and `this.threadId`.
-     * - MUST reset `latestUsage` to `{}` so the next `getContextUsage()` reports a fresh
-     *   "no reading yet" snapshot until the next turn produces one.
+     * - MUST reset `latestUsage` to `{}` and drop the retained per-turn state
+     *   (`latestTurnUsage` / `latestStepCount`) so the next `getContextUsage()`
+     *   reports a fresh "no reading yet" snapshot (`turnUsage` / `stepCount`
+     *   absent) until the next turn produces one.
      */
     async clearHistory() {
         this.assertNotDisposed();
         await this.harness.clearMessages(this.agentId, this.threadId);
         this.latestUsage = {};
+        this.latestTurnUsage = undefined;
+        this.latestStepCount = 0;
     }
     /**
      * @requirements
@@ -468,15 +510,29 @@ export class DefaultChatSession {
     getContextUsage() {
         this.assertNotDisposed();
         const contextWindow = this.getContextWindow();
-        const effectiveInputTokens = this.effectiveInputTokens();
-        const usedFraction = effectiveInputTokens === undefined
-            ? undefined
-            : Math.min(1, Math.max(0, effectiveInputTokens / contextWindow));
-        // Spread `latestUsage` so consumer mutation of the returned `usage`
-        // object cannot leak back into the session's internal state on a
-        // subsequent `getContextUsage()` call. `UsageMetadata`'s fields are
-        // all primitives, so a shallow copy is sufficient.
-        return { usage: { ...this.latestUsage }, contextWindow, usedFraction };
+        const contextTokens = this.effectiveInputTokens();
+        const usedFraction = contextTokens === undefined ? undefined : Math.min(1, Math.max(0, contextTokens / contextWindow));
+        // Spread `latestUsage` so consumer mutation of the returned object cannot
+        // leak back into the session's retained state on a later call. `usage` is
+        // the legacy alias for `lastStepUsage` (Phase 2, W-24125085) — the SAME
+        // object, so a consumer migrating from `usage` reads identical data.
+        // `UsageMetadata`'s fields are all primitives, so a shallow copy suffices.
+        const lastStepUsage = { ...this.latestUsage };
+        return {
+            usage: lastStepUsage,
+            lastStepUsage,
+            contextWindow,
+            // `contextTokens` mirrors `usedFraction`'s presence (both `undefined`
+            // when the latest reading carries no input-side tokens).
+            contextTokens,
+            usedFraction,
+            // `turnUsage` (spread for the same anti-leak reason) and `stepCount`
+            // describe the last COMPLETED turn; omitted pre-first-turn /
+            // post-`clearHistory()` and (for `turnUsage`) when the turn produced
+            // no `finish.usage`, matching the completion log's omit-when-absent.
+            ...(this.latestTurnUsage !== undefined ? { turnUsage: { ...this.latestTurnUsage } } : {}),
+            ...(this.latestStepCount > 0 ? { stepCount: this.latestStepCount } : {}),
+        };
     }
     /**
      * The last-step context numerator — the sum of all three input-bearing usage

package/dist/types/telemetry-events.d.ts

@@ -42,7 +42,31 @@ export type ChatStreamCompletedEvent = Base<'chat-stream-completed'> & {
     agentId: string;
     threadId: string;
     durationMs: number;
+    /**
+     * @deprecated Use {@link turnUsage} (identical value). `usage` is the
+     * ambiguous legacy name — it aliases the *whole-turn aggregate* here but the
+     * *last step* on `ContextUsage`, which is exactly the confusion the explicit
+     * names remove. Retained so existing telemetry consumers don't break
+     * (W-24125085); slated for removal in a future major (W-24125086).
+     *
+     * The whole-turn aggregate (`finish.usage`).
+     */
     usage?: UsageMetadata;
+    /**
+     * The whole-turn aggregate (`finish.usage`) — the billing/throughput total.
+     * Identical to {@link usage} (the legacy alias). Sums every step; read
+     * {@link stepCount} to interpret it.
+     */
+    turnUsage?: UsageMetadata;
+    /**
+     * The last model step's usage — the right "how full is my context" reading
+     * (the same measurement `ChatSession.getContextUsage()` returns). Carries
+     * forward the last reported reading across a usage gap (W-22692131); `{}`
+     * only when no step has reported since session start / `clearHistory()`.
+     */
+    lastStepUsage?: UsageMetadata;
+    /** Number of model steps in the turn. Absent when the turn had no reporting step. */
+    stepCount?: number;
 };
 export type ChatStreamErrorEvent = Base<'chat-stream-error'> & {
     agentId: string;

package/dist/types/usage.d.ts

@@ -42,20 +42,33 @@ export type UsageMetadata = {
  * smaller model, or warn the user as the conversation approaches the
  * model's context limit.
  *
- * `usage` carries the **last per-step** reading from the model —
- * specifically the `usage` from the latest `step-finish` event whose `usage`
- * was defined. This is the size of the prompt the model saw on its last
- * invocation, which is the right "how full is my context" reading. This is
- * **not** the per-turn billing aggregate (which sums steps and double-counts
- * persistent context). For per-turn billing totals, subscribe to
- * `chat-stream-completed` telemetry instead.
+ * Two self-describing measurements name the two things a reader might want
+ * (Phase 2, W-24125085), and the ambiguous **`usage` is retained as a
+ * documented alias** for the last-step reading so no existing consumer breaks:
+ *
+ * - **`lastStepUsage`** (≡ `usage`) — the `usage` from the latest `step-finish`
+ *   event whose `usage` was defined: the size of the prompt the model saw on
+ *   its last invocation, the right "how full is my context" reading. New
+ *   consumers should read `lastStepUsage`; `usage` is the legacy alias.
+ * - **`turnUsage`** — the whole-turn aggregate (`finish.usage`): the
+ *   billing/throughput total. It sums every step and can exceed `contextWindow`,
+ *   so it is **not** an occupancy reading; read `stepCount` alongside it to
+ *   interpret its size.
  *
  * Field shapes:
  *
- * - `usage` is always populated. Pre-first-turn (or post-`clearHistory()`)
- *   it is the empty object `{}` — i.e., a `UsageMetadata` whose token fields
- *   are all `undefined` — making "no reading yet" indistinguishable from
- *   "harness reported every field as undefined."
+ * - `usage` / `lastStepUsage` are always populated (and identical).
+ *   Pre-first-turn (or post-`clearHistory()`) they are the empty object `{}` —
+ *   i.e., a `UsageMetadata` whose token fields are all `undefined` — making
+ *   "no reading yet" indistinguishable from "harness reported every field as
+ *   undefined."
+ * - `turnUsage` and `stepCount` describe the last **completed** turn and are
+ *   **absent** pre-first-turn, after `clearHistory()`, and (for `turnUsage`)
+ *   when the completed turn produced no `finish.usage`.
+ * - `contextTokens` is the raw numerator behind `usedFraction`; `undefined`
+ *   under the same condition as `usedFraction`. Added so the SDK exposes the
+ *   same three occupancy fields (`contextTokens` / `contextWindow` /
+ *   `usedFraction`) as the completion log.
  * - `contextWindow` is always populated, contractually. Every `Model`
  *   bound to an `Agent` via `ModelConnectivityInfo.model` must publish a
  *   `contextWindow`; see the `sfdx-agent-sdk` ARCHITECTURE.md Critical
@@ -70,17 +83,56 @@ export type UsageMetadata = {
  */
 export type ContextUsage = {
     /**
-     * Last per-step usage reading observed on this session. Pre-first-turn
-     * and immediately after `clearHistory()` this is `{}` (every token field
-     * undefined).
+     * @deprecated Use {@link lastStepUsage} (identical value). `usage` is the
+     * ambiguous legacy name — it aliases the *last step* here but the *whole-turn
+     * aggregate* on `chat-stream-completed` telemetry, which is exactly the
+     * confusion the explicit names remove. Retained so existing callers don't
+     * break (W-24125085); slated for removal in a future major (W-24125086).
+     *
+     * Last per-step usage reading. Pre-first-turn and immediately after
+     * `clearHistory()` this is `{}` (every token field undefined).
      */
     usage: UsageMetadata;
+    /**
+     * The last model step's usage — the size of the prompt the model saw on its
+     * most recent invocation, the right "how full is my context" reading.
+     * Identical to {@link usage} (the legacy alias). Always populated; `{}`
+     * pre-first-turn / post-`clearHistory()`.
+     */
+    lastStepUsage: UsageMetadata;
+    /**
+     * The whole-turn aggregate (`finish.usage`) from the last **completed** turn —
+     * the billing/throughput total. It sums every step and can exceed
+     * {@link contextWindow}, so read {@link stepCount} to interpret it:
+     * `lastStepUsage.inputTokens ≤ turnUsage.inputTokens ≤ lastStepUsage.inputTokens × stepCount`
+     * (the lower bound is strict only when `stepCount > 1`). **Absent**
+     * pre-first-turn, after `clearHistory()`, and when the completed turn
+     * produced no `finish.usage`. This is the value `chat-stream-completed`
+     * telemetry carries as its `usage` alias.
+     */
+    turnUsage?: UsageMetadata;
+    /**
+     * Number of model steps in the last **completed** turn (counts every step,
+     * including one whose `step-finish` reported undefined usage — W-22692131).
+     * Makes {@link turnUsage} interpretable next to {@link lastStepUsage}.
+     * **Absent** pre-first-turn / post-`clearHistory()`.
+     */
+    stepCount?: number;
     /**
      * The model's total context-window size in tokens. Read live at call
      * time from the agent's currently-bound `ModelConnectivityInfo.model`,
      * so it stays correct across `Agent.updateAgentConfig()` model swaps.
      */
     contextWindow: number;
+    /**
+     * The exact numerator behind {@link usedFraction}: the last step's effective
+     * input `(inputTokens ?? 0) + (cachedInputTokens ?? 0) + (cacheWriteInputTokens ?? 0)`.
+     * `undefined` under the same condition as `usedFraction` (all three
+     * input-bearing fields missing on the latest reading). Added in Phase 2
+     * (W-24125085) so occupancy reads identically to the completion log's three
+     * fields — `contextTokens` / `contextWindow` / `usedFraction`.
+     */
+    contextTokens: number | undefined;
     /**
      * `(usage.inputTokens + usage.cachedInputTokens + usage.cacheWriteInputTokens) /
      * contextWindow`, clamped to `[0, 1]`. The denominator-numerator includes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.75.0",
+  "version": "0.76.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.71.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.74.0",
-    "@salesforce/sfdx-agent-harness-openai": "0.40.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.72.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.75.0",
+    "@salesforce/sfdx-agent-harness-openai": "0.41.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.11",
     "@vitest/eslint-plugin": "^1.6.27",