nexting-cc-bridge 0.8.3

package/README.md

@@ -0,0 +1,252 @@
+# nexting-cc-bridge
+
+Runs on a user's Mac so their **phone mirrors and controls their Claude Code
+terminal sessions, two-way synced** — one model, no read-only/bubble split.
+
+**How it works (the "manager"):** your `claude` is wrapped by a thin shell that
+runs the real, official `claude` in a pseudo-terminal. Your terminal stays
+native; the shell also mirrors the session to your phone and injects what the
+phone types. A single background **hub** daemon owns the cloud connection and
+multiplexes every wrapped session, so you can run many `claude`s at once and the
+phone switches between them.
+
+**The one hard limit (OS):** a `claude` already running bare in a terminal can't
+be reached — macOS won't let an outside process inject into another process's tty.
+So only sessions started _through the manager_ are phone-controllable. The
+installer makes that invisible by putting a `claude` shim first on your PATH, so
+you keep typing `claude` and every new session is automatically controllable.
+
+Design: `docs/superpowers/specs/2026-06-07-cc-manager-unified-design.md` (current);
+earlier: `…2026-06-06-cc-shared-session-json-shell-design.md`, `…2026-06-04-…`.
+
+## Install (end users)
+
+In the Nexting app: **Claude Code → Connect**, which shows a one-line command
+(it embeds an account token, so no second login):
+
+```bash
+curl -fsSL https://nexting.ai/install-cc | NEXTING_CC_TOKEN=<token> bash
+```
+
+This binds the Mac to your account, installs the manager, puts the `claude` shim
+on PATH, and starts the hub daemon (launchd). Then just run `claude` as usual.
+
+- Bypass once: `NEXTING_CC_DISABLE=1 claude`
+- Remove everything: `nexting-cc-bridge uninstall`
+
+(No app token? `curl -fsSL https://nexting.ai/install-cc | bash` falls back to
+device-code browser auth.)
+
+### Region-locked egress (e.g. China)
+
+A phone send spawns a **fresh** headless `claude`/`codex` under the launchd
+daemon — it does NOT go through your terminal, so it doesn't inherit the
+`https_proxy` your terminal `claude` wrapper uses. If your region needs a proxy
+to reach Anthropic/OpenAI, that child exits direct and fails
+`403 Request not allowed` (while the terminal works). Worse, a different exit IP
+on the same account is an **account-ban** risk.
+
+Fix: set `engineEnv` so the bridge child exits from the **same** residential
+IP / timezone / locale as your terminal. If your shell rc defines `CLAUDE_PROXY`
+(or `CLAUDE_PROXY_{USER,PASS,HOST,PORT}`):
+
+```bash
+nexting-cc-bridge sync-proxy   # writes engineEnv to ~/.nexting/{cc,codex}-bridge.json
+launchctl kickstart -k gui/$(id -u)/ai.nexting.cc-bridge
+```
+
+Otherwise add an `engineEnv` object by hand to those config files. It **fails
+closed** (a dead proxy errors the request, never falls back to direct) and the
+daemon log prints `engine egress: PROXIED via … / DIRECT` so you can verify it.
+Re-run `sync-proxy` after rotating the proxy. US users need none of this.
+
+## How discovery works
+
+- Scans `~/.claude/projects/<encoded-cwd>/*.jsonl` — each JSONL is one session,
+  `mtime` = last active. (`encoded-cwd` = every non-alphanumeric char → `-`.)
+- Finds live sessions via `ps`, matching the CLI by argv0 basename `claude` (since
+  0.5.1 — covers npm, pnpm, and the native installer's `~/.local/bin/claude`; the
+  desktop app is excluded), deduped to **root** processes by PPID. Procs started
+  with `--session-id <uuid>` (every wrapper-run session) bind pid↔session
+  **exactly**; only bare procs without it fall back to the heuristic: `lsof` the
+  proc's cwd, then with N live procs in a project the N newest JSONLs **touched
+  within the last 30 minutes** are `running`, the rest `idle` (the freshness
+  bound keeps hours-old sessions from showing as running just because unrelated
+  procs exist in the same project); extra procs with no JSONL yet are virtual
+  `pending-<pid>`.
+- List rows read only head 16KB (title/cwd) + tail 128KB (recent messages). Full
+  transcript is read on demand when the phone opens a session.
+- Row title (since 0.4.1) = the session's **live recap**: the freshest
+  `{type:"system", subtype:"away_summary"}` entry Claude Code keeps appending to
+  the JSONL (tail window beats head). Falls back to `ai-title`, then the first
+  user message — slash-command wrappers render as `/name`, local-command caveats
+  are skipped. Codex sessions have no recap and keep their meta title.
+- Codex transcripts (since 0.5.1) parse `~/.codex/sessions/` rollout JSONL and
+  hide the bookkeeping the Codex TUI never renders — developer/system-role
+  instruction messages and user-role `<environment_context>` /
+  `<user_instructions>` / `<turn_aborted>` prefix messages — so the phone shows
+  exactly what Codex shows.
+- Live streaming (since 0.5.0): while a phone has a session open, the cloud
+  arms a watch (`cc_watch` / alias `cc_watch_start`) and the bridge **tails that
+  session's JSONL** (`transcript-watcher.ts` + `watch-manager.ts`), pushing new
+  entries as `cc_event{kind:"transcript_append", startIndex, …}` (idempotent by
+  absolute index) plus `watch_ok{entryCount}` reconciliation heartbeats, so
+  terminal-driven turns appear on the phone block-by-block instead of on the
+  next poll. Watches stop on `cc_unwatch` / `cc_watch_stop` or expire on their
+  own TTL; `watch_failed` tells the phone to fall back to polling.
+
+## Commands
+
+```bash
+# normal usage (set up by the installer; you don't run these by hand)
+nexting-cc-bridge install     # install the `claude` shim + PATH + start the hub (idempotent)
+nexting-cc-bridge uninstall   # remove shim + PATH entry + hub launchd (reversible)
+nexting-cc-bridge hub         # the background daemon: holds the cloud link, multiplexes all shells
+nexting-cc-bridge term -- ... # one wrapped `claude` that joins the hub (what the shim calls)
+
+# debug / legacy
+nexting-cc-bridge once        # print one discovery snapshot as JSON and exit
+nexting-cc-bridge start       # legacy read-only discovery daemon
+nexting-cc-bridge mirror      # legacy single-session mirror (one bridge per user)
+```
+
+**Architecture:** `hub` (one daemon, one cloud WS, listens on
+`~/.nexting/cc-hub.sock`) ← many `term` shells (each = one pty-wrapped `claude`,
+registers over the local socket). The hub multiplexes all shells to the cloud and
+routes phone input back to the right one by `termId`. A shell exiting (Ctrl-C /
+crash) sends `bye`, so the phone never sees a ghost terminal.
+
+## Local dev / end-to-end proof (no cloud needed)
+
+```bash
+npm install
+npm test                              # unit tests (122)
+node --import tsx src/dev-server.ts &  # cloud stand-in (ws://localhost:7799)
+NEXTING_CC_URL=ws://localhost:7799/cc-bridge/connect NEXTING_CC_TOKEN=dummy \
+  node --import tsx src/cli.ts start & # bridge against real ~/.claude/projects
+node --import tsx src/phone-probe.ts   # simulates the phone: lists + opens a transcript
+```
+
+## End-to-End Encryption
+
+The Pinclaw cloud acts as a **relay and store**, not the agent host. By default
+the cloud can see the session content it relays. E2E encryption is an **opt-in**
+feature (`e2eEnabled: true` in `~/.pinclaw/cc-bridge.json`) that makes the cloud
+a pure ciphertext forwarder: it sees routing metadata and opaque blobs but no
+plaintext content.
+
+### Trust model
+
+- **Trusted endpoints**: the Mac bridge and the user's phone.
+- **Untrusted**: the Pinclaw cloud server (treated as a relay that may be
+  compromised).
+- When E2E is on, only the endpoints can decrypt transcript text, titles,
+  summaries, and stream deltas.
+
+### What gets encrypted
+
+| Content                                                               | Encrypted when E2E on                                                                                                                                                |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Session titles (`cc_snapshot`)                                        | Yes                                                                                                                                                                  |
+| Session summaries (`cc_snapshot`)                                     | Yes                                                                                                                                                                  |
+| Recent message text (`cc_snapshot`)                                   | Yes                                                                                                                                                                  |
+| Transcript entries (`cc_event transcript_append`)                     | Yes                                                                                                                                                                  |
+| Streaming text and thinking deltas (`cc_event stream_*_delta`)        | Yes                                                                                                                                                                  |
+| Inbound user sends (`cc_send content`)                                | Yes                                                                                                                                                                  |
+| Inbound question answers (`cc_answer updatedInput`)                   | Yes                                                                                                                                                                  |
+| Media/image bytes                                                     | Yes — `src/media-hydrator.ts` encrypts blob bytes with `sealBytes` (session CEK) before upload and marks them `encrypted: true`; the phone decrypts with `openBytes` |
+| Terminal mirror frames (`cc_term_output`, `cc_term_input`)            | No — these are already opaque binary blobs; the content stream above is where the readable text lives                                                                |
+| Control / handshake frames (`reg`, `cc_hello`, `cc_term_hello`, etc.) | No                                                                                                                                                                   |
+
+### Cryptographic details (auditable)
+
+All algorithms are in `src/e2e/crypto.ts` (Node built-in `node:crypto` only —
+no third-party crypto libraries).
+
+**Content encryption** (per session, text fields):
+
+- **Algorithm**: AES-256-GCM
+- **Per-session key**: 32-byte Content Encryption Key (CEK), one per session,
+  generated fresh by the bridge at session creation.
+- **Wire envelope**: `e2e:v1:<base64(nonce[12] || ciphertext || tag[16])>`
+- **AAD** (authenticated additional data): `"<sessionId>|0|<field>"` — binds
+  every ciphertext to its session and field, preventing cross-session replay.
+  The `0` is the sequence placeholder (current protocol has no per-frame
+  sequence number). Field tags are: `title`, `summary`, `msg`, `text`, `delta`,
+  `send`, `answer`.
+
+**Media encryption** (binary):
+
+- **Algorithm**: AES-256-GCM (same `sealBytes` / `openBytes` helpers).
+- **Wire layout**: raw bytes — `nonce[12] || ciphertext || tag[16]` (no text
+  prefix; an `encrypted: true` metadata flag marks the blob).
+- **AAD**: `"<sessionId>|0|media"`
+
+**Key wrapping** (CEK delivery to the phone):
+
+- **Algorithm**: ephemeral X25519 ECDH → HKDF-SHA256 → AES-256-GCM
+- **Derivation**: `HKDF-SHA256(ikm=X25519_shared, salt=UTF8(sessionId), info=UTF8("pinclaw-e2e-cek-wrap"), L=32)`
+- **Wire format**: `wrap:v1:<base64(ephPubSPKI[44] || nonce[12] || ct || tag[16])>`
+- The bridge generates an ephemeral X25519 keypair per wrap, computes the
+  shared secret with the recipient device's long-term public key, derives a
+  per-wrap AES-256-GCM key, and seals the CEK. The recipient (phone) reverses
+  the process.
+
+**Device identity key**:
+
+- Each endpoint (Mac bridge, phone) has an X25519 long-term keypair.
+- The bridge private key is stored in the **macOS Keychain** (service
+  `pinclaw-bridge-e2e`, written via `security add-generic-password`); it never
+  leaves the machine. See `src/e2e/keychain-identity.ts`.
+- Public keys are published to the cloud key directory so endpoints can
+  fetch each other's keys for wrapping.
+
+**Safety number** (human-verifiable MITM protection):
+
+- `SHA-256(sort(pubA, pubB))` — the first 10 bytes encoded in base32
+  (`A-Z2-7`), displayed as `XXXXX-XXXXX`.
+- Compare this five-plus-five string between your Mac terminal and the Pinclaw
+  app. If they match, no cloud-side key swap has occurred.
+
+### What you can verify
+
+1. **Algorithms**: read `src/e2e/crypto.ts` — every cipher call is there.
+   Node's built-in `node:crypto` module, no opaque libraries.
+2. **Which fields are sealed/unsealed**: read `src/e2e/codec.ts`
+   (`EnvelopeCodec.encryptOutbound` / `decryptInbound`). The switch cases
+   enumerate every frame type that the codec touches.
+3. **Key storage**: read `src/e2e/keychain-identity.ts` — the only I/O is
+   `security find-generic-password` (read) and `security add-generic-password`
+   (write) to the macOS login keychain.
+4. **Tests and interop vectors**: `test/e2e-crypto.test.ts`,
+   `test/e2e-codec.test.ts`, `test/e2e-wire.test.ts` — the vectors in
+   `e2e-crypto.test.ts` are the shared ground truth used to verify byte-level
+   compatibility between the bridge, cloud, iOS, and Android.
+
+To run just the E2E tests:
+
+```bash
+npm test -- --testPathPattern="e2e-"
+```
+
+---
+
+## Wire protocols
+
+**Terminal mirror — hub ⇄ cloud** (the current model):
+Hub → cloud: `cc_term_hello {termId,cwd,title,cols,rows}`, `cc_term_output
+{termId,data(b64)}`, `cc_term_bye {termId}`. Cloud → hub: `cc_term_input
+{termId,data}`, `cc_term_resize {termId,cols,rows}`.
+
+**Shell ⇄ hub (local socket, newline-JSON, `hub-protocol.ts`):**
+shell → hub `reg` / `out` / `bye`; hub → shell `in` / `resize`.
+
+**Phone ⇄ cloud (`routes/cc.ts`):** `GET /cc/term/list`, `GET /cc/term/stream`
+(SSE bytes, replays the rolling buffer then live), `POST /cc/term/input`, `POST
+/cc/term/resize`, and `POST /cc/pair` (logged-in phone mints an account-bound
+install token). Cloud relay: `services/cc-term-service.ts` (per-term rolling
+256KB buffer, replay-then-live, drops on bye).
+
+Legacy (bubble/discovery, still present): `cc_hello`/`cc_snapshot`/`cc_event` +
+`/cc/sessions|attach|send|stream`; migrations `049_claude_code_mode.sql` +
+`050_cc_sessions_controllable.sql`. The unified iOS UI uses the terminal path only.

package/dist/attach-manager.js

@@ -0,0 +1,259 @@
+// Owns the set of attached sessions. Reacts to phone→bridge frames
+// (cc_attach / cc_send / cc_answer / cc_detach), manages one SessionRunner per
+// session, and forwards each child frame upward as a cc_* envelope (+ sessionId).
+import { createSessionRunner, } from "./session-runner.js";
+export function createAttachManager(deps) {
+    const runners = new Map();
+    const owned = new Set(); // session ids owned by the local terminal shell
+    // Runners we are killing ON PURPOSE (detach / shutdown / WS-disconnect
+    // cleanup): their exit must NOT be reported as a session death.
+    const stopping = new WeakSet();
+    function stopRunner(r) {
+        stopping.add(r);
+        r.stop();
+    }
+    function forward(sessionId, frame) {
+        if (frame.type === "event") {
+            deps.send({
+                type: "cc_event",
+                sessionId,
+                kind: frame.kind,
+                payload: frame.payload,
+            });
+        }
+        else if (frame.type === "control_request") {
+            deps.send({
+                type: "cc_control_request",
+                sessionId,
+                controlRequestId: frame.controlRequestId,
+                toolName: frame.toolName,
+                input: frame.input,
+            });
+        }
+        else {
+            deps.send({
+                type: "cc_control_cancel",
+                sessionId,
+                controlRequestId: frame.controlRequestId,
+            });
+        }
+    }
+    // A runner's forwarding id is mutable: a brand-new session is created under
+    // "new" and re-keyed to its real id once system_init arrives (see rekey).
+    const idBox = new WeakMap();
+    function rekey(oldId, newId) {
+        if (oldId === newId)
+            return;
+        const r = runners.get(oldId);
+        if (r) {
+            runners.delete(oldId);
+            runners.set(newId, r);
+            const box = idBox.get(r);
+            if (box)
+                box.current = newId;
+        }
+        if (owned.delete(oldId))
+            owned.add(newId);
+    }
+    function makeRunner(sessionId, cwd) {
+        const isNew = sessionId === "new";
+        const box = { current: sessionId };
+        const engineName = deps.engine === "codex" ? "Codex" : "Claude Code";
+        const canonicalCwd = cwd;
+        const runner = createSessionRunner({
+            sessionId,
+            cwd: canonicalCwd,
+            resumeSessionId: isNew ? undefined : sessionId,
+            spawn: deps.spawn,
+            command: deps.command,
+            adapter: deps.adapterFactory?.(),
+            // Inject the device-tool MCP proxy when the bridge has cloud wiring. The
+            // file/block key is the spawn sessionId (stable across the "new"→real
+            // rekey); the route id starts equal and is updated on rekey below.
+            mcp: deps.mcp
+                ? {
+                    engine: deps.engine === "codex" ? "codex" : "claude",
+                    sessionId,
+                    cloudUrl: deps.mcp.cloudUrl,
+                    busToken: deps.mcp.busToken,
+                }
+                : undefined,
+            onFrame: (frame) => {
+                forward(box.current, frame);
+                // A phone-created session reports its real id in system_init. The frame
+                // itself just went out under "new" — that's how the phone learns the
+                // mapping — then the runner re-keys so every later frame (and send)
+                // rides the real id. Local-shell does its own rekey too; it's idempotent.
+                if (box.current === "new" &&
+                    frame.type === "event" &&
+                    frame.kind === "system_init") {
+                    const real = frame.payload
+                        ?.session_id;
+                    if (typeof real === "string" && real) {
+                        rekey("new", real);
+                        // Re-point the device-tool MCP proxy at the real session id so its
+                        // calls reach the phone's SSE subscription (which moves to the real
+                        // id after system_init). Config file path stays stable; only the
+                        // routed NEXTING_SESSION_ID changes.
+                        runner.rewriteMcpRoute(real);
+                    }
+                }
+            },
+            onError: (err) => {
+                // Spawn failure (e.g. `claude` not on PATH → ENOENT). Tell the phone and
+                // forget the runner; never let it bubble up and crash the bridge.
+                deps.send({
+                    type: "cc_event",
+                    sessionId: box.current,
+                    kind: "result_error",
+                    payload: {
+                        errors: [`无法启动 ${engineName} 会话进程：${err.message}`],
+                    },
+                });
+                runners.delete(box.current);
+                owned.delete(box.current);
+            },
+            onExit: (code, signal) => {
+                // EVERY unexpected exit gets reported — not just non-zero codes. A
+                // clean exit (code 0) and a signal kill (code null) used to be silent,
+                // leaving the phone spinning "working" on a process that no longer
+                // exists. Only intentional stops (detach/shutdown/reconnect cleanup)
+                // stay quiet.
+                if (!stopping.has(runner)) {
+                    const msg = code && code !== 0
+                        ? `会话进程意外退出（code ${code}）。`
+                        : signal
+                            ? `会话进程被终止（${signal}）。发送消息会自动重启会话。`
+                            : `会话进程已退出。发送消息会自动重启会话。`;
+                    deps.send({
+                        type: "cc_event",
+                        sessionId: box.current,
+                        kind: "result_error",
+                        payload: { errors: [msg] },
+                    });
+                }
+                runners.delete(box.current);
+                owned.delete(box.current);
+            },
+        });
+        runners.set(sessionId, runner);
+        idBox.set(runner, box);
+        return runner;
+    }
+    function attach(sessionId, cwd) {
+        if (runners.has(sessionId)) {
+            // Already attached (incl. local shell) — reuse.
+            return;
+        }
+        makeRunner(sessionId, cwd);
+    }
+    return {
+        handle: (msg) => {
+            switch (msg.type) {
+                case "cc_attach":
+                    attach(msg.sessionId, msg.cwd);
+                    break;
+                case "cc_send": {
+                    const m = msg;
+                    const r = runners.get(m.sessionId);
+                    if (!r) {
+                        // No live runner: report instead of silently dropping, so the phone
+                        // clears its "working" state and shows a real error.
+                        deps.send({
+                            type: "cc_event",
+                            sessionId: m.sessionId,
+                            kind: "result_error",
+                            payload: {
+                                errors: [
+                                    "该会话在这台 Mac 上没有在运行的会话进程（未附加）。请重新打开该会话后再发。",
+                                ],
+                            },
+                        });
+                        break;
+                    }
+                    r.send(m.content);
+                    break;
+                }
+                case "cc_answer": {
+                    const m = msg;
+                    runners.get(m.sessionId)?.answer(m.controlRequestId, m.updatedInput);
+                    break;
+                }
+                case "cc_deny": {
+                    const m = msg;
+                    runners.get(m.sessionId)?.deny(m.controlRequestId, m.message);
+                    break;
+                }
+                case "cc_detach": {
+                    const m = msg;
+                    // A locally-owned (terminal shell) runner must survive a remote detach:
+                    // the phone leaving doesn't end the session the user is driving locally.
+                    if (owned.has(m.sessionId))
+                        break;
+                    const r = runners.get(m.sessionId);
+                    if (r)
+                        stopRunner(r);
+                    runners.delete(m.sessionId);
+                    break;
+                }
+                case "codex_queue_edit": {
+                    const m = msg;
+                    runners.get(m.sessionId)?.editQueuedTurn(m.itemId, m.content);
+                    break;
+                }
+                case "codex_queue_delete": {
+                    const m = msg;
+                    runners.get(m.sessionId)?.deleteQueuedTurn(m.itemId);
+                    break;
+                }
+                case "codex_queue_close": {
+                    const m = msg;
+                    runners.get(m.sessionId)?.closeQueue();
+                    break;
+                }
+                case "codex_queue_steer": {
+                    const m = msg;
+                    runners.get(m.sessionId)?.steerQueuedTurn(m.itemId);
+                    break;
+                }
+                // unknown frames: ignore
+            }
+        },
+        stopAll: () => {
+            for (const r of runners.values())
+                stopRunner(r);
+            runners.clear();
+            owned.clear();
+        },
+        stopRemote: () => {
+            for (const [id, r] of runners) {
+                if (owned.has(id))
+                    continue; // keep the local shell alive across reconnects
+                // Intentional kill on a DEAD socket — a frame couldn't reach the cloud
+                // anyway; the cloud's bridge_offline broadcast informs the phones.
+                stopRunner(r);
+                runners.delete(id);
+            }
+        },
+        attachLocal: ({ sessionId, cwd }) => {
+            const r = runners.get(sessionId) ?? makeRunner(sessionId, cwd);
+            owned.add(sessionId);
+            return r;
+        },
+        rekey: (oldId, newId) => {
+            if (oldId === newId)
+                return;
+            const r = runners.get(oldId);
+            if (r) {
+                runners.delete(oldId);
+                runners.set(newId, r);
+                const box = idBox.get(r);
+                if (box)
+                    box.current = newId;
+            }
+            if (owned.delete(oldId))
+                owned.add(newId);
+        },
+        controllableIds: () => [...owned],
+    };
+}