@nopeek/agent-bridge 0.7.11 → 0.7.15

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/mid-turn.d.ts

@@ -0,0 +1,25 @@
+export type FollowupAction = "stop" | "continue";
+export interface FollowupDecision {
+    action: FollowupAction;
+    text: string;
+}
+export declare function isStopRequest(text: string): boolean;
+export declare function coalesceFollowups(texts: string[]): FollowupDecision;
+export declare function wrapInterruptedFollowup(text: string): string;
+export declare function hermesSessionId(channelId: string): string;
+export declare function hermesSessionHeaders(apiKey: string, channelId: string): Record<string, string>;
+export declare class ChannelTurn<T extends {
+    id: string;
+} = {
+    id: string;
+    text: string;
+}> {
+    readonly abort: AbortController;
+    active: boolean;
+    private incoming;
+    private seen;
+    interrupt(item: T): void;
+    consumed(id: string): boolean;
+    takeIncoming(): T[];
+    finish(): void;
+}

package/dist/mid-turn.js

@@ -0,0 +1,67 @@
+// Mid-turn interrupt policy for NoPeek → Hermes.
+//
+// Telegram can /stop a live agent immediately and fold the next message into
+// the same session. The HTTP brain used to serialize the whole turn, then
+// send each follow-up as a brand-new history=0 job — so "Stop" sat for 33
+// minutes and then replied "nothing to stop" three times.
+//
+// This module is the shared policy: detect stop, coalesce a burst, abort the
+// in-flight turn, and keep one stable Hermes session per channel.
+const STOP_RE = /^(?:\/)?(?:please\s+)?stop(?:\s+please)?[.!]?$/i;
+export function isStopRequest(text) {
+    return STOP_RE.test((text || "").trim());
+}
+export function coalesceFollowups(texts) {
+    const cleaned = texts.map((t) => (t || "").trim()).filter(Boolean);
+    if (cleaned.length === 0)
+        return { action: "continue", text: "" };
+    if (cleaned.every(isStopRequest))
+        return { action: "stop", text: cleaned[cleaned.length - 1] };
+    const kept = cleaned.filter((t) => !isStopRequest(t));
+    return { action: "continue", text: kept.join("\n\n") };
+}
+export function wrapInterruptedFollowup(text) {
+    return ("[System note: You were already working on a task. The user interrupted. " +
+        "Reassess the previous work together with this new message and continue as " +
+        "ONE combined task. Do not start a separate independent job. If the new " +
+        "message replaces the old task, switch to it.]\n\n" +
+        text);
+}
+export function hermesSessionId(channelId) {
+    return `nopeek-${channelId}`;
+}
+export function hermesSessionHeaders(apiKey, channelId) {
+    const headers = {};
+    if (!apiKey)
+        return headers;
+    const sid = hermesSessionId(channelId);
+    headers.authorization = `Bearer ${apiKey}`;
+    headers["X-Hermes-Session-Id"] = sid;
+    headers["X-Hermes-Session-Key"] = sid;
+    return headers;
+}
+export class ChannelTurn {
+    abort = new AbortController();
+    active = true;
+    incoming = [];
+    seen = new Set();
+    interrupt(item) {
+        if (!this.seen.has(item.id)) {
+            this.seen.add(item.id);
+            this.incoming.push(item);
+        }
+        if (!this.abort.signal.aborted)
+            this.abort.abort();
+    }
+    consumed(id) {
+        return this.seen.has(id);
+    }
+    takeIncoming() {
+        const items = this.incoming;
+        this.incoming = [];
+        return items;
+    }
+    finish() {
+        this.active = false;
+    }
+}

package/dist/tool-progress.d.ts

@@ -6,24 +6,69 @@ 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;
+    /** Split commentary/recap into a new bubble after this many chars. */
+    maxBubbleChars?: 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;
+/** Unified diffs / `| review` dumps should never land in the chat. */
+export declare function isToolDump(text: string): boolean;
+/** Split a reply into short chat bubbles. Drops tool-dump paragraphs. */
+export declare function splitBubbles(text: string, max?: number): 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;
+    private readonly maxBubbleChars;
+    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 sendBubbles;
+    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.";