@avasapp/agent-bridge 0.2.0 → 0.4.0

package/dist/cli.js

@@ -5,21 +5,28 @@ import {
   checkName,
   connect,
   connectSession,
+  encodeLine,
+  explicitMetro,
+  flowScenarios,
   formatDuration,
   isAlive,
   listDevices,
   listSessions,
+  logLine,
   metroHost,
   openConnection,
   parseDuration,
+  parseScenarioFlag,
   pickSession,
+  projectRoot,
   readSession,
   removeSessionFiles,
+  runFlow,
   sessionFiles,
   sessionRequest,
   stateDir,
   writePrivate
-} from "./chunk-LBYZ5JHF.js";
+} from "./chunk-AJD3XTNT.js";
 
 // src/cli.ts
 import { readFile } from "fs/promises";
@@ -27,22 +34,572 @@ import { resolve } from "path";
 import { pathToFileURL } from "url";
 import { parseArgs } from "util";
 
-// src/client/log-lines.ts
-function logLine(entry) {
-  const where = entry.during ? ` during ${entry.during}` : entry.after ? ` after ${entry.after}` : "";
-  const first = entry.message.split("\n")[0] ?? "";
-  const text = first.length > 300 ? `${first.slice(0, 300)}...` : first;
-  return `! ${entry.level}${where}: ${text}`;
+// src/client/batch.ts
+import { readFileSync } from "fs";
+import { mkdir, readdir, stat } from "fs/promises";
+import { join } from "path";
+import { createInterface } from "readline";
+
+// src/client/output.ts
+import { writeFile } from "fs/promises";
+var OUTPUT_LIMIT_BYTES = 32 * 1024;
+var kb = (bytes) => bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+function shapeOf(value) {
+  const kind = (v) => Array.isArray(v) ? `array(${v.length})` : v === null ? "null" : typeof v === "object" ? `object(${Object.keys(v).length} keys)` : typeof v === "string" ? `string(${v.length})` : typeof v;
+  if (Array.isArray(value)) {
+    const first = value.length ? kind(value[0]) : void 0;
+    return { type: kind(value), ...first && { first } };
+  }
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value).map(([k, v]) => [k, kind(v)])
+    );
+  return { type: kind(value) };
+}
+var fileSummary = (file, bytes, value) => ({
+  file,
+  bytes,
+  size: kb(bytes),
+  shape: shapeOf(value)
+});
+var tooLarge = (bytes, value, outKind = "file") => ({
+  resultTooLarge: true,
+  bytes,
+  size: kb(bytes),
+  shape: shapeOf(value),
+  hint: `Not printed: the result is ${kb(bytes)}. Re-run with --out <${outKind === "dir" ? "dir" : "file"}> to write it to a ${outKind === "dir" ? "file in that directory" : "file"}, or --full to print it, or narrow the call (a path, a filter, a smaller page).`
+});
+async function shapedResult(value, options = {}) {
+  const json = JSON.stringify(value, null, 2) ?? "null";
+  const bytes = Buffer.byteLength(json);
+  if (options.out) {
+    await writeFile(options.out, `${json}
+`);
+    return fileSummary(options.out, bytes, value);
+  }
+  if (options.full || bytes <= (options.limit ?? OUTPUT_LIMIT_BYTES))
+    return value === void 0 ? null : value;
+  return tooLarge(bytes, value, options.outKind);
+}
+async function renderResult(value, options = {}) {
+  const json = JSON.stringify(value, null, 2) ?? "null";
+  const bytes = Buffer.byteLength(json);
+  if (options.out) {
+    await writeFile(options.out, `${json}
+`);
+    return JSON.stringify(fileSummary(options.out, bytes, value), null, 2);
+  }
+  if (options.full || bytes <= (options.limit ?? OUTPUT_LIMIT_BYTES))
+    return json;
+  return JSON.stringify(tooLarge(bytes, value), null, 2);
+}
+
+// src/client/batch.ts
+function parseCallArgs(raw) {
+  if (raw === void 0) return [];
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return [raw];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+var readArgFile = (path) => {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    throw new Error(
+      `Cannot read arguments file ${path}: ${error.code ?? error.message}`
+    );
+  }
+};
+function fileJson(ref, read) {
+  const path = ref.slice(1);
+  if (!path)
+    throw new Error(
+      `An argument that is just "@" needs a path (@file, or @- for stdin). To pass the text itself, quote it as JSON: '"@"'`
+    );
+  const text = read(path);
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new Error(
+      `${path === "-" ? "stdin" : path} is not valid JSON (${error instanceof Error ? error.message : error})`
+    );
+  }
+}
+function parseCallArgv(argv, read = readArgFile) {
+  if (argv.length === 1) {
+    const [only] = argv;
+    if (!only.startsWith("@")) return parseCallArgs(only);
+    const value = fileJson(only, read);
+    return Array.isArray(value) ? value : [value];
+  }
+  return argv.map((word) => {
+    if (word.startsWith("@")) return fileJson(word, read);
+    try {
+      return JSON.parse(word);
+    } catch {
+      return word;
+    }
+  });
+}
+var BatchParseError = class extends Error {
+  constructor(tool, message2) {
+    super(message2);
+    this.tool = tool;
+  }
+  tool;
+};
+function parseBatchLine(line) {
+  const text = line.trim();
+  if (!text || text.startsWith("#")) return null;
+  const at = text.search(/\s/);
+  if (at < 0) return { tool: text, args: [] };
+  const tool = text.slice(0, at);
+  const raw = text.slice(at).trim();
+  if (/^[[{"]/.test(raw)) {
+    try {
+      JSON.parse(raw);
+    } catch (error) {
+      throw new BatchParseError(
+        tool,
+        `Arguments start like JSON but don't parse (${error instanceof Error ? error.message : error}). Fix the JSON, or quote the text to send it as a string: ${JSON.stringify(raw)}`
+      );
+    }
+  }
+  if (raw.startsWith("@")) {
+    try {
+      return {
+        tool,
+        args: parseCallArgv([raw], (path) => {
+          if (path === "-")
+            throw new Error("@- is not available in a batch: stdin carries the calls");
+          return readArgFile(path);
+        })
+      };
+    } catch (error) {
+      throw new BatchParseError(tool, error.message);
+    }
+  }
+  return { tool, args: parseCallArgs(raw) };
+}
+async function runCall(bridge, { tool, args }) {
+  const t0 = performance.now();
+  try {
+    const { value, ms, appMs, logs, notice } = await bridge.timed(tool, ...args);
+    return { tool, ok: true, ms, appMs, value, logs, notice };
+  } catch (error) {
+    const ms = performance.now() - t0;
+    const failed = error instanceof AgentBridgeCallError ? error : void 0;
+    return {
+      tool,
+      ok: false,
+      ms,
+      error: error instanceof Error ? error.message : String(error),
+      logs: failed?.logs ?? [],
+      notice: failed?.notice
+    };
+  }
+}
+async function runLine(bridge, line) {
+  try {
+    const parsed = parseBatchLine(line);
+    return parsed ? await runCall(bridge, parsed) : null;
+  } catch (error) {
+    if (!(error instanceof BatchParseError)) throw error;
+    return { tool: error.tool, ok: false, ms: 0, error: error.message, logs: [] };
+  }
+}
+var MAX_TIME_RUNS = 1e3;
+var DEFAULT_TIME_RUNS = 10;
+function parseTime(rest) {
+  const m = /^(.*?)(?:\s+x(\d+))?$/.exec(rest.trim());
+  const call = parseBatchLine(m?.[1] ?? "");
+  if (!call) return null;
+  const wanted = Math.max(1, Number(m?.[2] ?? DEFAULT_TIME_RUNS));
+  return { call, runs: Math.min(wanted, MAX_TIME_RUNS), capped: wanted > MAX_TIME_RUNS };
+}
+function spread(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = sorted.length >> 1;
+  const median = sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+  return { min: sorted[0], median, max: sorted.at(-1) };
+}
+var round = (ms) => Math.round(ms * 10) / 10;
+async function dotLine(bridge, line) {
+  const [name = ""] = line.split(/\s+/);
+  const rest = line.slice(name.length).trim();
+  switch (name) {
+    case ".exit":
+      return null;
+    case ".tools":
+      return {
+        tool: name,
+        ok: true,
+        ms: 0,
+        value: bridge.tools().filter((t) => t.name.startsWith(rest)).map((t) => ({ name: t.name, description: t.description }))
+      };
+    case ".pending":
+      return runCall(bridge, { tool: "bridge.pending", args: [] });
+    case ".restore":
+      return runCall(bridge, { tool: "bridge.restore", args: [] });
+    case ".time": {
+      let request;
+      try {
+        request = parseTime(rest);
+      } catch (error) {
+        return { tool: name, ok: false, ms: 0, error: error.message };
+      }
+      if (!request)
+        return { tool: name, ok: false, ms: 0, error: "Usage: .time <tool> [args] [xN]" };
+      const trips = [];
+      const inApp = [];
+      for (let i = 0; i < request.runs; i++) {
+        const outcome = await runCall(bridge, request.call);
+        if (!outcome.ok) return outcome;
+        trips.push(outcome.ms);
+        inApp.push(outcome.appMs ?? 0);
+      }
+      const r = (s) => ({
+        min: round(s.min),
+        median: round(s.median),
+        max: round(s.max)
+      });
+      return {
+        tool: name,
+        ok: true,
+        ms: 0,
+        value: {
+          call: request.call.tool,
+          runs: request.runs,
+          roundTrip: r(spread(trips)),
+          inApp: r(spread(inApp))
+        }
+      };
+    }
+    default:
+      return {
+        tool: name,
+        ok: false,
+        ms: 0,
+        error: `Unknown command ${name}. In batch mode: .tools, .time, .pending, .restore, .exit`
+      };
+  }
+}
+async function checkOutDir(dir) {
+  const info = await stat(dir).catch(() => null);
+  if (!info) return mkdir(dir, { recursive: true });
+  if (!info.isDirectory())
+    throw new Error(`--out ${dir} is a file; with --batch it must be a directory`);
+  if ((await readdir(dir)).length)
+    throw new Error(
+      `--out ${dir} is not empty; use a new or empty directory so old files aren't mistaken for this run's`
+    );
+}
+async function runBatch(bridge, input, options = {}) {
+  const write = options.write ?? ((line) => console.log(line));
+  if (options.outDir) await checkOutDir(options.outDir);
+  const result = { calls: 0, failed: 0 };
+  const rl = createInterface({ input, crlfDelay: Number.POSITIVE_INFINITY });
+  let stopped = false;
+  try {
+    for await (const line of rl) {
+      const text = line.trim();
+      const outcome = text.startsWith(".") ? await dotLine(bridge, text) : await runLine(bridge, line);
+      if (text.startsWith(".") && outcome === null) break;
+      if (!outcome) continue;
+      result.calls++;
+      const raw = outcome;
+      const record = {
+        tool: raw.tool,
+        ok: raw.ok,
+        ms: round(raw.ms)
+      };
+      if (raw.appMs !== void 0) record.appMs = raw.appMs;
+      if (raw.ok) {
+        try {
+          record.value = await shapedResult(raw.value, {
+            full: options.full,
+            outKind: "dir",
+            out: options.outDir ? join(
+              options.outDir,
+              `${result.calls}-${String(raw.tool).replace(/[^\w.-]/g, "_")}.json`
+            ) : void 0
+          });
+        } catch (error) {
+          record.ok = false;
+          record.error = `Could not write the result: ${error instanceof Error ? error.message : error}`;
+        }
+      } else record.error = raw.error;
+      const logs = raw.logs;
+      if (logs?.length) record.logs = logs;
+      if (raw.notice) record.notice = raw.notice;
+      write(JSON.stringify(record));
+      if (!record.ok) {
+        result.failed++;
+        if (options.stopOnError) {
+          stopped = true;
+          break;
+        }
+      }
+    }
+  } finally {
+    rl.close();
+    if (stopped) input.destroy?.();
+  }
+  return result;
+}
+
+// src/client/repl.ts
+import { appendFileSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join as join2 } from "path";
+import { createInterface as createInterface2 } from "readline";
+var HISTORY_LIMIT = 500;
+var DEFAULT_HISTORY_FILE = join2(
+  homedir(),
+  ".agent-bridge",
+  "repl_history"
+);
+var DOT_COMMANDS = [
+  ".help",
+  ".tools",
+  ".time",
+  ".pending",
+  ".restore",
+  ".exit"
+];
+var HELP = `Type a call the way \`agent-bridge call\` takes it: tool [args]
+  screen.press "Save"          one JSON value is one argument
+  store.set ["user", {"a":1}]   a JSON array is the argument list
+Dot commands
+  .tools [prefix]     List tools, optionally starting with prefix
+  .time <call> [xN]   Run a call N times (default 10, at most ${MAX_TIME_RUNS}); min/median/max
+  .pending            bridge.pending: what bridge.restore would undo
+  .restore            bridge.restore
+  .help               This text
+  .exit               Leave (also Ctrl-D)
+Ctrl-C clears the line, or gives up waiting for a running call (the app may still finish it).
+Tab completes tool names and dot commands.`;
+function complete(line, toolNames) {
+  const first = /^\s*(\S*)$/.exec(line);
+  if (first) {
+    const word = first[1];
+    const pool = word.startsWith(".") ? DOT_COMMANDS : toolNames;
+    return [pool.filter((n) => n.startsWith(word)), word];
+  }
+  const arg = /^\s*\.(?:tools|time)\s+(\S*)$/.exec(line);
+  if (arg) {
+    const word = arg[1];
+    return [toolNames.filter((n) => n.startsWith(word)), word];
+  }
+  return [[], line];
+}
+function loadHistory(file) {
+  let lines;
+  try {
+    lines = readFileSync2(file, "utf8").split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+  if (lines.length <= HISTORY_LIMIT) return lines;
+  saveHistory(file, lines);
+  return lines.slice(-HISTORY_LIMIT);
+}
+function saveHistory(file, lines) {
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${lines.slice(-HISTORY_LIMIT).join("\n")}
+`, {
+      mode: 384
+    });
+  } catch {
+  }
+}
+function appendHistory(file, line) {
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, `${line}
+`, { mode: 384 });
+  } catch {
+  }
+}
+var fixed = (s) => `min ${s.min.toFixed(1)} / median ${s.median.toFixed(1)} / max ${s.max.toFixed(1)} ms`;
+var INTERRUPTED = "Interrupted. The call may still finish in the app.";
+async function runRepl(bridge, options) {
+  const { output } = options;
+  const tty = !!options.tty;
+  const { historyFile } = options;
+  const paint = (code, text) => tty && !process.env.NO_COLOR ? `\x1B[${code}m${text}\x1B[0m` : text;
+  const print = (text = "") => {
+    output.write(`${text}
+`);
+  };
+  const toolNames = () => bridge.tools().map((t) => t.name);
+  const history = historyFile ? loadHistory(historyFile) : [];
+  const rl = createInterface2({
+    input: options.input,
+    output,
+    terminal: tty,
+    prompt: tty ? "agent-bridge> " : "",
+    history: [...history].reverse(),
+    historySize: HISTORY_LIMIT,
+    completer: (line) => complete(line, toolNames())
+  });
+  let closed = false;
+  rl.once("close", () => {
+    closed = true;
+  });
+  const prompt = () => {
+    if (!closed) rl.prompt();
+  };
+  let giveUp = null;
+  rl.on("SIGINT", () => {
+    if (giveUp) return giveUp();
+    print("^C");
+    if (tty) rl.write(null, { ctrl: true, name: "u" });
+    prompt();
+  });
+  const interruptible = async (work) => {
+    let live = true;
+    let release;
+    const aborted = new Promise((r) => {
+      release = r;
+    });
+    giveUp = () => {
+      live = false;
+      release();
+    };
+    try {
+      await Promise.race([work(() => live), aborted]);
+    } finally {
+      giveUp = null;
+    }
+    if (!live) print(paint(33, INTERRUPTED));
+  };
+  const show = async (outcome) => {
+    for (const e of outcome.logs) print(paint(2, logLine(e)));
+    if (outcome.notice) print(paint(33, `Warning: ${outcome.notice}`));
+    if (!outcome.ok) {
+      print(paint(31, outcome.error ?? "failed"));
+      return;
+    }
+    print(await renderResult(outcome.value, { full: options.full }));
+    print(
+      paint(
+        2,
+        `${outcome.ms.toFixed(1)} ms round trip, ${outcome.appMs} ms in the app`
+      )
+    );
+  };
+  const time = async (rest, live) => {
+    let request;
+    try {
+      request = parseTime(rest);
+    } catch (error) {
+      return print(paint(31, error instanceof Error ? error.message : String(error)));
+    }
+    if (!request) return print("Usage: .time <tool> [args] [xN]");
+    const { call, runs } = request;
+    if (request.capped)
+      print(paint(33, `Running ${runs} times: .time is capped at ${MAX_TIME_RUNS}.`));
+    const trips = [];
+    const inApp = [];
+    for (let i = 0; i < runs; i++) {
+      if (!live()) return;
+      const outcome = await runCall(bridge, call);
+      if (!live()) return;
+      if (!outcome.ok) {
+        await show(outcome);
+        return;
+      }
+      trips.push(outcome.ms);
+      inApp.push(outcome.appMs ?? 0);
+    }
+    print(`${call.tool} x${runs}`);
+    print(`  round trip  ${fixed(spread(trips))}`);
+    print(`  in the app  ${fixed(spread(inApp))}`);
+  };
+  const tool = (name) => (live) => runCall(bridge, { tool: name, args: [] }).then(
+    (outcome) => live() ? show(outcome) : void 0
+  );
+  const dot = async (line) => {
+    const [name = "", ...more] = line.split(/\s+/);
+    const rest = line.slice(name.length).trim();
+    switch (name) {
+      case ".exit":
+        return false;
+      case ".help":
+        print(HELP);
+        break;
+      case ".tools": {
+        const list2 = bridge.tools().filter((t) => t.name.startsWith(more[0] ?? ""));
+        if (!list2.length) print("No tools match.");
+        for (const t of list2)
+          print(`  ${t.name.padEnd(22)} ${t.description ?? ""}`);
+        break;
+      }
+      case ".time":
+        await interruptible((live) => time(rest, live));
+        break;
+      case ".pending":
+        await interruptible(tool("bridge.pending"));
+        break;
+      case ".restore":
+        await interruptible(tool("bridge.restore"));
+        break;
+      default:
+        print(paint(31, `Unknown command ${name}. Try .help`));
+    }
+    return true;
+  };
+  options.onReady?.(rl);
+  if (tty) print("agent-bridge repl. .help for commands, .exit or Ctrl-D to leave.");
+  prompt();
+  let eof = false;
+  try {
+    for await (const raw of rl) {
+      const line = raw.trim();
+      if (line && !line.startsWith("#")) {
+        if (historyFile) appendHistory(historyFile, line);
+        if (line.startsWith(".")) {
+          if (!await dot(line)) break;
+        } else {
+          await interruptible(async (live) => {
+            const outcome = await runLine(bridge, line);
+            if (outcome && live()) await show(outcome);
+          });
+        }
+      }
+      prompt();
+    }
+    eof = closed;
+  } finally {
+    rl.close();
+    if (tty && eof) output.write("\n");
+  }
 }
 
 // src/client/session/cli.ts
 import { spawn } from "child_process";
-import { existsSync, readFileSync, rmSync as rmSync2 } from "fs";
+import { existsSync, readFileSync as readFileSync3, rmSync as rmSync2 } from "fs";
 
 // src/client/session/daemon.ts
-import { appendFileSync, chmodSync, rmSync } from "fs";
+import { appendFileSync as appendFileSync2, chmodSync, rmSync } from "fs";
 import { createServer } from "net";
-import { createInterface } from "readline";
+import { createInterface as createInterface3 } from "readline";
+var RELOAD = "app.reload";
+var pause = (ms, signal) => new Promise((resolve2) => {
+  const done = () => {
+    clearTimeout(timer);
+    signal.removeEventListener("abort", done);
+    resolve2();
+  };
+  const timer = setTimeout(done, ms);
+  signal.addEventListener("abort", done, { once: true });
+});
 var message = (error) => error instanceof Error ? error.message : String(error);
 var lostConnection = (r) => !r.ok && (r.from === "" || /socket closed|closed the debugger|not open/i.test(r.error));
 async function runSessionDaemon(options) {
@@ -51,17 +608,22 @@ async function runSessionDaemon(options) {
   const files = sessionFiles(name, dir);
   const metro = metroHost(options.metro);
   const timeoutMs = options.timeoutMs ?? 1e4;
-  const log = (text) => appendFileSync(files.log, `${(/* @__PURE__ */ new Date()).toISOString()} ${text}
+  const reloadWaitMs = options.reloadWaitMs ?? 2e4;
+  const log = (text) => appendFileSync2(files.log, `${(/* @__PURE__ */ new Date()).toISOString()} ${text}
 `, {
     mode: 384
   });
   const running = readSession(name, dir);
   if (running)
     throw new Error(`Session "${name}" is already running (pid ${running.pid})`);
-  const reach = () => openConnection({
+  const attemptMs = options.attemptMs ?? 12e3;
+  const stopping = new AbortController();
+  const cutOff = new AbortController();
+  const reach = (signal) => openConnection({
     metro,
     device: options.device,
-    transport: options.transport
+    transport: options.transport,
+    ...signal && { signal, timeoutMs: attemptMs }
   });
   let conn = await reach();
   const owner = listSessions(dir).find(
@@ -83,6 +645,7 @@ async function runSessionDaemon(options) {
     pid: process.pid,
     socket: files.socket,
     metro,
+    project: options.project ?? projectRoot(),
     device: deviceOf(conn),
     deviceFilter: options.device,
     transport: conn.transport,
@@ -93,22 +656,64 @@ async function runSessionDaemon(options) {
   const save = () => {
     if (!finishing) writePrivate(files.state, JSON.stringify(state, null, 2));
   };
+  let knownLoad = conn.device.loadId;
+  let lastPending = [];
+  const reloads = [];
+  let unseen = [];
+  const noteReload = () => {
+    const lost = lastPending;
+    lastPending = [];
+    const note = `app reloaded; ${lost.length} pending restore${lost.length === 1 ? "" : "s"} lost${lost.length ? `: ${lost.join(", ")}` : ""}`;
+    reloads.push(note);
+    unseen.push(note);
+    log(`warning: ${note}`);
+  };
+  const observe = (r) => {
+    if (!r.loadId) return;
+    if (knownLoad && r.loadId !== knownLoad) noteReload();
+    knownLoad = r.loadId;
+    lastPending = r.pending ?? [];
+  };
+  const takeNotice = () => {
+    const notice = unseen.join("; ");
+    unseen = [];
+    return notice ? { notice } : {};
+  };
+  let reloadingUntil = 0;
   let stale = false;
   let reconnecting = null;
   const reconnect = (reason) => {
     reconnecting ??= (async () => {
       log(`reconnecting: ${reason}`);
       conn.close();
-      try {
-        conn = await reach();
-      } catch (error) {
-        stale = true;
-        log(`reconnect failed: ${message(error)}`);
-        throw new Error(
-          `The app is gone (${reason}). Reconnecting failed: ${message(error)}`
-        );
+      const patient = Date.now() < reloadingUntil;
+      const deadline = Date.now() + (patient ? reloadWaitMs : 0);
+      for (; ; ) {
+        try {
+          const next = await reach(cutOff.signal);
+          if (patient && knownLoad && next.device.loadId === knownLoad) {
+            next.close();
+            throw new Error("the old runtime still answers");
+          }
+          conn = next;
+          break;
+        } catch (error) {
+          if (stopping.signal.aborted || Date.now() >= deadline) {
+            stale = true;
+            log(`reconnect failed: ${message(error)}`);
+            throw new Error(
+              patient ? `The app is reloading; its bridge isn't ready yet (${message(error)})` : `The app is gone (${reason}). Reconnecting failed: ${message(error)}`
+            );
+          }
+          await pause(300, stopping.signal);
+        }
       }
       stale = false;
+      reloadingUntil = 0;
+      if (conn.device.loadId) {
+        if (knownLoad && conn.device.loadId !== knownLoad) noteReload();
+        knownLoad = conn.device.loadId;
+      }
       state.device = deviceOf(conn);
       state.transport = conn.transport;
       save();
@@ -118,8 +723,33 @@ async function runSessionDaemon(options) {
     });
     return reconnecting;
   };
+  const connected = async (reason = "app stopped answering") => {
+    const attempt2 = reconnecting ?? reconnect(reason);
+    const wait = Date.now() < reloadingUntil ? reloadWaitMs + 2 * attemptMs + 500 : 2 * attemptMs + 500;
+    let timer2;
+    try {
+      await Promise.race([
+        attempt2,
+        new Promise((_, reject) => {
+          timer2 = setTimeout(
+            () => reject(
+              new Error(
+                "app not connected; reconnecting. Try again in a moment"
+              )
+            ),
+            wait
+          );
+        })
+      ]);
+    } finally {
+      clearTimeout(timer2);
+    }
+  };
   const ping = (ms = 1500) => conn.call("bridge.ping", [], Math.min(ms, 1500)).then(
-    (r) => r.ok,
+    (r) => {
+      if (r.ok) observe(r);
+      return r.ok;
+    },
     () => false
   );
   const attempt = async (tool, args, ms) => {
@@ -132,25 +762,43 @@ async function runSessionDaemon(options) {
     }
   };
   const callApp = async (tool, args, ms) => {
-    if (stale || reconnecting)
-      await (reconnecting ?? reconnect("app stopped answering"));
+    if (stale || reconnecting) await connected();
     let t0 = performance.now();
     const first = await attempt(tool, args, ms);
-    if (first.result)
+    if (first.result) {
+      observe(first.result);
+      if (tool === RELOAD && first.result.ok) waitForReload();
       return { result: first.result, ms: performance.now() - t0 };
-    await reconnect(first.lost);
+    }
+    if (tool === RELOAD) {
+      waitForReload();
+      const result = {
+        id: "",
+        from: "",
+        ok: true,
+        value: { reloading: true },
+        ms: 0
+      };
+      return { result, ms: performance.now() - t0 };
+    }
+    await connected(first.lost);
     t0 = performance.now();
     const second = await attempt(tool, args, ms);
     if (!second.result)
       throw new Error(
         `The app stopped answering after a reconnect: ${second.lost}`
       );
+    observe(second.result);
     return {
       result: second.result,
       ms: performance.now() - t0,
       reconnected: true
     };
   };
+  const waitForReload = () => {
+    reloadingUntil = Date.now() + reloadWaitMs;
+    stale = true;
+  };
   let inflight = 0;
   let idleTimer;
   const armIdle = () => {
@@ -185,6 +833,8 @@ async function runSessionDaemon(options) {
     finishing ??= (async () => {
       clearTimeout(idleTimer);
       clearInterval(health);
+      stopping.abort();
+      const cut = setTimeout(() => cutOff.abort(), Math.min(attemptMs, 5e3));
       let restore = null;
       if (!keep) {
         restore = await callApp("bridge.restore", [], timeoutMs).then(
@@ -198,6 +848,8 @@ async function runSessionDaemon(options) {
           })
         );
       }
+      clearTimeout(cut);
+      cutOff.abort();
       conn.close();
       server.close();
       removeSessionFiles(name, dir);
@@ -213,6 +865,14 @@ async function runSessionDaemon(options) {
     })();
     return finishing;
   };
+  const readPending = async () => {
+    try {
+      const { result } = await callApp("bridge.pending", [], timeoutMs);
+      return result.ok ? result.value : void 0;
+    } catch {
+      return void 0;
+    }
+  };
   const handle = async (req) => {
     if (finishing && req.op !== "stop")
       return { id: req.id, error: `Session "${name}" is stopping` };
@@ -222,14 +882,14 @@ async function runSessionDaemon(options) {
         inflight++;
         touch();
         try {
-          return {
-            id: req.id,
-            ...await callApp(
-              req.tool,
-              req.args ?? [],
-              req.timeoutMs ?? timeoutMs
-            )
-          };
+          const answer = await callApp(
+            req.tool,
+            req.args ?? [],
+            req.timeoutMs ?? timeoutMs
+          );
+          return { id: req.id, ...answer, ...takeNotice() };
+        } catch (error) {
+          return { id: req.id, error: message(error), ...takeNotice() };
         } finally {
           inflight--;
           touch();
@@ -237,8 +897,7 @@ async function runSessionDaemon(options) {
       }
       case "tools":
         touch();
-        if (stale || reconnecting)
-          await (reconnecting ?? reconnect("app stopped answering"));
+        if (stale || reconnecting) await connected();
         return { id: req.id, device: conn.device, transport: conn.transport };
       case "info":
         return {
@@ -247,8 +906,18 @@ async function runSessionDaemon(options) {
           device: conn.device,
           transport: conn.transport
         };
-      case "stop":
-        return { id: req.id, restore: await teardown("stop", !!req.keep) };
+      case "stop": {
+        if (req.dryRun && finishing)
+          return { id: req.id, error: `Session "${name}" is stopping` };
+        const pending = req.dryRun || req.keep ? await readPending() : void 0;
+        if (req.dryRun) return { id: req.id, pending };
+        return {
+          id: req.id,
+          restore: await teardown("stop", !!req.keep),
+          ...pending && { pending },
+          ...reloads.length && { notice: reloads.join("; ") }
+        };
+      }
       default:
         return { id: req.id, error: `Unknown op "${String(req.op)}"` };
     }
@@ -262,7 +931,7 @@ async function runSessionDaemon(options) {
     socket.on("close", () => clients.delete(socket));
     socket.on("error", () => {
     });
-    createInterface({ input: socket }).on("line", async (line) => {
+    createInterface3({ input: socket }).on("line", async (line) => {
       let req;
       try {
         req = JSON.parse(line);
@@ -273,9 +942,8 @@ async function runSessionDaemon(options) {
         id: req.id,
         error: message(error)
       }));
-      if (!socket.writableEnded) socket.write(`${JSON.stringify(res)}
-`);
-      if (req.op === "stop") closeClients();
+      if (!socket.writableEnded) socket.write(encodeLine(res));
+      if (req.op === "stop" && !req.dryRun) closeClients();
     });
   });
   if (process.platform !== "win32") rmSync(files.socket, { force: true });
@@ -294,6 +962,7 @@ async function runSessionDaemon(options) {
   }
   if (process.platform !== "win32") chmodSync(files.socket, 384);
   touch();
+  await ping();
   log(
     `started: ${conn.device.name} via ${conn.transport} on ${metro}, pid ${process.pid}, idle ${options.idleMs} ms`
   );
@@ -314,7 +983,7 @@ function sessionFor(flags) {
   if (flags["no-session"]) return null;
   return pickSession({
     name: flags.session ?? process.env.AGENT_BRIDGE_SESSION,
-    metro: metroHost(flags.metro),
+    metro: explicitMetro(flags.metro),
     device: flags.device,
     transport: flags.transport
   });
@@ -385,7 +1054,7 @@ async function start(flags) {
       } else if (failed || exited || Date.now() > deadline) {
         clearInterval(tick);
         if (!exited) child.kill();
-        const reason = failed ? readFileSync(files.error, "utf8") : exited ? `The session exited early; see ${files.log}` : `The session didn't connect within 30 s; see ${files.log}`;
+        const reason = failed ? readFileSync3(files.error, "utf8") : exited ? `The session exited early; see ${files.log}` : `The session didn't connect within 30 s; see ${files.log}`;
         rmSync2(files.error, { force: true });
         reject(new Error(reason));
       }
@@ -397,23 +1066,54 @@ async function start(flags) {
     `Session "${state.name}": ${state.device.name} via ${state.transport}${idle}`
   );
   console.log(
-    "`call`, `tools` and `run` go through it; `agent-bridge session stop` undoes and ends it."
+    "`call`, `tools`, `repl` and `run` go through it; `agent-bridge session stop` undoes and ends it."
   );
 }
+var describePending = (pending) => Object.entries(pending).map(
+  ([area, detail]) => detail === true ? `  ${area}` : `  ${area}: ${JSON.stringify(detail)}`
+).join("\n");
 async function stop(flags) {
   const state = chosen(flags);
+  const dryRun = !!flags["dry-run"];
   const res = await sessionRequest(state, {
     op: "stop",
-    keep: !!flags.keep
+    keep: !!flags.keep,
+    dryRun
   }).catch(() => null);
+  if (dryRun && (!res || res.error)) {
+    console.log(
+      `Dry run failed: ${res?.error ?? `session "${state.name}" didn't answer`}. Nothing was stopped or restored; check \`agent-bridge session list\`.`
+    );
+    return;
+  }
   if (!res || res.error) {
     if (isAlive(state.pid)) process.kill(state.pid, "SIGTERM");
     console.log(`Session "${state.name}" didn't answer; sent it SIGTERM.`);
     return;
   }
+  if (dryRun && res.restore !== void 0) {
+    console.log(
+      `Stopped session "${state.name}": its daemon predates --dry-run, so it stopped and did not just list. ${describeRestore(res.restore)}`
+    );
+    return;
+  }
+  if (dryRun) {
+    const areas = Object.keys(res.pending ?? {});
+    console.log(
+      !res.pending ? `Session "${state.name}" is still running. The app has no bridge.pending, so nothing can be listed.` : areas.length ? `Session "${state.name}" is still running. bridge.restore would undo:
+${describePending(res.pending)}` : `Session "${state.name}" is still running. Nothing is pending; bridge.restore would undo nothing.`
+    );
+    return;
+  }
   console.log(
     `Stopped session "${state.name}". ${describeRestore(res.restore)}`
   );
+  if (res.pending && Object.keys(res.pending).length)
+    console.log(
+      `Warning: still pending, and a later bridge.restore will undo it (run store.commit to keep a store as it is):
+${describePending(res.pending)}`
+    );
+  if (res.notice) console.log(`Warning: ${res.notice}`);
 }
 function list() {
   const sessions = listSessions();
@@ -473,42 +1173,60 @@ async function daemonMain(flags) {
 }
 
 // src/cli.ts
-var HELP = `agent-bridge: drive a running React Native app from an agent
+var HELP2 = `agent-bridge: drive a running React Native app from an agent
 
 Usage
   agent-bridge devices                    Apps connected to Metro
   agent-bridge tools                      Tools the app exposes
   agent-bridge call <tool> [args]         Call a tool. args: a JSON array, or one JSON value
+  agent-bridge call <tool> @args.json     Same, read from a file (@- is stdin): no argv size limit
+  agent-bridge call <tool> '"/feed"' @feed.json
+                                          With several words each is one argument; @file is
+                                          that file's JSON. A string starting with @: '"@user"'
+  agent-bridge call --batch               Read \`tool args\` lines from stdin (args may be @file); one JSON line per call, one connection
+  agent-bridge repl                       Interactive prompt (history, tab completion, .help). With
+                                          stdin not a terminal it behaves like call --batch
   agent-bridge run <flow.mjs|.ts>         Run a flow: export default async ({ step, call }) => {}
+                                          export const scenario = 'signedIn' applies it first
+                                          and runs bridge.restore after, even on failure
+  agent-bridge scenarios                  Scenarios the app defines (scenario.apply applies one)
   agent-bridge assert-absent <files...>   Fail if a release bundle contains the bridge
 
 Sessions: one connection for all of an agent's calls
   agent-bridge session start [--name n] [--idle 15m]   Connect once in the background
   agent-bridge session stop [--name n] [--keep]        bridge.restore (unless --keep), then end
+  agent-bridge session stop --dry-run                  List what bridge.restore would undo; keep running
   agent-bridge session list | status [--name n]
-  While a session matches --metro/--device, call, tools and run use it.
+  call, tools, repl and run use this project's running session (the only one, or the one
+  matching --metro/--device), and print its name. With several, pass --session <name>.
 
 Options
   --metro <host:port>    Metro dev server (env AGENT_BRIDGE_METRO, default localhost:8081)
   --device <text>        Pick an app when several are connected
   --transport <name>     auto (default), expo or cdp
   --timeout <ms>         Per-call timeout (default 10000)
+  --out <file>           call: write the result to a file; print its size and shape
+                         (--batch: a directory, one <n>-<tool>.json per call)
+  --stop-on-error        call --batch: stop after the first failed call
+  --full                 call: print results over 32 KB instead of a summary
   --strict               run: exit non-zero if the app logged an error
+  --scenario <name>      run: also apply this scenario (repeatable). Options as
+                         JSON after "=": --scenario 'signedIn={"user":{"name":"Ada"}}'
   --session <name>       Use this session (env AGENT_BRIDGE_SESSION)
   --no-session           Connect directly even if a session is running
 `;
 var failedLogs = (error) => error instanceof AgentBridgeCallError ? error.logs : [];
-function parseCallArgs(raw) {
-  if (raw === void 0) return [];
-  let value;
-  try {
-    value = JSON.parse(raw);
-  } catch {
-    return [raw];
-  }
-  return Array.isArray(value) ? value : [value];
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
 }
 async function main() {
+  process.on("uncaughtException", (error) => {
+    if (error.code === "EPIPE") process.exit(process.exitCode ?? 0);
+    console.error(error);
+    process.exit(1);
+  });
   const { values, positionals } = parseArgs({
     allowPositionals: true,
     options: {
@@ -517,9 +1235,15 @@ async function main() {
       transport: { type: "string" },
       timeout: { type: "string" },
       strict: { type: "boolean" },
+      out: { type: "string" },
+      full: { type: "boolean" },
+      batch: { type: "boolean" },
+      "stop-on-error": { type: "boolean" },
+      scenario: { type: "string", multiple: true },
       name: { type: "string" },
       idle: { type: "string" },
       keep: { type: "boolean" },
+      "dry-run": { type: "boolean" },
       session: { type: "string" },
       "no-session": { type: "boolean" },
       help: { type: "boolean", short: "h" }
@@ -527,7 +1251,7 @@ async function main() {
   });
   const [command, ...rest] = positionals;
   if (!command || values.help) {
-    process.stdout.write(HELP);
+    process.stdout.write(HELP2);
     return;
   }
   const options = {
@@ -538,6 +1262,7 @@ async function main() {
   };
   const withBridge = async (fn) => {
     const session = sessionFor(values);
+    if (session) console.error(`Using session "${session.name}"`);
     const bridge = session ? await connectSession({
       name: session.name,
       timeoutMs: options.timeoutMs
@@ -548,6 +1273,14 @@ async function main() {
       bridge.close();
     }
   };
+  const batch = async (bridge) => {
+    const { failed } = await runBatch(bridge, process.stdin, {
+      stopOnError: values["stop-on-error"],
+      full: values.full,
+      outDir: values.out
+    });
+    if (failed) process.exitCode = 1;
+  };
   switch (command) {
     case "devices": {
       const devices = await listDevices(options);
@@ -565,65 +1298,82 @@ async function main() {
           console.log(`  ${t.name.padEnd(22)} ${t.description ?? ""}`);
       });
     case "call": {
-      const [tool, raw] = rest;
+      if (values.batch) {
+        if (rest.length)
+          throw new Error("call --batch reads calls from stdin; pass no tool");
+        return withBridge((bridge) => batch(bridge));
+      }
+      const [tool, ...words] = rest;
       if (!tool) throw new Error("Usage: agent-bridge call <tool> [args]");
+      if (words.filter((w) => w === "@-").length > 1)
+        throw new Error("Only one argument can be @- (stdin)");
+      const stdin = words.includes("@-") ? await readStdin() : "";
+      const args = parseCallArgv(
+        words,
+        (path) => path === "-" ? stdin : readArgFile(path)
+      );
       return withBridge(async (bridge) => {
-        const { value, ms, appMs, logs } = await bridge.timed(tool, ...parseCallArgs(raw)).catch((error) => {
+        const { value, ms, appMs, logs, notice } = await bridge.timed(tool, ...args).catch((error) => {
           for (const e of failedLogs(error)) console.error(logLine(e));
           throw error;
         });
-        console.log(JSON.stringify(value, null, 2));
+        console.log(
+          await renderResult(value, { out: values.out, full: values.full })
+        );
         for (const e of logs) console.error(logLine(e));
+        if (notice) console.error(`Warning: ${notice}`);
         console.error(
           `${tool} via ${bridge.transport}: ${ms.toFixed(1)} ms round trip, ${appMs} ms in the app`
         );
       });
     }
+    case "repl":
+      if (values.out)
+        throw new Error(
+          "repl has no --out; use `call --batch --out <dir>` to write results to files"
+        );
+      return withBridge(async (bridge) => {
+        if (!process.stdin.isTTY) return batch(bridge);
+        await runRepl(bridge, {
+          input: process.stdin,
+          output: process.stdout,
+          tty: !!process.stdout.isTTY,
+          historyFile: DEFAULT_HISTORY_FILE,
+          full: values.full
+        });
+      });
     case "run": {
       const [file] = rest;
       if (!file) throw new Error("Usage: agent-bridge run <flow file>");
       const flow = await import(pathToFileURL(resolve(file)).href);
+      flowScenarios(flow);
+      const extra = (values.scenario ?? []).map(parseScenarioFlag);
       return withBridge(async (bridge) => {
-        let n = 0;
-        let total = 0;
-        let errors = 0;
-        const t0 = performance.now();
-        const report = (logs) => {
-          errors += logs.length;
-          for (const e of logs) console.log(`   ${logLine(e)}`);
-        };
-        const timed = async (tool, ...args) => {
-          try {
-            const result = await bridge.timed(tool, ...args);
-            report(result.logs);
-            return result;
-          } catch (error) {
-            report(failedLogs(error));
-            throw error;
-          }
-        };
-        const call = async (tool, ...args) => (await timed(tool, ...args)).value;
-        const step = async (label, tool, ...args) => {
-          const { value, ms, logs } = await bridge.timed(tool, ...args).catch(
-            (error) => {
-              report(failedLogs(error));
-              throw error;
-            }
+        const { errors, restoreErrors } = await runFlow(bridge, flow, {
+          scenarios: extra
+        });
+        if (values.strict && errors || restoreErrors.length)
+          process.exitCode = 1;
+      });
+    }
+    case "scenarios":
+      return withBridge(async (bridge) => {
+        if (!bridge.tools().some((t) => t.name === "scenario.list")) {
+          console.log(
+            `${bridge.device.name} defines no scenarios (pass \`scenarios\` to useAgentBridge).`
           );
-          total += ms;
+          return;
+        }
+        const list2 = await bridge.call("scenario.list");
+        console.log(`${bridge.device.name} via ${bridge.transport}`);
+        for (const s of list2) {
           console.log(
-            `${String(++n).padStart(2, "0")} ${label.padEnd(30)} ${ms.toFixed(1).padStart(7)} ms`
+            `  ${s.name.padEnd(20)} ${s.active ? "(active) " : ""}${s.description ?? ""}`
           );
-          report(logs);
-          return value;
-        };
-        await flow.default({ bridge: { ...bridge, timed, call }, call, step });
-        console.log(
-          `${n} steps, ${total.toFixed(1)} ms in calls, ${(performance.now() - t0).toFixed(0)} ms wall (${bridge.transport})${errors ? `, ${errors} error${errors === 1 ? "" : "s"}` : ""}`
-        );
-        if (values.strict && errors) process.exitCode = 1;
+          if (s.options)
+            console.log(`  ${"".padEnd(20)} options: ${JSON.stringify(s.options)}`);
+        }
       });
-    }
     case "session":
       return sessionCommand(rest[0], values);
     case DAEMON_COMMAND:
@@ -648,7 +1398,7 @@ async function main() {
     default:
       throw new Error(`Unknown command "${command}".
 
-${HELP}`);
+${HELP2}`);
   }
 }
 main().catch((error) => {