@circuitwall/jarela 2.2.1 → 2.3.0

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/providers/external.ts

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

package/lib/skills/builtins/memory-organization/SKILL.md

@@ -37,6 +37,22 @@ Every update to an existing key keeps a dated snapshot of the prior record in
 its `history`, and older free-form or v1 entries are upgraded to the current
 schema automatically the first time they're read — no manual migration step.
 
+## Proactive Saving
+
+Memory is shared by every Jarela agent, so save durable information in the
+turn it appears instead of relying on background compaction, which runs later
+and can miss details.
+
+1. **Trigger:** the user states a preference, fact, decision, constraint, or
+   correction; or a tool result verifies a durable fact.
+2. **Check:** search for an existing record on the same subject and reuse its
+   key.
+3. **Write:** call `memory_upsert` before the final reply.
+4. **Validate:** the result must contain `ok: true` and the key you sent;
+   retry once on failure, then tell the user it was not saved.
+5. **Cite:** end the reply with `Saved to memory: facts/<key>` for each saved
+   key.
+
 ## Retrieval And Consolidation
 
 1. Let proactive recall supply matching facts on normal user turns. Use

package/lib/stores/threads.test.ts

@@ -692,6 +692,15 @@ describe("thread channel summaries (ADR-0044)", () => {
     expect(getThreadChannelSummary(t.thread_id, "watcher")?.summary).toBe("watcher recap");
     expect(getThreadChannelSummary(t.thread_id, "bridge")?.summary).toBe("bridge recap");
   });
+
+  it("round-trips stored channel topics and clears them when a later commit omits them", () => {
+    const t = createThread("agent-chsum-4");
+    const topics = JSON.stringify([{ title: "Nightly backup", start_seq: 1, end_seq: 2, recap: "r", facts: [], message_count: 2 }]);
+    commitThreadChannelSummary(t.thread_id, "scheduled_task", { summary: "recap", summaryBefore: null, summaryBeforeSeq: 3, topics });
+    expect(getThreadChannelSummary(t.thread_id, "scheduled_task")?.topics).toBe(topics);
+    commitThreadChannelSummary(t.thread_id, "scheduled_task", { summary: "fallback", summaryBefore: null, summaryBeforeSeq: 4 });
+    expect(getThreadChannelSummary(t.thread_id, "scheduled_task")?.topics).toBeNull();
+  });
 });
 
 describe("getRecentlyUsedToolNames", () => {

package/lib/stores/threads.ts

@@ -671,6 +671,8 @@ export interface ThreadChannelSummaryRow {
   summary_before: string | null;
   summary_before_seq: number | null;
   computed_at: string;
+  /** JSON array of SummaryTopicSegment, or null for summaries without topics. */
+  topics: string | null;
 }
 
 // ADR-0044 — one cached warm summary per (thread, automation channel),
@@ -682,27 +684,34 @@ export interface ThreadChannelSummaryRow {
 // hot/warm boundary move, there's no cross-field invariant to protect here.
 export function getThreadChannelSummary(threadId: string, channel: string): ThreadChannelSummaryRow | null {
   return (getDb()
-    .prepare("SELECT thread_id, channel, summary, summary_before, summary_before_seq, computed_at FROM thread_channel_summaries WHERE thread_id=? AND channel=?")
+    .prepare("SELECT thread_id, channel, summary, summary_before, summary_before_seq, computed_at, topics FROM thread_channel_summaries WHERE thread_id=? AND channel=?")
     .get(threadId, channel) as ThreadChannelSummaryRow | undefined) ?? null;
 }
 
+export function listThreadChannelSummaries(threadId: string): ThreadChannelSummaryRow[] {
+  return getDb()
+    .prepare("SELECT thread_id, channel, summary, summary_before, summary_before_seq, computed_at, topics FROM thread_channel_summaries WHERE thread_id=?")
+    .all(threadId) as unknown as ThreadChannelSummaryRow[];
+}
+
 export function commitThreadChannelSummary(
   threadId: string,
   channel: string,
-  input: { summary: string; summaryBefore: string | null; summaryBeforeSeq?: number | null },
+  input: { summary: string; summaryBefore: string | null; summaryBeforeSeq?: number | null; topics?: string | null },
 ): void {
   if (input.summaryBefore !== null && input.summaryBeforeSeq == null) {
     throw new Error("summaryBeforeSeq is required for a boundary summary");
   }
   getDb()
     .prepare(
-      `INSERT INTO thread_channel_summaries (thread_id, channel, summary, summary_before, summary_before_seq, computed_at)
-       VALUES (?, ?, ?, ?, ?, ?)
+      `INSERT INTO thread_channel_summaries (thread_id, channel, summary, summary_before, summary_before_seq, computed_at, topics)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(thread_id, channel) DO UPDATE SET
          summary=excluded.summary, summary_before=excluded.summary_before,
-         summary_before_seq=excluded.summary_before_seq, computed_at=excluded.computed_at`,
+         summary_before_seq=excluded.summary_before_seq, computed_at=excluded.computed_at,
+         topics=excluded.topics`,
     )
-    .run(threadId, channel, input.summary, input.summaryBefore, input.summaryBeforeSeq ?? null, now());
+    .run(threadId, channel, input.summary, input.summaryBefore, input.summaryBeforeSeq ?? null, now(), input.topics ?? null);
 }
 
 export function touchThread(thread_id: string, firstMsg?: string): void {
@@ -746,7 +755,7 @@ export interface ThreadWarmContextCommit {
   /** Reject the commit if another compactor refreshed the same boundary. */
   expectedWarmSummary?: string | null;
   autoBoundaryLockedUntilMessageCount?: number;
-  channelSummaries?: Array<{ channel: string; summary: string }>;
+  channelSummaries?: Array<{ channel: string; summary: string; topics?: string | null }>;
 }
 
 // A warm recap is only valid for the exact boundary it replaced. Commit both
@@ -790,14 +799,15 @@ export function commitThreadWarmContext(
       thread_id,
     );
     const upsertChannel = db.prepare(
-      `INSERT INTO thread_channel_summaries (thread_id, channel, summary, summary_before, summary_before_seq, computed_at)
-       VALUES (?, ?, ?, ?, ?, ?)
+      `INSERT INTO thread_channel_summaries (thread_id, channel, summary, summary_before, summary_before_seq, computed_at, topics)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(thread_id, channel) DO UPDATE SET
          summary=excluded.summary, summary_before=excluded.summary_before,
-         summary_before_seq=excluded.summary_before_seq, computed_at=excluded.computed_at`,
+         summary_before_seq=excluded.summary_before_seq, computed_at=excluded.computed_at,
+         topics=excluded.topics`,
     );
     for (const channelSummary of input.channelSummaries ?? []) {
-      upsertChannel.run(thread_id, channelSummary.channel, channelSummary.summary, input.hotSince, hotSinceSeq, now());
+      upsertChannel.run(thread_id, channelSummary.channel, channelSummary.summary, input.hotSince, hotSinceSeq, now(), channelSummary.topics ?? null);
     }
     db.exec("COMMIT");
     return getThread(thread_id);