@cueloop/schema 0.1.0-alpha.59 → 0.1.0-alpha.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/schema",
-  "version": "0.1.0-alpha.59",
+  "version": "0.1.0-alpha.60",
   "description": "The ReviewSession primitive: types, markdown block model, quote-primary anchors, feedback serialization",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {

package/src/anchor.test.ts

@@ -63,6 +63,7 @@ describe("anchor cascade", () => {
 
     // Assert
     const editedBlockIndex = edited.findIndex((block) => block.text.includes("Review sessions"));
+
     expect(resolved.blockIndex).toBe(editedBlockIndex);
     expect(edited[resolved.blockIndex]!.text.slice(resolved.start, resolved.end)).toBe(
       "Review sessions",

package/src/anchor.ts

@@ -42,6 +42,7 @@ export function makeAnchor(
   end: number,
 ): Anchor {
   const blockText = blocks[blockIndex]?.text ?? "";
+
   return {
     quote: blockText.slice(start, end),
     prefix: blockText.slice(Math.max(0, start - ANCHOR_CONTEXT_CHARS), start),
@@ -70,24 +71,29 @@ function contextScore(
   const prefix = block.text.slice(Math.max(0, start - ANCHOR_CONTEXT_CHARS), start);
   const suffix = block.text.slice(end, end + ANCHOR_CONTEXT_CHARS);
   let score = 0;
+
   if (prefix === anchor.prefix) score += 2;
   if (suffix === anchor.suffix) score += 2;
   if (anchor.blockIndex === blockIndex) score += 1;
   if (anchor.blockIndex === blockIndex && anchor.start === start) score += 1;
+
   return score;
 }
 
 /** Every verbatim occurrence of `quote` across the blocks, scored by context. */
 function findExactCandidates(anchor: Anchor, blocks: Block[], quote: string): Candidate[] {
   const candidates: Candidate[] = [];
+
   blocks.forEach((block, blockIndex) => {
     const text = block.text;
+
     for (
       let matchStart = text.indexOf(quote);
       matchStart !== -1;
       matchStart = text.indexOf(quote, matchStart + 1)
     ) {
       const matchEnd = matchStart + quote.length;
+
       candidates.push({
         blockIndex,
         start: matchStart,
@@ -96,6 +102,7 @@ function findExactCandidates(anchor: Anchor, blocks: Block[], quote: string): Ca
       });
     }
   });
+
   return candidates;
 }
 
@@ -115,14 +122,18 @@ function findFuzzyCandidates(
   minimumSimilarity: number,
 ): Candidate[] {
   const candidates: Candidate[] = [];
+
   blocks.forEach((block, blockIndex) => {
     const match = fuzzyFindBestMatch(needle, block.text, minimumSimilarity);
+
     if (match === null) return;
     const score =
       match.similarity +
       contextScore(anchor, blockIndex, block, match.start, match.end) * FUZZY_CONTEXT_TIE_BREAK;
+
     candidates.push({ blockIndex, start: match.start, end: match.end, score });
   });
+
   return candidates;
 }
 
@@ -130,6 +141,7 @@ function findFuzzyCandidates(
 function pickBest(candidates: Candidate[]): Candidate | null {
   if (candidates.length === 0) return null;
   candidates.sort((left, right) => right.score - left.score);
+
   return candidates[0]!;
 }
 
@@ -148,25 +160,32 @@ export function resolveAnchor(anchor: Anchor, blocks: Block[]): ResolvedAnchor |
   if (anchor.quote === "") return null;
 
   const exact = pickBest(findExactCandidates(anchor, blocks, anchor.quote));
+
   if (exact) return resolved(exact, "exact");
 
   const trimmedQuote = anchor.quote.trim();
+
   if (trimmedQuote !== "" && trimmedQuote !== anchor.quote) {
     const trimmed = pickBest(findExactCandidates(anchor, blocks, trimmedQuote));
+
     if (trimmed) return resolved(trimmed, "trimmed");
   }
 
   const normalizedQuote = stripLeadingBlockMarker(anchor.quote).trim();
+
   if (normalizedQuote !== "" && normalizedQuote !== trimmedQuote) {
     const normalized = pickBest(findExactCandidates(anchor, blocks, normalizedQuote));
+
     if (normalized) return resolved(normalized, "normalized");
   }
 
   const fuzzyNeedle = normalizedQuote !== "" ? normalizedQuote : trimmedQuote;
+
   if (fuzzyNeedle !== "") {
     const fuzzy = pickBest(
       findFuzzyCandidates(anchor, blocks, fuzzyNeedle, FUZZY_MINIMUM_SIMILARITY),
     );
+
     if (fuzzy) return resolved(fuzzy, "fuzzy");
   }
 

package/src/diff.test.ts

@@ -30,6 +30,7 @@ describe("unifiedDiff", () => {
     // Arrange
     const oldLines = Array.from({ length: 30 }, (_, i) => `line ${i + 1}`);
     const newLines = [...oldLines];
+
     newLines[1] = "first change";
     newLines[27] = "second change";
 
@@ -50,6 +51,7 @@ describe("unifiedDiff", () => {
 
     // Assert
     const rebuilt: string[] = [];
+
     for (const line of diffLines) {
       if (line.kind === "hunk") continue;
       if (line.kind === "ctx" || line.kind === "add") rebuilt.push(line.text.slice(1));

package/src/diff.ts

@@ -25,6 +25,7 @@ export function lcsDiff<T>(
   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]!)
@@ -38,6 +39,7 @@ export function lcsDiff<T>(
   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] });
@@ -53,6 +55,7 @@ export function lcsDiff<T>(
   }
   while (oldIndex < oldCount) ops.push({ kind: "del", oldValue: oldItems[oldIndex++] });
   while (newIndex < newCount) ops.push({ kind: "add", newValue: newItems[newIndex++] });
+
   return ops;
 }
 
@@ -67,6 +70,7 @@ 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((op) => op.kind !== "ctx")) return null;
   let oldLineNumber = 1;
   let newLineNumber = 1;
@@ -77,11 +81,14 @@ export function unifiedDiff(oldText: string, newText: string, context = 3): Unif
       oldLine: op.kind !== "add" ? oldLineNumber : null,
       newLine: op.kind !== "del" ? newLineNumber : null,
     };
+
     if (op.kind !== "add") oldLineNumber++;
     if (op.kind !== "del") newLineNumber++;
+
     return row;
   });
   const keep = Array.from({ length: rows.length }, () => false);
+
   rows.forEach((row, rowIndex) => {
     if (row.kind !== "ctx") {
       for (
@@ -95,9 +102,11 @@ export function unifiedDiff(oldText: string, newText: string, context = 3): Unif
   });
   const hunks: { rows: (typeof rows)[number][] }[] = [];
   let openHunk: { rows: (typeof rows)[number][] } | null = null;
+
   rows.forEach((row, rowIndex) => {
     if (!keep[rowIndex]) {
       openHunk = null;
+
       return;
     }
     if (!openHunk) {
@@ -107,11 +116,13 @@ export function unifiedDiff(oldText: string, newText: string, context = 3): Unif
     openHunk.rows.push(row);
   });
   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({
@@ -120,6 +131,7 @@ export function unifiedDiff(oldText: string, newText: string, context = 3): Unif
       });
     }
   }
+
   return lines;
 }
 
@@ -131,7 +143,9 @@ export function unifiedDiffText(
   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");
 }
 
@@ -142,7 +156,9 @@ export interface EditStats {
 
 export function editStats(oldText: string, newText: string): EditStats {
   const lines = unifiedDiff(oldText, newText, 0);
+
   if (!lines) return { added: 0, removed: 0 };
+
   return {
     added: lines.filter((line) => line.kind === "add").length,
     removed: lines.filter((line) => line.kind === "del").length,

package/src/feedback.test.ts

@@ -47,6 +47,24 @@ describe("renderFeedback", () => {
     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 diff working copy is handed back as the curated patch, not a diff of diffs", () => {
     // Arrange
     const submittedPatch = `--- a/src/x.ts
@@ -175,6 +193,7 @@ describe("renderFeedback", () => {
         }),
       ],
     });
+
     expect(mixed).toContain("## Annotations (1)");
     expect(mixed).not.toContain("The agent's own explanation of the change.");
   });

package/src/feedback.ts

@@ -52,6 +52,7 @@ export function renderFeedback(input: FeedbackInput): string {
     isDiff ? input.artifactContent : (input.workingCopy ?? input.artifactContent),
   );
   const lines: string[] = [];
+
   lines.push("# Review: " + input.verdictKind.replace("_", " "));
   lines.push("");
   if (input.summary.trim()) {
@@ -60,6 +61,7 @@ export function renderFeedback(input: FeedbackInput): string {
   }
 
   let hasEdits = false;
+
   if (isDiff && input.workingCopy !== undefined) {
     // The diff working copy is already the curated patch - the accepted subset
     // of the submitted changes - so hand it back verbatim, not a diff of diffs.
@@ -82,9 +84,12 @@ export function renderFeedback(input: FeedbackInput): string {
       input.workingCopy !== undefined
         ? unifiedDiffText(input.artifactContent, input.workingCopy, path)
         : null;
+
     if (diff) {
       hasEdits = true;
-      lines.push("## Plan edits");
+      // The edits section names the markdown artifact it edited (plan or reply)
+      // so the directive is not mislabelled when the artifact is not a plan.
+      lines.push(input.artifactType === "reply" ? "## Reply edits" : "## Plan edits");
       lines.push("");
       lines.push(`The reviewer edited ${path} directly. Apply this exact diff first;`);
       lines.push("it is a unified diff against the version you submitted.");
@@ -115,6 +120,7 @@ export function renderFeedback(input: FeedbackInput): string {
         !selector && resolved === null
           ? " [orphaned anchor: the quoted text is no longer present]"
           : "";
+
       lines.push(
         `### ${annotationIndex + 1}. ${capitalize(annotation.kind)}${location}${orphanFlag}`,
       );
@@ -145,6 +151,7 @@ export function renderFeedback(input: FeedbackInput): string {
     lines.push("_No edits or annotations._");
     lines.push("");
   }
+
   return lines.join("\n");
 }
 

package/src/fuzzy.ts

@@ -33,6 +33,7 @@ export function levenshteinDistance(left: string, right: string): number {
     currentRow[0] = leftIndex;
     for (let rightIndex = 1; rightIndex <= right.length; rightIndex++) {
       const substitutionCost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+
       currentRow[rightIndex] = Math.min(
         currentRow[rightIndex - 1]! + 1, // insertion
         previousRow[rightIndex]! + 1, // deletion
@@ -40,6 +41,7 @@ export function levenshteinDistance(left: string, right: string): number {
       );
     }
     const swap = previousRow;
+
     previousRow = currentRow;
     currentRow = swap;
   }
@@ -54,7 +56,9 @@ export function levenshteinDistance(left: string, right: string): number {
  */
 export function similarityRatio(left: string, right: string): number {
   const longestLength = Math.max(left.length, right.length);
+
   if (longestLength === 0) return 1;
+
   return 1 - levenshteinDistance(left, right) / longestLength;
 }
 
@@ -76,6 +80,7 @@ export function fuzzyFindBestMatch(
   const maximumWindowLength = needle.length + lengthTolerance;
 
   let bestMatch: FuzzyMatch | null = null;
+
   for (let start = 0; start < haystack.length; start++) {
     for (
       let windowLength = minimumWindowLength;
@@ -84,11 +89,13 @@ export function fuzzyFindBestMatch(
     ) {
       const window = haystack.slice(start, start + windowLength);
       const similarity = similarityRatio(needle, window);
+
       if (similarity < minimumSimilarity) continue;
       if (bestMatch === null || similarity > bestMatch.similarity) {
         bestMatch = { start, end: start + windowLength, similarity };
       }
     }
   }
+
   return bestMatch;
 }

package/src/herdr.ts

@@ -23,11 +23,13 @@ export type HerdrEnv = Record<string, string | undefined>;
 export function detectHerdr(env: HerdrEnv = process.env): HerdrContext | null {
   if (env.HERDR_ENV !== "1") return null;
   const paneId = env.HERDR_PANE_ID;
+
   if (!paneId) return null;
   // herdr 0.8.0 exposes no HERDR_BIN_PATH; the CLI is `herdr` on PATH and finds
   // the app over HERDR_SOCKET_PATH from the inherited env. Tests still override
   // HERDR_BIN_PATH to point the spawn at a stub script.
   const binPath = env.HERDR_BIN_PATH ?? "herdr";
+
   return { paneId, binPath };
 }
 
@@ -47,5 +49,6 @@ export function returnPaneFor(
 ): string | undefined {
   if (!insideHerdr(env)) return undefined;
   const pane = env.CUELOOP_RETURN_PANE ?? sessionHerdrPane;
+
   return pane && pane !== env.HERDR_PANE_ID ? pane : undefined;
 }

package/src/inline.test.ts

@@ -59,6 +59,7 @@ describe("inlineRuns", () => {
     ] as const) {
       const runs = inlineRuns(source);
       const content = runs.find((run) => run.role === role)!;
+
       expect(content.text).toBe(inner);
       expect(source.slice(content.start!, content.start! + inner.length)).toBe(inner);
       expect(reconstruct(runs)).toBe(source);
@@ -74,6 +75,7 @@ describe("inlineRuns", () => {
 
     // Assert - the backtick content is one literal code run, no strong inside
     const code = runs.find((run) => run.role === "code")!;
+
     expect(code.text).toBe("a**b**c");
     expect(runs.some((run) => run.role === "strong")).toBe(false);
   });
@@ -150,6 +152,7 @@ describe("inlineRuns", () => {
     // Assert
     for (const source of ["**not closed", "a * b", "`open code", "[label](noclose"]) {
       const runs = inlineRuns(source);
+
       expect(reconstruct(runs)).toBe(source);
       expect(runs.every((run) => run.role === "text" || run.role === "marker")).toBe(true);
       expect(offsetsAreExact(source, runs)).toBe(true);
@@ -174,6 +177,7 @@ describe("inlineRuns", () => {
     expect(reconstruct(runs)).toBe("not \\*emph\\* here");
     expect(offsetsAreExact("not \\*emph\\* here", runs)).toBe(true);
     const star = runs.find((run) => run.text === "*" && run.start !== null)!;
+
     expect("not \\*emph\\* here"[star.start!]).toBe("*");
   });
 

package/src/inline.ts

@@ -44,7 +44,9 @@ const PUNCTUATION = new Set(["*", "_", "`", "~", "[", "]", "(", ")", "\\"]);
 /** Tokenize one block's text into visible + concealed-marker runs, in order. */
 export function inlineRuns(text: string): InlineRun[] {
   const runs: InlineRun[] = [];
+
   tokenize(text, 0, "text", runs);
+
   return runs;
 }
 
@@ -76,6 +78,7 @@ function tokenize(source: string, base: number, role: InlineRole, out: InlineRun
     }
 
     const link = matchLink(source, cursor);
+
     if (link) {
       flushPlain(cursor);
       out.push({ text: source.slice(cursor, link.labelStart), role: "marker", start: null });
@@ -92,6 +95,7 @@ function tokenize(source: string, base: number, role: InlineRole, out: InlineRun
     }
 
     const code = matchCode(source, cursor);
+
     if (code) {
       flushPlain(cursor);
       out.push({ text: source.slice(cursor, code.contentStart), role: "marker", start: null });
@@ -107,6 +111,7 @@ function tokenize(source: string, base: number, role: InlineRole, out: InlineRun
     }
 
     const span = matchEmphasis(source, cursor);
+
     if (span) {
       flushPlain(cursor);
       out.push({
@@ -115,6 +120,7 @@ function tokenize(source: string, base: number, role: InlineRole, out: InlineRun
         start: null,
       });
       const contentStart = cursor + span.openLength;
+
       tokenize(source.slice(contentStart, span.closeIndex), base + contentStart, span.role, out);
       out.push({
         text: source.slice(span.closeIndex, span.closeIndex + span.closeLength),
@@ -145,14 +151,17 @@ function matchLink(
   if (text[index] !== "[") return null;
   const labelStart = index + 1;
   const labelEnd = text.indexOf("]", labelStart);
+
   if (labelEnd < 0 || labelEnd === labelStart) return null;
   if (text[labelEnd + 1] !== "(") return null;
   const hrefStart = labelEnd + 2;
   // the destination may carry balanced parentheses (wiki URLs); the span ends
   // at the first unmatched closer
   let depth = 0;
+
   for (let scan = hrefStart; scan < text.length; scan++) {
     const character = text[scan];
+
     if (character === "(") depth++;
     else if (character === ")") {
       if (depth > 0) {
@@ -160,9 +169,11 @@ function matchLink(
         continue;
       }
       if (scan === hrefStart) return null;
+
       return { labelStart, labelEnd, hrefStart, hrefEnd: scan, end: scan + 1 };
     }
   }
+
   return null;
 }
 
@@ -173,20 +184,25 @@ function matchCode(
 ): { contentStart: number; contentEnd: number; end: number } | null {
   if (text[index] !== "`") return null;
   let fence = 0;
+
   while (text[index + fence] === "`") fence++;
   const contentStart = index + fence;
   const closer = "`".repeat(fence);
   const contentEnd = text.indexOf(closer, contentStart);
+
   if (contentEnd < 0 || contentEnd === contentStart) return null;
+
   return { contentStart, contentEnd, end: contentEnd + fence };
 }
 
 /** A `**strong**`, `*em*`, or `~~strike~~` span at `index`, or null. */
 function matchEmphasis(text: string, index: number): Span | null {
   const two = text.slice(index, index + 2);
+
   if (two === "**") return closingSpan(text, index, 2, "strong");
   if (two === "~~") return closingSpan(text, index, 2, "strike");
   if (text[index] === "*") return closingSpan(text, index, 1, "em");
+
   return null;
 }
 
@@ -201,13 +217,16 @@ function closingSpan(
   const contentStart = index + length;
   const closeIndex =
     length === 1 ? findLoneStar(text, contentStart) : text.indexOf(marker, contentStart);
+
   if (closeIndex < 0 || closeIndex === contentStart) return null; // unbalanced or empty
+
   return { openLength: length, closeLength: length, closeIndex, role };
 }
 
 /** Index of the next standalone `*` (not part of a `**` run), or -1. */
 function findLoneStar(text: string, from: number): number {
   let index = from;
+
   while (index < text.length) {
     if (text[index] === "*") {
       if (text[index + 1] !== "*") return index;
@@ -216,5 +235,6 @@ function findLoneStar(text: string, from: number): number {
     }
     index++;
   }
+
   return -1;
 }

package/src/markdown.test.ts

@@ -47,6 +47,7 @@ describe("parseBlocks", () => {
       "hr",
     ]);
     const code = blocks.find((block) => block.kind === "code")!;
+
     expect(code.lang).toBe("ts");
     expect(code.text).toBe("const x = 1;\nconst y = 2;");
     // fence lines included in the source range
@@ -84,6 +85,7 @@ describe("parseBlocks", () => {
     const rebuilt = blocks
       .map((block) => {
         orderedItemCount = block.kind === "oli" ? orderedItemCount + 1 : 0;
+
         return blockToMd(block, orderedItemCount || 1);
       })
       .join("\n\n");
@@ -117,8 +119,10 @@ describe("sectionOf", () => {
 
     // Assert
     const orderedItemIndex = blocks.findIndex((block) => block.kind === "oli");
+
     expect(sectionOf(blocks, orderedItemIndex)).toBe("Steps");
     const paragraphIndex = blocks.findIndex((block) => block.kind === "p");
+
     expect(sectionOf(blocks, paragraphIndex)).toBe("Context");
   });
 });

package/src/markdown.ts

@@ -41,8 +41,10 @@ export function parseBlocks(markdown: string): Block[] {
   const lines = markdown.split("\n");
   const blocks: Block[] = [];
   let lineIndex = 0;
+
   while (lineIndex < lines.length) {
     const line = lines[lineIndex]!;
+
     if (line.trim() === "") {
       lineIndex++;
       continue;
@@ -50,13 +52,16 @@ export function parseBlocks(markdown: string): Block[] {
     if (line.startsWith("```")) {
       const start = lineIndex;
       const lang = line.slice(3).trim() || undefined;
+
       lineIndex++;
       const body: string[] = [];
+
       while (lineIndex < lines.length && !lines[lineIndex]!.startsWith("```")) {
         body.push(lines[lineIndex]!);
         lineIndex++;
       }
       const end = Math.min(lineIndex, lines.length - 1);
+
       lineIndex++;
       blocks.push({ kind: "code", text: body.join("\n"), lang, lineStart: start, lineEnd: end });
     } else if (line.startsWith("### ")) {
@@ -89,6 +94,7 @@ export function parseBlocks(markdown: string): Block[] {
     } else if (line.startsWith("> ")) {
       const start = lineIndex;
       const body: string[] = [];
+
       while (lineIndex < lines.length && lines[lineIndex]!.startsWith("> ")) {
         body.push(stripLeadingBlockMarker(lines[lineIndex]!));
         lineIndex++;
@@ -118,6 +124,7 @@ export function parseBlocks(markdown: string): Block[] {
     } else {
       const start = lineIndex;
       const body: string[] = [];
+
       while (
         lineIndex < lines.length &&
         lines[lineIndex]!.trim() !== "" &&
@@ -129,6 +136,7 @@ export function parseBlocks(markdown: string): Block[] {
       blocks.push({ kind: "p", text: body.join("\n"), lineStart: start, lineEnd: lineIndex - 1 });
     }
   }
+
   return blocks;
 }
 
@@ -162,10 +170,13 @@ export function blockToMd(block: Block, ordinal = 1): string {
 /** The section (nearest preceding heading) a block belongs to. */
 export function sectionOf(blocks: Block[], index: number): string {
   let sectionTitle = "";
+
   for (let blockIndex = 0; blockIndex <= index && blockIndex < blocks.length; blockIndex++) {
     const block = blocks[blockIndex]!;
+
     if (block.kind === "h1" || block.kind === "h2" || block.kind === "h3")
       sectionTitle = block.text;
   }
+
   return sectionTitle;
 }

package/src/participants.ts

@@ -21,12 +21,14 @@ export function registerParticipant(
   const participants = session.participants ?? [];
   const existing = participants.find((participant) => participant.id === author);
   const trimmed = name?.trim();
+
   if (existing && !trimmed) return session;
   const next: Identity = {
     id: author,
     provider: "ssh",
     ...(trimmed ? { name: trimmed } : existing?.name ? { name: existing.name } : {}),
   };
+
   return {
     ...session,
     participants: existing

package/src/types.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { newAnnotationId, verdictAllows } from "./types";
+import { isMarkdownArtifact, newAnnotationId, verdictAllows } from "./types";
 
 describe("verdictAllows", () => {
   test("only approve maps to allow", () => {
@@ -9,6 +9,15 @@ describe("verdictAllows", () => {
   });
 });
 
+describe("isMarkdownArtifact", () => {
+  test("plan and reply are markdown; diff and prototype are not", () => {
+    expect(isMarkdownArtifact("plan")).toBe(true);
+    expect(isMarkdownArtifact("reply")).toBe(true);
+    expect(isMarkdownArtifact("diff")).toBe(false);
+    expect(isMarkdownArtifact("prototype")).toBe(false);
+  });
+});
+
 describe("newAnnotationId", () => {
   test("unique by construction within a process, even on one millisecond", () => {
     // Act

package/src/types.ts

@@ -12,14 +12,30 @@ export interface WorkspaceKey {
   branch: string;
 }
 
-export type ArtifactType = "plan" | "diff" | "prototype";
+/**
+ * What kind of artifact a review session holds. `plan` and `reply` are both
+ * markdown documents (see isMarkdownArtifact) - a plan is a proposal written
+ * forward, a reply is the agent's previous message pulled back for review.
+ * `diff` is a unified-diff patch; `prototype` is a rendered HTML page.
+ */
+export type ArtifactType = "plan" | "diff" | "prototype" | "reply";
+
+/**
+ * Markdown artifacts (plan, reply) are block-parsed and quote-anchored, so they
+ * share the plan render path, first-heading title derivation, and revision
+ * drift-assist. A diff (a patch) and a prototype (HTML/DOM) do not - keep this
+ * the one place that names the set, so a new markdown primitive joins here once.
+ */
+export function isMarkdownArtifact(type: ArtifactType): boolean {
+  return type === "plan" || type === "reply";
+}
 
 export interface ArtifactMeta {
   cwd?: string;
   agent?: string;
   /** Agent-native session id, for resume/fork context. */
   agentSessionId?: string;
-  /** Path to the plan file on disk, so feedback can reference it. */
+  /** Path to the plan or reply markdown file on disk, so feedback can reference it. */
   planPath?: string;
   /** Path to the prototype's entry HTML file on disk. */
   prototypePath?: string;
@@ -45,7 +61,7 @@ export interface DiffFileContents {
 
 export interface Artifact {
   type: ArtifactType;
-  /** Markdown source for plans; unified-diff text for diffs. */
+  /** Markdown source for plans and replies; unified-diff text for diffs. */
   content: string;
   meta: ArtifactMeta;
   /**
@@ -201,6 +217,7 @@ export function verdictAllows(kind: VerdictKind): boolean {
  * annotators in different processes on the same millisecond.
  */
 let annotationSeq = 0;
+
 export function newAnnotationId(): string {
   return `a_${Date.now().toString(36)}${(annotationSeq++).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
 }

package/src/working-copy.test.ts

@@ -139,6 +139,7 @@ describe("restoreBlock", () => {
     ).toBeUndefined();
     // a real text change keeps the working copy alive
     const changed = restoreBlock(BASE, cut.replace("first", "1st"), listItem, line);
+
     expect(changed).toContain("1st item");
   });
 });

package/src/working-copy.ts

@@ -10,6 +10,7 @@ import { parseBlocks, type Block } from "./markdown";
 /** Chunk of the base source a block occupies (for restore and display). */
 export function sourceChunk(base: string, block: Block): string {
   const lines = base.split("\n");
+
   return lines.slice(block.lineStart, block.lineEnd + 1).join("\n");
 }
 
@@ -18,7 +19,9 @@ export function cutBlock(working: string, block: Block): string {
   const lines = working.split("\n");
   const before = lines.slice(0, block.lineStart);
   const after = lines.slice(block.lineEnd + 1);
+
   while (before.length && before[before.length - 1]!.trim() === "") before.pop();
+
   return [...before, ...after].join("\n");
 }
 
@@ -54,8 +57,10 @@ export function restoreBlock(
   const before = lines.slice(0, beforeLine);
   const after = lines.slice(beforeLine);
   const insertedLines = sourceChunk(base, block).split("\n");
+
   if (before.length && before[before.length - 1]!.trim() !== "") insertedLines.unshift("");
   if (after.length && after[0]!.trim() !== "") insertedLines.push("");
   const restored = [...before, ...insertedLines, ...after].join("\n");
+
   return signature(restored) === signature(base) ? undefined : restored;
 }