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

package/README.md

@@ -0,0 +1,7 @@
+# @cueloop/daemon
+
+The local cueloop daemon owns Thread mutations, persisted review history, harness
+bindings and socket subscriptions. Integrations use its typed NDJSON client.
+
+See the [daemon SDK contract](SDK.md) for explicit capabilities, safe mutation
+retries, reconnecting subscriptions and the optional scoped Effect service.

package/SDK.md

@@ -0,0 +1,102 @@
+# Daemon SDK
+
+The SDK is a facade over the existing NDJSON socket client. It lives at
+`@cueloop/daemon/sdk`; the optional Effect service is at
+`@cueloop/daemon/sdk-effect`. Both use the same daemon, Thread records and harness
+adapter. Importing the Promise SDK does not load Effect.
+
+## Capabilities
+
+`connectOwnerSdk({ home, autostart })` authenticates with the local owner token.
+It exposes Thread creation, review comments, review messages and embedded agent
+operations. Agent methods still require `[experimental] thread_agent = true` in
+the daemon's workspace configuration. Shared collaborators cannot invoke them.
+
+`connectReviewSdk({ home, role: "collaborator" | "agent", author })` exposes
+Thread reads and review comments only. An `agent` role here means a review-side
+agent, not the daemon-owned embedded harness. The daemon enforces authorization;
+TypeScript narrows the available operations but does not grant authority.
+The SDK brands Thread, operation and submission IDs separately. Thread reads
+return branded identities; `sdk.ids.thread`, `sdk.ids.operation` and
+`sdk.ids.submission` parse external strings for incremental adoption.
+
+## Acceptance, completion and retries
+
+`sessions.sendMessage` and `agents.prompt` require a caller-chosen `operationId`
+(up to 128 characters). Persist that ID with the normalized input if a workflow
+needs to resume. Receipts are scoped to a Thread and method. The same ID and
+payload return the original accepted message or submission batch after a lost
+response, disconnect or daemon restart. Different payloads reject with
+`operation_conflict`. Submission acceptance does not imply agent completion.
+
+Receipts commit in the same persisted record as their mutation. Each method
+retains up to 128 receipts for the lifetime of the Thread; it rejects new IDs with
+`operation_capacity` rather than evicting receipts and risking duplicate work.
+Deleting or retaining out an old Thread removes its receipts. A missing Thread
+rejects retries. Private receipt metadata is omitted from share blobs.
+
+`agents.wait(accepted)` waits for that exact batch and returns `completed`,
+`failed`, or `cancelled`. Terminal outcomes stay fixed even when a failed
+submission is explicitly retried with a new operation ID. Queued or running
+submissions recovered after a daemon restart become failed; they are never
+silently re-executed.
+
+There is no automatic mutation replay. A transport failure after writing has
+`certainty: "unknown"`; work may already have committed. Explicitly retry the two
+receipt-backed methods with the same operation ID and payload. Thread creation,
+comment replies and other legacy methods have no acceptance receipts: do not
+retry an ambiguous write automatically. Comments accept caller-chosen annotation
+IDs for upsert semantics, which are separate from mutation acceptance receipts.
+
+## Failures and cancellation
+
+`DaemonClientError` carries a daemon rejection `code` (including `forbidden`,
+`resolved`, `operation_conflict` and `operation_capacity`). A rejection is not a
+blanket rollback guarantee: a daemon internal error can follow a commit.
+
+`DaemonTransportError` carries `kind`: `protocol`, `connection`, `timeout` or
+`cancelled`, plus `certainty`: `not_sent` or `unknown`. A malformed result rejects
+its request promptly. A malformed outer frame closes the connection and rejects
+all outstanding requests. Pending requests remove timers and abort listeners on
+every completion or failure path.
+
+Requests accept `{ timeoutMs, signal }`, defaulting to a 30-second local deadline.
+Cancelling a request or wait stops local observation; it does not undo a mutation
+or stop a harness. `agents.cancel(threadId)` explicitly requests cancellation of
+the active turn and preserves partial output. It does not clear queued inputs.
+Closing the owner SDK also cancels its outstanding local waits.
+
+## Subscriptions
+
+`subscribeThreadState` owns an observation connection, subscribes before reading,
+refreshes after matching event hints and reconnects after connection loss. Every
+reconnect reads authoritative state, including changes made while disconnected.
+It never replays a write or treats event notifications as a durable log.
+
+Generation and request counters prevent late reads from overwriting newer state.
+Disposal removes listeners, cancels reconnect timers, aborts reads and closes the
+observation connection. Protocol errors and authorization/version rejections
+stop reconnection. Transient connection failures retry at the configured delay.
+The Thread-agent UI uses this shared lifecycle.
+
+## Effect and example
+
+`CueloopSdk.ownerLayer` acquires the owner connection with `Effect.acquireRelease`.
+Its operations have a typed `DaemonSdkError` channel. `threads.watch(id)` is a
+scoped stream of refreshed snapshots with a one-item sliding buffer. It coalesces
+state updates rather than promising delivery of every event. Effect interruption is passed
+through an AbortSignal, including to completion waits. Scope finalization closes
+the connection. The layer does not replace the daemon or rewrite UI state in
+Effect.
+
+With the experimental flag enabled and a harness configured, run:
+
+```sh
+bun run packages/daemon/src/examples/daemon-sdk.ts
+```
+
+The example creates and reads a Thread, submits a prompt, waits for its terminal
+outcome, lists and replies to a comment, then sends approval. It creates a real
+Thread and invokes the configured model. IDs are generated once per invocation;
+a resumable application should save them rather than generate replacements when
+retrying.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.97",
+  "version": "0.1.0-alpha.99",
   "description": "The cueloop session daemon and its client: socket protocol, atomic store, resumable waits",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -14,7 +14,8 @@
   },
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "SDK.md"
   ],
   "type": "module",
   "exports": {
@@ -33,17 +34,20 @@
     "./thread-surface-config": "./src/thread-surface-config.ts",
     "./herdr-split": "./src/herdr-split.ts",
     "./share-blob": "./src/share-blob.ts",
-    "./curate": "./src/curate.ts"
+    "./curate": "./src/curate.ts",
+    "./sdk": "./src/daemon-sdk.ts",
+    "./sdk-effect": "./src/daemon-sdk-effect.ts",
+    "./thread-subscription": "./src/thread-subscription.ts"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/extension-api": "0.1.0-alpha.97",
-    "@cueloop/schema": "0.1.0-alpha.97",
-    "@pierre/diffs": "^1.4.1",
-    "effect": "^4.0.0-rc.117",
-    "smol-toml": "^1.8.0",
+    "@cueloop/extension-api": "0.1.0-alpha.99",
+    "@cueloop/schema": "0.1.0-alpha.99",
+    "@pierre/diffs": "^1.5.1",
+    "effect": "^4.0.0",
+    "smol-toml": "^1.9.0",
     "valibot": "^1.5.0"
   },
   "engines": {

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/api.ts

@@ -52,6 +52,7 @@ import {
   type MessageOutcome,
   type WorkspaceKey,
 } from "@cueloop/schema";
+import { findOperationReceipt, operationFingerprint } from "./operation-receipts";
 import { curateDiff } from "./curate";
 import { ThreadStore, withHistory } from "./store";
 import { pruneExpiredSessions, resolveCleanupPeriodDays } from "./retention";
@@ -429,6 +430,7 @@ export class DaemonCore {
     authorName?: string,
   ): Thread {
     const session = this.mutable(id);
+
     // a welcome-playground note is ephemeral by design: never persisted, so never fed back
     if (annotationTarget(annotation).kind === "welcome") return session;
     const existing = session.annotations.findIndex((candidate) => candidate.id === annotation.id);
@@ -650,6 +652,7 @@ export class DaemonCore {
       this.vcsSources.select(cwd),
       resolveWorkspace(cwd),
     ]);
+
     workspace.repoRoot = selected.repoRoot;
     const key = `${workspace.rootCommit ?? selected.repoRoot}:${selected.adapter.id}`;
     // an open workbench is reused; a resolved one is immutable and would reject the note, so a fresh
@@ -892,8 +895,19 @@ export class DaemonCore {
     outcome: MessageOutcome,
     summary: string,
     actionBodies?: Record<string, string>,
+    operationId?: string,
   ): Thread {
-    const session = this.mutable(id);
+    const current = this.sessionGet(id);
+    const fingerprint = operationFingerprint([
+      outcome,
+      summary,
+      Object.entries(actionBodies ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+    ]);
+    const receipt = findOperationReceipt(current.messageOperations, operationId, fingerprint);
+
+    if (receipt) return { ...structuredClone(current), message: structuredClone(receipt.result) };
+    const mutable = this.mutable(id);
+    const session = operationId ? structuredClone(mutable) : mutable;
     const sentAt = new Date().toISOString();
     const sentAnnotations = new Map(
       (session.history?.entries ?? [])
@@ -916,6 +930,8 @@ export class DaemonCore {
       sentAt,
     };
 
+    if (operationId)
+      (session.messageOperations ??= []).push({ operationId, fingerprint, result: message });
     session.message = message;
     session.status = outcome === "comment" ? "pending" : "resolved";
     const entryId = this.record(session, {
@@ -923,6 +939,7 @@ export class DaemonCore {
       message,
       createdAt: message.sentAt,
     });
+
     this.store.upsert(session);
     this.reconcileDeliveries(session);
     this.emit("message.sent", id, entryId);
@@ -980,6 +997,7 @@ export class DaemonCore {
       content,
       createdAt: now,
     });
+
     delete session.workingCopy;
     delete session.textCuts;
     session.message = null;

package/src/capabilities.ts

@@ -18,6 +18,13 @@ 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.reply": "owner",
+  "agent.permission": "owner",
   "daemon.ping": "any",
   "daemon.hello": "any",
   "daemon.shutdown": "owner",

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

@@ -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"]);
+});