@circuitwall/jarela 2.3.0 → 2.5.0

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/packages/default-packages.test.ts

@@ -14,6 +14,7 @@ const {
   registerDefaultPackages,
   _resetDefaultPackages,
 } = await import("./default-packages");
+const { registeredTools, registeredCategory, registeredCapability } = await import("../runtime/registry");
 
 const { setPackageDisabled, listDisabledPackages } = await import(
   "@/lib/stores/disabled-packages"
@@ -52,6 +53,26 @@ describe("default LangChain packages", () => {
     expect(listDefaultPackages().every((p) => p.installed === false)).toBe(true);
   });
 
+  it("registers workspace packages with their declared categories and capabilities", () => {
+    const previousPackagesDir = process.env.JARELA_PACKAGES_DIR;
+    process.env.JARELA_PACKAGES_DIR = "";
+    try {
+      registerDefaultPackages();
+
+      expect(listDefaultPackages().every((p) => p.installed)).toBe(true);
+      const tools = registeredTools();
+      expect(tools.length).toBeGreaterThan(0);
+      for (const tool of tools) {
+        expect(registeredCategory(tool.name)).toBeDefined();
+        expect(["read", "write", "execute"]).toContain(registeredCapability(tool.name));
+      }
+    } finally {
+      _resetDefaultPackages();
+      if (previousPackagesDir === undefined) delete process.env.JARELA_PACKAGES_DIR;
+      else process.env.JARELA_PACKAGES_DIR = previousPackagesDir;
+    }
+  });
+
   it("findDefaultPackage returns the descriptor for a known id", () => {
     const d = findDefaultPackage("github");
     expect(d).not.toBeNull();

package/lib/tools/packages/optional-package.test.ts

@@ -0,0 +1,72 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { isOptionalPackageInstalled, loadOptionalPackage } from "./optional-package";
+
+describe("optional package resolution", () => {
+  let managedDir: string;
+  let originalPackagesDir: string | undefined;
+
+  beforeEach(() => {
+    originalPackagesDir = process.env.JARELA_PACKAGES_DIR;
+    managedDir = mkdtempSync(join(tmpdir(), "jarela-optional-packages-"));
+    process.env.JARELA_PACKAGES_DIR = managedDir;
+  });
+
+  afterEach(() => {
+    if (originalPackagesDir === undefined) delete process.env.JARELA_PACKAGES_DIR;
+    else process.env.JARELA_PACKAGES_DIR = originalPackagesDir;
+    rmSync(managedDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("prefers a package installed in the managed packages directory", () => {
+    const packageDir = join(managedDir, "node_modules", "fake-optional-package");
+    mkdirSync(packageDir, { recursive: true });
+    writeFileSync(join(packageDir, "package.json"), JSON.stringify({
+      name: "fake-optional-package",
+      version: "1.0.0",
+      main: "index.cjs",
+    }));
+    writeFileSync(join(packageDir, "index.cjs"), 'module.exports = { source: "managed" };');
+
+    expect(loadOptionalPackage("fake-optional-package")).toEqual({ source: "managed" });
+  });
+
+  it.each([
+    "@circuitwall/atlassian-langchain",
+    "@circuitwall/github-langchain",
+    "@circuitwall/icloud-langchain",
+    "@circuitwall/jira-align-langchain",
+    "@circuitwall/ms-todo-langchain",
+  ])("falls back to the app workspace for %s", (packageName) => {
+    delete process.env.JARELA_PACKAGES_DIR;
+    expect(loadOptionalPackage(packageName)).not.toBeNull();
+    expect(isOptionalPackageInstalled(packageName)).toBe(true);
+  });
+
+  it("exposes exports from the workspace fallback", () => {
+    delete process.env.JARELA_PACKAGES_DIR;
+    const loaded = loadOptionalPackage<{ githubFetch?: unknown }>("@circuitwall/github-langchain");
+
+    expect(loaded).not.toBeNull();
+    expect(typeof loaded?.githubFetch).toBe("function");
+  });
+
+  it("treats an absent optional package as a normal miss", () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    expect(loadOptionalPackage("@circuitwall/not-installed")).toBeNull();
+    expect(error).not.toHaveBeenCalled();
+  });
+
+  it("does not treat unrelated app dependencies as installed optional packages", () => {
+    expect(loadOptionalPackage("@langchain/core")).toBeNull();
+  });
+
+  it("honors an explicit managed directory even when a workspace package exists", () => {
+    expect(loadOptionalPackage("@circuitwall/github-langchain")).toBeNull();
+    expect(isOptionalPackageInstalled("@circuitwall/github-langchain")).toBe(false);
+  });
+});

package/lib/tools/packages/optional-package.ts

@@ -22,12 +22,40 @@ function managedPackagePath(packageName: string): string {
   return join(getPackagesDir(), "node_modules", packageName);
 }
 
+interface ResolvedOptionalPackage {
+  req: OptionalRequire;
+  path: string;
+}
+
+function resolveOptionalPackage(packageName: string): ResolvedOptionalPackage | null {
+  const managedReq = createRuntimeRequire(join(getPackagesDir(), "_anchor"));
+  try {
+    return {
+      req: managedReq,
+      path: managedReq.resolve(managedPackagePath(packageName)),
+    };
+  } catch {
+    // Workspace builds expose bundled @circuitwall packages from the app root.
+  }
+
+  if (process.env.JARELA_PACKAGES_DIR?.trim()) return null;
+  if (!packageName.startsWith("@circuitwall/")) return null;
+
+  const appReq = createRuntimeRequire(join(process.cwd(), "package.json"));
+  try {
+    return { req: appReq, path: appReq.resolve(packageName) };
+  } catch {
+    return null;
+  }
+}
+
 export function loadOptionalPackage<T extends AnyModule>(packageName: string): T | null {
   const override = testOverrides.get(packageName);
   if (override) return override as T;
+  const resolved = resolveOptionalPackage(packageName);
+  if (!resolved) return null;
   try {
-    const req = createRuntimeRequire(join(getPackagesDir(), "_anchor"));
-    return req(managedPackagePath(packageName)) as T;
+    return resolved.req(resolved.path) as T;
   } catch (err) {
     // Keep the optional boundary non-fatal, but leave the actual load failure
     // visible so missing peer dependencies are diagnosable from server logs.
@@ -68,9 +96,10 @@ export function optionalFunction<T extends (...args: any[]) => any>(
 }
 
 export function isOptionalPackageInstalled(packageName: string): boolean {
+  const resolved = resolveOptionalPackage(packageName);
+  if (!resolved) return false;
   try {
-    const req = createRuntimeRequire(join(getPackagesDir(), "_anchor"));
-    req(managedPackagePath(packageName));
+    resolved.req(resolved.path);
     return true;
   } catch (err) {
     console.error(`[optional-package] failed to load ${packageName}: ${err instanceof Error ? err.message : String(err)}`);

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/ui/navigate.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+import { parseHref } from "./navigate";
+
+describe("parseHref legacy Knowledge routes", () => {
+  it.each([
+    "/?tab=documents",
+    "/?tab=memory",
+    "/?tab=tools&item=documents",
+    "/?tab=tools&item=memory",
+  ])("routes %s to Knowledge", (href) => {
+    expect(parseHref(href)).toMatchObject({ tab: "memory", item: undefined, external: false });
+  });
+});

package/lib/ui/navigate.ts

@@ -40,8 +40,16 @@ export function parseHref(input: string | null | undefined): ParsedHref {
 
   const params = new URLSearchParams(queryStr);
   const tabRaw = params.get("tab");
-  const tab = TABS.includes(tabRaw as Tab) ? (tabRaw as Tab) : undefined;
-  const item = params.get("item") ?? undefined;
+  let tab = TABS.includes(tabRaw as Tab) ? (tabRaw as Tab) : undefined;
+  let item = params.get("item") ?? undefined;
+  if (
+    tab === "documents" ||
+    tab === "memory" ||
+    (tab === "tools" && (item === "memory" || item === "documents"))
+  ) {
+    tab = "memory";
+    item = undefined;
+  }
   const thread = params.get("thread") ?? undefined;
   const agent = params.get("agent") ?? undefined;
   return { tab, item, thread, agent, hash, external: false };

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.5.0",
   "description": "Jarela — local chat interface for LangGraph agents (multi-provider, single-process, SQLite-backed).",
   "license": "Apache-2.0",
   "author": "Andrew Ge Wu",