@salesforce/sfdx-agent-sdk 0.80.0 → 0.82.0

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to `@salesforce/sfdx-agent-sdk` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.82.0] - 2026-09-15
+
+_No changes — released alongside dependent packages._
+
+## [0.81.0] - 2026-09-15
+
+### Features
+- **agent-sdk,harness-claude**: enable auto-compaction by default @W-24153849@ ([#813](https://github.com/forcedotcom/agentic-dx/pull/813))
+
+### Chores
+- **deps-dev**: bump eslint from 10.9.1 to 10.10.0 in the eslint group across 1 directory ([#815](https://github.com/forcedotcom/agentic-dx/pull/815))
+- **deps-dev**: bump the dev-dependencies group with 2 updates ([#814](https://github.com/forcedotcom/agentic-dx/pull/814))
+
 ## [0.80.0] - 2026-09-14
 
 ### Fixes

package/README.md

@@ -154,7 +154,7 @@ keeps unparameterized call sites working.
 | `getChatSessionIds`   | `() => string[]`                                                                                               | List active session IDs.                                                                                                                                                                                                                                                                                                                                                       |
 | `destroyChatSession`  | `(sessionId: string) => Promise<void>`                                                                         | Destroy a session and its history.                                                                                                                                                                                                                                                                                                                                             |
 | `cloneChatSession`    | `(sourceSessionId: string) => Promise<ChatSession>`                                                            | Clone a session with its message history.                                                                                                                                                                                                                                                                                                                                      |
-| `compactChatSession`  | `(sessionId: string) => Promise<ChatSession>`                                                                  | Compact a session into a summarized new session.                                                                                                                                                                                                                                                                                                                               |
+| `compactChatSession`  | `(sessionId: string) => Promise<ChatSession>`                                                                  | Compact a session into a summarized **new** session (`session-destroyed` / `session-created` fire; the old `ChatSession` object is detached). Contrast with automatic auto-compaction (see "Auto-Compaction" below), which rotates the **existing** `ChatSession` object's id in place with no lifecycle events.                                                               |
 | `destroy`             | `() => Promise<void>`                                                                                          | Destroy the agent and all its sessions.                                                                                                                                                                                                                                                                                                                                        |
 | `onTelemetry`         | `(callback: TelemetryEventCallback) => Unsubscribe`                                                            | Subscribe to telemetry scoped to this agent (and its sessions).                                                                                                                                                                                                                                                                                                                |
 | `onLog`               | `(callback: (record: LogRecord) => void) => Unsubscribe`                                                       | Subscribe to logs scoped to this agent (and its sessions).                                                                                                                                                                                                                                                                                                                     |
@@ -165,7 +165,7 @@ A single conversation thread.
 
 | Method              | Signature                                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | ------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `getId`             | `() => string`                                                            | Session/thread identifier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `getId`             | `() => string`                                                            | Session/thread identifier. **Not immutable across the session's lifetime:** a successful automatic auto-compaction (see "Auto-Compaction" below) rotates this value in place — same `ChatSession` object, new id. Don't cache the return value as a stable key; call `getId()` again after any `chat()` if you persist it externally.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `chat`              | `(message: string, options?: ChatOptions) => Promise<ChatStreamResult>`   | Send a message and stream the response. The returned `eventStream` is the single iterator for the entire chat turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `submitToolResult`  | `(toolResult: ToolResultInfo) => Promise<void>`                           | Return a consumer-executed tool result. Control message on the existing turn — post-resume events flow on the same stream.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `approveToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<void>` | Approve a pending tool call. `{ remember: true }` ("Allow always") appends an `allow` rule to `AgentConfig.toolPolicies` and persists it before settling. Control message on the existing turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
@@ -271,19 +271,20 @@ telemetry for a service of your own.
 
 #### `AgentConfig`
 
-| 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. `'sfdc_ai__DefaultGPT5'`), or a pre-built `Model` instance to opt into a Bedrock-Anthropic Claude variant the SDK has not yet released — see `createClaudeModel(gatewayId, overrides)` exported from this package. Legacy pinned `llmgateway__*` ids still resolve via a back-compat alias map. |
-| `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.                                         |
-| `toolPolicies?`        | `ToolPolicyRule[]`   | Ordered per-tool approval rules resolved by `resolveToolApprovalPolicy` (cross-tier deny-wins / within-tier last-wins). Author directly or via `definePolicy(...)`. See "Tool Approval Policy" below.                                                                                                                                                                        |
-| `defaultToolDecision?` | `Decision`           | Fallback decision when no rule matches. Defaults to `'allow'` (no policy ⇒ no gating). Set to `'require-approval'` for a fail-closed posture (recommended for catalogs with un-annotated MCP servers).                                                                                                                                                                       |
+| 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. `'sfdc_ai__DefaultGPT5'`), or a pre-built `Model` instance to opt into a Bedrock-Anthropic Claude variant the SDK has not yet released — see `createClaudeModel(gatewayId, overrides)` exported from this package. Legacy pinned `llmgateway__*` ids still resolve via a back-compat alias map. |
+| `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.                                         |
+| `toolPolicies?`            | `ToolPolicyRule[]`   | Ordered per-tool approval rules resolved by `resolveToolApprovalPolicy` (cross-tier deny-wins / within-tier last-wins). Author directly or via `definePolicy(...)`. See "Tool Approval Policy" below.                                                                                                                                                                        |
+| `defaultToolDecision?`     | `Decision`           | Fallback decision when no rule matches. Defaults to `'allow'` (no policy ⇒ no gating). Set to `'require-approval'` for a fail-closed posture (recommended for catalogs with un-annotated MCP servers).                                                                                                                                                                       |
+| `autoCompactionThreshold?` | `number`             | Occupancy ratio (0-1) that triggers a thread compaction before the next turn's model call. Defaults to `DEFAULT_AUTO_COMPACTION_THRESHOLD` (0.9). Auto-compaction is always active — there is no field to disable it. See "Auto-Compaction" below.                                                                                                                           |
 
 #### `AgentStateUpdate` and `ConsumerMetadataMutation`
 
@@ -387,6 +388,34 @@ invariant alone. The exact resolved message reaches both the model and the singl
 It is never written to telemetry/log fields and never creates a remembered deny rule; untyped JavaScript that also
 supplies `remember: true` still follows those safety rules.
 
+#### Auto-Compaction
+
+Every agent auto-compacts its threads once context usage crosses `AgentConfig.autoCompactionThreshold` (default 0.9),
+checked once per turn before the model call. **Auto-compaction is always active — there is no field to disable it.**
+`resolveAutoCompactionThreshold` is the pure resolver harness authors call to apply the default; it's exported for
+consumers who want to inspect the effective threshold for an agent.
+
+```typescript
+import { resolveAutoCompactionThreshold, DEFAULT_AUTO_COMPACTION_THRESHOLD } from '@salesforce/sfdx-agent-sdk';
+
+resolveAutoCompactionThreshold(config.autoCompactionThreshold);
+// → number
+// defaults to DEFAULT_AUTO_COMPACTION_THRESHOLD (0.9) when omitted
+```
+
+Raise or lower `autoCompactionThreshold` (0–1) to change how full the context window must be before a compaction is
+triggered. On a harness whose runtime already runs its own native auto-compaction mechanism
+(`AgentHarness.hasNativeAutoCompaction === true`), the SDK's own turn-boundary trigger does not run for that harness's
+sessions — the threshold is forwarded to the harness's native mechanism instead, so double-compaction never happens.
+
+**This is a different lifecycle contract than `Agent.compactChatSession()`.** A successful automatic compaction rotates
+the same `ChatSession` object's id **in place** — `session.getId()` returns a new value after the triggering `chat()`
+call, with no `session-destroyed` / `session-created` telemetry. The manual `compactChatSession()` verb instead detaches
+the old session and hands back a brand-new `ChatSession`, firing those lifecycle events. If you key persistence, UI
+state, or logs off `getId()`, re-read it after every `chat()` call rather than caching it — and don't call
+`compactChatSession()` on a thread that already has automatic auto-compaction enabled unless you intend two independent
+compaction paths to potentially run back-to-back.
+
 #### `MCPConfiguration`
 
 ```typescript

package/dist/agent.d.ts

@@ -383,7 +383,21 @@ export declare class DefaultAgent implements Agent {
      * the concrete `DefaultAgent` type rather than `Agent`.
      */
     restoreSessions(threadIds: string[]): void;
+    /** Registers a thread's telemetry-router slice and records its unregister callback. */
+    private registerSlice;
+    /** Runs and clears a thread's telemetry-router slice unregister callback, if any. */
+    private unregisterSlice;
     private attachSession;
     private detachSession;
+    /**
+     * Re-keys the `sessions` map and the telemetry-router session slice after an in-place
+     * auto-compaction rotation (see `DefaultChatSession.maybeAutoCompact`). The session object
+     * itself is unchanged — only its backing thread id — so this does NOT emit
+     * `session-destroyed` / `session-created`; from the consumer's perspective the same
+     * `ChatSession` they already hold just now reports a different `getId()`. Without this,
+     * `getChatSession(newThreadId)` would miss and `destroyChatSession(oldThreadId)` would try
+     * to destroy a thread the harness already destroyed as part of compaction.
+     */
+    private handleAutoCompactionRotation;
     private assertNotDisposed;
 }

package/dist/agent.js

@@ -3,7 +3,7 @@
  * See LICENSE.txt for license terms.
  */
 import { LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
-import { toHarnessConfig, } from './harness/harness-config.js';
+import { resolveAutoCompactionThreshold, toHarnessConfig, } from './harness/harness-config.js';
 import { normalizeMcpAuthProviders } from './mcp-auth.js';
 import { DefaultChatSession } from './chat-session.js';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
@@ -457,8 +457,22 @@ export class DefaultAgent {
             }
         }
     }
-    attachSession(threadId) {
+    /** Registers a thread's telemetry-router slice and records its unregister callback. */
+    registerSlice(threadId) {
         const slice = this.router.registerSession(threadId);
+        this.sessionSliceUnregisters.set(threadId, () => this.router.unregisterSession(threadId));
+        return slice;
+    }
+    /** Runs and clears a thread's telemetry-router slice unregister callback, if any. */
+    unregisterSlice(threadId) {
+        const unregister = this.sessionSliceUnregisters.get(threadId);
+        if (unregister) {
+            unregister();
+            this.sessionSliceUnregisters.delete(threadId);
+        }
+    }
+    attachSession(threadId) {
+        const slice = this.registerSlice(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
@@ -476,12 +490,20 @@ export class DefaultAgent {
         const persistRememberedRule = async (rule) => {
             await this.updateAgentConfig({ toolPolicies: [...(this.config.toolPolicies ?? []), rule] });
         };
+        // Live getter, same pattern as `getContextWindow` — reads `this.config.autoCompactionThreshold`
+        // at call time so an `updateAgentConfig()` change takes effect on the session's next turn.
+        const getAutoCompactionThreshold = () => resolveAutoCompactionThreshold(this.config.autoCompactionThreshold);
         const session = new DefaultChatSession(this.harness, this.agentId, threadId, slice, {
             telemetry: this.telemetryBus,
             log: this.logBus,
-        }, getContextWindow, { clock: this.clock, idGenerator: this.idGenerator, persistRememberedRule });
+        }, getContextWindow, {
+            clock: this.clock,
+            idGenerator: this.idGenerator,
+            persistRememberedRule,
+            getAutoCompactionThreshold,
+            onThreadIdRotated: (oldThreadId, newThreadId) => this.handleAutoCompactionRotation(oldThreadId, newThreadId),
+        });
         this.sessions.set(threadId, session);
-        this.sessionSliceUnregisters.set(threadId, () => this.router.unregisterSession(threadId));
         const sessionCreatedAt = this.clock.now();
         // Tier-1 pair: share one tick across the telemetry event and its colocated log sibling.
         this.telemetryBus.emitTelemetry({ type: 'session-created', agentId: this.agentId, threadId }, sessionCreatedAt);
@@ -503,13 +525,28 @@ export class DefaultAgent {
         else {
             session.releaseWithoutEvent();
         }
-        const unregister = this.sessionSliceUnregisters.get(threadId);
-        if (unregister) {
-            unregister();
-            this.sessionSliceUnregisters.delete(threadId);
-        }
+        this.unregisterSlice(threadId);
         this.sessions.delete(threadId);
     }
+    /**
+     * Re-keys the `sessions` map and the telemetry-router session slice after an in-place
+     * auto-compaction rotation (see `DefaultChatSession.maybeAutoCompact`). The session object
+     * itself is unchanged — only its backing thread id — so this does NOT emit
+     * `session-destroyed` / `session-created`; from the consumer's perspective the same
+     * `ChatSession` they already hold just now reports a different `getId()`. Without this,
+     * `getChatSession(newThreadId)` would miss and `destroyChatSession(oldThreadId)` would try
+     * to destroy a thread the harness already destroyed as part of compaction.
+     */
+    handleAutoCompactionRotation(oldThreadId, newThreadId) {
+        const session = this.sessions.get(oldThreadId);
+        if (!session)
+            return;
+        this.sessions.delete(oldThreadId);
+        this.sessions.set(newThreadId, session);
+        this.unregisterSlice(oldThreadId);
+        const newSlice = this.registerSlice(newThreadId);
+        session.rebindInboundSlice(newSlice);
+    }
     assertNotDisposed() {
         if (this.disposed) {
             throw new AgentSDKError('Agent has been disposed.', AgentSDKErrorType.DISPOSED);

package/dist/chat-session.d.ts

@@ -1,6 +1,6 @@
 import { type Clock, LogBus, type LogRecord, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
 import type { AgentHarness } from './harness/agent-harness.js';
-import type { StreamOptions } from './harness/harness-config.js';
+import { type StreamOptions } from './harness/harness-config.js';
 import type { TelemetrySlice } from './internal/telemetry-router.js';
 import type { ChatEvent, ChatStreamResult } from './types/events.js';
 import type { Message, MessagePart } from './types/messages.js';
@@ -21,6 +21,16 @@ export type ChatOptions = StreamOptions;
  * `toolPolicies`-only partial so no connectivity re-resolution is triggered.
  */
 export type RememberedRulePersister = (rule: ToolPolicyRule) => Promise<void>;
+/**
+ * Notifies the owning `Agent` that a session's backing thread was rotated by an
+ * in-place auto-compaction (the session kept the same object identity, but
+ * {@link ChatSession.getId} now returns a new value). Supplied by `DefaultAgent`
+ * so it can re-key its `sessions` map and the telemetry-router session slice from
+ * the old id to the new one — otherwise `Agent.getChatSession` /
+ * `destroyChatSession` would keep looking up a thread the harness already
+ * destroyed. Omitted in unit tests that don't need this bookkeeping.
+ */
+export type ThreadIdRotatedNotifier = (oldThreadId: string, newThreadId: string) => void;
 /**
  * Optional injected dependencies for a {@link DefaultChatSession}. Bundled into
  * one trailing bag (rather than a growing tail of positional params) so a new
@@ -41,6 +51,16 @@ export type ChatSessionDeps = {
      * then behaves as a one-shot with no write. See {@link RememberedRulePersister}.
      */
     persistRememberedRule?: RememberedRulePersister;
+    /**
+     * Live getter for the agent's resolved auto-compaction threshold. Called at the
+     * start of every {@link ChatSession.chat} so a live `Agent.updateAgentConfig()` change
+     * to `AgentConfig.autoCompactionThreshold` takes effect on the next turn — same pattern
+     * as `getContextWindow`. Defaults to `DEFAULT_AUTO_COMPACTION_THRESHOLD` (0.9) when
+     * omitted.
+     */
+    getAutoCompactionThreshold?: () => number;
+    /** See {@link ThreadIdRotatedNotifier}. */
+    onThreadIdRotated?: ThreadIdRotatedNotifier;
 };
 /**
  * Parent bus pair used to wire upward forwarding at construction time.
@@ -321,7 +341,14 @@ export interface ChatSession {
 export declare class DefaultChatSession implements ChatSession {
     private readonly harness;
     private readonly agentId;
-    private readonly threadId;
+    /**
+     * Mutable (not `readonly`): auto-compaction rotates a session's backing thread in
+     * place — see {@link maybeAutoCompact} — so the session's public id
+     * ({@link getId}) can change over its lifetime while the object identity stays
+     * the same. {@link onThreadIdRotated} notifies `DefaultAgent` so its `sessions`
+     * map and telemetry-router slice stay keyed correctly.
+     */
+    private threadId;
     private readonly chatEventBus;
     private readonly telemetryBus;
     private readonly logBus;
@@ -390,6 +417,18 @@ export declare class DefaultChatSession implements ChatSession {
      */
     private latestTurnUsage;
     private latestStepCount;
+    /**
+     * Whether {@link latestUsage} reflects the last COMPLETED normal turn (`true`) or is stale —
+     * unset (fresh session), or left over from an errored/abandoned turn (`false`). Read by
+     * {@link currentOccupancy} to decide between the two occupancy signals: a trustworthy live
+     * reading is preferred; otherwise occupancy falls back to a transcript-size estimate. Set
+     * `true` in {@link wrapEventStream}'s natural-completion branch, `false` in its error branch
+     * and by {@link clearHistory}.
+     */
+    private lastTurnUsageTrustworthy;
+    /** Live getter for the agent's resolved auto-compaction threshold. See {@link ChatSessionDeps.getAutoCompactionThreshold}. */
+    private readonly getAutoCompactionThreshold;
+    private readonly onThreadIdRotated;
     private disposed;
     /**
      * True while a turn started by {@link chat} is in flight — from the `chat()`
@@ -443,6 +482,9 @@ export declare class DefaultChatSession implements ChatSession {
      * - MUST return an object containing the original `textStream` and the wrapped `eventStream`.
      * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
      *   before returning a stream result.
+     * - MUST check the auto-compaction policy before the harness call and, if the current
+     *   occupancy is at/above its threshold, compact the thread first (see
+     *   {@link maybeAutoCompact}) so the turn proceeds against the (now smaller) thread.
      */
     chat(message: string | MessagePart[], options?: ChatOptions): Promise<ChatStreamResult>;
     /**
@@ -492,7 +534,10 @@ export declare class DefaultChatSession implements ChatSession {
      * `chat-stream-started` is emitted by the entry-point method (chat / submitToolResult /
      * approveToolCall / declineToolCall) before the harness call so that pre-stream rejections
      * still produce a started+error pair. `startedAt` is captured there and threaded down so
-     * `durationMs` measures real elapsed time on both terminal events.
+     * `durationMs` measures real elapsed time on both terminal events. `threadId` is likewise
+     * captured before the harness call (pre-auto-compaction-rotation) and threaded down so the
+     * `chat-stream-started`/`chat-stream-completed`/`chat-stream-error` triple for one turn stays
+     * paired on the same threadId even when `maybeAutoCompact()` rotates `this.threadId` mid-turn.
      */
     private wrapEventStream;
     /**
@@ -547,6 +592,8 @@ export declare class DefaultChatSession implements ChatSession {
      *   absent) until the next turn produces one.
      */
     clearHistory(): Promise<void>;
+    /** Drops all retained per-turn usage state — shared by {@link clearHistory} and a successful {@link maybeAutoCompact} rotation, both of which retire the thread the retained state described. */
+    private resetUsageState;
     /**
      * @requirements
      * - MUST always return a populated `ContextUsage`. Pre-first-turn and post-`clearHistory()`,
@@ -596,6 +643,77 @@ export declare class DefaultChatSession implements ChatSession {
      * read from the same `latestUsage` snapshot `wrapEventStream` captures.
      */
     private contextUsageLogFields;
+    /**
+     * Pre-turn occupancy hook, called from {@link chat} before the harness call. Auto-compaction
+     * is always active — there is no "disabled" state to check. This method short-circuits
+     * immediately when `this.harness.hasNativeAutoCompaction` is `true`: a harness that runs its
+     * own native auto-compaction mechanism must not ALSO have the SDK's turn-boundary trigger run
+     * against the same conversation — that would double-compact via two uncoordinated mechanisms.
+     * A harness making that claim is expected to honor `AgentConfig.autoCompactionThreshold`
+     * itself, by forwarding it to its native mechanism; the SDK never verifies this.
+     *
+     * Otherwise, when {@link currentOccupancy} is at/above the resolved
+     * {@link ChatSessionDeps.getAutoCompactionThreshold} threshold, compacts the thread in place —
+     * the session keeps its object identity but {@link getId} returns a new value afterward, and
+     * {@link onThreadIdRotated} notifies `DefaultAgent` to re-key its bookkeeping. Both outcomes
+     * (`'compacted'` and `'failed'`) emit a structured `logBus` record tagged
+     * `event_type: 'auto-compaction'` — this log has no colocated telemetry sibling, unlike the
+     * Tier-1 sites documented in `ARCHITECTURE.md`, so a subscriber must read it off `logBus`
+     * directly.
+     *
+     * A `COMPACTION_FAILED` error is swallowed: the session is left intact (still pointed at
+     * the pre-compaction thread, per the harness contract's "leave it intact on failure"
+     * clause) and the turn proceeds normally against it rather than failing the whole `chat()`
+     * call over a best-effort maintenance operation. Any other error from {@link currentOccupancy}
+     * (e.g. a transient `getMessages()` failure while estimating transcript occupancy) is
+     * likewise swallowed (after a `logBus.warn`) — it is a best-effort heuristic read, not the
+     * actual harness operation, and a hiccup there must not fail the user's turn. Any other error
+     * from `harness.compactThread` propagates to `chat()`'s existing pre-stream-failure handling.
+     *
+     * `abortSignal` is `chat()`'s composed signal — `cancelTurn()`'s own per-turn controller
+     * folded together with any caller-supplied `options.abortSignal` — checked before starting
+     * the occupancy read and again before calling `compactThread`, so an abort from EITHER source
+     * that lands while this is running skips (rather than starts) compaction. This narrows, but
+     * does not close, the window an abort can block on: `AgentHarness.compactThread` takes no
+     * `AbortSignal`, so a `compactThread` call already in flight when the signal aborts cannot be
+     * interrupted — the caller blocks for the remaining compaction latency, and if
+     * `harness.stream()` subsequently runs against an already-aborted signal, the turn can end via
+     * `notifyPreStreamError` with `finishReason: 'error'` rather than `'cancelled'`. See
+     * `cancelTurn()`'s Critical Invariant below for the full contract and why this residual gap is
+     * accepted for now.
+     */
+    private maybeAutoCompact;
+    /**
+     * The occupancy ratio (0-1) `maybeAutoCompact` checks against the configured threshold,
+     * from whichever of two signals is available, in priority order:
+     *
+     * 1. **Live usage** — when {@link lastTurnUsageTrustworthy}, the same `effectiveInputTokens()
+     *    / contextWindow` computation {@link getContextUsage} exposes as `usedFraction`.
+     * 2. **Transcript-size estimate** — otherwise (cold session, or the prior turn ended
+     *    abnormally), a rough estimate from the persisted transcript's character count via
+     *    {@link estimateTranscriptOccupancy}.
+     *
+     * Returns `undefined` when neither signal is available (a brand-new session with no
+     * completed turn and no persisted messages), so `maybeAutoCompact` never compacts a
+     * session with nothing to compact.
+     */
+    private currentOccupancy;
+    /**
+     * Estimates occupancy from the thread's persisted transcript size (chars ÷
+     * {@link CHARS_PER_TOKEN} as a token-count proxy) when no trustworthy live usage reading is
+     * available. Returns `undefined` for an empty transcript so a brand-new thread never
+     * triggers compaction.
+     */
+    private estimateTranscriptOccupancy;
+    /**
+     * Re-points this session's inbound router-slice forwarding at a new slice, unsubscribing
+     * the old one first. Called by `DefaultAgent` after an auto-compaction rotation re-registers
+     * the telemetry-router slice under the new thread id, so any future thread-scoped
+     * harness-emitted event routes to this session under its new id rather than falling through
+     * to "unrouted". Not part of the public {@link ChatSession} interface — `DefaultAgent` holds
+     * the concrete `DefaultChatSession` type, same as {@link releaseWithoutEvent}.
+     */
+    rebindInboundSlice(slice: TelemetrySlice): void;
     /**
      * @requirements
      * - IF `message` is a `string`, it MUST be formatted into a standard `Message` object array containing exactly one message.
@@ -699,7 +817,10 @@ export declare class DefaultChatSession implements ChatSession {
      * not throw.
      *
      * `startedAt` is the timestamp captured by {@link emitChatStreamStarted} so `durationMs`
-     * measures real elapsed time even for pre-stream rejections.
+     * measures real elapsed time even for pre-stream rejections. `threadId` is the same
+     * pre-auto-compaction-rotation id captured alongside `startedAt`, so this event stays paired
+     * with its `chat-stream-started` even when the rejection surfaces after a mid-turn rotation
+     * (e.g. `harness.stream()` itself fails on the post-rotation thread).
      */
     private notifyPreStreamError;
     /**

package/dist/chat-session.js

@@ -3,8 +3,10 @@
  * See LICENSE.txt for license terms.
  */
 import { backfillCreatedAt, EventBus, LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
+import { resolveAutoCompactionThreshold } from './harness/harness-config.js';
 import { resolveToolDeclineModelMessage } from './harness/tool-decline.js';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
+import { CHARS_PER_TOKEN, estimateTranscriptChars } from './internal/transcript-occupancy.js';
 import { createTelemetryBus, } from './types/telemetry-events.js';
 /**
  * Composes the SDK-owned per-turn abort signal with the caller's (if any) into
@@ -16,6 +18,10 @@ import { createTelemetryBus, } from './types/telemetry-events.js';
 function composeAbortSignals(own, caller) {
     return caller === undefined ? own : AbortSignal.any([own, caller]);
 }
+/** Clamps an occupancy ratio to `[0, 1]` — a denominator/numerator pair can fall outside that range (e.g. a `contextWindow` change mid-session, or an estimate overshoot). */
+function clampFraction(numerator, denominator) {
+    return Math.min(1, Math.max(0, numerator / denominator));
+}
 /**
  * Default implementation of {@link ChatSession} that delegates all operations
  * to an {@link AgentHarness}. The session holds its agent ID and thread ID
@@ -24,6 +30,13 @@ function composeAbortSignals(own, caller) {
 export class DefaultChatSession {
     harness;
     agentId;
+    /**
+     * Mutable (not `readonly`): auto-compaction rotates a session's backing thread in
+     * place — see {@link maybeAutoCompact} — so the session's public id
+     * ({@link getId}) can change over its lifetime while the object identity stays
+     * the same. {@link onThreadIdRotated} notifies `DefaultAgent` so its `sessions`
+     * map and telemetry-router slice stay keyed correctly.
+     */
     threadId;
     chatEventBus = new EventBus();
     // Constructed in the constructor body so they use the injected `clock` (tests inject a StubClock for
@@ -95,6 +108,18 @@ export class DefaultChatSession {
      */
     latestTurnUsage = undefined;
     latestStepCount = 0;
+    /**
+     * Whether {@link latestUsage} reflects the last COMPLETED normal turn (`true`) or is stale —
+     * unset (fresh session), or left over from an errored/abandoned turn (`false`). Read by
+     * {@link currentOccupancy} to decide between the two occupancy signals: a trustworthy live
+     * reading is preferred; otherwise occupancy falls back to a transcript-size estimate. Set
+     * `true` in {@link wrapEventStream}'s natural-completion branch, `false` in its error branch
+     * and by {@link clearHistory}.
+     */
+    lastTurnUsageTrustworthy = false;
+    /** Live getter for the agent's resolved auto-compaction threshold. See {@link ChatSessionDeps.getAutoCompactionThreshold}. */
+    getAutoCompactionThreshold;
+    onThreadIdRotated;
     disposed = false;
     /**
      * True while a turn started by {@link chat} is in flight — from the `chat()`
@@ -146,6 +171,9 @@ export class DefaultChatSession {
         this.clock = deps.clock ?? new RealClock();
         this.idGenerator = deps.idGenerator ?? new UUIDGenerator();
         this.persistRememberedRule = deps.persistRememberedRule;
+        this.getAutoCompactionThreshold =
+            deps.getAutoCompactionThreshold ?? (() => resolveAutoCompactionThreshold(undefined));
+        this.onThreadIdRotated = deps.onThreadIdRotated;
         this.telemetryBus = createTelemetryBus(this.clock);
         this.logBus = new LogBus(this.clock);
         this.inboundUnsubs = [inbound.telemetry.forwardTo(this.telemetryBus), inbound.log.forwardTo(this.logBus)];
@@ -163,6 +191,9 @@ export class DefaultChatSession {
      * - MUST return an object containing the original `textStream` and the wrapped `eventStream`.
      * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
      *   before returning a stream result.
+     * - MUST check the auto-compaction policy before the harness call and, if the current
+     *   occupancy is at/above its threshold, compact the thread first (see
+     *   {@link maybeAutoCompact}) so the turn proceeds against the (now smaller) thread.
      */
     async chat(message, options) {
         this.assertNotDisposed();
@@ -181,7 +212,17 @@ export class DefaultChatSession {
         this.turnAbortController = turnAbort;
         const abortSignal = composeAbortSignals(turnAbort.signal, options?.abortSignal);
         const startedAt = this.emitChatStreamStarted('chat');
-        const streamPromise = this.harness.stream(this.agentId, this.threadId, message, { ...options, abortSignal });
+        // Captured before `maybeAutoCompact()` runs so the whole `chat-stream-started`
+        // / `chat-stream-completed` / `chat-stream-error` triple for THIS turn carries
+        // the same threadId, even though auto-compaction may rotate `this.threadId` in
+        // place mid-turn (the telemetry pairing contract keys on the pre-rotation id —
+        // the thread the turn was issued against).
+        const turnThreadId = this.threadId;
+        // Chained (not `await`ed here) so the auto-compaction check runs to completion
+        // before `harness.stream()` is invoked — it may rotate `this.threadId` in place,
+        // and the stream call must see the post-rotation id — while `streamPromise` is
+        // still derived synchronously, before any `await` in this function body.
+        const streamPromise = this.maybeAutoCompact(abortSignal).then(() => this.harness.stream(this.agentId, this.threadId, message, { ...options, abortSignal }));
         // Derive the settle barrier synchronously from the stream promise — before
         // the `await` — so a `cancelTurn()` that races this `chat()` still awaits the
         // real teardown + persistence flush rather than an `undefined` (an immediate
@@ -193,14 +234,14 @@ export class DefaultChatSession {
             const result = await streamPromise;
             return {
                 textStream: result.textStream,
-                eventStream: this.wrapEventStream(result.eventStream, startedAt),
+                eventStream: this.wrapEventStream(result.eventStream, startedAt, turnThreadId),
             };
         }
         catch (err) {
             // Pre-stream failure ends the turn before a stream exists — clear the
             // flag here since `wrapEventStream` (which normally clears it) never runs.
             this.turnActive = false;
-            this.notifyPreStreamError(err, startedAt);
+            this.notifyPreStreamError(err, startedAt, turnThreadId);
             throw err;
         }
     }
@@ -277,9 +318,12 @@ export class DefaultChatSession {
      * `chat-stream-started` is emitted by the entry-point method (chat / submitToolResult /
      * approveToolCall / declineToolCall) before the harness call so that pre-stream rejections
      * still produce a started+error pair. `startedAt` is captured there and threaded down so
-     * `durationMs` measures real elapsed time on both terminal events.
+     * `durationMs` measures real elapsed time on both terminal events. `threadId` is likewise
+     * captured before the harness call (pre-auto-compaction-rotation) and threaded down so the
+     * `chat-stream-started`/`chat-stream-completed`/`chat-stream-error` triple for one turn stays
+     * paired on the same threadId even when `maybeAutoCompact()` rotates `this.threadId` mid-turn.
      */
-    async *wrapEventStream(stream, startedAt) {
+    async *wrapEventStream(stream, startedAt, threadId) {
         let sawFinish = false;
         let lastError;
         let finishUsage;
@@ -371,11 +415,15 @@ export class DefaultChatSession {
         const finishedAt = this.clock.now();
         const durationMs = finishedAt.getTime() - startedAt.getTime();
         if (lastError !== undefined) {
+            // The retained `latestUsage` is stale for occupancy purposes — the errored/abandoned
+            // turn may have jumped occupancy without a completed step-finish reflecting it. The
+            // next `maybeAutoCompact()` falls back to the transcript-size estimate instead.
+            this.lastTurnUsageTrustworthy = false;
             // Tier-1 pair: share one tick across the telemetry event and its colocated log sibling.
             this.telemetryBus.emitTelemetry({
                 type: 'chat-stream-error',
                 agentId: this.agentId,
-                threadId: this.threadId,
+                threadId,
                 durationMs,
                 error: lastError,
             }, finishedAt);
@@ -385,7 +433,7 @@ export class DefaultChatSession {
                 context: {
                     event_type: 'chat-stream-error',
                     agentId: this.agentId,
-                    threadId: this.threadId,
+                    threadId,
                     durationMs,
                 },
                 error: lastError,
@@ -404,10 +452,13 @@ export class DefaultChatSession {
             // `getContextUsage()` (which spreads on read, carrying the mutation).
             this.latestTurnUsage = finishUsage === undefined ? undefined : { ...finishUsage };
             this.latestStepCount = stepCount;
+            // A completed turn's `latestUsage` is a trustworthy live occupancy reading —
+            // `maybeAutoCompact()` on the next `chat()` can use it directly.
+            this.lastTurnUsageTrustworthy = true;
             this.telemetryBus.emitTelemetry({
                 type: 'chat-stream-completed',
                 agentId: this.agentId,
-                threadId: this.threadId,
+                threadId,
                 durationMs,
                 // Self-describing usage on telemetry (W-24125085, Phase 2): `usage`
                 // stays as the legacy alias for the whole-turn aggregate, now also
@@ -451,7 +502,7 @@ export class DefaultChatSession {
                 context: {
                     event_type: 'chat-stream-completed',
                     agentId: this.agentId,
-                    threadId: this.threadId,
+                    threadId,
                     durationMs,
                     ...(finishUsage !== undefined ? { turnUsage: finishUsage } : {}),
                     ...(stepCount > 0 ? { stepCount } : {}),
@@ -548,9 +599,14 @@ export class DefaultChatSession {
     async clearHistory() {
         this.assertNotDisposed();
         await this.harness.clearMessages(this.agentId, this.threadId);
+        this.resetUsageState();
+    }
+    /** Drops all retained per-turn usage state — shared by {@link clearHistory} and a successful {@link maybeAutoCompact} rotation, both of which retire the thread the retained state described. */
+    resetUsageState() {
         this.latestUsage = {};
         this.latestTurnUsage = undefined;
         this.latestStepCount = 0;
+        this.lastTurnUsageTrustworthy = false;
     }
     /**
      * @requirements
@@ -579,7 +635,7 @@ export class DefaultChatSession {
         this.assertNotDisposed();
         const contextWindow = this.getContextWindow();
         const contextTokens = this.effectiveInputTokens();
-        const usedFraction = contextTokens === undefined ? undefined : Math.min(1, Math.max(0, contextTokens / contextWindow));
+        const usedFraction = contextTokens === undefined ? undefined : clampFraction(contextTokens, contextWindow);
         // Spread `latestUsage` so consumer mutation of the returned object cannot
         // leak back into the session's retained state on a later call. `usage` is
         // the legacy alias for `lastStepUsage` (Phase 2, W-24125085) — the SAME
@@ -642,9 +698,156 @@ export class DefaultChatSession {
             lastStepUsage: { ...this.latestUsage },
             contextTokens,
             contextWindow,
-            usedFraction: Math.min(1, Math.max(0, contextTokens / contextWindow)),
+            usedFraction: clampFraction(contextTokens, contextWindow),
         };
     }
+    /**
+     * Pre-turn occupancy hook, called from {@link chat} before the harness call. Auto-compaction
+     * is always active — there is no "disabled" state to check. This method short-circuits
+     * immediately when `this.harness.hasNativeAutoCompaction` is `true`: a harness that runs its
+     * own native auto-compaction mechanism must not ALSO have the SDK's turn-boundary trigger run
+     * against the same conversation — that would double-compact via two uncoordinated mechanisms.
+     * A harness making that claim is expected to honor `AgentConfig.autoCompactionThreshold`
+     * itself, by forwarding it to its native mechanism; the SDK never verifies this.
+     *
+     * Otherwise, when {@link currentOccupancy} is at/above the resolved
+     * {@link ChatSessionDeps.getAutoCompactionThreshold} threshold, compacts the thread in place —
+     * the session keeps its object identity but {@link getId} returns a new value afterward, and
+     * {@link onThreadIdRotated} notifies `DefaultAgent` to re-key its bookkeeping. Both outcomes
+     * (`'compacted'` and `'failed'`) emit a structured `logBus` record tagged
+     * `event_type: 'auto-compaction'` — this log has no colocated telemetry sibling, unlike the
+     * Tier-1 sites documented in `ARCHITECTURE.md`, so a subscriber must read it off `logBus`
+     * directly.
+     *
+     * A `COMPACTION_FAILED` error is swallowed: the session is left intact (still pointed at
+     * the pre-compaction thread, per the harness contract's "leave it intact on failure"
+     * clause) and the turn proceeds normally against it rather than failing the whole `chat()`
+     * call over a best-effort maintenance operation. Any other error from {@link currentOccupancy}
+     * (e.g. a transient `getMessages()` failure while estimating transcript occupancy) is
+     * likewise swallowed (after a `logBus.warn`) — it is a best-effort heuristic read, not the
+     * actual harness operation, and a hiccup there must not fail the user's turn. Any other error
+     * from `harness.compactThread` propagates to `chat()`'s existing pre-stream-failure handling.
+     *
+     * `abortSignal` is `chat()`'s composed signal — `cancelTurn()`'s own per-turn controller
+     * folded together with any caller-supplied `options.abortSignal` — checked before starting
+     * the occupancy read and again before calling `compactThread`, so an abort from EITHER source
+     * that lands while this is running skips (rather than starts) compaction. This narrows, but
+     * does not close, the window an abort can block on: `AgentHarness.compactThread` takes no
+     * `AbortSignal`, so a `compactThread` call already in flight when the signal aborts cannot be
+     * interrupted — the caller blocks for the remaining compaction latency, and if
+     * `harness.stream()` subsequently runs against an already-aborted signal, the turn can end via
+     * `notifyPreStreamError` with `finishReason: 'error'` rather than `'cancelled'`. See
+     * `cancelTurn()`'s Critical Invariant below for the full contract and why this residual gap is
+     * accepted for now.
+     */
+    async maybeAutoCompact(abortSignal) {
+        if (this.harness.hasNativeAutoCompaction || abortSignal.aborted)
+            return;
+        const threshold = this.getAutoCompactionThreshold();
+        let occupancy;
+        try {
+            occupancy = await this.currentOccupancy();
+        }
+        catch (err) {
+            this.logBus.warn('auto-compaction occupancy read failed; skipping compaction for this turn', { agentId: this.agentId, threadId: this.threadId }, err instanceof Error ? err : undefined);
+            return;
+        }
+        if (occupancy === undefined || occupancy < threshold || abortSignal.aborted)
+            return;
+        try {
+            const newThreadId = await this.harness.compactThread(this.agentId, this.threadId);
+            const oldThreadId = this.threadId;
+            const contextWindow = this.getContextWindow();
+            this.threadId = newThreadId;
+            this.resetUsageState();
+            this.onThreadIdRotated?.(oldThreadId, newThreadId);
+            this.logBus.emitLog({
+                level: 'info',
+                message: 'Auto-compaction fired',
+                context: {
+                    event_type: 'auto-compaction',
+                    trigger: 'auto',
+                    threshold,
+                    agentId: this.agentId,
+                    previousThreadId: oldThreadId,
+                    newThreadId,
+                    contextWindow,
+                    occupancy,
+                    outcome: 'compacted',
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof AgentSDKError && err.type === AgentSDKErrorType.COMPACTION_FAILED) {
+                this.logBus.emitLog({
+                    level: 'warn',
+                    message: 'Auto-compaction failed',
+                    context: {
+                        event_type: 'auto-compaction',
+                        trigger: 'auto',
+                        threshold,
+                        agentId: this.agentId,
+                        previousThreadId: this.threadId,
+                        contextWindow: this.getContextWindow(),
+                        occupancy,
+                        outcome: 'failed',
+                    },
+                });
+                return;
+            }
+            throw err;
+        }
+    }
+    /**
+     * The occupancy ratio (0-1) `maybeAutoCompact` checks against the configured threshold,
+     * from whichever of two signals is available, in priority order:
+     *
+     * 1. **Live usage** — when {@link lastTurnUsageTrustworthy}, the same `effectiveInputTokens()
+     *    / contextWindow` computation {@link getContextUsage} exposes as `usedFraction`.
+     * 2. **Transcript-size estimate** — otherwise (cold session, or the prior turn ended
+     *    abnormally), a rough estimate from the persisted transcript's character count via
+     *    {@link estimateTranscriptOccupancy}.
+     *
+     * Returns `undefined` when neither signal is available (a brand-new session with no
+     * completed turn and no persisted messages), so `maybeAutoCompact` never compacts a
+     * session with nothing to compact.
+     */
+    async currentOccupancy() {
+        if (this.lastTurnUsageTrustworthy) {
+            const contextTokens = this.effectiveInputTokens();
+            if (contextTokens !== undefined) {
+                return clampFraction(contextTokens, this.getContextWindow());
+            }
+        }
+        return this.estimateTranscriptOccupancy();
+    }
+    /**
+     * Estimates occupancy from the thread's persisted transcript size (chars ÷
+     * {@link CHARS_PER_TOKEN} as a token-count proxy) when no trustworthy live usage reading is
+     * available. Returns `undefined` for an empty transcript so a brand-new thread never
+     * triggers compaction.
+     */
+    async estimateTranscriptOccupancy() {
+        const messages = await this.harness.getMessages(this.agentId, this.threadId);
+        if (messages.length === 0)
+            return undefined;
+        const estimatedTokens = estimateTranscriptChars(messages) / CHARS_PER_TOKEN;
+        return clampFraction(estimatedTokens, this.getContextWindow());
+    }
+    /**
+     * Re-points this session's inbound router-slice forwarding at a new slice, unsubscribing
+     * the old one first. Called by `DefaultAgent` after an auto-compaction rotation re-registers
+     * the telemetry-router slice under the new thread id, so any future thread-scoped
+     * harness-emitted event routes to this session under its new id rather than falling through
+     * to "unrouted". Not part of the public {@link ChatSession} interface — `DefaultAgent` holds
+     * the concrete `DefaultChatSession` type, same as {@link releaseWithoutEvent}.
+     */
+    rebindInboundSlice(slice) {
+        for (const unsub of this.inboundUnsubs)
+            unsub();
+        this.inboundUnsubs.length = 0;
+        this.inboundUnsubs.push(slice.telemetry.forwardTo(this.telemetryBus), slice.log.forwardTo(this.logBus));
+    }
     /**
      * @requirements
      * - IF `message` is a `string`, it MUST be formatted into a standard `Message` object array containing exactly one message.
@@ -936,23 +1139,26 @@ export class DefaultChatSession {
      * not throw.
      *
      * `startedAt` is the timestamp captured by {@link emitChatStreamStarted} so `durationMs`
-     * measures real elapsed time even for pre-stream rejections.
+     * measures real elapsed time even for pre-stream rejections. `threadId` is the same
+     * pre-auto-compaction-rotation id captured alongside `startedAt`, so this event stays paired
+     * with its `chat-stream-started` even when the rejection surfaces after a mid-turn rotation
+     * (e.g. `harness.stream()` itself fails on the post-rotation thread).
      */
-    notifyPreStreamError(err, startedAt) {
+    notifyPreStreamError(err, startedAt, threadId) {
         const error = err instanceof Error ? err : new Error(String(err));
         this.chatEventBus.emit({ type: 'error', error });
         this.chatEventBus.emit({ type: 'finish', finishReason: 'error' });
         const finishedAt = this.clock.now();
         const durationMs = finishedAt.getTime() - startedAt.getTime();
         // Tier-1 pair: share one tick across the telemetry event and its colocated log sibling.
-        this.telemetryBus.emitTelemetry({ type: 'chat-stream-error', agentId: this.agentId, threadId: this.threadId, durationMs, error }, finishedAt);
+        this.telemetryBus.emitTelemetry({ type: 'chat-stream-error', agentId: this.agentId, threadId, durationMs, error }, finishedAt);
         this.logBus.emitLog({
             level: 'error',
             message: 'Chat stream failed',
             context: {
                 event_type: 'chat-stream-error',
                 agentId: this.agentId,
-                threadId: this.threadId,
+                threadId,
                 durationMs,
             },
             error,

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

@@ -72,6 +72,19 @@ export interface AgentHarness {
      * per-agent accessors take the agent id as their first argument.
      */
     readonly extensions: Record<string, unknown>;
+    /**
+     * `true` when this harness's underlying runtime already runs its own native
+     * auto-compaction mechanism, so the SDK's own turn-boundary auto-compaction
+     * trigger (`ChatSession`'s `maybeAutoCompact`) must NOT also run for this
+     * harness's sessions — running both would double-compact the same
+     * conversation via two uncoordinated mechanisms. Optional; a harness that
+     * omits the field (or sets it `false`) gets the SDK's trigger, which is the
+     * correct default for every harness with no native equivalent. A harness
+     * that sets `true` is expected to honor `AgentConfig.autoCompactionThreshold`
+     * itself, by forwarding it to its own native mechanism — the SDK never
+     * verifies this from the harness-agnostic side.
+     */
+    readonly hasNativeAutoCompaction?: boolean;
     /**
      * Shut down the harness gracefully, releasing all resources.
      * Disconnects MCP servers, closes storage connections, and

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

@@ -88,7 +88,28 @@ export type AgentConfig = {
      * annotation-matcher rules don't fire on tools with no annotations.
      */
     defaultToolDecision?: Decision;
+    /**
+     * Occupancy ratio (0-1) that triggers a compaction before the next turn's model call.
+     * Defaults to {@link DEFAULT_AUTO_COMPACTION_THRESHOLD} (0.9) when omitted. Values outside
+     * `[0.01, 0.99]` are clamped by {@link resolveAutoCompactionThreshold} — see its JSDoc for why.
+     *
+     * Auto-compaction is **always active** — there is no field to disable it. On a harness
+     * whose {@link AgentHarness.hasNativeAutoCompaction} is `true`, this value is forwarded to
+     * that harness's own native mechanism instead of running the SDK's turn-boundary trigger.
+     */
+    autoCompactionThreshold?: number;
 };
+/** Default {@link AgentConfig.autoCompactionThreshold} occupancy ratio used when a threshold is not supplied. */
+export declare const DEFAULT_AUTO_COMPACTION_THRESHOLD = 0.9;
+/**
+ * Resolves an {@link AgentConfig.autoCompactionThreshold} value to its effective threshold:
+ * defaults to {@link DEFAULT_AUTO_COMPACTION_THRESHOLD} when `threshold` is omitted or not a
+ * finite number (`NaN`, `Infinity`, `-Infinity`), then clamps the result to
+ * `[0.01, 0.99]` — see the comment above {@link AUTO_COMPACTION_THRESHOLD_MIN} for why this
+ * clamps rather than throws (a live `chat()` turn is the wrong place to fail a config mistake
+ * that was already accepted at `createAgent`/`updateAgentConfig` time).
+ */
+export declare function resolveAutoCompactionThreshold(threshold?: number): number;
 /**
  * Resolves the per-agent OAuth {@link McpAuthProviders} map (remote MCP server
  * name → provider) from the agent's id and the config the SDK has on file.

package/dist/harness/harness-config.js

@@ -2,6 +2,33 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+/** Default {@link AgentConfig.autoCompactionThreshold} occupancy ratio used when a threshold is not supplied. */
+export const DEFAULT_AUTO_COMPACTION_THRESHOLD = 0.9;
+/**
+ * Every harness must honor the same effective threshold for the same config value — that is the
+ * entire premise of a threshold-only (no on/off toggle) auto-compaction contract. An unvalidated
+ * out-of-range or non-numeric input would otherwise degrade differently per harness: on
+ * Mastra/OpenAI, a `threshold >= 1` makes the SDK's own `occupancy >= threshold` check
+ * (`occupancy` is itself clamped to `[0, 1]`) effectively unreachable — silently disabling
+ * auto-compaction on those two harnesses only, reproducing exactly the per-harness-meaningless
+ * "disabled" state this design exists to avoid. `[0.01, 0.99]` mirrors the Claude harness's own
+ * independent `toAutoCompactPctOverride` clamp, so every harness converges on the same effective
+ * value for any input, valid or not.
+ */
+const AUTO_COMPACTION_THRESHOLD_MIN = 0.01;
+const AUTO_COMPACTION_THRESHOLD_MAX = 0.99;
+/**
+ * Resolves an {@link AgentConfig.autoCompactionThreshold} value to its effective threshold:
+ * defaults to {@link DEFAULT_AUTO_COMPACTION_THRESHOLD} when `threshold` is omitted or not a
+ * finite number (`NaN`, `Infinity`, `-Infinity`), then clamps the result to
+ * `[0.01, 0.99]` — see the comment above {@link AUTO_COMPACTION_THRESHOLD_MIN} for why this
+ * clamps rather than throws (a live `chat()` turn is the wrong place to fail a config mistake
+ * that was already accepted at `createAgent`/`updateAgentConfig` time).
+ */
+export function resolveAutoCompactionThreshold(threshold) {
+    const resolved = threshold === undefined || !Number.isFinite(threshold) ? DEFAULT_AUTO_COMPACTION_THRESHOLD : threshold;
+    return Math.min(AUTO_COMPACTION_THRESHOLD_MAX, Math.max(AUTO_COMPACTION_THRESHOLD_MIN, resolved));
+}
 /**
  * Converts a consumer-facing {@link AgentConfig} into a {@link HarnessAgentConfig}
  * ready for the harness layer.

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export type { ResolverResult, ResolverTiers, ToolInvocation } from './policy-res
 export type { ContextUsage, FinishReason, UsageMetadata } from './types/usage.js';
 export type { AgentHooks, HooksForAgent, ToolResultRedactor, ToolResultRedactionInput, ToolResultRedactionResult, } from './types/redaction.js';
 export type { AgentConfig, AgentStateUpdate, ConsumerMetadataMutation, HarnessAgentConfig, McpAuthProviderResolver, StreamOptions, } from './harness/harness-config.js';
-export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
+export { DEFAULT_MAX_STEPS, DEFAULT_AUTO_COMPACTION_THRESHOLD, resolveAutoCompactionThreshold, } from './harness/harness-config.js';
 export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpOAuthClientProvider, McpAuthProviders, McpServerInfo, McpServerErrorCategory, McpServerErrorDetail, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
 export { McpServerStatus, mcpServerConfigEqual } from './mcp-config.js';
 export { Model, ModelName, createClaudeModel, Models, validateMultimodalFiles, ACCEPTED_MODEL_WIRE_IDS, } from './models/index.js';

package/dist/index.js

@@ -8,7 +8,7 @@
 // `resolveToolApprovalPolicy` into their gate sites (Phase 2); consumers author
 // `AgentConfig.toolPolicies` (directly or via `definePolicy`).
 export { BUILT_IN_TOOL_POLICIES, SKILL_BRIDGE_SERVER_ID, definePolicy, matcherMatches, resolveToolApprovalPolicy, } from './policy-resolver.js';
-export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
+export { DEFAULT_MAX_STEPS, DEFAULT_AUTO_COMPACTION_THRESHOLD, resolveAutoCompactionThreshold, } from './harness/harness-config.js';
 export { McpServerStatus, mcpServerConfigEqual } from './mcp-config.js';
 export { Model, ModelName, createClaudeModel, Models, validateMultimodalFiles, ACCEPTED_MODEL_WIRE_IDS, } from './models/index.js';
 export { MimeType } from './models/index.js';

package/dist/internal/transcript-occupancy.d.ts

@@ -0,0 +1,17 @@
+import type { Message } from '../types/messages.js';
+/**
+ * Approximate characters-per-token ratio used to estimate context occupancy from raw transcript
+ * text when no live usage reading is available (cold session, or the last turn ended abnormally).
+ * A rough estimate is only ever used to decide whether to compact — the post-compaction turn's
+ * real usage reading is the source of truth.
+ */
+export declare const CHARS_PER_TOKEN = 4;
+/**
+ * Estimates the total character count of a message transcript, for use as a rough
+ * proxy for token count (via {@link CHARS_PER_TOKEN}) when no live usage reading is
+ * available. Sums plain string content directly; for structured `MessagePart[]`
+ * content, sums the text of `text` / `reasoning` parts, the serialized size of
+ * `tool-call` args and `tool-result` payloads, and the base64 payload length of
+ * `image` / `file` parts.
+ */
+export declare function estimateTranscriptChars(messages: Message[]): number;

package/dist/internal/transcript-occupancy.js

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Approximate characters-per-token ratio used to estimate context occupancy from raw transcript
+ * text when no live usage reading is available (cold session, or the last turn ended abnormally).
+ * A rough estimate is only ever used to decide whether to compact — the post-compaction turn's
+ * real usage reading is the source of truth.
+ */
+export const CHARS_PER_TOKEN = 4;
+/**
+ * Estimates the total character count of a message transcript, for use as a rough
+ * proxy for token count (via {@link CHARS_PER_TOKEN}) when no live usage reading is
+ * available. Sums plain string content directly; for structured `MessagePart[]`
+ * content, sums the text of `text` / `reasoning` parts, the serialized size of
+ * `tool-call` args and `tool-result` payloads, and the base64 payload length of
+ * `image` / `file` parts.
+ */
+export function estimateTranscriptChars(messages) {
+    let total = 0;
+    for (const message of messages) {
+        if (typeof message.content === 'string') {
+            total += message.content.length;
+        }
+        else {
+            for (const part of message.content) {
+                total += estimatePartChars(part);
+            }
+        }
+    }
+    return total;
+}
+function estimatePartChars(part) {
+    switch (part.type) {
+        case 'text':
+        case 'reasoning':
+            return part.text.length;
+        case 'tool-call':
+            return JSON.stringify(part.args).length;
+        case 'tool-result':
+            return JSON.stringify(part.result).length;
+        case 'image':
+        case 'file':
+            return part.data.length;
+    }
+}
+//# sourceMappingURL=transcript-occupancy.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.80.0",
+  "version": "0.82.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -48,24 +48,24 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.76.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.79.0",
-    "@salesforce/sfdx-agent-harness-openai": "0.45.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.78.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.81.0",
+    "@salesforce/sfdx-agent-harness-openai": "0.47.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.11",
     "@vitest/eslint-plugin": "^1.6.27",
-    "eslint": "^10.9.1",
+    "eslint": "^10.10.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-n": "^18.3.0",
     "globals": "^17.12.0",
-    "lint-staged": "^17.4.1",
+    "lint-staged": "^17.5.0",
     "prettier": "^3.9.6",
     "rimraf": "^6.1.3",
     "tsx": "^4.23.13",
     "typescript": "^7.0.2",
-    "typescript-eslint": "^8.69.0",
+    "typescript-eslint": "^8.70.0",
     "vitest": "^4.1.11"
   },
   "engines": {