@cueloop/schema 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/diff.ts

@@ -1,52 +1,66 @@
 /**
  * Line/token diffing and unified-diff serialization. The working copy
- * serializes as ONE unified diff against the submitted revision (map #2).
+ * serializes as ONE unified diff against the submitted revision.
  * Pure algorithms, no IO.
  */
 
-export type DiffOpType = "ctx" | "del" | "add";
+export type DiffOpKind = "ctx" | "del" | "add";
 
 export interface DiffOp<T = string> {
-  t: DiffOpType;
+  kind: DiffOpKind;
   /** Present for ctx and del. */
-  a?: T;
+  oldValue?: T;
   /** Present for ctx and add. */
-  b?: T;
+  newValue?: T;
 }
 
 /** LCS diff over arrays. O(n*m) - fine for plan-sized documents. */
-export function lcsDiff<T>(a: T[], b: T[], eq: (x: T, y: T) => boolean = (x, y) => x === y): DiffOp<T>[] {
-  const n = a.length;
-  const m = b.length;
-  const dp: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
-  for (let i = n - 1; i >= 0; i--) {
-    for (let j = m - 1; j >= 0; j--) {
-      dp[i]![j] = eq(a[i]!, b[j]!) ? dp[i + 1]![j + 1]! + 1 : Math.max(dp[i + 1]![j]!, dp[i]![j + 1]!);
+export function lcsDiff<T>(
+  oldItems: T[],
+  newItems: T[],
+  equals: (oldItem: T, newItem: T) => boolean = (oldItem, newItem) => oldItem === newItem,
+): DiffOp<T>[] {
+  const oldCount = oldItems.length;
+  const newCount = newItems.length;
+  const longestCommon: number[][] = Array.from({ length: oldCount + 1 }, () =>
+    Array.from({ length: newCount + 1 }, () => 0),
+  );
+
+  for (let oldIndex = oldCount - 1; oldIndex >= 0; oldIndex--) {
+    for (let newIndex = newCount - 1; newIndex >= 0; newIndex--) {
+      longestCommon[oldIndex]![newIndex] = equals(oldItems[oldIndex]!, newItems[newIndex]!)
+        ? longestCommon[oldIndex + 1]![newIndex + 1]! + 1
+        : Math.max(
+            longestCommon[oldIndex + 1]![newIndex]!,
+            longestCommon[oldIndex]![newIndex + 1]!,
+          );
     }
   }
-  const out: DiffOp<T>[] = [];
-  let i = 0;
-  let j = 0;
-  while (i < n && j < m) {
-    if (eq(a[i]!, b[j]!)) {
-      out.push({ t: "ctx", a: a[i], b: b[j] });
-      i++;
-      j++;
-    } else if (dp[i + 1]![j]! >= dp[i]![j + 1]!) {
-      out.push({ t: "del", a: a[i] });
-      i++;
+  const ops: DiffOp<T>[] = [];
+  let oldIndex = 0;
+  let newIndex = 0;
+
+  while (oldIndex < oldCount && newIndex < newCount) {
+    if (equals(oldItems[oldIndex]!, newItems[newIndex]!)) {
+      ops.push({ kind: "ctx", oldValue: oldItems[oldIndex], newValue: newItems[newIndex] });
+      oldIndex++;
+      newIndex++;
+    } else if (longestCommon[oldIndex + 1]![newIndex]! >= longestCommon[oldIndex]![newIndex + 1]!) {
+      ops.push({ kind: "del", oldValue: oldItems[oldIndex] });
+      oldIndex++;
     } else {
-      out.push({ t: "add", b: b[j] });
-      j++;
+      ops.push({ kind: "add", newValue: newItems[newIndex] });
+      newIndex++;
     }
   }
-  while (i < n) out.push({ t: "del", a: a[i++] });
-  while (j < m) out.push({ t: "add", b: b[j++] });
-  return out;
+  while (oldIndex < oldCount) ops.push({ kind: "del", oldValue: oldItems[oldIndex++] });
+  while (newIndex < newCount) ops.push({ kind: "add", newValue: newItems[newIndex++] });
+
+  return ops;
 }
 
 export interface UnifiedLine {
-  t: DiffOpType | "hunk";
+  kind: DiffOpKind | "hunk";
   text: string;
 }
 
@@ -56,58 +70,83 @@ export interface UnifiedLine {
  */
 export function unifiedDiff(oldText: string, newText: string, context = 3): UnifiedLine[] | null {
   const ops = lcsDiff(oldText.split("\n"), newText.split("\n"));
-  if (!ops.some((o) => o.t !== "ctx")) return null;
-  let ol = 1;
-  let nl = 1;
-  const rows = ops.map((o) => {
-    const r = {
-      t: o.t,
-      text: (o.t === "add" ? o.b : o.a) ?? "",
-      ol: o.t !== "add" ? ol : null,
-      nl: o.t !== "del" ? nl : null,
+
+  if (!ops.some((op) => op.kind !== "ctx")) return null;
+  let oldLineNumber = 1;
+  let newLineNumber = 1;
+  const rows = ops.map((op) => {
+    const row = {
+      kind: op.kind,
+      text: (op.kind === "add" ? op.newValue : op.oldValue) ?? "",
+      oldLine: op.kind !== "add" ? oldLineNumber : null,
+      newLine: op.kind !== "del" ? newLineNumber : null,
     };
-    if (o.t !== "add") ol++;
-    if (o.t !== "del") nl++;
-    return r;
+
+    if (op.kind !== "add") oldLineNumber++;
+    if (op.kind !== "del") newLineNumber++;
+
+    return row;
   });
-  const keep = new Array<boolean>(rows.length).fill(false);
-  rows.forEach((r, idx) => {
-    if (r.t !== "ctx") {
-      for (let k = Math.max(0, idx - context); k <= Math.min(rows.length - 1, idx + context); k++) keep[k] = true;
+  const keep = Array.from({ length: rows.length }, () => false);
+
+  rows.forEach((row, rowIndex) => {
+    if (row.kind !== "ctx") {
+      for (
+        let keepIndex = Math.max(0, rowIndex - context);
+        keepIndex <= Math.min(rows.length - 1, rowIndex + context);
+        keepIndex++
+      ) {
+        keep[keepIndex] = true;
+      }
     }
   });
   const hunks: { rows: (typeof rows)[number][] }[] = [];
-  let cur: { rows: (typeof rows)[number][] } | null = null;
-  rows.forEach((r, idx) => {
-    if (!keep[idx]) {
-      cur = null;
+  let openHunk: { rows: (typeof rows)[number][] } | null = null;
+
+  rows.forEach((row, rowIndex) => {
+    if (!keep[rowIndex]) {
+      openHunk = null;
+
       return;
     }
-    if (!cur) {
-      cur = { rows: [] };
-      hunks.push(cur);
+    if (!openHunk) {
+      openHunk = { rows: [] };
+      hunks.push(openHunk);
     }
-    cur.rows.push(r);
+    openHunk.rows.push(row);
   });
-  const out: UnifiedLine[] = [];
-  for (const h of hunks) {
-    const oStart = h.rows.find((r) => r.ol !== null)?.ol ?? 1;
-    const nStart = h.rows.find((r) => r.nl !== null)?.nl ?? 1;
-    const oCount = h.rows.filter((r) => r.t !== "add").length;
-    const nCount = h.rows.filter((r) => r.t !== "del").length;
-    out.push({ t: "hunk", text: `@@ -${oStart},${oCount} +${nStart},${nCount} @@` });
-    for (const r of h.rows) {
-      out.push({ t: r.t, text: (r.t === "add" ? "+" : r.t === "del" ? "-" : " ") + r.text });
+  const lines: UnifiedLine[] = [];
+
+  for (const hunk of hunks) {
+    const oldStart = hunk.rows.find((row) => row.oldLine !== null)?.oldLine ?? 1;
+    const newStart = hunk.rows.find((row) => row.newLine !== null)?.newLine ?? 1;
+    const oldCount = hunk.rows.filter((row) => row.kind !== "add").length;
+    const newCount = hunk.rows.filter((row) => row.kind !== "del").length;
+
+    lines.push({ kind: "hunk", text: `@@ -${oldStart},${oldCount} +${newStart},${newCount} @@` });
+    for (const row of hunk.rows) {
+      lines.push({
+        kind: row.kind,
+        text: (row.kind === "add" ? "+" : row.kind === "del" ? "-" : " ") + row.text,
+      });
     }
   }
-  return out;
+
+  return lines;
 }
 
 /** Render a unified diff as text with file headers. */
-export function unifiedDiffText(oldText: string, newText: string, path = "plan.md", context = 3): string | null {
-  const d = unifiedDiff(oldText, newText, context);
-  if (!d) return null;
-  return [`--- a/${path}`, `+++ b/${path}`, ...d.map((l) => l.text)].join("\n");
+export function unifiedDiffText(
+  oldText: string,
+  newText: string,
+  path = "plan.md",
+  context = 3,
+): string | null {
+  const lines = unifiedDiff(oldText, newText, context);
+
+  if (!lines) return null;
+
+  return [`--- a/${path}`, `+++ b/${path}`, ...lines.map((line) => line.text)].join("\n");
 }
 
 export interface EditStats {
@@ -116,16 +155,12 @@ export interface EditStats {
 }
 
 export function editStats(oldText: string, newText: string): EditStats {
-  const d = unifiedDiff(oldText, newText, 0);
-  if (!d) return { added: 0, removed: 0 };
+  const lines = unifiedDiff(oldText, newText, 0);
+
+  if (!lines) return { added: 0, removed: 0 };
+
   return {
-    added: d.filter((r) => r.t === "add").length,
-    removed: d.filter((r) => r.t === "del").length,
+    added: lines.filter((line) => line.kind === "add").length,
+    removed: lines.filter((line) => line.kind === "del").length,
   };
 }
-
-/** Word-level diff ops for tracked-changes rendering. Whitespace-preserving. */
-export function wordDiff(oldText: string, newText: string): DiffOp[] {
-  const tok = (s: string) => s.split(/(\s+)/).filter((x) => x !== "");
-  return lcsDiff(tok(oldText), tok(newText));
-}

package/src/feedback.test.ts

@@ -13,7 +13,9 @@ Review sessions live only in daemon memory today.
 Sessions are written as one JSON document per session.
 `;
 
-function ann(partial: Partial<Annotation> & { anchor: Annotation["anchor"] }): Annotation {
+function makeAnnotation(
+  partial: Partial<Annotation> & { anchor: Annotation["anchor"] },
+): Annotation {
   return {
     id: "a1",
     kind: "comment",
@@ -25,91 +27,366 @@ function ann(partial: Partial<Annotation> & { anchor: Annotation["anchor"] }): A
 
 describe("renderFeedback", () => {
   test("plan edits section carries the one unified diff, directive framing first", () => {
-    const out = renderFeedback({
+    // Act
+    const feedback = renderFeedback({
       verdictKind: "request_changes",
       summary: "Tighten the storage section.",
       artifactContent: PLAN,
       workingCopy: PLAN.replace("one JSON document", "one JSON record"),
       annotations: [],
-      planPath: "docs/plan.md",
-    });
-    expect(out).toContain("# Review: request changes");
-    expect(out).toContain("Tighten the storage section.");
-    expect(out).toContain("## Plan edits");
-    expect(out).toContain("Apply this exact diff first");
-    expect(out).toContain("--- a/docs/plan.md");
-    expect(out).toContain("-Sessions are written as one JSON document per session.");
-    expect(out).toContain("+Sessions are written as one JSON record per session.");
+      artifactPath: "docs/plan.md",
+    });
+
+    // Assert
+    expect(feedback).toContain("# Review: request changes");
+    expect(feedback).toContain("Tighten the storage section.");
+    expect(feedback).toContain("## Plan edits");
+    expect(feedback).toContain("Apply this exact diff first");
+    expect(feedback).toContain("--- a/docs/plan.md");
+    expect(feedback).toContain("-Sessions are written as one JSON document per session.");
+    expect(feedback).toContain("+Sessions are written as one JSON record per session.");
+  });
+
+  test("reply edits section is labelled for the reply artifact, not a plan", () => {
+    // Act
+    const feedback = renderFeedback({
+      verdictKind: "request_changes",
+      summary: "",
+      artifactContent: PLAN,
+      workingCopy: PLAN.replace("one JSON document", "one JSON record"),
+      artifactType: "reply",
+      annotations: [],
+      artifactPath: "reply.md",
+    });
+
+    // Assert
+    expect(feedback).toContain("## Reply edits");
+    expect(feedback).not.toContain("## Plan edits");
+    expect(feedback).toContain("Apply this exact diff first");
+  });
+
+  test("a reply review with no artifact path references reply.md, never plan.md", () => {
+    // Act
+    const feedback = renderFeedback({
+      verdictKind: "request_changes",
+      summary: "",
+      artifactContent: "# Findings\n\nThe cache is fine.\n",
+      artifactType: "reply",
+      annotations: [
+        makeAnnotation({ anchor: { quote: "The cache is fine.", prefix: "", suffix: "" } }),
+      ],
+      sessionId: "ses_reply",
+    });
+
+    // Assert
+    expect(feedback).toContain("Locate each one in reply.md");
+    expect(feedback).toContain("submit-revision ses_reply --content-file reply.md");
+    expect(feedback).not.toContain("plan.md");
+  });
+
+  test("a diff working copy is handed back as the curated patch, not a diff of diffs", () => {
+    // Arrange
+    const submittedPatch = `--- a/src/x.ts
++++ b/src/x.ts
+@@ -1,1 +1,1 @@
+-const limit = 100;
++const limit = 250;
+`;
+    const curatedPatch = `--- a/src/x.ts
++++ b/src/x.ts
+@@ -1,1 +1,1 @@
+-const limit = 100;
++const limit = 175;
+`;
+
+    // Act
+    const feedback = renderFeedback({
+      verdictKind: "request_changes",
+      summary: "",
+      artifactContent: submittedPatch,
+      workingCopy: curatedPatch,
+      artifactType: "diff",
+      annotations: [],
+    });
+
+    // Assert
+    expect(feedback).toContain("## Curated changes");
+    expect(feedback).toContain("+const limit = 175;");
+    // the submitted patch is not re-diffed against the curated one
+    expect(feedback).not.toContain("Plan edits");
+    expect(feedback).not.toContain("++const");
+  });
+
+  test("a diff working copy that rejected everything says so", () => {
+    // Act
+    const feedback = renderFeedback({
+      verdictKind: "request_changes",
+      summary: "",
+      artifactContent: "--- a/x\n+++ b/x\n@@ -1 +1 @@\n-a\n+b\n",
+      workingCopy: "",
+      artifactType: "diff",
+      annotations: [],
+    });
+
+    // Assert
+    expect(feedback).toContain("## Curated changes");
+    expect(feedback).toContain("rejected all of your proposed changes");
   });
 
   test("annotations are located by quote and section", () => {
-    const out = renderFeedback({
+    // Act
+    const feedback = renderFeedback({
       verdictKind: "comment",
       summary: "",
       artifactContent: PLAN,
       annotations: [
-        ann({
+        makeAnnotation({
           anchor: { quote: "daemon memory", prefix: "live only in ", suffix: " today." },
         }),
       ],
     });
-    expect(out).toContain("## Annotations (1)");
-    expect(out).toContain("### 1. Comment (§ Context)");
-    expect(out).toContain("> daemon memory");
-    expect(out).toContain("Please clarify.");
+
+    // Assert
+    expect(feedback).toContain("## Annotations (1)");
+    expect(feedback).toContain("### 1. Comment (§ Context)");
+    expect(feedback).toContain("> daemon memory");
+    expect(feedback).toContain("Please clarify.");
   });
 
-  test("suggestions render as replace/with pairs", () => {
-    const out = renderFeedback({
-      verdictKind: "request_changes",
+  test("a discussion renders as one item: the root comment, then its replies in order", () => {
+    // Arrange: a root, a later reply, an earlier reply, and a reply whose root is gone
+    const anchor = { quote: "daemon memory", prefix: "live only in ", suffix: " today." };
+
+    // Act
+    const feedback = renderFeedback({
+      verdictKind: "comment",
       summary: "",
       artifactContent: PLAN,
       annotations: [
-        ann({
-          kind: "suggestion",
-          body: "one durable JSON record",
-          anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." },
+        makeAnnotation({ id: "root", anchor, body: "Which daemon?" }),
+        makeAnnotation({
+          id: "late",
+          anchor,
+          body: "The local one, I think.",
+          replyTo: "root",
+          createdAt: "2026-08-07T00:02:00.000Z",
+        }),
+        makeAnnotation({
+          id: "early",
+          anchor,
+          body: "Worth stating in the plan.",
+          replyTo: "root",
+          author: "SHA256:ana",
+          createdAt: "2026-08-07T00:01:00.000Z",
         }),
+        makeAnnotation({ id: "stray", anchor, body: "Standalone.", replyTo: "gone" }),
       ],
     });
-    expect(out).toContain("### 1. Suggested change (§ Storage)");
-    expect(out).toContain("Replace:\n> one JSON document");
-    expect(out).toContain("With:\n> one durable JSON record");
+
+    // Assert: two items, replies listed under the root by time
+    expect(feedback).toContain("## Annotations (2)");
+    expect(feedback).toContain(
+      "Which daemon?\n\nReplies:\n\n- Worth stating in the plan.\n- The local one, I think.\n\nannotation id: `root`",
+    );
+    expect(feedback).toContain("### 2. Comment");
+    expect(feedback).toContain("Standalone.");
+    expect(feedback).not.toContain("annotation id: `late`");
+  });
+
+  test("a reply whose root was addressed leaves the document with it", () => {
+    // Arrange: the root is addressed, its reply is not marked, a stray reply's root is unknown
+    const anchor = { quote: "daemon memory", prefix: "live only in ", suffix: " today." };
+
+    // Act
+    const feedback = renderFeedback({
+      verdictKind: "comment",
+      summary: "",
+      artifactContent: PLAN,
+      annotations: [
+        makeAnnotation({
+          id: "root",
+          anchor,
+          body: "Which daemon?",
+          resolution: { revision: 2, source: "agent" },
+        }),
+        makeAnnotation({ id: "reply", anchor, body: "The local one.", replyTo: "root" }),
+        makeAnnotation({ id: "stray", anchor, body: "Standalone.", replyTo: "gone" }),
+      ],
+    });
+
+    // Assert: only the stray reply remains, as its own item
+    expect(feedback).toContain("## Annotations (1)");
+    expect(feedback).not.toContain("The local one.");
+    expect(feedback).toContain("Standalone.");
   });
 
   test("orphaned anchors are flagged, never dropped", () => {
-    const out = renderFeedback({
+    // Act
+    const feedback = renderFeedback({
       verdictKind: "comment",
       summary: "",
       artifactContent: PLAN,
-      annotations: [ann({ anchor: { quote: "text that is gone", prefix: "", suffix: "" } })],
+      annotations: [
+        makeAnnotation({ anchor: { quote: "text that is gone", prefix: "", suffix: "" } }),
+      ],
     });
-    expect(out).toContain("[orphaned anchor: the quoted text is no longer present]");
-    expect(out).toContain("> text that is gone");
+
+    // Assert
+    expect(feedback).toContain("[orphaned anchor: the quoted text is no longer present]");
+    expect(feedback).toContain("> text that is gone");
   });
 
   test("empty review says so explicitly", () => {
-    const out = renderFeedback({
+    // Act
+    const feedback = renderFeedback({
       verdictKind: "approve",
       summary: "",
       artifactContent: PLAN,
       annotations: [],
     });
-    expect(out).toContain("_No edits or annotations._");
+
+    // Assert
+    expect(feedback).toContain("_No edits or annotations._");
+  });
+
+  test("agent notes never come back as feedback items", () => {
+    // Arrange
+    const note = makeAnnotation({
+      kind: "note",
+      anchor: { quote: "src/a.ts", prefix: "", suffix: "" },
+      body: "The agent's own explanation of the change.",
+    });
+
+    // Act
+    const noteOnly = renderFeedback({
+      verdictKind: "approve",
+      summary: "",
+      artifactContent: PLAN,
+      annotations: [note],
+    });
+
+    // Assert
+    expect(noteOnly).toContain("_No edits or annotations._");
+    expect(noteOnly).not.toContain("The agent's own explanation of the change.");
+    const mixed = renderFeedback({
+      verdictKind: "request_changes",
+      summary: "",
+      artifactContent: PLAN,
+      annotations: [
+        note,
+        makeAnnotation({
+          anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." },
+        }),
+      ],
+    });
+
+    expect(mixed).toContain("## Annotations (1)");
+    expect(mixed).not.toContain("The agent's own explanation of the change.");
   });
 
   test("anchors resolve against the working copy when present", () => {
+    // Arrange
     // annotation made on text that only exists in the edited copy
     const working = PLAN.replace("## Storage", "## Persistence");
-    const out = renderFeedback({
+
+    // Act
+    const feedback = renderFeedback({
       verdictKind: "request_changes",
       summary: "",
       artifactContent: PLAN,
       workingCopy: working,
       annotations: [
-        ann({ anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." } }),
+        makeAnnotation({
+          anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." },
+        }),
+      ],
+    });
+
+    // Assert
+    expect(feedback).toContain("(§ Persistence)");
+  });
+
+  test("a prototype annotation locates by its selector and is never orphan-flagged", () => {
+    // Act
+    const feedback = renderFeedback({
+      verdictKind: "request_changes",
+      summary: "",
+      artifactType: "prototype",
+      artifactContent: "<main><div class='card'>Pricing</div></main>",
+      annotations: [
+        makeAnnotation({
+          body: "Tighten the padding.",
+          anchor: { quote: "Pricing", prefix: "", suffix: "", selector: "main > div.card" },
+        }),
+      ],
+      artifactPath: "proto.html",
+    });
+
+    // Assert
+    expect(feedback).toContain("(main > div.card)");
+    expect(feedback).toContain("Tighten the padding.");
+    expect(feedback).toContain("by its CSS selector");
+    expect(feedback).not.toContain("orphaned anchor");
+  });
+});
+
+describe("renderFeedback target grouping", () => {
+  test("file notes group under their own path section, apart from the artifact", () => {
+    const feedback = renderFeedback({
+      verdictKind: "request_changes",
+      summary: "",
+      artifactContent: PLAN,
+      artifactPath: "docs/plan.md",
+      annotations: [
+        makeAnnotation({
+          id: "art1",
+          anchor: { quote: "Sessions are written", prefix: "", suffix: "" },
+          body: "artifact note",
+        }),
+        makeAnnotation({
+          id: "f1",
+          anchor: { quote: "const a = 1", prefix: "", suffix: "" },
+          target: { kind: "file", path: "src/a.ts", rev: "worktree" },
+          body: "file a note",
+        }),
+        makeAnnotation({
+          id: "f2",
+          anchor: { quote: "const b = 2", prefix: "", suffix: "" },
+          target: { kind: "file", path: "src/b.ts", rev: "worktree" },
+          body: "file b note",
+        }),
+      ],
+    });
+
+    // Assert - the artifact keeps its section; each file gets its own, with its note
+    expect(feedback).toContain("## Annotations (1)");
+    expect(feedback).toContain("artifact note");
+    expect(feedback).toContain("## src/a.ts (1)");
+    expect(feedback).toContain("file a note");
+    expect(feedback).toContain("## src/b.ts (1)");
+    expect(feedback).toContain("file b note");
+    // the file note's path is the heading, not an inline "(in ...)" locator on the artifact list
+    expect(feedback).not.toContain("(in src/a.ts)");
+  });
+
+  test("a quick-action reference expands to its body; an unknown skill reference passes through", () => {
+    const feedback = renderFeedback({
+      verdictKind: "comment",
+      summary: "",
+      artifactContent: PLAN,
+      annotations: [
+        makeAnnotation({
+          anchor: { quote: "Storage", prefix: "", suffix: "" },
+          body: "/restate-simplified and also /vitest-patterns here",
+        }),
       ],
+      artifactPath: "docs/plan.md",
+      actionBodies: { "restate-simplified": "Restate this as the simplest thing that works." },
     });
-    expect(out).toContain("(§ Persistence)");
+
+    expect(feedback).toContain("Restate this as the simplest thing that works.");
+    // the unknown reference (a user skill) is left verbatim for the harness to resolve
+    expect(feedback).toContain("/vitest-patterns");
+    expect(feedback).not.toContain("/restate-simplified");
   });
 });