@ouispec/agent-worker 0.4.0 → 0.8.0

package/dist/orchestrator.js

@@ -19,14 +19,24 @@
  *   - Configurable TurnPolicy for product-specific step control
  */
 import { streamText, dynamicTool, jsonSchema, isStepCount, hasToolCall } from 'ai';
-import { AGENT_SOCKET_EVENTS, argsHash } from '@ouispec/agent-core';
+import { AGENT_SOCKET_EVENTS, argsHash, canonicalJson, turnStoppedNote, } from '@ouispec/agent-core';
+import { DEFAULT_STOP_GRACE_MS, TurnStopped, stopOf, watchTurnStop } from './stop/turn-stop.js';
+import { stoppedTurnMessages } from './stop/partial.js';
+import { resultText, stoppedNotRun, stoppedWhileRunning } from './stop/results.js';
 import { defaultTurnPolicy } from './turn-policy.js';
 import { evaluateToolPolicySafe } from './authz/tool-policy.js';
 import { createToolInputValidator } from './tools/input-validation.js';
 import { readClientPage, withoutClientUI } from './ui/snapshot.js';
-import { readClientKnowledge, withClientKnowledge } from './ui/knowledge.js';
+import { KNOWLEDGE_TOOL, knowledgeTool, readClientKnowledge, withClientKnowledge } from './ui/knowledge.js';
+import { withNewestPageStateOnly } from './ui/newest-page-state.js';
 import { withClock } from './prompt/clock.js';
-import { buildUITools, createPageSight, DefinitionUnavailable, fitNotes, UI_ACT_TOOL, UI_DESCRIBE_TOOL, UI_READ_TOOL, } from './ui/ui-tools.js';
+import { withUserText } from './prompt/user-text.js';
+import { AttachmentGuard } from './attachments/guard.js';
+import { ATTACHMENT_DATA_NOTE, turnAttachmentParts, withReferenceLines, withTurnAttachments, withoutLeftOut } from './attachments/content.js';
+import { attachmentTools } from './attachments/tools.js';
+import { acceptsMediaType, attachmentIdsIn, attachmentNameForModel, misplacedAttachmentInputs } from '@ouispec/agent-core';
+const ATTACHMENT_LIST_HINT = 'attachment_list lists the files that can.';
+import { buildUITools, createPageSight, DefinitionUnavailable, fitNotes, jobWaitOf, UI_ACT_TOOL, UI_DESCRIBE_TOOL, UI_READ_TOOL, } from './ui/ui-tools.js';
 import { DEFAULT_INDEX_CHARS, indexText, pageFingerprint } from './ui/page-index.js';
 import { describeSchema } from './ui/outline.js';
 import { createUISequence } from './ui/ui-sequence.js';
@@ -34,7 +44,7 @@ import { createTurnLedger } from './turn-ledger.js';
 import { DEFAULT_PAGE_STATE_CHARS, observationSchemas, observationsText } from './ui/observations.js';
 import { approvalRequirement, APPROVAL_TOOL_NOTE } from './approvals/requirement.js';
 import { buildApprovalPreview, declaredTitle } from './approvals/preview.js';
-import { approvalMarker, approvedExpiredMarker, expiredNote, markedResult, notRunResult, ranNote, refusedNote, resolveContinuation, unavailableNote, waitingCalls, } from './approvals/continuation.js';
+import { approvalMarker, approvedExpiredMarker, expiredNote, markedResult, notRunResult, ranNote, refusedNote, resolveContinuation, unavailableNote, waitingCalls, withdrawnMarker, } from './approvals/continuation.js';
 const DEFAULT_MAX_ROUNDS = 12;
 const DEFAULT_MAX_TOKENS = 4096;
 const DEFAULT_TEMPERATURE = 0.3;
@@ -76,6 +86,7 @@ export async function runAgentTurn(config, input) {
     const turnDeadlineMs = config.turnDeadlineMs ?? 240_000; // 4 min, below the 5 min Lambda ceiling
     const retries = config.retries ?? 3;
     const uiResultTimeoutMs = config.ui?.resultTimeoutMs ?? DEFAULT_UI_RESULT_TIMEOUT_MS;
+    const uiJobWaitMs = jobWaitOf({ jobWaitMs: config.ui?.jobWaitMs });
     if (!config.model) {
         throw new Error('[agent-sdk] config.model is required: pass an `ai` library model (ADR-0227 §2.2)');
     }
@@ -109,9 +120,35 @@ export async function runAgentTurn(config, input) {
     const heldDefinitions = client?.held ?? new Map();
     // Whether the page can be seen (ADR-0245 §2.5): nothing that changes it runs while it cannot.
     const sight = createPageSight();
-    const uiCounts = { describes: 0, reads: 0, acts: 0 };
+    const uiCounts = { describes: 0, reads: 0, acts: 0, guides: 0 };
+    // Earlier answers' page states replaced, summed over the turn's steps.
+    let pageStatesNotRepeated = 0;
     // The knowledge the client sent for its page goes after the host's prompt.
     const knowledge = readClientKnowledge(input.context ?? null);
+    // ─── Files (ADR-0252 §2.11, §2.12) ─────────────────────────────────────────
+    // With the host's file area, the turn's files go to the model with its
+    // message, the attachment tools reach every file of the conversation, and the
+    // cost guard caps what the model is given of them.
+    const fileArea = config.attachments ?? null;
+    const fileOwner = { userId: input.userId, accountId: input.accountId, conversationId: input.conversationId };
+    let conversationFileTokens = 0;
+    if (fileArea?.store.conversationUsage) {
+        try {
+            conversationFileTokens = await fileArea.store.conversationUsage(fileOwner, { signal: AbortSignal.timeout(5_000) });
+        }
+        catch (err) {
+            log('warn', 'agent:tool', 'Could not read the conversation’s use of files; only the turn’s cap applies', {
+                turnId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const fileGuard = new AttachmentGuard({
+        turnTokens: fileArea?.turnTokens,
+        conversationTokens: fileArea?.conversationTokens,
+        conversationUsed: conversationFileTokens,
+    });
+    const fileTools = fileArea ? attachmentTools({ store: fileArea.store, owner: fileOwner, guard: fileGuard }) : [];
     log('info', 'agent:ui', 'UI surfaces for this turn', {
         turnId,
         clientSentSnapshot: client !== null,
@@ -145,14 +182,59 @@ export async function runAgentTurn(config, input) {
     const hostPrompt = typeof config.systemPrompt === 'function'
         ? config.systemPrompt({ userId: input.userId, accountId: input.accountId, context: withoutClientUI(input.context) })
         : config.systemPrompt;
-    const systemPrompt = withClientKnowledge(hostPrompt, input.context);
-    log('debug', 'agent:prompt', 'System prompt built', { turnId, promptLength: systemPrompt.length });
+    // With a file area, the model is told a file's name and content are data, never instructions (ADR-0252 §2.11).
+    const systemPrompt = withClientKnowledge(fileArea ? `${hostPrompt}\n\n${ATTACHMENT_DATA_NOTE}` : hostPrompt, input.context);
+    log('debug', 'agent:prompt', 'System prompt built', { turnId, promptLength: systemPrompt.length, hostPromptLength: hostPrompt.length });
     // Wall-clock deadline: abort the entire streamText call if it exceeds turnDeadlineMs.
     const turnStartedAt = Date.now();
     // A UI tool waiting on work it started stops in time for the model to answer.
     const uiWaitDeadline = () => turnStartedAt + turnDeadlineMs - UI_ANSWER_MARGIN_MS;
     const abortController = new AbortController();
-    const deadlineTimer = setTimeout(() => abortController.abort('Turn deadline exceeded'), turnDeadlineMs);
+    // ─── Stopping (ADR-0252) ───────────────────────────────────────────────────
+    // The person's Stop, or a newer message superseding this turn, is kept by the
+    // realtime server; the watch asks for it for as long as the turn runs. A stop
+    // aborts the turn's signal with a typed reason, which is what everything that
+    // waits (the model stream, a UI action's answer, a job's outcome) already
+    // honours. What the turn had produced is then stored and announced (below).
+    const stopWatch = input.stopWatch ?? watchTurnStop(config.stops, turnId, input.userId);
+    /** Set when the turn begins its own end: a stop that lands after is not one (§2.4). */
+    let ending = false;
+    /** Kept back from a stopped turn's grace for storing and announcing it. */
+    const STOP_STORE_MARGIN_MS = 3_000;
+    /** Kept back from a stopped turn's store for announcing it. */
+    const STOP_ANNOUNCE_MARGIN_MS = 1_000;
+    /** The least any step of the stop path is given, however little is left. */
+    const STOP_STEP_FLOOR_MS = 250;
+    let stopGraceMs = config.stopGraceMs ?? DEFAULT_STOP_GRACE_MS;
+    // The stop path's own signal: the turn's is aborted by the time anything needs one.
+    let graceSignal = null;
+    const stopState = {
+        reason: () => stopOf(abortController.signal)?.reason ?? null,
+        graceSignal: () => (graceSignal ??= AbortSignal.timeout(stopGraceMs + 250)),
+        get graceMs() {
+            return stopGraceMs;
+        },
+    };
+    /** Abort the turn on its stop path: what it had produced is stored, then announced. */
+    const stopTurn = (stop) => {
+        if (ending || abortController.signal.aborted)
+            return;
+        // Never longer than this process has left, less what storing and announcing take.
+        const remaining = input.remainingMs?.();
+        if (remaining !== undefined)
+            stopGraceMs = Math.max(0, Math.min(stopGraceMs, remaining - STOP_STORE_MARGIN_MS));
+        graceSignal = AbortSignal.timeout(stopGraceMs + 250);
+        log('info', 'agent:turn', stop.reason === 'deadline' ? 'Turn ran out of time' : 'Turn asked to stop', {
+            turnId,
+            reason: stop.reason,
+            graceMs: stopGraceMs,
+        });
+        abortController.abort(stop);
+    };
+    stopWatch.onStop((record) => stopTurn(new TurnStopped(record.reason, record.at)));
+    // The turn's deadline ends it on the same path (ADR-0252 §6.4): what it did
+    // before it ran out of time is kept, marked, and the next turn is told.
+    const deadlineTimer = setTimeout(() => stopTurn(new TurnStopped('deadline', Date.now())), turnDeadlineMs);
     // Build tool execution context
     const toolCtx = {
         userId: input.userId,
@@ -163,18 +245,44 @@ export async function runAgentTurn(config, input) {
         apiSurface: config.apiSurface,
         abortSignal: abortController.signal,
         socketRoom,
+        stop: stopState,
     };
     // Track tool executions for emit events and persistence.
     // We capture toolCallId from the execute options (2nd argument).
     const executedToolResults = [];
     // The pictures results came with, by call: given to the model with that call's result (ui/answer-image.ts).
     const answerImages = new Map();
+    // The text results came with (a file's text, read by attachment_read), by call: the model's only, like the pictures.
+    const answerTexts = new Map();
+    // The worker's own record of the turn, kept as it runs: what a stopped turn
+    // is stored from (stop/partial.ts). The model stream's own results do not
+    // survive an abort, so nothing on the stop path reads them.
+    const recordedSteps = [];
+    const recordedCalls = new Map();
+    let streamedText = '';
+    /** Records a call as it arrives, and its result when it settles. */
+    const tracked = (toolCallId, toolName, callInput, run) => {
+        const call = { toolCallId, toolName, input: callInput, text: null, settled: Promise.resolve() };
+        recordedCalls.set(toolCallId, call);
+        const result = run().then((text) => {
+            call.text = text;
+            return text;
+        });
+        call.settled = result.then(() => undefined, () => undefined);
+        return result;
+    };
     // Per-tool invocation quotas — mandatory for side-effecting tools.
     // Quota is per-turn, held in this closure — never module scope. It spans
     // segments: rebuilding the tool set does not reset what was already used.
     const toolInvocationCounts = new Map();
-    const DEFAULT_TOOL_QUOTA = 12; // matches maxRounds
+    const DEFAULT_TOOL_QUOTA = 12;
     const SIDE_EFFECT_TOOL_QUOTA = 2;
+    // A UI action is not counted (session 24611234: filling 12 slides of 3 values each
+    // ran one action 36 times, and a cap of 12 stopped it). What is refused is a loop:
+    // the same call with the same input, made again after it changed nothing three
+    // times in a row. Undo five times, or nudge a layer five times, is work: each changes the page.
+    const UNCHANGED_REPEATS = 3;
+    const uiRepeats = new Map();
     // What each call of the turn did: said back to the model before every step
     // after one did not succeed, so its reply matches it (ADR-0244 §2.5).
     const ledger = createTurnLedger();
@@ -206,6 +314,9 @@ export async function runAgentTurn(config, input) {
     const executeCall = async (t, rawArgs, toolUseId, uiSlot, approved) => {
         const startMs = Date.now();
         const isUI = t.kind === 'ui';
+        // A stopped turn starts nothing more.
+        if (stopState.reason())
+            return { text: resultText(stoppedNotRun(t.name)), ran: false };
         /**
          * A call refused before its tool ran: invalid input, over its quota, or
          * denied by policy. The model gets the reason; so does the client, as a
@@ -234,9 +345,10 @@ export async function runAgentTurn(config, input) {
             return notRun({ success: false, ...payload });
         };
         // A UI tool waits for the client's answer, which has its own deadline, and
-        // then for the outcome of work it started, until uiWaitDeadline.
+        // then for the outcome of work it started: for uiJobWaitMs at most, and
+        // never past uiWaitDeadline.
         const timeoutMs = isUI
-            ? Math.max(toolTimeoutMs, uiResultTimeoutMs + 5_000, uiWaitDeadline() - Date.now() + uiResultTimeoutMs + 5_000)
+            ? Math.max(toolTimeoutMs, uiResultTimeoutMs + 5_000, Math.min(uiJobWaitMs, Math.max(0, uiWaitDeadline() - Date.now())) + uiResultTimeoutMs + 5_000)
             : toolTimeoutMs;
         // ── No changes while blind (ADR-0245 §2.5) ──
         // After an answer that came without the page's state, or no answer, only
@@ -289,23 +401,107 @@ export async function runAgentTurn(config, input) {
             }, rawArgs);
         }
         const args = validation.value;
+        // ── Attached files named in the call (ADR-0252 §2.13) ──
+        // Each must be a file of this turn's conversation, ready, and of a type the
+        // input takes, checked before anything is dispatched; the page then
+        // resolves it through its own host. An action declaring a file where none
+        // can be checked is not run at all.
+        const misplaced = misplacedAttachmentInputs(schema);
+        if (misplaced.length > 0) {
+            return refused({
+                error: `"${t.name}" declares an attached file at ${misplaced.join(', ')}, where none can be checked: it cannot be run with a file.`,
+                notRun: true,
+            }, args);
+        }
+        const namedFiles = attachmentIdsIn(schema, args);
+        const callFiles = new Map();
+        if (namedFiles.length > 0) {
+            if (!fileArea) {
+                return refused({ error: `"${t.name}" takes an attached file, and this assistant cannot use attached files.`, notRun: true }, args);
+            }
+            const ids = [...new Set(namedFiles.map((f) => f.id))];
+            try {
+                for (const ref of await fileArea.store.describe(ids, fileOwner, { signal: abortController.signal }))
+                    callFiles.set(ref.id, ref);
+            }
+            catch (err) {
+                log('warn', 'agent:tool', 'Could not check the files a call names; it was not run', {
+                    turnId,
+                    toolName: t.name,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return refused({ error: `The files "${t.name}" names could not be checked just now. It was not run; try again.`, notRun: true }, args);
+            }
+            const missing = ids.filter((id) => !callFiles.has(id) || callFiles.get(id).removed);
+            if (missing.length > 0) {
+                return refused({
+                    error: `${missing.map((id) => `"${id}"`).join(', ')} ${missing.length === 1 ? 'is not a file' : 'are not files'} of this conversation that can be used. ${ATTACHMENT_LIST_HINT}`,
+                    notRun: true,
+                }, args);
+            }
+            const pending = ids.filter((id) => callFiles.get(id).pending);
+            if (pending.length > 0) {
+                return refused({
+                    error: `${pending.map((id) => `"${id}"`).join(', ')} ${pending.length === 1 ? 'is' : 'are'} still being checked, and can be used once that is done. It was not run.`,
+                    notRun: true,
+                }, args);
+            }
+            // The type each input takes, checked here as the page checks it (OUI spec §7.3.11).
+            const wrongType = namedFiles.filter((f) => !acceptsMediaType(f.input, callFiles.get(f.id).mediaType));
+            if (wrongType.length > 0) {
+                return refused({
+                    error: wrongType
+                        .map((f) => {
+                        const ref = callFiles.get(f.id);
+                        return `${f.property}: ${attachmentNameForModel(ref.name)} (${f.id}) is ${ref.mediaType}; it takes ${f.input.mediaTypes.join(', ')}.`;
+                    })
+                        .join(' '),
+                    notRun: true,
+                }, args);
+            }
+        }
         // Told to the model with the result, so it sends the value itself next time (below).
         const readFromText = validation.coerced ?? [];
+        // The call as a repeat is judged by: its name and its exact input. Set for a UI action that changes the page.
+        let repeatKey = null;
         // ── Quota enforcement ──
         // UI actions run as the user in their own session (ADR-0182 §3), so the
-        // backend side-effect cap does not apply to them (ADR-0209 D5).
+        // backend side-effect cap does not apply to them (ADR-0209 D5). They are
+        // bounded by the turn's steps and deadline; only a repeated identical call is refused.
         const currentCount = toolInvocationCounts.get(t.name) ?? 0;
         const isSideEffecting = schema.sideEffects !== false; // fail-closed: undefined = side-effecting
-        // A UI action that only reads (a room's inspect and query, ADR-0244 §2.2)
-        // changes nothing however often it is called: the turn's step limit bounds it.
-        const quota = reads ? Infinity : !isUI && isSideEffecting ? SIDE_EFFECT_TOOL_QUOTA : DEFAULT_TOOL_QUOTA;
-        if (currentCount >= quota) {
-            return refused({
-                error: `Tool "${t.name}" has reached its maximum invocation quota of ${quota} for this turn. Please proceed without calling it again.`,
-                quotaExceeded: true,
-            }, args);
+        if (isUI) {
+            // A UI action that only reads (a room's inspect and query, ADR-0244 §2.2)
+            // changes nothing however often it is called.
+            if (!reads) {
+                let input;
+                try {
+                    input = canonicalJson(args);
+                }
+                catch {
+                    input = JSON.stringify(args);
+                }
+                repeatKey = `${t.name} ${input}`;
+                const unchanged = uiRepeats.get(repeatKey)?.unchanged ?? 0;
+                if (unchanged >= UNCHANGED_REPEATS) {
+                    return refused({
+                        error: `"${t.name}" with exactly this input has changed nothing the last ${unchanged} times it ran in this turn. ` +
+                            'Running it again would change nothing again: read the page for why, then change the input or stop.',
+                        repeatedCall: true,
+                    }, args);
+                }
+            }
+        }
+        else {
+            const quota = isSideEffecting ? SIDE_EFFECT_TOOL_QUOTA : DEFAULT_TOOL_QUOTA;
+            if (currentCount >= quota) {
+                return refused({
+                    error: `Tool "${t.name}" has reached its maximum invocation quota of ${quota} for this turn. Please proceed without calling it again.`,
+                    quotaExceeded: true,
+                }, args);
+            }
+            toolInvocationCounts.set(t.name, currentCount + 1);
         }
-        toolInvocationCounts.set(t.name, currentCount + 1);
         // ── Policy enforcement ──
         // A deny always wins, over an approval too (ADR-0228 §2.1).
         const requirement = approvalRequirement(t);
@@ -319,6 +515,7 @@ export async function runAgentTurn(config, input) {
                 turnId,
                 hasSideEffects: isSideEffecting,
                 toolKind: isUI ? 'ui' : 'backend',
+                ...(t.toolClass ? { toolClass: t.toolClass } : {}),
                 effect: requirement.effect,
                 destructive: requirement.destructive,
             });
@@ -338,12 +535,15 @@ export async function runAgentTurn(config, input) {
         }
         if ((requirement.required || policyRequiresApproval) && !approved) {
             ledger.record({ tool: t.name, ok: false, error: 'Not run: it waits for the user’s approval on the card' });
-            return { text: await requestApproval(t, args, toolUseId, requirement), ran: false };
+            return { text: await requestApproval(t, args, toolUseId, requirement, callFiles), ran: false };
         }
         if (t.name === UI_DESCRIBE_TOOL)
             uiCounts.describes++;
         else if (t.name === UI_READ_TOOL)
             uiCounts.reads++;
+        // It reads what the client sent, and touches no page.
+        else if (t.name === KNOWLEDGE_TOOL)
+            uiCounts.guides++;
         else if (isUI)
             uiCounts.acts++;
         log('info', 'agent:tool', 'Tool call started', {
@@ -384,6 +584,11 @@ export async function runAgentTurn(config, input) {
             if (timer)
                 clearTimeout(timer);
         }
+        // A host tool that the stop cut short failed with whatever its abort threw:
+        // its result says what happened instead. (A UI tool says so itself.)
+        if (!isUI && stopState.reason() && result && typeof result === 'object' && 'success' in result && !result.success) {
+            result = stoppedWhileRunning(t.name);
+        }
         const durationMs = Date.now() - startMs;
         // Normalize result — built-in tools (present_options, etc.) return the
         // raw payload directly, while schema and UI tools return { success, data, error }.
@@ -423,10 +628,25 @@ export async function runAgentTurn(config, input) {
             ok: resultSuccess,
             ...(resultSuccess ? {} : { error: isWrapped && result.error ? result.error : 'it did not succeed' }),
         });
+        // Did this run change the page? Not when it failed, when the page says it changed no row,
+        // or when the page's state is what it was after the same call last ran.
+        if (repeatKey) {
+            const answer = (modelPayload ?? {});
+            const state = answer.state === undefined ? null : JSON.stringify(answer.state);
+            const changed = answer.result?.changed;
+            const held = uiRepeats.get(repeatKey);
+            const noChange = !resultSuccess ||
+                changed === false ||
+                (Array.isArray(changed) && changed.length === 0) ||
+                (state !== null && held?.lastState === state);
+            uiRepeats.set(repeatKey, { unchanged: noChange ? (held?.unchanged ?? 0) + 1 : 0, lastState: state });
+        }
         // A picture in the result is the model's to look at with this call's
         // result, and nothing else's: it is not in the text above, the event or the record.
         if (isWrapped && result.image)
             answerImages.set(toolUseId, result.image);
+        if (isWrapped && typeof result.modelText === 'string')
+            answerTexts.set(toolUseId, result.modelText);
         return { text: JSON.stringify(modelPayload ?? { error: 'no result' }), ran: true };
     };
     /**
@@ -436,13 +656,15 @@ export async function runAgentTurn(config, input) {
     const toModelOutput = ({ toolCallId, output }) => {
         const text = typeof output === 'string' ? output : JSON.stringify(output ?? null);
         const image = answerImages.get(toolCallId);
-        if (!image)
+        const fileText = answerTexts.get(toolCallId);
+        if (!image && fileText === undefined)
             return { type: 'text', value: text };
         return {
             type: 'content',
             value: [
                 { type: 'text', text },
-                { type: 'file', mediaType: image.mediaType, data: { type: 'data', data: image.base64 } },
+                ...(fileText !== undefined ? [{ type: 'text', text: fileText }] : []),
+                ...(image ? [{ type: 'file', mediaType: image.mediaType, data: { type: 'data', data: image.base64 } }] : []),
             ],
         };
     };
@@ -451,8 +673,9 @@ export async function runAgentTurn(config, input) {
      * stores it as a pending approval, shows the card, and tells the model only
      * that it is waiting. The model never sees a token.
      */
-    const requestApproval = async (t, args, toolUseId, requirement) => {
-        const preview = buildApprovalPreview(t, args);
+    const requestApproval = async (t, args, toolUseId, requirement, files) => {
+        // A file is shown by its name and size; the approval stays bound to its id (ADR-0252 §2.13).
+        const preview = buildApprovalPreview(t, args, files);
         approvalHold = { approvalId: toolUseId, title: preview.title };
         const refuse = (why) => {
             approvalHold = null;
@@ -526,12 +749,14 @@ export async function runAgentTurn(config, input) {
         // one response may get through them in any order (ui-sequence.ts). The place
         // is given up if the call never reaches the page, and otherwise held until
         // its action settles.
-        const execute = async (rawArgs, options) => {
+        const execute = (rawArgs, options) => {
             const toolUseId = options?.toolCallId ?? `tool_${Date.now()}`;
             const uiSlot = isUI ? uiSequence.reserve() : undefined;
-            const { text } = await executeCall(t, rawArgs, toolUseId, uiSlot).finally(() => uiSlot?.release());
-            executedToolResults.push({ toolCallId: toolUseId, toolName: t.name, result: text });
-            return text;
+            return tracked(toolUseId, t.name, rawArgs, async () => {
+                const { text } = await executeCall(t, rawArgs, toolUseId, uiSlot).finally(() => uiSlot?.release());
+                executedToolResults.push({ toolCallId: toolUseId, toolName: t.name, result: text });
+                return text;
+            });
         };
         // A call that needs approval says so in its description, in place of any
         // "confirm first" instruction: the card is the confirmation.
@@ -555,6 +780,7 @@ export async function runAgentTurn(config, input) {
             resultTimeoutMs: uiResultTimeoutMs,
             maxObservationChars: config.ui.maxObservationChars,
             waitDeadline: uiWaitDeadline,
+            jobWaitMs: uiJobWaitMs,
             currentPage: () => currentPage,
             sequence: uiSequence,
             held: heldDefinitions,
@@ -591,9 +817,10 @@ export async function runAgentTurn(config, input) {
     // with the id of an action of the page, is withheld (ADR-0209 D6): for a
     // UI-only agent, the page is the authority.
     function hostTools(ui) {
+        const sdkOwned = new Set(fileTools.map((t) => t.name));
         if (!ui)
-            return config.tools.tools;
-        const taken = (name) => ui.actions.has(name) || name === UI_ACT_TOOL || name === UI_DESCRIBE_TOOL || name === UI_READ_TOOL;
+            return [...config.tools.tools.filter((t) => !sdkOwned.has(t.name)), ...fileTools];
+        const taken = (name) => sdkOwned.has(name) || ui.actions.has(name) || name === UI_ACT_TOOL || name === UI_DESCRIBE_TOOL || name === UI_READ_TOOL;
         const withheld = config.tools.tools.filter((t) => taken(t.name)).map((t) => t.name);
         if (withheld.length > 0) {
             log('error', 'agent:ui', 'Host tools collide with UI tools or action ids; the host tools are withheld this turn', {
@@ -601,7 +828,7 @@ export async function runAgentTurn(config, input) {
                 withheld,
             });
         }
-        return config.tools.tools.filter((t) => !taken(t.name));
+        return [...config.tools.tools.filter((t) => !taken(t.name)), ...fileTools];
     }
     /** Every tool a call can name: the host's, and the page's actions. What an approved call is looked up in. */
     function callableTools() {
@@ -631,42 +858,55 @@ export async function runAgentTurn(config, input) {
                 required: ['action'],
                 additionalProperties: false,
             }),
-            execute: async (rawArgs, options) => {
+            execute: (rawArgs, options) => {
                 const toolUseId = options?.toolCallId ?? `tool_${Date.now()}`;
-                const { action, input: actionInput } = (rawArgs ?? {});
-                // Taken as the call arrives, like any UI call (ui-sequence.ts), and
-                // given up if it never reaches the page.
-                const uiSlot = uiSequence.reserve();
-                const notAnAction = (error) => {
-                    uiSlot.release();
-                    ledger.record({ tool: typeof action === 'string' && action ? action : UI_ACT_TOOL, ok: false, error });
-                    const text = JSON.stringify({ success: false, notRun: true, error });
-                    executedToolResults.push({ toolCallId: toolUseId, toolName: UI_ACT_TOOL, result: text });
-                    return text;
-                };
-                if (typeof action !== 'string' || !action)
-                    return notAnAction(`${UI_ACT_TOOL} needs "action": an action id from the page's index.`);
-                if (stepActions.forced && action !== stepActions.forced) {
-                    return notAnAction(`This step runs "${stepActions.forced}" and nothing else: call ${UI_ACT_TOOL} with that action.`);
-                }
-                if (stepActions.only && !stepActions.only.has(action)) {
-                    return notAnAction(`"${action}" is not available at this step.`);
-                }
-                // Looked up in the page as it is now: an earlier action of this response may have changed it.
-                const ui = currentUI();
-                const tool = ui?.actions.get(action);
-                if (!tool) {
-                    const ids = ui ? [...ui.actions.keys()] : [];
-                    const near = ids.filter((id) => id.includes(action) || action.includes(id)).slice(0, 8);
-                    return notAnAction(`"${action}" is not an action of the page as it is now.` +
-                        (near.length ? ` Did you mean: ${near.join(', ')}?` : ' Read the page’s index for what it offers; an action is named by its id there.'));
-                }
-                const { text } = await executeCall(tool, actionInput ?? {}, toolUseId, uiSlot).finally(() => uiSlot.release());
-                executedToolResults.push({ toolCallId: toolUseId, toolName: UI_ACT_TOOL, result: text });
-                return text;
+                return tracked(toolUseId, UI_ACT_TOOL, rawArgs, () => act(rawArgs, toolUseId));
             },
             toModelOutput,
         });
+        async function act(rawArgs, toolUseId) {
+            const { action, input: actionInput } = (rawArgs ?? {});
+            // Taken as the call arrives, like any UI call (ui-sequence.ts), and
+            // given up if it never reaches the page.
+            const uiSlot = uiSequence.reserve();
+            const notAnAction = (error) => {
+                uiSlot.release();
+                ledger.record({ tool: typeof action === 'string' && action ? action : UI_ACT_TOOL, ok: false, error });
+                const text = JSON.stringify({ success: false, notRun: true, error });
+                executedToolResults.push({ toolCallId: toolUseId, toolName: UI_ACT_TOOL, result: text });
+                return text;
+            };
+            if (typeof action !== 'string' || !action)
+                return notAnAction(`${UI_ACT_TOOL} needs "action": an action id from the page's index.`);
+            if (stepActions.forced && action !== stepActions.forced) {
+                return notAnAction(`This step runs "${stepActions.forced}" and nothing else: call ${UI_ACT_TOOL} with that action.`);
+            }
+            if (stepActions.only && !stepActions.only.has(action)) {
+                return notAnAction(`"${action}" is not available at this step.`);
+            }
+            // Looked up in the page as it is now: an earlier action of this response may have changed it.
+            const ui = currentUI();
+            const tool = ui?.actions.get(action);
+            if (!tool) {
+                const ids = ui ? [...ui.actions.keys()] : [];
+                const near = ids.filter((id) => id.includes(action) || action.includes(id)).slice(0, 8);
+                return notAnAction(`"${action}" is not an action of the page as it is now.` +
+                    (near.length ? ` Did you mean: ${near.join(', ')}?` : ' Read the page’s index for what it offers; an action is named by its id there.'));
+            }
+            const { text } = await executeCall(tool, actionInput ?? {}, toolUseId, uiSlot).finally(() => uiSlot.release());
+            executedToolResults.push({ toolCallId: toolUseId, toolName: UI_ACT_TOOL, result: text });
+            return text;
+        }
+    }
+    /** A tool the model is given, as a turn policy sees it: its name, kind and class. */
+    function describeStepTool(name) {
+        if (name === UI_ACT_TOOL || name === UI_DESCRIBE_TOOL || name === UI_READ_TOOL)
+            return { name, kind: 'ui' };
+        // The SDK's own file tools take their names before the host's (hostTools).
+        const registered = fileTools.find((t) => t.name === name) ?? config.tools.tools.find((t) => t.name === name);
+        if (!registered)
+            return { name, kind: 'builtin' };
+        return { name, kind: registered.kind === 'ui' ? 'ui' : 'backend', ...(registered.toolClass ? { toolClass: registered.toolClass } : {}) };
     }
     function assembleTools() {
         const ui = currentUI();
@@ -678,6 +918,9 @@ export async function runAgentTurn(config, input) {
             tools[UI_DESCRIBE_TOOL] = toAiTool(ui.describe);
             tools[UI_READ_TOOL] = toAiTool(ui.read);
         }
+        // What the prompt leaves out of the client's knowledge, read when it is needed.
+        if (knowledge && !tools[KNOWLEDGE_TOOL])
+            tools[KNOWLEDGE_TOOL] = toAiTool(knowledgeTool(knowledge));
         return tools;
     }
     /**
@@ -830,6 +1073,13 @@ export async function runAgentTurn(config, input) {
         // only when the page changes. `cacheReadTokens` in the usage below is how you
         // tell caching is still working.
         const cachePoint = config.promptCacheBreakpoint;
+        // A stop asked for while the turn waited to start (in a queue, or for the
+        // turns before it to be stored) is heard first: nothing runs, and the turn
+        // stores only that it was stopped.
+        await stopWatch.checked();
+        const stoppedBeforeStart = stopOf(abortController.signal);
+        if (stoppedBeforeStart)
+            return await finishStopped(stoppedBeforeStart, { expired: null, continued: null });
         // ─── The turn after an approval decision (ADR-0228 §2.2.5) ────────────────
         const continued = input.approval ? await continueApproval(input.approval) : null;
         // ─── Calls still stored as waiting, whose approval expired undecided ──────
@@ -846,7 +1096,7 @@ export async function runAgentTurn(config, input) {
         /** Calls beyond the newest few are left: a store call per waiting call, on every turn, has to stay small. */
         const MAX_WAITING_SETTLED = 5;
         async function settleExpiredWaiting() {
-            const settled = { outcomes: [], persisted: [], claimed: [], undecided: 0, approved: 0 };
+            const settled = { outcomes: [], persisted: [], claimed: [], undecided: 0, approved: 0, withdrawn: 0 };
             const store = config.approvals;
             if (!store?.settleExpired)
                 return settled;
@@ -870,8 +1120,15 @@ export async function runAgentTurn(config, input) {
                     continue;
                 // The user had approved it and it was never run, or nobody decided: the result says which.
                 const wasApproved = answer.decided === 'approved';
-                const content = notRunResult(wasApproved ? approvedExpiredMarker() : approvalMarker('expired', false));
-                if (wasApproved)
+                // Withdrawn (a new message, or its turn stopped) is said as that, not as time running out (ADR-0252 §2.6).
+                const content = notRunResult(answer.withdrawn
+                    ? withdrawnMarker(answer.withdrawn, wasApproved)
+                    : wasApproved
+                        ? approvedExpiredMarker()
+                        : approvalMarker('expired', false));
+                if (answer.withdrawn)
+                    settled.withdrawn += 1;
+                else if (wasApproved)
                     settled.approved += 1;
                 else
                     settled.undecided += 1;
@@ -885,12 +1142,17 @@ export async function runAgentTurn(config, input) {
                     turnId,
                     approvalId: w.approvalId,
                     decided: wasApproved ? 'approved' : null,
+                    ...(answer.withdrawn ? { withdrawn: answer.withdrawn } : {}),
                     stored: answer.outcome === 'claimed',
                 });
             }
             return settled;
         }
         const expired = await settleExpiredWaiting();
+        // Stopped while the approved call ran, or while the store was asked: the model is not called.
+        const stoppedBeforeModel = stopOf(abortController.signal);
+        if (stoppedBeforeModel)
+            return await finishStopped(stoppedBeforeModel, { expired, continued });
         // Convert history to AI SDK CoreMessage format. The page the user is on
         // travels with their message, not in the system prompt: it changes on every
         // page, and in the system prompt it would invalidate the cached prefix. An
@@ -899,15 +1161,48 @@ export async function runAgentTurn(config, input) {
         // The date and time on the user's clock travel with their message too: a
         // model has no clock, and the changing minute must stay out of the cached
         // system prompt (prompt/clock.ts).
+        const turnFilesGiven = !!fileArea && (input.attachments?.length ?? 0) > 0;
         const messages = [
             ...withClock(withPageState(withNote(convertHistoryToCoreMessages(
             // An approved call's outcome, and an expired one's, is a later result of the call already in the
             // history: it takes that call's place.
-            [...(input.history ?? []), ...expired.outcomes, ...(continued?.outcome ? [continued.outcome] : [])], [input.content, continued?.note].filter(Boolean).join('\n\n')), 
+            [...(input.history ?? []), ...expired.outcomes, ...(continued?.outcome ? [continued.outcome] : [])], [input.content, continued?.note].filter(Boolean).join('\n\n'), 
+            // The turn's own message, when the history already holds it: its files are given below,
+            // each with its line, so the history's copy of the message does not name them again.
+            turnFilesGiven && input.history?.at(-1)?.role === 'user' ? input.history.length - 1 : null), 
             // Said on the user's message whether or not the host's history already holds that message.
             expired.outcomes.length > 0 ? expiredNote(expired) : null), client, config.ui?.maxObservationChars ?? DEFAULT_PAGE_STATE_CHARS, config.ui?.maxIndexChars ?? DEFAULT_INDEX_CHARS), input.context ?? null),
             ...(continued?.messages ?? []),
         ];
+        // The turn's files go with its message, after everything said about it (ADR-0252 §2.11).
+        // A file that cannot be had is named with why; the turn goes on with the others.
+        if (fileArea && turnFilesGiven) {
+            try {
+                const files = await turnAttachmentParts(input.attachments, {
+                    store: fileArea.store,
+                    owner: fileOwner,
+                    guard: fileGuard,
+                    pdfAsDocument: fileArea.pdfAsDocument ?? false,
+                    perMessage: fileArea.perMessage,
+                    signal: abortController.signal,
+                });
+                if (files.failures.length > 0) {
+                    log('warn', 'agent:tool', 'Some of the message’s files could not be loaded; the turn goes on without them', { turnId, failures: files.failures });
+                }
+                messages.splice(0, messages.length, ...withTurnAttachments(messages, files));
+            }
+            catch (err) {
+                log('error', 'agent:tool', 'The message’s files could not be given; the turn goes on with their lines', {
+                    turnId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                messages.splice(0, messages.length, ...withTurnAttachments(messages, {
+                    parts: [],
+                    notes: [withReferenceLines('', input.attachments), 'These files could not be loaded with this message.'],
+                    failures: [],
+                }));
+            }
+        }
         // The system prompt goes in `instructions`, NOT in `messages`.
         //
         // ai v7 rejects a system-role entry in `messages` outright —
@@ -964,7 +1259,7 @@ export async function runAgentTurn(config, input) {
                     isEnabled: true,
                     functionId: `agent-turn:${turnId}`,
                 },
-                prepareStep: async ({ steps }) => {
+                prepareStep: async ({ steps, messages }) => {
                     // The policy speaks of the page's actions by their ids, as it always
                     // has: a `ui_act` call is shown to it as the action it ran, and the
                     // actions are among the tool names it may choose from.
@@ -980,6 +1275,11 @@ export async function runAgentTurn(config, input) {
                         })),
                         turnClass,
                         allToolNames: [...Object.keys(aiTools), ...actionIds],
+                        // What each tool is, so a policy can choose by class (the attachment tools are `attachment`).
+                        allTools: [
+                            ...Object.keys(aiTools).map((name) => describeStepTool(name)),
+                            ...actionIds.map((name) => ({ name, kind: 'ui' })),
+                        ],
                     });
                     // What it constrained, in the model's terms: an action is run through
                     // `ui_act`, which holds the step to the actions the policy allowed.
@@ -1006,14 +1306,37 @@ export async function runAgentTurn(config, input) {
                     // without a note sets the plain instructions back.
                     // So does the turn's record, once a call has not succeeded.
                     const notes = [note, forced ? `This step: call ${UI_ACT_TOOL} with action "${forced}".` : null, ledger.note()].filter((n) => !!n);
+                    // The page's state on the newest answer only: an earlier page is not the page now.
+                    const trimmed = messages ? withNewestPageStateOnly(messages) : null;
+                    if (trimmed)
+                        pageStatesNotRepeated += trimmed.replaced;
+                    // The files this step would carry, within the turn's and the conversation's caps (ADR-0252 §2.11).
+                    const leftOutNow = fileGuard.beforeStep();
+                    if (leftOutNow.length > 0) {
+                        log('info', 'agent:tool', 'Files left out of the next step to keep within the cap', {
+                            turnId,
+                            attachments: leftOutNow.map((p) => ({ id: p.attachmentId, kind: p.kind, estimatedTokens: p.tokens })),
+                        });
+                    }
+                    const leftOut = fileGuard.leftOutParts();
+                    const stepMessages = leftOut.length > 0 && messages ? withoutLeftOut(trimmed?.messages ?? messages, leftOut) : trimmed?.messages;
                     return {
                         ...constraints,
+                        ...(stepMessages ? { messages: stepMessages } : {}),
                         instructions: notes.length
                             ? [instructions, ...notes.map((content) => ({ role: 'system', content }))]
                             : instructions,
                     };
                 },
-                onStepEnd: async ({ text, toolCalls }) => {
+                onStepEnd: async ({ text, toolCalls, usage: stepUsage }) => {
+                    recordedSteps.push({
+                        text: text ?? '',
+                        toolCalls: (toolCalls ?? []).map((tc) => ({ toolCallId: tc.toolCallId, toolName: tc.toolName, input: tc.input })),
+                        inputTokens: stepUsage?.inputTokens ?? 0,
+                        outputTokens: stepUsage?.outputTokens ?? 0,
+                        cacheReadTokens: stepUsage?.inputTokenDetails?.cacheReadTokens ?? 0,
+                        cacheWriteTokens: stepUsage?.inputTokenDetails?.cacheWriteTokens ?? 0,
+                    });
                     log('info', 'agent:llm', 'Step completed', {
                         turnId,
                         turnClass,
@@ -1024,31 +1347,53 @@ export async function runAgentTurn(config, input) {
                     });
                 },
             });
-            for await (const textPart of result.textStream) {
-                tokenBuffer += textPart;
-                if (tokenBuffer.length >= COALESCE_CHARS) {
-                    await flushTokenBuffer();
-                }
-                else if (!flushTimer) {
-                    flushTimer = setTimeout(() => flushTokenBuffer(), COALESCE_MS);
+            // A stop aborts the stream. However that surfaces, as a throw here or as the
+            // stream simply ending, the turn then goes to its stop path, which reads
+            // none of the stream's own results: they reject on an abort.
+            try {
+                for await (const textPart of result.textStream) {
+                    streamedText += textPart;
+                    tokenBuffer += textPart;
+                    if (tokenBuffer.length >= COALESCE_CHARS) {
+                        await flushTokenBuffer();
+                    }
+                    else if (!flushTimer) {
+                        flushTimer = setTimeout(() => flushTokenBuffer(), COALESCE_MS);
+                    }
                 }
+                await flushTokenBuffer();
+                if (stopOf(abortController.signal))
+                    break;
+                // After the text stream completes, all promised properties resolve.
+                const steps = await result.steps;
+                const segmentUsage = await result.usage;
+                const response = await result.response;
+                allSteps.push(...steps);
+                usageTotals.inputTokens += segmentUsage?.inputTokens ?? 0;
+                usageTotals.outputTokens += segmentUsage?.outputTokens ?? 0;
+                usageTotals.cacheReadTokens += segmentUsage?.inputTokenDetails?.cacheReadTokens ?? 0;
+                usageTotals.cacheWriteTokens += segmentUsage?.inputTokenDetails?.cacheWriteTokens ?? 0;
+                responseMessageCount += response.messages.length;
+                conversation = [...conversation, ...response.messages];
+            }
+            catch (err) {
+                if (!stopOf(abortController.signal))
+                    throw err;
             }
-            await flushTokenBuffer();
-            // After the text stream completes, all promised properties resolve.
-            const steps = await result.steps;
-            const segmentUsage = await result.usage;
-            const response = await result.response;
-            allSteps.push(...steps);
-            usageTotals.inputTokens += segmentUsage?.inputTokens ?? 0;
-            usageTotals.outputTokens += segmentUsage?.outputTokens ?? 0;
-            usageTotals.cacheReadTokens += segmentUsage?.inputTokenDetails?.cacheReadTokens ?? 0;
-            usageTotals.cacheWriteTokens += segmentUsage?.inputTokenDetails?.cacheWriteTokens ?? 0;
-            responseMessageCount += response.messages.length;
-            conversation = [...conversation, ...response.messages];
             // The model's tools no longer change with the page (ADR-0245 §2.2): what
             // the page offers reaches it in each answer, so the turn runs as one segment.
             break;
         }
+        // ─── Stopped, or ending ────────────────────────────────────────────────────
+        // Decided here with nothing awaited in between: either the stop was heard
+        // before this point and the turn takes its stop path, or the turn has begun
+        // its own end and a stop that lands from now on is not one. Its watch is
+        // closed, so it cannot abort the store or cause a second announcement.
+        const stop = stopOf(abortController.signal);
+        if (stop)
+            return await finishStopped(stop, { expired, continued });
+        ending = true;
+        stopWatch.close();
         // ─── Finalize ──────────────────────────────────────────────────────────────
         const steps = allSteps;
         // Determine stop reason
@@ -1107,10 +1452,12 @@ export async function runAgentTurn(config, input) {
                         // What bounds the model: the page's index as it reads it, against the most it is given
                         // before the furthest surfaces are listed by id only.
                         indexChars: indexText(client.page, Infinity).length,
+                        pageStatesNotRepeated,
                         maxIndexChars: config.ui?.maxIndexChars ?? DEFAULT_INDEX_CHARS,
                     },
                 }
                 : {}),
+            ...(fileArea ? { attachments: fileGuard.usage() } : {}),
         });
         // The turn's messages, in the host's format, for it to store.
         const newMessages = [...expired.persisted, ...(continued?.persisted ?? []), ...convertResponseToTurnMessages({ steps }, executedToolResults)];
@@ -1149,12 +1496,172 @@ export async function runAgentTurn(config, input) {
             ...(expired.claimed.length > 0 ? { settledApprovals: expired.claimed } : {}),
             maxRoundsReached: steps.length >= maxRounds,
             stopReason,
+            ...(fileArea ? { attachments: fileGuard.usage() } : {}),
         };
     }
     finally {
         clearTimeout(deadlineTimer);
         if (flushTimer)
             clearTimeout(flushTimer);
+        // The turn is over, however it ended: nothing is listening for a stop.
+        ending = true;
+        stopWatch.close();
+    }
+    /**
+     * The end of a stopped turn (ADR-0252 §2.4): settle what was in flight, store
+     * what the turn had produced, then say so. Persist first, announce after, as
+     * a turn that ends by itself does.
+     *
+     * Everything here happens after the turn's signal was aborted, so nothing
+     * here is given that signal. The wait for calls in flight is bounded by the
+     * grace; the store and the announcement are bounded by what the process has
+     * left, when the host says (`remainingMs`). Without that, they take as long
+     * as the host's store and the emit adapter's own timeout take.
+     */
+    async function finishStopped(stopped, earlier) {
+        ending = true;
+        stopWatch.close();
+        // Text the turn produced and had not sent yet is still the person's to see.
+        await flushTokenBuffer().catch(() => undefined);
+        // A call that was out when the stop came takes one last look for its answer
+        // (the UI tools do, on the stop's own signal). They are waited for, a little
+        // past that grace, and no longer.
+        const pending = [...recordedCalls.values()].filter((call) => call.text === null);
+        if (pending.length > 0) {
+            let timer;
+            await Promise.race([
+                Promise.all(pending.map((call) => call.settled)),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, stopGraceMs + 500);
+                }),
+            ]);
+            if (timer)
+                clearTimeout(timer);
+        }
+        // A stopped turn leaves no live card: an approval it asked for as the stop came
+        // is withdrawn now, and a later turn records it as that (§2.6).
+        const held = approvalHold;
+        if (held && config.approvals?.withdraw) {
+            try {
+                await config.approvals.withdraw(held.approvalId, { userId: input.userId, conversationId: input.conversationId }, 'stopped');
+            }
+            catch (err) {
+                log('warn', 'agent:tool', 'Could not withdraw the stopped turn’s approval; it lasts until its time limit', {
+                    turnId,
+                    approvalId: held.approvalId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        const marker = { reason: stopped.reason, at: stopped.at };
+        const newMessages = [
+            ...(earlier.expired?.persisted ?? []),
+            ...(earlier.continued?.persisted ?? []),
+            ...stoppedTurnMessages({ steps: recordedSteps, calls: [...recordedCalls.values()], streamedText, marker }),
+        ];
+        const unsettled = [...recordedCalls.values()].filter((call) => call.text === null).map((call) => call.toolName);
+        // The steps that ended reported their tokens; the step the stop cut short did not.
+        const stepInputTokens = recordedSteps.map((step) => step.inputTokens);
+        const promptTokens = stepInputTokens.reduce((sum, n) => sum + n, 0);
+        const completionTokens = recordedSteps.reduce((sum, step) => sum + step.outputTokens, 0);
+        const usage = {
+            promptTokens,
+            completionTokens,
+            totalTokens: promptTokens + completionTokens,
+            peakPromptTokens: stepInputTokens.length > 0 ? Math.max(...stepInputTokens) : 0,
+            cacheReadTokens: recordedSteps.reduce((sum, step) => sum + step.cacheReadTokens, 0),
+            cacheWriteTokens: recordedSteps.reduce((sum, step) => sum + step.cacheWriteTokens, 0),
+        };
+        const rounds = recordedSteps.length;
+        log('info', 'agent:llm', 'Turn usage', {
+            turnId,
+            rounds,
+            stopped: true,
+            stopReason: stopped.reason,
+            peakPromptTokens: usage.peakPromptTokens,
+            promptTokens: usage.promptTokens,
+            cacheReadTokens: usage.cacheReadTokens,
+            cacheWriteTokens: usage.cacheWriteTokens,
+            ...(unsettled.length > 0 ? { unsettledCalls: unsettled } : {}),
+            ...(client ? { ui: { ...uiCounts, blindRefusals: sight.refusals(), stopped: sight.stopped() } } : {}),
+            ...(fileArea ? { attachments: fileGuard.usage() } : {}),
+        });
+        // The store and the announcement each get a limit of their own when the host says how long
+        // the process has left: a slow store must not run it to its hard end with nothing announced.
+        /** Whether the work finished within its limit. */
+        const within = async (what, keepBackMs, work) => {
+            const remaining = input.remainingMs?.();
+            if (remaining === undefined) {
+                await work();
+                return true;
+            }
+            const limitMs = Math.max(STOP_STEP_FLOOR_MS, remaining - keepBackMs);
+            let timer;
+            const timedOut = Symbol('timed out');
+            const outcome = await Promise.race([
+                work(),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(timedOut), limitMs);
+                }),
+            ]);
+            if (timer)
+                clearTimeout(timer);
+            if (outcome === timedOut) {
+                log('error', 'agent:turn', `The stopped turn's ${what} did not finish within its limit; the turn goes on without waiting for it`, {
+                    turnId,
+                    limitMs,
+                    remainingMs: remaining,
+                });
+                return false;
+            }
+            return true;
+        };
+        // Whether what the turn had produced was stored: a deadline stop that could not store it is
+        // not a stopped turn but one that ran out of time with nothing kept (ADR-0252 §6.4).
+        let stored = true;
+        if (config.beforeTurnComplete) {
+            try {
+                // Kept back: time to announce after it.
+                stored = await within('store', STOP_ANNOUNCE_MARGIN_MS, () => config.beforeTurnComplete({ rounds, usage, newMessages, stopped: marker }));
+            }
+            catch (err) {
+                stored = false;
+                log('error', 'agent:turn', 'beforeTurnComplete failed; the stopped turn is announced without it', {
+                    turnId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        try {
+            await within('announcement', STOP_STEP_FLOOR_MS, () => config.emit.emit(socketRoom, AGENT_SOCKET_EVENTS.TURN_COMPLETE, {
+                turnId,
+                rounds,
+                usage,
+                stopReason: stopped.reason,
+                timestamp: Date.now(),
+            }));
+        }
+        catch (err) {
+            log('error', 'agent:turn', 'The stopped turn could not be announced', { turnId, error: err instanceof Error ? err.message : String(err) });
+        }
+        log('info', 'agent:turn', 'Turn stopped', {
+            turnId,
+            conversationId: input.conversationId,
+            stopReason: stopped.reason,
+            totalRounds: rounds,
+            newMessageCount: newMessages.length,
+        });
+        return {
+            rounds,
+            usage,
+            newMessages,
+            ...(earlier.expired && earlier.expired.claimed.length > 0 ? { settledApprovals: earlier.expired.claimed } : {}),
+            maxRoundsReached: false,
+            stopReason: stopped.reason,
+            stopped: marker,
+            ...(stored ? {} : { stored: false }),
+            ...(fileArea ? { attachments: fileGuard.usage() } : {}),
+        };
     }
 }
 /** Put a note for the model on the turn's user message, after what the user said. */
@@ -1162,8 +1669,7 @@ function withNote(messages, note) {
     const last = messages[messages.length - 1];
     if (!note || !last || last.role !== 'user')
         return messages;
-    const text = typeof last.content === 'string' ? last.content : last.content.map((p) => ('text' in p ? p.text : '')).join('');
-    return [...messages.slice(0, -1), { role: 'user', content: text ? `${text}\n\n${note}` : note }];
+    return [...messages.slice(0, -1), withUserText(last, note)];
 }
 /**
  * Put the client's page on the user's message: what it offers, as an index of
@@ -1187,10 +1693,7 @@ function withPageState(messages, client, maxChars, maxIndexChars) {
         ...(notShown.length ? [`Not shown: ${notShown.join(' ')}`] : []),
         '</page_state>',
     ].join('\n');
-    const text = typeof last.content === 'string'
-        ? last.content
-        : last.content.map((p) => ('text' in p ? p.text : '')).join('');
-    return [...messages.slice(0, -1), { role: 'user', content: `${text}\n\n${pageState}` }];
+    return [...messages.slice(0, -1), withUserText(last, pageState)];
 }
 /**
  * Convert our TurnHistoryMessage[] to AI SDK CoreMessage[].
@@ -1201,7 +1704,9 @@ function withPageState(messages, client, maxChars, maxIndexChars) {
  * AI_MissingToolResultsError crashes when persistence has gaps (e.g., stopWhen
  * triggered before a tool result was persisted).
  */
-function convertHistoryToCoreMessages(history, currentContent) {
+function convertHistoryToCoreMessages(history, currentContent, 
+/** The history's copy of the turn's own message, whose files the turn gives with their lines. */
+turnMessageAt = null) {
     const messages = [];
     // First pass: collect all tool_call_ids that have results in history
     // AND all tool call IDs from assistant messages (to validate results)
@@ -1244,13 +1749,20 @@ function convertHistoryToCoreMessages(history, currentContent) {
     for (let idx = 0; idx < history.length; idx++) {
         const msg = history[idx];
         if (msg.role === 'user') {
-            messages.push({ role: 'user', content: msg.content });
+            // A message's files are in history as their reference lines, never their content (ADR-0252 §2.11).
+            messages.push({ role: 'user', content: idx === turnMessageAt ? msg.content : withReferenceLines(msg.content, msg.attachments ?? undefined) });
         }
         else if (msg.role === 'assistant') {
-            if (msg.content || msg.tool_calls?.length) {
+            // A stopped turn's last message says so after its text (ADR-0252 §2.3).
+            // A message that has only that carries the line as its whole text: an
+            // empty text block is refused by a model provider.
+            const stoppedLine = msg.stopped ? turnStoppedNote(msg.stopped) : null;
+            const said = msg.content && msg.content.trim() ? msg.content : null;
+            const text = [said, stoppedLine && !said?.includes(stoppedLine) ? stoppedLine : null].filter(Boolean).join('\n\n');
+            if (text || msg.tool_calls?.length) {
                 const parts = [];
-                if (msg.content) {
-                    parts.push({ type: 'text', text: msg.content });
+                if (text) {
+                    parts.push({ type: 'text', text });
                 }
                 if (msg.tool_calls?.length) {
                     for (const tc of msg.tool_calls) {