@circuitwall/jarela 2.3.0 → 2.4.0

package/lib/tools/communications/calendar.test.ts

@@ -1,6 +1,47 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
-const { calendarListEventsTool } = await import("./calendar");
+const { calendarGetEventTool, calendarListEventsTool } = await import("./calendar");
+const { outlookCalendarGetEventTool } = await import("./outlook-calendar");
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+});
+
+function stubApi(tokenHost: string, body: unknown) {
+  vi.stubGlobal("fetch", vi.fn(async (url: string) => {
+    if (url.includes(tokenHost)) return new Response(JSON.stringify({ access_token: "at", expires_in: 3600 }), { status: 200 });
+    return new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json" } });
+  }));
+}
+
+describe("calendar source links", () => {
+  it("returns Google's htmlLink as html_link and cite_as", async () => {
+    vi.stubEnv("GMAIL_CLIENT_ID", "test-client");
+    vi.stubEnv("GMAIL_CLIENT_SECRET", "test-secret");
+    vi.stubEnv("GMAIL_REFRESH_TOKEN", "calendar-source-link-refresh");
+    const htmlLink = "https://www.google.com/calendar/event?eid=ZXZ0MSB1c2VyQGV4YW1wbGUudGVzdA";
+    stubApi("oauth2", { id: "evt1", summary: "Dentist", htmlLink });
+
+    const out = JSON.parse(await calendarGetEventTool.invoke({ event_id: "evt1" })) as Record<string, unknown>;
+
+    expect(out.html_link).toBe(htmlLink);
+    expect(out.cite_as).toBe(`[Dentist](${htmlLink})`);
+  });
+
+  it("returns Outlook's webLink as web_link and cite_as", async () => {
+    vi.stubEnv("OUTLOOK_CLIENT_ID", "test-client");
+    vi.stubEnv("OUTLOOK_CLIENT_SECRET", "test-secret");
+    vi.stubEnv("OUTLOOK_REFRESH_TOKEN", "outlook-calendar-source-link-refresh");
+    const webLink = "https://outlook.office365.com/owa/?itemid=AAMk%3D&exvsurl=1&path=/calendar/item";
+    stubApi("/oauth2/", { id: "evt2", subject: "Standup", webLink });
+
+    const out = JSON.parse(await outlookCalendarGetEventTool.invoke({ event_id: "evt2" })) as Record<string, unknown>;
+
+    expect(out.web_link).toBe(webLink);
+    expect(out.cite_as).toBe(`[Standup](${webLink})`);
+  });
+});
 
 describe("calendar_list_events", () => {
   it("rejects date-only time bounds before calling Google Calendar", async () => {

package/lib/tools/communications/calendar.ts

@@ -25,6 +25,7 @@
 import { tool } from "@langchain/core/tools";
 import { z } from "zod";
 import { registerLangChainPackage } from "../packages/langchain-package";
+import { citeAs } from "@/lib/utils/source-link";
 import {
   googleFetch,
   resolveGoogleAuth,
@@ -94,6 +95,7 @@ function slimEvent(e: CalendarEvent): Record<string, unknown> {
     })),
     meet_link: e.hangoutLink ?? null,
     html_link: e.htmlLink ?? null,
+    cite_as: citeAs(e.summary, e.htmlLink, "Calendar event"),
   };
 }
 

package/lib/tools/communications/gmail.test.ts

@@ -2,10 +2,60 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { gzipSync } from "node:zlib";
 import { googleFetch } from "@/lib/integrations/gmail-oauth";
 
-const { buildRawMessage, gmailCreateDraftTool, gmailModifyMessageTool, gmailSendEmailTool } = await import("./gmail");
+const { buildRawMessage, gmailCreateDraftTool, gmailGetMessageTool, gmailModifyMessageTool, gmailSendEmailTool, gmailWebLink } = await import("./gmail");
 
 afterEach(() => {
   vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+});
+
+describe("gmail source links", () => {
+  it("builds an All Mail thread link scoped to the account", () => {
+    expect(gmailWebLink("18c2f0a1b2c3d4e5", "me+x@example.test"))
+      .toBe("https://mail.google.com/mail/u/me%2Bx%40example.test/#all/18c2f0a1b2c3d4e5");
+    expect(gmailWebLink("18c2f0a1b2c3d4e5", null)).toBe("https://mail.google.com/mail/u/0/#all/18c2f0a1b2c3d4e5");
+  });
+
+  it("refuses ids that are not Gmail API hex ids", () => {
+    expect(gmailWebLink(undefined, null)).toBeNull();
+    expect(gmailWebLink("../inbox", null)).toBeNull();
+    expect(gmailWebLink("18c2f0a1)x", null)).toBeNull();
+  });
+
+  function stubGmail(profile: Response) {
+    vi.stubEnv("GMAIL_CLIENT_ID", "test-client");
+    vi.stubEnv("GMAIL_CLIENT_SECRET", "test-secret");
+    const json = (body: unknown) => new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json" } });
+    vi.stubGlobal("fetch", vi.fn(async (url: string) => {
+      if (url.includes("oauth2")) return json({ access_token: "at", expires_in: 3600 });
+      if (url.endsWith("/profile")) return profile;
+      return json({
+        id: "18c2f0a1b2c3d4e6",
+        threadId: "18c2f0a1b2c3d4e5",
+        payload: { headers: [{ name: "Subject", value: "Invoice [March]" }] },
+      });
+    }));
+  }
+
+  it("returns web_link and cite_as from gmail_get_message", async () => {
+    vi.stubEnv("GMAIL_REFRESH_TOKEN", "gmail-link-ok-refresh-token");
+    stubGmail(new Response(JSON.stringify({ emailAddress: "owner@example.test" }), { status: 200, headers: { "content-type": "application/json" } }));
+
+    const out = JSON.parse(await gmailGetMessageTool.invoke({ id: "18c2f0a1b2c3d4e6" })) as Record<string, unknown>;
+
+    const link = "https://mail.google.com/mail/u/owner%40example.test/#all/18c2f0a1b2c3d4e5";
+    expect(out.web_link).toBe(link);
+    expect(out.cite_as).toBe(`[Invoice \\[March\\]](${link})`);
+  });
+
+  it("falls back to the first signed-in account when the profile lookup fails", async () => {
+    vi.stubEnv("GMAIL_REFRESH_TOKEN", "gmail-link-fail-refresh-token");
+    stubGmail(new Response(JSON.stringify({ error: { message: "forbidden" } }), { status: 403, headers: { "content-type": "application/json" } }));
+
+    const out = JSON.parse(await gmailGetMessageTool.invoke({ id: "18c2f0a1b2c3d4e6" })) as Record<string, unknown>;
+
+    expect(out.web_link).toBe("https://mail.google.com/mail/u/0/#all/18c2f0a1b2c3d4e5");
+  });
 });
 
 describe("gmail tools", () => {

package/lib/tools/communications/gmail.ts

@@ -30,6 +30,7 @@ import {
   type GoogleAuth,
 } from "@/lib/integrations/gmail-oauth";
 import { errorMessage } from "@/lib/utils/error";
+import { citeAs } from "@/lib/utils/source-link";
 
 // Re-export under the old name so existing imports (e.g. the integrations
 // test endpoint) keep working unchanged.
@@ -62,6 +63,38 @@ function resolveGmailAuthForTool(): GmailAuth | { error: string } {
   }
 }
 
+// ── Source links ────────────────────────────────────────────────────────────
+
+// Gmail's web URL scheme is undocumented. `#all/<threadId>` opens the
+// conversation from All Mail whatever its labels, and `/u/<email>/` selects
+// the signed-in account (`/u/0/` is whichever account signed in first).
+const GMAIL_API_ID = /^[0-9a-f]{8,32}$/i;
+
+export function gmailWebLink(threadId: string | null | undefined, account: string | null): string | null {
+  if (!threadId || !GMAIL_API_ID.test(threadId)) return null;
+  const slot = account ? encodeURIComponent(account) : "0";
+  return `https://mail.google.com/mail/u/${slot}/#all/${threadId}`;
+}
+
+const accountEmailCache = new Map<string, Promise<string | null>>();
+
+// getProfile works with every Gmail scope; a failure only drops the account
+// from the link, so it is not retried within the process.
+function gmailAccountEmail(auth: GmailAuth): Promise<string | null> {
+  const key = auth.refresh_token.slice(0, 20);
+  let pending = accountEmailCache.get(key);
+  if (!pending) {
+    pending = gmailFetch(auth, "/profile")
+      .then((p) => {
+        const email = (p as { emailAddress?: unknown }).emailAddress;
+        return typeof email === "string" && email.includes("@") ? email : null;
+      })
+      .catch(() => null);
+    accountEmailCache.set(key, pending);
+  }
+  return pending;
+}
+
 // ── Decoders / helpers ──────────────────────────────────────────────────────
 
 // Gmail uses base64url (no padding, +/ → -_). Node's Buffer handles it directly.
@@ -164,6 +197,7 @@ export const gmailSearchTool = tool(
         messages: [],
       });
     }
+    const account = await gmailAccountEmail(auth);
     // Parallel metadata fetch; the API recommends batching but for ≤100 ids
     // parallel single calls are simpler and well within quota.
     const details = await Promise.all(ids.map(async (id) => {
@@ -172,15 +206,19 @@ export const gmailSearchTool = tool(
         `/messages/${id}?format=metadata&metadataHeaders=From&metadataHeaders=To&metadataHeaders=Subject&metadataHeaders=Date`,
       ) as { id?: string; threadId?: string; snippet?: string; labelIds?: string[]; payload?: { headers?: Header[] }; error?: string };
       if (m.error) return { id, error: m.error };
+      const subject = header(m.payload?.headers, "Subject");
+      const webLink = gmailWebLink(m.threadId, account);
       return {
         id: m.id,
         thread_id: m.threadId,
         from: header(m.payload?.headers, "From"),
         to: header(m.payload?.headers, "To"),
-        subject: header(m.payload?.headers, "Subject"),
+        subject,
         date: header(m.payload?.headers, "Date"),
         snippet: m.snippet ?? null,
         labels: m.labelIds ?? [],
+        web_link: webLink,
+        cite_as: citeAs(subject, webLink, "Gmail message"),
       };
     }));
     return JSON.stringify({
@@ -220,14 +258,18 @@ export const gmailGetMessageTool = tool(
     if (m.error) return JSON.stringify(m);
     const body = extractBody(m.payload);
     const { text: capped, truncated } = truncateBytes(body, MAX_BODY_BYTES);
+    const subject = header(m.payload?.headers, "Subject");
+    const webLink = gmailWebLink(m.threadId, await gmailAccountEmail(auth));
     return JSON.stringify({
       id: m.id,
       thread_id: m.threadId,
+      web_link: webLink,
+      cite_as: citeAs(subject, webLink, "Gmail message"),
       labels: m.labelIds ?? [],
       from: header(m.payload?.headers, "From"),
       to: header(m.payload?.headers, "To"),
       cc: header(m.payload?.headers, "Cc"),
-      subject: header(m.payload?.headers, "Subject"),
+      subject,
       date: header(m.payload?.headers, "Date"),
       message_id: header(m.payload?.headers, "Message-Id") ?? header(m.payload?.headers, "Message-ID"),
       snippet: m.snippet ?? null,

package/lib/tools/communications/outlook-calendar.ts

@@ -19,6 +19,7 @@
 import { tool } from "@langchain/core/tools";
 import { z } from "zod";
 import { registerLangChainPackage } from "../packages/langchain-package";
+import { citeAs } from "@/lib/utils/source-link";
 import {
   graphFetch,
   resolveMicrosoftAuth,
@@ -81,6 +82,7 @@ function slimEvent(e: GraphEvent): Record<string, unknown> {
     show_as: e.showAs ?? null,
     teams_link: e.onlineMeeting?.joinUrl ?? null,
     web_link: e.webLink ?? null,
+    cite_as: citeAs(e.subject, e.webLink, "Outlook event"),
   };
 }
 

package/lib/tools/communications/outlook.test.ts

@@ -1,6 +1,37 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
-const { outlookCreateDraftTool, outlookSendEmailTool } = await import("./outlook");
+const { outlookCreateDraftTool, outlookSearchTool, outlookSendEmailTool } = await import("./outlook");
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+});
+
+describe("outlook source links", () => {
+  it("returns the Graph webLink and a cite_as markdown link per message", async () => {
+    vi.stubEnv("OUTLOOK_CLIENT_ID", "test-client");
+    vi.stubEnv("OUTLOOK_CLIENT_SECRET", "test-secret");
+    vi.stubEnv("OUTLOOK_REFRESH_TOKEN", "outlook-source-link-refresh");
+    const webLink = "https://outlook.office365.com/owa/?ItemID=AAMk%2BA%3D&exvsurl=1&viewmodel=ReadMessageItem";
+    vi.stubGlobal("fetch", vi.fn(async (url: string) => {
+      if (url.includes("/oauth2/")) return new Response(JSON.stringify({ access_token: "at", expires_in: 3600 }), { status: 200 });
+      return new Response(JSON.stringify({
+        value: [
+          { id: "m1", subject: "Budget [Q3]", webLink },
+          { id: "m2", subject: "No link" },
+        ],
+      }), { status: 200, headers: { "content-type": "application/json" } });
+    }));
+
+    const out = JSON.parse(await outlookSearchTool.invoke({ query: "budget" })) as {
+      messages: Array<{ web_link: string | null; cite_as: string | null }>;
+    };
+
+    expect(out.messages[0].web_link).toBe(webLink);
+    expect(out.messages[0].cite_as).toBe(`[Budget \\[Q3\\]](${webLink})`);
+    expect(out.messages[1]).toMatchObject({ web_link: null, cite_as: null });
+  });
+});
 
 describe("outlook_create_draft", () => {
   it("rejects oversized draft bodies before calling Microsoft Graph", async () => {

package/lib/tools/communications/outlook.ts

@@ -14,6 +14,7 @@ import { tool } from "@langchain/core/tools";
 import { z } from "zod";
 import { stripHtml } from "@/lib/utils/html";
 import { truncateBytes } from "@/lib/utils/text";
+import { citeAs } from "@/lib/utils/source-link";
 import { registerLangChainPackage } from "../packages/langchain-package";
 import {
   graphFetch,
@@ -84,6 +85,7 @@ function summarizeMessage(m: GraphMessage): Record<string, unknown> {
     folder_id: m.parentFolderId ?? null,
     snippet: m.bodyPreview ?? null,
     web_link: m.webLink ?? null,
+    cite_as: citeAs(m.subject, m.webLink, "Outlook message"),
   };
 }
 

package/lib/tools/filesystem/edit-match.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildMultipleMatchesDiagnostic,
+  buildNotFoundDiagnostic,
+  conformEol,
+  dominantEol,
+  lineNumberAt,
+  locateOldString,
+} from "./edit-match";
+
+const slice = (raw: string, r: { start: number; end: number }) => raw.slice(r.start, r.end);
+
+describe("locateOldString", () => {
+  it("returns every non-overlapping exact occurrence", () => {
+    const attempt = locateOldString("aaaa", "aa", "exact");
+    expect(attempt.ranges).toEqual([{ start: 0, end: 2 }, { start: 2, end: 4 }]);
+    expect(attempt).toMatchObject({ usedStrategy: "exact", crlfAdjusted: false });
+  });
+
+  it("never matches an empty old_string", () => {
+    expect(locateOldString("abc", "", "fuzzy").ranges).toEqual([]);
+  });
+
+  it("maps an LF old_string onto a CRLF file in raw coordinates", () => {
+    const raw = "one\r\ntwo\r\nthree\r\n";
+    const attempt = locateOldString(raw, "two\nthree\n", "exact");
+    expect(attempt.crlfAdjusted).toBe(true);
+    expect(slice(raw, attempt.ranges[0])).toBe("two\r\nthree\r\n");
+  });
+
+  it("maps a CRLF old_string onto an LF file", () => {
+    const raw = "a\nb\nc";
+    expect(slice(raw, locateOldString(raw, "b\r\nc", "exact").ranges[0])).toBe("b\nc");
+  });
+
+  it("does not apply whitespace strategies unless requested", () => {
+    const raw = "if (x)   {\n  y();\n}";
+    expect(locateOldString(raw, "if (x) {", "exact").ranges).toEqual([]);
+    const attempt = locateOldString(raw, "if (x) {", "normalize_whitespace");
+    expect(attempt.usedStrategy).toBe("normalize_whitespace");
+    expect(slice(raw, attempt.ranges[0])).toBe("if (x)   {");
+  });
+
+  it("matches trailing-whitespace drift and keeps the original text in range", () => {
+    const raw = "alpha  \t\nbeta\n";
+    const attempt = locateOldString(raw, "alpha\nbeta", "trim_trailing");
+    expect(attempt.usedStrategy).toBe("trim_trailing");
+    expect(slice(raw, attempt.ranges[0])).toBe("alpha  \t\nbeta");
+  });
+
+  it("keeps the leading indentation of the file when normalizing whitespace", () => {
+    const raw = "class A {\n    method() {\n        return 1;\n    }\n}";
+    const attempt = locateOldString(raw, "method() {\n return 1;", "normalize_whitespace");
+    expect(slice(raw, attempt.ranges[0])).toBe("method() {\n        return 1;");
+  });
+
+  it("returns a fuzzy range covering whole lines in an LF file", () => {
+    const raw = "header\nconst total = items.reduce((a, b) => a + b, 0);\nfooter\n";
+    const attempt = locateOldString(raw, "const totl = items.reduce((a, b) => a + b, 0);", "fuzzy");
+    expect(attempt.usedStrategy).toBe("fuzzy");
+    expect(slice(raw, attempt.ranges[0])).toBe("const total = items.reduce((a, b) => a + b, 0);");
+  });
+
+  it("returns a fuzzy range in raw coordinates for a CRLF file", () => {
+    const raw = "line one\r\nline two\r\nconst total = items.reduce((a, b) => a + b, 0);\r\nreturn total;\r\n";
+    const attempt = locateOldString(raw, "const totl = items.reduce((a, b) => a + b, 0);\nreturn total;", "fuzzy");
+    expect(attempt.usedStrategy).toBe("fuzzy");
+    expect(slice(raw, attempt.ranges[0])).toBe("const total = items.reduce((a, b) => a + b, 0);\r\nreturn total;");
+  });
+
+  it("returns a fuzzy range in raw coordinates for a classic-Mac CR file", () => {
+    const raw = "first\rsecond\rconst total = items.reduce((a, b) => a + b, 0);\rend";
+    const attempt = locateOldString(raw, "const totl = items.reduce((a, b) => a + b, 0);", "fuzzy");
+    expect(slice(raw, attempt.ranges[0])).toBe("const total = items.reduce((a, b) => a + b, 0);");
+  });
+
+  it("refuses an ambiguous fuzzy match", () => {
+    const line = "const total = items.reduce((a, b) => a + b, 0);";
+    const raw = `${line}\nmiddle\n${line}\n`;
+    expect(locateOldString(raw, line.replace("total", "totl"), "fuzzy").ranges).toEqual([]);
+  });
+
+  it("refuses fuzzy matching for short old_strings", () => {
+    expect(locateOldString("const x = 1;\n", "const x = 2", "fuzzy").ranges).toEqual([]);
+  });
+
+  it("handles non-BMP characters without splitting surrogate pairs", () => {
+    const raw = "emoji 😀 here\r\nnext";
+    const attempt = locateOldString(raw, "😀 here\nnext", "exact");
+    expect(slice(raw, attempt.ranges[0])).toBe("😀 here\r\nnext");
+  });
+});
+
+describe("EOL helpers", () => {
+  it("picks the majority line ending and null for single-line text", () => {
+    expect(dominantEol("a\r\nb\r\nc\n")).toBe("\r\n");
+    expect(dominantEol("a\nb\r\nc\n")).toBe("\n");
+    expect(dominantEol("single line")).toBeNull();
+  });
+
+  it("conforms mixed endings without doubling carriage returns", () => {
+    expect(conformEol("a\r\nb\nc", "\r\n")).toBe("a\r\nb\r\nc");
+    expect(conformEol("a\r\nb\nc", "\n")).toBe("a\nb\nc");
+  });
+
+  it("counts lines up to an offset and clamps past the end", () => {
+    expect(lineNumberAt("a\nb\nc", 0)).toBe(1);
+    expect(lineNumberAt("a\nb\nc", 4)).toBe(3);
+    expect(lineNumberAt("a\nb", 99)).toBe(2);
+  });
+});
+
+describe("diagnostics", () => {
+  it("points at the nearest line and suggests a strategy that would match", () => {
+    const raw = "function run() {\n  doWork(  1 );\n}\n";
+    const diag = buildNotFoundDiagnostic(raw, "doWork( 1 );");
+    expect(diag.nearest_match?.line).toBe(2);
+    expect(diag.nearest_match?.snippet).toContain("2:   doWork(  1 );");
+    expect(diag.normalized_hint).toBe('matches uniquely at line 2 if strategy="normalize_whitespace" is used');
+  });
+
+  it("returns no nearest match for whitespace-only old_strings", () => {
+    const diag = buildNotFoundDiagnostic("abc\n", "   \n  ");
+    expect(diag.nearest_match).toBeNull();
+    expect(diag.normalized_hint).toBeNull();
+  });
+
+  it("reports every occurrence line for multiple matches", () => {
+    const raw = "x\nfoo\ny\nfoo\n";
+    const { ranges } = locateOldString(raw, "foo", "exact");
+    expect(buildMultipleMatchesDiagnostic(raw, ranges)).toEqual({ reason: "multiple_matches", occurrences: [2, 4] });
+  });
+});

package/lib/tools/filesystem/edit-match.ts

@@ -130,10 +130,13 @@ function fuzzyUniqueRange(raw: string, oldString: string): MatchRange[] {
   if (oldLines.some((line) => line.length === 0)) return [];
   const rawLines = raw.split(/\r\n|\r|\n/);
   const rawLineStarts: number[] = [];
+  const eol = /\r\n|\r|\n/g;
   let offset = 0;
   for (const line of rawLines) {
     rawLineStarts.push(offset);
-    offset += line.length + 1;
+    eol.lastIndex = offset + line.length;
+    const brk = eol.exec(raw);
+    offset = offset + line.length + (brk ? brk[0].length : 0);
   }
   const scores: Array<{ score: number; start: number; end: number }> = [];
   for (let i = 0; i + oldLines.length <= rawLines.length; i++) {
@@ -188,7 +191,9 @@ function findAllExact(haystack: string, needle: string): number[] {
 function findWithTransforms(raw: string, oldString: string, fns: Array<(s: string) => Transform>): MatchRange[] {
   const bufT = composeTransforms(raw, fns);
   const oldT = composeTransforms(oldString, fns);
-  if (oldT.text.length === 0) return [];
+  // A needle that normalizes to bare whitespace would match an arbitrary
+  // line break, so it can never identify an edit target.
+  if (oldT.text.trim().length === 0) return [];
   const starts = findAllExact(bufT.text, oldT.text);
   return starts.map((s) => ({
     start: bufT.toOriginal[s],

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

@@ -0,0 +1,131 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, describe, expect, it, vi } from "vitest";
+
+const tmpRoot = mkdtempSync(join(tmpdir(), "jarela-result-refs-"));
+process.env.JARELA_DB_DIR = tmpRoot;
+
+const {
+  getToolResultMaxBytes,
+  parseToolResultReferenceEnvelope,
+  postProcessToolResult,
+  readToolResultRef,
+  serializeToolResult,
+} = await import("./result-refs");
+
+afterEach(() => vi.unstubAllEnvs());
+afterAll(() => rmSync(tmpRoot, { recursive: true, force: true }));
+
+async function spill(result: unknown, maxBytes = 64) {
+  vi.stubEnv("JARELA_TOOL_RESULT_MAX_BYTES", String(maxBytes));
+  const envelope = parseToolResultReferenceEnvelope(await postProcessToolResult("my tool/x", result));
+  if (!envelope) throw new Error("expected a reference envelope");
+  return envelope;
+}
+
+async function readAll(name: string, limit: number) {
+  const pages: string[] = [];
+  let offset: number | null = 0;
+  for (let guard = 0; offset !== null && guard < 10_000; guard++) {
+    const page = await readToolResultRef({ name, offset, limit });
+    expect(page.ok).toBe(true);
+    pages.push(page.result as string);
+    offset = page.next_offset as number | null;
+  }
+  return pages;
+}
+
+describe("max inline bytes", () => {
+  it("ignores invalid overrides", () => {
+    for (const bad of ["0", "-5", "abc", "Infinity"]) {
+      vi.stubEnv("JARELA_TOOL_RESULT_MAX_BYTES", bad);
+      expect(getToolResultMaxBytes()).toBe(16 * 1024);
+    }
+    vi.stubEnv("JARELA_TOOL_RESULT_MAX_BYTES", "100.9");
+    expect(getToolResultMaxBytes()).toBe(100);
+  });
+});
+
+describe("postProcessToolResult", () => {
+  it("passes small results through unchanged", async () => {
+    vi.stubEnv("JARELA_TOOL_RESULT_MAX_BYTES", "1000");
+    expect(await postProcessToolResult("t", { a: 1 })).toBe('{"a":1}');
+    expect(serializeToolResult(undefined)).toBe("undefined");
+  });
+
+  it("measures the limit in bytes, not characters", async () => {
+    vi.stubEnv("JARELA_TOOL_RESULT_MAX_BYTES", "10");
+    // 4 characters, 16 bytes.
+    const out = await postProcessToolResult("t", "😀😀😀😀");
+    expect(parseToolResultReferenceEnvelope(out)?.bytes).toBe(16);
+  });
+
+  it("sanitizes the tool name and records the total array length", async () => {
+    const envelope = await spill(Array.from({ length: 50 }, (_, i) => ({ i })));
+    expect(envelope.result_ref.mimeType).toBe("application/json");
+    expect(envelope.total_count).toBe(50);
+    expect((envelope.preview as unknown[]).length).toBe(20);
+  });
+
+  it("keeps array previews within the preview byte budget when rows are huge", async () => {
+    const rows = Array.from({ length: 3 }, (_, i) => ({ i, body: "x".repeat(50_000) }));
+    const envelope = await spill(rows);
+    expect(envelope.preview_bytes).toBeLessThanOrEqual(4 * 1024);
+    expect(typeof envelope.preview).toBe("string");
+    expect(Buffer.byteLength(envelope.preview as string)).toBe(envelope.preview_bytes);
+    expect(envelope.total_count).toBe(3);
+  });
+
+  it("never ends a text preview on half of a surrogate pair", async () => {
+    const envelope = await spill("a" + "😀".repeat(3000));
+    const preview = envelope.preview as string;
+    expect(Buffer.byteLength(preview)).toBeLessThanOrEqual(4 * 1024);
+    expect(preview.isWellFormed()).toBe(true);
+  });
+});
+
+describe("readToolResultRef", () => {
+  it("pages multi-byte text without corrupting characters at page edges", async () => {
+    const text = "héllo wörld — 日本語のテキスト 😀🎉 ".repeat(40);
+    const envelope = await spill(text);
+    for (const limit of [1, 2, 3, 5, 7, 64]) {
+      const pages = await readAll(envelope.result_ref.name, limit);
+      expect(pages.join("")).toBe(text);
+      expect(pages.every((p) => !p.includes("\uFFFD"))).toBe(true);
+    }
+  });
+
+  it("realigns a caller offset that lands inside a character", async () => {
+    const envelope = await spill("€".repeat(100)); // 3 bytes each
+    const page = await readToolResultRef({ name: envelope.result_ref.name, offset: 4, limit: 6 });
+    expect(page).toMatchObject({ offset: 3, result: "€€", next_offset: 9 });
+  });
+
+  it("returns an empty final page for offsets past the end", async () => {
+    const envelope = await spill("z".repeat(200));
+    const page = await readToolResultRef({ name: envelope.result_ref.name, offset: 10_000 });
+    expect(page).toMatchObject({ ok: true, result: "", next_offset: null, done: true });
+  });
+
+  it("clamps negative and fractional offsets and limits", async () => {
+    const envelope = await spill("abcdefghij".repeat(10));
+    const page = await readToolResultRef({ name: envelope.result_ref.name, offset: -3.7, limit: 2.9 });
+    expect(page).toMatchObject({ offset: 0, limit: 2, result: "ab", next_offset: 2 });
+  });
+
+  it("rejects path traversal and unknown refs without throwing", async () => {
+    expect(await readToolResultRef({ name: "../secrets.json" })).toMatchObject({ ok: false, error: "unsafe result_ref name" });
+    expect(await readToolResultRef({ name: "deadbeef.json" })).toMatchObject({ ok: false, status: "unknown" });
+  });
+});
+
+describe("parseToolResultReferenceEnvelope", () => {
+  it("rejects look-alike payloads", () => {
+    expect(parseToolResultReferenceEnvelope("not json")).toBeNull();
+    expect(parseToolResultReferenceEnvelope({ ok: true, truncated: true, bytes: 1 })).toBeNull();
+    expect(parseToolResultReferenceEnvelope({ ok: true, truncated: "yes", bytes: 1, result_ref: { name: "a" } })).toBeNull();
+    expect(parseToolResultReferenceEnvelope('{"ok":true,"truncated":true,"bytes":"1","result_ref":{"name":"a"}}')).toBeNull();
+    expect(parseToolResultReferenceEnvelope(null)).toBeNull();
+  });
+});