@cueloop/daemon 0.1.0-alpha.6 → 0.1.0-alpha.61

package/src/server.test.ts

@@ -27,18 +27,28 @@ afterEach(() => {
 
 describe("socket round-trip", () => {
   test("ping and full session flow over the wire", async () => {
+    // Assert
     expect((await client.ping()).pid).toBe(process.pid);
-    const s = await client.sessionCreate(WS, PLAN);
-    expect(s.status).toBe("pending");
-    await client.sessionAnnotate(s.id, {
+
+    // Act
+    const session = await client.sessionCreate(WS, PLAN);
+
+    // Assert
+    expect(session.status).toBe("pending");
+
+    // Act
+    await client.sessionAnnotate(session.id, {
       id: "a1",
       kind: "comment",
       anchor: { quote: "Body text", prefix: "", suffix: "." },
       body: "More detail please.",
     });
-    const wait = client.sessionWait(s.id, 5_000);
-    await client.sessionResolve(s.id, "request_changes", "Expand it.");
+    const wait = client.sessionWait(session.id, 5_000);
+
+    await client.sessionResolve(session.id, "request_changes", "Expand it.");
     const resolved = (await wait)!;
+
+    // Assert
     expect(resolved.verdict!.kind).toBe("request_changes");
     expect(resolved.verdict!.feedback).toContain("More detail please.");
   });
@@ -47,18 +57,25 @@ describe("socket round-trip", () => {
     expect(client.sessionGet("nope")).rejects.toBeInstanceOf(DaemonClientError);
     try {
       await client.sessionGet("nope");
-    } catch (e) {
-      expect((e as DaemonClientError).code).toBe("not_found");
+    } catch (error) {
+      expect((error as DaemonClientError).code).toBe("not_found");
     }
   });
 
   test("events push to subscribed connections only", async () => {
+    // Arrange
     const observer = await DaemonClient.connect({ home });
     const seen: string[] = [];
-    observer.onEvent((e) => seen.push(e.event));
+
+    observer.onEvent((event) => seen.push(event.event));
     await observer.subscribe();
-    const s = await client.sessionCreate(WS, PLAN);
-    await client.sessionResolve(s.id, "approve", "");
+
+    // Act
+    const session = await client.sessionCreate(WS, PLAN);
+
+    await client.sessionResolve(session.id, "approve", "");
+
+    // Assert
     // events are pushed async over the socket; give the loop a beat
     await Bun.sleep(50);
     expect(seen).toContain("session.created");
@@ -71,33 +88,165 @@ describe("socket round-trip", () => {
     try {
       await client.request("session.create", { artifact: { type: "plan", content: "x" } });
       throw new Error("should have thrown");
-    } catch (e) {
-      expect((e as DaemonClientError).code).toBe("invalid_params");
+    } catch (error) {
+      expect((error as DaemonClientError).code).toBe("invalid_params");
     }
     // wrong types
     try {
       await client.request("session.wait", { id: 42 });
       throw new Error("should have thrown");
-    } catch (e) {
-      expect((e as DaemonClientError).code).toBe("invalid_params");
+    } catch (error) {
+      expect((error as DaemonClientError).code).toBe("invalid_params");
     }
     // unknown method
     try {
       await client.request("session.nuke", {});
       throw new Error("should have thrown");
-    } catch (e) {
-      expect((e as DaemonClientError).code).toBe("unknown_method");
+    } catch (error) {
+      expect((error as DaemonClientError).code).toBe("unknown_method");
+    }
+    const prototypeMethods = await Promise.allSettled([
+      client.request("__proto__", {}),
+      client.request("toString", {}),
+      client.request("constructor", {}),
+    ]);
+
+    for (const result of prototypeMethods) {
+      expect(result.status).toBe("rejected");
+      expect(((result as PromiseRejectedResult).reason as DaemonClientError).code).toBe(
+        "unknown_method",
+      );
     }
     // the daemon is still fully alive afterwards
-    const s = await client.sessionCreate(WS, PLAN);
-    expect((await client.sessionGet(s.id)).id).toBe(s.id);
+    const session = await client.sessionCreate(WS, PLAN);
+
+    expect((await client.sessionGet(session.id)).id).toBe(session.id);
+  });
+
+  test("meta fields survive the wire: herdrPane set on create comes back from get", async () => {
+    // Act
+    const session = await client.sessionCreate(WS, {
+      type: "plan",
+      content: "# P",
+      meta: { agent: "claude-code", herdrPane: "%7" },
+    });
+    const got = await client.sessionGet(session.id);
+
+    // Assert
+    expect(got.artifact.meta.herdrPane).toBe("%7");
+    expect(got.artifact.meta.agent).toBe("claude-code");
+  });
+
+  test("share-sync verbs round-trip: setShareId persists, mergeShared unions notes and identities by id", async () => {
+    // Given a shared session with one local note
+    const session = await client.sessionCreate(WS, PLAN);
+    const anchor = { quote: "Body text", prefix: "", suffix: "." };
+
+    await client.sessionSetShareId(session.id, "p_abc123xy");
+    await client.sessionAnnotate(session.id, { id: "a1", kind: "comment", anchor, body: "mine" });
+    expect((await client.sessionGet(session.id)).shareId).toBe("p_abc123xy");
+
+    // When a pull merges an update to the known id, a new collaborator note, and the collaborator's identity
+    const merged = await client.sessionMergeShared(session.id, {
+      annotations: [
+        {
+          id: "a1",
+          kind: "comment",
+          anchor,
+          body: "should not overwrite",
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+        {
+          id: "a2",
+          kind: "comment",
+          anchor,
+          body: "theirs",
+          author: "SHA256:mate",
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      participants: [{ id: "SHA256:mate", provider: "ssh", name: "Sam" }],
+    });
+
+    // Then notes union by id (existing a1 kept), and the participant registry carries the collaborator's name
+    expect(merged.annotations.map((annotation) => annotation.id).sort()).toEqual(["a1", "a2"]);
+    expect(merged.annotations.find((annotation) => annotation.id === "a1")!.body).toBe("mine");
+    expect(merged.annotations.find((annotation) => annotation.id === "a2")!.author).toBe(
+      "SHA256:mate",
+    );
+    expect(merged.participants).toEqual([{ id: "SHA256:mate", provider: "ssh", name: "Sam" }]);
+  });
+
+  test("mergeShared validates each annotation at the socket boundary", async () => {
+    // Given a session
+    const session = await client.sessionCreate(WS, PLAN);
+
+    try {
+      // When a malformed annotation is merged
+      // @ts-expect-error intentionally malformed annotation (empty id, missing fields)
+      await client.sessionMergeShared(session.id, { annotations: [{ id: "" }] });
+      throw new Error("should have thrown");
+    } catch (error) {
+      // Then it is rejected at the wire boundary
+      expect((error as DaemonClientError).code).toBe("invalid_params");
+    }
+  });
+
+  test("session.delete removes a session over the wire", async () => {
+    // Given a created session
+    const session = await client.sessionCreate(WS, PLAN);
+
+    // When it is deleted
+    await client.sessionDelete(session.id);
+
+    // Then it is gone, and deleting an unknown id is a not_found error
+    expect(client.sessionGet(session.id)).rejects.toBeInstanceOf(DaemonClientError);
+    try {
+      await client.sessionDelete("ses_missing");
+      throw new Error("should have thrown");
+    } catch (error) {
+      expect((error as DaemonClientError).code).toBe("not_found");
+    }
   });
 
   test("two clients see the same state (thin-renderer model)", async () => {
+    // Arrange
     const second = await DaemonClient.connect({ home });
-    const s = await client.sessionCreate(WS, PLAN);
-    const fromSecond = await second.sessionGet(s.id);
+
+    // Act
+    const session = await client.sessionCreate(WS, PLAN);
+    const fromSecond = await second.sessionGet(session.id);
+
+    // Assert
     expect(fromSecond.artifact.content).toBe(PLAN.content);
     second.close();
   });
 });
+
+describe("large payloads survive socket backpressure", () => {
+  test("a session bigger than the kernel socket buffer round-trips", async () => {
+    // Regression: responses larger than one socket write used to truncate
+    // mid-line because the write return value was ignored, so the client
+    // never saw the frame's newline and every later request wedged too.
+    // Arrange
+    const bigContent =
+      "# Big plan\n" + "lorem ipsum dolor sit amet, consectetur adipiscing elit\n".repeat(4000);
+
+    // Act
+    const created = await client.sessionCreate(
+      { repoRoot: "/repo", branch: "main" },
+      { type: "plan", content: bigContent, meta: { title: "big" } },
+    );
+    const fetched = await client.sessionGet(created.id);
+
+    // Assert
+    expect(fetched.artifact.content).toBe(bigContent);
+
+    // Act
+    // the connection must still be usable for the next frame
+    const listed = await client.sessionList();
+
+    // Assert
+    expect(listed.some((session) => session.id === created.id)).toBe(true);
+  }, 15_000);
+});

package/src/server.ts

@@ -1,21 +1,35 @@
 /**
  * The socket server: binds DaemonCore's methods to the unix socket, owns the
- * pidfile, stale-socket cleanup, and the idle-exit timer (#14). File
+ * pidfile, stale-socket cleanup, and the idle-exit timer. File
  * permissions are the local auth: the socket and state dir are 0700/0600.
  */
 
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { DaemonCore, type DaemonEvent } from "./api";
 import { DaemonError } from "./errors";
-import { isKnownMethod, parseParams } from "./validate";
-import { LineBuffer, type Request } from "./protocol";
+import { roleAllowsMethod, type DaemonRole } from "./capabilities";
+import { isKnownMethod, parseParams, type MethodName } from "./validate";
+import { BackpressureWriter, LineBuffer, type Request } from "./protocol";
 import { cueloopHome, lockPath, pidPath, socketPath } from "./paths";
 
-interface Conn {
+interface Connection {
   write(data: string): void;
   subscribed: boolean;
+  /** Capability role for this connection; the owner until a daemon.hello caps it. */
+  role: DaemonRole;
 }
 
+type MethodHandler = (connection: Connection, request: Request) => unknown;
+
 export interface DaemonOptions {
   home?: string;
   /** Idle-exit delay; 0 disables (tests, foreground runs). */
@@ -33,20 +47,20 @@ const HELD_HOMES = new Set<string>();
 export class DaemonServer {
   readonly core: DaemonCore;
   readonly home: string;
-  private conns = new Set<Conn>();
+  private connections = new Set<Connection>();
   private server: ReturnType<typeof Bun.listen> | null = null;
   private idleTimer: ReturnType<typeof setTimeout> | null = null;
   private lockFd: number | null = null;
   private readonly idleExitMs: number;
   private readonly onIdleExit: () => void;
 
-  constructor(opts: DaemonOptions = {}) {
-    this.home = opts.home ?? cueloopHome();
-    this.idleExitMs = opts.idleExitMs ?? 15 * 60 * 1000;
-    this.onIdleExit = opts.onIdleExit ?? (() => process.exit(0));
+  constructor(options: DaemonOptions = {}) {
+    this.home = options.home ?? cueloopHome();
+    this.idleExitMs = options.idleExitMs ?? 15 * 60 * 1000;
+    this.onIdleExit = options.onIdleExit ?? (() => process.exit(0));
     mkdirSync(this.home, { recursive: true, mode: 0o700 });
     this.core = new DaemonCore(this.home);
-    this.core.onEvent((e) => this.broadcast(e));
+    this.core.onEvent((event) => this.broadcast(event));
   }
 
   /**
@@ -59,16 +73,20 @@ export class DaemonServer {
   private acquireLock(): boolean {
     if (HELD_HOMES.has(this.home)) return false; // another instance here owns it
     const path = lockPath(this.home);
+
     for (let attempt = 0; attempt < 3; attempt++) {
       try {
         // "wx" fails when the file exists - the atomic part of the handshake
         const fd = openSync(path, "wx");
+
         writeFileSync(fd, String(process.pid));
         this.lockFd = fd;
         HELD_HOMES.add(this.home);
+
         return true;
       } catch {
         let ownerPid = 0;
+
         try {
           ownerPid = Number(readFileSync(path, "utf8").trim());
         } catch {
@@ -78,6 +96,7 @@ export class DaemonServer {
         if (ownerPid && ownerPid !== process.pid) {
           try {
             process.kill(ownerPid, 0); // throws when the pid is gone
+
             return false; // a live daemon owns this home
           } catch {
             // stale lock from a crashed daemon
@@ -92,6 +111,7 @@ export class DaemonServer {
         }
       }
     }
+
     return false;
   }
 
@@ -115,27 +135,42 @@ export class DaemonServer {
   start(): string | null {
     if (!this.acquireLock()) return null;
     const path = socketPath(this.home);
+
     // safe now: holding the lock means no live daemon owns this home, so any
     // socket file left behind is stale
     if (existsSync(path)) rmSync(path, { force: true });
-    const self = this;
-    this.server = Bun.listen<{ buffer: LineBuffer; conn: Conn }>({
+    this.server = Bun.listen<{
+      buffer: LineBuffer;
+      connection: Connection;
+      writer: BackpressureWriter;
+    }>({
       unix: path,
       socket: {
-        open(socket) {
-          const conn: Conn = { write: (d) => socket.write(d), subscribed: false };
-          socket.data = { buffer: new LineBuffer(), conn };
-          self.conns.add(conn);
-          self.scheduleIdleCheck();
+        open: (socket) => {
+          const writer = new BackpressureWriter(socket);
+          const connection: Connection = {
+            write: (data) => writer.write(data),
+            subscribed: false,
+            role: "owner",
+          };
+
+          socket.data = { buffer: new LineBuffer(), connection, writer };
+          this.connections.add(connection);
+          this.scheduleIdleCheck();
         },
-        data(socket, data) {
+        data: (socket, data) => {
           socket.data.buffer.push(data.toString(), (line) => {
-            void self.handleLine(socket.data.conn, line);
+            void this.respondToRequestLine(socket.data.connection, line);
           });
         },
-        close(socket) {
-          self.conns.delete(socket.data.conn);
-          self.scheduleIdleCheck();
+        drain(socket) {
+          // drain can fire before open has attached data on some platforms;
+          // a throw here would take the whole daemon down with the socket
+          socket.data?.writer.drain();
+        },
+        close: (socket) => {
+          this.connections.delete(socket.data.connection);
+          this.scheduleIdleCheck();
         },
         error() {},
       },
@@ -143,10 +178,12 @@ export class DaemonServer {
     chmodSync(path, 0o600);
     writeFileSync(pidPath(this.home), String(process.pid));
     this.scheduleIdleCheck();
+
     return path;
   }
 
   stop(): void {
+    this.core.dispose();
     this.server?.stop(true);
     this.server = null;
     rmSync(socketPath(this.home), { force: true });
@@ -155,9 +192,10 @@ export class DaemonServer {
     this.releaseLock();
   }
 
-  private broadcast(e: DaemonEvent): void {
-    const frame = JSON.stringify(e) + "\n";
-    for (const c of this.conns) if (c.subscribed) c.write(frame);
+  private broadcast(event: DaemonEvent): void {
+    const frame = JSON.stringify(event) + "\n";
+
+    for (const connection of this.connections) if (connection.subscribed) connection.write(frame);
     this.scheduleIdleCheck();
   }
 
@@ -166,7 +204,7 @@ export class DaemonServer {
     if (this.idleExitMs <= 0) return;
     if (this.idleTimer) clearTimeout(this.idleTimer);
     this.idleTimer = setTimeout(() => {
-      if (this.conns.size === 0 && !this.core.hasPendingSessions()) {
+      if (this.connections.size === 0 && !this.core.hasPendingSessions()) {
         this.stop();
         this.onIdleExit();
       } else {
@@ -175,76 +213,147 @@ export class DaemonServer {
     }, this.idleExitMs);
   }
 
-  private async handleLine(conn: Conn, line: string): Promise<void> {
-    let req: Request;
+  private async respondToRequestLine(connection: Connection, line: string): Promise<void> {
+    let request: Request;
+
     try {
-      req = JSON.parse(line) as Request;
+      request = JSON.parse(line) as Request;
     } catch {
-      conn.write(JSON.stringify({ id: -1, error: { code: "bad_json", message: "unparseable request" } }) + "\n");
+      connection.write(
+        JSON.stringify({ id: -1, error: { code: "bad_json", message: "unparseable request" } }) +
+          "\n",
+      );
+
       return;
     }
     try {
-      const result = await this.dispatch(conn, req);
-      conn.write(JSON.stringify({ id: req.id, result }) + "\n");
+      const result = await this.dispatch(connection, request);
+
+      connection.write(JSON.stringify({ id: request.id, result }) + "\n");
     } catch (err) {
       const code = err instanceof DaemonError ? err.code : "internal";
       const message = err instanceof Error ? err.message : String(err);
-      conn.write(JSON.stringify({ id: req.id, error: { code, message } }) + "\n");
+
+      connection.write(JSON.stringify({ id: request.id, error: { code, message } }) + "\n");
     }
   }
 
-  private async dispatch(conn: Conn, req: Request): Promise<unknown> {
+  private readonly handlers: Record<MethodName, MethodHandler> = {
+    "daemon.ping": () => ({ pid: process.pid }),
+    "daemon.hello": (connection, request) => {
+      connection.role = parseParams("daemon.hello", request.params).role;
+
+      return {};
+    },
+    "daemon.shutdown": () => {
+      setTimeout(() => {
+        this.stop();
+        this.onIdleExit();
+      }, 10);
+
+      return {};
+    },
+    "events.subscribe": (connection) => {
+      connection.subscribed = true;
+
+      return {};
+    },
+    "session.create": (_connection, request) => {
+      const params = parseParams("session.create", request.params);
+
+      return this.core.sessionCreate({ workspace: params.workspace, artifact: params.artifact });
+    },
+    "session.get": (_connection, request) =>
+      this.core.sessionGet(parseParams("session.get", request.params).id),
+    "session.list": (_connection, request) =>
+      this.core.sessionList(parseParams("session.list", request.params).filter),
+    "session.wait": (_connection, request) => {
+      const params = parseParams("session.wait", request.params);
+
+      return this.core.sessionWait(params.id, params.timeoutMs);
+    },
+    "session.annotate": (_connection, request) => {
+      const params = parseParams("session.annotate", request.params);
+
+      return this.core.sessionAnnotate(params.id, params.annotation, params.authorName);
+    },
+    "session.removeAnnotation": (_connection, request) => {
+      const params = parseParams("session.removeAnnotation", request.params);
+
+      return this.core.sessionRemoveAnnotation(params.id, params.annotationId);
+    },
+    "session.setWorkingCopy": (_connection, request) => {
+      const params = parseParams("session.setWorkingCopy", request.params);
+
+      return this.core.sessionSetWorkingCopy(params.id, params.workingCopy);
+    },
+    "session.setViewed": (_connection, request) => {
+      const params = parseParams("session.setViewed", request.params);
+
+      return this.core.sessionSetViewed(params.id, params.viewedPaths);
+    },
+    "session.refreshDiff": (_connection, request) => {
+      const params = parseParams("session.refreshDiff", request.params);
+
+      return this.core.sessionRefreshDiff(params.id);
+    },
+    "session.setShareId": (_connection, request) => {
+      const params = parseParams("session.setShareId", request.params);
+
+      return this.core.sessionSetShareId(params.id, params.shareId);
+    },
+    "session.delete": (_connection, request) => {
+      this.core.sessionDelete(parseParams("session.delete", request.params).id);
+
+      return {};
+    },
+    "session.mergeShared": (_connection, request) => {
+      const params = parseParams("session.mergeShared", request.params);
+
+      return this.core.sessionMergeShared(params.id, {
+        annotations: params.annotations,
+        participants: params.participants,
+      });
+    },
+    "session.resolve": (_connection, request) => {
+      const params = parseParams("session.resolve", request.params);
+
+      return this.core.sessionResolve(params.id, params.verdictKind, params.summary);
+    },
+    "session.submitRevision": (_connection, request) => {
+      const params = parseParams("session.submitRevision", request.params);
+
+      return this.core.sessionSubmitRevision(
+        params.id,
+        params.content,
+        params.addressedAnnotationIds,
+      );
+    },
+    "herdr.getTab": (_connection, request) =>
+      this.core.herdrGetTab(parseParams("herdr.getTab", request.params).id),
+    "herdr.setTab": (_connection, request) => {
+      const params = parseParams("herdr.setTab", request.params);
+
+      this.core.herdrSetTab(params.id, { tabId: params.tabId, paneId: params.paneId });
+
+      return {};
+    },
+  };
+
+  private async dispatch(connection: Connection, request: Request): Promise<unknown> {
     // The wire is untrusted JSON: validate before DaemonCore sees anything.
-    if (typeof req.method !== "string" || !isKnownMethod(req.method)) {
-      throw new DaemonError("unknown_method", `unknown method ${String(req.method)}`);
+    if (typeof request.method !== "string" || !isKnownMethod(request.method)) {
+      throw new DaemonError("unknown_method", `unknown method ${String(request.method)}`);
     }
-    const core = this.core;
-    switch (req.method) {
-      case "daemon.ping":
-        return { pid: process.pid };
-      case "daemon.shutdown":
-        setTimeout(() => {
-          this.stop();
-          this.onIdleExit();
-        }, 10);
-        return {};
-      case "events.subscribe":
-        conn.subscribed = true;
-        return {};
-      case "session.create": {
-        const p = parseParams("session.create", req.params);
-        return core.sessionCreate({ workspace: p.workspace, artifact: p.artifact });
-      }
-      case "session.get":
-        return core.sessionGet(parseParams("session.get", req.params).id);
-      case "session.list":
-        return core.sessionList(parseParams("session.list", req.params).filter);
-      case "session.wait": {
-        const p = parseParams("session.wait", req.params);
-        return core.sessionWait(p.id, p.timeoutMs);
-      }
-      case "session.annotate": {
-        const p = parseParams("session.annotate", req.params);
-        return core.sessionAnnotate(p.id, p.annotation);
-      }
-      case "session.removeAnnotation": {
-        const p = parseParams("session.removeAnnotation", req.params);
-        return core.sessionRemoveAnnotation(p.id, p.annotationId);
-      }
-      case "session.setWorkingCopy": {
-        const p = parseParams("session.setWorkingCopy", req.params);
-        return core.sessionSetWorkingCopy(p.id, p.workingCopy);
-      }
-      case "session.resolve": {
-        const p = parseParams("session.resolve", req.params);
-        return core.sessionResolve(p.id, p.verdictKind, p.summary);
-      }
-      case "session.submitRevision": {
-        const p = parseParams("session.submitRevision", req.params);
-        return core.sessionSubmitRevision(p.id, p.content);
-      }
-      default:
-        throw new DaemonError("unknown_method", `unknown method ${req.method}`);
+    // Capability gate: a capped role (a review-side agent) cannot escalate past
+    // read + annotate, whatever verb it sends.
+    if (!roleAllowsMethod(connection.role, request.method)) {
+      throw new DaemonError("forbidden", `role ${connection.role} cannot call ${request.method}`);
     }
+    if (!Object.hasOwn(this.handlers, request.method)) {
+      throw new DaemonError("unknown_method", `unknown method ${request.method}`);
+    }
+
+    return this.handlers[request.method](connection, request);
   }
 }