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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.39",
+  "version": "0.1.0-alpha.40",
   "description": "The cueloop session daemon and its client: socket protocol, atomic store, resumable waits",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -22,13 +22,14 @@
     "./client": "./src/client.ts",
     "./review": "./src/review.ts",
     "./herdr-pane": "./src/herdr-pane.ts",
+    "./herdr-split": "./src/herdr-split.ts",
     "./share-blob": "./src/share-blob.ts"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.39",
+    "@cueloop/schema": "0.1.0-alpha.40",
     "valibot": "^1.4.2"
   },
   "engines": {

package/src/capabilities.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { asDaemonRole, roleAllowsMethod } from "./capabilities";
+
+describe("roleAllowsMethod", () => {
+  test("the owner may call every verb", () => {
+    // Assert
+    for (const method of ["session.resolve", "session.submitRevision", "session.delete"])
+      expect(roleAllowsMethod("owner", method)).toBe(true);
+  });
+
+  test("a capped role may read and annotate but not escalate", () => {
+    // Assert - allowed
+    for (const method of ["session.get", "session.list", "session.wait", "session.annotate"])
+      expect(roleAllowsMethod("agent", method)).toBe(true);
+    // Assert - denied
+    for (const method of [
+      "session.resolve",
+      "session.submitRevision",
+      "session.setWorkingCopy",
+      "session.delete",
+      "session.setShareId",
+    ])
+      expect(roleAllowsMethod("agent", method)).toBe(false);
+    expect(roleAllowsMethod("collaborator", "session.resolve")).toBe(false);
+  });
+});
+
+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,30 @@
+/**
+ * Daemon role capabilities: which socket methods a connection may call. The
+ * owner (the local planner) may call everything; a collaborator or a review-side
+ * agent is capped to reading the session and adding annotations, so a bring-your-
+ * own agent literally cannot resolve, rewrite, cut, share, or delete (ADR 0009).
+ * This is the single source of truth the server dispatch enforces.
+ */
+
+export type DaemonRole = "owner" | "collaborator" | "agent";
+
+/** Methods a non-owner role may call: read the session and annotate, plus connection plumbing. */
+const NON_OWNER_METHODS = new Set<string>([
+  "daemon.ping",
+  "daemon.hello",
+  "events.subscribe",
+  "session.get",
+  "session.list",
+  "session.wait",
+  "session.annotate",
+]);
+
+/** Whether `role` may call `method`. The owner may call anything; others are capped to read + annotate. */
+export function roleAllowsMethod(role: DaemonRole, method: string): boolean {
+  return role === "owner" || NON_OWNER_METHODS.has(method);
+}
+
+/** Parse an untrusted role string, defaulting unknown values to the capped "agent". */
+export function asDaemonRole(value: unknown): DaemonRole {
+  return value === "owner" || value === "collaborator" ? value : "agent";
+}

package/src/client.ts

@@ -14,6 +14,7 @@ import type {
   WorkspaceKey,
 } from "@cueloop/schema";
 import { BackpressureWriter, LineBuffer, type EventFrame, type Response } from "./protocol";
+import type { DaemonRole } from "./capabilities";
 import type { HerdrTabHandle } from "./herdr-tab-store";
 import { cueloopHome, socketPath } from "./paths";
 
@@ -23,6 +24,8 @@ export interface ConnectOptions {
   home?: string;
   /** Spawn the daemon when the socket is not alive. */
   autostart?: boolean;
+  /** Capability role for this connection; a review-side agent connects capped. Defaults to owner. */
+  role?: DaemonRole;
 }
 
 type PendingRequest = { resolve: (value: unknown) => void; reject: (error: Error) => void };
@@ -65,11 +68,13 @@ export class DaemonClient implements SessionClient {
   private nextId = 1;
   private eventListeners = new Set<(event: EventFrame) => void>();
   private closed = false;
+  private role: DaemonRole = "owner";
 
   static async connect(options: ConnectOptions = {}): Promise<DaemonClient> {
     const home = options.home ?? cueloopHome();
     const path = socketPath(home);
     const client = new DaemonClient();
+    client.role = options.role ?? "owner";
     try {
       await client.dial(path);
       return client;
@@ -119,6 +124,8 @@ export class DaemonClient implements SessionClient {
     // Verify liveness: a dead socket file accepts connects on some platforms
     // only to fail later, so a ping is the actual handshake.
     await this.request("daemon.ping", {}, 2_000);
+    // Cap this connection's role for the daemon's capability gate (owner is the default).
+    if (this.role !== "owner") await this.request("daemon.hello", { role: this.role }, 2_000);
   }
 
   onEvent(listener: (event: EventFrame) => void): () => void {

package/src/herdr-pane.test.ts

@@ -192,6 +192,28 @@ describe("openHerdrPaneForReview", () => {
     expect(readLines(stub.logPath).some((line) => line.startsWith("tab create"))).toBeTrue();
   });
 
+  test("a recall failure (stale daemon) still opens a fresh tab", async () => {
+    // Arrange - a daemon predating the herdr-tab verbs rejects the recall
+    const stub = makeStub("gated-recall-fail");
+    const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+    const persistence: HerdrTabPersistence = {
+      herdrGetTab: async () => {
+        throw new Error("unknown method herdr.getTab");
+      },
+      herdrSetTab: async () => {},
+    };
+
+    // Act
+    await openHerdrPaneForReview(newSession({ id: "ses_stale" }), persistence, env);
+
+    // Assert - the recall throwing must not abort the open
+    expect(readLines(stub.logPath)).toEqual([
+      "tab create --cwd /repo/work --label Rollout Plan --focus",
+      "pane send-text w1:p2 cueloop ses_stale",
+      "pane send-keys w1:p2 enter",
+    ]);
+  });
+
   test("reopens and re-records when the recorded pane is dead", async () => {
     // Arrange
     const stub = makeStub("gated-dead", false);

package/src/herdr-pane.ts

@@ -103,20 +103,41 @@ export async function openHerdrPaneForReview(
 ): Promise<void> {
   const herdr = detectHerdr(env);
   if (!herdr) return;
+  const recorded = await recallHerdrTab(persistence, session.id);
+  if (recorded && herdrPaneAlive(herdr.binPath, recorded.paneId)) {
+    focusHerdrTab(herdr.binPath, recorded.tabId);
+    return;
+  }
+  const opened = openHerdrPane({
+    sessionId: session.id,
+    cwd: session.artifact.meta.cwd ?? process.cwd(),
+    binPath: herdr.binPath,
+    label: session.artifact.meta.title ?? session.id,
+  });
+  if (opened) await rememberHerdrTab(persistence, session.id, opened);
+}
+
+/** The recorded handle, or null on any recall failure - a stale daemon must still open a fresh tab, not abort. */
+async function recallHerdrTab(
+  persistence: HerdrTabPersistence,
+  sessionId: string,
+): Promise<HerdrTabHandle | null> {
   try {
-    const recorded = await persistence.herdrGetTab(session.id);
-    if (recorded && herdrPaneAlive(herdr.binPath, recorded.paneId)) {
-      focusHerdrTab(herdr.binPath, recorded.tabId);
-      return;
-    }
-    const opened = openHerdrPane({
-      sessionId: session.id,
-      cwd: session.artifact.meta.cwd ?? process.cwd(),
-      binPath: herdr.binPath,
-      label: session.artifact.meta.title ?? session.id,
-    });
-    if (opened) await persistence.herdrSetTab(session.id, opened);
+    return await persistence.herdrGetTab(sessionId);
+  } catch {
+    return null;
+  }
+}
+
+/** Record the handle for later liveness checks; a store failure loses dedup, never the already-open tab. */
+async function rememberHerdrTab(
+  persistence: HerdrTabPersistence,
+  sessionId: string,
+  handle: HerdrTabHandle,
+): Promise<void> {
+  try {
+    await persistence.herdrSetTab(sessionId, handle);
   } catch {
-    // best-effort: a herdr spawn or a daemon persistence hiccup never blocks review creation
+    // stale daemon: the tab is already shown; only the liveness-dedup handle is lost
   }
 }

package/src/herdr-split.test.ts

@@ -0,0 +1,103 @@
+/** launchHarnessInSplit: a stubbed herdr binary logs its argv, and the launcher splits the current pane, runs the harness in the new pane, and optionally types the plan-context seed - a no-op outside herdr. */
+
+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 { launchHarnessInSplit } from "./herdr-split";
+
+const dir = mkdtempSync(join(tmpdir(), "cueloop-herdr-split-"));
+
+/** A stub herdr binary that logs argv and prints the pane-split result (pane_id of the new split). */
+function makeStub(name: string, splitOk = true): { binPath: string; logPath: string } {
+  const logPath = join(dir, `${name}.log`);
+  const binPath = join(dir, `${name}.sh`);
+  const splitResult = splitOk
+    ? `printf '{"result":{"pane":{"pane_id":"w1:p9"}}}'`
+    : `printf '{"result":{}}'`;
+  writeFileSync(
+    binPath,
+    `#!/bin/sh
+printf '%s\\n' "$*" >> "${logPath}"
+if [ "$1" = "pane" ] && [ "$2" = "split" ]; then ${splitResult}; fi
+exit 0
+`,
+  );
+  chmodSync(binPath, 0o755);
+  return { binPath, logPath };
+}
+
+function readLines(logPath: string): string[] {
+  if (!existsSync(logPath)) return [];
+  return readFileSync(logPath, "utf8").split("\n").filter(Boolean);
+}
+
+describe("launchHarnessInSplit", () => {
+  test("splits the current pane and runs the harness in the new pane", () => {
+    // Arrange
+    const stub = makeStub("run");
+    const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+
+    // Act
+    const launched = launchHarnessInSplit({ command: "cc", cwd: "/repo/work" }, env);
+
+    // Assert
+    expect(launched).toBeTrue();
+    expect(readLines(stub.logPath)).toEqual([
+      "pane split w1:p1 --direction right --ratio 0.4 --cwd /repo/work",
+      "pane send-text w1:p9 cc",
+      "pane send-keys w1:p9 enter",
+    ]);
+  });
+
+  test("types the plan-context seed into the split after launching", () => {
+    // Arrange
+    const stub = makeStub("seeded");
+    const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+
+    // Act
+    launchHarnessInSplit({ command: "pi", cwd: "/repo", seedText: "read plan ses_1" }, env);
+
+    // Assert
+    expect(readLines(stub.logPath)).toEqual([
+      "pane split w1:p1 --direction right --ratio 0.4 --cwd /repo",
+      "pane send-text w1:p9 pi",
+      "pane send-keys w1:p9 enter",
+      "pane send-text w1:p9 read plan ses_1",
+    ]);
+  });
+
+  test("no-op outside herdr - returns false and spawns nothing", () => {
+    // Arrange
+    const stub = makeStub("outside");
+
+    // Act
+    const launched = launchHarnessInSplit(
+      { command: "cc", cwd: "/repo" },
+      { HERDR_BIN_PATH: stub.binPath },
+    );
+
+    // Assert
+    expect(launched).toBeFalse();
+    expect(existsSync(stub.logPath)).toBeFalse();
+  });
+
+  test("returns false when the split yields no pane id", () => {
+    // Arrange
+    const stub = makeStub("nopane", false);
+    const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+
+    // Act
+    const launched = launchHarnessInSplit({ command: "cc", cwd: "/repo" }, env);
+
+    // Assert - the split ran but no harness was launched into a missing pane
+    expect(launched).toBeFalse();
+    expect(readLines(stub.logPath)).toEqual([
+      "pane split w1:p1 --direction right --ratio 0.4 --cwd /repo",
+    ]);
+  });
+});
+
+afterAll(() => {
+  rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+});

package/src/herdr-split.ts

@@ -0,0 +1,84 @@
+/**
+ * Launches a bring-your-own review harness (claude code / pi / codex) in a herdr
+ * split beside the current pane - the Agent rail's "run it right here" spawn, so
+ * a reviewer chats with an agent about the plan without leaving the review tab.
+ * Best-effort and herdr-only: a no-op returning false outside herdr or on any
+ * spawn failure, each spawn bounded by a timeout.
+ */
+
+import { detectHerdr, type HerdrEnv } from "@cueloop/schema";
+
+const HERDR_SPAWN_TIMEOUT_MS = 2000;
+
+/** How much of the current pane the launched harness split takes (herdr --ratio). */
+const HARNESS_SPLIT_RATIO = "0.4";
+
+export interface LaunchHarnessInSplitOptions {
+  /** The harness launch command run in the split, e.g. "cc", "pi", "codex". */
+  command: string;
+  /** Working directory for the split - the reviewed session's cwd. */
+  cwd: string;
+  /**
+   * A plan-context briefing typed into the split after the harness command, left
+   * unsubmitted for the reviewer to send. Best-effort: on a slow harness start it
+   * may reach the shell instead, so the launch never depends on it.
+   */
+  seedText?: string;
+}
+
+/**
+ * Split the current pane and run the harness in it. Returns true when the split
+ * opened, false on any best-effort bail-out. No-op outside herdr.
+ */
+export function launchHarnessInSplit(
+  options: LaunchHarnessInSplitOptions,
+  env: HerdrEnv = process.env,
+): boolean {
+  const herdr = detectHerdr(env);
+  if (!herdr) return false;
+  try {
+    const split = Bun.spawnSync(
+      [
+        herdr.binPath,
+        "pane",
+        "split",
+        herdr.paneId,
+        "--direction",
+        "right",
+        "--ratio",
+        HARNESS_SPLIT_RATIO,
+        "--cwd",
+        options.cwd,
+      ],
+      { stdout: "pipe", stderr: "ignore", timeout: HERDR_SPAWN_TIMEOUT_MS },
+    );
+    if (split.exitCode !== 0) return false;
+    const parsed = JSON.parse(split.stdout.toString()) as {
+      result?: { pane?: { pane_id?: string } };
+    };
+    const paneId = parsed.result?.pane?.pane_id;
+    if (!paneId) return false;
+    sendText(herdr.binPath, paneId, options.command);
+    sendKeys(herdr.binPath, paneId, "enter");
+    if (options.seedText) sendText(herdr.binPath, paneId, options.seedText);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sendText(binPath: string, paneId: string, text: string): void {
+  Bun.spawnSync([binPath, "pane", "send-text", paneId, text], {
+    stdout: "ignore",
+    stderr: "ignore",
+    timeout: HERDR_SPAWN_TIMEOUT_MS,
+  });
+}
+
+function sendKeys(binPath: string, paneId: string, keys: string): void {
+  Bun.spawnSync([binPath, "pane", "send-keys", paneId, keys], {
+    stdout: "ignore",
+    stderr: "ignore",
+    timeout: HERDR_SPAWN_TIMEOUT_MS,
+  });
+}

package/src/server.ts

@@ -16,6 +16,7 @@ import {
 } 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 { BackpressureWriter, LineBuffer, type Request } from "./protocol";
 import { cueloopHome, lockPath, pidPath, socketPath } from "./paths";
@@ -23,6 +24,8 @@ import { cueloopHome, lockPath, pidPath, socketPath } from "./paths";
 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 {
@@ -136,7 +139,11 @@ export class DaemonServer {
       socket: {
         open: (socket) => {
           const writer = new BackpressureWriter(socket);
-          const connection: Connection = { write: (data) => writer.write(data), subscribed: false };
+          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();
@@ -219,10 +226,18 @@ export class DaemonServer {
     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 (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();

package/src/validate.ts

@@ -153,6 +153,7 @@ export const Params = {
   }),
   "events.subscribe": v.object({}),
   "daemon.ping": v.object({}),
+  "daemon.hello": v.object({ role: v.picklist(["owner", "collaborator", "agent"]) }),
   "daemon.shutdown": v.object({}),
   // herdr adapter scratch: the review's opened tab, kept off the session record.
   "herdr.getTab": v.object({ id: SessionId }),