@cueloop/daemon 0.1.0-alpha.4 → 0.1.0-alpha.40

package/src/herdr-tab-store.ts

@@ -0,0 +1,67 @@
+/**
+ * herdr adapter scratch, kept out of the core session record: the tab cueloop
+ * opened to render each review, keyed by session id. One JSON map, atomic write.
+ * The core `ReviewSession` never mentions herdr; this side-store is the whole
+ * leak boundary.
+ */
+
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { herdrTabsPath } from "./paths";
+
+/** The tab and its root pane: pane id checks liveness, tab id focuses it. */
+export interface HerdrTabHandle {
+  tabId: string;
+  paneId: string;
+}
+
+/** Guard a persisted entry - both ids must be present strings, or it is dropped. */
+function isHerdrTabHandle(value: unknown): value is HerdrTabHandle {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as HerdrTabHandle).tabId === "string" &&
+    typeof (value as HerdrTabHandle).paneId === "string"
+  );
+}
+
+export class HerdrTabStore {
+  private tabs = new Map<string, HerdrTabHandle>();
+  private readonly path: string;
+
+  constructor(home: string) {
+    this.path = herdrTabsPath(home);
+    this.load();
+  }
+
+  private load(): void {
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(this.path, "utf8"));
+      if (typeof parsed !== "object" || parsed === null) return;
+      for (const [sessionId, value] of Object.entries(parsed)) {
+        if (isHerdrTabHandle(value))
+          this.tabs.set(sessionId, { tabId: value.tabId, paneId: value.paneId });
+      }
+    } catch {
+      // absent, unreadable, or malformed: start empty - a stale tab just reopens on resubmit
+    }
+  }
+
+  private persist(): void {
+    const tempPath = this.path + ".tmp";
+    writeFileSync(tempPath, JSON.stringify(Object.fromEntries(this.tabs), null, 2));
+    renameSync(tempPath, this.path);
+  }
+
+  get(sessionId: string): HerdrTabHandle | null {
+    return this.tabs.get(sessionId) ?? null;
+  }
+
+  set(sessionId: string, handle: HerdrTabHandle): void {
+    this.tabs.set(sessionId, handle);
+    this.persist();
+  }
+
+  delete(sessionId: string): void {
+    if (this.tabs.delete(sessionId)) this.persist();
+  }
+}

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/main.ts

@@ -2,7 +2,9 @@
 
 import { DaemonServer } from "./server";
 
-const idleExitMs = process.env.CUELOOP_IDLE_EXIT_MS ? Number(process.env.CUELOOP_IDLE_EXIT_MS) : undefined;
+const idleExitMs = process.env.CUELOOP_IDLE_EXIT_MS
+  ? Number(process.env.CUELOOP_IDLE_EXIT_MS)
+  : undefined;
 const server = new DaemonServer({ idleExitMs });
 const path = server.start();
 if (path === null) {

package/src/paths.ts

@@ -25,3 +25,8 @@ export function pidPath(home = cueloopHome()): string {
 export function lockPath(home = cueloopHome()): string {
   return join(home, "cueloop.lock");
 }
+
+/** Adapter scratch: herdr tab handles keyed by session id, kept out of the core session record. */
+export function herdrTabsPath(home = cueloopHome()): string {
+  return join(home, "herdr-tabs.json");
+}

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,362 @@
+/** 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 { awaitResolve, 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 {
+      // 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("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("awaitVerdict: one long-poll (the hook shape)", () => {
+  test("times out to pending; a later wait collects the stored verdict", async () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+
+    // Assert
+    expect(await review.awaitVerdict({ timeoutMs: 50 })).toBe("pending");
+
+    // Act
+    await client.sessionResolve(review.id, "approve", "Fine.");
+    const verdict = await review.awaitVerdict({ timeoutMs: 1_000 });
+
+    // Assert
+    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 () => {
+    // Arrange
+    const review = await openReview(client, { type: "plan", content: PLAN, cwd: home });
+    const waiting = review.awaitVerdict({ timeoutMs: 5_000 });
+
+    // Act
+    await client.sessionResolve(review.id, "request_changes", "One stage only.");
+    const verdict = await waiting;
+
+    // Assert
+    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 () => {
+    // Arrange
+    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),
+    });
+
+    // 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.sessionResolve(review.id, "request_changes", "Too vague.");
+    const verdict = await waiting;
+
+    // Assert
+    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 () => {
+    // Arrange
+    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,
+    });
+
+    // 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.awaitVerdict({ timeoutMs: 120, pollMs: 50 })).toBe("pending");
+  });
+});
+
+describe("awaitResolve: the adapter wake seam (session id only)", () => {
+  test("resolves to the outcome when the verdict 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.sessionResolve(review.id, "approve", "Ship it.");
+    const verdict = await waiting;
+
+    // Assert
+    expect(verdict).not.toBeNull();
+    expect(verdict!.allow).toBe(true);
+    expect(verdict!.feedback).toContain("Ship it.");
+    expect(verdict!.session.verdict!.kind).toBe("approve");
+  });
+
+  test("returns the stored verdict 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.sessionResolve(review.id, "request_changes", "One stage only.");
+
+    // Act
+    const verdict = await awaitResolve(client, review.id);
+
+    // Assert
+    expect(verdict).not.toBeNull();
+    expect(verdict!.allow).toBe(false);
+    expect(verdict!.feedback).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 verdict 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 verdict; the parked wait collects it
+      const resolver = await DaemonClient.connect({ home: idleHome });
+      await resolver.sessionResolve(review.id, "approve", "Good to go.");
+      resolver.close();
+      const verdict = await waiting;
+
+      // Assert
+      expect(verdict!.allow).toBe(true);
+    } finally {
+      waiterClient.close();
+      idleServer.stop();
+      rmSync(idleHome, { recursive: true, force: true });
+    }
+  }, 15_000);
+});