@cueloop/daemon 0.1.0-alpha.8 → 0.1.0-alpha.81

package/src/thread-review.test.ts

@@ -0,0 +1,394 @@
+/** The shared review core against a real DaemonServer in a temp home: workspace resolution, title derivation, open-or-revise by agentSessionId, and both awaitMessage shapes (one long-poll and the chunked loop with progress and abort). */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Thread } from "@cueloop/schema";
+import { DaemonServer } from "./server";
+import { DaemonClient } from "./client";
+import { awaitResolve, openReview, resolveWorkspace } from "./thread-review";
+
+const PLAN = "# Rollout Plan\n\nShip it in two stages.\n";
+
+let home: string;
+let server: DaemonServer;
+let client: DaemonClient;
+
+beforeEach(async () => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-review-core-"));
+  server = new DaemonServer({ home, idleExitMs: 0 });
+  server.start();
+  client = await DaemonClient.connect({ home });
+});
+afterEach(() => {
+  client.close();
+  server.stop();
+  rmSync(home, { recursive: true, force: true });
+});
+
+function sh(args: string[], cwd: string): void {
+  const gitResult = Bun.spawnSync(args, { cwd, stdout: "ignore", stderr: "ignore" });
+
+  if (gitResult.exitCode !== 0) throw new Error(`${args.join(" ")} failed`);
+}
+
+describe("resolveWorkspace", () => {
+  test("a git repo resolves to its root and branch", async () => {
+    const repo = mkdtempSync(join(tmpdir(), "cueloop-ws-"));
+
+    try {
+      // Arrange
+      sh(["git", "init", "-q", "-b", "main"], repo);
+      sh(["git", "config", "user.email", "t@t"], repo);
+      sh(["git", "config", "user.name", "t"], repo);
+      sh(["git", "commit", "-q", "--allow-empty", "-m", "init"], repo);
+
+      // Act
+      const ws = await resolveWorkspace(repo);
+
+      // Assert
+      expect(ws.branch).toBe("main");
+      // macOS tmpdirs can resolve through /private; compare the tail
+      expect(ws.repoRoot.endsWith(repo.split("/").at(-1)!)).toBe(true);
+    } finally {
+      rmSync(repo, { recursive: true, force: true });
+    }
+  });
+
+  test("outside a repo the cwd itself is the workspace, branch detached", async () => {
+    // Act
+    const ws = await resolveWorkspace(home);
+
+    // Assert
+    expect(ws).toEqual({ repoRoot: home, branch: "detached" });
+  });
+});
+
+describe("openReview", () => {
+  test("shapes the artifact: agent, derived title, cwd", async () => {
+    // Act
+    const review = await openReview(client, {
+      type: "plan",
+      content: PLAN,
+      cwd: home,
+      agent: "test-agent",
+    });
+
+    // Assert
+    const session = review.session;
+
+    expect(session.status).toBe("pending");
+    expect(session.artifact.type).toBe("plan");
+    expect(session.artifact.meta.agent).toBe("test-agent");
+    expect(session.artifact.meta.title).toBe("Rollout Plan");
+    expect(session.artifact.meta.cwd).toBe(home);
+    expect(session.workspace).toEqual({ repoRoot: home, branch: "detached" });
+  });
+
+  test("an explicit title wins; diffs never derive one from content", async () => {
+    // Act
+    const titled = await openReview(client, {
+      type: "plan",
+      content: PLAN,
+      cwd: home,
+      title: "Custom",
+    });
+
+    // Assert
+    expect(titled.session.artifact.meta.title).toBe("Custom");
+
+    // Act
+    const diff = await openReview(client, {
+      type: "diff",
+      content: "# not a heading\n",
+      cwd: home,
+    });
+
+    // Assert
+    expect(diff.session.artifact.meta.title).toBeUndefined();
+  });
+
+  test("a pre-resolved workspace skips git resolution", async () => {
+    // Arrange
+    const ws = { repoRoot: "/elsewhere", branch: "feature" };
+
+    // Act
+    const review = await openReview(client, {
+      type: "diff",
+      content: "d",
+      cwd: home,
+      workspace: ws,
+    });
+
+    // Assert
+    expect(review.session.workspace).toEqual(ws);
+  });
+
+  test("the same agentSessionId revises instead of opening a new session", async () => {
+    // Arrange
+    const first = await openReview(client, {
+      type: "plan",
+      content: PLAN,
+      cwd: home,
+      agentSessionId: "agent-1",
+    });
+
+    // Act
+    const second = await openReview(client, {
+      type: "plan",
+      content: PLAN + "\nStage three.\n",
+      cwd: home,
+      agentSessionId: "agent-1",
+    });
+
+    // Assert
+    expect(second.id).toBe(first.id);
+    expect(second.session.revisions.length).toBe(2);
+    expect(second.session.status).toBe("pending");
+
+    // Act
+    const other = await openReview(client, {
+      type: "plan",
+      content: PLAN,
+      cwd: home,
+      agentSessionId: "agent-2",
+    });
+
+    // Assert
+    expect(other.id).not.toBe(first.id);
+  });
+
+  test("the same agentSessionId with a different type opens a new session, never a type mismatch", async () => {
+    // Arrange - the agent session's plan review is open
+    const plan = await openReview(client, {
+      type: "plan",
+      content: PLAN,
+      cwd: home,
+      agentSessionId: "agent-cross",
+    });
+
+    // Act - the same agent session now submits a reply for review
+    const reply = await openReview(client, {
+      type: "reply",
+      content: "# Findings\n\nThe cache is fine.\n",
+      cwd: home,
+      agentSessionId: "agent-cross",
+    });
+
+    // Assert - a fresh reply session; the plan session keeps its type and history
+    expect(reply.id).not.toBe(plan.id);
+    expect(reply.session.artifact.type).toBe("reply");
+    expect(reply.session.revisions.length).toBe(1);
+    expect((await client.sessionGet(plan.id)).artifact.type).toBe("plan");
+  });
+
+  test("per-file notes land as note annotations anchored at the file path", async () => {
+    // Act
+    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." },
+      ],
+    });
+
+    // Assert
+    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("awaitMessage: one long-poll (the hook shape)", () => {
+  test("times out to pending; a later wait collects the stored message", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+
+    // Assert
+    expect(await review.awaitMessage({ timeoutMs: 50 })).toBe("pending");
+
+    // Act
+    await client.sessionSendMessage(review.id, "approved", "Fine.");
+    const message = await review.awaitMessage({ timeoutMs: 1_000 });
+
+    // Assert
+    expect(message).not.toBe("pending");
+    if (message === "pending") throw new Error("unreachable");
+    expect(message.allow).toBe(true);
+    expect(message.message.body).toContain("Fine.");
+    expect(message.session.message!.outcome).toBe("approved");
+  });
+
+  test("changes_requested maps to allow=false with feedback.md attached", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    const waiting = review.awaitMessage({ timeoutMs: 5_000 });
+
+    // Act
+    await client.sessionSendMessage(review.id, "changes_requested", "One stage only.");
+    const message = await waiting;
+
+    // Assert
+    if (message === "pending") throw new Error("expected a message");
+    expect(message.allow).toBe(false);
+    expect(message.message.body).toContain("# Review: changes requested");
+    expect(message.message.body).toContain("One stage only.");
+  });
+});
+
+describe("awaitMessage: chunked loop (the pi shape)", () => {
+  test("onProgress sees fresh sessions between chunks; the message ends the loop", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    const seen: Thread[] = [];
+    const waiting = review.awaitMessage({
+      timeoutMs: Infinity,
+      pollMs: 100,
+      onProgress: (progress) => seen.push(progress),
+    });
+
+    // Act
+    await client.sessionAnnotate(review.id, {
+      id: "a1",
+      kind: "comment",
+      anchor: { quote: "two stages", prefix: "in ", suffix: "." },
+      body: "Name them.",
+    });
+
+    // Assert
+    // give the loop a chunk to observe the annotation before resolving
+    for (let i = 0; i < 100 && !seen.some((snapshot) => snapshot.annotations.length === 1); i++)
+      await Bun.sleep(20);
+    expect(seen.some((snapshot) => snapshot.annotations.length === 1)).toBe(true);
+
+    // Act
+    await client.sessionSendMessage(review.id, "changes_requested", "Too vague.");
+    const message = await waiting;
+
+    // Assert
+    if (message === "pending") throw new Error("expected a message");
+    expect(message.allow).toBe(false);
+    expect(message.session.annotations.length).toBe(1);
+  }, 15_000);
+
+  test("abort surfaces as pending and leaves the session collectable", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    const controller = new AbortController();
+    const waiting = review.awaitMessage({
+      timeoutMs: Infinity,
+      pollMs: 100,
+      signal: controller.signal,
+    });
+
+    // Act
+    controller.abort();
+
+    // Assert
+    expect(await waiting).toBe("pending");
+    expect((await client.sessionGet(review.id)).status).toBe("pending");
+  });
+
+  test("a finite budget runs out to pending", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+
+    // Assert
+    expect(await review.awaitMessage({ timeoutMs: 120, pollMs: 50 })).toBe("pending");
+  });
+});
+
+describe("awaitResolve: the adapter wake seam (session id only)", () => {
+  test("resolves to the outcome when the message lands during the wait", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    const waiting = awaitResolve(client, review.id, { pollMs: 100 });
+
+    // Act
+    await client.sessionSendMessage(review.id, "approved", "Ship it.");
+    const message = await waiting;
+
+    // Assert
+    expect(message).not.toBeNull();
+    expect(message!.allow).toBe(true);
+    expect(message!.message.body).toContain("Ship it.");
+    expect(message!.session.message!.outcome).toBe("approved");
+  });
+
+  test("returns the stored message immediately when the session already resolved", async () => {
+    // Arrange - a detached waiter that only attaches after the human decided
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+
+    await client.sessionSendMessage(review.id, "changes_requested", "One stage only.");
+
+    // Act
+    const message = await awaitResolve(client, review.id);
+
+    // Assert
+    expect(message).not.toBeNull();
+    expect(message!.allow).toBe(false);
+    expect(message!.message.body).toContain("One stage only.");
+  });
+
+  test("returns null when the signal aborts first", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    const controller = new AbortController();
+    const waiting = awaitResolve(client, review.id, { pollMs: 100, signal: controller.signal });
+
+    // Act
+    controller.abort();
+
+    // Assert
+    expect(await waiting).toBeNull();
+    expect((await client.sessionGet(review.id)).status).toBe("pending");
+  });
+});
+
+describe("awaitResolve: the held wait keeps the daemon alive", () => {
+  test("a pending session does not idle-exit while a waiter is parked, then the message lands", async () => {
+    // Arrange - a daemon with an aggressive idle timer and its own home
+    const idleHome = mkdtempSync(join(tmpdir(), "cueloop-idle-"));
+    let idleExits = 0;
+    const idleServer = new DaemonServer({
+      home: idleHome,
+      idleExitMs: 30,
+      onIdleExit: () => idleExits++,
+    });
+
+    idleServer.start();
+    const waiterClient = await DaemonClient.connect({ home: idleHome });
+
+    try {
+      const review = await openReview(waiterClient, { type: "plan", content: PLAN, cwd: idleHome });
+      const waiting = awaitResolve(waiterClient, review.id, { pollMs: 40 });
+
+      // Act - wait well past the idle window while the review is still pending
+      await Bun.sleep(120);
+
+      // Assert - the parked waiter and the pending session both keep it alive
+      expect(idleExits).toBe(0);
+      expect((await waiterClient.ping()).pid).toBe(process.pid);
+
+      // Act - the human returns a message; the parked wait collects it
+      const resolver = await DaemonClient.connect({ home: idleHome });
+
+      await resolver.sessionSendMessage(review.id, "approved", "Good to go.");
+      resolver.close();
+      const message = await waiting;
+
+      // Assert
+      expect(message!.allow).toBe(true);
+    } finally {
+      waiterClient.close();
+      idleServer.stop();
+      rmSync(idleHome, { recursive: true, force: true });
+    }
+  }, 15_000);
+});

package/src/thread-review.ts

@@ -0,0 +1,314 @@
+import {
+  isMarkdownArtifact,
+  newAnnotationId,
+  type Annotation,
+  type Artifact,
+  type ArtifactType,
+  type DiffFileContents,
+  type Thread,
+  type WorkspaceKey,
+  type WorkflowKind,
+} from "@cueloop/schema";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { messageResponse } from "./api";
+import { ABORTED, pollUntilResolved, raceAbort } from "./interruptible-wait";
+
+// Adapters and CLI primitives reach the message mapping through this module too,
+// so a session obtained outside a ReviewHandle maps the same way.
+export { messageResponse };
+
+async function git(args: string[], cwd: string): Promise<string | null> {
+  try {
+    const { stdout } = await promisify(execFile)("git", args, { cwd });
+
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+/** The oldest root commit reachable from HEAD; the project key that survives moving or re-cloning the repo. */
+function earliestRootCommit(revList: string | null): string | undefined {
+  if (!revList) return undefined;
+  const roots = revList.split("\n").filter((line) => line.length > 0);
+
+  // --date-order lists newest first, so the last root is the earliest
+  return roots.at(-1);
+}
+
+/** Workspace key resolution: repo root, branch, and the project identity (root commit + remote) from the cwd. */
+export async function resolveWorkspace(cwd = process.cwd()): Promise<WorkspaceKey> {
+  const repoRoot = (await git(["rev-parse", "--show-toplevel"], cwd)) ?? cwd;
+  const branch = (await git(["rev-parse", "--abbrev-ref", "HEAD"], cwd)) ?? "detached";
+  // a shallow clone's oldest commit is the graft boundary, not the true root, so
+  // it would key a different project than a full clone - leave it unset instead
+  const shallow = (await git(["rev-parse", "--is-shallow-repository"], cwd)) === "true";
+  const rootCommit = shallow
+    ? undefined
+    : earliestRootCommit(await git(["rev-list", "--max-parents=0", "--date-order", "HEAD"], cwd));
+  const remote = await git(["remote", "get-url", "origin"], cwd);
+
+  const workspace: WorkspaceKey = { repoRoot, branch };
+  // a repo with no commits (or a shallow clone) has no reliable root, so the thread stays standalone
+  if (rootCommit) workspace.rootCommit = rootCommit;
+  if (remote) workspace.remote = remote;
+
+  return workspace;
+}
+
+function firstHeading(markdown: string): string | undefined {
+  const headingMatch = markdown.match(/^#\s+(.+)$/m);
+
+  return headingMatch?.[1]?.trim();
+}
+
+export interface OpenReviewOptions {
+  type: ArtifactType;
+  /** Workflow identity keeps plan/refine and diff/review Threads separate. */
+  workflow?: WorkflowKind;
+  content: string;
+  /** Workspace resolution root and meta.cwd; defaults to process.cwd(). */
+  cwd?: string;
+  /** Pre-resolved workspace key; skips git resolution when the caller already has it. */
+  workspace?: WorkspaceKey;
+  agent?: string;
+  /** When set, a resubmit from the same agent session becomes a revision, not a new session. */
+  agentSessionId?: string;
+  planPath?: string;
+  prototypePath?: string;
+  pr?: string;
+  herdrPane?: string;
+  /**
+   * Full file contents per changed file for a working-tree diff, carried onto
+   * the artifact so hunk curation produces an exactly applyable patch.
+   */
+  files?: DiffFileContents[];
+  /** Defaults to a markdown artifact's first heading (plan, reply); 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;
+}
+
+/** The transport-neutral daemon operations used by the shared review lifecycle. */
+export interface ThreadSessionClient {
+  sessionList(filter?: { status?: "pending" | "resolved" }): Promise<Thread[]>;
+  sessionCreate(workspace: WorkspaceKey, artifact: Artifact): Promise<Thread>;
+  sessionSubmitRevision(
+    id: string,
+    content: string,
+    addressedAnnotationIds?: string[],
+    files?: DiffFileContents[],
+  ): Promise<Thread>;
+  sessionAnnotate(
+    id: string,
+    annotation: Omit<Annotation, "createdAt">,
+    authorName?: string,
+  ): Promise<Thread>;
+  sessionGet(id: string): Promise<Thread>;
+  sessionWait(id: string, timeoutMs: number): Promise<Thread | null>;
+}
+
+/** Anchor a note at its file: quote = the path, no context selectors. */
+async function attachNotes(
+  client: ThreadSessionClient,
+  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 AwaitMessageOptions {
+  /** Total wait budget; Infinity keeps polling until resolved or aborted. */
+  timeoutMs: number;
+  /** Chunk length for the poll loop; between chunks the session is re-read for progress. */
+  pollMs?: number;
+  /** Called with the fresh session after each chunk that is still pending. */
+  onProgress?: (session: Thread) => void;
+  signal?: AbortSignal;
+}
+
+/** A resolved review mapped onto the agent contract, plus the full session. */
+export interface MessageResult {
+  allow: boolean;
+  message: import("@cueloop/schema").Message;
+  session: Thread;
+}
+
+export class ReviewHandle {
+  constructor(
+    private readonly client: Pick<ThreadSessionClient, "sessionWait" | "sessionGet">,
+    readonly session: Thread,
+  ) {}
+
+  get id(): string {
+    return this.session.id;
+  }
+
+  /**
+   * Block on the message. "pending" means the budget ran out or the signal
+   * aborted - the session stays open and the message is collectable later
+   * (messages outlive waits). With only timeoutMs this is one long-poll;
+   * pollMs/onProgress/signal switch to the chunked loop.
+   */
+  async awaitMessage(options: AwaitMessageOptions): Promise<MessageResult | "pending"> {
+    const { timeoutMs, pollMs, onProgress, signal } = options;
+
+    if (pollMs === undefined && onProgress === undefined && signal === undefined) {
+      const resolved = await this.client.sessionWait(this.session.id, timeoutMs);
+
+      return resolved === null ? "pending" : outcome(resolved);
+    }
+    const chunkMs = pollMs ?? 10_000;
+    const deadline = Number.isFinite(timeoutMs) ? Date.now() + timeoutMs : undefined;
+
+    for (;;) {
+      const budget = deadline === undefined ? chunkMs : Math.min(chunkMs, deadline - Date.now());
+
+      if (budget <= 0 || signal?.aborted) return "pending";
+      const resolved = await raceAbort(this.client.sessionWait(this.session.id, budget), signal);
+
+      if (resolved === ABORTED) return "pending";
+
+      if (resolved !== null) return outcome(resolved);
+      // Still pending after this chunk: re-read to surface reviewer progress.
+      const current = await raceAbort(this.client.sessionGet(this.session.id), signal);
+
+      if (current === ABORTED) return "pending";
+
+      onProgress?.(current);
+    }
+  }
+}
+
+function outcome(session: Thread): MessageResult {
+  return { ...messageResponse(session), session };
+}
+
+export interface AwaitResolveOptions {
+  /** Long-poll chunk length; the wait re-arms each chunk until resolved or aborted. Default 30s. */
+  pollMs?: number;
+  /** Abort the wait (the harness session shut down); resolves to null. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Park until a thread resolves, then return the message outcome; null
+ * when the signal aborts first. Where ReviewHandle.awaitMessage needs the handle
+ * that opened the review, this needs only a session id - so a background waiter
+ * that woke on a session it did not open (a detached Claude Code / Codex waiter,
+ * or pi's session_start listener) can collect the same message. This is the
+ * wake seam every non-blocking adapter builds on. Loops the daemon long-poll, so
+ * a message that lands between chunks is never missed and a session already
+ * resolved returns on the first chunk. The held connection also keeps the daemon
+ * off its idle-exit path for the whole wait.
+ */
+export async function awaitResolve(
+  client: Pick<ThreadSessionClient, "sessionWait">,
+  sessionId: string,
+  options: AwaitResolveOptions = {},
+): Promise<MessageResult | null> {
+  const chunkMs = options.pollMs ?? 30_000;
+  const resolved = await pollUntilResolved(
+    () => client.sessionWait(sessionId, chunkMs),
+    options.signal,
+  );
+
+  return resolved === null ? null : outcome(resolved);
+}
+
+/** Find the Thread already submitted by this agent in the same workspace and primitive. */
+export async function findExistingReview(
+  client: ThreadSessionClient,
+  options: OpenReviewOptions,
+): Promise<Thread | undefined> {
+  const cwd = options.cwd ?? process.cwd();
+  const workspace = options.workspace ?? (await resolveWorkspace(cwd));
+
+  if (options.agentSessionId === undefined) return undefined;
+
+  return (await client.sessionList()).find(
+    (candidate) =>
+      candidate.artifact.meta.agentSessionId === options.agentSessionId &&
+      candidate.artifact.meta.agent === options.agent &&
+      candidate.artifact.type === options.type &&
+      (candidate.artifact.meta.workflow ??
+        (candidate.artifact.meta.pr ? "review" : candidate.artifact.type)) ===
+        (options.workflow ?? (options.pr ? "review" : options.type)) &&
+      candidate.artifact.meta.pr === options.pr &&
+      candidate.workspace.repoRoot === workspace.repoRoot &&
+      candidate.workspace.branch === workspace.branch,
+  );
+}
+
+/** Open a thread (or revise the agent session's existing one) and hand back the wait surface. */
+export async function openReview(
+  client: ThreadSessionClient,
+  options: OpenReviewOptions,
+): Promise<ReviewHandle> {
+  const cwd = options.cwd ?? process.cwd();
+  const workspace = options.workspace ?? (await resolveWorkspace(cwd));
+  const existing = await findExistingReview(client, options);
+
+  if (existing !== undefined) {
+    // PR diffs have no full file contents. An absent local-diff capture clears
+    // old curatable files, while a PR revision must keep curation disabled.
+    const revisionFiles = options.type !== "diff" || options.pr ? undefined : (options.files ?? []);
+    let revised = await client.sessionSubmitRevision(
+      existing.id,
+      options.content,
+      [],
+      revisionFiles,
+    );
+
+    if (options.notes?.length) {
+      await attachNotes(client, revised.id, options.notes);
+      revised = await client.sessionGet(revised.id);
+    }
+
+    return new ReviewHandle(client, revised);
+  }
+  let session = await client.sessionCreate(workspace, {
+    type: options.type,
+    content: options.content,
+    files: options.files,
+    meta: {
+      workflow: options.workflow,
+      agent: options.agent,
+      agentSessionId: options.agentSessionId,
+      planPath: options.planPath,
+      prototypePath: options.prototypePath,
+      pr: options.pr,
+      herdrPane: options.herdrPane,
+      title:
+        options.title ??
+        (isMarkdownArtifact(options.type) ? firstHeading(options.content) : undefined),
+      cwd,
+    },
+  });
+
+  if (options.notes?.length) {
+    await attachNotes(client, session.id, options.notes);
+    session = await client.sessionGet(session.id);
+  }
+
+  return new ReviewHandle(client, session);
+}