@superdurable/dex-agents 0.1.0 → 0.3.0

package/dist/src/agent-framework-runner.d.ts

@@ -1,4 +1,6 @@
-import type { AgentMessage, AgentToolCall, AgentToolCallStatus, AgentUsage, FrameworkMessage, ToolEffect } from "./agent-session-values.js";
+import type { BuiltInTool } from "./agent-built-in-tools.js";
+import type { ContextSummaryRequest, ContextSummaryResult } from "./agent-context-compaction.js";
+import type { AgentMessage, AgentPlan, AgentToolCall, AgentToolCallRecord, AgentToolCallStatus, AgentUsage, ContextSummary, SessionSettings, FrameworkMessage, InteractionMode, QuestionAnswer, ToolEffect } from "./agent-session-values.js";
 /**
  * Per-tool override of the effect and approval defaults.
  *
@@ -113,13 +115,22 @@ export interface AgentTurnContext {
     /** Turn ID, `turn-<n>`. */
     readonly turnId: string;
     /**
-     * One-based `RunModel` attempt. A rerun after a Worker crash may keep the same attempt when the
-     * crashed attempt sent no output, so do not rely on it to detect reruns.
+     * One-based `RunModel` attempt. A rerun after a Worker crash gets the next attempt, but an attempt whose
+     * stream half-closed before any output returns as not run and keeps its number, so do not rely on it to
+     * detect reruns.
      */
     readonly attempt: number;
+    /**
+     * Dex Step execution ID of this `RunModel` Step, shared by all of its attempts.
+     *
+     * The session always sets this field. It is optional only so that code that builds a context by hand
+     * keeps compiling.
+     */
+    readonly stepExecutionId?: string;
     /**
      * Every stored session message in ascending sequence order, including the user message that
-     * started this turn. Replay each `frameworkItem` to the framework unchanged.
+     * started this turn. Replay each `frameworkItem` to the framework unchanged. After compaction, only the
+     * messages after {@link contextSummary}.
      */
     readonly messages: readonly AgentMessage[];
     /**
@@ -141,6 +152,52 @@ export interface AgentTurnContext {
     readonly cancellationSignal: AbortSignal;
     /** Absolute deadline of the current attempt, or `undefined` when Dex supplied none. */
     readonly deadline: Date | undefined;
+    /**
+     * Built-in tools enabled for this session through {@link AgentSessionOptions.builtInTools}. Offer
+     * their definitions from {@link builtInToolDefinitions} to the model; the session handles their calls.
+     *
+     * The session always sets this field. It is optional only so that code that builds a context by hand,
+     * such as a unit test, keeps compiling; treat `undefined` as no built-in tools.
+     */
+    readonly enabledBuiltInTools?: ReadonlySet<BuiltInTool>;
+    /**
+     * Explicit policies by tool name from {@link AgentSessionOptions.toolPolicies}, the same map
+     * {@link resolveToolPolicy} applies first. A runner whose framework sets its own approval default, such as
+     * a tool's `requiresApproval`, applies that default only to tools without an explicit policy here.
+     * Optional for the same reason as {@link enabledBuiltInTools}; treat `undefined` as no policies.
+     */
+    readonly toolPolicies?: Readonly<Record<string, ToolPolicy>>;
+    /**
+     * {@link AgentSessionOptions.defaultToolEffect}, the effect of a tool without a policy or framework
+     * metadata. Optional for the same reason as {@link enabledBuiltInTools}.
+     */
+    readonly defaultToolEffect?: ToolEffect;
+    /**
+     * The turn's {@link AgentState.interactionMode}. A runner with {@link AgentFrameworkRunner.supportsPlanMode}
+     * offers only `write_todos` in a `planning` turn. The session always sets it; treat `undefined` as `chat`.
+     */
+    readonly interactionMode?: InteractionMode;
+    /**
+     * The {@link AgentPlan} as committed before this model call, or `null` before `write_todos` first
+     * succeeded. Show it to the model with {@link buildPlanNote}. The session always sets it; treat
+     * `undefined` as `null`.
+     */
+    readonly plan?: AgentPlan | null;
+    /**
+     * The summary of the messages before {@link messages}, or `null`. Only a runner that implements the
+     * compaction methods, such as {@link AgentFrameworkRunner.summarizeContext}, receives one; put its text
+     * before {@link messages} in the model input. Optional for the same reason as {@link enabledBuiltInTools};
+     * treat `undefined` as no summary.
+     */
+    readonly contextSummary?: ContextSummary | null;
+    /**
+     * The {@link SessionSettings} this turn started with, such as `{ model: "gpt-5-mini" }`. Use them to choose
+     * the model or the instructions of each model call. `update_session_settings` changes them from the next turn
+     * on, so every model call of one turn sees the same value, retries included. Empty when the session has no
+     * settings, such as a session started on dex-agents 0.1.0. The session always sets it; it is optional for the
+     * same reason as {@link enabledBuiltInTools}, so treat `undefined` as `{}`.
+     */
+    readonly sessionSettings?: SessionSettings;
     /**
      * Returns the effective policy of a tool; see {@link resolveToolPolicy} for the precedence.
      * Pass it unchanged in {@link DeferredToolCall.policy}.
@@ -178,30 +235,89 @@ export interface DeferredToolCall {
     readonly arguments: string;
     /** Policy from {@link AgentTurnContext.resolveToolPolicy}; it decides approval and the tool Step. */
     readonly policy: ResolvedToolPolicy;
+    /**
+     * Opaque text that the tool's source stores on the call's record, such as which MCP server and tool
+     * to call. The tool Step returns it in {@link DeferredToolExecution.toolCall}, so the source resolves
+     * the tool without listing it again. Omit it to store nothing.
+     */
+    readonly toolSourceReference?: string;
+}
+/**
+ * Model and response of one model call, returned in {@link TurnCompleted} or {@link ToolCallsRequested}
+ * for tracing.
+ *
+ * The session never stores it: it only names the `chat` span and sets its GenAI attributes. Omit a
+ * field when the framework does not expose it.
+ *
+ * @example
+ * ```ts
+ * const modelCallMetadata: ModelCallMetadata = {
+ *   requestModel: "gpt-5",
+ *   responseModel: "gpt-5-2026-08-07",
+ *   providerName: "openai",
+ *   responseId: "resp_123",
+ *   finishReasons: ["tool_calls"],
+ * };
+ * return { kind: "tool_calls_requested", frameworkRunState, toolCalls, usage, modelCallMetadata };
+ * ```
+ */
+export interface ModelCallMetadata {
+    /**
+     * Model name the call requested, such as `"gpt-5"`. It becomes `gen_ai.request.model` and the span
+     * name `chat <requestModel>`.
+     */
+    readonly requestModel?: string;
+    /** Model name the provider reported. */
+    readonly responseModel?: string;
+    /**
+     * GenAI provider, such as `"openai"`, `"anthropic"`, or `"gcp.gemini"`. Use the well-known
+     * `gen_ai.provider.name` value when one applies.
+     */
+    readonly providerName?: string;
+    /** Provider response ID. */
+    readonly responseId?: string;
+    /** Provider finish reasons, one per returned choice. */
+    readonly finishReasons?: readonly string[];
 }
 /** Outcome of a model call that produced the turn's final answer. */
 export interface TurnCompleted {
     /** Discriminator. */
     readonly kind: "completed";
     /**
-     * Every message the turn produced after its user message, across all of its model calls, in order:
-     * model output, tool requests, tool results, and the final answer. The session appends them in one
-     * commit and deletes the turn's tool call records.
+     * Every message of the turn that the session has not stored yet, in order: model output, tool
+     * requests, tool results, and the final answer. The session appends them in one commit and deletes the
+     * turn's tool call records.
+     *
+     * A runner that never sets {@link ToolCallsRequested.newMessages} returns every message the turn
+     * produced after its user message, across all of its model calls. A runner that stores messages
+     * incrementally returns only the messages after the ones it already returned.
      */
     readonly newMessages: readonly FrameworkMessage[];
     /** Usage of this model call only; the session adds it to the cumulative usage. */
     readonly usage: AgentUsage;
+    /** Model and response of this model call, for the `chat` span. When omitted, the span is named `chat`. */
+    readonly modelCallMetadata?: ModelCallMetadata;
 }
 /** Outcome of a model call that requested tool calls. */
 export interface ToolCallsRequested {
     /** Discriminator. */
     readonly kind: "tool_calls_requested";
     /**
-     * Non-empty serialized framework state from which the next `RunModel` continues the turn, including
-     * the messages this turn has produced so far. The session stores no partial messages; it keeps this
-     * value opaquely in `FrameworkRunState`.
+     * Non-empty serialized framework state from which the next `RunModel` continues the turn. The
+     * session keeps this value opaquely in `FrameworkRunState`. A runner without
+     * {@link newMessages} includes the messages this turn has produced so far; a runner with them keeps
+     * only what the stored messages cannot rebuild, so the value does not grow with the turn.
      */
     readonly frameworkRunState: string;
+    /**
+     * Messages of the turn to store now, in the same commit that records the tool calls. Defaults to none.
+     *
+     * Return the previous model response's tool results and this model response, so the turn's
+     * transcript is stored while its tools run. A runner that sets this field must implement
+     * {@link AgentFrameworkRunner.buildUnfinishedTurnMessages}; the session fails the model call
+     * otherwise. The next {@link AgentTurnContext.messages} include these messages.
+     */
+    readonly newMessages?: readonly FrameworkMessage[];
     /**
      * Every tool call of the model response, at least one. Each runs in its own Step, in parallel. Do not
      * repeat a call that already has a record in {@link AgentTurnContext.toolCalls}; the session rejects
@@ -210,6 +326,8 @@ export interface ToolCallsRequested {
     readonly toolCalls: readonly DeferredToolCall[];
     /** Usage of this model call only. */
     readonly usage: AgentUsage;
+    /** Model and response of this model call, for the `chat` span. When omitted, the span is named `chat`. */
+    readonly modelCallMetadata?: ModelCallMetadata;
 }
 /** Result of {@link AgentFrameworkRunner.runModelStep}. */
 export type AgentTurnOutcome = TurnCompleted | ToolCallsRequested;
@@ -236,17 +354,200 @@ export interface DeferredToolExecution {
     readonly cancellationSignal: AbortSignal;
     /** Absolute deadline of the current attempt, or `undefined`. */
     readonly deadline: Date | undefined;
+    /**
+     * Answers to the questions this call asked by returning {@link ToolInputRequested}, oldest first, or
+     * empty. The opaque continuation of the last question is in `toolCall.inputContinuation`.
+     *
+     * The session always sets this field. It is optional only so that code that builds an execution by
+     * hand, such as a unit test, keeps compiling; treat `undefined` as no answers.
+     */
+    readonly inputAnswers?: readonly QuestionAnswer[];
+    /**
+     * Whether the runner implements {@link AgentFrameworkRunner.pollToolTask}, so the tool may return
+     * {@link ToolTaskStarted}. When it is not `true`, run remote work to its end inside the call instead.
+     * Optional for the same reason as {@link inputAnswers}; treat `undefined` as `false`.
+     */
+    readonly supportsToolTasks?: boolean;
     /**
      * Records a heartbeat. The session already records one every 20 seconds.
      * @returns A Promise that resolves when the Worker accepted the heartbeat.
      */
     heartbeat(): Promise<void>;
+    /**
+     * The checkpoint an earlier attempt of this call saved with {@link saveHeartbeatCheckpoint}, absent
+     * when none did. Use it to resume work that the earlier attempt started, such as polling a
+     * long-running job, instead of starting it again.
+     */
+    readonly heartbeatCheckpoint?: string;
+    /**
+     * Records a heartbeat carrying a checkpoint. Every later heartbeat of the attempt, including the
+     * session's background heartbeats, carries it too, so the next attempt reads it as
+     * {@link heartbeatCheckpoint}. Absent when the caller cannot save checkpoints.
+     * @param checkpoint - Text to hand to the next attempt.
+     * @returns A Promise that resolves when the Worker accepted the heartbeat.
+     */
+    saveHeartbeatCheckpoint?(checkpoint: string): Promise<void>;
 }
-/** Successful result of one deferred tool call. */
+/** Successful result of one deferred tool call. A result without `kind` is a `ToolExecutionResult`. */
 export interface ToolExecutionResult {
     /** Output text recorded on the call and shown to the model. */
     readonly output: string;
 }
+/**
+ * Result of a deferred tool call that needs an answer from the user before it can take effect.
+ *
+ * Return it from {@link AgentFrameworkRunner.executeDeferredToolCall} only when the call has had no
+ * effect yet. The tool Step records `awaiting_answer` and stores {@link continuation}. `AwaitQuestionAnswer`
+ * then raises a `question` interrupt with ID `<toolCallId>-input-<n>`, where `n` counts the call's
+ * questions from 1. After `answer_question`, the record returns to `approved` and the same tool Step
+ * type runs the call again, with every answer in {@link DeferredToolExecution.inputAnswers} and the
+ * continuation in `toolCall.inputContinuation`. The tool's later output, not the answer, is the result.
+ * A declined question or a passed deadline records `rejected`, and the tool never runs again.
+ *
+ * Because the call took no effect, a single-attempt tool that runs again after an answer still never
+ * repeats an effect. A crash during the second run records `outcome_unknown`, as for any run.
+ *
+ * @example
+ * ```ts
+ * public async executeDeferredToolCall(call: DeferredToolExecution): Promise<DeferredToolOutcome> {
+ *   const confirmation = call.inputAnswers?.at(-1)?.answer;
+ *   if (confirmation === undefined) {
+ *     return { kind: "tool_input_requested", question: "Ship to the saved address?", choices: ["yes", "no"],
+ *       allowsFreeText: false, continuation: null };
+ *   }
+ *   return { output: confirmation === "yes" ? await shipOrder(call.idempotencyKey) : "not shipped" };
+ * }
+ * ```
+ */
+export interface ToolInputRequested {
+    /** Discriminator. */
+    readonly kind: "tool_input_requested";
+    /** Question for the user; it must not be blank. */
+    readonly question: string;
+    /** Answers to offer. Defaults to none, which makes the question free text. */
+    readonly choices?: readonly string[];
+    /** Whether an answer outside {@link choices} is accepted. Defaults to `true`; ignored without choices. */
+    readonly allowsFreeText?: boolean;
+    /** Opaque text returned to the tool with the answer, such as a server request ID, or `null`. */
+    readonly continuation: string | null;
+}
+/**
+ * Result of a deferred tool call that started remote work and returned a handle to poll.
+ *
+ * Return it from {@link AgentFrameworkRunner.executeDeferredToolCall} when the tool's work runs
+ * elsewhere and outlives the call, such as an MCP task. The tool Step records `waiting_for_task` with
+ * {@link taskId} and the poll interval, writes `tool_task_started`, and ends. `PollToolTask` then waits
+ * on a Timer for the interval and calls {@link AgentFrameworkRunner.pollToolTask} once per execution, so
+ * no Step or connection is held while the work runs, and a Worker restart only delays the next poll. The
+ * runner must implement `pollToolTask`; without it the session records the call `failed` for a `read`
+ * tool and `outcome_unknown` otherwise.
+ *
+ * The tool Step commits the handle with its result. A `CallTool` attempt that dies after the remote work
+ * started runs again, so save the handle with {@link DeferredToolExecution.saveHeartbeatCheckpoint}
+ * before you return it, and return the saved handle when {@link DeferredToolExecution.heartbeatCheckpoint}
+ * holds one. Once the checkpoint has reached Dex, a retried attempt resumes the same work. Dex may drop a
+ * heartbeat checkpoint, though, so an attempt that dies before its checkpoint is saved and before the tool
+ * Step commits can still start the work a second time on a `CallTool` retry; pass the idempotency key to
+ * the remote system so it can drop the duplicate. Steering waits for a started task. `cancel_turn` abandons
+ * it: the session records `outcome_unknown` and asks {@link AgentFrameworkRunner.cancelToolTask} to cancel it.
+ *
+ * @example
+ * ```ts
+ * public async executeDeferredToolCall(call: DeferredToolExecution): Promise<DeferredToolOutcome> {
+ *   if (call.heartbeatCheckpoint !== undefined) {
+ *     return { kind: "tool_task_started", taskId: call.heartbeatCheckpoint, pollIntervalSeconds: 5 };
+ *   }
+ *   const jobId = await reports.start(call.idempotencyKey);
+ *   await call.saveHeartbeatCheckpoint?.(jobId);
+ *   return { kind: "tool_task_started", taskId: jobId, pollIntervalSeconds: 5 };
+ * }
+ * ```
+ */
+export interface ToolTaskStarted {
+    /** Discriminator. */
+    readonly kind: "tool_task_started";
+    /** Handle of the remote work; it must not be blank. The session stores it as the record's `taskId`. */
+    readonly taskId: string;
+    /**
+     * Seconds to wait before the first poll. The session rounds it up to whole seconds, at least 1,
+     * because Dex Timers take whole seconds, and shortens it to at most a day.
+     */
+    readonly pollIntervalSeconds: number;
+}
+/** Result of {@link AgentFrameworkRunner.pollToolTask} while the polled task still runs. */
+export interface ToolTaskPending {
+    /** Discriminator. */
+    readonly kind: "tool_task_pending";
+    /** Seconds to wait before the next poll. The session rounds it up to whole seconds, from 1 to a day. */
+    readonly pollIntervalSeconds: number;
+    /**
+     * Text the next poll reads as `toolCall.inputContinuation`, such as which question the task took an answer
+     * to and when. Omitted or `null` clears it: keep what the next poll needs, and drop a question's
+     * continuation once the task took its answer, so an identical later question reads as new.
+     */
+    readonly continuation?: string | null;
+}
+/** One task that `PollToolTask` asks the runner to poll. */
+export interface ToolTaskPoll {
+    /** Flow ID, which is the session ID. */
+    readonly flowId: string;
+    /** The call's record, `waiting_for_task`, with `taskId`, `taskPollIntervalSeconds`, and `toolSourceReference`. */
+    readonly toolCall: AgentToolCallRecord;
+    /** `<flowId>/<turnId>/<toolCallId>`, the key the tool Step passed when it started the task. */
+    readonly idempotencyKey: string;
+    /** One-based `PollToolTask` attempt. Each poll gets up to three attempts. */
+    readonly attempt: number;
+    /** How the questions this call asked were resolved, oldest first, whether its tool or its task asked them. */
+    readonly inputAnswers: readonly QuestionAnswer[];
+    /**
+     * The resolution of the task's last question, which has not reached the task yet, or `null`. It is set
+     * only on the first poll after `AwaitQuestionAnswer` resolved the question, which runs at once. Deliver it
+     * to the task: the answer when `resolution` is `answered`, a decline when it is `declined`, and a
+     * cancelled request when it is `deadline_passed`. `toolCall.inputContinuation` holds the question's
+     * continuation, so recognize the request it answers and deliver only to that request. Later polls read the
+     * continuation the last {@link ToolTaskPending} returned. A retried attempt gets it again; when it cannot
+     * tell whether an earlier attempt delivered it, return the task's question as {@link ToolInputRequested}
+     * again rather than send it to what may be a later question. When the task cannot take the resolution,
+     * cancel the task best-effort and throw an error other than {@link ToolExecutionError}, so the session
+     * records the call by its effect.
+     */
+    readonly pendingAnswer: QuestionAnswer | null;
+    /** Events writer bound to the turn and attempt. */
+    readonly events: AgentEventWriter;
+    /** Signal aborted when Dex cancels the attempt. */
+    readonly cancellationSignal: AbortSignal;
+    /** Absolute deadline of the current attempt, or `undefined`. */
+    readonly deadline: Date | undefined;
+    /**
+     * Records a heartbeat. The session already records one every 20 seconds.
+     * @returns A Promise that resolves when the Worker accepted the heartbeat.
+     */
+    heartbeat(): Promise<void>;
+}
+/** One task that `cancel_turn` abandoned, which `CancelToolTask` asks the runner to cancel. */
+export interface ToolTaskCancellation {
+    /** Flow ID, which is the session ID. */
+    readonly flowId: string;
+    /**
+     * The call's record with `taskId` and `toolSourceReference`. Its `cancellationReason` is `turn_cancelled`.
+     */
+    readonly toolCall: AgentToolCallRecord;
+    /** `<flowId>/<turnId>/<toolCallId>`, the key the tool Step passed when it started the task. */
+    readonly idempotencyKey: string;
+    /** One-based `CancelToolTask` attempt. Each cancellation gets up to three attempts. */
+    readonly attempt: number;
+    /** Signal aborted when Dex cancels the attempt, such as when its method timeout passes. */
+    readonly cancellationSignal: AbortSignal;
+    /**
+     * Records a heartbeat. The session already records one every 20 seconds.
+     * @returns A Promise that resolves when the Worker accepted the heartbeat.
+     */
+    heartbeat(): Promise<void>;
+}
+/** Result of {@link AgentFrameworkRunner.executeDeferredToolCall}. */
+export type DeferredToolOutcome = ToolExecutionResult | ToolInputRequested | ToolTaskStarted;
+/** Result of {@link AgentFrameworkRunner.pollToolTask}. */
+export type ToolTaskPollOutcome = ToolExecutionResult | ToolInputRequested | ToolTaskPending;
 /**
  * Tool failure that the model should see, thrown from {@link AgentFrameworkRunner.executeDeferredToolCall}.
  *
@@ -290,6 +591,9 @@ export declare class ToolExecutionError extends Error {
  *   run in another Worker process.
  * - Throwing from `runModelStep` retries the model call, up to 3 attempts within 30 minutes; then the
  *   turn fails, the session records `last_turn_error`, and it waits for the next user message.
+ * - A runner may store the turn's transcript incrementally with {@link ToolCallsRequested.newMessages};
+ *   it then implements {@link buildUnfinishedTurnMessages}. A runner may offer the
+ *   {@link AgentTurnContext.enabledBuiltInTools} to its model; the session handles their calls.
  *
  * @example
  * ```ts
@@ -310,8 +614,11 @@ export declare class ToolExecutionError extends Error {
  *   }
  * }
  * ```
+ * @typeParam ToolOutcome - What {@link executeDeferredToolCall} returns. It defaults to
+ * {@link ToolExecutionResult}; a runner whose tools can ask the user a question first or start a remote
+ * task implements `AgentFrameworkRunner<DeferredToolOutcome>`. The session accepts both.
  */
-export interface AgentFrameworkRunner {
+export interface AgentFrameworkRunner<ToolOutcome extends DeferredToolOutcome = ToolExecutionResult> {
     /**
      * Converts user text into the framework's user message.
      *
@@ -335,12 +642,144 @@ export interface AgentFrameworkRunner {
      * Runs the real tool for one tool call, in `CallTool` or `CallSingleAttemptTool`.
      *
      * @param call - Deferred call to run.
-     * @returns The tool output text.
+     * @returns The tool output text; {@link ToolInputRequested} when the tool needs an answer from the
+     * user before it takes any effect; or {@link ToolTaskStarted} when the tool started remote work that
+     * {@link pollToolTask} polls.
      * @throws {ToolExecutionError} For a failure the model should see; the call is recorded as `failed`.
      * @throws Any other error for an unexpected failure; after the last attempt the record becomes
      * `failed` for a `read` tool and `outcome_unknown` for a write. See {@link ToolExecutionError}.
      */
-    executeDeferredToolCall(call: DeferredToolExecution): Promise<ToolExecutionResult>;
+    executeDeferredToolCall(call: DeferredToolExecution): Promise<ToolOutcome>;
+    /**
+     * Returns the turn's messages that the session has not stored yet, when the turn ends without a final
+     * answer. Optional.
+     *
+     * Implement it when the runner sets {@link ToolCallsRequested.newMessages}. `RecordTurnFailure` calls
+     * it before it appends the turn-failure note, with every record of the turn final. Return the tool
+     * result of every tool call already stored or returned that has no stored result, so no tool call is
+     * left without a result. It must be synchronous and make no model call. When it throws, the session
+     * stores only the turn-failure note, so a runner defect never blocks the failure route.
+     *
+     * @param turn - The ended turn; {@link AgentTurnContext.toolCalls} holds its final records.
+     * @returns The messages to append, in order, possibly none.
+     */
+    buildUnfinishedTurnMessages?(turn: AgentTurnContext): readonly FrameworkMessage[];
+    /**
+     * Whether the runner honors plan mode. Optional; {@link AgentSessionOptions.planModeEnabled} needs `true`,
+     * and `createAgentSessionFlow` throws otherwise.
+     *
+     * Such a runner reads {@link AgentTurnContext.interactionMode} in every `runModelStep`. In a `planning`
+     * turn it offers only the `write_todos` definition from {@link builtInToolDefinitions}. It may force
+     * `write_todos` on the turn's first model call while the plan is not a draft yet, where the model accepts a
+     * forced tool choice; Stepwise does with `planningToolChoice: "required"`. In every
+     * turn it shows the plan with {@link buildPlanNote} as user text before the turn's messages. The Stepwise
+     * runner implements it; a framework adapter that cannot change the tools it offers between turns leaves
+     * plan mode off.
+     */
+    readonly supportsPlanMode?: boolean;
+    /**
+     * Polls one remote task that a tool started with {@link ToolTaskStarted}, once. Optional.
+     *
+     * Implement it when a tool returns `ToolTaskStarted`. `PollToolTask` calls it once per execution,
+     * after a Timer for the call's poll interval, until it returns a result. Polling must only read the
+     * task, and deliver `poll.pendingAnswer` when it is set, because the session may poll again after a
+     * crash. Steering never stops a poll. `cancel_turn` aborts `poll.cancellationSignal` of a running poll,
+     * and the session drops whatever it returns.
+     *
+     * @example
+     * ```ts
+     * public async pollToolTask(poll: ToolTaskPoll): Promise<ToolTaskPollOutcome> {
+     *   const job = await reports.get(poll.toolCall.taskId!);
+     *   return job.done ? { output: job.summary } : { kind: "tool_task_pending", pollIntervalSeconds: 10 };
+     * }
+     * ```
+     * @param poll - The call's record and its idempotency key.
+     * @returns {@link ToolExecutionResult} when the task finished, which the model sees;
+     * {@link ToolTaskPending} while it runs; or {@link ToolInputRequested} when it needs the user's answer.
+     * The session asks the question through `AwaitQuestionAnswer` and polls again at once with its
+     * resolution, answered, declined, or past its deadline, as `pendingAnswer`. The task's later result is
+     * the call's result.
+     * @throws {ToolExecutionError} When the task failed in a way the model should see; the call is
+     * recorded as `failed`.
+     * @throws Any other error to fail the poll attempt; after three attempts the record becomes `failed`
+     * for a `read` call and `outcome_unknown` otherwise, because the task may still run.
+     */
+    pollToolTask?(poll: ToolTaskPoll): Promise<ToolTaskPollOutcome>;
+    /**
+     * Asks the remote system to stop one task that `cancel_turn` abandoned. Optional.
+     *
+     * `cancel_turn` does not wait for a started task: the session records the call `outcome_unknown` with
+     * `cancellationReason` `turn_cancelled`, and the `CancelToolTask` Step calls this method best-effort before
+     * it records the call. A runner without it leaves the task running. Steering never cancels a task. The
+     * session may call it more than once for one task, after a crash or a failed attempt, so make it idempotent
+     * by `taskId`. A task that already finished, or that the remote system no longer knows, is cancelled: return
+     * normally. The record is final whatever this method does, and a result the task returns later is dropped.
+     *
+     * @example
+     * ```ts
+     * public async cancelToolTask(cancellation: ToolTaskCancellation): Promise<void> {
+     *   await reports.cancel(cancellation.toolCall.taskId!);
+     * }
+     * ```
+     * @param cancellation - The abandoned call's record and its idempotency key.
+     * @returns A Promise that resolves once the remote system took the cancellation.
+     * @throws Any error when the cancellation did not reach the remote system; the session retries it up to
+     * three times, then records the call `outcome_unknown` anyway, so the turn always ends.
+     */
+    cancelToolTask?(cancellation: ToolTaskCancellation): Promise<void>;
+    /**
+     * Estimates the size of the model input that the next {@link runModelStep} sends. Optional; one of the
+     * three compaction methods that {@link AgentSessionOptions.compaction} requires.
+     *
+     * `RunModel` calls it before every model call of a session with a compaction policy. At the policy's
+     * threshold it calls {@link selectCompactionCutoff}, and when that returns a sequence after the current
+     * summary, `CompactContext` calls {@link summarizeContext} once and stores the result as the
+     * `ContextSummary`. From then on, {@link AgentTurnContext.messages} start after the summary and
+     * {@link AgentTurnContext.contextSummary} holds it. A runner without these methods never compacts.
+     *
+     * @example
+     * ```ts
+     * class CompactingRunner extends MyRunner {
+     *   public estimateInputTokens(turn: AgentTurnContext): number {
+     *     return countTokens(buildModelInput(turn));
+     *   }
+     *   public selectCompactionCutoff(turn: AgentTurnContext, retainedTokenBudget: number): number | null {
+     *     return lastSequenceBeforeNewestMessages(turn.messages, retainedTokenBudget);
+     *   }
+     *   public async summarizeContext(request: ContextSummaryRequest): Promise<ContextSummaryResult> {
+     *     const response = await model.summarize(request.previousSummary, request.messages);
+     *     return { text: response.text, usage: response.usage };
+     *   }
+     * }
+     * ```
+     * @param turn - The same context the next {@link runModelStep} receives.
+     * @returns The estimated input tokens, in the unit of `CompactionPolicy.contextWindowTokens`.
+     */
+    estimateInputTokens?(turn: AgentTurnContext): number | Promise<number>;
+    /**
+     * Chooses the last message to summarize, so the newest messages fit a token budget. Optional; see
+     * {@link estimateInputTokens}.
+     *
+     * Never separate a tool call from its result: the messages after the cutoff must not start with a tool
+     * result or hold a result whose call is before the cutoff. Keep the turn's unstored tool results
+     * answerable.
+     *
+     * @param turn - The context of the model call that crossed the threshold.
+     * @param retainedTokenBudget - Tokens that the messages after the cutoff may use.
+     * @returns The sequence of the last message to summarize, one of {@link AgentTurnContext.messages}; or
+     * `null` when nothing can be summarized, which lets the model call proceed.
+     */
+    selectCompactionCutoff?(turn: AgentTurnContext, retainedTokenBudget: number): number | null | Promise<number | null>;
+    /**
+     * Folds the previous summary and a range of messages into a new summary, with at most one model call.
+     * Optional; see {@link estimateInputTokens}. A crash during the call reruns only this call.
+     *
+     * @param request - The previous summary and the messages to summarize.
+     * @returns The new summary text and the usage of the call.
+     * @throws Any error to fail the `CompactContext` attempt; it retries up to 3 attempts within 30
+     * minutes, then the turn fails through `RecordTurnFailure`.
+     */
+    summarizeContext?(request: ContextSummaryRequest): Promise<ContextSummaryResult>;
 }
 /** MCP tool annotations that classify a tool's side effects. */
 export interface McpToolAnnotations {
@@ -362,7 +801,8 @@ export interface McpToolAnnotations {
  * const policy = turn.resolveToolPolicy(tool.name, toolEffectFromMcpToolAnnotations(tool.annotations ?? {}));
  * ```
  * @param annotations - The tool's MCP annotations.
- * @returns `read` when `readOnlyHint` is `true`; `idempotent_write` when `idempotentHint` is `true`
- * and `destructiveHint` is not `true`; otherwise `undefined`, so the session default applies.
+ * @returns `read` when `readOnlyHint` is `true`; otherwise `idempotent_write` when `idempotentHint` is
+ * `true`, whatever `destructiveHint` says, as in the Python core; otherwise `undefined`, so the session
+ * default applies.
  */
 export declare function toolEffectFromMcpToolAnnotations(annotations: McpToolAnnotations): ToolEffect | undefined;

package/dist/src/agent-framework-runner.js

@@ -66,14 +66,15 @@ export class ToolExecutionError extends Error {
  * const policy = turn.resolveToolPolicy(tool.name, toolEffectFromMcpToolAnnotations(tool.annotations ?? {}));
  * ```
  * @param annotations - The tool's MCP annotations.
- * @returns `read` when `readOnlyHint` is `true`; `idempotent_write` when `idempotentHint` is `true`
- * and `destructiveHint` is not `true`; otherwise `undefined`, so the session default applies.
+ * @returns `read` when `readOnlyHint` is `true`; otherwise `idempotent_write` when `idempotentHint` is
+ * `true`, whatever `destructiveHint` says, as in the Python core; otherwise `undefined`, so the session
+ * default applies.
  */
 export function toolEffectFromMcpToolAnnotations(annotations) {
     if (annotations.readOnlyHint === true) {
         return "read";
     }
-    if (annotations.idempotentHint === true && annotations.destructiveHint !== true) {
+    if (annotations.idempotentHint === true) {
         return "idempotent_write";
     }
     return undefined;

package/dist/src/agent-framework-runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-framework-runner.js","sourceRoot":"","sources":["../../src/agent-framework-runner.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AA2C1D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAgB,EAChB,YAAkD,EAClD,iBAA6B,EAC7B,eAA4B;IAE5B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1F,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,eAAe,IAAI,iBAAiB,CAAC;IACtE,MAAM,gBAAgB,GACpB,MAAM,EAAE,gBAAgB,IAAI,CAAC,MAAM,KAAK,sBAAsB,IAAI,MAAM,KAAK,cAAc,CAAC,CAAC;IAC/F,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;AACtC,CAAC;AAiND;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C;;;;OAIG;IACH,YAAmB,OAAe,EAAE,OAAsB;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAqFD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gCAAgC,CAC9C,WAA+B;IAE/B,IAAI,WAAW,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QACtC,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,WAAW,CAAC,cAAc,KAAK,IAAI,IAAI,WAAW,CAAC,eAAe,KAAK,IAAI,EAAE,CAAC;QAChF,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"agent-framework-runner.js","sourceRoot":"","sources":["../../src/agent-framework-runner.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAmD1D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAgB,EAChB,YAAkD,EAClD,iBAA6B,EAC7B,eAA4B;IAE5B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1F,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,eAAe,IAAI,iBAAiB,CAAC;IACtE,MAAM,gBAAgB,GACpB,MAAM,EAAE,gBAAgB,IAAI,CAAC,MAAM,KAAK,sBAAsB,IAAI,MAAM,KAAK,cAAc,CAAC,CAAC;IAC/F,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;AACtC,CAAC;AAogBD;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C;;;;OAIG;IACH,YAAmB,OAAe,EAAE,OAAsB;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AA+ND;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gCAAgC,CAC9C,WAA+B;IAE/B,IAAI,WAAW,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QACtC,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,WAAW,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;QACxC,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/src/agent-plans.d.ts

@@ -0,0 +1,48 @@
+import type { AgentPlan, AgentPlanTask, InteractionMode, PlanStatus } from "./agent-session-values.js";
+/**
+ * Rejection message of a call to any tool other than `write_todos` in a `planning` turn; the same text as
+ * the Python core.
+ */
+export declare const planningTurnToolRejection = "The tool call was not run: a planning turn can only call write_todos.";
+/** First line of the plan note while no plan exists; the same text as the Python core. */
+export declare const noPlanNote = "[Dex] There is no plan yet.";
+/** Last line of the plan note in a `planning` turn; the same text as the Python core. */
+export declare const planningTurnInstruction: string;
+/**
+ * Returns the user message text of a turn that `execute_plan` started.
+ *
+ * @param revision - The approved {@link AgentPlan.revision}.
+ * @returns `[Dex] The user approved plan revision <n>. Execute it and keep the task statuses current with
+ * write_todos.`, the same text as the Python core.
+ */
+export declare function buildPlanExecutionMessage(revision: number): string;
+/**
+ * Returns the text that shows the model the current plan, or `undefined` for none.
+ *
+ * A runner that honors plan mode adds it to the model input of every model call, after the context summary
+ * and before the turn's messages, as user text. It is not stored as a message, so it always shows the
+ * latest plan. The text is the same as the Python core's `build_plan_note`:
+ *
+ * ```text
+ * [Dex] The current plan, revision 2, is draft:
+ * - [completed] Look up the order
+ * - [pending] Refund the order
+ * This turn only plans: write or revise the plan with write_todos, ...
+ * ```
+ *
+ * @param plan - The {@link AgentPlan}, or `null` or `undefined` when there is none.
+ * @param interactionMode - The turn's mode; `undefined` means `chat`.
+ * @returns One line for the plan and one per task, then {@link planningTurnInstruction} in a `planning`
+ * turn, joined with newlines. {@link noPlanNote} stands for a missing or cleared plan in a `planning` turn.
+ * `undefined` when there is no plan to show outside a `planning` turn.
+ */
+export declare function buildPlanNote(plan: AgentPlan | null | undefined, interactionMode: InteractionMode | undefined): string | undefined;
+/**
+ * Returns the status of the plan that `write_todos` writes.
+ *
+ * @param tasks - The tasks written.
+ * @param interactionMode - The mode of the turn that wrote them.
+ * @returns `cleared` for no tasks, `draft` in a `planning` turn, `completed` when every task is completed,
+ * and `active` otherwise.
+ */
+export declare function planStatusAfterWrite(tasks: readonly AgentPlanTask[], interactionMode: InteractionMode | undefined): PlanStatus;