@superdurable/dex-agents 0.4.0 → 0.5.0

package/dist/src/{stepwise → builtin-loop}/agent-definition.d.ts

@@ -4,8 +4,67 @@ import type { ModelSpendLimit } from "../agent-session-spend-limit.js";
 import type { ToolPolicy } from "../agent-framework-runner.js";
 import type { AgentPlan, InteractionMode, SessionSettings, ToolEffect } from "../agent-session-values.js";
 import type { FunctionTool } from "./function-tool.js";
-import type { ModelClient, ModelSettings } from "./model-client.js";
+import type { ModelClient, ModelOutputItem, ModelSettings, ModelToolResultItem } from "./model-client.js";
 import type { ToolSource } from "./tool-source.js";
+/**
+ * The {@link TurnContinuation} that makes the model answer again within the same turn.
+ *
+ * {@link message} is the instruction for the next model call, such as what the previous answer lacked. The runner
+ * stores it in the turn as user text, so the next model request ends with a user message, which every provider
+ * accepts.
+ *
+ * @example
+ * ```ts
+ * const continuation: ContinueTurn = { action: "continue", message: "Add the order number to your answer." };
+ * ```
+ * @since 0.5.0
+ */
+export interface ContinueTurn {
+    /** Discriminator. */
+    readonly action: "continue";
+    /** Text the model receives as the next user message of the turn. It must not be blank. */
+    readonly message: string;
+}
+/**
+ * What {@link AgentDefinition.decideTurnContinuation} returns at the end of one loop iteration.
+ *
+ * - `"end"`: end the turn now. After tool calls, the runner makes no further model call.
+ * - {@link ContinueTurn}: store its message in the turn as user text, then call the model. After an answer
+ *   without tool calls, this makes another model call instead of ending the turn. After tool calls, the message
+ *   follows the tool results in the same model call.
+ * - `"default"`: do what the loop does without the hook: call the model again after tool calls, and end the turn
+ *   after an answer.
+ *
+ * Later releases may add more forms, so handle only the values you return.
+ *
+ * @since 0.5.0
+ */
+export type TurnContinuation = "end" | "default" | ContinueTurn;
+/**
+ * What {@link AgentDefinition.decideTurnContinuation} receives at the end of one loop iteration.
+ *
+ * An iteration is one model call and the tool calls it requested. The runner never stores this context.
+ *
+ * @since 0.5.0
+ */
+export interface TurnContinuationContext {
+    /** Flow ID, which is the session ID. */
+    readonly flowId: string;
+    /** Turn ID. */
+    readonly turnId: string;
+    /** The {@link SessionSettings} the turn started with. Empty when the session has none. */
+    readonly sessionSettings: SessionSettings;
+    /**
+     * The output items of this iteration's model response, in the order the model returned them. Read
+     * {@link ModelOutputItem.text} for the answer and {@link ModelOutputItem.toolCalls} for the calls.
+     */
+    readonly modelOutput: readonly ModelOutputItem[];
+    /**
+     * The results of this iteration's tool calls, in the order the model requested them. Empty when the model
+     * answered without tool calls.
+     */
+    readonly toolResults: readonly ModelToolResultItem[];
+}
 /**
  * How the first model call of a planning turn without a draft uses `write_todos`, as
  * {@link AgentDefinition.planningToolChoice}: `auto` lets the model choose, and `required` forces it.
@@ -33,9 +92,9 @@ export interface InstructionContext {
     readonly sessionSettings?: SessionSettings;
 }
 /**
- * An agent defined in Dex terms, run by the built-in Stepwise loop.
+ * An agent defined in Dex terms, run by the built-in agent loop.
  *
- * Pass it to {@link createStepwiseAgentSessionFlow}. The session Flow, its Steps, approvals, events,
+ * Pass it to {@link createBuiltinAgentSessionFlow}. The session Flow, its Steps, approvals, events,
  * and RPCs are the ones every adapter uses: each model call is one `RunModel` Step, and each function
  * tool call is its own Step. Nothing replays a loop, so no code follows a determinism rule, and a
  * deployed change to the definition takes effect at the next model call.
@@ -44,9 +103,9 @@ export interface InstructionContext {
  * ```ts
  * import { openai } from "@ai-sdk/openai";
  * import { createAiSdkModelClient } from "@superdurable/dex-agents/ai-sdk";
- * import { createStepwiseAgentSessionFlow } from "@superdurable/dex-agents/stepwise";
+ * import { createBuiltinAgentSessionFlow } from "@superdurable/dex-agents/builtin-loop";
  *
- * export const supportAgentFlow = createStepwiseAgentSessionFlow(
+ * export const supportAgentFlow = createBuiltinAgentSessionFlow(
  *   {
  *     name: "support",
  *     instructions: "You help customers with their orders.",
@@ -163,4 +222,60 @@ export interface AgentDefinition {
      * @since 0.3.0
      */
     readonly spendLimit?: ModelSpendLimit;
+    /**
+     * Decides, at the end of each loop iteration, whether the turn ends or continues.
+     *
+     * Use it to stop a turn once a tool call has done the work, or to make the model try again after an answer
+     * that the application rejects. Absent, the default, the loop calls the model again after tool calls and ends
+     * the turn after an answer.
+     *
+     * The runner calls it in two places:
+     *
+     * - After a batch of tool calls, in the next `RunModel` Step, before the model call. `"end"` completes the turn
+     *   with no model call: the tool results become the turn's last messages, and the Step records zero model
+     *   calls. A {@link ContinueTurn} adds its message after the tool results, and the model call receives both.
+     *   `"default"` calls the model with the results.
+     * - After a model call that requested no tools, in the same `RunModel` Step. A {@link ContinueTurn} stores the
+     *   answer and its message as user text, then makes another model call in a new `RunModel` Step. `"end"` and
+     *   `"default"` complete the turn.
+     *
+     * The continuation message is part of the turn's transcript: the model sees it as user text, and snapshots hold
+     * it as a `user` message between the two answers. `convertAgentSnapshotToUIMessages` keeps such a message out of
+     * the chat and shows the next model call as a new step of the same assistant message, as the UI stream does.
+     *
+     * At most 8 continuations in a row may follow answers without tool calls; a tool call resets the count. The 9th
+     * ends the turn with that answer stored and the turn's `lastTurnError` set. Each continued model call counts
+     * toward {@link maxModelCallsPerTurn}.
+     *
+     * The function may be synchronous or return a Promise. It runs inside the `RunModel` attempt, so a thrown error
+     * or any other value, including a {@link ContinueTurn} with a blank message, fails that attempt, and the Step's
+     * retry policy runs it again. After an answer, that retry also repeats the model call. The function can run more
+     * than once for one iteration, so keep it free of side effects. `cancel_turn` and a steered message still end a
+     * continued turn, because the session checks them before every `RunModel` reaches the runner.
+     *
+     * @example
+     * ```ts
+     * const definition: AgentDefinition = {
+     *   name: "approvals",
+     *   instructions: "Review the request, then call submit_decision.",
+     *   model,
+     *   tools: [submitDecision],
+     *   decideTurnContinuation: ({ toolResults, modelOutput }) => {
+     *     // Once submit_decision ran, the turn is done; skip the closing model call.
+     *     if (toolResults.some((result) => result.toolName === "submit_decision")) {
+     *       return "end";
+     *     }
+     *     const answer = modelOutput.map((item) => item.text ?? "").join("");
+     *     if (toolResults.length === 0 && !answer.includes("DECISION:")) {
+     *       return { action: "continue", message: "Finish with a line that starts with DECISION:." };
+     *     }
+     *     return "default";
+     *   },
+     * };
+     * ```
+     * @param context - This iteration's model output and tool results.
+     * @returns `"end"`, `"default"`, or a {@link ContinueTurn}; see {@link TurnContinuation}.
+     * @since 0.5.0
+     */
+    readonly decideTurnContinuation?: (context: TurnContinuationContext) => TurnContinuation | Promise<TurnContinuation>;
 }

package/dist/src/builtin-loop/agent-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-definition.js","sourceRoot":"","sources":["../../../src/builtin-loop/agent-definition.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D"}

package/dist/src/builtin-loop/builtin-agent-session-flow.d.ts

@@ -0,0 +1,69 @@
+import type { MediaStore } from "../agent-media.js";
+import { type AgentSessionFlow } from "../agent-session-flow.js";
+import type { AgentDefinition } from "./agent-definition.js";
+import { BuiltinLoopAgentRunner } from "./builtin-loop-agent-runner.js";
+/**
+ * Options of {@link createBuiltinAgentSessionFlow} that are not part of the agent definition.
+ *
+ * @since 0.5.0
+ */
+export interface BuiltinAgentSessionFlowOptions {
+    /**
+     * The media store that holds the session's images, such as `S3MediaStore` from `@superdurable/dex-agents/s3`.
+     * Defaults to none.
+     *
+     * With a store, `send_user_message` accepts images, and the model sees each image of a user message or a tool
+     * result. Stored messages keep only references: the runner reads the bytes with `loadImages` right before each
+     * model call, so a store read failure fails that call and its `RunModel` Step retries. Use the same store, or one
+     * that reads the same objects, in every Worker process of the Flow type. Without a store, `send_user_message`
+     * refuses images and tool result images do not reach the model.
+     *
+     * @example
+     * ```ts
+     * import { S3MediaStore } from "@superdurable/dex-agents/s3";
+     *
+     * const mediaStore = S3MediaStore.fromStoreUri("s3://agent-media/sessions");
+     * const flow = createBuiltinAgentSessionFlow(supportAgent, "SupportAgent", { mediaStore });
+     * ```
+     * @since 0.5.0
+     */
+    readonly mediaStore?: MediaStore;
+}
+/**
+ * Creates the agent session Flow for an agent defined in Dex terms, run by the built-in agent loop.
+ *
+ * It builds the session Flow with a {@link BuiltinLoopAgentRunner} and derives the session options from
+ * the definition, so tool policies, built-in tools, plan mode, the deadlines, and compaction are declared once. The Flow is the
+ * same session Flow every adapter uses, with the same Steps, RPCs, and events. Construct it once at
+ * application startup and register the same object in the Worker and Client Registry.
+ *
+ * @example
+ * ```ts
+ * const supportAgentFlow = createBuiltinAgentSessionFlow(
+ *   {
+ *     name: "support",
+ *     instructions: "You help customers with their orders.",
+ *     model: createAiSdkModelClient(openai("gpt-5-mini")),
+ *     tools: [lookupOrder, refundOrder],
+ *     builtInTools: ["ask_user", "durable_wait"],
+ *     interruptDeadlineMs: 24 * 60 * 60 * 1000,
+ *   },
+ *   "SupportAgent",
+ * );
+ * const registry = new Registry([supportAgentFlow]);
+ * await client.startFlow(supportAgentFlow, sessionId, { initialMessage: "Where is order 42?" });
+ * ```
+ * @param definition - The agent definition.
+ * @param flowType - Flow type, unique within the Registry. Keep it stable: running sessions resume by it.
+ * @param flowOptions - The media store; see {@link BuiltinAgentSessionFlowOptions}. Since 0.5.0.
+ * @returns A new Flow; its `runner` is the {@link BuiltinLoopAgentRunner}.
+ * @throws {TypeError} When the definition is invalid; see {@link BuiltinLoopAgentRunner} and
+ * `createAgentSessionFlow`.
+ * @throws {RangeError} When a limit or deadline in the definition is out of range.
+ *
+ * It replaces `createStepwiseAgentSessionFlow`, which `@superdurable/dex-agents/stepwise` keeps as a deprecated
+ * alias.
+ *
+ * @since 0.5.0
+ */
+export declare function createBuiltinAgentSessionFlow(definition: AgentDefinition, flowType: string, flowOptions?: BuiltinAgentSessionFlowOptions): AgentSessionFlow<BuiltinLoopAgentRunner>;

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

@@ -6,18 +6,18 @@
 //
 // SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
 import { createAgentSessionFlow } from "../agent-session-flow.js";
-import { StepwiseAgentRunner } from "./stepwise-agent-runner.js";
+import { BuiltinLoopAgentRunner } from "./builtin-loop-agent-runner.js";
 /**
- * Creates the agent session Flow for an agent defined in Dex terms, run by the built-in Stepwise loop.
+ * Creates the agent session Flow for an agent defined in Dex terms, run by the built-in agent loop.
  *
- * It builds the session Flow with a {@link StepwiseAgentRunner} and derives the session options from
+ * It builds the session Flow with a {@link BuiltinLoopAgentRunner} and derives the session options from
  * the definition, so tool policies, built-in tools, plan mode, the deadlines, and compaction are declared once. The Flow is the
  * same session Flow every adapter uses, with the same Steps, RPCs, and events. Construct it once at
  * application startup and register the same object in the Worker and Client Registry.
  *
  * @example
  * ```ts
- * const supportAgentFlow = createStepwiseAgentSessionFlow(
+ * const supportAgentFlow = createBuiltinAgentSessionFlow(
  *   {
  *     name: "support",
  *     instructions: "You help customers with their orders.",
@@ -33,13 +33,19 @@ import { StepwiseAgentRunner } from "./stepwise-agent-runner.js";
  * ```
  * @param definition - The agent definition.
  * @param flowType - Flow type, unique within the Registry. Keep it stable: running sessions resume by it.
- * @returns A new Flow; its `runner` is the {@link StepwiseAgentRunner}.
- * @throws {TypeError} When the definition is invalid; see {@link StepwiseAgentRunner} and
+ * @param flowOptions - The media store; see {@link BuiltinAgentSessionFlowOptions}. Since 0.5.0.
+ * @returns A new Flow; its `runner` is the {@link BuiltinLoopAgentRunner}.
+ * @throws {TypeError} When the definition is invalid; see {@link BuiltinLoopAgentRunner} and
  * `createAgentSessionFlow`.
  * @throws {RangeError} When a limit or deadline in the definition is out of range.
+ *
+ * It replaces `createStepwiseAgentSessionFlow`, which `@superdurable/dex-agents/stepwise` keeps as a deprecated
+ * alias.
+ *
+ * @since 0.5.0
  */
-export function createStepwiseAgentSessionFlow(definition, flowType) {
-    const runner = new StepwiseAgentRunner(definition);
+export function createBuiltinAgentSessionFlow(definition, flowType, flowOptions = {}) {
+    const runner = new BuiltinLoopAgentRunner(definition, flowOptions.mediaStore);
     const options = {
         ...(definition.toolPolicies === undefined ? {} : { toolPolicies: definition.toolPolicies }),
         ...(definition.defaultToolEffect === undefined ? {} : { defaultToolEffect: definition.defaultToolEffect }),
@@ -54,4 +60,4 @@ export function createStepwiseAgentSessionFlow(definition, flowType) {
     };
     return createAgentSessionFlow(runner, flowType, options);
 }
-//# sourceMappingURL=stepwise-agent-session-flow.js.map
+//# sourceMappingURL=builtin-agent-session-flow.js.map

package/dist/src/builtin-loop/builtin-agent-session-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-agent-session-flow.js","sourceRoot":"","sources":["../../../src/builtin-loop/builtin-agent-session-flow.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAG1D,OAAO,EAAE,sBAAsB,EAAmD,MAAM,0BAA0B,CAAC;AAEnH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AA8BxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,6BAA6B,CAC3C,UAA2B,EAC3B,QAAgB,EAChB,cAA8C,EAAE;IAEhD,MAAM,MAAM,GAAG,IAAI,sBAAsB,CAAC,UAAU,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IAC9E,MAAM,OAAO,GAAwB;QACnC,GAAG,CAAC,UAAU,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,UAAU,CAAC,YAAY,EAAE,CAAC;QAC3F,GAAG,CAAC,UAAU,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,UAAU,CAAC,iBAAiB,EAAE,CAAC;QAC1G,GAAG,CAAC,UAAU,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,UAAU,CAAC,YAAY,EAAE,CAAC;QAC3F,GAAG,CAAC,UAAU,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,UAAU,CAAC,eAAe,EAAE,CAAC;QACpG,GAAG,CAAC,UAAU,CAAC,mBAAmB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,UAAU,CAAC,mBAAmB,EAAE,CAAC;QAChH,GAAG,CAAC,UAAU,CAAC,wBAAwB,KAAK,SAAS;YACnD,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,wBAAwB,EAAE,UAAU,CAAC,wBAAwB,EAAE,CAAC;QACtE,GAAG,CAAC,UAAU,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,UAAU,EAAE,CAAC;QACrF,GAAG,CAAC,UAAU,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,UAAU,EAAE,CAAC;KACtF,CAAC;IACF,OAAO,sBAAsB,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC3D,CAAC"}

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

@@ -1,16 +1,30 @@
 import { type ContextSummaryRequest, type ContextSummaryResult } from "../agent-context-compaction.js";
 export { buildContextSummaryNote, buildContextSummaryOmissionNote, contextSummaryInstructions, contextSummaryNoteHeader, contextSummaryRequest, } from "../agent-context-compaction.js";
 import { type AgentFrameworkRunner, type AgentTurnContext, type AgentTurnOutcome, type DeferredToolExecution, type DeferredToolOutcome, type ToolCallStepOptions, type ToolTaskCancellation, type ToolTaskPoll, type ToolTaskPollOutcome } from "../agent-framework-runner.js";
+import { type MediaStore } from "../agent-media.js";
 import { type AgentToolCall, type FrameworkMessage } from "../agent-session-values.js";
 import type { AgentDefinition } from "./agent-definition.js";
 export { defaultToolSourceListingTimeoutMs } from "../tool-source-router.js";
 export declare 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 declare 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 declare function buildToolCallLimitReachedResult(maxModelCallsPerTurn: number): string;
 /**
- * The {@link AgentFrameworkRunner} of the built-in Stepwise loop.
+ * 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 declare function buildTurnContinuationLimitError(limit: number): string;
+/**
+ * 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
@@ -22,13 +36,28 @@ export declare function buildToolCallLimitReachedResult(maxModelCallsPerTurn: nu
  * 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 declare class StepwiseAgentRunner implements AgentFrameworkRunner<DeferredToolOutcome> {
+export declare class BuiltinLoopAgentRunner implements AgentFrameworkRunner<DeferredToolOutcome> {
+    #private;
     /** The agent definition, frozen at construction. */
     readonly definition: AgentDefinition;
     /** The runner honors {@link AgentTurnContext.interactionMode}, so plan mode can be enabled. */
@@ -39,13 +68,22 @@ export declare class StepwiseAgentRunner implements AgentFrameworkRunner<Deferre
     /**
      * 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: AgentDefinition);
+    constructor(definition: AgentDefinition, mediaStore?: MediaStore | undefined);
     /**
      * Converts user text into a stored `user_text` item.
      * @param text - User message text.
@@ -56,27 +94,42 @@ export declare class StepwiseAgentRunner implements AgentFrameworkRunner<Deferre
      * 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.
      */
     runModelStep(turn: AgentTurnContext): Promise<AgentTurnOutcome>;
     /**
-     * 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.
      */
     executeDeferredToolCall(call: DeferredToolExecution): Promise<DeferredToolOutcome>;
+    private toToolExecutionResult;
     /**
      * Polls a tool source's task once, through the source that built the call.
      * @param poll - The call's record from `PollToolTask`.
@@ -154,6 +207,9 @@ export declare class StepwiseAgentRunner implements AgentFrameworkRunner<Deferre
     private buildSummaryRequest;
     private buildModelRequest;
     private estimateItems;
+    /** Returns the request with the bytes of its images, read from the store right now. */
+    private addImageBytes;
+    private keepShownImagesOnly;
     /** A built-in enabled only in the session options must not share a function tool's name. */
     private requireNoBuiltInToolNameClash;
     private listOfferedTools;
@@ -161,6 +217,8 @@ export declare class StepwiseAgentRunner implements AgentFrameworkRunner<Deferre
     private resolveModelToolPolicy;
     private resolveModel;
     private resolveInstructions;
+    /** Returns the hook's decision for one iteration, or `"default"` without a hook. */
+    private decideTurnContinuation;
 }
 /** Error of a call to a tool that no function tool or source listing offers; the same text as the Python core. */
 export declare function buildUnknownToolError(toolName: string): string;