@superdurable/dex-agents 0.4.0 → 0.6.0

package/dist/src/ai-sdk/ai-sdk-model-client.js

@@ -9,6 +9,12 @@ import { jsonSchema, stepCountIs, streamText, } from "ai";
 import { emptyAgentUsage } from "../agent-session-values.js";
 /** API name recorded on every output item of this client. */
 export const aiSdkModelClientApi = "ai-sdk";
+/**
+ * Input tokens `estimateInputTokens` counts for each image, whose bytes it never reads.
+ *
+ * @since 0.5.0
+ */
+export const estimatedImageInputTokens = 1600;
 const reasoningEfforts = [
     "provider-default",
     "none",
@@ -20,7 +26,7 @@ const reasoningEfforts = [
     "max",
 ];
 /**
- * Creates a Stepwise {@link ModelClient} for any AI SDK language model.
+ * Creates a built-in agent loop {@link ModelClient} for any AI SDK language model.
  *
  * Each `callModel` makes exactly one model call: one `streamText` call with `stopWhen: stepCountIs(1)`,
  * `maxRetries: 0`, and the agent's tools as definitions without `execute`. The AI SDK therefore runs no
@@ -34,6 +40,12 @@ const reasoningEfforts = [
  * model between turns. Tool results reach the model as text. For a model ID string, the string itself
  * names the provider, so a model switch between two strings replays text only.
  *
+ * Images of user text and tool result items reach the model as AI SDK `file` parts with their bytes from
+ * `ModelRequest.imageBytes`, after the item's text and in order: a user message's content is a text part and one
+ * file part per image, and a tool result with images has `content` output, a text part and one file part per
+ * image. The provider package converts them; a provider that takes no images in a tool result handles them as
+ * its package does. Changed in 0.5.0: sends images.
+ *
  * It requires the optional peer dependency `ai`, version 7.0.159 or a later 7.x release, and uses only
  * its public API; install it next to the provider package.
  *
@@ -43,7 +55,7 @@ const reasoningEfforts = [
  * import { createAiSdkModelClient } from "@superdurable/dex-agents/ai-sdk";
  *
  * const model = createAiSdkModelClient(anthropic("claude-sonnet-4-5"));
- * const flow = createStepwiseAgentSessionFlow({ name: "support", instructions, model, tools }, "SupportAgent");
+ * const flow = createBuiltinAgentSessionFlow({ name: "support", instructions, model, tools }, "SupportAgent");
  * ```
  * @param model - Any AI SDK `LanguageModel`: a provider model or a model ID string.
  * @param options - Request headers.
@@ -72,7 +84,7 @@ class AiSdkModelClient {
         const result = streamText({
             model: this.model,
             ...(request.instructions.trim() === "" ? {} : { system: request.instructions }),
-            messages: request.inputItems.reduce((messages, item) => this.appendInputItem(messages, item), []),
+            messages: request.inputItems.reduce((messages, item) => this.appendInputItem(messages, item, request.imageBytes ?? new Map()), []),
             ...(request.tools.length === 0 ? {} : { tools, toolChoice: toAiSdkToolChoice(request.toolChoice) }),
             ...(settings.temperature === undefined ? {} : { temperature: settings.temperature }),
             ...(settings.maxOutputTokens === undefined ? {} : { maxOutputTokens: settings.maxOutputTokens }),
@@ -140,12 +152,16 @@ class AiSdkModelClient {
     }
     estimateInputTokens(request) {
         const characters = request.instructions.length + JSON.stringify(request.inputItems).length + JSON.stringify(request.tools).length;
-        return Math.ceil(characters / 4);
+        const imageCount = request.inputItems.reduce((count, item) => count + (item.type === "model_output" ? 0 : (item.images ?? []).length), 0);
+        return Math.ceil(characters / 4) + imageCount * estimatedImageInputTokens;
     }
-    appendInputItem(messages, item) {
+    appendInputItem(messages, item, imageBytes) {
         switch (item.type) {
             case "user_text":
-                messages.push({ role: "user", content: [{ type: "text", text: item.text }] });
+                messages.push({
+                    role: "user",
+                    content: [{ type: "text", text: item.text }, ...toFileParts(item.images, imageBytes)],
+                });
                 return messages;
             case "model_output": {
                 const message = this.replayModelOutput(item);
@@ -155,11 +171,14 @@ class AiSdkModelClient {
                 return messages;
             }
             case "tool_result": {
+                const fileParts = toFileParts(item.images, imageBytes);
                 const part = {
                     type: "tool-result",
                     toolCallId: item.toolCallId,
                     toolName: item.toolName,
-                    output: { type: "text", value: item.output },
+                    output: fileParts.length === 0
+                        ? { type: "text", value: item.output }
+                        : { type: "content", value: [{ type: "text", text: item.output }, ...fileParts] },
                 };
                 const lastMessage = messages.at(-1);
                 if (lastMessage?.role === "tool") {
@@ -196,6 +215,16 @@ class AiSdkModelClient {
         return { role: "assistant", content };
     }
 }
+/** One AI SDK file part per image, with the bytes the runner loaded for the request. */
+function toFileParts(images, imageBytes) {
+    return (images ?? []).map((image) => {
+        const data = imageBytes.get(image.sha256);
+        if (data === undefined) {
+            throw new TypeError(`the model request has no bytes for image ${image.uri}`);
+        }
+        return { type: "file", mediaType: image.mimeType, data: { type: "data", data } };
+    });
+}
 /** The model's arguments as JSON text; an invalid call keeps its raw text, so the tool Step reports it. */
 function serializeToolInput(part) {
     if (part.invalid === true && typeof part.input === "string") {

package/dist/src/ai-sdk/ai-sdk-model-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai-sdk-model-client.js","sourceRoot":"","sources":["../../../src/ai-sdk/ai-sdk-model-client.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EACL,UAAU,EACV,WAAW,EACX,UAAU,GASX,MAAM,IAAI,CAAC;AAEZ,OAAO,EAAE,eAAe,EAAmB,MAAM,4BAA4B,CAAC;AAY9E,6DAA6D;AAC7D,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC;AAM5C,MAAM,gBAAgB,GAA+B;IACnD,kBAAkB;IAClB,MAAM;IACN,SAAS;IACT,KAAK;IACL,QAAQ;IACR,MAAM;IACN,OAAO;IACP,KAAK;CACN,CAAC;AAQF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAoB,EAAE,UAAmC,EAAE;IAChG,OAAO,IAAI,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,gBAAgB;IAID;IACA;IAJF,QAAQ,CAAS;IAElC,YACmB,KAAoB,EACpB,OAAgC;QADhC,UAAK,GAAL,KAAK,CAAe;QACpB,YAAO,GAAP,OAAO,CAAyB;QAEjD,IAAI,CAAC,QAAQ,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;IACrE,CAAC;IAEM,KAAK,CAAC,SAAS,CAAC,OAAqB,EAAE,MAAyB;QACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QAClC,MAAM,KAAK,GAAY,EAAE,CAAC;QAC1B,KAAK,MAAM,UAAU,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YACvC,MAAM,IAAI,GAAS,EAAE,WAAW,EAAE,UAAU,CAAC,WAAW,EAAE,WAAW,EAAE,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3G,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAChC,CAAC;QACD,IAAI,WAAoD,CAAC;QACzD,MAAM,MAAM,GAAG,UAAU,CAAC;YACxB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC;YAC/E,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,MAAM,CAAiB,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;YACjH,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,iBAAiB,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YACnG,GAAG,CAAC,QAAQ,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC;YACpF,GAAG,CAAC,QAAQ,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,QAAQ,CAAC,eAAe,EAAE,CAAC;YAChG,GAAG,CAAC,QAAQ,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,iBAAiB,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;YAC7G,GAAG,CAAC,QAAQ,CAAC,eAAe,KAAK,SAAS;gBACxC,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,eAAe,EAAE,QAAQ,CAAC,eAAkC,EAAE,CAAC;YACrE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;YACvF,UAAU,EAAE,CAAC;YACb,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;YACxB,WAAW,EAAE,OAAO,CAAC,kBAAkB;YACvC,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;gBACrB,WAAW,KAAK,EAAE,KAAK,EAAE,CAAC;YAC5B,CAAC;SACF,CAAC,CAAC;QACH,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YAC3C,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;gBAClB,KAAK,YAAY;oBACf,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACjC,MAAM;gBACR,KAAK,iBAAiB;oBACpB,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACtC,MAAM;gBACR,KAAK,OAAO;oBACV,WAAW,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;oBACtC,MAAM;gBACR,KAAK,OAAO;oBACV,OAAO,CAAC,kBAAkB,CAAC,cAAc,EAAE,CAAC;oBAC5C,MAAM,IAAI,KAAK,CAAC,sCAAsC,IAAI,CAAC,MAAM,IAAI,iBAAiB,EAAE,CAAC,CAAC;gBAC5F;oBACE,MAAM;YACV,CAAC;QACH,CAAC;QACD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,WAAW,CAAC,KAAK,CAAC;QAC1B,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC;QAClC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC5D,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,EAAmB,EAAE,CAC/D,IAAI,CAAC,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,gBAAgB,KAAK,IAAI;YACzD,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;YACjG,CAAC,CAAC,EAAE,CACP,CAAC;QACF,MAAM,gBAAgB,GAAG,CAAC,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAC3D,CAAC,OAAO,EAAoC,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,WAAW,CAC5E,CAAC;QACF,MAAM,WAAW,GACf,gBAAgB,KAAK,SAAS;YAC5B,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE;oBACE,IAAI,EAAE,cAAc;oBACpB,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,GAAG,EAAE,mBAAmB;oBACxB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC;oBACtC,IAAI,EAAE,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI;oBACzC,SAAS;iBACV;aACF,CAAC;QACR,OAAO;YACL,WAAW;YACX,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,SAAS;YACT,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;YAC/B,aAAa,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO;YACpC,YAAY,EAAE,IAAI,CAAC,YAAY;SAChC,CAAC;IACJ,CAAC;IAEM,mBAAmB,CAAC,OAAqB;QAC9C,MAAM,UAAU,GACd,OAAO,CAAC,YAAY,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;QACjH,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;IACnC,CAAC;IAEO,eAAe,CAAC,QAAwB,EAAE,IAAoB;QACpE,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,WAAW;gBACd,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;gBAC9E,OAAO,QAAQ,CAAC;YAClB,KAAK,cAAc,CAAC,CAAC,CAAC;gBACpB,MAAM,OAAO,GAAG,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;gBAC7C,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC9F,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACzB,CAAC;gBACD,OAAO,QAAQ,CAAC;YAClB,CAAC;YACD,KAAK,aAAa,CAAC,CAAC,CAAC;gBACnB,MAAM,IAAI,GAAwC;oBAChD,IAAI,EAAE,aAAa;oBACnB,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE;iBAC7C,CAAC;gBACF,MAAM,WAAW,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;gBACpC,IAAI,WAAW,EAAE,IAAI,KAAK,MAAM,EAAE,CAAC;oBACjC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACjC,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACnD,CAAC;gBACD,OAAO,QAAQ,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IAED,0GAA0G;IAClG,iBAAiB,CAAC,IAAqB;QAC7C,IAAI,IAAI,CAAC,GAAG,KAAK,mBAAmB,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;YACxE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAA0B,CAAC;YAC/D,IAAI,OAAO,EAAE,IAAI,KAAK,WAAW,EAAE,CAAC;gBAClC,MAAM,IAAI,SAAS,CAAC,0DAA0D,CAAC,CAAC;YAClF,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,MAAM,OAAO,GAAsD,EAAE,CAAC;QACtE,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;YAC3C,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,WAAW;gBACjB,UAAU,EAAE,QAAQ,CAAC,UAAU;gBAC/B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,KAAK,EAAE,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC;aAC1C,CAAC,CAAC;QACL,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;IACxC,CAAC;CACF;AAED,2GAA2G;AAC3G,SAAS,kBAAkB,CAAC,IAAyE;IACnG,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5D,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,iBAAiB,CAAC,UAA2B;IACpD,OAAO,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC;AACvG,CAAC;AAED,SAAS,iBAAiB,CAAC,eAAuB;IAChD,IAAI,CAAE,gBAAsC,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QACvE,MAAM,IAAI,SAAS,CAAC,yCAAyC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,eAAe,EAAE,CAAC,CAAC;IACtH,CAAC;IACD,OAAO,eAAkC,CAAC;AAC5C,CAAC;AAED,kHAAkH;AAClH,SAAS,cAAc,CAAC,aAAqB;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAClD,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,KAAyB;IAC7C,OAAO;QACL,GAAG,eAAe,EAAE;QACpB,UAAU,EAAE,CAAC;QACb,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,CAAC;QACnC,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,CAAC;QACrC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,CAAC,eAAe,IAAI,CAAC;QAC/D,eAAe,EAAE,KAAK,CAAC,kBAAkB,CAAC,eAAe,IAAI,CAAC;KAC/D,CAAC;AACJ,CAAC"}
+{"version":3,"file":"ai-sdk-model-client.js","sourceRoot":"","sources":["../../../src/ai-sdk/ai-sdk-model-client.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EACL,UAAU,EACV,WAAW,EACX,UAAU,GASX,MAAM,IAAI,CAAC;AAEZ,OAAO,EAAE,eAAe,EAA6C,MAAM,4BAA4B,CAAC;AAYxG,6DAA6D;AAC7D,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAM9C,MAAM,gBAAgB,GAA+B;IACnD,kBAAkB;IAClB,MAAM;IACN,SAAS;IACT,KAAK;IACL,QAAQ;IACR,MAAM;IACN,OAAO;IACP,KAAK;CACN,CAAC;AAQF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAoB,EAAE,UAAmC,EAAE;IAChG,OAAO,IAAI,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,gBAAgB;IAID;IACA;IAJF,QAAQ,CAAS;IAElC,YACmB,KAAoB,EACpB,OAAgC;QADhC,UAAK,GAAL,KAAK,CAAe;QACpB,YAAO,GAAP,OAAO,CAAyB;QAEjD,IAAI,CAAC,QAAQ,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;IACrE,CAAC;IAEM,KAAK,CAAC,SAAS,CAAC,OAAqB,EAAE,MAAyB;QACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QAClC,MAAM,KAAK,GAAY,EAAE,CAAC;QAC1B,KAAK,MAAM,UAAU,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YACvC,MAAM,IAAI,GAAS,EAAE,WAAW,EAAE,UAAU,CAAC,WAAW,EAAE,WAAW,EAAE,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3G,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAChC,CAAC;QACD,IAAI,WAAoD,CAAC;QACzD,MAAM,MAAM,GAAG,UAAU,CAAC;YACxB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC;YAC/E,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,MAAM,CACjC,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI,GAAG,EAAE,CAAC,EACzF,EAAE,CACH;YACD,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,iBAAiB,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YACnG,GAAG,CAAC,QAAQ,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC;YACpF,GAAG,CAAC,QAAQ,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,QAAQ,CAAC,eAAe,EAAE,CAAC;YAChG,GAAG,CAAC,QAAQ,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,iBAAiB,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;YAC7G,GAAG,CAAC,QAAQ,CAAC,eAAe,KAAK,SAAS;gBACxC,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,eAAe,EAAE,QAAQ,CAAC,eAAkC,EAAE,CAAC;YACrE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;YACvF,UAAU,EAAE,CAAC;YACb,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;YACxB,WAAW,EAAE,OAAO,CAAC,kBAAkB;YACvC,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;gBACrB,WAAW,KAAK,EAAE,KAAK,EAAE,CAAC;YAC5B,CAAC;SACF,CAAC,CAAC;QACH,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YAC3C,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;gBAClB,KAAK,YAAY;oBACf,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACjC,MAAM;gBACR,KAAK,iBAAiB;oBACpB,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACtC,MAAM;gBACR,KAAK,OAAO;oBACV,WAAW,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;oBACtC,MAAM;gBACR,KAAK,OAAO;oBACV,OAAO,CAAC,kBAAkB,CAAC,cAAc,EAAE,CAAC;oBAC5C,MAAM,IAAI,KAAK,CAAC,sCAAsC,IAAI,CAAC,MAAM,IAAI,iBAAiB,EAAE,CAAC,CAAC;gBAC5F;oBACE,MAAM;YACV,CAAC;QACH,CAAC;QACD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,WAAW,CAAC,KAAK,CAAC;QAC1B,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC;QAClC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC5D,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,EAAmB,EAAE,CAC/D,IAAI,CAAC,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,gBAAgB,KAAK,IAAI;YACzD,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;YACjG,CAAC,CAAC,EAAE,CACP,CAAC;QACF,MAAM,gBAAgB,GAAG,CAAC,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAC3D,CAAC,OAAO,EAAoC,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,WAAW,CAC5E,CAAC;QACF,MAAM,WAAW,GACf,gBAAgB,KAAK,SAAS;YAC5B,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE;oBACE,IAAI,EAAE,cAAc;oBACpB,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,GAAG,EAAE,mBAAmB;oBACxB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC;oBACtC,IAAI,EAAE,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI;oBACzC,SAAS;iBACV;aACF,CAAC;QACR,OAAO;YACL,WAAW;YACX,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,SAAS;YACT,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;YAC/B,aAAa,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO;YACpC,YAAY,EAAE,IAAI,CAAC,YAAY;SAChC,CAAC;IACJ,CAAC;IAEM,mBAAmB,CAAC,OAAqB;QAC9C,MAAM,UAAU,GACd,OAAO,CAAC,YAAY,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;QACjH,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,CAC1C,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EACxF,CAAC,CACF,CAAC;QACF,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,UAAU,GAAG,yBAAyB,CAAC;IAC5E,CAAC;IAEO,eAAe,CACrB,QAAwB,EACxB,IAAoB,EACpB,UAA2C;QAE3C,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,WAAW;gBACd,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;iBACtF,CAAC,CAAC;gBACH,OAAO,QAAQ,CAAC;YAClB,KAAK,cAAc,CAAC,CAAC,CAAC;gBACpB,MAAM,OAAO,GAAG,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;gBAC7C,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC9F,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACzB,CAAC;gBACD,OAAO,QAAQ,CAAC;YAClB,CAAC;YACD,KAAK,aAAa,CAAC,CAAC,CAAC;gBACnB,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;gBACvD,MAAM,IAAI,GAAwC;oBAChD,IAAI,EAAE,aAAa;oBACnB,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,MAAM,EACJ,SAAS,CAAC,MAAM,KAAK,CAAC;wBACpB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE;wBACtC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,GAAG,SAAS,CAAC,EAAE;iBACtF,CAAC;gBACF,MAAM,WAAW,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;gBACpC,IAAI,WAAW,EAAE,IAAI,KAAK,MAAM,EAAE,CAAC;oBACjC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACjC,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACnD,CAAC;gBACD,OAAO,QAAQ,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IAED,0GAA0G;IAClG,iBAAiB,CAAC,IAAqB;QAC7C,IAAI,IAAI,CAAC,GAAG,KAAK,mBAAmB,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;YACxE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAA0B,CAAC;YAC/D,IAAI,OAAO,EAAE,IAAI,KAAK,WAAW,EAAE,CAAC;gBAClC,MAAM,IAAI,SAAS,CAAC,0DAA0D,CAAC,CAAC;YAClF,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,MAAM,OAAO,GAAsD,EAAE,CAAC;QACtE,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;YAC3C,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,WAAW;gBACjB,UAAU,EAAE,QAAQ,CAAC,UAAU;gBAC/B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,KAAK,EAAE,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC;aAC1C,CAAC,CAAC;QACL,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;IACxC,CAAC;CACF;AASD,wFAAwF;AACxF,SAAS,WAAW,CAClB,MAAkD,EAClD,UAA2C;IAE3C,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAiB,EAAE;QACjD,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,SAAS,CAAC,4CAA4C,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;QAC/E,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;IACnF,CAAC,CAAC,CAAC;AACL,CAAC;AAED,2GAA2G;AAC3G,SAAS,kBAAkB,CAAC,IAAyE;IACnG,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5D,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,iBAAiB,CAAC,UAA2B;IACpD,OAAO,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC;AACvG,CAAC;AAED,SAAS,iBAAiB,CAAC,eAAuB;IAChD,IAAI,CAAE,gBAAsC,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QACvE,MAAM,IAAI,SAAS,CAAC,yCAAyC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,eAAe,EAAE,CAAC,CAAC;IACtH,CAAC;IACD,OAAO,eAAkC,CAAC;AAC5C,CAAC;AAED,kHAAkH;AAClH,SAAS,cAAc,CAAC,aAAqB;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAClD,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,KAAyB;IAC7C,OAAO;QACL,GAAG,eAAe,EAAE;QACpB,UAAU,EAAE,CAAC;QACb,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,CAAC;QACnC,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,CAAC;QACrC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,CAAC,eAAe,IAAI,CAAC;QAC/D,eAAe,EAAE,KAAK,CAAC,kBAAkB,CAAC,eAAe,IAAI,CAAC;KAC/D,CAAC;AACJ,CAAC"}

package/dist/src/ai-sdk/index.d.ts

@@ -1 +1 @@
-export { aiSdkModelClientApi, createAiSdkModelClient, type AiSdkModelClientOptions } from "./ai-sdk-model-client.js";
+export { aiSdkModelClientApi, createAiSdkModelClient, estimatedImageInputTokens, type AiSdkModelClientOptions, } from "./ai-sdk-model-client.js";

package/dist/src/ai-sdk/index.js

@@ -5,5 +5,5 @@
 // See the LICENSE file in the repository root.
 //
 // SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
-export { aiSdkModelClientApi, createAiSdkModelClient } from "./ai-sdk-model-client.js";
+export { aiSdkModelClientApi, createAiSdkModelClient, estimatedImageInputTokens, } from "./ai-sdk-model-client.js";
 //# sourceMappingURL=index.js.map

package/dist/src/ai-sdk/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAgC,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,yBAAyB,GAE1B,MAAM,0BAA0B,CAAC"}

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,77 @@
+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;
+    /**
+     * Whether the session keeps the indexed session summary. Defaults to `false`. See
+     * `AgentSessionOptions.summaryAttributesIndexed` for what it stores and the index keys it registers.
+     *
+     * @since 0.6.0
+     */
+    readonly summaryAttributesIndexed?: boolean;
+}
+/**
+ * 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 (since 0.5.0) and `summaryAttributesIndexed` (since 0.6.0, default `false`);
+ * see {@link BuiltinAgentSessionFlowOptions}.
+ * @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,20 @@ 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 (since 0.5.0) and `summaryAttributesIndexed` (since 0.6.0, default `false`);
+ * see {@link BuiltinAgentSessionFlowOptions}.
+ * @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 }),
@@ -51,7 +58,10 @@ export function createStepwiseAgentSessionFlow(definition, flowType) {
             : { eventStreamCapacityBytes: definition.eventStreamCapacityBytes }),
         ...(definition.compaction === undefined ? {} : { compaction: definition.compaction }),
         ...(definition.spendLimit === undefined ? {} : { spendLimit: definition.spendLimit }),
+        ...(flowOptions.summaryAttributesIndexed === undefined
+            ? {}
+            : { summaryAttributesIndexed: flowOptions.summaryAttributesIndexed }),
     };
     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;AAqCxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;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;QACrF,GAAG,CAAC,WAAW,CAAC,wBAAwB,KAAK,SAAS;YACpD,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,wBAAwB,EAAE,WAAW,CAAC,wBAAwB,EAAE,CAAC;KACxE,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;