esque-bridge 0.2.1 → 0.3.0

package/index.js

@@ -71,7 +71,10 @@ const PORT = Number(argv.port || process.env.PORT || 3030);
 const WORKDIR = path.resolve(
   argv.workdir || process.env.CLAUDE_WORKDIR || process.cwd(),
 );
-const TIMEOUT_MS = Number(argv.timeout || 5 * 60 * 1000);
+// 20 min default. With the async protocol the phone no longer holds a
+// connection open, so a generous ceiling just lets big agentic tasks (full
+// scaffolds) finish. Override with --timeout.
+const TIMEOUT_MS = Number(argv.timeout || 20 * 60 * 1000);
 const AGENT_TYPE = String(argv.agent || process.env.ESQUE_AGENT || 'claude').toLowerCase();
 const CUSTOM_CMD = argv.cmd || process.env.ESQUE_CMD || null;
 const BIN_OVERRIDE = argv.bin || null;
@@ -370,6 +373,142 @@ 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;
+}
+
+const PREVIEW_RE = /^[ \t]*ESQUE_PREVIEW:\s*(.+?)\s*@\s*(\d+)[ \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
+// phone out. Newer phones advertise `x-esque-async`; they get a jobId back
+// immediately and poll GET /result/:id while the agent runs in the
+// background. Jobs are evicted after a TTL so the map can't grow unbounded.
+const jobs = new Map(); // jobId -> { status, text, createdAt }
+const RESULT_TTL_MS = 30 * 60 * 1000;
+let jobSeq = 0;
+function newJobId() {
+  jobSeq += 1;
+  return `j${Date.now().toString(36)}${jobSeq.toString(36)}`;
+}
+function gcJobs() {
+  const now = Date.now();
+  for (const [id, j] of jobs) {
+    if (now - j.createdAt > RESULT_TTL_MS) jobs.delete(id);
+  }
+}
+
 async function executeHandler(req, res) {
   const body = req.body || {};
   const prompt = String(body.prompt || '');
@@ -384,12 +523,42 @@ async function executeHandler(req, res) {
     `[bridge] POST  ${preview}…  esque=${esqueSessionId ?? '-'}  ${AGENT_TYPE}=${prev ?? 'new'}`,
   );
 
-  // Stream a keep-alive heartbeat while the agent thinks. `claude --print`
-  // emits nothing until it finishes (often 30–120s on a cold start with a big
-  // prompt), and localtunnel / intervening proxies close *idle* connections —
-  // which surfaced on the phone as "fetch request has been canceled". A space
-  // every few seconds keeps the connection active. The phone trims the body
-  // before JSON.parse, so leading whitespace is harmless.
+  // ── Async path (polling-capable phones) ─────────────────────────────
+  // Return a jobId instantly and run the agent in the background. The phone
+  // polls GET /result/:id every few seconds — tiny requests that survive
+  // any tunnel and never time out, no matter how long the task runs.
+  const wantsAsync = req.header('x-esque-async') === '1' || body.async === true;
+  if (wantsAsync) {
+    gcJobs();
+    const jobId = newJobId();
+    jobs.set(jobId, { status: 'working', text: '', createdAt: Date.now() });
+    res.json({ jobId, status: 'working' });
+    runAgentWithPreview(prompt, esqueSessionId)
+      .then((result) => {
+        jobs.set(jobId, {
+          status: result.isError ? 'blocked' : 'finished',
+          text: result.text,
+          createdAt: Date.now(),
+        });
+        console.log(
+          `[bridge] done  job=${jobId}  ${result.isError ? 'blocked' : 'finished'}`,
+        );
+      })
+      .catch((err) => {
+        jobs.set(jobId, {
+          status: 'blocked',
+          text: `${adapter.label} failed: ${err.message}`,
+          createdAt: Date.now(),
+        });
+        console.error(`[bridge] error  job=${jobId}:`, err.message);
+      });
+    return;
+  }
+
+  // ── Legacy synchronous path (older phones) ──────────────────────────
+  // Hold the connection open with a keep-alive heartbeat so idle-closing
+  // proxies don't drop it while the agent thinks. The phone trims the body
+  // before JSON.parse, so the leading whitespace is harmless.
   res.status(200);
   res.setHeader('Content-Type', 'application/json; charset=utf-8');
   res.setHeader('Cache-Control', 'no-cache, no-transform');
@@ -410,21 +579,33 @@ 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',
     });
   } catch (err) {
     console.error('[bridge] error:', err.message);
-    // Headers are already sent (heartbeat), so the error rides in the body
-    // with status 'blocked' rather than an HTTP 500.
     finish({ text: `${adapter.label} failed: ${err.message}`, status: 'blocked' });
   }
 }
 
+// Poll endpoint for the async protocol. Returns the job's current state:
+// { status: 'working' | 'finished' | 'blocked', text }.
+function resultHandler(req, res) {
+  const job = jobs.get(req.params.id);
+  if (!job) {
+    return res.status(404).json({
+      status: 'blocked',
+      text: 'That task is no longer available — the bridge may have restarted.',
+    });
+  }
+  res.json({ status: job.status, text: job.text });
+}
+
 app.post('/execute', requireAuth, executeHandler);
 app.post('/', requireAuth, executeHandler);
+app.get('/result/:id', requireAuth, resultHandler);
 app.use((_req, res) => res.status(405).json({ error: 'POST only' }));
 
 // --- Boot -----------------------------------------------------------------
@@ -472,6 +653,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.1",
+  "version": "0.3.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"