@salesforce/sfdx-agent-sdk 0.73.0 → 0.75.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 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.75.0] - 2026-09-08
+
+_No changes — released alongside dependent packages._
+
+## [0.74.0] - 2026-09-08
+
+### Features
+- **agent-sdk**: self-describing usage fields on chat-stream-completed log @W-24125082@ ([#800](https://github.com/forcedotcom/agentic-dx/pull/800))
+
+### Chores
+- **deps-dev**: bump the dev-dependencies group with 3 updates ([#795](https://github.com/forcedotcom/agentic-dx/pull/795))
+
 ## [0.73.0] - 2026-09-04
 
 ### Features

package/dist/chat-session.d.ts

@@ -498,13 +498,18 @@ export declare class DefaultChatSession implements ChatSession {
      */
     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.
+     * Last-step usage + compact context-window occupancy for the
+     * `chat-stream-completed` log record: the last model step's full usage
+     * (`lastStepUsage`), the token amount that occupies the window
+     * (`contextTokens` — the last-step effective input), the window it is out of
+     * (`contextWindow`), and the occupancy ratio as a 0–1 float (`usedFraction`).
+     * `usedFraction` matches the SDK/service occupancy ratio exactly — the log no
+     * longer emits the redundant, lossy `contextUsedPercent` (a consumer wanting a
+     * percent computes `round(usedFraction * 100)`) (W-24125082, Phase 1). 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;
     /**

package/dist/chat-session.js

@@ -202,22 +202,36 @@ export class DefaultChatSession {
         let sawFinish = false;
         let lastError;
         let finishUsage;
+        // Count model steps in the turn so the completion log's `turnUsage`
+        // (the whole-turn aggregate) is interpretable next to `lastStepUsage`:
+        //   lastStepUsage.inputTokens ≤ turnUsage.inputTokens ≤ lastStepUsage.inputTokens × stepCount
+        // The lower bound is strict (<) only when stepCount > 1; a single-step
+        // turn's aggregate equals its one step. `stepCount` counts EVERY model
+        // step, including one whose `step-finish` reported undefined usage
+        // (W-22692131) — in that gap case `lastStepUsage` carries forward the last
+        // reporting step, so the upper bound just carries extra slack.
+        let stepCount = 0;
         try {
             for await (const event of stream) {
                 this.chatEventBus.emit(event);
                 this.deriveToolTelemetry(event);
                 yield event;
-                if (event.type === 'step-finish' && event.usage !== undefined) {
-                    // Snapshot the most recent per-step usage. Last-step semantics
-                    // (not the per-turn `finish.usage` aggregate) — `finish.usage`
-                    // sums every step inside the turn and double-counts persistent
-                    // context, which is the wrong denominator for "how full is my
-                    // context". An undefined usage on this step is intentionally
-                    // ignored so the prior reading is carried forward — gateway-side
-                    // gaps are rare but real (W-22692131) and clobbering with
-                    // undefined would surface as a transient hole consumers can't
-                    // distinguish from a fresh session.
-                    this.latestUsage = event.usage;
+                if (event.type === 'step-finish') {
+                    // Every step-finish is one model step; count it for the log's
+                    // `stepCount` regardless of whether this step reported usage.
+                    stepCount++;
+                    if (event.usage !== undefined) {
+                        // Snapshot the most recent per-step usage. Last-step semantics
+                        // (not the per-turn `finish.usage` aggregate) — `finish.usage`
+                        // sums every step inside the turn and double-counts persistent
+                        // context, which is the wrong denominator for "how full is my
+                        // context". An undefined usage on this step is intentionally
+                        // ignored so the prior reading is carried forward — gateway-side
+                        // gaps are rare but real (W-22692131) and clobbering with
+                        // undefined would surface as a transient hole consumers can't
+                        // distinguish from a fresh session.
+                        this.latestUsage = event.usage;
+                    }
                 }
                 if (event.type === 'finish') {
                     sawFinish = true;
@@ -304,13 +318,27 @@ 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.
+            // Fold the turn's usage + post-turn context-window occupancy onto the
+            // existing completion log so an operator can read both without
+            // subscribing to telemetry or adding a noisier log line. The two
+            // measurements carry self-describing names (W-24125082, Phase 1):
+            //   - `turnUsage` — the whole-turn aggregate (`finish.usage`), the
+            //     billing/throughput total; sums every step and can exceed the window.
+            //   - `lastStepUsage` + the occupancy fields — the last model step, the
+            //     right "how full is my context" reading (see contextUsageLogFields).
+            //   - `stepCount` — makes `turnUsage` interpretable next to `lastStepUsage`.
+            // The ambiguous `usage` field is intentionally NOT emitted (the log is the
+            // free, unshipped surface — no alias needed; carrying a third duplicate
+            // object would only bloat every record). Both blocks preserve today's
+            // omit-when-absent behavior: `turnUsage`/`stepCount` are omitted before any
+            // 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.
             this.logBus.emitLog({
                 level: 'info',
                 message: 'Chat stream completed',
@@ -319,7 +347,8 @@ export class DefaultChatSession {
                     agentId: this.agentId,
                     threadId: this.threadId,
                     durationMs,
-                    ...(finishUsage !== undefined ? { usage: finishUsage } : {}),
+                    ...(finishUsage !== undefined ? { turnUsage: finishUsage } : {}),
+                    ...(stepCount > 0 ? { stepCount } : {}),
                     ...this.contextUsageLogFields(),
                 },
             }, finishedAt);
@@ -466,13 +495,18 @@ export class DefaultChatSession {
         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.
+     * Last-step usage + compact context-window occupancy for the
+     * `chat-stream-completed` log record: the last model step's full usage
+     * (`lastStepUsage`), the token amount that occupies the window
+     * (`contextTokens` — the last-step effective input), the window it is out of
+     * (`contextWindow`), and the occupancy ratio as a 0–1 float (`usedFraction`).
+     * `usedFraction` matches the SDK/service occupancy ratio exactly — the log no
+     * longer emits the redundant, lossy `contextUsedPercent` (a consumer wanting a
+     * percent computes `round(usedFraction * 100)`) (W-24125082, Phase 1). 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();
@@ -480,9 +514,11 @@ export class DefaultChatSession {
             return {};
         const contextWindow = this.getContextWindow();
         return {
+            // Spread so a later `getContextUsage()` reader can't observe log-side mutation.
+            lastStepUsage: { ...this.latestUsage },
             contextTokens,
             contextWindow,
-            contextUsedPercent: Math.round(Math.min(1, Math.max(0, contextTokens / contextWindow)) * 100),
+            usedFraction: Math.min(1, Math.max(0, contextTokens / contextWindow)),
         };
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.73.0",
+  "version": "0.75.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.69.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.72.0",
-    "@salesforce/sfdx-agent-harness-openai": "0.38.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.71.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.74.0",
+    "@salesforce/sfdx-agent-harness-openai": "0.40.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.11",
     "@vitest/eslint-plugin": "^1.6.27",
@@ -60,12 +60,12 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-n": "^18.3.0",
     "globals": "^17.12.0",
-    "lint-staged": "^17.3.0",
+    "lint-staged": "^17.4.1",
     "prettier": "^3.9.6",
     "rimraf": "^6.1.3",
-    "tsx": "^4.23.12",
+    "tsx": "^4.23.13",
     "typescript": "^7.0.2",
-    "typescript-eslint": "^8.68.0",
+    "typescript-eslint": "^8.69.0",
     "vitest": "^4.1.11"
   },
   "engines": {