@cueloop/daemon 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/herdr-pane.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Creation-side herdr pane opener tests. The herdr binary is stubbed by a
+ * script that both records its argv to a log file and, for `tab create`,
+ * prints the JSON the helper reads to learn the new pane id. The gating
+ * wrapper is exercised for its three outcomes: no-op outside herdr, no-op for
+ * a revision (the open pane is reused), and a full open for a genuinely 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 paneId on stdout so the helper
+ * can drive send-text and send-keys.
+ */
+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":{"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", () => {
+    const stub = makeStub("open");
+    const ok = openHerdrPane({ sessionId: "ses_abc", cwd: "/repo/work", binPath: stub.binPath, label: "Rollout Plan" });
+    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", () => {
+    const ok = openHerdrPane({
+      sessionId: "ses_abc",
+      cwd: "/repo/work",
+      binPath: join(dir, "missing-bin"),
+      label: "x",
+    });
+    expect(ok).toBeFalse();
+  });
+
+  test("bails out when tab create yields no pane id - no send-text, no send-keys", () => {
+    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);
+    const ok = openHerdrPane({ sessionId: "ses_abc", cwd: "/repo/work", binPath, label: "x" });
+    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", () => {
+    const stub = makeStub("gated-new");
+    const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+    openHerdrPaneForReview(newSession({ id: "ses_xyz" }), env);
+    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", () => {
+    const stub = makeStub("gated-outside");
+    openHerdrPaneForReview(newSession(), { HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath });
+    expect(existsSync(stub.logPath)).toBeFalse();
+  });
+
+  test("no-op for a revision - the already open pane is reused, not spammed", () => {
+    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" },
+      ],
+    });
+    openHerdrPaneForReview(revised, env);
+    expect(existsSync(stub.logPath)).toBeFalse();
+  });
+});
+
+afterAll(() => {
+  rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+});

package/src/herdr-pane.ts

@@ -0,0 +1,94 @@
+/**
+ * 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: { pane: { id } } }` - the same `result.pane` nesting
+ * focusHerdrPane reads - and 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?: { pane?: { id?: string } } };
+    const paneId = parsed.result?.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);
+  }
+}

package/src/review.test.ts

@@ -0,0 +1,184 @@
+/**
+ * The shared review core against a real DaemonServer in a temp home:
+ * workspace resolution, title derivation, open-or-revise by agentSessionId,
+ * and both awaitVerdict 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 { ReviewSession } from "@cueloop/schema";
+import { DaemonServer } from "./server";
+import { DaemonClient } from "./client";
+import { openReview, resolveWorkspace } from "./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 {
+      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);
+      const ws = await resolveWorkspace(repo);
+      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 () => {
+    const ws = await resolveWorkspace(home);
+    expect(ws).toEqual({ repoRoot: home, branch: "detached" });
+  });
+});
+
+describe("openReview", () => {
+  test("shapes the artifact: agent, derived title, cwd", async () => {
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home, agent: "test-agent" });
+    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 () => {
+    const titled = await openReview(client, { type: "plan", content: PLAN, cwd: home, title: "Custom" });
+    expect(titled.session.artifact.meta.title).toBe("Custom");
+    const diff = await openReview(client, { type: "diff", content: "# not a heading\n", cwd: home });
+    expect(diff.session.artifact.meta.title).toBeUndefined();
+  });
+
+  test("a pre-resolved workspace skips git resolution", async () => {
+    const ws = { repoRoot: "/elsewhere", branch: "feature" };
+    const review = await openReview(client, { type: "diff", content: "d", cwd: home, workspace: ws });
+    expect(review.session.workspace).toEqual(ws);
+  });
+
+  test("the same agentSessionId revises instead of opening a new session", async () => {
+    const first = await openReview(client, { type: "plan", content: PLAN, cwd: home, agentSessionId: "agent-1" });
+    const second = await openReview(client, {
+      type: "plan",
+      content: PLAN + "\nStage three.\n",
+      cwd: home,
+      agentSessionId: "agent-1",
+    });
+    expect(second.id).toBe(first.id);
+    expect(second.session.revisions.length).toBe(2);
+    expect(second.session.status).toBe("pending");
+    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)", () => {
+  test("times out to pending; a later wait collects the stored verdict", async () => {
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    expect(await review.awaitVerdict({ timeoutMs: 50 })).toBe("pending");
+    await client.sessionResolve(review.id, "approve", "Fine.");
+    const verdict = await review.awaitVerdict({ timeoutMs: 1_000 });
+    expect(verdict).not.toBe("pending");
+    if (verdict === "pending") throw new Error("unreachable");
+    expect(verdict.allow).toBe(true);
+    expect(verdict.feedback).toContain("Fine.");
+    expect(verdict.session.verdict!.kind).toBe("approve");
+  });
+
+  test("request_changes maps to allow=false with feedback.md attached", async () => {
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    const waiting = review.awaitVerdict({ timeoutMs: 5_000 });
+    await client.sessionResolve(review.id, "request_changes", "One stage only.");
+    const verdict = await waiting;
+    if (verdict === "pending") throw new Error("expected a verdict");
+    expect(verdict.allow).toBe(false);
+    expect(verdict.feedback).toContain("# Review: request changes");
+    expect(verdict.feedback).toContain("One stage only.");
+  });
+});
+
+describe("awaitVerdict: chunked loop (the pi shape)", () => {
+  test("onProgress sees fresh sessions between chunks; the verdict ends the loop", async () => {
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    const seen: ReviewSession[] = [];
+    const waiting = review.awaitVerdict({
+      timeoutMs: Infinity,
+      pollMs: 100,
+      onProgress: (progress) => seen.push(progress),
+    });
+    await client.sessionAnnotate(review.id, {
+      id: "a1",
+      kind: "comment",
+      anchor: { quote: "two stages", prefix: "in ", suffix: "." },
+      body: "Name them.",
+    });
+    // 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);
+    await client.sessionResolve(review.id, "request_changes", "Too vague.");
+    const verdict = await waiting;
+    if (verdict === "pending") throw new Error("expected a verdict");
+    expect(verdict.allow).toBe(false);
+    expect(verdict.session.annotations.length).toBe(1);
+  }, 15_000);
+
+  test("abort surfaces as pending and leaves the session collectable", async () => {
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    const controller = new AbortController();
+    const waiting = review.awaitVerdict({ timeoutMs: Infinity, pollMs: 100, signal: controller.signal });
+    controller.abort();
+    expect(await waiting).toBe("pending");
+    expect((await client.sessionGet(review.id)).status).toBe("pending");
+  });
+
+  test("a finite budget runs out to pending", async () => {
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    expect(await review.awaitVerdict({ timeoutMs: 120, pollMs: 50 })).toBe("pending");
+  });
+});