@nopeek/agent-bridge 0.7.10 → 0.7.11

package/README.md

@@ -41,6 +41,9 @@ The `npr_…` code comes from Settings → Connect your computer (bots) in the a
 
 Hermes brains prefer the local agent API (`HERMES_API_URL`, default
 `http://127.0.0.1:8642`) when `/health` is up, and fall back to `hermes chat`.
+While Hermes is working, the bot posts Telegram-style tool lines a few at a
+time (read file, patch, skill, memory). A quiet gap starts a new message.
+The final reply is the answer plus a short recap when tools were used.
 Idle kill waits for **no output and no CPU** (default 15 min). Authenticated
 `GET /status` includes `bridge`, `bots[]` (each with `lastTurn`), `hermesApi`,
 and `lastTurn`. See `docs/HERMES-BRAIN-PLAN.md`.

package/dist/backends.js

@@ -16,7 +16,7 @@ import { createHash } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
-import { stripAnsi } from "./brain.js";
+import { asHooks, stripAnsi } from "./brain.js";
 import { hermesHttpBrain, probeHermesApi } from "./hermes-http.js";
 const BRAIN_UNREACHABLE = "⚠️ I couldn't reach my brain just now — please try again in a moment.";
 // ------------------------------------------------------------------ souls ----
@@ -224,7 +224,8 @@ function runClaudeOnce(bin, args, text, cwd, timeoutMs, tag, onDelta) {
  * host powers from wherever the bridge happens to run.
  */
 export function claudeBrain(cfg) {
-    return async (text, ctx, onChunk) => {
+    return async (text, ctx, hooks) => {
+        const { onChunk } = asHooks(hooks);
         const bin = resolveBin("claude", "CLAUDE_BIN");
         if (!bin) {
             console.error(`[brain:claude:@${ctx.botHandle}] claude not found on PATH`);
@@ -302,8 +303,15 @@ you reply. Your replies are chat messages — every word you print is sent verba
 ## Guardrails
 - Never expose secrets, keys, or tokens.
 - Confirm before destructive or outward-facing actions.
-- Report honestly — if something failed, say so.
+- Report honestly. If something failed, say so.
 - If a request is far outside your purpose, say so briefly and offer what you can do.
+
+## After tool work
+When you used tools this turn (read or wrote files, ran commands, changed skills, saved memory), end with a short recap:
+- What was going on (one line).
+- What you did (one or two lines).
+- Result (one line).
+Skip the recap for simple conversation with no tools.
 `;
 /**
  * Create (or reuse) the bot's isolated Hermes profile: its own SOUL.md and
@@ -527,7 +535,8 @@ function hermesCliBrain(cfg) {
             finish();
         });
     });
-    return async (text, ctx, onChunk) => {
+    return async (text, ctx, hooks) => {
+        const { onChunk } = asHooks(hooks);
         const handle = ctx.botHandle.replace(/^@/, "");
         const tag = `[brain:hermes:@${handle}]`;
         if (!resolveBin("hermes", "HERMES_BIN")) {
@@ -606,15 +615,15 @@ function hermesCliBrain(cfg) {
 export function hermesBrain(cfg) {
     const cli = hermesCliBrain(cfg);
     const http = hermesHttpBrain(cfg);
-    return async (text, ctx, onChunk) => {
+    return async (text, ctx, hooks) => {
         const health = await probeHermesApi(cfg);
         if (health.ok) {
-            const reply = await http(text, ctx, onChunk);
+            const reply = await http(text, ctx, hooks);
             if (reply)
                 return reply;
             console.error(`[brain:hermes:@${ctx.botHandle.replace(/^@/, "")}] API returned empty — falling back to CLI`);
         }
-        return cli(text, ctx, onChunk);
+        return cli(text, ctx, hooks);
     };
 }
 export function hermesHttpOnlyBrain(cfg) {

package/dist/bot.js

@@ -7,6 +7,7 @@ import { isChannelMode } from "./control.js";
 import { FALLBACK_REPLY, resolveBrain } from "./brain.js";
 import { beginTurn, finishTurn, lastTurnFor } from "./last-turn.js";
 import { FileStore } from "./storage.js";
+import { ToolProgressFlusher } from "./tool-progress.js";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const MAX_BACKOFF_MS = 60_000;
 // Owner-membership answers are cached per channel for a short window; a
@@ -551,16 +552,20 @@ export class BotRunner {
         // 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 stopTyping = () => {
+            try {
+                ch.typing(false);
+            }
+            catch {
+                /* best-effort */
+            }
+        };
         const onChunk = (delta) => {
             if (!delta)
                 return;
+            void progress.flush();
             if (!streamRef.p) {
-                try {
-                    ch.typing(false); // the live bubble replaces the typing indicator
-                }
-                catch {
-                    /* best-effort */
-                }
+                stopTyping();
                 streamRef.p = ch.stream();
                 streamRef.p.catch((err) => {
                     this.notePostFailure(m.channelId, err);
@@ -569,6 +574,10 @@ export class BotRunner {
             }
             streamRef.p.then((s) => s.append(delta)).catch(() => { });
         };
+        const progress = new ToolProgressFlusher(async (body) => {
+            stopTyping();
+            await ch.send({ text: body });
+        });
         let reply = "";
         const turn = beginTurn(this.info.handle, m.channelId, resolved.kind);
         try {
@@ -577,7 +586,7 @@ export class BotRunner {
                 botUserId: this.info.userId,
                 channelId: m.channelId,
                 senderUserId: m.senderUserId,
-            }, onChunk);
+            }, { onChunk, onTool: (ev) => progress.push(ev) });
             const trimmed = reply.trim();
             const timedOut = /went quiet for over \d+s/i.test(trimmed);
             finishTurn(turn, {
@@ -591,6 +600,7 @@ export class BotRunner {
             finishTurn(turn, { ok: false, error: err.message, timedOut: false });
             // Brain blew up mid-stream: finalize the partial bubble with an honest
             // error line instead of leaving a forever-blinking cursor.
+            await progress.flush();
             const stream = streamRef.p ? await streamRef.p.catch(() => null) : null;
             if (stream)
                 await stream.fail(FALLBACK_REPLY).catch(() => { });
@@ -604,6 +614,7 @@ export class BotRunner {
                 /* best-effort */
             }
         }
+        await progress.flush();
         const stream = streamRef.p ? await streamRef.p.catch(() => null) : null;
         if (stream) {
             await stream.done(reply.trim() || undefined);

package/dist/brain.d.ts

@@ -1,4 +1,5 @@
 import type { BridgeConfig } from "./config.js";
+import type { ToolProgressEvent } from "./tool-progress.js";
 export interface BrainContext {
     botHandle: string;
     botUserId: string;
@@ -9,8 +10,14 @@ export interface BrainContext {
  * 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.
+ * `onTool` is optional: Hermes HTTP uses it for live tool-progress lines.
  */
-export type Brain = (text: string, ctx: BrainContext, onChunk?: (delta: string) => void) => Promise<string>;
+export type BrainHooks = {
+    onChunk?: (delta: string) => void;
+    onTool?: (ev: ToolProgressEvent) => void;
+};
+export type Brain = (text: string, ctx: BrainContext, hooks?: BrainHooks | ((delta: string) => void)) => Promise<string>;
+export declare function asHooks(hooks?: BrainHooks | ((delta: string) => void)): BrainHooks;
 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 {

package/dist/brain.js

@@ -7,6 +7,13 @@
 // own service): the bridge never knows or cares what's on the other side.
 import { spawn } from "node:child_process";
 import { claudeBrain, hermesBrain, hermesHttpOnlyBrain } from "./backends.js";
+export function asHooks(hooks) {
+    if (!hooks)
+        return {};
+    if (typeof hooks === "function")
+        return { onChunk: hooks };
+    return hooks;
+}
 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.
@@ -23,7 +30,8 @@ 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, onChunk) => new Promise((resolvePromise) => {
+    return (text, ctx, hooks) => new Promise((resolvePromise) => {
+        const { onChunk } = asHooks(hooks);
         const child = spawn("bash", ["-c", cmd], {
             stdio: ["pipe", "pipe", "pipe"],
             env: {

package/dist/hermes-http.d.ts

@@ -1,5 +1,5 @@
 import type { BridgeConfig } from "./config.js";
-import type { Brain } from "./brain.js";
+import { type Brain } from "./brain.js";
 export interface HermesApiHealth {
     ok: boolean;
     url: string;

package/dist/hermes-http.js

@@ -1,3 +1,5 @@
+import { asHooks } from "./brain.js";
+import { RECAP_HINT } from "./tool-progress.js";
 let lastHealth = null;
 const HEALTH_TTL_MS = 15_000;
 export function lastHermesApiHealth() {
@@ -35,16 +37,20 @@ export async function probeHermesApi(cfg, force = false) {
  * Session continuity: X-Hermes-Session-Key = nopeek-<channelId> (stable per chat).
  */
 export function hermesHttpBrain(cfg) {
-    return async (text, ctx, onChunk) => {
+    return async (text, ctx, hooks) => {
+        const { onChunk, onTool } = asHooks(hooks);
         const handle = ctx.botHandle.replace(/^@/, "");
         const tag = `[brain:hermes-http:@${handle}]`;
         const url = cfg.hermesApiUrl.replace(/\/+$/, "");
         const headers = {
             "content-type": "application/json",
-            "X-Hermes-Session-Key": `nopeek-${ctx.channelId}`,
         };
-        if (cfg.hermesApiKey)
+        // Hermes rejects X-Hermes-Session-Key with 403 unless API_SERVER_KEY is set.
+        // Without a key, skip the header so the turn still runs (no session memory).
+        if (cfg.hermesApiKey) {
             headers.authorization = `Bearer ${cfg.hermesApiKey}`;
+            headers["X-Hermes-Session-Key"] = `nopeek-${ctx.channelId}`;
+        }
         // Idle abort — same rule as the CLI path. A wall-clock timeout on the
         // whole POST would kill a healthy 20-minute agentic turn. Any SSE byte
         // (token, keepalive, tool-progress) resets the idle timer.
@@ -66,7 +72,10 @@ export function hermesHttpBrain(cfg) {
                 body: JSON.stringify({
                     model: "hermes-agent",
                     stream: true,
-                    messages: [{ role: "user", content: text }],
+                    messages: [
+                        { role: "system", content: RECAP_HINT },
+                        { role: "user", content: text },
+                    ],
                 }),
                 signal: controller.signal,
             });
@@ -98,29 +107,40 @@ export function hermesHttpBrain(cfg) {
                     break;
                 armIdle();
                 buf += decoder.decode(value, { stream: true });
-                const lines = buf.split("\n");
-                buf = lines.pop() ?? "";
-                for (const line of lines) {
-                    const trimmed = line.trim();
-                    if (!trimmed.startsWith("data:"))
-                        continue;
-                    const payload = trimmed.slice(5).trim();
-                    if (!payload || payload === "[DONE]")
+                const frames = buf.split("\n\n");
+                buf = frames.pop() ?? "";
+                for (const frame of frames) {
+                    const ev = parseSseFrame(frame);
+                    if (!ev)
                         continue;
-                    let parsed;
-                    try {
-                        parsed = JSON.parse(payload);
-                    }
-                    catch {
+                    if (ev.event === "hermes.tool.progress") {
+                        const tool = asToolProgress(ev.data);
+                        if (tool)
+                            onTool?.(tool);
                         continue;
                     }
-                    const delta = extractDelta(parsed);
+                    const delta = extractDelta(ev.data);
                     if (!delta)
                         continue;
                     reply += delta;
                     onChunk?.(delta);
                 }
             }
+            if (buf.trim()) {
+                const ev = parseSseFrame(buf);
+                if (ev?.event === "hermes.tool.progress") {
+                    const tool = asToolProgress(ev.data);
+                    if (tool)
+                        onTool?.(tool);
+                }
+                else if (ev) {
+                    const delta = extractDelta(ev.data);
+                    if (delta) {
+                        reply += delta;
+                        onChunk?.(delta);
+                    }
+                }
+            }
         }
         catch (err) {
             const msg = err.message || "";
@@ -135,6 +155,44 @@ export function hermesHttpBrain(cfg) {
         return reply.trim();
     };
 }
+function parseSseFrame(frame) {
+    let event = "message";
+    const dataLines = [];
+    for (const raw of frame.split("\n")) {
+        const line = raw.replace(/\r$/, "");
+        if (!line || line.startsWith(":"))
+            continue;
+        if (line.startsWith("event:"))
+            event = line.slice(6).trim();
+        else if (line.startsWith("data:"))
+            dataLines.push(line.slice(5).trimStart());
+    }
+    if (dataLines.length === 0)
+        return null;
+    const payload = dataLines.join("\n");
+    if (!payload || payload === "[DONE]")
+        return null;
+    try {
+        return { event, data: JSON.parse(payload) };
+    }
+    catch {
+        return { event, data: payload };
+    }
+}
+function asToolProgress(data) {
+    if (!data || typeof data !== "object")
+        return null;
+    const obj = data;
+    const tool = typeof obj.tool === "string" ? obj.tool : typeof obj.name === "string" ? obj.name : "";
+    if (!tool)
+        return null;
+    return {
+        tool,
+        emoji: typeof obj.emoji === "string" ? obj.emoji : undefined,
+        label: typeof obj.label === "string" ? obj.label : undefined,
+        status: typeof obj.status === "string" ? obj.status : "running",
+    };
+}
 function extractDelta(parsed) {
     if (!parsed || typeof parsed !== "object")
         return "";
@@ -143,8 +201,6 @@ function extractDelta(parsed) {
     const fromChoice = choice?.delta?.content ?? choice?.message?.content;
     if (typeof fromChoice === "string")
         return fromChoice;
-    // Hermes also emits custom SSE tool-progress events; ignore those for the
-    // chat body (they keep the HTTP connection alive, which is the point).
     if (typeof obj.data?.content === "string")
         return obj.data.content;
     if (typeof obj.data?.text === "string")

package/dist/tool-progress.d.ts

@@ -0,0 +1,29 @@
+export type ToolProgressEvent = {
+    tool: string;
+    emoji?: string;
+    label?: string;
+    status?: string;
+};
+/** One Telegram-style line. Running events only; completed is silent. */
+export declare function formatToolLine(ev: ToolProgressEvent): string | null;
+export type ProgressSender = (text: string) => Promise<void>;
+/**
+ * Collect tool lines and flush them as short chat messages.
+ * Flush when we have `maxLines` tools, or after `gapMs` of quiet.
+ */
+export declare class ToolProgressFlusher {
+    private readonly send;
+    private readonly gapMs;
+    private readonly maxLines;
+    private lines;
+    private timer;
+    private chain;
+    private seen;
+    constructor(send: ProgressSender, gapMs?: number, maxLines?: number);
+    get pending(): number;
+    push(ev: ToolProgressEvent): void;
+    flush(): Promise<void>;
+    private arm;
+}
+/** Hint so Hermes ends a tool-using turn with a recap, like Telegram. */
+export declare const RECAP_HINT = "When this turn used tools (read/write files, commands, skills, memory), end your reply with a short recap: what was going on, what you did, and the result. Skip the recap for simple chat with no tools. No em dashes.";

package/dist/tool-progress.js

@@ -0,0 +1,105 @@
+// Telegram-style tool progress for NoPeek bots.
+//
+// Hermes emits `hermes.tool.progress` SSE events while it works. Telegram
+// already shows those as short status messages (a few tools, then a new
+// message after a quiet gap). We do the same in the encrypted chat so the
+// human can see the bot is actually taking action.
+const FALLBACK_EMOJI = {
+    read_file: "📖",
+    write_file: "✍️",
+    patch: "🔧",
+    search_files: "🔎",
+    terminal: "💻",
+    web_search: "🔍",
+    web_extract: "📄",
+    web_crawl: "🕸️",
+    memory: "🧠",
+    skill_view: "📘",
+    skill_manage: "🧩",
+    skills_list: "📚",
+    todo: "✅",
+    execute_code: "🐍",
+    delegate_task: "👥",
+    cronjob: "⏰",
+    process: "⚙️",
+};
+/** One Telegram-style line. Running events only; completed is silent. */
+export function formatToolLine(ev) {
+    if (ev.status && ev.status !== "running")
+        return null;
+    const tool = (ev.tool || "").trim();
+    if (!tool || tool.startsWith("_"))
+        return null;
+    const emoji = (ev.emoji || FALLBACK_EMOJI[tool] || "⚡").trim() || "⚡";
+    const label = tidyLabel(ev.label);
+    if (label)
+        return `${emoji} ${tool}: "${label}"`;
+    return `${emoji} ${tool}...`;
+}
+function tidyLabel(raw) {
+    if (!raw)
+        return "";
+    const s = raw.replace(/\s+/g, " ").trim();
+    if (!s)
+        return "";
+    return s.length > 80 ? `${s.slice(0, 77)}...` : s;
+}
+/**
+ * Collect tool lines and flush them as short chat messages.
+ * Flush when we have `maxLines` tools, or after `gapMs` of quiet.
+ */
+export class ToolProgressFlusher {
+    send;
+    gapMs;
+    maxLines;
+    lines = [];
+    timer = null;
+    chain = Promise.resolve();
+    seen = new Set();
+    constructor(send, gapMs = 2200, maxLines = 4) {
+        this.send = send;
+        this.gapMs = gapMs;
+        this.maxLines = maxLines;
+    }
+    get pending() {
+        return this.lines.length;
+    }
+    push(ev) {
+        const line = formatToolLine(ev);
+        if (!line)
+            return;
+        if (this.lines[this.lines.length - 1] === line)
+            return;
+        if (this.seen.has(line) && this.lines.includes(line))
+            return;
+        this.seen.add(line);
+        this.lines.push(line);
+        if (this.lines.length >= this.maxLines) {
+            void this.flush();
+            return;
+        }
+        this.arm();
+    }
+    async flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.lines.length === 0)
+            return;
+        const text = this.lines.join("\n");
+        this.lines = [];
+        this.chain = this.chain.then(() => this.send(text).catch(() => { }));
+        await this.chain;
+    }
+    arm() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.flush();
+        }, this.gapMs);
+    }
+}
+/** Hint so Hermes ends a tool-using turn with a recap, like Telegram. */
+export const RECAP_HINT = "When this turn used tools (read/write files, commands, skills, memory), end your reply with a short recap: what was going on, what you did, and the result. Skip the recap for simple chat with no tools. No em dashes.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nopeek/agent-bridge",
-  "version": "0.7.10",
+  "version": "0.7.11",
   "description": "Run your own agents as E2EE NoPeek bots. Pairs with one-time codes (multiple accounts per computer), runs every bot each account owns, and pipes messages to any command or webhook.",
   "type": "module",
   "license": "MIT",
@@ -22,8 +22,15 @@
   "engines": {
     "node": ">=22"
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "tsc -p tsconfig.json",
+    "start": "node dist/cli.js",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
   "dependencies": {
-    "@nopeek/chat": "^0.2.4"
+    "@nopeek/chat": "workspace:^0.2.4"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
@@ -40,11 +47,5 @@
   ],
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "start": "node dist/cli.js",
-    "dev": "tsx src/cli.ts",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
   }
-}
+}