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

package/src/server.ts

@@ -1,19 +1,31 @@
 /**
  * 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 { roleAllowsMethod, type DaemonRole } from "./capabilities";
 import { isKnownMethod, parseParams } from "./validate";
-import { LineBuffer, type Request } from "./protocol";
+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;
 }
 
 export interface DaemonOptions {
@@ -33,20 +45,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));
   }
 
   /**
@@ -118,24 +130,37 @@ export class DaemonServer {
     // 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() {},
       },
@@ -155,9 +180,9 @@ 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 +191,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,33 +200,44 @@ 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 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)}`);
+    }
+    // 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}`);
     }
     const core = this.core;
-    switch (req.method) {
+    switch (request.method) {
       case "daemon.ping":
         return { pid: process.pid };
+      case "daemon.hello":
+        connection.role = parseParams("daemon.hello", request.params).role;
+        return {};
       case "daemon.shutdown":
         setTimeout(() => {
           this.stop();
@@ -209,42 +245,68 @@ export class DaemonServer {
         }, 10);
         return {};
       case "events.subscribe":
-        conn.subscribed = true;
+        connection.subscribed = true;
         return {};
       case "session.create": {
-        const p = parseParams("session.create", req.params);
-        return core.sessionCreate({ workspace: p.workspace, artifact: p.artifact });
+        const params = parseParams("session.create", request.params);
+        return core.sessionCreate({ workspace: params.workspace, artifact: params.artifact });
       }
       case "session.get":
-        return core.sessionGet(parseParams("session.get", req.params).id);
+        return core.sessionGet(parseParams("session.get", request.params).id);
       case "session.list":
-        return core.sessionList(parseParams("session.list", req.params).filter);
+        return core.sessionList(parseParams("session.list", request.params).filter);
       case "session.wait": {
-        const p = parseParams("session.wait", req.params);
-        return core.sessionWait(p.id, p.timeoutMs);
+        const params = parseParams("session.wait", request.params);
+        return core.sessionWait(params.id, params.timeoutMs);
       }
       case "session.annotate": {
-        const p = parseParams("session.annotate", req.params);
-        return core.sessionAnnotate(p.id, p.annotation);
+        const params = parseParams("session.annotate", request.params);
+        return core.sessionAnnotate(params.id, params.annotation, params.authorName);
       }
       case "session.removeAnnotation": {
-        const p = parseParams("session.removeAnnotation", req.params);
-        return core.sessionRemoveAnnotation(p.id, p.annotationId);
+        const params = parseParams("session.removeAnnotation", request.params);
+        return core.sessionRemoveAnnotation(params.id, params.annotationId);
       }
       case "session.setWorkingCopy": {
-        const p = parseParams("session.setWorkingCopy", req.params);
-        return core.sessionSetWorkingCopy(p.id, p.workingCopy);
+        const params = parseParams("session.setWorkingCopy", request.params);
+        return core.sessionSetWorkingCopy(params.id, params.workingCopy);
+      }
+      case "session.setViewed": {
+        const params = parseParams("session.setViewed", request.params);
+        return core.sessionSetViewed(params.id, params.viewedPaths);
+      }
+      case "session.setShareId": {
+        const params = parseParams("session.setShareId", request.params);
+        return core.sessionSetShareId(params.id, params.shareId);
+      }
+      case "session.delete": {
+        core.sessionDelete(parseParams("session.delete", request.params).id);
+        return {};
+      }
+      case "session.mergeShared": {
+        const params = parseParams("session.mergeShared", request.params);
+        return core.sessionMergeShared(params.id, {
+          annotations: params.annotations,
+          participants: params.participants,
+        });
       }
       case "session.resolve": {
-        const p = parseParams("session.resolve", req.params);
-        return core.sessionResolve(p.id, p.verdictKind, p.summary);
+        const params = parseParams("session.resolve", request.params);
+        return core.sessionResolve(params.id, params.verdictKind, params.summary);
       }
       case "session.submitRevision": {
-        const p = parseParams("session.submitRevision", req.params);
-        return core.sessionSubmitRevision(p.id, p.content);
+        const params = parseParams("session.submitRevision", request.params);
+        return core.sessionSubmitRevision(params.id, params.content, params.addressedAnnotationIds);
+      }
+      case "herdr.getTab":
+        return core.herdrGetTab(parseParams("herdr.getTab", request.params).id);
+      case "herdr.setTab": {
+        const params = parseParams("herdr.setTab", request.params);
+        core.herdrSetTab(params.id, { tabId: params.tabId, paneId: params.paneId });
+        return {};
       }
       default:
-        throw new DaemonError("unknown_method", `unknown method ${req.method}`);
+        throw new DaemonError("unknown_method", `unknown method ${request.method}`);
     }
   }
 }

package/src/share-blob.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { gzipSync } from "node:zlib";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Artifact, WorkspaceKey } from "@cueloop/schema";
+import { DaemonCore } from "./api";
+import { MAX_BLOB_BYTES, packSessionBlob, unpackSessionBlob } from "./share-blob";
+
+const WS: WorkspaceKey = { repoRoot: "/repo", branch: "main" };
+const PLAN: Artifact = { type: "plan", content: "# Plan\n\nDo the thing.\n", meta: {} };
+
+let home: string;
+let core: DaemonCore;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-blob-"));
+  core = new DaemonCore(home);
+});
+afterEach(() => rmSync(home, { recursive: true, force: true }));
+
+describe("share blob roundtrip", () => {
+  test("pack then unpack restores the session with its annotations", () => {
+    // Arrange
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const annotated = core.sessionAnnotate(session.id, {
+      id: "a_1",
+      kind: "comment",
+      anchor: { quote: "the thing", prefix: "", suffix: "" },
+      body: "why this?",
+    });
+
+    // Act
+    const restored = unpackSessionBlob(packSessionBlob(annotated));
+
+    // Assert
+    expect(restored).toEqual(annotated);
+  });
+});
+
+describe("unpack rejects bad input", () => {
+  test("caps the decompressed size, so a compression bomb throws", () => {
+    // Arrange: tiny gzip, huge inflation - the decompression-bomb shape
+    const bomb = gzipSync(Buffer.alloc(MAX_BLOB_BYTES + 1, 0x61));
+
+    // Act / Assert
+    expect(() => unpackSessionBlob(bomb)).toThrow(/exceeds|maxOutputLength/i);
+  });
+
+  test("throws on bytes that are not gzip", () => {
+    // Act / Assert
+    expect(() => unpackSessionBlob(Buffer.from("not gzip at all"))).toThrow(/gzip/i);
+  });
+
+  test("throws on a shape that is not a session", () => {
+    // Arrange
+    const notASession = gzipSync(Buffer.from(JSON.stringify({ hello: "world" })));
+
+    // Act / Assert
+    expect(() => unpackSessionBlob(notASession)).toThrow(/not a valid session/i);
+  });
+});

package/src/share-blob.ts

@@ -0,0 +1,51 @@
+/**
+ * The share-blob wire format: how a ReviewSession travels from `cueloop share`
+ * to the gateway. The planner's CLI packs (this is the only thing it can do -
+ * it holds no encryption key); the gateway unpacks, then encrypts for R2.
+ *
+ * Format is gzip(JSON). Unpack is the untrusted boundary - the bytes come off
+ * an SSH channel from anyone who can reach the `share` user - so it caps the
+ * decompressed size (a decompression-bomb guard) and runs the same record
+ * validator the daemon store uses, never trusting the shape.
+ */
+
+import { gzipSync, gunzipSync } from "node:zlib";
+import type { ReviewSession } from "@cueloop/schema";
+import { validateSessionRecord } from "./validate";
+
+/** Decompressed ceiling for one shared session (ADR 0004's payload cap). */
+export const MAX_BLOB_BYTES = 1024 * 1024;
+
+/** The SSH username `cueloop share` connects as to upload; the gateway routes on it. */
+export const SHARE_UPLOAD_USER = "share";
+
+/** Where shares live, in one place: the client uploads here, the gateway prints it. */
+export const DEFAULT_SHARE_HOST = "cueloop.dev";
+export const DEFAULT_SHARE_PORT = 22;
+
+/** Serialise + compress a session for upload. */
+export function packSessionBlob(session: ReviewSession): Buffer {
+  return gzipSync(Buffer.from(JSON.stringify(session), "utf8"));
+}
+
+/** Decompress + validate an uploaded blob, or throw a precise reason. */
+export function unpackSessionBlob(bytes: Uint8Array): ReviewSession {
+  let json: string;
+  try {
+    json = gunzipSync(bytes, { maxOutputLength: MAX_BLOB_BYTES }).toString("utf8");
+  } catch (err) {
+    throw new Error(
+      `blob is not valid gzip or exceeds ${MAX_BLOB_BYTES} bytes: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err },
+    );
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(json);
+  } catch {
+    throw new Error("blob is not valid JSON");
+  }
+  const parsed = validateSessionRecord(raw);
+  if (!parsed.ok) throw new Error(`blob is not a valid session: ${parsed.error}`);
+  return parsed.value as ReviewSession;
+}

package/src/single-instance.test.ts

@@ -1,5 +1,5 @@
 /**
- * Single-instance guarantee (#14): one daemon per home. Two daemons over one
+ * Single-instance guarantee: one daemon per home. Two daemons over one
  * state directory means divergent in-memory sessions and clients seeing
  * whichever half they connect to.
  */
@@ -23,33 +23,39 @@ beforeEach(() => {
   home = mkdtempSync(join(tmpdir(), "cueloop-lock-"));
 });
 afterEach(() => {
-  for (const s of servers.splice(0)) s.stop();
+  for (const runningServer of servers.splice(0)) runningServer.stop();
   rmSync(home, { recursive: true, force: true });
 });
 
 function server(): DaemonServer {
-  const s = new DaemonServer({ home, idleExitMs: 0 });
-  servers.push(s);
-  return s;
+  const daemonServer = new DaemonServer({ home, idleExitMs: 0 });
+  servers.push(daemonServer);
+  return daemonServer;
 }
 
 describe("one daemon per home", () => {
   test("the second start is refused instead of stealing the socket", () => {
+    // Arrange
     const first = server();
     const path = first.start();
     expect(path).toBe(socketPath(home));
     const second = server();
+
+    // Assert
     expect(second.start()).toBeNull();
     // the winner's socket survives untouched
     expect(existsSync(path!)).toBe(true);
   });
 
   test("clients keep talking to the one live daemon after a refused start", async () => {
+    // Arrange
     const first = server();
     first.start();
     const created = first.core.sessionCreate({ workspace: WS, artifact: PLAN });
     server().start(); // refused
     const client = await DaemonClient.connect({ home });
+
+    // Assert
     try {
       // no split brain: the session created on the winner is visible
       expect((await client.sessionGet(created.id)).id).toBe(created.id);
@@ -60,36 +66,47 @@ describe("one daemon per home", () => {
   });
 
   test("a stale lock from a crashed daemon is reclaimed", () => {
+    // Arrange
     // a pid that cannot be running (init is never a cueloop daemon, and this
     // simulates the record a crashed process leaves behind)
     writeFileSync(lockPath(home), "999999");
-    const s = server();
-    expect(s.start()).toBe(socketPath(home));
+    const daemonServer = server();
+
+    // Assert
+    expect(daemonServer.start()).toBe(socketPath(home));
   });
 
   test("stopping releases the lock so a restart works", () => {
+    // Arrange
     const first = server();
     first.start();
+
+    // Act
     first.stop();
+
+    // Assert
     expect(existsSync(lockPath(home))).toBe(false);
     const second = server();
     expect(second.start()).toBe(socketPath(home));
   });
 
   test("concurrent autostarts converge on a single daemon", async () => {
+    // Act
     // several clients race to autostart; all must end up on the same daemon
     const clients = await Promise.all([
       DaemonClient.connect({ home, autostart: true }),
       DaemonClient.connect({ home, autostart: true }),
       DaemonClient.connect({ home, autostart: true }),
     ]);
+
+    // Assert
     try {
-      const pids = await Promise.all(clients.map((c) => c.ping()));
-      const unique = new Set(pids.map((p) => p.pid));
+      const pids = await Promise.all(clients.map((client) => client.ping()));
+      const unique = new Set(pids.map((ping) => ping.pid));
       expect(unique.size).toBe(1);
       // and state is shared: one client's session is visible to the others
-      const s = await clients[0]!.sessionCreate(WS, PLAN);
-      expect((await clients[2]!.sessionGet(s.id)).id).toBe(s.id);
+      const session = await clients[0]!.sessionCreate(WS, PLAN);
+      expect((await clients[2]!.sessionGet(session.id)).id).toBe(session.id);
     } finally {
       for (const c of clients) c.close();
       // the autostarted daemon is not one of `servers` - shut it down

package/src/store.ts

@@ -1,5 +1,5 @@
 /**
- * Session persistence (#14): one JSON document per session, every write
+ * Session persistence: one JSON document per session, every write
  * through a temp file + atomic rename so a crash mid-write can never leave
  * a corrupt record. Recovery is a read-only scan; records that fail to
  * parse are skipped and reported, never deleted.
@@ -49,15 +49,17 @@ export class SessionStore {
   }
 
   list(): ReviewSession[] {
-    return [...this.sessions.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    return [...this.sessions.values()].sort((left, right) =>
+      left.createdAt.localeCompare(right.createdAt),
+    );
   }
 
   upsert(session: ReviewSession): void {
     this.sessions.set(session.id, session);
     const path = join(this.dir, `${session.id}.json`);
-    const tmp = path + ".tmp";
-    writeFileSync(tmp, JSON.stringify(session, null, 2));
-    renameSync(tmp, path);
+    const tempPath = path + ".tmp";
+    writeFileSync(tempPath, JSON.stringify(session, null, 2));
+    renameSync(tempPath, path);
   }
 
   delete(id: string): boolean {