@nopeek/agent-bridge 0.7.11 → 0.7.14

package/README.md

@@ -41,9 +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.
+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`.
@@ -79,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:
 
@@ -109,7 +110,8 @@ Content-Type: application/json
   "botHandle": "weatherbot",
   "botUserId": "usr_…",
   "channelId": "ch_…",
-  "senderUserId": "usr_…"
+  "senderUserId": "usr_…",
+  "files": []
 }
 ```
 

package/dist/bot.js

@@ -7,7 +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 { ToolProgressFlusher } from "./tool-progress.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
@@ -457,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
@@ -516,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") {
@@ -534,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 {
@@ -546,12 +570,8 @@ 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 };
+        // 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);
@@ -560,23 +580,17 @@ export class BotRunner {
                 /* best-effort */
             }
         };
-        const onChunk = (delta) => {
-            if (!delta)
-                return;
-            void progress.flush();
-            if (!streamRef.p) {
-                stopTyping();
-                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}`);
-                });
-            }
-            streamRef.p.then((s) => s.append(delta)).catch(() => { });
-        };
-        const progress = new ToolProgressFlusher(async (body) => {
-            stopTyping();
-            await ch.send({ text: body });
+        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);
@@ -586,7 +600,8 @@ export class BotRunner {
                 botUserId: this.info.userId,
                 channelId: m.channelId,
                 senderUserId: m.senderUserId,
-            }, { onChunk, onTool: (ev) => progress.push(ev) });
+                ...(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, {
@@ -600,10 +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.
-            await progress.flush();
-            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 {
@@ -614,21 +626,13 @@ 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);
-            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,10 +1,20 @@
 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

package/dist/brain.js

@@ -40,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 = "";
@@ -113,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.js

@@ -1,5 +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() {
@@ -74,7 +99,7 @@ export function hermesHttpBrain(cfg) {
                     stream: true,
                     messages: [
                         { role: "system", content: RECAP_HINT },
-                        { role: "user", content: text },
+                        { role: "user", content: userContent(text, ctx.files) },
                     ],
                 }),
                 signal: controller.signal,

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

@@ -6,24 +6,61 @@ export type ToolProgressEvent = {
 };
 /** 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>;
+/** 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;
 /**
- * Collect tool lines and flush them as short chat messages.
- * Flush when we have `maxLines` tools, or after `gapMs` of quiet.
+ * 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 ToolProgressFlusher {
-    private readonly send;
-    private readonly gapMs;
-    private readonly maxLines;
-    private lines;
-    private timer;
-    private chain;
+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;
-    constructor(send: ProgressSender, gapMs?: number, maxLines?: number);
-    get pending(): number;
-    push(ev: ToolProgressEvent): void;
-    flush(): Promise<void>;
-    private arm;
+    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;
 }
-/** 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

@@ -1,9 +1,13 @@
 // 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.
+// 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: "✍️",
@@ -44,62 +48,246 @@ function tidyLabel(raw) {
         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;
+}
 /**
- * Collect tool lines and flush them as short chat messages.
- * Flush when we have `maxLines` tools, or after `gapMs` of quiet.
+ * 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 ToolProgressFlusher {
-    send;
-    gapMs;
-    maxLines;
-    lines = [];
-    timer = null;
-    chain = Promise.resolve();
+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();
-    constructor(send, gapMs = 2200, maxLines = 4) {
-        this.send = send;
-        this.gapMs = gapMs;
-        this.maxLines = maxLines;
+    startDelayMs;
+    maxProgressLines;
+    constructor(sink, opts) {
+        this.sink = sink;
+        this.opts = opts;
+        this.startDelayMs = opts.startDelayMs ?? 400;
+        this.maxProgressLines = opts.maxProgressLines ?? 16;
     }
-    get pending() {
-        return this.lines.length;
+    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);
     }
-    push(ev) {
+    onTool(ev) {
         const line = formatToolLine(ev);
         if (!line)
             return;
-        if (this.lines[this.lines.length - 1] === line)
+        if (this.progressLines[this.progressLines.length - 1] === line)
             return;
-        if (this.seen.has(line) && this.lines.includes(line))
+        if (this.seen.has(line) && this.progressLines.includes(line))
             return;
         this.seen.add(line);
-        this.lines.push(line);
-        if (this.lines.length >= this.maxLines) {
-            void this.flush();
+        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;
         }
-        this.arm();
+        if (!pending.trim())
+            return;
+        this.opts.stopTyping();
+        await this.sink.send(pending);
+        this.published += pending;
     }
-    async flush() {
-        if (this.timer) {
-            clearTimeout(this.timer);
-            this.timer = null;
+    async addProgressLine(line) {
+        this.opts.stopTyping();
+        if (this.progressLines.length >= this.maxProgressLines && this.progressP) {
+            await this.closeProgress();
         }
-        if (this.lines.length === 0)
+        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;
-        const text = this.lines.join("\n");
-        this.lines = [];
-        this.chain = this.chain.then(() => this.send(text).catch(() => { }));
-        await this.chain;
+        }
+        this.progress?.replace(body);
     }
-    arm() {
-        if (this.timer)
-            clearTimeout(this.timer);
-        this.timer = setTimeout(() => {
-            this.timer = null;
-            void this.flush();
-        }, this.gapMs);
+    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(() => { });
     }
 }
-/** 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.11",
+  "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",
@@ -22,15 +22,8 @@
   "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": "workspace:^0.2.4"
+    "@nopeek/chat": "^0.2.4"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
@@ -47,5 +40,12 @@
   ],
   "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",
+    "test": "tsx --test --test-concurrency=1 src/tool-progress.test.ts src/inbound-files.test.ts"
   }
-}
+}