wb-browser-runtime 0.7.0 → 0.11.0

package/README.md

@@ -11,10 +11,19 @@ name across slices for the lifetime of the sidecar process so a runbook with
 multiple browser blocks against the same vendor reuses one logged-in browser
 context.
 
-## Install (local dev)
+## Install
+
+From npm:
+
+```bash
+npm install -g wb-browser-runtime
+```
+
+From source (local dev):
 
 ```bash
-cd runtimes/browser
+git clone https://github.com/workbooks-dev/wb-browser-runtime.git
+cd wb-browser-runtime
 npm install       # installs playwright-core
 npm link          # exposes `wb-browser-runtime` on $PATH
 ```
@@ -42,7 +51,9 @@ at sidecar boot; there is no per-slice override.
   is 60 minutes; unused time is refunded if the session ran less than an hour.
 
 Profile (auth state) is selected per-runbook via the `profile_id:` field on a
-`browser` block — see "Profiles" below.
+`browser` block — see "Profiles" below. `BROWSER_USE_PROFILE_ID` is read as a
+default when the browser block omits `profile_id:`; a per-runbook `profile_id:`
+always wins over the env var.
 
 ## Profiles
 

package/bin/wb-browser-runtime.js

@@ -36,7 +36,7 @@ import {
 import { getProvider } from "../lib/providers/index.js";
 import { SUPPORTS, runVerb, verbName } from "../verbs/index.js";
 
-const VERSION = "0.7.0";
+const VERSION = "0.8.0";
 const provider = getProvider();
 log(`[provider] ${provider.name}`);
 
@@ -56,7 +56,7 @@ if (recording.enabled) {
 
 const sessions = new SessionManager();
 
-async function ensureSession(name, { profile } = {}) {
+async function ensureSession(name, { profile, restoreSession } = {}) {
   return sessions.ensure(name, async () => {
     // Vendors charge for the session the moment allocate() returns; if
     // anything after this point throws (getLiveUrl, CDP connect, newContext,
@@ -69,11 +69,22 @@ async function ensureSession(name, { profile } = {}) {
     // against a cold vendor region, but the live-URL fetch and
     // newContext/newPage can each stall independently.
     const t0 = Date.now();
-    const allocated = await provider.allocate({ profile, sessionName: name });
+    const restored =
+      restoreSession &&
+      restoreSession.vendor === provider.name &&
+      restoreSession.cdpUrl;
+    const allocated = restored
+      ? {
+          sid: restoreSession.sid,
+          cdpUrl: restoreSession.cdpUrl,
+          _liveUrl: restoreSession.liveUrl ?? null,
+          _restored: true,
+        }
+      : await provider.allocate({ profile, sessionName: name });
     const tAllocated = Date.now();
     let browser = null;
     try {
-      const liveUrl = await provider.getLiveUrl(allocated);
+      const liveUrl = allocated._liveUrl ?? (await provider.getLiveUrl(allocated));
       browser = await chromium.connectOverCDP(allocated.cdpUrl);
       const tConnected = Date.now();
       const context = browser.contexts()[0] ?? (await browser.newContext());
@@ -82,6 +93,8 @@ async function ensureSession(name, { profile } = {}) {
 
       const info = {
         sid: allocated.sid,
+        cdpUrl: allocated.cdpUrl,
+        vendor: provider.name,
         browser,
         context,
         page,
@@ -95,6 +108,7 @@ async function ensureSession(name, { profile } = {}) {
         session_id: allocated.sid,
         live_url: liveUrl,
         vendor: provider.name,
+        restored: Boolean(restored),
         started_at: new Date().toISOString(),
         timings: {
           allocate_ms: tAllocated - t0,
@@ -107,12 +121,12 @@ async function ensureSession(name, { profile } = {}) {
       await recording.start(info, name);
       return info;
     } catch (e) {
-      if (browser) {
+      if (browser && !allocated._restored) {
         try {
           await browser.close();
         } catch {}
       }
-      await provider.release(allocated.sid);
+      if (!allocated._restored) await provider.release(allocated.sid);
       throw e;
     }
   });
@@ -252,10 +266,14 @@ async function handleSlice(msg) {
     const verbs = Array.isArray(msg.verbs) ? msg.verbs : [];
     const sessionName = msg.session || "default";
     const restore = msg.restore || null;
+    const restoreSession = restore?.state?.session || null;
 
     let session;
     try {
-      session = await ensureSession(sessionName, { profile: msg.profile });
+      session = await ensureSession(sessionName, {
+        profile: msg.profile,
+        restoreSession,
+      });
     } catch (e) {
       send({
         type: "slice.failed",
@@ -264,10 +282,17 @@ async function handleSlice(msg) {
       return;
     }
 
-    // Restore-from-pause is not implemented yet (no pause verb wired here).
-    // The sidecar protocol leaves room for it; when wait_for_mfa lands, this
-    // is where we'd jump to verbs[restore.state.verb_index].
-    const startAt = restore?.state?.verb_index ?? 0;
+    // Restore-from-pause: when the Rust side resumes us after a
+    // `slice.paused` frame, `restore.state.verb_index` is the index of the
+    // verb that paused. We skip *past* it — the verb has no post-resume
+    // work (any payload from the operator is already in
+    // $WB_ARTIFACTS_DIR/pause_result.json, written by `wb resume` before
+    // it re-boots the sidecar). Skipping keeps pause verbs pure: their
+    // only job is "halt now," not "halt, then continue."
+    const startAt =
+      restore?.state?.verb_index !== undefined
+        ? Number(restore.state.verb_index) + 1
+        : 0;
 
     for (let i = startAt; i < verbs.length; i++) {
       if (Date.now() >= sliceDeadline) {
@@ -282,6 +307,42 @@ async function handleSlice(msg) {
       const verbStart = Date.now();
       try {
         const summary = await runVerb(session.page, v, i, sliceCtx, expand);
+        // Pause-sentinel escape hatch: a verb signals a mid-slice halt by
+        // returning `{ __pause: {...} }`. We translate that into a
+        // `slice.paused` frame (so the Rust side writes a pending
+        // descriptor and exits 42) and bail out of the verb loop without
+        // firing `slice.complete`. Non-pause verbs hand back a plain
+        // summary and the loop proceeds normally.
+        if (summary && typeof summary === "object" && summary.__pause) {
+          const pauseMeta = summary.__pause;
+          send({
+            type: "slice.paused",
+            reason: pauseMeta.reason || "slice.paused",
+            message: pauseMeta.message || "",
+            context_url: pauseMeta.context_url ?? null,
+            resume_on: pauseMeta.resume_on || "operator_click",
+            timeout: pauseMeta.timeout ?? null,
+            actions: pauseMeta.actions || [{ label: "Resume", value: null }],
+            verb: name,
+            verb_index: i,
+            // `sidecar_state` is forwarded verbatim into the Rust pending
+            // descriptor and handed back on resume. The verb can stash
+            // whatever it needs here; we always ensure verb_index is set
+            // so the dispatcher can compute startAt on re-entry.
+            sidecar_state: {
+              ...(pauseMeta.sidecar_state || {}),
+              verb_index: i,
+              session: {
+                vendor: session.vendor,
+                name: sessionName,
+                sid: session.sid,
+                cdpUrl: session.cdpUrl,
+                liveUrl: session.liveUrl,
+              },
+            },
+          });
+          return;
+        }
         send({
           type: "verb.complete",
           verb: name,
@@ -358,6 +419,32 @@ async function shutdown() {
   process.exit(0);
 }
 
+async function suspend() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  // Flush recordings while CDP is still connected, but intentionally leave
+  // browser contexts and vendor sessions open. The operator needs the live
+  // inspector after wb exits 42, and wb resume reconnects using the persisted
+  // cdpUrl/liveUrl in sidecar_state.
+  for (const [name, info] of sessions) {
+    try {
+      await recording.flush(info, name);
+    } catch (e) {
+      log(`[suspend] flush recording ${name}: ${e.message}`);
+      try {
+        send({
+          type: "slice.recording.failed",
+          session: name,
+          run_id: recording.runId,
+          reason: `suspend_finalize_error: ${e.message}`,
+        });
+      } catch {}
+    }
+  }
+  log("[suspend] leaving browser session alive for external resume");
+  process.exit(0);
+}
+
 // --- Main loop --------------------------------------------------------------
 
 const rl = readline.createInterface({ input: process.stdin, terminal: false });
@@ -393,6 +480,15 @@ async function drainAndShutdown() {
   await shutdown();
 }
 
+async function drainAndSuspend() {
+  try {
+    await sessions.drainAll();
+  } catch (e) {
+    log(`[suspend] drain failed: ${e.message}`);
+  }
+  await suspend();
+}
+
 rl.on("line", (line) => {
   const trimmed = line.trim();
   if (!trimmed) return;
@@ -420,6 +516,9 @@ rl.on("line", (line) => {
     case "shutdown":
       drainAndShutdown();
       break;
+    case "suspend":
+      drainAndSuspend();
+      break;
     default:
       log(`[warn] unknown message type: ${msg.type}`);
   }

package/lib/providers/browser-use.js

@@ -38,7 +38,7 @@ export function createBrowserUseProvider() {
       // bootstrap, baked into the runbook frontmatter by whatever generates
       // it (UI editor, codegen, hand-authored). The slice envelope carries
       // it through; this provider just forwards.
-      const profileId = profile ?? null;
+      const profileId = profile ?? process.env.BROWSER_USE_PROFILE_ID ?? null;
 
       const body = {};
       if (profileId) body.profileId = profileId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wb-browser-runtime",
-  "version": "0.7.0",
+  "version": "0.11.0",
   "description": "Browser sidecar runtime for wb — Playwright over CDP (Browserbase, browser-use) via the wb-sidecar/1 line-framed JSON protocol.",
   "bin": {
     "wb-browser-runtime": "bin/wb-browser-runtime.js"
@@ -21,5 +21,22 @@
     "verbs",
     "vendor",
     "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/workbooks-dev/wb-browser-runtime.git"
+  },
+  "homepage": "https://github.com/workbooks-dev/wb-browser-runtime#readme",
+  "bugs": {
+    "url": "https://github.com/workbooks-dev/wb-browser-runtime/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "wb",
+    "workbooks",
+    "playwright",
+    "browser-automation",
+    "browserbase",
+    "cdp"
   ]
 }

package/verbs/announce_artifact.js

@@ -0,0 +1,74 @@
+import path from "node:path";
+import { promises as fsPromises } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { resolveInside } from "../lib/util.js";
+
+// Ergonomic shorthand for attaching a human-readable label to an artifact
+// already in (or about-to-be-in) $WB_ARTIFACTS_DIR. Writes a sidecar JSON
+// at `<path>.meta.json`; the next Artifacts::sync() pass picks it up and
+// attaches the label to the step.artifact_saved callback event. No upload,
+// no network — just filesystem metadata.
+//
+// Usage:
+//   - save:
+//       path: statement.csv
+//   - announce_artifact:
+//       path: statement.csv
+//       label: "April HSBC statement"
+//       description: "Reconciled balance export"
+//
+// The target artifact need not exist yet — callers may pre-write the
+// sidecar in an earlier block and drop the artifact later. The sidecar
+// only takes effect once the artifact is visible to sync().
+export default {
+  name: "announce_artifact",
+  primaryKey: "path",
+  async execute(_page, args) {
+    const rawPath = typeof args.path === "string" ? args.path.trim() : "";
+    if (!rawPath) {
+      throw new Error("announce_artifact: `path` is required");
+    }
+    const label = typeof args.label === "string" ? args.label : "";
+    if (!label) {
+      throw new Error("announce_artifact: `label` is required");
+    }
+    const description =
+      typeof args.description === "string" ? args.description : undefined;
+
+    const artifactsDir = (process.env.WB_ARTIFACTS_DIR || "").trim();
+    if (!artifactsDir) {
+      throw new Error(
+        "announce_artifact: $WB_ARTIFACTS_DIR is not set — run this workbook via `wb run` (wb exports the dir for you)",
+      );
+    }
+    if (path.isAbsolute(rawPath)) {
+      throw new Error(
+        `announce_artifact: absolute paths are not allowed (got ${rawPath})`,
+      );
+    }
+    const full = resolveInside(artifactsDir, rawPath);
+    if (!full) {
+      throw new Error(
+        `announce_artifact: path escapes artifacts dir (got ${rawPath})`,
+      );
+    }
+
+    const payload = { label };
+    if (description !== undefined) payload.description = description;
+    const serialized = JSON.stringify(payload, null, 2);
+
+    const sidecar = `${full}.meta.json`;
+    await fsPromises.mkdir(path.dirname(sidecar), { recursive: true });
+    const tmp = `${sidecar}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+    try {
+      await fsPromises.writeFile(tmp, serialized, "utf8");
+      await fsPromises.rename(tmp, sidecar);
+    } catch (e) {
+      try {
+        await fsPromises.unlink(tmp);
+      } catch {}
+      throw e;
+    }
+    return `→ ${rawPath} (labelled)`;
+  },
+};

package/verbs/index.js

@@ -18,6 +18,9 @@ import extractVerb from "./extract.js";
 import assertVerb from "./assert.js";
 import evalVerb from "./eval.js";
 import saveVerb from "./save.js";
+import pauseForHumanVerb from "./pause_for_human.js";
+import waitForDropVerb from "./wait_for_drop.js";
+import announceArtifactVerb from "./announce_artifact.js";
 
 const VERBS = [
   gotoVerb,
@@ -30,6 +33,9 @@ const VERBS = [
   assertVerb,
   evalVerb,
   saveVerb,
+  pauseForHumanVerb,
+  waitForDropVerb,
+  announceArtifactVerb,
 ];
 
 export const VERB_REGISTRY = Object.fromEntries(VERBS.map((v) => [v.name, v]));
@@ -66,5 +72,10 @@ export async function runVerb(page, verb, index, ctx, expand) {
     ctx?.secrets,
     ctx?.artifactCache,
   );
-  return handler.execute(page, args, { ...ctx, index });
+  // Mutate-in-place so writes a verb makes to ctx (e.g. eval setting
+  // ctx.lastResult for a later save to pick up) survive to the next verb.
+  // The spread-copy pattern that used to live here silently dropped those
+  // writes, which broke the documented eval → save pattern.
+  ctx.index = index;
+  return handler.execute(page, args, ctx);
 }

package/verbs/pause_for_human.js

@@ -0,0 +1,60 @@
+// pause_for_human — generalized operator-handoff pause.
+//
+// Unlike side-effecting verbs (click, fill, goto) which return a summary
+// and let the slice loop continue, pause_for_human returns a sentinel
+// `{ __pause: {...} }` shape. The dispatcher in ../bin/wb-browser-runtime.js
+// inspects that shape and emits a `slice.paused` frame instead of a
+// `verb.complete`, which flips the Rust side into its pause-and-exit-42 path
+// (pending descriptor written, checkpoint marked paused, process exits).
+//
+// On `wb resume`, the slice re-enters at verb_index + 1 (the verb that
+// paused is skipped — it has no post-resume work). If the pause carried
+// `actions`, the operator's choice is written to
+// `$WB_ARTIFACTS_DIR/pause_result.json` by the Rust side before the sidecar
+// boots again, so downstream bash/python cells can branch on it via a
+// plain file read.
+
+const VALID_RESUME_MODES = ["operator_click", "poll", "timeout"];
+
+export default {
+  name: "pause_for_human",
+  primaryKey: "message",
+  async execute(_page, args, ctx) {
+    const resumeOn = args.resume_on || "operator_click";
+    if (!VALID_RESUME_MODES.includes(resumeOn)) {
+      throw new Error(
+        `pause_for_human: resume_on must be one of ${VALID_RESUME_MODES.join("|")}, got "${resumeOn}"`,
+      );
+    }
+    // Default action: a single "Resume" button. Authors who want
+    // branching on operator choice provide their own `actions` list.
+    const actions =
+      Array.isArray(args.actions) && args.actions.length > 0
+        ? args.actions
+        : [{ label: "Resume", value: null }];
+
+    // Validate action entries early so malformed YAML doesn't reach the
+    // run page as a broken button set.
+    for (const a of actions) {
+      if (!a || typeof a !== "object" || typeof a.label !== "string") {
+        throw new Error(
+          `pause_for_human: each action must be { label: string, value?: any }; got ${JSON.stringify(a)}`,
+        );
+      }
+    }
+
+    return {
+      __pause: {
+        reason: "pause_for_human",
+        message: args.message || "",
+        context_url: args.context_url || null,
+        resume_on: resumeOn,
+        timeout: args.timeout || null,
+        actions,
+        // Dispatcher wraps this with verb_index at emit time so `wb resume`
+        // knows where to re-enter.
+        sidecar_state: {},
+      },
+    };
+  },
+};

package/verbs/wait_for_drop.js

@@ -0,0 +1,235 @@
+// wait_for_drop — wait for files to land in a Google Drive folder.
+//
+// Unlike `pause_for_human`, which hands control back to the Rust side via the
+// `__pause` sentinel + `slice.paused` + exit 42, `wait_for_drop` is *in-slice*:
+// it keeps the sidecar alive through a poll loop, never triggering the
+// pause-and-resume lifecycle. The verb returns a summary when the folder's
+// contents satisfy the predicate, throws on timeout.
+//
+// Trade-off: the run's `wb` process must stay up for the whole wait. No
+// resume-after-crash, no operator-click resume (a follow-up feature). What we
+// get in exchange: simple UX for the runbook author, no out-of-band plumbing.
+//
+// The operator sees progress because we emit a `slice.drop_poll` event on
+// each poll cycle — wb forwards these as `step.drop_poll` callbacks, and the
+// per-event watchdog (SLICE_EVENT_TIMEOUT, resets on every emitted frame)
+// stays alive through the wait.
+//
+// The Paracord relay's Google Drive connector handles auth + transport. We
+// never touch Google's APIs directly — the bearer token is for the relay,
+// not Google. When the relay is down we get a 502 `provider_not_connected`
+// response, which we surface verbatim so the operator sees the actual
+// failure mode.
+
+import { send } from "../lib/io.js";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { resolveInside } from "../lib/util.js";
+
+// Poll-budget guardrails. The spec worst case (10s poll × 30min timeout =
+// 180 relay calls per run) is inside typical per-key quotas; bumping timeout
+// past an hour without extending poll_every would start to matter. These are
+// hard caps: runbooks that exceed them should re-think the approach.
+const MAX_TIMEOUT_MS = 4 * 60 * 60 * 1000; // 4h
+const MIN_POLL_MS = 2_000; // 2s — relay rate-limit breathing room
+
+const FOLDER_URL_RE =
+  /https:\/\/drive\.google\.com\/drive\/(?:u\/\d+\/)?folders\/([A-Za-z0-9_-]+)/;
+
+function extractFolderId(folderUrl) {
+  if (!folderUrl || typeof folderUrl !== "string") {
+    throw new Error("wait_for_drop: folder_url is required");
+  }
+  const m = folderUrl.match(FOLDER_URL_RE);
+  if (!m) {
+    throw new Error(
+      `wait_for_drop: folder_url does not look like a Drive folder URL: ${folderUrl}`,
+    );
+  }
+  return m[1];
+}
+
+// "30s" | "5m" | "1h" | bare integer (seconds). Mirrors wb's Rust-side parser
+// closely enough that authors don't need to context-switch between the two.
+function parseDurationMs(s, fallbackMs) {
+  if (s == null) return fallbackMs;
+  if (typeof s === "number") return s * 1000;
+  const m = String(s).trim().match(/^(\d+)\s*([smh]?)$/i);
+  if (!m) {
+    throw new Error(`wait_for_drop: invalid duration "${s}" (use 30s, 5m, 1h)`);
+  }
+  const n = Number.parseInt(m[1], 10);
+  const unit = (m[2] || "s").toLowerCase();
+  const mult = unit === "h" ? 3600 : unit === "m" ? 60 : 1;
+  return n * mult * 1000;
+}
+
+// Shell-style glob → RegExp. Only `*` + `?` are supported; anything fancier
+// is a smell in a filename pattern.
+function globToRegex(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const re = escaped.replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${re}$`);
+}
+
+function predicateMatches(files, expect, pattern) {
+  if (expect === "at_least_one_file") {
+    return files.length > 0;
+  }
+  if (expect === "filename_matches") {
+    if (!pattern) {
+      throw new Error(
+        "wait_for_drop: filename_matches requires filename_pattern",
+      );
+    }
+    const re = globToRegex(pattern);
+    return files.some((f) => re.test(f.name || ""));
+  }
+  throw new Error(
+    `wait_for_drop: expect must be "at_least_one_file" or "filename_matches", got "${expect}"`,
+  );
+}
+
+async function pollFolder(relayBase, apiKey, folderId) {
+  const q = encodeURIComponent(`'${folderId}' in parents and trashed = false`);
+  const url = `${relayBase.replace(/\/$/, "")}/google_drive/drive/v3/files?q=${q}&fields=files(id,name,mimeType,modifiedTime,size)`;
+  const resp = await fetch(url, {
+    headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+  });
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => "");
+    throw new Error(
+      `wait_for_drop: relay returned ${resp.status} — ${body.slice(0, 200)}`,
+    );
+  }
+  const data = await resp.json().catch(() => ({}));
+  return Array.isArray(data.files) ? data.files : [];
+}
+
+function writeBindArtifact(name, files) {
+  const dir = (process.env.WB_ARTIFACTS_DIR || "").trim();
+  if (!dir) {
+    // Non-fatal; downstream cells might not need the list. Matches the
+    // warn-and-continue posture of other artifact-writing verbs.
+    console.log(
+      `[wait_for_drop] WB_ARTIFACTS_DIR not set; skipping bind_artifact write`,
+    );
+    return null;
+  }
+  mkdirSync(dir, { recursive: true });
+  const target = resolveInside(dir, `${name}.json`);
+  if (!target) {
+    throw new Error(
+      `wait_for_drop: invalid bind_artifact name "${name}" (resolves outside artifacts dir)`,
+    );
+  }
+  writeFileSync(target, JSON.stringify({ files }, null, 2), "utf8");
+  return target;
+}
+
+export default {
+  name: "wait_for_drop",
+  primaryKey: "folder_url",
+  async execute(_page, args, ctx) {
+    const apiKey = (process.env.PARACORD_RELAY_API_KEY || "").trim();
+    if (!apiKey) {
+      throw new Error(
+        "wait_for_drop: PARACORD_RELAY_API_KEY is required (Google Drive connector access)",
+      );
+    }
+    const relayBase = (process.env.PARACORD_RELAY_URL || "").trim();
+    if (!relayBase) {
+      throw new Error(
+        "wait_for_drop: PARACORD_RELAY_URL is required (base URL of the Paracord relay)",
+      );
+    }
+
+    const folderId = extractFolderId(args.folder_url);
+    const expect = args.expect || "at_least_one_file";
+    const pattern = args.filename_pattern || null;
+    if (expect !== "at_least_one_file" && expect !== "filename_matches") {
+      throw new Error(
+        `wait_for_drop: expect must be "at_least_one_file" or "filename_matches", got "${expect}"`,
+      );
+    }
+    if (expect === "filename_matches" && !pattern) {
+      throw new Error(
+        "wait_for_drop: filename_matches requires filename_pattern (e.g. '*.pdf')",
+      );
+    }
+    const pollMs = Math.max(
+      MIN_POLL_MS,
+      parseDurationMs(args.poll_every, 10_000),
+    );
+    const timeoutMs = Math.min(
+      MAX_TIMEOUT_MS,
+      parseDurationMs(args.timeout, 30 * 60 * 1000),
+    );
+    const bindName = args.bind_artifact || "dropped_files";
+    const message =
+      args.message || "Waiting for files to land in the Drive folder";
+
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
+
+    // Announce the wait — gives the run page a frame to pin the widget on,
+    // distinct from the per-poll heartbeats below.
+    send({
+      type: "slice.drop_waiting",
+      verb: "wait_for_drop",
+      verb_index: ctx.index,
+      folder_url: args.folder_url,
+      message,
+      expect,
+      filename_pattern: pattern,
+      poll_every_ms: pollMs,
+      timeout_ms: timeoutMs,
+    });
+
+    let pollCount = 0;
+    while (Date.now() < deadline) {
+      pollCount++;
+      let files;
+      try {
+        files = await pollFolder(relayBase, apiKey, folderId);
+      } catch (e) {
+        // Surface poll errors as a heartbeat with `error:` set, then keep
+        // polling. A transient relay blip shouldn't abort a 30-min wait,
+        // but the operator should see the dashboard flag the degradation.
+        send({
+          type: "slice.drop_poll",
+          verb_index: ctx.index,
+          poll: pollCount,
+          error: String(e.message || e),
+        });
+        await sleep(Math.min(pollMs, Math.max(0, deadline - Date.now())));
+        continue;
+      }
+
+      const matched = predicateMatches(files, expect, pattern);
+      send({
+        type: "slice.drop_poll",
+        verb_index: ctx.index,
+        poll: pollCount,
+        file_count: files.length,
+        matched,
+      });
+
+      if (matched) {
+        const written = writeBindArtifact(bindName, files);
+        return `wait_for_drop: matched after ${pollCount} poll(s) (${files.length} file${files.length === 1 ? "" : "s"})${written ? ` → ${bindName}.json` : ""}`;
+      }
+
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await sleep(Math.min(pollMs, remaining));
+    }
+
+    throw new Error(
+      `wait_for_drop: timed out after ${Math.round(timeoutMs / 1000)}s and ${pollCount} poll(s) — no files matching ${expect}${pattern ? ` (${pattern})` : ""} appeared`,
+    );
+  },
+};
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}