@avasapp/agent-bridge 0.4.2 → 0.6.0

package/dist/{chunk-TA2OLPPT.js → chunk-Y6QFU5ON.js}

@@ -1,3 +1,18 @@
+// src/client/call-timeout.ts
+var WAITERS = {
+  "screen.waitFor": 2e3,
+  // The page helper adds 5 s to timeoutMs before it gives up.
+  "webview.waitFor": 7e3
+};
+var MAX_MS = 10 * 6e4;
+function callTimeout(base, tool, args) {
+  const margin = WAITERS[tool];
+  const t = args[1]?.timeoutMs;
+  if (margin === void 0 || typeof t !== "number" || !(t > 0) || !Number.isFinite(t))
+    return base;
+  return Math.max(base, Math.min(t + margin, MAX_MS));
+}
+
 // src/client/discover.ts
 var within = (ms, signal) => signal ? AbortSignal.any([AbortSignal.timeout(ms), signal]) : AbortSignal.timeout(ms);
 var DEFAULT_METRO = "localhost:8081";
@@ -35,11 +50,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."
@@ -52,11 +67,11 @@ function pickOne(items, filter, label) {
   }
   if (matching.length > 1) {
     const exact = matching.filter(
-      (item) => label(item).toLowerCase() === filter?.toLowerCase()
+      (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(label).join("; ")}`
+      `${matching.length} apps match "${filter}"; narrow --device. Matching: ${matching.map(label2).join("; ")}`
     );
   }
   return matching[0];
@@ -232,7 +247,7 @@ async function connectExpo(metro, device, discoveryMs = 600, signal, pin) {
     transport: "expo",
     device: info,
     pin: { name: info.name, platform: info.platform },
-    call(tool, args, timeoutMs) {
+    call(tool, args, timeoutMs, extra) {
       if (superseded)
         return Promise.resolve({
           id: "",
@@ -245,7 +260,8 @@ async function connectExpo(metro, device, discoveryMs = 600, signal, pin) {
         id: newCallId(),
         tool,
         args,
-        to: info.deviceId
+        to: info.deviceId,
+        ...extra
       };
       const reply = pending.wait(call.id, tool, timeoutMs);
       send("call", call);
@@ -255,6 +271,247 @@ async function connectExpo(metro, device, discoveryMs = 600, signal, pin) {
   };
 }
 
+// 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, sep } 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 isPackage = (dir) => existsSync(join(dir, "package.json"));
+function inProject(session, project) {
+  if (!session) return false;
+  if (session === project) return true;
+  if (!session.startsWith(project + sep) || !isPackage(project)) return false;
+  for (let dir = session; dir !== project; dir = dirname(dir)) {
+    if (existsSync(join(dir, ".git"))) return false;
+    if (dir !== session && isPackage(dir)) return false;
+  }
+  return true;
+}
+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) => !filter.skip?.(s) && (explicit || inProject(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 (!explicit && matching.length > 1 && matching.every((s) => s.project !== project))
+    return 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/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 {
@@ -359,8 +616,8 @@ async function connectCdp(metro, device, signal, pin) {
       target: targetLabel(target)
     },
     device: { ...info, name: `${info.name} (${targetLabel(target)})` },
-    call(tool, args, timeoutMs) {
-      const call = { id: newCallId(), tool, args };
+    call(tool, args, timeoutMs, extra) {
+      const call = { id: newCallId(), tool, args, ...extra };
       const reply = pending.wait(call.id, tool, timeoutMs);
       evaluate(
         `${CDP_GLOBAL}.dispatch(${JSON.stringify(toAsciiJson(call))})`
@@ -443,6 +700,40 @@ function logLine(entry) {
 }
 
 // src/client/flow.ts
+function deepMatches(actual, expected) {
+  if (expected instanceof RegExp) return typeof actual === "string" && expected.test(actual);
+  if (Array.isArray(expected))
+    return Array.isArray(actual) && actual.length === expected.length && expected.every((e, i) => deepMatches(actual[i], e));
+  if (expected && typeof expected === "object") {
+    const proto = Object.getPrototypeOf(expected);
+    if (proto !== Object.prototype && proto !== null)
+      throw new Error(
+        `A match can hold plain objects, arrays, values and RegExps, not a ${expected.constructor?.name ?? "class instance"}`
+      );
+    return !!actual && typeof actual === "object" && Object.entries(expected).every(
+      ([k, v]) => deepMatches(actual[k], v)
+    );
+  }
+  return Object.is(actual, expected);
+}
+var MAX_SCREEN_LINES = 40;
+function compactScreen(snapshot) {
+  const elements = snapshot?.elements;
+  if (!Array.isArray(elements)) return [];
+  const lines = elements.slice(0, MAX_SCREEN_LINES).map((raw) => {
+    const e = raw;
+    const parts = [String(e.kind ?? "element")];
+    if (e.testID) parts.push(`#${String(e.testID)}`);
+    for (const key of ["text", "label", "placeholder", "value"])
+      if (typeof e[key] === "string" && e[key]) parts.push(JSON.stringify(e[key]));
+    if (e.disabled) parts.push("disabled");
+    if (e.checked) parts.push(`checked=${String(e.checked)}`);
+    return parts.join(" ");
+  });
+  if (elements.length > MAX_SCREEN_LINES)
+    lines.push(`... ${elements.length - MAX_SCREEN_LINES} more`);
+  return lines;
+}
 function flowScenarios(flow) {
   const declared = [
     ...flow.scenario === void 0 ? [] : [flow.scenario],
@@ -483,6 +774,10 @@ async function runFlow(bridge, flow, options = {}) {
   let errors = 0;
   const t0 = performance.now();
   const notices = [];
+  let lost = false;
+  const noteOutcome = (error) => {
+    lost = error !== void 0 && !(error instanceof AgentBridgeCallError);
+  };
   const report = (logs, notice) => {
     errors += logs.length;
     for (const e of logs) print(`   ${logLine(e)}`);
@@ -494,28 +789,82 @@ async function runFlow(bridge, flow, options = {}) {
   const timed = async (tool, ...args) => {
     try {
       const result = await bridge.timed(tool, ...args);
+      noteOutcome();
       report(result.logs, result.notice);
       return result;
     } catch (error) {
+      noteOutcome(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;
-    });
+  const record = (label2, ms) => {
     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;
+  };
+  const step = async (label2, tool, ...given) => {
+    const args = given.length === 1 && Array.isArray(given[0]) ? given[0] : given;
+    const result = await timed(tool, ...args);
+    record(label2, result.ms);
+    return result.value;
+  };
+  const message = (error) => error instanceof Error ? error.message : String(error);
+  const expectApi = {
+    text: async (target, o) => {
+      await step(`expect text ${JSON.stringify(target)}`, "screen.waitFor", target, o ?? {}).catch(
+        (error) => {
+          throw new Error(`expected ${JSON.stringify(target)} on screen: ${message(error)}`);
+        }
+      );
+    },
+    gone: async (target, o) => {
+      await step(`expect gone ${JSON.stringify(target)}`, "screen.waitFor", target, {
+        ...o,
+        gone: true
+      }).catch((error) => {
+        throw new Error(`expected ${JSON.stringify(target)} to be off screen: ${message(error)}`);
+      });
+    },
+    route: async (pathname, o) => {
+      const label2 = `expect route ${pathname}`;
+      const t02 = performance.now();
+      const deadline = t02 + (o?.timeoutMs ?? 2e3);
+      for (; ; ) {
+        const route = await call("router.current").catch((error) => {
+          record(label2, performance.now() - t02);
+          throw error;
+        });
+        if (route?.pathname === pathname) return record(label2, performance.now() - t02);
+        if (performance.now() >= deadline) {
+          record(label2, performance.now() - t02);
+          throw new Error(`expected route ${pathname}, got ${route?.pathname ?? JSON.stringify(route)}`);
+        }
+        await new Promise((r) => setTimeout(r, 50));
+      }
+    },
+    result: async (tool, args, match) => {
+      const value = await step(`expect ${tool}`, tool, args);
+      if (!deepMatches(value, match))
+        throw new Error(
+          `expected ${tool} to match ${JSON.stringify(match)}, got ${JSON.stringify(value)}`
+        );
+    }
+  };
+  const failureState = async () => {
+    const has = (name) => bridge.tools().some((t) => t.name === name);
+    const state = {};
+    if (has("screen.snapshot"))
+      state.screen = await call("screen.snapshot").then(compactScreen).catch(() => void 0);
+    if (has("router.current") && !lost)
+      state.route = await call("router.current").catch(() => void 0);
+    return state;
   };
   const restoreErrors = [];
+  let flowErrors = 0;
+  let unreachable = false;
   const applied = {};
   if (needs.length && !bridge.tools().some((t) => t.name === "scenario.apply"))
     throw new Error(
@@ -530,10 +879,22 @@ async function runFlow(bridge, flow, options = {}) {
       bridge: { ...bridge, timed, call },
       call,
       step,
-      scenarios: applied
+      scenarios: applied,
+      expect: expectApi
     });
+  } catch (error) {
+    const state = lost ? {} : await failureState();
+    if (state.route !== void 0) print(`   route: ${JSON.stringify(state.route)}`);
+    if (state.screen?.length) {
+      print("   on screen:");
+      for (const line of state.screen) print(`     ${line}`);
+    }
+    options.onFailure?.(state);
+    throw error;
   } finally {
-    if (needs.length) {
+    flowErrors = errors;
+    unreachable = lost;
+    if (!lost && !options.keep && (needs.length || bridge.tools().some((t) => t.name === "bridge.restore"))) {
       try {
         const result = await step("restore", "bridge.restore");
         for (const [name, value] of Object.entries(result ?? {})) {
@@ -541,17 +902,70 @@ async function runFlow(bridge, flow, options = {}) {
           if (error !== void 0) restoreErrors.push(`${name}: ${String(error)}`);
         }
       } catch (error) {
+        unreachable = lost;
         restoreErrors.push(
           `bridge.restore: ${error instanceof Error ? error.message : String(error)}`
         );
       }
       for (const e of restoreErrors) print(`   ! restore failed: ${e}`);
     }
+    options.onFinish?.({ steps: n, errors: flowErrors, restoreErrors, notices, unreachable });
   }
   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" : ""}`
+    `${n} steps, ${total.toFixed(1)} ms in calls, ${(performance.now() - t0).toFixed(0)} ms wall (${bridge.transport})${flowErrors ? `, ${flowErrors} error${flowErrors === 1 ? "" : "s"}` : ""}${notices.length ? ", the app reloaded" : ""}`
   );
-  return { steps: n, errors, restoreErrors, notices };
+  return { steps: n, errors: flowErrors, restoreErrors, notices, unreachable };
+}
+async function runFlows(bridge, entries, options = {}) {
+  const print = options.print ?? console.log;
+  const printError = options.single ? options.printError ?? console.error : print;
+  const runs = [];
+  let unreachable = false;
+  for (const entry of entries) {
+    const base = { file: entry.file, name: entry.name, restoreErrors: [], notices: [] };
+    const skip = unreachable ? "skipped: the app stopped answering in an earlier flow" : options.bail && runs.some((r) => r.status === "failed") ? "skipped: an earlier flow failed (--bail)" : void 0;
+    if (skip) {
+      runs.push({ ...base, status: "skipped", ms: 0, steps: 0, errors: 0, error: skip });
+      continue;
+    }
+    if (!options.single) print(`
+${entry.name}`);
+    const t0 = performance.now();
+    let state;
+    let done = { steps: 0, errors: 0, restoreErrors: [], notices: [], unreachable: false };
+    const reasons = [];
+    try {
+      await runFlow(bridge, entry.module, {
+        ...options,
+        onFailure: (s) => {
+          state = s;
+        },
+        onFinish: (r) => {
+          done = r;
+        }
+      });
+    } catch (error) {
+      const why = error instanceof Error ? error.message : String(error);
+      printError(`   FAILED: ${why}`);
+      reasons.push(why);
+    }
+    if (done.restoreErrors.length) reasons.push(`restore failed: ${done.restoreErrors.join("; ")}`);
+    if (options.strict && done.errors)
+      reasons.push(`the app logged ${done.errors} error${done.errors === 1 ? "" : "s"}`);
+    if (done.notices.length)
+      print("   ! the app reloaded: changes made before the reload could not be undone");
+    const { unreachable: gone, ...result } = done;
+    runs.push({
+      ...base,
+      ...result,
+      status: reasons.length ? "failed" : "passed",
+      ms: performance.now() - t0,
+      ...reasons.length && { error: reasons.join("; ") },
+      ...state && { state }
+    });
+    if (gone) unreachable = true;
+  }
+  return runs;
 }
 
 // src/client/session/client.ts
@@ -562,148 +976,27 @@ 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
+var SessionLinkError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SessionLinkError";
+  }
+};
 function openSessionLink(state) {
   return new Promise((resolve2, reject) => {
     const socket = createConnection(state.socket);
     const waiting = /* @__PURE__ */ new Map();
     let seq = 0;
     let open = false;
-    const gone = `Session "${state.name}" closed the connection`;
+    let lastError = "";
+    const gone = () => `Session "${state.name}" closed the connection${lastError && `: ${lastError}`}`;
     socket.once("connect", () => {
       open = true;
       resolve2({
         request: (req) => new Promise((done, fail) => {
           if (socket.destroyed || socket.writableEnded) {
-            fail(new Error(gone));
+            fail(new SessionLinkError(gone()));
             return;
           }
           const id = ++seq;
@@ -714,18 +1007,22 @@ function openSessionLink(state) {
       });
     });
     socket.on("error", (error) => {
+      lastError = error.message;
       if (!open)
         reject(
-          new Error(
+          new SessionLinkError(
             `Session "${state.name}" isn't answering on ${state.socket}: ${error.message}`
           )
         );
     });
     socket.on("close", () => {
-      for (const [id, done] of waiting) done({ id, error: gone });
+      for (const [id, done] of waiting) done({ id, error: gone(), linkLost: true });
       waiting.clear();
     });
-    createInterface({ input: socket }).on("line", (line) => {
+    const lines = createInterface({ input: socket });
+    lines.on("error", () => {
+    });
+    lines.on("line", (line) => {
       const res = JSON.parse(line);
       waiting.get(res.id)?.(res);
       waiting.delete(res.id);
@@ -747,10 +1044,16 @@ async function connectSession(options = {}) {
     device: options.device,
     transport: options.transport
   });
-  if (!state)
+  if (!state) {
+    const where = [
+      explicitMetro(options.metro) && `on Metro ${explicitMetro(options.metro)}`,
+      options.device && `on a device matching "${options.device}"`,
+      options.transport && options.transport !== "auto" && `using ${options.transport}`
+    ].filter(Boolean);
     throw new Error(
-      "No single session matches. Start one with `agent-bridge session start`, or name it."
+      `No single session matches (looked for sessions ${where.length ? where.join(", ") : `started in ${projectRoot()}, or in an app folder under it`}). Start one with \`agent-bridge session start\`, or name it.`
     );
+  }
   const link = await openSessionLink(state);
   const info = await link.request({ op: "info" });
   if (info.error || !info.device || !info.transport) {
@@ -767,6 +1070,7 @@ async function connectSession(options = {}) {
     });
     if (res.error || !res.result) {
       const why = res.error ?? "No result";
+      if (res.linkLost) throw new SessionLinkError(why);
       throw res.notice ? new AgentBridgeCallError(tool, why, [], res.notice) : new Error(why);
     }
     const result = res.result;
@@ -819,10 +1123,12 @@ 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);
+    const result = await conn.call(tool, args, callTimeout(timeoutMs, tool, args));
     const ms = performance.now() - t0;
     const logs = result.logs ?? [];
     if (!result.ok) throw new AgentBridgeCallError(tool, result.error, logs);
@@ -858,15 +1164,10 @@ async function listDevices(options = {}) {
 }
 
 export {
+  callTimeout,
   explicitMetro,
   metroHost,
   RUNTIME_MARKER,
-  openConnection,
-  logLine,
-  flowScenarios,
-  parseScenarioFlag,
-  runFlow,
-  encodeLine,
   projectRoot,
   stateDir,
   sessionFiles,
@@ -879,6 +1180,17 @@ export {
   listSessions,
   readSession,
   pickSession,
+  noAppHint,
+  explainConnectError,
+  assertListening,
+  openConnection,
+  logLine,
+  flowScenarios,
+  parseScenarioFlag,
+  runFlow,
+  runFlows,
+  encodeLine,
+  SessionLinkError,
   sessionRequest,
   connectSession,
   AgentBridgeCallError,