@circuitwall/jarela 2.3.0 → 2.4.0

package/lib/tools/support/result-refs.ts

@@ -93,23 +93,27 @@ export async function readToolResultRef(args: {
   }
   const offset = Math.max(0, Math.floor(args.offset ?? 0));
   const limit = Math.min(MAX_READ_BYTES, Math.max(1, Math.floor(args.limit ?? DEFAULT_PREVIEW_BYTES)));
-  let buf: Buffer;
   try {
     const file = await fsp.open(abs, "r");
     try {
       const stat = await file.stat();
-      const readLength = Math.max(0, Math.min(limit, stat.size - offset));
-      buf = Buffer.alloc(readLength);
-      if (readLength > 0) await file.read(buf, 0, readLength, offset);
-      const nextOffset = offset + readLength;
+      // Read a few bytes either side so the window can be moved onto UTF-8
+      // character boundaries; paging must never split a multi-byte character.
+      const windowStart = Math.min(Math.max(0, offset - 3), stat.size);
+      const windowLength = Math.max(0, Math.min(stat.size - windowStart, offset - windowStart + limit + 3));
+      const buf = Buffer.alloc(windowLength);
+      if (windowLength > 0) await file.read(buf, 0, windowLength, windowStart);
+      const { start, end } = utf8Window(buf, Math.min(offset, stat.size) - windowStart, limit);
+      const actualOffset = windowStart + start;
+      const nextOffset = windowStart + end;
       return {
         ok: true,
         status: "done",
         name: args.name,
-        offset,
+        offset: actualOffset,
         limit,
         bytes: stat.size,
-        result: buf.toString("utf8"),
+        result: buf.subarray(start, end).toString("utf8"),
         next_offset: nextOffset < stat.size ? nextOffset : null,
         done: nextOffset >= stat.size,
       };
@@ -126,6 +130,25 @@ export async function readToolResultRef(args: {
   }
 }
 
+const isUtf8Continuation = (byte: number | undefined) => byte !== undefined && (byte & 0xc0) === 0x80;
+
+// Moves `[start, start + limit)` inside `buf` onto character boundaries: the
+// start backs up to its lead byte, and the end backs up so it does not cut a
+// character — unless that character alone exceeds `limit`, in which case the
+// whole character is returned so paging always makes progress.
+function utf8Window(buf: Buffer, start: number, limit: number): { start: number; end: number } {
+  let s = Math.max(0, Math.min(start, buf.length));
+  while (s > 0 && isUtf8Continuation(buf[s])) s--;
+  let e = Math.min(buf.length, s + limit);
+  if (e < buf.length && isUtf8Continuation(buf[e])) {
+    let lead = e;
+    while (lead > s && isUtf8Continuation(buf[lead])) lead--;
+    if (lead > s) e = lead;
+    else while (e < buf.length && isUtf8Continuation(buf[e])) e++;
+  }
+  return { start: s, end: e };
+}
+
 export function serializeToolResult(result: unknown): string {
   if (typeof result === "string") return result;
   return JSON.stringify(result) ?? String(result);
@@ -145,8 +168,15 @@ function buildPreview(value: string, mimeType: string): { value: unknown; bytes:
     try {
       const parsed = JSON.parse(value) as unknown;
       if (Array.isArray(parsed)) {
-        const preview = parsed.slice(0, JSON_ARRAY_PREVIEW_ITEMS);
-        return { value: preview, bytes: Buffer.byteLength(JSON.stringify(preview)), total_count: parsed.length };
+        // Cap by bytes as well as items: a few huge rows must not smuggle the
+        // whole result back inline.
+        for (let n = Math.min(parsed.length, JSON_ARRAY_PREVIEW_ITEMS); n > 0; n--) {
+          const preview = parsed.slice(0, n);
+          const bytes = Buffer.byteLength(JSON.stringify(preview));
+          if (bytes <= DEFAULT_PREVIEW_BYTES) return { value: preview, bytes, total_count: parsed.length };
+        }
+        const text = takeUtf8Prefix(value, DEFAULT_PREVIEW_BYTES);
+        return { value: text, bytes: Buffer.byteLength(text), total_count: parsed.length };
       }
     } catch {
       // Fall through to byte preview.
@@ -165,6 +195,8 @@ function takeUtf8Prefix(value: string, maxBytes: number): string {
     if (Buffer.byteLength(value.slice(0, mid)) <= maxBytes) lo = mid;
     else hi = mid - 1;
   }
+  const code = value.charCodeAt(lo - 1);
+  if (lo > 0 && code >= 0xd800 && code <= 0xdbff) lo--;
   return value.slice(0, lo);
 }
 

package/lib/utils/source-link.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { citeAs, httpsUrlOrNull } from "./source-link";
+
+describe("httpsUrlOrNull", () => {
+  it("accepts absolute https URLs", () => {
+    expect(httpsUrlOrNull("https://outlook.office365.com/owa/?ItemID=AAk%3D&exvsurl=1")).toBe(
+      "https://outlook.office365.com/owa/?ItemID=AAk%3D&exvsurl=1",
+    );
+  });
+
+  it("rejects missing, relative, and non-https URLs", () => {
+    for (const url of [null, undefined, "", "/mail/123", "http://example.com", "javascript:alert(1)", "message://%3cid%3e", "not a url"]) {
+      expect(httpsUrlOrNull(url)).toBeNull();
+    }
+  });
+});
+
+describe("citeAs", () => {
+  it("builds a markdown link from a label and URL", () => {
+    expect(citeAs("Quarterly report", "https://www.google.com/calendar/event?eid=abc")).toBe(
+      "[Quarterly report](https://www.google.com/calendar/event?eid=abc)",
+    );
+  });
+
+  it("returns null without a usable URL", () => {
+    expect(citeAs("Subject", null)).toBeNull();
+    expect(citeAs("Subject", "http://insecure.example")).toBeNull();
+  });
+
+  it("escapes brackets and flattens whitespace in the label", () => {
+    expect(citeAs("Re: [EXT]\n  budget\\plan", "https://x.test/a")).toBe("[Re: \\[EXT\\] budget\\\\plan](https://x.test/a)");
+  });
+
+  it("falls back to a default label for an empty subject", () => {
+    expect(citeAs("   ", "https://x.test/a", "Outlook message")).toBe("[Outlook message](https://x.test/a)");
+    expect(citeAs(null, "https://x.test/a")).toBe("[source](https://x.test/a)");
+  });
+
+  it("caps long labels", () => {
+    const link = citeAs("x".repeat(200), "https://x.test/a")!;
+    const label = link.slice(1, link.indexOf("]("));
+    expect(label.length).toBe(80);
+    expect(label.endsWith("…")).toBe(true);
+  });
+
+  it("encodes characters that would end the markdown destination", () => {
+    const link = citeAs("Event", "https://x.test/path(1)?q=a b")!;
+    expect(link).toBe("[Event](https://x.test/path%281%29?q=a%20b)");
+    expect(/^\[[^\]]*\]\([^()\s]+\)$/.test(link)).toBe(true);
+  });
+});

package/lib/utils/source-link.ts

@@ -0,0 +1,45 @@
+/**
+ * Source-link fields for tool results, so an agent can link a reply back to
+ * the email, calendar event, or chat it came from without building URLs.
+ *
+ * `cite_as` is a ready-made markdown link the system prompt tells agents to
+ * paste verbatim. Building it in code keeps the label and URL well-formed:
+ * a stray `]` in a subject or `)` in a URL would otherwise break the link.
+ */
+
+const MAX_LABEL_CHARS = 80;
+
+/** Returns `url` when it is an absolute https URL, otherwise null. */
+export function httpsUrlOrNull(url: string | null | undefined): string | null {
+  if (!url) return null;
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:" ? parsed.href : null;
+  } catch {
+    return null;
+  }
+}
+
+function markdownLabel(label: string | null | undefined, fallback: string): string {
+  const flat = (label ?? "").replace(/\s+/g, " ").trim();
+  const capped = flat.length > MAX_LABEL_CHARS ? `${flat.slice(0, MAX_LABEL_CHARS - 1).trimEnd()}…` : flat;
+  return (capped || fallback).replace(/[\\[\]]/g, (c) => `\\${c}`);
+}
+
+function markdownDestination(url: string): string {
+  return url.replace(/[()\s<>]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
+}
+
+/**
+ * Pre-built markdown link for `cite_as`, or null when there is no usable URL.
+ * Only https URLs qualify: the chat renderer drops other schemes.
+ */
+export function citeAs(
+  label: string | null | undefined,
+  url: string | null | undefined,
+  fallbackLabel = "source",
+): string | null {
+  const safe = httpsUrlOrNull(url);
+  if (!safe) return null;
+  return `[${markdownLabel(label, fallbackLabel)}](${markdownDestination(safe)})`;
+}

package/package.json

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