@nopeek/agent-bridge 0.7.10 → 0.7.14

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 edits one Telegram-style progress bubble
+(read file, patch, skill, memory). New tools update that bubble instead of
+stacking under a running summary. The recap is a separate message underneath.
 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`.
@@ -76,6 +79,7 @@ Context is passed as environment variables:
 | `NOPEEK_BOT_USER_ID` | user id of the bot |
 | `NOPEEK_CHANNEL_ID` | channel the message arrived in |
 | `NOPEEK_SENDER_USER_ID` | who sent the message |
+| `NOPEEK_FILES` | JSON array of decrypted inbound files (`path`, `name`, `contentType`, `size`, `kind`) |
 
 Examples:
 
@@ -106,7 +110,8 @@ Content-Type: application/json
   "botHandle": "weatherbot",
   "botUserId": "usr_…",
   "channelId": "ch_…",
-  "senderUserId": "usr_…"
+  "senderUserId": "usr_…",
+  "files": []
 }
 ```
 

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,8 @@ 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 { TurnPublisher } from "./tool-progress.js";
+import { buildInboundPrompt, describeStructured, hasInboundWork, isControlType, parseAttachments, saveInboundFiles, } from "./inbound-files.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
@@ -456,8 +458,11 @@ export class BotRunner {
             }
             return;
         }
-        if (m.body?.type !== "text" || typeof m.body.text !== "string" || !m.body.text.trim())
+        const body = m.body;
+        if (!body || isControlType(body.type) || !hasInboundWork(body))
             return;
+        const attachments = parseAttachments(body);
+        const caption = typeof body.text === "string" ? body.text : "";
         // OWNER-PRESENT POLICY: in a multi-party channel (anything but a direct
         // chat), a non-owner sender may use the bot ONLY while the bot's owner is
         // also a member of that channel. Owner absent → completely silent (no
@@ -515,7 +520,7 @@ export class BotRunner {
         // predictable: mention-only means even the owner must @mention there.
         // DIRECT channels always behave as "everyone" (a DM with the bot is always
         // for the bot).
-        let text = m.body.text;
+        let text = caption;
         if (ch.record.kind !== "direct" && ch.record.kind !== "dm") {
             const mode = this.channelModes.get(m.channelId) ?? "everyone";
             if (mode === "off") {
@@ -533,6 +538,26 @@ export class BotRunner {
                 text = stripped;
             }
         }
+        let files = [];
+        const failures = [];
+        const previews = [];
+        if (attachments.length) {
+            const saved = await saveInboundFiles(async (att) => {
+                const blob = await ch.fetchAttachment(att);
+                return Buffer.from(await blob.arrayBuffer());
+            }, attachments, m.messageId);
+            files = saved.files;
+            failures.push(...saved.failures);
+            previews.push(...saved.previews);
+            this.log(`${m.channelId} inbound ${body.type}: ${files.length} file(s) saved` +
+                (failures.length ? `, ${failures.length} failed` : ""));
+        }
+        const structured = describeStructured(body);
+        text = buildInboundPrompt({ caption: text, files, structured, failures });
+        if (previews.length)
+            text = `${previews.join("\n\n")}\n\n${text}`;
+        if (!text.trim())
+            return;
         this.log(`${m.channelId} <- ${m.senderUserId}: ${text.slice(0, 120)}`);
         ch.markRead(m.messageId).catch(() => { });
         try {
@@ -545,30 +570,28 @@ 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.notePostFailure(m.channelId, err);
-                    this.logErr(`stream open failed (falling back to a single send): ${err.message}`);
-                });
+        // Telegram-style turn: tool lines edit one live bubble; commentary
+        // between tool batches is posted in place; leftover recap goes last.
+        const stopTyping = () => {
+            try {
+                ch.typing(false);
+            }
+            catch {
+                /* best-effort */
             }
-            streamRef.p.then((s) => s.append(delta)).catch(() => { });
         };
+        const published = new TurnPublisher({
+            stream: () => ch.stream(),
+            send: async (body) => {
+                await ch.send({ text: body });
+            },
+        }, {
+            stopTyping,
+            onStreamError: (err) => {
+                this.notePostFailure(m.channelId, err);
+                this.logErr(`stream open failed (falling back to a single send): ${err.message}`);
+            },
+        });
         let reply = "";
         const turn = beginTurn(this.info.handle, m.channelId, resolved.kind);
         try {
@@ -577,7 +600,8 @@ export class BotRunner {
                 botUserId: this.info.userId,
                 channelId: m.channelId,
                 senderUserId: m.senderUserId,
-            }, onChunk);
+                ...(files.length ? { files } : {}),
+            }, { onChunk: (delta) => published.onChunk(delta), onTool: (ev) => published.onTool(ev) });
             const trimmed = reply.trim();
             const timedOut = /went quiet for over \d+s/i.test(trimmed);
             finishTurn(turn, {
@@ -591,9 +615,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.
-            const stream = streamRef.p ? await streamRef.p.catch(() => null) : null;
-            if (stream)
-                await stream.fail(FALLBACK_REPLY).catch(() => { });
+            await published.fail(FALLBACK_REPLY).catch(() => { });
             throw err;
         }
         finally {
@@ -604,20 +626,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()) {
+        const how = await published.finish(reply.trim());
+        if (how === "empty") {
             this.log(`brain returned empty reply — ignoring`);
             return;
         }
-        await ch.send({ text: reply.trim() });
         this.handled++;
-        this.log(`${m.channelId} -> replied (${reply.trim().length} chars, handled=${this.handled})`);
+        this.log(`${m.channelId} -> ${how} reply (${reply.trim().length} chars, handled=${this.handled})`);
     }
     /** A FORBIDDEN post (broadcast channel, bot not an operator) fails for every
      *  future message too — mute the channel so the brain stops running there. */

package/dist/brain.d.ts

@@ -1,16 +1,33 @@
 import type { BridgeConfig } from "./config.js";
+import type { ToolProgressEvent } from "./tool-progress.js";
+/** A decrypted inbound file written onto the Hermes cache for this turn. */
+export interface BrainFile {
+    path: string;
+    name: string;
+    contentType: string;
+    size: number;
+    kind: "image" | "video" | "audio" | "document";
+}
 export interface BrainContext {
     botHandle: string;
     botUserId: string;
     channelId: string;
     senderUserId: string;
+    /** Local paths of photos / video / PDFs / any file the human just sent. */
+    files?: BrainFile[];
 }
 /**
  * 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: {
@@ -32,6 +40,7 @@ function cmdBrain(cmd, timeoutMs) {
                 NOPEEK_BOT_USER_ID: ctx.botUserId,
                 NOPEEK_CHANNEL_ID: ctx.channelId,
                 NOPEEK_SENDER_USER_ID: ctx.senderUserId,
+                ...(ctx.files?.length ? { NOPEEK_FILES: JSON.stringify(ctx.files) } : {}),
             },
         });
         let stdout = "";
@@ -105,6 +114,7 @@ function urlBrain(url, timeoutMs) {
                     botUserId: ctx.botUserId,
                     channelId: ctx.channelId,
                     senderUserId: ctx.senderUserId,
+                    ...(ctx.files?.length ? { files: ctx.files } : {}),
                 }),
             });
             if (!res.ok) {

package/dist/bridge.d.ts

@@ -1,5 +1,5 @@
 import type { BridgeConfig, Pairing, BrainSpec, BrainBackend } from "./config.js";
-export declare const VERSION = "0.7.10";
+export declare const VERSION = "0.7.14";
 export interface PairRequest {
     pairingSecret: string;
     appId: string;

package/dist/bridge.js

@@ -19,7 +19,7 @@ import { reportCapabilities } from "./capabilities.js";
 import { lastHermesApiHealth, probeHermesApi } from "./hermes-http.js";
 import { lastTurnGlobal, turnSnapshot } from "./last-turn.js";
 import { isBrainBackend } from "./config.js";
-export const VERSION = "0.7.10";
+export const VERSION = "0.7.14";
 function hermesApiStatus(cfg) {
     const api = lastHermesApiHealth();
     return {

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,30 @@
+import { readFileSync } from "node:fs";
+import { asHooks } from "./brain.js";
+import { RECAP_HINT } from "./tool-progress.js";
+/** Skip data-URL vision parts above this so a gallery cannot blow the POST. */
+const MAX_IMAGE_DATA_URL_BYTES = 8 * 1024 * 1024;
+const MAX_IMAGE_DATA_URL_TOTAL = 20 * 1024 * 1024;
+function userContent(text, files) {
+    const images = (files ?? []).filter((f) => f.kind === "image" && f.size > 0 && f.size <= MAX_IMAGE_DATA_URL_BYTES);
+    if (!images.length)
+        return text;
+    const parts = [{ type: "text", text }];
+    let used = 0;
+    for (const img of images) {
+        if (used + img.size > MAX_IMAGE_DATA_URL_TOTAL)
+            break;
+        try {
+            const b64 = readFileSync(img.path).toString("base64");
+            const mime = img.contentType.startsWith("image/") ? img.contentType : "image/jpeg";
+            parts.push({ type: "image_url", image_url: { url: `data:${mime};base64,${b64}` } });
+            used += img.size;
+        }
+        catch (err) {
+            console.error(`[brain:hermes-http] could not attach ${img.path}: ${err.message}`);
+        }
+    }
+    return parts.length > 1 ? parts : text;
+}
 let lastHealth = null;
 const HEALTH_TTL_MS = 15_000;
 export function lastHermesApiHealth() {
@@ -35,16 +62,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 +97,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: userContent(text, ctx.files) },
+                    ],
                 }),
                 signal: controller.signal,
             });
@@ -98,29 +132,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:"))
+                const frames = buf.split("\n\n");
+                buf = frames.pop() ?? "";
+                for (const frame of frames) {
+                    const ev = parseSseFrame(frame);
+                    if (!ev)
                         continue;
-                    const payload = trimmed.slice(5).trim();
-                    if (!payload || payload === "[DONE]")
+                    if (ev.event === "hermes.tool.progress") {
+                        const tool = asToolProgress(ev.data);
+                        if (tool)
+                            onTool?.(tool);
                         continue;
-                    let parsed;
-                    try {
-                        parsed = JSON.parse(payload);
                     }
-                    catch {
-                        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 +180,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 +226,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/inbound-files.d.ts

@@ -0,0 +1,36 @@
+import type { BrainFile } from "./brain.js";
+export declare const CONTROL_TYPES: Set<string>;
+export declare const MAX_ATTACHMENT_BYTES: number;
+export declare const MAX_ATTACHMENTS = 20;
+export declare const MAX_TEXT_INJECT_BYTES: number;
+export type EncryptedAtt = {
+    blobUrl: string;
+    contentKey: string;
+    iv: string;
+    name?: string;
+    contentType?: string;
+    size?: number;
+};
+export type FileKind = BrainFile["kind"];
+export declare function isControlType(type?: string | null): boolean;
+export declare function parseAttachments(body: unknown): EncryptedAtt[];
+export declare function hasInboundWork(body: unknown): boolean;
+export declare function safeFileName(name: string | undefined, fallback: string): string;
+export declare function classifyKind(contentType: string | undefined, name: string): FileKind;
+export declare function inferContentType(name: string, contentType?: string): string;
+export declare function cacheDirFor(kind: FileKind, home?: string): string;
+export declare function describeStructured(body: Record<string, unknown> | null | undefined): string;
+export declare function fileNote(file: BrainFile): string;
+export declare function buildInboundPrompt(opts: {
+    caption: string;
+    files: BrainFile[];
+    structured?: string;
+    failures?: string[];
+}): string;
+export declare function injectTextPreview(file: BrainFile, bytes: Buffer): string | null;
+export type AttachmentFetcher = (att: EncryptedAtt) => Promise<Buffer>;
+export declare function saveInboundFiles(fetchAtt: AttachmentFetcher, attachments: EncryptedAtt[], messageId: string, home?: string): Promise<{
+    files: BrainFile[];
+    failures: string[];
+    previews: string[];
+}>;

package/dist/inbound-files.js

@@ -0,0 +1,241 @@
+// Decrypt NoPeek attachments onto the Hermes cache so any brain (Hermes HTTP,
+// Hermes CLI, Claude Code, cmd/webhook) can read photos, video, PDFs, docx,
+// and any other file the human sent. The old hop forwarded only m.body.text.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { extname, join } from "node:path";
+import { hermesHome } from "./backends.js";
+export const CONTROL_TYPES = new Set([
+    "reaction",
+    "poll_vote",
+    "rsvp",
+    "edit",
+    "recall",
+    "link_preview_update",
+]);
+export const MAX_ATTACHMENT_BYTES = 200 * 1024 * 1024;
+export const MAX_ATTACHMENTS = 20;
+export const MAX_TEXT_INJECT_BYTES = 100 * 1024;
+const MAX_NAME = 80;
+const TEXT_INJECT_EXT = new Set([".txt", ".md", ".csv", ".log", ".json", ".xml", ".yaml", ".yml", ".toml", ".ini", ".cfg"]);
+export function isControlType(type) {
+    return typeof type === "string" && CONTROL_TYPES.has(type);
+}
+export function parseAttachments(body) {
+    if (!body || typeof body !== "object")
+        return [];
+    const raw = body.attachments;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (!item || typeof item !== "object")
+            continue;
+        const a = item;
+        if (typeof a.blobUrl !== "string" || !a.blobUrl)
+            continue;
+        if (typeof a.contentKey !== "string" || !a.contentKey)
+            continue;
+        if (typeof a.iv !== "string" || !a.iv)
+            continue;
+        out.push({
+            blobUrl: a.blobUrl,
+            contentKey: a.contentKey,
+            iv: a.iv,
+            name: typeof a.name === "string" && a.name.trim() ? a.name : undefined,
+            contentType: typeof a.contentType === "string" ? a.contentType : undefined,
+            size: typeof a.size === "number" && Number.isFinite(a.size) ? a.size : undefined,
+        });
+        if (out.length >= MAX_ATTACHMENTS)
+            break;
+    }
+    return out;
+}
+export function hasInboundWork(body) {
+    if (!body || typeof body !== "object")
+        return false;
+    const b = body;
+    if (isControlType(b.type))
+        return false;
+    if (typeof b.text === "string" && b.text.trim())
+        return true;
+    if (parseAttachments(body).length > 0)
+        return true;
+    if (typeof b.type === "string" && b.type !== "text")
+        return true;
+    return false;
+}
+export function safeFileName(name, fallback) {
+    const base = (name ?? fallback).split(/[/\\]/).pop()?.trim() || fallback;
+    const cleaned = base.replace(/[^\w.\- ()[\]]+/g, "_").replace(/^\.+/, "") || fallback;
+    if (cleaned.length <= MAX_NAME)
+        return cleaned;
+    const ext = extname(cleaned);
+    const stem = cleaned.slice(0, Math.max(1, MAX_NAME - ext.length));
+    return `${stem}${ext}`;
+}
+export function classifyKind(contentType, name) {
+    const ct = (contentType ?? "").toLowerCase();
+    if (ct.startsWith("image/"))
+        return "image";
+    if (ct.startsWith("video/"))
+        return "video";
+    if (ct.startsWith("audio/"))
+        return "audio";
+    const ext = extname(name).toLowerCase();
+    if ([".jpg", ".jpeg", ".png", ".gif", ".webp", ".heic", ".heif", ".bmp", ".tif", ".tiff"].includes(ext))
+        return "image";
+    if ([".mp4", ".mov", ".m4v", ".webm", ".mkv", ".avi"].includes(ext))
+        return "video";
+    if ([".mp3", ".m4a", ".aac", ".wav", ".ogg", ".flac", ".opus"].includes(ext))
+        return "audio";
+    return "document";
+}
+export function inferContentType(name, contentType) {
+    if (contentType && contentType !== "application/octet-stream")
+        return contentType;
+    const ext = extname(name).toLowerCase();
+    const map = {
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".png": "image/png",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".heic": "image/heic",
+        ".mp4": "video/mp4",
+        ".mov": "video/quicktime",
+        ".webm": "video/webm",
+        ".mp3": "audio/mpeg",
+        ".m4a": "audio/mp4",
+        ".wav": "audio/wav",
+        ".ogg": "audio/ogg",
+        ".pdf": "application/pdf",
+        ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        ".txt": "text/plain",
+        ".md": "text/markdown",
+        ".csv": "text/csv",
+        ".json": "application/json",
+    };
+    return map[ext] || contentType || "application/octet-stream";
+}
+export function cacheDirFor(kind, home = hermesHome()) {
+    const sub = kind === "image" ? "images" : kind === "video" ? "videos" : kind === "audio" ? "audio" : "documents";
+    return join(home, "cache", sub);
+}
+export function describeStructured(body) {
+    if (!body || typeof body.type !== "string")
+        return "";
+    if (body.type === "poll" && body.poll && typeof body.poll === "object") {
+        const poll = body.poll;
+        const q = typeof poll.question === "string" ? poll.question : "poll";
+        const opts = Array.isArray(poll.options)
+            ? poll.options
+                .map((o) => (o && typeof o === "object" && typeof o.label === "string" ? o.label : ""))
+                .filter(Boolean)
+            : [];
+        return `[The user sent a poll: "${q}"${opts.length ? ` options: ${opts.join(" / ")}` : ""}]`;
+    }
+    if (body.type === "contact" && body.contact && typeof body.contact === "object") {
+        const c = body.contact;
+        const name = typeof c.name === "string" ? c.name : "contact";
+        const org = typeof c.organization === "string" ? ` (${c.organization})` : "";
+        return `[The user sent a contact card: ${name}${org}]`;
+    }
+    if ((body.type === "calendar_event" || body.calendarEvent) && body.calendarEvent && typeof body.calendarEvent === "object") {
+        const ev = body.calendarEvent;
+        const title = typeof ev.title === "string" ? ev.title : "event";
+        const start = typeof ev.start === "string" ? ` at ${ev.start}` : "";
+        return `[The user sent a calendar event: ${title}${start}]`;
+    }
+    if (body.type === "location" && body.location && typeof body.location === "object") {
+        const loc = body.location;
+        const label = typeof loc.label === "string" ? loc.label : "location";
+        const lat = typeof loc.lat === "number" ? loc.lat : "?";
+        const lng = typeof loc.lng === "number" ? loc.lng : "?";
+        return `[The user sent a location: ${label} (${lat}, ${lng})]`;
+    }
+    return "";
+}
+export function fileNote(file) {
+    const size = file.size > 0 ? `, ${formatBytes(file.size)}` : "";
+    const noun = file.kind === "image" ? "photo" : file.kind === "video" ? "video" : file.kind === "audio" ? "audio file" : "document";
+    return (`[The user sent a ${noun}: '${file.name}' (${file.contentType}${size}). ` +
+        `The file is saved at: ${file.path}. ` +
+        `Read, inspect, and work from that path. If you need to edit it, copy it into the project first — this cache is temporary.]`);
+}
+export function buildInboundPrompt(opts) {
+    const parts = [];
+    for (const file of opts.files)
+        parts.push(fileNote(file));
+    for (const fail of opts.failures ?? [])
+        parts.push(fail);
+    if (opts.structured)
+        parts.push(opts.structured);
+    if (opts.caption.trim())
+        parts.push(opts.caption.trim());
+    if (parts.length === 0)
+        return "";
+    return parts.join("\n\n");
+}
+export function injectTextPreview(file, bytes) {
+    const ext = extname(file.name).toLowerCase();
+    if (!TEXT_INJECT_EXT.has(ext))
+        return null;
+    if (bytes.length > MAX_TEXT_INJECT_BYTES)
+        return null;
+    try {
+        const text = bytes.toString("utf8");
+        if (!text.trim())
+            return null;
+        return `[Content of ${file.name}]:\n${text}`;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveInboundFiles(fetchAtt, attachments, messageId, home = hermesHome()) {
+    const files = [];
+    const failures = [];
+    const previews = [];
+    const shortId = (messageId || "msg").replace(/[^a-zA-Z0-9]/g, "").slice(-10) || "msg";
+    let i = 0;
+    for (const att of attachments) {
+        i += 1;
+        const name = safeFileName(att.name, `attachment-${i}`);
+        const contentType = inferContentType(name, att.contentType);
+        const kind = classifyKind(contentType, name);
+        if (typeof att.size === "number" && att.size > MAX_ATTACHMENT_BYTES) {
+            failures.push(`[Could not save '${name}': ${formatBytes(att.size)} is over the ${formatBytes(MAX_ATTACHMENT_BYTES)} limit.]`);
+            continue;
+        }
+        try {
+            const bytes = await fetchAtt(att);
+            if (bytes.length > MAX_ATTACHMENT_BYTES) {
+                failures.push(`[Could not save '${name}': ${formatBytes(bytes.length)} is over the ${formatBytes(MAX_ATTACHMENT_BYTES)} limit.]`);
+                continue;
+            }
+            const dir = cacheDirFor(kind, home);
+            mkdirSync(dir, { recursive: true });
+            const prefix = kind === "image" ? "img" : kind === "video" ? "vid" : kind === "audio" ? "aud" : "doc";
+            const path = join(dir, `${prefix}_nopeek_${shortId}_${i}_${name}`);
+            writeFileSync(path, bytes);
+            const file = { path, name, contentType, size: bytes.length, kind };
+            files.push(file);
+            const preview = injectTextPreview(file, bytes);
+            if (preview)
+                previews.push(preview);
+        }
+        catch (err) {
+            failures.push(`[Could not download attachment '${name}': ${err.message}]`);
+        }
+    }
+    return { files, failures, previews };
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${Math.round(n / 102.4) / 10} KB`;
+    return `${Math.round(n / (1024 * 102.4)) / 10} MB`;
+}

package/dist/tool-progress.d.ts

@@ -0,0 +1,66 @@
+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;
+/** 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.";
+export interface StreamHandle {
+    append(chunk: string): void;
+    replace(full: string): void;
+    done(finalText?: string): Promise<unknown>;
+    fail(text: string): Promise<void>;
+}
+export interface TurnSink {
+    stream(): Promise<StreamHandle>;
+    send(text: string): Promise<void>;
+}
+export type TurnPublisherOpts = {
+    stopTyping: () => void;
+    onStreamError: (err: Error) => void;
+    /** Wait this long for a tool before opening a streamed answer. */
+    startDelayMs?: number;
+    /** Start a fresh progress bubble after this many lines. */
+    maxProgressLines?: number;
+};
+export type TurnFinishKind = "streamed" | "sent" | "empty";
+/** Text in `full` that has not already been posted as commentary. */
+export declare function unpublishedTail(full: string, published: string): string;
+/**
+ * One chat turn: live tool progress (edited in place) with commentary
+ * messages in between tool batches, then any leftover recap below.
+ * All channel writes run on a single promise chain so bubbles stay in order.
+ */
+export declare class TurnPublisher {
+    private readonly sink;
+    private readonly opts;
+    private write;
+    private progressP;
+    private progress;
+    private progressLines;
+    private textP;
+    private textBuf;
+    private held;
+    private published;
+    private toolsUsed;
+    private startTimer;
+    private seen;
+    private readonly startDelayMs;
+    private readonly maxProgressLines;
+    constructor(sink: TurnSink, opts: TurnPublisherOpts);
+    onChunk(delta: string): void;
+    onTool(ev: ToolProgressEvent): void;
+    finish(reply: string): Promise<TurnFinishKind>;
+    fail(text: string): Promise<void>;
+    private cancelStart;
+    private enqueue;
+    /** Open or append the current commentary/answer stream with this chunk only. */
+    private appendCommentary;
+    /** Finalize the current commentary so later tools land below it. */
+    private commitText;
+    private addProgressLine;
+    private closeProgress;
+}

package/dist/tool-progress.js

@@ -0,0 +1,293 @@
+// Telegram-style tool progress for NoPeek bots.
+//
+// Hermes emits `hermes.tool.progress` SSE events while it works, interleaved
+// with assistant text deltas (the "Skills are loaded. Next I'll…" lines).
+// On Telegram the gateway posts each commentary as its own message and starts
+// a fresh progress bubble underneath. This publisher matches that:
+//   1. Tool lines edit a single live bubble (roll to a new one if it gets long).
+//   2. Commentary after a tool batch finalizes that bubble and is posted below.
+//   3. The next tool batch opens a NEW progress bubble under the commentary.
+//   4. The recap is whatever text is still unpublished at finish().
+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;
+}
+/** 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.";
+/** Text in `full` that has not already been posted as commentary. */
+export function unpublishedTail(full, published) {
+    const f = full.trim();
+    const p = published.trim();
+    if (!f)
+        return "";
+    if (!p)
+        return f;
+    if (f === p)
+        return "";
+    if (full.startsWith(published))
+        return full.slice(published.length).trim();
+    if (f.startsWith(p))
+        return f.slice(p.length).trim();
+    const idx = f.indexOf(p);
+    if (idx >= 0)
+        return (f.slice(0, idx) + f.slice(idx + p.length)).trim();
+    return f;
+}
+/**
+ * One chat turn: live tool progress (edited in place) with commentary
+ * messages in between tool batches, then any leftover recap below.
+ * All channel writes run on a single promise chain so bubbles stay in order.
+ */
+export class TurnPublisher {
+    sink;
+    opts;
+    write = Promise.resolve();
+    progressP = null;
+    progress = null;
+    progressLines = [];
+    textP = null;
+    textBuf = "";
+    held = "";
+    published = "";
+    toolsUsed = false;
+    startTimer = null;
+    seen = new Set();
+    startDelayMs;
+    maxProgressLines;
+    constructor(sink, opts) {
+        this.sink = sink;
+        this.opts = opts;
+        this.startDelayMs = opts.startDelayMs ?? 400;
+        this.maxProgressLines = opts.maxProgressLines ?? 16;
+    }
+    onChunk(delta) {
+        if (!delta)
+            return;
+        if (this.toolsUsed) {
+            this.cancelStart();
+            this.enqueue(() => this.appendCommentary(delta));
+            return;
+        }
+        if (this.textP) {
+            this.enqueue(() => this.appendCommentary(delta));
+            return;
+        }
+        this.held += delta;
+        if (this.startTimer)
+            return;
+        this.startTimer = setTimeout(() => {
+            this.startTimer = null;
+            if (this.toolsUsed || this.textP || !this.held)
+                return;
+            const chunk = this.held;
+            this.held = "";
+            this.enqueue(() => this.appendCommentary(chunk));
+        }, this.startDelayMs);
+    }
+    onTool(ev) {
+        const line = formatToolLine(ev);
+        if (!line)
+            return;
+        if (this.progressLines[this.progressLines.length - 1] === line)
+            return;
+        if (this.seen.has(line) && this.progressLines.includes(line))
+            return;
+        this.seen.add(line);
+        this.toolsUsed = true;
+        if (this.startTimer) {
+            clearTimeout(this.startTimer);
+            this.startTimer = null;
+        }
+        const pending = this.held;
+        this.held = "";
+        this.enqueue(async () => {
+            await this.commitText(pending);
+            await this.addProgressLine(line);
+        });
+    }
+    async finish(reply) {
+        this.cancelStart();
+        await this.write;
+        await this.closeProgress();
+        const trimmed = reply.trim();
+        if (this.textP && !this.toolsUsed) {
+            const s = await this.textP.catch(() => null);
+            this.textP = null;
+            if (s) {
+                await s.done(trimmed || undefined);
+                return trimmed ? "streamed" : "empty";
+            }
+        }
+        await this.commitText(this.held);
+        const rest = unpublishedTail(trimmed, this.published);
+        if (!rest)
+            return this.published.trim() ? "streamed" : "empty";
+        this.opts.stopTyping();
+        await this.sink.send(rest);
+        return "sent";
+    }
+    async fail(text) {
+        this.cancelStart();
+        await this.write;
+        await this.closeProgress();
+        if (this.textP) {
+            const s = await this.textP.catch(() => null);
+            this.textP = null;
+            this.textBuf = "";
+            this.held = "";
+            if (s) {
+                await s.fail(text);
+                return;
+            }
+        }
+        this.opts.stopTyping();
+        await this.sink.send(text);
+    }
+    cancelStart() {
+        if (!this.startTimer)
+            return;
+        clearTimeout(this.startTimer);
+        this.startTimer = null;
+    }
+    enqueue(fn) {
+        this.write = this.write.then(fn).catch((err) => {
+            console.error(`[turn] ${err.message}`);
+        });
+    }
+    /** Open or append the current commentary/answer stream with this chunk only. */
+    async appendCommentary(chunk) {
+        if (!chunk)
+            return;
+        if (this.toolsUsed)
+            await this.closeProgress();
+        this.opts.stopTyping();
+        if (!this.textP) {
+            this.textP = this.sink.stream();
+            try {
+                const s = await this.textP;
+                s.append(chunk);
+                this.textBuf += chunk;
+            }
+            catch (err) {
+                this.textP = null;
+                this.opts.onStreamError(err);
+                await this.sink.send(chunk).catch(() => { });
+                this.published += chunk;
+            }
+            return;
+        }
+        try {
+            const s = await this.textP;
+            s.append(chunk);
+            this.textBuf += chunk;
+        }
+        catch (err) {
+            this.textP = null;
+            this.opts.onStreamError(err);
+            await this.sink.send(this.textBuf + chunk).catch(() => { });
+            this.published += this.textBuf + chunk;
+            this.textBuf = "";
+        }
+    }
+    /** Finalize the current commentary so later tools land below it. */
+    async commitText(pending = "") {
+        if (this.textP) {
+            const s = await this.textP.catch(() => null);
+            this.textP = null;
+            const extra = pending;
+            const final = this.textBuf + extra;
+            this.textBuf = "";
+            if (s && final) {
+                if (extra)
+                    s.append(extra);
+                await s.done(final).catch(() => { });
+                this.published += final;
+                return;
+            }
+            if (final.trim()) {
+                this.opts.stopTyping();
+                await this.sink.send(final).catch(() => { });
+                this.published += final;
+            }
+            return;
+        }
+        if (!pending.trim())
+            return;
+        this.opts.stopTyping();
+        await this.sink.send(pending);
+        this.published += pending;
+    }
+    async addProgressLine(line) {
+        this.opts.stopTyping();
+        if (this.progressLines.length >= this.maxProgressLines && this.progressP) {
+            await this.closeProgress();
+        }
+        this.progressLines.push(line);
+        const body = this.progressLines.join("\n");
+        if (!this.progressP) {
+            this.progressP = this.sink.stream();
+            try {
+                this.progress = await this.progressP;
+                this.progress.replace(body);
+            }
+            catch (err) {
+                this.progressP = null;
+                this.progress = null;
+                this.opts.onStreamError(err);
+                await this.sink.send(body).catch(() => { });
+            }
+            return;
+        }
+        this.progress?.replace(body);
+    }
+    async closeProgress() {
+        if (!this.progressP) {
+            this.progressLines = [];
+            this.progress = null;
+            return;
+        }
+        const s = await this.progressP.catch(() => null);
+        this.progressP = null;
+        this.progress = null;
+        const text = this.progressLines.join("\n");
+        this.progressLines = [];
+        if (s && text)
+            await s.done(text).catch(() => { });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nopeek/agent-bridge",
-  "version": "0.7.10",
+  "version": "0.7.14",
   "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",
@@ -45,6 +45,7 @@
     "build": "tsc -p tsconfig.json",
     "start": "node dist/cli.js",
     "dev": "tsx src/cli.ts",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test --test-concurrency=1 src/tool-progress.test.ts src/inbound-files.test.ts"
   }
 }