esque-bridge 0.6.13 → 0.6.15

package/index.js

@@ -87,6 +87,9 @@ const WORKDIR = path.resolve(
 // 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();
+// Optional bridge-side model override; the phone's per-request model wins over
+// this, and if neither is set the agent CLI uses its own default model.
+const MODEL_OVERRIDE = argv.model || process.env.ESQUE_MODEL || null;
 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;
@@ -191,6 +194,47 @@ function clearCliSessionId(agent, esqueSessionId) {
   saveSessions();
 }
 
+// --- Handoff log ----------------------------------------------------------
+// A running, on-disk record of each turn (prompt + what the agent did), kept in
+// the project folder. Its whole purpose is to survive a lost CLI session: if
+// the agent's conversation memory is ever GC'd, the fresh session is told to
+// read this file and recover the project's context — so a memory reset doesn't
+// mean starting from zero. Best-effort; bounded so it stays readable.
+const HANDOFF_MAX = 48 * 1024;
+function handoffRel(esqueSessionId) {
+  const short = String(esqueSessionId || 'default').replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 16) || 'default';
+  return `.esque/handoff-${short}.md`;
+}
+function handoffPath(esqueSessionId) {
+  return path.join(WORKDIR, handoffRel(esqueSessionId));
+}
+function appendHandoff(esqueSessionId, prompt, replyText) {
+  if (!esqueSessionId) return;
+  try {
+    fs.mkdirSync(path.join(WORKDIR, '.esque'), { recursive: true });
+    const file = handoffPath(esqueSessionId);
+    const header = fs.existsSync(file)
+      ? ''
+      : "# Esque handoff log\n\n> A running record of this project's work so your AI agent can recover context if its session is ever reset. Safe to delete (or add `.esque/` to .gitignore).\n\n";
+    const reply = String(replyText || '').trim().replace(/\n{3,}/g, '\n\n').slice(0, 1200);
+    const stamp = new Date().toISOString();
+    fs.appendFileSync(
+      file,
+      `${header}## ${stamp}\n\n**Prompt:** ${String(prompt || '').slice(0, 600)}\n\n**Agent:** ${reply || '(no output)'}\n\n---\n\n`,
+    );
+    // Keep it bounded: on overflow, retain the most recent entries (trim to a
+    // clean entry boundary so the recovered context reads cleanly).
+    const buf = fs.readFileSync(file, 'utf8');
+    if (buf.length > HANDOFF_MAX) {
+      const tail = buf.slice(buf.length - HANDOFF_MAX);
+      const cut = tail.indexOf('\n## ');
+      fs.writeFileSync(file, '# Esque handoff log (older entries trimmed)\n\n' + (cut >= 0 ? tail.slice(cut + 1) : tail));
+    }
+  } catch {
+    /* best-effort — never let handoff bookkeeping break a turn */
+  }
+}
+
 // --- Adapters -------------------------------------------------------------
 // Each adapter describes how to invoke a CLI for a single prompt. The
 // runner is identical across adapters; only argv-building and stdout
@@ -204,7 +248,7 @@ const ADAPTERS = {
       "npm install -g @anthropic-ai/claude-code, then \`claude /login\` to authenticate.",
     // `--output-format json` returns a single JSON object with
     // {result, session_id, is_error, ...} — easy to parse, exact.
-    buildArgs(_prompt, prevSessionId) {
+    buildArgs(_prompt, prevSessionId, model) {
       // `--dangerously-skip-permissions` lets Claude actually use its
       // Write / Edit / Bash tools without an interactive approval prompt.
       // In headless `--print` mode there's no way to say "yes" to a
@@ -219,6 +263,9 @@ const ADAPTERS = {
         'json',
         '--dangerously-skip-permissions',
       ];
+      // Optional per-agent model pin from the phone (Settings → Agent models).
+      // Claude accepts an alias (opus/sonnet/haiku) or a full model id.
+      if (model) args.push('--model', model);
       if (prevSessionId) args.push('--resume', prevSessionId);
       return args;
     },
@@ -229,9 +276,22 @@ const ADAPTERS = {
           text: r.result || r.text || '(claude returned no text)',
           cliSessionId: r.session_id || null,
           isError: !!r.is_error,
+          // Claude Code's JSON result already carries per-turn spend + tokens —
+          // free to surface (no extra process). Remaining WEEKLY/5h plan quota
+          // is NOT available headless (only the interactive `/usage` TUI), so we
+          // report cost + tokens per turn and let the phone keep a running total.
+          usage: {
+            agent: 'claude',
+            costUsd: typeof r.total_cost_usd === 'number' ? r.total_cost_usd : null,
+            inputTokens: r.usage?.input_tokens ?? null,
+            outputTokens: r.usage?.output_tokens ?? null,
+            cacheReadTokens: r.usage?.cache_read_input_tokens ?? null,
+            numTurns: r.num_turns ?? null,
+            durationMs: r.duration_ms ?? null,
+          },
         };
       } catch {
-        return { text: stdout.trim() || '(no output)', cliSessionId: null, isError: false };
+        return { text: stdout.trim() || '(no output)', cliSessionId: null, isError: false, usage: null };
       }
     },
   },
@@ -248,12 +308,14 @@ const ADAPTERS = {
     // looks busy but can't touch the disk. Access is already gated by the
     // pairing secret + the startup workdir confirmation. --skip-git-repo-check
     // lets it run in a brand-new (not-yet-git) project dir for `fresh` builds.
-    buildArgs(_prompt, _prevSessionId) {
-      return [
+    buildArgs(_prompt, _prevSessionId, model) {
+      const args = [
         'exec',
         '--dangerously-bypass-approvals-and-sandbox',
         '--skip-git-repo-check',
       ];
+      if (model) args.push('--model', model); // optional per-agent model pin
+      return args;
     },
     parseOutput(stdout) {
       // `codex exec` streams its run to stdout and logs to stderr; the trimmed
@@ -263,6 +325,13 @@ const ADAPTERS = {
         text: stdout.trim() || '(codex returned no output)',
         cliSessionId: null,
         isError: false,
+        // Per-turn tokens ARE available, but only by switching `exec` to
+        // `--json` (usage rides a `turn.completed` event) + `--output-last-message`
+        // to keep the reply text clean — a change to the invocation that needs a
+        // real Codex test before shipping, so it's deferred. Remaining rate-limit
+        // quota is NOT available in exec mode at all (rate_limits is null;
+        // openai/codex#14728). Reports null until the --json migration lands.
+        usage: null,
       };
     },
   },
@@ -280,22 +349,45 @@ const ADAPTERS = {
     // "--message -  = read stdin" convention; passing '-' would send the
     // agent a literal one-character message.
     promptInArgs: true,
-    buildArgs(prompt) {
-      return [
+    buildArgs(prompt, _prevSessionId, model) {
+      const args = [
         '--message', prompt,
         '--no-stream',
         '--yes-always',             // skip the "apply edit? y/n" prompts
         '--no-pretty',              // ANSI-free output for parsing
         '--no-show-model-warnings',
       ];
+      if (model) args.push('--model', model); // optional per-agent model pin
+      return args;
     },
     parseOutput(stdout) {
       // Aider streams its assistant turn interleaved with diff blocks.
       // Best-effort: return everything stdout produced.
+      // Aider auto-prints a cost line after each exchange (we already run
+      // --no-pretty so it's ANSI-free): "Tokens: 2.8k sent, 112 received.
+      // Cost: $0.01 message, $0.01 session." The session figure accumulates
+      // across turns in the same workdir, so it's a real running total.
+      const m = stdout.match(
+        /Tokens:\s*([\d.]+[kMK]?)\s*sent,\s*([\d.]+[kMK]?)\s*received\.\s*Cost:\s*\$([\d.]+)\s*message,\s*\$([\d.]+)\s*session/i,
+      );
+      const scale = (s) => {
+        const v = parseFloat(s);
+        return /m$/i.test(s) ? v * 1e6 : /k$/i.test(s) ? v * 1e3 : v;
+      };
+      const usage = m
+        ? {
+            agent: 'aider',
+            inputTokens: Math.round(scale(m[1])),
+            outputTokens: Math.round(scale(m[2])),
+            costUsd: parseFloat(m[3]),
+            costUsdSession: parseFloat(m[4]),
+          }
+        : null;
       return {
         text: stdout.trim() || '(aider returned no text)',
         cliSessionId: null,
         isError: false,
+        usage,
       };
     },
   },
@@ -352,12 +444,12 @@ if (AGENT_TYPE === 'custom') {
 // editing files after the bridge is gone.
 let activeAgentKill = null;
 
-function runAgent(prompt, esqueSessionId) {
+function runAgent(prompt, esqueSessionId, model) {
   return new Promise((resolve, reject) => {
     const prevId = getCliSessionId(AGENT_TYPE, esqueSessionId);
     let argv;
     try {
-      argv = adapter.buildArgs(prompt, prevId);
+      argv = adapter.buildArgs(prompt, prevId, model);
     } catch (err) {
       reject(err);
       return;
@@ -534,15 +626,31 @@ function runAgent(prompt, esqueSessionId) {
 // bricked forever. Detect that specific failure, drop the mapping, and rerun
 // once as a fresh CLI session.
 const RESUME_FAIL_RE = /no conversation found|session.*not found|unknown session|invalid session/i;
-async function runAgentResilient(prompt, esqueSessionId) {
+async function runAgentResilient(prompt, esqueSessionId, model) {
   const prevId = getCliSessionId(AGENT_TYPE, esqueSessionId);
   try {
-    return await runAgent(prompt, esqueSessionId);
+    return await runAgent(prompt, esqueSessionId, model);
   } catch (err) {
     if (prevId && RESUME_FAIL_RE.test(String(err && err.message))) {
       console.warn('[bridge] stored CLI session is gone — retrying as a fresh session');
       clearCliSessionId(AGENT_TYPE, esqueSessionId);
-      return runAgent(prompt, esqueSessionId);
+      // The agent lost its memory. If we've been keeping a handoff log, point
+      // the fresh session at it FIRST so it recovers the project's context
+      // instead of starting from zero.
+      let recovered = prompt;
+      try {
+        if (fs.existsSync(handoffPath(esqueSessionId))) {
+          recovered =
+            `[Esque session recovery] Your previous conversation in this project was reset and its in-memory context was lost. ` +
+            `BEFORE anything else, read the file \`${handoffRel(esqueSessionId)}\` in this folder — a running log of everything done in this project so far — and use it to reconstruct context. Then carry out this request:\n\n${prompt}`;
+        }
+      } catch {
+        /* fall back to the bare prompt */
+      }
+      const fresh = await runAgent(recovered, esqueSessionId, model);
+      // Tell the phone the agent's memory was reset (it ignores the field if
+      // unknown). Older bridges never set it.
+      return { ...fresh, sessionReset: true };
     }
     throw err;
   }
@@ -798,6 +906,45 @@ function waitForPort(port, timeoutMs) {
   });
 }
 
+// Reclaim `port` from any process already listening on it. A stale/foreign dev
+// server squatting on the preview port is the #1 cause of "the preview shows
+// the WRONG project": waitForPort() only checks that SOMETHING is listening, so
+// a leftover Metro/Vite/expo from another repo would get tunneled instead of the
+// server we just started. Esque owns the preview port, so we forcibly clear it
+// before starting ours. Best-effort + synchronous (we're about to rebind).
+// Returns the number of processes killed.
+function freePort(port) {
+  try {
+    if (isWindows) {
+      const out = execSync(`netstat -ano -p tcp | findstr :${port}`, {
+        encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      const pids = new Set();
+      out.split('\n').forEach((l) => {
+        const m = l.trim().match(/LISTENING\s+(\d+)\s*$/i);
+        if (m) pids.add(m[1]);
+      });
+      pids.forEach((pid) => {
+        try { execSync(`taskkill /PID ${pid} /T /F`, { stdio: 'ignore' }); } catch { /* already gone */ }
+      });
+      return pids.size;
+    }
+    const out = execSync(`lsof -ti tcp:${port} -sTCP:LISTEN`, {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (!out) return 0;
+    const pids = out.split('\n').map((s) => s.trim()).filter(Boolean);
+    pids.forEach((pid) => {
+      try { process.kill(Number(pid), 'SIGKILL'); } catch { /* already gone */ }
+    });
+    return pids.length;
+  } catch {
+    // lsof/netstat exit non-zero when nothing is on the port — that's the
+    // common (port-is-free) case, not an error.
+    return 0;
+  }
+}
+
 function hasCloudflared() {
   try { execSync(isWindows ? 'where cloudflared' : 'which cloudflared', { stdio: 'ignore' }); return true; }
   catch { return false; }
@@ -909,6 +1056,15 @@ async function probeBuildError(port) {
   if (!root) return null; // couldn't reach it — don't cry wolf
   if (root.status >= 500) return summarizeBuildError(root.status, root.body);
 
+  // A NATIVE Expo dev server (`expo start`, without --web) serves a JSON
+  // MANIFEST at the root — not a web page — so the phone's webview shows raw
+  // JSON / a blank screen. The web preview must use `expo start --web` (React
+  // Native Web), which serves HTML. If we see a native manifest, say exactly
+  // what's wrong instead of handing the phone something it can't render.
+  if (/"launchAsset"/.test(root.body) && /AppEntry|expoGo|packagerOpts|debuggerHost/.test(root.body)) {
+    return 'This preview is a NATIVE Expo dev server (expo start), which serves a manifest the phone cannot render — you would see raw JSON or a blank screen. The web preview must run React Native Web: npx expo install react-native-web react-dom @expo/metro-runtime && npx expo start --web';
+  }
+
   // Expo/Metro: the HTML points at a *.bundle script. Fetching it forces the
   // compile and surfaces the react-native-web class of error as a 500.
   const m = root.body.match(/<script[^>]+src="([^"]*\.bundle[^"]*)"/i);
@@ -1054,6 +1210,16 @@ async function startPreview(cmd, port) {
     console.error(`[preview] dependency install failed:\n${deps.error}`);
     return { url: null, buildError: deps.error };
   }
+  // Reclaim the port from any stale/foreign dev server BEFORE starting ours.
+  // Without this, a leftover server from another project (e.g. a manual
+  // `expo start` left running on 8081) would be what waitForPort() latches onto,
+  // and we'd tunnel the WRONG project to the phone. Give the port a moment to
+  // actually release before we try to bind it.
+  const cleared = freePort(port);
+  if (cleared) {
+    console.log(`[preview] cleared ${cleared} stale process(es) on port ${port} before starting`);
+    await new Promise((r) => setTimeout(r, 400));
+  }
   console.log(`[preview] starting: ${cmd}  (port ${port})`);
   // Remember the command now (not on success): a revival attempt after a
   // mid-start crash should still know what to run.
@@ -1154,8 +1320,8 @@ async function applyPreview(text) {
   return { text: text.replace(PREVIEW_RE, () => replacement), buildError };
 }
 
-async function runAgentWithPreview(prompt, sessionId) {
-  const result = await runAgentResilient(prompt, sessionId);
+async function runAgentWithPreview(prompt, sessionId, model) {
+  const result = await runAgentResilient(prompt, sessionId, model);
   if (!result || !result.text) return result;
 
   const applied = await applyPreview(result.text);
@@ -1174,7 +1340,7 @@ async function runAgentWithPreview(prompt, sessionId) {
       `Fix the root cause in the code, then re-emit the ESQUE_PREVIEW marker on ` +
       `its own line. Keep the explanation brief — make the fix and output the marker.`;
     let fix = null;
-    try { fix = await runAgentResilient(fixPrompt, sessionId); } catch (e) { console.error('[preview] auto-fix run failed:', e.message); }
+    try { fix = await runAgentResilient(fixPrompt, sessionId, model); } catch (e) { console.error('[preview] auto-fix run failed:', e.message); }
     if (fix && fix.text) {
       const fixApplied = await applyPreview(fix.text);
       result.text = `${applied.text}\n\n— Auto-fix attempt —\n${fixApplied.text}`;
@@ -1248,8 +1414,8 @@ async function sendExpoPush(token, kind, sessionId, title, message) {
 // races two --resume's of the same CLI session, and collides in the preview
 // pipeline. A simple promise chain keeps arrival order and isolates failures.
 let runQueue = Promise.resolve();
-function enqueueRun(prompt, sessionId) {
-  const run = runQueue.then(() => runAgentWithPreview(prompt, sessionId));
+function enqueueRun(prompt, sessionId, model) {
+  const run = runQueue.then(() => runAgentWithPreview(prompt, sessionId, model));
   runQueue = run.then(() => undefined, () => undefined);
   return run;
 }
@@ -1259,6 +1425,10 @@ async function executeHandler(req, res) {
   const prompt = String(body.prompt || '');
   const esqueSessionId = body.sessionId ?? null;
   const pushToken = typeof body.pushToken === 'string' ? body.pushToken : null;
+  // Optional per-agent model pin sent by the phone (Settings → Agent models).
+  // Falls back to a bridge-side --model / ESQUE_MODEL override if the phone
+  // sends none, else the agent CLI's own default model.
+  const model = typeof body.model === 'string' && body.model.trim() ? body.model.trim() : MODEL_OVERRIDE;
   if (!prompt.trim()) {
     return res.status(400).json({ text: 'Empty prompt.', status: 'blocked' });
   }
@@ -1279,16 +1449,19 @@ async function executeHandler(req, res) {
     const jobId = newJobId();
     jobs.set(jobId, { status: 'working', text: '', createdAt: Date.now() });
     res.json({ jobId, status: 'working' });
-    enqueueRun(prompt, esqueSessionId)
+    enqueueRun(prompt, esqueSessionId, model)
       .then((result) => {
         jobs.set(jobId, {
           status: result.isError ? 'blocked' : 'finished',
           text: result.text,
+          sessionReset: !!result.sessionReset,
+          usage: result.usage ?? null,
           createdAt: Date.now(),
         });
         console.log(
           `[bridge] done  job=${jobId}  ${result.isError ? 'blocked' : 'finished'}`,
         );
+        if (!result.isError) appendHandoff(esqueSessionId, prompt, result.text);
         const ok = !result.isError;
         sendExpoPush(
           pushToken,
@@ -1334,10 +1507,13 @@ async function executeHandler(req, res) {
   };
 
   try {
-    const result = await enqueueRun(prompt, esqueSessionId);
+    const result = await enqueueRun(prompt, esqueSessionId, model);
+    if (!result.isError) appendHandoff(esqueSessionId, prompt, result.text);
     finish({
       text: result.text,
       status: result.isError ? 'blocked' : 'finished',
+      sessionReset: !!result.sessionReset,
+      usage: result.usage ?? null,
     });
   } catch (err) {
     console.error('[bridge] error:', err.message);
@@ -1355,7 +1531,7 @@ function resultHandler(req, res) {
       text: 'That task is no longer available — the bridge may have restarted.',
     });
   }
-  res.json({ status: job.status, text: job.text });
+  res.json({ status: job.status, text: job.text, sessionReset: !!job.sessionReset, usage: job.usage ?? null });
 }
 
 // Single-flight wrapper for reviving the saved preview: GET /preview and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esque-bridge",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "description": "Desktop-side receiver for the Esque Agent mobile app. Pairs your phone with a local coding-agent CLI (Claude Code, Codex, 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"