@cueloop/daemon 0.1.0-alpha.96 → 0.1.0-alpha.98

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.96",
+  "version": "0.1.0-alpha.98",
   "description": "The cueloop session daemon and its client: socket protocol, atomic store, resumable waits",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -39,8 +39,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/extension-api": "0.1.0-alpha.96",
-    "@cueloop/schema": "0.1.0-alpha.96",
+    "@cueloop/extension-api": "0.1.0-alpha.98",
+    "@cueloop/schema": "0.1.0-alpha.98",
     "@pierre/diffs": "^1.4.1",
     "effect": "^4.0.0-rc.117",
     "smol-toml": "^1.8.0",

package/src/agent-tools.ts

@@ -0,0 +1,98 @@
+import * as v from "valibot";
+import { resolve } from "node:path";
+import { MESSAGE_OUTCOMES, type Thread } from "@cueloop/schema";
+import type { MethodName } from "./validate";
+
+/** Tool arguments are validated before entering the owner's daemon API. */
+export function parseAgentToolInput(name: string, serialized: string) {
+  const input: unknown = JSON.parse(serialized);
+
+  if (name === "reply_to_comment") {
+    const args = v.parse(
+      v.object({
+        id: v.string(),
+        commentId: v.string(),
+        body: v.pipe(v.string(), v.minLength(1), v.maxLength(32768)),
+      }),
+      input,
+    );
+
+    return { kind: "reply" as const, ...args };
+  }
+  if (name === "send_message") {
+    const args = v.parse(
+      v.object({
+        id: v.string(),
+        outcome: v.picklist(MESSAGE_OUTCOMES),
+        summary: v.optional(v.string(), ""),
+      }),
+      input,
+    );
+
+    return { kind: "api" as const, method: "session.sendMessage", params: args };
+  }
+  if (name !== "cueloop_api") throw new Error("Thread agent tool name is unavailable");
+  const args = v.parse(v.object({ method: v.string(), params: v.unknown() }), input);
+
+  return { kind: "api" as const, ...args };
+}
+
+const THREAD_AGENT_SESSION_METHODS = new Set<string>([
+  "session.get",
+  "session.wait",
+  "session.annotate",
+  "session.comment",
+  "session.removeAnnotation",
+  "session.setParticipantName",
+  "session.setWorkingCopy",
+  "session.cutBlock",
+  "session.navigate",
+  "session.branch",
+  "session.switch",
+  "session.label",
+  "session.restoreBlock",
+  "session.curate",
+  "session.setViewed",
+  "session.setTitle",
+  "session.projectFiles",
+  "session.fileContents",
+  "session.refreshDiff",
+  "session.sendMessage",
+  "session.submitRevision",
+] satisfies MethodName[]);
+const THREAD_AGENT_REPO_METHODS = new Set<string>([
+  "repo.files",
+  "repo.fileContents",
+  "repo.changes",
+  "repo.diff",
+] satisfies MethodName[]);
+
+/** Harness tools are bound to their originating Thread; model arguments cannot widen that scope. */
+export function assertAgentToolScope(
+  thread: Thread,
+  input: ReturnType<typeof parseAgentToolInput>,
+): void {
+  if (input.kind === "reply") {
+    if (input.id !== thread.id) throw new Error("Thread agent tool cannot access another Thread");
+
+    return;
+  }
+  if (input.method === "session.list") return;
+  const params = v.parse(v.record(v.string(), v.unknown()), input.params);
+
+  if (THREAD_AGENT_SESSION_METHODS.has(input.method)) {
+    if (params.id !== thread.id) throw new Error("Thread agent tool cannot access another Thread");
+
+    return;
+  }
+  if (THREAD_AGENT_REPO_METHODS.has(input.method)) {
+    const { cwd } = v.parse(v.object({ cwd: v.string() }), params);
+
+    if (resolve(cwd) !== resolve(thread.workspace.repoRoot))
+      throw new Error("Thread agent tool cannot access another repository");
+
+    return;
+  }
+
+  throw new Error("Thread agent tool API method is unavailable");
+}

package/src/agent-turn.test.ts

@@ -0,0 +1,24 @@
+import { expect, test } from "bun:test";
+import { stepAgentTurn, type AgentTurn } from "./agent-turn";
+
+test("an initialization stop settles before accepting a fresh turn", () => {
+  const starting = stepAgentTurn({ kind: "idle" }, "start");
+  const stopped = stepAgentTurn(starting, "stop");
+  const ready = stepAgentTurn(stopped, "ready");
+
+  expect(ready).toEqual({ kind: "idle" });
+  expect(stepAgentTurn(ready, "start")).toEqual({ kind: "starting", cancelled: false });
+});
+
+test("an active stop waits for completion before accepting another turn", () => {
+  const running: AgentTurn = { kind: "running" };
+  const stopped = stepAgentTurn(running, "stop");
+
+  expect(stopped).toEqual({ kind: "stopping" });
+  expect(stepAgentTurn(stopped, "start")).toEqual(stopped);
+  expect(stepAgentTurn(stopped, "ready")).toEqual(stopped);
+  expect(stepAgentTurn(stepAgentTurn(stopped, "finished"), "start")).toEqual({
+    kind: "starting",
+    cancelled: false,
+  });
+});

package/src/agent-turn.ts

@@ -0,0 +1,34 @@
+/** A harness turn distinguishes initialization cancellation from a running stop request. */
+export type AgentTurn =
+  | { kind: "idle" }
+  | { kind: "starting"; cancelled: boolean }
+  | { kind: "running" }
+  | { kind: "stopping" };
+
+/** Lifecycle events are independent of the harness wire protocol. */
+export type AgentTurnEvent = "start" | "ready" | "stop" | "finished";
+
+/** Start is accepted only at idle; readiness consumes an initialization cancellation. */
+export function stepAgentTurn(state: AgentTurn, event: AgentTurnEvent): AgentTurn {
+  switch (event) {
+    case "start":
+      return state.kind === "idle" ? { kind: "starting", cancelled: false } : state;
+    case "ready":
+      return state.kind === "starting"
+        ? state.cancelled
+          ? { kind: "idle" }
+          : { kind: "running" }
+        : state;
+    case "stop":
+      if (state.kind === "starting") return { kind: "starting", cancelled: true };
+
+      return state.kind === "running" ? { kind: "stopping" } : state;
+    case "finished":
+      return { kind: "idle" };
+  }
+}
+
+/** Pending stop requests suppress later tool and permission events from this turn. */
+export function agentTurnCancelled(state: AgentTurn): boolean {
+  return state.kind === "stopping" || (state.kind === "starting" && state.cancelled);
+}

package/src/capabilities.ts

@@ -18,6 +18,12 @@ export type DaemonRole = "owner" | "collaborator" | "agent";
 type Audience = "any" | "owner";
 
 const PRIMITIVE_ROLES = {
+  "agent.configure": "owner",
+  "agent.get": "owner",
+  "agent.prompt": "owner",
+  "agent.cancel": "owner",
+  "agent.comment": "owner",
+  "agent.permission": "owner",
   "daemon.ping": "any",
   "daemon.hello": "any",
   "daemon.shutdown": "owner",

package/src/client.test.ts

@@ -22,3 +22,16 @@ describe("daemonSpawnCommand", () => {
     ).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"]);
+});

package/src/client.ts

@@ -58,6 +58,8 @@ import {
 } from "./validate";
 import type { WorkingTreeDiff } from "./working-tree";
 import { DAEMON_VERSION } from "./version";
+import { ThreadAgentSchema } from "./thread-agent-validation";
+import type { AgentComment, ThreadAgentState } from "@cueloop/schema";
 
 export type { EventFrame } from "./protocol";
 
@@ -101,6 +103,8 @@ export interface ThreadClient {
   onEvent(listener: (event: EventFrame) => void): () => void;
   subscribe(): Promise<void>;
   sessionGet(id: string): Promise<Thread>;
+  /** Create a local owner Thread; shared clients omit this capability. */
+  sessionCreate?(workspace: WorkspaceKey, artifact: Artifact): Promise<Thread>;
   sessionList(filter?: { status?: "pending" | "resolved" }): Promise<Thread[]>;
   /** Add a comment; the primary annotate method. `sessionAnnotate` is the retained alias. */
   sessionComment(
@@ -458,6 +462,44 @@ export class DaemonClient implements ThreadClient {
   }
 
   // ── typed primitives ─────────────────────────────
+  /** Read the agent transcript without starting a model request. */
+  agentGet(id: string): Promise<ThreadAgentState> {
+    return this.request("agent.get", { id }, ThreadAgentSchema);
+  }
+  /** Submit a question and optional selected passage to the daemon-owned agent. */
+  agentPrompt(params: {
+    id: string;
+    text: string;
+    context?: string;
+    retry?: string;
+  }): Promise<ThreadAgentState> {
+    return this.request("agent.prompt", params, ThreadAgentSchema);
+  }
+  /** Cancel the active turn; the daemon retains partial output. */
+  agentCancel(id: string): Promise<ThreadAgentState> {
+    return this.request("agent.cancel", { id }, ThreadAgentSchema);
+  }
+  /** Save quote-primary feedback on a finalized agent answer. */
+  agentComment(params: { id: string; comment: AgentComment }): Promise<ThreadAgentState> {
+    return this.request("agent.comment", params, ThreadAgentSchema);
+  }
+  /** Configure only an option advertised by the current harness. */
+  agentConfigure(params: {
+    id: string;
+    configId?: string;
+    value?: string;
+  }): Promise<ThreadAgentState> {
+    return this.request("agent.configure", params, ThreadAgentSchema);
+  }
+
+  /** Select an option from the active agent permission card. */
+  agentPermission(params: {
+    id: string;
+    requestId: string;
+    optionId: string;
+  }): Promise<ThreadAgentState> {
+    return this.request("agent.permission", params, ThreadAgentSchema);
+  }
   ping(): Promise<{ pid: number }> {
     return this.request("daemon.ping", {}, PingResultSchema);
   }
@@ -731,7 +773,7 @@ export class DaemonClientError extends Error {
 }
 
 // A compiled binary re-execs `cueloop daemon --autostart` (idle-exits like main.ts,
-// unlike the never-exiting foreground daemon); from source, bun runs main.ts. In
+// unlike the never-exiting foreground daemon); source also uses the CLI composition root. In
 // dev (CUELOOP_DEV_WATCH=1, source only) it runs under --watch so daemon-code edits
 // reload the daemon without a manual restart - the version handshake only catches
 // release upgrades, not same-version source changes.
@@ -739,14 +781,19 @@ export function daemonSpawnCommand(
   execPath: string,
   moduleUrl: string,
   devWatch = process.env.CUELOOP_DEV_WATCH === "1",
+  entry = process.env.CUELOOP_DAEMON_ENTRY,
 ): string[] {
   const compiled =
     moduleUrl.includes("$bunfs") || moduleUrl.includes("~BUN") || moduleUrl.includes("%7EBUN");
 
   if (compiled) return [execPath, "daemon", "--autostart"];
-  const mainPath = new URL("./main.ts", moduleUrl).pathname;
+  const mainPath = entry ?? new URL("./main.ts", moduleUrl).pathname;
+
+  const args = entry ? ["daemon", "--autostart"] : [];
 
-  return devWatch ? [execPath, "--watch", "run", mainPath] : [execPath, "run", mainPath];
+  return devWatch
+    ? [execPath, "--watch", "run", mainPath, ...args]
+    : [execPath, "run", mainPath, ...args];
 }
 
 function spawnDaemon(home: string): string {

package/src/harness-diagnostics.test.ts

@@ -0,0 +1,26 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { writeHarnessDiagnostic } from "./harness-diagnostics";
+
+test("diagnostic logs are private and bounded across repeated notices", () => {
+  const directory = mkdtempSync(join(tmpdir(), "cueloop-diagnostics-"));
+  const path = join(directory, "thread.diagnostics.ndjson");
+
+  try {
+    for (let i = 0; i < 100; i++)
+      writeHarnessDiagnostic(directory, "thread", {
+        kind: "diagnostic",
+        severity: "error",
+        source: "protocol",
+        title: "Advisory",
+        text: "x".repeat(32768),
+      });
+    expect(statSync(path).size).toBeLessThanOrEqual(256 * 1024);
+    expect(statSync(path).mode & 0o777).toBe(0o600);
+    expect(JSON.parse(readFileSync(path, "utf8").trim().split("\n")[0]!).text).toHaveLength(16384);
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});

package/src/harness-diagnostics.ts

@@ -0,0 +1,30 @@
+import { appendFileSync, existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AgentHarnessDiagnostic } from "@cueloop/schema";
+
+/** Store harness diagnostics in a private, bounded log, outside Thread history and model context. */
+export function writeHarnessDiagnostic(
+  directory: string,
+  threadId: string,
+  diagnostic: AgentHarnessDiagnostic,
+): void {
+  const path = join(directory, `${encodeURIComponent(threadId)}.diagnostics.ndjson`);
+  const record =
+    JSON.stringify({
+      at: new Date().toISOString(),
+      ...diagnostic,
+      severity: diagnostic.severity.slice(0, 128),
+      title: diagnostic.title.slice(0, 512),
+      text: diagnostic.text.slice(0, 16384),
+    }) + "\n";
+
+  try {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (existsSync(path) && statSync(path).size + Buffer.byteLength(record) > 256 * 1024)
+      writeFileSync(path, record, { mode: 0o600 });
+    else appendFileSync(path, record, { mode: 0o600 });
+  } catch {
+    // A diagnostic log failure must not change the agent turn outcome.
+    console.error("Thread agent diagnostic log could not be written");
+  }
+}

package/src/server.ts

@@ -17,6 +17,7 @@ import {
   statSync,
   writeFileSync,
 } from "node:fs";
+import type { AgentHarnessTools } from "@cueloop/schema";
 import { DaemonCore, type DaemonEvent } from "./api";
 import { DaemonError } from "./errors";
 import { DEFAULT_ROLE, roleAllowsMethod, type DaemonRole } from "./capabilities";
@@ -30,7 +31,9 @@ import {
 } from "./protocol";
 import { cueloopHome, lockPath, ownerTokenPath, pidPath, socketPath } from "./paths";
 import { DAEMON_VERSION } from "./version";
-import { randomBytes } from "node:crypto";
+import { randomUUID, randomBytes } from "node:crypto";
+import { parseAgentToolInput, assertAgentToolScope } from "./agent-tools";
+import { ThreadAgentManager, type ThreadAgentOptions } from "./thread-agent";
 
 interface Connection {
   /** The author a non-owner connection acts as, bound in the handshake. */
@@ -44,6 +47,8 @@ interface Connection {
 type MethodHandler = (connection: Connection, request: Request) => Response["result"];
 
 export interface DaemonOptions {
+  /** Explicit prototype configuration; commands cannot arrive from socket callers. */
+  threadAgent?: Pick<ThreadAgentOptions, "enabled" | "enabledForThread" | "adapter">;
   home?: string;
   /** Idle-exit delay; 0 disables (tests, foreground runs). */
   idleExitMs?: number;
@@ -61,6 +66,7 @@ const HELD_HOMES = new Set<string>();
 const LOCK_WAIT = new Int32Array(new SharedArrayBuffer(4));
 
 export class DaemonServer {
+  private readonly threadAgent: ThreadAgentManager;
   readonly core: DaemonCore;
   readonly home: string;
   private connections = new Set<Connection>();
@@ -80,6 +86,62 @@ export class DaemonServer {
     this.version = options.version ?? DAEMON_VERSION;
     mkdirSync(this.home, { recursive: true, mode: 0o700 });
     this.core = new DaemonCore(this.home);
+    this.threadAgent = new ThreadAgentManager({
+      home: this.home,
+      enabled: options.threadAgent?.enabled ?? false,
+      enabledForThread: options.threadAgent?.enabledForThread,
+      adapter: options.threadAgent?.adapter,
+      getThread: (id) => this.core.sessionGet(id),
+      tools: (thread): AgentHarnessTools => ({
+        definitions: [
+          {
+            name: "send_message",
+            description:
+              "Return the Thread and its comments to the main session using the existing Send message action.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                id: { type: "string" },
+                outcome: { type: "string", enum: ["comment", "approved", "changes_requested"] },
+                summary: { type: "string" },
+              },
+              required: ["id", "outcome"],
+            },
+          },
+          {
+            name: "reply_to_comment",
+            description:
+              "Append a reply to an existing comment discussion, preserving its quote and Changes origin.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                id: { type: "string" },
+                commentId: { type: "string" },
+                body: { type: "string" },
+              },
+              required: ["id", "commentId", "body"],
+            },
+          },
+          {
+            name: "cueloop_api",
+            description:
+              "Call a cueloop API operation on this Thread or its repository. Use session.get to inspect this Thread. Global harness, sharing, deletion and Thread creation operations are unavailable. Parameters follow the cueloop socket API.",
+            inputSchema: {
+              type: "object",
+              properties: { method: { type: "string" }, params: { type: "object" } },
+              required: ["method", "params"],
+            },
+          },
+        ],
+        call: async (name, input) => this.callAgentTool(thread.id, name, input),
+      }),
+      onChange: (id) => {
+        for (const connection of this.connections) {
+          if (connection.subscribed && connection.role === "owner")
+            connection.write(JSON.stringify({ event: "agent.updated", sessionId: id }) + "\n");
+        }
+      },
+    });
     this.core.onEvent((event) => this.broadcast(event));
   }
 
@@ -230,6 +292,7 @@ export class DaemonServer {
   }
 
   stop(): void {
+    this.threadAgent.dispose();
     this.core.dispose();
     if (this.lockFd === null) return;
     this.server?.stop(true);
@@ -287,7 +350,81 @@ export class DaemonServer {
     }
   }
 
+  private async callAgentTool(threadId: string, name: string, input: string): Promise<string> {
+    const args = parseAgentToolInput(name, input);
+    const origin = this.core.sessionGet(threadId);
+    assertAgentToolScope(origin, args);
+    if (args.kind === "api" && args.method === "session.list") {
+      const { filter } = parseParams("session.list", args.params);
+
+      return JSON.stringify(!filter?.status || origin.status === filter.status ? [origin] : []);
+    }
+    if (args.kind === "reply") {
+      const thread = origin;
+      const comment = thread.annotations.find((entry) => entry.id === args.commentId);
+      if (!comment)
+        return JSON.stringify(this.threadAgent.reply(args.id, args.commentId, args.body));
+      const root =
+        thread.annotations.find((entry) => entry.id === (comment.replyTo ?? comment.id)) ?? comment;
+
+      return JSON.stringify(
+        this.core.sessionAnnotate(
+          args.id,
+          {
+            id: randomUUID(),
+            kind: "comment",
+            anchor: root.anchor,
+            target: root.target,
+            replyTo: root.id,
+            body: args.body,
+            author: "embedded-agent",
+          },
+          "Agent",
+        ),
+      );
+    }
+    const method = args.method;
+    if (!isKnownMethod(method)) throw new Error("Thread agent tool API method is unavailable");
+
+    return JSON.stringify(
+      await this.handlers[method](
+        { role: "owner", subscribed: false, write: () => {} },
+        { id: 0, method, params: args.params },
+      ),
+    );
+  }
+
   private readonly handlers: Record<MethodName, MethodHandler> = {
+    "agent.configure": (_connection, request) => {
+      const params = parseParams("agent.configure", request.params);
+      this.threadAgent.assertEnabled(params.id);
+      return this.threadAgent.configure(params);
+    },
+    "agent.get": (_connection, request) => {
+      const { id } = parseParams("agent.get", request.params);
+      this.threadAgent.assertEnabled(id);
+      return this.threadAgent.get(id);
+    },
+    "agent.prompt": (_connection, request) => {
+      const params = parseParams("agent.prompt", request.params);
+      this.threadAgent.assertEnabled(params.id);
+      return this.threadAgent.prompt(params);
+    },
+    "agent.cancel": (_connection, request) => {
+      const { id } = parseParams("agent.cancel", request.params);
+      this.threadAgent.assertEnabled(id);
+      return this.threadAgent.cancel(id);
+    },
+    "agent.comment": (_connection, request) => {
+      const params = parseParams("agent.comment", request.params);
+      this.threadAgent.assertEnabled(params.id);
+      return this.threadAgent.comment(params);
+    },
+    "agent.permission": (_connection, request) => {
+      const params = parseParams("agent.permission", request.params);
+      this.threadAgent.assertEnabled(params.id);
+      return this.threadAgent.permission(params);
+    },
     "daemon.ping": () => ({ pid: process.pid, version: this.version }),
     "daemon.hello": (connection, request) => {
       const params = parseParams("daemon.hello", request.params);
@@ -340,11 +477,17 @@ export class DaemonServer {
     "session.annotate": (_connection, request) => {
       const params = parseParams("session.annotate", request.params);
 
+      if (this.threadAgent.isReadOnly(params.id, params.annotation.id))
+        throw new Error("Thread agent submitted comments are read-only");
+
       return this.core.sessionAnnotate(params.id, params.annotation, params.authorName);
     },
     "session.comment": (_connection, request) => {
       const params = parseParams("session.comment", request.params);
 
+      if (this.threadAgent.isReadOnly(params.id, params.annotation.id))
+        throw new Error("Thread agent submitted comments are read-only");
+
       return this.core.sessionAnnotate(params.id, params.annotation, params.authorName);
     },
     "session.removeAnnotation": (connection, request) => {
@@ -358,6 +501,9 @@ export class DaemonServer {
         );
       }
 
+      if (this.threadAgent.isReadOnly(params.id, params.annotationId))
+        throw new Error("Thread agent submitted comments are read-only");
+
       return this.core.sessionRemoveAnnotation(
         params.id,
         params.annotationId,
@@ -475,7 +621,10 @@ export class DaemonServer {
       return this.core.sessionSetShares(params.id, params.shares);
     },
     "session.delete": (_connection, request) => {
-      this.core.sessionDelete(parseParams("session.delete", request.params).id);
+      const { id } = parseParams("session.delete", request.params);
+
+      this.core.sessionDelete(id);
+      this.threadAgent.remove(id);
 
       return {};
     },