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

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,29 +1,56 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.100",
+  "description": "The cueloop session daemon and its client: socket protocol, atomic store, resumable waits",
+  "homepage": "https://github.com/mmurakaru/cueloop#readme",
+  "bugs": {
+    "url": "https://github.com/mmurakaru/cueloop/issues"
+  },
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmurakaru/cueloop.git",
+    "directory": "packages/daemon"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "SDK.md"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./client": "./src/client.ts"
-  },
-  "dependencies": {
-    "@cueloop/schema": "workspace:*",
-    "valibot": "^1.4.2"
+    "./client": "./src/client.ts",
+    "./thread-review": "./src/thread-review.ts",
+    "./vcs-source": "./src/vcs-source.ts",
+    "./api": "./src/api.ts",
+    "./working-tree": "./src/working-tree.ts",
+    "./store": "./src/store.ts",
+    "./validate": "./src/validate.ts",
+    "./paths": "./src/paths.ts",
+    "./retention": "./src/retention.ts",
+    "./herdr-thread-surface": "./src/herdr-thread-surface.ts",
+    "./ghostty-thread-surface": "./src/ghostty-thread-surface.ts",
+    "./thread-surface-config": "./src/thread-surface-config.ts",
+    "./herdr-split": "./src/herdr-split.ts",
+    "./share-blob": "./src/share-blob.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"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
+  "dependencies": {
+    "@cueloop/extension-api": "0.1.0-alpha.100",
+    "@cueloop/schema": "0.1.0-alpha.100",
+    "@pierre/diffs": "^1.5.1",
+    "effect": "^4.0.0",
+    "smol-toml": "^1.9.0",
+    "valibot": "^1.5.0"
+  },
   "engines": {
     "bun": ">=1.3.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mmurakaru/cueloop.git",
-    "directory": "packages/daemon"
   }
-}
+}

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