esque-bridge 0.1.0 → 0.2.1

package/index.js

@@ -2,20 +2,19 @@
 /**
  * esque-bridge — the desktop-side receiver for the Esque Agent mobile app.
  *
- * Pairs your phone with the local `claude` CLI so prompts sent from the
- * Esque iOS app run through your Claude Pro / Max subscription rather than
- * per-token API billing. The bridge:
+ * Pairs your phone with a local coding-agent CLI (Claude Code by default,
+ * Aider, or any custom command) so prompts you send from the Esque app
+ * run through your subscription rather than per-token API billing.
  *
  *   1. Boots an Express server on localhost
- *   2. Opens a public localtunnel URL to that port
- *   3. Prints a QR code embedding `esque://pair?url=…&secret=…` in your
- *      terminal — scan it from the Esque app to pair
- *   4. Accepts POST /execute { prompt, sessionId } (pairing-secret-gated)
- *      and runs the prompt through `claude --print`, returning stdout
+ *   2. Opens a public localtunnel URL
+ *   3. Prints a QR code embedding `esque://pair?url=…&secret=…&agent=…`
+ *   4. Accepts POST /execute (pairing-secret-gated) and runs the prompt
+ *      through the configured agent adapter, returning stdout
  *
- * Run it:
- *   npx esque-bridge                            # zero-config
- *   esque-bridge --workdir ~/my-project         # point claude at a repo
+ *   npx esque-bridge                            # default: claude
+ *   npx esque-bridge --agent aider              # Aider against the current repo
+ *   npx esque-bridge --agent custom --cmd 'mycli --prompt {prompt}'
  */
 
 const express = require('express');
@@ -34,21 +33,31 @@ const argv = parseArgs(process.argv.slice(2));
 if (argv.help || argv.h) {
   console.log(
     `
-Esque Bridge — pair your phone with your local Claude Code.
+Esque Bridge — pair your phone with a local coding-agent CLI.
 
 USAGE
-  esque-bridge [--port 3030] [--workdir .] [--bin claude] [--timeout 300000]
+  esque-bridge [--agent claude|aider|custom] [--port 3030] [--workdir .]
+               [--cmd 'tool --prompt {prompt}'] [--bin <binary>]
+               [--timeout 300000]
+
+AGENT ADAPTERS
+  claude (default) — uses Claude Code CLI (\`claude --print --output-format json\`).
+                     Persists session ids so each conversation continues via --resume.
+  aider           — uses Aider CLI (\`aider --message ... --yes-always --no-stream\`).
+                     Conversation continuity is handled by aider's own .aider.chat.history.md.
+  custom          — runs an arbitrary command. Pass --cmd 'tool --prompt {prompt}'
+                     with literal {prompt} as a placeholder.
 
 OPTIONS
   --port      Local HTTP port to listen on (default: 3030)
-  --workdir   Working directory for claude (default: current dir)
-  --bin       Path to claude CLI binary (default: 'claude' on PATH)
+  --workdir   Working directory for the agent (default: current dir)
+  --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)
 
 PREREQS
-  npm install -g @anthropic-ai/claude-code
-  claude /login                                 # one-time OAuth
+  Claude:  npm install -g @anthropic-ai/claude-code   &&   claude /login
+  Aider:   python -m pip install aider-chat
 
 OUTPUT
   Prints a QR code in your terminal. Scan it from the Esque iOS app to
@@ -63,7 +72,9 @@ const WORKDIR = path.resolve(
   argv.workdir || process.env.CLAUDE_WORKDIR || process.cwd(),
 );
 const TIMEOUT_MS = Number(argv.timeout || 5 * 60 * 1000);
-const CLAUDE_BIN = argv.bin || process.env.CLAUDE_BIN || 'claude';
+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;
 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');
@@ -86,8 +97,8 @@ function parseArgs(args) {
 }
 
 // --- Session persistence -------------------------------------------------
-// Map of {esqueSessionId → claudeSessionId} so each conversation continues
-// in-context across prompts via `claude --resume`. Survives bridge restarts.
+// Per-agent map of {esqueSessionId → cliSessionId}. Each adapter that
+// supports --resume reads/writes its own slot. Survives bridge restarts.
 
 let sessionMap = {};
 try {
@@ -102,23 +113,158 @@ function saveSessions() {
     console.warn('[bridge] could not persist session map:', err.message);
   }
 }
+function getCliSessionId(agent, esqueSessionId) {
+  if (!esqueSessionId) return null;
+  return sessionMap[agent]?.[esqueSessionId] ?? null;
+}
+function setCliSessionId(agent, esqueSessionId, cliId) {
+  if (!cliId || !esqueSessionId) return;
+  if (!sessionMap[agent]) sessionMap[agent] = {};
+  sessionMap[agent][esqueSessionId] = cliId;
+  saveSessions();
+}
+
+// --- Adapters -------------------------------------------------------------
+// Each adapter describes how to invoke a CLI for a single prompt. The
+// runner is identical across adapters; only argv-building and stdout
+// parsing differ.
+
+const ADAPTERS = {
+  claude: {
+    label: 'Claude Code',
+    defaultBin: 'claude',
+    install:
+      "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) {
+      // `--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
+      // permission request, so without this every file write is silently
+      // blocked — the agent looks busy but can't touch the disk. This is
+      // the autonomous-bridge use case the flag exists for; access is
+      // already gated by the per-session pairing secret. (Mirrors Aider's
+      // `--yes-always` below.)
+      const args = [
+        '--print',
+        '--output-format',
+        'json',
+        '--dangerously-skip-permissions',
+      ];
+      if (prevSessionId) args.push('--resume', prevSessionId);
+      return args;
+    },
+    parseOutput(stdout) {
+      try {
+        const r = JSON.parse(stdout);
+        return {
+          text: r.result || r.text || '(claude returned no text)',
+          cliSessionId: r.session_id || null,
+          isError: !!r.is_error,
+        };
+      } catch {
+        return { text: stdout.trim() || '(no output)', cliSessionId: null, isError: false };
+      }
+    },
+  },
+
+  aider: {
+    label: 'Aider',
+    defaultBin: 'aider',
+    install: 'python -m pip install aider-chat',
+    // Aider keeps its own .aider.chat.history.md per-directory, so we
+    // don't need to track a session id — every invocation against the
+    // same workdir picks up where the last one left off.
+    buildArgs(_prompt) {
+      return [
+        '--message', '-',           // read message from stdin (we'll pipe it)
+        '--no-stream',
+        '--yes-always',             // skip the "apply edit? y/n" prompts
+        '--no-pretty',              // ANSI-free output for parsing
+        '--no-show-model-warnings',
+      ];
+    },
+    parseOutput(stdout) {
+      // Aider streams its assistant turn interleaved with diff blocks.
+      // Best-effort: return everything stdout produced.
+      return {
+        text: stdout.trim() || '(aider returned no text)',
+        cliSessionId: null,
+        isError: false,
+      };
+    },
+  },
+
+  custom: {
+    label: 'Custom',
+    defaultBin: null,
+    install:
+      "Pass --cmd 'your-cli --prompt {prompt}' (with literal {prompt} as placeholder).",
+    buildArgs(_prompt) {
+      if (!CUSTOM_CMD) {
+        throw new Error(
+          "--agent custom requires --cmd '<command-template>' with {prompt} placeholder.",
+        );
+      }
+      // Split the template on whitespace but preserve {prompt} as its own
+      // argv slot (so the runner can substitute the prompt body in).
+      return CUSTOM_CMD.split(/\s+/).filter(Boolean);
+    },
+    parseOutput(stdout) {
+      return {
+        text: stdout.trim() || '(no output)',
+        cliSessionId: null,
+        isError: false,
+      };
+    },
+  },
+};
+
+if (!ADAPTERS[AGENT_TYPE]) {
+  console.error(
+    `Unknown --agent: ${AGENT_TYPE}. Use one of: ${Object.keys(ADAPTERS).join(', ')}.`,
+  );
+  process.exit(1);
+}
 
-// --- Claude runner --------------------------------------------------------
+const adapter = ADAPTERS[AGENT_TYPE];
+const AGENT_BIN = BIN_OVERRIDE || adapter.defaultBin;
 
-function runClaude(prompt, claudeSessionId) {
+if (AGENT_TYPE === 'custom') {
+  if (!CUSTOM_CMD) {
+    console.error(
+      "--agent custom requires --cmd '<your-cli> {prompt}' (literal {prompt} substitution).",
+    );
+    process.exit(1);
+  }
+}
+
+// --- Runner ---------------------------------------------------------------
+
+function runAgent(prompt, esqueSessionId) {
   return new Promise((resolve, reject) => {
-    // `--output-format json` returns a single JSON object with
-    // {result, session_id, is_error, total_cost_usd, ...}. Far simpler to
-    // consume than the NDJSON stream-json mode; we trade incremental
-    // progress for parse-once reliability.
-    const args = ['--print', '--output-format', 'json'];
-    if (claudeSessionId) args.push('--resume', claudeSessionId);
-
-    // spawn (not exec) — argv array means no shell interpretation, so the
-    // prompt content can't inject shell commands. The prompt itself goes
-    // through stdin to avoid ARG_MAX on long blueprint payloads (the god
-    // prompt easily exceeds 16 KB).
-    const child = spawn(CLAUDE_BIN, args, {
+    const prevId = getCliSessionId(AGENT_TYPE, esqueSessionId);
+    let argv;
+    try {
+      argv = adapter.buildArgs(prompt, prevId);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+
+    // For 'custom', substitute the {prompt} placeholder in argv. For
+    // built-in adapters, the prompt always rides via stdin (avoids
+    // ARG_MAX on long blueprint payloads).
+    let bin = AGENT_BIN;
+    let usesStdin = true;
+    if (AGENT_TYPE === 'custom') {
+      bin = argv.shift();
+      argv = argv.map((a) => a.replace('{prompt}', prompt));
+      usesStdin = !argv.some((a) => a.includes(prompt));
+    }
+
+    const child = spawn(bin, argv, {
       cwd: WORKDIR,
       env: process.env,
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -138,7 +284,7 @@ function runClaude(prompt, claudeSessionId) {
     const killTimer = setTimeout(() => {
       child.kill('SIGTERM');
       rejectOnce(
-        new Error(`claude timed out after ${Math.round(TIMEOUT_MS / 1000)}s`),
+        new Error(`${adapter.label} timed out after ${Math.round(TIMEOUT_MS / 1000)}s`),
       );
     }, TIMEOUT_MS);
 
@@ -148,9 +294,7 @@ function runClaude(prompt, claudeSessionId) {
       clearTimeout(killTimer);
       if (err.code === 'ENOENT') {
         rejectOnce(
-          new Error(
-            `'${CLAUDE_BIN}' not found in PATH. Install: npm install -g @anthropic-ai/claude-code, then \`claude /login\`.`,
-          ),
+          new Error(`'${bin}' not found in PATH. Install: ${adapter.install}`),
         );
         return;
       }
@@ -161,31 +305,25 @@ function runClaude(prompt, claudeSessionId) {
       if (code !== 0) {
         rejectOnce(
           new Error(
-            `claude exited ${code}${stderr ? `: ${stderr.trim().slice(0, 500)}` : ''}`,
+            `${adapter.label} exited ${code}${stderr ? `: ${stderr.trim().slice(0, 500)}` : ''}`,
           ),
         );
         return;
       }
       try {
-        const result = JSON.parse(stdout);
-        resolveOnce({
-          text:
-            result.result || result.text || '(claude returned no text)',
-          sessionId: result.session_id || null,
-          isError: !!result.is_error,
-        });
-      } catch {
-        // Claude returned non-JSON for some reason — surface raw stdout so
-        // the user at least sees what happened.
-        resolveOnce({
-          text: stdout.trim() || '(no output)',
-          sessionId: null,
-          isError: false,
-        });
+        const parsed = adapter.parseOutput(stdout);
+        if (parsed.cliSessionId) {
+          setCliSessionId(AGENT_TYPE, esqueSessionId, parsed.cliSessionId);
+        }
+        resolveOnce(parsed);
+      } catch (err) {
+        rejectOnce(err);
       }
     });
 
-    child.stdin.write(prompt);
+    if (usesStdin) {
+      child.stdin.write(prompt);
+    }
     child.stdin.end();
   });
 }
@@ -194,34 +332,28 @@ function runClaude(prompt, claudeSessionId) {
 
 const app = express();
 app.use(express.json({ limit: '5mb' }));
-
-// Disable Express's default x-powered-by header and any tunnel-side
-// caching surprises.
 app.disable('x-powered-by');
 app.use((req, res, next) => {
   res.setHeader('Cache-Control', 'no-store');
   next();
 });
 
-// Public health probe. No auth — anyone hitting the URL gets a tiny "is
-// the bridge alive" answer. The Esque app's connection-test uses this for
-// reachability before it sends a real prompt.
+// Public health probe.
 app.get('/', (_req, res) => {
   res.json({
     ok: true,
     service: 'esque-bridge',
+    agent: AGENT_TYPE,
+    agentLabel: adapter.label,
     workdir: WORKDIR,
-    sessions: Object.keys(sessionMap).length,
+    sessions: Object.keys(sessionMap[AGENT_TYPE] ?? {}).length,
   });
 });
 
-// Pairing-check shim — Esque's `testConnectionDetailed()` sends a probe
-// POST with `_probe: true`. Reply OK without invoking claude, and without
-// requiring the secret (because the very first thing a freshly-paired app
-// will do is run this check).
+// Connection-test probe — no auth.
 app.post('/', (req, res, next) => {
   if (req.body && req.body._probe === true) {
-    return res.json({ ok: true, service: 'esque-bridge' });
+    return res.json({ ok: true, service: 'esque-bridge', agent: AGENT_TYPE });
   }
   return next();
 });
@@ -238,8 +370,6 @@ function requireAuth(req, res, next) {
   next();
 }
 
-// The execute endpoint. Body: { prompt, sessionId?, pushToken? }.
-// Returns: { text, status: 'finished' | 'blocked' }.
 async function executeHandler(req, res) {
   const body = req.body || {};
   const prompt = String(body.prompt || '');
@@ -248,37 +378,53 @@ async function executeHandler(req, res) {
     return res.status(400).json({ text: 'Empty prompt.', status: 'blocked' });
   }
 
-  const claudeSid = esqueSessionId ? sessionMap[esqueSessionId] : null;
+  const prev = getCliSessionId(AGENT_TYPE, esqueSessionId);
   const preview = prompt.slice(0, 80).replace(/\s+/g, ' ');
   console.log(
-    `[bridge] POST  ${preview}…  esque=${esqueSessionId ?? '-'}  claude=${claudeSid ?? 'new'}`,
+    `[bridge] POST  ${preview}…  esque=${esqueSessionId ?? '-'}  ${AGENT_TYPE}=${prev ?? 'new'}`,
   );
 
-  try {
-    const result = await runClaude(prompt, claudeSid);
-    if (result.sessionId && esqueSessionId) {
-      sessionMap[esqueSessionId] = result.sessionId;
-      saveSessions();
+  // 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.
+  res.status(200);
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  res.setHeader('Cache-Control', 'no-cache, no-transform');
+  const heartbeat = setInterval(() => {
+    try {
+      res.write(' ');
+    } catch {
+      /* socket already closed */
     }
-    res.json({
+  }, 5000);
+  const finish = (payload) => {
+    clearInterval(heartbeat);
+    try {
+      res.end(JSON.stringify(payload));
+    } catch {
+      /* socket already closed */
+    }
+  };
+
+  try {
+    const result = await runAgent(prompt, esqueSessionId);
+    finish({
       text: result.text,
       status: result.isError ? 'blocked' : 'finished',
     });
   } catch (err) {
     console.error('[bridge] error:', err.message);
-    res
-      .status(500)
-      .json({ text: `Claude bridge failed: ${err.message}`, status: 'blocked' });
+    // 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' });
   }
 }
 
-// Two routes for the same handler: `/` (what the Esque app POSTs to today)
-// and `/execute` (the cleaner name the directive spec specified — kept so
-// future iOS versions can switch without breaking the bridge).
 app.post('/execute', requireAuth, executeHandler);
 app.post('/', requireAuth, executeHandler);
-
-// Anything else: 405.
 app.use((_req, res) => res.status(405).json({ error: 'POST only' }));
 
 // --- Boot -----------------------------------------------------------------
@@ -296,30 +442,27 @@ async function main() {
     tunnel = await localtunnel({ port: PORT, subdomain: LT_SUBDOMAIN });
   } catch (err) {
     console.error('Failed to open localtunnel:', err.message);
-    console.error(
-      'If localtunnel.me is blocked on your network, try cloudflared:',
-    );
+    console.error('If localtunnel.me is blocked, try cloudflared:');
     console.error(`  cloudflared tunnel --url http://localhost:${PORT}`);
     process.exit(1);
   }
 
-  const pairUrl = `esque://pair?url=${encodeURIComponent(tunnel.url)}&secret=${PAIRING_SECRET}`;
+  const pairUrl = `esque://pair?url=${encodeURIComponent(tunnel.url)}&secret=${PAIRING_SECRET}&agent=${AGENT_TYPE}`;
 
   console.log('');
   console.log('━'.repeat(68));
-  console.log('  Esque Bridge Active');
+  console.log(`  Esque Bridge Active  ·  ${adapter.label}`);
   console.log('━'.repeat(68));
   console.log('');
-  console.log(
-    '  Scan this QR code with the Esque Agent mobile app to pair your device.',
-  );
+  console.log('  Scan this QR code with the Esque Agent mobile app to pair.');
   console.log('');
   qrcode.generate(pairUrl, { small: true });
   console.log('');
+  console.log(`  Agent        ${adapter.label} (${AGENT_TYPE})`);
   console.log(`  Local        http://localhost:${PORT}`);
   console.log(`  Tunnel       ${tunnel.url}`);
   console.log(`  Workdir      ${WORKDIR}`);
-  console.log(`  Claude bin   ${CLAUDE_BIN}`);
+  console.log(`  Binary       ${AGENT_BIN ?? '(custom)'}`);
   console.log(
     `  Pair secret  ${PAIRING_SECRET.slice(0, 8)}…  (rotates on restart — don't share)`,
   );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "esque-bridge",
-  "version": "0.1.0",
-  "description": "Desktop-side receiver for the Esque Agent mobile app. Pairs your phone with your local Claude Code CLI via a tunnel + QR code, so prompts run through your Claude Pro / Max subscription instead of per-token API billing.",
+  "version": "0.2.1",
+  "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"
   },