@circuitwall/jarela 2.3.0 → 2.5.0

package/lib/stores/proxy-config.test.ts

@@ -0,0 +1,120 @@
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const tmpRoot = mkdtempSync(join(tmpdir(), "jarela-test-proxy-config-"));
+process.env.JARELA_DB_DIR = tmpRoot;
+
+const store = await import("./proxy-config");
+const { getDb } = await import("@/lib/db");
+const { SECRET_MASK } = await import("./integrations");
+
+afterAll(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* */ }
+});
+
+const PEM = "-----BEGIN CERTIFICATE-----\nMIIBfake\n-----END CERTIFICATE-----\n";
+
+function storedPasswordColumn(): string | null {
+  const row = getDb().prepare("SELECT password FROM proxy_config WHERE id = 1").get() as { password: string | null } | undefined;
+  return row?.password ?? null;
+}
+
+describe("proxy-config store", () => {
+  beforeEach(() => {
+    getDb().exec("DELETE FROM proxy_config");
+  });
+
+  it("returns the default off status before anything is saved", () => {
+    expect(store.getProxyConfigStatus()).toMatchObject({ mode: "off", scheme: "http", host: null, password: null });
+    expect(store.getProxyConfigRaw()).toBeNull();
+    expect(store.deleteProxyConfig()).toBe(false);
+  });
+
+  it("encrypts the password at rest, masks it in status and decrypts it for the dispatcher", () => {
+    const saved = store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, username: "u", password: "p@ss:word" });
+    expect(saved).toMatchObject({ mode: "manual", host: "proxy.corp", port: 3128, password: SECRET_MASK });
+    expect(storedPasswordColumn()).not.toContain("p@ss:word");
+    expect(store.getProxyConfigRaw()?.password).toBe("p@ss:word");
+  });
+
+  it("keeps the existing password when the UI echoes the mask back, without re-encrypting it", () => {
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, username: "u", password: "secret" });
+    const before = storedPasswordColumn();
+    store.saveProxyConfig({ mode: "manual", host: "proxy2.corp", port: 8080, username: "u", password: SECRET_MASK });
+    expect(storedPasswordColumn()).toBe(before);
+    expect(store.getProxyConfigRaw()).toMatchObject({ host: "proxy2.corp", port: 8080, password: "secret" });
+  });
+
+  it("never stores the mask itself as a password when none existed", () => {
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, password: SECRET_MASK });
+    expect(store.getProxyConfigRaw()?.password).toBeNull();
+    expect(store.getProxyConfigStatus().password).toBeNull();
+  });
+
+  it("clears the password when an empty string or null is sent", () => {
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, password: "secret" });
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, password: "" });
+    expect(store.getProxyConfigRaw()?.password).toBeNull();
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, password: "secret" });
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128, password: null });
+    expect(store.getProxyConfigRaw()?.password).toBeNull();
+  });
+
+  it("trims host, username and no_proxy and stores blanks as null", () => {
+    store.saveProxyConfig({ mode: "manual", host: "  proxy.corp  ", port: 3128, username: "   ", no_proxy: "  " });
+    expect(store.getProxyConfigRaw()).toMatchObject({ host: "proxy.corp", username: null, no_proxy: null });
+  });
+
+  it.each([
+    ["a URL with a scheme", "http://proxy.corp"],
+    ["a host with a port", "proxy.corp:8080"],
+    ["a hex-only host with a port", "dead.beef:3128"],
+    ["a host with a path", "proxy.corp/pac"],
+    ["a host with credentials", "user:pw@proxy.corp"],
+    ["a host with spaces", "proxy corp"],
+  ])("rejects %s in manual mode instead of building a broken proxy URL", (_label, host) => {
+    const result = store.saveProxyConfig({ mode: "manual", host, port: 3128 });
+    expect(result).toHaveProperty("error");
+    expect((result as { error: string }).error).toMatch(/host/i);
+    expect(store.getProxyConfigRaw()).toBeNull();
+  });
+
+  it.each([
+    ["fd00::1", "fd00::1"],
+    ["[fd00::1]", "fd00::1"],
+    ["10.0.0.5", "10.0.0.5"],
+    ["proxy-1.corp.example", "proxy-1.corp.example"],
+  ])("accepts host %s and stores it as %s", (input, stored) => {
+    const result = store.saveProxyConfig({ mode: "manual", host: input, port: 3128 });
+    expect(result).not.toHaveProperty("error");
+    expect(store.getProxyConfigRaw()?.host).toBe(stored);
+  });
+
+  it.each([0, -1, 65536, 3128.5, Number.NaN, Number.POSITIVE_INFINITY])("rejects port %s", (port) => {
+    expect(store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port })).toHaveProperty("error");
+  });
+
+  it("requires host and port only in manual mode", () => {
+    expect(store.saveProxyConfig({ mode: "manual", port: 3128 })).toHaveProperty("error");
+    expect(store.saveProxyConfig({ mode: "manual", host: "proxy.corp" })).toHaveProperty("error");
+    expect(store.saveProxyConfig({ mode: "system" })).toMatchObject({ mode: "system" });
+    expect(store.saveProxyConfig({ mode: "off" })).toMatchObject({ mode: "off" });
+  });
+
+  it("rejects an invalid mode and a non-PEM CA bundle, and clears a blank bundle", () => {
+    expect(store.saveProxyConfig({ mode: "auto" as never })).toHaveProperty("error");
+    expect(store.saveProxyConfig({ mode: "off", ca_bundle: "not a cert" })).toHaveProperty("error");
+    store.saveProxyConfig({ mode: "off", ca_bundle: PEM });
+    expect(store.getProxyConfigRaw()?.ca_bundle).toBe(PEM);
+    store.saveProxyConfig({ mode: "off", ca_bundle: "   " });
+    expect(store.getProxyConfigRaw()?.ca_bundle).toBeNull();
+  });
+
+  it("normalises an unknown persisted scheme to http", () => {
+    store.saveProxyConfig({ mode: "manual", host: "proxy.corp", port: 3128 });
+    getDb().prepare("UPDATE proxy_config SET scheme = 'socks5' WHERE id = 1").run();
+    expect(store.getProxyConfigRaw()).toMatchObject({ mode: "manual", scheme: "http" });
+  });
+});

package/lib/stores/proxy-config.ts

@@ -15,6 +15,7 @@
 // existing password" so the UI can echo back the masked form without
 // blanking the secret.
 
+import { isIPv6 } from "node:net";
 import { getDb } from "@/lib/db";
 import { decryptIfNeeded, encrypt } from "@/lib/crypto/envelope";
 import { SECRET_MASK } from "@/lib/stores/integrations";
@@ -122,11 +123,18 @@ export function saveProxyConfig(input: ProxyConfigInput): ProxyConfigStatus | {
   const scheme: ProxyScheme = input.scheme === "https" ? "https" : "http";
 
   // Manual mode requires host + port. system / off don't.
+  let host = nullable(input.host);
   if (input.mode === "manual") {
-    if (!input.host || !input.host.trim()) return { error: "host is required in manual mode" };
-    if (input.port == null || !Number.isFinite(input.port) || input.port <= 0 || input.port > 65535) {
-      return { error: "port must be between 1 and 65535" };
+    if (!host) return { error: "host is required in manual mode" };
+    const normalisedHost = normaliseProxyHost(host);
+    if (!normalisedHost) {
+      return { error: "host must be a hostname or IP address, without scheme, port, path or credentials" };
     }
+    host = normalisedHost;
+    if (input.port == null) return { error: "port must be between 1 and 65535" };
+  }
+  if (input.port != null && (!Number.isInteger(input.port) || input.port <= 0 || input.port > 65535)) {
+    return { error: "port must be between 1 and 65535" };
   }
 
   // CA bundle: empty/null clears; non-empty must look like PEM.
@@ -167,7 +175,7 @@ export function saveProxyConfig(input: ProxyConfigInput): ProxyConfigStatus | {
   ).run(
     input.mode,
     scheme,
-    nullable(input.host),
+    host,
     input.port ?? null,
     nullable(input.username),
     storedPassword,
@@ -207,6 +215,16 @@ function normaliseScheme(s: string | null | undefined): ProxyScheme {
   return s === "https" ? "https" : "http";
 }
 
+// The dispatcher builds `${scheme}://${auth}${host}:${port}`, so a pasted URL
+// or host:port would produce an unusable proxy URL. IPv6 is stored unbracketed;
+// the dispatcher adds the brackets.
+function normaliseProxyHost(host: string): string | null {
+  const unbracketed = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  if (/^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$/.test(unbracketed)) return unbracketed;
+  if (isIPv6(unbracketed)) return unbracketed;
+  return null;
+}
+
 function nullable(v: string | null | undefined): string | null {
   if (v == null) return null;
   const trimmed = v.trim();

package/lib/stores/threads.ts

@@ -157,11 +157,15 @@ export function getThreadMessageBySeq(thread_id: string, seq: number): MessageRo
   return (getDb().prepare(MSG_COLS_SQL + " WHERE thread_id=? AND rowid=?").get(thread_id, seq) as unknown as MessageRow | undefined) ?? null;
 }
 
-export function countThreadMessagesFromSeq(thread_id: string, seq: number): number {
-  const row = getDb().prepare("SELECT COUNT(*) AS n FROM messages WHERE thread_id=? AND rowid>=?").get(thread_id, seq) as { n: number } | undefined;
+
+// Rows that size compaction can prune: automation-channel rows are kept
+// (see pruneThreadMessages), so they must not count toward its trigger.
+export function countForegroundThreadMessages(thread_id: string, fromSeq = 0): number {
+  const row = getDb()
+    .prepare("SELECT COUNT(*) AS n FROM messages WHERE thread_id=? AND rowid>=? AND " + foregroundCategoryGuardSql())
+    .get(thread_id, fromSeq, ...FOREGROUND_EXCLUDED_CATEGORIES) as { n: number } | undefined;
   return row?.n ?? 0;
 }
-
 export function isValidThreadContextCursor(thread_id: string, seq: number): boolean {
   if (getThreadMessageBySeq(thread_id, seq)) return true;
   return getThread(thread_id)?.hot_since_seq === seq;
@@ -733,11 +737,11 @@ export function setThreadContextPin(thread_id: string, hot_since: string | null,
     .run(hot_since, hot_since === null ? null : hot_since_seq!, thread_id);
 }
 
-// Called by moveThreadContextBoundary whenever the user explicitly moves the
-// boundary (drag, or manual /compact) — never by the auto-detector's own
-// commit path, which calls setThreadContextPin directly. `untilMessageCount`
-// is a one-time write; the read side (lib/agents/run-thread.ts) just compares
-// against it, no per-turn write needed.
+// Armed by moveThreadContextBoundary whenever the user explicitly moves the
+// boundary (drag, or manual /compact), and by the auto-detector's hot-turn
+// cooldown when a compaction pass ends without a commit (a commit writes the
+// lock in the same transaction). `untilMessageCount` is a one-time write; the
+// read side (lib/agents/run-thread.ts) just compares against it.
 export function setAutoBoundaryLock(thread_id: string, untilMessageCount: number): void {
   getDb()
     .prepare("UPDATE threads SET auto_boundary_locked_until_msg_count=? WHERE thread_id=?")

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