esque-bridge 0.2.2 → 0.4.0

package/index.js

@@ -54,6 +54,8 @@ OPTIONS
   --bin       Override the agent's default binary
   --timeout   Max ms per prompt before SIGTERM (default: 300000 = 5 min)
   --subdomain Request a stable localtunnel subdomain (optional)
+  --rotate    Generate a fresh pair secret (invalidates existing pairings)
+  --yes, -y   Skip the "edit files in <dir>?" confirmation prompt
 
 PREREQS
   Claude:  npm install -g @anthropic-ai/claude-code   &&   claude /login
@@ -79,8 +81,35 @@ const AGENT_TYPE = String(argv.agent || process.env.ESQUE_AGENT || 'claude').toL
 const CUSTOM_CMD = argv.cmd || process.env.ESQUE_CMD || null;
 const BIN_OVERRIDE = argv.bin || null;
 const LT_SUBDOMAIN = argv.subdomain || process.env.LT_SUBDOMAIN || undefined;
-const PAIRING_SECRET = crypto.randomBytes(16).toString('hex');
 const SESSIONS_FILE = path.join(os.homedir(), '.esque-bridge-sessions.json');
+const SECRET_FILE = path.join(os.homedir(), '.esque-bridge-secret');
+
+// Pairing secret. Persisted across restarts so a routine bridge restart
+// doesn't silently invalidate the phone's pairing (the #1 real-world
+// breakage). Pass `--rotate` to force a fresh secret (e.g. if it leaked).
+// Stored 0600 in the user's home dir; a malformed/empty file is regenerated.
+function resolvePairingSecret() {
+  const gen = () => crypto.randomBytes(16).toString('hex');
+  if (!argv.rotate) {
+    try {
+      const existing = fs.readFileSync(SECRET_FILE, 'utf8').trim();
+      if (/^[a-f0-9]{32}$/.test(existing)) return existing;
+    } catch {
+      /* missing/unreadable — fall through and create one */
+    }
+  }
+  const secret = gen();
+  try {
+    fs.writeFileSync(SECRET_FILE, secret, { mode: 0o600 });
+  } catch (err) {
+    console.warn(
+      `[esque-bridge] could not persist pair secret to ${SECRET_FILE} ` +
+        `(${err.message}); it will rotate on next restart.`,
+    );
+  }
+  return secret;
+}
+const PAIRING_SECRET = resolvePairingSecret();
 
 function parseArgs(args) {
   const out = {};
@@ -267,15 +296,22 @@ function runAgent(prompt, esqueSessionId) {
       usesStdin = !argv.some((a) => a.includes(prompt));
     }
 
+    // detached → its own process group so we can kill the WHOLE tree (the
+    // agent can spawn its own subprocesses) on timeout instead of orphaning
+    // zombies.
     const child = spawn(bin, argv, {
       cwd: WORKDIR,
       env: process.env,
       stdio: ['pipe', 'pipe', 'pipe'],
+      detached: true,
     });
 
+    const MAX_BUF = 16 * 1024 * 1024; // hard cap so a runaway agent can't OOM the bridge
     let stdout = '';
     let stderr = '';
+    let truncated = false;
     let settled = false;
+    let killEscalation = null;
     const settle = (fn) => (val) => {
       if (settled) return;
       settled = true;
@@ -284,17 +320,50 @@ function runAgent(prompt, esqueSessionId) {
     const resolveOnce = settle(resolve);
     const rejectOnce = settle(reject);
 
+    const killTree = (signal) => {
+      try {
+        process.kill(-child.pid, signal);
+      } catch {
+        try {
+          child.kill(signal);
+        } catch {
+          /* already gone */
+        }
+      }
+    };
+
     const killTimer = setTimeout(() => {
-      child.kill('SIGTERM');
+      killTree('SIGTERM');
+      // Escalate to SIGKILL if the agent ignores SIGTERM.
+      killEscalation = setTimeout(() => killTree('SIGKILL'), 5000);
       rejectOnce(
         new Error(`${adapter.label} timed out after ${Math.round(TIMEOUT_MS / 1000)}s`),
       );
     }, TIMEOUT_MS);
+    const clearTimers = () => {
+      clearTimeout(killTimer);
+      if (killEscalation) clearTimeout(killEscalation);
+    };
+
+    const appendCapped = (buf, d) => {
+      if (truncated) return buf;
+      const next = buf + d;
+      if (next.length > MAX_BUF) {
+        truncated = true;
+        clearTimers();
+        killTree('SIGTERM');
+        rejectOnce(
+          new Error(`${adapter.label} produced too much output (>16MB) and was stopped.`),
+        );
+        return next.slice(0, MAX_BUF);
+      }
+      return next;
+    };
 
-    child.stdout.on('data', (d) => (stdout += d));
-    child.stderr.on('data', (d) => (stderr += d));
+    child.stdout.on('data', (d) => (stdout = appendCapped(stdout, d)));
+    child.stderr.on('data', (d) => (stderr = appendCapped(stderr, d)));
     child.on('error', (err) => {
-      clearTimeout(killTimer);
+      clearTimers();
       if (err.code === 'ENOENT') {
         rejectOnce(
           new Error(`'${bin}' not found in PATH. Install: ${adapter.install}`),
@@ -304,7 +373,8 @@ function runAgent(prompt, esqueSessionId) {
       rejectOnce(err);
     });
     child.on('close', (code) => {
-      clearTimeout(killTimer);
+      clearTimers();
+      if (truncated) return;
       if (code !== 0) {
         rejectOnce(
           new Error(
@@ -324,10 +394,15 @@ function runAgent(prompt, esqueSessionId) {
       }
     });
 
-    if (usesStdin) {
-      child.stdin.write(prompt);
+    // A child that dies at startup makes the stdin write throw EPIPE — an
+    // uncaught error that would otherwise crash the whole bridge.
+    child.stdin.on('error', () => {});
+    try {
+      if (usesStdin) child.stdin.write(prompt);
+      child.stdin.end();
+    } catch {
+      /* child already gone — handled by the 'error'/'close' listeners */
     }
-    child.stdin.end();
   });
 }
 
@@ -353,10 +428,16 @@ app.get('/', (_req, res) => {
   });
 });
 
-// Connection-test probe — no auth.
+// Connection-test probe — no auth required to confirm reachability, but if
+// the phone includes the pair secret we validate it and report back via
+// `paired` so the app can verify the secret BEFORE showing a green
+// "Paired" state. `paired` is true (match), false (wrong/stale secret), or
+// null (no secret sent — older app builds; we can't say either way).
 app.post('/', (req, res, next) => {
   if (req.body && req.body._probe === true) {
-    return res.json({ ok: true, service: 'esque-bridge', agent: AGENT_TYPE });
+    const provided = req.header('x-esque-pair') || req.body?.pairSecret;
+    const paired = provided == null ? null : provided === PAIRING_SECRET;
+    return res.json({ ok: true, service: 'esque-bridge', agent: AGENT_TYPE, paired });
   }
   return next();
 });
@@ -373,6 +454,125 @@ function requireAuth(req, res, next) {
   next();
 }
 
+// ── Live preview (bridge-owned) ───────────────────────────────────────
+// The agent declares a preview with a marker line in its reply:
+//     ESQUE_PREVIEW: <dev server start command> @ <port>
+//     e.g.  ESQUE_PREVIEW: npm run dev @ 3000
+//
+// The BRIDGE runs that dev server and tunnels it — NOT the one-shot
+// `claude --print`, which exits the instant its turn ends and would
+// orphan/kill anything it started (that's why the old "agent starts its
+// own tunnel" approach left the preview URL dead by the time you tapped
+// it). cloudflared is preferred over localtunnel because its URL has no
+// "click to continue" interstitial that would block the in-app WebView.
+const net = require('net');
+const { execSync } = require('child_process');
+
+let preview = null; // { port, proc, kind, url, tunnel, tunnelProc }
+
+function killPreview() {
+  if (!preview) return;
+  try { preview.proc && preview.proc.kill('SIGTERM'); } catch {}
+  try { preview.tunnel && preview.tunnel.close(); } catch {}
+  try { preview.tunnelProc && preview.tunnelProc.kill('SIGTERM'); } catch {}
+  preview = null;
+}
+
+function waitForPort(port, timeoutMs) {
+  const start = Date.now();
+  return new Promise((resolve) => {
+    const tick = () => {
+      const s = net.connect(port, '127.0.0.1');
+      s.on('connect', () => { s.destroy(); resolve(true); });
+      s.on('error', () => {
+        s.destroy();
+        if (Date.now() - start > timeoutMs) resolve(false);
+        else setTimeout(tick, 600);
+      });
+    };
+    tick();
+  });
+}
+
+function hasCloudflared() {
+  try { execSync('which cloudflared', { stdio: 'ignore' }); return true; }
+  catch { return false; }
+}
+
+// Open a public tunnel to a local port. Prefers cloudflared (clean URL,
+// no interstitial), falls back to localtunnel. Resolves the tunnel handle.
+function openPreviewTunnel(port) {
+  return new Promise(async (resolve) => {
+    if (hasCloudflared()) {
+      const proc = spawn('cloudflared', ['tunnel', '--url', `http://localhost:${port}`], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      let done = false;
+      const scan = (d) => {
+        const m = String(d).match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/i);
+        if (m && !done) { done = true; resolve({ url: m[0], kind: 'cloudflared', tunnelProc: proc }); }
+      };
+      proc.stdout.on('data', scan);
+      proc.stderr.on('data', scan);
+      setTimeout(() => { if (!done) { done = true; try { proc.kill(); } catch {} resolve(null); } }, 25000);
+    } else {
+      try {
+        const tunnel = await localtunnel({ port });
+        resolve({ url: tunnel.url, kind: 'localtunnel', tunnel });
+      } catch { resolve(null); }
+    }
+  });
+}
+
+async function startPreview(cmd, port) {
+  killPreview();
+  console.log(`[preview] starting: ${cmd}  (port ${port})`);
+  const proc = spawn('sh', ['-c', cmd], { cwd: WORKDIR, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+  proc.stdout.on('data', (d) => process.stdout.write(`[preview] ${d}`));
+  proc.stderr.on('data', (d) => process.stdout.write(`[preview] ${d}`));
+  proc.on('exit', (code) => console.log(`[preview] dev server exited (${code})`));
+  preview = { port, proc, kind: null, url: null, tunnel: null, tunnelProc: null };
+
+  const up = await waitForPort(port, 60000);
+  if (!up) { console.log('[preview] dev server never opened the port'); return null; }
+
+  const t = await openPreviewTunnel(port);
+  if (!t) { console.log('[preview] could not open a public tunnel'); return null; }
+  preview.url = t.url;
+  preview.kind = t.kind;
+  preview.tunnel = t.tunnel || null;
+  preview.tunnelProc = t.tunnelProc || null;
+  console.log(`[preview] live at ${t.url}  (${t.kind})`);
+  return t.url;
+}
+
+// Tolerate leading markdown punctuation / code-fence backticks the agent
+// may wrap the marker in (e.g. `ESQUE_PREVIEW: npm run dev @ 3000`), and an
+// optional trailing backtick — otherwise the whole preview feature no-ops.
+const PREVIEW_RE = /^[ \t>*`-]*ESQUE_PREVIEW:\s*(.+?)\s*@\s*(\d+)\s*`?[ \t]*$/im;
+
+// If the agent's reply declares a preview, start it (bridge-owned) and
+// swap the marker line for the public URL the phone can open.
+async function applyPreview(text) {
+  if (!text) return text;
+  const m = text.match(PREVIEW_RE);
+  if (!m) return text;
+  const cmd = m[1].trim();
+  const port = Number(m[2]);
+  let url = null;
+  try { url = await startPreview(cmd, port); } catch (e) { console.error('[preview] error:', e.message); }
+  const replacement = url
+    ? `🔗 Live preview: ${url}`
+    : `(Couldn't auto-start the preview — run \`${cmd}\` in ${WORKDIR} yourself.)`;
+  return text.replace(PREVIEW_RE, replacement);
+}
+
+async function runAgentWithPreview(prompt, sessionId) {
+  const result = await runAgent(prompt, sessionId);
+  if (result && result.text) result.text = await applyPreview(result.text);
+  return result;
+}
+
 // ── Async job store ───────────────────────────────────────────────────
 // A prompt can run for minutes (e.g. a full project scaffold). Holding one
 // HTTP connection open that long is fragile over tunnels and times the
@@ -392,6 +592,10 @@ function gcJobs() {
     if (now - j.createdAt > RESULT_TTL_MS) jobs.delete(id);
   }
 }
+// Evict expired jobs even on an idle bridge (the POST path GCs too, but an
+// idle bridge would otherwise hold finished jobs forever). unref so it
+// never keeps the process alive on its own.
+setInterval(gcJobs, 60_000).unref?.();
 
 async function executeHandler(req, res) {
   const body = req.body || {};
@@ -417,7 +621,7 @@ async function executeHandler(req, res) {
     const jobId = newJobId();
     jobs.set(jobId, { status: 'working', text: '', createdAt: Date.now() });
     res.json({ jobId, status: 'working' });
-    runAgent(prompt, esqueSessionId)
+    runAgentWithPreview(prompt, esqueSessionId)
       .then((result) => {
         jobs.set(jobId, {
           status: result.isError ? 'blocked' : 'finished',
@@ -463,7 +667,7 @@ async function executeHandler(req, res) {
   };
 
   try {
-    const result = await runAgent(prompt, esqueSessionId);
+    const result = await runAgentWithPreview(prompt, esqueSessionId);
     finish({
       text: result.text,
       status: result.isError ? 'blocked' : 'finished',
@@ -494,12 +698,60 @@ app.use((_req, res) => res.status(405).json({ error: 'POST only' }));
 
 // --- Boot -----------------------------------------------------------------
 
+// One-line y/N confirmation read from the controlling terminal. Resolves
+// true only on an explicit yes.
+function confirmWorkdir(dir) {
+  return new Promise((resolve) => {
+    const rl = require('readline').createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(
+      `\n  ⚠ Esque will let the AI agent READ and EDIT files in:\n      ${dir}\n` +
+        `    (Claude runs with --dangerously-skip-permissions, so it won't ask per-file.)\n` +
+        `  Continue? [y/N] `,
+      (answer) => {
+        rl.close();
+        resolve(/^y(es)?$/i.test(String(answer).trim()));
+      },
+    );
+  });
+}
+
 async function main() {
   if (!fs.existsSync(WORKDIR) || !fs.statSync(WORKDIR).isDirectory()) {
     console.error(`workdir does not exist: ${WORKDIR}`);
     process.exit(1);
   }
 
+  // Safety gate: confirm the working directory before exposing it to the
+  // agent. Only prompts on an interactive terminal — piped/CI starts (and
+  // `--yes`) skip it. This is the guard against accidentally running against
+  // $HOME or an unintended repo via `npx esque-bridge` in the wrong place.
+  if (process.stdin.isTTY && !argv.yes && !argv.y) {
+    const ok = await confirmWorkdir(WORKDIR);
+    if (!ok) {
+      console.log(
+        '\n  Aborted. cd into your project first, or pass --workdir <path>.\n',
+      );
+      process.exit(0);
+    }
+  }
+
+  // Claude Code refuses to run with --dangerously-skip-permissions as root,
+  // which would make every prompt fail on a healthy-looking pairing. Catch it
+  // up front with a plain-language fix instead.
+  if (
+    AGENT_TYPE === 'claude' &&
+    typeof process.getuid === 'function' &&
+    process.getuid() === 0
+  ) {
+    console.error('\n  ✗ Esque can\'t drive Claude as the root user.');
+    console.error('    Re-run WITHOUT sudo, as your normal user:');
+    console.error('      npx esque-bridge\n');
+    process.exit(1);
+  }
+
   await new Promise((resolve) => app.listen(PORT, resolve));
 
   let tunnel;
@@ -529,7 +781,7 @@ async function main() {
   console.log(`  Workdir      ${WORKDIR}`);
   console.log(`  Binary       ${AGENT_BIN ?? '(custom)'}`);
   console.log(
-    `  Pair secret  ${PAIRING_SECRET.slice(0, 8)}…  (rotates on restart — don't share)`,
+    `  Pair secret  ${PAIRING_SECRET.slice(0, 8)}…  (persists across restarts; --rotate to reset)`,
   );
   console.log('');
   console.log('  Press Ctrl-C to stop.');
@@ -537,6 +789,7 @@ async function main() {
 
   const shutdown = (signal) => {
     console.log(`\n  Received ${signal} — closing tunnel…`);
+    killPreview();
     try {
       tunnel.close();
     } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esque-bridge",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Desktop-side receiver for the Esque Agent mobile app. Pairs your phone with a local coding-agent CLI (Claude Code, Aider, or any custom command) via a tunnel + QR code, so prompts run through your subscription instead of per-token API billing.",
   "bin": {
     "esque-bridge": "index.js"