@superdurable/dex-agents 0.3.0 → 0.5.0

package/dist/src/{stepwise/stepwise-agent-runner.js → builtin-loop/builtin-loop-agent-runner.js}

@@ -9,32 +9,47 @@ import { builtInToolDefinitions } from "../agent-built-in-tools.js";
 import { buildContextSummaryNote, buildContextSummaryOmissionNote, contextSummaryInstructions, contextSummaryRequest, } from "../agent-context-compaction.js";
 export { buildContextSummaryNote, buildContextSummaryOmissionNote, contextSummaryInstructions, contextSummaryNoteHeader, contextSummaryRequest, } from "../agent-context-compaction.js";
 import { ToolExecutionError, } from "../agent-framework-runner.js";
+import { loadImages } from "../agent-media.js";
 import { buildPlanNote } from "../agent-plans.js";
-import { describeToolCallOutcome, } from "../agent-session-values.js";
+import { describeToolCallOutcome, emptyAgentUsage, } from "../agent-session-values.js";
+import { isFunctionToolResult } from "./function-tool.js";
 import { findJsonSchemaViolation, serializeJsonWithSpacedSeparators } from "./json-schema-validation.js";
-import { pairToolCallsWithResults, readStoredModelInputItem, toStepwiseFrameworkMessage, } from "./stepwise-input-items.js";
-const toolSourceMethods = ["listTools", "deferredToolCall", "executeDeferredToolCall", "pollToolTask"];
+import { pairToolCallsWithResults, readStoredModelInputItem, toBuiltinLoopFrameworkMessage, } from "./builtin-loop-input-items.js";
+import { ToolSourceRouter, defaultToolSourceListingTimeoutMs, readToolSourceEnvelope as readRouterToolSourceEnvelope, writeToolSourceEnvelope as writeRouterToolSourceEnvelope, } from "../tool-source-router.js";
+export { defaultToolSourceListingTimeoutMs } from "../tool-source-router.js";
 // The runner's envelope around a source's toolSourceReference: the building source's name.
 const toolSourceNameKey = "stepwise_tool_source";
 // An unlisted name never reaches a source, so it fails without asking anyone to approve it.
 const unlistedSourceToolPolicy = { effect: "unclassified", requiresApproval: false };
-const toolSourceReferenceKey = "reference";
-/** Default {@link AgentDefinition.toolSourceListingTimeoutMs}: 10 seconds. */
-export const defaultToolSourceListingTimeoutMs = 10_000;
 export const defaultMaxModelCallsPerTurn = 100;
+/**
+ * How many {@link ContinueTurn} results of {@link AgentDefinition.decideTurnContinuation} may follow answers without
+ * tool calls in a row. A model response with tool calls resets the count.
+ * @since 0.5.0
+ */
+export const maxConsecutiveTurnContinuations = 8;
 /** Result of a tool call the model made after the turn's model call limit; the same text as the Python core. */
 export function buildToolCallLimitReachedResult(maxModelCallsPerTurn) {
     return `The tool call was not run: this turn reached its limit of ${maxModelCallsPerTurn} model calls.`;
 }
+/**
+ * The `lastTurnError` of a turn whose `decideTurnContinuation` returned a {@link ContinueTurn} once too often in a
+ * row; the same text as the Python core.
+ * @param limit - {@link maxConsecutiveTurnContinuations}.
+ * @returns The error text.
+ */
+export function buildTurnContinuationLimitError(limit) {
+    return `the turn reached its limit of ${limit} consecutive continuations without a tool call`;
+}
 // The summary is not the assistant's answer, so its live text goes nowhere.
 const discardedModelOutput = {
     writeTextDelta: () => undefined,
     writeReasoningDelta: () => undefined,
 };
 /**
- * The {@link AgentFrameworkRunner} of the built-in Stepwise loop.
+ * The {@link AgentFrameworkRunner} of the built-in agent loop.
  *
- * {@link createStepwiseAgentSessionFlow} creates one; construct it directly only to pass it to
+ * {@link createBuiltinAgentSessionFlow} creates one; construct it directly only to pass it to
  * `createAgentSessionFlow` with options of your own. Each `RunModel` makes at most one model call
  * through {@link AgentDefinition.model}, from committed state only: the stored messages, the results
  * of the previous model response from the turn's final records, and the instructions. The runner
@@ -46,34 +61,55 @@ const discardedModelOutput = {
  * tasks. Its {@link cancelToolTask} passes a task that `cancel_turn` abandoned to that source's optional
  * `cancelToolTask`.
  *
+ * With a media store, the runner shows images to the model. It then has `buildUserMessageWithImages` of
+ * {@link AgentFrameworkRunner}, as an own property, so `send_user_message` accepts images: the stored `user_text` item keeps their references after the text. A tool
+ * result item keeps the references of `AgentToolCall.images`. Before each model call, the runner reads the bytes of
+ * every image in the request with `loadImages` and passes them in `ModelRequest.imageBytes`; the model client
+ * converts each image to the provider's image part. A failed read fails that `RunModel` attempt, which retries. The
+ * model call that writes a context summary sees the text of the items only. Without a store the session refuses
+ * user images, and a tool source result's images are stored but not shown to the model. A function tool's images fail
+ * the call instead, without a retry. The class declares neither member, so a subclass may still define its own
+ * `buildUserMessageWithImages` or `mediaStore`; a subclass method stays in use with a store.
+ *
  * @example
  * ```ts
- * const runner = new StepwiseAgentRunner(definition);
+ * const runner = new BuiltinLoopAgentRunner(definition);
  * const flow = createAgentSessionFlow(runner, "SupportAgent", { builtInTools: ["ask_user"] });
  * ```
+ *
+ * It replaces `StepwiseAgentRunner`, which `@superdurable/dex-agents/stepwise` keeps as a deprecated alias.
+ *
+ * @since 0.5.0
  */
-export class StepwiseAgentRunner {
+export class BuiltinLoopAgentRunner {
     /** The agent definition, frozen at construction. */
     definition;
     /** The runner honors {@link AgentTurnContext.interactionMode}, so plan mode can be enabled. */
     supportsPlanMode = true;
     functionToolsByName;
     toolSources;
-    toolSourcesByName;
     maxModelCallsPerTurn;
-    toolSourceListingTimeoutMs;
-    /** The last listing of each source, so estimates count its tools without listing again. */
-    lastListings = new Map();
+    // An ES private field, so it never collides with a subclass member.
+    #mediaStore;
     /**
      * Creates the runner and checks the definition.
      * @param definition - The agent definition.
-     * @throws {TypeError} When the name, instructions, model, or tools are invalid, two tools share a
-     * name, a function tool uses the name of an enabled built-in tool, `planModeEnabled` is set without
+     * @param mediaStore - The store that holds the session's images, such as `S3MediaStore`. With it, the runner
+     * accepts user messages with images and shows them and tool result images to the model, reading the bytes for
+     * each model call; stored messages hold only references. It also gets an own `buildUserMessageWithImages`, which
+     * stores user text and its images as one `user_text` item that holds the references, not the bytes, unless a
+     * subclass defines its own `buildUserMessageWithImages`, which then stays in use. Use the store
+     * the clients and tools upload to. Omit it to refuse user images and show tool result images to the model as text
+     * only. Since 0.5.0.
+     *
+     * Changed in 0.5.0: takes `mediaStore`.
+     * @throws {TypeError} When the name, instructions, model, tools, or `decideTurnContinuation` are invalid, two tools
+     * share a name, a function tool uses the name of an enabled built-in tool, `planModeEnabled` is set without
      * `write_todos`, `planningToolChoice` is neither `auto` nor `required`, or a tool source lacks a
      * {@link ToolSource} method.
      * @throws {RangeError} When `maxModelCallsPerTurn` is not a positive integer.
      */
-    constructor(definition) {
+    constructor(definition, mediaStore = undefined) {
         if (typeof definition?.name !== "string" || definition.name.trim() === "") {
             throw new TypeError("AgentDefinition.name must be a non-blank string");
         }
@@ -86,6 +122,9 @@ export class StepwiseAgentRunner {
         if (definition.resolveModel !== undefined && typeof definition.resolveModel !== "function") {
             throw new TypeError("AgentDefinition.resolveModel must be a function");
         }
+        if (definition.decideTurnContinuation !== undefined && typeof definition.decideTurnContinuation !== "function") {
+            throw new TypeError("AgentDefinition.decideTurnContinuation must be a function");
+        }
         const enabledBuiltInTools = new Set(definition.builtInTools ?? []);
         const functionToolsByName = new Map();
         for (const tool of definition.tools ?? []) {
@@ -100,28 +139,17 @@ export class StepwiseAgentRunner {
             }
             functionToolsByName.set(tool.name, tool);
         }
-        const toolSources = [...(definition.toolSources ?? [])];
-        for (const source of toolSources) {
-            const missing = toolSourceMethods.find((method) => typeof source?.[method] !== "function");
-            if (missing !== undefined) {
-                throw new TypeError(`tool source ${String(source)} has no ${missing} method`);
-            }
-        }
-        const toolSourcesByName = new Map();
-        for (const source of toolSources) {
-            if (typeof source.sourceName !== "string" || source.sourceName.trim() === "") {
-                throw new TypeError(`tool source ${String(source)} needs a non-blank sourceName`);
-            }
-            if (toolSourcesByName.has(source.sourceName)) {
-                throw new TypeError(`two tool sources are named ${source.sourceName}`);
-            }
-            toolSourcesByName.set(source.sourceName, source);
-        }
-        refuseDeclaredToolNameCollisions(toolSources, new Set(functionToolsByName.keys()), enabledBuiltInTools);
         const toolSourceListingTimeoutMs = definition.toolSourceListingTimeoutMs ?? defaultToolSourceListingTimeoutMs;
         if (!(toolSourceListingTimeoutMs > 0)) {
             throw new RangeError("AgentDefinition.toolSourceListingTimeoutMs must be positive");
         }
+        const toolSources = new ToolSourceRouter(definition.toolSources ?? [], {
+            sourceNameKey: toolSourceNameKey,
+            localToolNames: new Set(functionToolsByName.keys()),
+            localToolDescription: "a function tool",
+            builtInToolNames: enabledBuiltInTools,
+            listingTimeoutMs: toolSourceListingTimeoutMs,
+        });
         if (definition.planModeEnabled === true && !enabledBuiltInTools.has("write_todos")) {
             throw new TypeError("planModeEnabled requires the write_todos built-in tool");
         }
@@ -136,9 +164,14 @@ export class StepwiseAgentRunner {
         this.definition = Object.freeze({ ...definition });
         this.functionToolsByName = functionToolsByName;
         this.toolSources = toolSources;
-        this.toolSourcesByName = toolSourcesByName;
-        this.toolSourceListingTimeoutMs = toolSourceListingTimeoutMs;
         this.maxModelCallsPerTurn = maxModelCallsPerTurn;
+        this.#mediaStore = mediaStore;
+        if (mediaStore !== undefined) {
+            // The session accepts images only from a runner with this method; the class leaves it undeclared for subclasses.
+            const runner = this;
+            // A subclass's own method is already on the prototype chain, and it stays in use.
+            runner.buildUserMessageWithImages ??= (text, images) => toBuiltinLoopFrameworkMessage({ type: "user_text", text, images: [...images] });
+        }
     }
     /**
      * Converts user text into a stored `user_text` item.
@@ -146,31 +179,76 @@ export class StepwiseAgentRunner {
      * @returns The message with role `user`.
      */
     buildUserMessage(text) {
-        return toStepwiseFrameworkMessage({ type: "user_text", text });
+        return toBuiltinLoopFrameworkMessage({ type: "user_text", text });
     }
     /**
      * Makes the turn's next model call.
      * @param turn - The turn context.
      * @returns {@link TurnCompleted} with the results and final answer not stored yet, or
-     * {@link ToolCallsRequested} with the previous results, this response, and its tool calls.
+     * {@link ToolCallsRequested} with the previous results, this response, and its tool calls. When
+     * {@link AgentDefinition.decideTurnContinuation} returns `"end"` after tool calls, a {@link TurnCompleted} with only
+     * the results and zero usage, without a model call. When it continues after tool calls, its message follows the
+     * results in the request and in the stored messages. When it continues after an answer, a {@link TurnContinued}
+     * with the previous results, this response, and the message as user text, or a {@link TurnCompleted} with
+     * {@link TurnCompleted.turnError} once {@link maxConsecutiveTurnContinuations} is exceeded.
      * @throws {TypeError} When a function tool uses the name of an enabled built-in tool, or a tool source lists a
      * name that repeats a function tool, an enabled built-in tool, or another source's tool. No model request is
-     * made.
-     * @throws Any error of the model call or of a tool source's `listTools`, which retries the `RunModel` attempt.
+     * made. Also when `decideTurnContinuation` returns another value.
+     * @throws Any error of the model call, of the media store, of a tool source's `listTools`, or of
+     * `decideTurnContinuation`, which retries the `RunModel` attempt.
      */
     async runModelStep(turn) {
         this.requireNoBuiltInToolNameClash(turn);
-        const modelCallCount = readModelCallCount(turn.frameworkRunState);
+        const runState = readBuiltinLoopRunState(turn.frameworkRunState);
+        const modelCallCount = runState.modelCalls;
         const unstoredToolResults = buildUnstoredToolResults(turn);
+        const unstoredItems = [...unstoredToolResults];
+        if (unstoredToolResults.length > 0 && this.definition.decideTurnContinuation !== undefined) {
+            const decision = await this.decideTurnContinuation(turn, readLatestModelOutput(turn), unstoredToolResults);
+            if (decision === "end") {
+                return {
+                    kind: "completed",
+                    newMessages: unstoredToolResults.map(toBuiltinLoopFrameworkMessage),
+                    usage: emptyAgentUsage(),
+                };
+            }
+            if (decision !== "default") {
+                unstoredItems.push({ type: "user_text", text: decision.message });
+            }
+        }
         const isToolBudgetSpent = modelCallCount >= this.maxModelCallsPerTurn;
-        const sourceTools = isToolBudgetSpent || turn.interactionMode === "planning" ? new Map() : await this.listSourceTools(turn);
-        const request = await this.buildModelRequest(turn, unstoredToolResults, modelCallCount, isToolBudgetSpent, sourceTools);
-        const response = await this.resolveModel(turn.sessionSettings).callModel(request, turn.events);
+        const sourceTools = isToolBudgetSpent || turn.interactionMode === "planning"
+            ? new Map()
+            : await this.toolSources.listSourceTools(turn.enabledBuiltInTools ?? new Set());
+        const request = await this.buildModelRequest(turn, unstoredItems, modelCallCount, isToolBudgetSpent, sourceTools);
+        const response = await this.resolveModel(turn.sessionSettings).callModel(await this.addImageBytes(request), turn.events);
         requireModelResponse(response);
         const usage = { ...response.usage, modelCalls: 1 };
-        const newMessages = [...unstoredToolResults, ...response.outputItems].map(toStepwiseFrameworkMessage);
+        const newMessages = [...unstoredItems, ...response.outputItems].map(toBuiltinLoopFrameworkMessage);
         if (response.toolCalls.length === 0) {
-            return { kind: "completed", newMessages, usage };
+            const decision = await this.decideTurnContinuation(turn, response.outputItems, []);
+            if (decision === "end" || decision === "default") {
+                return { kind: "completed", newMessages, usage };
+            }
+            const consecutiveContinuations = runState.consecutiveContinuations + 1;
+            if (consecutiveContinuations > maxConsecutiveTurnContinuations) {
+                return {
+                    kind: "completed",
+                    newMessages,
+                    usage,
+                    turnError: buildTurnContinuationLimitError(maxConsecutiveTurnContinuations),
+                };
+            }
+            return {
+                kind: "turn_continued",
+                frameworkRunState: serializeJsonWithSpacedSeparators({
+                    model_calls: modelCallCount + 1,
+                    consecutive_continuations: consecutiveContinuations,
+                }),
+                // The message makes the next request end with user text, as every provider requires.
+                newMessages: [...newMessages, toBuiltinLoopFrameworkMessage({ type: "user_text", text: decision.message })],
+                usage,
+            };
         }
         if (isToolBudgetSpent) {
             // The model asked for tools although none were offered; end the turn so it cannot loop.
@@ -182,7 +260,7 @@ export class StepwiseAgentRunner {
             }));
             return {
                 kind: "completed",
-                newMessages: [...newMessages, ...notRunResults.map(toStepwiseFrameworkMessage)],
+                newMessages: [...newMessages, ...notRunResults.map(toBuiltinLoopFrameworkMessage)],
                 usage,
             };
         }
@@ -193,11 +271,7 @@ export class StepwiseAgentRunner {
             toolCalls: response.toolCalls.map((toolCall) => {
                 const listed = sourceTools.get(toolCall.toolName);
                 if (listed !== undefined) {
-                    const built = listed.source.deferredToolCall(turn, { ...toolCall, listedTool: listed.tool });
-                    return {
-                        ...built,
-                        toolSourceReference: writeToolSourceEnvelope(listed.source.sourceName, built.toolSourceReference),
-                    };
+                    return this.toolSources.buildDeferredToolCall(turn, listed, toolCall);
                 }
                 return {
                     toolCallId: toolCall.toolCallId,
@@ -210,14 +284,22 @@ export class StepwiseAgentRunner {
         };
     }
     /**
-     * Runs one function tool call after checking its arguments against the tool's schema, or passes a call that a
+     * Runs one function tool call after converting its arguments with the tool's `prepareArguments`, when it has
+     * one, and checking them against the tool's schema, or passes a call that a
      * tool source built in `runModelStep` to that source, with the source's own `toolSourceReference` and without a
      * listing. Any other name is an unknown tool and never reaches a source.
+     * A function tool's {@link ToolCallContext.mediaStore} is this runner's store.
+     *
+     * Changed in 0.5.0: a function tool receives the media store and may return a {@link FunctionToolResult} with
+     * images.
      * @param call - The deferred call.
-     * @returns The output: a `string` result unchanged, any other result as JSON; the tool's
-     * {@link ToolInputRequested}; or a source's outcome, such as {@link ToolTaskStarted}.
+     * @returns The output: a `string` result unchanged, a {@link FunctionToolResult} as its output and images, any
+     * other result as JSON; the tool's {@link ToolInputRequested}; or a source's outcome, such as
+     * {@link ToolTaskStarted}.
      * @throws {ToolExecutionError} For an unknown tool, arguments that are not a JSON object or break the
-     * schema, or a `ToolExecutionError` from the tool or its source.
+     * schema, a non-cancellation error or a thenable result of the tool's `prepareArguments`, a
+     * `ToolExecutionError` from the tool or its source, or a function tool that returned images while this runner has
+     * no media store.
      * @throws {RangeError} When a source built the call but the definition no longer has it, so the effect decides
      * the outcome.
      * @throws Any other error of the tool source.
@@ -226,13 +308,12 @@ export class StepwiseAgentRunner {
         const toolCall = call.toolCall;
         const tool = this.functionToolsByName.get(toolCall.toolName);
         if (tool === undefined) {
-            const routed = this.routeToToolSource(toolCall);
-            if (routed === undefined) {
+            if (!this.toolSources.isSourceToolCall(toolCall)) {
                 throw new ToolExecutionError(buildUnknownToolError(toolCall.toolName));
             }
-            return routed.source.executeDeferredToolCall({ ...call, toolCall: withToolSourceReference(toolCall, routed.reference) });
+            return this.toolSources.executeDeferredToolCall(call);
         }
-        const toolArguments = parseToolArguments(tool.name, toolCall.arguments);
+        const toolArguments = prepareToolArguments(tool, toolCall.arguments, call.cancellationSignal);
         const violation = findJsonSchemaViolation(toolArguments, tool.parameters, "arguments");
         if (violation !== undefined) {
             throw new ToolExecutionError(`invalid arguments for ${tool.name}: ${violation}`);
@@ -243,12 +324,14 @@ export class StepwiseAgentRunner {
             toolCallId: toolCall.toolCallId,
             idempotencyKey: call.idempotencyKey,
             attempt: call.attempt,
+            effect: toolCall.effect,
             events: call.events,
             cancellationSignal: call.cancellationSignal,
             deadline: call.deadline,
             inputAnswers: call.inputAnswers ?? [],
             inputContinuation: toolCall.inputContinuation ?? null,
             heartbeat: () => call.heartbeat(),
+            ...(this.#mediaStore === undefined ? {} : { mediaStore: this.#mediaStore }),
         };
         const result = await tool.execute(toolArguments, context);
         if (typeof result === "string") {
@@ -257,8 +340,20 @@ export class StepwiseAgentRunner {
         if (result?.kind === "tool_input_requested") {
             return result;
         }
+        if (isFunctionToolResult(result)) {
+            return this.toToolExecutionResult(tool.name, result);
+        }
         return { output: serializeJsonWithSpacedSeparators(result === undefined ? null : result) };
     }
+    toToolExecutionResult(toolName, result) {
+        if (result.images === undefined || result.images.length === 0) {
+            return { output: result.output };
+        }
+        if (this.#mediaStore === undefined) {
+            throw new ToolExecutionError(`function tool ${toolName} returned images, but the runner has no media store`);
+        }
+        return { output: result.output, images: result.images };
+    }
     /**
      * Polls a tool source's task once, through the source that built the call.
      * @param poll - The call's record from `PollToolTask`.
@@ -268,11 +363,22 @@ export class StepwiseAgentRunner {
      * @throws Any error of the source.
      */
     async pollToolTask(poll) {
-        const routed = this.routeToToolSource(poll.toolCall);
-        if (routed === undefined) {
-            throw new RangeError(`no tool source built the call of tool ${poll.toolCall.toolName}`);
+        return this.toolSources.pollToolTask(poll);
+    }
+    /**
+     * Returns a tool source's options for one call's tool Step. Function tools and sources without
+     * `toolCallStepOptions` keep the tool Steps' defaults.
+     * @param toolCall - The record whose tool Step starts.
+     * @returns The source's options, or `undefined` for the defaults.
+     * @throws {RangeError} When a source built the call but the definition no longer has it; the session then uses
+     * the defaults.
+     * @since 0.4.0
+     */
+    toolCallStepOptions(toolCall) {
+        if (this.functionToolsByName.has(toolCall.toolName)) {
+            return undefined;
         }
-        return routed.source.pollToolTask({ ...poll, toolCall: withToolSourceReference(poll.toolCall, routed.reference) });
+        return this.toolSources.toolCallStepOptions(toolCall);
     }
     /**
      * Cancels a tool source's task through the source that built the call; a source without `cancelToolTask` leaves
@@ -284,14 +390,7 @@ export class StepwiseAgentRunner {
      * @throws Any error of the source.
      */
     async cancelToolTask(cancellation) {
-        const routed = this.routeToToolSource(cancellation.toolCall);
-        if (routed === undefined) {
-            throw new RangeError(`no tool source built the call of tool ${cancellation.toolCall.toolName}`);
-        }
-        await routed.source.cancelToolTask?.({
-            ...cancellation,
-            toolCall: withToolSourceReference(cancellation.toolCall, routed.reference),
-        });
+        await this.toolSources.cancelToolTask(cancellation);
     }
     /**
      * Returns the results of the turn's tool calls that are not stored yet.
@@ -299,7 +398,7 @@ export class StepwiseAgentRunner {
      * @returns One `tool_result` message per unstored result, in deferral order.
      */
     buildUnfinishedTurnMessages(turn) {
-        return buildUnstoredToolResults(turn).map(toStepwiseFrameworkMessage);
+        return buildUnstoredToolResults(turn).map(toBuiltinLoopFrameworkMessage);
     }
     /**
      * Estimates the model input of the next `runModelStep` with the model client.
@@ -309,10 +408,10 @@ export class StepwiseAgentRunner {
      * when it has one, else from the runner's last listing, as in the Python core.
      */
     async estimateInputTokens(turn) {
-        const modelCallCount = readModelCallCount(turn.frameworkRunState);
+        const modelCallCount = readBuiltinLoopRunState(turn.frameworkRunState).modelCalls;
         const isToolBudgetSpent = modelCallCount >= this.maxModelCallsPerTurn;
-        const request = await this.buildModelRequest(turn, buildUnstoredToolResults(turn), modelCallCount, isToolBudgetSpent, this.readCachedSourceTools());
-        return this.resolveModel(turn.sessionSettings).estimateInputTokens(request);
+        const request = await this.buildModelRequest(turn, buildUnstoredToolResults(turn), modelCallCount, isToolBudgetSpent, this.toolSources.readCachedSourceTools());
+        return this.resolveModel(turn.sessionSettings).estimateInputTokens(this.keepShownImagesOnly(request));
     }
     /**
      * Chooses the last message to summarize, at a boundary between model responses.
@@ -370,7 +469,11 @@ export class StepwiseAgentRunner {
                 request.inputTokenBudget - (this.definition.modelSettings?.maxOutputTokens ?? 0);
         if (budget !== undefined) {
             // Estimate by parts, then leave out the oldest items up to the first cut that fits.
-            const itemTokens = rangeItems.map((item) => model.estimateInputTokens({ ...this.buildSummaryRequest(request, [], 0), instructions: "", inputItems: [item] }));
+            const itemTokens = rangeItems.map((item) => model.estimateInputTokens({
+                ...this.buildSummaryRequest(request, [], 0),
+                instructions: "",
+                inputItems: stripImages([item]),
+            }));
             let tokens = model.estimateInputTokens(this.buildSummaryRequest(request, [], rangeItems.length)) +
                 itemTokens.reduce((total, itemToken) => total + itemToken, 0);
             // A cut never splits a model response or separates a tool call from its result.
@@ -397,7 +500,8 @@ export class StepwiseAgentRunner {
         if (omittedCount > 0) {
             items.push({ type: "user_text", text: buildContextSummaryOmissionNote(omittedCount) });
         }
-        items.push(...rangeItems, { type: "user_text", text: contextSummaryRequest });
+        // The summary call reads no image bytes, so it sees each item's text only.
+        items.push(...stripImages(rangeItems), { type: "user_text", text: contextSummaryRequest });
         return {
             instructions: contextSummaryInstructions,
             inputItems: pairToolCallsWithResults(items),
@@ -413,7 +517,7 @@ export class StepwiseAgentRunner {
             cancellationSignal: request.cancellationSignal,
         };
     }
-    async buildModelRequest(turn, unstoredToolResults, modelCallCount, isToolBudgetSpent, sourceTools) {
+    async buildModelRequest(turn, unstoredItems, modelCallCount, isToolBudgetSpent, sourceTools) {
         const contextSummary = turn.contextSummary ?? null;
         const summaryItems = contextSummary === null ? [] : [{ type: "user_text", text: buildContextSummaryNote(contextSummary) }];
         let toolChoice = isToolBudgetSpent ? "none" : "auto";
@@ -426,7 +530,7 @@ export class StepwiseAgentRunner {
             inputItems: pairToolCallsWithResults([
                 ...summaryItems,
                 ...readStoredInputItemsWithPlanNote(turn),
-                ...unstoredToolResults,
+                ...unstoredItems,
             ]),
             tools: isToolBudgetSpent ? [] : this.listOfferedTools(turn, sourceTools),
             toolChoice,
@@ -441,7 +545,7 @@ export class StepwiseAgentRunner {
         }
         return this.resolveModel(turn.sessionSettings).estimateInputTokens({
             instructions: "",
-            inputItems: items,
+            inputItems: this.#mediaStore === undefined ? stripImages(items) : items,
             tools: [],
             toolChoice: "none",
             settings: this.definition.modelSettings ?? {},
@@ -449,6 +553,21 @@ export class StepwiseAgentRunner {
             cancellationSignal: turn.cancellationSignal,
         });
     }
+    /** Returns the request with the bytes of its images, read from the store right now. */
+    async addImageBytes(request) {
+        if (this.#mediaStore === undefined) {
+            return this.keepShownImagesOnly(request);
+        }
+        const references = request.inputItems.flatMap((item) => item.type === "model_output" ? [] : (item.images ?? []));
+        if (references.length === 0) {
+            return request;
+        }
+        return { ...request, imageBytes: await loadImages(this.#mediaStore, references) };
+    }
+    keepShownImagesOnly(request) {
+        // Without a store the model sees no image, such as a tool source's.
+        return this.#mediaStore === undefined ? { ...request, inputItems: stripImages(request.inputItems) } : request;
+    }
     /** A built-in enabled only in the session options must not share a function tool's name. */
     requireNoBuiltInToolNameClash(turn) {
         for (const builtInTool of turn.enabledBuiltInTools ?? []) {
@@ -457,75 +576,6 @@ export class StepwiseAgentRunner {
             }
         }
     }
-    async listSourceTools(turn) {
-        const enabledBuiltInTools = turn.enabledBuiltInTools ?? new Set();
-        const functionToolNames = new Set(this.functionToolsByName.keys());
-        const listed = new Map();
-        for (const [index, source] of this.toolSources.entries()) {
-            for (const tool of await this.listOneSource(index, source)) {
-                refuseSourceToolName(tool.name, functionToolNames, enabledBuiltInTools, listed);
-                listed.set(tool.name, { index, source, tool });
-            }
-        }
-        return listed;
-    }
-    async listOneSource(index, source) {
-        const listing = source.listTools();
-        // A listing that outlives this call keeps running; nobody else reads its error.
-        listing.catch(() => undefined);
-        let timer;
-        const timedOut = new Promise((resolve) => {
-            timer = setTimeout(() => resolve("timed_out"), this.toolSourceListingTimeoutMs);
-        });
-        try {
-            const tools = await Promise.race([listing, timedOut]);
-            if (tools === "timed_out") {
-                console.warn(`tool source ${index} listed nothing within ${this.toolSourceListingTimeoutMs} ms`);
-                return [];
-            }
-            this.lastListings.set(index, tools);
-            return tools;
-        }
-        catch (error) {
-            console.warn(`tool source ${index} could not list its tools: ${error instanceof Error ? error.message : String(error)}`);
-            return [];
-        }
-        finally {
-            clearTimeout(timer);
-        }
-    }
-    readCachedSourceTools() {
-        const cached = new Map();
-        for (const [index, source] of this.toolSources.entries()) {
-            const tools = source.cachedTools?.() ?? this.lastListings.get(index) ?? [];
-            for (const tool of tools) {
-                if (!cached.has(tool.name)) {
-                    cached.set(tool.name, { index, source, tool });
-                }
-            }
-        }
-        return cached;
-    }
-    routeToToolSource(toolCall) {
-        const envelope = readToolSourceEnvelope(toolCall.toolSourceReference);
-        if (envelope !== undefined) {
-            const source = this.toolSourcesByName.get(envelope.sourceName);
-            if (source === undefined) {
-                throw new RangeError(`tool source ${envelope.sourceName}, which built the call of tool ${toolCall.toolName}, is not configured on this Worker`);
-            }
-            return { source, reference: envelope.reference };
-        }
-        const reference = toolCall.toolSourceReference ?? undefined;
-        if (reference === undefined || this.toolSources.length === 0) {
-            return undefined;
-        }
-        const onlySource = this.toolSources.length === 1 ? this.toolSources[0] : undefined;
-        if (onlySource !== undefined) {
-            // A reference the source built itself, such as in a runner subclass.
-            return { source: onlySource, reference };
-        }
-        throw new RangeError(`cannot tell which tool source built the call of ${toolCall.toolName}`);
-    }
     listOfferedTools(turn, sourceTools) {
         const isPlanning = turn.interactionMode === "planning";
         const enabledBuiltInTools = turn.enabledBuiltInTools ?? new Set();
@@ -556,7 +606,7 @@ export class StepwiseAgentRunner {
     resolveModelToolPolicy(turn, toolName) {
         const tool = this.functionToolsByName.get(toolName);
         const isBuiltIn = turn.enabledBuiltInTools?.has(toolName) === true;
-        if (tool === undefined && this.toolSources.length > 0 && !isBuiltIn) {
+        if (tool === undefined && this.toolSources.hasToolSources && !isBuiltIn) {
             return unlistedSourceToolPolicy;
         }
         const sessionPolicies = turn.toolPolicies ?? this.definition.toolPolicies ?? {};
@@ -601,6 +651,43 @@ export class StepwiseAgentRunner {
         }
         return resolved;
     }
+    /** Returns the hook's decision for one iteration, or `"default"` without a hook. */
+    async decideTurnContinuation(turn, modelOutput, toolResults) {
+        const decide = this.definition.decideTurnContinuation;
+        if (decide === undefined) {
+            return "default";
+        }
+        const decision = await decide({
+            flowId: turn.flowId,
+            turnId: turn.turnId,
+            sessionSettings: turn.sessionSettings ?? {},
+            modelOutput,
+            toolResults,
+        });
+        if (decision === "end" || decision === "default") {
+            return decision;
+        }
+        const continuation = decision;
+        if (typeof continuation === "object" &&
+            continuation !== null &&
+            continuation.action === "continue" &&
+            typeof continuation.message === "string" &&
+            continuation.message.trim() !== "") {
+            return { action: "continue", message: continuation.message };
+        }
+        throw new TypeError(`decideTurnContinuation of agent ${this.definition.name} must return "end", "default", or ` +
+            `{ action: "continue", message } with a non-blank message, not ${describeTurnContinuation(decision)}`);
+    }
+}
+/** Names an invalid hook result without its message text, which may hold application data. */
+function describeTurnContinuation(decision) {
+    if (typeof decision === "string") {
+        return JSON.stringify(decision);
+    }
+    if (typeof decision === "object" && decision !== null) {
+        return `an object with action ${JSON.stringify(decision.action) ?? "undefined"}`;
+    }
+    return String(decision);
 }
 /** A planning turn without a draft drafts one first; feedback on a draft may only answer. */
 function mustWritePlanFirst(turn, modelCallCount) {
@@ -640,31 +727,100 @@ function buildUnstoredToolResults(turn) {
         toolCallId: record.toolCallId,
         toolName: record.toolName,
         output: describeToolCallOutcome(record),
+        ...((record.images ?? []).length === 0 ? {} : { images: record.images }),
     }));
 }
-function parseToolArguments(toolName, argumentsText) {
+function stripImages(items) {
+    return items.map((item) => {
+        if (item.type === "model_output" || (item.images ?? []).length === 0) {
+            return item;
+        }
+        const { images: _images, ...withoutImages } = item;
+        return withoutImages;
+    });
+}
+function prepareToolArguments(tool, argumentsText, cancellationSignal) {
     let parsed;
     try {
         parsed = JSON.parse(argumentsText === "" ? "{}" : argumentsText);
     }
     catch {
         // A fixed text, because the two cores' JSON parsers word their errors differently.
-        throw new ToolExecutionError(`invalid arguments for ${toolName}: arguments are not valid JSON`);
+        throw new ToolExecutionError(`invalid arguments for ${tool.name}: arguments are not valid JSON`);
+    }
+    if (tool.prepareArguments !== undefined) {
+        try {
+            parsed = tool.prepareArguments(parsed);
+        }
+        catch (error) {
+            if (isCancellation(error, cancellationSignal)) {
+                throw error;
+            }
+            // Any other error, so a failed conversion never retries or records outcome_unknown.
+            const message = error instanceof Error ? error.message : String(error);
+            throw new ToolExecutionError(`invalid arguments for ${tool.name}: ${message}`);
+        }
+        if (isThenable(parsed)) {
+            if (parsed instanceof Promise) {
+                observePromiseRejection(parsed);
+            }
+            throw new ToolExecutionError(`invalid arguments for ${tool.name}: argument conversion must be synchronous`);
+        }
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw new ToolExecutionError(`invalid arguments for ${toolName}: expected a JSON object`);
+        throw new ToolExecutionError(`invalid arguments for ${tool.name}: expected a JSON object`);
     }
     return parsed;
 }
-function readModelCallCount(frameworkRunState) {
+/** Reads `then` without calling it; a throwing `then` getter counts as a thenable, so it is refused too. */
+function isThenable(value) {
+    if ((typeof value !== "object" || value === null) && typeof value !== "function") {
+        return false;
+    }
+    try {
+        return typeof value.then === "function";
+    }
+    catch {
+        return true;
+    }
+}
+/** Observes a refused Promise's rejection through the native `then`, so a subclass's own `then` never runs. */
+function observePromiseRejection(promise) {
+    try {
+        void Promise.prototype.then.call(promise, undefined, () => undefined);
+    }
+    catch {
+        // A subclass constructor may throw; the result is refused either way.
+    }
+}
+function isCancellation(error, cancellationSignal) {
+    if (cancellationSignal.aborted && error === cancellationSignal.reason) {
+        return true;
+    }
+    return error?.name === "AbortError";
+}
+function readBuiltinLoopRunState(frameworkRunState) {
     if (frameworkRunState === null) {
-        return 0;
+        return { modelCalls: 0, consecutiveContinuations: 0 };
     }
     const parsed = JSON.parse(frameworkRunState);
-    if (typeof parsed.model_calls !== "number" || !Number.isSafeInteger(parsed.model_calls)) {
-        throw new TypeError("FrameworkRunState is not a Stepwise run state");
-    }
-    return parsed.model_calls;
+    const consecutiveContinuations = parsed.consecutive_continuations ?? 0;
+    if (typeof parsed.model_calls !== "number" ||
+        !Number.isSafeInteger(parsed.model_calls) ||
+        typeof consecutiveContinuations !== "number" ||
+        !Number.isSafeInteger(consecutiveContinuations)) {
+        throw new TypeError("FrameworkRunState is not a built-in loop run state");
+    }
+    return { modelCalls: parsed.model_calls, consecutiveContinuations };
+}
+/** The output items of the turn's latest model response: the turn's trailing stored `model_output` items. */
+function readLatestModelOutput(turn) {
+    const items = turn.messages.filter((message) => message.turnId === turn.turnId).map(readStoredModelInputItem);
+    let start = items.length;
+    while (start > 0 && items[start - 1]?.type === "model_output") {
+        start -= 1;
+    }
+    return items.slice(start);
 }
 function requireModelResponse(response) {
     if (!Array.isArray(response?.outputItems) ||
@@ -714,64 +870,15 @@ function modelRequestMetadata(turn) {
         attempt: turn.attempt,
     };
 }
-function refuseSourceToolName(toolName, functionToolNames, builtInTools, otherSourceTools) {
-    if (builtInTools.has(toolName)) {
-        throw new TypeError(`tool ${toolName} uses the name of an enabled built-in tool`);
-    }
-    if (functionToolNames.has(toolName)) {
-        throw new TypeError(`tool ${toolName} of a tool source uses the name of a function tool`);
-    }
-    if (otherSourceTools.has(toolName)) {
-        throw new TypeError(`two tool sources list a tool named ${toolName}`);
-    }
-}
-function refuseDeclaredToolNameCollisions(toolSources, functionToolNames, builtInTools) {
-    const declared = new Map();
-    for (const source of toolSources) {
-        const names = [...(source.declaredToolNames?.() ?? [])].sort();
-        for (const toolName of names) {
-            refuseSourceToolName(toolName, functionToolNames, builtInTools, declared);
-        }
-        for (const toolName of names) {
-            declared.set(toolName, source);
-        }
-    }
-}
 /** Error of a call to a tool that no function tool or source listing offers; the same text as the Python core. */
 export function buildUnknownToolError(toolName) {
     return `unknown tool ${toolName}`;
 }
 /** The runner's `toolSourceReference`: the source's name and its own reference, as JSON text. */
 export function writeToolSourceEnvelope(sourceName, reference) {
-    return JSON.stringify({ [toolSourceNameKey]: sourceName, [toolSourceReferenceKey]: reference ?? null });
+    return writeRouterToolSourceEnvelope(toolSourceNameKey, sourceName, reference);
 }
 export function readToolSourceEnvelope(toolSourceReference) {
-    if (toolSourceReference === undefined || toolSourceReference === null) {
-        return undefined;
-    }
-    let envelope;
-    try {
-        envelope = JSON.parse(toolSourceReference);
-    }
-    catch {
-        return undefined;
-    }
-    if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) {
-        return undefined;
-    }
-    const sourceName = envelope[toolSourceNameKey];
-    const reference = envelope[toolSourceReferenceKey];
-    if (typeof sourceName !== "string") {
-        return undefined;
-    }
-    if (reference !== null && reference !== undefined && typeof reference !== "string") {
-        return undefined;
-    }
-    return { sourceName, reference: reference ?? undefined };
-}
-/** The record as the source built it: its own reference instead of the runner's envelope. */
-function withToolSourceReference(toolCall, reference) {
-    const { toolSourceReference: _envelope, ...rest } = toolCall;
-    return (reference === undefined ? rest : { ...rest, toolSourceReference: reference });
+    return readRouterToolSourceEnvelope(toolSourceNameKey, toolSourceReference);
 }
-//# sourceMappingURL=stepwise-agent-runner.js.map
+//# sourceMappingURL=builtin-loop-agent-runner.js.map