@nopeek/agent-bridge 0.2.1 → 0.4.0

package/dist/backends.d.ts

@@ -0,0 +1,38 @@
+import type { BridgeConfig } from "./config.js";
+import { type Brain } from "./brain.js";
+export declare function soulsDir(homeDir: string): string;
+export declare function soulPath(homeDir: string, handle: string): string;
+/**
+ * Write <home>/agent-souls/<handle>.md from the built-in template if absent
+ * (idempotent — an existing, possibly hand-edited soul is never overwritten).
+ * Returns the soul path.
+ */
+export declare function provisionSoul(handle: string, homeDir: string): string;
+/**
+ * Deterministic per-(bot, channel) session UUID so each chat is one running
+ * Claude conversation. UUIDv5-ish (sha1 of the key formatted as a UUID) —
+ * byte-for-byte identical to tools/agent/bot-brain.sh so existing sessions
+ * keep their history when a bot moves from the shell brain to the native one.
+ */
+export declare function sessionUuid(handle: string, channelId: string): string;
+/**
+ * Claude Code backend: `claude -p` headless (reliable — no OAuth flakiness),
+ * one continuous session per (bot, channel). Streams assistant text deltas
+ * only. Runs in a dedicated empty cwd with --strict-mcp-config and a tool
+ * denylist, so a chat bot never inherits repo CLAUDE.md, MCP servers, or
+ * host powers from wherever the bridge happens to run.
+ */
+export declare function claudeBrain(cfg: BridgeConfig): Brain;
+/**
+ * Create (or reuse) the bot's isolated Hermes profile: its own SOUL.md and
+ * memories/, inheriting the main install's model config and provider auth
+ * (auth.json symlink — OAuth tokens refresh in place, so every bot profile
+ * stays authenticated from one login). Idempotent.
+ */
+export declare function provisionHermesProfile(handle: string): string;
+/**
+ * Hermes backend: per-bot profile (own soul + memories), one persistent
+ * session per channel (`--continue nopeek-<channel>`), streaming cleaned
+ * stdout lines to onChunk.
+ */
+export declare function hermesBrain(cfg: BridgeConfig): Brain;

package/dist/backends.js

@@ -0,0 +1,384 @@
+// Native brain backends — no external shell scripts required. Two batteries-
+// included agent runtimes the bridge can drive directly:
+//
+//   claude — Claude Code headless (`claude -p`), one continuous session per
+//            (bot, channel) via a deterministic session UUID, streaming
+//            assistant text deltas (stream-json) to onChunk.
+//   hermes — a per-bot Hermes profile (own soul + memories) under
+//            $HERMES_HOME/profiles/bot-<handle>, one persistent chat session
+//            per channel (--continue), streaming stdout lines to onChunk.
+//
+// Both are Brains: (text, ctx, onChunk?) => Promise<fullReply>. The returned
+// string is authoritative for the final message body; onChunk deltas are
+// display-only. Selected per bot via BRAIN_MAP entries like {"backend":"claude"}.
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { stripAnsi } from "./brain.js";
+const BRAIN_UNREACHABLE = "⚠️ I couldn't reach my brain just now — please try again in a moment.";
+// ------------------------------------------------------------------ souls ----
+/** Built-in personality template — personalized per bot by provisionSoul(). */
+const SOUL_TEMPLATE = `You are {{NAME}} (handle @{{HANDLE}}), a personal AI agent reachable through the
+NoPeek end-to-end-encrypted messenger. A human messages you in a chat; you help;
+you reply. Everything you output is sent verbatim as a chat message.
+
+Voice: friendly, sharp, concise. This is a chat, not a report — short paragraphs
+or brief lists, no markdown headers. Answer the question directly.
+
+You have your own memory of past conversations in this chat (each chat is a
+separate ongoing thread). Remember what the humans tell you.
+
+Guardrails: never expose secrets or tokens; confirm before anything destructive
+or outward-facing; report honestly when something failed; if a request is far
+outside what you can do, say so briefly and offer what you can.
+`;
+export function soulsDir(homeDir) {
+    return join(homeDir, "agent-souls");
+}
+export function soulPath(homeDir, handle) {
+    return join(soulsDir(homeDir), `${handle.replace(/^@/, "")}.md`);
+}
+/** "weather_bot" -> "weather", "ops_helper" -> "ops helper". */
+function displayName(handle) {
+    return handle.replace(/^@/, "").replace(/_bot$/, "").replace(/_/g, " ") || handle;
+}
+/**
+ * Write <home>/agent-souls/<handle>.md from the built-in template if absent
+ * (idempotent — an existing, possibly hand-edited soul is never overwritten).
+ * Returns the soul path.
+ */
+export function provisionSoul(handle, homeDir) {
+    const h = handle.replace(/^@/, "");
+    const path = soulPath(homeDir, h);
+    if (!existsSync(path)) {
+        mkdirSync(soulsDir(homeDir), { recursive: true });
+        const soul = SOUL_TEMPLATE.replace(/\{\{HANDLE\}\}/g, h).replace(/\{\{NAME\}\}/g, displayName(h));
+        writeFileSync(path, soul);
+        console.log(`[soul:@${h}] provisioned ${path}`);
+    }
+    return path;
+}
+// ----------------------------------------------------------------- helpers ----
+/** Resolve a binary: $<ENVVAR> > PATH (command -v) > common install dirs. */
+function resolveBin(name, envVar) {
+    const fromEnv = process.env[envVar];
+    if (fromEnv)
+        return fromEnv;
+    const r = spawnSync("bash", ["-lc", `command -v ${name}`], { encoding: "utf8" });
+    const found = (r.stdout || "").trim().split("\n")[0];
+    if (r.status === 0 && found)
+        return found;
+    for (const dir of [join(homedir(), ".local", "bin"), "/usr/local/bin", "/opt/homebrew/bin"]) {
+        const p = join(dir, name);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * Deterministic per-(bot, channel) session UUID so each chat is one running
+ * Claude conversation. UUIDv5-ish (sha1 of the key formatted as a UUID) —
+ * byte-for-byte identical to tools/agent/bot-brain.sh so existing sessions
+ * keep their history when a bot moves from the shell brain to the native one.
+ */
+export function sessionUuid(handle, channelId) {
+    const h = createHash("sha1").update(`nopeek:${handle}:${channelId}`).digest("hex").slice(0, 32);
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-5${h.slice(13, 16)}-8${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+function runClaudeOnce(bin, args, text, cwd, timeoutMs, tag, onDelta) {
+    return new Promise((resolvePromise) => {
+        const child = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"], cwd });
+        let deltas = "";
+        let resultText = "";
+        let assistantText = "";
+        let lineBuf = "";
+        let stderr = "";
+        let settled = false;
+        const handleLine = (line) => {
+            if (!line.trim())
+                return;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                return; // non-JSON noise
+            }
+            if (parsed.type === "stream_event" &&
+                parsed.event?.type === "content_block_delta" &&
+                parsed.event.delta?.type === "text_delta" &&
+                typeof parsed.event.delta.text === "string") {
+                deltas += parsed.event.delta.text;
+                onDelta(parsed.event.delta.text);
+                return;
+            }
+            // Fallbacks if no text_delta ever arrives (older CLIs / odd runs):
+            if (parsed.type === "result" && typeof parsed.result === "string") {
+                resultText = parsed.result;
+                return;
+            }
+            if (parsed.type === "assistant" && Array.isArray(parsed.message?.content)) {
+                const t = parsed.message.content
+                    .filter((b) => b.type === "text" && typeof b.text === "string")
+                    .map((b) => b.text)
+                    .join("");
+                if (t)
+                    assistantText = t;
+            }
+        };
+        const finish = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            if (lineBuf)
+                handleLine(lineBuf);
+            const reply = (deltas.trim() || resultText.trim() || assistantText.trim());
+            if (!reply && stderr.trim())
+                console.error(`${tag} stderr: ${stderr.slice(0, 1000)}`);
+            resolvePromise({ reply, exitCode });
+        };
+        const timer = setTimeout(() => {
+            console.error(`${tag} timed out after ${timeoutMs / 1000}s, killing`);
+            child.kill("SIGKILL");
+            finish(null);
+        }, timeoutMs);
+        child.stdout.on("data", (d) => {
+            lineBuf += d.toString();
+            const lines = lineBuf.split("\n");
+            lineBuf = lines.pop() ?? "";
+            for (const line of lines)
+                handleLine(line);
+        });
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            console.error(`${tag} spawn error: ${err.message}`);
+            finish(null);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            finish(code);
+        });
+        child.stdin.on("error", () => {
+            /* claude may exit before reading stdin — close handler settles */
+        });
+        child.stdin.write(text);
+        child.stdin.end();
+    });
+}
+/**
+ * Claude Code backend: `claude -p` headless (reliable — no OAuth flakiness),
+ * one continuous session per (bot, channel). Streams assistant text deltas
+ * only. Runs in a dedicated empty cwd with --strict-mcp-config and a tool
+ * denylist, so a chat bot never inherits repo CLAUDE.md, MCP servers, or
+ * host powers from wherever the bridge happens to run.
+ */
+export function claudeBrain(cfg) {
+    return async (text, ctx, onChunk) => {
+        const bin = resolveBin("claude", "CLAUDE_BIN");
+        if (!bin) {
+            console.error(`[brain:claude:@${ctx.botHandle}] claude not found on PATH`);
+            return BRAIN_UNREACHABLE;
+        }
+        const handle = ctx.botHandle.replace(/^@/, "");
+        const soulFile = provisionSoul(handle, cfg.homeDir);
+        let soul = "";
+        try {
+            soul = readFileSync(soulFile, "utf8");
+        }
+        catch {
+            /* missing/unreadable soul — run with base behavior */
+        }
+        const sid = sessionUuid(handle, ctx.channelId);
+        const runDir = join(cfg.homeDir, "agent-run");
+        mkdirSync(runDir, { recursive: true });
+        const tag = `[brain:claude:@${handle}]`;
+        const baseArgs = [
+            "-p",
+            "--verbose", // required by -p + --output-format stream-json
+            "--append-system-prompt",
+            soul,
+            "--disallowedTools",
+            "Bash Edit Write NotebookEdit MultiEdit Task WebFetch",
+            "--strict-mcp-config", // never inherit the host's MCP servers
+            "--output-format",
+            "stream-json",
+            "--include-partial-messages",
+        ];
+        // Only forward deltas from the attempt that actually produces text, so a
+        // failed --resume can't leak a half-answer before the retry streams.
+        let emitted = false;
+        const emit = (delta) => {
+            emitted = true;
+            onChunk?.(delta);
+        };
+        // Resume this chat's session; if it doesn't exist yet, create it with that id.
+        const first = await runClaudeOnce(bin, [...baseArgs, "--resume", sid], text, runDir, cfg.brainTimeoutMs, tag, emit);
+        if (first.reply)
+            return first.reply;
+        if (emitted) {
+            // Deltas reached the chat but the run died before a final — don't retry
+            // into a duplicate answer; tell the user honestly.
+            return BRAIN_UNREACHABLE;
+        }
+        console.error(`${tag} --resume ${sid} yielded nothing (exit ${first.exitCode}) — retrying with --session-id`);
+        const second = await runClaudeOnce(bin, [...baseArgs, "--session-id", sid], text, runDir, cfg.brainTimeoutMs, tag, emit);
+        if (second.reply)
+            return second.reply;
+        console.error(`${tag} both attempts yielded nothing (exit ${second.exitCode})`);
+        return BRAIN_UNREACHABLE;
+    };
+}
+// ----------------------------------------------------------------- hermes ----
+function hermesHome() {
+    return process.env.HERMES_HOME || "/Volumes/x10drive/hermes";
+}
+/** Hermes profile-local soul (mirrors tools/hermes/SOUL-template.md). */
+const HERMES_SOUL_TEMPLATE = `# {{NAME}} — Hermes profile for a NoPeek bot
+
+You are **{{NAME}}** (handle \`@{{HANDLE}}\`), a personal AI agent reachable through the
+**NoPeek** end-to-end-encrypted messenger. A human messages you in the app; you help;
+you reply. Your replies are chat messages — every word you print is sent verbatim.
+
+## Voice
+- Friendly, sharp, practical. Concise by default — this is a chat, not a report.
+- Plain language. No markdown headers in replies; short paragraphs or brief lists only.
+
+## Memory
+- This profile is yours alone: your soul (this file) and your memories
+  (\`memories/\` in this profile) belong to \`@{{HANDLE}}\` and no other bot.
+- Remember durable facts the humans tell you; forget nothing they'd expect you to keep.
+
+## Guardrails
+- Never expose secrets, keys, or tokens.
+- Confirm before destructive or outward-facing actions.
+- Report honestly — if something failed, say so.
+- If a request is far outside your purpose, say so briefly and offer what you can do.
+`;
+/**
+ * Create (or reuse) the bot's isolated Hermes profile: its own SOUL.md and
+ * memories/, inheriting the main install's model config and provider auth
+ * (auth.json symlink — OAuth tokens refresh in place, so every bot profile
+ * stays authenticated from one login). Idempotent.
+ */
+export function provisionHermesProfile(handle) {
+    const h = handle.replace(/^@/, "");
+    const home = hermesHome();
+    const profile = `bot-${h}`;
+    const pdir = join(home, "profiles", profile);
+    if (!existsSync(pdir)) {
+        mkdirSync(join(pdir, "memories"), { recursive: true });
+        mkdirSync(join(pdir, "home"), { recursive: true });
+        const soul = HERMES_SOUL_TEMPLATE.replace(/\{\{HANDLE\}\}/g, h).replace(/\{\{NAME\}\}/g, displayName(h));
+        writeFileSync(join(pdir, "SOUL.md"), soul);
+        writeFileSync(join(pdir, "memories", "MEMORY.md"), "");
+        const mainConfig = join(home, "config.yaml");
+        if (existsSync(mainConfig))
+            copyFileSync(mainConfig, join(pdir, "config.yaml"));
+        const mainAuth = join(home, "auth.json");
+        if (existsSync(mainAuth) && !existsSync(join(pdir, "auth.json"))) {
+            try {
+                symlinkSync(mainAuth, join(pdir, "auth.json"));
+            }
+            catch {
+                /* best-effort — hermes still runs, just unauthenticated */
+            }
+        }
+        console.log(`[hermes:@${h}] provisioned profile ${pdir}`);
+    }
+    return profile;
+}
+// Chat chrome Hermes prints even in -Q mode: ruler lines, the echoed prompt
+// bubble (● …), the goodbye line, and session-info footers.
+const HERMES_CHROME = [/^[─━—-]{4,}\s*─*$/, /^●/, /^Goodbye!/, /^session( id)?:/i];
+function isHermesChrome(line) {
+    return HERMES_CHROME.some((re) => re.test(line));
+}
+/**
+ * Hermes backend: per-bot profile (own soul + memories), one persistent
+ * session per channel (`--continue nopeek-<channel>`), streaming cleaned
+ * stdout lines to onChunk.
+ */
+export function hermesBrain(cfg) {
+    return (text, ctx, onChunk) => new Promise((resolvePromise) => {
+        const handle = ctx.botHandle.replace(/^@/, "");
+        const tag = `[brain:hermes:@${handle}]`;
+        const bin = resolveBin("hermes", "HERMES_BIN");
+        if (!bin) {
+            console.error(`${tag} hermes not found on PATH`);
+            resolvePromise(BRAIN_UNREACHABLE);
+            return;
+        }
+        let profile;
+        try {
+            profile = provisionHermesProfile(handle);
+        }
+        catch (err) {
+            console.error(`${tag} profile provisioning failed: ${err.message}`);
+            resolvePromise(BRAIN_UNREACHABLE);
+            return;
+        }
+        const child = spawn(bin, ["--profile", profile, "chat", "-Q", "--continue", `nopeek-${ctx.channelId}`, "-q", text], {
+            stdio: ["ignore", "pipe", "pipe"],
+            // Hermes keys everything off $HOME; point it at the Hermes install.
+            env: { ...process.env, HOME: hermesHome() },
+        });
+        let out = "";
+        let lineBuf = "";
+        let sawContent = false; // suppress leading blank lines
+        let stderr = "";
+        let settled = false;
+        const handleLine = (raw) => {
+            const line = stripAnsi(raw);
+            if (isHermesChrome(line))
+                return;
+            if (!sawContent && !line.trim())
+                return;
+            sawContent = true;
+            out += `${line}\n`;
+            onChunk?.(`${line}\n`);
+        };
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            if (lineBuf)
+                handleLine(lineBuf);
+            const reply = out.trim();
+            if (!reply) {
+                if (stderr.trim())
+                    console.error(`${tag} stderr: ${stderr.slice(0, 1000)}`);
+                resolvePromise("⚠️ My brain isn't reachable right now — Hermes has no authenticated provider on the host. Run 'hermes model' there, then message me again.");
+                return;
+            }
+            resolvePromise(reply);
+        };
+        const timer = setTimeout(() => {
+            console.error(`${tag} timed out after ${cfg.brainTimeoutMs / 1000}s, killing`);
+            child.kill("SIGKILL");
+            finish();
+        }, cfg.brainTimeoutMs);
+        child.stdout.on("data", (d) => {
+            lineBuf += d.toString();
+            const lines = lineBuf.split("\n");
+            lineBuf = lines.pop() ?? "";
+            for (const line of lines)
+                handleLine(line);
+        });
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            console.error(`${tag} spawn error: ${err.message}`);
+            if (!settled) {
+                settled = true;
+                resolvePromise(BRAIN_UNREACHABLE);
+            }
+        });
+        child.on("close", () => {
+            clearTimeout(timer);
+            finish();
+        });
+    });
+}

package/dist/bot.js

@@ -3,7 +3,7 @@
 // for decrypted messages and answers through the resolved brain. Failures are
 // isolated — a broken bot retries with backoff and never takes down its peers.
 import { NoPeek } from "@nopeek/chat";
-import { resolveBrain } from "./brain.js";
+import { FALLBACK_REPLY, resolveBrain } from "./brain.js";
 import { FileStore } from "./storage.js";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const MAX_BACKOFF_MS = 60_000;
@@ -254,6 +254,29 @@ export class BotRunner {
         // local API (PUT /brains) and the very next message uses the new one.
         const resolved = resolveBrain(this.cfg, this.info.handle);
         this.brainKind = resolved.kind;
+        // Streaming: if the brain emits chunks, open a streaming message on the
+        // FIRST chunk and forward deltas into it (typing indicator stays on until
+        // then). Deltas can arrive before the placeholder lands — chaining every
+        // append onto the open promise keeps them ordered and loses none.
+        // (Ref object rather than a `let`: TS can't see closure assignments.)
+        const streamRef = { p: null };
+        const onChunk = (delta) => {
+            if (!delta)
+                return;
+            if (!streamRef.p) {
+                try {
+                    ch.typing(false); // the live bubble replaces the typing indicator
+                }
+                catch {
+                    /* best-effort */
+                }
+                streamRef.p = ch.stream();
+                streamRef.p.catch((err) => {
+                    this.logErr(`stream open failed (falling back to a single send): ${err.message}`);
+                });
+            }
+            streamRef.p.then((s) => s.append(delta)).catch(() => { });
+        };
         let reply = "";
         try {
             reply = await resolved.brain(text, {
@@ -261,7 +284,15 @@ export class BotRunner {
                 botUserId: this.info.userId,
                 channelId: m.channelId,
                 senderUserId: m.senderUserId,
-            });
+            }, onChunk);
+        }
+        catch (err) {
+            // Brain blew up mid-stream: finalize the partial bubble with an honest
+            // error line instead of leaving a forever-blinking cursor.
+            const stream = streamRef.p ? await streamRef.p.catch(() => null) : null;
+            if (stream)
+                await stream.fail(FALLBACK_REPLY).catch(() => { });
+            throw err;
         }
         finally {
             try {
@@ -271,6 +302,13 @@ export class BotRunner {
                 /* best-effort */
             }
         }
+        const stream = streamRef.p ? await streamRef.p.catch(() => null) : null;
+        if (stream) {
+            await stream.done(reply.trim() || undefined);
+            this.handled++;
+            this.log(`${m.channelId} -> streamed reply (${reply.trim().length} chars, handled=${this.handled})`);
+            return;
+        }
         if (!reply || !reply.trim()) {
             this.log(`brain returned empty reply — ignoring`);
             return;

package/dist/brain.d.ts

@@ -5,7 +5,12 @@ export interface BrainContext {
     channelId: string;
     senderUserId: string;
 }
-export type Brain = (text: string, ctx: BrainContext) => Promise<string>;
+/**
+ * A brain answers one message. If it can stream, it calls `onChunk(delta)` as
+ * text arrives (plain text, ANSI-stripped) and STILL returns the full reply —
+ * the returned string is authoritative for the final message body.
+ */
+export type Brain = (text: string, ctx: BrainContext, onChunk?: (delta: string) => void) => Promise<string>;
 export declare const FALLBACK_REPLY = "Sorry \u2014 I hit an error processing that. Please try again.";
 export declare function stripAnsi(s: string): string;
 export interface ResolvedBrain {
@@ -14,7 +19,8 @@ export interface ResolvedBrain {
     kind: string;
 }
 /**
- * Pick the brain for one bot:
- * BRAIN_MAP[handle] (cmd beats url beats echo within an entry) > BRAIN_CMD > BRAIN_URL > echo.
+ * Pick the brain for one bot. Per-bot precedence within a BRAIN_MAP entry:
+ * cmd > url > backend (native claude/hermes/echo) > echo; then the globals:
+ * BRAIN_CMD > BRAIN_URL > echo.
  */
 export declare function resolveBrain(cfg: BridgeConfig, handle: string): ResolvedBrain;

package/dist/brain.js

@@ -6,6 +6,7 @@
 // This is how ANY agentic runtime plugs in (Hermes, OpenClaw, a curl to your
 // own service): the bridge never knows or cares what's on the other side.
 import { spawn } from "node:child_process";
+import { claudeBrain, hermesBrain } from "./backends.js";
 export const FALLBACK_REPLY = "Sorry — I hit an error processing that. Please try again.";
 // ANSI escape sequences (CSI, OSC, and lone ESC controls). Agent runtimes like
 // Hermes color their stdout; the chat must receive plain text.
@@ -22,7 +23,7 @@ export function stripAnsi(s) {
  * NOPEEK_BOT_HANDLE, NOPEEK_BOT_USER_ID, NOPEEK_CHANNEL_ID, NOPEEK_SENDER_USER_ID.
  */
 function cmdBrain(cmd, timeoutMs) {
-    return (text, ctx) => new Promise((resolvePromise) => {
+    return (text, ctx, onChunk) => new Promise((resolvePromise) => {
         const child = spawn("bash", ["-c", cmd], {
             stdio: ["pipe", "pipe", "pipe"],
             env: {
@@ -47,7 +48,18 @@ function cmdBrain(cmd, timeoutMs) {
             child.kill("SIGKILL");
             finish(stripAnsi(stdout).trim() || FALLBACK_REPLY);
         }, timeoutMs);
-        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stdout.on("data", (d) => {
+            const chunk = d.toString();
+            stdout += chunk;
+            if (onChunk) {
+                // Stream deltas as they arrive, ANSI-stripped. (A sequence split
+                // across chunk boundaries can slip through; the final reply is
+                // stripped over the WHOLE buffer, so the finalized text is clean.)
+                const clean = stripAnsi(chunk);
+                if (clean)
+                    onChunk(clean);
+            }
+        });
         child.stderr.on("data", (d) => (stderr += d.toString()));
         child.on("error", (err) => {
             clearTimeout(timer);
@@ -116,8 +128,9 @@ function urlBrain(url, timeoutMs) {
 /** Zero-config smoke test. */
 const echoBrain = async (text) => `You said: ${text}`;
 /**
- * Pick the brain for one bot:
- * BRAIN_MAP[handle] (cmd beats url beats echo within an entry) > BRAIN_CMD > BRAIN_URL > echo.
+ * Pick the brain for one bot. Per-bot precedence within a BRAIN_MAP entry:
+ * cmd > url > backend (native claude/hermes/echo) > echo; then the globals:
+ * BRAIN_CMD > BRAIN_URL > echo.
  */
 export function resolveBrain(cfg, handle) {
     const override = cfg.brainMap[handle.replace(/^@/, "")];
@@ -125,7 +138,11 @@ export function resolveBrain(cfg, handle) {
         return { brain: cmdBrain(override.cmd, cfg.brainTimeoutMs), kind: "cmd (per-bot)" };
     if (override?.url)
         return { brain: urlBrain(override.url, cfg.brainTimeoutMs), kind: "url (per-bot)" };
-    if (override?.echo)
+    if (override?.backend === "claude")
+        return { brain: claudeBrain(cfg), kind: "claude (per-bot)" };
+    if (override?.backend === "hermes")
+        return { brain: hermesBrain(cfg), kind: "hermes (per-bot)" };
+    if (override?.backend === "echo" || override?.echo)
         return { brain: echoBrain, kind: "echo (per-bot)" };
     if (cfg.brainCmd)
         return { brain: cmdBrain(cfg.brainCmd, cfg.brainTimeoutMs), kind: "cmd" };

package/dist/bridge.d.ts

@@ -1,5 +1,5 @@
 import type { BridgeConfig, BrainSpec } from "./config.js";
-export declare const VERSION = "0.2.1";
+export declare const VERSION = "0.4.0";
 export interface PairRequest {
     pairingSecret: string;
     appId: string;
@@ -10,7 +10,10 @@ export interface BrainsPatch {
     brainCmd?: string | null;
     /** Global webhook brain; null clears it. */
     brainUrl?: string | null;
-    /** Per-handle entries; a null value removes that bot's override. */
+    /** Auto-provisioner command for newly adopted bots; null clears it. */
+    brainProvisionCmd?: string | null;
+    /** Per-handle entries — {"cmd"}, {"url"}, {"backend":"claude"|"hermes"|"echo"}
+     *  or {"echo":true}; a null value removes that bot's override. */
     map?: Record<string, BrainSpec | null>;
 }
 export declare class PairError extends Error {
@@ -43,6 +46,14 @@ export declare class BridgeApp {
     statusMinimal(): Record<string, unknown>;
     statusFull(): Record<string, unknown>;
     private startBot;
+    private provisioning;
+    /**
+     * Auto-provision a brain for a newly adopted bot: run BRAIN_PROVISION_CMD
+     * (e.g. "create a Hermes profile with its own soul + memory for this handle")
+     * and store its stdout as the bot's brain command. Best-effort — on any
+     * failure the bot simply keeps the default brain.
+     */
+    private provisionBrain;
     /** Fetch the authoritative bot list and start anything we're missing. */
     private syncBots;
     private startCore;

package/dist/bridge.js

@@ -6,11 +6,14 @@
 // Pairing, unpairing and brain config all happen at runtime (from the app) and
 // persist to <home>/settings.json — no restart, no terminal.
 import { hostname } from "node:os";
+import { spawn } from "node:child_process";
 import { saveSettings } from "./config.js";
 import { BotRunner } from "./bot.js";
 import { ControlSocket } from "./control.js";
 import { resolveBrain } from "./brain.js";
-export const VERSION = "0.2.1";
+import { provisionSoul } from "./backends.js";
+import { isBrainBackend } from "./config.js";
+export const VERSION = "0.4.0";
 export class PairError extends Error {
     code;
     constructor(code, message) {
@@ -99,6 +102,8 @@ export class BridgeApp {
             this.cfg.brainCmd = patch.brainCmd || null;
         if (patch.brainUrl !== undefined)
             this.cfg.brainUrl = patch.brainUrl || null;
+        if (patch.brainProvisionCmd !== undefined)
+            this.cfg.brainProvisionCmd = patch.brainProvisionCmd || null;
         if (patch.map) {
             for (const [rawHandle, spec] of Object.entries(patch.map)) {
                 const handle = rawHandle.replace(/^@/, "");
@@ -111,6 +116,19 @@ export class BridgeApp {
                 else if (typeof spec.url === "string" && spec.url.trim()) {
                     this.cfg.brainMap[handle] = { url: spec.url.trim() };
                 }
+                else if (isBrainBackend(spec.backend)) {
+                    this.cfg.brainMap[handle] = { backend: spec.backend };
+                    // Native backends personify through a soul file — make sure it
+                    // exists the moment the backend is chosen (idempotent).
+                    if (spec.backend !== "echo") {
+                        try {
+                            provisionSoul(handle, this.cfg.homeDir);
+                        }
+                        catch (err) {
+                            console.error(`[bridge] soul provisioning for @${handle} failed: ${err.message}`);
+                        }
+                    }
+                }
                 else if (spec.echo === true) {
                     this.cfg.brainMap[handle] = { echo: true };
                 }
@@ -146,6 +164,7 @@ export class BridgeApp {
                         ? { url: this.cfg.brainUrl }
                         : { echo: true },
                 map: this.cfg.brainMap,
+                provisionCmd: this.cfg.brainProvisionCmd,
             },
             bots: [...this.bots.values()].map((b) => ({
                 handle: b.info.handle,
@@ -163,6 +182,59 @@ export class BridgeApp {
         const runner = new BotRunner(info, this.cfg);
         this.bots.set(info.userId, runner);
         runner.start(); // background; failures are isolated inside the runner
+        void this.provisionBrain(info); // background; bot echoes until it lands
+    }
+    // A handle is provisioned at most once per process; the persisted BRAIN_MAP
+    // entry prevents re-provisioning across restarts.
+    provisioning = new Set();
+    /**
+     * Auto-provision a brain for a newly adopted bot: run BRAIN_PROVISION_CMD
+     * (e.g. "create a Hermes profile with its own soul + memory for this handle")
+     * and store its stdout as the bot's brain command. Best-effort — on any
+     * failure the bot simply keeps the default brain.
+     */
+    async provisionBrain(info) {
+        const cmd = this.cfg.brainProvisionCmd;
+        const handle = info.handle.replace(/^@/, "");
+        if (!cmd || this.cfg.brainMap[handle] || this.provisioning.has(handle))
+            return;
+        this.provisioning.add(handle);
+        console.log(`[provision:@${handle}] running brain provisioner`);
+        const out = await new Promise((resolvePromise) => {
+            const child = spawn("bash", ["-c", cmd], {
+                stdio: ["ignore", "pipe", "pipe"],
+                env: { ...process.env, NOPEEK_BOT_HANDLE: handle, NOPEEK_BOT_USER_ID: info.userId },
+            });
+            let stdout = "";
+            let stderr = "";
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                resolvePromise(null);
+            }, 120_000);
+            child.stdout.on("data", (d) => (stdout += d.toString()));
+            child.stderr.on("data", (d) => (stderr += d.toString()));
+            child.on("error", () => {
+                clearTimeout(timer);
+                resolvePromise(null);
+            });
+            child.on("close", (code) => {
+                clearTimeout(timer);
+                if (code !== 0) {
+                    console.error(`[provision:@${handle}] exit ${code}. stderr: ${stderr.slice(0, 1000)}`);
+                    resolvePromise(null);
+                    return;
+                }
+                resolvePromise(stdout.trim());
+            });
+        });
+        if (!out) {
+            console.error(`[provision:@${handle}] provisioner produced no brain command — bot keeps the default brain`);
+            return;
+        }
+        // Use the LAST non-empty stdout line: provisioners may log progress above it.
+        const brainCmd = out.split("\n").map((l) => l.trim()).filter(Boolean).pop();
+        this.setBrains({ map: { [handle]: { cmd: brainCmd } } });
+        console.log(`[provision:@${handle}] brain provisioned`);
     }
     /** Fetch the authoritative bot list and start anything we're missing. */
     async syncBots() {

package/dist/cli.js

@@ -51,7 +51,7 @@ if (sub === "status") {
 }
 if (sub === "install") {
     try {
-        await installService(cfg);
+        await installService(cfg, rest.includes("--no-open"));
     }
     catch (err) {
         console.error(`[install] ${err.message}`);

package/dist/config.d.ts

@@ -1,10 +1,16 @@
+/** Built-in native backends (see backends.ts): claude = Claude Code headless,
+ *  hermes = per-bot Hermes profile, echo = smoke test. */
+export type BrainBackend = "claude" | "hermes" | "echo";
 /** Per-bot brain override, keyed by bot handle in BRAIN_MAP.
+ *  `backend` selects a native built-in (claude/hermes/echo);
  *  `echo: true` pins the bot to echo mode even when a global brain is set. */
 export interface BrainSpec {
     cmd?: string;
     url?: string;
+    backend?: BrainBackend;
     echo?: boolean;
 }
+export declare function isBrainBackend(v: unknown): v is BrainBackend;
 export interface BridgeConfig {
     /** NoPeek API base, e.g. https://d3qweh72vesa98.cloudfront.net */
     apiUrl: string;
@@ -18,7 +24,16 @@ export interface BridgeConfig {
     brainUrl: string | null;
     /** Per-handle overrides: { "<handle>": {"cmd": "…"} | {"url": "…"} }. */
     brainMap: Record<string, BrainSpec>;
+    /**
+     * Auto-provisioner: run ONCE for each adopted bot that has no BRAIN_MAP
+     * entry (env: NOPEEK_BOT_HANDLE, NOPEEK_BOT_USER_ID). Its trimmed stdout
+     * becomes that bot's brain command — e.g. a script that creates a fresh
+     * Hermes profile (own soul + memory) per bot and prints how to invoke it.
+     */
+    brainProvisionCmd: string | null;
     brainTimeoutMs: number;
+    /** Where `install` sends the user to finish setup (opened in the browser). */
+    appUrl: string;
     /** Local control API port (status + pairing + brain config, loopback only). */
     port: number;
     /** Where per-bot device identity/key stores live. */
@@ -30,10 +45,11 @@ export interface BridgeConfig {
     declineMessage: string | null;
 }
 export declare const DEFAULT_API_URL = "https://d3qweh72vesa98.cloudfront.net";
+export declare const DEFAULT_APP_URL = "https://d32w3to73s0pu5.cloudfront.net/messenger/";
 export declare const DEFAULT_PORT = 8790;
 export declare const DEFAULT_BRAIN_TIMEOUT_MS = 180000;
 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.";
+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\"}|\n                           {\"backend\":\"claude\"|\"hermes\"|\"echo\"}}              (env BRAIN_MAP)\n  --brain-provision-cmd <cmd>  Run once per new bot; stdout becomes its brain command\n                           (env BRAIN_PROVISION_CMD \u2014 e.g. a script that creates a\n                           fresh Hermes profile with its own soul + memory)\n  --app-url <url>          App opened after install                     (env NOPEEK_APP_URL)\n  --no-open                install: don't open the app in the browser\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;

package/dist/config.js

@@ -9,7 +9,11 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from "
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { parseArgs } from "node:util";
+export function isBrainBackend(v) {
+    return v === "claude" || v === "hermes" || v === "echo";
+}
 export const DEFAULT_API_URL = "https://d3qweh72vesa98.cloudfront.net";
+export const DEFAULT_APP_URL = "https://d32w3to73s0pu5.cloudfront.net/messenger/";
 export const DEFAULT_PORT = 8790;
 export const DEFAULT_BRAIN_TIMEOUT_MS = 180_000;
 export function defaultHomeDir() {
@@ -22,8 +26,11 @@ const CLI_OPTIONS = {
     "brain-cmd": { type: "string" },
     "brain-url": { type: "string" },
     "brain-map": { type: "string" },
+    "brain-provision-cmd": { type: "string" },
     "brain-timeout-ms": { type: "string" },
     "decline-message": { type: "string" },
+    "app-url": { type: "string" },
+    "no-open": { type: "boolean" },
     port: { type: "string" },
     "data-dir": { type: "string" },
     home: { type: "string" },
@@ -38,8 +45,10 @@ const FLAG_TO_KEY = {
     "brain-cmd": "BRAIN_CMD",
     "brain-url": "BRAIN_URL",
     "brain-map": "BRAIN_MAP",
+    "brain-provision-cmd": "BRAIN_PROVISION_CMD",
     "brain-timeout-ms": "BRAIN_TIMEOUT_MS",
     "decline-message": "NOPEEK_DECLINE_MESSAGE",
+    "app-url": "NOPEEK_APP_URL",
     port: "NOPEEK_BRIDGE_PORT",
     "data-dir": "NOPEEK_BRIDGE_DATA_DIR",
     home: "NOPEEK_BRIDGE_HOME",
@@ -62,7 +71,13 @@ Options:
   --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-map <json>       Per-bot overrides {"<handle>":{"cmd":"…"}|{"url":"…"}|
+                           {"backend":"claude"|"hermes"|"echo"}}              (env BRAIN_MAP)
+  --brain-provision-cmd <cmd>  Run once per new bot; stdout becomes its brain command
+                           (env BRAIN_PROVISION_CMD — e.g. a script that creates a
+                           fresh Hermes profile with its own soul + memory)
+  --app-url <url>          App opened after install                     (env NOPEEK_APP_URL)
+  --no-open                install: don't open the app in the browser
   --brain-timeout-ms <ms>  Brain timeout, default ${DEFAULT_BRAIN_TIMEOUT_MS}          (env BRAIN_TIMEOUT_MS)
   --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)
@@ -110,13 +125,18 @@ function parseBrainMap(raw) {
         if (typeof spec !== "object" || spec === null) {
             throw new Error(`BRAIN_MAP["${handle}"] must be {"cmd":"…"} or {"url":"…"}`);
         }
-        const { cmd, url } = spec;
-        if (typeof cmd !== "string" && typeof url !== "string") {
-            throw new Error(`BRAIN_MAP["${handle}"] needs a "cmd" or "url" string`);
+        const { cmd, url, backend, echo } = spec;
+        if (backend !== undefined && !isBrainBackend(backend)) {
+            throw new Error(`BRAIN_MAP["${handle}"].backend must be "claude", "hermes" or "echo"`);
+        }
+        if (typeof cmd !== "string" && typeof url !== "string" && !isBrainBackend(backend) && echo !== true) {
+            throw new Error(`BRAIN_MAP["${handle}"] needs a "cmd", "url" or "backend" ("claude"|"hermes"|"echo")`);
         }
         out[handle.replace(/^@/, "")] = {
             ...(typeof cmd === "string" ? { cmd } : {}),
             ...(typeof url === "string" ? { url } : {}),
+            ...(isBrainBackend(backend) ? { backend } : {}),
+            ...(echo === true ? { echo: true } : {}),
         };
     }
     return out;
@@ -179,11 +199,13 @@ export function loadConfig(argv = process.argv.slice(2)) {
         brainCmd: get("brain-cmd") ?? null,
         brainUrl: get("brain-url") ?? null,
         brainMap: parseBrainMap(get("brain-map")),
+        brainProvisionCmd: get("brain-provision-cmd") ?? null,
         brainTimeoutMs,
         port,
         dataDir,
         homeDir,
         declineMessage: get("decline-message") ?? null,
+        appUrl: get("app-url") ?? DEFAULT_APP_URL,
     };
 }
 /**
@@ -200,6 +222,7 @@ export function saveSettings(cfg) {
         ...(cfg.brainCmd ? { BRAIN_CMD: cfg.brainCmd } : {}),
         ...(cfg.brainUrl ? { BRAIN_URL: cfg.brainUrl } : {}),
         ...(Object.keys(cfg.brainMap).length ? { BRAIN_MAP: JSON.stringify(cfg.brainMap) } : {}),
+        ...(cfg.brainProvisionCmd ? { BRAIN_PROVISION_CMD: cfg.brainProvisionCmd } : {}),
         ...(cfg.declineMessage ? { NOPEEK_DECLINE_MESSAGE: cfg.declineMessage } : {}),
     };
     const path = settingsPath(cfg.homeDir);

package/dist/service.d.ts

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

package/dist/service.js

@@ -41,7 +41,7 @@ function launchctl(args, ignoreFailure = false) {
             throw err;
     }
 }
-export async function installService(cfg) {
+export async function installService(cfg, noOpen = false) {
     if (process.platform !== "darwin" && process.platform !== "linux") {
         throw new Error(`automatic service install supports macOS and Linux. On this platform, run the bridge with any process manager:\n  nopeek-agent-bridge run`);
     }
@@ -122,9 +122,21 @@ WantedBy=default.target
     }
     console.log(`
 Done. Next step — in the NoPeek app on THIS computer:
-  Contacts -> My Bots -> Connect this computer
+  Contacts -> My Bots -> "Run your bots on this computer" -> Connect
 Pairing, choosing your agent (Hermes, …) and everything else happens in the app.
 Logs: ${logFile}`);
+    // Take the user straight to the app: sign in once, tap Connect, done.
+    // (Sessions persist, so next time this is automatic.)
+    if (!noOpen) {
+        const opener = process.platform === "darwin" ? "open" : "xdg-open";
+        try {
+            execFileSync(opener, [cfg.appUrl], { stdio: "ignore" });
+            console.log(`[install] opened ${cfg.appUrl}`);
+        }
+        catch {
+            console.log(`[install] open ${cfg.appUrl} in your browser to finish setup`);
+        }
+    }
 }
 export function uninstallService() {
     if (process.platform === "darwin") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nopeek/agent-bridge",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Run your own agents as E2EE NoPeek bots. Pairs with a one-time code, runs every bot you own, and pipes messages to any command or webhook.",
   "type": "module",
   "license": "MIT",