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

package/src/client.ts

@@ -1,38 +1,65 @@
 /**
  * Daemon client: the one library every consumer shares - CLI verbs, the TUI,
- * adapters, and tests. Also owns the lazy-launch story (#14): connect() with
+ * adapters, and tests. Also owns the lazy-launch story: connect() with
  * autostart spawns a detached daemon when the socket is dead, then attaches.
  */
 
 import { existsSync, rmSync } from "node:fs";
-import type { Annotation, Artifact, ReviewSession, VerdictKind, WorkspaceKey } from "@cueloop/schema";
-import { LineBuffer, type EventFrame, type Response } from "./protocol";
+import type { Annotation, Artifact, Identity, ReviewSession, VerdictKind, WorkspaceKey } from "@cueloop/schema";
+import { BackpressureWriter, LineBuffer, type EventFrame, type Response } from "./protocol";
 import { cueloopHome, socketPath } from "./paths";
 
+export type { EventFrame } from "./protocol";
+
 export interface ConnectOptions {
   home?: string;
   /** Spawn the daemon when the socket is not alive. */
   autostart?: boolean;
 }
 
-type Pending = { resolve: (v: unknown) => void; reject: (e: Error) => void };
+type PendingRequest = { resolve: (value: unknown) => void; reject: (error: Error) => void };
+
+/**
+ * The session verbs the review controller drives. DaemonClient is the local
+ * implementation (unix socket); the sharing gateway supplies an in-memory,
+ * blob-backed one. Depending on this interface - not DaemonClient - is what
+ * lets the same <App> render a local session or a decrypted share unchanged.
+ */
+export interface SessionClient {
+  onEvent(listener: (event: EventFrame) => void): () => void;
+  subscribe(): Promise<void>;
+  sessionGet(id: string): Promise<ReviewSession>;
+  sessionList(filter?: { status?: "pending" | "resolved" }): Promise<ReviewSession[]>;
+  sessionAnnotate(id: string, annotation: Omit<Annotation, "createdAt">): Promise<ReviewSession>;
+  sessionRemoveAnnotation(id: string, annotationId: string): Promise<ReviewSession>;
+  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<ReviewSession>;
+  sessionSetViewed(id: string, viewedPaths: string[]): Promise<ReviewSession>;
+  sessionSetShareId(id: string, shareId: string): Promise<ReviewSession>;
+  sessionMergeShared(id: string, incoming: { annotations: Annotation[]; participants?: Identity[] }): Promise<ReviewSession>;
+  sessionDelete(id: string): Promise<void>;
+  /** Record the caller's own identity name (collaborator self-naming on a share). */
+  sessionSetSelfName(id: string, name: string): Promise<ReviewSession>;
+  sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession>;
+  close(): void;
+}
 
-export class DaemonClient {
+export class DaemonClient implements SessionClient {
   private socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
-  private pending = new Map<number, Pending>();
+  private writer: BackpressureWriter | null = null;
+  private pending = new Map<number, PendingRequest>();
   private nextId = 1;
-  private eventListeners = new Set<(e: EventFrame) => void>();
+  private eventListeners = new Set<(event: EventFrame) => void>();
   private closed = false;
 
-  static async connect(opts: ConnectOptions = {}): Promise<DaemonClient> {
-    const home = opts.home ?? cueloopHome();
+  static async connect(options: ConnectOptions = {}): Promise<DaemonClient> {
+    const home = options.home ?? cueloopHome();
     const path = socketPath(home);
     const client = new DaemonClient();
     try {
       await client.dial(path);
       return client;
     } catch (err) {
-      if (!opts.autostart) throw err;
+      if (!options.autostart) throw err;
     }
     // Socket dead or absent: clean a stale file and spawn the daemon detached.
     if (existsSync(path)) rmSync(path, { force: true });
@@ -40,17 +67,17 @@ export class DaemonClient {
     // Generous: a cold or loaded machine pays for a runtime start before the
     // socket exists, and giving up early looks to callers like a broken daemon.
     const deadline = Date.now() + Number(process.env.CUELOOP_START_TIMEOUT_MS ?? 30_000);
-    let lastErr: unknown;
+    let lastError: unknown;
     while (Date.now() < deadline) {
       try {
         await client.dial(path);
         return client;
       } catch (err) {
-        lastErr = err;
+        lastError = err;
         await Bun.sleep(50);
       }
     }
-    throw new Error(`daemon did not come up at ${path}: ${String(lastErr)}`);
+    throw new Error(`daemon did not come up at ${path}: ${String(lastError)}`);
   }
 
   private async dial(path: string): Promise<void> {
@@ -60,27 +87,31 @@ export class DaemonClient {
       unix: path,
       socket: {
         data(_socket, data) {
-          buffer.push(data.toString(), (line) => self.handleFrame(line));
+          buffer.push(data.toString(), (line) => self.routeInboundFrame(line));
+        },
+        drain() {
+          self.writer?.drain();
         },
         close() {
           self.closed = true;
-          for (const p of self.pending.values()) p.reject(new Error("daemon connection closed"));
+          for (const pendingRequest of self.pending.values()) pendingRequest.reject(new Error("daemon connection closed"));
           self.pending.clear();
         },
         error() {},
       },
     });
+    this.writer = new BackpressureWriter(this.socket);
     // Verify liveness: a dead socket file accepts connects on some platforms
     // only to fail later, so a ping is the actual handshake.
     await this.request("daemon.ping", {}, 2_000);
   }
 
-  onEvent(listener: (e: EventFrame) => void): () => void {
+  onEvent(listener: (event: EventFrame) => void): () => void {
     this.eventListeners.add(listener);
     return () => this.eventListeners.delete(listener);
   }
 
-  private handleFrame(line: string): void {
+  private routeInboundFrame(line: string): void {
     let frame: Response | EventFrame;
     try {
       frame = JSON.parse(line) as Response | EventFrame;
@@ -88,14 +119,14 @@ export class DaemonClient {
       return;
     }
     if ("event" in frame) {
-      for (const l of this.eventListeners) l(frame);
+      for (const listener of this.eventListeners) listener(frame);
       return;
     }
-    const p = this.pending.get(frame.id);
-    if (!p) return;
+    const pendingRequest = this.pending.get(frame.id);
+    if (!pendingRequest) return;
     this.pending.delete(frame.id);
-    if (frame.error) p.reject(new DaemonClientError(frame.error.code, frame.error.message));
-    else p.resolve(frame.result);
+    if (frame.error) pendingRequest.reject(new DaemonClientError(frame.error.code, frame.error.message));
+    else pendingRequest.resolve(frame.result);
   }
 
   request<T = unknown>(method: string, params: unknown, timeoutMs = 30_000): Promise<T> {
@@ -107,16 +138,16 @@ export class DaemonClient {
         reject(new Error(`request ${method} timed out`));
       }, timeoutMs);
       this.pending.set(id, {
-        resolve: (v) => {
+        resolve: (value) => {
           clearTimeout(timer);
-          resolve(v as T);
+          resolve(value as T);
         },
-        reject: (e) => {
+        reject: (error) => {
           clearTimeout(timer);
-          reject(e);
+          reject(error);
         },
       });
-      this.socket!.write(JSON.stringify({ id, method, params }) + "\n");
+      this.writer!.write(JSON.stringify({ id, method, params }) + "\n");
     });
   }
 
@@ -154,11 +185,27 @@ 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 });
+  }
+  sessionSetShareId(id: string, shareId: string): Promise<ReviewSession> {
+    return this.request("session.setShareId", { id, shareId });
+  }
+  sessionMergeShared(id: string, incoming: { annotations: Annotation[]; participants?: Identity[] }): Promise<ReviewSession> {
+    return this.request("session.mergeShared", { id, ...incoming });
+  }
+  sessionDelete(id: string): Promise<void> {
+    return this.request("session.delete", { id });
+  }
+  /** Local sessions have no collaborator self-name; the share client owns this. */
+  sessionSetSelfName(id: string, _name: string): Promise<ReviewSession> {
+    return this.sessionGet(id);
+  }
   sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession> {
     return this.request("session.resolve", { id, verdictKind, summary });
   }
-  sessionSubmitRevision(id: string, content: string): Promise<ReviewSession> {
-    return this.request("session.submitRevision", { id, content });
+  sessionSubmitRevision(id: string, content: string, addressedAnnotationIds: string[] = []): Promise<ReviewSession> {
+    return this.request("session.submitRevision", { id, content, addressedAnnotationIds });
   }
   shutdown(): Promise<void> {
     return this.request("daemon.shutdown", {});

package/src/herdr-pane.test.ts

@@ -0,0 +1,146 @@
+/** Creation-side herdr pane opener: a stubbed herdr binary logs its argv, and the gating wrapper is checked for its three outcomes (no-op outside herdr, no-op on revision, full open for a new session). */
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ReviewSession } from "@cueloop/schema";
+import { openHerdrPane, openHerdrPaneForReview } from "./herdr-pane";
+
+const dir = mkdtempSync(join(tmpdir(), "cueloop-herdr-pane-"));
+
+/**
+ * A stub herdr binary. It appends its argv to logPath and, when the verb is
+ * `tab create`, prints a JSON result carrying the pane id on stdout so the
+ * helper can drive send-text and send-keys. The printed shape mirrors the
+ * REAL herdr `tab create` output ({ result: { root_pane: { pane_id } } },
+ * verified against herdr 0.8.0) - an earlier stub invented a different shape
+ * and let a parser that never matched real herdr pass the suite.
+ */
+function makeStub(name: string, paneId = "w1:p2"): { binPath: string; logPath: string } {
+  const logPath = join(dir, `${name}.log`);
+  const binPath = join(dir, `${name}.sh`);
+  writeFileSync(
+    binPath,
+    `#!/bin/sh\nprintf '%s\\n' "$*" >> "${logPath}"\nif [ "$1" = "tab" ] && [ "$2" = "create" ]; then\n  printf '{"result":{"root_pane":{"pane_id":"${paneId}"}}}'\nfi\n`,
+  );
+  chmodSync(binPath, 0o755);
+  return { binPath, logPath };
+}
+
+function readLines(logPath: string): string[] {
+  if (!existsSync(logPath)) return [];
+  return readFileSync(logPath, "utf8").split("\n").filter(Boolean);
+}
+
+function newSession(overrides: Partial<ReviewSession> = {}): ReviewSession {
+  return {
+    schemaVersion: "1",
+    id: "ses_new1",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: "# P", meta: { cwd: "/repo/work", title: "Rollout Plan" } },
+    revisions: [{ revision: 1, content: "# P", submittedAt: "now" }],
+    annotations: [],
+    verdict: null,
+    status: "pending",
+    createdAt: "now",
+    ...overrides,
+  };
+}
+
+describe("openHerdrPane", () => {
+  test("creates a focused tab, types the cueloop command, and presses enter", () => {
+    // Arrange
+    const stub = makeStub("open");
+
+    // Act
+    const ok = openHerdrPane({ sessionId: "ses_abc", cwd: "/repo/work", binPath: stub.binPath, label: "Rollout Plan" });
+
+    // Assert
+    expect(ok).toBeTrue();
+    expect(readLines(stub.logPath)).toEqual([
+      "tab create --cwd /repo/work --label Rollout Plan --focus",
+      "pane send-text w1:p2 cueloop ses_abc",
+      "pane send-keys w1:p2 enter",
+    ]);
+  });
+
+  test("returns false and never throws on a broken binary", () => {
+    // Act
+    const ok = openHerdrPane({
+      sessionId: "ses_abc",
+      cwd: "/repo/work",
+      binPath: join(dir, "missing-bin"),
+      label: "x",
+    });
+
+    // Assert
+    expect(ok).toBeFalse();
+  });
+
+  test("bails out when tab create yields no pane id - no send-text, no send-keys", () => {
+    // Arrange
+    const logPath = join(dir, "nopane.log");
+    const binPath = join(dir, "nopane.sh");
+    writeFileSync(binPath, `#!/bin/sh\nprintf '%s\\n' "$*" >> "${logPath}"\nprintf '{"result":{}}'\n`);
+    chmodSync(binPath, 0o755);
+
+    // Act
+    const ok = openHerdrPane({ sessionId: "ses_abc", cwd: "/repo/work", binPath, label: "x" });
+
+    // Assert
+    expect(ok).toBeFalse();
+    expect(readLines(logPath)).toEqual(["tab create --cwd /repo/work --label x --focus"]);
+  });
+});
+
+describe("openHerdrPaneForReview", () => {
+  test("opens a pane for a genuinely new session inside herdr", () => {
+    // Arrange
+    const stub = makeStub("gated-new");
+    const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+
+    // Act
+    openHerdrPaneForReview(newSession({ id: "ses_xyz" }), env);
+
+    // Assert
+    expect(readLines(stub.logPath)).toEqual([
+      "tab create --cwd /repo/work --label Rollout Plan --focus",
+      "pane send-text w1:p2 cueloop ses_xyz",
+      "pane send-keys w1:p2 enter",
+    ]);
+  });
+
+  test("no-op outside herdr - no herdr process is spawned", () => {
+    // Arrange
+    const stub = makeStub("gated-outside");
+
+    // Act
+    openHerdrPaneForReview(newSession(), { HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath });
+
+    // Assert
+    expect(existsSync(stub.logPath)).toBeFalse();
+  });
+
+  test("no-op for a revision - the already open pane is reused, not spammed", () => {
+    // Arrange
+    const stub = makeStub("gated-revision");
+    const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+    const revised = newSession({
+      revisions: [
+        { revision: 1, content: "# P", submittedAt: "now" },
+        { revision: 2, content: "# P2", submittedAt: "now" },
+      ],
+    });
+
+    // Act
+    openHerdrPaneForReview(revised, env);
+
+    // Assert
+    expect(existsSync(stub.logPath)).toBeFalse();
+  });
+});
+
+afterAll(() => {
+  rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+});

package/src/herdr-pane.ts

@@ -0,0 +1,95 @@
+/**
+ * Creation-side herdr pane opener: when a review is created from inside a
+ * herdr pane, cueloop opens a NEW herdr tab that renders the review, so the
+ * creator does not have to run a command by hand. This is the counterpart to
+ * the reviewer-side focusHerdrPane in @cueloop/client. It lives here, beside
+ * the shared review core (openReview), because both creation sites - the
+ * Claude Code hook and the `cueloop session create` CLI - already depend on
+ * this package and drive creation through it, so a single home reaches both
+ * with no new cross-package dependency.
+ *
+ * A fresh tab hosts a plain shell with no command argument, so the review is
+ * launched exactly as a human would: type `cueloop <sessionId>` into the new
+ * pane and press enter. The herdr CLI is spawned synchronously because the
+ * send-text and send-keys steps need the pane id that `tab create` returns.
+ *
+ * Best-effort like the rest of the herdr tier: a missing or broken binary, an
+ * unexpected JSON shape, or any spawn failure is swallowed and never blocks
+ * review creation. Each spawn is bounded by HERDR_SPAWN_TIMEOUT_MS so a hung
+ * herdr binary cannot stall the review-creation path - a timeout kills the
+ * child and reads as a non-zero exit, i.e. a best-effort bail-out.
+ */
+
+import { detectHerdr, type HerdrEnv, type ReviewSession } from "@cueloop/schema";
+
+/** Upper bound per herdr spawn, so a stuck binary can never block creation. */
+const HERDR_SPAWN_TIMEOUT_MS = 2000;
+
+export interface OpenHerdrPaneOptions {
+  /** The review session id; `cueloop <sessionId>` opens it in the new pane. */
+  sessionId: string;
+  /** Working directory for the new tab; the review's cwd. */
+  cwd: string;
+  /** Absolute path to the herdr binary, from the ambient env contract. */
+  binPath: string;
+  /** Sidebar label for the new tab. */
+  label: string;
+}
+
+/**
+ * Open a herdr tab that renders the review. `tab create` prints a JSON result
+ * shaped like `{ result: { root_pane: { pane_id } } }` (verified against
+ * herdr 0.8.0; `pane get` uses a different `result.pane` nesting, which is
+ * what focusHerdrPane reads). The pane id drives the two follow-up steps.
+ * Returns true when the full open-and-launch sequence completed, false on any
+ * best-effort bail-out.
+ */
+export function openHerdrPane(options: OpenHerdrPaneOptions): boolean {
+  const { sessionId, cwd, binPath, label } = options;
+  try {
+    const created = Bun.spawnSync([binPath, "tab", "create", "--cwd", cwd, "--label", label, "--focus"], {
+      stdout: "pipe",
+      stderr: "ignore",
+      timeout: HERDR_SPAWN_TIMEOUT_MS,
+    });
+    if (created.exitCode !== 0) return false;
+    const parsed = JSON.parse(created.stdout.toString()) as { result?: { root_pane?: { pane_id?: string } } };
+    const paneId = parsed.result?.root_pane?.pane_id;
+    if (!paneId) return false;
+    // A fresh tab hosts a plain shell, so the review is typed in like a human.
+    const typed = Bun.spawnSync([binPath, "pane", "send-text", paneId, `cueloop ${sessionId}`], {
+      stdout: "ignore",
+      stderr: "ignore",
+      timeout: HERDR_SPAWN_TIMEOUT_MS,
+    });
+    if (typed.exitCode !== 0) return false;
+    return (
+      Bun.spawnSync([binPath, "pane", "send-keys", paneId, "enter"], {
+        stdout: "ignore",
+        stderr: "ignore",
+        timeout: HERDR_SPAWN_TIMEOUT_MS,
+      }).exitCode === 0
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Open a pane for a freshly created review, guarded for the one case that
+ * wants it: inside herdr and genuinely new. A revision reuses the pane the
+ * original review already opened, so a resubmit (revisions beyond the first)
+ * never spawns another tab. A no-op outside herdr keeps a plain terminal
+ * byte-identical.
+ */
+export function openHerdrPaneForReview(session: ReviewSession, env: HerdrEnv = process.env): void {
+  const herdr = detectHerdr(env);
+  if (!herdr) return;
+  if (session.revisions.length !== 1) return;
+  openHerdrPane({
+    sessionId: session.id,
+    cwd: session.artifact.meta.cwd ?? process.cwd(),
+    binPath: herdr.binPath,
+    label: session.artifact.meta.title ?? session.id,
+  });
+}

package/src/index.ts

@@ -1,8 +1,8 @@
-export * from "./api";
-export * from "./errors";
-export * from "./validate";
-export * from "./store";
-export * from "./server";
-export * from "./protocol";
-export * from "./paths";
-export { DaemonClient, DaemonClientError, type ConnectOptions } from "./client";
+/**
+ * The daemon's public surface. Consumers reach the client and the review
+ * helpers through the ./client and ./review subpaths; this barrel carries
+ * only the two names imported bare: the server and the home-dir resolver.
+ */
+
+export { DaemonServer, type DaemonOptions } from "./server";
+export { cueloopHome } from "./paths";

package/src/protocol.ts

@@ -1,5 +1,5 @@
 /**
- * Wire protocol (#14): newline-delimited JSON over the unix socket.
+ * Wire protocol: newline-delimited JSON over the unix socket.
  * Requests: { id, method, params }  Responses: { id, result } | { id, error }
  * Events (push, after events.subscribe): { event, sessionId }
  */
@@ -25,16 +25,53 @@ export type Frame = Response | EventFrame;
 
 /** Incremental NDJSON splitter; tolerates partial writes. */
 export class LineBuffer {
-  private buf = "";
+  private buffered = "";
 
   push(chunk: string, onLine: (line: string) => void): void {
-    this.buf += chunk;
+    this.buffered += chunk;
     for (;;) {
-      const nl = this.buf.indexOf("\n");
-      if (nl === -1) return;
-      const line = this.buf.slice(0, nl).trim();
-      this.buf = this.buf.slice(nl + 1);
+      const newlineIndex = this.buffered.indexOf("\n");
+      if (newlineIndex === -1) return;
+      const line = this.buffered.slice(0, newlineIndex).trim();
+      this.buffered = this.buffered.slice(newlineIndex + 1);
       if (line) onLine(line);
     }
   }
 }
+
+/** The surface both Bun.listen and Bun.connect sockets satisfy. */
+interface WritableSocket {
+  write(data: Buffer): number;
+}
+
+/**
+ * Outbound writes honoring socket backpressure. A frame larger than the
+ * kernel buffer is written partially by the socket; the unwritten tail must
+ * wait for the drain callback or the frame truncates mid-line and the NDJSON
+ * stream corrupts for good. Frames never reorder: while a tail is pending,
+ * new writes append behind it.
+ */
+export class BackpressureWriter {
+  private pending: Buffer | null = null;
+
+  constructor(private socket: WritableSocket) {}
+
+  write(data: string): void {
+    const bytes = Buffer.from(data, "utf8");
+    if (this.pending) {
+      this.pending = Buffer.concat([this.pending, bytes]);
+      return;
+    }
+    const written = Math.max(0, this.socket.write(bytes));
+    if (written < bytes.length) this.pending = bytes.subarray(written);
+  }
+
+  /** Call from the socket's drain handler. */
+  drain(): void {
+    if (!this.pending) return;
+    const tail = this.pending;
+    this.pending = null;
+    const written = Math.max(0, this.socket.write(tail));
+    if (written < tail.length) this.pending = tail.subarray(written);
+  }
+}