@avasapp/agent-bridge 0.1.0

package/dist/cli.js

@@ -0,0 +1,657 @@
+#!/usr/bin/env node
+import {
+  AgentBridgeCallError,
+  RUNTIME_MARKER,
+  checkName,
+  connect,
+  connectSession,
+  formatDuration,
+  isAlive,
+  listDevices,
+  listSessions,
+  metroHost,
+  openConnection,
+  parseDuration,
+  pickSession,
+  readSession,
+  removeSessionFiles,
+  sessionFiles,
+  sessionRequest,
+  stateDir,
+  writePrivate
+} from "./chunk-UEWFQWCY.js";
+
+// src/cli.ts
+import { readFile } from "fs/promises";
+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/session/cli.ts
+import { spawn } from "child_process";
+import { existsSync, readFileSync, rmSync as rmSync2 } from "fs";
+
+// src/client/session/daemon.ts
+import { appendFileSync, chmodSync, rmSync } from "fs";
+import { createServer } from "net";
+import { createInterface } from "readline";
+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) {
+  const name = checkName(options.name);
+  const dir = stateDir();
+  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}
+`, {
+    mode: 384
+  });
+  const running = readSession(name, dir);
+  if (running)
+    throw new Error(`Session "${name}" is already running (pid ${running.pid})`);
+  const reach = () => openConnection({
+    metro,
+    device: options.device,
+    transport: options.transport
+  });
+  let conn = await reach();
+  const owner = listSessions(dir).find(
+    (s) => s.metro === metro && s.device.deviceId === conn.device.deviceId
+  );
+  if (owner) {
+    conn.close();
+    throw new Error(
+      `${conn.device.name} already belongs to session "${owner.name}". Use --session ${owner.name}, or stop it first.`
+    );
+  }
+  const deviceOf = (c) => ({
+    name: c.device.name,
+    deviceId: c.device.deviceId,
+    platform: c.device.platform
+  });
+  const state = {
+    name,
+    pid: process.pid,
+    socket: files.socket,
+    metro,
+    device: deviceOf(conn),
+    deviceFilter: options.device,
+    transport: conn.transport,
+    startedAt: Date.now(),
+    lastCallAt: Date.now(),
+    idleMs: options.idleMs
+  };
+  const save = () => {
+    if (!finishing) writePrivate(files.state, JSON.stringify(state, null, 2));
+  };
+  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)}`
+        );
+      }
+      stale = false;
+      state.device = deviceOf(conn);
+      state.transport = conn.transport;
+      save();
+      log(`reconnected to ${conn.device.name} via ${conn.transport}`);
+    })().finally(() => {
+      reconnecting = null;
+    });
+    return reconnecting;
+  };
+  const ping = (ms = 1500) => conn.call("bridge.ping", [], Math.min(ms, 1500)).then(
+    (r) => r.ok,
+    () => false
+  );
+  const attempt = async (tool, args, ms) => {
+    try {
+      const result = await conn.call(tool, args, ms);
+      return lostConnection(result) ? { lost: result.error } : { result };
+    } catch (error) {
+      if (await ping(ms)) throw error;
+      return { lost: message(error) };
+    }
+  };
+  const callApp = async (tool, args, ms) => {
+    if (stale || reconnecting)
+      await (reconnecting ?? reconnect("app stopped answering"));
+    let t0 = performance.now();
+    const first = await attempt(tool, args, ms);
+    if (first.result)
+      return { result: first.result, ms: performance.now() - t0 };
+    await reconnect(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}`
+      );
+    return {
+      result: second.result,
+      ms: performance.now() - t0,
+      reconnected: true
+    };
+  };
+  let inflight = 0;
+  let idleTimer;
+  const armIdle = () => {
+    clearTimeout(idleTimer);
+    if (!options.idleMs) return;
+    idleTimer = setTimeout(() => {
+      if (inflight) armIdle();
+      else void teardown("idle", false).then(closeClients);
+    }, options.idleMs);
+  };
+  const touch = () => {
+    if (finishing) return;
+    state.lastCallAt = Date.now();
+    save();
+    armIdle();
+  };
+  const health = options.healthMs === 0 ? void 0 : setInterval(async () => {
+    if (inflight || reconnecting || finishing) return;
+    if (stale || !await ping())
+      await reconnect("no answer to bridge.ping").catch(() => {
+      });
+  }, options.healthMs ?? 5e3);
+  const timer = health;
+  timer?.unref?.();
+  let finishing = null;
+  let resolveDone = () => {
+  };
+  const done = new Promise((r) => {
+    resolveDone = r;
+  });
+  const teardown = (reason, keep) => {
+    finishing ??= (async () => {
+      clearTimeout(idleTimer);
+      clearInterval(health);
+      let restore = null;
+      if (!keep) {
+        restore = await callApp("bridge.restore", [], timeoutMs).then(
+          (r) => r.result,
+          (error) => ({
+            id: "restore",
+            from: "",
+            ok: false,
+            error: message(error),
+            ms: 0
+          })
+        );
+      }
+      conn.close();
+      server.close();
+      removeSessionFiles(name, dir);
+      const outcome = !restore ? "kept app state" : restore.ok ? `restore: ${JSON.stringify(restore.value)}` : `restore: ${restore.error}`;
+      log(`stopped (${reason}); ${outcome}`);
+      const deadline = Date.now() + 2e3;
+      const settle = () => {
+        if (!clients.size || Date.now() > deadline) resolveDone(reason);
+        else setTimeout(settle, 10);
+      };
+      settle();
+      return restore;
+    })();
+    return finishing;
+  };
+  const handle = async (req) => {
+    if (finishing && req.op !== "stop")
+      return { id: req.id, error: `Session "${name}" is stopping` };
+    switch (req.op) {
+      case "call": {
+        if (!req.tool) return { id: req.id, error: "call needs a tool" };
+        inflight++;
+        touch();
+        try {
+          return {
+            id: req.id,
+            ...await callApp(
+              req.tool,
+              req.args ?? [],
+              req.timeoutMs ?? timeoutMs
+            )
+          };
+        } finally {
+          inflight--;
+          touch();
+        }
+      }
+      case "tools":
+        touch();
+        if (stale || reconnecting)
+          await (reconnecting ?? reconnect("app stopped answering"));
+        return { id: req.id, device: conn.device, transport: conn.transport };
+      case "info":
+        return {
+          id: req.id,
+          state,
+          device: conn.device,
+          transport: conn.transport
+        };
+      case "stop":
+        return { id: req.id, restore: await teardown("stop", !!req.keep) };
+      default:
+        return { id: req.id, error: `Unknown op "${String(req.op)}"` };
+    }
+  };
+  const clients = /* @__PURE__ */ new Set();
+  const closeClients = () => {
+    for (const socket of clients) socket.end();
+  };
+  const server = createServer((socket) => {
+    clients.add(socket);
+    socket.on("close", () => clients.delete(socket));
+    socket.on("error", () => {
+    });
+    createInterface({ input: socket }).on("line", async (line) => {
+      let req;
+      try {
+        req = JSON.parse(line);
+      } catch {
+        return;
+      }
+      const res = await handle(req).catch((error) => ({
+        id: req.id,
+        error: message(error)
+      }));
+      if (!socket.writableEnded) socket.write(`${JSON.stringify(res)}
+`);
+      if (req.op === "stop") closeClients();
+    });
+  });
+  if (process.platform !== "win32") rmSync(files.socket, { force: true });
+  try {
+    await new Promise((resolve2, reject) => {
+      server.once("error", reject);
+      server.listen(files.socket, () => {
+        server.off("error", reject);
+        resolve2();
+      });
+    });
+  } catch (error) {
+    conn.close();
+    clearInterval(health);
+    throw error;
+  }
+  if (process.platform !== "win32") chmodSync(files.socket, 384);
+  touch();
+  log(
+    `started: ${conn.device.name} via ${conn.transport} on ${metro}, pid ${process.pid}, idle ${options.idleMs} ms`
+  );
+  return {
+    state,
+    stop: async (keep = false) => {
+      const restore = await teardown("stop", keep);
+      closeClients();
+      return restore;
+    },
+    done
+  };
+}
+
+// src/client/session/cli.ts
+var DAEMON_COMMAND = "__session-daemon";
+function sessionFor(flags) {
+  if (flags["no-session"]) return null;
+  return pickSession({
+    name: flags.session ?? process.env.AGENT_BRIDGE_SESSION,
+    metro: metroHost(flags.metro),
+    device: flags.device,
+    transport: flags.transport
+  });
+}
+var describeRestore = (restore) => {
+  if (!restore) return "App state kept (--keep).";
+  if (restore.ok) return `bridge.restore: ${JSON.stringify(restore.value)}`;
+  if (/Unknown tool/.test(restore.error))
+    return "The app has no bridge.restore; nothing was undone.";
+  return `bridge.restore failed: ${restore.error}`;
+};
+function chosen(flags) {
+  const name = flags.name ?? flags.session ?? process.env.AGENT_BRIDGE_SESSION;
+  if (name) {
+    const state = readSession(checkName(name));
+    if (!state) throw new Error(`No session named "${name}" is running`);
+    return state;
+  }
+  const all = listSessions();
+  if (all.length === 1) return all[0];
+  const match = sessionFor({ ...flags, session: void 0 });
+  if (match) return match;
+  throw new Error(
+    all.length ? `Several sessions are running (${all.map((s) => s.name).join(", ")}); pass --name` : "No session is running"
+  );
+}
+function freeName() {
+  const taken = new Set(listSessions().map((s) => s.name));
+  let name = "default";
+  for (let n = 2; taken.has(name); n++) name = `default-${n}`;
+  return name;
+}
+async function start(flags) {
+  const name = checkName(flags.name ?? freeName());
+  const running = readSession(name);
+  if (running)
+    throw new Error(`Session "${name}" is already running (pid ${running.pid})`);
+  const files = sessionFiles(name);
+  rmSync2(files.error, { force: true });
+  const args = [
+    DAEMON_COMMAND,
+    "--name",
+    name,
+    "--metro",
+    metroHost(flags.metro)
+  ];
+  args.push("--idle", String(parseDuration(flags.idle ?? "15m")));
+  if (flags.device) args.push("--device", flags.device);
+  if (flags.transport) args.push("--transport", flags.transport);
+  if (flags.timeout) args.push("--timeout", flags.timeout);
+  const child = spawn(
+    process.execPath,
+    [...process.execArgv, process.argv[1], ...args],
+    { detached: true, stdio: "ignore", windowsHide: true }
+  );
+  const state = await new Promise((resolve2, reject) => {
+    const deadline = Date.now() + 3e4;
+    let exited = false;
+    child.once("exit", () => {
+      exited = true;
+    });
+    const tick = setInterval(() => {
+      const ready = readSession(name);
+      const failed = existsSync(files.error);
+      if (ready && ready.pid === child.pid) {
+        clearInterval(tick);
+        resolve2(ready);
+      } 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}`;
+        rmSync2(files.error, { force: true });
+        reject(new Error(reason));
+      }
+    }, 50);
+  });
+  child.unref();
+  const idle = state.idleMs ? `, stops after ${formatDuration(state.idleMs)} idle` : "";
+  console.log(
+    `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."
+  );
+}
+async function stop(flags) {
+  const state = chosen(flags);
+  const res = await sessionRequest(state, {
+    op: "stop",
+    keep: !!flags.keep
+  }).catch(() => null);
+  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;
+  }
+  console.log(
+    `Stopped session "${state.name}". ${describeRestore(res.restore)}`
+  );
+}
+function list() {
+  const sessions = listSessions();
+  if (!sessions.length) console.log("No sessions.");
+  for (const s of sessions) {
+    const left = s.idleMs ? `${formatDuration(s.lastCallAt + s.idleMs - Date.now())} left` : "no idle limit";
+    console.log(
+      `${s.name.padEnd(12)} ${s.device.name}  ${s.transport}  ${s.metro}  ${left}  pid ${s.pid}`
+    );
+  }
+}
+async function status(flags) {
+  const state = chosen(flags);
+  const res = await sessionRequest(state, { op: "info" });
+  if (res.error) throw new Error(res.error);
+  console.log(
+    JSON.stringify({ ...res.state, tools: res.device?.tools.length }, null, 2)
+  );
+}
+async function sessionCommand(sub, flags) {
+  switch (sub) {
+    case "start":
+      return start(flags);
+    case "stop":
+      return stop(flags);
+    case "list":
+      return list();
+    case "status":
+      return status(flags);
+    default:
+      throw new Error("Usage: agent-bridge session start|stop|list|status");
+  }
+}
+async function daemonMain(flags) {
+  const name = checkName(flags.name ?? "default");
+  let daemon;
+  try {
+    daemon = await runSessionDaemon({
+      name,
+      metro: flags.metro,
+      device: flags.device,
+      transport: flags.transport,
+      idleMs: parseDuration(flags.idle ?? "15m"),
+      timeoutMs: flags.timeout ? Number(flags.timeout) : void 0
+    });
+  } catch (error) {
+    writePrivate(
+      sessionFiles(name).error,
+      error instanceof Error ? error.message : String(error)
+    );
+    process.exit(1);
+  }
+  for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"])
+    process.on(signal, () => void daemon.stop());
+  await daemon.done;
+  process.exit(0);
+}
+
+// src/cli.ts
+var HELP = `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 run <flow.mjs|.ts>         Run a flow: export default async ({ step, call }) => {}
+  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 list | status [--name n]
+  While a session matches --metro/--device, call, tools and run use it.
+
+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)
+  --strict               run: exit non-zero if the app logged an error
+  --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 main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      metro: { type: "string" },
+      device: { type: "string" },
+      transport: { type: "string" },
+      timeout: { type: "string" },
+      strict: { type: "boolean" },
+      name: { type: "string" },
+      idle: { type: "string" },
+      keep: { type: "boolean" },
+      session: { type: "string" },
+      "no-session": { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    }
+  });
+  const [command, ...rest] = positionals;
+  if (!command || values.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  const options = {
+    metro: values.metro,
+    device: values.device,
+    transport: values.transport,
+    timeoutMs: values.timeout ? Number(values.timeout) : void 0
+  };
+  const withBridge = async (fn) => {
+    const session = sessionFor(values);
+    const bridge = session ? await connectSession({
+      name: session.name,
+      timeoutMs: options.timeoutMs
+    }) : await connect(options);
+    try {
+      await fn(bridge);
+    } finally {
+      bridge.close();
+    }
+  };
+  switch (command) {
+    case "devices": {
+      const devices = await listDevices(options);
+      if (!devices.length) console.log("No apps connected.");
+      for (const d of devices) {
+        const extra = d.tools !== void 0 ? `  ${d.tools} tools  ${d.deviceId}` : "";
+        console.log(`${d.transport.padEnd(5)} ${d.name}${extra}`);
+      }
+      return;
+    }
+    case "tools":
+      return withBridge(async (bridge) => {
+        console.log(`${bridge.device.name} via ${bridge.transport}`);
+        for (const t of bridge.tools())
+          console.log(`  ${t.name.padEnd(22)} ${t.description ?? ""}`);
+      });
+    case "call": {
+      const [tool, raw] = rest;
+      if (!tool) throw new Error("Usage: agent-bridge call <tool> [args]");
+      return withBridge(async (bridge) => {
+        const { value, ms, appMs, logs } = await bridge.timed(tool, ...parseCallArgs(raw)).catch((error) => {
+          for (const e of failedLogs(error)) console.error(logLine(e));
+          throw error;
+        });
+        console.log(JSON.stringify(value, null, 2));
+        for (const e of logs) console.error(logLine(e));
+        console.error(
+          `${tool} via ${bridge.transport}: ${ms.toFixed(1)} ms round trip, ${appMs} ms in the app`
+        );
+      });
+    }
+    case "run": {
+      const [file] = rest;
+      if (!file) throw new Error("Usage: agent-bridge run <flow file>");
+      const flow = await import(pathToFileURL(resolve(file)).href);
+      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;
+            }
+          );
+          total += ms;
+          console.log(
+            `${String(++n).padStart(2, "0")} ${label.padEnd(30)} ${ms.toFixed(1).padStart(7)} ms`
+          );
+          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;
+      });
+    }
+    case "session":
+      return sessionCommand(rest[0], values);
+    case DAEMON_COMMAND:
+      return daemonMain(values);
+    case "assert-absent": {
+      if (!rest.length)
+        throw new Error("Usage: agent-bridge assert-absent <bundle files...>");
+      const found = [];
+      for (const file of rest) {
+        if ((await readFile(file)).includes(RUNTIME_MARKER)) found.push(file);
+      }
+      if (found.length) {
+        console.error(
+          `agent-bridge is in a release bundle: ${found.join(", ")}`
+        );
+        process.exitCode = 1;
+      } else {
+        console.log(`agent-bridge is absent from ${rest.length} file(s).`);
+      }
+      return;
+    }
+    default:
+      throw new Error(`Unknown command "${command}".
+
+${HELP}`);
+  }
+}
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});