@cueloop/schema 0.1.0-alpha.68 → 0.1.0-alpha.69

package/package.json

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

package/src/feedback.test.ts

@@ -329,3 +329,64 @@ describe("renderFeedback", () => {
     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(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");
+  });
+});

package/src/feedback.ts

@@ -6,6 +6,7 @@
  */
 
 import {
+  annotationTarget,
   isAddressed,
   isAgentNote,
   type Annotation,
@@ -13,7 +14,7 @@ import {
   type ReviewSession,
   type VerdictKind,
 } from "./types";
-import { parseBlocks, sectionOf } from "./markdown";
+import { parseBlocks, sectionOf, type Block } from "./markdown";
 import { resolveAnchor } from "./anchor";
 import { unifiedDiffText } from "./diff";
 
@@ -32,10 +33,20 @@ export interface FeedbackInput {
   artifactPath?: string;
   /** Session id, so the document can teach the addressed-ids resubmit call. */
   sessionId?: string;
+  /** cueloop quick-action name -> body; a `/name` reference in a comment expands to it for the agent. */
+  actionBodies?: Record<string, string>;
 }
 
 const quoteLines = (text: string) => "> " + text.replace(/\n/g, "\n> ");
 
+function expandActionRefs(body: string, actionBodies: Record<string, string> | undefined): string {
+  if (!actionBodies) return body;
+
+  return body.replace(/(^|\s)\/([A-Za-z0-9-]+)/g, (whole, lead: string, name: string) =>
+    actionBodies[name] !== undefined ? `${lead}${actionBodies[name]}` : whole,
+  );
+}
+
 export function renderFeedback(input: FeedbackInput): string {
   // The document the agent revises: a reply's feedback references reply.md so
   // the resubmit instruction never points a reply review at plan.md.
@@ -118,44 +129,16 @@ export function renderFeedback(input: FeedbackInput): string {
   }
 
   if (annotations.length) {
-    lines.push(`## Annotations (${annotations.length})`);
-    lines.push("");
     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.`,
+      ...annotationSectionLines(
+        annotations,
+        blocks,
+        path,
+        isPrototype,
+        repliesTo,
+        input.actionBodies,
+      ),
     );
-    lines.push("");
-    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("");
-      const replies = repliesTo(annotation);
-
-      if (replies.length > 0) {
-        lines.push("Replies:");
-        lines.push("");
-        for (const reply of replies) lines.push(`- ${reply.body.replace(/\n/g, "\n  ")}`);
-        lines.push("");
-      }
-      lines.push(`annotation id: \`${annotation.id}\``);
-      lines.push("");
-    });
     if (input.sessionId) {
       lines.push("## Reporting what you addressed");
       lines.push("");
@@ -179,10 +162,94 @@ export function renderFeedback(input: FeedbackInput): string {
   return lines.join("\n");
 }
 
+/**
+ * The annotation body of the feedback, grouped by the surface each note was made on: the reviewed
+ * artifact first (resolved against its blocks for a section locator), then one section per file, so a
+ * note left on a file comes back beside that file rather than mixed into the plan's list.
+ */
+function annotationSectionLines(
+  annotations: Annotation[],
+  blocks: Block[],
+  path: string,
+  isPrototype: boolean,
+  repliesTo: (root: Annotation) => Annotation[],
+  actionBodies: Record<string, string> | undefined,
+): string[] {
+  const lines: string[] = [];
+  const artifactNotes = annotations.filter(
+    (annotation) => annotationTarget(annotation).kind === "artifact",
+  );
+  const fileGroups = new Map<string, Annotation[]>();
+
+  for (const annotation of annotations) {
+    const target = annotationTarget(annotation);
+
+    if (target.kind !== "file") continue;
+    const group = fileGroups.get(target.path) ?? [];
+
+    group.push(annotation);
+    fileGroups.set(target.path, group);
+  }
+
+  const pushNote = (annotation: Annotation, index: number, location: string, orphan: string) => {
+    lines.push(`### ${index + 1}. ${capitalize(annotation.kind)}${location}${orphan}`);
+    lines.push("");
+    lines.push(quoteLines(annotation.anchor.quote));
+    lines.push("");
+    lines.push(expandActionRefs(annotation.body, actionBodies));
+    lines.push("");
+    const replies = repliesTo(annotation);
+
+    if (replies.length > 0) {
+      lines.push("Replies:");
+      lines.push("");
+      for (const reply of replies)
+        lines.push(`- ${expandActionRefs(reply.body, actionBodies).replace(/\n/g, "\n  ")}`);
+      lines.push("");
+    }
+    lines.push(`annotation id: \`${annotation.id}\``);
+    lines.push("");
+  };
+
+  if (artifactNotes.length) {
+    lines.push(`## Annotations (${artifactNotes.length})`);
+    lines.push("");
+    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("");
+    artifactNotes.forEach((annotation, index) => {
+      // a prototype selector anchor never resolves or orphans against blocks; a quote anchor does
+      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 orphan =
+        !selector && resolved === null
+          ? " [orphaned anchor: the quoted text is no longer present]"
+          : "";
+
+      pushNote(annotation, index, location, orphan);
+    });
+  }
+  for (const [filePath, notes] of fileGroups) {
+    lines.push(`## ${filePath} (${notes.length})`);
+    lines.push("");
+    lines.push(`Address every item. Locate each one in ${filePath} by its quoted text.`);
+    lines.push("");
+    notes.forEach((annotation, index) => pushNote(annotation, index, "", ""));
+  }
+
+  return lines;
+}
+
 export function feedbackForSession(
   session: ReviewSession,
   verdictKind: VerdictKind,
   summary: string,
+  actionBodies?: Record<string, string>,
 ): string {
   return renderFeedback({
     verdictKind,
@@ -193,6 +260,7 @@ export function feedbackForSession(
     annotations: session.annotations,
     artifactPath: session.artifact.meta.prototypePath ?? session.artifact.meta.planPath,
     sessionId: session.id,
+    actionBodies,
   });
 }
 

package/src/types.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import {
+  annotationTarget,
   ARTIFACT_TYPES,
   isArtifactType,
   isMarkdownArtifact,
@@ -7,6 +8,18 @@ import {
   verdictAllows,
 } from "./types";
 
+describe("annotationTarget", () => {
+  test("an annotation with no target means the reviewed artifact", () => {
+    expect(annotationTarget({ target: undefined })).toEqual({ kind: "artifact" });
+  });
+
+  test("a stamped target is returned as-is", () => {
+    const target = { kind: "file", path: "src/x.ts", rev: "worktree" } as const;
+
+    expect(annotationTarget({ target })).toBe(target);
+  });
+});
+
 describe("ARTIFACT_TYPES", () => {
   test("names every primitive exactly once", () => {
     expect([...ARTIFACT_TYPES].sort()).toEqual(["diff", "plan", "prototype", "reply"]);
@@ -29,11 +42,11 @@ describe("verdictAllows", () => {
 });
 
 describe("isMarkdownArtifact", () => {
-  test("plan and reply are markdown; diff and prototype are not", () => {
+  test("plan, reply, and prototype are markdown; diff is not", () => {
     expect(isMarkdownArtifact("plan")).toBe(true);
     expect(isMarkdownArtifact("reply")).toBe(true);
+    expect(isMarkdownArtifact("prototype")).toBe(true);
     expect(isMarkdownArtifact("diff")).toBe(false);
-    expect(isMarkdownArtifact("prototype")).toBe(false);
   });
 });
 

package/src/types.ts

@@ -22,7 +22,8 @@ export interface WorkspaceKey {
  * 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.
+ * `diff` is a unified-diff patch; `prototype` is a component design doc (API /
+ * Composition / Callstack) in markdown, with an opt-in experimental pixel mode.
  *
  * One runtime union: every consumer that names the supported set - daemon
  * wire validation, CLI flag parsing, adapter tool schemas - derives from this
@@ -38,13 +39,15 @@ export function isArtifactType(value: string): value is ArtifactType {
 }
 
 /**
- * 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.
+ * Markdown artifacts (plan, reply, prototype) are block-parsed and quote-anchored,
+ * so they share the plan render path, first-heading title derivation, and revision
+ * drift-assist. A prototype is a component design doc (API / Composition / Callstack)
+ * by default; its opt-in experimental pixel mode is a client render override, not a
+ * different artifact. A diff (a patch) does 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";
+  return type === "plan" || type === "reply" || type === "prototype";
 }
 
 export interface ArtifactMeta {
@@ -61,6 +64,8 @@ export interface ArtifactMeta {
   /** herdr pane the submitting agent runs in - the review returns focus there. */
   herdrPane?: string;
   title?: string;
+  /** A self-initiated per-repo workbench thread (a bare launch's first comment), not an agent submission. */
+  workbench?: boolean;
 }
 
 /** Full old/new contents of one changed file, keyed by its repo-relative path. */
@@ -122,6 +127,23 @@ export interface Anchor {
 /** The annotation kind set is open; these are the built-ins. */
 export type AnnotationKind = "comment" | (string & {});
 
+/**
+ * The surface an annotation was made on. Name-only: the ref names the surface and the
+ * client loads that surface's text to resolve the quote anchor. Absent means the session's
+ * reviewed artifact, so every existing annotation keeps its meaning with no data change.
+ * A `file` target's `rev` doubles as the diff side: worktree for an added or context row,
+ * head for a deletion.
+ */
+export type AnnotationTarget =
+  | { kind: "artifact" }
+  | { kind: "file"; path: string; rev: "worktree" | "head" }
+  | { kind: "welcome" };
+
+/** The target an annotation resolves against; absent records mean the reviewed artifact. */
+export function annotationTarget(annotation: Pick<Annotation, "target">): AnnotationTarget {
+  return annotation.target ?? { kind: "artifact" };
+}
+
 /**
  * Agent-authored context, not reviewer feedback: the guided walk's per-file
  * notes (kind "note", anchored by the file path). Excluded from the feedback
@@ -136,6 +158,8 @@ export interface Annotation {
   id: string;
   kind: AnnotationKind;
   anchor: Anchor;
+  /** The surface this note was made on; absent means the session's reviewed artifact. */
+  target?: AnnotationTarget;
   /** Comment body. */
   body: string;
   /** Set by resolution when the quote can no longer be found. */