@circuitwall/jarela 2.2.1 → 2.4.0

package/lib/tools/communications/ms-todo.ts

@@ -21,19 +21,12 @@ import { registerLangChainPackage } from "../packages/langchain-package";
 import {
   getMicrosoftAccessToken,
   resolveMicrosoftAuth,
-  type MicrosoftAuth,
 } from "@/lib/integrations/microsoft-oauth";
 
 const msTodoReadTools = optionalTools<StructuredToolInterface>("@circuitwall/ms-todo-langchain", "msTodoReadTools");
 const msTodoWriteTools = optionalTools<StructuredToolInterface>("@circuitwall/ms-todo-langchain", "msTodoWriteTools");
 const setAuthResolver = optionalFunction<(resolver: () => unknown) => void>("@circuitwall/ms-todo-langchain", "setAuthResolver", () => undefined);
 
-// Exposed for the integrations test endpoint, matching the gmail/outlook
-// `_resolveXxxAuth` probe convention.
-export function _resolveMsTodoAuth(): MicrosoftAuth | { error: string } {
-  return resolveMicrosoftAuth();
-}
-
 // Bridge: the package calls this on every tool invocation. We resolve
 // the user's Microsoft credentials from Jarela's encrypted store (or env
 // vars) and exchange them for a short-lived access token via the shared

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/general/memory.ts

@@ -46,7 +46,7 @@ export const memoryUpsertTool = tool(
   {
     name: "memory_upsert",
     description:
-      "Store a durable, structured memory record for proactive semantic recall. Use namespace='facts' for information that should surface in future conversations. Store explicit user preferences, verified facts, decisions, constraints, and reusable project context; do not store transient chat details or secrets. Use an expiry for temporary facts, and status='archived' to soft-retire a record instead of deleting it.",
+      "Store a durable, structured memory record for proactive semantic recall. Use namespace='facts' for information that should surface in future conversations. Store explicit user preferences, verified facts, decisions, constraints, and reusable project context; do not store transient chat details or secrets. Use an expiry for temporary facts, and status='archived' to soft-retire a record instead of deleting it. Save proactively in the same turn the information appears so other agents can use it immediately; do not defer to background compaction.",
     schema: z.object({
       namespace: z.string().describe("Memory namespace. Use 'facts' for proactively recalled durable knowledge."),
       key: z.string().describe("Stable, descriptive key such as 'user-research-preference' or 'project-auth-decision'."),

package/lib/tools/general/workflow-progress.ts

@@ -30,6 +30,7 @@ const workflowProgressSchema = z.object({
   summary: z.string().max(300).optional().describe("Optional short workflow summary shown in the chat checklist."),
   detail: z.string().max(300).optional().describe("Optional live progress text to stream immediately to the UI."),
   needs_attention_reason: z.string().max(300).optional().describe("Optional reason shown when the item or workflow needs user attention."),
+  needs_user: z.boolean().optional().describe("For version_adoption only: set true when item_id cannot progress without the user's input or approval."),
 });
 
 function versionAdoptionPhase(phase: string | undefined): "impact_radius" | "adoption" | "complete" | undefined {
@@ -132,6 +133,7 @@ export const workflowProgressTool = tool(
     name: "workflow_progress",
     description:
       "Report structured progress for a substantial multi-step task. Use only when the task has several dependent phases, likely spans turns, or needs explicit verification; skip simple tasks and work already covered by native tool progress. For agent-created workflows, send the full current items snapshot on every call and reuse the same workflow_id. Keep secrets and private data out of workflow fields. Mark items done only with observed validation evidence; use needs_attention for blockers; phase=complete requires every item done or skipped. " +
+      "A rejected update, or a step left checking or needs_attention at the end of the turn, is retried automatically (at most 3 attempts per step); set needs_user=true on a step that only the user can unblock. " +
       "Every item needs input, expected output, and concrete validation criteria. Completed items also need observed validation_evidence. The system-owned version_adoption workflow has its own durable checklist.",
     schema: workflowProgressSchema,
   },

package/lib/tools/runtime/catalog.ts

@@ -5,10 +5,7 @@ import {
   registeredTools,
   registeredNames,
   registeredCategory,
-  registeredCapability,
-  registeredGroup,
   registeredIntegration,
-  groupForCategory,
   type Capability,
   type ToolCategory,
   type ToolGroup,
@@ -30,7 +27,7 @@ import { isBasicToolCategory, normalizeToolCategory } from "./categories";
 import { isAlwaysOnTool } from "./always-on";
 import { getIntegrationReadiness } from "@/lib/health/probe-cache";
 import { getInjectedSubprocessEnv } from "@/lib/env/allowlist";
-import { getAllTools, getAllToolsAsync } from "./runtime";
+import { getAllTools } from "./runtime";
 
 export type ToolSource = "builtin" | "external" | "mcp";
 export type ToolStatus = "enabled" | "disabled" | "unavailable";
@@ -94,10 +91,6 @@ export function getToolSource(name: string): ToolSource {
   return "mcp";
 }
 
-export function getToolCapability(name: string): Capability {
-  return registeredCapability(name) ?? "execute";
-}
-
 export function getToolCategory(name: string): ToolCategory {
   const builtin = registeredCategory(name);
   if (builtin) return builtin;
@@ -108,16 +101,6 @@ export function getToolCategory(name: string): ToolCategory {
   return normalizeToolCategory(mcpCat) as ToolCategory;
 }
 
-export function getToolGroup(name: string): ToolGroup {
-  const cat = getToolCategory(name);
-  if (cat === "MCP") return null;
-  const builtinGroup = registeredGroup(name);
-  if (builtinGroup !== undefined) return builtinGroup;
-  const mcpGroup = getMcpToolMeta(name)?.group;
-  if (mcpGroup !== undefined) return mcpGroup as ToolGroup;
-  return groupForCategory(cat);
-}
-
 export function getToolCredentialsRequired(name: string): string[] {
   if (registeredCategory(name)) return [];
   const ext = loadExternal().credentialsRequired.get(name);
@@ -160,13 +143,6 @@ export function getDefaultAgentToolNames(): string[] {
     .map((t) => t.name);
 }
 
-export async function getDefaultAgentToolNamesAsync(): Promise<string[]> {
-  const tools = await getAllToolsAsync();
-  return tools
-    .filter((t) => isDefaultBasicTool(t.name, getToolCategory(t.name)))
-    .map((t) => t.name);
-}
-
 function isDefaultBasicTool(name: string, category: string): boolean {
   return isBasicToolCategory(category) && !DEFAULT_EXCLUDED_BASIC_TOOLS.has(name);
 }

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();
+  });
+});

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/triggers/registry.ts

@@ -14,10 +14,6 @@ export function registerTriggerHandler(handler: TriggerHandler): void {
   state.handlers.set(handler.kind, handler);
 }
 
-export function getTriggerHandler(kind: string): TriggerHandler | undefined {
-  return state.handlers.get(kind);
-}
-
 export function listTriggerHandlers(): TriggerHandler[] {
   return Array.from(state.handlers.values());
 }

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);
+  });
+});