@avasapp/agent-bridge 0.2.0 → 0.4.0

package/dist/client/index.cjs

@@ -34,23 +34,30 @@ __export(client_exports, {
   connect: () => connect,
   connectSession: () => connectSession,
   listDevices: () => listDevices,
-  listSessions: () => listSessions
+  listSessions: () => listSessions,
+  runFlow: () => runFlow
 });
 module.exports = __toCommonJS(client_exports);
 
 // src/client/discover.ts
+var within = (ms, signal) => signal ? AbortSignal.any([AbortSignal.timeout(ms), signal]) : AbortSignal.timeout(ms);
 var DEFAULT_METRO = "localhost:8081";
+var stripScheme = (metro) => metro.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+function explicitMetro(metro) {
+  const given = metro ?? process.env.AGENT_BRIDGE_METRO;
+  return given ? stripScheme(given) : void 0;
+}
 function metroHost(metro) {
-  return (metro ?? process.env.AGENT_BRIDGE_METRO ?? DEFAULT_METRO).replace(/^https?:\/\//, "").replace(/\/+$/, "");
+  return stripScheme(metro ?? process.env.AGENT_BRIDGE_METRO ?? DEFAULT_METRO);
 }
-async function expoHostUri(metro) {
+async function expoHostUri(metro, signal) {
   try {
     const res = await fetch(`http://${metro}/`, {
       headers: {
         "expo-platform": "ios",
         accept: "application/expo+json,application/json"
       },
-      signal: AbortSignal.timeout(3e3)
+      signal: within(3e3, signal)
     });
     if (!res.ok) return null;
     const manifest = await res.json();
@@ -59,9 +66,9 @@ async function expoHostUri(metro) {
     return null;
   }
 }
-async function listCdpTargets(metro) {
+async function listCdpTargets(metro, signal) {
   const res = await fetch(`http://${metro}/json/list`, {
-    signal: AbortSignal.timeout(3e3)
+    signal: within(3e3, signal)
   });
   if (!res.ok)
     throw new Error(
@@ -100,21 +107,43 @@ function toAsciiJson(value) {
 
 // src/client/connection.ts
 var import_ws = __toESM(require("ws"), 1);
-function openSocket(url, headers) {
-  return new Promise((resolve, reject) => {
+var OPEN_SOCKET_MS = 5e3;
+var OpenGaveUp = class extends Error {
+};
+function openSocket(url, headers, signal, timeoutMs = OPEN_SOCKET_MS) {
+  return new Promise((resolve2, reject) => {
     const ws = new import_ws.default(url, headers ? { headers } : void 0);
     let opened = false;
+    const giveUp = (why) => {
+      if (opened) return;
+      reject(new OpenGaveUp(`Could not open ${url}: ${why}`));
+      ws.terminate();
+    };
+    const timer = setTimeout(
+      () => giveUp(`no answer within ${timeoutMs} ms`),
+      timeoutMs
+    );
+    const onAbort = () => giveUp("aborted");
+    if (signal?.aborted) onAbort();
+    else signal?.addEventListener("abort", onAbort, { once: true });
+    const settled = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
     ws.on("error", (event) => {
       if (opened) return;
+      settled();
       const message = event?.message ?? String(event);
       reject(new Error(`Could not open ${url}: ${message}`));
     });
     ws.once("close", () => {
+      settled();
       if (!opened) reject(new Error(`${url} closed before opening`));
     });
     ws.once("open", () => {
+      settled();
       opened = true;
-      resolve(ws);
+      resolve2(ws);
     });
   });
 }
@@ -123,7 +152,7 @@ function createPending() {
   const waiting = /* @__PURE__ */ new Map();
   return {
     wait(id, tool, timeoutMs) {
-      return new Promise((resolve, reject) => {
+      return new Promise((resolve2, reject) => {
         const timer = setTimeout(() => {
           waiting.delete(id);
           reject(new Error(`No reply to "${tool}" within ${timeoutMs} ms`));
@@ -131,7 +160,7 @@ function createPending() {
         waiting.set(id, (result) => {
           clearTimeout(timer);
           waiting.delete(id);
-          resolve(result);
+          resolve2(result);
         });
       });
     },
@@ -148,10 +177,15 @@ function createPending() {
 
 // src/client/expo.ts
 var deviceLabel = (d) => `${d.name} (${d.platform}, ${d.deviceId})`;
-async function openBroadcast(metro, discoveryMs) {
-  const ws = await openSocket(`ws://${metro}/expo-dev-plugins/broadcast`);
+async function openBroadcast(metro, discoveryMs, signal) {
+  const ws = await openSocket(
+    `ws://${metro}/expo-dev-plugins/broadcast`,
+    void 0,
+    signal
+  );
   const devices = /* @__PURE__ */ new Map();
   const pending = createPending();
+  const announced = [];
   ws.on("message", (data, isBinary) => {
     if (isBinary) return;
     let frame;
@@ -163,7 +197,9 @@ async function openBroadcast(metro, discoveryMs) {
     if (frame.messageKey?.pluginName !== PLUGIN_NAME) return;
     if (frame.messageKey.method === "hello:reply") {
       const info = frame.payload;
+      const fresh = !devices.has(info.deviceId);
       devices.set(info.deviceId, info);
+      if (fresh) for (const listener of announced) listener(info);
     } else if (frame.messageKey.method === "result") {
       pending.settle(frame.payload);
     }
@@ -176,16 +212,32 @@ async function openBroadcast(metro, discoveryMs) {
     })
   );
   send("hello", {});
-  await new Promise((r) => setTimeout(r, discoveryMs));
-  return { ws, devices, pending, send };
+  await new Promise((resolve2, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      ws.terminate();
+      reject(new Error("aborted while waiting for hello replies"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve2();
+    }, discoveryMs);
+    if (signal?.aborted) onAbort();
+    else signal?.addEventListener("abort", onAbort, { once: true });
+  });
+  return { ws, devices, pending, send, announced };
 }
 async function listExpoDevices(metro, discoveryMs = 600) {
   const { ws, devices } = await openBroadcast(metro, discoveryMs);
   ws.close();
   return [...devices.values()];
 }
-async function connectExpo(metro, device, discoveryMs = 600) {
-  const { ws, devices, pending, send } = await openBroadcast(metro, discoveryMs);
+async function connectExpo(metro, device, discoveryMs = 600, signal) {
+  const { ws, devices, pending, send, announced } = await openBroadcast(
+    metro,
+    discoveryMs,
+    signal
+  );
   let info;
   try {
     info = pickOne([...devices.values()], device, deviceLabel);
@@ -193,10 +245,25 @@ async function connectExpo(metro, device, discoveryMs = 600) {
     ws.close();
     throw error;
   }
+  let superseded = null;
+  announced.push((next) => {
+    if (superseded || next.name !== info.name || next.platform !== info.platform)
+      return;
+    superseded = `${info.name} announced a new bridge (${next.deviceId}); the app reloaded`;
+    pending.failAll(superseded);
+  });
   return {
     transport: "expo",
     device: info,
     call(tool, args, timeoutMs) {
+      if (superseded)
+        return Promise.resolve({
+          id: "",
+          from: "",
+          ok: false,
+          error: superseded,
+          ms: 0
+        });
       const call = {
         id: newCallId(),
         tool,
@@ -216,17 +283,26 @@ var import_ws2 = __toESM(require("ws"), 1);
 var CannotEvaluate = class extends Error {
 };
 var targetLabel = (t) => `${t.title}${t.deviceName ? ` [${t.deviceName}]` : ""}`;
-async function connectCdp(metro, device) {
-  const target = pickOne(await listCdpTargets(metro), device, targetLabel);
-  const hostUri = await expoHostUri(metro);
+async function connectCdp(metro, device, signal) {
+  const target = pickOne(
+    await listCdpTargets(metro, signal),
+    device,
+    targetLabel
+  );
+  const hostUri = await expoHostUri(metro, signal);
   const port = metro.split(":")[1] ?? "8081";
   const origin = hostUri ? `http://${hostUri}` : `http://localhost:${port}`;
   const closedEarly = `Metro closed the debugger socket. Origin sent: ${origin}. Is that the host Metro advertises?`;
-  const ws = await openSocket(target.webSocketDebuggerUrl, {
-    Origin: origin
-  }).catch(() => {
-    throw new Error(closedEarly);
+  const ws = await openSocket(
+    target.webSocketDebuggerUrl,
+    { Origin: origin },
+    signal
+  ).catch((error) => {
+    throw error instanceof OpenGaveUp ? error : new Error(closedEarly);
   });
+  const dropOnAbort = () => ws.terminate();
+  if (signal?.aborted) dropOnAbort();
+  else signal?.addEventListener("abort", dropOnAbort, { once: true });
   let seq = 0;
   let answered = false;
   const commands = /* @__PURE__ */ new Map();
@@ -247,13 +323,13 @@ async function connectCdp(metro, device) {
     commands.clear();
     pending.failAll(reason);
   });
-  const send = (method, params = {}) => new Promise((resolve, reject) => {
+  const send = (method, params = {}) => new Promise((resolve2, reject) => {
     if (ws.readyState !== import_ws2.default.OPEN) {
       reject(new Error(answered ? "The debugger socket closed" : closedEarly));
       return;
     }
     const id = ++seq;
-    commands.set(id, { resolve, reject });
+    commands.set(id, { resolve: resolve2, reject });
     ws.send(JSON.stringify({ id, method, params }));
   });
   const evaluate = async (expression) => {
@@ -269,25 +345,35 @@ async function connectCdp(metro, device) {
     }
     return message.result?.result?.value;
   };
-  await send("Runtime.enable");
-  await send("Runtime.addBinding", { name: CDP_REPLY_BINDING });
+  try {
+    await send("Runtime.enable");
+    await send("Runtime.addBinding", { name: CDP_REPLY_BINDING });
+  } catch (error) {
+    ws.terminate();
+    signal?.removeEventListener("abort", dropOnAbort);
+    throw error;
+  }
   let info;
   try {
     info = JSON.parse(
       String(await evaluate(`${CDP_GLOBAL}.info()`))
     );
   } catch (error) {
-    ws.close();
+    ws.terminate();
+    signal?.removeEventListener("abort", dropOnAbort);
     throw new Error(
       error instanceof CannotEvaluate ? `The debugger for ${targetLabel(target)} can't run code (no Runtime.evaluate, as in Expo Go on Android). Use --transport expo, or a dev build.` : `agent-bridge isn't running in ${targetLabel(target)}. Is useAgentBridge mounted in a dev build?`
     );
   }
+  signal?.removeEventListener("abort", dropOnAbort);
   return {
     transport: "cdp",
     device: { ...info, name: `${info.name} (${targetLabel(target)})` },
     async call(tool, args, timeoutMs) {
       const call = { id: newCallId(), tool, args };
       const reply = pending.wait(call.id, tool, timeoutMs);
+      reply.catch(() => {
+      });
       try {
         await evaluate(
           `${CDP_GLOBAL}.dispatch(${JSON.stringify(toAsciiJson(call))})`
@@ -308,37 +394,186 @@ async function connectCdp(metro, device) {
 }
 
 // src/client/open.ts
+var OPEN_MS = 15e3;
+var abortable = (work, signal) => new Promise((resolve2, reject) => {
+  const onAbort = () => reject(new Error("aborted"));
+  signal.addEventListener("abort", onAbort, { once: true });
+  work.then(resolve2, reject).finally(() => {
+    signal.removeEventListener("abort", onAbort);
+  });
+});
+function phase(options, run) {
+  const ms = options.timeoutMs ?? OPEN_MS;
+  const timeout = AbortSignal.timeout(ms);
+  const signal = options.signal ? AbortSignal.any([timeout, options.signal]) : timeout;
+  const attempt = run(signal);
+  attempt.then(
+    (late) => {
+      if (signal.aborted) late.close();
+    },
+    () => {
+    }
+  );
+  return abortable(attempt, signal).catch((error) => {
+    if (!signal.aborted) throw error;
+    throw new OpenGaveUp(
+      timeout.aborted ? `Timed out after ${ms} ms opening a connection to Metro` : "Connecting was aborted"
+    );
+  });
+}
 async function openConnection(options = {}) {
   const metro = metroHost(options.metro);
   const want = options.transport ?? "auto";
   let expoError;
   if (want !== "cdp") {
     try {
-      return await connectExpo(metro, options.device);
+      return await phase(
+        options,
+        (signal) => connectExpo(metro, options.device, void 0, signal)
+      );
     } catch (error) {
-      if (want === "expo") throw error;
+      if (want === "expo" || options.signal?.aborted) throw error;
       expoError = error;
     }
   }
   try {
-    return await connectCdp(metro, options.device);
+    return await phase(
+      options,
+      (signal) => connectCdp(metro, options.device, signal)
+    );
   } catch (error) {
     const expoNote = expoError ? ` (Expo socket: ${String(expoError)})` : "";
+    const text = `${error instanceof Error ? error.message : String(error)}${expoNote}`;
+    throw error instanceof OpenGaveUp ? new OpenGaveUp(text) : new Error(text);
+  }
+}
+
+// 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/flow.ts
+function flowScenarios(flow) {
+  const declared = [
+    ...flow.scenario === void 0 ? [] : [flow.scenario],
+    ...flow.scenarios ?? []
+  ];
+  return declared.map((s) => {
+    if (typeof s === "string") return { name: s };
+    if (s && typeof s === "object" && typeof s.name === "string") return s;
+    throw new Error(
+      `A flow's scenario is a name or { name, options }, not ${JSON.stringify(s)}`
+    );
+  });
+}
+function mergeScenarios(declared, extra) {
+  const names = new Set(extra.map((s) => s.name));
+  return [...declared.filter((s) => !names.has(s.name)), ...extra];
+}
+var failedLogs = (error) => error instanceof AgentBridgeCallError ? error.logs : [];
+var failedNotice = (error) => error instanceof AgentBridgeCallError ? error.notice : void 0;
+async function runFlow(bridge, flow, options = {}) {
+  const print = options.print ?? console.log;
+  const needs = mergeScenarios(flowScenarios(flow), options.scenarios ?? []);
+  let n = 0;
+  let total = 0;
+  let errors = 0;
+  const t0 = performance.now();
+  const notices = [];
+  const report = (logs, notice) => {
+    errors += logs.length;
+    for (const e of logs) print(`   ${logLine(e)}`);
+    if (notice) {
+      notices.push(notice);
+      print(`   ! ${notice}`);
+    }
+  };
+  const timed = async (tool, ...args) => {
+    try {
+      const result = await bridge.timed(tool, ...args);
+      report(result.logs, result.notice);
+      return result;
+    } catch (error) {
+      report(failedLogs(error), failedNotice(error));
+      throw error;
+    }
+  };
+  const call = async (tool, ...args) => (await timed(tool, ...args)).value;
+  const step = async (label, tool, ...given) => {
+    const args = given.length === 1 && Array.isArray(given[0]) ? given[0] : given;
+    const { value, ms, logs, notice } = await bridge.timed(tool, ...args).catch((error) => {
+      report(failedLogs(error), failedNotice(error));
+      throw error;
+    });
+    total += ms;
+    print(
+      `${String(++n).padStart(2, "0")} ${label.padEnd(30)} ${ms.toFixed(1).padStart(7)} ms`
+    );
+    report(logs, notice);
+    return value;
+  };
+  const restoreErrors = [];
+  const applied = {};
+  if (needs.length && !bridge.tools().some((t) => t.name === "scenario.apply"))
     throw new Error(
-      `${error instanceof Error ? error.message : String(error)}${expoNote}`
+      `The flow needs scenario "${needs[0].name}", but the app defines none: pass \`scenarios\` to useAgentBridge.`
     );
+  try {
+    for (const { name, options: options2 } of needs) {
+      const args = options2 === void 0 ? [name] : [name, options2];
+      applied[name] = await step(`scenario ${name}`, "scenario.apply", ...args);
+    }
+    await flow.default({
+      bridge: { ...bridge, timed, call },
+      call,
+      step,
+      scenarios: applied
+    });
+  } finally {
+    if (needs.length) {
+      try {
+        const result = await step("restore", "bridge.restore");
+        for (const [name, value] of Object.entries(result ?? {})) {
+          const error = value?.error;
+          if (error !== void 0) restoreErrors.push(`${name}: ${String(error)}`);
+        }
+      } catch (error) {
+        restoreErrors.push(
+          `bridge.restore: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+      for (const e of restoreErrors) print(`   ! restore failed: ${e}`);
+    }
   }
+  print(
+    `${n} steps, ${total.toFixed(1)} ms in calls, ${(performance.now() - t0).toFixed(0)} ms wall (${bridge.transport})${errors ? `, ${errors} error${errors === 1 ? "" : "s"}` : ""}${notices.length ? ", the app reloaded" : ""}`
+  );
+  return { steps: n, errors, restoreErrors, notices };
 }
 
 // src/client/session/client.ts
 var import_node_net = require("net");
 var import_node_readline = require("readline");
 
+// src/client/session/protocol.ts
+var encodeLine = (message) => `${JSON.stringify(message).replace(/[\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16)}`)}
+`;
+
 // src/client/session/state.ts
 var import_node_crypto = require("crypto");
 var import_node_fs = require("fs");
 var import_node_os = require("os");
 var import_node_path = require("path");
+function projectRoot(from = process.cwd()) {
+  for (let dir = (0, import_node_path.resolve)(from); ; dir = (0, import_node_path.dirname)(dir)) {
+    if ((0, import_node_fs.existsSync)((0, import_node_path.join)(dir, "package.json"))) return dir;
+    if ((0, import_node_path.dirname)(dir) === dir) return (0, import_node_path.resolve)(from);
+  }
+}
 var uid = () => process.getuid?.() ?? (0, import_node_os.userInfo)().username;
 function privateDir(dir) {
   (0, import_node_fs.mkdirSync)(dir, { recursive: true, mode: 448 });
@@ -419,15 +654,21 @@ function pickSession(filter) {
     return named;
   }
   const device = filter.device?.toLowerCase();
+  const explicit = !!(filter.metro || device || filter.transport && filter.transport !== "auto");
+  const project = projectRoot();
   const matching = listSessions().filter(
-    (s) => s.metro === filter.metro && (!device || s.device.name.toLowerCase().includes(device) || s.device.deviceId.toLowerCase().includes(device)) && (!filter.transport || filter.transport === "auto" || filter.transport === s.transport)
+    (s) => (explicit || s.project === project) && (!filter.metro || s.metro === filter.metro) && (!device || s.device.name.toLowerCase().includes(device) || s.device.deviceId.toLowerCase().includes(device)) && (!filter.transport || filter.transport === "auto" || filter.transport === s.transport)
   );
-  return matching.length === 1 ? matching[0] : null;
+  if (matching.length > 1)
+    throw new Error(
+      `Several sessions match (${matching.map((s) => `${s.name}: ${s.device.name} on ${s.metro}`).join("; ")}); pick one by name (--session, or --name for session stop/status), or narrow with --metro/--device`
+    );
+  return matching[0] ?? null;
 }
 
 // src/client/session/client.ts
 function openSessionLink(state) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const socket = (0, import_node_net.createConnection)(state.socket);
     const waiting = /* @__PURE__ */ new Map();
     let seq = 0;
@@ -435,7 +676,7 @@ function openSessionLink(state) {
     const gone = `Session "${state.name}" closed the connection`;
     socket.once("connect", () => {
       open = true;
-      resolve({
+      resolve2({
         request: (req) => new Promise((done, fail) => {
           if (socket.destroyed || socket.writableEnded) {
             fail(new Error(gone));
@@ -443,8 +684,7 @@ function openSessionLink(state) {
           }
           const id = ++seq;
           waiting.set(id, done);
-          socket.write(`${JSON.stringify({ ...req, id })}
-`);
+          socket.write(encodeLine({ ...req, id }));
         }),
         close: () => socket.end()
       });
@@ -471,7 +711,7 @@ function openSessionLink(state) {
 async function connectSession(options = {}) {
   const state = pickSession({
     name: options.name ?? process.env.AGENT_BRIDGE_SESSION,
-    metro: metroHost(options.metro),
+    metro: explicitMetro(options.metro),
     device: options.device,
     transport: options.transport
   });
@@ -493,12 +733,32 @@ async function connectSession(options = {}) {
       args,
       timeoutMs: options.timeoutMs
     });
-    if (res.error || !res.result) throw new Error(res.error ?? "No result");
+    if (res.error || !res.result) {
+      const why = res.error ?? "No result";
+      throw res.notice ? new AgentBridgeCallError(tool, why, [], res.notice) : new Error(why);
+    }
     const result = res.result;
     const logs = result.logs ?? [];
-    if (!result.ok) throw new AgentBridgeCallError(tool, result.error, logs);
-    const { id: _id, from: _from, ok: _ok, ms: appMs, value, ...extra } = result;
-    return { ...extra, value, ms: res.ms ?? 0, appMs, logs };
+    if (!result.ok)
+      throw new AgentBridgeCallError(tool, result.error, logs, res.notice);
+    const {
+      id: _id,
+      from: _from,
+      ok: _ok,
+      ms: appMs,
+      value,
+      loadId: _loadId,
+      pending: _pending,
+      ...extra
+    } = result;
+    return {
+      ...extra,
+      value,
+      ms: res.ms ?? 0,
+      appMs,
+      logs,
+      ...res.notice && { notice: res.notice }
+    };
   };
   return {
     session: info.state ?? state,
@@ -513,14 +773,17 @@ async function connectSession(options = {}) {
 
 // src/client/index.ts
 var AgentBridgeCallError = class extends Error {
-  constructor(tool, message, logs = []) {
-    super(`${tool}: ${message}`);
+  constructor(tool, message, logs = [], notice) {
+    super(`${tool}: ${message}${notice ? `
+Warning: ${notice}` : ""}`);
     this.tool = tool;
     this.logs = logs;
+    this.notice = notice;
     this.name = "AgentBridgeCallError";
   }
   tool;
   logs;
+  notice;
 };
 async function connect(options = {}) {
   const timeoutMs = options.timeoutMs ?? 1e4;
@@ -567,5 +830,6 @@ async function listDevices(options = {}) {
   connect,
   connectSession,
   listDevices,
-  listSessions
+  listSessions,
+  runFlow
 });