@superdurable/dex-agents 0.1.0 → 0.3.0

package/dist/src/agent-built-in-tools.d.ts

@@ -0,0 +1,81 @@
+import type { AgentPlanTask } from "./agent-session-values.js";
+/**
+ * Name of a built-in tool that the session itself handles.
+ *
+ * - `ask_user`: asks the user a question. The session raises a `question` interrupt, waits in
+ *   `AwaitQuestionAnswer`, and the answer becomes the tool result, so the model continues the same turn.
+ * - `durable_wait`: suspends the turn on a Dex Timer in `AwaitTimer`. No model call, coroutine, or
+ *   Worker holds the wait.
+ * - `write_todos`: replaces the session's {@link AgentPlan} with a new revision. `RunModel` records the
+ *   call in its own commit; no tool Step runs.
+ *
+ * Enable built-in tools with {@link AgentSessionOptions.builtInTools}. A runner offers the enabled ones
+ * to its model, from {@link builtInToolDefinitions}, like any other tool, and returns their calls in
+ * {@link ToolCallsRequested} like any other call. The session routes a call whose name is an enabled
+ * built-in tool to that tool's handling instead of a tool Step. An enabled built-in name is reserved.
+ * A disabled built-in name is an ordinary tool name.
+ */
+export type BuiltInTool = "ask_user" | "durable_wait" | "write_todos";
+/** Model-visible definition of one built-in tool, from {@link builtInToolDefinitions}. */
+export interface BuiltInToolDefinition {
+    /** Tool name as the model calls it. */
+    readonly name: BuiltInTool;
+    /** Tool description for the model; the same text as the Python core. */
+    readonly description: string;
+    /** JSON Schema of the tool arguments; the same schema as the Python core. */
+    readonly parameters: Readonly<Record<string, unknown>>;
+}
+/**
+ * Definitions of every built-in tool, with the same names, descriptions, and JSON Schemas as the Python
+ * core's `BUILT_IN_TOOL_DEFINITIONS`.
+ *
+ * A runner offers the definitions of {@link AgentTurnContext.enabledBuiltInTools} to its model. Adapters
+ * register them as tools without an implementation, which every adapter already does for deferred
+ * application tools.
+ *
+ * @example
+ * ```ts
+ * const offeredBuiltInTools = builtInToolDefinitions.filter((definition) =>
+ *   turn.enabledBuiltInTools?.has(definition.name) === true);
+ * ```
+ */
+export declare const builtInToolDefinitions: readonly BuiltInToolDefinition[];
+/** Every built-in tool name, in definition order. */
+export declare const builtInToolNames: readonly BuiltInTool[];
+/** Parsed arguments of an `ask_user` call. */
+export interface AskUserArguments {
+    readonly question: string;
+    readonly choices: readonly string[];
+    readonly allowsFreeText: boolean;
+}
+/** Parsed arguments of a `durable_wait` call. */
+export interface DurableWaitArguments {
+    readonly durationSeconds: number;
+    readonly reason: string;
+}
+/** Error of every `write_todos` call of a model response that has more than one; the same text as the Python core. */
+export declare const writeTodosCalledMoreThanOnce = "write_todos was called more than once in one response";
+/** Result of validating a built-in call's arguments: the parsed arguments or the model-visible error. */
+export type BuiltInArgumentsValidation<Arguments> = {
+    readonly isValid: true;
+    readonly arguments: Arguments;
+} | {
+    readonly isValid: false;
+    readonly error: string;
+};
+/** Reports whether text is empty or only whitespace, as Python's `not text.strip()` does. */
+export declare function isBlankText(text: string): boolean;
+export declare function isBuiltInTool(name: string): name is BuiltInTool;
+export declare function validateAskUserArguments(argumentsText: string): BuiltInArgumentsValidation<AskUserArguments>;
+/** A JSON number without a fraction, such as `2.0`, counts as an integer, as JSON Schema defines it. */
+export declare function validateDurableWaitArguments(argumentsText: string, maxDurableWaitSeconds: number): BuiltInArgumentsValidation<DurableWaitArguments>;
+/** Validates `write_todos` arguments; the error is `invalid todos: <reason>`, as in the Python core. */
+export declare function validateWriteTodosArguments(argumentsText: string): BuiltInArgumentsValidation<readonly AgentPlanTask[]>;
+/** Tool output after `write_todos` wrote tasks: `{"status":"updated","revision":<n>,"task_count":<k>}`. */
+export declare function buildPlanUpdatedOutput(revision: number, taskCount: number): string;
+/** Tool output after `write_todos` cleared the plan: `{"status":"cleared","revision":<n>}`. */
+export declare function buildPlanClearedOutput(revision: number): string;
+/** Tool output after the user answered `ask_user`: `{"status":"answered","answer":"<answer>"}`. */
+export declare function buildQuestionAnsweredOutput(answer: string): string;
+/** Tool output after a `durable_wait` Timer ended: `{"status":"completed","waited_seconds":<n>,"reason":"<reason>"}`. */
+export declare function buildDurableWaitCompletedOutput(waitedSeconds: number, reason: string): string;

package/dist/src/agent-built-in-tools.js

@@ -0,0 +1,246 @@
+// Copyright (c) 2026 Super Durable, Inc.
+//
+// Licensed under the Sustainable Use License 1.0.
+// You may not use this file except in compliance with the License.
+// See the LICENSE file in the repository root.
+//
+// SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+/**
+ * Definitions of every built-in tool, with the same names, descriptions, and JSON Schemas as the Python
+ * core's `BUILT_IN_TOOL_DEFINITIONS`.
+ *
+ * A runner offers the definitions of {@link AgentTurnContext.enabledBuiltInTools} to its model. Adapters
+ * register them as tools without an implementation, which every adapter already does for deferred
+ * application tools.
+ *
+ * @example
+ * ```ts
+ * const offeredBuiltInTools = builtInToolDefinitions.filter((definition) =>
+ *   turn.enabledBuiltInTools?.has(definition.name) === true);
+ * ```
+ */
+export const builtInToolDefinitions = Object.freeze([
+    Object.freeze({
+        name: "ask_user",
+        description: "Ask the user one question and wait for the answer, which becomes this tool's result. Use it only " +
+            "when you cannot continue without information or a decision from the user. The wait can last hours " +
+            "or days.",
+        parameters: Object.freeze({
+            type: "object",
+            properties: {
+                question: { type: "string", description: "One concise question for the user." },
+                choices: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Answers the user can pick. Omit for a free-text answer.",
+                },
+                allows_free_text: {
+                    type: "boolean",
+                    description: "Whether the user may answer with text that is not one of the choices. Defaults to true.",
+                },
+            },
+            required: ["question"],
+            additionalProperties: false,
+        }),
+    }),
+    Object.freeze({
+        name: "durable_wait",
+        description: "Pause this turn for a number of whole seconds, then continue. Nothing runs during the wait. Use it " +
+            "to wait for something outside the conversation, such as a job that needs time to finish.",
+        parameters: Object.freeze({
+            type: "object",
+            properties: {
+                duration_seconds: { type: "integer", minimum: 1, description: "Whole seconds to wait." },
+                reason: { type: "string", description: "Why the turn waits, shown to the user." },
+            },
+            required: ["duration_seconds", "reason"],
+            additionalProperties: false,
+        }),
+    }),
+    Object.freeze({
+        name: "write_todos",
+        description: "Replace the plan with a complete, ordered list of tasks. Send every task each time, with its " +
+            "status. An empty list clears the plan. Keep the statuses current: mark a task in_progress when you " +
+            "start it and completed when it is done.",
+        parameters: Object.freeze({
+            type: "object",
+            properties: {
+                todos: {
+                    type: "array",
+                    description: "Every task of the plan, in order.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            content: { type: "string", description: "What the task does, in one short sentence." },
+                            status: {
+                                type: "string",
+                                enum: ["pending", "in_progress", "completed"],
+                                description: "Where the task stands.",
+                            },
+                        },
+                        required: ["content", "status"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["todos"],
+            additionalProperties: false,
+        }),
+    }),
+]);
+/** Every built-in tool name, in definition order. */
+export const builtInToolNames = Object.freeze(builtInToolDefinitions.map((definition) => definition.name));
+/** Error of every `write_todos` call of a model response that has more than one; the same text as the Python core. */
+export const writeTodosCalledMoreThanOnce = "write_todos was called more than once in one response";
+const planTaskStatuses = ["pending", "in_progress", "completed"];
+// The characters Python's str.isspace() accepts, so blank checks match the Python core exactly.
+const pythonWhitespaceOnly = /^[\t\n\v\f\r\x1c-\x1f \x85\xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]*$/u;
+/** Reports whether text is empty or only whitespace, as Python's `not text.strip()` does. */
+export function isBlankText(text) {
+    return pythonWhitespaceOnly.test(text);
+}
+export function isBuiltInTool(name) {
+    return builtInToolNames.includes(name);
+}
+export function validateAskUserArguments(argumentsText) {
+    const parsed = parseArgumentsObject("ask_user", argumentsText);
+    if (!parsed.isValid) {
+        return parsed;
+    }
+    const record = parsed.arguments;
+    const question = record["question"];
+    if (typeof question !== "string" || isBlankText(question)) {
+        return invalidArguments("ask_user", "question must be a non-empty string");
+    }
+    const choices = record["choices"] ?? [];
+    if (!Array.isArray(choices) || !choices.every((choice) => typeof choice === "string" && !isBlankText(choice))) {
+        return invalidArguments("ask_user", "choices must be a list of non-empty strings");
+    }
+    const allowsFreeText = record["allows_free_text"] ?? true;
+    if (typeof allowsFreeText !== "boolean") {
+        return invalidArguments("ask_user", "allows_free_text must be a boolean");
+    }
+    return {
+        isValid: true,
+        arguments: { question, choices: choices, allowsFreeText: allowsFreeText || choices.length === 0 },
+    };
+}
+/** A JSON number without a fraction, such as `2.0`, counts as an integer, as JSON Schema defines it. */
+export function validateDurableWaitArguments(argumentsText, maxDurableWaitSeconds) {
+    const parsed = parseArgumentsObject("durable_wait", argumentsText);
+    if (!parsed.isValid) {
+        return parsed;
+    }
+    const record = parsed.arguments;
+    const durationSeconds = record["duration_seconds"];
+    if (typeof durationSeconds !== "number" || !Number.isInteger(durationSeconds)) {
+        return invalidArguments("durable_wait", "duration_seconds must be an integer");
+    }
+    if (durationSeconds < 1 || durationSeconds > maxDurableWaitSeconds) {
+        return invalidArguments("durable_wait", `duration_seconds must be between 1 and ${maxDurableWaitSeconds}`);
+    }
+    const reason = record["reason"];
+    if (typeof reason !== "string") {
+        return invalidArguments("durable_wait", "reason must be a string");
+    }
+    return { isValid: true, arguments: { durationSeconds, reason } };
+}
+/** Validates `write_todos` arguments; the error is `invalid todos: <reason>`, as in the Python core. */
+export function validateWriteTodosArguments(argumentsText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(argumentsText);
+    }
+    catch {
+        return invalidTodos("arguments must be a JSON object");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return invalidTodos("arguments must be a JSON object");
+    }
+    const [unknownName] = sortByCodePoint(Object.keys(parsed).filter((name) => name !== "todos"));
+    if (unknownName !== undefined) {
+        return invalidTodos(`unknown argument ${unknownName}`);
+    }
+    const todos = parsed["todos"];
+    if (!Array.isArray(todos)) {
+        return invalidTodos("todos must be a list");
+    }
+    const tasks = [];
+    for (const [index, todo] of todos.entries()) {
+        if (typeof todo !== "object" || todo === null || Array.isArray(todo)) {
+            return invalidTodos(`todos[${index}] must be an object`);
+        }
+        const [unknownField] = sortByCodePoint(Object.keys(todo).filter((name) => name !== "content" && name !== "status"));
+        if (unknownField !== undefined) {
+            return invalidTodos(`todos[${index}] has unknown field ${unknownField}`);
+        }
+        const { content, status } = todo;
+        if (typeof content !== "string" || isBlankText(content)) {
+            return invalidTodos(`todos[${index}].content must be a non-empty string`);
+        }
+        if (typeof status !== "string" || !planTaskStatuses.includes(status)) {
+            return invalidTodos(`todos[${index}].status must be pending, in_progress, or completed`);
+        }
+        tasks.push({ content, status: status });
+    }
+    return { isValid: true, arguments: tasks };
+}
+/** Tool output after `write_todos` wrote tasks: `{"status":"updated","revision":<n>,"task_count":<k>}`. */
+export function buildPlanUpdatedOutput(revision, taskCount) {
+    return JSON.stringify({ status: "updated", revision, task_count: taskCount });
+}
+/** Tool output after `write_todos` cleared the plan: `{"status":"cleared","revision":<n>}`. */
+export function buildPlanClearedOutput(revision) {
+    return JSON.stringify({ status: "cleared", revision });
+}
+/** Tool output after the user answered `ask_user`: `{"status":"answered","answer":"<answer>"}`. */
+export function buildQuestionAnsweredOutput(answer) {
+    return JSON.stringify({ status: "answered", answer });
+}
+/** Tool output after a `durable_wait` Timer ended: `{"status":"completed","waited_seconds":<n>,"reason":"<reason>"}`. */
+export function buildDurableWaitCompletedOutput(waitedSeconds, reason) {
+    return JSON.stringify({ status: "completed", waited_seconds: waitedSeconds, reason });
+}
+function invalidTodos(reason) {
+    return { isValid: false, error: `invalid todos: ${reason}` };
+}
+/** Sorted by code point, as Python's `sorted` orders strings, so both cores report the same name. */
+function sortByCodePoint(names) {
+    return [...names].sort(compareByCodePoint);
+}
+/** JavaScript's `<` compares UTF-16 code units, which orders characters above U+FFFF before U+E000. */
+function compareByCodePoint(left, right) {
+    const leftCodePoints = Array.from(left, (character) => character.codePointAt(0) ?? 0);
+    const rightCodePoints = Array.from(right, (character) => character.codePointAt(0) ?? 0);
+    const sharedLength = Math.min(leftCodePoints.length, rightCodePoints.length);
+    for (let index = 0; index < sharedLength; index += 1) {
+        const difference = (leftCodePoints[index] ?? 0) - (rightCodePoints[index] ?? 0);
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return leftCodePoints.length - rightCodePoints.length;
+}
+function parseArgumentsObject(builtInTool, argumentsText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(argumentsText);
+    }
+    catch {
+        return invalidArguments(builtInTool, "arguments must be a JSON object");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return invalidArguments(builtInTool, "arguments must be a JSON object");
+    }
+    const definition = builtInToolDefinitions.find((candidate) => candidate.name === builtInTool);
+    const allowedNames = Object.keys((definition?.parameters["properties"] ?? {}));
+    const [unknownName] = sortByCodePoint(Object.keys(parsed).filter((name) => !allowedNames.includes(name)));
+    if (unknownName !== undefined) {
+        return invalidArguments(builtInTool, `unknown argument ${unknownName}`);
+    }
+    return { isValid: true, arguments: parsed };
+}
+function invalidArguments(builtInTool, reason) {
+    return { isValid: false, error: `invalid ${builtInTool} arguments: ${reason}` };
+}
+//# sourceMappingURL=agent-built-in-tools.js.map

package/dist/src/agent-built-in-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-built-in-tools.js","sourceRoot":"","sources":["../../src/agent-built-in-tools.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,254 @@
+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
+ * as {@link AgentSessionOptions.compaction} or as `AgentDefinition.compaction` for a Stepwise agent.
+ *
+ * Before each model call, `RunModel` asks the runner for the size of the next model input. When it reaches
+ * {@link triggerRatio} of {@link contextWindowTokens}, `RunModel` makes no model call and moves to
+ * `CompactContext`, which folds the earlier messages into a {@link ContextSummary}, then back to
+ * `RunModel`. The runner must implement {@link AgentFrameworkRunner.estimateInputTokens},
+ * {@link AgentFrameworkRunner.selectCompactionCutoff}, and {@link AgentFrameworkRunner.summarizeContext};
+ * `createAgentSessionFlow` throws otherwise. Summarized messages stay stored until
+ * `AgentSessionOptions.retainedMessageLimit` deletes them; only the model input changes. Enable
+ * compaction only after every Worker of the Flow type runs a release with the `CompactContext` Step.
+ *
+ * @example
+ * ```ts
+ * const flow = createAgentSessionFlow(runner, "SupportAgent", {
+ *   compaction: { contextWindowTokens: 400_000 },
+ * });
+ * ```
+ */
+export interface CompactionPolicy {
+    /** The model's context window, in the tokens that the runner's `estimateInputTokens` counts. */
+    readonly contextWindowTokens: number;
+    /** Share of the window at which the session compacts before the next model call. Defaults to 0.85. */
+    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 {
+    /** The model's context window in tokens. */
+    readonly contextWindowTokens: number;
+    /** Share of the window at which the session compacts. */
+    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. */
+    readonly flowId: string;
+    /** Turn ID of the running turn. */
+    readonly turnId: string;
+    /** One-based `CompactContext` attempt. */
+    readonly attempt: number;
+    /** Dex Step execution ID of the `CompactContext` Step, shared by all of its attempts. */
+    readonly stepExecutionId: string;
+    /** The summary so far, or `null` for the first one. Fold its text into the new summary. */
+    readonly previousSummary: ContextSummary | null;
+    /**
+     * The messages after the previous summary through {@link throughSequence}, in sequence order. No tool
+     * call is separated from its result.
+     */
+    readonly messages: readonly AgentMessage[];
+    /** Sequence of the last message to summarize. */
+    readonly throughSequence: number;
+    /** Events writer bound to the turn and attempt. Write no model text to it: the summary is not an answer. */
+    readonly events: AgentEventWriter;
+    /** Signal aborted when Dex cancels the attempt; pass it to the model call. */
+    readonly cancellationSignal: AbortSignal;
+    /** Absolute deadline of the current attempt, or `undefined` when Dex supplied none. */
+    readonly deadline: Date | undefined;
+    /**
+     * Tokens the summary call may use, the policy's `contextWindowTokens`, or `undefined` for no limit. A runner
+     * keeps the input below it, less what it reserves for the summary, such as its `maxOutputTokens`. The range
+     * can be larger after the window shrank or when compaction starts on a long session;
+     * leave out its oldest part rather than send an over-window request that fails every turn.
+     */
+    readonly inputTokenBudget?: number;
+    /**
+     * The {@link SessionSettings} the running turn started with, as `AgentTurnContext.sessionSettings` has them.
+     * Use them to choose the model that writes the summary. The session always sets it; treat `undefined` as `{}`.
+     */
+    readonly sessionSettings?: SessionSettings;
+    /**
+     * Records a heartbeat. The session already records one every 20 seconds while the summary runs.
+     * @returns A Promise that resolves when the Worker accepted the heartbeat.
+     */
+    heartbeat(): Promise<void>;
+}
+/** What {@link AgentFrameworkRunner.summarizeContext} returns. */
+export interface ContextSummaryResult {
+    /** Summary text; it must not be blank. It replaces the previous summary, so it includes what that one said. */
+    readonly text: string;
+    /** Usage of the summary model call; the session adds it to the session's usage. */
+    readonly usage: AgentUsage;
+    /**
+     * Model and response of the summary call, for the `CompactContext` attempt's `chat` span. When omitted,
+     * the span is named `chat`.
+     */
+    readonly modelCallMetadata?: ModelCallMetadata;
+}
+/** A runner that implements the three optional compaction methods. */
+export type ContextCompactionRunner = AgentFrameworkRunner<DeferredToolOutcome> & Required<Pick<AgentFrameworkRunner<DeferredToolOutcome>, "estimateInputTokens" | "selectCompactionCutoff" | "summarizeContext">>;
+/** Reports whether a runner implements every compaction method. */
+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, `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: 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;