@beryl-so/cli 0.11.1 → 0.17.0

package/dist/commands/tests.js

@@ -1,10 +1,68 @@
 import fs from "node:fs";
-import { UsageError } from "../errors.js";
+import { CliError, UsageError } from "../errors.js";
+import { ApiError } from "../http.js";
 import { lintPlan } from "../lint.js";
-import { table } from "../output.js";
+import { buildImportForm, executeLocalSpec, toRunEntry, } from "../local-exec.js";
+import { PlaywrightMissingError } from "../local-run.js";
+import { dim, green, red, table, yellow } from "../output.js";
+import { confirmInstall, installPlaywright } from "../playwright-install.js";
 import { ACTION_PLAN_SCHEMA } from "../schema.generated.js";
 import { arg, argList, flagBool, flagNum, flagStr, projectPath, readJsonFlag } from "./util.js";
 const testPath = (ws, p, id) => `${projectPath(ws, p)}/tests/${id}`;
+// A duplicate-title 409 after a green replay is idempotent when the existing row
+// holds the same plan (a retry after a lost response) — success, not an error.
+// A different plan under the same title is a real conflict.
+function createConflictResult(err, planHash) {
+    if (!(err instanceof ApiError) || err.status !== 409)
+        return undefined;
+    const detail = err.detail;
+    if (typeof detail !== "object" || detail === null || detail.code !== "duplicate_title")
+        return undefined;
+    if (detail.existing_plan_hash && detail.existing_plan_hash === planHash) {
+        return {
+            data: { id: detail.existing_test_id, already_existed: true },
+            human: green(`✓ Already banked as ${detail.existing_test_id} (same plan) — nothing to do.`),
+        };
+    }
+    return {
+        human: (detail.message ?? "A test with this title already exists.") +
+            "\nIts plan differs from yours — use `tests set-plan` to update it, or pick a new title.",
+        exitCode: 1,
+    };
+}
+// The server transcodes a failure screenshot to WebP to fit it under the payload cap,
+// so the format is not knowable up front — sniff it off the decoded magic bytes rather
+// than asserting PNG.
+export function sniffImageMime(b64) {
+    const head = Buffer.from(b64.slice(0, 24), "base64");
+    if (head.subarray(0, 4).toString("latin1") === "RIFF" && head.subarray(8, 12).toString("latin1") === "WEBP") {
+        return "image/webp";
+    }
+    if (head.subarray(0, 3).toString("hex") === "ffd8ff")
+        return "image/jpeg";
+    return "image/png";
+}
+// A verify-failure 422 carries evidence (a11y page state + failure screenshot).
+// Returned as a CommandResult rather than thrown: a thrown error is text-only in
+// the MCP adapter, and the screenshot only reaches the agent as image content.
+function verifyFailureResult(err) {
+    if (!(err instanceof ApiError) || err.status !== 422)
+        return undefined;
+    const detail = err.detail;
+    if (typeof detail !== "object" || detail === null || !detail.message)
+        return undefined;
+    const parts = [detail.message];
+    if (detail.error_context) {
+        parts.push("", "----- Page state at failure (accessibility snapshot) -----", detail.error_context);
+    }
+    return {
+        human: parts.join("\n"),
+        images: detail.screenshot_b64
+            ? [{ data: detail.screenshot_b64, mimeType: sniffImageMime(detail.screenshot_b64) }]
+            : undefined,
+        exitCode: 1,
+    };
+}
 // The concise human table for `tests list` — the full TestResponse is a 24-column
 // firehose of internal ids that wraps unreadably in a normal terminal. `--wide`
 // (and `--json`) still expose every field.
@@ -94,10 +152,21 @@ export const testCommands = [
         name: "tests create",
         summary: "Create a test case from a JSON action plan — for tests authored locally, e.g. by your coding agent",
         description: "The plan is a JSON object whose steps are {action, selector, url, value, ...}: the first " +
-            "EXECUTED step must be a goto, and at least one step must be an expect. By default the plan " +
-            "is verified in a real browser before the test is accepted. Optional `before` and `after` " +
-            "arrays hold setup and teardown steps: `after` runs even when a main step fails, which is " +
-            "how a create/update/delete test cleans up the record it made on the runs that go red.",
+            "EXECUTED step must be a goto, and at least one step must be an expect. Before anything is " +
+            "banked, the plan is proven by replaying it in a browser ON YOUR MACHINE with your local " +
+            "@playwright/test: the server renders the spec (`tests/compile`), the CLI runs it — minting " +
+            "a run inbox for await_email steps and resolving the saved login exactly as a cloud run " +
+            "would — and only a green replay creates the test (bound to the replayed plan by its hash). " +
+            "This holds over MCP too: the replay runs on the machine hosting the MCP server, never on " +
+            "Beryl's; if @playwright/test is missing there the tool returns the install commands (on a " +
+            "terminal the CLI offers to install it). " +
+            "A red replay banks NOTHING: the failure evidence comes back (over MCP the screenshot is " +
+            "image content), you fix the plan file and re-run. The proving run is imported as the " +
+            "test's first run (--no-sync to skip). A plan that signs in with a captured session cannot " +
+            "replay locally (the session never leaves Beryl's cloud) — it falls back to server-side " +
+            "verification automatically. Optional `before` and `after` arrays hold setup and teardown " +
+            "steps: `after` runs even when a main step fails, which is how a create/update/delete test " +
+            "cleans up the record it made on the runs that go red.",
         scope: "project",
         flags: [
             { name: "title", type: "string", required: true, description: "Title for the new test" },
@@ -112,25 +181,214 @@ export const testCommands = [
             {
                 name: "no-verify",
                 type: "boolean",
-                description: "Skip the compile-time browser/AI verification — trust the authored plan as-is",
+                description: "Skip verification entirely — bank the authored plan as-is, unproven",
+            },
+            {
+                name: "url-override",
+                type: "string",
+                description: "Replay against this base URL instead of the environment's (e.g. http://localhost:3000). " +
+                    "The banked test is then unproven against its real environment — the CLI says so.",
+            },
+            { name: "env", type: "string", description: "Environment id to compile and prove against" },
+            {
+                name: "sync",
+                type: "boolean",
+                default: true,
+                description: "Import the green proving replay as the test's first run (--no-sync: bank only, " +
+                    "no run recorded)",
+            },
+            {
+                name: "dir",
+                type: "string",
+                description: "Keep the rendered spec, artifacts, and JSON report under this directory",
             },
         ],
         examples: [
             'beryl tests create --title "Checkout happy path" --file plan.json',
             'beryl tests create --title "Checkout happy path" --file plan.json --description "Proves a shopper can buy a product: after paying, an order-confirmation page with an order number appears."',
+            'beryl tests create --title "Checkout happy path" --file plan.json --url-override http://localhost:3000',
         ],
         async run(ctx, input) {
             const title = flagStr(input, "title");
             if (!title)
                 throw new UsageError("--title is required");
             const { workspaceId, projectId } = await ctx.requireProject(input);
+            const plan = readJsonFlag(input, "file");
+            const description = flagStr(input, "description");
+            const urlOverride = flagStr(input, "url-override");
+            const env = flagStr(input, "env");
+            const sync = input.flags.sync !== false;
+            const bank = (extra) => ctx.client.post(`${projectPath(workspaceId, projectId)}/tests`, {
+                title,
+                plan,
+                description,
+                ...extra,
+            });
+            if (flagBool(input, "no-verify")) {
+                const created = await bank({ verify: false });
+                return {
+                    data: created,
+                    human: yellow(`Banked UNPROVEN (--no-verify): ${created.id}`),
+                };
+            }
+            const compile = () => ctx.client.post(`${projectPath(workspaceId, projectId)}/tests/compile`, {
+                plan,
+                title,
+                base_url: urlOverride,
+                environment_id: env,
+                // The proof replay becomes the test's first run, so capture the filmstrip
+                // frames its replay view needs.
+                frames: sync ? true : undefined,
+            });
+            let compiled = await compile();
+            // A captured session lives encrypted in Beryl's cloud and is never handed to
+            // this machine — the cloud is the only place this plan can be proven.
+            if (compiled.requires_auth) {
+                ctx.err(yellow("! This plan signs in with a captured session, so it can only be verified " +
+                    "in Beryl's cloud — verifying server-side instead."));
+                try {
+                    return { data: await bank({ verify: true, plan_hash: compiled.plan_hash }) };
+                }
+                catch (err) {
+                    const failure = verifyFailureResult(err);
+                    if (failure)
+                        return failure;
+                    const conflict = createConflictResult(err, compiled.plan_hash);
+                    if (conflict)
+                        return conflict;
+                    throw err;
+                }
+            }
+            if (compiled.login_config_error)
+                throw new CliError(compiled.login_config_error);
+            let loginPassword;
+            if (compiled.uses_login_password) {
+                try {
+                    const secret = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/config/secrets/LOGIN_PASSWORD/value`, { environment_id: env }));
+                    loginPassword = secret.value;
+                }
+                catch (err) {
+                    throw new CliError("Could not reveal the LOGIN_PASSWORD secret for the saved login: " +
+                        (err instanceof Error ? err.message : String(err)));
+                }
+            }
+            const specOf = (content) => ({
+                id: "local-verify",
+                title,
+                content,
+                requiresAuth: false,
+                usesEmail: /__vmInbox\(|__vmAwaitEmail\(/.test(content),
+                usesLoginPassword: compiled.uses_login_password,
+            });
+            const startedAt = new Date().toISOString();
+            const attempts = 1 + Math.max(0, compiled.policy.error_retries);
+            let outcome;
+            let runError;
+            let installOffered = false;
+            for (let attempt = 1; attempt <= attempts; attempt++) {
+                if (attempt > 1) {
+                    // Fresh render per attempt: the errored attempt may already have consumed
+                    // the {{unique}}/inbox handles its spec minted — replaying the same spec
+                    // would collide on exactly the uniqueness those handles exist to dodge.
+                    ctx.err(dim(`Replay errored — recompiling and retrying (${attempt}/${attempts})…`));
+                    compiled = await compile();
+                }
+                ctx.err(dim(`Replaying "${title}" locally before banking…`));
+                try {
+                    ({ outcome, runError } = await executeLocalSpec({ client: ctx.client, workspaceId, projectId }, {
+                        spec: specOf(compiled.content),
+                        dir: flagStr(input, "dir"),
+                        harvest: true,
+                        loginPassword,
+                        onEvent: (line) => ctx.err(dim(line)),
+                    }));
+                }
+                catch (err) {
+                    if (err instanceof PlaywrightMissingError) {
+                        // On a TTY offer the install once and redo this attempt; over MCP or a
+                        // pipe the hint is the answer.
+                        if (ctx.interactive && !installOffered) {
+                            installOffered = true;
+                            if (await confirmInstall(ctx.prompt)) {
+                                await installPlaywright(process.cwd(), (line) => ctx.err(dim(line)));
+                                attempt -= 1;
+                                continue;
+                            }
+                        }
+                        throw new CliError(err.message);
+                    }
+                    throw err;
+                }
+                // A completed replay — green or red — is a verdict; only an errored one
+                // (the spec never ran) earns a retry.
+                if (outcome)
+                    break;
+            }
+            if (!outcome) {
+                return {
+                    data: { banked: false, verified: false, error: runError },
+                    human: red(`Replay errored after ${attempts} attempt(s) — nothing was banked.`) +
+                        `\n${runError ?? "the spec did not run"}` +
+                        `\nFix the environment (or retry), then re-run \`beryl tests create\`.`,
+                    exitCode: 1,
+                };
+            }
+            const result = outcome.results[0];
+            if (outcome.failed > 0 || outcome.passed === 0) {
+                const shot = outcome.harvested?.screenshot;
+                const parts = [
+                    `Plan failed its local replay — nothing was banked.`,
+                    ...(result?.error ? ["", result.error] : []),
+                    "",
+                    "Fix the plan file and re-run `beryl tests create`. The replay artifacts " +
+                        (flagStr(input, "dir")
+                            ? `are under ${outcome.directory}.`
+                            : "can be kept with --dir."),
+                ];
+                return {
+                    data: { banked: false, verified: false, error: result?.error },
+                    human: parts.join("\n"),
+                    images: shot
+                        ? [{ data: shot.toString("base64"), mimeType: "image/png" }]
+                        : undefined,
+                    exitCode: 1,
+                };
+            }
+            let created;
+            try {
+                created = await bank({ verify: false, plan_hash: compiled.plan_hash });
+            }
+            catch (err) {
+                const conflict = createConflictResult(err, compiled.plan_hash);
+                if (conflict)
+                    return conflict;
+                throw err;
+            }
+            let runId;
+            if (sync) {
+                const entry = toRunEntry({ ...specOf(compiled.content), id: String(created.id) }, outcome, undefined, startedAt, 0, loginPassword);
+                const imported = (await ctx.client.request("POST", `${projectPath(workspaceId, projectId)}/runs/import`, {
+                    form: buildImportForm([entry], {
+                        environmentId: env,
+                        targetUrlOverride: urlOverride,
+                        // The proof replay is authoring machinery, not a run the customer
+                        // asked for — it must never email/Slack "your report is ready".
+                        notifications: false,
+                        startedAt,
+                        completedAt: new Date().toISOString(),
+                        onNote: (line) => ctx.err(yellow(`! ${line}`)),
+                    }),
+                }));
+                runId = imported.id;
+            }
+            if (urlOverride) {
+                ctx.err(yellow(`! The proof ran against ${urlOverride}, not the environment's root URL — ` +
+                    "the banked test is unproven against its real target until a run there passes."));
+            }
             return {
-                data: await ctx.client.post(`${projectPath(workspaceId, projectId)}/tests`, {
-                    title,
-                    plan: readJsonFlag(input, "file"),
-                    verify: !flagBool(input, "no-verify"),
-                    description: flagStr(input, "description"),
-                }),
+                data: { ...created, ...(runId ? { proof_run_id: runId } : {}) },
+                human: green(`✓ Replay passed locally — banked as ${created.id}`) +
+                    (runId ? `\nProving run imported: \`beryl runs get ${runId}\`` : ""),
             };
         },
     },
@@ -227,8 +485,14 @@ export const testCommands = [
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
+            const res = (await ctx.client.post(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/plan/recompile`, { json_plan: readJsonFlag(input, "file") }));
+            // Base64 in the JSON output would flood the caller's context — hand the
+            // failure screenshot over as image content instead.
+            const shot = typeof res.screenshot_b64 === "string" ? res.screenshot_b64 : undefined;
+            delete res.screenshot_b64;
             return {
-                data: await ctx.client.post(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/plan/recompile`, { json_plan: readJsonFlag(input, "file") }),
+                data: res,
+                images: shot ? [{ data: shot, mimeType: sniffImageMime(shot) }] : undefined,
             };
         },
     },
@@ -342,11 +606,36 @@ export const testCommands = [
     },
     {
         name: "tests script",
-        summary: "Print the rendered Playwright spec for a test",
+        summary: "Print the rendered Playwright spec for a test (or an unbanked plan file)",
+        description: "With a test id, fetches the banked test's rendered .spec.ts. With --file, compiles a " +
+            "plan JSON that has NOT been banked yet — the same render `tests create` proves locally — " +
+            "so you can inspect exactly what would run before creating anything.",
         scope: "project",
-        args: [{ name: "test-id", description: "Test id", required: true }],
+        args: [{ name: "test-id", description: "Test id (omit when passing --file)" }],
+        flags: [
+            { name: "file", type: "string", description: "Compile this plan JSON file instead of a banked test" },
+            {
+                name: "url-override",
+                type: "string",
+                description: "With --file: resolve relative gotos against this base URL",
+            },
+            { name: "env", type: "string", description: "With --file: environment id to render against" },
+        ],
+        examples: ["beryl tests script 4f…", "beryl tests script --file plan.json"],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
+            const id = input.args["test-id"];
+            const file = flagStr(input, "file");
+            if (Boolean(id) === Boolean(file))
+                throw new UsageError("Pass exactly one of <test-id> or --file");
+            if (file) {
+                const data = (await ctx.client.post(`${projectPath(workspaceId, projectId)}/tests/compile`, {
+                    plan: readJsonFlag(input, "file"),
+                    base_url: flagStr(input, "url-override"),
+                    environment_id: flagStr(input, "env"),
+                }));
+                return { data: data, human: data.content };
+            }
             const data = (await ctx.client.get(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/script`));
             const script = typeof data === "string" ? data : (data.script ?? data.content ?? data);
             return { data, human: typeof script === "string" ? script : JSON.stringify(data, null, 2) };

package/dist/context.js

@@ -1,6 +1,23 @@
 import readline from "node:readline/promises";
 import { CliError, UsageError } from "./errors.js";
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// On a terminal, an ambiguous workspace/project becomes a numbered pick instead of an
+// error the user answers by retyping the same command with a flag. Non-interactive
+// callers (CI, MCP) still get the actionable UsageError — a prompt there would hang.
+async function pickOne(ctx, candidates, kind, usageMessage) {
+    if (!ctx.interactive)
+        throw new UsageError(usageMessage);
+    ctx.err(`Multiple ${kind}s:`);
+    candidates.forEach((c, i) => {
+        ctx.err(`  ${i + 1}. ${c.name ?? c.root_url ?? c.id}  (${c.id})`);
+    });
+    const answer = await ctx.prompt(`Which ${kind}? [1-${candidates.length}] `);
+    const n = Number.parseInt(answer, 10);
+    if (!Number.isInteger(n) || n < 1 || n > candidates.length) {
+        throw new UsageError(usageMessage);
+    }
+    return candidates[n - 1].id;
+}
 function matchByName(candidates, value, kind) {
     const lower = value.toLowerCase();
     const matches = candidates.filter((c) => c.name?.toLowerCase() === lower ||
@@ -65,13 +82,27 @@ export function createContext(options) {
                 throw new CliError("You have no workspaces yet — create one with `beryl workspaces create`");
             }
             else {
-                throw new UsageError("Multiple workspaces — pass --workspace <id|name> or set BERYL_WORKSPACE:\n" +
+                workspaceCache = await pickOne(ctx, workspaces, "workspace", "Multiple workspaces — pass --workspace <id|name> or set BERYL_WORKSPACE:\n" +
                     workspaces.map((w) => `  ${w.id}  ${w.name ?? ""}`).join("\n"));
             }
             return workspaceCache;
         },
         async requireProject(input) {
             const requested = input.flags.project ?? config.project;
+            // A project id is globally unique, so it alone must be enough: when no workspace
+            // is flagged/configured, find the owner instead of demanding --workspace.
+            const requestedWorkspace = input.flags.workspace ?? config.workspace;
+            if (requested && UUID_RE.test(requested) && !requestedWorkspace && !workspaceCache) {
+                const workspaces = (await client.get("/workspaces/"));
+                for (const w of workspaces) {
+                    const projects = (await client.get(`/workspaces/${w.id}/projects`));
+                    if (projects.some((p) => p.id === requested)) {
+                        workspaceCache = w.id;
+                        return { workspaceId: w.id, projectId: requested };
+                    }
+                }
+                throw new CliError(`No project ${requested} found in any of your workspaces`);
+            }
             const workspaceId = await ctx.requireWorkspace(input);
             if (requested && UUID_RE.test(requested))
                 return { workspaceId, projectId: requested };
@@ -90,7 +121,7 @@ export function createContext(options) {
                     "`beryl projects create <url>` (add --no-explore to author tests yourself).");
             }
             else {
-                throw new UsageError("Multiple projects — pass --project <id|name|url> or set BERYL_PROJECT:\n" +
+                projectId = await pickOne(ctx, projects, "project", "Multiple projects — pass --project <id|name|url> or set BERYL_PROJECT:\n" +
                     projects.map((p) => `  ${p.id}  ${p.name ?? p.root_url ?? ""}`).join("\n"));
             }
             projectCache = { workspaceId, projectId };

package/dist/email-extract.js

@@ -0,0 +1,99 @@
+import vm from "node:vm";
+// A labelled digit run ("your code is 654321") beats the bare fenced pattern, because a
+// real sign-in mail is full of innocent 4-8 digit runs — "© 2026", a support number —
+// and the bare fence would happily return the first of them.
+const CODE_PATTERN = /(?<!\d)(\d{4,8})(?!\d)/;
+const LABELLED_CODE_PATTERN = /(?:verification|security|one[\s-]?time|login|sign[\s-]?in|access|confirmation)?\s*(?:code|otp|passcode|pin)\b[^0-9]{0,20}(?<!\d)(\d{4,8})(?!\d)/i;
+const LINK_PATTERN = /https:\/\/[^\s"'<>)\]]+/;
+// An anchor's href is the click target in an HTML mail; a bare URL scan over raw markup
+// would return a CSS background or tracking pixel instead.
+const HREF_PATTERN = /<a\b[^>]*\bhref\s*=\s*["']?(https:\/\/[^\s"'>]+)/gi;
+// Footer furniture a sign-in mail carries but nobody means.
+const LINK_NOISE = [
+    "unsubscribe",
+    "/privacy",
+    "/terms",
+    "list-manage",
+    "mailchimp",
+    "sendgrid.net",
+    "/track/",
+    "/wf/open",
+    "twitter.com",
+    "facebook.com",
+    "linkedin.com",
+];
+// Matches the server's EMAIL_PATTERN_MAX_BODY_CHARS bound: backtracking cost scales with
+// haystack length, and no real sign-in code lives past the first few KB of an email.
+const PATTERN_MAX_BODY_CHARS = 20_000;
+const PATTERN_TIMEOUT_MS = 2_000;
+// An author-supplied regex against a sender-supplied body is the textbook ReDoS setup,
+// and native RegExp cannot be interrupted once it starts. Running the match inside a vm
+// context gives it a real wall-clock deadline — V8 services the timeout interrupt while
+// backtracking — matching the server's regex-engine timeout, whatever the pattern is.
+function matchWithDeadline(haystack, pattern) {
+    try {
+        return vm.runInNewContext("haystack.match(new RegExp(pattern))", { haystack, pattern }, { timeout: PATTERN_TIMEOUT_MS });
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ERR_SCRIPT_EXECUTION_TIMEOUT" || /timed out/i.test(String(err))) {
+            throw new Error("the extract_pattern took too long to match this email — it backtracks " +
+                "explosively (an ambiguous quantifier like (a+)+ or (a|a)+ does this). " +
+                "Rewrite it to match unambiguously.");
+        }
+        throw err;
+    }
+}
+export function visibleText(html) {
+    return html
+        .replace(/<(style|script|head)\b[\s\S]*?<\/\1>/gi, " ")
+        .replace(/<[^>]+>/g, " ");
+}
+function bodyOf(email) {
+    if (email.body_text)
+        return email.body_text;
+    if (email.body_html)
+        return visibleText(email.body_html);
+    return "";
+}
+export function extractCode(email) {
+    for (const pattern of [LABELLED_CODE_PATTERN, CODE_PATTERN]) {
+        for (const text of [bodyOf(email), email.subject ?? ""]) {
+            const match = text.match(pattern);
+            if (match)
+                return match[1];
+        }
+    }
+    return null;
+}
+export function extractLink(email) {
+    const html = email.body_html ?? "";
+    const hrefs = [...html.matchAll(HREF_PATTERN)].map((m) => m[1]);
+    const candidates = hrefs.length > 0 ? hrefs : (bodyOf(email).match(LINK_PATTERN) ?? []);
+    for (const url of candidates) {
+        if (!LINK_NOISE.some((noise) => url.toLowerCase().includes(noise)))
+            return url;
+    }
+    if (candidates.length > 0) {
+        throw new Error("the email's only links look like footer/unsubscribe links, not a sign-in link");
+    }
+    throw new Error("the email arrived but carried no https link to follow");
+}
+export function extractValue(email, extract, pattern) {
+    if (extract === "link")
+        return extractLink(email);
+    const body = bodyOf(email);
+    if (extract === "pattern") {
+        if (!pattern)
+            throw new Error("extract=pattern needs an extract_pattern");
+        const match = matchWithDeadline(body.slice(0, PATTERN_MAX_BODY_CHARS), pattern);
+        if (!match) {
+            throw new Error("the email arrived but nothing in it matched the extract_pattern");
+        }
+        return match[1] ?? match[0];
+    }
+    const code = extractCode(email);
+    if (!code)
+        throw new Error("the email arrived but carried no 4-8 digit sign-in code");
+    return code;
+}

package/dist/email-pump.js

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import { extractValue } from "./email-extract.js";
+import { ApiError } from "./http.js";
+const SIDECAR_POLL_MS = 500;
+// The server caps one blocking wait at 50s; stay under it and loop.
+const SERVER_WAIT_MAX_S = 45;
+const DEFAULT_WAIT_S = 30;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export function startEmailPump(opts) {
+    let stopped = false;
+    const served = new Set();
+    const consumed = new Set();
+    let since = opts.since;
+    const fetchLatest = async (req, timeoutS) => {
+        try {
+            return (await opts.client.get(`/workspaces/${opts.workspaceId}/inboxes/${opts.inboxId}/emails/latest`, {
+                timeout_s: timeoutS,
+                since,
+                from_contains: req.from_contains,
+                subject_contains: req.subject_contains,
+            }));
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.status === 404)
+                return null;
+            throw err;
+        }
+    };
+    const resolveRequest = async (req) => {
+        // Wait exactly wait_s, like the cloud resolver — the spec's own grace window
+        // covers this side's poll tick + round trip.
+        const waitS = Math.max(1, Number(req.wait_s) || DEFAULT_WAIT_S);
+        const deadline = Date.now() + waitS * 1000;
+        while (!stopped && Date.now() < deadline) {
+            const remainingS = Math.ceil((deadline - Date.now()) / 1000);
+            const email = await fetchLatest(req, Math.min(SERVER_WAIT_MAX_S, remainingS));
+            if (email === null)
+                continue;
+            if (consumed.has(email.id)) {
+                // The fence rides received_at, which comes from the sender's Date header — a
+                // lagging mailer clock can re-serve a consumed mail. Nudge past it instead.
+                since = new Date(new Date(email.received_at).getTime() + 1000).toISOString();
+                continue;
+            }
+            consumed.add(email.id);
+            since = email.received_at;
+            opts.onEvent?.(`await_email: matched "${email.subject ?? "(no subject)"}"`);
+            return extractValue(email, String(req.extract ?? "code"), req.pattern);
+        }
+        throw new Error(`no matching email arrived in the run inbox within ${waitS}s`);
+    };
+    const writeResponse = (response) => {
+        let box = {};
+        try {
+            box = JSON.parse(fs.readFileSync(opts.sidecarPath, "utf8"));
+        }
+        catch {
+            // keep at least the response readable
+        }
+        box.response = response;
+        // Write-then-rename so the spec never reads a half-written response.
+        const tmp = `${opts.sidecarPath}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(box), "utf8");
+        fs.renameSync(tmp, opts.sidecarPath);
+    };
+    void (async () => {
+        while (!stopped) {
+            await sleep(SIDECAR_POLL_MS);
+            let box;
+            try {
+                box = JSON.parse(fs.readFileSync(opts.sidecarPath, "utf8"));
+            }
+            catch {
+                continue; // torn read or not yet written — the spec re-polls
+            }
+            const req = box.request;
+            if (!req || typeof req.id !== "string" || served.has(req.id))
+                continue;
+            served.add(req.id);
+            const response = { id: req.id };
+            try {
+                response.value = await resolveRequest(req);
+            }
+            catch (err) {
+                response.error = err instanceof Error ? err.message : String(err);
+            }
+            if (stopped)
+                return;
+            try {
+                writeResponse(response);
+            }
+            catch {
+                // run dir vanished mid-write — the run is over anyway
+            }
+        }
+    })();
+    return {
+        stop: () => {
+            stopped = true;
+        },
+    };
+}