@circuitwall/jarela 2.2.1 → 2.3.0

package/lib/agents/warm-topics.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { canMergeIntoTopics, savedMemoryFacts } from "./warm-topics";
+
+const events = (...list: unknown[]) => JSON.stringify(list);
+
+describe("savedMemoryFacts", () => {
+  it("counts only saves the tool result confirms, including ones routed through invoke_tool", () => {
+    const row = {
+      seq: 1,
+      content: "",
+      tool_events: events(
+        { id: "a", phase: "call", name: "invoke_tool", payload: { name: "memory_write", args_json: JSON.stringify({ namespace: "facts", key: "editor", value: "Uses VS Code." }) } },
+        { id: "a", phase: "result", name: "invoke_tool", payload: JSON.stringify({ ok: true, namespace: "facts", key: "editor" }) },
+        { id: "b", phase: "call", name: "memory_upsert", payload: { namespace: "facts", key: "failed", record: { subject: "Failed" } } },
+        { id: "b", phase: "result", name: "memory_upsert", payload: JSON.stringify({ ok: false, error: "denied" }) },
+        { id: "c", phase: "call", name: "memory_upsert", payload: { namespace: "facts", key: "mismatch", record: { subject: "Mismatch" } } },
+        { id: "c", phase: "result", name: "memory_upsert", payload: JSON.stringify({ ok: true, key: "other" }) },
+        { id: "d", phase: "call", name: "memory_write", payload: { namespace: "state", key: "last_run", value: "x" } },
+        { id: "d", phase: "result", name: "memory_write", payload: JSON.stringify({ ok: true, key: "last_run" }) },
+      ),
+    };
+    expect(savedMemoryFacts(row)).toEqual([
+      { subject: "editor", content: "Uses VS Code.", tags: [], confidence: "explicit", key: "facts/editor", origin: "agent" },
+    ]);
+  });
+});
+
+describe("canMergeIntoTopics", () => {
+  const topic = { title: "t", start_seq: 1, end_seq: 4, start_at: "", end_at: "", recap: "r", facts: [], message_count: 4 };
+
+  it("extends stored topics only when the boundary moved forward and every topic carries its counts", () => {
+    expect(canMergeIntoTopics([topic], 5, 9)).toBe(true);
+    expect(canMergeIntoTopics([topic], 5, 5)).toBe(false);
+    expect(canMergeIntoTopics([{ ...topic, message_count: undefined }], 5, 9)).toBe(false);
+    expect(canMergeIntoTopics([topic], null, 9)).toBe(false);
+  });
+});

package/lib/agents/warm-topics.ts

@@ -0,0 +1,297 @@
+import { transcriptText, type SummaryTopicFact, type SummaryTopicSegment } from "@/lib/agents/conversation-summary";
+import type { PersistedToolEvent } from "@/lib/stores/threads";
+
+// Deterministic half of warm-context compaction. The summarizer model only
+// segments and recaps; everything that can be checked or computed in code —
+// message counts, which topic a saved memory belongs to, merging into the
+// stored topics, and fading out the oldest ones — lives here.
+
+export interface WarmTopicSourceRow {
+  seq: number;
+  content: string;
+  tool_events?: string | null;
+}
+
+const MAX_TOPIC_FACTS = 16;
+const MEMORY_WRITE_NAMESPACES = new Set(["facts"]);
+
+/** Stable id the compaction pipeline uses to refer to stored topic `index`. */
+export function warmTopicId(index: number): string {
+  return `t${index + 1}`;
+}
+
+function rowsInRange<T extends WarmTopicSourceRow>(rows: readonly T[], topic: SummaryTopicSegment): T[] {
+  return rows.filter((row) => row.seq >= (topic.start_seq ?? Infinity) && row.seq <= (topic.end_seq ?? -Infinity));
+}
+
+export function slugifyForMemoryKey(subject: string): string {
+  return subject
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}
+
+/**
+ * Merge facts by subject (case-insensitive) and memory key. Later entries win,
+ * so callers pass the newer or more trustworthy list last. Keeps the newest
+ * MAX_TOPIC_FACTS.
+ */
+export function mergeTopicFacts(...lists: readonly (readonly SummaryTopicFact[])[]): SummaryTopicFact[] {
+  const merged = new Map<string, SummaryTopicFact>();
+  const keyToSubject = new Map<string, string>();
+  for (const list of lists) {
+    for (const fact of list) {
+      const subjectId = fact.subject.trim().toLowerCase();
+      const existingSubject = fact.key ? keyToSubject.get(fact.key) : undefined;
+      if (existingSubject && existingSubject !== subjectId) merged.delete(existingSubject);
+      merged.delete(subjectId);
+      merged.set(subjectId, fact);
+      if (fact.key) keyToSubject.set(fact.key, subjectId);
+    }
+  }
+  return [...merged.values()].slice(-MAX_TOPIC_FACTS);
+}
+
+/**
+ * A topic must span at least two messages. Fold any single-message topic into
+ * the previous topic (or the next one when it is first). Input must be the
+ * ordered, non-overlapping output of validateTopicSegments.
+ */
+export function foldSingleMessageTopics(
+  topics: readonly SummaryTopicSegment[],
+  rows: readonly WarmTopicSourceRow[],
+): SummaryTopicSegment[] {
+  const out = topics.map((topic) => ({ ...topic, facts: [...topic.facts] }));
+  let index = 0;
+  while (out.length > 1 && index < out.length) {
+    if (rowsInRange(rows, out[index]).length >= 2) {
+      index += 1;
+      continue;
+    }
+    const single = out[index];
+    const targetIndex = index > 0 ? index - 1 : 1;
+    const target = out[targetIndex];
+    const [first, second] = targetIndex < index ? [target, single] : [single, target];
+    out[targetIndex] = {
+      ...target,
+      start_seq: first.start_seq,
+      start_at: first.start_at,
+      partial_start: first.partial_start,
+      end_seq: second.end_seq,
+      end_at: second.end_at,
+      recap: targetIndex < index ? `${target.recap} ${single.recap}` : `${single.recap} ${target.recap}`,
+      facts: mergeTopicFacts(target.facts, single.facts),
+      continues: target.continues ?? single.continues,
+    };
+    out.splice(index, 1);
+    if (targetIndex < index) index = targetIndex;
+  }
+  return out;
+}
+
+function toolResultText(payload: unknown): string | null {
+  if (typeof payload === "string") return payload;
+  if (!payload || typeof payload !== "object") return null;
+  const obj = payload as Record<string, unknown>;
+  if (obj.__truncated) return null;
+  const kwargs = obj.kwargs as Record<string, unknown> | undefined;
+  if (typeof kwargs?.content === "string") return kwargs.content;
+  if (typeof obj.content === "string") return obj.content;
+  return JSON.stringify(obj);
+}
+
+function parseObject(value: unknown): Record<string, unknown> | null {
+  if (value && typeof value === "object" && !Array.isArray(value)) return value as Record<string, unknown>;
+  if (typeof value !== "string") return null;
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}
+
+function unwrapCall(event: PersistedToolEvent): { name: string; args: Record<string, unknown> } | null {
+  const payload = parseObject(event.payload);
+  if (!payload) return null;
+  if (event.name !== "invoke_tool") return { name: event.name, args: payload };
+  const name = typeof payload.name === "string" ? payload.name : "";
+  const args = parseObject(payload.args_json) ?? parseObject(payload.args) ?? {};
+  return name ? { name, args } : null;
+}
+
+function savedFactFromCall(name: string, args: Record<string, unknown>, key: string): SummaryTopicFact | null {
+  const namespace = typeof args.namespace === "string" ? args.namespace : "";
+  if (name === "memory_upsert") {
+    const record = parseObject(args.record) ?? {};
+    const subject = typeof record.subject === "string" && record.subject.trim() ? record.subject.trim() : key;
+    const content = typeof record.content === "string" ? record.content.trim() : "";
+    const confidence = record.confidence === "explicit" || record.confidence === "inferred" || record.confidence === "verified"
+      ? record.confidence
+      : "explicit";
+    const tags = Array.isArray(record.tags) ? record.tags.filter((t): t is string => typeof t === "string").slice(0, 16) : [];
+    return { subject: subject.slice(0, 160), content: content.slice(0, 1_000), tags, confidence, key: `${namespace}/${key}`, origin: "agent" };
+  }
+  if (name === "memory_write" && MEMORY_WRITE_NAMESPACES.has(namespace)) {
+    const value = typeof args.value === "string" ? args.value.trim() : "";
+    return { subject: key, content: value.slice(0, 1_000), tags: [], confidence: "explicit", key: `${namespace}/${key}`, origin: "agent" };
+  }
+  return null;
+}
+
+/**
+ * Memory records the agent saved in a message, verified by the tool result
+ * (`ok: true` echoing the same key). Unverified or failed writes are skipped.
+ */
+export function savedMemoryFacts(row: WarmTopicSourceRow): SummaryTopicFact[] {
+  if (!row.tool_events) return [];
+  let events: PersistedToolEvent[];
+  try {
+    const parsed = JSON.parse(row.tool_events) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    events = parsed as PersistedToolEvent[];
+  } catch {
+    return [];
+  }
+  const calls = new Map<string, { name: string; args: Record<string, unknown> }>();
+  for (const event of events) {
+    if (event?.phase !== "call") continue;
+    const call = unwrapCall(event);
+    if (call && (call.name === "memory_upsert" || call.name === "memory_write")) calls.set(event.id, call);
+  }
+  const facts: SummaryTopicFact[] = [];
+  for (const event of events) {
+    if (event?.phase !== "result") continue;
+    const call = calls.get(event.id);
+    if (!call) continue;
+    const text = toolResultText(event.payload);
+    let result = text ? parseObject(text) : null;
+    if (result && typeof result.result === "string") result = parseObject(result.result) ?? result;
+    const key = typeof call.args.key === "string" ? call.args.key : "";
+    if (!result || result.ok !== true || !key || (typeof result.key === "string" && result.key !== key)) continue;
+    const fact = savedFactFromCall(call.name, call.args, key);
+    if (fact) facts.push(fact);
+  }
+  return facts;
+}
+
+/**
+ * Attach the code-derived fields to one topic: message count and size of the
+ * rows it covers, keys for extracted facts, and memory the agent saved there.
+ */
+export function finalizeTopic(
+  topic: SummaryTopicSegment,
+  covered: readonly WarmTopicSourceRow[],
+): SummaryTopicSegment {
+  const extracted = topic.facts.map((fact): SummaryTopicFact => ({
+    ...fact,
+    key: fact.key ?? `facts/${slugifyForMemoryKey(fact.subject)}`,
+    origin: fact.origin ?? "compaction",
+  }));
+  return {
+    ...topic,
+    facts: mergeTopicFacts(extracted, covered.flatMap(savedMemoryFacts)),
+    message_count: covered.length,
+    source_chars: covered.reduce((total, row) => total + transcriptText(row.content).length, 0),
+  };
+}
+
+/**
+ * Turn validated summarizer topics into stored topics: fold single-message
+ * topics, then finalize each against the rows in its seq range.
+ */
+export function finalizeFreshTopics(
+  topics: readonly SummaryTopicSegment[],
+  rows: readonly WarmTopicSourceRow[],
+): SummaryTopicSegment[] {
+  return foldSingleMessageTopics(topics, rows).map((topic) => finalizeTopic(topic, rowsInRange(rows, topic)));
+}
+
+/** Stored topics can be extended incrementally only when every one carries its message count and seq range. */
+export function canMergeIntoTopics(
+  prior: readonly SummaryTopicSegment[] | null | undefined,
+  priorBeforeSeq: number | null | undefined,
+  boundarySeq: number,
+): prior is SummaryTopicSegment[] {
+  if (!prior || prior.length === 0 || priorBeforeSeq == null || boundarySeq <= priorBeforeSeq) return false;
+  return prior.every((topic) =>
+    Number.isSafeInteger(topic.start_seq)
+    && Number.isSafeInteger(topic.end_seq)
+    && topic.end_seq! < priorBeforeSeq
+    && typeof topic.message_count === "number"
+    && Array.isArray(topic.facts),
+  );
+}
+
+/** Model-facing text for stored topics: one heading per topic, its recap, and the memory keys it produced. */
+export function renderTopicRecaps(topics: readonly SummaryTopicSegment[]): string {
+  return topics.map((topic) => {
+    const memorized = topic.facts.flatMap((fact) => fact.key ? [fact.key] : []);
+    return [
+      `### ${topic.title}${topic.partial_start ? " (partial; earlier messages omitted)" : ""}`,
+      topic.recap,
+      ...(memorized.length > 0 ? [`Memorized: ${memorized.join(", ")}`] : []),
+    ].join("\n");
+  }).join("\n\n");
+}
+
+export interface MergedWarmTopics {
+  topics: SummaryTopicSegment[];
+  sourceMessages: number;
+  sourceChars: number;
+  evicted: number;
+}
+
+/**
+ * Fold fresh topics into the stored ones, newest last. A fresh topic that
+ * `continues` a stored one updates it in place (newer recap, merged facts,
+ * summed counts). Then the least recently active topics fade out until the
+ * kept topics fit `messageLimit`, mirroring how memory keeps recent detail.
+ * Their facts already live in the memory store, so eviction loses no record.
+ */
+export function mergeWarmTopics(
+  prior: readonly SummaryTopicSegment[],
+  fresh: readonly SummaryTopicSegment[],
+  messageLimit: number,
+): MergedWarmTopics {
+  const out: SummaryTopicSegment[] = prior.map((topic) => ({ ...topic, facts: [...topic.facts] }));
+  const indexById = new Map(prior.map((_, index) => [warmTopicId(index), index]));
+  for (const topic of fresh) {
+    const { continues, ...clean } = topic;
+    const index = continues ? indexById.get(continues) : undefined;
+    if (index === undefined) {
+      out.push(clean);
+      continue;
+    }
+    const base = out[index];
+    out[index] = {
+      ...base,
+      title: clean.title,
+      end_seq: clean.end_seq,
+      end_at: clean.end_at,
+      recap: clean.recap,
+      facts: mergeTopicFacts(base.facts, clean.facts),
+      message_count: (base.message_count ?? 0) + (clean.message_count ?? 0),
+      source_chars: (base.source_chars ?? 0) + (clean.source_chars ?? 0),
+    };
+  }
+  out.sort((a, b) => (a.end_seq ?? 0) - (b.end_seq ?? 0));
+
+  let total = out.reduce((sum, topic) => sum + (topic.message_count ?? 0), 0);
+  let evicted = 0;
+  while (out.length > 1 && total > messageLimit) {
+    total -= out[0].message_count ?? 0;
+    out.shift();
+    evicted += 1;
+  }
+  return {
+    topics: out,
+    // The warm cache treats a count above the limit as an oversized legacy
+    // summary and rebuilds it; one topic larger than the limit is still a
+    // bounded, merged recap, so report it at the limit.
+    sourceMessages: Math.min(total, messageLimit),
+    sourceChars: out.reduce((sum, topic) => sum + (topic.source_chars ?? 0), 0),
+    evicted,
+  };
+}

package/lib/agents/workflow-step-retry.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildWorkflowStepRetryNudge,
+  collectWorkflowContractFailures,
+  planWorkflowStepRetries,
+  WORKFLOW_STEP_MAX_ATTEMPTS,
+  workflowProgressArgs,
+} from "./workflow-step-retry";
+
+const item = (id: string, status: string, extra: Record<string, unknown> = {}) => ({
+  id, label: `Step ${id}`, input: "in", output: "out", validation: "check", status, ...extra,
+});
+const ok = (workflowId: string, checklist: unknown[], phase: string | null = null, error: string | null = null) =>
+  JSON.stringify({ ok: true, workflow_id: workflowId, state: { phase, summary: "", error, checklist } });
+
+describe("collectWorkflowContractFailures", () => {
+  it("passes a workflow whose steps are verified or pending", () => {
+    expect(collectWorkflowContractFailures([
+      { args: { workflow_id: "w" }, result: ok("w", [item("a", "done", { validation_evidence: "ran" }), item("b", "pending")]) },
+    ])).toEqual([]);
+  });
+
+  it("flags a rejected update and names the step that broke the contract", () => {
+    const failures = collectWorkflowContractFailures([
+      { args: { workflow_id: "w", items: [item("a", "done")] }, result: JSON.stringify({ ok: false, workflow_id: "w", error: "Every completed workflow item requires observed validation_evidence." }) },
+    ]);
+    expect(failures).toEqual([expect.objectContaining({ key: "w:a", itemId: "a", label: "Step a" })]);
+    expect(failures[0].reason).toContain("validation_evidence");
+  });
+
+  it("clears a rejection once a later update for the same workflow is accepted", () => {
+    expect(collectWorkflowContractFailures([
+      { args: { workflow_id: "w", items: [item("a", "done")] }, result: { ok: false, workflow_id: "w", error: "x" } },
+      { args: { workflow_id: "w" }, result: ok("w", [item("a", "done", { validation_evidence: "ran" })]) },
+    ])).toEqual([]);
+  });
+
+  it("flags steps left checking or needing attention at turn end", () => {
+    const failures = collectWorkflowContractFailures([
+      { args: { workflow_id: "w" }, result: ok("w", [item("a", "checking"), item("b", "needs_attention")], null, "tests failed") },
+    ]);
+    expect(failures.map((f) => f.key)).toEqual(["w:a", "w:b"]);
+    expect(failures[1].reason).toContain("tests failed");
+  });
+
+  it("does not retry steps that are waiting on the user", () => {
+    expect(collectWorkflowContractFailures([
+      { args: { workflow_id: "w" }, result: ok("w", [item("a", "needs_attention", { needs_user: true })]) },
+      { args: { workflow_id: "version_adoption", item_id: "review-tools", status: "needs_attention", needs_user: true }, result: ok("version_adoption", [item("review-tools", "needs_attention")]) },
+    ])).toEqual([]);
+  });
+
+  it("ignores completed workflows and reads invoke_tool envelopes", () => {
+    expect(collectWorkflowContractFailures([
+      { args: { workflow_id: "w" }, result: ok("w", [item("a", "checking")], "complete") },
+    ])).toEqual([]);
+    expect(collectWorkflowContractFailures([
+      { args: { workflow_id: "w" }, result: { ok: true, tool: "workflow_progress", status: "done", result: ok("w", [item("a", "checking")]) } },
+    ]).map((f) => f.key)).toEqual(["w:a"]);
+  });
+});
+
+describe("workflowProgressArgs", () => {
+  it("unwraps direct and proxied workflow_progress calls only", () => {
+    expect(workflowProgressArgs("workflow_progress", { workflow_id: "w" })).toEqual({ workflow_id: "w" });
+    expect(workflowProgressArgs("invoke_tool", { name: "workflow_progress", args_json: "{\"workflow_id\":\"w\"}" })).toEqual({ workflow_id: "w" });
+    expect(workflowProgressArgs("invoke_tool", { name: "file_read", args_json: "{}" })).toBeNull();
+    expect(workflowProgressArgs("file_read", { workflow_id: "w" })).toBeNull();
+  });
+});
+
+describe("planWorkflowStepRetries", () => {
+  const failure = { key: "w:a", workflowId: "w", itemId: "a", label: "Step a", reason: "r" };
+
+  it(`allows ${WORKFLOW_STEP_MAX_ATTEMPTS} total attempts per step`, () => {
+    expect(planWorkflowStepRetries([failure]).retry).toEqual([{ ...failure, attempt: 2 }]);
+    expect(planWorkflowStepRetries([failure], { "w:a": 1 }).retry).toEqual([{ ...failure, attempt: 3 }]);
+    const exhausted = planWorkflowStepRetries([failure], { "w:a": 2 });
+    expect(exhausted.retry).toEqual([]);
+    expect(exhausted.exhausted).toEqual([failure]);
+  });
+});
+
+describe("buildWorkflowStepRetryNudge", () => {
+  it("states the attempt, the failure, and the exact progress call for each workflow kind", () => {
+    const nudge = buildWorkflowStepRetryNudge([
+      { key: "w:a", workflowId: "w", itemId: "a", label: "Step a", reason: "validation failed", attempt: 2 },
+      { key: "version_adoption:review-tools", workflowId: "version_adoption", itemId: "review-tools", label: "Review tools", reason: "left checking", attempt: 3 },
+    ]);
+    expect(nudge).toContain(`attempt 2 of ${WORKFLOW_STEP_MAX_ATTEMPTS}`);
+    expect(nudge).toContain("complete items snapshot");
+    expect(nudge).toContain('item_id: "review-tools"');
+    expect(nudge).toContain("needs_user: true");
+    expect(nudge).not.toMatch(/undefined|NaN|\[object Object\]/);
+  });
+});

package/lib/agents/workflow-step-retry.ts

@@ -0,0 +1,216 @@
+// Workflow-step contract enforcement. Every workflow_progress step promises
+// an input, an output, and a validation check; a model can still end a turn
+// with a rejected update, a step left mid-flight, or a step whose validation
+// failed. This module detects those breaches from the turn's own tool results
+// (code, not model judgement) and builds the targeted auto-retry nudge.
+
+/** Total attempts per step: the original attempt plus two automatic retries. */
+export const WORKFLOW_STEP_MAX_ATTEMPTS = 3;
+export const WORKFLOW_STEP_AUTO_RETRIES = WORKFLOW_STEP_MAX_ATTEMPTS - 1;
+/** Hard cap on automatic workflow retries in one turn, across all steps. */
+export const WORKFLOW_TURN_AUTO_RETRY_LIMIT = 6;
+
+export interface WorkflowProgressObservation {
+  args: unknown;
+  result: unknown;
+}
+
+export interface WorkflowStepFailure {
+  key: string;
+  workflowId: string;
+  itemId: string | null;
+  label: string;
+  reason: string;
+}
+
+type JsonObject = Record<string, unknown>;
+
+function asObject(value: unknown): JsonObject | null {
+  if (typeof value === "string") {
+    try { return asObject(JSON.parse(value)); } catch { return null; }
+  }
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const obj = value as JsonObject;
+    // LangChain ToolMessage-ish wrappers carry the JSON string in `content`
+    // or `kwargs.content`.
+    if (obj.workflow_id === undefined) {
+      // invoke_tool envelope: { ok, tool, status, result }.
+      if (obj.tool === "workflow_progress" && obj.result !== undefined) return asObject(obj.result);
+      const kwargs = asPlainObject(obj.kwargs);
+      const content = obj.content ?? kwargs?.content;
+      if (typeof content === "string") return asObject(content);
+    }
+    return obj;
+  }
+  return null;
+}
+
+function asPlainObject(value: unknown): JsonObject | null {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as JsonObject : null;
+}
+
+function str(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+/** Normalizes a direct workflow_progress call or an invoke_tool proxy of one. */
+export function workflowProgressArgs(name: string, args: unknown): JsonObject | null {
+  const obj = asPlainObject(args);
+  if (!obj) return null;
+  if (name === "workflow_progress") return obj;
+  if (name === "invoke_tool" && obj.name === "workflow_progress") {
+    const inner = obj.args_json ?? obj.args;
+    return asObject(inner);
+  }
+  return null;
+}
+
+function labelFor(itemId: string | null, items: unknown): string {
+  if (!itemId) return "workflow update";
+  if (Array.isArray(items)) {
+    for (const raw of items) {
+      const item = asPlainObject(raw);
+      if (item?.id === itemId && str(item.label)) return str(item.label)!;
+    }
+  }
+  return itemId.replace(/[_-]/g, " ");
+}
+
+function rejectedItemId(args: JsonObject | null): string | null {
+  if (!args) return null;
+  if (str(args.item_id)) return str(args.item_id);
+  if (Array.isArray(args.items)) {
+    for (const raw of args.items) {
+      const item = asPlainObject(raw);
+      if (item?.status === "done" && !str(item.validation_evidence) && str(item.id)) return str(item.id);
+    }
+  }
+  return null;
+}
+
+/**
+ * Returns the contract breaches still standing at the end of the turn, in
+ * the order the workflows were last touched. A later accepted update for the
+ * same workflow clears an earlier rejection.
+ */
+export function collectWorkflowContractFailures(observations: readonly WorkflowProgressObservation[]): WorkflowStepFailure[] {
+  type Entry = {
+    rejected: { itemId: string | null; label: string; error: string } | null;
+    checklist: unknown[];
+    phase: string | null;
+    error: string | null;
+    needsUser: Set<string>;
+  };
+  const latest = new Map<string, Entry>();
+  for (const { args, result } of observations) {
+    const payload = asObject(result);
+    const callArgs = asPlainObject(args);
+    const workflowId = str(payload?.workflow_id) ?? str(callArgs?.workflow_id);
+    if (!workflowId) continue;
+    const previous: Entry = latest.get(workflowId) ?? { rejected: null, checklist: [], phase: null, error: null, needsUser: new Set<string>() };
+    latest.delete(workflowId);
+    if (payload?.ok === false) {
+      const itemId = rejectedItemId(callArgs);
+      latest.set(workflowId, {
+        ...previous,
+        rejected: {
+          itemId,
+          label: labelFor(itemId, callArgs?.items ?? previous.checklist),
+          error: str(payload.error) ?? "the update was rejected",
+        },
+      });
+      continue;
+    }
+    const state = asPlainObject(payload?.state);
+    const needsUser = new Set(previous.needsUser);
+    const updatedItemId = str(callArgs?.item_id);
+    if (updatedItemId) {
+      if (callArgs?.needs_user === true) needsUser.add(updatedItemId);
+      else needsUser.delete(updatedItemId);
+    }
+    latest.set(workflowId, {
+      rejected: null,
+      checklist: Array.isArray(state?.checklist) ? state.checklist : previous.checklist,
+      phase: typeof state?.phase === "string" ? state.phase : null,
+      error: str(state?.error),
+      needsUser,
+    });
+  }
+
+  const failures: WorkflowStepFailure[] = [];
+  for (const [workflowId, entry] of latest) {
+    if (entry.rejected) {
+      const { itemId, label, error } = entry.rejected;
+      failures.push({
+        key: `${workflowId}:${itemId ?? "*"}`,
+        workflowId,
+        itemId,
+        label,
+        reason: `workflow_progress rejected the update: ${error}`,
+      });
+      continue;
+    }
+    if (entry.phase === "complete") continue;
+    for (const raw of entry.checklist) {
+      const item = asPlainObject(raw);
+      const itemId = str(item?.id);
+      if (!item || !itemId || item.needs_user === true || entry.needsUser.has(itemId)) continue;
+      const label = str(item.label) ?? itemId;
+      if (item.status === "checking") {
+        failures.push({
+          key: `${workflowId}:${itemId}`,
+          workflowId,
+          itemId,
+          label,
+          reason: "the step was started but the turn ended before its output was validated",
+        });
+      } else if (item.status === "needs_attention") {
+        const why = entry.error;
+        failures.push({
+          key: `${workflowId}:${itemId}`,
+          workflowId,
+          itemId,
+          label,
+          reason: `the step's validation did not pass (needs_attention${why ? `: ${why}` : ""})`,
+        });
+      }
+    }
+  }
+  return failures;
+}
+
+/** Splits failures into those with automatic retries left and those exhausted. */
+export function planWorkflowStepRetries(
+  failures: readonly WorkflowStepFailure[],
+  spent: Readonly<Record<string, number>> = {},
+): { retry: Array<WorkflowStepFailure & { attempt: number }>; exhausted: WorkflowStepFailure[] } {
+  const retry: Array<WorkflowStepFailure & { attempt: number }> = [];
+  const exhausted: WorkflowStepFailure[] = [];
+  for (const failure of failures) {
+    const used = spent[failure.key] ?? 0;
+    if (used < WORKFLOW_STEP_AUTO_RETRIES) retry.push({ ...failure, attempt: used + 2 });
+    else exhausted.push(failure);
+  }
+  return { retry, exhausted };
+}
+
+export function workflowStepRetryInstruction(workflowId: string, itemId: string | null, label: string): string {
+  if (!itemId) {
+    return `Resend the \`workflow_progress\` update for workflow \`${workflowId}\` so it satisfies the contract.`;
+  }
+  const progressUpdate = workflowId === "version_adoption"
+    ? `Call \`workflow_progress\` with \`workflow_id: "version_adoption"\`, \`item_id: "${itemId}"\`, and \`status: "checking"\``
+    : `Call \`workflow_progress\` for workflow \`${workflowId}\` with the complete items snapshot, setting this step to \`checking\``;
+  return `${progressUpdate}, then redo "${label}" from its stated input and run its validation again. Finally mark it \`done\` with newly observed \`validation_evidence\`, or \`needs_attention\` with the reason.`;
+}
+
+export function buildWorkflowStepRetryNudge(retries: ReadonlyArray<WorkflowStepFailure & { attempt: number }>): string {
+  const lines = retries.map((failure) => (
+    `- "${failure.label}" in \`${failure.workflowId}\` (attempt ${failure.attempt} of ${WORKFLOW_STEP_MAX_ATTEMPTS}): ${failure.reason}. ${workflowStepRetryInstruction(failure.workflowId, failure.itemId, failure.label)}`
+  ));
+  return [
+    `↻ Auto-retry: ${retries.length === 1 ? "a workflow step has" : `${retries.length} workflow steps have`} not met the step contract (input → output → validation):`,
+    ...lines,
+    "Work only on these steps and leave the others unchanged. Do not reuse earlier evidence or claim a result you did not observe. If a step is genuinely paused for the user's approval or input, mark it `needs_attention` with `needs_user: true` and say what you need instead of retrying.",
+  ].join("\n");
+}

package/lib/api/browser-control.ts

@@ -663,6 +663,3 @@ export async function handleBrowserRetry(req: Request): Promise<Response> {
   if (!entry.retryable || !entry.retry_payload) return jsonResponse({ error: "browser command is not retryable" }, 409);
   return awaitBrowserCommand(entry.retry_payload, parsed.data.timeout_ms ?? 30_000);
 }
-
-/** @internal — exported for the agent-side tool layer; do not import elsewhere. */
-export { CommandShape as _CommandShape };

package/lib/db/migrations.ts

@@ -629,6 +629,11 @@ function ensureThreadChannelSummariesTable(db: DatabaseSync): void {
   if (!cols.some((column) => column.name === "summary_before_seq")) {
     db.exec("ALTER TABLE thread_channel_summaries ADD COLUMN summary_before_seq INTEGER");
   }
+  // Stored topic segments (JSON array) so the next compaction can merge new
+  // activity into them instead of re-summarising the channel from scratch.
+  if (!cols.some((column) => column.name === "topics")) {
+    db.exec("ALTER TABLE thread_channel_summaries ADD COLUMN topics TEXT");
+  }
 }
 
 // ADR-0041. Immutable per-assistant-turn snapshot of LLM usage. Written once