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

package/src/daemon-sdk.ts

@@ -0,0 +1,397 @@
+import * as v from "valibot";
+import {
+  newAnnotationId,
+  type Annotation,
+  type Artifact,
+  type Message,
+  type MessageOutcome,
+  type Thread,
+  type ThreadAgentState,
+  type WorkspaceKey,
+} from "@cueloop/schema";
+import { DaemonClient, DaemonClientError, type ConnectOptions } from "./client";
+import { DaemonTransportError, type DaemonRequestOptions } from "./client-errors";
+import {
+  createSdkThreadId,
+  createSdkOperationId,
+  createSdkSubmissionId,
+  type SdkThreadId,
+  type SdkOperationId,
+  type SdkSubmissionId,
+} from "./sdk-identities";
+export {
+  createSdkThreadId,
+  createSdkOperationId,
+  createSdkSubmissionId,
+  type SdkThreadId,
+  type SdkOperationId,
+  type SdkSubmissionId,
+} from "./sdk-identities";
+import { ThreadRecordSchema } from "./validate";
+import { ThreadAgentSchema } from "./thread-agent-validation";
+import { connectThreadObserver, subscribeThreadState } from "./thread-subscription";
+
+/** Validated SDK Thread reads carry a distinct identity without changing the wire model. */
+export type SdkThread = Thread & { id: SdkThreadId };
+const SdkThreadRecordSchema = v.pipe(
+  ThreadRecordSchema,
+  v.transform((thread): SdkThread => ({ ...thread, id: createSdkThreadId(thread.id) })),
+);
+
+/** These errors preserve daemon rejection codes and uncertainty after a lost response. */
+export type DaemonSdkError = DaemonClientError | DaemonTransportError;
+
+/** Acceptance identifies the exact batch; idle Thread state alone does not prove completion. */
+export interface AgentAcceptance {
+  threadId: SdkThreadId;
+  operationId: SdkOperationId;
+  submissionIds: readonly SdkSubmissionId[];
+}
+
+/** Explicit cancellation and failed execution remain distinct terminal outcomes. */
+export interface AgentCompletion extends AgentAcceptance {
+  outcome: "completed" | "failed" | "cancelled";
+  state: ThreadAgentState;
+}
+
+/** A review capability cannot create Threads, submit agents, or resolve reviews. */
+export class ReviewDaemonSdk {
+  readonly ids = {
+    thread: createSdkThreadId,
+    operation: createSdkOperationId,
+    submission: createSdkSubmissionId,
+  };
+
+  protected closed = false;
+  private readonly observers = new Set<() => void>();
+
+  constructor(
+    protected readonly client: DaemonClient,
+    protected readonly connectionOptions: ConnectOptions = {},
+  ) {}
+
+  /** Snapshot observation owns a separate connection and never replays mutations. */
+  observeThread(input: {
+    threadId: SdkThreadId;
+    onValue: (thread: SdkThread) => void;
+    onError: (error: DaemonSdkError) => void;
+  }): () => void {
+    if (this.closed) {
+      input.onError(new DaemonTransportError("connection", "SDK connection is closed", "not_sent"));
+
+      return () => {};
+    }
+    const dispose = subscribeThreadState({
+      connect: connectThreadObserver(this.connectionOptions),
+      matches: (event) => event.sessionId === input.threadId,
+      read: (client, signal) =>
+        client.request("session.get", { id: input.threadId }, SdkThreadRecordSchema, { signal }),
+      onValue: input.onValue,
+      onError: (error) => input.onError(normalizeSdkError(error)),
+    });
+    const stop = () => {
+      dispose();
+      this.observers.delete(stop);
+    };
+
+    this.observers.add(stop);
+
+    return stop;
+  }
+
+  get threads() {
+    return {
+      get: (threadId: SdkThreadId, options?: DaemonRequestOptions): Promise<SdkThread> =>
+        this.client.request("session.get", { id: threadId }, SdkThreadRecordSchema, options),
+    };
+  }
+
+  readonly comments = {
+    add: (
+      input: { threadId: SdkThreadId; annotation: Parameters<DaemonClient["sessionComment"]>[1] },
+      options?: DaemonRequestOptions,
+    ): Promise<SdkThread> =>
+      this.client.request(
+        "session.comment",
+        { id: input.threadId, annotation: input.annotation },
+        SdkThreadRecordSchema,
+        options,
+      ),
+    list: async (threadId: SdkThreadId, options?: DaemonRequestOptions): Promise<Annotation[]> =>
+      (await this.threads.get(threadId, options)).annotations,
+    reply: async (
+      input: { threadId: SdkThreadId; commentId: string; body: string; replyId?: string },
+      options?: DaemonRequestOptions,
+    ): Promise<SdkThread> => {
+      const thread = await this.threads.get(input.threadId, options);
+      const comment = thread.annotations.find((entry) => entry.id === input.commentId);
+
+      if (!comment)
+        throw new DaemonClientError("not_found", "SDK comment reply target does not exist");
+      const rootId = comment.replyTo ?? comment.id;
+      const root = thread.annotations.find((entry) => entry.id === rootId);
+
+      if (!root) throw new DaemonClientError("not_found", "SDK comment reply root does not exist");
+
+      return this.client.request(
+        "session.comment",
+        {
+          id: input.threadId,
+          annotation: {
+            id: input.replyId ?? newAnnotationId(),
+            kind: "comment",
+            anchor: root.anchor,
+            target: root.target,
+            replyTo: root.id,
+            body: input.body,
+          },
+        },
+        SdkThreadRecordSchema,
+        options,
+      );
+    },
+  };
+
+  close(): void {
+    this.closed = true;
+    for (const stop of this.observers) stop();
+    this.client.close();
+  }
+}
+
+/** Owner methods still require daemon token authorization and the experimental agent flag. */
+export class OwnerDaemonSdk extends ReviewDaemonSdk {
+  get threads() {
+    return {
+      ...super.threads,
+      create: (
+        input: { workspace: WorkspaceKey; artifact: Artifact },
+        options?: DaemonRequestOptions,
+      ): Promise<SdkThread> =>
+        this.client.request("session.create", input, SdkThreadRecordSchema, options),
+    };
+  }
+
+  readonly sessions = {
+    sendMessage: async (
+      input: {
+        threadId: SdkThreadId;
+        operationId: SdkOperationId;
+        outcome: MessageOutcome;
+        summary: string;
+        actionBodies?: Record<string, string>;
+      },
+      options?: DaemonRequestOptions,
+    ): Promise<Message> => {
+      const thread = await this.client.sessionSendMessage(
+        input.threadId,
+        input.outcome,
+        input.summary,
+        input.actionBodies,
+        input.operationId,
+        options,
+      );
+
+      if (!thread.message)
+        throw new DaemonTransportError(
+          "protocol",
+          "SDK accepted review message is missing",
+          "unknown",
+          "session.sendMessage",
+        );
+
+      return thread.message;
+    },
+  };
+
+  readonly agents = {
+    get: (threadId: SdkThreadId, options?: DaemonRequestOptions): Promise<ThreadAgentState> =>
+      this.client.request("agent.get", { id: threadId }, ThreadAgentSchema, options),
+    prompt: async (
+      input: {
+        threadId: SdkThreadId;
+        operationId: SdkOperationId;
+        text: string;
+        context?: string;
+        retry?: SdkSubmissionId;
+      },
+      options?: DaemonRequestOptions,
+    ): Promise<AgentAcceptance> => {
+      const state = await this.client.agentPrompt(
+        {
+          id: input.threadId,
+          operationId: input.operationId,
+          text: input.text,
+          context: input.context,
+          retry: input.retry,
+        },
+        options,
+      );
+      const receipt = state.promptOperations?.find(
+        (entry) => entry.operationId === input.operationId,
+      );
+
+      if (!receipt)
+        throw new DaemonTransportError(
+          "protocol",
+          "SDK accepted agent operation receipt is missing",
+          "unknown",
+          "agent.prompt",
+        );
+
+      return {
+        threadId: input.threadId,
+        operationId: input.operationId,
+        submissionIds: receipt.result.map(createSdkSubmissionId),
+      };
+    },
+    replyToComment: (
+      input: { threadId: SdkThreadId; commentId: string; body: string },
+      options?: DaemonRequestOptions,
+    ): Promise<ThreadAgentState> =>
+      this.client.request(
+        "agent.reply",
+        { id: input.threadId, commentId: input.commentId, body: input.body },
+        ThreadAgentSchema,
+        options,
+      ),
+    wait: (accepted: AgentAcceptance, options?: DaemonRequestOptions): Promise<AgentCompletion> =>
+      this.waitAgentCompletion(accepted, options),
+    cancel: (threadId: SdkThreadId, options?: DaemonRequestOptions): Promise<ThreadAgentState> =>
+      this.client.request("agent.cancel", { id: threadId }, ThreadAgentSchema, options),
+  };
+
+  private readonly waits = new Set<AbortController>();
+
+  override close(): void {
+    this.closed = true;
+    for (const wait of this.waits) wait.abort();
+    super.close();
+  }
+
+  private waitAgentCompletion(
+    accepted: AgentAcceptance,
+    options: DaemonRequestOptions = {},
+  ): Promise<AgentCompletion> {
+    if (this.closed)
+      return Promise.reject(
+        new DaemonTransportError("connection", "SDK connection is closed", "not_sent"),
+      );
+    if (!accepted.submissionIds.length)
+      return Promise.reject(
+        new DaemonClientError("invalid_params", "SDK wait requires accepted submissions"),
+      );
+
+    const controller = new AbortController();
+
+    this.waits.add(controller);
+    const signal = options.signal
+      ? AbortSignal.any([controller.signal, options.signal])
+      : controller.signal;
+
+    return new Promise((resolve, reject) => {
+      let done = false;
+      let detach: (() => void) | undefined;
+      const finish = (result?: AgentCompletion, error?: DaemonSdkError) => {
+        if (done) return;
+        done = true;
+        clearTimeout(timer);
+        signal.removeEventListener("abort", abort);
+        this.waits.delete(controller);
+        detach?.();
+        if (result) resolve(result);
+        else reject(error);
+      };
+      const abort = () =>
+        finish(
+          undefined,
+          new DaemonTransportError("cancelled", "SDK agent wait cancelled locally", "not_sent"),
+        );
+      const timer = setTimeout(
+        () =>
+          finish(
+            undefined,
+            new DaemonTransportError(
+              "timeout",
+              "SDK agent completion deadline elapsed",
+              "not_sent",
+            ),
+          ),
+        options.timeoutMs ?? 30_000,
+      );
+
+      signal.addEventListener("abort", abort, { once: true });
+      if (signal.aborted) {
+        abort();
+
+        return;
+      }
+      detach = subscribeThreadState({
+        connect: connectThreadObserver(this.connectionOptions),
+        matches: (event) =>
+          event.event === "agent.updated" && event.sessionId === accepted.threadId,
+        read: (client, readSignal) =>
+          client.request("agent.get", { id: accepted.threadId }, ThreadAgentSchema, {
+            signal: readSignal,
+          }),
+        onValue: (state) => {
+          const receipt = state.promptOperations?.find(
+            (entry) => entry.operationId === accepted.operationId,
+          );
+
+          if (!receipt || receipt.result.join("\n") !== accepted.submissionIds.join("\n")) {
+            finish(
+              undefined,
+              new DaemonClientError("not_found", "SDK accepted agent operation no longer exists"),
+            );
+
+            return;
+          }
+          if (receipt.outcome) finish({ ...accepted, outcome: receipt.outcome, state });
+        },
+        onError: (error) => {
+          if (
+            error instanceof DaemonClientError ||
+            (error instanceof DaemonTransportError && error.kind === "protocol")
+          )
+            finish(undefined, normalizeSdkError(error));
+        },
+      });
+    });
+  }
+
+  constructor(client: DaemonClient, connectionOptions: ConnectOptions) {
+    super(client, connectionOptions);
+  }
+}
+
+/** Choose capabilities at connection time; the daemon remains the authority. */
+export async function connectOwnerSdk(
+  options: Omit<ConnectOptions, "role"> = {},
+): Promise<OwnerDaemonSdk> {
+  return new OwnerDaemonSdk(await DaemonClient.connect({ ...options, role: "owner" }), {
+    ...options,
+    role: "owner",
+  });
+}
+
+/** Collaborators and review agents expose only shared review operations. */
+export async function connectReviewSdk(
+  options: ConnectOptions & { role: "collaborator" | "agent" },
+): Promise<ReviewDaemonSdk> {
+  return new ReviewDaemonSdk(await DaemonClient.connect(options), options);
+}
+
+/** Preserve typed failures; unexpected transport exceptions carry their original cause. */
+// eslint-disable-next-line type-evidence/no-unknown-parameters -- Promise rejection is an untyped transport boundary.
+export function normalizeSdkError(error: unknown): DaemonSdkError {
+  if (error instanceof DaemonClientError || error instanceof DaemonTransportError) return error;
+
+  return new DaemonTransportError(
+    "connection",
+    "SDK daemon operation failed",
+    "unknown",
+    undefined,
+    { cause: error },
+  );
+}

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