@superdurable/dex-agents 0.2.0 → 0.3.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
@@ -77,7 +77,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 +90,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 +533,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 +571,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 +993,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 +1195,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

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) {

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

@@ -1 +1 @@
-{"version":3,"file":"agent-context-compaction.js","sourceRoot":"","sources":["../../src/agent-context-compaction.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAgH1D,mEAAmE;AACnE,MAAM,UAAU,yBAAyB,CACvC,MAAiD;IAEjD,OAAO,CACL,OAAO,MAAM,CAAC,mBAAmB,KAAK,UAAU;QAChD,OAAO,MAAM,CAAC,sBAAsB,KAAK,UAAU;QACnD,OAAO,MAAM,CAAC,gBAAgB,KAAK,UAAU,CAC9C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAwB;IAC9D,MAAM,mBAAmB,GAAG,MAAM,CAAC,mBAAmB,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,mBAAmB,CAAC,IAAI,mBAAmB,IAAI,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,UAAU,CAAC,2DAA2D,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,IAAI,CAAC;IACjD,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,GAAG,CAAC;IAClD,IAAI,CAAC,CAAC,aAAa,GAAG,CAAC,IAAI,aAAa,GAAG,YAAY,IAAI,YAAY,IAAI,CAAC,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,UAAU,CAAC,wDAAwD,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,mBAAmB,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,qBAAqB,CAAC,MAAgC,EAAE,oBAA4B;IAClG,OAAO,oBAAoB,IAAI,MAAM,CAAC,YAAY,GAAG,MAAM,CAAC,mBAAmB,CAAC;AAClF,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,uBAAuB,CAAC,MAAgC;IACtE,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;AACvE,CAAC"}
+{"version":3,"file":"agent-context-compaction.js","sourceRoot":"","sources":["../../src/agent-context-compaction.ts"],"names":[],"mappings":"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"}

package/dist/src/agent-session-codecs.js

@@ -12,6 +12,7 @@ const agentSessionStatuses = [
     "running_model",
     "running_tools",
     "compacting_context",
+    "failed",
 ];
 const agentMessageRoles = ["user", "assistant", "tool"];
 const toolEffects = [