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

package/src/daemon-sdk.test.ts

@@ -0,0 +1,306 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Effect, Stream } from "effect";
+import { DaemonServer } from "./server";
+import { DaemonClient } from "./client";
+import { connectOwnerSdk, connectReviewSdk } from "./daemon-sdk";
+import { CueloopSdk } from "./daemon-sdk-effect";
+
+import { createTestSdkHarness } from "../../../test/helpers/sdk-harness";
+
+test("SDK accepts once, waits for its own submission and cancelling a wait preserves work", async () => {
+  const home = mkdtempSync(join(tmpdir(), "cueloop-sdk-"));
+  const harness = createTestSdkHarness();
+  const server = new DaemonServer({
+    home,
+    idleExitMs: 0,
+    threadAgent: { enabled: true, adapter: harness.adapter },
+  });
+
+  server.start();
+  const sdk = await connectOwnerSdk({ home });
+
+  try {
+    const thread = await sdk.threads.create({
+      workspace: { repoRoot: home, branch: "main" },
+      artifact: { type: "plan", content: "Explain this", meta: {} },
+    });
+    const input = {
+      threadId: thread.id,
+      operationId: sdk.ids.operation("ask-once"),
+      text: "Explain",
+    };
+    const accepted = await sdk.agents.prompt(input);
+    const duplicate = await sdk.agents.prompt(input);
+
+    expect(duplicate).toEqual(accepted);
+    expect((await sdk.agents.get(thread.id)).submissions).toHaveLength(1);
+    await expect(sdk.agents.prompt({ ...input, text: "Different" })).rejects.toMatchObject({
+      code: "operation_conflict",
+    });
+    const cancel = new AbortController();
+    const abandonedWait = sdk.agents.wait(accepted, { signal: cancel.signal });
+
+    cancel.abort();
+    await expect(abandonedWait).rejects.toMatchObject({ kind: "cancelled" });
+    expect(harness.cancelled()).toBe(0);
+    const completed = sdk.agents.wait(accepted);
+
+    harness.complete();
+    expect((await completed).outcome).toBe("completed");
+    const message = {
+      threadId: thread.id,
+      operationId: sdk.ids.operation("approve-once"),
+      outcome: "approved" as const,
+      summary: "Good",
+    };
+    const sent = await sdk.sessions.sendMessage(message);
+
+    expect(await sdk.sessions.sendMessage(message)).toEqual(sent);
+  } finally {
+    sdk.close();
+    server.stop();
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("Effect scope supports review comments and typed owner-only capabilities", async () => {
+  const home = mkdtempSync(join(tmpdir(), "cueloop-sdk-effect-"));
+  const server = new DaemonServer({ home, idleExitMs: 0 });
+
+  server.start();
+
+  try {
+    const program = Effect.gen(function* () {
+      const sdk = yield* CueloopSdk;
+      const thread = yield* sdk.threads.create({
+        workspace: { repoRoot: home, branch: "main" },
+        artifact: { type: "plan", content: "Discuss this", meta: {} },
+      });
+      const snapshots = yield* sdk.threads.watch(thread.id).pipe(Stream.take(1), Stream.runCollect);
+
+      expect(snapshots[0]?.id).toBe(thread.id);
+      const client = yield* Effect.promise(() => DaemonClient.connect({ home }));
+
+      try {
+        yield* Effect.promise(() =>
+          client.sessionComment(thread.id, {
+            id: "comment",
+            kind: "comment",
+            anchor: { quote: "Discuss", prefix: "", suffix: " this" },
+            body: "Why?",
+          }),
+        );
+      } finally {
+        client.close();
+      }
+      yield* sdk.comments.reply({
+        threadId: thread.id,
+        commentId: "comment",
+        body: "Because",
+        replyId: "reply",
+      });
+      const comments = yield* sdk.comments.list(thread.id);
+
+      expect(comments.at(-1)).toMatchObject({ id: "reply", replyTo: "comment", body: "Because" });
+
+      return thread.id;
+    });
+    const id = await Effect.runPromise(
+      program.pipe(Effect.provide(CueloopSdk.ownerLayer({ home }))),
+    );
+    const review = await connectReviewSdk({ home, role: "agent", author: "review-agent" });
+
+    try {
+      expect((await review.threads.get(id)).id).toBe(id);
+      expect("agents" in review).toBe(false);
+      const capped = await DaemonClient.connect({ home, role: "agent", author: "review-agent" });
+
+      try {
+        await expect(capped.agentPrompt({ id, text: "Forbidden" })).rejects.toMatchObject({
+          code: "forbidden",
+        });
+      } finally {
+        capped.close();
+      }
+    } finally {
+      review.close();
+    }
+  } finally {
+    server.stop();
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("lost response after message commit is uncertain and an explicit retry survives server restart", async () => {
+  const home = mkdtempSync(join(tmpdir(), "cueloop-sdk-lost-response-"));
+  let server = new DaemonServer({ home, idleExitMs: 0 });
+
+  server.start();
+  const connection = await DaemonClient.connect({ home });
+
+  try {
+    const thread = await connection.sessionCreate(
+      { repoRoot: home, branch: "main" },
+      { type: "plan", content: "Approve this", meta: {} },
+    );
+    const send = server.core.sessionSendMessage.bind(server.core);
+
+    server.core.sessionSendMessage = (...args) => {
+      const result = send(...args);
+
+      connection.close();
+
+      return result;
+    };
+    await expect(
+      connection.sessionSendMessage(thread.id, "approved", "Done", undefined, "lost-ack"),
+    ).rejects.toMatchObject({ kind: "connection", certainty: "unknown" });
+    const original = server.core.sessionGet(thread.id).message;
+
+    server.stop();
+    server = new DaemonServer({ home, idleExitMs: 0 });
+    server.start();
+    const sdk = await connectOwnerSdk({ home });
+
+    try {
+      expect(
+        await sdk.sessions.sendMessage({
+          threadId: sdk.ids.thread(thread.id),
+          operationId: sdk.ids.operation("lost-ack"),
+          outcome: "approved",
+          summary: "Done",
+        }),
+      ).toEqual(original!);
+      expect(
+        (await sdk.threads.get(sdk.ids.thread(thread.id))).history?.entries.filter(
+          (entry) => entry.type === "message",
+        ),
+      ).toHaveLength(1);
+    } finally {
+      sdk.close();
+    }
+  } finally {
+    connection.close();
+    server.stop();
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("Effect interruption aborts the completion wait without stopping the harness", async () => {
+  const { Fiber } = await import("effect");
+  const home = mkdtempSync(join(tmpdir(), "cueloop-sdk-interrupt-"));
+  const harness = createTestSdkHarness();
+  const server = new DaemonServer({
+    home,
+    idleExitMs: 0,
+    threadAgent: { enabled: true, adapter: harness.adapter },
+  });
+
+  server.start();
+
+  try {
+    const program = Effect.gen(function* () {
+      const sdk = yield* CueloopSdk;
+      const thread = yield* sdk.threads.create({
+        workspace: { repoRoot: home, branch: "main" },
+        artifact: { type: "plan", content: "Explain", meta: {} },
+      });
+      const accepted = yield* sdk.agents.prompt({
+        threadId: thread.id,
+        operationId: sdk.ids.operation("interrupt"),
+        text: "Explain",
+      });
+      const fiber = yield* Effect.forkChild(sdk.agents.wait(accepted));
+
+      yield* Effect.yieldNow;
+      yield* Fiber.interrupt(fiber);
+      expect(harness.cancelled()).toBe(0);
+      yield* Effect.sync(() => harness.complete());
+      const completed = yield* sdk.agents.wait(accepted);
+
+      expect(completed.outcome).toBe("completed");
+    });
+
+    await Effect.runPromise(program.pipe(Effect.provide(CueloopSdk.ownerLayer({ home }))));
+  } finally {
+    server.stop();
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("lost prompt acknowledgement replays original acceptance after restart without a harness", async () => {
+  const home = mkdtempSync(join(tmpdir(), "cueloop-sdk-lost-prompt-"));
+  const harness = createTestSdkHarness();
+  let server = new DaemonServer({
+    home,
+    idleExitMs: 0,
+    threadAgent: { enabled: true, adapter: harness.adapter },
+  });
+
+  server.start();
+  const connection = await DaemonClient.connect({ home });
+
+  try {
+    const thread = await connection.sessionCreate(
+      { repoRoot: home, branch: "main" },
+      { type: "plan", content: "Explain", meta: {} },
+    );
+
+    await connection.subscribe();
+    connection.onEvent((event) => {
+      if (event.event === "agent.updated") connection.close();
+    });
+    await expect(
+      connection.agentPrompt({ id: thread.id, text: "Once", operationId: "lost-prompt" }),
+    ).rejects.toMatchObject({ kind: "connection", certainty: "unknown" });
+    const inspect = await DaemonClient.connect({ home });
+    const accepted = await inspect.agentGet(thread.id);
+
+    inspect.close();
+    server.stop();
+    server = new DaemonServer({ home, idleExitMs: 0, threadAgent: { enabled: true } });
+    server.start();
+    const sdk = await connectOwnerSdk({ home });
+
+    try {
+      const replay = await sdk.agents.prompt({
+        threadId: sdk.ids.thread(thread.id),
+        operationId: sdk.ids.operation("lost-prompt"),
+        text: "Once",
+      });
+
+      expect(replay.submissionIds).toEqual(
+        accepted.promptOperations![0]!.result.map(sdk.ids.submission),
+      );
+      expect((await sdk.agents.get(sdk.ids.thread(thread.id))).submissions).toHaveLength(1);
+      expect((await sdk.agents.wait(replay)).outcome).toBe("failed");
+    } finally {
+      sdk.close();
+    }
+  } finally {
+    connection.close();
+    server.stop();
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("SDK identity types distinguish Thread, operation, and submission capabilities", () => {
+  type ThreadId = import("./daemon-sdk").SdkThreadId;
+  type OperationId = import("./daemon-sdk").SdkOperationId;
+  type SubmissionId = import("./daemon-sdk").SdkSubmissionId;
+  type Review = import("./daemon-sdk").ReviewDaemonSdk;
+  const operationIsThread: OperationId extends ThreadId ? true : false = false;
+  const submissionIsOperation: SubmissionId extends OperationId ? true : false = false;
+  const reviewHasAgent: "agents" extends keyof Review ? true : false = false;
+  const reviewCreatesThread: "create" extends keyof Review["threads"] ? true : false = false;
+
+  expect([operationIsThread, submissionIsOperation, reviewHasAgent, reviewCreatesThread]).toEqual([
+    false,
+    false,
+    false,
+    false,
+  ]);
+});

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