jevway 0.2.0 → 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';
@@ -12,8 +14,12 @@ import { deepLink, quoteSpans } from './evidence.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.
@@ -45,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.
@@ -136,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;
@@ -186,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. */
@@ -209,13 +226,22 @@ export class BrowserTask {
     /** 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, output, ...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) };
+        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));
@@ -231,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
@@ -241,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),
@@ -256,9 +282,10 @@ export class BrowserTask {
             })),
         };
     }
-    /** Reads the session's tab with no model call and no input, its secret values already masked: what `jevway_look` shows. */
-    look() {
-        return this.#observe();
+    /** 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() {
@@ -311,9 +338,10 @@ 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, output: _output, 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 (newGoal)
@@ -329,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).
@@ -340,13 +369,40 @@ 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. `onStep` hears each step of
-     * this call (numbered from 1) once the run moves past it, with the page's URL then; a listener that throws is ignored.
+     * 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, onStep } = {}) {
+    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);
@@ -366,6 +422,7 @@ export class BrowserTask {
             this.trace[this.#traceScrubbed] = this.#scrub(this.trace[this.#traceScrubbed]);
         const summary = this.#scrub(settled);
         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);
@@ -390,6 +447,61 @@ export class BrowserTask {
         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)
@@ -490,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);
@@ -507,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)
@@ -529,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 {
@@ -562,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;
@@ -626,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);
@@ -748,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)
@@ -930,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)
@@ -1101,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);
@@ -1188,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),
@@ -1238,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) {
@@ -1537,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) => {
@@ -1664,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)}`;

package/dist/task/start-task.js

@@ -1,4 +1,5 @@
 import { connectChrome } from '../browser/chrome.js';
+import { dropStagedDownloads, useDownloads } from '../browser/downloads.js';
 import { Tab } from '../browser/tab.js';
 import { createAsk, profileOptions, resolveModel } from '../jev/model.js';
 import { replayMode } from '../jev/replay.js';
@@ -7,6 +8,7 @@ import { missingKeyMessage } from '../setup/env-file.js';
 import { hostsFromEnv, narrowHosts, outsideHosts } from './hosts.js';
 import { BrowserTask } from './run-task.js';
 import { retryingAsk } from '../jev/retry.js';
+import { desktopNotifier } from '../notify/desktop.js';
 /**
  * Connects a browser once and starts tasks on tabs inside it. Tasks and journeys need the chosen model's key:
  * `TYPESAFE_API_KEY` for Jev (default), `OPENROUTER_API_KEY` for Clef-omni. Without it the runner is still made, so an
@@ -30,7 +32,12 @@ export const createRunner = (source, choice = {}) => {
         return (client ??= createAsk(profile));
     };
     let chrome;
-    const browser = () => (chrome ??= connectChrome(source));
+    // Downloads are set up once per connection: staged in jevway's own browser, Chrome's own behaviour in the person's.
+    const browser = () => (chrome ??= connectChrome(source).then(async (handle) => {
+        await useDownloads(handle.cdp, source).catch(() => undefined);
+        return handle;
+    }));
+    let shown;
     return {
         /** Throws the missing-key message, so the CLI can report it as a usage error before any browser starts. */
         requireKey() {
@@ -46,17 +53,23 @@ export const createRunner = (source, choice = {}) => {
             if (!url && !tab)
                 throw new Error('Pass `url` to open a new tab or `tab` to reuse an open one.');
             const page = url ? await Tab.open(cdp, url) : await Tab.find(cdp, tab);
+            const visible = await (shown ??= browserShown(source, cdp));
             const task = new BrowserTask(page, decider, {
                 ...profileOptions(profile),
                 ...definedOnly(options),
                 hosts,
                 screenshots: options.screenshots ?? screenshots,
+                waitForPersonSeconds: personWaitSeconds(options.waitForPersonSeconds),
+                person: { visible, notify: desktopNotifier() },
             });
             task.update({ confirmIrreversible, confirmTarget });
             return task;
         },
-        /** Reads a page with no model call and no input: an open tab by URL part, or a URL in a background tab closed again. */
-        async look({ url, tab }) {
+        /**
+         * Reads a page with no model call and no input: an open tab by URL part, or a URL in a background tab closed again.
+         * With `pdf`, the page printed as a PDF comes with it.
+         */
+        async look({ url, tab, pdf = false }) {
             if (!url && !tab)
                 throw new Error('Pass `url` to open a page or `tab` to read an open one.');
             if (url)
@@ -64,7 +77,8 @@ export const createRunner = (source, choice = {}) => {
             const { cdp } = await browser();
             const page = url ? await Tab.open(cdp, url) : await Tab.find(cdp, tab);
             try {
-                return await page.observe();
+                const state = await page.observe();
+                return pdf ? { ...state, pdf: await page.pdf() } : state;
             }
             finally {
                 if (url)
@@ -89,14 +103,43 @@ export const createRunner = (source, choice = {}) => {
             });
         },
         async close() {
-            if (chrome)
-                await (await chrome).close();
+            if (chrome) {
+                const handle = await chrome;
+                await handle.close();
+                dropStagedDownloads(handle.cdp);
+            }
             chrome = undefined;
+            shown = undefined;
         },
     };
 };
 // Waits before each retry of a journey's model call after a busy or flaky API answer.
 const JOURNEY_RETRY_MS = [1000, 3000];
+// Waits for a person at a wall this long, in seconds, when the call names no wait and JEVWAY_PERSON_WAIT_SECONDS is unset.
+const PERSON_WAIT_SECONDS = 120;
+/**
+ * The call's wait for a person, else `JEVWAY_PERSON_WAIT_SECONDS` (whole seconds), else 120. A headless browser waits 0
+ * whatever this says (the task knows whether a person can see it).
+ *
+ * @example
+ * personWaitSeconds(undefined, { JEVWAY_PERSON_WAIT_SECONDS: '60' }) // 60
+ */
+export const personWaitSeconds = (call, env = process.env) => {
+    const raw = env.JEVWAY_PERSON_WAIT_SECONDS?.trim();
+    return call ?? (raw && /^\d+$/.test(raw) ? Number(raw) : PERSON_WAIT_SECONDS);
+};
+/** Whether a person can see this browser: never `launch-headless`, nor a headless Chrome behind a port or `auto`. */
+const browserShown = async (source, cdp) => {
+    if (source === 'launch-headless')
+        return false;
+    try {
+        const { userAgent } = await cdp.send('Browser.getVersion');
+        return !/HeadlessChrome/.test(String(userAgent));
+    }
+    catch {
+        return true;
+    }
+};
 /** Throws before a page outside the host rules is opened. */
 const refuseOutside = (url, hosts) => {
     const outside = outsideHosts(url, hosts);