sitelooper 0.3.0

package/dist/agent/loop.js

@@ -0,0 +1,870 @@
+import { captureSignature } from '../daemon/diff.js';
+import { fingerprintPage } from '../daemon/fingerprint.js';
+import { candidatesFor, renderCandidates } from '../skills/replay.js';
+import { componentsOnPage, renderComponents } from '../skills/components.js';
+import { originOf } from '../skills/store.js';
+import { buildSystemPrompt } from './prompt.js';
+import { addEvidenceValue, admitsIncompletion, backfillReadValues, flattenComposedValues, mergeReportValues, namingAskMessage, promoteLabelledReads, proseIdentifiers, unnamedReadValues, validateReport } from './report.js';
+import { executeTool, toolDefsFor } from './tools.js';
+import { captureReadBack, captureReadBackAt, setIdentityHints } from '../daemon/recorder.js';
+/** Tools that change the page URL, staleing every existing snapshot's refs. */
+const NAVIGATION_TOOLS = new Set(['goto', 'back', 'tabs']);
+/** Per-turn LLM watchdog: a turn that hasn't produced a tool call by now is aborted. */
+export const DEFAULT_TURN_TIMEOUT_MS = 90_000;
+/**
+ * Consecutive turns allowed to end without a tool call (watchdog abort or
+ * prose-only reply) before the loop gives up. Bailing here turns a silent
+ * multi-minute stall into a fast, explicit failure.
+ */
+const MAX_UNPRODUCTIVE_TURNS = 3;
+/** Gestures that count towards cycle detection; observations never do. */
+const CYCLE_TOOLS = new Set(['click', 'dblclick', 'modifier_click', 'right_click', 'fill', 'type', 'press', 'select', 'check', 'goto', 'back']);
+/** Repetitions of a cycle before it counts as looping. */
+const CYCLE_REPEATS = 3;
+/** Longest cycle looked for (Exit edit ↔ Discard is 2; open-menu, pick, confirm is 3). */
+const CYCLE_MAX_PERIOD = 3;
+/**
+ * The period of a short cycle that has just repeated CYCLE_REPEATS times at
+ * the tail of `acts`, or 0. Entries carry the tool, its args AND the tool
+ * result (state diff included), so a paginating "Next" click whose diff
+ * differs each time is not a cycle — only identical responses to identical
+ * gestures are.
+ */
+export function loopingCycle(acts) {
+    for (let p = 1; p <= CYCLE_MAX_PERIOD; p++) {
+        const need = p * CYCLE_REPEATS;
+        if (acts.length < need)
+            return 0;
+        const tail = acts.slice(-need);
+        let same = true;
+        for (let i = p; i < need && same; i++)
+            if (tail[i] !== tail[i - p])
+                same = false;
+        if (same)
+            return p;
+    }
+    return 0;
+}
+/**
+ * Extra turn/time budget the escalation attempt gets when the routine model
+ * bailed by exhausting its own. Deliberately modest: the point is to clear a
+ * wall the first attempt proved is there, not to let one instruction run away.
+ */
+const ESCALATION_BUDGET_MULTIPLIER = 1.5;
+/** Cap on the evidence values carried into the durable one-line report entry. */
+const REPORT_FACTS_CHARS = 600;
+/** The first hold not yet asked that has something to ask about `report`. */
+function firstHold(holds, asked, report) {
+    for (const hold of holds) {
+        if (asked.has(hold.name))
+            continue;
+        const hit = hold.check(report);
+        if (hit)
+            return { name: hold.name, ...hit };
+    }
+    return null;
+}
+/**
+ * The agentic loop: send instruction + history, execute the model's tool
+ * calls in-process, feed results back, until a valid `report` (or turn/time
+ * caps hit → blocked with a transcript tail).
+ */
+export async function runInstruction(provider, browser, state, instruction, opts) {
+    const deadline = Date.now() + opts.timeoutMs;
+    const usage = { promptTokens: 0, completionTokens: 0, cachedTokens: 0 };
+    const transcript = [];
+    const actions = [];
+    const screenshots = [];
+    let reportRetried = false;
+    /** evidence.values from the report held for naming, so the retry cannot lose them. */
+    let heldValues;
+    /**
+     * Reasons to hand a schema-valid report back to the model ONCE before
+     * accepting it, asked in this order. Each fires at most once per
+     * instruction and never on the last turn: a held report that then hits the
+     * cap is reported as blocked, and losing a completed instruction costs far
+     * more than anything a hold can win. The retry is accepted whatever it
+     * says — so is the first report, if the model simply repeats it.
+     */
+    const holds = [
+        {
+            // A success whose own summary says the work was not finished: the
+            // status and the prose must agree before a flow marks the step done on
+            // the strength of the status alone.
+            name: 'contradiction',
+            check: (report) => {
+                const admission = report.status === 'success' ? admitsIncompletion(report.summary) : null;
+                if (!admission)
+                    return null;
+                return {
+                    message: `report held — status is "success" but the summary says "${admission}". Those cannot both be true. If the instruction was FULLY completed and verified, call report again with a summary that does not describe unfinished work. If it was not, call report again with status "failure" or "blocked" and say exactly what is missing. Do not take further actions first.`,
+                    transcript: `report held for contradiction: success but "${admission}"`,
+                    progress: `holding success report that admits "${admission}"`,
+                };
+            },
+        },
+        {
+            // Values the report describes but never named. Ask with the values
+            // quoted back so the model supplies labels rather than re-reading the
+            // page — see unnamedReadValues for what an unnamed value costs every
+            // later replay.
+            name: 'naming',
+            check: (report) => {
+                const unnamed = unnamedReadValues(report, browser.script?.readsThisInstruction() ?? []);
+                if (!unnamed.length)
+                    return null;
+                heldValues = report.evidence?.values;
+                browser.script?.noteNamingAsk?.(unnamed);
+                return {
+                    message: namingAskMessage(unnamed),
+                    transcript: `report held for naming: ${unnamed.join(', ')}`,
+                    progress: `asking for names for ${unnamed.length} unnamed read value(s): ${unnamed.join(', ')}`,
+                };
+            },
+        },
+    ];
+    const holdsAsked = new Set();
+    let capWarned = false;
+    let unproductiveTurns = 0;
+    // Recent state-changing calls with their outcomes, for cycle detection —
+    // see loopingCycle. Cleared when the nudge is issued so the second strike
+    // needs a fresh full cycle.
+    const recentActs = [];
+    let loopNudged = false;
+    // Previous instructions' raw tool output describes a page that has usually
+    // moved on; their durable conclusion survives as the `[report]` line below.
+    // Blanking it here keeps per-turn context flat across a long session instead
+    // of letting it grow until trimHistory's size cap forces the same thing.
+    const elided = state.elidePriorToolResults();
+    if (elided.elided) {
+        opts.onProgress?.(`[history] elided ${elided.elided} tool result(s) from earlier instructions (~${Math.round(elided.charsSaved / 4000)}k tokens/turn saved)`);
+    }
+    state.trimHistory();
+    const location = await describeLocation(browser);
+    // Learning mode: offer the stored procedures that start on this page. They
+    // go in the user message, not the system prompt, so the cached prefix stays
+    // byte-identical across instructions.
+    const offered = await offerSkills(browser);
+    const skill = {
+        listed: offered.ids,
+        stepsReplayed: 0,
+        stepsTotal: 0,
+        repaired: false,
+        refused: false,
+        fallthroughs: 0,
+        similarity: null,
+        deterministicActions: 0,
+        totalActions: 0,
+    };
+    state.messages.push({
+        role: 'user',
+        content: [instruction, location, offered.text].filter(Boolean).join('\n\n'),
+    });
+    // Script recording (opt-in) groups this instruction's actions under one
+    // test.step, so a generated spec reads as the plan that produced it.
+    // Identity hints for this instruction's locators: the caller's declared
+    // variables (the runid every record of this run is named after). Typed
+    // values join them as the instruction runs — see ScriptRecorder.prepare.
+    setIdentityHints(Object.values(state.vars ?? {}));
+    browser.script?.beginInstruction(opts.recordAs?.text ?? instruction, opts.recordAs ? { ...offered.context, resume: true } : offered.context);
+    const system = { role: 'system', content: buildSystemPrompt(state) };
+    const toolDefs = toolDefsFor(browser);
+    /** Resume advice differs sharply depending on whether anything actually ran. */
+    const resumeHint = () => actions.length
+        ? 'Work may be partially complete — check the actions log and verify current state before resuming.'
+        : 'No tool call ran, so the browser was not touched — nothing to undo.';
+    /** Only for the failure modes where the agent never got going by itself. */
+    const narrowHint = ' Re-run with one concrete artifact per instruction.';
+    const finish = async (report, turns, blockedTail = false, bailReason) => {
+        // Deterministic evidence backfill: a read value the model cited in prose
+        // but left out of evidence.values would drop the read at compile time and
+        // leave the step with no skill. Runs before the facts line and before
+        // read-back synthesis so both see the promoted values.
+        if (report.status === 'success' && browser.script) {
+            // A value the model composed out of several page values (a JSON blob per
+            // order line) is unpinnable and unrepublishable as one string. Split it
+            // first, so everything below — backfill, read-back synthesis, compile —
+            // sees the scalars a real element actually shows.
+            const split = flattenComposedValues(report);
+            if (split.length)
+                opts.onProgress?.(`[report] split composed value(s) into ${split.join(', ')}`);
+            // Read-time labels first: the model named these values in the read call
+            // itself, and its name must win over the selector slug backfill derives.
+            const labelled = promoteLabelledReads(report, browser.script.readsThisInstruction());
+            if (labelled.length)
+                opts.onProgress?.(`[report] published ${labelled.length} read-time labelled value(s): ${labelled.join(', ')}`);
+            const promoted = backfillReadValues(report, browser.script.readsThisInstruction());
+            if (promoted.length)
+                opts.onProgress?.(`[report] promoted ${promoted.length} prose-cited read value(s) into evidence: ${promoted.join(', ')}`);
+            // Second source, for the identifiers no read observed at all: a record
+            // reference the model only ever put in prose (a confirmed order's
+            // S00021). Pin it on the live page as a real read, so it becomes a
+            // published output a later step can reference and a replay re-reads its
+            // OWN — fwod5 cancelled the recorded run's order for want of this.
+            if (browser.isOpen) {
+                try {
+                    const page = await browser.getPage();
+                    const pinned = [];
+                    for (const value of proseIdentifiers(report)) {
+                        const step = await captureReadBack(page, value);
+                        if (!step)
+                            continue; // not uniquely on the page — it stays prose
+                        browser.script.addStep(step);
+                        // Named `ref`, not after the target. The target of a synthesized
+                        // read-back is the literal "(read-back)" or, on the model-sourced
+                        // path, a CSS selector — odoo published a value called
+                        // `o_subtotal_o_total_name_`, slugged from
+                        // `.o_subtotal, .o_total, [name="amount_untaxed"]`. A later step
+                        // can only reference a name a human or a model would write.
+                        pinned.push(addEvidenceValue(report, 'ref', value));
+                    }
+                    if (pinned.length)
+                        opts.onProgress?.(`[report] pinned ${pinned.length} prose-cited identifier(s) to the page: ${pinned.join(', ')}`);
+                }
+                catch {
+                    // a wedged/navigating page must never turn a good report into no report
+                }
+            }
+        }
+        // This line is what survives once the instruction's tool results are
+        // elided at the next boundary, so the facts the caller asked for ride
+        // along with the prose — otherwise a value read in step 3 would be gone
+        // by step 4 despite having been correctly obtained and reported.
+        const values = report.evidence?.values;
+        const facts = values && Object.keys(values).length
+            ? ' | ' +
+                Object.entries(values)
+                    .map(([k, v]) => `${k}=${v}`)
+                    .join(', ')
+                    .slice(0, REPORT_FACTS_CHARS)
+            : '';
+        state.messages.push({
+            role: 'assistant',
+            content: `[report] ${report.status}: ${report.summary}${facts}`,
+        });
+        // Close the recording's instruction group with its outcome, so a flow can
+        // be built from what each step achieved (values, the skill it used).
+        if (browser.script) {
+            const values = {};
+            for (const [k, v] of Object.entries(report.evidence?.values ?? {}))
+                values[k] = String(v);
+            // Read-back synthesis: for each value the agent reported, capture a
+            // durable read of the live element showing it, so a replay re-reads the
+            // value rather than dropping it as stale. Record-time only, best-effort,
+            // never blocks the report. Skip values already backed by a real read.
+            if (report.status === 'success' && Object.keys(values).length) {
+                try {
+                    const page = await browser.getPage();
+                    const alreadyRead = browser.script.readResultsThisInstruction();
+                    const stragglers = [];
+                    const seenValue = new Set();
+                    // Keyed, not just valued. The evidence KEY is the output name a later
+                    // flow step references, and compile used to recover it by matching
+                    // the read's result against every reported value for an exact hit —
+                    // so a read differing by a currency symbol was stored unlabelled,
+                    // published nothing, and stranded every reference to it.
+                    for (const [name, value] of Object.entries(values)) {
+                        if (!value || alreadyRead.has(value) || seenValue.has(value))
+                            continue;
+                        seenValue.add(value);
+                        const step = await captureReadBack(page, value, name);
+                        if (step)
+                            browser.script.addStep(step);
+                        else
+                            stragglers.push(value); // not pinnable by text — try the model next
+                    }
+                    // Verified model fallback: for values the deterministic search could
+                    // not pin (typically because they are not unique on the page), ask
+                    // the model — which knows where it read them — for a selector, then
+                    // trust it only after it resolves to exactly that value. One extra
+                    // turn, and only when a straggler exists.
+                    // Never past the instruction deadline: this is one more model
+                    // call, and the caller believes the budget bounds the whole thing.
+                    if (stragglers.length && Date.now() < deadline) {
+                        const sourced = await sourceStragglers(provider, page, system, state, stragglers, opts, usage);
+                        for (const step of sourced)
+                            browser.script.addStep(step);
+                    }
+                }
+                catch {
+                    // a wedged/navigating page must never turn a good report into no report
+                }
+            }
+            browser.script.endInstruction({
+                status: report.status,
+                summary: report.summary,
+                values,
+                ...(skill.invoked ? { skill: skill.invoked } : {}),
+                ...(skill.tier ? { tier: skill.tier } : {}),
+            });
+        }
+        state.recordUsage(provider.model, usage);
+        // Any blocked outcome carries its evidence, not just loop-enforced bail-outs:
+        // an agent that declares itself stuck is exactly when a caller — or the
+        // escalation model — needs to know what already ran. Clean successes stay lean.
+        const includeTail = blockedTail || report.status === 'blocked';
+        const finalState = includeTail ? await captureFinalState(browser) : undefined;
+        if (skill.invoked && !skill.refused && skill.stepsReplayed < skill.stepsTotal && report.status === 'success') {
+            skill.repaired = true;
+        }
+        return {
+            report,
+            turns,
+            usage,
+            screenshots,
+            ...(includeTail ? { transcriptTail: transcript.slice(-12), actions: actions.slice(-40) } : {}),
+            ...(finalState ? { finalState } : {}),
+            ...(bailReason ? { bailReason } : {}),
+            ...(browser.learn ? { skill } : {}),
+        };
+    };
+    const timedOut = (turns) => finish({
+        status: 'blocked',
+        summary: `Instruction timed out after ${Math.round(opts.timeoutMs / 1000)}s (${turns} turns, ${actions.length} tool call(s)). ${resumeHint()}${actions.length ? '' : narrowHint}`,
+    }, turns, true, 'timeout');
+    const looping = (turns, period) => finish({
+        status: 'blocked',
+        summary: `Agent looped: a cycle of ${period} action(s) repeated ${CYCLE_REPEATS}× with identical page responses, twice, despite being told to change approach — the state was not advancing. ${resumeHint()} Check the page for a dialog or unsaved-changes prompt that needs a different response.`,
+    }, turns, true, 'looping');
+    const stalled = (turns) => finish({
+        status: 'blocked',
+        summary: `Agent stalled: ${MAX_UNPRODUCTIVE_TURNS} consecutive turns produced no tool call — it reasoned without driving the browser. ${resumeHint()}${narrowHint} Raise --turn-timeout if the model legitimately needs longer per step.`,
+    }, turns, true, 'stalled');
+    /**
+     * Run one tool call, bounded by the instruction deadline (and by `stop`).
+     * Playwright actions have their own internal timeouts, but some can exceed
+     * the remaining budget or wedge entirely (a drag against a blocked renderer),
+     * which would otherwise let a single call run past `--timeout` unchecked.
+     * On expiry we abandon the call — the cooperative signal stops wait_for's
+     * polling, anything still in flight inside Playwright is left to settle
+     * unobserved — and hand back an error result so the loop bails out with the
+     * same blocked report a timeout produces.
+     */
+    const runTool = async (name, args) => {
+        // A stop that already landed must not let the rest of a multi-call turn
+        // run: the listener below never fires on an already-aborted signal.
+        if (opts.signal?.aborted)
+            return { result: `ERROR: ${name} was not run — the instruction was stopped.`, isError: true };
+        const abort = new AbortController();
+        const abortTool = () => abort.abort();
+        const timer = setTimeout(abortTool, Math.max(0, deadline - Date.now()));
+        opts.signal?.addEventListener('abort', abortTool, { once: true });
+        try {
+            return await Promise.race([
+                executeTool(browser, name, args, opts.screenshotDir, abort.signal),
+                new Promise((resolve) => {
+                    abort.signal.addEventListener('abort', () => resolve({
+                        result: `ERROR: ${name} was abandoned — it did not finish within the remaining instruction budget. The page may be mid-action; verify state before repeating it.`,
+                        isError: true,
+                    }), { once: true });
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', abortTool);
+        }
+    };
+    for (let turn = 1; turn <= opts.maxTurns; turn++) {
+        if (opts.signal?.aborted) {
+            return finish({
+                status: 'blocked',
+                summary: `Instruction was stopped after ${turn - 1} turns and ${actions.length} tool call(s). ${resumeHint()}`,
+            }, turn - 1, true, 'stopped');
+        }
+        if (Date.now() > deadline)
+            return timedOut(turn - 1);
+        // Near the cap, tell the agent to stop acting and report now — otherwise a
+        // completed-but-unreported instruction is misreported as blocked/failed.
+        if (!capWarned && turn > opts.maxTurns - 2) {
+            capWarned = true;
+            state.messages.push({
+                role: 'user',
+                content: `Only ${opts.maxTurns - turn + 1} turn(s) left before the cap. Call report NOW with your best current assessment of what was done and verified — do not start new actions. Flag anything you could not confirm.`,
+            });
+        }
+        // Watchdog the LLM call itself: a model that reasons without emitting a tool
+        // call would otherwise spend the entire instruction budget inside one
+        // request, returning zero actions. Never wait past the instruction deadline.
+        // Floor keeps a nearly-expired deadline from producing a zero-length budget;
+        // the abort then falls through to the deadline check and reports a timeout.
+        const turnBudgetMs = Math.max(250, Math.min(opts.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS, deadline - Date.now()));
+        const watchdog = new AbortController();
+        const abortTurn = () => watchdog.abort();
+        const timer = setTimeout(abortTurn, turnBudgetMs);
+        opts.signal?.addEventListener('abort', abortTurn, { once: true });
+        let completion;
+        try {
+            completion = await provider.complete([system, ...state.messages], toolDefs, {
+                signal: watchdog.signal,
+            });
+        }
+        catch (err) {
+            if (!watchdog.signal.aborted)
+                throw err;
+            // Aborted: the assistant message never arrived, so history stays consistent.
+            if (opts.signal?.aborted)
+                continue; // stop requested — reported at the top of the next pass
+            if (Date.now() > deadline)
+                return timedOut(turn - 1);
+            unproductiveTurns++;
+            const secs = Math.round(turnBudgetMs / 1000);
+            transcript.push(`turn ${turn}: aborted after ${secs}s — still reasoning, no tool call issued`);
+            opts.onProgress?.(`[turn ${turn}/${opts.maxTurns}] watchdog: no tool call within ${secs}s, retrying`);
+            if (unproductiveTurns >= MAX_UNPRODUCTIVE_TURNS)
+                return stalled(turn);
+            state.messages.push({
+                role: 'user',
+                content: `Your previous turn was aborted after ${secs}s because it produced no tool call. Stop planning and issue exactly ONE tool call now — the smallest observation that moves the instruction forward (snapshot, read, or eval). You will get another turn after you see its result.`,
+            });
+            continue;
+        }
+        finally {
+            clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', abortTurn);
+        }
+        usage.promptTokens += completion.usage.promptTokens;
+        usage.completionTokens += completion.usage.completionTokens;
+        usage.cachedTokens += completion.usage.cachedTokens;
+        state.messages.push(completion.assistantMessage);
+        if (completion.text)
+            transcript.push(`assistant: ${completion.text.slice(0, 300)}`);
+        if (completion.toolCalls.length === 0) {
+            // Model replied with prose only — remind it of the contract once per occurrence.
+            unproductiveTurns++;
+            if (unproductiveTurns >= MAX_UNPRODUCTIVE_TURNS)
+                return stalled(turn);
+            state.messages.push({
+                role: 'user',
+                content: 'Reminder: act via tool calls only, and finish by calling the report tool. Continue with the instruction.',
+            });
+            continue;
+        }
+        unproductiveTurns = 0;
+        // Every tool call on an assistant message must get a tool result, or the
+        // history is malformed for every later request in the session (both
+        // OpenAI-compatible and Anthropic hosts reject it with a 400). A turn that
+        // ends early — deadline, stop, an accepted report mid-turn — answers the
+        // calls it did not run with a stub. A nudge to the model is likewise held
+        // until the turn's results are all in, never pushed between them.
+        const calls = completion.toolCalls;
+        const stubFrom = (index, why) => {
+            for (const c of calls.slice(index))
+                state.messages.push({ role: 'tool', tool_call_id: c.id, content: `not executed — ${why}` });
+        };
+        let nudge = null;
+        for (const [ci, call] of calls.entries()) {
+            if (Date.now() > deadline || opts.signal?.aborted) {
+                stubFrom(ci, 'the instruction ended first');
+                break;
+            }
+            if (call.name === 'report') {
+                const validation = call.args ? validateReport(call.args) : { ok: false, error: 'arguments were not valid JSON' };
+                if (validation.ok) {
+                    // The report is schema-valid and will be accepted unless one of the
+                    // holds has something to ask first — see `holds`.
+                    const roomToHold = turn < opts.maxTurns && Date.now() < deadline;
+                    const hold = roomToHold ? firstHold(holds, holdsAsked, validation.report) : null;
+                    if (hold) {
+                        holdsAsked.add(hold.name);
+                        state.messages.push({ role: 'tool', tool_call_id: call.id, content: hold.message });
+                        transcript.push(hold.transcript);
+                        opts.onProgress?.(`[turn ${turn}] ${hold.progress}`);
+                        continue;
+                    }
+                    if (holdsAsked.has('naming')) {
+                        if (Object.keys(validation.report.evidence?.values ?? {}).length)
+                            browser.script?.noteNamingAnswered?.();
+                        // The retry asked for the report "unchanged except…"; models drop
+                        // things anyway — sometimes the whole evidence block. Keep every
+                        // value either report named — see mergeReportValues for the
+                        // trace that made this necessary.
+                        if (heldValues) {
+                            (validation.report.evidence ??= {}).values = mergeReportValues(heldValues, validation.report.evidence.values);
+                        }
+                    }
+                    // A repaired payload is accepted, not silently rewritten: the caller
+                    // and the transcript both see what was changed on the agent's behalf.
+                    if (validation.coerced?.length) {
+                        transcript.push(`report coerced: ${validation.coerced.join('; ')}`);
+                        opts.onProgress?.(`[turn ${turn}] report accepted after repair: ${validation.coerced.join('; ')}`);
+                    }
+                    state.messages.push({ role: 'tool', tool_call_id: call.id, content: 'report accepted' });
+                    stubFrom(ci + 1, 'the report closed the instruction');
+                    return finish(validation.report, turn);
+                }
+                state.messages.push({
+                    role: 'tool',
+                    tool_call_id: call.id,
+                    content: `report rejected — ${validation.error}. Call report again with a valid payload (status: success|failure|blocked, summary: string).`,
+                });
+                transcript.push(`report rejected: ${validation.error}`);
+                if (reportRetried) {
+                    stubFrom(ci + 1, 'the instruction ended first');
+                    return finish({
+                        status: 'blocked',
+                        summary: `Agent could not produce a schema-valid report (last error: ${validation.error}).`,
+                    }, turn, true, 'invalid-report');
+                }
+                reportRetried = true;
+                continue;
+            }
+            if (!call.args) {
+                state.messages.push({
+                    role: 'tool',
+                    tool_call_id: call.id,
+                    content: `ERROR: arguments for ${call.name} were not valid JSON. Re-issue the call.`,
+                });
+                transcript.push(`${call.name}: malformed arguments`);
+                continue;
+            }
+            const summary = summarizeArgs(call.args);
+            opts.onProgress?.(`[turn ${turn}/${opts.maxTurns}] ${call.name} ${summary}`);
+            const execution = await runTool(call.name, call.args);
+            actions.push({ tool: call.name, args: summary, ok: !execution.isError });
+            state.messages.push({ role: 'tool', tool_call_id: call.id, content: execution.result });
+            accountActions(skill, call.name, call.args, execution);
+            // The same gesture cycle producing the same page response, over and
+            // over, means the agent is not advancing — the r2 halt on grafana was
+            // 75 turns of Exit edit ↔ Discard dialog. One nudge to break out, then
+            // a blocked report that says so, instead of burning to the cap.
+            if (CYCLE_TOOLS.has(call.name)) {
+                recentActs.push(`${call.name} ${summary} → ${execution.result.slice(0, 600)}`);
+                const period = loopingCycle(recentActs);
+                if (period) {
+                    recentActs.length = 0;
+                    if (loopNudged) {
+                        stubFrom(ci + 1, 'the instruction ended first');
+                        return looping(turn, period);
+                    }
+                    loopNudged = true;
+                    transcript.push(`turn ${turn}: looping — the last ${period} action(s) repeated ${CYCLE_REPEATS}× with identical results`);
+                    opts.onProgress?.(`[turn ${turn}/${opts.maxTurns}] loop detected (period ${period}); nudging`);
+                    nudge = `You are looping: your last ${period} action(s) have run ${CYCLE_REPEATS} times in a row and the page responded identically each time, so repeating them will not change anything. Stop. Take a snapshot, work out why the state is not advancing (a dialog that needs a different button, an unsaved change to discard or keep, a control that is not the one you think), and take a DIFFERENT route. If there is no other route, call report with status blocked and say exactly what is stuck.`;
+                }
+            }
+            if (call.name === 'screenshot' && !execution.isError) {
+                // Multiline: a native-dialog note may follow the path on its own line.
+                const m = execution.result.match(/^screenshot saved: (.+)$/m);
+                if (m)
+                    screenshots.push(m[1]);
+            }
+            // Keep the re-sent context lean: a snapshot's @refs go stale on navigation
+            // and when a newer snapshot arrives, so stub superseded snapshots now
+            // rather than re-sending them (up to ~2k tokens each) every remaining turn.
+            if (!execution.isError) {
+                if (call.name === 'snapshot')
+                    state.elideSnapshots(call.id);
+                else if (NAVIGATION_TOOLS.has(call.name) && !(call.name === 'tabs' && call.args.switch_to === undefined)) {
+                    state.elideSnapshots();
+                }
+            }
+            transcript.push(`${call.name} ${summary} → ${execution.isError ? execution.result.slice(0, 200) : 'ok'}`);
+        }
+        if (nudge)
+            state.messages.push({ role: 'user', content: nudge });
+    }
+    return finish({
+        status: 'blocked',
+        summary: `Turn cap (${opts.maxTurns}) reached without a final report. ${resumeHint()} Do not blindly repeat state-changing actions like submit/delete/move.`,
+    }, opts.maxTurns, true, 'turn-cap');
+}
+/**
+ * Run an instruction on the routine model and, if it comes back blocked, retry
+ * it once on a stronger fallback model.
+ *
+ * Why blocked only: `failure` is a verified negative answer (the assertion was
+ * checked and did not hold) — retrying it on a better model just buys the same
+ * answer twice. `blocked` means the agent could not determine the answer, which
+ * is precisely the failure mode a stronger model can rescue, and the one this
+ * project measured on a real app (a cheap model abandoned a supplier-autocomplete
+ * step after 29 turns that a stronger model then solved).
+ *
+ * The retry shares the SAME live browser and message history, so the fallback
+ * inherits everything the first attempt discovered — and, critically, is told it
+ * is resuming, so it verifies state before repeating anything destructive.
+ */
+export async function runEscalatingInstruction(primary, fallback, browser, state, instruction, opts) {
+    // Where this instruction's history starts, so the failed attempt can be
+    // compacted on handoff without touching earlier instructions (which are
+    // already cached and were not the thing that went wrong).
+    const historyMark = state.messages.length;
+    const first = await runInstruction(primary, browser, state, instruction, opts);
+    const blocked = first.report.status === 'blocked';
+    // An operator `stop` also yields a blocked report — escalating there would
+    // restart work the operator just killed, which is the opposite of the ask.
+    const operatorStopped = Boolean(opts.signal?.aborted);
+    if (!fallback || !blocked || operatorStopped || fallback.model === primary.model)
+        return first;
+    // A first attempt that exhausted its turn/time budget is positive evidence
+    // that the instruction needs MORE of that budget — handing the fallback the
+    // same allowance mostly buys a second bail-out at the same wall. Measured on
+    // a real app: both tiers hit a 30-turn cap on one step that the routine model
+    // then completed in 19 turns once the cap was raised.
+    const headroom = (n) => Math.ceil(n * ESCALATION_BUDGET_MULTIPLIER);
+    const escalatedOpts = {
+        ...opts,
+        // The recording must carry the caller's wording, not the resume scaffold —
+        // see LoopOptions.recordAs. Flow building then merges the continuation
+        // into the failed first attempt's group.
+        recordAs: { text: opts.recordAs?.text ?? instruction, resume: true },
+        ...(first.bailReason === 'turn-cap' ? { maxTurns: headroom(opts.maxTurns) } : {}),
+        ...(first.bailReason === 'timeout' ? { timeoutMs: headroom(opts.timeoutMs) } : {}),
+    };
+    // Hand the stronger model a clean brief, not a transcript of the failure.
+    // escalationPrompt() below already carries what mattered — the blocked
+    // report, the ordered actions log, where the browser was left — so leaving
+    // the raw tool results in place would re-send that same information every
+    // turn at the escalation tier's (much higher) cache rate.
+    const compacted = state.compactToolResults(historyMark);
+    opts.onProgress?.(`[escalating] ${primary.model} reported blocked (${first.bailReason ?? 'agent gave up'}) — ` +
+        `retrying on ${fallback.model}${escalatedOpts.maxTurns !== opts.maxTurns ? ` with ${escalatedOpts.maxTurns} turns` : ''}` +
+        `${compacted.elided ? `, compacted ${compacted.elided} tool result(s) (~${Math.round(compacted.charsSaved / 4000)}k tokens/turn saved)` : ''}`);
+    const second = await runInstruction(fallback, browser, state, escalationPrompt(instruction, first), escalatedOpts);
+    return {
+        ...second,
+        turns: first.turns + second.turns,
+        usage: {
+            promptTokens: first.usage.promptTokens + second.usage.promptTokens,
+            completionTokens: first.usage.completionTokens + second.usage.completionTokens,
+            cachedTokens: first.usage.cachedTokens + second.usage.cachedTokens,
+        },
+        screenshots: [...first.screenshots, ...second.screenshots],
+        escalation: {
+            from: primary.model,
+            to: fallback.model,
+            reason: first.report.summary,
+            firstAttempt: { status: first.report.status, turns: first.turns, usage: first.usage },
+            rescued: second.report.status === 'success',
+            compactedToolResults: compacted.elided,
+        },
+    };
+}
+function escalationPrompt(instruction, first) {
+    const ran = first.actions?.length
+        ? `\nActions the previous attempt ran (most recent last):\n${first.actions
+            .map((a) => `  ${a.ok ? 'ok' : 'FAILED'} ${a.tool} ${a.args}`)
+            .join('\n')}`
+        : '';
+    const where = first.finalState ? `\nThe browser was left at: ${first.finalState.url}` : '';
+    return (`You are RESUMING an instruction that a previous, weaker model could not complete. ` +
+        `It gave up with this report:\n"${first.report.summary}"${ran}${where}\n\n` +
+        `The browser session is that same attempt — nothing has been reset — but the previous attempt's ` +
+        `raw tool output has been elided from the conversation above to keep it small, so treat the ` +
+        `summary and action list here as the record of it and re-observe the page for anything you need. ` +
+        `Before you repeat ANY state-changing action (submit, create, delete, move), observe the current ` +
+        `page and confirm whether it already took effect; the previous attempt may have partially ` +
+        `succeeded. Do not assume its conclusions were correct — it may have been stuck because it ` +
+        `misread the page or probed the wrong values, so re-examine the evidence yourself and look for an ` +
+        `approach it did not try.\n\nThe original instruction to complete is:\n${instruction}`);
+}
+/**
+ * Verified model fallback for read-back synthesis: ask the model where each
+ * un-pinnable reported value lives on the current page, then trust the answer
+ * only after it resolves to exactly that value. Ephemeral — does not touch the
+ * running history — and bounded to one completion.
+ */
+async function sourceStragglers(provider, page, system, state, values, opts, usage) {
+    const ask = {
+        role: 'user',
+        content: `Before this instruction is filed, point to where these value(s) you just reported are shown on the CURRENT page, so they can be re-read on a later run. ` +
+            `Call locate with, for each value, a CSS selector (or @ref from your latest snapshot) that resolves to EXACTLY the one element displaying it — or an empty selector if the value is computed and not shown verbatim on the page. Values:\n` +
+            values.map((v) => `- ${JSON.stringify(v)}`).join('\n'),
+    };
+    let completion;
+    try {
+        // One structured answer from a page the model has already seen: low
+        // reasoning effort, or a reasoning model spends a 16k budget on it.
+        completion = await provider.complete([system, ...state.messages, ask], [LOCATE_TOOL], { signal: opts.signal, effort: 'low' });
+    }
+    catch {
+        return [];
+    }
+    usage.promptTokens += completion.usage.promptTokens;
+    usage.completionTokens += completion.usage.completionTokens;
+    usage.cachedTokens += completion.usage.cachedTokens;
+    const call = completion.toolCalls.find((c) => c.name === 'locate');
+    const sources = call?.args && Array.isArray(call.args.sources) ? (call.args.sources) : [];
+    const out = [];
+    for (const entry of sources) {
+        const e = entry;
+        if (typeof e.value !== 'string' || typeof e.selector !== 'string' || !e.selector.trim())
+            continue;
+        const step = await captureReadBackAt(page, e.value, e.selector).catch(() => null);
+        if (step)
+            out.push(step);
+    }
+    if (out.length)
+        opts.onProgress?.(`[read-back] model sourced ${out.length}/${values.length} un-pinnable value(s)`);
+    return out;
+}
+const LOCATE_TOOL = {
+    name: 'locate',
+    description: 'Point to where each listed value is shown on the current page, so it can be re-read later.',
+    parameters: {
+        type: 'object',
+        required: ['sources'],
+        properties: {
+            sources: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    required: ['value', 'selector'],
+                    properties: {
+                        value: { type: 'string', description: 'The reported value, exactly as given.' },
+                        selector: { type: 'string', description: 'CSS selector or @ref resolving to exactly the element that displays this value; "" if it is computed / not shown.' },
+                    },
+                },
+            },
+        },
+    },
+};
+/** What the stored-skill listing contributes to an instruction's first message. */
+/** Cap on the recorded instruction-start page text (identity evidence, not a snapshot). */
+const START_TEXT_BUDGET = 8000;
+async function offerSkills(browser) {
+    const none = { ids: [], text: '', context: {} };
+    if (!browser.learn || !browser.isOpen)
+        return none;
+    try {
+        const page = await browser.getPage();
+        const url = page.url();
+        const origin = originOf(url);
+        if (!origin)
+            return none;
+        const candidates = candidatesFor(browser.learn.list(origin), url);
+        const fingerprint = (await fingerprintPage(page)) ?? undefined;
+        // Recognized hard widgets on this page: one line telling the model that
+        // plain fill/type/select on them is recipe-backed and self-verifying, so
+        // it does not improvise long keyboard workarounds.
+        const components = renderComponents(await componentsOnPage(page));
+        const text = [renderCandidates(candidates), components].filter(Boolean).join('\n');
+        // Which RECORD this page showed when the instruction started, capped: the
+        // evidence compile needs to give a skill an identity precondition (see
+        // RecordedInstruction.startText).
+        const sig = await captureSignature(page);
+        const startText = sig ? sig.lines.join('\n').slice(0, START_TEXT_BUDGET) : undefined;
+        return {
+            ids: candidates.map((s) => s.id),
+            text,
+            context: { url, ...(fingerprint ? { fingerprint } : {}), ...(startText ? { startText } : {}) },
+        };
+    }
+    catch {
+        return none;
+    }
+}
+/** Count browser actions per tool call, and fold a replay's outcome into the record. */
+function accountActions(skill, name, args, execution) {
+    if (name === 'snapshot' || name === 'report')
+        return;
+    if (name === 'run_skill') {
+        const r = execution.replay;
+        if (!r)
+            return;
+        // First replay wins the record; a second run_skill in one instruction is
+        // unusual and its steps still count as deterministic actions.
+        if (!skill.invoked) {
+            skill.tier = 'B';
+            skill.invoked = r.skill;
+            skill.stepsReplayed = r.stepsRun;
+            skill.stepsTotal = r.stepsTotal;
+            skill.refused = Boolean(r.refused);
+            skill.fallthroughs = r.fallthroughs;
+            skill.similarity = r.similarity;
+            if (r.misses.length)
+                skill.misses = r.misses;
+            if (r.reason)
+                skill.failReason = r.reason;
+            if (r.failedAt !== undefined)
+                skill.failedAt = r.failedAt;
+            skill.replayUrl = r.url;
+        }
+        skill.deterministicActions += r.stepsRun;
+        skill.totalActions += r.stepsRun;
+        return;
+    }
+    if (name === 'batch' && Array.isArray(args.steps)) {
+        // Only the steps that ran count; the result lists one line per step that did.
+        const ran = (execution.result.match(/^\d+\. /gm) ?? []).length;
+        if (execution.isError && !ran)
+            return; // rejected at validation — nothing ran
+        skill.totalActions += ran || args.steps.length;
+        return;
+    }
+    skill.totalActions += 1;
+}
+function summarizeArgs(args) {
+    // A batch's raw args are a wall of nested JSON; the step tools are what the
+    // progress line and the actions log actually need to convey.
+    if (Array.isArray(args.steps)) {
+        const tools = args.steps.map((s) => String(s?.tool ?? '?'));
+        return `[${tools.length} steps: ${tools.join(', ')}]`;
+    }
+    const s = JSON.stringify(args);
+    return s.length > 120 ? s.slice(0, 120) + '…' : s;
+}
+/**
+ * Best-effort "where did this leave the browser" for bail-out results. Bounded
+ * and never throws: this runs on the failure path, where a wedged page must not
+ * turn a blocked report into no report at all.
+ */
+async function captureFinalState(browser) {
+    try {
+        if (!browser.isOpen)
+            return undefined; // never launch a browser just to report on one
+        const page = await browser.getPage();
+        const url = page.url();
+        const title = await Promise.race([
+            page.title().catch(() => undefined),
+            new Promise((r) => setTimeout(() => r(undefined), 2_000)),
+        ]);
+        return title ? { url, title } : { url };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Where the browser is right now, as a line appended to every instruction.
+ *
+ * Without it the model starts blind and, being told to act rather than
+ * deliberate, may guess. Bench run c0822bp (2026-08-22) began its first
+ * instruction with `goto http://localhost:3000` although the caller had just
+ * opened the app on another port: it landed on a browser error page,
+ * port-scanned from inside it, reported the app unreachable, and — because
+ * history persists across instructions — repeated that verdict 118 times.
+ * Naming the page costs ~30 tokens per instruction and removes the guess.
+ *
+ * Never launches a browser: a session with no page yet gets no line, and the
+ * rules then only allow a URL the instruction itself provides. Never throws —
+ * a wedged page must not stop an instruction from starting.
+ */
+async function describeLocation(browser) {
+    if (!browser.isOpen)
+        return null;
+    try {
+        const page = await browser.getPage();
+        const url = page.url();
+        const title = await Promise.race([
+            page.title().catch(() => ''),
+            new Promise((r) => setTimeout(() => r(''), 2_000)),
+        ]);
+        let line = `[browser] You are currently on ${url}${title ? ` — "${title}"` : ''}.`;
+        if (url.startsWith('chrome-error://')) {
+            line +=
+                ' That is a browser error page: the last navigation failed, so the app is NOT at that address. Use back to return to the page the caller set up, or goto a URL the instruction gives — do not guess one.';
+        }
+        else if (url === 'about:blank') {
+            line += ' Nothing has been loaded yet: only navigate to a URL the instruction or briefing gives.';
+        }
+        else {
+            line += ' Start from this page; the caller put the browser here on purpose.';
+        }
+        return line;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=loop.js.map