@cueloop/daemon 0.1.0-alpha.0 → 0.1.0-alpha.100

package/src/thread-review.ts

@@ -0,0 +1,382 @@
+import {
+  isMarkdownArtifact,
+  newAnnotationId,
+  type Annotation,
+  type Artifact,
+  type ArtifactType,
+  type DiffFileContents,
+  type DiffSource,
+  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";
+import { VcsSourceManager } from "./vcs-source";
+
+// 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;
+  }
+}
+
+async function jjRoot(cwd: string): Promise<string | null> {
+  try {
+    const { stdout } = await promisify(execFile)("jj", ["--ignore-working-copy", "root"], { 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 [gitRepoRoot, jjRepoRoot] = await Promise.all([
+    git(["rev-parse", "--show-toplevel"], cwd),
+    jjRoot(cwd),
+  ]);
+  const nativeJjRoot =
+    jjRepoRoot && (!gitRepoRoot || jjRepoRoot.length > gitRepoRoot.length) ? jjRepoRoot : null;
+  const repoRoot = nativeJjRoot ?? gitRepoRoot ?? cwd;
+  const [gitBranch, isShallow, rootList, gitRemote] = nativeJjRoot
+    ? [null, null, null, null]
+    : await Promise.all([
+        git(["rev-parse", "--abbrev-ref", "HEAD"], cwd),
+        git(["rev-parse", "--is-shallow-repository"], cwd),
+        git(["rev-list", "--max-parents=0", "--date-order", "HEAD"], cwd),
+        git(["remote", "get-url", "origin"], cwd),
+      ]);
+  const branch = nativeJjRoot ? "jj" : (gitBranch ?? "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 = nativeJjRoot !== null || isShallow === "true";
+  const rootCommit = shallow ? undefined : earliestRootCommit(rootList);
+  const remote = nativeJjRoot ? null : gitRemote;
+
+  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?: WorkflowKind;
+  content: string;
+  cwd?: string;
+  vcs?: string;
+  vcsChangeId?: string;
+  workspace?: WorkspaceKey;
+  agent?: string;
+  agentSessionId?: string;
+  planPath?: string;
+  prototypePath?: string;
+  pr?: string;
+  prBrief?: string;
+  prBaseSha?: string;
+  prHeadSha?: string;
+  prUrl?: string;
+  herdrPane?: string;
+  files?: DiffFileContents[];
+  title?: string;
+  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[],
+    source?: DiffSource,
+  ): 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 {
+  timeoutMs: number;
+  pollMs?: number;
+  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 {
+  pollMs?: number;
+  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;
+
+  const isJjDiff = options.type === "diff" && options.vcs === "jj";
+  const hasJjProvenance = (candidate: Thread): boolean =>
+    candidate.artifact.meta.vcs === "jj" ||
+    candidate.revisions.some((revision) => revision.source?.vcs === "jj");
+  const candidates = (await client.sessionList()).filter(
+    (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 || (isJjDiff && hasJjProvenance(candidate))),
+  );
+
+  if (options.vcsChangeId !== undefined)
+    return candidates.find(
+      (candidate) => candidate.artifact.meta.vcsChangeId === options.vcsChangeId,
+    );
+  if (isJjDiff) {
+    const jjCandidates = candidates.filter(hasJjProvenance);
+
+    // An unmatched patch has no verified change ID. Reuse the Thread only when
+    // there is exactly one possible JJ change in this agent session.
+    return jjCandidates.length === 1 ? jjCandidates[0] : undefined;
+  }
+
+  return candidates.find((candidate) => candidate.artifact.meta.vcsChangeId === undefined);
+}
+
+/** Attach VCS provenance only when the submitted patch matches a native capture. */
+async function matchingDiffCapture(
+  options: OpenReviewOptions,
+  cwd: string,
+): Promise<{ source?: DiffSource; files?: DiffFileContents[] }> {
+  if (options.type !== "diff" || options.pr || !options.content.trim()) return {};
+  try {
+    const captured = await new VcsSourceManager().capture(cwd, options.vcs);
+
+    if (captured.patch.replace(/\n+$/, "") !== options.content.replace(/\n+$/, "")) return {};
+
+    return {
+      source: {
+        vcs: captured.vcs,
+        changeId: captured.source?.changeId,
+        revisionId: captured.source?.revisionId,
+      },
+      files: captured.files,
+    };
+  } catch {
+    // A supplied patch stays reviewable even when the local source is unavailable.
+    return {};
+  }
+}
+
+/** 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 { source, files: capturedFiles } = await matchingDiffCapture(options, cwd);
+  const existing = await findExistingReview(client, {
+    ...options,
+    vcsChangeId: source?.changeId,
+  });
+
+  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 ?? capturedFiles ?? []);
+    let revised = await client.sessionSubmitRevision(
+      existing.id,
+      options.content,
+      [],
+      revisionFiles,
+      source,
+    );
+
+    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 ?? capturedFiles,
+    meta: {
+      workflow: options.workflow,
+      agent: options.agent,
+      agentSessionId: options.agentSessionId,
+      planPath: options.planPath,
+      prototypePath: options.prototypePath,
+      pr: options.pr,
+      prBrief: options.prBrief,
+      prBaseSha: options.prBaseSha,
+      prHeadSha: options.prHeadSha,
+      prUrl: options.prUrl,
+      herdrPane: options.herdrPane,
+      title:
+        options.title ??
+        (isMarkdownArtifact(options.type) ? firstHeading(options.content) : undefined),
+      cwd,
+      vcs: source?.vcs,
+      vcsChangeId: source?.changeId,
+      vcsRevisionId: source?.revisionId,
+    },
+  });
+
+  if (options.notes?.length) {
+    await attachNotes(client, session.id, options.notes);
+    session = await client.sessionGet(session.id);
+  }
+
+  return new ReviewHandle(client, session);
+}

package/src/thread-subscription.test.ts

@@ -0,0 +1,174 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DaemonServer } from "./server";
+import { DaemonClient } from "./client";
+import { subscribeThreadState, connectThreadObserver } from "./thread-subscription";
+
+import { createTestSignal } from "../../../test/helpers/test-signal";
+
+test("subscription refresh discards stale reads and disposal suppresses late callbacks", async () => {
+  const home = mkdtempSync(join(tmpdir(), "cueloop-subscription-"));
+  const server = new DaemonServer({ home, idleExitMs: 0 });
+
+  server.start();
+  const client = await DaemonClient.connect({ home });
+  const firstRead = createTestSignal<void>();
+  const releaseFirst = createTestSignal<void>();
+  const latest = createTestSignal<void>();
+  const values: string[] = [];
+  let reads = 0;
+  let dispose = () => {};
+
+  try {
+    const thread = await client.sessionCreate(
+      { repoRoot: home, branch: "main" },
+      { type: "plan", content: "Initial", meta: {} },
+    );
+
+    dispose = subscribeThreadState({
+      connect: connectThreadObserver({ home }),
+      matches: (event) => event.sessionId === thread.id,
+      read: async (api) => {
+        const state = await api.sessionGet(thread.id);
+
+        if (++reads === 1) {
+          firstRead.resolve();
+          await releaseFirst.promise;
+        }
+
+        return state;
+      },
+      onValue: (state) => {
+        values.push(state.artifact.meta.title ?? "Initial");
+        latest.resolve();
+      },
+      onError: (error) => latest.reject(error),
+    });
+    await firstRead.promise;
+    await client.sessionSetTitle(thread.id, "New");
+    await latest.promise;
+    releaseFirst.resolve();
+    await Promise.resolve();
+    expect(values).toEqual(["New"]);
+    dispose();
+    await client.sessionSetTitle(thread.id, "After disposal");
+    expect(values).toEqual(["New"]);
+  } finally {
+    dispose();
+    client.close();
+    server.stop();
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("reconnect subscribes again and refreshes authoritative state even without a notification", async () => {
+  const home = mkdtempSync(join(tmpdir(), "cueloop-reconnect-"));
+  let server = new DaemonServer({ home, idleExitMs: 0 });
+
+  server.start();
+  const client = await DaemonClient.connect({ home });
+  const initial = createTestSignal<void>();
+  const recovered = createTestSignal<void>();
+  let connections = 0;
+  const values: string[] = [];
+  let dispose = () => {};
+
+  try {
+    const thread = await client.sessionCreate(
+      { repoRoot: home, branch: "main" },
+      { type: "plan", content: "Initial", meta: {} },
+    );
+
+    dispose = subscribeThreadState({
+      connect: connectThreadObserver({ home }),
+      reconnectMs: 1,
+      matches: (event) => event.sessionId === thread.id,
+      read: (api) => api.sessionGet(thread.id),
+      onConnect: () => {
+        connections++;
+      },
+      onValue: (state) => {
+        values.push(state.artifact.meta.title ?? "Initial");
+        if (connections === 1) initial.resolve();
+        else recovered.resolve();
+      },
+      onError() {},
+    });
+    await initial.promise;
+    server.stop();
+    server = new DaemonServer({ home, idleExitMs: 0 });
+    server.core.sessionSetTitle(thread.id, "Recovered");
+    server.start();
+    await recovered.promise;
+    expect(connections).toBe(2);
+    expect(values).toEqual(["Initial", "Recovered"]);
+  } finally {
+    dispose();
+    client.close();
+    server.stop();
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("a malformed protocol frame stops the observer instead of reconnecting", async () => {
+  const { LineBuffer, parseRequestFrame } = await import("./protocol");
+  const { socketPath } = await import("./paths");
+  const { DAEMON_VERSION } = await import("./version");
+  const home = mkdtempSync(join(tmpdir(), "cueloop-subscription-protocol-"));
+  const failed = createTestSignal<void>();
+  const reads = new Map<object, InstanceType<typeof LineBuffer>>();
+  let connections = 0;
+  const server = Bun.listen({
+    unix: socketPath(home),
+    socket: {
+      open(socket) {
+        reads.set(socket, new LineBuffer());
+        connections++;
+        if (connections > 1) failed.reject(new Error("Unexpected reconnect"));
+      },
+      data(socket, bytes) {
+        reads.get(socket)!.push(bytes.toString(), (line) => {
+          const request = parseRequestFrame(line);
+
+          socket.write(
+            JSON.stringify({
+              id: request.id,
+              result:
+                request.method === "daemon.ping"
+                  ? { pid: process.pid, version: DAEMON_VERSION }
+                  : {},
+            }) + "\n",
+          );
+          if (request.method === "events.subscribe") socket.write("{broken\n");
+        });
+      },
+      close(socket) {
+        reads.delete(socket);
+      },
+    },
+  });
+  const dispose = subscribeThreadState({
+    connect: connectThreadObserver({ home }),
+    reconnectMs: 1,
+    matches: () => true,
+    read: (client) => client.ping(),
+    onValue() {},
+    onError: (error) => {
+      expect(error).toMatchObject({ kind: "protocol" });
+      failed.resolve();
+    },
+  });
+
+  try {
+    await failed.promise;
+    // A timer boundary proves no reconnect remains scheduled after the protocol closure.
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(connections).toBe(1);
+  } finally {
+    dispose();
+    server.stop(true);
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/thread-subscription.ts

@@ -0,0 +1,129 @@
+import { DaemonClient, DaemonClientError, type ConnectOptions } from "./client";
+import { DaemonTransportError } from "./client-errors";
+import type { EventFrame } from "./protocol";
+
+// eslint-disable-next-line type-evidence/no-unknown-parameters -- Socket and read failures arrive from an untyped Promise rejection boundary.
+type ThreadSubscriptionErrorHandler = (error: unknown) => void;
+
+/** Notifications are refresh hints; each connection starts with an authoritative read. */
+export interface ThreadSubscriptionOptions<Value> {
+  connect: () => Promise<DaemonClient>;
+  matches: (event: EventFrame) => boolean;
+  read: (client: DaemonClient, signal: AbortSignal) => Promise<Value>;
+  onValue: (value: Value, client: DaemonClient) => void;
+  onError: ThreadSubscriptionErrorHandler;
+  onConnect?: (client: DaemonClient) => void;
+  reconnectMs?: number;
+}
+
+/** Dispose removes listeners, aborts local reads, and closes only the observation connection. */
+export function subscribeThreadState<Value>(options: ThreadSubscriptionOptions<Value>): () => void {
+  let stopped = false;
+  let generation = 0;
+  let connection: DaemonClient | undefined;
+  let detach: (() => void) | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const reads = new Set<AbortController>();
+  const schedule = () => {
+    if (!stopped) timer = setTimeout(() => void connect(), options.reconnectMs ?? 250);
+  };
+  const connect = async () => {
+    const epoch = ++generation;
+    let request = 0;
+    let api: DaemonClient | undefined;
+
+    try {
+      api = await options.connect();
+      if (stopped || epoch !== generation) {
+        api.close();
+
+        return;
+      }
+      connection = api;
+      const current = api;
+      const refresh = async () => {
+        const version = ++request;
+
+        for (const read of reads) read.abort();
+        const controller = new AbortController();
+
+        reads.add(controller);
+        try {
+          const value = await options.read(current, controller.signal);
+
+          if (!stopped && epoch === generation && version === request)
+            options.onValue(value, current);
+        } catch (error) {
+          if (!stopped && epoch === generation && version === request) {
+            if (error instanceof Error && isFatalSubscriptionError(error)) {
+              stopped = true;
+              ++generation;
+              clearTimeout(timer);
+              detach?.();
+              current.close();
+            }
+            options.onError(error);
+          }
+        } finally {
+          reads.delete(controller);
+        }
+      };
+      const offEvent = api.onEvent((event) => {
+        if (options.matches(event)) void refresh();
+      });
+      const offDisconnect = api.onDisconnect((reason) => {
+        if (stopped || epoch !== generation) return;
+        ++generation;
+        detach?.();
+        for (const read of reads) read.abort();
+        connection = undefined;
+        current.close();
+        if (isFatalSubscriptionError(reason)) {
+          stopped = true;
+          options.onError(reason);
+        } else schedule();
+      });
+
+      detach = () => {
+        offEvent();
+        offDisconnect();
+      };
+      await api.subscribe();
+      if (stopped || epoch !== generation) return;
+      options.onConnect?.(api);
+      await refresh();
+    } catch (error) {
+      if (stopped || epoch !== generation) return;
+      ++generation;
+      detach?.();
+      api?.close();
+      connection = undefined;
+      options.onError(error);
+      if (!(error instanceof Error && isFatalSubscriptionError(error))) schedule();
+    }
+  };
+
+  void connect();
+
+  return () => {
+    stopped = true;
+    ++generation;
+    clearTimeout(timer);
+    detach?.();
+    for (const read of reads) read.abort();
+    reads.clear();
+    connection?.close();
+  };
+}
+
+/** Reconnect never replays writes, only subscribes and reads the latest Thread state. */
+export function connectThreadObserver(options: ConnectOptions): () => Promise<DaemonClient> {
+  return () => DaemonClient.connect(options);
+}
+
+function isFatalSubscriptionError(error: Error): boolean {
+  return (
+    error instanceof DaemonClientError ||
+    (error instanceof DaemonTransportError && error.kind === "protocol")
+  );
+}