@superdurable/dex-agents 0.2.0 → 0.4.0

package/README.md

@@ -27,10 +27,10 @@ Applications usually install an adapter next to this package. To build a
 runner of your own, install the core with the Dex SDK it supports:
 
 ```bash
-npm i @superdurable/dex-agents @superdurable/dex@1.35.0
+npm i @superdurable/dex-agents @superdurable/dex@1.38.0
 ```
 
-`@superdurable/dex` 1.35.0 is a peer dependency, so the application, the core,
+`@superdurable/dex` 1.38.0 is a peer dependency, so the application, the core,
 and every adapter share one copy. The Dex Registry matches Flow classes and
 RPC registrations by identity, so a second copy makes it reject the Flow
 (`steps must be a StepList`). Adapters list this package as a peer dependency
@@ -52,6 +52,7 @@ the published core. It is for tests only; it needs `DEXCLI` and
 | `@superdurable/dex-agents/stepwise` | Stepwise mode: `createStepwiseAgentSessionFlow`, `functionTool`, `ToolSource`, `ModelClient`, `ScriptedModelClient` | none |
 | `@superdurable/dex-agents/ai-sdk` | `createAiSdkModelClient` for any AI SDK `LanguageModel` | optional peer `ai@^7.0.159`, the Vercel AI SDK adapter's range |
 | `@superdurable/dex-agents/mcp` | MCP servers' tools as agent tools; see [MCP tools](#mcp-tools-superdurabledex-agentsmcp) | optional peer `@modelcontextprotocol/sdk@^1.32.2` |
+| `@superdurable/dex-agents/connectors` | Reviewed Connector operations as agent tools; see [Connector tools](#connector-tools-superdurabledex-agentsconnectors) | optional peer `@superdurable/connectors-sdk` |
 | `@superdurable/dex-agents/ui-stream` | Browser streams of live sessions; see [UI streams](#ui-streams) | none |
 | `@superdurable/dex-agents/testing` | Test engine, Worker processes, waits, and `ScriptedModelClient` (the same class as the stepwise entry point's) | none |
 
@@ -77,7 +78,7 @@ agents packages share one version line; see the
 
 ```ts
 import { Client, Registry, Worker, openBlobCache } from "@superdurable/dex";
-import { createAgentSessionFlow } from "@superdurable/dex-agents";
+import { createAgentSessionFlow, startAgentSession } from "@superdurable/dex-agents";
 
 const flow = createAgentSessionFlow(new MyFrameworkRunner(agent), "SupportAgent", {
   toolPolicies: { search_orders: { effect: "read" } },
@@ -90,7 +91,7 @@ await worker.start();
 await worker.waitPullRegistered({ timeoutMs: 10_000 });
 const client = new Client(registry, blobCache, { serverAddress: "127.0.0.1:8801" });
 
-await client.startFlow(flow, "session-42", { initialMessage: "Where is order 42?" });
+await startAgentSession(client, flow, "session-42", { initialMessage: "Where is order 42?" });
 const snapshot = await client.invokeRPC(flow.getAgentSnapshot, "session-42");
 for (const interrupt of snapshot.pendingInterrupts) {
   await client.invokeRPC(flow.resolveInterrupt, "session-42", {
@@ -533,6 +534,21 @@ it. The AI SDK UI message stream sends
 the compaction events and the summary call's `usage_recorded` as event data,
 outside the assistant message's steps.
 
+A framework adapter cannot measure or rebuild the framework's own request, so
+the core exports one shared rule. `estimateStoredInputTokens(turn,
+fixedInputTokens)` counts each stored `frameworkItem` with `estimateTextTokens`,
+three UTF-8 bytes per token, which errs high for English text.
+`selectTurnBoundaryCutoff(turn, retainedTokenBudget)` cuts only between turns,
+never inside the running turn, and returns `null` while `turn.frameworkRunState`
+is set, because a resumed call continues from that state.
+`buildContextSummaryPrompt(request)` writes the range as one plain text prompt,
+starting with `contextSummaryTranscriptHeader`, that fits `inputTokenBudget`,
+byte for byte as the Python core writes it. `CompactionPolicy.reservedInputTokens`
+adds what an adapter's estimate cannot see, such as a framework's system prompt.
+The adapters of this repository use them; see each adapter's README.
+`ContextWindowSessionScenario` from `/testing` runs the same session past a
+small context window for any adapter.
+
 ## Session settings
 
 Session settings let one Flow type serve sessions that differ, such as by
@@ -556,7 +572,7 @@ const flow = createStepwiseAgentSessionFlow(
 );
 
 validateSessionSettings({ model: "gpt-5" });
-await client.startFlow(flow, sessionId, { initialMessage: "Hello", sessionSettings: { model: "gpt-5" } });
+await startAgentSession(client, flow, sessionId, { initialMessage: "Hello", sessionSettings: { model: "gpt-5" } });
 await client.invokeRPC(flow.updateSessionSettings, sessionId, { sessionSettings: { model: "gpt-5-mini" } });
 ```
 
@@ -978,6 +994,29 @@ adapter-specific events a prefix, such as `"vercel_ai.step_finished"`. The
 writer coalesces consecutive deltas of one type for up to 100 ms or 1,024
 characters, and drops writes after the handler returns.
 
+## Finding sessions that need a person
+
+`startAgentSession` makes a session searchable by the Steps it waits in, so one query finds every session waiting
+for a person, across agents:
+
+```ts
+await startAgentSession(client, flow, "session-42", { initialMessage: "Refund order 7" });
+const waiting = await client.searchFlows('ActiveStepTypes = "AwaitToolApproval"', 50);
+```
+
+`AwaitQuestionAnswer` finds questions the same way. A session leaves the search when it moves on. `Client.startFlow`
+does not turn this on; pass `configOverride: { activeStepSearchMode: agentSessionActiveStepSearchMode }` there, or use
+`Client.updateFlowConfig` for a running session. See
+[Find sessions that need a person](https://docs.superdurable.io/agent-frameworks/deploy-agents#find-sessions).
+
+## Spend limits
+
+`ModelSpendLimit` is an application's spend limit, usually per account or API key
+across many sessions. The session asks it before each model call and reports what
+the call used. Counters and limits belong to the application. Without one, the
+session makes no checks. See the interface's documentation and
+[Spend limits](https://docs.superdurable.io/agent-frameworks/deploy-agents#spend-limits).
+
 ## Flow shape
 
 ```text
@@ -1157,7 +1196,7 @@ It needs `@modelcontextprotocol/sdk` 1.x, an optional peer dependency; the main
 entry point never imports it:
 
 ```bash
-npm i @superdurable/dex-agents @superdurable/dex@1.35.0 @modelcontextprotocol/sdk zod
+npm i @superdurable/dex-agents @superdurable/dex@1.38.0 @modelcontextprotocol/sdk zod
 ```
 
 Configure the servers on the Worker, never from Flow input, a user message, or
@@ -1361,6 +1400,104 @@ Steps; use the source there for the shared idempotency key and annotation
 handling. The OpenAI Agents SDK runs its own MCP servers inline in `RunModel`,
 so a wrapper is its only path to tool Steps.
 
+## Connector tools (`@superdurable/dex-agents/connectors`)
+
+`@superdurable/dex-agents/connectors` offers reviewed Connector operations to a
+Stepwise agent as tools. `ConnectorToolSource` implements `ToolSource`, like
+`McpToolSource`. Each call runs one operation in its own tool Step through the
+Connector SDK's `runQuery` or `runMutation`, so the connector's Call ID,
+idempotency key, credential handling, and single-dispatch fence apply. Install
+the Connector SDK, an optional peer dependency, and each Connector package the
+agent uses:
+
+```bash
+npm i @superdurable/connectors-sdk @superdurable/connector-stripe
+```
+
+The subpath needs Connector SDK 0.9.0, the first release that exports
+`throwDexRetry`, and Connector packages that export `./dex-connector.json`.
+
+```ts
+import manifest from "@superdurable/connector-stripe/dex-connector.json" with { type: "json" };
+import { CreateRefundInputSchema, newProjectConnection } from "@superdurable/connector-stripe";
+import { ConnectorToolSource, connectorTool } from "@superdurable/dex-agents/connectors";
+
+const stripe = newProjectConnection(project, "billing-stripe");
+const source = new ConnectorToolSource([
+  connectorTool(stripe.operations.createRefund(), stripe.reference, {
+    manifest,
+    inputValidator: CreateRefundInputSchema,
+    requiresApproval: (args) => Number(args["amount"]) > 5000,
+  }),
+]);
+```
+
+Nothing is exposed by default. `connectorTool` takes the package's parsed
+`dex-connector.json` and the input validator the package exports, and refuses
+an operation whose entry lacks `agent.exposed: true`, an `agent` value it does
+not know, an `agent.branches` key that is not an optional branch (or an
+`unknown` one on a Query), or an `inputSchema` keyword it cannot check. The
+tool name defaults to `<connectorId>_<operation in snake case>`; the
+description and argument schema come from the manifest. A Mutation is any
+operation with an `idempotencyKey` method.
+
+| Operation | Effect | Tool Step | Retries |
+| --- | --- | --- | --- |
+| Query | `read` | `CallTool` | The operation's Execute retry policy, at most three attempts |
+| Mutation with `agent.retry: safe` | `idempotent_write` | `CallTool` | The same |
+| Any other Mutation | `non_idempotent_write` | `CallSingleAttemptTool` | None |
+
+The source gives each call's tool Step the operation's `executeMethodTimeoutMs`
+and retry policy through `toolCallStepOptions`, a movement-scoped option. A
+session `toolPolicies` entry for a connector tool changes only its approval;
+the effect always comes from the manifest. Approval follows
+`agent.approval: recommended`; `requiresApproval` overrides it with a boolean
+or a per-call predicate over the decoded arguments, and a predicate that throws
+asks for approval.
+
+A call checks the arguments against `inputSchema`, then decodes them with the
+input validator; either failure is a `ToolExecutionError` the model reads, and
+the operation never runs. The Call ID comes from
+`deriveCallID(flowId, stepExecutionId, operation)` over
+`DeferredToolExecution.context`, the same on every attempt. The operation sees
+a `ConnectorStepContext`, which stores each heartbeat value, such as the
+fence's marker, as the tool Step's text checkpoint in the Python core's JSON
+form, so the session's heartbeats repeat it and the next attempt reads it
+back. A `RetryError` goes through `throwDexRetry`, except for a single-attempt write
+whose fence saved `notSent` or `canResend` in this attempt: that records `failed` with
+`connectorNotSentRetryLater` instead of `outcome_unknown`.
+
+| Branch | Record | The model reads |
+| --- | --- | --- |
+| A required (success) branch | `succeeded` | The value as compact JSON, keys sorted |
+| Listed `rejected` under `agent.branches` | `failed` (`ToolExecutionError`) | `<connector> <operation> returned <branch>: <kind>: <message>` |
+| `defect` | `failed` | The same text |
+| A Query branch not listed | `failed` | The same text |
+| `uncertain`, listed `unknown`, or a Mutation branch not listed | `outcome_unknown` (`ToolOutcomeUnknownError`) | `outcomeUnknownToolResult` |
+
+A result over `maxResultBytes` (default `defaultConnectorResultMaxBytes`,
+64 KiB of UTF-8 text, set per source or per tool) is cut, followed by
+`connectorResultTruncatedNote`, and `AgentToolCall.truncatedOutputBytes` holds
+the full size.
+
+Writes are ordered: the source marks every connector write
+`DeferredToolCall.ordered`, so the writes of one model response run one at a
+time in the model's order while reads run in parallel. `RunModel` starts the
+next queued write (`AgentToolCall.writeQueued`) before any model call and raises
+its approval only then. Once a write is not `succeeded`, the response's later
+writes record `failed` with `skipped: true` and the error
+`` `${toolCallNotRunErrorPrefix}: ${toolCallSkippedAfterWriteDetail}` ``.
+Steering and `cancel_turn` cancel queued writes as they cancel unstarted calls.
+
+The Vercel AI, OpenAI Agents, and Mastra adapters take tool sources, such as
+`ConnectorToolSource`, in their own `toolSources` option; see each adapter's
+README. An adapter serves them through `ToolSourceRouter`, exported from the
+package root: it lists the sources in each `RunModel`, refuses name
+collisions, lets the source build each deferred call, so the effect, the
+approval, and the write order come from the source, and routes the tool Step,
+its Step options, and polls back to that source. The Stepwise runner uses it
+too.
+
 ## UI streams
 
 `@superdurable/dex-agents/ui-stream` lets a browser render a live session

package/dist/src/agent-context-compaction.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEventWriter, AgentFrameworkRunner, DeferredToolOutcome, ModelCallMetadata } from "./agent-framework-runner.js";
+import type { AgentEventWriter, AgentFrameworkRunner, AgentTurnContext, DeferredToolOutcome, ModelCallMetadata } from "./agent-framework-runner.js";
 import type { AgentMessage, AgentUsage, ContextSummary, SessionSettings } from "./agent-session-values.js";
 /**
  * When a session summarizes its earlier messages so the model input stays under the context window, passed
@@ -27,6 +27,13 @@ export interface CompactionPolicy {
     readonly triggerRatio?: number;
     /** Share of the window that the newest messages may keep unsummarized. Defaults to 0.3. */
     readonly retainedRatio?: number;
+    /**
+     * Tokens of every model input that the runner's estimate cannot see, such as a system prompt that a
+     * framework builds, a dynamic instruction, or tools listed at run time. The session adds them to the
+     * estimate. Defaults to 0.
+     * @since 0.3.0
+     */
+    readonly reservedInputTokens?: number;
 }
 /** A {@link CompactionPolicy} with every default filled in. */
 export interface ResolvedCompactionPolicy {
@@ -36,7 +43,143 @@ export interface ResolvedCompactionPolicy {
     readonly triggerRatio: number;
     /** Share of the window that the newest messages may keep. */
     readonly retainedRatio: number;
+    /**
+     * Tokens added to every estimate. `undefined` reads as 0.
+     * @since 0.3.0
+     */
+    readonly reservedInputTokens?: number;
 }
+/** First line of the user text that carries the {@link ContextSummary} into the model input. */
+export declare const contextSummaryNoteHeader = "[Dex] Summary of the earlier conversation:";
+/** Instructions of the model call that writes a {@link ContextSummary}. */
+export declare const contextSummaryInstructions: string;
+/** Last user text of the model call that writes a {@link ContextSummary}. */
+export declare const contextSummaryRequest = "[Dex] Summarize the conversation above. Reply with the summary only.";
+/**
+ * First line of the transcript in the prompt of {@link buildContextSummaryPrompt}.
+ * @since 0.3.0
+ */
+export declare const contextSummaryTranscriptHeader = "[Dex] The conversation to summarize:";
+/**
+ * The most tokens {@link buildContextSummaryPrompt} leaves free for the summary it asks for.
+ * @since 0.3.0
+ */
+export declare const contextSummaryOutputTokens = 4096;
+/**
+ * Returns the user text that says how many of the oldest messages a summary request left out.
+ * @param omittedCount - Messages left out, at least 1.
+ * @returns `[Dex] <omittedCount> earlier messages did not fit in this request and are left out.`, or
+ * `[Dex] 1 earlier message did not fit in this request and is left out.` for one message.
+ */
+export declare function buildContextSummaryOmissionNote(omittedCount: number): string;
+/**
+ * Returns the user text that puts a summary before the newer messages in a model input.
+ * @param summary - The session's summary.
+ * @returns {@link contextSummaryNoteHeader}, a newline, and the summary text.
+ */
+export declare function buildContextSummaryNote(summary: ContextSummary): string;
+/**
+ * Estimates the tokens of a text without a tokenizer, rounding up.
+ *
+ * Use it where a framework assembles the prompt and offers no token counter. It counts one token per three UTF-8
+ * bytes. That is more than a provider counts for English text, and about one token per CJK character, so the
+ * estimate errs toward compacting early.
+ *
+ * @example
+ * ```ts
+ * estimateTextTokens("twelve bytes"); // 4
+ * ```
+ * @param text - The text to measure.
+ * @returns The estimated tokens; 0 for an empty text.
+ * @since 0.3.0
+ */
+export declare function estimateTextTokens(text: string): number;
+/**
+ * Estimates a model input that a framework builds from the stored items.
+ *
+ * Call it from `estimateInputTokens` of a framework adapter. It measures each `frameworkItem` as stored, so JSON
+ * syntax and opaque provider items count too, plus the summary and any `frameworkRunState`.
+ *
+ * @example
+ * ```ts
+ * public estimateInputTokens(turn: AgentTurnContext): number {
+ *   return estimateStoredInputTokens(turn, estimateTextTokens(this.instructions));
+ * }
+ * ```
+ * @param turn - The context of the next model call.
+ * @param fixedInputTokens - Tokens of what every request repeats, such as instructions and tool definitions.
+ * Measure what the framework shows; `CompactionPolicy.reservedInputTokens` covers the rest. Defaults to 0.
+ * @returns The estimated input tokens.
+ * @since 0.3.0
+ */
+export declare function estimateStoredInputTokens(turn: AgentTurnContext, fixedInputTokens?: number): number;
+/**
+ * Chooses the last message to summarize, cutting only between turns.
+ *
+ * Call it from `selectCompactionCutoff` of a framework adapter. A turn's messages are stored together, so a cut
+ * between turns never separates a tool call from its result and never splits a model response, whatever
+ * framework items the turn holds. The running turn is always kept, because the adapter reads its opening user
+ * message from `turn.messages`.
+ *
+ * It returns `null` while `turn.frameworkRunState` is set. A resumed model call continues from that value, which
+ * may already hold the older messages, so the summary could not replace them. Compaction waits for the next turn.
+ *
+ * @example
+ * ```ts
+ * public selectCompactionCutoff(turn: AgentTurnContext, retainedTokenBudget: number): number | null {
+ *   return selectTurnBoundaryCutoff(turn, retainedTokenBudget);
+ * }
+ * ```
+ * @param turn - The context of the model call that crossed the threshold.
+ * @param retainedTokenBudget - Tokens that the kept messages may use.
+ * @returns The sequence of the last message to summarize: the earliest turn boundary whose kept messages fit the
+ * budget, else the boundary before the running turn. `null` when the turn is resuming, every message already
+ * fits, or no earlier turn is left to summarize.
+ * @since 0.3.0
+ */
+export declare function selectTurnBoundaryCutoff(turn: AgentTurnContext, retainedTokenBudget: number): number | null;
+/**
+ * Returns a stored message as the plain text a summary prompt shows.
+ *
+ * Wrap it in the `describeMessage` of {@link buildContextSummaryPrompt} to leave out items that only a provider can
+ * read.
+ *
+ * @param message - The stored message.
+ * @returns Its role and text, tool arguments, and tool output. A message with none of them returns its role and
+ * `frameworkItem`, such as a model response with several tool calls.
+ * @since 0.3.0
+ */
+export declare function describeStoredMessage(message: AgentMessage): string;
+/**
+ * Builds the one user prompt of a summary call for a framework adapter.
+ *
+ * Call it from `summarizeContext` and send the result with {@link contextSummaryInstructions} and no tools. The
+ * prompt holds the previous summary, the messages as plain text, and {@link contextSummaryRequest}. Plain text
+ * works with any framework: it needs no tool definitions, and no provider sees an item out of its place.
+ *
+ * The prompt fits `request.inputTokenBudget`, less room for the summary, as {@link estimateTextTokens} counts.
+ * When the range is too large, it leaves out the oldest messages and says so with
+ * {@link buildContextSummaryOmissionNote}. It shortens a single message only when that message alone is too
+ * large.
+ *
+ * @example
+ * ```ts
+ * public async summarizeContext(request: ContextSummaryRequest): Promise<ContextSummaryResult> {
+ *   const result = await generateText({
+ *     model,
+ *     system: contextSummaryInstructions,
+ *     prompt: buildContextSummaryPrompt(request),
+ *   });
+ *   return { text: result.text, usage: toAgentUsage(result.usage) };
+ * }
+ * ```
+ * @param request - The previous summary and the messages to summarize.
+ * @param describeMessage - Returns a message's text for the prompt, or `null` to leave it out, such as an
+ * encrypted reasoning item. Defaults to {@link describeStoredMessage}.
+ * @returns The prompt text.
+ * @since 0.3.0
+ */
+export declare function buildContextSummaryPrompt(request: ContextSummaryRequest, describeMessage?: (message: AgentMessage) => string | null): string;
 /** What {@link AgentFrameworkRunner.summarizeContext} receives: the messages to fold into a new summary. */
 export interface ContextSummaryRequest {
     /** Flow ID, which is the session ID. */
@@ -98,11 +241,14 @@ export type ContextCompactionRunner = AgentFrameworkRunner<DeferredToolOutcome>
 export declare function isContextCompactionRunner(runner: AgentFrameworkRunner<DeferredToolOutcome>): runner is ContextCompactionRunner;
 /**
  * Fills in a compaction policy's defaults and checks it.
- * @throws {RangeError} When `contextWindowTokens` is not a positive integer, or unless
- * `0 < retainedRatio < triggerRatio <= 1`.
+ * @throws {RangeError} When `contextWindowTokens` is not a positive integer, `reservedInputTokens` is not an
+ * integer from 0 to below the window, or unless `0 < retainedRatio < triggerRatio <= 1`.
  */
 export declare function resolveCompactionPolicy(policy: CompactionPolicy): ResolvedCompactionPolicy;
-/** Reports whether a model input of this size makes the session compact before the model call. */
+/**
+ * Reports whether a model input of this size makes the session compact before the model call: the estimate
+ * plus `reservedInputTokens` reaches `triggerRatio` of the window.
+ */
 export declare function isCompactionTriggered(policy: ResolvedCompactionPolicy, estimatedInputTokens: number): boolean;
 /** Tokens that the newest messages may keep after compaction: the retained share of the window, rounded down. */
 export declare function readRetainedTokenBudget(policy: ResolvedCompactionPolicy): number;

package/dist/src/agent-context-compaction.js

@@ -5,6 +5,245 @@
 // See the LICENSE file in the repository root.
 //
 // SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+/** First line of the user text that carries the {@link ContextSummary} into the model input. */
+export const contextSummaryNoteHeader = "[Dex] Summary of the earlier conversation:";
+/** Instructions of the model call that writes a {@link ContextSummary}. */
+export const contextSummaryInstructions = "You summarize the earlier part of an agent conversation. The agent continues from your " +
+    "summary and the messages after it, so keep every fact, decision, user request and " +
+    "preference, open task, and tool result that it still needs, including what an earlier " +
+    "summary says. Write plain text.";
+/** Last user text of the model call that writes a {@link ContextSummary}. */
+export const contextSummaryRequest = "[Dex] Summarize the conversation above. Reply with the summary only.";
+/**
+ * First line of the transcript in the prompt of {@link buildContextSummaryPrompt}.
+ * @since 0.3.0
+ */
+export const contextSummaryTranscriptHeader = "[Dex] The conversation to summarize:";
+/**
+ * The most tokens {@link buildContextSummaryPrompt} leaves free for the summary it asks for.
+ * @since 0.3.0
+ */
+export const contextSummaryOutputTokens = 4096;
+// Bytes per estimated token. Below the 4 of English text, and 1 token per CJK character.
+const estimatedBytesPerToken = 3;
+const textEncoder = new TextEncoder();
+/**
+ * Returns the user text that says how many of the oldest messages a summary request left out.
+ * @param omittedCount - Messages left out, at least 1.
+ * @returns `[Dex] <omittedCount> earlier messages did not fit in this request and are left out.`, or
+ * `[Dex] 1 earlier message did not fit in this request and is left out.` for one message.
+ */
+export function buildContextSummaryOmissionNote(omittedCount) {
+    if (omittedCount === 1) {
+        return "[Dex] 1 earlier message did not fit in this request and is left out.";
+    }
+    return `[Dex] ${omittedCount} earlier messages did not fit in this request and are left out.`;
+}
+/**
+ * Returns the user text that puts a summary before the newer messages in a model input.
+ * @param summary - The session's summary.
+ * @returns {@link contextSummaryNoteHeader}, a newline, and the summary text.
+ */
+export function buildContextSummaryNote(summary) {
+    return `${contextSummaryNoteHeader}\n${summary.text}`;
+}
+/**
+ * Estimates the tokens of a text without a tokenizer, rounding up.
+ *
+ * Use it where a framework assembles the prompt and offers no token counter. It counts one token per three UTF-8
+ * bytes. That is more than a provider counts for English text, and about one token per CJK character, so the
+ * estimate errs toward compacting early.
+ *
+ * @example
+ * ```ts
+ * estimateTextTokens("twelve bytes"); // 4
+ * ```
+ * @param text - The text to measure.
+ * @returns The estimated tokens; 0 for an empty text.
+ * @since 0.3.0
+ */
+export function estimateTextTokens(text) {
+    return Math.ceil(textEncoder.encode(text).length / estimatedBytesPerToken);
+}
+/**
+ * Estimates a model input that a framework builds from the stored items.
+ *
+ * Call it from `estimateInputTokens` of a framework adapter. It measures each `frameworkItem` as stored, so JSON
+ * syntax and opaque provider items count too, plus the summary and any `frameworkRunState`.
+ *
+ * @example
+ * ```ts
+ * public estimateInputTokens(turn: AgentTurnContext): number {
+ *   return estimateStoredInputTokens(turn, estimateTextTokens(this.instructions));
+ * }
+ * ```
+ * @param turn - The context of the next model call.
+ * @param fixedInputTokens - Tokens of what every request repeats, such as instructions and tool definitions.
+ * Measure what the framework shows; `CompactionPolicy.reservedInputTokens` covers the rest. Defaults to 0.
+ * @returns The estimated input tokens.
+ * @since 0.3.0
+ */
+export function estimateStoredInputTokens(turn, fixedInputTokens = 0) {
+    let tokens = fixedInputTokens;
+    for (const message of turn.messages) {
+        tokens += estimateTextTokens(message.frameworkItem);
+    }
+    if (turn.contextSummary) {
+        tokens += estimateTextTokens(buildContextSummaryNote(turn.contextSummary));
+    }
+    if (turn.frameworkRunState !== null) {
+        tokens += estimateTextTokens(turn.frameworkRunState);
+    }
+    return tokens;
+}
+/**
+ * Chooses the last message to summarize, cutting only between turns.
+ *
+ * Call it from `selectCompactionCutoff` of a framework adapter. A turn's messages are stored together, so a cut
+ * between turns never separates a tool call from its result and never splits a model response, whatever
+ * framework items the turn holds. The running turn is always kept, because the adapter reads its opening user
+ * message from `turn.messages`.
+ *
+ * It returns `null` while `turn.frameworkRunState` is set. A resumed model call continues from that value, which
+ * may already hold the older messages, so the summary could not replace them. Compaction waits for the next turn.
+ *
+ * @example
+ * ```ts
+ * public selectCompactionCutoff(turn: AgentTurnContext, retainedTokenBudget: number): number | null {
+ *   return selectTurnBoundaryCutoff(turn, retainedTokenBudget);
+ * }
+ * ```
+ * @param turn - The context of the model call that crossed the threshold.
+ * @param retainedTokenBudget - Tokens that the kept messages may use.
+ * @returns The sequence of the last message to summarize: the earliest turn boundary whose kept messages fit the
+ * budget, else the boundary before the running turn. `null` when the turn is resuming, every message already
+ * fits, or no earlier turn is left to summarize.
+ * @since 0.3.0
+ */
+export function selectTurnBoundaryCutoff(turn, retainedTokenBudget) {
+    if (turn.frameworkRunState !== null) {
+        return null;
+    }
+    const messages = turn.messages;
+    const foundRunningTurnIndex = messages.findIndex((message) => message.turnId === turn.turnId);
+    const runningTurnIndex = foundRunningTurnIndex === -1 ? messages.length : foundRunningTurnIndex;
+    const cuts = [];
+    for (let index = 1; index < Math.min(runningTurnIndex + 1, messages.length); index += 1) {
+        if (messages[index]?.turnId !== messages[index - 1]?.turnId) {
+            cuts.push(index);
+        }
+    }
+    if (cuts.length === 0) {
+        return null;
+    }
+    const keptTokens = new Array(messages.length + 1).fill(0);
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        keptTokens[index] = (keptTokens[index + 1] ?? 0) + estimateTextTokens(messages[index]?.frameworkItem ?? "");
+    }
+    if ((keptTokens[0] ?? 0) <= retainedTokenBudget) {
+        return null;
+    }
+    const cut = cuts.find((candidate) => (keptTokens[candidate] ?? 0) <= retainedTokenBudget) ?? cuts.at(-1);
+    return cut === undefined ? null : (messages[cut - 1]?.sequence ?? null);
+}
+/**
+ * Returns a stored message as the plain text a summary prompt shows.
+ *
+ * Wrap it in the `describeMessage` of {@link buildContextSummaryPrompt} to leave out items that only a provider can
+ * read.
+ *
+ * @param message - The stored message.
+ * @returns Its role and text, tool arguments, and tool output. A message with none of them returns its role and
+ * `frameworkItem`, such as a model response with several tool calls.
+ * @since 0.3.0
+ */
+export function describeStoredMessage(message) {
+    const lines = [];
+    if (message.text) {
+        lines.push(`${message.role}: ${message.text}`);
+    }
+    if (message.toolArguments !== null) {
+        lines.push(`tool call ${message.toolName ?? ""}: ${message.toolArguments}`);
+    }
+    if (message.toolOutput !== null) {
+        lines.push(`tool result ${message.toolName ?? ""}: ${message.toolOutput}`);
+    }
+    return lines.length > 0 ? lines.join("\n") : `${message.role}: ${message.frameworkItem}`;
+}
+/**
+ * Builds the one user prompt of a summary call for a framework adapter.
+ *
+ * Call it from `summarizeContext` and send the result with {@link contextSummaryInstructions} and no tools. The
+ * prompt holds the previous summary, the messages as plain text, and {@link contextSummaryRequest}. Plain text
+ * works with any framework: it needs no tool definitions, and no provider sees an item out of its place.
+ *
+ * The prompt fits `request.inputTokenBudget`, less room for the summary, as {@link estimateTextTokens} counts.
+ * When the range is too large, it leaves out the oldest messages and says so with
+ * {@link buildContextSummaryOmissionNote}. It shortens a single message only when that message alone is too
+ * large.
+ *
+ * @example
+ * ```ts
+ * public async summarizeContext(request: ContextSummaryRequest): Promise<ContextSummaryResult> {
+ *   const result = await generateText({
+ *     model,
+ *     system: contextSummaryInstructions,
+ *     prompt: buildContextSummaryPrompt(request),
+ *   });
+ *   return { text: result.text, usage: toAgentUsage(result.usage) };
+ * }
+ * ```
+ * @param request - The previous summary and the messages to summarize.
+ * @param describeMessage - Returns a message's text for the prompt, or `null` to leave it out, such as an
+ * encrypted reasoning item. Defaults to {@link describeStoredMessage}.
+ * @returns The prompt text.
+ * @since 0.3.0
+ */
+export function buildContextSummaryPrompt(request, describeMessage = describeStoredMessage) {
+    const opening = request.previousSummary === null ? [] : [buildContextSummaryNote(request.previousSummary)];
+    const closing = [contextSummaryTranscriptHeader, contextSummaryRequest];
+    const descriptions = request.messages.flatMap((message) => {
+        const description = describeMessage(message);
+        return description === null ? [] : [description];
+    });
+    let remainingTokens;
+    if (request.inputTokenBudget !== undefined) {
+        const fixedTokens = estimateTextTokens([contextSummaryInstructions, ...opening, ...closing].join("\n\n"));
+        const roomForTranscript = request.inputTokenBudget - fixedTokens;
+        remainingTokens =
+            roomForTranscript - Math.min(contextSummaryOutputTokens, Math.floor(Math.max(roomForTranscript, 0) / 4));
+    }
+    const kept = [];
+    for (const description of [...descriptions].reverse()) {
+        if (remainingTokens === undefined) {
+            kept.push(description);
+            continue;
+        }
+        // Two newlines separate messages; they count toward the estimate.
+        const tokens = estimateTextTokens(`${description}\n\n`);
+        if (tokens <= remainingTokens) {
+            kept.push(description);
+            remainingTokens -= tokens;
+            continue;
+        }
+        if (kept.length === 0 && remainingTokens > 0) {
+            kept.push(shortenToTokens(description, remainingTokens));
+        }
+        break;
+    }
+    kept.reverse();
+    const omittedCount = descriptions.length - kept.length;
+    if (omittedCount > 0) {
+        opening.push(buildContextSummaryOmissionNote(omittedCount));
+    }
+    return [...opening, contextSummaryTranscriptHeader, ...kept, contextSummaryRequest].join("\n\n");
+}
+function shortenToTokens(text, tokens) {
+    const marker = "[Dex] The rest of this message is left out.";
+    const keptBytes = Math.max(tokens - estimateTextTokens(marker) - 1, 0) * estimatedBytesPerToken;
+    const kept = new TextDecoder().decode(textEncoder.encode(text).slice(0, keptBytes)).replace(/\uFFFD$/u, "");
+    return `${kept}\n${marker}`;
+}
 /** Reports whether a runner implements every compaction method. */
 export function isContextCompactionRunner(runner) {
     return (typeof runner.estimateInputTokens === "function" &&
@@ -13,8 +252,8 @@ export function isContextCompactionRunner(runner) {
 }
 /**
  * Fills in a compaction policy's defaults and checks it.
- * @throws {RangeError} When `contextWindowTokens` is not a positive integer, or unless
- * `0 < retainedRatio < triggerRatio <= 1`.
+ * @throws {RangeError} When `contextWindowTokens` is not a positive integer, `reservedInputTokens` is not an
+ * integer from 0 to below the window, or unless `0 < retainedRatio < triggerRatio <= 1`.
  */
 export function resolveCompactionPolicy(policy) {
     const contextWindowTokens = policy.contextWindowTokens;
@@ -26,11 +265,20 @@ export function resolveCompactionPolicy(policy) {
     if (!(retainedRatio > 0 && retainedRatio < triggerRatio && triggerRatio <= 1)) {
         throw new RangeError("compaction needs 0 < retainedRatio < triggerRatio <= 1");
     }
-    return Object.freeze({ contextWindowTokens, triggerRatio, retainedRatio });
+    const reservedInputTokens = policy.reservedInputTokens ?? 0;
+    const isReservationValid = Number.isSafeInteger(reservedInputTokens) && reservedInputTokens >= 0 && reservedInputTokens < contextWindowTokens;
+    if (!isReservationValid) {
+        throw new RangeError("compaction.reservedInputTokens must be an integer from 0 to below contextWindowTokens");
+    }
+    return Object.freeze({ contextWindowTokens, triggerRatio, retainedRatio, reservedInputTokens });
 }
-/** Reports whether a model input of this size makes the session compact before the model call. */
+/**
+ * Reports whether a model input of this size makes the session compact before the model call: the estimate
+ * plus `reservedInputTokens` reaches `triggerRatio` of the window.
+ */
 export function isCompactionTriggered(policy, estimatedInputTokens) {
-    return estimatedInputTokens >= policy.triggerRatio * policy.contextWindowTokens;
+    const estimatedTokens = estimatedInputTokens + (policy.reservedInputTokens ?? 0);
+    return estimatedTokens >= policy.triggerRatio * policy.contextWindowTokens;
 }
 /** Tokens that the newest messages may keep after compaction: the retained share of the window, rounded down. */
 export function readRetainedTokenBudget(policy) {