@cueloop/daemon 0.1.0-alpha.0 → 0.1.0-alpha.100

package/src/capabilities.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import { asDaemonRole, DEFAULT_ROLE, roleAllowsMethod } from "./capabilities";
+import type { MethodName } from "./validate";
+
+describe("roleAllowsMethod", () => {
+  test("the owner may call every primitive", () => {
+    // Assert
+    const owned: MethodName[] = ["session.sendMessage", "session.submitRevision", "session.delete"];
+
+    for (const method of owned) expect(roleAllowsMethod("owner", method)).toBe(true);
+  });
+
+  test("a capped role may read and annotate but not escalate", () => {
+    // Assert - allowed
+    const open: MethodName[] = ["session.get", "session.list", "session.wait", "session.annotate"];
+
+    for (const method of open) expect(roleAllowsMethod("agent", method)).toBe(true);
+    // Assert - denied
+    const owned: MethodName[] = [
+      "session.sendMessage",
+      "session.submitRevision",
+      "session.setWorkingCopy",
+      "session.delete",
+      "session.setShares",
+      "session.refreshDiff",
+      "session.create",
+      "session.navigate",
+      "session.branch",
+      "session.switch",
+      "session.label",
+      "session.fork",
+    ];
+
+    for (const method of owned) expect(roleAllowsMethod("agent", method)).toBe(false);
+    expect(roleAllowsMethod("collaborator", "session.sendMessage")).toBe(false);
+    // removal and naming are open to every role; the primitive itself scopes a
+    // non-owner to the author it acts as
+    expect(roleAllowsMethod("agent", "session.removeAnnotation")).toBe(true);
+    expect(roleAllowsMethod("agent", "session.setParticipantName")).toBe(true);
+  });
+
+  test("a connection starts as a collaborator, never as the owner", () => {
+    // Assert
+    expect(DEFAULT_ROLE).toBe("collaborator");
+  });
+});
+
+describe("asDaemonRole", () => {
+  test("passes owner and collaborator through and caps anything unknown to agent", () => {
+    // Assert
+    expect(asDaemonRole("owner")).toBe("owner");
+    expect(asDaemonRole("collaborator")).toBe("collaborator");
+    expect(asDaemonRole("agent")).toBe("agent");
+    expect(asDaemonRole("root")).toBe("agent");
+    expect(asDaemonRole(undefined)).toBe("agent");
+  });
+});

package/src/capabilities.ts

@@ -0,0 +1,95 @@
+/**
+ * Daemon roles: which primitives a connection may call. A connection is a
+ * collaborator until it proves ownership with the owner token in daemon.hello
+ * - never an owner by default. The owner (the local planner) may call every
+ * primitive; a collaborator or a review-side agent is capped to reading the
+ * session and adding comments, so a bring-your-own agent cannot resolve,
+ * rewrite, cut, share, or delete (ADR 0009). The table below is exhaustive
+ * over the primitive schemas: adding a primitive without naming its roles
+ * does not compile.
+ */
+
+import * as v from "valibot";
+import type { MethodName } from "./validate";
+
+export type DaemonRole = "owner" | "collaborator" | "agent";
+
+/** Who may call a primitive: everyone, or the owner only. */
+type Audience = "any" | "owner";
+
+const PRIMITIVE_ROLES = {
+  "agent.configure": "owner",
+  "agent.get": "owner",
+  "agent.prompt": "owner",
+  "agent.cancel": "owner",
+  "agent.comment": "owner",
+  "agent.reply": "owner",
+  "agent.permission": "owner",
+  "daemon.ping": "any",
+  "daemon.hello": "any",
+  "daemon.shutdown": "owner",
+  "events.subscribe": "any",
+  "session.create": "owner",
+  "session.get": "any",
+  "session.list": "any",
+  "session.wait": "any",
+  "session.annotate": "any",
+  "session.comment": "any",
+  // any role may call it; a non-owner must act on behalf of an author and stays scoped to it
+  "session.removeAnnotation": "any",
+  "session.setParticipantName": "any",
+  "session.setWorkingCopy": "owner",
+  "session.cutBlock": "owner",
+  "session.restoreBlock": "owner",
+  "session.curate": "owner",
+  "session.setViewed": "owner",
+  "session.setTitle": "owner",
+  // reading the local working tree is the owner's alone; a share carries no repo to read
+  "session.projectFiles": "owner",
+  "session.fileContents": "owner",
+  // the launch repo is the local owner's; a share has no local repo to browse
+  "repo.files": "owner",
+  "repo.fileContents": "owner",
+  "repo.changes": "owner",
+  "repo.diff": "owner",
+  "session.workbench": "owner",
+  "session.workbenchReview": "owner",
+  // the tree is the owner's: collaborators comment on the branch a share follows
+  "session.navigate": "owner",
+  "session.branch": "owner",
+  "session.switch": "owner",
+  "session.label": "owner",
+  "session.fork": "owner",
+  "session.refreshDiff": "owner",
+  "session.setShares": "owner",
+  "session.delete": "owner",
+  "session.mergeShared": "owner",
+  "session.sendMessage": "owner",
+  "harness.bind": "owner",
+  "harness.getBinding": "owner",
+  "harness.bindingsForSession": "owner",
+  "harness.consumeApprovedRetry": "owner",
+  "delivery.pending": "owner",
+  "delivery.acknowledge": "owner",
+  "session.submitRevision": "owner",
+  "herdr.getThreadSurface": "owner",
+  "herdr.setThreadSurface": "owner",
+  "ghostty.getThreadSurface": "owner",
+  "ghostty.setThreadSurface": "owner",
+  "ghostty.claimThreadSurface": "owner",
+  "ghostty.releaseThreadSurface": "owner",
+} as const satisfies Record<MethodName, Audience>;
+
+/** Whether `role` may call `method`. */
+export function roleAllowsMethod(role: DaemonRole, method: MethodName): boolean {
+  return role === "owner" || PRIMITIVE_ROLES[method] === "any";
+}
+
+/** The role a connection starts with, before any proof. */
+export const DEFAULT_ROLE: DaemonRole = "collaborator";
+
+export function asDaemonRole(value: Parameters<typeof v.safeParse>[1]): DaemonRole {
+  const result = v.safeParse(v.picklist(["owner", "collaborator"]), value);
+
+  return result.success ? result.output : "agent";
+}

package/src/client-errors.ts

@@ -0,0 +1,24 @@
+/** Request failure certainty never promises rollback after bytes may have reached the daemon. */
+export type DaemonRequestCertainty = "not_sent" | "unknown";
+
+/** Transport failures are distinct from daemon rejection codes and domain terminal outcomes. */
+export class DaemonTransportError extends Error {
+  readonly _tag = "DaemonTransportError";
+
+  constructor(
+    readonly kind: "protocol" | "connection" | "timeout" | "cancelled",
+    message: string,
+    readonly certainty: DaemonRequestCertainty,
+    readonly method?: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "DaemonTransportError";
+  }
+}
+
+/** Local cancellation stops observation; it does not cancel daemon-owned work. */
+export interface DaemonRequestOptions {
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}

package/src/client-reliability.test.ts

@@ -0,0 +1,189 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import * as v from "valibot";
+import { DaemonClient } from "./client";
+import { DAEMON_VERSION } from "./version";
+import { LineBuffer, parseRequestFrame } from "./protocol";
+import { socketPath } from "./paths";
+
+test("malformed response results reject promptly and leave the connection usable", async () => {
+  const home = mkdtempSync(join(tmpdir(), "cueloop-client-contract-"));
+  const buffers = new Map<object, LineBuffer>();
+  const server = Bun.listen({
+    unix: socketPath(home),
+    socket: {
+      open(socket) {
+        buffers.set(socket, new LineBuffer());
+      },
+      data(socket, data) {
+        buffers.get(socket)!.push(data.toString(), (line) => {
+          const request = parseRequestFrame(line);
+          const result =
+            request.method === "daemon.ping"
+              ? { pid: process.pid, version: DAEMON_VERSION }
+              : request.method === "daemon.hello"
+                ? {}
+                : "malformed";
+
+          socket.write(JSON.stringify({ id: request.id, result }) + "\n");
+        });
+      },
+      close(socket) {
+        buffers.delete(socket);
+      },
+    },
+  });
+  let client: DaemonClient | undefined;
+
+  try {
+    client = await DaemonClient.connect({ home });
+    await expect(client.request("test.number", {}, v.number(), 100)).rejects.toMatchObject({
+      _tag: "DaemonTransportError",
+      kind: "protocol",
+      certainty: "unknown",
+    });
+    await expect(
+      client.request(
+        "test.transform",
+        {},
+        v.pipe(
+          v.string(),
+          v.transform(() => {
+            throw new Error("Invalid transformation");
+          }),
+        ),
+        100,
+      ),
+    ).rejects.toMatchObject({ kind: "protocol", certainty: "unknown" });
+    expect((await client.ping()).pid).toBe(process.pid);
+  } finally {
+    client?.close();
+    server.stop(true);
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("deadlines, local abort and close reject outstanding requests without cancelling daemon work", async () => {
+  const home = mkdtempSync(join(tmpdir(), "cueloop-client-cancel-"));
+  const buffers = new Map<object, LineBuffer>();
+  const work: number[] = [];
+  const server = Bun.listen({
+    unix: socketPath(home),
+    socket: {
+      open(socket) {
+        buffers.set(socket, new LineBuffer());
+      },
+      data(socket, data) {
+        buffers.get(socket)!.push(data.toString(), (line) => {
+          const request = parseRequestFrame(line);
+
+          if (request.method === "work") {
+            work.push(request.id);
+
+            return;
+          }
+          socket.write(
+            JSON.stringify({
+              id: request.id,
+              result:
+                request.method === "daemon.ping"
+                  ? { pid: process.pid, version: DAEMON_VERSION }
+                  : {},
+            }) + "\n",
+          );
+        });
+      },
+      close(socket) {
+        buffers.delete(socket);
+      },
+    },
+  });
+  const client = await DaemonClient.connect({ home });
+
+  try {
+    const alreadyCancelled = new AbortController();
+
+    alreadyCancelled.abort();
+    await expect(
+      client.request("work", {}, v.number(), { signal: alreadyCancelled.signal }),
+    ).rejects.toMatchObject({ kind: "cancelled", certainty: "not_sent" });
+    await expect(client.request("work", {}, v.number(), { timeoutMs: 10 })).rejects.toMatchObject({
+      kind: "timeout",
+      certainty: "unknown",
+    });
+    expect(work).toHaveLength(1);
+    const controller = new AbortController();
+    const waiting = client.request("work", {}, v.number(), { signal: controller.signal });
+
+    await client.ping();
+    controller.abort();
+    await expect(waiting).rejects.toMatchObject({ kind: "cancelled", certainty: "unknown" });
+    expect(work).toHaveLength(2);
+    const pending = client.request("work", {}, v.number());
+
+    client.close();
+    await expect(pending).rejects.toMatchObject({ kind: "connection", certainty: "unknown" });
+    await expect(client.ping()).rejects.toMatchObject({
+      kind: "connection",
+      certainty: "not_sent",
+    });
+  } finally {
+    client.close();
+    server.stop(true);
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("malformed frames reject all pending requests as protocol failures", async () => {
+  const home = mkdtempSync(join(tmpdir(), "cueloop-client-frame-"));
+  const buffers = new Map<object, LineBuffer>();
+  const server = Bun.listen({
+    unix: socketPath(home),
+    socket: {
+      open(socket) {
+        buffers.set(socket, new LineBuffer());
+      },
+      data(socket, data) {
+        buffers.get(socket)!.push(data.toString(), (line) => {
+          const request = parseRequestFrame(line);
+
+          if (request.method === "bad-frame") {
+            socket.write("{broken\n");
+
+            return;
+          }
+          socket.write(
+            JSON.stringify({
+              id: request.id,
+              result:
+                request.method === "daemon.ping"
+                  ? { pid: process.pid, version: DAEMON_VERSION }
+                  : {},
+            }) + "\n",
+          );
+        });
+      },
+      close(socket) {
+        buffers.delete(socket);
+      },
+    },
+  });
+  const client = await DaemonClient.connect({ home });
+
+  try {
+    await expect(client.request("bad-frame", {}, v.number())).rejects.toMatchObject({
+      kind: "protocol",
+      certainty: "unknown",
+    });
+    await expect(client.ping()).rejects.toMatchObject({
+      kind: "connection",
+      certainty: "not_sent",
+    });
+  } finally {
+    client.close();
+    server.stop(true);
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/client.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { daemonSpawnCommand } from "./client";
+
+describe("daemonSpawnCommand", () => {
+  test("re-execs the binary as `daemon` when compiled (bun virtual-fs markers)", () => {
+    for (const moduleUrl of [
+      "file:///$bunfs/root/cueloop",
+      "file:///B:/~BUN/root/cueloop",
+      "file:///B:/%7EBUN/root/cueloop",
+    ]) {
+      expect(daemonSpawnCommand("/usr/local/bin/cueloop", moduleUrl)).toEqual([
+        "/usr/local/bin/cueloop",
+        "daemon",
+        "--autostart",
+      ]);
+    }
+  });
+
+  test("runs main.ts with bun from source", () => {
+    expect(
+      daemonSpawnCommand("/path/to/bun", "file:///repo/packages/daemon/src/client.ts"),
+    ).toEqual(["/path/to/bun", "run", "/repo/packages/daemon/src/main.ts"]);
+  });
+});
+
+test("published daemon starts itself unless the CLI supplies its real entry path", () => {
+  const published = "file:///project/node_modules/@cueloop/daemon/src/client.ts";
+
+  expect(daemonSpawnCommand("bun", published, false)).toEqual([
+    "bun",
+    "run",
+    "/project/node_modules/@cueloop/daemon/src/main.ts",
+  ]);
+  expect(
+    daemonSpawnCommand("bun", published, false, "/project/node_modules/cueloop/src/main.ts"),
+  ).toEqual(["bun", "run", "/project/node_modules/cueloop/src/main.ts", "daemon", "--autostart"]);
+});