esque-bridge 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# esque-bridge
+
+Desktop-side receiver for the [Esque Agent](https://esque.app) iOS app. Pairs your phone with the local `claude` CLI so prompts you send from the app run through your **Claude Pro / Max subscription** rather than per-token API billing.
+
+## What it does
+
+1. Boots an Express server on localhost
+2. Opens a public localtunnel URL to that port
+3. Prints a QR code in your terminal embedding `esque://pair?url=…&secret=…`
+4. Accepts `POST /execute { prompt, sessionId }` (pairing-secret-gated)
+5. Runs each prompt through `claude --print --output-format json`
+6. Returns Claude's response to the phone, persisting the Claude session id so the next prompt continues the same conversation
+
+## Install
+
+You'll need:
+
+- **Node.js 18 or newer** — https://nodejs.org
+- **Claude Code CLI** logged into your Pro/Max account:
+  ```bash
+  npm install -g @anthropic-ai/claude-code
+  claude /login
+  ```
+
+Then either run via `npx` (no install) or globally:
+
+```bash
+npx esque-bridge                    # zero-install
+# — or —
+npm install -g esque-bridge
+esque-bridge
+```
+
+## Run
+
+```bash
+# from the directory you want Claude to edit:
+esque-bridge
+
+# point at a different repo without cd:
+esque-bridge --workdir ~/my-project
+
+# pick a non-default port:
+esque-bridge --port 4000
+```
+
+The terminal will print a QR code. Open the **Esque Agent** iOS app, tap **Pair Bridge**, and scan the code. That's it.
+
+## Flags
+
+| Flag          | Default      | Purpose                                   |
+| ------------- | ------------ | ----------------------------------------- |
+| `--port`      | `3030`       | Local HTTP port                           |
+| `--workdir`   | `$(pwd)`     | Directory Claude runs in                  |
+| `--bin`       | `claude`     | Path to the Claude CLI binary             |
+| `--timeout`   | `300000`     | Per-prompt timeout (ms)                   |
+| `--subdomain` | _(auto)_     | Stable localtunnel subdomain (optional)   |
+
+## Security notes
+
+- The pairing secret is regenerated every time the bridge starts and never persisted. If you stop and restart, you must re-pair the phone. This is deliberate — a leaked tunnel URL alone can't drive your Claude session.
+- The bridge accepts a no-auth `GET /` and `POST / {_probe: true}` for the Esque app's connection-test only. Every other request requires the secret in the `X-Esque-Pair` header.
+- `spawn(claude, [...args])` is used so the prompt body can never inject shell commands.
+
+## Troubleshooting
+
+**`'claude' not found in PATH`** — install the CLI: `npm install -g @anthropic-ai/claude-code`, then `claude /login` to authenticate.
+
+**`Failed to open localtunnel`** — your network is blocking localtunnel.me. Run cloudflared instead:
+```bash
+cloudflared tunnel --url http://localhost:3030
+```
+…and paste that URL into the Esque app manually (skip the QR).
+
+**Long prompts time out** — bump `--timeout 600000` (10 min).
+
+## Session continuity
+
+Each Esque conversation maps to a Claude session id. The map is persisted to `~/.esque-bridge-sessions.json` so restarting the bridge doesn't lose context. Delete that file to wipe history.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+/**
+ * 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:
+ *
+ *   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
+ *
+ * Run it:
+ *   npx esque-bridge                            # zero-config
+ *   esque-bridge --workdir ~/my-project         # point claude at a repo
+ */
+
+const express = require('express');
+const localtunnel = require('localtunnel');
+const qrcode = require('qrcode-terminal');
+const { spawn } = require('child_process');
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// --- Config ---------------------------------------------------------------
+
+const argv = parseArgs(process.argv.slice(2));
+
+if (argv.help || argv.h) {
+  console.log(
+    `
+Esque Bridge — pair your phone with your local Claude Code.
+
+USAGE
+  esque-bridge [--port 3030] [--workdir .] [--bin claude] [--timeout 300000]
+
+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)
+  --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
+
+OUTPUT
+  Prints a QR code in your terminal. Scan it from the Esque iOS app to
+  pair this laptop with your phone.
+    `.trim(),
+  );
+  process.exit(0);
+}
+
+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);
+const CLAUDE_BIN = argv.bin || process.env.CLAUDE_BIN || 'claude';
+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');
+
+function parseArgs(args) {
+  const out = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith('--') && !a.startsWith('-')) continue;
+    const key = a.replace(/^-+/, '');
+    const next = args[i + 1];
+    if (!next || next.startsWith('-')) {
+      out[key] = true;
+    } else {
+      out[key] = next;
+      i++;
+    }
+  }
+  return out;
+}
+
+// --- Session persistence -------------------------------------------------
+// Map of {esqueSessionId → claudeSessionId} so each conversation continues
+// in-context across prompts via `claude --resume`. Survives bridge restarts.
+
+let sessionMap = {};
+try {
+  sessionMap = JSON.parse(fs.readFileSync(SESSIONS_FILE, 'utf8'));
+} catch {
+  /* first run */
+}
+function saveSessions() {
+  try {
+    fs.writeFileSync(SESSIONS_FILE, JSON.stringify(sessionMap, null, 2));
+  } catch (err) {
+    console.warn('[bridge] could not persist session map:', err.message);
+  }
+}
+
+// --- Claude runner --------------------------------------------------------
+
+function runClaude(prompt, claudeSessionId) {
+  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, {
+      cwd: WORKDIR,
+      env: process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const settle = (fn) => (val) => {
+      if (settled) return;
+      settled = true;
+      fn(val);
+    };
+    const resolveOnce = settle(resolve);
+    const rejectOnce = settle(reject);
+
+    const killTimer = setTimeout(() => {
+      child.kill('SIGTERM');
+      rejectOnce(
+        new Error(`claude timed out after ${Math.round(TIMEOUT_MS / 1000)}s`),
+      );
+    }, TIMEOUT_MS);
+
+    child.stdout.on('data', (d) => (stdout += d));
+    child.stderr.on('data', (d) => (stderr += d));
+    child.on('error', (err) => {
+      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\`.`,
+          ),
+        );
+        return;
+      }
+      rejectOnce(err);
+    });
+    child.on('close', (code) => {
+      clearTimeout(killTimer);
+      if (code !== 0) {
+        rejectOnce(
+          new Error(
+            `claude 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,
+        });
+      }
+    });
+
+    child.stdin.write(prompt);
+    child.stdin.end();
+  });
+}
+
+// --- HTTP server ----------------------------------------------------------
+
+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.
+app.get('/', (_req, res) => {
+  res.json({
+    ok: true,
+    service: 'esque-bridge',
+    workdir: WORKDIR,
+    sessions: Object.keys(sessionMap).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).
+app.post('/', (req, res, next) => {
+  if (req.body && req.body._probe === true) {
+    return res.json({ ok: true, service: 'esque-bridge' });
+  }
+  return next();
+});
+
+function requireAuth(req, res, next) {
+  const provided = req.header('x-esque-pair') || req.body?.pairSecret;
+  if (provided !== PAIRING_SECRET) {
+    return res.status(401).json({
+      text:
+        'Unauthorized. Pair this bridge with your phone by scanning the QR code from the terminal where esque-bridge is running.',
+      status: 'blocked',
+    });
+  }
+  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 || '');
+  const esqueSessionId = body.sessionId ?? null;
+  if (!prompt.trim()) {
+    return res.status(400).json({ text: 'Empty prompt.', status: 'blocked' });
+  }
+
+  const claudeSid = esqueSessionId ? sessionMap[esqueSessionId] : null;
+  const preview = prompt.slice(0, 80).replace(/\s+/g, ' ');
+  console.log(
+    `[bridge] POST  ${preview}…  esque=${esqueSessionId ?? '-'}  claude=${claudeSid ?? 'new'}`,
+  );
+
+  try {
+    const result = await runClaude(prompt, claudeSid);
+    if (result.sessionId && esqueSessionId) {
+      sessionMap[esqueSessionId] = result.sessionId;
+      saveSessions();
+    }
+    res.json({
+      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' });
+  }
+}
+
+// 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 -----------------------------------------------------------------
+
+async function main() {
+  if (!fs.existsSync(WORKDIR) || !fs.statSync(WORKDIR).isDirectory()) {
+    console.error(`workdir does not exist: ${WORKDIR}`);
+    process.exit(1);
+  }
+
+  await new Promise((resolve) => app.listen(PORT, resolve));
+
+  let tunnel;
+  try {
+    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(`  cloudflared tunnel --url http://localhost:${PORT}`);
+    process.exit(1);
+  }
+
+  const pairUrl = `esque://pair?url=${encodeURIComponent(tunnel.url)}&secret=${PAIRING_SECRET}`;
+
+  console.log('');
+  console.log('━'.repeat(68));
+  console.log('  Esque Bridge Active');
+  console.log('━'.repeat(68));
+  console.log('');
+  console.log(
+    '  Scan this QR code with the Esque Agent mobile app to pair your device.',
+  );
+  console.log('');
+  qrcode.generate(pairUrl, { small: true });
+  console.log('');
+  console.log(`  Local        http://localhost:${PORT}`);
+  console.log(`  Tunnel       ${tunnel.url}`);
+  console.log(`  Workdir      ${WORKDIR}`);
+  console.log(`  Claude bin   ${CLAUDE_BIN}`);
+  console.log(
+    `  Pair secret  ${PAIRING_SECRET.slice(0, 8)}…  (rotates on restart — don't share)`,
+  );
+  console.log('');
+  console.log('  Press Ctrl-C to stop.');
+  console.log('━'.repeat(68));
+
+  const shutdown = (signal) => {
+    console.log(`\n  Received ${signal} — closing tunnel…`);
+    try {
+      tunnel.close();
+    } catch {
+      /* tunnel may already be closed */
+    }
+    process.exit(0);
+  };
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+
+  tunnel.on('close', () => {
+    console.error('\nTunnel closed unexpectedly. Restart `esque-bridge`.');
+    process.exit(1);
+  });
+}
+
+main().catch((err) => {
+  console.error('Fatal:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "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.",
+  "bin": {
+    "esque-bridge": "index.js"
+  },
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "esque",
+    "claude",
+    "claude-code",
+    "anthropic",
+    "agent",
+    "bridge",
+    "mobile",
+    "ios"
+  ],
+  "dependencies": {
+    "express": "^4.21.1",
+    "localtunnel": "^2.0.2",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "license": "MIT"
+}