@circuitwall/jarela 1.2.0 → 1.3.0

package/lib/bridges/attachment-store.ts

@@ -0,0 +1,184 @@
+// Bridge attachment spill store.
+//
+// Inbound bridge messages (WhatsApp, future Telegram/Slack, etc.) can
+// carry files that are too large or too opaque to inline straight into
+// the LLM context: PDFs, spreadsheets, archives, multi-minute audio,
+// short videos. We persist those bytes under the user's Jarela data
+// dir and hand the agent a text pointer (`saved locally at <abs>`) so
+// it can decide what to do — typically calling `file_read` on the path.
+//
+// Small media (e.g. ≤ 1 MB images) keep going inline so vision-capable
+// models can still describe them in one round-trip without bouncing
+// through disk.
+//
+// Layout: <dataDir>/bridge-attachments/<bridge_id>/<YYYY-MM-DD>/<id>-<safe-name>
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { getDataDir } from "@/lib/db/data-dir";
+
+export const BRIDGE_ATTACHMENTS_DIRNAME = "bridge-attachments";
+
+/** Default inline cap for media we still want the LLM to see directly. */
+export const DEFAULT_INLINE_LIMIT_BYTES = 1 * 1024 * 1024;
+
+/** Media types kept inline when small. Everything else is always spilled. */
+export const INLINE_MIME_PREFIXES: readonly string[] = ["image/"];
+
+export interface SaveAttachmentInput {
+  bridge_id: string;
+  /** Best-effort source filename (may be missing — we'll synthesize one). */
+  filename: string | null;
+  media_type: string;
+  /** Optional adapter-side message id used to make filenames deterministic. */
+  message_id?: string | null;
+  buffer: Buffer;
+}
+
+export interface SavedAttachment {
+  abs_path: string;
+  size: number;
+  sha256: string;
+}
+
+/**
+ * Decide whether a buffer should be inlined as a `ContentPart` or
+ * spilled to disk. Keeps small images inline so vision models still
+ * work out-of-the-box; spills everything else.
+ */
+export function shouldInline(media_type: string, size: number, limit = DEFAULT_INLINE_LIMIT_BYTES): boolean {
+  if (size > limit) return false;
+  return INLINE_MIME_PREFIXES.some((p) => media_type.startsWith(p));
+}
+
+function baseDir(): string {
+  return path.join(getDataDir(), BRIDGE_ATTACHMENTS_DIRNAME);
+}
+
+function todayDir(): string {
+  // Local-time YYYY-MM-DD keeps directories human-scannable in the
+  // user's timezone. Cross-day boundary noise isn't worth UTC.
+  const d = new Date();
+  const yyyy = d.getFullYear();
+  const mm = String(d.getMonth() + 1).padStart(2, "0");
+  const dd = String(d.getDate()).padStart(2, "0");
+  return `${yyyy}-${mm}-${dd}`;
+}
+
+// Strip path separators, control chars, and anything that would
+// surprise a Windows shell. Truncate so long captions can't blow
+// MAX_PATH (260) on Win32.
+function safeFilename(name: string | null, fallback: string): string {
+  const raw = (name ?? "").trim() || fallback;
+  let s = raw.replace(/[\\/:*?"<>|\u0000-\u001f]/g, "_");
+  s = s.replace(/\s+/g, " ").trim();
+  if (s.length > 80) {
+    const ext = path.extname(s).slice(0, 12);
+    s = s.slice(0, 80 - ext.length) + ext;
+  }
+  return s || fallback;
+}
+
+function safeBridgeId(id: string): string {
+  // bridge_id is internally generated but be defensive — refuse anything
+  // that could escape the attachments dir.
+  return id.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+
+/**
+ * Persist a bridge attachment to disk and return its absolute path.
+ *
+ * Idempotent on (bridge_id, message_id, filename): re-saving the same
+ * inbound message overwrites the same file rather than fanning out
+ * duplicates on adapter restart.
+ */
+export async function saveBridgeAttachment(input: SaveAttachmentInput): Promise<SavedAttachment> {
+  const dir = path.join(baseDir(), safeBridgeId(input.bridge_id), todayDir());
+  await fs.mkdir(dir, { recursive: true });
+
+  // Deterministic id when the adapter gave us a message id; fall back
+  // to a short random hex so concurrent unrelated messages can't collide.
+  const idPart = (input.message_id ?? "").replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 32)
+    || crypto.randomBytes(6).toString("hex");
+  const fname = `${idPart}-${safeFilename(input.filename, "attachment")}`;
+  const abs = path.join(dir, fname);
+
+  await fs.writeFile(abs, input.buffer);
+
+  const sha256 = crypto.createHash("sha256").update(input.buffer).digest("hex");
+  return { abs_path: abs, size: input.buffer.length, sha256 };
+}
+
+export interface PruneOptions {
+  /** Files older than this many ms are deleted. */
+  maxAgeMs: number;
+}
+
+export interface PruneResult {
+  removed_files: number;
+  removed_dirs: number;
+  freed_bytes: number;
+}
+
+/**
+ * Delete bridge attachments older than `maxAgeMs`. Best-effort: a
+ * locked or vanished file is skipped silently. Empty per-day and
+ * per-bridge directories are pruned afterwards so the tree doesn't
+ * accumulate empty husks.
+ */
+export async function pruneBridgeAttachments(opts: PruneOptions): Promise<PruneResult> {
+  const root = baseDir();
+  const cutoff = Date.now() - Math.max(0, opts.maxAgeMs);
+  const result: PruneResult = { removed_files: 0, removed_dirs: 0, freed_bytes: 0 };
+
+  let bridges: string[] = [];
+  try { bridges = await fs.readdir(root); } catch { return result; }
+
+  for (const bridge of bridges) {
+    const bridgeDir = path.join(root, bridge);
+    let days: string[] = [];
+    try { days = await fs.readdir(bridgeDir); } catch { continue; }
+
+    for (const day of days) {
+      const dayDir = path.join(bridgeDir, day);
+      let files: string[] = [];
+      try { files = await fs.readdir(dayDir); } catch { continue; }
+
+      for (const f of files) {
+        const fp = path.join(dayDir, f);
+        try {
+          const st = await fs.stat(fp);
+          if (!st.isFile()) continue;
+          if (st.mtimeMs >= cutoff) continue;
+          await fs.unlink(fp);
+          result.removed_files++;
+          result.freed_bytes += st.size;
+        } catch { /* skip */ }
+      }
+
+      try {
+        const remaining = await fs.readdir(dayDir);
+        if (remaining.length === 0) {
+          await fs.rmdir(dayDir);
+          result.removed_dirs++;
+        }
+      } catch { /* skip */ }
+    }
+
+    try {
+      const remaining = await fs.readdir(bridgeDir);
+      if (remaining.length === 0) {
+        await fs.rmdir(bridgeDir);
+        result.removed_dirs++;
+      }
+    } catch { /* skip */ }
+  }
+
+  return result;
+}
+
+/** Test helper: absolute path to the root attachments dir. */
+export function bridgeAttachmentsRoot(): string {
+  return baseDir();
+}

package/lib/bridges/whatsapp.ts

@@ -27,6 +27,7 @@ import { createRequire } from "node:module";
 import { ensureBridgeAuthDir, findRoute, removeBridgeAuthDir } from "@/lib/stores/bridges";
 import type { BridgeAdapter, ChatInfo, InboundHandler, StatusHandler, InboundMessage, StatusUpdate } from "./types";
 import type { ContentPart } from "@/lib/tools/types";
+import { saveBridgeAttachment, shouldInline } from "./attachment-store";
 
 // Baileys + qrcode are dev-time-installed peer libs. We never import their
 // types directly — both modules are loaded via dynamic `import()` inside
@@ -597,14 +598,44 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
       }
     };
 
+    // Spill helper: persist any buffer we can't (or shouldn't) inline,
+    // and append a text pointer the agent can act on with file_read.
+    // Returns true if the buffer was spilled so callers can decide
+    // whether to also push an inline ContentPart.
+    const messageId = (rawMessage as { key?: { id?: string } })?.key?.id ?? null;
+    const spill = async (
+      buf: Buffer,
+      filename: string,
+      mime: string,
+      label: string,
+    ): Promise<void> => {
+      try {
+        const saved = await saveBridgeAttachment({
+          bridge_id: this.bridge_id,
+          filename,
+          media_type: mime,
+          message_id: messageId,
+          buffer: buf,
+        });
+        const sizeKb = Math.max(1, Math.round(saved.size / 1024));
+        text = (text ? text + "\n" : "")
+          + `[Attached ${label}: ${filename} (${mime}, ${sizeKb} KB) saved locally at ${saved.abs_path}. `
+          + `Use file_read on that path to inspect the contents.]`;
+      } catch (err) {
+        const m = err instanceof Error ? err.message : String(err);
+        console.warn(`[bridge ${this.bridge_id}] failed to spill ${label} from ${remote_jid}: ${m}`);
+      }
+    };
+
     if (inner.imageMessage) {
       const buf = await download("image");
       if (buf) {
-        attachments.push({
-          type: "image",
-          media_type: sanitizeMediaType(inner.imageMessage.mimetype, "image", "image/jpeg"),
-          data: buf.toString("base64"),
-        });
+        const mime = sanitizeMediaType(inner.imageMessage.mimetype, "image", "image/jpeg");
+        if (shouldInline(mime, buf.length)) {
+          attachments.push({ type: "image", media_type: mime, data: buf.toString("base64") });
+        } else {
+          await spill(buf, `image-${messageId ?? Date.now()}.${mime.split("/")[1] ?? "bin"}`, mime, "image");
+        }
       }
     }
 
@@ -615,11 +646,12 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
         // models actually describe them. Animated stickers go through as
         // their raw webp; providers that can't decode animated webp will
         // typically render the first frame.
-        attachments.push({
-          type: "image",
-          media_type: sanitizeMediaType(inner.stickerMessage.mimetype, "image", "image/webp"),
-          data: buf.toString("base64"),
-        });
+        const mime = sanitizeMediaType(inner.stickerMessage.mimetype, "image", "image/webp");
+        if (shouldInline(mime, buf.length)) {
+          attachments.push({ type: "image", media_type: mime, data: buf.toString("base64") });
+        } else {
+          await spill(buf, `sticker-${messageId ?? Date.now()}.webp`, mime, "sticker");
+        }
       }
     }
 
@@ -627,24 +659,18 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
       const isVoice = !!inner.audioMessage.ptt;
       const buf = await download(isVoice ? "voice" : "audio");
       if (buf) {
-        attachments.push({
-          type: "file",
-          name: isVoice ? "voice-note" : "audio",
-          media_type: sanitizeMediaType(inner.audioMessage.mimetype, "audio", "audio/ogg"),
-          data: buf.toString("base64"),
-        });
+        const mime = sanitizeMediaType(inner.audioMessage.mimetype, "audio", "audio/ogg");
+        const ext = mime.split("/")[1]?.replace(/^x-/, "") ?? "ogg";
+        await spill(buf, `${isVoice ? "voice-note" : "audio"}-${messageId ?? Date.now()}.${ext}`, mime, isVoice ? "voice note" : "audio");
       }
     }
 
     if (inner.videoMessage) {
       const buf = await download("video");
       if (buf) {
-        attachments.push({
-          type: "file",
-          name: "video",
-          media_type: sanitizeMediaType(inner.videoMessage.mimetype, "video", "video/mp4"),
-          data: buf.toString("base64"),
-        });
+        const mime = sanitizeMediaType(inner.videoMessage.mimetype, "video", "video/mp4");
+        const ext = mime.split("/")[1] ?? "mp4";
+        await spill(buf, `video-${messageId ?? Date.now()}.${ext}`, mime, "video");
       }
     }
 
@@ -656,16 +682,8 @@ export class WhatsAppBridgeAdapter implements BridgeAdapter {
           "document",
           "application/octet-stream",
         );
-        // The LLM layer (lib/agents/llm.ts) inlines text/* and
-        // application/json file parts directly as their `data` string. For
-        // those we must store the decoded UTF-8 contents, not base64.
-        const inlineAsText = mime.startsWith("text/") || mime === "application/json";
-        attachments.push({
-          type: "file",
-          name: inner.documentMessage.fileName || inner.documentMessage.title || "document",
-          media_type: mime,
-          data: inlineAsText ? buf.toString("utf8") : buf.toString("base64"),
-        });
+        const filename = inner.documentMessage.fileName || inner.documentMessage.title || `document-${messageId ?? Date.now()}`;
+        await spill(buf, filename, mime, "document");
       }
     }
 

package/lib/tools/async-results-tool.ts

@@ -0,0 +1,114 @@
+// Built-in tools that pair with the wallclock wrapper's `async_run` mode.
+//
+// `async_run: true` on any tool returns immediately with a key; the
+// agent later calls these tools to retrieve the result.
+
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import { registerTools } from "./registry";
+import {
+  consumeAsyncResult,
+  getAsyncResult,
+  listAsyncResults,
+  type AsyncResultRecord,
+} from "./async-results";
+
+function serialize(rec: AsyncResultRecord, includeResult: boolean): Record<string, unknown> {
+  const out: Record<string, unknown> = {
+    key: rec.key,
+    tool: rec.tool,
+    status: rec.status,
+    started_at: rec.started_at,
+    finished_at: rec.finished_at,
+    elapsed_ms: (rec.finished_at ?? Date.now()) - rec.started_at,
+  };
+  if (includeResult && rec.status === "done") out.result = rec.result;
+  if (includeResult && rec.status === "error") out.error = rec.error;
+  return out;
+}
+
+async function waitForFinish(key: string, waitMs: number): Promise<AsyncResultRecord | null> {
+  const deadline = Date.now() + Math.max(0, waitMs);
+  // 50ms poll — cheap on a Map.get, and bounded by waitMs.
+  while (Date.now() < deadline) {
+    const rec = getAsyncResult(key);
+    if (!rec) return null;
+    if (rec.status !== "pending") return rec;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  return getAsyncResult(key);
+}
+
+export const toolResultGetTool = tool(
+  async ({ key, wait_ms, consume }) => {
+    let rec: AsyncResultRecord | null = getAsyncResult(key);
+    if (!rec) {
+      return JSON.stringify({
+        ok: false,
+        status: "unknown",
+        key,
+        error: "no async result for that key (it may have expired or never existed)",
+      });
+    }
+    if (rec.status === "pending" && typeof wait_ms === "number" && wait_ms > 0) {
+      rec = (await waitForFinish(key, wait_ms)) ?? rec;
+    }
+    if (!rec) {
+      return JSON.stringify({ ok: false, status: "unknown", key });
+    }
+    const finished = rec.status !== "pending";
+    if (consume && finished) {
+      consumeAsyncResult(key);
+    }
+    return JSON.stringify({ ok: true, ...serialize(rec, /* includeResult */ true) });
+  },
+  {
+    name: "tool_result_get",
+    description:
+      "Retrieve the result of a previously async-fired tool call by its key. " +
+      "Pass `wait_ms` to short-poll up to that long for a pending call to finish. " +
+      "Pass `consume: true` to delete the entry after reading a finished result. " +
+      "Status will be 'pending' (still running), 'done' (success — `result` populated), " +
+      "'error' (failed — `error` populated), or 'unknown' (no such key).",
+    schema: z.object({
+      key: z.string().describe("The key returned by the original async tool call."),
+      wait_ms: z
+        .number()
+        .int()
+        .min(0)
+        .max(60_000)
+        .optional()
+        .describe("Optional short-poll budget (0–60000 ms). Returns as soon as the call finishes or the budget elapses."),
+      consume: z
+        .boolean()
+        .optional()
+        .describe("If true and the call has finished, delete the entry after returning it. Default false."),
+    }),
+  },
+);
+
+export const toolResultListTool = tool(
+  async ({ status }) => {
+    let recs = listAsyncResults();
+    if (status) recs = recs.filter((r) => r.status === status);
+    return JSON.stringify({
+      ok: true,
+      count: recs.length,
+      // Lightweight summary only — full result/error stays behind tool_result_get.
+      results: recs.map((r) => serialize(r, /* includeResult */ false)),
+    });
+  },
+  {
+    name: "tool_result_list",
+    description:
+      "List currently tracked async tool results (newest first). Useful when you've forgotten " +
+      "a key or want a quick status check across pending background calls. Optional `status` " +
+      "filter narrows to 'pending' / 'done' / 'error'.",
+    schema: z.object({
+      status: z.enum(["pending", "done", "error"]).optional()
+        .describe("Optional status filter."),
+    }),
+  },
+);
+
+registerTools("Agent", "read", [toolResultGetTool, toolResultListTool]);