@superdurable/dex-agents 0.4.0 → 0.6.0

package/README.md

@@ -1,15 +1,15 @@
 # @superdurable/dex-agents
 
 Durable agent sessions for Dex, shared by the TypeScript agent framework
-adapters. One Flow execution is one agent session, and the Flow ID is the
+adapters. One Flow run is one agent session, and the Flow ID is the
 session ID. An adapter package supplies a framework runner; this package owns
 the Steps, persistence, RPCs, live events, tool approval, and crash recovery.
 It runs in Step mode: each model call and each tool call is its own Dex Step,
 and the tool calls of one model response run in parallel.
 
-The package also ships the built-in agent loop, **Stepwise mode**, for agents
-defined in Dex terms without a framework (`@superdurable/dex-agents/stepwise`),
-and its AI SDK model client (`@superdurable/dex-agents/ai-sdk`). Stepwise runs
+The package also ships the built-in agent loop for agents
+defined in Dex terms without a framework (`@superdurable/dex-agents/builtin-loop`),
+and its AI SDK model client (`@superdurable/dex-agents/ai-sdk`). The built-in loop runs
 on the same session Flow as every adapter, with the same Steps, RPCs, and
 events. The session also handles two built-in tools under any runner:
 `ask_user` asks the user a question and waits in `AwaitQuestionAnswer`, and
@@ -27,10 +27,10 @@ Applications usually install an adapter next to this package. To build a
 runner of your own, install the core with the Dex SDK it supports:
 
 ```bash
-npm i @superdurable/dex-agents @superdurable/dex@1.38.0
+npm i @superdurable/dex-agents @superdurable/dex@1.45.0
 ```
 
-`@superdurable/dex` 1.38.0 is a peer dependency, so the application, the core,
+`@superdurable/dex` 1.45.0 is a peer dependency, so the application, the core,
 and every adapter share one copy. The Dex Registry matches Flow classes and
 RPC registrations by identity, so a second copy makes it reject the Flow
 (`steps must be a StepList`). Adapters list this package as a peer dependency
@@ -49,12 +49,13 @@ the published core. It is for tests only; it needs `DEXCLI` and
 | Subpath | Contents | Extra dependency |
 | --- | --- | --- |
 | `@superdurable/dex-agents` | Session Flow, runner contract, built-in tool definitions | none |
-| `@superdurable/dex-agents/stepwise` | Stepwise mode: `createStepwiseAgentSessionFlow`, `functionTool`, `ToolSource`, `ModelClient`, `ScriptedModelClient` | none |
+| `@superdurable/dex-agents/builtin-loop` | The built-in agent loop: `createBuiltinAgentSessionFlow`, `functionTool`, `ToolSource`, `ModelClient`, `ScriptedModelClient` | none |
 | `@superdurable/dex-agents/ai-sdk` | `createAiSdkModelClient` for any AI SDK `LanguageModel` | optional peer `ai@^7.0.159`, the Vercel AI SDK adapter's range |
 | `@superdurable/dex-agents/mcp` | MCP servers' tools as agent tools; see [MCP tools](#mcp-tools-superdurabledex-agentsmcp) | optional peer `@modelcontextprotocol/sdk@^1.32.2` |
 | `@superdurable/dex-agents/connectors` | Reviewed Connector operations as agent tools; see [Connector tools](#connector-tools-superdurabledex-agentsconnectors) | optional peer `@superdurable/connectors-sdk` |
 | `@superdurable/dex-agents/ui-stream` | Browser streams of live sessions; see [UI streams](#ui-streams) | none |
-| `@superdurable/dex-agents/testing` | Test engine, Worker processes, waits, and `ScriptedModelClient` (the same class as the stepwise entry point's) | none |
+| `@superdurable/dex-agents/s3` | `S3MediaStore`, image bytes in an S3-compatible bucket; see [Images](#images) | optional peer `@aws-sdk/client-s3@^3.400.0` |
+| `@superdurable/dex-agents/testing` | Test engine, Worker processes, waits, and `ScriptedModelClient` (the same class as the builtin-loop entry point's) | none |
 
 Install `ai` and a provider package only for `./ai-sdk`; importing that
 subpath without `ai` fails with `Cannot find package 'ai'`.
@@ -128,17 +129,17 @@ Enable built-in tools and call `answer_question` only after every Worker of the
 Flow type runs 0.2.0, because a 0.1.0 Worker cannot decode the new non-final
 statuses.
 
-## Stepwise mode
+## Built-in agent loop
 
-Stepwise is the built-in agent loop. Declare the agent, its function tools,
-and its model client; `createStepwiseAgentSessionFlow` builds the session Flow
-with a `StepwiseAgentRunner` and derives the session options from the
+The built-in agent loop runs an agent without a framework. Declare the agent, its function tools,
+and its model client; `createBuiltinAgentSessionFlow` builds the session Flow
+with a `BuiltinLoopAgentRunner` and derives the session options from the
 definition.
 
 ```ts
 import { openai } from "@ai-sdk/openai";
 import { createAiSdkModelClient } from "@superdurable/dex-agents/ai-sdk";
-import { createStepwiseAgentSessionFlow, functionTool } from "@superdurable/dex-agents/stepwise";
+import { createBuiltinAgentSessionFlow, functionTool } from "@superdurable/dex-agents/builtin-loop";
 
 const lookupOrder = functionTool<{ order_id: string }>({
   name: "lookup_order",
@@ -155,7 +156,7 @@ const refundOrder = functionTool<{ order_id: string }>({
   execute: async ({ order_id }, context) => payments.refund(order_id, { idempotencyKey: context.idempotencyKey }),
 });
 
-export const supportAgentFlow = createStepwiseAgentSessionFlow(
+export const supportAgentFlow = createBuiltinAgentSessionFlow(
   {
     name: "support",
     instructions: "You help customers with their orders.",
@@ -181,6 +182,7 @@ export const supportAgentFlow = createStepwiseAgentSessionFlow(
 | `maxModelCallsPerTurn` | 100 | After this many model calls in one turn, the next call offers no tools, so the model must answer. If it still asks for tools, the turn ends and each call gets the result `The tool call was not run: this turn reached its limit of <n> model calls.` |
 | `planModeEnabled` | `false` | Accept `planMode` user messages; requires `write_todos` in `builtInTools`. See [Plans and plan mode](#plans-and-plan-mode) |
 | `interruptDeadlineMs`, `eventStreamCapacityBytes` | as for the session | Passed to the session options |
+| `decideTurnContinuation` | none | A function that ends or continues the turn at the end of each loop iteration; see [Ending or continuing a turn](#ending-or-continuing-a-turn). Since 0.5.0 |
 
 Each `RunModel` makes at most one model call, built from committed state only:
 the instructions, the stored messages, the plan note from `buildPlanNote`
@@ -188,7 +190,8 @@ before the turn's messages when a plan exists or the turn plans, and the
 results of the previous model response from the turn's final records. The runner stores the turn's
 transcript as it goes: `ToolCallsRequested.newMessages` carries the previous
 round's tool results and the new model output, so `FrameworkRunState` holds
-only `{"model_calls": <n>}`. The input builder pairs every stored tool call
+only `{"model_calls": <n>}`, plus `"consecutive_continuations": <n>` after a
+continued answer. The input builder pairs every stored tool call
 with a result, and a missing one gets the outcome-unknown text, so an orphaned
 call never reaches a provider.
 
@@ -197,9 +200,19 @@ A function tool declares its effect, which picks `CallTool` or
 model's arguments against the tool's JSON Schema before `execute` runs, and a
 mismatch or an unknown tool reaches the model as a tool failure. `execute`
 receives the arguments and a `ToolCallContext` with the idempotency key,
-attempt, events, heartbeat, and the answers to the tool's own questions. A
-`string` result is the output, and a `ToolInputRequested` result asks the user
-first. Any other result is JSON with the separators of Python's `json.dumps`,
+attempt, events, heartbeat, the answers to the tool's own questions, and
+`effect`: the call's effect after the tool policies, which chose its tool Step.
+A wrapper that turns errors into `ToolExecutionError` lets them propagate for a
+`non_idempotent_write` or `unclassified` effect, and for an absent one, which
+only a hand-built context has. `prepareArguments`, a synchronous and deterministic function, converts the
+decoded arguments before the schema check, such as an argument shape an earlier
+version of the tool took; a throw fails the call like a schema violation, a
+cancellation passes through, and a Promise result is refused. The
+stored tool call and the approval interrupt keep the model's original
+arguments. A
+`string` result is the output, a `functionToolResult` adds images (see
+[Images from function tools](#images-from-function-tools)), and a
+`ToolInputRequested` result asks the user first. Any other result is JSON with the separators of Python's `json.dumps`,
 so the model sees the same text as from the Python core; the one exception is a
 whole-number float such as `1.0`, which JavaScript cannot tell from `1`. The
 argument check and its messages match the Python core, including Python's `==`
@@ -207,7 +220,7 @@ for `enum`, so `true` matches `1`.
 
 The session's tool policies, `turn.toolPolicies`, win over a function tool's own
 effect and `requiresApproval`, whether they come from the agent definition or
-from options passed to `createAgentSessionFlow` with a `StepwiseAgentRunner`. A
+from options passed to `createAgentSessionFlow` with a `BuiltinLoopAgentRunner`. A
 built-in tool enabled only in those options must not share a function tool's
 name; the first `RunModel` fails before it calls the model.
 
@@ -222,6 +235,74 @@ SDK returned them. It is replayed unchanged to a model of the same provider;
 any other provider gets its text and tool calls only, so a session can change
 model between turns.
 
+### Ending or continuing a turn
+
+`decideTurnContinuation` lets the application decide, at the end of each loop
+iteration, whether the turn ends or continues. An iteration is one model call
+and the tool calls it requested. The function receives a
+`TurnContinuationContext`: `flowId`, `turnId`, `sessionSettings`, the
+iteration's `modelOutput` items, and its `toolResults` (empty when the model
+answered without tools). It returns `"end"`, `"default"`, or a
+`ContinueTurn` (`{ action: "continue", message }`), directly or as a Promise.
+
+| The iteration | `"end"` | `{ action: "continue", message }` | `"default"` or no hook |
+| --- | --- | --- | --- |
+| The model called tools | The turn completes without another model call | The message follows the tool results, and the model is called with both | The model is called with the tool results |
+| The model answered without tools | The turn completes | The answer and the message are stored, and the model is called again in the same turn | The turn completes |
+
+```ts
+const approvalsAgentFlow = createBuiltinAgentSessionFlow(
+  {
+    name: "approvals",
+    instructions: "Review the request, then call submit_decision.",
+    model,
+    tools: [submitDecision],
+    decideTurnContinuation: ({ toolResults, modelOutput }) => {
+      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";
+    },
+  },
+  "ApprovalsAgent",
+);
+```
+
+- After tools, the hook runs in the next `RunModel` Step, before its model
+  call. `"end"` completes the turn there with the tool results as its last
+  messages and zero model calls in that Step's usage. The snapshot, the
+  `turn_completed` event, and the UI stream show a finished turn whose last
+  part is the tool result. That `RunModel` still runs the session's
+  compaction and spend-limit checks first, and still emits a `chat` span. The
+  UI stream starts a step for every `RunModel` Step, so it sends one more
+  `start-step` and `finish-step` with no visible part; the AI SDK message has
+  no part for them and matches `convertAgentSnapshotToUIMessages`.
+- After an answer, the hook runs in the same `RunModel` Step, after the model
+  call. A continuation returns the `TurnContinued` outcome: the session stores
+  the answer and the message as user text, then moves to `RunModel` again.
+  The next model request therefore ends with a user message, which every
+  provider accepts. Each model call stays its own `RunModel` Step, so a crash
+  or retry repeats only that call. Each continued call counts toward
+  `maxModelCallsPerTurn`.
+- The message is part of the turn's transcript: the model sees it as user
+  text, and snapshots hold it as a `user` message of the same turn.
+  `convertAgentSnapshotToUIMessages` keeps a user message between two model
+  calls of one turn out of the chat and starts the next model call's step, as
+  the UI stream does.
+- At most `maxConsecutiveTurnContinuations` (8) continuations in a row may
+  follow answers without tools; a tool call resets the count. The next one
+  ends the turn with its answer stored, `lastTurnError` set to `the turn
+  reached its limit of 8 consecutive continuations without a tool call`, and a
+  `turn_failed` event.
+- A thrown error, or any other value, including a continuation with a blank
+  message, fails the `RunModel` attempt, and its retry policy runs it again.
+  After an answer, the retry repeats the model call too. Keep the function
+  free of side effects.
+
 ### Tool sources
 
 `toolSources` takes tools that are listed at run time, such as an MCP server's
@@ -236,7 +317,7 @@ const files = new McpToolSource(
   [{ transport: "stdio", name: "files", command: "mcp-server-files", args: ["/srv/reports"] }],
   { resourceAndPromptToolsEnabled: true },
 );
-export const reportsAgentFlow = createStepwiseAgentSessionFlow(
+export const reportsAgentFlow = createBuiltinAgentSessionFlow(
   {
     name: "reports",
     instructions: "You manage reports.",
@@ -286,7 +367,7 @@ runner's last listing of that source, as the Python core does.
 
 ### Demo model without a key
 
-`ScriptedModelClient` from `@superdurable/dex-agents/stepwise` answers each
+`ScriptedModelClient` from `@superdurable/dex-agents/builtin-loop` answers each
 call from a function of the `ModelRequest`, so an agent runs without a model
 key: a local demo mode, a tutorial, or a test. The function returns text,
 reasoning, and tool calls, sync or async; `ScriptedModelClient.userTexts` and
@@ -296,7 +377,7 @@ core's. Keep the script deterministic, because a crashed `RunModel` reruns
 it. `@superdurable/dex-agents/testing` exports the same class.
 
 ```ts
-import { ScriptedModelClient, type ModelRequest, type ScriptedModelReply } from "@superdurable/dex-agents/stepwise";
+import { ScriptedModelClient, type ModelRequest, type ScriptedModelReply } from "@superdurable/dex-agents/builtin-loop";
 
 function replyAsDemoModel(request: ModelRequest): ScriptedModelReply {
   const results = ScriptedModelClient.toolResults(request);
@@ -309,7 +390,7 @@ function replyAsDemoModel(request: ModelRequest): ScriptedModelReply {
 const model = isDemo ? new ScriptedModelClient(replyAsDemoModel) : createAiSdkModelClient(openai("gpt-5-mini"));
 ```
 
-The stored `framework_item` of a Stepwise message is one of
+The stored `framework_item` of a built-in loop message is one of
 `{"type":"user_text","text"}`,
 `{"type":"model_output","provider","api","item","text","tool_calls"}`, or
 `{"type":"tool_result","tool_call_id","tool_name","output"}`, the same as the
@@ -362,7 +443,7 @@ response`; invalid arguments fail with `invalid todos: <reason>`.
 
 Plan mode reviews a plan before it runs. Enable it with
 `planModeEnabled: true`, which needs `write_todos` in `builtInTools` and a
-runner whose `supportsPlanMode` is `true`, such as the Stepwise runner.
+runner whose `supportsPlanMode` is `true`, such as the built-in loop runner.
 `AgentDefinition.planningToolChoice` is `"auto"` by default: a planning turn
 offers only `write_todos`, the plan note tells the model to write the plan with
 it, and a turn that answers in text, such as with a clarifying question, ends
@@ -406,9 +487,10 @@ if (snapshot.plan?.status === "draft") {
   never runs. It marks the plan `active`, writes `plan_execution_started`, and
   starts an `executing` turn with every tool, whose user message is `[Dex] The
   user approved plan revision <n>. Execute it and keep the task statuses
-  current with write_todos.`.
+  current with write_todos.`. The stored message has `origin`
+  `plan_execution`; see [User messages the session writes](#user-messages-the-session-writes).
 - `buildPlanNote(plan, interactionMode)` returns the note that shows the model
-  the plan. Stepwise adds it as user text before the turn's messages in every
+  the plan. The built-in loop adds it as user text before the turn's messages in every
   model call, so the model always sees the latest plan.
 
 ## Steering and turn cancellation
@@ -493,7 +575,7 @@ at once.
 
 Compaction keeps the model input under the context window. Pass
 `compaction: { contextWindowTokens, triggerRatio?, retainedRatio? }` to
-`createAgentSessionFlow`, or as `AgentDefinition.compaction` for Stepwise. The
+`createAgentSessionFlow`, or as `AgentDefinition.compaction` for the built-in loop. The
 ratios default to 0.85 and 0.3, as in the Python core.
 
 ```ts
@@ -517,7 +599,7 @@ in `turn.messages` and the summary in `turn.contextSummary`.
 Summarized messages stay stored until retention deletes them; see
 [Message storage and retention](#message-storage-and-retention). A compaction policy needs a runner with all
 three optional methods, and `createAgentSessionFlow` throws a `TypeError`
-otherwise. `StepwiseAgentRunner` implements them: its input starts with
+otherwise. `BuiltinLoopAgentRunner` implements them: its input starts with
 `contextSummaryNoteHeader` (`[Dex] Summary of the earlier conversation:`) and
 the summary, it cuts only between model responses whose tool calls all have
 stored results, so a turn with many tool calls compacts mid-turn without
@@ -560,7 +642,7 @@ const models: Record<string, ModelClient> = {
   "gpt-5-mini": createAiSdkModelClient(openai("gpt-5-mini")),
   "gpt-5": createAiSdkModelClient(openai("gpt-5")),
 };
-const flow = createStepwiseAgentSessionFlow(
+const flow = createBuiltinAgentSessionFlow(
   {
     name: "support",
     instructions: "You help customers with their orders.",
@@ -588,7 +670,7 @@ await client.invokeRPC(flow.updateSessionSettings, sessionId, { sessionSettings:
   turn left reads as no settings.
 - A runner reads `AgentTurnContext.sessionSettings`, `{}` when there are
   none, such as in a session started on 0.1.0. `ContextSummaryRequest` carries
-  the same value. Stepwise's `AgentDefinition.resolveModel` maps it to the
+  the same value. The built-in loop's `AgentDefinition.resolveModel` maps it to the
   `ModelClient` of each model call, including summary calls and token
   estimates, and `InstructionContext.sessionSettings` passes it to an
   instructions function.
@@ -616,6 +698,182 @@ await client.invokeRPC(flow.updateSessionSettings, sessionId, { sessionSettings:
 - Start sessions with settings, and call `update_session_settings`, only after
   every Worker of the Flow type runs 0.2.0. A 0.1.0 Worker drops the start
   settings and starts turns without them.
+- `AgentSessionStartInput.startEnvironment` (`startAgentSession(..., { startEnvironment })`) is different: string
+  keys and values that say where the starting program ran. It stays in the Flow's start input and the session never
+  reads it, so it is not a setting and cannot change.
+
+## Images
+
+A user message and a tool result can carry images. Session state holds only an `AgentImageReference` for each image;
+the bytes live in a media store, keyed by their SHA-256. The wire form is the same as the Python core's:
+
+```json
+{"type": "image", "uri": "s3://agent-media/sessions/sha256/9f2c...", "mime_type": "image/png", "sha256": "9f2c...", "size_bytes": 48213}
+```
+
+Upload first, then send the reference:
+
+```ts
+import { sendAgentUserMessage } from "@superdurable/dex-agents";
+import { S3MediaStore } from "@superdurable/dex-agents/s3";
+
+const store = new S3MediaStore({ bucket: "agent-media", prefix: "sessions" }); // credentials from the AWS chain
+const reference = await store.putImage(await readFile("chart.png"));
+await sendAgentUserMessage(client, flow, "session-42", { text: "What does this chart show?", images: [reference] });
+```
+
+A tool source returns images the same way, uploading inside its call. This is a tool source's
+`executeDeferredToolCall` result:
+
+```ts
+const reference = await store.putImage(screenshotPng);
+return { output: "Took a screenshot.", images: [reference] };
+```
+
+A function tool returns `functionToolResult({ output, images })` instead, because the runner serializes its plain
+objects as JSON; see [Images from function tools](#images-from-function-tools).
+
+- **One object per image.** The object key is `<prefix>/sha256/<sha256>`, and the reference's `uri` ends in
+  `/sha256/<sha256>`. `S3MediaStore.putImage` uploads with `If-None-Match: *` and treats "already exists" (412) as
+  success, so a tool Step that a crash retries, a client that sends again, or two Workers at once write one object.
+  A 409 conflict retries the upload twice; when every attempt conflicts, a `HEAD` must find the object with the
+  image's size, or `putImage` throws `MediaStoreError`. On a
+  service that refuses conditional writes it checks with `HEAD` first; two concurrent uploads may then both write the
+  same content, so deduplication holds for the key and its final content. A replay always reads the bytes the
+  reference was made from: `getImage` reads only references under its own bucket and prefix, refuses an object whose
+  `Content-Length` differs, reads at most one byte past `sizeBytes`, and `verifyImageBytes` checks the SHA-256, the
+  size, and that the bytes are a well-formed image of `mimeType`.
+- **Types and sizes.** PNG, JPEG, GIF, and WebP, detected from the bytes with a cheap structural check (PNG signature
+  and `IHDR`; JPEG SOI, a marker, and EOI at the end; GIF header and screen descriptor; WebP RIFF size and a `VP8`,
+  `VP8L`, or `VP8X` chunk), not a full decode, up to `maxImageBytes` (3,750,000 bytes) each. Its base64 text is 5,000,000 bytes, which fits the per-image limits of Amazon Bedrock (5 MB of base64) and the
+  Claude API (10 MB of base64). One message or tool
+  result carries at most `maxImagesPerMessage` (20). `putImage` throws `ImageValidationError` for other bytes. A `uri`
+  is at most `maxImageUriLength` (1024) bytes as UTF-8 in every core, and a store refuses a bucket, prefix, or name
+  that would make longer ones. `validateImageReferences` checks references, and `sendAgentUserMessage` checks them
+  before it sends.
+- **Where they are stored.** `AgentUserMessage.images`, the session copy on the stored `AgentMessage.images` for
+  display, `ToolExecutionResult.images`, and `AgentToolCall.images`. A runner also keeps the references, never the
+  bytes, in its `frameworkItem`, the replay truth. Decoded values omit `images` when there are none. The browser
+  snapshot JSON includes the `images` of messages and tool calls.
+- **The runner.** `send_user_message` returns `false` for images unless the runner implements
+  `buildUserMessageWithImages`, which the session calls instead of `buildUserMessage` for a message with images.
+  When it builds model input, the runner reads the bytes with `loadImages(store, references)`, choosing the
+  references from its replayed items or from `collectTurnImages(turn)`. The session sets the stored user message's
+  `images` itself; for a tool result message the runner sets `FrameworkMessage.images` from the record. A tool result
+  with an invalid reference fails the tool Step attempt. The session checks the `images` of every `FrameworkMessage` a
+  runner returns before it stores any: an invalid one fails the model call like any runner error, and one from
+  `buildUnfinishedTurnMessages` leaves only the turn's note.
+- **Stores.** `new S3MediaStore({ bucket, prefix, endpoint, region, forcePathStyle, credentials })` or
+  `S3MediaStore.fromStoreUri("s3://bucket/prefix")` for AWS S3 or any S3-compatible service; call `close()` when done.
+  Credentials come from the standard AWS chain by default; pass `credentials` (`accessKeyId`, `secretAccessKey`, and
+  optionally `sessionToken`) only for a bucket whose keys are not secret, such as a local development bucket with
+  fixed loopback keys. The store never logs them. `InMemoryMediaStore` is for tests in one process, and returns a copy
+  on each read. A store of your own implements `MediaStore`: check its location with `requireShortImageUris`, build
+  each reference with `buildImageReference(data, storeUri)`, and check reads with `requireStoreImageReference` and
+  `verifyImageBytes`.
+- **Local directory.** `new LocalDirectoryMediaStore(root)`, from the main export, keeps images on one machine, for a
+  client and Workers that share a file system, such as a command-line tool in local mode; use `S3MediaStore` across
+  machines. `root` must be an absolute path. An image's file is `<root>/sha256/<sha256>`, and its `uri` is
+  `file://<root>/sha256/<sha256>`: the root is made absolute as text, without resolving symbolic links or normalizing
+  Unicode, and every byte other than ASCII letters, digits, `-._~`, and `/` is percent-encoded, the same in every core.
+  `putImage` copies the bytes into a temporary file in the same directory and renames it into place; an existing file
+  with the same bytes is success. Directories it creates get mode `0700` and files `0600`. A write syncs the image file
+  before the rename. Before every `putImage` returns, even when an identical file already existed and nothing was
+  written, it syncs the `sha256` directory, the root, and the root's parent; it also syncs the parent of each directory
+  it creates. Directories above the root's parent must already be durable; a concurrent creator of a deeper missing
+  ancestor is out of scope. It refuses a symbolic link, a special file, or an image file
+  with more than one hard link under the root with `MediaStoreError`. Node.js has no `openat`, so it opens files by path
+  and checks before and after each operation: `lstat` on the `sha256` directory and `O_NOFOLLOW` on the file before,
+  then the directory's real path and the file's device and inode after. A read that fails the check returns nothing;
+  a write that fails it removes the file it wrote when it can and throws. A process of the same user that can write the
+  `0700` root can still race a directory swap between these checks, so this store does not guarantee that it never
+  follows a symbolic link. The Python core opens every path relative to an open directory and has no such window.
+  Reads check the file's size first, read at most one byte past `sizeBytes`, and run `verifyImageBytes`. It needs a POSIX file system. Deleting a
+  session deletes no file.
+- **Built-in runners.** The built-in loop and the framework adapters show images to their model when built with a
+  `mediaStore`: they implement `buildUserMessageWithImages`, keep references in their stored items, and load the bytes
+  for each model call. Without a store they do not, and their sessions refuse images. For the built-in loop, pass it
+  to `createBuiltinAgentSessionFlow(definition, flowType, { mediaStore })` or `new BuiltinLoopAgentRunner(definition,
+  mediaStore)`; see [Images on the built-in loop](#images-on-the-built-in-loop).
+- **MCP tools.** `new McpToolSource(servers, { mediaStore })` uploads the `image` content of a successful result
+  inside the tool Step and returns the references in `ToolExecutionResult.images`. Give it the store the runner
+  reads.
+- **Retention.** Deleting a session deletes no object. A runner reads the images again whenever a model call replays
+  them, so a bucket lifecycle rule must keep each object at least as long as any session that references it can
+  still run a turn or replay its history. When an object is gone, the turn that needs it fails with `MediaStoreError`
+  in `lastTurnError`, after its user message, with nothing else stored; later turns that replay the image fail the
+  same way.
+- Send images only after every Worker of the Flow type runs 0.5.0: an earlier Worker drops them.
+
+### Images on the built-in loop
+
+```ts
+import { S3MediaStore } from "@superdurable/dex-agents/s3";
+
+const mediaStore = S3MediaStore.fromStoreUri("s3://agent-media/sessions");
+const flow = createBuiltinAgentSessionFlow(supportAgent, "SupportAgent", { mediaStore });
+```
+
+- **Stored items.** The `user_text` item of a message with images, and the `tool_result` item of a call whose record
+  has images, add an `images` list of snake_case references after their other fields, the same JSON as the Python
+  core. An item without images has no `images` key, so its bytes are unchanged. The tool result message also shows
+  the references in `images`. Session state never holds image bytes.
+- **Model calls.** `ModelUserTextItem.images` and `ModelToolResultItem.images` carry the references into the
+  `ModelRequest`. Right before each model call, the runner reads the bytes of every image in the request with
+  `loadImages` and passes them in `ModelRequest.imageBytes`, keyed by SHA-256. A retried `RunModel` attempt, or one on
+  a new Worker after a crash, builds the same request from the same references and bytes. A store read that fails
+  fails that attempt, which retries; after the last attempt the turn records the error in `lastTurnError`.
+- **Summaries and estimates.** The model call that writes a context summary sees the text of the summarized items,
+  without their images. `estimateInputTokens` gets requests without image bytes; the AI SDK client counts
+  `estimatedImageInputTokens` (1600) for each image.
+- **Without a store.** A tool source result's references are still stored for display, but the model sees only the
+  text. A function tool's images fail the call instead, without a retry.
+- **AI SDK.** `createAiSdkModelClient` sends each image after the item's text as an AI SDK `file` part with its bytes:
+  `{ type: "file", mediaType, data: { type: "data", data } }`. A user message's content is a text part and one file
+  part per image. A tool result with images has `content` output, a text part and one file part per image; the
+  provider package converts it, and a provider that takes no images in a tool result handles them as its package
+  does.
+- **Your own model client.** Convert each reference in `images` to the provider's image part with its bytes from
+  `ModelRequest.imageBytes`, and throw when they are missing. A client that ignores `images` shows the model the text
+  only.
+- **Which tools return images.** A tool source's `ToolExecutionResult.images`, such as the image content of a
+  `new McpToolSource(servers, { mediaStore })` result. Give the source the store the runner reads. A function tool
+  returns `functionToolResult`; see [Images from function tools](#images-from-function-tools).
+
+### Images from function tools
+
+A function tool gets the runner's media store as `ToolCallContext.mediaStore`, or `undefined` when the runner has
+none. It uploads the bytes inside its call and returns the references with its text through `functionToolResult`:
+
+```ts
+import { functionTool, functionToolResult } from "@superdurable/dex-agents/builtin-loop";
+
+const takeScreenshot = functionTool<Record<string, never>>({
+  name: "take_screenshot",
+  description: "Take a screenshot of the screen.",
+  parameters: { type: "object", properties: {} },
+  effect: "read",
+  execute: async (_args, context) => {
+    if (context.mediaStore === undefined) {
+      return "Screenshots need a media store.";
+    }
+    const reference = await context.mediaStore.putImage(await screen.capturePng());
+    return functionToolResult({ output: "Took a screenshot.", images: [reference] });
+  },
+});
+```
+
+- The runner returns the `FunctionToolResult` that `functionToolResult` created as a `ToolExecutionResult` with the
+  same output and images, so the images are stored, checked, and shown to the model exactly like a tool source's.
+  Only the object `functionToolResult` returned counts: a plain object, or a copy, with the same fields is still
+  serialized as JSON.
+- More than `maxImagesPerMessage` images, or a reference that `validateImageReference` refuses, fails the attempt
+  with `ImageValidationError`. A failed attempt of a `read` or `idempotent_write` tool retries; a single-attempt call
+  records `outcome_unknown`.
+- Images from a runner without a media store throw `ToolExecutionError`, because no retry could show them. The
+  session records `failed` once, without a retry, and the model sees the error text.
+- A retried attempt uploads the same bytes to the same object, so uploading again is safe. A replay reads the stored
+  references, so the tool does not run again.
 
 ## Message storage and retention
 
@@ -738,10 +996,22 @@ interface AgentFrameworkRunner<ToolOutcome = ToolExecutionResult> {
   runModelStep(turn: AgentTurnContext): Promise<AgentTurnOutcome>;
   executeDeferredToolCall(call: DeferredToolExecution): Promise<ToolOutcome>;
   buildUnfinishedTurnMessages?(turn: AgentTurnContext): FrameworkMessage[]; // optional
+  buildUserMessageWithImages?(text: string, images: AgentImageReference[]): FrameworkMessage; // optional; see Images
 }
 
-type AgentTurnOutcome = TurnCompleted | ToolCallsRequested;
-interface TurnCompleted { kind: "completed"; newMessages: FrameworkMessage[]; usage: AgentUsage }
+type AgentTurnOutcome = TurnCompleted | ToolCallsRequested | TurnContinued;
+interface TurnCompleted {
+  kind: "completed";
+  newMessages: FrameworkMessage[];
+  usage: AgentUsage;
+  turnError?: string;                 // optional since 0.5.0: end the turn as failed, without a retry
+}
+interface TurnContinued {             // since 0.5.0
+  kind: "turn_continued";
+  frameworkRunState: string;          // non-empty, opaque to the session
+  newMessages: FrameworkMessage[];    // stored now; requires buildUnfinishedTurnMessages
+  usage: AgentUsage;
+}
 interface ToolCallsRequested {
   kind: "tool_calls_requested";
   frameworkRunState: string;          // non-empty, opaque to the session
@@ -756,6 +1026,7 @@ interface FrameworkMessage {
   text: string | null; toolCallId: string | null; toolName: string | null;
   toolArguments: string | null; toolOutput: string | null;
   frameworkItem: string;              // framework-native JSON, replayed unchanged
+  images?: AgentImageReference[];     // optional display projection; see Images
 }
 ```
 
@@ -776,7 +1047,7 @@ calls it for the turn failure note.
 | --- | --- |
 | `flowId`, `turnId`, `attempt` | Session ID, `turn-<n>`, one-based `RunModel` attempt |
 | `messages` | Every stored message in sequence order, including this turn's user message |
-| `frameworkRunState`, `isResuming` | Run state from this turn's last `ToolCallsRequested`, or `null` for the turn's first model call |
+| `frameworkRunState`, `isResuming` | Run state from this turn's last `ToolCallsRequested` or `TurnContinued`, or `null` for the turn's first model call |
 | `toolCalls`, `recordedToolCall(id)` | This turn's tool call records, in deferral order; all final when `runModelStep` runs |
 | `resolveToolPolicy(name, frameworkEffect?)` | Effective `ResolvedToolPolicy { effect, requiresApproval }` |
 | `events` | `AgentEventWriter` bound to this turn and attempt |
@@ -812,13 +1083,20 @@ The runner must:
    every message of the turn the session has not stored yet, in order: model
    output, tool requests, tool results, and the answer. Without incremental
    messages, that is every message the turn produced after its user message.
-6. Report only this model call's usage. Use `emptyAgentUsage()` and
+6. To make another model call within the same turn, return `TurnContinued`
+   with the run state and the messages to store now, ending with a user
+   message when the provider needs the request to end with one. The session
+   stores them and runs `RunModel` again. A runner that never needs this
+   ignores it. To end the turn as failed without a retry, such as at a
+   limit the runner enforces, return `TurnCompleted` with `turnError`; the
+   session stores `newMessages` and sets `lastTurnError` to that text.
+7. Report only this model call's usage. Use `emptyAgentUsage()` and
    `addAgentUsage()` when a framework reports several usage parts. Optionally
    return `modelCallMetadata: { requestModel, responseModel, providerName,
    responseId, finishReasons }` in either outcome. The session never stores it;
    it names the `chat` span (see [Tracing](#tracing)). Omit a field the
    framework does not expose.
-7. Throw for an unexpected failure. The model call reruns from the same
+8. Throw for an unexpected failure. The model call reruns from the same
    committed state, up to 3 attempts within 30 minutes; then the turn fails.
 
 **Incremental turn messages (optional).** A runner may return the turn's
@@ -1007,7 +1285,133 @@ const waiting = await client.searchFlows('ActiveStepTypes = "AwaitToolApproval"'
 `AwaitQuestionAnswer` finds questions the same way. A session leaves the search when it moves on. `Client.startFlow`
 does not turn this on; pass `configOverride: { activeStepSearchMode: agentSessionActiveStepSearchMode }` there, or use
 `Client.updateFlowConfig` for a running session. See
-[Find sessions that need a person](https://docs.superdurable.io/agent-frameworks/deploy-agents#find-sessions).
+[Find sessions that need a person](https://docs.superdurable.io/reference/agents/approvals#find-sessions).
+
+## Showing what an approval acts on
+
+A tool approval can say what the call acts on and what it does. Its tool source returns an
+`AgentInterruptDisplay` `{ target, summary, preview? }` in `DeferredToolCall.approvalDisplay`, and the session
+stores it in `AgentInterrupt.display`, on the call's record as `approvalDisplay`, and in the `interrupt_raised`
+event. A queued ordered write raises its approval later with the display its source built when the model asked.
+
+```ts
+const snapshot = await client.invokeRPC(flow.getAgentSnapshot, sessionId);
+for (const interrupt of snapshot.pendingInterrupts) {
+  console.log(interrupt.display?.summary ?? interrupt.arguments);
+}
+```
+
+- `ConnectorToolSource` and the CLI's connector tools build it with `buildConnectorToolApprovalDisplay`: the
+  target is `<connector>/<connection>`, and the summary names the operation, the connection, and up to five short
+  arguments, such as `Calls slack postChannelMessage with connection support-slack; channel: "#eng".`
+- The CLI's local file writes name the workspace path and carry a unified diff against the file as it is when the
+  model asks; its header lines say so. Its shell commands name the working directory and the command with its
+  inline credentials redacted and its control characters escaped, cut at 2 KiB; the full command is in the call's
+  arguments.
+- A display never says how often the call runs or what it achieves, and never uses a tool's description as its
+  effect.
+- Redaction in a display is best-effort hygiene, not a security boundary. The display's text comes from the call's
+  arguments, which the session stores in full as before, and an agent can read a workspace file with its own tools.
+  A credential-like argument (`isCredentialLikeName`) shows `<redacted>`, and `redactInlineCredentials` replaces
+  common credential shapes: the value after a credential-like name, read as a shell word, a triple-quoted string, or
+  a YAML block; `Authorization` and `Cookie` header values; URL passwords; `sshpass -p`; and common token shapes.
+  It reads `\uXXXX`, `\xXX`, and `%XX` escapes to find credentials but changes no other text: escapes stay as
+  written, and only the characters of each credential become `<redacted>`. It is conservative, so a generic
+  `key=value` is redacted too, and the CLI leaves out a file preview whose text it changes. It finds common forms
+  only, and Unicode lookalike letters are out of scope; `agents/conformance/approval_display.json` lists the cases
+  both cores share.
+- The session cuts a target over `maxApprovalTargetBytes` (1 KiB) and a summary over `maxApprovalSummaryBytes`
+  (2 KiB), ending them with `…`, and drops a preview over `maxApprovalPreviewBytes` (16 KiB). A tool without a
+  display, and every approval a Worker before 0.6.0 raised, has `display` `null`: show the concrete arguments, not a
+  guessed effect.
+
+## User messages the session writes
+
+Since 0.6.0, a stored `user` message that the session wrote itself, not a person, carries
+`AgentMessage.origin`. Show such a message as a session note, or hide it, never as text the user typed.
+
+| `origin` | Message |
+| --- | --- |
+| `plan_execution` | The message with which `execute_plan` starts the turn, `buildPlanExecutionMessage(revision)` |
+| `turn_failure_note` | The note `RecordTurnFailure` stores for the model after a failed turn whose tools ran |
+| `turn_steered_note` | The note that lists the tool calls that ran before `steer_user_message` ended the turn |
+| `turn_cancelled_note` | The note that lists the tool calls that ran before `cancel_turn` ended the turn |
+
+```ts
+const page = await client.invokeRPC(flow.listAgentMessages, sessionId, { beforeSequence: null, limit: 50 });
+for (const message of page.messages) {
+  if (message.origin === "plan_execution") {
+    console.log("Running the approved plan");
+  } else if (message.origin === undefined && message.role === "user") {
+    console.log(`> ${message.text ?? ""}`);
+  }
+}
+```
+
+- Only the session sets `origin`. `send_user_message`, the start input's initial message, and a runner's messages,
+  such as a `decideTurnContinuation` message, have none.
+- The wire field is `origin`, `null` when absent; a decoded message omits it. Messages stored before 0.6.0 have
+  none. A Worker before 0.6.0 ignores the field, and drops it when it moves the message into an archive chunk.
+- A later release may add values. The decoder keeps a value it does not know, so treat any `origin` as written by
+  the session.
+
+## Listing sessions
+
+Since 0.6.0, a session can keep a summary that a session list needs: its title, the first 80 Unicode code points of
+the first user message; the time its latest turn started or ended; and its turn count. Turn it on with
+`summaryAttributesIndexed: true`; the adapter factories, such as `createBuiltinAgentSessionFlow`, take the same option.
+It is off by default, and `flow.options.summaryAttributesIndexed` tells whether a Flow keeps it. `listAgentSessions` reads one page of sessions in one `Client.searchFlows` call, without a snapshot
+per session and without a running Worker:
+
+```ts
+const flow = createAgentSessionFlow(runner, "SupportAgent", { summaryAttributesIndexed: true });
+const page = await listAgentSessions(client, flow.getFlowType(), { pageSize: 50, titleSearch: "refund" });
+for (const session of sortAgentSessionsByLastActivity(page.sessions)) {
+  console.log(session.sessionId, session.title ?? "—", session.lastActivityAt?.toISOString() ?? "—", session.turnCount);
+}
+```
+
+- Dex returns running sessions first, then the most recently closed and started ones. It cannot sort by last
+  activity, so `sortAgentSessionsByLastActivity` sorts the sessions you loaded.
+- `titleSearch` matches whole words of the title, without case: `flaky` finds "Fix the flaky test", `flak` does not.
+  Pass the same `titleSearch` with each `nextPageToken`.
+- A session without the option, or one that an earlier release started, lists without the summary, and a title search
+  never finds it. An earlier session gains the last activity time and the turn count at its next turn on a Worker with
+  the option. Show each missing value as a dash. Until a Worker with the option has started on the server, a title
+  search throws `SessionTitleSearchUnavailableError`.
+- A session that fails because its state would exceed the server's limit can keep the values of its last turn start.
+- Privacy: the title is the user's own text, and anyone who can search the namespace's Flows reads it. Turn the option
+  on only when the first message may be stored in the search index.
+- The three Attributes are indexed under `text1` (FULL_TEXT), `datetime1` (DATETIME), and `int1` (INT), the generic
+  keys that every Flow type of a namespace shares. A Worker with the option registers them when it starts. With
+  PostgreSQL search, a namespace has three keys of each of these types; the Worker fails to start with
+  `FAILED_PRECONDITION` when the namespace registered one of these keys with another type, or when all three keys of
+  the type are taken by other names. Search queries of other Flow types must filter on `FlowType`.
+
+## Showing sessions in Dex Web
+
+Dex Web draws a session and offers its Actions from the session Flow
+Definition Graph. Let the Worker upload it: pass
+`sessionFlowDefinitionDocument({ flowType, actionPermission })` in
+`WorkerOptions.flowDefinitions`.
+
+```ts
+import { Registry, Worker } from "@superdurable/dex";
+import { sessionFlowDefinitionDocument } from "@superdurable/dex-agents";
+
+const worker = new Worker(new Registry([flow]), blobCache, {
+  flowDefinitions: [
+    sessionFlowDefinitionDocument({ flowType: "SupportAgent", actionPermission: "support-agent.operate" }),
+  ],
+});
+```
+
+The upload needs server-zd 0.1.26 or later. The document's `generatedAt` is
+the time the graph template last changed, the same in both cores, so a restart
+writes nothing and an upgrade replaces the graph. For an older server, render
+a file with `renderSessionFlowGraph` or the `dex-agents-session-graph` command
+and pass its directory to Dex Web with `--flow-rendering-dir`. See
+[Show sessions in Dex Web](https://docs.superdurable.io/reference/agents/dex-web).
 
 ## Spend limits
 
@@ -1015,7 +1419,7 @@ does not turn this on; pass `configOverride: { activeStepSearchMode: agentSessio
 across many sessions. The session asks it before each model call and reports what
 the call used. Counters and limits belong to the application. Without one, the
 session makes no checks. See the interface's documentation and
-[Spend limits](https://docs.superdurable.io/agent-frameworks/deploy-agents#spend-limits).
+[Spend limits](https://docs.superdurable.io/reference/agents/spend-limits).
 
 ## Flow shape
 
@@ -1116,6 +1520,9 @@ Do not repeat these tool calls unless the user asks again.
 | `PlanExecutions` | ChannelMap, key = `planExecutionKey(revision)` (decimal) | `PlanExecutionRequest { revision }` |
 | `PendingPlanExecution` | Attribute | `PlanExecutionRequest` that `execute_plan` accepted and `AwaitUserMessage` has not consumed |
 | `ContextSummary` | Attribute | `ContextSummary`, set once the session compacts |
+| `AgentSessionTitle` | Attribute, indexed FULL_TEXT `text1`; only with `summaryAttributesIndexed` | string, the first user message's title; set by the first turn only |
+| `AgentSessionLastActivityAt` | Attribute, indexed DATETIME `datetime1`; only with `summaryAttributesIndexed` | string, RFC 3339 time the latest turn started or ended |
+| `AgentSessionTurnCount` | Attribute, indexed INT `int1`; only with `summaryAttributesIndexed` | int64, `AgentState.turnCount` as of the latest turn start or end |
 | `AgentEvents` | Stream | `AgentEvent` |
 
 `AgentState.status` is `waiting_for_user_message`, `running_model`,
@@ -1155,7 +1562,7 @@ IDs are `turn-<n>`, where `n` is `turn_count + 1` when the turn starts.
 | `tool_call_deferred` | `{"tool_call_id","tool_name","effect","requires_approval"}`; the model asked for a call, which runs in its own Step |
 | `tool_call_started` | `{"tool_call_id","tool_name"}` |
 | `tool_call_finished` | `{"tool_call_id","tool_name","status"}`; the record became final, including a rejection |
-| `interrupt_raised` | `{"interrupt_id","kind","tool_call_id","tool_name","deadline","question","choices","allows_free_text"}` |
+| `interrupt_raised` | `{"interrupt_id","kind","tool_call_id","tool_name","deadline","question","choices","allows_free_text","display"}`; `display` is `{"target","summary","preview"}` or `null` |
 | `interrupt_resolved` | `{"interrupt_id","kind","approved","answered","rejection_message","cancellation_reason"}`; `answered` is `true` only for an answered question, and `cancellation_reason` is `"steered"` or `"turn_cancelled"` when steering or cancellation removed the interrupt |
 | `timer_started` | `{"tool_call_id","wait_until","reason"}` for a `durable_wait` call |
 | `plan_updated` | `{"revision","status","task_count"}` after `write_todos` replaced the plan, or when an approval marks a draft `active` |
@@ -1191,12 +1598,13 @@ cannot defer it.
 
 `@superdurable/dex-agents/mcp` turns the tools of MCP servers into tools of an
 agent session. Every MCP tool call runs in its own tool Step, with an effect
-class from the tool's annotations, so a crash never repeats a write silently.
+class from the tool's annotations or from the [Dex MCP
+conventions](#dex-mcp-conventions), so a crash never repeats a write silently.
 It needs `@modelcontextprotocol/sdk` 1.x, an optional peer dependency; the main
 entry point never imports it:
 
 ```bash
-npm i @superdurable/dex-agents @superdurable/dex@1.38.0 @modelcontextprotocol/sdk zod
+npm i @superdurable/dex-agents @superdurable/dex@1.45.0 @modelcontextprotocol/sdk zod
 ```
 
 Configure the servers on the Worker, never from Flow input, a user message, or
@@ -1216,7 +1624,7 @@ const tools = new McpToolSource([
 ]);
 ```
 
-A Stepwise agent takes the source in `toolSources`; see
+A built-in loop agent takes the source in `toolSources`; see
 [Tool sources](#tool-sources). Another runner offers the tools and defers every
 call; the tool Step runs it:
 
@@ -1248,7 +1656,9 @@ server is listed again in the background while its earlier tools are
 returned. A server that cannot be listed is left out with a warning and is not
 tried again for `listingFailureBackoffMs` (30 seconds), then in the
 background, so one bad server never hides the others' tools or slows every
-model call. One listing per server runs at a time. `listTools({ refresh: true
+model call. The warnings go to `console.warn` unless `logWarning` sends them
+elsewhere, such as a log file; a `logWarning` that throws falls back to
+`console.warn`. One listing per server runs at a time. `listTools({ refresh: true
 })` lists every server again now. `deferredToolCall` stores the
 server, the tool's MCP name, and its task support on the call's record, so the
 tool Step calls that server directly, without a listing; `callTool` finds the
@@ -1258,6 +1668,16 @@ characters shortened with a hash. When two tools get the same name, the first
 in server order is offered and the other is left out with a warning. Key tool
 policies by that name.
 
+`executeDeferredToolCall(call, { requestMeta })` adds entries to the
+`tools/call` request's `_meta`, such as the identity the caller expects the
+tool to have; `callTool` takes the same `requestMeta` option. The idempotency
+key entry wins on a name clash. `willResumeToolTaskWithoutSending(call)` is
+`true` only when `executeDeferredToolCall` will return a session-polled task
+that an earlier attempt started and can never send `tools/call` for the call;
+a task polled inside the tool Step, such as one bound to a protocol session,
+may be called again when the server no longer knows it. A check that only
+guards a new send can be skipped when it is `true`. Since 0.5.0.
+
 ### Resources and prompts
 
 With `resourceAndPromptToolsEnabled: true`, `listTools` also offers three
@@ -1287,10 +1707,11 @@ or list-change notifications. The names are exported as
 
 ### Effects
 
-`toolEffectFromMcpToolAnnotations` classifies each tool:
+A tool with the Dex `effect` key keeps the declared effect; `toolEffectFromMcpToolAnnotations` classifies the others:
 
 | MCP annotations | Effect | Tool Step | Approval by default |
 | --- | --- | --- | --- |
+| any, with the Dex `effect` key in `_meta` | the declared effect; see [Dex MCP conventions](#dex-mcp-conventions) | by effect | Only with `approval: recommended` |
 | `readOnlyHint: true` | `read` | `CallTool` | No |
 | `idempotentHint: true`, whatever `destructiveHint` says | `idempotent_write` | `CallTool` | No |
 | anything else, or none | `defaultToolEffect`, `unclassified` by default | `CallSingleAttemptTool` | Yes |
@@ -1317,7 +1738,10 @@ signal aborts the request.
 | What happens | Recorded | Re-issued? |
 | --- | --- | --- |
 | A result | `succeeded`: text blocks joined with newlines, other content as JSON | - |
+| A result with `image` content, on a source built with `mediaStore` | `succeeded`: each image uploaded and recorded in `images`; the text shows `[image <n>]` in its place, counting from 1. More than 20 images, base64 that is invalid or not canonical, or bytes that are not a supported image: `failed` (`ToolExecutionError`) | - |
+| An `isError`, `rejected`, or `unknown` result with `image` content | As above, with `[image <n> omitted]` for each image in the text, with or without a store, so the recorded error holds no image bytes | As above |
 | An `isError` result, or a JSON-RPC error response other than `-32603` | `failed` with the text (`ToolExecutionError`) | No |
+| A result or error with the Dex `outcome` key | `outcome_unknown` or `failed`; see [Dex MCP conventions](#dex-mcp-conventions) | No |
 | The call was never sent: its server is not configured, or 3 connection attempts failed | `failed` | No |
 | The connection broke, the server exited, or the request timed out after it was sent; an internal error (`-32603`), an HTTP error status, or an unreadable body, which a gateway can return after the server ran the call | `McpToolCallInterruptedError`, a Step failure | `read` and `idempotent_write`: `CallTool` sends a new request, same idempotency key, up to 3 attempts. Other effects: `outcome_unknown`, never sent again |
 
@@ -1347,7 +1771,7 @@ only delays the next poll. A server that no longer knows the task, or cannot be
 reached for three poll attempts, records `failed` for a `read` tool and
 `outcome_unknown` otherwise. `cancel_turn` abandons the task, and
 `cancelToolTask` sends `tasks/cancel`; forward it from your runner's
-`cancelToolTask`, as the Stepwise runner does. Any answer from the server ends
+`cancelToolTask`, as the built-in loop runner does. Any answer from the server ends
 the cancellation, so a retried one is harmless.
 
 The source requests such a task's TTL as `taskTtlMs`, 24 hours by default. The
@@ -1379,13 +1803,117 @@ task's input request into a session question. The source declares no
 elicitation, sampling, or roots capability, so a server cannot send those
 requests directly.
 
+### Dex MCP conventions
+
+An MCP server built for Dex, such as one that serves Dex connectors, carries a
+connector's guarantees across MCP with `_meta` keys under the
+`io.superdurable.dex/` prefix. A server that sets none of them behaves exactly
+as described above. Both cores follow the same rules, and
+[`agents/conformance/mcp_dex_conventions.json`](../../conformance/mcp_dex_conventions.json)
+fixes them case by case. Since 0.5.0.
+
+| Key | Where | Values |
+| --- | --- | --- |
+| `io.superdurable.dex/effect` (`mcpToolEffectMetaKey`) | tool definition `_meta` in `tools/list` | `read`, `idempotent_write`, `non_idempotent_write` |
+| `io.superdurable.dex/approval` (`mcpToolApprovalMetaKey`) | tool definition `_meta` in `tools/list` | `recommended` |
+| `io.superdurable.dex/outcome` (`mcpToolOutcomeMetaKey`) | `tools/call` result `_meta`, or JSON-RPC `error.data._meta` | `unknown`, `rejected` |
+| `io.superdurable.dex/idempotencyKey` (`mcpIdempotencyKeyMetaKey`) | `tools/call` request `_meta`, sent by the source | `<flowId>/<turnId>/<toolCallId>` |
+
+**Tool definitions.** A tool with the `effect` key is declared, as a connector
+manifest declares an operation for `ConnectorToolSource`:
+
+- Its effect class is the declared value, whatever its annotations say:
+  `read` and `idempotent_write` run in `CallTool`, `non_idempotent_write` in
+  `CallSingleAttemptTool`. A declared write runs in the model's order after the
+  turn's earlier writes, and a write after one that did not succeed is skipped.
+- Without a session policy, its calls wait for approval only with `approval:
+  recommended`, like `agent.approval: recommended` in a manifest. Any other
+  `approval` value, `null` included, also asks, so an unknown value fails
+  closed.
+- A session policy in `toolPolicies` for the tool may keep or raise its
+  safety, never lower it. The call gets the more conservative of the declared
+  effect and the policy's effect, ranked `read`, `idempotent_write`,
+  `non_idempotent_write`, then `unclassified`. So a policy
+  `{ effect: "non_idempotent_write" }` on a tool declared `read` runs it once in
+  `CallSingleAttemptTool`, in the model's order, after approval. A declared
+  `non_idempotent_write` stays one with a `read` policy.
+- The policy's `requiresApproval`, when set, wins. When it is left out, a call
+  waits for approval when the tool recommends it or the policy's effect asks
+  for approval by default, as `non_idempotent_write` does.
+- A framework adapter gets the same rule from
+  `tools.mergeToolPolicies(yourPolicies)`. Do not spread your policies after
+  `tools.toolPolicies()`: yours would replace the declaration and could lower
+  its effect.
+- `approval` without `effect` is ignored. An `effect` value outside the three
+  above gives the tool the session's `defaultToolEffect` and ignores its
+  annotations, with a warning log.
+- `trustsToolAnnotations: false` also ignores both keys.
+
+**Results.** The `outcome` key reports what a call did:
+
+| `outcome` | Recorded | The model sees | Sent again? |
+| --- | --- | --- | --- |
+| `unknown` | `outcome_unknown` (`ToolOutcomeUnknownError`), with the result's text as `error` | `outcomeUnknownToolResult` | Never, for any effect class |
+| `rejected` | `failed` (`ToolExecutionError`) | `The tool call failed: <text>` | Never |
+| absent | as in "What a call does" | | |
+
+- The key wins over `isError` and over the JSON-RPC error code. Set
+  `isError: true` with either value, so a client that does not know these
+  conventions never reads the result as a success.
+- The text is the result's text: text blocks joined with newlines, other
+  content as JSON. A result without text gets a fixed text. Write a message
+  that is safe to show the model and the user.
+- In the JSON-RPC error form, put the key in `error.data._meta`. The text is
+  `MCP error <code>: <message>`. An internal error (`-32603`) with the key is
+  not re-issued.
+- A task's completed result follows the same rule, whether the tool Step or
+  `PollToolTask` reads it.
+- Other values are reserved; the source ignores them with a warning log.
+
+**Idempotency key.** Every `tools/call` from a tool Step carries the session's
+idempotency key. It is the same on every attempt of one tool call, including a
+`CallTool` retry and an attempt after a Worker restart, and it is unique per
+tool call. Treat it as opaque. A server that follows these conventions derives
+its own call ID from it, such as a hash, and keeps a fence per call ID: a
+retried attempt gets the first attempt's result and never applies the write a
+second time. When the server cannot tell whether an earlier attempt took
+effect, it answers `outcome: unknown`. It should refuse a declared write that
+arrives without the key, because it cannot recognize a retry of that call.
+Task requests (`tasks/get`, `tasks/update`, `tasks/cancel`) carry no key; the
+task ID names the call there.
+
+A declared tool, as `tools/list` returns it:
+
+```json
+{
+  "name": "send_payment",
+  "description": "Send a payment.",
+  "inputSchema": {"type": "object", "properties": {"amount": {"type": "integer"}}},
+  "annotations": {"idempotentHint": true},
+  "_meta": {
+    "io.superdurable.dex/effect": "idempotent_write",
+    "io.superdurable.dex/approval": "recommended"
+  }
+}
+```
+
+A result whose outcome is unknown:
+
+```json
+{
+  "content": [{"type": "text", "text": "the payment provider timed out"}],
+  "isError": true,
+  "_meta": {"io.superdurable.dex/outcome": "unknown"}
+}
+```
+
 ### With a framework adapter
 
 The runner above is the core's runner-agnostic path. A framework adapter uses
 the source when it accepts tools defined by a JSON Schema: wrap each `McpTool`
 as a framework tool that calls `tools.callTool(name, input, { idempotencyKey })`
 with the key from the adapter's tool context, and pass
-`{ ...tools.toolPolicies(), ...yourPolicies }` as the adapter's `toolPolicies`.
+`tools.mergeToolPolicies(yourPolicies)` as the adapter's `toolPolicies`.
 No adapter package changes for this.
 
 | Adapter | Schema-only tool | Key inside the tool |
@@ -1403,7 +1931,7 @@ so a wrapper is its only path to tool Steps.
 ## Connector tools (`@superdurable/dex-agents/connectors`)
 
 `@superdurable/dex-agents/connectors` offers reviewed Connector operations to a
-Stepwise agent as tools. `ConnectorToolSource` implements `ToolSource`, like
+built-in loop agent as tools. `ConnectorToolSource` implements `ToolSource`, like
 `McpToolSource`. Each call runs one operation in its own tool Step through the
 Connector SDK's `runQuery` or `runMutation`, so the connector's Call ID,
 idempotency key, credential handling, and single-dispatch fence apply. Install
@@ -1438,7 +1966,10 @@ an operation whose entry lacks `agent.exposed: true`, an `agent` value it does
 not know, an `agent.branches` key that is not an optional branch (or an
 `unknown` one on a Query), or an `inputSchema` keyword it cannot check. The
 tool name defaults to `<connectorId>_<operation in snake case>`; the
-description and argument schema come from the manifest. A Mutation is any
+description and argument schema come from the manifest. The snake case is
+connectorctl's, which also names the Python Step factories: an acronym run
+stays one word, so `listStoryIDs` becomes `list_story_ids`.
+`agents/conformance/connector_tools.json` pins it. A Mutation is any
 operation with an `idempotencyKey` method.
 
 | Operation | Effect | Tool Step | Retries |
@@ -1467,13 +1998,42 @@ back. A `RetryError` goes through `throwDexRetry`, except for a single-attempt w
 whose fence saved `notSent` or `canResend` in this attempt: that records `failed` with
 `connectorNotSentRetryLater` instead of `outcome_unknown`.
 
+The first matching row wins. The rows before the listing can only make an
+outcome unknown:
+
 | Branch | Record | The model reads |
 | --- | --- | --- |
-| A required (success) branch | `succeeded` | The value as compact JSON, keys sorted |
+| `uncertain`, whatever the listing or the required branches say | `outcome_unknown` (`ToolOutcomeUnknownError`) | `outcomeUnknownToolResult` |
+| A Mutation's `defect`, whatever the listing or the required branches say | `outcome_unknown` | The same text |
+| A required (success) branch other than `defect` | `succeeded` | The value as compact JSON, keys sorted |
+| Any Mutation branch when its fence cannot prove that nothing was sent | `outcome_unknown` | The same text |
 | Listed `rejected` under `agent.branches` | `failed` (`ToolExecutionError`) | `<connector> <operation> returned <branch>: <kind>: <message>` |
-| `defect` | `failed` | The same text |
-| A Query branch not listed | `failed` | The same text |
-| `uncertain`, listed `unknown`, or a Mutation branch not listed | `outcome_unknown` (`ToolOutcomeUnknownError`) | `outcomeUnknownToolResult` |
+| Listed `unknown`, or a Mutation branch not listed | `outcome_unknown` | `outcomeUnknownToolResult` |
+| A Query branch not listed, including `defect` | `failed` | `<connector> <operation> returned <branch>: <kind>: <message>` |
+
+A Mutation's `defect` is not always local: the Connector SDK selects it for
+some attempts that already called the provider, such as an invalid attempt or
+an undeclared branch, and the source cannot tell those apart. A Query's
+`defect` follows its listing.
+
+A Mutation that uses the single-dispatch fence gets one more check, the same
+one the Go Connector SDK makes for Go agent hosts. The source observes every
+fence marker the attempt saves through its Step context, bound to the call's
+Call ID and attempt. Once the fence claims a send, or records a provider ID,
+the attempt may have sent. Only a later `canResend` marker of the same call and
+attempt, after a claim without a provider ID, lowers that, as the fence's own
+`recordCanResend` does. The operation's own later checkpoints never lower it.
+On a retry that reads the earlier checkpoint, a missing checkpoint, one that is
+not a fence marker, a malformed one, another call's, or one that does not allow
+this attempt a send also means the request may have been sent. While the
+request may have been sent, every branch but the success branch records outcome
+unknown, whatever the listing says, and a Retry is never proof that nothing was
+sent. The core cannot see inside the fence, so it reads the markers instead of
+the fence's own events: a forged `canResend` marker of the same call would
+count. A Mutation that never reads its checkpoint and never saves a fence
+marker gets no such check and relies on its listing.
+`agents/conformance/connector_tools.json` pins these cases in
+`fenceObservationCases`.
 
 A result over `maxResultBytes` (default `defaultConnectorResultMaxBytes`,
 64 KiB of UTF-8 text, set per source or per tool) is cut, followed by
@@ -1495,7 +2055,7 @@ README. An adapter serves them through `ToolSourceRouter`, exported from the
 package root: it lists the sources in each `RunModel`, refuses name
 collisions, lets the source build each deferred call, so the effect, the
 approval, and the write order come from the source, and routes the tool Step,
-its Step options, and polls back to that source. The Stepwise runner uses it
+its Step options, and polls back to that source. The built-in loop runner uses it
 too.
 
 ## UI streams
@@ -1723,7 +2283,7 @@ The snapshot JSON is the `get_agent_snapshot` wire format without the fields
 only the session's Steps use. Messages leave out `framework_item`, the
 framework's replay data, which can hold the agent's instructions. Tool calls
 leave out `tool_source_reference`, `trace_context`, `input_continuation`,
-`input_answers`, and `task_answer_pending`. Read them with `getAgentSnapshot` on the server when needed. It
+`input_answers`, `task_answer_pending`, and `runner_tool_state`. Read them with `getAgentSnapshot` on the server when needed. It
 includes `session_settings` as stored, so keep anything a browser must not see out of session settings, or
 remove the key.
 
@@ -1887,7 +2447,7 @@ real Dex Server with no model key:
 | `AgentSessionTestClient` | Typed RPC calls (`resolveInterrupt` retries lock conflicts) and Worker-free waits on committed Attributes |
 | `readStepHistory(serverAddress, flowId)` | Completed Step methods from `dexcli flow history`, to assert a turn's Step shape |
 | `FileGate`, `InvocationLog` | Pause Worker code at an exact point; count real tool runs across processes |
-| `ScriptedModelClient` | Stepwise `ModelClient` that answers from a script, like the Python core's; the same class as `@superdurable/dex-agents/stepwise` exports. See [Demo model without a key](#demo-model-without-a-key) |
+| `ScriptedModelClient` | Built-in loop `ModelClient` that answers from a script, like the Python core's; the same class as `@superdurable/dex-agents/builtin-loop` exports. See [Demo model without a key](#demo-model-without-a-key) |
 | `pollUntil(probe, options)` | Deadline polling where the Client has no direct wait |
 | `findFreeLoopbackPorts(count)` | Distinct free loopback ports, chosen with every listener held open until all are picked |
 
@@ -1980,7 +2540,7 @@ use a scripted runner (`test/fixtures/scripted-agent-runner.ts`) and cover:
 - two tools of one response that ask at once, both answerable, and a sibling
   approval resolved while a tool runs that never reappears as pending.
 
-The Stepwise tests (`test/integ/stepwise-*.integration.test.ts`) run the
+The built-in loop tests (`test/integ/stepwise-*.integration.test.ts`) run the
 built-in loop on the AI SDK's `MockLanguageModelV4`, scripted from its prompt
 (`test/fixtures/stepwise-scripted-language-model.ts`), and cover:
 
@@ -2112,6 +2672,7 @@ built-in loop on the AI SDK's `MockLanguageModelV4`, scripted from its prompt
   attempts, on every `listTools` call until it answers. A server that binds
   tasks to its protocol session, such as a stateful server on the SDK's task
   store, cannot resume a task across attempts; the retry calls the tool again.
+- Images: the media stores keep no local read cache, so each `loadImages` reads the store.
 - Tracing covers the session's Steps only. The Dex SDK emits no spans, so Dex
   Server and Worker internals do not appear in the traces.
 - The adapters report only the model information their framework exposes, so