@cueloop/schema 0.1.0-alpha.3 → 0.1.0-alpha.30

package/src/feedback.test.ts

@@ -13,7 +13,7 @@ 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,7 +25,8 @@ 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,
@@ -33,83 +34,126 @@ describe("renderFeedback", () => {
       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.");
+
+    // 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("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({
+    // Act
+    const feedback = renderFeedback({
       verdictKind: "request_changes",
       summary: "",
       artifactContent: PLAN,
       annotations: [
-        ann({
+        makeAnnotation({
           kind: "suggestion",
           body: "one durable JSON record",
           anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." },
         }),
       ],
     });
-    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
+    expect(feedback).toContain("### 1. Suggested change (§ Storage)");
+    expect(feedback).toContain("Replace:\n> one JSON document");
+    expect(feedback).toContain("With:\n> one durable JSON record");
   });
 
   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." } }),
       ],
     });
-    expect(out).toContain("(§ Persistence)");
+
+    // Assert
+    expect(feedback).toContain("(§ Persistence)");
   });
 });

package/src/feedback.ts

@@ -1,11 +1,11 @@
 /**
  * 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 ReviewSession, type VerdictKind } from "./types";
 import { parseBlocks, sectionOf } from "./markdown";
 import { resolveAnchor } from "./anchor";
 import { unifiedDiffText } from "./diff";
@@ -20,12 +20,18 @@ export interface FeedbackInput {
   annotations: Annotation[];
   /** Path the agent knows the plan by, for direct reference. */
   planPath?: 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";
+  // 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 blocks = parseBlocks(input.workingCopy ?? input.artifactContent);
   const lines: string[] = [];
   lines.push("# Review: " + input.verdictKind.replace("_", " "));
@@ -49,35 +55,48 @@ export function renderFeedback(input: FeedbackInput): string {
     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("");
-    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}`);
+    annotations.forEach((annotation, annotationIndex) => {
+      const resolved = resolveAnchor(annotation.anchor, blocks);
+      const sectionTitle = resolved ? sectionOf(blocks, resolved.blockIndex) : "";
+      const location = sectionTitle ? ` (§ ${sectionTitle})` : "";
+      const orphanFlag = resolved === null ? " [orphaned anchor: the quoted text is no longer present]" : "";
+      if (annotation.kind === "suggestion") {
+        lines.push(`### ${annotationIndex + 1}. Suggested change${location}${orphanFlag}`);
         lines.push("");
         lines.push("Replace:");
-        lines.push(quoteLines(a.anchor.quote));
+        lines.push(quoteLines(annotation.anchor.quote));
         lines.push("With:");
-        lines.push(quoteLines(a.body));
+        lines.push(quoteLines(annotation.body));
       } else {
-        lines.push(`### ${i + 1}. ${capitalize(a.kind)}${loc}${flag}`);
+        lines.push(`### ${annotationIndex + 1}. ${capitalize(annotation.kind)}${location}${orphanFlag}`);
         lines.push("");
-        lines.push(quoteLines(a.anchor.quote));
+        lines.push(quoteLines(annotation.anchor.quote));
         lines.push("");
-        lines.push(a.body);
+        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 (!diff && !annotations.length) {
     lines.push("_No edits or annotations._");
     lines.push("");
   }
@@ -92,9 +111,10 @@ export function feedbackForSession(session: ReviewSession, verdictKind: VerdictK
     workingCopy: session.workingCopy,
     annotations: session.annotations,
     planPath: 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/herdr.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import { detectHerdr, insideHerdr, returnPaneFor } from "./herdr";
+
+describe("detectHerdr", () => {
+  test("null outside herdr, context inside", () => {
+    expect(detectHerdr({})).toBeNull();
+    expect(detectHerdr({ HERDR_ENV: "1", HERDR_PANE_ID: "p1" })).toBeNull();
+    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,43 @@
+/**
+ * The herdr ambient env contract, single-sourced. A process running inside a
+ * herdr pane sees HERDR_ENV=1 plus the pane id and the herdr binary 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;
+  const binPath = env.HERDR_BIN_PATH;
+  if (!paneId || !binPath) return null;
+  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,7 @@
 export * from "./types";
 export * from "./markdown";
+export * from "./working-copy";
 export * from "./diff";
 export * from "./anchor";
 export * from "./feedback";
+export * from "./herdr";

package/src/markdown.test.ts

@@ -29,8 +29,11 @@ const y = 2;
 
 describe("parseBlocks", () => {
   test("parses every block kind with source line ranges", () => {
+    // Act
     const blocks = parseBlocks(SAMPLE);
-    expect(blocks.map((b) => b.kind)).toEqual([
+
+    // Assert
+    expect(blocks.map((block) => block.kind)).toEqual([
       "h1",
       "h2",
       "p",
@@ -43,7 +46,7 @@ describe("parseBlocks", () => {
       "quote",
       "hr",
     ]);
-    const code = blocks.find((b) => b.kind === "code")!;
+    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
@@ -51,50 +54,69 @@ describe("parseBlocks", () => {
   });
 
   test("multi-line paragraph keeps its text and range", () => {
+    // Arrange
     const blocks = parseBlocks(SAMPLE);
-    const p = blocks.find((b) => b.kind === "p")!;
-    expect(p.text).toBe("A paragraph that\nspans two lines.");
-    expect(p.lineEnd - p.lineStart).toBe(1);
+    const paragraph = blocks.find((block) => block.kind === "p")!;
+
+    // Assert
+    expect(paragraph.text).toBe("A paragraph that\nspans two lines.");
+    expect(paragraph.lineEnd - paragraph.lineStart).toBe(1);
   });
 
   test("line ranges index into the source", () => {
+    // Arrange
     const lines = SAMPLE.split("\n");
-    for (const b of parseBlocks(SAMPLE)) {
-      if (b.kind === "code") {
-        expect(lines[b.lineStart]!.startsWith("```")).toBe(true);
-      } else if (b.kind === "h2") {
-        expect(lines[b.lineStart]!.startsWith("## ")).toBe(true);
+
+    // Assert
+    for (const block of parseBlocks(SAMPLE)) {
+      if (block.kind === "code") {
+        expect(lines[block.lineStart]!.startsWith("```")).toBe(true);
+      } else if (block.kind === "h2") {
+        expect(lines[block.lineStart]!.startsWith("## ")).toBe(true);
       }
     }
   });
 
   test("round-trips through blockToMd", () => {
+    // Arrange
     const blocks = parseBlocks(SAMPLE);
-    let oli = 0;
+    let orderedItemCount = 0;
     const rebuilt = blocks
-      .map((b) => {
-        oli = b.kind === "oli" ? oli + 1 : 0;
-        return blockToMd(b, oli || 1);
+      .map((block) => {
+        orderedItemCount = block.kind === "oli" ? orderedItemCount + 1 : 0;
+        return blockToMd(block, orderedItemCount || 1);
       })
       .join("\n\n");
+
+    // Act
     // re-parsing the rebuild yields the same kinds and texts
     const again = parseBlocks(rebuilt);
-    expect(again.map((b) => [b.kind, b.text])).toEqual(blocks.map((b) => [b.kind, b.text]));
+
+    // Assert
+    expect(again.map((block) => [block.kind, block.text])).toEqual(blocks.map((block) => [block.kind, block.text]));
   });
 
   test("unknown constructs degrade to paragraphs, no content lost", () => {
+    // Arrange
     const md = "| a | b |\n|---|---|\n| 1 | 2 |";
+
+    // Act
     const blocks = parseBlocks(md);
-    expect(blocks.map((b) => b.text).join("\n")).toContain("| a | b |");
+
+    // Assert
+    expect(blocks.map((block) => block.text).join("\n")).toContain("| a | b |");
   });
 });
 
 describe("sectionOf", () => {
   test("returns the nearest preceding heading", () => {
+    // Arrange
     const blocks = parseBlocks(SAMPLE);
-    const oliIdx = blocks.findIndex((b) => b.kind === "oli");
-    expect(sectionOf(blocks, oliIdx)).toBe("Steps");
-    const pIdx = blocks.findIndex((b) => b.kind === "p");
-    expect(sectionOf(blocks, pIdx)).toBe("Context");
+
+    // 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");
   });
 });