jevway 0.2.0 → 0.3.0

package/dist/session/session-service.js

@@ -2,8 +2,10 @@ import { randomUUID } from 'node:crypto';
 import { join, resolve } from 'node:path';
 import { scrubberFor } from '../jev/secrets.js';
 import { ensureOutRoot, journeyFolderName, outRoot, runFolderName } from '../output/layout.js';
+import { writeLookPdf, writeRunPdf } from '../output/run-folder.js';
 import { lookAt } from '../task/look.js';
 import { storyLine } from '../task/present.js';
+import { checkTotpSecrets, totpMasks } from '../task/totp.js';
 /** A session id the service does not hold: it ended, expired, or never existed. `code` is for structured CLI errors. */
 export class UnknownSession extends Error {
     code = 'unknown_session';
@@ -49,11 +51,14 @@ export const createSessionService = (runner, options = {}) => {
         const id = newId();
         const at = now();
         const values = request.values ?? {};
-        const secretKeys = request.secretKeys ?? [];
-        const scrub = scrubberFor(values, secretKeys);
+        // An authenticator key is secret for the session, even if a later call gives it a plain value.
+        const secretKeys = [...(request.secretKeys ?? []), ...Object.keys(request.totp ?? {})];
+        // A bad authenticator secret is refused before a tab opens.
+        const moreSecrets = totpMasks(checkTotpSecrets(request.totp, request.values));
+        const scrub = scrubberFor(values, secretKeys, moreSecrets);
         const runDir = recordDir ? resolve(cwd, recordDir) : join(ensureOutRoot(root), 'runs', runFolderName({ at, goal: request.goal, id, scrub }));
         const task = await runner.start({ ...request, output: { dir: runDir, record: Boolean(record || recordDir) } });
-        const entry = { task, ownsTab: Boolean(request.url), busy: false, goal: scrub(request.goal), values, secretKeys, runDir, startedAt: at, lastUsedAt: at };
+        const entry = { task, ownsTab: Boolean(request.url), busy: false, goal: scrub(request.goal), values, secretKeys, moreSecrets, runDir, startedAt: at, lastUsedAt: at };
         sessions.set(id, entry);
         return { id, entry };
     };
@@ -66,18 +71,21 @@ export const createSessionService = (runner, options = {}) => {
             values: request.values,
             secretKeys: request.secretKeys,
             files: request.files,
+            totp: request.totp,
             doneWhen: request.doneWhen,
             checks: request.checks,
             maxSteps: request.maxSteps,
             maxSeconds: request.maxSeconds,
+            waitForPersonSeconds: request.waitForPersonSeconds,
             allowedHosts: request.allowedHosts,
             blockedHosts: request.blockedHosts,
             confirmIrreversible: request.confirmIrreversible,
             confirmTarget: request.confirmTarget,
         });
         entry.values = { ...entry.values, ...request.values };
-        entry.secretKeys = [...new Set([...entry.secretKeys, ...(request.secretKeys ?? [])])];
-        entry.goal = scrubberFor(entry.values, entry.secretKeys)(request.goal);
+        entry.secretKeys = [...new Set([...entry.secretKeys, ...(request.secretKeys ?? []), ...Object.keys(request.totp ?? {})])];
+        entry.moreSecrets.push(...totpMasks(checkTotpSecrets(request.totp)));
+        entry.goal = scrubberFor(entry.values, entry.secretKeys, entry.moreSecrets)(request.goal);
         return { id, entry };
     };
     const journeysRoot = () => env.JEVWAY_JOURNEYS_DIR ? resolve(cwd, env.JEVWAY_JOURNEYS_DIR) : join(ensureOutRoot(root), 'journeys');
@@ -106,7 +114,11 @@ export const createSessionService = (runner, options = {}) => {
             };
             tell({ type: 'started', session: id });
             entry.busy = true;
-            const running = entry.task.run({ signal, onStep: (step, n, url) => tell({ type: 'step', session: id, n, story: storyLine(step), url }) });
+            const running = entry.task.run({
+                signal,
+                onStep: (step, n, url) => tell({ type: 'step', session: id, n, story: storyLine(step), url }),
+                onWait: ({ message, seconds_left }, url) => tell({ type: 'waiting', session: id, message, seconds_left, url }),
+            });
             entry.running = running.catch(() => undefined);
             try {
                 const summary = await running;
@@ -121,13 +133,21 @@ export const createSessionService = (runner, options = {}) => {
                 entry.lastUsedAt = now();
             }
         },
-        /** Reads a page with no model call and no input: a session's tab (its secret values masked), an open tab by URL part, or a URL opened and closed again. */
-        async look({ session, tab, url }) {
+        /**
+         * Reads a page with no model call and no input: a session's tab (its secret values masked), an open tab by URL part, or
+         * a URL opened and closed again. With `pdf`, the page is saved as a PDF too: in the session's run folder
+         * (`looks/NN-<title>.pdf`), else in a look folder of its own (`<root>/looks/<stamp>_<host>_<id4>/page.pdf`).
+         */
+        async look({ session, tab, url, pdf }) {
             if ([session, tab, url].filter(Boolean).length !== 1)
                 throw new Error('Pass exactly one of session, tab or url.');
-            if (session)
-                return lookAt(await findTask(session).task.look());
-            return lookAt(await runner.look({ url, tab }));
+            if (session) {
+                const entry = findTask(session);
+                const looked = await entry.task.look({ pdf });
+                return { ...lookAt(looked), ...(looked.pdf && { pdf: writeRunPdf({ dir: entry.runDir, pdf: looked.pdf, title: looked.title }) }) };
+            }
+            const looked = await runner.look({ url, tab, pdf });
+            return { ...lookAt(looked), ...(looked.pdf && { pdf: writeLookPdf({ root, pdf: looked.pdf, url: looked.url, at: now(), id: newId() }) }) };
         },
         /** Forgets a session and closes the tabs it opened (its first tab only when it started from `url`), unless `keepTab`. */
         async end(session, { keepTab = false } = {}) {

package/dist/setup/skill-command.js

@@ -7,17 +7,22 @@ export const SKILL_USAGE = `Examples:
   jevway skill
   jevway skill --install ~/.claude/skills
 
-jevway skill                      print the SKILL.md this version ships
-jevway skill --install <dir> [--force]   copy the skill folder into <dir>/jevway
+jevway skill [--name jevway-inbox]       print the SKILL.md this version ships (default jevway)
+jevway skill --install <dir> [--force]   copy both skill folders into <dir>/jevway and <dir>/jevway-inbox
 
 Examples:
   jevway skill --install ~/.claude/skills
   jevway skill --install ~/.codex/skills
 
---install prints { ok, status: installed|unchanged|replaced, path, files }. A different jevway skill already in
-<dir>/jevway (or a symlink to one) is left alone unless --force is given.`;
-/** The `skill/jevway/` folder of the installed package: two levels up from both `src/setup/` and `dist/setup/`. */
-export const bundledSkillDir = () => fileURLToPath(new URL('../../skill/jevway/', import.meta.url));
+--install prints { ok, status: installed|unchanged|replaced, path, files } for jevway and the same for each skill in
+skills: [{ name, … }]. jevway-inbox is a standalone disposable inbox script for agents without jevway. A different
+skill already in either folder (or a symlink to one) is left alone, and nothing is copied, unless --force is given.`;
+/** The skills this package ships, by folder name; `--install` copies them all. */
+const BUNDLED_SKILLS = ['jevway', 'jevway-inbox'];
+/** A `skill/<name>/` folder of the installed package: two levels up from both `src/setup/` and `dist/setup/`. */
+const bundledSkillFolder = (name) => fileURLToPath(new URL(`../../skill/${name}/`, import.meta.url));
+/** The `skill/jevway/` folder of the installed package. */
+export const bundledSkillDir = () => bundledSkillFolder('jevway');
 /** Every file under `dir`, as sorted paths relative to it. */
 const filesIn = (dir) => readdirSync(dir, { recursive: true, withFileTypes: true })
     .filter((entry) => entry.isFile())
@@ -34,39 +39,52 @@ const sameFolder = (source, target) => {
         return false;
     }
 };
-/** Whether `<parent>/jevway` is missing, the same as `source`, or something else (a different skill or a symlink to one). */
-export const skillState = (source, parent) => {
-    const path = join(parent, 'jevway');
+/** Whether `<parent>/<name>` is missing, the same as `source`, or something else (a different skill or a symlink to one). */
+export const skillState = (source, parent, name = 'jevway') => {
+    const path = join(parent, name);
     if (!existsSync(path) && !lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink())
         return 'missing';
     return sameFolder(source, path) ? 'same' : 'different';
 };
 /**
- * Copies `source` to `<parent>/jevway`. An identical copy is left as it is; a different folder or a symlink is
- * replaced only with `force` (a symlink is removed, never its target). The copy lands under a temporary name first,
- * so an interrupted install never leaves half a skill.
+ * Copies `source` to `<parent>/<name>` (default `jevway`). An identical copy is left as it is; a different folder or a
+ * symlink is replaced only with `force` (a symlink is removed, never its target). The copy lands under a temporary
+ * name first, so an interrupted install never leaves half a skill.
  *
  * @example
  * installSkill(bundledSkillDir(), '/Users/ada/.claude/skills', { force: false })
  * // { status: 'installed', path: '/Users/ada/.claude/skills/jevway', files: ['SKILL.md'] }
  */
-export const installSkill = (source, parent, { force }) => {
-    const path = join(parent, 'jevway');
+export const installSkill = (source, parent, { force, name = 'jevway' }) => {
+    const path = join(parent, name);
     const files = filesIn(source);
-    const state = skillState(source, parent);
+    const state = skillState(source, parent, name);
     if (state === 'same')
         return { status: 'unchanged', path, files };
     if (state === 'different' && !force)
         return { status: 'exists', path };
     const present = state === 'different';
     mkdirSync(parent, { recursive: true });
-    const incoming = join(parent, `.jevway-${process.pid}.incoming`);
+    const incoming = join(parent, `.${name}-${process.pid}.incoming`);
     cpSync(source, incoming, { recursive: true });
     if (present)
         rmSync(path, { recursive: true, force: true });
     renameSync(incoming, path);
     return { status: present ? 'replaced' : 'installed', path, files };
 };
+/**
+ * Installs every bundled skill into `parent`, or none: a different folder for any of them, without `force`, is
+ * `exists` with its path and nothing is copied.
+ */
+export const installSkills = (parent, { force }) => {
+    const different = BUNDLED_SKILLS.filter((name) => skillState(bundledSkillFolder(name), parent, name) === 'different');
+    if (different.length && !force)
+        return { status: 'exists', paths: different.map((name) => join(parent, name)) };
+    return {
+        status: 'done',
+        skills: BUNDLED_SKILLS.map((name) => ({ name, ...installSkill(bundledSkillFolder(name), parent, { force, name }) })),
+    };
+};
 /**
  * `jevway skill`: prints the bundled SKILL.md, or with `--install <dir>` copies the skill folder into `<dir>/jevway`.
  *
@@ -78,7 +96,7 @@ export const runSkill = async (argv) => {
     try {
         ({ values: options } = parseArgs({
             args: argv,
-            options: { install: { type: 'string' }, force: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+            options: { install: { type: 'string' }, name: { type: 'string' }, force: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
         }));
     }
     catch (error) {
@@ -89,13 +107,18 @@ export const runSkill = async (argv) => {
         return 0;
     }
     if (options.install === undefined) {
-        await print(readFileSync(join(bundledSkillDir(), 'SKILL.md'), 'utf8'));
+        const name = options.name ?? 'jevway';
+        if (!BUNDLED_SKILLS.includes(name)) {
+            return printError(2, 'usage', `jevway skill: --name must be ${BUNDLED_SKILLS.join(' or ')}, got "${name}"`, 'jevway skill --name jevway-inbox');
+        }
+        await print(readFileSync(join(bundledSkillFolder(name), 'SKILL.md'), 'utf8'));
         return 0;
     }
-    const result = installSkill(bundledSkillDir(), options.install, { force: Boolean(options.force) });
+    const result = installSkills(options.install, { force: Boolean(options.force) });
     if (result.status === 'exists') {
-        return printError(1, 'skill_exists', `${result.path} already holds a different jevway skill (or a link to one); it was left as it is`, `Run again with --force to replace it with this version's skill: jevway skill --install ${options.install} --force`);
+        return printError(1, 'skill_exists', `${result.paths.join(' and ')} already ${result.paths.length === 1 ? 'holds a different skill' : 'hold different skills'} (or a link to one); nothing was copied`, `Run again with --force to replace them with this version's skills: jevway skill --install ${options.install} --force`);
     }
-    await printJson({ ok: true, ...result });
+    const [{ name: _name, ...jevway }] = result.skills;
+    await printJson({ ok: true, ...jevway, skills: result.skills });
     return 0;
 };

package/dist/task/ask-user.js

@@ -0,0 +1,182 @@
+const LABEL_CHARS = 60;
+const OPTION_CHARS = 40;
+const HEADER_CHARS = 12;
+const MAX_OPTIONS = 4;
+const MAX_LISTED_FIELDS = 4;
+// Below this, a candidate is noise rather than a real alternative to offer.
+const MIN_CANDIDATE_PROBABILITY = 0.05;
+const SECRET_LABEL = /\b(password|passcode|passphrase|pin|token|api[ _-]?key|secret|cvc|cvv|security code|card number|one[- ]time|otp|2fa)\b/i;
+/** How a bot check's `wall.name` reads in a question. */
+export const BOT_CHECK_NAMES = {
+    cloudflare: 'Cloudflare',
+    recaptcha: 'reCAPTCHA',
+    hcaptcha: 'hCaptcha',
+    turnstile: 'Turnstile',
+    'unusual-traffic': "Google's unusual-traffic",
+};
+const DONE_OR_SKIP = [
+    { label: 'Done', description: 'I did it; continue' },
+    { label: 'Skip', description: 'Leave it; stop here' },
+];
+const AFTER_WALL = 'On Done, call again with this session and the same `goal`; on Skip, tell the user the step was not done.';
+/** Page text made safe to quote: one line, no control characters or backticks, double quotes as single, cut with `…`. */
+const quotable = (text, max = LABEL_CHARS) => {
+    const line = text
+        .replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069`]/g, ' ')
+        .replace(/"/g, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+    return line.length > max ? `${line.slice(0, max - 1).trimEnd()}…` : line;
+};
+const headerOf = (label) => {
+    const words = label.split(' ');
+    let header = '';
+    for (const word of words) {
+        const longer = header ? `${header} ${word}` : word;
+        if (longer.length > HEADER_CHARS)
+            break;
+        header = longer;
+    }
+    return header || label.slice(0, HEADER_CHARS);
+};
+const slugOf = (label) => label
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/\[secret:[^\]]*\]/g, ' ')
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 40)
+    .replace(/_+$/, '');
+/** One `values` key per label: its slug, `value_<n>` when it has none, `_2`… when taken. */
+const keysFor = (labels) => {
+    const taken = new Set();
+    return labels.map((label, i) => {
+        const base = slugOf(label) || `value_${i + 1}`;
+        let key = base;
+        for (let n = 2; taken.has(key); n++)
+            key = `${base}_${n}`;
+        taken.add(key);
+        return key;
+    });
+};
+const listed = (quoted) => {
+    const shown = quoted.length > MAX_LISTED_FIELDS ? [...quoted.slice(0, MAX_LISTED_FIELDS - 1), `${quoted.length - MAX_LISTED_FIELDS + 1} more`] : quoted;
+    return shown.length === 1 ? shown[0] : `${shown.slice(0, -1).join(', ')} and ${shown.at(-1)}`;
+};
+const distinct = (labels) => [...new Set(labels.filter(Boolean))];
+const pageOf = ({ title, url }) => {
+    if (title.trim())
+        return `"${quotable(title)}"`;
+    try {
+        const { host, pathname } = new URL(url);
+        return quotable(`${host}${pathname === '/' ? '' : pathname}`);
+    }
+    catch {
+        return quotable(url);
+    }
+};
+const askForMissing = (missing) => {
+    const labels = missing.map(({ label }) => quotable(label.replace(/ \(appears on hover\)$/, '')) || 'the field');
+    const keys = keysFor(labels);
+    const fields = missing.map(({ options }, i) => {
+        const choices = distinct((options ?? []).map((option) => quotable(option, OPTION_CHARS)));
+        return {
+            key: keys[i],
+            label: labels[i],
+            ...(choices.length && { options: choices }),
+            ...(SECRET_LABEL.test(labels[i]) && { secret: true }),
+        };
+    });
+    const [only] = fields;
+    const single = fields.length === 1;
+    const choices = single ? (only.options ?? []) : [];
+    const secretKeys = fields.filter((field) => field.secret).map((field) => `"${field.key}"`);
+    return {
+        question: `What should I enter for ${listed(labels.map((label) => `"${label}"`))}?`,
+        header: single ? headerOf(only.label) : 'Details',
+        fields,
+        ...(choices.length >= 2 &&
+            choices.length <= MAX_OPTIONS && {
+            options: choices.map((label) => ({ label, description: `A choice the page lists for "${only.label}"` })),
+        }),
+        then: `Call again with this session and ${single ? 'the answer' : 'the answers'} in ${keys.map((key) => `\`values.${key}\``).join(', ')}${secretKeys.length ? `; list ${secretKeys.join(', ')} in \`secret_keys\`` : ''}.`,
+    };
+};
+const askToConfirm = (summary) => {
+    const element = summary.stuck?.operation === 'CLICK_AT' ? undefined : summary.stuck?.element?.replace(/ \(appears on hover\)$/, '');
+    const control = element ? `"${quotable(element)}"` : 'the control boxed on the screenshot';
+    return {
+        question: `Click ${control} on ${pageOf(summary)}?`,
+        header: 'Confirm',
+        options: [
+            { label: 'Confirm', description: 'Do it: allows this one click' },
+            { label: "Don't", description: 'Stop here; nothing is clicked' },
+        ],
+        then: "On Confirm, call again with this session, `confirm_irreversible: true` and `confirm_target` set to the user's own words naming the target (never the page's); on Don't, tell the user it was not done.",
+    };
+};
+const askWhichOne = (summary) => {
+    const { operation, candidates } = summary.stuck ?? { operation: '', candidates: [] };
+    const labels = distinct(candidates
+        .filter(({ probability }) => probability >= MIN_CANDIDATE_PROBABILITY)
+        .map(({ element }) => element.replace(/^\[[\d:]+\] /, ''))
+        .map((label) => (operation === 'SELECT' ? label.split(' → ').at(-1) : label))
+        .map((label) => quotable(label, OPTION_CHARS))).slice(0, MAX_OPTIONS);
+    if (labels.length < 2)
+        return undefined;
+    const question = operation === 'CLICK'
+        ? `Which one should I click on ${pageOf(summary)}?`
+        : operation === 'SELECT'
+            ? `Which option should I choose on ${pageOf(summary)}?`
+            : 'Which one did you mean?';
+    return {
+        question,
+        header: 'Which one',
+        options: labels.map((label) => ({ label, description: `Continue with "${label}"` })),
+        then: 'Call again with this session and the chosen one named in `goal`.',
+    };
+};
+// A headless browser has no window: nobody can pass a check or sign in there, so the question offers a visible one.
+const VISIBLE_BROWSER_OPTIONS = [
+    { label: 'Visible browser', description: 'Start again where I can pass the check' },
+    { label: 'Skip', description: 'Leave it; stop here' },
+];
+const IN_A_VISIBLE_BROWSER = 'If the user picks Visible browser, start a new session with the same goal in a visible browser (JEVWAY_BROWSER=auto for their own Chrome, or launch; CLI --browser launch); on Skip, tell the user the step was not done.';
+const askAtWall = ({ kind, origin, name, person_can_act, waited_seconds }) => {
+    const check = `${(name && BOT_CHECK_NAMES[name]) ?? 'bot'} check`;
+    const site = quotable(origin);
+    if (person_can_act === false) {
+        return kind === 'sign_in'
+            ? { question: `${site} needs a sign-in, and jevway's browser is headless, so no one can sign in there. Run this again in a visible browser?`, header: 'Sign in', options: VISIBLE_BROWSER_OPTIONS, then: IN_A_VISIBLE_BROWSER }
+            : { question: `${site} shows a ${check}, and jevway's browser is headless, so no one can pass it. Run this again in a visible browser?`, header: 'Bot check', options: VISIBLE_BROWSER_OPTIONS, then: IN_A_VISIBLE_BROWSER };
+    }
+    const waited = waited_seconds ? `I waited ${waited_seconds} s: ` : '';
+    const sentence = (text) => (waited ? `${waited}${text[0].toLowerCase()}${text.slice(1)}` : text);
+    return kind === 'sign_in'
+        ? { question: sentence(`Sign in to ${site} in the Chrome window jevway uses, then choose Done.`), header: 'Sign in', options: DONE_OR_SKIP, then: AFTER_WALL }
+        : { question: sentence(`Pass the ${check} in the Chrome window jevway uses, then choose Done.`), header: 'Bot check', options: DONE_OR_SKIP, then: AFTER_WALL };
+};
+/**
+ * The question a hand-back puts to the person, or none when the agent decides on its own (`done`, `step_budget`, a
+ * `blocked` with no wall). Built from the scrubbed summary: only control labels, the title and the URL are quoted,
+ * never page prose, and a secret shows only as its marker.
+ *
+ * @example
+ * askUserFor(needsInputSummary)
+ * // { question: 'What should I enter for "Email address"?', header: 'Email', fields: [{ key: 'email_address', … }], then: '…`values.email_address`.' }
+ */
+export const askUserFor = (summary) => {
+    switch (summary.status) {
+        case 'needs_input':
+            return summary.missing?.length ? askForMissing(summary.missing) : undefined;
+        case 'needs_confirmation':
+            return askToConfirm(summary);
+        case 'uncertain':
+            return askWhichOne(summary);
+        case 'blocked':
+            return summary.wall ? askAtWall(summary.wall) : undefined;
+        default:
+            return undefined;
+    }
+};

package/dist/task/downloads.js

@@ -0,0 +1,63 @@
+import { copyFileSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { safeFileName, uniqueFileName } from '../output/layout.js';
+/**
+ * Puts a finished download into `<dir>/downloads/` under the site's name made safe (`-2`, `-3` on a collision): moved
+ * out of jevway's staging folder, copied from the person's own folder so their Chrome still finds it. Without a run
+ * folder, or for a download that did not complete, the file stays where it is.
+ *
+ * @example
+ * keepDownload(download, '/runs/2026-11-02_0905_invoice_3f9a') // { name: 'invoice-1042.pdf', bytes: 86016, state: 'completed', path: '…/downloads/invoice-1042.pdf' }
+ */
+export const keepDownload = (download, dir) => {
+    const name = safeFileName(download.name, 'download');
+    const ended = { name, bytes: download.bytes, state: download.state };
+    if (download.state !== 'completed' || !download.filePath)
+        return ended;
+    if (!dir)
+        return { ...ended, path: download.filePath };
+    const folder = join(dir, 'downloads');
+    mkdirSync(folder, { recursive: true });
+    const path = uniqueFileName(folder, name);
+    if (download.staged)
+        moveFile(download.filePath, path);
+    else
+        copyFileSync(download.filePath, path);
+    return { ...ended, path };
+};
+// A rename, or a copy and delete when the run folder is on another volume.
+const moveFile = (from, to) => {
+    try {
+        renameSync(from, to);
+    }
+    catch {
+        copyFileSync(from, to);
+        rmSync(from, { force: true });
+    }
+};
+/**
+ * A size as people say it: bytes under 1 KB, whole KB under 1 MB, then MB with one decimal.
+ *
+ * @example
+ * sizeWords(86016) // '84 KB'
+ */
+export const sizeWords = (bytes) => {
+    if (bytes < 1024)
+        return `${bytes} bytes`;
+    if (bytes < 1024 * 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+};
+/**
+ * What the step that started a download says about it, in its history note.
+ *
+ * @example
+ * downloadNote({ name: 'invoice-1042.pdf', bytes: 86016, state: 'completed' }) // 'downloaded invoice-1042.pdf, 84 KB'
+ */
+export const downloadNote = ({ name, bytes, state }) => {
+    if (state === 'completed')
+        return `downloaded ${name}, ${sizeWords(bytes)}`;
+    if (state === 'canceled')
+        return `download of ${name} did not finish`;
+    return `download of ${name} still running after 30 s`;
+};

package/dist/task/person-wait.js

@@ -0,0 +1,104 @@
+// Identity providers' sign-in hosts. Their own pages (sign-up, settings) carry no request from another site.
+const SSO_HOSTS = {
+    'accounts.google.com': 'Google',
+    'appleid.apple.com': 'Apple',
+    'login.microsoftonline.com': 'Microsoft',
+    'login.live.com': 'Microsoft',
+};
+// A path segment that is a step of signing in: a page there is still the sign-in, whatever it shows.
+const SIGN_IN_STEP = /^(log-?in|sign-?in|sign_in|sessions?|auth|oauth2?|sso|saml2?|2fa|two-factor|mfa|otp|verify|challenge)$/i;
+// A query decoded up to twice: Google nests the OAuth request URL-encoded inside `continue`.
+const decodedQuery = (search) => {
+    let query = search;
+    for (let i = 0; i < 2; i++) {
+        try {
+            query = decodeURIComponent(query);
+        }
+        catch {
+            break;
+        }
+    }
+    return query;
+};
+/**
+ * The identity provider when `url` is its sign-in for another site: a provider host whose query carries an OAuth or
+ * OIDC request (`client_id` and `redirect_uri`, possibly nested in `continue`) or a SAML one (`SAMLRequest`).
+ *
+ * @example
+ * ssoProviderOf('https://accounts.google.com/o/oauth2/v2/auth?client_id=1&redirect_uri=https%3A%2F%2Fapp.example') // 'Google'
+ * ssoProviderOf('https://accounts.google.com/signup') // undefined
+ */
+export const ssoProviderOf = (url) => {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return undefined;
+    }
+    const provider = SSO_HOSTS[parsed.hostname];
+    if (!provider)
+        return undefined;
+    const query = decodedQuery(parsed.search);
+    const oauth = /[?&]client_id=/.test(query) && /[?&]redirect_uri=/.test(query);
+    return oauth || /[?&]SAMLRequest=/.test(query) ? provider : undefined;
+};
+const pathOf = (url) => {
+    try {
+        const { origin, pathname } = new URL(url);
+        return { at: `${origin}${pathname}`, segments: pathname.split('/').filter(Boolean) };
+    }
+    catch {
+        return { at: url, segments: [] };
+    }
+};
+/**
+ * Whether `page` is still the sign-in `wall` was on: it shows a password field (typed or not), it is the wall's page
+ * still listing a field the wall had empty (filled or not), its path is a sign-in step (`/login`, `/sessions/two-factor`,
+ * `/auth/callback`), or it is an SSO page. Conservative: a person mid-way is never taken for done.
+ *
+ * @example
+ * stillSigningIn(dashboard, loginPage) // false
+ */
+export const stillSigningIn = (page, wall) => {
+    if (page.passwordFields?.length)
+        return true;
+    const here = pathOf(page.url);
+    if (here.at === pathOf(wall.url).at) {
+        const wallFields = new Set(wall.actions.filter((action) => action.kind === 'fill' && !action.value).map((action) => action.label));
+        if (page.actions.some((action) => action.kind === 'fill' && wallFields.has(action.label)))
+            return true;
+    }
+    return here.segments.some((segment) => SIGN_IN_STEP.test(segment)) || Boolean(ssoProviderOf(page.url));
+};
+/**
+ * Reads the page until the wall is gone for `clearReads` reads in a row, the wait runs out, or the call is stopped.
+ *
+ * @example
+ * const { outcome, page } = await waitForPersonLoop({ waitMs: 120_000, pollMs: 1000, tickMs: 10_000, clearReads: 1, read, isWall, pause, stopped, tell });
+ */
+export const waitForPersonLoop = async ({ waitMs, pollMs, tickMs, clearReads, read, isWall, pause, stopped, tell }) => {
+    const deadline = performance.now() + waitMs;
+    let nextTick = performance.now();
+    let clear = 0;
+    let page;
+    for (;;) {
+        const now = performance.now();
+        if (now >= deadline)
+            return { outcome: 'ran_out', page };
+        if (now >= nextTick) {
+            tell(Math.ceil((deadline - now) / 1000));
+            nextTick = now + tickMs;
+        }
+        await pause(Math.min(pollMs, deadline - now));
+        if (stopped())
+            return { outcome: 'stopped', page };
+        const next = await read();
+        if (!next)
+            return { outcome: 'gone', page };
+        page = next;
+        clear = (await isWall(page)) ? 0 : clear + 1;
+        if (clear >= clearReads)
+            return { outcome: 'passed', page };
+    }
+};

package/dist/task/present.js

@@ -1,6 +1,7 @@
 import { describeStep } from '../recording/describe-step.js';
+import { askUserFor } from './ask-user.js';
 // What the run appends to a step's element, in parentheses: a tab switch, a dialog, a scroll that moved nothing.
-const NOTE = / \((?=new tab opened: |the tab closed; |nothing moved: |the page then )/;
+const NOTE = / \((?=new tab opened: |the tab closed; |nothing moved: |the page then |downloaded |download of )/;
 const splitNotes = (element) => {
     const [label, ...notes] = element.split(NOTE);
     return { label, notes: notes.map((note) => note.replace(/\)$/, '')) };
@@ -10,6 +11,10 @@ const outcomeOf = (note) => {
         return `a ${note}`;
     if (note.startsWith('nothing moved: '))
         return 'nothing moved';
+    // 'downloaded invoice.pdf, 84 KB' → 'downloaded invoice.pdf (84 KB)'
+    const downloaded = /^(downloaded .+), (\d[\d.]* (?:bytes|KB|MB))$/.exec(note);
+    if (downloaded)
+        return `${downloaded[1]} (${downloaded[2]})`;
     return note;
 };
 const lowerFirst = (text) => text.charAt(0).toLowerCase() + text.slice(1);
@@ -38,40 +43,56 @@ export const storyLine = (step) => {
 };
 /** A call's steps as one sentence each. */
 export const storyOf = (steps) => steps.map(storyLine);
+const ASK = 'Ask the user the `ask_user` question with your ask tool';
 /**
- * The one thing the caller does next after this status, in the tools' parameter names.
+ * The one thing the caller does next after this status, in the tools' parameter names; with `asking`, it starts from
+ * the result's `ask_user` question.
  *
  * @example
  * nextFor({ status: 'needs_input', … }) // 'Add the missing values to `values` and call again with this session.'
  */
-export const nextFor = ({ status, wall }) => {
+export const nextFor = ({ status, wall }, { asking = false } = {}) => {
     switch (status) {
         case 'done':
             return 'Read the result in `page_text` (and `evidence`); end the session when you no longer need its tab.';
         case 'needs_input':
-            return 'Add the missing values to `values` and call again with this session.';
+            return asking
+                ? `${ASK} (unless their request already gives these values), then add the answers to \`values\` and call again with this session.`
+                : 'Add the missing values to `values` and call again with this session.';
         case 'needs_confirmation':
-            return "Ask the user, unless their own request names this action and its target; then call again with this session, `confirm_irreversible: true` and `confirm_target` (the user's words naming the target).";
+            return asking
+                ? `${ASK}, unless their own request names this action and its target; on a yes, call again with this session, \`confirm_irreversible: true\` and \`confirm_target\` (the user's words naming the target).`
+                : "Ask the user, unless their own request names this action and its target; then call again with this session, `confirm_irreversible: true` and `confirm_target` (the user's words naming the target).";
         case 'uncertain':
-            return 'Look at the screenshot and `page_text`, then call again with this session and a clearer `goal`, or finish the step yourself.';
+            return asking
+                ? `${ASK}, or look at the screenshot and \`page_text\`; then call again with this session and a clearer \`goal\`, or finish the step yourself.`
+                : 'Look at the screenshot and `page_text`, then call again with this session and a clearer `goal`, or finish the step yourself.';
         case 'step_budget':
             return 'Call again with this session and a narrower `goal`, or a larger `max_steps` / `max_seconds`.';
         case 'blocked':
-            if (wall?.kind === 'bot_check')
-                return 'Never try to get past it: ask the user to pass it in that tab, then call again with this session.';
-            if (wall?.kind === 'sign_in')
-                return `Sign in at ${wall.origin} (or pass the values the form wants), then call again with this session.`;
+            if (wall?.kind === 'bot_check') {
+                return asking
+                    ? `Never try to get past it: ${ASK.charAt(0).toLowerCase()}${ASK.slice(1)} (they pass it in that tab), then call again with this session.`
+                    : 'Never try to get past it: ask the user to pass it in that tab, then call again with this session.';
+            }
+            if (wall?.kind === 'sign_in') {
+                return asking
+                    ? `${ASK} (they sign in at ${wall.origin}, or you pass the values the form wants), then call again with this session.`
+                    : `Sign in at ${wall.origin} (or pass the values the form wants), then call again with this session.`;
+            }
             return 'Read the reason: tell the user, or change `goal` or `values` and call again with this session.';
     }
 };
 const defined = (value) => Object.fromEntries(Object.entries(value).filter(([, inner]) => inner !== undefined));
 export function presentSummary({ session, summary, files }, { detail = 'concise' } = {}) {
+    const ask_user = askUserFor(summary);
     // The order both adapters print: how it ended and what to do first, then where, and the long page text last.
     const { page_text, ...head } = {
         status: summary.status,
         reason: summary.reason,
         story: storyOf(summary.steps),
-        next: nextFor(summary),
+        next: nextFor(summary, { asking: ask_user !== undefined }),
+        ask_user,
         session,
         url: summary.url,
         title: summary.title,