uxnan-bridge 0.0.1-alpha.20260621

package/README.md

@@ -0,0 +1,150 @@
+# uxnan-bridge
+
+Local control-plane daemon that connects the Uxnan mobile app to the developer's
+PC over an end-to-end-encrypted channel. It runs Git, reads the workspace, and
+drives AI coding agents on behalf of the phone, routing JSON-RPC methods to
+per-domain handlers.
+
+> **Status: ALPHA-FUNCTIONAL on the primary path (LAN/Tailscale-direct, bridge-
+> direct push).** The bridge is the **heart of the product** — the product is
+> bridge-first: the mobile app pairs with the bridge and tries direct LAN/
+> Tailscale addresses first; the relay is an optional, self-hosted off-LAN
+> fallback. Background push is sent **by the bridge** (FCM HTTP v1) over any
+> transport, so the phone keeps getting notifications whether the bridge is
+> reached via direct LAN, Tailscale, or relay.
+>
+> **DONE:**
+> - **E2EE transport** (relay `mac` client + direct-LAN `http+ws` server,
+>   handshake, AES-256-GCM channel, byte-for-byte compatible with the mobile
+>   app; background reconnect loop; stable pairing session; mDNS discovery
+>   `_uxnan._tcp.local`; manual-code pairing `GET /pair/resolve?code=`).
+> - **OS-keychain identity persistence** + single-instance lock.
+> - **Real Git + Workspace handlers** (path-traversal-safe, working-tree
+>   checkpoints with **true restore** + retention pruning, `git/revert`,
+>   `git/deleteBranch`, `git/removeWorktree`, `workspace/exists`,
+>   `workspace/browseDirs`).
+> - **Conversation engine** (threads/turns + streaming, per-thread
+>   `Message.blocks`/`Message.thinking`/`Message.usage`).
+> - **5 real agents wired:** OpenCode (default), Claude Code, Codex, pi, and
+>   **Gemini CLI**. Each spawns its **official local CLI** over stdio with
+>   `shell:false`, parses the native stream, and emits structured
+>   `stream/content/block` events (command / diff / tool) plus
+>   `stream/thinking/delta` (reasoning). **Aider** is the only remaining
+>   agent (recipe in [`FOR-DEV.md`](FOR-DEV.md)).
+> - **Per-thread agent/project selection** + per-project agent/model pins
+>   (`projectAgents` config); per-model run-option knobs advertised on
+>   `agent/models`; per-turn token usage on `stream/turn/completed`.
+> - **Full thread lifecycle** (`thread/rename|archive|unarchive|delete`).
+> - **Plug-and-play folder browsing** (`workspace/browseDirs`) with
+>   `browseRoots` config.
+> - **Direct FCM push from the bridge** (primary path, persisted across
+>   restarts, per-phone target, prune-on-untrust). `firebase-admin` is an
+>   `optionalDependency` — no creds = silent no-op, foreground local
+>   notifications still work.
+> - **Sanitized per-agent `auth/status`** (never tokens, login detected by
+>   auth-file existence only).
+> - **Interactive approval intake** (Echo demo + Claude Code opt-in
+>   `PreToolUse` hook + Codex via the `codex app-server` turn protocol
+>   — `applyPatchApproval` / `execCommandApproval` elicitations routed
+>   through the same `requestApproval` round-trip; all validated
+>   end-to-end).
+> - **Image attachments** (CLI-agnostic file-path, sandbox-safe).
+> - **On-disk `turn/list` history fallback** for Claude/Codex/OpenCode/pi/Gemini
+>   JSONL/JSON stores.
+> - **Bridge control:** `bridge/status` (real `relayConnected`),
+>   `bridge/removeTrustedDevice` (revokes + drops session + prunes push
+>   registration), `bridge/trustedDevices`, `bridge/connectedPhones`,
+>   `bridge/generatePairingQr`.
+> - **Autostart** (`install-service`/`uninstall-service` per platform,
+>   never elevated), file logging with secret redaction, CLI
+>   (`start`/`stop`/`status`/`qr`/`code`/`install-service`).
+>
+> **PENDING that matters for a public release (not LAN alpha):** Aider
+> adapter, packaging + `npm publish` (pin `@uxnan/shared`), real-device push
+> validation. **Optional / blocked-on-mobile:** seq catch-up + key rotation
+> (await a mobile trigger), desktop embedded IPC (desktop Phase 6), Aider in
+> the history reader (no per-session log shipped), log size-rotation. See
+> [`FOR-DEV.md`](./FOR-DEV.md).
+>
+> **How the bridge talks to agents:** it spawns each agent's **official local
+> CLI** (`opencode`, `claude`, `codex`, `pi`, `gemini`) as a child process
+> and drives it over stdio — exactly as you would in a terminal. It does
+> **not** use any provider HTTP API, API key, or language SDK; each CLI runs
+> under the account/subscription you already authenticated it with. Prompts
+> are passed as argv elements with `shell:false` (no shell injection). See
+> [`FOR-HUMAN.md`](./FOR-HUMAN.md) for the per-agent install/login
+> prerequisites.
+
+## Docs
+
+Detailed docs live in [`docs/`](./docs/):
+[installation & autostart](./docs/installation.md) ·
+[configuration](./docs/configuration.md) ·
+[connectivity (LAN/Tailscale/relay)](./docs/connectivity.md) ·
+[how agents are driven](./docs/agents.md) ·
+[testing](./docs/testing.md) ·
+[packaging & deploy](./docs/deploy.md) ·
+[push notifications](./docs/push-notifications.md).
+
+## Install (later, as a global package)
+
+```bash
+npm install -g uxnan-bridge
+```
+
+## CLI
+
+```bash
+uxnan-bridge start            # start the daemon: LAN server + (optional) relay pairing session
+uxnan-bridge status           # print current status as JSON
+uxnan-bridge qr               # print the pairing QR in the terminal (with the manual code)
+uxnan-bridge code             # print just the current pairing code
+uxnan-bridge stop             # stop the running daemon (via the lock file)
+uxnan-bridge install-service  # autostart at logon (Task Scheduler / LaunchAgent / systemd --user)
+uxnan-bridge uninstall-service
+```
+
+Logs are written to `~/.uxnan/logs/bridge-YYYY-MM-DD.log` (daily rotation, with a
+secret-redaction pass) and to stderr. Autostart at login is configured by the
+platform scripts under `scripts/`.
+
+The Ed25519 identity is stored in the OS keychain (Windows Credential Manager /
+macOS Keychain / Linux Secret Service) via `@napi-rs/keyring`. If no keychain
+is available the bridge still runs with an in-memory identity (not persisted
+across restarts).
+
+## Architecture
+
+- **Contracts:** consumes [`@uxnan/shared`](../shared) for JSON-RPC and E2EE
+  types and runtime validators. The bridge exposes **59 JSON-RPC methods +
+  8 streaming notifications** (see `shared/src/jsonrpc/`). The mobile app
+  keeps manually-synced Dart equivalents of the same shapes.
+- **State:** non-secret JSON under `~/.uxnan/` (atomic writes): `daemon-config.json`,
+  `pairing-session.json`, `threads.json`, `trusted-phones.json`,
+  `push-state.json`, `agent-cache/`, `logs/`. The Ed25519 identity is a
+  secret and is kept in a `SecretStore`, never written in plaintext.
+- **Routing:** `HandlerRouter.dispatchRaw()` validates the envelope and
+  routes to registered handlers; errors map to JSON-RPC error codes
+  (`-32000..-32008` + standard).
+- **Agents:** `IAgentAdapter` per agent (OpenCode / Claude Code / Codex /
+  pi / Gemini CLI); `AgentManager` orchestrates streaming and broadcasts
+  `stream/*` notifications to connected phones.
+- **Push:** `PushService` (persisted by relay `sessionId`) delivers FCM
+  HTTP v1 directly via `createBridgePushSender` (lazy `firebase-admin`),
+  with the relay `/push/notify` as a fallback.
+
+See `architecture/02a-system-architecture.md` §5.8 and
+`uxnandesktop/architecture/02e-bridge-integration.md`.
+
+## Develop
+
+```bash
+# from the repo root (workspaces):
+npm run build      # build @uxnan/shared then uxnan-bridge
+npm test           # build + run all node:test suites (263 bridge + 29 shared + 9 relay)
+npm run typecheck  # tsc --noEmit across packages
+npm run format     # prettier --write
+```
+
+Requires Node ≥18. ESM-only. Test runner uses `--test-concurrency=1` on
+Windows (see CHANGELOG for why).

package/dist/src/account-status.d.ts

@@ -0,0 +1,13 @@
+import type { AgentId, AuthStatus } from '@uxnan/shared';
+export interface AccountStatusDeps {
+    /** Whether the agent's binary resolved (from the AgentManager). */
+    isAvailable(agentId: AgentId): boolean;
+    /** Injectable home dir (defaults to the OS home) — for tests. */
+    homeDir?: string;
+    /** Injectable existence check (defaults to fs `access`) — for tests. */
+    fileExists?: (path: string) => Promise<boolean>;
+    /** Injectable platform (defaults to `process.platform`) — for tests. */
+    platform?: NodeJS.Platform | string;
+}
+/** Build the sanitized {@link AuthStatus} for one agent. */
+export declare function getAuthStatus(agentId: AgentId, deps: AccountStatusDeps): Promise<AuthStatus>;

package/dist/src/account-status.js

@@ -0,0 +1,78 @@
+/**
+ * Sanitized account/auth status per agent (architecture/02a §5.8.9).
+ *
+ * Reports whether an agent's CLI looks logged in on this PC WITHOUT ever reading
+ * or exposing tokens/keys: detection is by **existence only** of each agent's
+ * well-known auth file (never its contents), and the response carries only the
+ * agent id, booleans, the public provider name, the transport mode and the OS
+ * platform. There is intentionally no `displayName` — deriving it would mean
+ * reading an account/credentials file, which may hold secrets.
+ *
+ * Heuristic, not authoritative: an installed-but-logged-out CLI whose auth file
+ * is absent reports `requiresLogin: true`; an agent we have no auth-file mapping
+ * for falls back to its binary availability. FOR-DEV: for an authoritative
+ * answer, run the agent CLI's own auth/whoami command (out of MVP scope — it is
+ * slower and per-CLI).
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { access } from 'node:fs/promises';
+/** Public provider name surfaced per agent (never a secret). */
+const PROVIDER_BY_AGENT = {
+    codex: 'openai',
+    'claude-code': 'anthropic',
+    opencode: 'opencode',
+};
+/**
+ * Auth-presence files per agent, relative to the user's home. EXISTENCE is the
+ * only signal read — contents (which hold the token) are never opened. Multiple
+ * candidates cover platform/version differences; the first that exists wins.
+ */
+const AUTH_FILES = {
+    codex: ['.codex/auth.json'],
+    'claude-code': ['.claude/.credentials.json', '.claude.json'],
+    opencode: ['.local/share/opencode/auth.json', '.config/opencode/auth.json'],
+    // pi stores per-provider credentials (OAuth/API keys) in one auth file; its
+    // existence means at least one provider is logged in. pi is multi-provider, so
+    // no single public provider name is surfaced.
+    'pi-agent': ['.pi/agent/auth.json'],
+};
+async function defaultExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Build the sanitized {@link AuthStatus} for one agent. */
+export async function getAuthStatus(agentId, deps) {
+    const available = deps.isAvailable(agentId);
+    const provider = PROVIDER_BY_AGENT[agentId];
+    const authFiles = AUTH_FILES[agentId] ?? [];
+    let authenticated = false;
+    if (available && authFiles.length > 0) {
+        const home = deps.homeDir ?? homedir();
+        const exists = deps.fileExists ?? defaultExists;
+        for (const relative of authFiles) {
+            if (await exists(join(home, relative))) {
+                authenticated = true;
+                break;
+            }
+        }
+    }
+    // No binary → must be set up on the PC. Binary present with an auth-file
+    // mapping → trust the existence check. Binary present without a mapping →
+    // assume usable (we can't cheaply tell, and blocking would be wrong).
+    const requiresLogin = available ? (authFiles.length > 0 ? !authenticated : false) : true;
+    return {
+        agentId,
+        requiresLogin,
+        loginInProgress: false,
+        ...(provider !== undefined && authenticated ? { authenticatedProvider: provider } : {}),
+        transportMode: 'local',
+        platform: deps.platform ?? process.platform,
+    };
+}
+//# sourceMappingURL=account-status.js.map

package/dist/src/account-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-status.js","sourceRoot":"","sources":["../../src/account-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG1C,gEAAgE;AAChE,MAAM,iBAAiB,GAAqC;IAC1D,KAAK,EAAE,QAAQ;IACf,aAAa,EAAE,WAAW;IAC1B,QAAQ,EAAE,UAAU;CACrB,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,GAAuC;IACrD,KAAK,EAAE,CAAC,kBAAkB,CAAC;IAC3B,aAAa,EAAE,CAAC,2BAA2B,EAAE,cAAc,CAAC;IAC5D,QAAQ,EAAE,CAAC,iCAAiC,EAAE,4BAA4B,CAAC;IAC3E,4EAA4E;IAC5E,+EAA+E;IAC/E,8CAA8C;IAC9C,UAAU,EAAE,CAAC,qBAAqB,CAAC;CACpC,CAAC;AAaF,KAAK,UAAU,aAAa,CAAC,IAAY;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAgB,EAChB,IAAuB;IAEvB,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAE5C,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,IAAI,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,EAAE,CAAC;QACvC,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,IAAI,aAAa,CAAC;QAChD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,IAAI,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;gBACvC,aAAa,GAAG,IAAI,CAAC;gBACrB,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,0EAA0E;IAC1E,sEAAsE;IACtE,MAAM,aAAa,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEzF,OAAO;QACL,OAAO;QACP,aAAa;QACb,eAAe,EAAE,KAAK;QACtB,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,aAAa,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvF,aAAa,EAAE,OAAO;QACtB,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ;KAC5C,CAAC;AACJ,CAAC"}

package/dist/src/adapters/base-adapter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Base class for agent CLI adapters: event fan-out plus the {@link IAgentAdapter}
+ * surface. Concrete adapters implement the lifecycle and turn methods.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.2 (adapters/base-adapter).
+ */
+import type { AgentCapabilities, AgentConfig, AgentId, AgentStreamEvent, IAgentAdapter, SendTurnOptions } from '@uxnan/shared';
+export declare abstract class BaseAgentAdapter implements IAgentAdapter {
+    #private;
+    abstract readonly agentId: AgentId;
+    abstract readonly capabilities: AgentCapabilities;
+    onEvent(listener: (event: AgentStreamEvent) => void): () => void;
+    protected emit(event: AgentStreamEvent): void;
+    abstract start(config: AgentConfig): Promise<void>;
+    abstract stop(): Promise<void>;
+    abstract sendTurn(options: SendTurnOptions): Promise<void>;
+    abstract cancelTurn(threadId: string, turnId: string): Promise<void>;
+}

package/dist/src/adapters/base-adapter.js

@@ -0,0 +1,15 @@
+export class BaseAgentAdapter {
+    #listeners = new Set();
+    onEvent(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    emit(event) {
+        for (const listener of this.#listeners) {
+            listener(event);
+        }
+    }
+}
+//# sourceMappingURL=base-adapter.js.map

package/dist/src/adapters/base-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-adapter.js","sourceRoot":"","sources":["../../../src/adapters/base-adapter.ts"],"names":[],"mappings":"AAeA,MAAM,OAAgB,gBAAgB;IAI3B,UAAU,GAAG,IAAI,GAAG,EAAqC,CAAC;IAEnE,OAAO,CAAC,QAA2C;QACjD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACnC,CAAC,CAAC;IACJ,CAAC;IAES,IAAI,CAAC,KAAuB;QACpC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACvC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CAMF"}

package/dist/src/adapters/claude-adapter.d.ts

@@ -0,0 +1,102 @@
+import type { AgentCapabilities, AgentConfig, AgentId, AgentModel, SendTurnOptions } from '@uxnan/shared';
+import { BaseAgentAdapter } from './base-adapter.js';
+import { type ClaudeToolResult, type ClaudeToolUse } from './claude-tools.js';
+import { type SpawnFn } from './spawn.js';
+/**
+ * Headless permission posture passed to the CLI:
+ *  - `default`           → no flag (tools needing approval are auto-denied headless);
+ *  - `acceptEdits`       → `--permission-mode acceptEdits` (file edits auto-apply);
+ *  - `bypassPermissions` → `--dangerously-skip-permissions` (all tools run).
+ */
+export type ClaudePermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions';
+/** An explicit, concrete model to add to the picker beyond the stable aliases. */
+export interface ClaudeModelSpec {
+    /** Exact model id passed to `--model` (e.g. `claude-opus-4-8`). */
+    id: string;
+    /** Human-facing label (defaults to `id`). */
+    displayName?: string;
+    /** Optional one-line description. */
+    description?: string;
+}
+export interface ClaudeCodeAdapterOptions {
+    /** Executable to spawn (resolved path; see resolve-claude.ts). */
+    binaryPath?: string;
+    /** Args prepended before the adapter args (e.g. `[cli.js]` when running via node). */
+    prependArgs?: string[];
+    /** Default model (`alias` or full id) when the thread/turn doesn't pick one. */
+    defaultModel?: string;
+    /**
+     * Concrete, versioned models to surface in the picker **in addition** to the
+     * stable `opus`/`sonnet`/`haiku` aliases — declared in daemon config
+     * (`agents.claude-code.models`). Lets users pick an exact/older version while
+     * the aliases keep tracking "latest". Deduplicated against the aliases by id.
+     */
+    pinnedModels?: ClaudeModelSpec[];
+    /** Headless permission posture (default `acceptEdits`). */
+    permissionMode?: ClaudePermissionMode;
+    /**
+     * Opt-in interactive approvals: inject a `PreToolUse` hook (via `--settings`)
+     * so every tool round-trips to the bridge for the user's approval. Requires
+     * {@link approvalHook} to be set and resolvable (the bridge's local endpoint).
+     */
+    interactiveApprovals?: boolean;
+    /**
+     * The local approval-hook endpoint + token + the path to the shipped hook
+     * script. `url()` is lazy because the LAN port is known only after the server
+     * starts; it returns `undefined` until then (the turn runs without the hook).
+     */
+    approvalHook?: {
+        token: string;
+        scriptPath: string;
+        url: () => string | undefined;
+    };
+    /** Injected spawn function for the one-shot path (tests). */
+    spawnFn?: SpawnFn;
+}
+/** A normalized Claude Code event extracted from one stream-json line. */
+export interface ClaudeEvent {
+    kind: 'init' | 'delta' | 'thinking' | 'assistant_text' | 'tool_result' | 'result' | 'other';
+    sessionId?: string;
+    text?: string;
+    /** Only set for `init`: the concrete model id the run resolved the alias to. */
+    model?: string;
+    /** Only set for `result`: whether the turn ended in error. */
+    isError?: boolean;
+    /** Only set for `result`: the raw `usage` object (token counts), if present. */
+    usage?: unknown;
+    /** Only set for `assistant_text`: any tool invocations in the message. */
+    toolUses?: ClaudeToolUse[];
+    /** Only set for `tool_result`: results the agent fed back from its tools. */
+    toolResults?: ClaudeToolResult[];
+}
+/**
+ * Context-window size (tokens) for a Claude model id or alias, so the phone can
+ * show context usage as a percentage. Fable/Opus/Sonnet are 1M, Haiku is 200K
+ * (matches the current model catalog); unknown ids return undefined.
+ */
+export declare function claudeContextWindow(model: string | undefined): number | undefined;
+/** Sum the context-occupying token counts from a Claude `result.usage` object. */
+export declare function claudeUsageTokens(usage: unknown): number | undefined;
+/** Parse one `claude … --output-format stream-json` line, or null if it isn't JSON. */
+export declare function parseClaudeLine(line: string): ClaudeEvent | null;
+export declare class ClaudeCodeAdapter extends BaseAgentAdapter {
+    #private;
+    readonly agentId: AgentId;
+    readonly capabilities: AgentCapabilities;
+    /** Native Claude session id for a thread (on-disk history-fallback locator). */
+    nativeSessionId(threadId: string): string | undefined;
+    constructor(options?: ClaudeCodeAdapterOptions);
+    get defaultModel(): string | undefined;
+    start(config: AgentConfig): Promise<void>;
+    stop(): Promise<void>;
+    sendTurn(options: SendTurnOptions): Promise<void>;
+    cancelTurn(threadId: string, turnId: string): Promise<void>;
+    /**
+     * Claude Code has no model-list command. Expose the stable `--model` aliases
+     * (each tracks the latest model of its tier the account can use — the concrete
+     * version is reported per-run via the `model_resolved` event), followed by any
+     * concrete versions pinned in config. Pinned ids that collide with an alias
+     * are dropped so the alias (the "latest" entry) wins.
+     */
+    listModels(): Promise<AgentModel[]>;
+}