jevway 0.1.2 → 0.3.0

package/dist/task/run-task.js

@@ -1,3 +1,5 @@
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { findBotWall } from '../browser/bot-wall.js';
 import { PAGE_LEVEL_KINDS, StalePage, TargetUnreachable } from '../browser/tab.js';
 import { showsTarget } from '../browser/words.js';
@@ -9,13 +11,21 @@ import { ANY_HOST, narrowHosts, outsideHosts } from './hosts.js';
 import { scrubberFor } from '../jev/secrets.js';
 import { describeFailure, runChecks } from './checks.js';
 import { deepLink, quoteSpans } from './evidence.js';
-import { Recording } from './recording.js';
+import { writeCall } from '../output/run-folder.js';
+import { Recording } from '../recording/recording.js';
 import { RunStopped, startRunLimit } from './run-limit.js';
-import { checkUploadFiles, fileNames } from './upload-files.js';
+import { checkUploadFiles, fetchUploadUrls, fileNames } from './upload-files.js';
+import { checkTotpSecrets, totpMasks, typingCode } from './totp.js';
+import { downloadNote, keepDownload, sizeWords } from './downloads.js';
+import { isTransientModelError } from '../jev/retry.js';
+import { notificationText, passedText, waitingText } from '../notify/person-messages.js';
+import { ssoProviderOf, stillSigningIn, waitForPersonLoop } from './person-wait.js';
 // How much of the final page's visible text a summary carries: enough to read a list or a settings section, not a whole page.
 const PAGE_TEXT_CHARS = 2500;
 // An agent must know when the text was cut, to read the rest with another call or chrome-devtools.
 export const pageTextFor = (text) => text.length > PAGE_TEXT_CHARS ? `${text.slice(0, PAGE_TEXT_CHARS)}\n…[${text.length - PAGE_TEXT_CHARS} more characters not shown]` : text;
+// The widest end-page screenshot a run folder keeps, in pixels: enough to read, light enough to inline in a result.
+const END_PAGE_WIDTH = 1280;
 // How much of the page title a needs_confirmation reason quotes.
 const CONFIRM_TITLE_CHARS = 80;
 // How much of a page dialog's text a step or a repeat reason quotes.
@@ -41,8 +51,13 @@ const DEFAULTS = {
     hosts: ANY_HOST,
     // Prior art (jkudish/jev-browser) waits 8 s; npm's headless challenge never cleared in 50 s, so this bounds patience.
     wallWaitMs: 8000,
+    // A task built without the runner never waits for a person; the runner sets the call's wait (default 120 s when visible).
+    waitForPersonSeconds: 0,
     checks: [],
 };
+// While waiting for a person: how often the page is read (a full observe, so not every 250 ms) and how often the countdown is told.
+const PERSON_POLL_MS = 1000;
+const PERSON_TICK_MS = 10_000;
 // How often a bot check is looked at again while it gets the chance to clear itself.
 const WALL_POLL_MS = 250;
 // How often a page that has not reacted yet is looked at again while waiting for it to change.
@@ -104,7 +119,6 @@ const ESCAPE = { id: 'press_escape', kind: 'escape', label: 'Press Escape to clo
 // Boxes on small targets land a row off (13 px checkboxes); pad before asking whether one covers the chosen control.
 const BOX_PADDING = 16;
 // A model call that fails like this (5xx, 499 "unexpected error", rate limit, network, timeout) is retried once; any other error is final.
-const TRANSIENT_MODEL_ERROR = /^(5\d\d|429|499)\b|timeout|timed out|ECONNRESET|ETIMEDOUT|fetch failed|socket hang up/i;
 // Pause before that one retry, so a rate limit or a restarting upstream has a moment to clear.
 const MODEL_RETRY_MS = 800;
 // Stands in for the page in a summary when the very first observe fails.
@@ -133,6 +147,8 @@ const BLANK_PAGE = {
 export class BrowserTask {
     trace = [];
     #options;
+    /** Whether a person can see the browser and how to tell them; fixed when the session starts. */
+    #person;
     #history = [];
     #latencies = [];
     #inputTokens = 0;
@@ -183,6 +199,10 @@ export class BrowserTask {
     #toggled = new Map();
     /** Nodes of fields the model chose with no supplied value to type: each is refused once before the caller is asked. */
     #refusedForValue = new Set();
+    /** The caller's authenticator secrets by key: only `decide` (as a marker) and the typing see them. */
+    #totp = new Map();
+    /** Secrets that are not supplied values, by key: each authenticator secret as given and as base32, every code typed. Kept for the session. */
+    #moreSecrets = [];
     /** Trace entries before this index are already scrubbed of secret values. */
     #traceScrubbed = 0;
     /** The page each decision was made on: a `done_when` score counts for the caller's checks only on the page it judged. */
@@ -199,15 +219,36 @@ export class BrowserTask {
     #tabs;
     #ask;
     #recording;
+    /** The run folder each call writes to, every call's summary so far, and what the last call left there. */
+    #output;
+    #summaries = [];
+    #lastCall;
+    /** This call's step listener, and how many of the call's steps it was told. */
+    #onStep;
+    #stepsTold = 0;
+    #onWait;
     /** This call's stop signal (caller cancel or time budget); set while a call runs. */
     #limit;
-    constructor(tab, ask, { recordDir, ...options }) {
+    /** URL files this session fetched, by URL: a later call reuses the file. */
+    #fetchedUploads = new Map();
+    /** Downloads already reported, by guid, and what this call's steps downloaded, for the page text Jev reads. */
+    #downloadsSeen = new Set();
+    #downloadedThisCall = [];
+    constructor(tab, ask, { recordDir, output, totp, person, ...options }) {
         this.#tab = tab;
+        this.#person = person ?? { visible: true };
         this.#tabs = [tab];
         this.#ask = ask;
+        const authenticators = checkTotpSecrets(totp, options.values);
         this.#options = { ...DEFAULTS, values: {}, secretKeys: [], ...definedOnly(options), files: checkUploadFiles(options.files) };
-        if (recordDir)
-            this.#recording = new Recording(recordDir, (text) => this.#scrub(text));
+        this.#takeTotp(authenticators);
+        this.#output = output ?? (recordDir ? { dir: recordDir, record: true } : undefined);
+        if (this.#output?.record)
+            this.#recording = new Recording(this.#output.dir, (text) => this.#scrub(text));
+    }
+    /** What the last call left in the run folder, and its end page as JPEG bytes (absent when the capture failed); none without `output`. */
+    get lastCall() {
+        return this.#lastCall;
     }
     /** The model a call's requests went to, and what its input tokens cost at that model's published rate. */
     #costOf(inputTokens) {
@@ -216,7 +257,7 @@ export class BrowserTask {
     }
     /** Replaces every value the caller marked secret with its marker, in a string or a plain object's strings. */
     #scrub(value) {
-        return scrubberFor(this.#options.values, this.#options.secretKeys)(value);
+        return scrubberFor(this.#options.values, this.#options.secretKeys, this.#moreSecrets)(value);
     }
     // jevway: a page is scrubbed of secrets as soon as the run reads it, so every label, value, history line, page
     // message and reason is built from scrubbed text before anything cuts it short (a cut secret no longer matches the
@@ -226,7 +267,7 @@ export class BrowserTask {
         const page = await this.#tab.observe();
         if (!this.#options.secretKeys.length)
             return page;
-        const scrub = scrubberFor(this.#options.values, this.#options.secretKeys);
+        const scrub = scrubberFor(this.#options.values, this.#options.secretKeys, this.#moreSecrets);
         return {
             ...page,
             url: scrub(page.url),
@@ -241,6 +282,11 @@ export class BrowserTask {
             })),
         };
     }
+    /** Reads the session's tab with no model call and no input, its secret values already masked: what `jevway_look` shows. With `pdf`, the page as a PDF too. */
+    async look({ pdf = false } = {}) {
+        const page = await this.#observe();
+        return pdf ? { ...page, pdf: await this.#tab.pdf() } : page;
+    }
     /** The tab the session is on now: a tab its clicks opened, once followed, or the one it started on. */
     get tab() {
         return this.#tab;
@@ -292,14 +338,18 @@ export class BrowserTask {
     }
     /** Merge new values, a new goal, narrower hosts (a widening list throws), or a one-time confirmation for the next irreversible click. */
     update(patch) {
-        const { confirmIrreversible, confirmTarget, values, secretKeys, files, recordDir: _recordDir, allowedHosts, blockedHosts, ...options } = patch;
-        // First, so a list that would widen the hosts throws before anything else changes.
+        const { confirmIrreversible, confirmTarget, values, secretKeys, files, totp, recordDir: _recordDir, output: _output, person: _person, allowedHosts, blockedHosts, ...options } = patch;
+        // First, so a list that would widen the hosts, or a bad authenticator secret, throws before anything else changes.
         const hosts = narrowHosts(this.#options.hosts, { allowed: allowedHosts, blocked: blockedHosts });
+        const authenticators = checkTotpSecrets(totp, values);
+        const newGoal = options.goal !== undefined && options.goal !== this.#options.goal;
         // A new goal may be to flip back what the old one flipped.
-        if (options.goal !== undefined && options.goal !== this.#options.goal)
+        if (newGoal)
             this.#toggled.clear();
         this.#options = {
             ...this.#options,
+            // The old goal's done_when may already hold, and would end the new goal before it starts.
+            ...(newGoal && options.doneWhen === undefined && { doneWhen: undefined }),
             ...definedOnly(options),
             hosts,
             values: { ...this.#options.values, ...values },
@@ -307,6 +357,7 @@ export class BrowserTask {
             secretKeys: [...new Set([...this.#options.secretKeys, ...(secretKeys ?? [])])],
             files: { ...this.#options.files, ...checkUploadFiles(files) },
         };
+        this.#takeTotp(authenticators, values);
         if (!confirmIrreversible)
             return;
         // A confirmation answers the question jevway asked, so a flag carried onto a later call allows nothing (an unused earlier one stands).
@@ -318,11 +369,41 @@ export class BrowserTask {
         else if (!this.#confirmedCommit)
             this.#confirmIgnored = this.#lastStatus;
     }
+    // The newest plain value or authenticator secret for a key replaces the older one; either stays secret for the session.
+    #takeTotp(authenticators, values = {}) {
+        for (const key of Object.keys(values))
+            this.#totp.delete(key);
+        for (const [key, secret] of authenticators)
+            this.#totp.set(key, secret);
+        this.#moreSecrets.push(...totpMasks(authenticators));
+        if (!authenticators.size)
+            return;
+        this.#options.values = Object.fromEntries(Object.entries(this.#options.values).filter(([key]) => !authenticators.has(key)));
+        this.#options.secretKeys = [...new Set([...this.#options.secretKeys, ...authenticators.keys()])];
+    }
+    // An authenticator key types the code current now (the next one when its period is about to end), masked before it is typed.
+    async #textFor(key, values) {
+        const secret = this.#totp.get(key);
+        if (!secret)
+            return values[key];
+        const code = await typingCode(secret, { now: Date.now, pause: (ms) => this.#limit?.pause(ms) ?? Promise.resolve() });
+        this.#moreSecrets.push([key, code]);
+        return code;
+    }
     /**
      * Runs until done or a hand-back. `signal` is the caller's cancel (the MCP request's): the run stops at its next
-     * check, `blocked` "Cancelled by the caller"; an input already under way finishes first.
+     * check, `blocked` "Cancelled by the caller"; an input already under way finishes first. `onStep` hears each step of
+     * this call (numbered from 1) once the run moves past it, with the page's URL then; `onWait` the countdown while it
+     * waits for a person at a wall. A listener that throws is ignored.
      */
-    async run({ signal } = {}) {
+    async run({ signal, onStep, onWait } = {}) {
+        // URL files are fetched before the run reads a page; a refused one fails the call naming its key.
+        const uploads = this.#output ? join(this.#output.dir, 'uploads') : join(tmpdir(), `jevway-uploads-${process.pid}`);
+        this.#options.files = await fetchUploadUrls(this.#options.files, { dir: uploads, hosts: this.#options.hosts, known: this.#fetchedUploads, signal });
+        this.#downloadedThisCall = [];
+        this.#onStep = onStep;
+        this.#onWait = onWait;
+        this.#stepsTold = 0;
         // The recording is for people: a browser failure while recording must not change or hang the run's outcome.
         await this.#recording?.start(this.#tab).catch(() => undefined);
         let settled;
@@ -340,9 +421,100 @@ export class BrowserTask {
         for (; this.#traceScrubbed < this.trace.length; this.#traceScrubbed++)
             this.trace[this.#traceScrubbed] = this.#scrub(this.trace[this.#traceScrubbed]);
         const summary = this.#scrub(settled);
-        await this.#recording?.finish(this.#tab, summary).catch(() => undefined);
+        this.#onStep = undefined;
+        this.#onWait = undefined;
+        await this.#recording?.finish(this.#tab, summary, { goal: this.#options.goal, doneWhen: this.#options.doneWhen }).catch(() => undefined);
+        if (this.#output)
+            await this.#writeCall(this.#output.dir, summary);
         return summary;
     }
+    // What a call leaves in the run folder; like the recording, it never changes or hangs the run's outcome.
+    async #writeCall(dir, summary) {
+        this.#summaries.push(summary);
+        const screenshot = await this.#endPage().catch(() => undefined);
+        try {
+            const files = writeCall({ dir, call: this.#summaries.length, status: summary.status, shot: screenshot, summaries: this.#summaries, recorded: Boolean(this.#recording) });
+            this.#lastCall = { files, ...(screenshot && { screenshot }) };
+        }
+        catch {
+            this.#lastCall = undefined;
+        }
+    }
+    /** The tab's viewport as a light JPEG for agents: quality 70, at most 1280 pixels wide. Pixels: a secret typed into a visible field shows. */
+    async #endPage() {
+        const ratio = Number(await this.#tab.evaluate('devicePixelRatio')) || 1;
+        const width = this.#ending?.page.w || END_PAGE_WIDTH;
+        const scale = Math.min(1, END_PAGE_WIDTH / (width * ratio));
+        return Buffer.from(await this.#tab.screenshot({ format: 'jpeg', quality: 70, scale }), 'base64');
+    }
+    /** Tells the wait listener the countdown; like a step listener, it only hears. */
+    #tellWait(message, secondsLeft, url) {
+        try {
+            this.#onWait?.({ message: this.#scrub(message), seconds_left: secondsLeft }, this.#scrub(url));
+        }
+        catch {
+            // The caller's progress line never decides how the run goes.
+        }
+    }
+    // jevway: with the browser in view, a person can get past a wall the run never touches. The tab comes forward, one
+    // notification says what to do, and the page is read (no model, no input) until the wall is gone or the time is up.
+    async #waitForPerson(wall, page, { isWall, clearReads, limit }) {
+        const waitMs = this.#person.visible ? this.#options.waitForPersonSeconds * 1000 : 0;
+        if (waitMs <= 0 || limit.stopped())
+            return { outcome: 'off', page };
+        const tab = this.#tab;
+        for (const [method, params] of [['Page.bringToFront', {}], ['Target.activateTarget', { targetId: tab.targetId }]]) {
+            try {
+                await tab.send(method, params);
+            }
+            catch {
+                // Best effort: an old Chrome or a closed window still gets the notification.
+            }
+        }
+        try {
+            this.#person.notify?.(notificationText(wall));
+        }
+        catch {
+            // A notifier only hears.
+        }
+        const { outcome, page: read } = await waitForPersonLoop({
+            waitMs,
+            pollMs: this.#person.pollMs ?? PERSON_POLL_MS,
+            tickMs: this.#person.tickMs ?? PERSON_TICK_MS,
+            clearReads,
+            read: async () => {
+                // A tab the page opens meanwhile is the person's (a "Sign in with Google" popup): never followed.
+                tab.takeOpened();
+                if (tab.closed)
+                    return undefined;
+                return this.#observe().catch((error) => {
+                    if (error instanceof StalePage)
+                        return page;
+                    throw error;
+                });
+            },
+            isWall,
+            pause: limit.pause,
+            stopped: () => Boolean(limit.stopped()),
+            tell: (secondsLeft) => this.#tellWait(waitingText(wall, secondsLeft), secondsLeft, page.url),
+        });
+        if (outcome === 'passed')
+            this.#history.push({ operation: 'WAIT_FOR_PERSON', element: passedText(wall), page_changed: true, confidence: 1 });
+        return { outcome, page: read ?? page };
+    }
+    /** Tells the step listener about this call's steps it has not heard yet; the page's URL is the one the run is on now. */
+    #tellSteps(firstStep, url) {
+        if (!this.#onStep)
+            return;
+        for (; firstStep + this.#stepsTold < this.#history.length; this.#stepsTold++) {
+            try {
+                this.#onStep(this.#scrub(this.#history[firstStep + this.#stepsTold]), this.#stepsTold + 1, url);
+            }
+            catch {
+                // A listener is the caller's (progress, a log line): it never decides how the run goes.
+            }
+        }
+    }
     async #loop(signal) {
         // The page's own scripts can read what it is told to look for, so a secret reaches the page only when typed into its field.
         this.#tab.want(Object.entries(this.#options.values).filter(([key]) => !this.#options.secretKeys.includes(key)).map(([, value]) => value), { files: Object.keys(this.#options.files).length > 0 });
@@ -370,6 +542,7 @@ export class BrowserTask {
         const stop = (status, reason, decision, { overridable = false } = {}) => {
             // A dialog that opened late still belongs on the step that caused it.
             this.#reportDialogs(firstStep);
+            this.#tellSteps(firstStep, page.url);
             // A hand-back asks a new question, so a confirmation still pending (a refused one) is spent.
             if (status === 'needs_confirmation')
                 this.#spendConfirmation();
@@ -429,8 +602,8 @@ export class BrowserTask {
                 const now = await this.#observe().catch(() => undefined);
                 if (now && (await findBotWall(this.#tab, now))) {
                     page = now;
-                    const { wall } = await wallAfterWait();
-                    return wall ? stopAtWall(wall, decision) : undefined;
+                    const { wall, waited } = await wallAfterWait();
+                    return wall ? stopAtWall(wall, decision, waited) : undefined;
                 }
             }
             return stop('done', reason, decision);
@@ -446,8 +619,19 @@ export class BrowserTask {
             return stop(status, reason, decision, { overridable: true });
         };
         // jevway: a bot check offers nothing to act on, and the run never tries to get past one. It gets wallWaitMs to clear
-        // itself (the page read again meanwhile), once per call: one that comes back after clearing ends the run at once.
+        // itself (the page read again meanwhile), then, in a visible browser, a person gets waitForPersonSeconds to pass it;
+        // once per call: one that comes back after clearing ends the run at once.
         let wallWaited = false;
+        // Each kind of wall waits for a person once per call.
+        const personWaited = new Set();
+        const waitForPerson = async (wall, isWall, clearReads) => {
+            if (personWaited.has(wall.kind))
+                return 'off';
+            personWaited.add(wall.kind);
+            const waited = await this.#waitForPerson(wall, page, { isWall, clearReads, limit });
+            page = waited.page;
+            return waited.outcome;
+        };
         const wallAfterWait = async () => {
             let wall = await findBotWall(this.#tab, page);
             if (!wall)
@@ -468,14 +652,24 @@ export class BrowserTask {
                 });
                 wall = await findBotWall(this.#tab, page);
             }
-            return { wall, cleared: !wall };
+            if (!wall || limit.stopped())
+                return { wall, cleared: !wall };
+            const outcome = await waitForPerson({ kind: 'bot_check', check: wall.name }, async (now) => Boolean(await findBotWall(this.#tab, now)), 1);
+            // A tab that went away is the loop's to handle, as after any step.
+            if (outcome === 'passed' || outcome === 'gone')
+                return { cleared: true, byPerson: true };
+            return { wall, cleared: false, ...(outcome === 'ran_out' && { waited: this.#options.waitForPersonSeconds }) };
         };
-        const stopAtWall = (wall, decision) => {
+        const stopAtWall = (wall, decision, waited) => {
             // A cancel or the time budget that cut the wait short is the reason the run ended.
             const halt = limit.stopped();
             if (halt)
                 return stop(halt.status, halt.reason, decision);
-            return { ...stop('blocked', wallReason(wall), decision), wall: { kind: 'bot_check', origin: originOf(page.url), name: wall.provider } };
+            const { visible } = this.#person;
+            return {
+                ...stop('blocked', wallReason(wall, { visible, waited }), decision),
+                wall: { kind: 'bot_check', origin: originOf(page.url), name: wall.provider, person_can_act: visible, ...(waited !== undefined && { waited_seconds: waited }) },
+            };
         };
         // Browser and model errors end the run as `blocked`: the calling agent keeps the session and decides what next.
         try {
@@ -492,6 +686,7 @@ export class BrowserTask {
                 const switchedLate = await this.#switchTabs();
                 if (switchedLate)
                     page = await this.#afterSwitch(switchedLate, firstStep);
+                this.#tellSteps(firstStep, page.url);
                 // Never a decision on a page outside the hosts: a start page, a redirect or a late navigation that left them ends the run.
                 const outside = outsideHosts(page.url, hosts);
                 if (outside)
@@ -500,9 +695,31 @@ export class BrowserTask {
                 for (const tab of this.#tabs)
                     tab.disarmConfirm();
                 // Checked before a decision is spent: a challenge page has nothing for Jev to pick.
-                const { wall } = await wallAfterWait();
+                const { wall, waited, byPerson } = await wallAfterWait();
                 if (wall)
-                    return stopAtWall(wall);
+                    return stopAtWall(wall, undefined, waited);
+                // A person passed it (or its tab went away): the checks above run again on the page now.
+                if (byPerson)
+                    continue;
+                // An identity provider's sign-in for another site is the person's: with a visible browser it waits for them.
+                const provider = ssoProviderOf(page.url);
+                if (provider) {
+                    const origin = originOf(page.url);
+                    const outcome = await waitForPerson({ kind: 'sso', provider }, (now) => Boolean(ssoProviderOf(now.url)), 2);
+                    if (outcome === 'passed' || outcome === 'gone')
+                        continue;
+                    if (outcome === 'stopped') {
+                        const halt = limit.stopped();
+                        return stop(halt.status, halt.reason);
+                    }
+                    if (outcome === 'ran_out') {
+                        const waited = this.#options.waitForPersonSeconds;
+                        return {
+                            ...stop('blocked', ssoReason(provider, origin, waited)),
+                            wall: { kind: 'sign_in', origin, name: provider.toLowerCase(), person_can_act: true, waited_seconds: waited },
+                        };
+                    }
+                }
                 if (++decisions > maxSteps * 2)
                     return stop('step_budget', `Made ${maxSteps * 2} decisions without finishing`);
                 let decision;
@@ -564,9 +781,18 @@ export class BrowserTask {
                         continue;
                     }
                     if (signIn) {
+                        const wallPage = page;
+                        const outcome = await waitForPerson({ kind: 'sign_in', host: hostOf(page.url) }, (now) => stillSigningIn(now, wallPage), 2);
+                        if (outcome === 'passed' || outcome === 'gone')
+                            continue;
+                        const halt = limit.stopped();
+                        if (halt)
+                            return stop(halt.status, halt.reason, decision);
+                        const { visible } = this.#person;
+                        const waited = outcome === 'ran_out' ? this.#options.waitForPersonSeconds : undefined;
                         return {
-                            ...stop('blocked', `The page asks to sign in at ${signIn.origin} and no supplied value fits its fields; sign in there (or pass the values), then call again.`, decision),
-                            wall: signIn,
+                            ...stop('blocked', signInReason(signIn.origin, { visible, waited }), decision),
+                            wall: { ...signIn, person_can_act: visible, ...(waited !== undefined && { waited_seconds: waited }) },
                         };
                     }
                     return stop('blocked', error, decision);
@@ -686,7 +912,7 @@ export class BrowserTask {
                     continue;
                 }
                 const action = decision.action;
-                const text = decision.valueKey ? values[decision.valueKey] : undefined;
+                const text = decision.valueKey ? await this.#textFor(decision.valueKey, values) : undefined;
                 let element;
                 // jevway: the dialog a confirmed click opens is the same action asking again; any other dialog still gets the answer that changes nothing.
                 if (isRiskyClick(decision) && this.#confirmedCommit)
@@ -696,6 +922,7 @@ export class BrowserTask {
                         operation: decision.operation,
                         element: action.label,
                         valueKey: decision.valueKey ?? undefined,
+                        fileKey: decision.fileKey ?? undefined,
                         option: action.kind === 'select' ? String(action.value) : undefined,
                         confidence: round(Math.min(decision.confidence, decision.targetConfidence ?? 1)),
                     }, decision.operation === 'CLICK_AT' ? decision.nextClick.rect : action.rect);
@@ -867,6 +1094,7 @@ export class BrowserTask {
                 if (decision.operation === 'CLICK' && decision.via !== 'disclosure' && action.expanded === 'false' && page.actions.some((a) => a.node === action.node && a.expanded === 'true')) {
                     this.#openedByRun.add(action.node);
                 }
+                await this.#reportDownloads(firstStep);
                 const repeatedDialog = this.#reportDialogs(firstStep, decision.operation === 'CLICK' ? { action, path: pathBefore, unsaved: unsavedBefore } : undefined);
                 this.#tab.disarmConfirm();
                 if (repeatedDialog)
@@ -1038,6 +1266,34 @@ export class BrowserTask {
             this.#history[last] = { ...this.#history[last], not_executed: saveFirst };
         return repeated;
     }
+    // jevway: the downloads the last action started, once finished (30 s at most), kept in the run folder and noted on its step.
+    async #reportDownloads(firstStep) {
+        const notes = [];
+        for (const tab of this.#tabs) {
+            for (const download of await tab.downloadsAfterInput()) {
+                // A tab this one opened reports its own downloads, which its opener claimed too.
+                if (this.#downloadsSeen.has(download.guid))
+                    continue;
+                this.#downloadsSeen.add(download.guid);
+                const named = { ...download, name: this.#scrub(download.name) };
+                let kept;
+                try {
+                    kept = keepDownload(named, this.#output?.dir);
+                }
+                catch {
+                    kept = { name: named.name, bytes: named.bytes, state: named.state, ...(named.filePath && { path: named.filePath }) };
+                }
+                notes.push(downloadNote(kept));
+                if (kept.state === 'completed')
+                    this.#downloadedThisCall.push(`${kept.name} (${sizeWords(kept.bytes)})`);
+            }
+        }
+        const last = this.#history.length - 1;
+        if (notes.length && last >= firstStep) {
+            const entry = this.#history[last];
+            this.#history[last] = { ...entry, element: `${entry.element} ${notes.map((note) => `(${note})`).join(' ')}` };
+        }
+    }
     // What the run left unsaved on the page a click was made on: the last field typed there, else the control last ticked.
     #unsavedOn(path, ticked) {
         const typed = this.#typedFields.filter((field) => field.path === path).at(-1);
@@ -1086,7 +1342,7 @@ export class BrowserTask {
             return await this.#decide(page);
         }
         catch (error) {
-            if (!(error instanceof ModelCallError) || !TRANSIENT_MODEL_ERROR.test(error.message))
+            if (!(error instanceof ModelCallError) || !isTransientModelError(error))
                 throw error;
             await (this.#limit?.pause(MODEL_RETRY_MS) ?? new Promise((resolve) => setTimeout(resolve, MODEL_RETRY_MS)));
             return this.#decide(page);
@@ -1125,7 +1381,8 @@ export class BrowserTask {
             const decision = await decide(ask, {
                 page: this.#withSaid(this.#withKeys(page)),
                 goal,
-                values,
+                // An authenticator key is offered like a secret value: Jev sees its marker, never the secret.
+                values: { ...values, ...Object.fromEntries([...this.#totp].map(([key, secret]) => [key, secret.base32])) },
                 secretKeys,
                 files: fileNames(this.#options.files),
                 history: this.#history.slice(-10),
@@ -1175,12 +1432,17 @@ export class BrowserTask {
     // jevway: what the page said after the last submit is the first line of the text Jev reads. The done check judges the current
     // page's text only, so a "saved" message that scrolled away (or sits above the viewport) is no evidence unless the text carries it.
     // It stays while the run is on the path where the message appeared; the caller's page_text is never changed.
+    // A download shows nothing on the page, so what this call downloaded leads the text too.
     #withSaid(page) {
         if (this.#said && this.#said.path !== pathOf(page.url))
             this.#said = undefined;
-        if (!this.#said)
+        const lines = [
+            ...(this.#downloadedThisCall.length ? [`[Downloaded this call] ${this.#downloadedThisCall.join(', ')}`] : []),
+            ...(this.#said ? [`[Page message after "${this.#said.label}"] ${this.#said.text}`] : []),
+        ];
+        if (!lines.length)
             return page;
-        return { ...page, text: `[Page message after "${this.#said.label}"] ${this.#said.text}\n${page.text}` };
+        return { ...page, text: `${lines.join('\n')}\n${page.text}` };
     }
     // The lines the page now shows that this run never saw on its path. The previous message of a submit doesn't count as seen, so a repeated one is quoted again.
     #saidAfter(label, page, textBefore) {
@@ -1474,12 +1736,25 @@ const controlOf = (decision, page) => ({
     label: decision.operation === 'CLICK_AT' ? '' : bareLabel(decision.action?.label ?? ''),
     coordinate: decision.operation === 'CLICK_AT',
 });
+// How many of a field's choices a needs_input lists, and how much of each: page text, so kept short.
+const FIELD_CHOICES = 10;
+const FIELD_CHOICE_CHARS = 80;
+// The choices the page lists for a field: a select of the same name, or the option rows of its open list (an expanded combobox).
+const choicesFor = (field, page) => {
+    const prefix = `${field.label} → `;
+    const selectOptions = page.actions.filter((action) => action.kind === 'select' && action.label.startsWith(prefix)).map((action) => action.label.slice(prefix.length));
+    const openRows = field.expanded === 'true' ? page.actions.filter((action) => action.kind === 'click' && action.role === 'option').map((action) => bareLabel(action.label)) : [];
+    return [...new Set([...selectOptions, ...openRows].map((label) => label.trim().slice(0, FIELD_CHOICE_CHARS)).filter(Boolean))].slice(0, FIELD_CHOICES);
+};
 // The fields a needs_input wants: the one Jev chose to type into, or every empty field a BLOCKED found no value for, in page order.
 const missingFields = (decision, page) => {
     const fields = decision.operation === 'TYPE_TEXT' && decision.action
         ? [decision.action]
         : decision.fieldsWithoutValue.map((label) => page.actions.find((action) => action.kind === 'fill' && action.label === label) ?? { label });
-    return fields.map((field) => ({ label: bareLabel(field.label), ...(field.role && { role: field.role }), path: pathnameOf(page.url) }));
+    return fields.map((field) => {
+        const options = choicesFor(field, page);
+        return { label: bareLabel(field.label), ...(field.role && { role: field.role }), path: pathnameOf(page.url), ...(options.length && { options }) };
+    });
 };
 const sameControl = (a, b) => a.path === b.path && a.label === b.label && a.coordinate === b.coordinate;
 const pathnameOf = (url) => {
@@ -1601,7 +1876,32 @@ const round = (value) => Math.round(value * 1000) / 1000;
 class ModelCallError extends Error {
 }
 const messageOf = (error) => (error instanceof Error ? error.message : String(error));
-// The hand-back for a bot wall: what it is, what made it one, and who can pass it.
-const wallReason = (wall) => `The page is a bot check (${wall.name}; seen: ${wall.evidence.map((e) => (e.startsWith('title ') ? e : `"${e}"`)).join(', ')}) that did not clear by itself; jevway never tries to get past one. A person can pass it in this tab, then continue the session.`;
+// The hand-back for a bot wall: what it is, what made it one, whether a person was waited for, and who can pass it.
+const wallReason = (wall, { visible, waited }) => {
+    const seen = wall.evidence.map((e) => (e.startsWith('title ') ? e : `"${e}"`)).join(', ');
+    const wait = waited === undefined ? '' : `, and nobody passed it in the ${waited} s jevway waited with the tab in front`;
+    const who = visible
+        ? 'A person can pass it in this tab, then continue the session.'
+        : 'This browser is headless, so nobody can pass it here: a visible browser is needed (JEVWAY_BROWSER=auto or launch).';
+    return `The page is a bot check (${wall.name}; seen: ${seen}) that did not clear by itself${wait}; jevway never tries to get past one. ${who}`;
+};
+// The hand-back for a sign-in wall no supplied value passes.
+const signInReason = (origin, { visible, waited }) => {
+    const wait = waited === undefined ? '' : `, and nobody signed in during the ${waited} s jevway waited with the tab in front`;
+    const what = visible
+        ? 'sign in there (or pass the values), then call again.'
+        : 'pass the values, or sign in with a visible browser (JEVWAY_BROWSER=auto or launch; this one is headless), then call again.';
+    return `The page asks to sign in at ${origin} and no supplied value fits its fields${wait}; ${what}`;
+};
+// The hand-back for an SSO sign-in nobody finished while the run waited.
+const ssoReason = (provider, origin, waited) => `The page asks to sign in with ${provider} at ${origin} for another site, and nobody finished it during the ${waited} s jevway waited with the tab in front; sign in there, then call again.`;
+const hostOf = (url) => {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+};
 // Anything that is not a model error came from the tab (CDP, page never settling, an unconfirmed action).
 const describeError = (error) => `${error instanceof ModelCallError ? 'Model' : 'Browser'} error: ${messageOf(error).slice(0, 200)}`;