@salesforce/sfdx-agent-sdk 0.14.0 → 0.16.0

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.
@@ -211,55 +238,65 @@ export interface AgentHarness {
     stream(agentId: string, threadId: string, message: string | MessagePart[], options?: StreamOptions): Promise<ChatStreamResult>;
     /**
      * Feed the result of a **consumer-executed (client-side) tool** back into the
-     * conversation and resume stream generation. Implements the consumer-facing
+     * conversation. Implements the consumer-facing
      * {@link ChatSession.submitToolResult} contract: see that JSDoc for the
      * full consumer-level semantics.
      *
      * Called only for tools declared in {@link HarnessAgentConfig.tools} (no
      * `execute` function). Tools provided via `mcpServers` are executed by the
-     * harness directly and never reach this method. The harness resumes the
-     * suspended agentic loop from the most recent `stream()` call on the given
-     * thread, feeds `toolResult` into the loop, and returns a continuation
-     * stream the consumer iterates for the model's next turn.
+     * harness directly and never reach this method.
+     *
+     * Returns `Promise<void>` once the harness has accepted the tool result
+     * (the parked bridge handler resolved). Post-resume events
+     * (`tool-result`, model follow-up text, terminal `finish`) flow through
+     * the SAME `ChatStreamResult.eventStream` returned by the most recent
+     * {@link stream} call on the thread — the consumer is still iterating
+     * that stream and sees the events arrive.
      *
      * @param agentId - ID of the agent.
      * @param threadId - ID of the conversation thread.
      * @param toolResult - The completed tool execution result; `toolCallId`
      *   matches the id from the originating `tool-call` event.
      */
-    submitToolResult(agentId: string, threadId: string, toolResult: ToolResultInfo): Promise<ChatStreamResult>;
+    submitToolResult(agentId: string, threadId: string, toolResult: ToolResultInfo): Promise<void>;
     /**
      * Approve a pending tool call, allowing the harness to execute it.
      * Called after receiving a `tool-approval-request` event.
      *
-     * Returns a `ChatStreamResult` containing the continuation stream — the harness
-     * executes the approved tool, generates the model's follow-up response, and
-     * streams both the text and events back to the caller.
+     * Returns `Promise<void>` once the harness has accepted the approval
+     * (the parked PreToolUse hook resolved on Claude; the resume call was
+     * dispatched on Mastra). Post-resume events flow through the SAME
+     * `ChatStreamResult.eventStream` returned by the most recent
+     * {@link stream} call on the thread.
      *
      * @param agentId - ID of the agent.
      * @param threadId - ID of the conversation thread (needed for harness-internal state lookup).
      * @param toolCallId - ID of the tool call to approve.
      */
-    approveToolCall(agentId: string, threadId: string, toolCallId: string): Promise<ChatStreamResult>;
+    approveToolCall(agentId: string, threadId: string, toolCallId: string): Promise<void>;
     /**
-     * Decline a pending tool call. The harness resumes the stream with the
-     * model acknowledging the decline and potentially suggesting alternatives.
+     * Decline a pending tool call. The harness resumes the agentic loop with
+     * the model acknowledging the decline and potentially suggesting
+     * alternatives.
      *
-     * Returns a `ChatStreamResult` containing the continuation stream — the harness
-     * cancels the pending tool call, generates the model's acknowledgement response,
-     * and streams both the text and events back to the caller.
+     * Returns `Promise<void>` once the harness has accepted the decline.
+     * Post-resume events flow through the SAME `ChatStreamResult.eventStream`
+     * returned by the most recent {@link stream} call on the thread.
      *
      * @param agentId - ID of the agent.
      * @param threadId - ID of the conversation thread.
      * @param toolCallId - ID of the tool call to decline.
      */
-    declineToolCall(agentId: string, threadId: string, toolCallId: string): Promise<ChatStreamResult>;
+    declineToolCall(agentId: string, threadId: string, toolCallId: string): Promise<void>;
     /**
      * 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/gen-sink.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Buffered async-generator wrapper used by `AgentHarness` implementations to
+ * deliver `ChatEvent`s to a consumer's `ChatStreamResult.eventStream`.
+ *
+ * The buffer holds events pushed before the consumer starts iterating, so the
+ * harness can begin populating the sink eagerly without coordinating with the
+ * consumer's `for await` loop. Events pushed after iteration starts unblock
+ * the awaiting consumer via an internal Promise waiter.
+ *
+ * # Single-iteration invariant
+ *
+ * `generator()` may be called **at most once** per sink. Sinks are stateful
+ * (single waiter slot, single buffer); two iterators on the same sink race on
+ * both, so two iterators is always a bug. Calling `generator()` a second time
+ * throws — the alternative (silently allowing the second call to share the
+ * buffer / waiter with the first) produced the deadlock-class bug catalogued
+ * in [issue #529](https://github.com/forcedotcom/agentic-dx/issues/529)
+ * Finding 4. Surface failures at construction-time, not at deadlock-time.
+ *
+ * # `isEnded()`
+ *
+ * Exposes the closed state for routing logic that needs to skip pushes onto
+ * a sink that's already been retired. Routing for a closed sink should
+ * silently no-op with a debug log rather than throw — the late event is
+ * upstream noise, not a programmer error.
+ *
+ * Exported from the public `index.ts` so third-party `AgentHarness`
+ * implementations in sibling packages can reuse it.
+ */
+export declare class GenSink<T> {
+    private readonly buffered;
+    private ended;
+    private waiter;
+    private generated;
+    push(event: T): void;
+    end(): void;
+    isEnded(): boolean;
+    generator(): AsyncGenerator<T, void>;
+    private iterate;
+    private wake;
+}

package/dist/harness/gen-sink.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Buffered async-generator wrapper used by `AgentHarness` implementations to
+ * deliver `ChatEvent`s to a consumer's `ChatStreamResult.eventStream`.
+ *
+ * The buffer holds events pushed before the consumer starts iterating, so the
+ * harness can begin populating the sink eagerly without coordinating with the
+ * consumer's `for await` loop. Events pushed after iteration starts unblock
+ * the awaiting consumer via an internal Promise waiter.
+ *
+ * # Single-iteration invariant
+ *
+ * `generator()` may be called **at most once** per sink. Sinks are stateful
+ * (single waiter slot, single buffer); two iterators on the same sink race on
+ * both, so two iterators is always a bug. Calling `generator()` a second time
+ * throws — the alternative (silently allowing the second call to share the
+ * buffer / waiter with the first) produced the deadlock-class bug catalogued
+ * in [issue #529](https://github.com/forcedotcom/agentic-dx/issues/529)
+ * Finding 4. Surface failures at construction-time, not at deadlock-time.
+ *
+ * # `isEnded()`
+ *
+ * Exposes the closed state for routing logic that needs to skip pushes onto
+ * a sink that's already been retired. Routing for a closed sink should
+ * silently no-op with a debug log rather than throw — the late event is
+ * upstream noise, not a programmer error.
+ *
+ * Exported from the public `index.ts` so third-party `AgentHarness`
+ * implementations in sibling packages can reuse it.
+ */
+export class GenSink {
+    buffered = [];
+    ended = false;
+    waiter = null;
+    generated = false;
+    push(event) {
+        if (this.ended)
+            return;
+        this.buffered.push(event);
+        this.wake();
+    }
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.wake();
+    }
+    isEnded() {
+        return this.ended;
+    }
+    generator() {
+        // Synchronous guard. Must live outside the async generator body —
+        // async generators are lazy (the body does not execute until the
+        // first `next()`), so a `throw` inside the body would not surface
+        // at the second `generator()` call site as expected.
+        if (this.generated) {
+            throw new Error('GenSink.generator(): sinks are single-iteration. ' +
+                'Two iterators on one sink race on the buffer and waiter slot. ' +
+                'See https://github.com/forcedotcom/agentic-dx/issues/529 (Finding 4).');
+        }
+        this.generated = true;
+        return this.iterate();
+    }
+    async *iterate() {
+        while (true) {
+            if (this.buffered.length > 0) {
+                yield this.buffered.shift();
+                continue;
+            }
+            if (this.ended)
+                return;
+            await new Promise((resolve) => {
+                this.waiter = { resolve };
+            });
+        }
+    }
+    wake() {
+        const w = this.waiter;
+        if (w) {
+            this.waiter = null;
+            w.resolve();
+        }
+    }
+}
+//# sourceMappingURL=gen-sink.js.map

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/harness/index.d.ts

@@ -2,3 +2,4 @@ export type { AgentHarness, WithAgentConfig, ConfigOf } from './agent-harness.js
 export type { HarnessFactory } from './harness-factory.js';
 export type { AgentConfig, StreamOptions } from './harness-config.js';
 export { toHarnessConfig, DEFAULT_MAX_STEPS } from './harness-config.js';
+export { GenSink } from './gen-sink.js';

package/dist/harness/index.js

@@ -3,4 +3,5 @@
  * See LICENSE.txt for license terms.
  */
 export { toHarnessConfig, DEFAULT_MAX_STEPS } from './harness-config.js';
+export { GenSink } from './gen-sink.js';
 //# sourceMappingURL=index.js.map

package/dist/harness/public.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Harness-implementation public surface.
+ *
+ * This module is reachable as `@salesforce/sfdx-agent-sdk/harness` —
+ * **never** import directly from `dist/` or via deep relative paths.
+ *
+ * # When to import from here
+ *
+ * Use this surface when implementing an `AgentHarness` (e.g.
+ * `@salesforce/sfdx-agent-harness-claude`,
+ * `@salesforce/sfdx-agent-harness-mastra`). It re-exports both the
+ * harness contract types (`AgentHarness`, `HarnessFactory`) and the
+ * harness-implementation helpers consumer applications must not touch
+ * (`HarnessBusOwner`, `GenSink`, `lowerStreamInput`,
+ * `SUPPORTED_PROTOCOL_VERSIONS`).
+ *
+ * # Why this is a separate subpath
+ *
+ * Consumer applications (anything that calls `createAgentManager` and
+ * iterates `ChatStreamResult`) import from the bare specifier:
+ *
+ *     import { createAgentManager, Agent } from '@salesforce/sfdx-agent-sdk';
+ *
+ * Harness implementations import from the subpath:
+ *
+ *     import { HarnessBusOwner, GenSink } from '@salesforce/sfdx-agent-sdk/harness';
+ *
+ * The split makes the boundary mechanical: a consumer who tries to import
+ * `HarnessBusOwner` from the bare specifier gets an immediate
+ * "not exported" error from the bundler / TS resolver, instead of
+ * accidentally reaching for a primitive they shouldn't be using.
+ *
+ * Type-only references to the contract interface (`AgentHarness`,
+ * `HarnessFactory`) ALSO appear on the bare specifier so consumer code
+ * that needs `AgentManager<H extends AgentHarness>` typing still works
+ * without a subpath import — but their runtime / constructible
+ * counterparts live only here.
+ *
+ * Symbols that consumers and harnesses both need (`AgentConfig`,
+ * `StreamOptions`, `DEFAULT_MAX_STEPS`, `resolveToolApprovalMode`,
+ * `ChatEvent` types, `Message` types, `MCPConfiguration`, etc.) stay on
+ * the bare specifier. The split is "harness-only" vs. "consumer-AND-harness",
+ * not "harness vs. consumer."
+ */
+export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './index.js';
+export { SUPPORTED_PROTOCOL_VERSIONS } from './agent-harness.js';
+export { HarnessBusOwner } from './harness-bus-owner.js';
+export { lowerStreamInput, type InputMessagePart } from './stream-input.js';
+export { GenSink } from './gen-sink.js';

package/dist/harness/public.js

@@ -0,0 +1,10 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export { SUPPORTED_PROTOCOL_VERSIONS } from './agent-harness.js';
+// ── Harness-implementation helpers ──────────────────────────────────
+export { HarnessBusOwner } from './harness-bus-owner.js';
+export { lowerStreamInput } from './stream-input.js';
+export { GenSink } from './gen-sink.js';
+//# sourceMappingURL=public.js.map

package/dist/index.d.ts

@@ -1,21 +1,19 @@
 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';
 export { type ChatSession, type ChatOptions } from './chat-session.js';
 export type { AgentConnectivityResolver, ResolvedConnectivity } from './agent-connectivity-resolver.js';
 export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './harness/index.js';
-export { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
-export { HarnessBusOwner } from './harness/harness-bus-owner.js';
-export { lowerStreamInput, type InputMessagePart } from './harness/stream-input.js';
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
 export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent, ChatStreamErrorEvent, ChatStreamStartedEvent, ChatStreamTrigger, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, McpServerStatusChangedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalRequestedEvent, ToolApprovalResolvedEvent, ToolExecutionCompletedEvent, ToolExecutionStartedEvent, } from './types/telemetry-events.js';
 export type { LogLevel, LogRecord, Unsubscribe } from '@salesforce/agentic-common';

package/dist/index.js

@@ -4,15 +4,12 @@
  */
 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';
 export {} from './agent.js';
 export {} from './chat-session.js';
-export { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
-export { HarnessBusOwner } from './harness/harness-bus-owner.js';
-export { lowerStreamInput } from './harness/stream-input.js';
 // ── Errors ───────────────────────────────────────────────────────────
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
 // ── MCP Auth ────────────────────────────────────────────────────────

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.16.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./harness": {
+      "types": "./dist/harness/public.d.ts",
+      "default": "./dist/harness/public.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -35,13 +39,13 @@
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@salesforce/agentic-common": "0.6.0",
-    "@salesforce/llm-gateway-sdk": "0.10.0"
+    "@salesforce/agentic-common": "0.8.0",
+    "@salesforce/llm-gateway-sdk": "0.12.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.12.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.15.0",
     "@types/node": "^22.19.17",
     "@vitest/coverage-istanbul": "^4.1.7",
     "@vitest/eslint-plugin": "^1.6.17",