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

package/src/feedback.ts

@@ -1,11 +1,18 @@
 /**
  * feedback.md: the ONE structured markdown document the agent receives on
- * resolve (map #2, verified in the edit-mode deep-dive). Directive framing -
- * soft phrasing gets ignored by models: the plan diff is applied verbatim
- * first, then every annotation is addressed, located by quoted text.
+ * resolve. Directive framing - soft phrasing gets ignored by models: the plan
+ * diff is applied verbatim first, then every annotation is addressed, located
+ * by quoted text.
  */
 
-import type { Annotation, ReviewSession, VerdictKind } from "./types";
+import {
+  isAddressed,
+  isAgentNote,
+  type Annotation,
+  type ArtifactType,
+  type ReviewSession,
+  type VerdictKind,
+} from "./types";
 import { parseBlocks, sectionOf } from "./markdown";
 import { resolveAnchor } from "./anchor";
 import { unifiedDiffText } from "./diff";
@@ -15,19 +22,37 @@ export interface FeedbackInput {
   summary: string;
   /** The submitted artifact content (latest revision). */
   artifactContent: string;
-  /** The reviewer's working copy; undefined = no direct edits. */
+  /** The reviewer's working copy; undefined = no direct edits. For a diff it is
+   *  the curated patch (accepted hunks); for a plan it is the edited source. */
   workingCopy?: string;
+  /** Artifact kind; defaults to "plan". A diff working copy is already a patch. */
+  artifactType?: ArtifactType;
   annotations: Annotation[];
-  /** Path the agent knows the plan by, for direct reference. */
-  planPath?: string;
+  /** Path the agent knows the artifact by (plan or prototype), for direct reference. */
+  artifactPath?: string;
+  /** Session id, so the document can teach the addressed-ids resubmit call. */
+  sessionId?: string;
 }
 
-const quoteLines = (s: string) => "> " + s.replace(/\n/g, "\n> ");
+const quoteLines = (text: string) => "> " + text.replace(/\n/g, "\n> ");
 
 export function renderFeedback(input: FeedbackInput): string {
-  const path = input.planPath ?? "plan.md";
-  const blocks = parseBlocks(input.workingCopy ?? input.artifactContent);
+  const path = input.artifactPath ?? "plan.md";
+  // agent notes are the submitter's own context - never echoed back as
+  // feedback - and annotations a previous revision already addressed stay out
+  // of the next document, so the agent only ever sees the open items
+  const annotations = input.annotations.filter(
+    (annotation) => !isAgentNote(annotation) && !isAddressed(annotation),
+  );
+  const isDiff = input.artifactType === "diff";
+  const isPrototype = input.artifactType === "prototype";
+  // A diff's annotations anchor to the submitted patch rows; resolve against it,
+  // not the curated working copy (which may drop the rejected rows).
+  const blocks = parseBlocks(
+    isDiff ? input.artifactContent : (input.workingCopy ?? input.artifactContent),
+  );
   const lines: string[] = [];
+
   lines.push("# Review: " + input.verdictKind.replace("_", " "));
   lines.push("");
   if (input.summary.trim()) {
@@ -35,66 +60,118 @@ export function renderFeedback(input: FeedbackInput): string {
     lines.push("");
   }
 
-  const diff =
-    input.workingCopy !== undefined ? unifiedDiffText(input.artifactContent, input.workingCopy, path) : null;
-  if (diff) {
-    lines.push("## 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.");
+  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.
+    hasEdits = true;
+    lines.push("## Curated changes");
     lines.push("");
-    lines.push("```diff");
-    lines.push(diff);
-    lines.push("```");
+    if (input.workingCopy.trim()) {
+      lines.push("The reviewer accepted a subset of your proposed changes. Apply this");
+      lines.push("exact unified diff; it replaces what you submitted.");
+      lines.push("");
+      lines.push("```diff");
+      lines.push(input.workingCopy);
+      lines.push("```");
+    } else {
+      lines.push("The reviewer rejected all of your proposed changes.");
+    }
     lines.push("");
+  } else {
+    const diff =
+      input.workingCopy !== undefined
+        ? unifiedDiffText(input.artifactContent, input.workingCopy, path)
+        : null;
+
+    if (diff) {
+      hasEdits = true;
+      // 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.");
+      lines.push("");
+      lines.push("```diff");
+      lines.push(diff);
+      lines.push("```");
+      lines.push("");
+    }
   }
 
-  if (input.annotations.length) {
-    lines.push(`## Annotations (${input.annotations.length})`);
+  if (annotations.length) {
+    lines.push(`## Annotations (${annotations.length})`);
     lines.push("");
-    lines.push(`Address every item. Locate each one in ${path} by its quoted text.`);
+    lines.push(
+      isPrototype
+        ? `Address every item. Locate each one in ${path} by its CSS selector.`
+        : `Address every item. Locate each one in ${path} by its quoted text.`,
+    );
     lines.push("");
-    input.annotations.forEach((a, i) => {
-      const res = resolveAnchor(a.anchor, blocks);
-      const sec = res ? sectionOf(blocks, res.blockIndex) : "";
-      const loc = sec ? ` (§ ${sec})` : "";
-      const flag = res === null ? " [orphaned anchor: the quoted text is no longer present]" : "";
-      if (a.kind === "suggestion") {
-        lines.push(`### ${i + 1}. Suggested change${loc}${flag}`);
-        lines.push("");
-        lines.push("Replace:");
-        lines.push(quoteLines(a.anchor.quote));
-        lines.push("With:");
-        lines.push(quoteLines(a.body));
-      } else {
-        lines.push(`### ${i + 1}. ${capitalize(a.kind)}${loc}${flag}`);
-        lines.push("");
-        lines.push(quoteLines(a.anchor.quote));
-        lines.push("");
-        lines.push(a.body);
-      }
+    annotations.forEach((annotation, annotationIndex) => {
+      // a prototype selector anchor is never resolved or orphaned against blocks
+      const selector = annotation.anchor.selector;
+      const resolved = selector ? null : resolveAnchor(annotation.anchor, blocks);
+      const sectionTitle = resolved ? sectionOf(blocks, resolved.blockIndex) : "";
+      const location = selector ? ` (${selector})` : sectionTitle ? ` (§ ${sectionTitle})` : "";
+      const orphanFlag =
+        !selector && resolved === null
+          ? " [orphaned anchor: the quoted text is no longer present]"
+          : "";
+
+      lines.push(
+        `### ${annotationIndex + 1}. ${capitalize(annotation.kind)}${location}${orphanFlag}`,
+      );
+      lines.push("");
+      lines.push(quoteLines(annotation.anchor.quote));
+      lines.push("");
+      lines.push(annotation.body);
+      lines.push("");
+      lines.push(`annotation id: \`${annotation.id}\``);
       lines.push("");
     });
+    if (input.sessionId) {
+      lines.push("## Reporting what you addressed");
+      lines.push("");
+      lines.push("When you resubmit the revised plan, list the annotation ids you acted on -");
+      lines.push("they are marked addressed for the reviewer and leave the open list:");
+      lines.push("");
+      lines.push("```sh");
+      lines.push(
+        `cueloop session submit-revision ${input.sessionId} --content-file ${path} --addressed <id,id,...>`,
+      );
+      lines.push("```");
+      lines.push("");
+    }
   }
 
-  if (!diff && !input.annotations.length) {
+  if (!hasEdits && !annotations.length) {
     lines.push("_No edits or annotations._");
     lines.push("");
   }
+
   return lines.join("\n");
 }
 
-export function feedbackForSession(session: ReviewSession, verdictKind: VerdictKind, summary: string): string {
+export function feedbackForSession(
+  session: ReviewSession,
+  verdictKind: VerdictKind,
+  summary: string,
+): string {
   return renderFeedback({
     verdictKind,
     summary,
     artifactContent: session.artifact.content,
     workingCopy: session.workingCopy,
+    artifactType: session.artifact.type,
     annotations: session.annotations,
-    planPath: session.artifact.meta.planPath,
+    artifactPath: session.artifact.meta.prototypePath ?? session.artifact.meta.planPath,
+    sessionId: session.id,
   });
 }
 
-function capitalize(s: string): string {
-  return s.charAt(0).toUpperCase() + s.slice(1);
+function capitalize(word: string): string {
+  return word.charAt(0).toUpperCase() + word.slice(1);
 }

package/src/fuzzy.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test } from "bun:test";
+import { fuzzyFindBestMatch, levenshteinDistance, similarityRatio } from "./fuzzy";
+
+describe("levenshteinDistance", () => {
+  test("identical strings cost nothing", () => {
+    // Arrange / Act / Assert
+    expect(levenshteinDistance("anchor", "anchor")).toBe(0);
+  });
+
+  test("counts a single substitution", () => {
+    // Arrange / Act / Assert
+    expect(levenshteinDistance("plan", "plane")).toBe(1);
+  });
+
+  test("empty against non-empty costs the whole length", () => {
+    // Arrange / Act / Assert
+    expect(levenshteinDistance("", "quote")).toBe(5);
+  });
+
+  test("is symmetric", () => {
+    // Arrange / Act / Assert
+    expect(levenshteinDistance("kitten", "sitting")).toBe(levenshteinDistance("sitting", "kitten"));
+  });
+});
+
+describe("similarityRatio", () => {
+  test("two empty strings are identical", () => {
+    // Arrange / Act / Assert
+    expect(similarityRatio("", "")).toBe(1);
+  });
+
+  test("identical strings score one", () => {
+    // Arrange / Act / Assert
+    expect(similarityRatio("review", "review")).toBe(1);
+  });
+
+  test("a one-character typo in a long string stays close to one", () => {
+    // Arrange
+    const original = "demonstration plan";
+
+    // Act
+    const ratio = similarityRatio(original, "demonstration plann");
+
+    // Assert
+    expect(ratio).toBeGreaterThan(0.9);
+  });
+
+  test("unrelated strings score low", () => {
+    // Arrange / Act / Assert
+    expect(similarityRatio("abcdef", "zyxwvu")).toBeLessThan(0.2);
+  });
+});
+
+describe("fuzzyFindBestMatch", () => {
+  test("finds a lightly edited window and reports its offsets", () => {
+    // Arrange
+    const haystack = "the quick brown fox jumps";
+
+    // Act
+    const match = fuzzyFindBestMatch("quikc brown", haystack, 0.75)!;
+
+    // Assert
+    expect(match).not.toBeNull();
+    expect(haystack.slice(match.start, match.end)).toBe("quick brown");
+    expect(match.similarity).toBeGreaterThan(0.75);
+  });
+
+  test("returns null when nothing clears the similarity floor", () => {
+    // Arrange / Act
+    const match = fuzzyFindBestMatch("completely unrelated", "short text", 0.75);
+
+    // Assert
+    expect(match).toBeNull();
+  });
+
+  test("an empty needle or haystack never matches", () => {
+    // Arrange / Act / Assert
+    expect(fuzzyFindBestMatch("", "text", 0.75)).toBeNull();
+    expect(fuzzyFindBestMatch("text", "", 0.75)).toBeNull();
+  });
+
+  test("ties keep the earliest window", () => {
+    // Arrange
+    const haystack = "word word";
+
+    // Act
+    const match = fuzzyFindBestMatch("word", haystack, 0.9)!;
+
+    // Assert
+    expect(match.start).toBe(0);
+  });
+});

package/src/fuzzy.ts

@@ -0,0 +1,101 @@
+/**
+ * Approximate string matching for anchor re-binding. The anchor resolver falls
+ * back to these when exact and marker-normalized quote lookups both miss - the
+ * quoted text is still present but was lightly edited (a word changed, a typo
+ * fixed, punctuation adjusted). Everything here is pure and offset-exact so it
+ * can be tested in isolation from the resolver.
+ */
+
+/** A window of the haystack that best matches the needle. */
+export interface FuzzyMatch {
+  /** Inclusive start offset into the haystack. */
+  start: number;
+  /** Exclusive end offset into the haystack. */
+  end: number;
+  /** Similarity of the matched window to the needle, in [0, 1]. */
+  similarity: number;
+}
+
+/**
+ * Levenshtein edit distance: the fewest single-character insertions, deletions,
+ * or substitutions that turn `left` into `right`. Uses two rolling rows, so it
+ * costs O(left.length * right.length) time and O(right.length) space.
+ */
+export function levenshteinDistance(left: string, right: string): number {
+  if (left === right) return 0;
+  if (left.length === 0) return right.length;
+  if (right.length === 0) return left.length;
+
+  let previousRow: number[] = Array.from({ length: right.length + 1 }, (_unused, column) => column);
+  let currentRow: number[] = Array.from({ length: right.length + 1 }, () => 0);
+
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex++) {
+    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
+        previousRow[rightIndex - 1]! + substitutionCost, // substitution
+      );
+    }
+    const swap = previousRow;
+
+    previousRow = currentRow;
+    currentRow = swap;
+  }
+
+  return previousRow[right.length]!;
+}
+
+/**
+ * Similarity of two strings in [0, 1]: 1 is identical, 0 shares nothing. Derived
+ * from the edit distance normalized by the longer string. Two empty strings are
+ * defined as identical (1).
+ */
+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;
+}
+
+/**
+ * Find the haystack window most similar to the needle, or null when nothing
+ * clears `minimumSimilarity`. Windows range around the needle length so the
+ * match tolerates a few inserted or deleted characters, not only substitutions.
+ * Ties keep the earliest window. Offsets index the haystack directly.
+ */
+export function fuzzyFindBestMatch(
+  needle: string,
+  haystack: string,
+  minimumSimilarity: number,
+): FuzzyMatch | null {
+  if (needle === "" || haystack === "") return null;
+
+  const lengthTolerance = Math.max(2, Math.round(needle.length * 0.25));
+  const minimumWindowLength = Math.max(1, needle.length - lengthTolerance);
+  const maximumWindowLength = needle.length + lengthTolerance;
+
+  let bestMatch: FuzzyMatch | null = null;
+
+  for (let start = 0; start < haystack.length; start++) {
+    for (
+      let windowLength = minimumWindowLength;
+      windowLength <= maximumWindowLength && start + windowLength <= haystack.length;
+      windowLength++
+    ) {
+      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.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import { detectHerdr, insideHerdr, returnPaneFor } from "./herdr";
+
+describe("detectHerdr", () => {
+  test("null outside herdr, context inside", () => {
+    expect(detectHerdr({})).toBeNull();
+    // no HERDR_ENV or no pane id means we are not in a usable herdr pane
+    expect(detectHerdr({ HERDR_PANE_ID: "p1" })).toBeNull();
+    expect(detectHerdr({ HERDR_ENV: "1" })).toBeNull();
+    // herdr 0.8.0 sets no HERDR_BIN_PATH: the binary defaults to `herdr` on PATH
+    expect(detectHerdr({ HERDR_ENV: "1", HERDR_PANE_ID: "p1" })).toEqual({
+      paneId: "p1",
+      binPath: "herdr",
+    });
+    // an explicit HERDR_BIN_PATH (tests, or a pinned install) still wins
+    expect(
+      detectHerdr({ HERDR_ENV: "1", HERDR_PANE_ID: "p1", HERDR_BIN_PATH: "/x/herdr" }),
+    ).toEqual({
+      paneId: "p1",
+      binPath: "/x/herdr",
+    });
+  });
+});
+
+describe("insideHerdr", () => {
+  test("true only when HERDR_ENV is exactly 1", () => {
+    expect(insideHerdr({})).toBeFalse();
+    expect(insideHerdr({ HERDR_ENV: "0" })).toBeFalse();
+    expect(insideHerdr({ HERDR_ENV: "1" })).toBeTrue();
+  });
+});
+
+describe("returnPaneFor", () => {
+  test("outside herdr there is never a return target", () => {
+    expect(returnPaneFor("w1:p1", {})).toBeUndefined();
+  });
+
+  test("env override wins, session meta is the fallback", () => {
+    // Arrange
+    const inside = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p9" };
+
+    // Assert
+    expect(returnPaneFor("w1:p1", inside)).toBe("w1:p1");
+    expect(returnPaneFor("w1:p1", { ...inside, CUELOOP_RETURN_PANE: "w1:p2" })).toBe("w1:p2");
+  });
+
+  test("returning to our own pane is a no-op", () => {
+    expect(returnPaneFor("w1:p1", { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1" })).toBeUndefined();
+  });
+});

package/src/herdr.ts

@@ -0,0 +1,54 @@
+/**
+ * The herdr ambient env contract, single-sourced. A process running inside a
+ * herdr pane sees HERDR_ENV=1 plus the pane id; the herdr CLI itself reaches
+ * the app over HERDR_SOCKET_PATH (which the spawned `herdr` reads from the
+ * inherited env), so the binary is just `herdr` on PATH. Both the agent-side
+ * reporter (adapters) and the reviewer-side return-focus (client) read this
+ * contract; decoding it in one place stops the two sides drifting on which
+ * vars are required. Pure: no IO, env is only the default argument so callers
+ * can pass a fixture.
+ */
+
+export interface HerdrContext {
+  paneId: string;
+  binPath: string;
+}
+
+export type HerdrEnv = Record<string, string | undefined>;
+
+/**
+ * The pane's full contract - pane id and binary path - or null outside a
+ * functioning herdr. Required by anything that spawns the herdr CLI.
+ */
+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 };
+}
+
+/** True whenever this process runs inside a herdr pane. */
+export function insideHerdr(env: HerdrEnv = process.env): boolean {
+  return env.HERDR_ENV === "1";
+}
+
+/**
+ * The pane a closing review should hand focus back to: the opener's
+ * CUELOOP_RETURN_PANE, or the session's recorded pane, but never this pane
+ * itself. Undefined outside herdr or when the only candidate is our own pane.
+ */
+export function returnPaneFor(
+  sessionHerdrPane?: string,
+  env: HerdrEnv = process.env,
+): 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/index.ts

@@ -1,5 +1,10 @@
 export * from "./types";
+export * from "./participants";
 export * from "./markdown";
+export * from "./inline";
+export * from "./working-copy";
 export * from "./diff";
 export * from "./anchor";
+export * from "./fuzzy";
 export * from "./feedback";
+export * from "./herdr";