@cueloop/daemon 0.1.0-alpha.15 → 0.1.0-alpha.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.16",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -9,7 +9,7 @@
     "./review": "./src/review.ts"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.15",
+    "@cueloop/schema": "0.1.0-alpha.16",
     "valibot": "^1.4.2"
   },
   "publishConfig": {

package/src/api.test.ts

@@ -84,6 +84,20 @@ describe("session lifecycle", () => {
     expect(core.sessionGet(s.id).workingCopy).toBeUndefined();
   });
 
+  test("viewed paths merge, dedupe, clear on empty, and survive a daemon restart", () => {
+    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionSetViewed(s.id, ["src/a.ts", "src/b.ts", "src/a.ts"]);
+    expect(core.sessionGet(s.id).viewedPaths).toEqual(["src/a.ts", "src/b.ts"]);
+    // merge-additive: a stale client sending only its own new mark loses nothing
+    core.sessionSetViewed(s.id, ["src/c.ts"]);
+    expect(core.sessionGet(s.id).viewedPaths).toEqual(["src/a.ts", "src/b.ts", "src/c.ts"]);
+    // a resumed review reads its progress back after a daemon restart
+    const reborn = new DaemonCore(home);
+    expect(reborn.sessionGet(s.id).viewedPaths).toEqual(["src/a.ts", "src/b.ts", "src/c.ts"]);
+    core.sessionSetViewed(s.id, []);
+    expect(core.sessionGet(s.id).viewedPaths).toBeUndefined();
+  });
+
   test("revision reopens the session and resets working copy + verdict", () => {
     const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
     core.sessionSetWorkingCopy(s.id, PLAN.content + "\nedit");

package/src/api.ts

@@ -150,6 +150,26 @@ export class DaemonCore {
     return s;
   }
 
+  /**
+   * The guided walk's viewed marks. The full list replaces the stored one
+   * (last write wins - one reviewer walks at a time); an empty list clears
+   * the field so untouched records stay lean. Duplicates collapse here so
+   * the record never accumulates repeats from racing clients.
+   */
+  /**
+   * Merge-additive: walking only ever adds marks, so concurrent or stale
+   * clients converge instead of overwriting each other. An empty array is the
+   * explicit reset.
+   */
+  sessionSetViewed(id: string, viewedPaths: string[]): ReviewSession {
+    const s = this.mutable(id);
+    if (viewedPaths.length === 0) delete s.viewedPaths;
+    else s.viewedPaths = [...new Set([...(s.viewedPaths ?? []), ...viewedPaths])];
+    this.store.upsert(s);
+    this.emit("session.updated", id);
+    return s;
+  }
+
   sessionResolve(id: string, verdictKind: VerdictKind, summary: string): ReviewSession {
     const s = this.mutable(id);
     const verdict: Verdict = {

package/src/client.ts

@@ -159,6 +159,9 @@ export class DaemonClient {
   sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<ReviewSession> {
     return this.request("session.setWorkingCopy", { id, workingCopy });
   }
+  sessionSetViewed(id: string, viewedPaths: string[]): Promise<ReviewSession> {
+    return this.request("session.setViewed", { id, viewedPaths });
+  }
   sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession> {
     return this.request("session.resolve", { id, verdictKind, summary });
   }

package/src/review.test.ts

@@ -99,6 +99,23 @@ describe("openReview", () => {
     const other = await openReview(client, { type: "plan", content: PLAN, cwd: home, agentSessionId: "agent-2" });
     expect(other.id).not.toBe(first.id);
   });
+
+  test("per-file notes land as note annotations anchored at the file path", async () => {
+    const review = await openReview(client, {
+      type: "diff",
+      content: "d",
+      cwd: home,
+      notes: [
+        { path: "src/a.ts", body: "Renames b and adds c." },
+        { path: "src/b.ts", body: "Swaps the line." },
+      ],
+    });
+    const notes = review.session.annotations;
+    expect(notes.length).toBe(2);
+    expect(notes.every((annotation) => annotation.kind === "note")).toBe(true);
+    expect(notes.map((annotation) => annotation.anchor.quote)).toEqual(["src/a.ts", "src/b.ts"]);
+    expect(notes[0]!.body).toBe("Renames b and adds c.");
+  });
 });
 
 describe("awaitVerdict: one long-poll (the hook shape)", () => {

package/src/review.ts

@@ -7,7 +7,7 @@
  * serializing the decision in its host's contract.
  */
 
-import type { ArtifactType, ReviewSession, WorkspaceKey } from "@cueloop/schema";
+import { newAnnotationId, type ArtifactType, type ReviewSession, type WorkspaceKey } from "@cueloop/schema";
 import { verdictResponse } from "./api";
 import type { DaemonClient } from "./client";
 
@@ -53,6 +53,31 @@ export interface OpenReviewOptions {
   herdrPane?: string;
   /** Defaults to the plan's first markdown heading; diffs get no derived title. */
   title?: string;
+  /**
+   * Per-file agent notes for diff sessions: the submitting agent's own
+   * explanation of each file's change, in dead prose. Stored as annotations
+   * with kind "note" anchored at the file path, so they render as regular
+   * rail cards and feed the guided walk's agent-note block.
+   */
+  notes?: ReviewNote[];
+}
+
+/** The note contract: one note per changed file, anchored by the file path. */
+export interface ReviewNote {
+  path: string;
+  body: string;
+}
+
+/** Anchor a note at its file: quote = the path, no context selectors. */
+async function attachNotes(client: DaemonClient, sessionId: string, notes: ReviewNote[]): Promise<void> {
+  for (const note of notes) {
+    await client.sessionAnnotate(sessionId, {
+      id: newAnnotationId(),
+      kind: "note",
+      anchor: { quote: note.path, prefix: "", suffix: "" },
+      body: note.body,
+    });
+  }
 }
 
 export interface AwaitVerdictOptions {
@@ -154,10 +179,15 @@ export async function openReview(client: DaemonClient, opts: OpenReviewOptions):
       (s) => s.artifact.meta.agentSessionId === opts.agentSessionId,
     );
     if (existing !== undefined) {
-      return new ReviewHandle(client, await client.sessionSubmitRevision(existing.id, opts.content));
+      let revised = await client.sessionSubmitRevision(existing.id, opts.content);
+      if (opts.notes?.length) {
+        await attachNotes(client, revised.id, opts.notes);
+        revised = await client.sessionGet(revised.id);
+      }
+      return new ReviewHandle(client, revised);
     }
   }
-  const session = await client.sessionCreate(workspace, {
+  let session = await client.sessionCreate(workspace, {
     type: opts.type,
     content: opts.content,
     meta: {
@@ -170,5 +200,9 @@ export async function openReview(client: DaemonClient, opts: OpenReviewOptions):
       cwd,
     },
   });
+  if (opts.notes?.length) {
+    await attachNotes(client, session.id, opts.notes);
+    session = await client.sessionGet(session.id);
+  }
   return new ReviewHandle(client, session);
 }

package/src/server.ts

@@ -241,6 +241,10 @@ export class DaemonServer {
         const p = parseParams("session.setWorkingCopy", req.params);
         return core.sessionSetWorkingCopy(p.id, p.workingCopy);
       }
+      case "session.setViewed": {
+        const p = parseParams("session.setViewed", req.params);
+        return core.sessionSetViewed(p.id, p.viewedPaths);
+      }
       case "session.resolve": {
         const p = parseParams("session.resolve", req.params);
         return core.sessionResolve(p.id, p.verdictKind, p.summary);

package/src/validate.test.ts

@@ -89,6 +89,16 @@ describe("parseParams", () => {
     expect(p.annotation.anchor.prefix).toBe("");
   });
 
+  test("setViewed takes a full path list and rejects non-string entries", () => {
+    expect(parseParams("session.setViewed", { id: "s", viewedPaths: ["src/a.ts", "src/b.ts"] }).viewedPaths).toEqual([
+      "src/a.ts",
+      "src/b.ts",
+    ]);
+    expect(parseParams("session.setViewed", { id: "s", viewedPaths: [] }).viewedPaths).toEqual([]);
+    expect(() => parseParams("session.setViewed", { id: "s", viewedPaths: [1] })).toThrow(/viewedPaths/);
+    expect(() => parseParams("session.setViewed", { id: "s" })).toThrow(/viewedPaths/);
+  });
+
   test("null params are treated as empty", () => {
     expect(parseParams("daemon.ping", null)).toEqual({});
   });
@@ -163,6 +173,7 @@ describe("wire pins", () => {
     revisions: [fullRevision],
     annotations: [fullAnnotation],
     workingCopy: "# P edited",
+    viewedPaths: ["src/a.ts"],
     verdict: fullVerdict,
     status: "pending",
     createdAt: "now",

package/src/validate.ts

@@ -95,6 +95,7 @@ export const Params = {
   "session.annotate": v.object({ id: SessionId, annotation: AnnotationSchema }),
   "session.removeAnnotation": v.object({ id: SessionId, annotationId: NonEmpty }),
   "session.setWorkingCopy": v.object({ id: SessionId, workingCopy: v.optional(v.string()) }),
+  "session.setViewed": v.object({ id: SessionId, viewedPaths: v.array(v.string()) }),
   "session.resolve": v.object({
     id: SessionId,
     verdictKind: v.picklist(["comment", "approve", "request_changes"]),
@@ -145,6 +146,7 @@ export const SessionRecordSchema = v.object({
   revisions: v.array(RevisionSchema),
   annotations: v.array(v.object({ ...AnnotationSchema.entries, createdAt: v.string() } satisfies EntriesOf<Annotation>)),
   workingCopy: v.optional(v.string()),
+  viewedPaths: v.optional(v.array(v.string())),
   verdict: v.nullable(VerdictSchema),
   status: v.picklist(["pending", "resolved"]),
   createdAt: v.string(),