@avasapp/agent-bridge 0.4.1 → 0.5.0

package/README.md

@@ -1,15 +1,23 @@
 # @avasapp/agent-bridge
 
-Let coding agents drive a running React Native app directly. Seed data, flip flags, fake realtime messages, navigate and check the screen in **milliseconds**, without tapping through the app. It works alongside [agent-device](https://github.com/callstack/agent-device): agent-device opens the app and handles native UI, and agent-bridge handles everything inside the app.
+Let coding agents drive any running Expo or React Native app directly. Seed data, flip flags, fake realtime messages, navigate and check the screen in **milliseconds**, without tapping through the app. It works alongside [agent-device](https://github.com/callstack/agent-device): agent-device opens the app and handles native UI, and agent-bridge handles everything inside the app.
 
 ![The same checks with agent-device alone (22.4 s) and with agent-bridge (1.4 s): hide a tab, turn on dark mode, fill in a form, seed data, fake a live message and undo it all](example/media/demo.gif)
 
 The same 19 checks on [the example app](example), at real speed: 22.4 s with agent-device alone, 1.4 s with agent-bridge. Most calls take a few milliseconds ([benchmarks](docs/benchmarks.md)).
 
-Works on Expo (dev-tools socket) and on bare React Native (CDP over Metro). Dev builds only: release builds get empty stubs.
+Works on Expo (dev-tools socket) and on bare React Native (CDP over Metro). Nothing ships to users: every entry point compiles to an empty stub in release builds, and `agent-bridge assert-absent` checks a bundle in CI ([security](docs/security.md)).
 
 ## Install
 
+```sh
+npx @avasapp/agent-bridge init
+```
+
+Run it in the app. It installs the package, writes a dev-only `src/dev/agent-bridge.tsx` wired for the libraries it finds, adds a smoke flow and the agent skill, and prints the two lines to paste into your root component. Agents run it as `init --json`; see [the CLI](docs/cli.md#init).
+
+### Manual setup
+
 ```sh
 bun add -d @avasapp/agent-bridge   # or npm / yarn / pnpm
 ```
@@ -74,17 +82,17 @@ Most flows need the app in a known state first, such as a user signed in locally
 ## From the agent
 
 ```sh
-npx agent-bridge session start            # hold one connection; call/tools/run reuse it
-npx agent-bridge tools
-npx agent-bridge call scenario.apply '["signedIn", {"user": {"name": "Ada"}}]'
-npx agent-bridge call query.pin '[["features"], {"beta": false}]'
-npx agent-bridge call screen.press '"add-plant"'
-npx agent-bridge call screen.waitFor '"Name is required"'
-npx agent-bridge run flows/add-plant.mjs --strict   # fail if the app logged an error
-npx agent-bridge session stop             # runs bridge.restore, then disconnects
+npx @avasapp/agent-bridge session start            # hold one connection; call/tools/run reuse it
+npx @avasapp/agent-bridge tools
+npx @avasapp/agent-bridge call scenario.apply '["signedIn", {"user": {"name": "Ada"}}]'
+npx @avasapp/agent-bridge call query.pin '[["features"], {"beta": false}]'
+npx @avasapp/agent-bridge call screen.press '"add-plant"'
+npx @avasapp/agent-bridge call screen.waitFor '"Name is required"'
+npx @avasapp/agent-bridge run flows/add-plant.flow.mjs --strict   # fail if the app logged an error
+npx @avasapp/agent-bridge session stop             # runs bridge.restore, then disconnects
 ```
 
-Agents should run `./node_modules/.bin/agent-bridge` (or `bunx agent-bridge`) rather than `npx`, which is slower and can print npm warnings into their output. See [the CLI](docs/cli.md) for flows, batch mode, the REPL, sessions and the `connect()` client.
+Agents should run `./node_modules/.bin/agent-bridge` rather than `npx`, which is slower and can print npm warnings into their output. See [the CLI](docs/cli.md) for flows, batch mode, the REPL, sessions and the `connect()` client.
 
 No device tool is needed. Pair one (such as agent-device) with the bridge for what it can't reach: system alerts, permission prompts, the keyboard, screenshots, and one real tap per flow.
 

package/dist/adapters/tanstack-query.cjs

@@ -222,6 +222,9 @@ function atPath(value, path) {
   return current;
 }
 function queryTools(queryClient) {
+  return toolsFor(queryClient);
+}
+function toolsFor(queryClient) {
   const cache = queryClient.getQueryCache();
   const state = pinStateFor(queryClient);
   const { pins, seeded } = state;

package/dist/adapters/tanstack-query.d.cts

@@ -1,10 +1,19 @@
-import { QueryClient } from '@tanstack/query-core';
 import { T as Tools } from '../types-BmpykP1P.cjs';
 
+/** A TanStack Query `QueryClient`, e.g. from `useQueryClient()`. */
+type QueryClientLike = {
+    getQueryCache(): object;
+    getQueryData(queryKey: readonly unknown[]): unknown;
+    setQueryData(queryKey: readonly unknown[], updater: unknown): unknown;
+    invalidateQueries(filters?: object): Promise<void>;
+    refetchQueries(filters?: object): Promise<void>;
+    resetQueries(filters?: object): Promise<void>;
+    getDefaultOptions(): object;
+};
 /**
  * Read and seed the TanStack Query cache. `query.pin` keeps a seed in place:
  * when a refetch lands with real data, the seed is put back until unpinned.
  */
-declare function queryTools(queryClient: QueryClient): Tools;
+declare function queryTools(queryClient: QueryClientLike): Tools;
 
-export { queryTools };
+export { type QueryClientLike, queryTools };

package/dist/{chunk-AJD3XTNT.js → chunk-3QIG7A5W.js}

@@ -35,11 +35,11 @@ async function listCdpTargets(metro, signal) {
     );
   return await res.json();
 }
-function pickOne(items, filter, label) {
+function pickOne(items, filter, label2) {
   const matching = filter ? items.filter(
-    (item) => label(item).toLowerCase().includes(filter.toLowerCase())
+    (item) => label2(item).toLowerCase().includes(filter.toLowerCase())
   ) : items;
-  const connected = items.map(label).join("; ") || "none";
+  const connected = items.map(label2).join("; ") || "none";
   if (matching.length === 0) {
     throw new Error(
       filter ? `No app matches "${filter}". Connected: ${connected}` : "No app is connected to Metro."
@@ -50,6 +50,15 @@ function pickOne(items, filter, label) {
       `${matching.length} apps are connected; pick one with --device. Connected: ${connected}`
     );
   }
+  if (matching.length > 1) {
+    const exact = matching.filter(
+      (item) => label2(item).toLowerCase() === filter?.toLowerCase()
+    );
+    if (exact.length === 1) return exact[0];
+    throw new Error(
+      `${matching.length} apps match "${filter}"; narrow --device. Matching: ${matching.map(label2).join("; ")}`
+    );
+  }
   return matching[0];
 }
 
@@ -67,6 +76,7 @@ function toAsciiJson(value) {
 
 // src/client/connection.ts
 import WebSocket from "ws";
+var describePin = (pin) => `${pin.name} (${pin.platform}${pin.target ? `, ${pin.target}` : ""})`;
 var OPEN_SOCKET_MS = 5e3;
 var OpenGaveUp = class extends Error {
 };
@@ -192,7 +202,7 @@ async function listExpoDevices(metro, discoveryMs = 600) {
   ws.close();
   return [...devices.values()];
 }
-async function connectExpo(metro, device, discoveryMs = 600, signal) {
+async function connectExpo(metro, device, discoveryMs = 600, signal, pin) {
   const { ws, devices, pending, send, announced } = await openBroadcast(
     metro,
     discoveryMs,
@@ -200,7 +210,13 @@ async function connectExpo(metro, device, discoveryMs = 600, signal) {
   );
   let info;
   try {
-    info = pickOne([...devices.values()], device, deviceLabel);
+    const all = [...devices.values()];
+    const candidates = pin ? all.filter((d) => d.name === pin.name && d.platform === pin.platform) : all;
+    if (pin && !candidates.length)
+      throw new Error(
+        `${describePin(pin)} is not connected; connected: ${all.map(deviceLabel).join("; ") || "none"}`
+      );
+    info = pickOne(candidates, device, deviceLabel);
   } catch (error) {
     ws.close();
     throw error;
@@ -215,6 +231,7 @@ async function connectExpo(metro, device, discoveryMs = 600, signal) {
   return {
     transport: "expo",
     device: info,
+    pin: { name: info.name, platform: info.platform },
     call(tool, args, timeoutMs) {
       if (superseded)
         return Promise.resolve({
@@ -238,17 +255,247 @@ async function connectExpo(metro, device, discoveryMs = 600, signal) {
   };
 }
 
+// src/client/session/state.ts
+import { createHash } from "crypto";
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync
+} from "fs";
+import { tmpdir, userInfo } from "os";
+import { dirname, join, resolve } from "path";
+function projectRoot(from = process.cwd()) {
+  for (let dir = resolve(from); ; dir = dirname(dir)) {
+    if (existsSync(join(dir, "package.json"))) return dir;
+    if (dirname(dir) === dir) return resolve(from);
+  }
+}
+var uid = () => process.getuid?.() ?? userInfo().username;
+function privateDir(dir) {
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  const stat = lstatSync(dir);
+  if (!stat.isDirectory())
+    throw new Error(`${dir} is not a directory; remove it and retry`);
+  if (process.getuid && stat.uid !== process.getuid())
+    throw new Error(`${dir} belongs to another user; refusing to use it`);
+  if (process.platform !== "win32" && (stat.mode & 63) !== 0)
+    chmodSync(dir, 448);
+  return dir;
+}
+function stateDir() {
+  return privateDir(
+    process.env.AGENT_BRIDGE_STATE_DIR ?? (process.env.XDG_RUNTIME_DIR ? join(process.env.XDG_RUNTIME_DIR, "agent-bridge") : join(tmpdir(), `agent-bridge-${uid()}`))
+  );
+}
+var shortHash = (text) => createHash("sha256").update(text).digest("hex").slice(0, 16);
+function socketPath(name, dir) {
+  if (process.platform === "win32")
+    return `\\\\.\\pipe\\agent-bridge-${shortHash(dir)}-${name}`;
+  const path = join(dir, `${name}.sock`);
+  if (Buffer.byteLength(path) <= 100) return path;
+  const short = privateDir(`/tmp/agent-bridge-${uid()}`);
+  return join(short, `${shortHash(path)}.sock`);
+}
+var sessionFiles = (name, dir = stateDir()) => ({
+  state: join(dir, `${name}.json`),
+  error: join(dir, `${name}.error`),
+  log: join(dir, `${name}.log`),
+  socket: socketPath(name, dir)
+});
+function checkName(name) {
+  if (!/^[\w.-]{1,40}$/.test(name))
+    throw new Error(
+      `Session name "${name}" must be 1-40 letters, digits, ".", "_" or "-"`
+    );
+  return name;
+}
+function parseDuration(text) {
+  const match = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h)?$/.exec(text.trim());
+  if (!match) throw new Error(`Can't read duration "${text}"; try 15m or 90s`);
+  const units = { s: 1e3, m: 6e4, h: 36e5 };
+  return Math.round(Number(match[1]) * (units[match[2] ?? "ms"] ?? 1));
+}
+function formatDuration(ms) {
+  const s = Math.max(0, Math.round(ms / 1e3));
+  if (s < 60) return `${s}s`;
+  if (s < 3600)
+    return `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
+  return `${Math.floor(s / 3600)}h${String(Math.floor(s / 60) % 60).padStart(2, "0")}m`;
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function writePrivate(file, text) {
+  writeFileSync(file, text, { mode: 384 });
+}
+function removeSessionFiles(name, dir = stateDir()) {
+  const files = sessionFiles(name, dir);
+  rmSync(files.state, { force: true });
+  if (process.platform !== "win32") rmSync(files.socket, { force: true });
+}
+function readState(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function listSessions(dir = stateDir()) {
+  const live = [];
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith(".json")) continue;
+    const state = readState(join(dir, entry));
+    if (!state) continue;
+    if (isAlive(state.pid)) live.push(state);
+    else removeSessionFiles(state.name, dir);
+  }
+  return live.sort((a, b) => a.startedAt - b.startedAt);
+}
+function readSession(name, dir = stateDir()) {
+  return listSessions(dir).find((s) => s.name === name) ?? null;
+}
+function pickSession(filter) {
+  if (filter.name) {
+    const named = readSession(checkName(filter.name));
+    if (!named) throw new Error(`No session named "${filter.name}" is running`);
+    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) => (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)
+  );
+  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/metro-hint.ts
+var range = (from, to) => Array.from({ length: to - from + 1 }, (_, i) => from + i);
+var probe = {
+  ports: [...range(8081, 8090), ...range(8100, 8199)],
+  eachMs: 300,
+  totalMs: 1e3
+};
+var hostOf = (metro) => {
+  const colon = metro.lastIndexOf(":");
+  return colon > 0 && !metro.endsWith("]") ? metro.slice(0, colon) : metro;
+};
+async function answers(metro, signal) {
+  try {
+    const res = await fetch(`http://${metro}/status`, { signal });
+    return (await res.text()).includes("packager-status:running");
+  } catch {
+    return false;
+  }
+}
+async function appsOn(metro, signal) {
+  try {
+    const res = await fetch(`http://${metro}/json/list`, { signal });
+    const targets = await res.json();
+    const names = targets.map(
+      (t) => `${t.title ?? "?"}${t.deviceName ? ` [${t.deviceName}]` : ""}`
+    );
+    return [...new Set(names)];
+  } catch {
+    return [];
+  }
+}
+async function findMetros(metro) {
+  const host = hostOf(metro);
+  const candidates = new Set(probe.ports.map((port) => `${host}:${port}`));
+  try {
+    for (const s of listSessions()) candidates.add(s.metro);
+  } catch {
+  }
+  candidates.delete(metro);
+  const deadline = AbortSignal.timeout(probe.totalMs);
+  const within2 = () => AbortSignal.any([deadline, AbortSignal.timeout(probe.eachMs)]);
+  const running = (await Promise.all(
+    [...candidates].map(async (m) => await answers(m, within2()) ? m : null)
+  )).filter((m) => m !== null);
+  return Promise.all(
+    running.map(async (m) => ({ metro: m, apps: await appsOn(m, within2()) }))
+  );
+}
+var label = (found) => `${found.metro} (${found.apps.length ? `${found.apps.length === 1 ? "app" : "apps"}: ${found.apps.join(", ")}` : "no app connected"})`;
+var howToSet = (metro) => `Pass --metro ${metro} or set AGENT_BRIDGE_METRO=${metro}.`;
+function elsewhere(found) {
+  const [only] = found;
+  if (found.length === 1 && only)
+    return `Metro is running on ${label(only)}. ${howToSet(only.metro)}`;
+  return `Metro is running on ${found.map(label).join("; ")}. ${howToSet("<host:port>")}`;
+}
+var errorText = (error) => {
+  if (!(error instanceof Error)) return String(error);
+  const code = error.code ?? "";
+  return `${error.message} ${code} ${error.cause ? errorText(error.cause) : ""}`;
+};
+var isRefused = (error) => /ECONNREFUSED|ConnectionRefused/.test(errorText(error));
+var NO_APP = /No app is connected to Metro|No app matches/;
+async function refusedMessage(metro) {
+  const found = await findMetros(metro);
+  if (found.length)
+    return `Nothing is listening on ${metro}. ${elsewhere(found)}`;
+  const host = hostOf(metro);
+  return `Nothing is listening on ${metro}, and no Metro answered on ${host} ports 8081-8090 or 8100-8199. Start Metro, or if it runs elsewhere, pass --metro <host:port> or set AGENT_BRIDGE_METRO=<host:port>.`;
+}
+async function noAppHint(metro, device) {
+  const causes = `Likely: the app isn't open or hasn't reloaded since the bridge was mounted, it uses another Metro${device ? `, or --device "${device}" doesn't match` : ""}.`;
+  const withApps = (await findMetros(metro)).filter((f) => f.apps.length);
+  return withApps.length ? `${causes} ${elsewhere(withApps)}` : causes;
+}
+async function refused(metro) {
+  try {
+    await fetch(`http://${metro}/status`, {
+      signal: AbortSignal.timeout(probe.eachMs)
+    });
+    return false;
+  } catch (error) {
+    return isRefused(error);
+  }
+}
+async function explainConnectError(error, metro, device) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (NO_APP.test(message))
+    return new Error(`${message}
+${await noAppHint(metro, device)}`, {
+      cause: error
+    });
+  if (await refused(metro))
+    return new Error(await refusedMessage(metro), { cause: error });
+  return error;
+}
+async function assertListening(metro) {
+  if (await refused(metro)) throw new Error(await refusedMessage(metro));
+}
+
 // src/client/cdp.ts
 import WebSocket2 from "ws";
 var CannotEvaluate = class extends Error {
 };
 var targetLabel = (t) => `${t.title}${t.deviceName ? ` [${t.deviceName}]` : ""}`;
-async function connectCdp(metro, device, signal) {
-  const target = pickOne(
-    await listCdpTargets(metro, signal),
-    device,
-    targetLabel
-  );
+async function connectCdp(metro, device, signal, pin) {
+  const targets = await listCdpTargets(metro, signal);
+  const candidates = pin?.target ? targets.filter((t) => targetLabel(t) === pin.target) : targets;
+  if (pin && !candidates.length)
+    throw new Error(
+      `${describePin(pin)} is not connected; connected: ${targets.map(targetLabel).join("; ") || "none"}`
+    );
+  const target = pickOne(candidates, device, targetLabel);
   const hostUri = await expoHostUri(metro, signal);
   const port = metro.split(":")[1] ?? "8081";
   const origin = hostUri ? `http://${hostUri}` : `http://localhost:${port}`;
@@ -326,27 +573,34 @@ async function connectCdp(metro, device, signal) {
     );
   }
   signal?.removeEventListener("abort", dropOnAbort);
+  if (pin && (info.name !== pin.name || info.platform !== pin.platform)) {
+    ws.terminate();
+    throw new Error(
+      `${describePin(pin)} is not connected; connected: ${targetLabel(target)} runs ${info.name} (${info.platform})`
+    );
+  }
   return {
     transport: "cdp",
+    pin: {
+      name: info.name,
+      platform: info.platform,
+      target: targetLabel(target)
+    },
     device: { ...info, name: `${info.name} (${targetLabel(target)})` },
-    async call(tool, args, timeoutMs) {
+    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))})`
-        );
-      } catch (error) {
-        pending.settle({
+      evaluate(
+        `${CDP_GLOBAL}.dispatch(${JSON.stringify(toAsciiJson(call))})`
+      ).catch(
+        (error) => pending.settle({
           id: call.id,
           from: info.deviceId,
           ok: false,
           error: String(error),
           ms: 0
-        });
-      }
+        })
+      );
       return reply;
     },
     close: () => ws.close()
@@ -389,7 +643,7 @@ async function openConnection(options = {}) {
     try {
       return await phase(
         options,
-        (signal) => connectExpo(metro, options.device, void 0, signal)
+        (signal) => connectExpo(metro, options.device, void 0, signal, options.pin)
       );
     } catch (error) {
       if (want === "expo" || options.signal?.aborted) throw error;
@@ -399,7 +653,7 @@ async function openConnection(options = {}) {
   try {
     return await phase(
       options,
-      (signal) => connectCdp(metro, options.device, signal)
+      (signal) => connectCdp(metro, options.device, signal, options.pin)
     );
   } catch (error) {
     const expoNote = expoError ? ` (Expo socket: ${String(expoError)})` : "";
@@ -476,7 +730,7 @@ async function runFlow(bridge, flow, options = {}) {
     }
   };
   const call = async (tool, ...args) => (await timed(tool, ...args)).value;
-  const step = async (label, tool, ...given) => {
+  const step = async (label2, 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));
@@ -484,7 +738,7 @@ async function runFlow(bridge, flow, options = {}) {
     });
     total += ms;
     print(
-      `${String(++n).padStart(2, "0")} ${label.padEnd(30)} ${ms.toFixed(1).padStart(7)} ms`
+      `${String(++n).padStart(2, "0")} ${label2.padEnd(30)} ${ms.toFixed(1).padStart(7)} ms`
     );
     report(logs, notice);
     return value;
@@ -536,134 +790,6 @@ import { createInterface } from "readline";
 var encodeLine = (message) => `${JSON.stringify(message).replace(/[\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16)}`)}
 `;
 
-// src/client/session/state.ts
-import { createHash } from "crypto";
-import {
-  chmodSync,
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  rmSync,
-  writeFileSync
-} from "fs";
-import { tmpdir, userInfo } from "os";
-import { dirname, join, resolve } from "path";
-function projectRoot(from = process.cwd()) {
-  for (let dir = resolve(from); ; dir = dirname(dir)) {
-    if (existsSync(join(dir, "package.json"))) return dir;
-    if (dirname(dir) === dir) return resolve(from);
-  }
-}
-var uid = () => process.getuid?.() ?? userInfo().username;
-function privateDir(dir) {
-  mkdirSync(dir, { recursive: true, mode: 448 });
-  const stat = lstatSync(dir);
-  if (!stat.isDirectory())
-    throw new Error(`${dir} is not a directory; remove it and retry`);
-  if (process.getuid && stat.uid !== process.getuid())
-    throw new Error(`${dir} belongs to another user; refusing to use it`);
-  if (process.platform !== "win32" && (stat.mode & 63) !== 0)
-    chmodSync(dir, 448);
-  return dir;
-}
-function stateDir() {
-  return privateDir(
-    process.env.AGENT_BRIDGE_STATE_DIR ?? (process.env.XDG_RUNTIME_DIR ? join(process.env.XDG_RUNTIME_DIR, "agent-bridge") : join(tmpdir(), `agent-bridge-${uid()}`))
-  );
-}
-var shortHash = (text) => createHash("sha256").update(text).digest("hex").slice(0, 16);
-function socketPath(name, dir) {
-  if (process.platform === "win32")
-    return `\\\\.\\pipe\\agent-bridge-${shortHash(dir)}-${name}`;
-  const path = join(dir, `${name}.sock`);
-  if (Buffer.byteLength(path) <= 100) return path;
-  const short = privateDir(`/tmp/agent-bridge-${uid()}`);
-  return join(short, `${shortHash(path)}.sock`);
-}
-var sessionFiles = (name, dir = stateDir()) => ({
-  state: join(dir, `${name}.json`),
-  error: join(dir, `${name}.error`),
-  log: join(dir, `${name}.log`),
-  socket: socketPath(name, dir)
-});
-function checkName(name) {
-  if (!/^[\w.-]{1,40}$/.test(name))
-    throw new Error(
-      `Session name "${name}" must be 1-40 letters, digits, ".", "_" or "-"`
-    );
-  return name;
-}
-function parseDuration(text) {
-  const match = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h)?$/.exec(text.trim());
-  if (!match) throw new Error(`Can't read duration "${text}"; try 15m or 90s`);
-  const units = { s: 1e3, m: 6e4, h: 36e5 };
-  return Math.round(Number(match[1]) * (units[match[2] ?? "ms"] ?? 1));
-}
-function formatDuration(ms) {
-  const s = Math.max(0, Math.round(ms / 1e3));
-  if (s < 60) return `${s}s`;
-  if (s < 3600)
-    return `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
-  return `${Math.floor(s / 3600)}h${String(Math.floor(s / 60) % 60).padStart(2, "0")}m`;
-}
-function isAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return error.code === "EPERM";
-  }
-}
-function writePrivate(file, text) {
-  writeFileSync(file, text, { mode: 384 });
-}
-function removeSessionFiles(name, dir = stateDir()) {
-  const files = sessionFiles(name, dir);
-  rmSync(files.state, { force: true });
-  if (process.platform !== "win32") rmSync(files.socket, { force: true });
-}
-function readState(file) {
-  try {
-    return JSON.parse(readFileSync(file, "utf8"));
-  } catch {
-    return null;
-  }
-}
-function listSessions(dir = stateDir()) {
-  const live = [];
-  for (const entry of readdirSync(dir)) {
-    if (!entry.endsWith(".json")) continue;
-    const state = readState(join(dir, entry));
-    if (!state) continue;
-    if (isAlive(state.pid)) live.push(state);
-    else removeSessionFiles(state.name, dir);
-  }
-  return live.sort((a, b) => a.startedAt - b.startedAt);
-}
-function readSession(name, dir = stateDir()) {
-  return listSessions(dir).find((s) => s.name === name) ?? null;
-}
-function pickSession(filter) {
-  if (filter.name) {
-    const named = readSession(checkName(filter.name));
-    if (!named) throw new Error(`No session named "${filter.name}" is running`);
-    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) => (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)
-  );
-  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((resolve2, reject) => {
@@ -793,7 +919,9 @@ Warning: ${notice}` : ""}`);
 };
 async function connect(options = {}) {
   const timeoutMs = options.timeoutMs ?? 1e4;
-  const conn = await openConnection(options);
+  const conn = await openConnection(options).catch(async (error) => {
+    throw await explainConnectError(error, metroHost(options.metro), options.device);
+  });
   const timed = async (tool, ...args) => {
     const t0 = performance.now();
     const result = await conn.call(tool, args, timeoutMs);
@@ -835,12 +963,6 @@ export {
   explicitMetro,
   metroHost,
   RUNTIME_MARKER,
-  openConnection,
-  logLine,
-  flowScenarios,
-  parseScenarioFlag,
-  runFlow,
-  encodeLine,
   projectRoot,
   stateDir,
   sessionFiles,
@@ -853,6 +975,15 @@ export {
   listSessions,
   readSession,
   pickSession,
+  noAppHint,
+  explainConnectError,
+  assertListening,
+  openConnection,
+  logLine,
+  flowScenarios,
+  parseScenarioFlag,
+  runFlow,
+  encodeLine,
   sessionRequest,
   connectSession,
   AgentBridgeCallError,