macroclaw 0.8.0 → 0.10.0

package/src/claude.test.ts

@@ -1,15 +1,16 @@
 import { afterEach, describe, expect, it, mock } from "bun:test";
-import { Claude, type ClaudeDeferredResult, ClaudeParseError, ClaudeProcessError, type ClaudeResult, type ClaudeRunOptions, isDeferred } from "./claude";
+import { z } from "zod/v4";
+import { Claude, QueryParseError, QueryProcessError, QueryValidationError } from "./claude";
 
-function jsonResult(structuredOutput: unknown, sessionId = "test-session-id"): string {
+function envelope(opts: { structuredOutput?: unknown; result?: string; sessionId?: string; durationMs?: number; costUsd?: number }): string {
   return JSON.stringify({
     type: "result",
     subtype: "success",
-    duration_ms: 1234,
-    total_cost_usd: 0.05,
-    result: "",
-    session_id: sessionId,
-    structured_output: structuredOutput,
+    duration_ms: opts.durationMs ?? 1234,
+    total_cost_usd: opts.costUsd ?? 0.05,
+    result: opts.result ?? "",
+    session_id: opts.sessionId ?? "server-sid",
+    structured_output: opts.structuredOutput,
   });
 }
 
@@ -19,247 +20,296 @@ afterEach(() => {
   Bun.spawn = originalSpawn;
 });
 
-function mockSpawn(opts: {
-  stdout?: string;
-  stderr?: string;
-  exitCode?: number;
-}) {
+function mockSpawn(opts: { stdout?: string; stderr?: string; exitCode?: number }) {
   const proc = {
     stdout: new Response(opts.stdout ?? "").body,
     stderr: new Response(opts.stderr ?? "").body,
     exited: Promise.resolve(opts.exitCode ?? 0),
     kill: mock(() => {}),
   };
-
   Bun.spawn = mock((() => proc) as any);
   return proc;
 }
 
-const TEST_WORKSPACE = "/tmp/macroclaw-test-workspace";
-const DUMMY_SCHEMA = '{"type":"object"}';
+function mockHangingSpawn(stdout: string) {
+  let resolveExited!: (code: number) => void;
+  const proc = {
+    stdout: new Response(stdout).body,
+    stderr: new Response("").body,
+    exited: new Promise<number>((resolve) => {
+      resolveExited = resolve;
+    }),
+    kill: mock(() => {}),
+  };
+  Bun.spawn = mock((() => proc) as any);
+  return { proc, resolveExited };
+}
+
+const TEST_WORKSPACE = "/tmp/claude2-test";
 
-function makeClaude() {
-  return new Claude({ workspace: TEST_WORKSPACE, jsonSchema: DUMMY_SCHEMA });
+function makeClaude(config?: { model?: string; systemPrompt?: string }) {
+  return new Claude({ workspace: TEST_WORKSPACE, ...config });
 }
 
-function opts(overrides?: Partial<ClaudeRunOptions>): ClaudeRunOptions {
-  return {
-    prompt: "test message",
-    sessionId: "sid-1",
-    ...overrides,
-  };
+const textResult = { type: "text" } as const;
+
+function objectResult(schema?: z.ZodType) {
+  return { type: "object" as const, schema: schema ?? z.any() };
 }
 
-async function runSync(claude: Claude, options: ClaudeRunOptions): Promise<ClaudeResult> {
-  const result = await claude.run(options);
-  if (isDeferred(result)) throw new Error("Expected sync result, got deferred");
-  return result;
+function spawnArgs(): string[] {
+  return (Bun.spawn as any).mock.calls[0][0] as string[];
 }
 
 describe("Claude", () => {
-  it("passes --session-id flag when resume is false/unset", async () => {
-    mockSpawn({ stdout: jsonResult({ action: "send", message: "Hello" }), exitCode: 0 });
-    const claude = makeClaude();
-    const result = await runSync(claude, opts());
-    expect(result.structuredOutput).toEqual({ action: "send", message: "Hello" });
-    expect(Bun.spawn).toHaveBeenCalledWith(
-      expect.arrayContaining(["claude", "-p", "--session-id", "sid-1", "--output-format", "json", "--json-schema"]),
-      expect.objectContaining({ cwd: TEST_WORKSPACE, stdout: "pipe", stderr: "pipe" }),
-    );
-  });
-
-  it("passes --resume flag when resume is true", async () => {
-    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
-    const claude = makeClaude();
-    await claude.run(opts({ resume: true, sessionId: "sid-2" }));
-    expect(Bun.spawn).toHaveBeenCalledWith(
-      expect.arrayContaining(["claude", "-p", "--resume", "sid-2"]),
-      expect.objectContaining({ cwd: TEST_WORKSPACE }),
-    );
+  describe("newSession", () => {
+    it("uses --session-id with a generated UUID", async () => {
+      mockSpawn({ stdout: envelope({ result: "hi" }), exitCode: 0 });
+      const claude = makeClaude();
+      const query = claude.newSession("hello", textResult);
+
+      expect(query.sessionId).toMatch(/^[0-9a-f-]{36}$/);
+      const args = spawnArgs();
+      expect(args).toContain("--session-id");
+      expect(args).toContain(query.sessionId);
+      expect(args).not.toContain("--resume");
+      expect(args).not.toContain("--fork-session");
+
+      await query.result;
+    });
+
+    it("returns text value for text resultType", async () => {
+      mockSpawn({ stdout: envelope({ result: "hello world" }), exitCode: 0 });
+      const claude = makeClaude();
+      const { value } = await claude.newSession("hi", textResult).result;
+      expect(value).toBe("hello world");
+    });
+
+    it("returns parsed value for object resultType", async () => {
+      mockSpawn({ stdout: envelope({ structuredOutput: { action: "send", message: "hi" } }), exitCode: 0 });
+      const claude = makeClaude();
+      const schema = objectResult();
+      const { value } = await claude.newSession("hi", schema).result;
+      expect(value).toEqual({ action: "send", message: "hi" });
+    });
   });
 
-  it("passes model flag when provided", async () => {
-    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
-    const claude = makeClaude();
-    await claude.run(opts({ sessionId: "sid-3", model: "haiku", prompt: "msg" }));
-    expect(Bun.spawn).toHaveBeenCalledWith(
-      expect.arrayContaining(["--model", "haiku", "msg"]),
-      expect.objectContaining({ cwd: TEST_WORKSPACE }),
-    );
+  describe("resumeSession", () => {
+    it("uses --resume with the provided sessionId", async () => {
+      mockSpawn({ stdout: envelope({ result: "resumed" }), exitCode: 0 });
+      const claude = makeClaude();
+      const query = claude.resumeSession("existing-sid", "continue", textResult);
+
+      expect(query.sessionId).toBe("existing-sid");
+      const args = spawnArgs();
+      expect(args).toContain("--resume");
+      expect(args).toContain("existing-sid");
+      expect(args).not.toContain("--session-id");
+      expect(args).not.toContain("--fork-session");
+
+      await query.result;
+    });
   });
 
-  it("passes --append-system-prompt when provided", async () => {
-    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
-    const claude = makeClaude();
-    await claude.run(opts({ sessionId: "sid-4", systemPrompt: "You are a background agent.", prompt: "msg" }));
-    expect(Bun.spawn).toHaveBeenCalledWith(
-      expect.arrayContaining(["--append-system-prompt", "You are a background agent.", "msg"]),
-      expect.objectContaining({ cwd: TEST_WORKSPACE }),
-    );
+  describe("forkSession", () => {
+    it("generates a new session ID and passes parent via --resume", async () => {
+      mockSpawn({ stdout: envelope({ result: "forked" }), exitCode: 0 });
+      const claude = makeClaude();
+      const query = claude.forkSession("parent-sid", "bg task", textResult);
+
+      expect(query.sessionId).toMatch(/^[0-9a-f-]{36}$/);
+      expect(query.sessionId).not.toBe("parent-sid");
+      const args = spawnArgs();
+      expect(args).toContain("--resume");
+      expect(args).toContain("parent-sid");
+      expect(args).toContain("--fork-session");
+      expect(args).toContain("--session-id");
+      expect(args).toContain(query.sessionId);
+
+      await query.result;
+    });
   });
 
-  it("passes --fork-session when forkSession is true", async () => {
-    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
-    const claude = makeClaude();
-    await claude.run(opts({ resume: true, sessionId: "sid-fork", forkSession: true, prompt: "bg task" }));
-    expect(Bun.spawn).toHaveBeenCalledWith(
-      expect.arrayContaining(["--resume", "sid-fork", "--fork-session"]),
-      expect.objectContaining({ cwd: TEST_WORKSPACE }),
-    );
+  describe("options", () => {
+    it("uses constructor model as default", async () => {
+      mockSpawn({ stdout: envelope({ result: "ok" }), exitCode: 0 });
+      const claude = makeClaude({ model: "sonnet" });
+      await claude.newSession("hi", textResult).result;
+      expect(spawnArgs()).toContain("sonnet");
+    });
+
+    it("per-call model overrides constructor model", async () => {
+      mockSpawn({ stdout: envelope({ result: "ok" }), exitCode: 0 });
+      const claude = makeClaude({ model: "sonnet" });
+      await claude.newSession("hi", textResult, { model: "haiku" }).result;
+      const args = spawnArgs();
+      expect(args).toContain("haiku");
+      expect(args).not.toContain("sonnet");
+    });
+
+    it("uses constructor systemPrompt as default", async () => {
+      mockSpawn({ stdout: envelope({ result: "ok" }), exitCode: 0 });
+      const claude = makeClaude({ systemPrompt: "Be helpful." });
+      await claude.newSession("hi", textResult).result;
+      const args = spawnArgs();
+      expect(args).toContain("--append-system-prompt");
+      expect(args).toContain("Be helpful.");
+    });
+
+    it("per-call systemPrompt overrides constructor systemPrompt", async () => {
+      mockSpawn({ stdout: envelope({ result: "ok" }), exitCode: 0 });
+      const claude = makeClaude({ systemPrompt: "Be helpful." });
+      await claude.newSession("hi", textResult, { systemPrompt: "Be brief." }).result;
+      const args = spawnArgs();
+      expect(args).toContain("Be brief.");
+      expect(args).not.toContain("Be helpful.");
+    });
+
+    it("omits --model when none specified", async () => {
+      mockSpawn({ stdout: envelope({ result: "ok" }), exitCode: 0 });
+      const claude = makeClaude();
+      await claude.newSession("hi", textResult).result;
+      expect(spawnArgs()).not.toContain("--model");
+    });
+
+    it("omits --append-system-prompt when none specified", async () => {
+      mockSpawn({ stdout: envelope({ result: "ok" }), exitCode: 0 });
+      const claude = makeClaude();
+      await claude.newSession("hi", textResult).result;
+      expect(spawnArgs()).not.toContain("--append-system-prompt");
+    });
   });
 
-  it("omits --fork-session when not specified", async () => {
-    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
-    const claude = makeClaude();
-    await claude.run(opts({ sessionId: "sid-nofork" }));
-    const args = (Bun.spawn as any).mock.calls[0][0] as string[];
-    expect(args).not.toContain("--fork-session");
+  describe("resultType", () => {
+    it("omits --json-schema for text resultType", async () => {
+      mockSpawn({ stdout: envelope({ result: "plain" }), exitCode: 0 });
+      const claude = makeClaude();
+      await claude.newSession("hi", textResult).result;
+      expect(spawnArgs()).not.toContain("--json-schema");
+    });
+
+    it("passes --json-schema for object resultType", async () => {
+      mockSpawn({ stdout: envelope({ structuredOutput: { ok: true } }), exitCode: 0 });
+      const claude = makeClaude();
+      const schema = objectResult();
+      await claude.newSession("hi", schema).result;
+      const args = spawnArgs();
+      expect(args).toContain("--json-schema");
+    });
+
+    it("validates structured output through schema.parse", async () => {
+      mockSpawn({ stdout: envelope({ structuredOutput: { count: 5 } }), exitCode: 0 });
+      const claude = makeClaude();
+      const schema = objectResult(z.object({ count: z.number() }));
+      const { value } = await claude.newSession("hi", schema).result;
+      expect(value).toEqual({ count: 5 });
+    });
   });
 
-  it("omits --append-system-prompt when undefined", async () => {
-    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
-    const claude = makeClaude();
-    await claude.run(opts({ sessionId: "sid-5" }));
-    const args = (Bun.spawn as any).mock.calls[0][0] as string[];
-    expect(args).not.toContain("--append-system-prompt");
+  describe("metadata", () => {
+    it("returns duration and cost", async () => {
+      mockSpawn({ stdout: envelope({ result: "ok", durationMs: 2500, costUsd: 0.123 }), exitCode: 0 });
+      const claude = makeClaude();
+      const { duration, cost } = await claude.newSession("hi", textResult).result;
+      expect(duration).toBe("2.5s");
+      expect(cost).toBe("$0.1230");
+    });
+
+    it("returns sessionId from server envelope", async () => {
+      mockSpawn({ stdout: envelope({ result: "ok", sessionId: "server-returned-sid" }), exitCode: 0 });
+      const claude = makeClaude();
+      const { sessionId } = await claude.newSession("hi", textResult).result;
+      expect(sessionId).toBe("server-returned-sid");
+    });
+
+    it("sets startedAt on the running query", () => {
+      mockSpawn({ stdout: envelope({ result: "ok" }), exitCode: 0 });
+      const claude = makeClaude();
+      const before = new Date();
+      const query = claude.newSession("hi", textResult);
+      const after = new Date();
+      expect(query.startedAt.getTime()).toBeGreaterThanOrEqual(before.getTime());
+      expect(query.startedAt.getTime()).toBeLessThanOrEqual(after.getTime());
+    });
   });
 
-  it("omits --json-schema when plainText is true", async () => {
-    const envelope = JSON.stringify({ type: "result", result: "status update", duration_ms: 100, total_cost_usd: 0.01, session_id: "sid-pt" });
-    mockSpawn({ stdout: envelope, exitCode: 0 });
-    const claude = makeClaude();
-    const result = await runSync(claude, opts({ sessionId: "sid-pt", plainText: true }));
-    const args = (Bun.spawn as any).mock.calls[0][0] as string[];
-    expect(args).not.toContain("--json-schema");
-    expect(args).toContain("--output-format");
-    expect(result.result).toBe("status update");
+  describe("errors", () => {
+    it("rejects with QueryProcessError on non-zero exit", async () => {
+      mockSpawn({ stderr: "boom", exitCode: 1 });
+      const claude = makeClaude();
+      try {
+        await claude.newSession("hi", textResult).result;
+        expect.unreachable("should have thrown");
+      } catch (err) {
+        expect(err).toBeInstanceOf(QueryProcessError);
+        expect((err as QueryProcessError).exitCode).toBe(1);
+        expect((err as QueryProcessError).stderr).toBe("boom");
+      }
+    });
+
+    it("rejects with QueryParseError on invalid JSON", async () => {
+      mockSpawn({ stdout: "not json", exitCode: 0 });
+      const claude = makeClaude();
+      try {
+        await claude.newSession("hi", textResult).result;
+        expect.unreachable("should have thrown");
+      } catch (err) {
+        expect(err).toBeInstanceOf(QueryParseError);
+        expect((err as QueryParseError).raw).toBe("not json");
+      }
+    });
+
+    it("rejects with QueryValidationError when schema.parse throws", async () => {
+      mockSpawn({ stdout: envelope({ structuredOutput: { bad: true } }), exitCode: 0 });
+      const claude = makeClaude();
+      const schema = objectResult(z.object({ count: z.number() }).strict());
+      try {
+        await claude.newSession("hi", schema).result;
+        expect.unreachable("should have thrown");
+      } catch (err) {
+        expect(err).toBeInstanceOf(QueryValidationError);
+        expect((err as QueryValidationError).raw).toEqual({ bad: true });
+      }
+    });
   });
 
-  it("includes --json-schema when plainText is not set", async () => {
-    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
-    const claude = makeClaude();
-    await claude.run(opts({ sessionId: "sid-schema" }));
-    const args = (Bun.spawn as any).mock.calls[0][0] as string[];
-    expect(args).toContain("--json-schema");
-  });
-
-  it("throws ClaudeProcessError on non-zero exit", async () => {
-    mockSpawn({ stderr: "something went wrong", exitCode: 1 });
-    const claude = makeClaude();
-    try {
-      await claude.run(opts({ sessionId: "sid-6" }));
-      expect.unreachable("should have thrown");
-    } catch (err) {
-      expect(err).toBeInstanceOf(ClaudeProcessError);
-      expect((err as ClaudeProcessError).exitCode).toBe(1);
-      expect((err as ClaudeProcessError).stderr).toBe("something went wrong");
-    }
-  });
+  describe("kill", () => {
+    it("kills the process and waits for exit", async () => {
+      const { proc, resolveExited } = mockHangingSpawn(envelope({ result: "done" }));
+      const claude = makeClaude();
+      const query = claude.newSession("hi", textResult);
 
-  it("returns deferred result when process exceeds timeout", async () => {
-    let resolveExited!: (code: number) => void;
-    const stdoutData = jsonResult({ action: "send", message: "done" });
-    const proc = {
-      stdout: new Response(stdoutData).body,
-      stderr: new Response("").body,
-      exited: new Promise<number>((resolve) => {
-        resolveExited = resolve;
-      }),
-      kill: mock(() => {}),
-    };
-
-    const origSetTimeout = globalThis.setTimeout;
-    globalThis.setTimeout = ((fn: Function) => {
-      fn();
-      return 0 as any;
-    }) as any;
-
-    Bun.spawn = mock((() => proc) as any);
-    const claude = makeClaude();
-    try {
-      const result = await claude.run(opts({ sessionId: "sid-7", timeoutMs: 60_000 }));
-      expect("deferred" in result && result.deferred).toBe(true);
-      const deferred = result as ClaudeDeferredResult;
-      expect(deferred.sessionId).toBe("sid-7");
-
-      // Process hasn't been killed
-      expect(proc.kill).not.toHaveBeenCalled();
-
-      // Resolve the process — completion should resolve
+      const killPromise = query.kill();
       resolveExited(0);
-      const completed = await deferred.completion;
-      expect(completed.structuredOutput).toEqual({ action: "send", message: "done" });
-    } finally {
-      globalThis.setTimeout = origSetTimeout;
-    }
-  });
-
-  it("returns structured_output from successful response", async () => {
-    mockSpawn({ stdout: jsonResult({ action: "silent", actionReason: "no new results" }), exitCode: 0 });
-    const claude = makeClaude();
-    const result = await runSync(claude, opts({ resume: true, sessionId: "sid-8" }));
-    expect(result.structuredOutput).toEqual({ action: "silent", actionReason: "no new results" });
-    expect(result.sessionId).toBe("test-session-id");
-  });
-
-  it("returns null structuredOutput and result text when structured_output is missing", async () => {
-    const envelope = JSON.stringify({ type: "result", result: "plain text", duration_ms: 100, total_cost_usd: 0.01, session_id: "sid-abc" });
-    mockSpawn({ stdout: envelope, exitCode: 0 });
-    const claude = makeClaude();
-    const result = await runSync(claude, opts({ resume: true, sessionId: "sid-9" }));
-    expect(result.structuredOutput).toBeNull();
-    expect(result.result).toBe("plain text");
-    expect(result.sessionId).toBe("sid-abc");
-  });
-
-  it("returns empty sessionId when session_id is missing from envelope", async () => {
-    const envelope = JSON.stringify({ type: "result", result: "text", duration_ms: 100, total_cost_usd: 0.01 });
-    mockSpawn({ stdout: envelope, exitCode: 0 });
-    const claude = makeClaude();
-    const result = await runSync(claude, opts({ resume: true, sessionId: "sid-9c" }));
-    expect(result.sessionId).toBe("");
-  });
-
-  it("returns result from envelope", async () => {
-    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
-    const claude = makeClaude();
-    const result = await runSync(claude, opts({ resume: true, sessionId: "sid-9b" }));
-    expect(result.result).toBe("");
-  });
-
-  it("throws ClaudeParseError when stdout is not valid JSON", async () => {
-    mockSpawn({ stdout: "not json at all", exitCode: 0 });
-    const claude = makeClaude();
-    try {
-      await runSync(claude, opts({ resume: true, sessionId: "sid-10" }));
-      expect.unreachable("should have thrown");
-    } catch (err) {
-      expect(err).toBeInstanceOf(ClaudeParseError);
-      expect((err as ClaudeParseError).raw).toBe("not json at all");
-    }
-  });
-
-  it("returns duration and cost from envelope", async () => {
-    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
-    const claude = makeClaude();
-    const result = await runSync(claude, opts({ resume: true, sessionId: "sid-11" }));
-    expect(result.duration).toBe("1.2s");
-    expect(result.cost).toBe("$0.0500");
-  });
-
-  it("does not set timeout when timeoutMs is not provided", async () => {
-    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
-    const claude = makeClaude();
-    const result = await runSync(claude, opts({ resume: true, sessionId: "sid-12" }));
-    expect(result.structuredOutput).toEqual({ action: "send" });
+      await killPromise;
+      expect(proc.kill).toHaveBeenCalled();
+    });
   });
 
-  it("passes jsonSchema to CLI args", async () => {
-    const schema = '{"type":"object","properties":{}}';
-    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
-    const claude = new Claude({ workspace: TEST_WORKSPACE, jsonSchema: schema });
-    await claude.run(opts({ sessionId: "sid-13" }));
-    const args = (Bun.spawn as any).mock.calls[0][0] as string[];
-    expect(args).toContain(schema);
+  describe("environment", () => {
+    it("strips CLAUDECODE env var", async () => {
+      mockSpawn({ stdout: envelope({ result: "ok" }), exitCode: 0 });
+      const claude = makeClaude();
+      await claude.newSession("hi", textResult).result;
+      const spawnOpts = (Bun.spawn as any).mock.calls[0][1];
+      expect(spawnOpts.env).not.toHaveProperty("CLAUDECODE");
+    });
+
+    it("spawns in the configured workspace directory", async () => {
+      mockSpawn({ stdout: envelope({ result: "ok" }), exitCode: 0 });
+      const claude = makeClaude();
+      await claude.newSession("hi", textResult).result;
+      const spawnOpts = (Bun.spawn as any).mock.calls[0][1];
+      expect(spawnOpts.cwd).toBe(TEST_WORKSPACE);
+    });
+
+    it("includes disallowedTools in CLI args", async () => {
+      mockSpawn({ stdout: envelope({ result: "ok" }), exitCode: 0 });
+      const claude = makeClaude();
+      await claude.newSession("hi", textResult).result;
+      const args = spawnArgs();
+      expect(args).toContain("--disallowedTools");
+      expect(args).toContain("CronList,CronDelete,CronCreate,AskUserQuestion");
+    });
   });
 });