@nopeek/agent-bridge 0.1.0 → 0.2.0

package/dist/cli.js

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
 // @nopeek/agent-bridge — connect your own agent runtime to NoPeek as E2EE bots.
-//   npx @nopeek/agent-bridge --pair npr_… --app-id app_… --brain-cmd '…'
+//
+//   nopeek-agent-bridge install    one-time: background service, then pair FROM THE APP
+//   nopeek-agent-bridge [run]      foreground (unpaired bridges wait for the app)
+//   nopeek-agent-bridge status     ask the running bridge how it's doing
+//   nopeek-agent-bridge uninstall  remove the service
 import { loadConfig, HELP } from "./config.js";
-import { runBridge } from "./bridge.js";
+import { BridgeApp, VERSION } from "./bridge.js";
+import { startLocalApi } from "./localapi.js";
+import { installService, uninstallService, printStatus } from "./service.js";
 // ---------------------------------------------------------------- guards ----
 // The bridge must never die to a stray rejection deep inside a WS/crypto
 // callback — one flaky bot cannot take the fleet down.
@@ -16,25 +22,87 @@ if (typeof WebSocket === "undefined" || !globalThis.crypto?.subtle) {
     console.error(`@nopeek/agent-bridge needs Node >= 22 (global WebSocket + fetch + WebCrypto). Current: ${process.version}`);
     process.exit(1);
 }
-// ---------------------------------------------------------------- config ----
+// ----------------------------------------------------------- subcommands ----
+const argv = process.argv.slice(2);
+const SUBCOMMANDS = new Set(["install", "uninstall", "status", "run", "help"]);
+const sub = argv[0] && SUBCOMMANDS.has(argv[0]) ? argv[0] : "run";
+const rest = sub === argv[0] ? argv.slice(1) : argv;
+if (sub === "help") {
+    console.log(HELP);
+    process.exit(0);
+}
 // Config errors exit cleanly with guidance — never a crash loop.
 let cfg;
 try {
-    cfg = loadConfig();
+    cfg = loadConfig(rest);
 }
 catch (err) {
     console.error(`[config] ${err.message}\n`);
     console.error(HELP);
     process.exit(1);
 }
-console.log(`[bridge] NoPeek agent-bridge starting`);
-console.log(`[bridge] api=${cfg.apiUrl} app=${cfg.appId} data=${cfg.dataDir} health=:${cfg.port}`);
-console.log(`[bridge] default brain: ${cfg.brainCmd ? "cmd" : cfg.brainUrl ? "url" : "echo (set --brain-cmd or --brain-url to plug in your agent)"}` +
+if (sub === "uninstall") {
+    uninstallService();
+    process.exit(0);
+}
+if (sub === "status") {
+    await printStatus(cfg.port);
+    process.exit(process.exitCode ?? 0);
+}
+if (sub === "install") {
+    try {
+        await installService(cfg);
+    }
+    catch (err) {
+        console.error(`[install] ${err.message}`);
+        process.exit(1);
+    }
+    // Optional: `install --pair npr_… --app-id app_…` pre-pairs the fresh service
+    // through its local API (same path the app uses).
+    if (cfg.pairingCode && cfg.appId) {
+        try {
+            const res = await fetch(`http://127.0.0.1:${cfg.port}/pair`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ pairingSecret: cfg.pairingCode, appId: cfg.appId, apiUrl: cfg.apiUrl }),
+            });
+            const body = (await res.json().catch(() => ({})));
+            if (res.ok)
+                console.log(`[install] paired successfully`);
+            else
+                console.error(`[install] pairing failed: ${body.message ?? `HTTP ${res.status}`}`);
+        }
+        catch (err) {
+            console.error(`[install] pairing failed: ${err.message}`);
+        }
+    }
+    process.exit(0);
+}
+// ---------------------------------------------------------------- run -------
+console.log(`[bridge] NoPeek agent-bridge v${VERSION} starting`);
+console.log(`[bridge] api=${cfg.apiUrl} app=${cfg.appId ?? "(not paired)"} data=${cfg.dataDir} local-api=:${cfg.port} home=${cfg.homeDir}`);
+console.log(`[bridge] default brain: ${cfg.brainCmd ? "cmd" : cfg.brainUrl ? "url" : "echo (choose an agent in the NoPeek app, or set --brain-cmd)"}` +
     (Object.keys(cfg.brainMap).length ? ` + ${Object.keys(cfg.brainMap).length} per-bot override(s)` : ""));
-const bridge = await runBridge(cfg);
+const app = new BridgeApp(cfg);
+let localApi;
+try {
+    localApi = await startLocalApi(app);
+}
+catch (err) {
+    const e = err;
+    if (e.code === "EADDRINUSE") {
+        console.error(`[bridge] port ${cfg.port} is already in use — another bridge is probably running (try 'nopeek-agent-bridge status'). Exiting.`);
+    }
+    else {
+        console.error(`[bridge] could not start local API: ${e.message}`);
+    }
+    process.exit(1);
+}
+app.start();
 const shutdown = (signal) => {
     console.log(`[bridge] ${signal} — shutting down`);
-    bridge.stop();
+    app.stop();
+    localApi.close();
     // Give sockets a beat to close, then force-exit so systemd/launchd restarts cleanly.
     setTimeout(() => process.exit(0), 500).unref();
 };

package/dist/config.d.ts

@@ -1,14 +1,17 @@
-/** Per-bot brain override, keyed by bot handle in BRAIN_MAP. */
+/** Per-bot brain override, keyed by bot handle in BRAIN_MAP.
+ *  `echo: true` pins the bot to echo mode even when a global brain is set. */
 export interface BrainSpec {
     cmd?: string;
     url?: string;
+    echo?: boolean;
 }
 export interface BridgeConfig {
     /** NoPeek API base, e.g. https://d3qweh72vesa98.cloudfront.net */
     apiUrl: string;
-    appId: string;
-    /** Runtime pairing token from the NoPeek app ("Connect your computer"), npr_… */
-    pairingCode: string;
+    /** Null until paired (from the app or via --pair/--app-id). */
+    appId: string | null;
+    /** Runtime pairing token (npr_…). Null until paired. */
+    pairingCode: string | null;
     /** Global brain: shell command reading the message on stdin, printing the reply. */
     brainCmd: string | null;
     /** Global brain: webhook POSTed {text, botHandle, botUserId, channelId, senderUserId}. */
@@ -16,14 +19,27 @@ export interface BridgeConfig {
     /** Per-handle overrides: { "<handle>": {"cmd": "…"} | {"url": "…"} }. */
     brainMap: Record<string, BrainSpec>;
     brainTimeoutMs: number;
-    /** Health endpoint port. */
+    /** Local control API port (status + pairing + brain config, loopback only). */
     port: number;
-    /** Where per-bot device identity/key stores live (./data by default). */
+    /** Where per-bot device identity/key stores live. */
     dataDir: string;
+    /** Bridge home: persisted settings, default data dir, service logs. */
+    homeDir: string;
+    /** Optional reply sent ONCE to an unauthorized sender. Null (default) =
+     *  silently ignore them (most private — doesn't reveal the bot exists). */
+    declineMessage: string | null;
 }
 export declare const DEFAULT_API_URL = "https://d3qweh72vesa98.cloudfront.net";
 export declare const DEFAULT_PORT = 8790;
 export declare const DEFAULT_BRAIN_TIMEOUT_MS = 180000;
-export declare const HELP = "nopeek-agent-bridge \u2014 run your agents as E2EE NoPeek bots\n\nUsage:\n  npx @nopeek/agent-bridge --pair npr_\u2026 --app-id app_\u2026 [--brain-cmd '\u2026' | --brain-url https://\u2026]\n\nOptions:\n  --pair <code>            One-time pairing code from the NoPeek app  (env NOPEEK_PAIRING_CODE)\n  --app-id <id>            NoPeek app id                              (env NOPEEK_APP_ID)\n  --api-url <url>          API base, default https://d3qweh72vesa98.cloudfront.net  (env NOPEEK_API_URL)\n  --brain-cmd <cmd>        Shell brain: message on stdin -> reply on stdout   (env BRAIN_CMD)\n  --brain-url <url>        Webhook brain: POST {text,...} -> {text|reply}     (env BRAIN_URL)\n  --brain-map <json>       Per-bot overrides {\"<handle>\":{\"cmd\":\"\u2026\"}|{\"url\":\"\u2026\"}} (env BRAIN_MAP)\n  --brain-timeout-ms <ms>  Brain timeout, default 180000          (env BRAIN_TIMEOUT_MS)\n  --port <port>            Health endpoint port, default 8790       (env NOPEEK_BRIDGE_PORT)\n  --data-dir <dir>         Device-key store dir, default ./data       (env NOPEEK_BRIDGE_DATA_DIR)\n  --config <path>          Config file, default ./nopeek-bridge.config.json\n  -h, --help               Show this help\n\nWith no brain configured, bots run in echo mode (\"You said: \u2026\") \u2014 a zero-config smoke test.";
-/** Load config from argv + env + config file. Throws on missing/invalid values. */
+export declare function defaultHomeDir(): string;
+export declare const HELP = "nopeek-agent-bridge \u2014 run your agents as E2EE NoPeek bots\n\nUsage:\n  nopeek-agent-bridge install     Install as a background service (launchd/systemd),\n                                  then finish setup from the NoPeek app:\n                                  Bots -> Connect this computer.\n  nopeek-agent-bridge uninstall   Remove the background service (keeps data/settings).\n  nopeek-agent-bridge status      Show the running bridge's status.\n  nopeek-agent-bridge [run]       Run in the foreground. Unpaired bridges wait to be\n                                  paired from the NoPeek app; --pair still works:\n                                    npx @nopeek/agent-bridge --pair npr_\u2026 --app-id app_\u2026\n\nOptions:\n  --pair <code>            Pairing code from the NoPeek app             (env NOPEEK_PAIRING_CODE)\n  --app-id <id>            NoPeek app id                                (env NOPEEK_APP_ID)\n  --api-url <url>          API base, default https://d3qweh72vesa98.cloudfront.net  (env NOPEEK_API_URL)\n  --brain-cmd <cmd>        Shell brain: message on stdin -> reply on stdout   (env BRAIN_CMD)\n  --brain-url <url>        Webhook brain: POST {text,...} -> {text|reply}     (env BRAIN_URL)\n  --brain-map <json>       Per-bot overrides {\"<handle>\":{\"cmd\":\"\u2026\"}|{\"url\":\"\u2026\"}} (env BRAIN_MAP)\n  --brain-timeout-ms <ms>  Brain timeout, default 180000          (env BRAIN_TIMEOUT_MS)\n  --port <port>            Local control API port, default 8790    (env NOPEEK_BRIDGE_PORT)\n  --data-dir <dir>         Device-key store dir                        (env NOPEEK_BRIDGE_DATA_DIR)\n  --home <dir>             Bridge home, default ~/.nopeek-bridge       (env NOPEEK_BRIDGE_HOME)\n  --config <path>          Config file, default ./nopeek-bridge.config.json\n  -h, --help               Show this help\n\nWith no brain configured, bots run in echo mode (\"You said: \u2026\") \u2014 a zero-config smoke test.\nPairing and brains can be managed entirely from the NoPeek app once the service is running.";
+/** Load config from argv + env + cwd config file + home settings. Never
+ *  requires pairing — an unpaired bridge waits for the app to pair it. */
 export declare function loadConfig(argv?: string[]): BridgeConfig;
+/**
+ * Persist the app-manageable parts of the config (pairing + brains) to
+ * <home>/settings.json so pairing from the NoPeek app survives restarts.
+ * Written atomically; the file contains a bearer credential — chmod 600.
+ */
+export declare function saveSettings(cfg: BridgeConfig): void;

package/dist/config.js

@@ -1,13 +1,20 @@
 // Bridge config. Precedence: CLI flags > environment variables > optional
-// ./nopeek-bridge.config.json (same key names as the env vars). Throws with a
-// clear, actionable message when required values are missing — the CLI turns
-// that into a clean exit, never a crash loop.
-import { readFileSync, existsSync } from "node:fs";
-import { resolve } from "node:path";
+// ./nopeek-bridge.config.json (same key names as the env vars) > persisted
+// settings in the bridge home (~/.nopeek-bridge/settings.json — written when
+// you pair or set brains FROM THE NOPEEK APP).
+//
+// Pairing is no longer required at startup: an unpaired bridge starts its
+// local control API and waits for the NoPeek app to POST /pair.
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 export const DEFAULT_API_URL = "https://d3qweh72vesa98.cloudfront.net";
 export const DEFAULT_PORT = 8790;
 export const DEFAULT_BRAIN_TIMEOUT_MS = 180_000;
+export function defaultHomeDir() {
+    return process.env.NOPEEK_BRIDGE_HOME || join(homedir(), ".nopeek-bridge");
+}
 const CLI_OPTIONS = {
     pair: { type: "string" },
     "api-url": { type: "string" },
@@ -16,8 +23,10 @@ const CLI_OPTIONS = {
     "brain-url": { type: "string" },
     "brain-map": { type: "string" },
     "brain-timeout-ms": { type: "string" },
+    "decline-message": { type: "string" },
     port: { type: "string" },
     "data-dir": { type: "string" },
+    home: { type: "string" },
     config: { type: "string" },
     help: { type: "boolean", short: "h" },
 };
@@ -30,29 +39,40 @@ const FLAG_TO_KEY = {
     "brain-url": "BRAIN_URL",
     "brain-map": "BRAIN_MAP",
     "brain-timeout-ms": "BRAIN_TIMEOUT_MS",
+    "decline-message": "NOPEEK_DECLINE_MESSAGE",
     port: "NOPEEK_BRIDGE_PORT",
     "data-dir": "NOPEEK_BRIDGE_DATA_DIR",
+    home: "NOPEEK_BRIDGE_HOME",
 };
 export const HELP = `nopeek-agent-bridge — run your agents as E2EE NoPeek bots
 
 Usage:
-  npx @nopeek/agent-bridge --pair npr_… --app-id app_… [--brain-cmd '…' | --brain-url https://…]
+  nopeek-agent-bridge install     Install as a background service (launchd/systemd),
+                                  then finish setup from the NoPeek app:
+                                  Bots -> Connect this computer.
+  nopeek-agent-bridge uninstall   Remove the background service (keeps data/settings).
+  nopeek-agent-bridge status      Show the running bridge's status.
+  nopeek-agent-bridge [run]       Run in the foreground. Unpaired bridges wait to be
+                                  paired from the NoPeek app; --pair still works:
+                                    npx @nopeek/agent-bridge --pair npr_… --app-id app_…
 
 Options:
-  --pair <code>            One-time pairing code from the NoPeek app  (env NOPEEK_PAIRING_CODE)
-  --app-id <id>            NoPeek app id                              (env NOPEEK_APP_ID)
+  --pair <code>            Pairing code from the NoPeek app             (env NOPEEK_PAIRING_CODE)
+  --app-id <id>            NoPeek app id                                (env NOPEEK_APP_ID)
   --api-url <url>          API base, default ${DEFAULT_API_URL}  (env NOPEEK_API_URL)
   --brain-cmd <cmd>        Shell brain: message on stdin -> reply on stdout   (env BRAIN_CMD)
   --brain-url <url>        Webhook brain: POST {text,...} -> {text|reply}     (env BRAIN_URL)
   --brain-map <json>       Per-bot overrides {"<handle>":{"cmd":"…"}|{"url":"…"}} (env BRAIN_MAP)
   --brain-timeout-ms <ms>  Brain timeout, default ${DEFAULT_BRAIN_TIMEOUT_MS}          (env BRAIN_TIMEOUT_MS)
-  --port <port>            Health endpoint port, default ${DEFAULT_PORT}       (env NOPEEK_BRIDGE_PORT)
-  --data-dir <dir>         Device-key store dir, default ./data       (env NOPEEK_BRIDGE_DATA_DIR)
+  --port <port>            Local control API port, default ${DEFAULT_PORT}    (env NOPEEK_BRIDGE_PORT)
+  --data-dir <dir>         Device-key store dir                        (env NOPEEK_BRIDGE_DATA_DIR)
+  --home <dir>             Bridge home, default ~/.nopeek-bridge       (env NOPEEK_BRIDGE_HOME)
   --config <path>          Config file, default ./nopeek-bridge.config.json
   -h, --help               Show this help
 
-With no brain configured, bots run in echo mode ("You said: …") — a zero-config smoke test.`;
-function readConfigFile(path, explicit) {
+With no brain configured, bots run in echo mode ("You said: …") — a zero-config smoke test.
+Pairing and brains can be managed entirely from the NoPeek app once the service is running.`;
+function readJsonFile(path, explicit) {
     if (!existsSync(path)) {
         if (explicit)
             throw new Error(`config file not found: ${path}`);
@@ -66,7 +86,6 @@ function readConfigFile(path, explicit) {
                 continue;
             out[k] = typeof v === "string" ? v : JSON.stringify(v);
         }
-        console.log(`[config] loaded ${path}`);
         return out;
     }
     catch (err) {
@@ -102,34 +121,40 @@ function parseBrainMap(raw) {
     }
     return out;
 }
-/** Load config from argv + env + config file. Throws on missing/invalid values. */
+function settingsPath(homeDir) {
+    return join(homeDir, "settings.json");
+}
+/** Load config from argv + env + cwd config file + home settings. Never
+ *  requires pairing — an unpaired bridge waits for the app to pair it. */
 export function loadConfig(argv = process.argv.slice(2)) {
     const { values: flags } = parseArgs({ args: argv, options: CLI_OPTIONS, strict: true });
     if (flags.help) {
         console.log(HELP);
         process.exit(0);
     }
+    const homeDir = resolve(flags.home ?? defaultHomeDir());
     const configPath = resolve(process.cwd(), flags.config ?? "nopeek-bridge.config.json");
-    const file = readConfigFile(configPath, flags.config !== undefined);
+    const file = readJsonFile(configPath, flags.config !== undefined);
+    if (Object.keys(file).length)
+        console.log(`[config] loaded ${configPath}`);
+    const saved = readJsonFile(settingsPath(homeDir), false);
+    if (Object.keys(saved).length)
+        console.log(`[config] loaded ${settingsPath(homeDir)}`);
     const get = (flagName) => {
         const key = FLAG_TO_KEY[flagName];
-        const v = flags[flagName] ?? process.env[key] ?? file[key];
+        const v = flags[flagName] ??
+            process.env[key] ??
+            file[key] ??
+            saved[key];
         return v === undefined || v === "" ? undefined : v;
     };
-    const pairingCode = get("pair");
-    if (!pairingCode) {
-        throw new Error(`missing pairing code.\n` +
-            `Get one from the NoPeek app ("Connect your computer"), then run:\n` +
-            `  npx @nopeek/agent-bridge --pair npr_…\n` +
-            `or set NOPEEK_PAIRING_CODE (env or nopeek-bridge.config.json).`);
-    }
-    if (!pairingCode.startsWith("npr_")) {
+    const pairingCode = get("pair") ?? null;
+    if (pairingCode && !pairingCode.startsWith("npr_")) {
         console.warn(`[config] pairing code does not start with "npr_" — double-check you pasted the runtime pairing code`);
     }
-    const appId = get("app-id");
-    if (!appId) {
-        throw new Error(`missing app id.\n` +
-            `Pass --app-id app_… or set NOPEEK_APP_ID (shown alongside the pairing code in the NoPeek app).`);
+    const appId = get("app-id") ?? null;
+    if (pairingCode && !appId) {
+        throw new Error(`--pair was given without --app-id (or NOPEEK_APP_ID) — both are needed to connect.`);
     }
     const brainTimeoutMs = Number(get("brain-timeout-ms") ?? DEFAULT_BRAIN_TIMEOUT_MS);
     if (!Number.isFinite(brainTimeoutMs) || brainTimeoutMs <= 0) {
@@ -139,6 +164,14 @@ export function loadConfig(argv = process.argv.slice(2)) {
     if (!Number.isInteger(port) || port < 0 || port > 65535) {
         throw new Error(`NOPEEK_BRIDGE_PORT must be a valid port number`);
     }
+    // Data dir: explicit wins; a legacy ./data (pre-0.2 default) keeps working;
+    // otherwise device keys live in the bridge home.
+    const explicitDataDir = get("data-dir");
+    const dataDir = explicitDataDir
+        ? resolve(process.cwd(), explicitDataDir)
+        : existsSync(resolve(process.cwd(), "data"))
+            ? resolve(process.cwd(), "data")
+            : join(homeDir, "data");
     return {
         apiUrl: (get("api-url") ?? DEFAULT_API_URL).replace(/\/+$/, ""),
         appId,
@@ -148,6 +181,29 @@ export function loadConfig(argv = process.argv.slice(2)) {
         brainMap: parseBrainMap(get("brain-map")),
         brainTimeoutMs,
         port,
-        dataDir: resolve(process.cwd(), get("data-dir") ?? "data"),
+        dataDir,
+        homeDir,
+        declineMessage: get("decline-message") ?? null,
+    };
+}
+/**
+ * Persist the app-manageable parts of the config (pairing + brains) to
+ * <home>/settings.json so pairing from the NoPeek app survives restarts.
+ * Written atomically; the file contains a bearer credential — chmod 600.
+ */
+export function saveSettings(cfg) {
+    mkdirSync(cfg.homeDir, { recursive: true });
+    const out = {
+        NOPEEK_API_URL: cfg.apiUrl,
+        ...(cfg.appId ? { NOPEEK_APP_ID: cfg.appId } : {}),
+        ...(cfg.pairingCode ? { NOPEEK_PAIRING_CODE: cfg.pairingCode } : {}),
+        ...(cfg.brainCmd ? { BRAIN_CMD: cfg.brainCmd } : {}),
+        ...(cfg.brainUrl ? { BRAIN_URL: cfg.brainUrl } : {}),
+        ...(Object.keys(cfg.brainMap).length ? { BRAIN_MAP: JSON.stringify(cfg.brainMap) } : {}),
+        ...(cfg.declineMessage ? { NOPEEK_DECLINE_MESSAGE: cfg.declineMessage } : {}),
     };
+    const path = settingsPath(cfg.homeDir);
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(out, null, 2), { mode: 0o600 });
+    renameSync(tmp, path);
 }

package/dist/control.js

@@ -27,7 +27,7 @@ export class ControlSocket {
     connect() {
         if (this.stopped)
             return;
-        const url = `${this.cfg.apiUrl.replace(/^http/, "ws")}/v1/ws?runtimeToken=${encodeURIComponent(this.cfg.pairingCode)}`;
+        const url = `${this.cfg.apiUrl.replace(/^http/, "ws")}/v1/ws?runtimeToken=${encodeURIComponent(this.cfg.pairingCode ?? "")}`;
         let ws;
         try {
             ws = new WebSocket(url);

package/dist/detect.d.ts

@@ -0,0 +1,11 @@
+export interface DetectedRuntime {
+    id: string;
+    label: string;
+    bin: string;
+    found: boolean;
+    path: string | null;
+    /** Suggested BRAIN_CMD for this runtime (message on stdin -> reply on stdout). */
+    template: string;
+}
+/** Probe all known runtimes concurrently (a couple hundred ms, cached by caller). */
+export declare function detectRuntimes(): Promise<DetectedRuntime[]>;

package/dist/detect.js

@@ -0,0 +1,47 @@
+// Detect agent runtimes installed on this machine so the NoPeek app can offer
+// them as one-tap brains. Detection is just `command -v <bin>` — the app shows
+// the suggested command template, the user can edit it, and the final string is
+// stored locally (never on the server) as that bot's BRAIN_MAP entry.
+import { spawn } from "node:child_process";
+const CANDIDATES = [
+    {
+        id: "hermes",
+        label: "Hermes",
+        bin: "hermes",
+        template: 'hermes chat -Q -q "$(cat)"',
+    },
+    {
+        id: "claude",
+        label: "Claude Code",
+        bin: "claude",
+        template: 'claude -p "$(cat)"',
+    },
+    {
+        id: "llm",
+        label: "llm (Simon Willison)",
+        bin: "llm",
+        template: 'llm "$(cat)"',
+    },
+    {
+        id: "ollama",
+        label: "Ollama",
+        bin: "ollama",
+        template: 'ollama run llama3.2 "$(cat)"',
+    },
+];
+function which(bin) {
+    return new Promise((resolvePromise) => {
+        const child = spawn("bash", ["-lc", `command -v ${bin}`], { stdio: ["ignore", "pipe", "ignore"] });
+        let out = "";
+        child.stdout.on("data", (d) => (out += d.toString()));
+        child.on("error", () => resolvePromise(null));
+        child.on("close", (code) => resolvePromise(code === 0 && out.trim() ? out.trim().split("\n")[0] : null));
+    });
+}
+/** Probe all known runtimes concurrently (a couple hundred ms, cached by caller). */
+export async function detectRuntimes() {
+    return Promise.all(CANDIDATES.map(async (c) => {
+        const path = await which(c.bin);
+        return { ...c, found: path !== null, path };
+    }));
+}

package/dist/localapi.d.ts

@@ -0,0 +1,3 @@
+import { type Server } from "node:http";
+import { BridgeApp } from "./bridge.js";
+export declare function startLocalApi(app: BridgeApp): Promise<Server>;

package/dist/localapi.js

@@ -0,0 +1,179 @@
+// Local control API — how the NoPeek app manages this bridge with zero
+// terminal work after install. Loopback-only (127.0.0.1); the app on the same
+// computer calls it directly from the browser.
+//
+// Auth model:
+//   GET  /        minimal, unauthenticated status (is a bridge here? paired?)
+//   POST /pair    unauthenticated BUT only accepted while unpaired, and the
+//                 npr_ secret itself is the (server-minted, unguessable) proof.
+//   everything else requires header `x-nopeek-runtime: rt_…` — the runtime id,
+//   which only the OWNER's logged-in app can fetch from the NoPeek server
+//   (GET /bot-runtimes). A random webpage can't know it, so drive-by requests
+//   to 127.0.0.1 can't read bot lists or change brain commands.
+//
+// CORS reflects the caller origin (the app may be served from any white-label
+// domain) and answers Chrome's Private Network Access preflight.
+import { createServer } from "node:http";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { PairError } from "./bridge.js";
+import { detectRuntimes } from "./detect.js";
+const BODY_LIMIT = 64 * 1024;
+function setCors(req, res) {
+    const origin = req.headers.origin;
+    if (!origin)
+        return; // curl and friends — CORS is a browser concern
+    res.setHeader("access-control-allow-origin", origin);
+    res.setHeader("vary", "Origin");
+    res.setHeader("access-control-allow-methods", "GET,POST,PUT,DELETE,OPTIONS");
+    res.setHeader("access-control-allow-headers", "content-type, x-nopeek-runtime");
+    res.setHeader("access-control-max-age", "600");
+    if (req.headers["access-control-request-private-network"] === "true") {
+        // Chrome PNA: a public https page fetching 127.0.0.1 needs this on preflight.
+        res.setHeader("access-control-allow-private-network", "true");
+    }
+}
+function json(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify(body));
+}
+function readBody(req) {
+    return new Promise((resolvePromise, reject) => {
+        let body = "";
+        req.on("data", (d) => {
+            body += d.toString();
+            if (body.length > BODY_LIMIT) {
+                reject(new Error("body too large"));
+                req.destroy();
+            }
+        });
+        req.on("end", () => {
+            if (!body.trim())
+                return resolvePromise({});
+            try {
+                const parsed = JSON.parse(body);
+                if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                    return reject(new Error("body must be a JSON object"));
+                }
+                resolvePromise(parsed);
+            }
+            catch {
+                reject(new Error("body is not valid JSON"));
+            }
+        });
+        req.on("error", reject);
+    });
+}
+/** Constant-time compare of unequal-length strings via SHA-256. */
+function safeEq(a, b) {
+    const ha = createHash("sha256").update(a).digest();
+    const hb = createHash("sha256").update(b).digest();
+    return timingSafeEqual(ha, hb);
+}
+function authorized(app, req) {
+    const header = req.headers["x-nopeek-runtime"];
+    const given = Array.isArray(header) ? header[0] : header;
+    if (!given)
+        return "denied";
+    const rt = app.runtimeId;
+    if (!rt)
+        return "no-runtime-yet"; // paired but control socket hasn't auth'd yet
+    return safeEq(given, rt) ? "ok" : "denied";
+}
+export function startLocalApi(app) {
+    const server = createServer((req, res) => {
+        void handle(app, req, res).catch((err) => {
+            console.error(`[localapi] ${err.message}`);
+            if (!res.headersSent)
+                json(res, 500, { error: "INTERNAL", message: "internal error" });
+            else
+                res.end();
+        });
+    });
+    return new Promise((resolvePromise, reject) => {
+        server.once("error", reject);
+        server.listen(app.cfg.port, "127.0.0.1", () => {
+            console.log(`[localapi] http://127.0.0.1:${app.cfg.port}/ (status, pairing, brains — loopback only)`);
+            resolvePromise(server);
+        });
+    });
+}
+async function handle(app, req, res) {
+    setCors(req, res);
+    const method = req.method ?? "GET";
+    const path = (req.url ?? "/").split("?")[0].replace(/\/+$/, "") || "/";
+    if (method === "OPTIONS") {
+        res.statusCode = 204;
+        res.end();
+        return;
+    }
+    // Unauthenticated: presence probe. Deliberately minimal — no handles, no
+    // runtime id, no brain config (any webpage can read this).
+    if (method === "GET" && path === "/") {
+        json(res, 200, app.statusMinimal());
+        return;
+    }
+    // Unauthenticated but self-proving (npr_ secret) and unpaired-only.
+    if (method === "POST" && path === "/pair") {
+        let body;
+        try {
+            body = await readBody(req);
+        }
+        catch (err) {
+            json(res, 400, { error: "BAD_REQUEST", message: err.message });
+            return;
+        }
+        try {
+            await app.pair(body);
+            json(res, 200, { ok: true, paired: true });
+        }
+        catch (err) {
+            if (err instanceof PairError) {
+                const status = err.code === "ALREADY_PAIRED" ? 409 : err.code === "BAD_REQUEST" ? 400 : err.code === "PAIR_REJECTED" ? 401 : 502;
+                json(res, status, { error: err.code, message: err.message });
+            }
+            else {
+                json(res, 500, { error: "INTERNAL", message: err.message });
+            }
+        }
+        return;
+    }
+    // Everything below requires the runtime id capability.
+    const auth = authorized(app, req);
+    if (auth !== "ok") {
+        if (auth === "no-runtime-yet") {
+            json(res, 503, { error: "NOT_READY", message: "bridge is still connecting — retry in a moment" });
+        }
+        else {
+            json(res, 403, { error: "FORBIDDEN", message: "missing or wrong x-nopeek-runtime header" });
+        }
+        return;
+    }
+    if (method === "GET" && path === "/status") {
+        json(res, 200, app.statusFull());
+        return;
+    }
+    if (method === "GET" && path === "/detect") {
+        json(res, 200, { runtimes: await detectRuntimes() });
+        return;
+    }
+    if (method === "PUT" && path === "/brains") {
+        let body;
+        try {
+            body = await readBody(req);
+        }
+        catch (err) {
+            json(res, 400, { error: "BAD_REQUEST", message: err.message });
+            return;
+        }
+        app.setBrains(body);
+        json(res, 200, { ok: true, status: app.statusFull() });
+        return;
+    }
+    if (method === "DELETE" && path === "/pair") {
+        app.unpair();
+        json(res, 200, { ok: true, paired: false });
+        return;
+    }
+    json(res, 404, { error: "NOT_FOUND", message: `no ${method} ${path}` });
+}

package/dist/service.d.ts

@@ -0,0 +1,4 @@
+import type { BridgeConfig } from "./config.js";
+export declare function installService(cfg: BridgeConfig): Promise<void>;
+export declare function uninstallService(): void;
+export declare function printStatus(port: number): Promise<void>;