@circuitwall/jarela 2.2.1 → 2.4.0

package/lib/stores/version-adoption.ts

@@ -3,6 +3,12 @@ import { getMemory, putMemory } from "@/lib/stores/memory";
 import { getDefaultAgentConfig } from "@/lib/stores/agent-configs";
 import { getOrCreateAgentThread } from "@/lib/stores/threads";
 import { getCurrentVersion } from "@/lib/lifecycle/version";
+import {
+  changesetsBetween,
+  formatChangesetsForPrompt,
+  summarizeChangesets,
+  type ChangesetRange,
+} from "@/lib/lifecycle/changesets";
 import {
   completeWorkflow,
   mergeWorkflowProgress,
@@ -34,6 +40,7 @@ export interface VersionAdoptionChecklistItem {
   validation: string;
   status: VersionAdoptionChecklistStatus;
   validation_evidence?: string;
+  attempts?: number;
   reason: string;
   affected_files: string[];
   action?: VersionAdoptionAction;
@@ -62,6 +69,9 @@ type StoredVersionAdoptionState = VersionAdoptionState & {
   last_adopted_version: string | null;
 };
 
+/** A client request that cannot be applied to the current adoption state. */
+export class VersionAdoptionRequestError extends Error {}
+
 const DEFAULT_CHECKLIST: VersionAdoptionChecklistItem[] = [
   {
     id: "instructions",
@@ -102,9 +112,9 @@ const PHASE_1_CHECKLIST: VersionAdoptionChecklistItem[] = [
   {
     id: "fetch-changes",
     label: "Fetch changes",
-    input: "Previously adopted version tag and current repository HEAD.",
-    output: "The changed-file list between the baseline and current version.",
-    validation: "Use the system-computed git diff result; if no baseline is available, explicitly identify first-adoption status.",
+    input: "Previously adopted version, current version, the bundled release changesets, and git history when running from a source checkout.",
+    output: "The prompt and tool description/schema deltas from the release changesets, or the changed-file list from git, between the baseline and current version.",
+    validation: "Use the system-computed changeset or git diff result; if no baseline is available, explicitly identify first-adoption status.",
     status: "pending",
     reason: "Compare the current version with the previously adopted version or baseline.",
     affected_files: [],
@@ -112,9 +122,9 @@ const PHASE_1_CHECKLIST: VersionAdoptionChecklistItem[] = [
   {
     id: "build-todo-list",
     label: "Build todo list",
-    input: "System-computed changed-file list and classified adoption surfaces.",
+    input: "System-computed change surface and classified adoption surfaces.",
     output: "A Phase 2 checklist covering all matched changes and a fallback review for unmatched changes.",
-    validation: "Check that every changed path is represented by an adoption item or explicitly covered by the fallback.",
+    validation: "Check that every changed prompt, tool, or path is represented by an adoption item or explicitly covered by the fallback.",
     status: "pending",
     reason: "Turn detected version changes into the concrete Phase 2 adoption checklist.",
     affected_files: [],
@@ -192,6 +202,7 @@ function normalizeChecklistItem(value: unknown): VersionAdoptionChecklistItem |
       ? item.validation
       : "Verify findings against the affected files; report unavailable evidence instead of inferring.",
     ...(validationEvidence ? { validation_evidence: validationEvidence } : {}),
+    ...(typeof item.attempts === "number" && Number.isInteger(item.attempts) && item.attempts > 0 ? { attempts: item.attempts } : {}),
     ...(isVersionAdoptionAction(item.action) ? { action: item.action } : {}),
   };
 }
@@ -262,12 +273,118 @@ function item(
   };
 }
 
-function buildChecklist(previousVersion: string | null, currentVersion: string): VersionAdoptionChecklistItem[] {
-  if (!previousVersion) {
-    return DEFAULT_CHECKLIST.map((entry) => ({ ...entry }));
+type ChangeSource = "changeset" | "git" | "none";
+
+interface AdoptionPlan {
+  items: VersionAdoptionChecklistItem[];
+  source: ChangeSource;
+  range: ChangesetRange | null;
+}
+
+function changesetChecklist(previousVersion: string, range: ChangesetRange): VersionAdoptionChecklistItem[] {
+  const summary = summarizeChangesets(range.entries);
+  const toolRefs = summary.toolNames.map((name) => `tool:${name}`);
+  const promptRefs = summary.promptIds.map((id) => `prompt:${id}`);
+  const removed = summary.removedTools.length > 0 ? ` Removed tools: ${summary.removedTools.join(", ")}.` : "";
+  const items: VersionAdoptionChecklistItem[] = [];
+  const surfaceItem = (
+    entry: Omit<VersionAdoptionChecklistItem, "status" | "affected_files"> & { refs: string[] },
+  ): VersionAdoptionChecklistItem => {
+    const { refs, ...rest } = entry;
+    return { ...rest, status: "pending", affected_files: refs.slice(0, 12) };
+  };
+
+  if (summary.toolNames.length > 0) {
+    items.push(surfaceItem({
+      id: "adapt-settings",
+      label: "Adapt agent settings to tool changes",
+      reason: `${summary.toolNames.length} built-in tool(s) changed description or schema since ${previousVersion}.${removed}`,
+      input: "Release changeset tool deltas, every agent's configuration from read_agent_config (tool allowlist and delegate targets), and the live catalog from list_tools.",
+      output: "Per agent: proposed settings edits for allowlists that reference removed tools or should include changed tools the user relies on, or an explicit no-change finding.",
+      validation: "After approved edits, re-read each agent with read_agent_config and confirm every allowlisted tool name exists in list_tools; name every agent checked.",
+      action: "review_permissions",
+      refs: toolRefs,
+    }));
+  }
+  if (summary.toolNames.length > 0 || summary.promptIds.length > 0) {
+    items.push(surfaceItem({
+      id: "adapt-task-prompts",
+      label: "Adapt scheduled task and watcher prompts",
+      reason: "Long-lived task and watcher prompts can reference changed tools or parameters, or repeat built-in guidance that changed.",
+      input: "Release changeset tool and prompt deltas, plus every prompt returned by list_scheduled_tasks and list_watchers.",
+      output: "For each affected task or watcher: current prompt, proposed prompt, and the changeset delta that motivates it; unaffected ones listed as checked.",
+      validation: "After approved update_scheduled_task / update_watcher calls, re-list and confirm each stored prompt equals the approved text and names only tools present in list_tools.",
+      action: "review_schedule",
+      refs: [...toolRefs, ...promptRefs],
+    }));
+    items.push(surfaceItem({
+      id: "adapt-instructions-skills",
+      label: "Adapt agent instructions and skills",
+      reason: "Agent instructions and user skills can reference changed tools or parameters, or duplicate or contradict changed built-in prompt guidance.",
+      input: "Release changeset prompt and tool deltas, each agent's instructions from read_agent_instruction, and user skills from list_skills / read_skill.",
+      output: "For each affected instruction or skill: before and after text and the changeset delta that motivates it; unaffected ones listed as checked.",
+      validation: "After approved update_agent_instruction / write_skill calls, re-read each artifact and confirm the stored text matches and names only tools and parameters present in list_tools and the changed schemas.",
+      action: "read_skill",
+      refs: [...promptRefs, ...toolRefs],
+    }));
+  }
+  if (summary.hints.length > 0) {
+    items.push(surfaceItem({
+      id: "release-hints",
+      label: "Apply release adoption hints",
+      reason: `The release notes include ${summary.hints.length} adoption hint(s) from the maintainers.`,
+      input: `Adoption hints: ${summary.hints.join(" | ")}`,
+      output: "Each hint applied to the user's setup, or a finding that it does not apply.",
+      validation: "For each hint, cite the artifact or setting checked and re-read anything changed.",
+      action: "review_release",
+      refs: [],
+    }));
+  }
+  if (!range.complete) {
+    items.push(surfaceItem({
+      id: "version-diff",
+      label: "Review changes not covered by changesets",
+      reason: `Bundled changesets do not fully cover ${previousVersion} → current; older releases predate changesets.`,
+      input: "The available changesets and the changelog for the uncovered versions.",
+      output: "Findings for uncovered versions and any required adoption actions.",
+      validation: "State which versions were covered by changesets and which only by the changelog.",
+      action: "review_release",
+      refs: [],
+    }));
   }
+  if (items.length === 0) {
+    items.push(surfaceItem({
+      id: "version-diff",
+      label: "Review version changes",
+      reason: "Release changesets report no prompt or tool description/schema changes; user prompts, skills, and settings need no adaptation.",
+      input: "Release changesets for the version range.",
+      output: "Confirmation that no adaptation is required.",
+      validation: "Confirm each changeset in the range lists no tool or prompt changes and no adoption hints.",
+      action: "review_release",
+      refs: [],
+    }));
+    items[0].status = "skipped";
+  }
+  return items;
+}
 
+function computeAdoptionPlan(previousVersion: string | null, currentVersion: string): AdoptionPlan {
+  if (!previousVersion) {
+    return { items: DEFAULT_CHECKLIST.map((entry) => ({ ...entry })), source: "none", range: null };
+  }
+  const range = changesetsBetween(previousVersion, currentVersion);
+  if (range.entries.length > 0) {
+    return { items: changesetChecklist(previousVersion, range), source: "changeset", range };
+  }
   const files = changedFiles(previousVersion, currentVersion);
+  return { items: gitChecklist(files), source: files.length > 0 ? "git" : "none", range: null };
+}
+
+function buildChecklist(previousVersion: string | null, currentVersion: string): VersionAdoptionChecklistItem[] {
+  return computeAdoptionPlan(previousVersion, currentVersion).items;
+}
+
+function gitChecklist(files: readonly string[]): VersionAdoptionChecklistItem[] {
   const dynamic = [
     item(
       "permissions",
@@ -353,26 +470,35 @@ function phase1Checklist(): VersionAdoptionChecklistItem[] {
   return PHASE_1_CHECKLIST.map((entry) => ({ ...entry }));
 }
 
-// `fetch-changes` never needs an agent tool call: the git diff it reports
-// on already ran synchronously in createState() (via buildChecklist), so
-// the item starts pre-completed with the deterministic result baked into
-// its reason. Only `build-todo-list` is left for the agent to actually do.
+// `fetch-changes` never needs an agent tool call: the changeset read or git
+// diff it reports on already ran synchronously in createState() (via
+// computeAdoptionPlan), so the item starts pre-completed with the
+// deterministic result baked into its reason. Only `build-todo-list` is left
+// for the agent to actually do.
 function resolvedPhase1Checklist(
-  adoptionChecklist: readonly VersionAdoptionChecklistItem[],
+  plan: AdoptionPlan,
   isFirst: boolean,
 ): VersionAdoptionChecklistItem[] {
   const [fetchChanges, ...rest] = phase1Checklist();
+  const adoptionChecklist = plan.items;
   const affectedCount = adoptionChecklist.reduce((n, entry) => n + entry.affected_files.length, 0);
+  const changesetVersions = plan.range?.entries.map((entry) => entry.version).join(", ") ?? "";
+  const evidence = isFirst
+    ? "System confirmed that this is the first adoption and no prior baseline exists."
+    : plan.source === "changeset"
+      ? `System read bundled release changesets for ${changesetVersions}${plan.range?.complete ? "" : " (partial coverage)"}; ${affectedCount} changed prompt/tool surface reference(s) were counted.`
+      : `System computed the changed-file surface against the prior version; ${affectedCount} affected file(s) were counted.`;
+  const reason = isFirst
+    ? "First adoption — no previously adopted version to diff against."
+    : plan.source === "changeset"
+      ? `Read deterministically from the bundled release changesets (prompt and tool description/schema deltas): ${affectedCount} surface reference(s) across ${adoptionChecklist.length} area(s).`
+      : `Computed deterministically via git diff against the previously adopted version: ${affectedCount} affected file(s) across ${adoptionChecklist.length} area(s).`;
   return [
     {
       ...fetchChanges,
       status: "done",
-      validation_evidence: isFirst
-        ? "System confirmed that this is the first adoption and no prior baseline exists."
-        : `System computed the changed-file surface against the prior version; ${affectedCount} affected file(s) were counted.`,
-      reason: isFirst
-        ? "First adoption — no previously adopted version to diff against."
-        : `Computed deterministically via git diff against the previously adopted version: ${affectedCount} affected file(s) across ${adoptionChecklist.length} area(s).`,
+      validation_evidence: evidence,
+      reason,
     },
     ...rest,
   ];
@@ -380,7 +506,8 @@ function resolvedPhase1Checklist(
 
 function stalePromptRisks(checklist: readonly VersionAdoptionChecklistItem[]): string[] {
   return checklist
-    .filter((item) => item.id === "skills-instructions" || item.id === "scheduled-work" || item.id === "stale-prompts" || item.id === "permissions")
+    .filter((item) => item.id === "skills-instructions" || item.id === "scheduled-work" || item.id === "stale-prompts" || item.id === "permissions"
+      || item.id === "adapt-settings" || item.id === "adapt-task-prompts" || item.id === "adapt-instructions-skills")
     .map((item) => item.label);
 }
 
@@ -395,11 +522,21 @@ function buildAdoptionPrompt(state: Pick<VersionAdoptionState, "current_version"
   const phaseLabel = state.is_first_adoption
     ? `current-version baseline ${state.current_version}`
     : `upgrade from ${state.previous_version} to ${state.current_version}`;
+  const plan = computeAdoptionPlan(state.previous_version, state.current_version);
+  const changesetSection = plan.source === "changeset" && plan.range
+    ? [
+      "",
+      `Release changesets — model-facing prompt and tool description/schema changes from ${state.previous_version} to ${state.current_version}${plan.range.complete ? "" : " (partial: older versions predate changesets)"}:`,
+      formatChangesetsForPrompt(plan.range.entries),
+    ]
+    : [];
   return [
     `Run Jarela version adoption for ${phaseLabel}.`,
     "",
     "Phase 1 — impact radius analysis:",
-    "- The changed-file surface (`fetch-changes`) was already computed deterministically by the system via git diff against the previously adopted version — see each Phase 2 checklist item below with its affected_files. Do not independently fetch or guess at what changed; that item is already marked done in the UI.",
+    plan.source === "changeset"
+      ? "- The change surface (`fetch-changes`) was already read deterministically by the system from the bundled release changesets: prompt text and built-in tool description/schema deltas between the previously adopted version and this one. They are listed under \"Release changesets\" below. Do not independently fetch or guess at what changed; that item is already marked done in the UI."
+      : "- The changed-file surface (`fetch-changes`) was already computed deterministically by the system via git diff against the previously adopted version — see each Phase 2 checklist item below with its affected_files. Do not independently fetch or guess at what changed; that item is already marked done in the UI.",
     "- Every checklist item provides its input, expected output, and validation criteria. Work from the stated inputs, validate the output using those criteria, and report observed evidence before marking the item done.",
     "- Prefer executable checks for code-verifiable behavior. If a check cannot run, say why and leave the result unverified or mark the item needs_attention.",
     "- Call `workflow_progress` with `workflow_id: \"version_adoption\"`, `phase: \"impact_radius\"`, `item_id: \"build-todo-list\"`, and `status: \"checking\"`.",
@@ -410,9 +547,10 @@ function buildAdoptionPrompt(state: Pick<VersionAdoptionState, "current_version"
     "- Start Phase 2 by calling `workflow_progress` with `workflow_id: \"version_adoption\"` and `phase: \"adoption\"`; the UI will swap from the Phase 1 checklist to the generated adoption todo list.",
     "- Before each Phase 2 checklist item, call `workflow_progress` with that `item_id` and `status: \"checking\"`.",
     "- If Phase 1 finds actionable adoption work, complete safe local updates directly when your available tools allow it.",
+    "- For `adapt-*` items, compare each user artifact (agent settings, instructions, skills, scheduled task and watcher prompts) with the release changesets: removed tools, added, removed, or newly required parameters, changed tool descriptions, and built-in prompt guidance the artifact now duplicates or contradicts. Show the before and after text, apply an edit only after the user approves it, then re-read the artifact to validate.",
     "- For risky or external side effects, propose an approval flow instead of acting silently.",
     "- If Phase 1 finds no adoption work, explicitly say that Phase 2 is skipped and why.",
-    "- After each Phase 2 item, call `workflow_progress` with `status: \"done\"` and observed `validation_evidence`, or `status: \"skipped\"` / `status: \"needs_attention\"` as appropriate.",
+    "- After each Phase 2 item, call `workflow_progress` with `status: \"done\"` and observed `validation_evidence`, or `status: \"skipped\"` / `status: \"needs_attention\"` as appropriate. Add `needs_user: true` only when the user must decide or act; other unfinished or failed steps are retried automatically, up to 3 attempts per step.",
     "- Before your final response, call `workflow_progress` with `workflow_id: \"version_adoption\"`, `phase: \"complete\"`, and a concise `summary`.",
     "",
     "Constraints:",
@@ -423,15 +561,81 @@ function buildAdoptionPrompt(state: Pick<VersionAdoptionState, "current_version"
     "Phase 1 checklist:",
     ...PHASE_1_CHECKLIST.map((item) => `- ${item.id}: ${item.label} — Input: ${item.input} Output: ${item.output} Validation: ${item.validation} Reason: ${item.reason}`),
     "Phase 2 adoption checklist:",
-    ...buildChecklist(state.previous_version, state.current_version).map((item) => `- ${item.id}: ${item.label}: Input: ${item.input} Output: ${item.output} Validation: ${item.validation} Reason: ${item.reason}${item.affected_files.length > 0 ? ` Affected files: ${item.affected_files.join(", ")}.` : ""}`),
+    ...plan.items.map((item) => `- ${item.id}: ${item.label}: Input: ${item.input} Output: ${item.output} Validation: ${item.validation} Reason: ${item.reason}${item.affected_files.length > 0 ? ` Affected: ${item.affected_files.join(", ")}.` : ""}`),
     state.stale_prompt_risks.length > 0 ? `Stale-prompt risks: ${state.stale_prompt_risks.join(", ")}.` : "Stale-prompt risks: none detected in the checklist.",
+    ...changesetSection,
   ].join("\n");
 }
 
+function buildAdoptionStepRetryPrompt(
+  state: Pick<VersionAdoptionState, "current_version" | "previous_version" | "is_first_adoption">,
+  phase: "impact_radius" | "adoption",
+  entry: VersionAdoptionChecklistItem,
+): string {
+  const phaseLabel = state.is_first_adoption
+    ? `current-version baseline ${state.current_version}`
+    : `upgrade from ${state.previous_version} to ${state.current_version}`;
+  const plan = computeAdoptionPlan(state.previous_version, state.current_version);
+  const changesetSection = phase === "adoption" && plan.source === "changeset" && plan.range
+    ? ["", "Release changesets:", formatChangesetsForPrompt(plan.range.entries)]
+    : [];
+  return [
+    `Retry one Jarela version adoption step for ${phaseLabel}. The user asked to redo only this step; leave every other checklist item unchanged.`,
+    "",
+    `Step: ${entry.id} — ${entry.label}`,
+    `Input: ${entry.input}`,
+    `Output: ${entry.output}`,
+    `Validation: ${entry.validation}`,
+    `Reason: ${entry.reason}`,
+    ...(entry.affected_files.length > 0 ? [`Affected: ${entry.affected_files.join(", ")}.`] : []),
+    "",
+    `- Call \`workflow_progress\` with \`workflow_id: "version_adoption"\`, \`phase: "${phase}"\`, \`item_id: "${entry.id}"\`, and \`status: "checking"\`.`,
+    "- Redo the step from its stated input. Prefer executable checks for code-verifiable behavior, and do not reuse earlier evidence: run the validation again.",
+    `- Then call \`workflow_progress\` for \`item_id: "${entry.id}"\` with \`status: "done"\` and newly observed \`validation_evidence\`, or \`status: "needs_attention"\` with the reason.`,
+    "- For `adapt-*` steps, show the before and after text and apply an edit only after the user approves it, then re-read the artifact.",
+    "- Do not create external issues, PRs, scheduled tasks, watcher updates, or credential changes unless the user explicitly approves.",
+    "- Keep the response concise: what you rechecked, the observed result, and any approval needed.",
+    ...changesetSection,
+  ].join("\n");
+}
+
+function retryAdoptionItem(
+  state: StoredVersionAdoptionState,
+  checklist: VersionAdoptionChecklistItem[],
+  itemId: string,
+  t: string,
+): StoredVersionAdoptionState {
+  const index = checklist.findIndex((entry) => entry.id === itemId);
+  if (index === -1) throw new VersionAdoptionRequestError(`Unknown adoption checklist item: ${itemId}`);
+  if (itemId === "fetch-changes") {
+    throw new VersionAdoptionRequestError("fetch-changes is computed by the system and cannot be retried by the agent.");
+  }
+  if (!state.default_agent_id) {
+    return { ...state, status: "blocked_no_default_agent", phase: null, error: "No default agent is configured." };
+  }
+  const phase = PHASE_1_CHECKLIST.some((entry) => entry.id === itemId) ? "impact_radius" : "adoption";
+  const { validation_evidence: _previousEvidence, ...rest } = checklist[index];
+  checklist[index] = { ...rest, status: "checking", attempts: (rest.attempts ?? 0) + 1 };
+  const thread = getOrCreateAgentThread(state.default_agent_id);
+  return {
+    ...state,
+    status: "running",
+    phase,
+    started_at: state.started_at ?? t,
+    completed_at: null,
+    dismissed_at: null,
+    checklist,
+    adoption_thread_id: thread.thread_id,
+    adoption_prompt: buildAdoptionStepRetryPrompt(state, phase, checklist[index]),
+    error: null,
+  };
+}
+
 function createState(currentVersion: string, previousVersion: string | null): StoredVersionAdoptionState {
   const defaultAgent = getDefaultAgentConfig();
   const isFirst = previousVersion === null;
-  const adoptionChecklist = buildChecklist(previousVersion, currentVersion);
+  const plan = computeAdoptionPlan(previousVersion, currentVersion);
+  const adoptionChecklist = plan.items;
   const summaryInput = {
     current_version: currentVersion,
     previous_version: previousVersion,
@@ -450,7 +654,7 @@ function createState(currentVersion: string, previousVersion: string | null): St
     started_at: null,
     completed_at: null,
     dismissed_at: null,
-    checklist: resolvedPhase1Checklist(adoptionChecklist, isFirst),
+    checklist: resolvedPhase1Checklist(plan, isFirst),
     stale_prompt_risks: stalePromptRisks(adoptionChecklist),
     summary: buildSummary(summaryInput, adoptionChecklist),
     error: defaultAgent ? null : "No default agent is configured.",
@@ -475,6 +679,7 @@ export function getVersionAdoptionState(currentVersion = getCurrentVersion()): V
 export function updateVersionAdoptionState(
   action: "start" | "mark_done" | "dismiss" | "retry",
   currentVersion = getCurrentVersion(),
+  itemId?: string,
 ): VersionAdoptionState {
   const existing = parseStored();
   const state = existing && existing.current_version === currentVersion
@@ -483,6 +688,10 @@ export function updateVersionAdoptionState(
   const t = now();
   const nextChecklist = state.checklist.map((entry) => ({ ...entry }));
 
+  if (action === "retry" && itemId) {
+    return persist(retryAdoptionItem(state, nextChecklist, itemId, t));
+  }
+
   if (action === "start" || action === "retry") {
     if (!state.default_agent_id) {
       return persist({
@@ -497,7 +706,11 @@ export function updateVersionAdoptionState(
     // still-open item (normally build-todo-list) as checking instead of
     // hardcoding index 0, which would otherwise clobber that done status.
     const firstOpen = nextChecklist.findIndex((entry) => entry.status !== "done" && entry.status !== "skipped");
-    if (firstOpen !== -1) nextChecklist[firstOpen].status = "checking";
+    if (firstOpen !== -1) {
+      const entry = nextChecklist[firstOpen];
+      if (entry.status !== "checking") entry.attempts = (entry.attempts ?? 0) + 1;
+      entry.status = "checking";
+    }
     const running = {
       ...state,
       status: "running",

package/lib/stores/workflow-progress.ts

@@ -5,6 +5,8 @@ export interface WorkflowItem<Action extends string = string> {
   label: string;
   status: WorkflowItemStatus;
   validation_evidence?: string;
+  /** Times the step has entered `checking`; auto- and manual retries add one each. */
+  attempts?: number;
   reason: string;
   affected_files: string[];
   action?: Action;
@@ -59,6 +61,7 @@ export function updateWorkflowItem<State extends WorkflowState>(
     return {
       ...item,
       status,
+      ...(status === "checking" && item.status !== "checking" ? { attempts: (item.attempts ?? 0) + 1 } : {}),
       ...(validationEvidence ? { validation_evidence: validationEvidence } : {}),
     };
   });

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,