@salesforce/sfdx-agent-sdk 0.14.0 → 0.15.0

package/README.md

@@ -152,21 +152,22 @@ 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.                                          |
-| `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.                                       |
+| `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.                            |
 
 ### `ChatStreamResult`
 
@@ -193,23 +194,28 @@ Discriminated union (`event.type`) of streaming events:
 | `step-finish`           | `stepIndex`, `finishReason`, `usage?`                                                   | Step completed with per-step token usage.                                                                                                                                                                                                                                                                                        |
 | `error`                 | `error`, `code?`                                                                        | Mid-stream error (yielded, not thrown).                                                                                                                                                                                                                                                                                          |
 | `finish`                | `finishReason`, `usage?`                                                                | Stream completed with aggregate token usage.                                                                                                                                                                                                                                                                                     |
-| `unmapped-chunk`        | `chunkType`, `rawChunk`                                                                 | Unrecognized harness event, preserved for observability.                                                                                                                                                                                                                                                                         |
+
+> **Diagnostic logging.** The `ChatEvent` union is the harness-agnostic public stream — it never carries
+> harness-internal chunk shapes. When a harness encounters a chunk type its adapter does not recognize (typically after
+> an upstream Mastra / Claude SDK upgrade), the chunk is skipped on the public stream and surfaced via `LogBus.debug`
+> with `chunkType` and `rawChunk` in the record's `context`. Subscribe via `manager.onLog` (or `agent.onLog` /
+> `session.onLog`) at debug level to observe these. Production consumers do not need to filter for unrecognized chunks.
 
 ### Configuration Types
 
 #### `AgentConfig`
 
-| Field           | Type               | Description                                                                                                                                                                                                                                                                                                                          |
-| --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `orgAlias?`     | `string`           | Salesforce org alias or username. Falls back to project/default org.                                                                                                                                                                                                                                                                 |
-| `modelId?`      | `ModelName`        | LLM model identifier (e.g. `'llmgateway__OpenAIGPT5'`).                                                                                                                                                                                                                                                                              |
-| `name?`         | `string`           | Human-readable agent name.                                                                                                                                                                                                                                                                                                           |
-| `description?`  | `string`           | Agent purpose description.                                                                                                                                                                                                                                                                                                           |
-| `instructions?` | `string`           | System instructions for the agent.                                                                                                                                                                                                                                                                                                   |
-| `tools?`        | `ToolDefinition[]` | Consumer-executed tool schemas.                                                                                                                                                                                                                                                                                                      |
-| `mcpServers?`   | `MCPConfiguration` | MCP server connections.                                                                                                                                                                                                                                                                                                              |
-| `skills?`       | `string[]`         | Each entry is either an individual skill folder (containing `SKILL.md`) or a parent folder containing skill subfolders. Relative and absolute paths supported; forms can be mixed in the same array.                                                                                                                                 |
-| `rules?`        | `string[]`         | Each entry is either an individual `.md` rule file or a directory of `.md` rule files (scanned one level deep, alphabetical, non-`.md` skipped). Bodies are composed verbatim into the agent's effective system prompt; YAML frontmatter is optional and stripped if present. Matches Claude Code's `.claude/rules/*.md` convention. |
+| Field           | Type                 | Description                                                                                                                                                                                                                                                                                                                          |
+| --------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `orgAlias?`     | `string`             | Salesforce org alias or username. Falls back to project/default org.                                                                                                                                                                                                                                                                 |
+| `modelId?`      | `ModelName \| Model` | LLM model selector. Pass a `ModelName` enum value for an in-tree model (e.g. `'llmgateway__OpenAIGPT5'`), or a pre-built `Model` instance to opt into a Bedrock-Anthropic Claude variant the SDK has not yet released — see `createClaudeModel(gatewayId, overrides)` in `@salesforce/llm-gateway-sdk`.                              |
+| `name?`         | `string`             | Human-readable agent name.                                                                                                                                                                                                                                                                                                           |
+| `description?`  | `string`             | Agent purpose description.                                                                                                                                                                                                                                                                                                           |
+| `instructions?` | `string`             | System instructions for the agent.                                                                                                                                                                                                                                                                                                   |
+| `tools?`        | `ToolDefinition[]`   | Consumer-executed tool schemas.                                                                                                                                                                                                                                                                                                      |
+| `mcpServers?`   | `MCPConfiguration`   | MCP server connections.                                                                                                                                                                                                                                                                                                              |
+| `skills?`       | `string[]`           | Each entry is either an individual skill folder (containing `SKILL.md`) or a parent folder containing skill subfolders. Relative and absolute paths supported; forms can be mixed in the same array.                                                                                                                                 |
+| `rules?`        | `string[]`           | Each entry is either an individual `.md` rule file or a directory of `.md` rule files (scanned one level deep, alphabetical, non-`.md` skipped). Bodies are composed verbatim into the agent's effective system prompt; YAML frontmatter is optional and stripped if present. Matches Claude Code's `.claude/rules/*.md` convention. |
 
 #### `StreamOptions`
 
@@ -241,6 +247,12 @@ type MCPRemoteServerConfig = {
   headers?: Record<string, string>;
   enabled?: boolean;
   timeout?: number;
+  reconnectionOptions?: {
+    maxRetries?: number;
+    initialReconnectionDelay?: number;
+    maxReconnectionDelay?: number;
+    reconnectionDelayGrowFactor?: number;
+  };
   alwaysLoad?: boolean;
 };
 ```
@@ -252,6 +264,14 @@ surfaces (≤ a few tools the model needs to find without prompting). The Claude
 `_meta['anthropic/alwaysLoad'] = true` on each forwarded tool (equivalent to `defer_loading: false` on the Claude API).
 The Mastra harness eager-loads all MCP tools regardless, so the flag is a no-op there.
 
+**`reconnectionOptions`** tunes the HTTP MCP transport's retry / backoff behavior. Forwarded to the underlying SDK
+transport on both harnesses (Claude's `@modelcontextprotocol/sdk` `StreamableHTTPClientTransport` and Mastra's
+`@mastra/mcp` `HttpServerDefinition`, which is itself typed off the same MCP SDK shape). Each field is optional;
+unspecified fields fall back to the MCP SDK's built-in defaults — `maxRetries: 2`, `initialReconnectionDelay: 1000` ms,
+`maxReconnectionDelay: 30000` ms, `reconnectionDelayGrowFactor: 1.5`. Partial overrides are merged with those defaults
+at the harness boundary so a consumer setting only `maxRetries` doesn't zero out the others. No-op for stdio servers —
+only `MCPRemoteServerConfig` carries it.
+
 #### `McpServerInfo`
 
 | Field          | Type                                                                     | Description                                                                                                                               |
@@ -375,6 +395,13 @@ type ImagePart = { type: 'image'; mimeType: 'image/png' | 'image/jpeg'; data: st
 type FilePart = { type: 'file'; mimeType: 'application/pdf'; data: string; fileName?: string };
 ```
 
+`createdAt` is **required-on-read, optional-on-write**:
+
+- Messages returned from `ChatSession.getMessageHistory()` always have `createdAt` populated, and the array is sorted
+  ascending by `createdAt`. Consumer code can read `msg.createdAt` directly.
+- Consumers constructing `Message` literals for `ChatSession.addContext()` may omit `createdAt`; the SDK backfills the
+  current time before forwarding to the harness. Pass an explicit value to override.
+
 #### Multimodal input
 
 `ChatSession.chat()` (and the harness `stream()` it delegates to) accept either a plain string or a `MessagePart[]`. Use
@@ -409,7 +436,8 @@ await session.chat([
   },
 ]);
 
-// Inject multimodal context before a chat turn
+// Inject multimodal context before a chat turn. `createdAt` is omitted —
+// the SDK backfills it before forwarding to the harness.
 await session.addContext([
   {
     id: 'ctx-screenshot',
@@ -455,9 +483,52 @@ type UsageMetadata = {
   cacheWriteInputTokens?: number;
 };
 
+type ContextUsage = {
+  /**
+   * Last per-step usage reading observed on this session. Pre-first-turn and
+   * immediately after `clearHistory()` this is `{}` (every token field undefined).
+   */
+  usage: UsageMetadata;
+  /** 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.
+   */
+  usedFraction: number | undefined;
+};
+
 type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'other';
 ```
 
+**Tracking context-window utilization.** `ChatSession.getContextUsage()` always returns a populated `ContextUsage` —
+even pre-first-turn, where `usage` is `{}` and `usedFraction` is `undefined`, but `contextWindow` is always available.
+Use it to decide when to compact a thread:
+
+```typescript
+const ctx = session.getContextUsage();
+if (ctx.usedFraction !== undefined && ctx.usedFraction > 0.8) {
+  await agent.compactChatSession(session.getId());
+}
+```
+
+Render a context-usage indicator that distinguishes "no reading yet" from a real measurement:
+
+```typescript
+const ctx = session.getContextUsage();
+const limit = ctx.contextWindow.toLocaleString(); // always available
+const used = ctx.usage.inputTokens?.toLocaleString() ?? '—';
+const pct = ctx.usedFraction !== undefined ? `${Math.round(ctx.usedFraction * 100)}%` : '—';
+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.
+
 ### Error Handling
 
 The SDK throws `AgentSDKError` for predictable not-found and compatibility conditions. Each error has a `type` property
@@ -669,7 +740,11 @@ Returns `true` if the URL matches a Salesforce Hosted MCP Server endpoint (prod,
 
 ### Re-exported from `@salesforce/llm-gateway-sdk`
 
-- `ModelName` — enum of supported model identifiers
+- `Model` — abstract base class. Returned by `Models.getByName(...)` and accepted as an `AgentConfig.modelId` value.
+- `ModelName` — enum of in-tree model identifiers.
+- `createClaudeModel(gatewayId, overrides?)` — escape-hatch factory for opting into a Bedrock-Anthropic Claude variant
+  the SDK has not released yet (`AgentConfig.modelId` accepts the returned instance directly).
+- `ClaudeModelOverrides` — optional caps for `createClaudeModel`.
 - `SfApiEnv` — Salesforce API environment enum (`dev`, `perf`, `prod`, `stage`, `test`)
 - `inferSfApiEnv(instanceUrl, options?)` — maps an instance URL to a `SfApiEnv`. Re-exported from
   `@salesforce/agentic-common` for consumers that need the mapping without an `OrgConnection` (e.g. building a

package/dist/agent-connectivity-resolver.d.ts

@@ -1,4 +1,4 @@
-import { type JSONWebToken, type LLMGatewayClient, type LLMGatewayClientFactory } from '@salesforce/llm-gateway-sdk';
+import { Model, type JSONWebToken, type LLMGatewayClient, type LLMGatewayClientFactory } from '@salesforce/llm-gateway-sdk';
 import { type OrgConnection, type OrgConnectionFactory } from '@salesforce/agentic-common';
 import type { AgentConfig } from './harness/harness-config.js';
 /**
@@ -60,3 +60,18 @@ export declare class DefaultAgentConnectivityResolver implements AgentConnectivi
      */
     resolve(projectRoot: string, config: AgentConfig): Promise<ResolvedConnectivity>;
 }
+/**
+ * Resolves an `AgentConfig.modelId` value (which may be a {@link ModelName} enum value, a
+ * pre-built {@link Model} instance, or `undefined`) to a concrete {@link Model}.
+ *
+ * The enum branch goes through the strict {@link Models.getByName} registry; the live
+ * instance branch passes the consumer-built model through unchanged. A persisted-and-restored
+ * `Model` instance arrives here as a plain object (the JSON round-trip drops its prototype),
+ * and is rehydrated via {@link createClaudeModel} for Bedrock-Anthropic Claude variants — the
+ * single use case the consumer-built escape hatch was added for. Any other persisted shape is
+ * a programming error and throws.
+ *
+ * Exported for use by `Agent.updateAgentConfig`, which performs the same resolution when
+ * comparing previous and next models without re-running the full connectivity resolver.
+ */
+export declare function resolveAgentConfigModel(modelId: AgentConfig['modelId']): Model;

package/dist/agent-connectivity-resolver.js

@@ -2,7 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { DefaultLLMGatewayClientFactory, Models, createJWTFromConnection, } from '@salesforce/llm-gateway-sdk';
+import { DefaultLLMGatewayClientFactory, Model, ModelName, Models, createClaudeModel, createJWTFromConnection, } from '@salesforce/llm-gateway-sdk';
 import { SfApiEnv, RealOrgConnectionFactory, } from '@salesforce/agentic-common';
 // TODO(@W-22782317): Temporary workaround — only on prod orgs the LLM Gateway must
 // route requests through AgentforceVibes rather than the default VibesService. Remove once a
@@ -46,9 +46,60 @@ export class DefaultAgentConnectivityResolver {
         const featureId = env === SfApiEnv.Prod ? PROD_ORG_FEATURE_ID : undefined;
         const orgJwt = await createJWTFromConnection(orgConnection, { featureId });
         const llmGatewayClient = this.gatewayClientFactory.create(orgJwt, { env });
-        const modelName = config.modelId ?? Models.getDefault().name;
-        llmGatewayClient.setModel(Models.getByName(modelName));
+        llmGatewayClient.setModel(resolveAgentConfigModel(config.modelId));
         return { llmGatewayClient, orgConnection, orgJwt };
     }
 }
+/**
+ * Resolves an `AgentConfig.modelId` value (which may be a {@link ModelName} enum value, a
+ * pre-built {@link Model} instance, or `undefined`) to a concrete {@link Model}.
+ *
+ * The enum branch goes through the strict {@link Models.getByName} registry; the live
+ * instance branch passes the consumer-built model through unchanged. A persisted-and-restored
+ * `Model` instance arrives here as a plain object (the JSON round-trip drops its prototype),
+ * and is rehydrated via {@link createClaudeModel} for Bedrock-Anthropic Claude variants — the
+ * single use case the consumer-built escape hatch was added for. Any other persisted shape is
+ * a programming error and throws.
+ *
+ * Exported for use by `Agent.updateAgentConfig`, which performs the same resolution when
+ * comparing previous and next models without re-running the full connectivity resolver.
+ */
+export function resolveAgentConfigModel(modelId) {
+    if (modelId === undefined)
+        return Models.getDefault();
+    // Known limitation: `instanceof Model` is realm-scoped — a consumer that ends up with two copies
+    // of `@salesforce/llm-gateway-sdk` resolved in their dependency tree will have their `Model`
+    // instance fail this check and fall through to `rehydratePersistedModel`. That branch handles
+    // it correctly for Claude variants but throws for anything else. The duplicate-package case is
+    // a packaging bug at the consumer; we don't paper over it here.
+    if (modelId instanceof Model)
+        return modelId;
+    if (typeof modelId === 'string')
+        return Models.getByName(modelId);
+    return rehydratePersistedModel(modelId);
+}
+function rehydratePersistedModel(persisted) {
+    const obj = persisted;
+    if (typeof obj.name !== 'string') {
+        throw new Error(`Cannot resolve modelId: missing string "name" on persisted object.`);
+    }
+    // If the persisted name matches an in-tree model, prefer the strict registry — the
+    // returned instance has the correct prototype and the canonical caps.
+    if (Object.values(ModelName).includes(obj.name)) {
+        return Models.getByName(obj.name);
+    }
+    if (!obj.name.startsWith('llmgateway__BedrockAnthropic')) {
+        throw new Error(`Cannot rehydrate persisted model "${obj.name}". Only Bedrock-Anthropic Claude variants are supported via the consumer-built Model escape hatch.`);
+    }
+    return createClaudeModel(obj.name, {
+        displayId: obj.displayId,
+        maxInputTokens: obj.maxInputTokens,
+        maxOutputTokens: obj.maxOutputTokens,
+        contextWindow: obj.contextWindow,
+        supportsPromptCache: obj.supportsPromptCache,
+        supportedFormats: obj.supportedFormats,
+        permittedParameters: obj.permittedParameters,
+        customHeaders: obj.customHeaders,
+    });
+}
 //# sourceMappingURL=agent-connectivity-resolver.js.map

package/dist/agent.d.ts

@@ -4,7 +4,7 @@ import { type AgentConfig } from './harness/harness-config.js';
 import { type ChatSession } from './chat-session.js';
 import type { McpServerInfo } from './mcp-config.js';
 import { type JSONWebToken, type LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
-import type { AgentConnectivityResolver } from './agent-connectivity-resolver.js';
+import { type AgentConnectivityResolver } from './agent-connectivity-resolver.js';
 import type { AgentIdentityStore } from './internal/agent-identity-store.js';
 import type { TelemetryRouter, TelemetrySlice } from './internal/telemetry-router.js';
 import type { TelemetryBus, TelemetryEventCallback } from './types/telemetry-events.js';

package/dist/agent.js

@@ -5,7 +5,8 @@
 import { EventBus, LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
 import { toHarnessConfig } from './harness/harness-config.js';
 import { DefaultChatSession } from './chat-session.js';
-import { Models } from '@salesforce/llm-gateway-sdk';
+import {} from '@salesforce/llm-gateway-sdk';
+import { resolveAgentConfigModel } from './agent-connectivity-resolver.js';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
 /**
  * Default implementation of {@link Agent} that delegates
@@ -112,8 +113,8 @@ export class DefaultAgent {
         const previousOrgJwt = this.orgJwt;
         const nextConfig = { ...this.config, ...config };
         const orgAliasRequested = Object.prototype.hasOwnProperty.call(config, 'orgAlias');
-        const previousModelName = previousClient.getModel().name;
-        const nextModelName = nextConfig.modelId ?? Models.getDefault().name;
+        const previousModel = previousClient.getModel();
+        const nextModel = resolveAgentConfigModel(nextConfig.modelId);
         let nextClient = previousClient;
         let nextConnection = this.orgConnection;
         let nextOrgJwt = this.orgJwt;
@@ -123,14 +124,16 @@ export class DefaultAgent {
             nextConnection = runtime.orgConnection;
             nextOrgJwt = runtime.orgJwt;
         }
-        else if (nextModelName !== previousModelName) {
+        else if (nextModel.name !== previousModel.name) {
             // Keep the same authenticated client, but pin the updated model.
             // (If modelId is omitted, the resolver pinned the default at creation time.)
-            nextClient.setModel(Models.getByName(nextModelName));
+            nextClient.setModel(nextModel);
         }
         await this.harness.destroyAgent(this.agentId);
+        let nextConfigRegistered = false;
         try {
             await this.harness.createAgent(this.agentId, this.projectRoot, nextClient, toHarnessConfig(nextConfig, nextOrgJwt), options);
+            nextConfigRegistered = true;
             // Persist before the in-memory swaps so a write failure flows through the same
             // catch block as a recreate failure: the rollback restores the harness with
             // previousConfig and disk state remains the pre-update record.
@@ -148,16 +151,21 @@ export class DefaultAgent {
         catch (error) {
             // Best-effort restoration to keep wrapper and harness state aligned.
             try {
-                // Restore client model if we mutated it in-place.
+                // Restore client model if we mutated it in-place. We re-pin the live previousModel
+                // instance (captured above as previousClient.getModel()) rather than re-resolving from
+                // this.config.modelId, because a JSON-rehydrated config may have a plain object there
+                // that would round-trip through createClaudeModel and lose the original prototype.
                 if (nextClient === previousClient) {
-                    previousClient.setModel(Models.getByName(previousModelName));
+                    previousClient.setModel(previousModel);
+                }
+                // Clear nextConfig registration only when the harness recreate
+                // actually succeeded (identityStore.write-failure path) — the
+                // harness throws on unknown id, so calling destroyAgent on the
+                // harness-recreate-failure path would short-circuit the rollback
+                // createAgent below.
+                if (nextConfigRegistered) {
+                    await this.harness.destroyAgent(this.agentId);
                 }
-                // Clear any nextConfig registration left behind by a successful harness recreate
-                // before the rollback createAgent runs. On the harness-recreate-failure path this
-                // is a no-op (the agent was never registered with nextConfig); on the
-                // identityStore.write-failure path it removes the live nextConfig so the rollback
-                // doesn't trip the harness's duplicate-registration guard.
-                await this.harness.destroyAgent(this.agentId);
                 await this.harness.createAgent(this.agentId, this.projectRoot, previousClient, toHarnessConfig(previousConfig, previousOrgJwt));
             }
             catch {
@@ -319,10 +327,18 @@ export class DefaultAgent {
     }
     attachSession(threadId) {
         const slice = this.router.registerSession(threadId);
+        // Live getter — read at call time so getContextUsage() reflects the
+        // model bound to the agent right now, not the model that was bound
+        // when this session was created. updateAgentConfig() can swap the
+        // underlying LLMGatewayClient mid-life. Per the SDK's Critical
+        // Invariant on context-window reachability, every bound model
+        // exposes a usable `contextWindow`; #507's decoupling work must
+        // preserve that, so this access is contractually safe.
+        const getContextWindow = () => this.llmGatewayClient.getModel().contextWindow;
         const session = new DefaultChatSession(this.harness, this.agentId, threadId, slice, {
             telemetry: this.telemetryBus,
             log: this.logBus,
-        }, this.clock, this.idGenerator);
+        }, getContextWindow, this.clock, this.idGenerator);
         this.sessions.set(threadId, session);
         this.sessionSliceUnregisters.set(threadId, () => this.router.unregisterSession(threadId));
         this.telemetryBus.emit({

package/dist/chat-session.d.ts

@@ -6,6 +6,7 @@ import type { ChatEvent, ChatStreamResult } from './types/events.js';
 import type { Message, MessagePart } from './types/messages.js';
 import type { TelemetryBus, TelemetryEventCallback } from './types/telemetry-events.js';
 import type { ToolResultInfo } from './types/tools.js';
+import type { ContextUsage } from './types/usage.js';
 /**
  * Options for a single chat interaction.
  */
@@ -123,6 +124,25 @@ export interface ChatSession {
     getMessageHistory(): Promise<Message[]>;
     /** Delete all messages in this session's history. */
     clearHistory(): Promise<void>;
+    /**
+     * 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.
+     *
+     * `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.
+     *
+     * The `contextWindow` is read live from the agent's currently-bound
+     * model, so it reflects any `Agent.updateAgentConfig()` model swap
+     * that happened between turns.
+     */
+    getContextUsage(): ContextUsage;
     /**
      * Inject context messages into the thread without triggering an LLM response.
      * Useful for seeding file contents, system instructions, or prior conversation
@@ -176,6 +196,23 @@ export declare class DefaultChatSession implements ChatSession {
      * are stale and should not bleed into the next turn).
      */
     private readonly toolStartMs;
+    /**
+     * Live getter for the agent's currently-bound model's context window.
+     * Called by {@link getContextUsage} so reads reflect the model in
+     * effect right now, not the model bound when this session was created
+     * (an `Agent.updateAgentConfig()` swap can change it mid-life).
+     */
+    private readonly getContextWindow;
+    /**
+     * Last per-step usage reading observed on this session. Initialized
+     * to `{}` (every token field undefined) so {@link getContextUsage}
+     * can always return a populated `ContextUsage`. Updated on every
+     * `step-finish` ChatEvent whose `usage` is defined; an undefined
+     * usage is carried forward (defense against rare gateway-side gaps —
+     * see W-22692131). Reset to `{}` on `clearHistory()` so a fresh
+     * thread starts unprimed.
+     */
+    private latestUsage;
     private disposed;
     /**
      * @param harness - The agent harness managing thread and message lifecycle.
@@ -183,10 +220,12 @@ export declare class DefaultChatSession implements ChatSession {
      * @param threadId - ID of the conversation thread backing this session.
      * @param inbound - Router slice delivering harness events routed to this session.
      * @param parent - Parent agent's buses; this session forwards its events upward into them.
+     * @param getContextWindow - Live getter for the agent's currently-bound model's `contextWindow`.
+     *   Called by `getContextUsage()` so reads stay correct across `Agent.updateAgentConfig()` model swaps.
      * @param clock - Source of monotonic timestamps for telemetry events. Defaults to `RealClock`.
      * @param idGenerator - Source of message ids for `addContext()`. Defaults to `UUIDGenerator`.
      */
-    constructor(harness: AgentHarness, agentId: string, threadId: string, inbound: TelemetrySlice, parent: ChatSessionParentBuses, clock?: Clock, idGenerator?: UniqueIDGenerator);
+    constructor(harness: AgentHarness, agentId: string, threadId: string, inbound: TelemetrySlice, parent: ChatSessionParentBuses, getContextWindow: () => number, clock?: Clock, idGenerator?: UniqueIDGenerator);
     getId(): string;
     /**
      * @requirements
@@ -273,8 +312,34 @@ 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.
      */
     clearHistory(): Promise<void>;
+    /**
+     * @requirements
+     * - MUST always return a populated `ContextUsage`. Pre-first-turn and post-`clearHistory()`,
+     *   `usage` is `{}` and `usedFraction` is `undefined`, but `contextWindow` is always
+     *   populated from the agent's currently-bound model.
+     * - MUST read `contextWindow` via the constructor-injected `getContextWindow` getter
+     *   so swaps via `Agent.updateAgentConfig()` are reflected on the next call. Per the
+     *   SDK's Critical Invariant on context-window reachability, every bound model exposes
+     *   a usable `contextWindow`; the getter does not need a defensive try/catch.
+     * - MUST compute `usedFraction = (inputTokens + cachedInputTokens + cacheWriteInputTokens) /
+     *   contextWindow`, clamped to `[0, 1]`. The denominator-numerator must include cached
+     *   tokens because Bedrock-Claude's `message_delta.usage` reports only the *incremental*
+     *   `input_tokens` per delta — the bulk of the prompt rides on `cache_read_input_tokens`
+     *   / `cache_creation_input_tokens` which the Claude adapter surfaces as
+     *   `cachedInputTokens` / `cacheWriteInputTokens`. Those are real tokens the model
+     *   actually loaded into its context window (Bedrock charges for them and counts them
+     *   against the window), so they belong in the "how full" denominator. Mastra is
+     *   unaffected — it doesn't populate the cache fields, so the sum collapses to
+     *   `inputTokens` alone.
+     * - MUST treat `usedFraction` as `undefined` when ALL three input-bearing fields are
+     *   undefined — pre-first-turn, post-`clearHistory()`, or a harness reading with no
+     *   input-side counts at all.
+     */
+    getContextUsage(): ContextUsage;
     /**
      * @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

@@ -2,7 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { EventBus, LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
+import { backfillCreatedAt, EventBus, LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
 /**
  * Default implementation of {@link ChatSession} that delegates all operations
@@ -31,6 +31,23 @@ export class DefaultChatSession {
      * are stale and should not bleed into the next turn).
      */
     toolStartMs = new Map();
+    /**
+     * Live getter for the agent's currently-bound model's context window.
+     * Called by {@link getContextUsage} so reads reflect the model in
+     * effect right now, not the model bound when this session was created
+     * (an `Agent.updateAgentConfig()` swap can change it mid-life).
+     */
+    getContextWindow;
+    /**
+     * Last per-step usage reading observed on this session. Initialized
+     * to `{}` (every token field undefined) so {@link getContextUsage}
+     * can always return a populated `ContextUsage`. Updated on every
+     * `step-finish` ChatEvent whose `usage` is defined; an undefined
+     * usage is carried forward (defense against rare gateway-side gaps —
+     * see W-22692131). Reset to `{}` on `clearHistory()` so a fresh
+     * thread starts unprimed.
+     */
+    latestUsage = {};
     disposed = false;
     /**
      * @param harness - The agent harness managing thread and message lifecycle.
@@ -38,13 +55,16 @@ export class DefaultChatSession {
      * @param threadId - ID of the conversation thread backing this session.
      * @param inbound - Router slice delivering harness events routed to this session.
      * @param parent - Parent agent's buses; this session forwards its events upward into them.
+     * @param getContextWindow - Live getter for the agent's currently-bound model's `contextWindow`.
+     *   Called by `getContextUsage()` so reads stay correct across `Agent.updateAgentConfig()` model swaps.
      * @param clock - Source of monotonic timestamps for telemetry events. Defaults to `RealClock`.
      * @param idGenerator - Source of message ids for `addContext()`. Defaults to `UUIDGenerator`.
      */
-    constructor(harness, agentId, threadId, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
+    constructor(harness, agentId, threadId, inbound, parent, getContextWindow, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
         this.harness = harness;
         this.agentId = agentId;
         this.threadId = threadId;
+        this.getContextWindow = getContextWindow;
         this.clock = clock;
         this.idGenerator = idGenerator;
         this.inboundUnsubs = [inbound.telemetry.forwardTo(this.telemetryBus), inbound.log.forwardTo(this.logBus)];
@@ -138,6 +158,18 @@ export class DefaultChatSession {
                 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 === 'finish') {
                     sawFinish = true;
                     finishUsage = event.usage;
@@ -267,10 +299,53 @@ 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.
      */
     async clearHistory() {
         this.assertNotDisposed();
         await this.harness.clearMessages(this.agentId, this.threadId);
+        this.latestUsage = {};
+    }
+    /**
+     * @requirements
+     * - MUST always return a populated `ContextUsage`. Pre-first-turn and post-`clearHistory()`,
+     *   `usage` is `{}` and `usedFraction` is `undefined`, but `contextWindow` is always
+     *   populated from the agent's currently-bound model.
+     * - MUST read `contextWindow` via the constructor-injected `getContextWindow` getter
+     *   so swaps via `Agent.updateAgentConfig()` are reflected on the next call. Per the
+     *   SDK's Critical Invariant on context-window reachability, every bound model exposes
+     *   a usable `contextWindow`; the getter does not need a defensive try/catch.
+     * - MUST compute `usedFraction = (inputTokens + cachedInputTokens + cacheWriteInputTokens) /
+     *   contextWindow`, clamped to `[0, 1]`. The denominator-numerator must include cached
+     *   tokens because Bedrock-Claude's `message_delta.usage` reports only the *incremental*
+     *   `input_tokens` per delta — the bulk of the prompt rides on `cache_read_input_tokens`
+     *   / `cache_creation_input_tokens` which the Claude adapter surfaces as
+     *   `cachedInputTokens` / `cacheWriteInputTokens`. Those are real tokens the model
+     *   actually loaded into its context window (Bedrock charges for them and counts them
+     *   against the window), so they belong in the "how full" denominator. Mastra is
+     *   unaffected — it doesn't populate the cache fields, so the sum collapses to
+     *   `inputTokens` alone.
+     * - MUST treat `usedFraction` as `undefined` when ALL three input-bearing fields are
+     *   undefined — pre-first-turn, post-`clearHistory()`, or a harness reading with no
+     *   input-side counts at all.
+     */
+    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 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 };
     }
     /**
      * @requirements
@@ -292,7 +367,15 @@ export class DefaultChatSession {
                     createdAt: this.clock.now(),
                 },
             ]
-            : message;
+            : // `Message.createdAt` is required-on-read, optional-on-write —
+                // the SDK owns the backfill so harnesses see populated
+                // timestamps regardless of consumer-construction style. The
+                // shared `backfillCreatedAt` helper steps per-position via
+                // `clock.nextAfter` so a bulk insert produces strictly-
+                // ascending values. The two production harnesses share the
+                // same helper at their own `addContext` boundary so a
+                // direct `harness.addContext` call gets the same shape.
+                backfillCreatedAt(message, this.clock);
         await this.harness.addContext(this.agentId, this.threadId, messages);
     }
     /**

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

@@ -112,7 +112,14 @@ export interface AgentHarness {
     }): Promise<void>;
     /**
      * Destroy an agent and release its resources (MCP connections, workspace, memory).
+     *
+     * MUST throw if `agentId` is not registered. Symmetric with `createThread`,
+     * `destroyThread`, and `clearMessages`, which all reject unknown ids the
+     * same way; gives SDK rollback paths in `Agent.updateAgentConfig` and
+     * `AgentManager.installAgent` an explicit failure mode they can catch.
+     *
      * @param agentId - ID of the agent to destroy.
+     * @returns `true` after a real removal.
      */
     destroyAgent(agentId: string): Promise<boolean>;
     /**
@@ -124,8 +131,11 @@ export interface AgentHarness {
      * including connection status and discovered tool names. This is a synchronous
      * snapshot — status is updated asynchronously by background discovery promises.
      *
+     * MUST throw if `agentId` is not registered.
+     *
      * @param agentId - ID of the agent whose MCP servers to inspect.
-     * @returns Info for each configured MCP server (empty array if none configured).
+     * @returns Info for each configured MCP server (empty array if the agent
+     *   exists but has no MCP servers configured).
      */
     getMcpServerInfo(agentId: string): McpServerInfo[];
     /**
@@ -175,14 +185,31 @@ export interface AgentHarness {
      */
     getThreadIds(agentId: string): Promise<string[]>;
     /**
-     * Clone an existing thread, creating a new thread with copied message history.
-     * Used to implement conversation forking.
+     * Clone an existing thread, creating a new thread that mirrors the source
+     * thread's state at the moment of the call. Used to implement conversation
+     * forking.
+     *
+     * The harness chooses the new thread's id; consumers read it from the
+     * returned value. The id is unique within the agent.
+     *
+     * Two source-state shapes are observable to consumers:
+     *
+     * - **Source thread has been streamed at least once** — the new thread
+     *   inherits the source's persisted message history; subsequent
+     *   `getMessages()` returns it. Implementations may copy the underlying
+     *   transcript (Mastra's libsql `cloneThread`, Claude's `forkSession`)
+     *   or any harness-specific equivalent.
+     * - **Source thread has never been streamed** (`addContext`-only or
+     *   freshly-created) — the new thread is allocated empty by design;
+     *   `addContext`-injected messages on the source are copied forward by
+     *   harnesses that mirror them in-process, but no persisted transcript
+     *   exists to fork.
+     *
      * @param agentId - ID of the owning agent.
      * @param sourceThreadId - ID of the thread to clone.
-     * @param targetThreadId - Optional ID for the new thread.
      * @returns The ID of the cloned thread.
      */
-    cloneThread(agentId: string, sourceThreadId: string, targetThreadId?: string): Promise<string>;
+    cloneThread(agentId: string, sourceThreadId: string): Promise<string>;
     /**
      * Compacts a thread's message history to reduce context window usage.
      * Starts a new conversation thread seeded with an LLM-generated summary of the current session.
@@ -257,9 +284,12 @@ export interface AgentHarness {
     /**
      * Retrieve message history for a thread.
      *
+     * MUST populate `Message.createdAt` on every returned message. MUST return
+     * messages sorted ascending by `createdAt`.
+     *
      * @param agentId - ID of the agent.
      * @param threadId - ID of the conversation thread.
-     * @returns All messages in chronological order (ascending by creation time).
+     * @returns All messages in chronological order (ascending by `createdAt`).
      */
     getMessages(agentId: string, threadId: string): Promise<Message[]>;
     /**

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

@@ -1,6 +1,6 @@
 import type { ToolDefinition } from '../types/tools.js';
 import type { MCPConfiguration } from '../mcp-config.js';
-import type { JSONWebToken, ModelName } from '@salesforce/llm-gateway-sdk';
+import type { JSONWebToken, Model, ModelName } from '@salesforce/llm-gateway-sdk';
 /**
  * Configuration for an agent's behavior and capabilities.
  * This excludes identity; `agentId` is handled separately.
@@ -14,8 +14,15 @@ export type AgentConfig = {
      * - Otherwise, use the default org configured on the machine.
      */
     orgAlias?: string;
-    /** The model to use for this agent. */
-    modelId?: ModelName;
+    /**
+     * The model to use for this agent.
+     *
+     * Accepts either a {@link ModelName} enum value (the typical case for in-tree models) or a
+     * pre-built {@link Model} instance. The instance form lets consumers opt into a Claude
+     * variant published on the gateway before the SDK has been updated — see
+     * `createClaudeModel(gatewayId, overrides)` from `@salesforce/llm-gateway-sdk`.
+     */
+    modelId?: ModelName | Model;
     /** Human-readable name for the agent. */
     name?: string;
     /** Description of the agent's purpose. ACP/OASF-ready metadata. */

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 export type { Message, MessagePart, ImagePart, FilePart } from './types/messages.js';
 export type { ChatEvent, StartEvent, TextDeltaEvent, ReasoningDeltaEvent, ToolCallEvent, ToolApprovalRequestEvent, ToolResultEvent, StepStartEvent, StepFinishEvent, ErrorEvent, FinishEvent, ChatStreamResult, } from './types/events.js';
 export type { ToolDefinition, ToolCallInfo, ToolResultInfo } from './types/tools.js';
-export type { FinishReason, UsageMetadata } from './types/usage.js';
+export type { ContextUsage, FinishReason, UsageMetadata } from './types/usage.js';
 export type { AgentConfig, HarnessAgentConfig, StreamOptions, ToolApprovalMode } from './harness/harness-config.js';
 export { DEFAULT_MAX_STEPS, resolveToolApprovalMode } from './harness/harness-config.js';
 export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpServerInfo, McpServerErrorCategory, McpServerErrorDetail, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
 export { McpServerStatus } from './mcp-config.js';
-export { ModelName } from '@salesforce/llm-gateway-sdk';
+export { Model, ModelName, createClaudeModel } from '@salesforce/llm-gateway-sdk';
+export type { ClaudeModelOverrides } from '@salesforce/llm-gateway-sdk';
 export { inferSfApiEnv, SfApiEnv } from '@salesforce/agentic-common';
 export { type AgentManager, type RestoreFailure, createAgentManager } from './agent-manager.js';
 export { type Agent } from './agent.js';

package/dist/index.js

@@ -4,7 +4,7 @@
  */
 export { DEFAULT_MAX_STEPS, resolveToolApprovalMode } from './harness/harness-config.js';
 export { McpServerStatus } from './mcp-config.js';
-export { ModelName } from '@salesforce/llm-gateway-sdk';
+export { Model, ModelName, createClaudeModel } from '@salesforce/llm-gateway-sdk';
 export { inferSfApiEnv, SfApiEnv } from '@salesforce/agentic-common';
 // ── Agent Layer ─────────────────────────────────────────────────────
 export { createAgentManager } from './agent-manager.js';

package/dist/mcp-config.d.ts

@@ -65,6 +65,32 @@ export type MCPRemoteServerConfig = {
     enabled?: boolean;
     /** Timeout in milliseconds for individual requests to the server. */
     timeout?: number;
+    /**
+     * Transport-level reconnection tuning for HTTP MCP servers. Forwarded to
+     * the underlying SDK transport (`@modelcontextprotocol/sdk`'s
+     * `StreamableHTTPClientTransport` on the Claude harness, and the
+     * equivalent plumb-through on `@mastra/mcp`'s `HttpServerDefinition`).
+     *
+     * Each field is optional. The harness mappers merge unspecified fields
+     * with the MCP SDK's built-in defaults (`maxRetries: 2`,
+     * `initialReconnectionDelay: 1000`, `maxReconnectionDelay: 30000`,
+     * `reconnectionDelayGrowFactor: 1.5`) so a partial override leaves the
+     * other fields at their defaults rather than zeroing them out — the
+     * underlying transport replaces the entire defaults object when
+     * `reconnectionOptions` is set.
+     *
+     * No-op for stdio servers — only `MCPRemoteServerConfig` carries it.
+     */
+    reconnectionOptions?: {
+        /** Maximum number of reconnection attempts before giving up. Default `2`. */
+        maxRetries?: number;
+        /** Initial backoff between reconnection attempts in milliseconds. Default `1000`. */
+        initialReconnectionDelay?: number;
+        /** Maximum backoff between reconnection attempts in milliseconds. Default `30000`. */
+        maxReconnectionDelay?: number;
+        /** Factor by which the reconnection delay grows after each attempt. Default `1.5`. */
+        reconnectionDelayGrowFactor?: number;
+    };
     /**
      * Opt the server's tool surface out of the active runtime's tool-search
      * deferral. See {@link MCPStdioServerConfig.alwaysLoad}.

package/dist/types/events.d.ts

@@ -8,7 +8,7 @@ import type { FinishReason, UsageMetadata } from './usage.js';
  * convention, with the addition of `tool-approval-request` for human-in-the-loop
  * tool approval flows.
  */
-export type ChatEvent = StartEvent | TextDeltaEvent | ReasoningDeltaEvent | ToolCallEvent | ToolApprovalRequestEvent | ToolResultEvent | StepStartEvent | StepFinishEvent | ErrorEvent | FinishEvent | UnmappedChunkEvent;
+export type ChatEvent = StartEvent | TextDeltaEvent | ReasoningDeltaEvent | ToolCallEvent | ToolApprovalRequestEvent | ToolResultEvent | StepStartEvent | StepFinishEvent | ErrorEvent | FinishEvent;
 /**
  * The stream has begun. Symmetric counterpart to {@link FinishEvent}.
  *
@@ -155,19 +155,6 @@ export type ErrorEvent = {
     /** Machine-readable error code (e.g., `'insufficient-tokens'`). */
     code?: string;
 };
-/**
- * A stream chunk from the underlying harness that has no `ChatEvent` counterpart.
- *
- * Returned instead of silently discarding the chunk, so consumers can log or
- * monitor unhandled harness events for observability.
- */
-export type UnmappedChunkEvent = {
-    type: 'unmapped-chunk';
-    /** The original harness chunk type string (e.g., `'tool-call-suspended'`, `'raw'`). */
-    chunkType: string;
-    /** The raw chunk object, preserved for diagnostic logging. */
-    rawChunk: unknown;
-};
 /** The entire stream has completed. */
 export type FinishEvent = {
     type: 'finish';

package/dist/types/messages.d.ts

@@ -24,7 +24,18 @@ export type Message = {
     role: MessageRole;
     /** Message content — plain text or structured parts. */
     content: string | MessagePart[];
-    /** Optional timestamp of when the message was created. */
+    /**
+     * Timestamp of when the message was created. **Always populated** on
+     * messages returned from `ChatSession.getMessageHistory()`. **Optional on
+     * write** — consumers constructing `Message` for `ChatSession.addContext()`
+     * may omit it; the SDK backfills the current time before forwarding to
+     * the harness, so the on-read contract still holds.
+     *
+     * The read-side guarantee lives on `AgentHarness.getMessages` — see its
+     * JSDoc for the contract every harness implementation upholds (populated
+     * `createdAt` on every returned message; array sorted ascending by
+     * `createdAt`). The SDK passes the harness's output through unchanged.
+     */
     createdAt?: Date;
 };
 /**

package/dist/types/usage.d.ts

@@ -16,6 +16,71 @@ export type UsageMetadata = {
     /** Input tokens written to the provider cache during this interaction. */
     cacheWriteInputTokens?: number;
 };
+/**
+ * Snapshot of how much of the model's context window the most recent
+ * turn used. Returned by {@link ChatSession.getContextUsage}.
+ *
+ * Consumers use this to decide when to call `compactThread()`, switch to a
+ * 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.
+ *
+ * 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."
+ * - `contextWindow` is always populated, contractually. Every `Model`
+ *   reachable via `Agent.llmGatewayClient.getModel()` must publish a
+ *   `contextWindow`; see the `sfdx-agent-sdk` ARCHITECTURE.md Critical
+ *   Invariant on this and issue #507.
+ * - `usedFraction` is `undefined` iff every input-bearing field on the
+ *   latest reading (`inputTokens`, `cachedInputTokens`, `cacheWriteInputTokens`)
+ *   is `undefined` — the only honest answer when we have no input-side
+ *   reading to divide. The denominator-numerator sums all three because
+ *   cached prompt tokens occupy real space in the context window (see the
+ *   field-level doc on `usedFraction` for the Bedrock-Claude rationale).
+ *   Consumers who want zero-on-empty UX can collapse with `usedFraction ?? 0`.
+ */
+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).
+     */
+    usage: UsageMetadata;
+    /**
+     * The model's total context-window size in tokens. Read live at call
+     * time from the agent's currently-bound `LLMGatewayClient`, so it stays
+     * correct across `Agent.updateAgentConfig()` model swaps.
+     */
+    contextWindow: number;
+    /**
+     * `(usage.inputTokens + usage.cachedInputTokens + usage.cacheWriteInputTokens) /
+     * contextWindow`, clamped to `[0, 1]`. The denominator-numerator includes
+     * cached prompt tokens because they are real tokens occupying the model's
+     * context window — Bedrock-Claude's `message_delta.usage` reports only the
+     * incremental `inputTokens` per delta, with the bulk of the prompt riding
+     * on `cachedInputTokens` / `cacheWriteInputTokens`. Counting only
+     * `inputTokens` would underreport "how full" by orders of magnitude on
+     * cache-hit paths. Mastra is unaffected because it does not populate the
+     * cache fields, so the sum collapses to `inputTokens` alone.
+     *
+     * `undefined` when ALL three input-bearing fields are missing on the
+     * latest reading (pre-first-turn, post-`clearHistory()`, or when a
+     * harness emits a reading without any input-side counts). Consumers
+     * wanting zero-on-empty: `usedFraction ?? 0`.
+     */
+    usedFraction: number | undefined;
+};
 /**
  * Reason the model stopped generating.
  * Aligned with AI SDK V3's unified finish-reason set; harnesses normalize provider-specific

package/package.json

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