@ouispec/agent-worker 0.3.0 → 0.7.0

package/dist/orchestrator.js

@@ -19,14 +19,18 @@
  *   - 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 { 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 +38,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, markedResult, notRunResult, ranNote, refusedNote, resolveContinuation, unavailableNote, } 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 +80,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,7 +114,9 @@ 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);
     log('info', 'agent:ui', 'UI surfaces for this turn', {
@@ -146,13 +153,49 @@ export async function runAgentTurn(config, input) {
         ? 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 });
+    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;
+        },
+    };
+    stopWatch.onStop((record) => {
+        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', 'Turn asked to stop', { turnId, reason: record.reason, graceMs: stopGraceMs });
+        abortController.abort(new TurnStopped(record.reason, record.at));
+    });
     // Build tool execution context
     const toolCtx = {
         userId: input.userId,
@@ -163,18 +206,42 @@ 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 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 +273,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 +304,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
@@ -291,21 +362,46 @@ export async function runAgentTurn(config, input) {
         const args = validation.value;
         // 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);
@@ -344,6 +440,9 @@ export async function runAgentTurn(config, input) {
             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 +483,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,6 +527,19 @@ 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)
@@ -526,12 +643,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 +674,7 @@ export async function runAgentTurn(config, input) {
             resultTimeoutMs: uiResultTimeoutMs,
             maxObservationChars: config.ui.maxObservationChars,
             waitDeadline: uiWaitDeadline,
+            jobWaitMs: uiJobWaitMs,
             currentPage: () => currentPage,
             sequence: uiSequence,
             held: heldDefinitions,
@@ -631,42 +751,45 @@ 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;
+        }
     }
     function assembleTools() {
         const ui = currentUI();
@@ -678,6 +801,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,8 +956,86 @@ 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 ──────
+        //
+        // A card that expires with nobody clicking it sends nothing, so no turn ever
+        // stored how the call ended: every later turn read "waiting for approval…
+        // has not run" (dev, 2026-10-04). At the start of a turn the store is asked
+        // about each call the history still shows as waiting. Only its explicit
+        // answer settles one: `claimed` stores the expired result under the call's
+        // own id; `already` (another turn holds the claim) tells the model for this
+        // turn and stores nothing; `open` and `unknown` leave the call as it is. A
+        // call whose "waiting" row is not in the history yet is simply not found.
+        // Expiry is the store's clock's to decide, never this process's.
+        /** 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, withdrawn: 0 };
+            const store = config.approvals;
+            if (!store?.settleExpired)
+                return settled;
+            const owner = { userId: input.userId, conversationId: input.conversationId };
+            const waiting = waitingCalls(input.history ?? [])
+                // The call this very turn carries the decision for is the continuation's.
+                .filter((w) => w.approvalId !== input.approval?.approvalId)
+                .slice(0, MAX_WAITING_SETTLED);
+            const answers = await Promise.all(waiting.map(async (w) => {
+                try {
+                    return { w, answer: await store.settleExpired(w.approvalId, owner) };
+                }
+                catch (err) {
+                    // A store that cannot be reached settles nothing: the call keeps reading "waiting".
+                    log('warn', 'agent:tool', 'Could not ask the approval store about a waiting call', { turnId, approvalId: w.approvalId, error: err instanceof Error ? err.message : String(err) });
+                    return { w, answer: null };
+                }
+            }));
+            for (const { w, answer } of answers) {
+                if (answer?.outcome !== 'claimed' && answer?.outcome !== 'already')
+                    continue;
+                // The user had approved it and it was never run, or nobody decided: the result says which.
+                const wasApproved = answer.decided === 'approved';
+                // 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;
+                const name = w.name ?? 'unknown';
+                settled.outcomes.push({ role: 'tool', content, tool_call_id: w.approvalId, name });
+                if (answer.outcome === 'claimed') {
+                    settled.persisted.push({ role: 'tool', content, toolCallId: w.approvalId, name });
+                    settled.claimed.push(w.approvalId);
+                }
+                log('info', 'agent:tool', 'A waiting call’s approval expired without the call running', {
+                    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
@@ -841,9 +1045,12 @@ export async function runAgentTurn(config, input) {
         // model has no clock, and the changing minute must stay out of the cached
         // system prompt (prompt/clock.ts).
         const messages = [
-            ...withClock(withPageState(convertHistoryToCoreMessages(
-            // An approved call's outcome is a later result of the call already in the history: it takes that call's place.
-            continued?.outcome ? [...(input.history ?? []), continued.outcome] : (input.history ?? []), [input.content, continued?.note].filter(Boolean).join('\n\n')), client, config.ui?.maxObservationChars ?? DEFAULT_PAGE_STATE_CHARS, config.ui?.maxIndexChars ?? DEFAULT_INDEX_CHARS), input.context ?? null),
+            ...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')), 
+            // 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 system prompt goes in `instructions`, NOT in `messages`.
@@ -902,7 +1109,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.
@@ -944,14 +1151,27 @@ 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;
                     return {
                         ...constraints,
+                        ...(trimmed ? { messages: trimmed.messages } : {}),
                         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,
@@ -962,31 +1182,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
@@ -1045,11 +1287,27 @@ 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,
                     },
                 }
                 : {}),
         });
+        // The turn's messages, in the host's format, for it to store.
+        const newMessages = [...expired.persisted, ...(continued?.persisted ?? []), ...convertResponseToTurnMessages({ steps }, executedToolResults)];
+        // The host stores the turn before the client hears it is complete: a message sent the moment
+        // it completes must be answered from a history that holds this turn.
+        if (config.beforeTurnComplete) {
+            try {
+                await config.beforeTurnComplete({ rounds: steps.length, usage, newMessages });
+            }
+            catch (err) {
+                log('error', 'agent:turn', 'beforeTurnComplete failed; the turn completes without it', {
+                    turnId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
         await config.emit.emit(socketRoom, AGENT_SOCKET_EVENTS.TURN_COMPLETE, {
             turnId,
             rounds: steps.length,
@@ -1065,12 +1323,11 @@ export async function runAgentTurn(config, input) {
             usage,
             newMessageCount: responseMessageCount,
         });
-        // Convert AI SDK response messages to our TurnMessage format for persistence
-        const newMessages = [...(continued?.persisted ?? []), ...convertResponseToTurnMessages({ steps }, executedToolResults)];
         return {
             rounds: steps.length,
             usage,
             newMessages,
+            ...(expired.claimed.length > 0 ? { settledApprovals: expired.claimed } : {}),
             maxRoundsReached: steps.length >= maxRounds,
             stopReason,
         };
@@ -1079,7 +1336,164 @@ export async function runAgentTurn(config, input) {
         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() } } : {}),
+        });
+        // 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.
+        const within = async (what, keepBackMs, work) => {
+            const remaining = input.remainingMs?.();
+            if (remaining === undefined) {
+                await work();
+                return;
+            }
+            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,
+                });
+            }
+        };
+        if (config.beforeTurnComplete) {
+            try {
+                // Kept back: time to announce after it.
+                await within('store', STOP_ANNOUNCE_MARGIN_MS, () => config.beforeTurnComplete({ rounds, usage, newMessages, stopped: marker }));
+            }
+            catch (err) {
+                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,
+        };
+    }
+}
+/** Put a note for the model on the turn's user message, after what the user said. */
+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 }];
 }
 /**
  * Put the client's page on the user's message: what it offers, as an index of
@@ -1163,10 +1577,16 @@ function convertHistoryToCoreMessages(history, currentContent) {
             messages.push({ role: 'user', content: msg.content });
         }
         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) {