@cueloop/daemon 0.1.0-alpha.97 → 0.1.0-alpha.99

package/src/examples/daemon-sdk.ts

@@ -0,0 +1,55 @@
+import { randomUUID } from "node:crypto";
+import { Effect } from "effect";
+import { CueloopSdk } from "../daemon-sdk-effect";
+
+const reviewConversation = Effect.gen(function* () {
+  const sdk = yield* CueloopSdk;
+  const thread = yield* sdk.threads.create({
+    workspace: { repoRoot: process.cwd(), branch: "main" },
+    artifact: { type: "plan", content: "Review this proposal.", meta: { title: "SDK example" } },
+  });
+
+  yield* sdk.threads.get(thread.id);
+  yield* sdk.comments.add({
+    threadId: thread.id,
+    annotation: {
+      id: "question",
+      kind: "comment",
+      body: "Explain the proposal",
+      anchor: { quote: "proposal", prefix: "Review this ", suffix: "." },
+    },
+  });
+  const accepted = yield* sdk.agents.prompt({
+    threadId: thread.id,
+    operationId: sdk.ids.operation(randomUUID()),
+    text: "Explain this Thread and its comment.",
+  });
+  const completed = yield* sdk.agents.wait(accepted, { timeoutMs: 300_000 });
+
+  if (completed.outcome !== "completed")
+    throw new Error(`SDK example agent finished: ${completed.outcome}`);
+  const comments = yield* sdk.comments.list(thread.id);
+
+  if (comments[0])
+    yield* sdk.comments.reply({
+      threadId: thread.id,
+      commentId: comments[0].id,
+      body: "The explanation is clear.",
+    });
+  yield* sdk.sessions.sendMessage({
+    threadId: thread.id,
+    operationId: sdk.ids.operation(randomUUID()),
+    outcome: "approved",
+    summary: "Review complete",
+  });
+
+  return thread.id;
+});
+
+if (import.meta.main) {
+  const threadId = await Effect.runPromise(
+    reviewConversation.pipe(Effect.provide(CueloopSdk.ownerLayer({ autostart: true }))),
+  );
+
+  console.log(`Thread approved: ${threadId}`);
+}

package/src/harness-delivery.test.ts

@@ -164,6 +164,7 @@ describe("durable harness delivery", () => {
       harnessSessionId: "fake_1",
     });
     const sent = first.sessionSendMessage(thread.id, "approved", "Ready.");
+
     first.store.upsert({
       ...first.sessionGet(thread.id),
       createdAt: "2020-01-01T00:00:00.000Z",

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/operation-receipts.test.ts

@@ -0,0 +1,111 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DaemonCore } from "./api";
+
+test("send message operation receipts survive restart and reject changed payloads", () => {
+  const home = mkdtempSync(join(tmpdir(), "cueloop-operation-"));
+  let core = new DaemonCore(home);
+
+  try {
+    const thread = core.sessionCreate({
+      workspace: { repoRoot: home, branch: "main" },
+      artifact: { type: "plan", content: "Review this", meta: {} },
+    });
+    const accepted = core.sessionSendMessage(thread.id, "comment", "First", undefined, "op-first");
+    const message = structuredClone(accepted.message);
+
+    core.sessionSendMessage(thread.id, "comment", "Second", undefined, "op-second");
+    core.dispose();
+    core = new DaemonCore(home);
+    const replay = core.sessionSendMessage(thread.id, "comment", "First", undefined, "op-first");
+
+    expect(replay.message).toEqual(message);
+    expect(
+      core.sessionGet(thread.id).history?.entries.filter((entry) => entry.type === "message"),
+    ).toHaveLength(2);
+    expect(() =>
+      core.sessionSendMessage(thread.id, "comment", "Changed", undefined, "op-first"),
+    ).toThrow("Operation payload conflict");
+  } finally {
+    core.dispose();
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("receipt capacity never evicts accepted IDs and share blobs omit private receipts", async () => {
+  const { packSessionBlob, unpackSessionBlob } = await import("./share-blob");
+  const home = mkdtempSync(join(tmpdir(), "cueloop-operation-capacity-"));
+  const core = new DaemonCore(home);
+
+  try {
+    const thread = core.sessionCreate({
+      workspace: { repoRoot: home, branch: "main" },
+      artifact: { type: "plan", content: "Review", meta: {} },
+    });
+    const first = structuredClone(
+      core.sessionSendMessage(thread.id, "comment", "First", undefined, "first").message,
+    );
+
+    for (let index = 1; index < 128; index++)
+      core.sessionSendMessage(
+        thread.id,
+        "comment",
+        `Message ${index}`,
+        undefined,
+        `operation-${index}`,
+      );
+    expect(() =>
+      core.sessionSendMessage(thread.id, "comment", "Overflow", undefined, "overflow"),
+    ).toThrow("Operation receipt capacity");
+    expect(
+      core.sessionSendMessage(thread.id, "comment", "First", undefined, "first").message,
+    ).toEqual(first);
+    expect(
+      unpackSessionBlob(packSessionBlob(core.sessionGet(thread.id))).messageOperations,
+    ).toBeUndefined();
+  } finally {
+    core.dispose();
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("failed receipt persistence never acknowledges an in-memory-only review message", async () => {
+  const { mkdirSync, readdirSync } = await import("node:fs");
+  const { threadsDir } = await import("./paths");
+  const home = mkdtempSync(join(tmpdir(), "cueloop-operation-disk-failure-"));
+  const core = new DaemonCore(home);
+
+  try {
+    const thread = core.sessionCreate({
+      workspace: { repoRoot: home, branch: "main" },
+      artifact: { type: "plan", content: "Review", meta: {} },
+    });
+    const bucket = readdirSync(threadsDir(home))[0]!;
+    const tempPath = join(threadsDir(home), bucket, `${thread.id}.jsonl.tmp`);
+
+    mkdirSync(tempPath);
+    expect(() =>
+      core.sessionSendMessage(thread.id, "comment", "Once", undefined, "persist-once"),
+    ).toThrow();
+    expect(core.sessionGet(thread.id).messageOperations).toBeUndefined();
+    expect(core.sessionGet(thread.id).message).toBeNull();
+    rmSync(tempPath, { recursive: true });
+    const accepted = core.sessionSendMessage(
+      thread.id,
+      "comment",
+      "Once",
+      undefined,
+      "persist-once",
+    );
+
+    expect(accepted.messageOperations).toHaveLength(1);
+    expect(
+      core.sessionSendMessage(thread.id, "comment", "Once", undefined, "persist-once").message,
+    ).toEqual(accepted.message);
+  } finally {
+    core.dispose();
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/operation-receipts.ts

@@ -0,0 +1,91 @@
+import type { ThreadAgentState, OperationReceipt, AgentPromptRequest } from "@cueloop/schema";
+import { createHash } from "node:crypto";
+import { DaemonError } from "./errors";
+
+/** Hash normalized payloads rather than persisting another copy of private input. */
+export function operationFingerprint(
+  payload: readonly (string | null | readonly (readonly [string, string])[])[],
+): string {
+  return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+
+/** A duplicate returns its original acceptance even after later operations or restart. */
+export function findOperationReceipt<Result>(
+  receipts: readonly OperationReceipt<Result>[] | undefined,
+  operationId: string | undefined,
+  fingerprint: string,
+): OperationReceipt<Result> | undefined {
+  if (!operationId) return;
+  const receipt = receipts?.find((entry) => entry.operationId === operationId);
+
+  if (receipt && receipt.fingerprint !== fingerprint)
+    throw new DaemonError(
+      "operation_conflict",
+      "Operation payload conflict: use a new operation ID for changed input",
+    );
+  if (!receipt && (receipts?.length ?? 0) >= 128)
+    throw new DaemonError(
+      "operation_capacity",
+      "Operation receipt capacity: create a new Thread before submitting more operations",
+    );
+
+  return receipt;
+}
+
+/** Each accepted prompt freezes the original batch before it can start a harness turn. */
+export function recordPromptOperation(
+  state: ThreadAgentState,
+  before: ThreadAgentState,
+  input: AgentPromptRequest,
+): void {
+  if (!input.operationId) return;
+  const previous = new Set(before.submissions?.map((entry) => entry.id));
+  const accepted = input.retry
+    ? [input.retry]
+    : (state.submissions ?? []).filter((entry) => !previous.has(entry.id)).map((entry) => entry.id);
+
+  if (!accepted.length) throw new DaemonError("invalid_params", "Agent operation requires input");
+  const fingerprint = promptOperationFingerprint(input);
+
+  (state.promptOperations ??= []).push({
+    operationId: input.operationId,
+    fingerprint,
+    result: accepted,
+  });
+}
+
+/** Completion is an immutable fact about acceptance, including across explicit retries. */
+export function settlePromptOperations(state: ThreadAgentState): void {
+  for (const receipt of state.promptOperations ?? []) {
+    if (receipt.outcome || !receipt.result.length) continue;
+    const submissions = receipt.result.map((id) =>
+      state.submissions?.find((entry) => entry.id === id),
+    );
+
+    if (
+      submissions.some((entry) => !entry || entry.status === "queued" || entry.status === "running")
+    )
+      continue;
+    receipt.outcome = submissions.some((entry) => entry?.cancelled)
+      ? "cancelled"
+      : submissions.some((entry) => entry?.status === "failed")
+        ? "failed"
+        : "completed";
+  }
+}
+
+/** Prompt identity hashes only explicit input; a retry does not consume newly pending comments. */
+export function findPromptOperationReceipt(
+  state: ThreadAgentState,
+  input: AgentPromptRequest,
+): OperationReceipt<string[]> | undefined {
+  return findOperationReceipt(
+    state.promptOperations,
+    input.operationId,
+    promptOperationFingerprint(input),
+  );
+}
+
+function promptOperationFingerprint(input: AgentPromptRequest): string {
+  return operationFingerprint([input.text, input.context ?? null, input.retry ?? null]);
+}

package/src/pr-poller.ts

@@ -29,6 +29,7 @@ export class PrReviewPoller {
   trackPr(sessionId: string, pr: string, reviewedRefs: PullRequestRefs | null = null): void {
     if (this.polls.has(sessionId)) return;
     const timer = setInterval(() => void this.refreshHead(sessionId), this.intervalMs);
+
     // the poll timer must not by itself keep the daemon alive against idle-exit
     timer.unref?.();
     this.polls.set(sessionId, { pr, lastRefs: reviewedRefs, timer });

package/src/sdk-identities.ts

@@ -0,0 +1,35 @@
+import * as v from "valibot";
+
+const ThreadIdSchema = v.pipe(v.string(), v.minLength(1), v.maxLength(128), v.brand("SdkThreadId"));
+const OperationIdSchema = v.pipe(
+  v.string(),
+  v.minLength(1),
+  v.maxLength(128),
+  v.brand("SdkOperationId"),
+);
+const SubmissionIdSchema = v.pipe(
+  v.string(),
+  v.minLength(1),
+  v.maxLength(128),
+  v.brand("SdkSubmissionId"),
+);
+
+/** Thread, operation and submission IDs share a wire representation, not a domain type. */
+export type SdkThreadId = v.InferOutput<typeof ThreadIdSchema>;
+/** Operation IDs are caller-owned and persist across explicit retries. */
+export type SdkOperationId = v.InferOutput<typeof OperationIdSchema>;
+/** Submission IDs are minted by the daemon after accepting agent input. */
+export type SdkSubmissionId = v.InferOutput<typeof SubmissionIdSchema>;
+
+/** External Thread identities must be nonempty and at most 128 characters. */
+export function createSdkThreadId(value: string): SdkThreadId {
+  return v.parse(ThreadIdSchema, value);
+}
+/** Caller operation identities are stable across retries and at most 128 characters. */
+export function createSdkOperationId(value: string): SdkOperationId {
+  return v.parse(OperationIdSchema, value);
+}
+/** Submission identities are daemon-minted; parsing grants no capability. */
+export function createSdkSubmissionId(value: string): SdkSubmissionId {
+  return v.parse(SubmissionIdSchema, value);
+}

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,110 @@ 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.replyAgentComment(args));
+      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 replyAgentComment(params: {
+    id: string;
+    commentId: string;
+    body: string;
+  }): ReturnType<ThreadAgentManager["reply"]> {
+    this.threadAgent.assertEnabled(params.id);
+
+    return this.threadAgent.reply(params.id, params.commentId, params.body);
+  }
+
   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.reply": (_connection, request) => {
+      const params = parseParams("agent.reply", request.params);
+
+      return this.replyAgentComment(params);
+    },
+    "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 +506,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 +530,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 +650,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 {};
     },
@@ -496,6 +674,7 @@ export class DaemonServer {
         params.outcome,
         params.summary,
         params.actionBodies,
+        params.operationId,
       );
     },
     "harness.bind": (_connection, request) => {

package/src/share-blob.ts

@@ -25,7 +25,9 @@ export const DEFAULT_SHARE_PORT = 22;
 
 /** Serialise + compress a session for upload. */
 export function packSessionBlob(session: Thread): Buffer {
-  return gzipSync(Buffer.from(JSON.stringify(session), "utf8"));
+  const { messageOperations: _privateReceipts, ...shared } = session;
+
+  return gzipSync(Buffer.from(JSON.stringify(shared), "utf8"));
 }
 
 /** Decompress + validate an uploaded blob, or throw a precise reason. */