@circuitwall/jarela 2.2.0 → 2.3.0

package/lib/lifecycle/changesets.ts

@@ -0,0 +1,166 @@
+/**
+ * Bundled release changesets (docs/adoption/changesets.json), generated at
+ * release time by `npm run release:changeset`. Installed bundles have no git
+ * history, so version adoption reads these to learn which prompts and tool
+ * descriptions/schemas changed between the user's last adopted version and
+ * the running one.
+ */
+import { z } from "zod";
+import bundled from "@/docs/adoption/changesets.json";
+import type { PromptChange, ToolChange } from "./surface-snapshot";
+
+const changeKind = z.enum(["added", "removed", "changed"]);
+
+const promptChangeSchema = z.object({
+  id: z.string(),
+  source: z.string(),
+  change: changeKind,
+  added_lines: z.array(z.string()),
+  removed_lines: z.array(z.string()),
+  omitted_lines: z.number().int().nonnegative(),
+});
+
+const toolChangeSchema = z.object({
+  name: z.string(),
+  change: changeKind,
+  description_changed: z.boolean(),
+  description: z.string().optional(),
+  previous_description: z.string().optional(),
+  params_added: z.array(z.string()),
+  params_removed: z.array(z.string()),
+  params_changed: z.array(z.string()),
+  required_added: z.array(z.string()),
+  required_removed: z.array(z.string()),
+});
+
+export const releaseChangesetSchema = z.object({
+  version: z.string().regex(/^\d+\.\d+\.\d+$/),
+  previous_version: z.string().regex(/^\d+\.\d+\.\d+$/).nullable(),
+  date: z.string(),
+  hints: z.array(z.string()),
+  commits: z.array(z.string()),
+  prompts: z.array(promptChangeSchema),
+  tools: z.array(toolChangeSchema),
+});
+
+export const changesetFileSchema = z.object({
+  schema_version: z.literal(1),
+  changesets: z.array(releaseChangesetSchema),
+});
+
+export type ReleaseChangeset = z.infer<typeof releaseChangesetSchema>;
+export type ChangesetFile = z.infer<typeof changesetFileSchema>;
+
+// Compile-time guard: the bundled schema must stay in sync with the diff types.
+type Assert<T extends true> = T;
+type _PromptShape = Assert<PromptChange extends z.infer<typeof promptChangeSchema> ? true : false>;
+type _ToolShape = Assert<ToolChange extends z.infer<typeof toolChangeSchema> ? true : false>;
+
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const pb = b.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+let cached: ReleaseChangeset[] | null = null;
+
+export function loadBundledChangesets(): ReleaseChangeset[] {
+  if (cached) return cached;
+  const parsed = changesetFileSchema.safeParse(bundled);
+  cached = parsed.success
+    ? [...parsed.data.changesets].sort((a, b) => compareVersions(a.version, b.version))
+    : [];
+  return cached;
+}
+
+export interface ChangesetRange {
+  entries: ReleaseChangeset[];
+  /** True when the entries chain fully from `previous` to `current`. */
+  complete: boolean;
+}
+
+/** Cumulative changesets for versions in (previous, current]. */
+export function changesetsBetween(
+  previous: string,
+  current: string,
+  all: readonly ReleaseChangeset[] = loadBundledChangesets(),
+): ChangesetRange {
+  const entries = all
+    .filter((entry) => compareVersions(entry.version, previous) > 0 && compareVersions(entry.version, current) <= 0)
+    .sort((a, b) => compareVersions(a.version, b.version));
+  const reachesCurrent = entries.some((entry) => compareVersions(entry.version, current) === 0);
+  const first = entries[0];
+  const reachesPrevious = Boolean(first?.previous_version && compareVersions(first.previous_version, previous) <= 0);
+  return { entries, complete: reachesCurrent && reachesPrevious };
+}
+
+export interface ChangesetSurfaceSummary {
+  promptIds: string[];
+  toolNames: string[];
+  removedTools: string[];
+  hints: string[];
+}
+
+/** Collapses a version range to the latest state of each changed surface. */
+export function summarizeChangesets(entries: readonly ReleaseChangeset[]): ChangesetSurfaceSummary {
+  const prompts = new Set<string>();
+  const tools = new Map<string, ToolChange["change"]>();
+  const hints: string[] = [];
+  for (const entry of entries) {
+    for (const prompt of entry.prompts) prompts.add(prompt.id);
+    for (const tool of entry.tools) tools.set(tool.name, tool.change);
+    for (const hint of entry.hints) hints.push(`${entry.version}: ${hint}`);
+  }
+  return {
+    promptIds: [...prompts].sort(),
+    toolNames: [...tools.keys()].sort(),
+    removedTools: [...tools].filter(([, change]) => change === "removed").map(([name]) => name).sort(),
+    hints,
+  };
+}
+
+function describeTool(tool: ToolChange): string {
+  const parts: string[] = [];
+  if (tool.change === "added") parts.push("new tool");
+  if (tool.change === "removed") parts.push("removed — references to it will fail");
+  if (tool.description_changed) parts.push("description changed");
+  if (tool.params_added.length) parts.push(`params added: ${tool.params_added.join(", ")}`);
+  if (tool.params_removed.length) parts.push(`params removed: ${tool.params_removed.join(", ")}`);
+  if (tool.params_changed.length) parts.push(`params changed: ${tool.params_changed.join(", ")}`);
+  if (tool.required_added.length) parts.push(`now required: ${tool.required_added.join(", ")}`);
+  if (tool.required_removed.length) parts.push(`no longer required: ${tool.required_removed.join(", ")}`);
+  const head = `  - tool \`${tool.name}\`: ${parts.join("; ") || tool.change}`;
+  return tool.description && tool.change !== "removed"
+    ? `${head}\n    description: ${tool.description}`
+    : head;
+}
+
+function describePrompt(prompt: PromptChange): string {
+  const lines = [`  - prompt \`${prompt.id}\` (${prompt.source}): ${prompt.change}`];
+  for (const line of prompt.added_lines) lines.push(`    + ${line}`);
+  for (const line of prompt.removed_lines) lines.push(`    - ${line}`);
+  if (prompt.omitted_lines > 0) lines.push(`    … ${prompt.omitted_lines} more changed line(s)`);
+  return lines.join("\n");
+}
+
+/** Renders the range for the adoption prompt, bounded to `maxChars`. */
+export function formatChangesetsForPrompt(entries: readonly ReleaseChangeset[], maxChars = 8000): string {
+  const blocks: string[] = [];
+  for (const entry of entries) {
+    const lines = [`Version ${entry.version} (from ${entry.previous_version ?? "unknown"}, ${entry.date}):`];
+    if (entry.hints.length) lines.push(...entry.hints.map((hint) => `  - adoption hint: ${hint}`));
+    lines.push(...entry.tools.map(describeTool));
+    lines.push(...entry.prompts.map(describePrompt));
+    if (!entry.hints.length && !entry.tools.length && !entry.prompts.length) {
+      lines.push("  - no prompt or tool surface changes");
+    }
+    blocks.push(lines.join("\n"));
+  }
+  const text = blocks.join("\n");
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars)}\n… changeset truncated; the full record is docs/adoption/changesets.json in the release.`;
+}

package/lib/lifecycle/surface-collect.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Collects the live prompt + tool surface and checks it is complete and
+ * deterministic. `scripts/release-changeset.mjs` also drives this file to
+ * write snapshots and release changesets, because collection needs the
+ * TypeScript runtime and the `@/` alias:
+ *   JARELA_SURFACE_OUT=<path>   write the live snapshot to <path>
+ *   JARELA_CHANGESET_WRITE=1    record the release changeset (see the script)
+ */
+import { describe, it, expect, afterAll } from "vitest";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const tmpRoot = mkdtempSync(join(tmpdir(), "jarela-surface-"));
+process.env.JARELA_DB_DIR = tmpRoot;
+
+const { collectSurfaceSnapshot } = await import("./surface-collect");
+const { SURFACE_SNAPSHOT_SCHEMA_VERSION } = await import("./surface-snapshot");
+type SurfaceSnapshot = import("./surface-snapshot").SurfaceSnapshot;
+
+afterAll(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* held open */ }
+});
+
+const root = process.cwd();
+const packageVersion = (JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as { version: string }).version;
+const snapshot = await collectSurfaceSnapshot(packageVersion);
+
+if (process.env.JARELA_SURFACE_OUT) {
+  writeFileSync(process.env.JARELA_SURFACE_OUT, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+}
+
+if (process.env.JARELA_CHANGESET_WRITE === "1") {
+  const { writeReleaseChangeset, readSnapshot } = await import("./changeset-build");
+  const readOptional = (path: string | undefined): SurfaceSnapshot | undefined =>
+    path ? readSnapshot(path) : undefined;
+  const entry = writeReleaseChangeset({
+    root,
+    version: process.env.JARELA_CHANGESET_VERSION || packageVersion,
+    nextSnapshot: readOptional(process.env.JARELA_CHANGESET_NEXT_SNAPSHOT) ?? snapshot,
+    previousSnapshot: readOptional(process.env.JARELA_CHANGESET_PREVIOUS_SNAPSHOT),
+    date: process.env.JARELA_CHANGESET_DATE || new Date().toISOString().slice(0, 10),
+    ref: process.env.JARELA_CHANGESET_REF || undefined,
+  });
+  if (process.env.JARELA_CHANGESET_REPORT) {
+    writeFileSync(process.env.JARELA_CHANGESET_REPORT, JSON.stringify({
+      version: entry.version,
+      previous_version: entry.previous_version,
+      prompts: entry.prompts.length,
+      tools: entry.tools.length,
+      hints: entry.hints.length,
+      commits: entry.commits.length,
+    }), "utf8");
+  }
+}
+
+describe("model-facing surface snapshot", () => {
+  it("covers static prompts, system prompt sections, and built-in tools", () => {
+    expect(snapshot.schema_version).toBe(SURFACE_SNAPSHOT_SCHEMA_VERSION);
+    expect(snapshot.prompts["static.agent.tool-usage-sop"]?.text).toBeTruthy();
+    expect(Object.keys(snapshot.prompts).filter((id) => id.startsWith("system."))).toEqual(
+      expect.arrayContaining(["system.Tool usage SOP", "system.Self-configuration (with user approval)"]),
+    );
+    expect(Object.keys(snapshot.tools).length).toBeGreaterThan(50);
+    expect(snapshot.tools.update_scheduled_task?.description).toBeTruthy();
+  });
+
+  it("records an object parameter schema for every tool", () => {
+    for (const [name, tool] of Object.entries(snapshot.tools)) {
+      expect((tool.parameters as { type?: unknown }).type, name).toBe("object");
+      expect(tool.parameters, name).not.toHaveProperty("$schema");
+    }
+  });
+
+  it("excludes host- and time-dependent prompt content", () => {
+    expect(snapshot.prompts).not.toHaveProperty(["system.Host environment"]);
+    expect(snapshot.prompts).not.toHaveProperty(["system.System signals"]);
+    for (const [id, prompt] of Object.entries(snapshot.prompts)) {
+      if (!id.startsWith("system.")) continue;
+      expect(prompt.text, id).not.toMatch(/^Current (time|local date and time):/m);
+      expect(prompt.text, id).not.toContain(tmpRoot);
+    }
+  });
+
+  it("is deterministic across collections", async () => {
+    expect(await collectSurfaceSnapshot(packageVersion)).toEqual(snapshot);
+  });
+});

package/lib/lifecycle/surface-collect.ts

@@ -0,0 +1,64 @@
+/**
+ * Collects the live model-facing surface (see surface-snapshot.ts). Imports
+ * the agent runtime, so callers must point JARELA_DB_DIR at a scratch
+ * directory first. Used only by the release changeset generator and its
+ * tests — never by the running app.
+ */
+import { toJsonSchema } from "@langchain/core/utils/json_schema";
+import { allBuiltins } from "@/lib/tools";
+import { listStaticPrompts } from "@/lib/agents/prompt-registry";
+import { buildVariants } from "@/lib/agents/prompt-variants";
+import {
+  SURFACE_SNAPSHOT_SCHEMA_VERSION,
+  splitSystemPromptSections,
+  type SurfacePrompt,
+  type SurfaceSnapshot,
+  type SurfaceTool,
+} from "./surface-snapshot";
+
+const SYSTEM_PROMPT_SOURCE = "lib/agents/prepare/system-prompt.ts";
+/** Richest variant first so shared sections keep their fullest form. */
+const VARIANT_PRIORITY = ["pinned-tools-all-bound", "delivery-channel", "proxy-only-and-provider-cap", "minimal-agent"];
+
+function sortedRecord<T>(record: Record<string, T>): Record<string, T> {
+  return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+export async function collectSurfaceSnapshot(version: string): Promise<SurfaceSnapshot> {
+  const prompts: Record<string, SurfacePrompt> = {};
+  for (const prompt of listStaticPrompts()) {
+    prompts[`static.${prompt.id}`] = { source: prompt.source, text: prompt.text };
+  }
+
+  const variants = await buildVariants();
+  const rank = (id: string) => {
+    const index = VARIANT_PRIORITY.indexOf(id);
+    return index === -1 ? VARIANT_PRIORITY.length : index;
+  };
+  for (const variant of [...variants].sort((a, b) => rank(a.id) - rank(b.id))) {
+    for (const [title, text] of Object.entries(splitSystemPromptSections(variant.prompt))) {
+      prompts[`system.${title}`] ??= { source: SYSTEM_PROMPT_SOURCE, text };
+    }
+  }
+
+  const tools: Record<string, SurfaceTool> = {};
+  for (const tool of allBuiltins()) {
+    let parameters: unknown;
+    try {
+      parameters = toJsonSchema(tool.schema as Parameters<typeof toJsonSchema>[0]);
+    } catch {
+      parameters = {};
+    }
+    if (parameters && typeof parameters === "object") {
+      delete (parameters as Record<string, unknown>).$schema;
+    }
+    tools[tool.name] = { description: tool.description ?? "", parameters };
+  }
+
+  return {
+    schema_version: SURFACE_SNAPSHOT_SCHEMA_VERSION,
+    version,
+    prompts: sortedRecord(prompts),
+    tools: sortedRecord(tools),
+  };
+}

package/lib/lifecycle/surface-snapshot.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import { diffPrompts, diffTools, splitSystemPromptSections } from "./surface-snapshot";
+
+const objectSchema = (properties: Record<string, unknown>, required: string[] = []) => ({
+  type: "object",
+  properties,
+  required,
+});
+
+describe("splitSystemPromptSections", () => {
+  it("splits on section headers and drops host- and time-dependent content", () => {
+    const sections = splitSystemPromptSections([
+      "intro line",
+      "--- Tool usage SOP ---",
+      "1. Use tools.",
+      "<!-- jarela:dynamic -->",
+      "--- Host environment ---",
+      "OS: win32",
+      "--- System signals ---",
+      "[]",
+      "--- Enabled tools ---",
+      "Current time: 2026-01-01T00:00:00Z (UTC).",
+      "Current local date and time: 2026-01-01 01:00",
+      "- web_search",
+    ].join("\n"));
+    expect(sections).toEqual({
+      Preamble: "intro line",
+      "Tool usage SOP": "1. Use tools.",
+      "Enabled tools": "- web_search",
+    });
+  });
+});
+
+describe("diffPrompts", () => {
+  it("reports line-level additions and removals and ignores whitespace-only edits", () => {
+    const prev = {
+      a: { source: "a.ts", text: "keep\nold rule" },
+      b: { source: "b.ts", text: "same" },
+      gone: { source: "g.ts", text: "bye" },
+    };
+    const next = {
+      a: { source: "a.ts", text: "keep\nnew rule" },
+      b: { source: "b.ts", text: "  same  \n" },
+      fresh: { source: "f.ts", text: "hello" },
+    };
+    expect(diffPrompts(prev, next)).toEqual([
+      { id: "a", source: "a.ts", change: "changed", added_lines: ["new rule"], removed_lines: ["old rule"], omitted_lines: 0 },
+      { id: "fresh", source: "f.ts", change: "added", added_lines: [], removed_lines: [], omitted_lines: 0 },
+      { id: "gone", source: "g.ts", change: "removed", added_lines: [], removed_lines: [], omitted_lines: 0 },
+    ]);
+  });
+
+  it("caps excerpts and counts the omitted lines", () => {
+    const lines = Array.from({ length: 20 }, (_, i) => `line ${i}`).join("\n");
+    const [change] = diffPrompts({ p: { source: "p.ts", text: "x" } }, { p: { source: "p.ts", text: lines } });
+    expect(change.added_lines).toHaveLength(12);
+    expect(change.omitted_lines).toBe(8);
+  });
+});
+
+describe("diffTools", () => {
+  it("classifies parameter, requirement, and description changes", () => {
+    const prev = {
+      t: { description: "Old.", parameters: objectSchema({ a: { type: "string" }, b: { type: "number" }, gone: {} }, ["a"]) },
+      same: { description: "Same.", parameters: objectSchema({ q: { type: "string" } }) },
+    };
+    const next = {
+      t: { description: "New.", parameters: objectSchema({ a: { type: "string" }, b: { type: "string" }, c: {} }, ["a", "c"]) },
+      same: { description: "Same.", parameters: objectSchema({ q: { type: "string" } }) },
+    };
+    expect(diffTools(prev, next)).toEqual([{
+      name: "t",
+      change: "changed",
+      description_changed: true,
+      description: "New.",
+      previous_description: "Old.",
+      params_added: ["c"],
+      params_removed: ["gone"],
+      params_changed: ["b"],
+      required_added: ["c"],
+      required_removed: [],
+    }]);
+  });
+
+  it("treats property order differences as unchanged", () => {
+    const prev = { t: { description: "d", parameters: objectSchema({ a: { type: "string", description: "x" } }) } };
+    const next = { t: { description: "d", parameters: objectSchema({ a: { description: "x", type: "string" } }) } };
+    expect(diffTools(prev, next)).toEqual([]);
+  });
+
+  it("records added and removed tools", () => {
+    const tool = { description: "T.", parameters: objectSchema({ a: {} }, ["a"]) };
+    expect(diffTools({ old: tool }, { added: tool })).toEqual([
+      {
+        name: "added", change: "added", description_changed: false, description: "T.",
+        params_added: ["a"], params_removed: [], params_changed: [], required_added: ["a"], required_removed: [],
+      },
+      {
+        name: "old", change: "removed", description_changed: false,
+        params_added: [], params_removed: [], params_changed: [], required_added: [], required_removed: [],
+      },
+    ]);
+  });
+});

package/lib/lifecycle/surface-snapshot.ts

@@ -0,0 +1,210 @@
+/**
+ * The model-facing surface of a Jarela release: every prompt text Jarela
+ * sends and every built-in tool's description and parameter schema. Release
+ * changesets diff two snapshots so version adoption can tell which user
+ * instructions, skills, settings, and scheduled prompts may need adapting.
+ * Pure functions only — collection lives in surface-collect.ts.
+ */
+
+export const SURFACE_SNAPSHOT_SCHEMA_VERSION = 1;
+
+export interface SurfacePrompt {
+  source: string;
+  text: string;
+}
+
+export interface SurfaceTool {
+  description: string;
+  parameters: unknown;
+}
+
+export interface SurfaceSnapshot {
+  schema_version: number;
+  version: string;
+  prompts: Record<string, SurfacePrompt>;
+  tools: Record<string, SurfaceTool>;
+}
+
+export type SurfaceChangeKind = "added" | "removed" | "changed";
+
+export interface PromptChange {
+  id: string;
+  source: string;
+  change: SurfaceChangeKind;
+  added_lines: string[];
+  removed_lines: string[];
+  /** Lines beyond the excerpt cap, so readers know the excerpt is partial. */
+  omitted_lines: number;
+}
+
+export interface ToolChange {
+  name: string;
+  change: SurfaceChangeKind;
+  description_changed: boolean;
+  description?: string;
+  previous_description?: string;
+  params_added: string[];
+  params_removed: string[];
+  params_changed: string[];
+  required_added: string[];
+  required_removed: string[];
+}
+
+export interface SurfaceDelta {
+  prompts: PromptChange[];
+  tools: ToolChange[];
+}
+
+const SECTION_HEADER = /^--- (.+) ---$/;
+/** Sections whose content depends on the host machine or the moment of collection. */
+const VOLATILE_SECTIONS = new Set(["Host environment", "System signals"]);
+const VOLATILE_LINES = [/^Current time:/, /^Current local date and time:/];
+const MAX_EXCERPT_LINES = 12;
+const MAX_LINE_CHARS = 300;
+const MAX_DESCRIPTION_CHARS = 600;
+
+function clip(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/**
+ * Splits an assembled agent system prompt into its `--- Title ---` sections,
+ * dropping host- and time-dependent content so two snapshots of the same code
+ * compare equal on any machine.
+ */
+export function splitSystemPromptSections(prompt: string): Record<string, string> {
+  const sections: Record<string, string[]> = {};
+  let current = "Preamble";
+  for (const raw of prompt.split(/\r?\n/)) {
+    const header = SECTION_HEADER.exec(raw.trim());
+    if (header) {
+      current = header[1].trim();
+      sections[current] ??= [];
+      continue;
+    }
+    if (raw.startsWith("<!-- jarela:")) continue;
+    if (VOLATILE_LINES.some((pattern) => pattern.test(raw.trim()))) continue;
+    (sections[current] ??= []).push(raw);
+  }
+  const out: Record<string, string> = {};
+  for (const [title, lines] of Object.entries(sections)) {
+    if (VOLATILE_SECTIONS.has(title)) continue;
+    const text = lines.join("\n").trim();
+    if (text) out[title] = text;
+  }
+  return out;
+}
+
+function significantLines(text: string): string[] {
+  return text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+
+function excerpt(lines: string[]): { lines: string[]; omitted: number } {
+  return {
+    lines: lines.slice(0, MAX_EXCERPT_LINES).map((line) => clip(line, MAX_LINE_CHARS)),
+    omitted: Math.max(0, lines.length - MAX_EXCERPT_LINES),
+  };
+}
+
+export function diffPrompts(
+  prev: Record<string, SurfacePrompt>,
+  next: Record<string, SurfacePrompt>,
+): PromptChange[] {
+  const ids = [...new Set([...Object.keys(prev), ...Object.keys(next)])].sort();
+  const changes: PromptChange[] = [];
+  for (const id of ids) {
+    const before = prev[id];
+    const after = next[id];
+    if (before && after && before.text === after.text) continue;
+    const beforeLines = before ? significantLines(before.text) : [];
+    const afterLines = after ? significantLines(after.text) : [];
+    const beforeSet = new Set(beforeLines);
+    const afterSet = new Set(afterLines);
+    const added = excerpt(afterLines.filter((line) => !beforeSet.has(line)));
+    const removed = excerpt(beforeLines.filter((line) => !afterSet.has(line)));
+    // Whitespace-only edits change the text but not what the model reads.
+    if (before && after && added.lines.length === 0 && removed.lines.length === 0) continue;
+    changes.push({
+      id,
+      source: (after ?? before).source,
+      change: !before ? "added" : !after ? "removed" : "changed",
+      added_lines: before ? added.lines : [],
+      removed_lines: after ? removed.lines : [],
+      omitted_lines: (before ? added.omitted : 0) + (after ? removed.omitted : 0),
+    });
+  }
+  return changes;
+}
+
+interface ObjectSchema {
+  properties: Record<string, unknown>;
+  required: string[];
+}
+
+function objectSchema(parameters: unknown): ObjectSchema {
+  const schema = parameters && typeof parameters === "object" ? parameters as Record<string, unknown> : {};
+  const properties = schema.properties && typeof schema.properties === "object"
+    ? schema.properties as Record<string, unknown>
+    : {};
+  const required = Array.isArray(schema.required)
+    ? schema.required.filter((name): name is string => typeof name === "string")
+    : [];
+  return { properties, required };
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries.map(([key, inner]) => `${JSON.stringify(key)}:${stableJson(inner)}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+export function diffTools(
+  prev: Record<string, SurfaceTool>,
+  next: Record<string, SurfaceTool>,
+): ToolChange[] {
+  const names = [...new Set([...Object.keys(prev), ...Object.keys(next)])].sort();
+  const changes: ToolChange[] = [];
+  for (const name of names) {
+    const before = prev[name];
+    const after = next[name];
+    const beforeSchema = objectSchema(before?.parameters);
+    const afterSchema = objectSchema(after?.parameters);
+    const beforeParams = Object.keys(beforeSchema.properties);
+    const afterParams = Object.keys(afterSchema.properties);
+    const paramsAdded = afterParams.filter((param) => !(param in beforeSchema.properties)).sort();
+    const paramsRemoved = beforeParams.filter((param) => !(param in afterSchema.properties)).sort();
+    const paramsChanged = afterParams
+      .filter((param) => param in beforeSchema.properties)
+      .filter((param) => stableJson(beforeSchema.properties[param]) !== stableJson(afterSchema.properties[param]))
+      .sort();
+    const requiredAdded = afterSchema.required.filter((param) => !beforeSchema.required.includes(param)).sort();
+    const requiredRemoved = beforeSchema.required.filter((param) => !afterSchema.required.includes(param)).sort();
+    const descriptionChanged = Boolean(before && after && before.description.trim() !== after.description.trim());
+    const schemaChanged = paramsAdded.length + paramsRemoved.length + paramsChanged.length
+      + requiredAdded.length + requiredRemoved.length > 0;
+    if (before && after && !descriptionChanged && !schemaChanged) continue;
+    changes.push({
+      name,
+      change: !before ? "added" : !after ? "removed" : "changed",
+      description_changed: descriptionChanged,
+      ...(after && (!before || descriptionChanged) ? { description: clip(after.description.trim(), MAX_DESCRIPTION_CHARS) } : {}),
+      ...(before && after && descriptionChanged ? { previous_description: clip(before.description.trim(), MAX_DESCRIPTION_CHARS) } : {}),
+      params_added: after ? paramsAdded : [],
+      params_removed: before && after ? paramsRemoved : [],
+      params_changed: paramsChanged,
+      required_added: after ? requiredAdded : [],
+      required_removed: before && after ? requiredRemoved : [],
+    });
+  }
+  return changes;
+}
+
+export function diffSurfaces(prev: SurfaceSnapshot, next: SurfaceSnapshot): SurfaceDelta {
+  return {
+    prompts: diffPrompts(prev.prompts, next.prompts),
+    tools: diffTools(prev.tools, next.tools),
+  };
+}

package/lib/memory/record.ts

@@ -65,9 +65,7 @@ export const StructuredMemoryInputSchema = z.object({
   status: z.enum(MEMORY_STATUSES).default("active"),
 }).strict();
 
-export type StructuredMemoryInput = z.infer<typeof StructuredMemoryInputSchema>;
 export type StructuredMemoryRecord = z.infer<typeof StructuredMemoryEnvelopeV2Schema>;
-export type StructuredMemoryHistoryEntry = z.infer<typeof StructuredMemoryHistoryEntrySchema>;
 
 function normalizeStructuredMemoryCandidate(candidate: unknown): unknown {
   if (!candidate || typeof candidate !== "object") return candidate;

package/lib/models/editor-payload.ts

@@ -24,7 +24,7 @@ export interface ModelEditorFormInput {
   credential_id?: string | null;
 }
 
-export type ModelEditorPayload = Omit<ModelConfig, "name" | "created_at" | "updated_at">;
+export type ModelEditorPayload = Omit<ModelConfig, "name" | "enabled" | "created_at" | "updated_at">;
 
 export type BuildResult =
   | { ok: true; name: string; payload: ModelEditorPayload }

package/lib/providers/external.ts

@@ -97,5 +97,3 @@ export function loadExternalProviders(
 ): Record<string, ModelProvider> {
   return loadExternalProvidersDetailed(builtins).providers;
 }
-
-export { type ExternalProviderCredentialField as ProviderCredentialField };

package/lib/providers/github-copilot-auth.ts

@@ -1,6 +1,5 @@
-// GitHub Copilot device-flow login. Lets users sign in with their Copilot
-// subscription instead of pasting a PAT (which can't be exchanged for a
-// Copilot session token and gets rate-limited on the Models REST API).
+// GitHub Copilot device-flow login. The legacy PAT path depended on GitHub
+// Models, which has been retired; use this flow for Copilot Chat access.
 //
 // Flow (RFC 8628):
 //   1. POST github.com/login/device/code with the VS Code Copilot client_id.