@flowriki/agent 0.1.0-beta.27 → 0.1.0-beta.29

package/dist/{chunk-6FCAGGGY.js → chunk-3SU3RBVY.js}

@@ -6,7 +6,7 @@ import os from "os";
 import path from "path";
 import { createRequire } from "module";
 import { spawnSync } from "child_process";
-var AGENT_VERSION = "0.1.0-beta.27";
+var AGENT_VERSION = "0.1.0-beta.29";
 async function prepareBrowsers() {
   if (browsersReady()) {
     return { ok: true, already: true, message: "chromium is already installed" };
@@ -133,9 +133,9 @@ function forgetConnection(service, env = process.env) {
   fs3.renameSync(temporary, file);
   return true;
 }
-var fingerprint = (secret) => crypto2.createHash("sha256").update(secret).digest("hex").slice(0, 12);
+var fingerprint = (secret2) => crypto2.createHash("sha256").update(secret2).digest("hex").slice(0, 12);
 
-// ../contracts/dist/chunk-MQTBBCDK.js
+// ../contracts/dist/chunk-UFMRFPRU.js
 import { z } from "zod";
 var PROTOCOL_VERSION = 1;
 var PAIRING_CODE_TTL_MS = 5 * 60 * 1e3;
@@ -293,7 +293,10 @@ var AGENT_FEATURES = /* @__PURE__ */ new Set([
   "actors.v1",
   /** Replaying other flows' steps before a recording starts capturing, so a
    *  flow can be recorded from where its prerequisites leave the browser. */
-  "prerequisites.v1"
+  "prerequisites.v1",
+  /** Running a helper — an email code, an authenticator, a text, an API
+   *  call — as a step, from the helpers a run is sent. */
+  "helpers.v1"
 ]);
 var AgentMessageSchema = z.discriminatedUnion("type", [
   AckSchema,
@@ -461,7 +464,7 @@ import path7 from "path";
 // ../engine-playwright/dist/index.js
 import path3 from "path";
 
-// ../test-model/dist/chunk-TSFRTYLG.js
+// ../test-model/dist/chunk-GALEMMJW.js
 import { z as z3 } from "zod";
 var LocatorOverrideSchema = z3.object({
   strategy: z3.enum(["css", "xpath", "id", "testId", "text", "label", "placeholder", "altText", "title"]),
@@ -667,7 +670,7 @@ var DialogAnswerSchema = z3.object({
 }).strict();
 var RecordedStepSchema = RecordedTargetSchema.extend({
   id: z3.string().min(1),
-  type: z3.enum(["fill", "select", "click", "dblclick", "rightclick", "drag", "check", "press", "hover", "upload", "scroll", "back", "forward", "navigate", "closePage", "unsupported", "setRange", "assert", "signIn", "signOut", "useActor", "resetActor", "capture"]),
+  type: z3.enum(["fill", "select", "click", "dblclick", "rightclick", "drag", "check", "press", "hover", "upload", "scroll", "back", "forward", "navigate", "closePage", "unsupported", "setRange", "assert", "signIn", "signOut", "useActor", "resetActor", "capture", "useHelper"]),
   scope: z3.string(),
   value: z3.string(),
   secret: z3.boolean(),
@@ -743,7 +746,21 @@ var RecordedStepSchema = RecordedTargetSchema.extend({
    * participants cost a login each time, which is the cost this removes. */
   actorId: z3.string().optional(),
   navigationBase: z3.enum(["page", "application"]).optional(),
-  capture: z3.object({ name: z3.string().regex(/^[a-zA-Z][a-zA-Z0-9_]*$/), source: z3.enum(["text", "value", "url"]) }).strict().optional()
+  capture: z3.object({ name: z3.string().regex(/^[a-zA-Z][a-zA-Z0-9_]*$/), source: z3.enum(["text", "value", "url"]) }).strict().optional(),
+  /** WHICH HELPER, for `useHelper`: the email code, the authenticator, the
+   *  text, the API call — set up on the Helpers screen and referred to here by
+   *  id, never copied, so fixing a helper fixes every test using it.
+   *
+   *  `inputs` fills the helper's `{{names}}` and may itself use a value read
+   *  earlier in the run (`{{email}}`). What comes back is kept under `saveAs`
+   *  for later steps, exactly as a captured value is; `then: "open"` also
+   *  takes the browser to it, which is what a verification link is for. */
+  helper: z3.object({
+    helperId: z3.string(),
+    inputs: z3.record(z3.string(), z3.string()).default({}),
+    saveAs: z3.string().regex(/^([a-zA-Z][a-zA-Z0-9_]*)?$/),
+    then: z3.enum(["remember", "open"]).default("remember")
+  }).strict().optional()
 }).strict();
 var DraftStepSchema = RecordedStepSchema.extend({
   role: z3.string().default(""),
@@ -940,6 +957,7 @@ function liftSignInFirst(raw) {
 import { z as z4 } from "zod";
 import { z as z22 } from "zod";
 import { z as z32 } from "zod";
+import { z as z42 } from "zod";
 var EngineSchema = z4.enum(["chromium", "firefox", "webkit"]);
 var CapabilitySchema = z4.object({
   id: z4.string(),
@@ -1590,6 +1608,115 @@ function expandForRun(flow, lookup) {
   const { signIn, steps } = preparationFor(flow, lookup);
   return { ...rest, steps: [...signIn ? [signIn] : [], ...steps, ...flow.steps] };
 }
+var HELPER_SCHEMA_VERSION = 1;
+var SecretRef = z42.string().regex(/^[a-z][a-z0-9_]*$/i);
+var PatternSchema = z42.string().max(500).refine((source) => {
+  try {
+    new RegExp(source);
+    return true;
+  } catch {
+    return false;
+  }
+}, "that is not a valid pattern");
+var MailboxHelperSchema = z42.object({
+  kind: z42.literal("mailbox"),
+  /** IMAP, which every provider offers: Gmail, Outlook, Zoho, Fastmail… */
+  host: z42.string().min(1),
+  port: z42.number().int().positive().default(993),
+  secure: z42.boolean().default(true),
+  username: z42.string().min(1),
+  passwordRef: SecretRef,
+  folder: z42.string().min(1).default("INBOX"),
+  /** Which email. All optional; the newest that matches every one given. */
+  match: z42.object({
+    to: z42.string().default(""),
+    from: z42.string().default(""),
+    subject: z42.string().default("")
+  }).strict().default({}),
+  /** What to take out of it. */
+  extract: z42.object({
+    take: z42.enum(["code", "link", "subject", "body"]).default("code"),
+    /** For a code: the pattern, first group if it has one. Default: 4–8 digits.
+     *  For a link: only links containing this text. */
+    pattern: z42.string().max(500).default("")
+  }).strict().default({}),
+  /** How long to wait for the email to arrive. */
+  waitSeconds: z42.number().int().min(0).max(300).default(60)
+}).strict();
+var TotpHelperSchema = z42.object({
+  kind: z42.literal("totp"),
+  /** The authenticator secret (base32, from the QR code's "manual entry"). */
+  secretRef: SecretRef,
+  digits: z42.union([z42.literal(6), z42.literal(8)]).default(6),
+  period: z42.number().int().min(10).max(120).default(30),
+  algorithm: z42.enum(["SHA1", "SHA256", "SHA512"]).default("SHA1")
+}).strict();
+var SmsHelperSchema = z42.object({
+  kind: z42.literal("sms"),
+  provider: z42.literal("twilio").default("twilio"),
+  accountSid: z42.string().regex(/^AC[0-9a-f]{32}$/i, "a Twilio account SID starts with AC followed by 32 characters"),
+  authTokenRef: SecretRef,
+  /** The Twilio number the application texts. */
+  to: z42.string().min(3),
+  match: z42.object({
+    from: z42.string().default(""),
+    contains: z42.string().default("")
+  }).strict().default({}),
+  extract: z42.object({ pattern: z42.string().max(500).default("") }).strict().default({}),
+  waitSeconds: z42.number().int().min(0).max(300).default(60)
+}).strict();
+var HttpHelperSchema = z42.object({
+  kind: z42.literal("http"),
+  method: z42.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("POST"),
+  url: z42.string().min(1),
+  /** Plain headers, in the repository. */
+  headers: z42.record(z42.string(), z42.string()).default({}),
+  /** Header name → vault reference, for tokens and keys. */
+  secretHeaders: z42.record(z42.string(), SecretRef).default({}),
+  body: z42.string().max(2e4).default(""),
+  /** Refused unless the response has this status. 0 means any 2xx. */
+  expectStatus: z42.number().int().min(0).max(599).default(0),
+  extract: z42.object({
+    take: z42.enum(["json", "pattern", "status", "nothing"]).default("nothing"),
+    /** For json: a dot path — `data.order.id`, `items.0.code`. */
+    path: z42.string().max(300).default(""),
+    pattern: z42.string().max(500).default("")
+  }).strict().default({})
+}).strict();
+var HelperConfigSchema = z42.discriminatedUnion("kind", [
+  MailboxHelperSchema,
+  TotpHelperSchema,
+  SmsHelperSchema,
+  HttpHelperSchema
+]);
+var HelperSchema = z42.object({
+  schemaVersion: z42.literal(HELPER_SCHEMA_VERSION),
+  id: z42.string().min(1),
+  slug: z42.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+  name: z42.string().min(1).max(120),
+  description: z42.string().max(1e3).default(""),
+  config: HelperConfigSchema,
+  createdAt: z42.string(),
+  createdBy: z42.string().default(""),
+  updatedAt: z42.string(),
+  revision: z42.number().int().nonnegative().default(0)
+}).strict().superRefine((helper, ctx) => {
+  const patterns = [
+    helper.config.kind === "mailbox" && helper.config.extract.take === "code" ? helper.config.extract.pattern : "",
+    helper.config.kind === "sms" ? helper.config.extract.pattern : "",
+    helper.config.kind === "http" && helper.config.extract.take === "pattern" ? helper.config.extract.pattern : ""
+  ];
+  for (const pattern of patterns) {
+    if (pattern && !PatternSchema.safeParse(pattern).success) {
+      ctx.addIssue({ code: "custom", path: ["config", "extract", "pattern"], message: "that is not a valid pattern" });
+    }
+  }
+});
+var DeliveredHelperSchema = z42.object({
+  id: z42.string().min(1),
+  name: z42.string(),
+  config: HelperConfigSchema
+}).strict();
 
 // ../engine-playwright/dist/index.js
 import { createHmac, randomBytes } from "crypto";
@@ -3390,6 +3517,27 @@ function withRuntimeValues(step, values) {
     proposals: step.proposals.map((check) => ({ ...check, value: Array.isArray(check.value) ? check.value.map(expand) : expand(check.value) }))
   };
 }
+var NAME = /\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}/g;
+async function performHelperStep(page, step, options) {
+  const helper = step.helper;
+  if (!helper?.helperId) throw new Error("Choose which helper this step uses");
+  if (!helper.saveAs) throw new Error("Name the value this step gets");
+  if (!options.runHelper) {
+    throw new Error("helpers run only on runs started from the dashboard \u2014 this machine was not sent any");
+  }
+  const inputs = Object.fromEntries(Object.entries(helper.inputs ?? {}).map(([name, text]) => [name, text.replace(NAME, (_, used) => {
+    if (!options.values.has(used)) throw new Error(`Runtime value "${used}" has not been captured yet`);
+    return options.values.get(used);
+  })]));
+  const got = await options.runHelper(helper.helperId, inputs);
+  if (got.value.length > 16384) throw new Error("The helper's value is over 16 KB");
+  options.values.set(helper.saveAs, got.value);
+  if (helper.then === "open") {
+    if (!/^https?:\/\//i.test(got.value)) throw new Error(`The helper gave "${got.value.slice(0, 80)}", which is not a link to open`);
+    await page.goto(got.value, { waitUntil: "domcontentloaded", timeout: options.navigationTimeoutMs ?? 45e3 });
+  }
+  return got;
+}
 var secretsBehind = (auth) => [.../* @__PURE__ */ new Set([
   ...Object.values(auth.secretRefs ?? {}),
   ...auth.steps.flatMap((step) => step.secretRef ? [step.secretRef] : [])
@@ -3625,7 +3773,9 @@ var RunActors = class {
           pages: session.pages,
           baseUrl: this.opts.baseUrl,
           ...this.opts.resolveAuth ? { resolveAuth: this.opts.resolveAuth } : {},
-          ...this.opts.resolveSecret ? { resolveSecret: this.opts.resolveSecret } : {}
+          ...this.opts.resolveSecret ? { resolveSecret: this.opts.resolveSecret } : {},
+          ...this.opts.runHelper ? { runHelper: this.opts.runHelper } : {},
+          values: this.values
         }
       );
       if (!this.preparations.has(id)) this.preparations.set(id, "fresh");
@@ -4486,7 +4636,7 @@ async function openRunSession(opts) {
   const consoleLines = [];
   if (artifacts.console) {
     const typed = steps.filter((step) => step.secret).map((step) => resolveSecret?.(step.secretRef || step.value)).filter((value) => Boolean(value && value.length >= 3));
-    const redact2 = (line) => typed.reduce((text, secret) => text.split(secret).join("[secret]"), line);
+    const redact2 = (line) => typed.reduce((text, secret2) => text.split(secret2).join("[secret]"), line);
     const watch = (p) => p.on("console", (m) => {
       if (consoleLines.length < 2e3) consoleLines.push(redact2(`[${m.type()}] ${m.text()}`));
     });
@@ -4636,6 +4786,7 @@ async function replayInto(target, steps, opts) {
     startUrl: null,
     ...opts.resolveSecret ? { resolveSecret: opts.resolveSecret } : {},
     ...opts.resolveAuth ? { resolveAuth: opts.resolveAuth } : {},
+    ...opts.runHelper ? { runHelper: opts.runHelper } : {},
     ...opts.baseUrl ? { baseUrl: opts.baseUrl } : {}
   });
   return outcome.status === "passed" ? { ok: true } : { ok: false, error: outcome.error ?? "a step before recording did not complete" };
@@ -4663,6 +4814,7 @@ function stepFailure(step, detail) {
 async function runStepsIn(session, steps, opts) {
   let { page, pages, config, artifacts } = session;
   const { resolveSecret, resolveFile, onStepResult, evidenceDir } = opts;
+  const values = opts.actors?.values ?? opts.values ?? /* @__PURE__ */ new Map();
   const results = [];
   let status2 = "passed";
   let error = null;
@@ -4674,7 +4826,7 @@ async function runStepsIn(session, steps, opts) {
       let step = recorded;
       if (!recorded.disabled) {
         try {
-          step = withRuntimeValues(recorded, opts.actors?.values ?? /* @__PURE__ */ new Map());
+          step = withRuntimeValues(recorded, values);
         } catch (err) {
           const result2 = stepFailure(recorded, firstLine2(err));
           results.push(result2);
@@ -4859,6 +5011,14 @@ async function runStepsIn(session, steps, opts) {
           valuesResolved: true,
           baseUrl: opts.baseUrl,
           ...opts.actors ? { actors: opts.actors } : {},
+          ...opts.runHelper ? { runHelper: opts.runHelper } : {},
+          values,
+          // What the helper got is what this row reports: the code typed next
+          // is the first thing anybody checks when the application refused it.
+          onHelper: (got) => {
+            result.value = got.value;
+            result.detail = got.detail;
+          },
           timeoutMs: config.timeoutMs,
           navigationTimeoutMs: config.navigationTimeoutMs,
           // SAID OUT LOUD, on a step that passed. The element was found, but
@@ -4968,6 +5128,7 @@ async function replayFlow(opts) {
     ...opts.evidenceDir === void 0 ? {} : { evidenceDir: opts.evidenceDir },
     ...opts.signal === void 0 ? {} : { signal: opts.signal },
     ...opts.resolveAuth === void 0 ? {} : { resolveAuth: opts.resolveAuth },
+    ...opts.runHelper === void 0 ? {} : { runHelper: opts.runHelper },
     baseUrl,
     startUrl: null
   });
@@ -4991,7 +5152,8 @@ async function replayFlow(opts) {
 }
 async function executeStep(main, input, options = {}) {
   const parsed = RecordedStepSchema.parse(input);
-  const step = options.valuesResolved ? parsed : withRuntimeValues(parsed, options.actors?.values ?? /* @__PURE__ */ new Map());
+  const values = options.actors?.values ?? options.values ?? /* @__PURE__ */ new Map();
+  const step = options.valuesResolved ? parsed : withRuntimeValues(parsed, values);
   if (options.actors) {
     if (step.type === "resetActor") {
       await options.actors.freshGuest(step.actorId ?? options.actors.currentId);
@@ -5020,6 +5182,15 @@ async function executeStep(main, input, options = {}) {
     if (!outcome.ok) throw new Error(outcome.detail ?? "Authentication failed");
     return main;
   }
+  if (step.type === "useHelper") {
+    const got = await performHelperStep(page, step, {
+      values,
+      ...options.runHelper ? { runHelper: options.runHelper } : {},
+      ...options.navigationTimeoutMs ? { navigationTimeoutMs: options.navigationTimeoutMs } : {}
+    });
+    options.onHelper?.(got);
+    return page;
+  }
   if (step.type === "capture") {
     if (!step.capture || !options.actors) throw new Error("Configure the runtime output name and source");
     if (step.secret) throw new Error("Secret fields cannot be captured as shared outputs");
@@ -5243,6 +5414,7 @@ async function replayCase(opts) {
         actors,
         baseUrl: occurrence.baseUrl ?? baseUrl,
         ...opts.resolveAuth ? { resolveAuth: opts.resolveAuth } : {},
+        ...opts.runHelper ? { runHelper: opts.runHelper } : {},
         stepOffset: outcomes.reduce((count, previous) => count + previous.stepsTotal, 0),
         ...occurrence.ownSignIn ? { ownSignIn: occurrence.ownSignIn } : {},
         ...opts.resolveSecret === void 0 ? {} : { resolveSecret: opts.resolveSecret },
@@ -5700,6 +5872,7 @@ async function startRecordingSession(opts) {
       const replayed = await replayInto({ browser, context, page, config }, opts.preparation.steps, {
         resolveSecret: opts.preparation.resolveSecret,
         ...opts.preparation.resolveAuth ? { resolveAuth: opts.preparation.resolveAuth } : {},
+        ...opts.preparation.runHelper ? { runHelper: opts.preparation.runHelper } : {},
         baseUrl: url
       });
       if (!replayed.ok) throw new Error(replayed.error);
@@ -5880,7 +6053,7 @@ async function startRecordingSession(opts) {
 function firstLine2(err) {
   return String(err?.message ?? err).split("\n")[0].trim();
 }
-var SESSION_STEPS = /* @__PURE__ */ new Set(["signIn", "signOut", "useActor", "resetActor", "capture"]);
+var SESSION_STEPS = /* @__PURE__ */ new Set(["signIn", "signOut", "useActor", "resetActor", "capture", "useHelper"]);
 var usesAnOutput = (text) => Array.isArray(text) ? text.some(usesAnOutput) : String(text ?? "").includes("{{");
 function needsWholeRun(opts) {
   if (opts.actors?.length) return true;
@@ -6233,7 +6406,7 @@ async function startDebugSession(opts) {
       step = withRuntimeValues(step, actors?.values ?? /* @__PURE__ */ new Map());
       const fresh = step.secret && recordedInSession.has(step.id);
       const on = actors?.current ?? { page, pages };
-      const active = await executeStep(on.page, fresh ? { ...step, secret: false } : step, { pages: on.pages, resolveSecret, resolveFile, timeoutMs, baseUrl, valuesResolved: true, ...actors ? { actors } : {}, ...opts.resolveAuth ? { resolveAuth: opts.resolveAuth } : {} });
+      const active = await executeStep(on.page, fresh ? { ...step, secret: false } : step, { pages: on.pages, resolveSecret, resolveFile, timeoutMs, baseUrl, valuesResolved: true, ...actors ? { actors } : {}, ...opts.resolveAuth ? { resolveAuth: opts.resolveAuth } : {}, ...opts.runHelper ? { runHelper: opts.runHelper } : {} });
       for (const a of step.proposals ?? []) {
         if (a.enabled === false) continue;
         const label = describeAssertion(a, step.name);
@@ -7307,7 +7480,7 @@ function toSummary(row) {
   };
 }
 
-// ../repository-store/dist/chunk-A4JZPKZT.js
+// ../repository-store/dist/chunk-HTFXAD4R.js
 var FLOWRIKI_DIR = ".flowriki";
 var FEATURES_DIR = `${FLOWRIKI_DIR}/features`;
 var CONFIG_PATH = `${FLOWRIKI_DIR}/config.json`;
@@ -7318,6 +7491,7 @@ var CASES_DIR = `${FLOWRIKI_DIR}/cases`;
 var SUITES_DIR = `${FLOWRIKI_DIR}/suites`;
 var AUTH_DIR = `${FLOWRIKI_DIR}/auth`;
 var ACCOUNTS_DIR = `${AUTH_DIR}/accounts`;
+var HELPERS_DIR = `${FLOWRIKI_DIR}/helpers`;
 function assertSlug(slug) {
   if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) throw new Error(`invalid slug: ${slug}`);
   return slug;
@@ -8026,6 +8200,275 @@ function ensureRootCommit(root) {
   return git2(root, ["rev-list", "--max-parents=0", "HEAD"]).split("\n").pop();
 }
 
+// ../helpers/dist/index.js
+import { createHmac as createHmac2 } from "crypto";
+var HelperFailure = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "HelperFailure";
+  }
+};
+var NAME2 = /\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}/g;
+function fill(text, inputs = {}) {
+  return text.replace(NAME2, (_, name) => {
+    if (inputs[name] === void 0) throw new HelperFailure(`needs a value for {{${name}}}`);
+    return inputs[name];
+  });
+}
+var secret = (ctx, ref, what) => {
+  const value = ctx.resolveSecret(ref);
+  if (!value) throw new HelperFailure(`the ${what} has not been set \u2014 save it on this helper first`);
+  return value;
+};
+var DEFAULT_CODE = "\\b\\d{4,8}\\b";
+function takeCode(text, pattern) {
+  const re = new RegExp(pattern || DEFAULT_CODE);
+  const m = re.exec(text);
+  if (!m) return null;
+  return (m[1] ?? m[0]).trim();
+}
+function linksIn(html, text) {
+  const out = [];
+  for (const m of html.matchAll(/href\s*=\s*["']([^"']+)["']/gi)) out.push(m[1].replace(/&amp;/g, "&"));
+  for (const m of text.matchAll(/https?:\/\/[^\s<>"')\]]+/g)) out.push(m[0]);
+  return [...new Set(out)].filter((url) => /^https?:\/\//i.test(url));
+}
+var textOfHtml = (html) => html.replace(/<style[\s\S]*?<\/style>/gi, " ").replace(/<script[\s\S]*?<\/script>/gi, " ").replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/\s+/g, " ").trim();
+var ago = (from, at) => {
+  const s2 = Math.max(0, Math.round((from - at.getTime()) / 1e3));
+  return s2 < 60 ? `${s2}s ago` : s2 < 3600 ? `${Math.round(s2 / 60)} min ago` : at.toISOString();
+};
+function base32(input) {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+  const clean = input.toUpperCase().replace(/[\s=-]/g, "");
+  let bits = 0, value = 0;
+  const out = [];
+  for (const ch of clean) {
+    const at = alphabet.indexOf(ch);
+    if (at < 0) throw new HelperFailure(`the authenticator secret is not base32 \u2014 copy it from the "can't scan the code?" option`);
+    value = value << 5 | at;
+    bits += 5;
+    if (bits >= 8) {
+      out.push(value >>> bits - 8 & 255);
+      bits -= 8;
+    }
+  }
+  return Buffer.from(out);
+}
+function totp(secretBase32, at, options = {}) {
+  const { digits = 6, period = 30, algorithm = "SHA1" } = options;
+  const counter = Math.floor(at / 1e3 / period);
+  const buffer = Buffer.alloc(8);
+  buffer.writeBigUInt64BE(BigInt(counter));
+  const hmac = createHmac2(algorithm.toLowerCase(), base32(secretBase32)).update(buffer).digest();
+  const offset = hmac[hmac.length - 1] & 15;
+  const binary = (hmac[offset] & 127) << 24 | hmac[offset + 1] << 16 | hmac[offset + 2] << 8 | hmac[offset + 3];
+  const code = String(binary % 10 ** digits).padStart(digits, "0");
+  const remaining = period - Math.floor(at / 1e3 % period);
+  return { code, remaining };
+}
+async function imapMailbox(config, password) {
+  const { ImapFlow } = await import("imapflow");
+  const { simpleParser } = await import("mailparser");
+  const client = new ImapFlow({
+    host: config.host,
+    port: config.port,
+    secure: config.secure,
+    auth: { user: config.username, pass: password },
+    logger: false
+  });
+  try {
+    await client.connect();
+  } catch (error) {
+    const text = String(error.responseText ?? error.message ?? error);
+    throw new HelperFailure(/auth|credential|login|password/i.test(text) ? `the mailbox refused the username or password \u2014 for Gmail and Outlook this has to be an app password (${text.slice(0, 120)})` : `could not reach the mailbox at ${config.host}:${config.port} \u2014 ${text.slice(0, 160)}`);
+  }
+  return {
+    async latest(query, limit) {
+      const lock = await client.getMailboxLock(config.folder);
+      try {
+        const criteria = {};
+        if (query.to) criteria["to"] = query.to;
+        if (query.from) criteria["from"] = query.from;
+        if (query.subject) criteria["subject"] = query.subject;
+        if (query.since) criteria["since"] = new Date(query.since.getTime() - 864e5);
+        const found = await client.search(Object.keys(criteria).length ? criteria : { all: true }, { uid: true });
+        const uids = (Array.isArray(found) ? found : []).slice(-limit).reverse();
+        const out = [];
+        for (const uid of uids) {
+          const message = await client.fetchOne(String(uid), { source: true, internalDate: true }, { uid: true });
+          if (!message || !message.source) continue;
+          const parsed = await simpleParser(message.source);
+          const addresses = (v) => {
+            const list = Array.isArray(v) ? v : v ? [v] : [];
+            return list.map((a) => a.text ?? "").join(", ");
+          };
+          out.push({
+            received: message.internalDate ? new Date(message.internalDate) : parsed.date ?? /* @__PURE__ */ new Date(0),
+            from: addresses(parsed.from),
+            to: addresses(parsed.to),
+            subject: parsed.subject ?? "",
+            text: parsed.text ?? "",
+            html: typeof parsed.html === "string" ? parsed.html : ""
+          });
+        }
+        return out;
+      } finally {
+        lock.release();
+      }
+    },
+    async close() {
+      await client.logout().catch(() => void 0);
+    }
+  };
+}
+async function runMailbox(config, ctx) {
+  const now = ctx.now ?? Date.now;
+  const query = {
+    to: fill(config.match.to, ctx.inputs),
+    from: fill(config.match.from, ctx.inputs),
+    subject: fill(config.match.subject, ctx.inputs),
+    since: ctx.since ?? null
+  };
+  const mailbox = await (ctx.openMailbox ?? imapMailbox)(config, secret(ctx, config.passwordRef, "mailbox password"));
+  const deadline = now() + config.waitSeconds * 1e3;
+  try {
+    for (; ; ) {
+      const messages = (await mailbox.latest(query, 20)).filter((m) => !query.since || m.received.getTime() >= query.since.getTime()).sort((a, b2) => b2.received.getTime() - a.received.getTime());
+      const message = messages[0];
+      if (message) {
+        const evidence = { from: message.from, subject: message.subject, received: ago(now(), message.received) };
+        const body = message.text || textOfHtml(message.html);
+        switch (config.extract.take) {
+          case "subject":
+            return { value: message.subject, detail: `the subject of "${message.subject}"`, evidence };
+          case "body":
+            return { value: body.slice(0, 4e3), detail: `the text of "${message.subject}"`, evidence };
+          case "link": {
+            const links = linksIn(message.html, message.text).filter((url) => !config.extract.pattern || url.includes(config.extract.pattern));
+            if (!links[0]) throw new HelperFailure(`"${message.subject}" has no link${config.extract.pattern ? ` containing "${config.extract.pattern}"` : ""}`);
+            return { value: links[0], detail: `the link in "${message.subject}"`, evidence };
+          }
+          case "code": {
+            const code = takeCode(`${message.subject}
+${body}`, config.extract.pattern);
+            if (!code) throw new HelperFailure(`"${message.subject}" has nothing matching ${config.extract.pattern || "a 4\u20138 digit code"}`);
+            return { value: code, detail: `the code in "${message.subject}"`, evidence };
+          }
+        }
+      }
+      if (now() >= deadline || ctx.signal?.aborted) {
+        const looked = [query.to && `to ${query.to}`, query.from && `from ${query.from}`, query.subject && `about "${query.subject}"`].filter(Boolean).join(", ");
+        throw new HelperFailure(`no email${looked ? ` ${looked}` : ""}${query.since ? " since this started" : ""} arrived within ${config.waitSeconds}s`);
+      }
+      await new Promise((r) => setTimeout(r, ctx.pollMs ?? 3e3));
+    }
+  } finally {
+    await mailbox.close();
+  }
+}
+async function runSms(config, ctx) {
+  const now = ctx.now ?? Date.now;
+  const http = ctx.fetch ?? fetch;
+  const to = fill(config.to, ctx.inputs);
+  const from = fill(config.match.from, ctx.inputs);
+  const contains = fill(config.match.contains, ctx.inputs);
+  const token = secret(ctx, config.authTokenRef, "Twilio auth token");
+  const auth = Buffer.from(`${config.accountSid}:${token}`).toString("base64");
+  const deadline = now() + config.waitSeconds * 1e3;
+  for (; ; ) {
+    const url = `https://api.twilio.com/2010-04-01/Accounts/${encodeURIComponent(config.accountSid)}/Messages.json?To=${encodeURIComponent(to)}&PageSize=20`;
+    const response = await http(url, { headers: { authorization: `Basic ${auth}` }, ...ctx.signal ? { signal: ctx.signal } : {} });
+    if (response.status === 401) throw new HelperFailure("Twilio refused the account SID or auth token");
+    if (!response.ok) throw new HelperFailure(`Twilio answered ${response.status}`);
+    const body = await response.json();
+    const messages = (body.messages ?? []).map((m) => ({ ...m, at: new Date(m.date_sent ?? m.date_created) })).filter((m) => (!from || m.from.includes(from)) && (!contains || m.body.includes(contains))).filter((m) => !ctx.since || m.at.getTime() >= ctx.since.getTime()).sort((a, b2) => b2.at.getTime() - a.at.getTime());
+    const message = messages[0];
+    if (message) {
+      const code = takeCode(message.body, config.extract.pattern);
+      const evidence = { from: message.from, text: message.body.slice(0, 160), received: ago(now(), message.at) };
+      if (!code) throw new HelperFailure(`the latest text has nothing matching ${config.extract.pattern || "a 4\u20138 digit code"}`);
+      return { value: code, detail: `the code in the text from ${message.from}`, evidence };
+    }
+    if (now() >= deadline || ctx.signal?.aborted) {
+      throw new HelperFailure(`no text to ${to}${ctx.since ? " since this started" : ""} arrived within ${config.waitSeconds}s`);
+    }
+    await new Promise((r) => setTimeout(r, ctx.pollMs ?? 3e3));
+  }
+}
+function atPath(value, path11) {
+  let at = value;
+  for (const key of path11.split(".").filter(Boolean)) {
+    if (at === null || at === void 0) return void 0;
+    at = Array.isArray(at) && /^\d+$/.test(key) ? at[Number(key)] : at[key];
+  }
+  return at;
+}
+async function runHttp(config, ctx) {
+  const http = ctx.fetch ?? fetch;
+  const url = fill(config.url, ctx.inputs);
+  try {
+    new URL(url);
+  } catch {
+    throw new HelperFailure(`"${url}" is not an address`);
+  }
+  const headers = {};
+  for (const [name, value] of Object.entries(config.headers)) headers[name] = fill(value, ctx.inputs);
+  for (const [name, ref] of Object.entries(config.secretHeaders)) headers[name] = secret(ctx, ref, `"${name}" header`);
+  const body = config.method === "GET" || !config.body ? void 0 : fill(config.body, ctx.inputs);
+  if (body && !Object.keys(headers).some((h) => h.toLowerCase() === "content-type")) {
+    headers["content-type"] = /^\s*[[{]/.test(body) ? "application/json" : "text/plain";
+  }
+  const timeout = AbortSignal.timeout(3e4);
+  let response;
+  try {
+    response = await http(url, { method: config.method, headers, ...body !== void 0 ? { body } : {}, signal: ctx.signal ? AbortSignal.any([ctx.signal, timeout]) : timeout });
+  } catch (error) {
+    throw new HelperFailure(`could not reach ${new URL(url).host} \u2014 ${error.message}`);
+  }
+  const text = await response.text();
+  const ok = config.expectStatus ? response.status === config.expectStatus : response.ok;
+  if (!ok) throw new HelperFailure(`${config.method} ${new URL(url).pathname} answered ${response.status}${config.expectStatus ? `, not ${config.expectStatus}` : ""}: ${text.slice(0, 200)}`);
+  const evidence = { status: String(response.status), response: text.slice(0, 300) };
+  switch (config.extract.take) {
+    case "nothing":
+      return { value: "", detail: `${config.method} ${new URL(url).pathname} answered ${response.status}`, evidence };
+    case "status":
+      return { value: String(response.status), detail: "the response status", evidence };
+    case "pattern": {
+      const found = takeCode(text, config.extract.pattern);
+      if (found === null) throw new HelperFailure(`the response has nothing matching ${config.extract.pattern}`);
+      return { value: found, detail: "matched in the response", evidence };
+    }
+    case "json": {
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        throw new HelperFailure("the response is not JSON");
+      }
+      const value = atPath(parsed, config.extract.path);
+      if (value === void 0 || value === null) throw new HelperFailure(`the response has no "${config.extract.path}"`);
+      return { value: typeof value === "string" ? value : JSON.stringify(value), detail: `"${config.extract.path}" from the response`, evidence };
+    }
+  }
+}
+async function runHelper(helper, ctx) {
+  const config = "config" in helper ? helper.config : helper;
+  switch (config.kind) {
+    case "totp": {
+      const { code, remaining } = totp(secret(ctx, config.secretRef, "authenticator secret"), (ctx.now ?? Date.now)(), config);
+      return { value: code, detail: `valid for ${remaining} more seconds`, evidence: {} };
+    }
+    case "mailbox":
+      return runMailbox(config, ctx);
+    case "sms":
+      return runSms(config, ctx);
+    case "http":
+      return runHttp(config, ctx);
+  }
+}
+
 // ../execution/dist/index.js
 import fs24 from "fs";
 import crypto3 from "crypto";
@@ -8101,6 +8544,7 @@ async function executeFlow(opts) {
       ...flow.actors ? { actors: flow.actors } : {},
       ...flow.defaultActorId ? { defaultActorId: flow.defaultActorId } : {},
       ...store.resolveAuth ? { resolveAuth: store.resolveAuth } : {},
+      ...store.runHelper ? { runHelper: store.runHelper } : {},
       ...opts.reuse ? { reuse: opts.reuse } : {},
       // The flow's own origin when it has one, the project's otherwise. A flow
       // that carries no origin is the normal case now: the environment belongs
@@ -8321,6 +8765,28 @@ function toStepRow(ordinal, result, step) {
     checks
   };
 }
+var CLOCK_SLACK_MS = 1e4;
+function helperRunner(delivered, secrets, startedAt = /* @__PURE__ */ new Date()) {
+  if (!Array.isArray(delivered) || delivered.length === 0) return void 0;
+  const helpers = new Map(
+    DeliveredHelperSchema.array().parse(delivered).map((helper) => [helper.id, helper])
+  );
+  const since = new Date(startedAt.getTime() - CLOCK_SLACK_MS);
+  return async (helperId, inputs) => {
+    const helper = helpers.get(helperId);
+    if (!helper) throw new Error("that helper was deleted, or was not sent with this run \u2014 choose another");
+    try {
+      const { value, detail } = await runHelper(helper.config, {
+        resolveSecret: (ref) => secrets?.[ref],
+        inputs,
+        since
+      });
+      return { value, detail: `${helper.name}: ${detail}` };
+    } catch (error) {
+      throw new Error(`${helper.name}: ${error.message}`);
+    }
+  };
+}
 var LOCAL_CHROMIUM2 = { id: "chromium", provider: "local", engine: "chromium" };
 async function summaryOf2(storage, runId) {
   const detail = await storage.getRun(runId);
@@ -8381,6 +8847,7 @@ async function executeCase(opts) {
   const stepsByOccurrence = new Map(testCase.occurrences.map((o) => [o.occurrenceId, new Map(o.steps.map((s2) => [s2.id, s2]))]));
   const ordinals = /* @__PURE__ */ new Map();
   const writes = [];
+  const helpers = helperRunner(opts.helpers, opts.secrets);
   let outcome;
   try {
     outcome = await replayCase({
@@ -8388,6 +8855,7 @@ async function executeCase(opts) {
       ...testCase.actors ? { actors: testCase.actors } : {},
       ...testCase.defaultActorId ? { defaultActorId: testCase.defaultActorId } : {},
       resolveAuth: authenticationResolver(opts.authentications),
+      ...helpers ? { runHelper: helpers } : {},
       ...opts.reuse ? { reuse: opts.reuse } : {},
       baseUrl: testCase.baseUrl ?? baseUrl,
       ...testCase.environment ? { environment: testCase.environment } : {},
@@ -8582,6 +9050,7 @@ var RecordingCoordinator = class {
   /** Everything that used to happen before `start` answered. */
   async open(target, opts) {
     const config = this.deps.store.readConfig();
+    const helpers = helperRunner(opts.helpers, opts.secrets);
     const configuredBase = config.baseUrl;
     try {
       this.session = await startRecordingSession({
@@ -8589,12 +9058,14 @@ var RecordingCoordinator = class {
         ...opts.authentication ? { authentication: {
           step: { id: "auth-preparation", type: "signIn", auth: opts.authentication, name: "Sign in before recording", role: "", scope: "", value: "", secret: false, legacySelector: "", proposals: [] },
           resolveAuth: authenticationResolver(opts.authentications),
-          resolveSecret: (ref) => opts.secrets?.[ref]
+          resolveSecret: (ref) => opts.secrets?.[ref],
+          ...helpers ? { runHelper: helpers } : {}
         } } : {},
         ...opts.preparation?.length ? { preparation: {
           steps: opts.preparation,
           resolveAuth: authenticationResolver(opts.authentications),
-          resolveSecret: (ref) => opts.secrets?.[ref]
+          resolveSecret: (ref) => opts.secrets?.[ref],
+          ...helpers ? { runHelper: helpers } : {}
         } } : {},
         // The project's saved defaults, unless this recording asks for
         // something else. Without the fallback the settings screen would write
@@ -8788,6 +9259,7 @@ var DebugCoordinator = class {
         ...flow.actors ? { actors: flow.actors } : {},
         ...flow.defaultActorId ? { defaultActorId: flow.defaultActorId } : {},
         ...store.resolveAuth ? { resolveAuth: store.resolveAuth } : {},
+        ...store.runHelper ? { runHelper: store.runHelper } : {},
         environment: store.environmentFor(flow),
         resolveFile: (name) => store.resolveFile(name),
         baseUrl,
@@ -8921,6 +9393,7 @@ async function verifyFlowSteps(deps, opts) {
     const secrets = store.readSecrets();
     return await verifySteps({
       ...store.resolveAuth ? { resolveAuth: store.resolveAuth } : {},
+      ...store.runHelper ? { runHelper: store.runHelper } : {},
       environment: store.environmentFor(flow),
       resolveFile: (name) => store.resolveFile(name),
       // Streamed, so the editor fills in as the pass proceeds instead of
@@ -8945,8 +9418,10 @@ async function verifyFlowSteps(deps, opts) {
 }
 function deliveredRun(delivered) {
   const { flow, secrets, config } = delivered;
+  const runHelper2 = helperRunner(delivered.helpers, secrets);
   return {
     resolveAuth: authenticationResolver(delivered.authentications),
+    ...runHelper2 ? { runHelper: runHelper2 } : {},
     readConfig: () => config,
     // By id, and only the one that was sent. A machine serving no checkout has
     // no other flow to confuse it with.
@@ -9040,7 +9515,7 @@ function resolveCheckouts(dirs) {
   return { projects, skipped };
 }
 
-// ../agent-core/dist/chunk-4MOK25KG.js
+// ../agent-core/dist/chunk-LR7LBGCT.js
 import { WebSocket, WebSocketServer } from "ws";
 var HEARTBEAT_MS = 3e4;
 function adapt(socket) {
@@ -9927,6 +10402,7 @@ function executionHandlers(ctx) {
       const source = carried ? deliveredRun({
         flow: carried,
         authentications: command.args["authentications"],
+        helpers: command.args["helpers"],
         secrets: command.args["secrets"] ?? {},
         config: command.args["config"] ?? {}
       }) : storeFor(project.root);
@@ -10033,6 +10509,7 @@ function executionHandlers(ctx) {
         const { outcome, run } = await executeCase({
           testCase,
           authentications: command.args["authentications"],
+          helpers: command.args["helpers"],
           projectId: project.id,
           config: command.args["config"] ?? {},
           secrets: command.args["secrets"] ?? {},
@@ -10115,6 +10592,7 @@ function recordingHandlers({ recorder, onActivity }) {
           ...Array.isArray(command.args["preparation"]) && command.args["preparation"].length > 0 ? { preparation: RecordedStepSchema.array().parse(command.args["preparation"]) } : {},
           ...command.args["authentication"] || command.args["preparation"] ? {
             authentications: command.args["authentications"],
+            helpers: command.args["helpers"],
             secrets: command.args["secrets"] ?? {}
           } : {},
           projectId: project.id,
@@ -10201,6 +10679,7 @@ function debuggingHandlers(ctx) {
           ...carried ? { delivered: {
             flow: carried,
             authentications: command.args["authentications"],
+            helpers: command.args["helpers"],
             secrets: command.args["secrets"] ?? {},
             config: command.args["config"] ?? {}
           } } : {},
@@ -10242,6 +10721,7 @@ function debuggingHandlers(ctx) {
             delivered: {
               flow: carried,
               authentications: command.args["authentications"],
+              helpers: command.args["helpers"],
               secrets: command.args["secrets"] ?? {},
               config: command.args["config"] ?? {},
               scratchRoot: scratchRoot(project.id)
@@ -10372,6 +10852,7 @@ function createAgentRuntime(options) {
     store: deliveredRun({
       flow: delivered.flow,
       authentications: delivered.authentications,
+      helpers: delivered.helpers,
       secrets: delivered.secrets,
       config: delivered.config
     }),
@@ -10725,7 +11206,17 @@ export {
   AGENT_VERSION,
   prepareBrowsers,
   browsersReady,
+  connectionFor,
+  resolveService,
   connect,
+  RecordedStepSchema,
+  authenticationResolver,
+  checkAssertion,
+  openRunSession,
+  closeRunSession,
+  replayFlow,
+  executeStep,
+  helperRunner,
   resolveCheckouts,
   start,
   status,