@circuitwall/jarela 0.7.2 → 0.7.3

package/lib/bridges/message-role.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { formatBridgePrompt, parseBridgePrompt } from "./message-role";
+
+describe("bridge prompt envelope", () => {
+  it("round-trips DM prompt metadata and body", () => {
+    const raw = formatBridgePrompt({
+      bridge_id: "b1",
+      chat_id: "dm@jid",
+      chat_name: "Alice",
+      is_group: false,
+      role: "counterpart",
+      sender_id: "alice@jid",
+      sender_name: "Alice",
+      text: "hello from dm",
+    });
+    const parsed = parseBridgePrompt(raw);
+    expect(parsed).not.toBeNull();
+    expect(parsed?.bridgeId).toBe("b1");
+    expect(parsed?.chatJid).toBe("dm@jid");
+    expect(parsed?.isGroup).toBe(false);
+    expect(parsed?.senderJid).toBe("alice@jid");
+    expect(parsed?.body).toBe("hello from dm");
+  });
+
+  it("round-trips group prompt metadata and body", () => {
+    const raw = formatBridgePrompt({
+      bridge_id: "b1",
+      chat_id: "group@jid",
+      chat_name: "Family Group",
+      is_group: true,
+      role: "counterpart",
+      sender_id: "bob@jid",
+      sender_name: "Bob",
+      text: "group message",
+    });
+    const parsed = parseBridgePrompt(raw);
+    expect(parsed).not.toBeNull();
+    expect(parsed?.chatJid).toBe("group@jid");
+    expect(parsed?.chatName).toBe("Family Group");
+    expect(parsed?.isGroup).toBe(true);
+    expect(parsed?.senderName).toBe("Bob");
+    expect(parsed?.body).toBe("group message");
+  });
+
+  it("parses envelopes with prose preface before bracket headers", () => {
+    const raw = [
+      "The paired user themselves sent the message below.",
+      "",
+      "[bridge:b1]",
+      "[chat_id:dm@jid]",
+      "[chat_name:Alice]",
+      "[chat_type:dm]",
+      "[sender_id:alice@jid]",
+      "[sender_name:Alice]",
+      "",
+      "body",
+    ].join("\n");
+    const parsed = parseBridgePrompt(raw);
+    expect(parsed?.bridgeId).toBe("b1");
+    expect(parsed?.body).toBe("body");
+  });
+
+  it("accepts legacy key names for compatibility", () => {
+    const raw = [
+      "[bridge:b1]",
+      "[chat_jid:legacy@jid]",
+      "[chat_name:Legacy]",
+      "[chat_type:dm]",
+      "[sender_jid:sender@jid]",
+      "[sender_name:Sender]",
+      "",
+      "legacy body",
+    ].join("\n");
+    const parsed = parseBridgePrompt(raw);
+    expect(parsed?.chatJid).toBe("legacy@jid");
+    expect(parsed?.senderJid).toBe("sender@jid");
+    expect(parsed?.body).toBe("legacy body");
+  });
+
+  it("returns null when not a bridge envelope", () => {
+    expect(parseBridgePrompt("plain text")).toBeNull();
+  });
+});

package/lib/bridges/message-role.ts

@@ -56,6 +56,18 @@ export interface BridgePromptInput {
   text: string;
 }
 
+// Parsed chat-friendly envelope extracted from a bridge prompt body.
+// Used by the chat UI so rendering stays in lockstep with formatter changes.
+export interface BridgePromptContext {
+  bridgeId: string;
+  chatJid: string;
+  chatName: string;
+  isGroup: boolean;
+  senderJid: string;
+  senderName: string;
+  body: string;
+}
+
 /**
  * Build the prompt prefix the agent receives for one bridge-inbound message.
  *
@@ -97,6 +109,40 @@ export function formatBridgePrompt(input: BridgePromptInput): string {
   return `${note}\n\n${lines.join("\n")}\n\n${input.text}`;
 }
 
+// Parses bridge prompt envelopes rendered by formatBridgePrompt().
+// Back-compat: also accepts legacy keys (chat_jid/sender_jid) and optional
+// prose preface before the [bridge:...] metadata block.
+export function parseBridgePrompt(raw: string): BridgePromptContext | null {
+  const start = raw.indexOf("[bridge:");
+  if (start < 0) return null;
+  const src = raw.slice(start);
+
+  const headers: Record<string, string> = {};
+  const lines = src.split("\n");
+  let i = 0;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === "") { i++; break; }
+    const m = /^\[([a-z_]+):([\s\S]*)\]$/.exec(line);
+    if (!m) return null;
+    headers[m[1]] = m[2];
+  }
+
+  const chatId = headers.chat_id || headers.chat_jid;
+  const senderId = headers.sender_id || headers.sender_jid || chatId;
+  if (!headers.bridge || !chatId || !headers.chat_type) return null;
+
+  return {
+    bridgeId: headers.bridge,
+    chatJid: chatId,
+    chatName: headers.chat_name || chatId,
+    isGroup: headers.chat_type === "group",
+    senderJid: senderId,
+    senderName: headers.sender_name || senderId || "Unknown",
+    body: lines.slice(i).join("\n").trimEnd(),
+  };
+}
+
 function roleNote(role: MessageRole, isGroup: boolean): string {
   switch (role) {
     case "user":

package/lib/triggers/handlers/watcher.test.ts

@@ -75,12 +75,31 @@ describe("watcherHandler (ADR-0027)", () => {
     expect(fired.agentId).toBe("a");
     expect(fired.kind).toBe("watcher");
     expect(fired.prompt).toContain('Watcher "change" detected a change');
-    expect(fired.prompt).toContain("v1");
-    expect(fired.prompt).toContain("v2");
+    expect(fired.prompt).toContain("--- Diff (previous -> current) ---");
+    expect(fired.prompt).toContain("- v1");
+    expect(fired.prompt).toContain("+ v2");
+    expect(fired.prompt).not.toContain("--- Previous result ---");
+    expect(fired.prompt).not.toContain("--- Current result ---");
     const after = getWatcher(w.id)!;
     expect(after.last_fired_at).not.toBeNull();
   });
 
+  it("truncates oversized result payloads in the firing prompt", async () => {
+    const w = createWatcher({
+      agent_id: "a", label: "big", tool_name: "watcher_test_tool", interval_seconds: 60,
+    });
+    fakeResult = "A".repeat(5000);
+    await watcherHandler.getDueFirings(new Date(Date.parse(w.next_run_at) + 1));
+    fakeResult = "B".repeat(5000);
+    const w2 = getWatcher(w.id)!;
+    const firings = await watcherHandler.getDueFirings(new Date(Date.parse(w2.next_run_at) + 1));
+    expect(firings).toHaveLength(1);
+    const fired = firings[0];
+    if (fired.mode !== "prompt") throw new Error("expected prompt firing");
+    expect(fired.prompt).toContain("[diff truncated: showing");
+    expect(fired.prompt.length).toBeLessThan(8000);
+  });
+
   it("does NOT fire when result is unchanged across polls", async () => {
     const w = createWatcher({
       agent_id: "a", label: "stable", tool_name: "watcher_test_tool", interval_seconds: 60,
@@ -123,8 +142,8 @@ describe("watcherHandler (ADR-0027)", () => {
     expect(fired.prompt).toContain("Open a Jira ticket against the broken dashboard.");
     expect(fired.prompt).not.toContain("Summarise what changed");
     // Diff envelope is preserved.
-    expect(fired.prompt).toContain("v1");
-    expect(fired.prompt).toContain("v2");
+    expect(fired.prompt).toContain("- v1");
+    expect(fired.prompt).toContain("+ v2");
   });
 
   it("uses the default directive when reaction_prompt is null", async () => {

package/lib/triggers/handlers/watcher.ts

@@ -6,7 +6,7 @@
 //      tools must be context-free).
 //   3. Hash the stringified result and compare to last_fingerprint.
 //   4. If the hash differs from the previous run, return a TriggerFiring
-//      whose prompt embeds {previous, current} as context for the agent.
+//      whose prompt embeds a compact previous->current diff for the agent.
 //      If it matches (or this is the first run with no previous), record
 //      the fingerprint and skip — no LLM call, no firing.
 //   5. Either way the watcher's next_run_at is advanced by
@@ -25,6 +25,7 @@ import {
 } from "@/lib/stores/watchers";
 import { registeredTools } from "@/lib/tools/registry";
 import { publish as publishNotification } from "@/lib/notifications/bus";
+import { truncateBytes } from "@/lib/utils/text";
 import type { TriggerFiring, TriggerHandler, TriggerOutcome } from "../types";
 
 export const WATCHER_KIND = "watcher";
@@ -46,14 +47,64 @@ const DEFAULT_REACTION_DIRECTIVE =
   `Summarise what changed and decide whether the user needs to know. ` +
   `If nothing material changed, you may stay silent.`;
 
+// Watcher tool outputs can be very large (full JSON payloads, long lists).
+// Keep the diff context bounded so one firing cannot consume most of an
+// agent's prompt budget.
+const MAX_DIFF_CONTEXT_BYTES = 3500;
+
+function normalizeForDiff(raw: string): string {
+  try {
+    return JSON.stringify(JSON.parse(raw), null, 2);
+  } catch {
+    return raw;
+  }
+}
+
+function buildDiffForPrompt(previous: string | null, current: string): string {
+  if (previous === null) return "+ (first observation baseline established; no diff available)";
+
+  const prev = normalizeForDiff(previous).split(/\r?\n/);
+  const curr = normalizeForDiff(current).split(/\r?\n/);
+
+  let start = 0;
+  while (start < prev.length && start < curr.length && prev[start] === curr[start]) {
+    start += 1;
+  }
+
+  let prevEnd = prev.length - 1;
+  let currEnd = curr.length - 1;
+  while (prevEnd >= start && currEnd >= start && prev[prevEnd] === curr[currEnd]) {
+    prevEnd -= 1;
+    currEnd -= 1;
+  }
+
+  const removed = prev.slice(start, prevEnd + 1);
+  const added = curr.slice(start, currEnd + 1);
+  if (removed.length === 0 && added.length === 0) {
+    return "(no textual diff after normalization)";
+  }
+
+  const hunkHeader = `@@ old:${start + 1}-${Math.max(start, prevEnd + 1)} new:${start + 1}-${Math.max(start, currEnd + 1)} @@`;
+  const raw = [
+    hunkHeader,
+    ...removed.map((l) => `- ${l}`),
+    ...added.map((l) => `+ ${l}`),
+  ].join("\n");
+
+  const bytes = Buffer.byteLength(raw, "utf8");
+  const clipped = truncateBytes(raw, MAX_DIFF_CONTEXT_BYTES);
+  if (!clipped.truncated) return raw;
+  return `${clipped.text}\n… [diff truncated: showing ${MAX_DIFF_CONTEXT_BYTES} of ${bytes} bytes; full values retained in watcher state]`;
+}
+
 function buildFiringPrompt(watcher: WatcherRow, previous: string | null, current: string): string {
   const argsPretty = (() => {
     try { return JSON.stringify(JSON.parse(watcher.tool_args), null, 2); }
     catch { return watcher.tool_args; }
   })();
   // ADR-0030: a non-null reaction_prompt swaps in for the default directive.
-  // The diff envelope (label/tool/args/previous/current) is unchanged so the
-  // agent always has the change context regardless of the user's instruction.
+  // The diff envelope (label/tool/args/diff) is unchanged so the agent
+  // always has the change context regardless of the user's instruction.
   const directive = watcher.reaction_prompt?.trim() || DEFAULT_REACTION_DIRECTIVE;
   return [
     `Watcher "${watcher.label}" detected a change.`,
@@ -61,11 +112,8 @@ function buildFiringPrompt(watcher: WatcherRow, previous: string | null, current
     `Tool: ${watcher.tool_name}`,
     `Args: ${argsPretty}`,
     ``,
-    `--- Previous result ---`,
-    previous ?? "(none — first observation)",
-    ``,
-    `--- Current result ---`,
-    current,
+    `--- Diff (previous -> current) ---`,
+    buildDiffForPrompt(previous, current),
     ``,
     directive,
   ].join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circuitwall/jarela",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Jarela — local chat interface for LangGraph agents (multi-provider, single-process, SQLite-backed).",
   "license": "Apache-2.0",
   "author": "Andrew Ge Wu",