macroclaw 0.0.0-dev

package/src/app.ts

@@ -0,0 +1,164 @@
+import type { Bot } from "grammy";
+import type { Claude } from "./claude";
+import { CronScheduler } from "./cron";
+import { createLogger } from "./logger";
+import { Orchestrator, type OrchestratorResponse } from "./orchestrator";
+import { isAvailable as isSttAvailable, transcribe } from "./stt";
+import { createBot, downloadFile, sendFile, sendResponse } from "./telegram";
+
+const log = createLogger("app");
+
+export interface AppConfig {
+  botToken: string;
+  authorizedChatId: string;
+  workspace: string;
+  model?: string;
+  settingsDir?: string;
+  claude?: Claude;
+}
+
+export class App {
+  #bot: Bot;
+  #orchestrator: Orchestrator;
+  #config: AppConfig;
+
+  constructor(config: AppConfig) {
+    this.#config = config;
+    this.#bot = createBot(config.botToken);
+    this.#orchestrator = new Orchestrator({
+      model: config.model,
+      workspace: config.workspace,
+      settingsDir: config.settingsDir,
+      claude: config.claude,
+      onResponse: (r) => this.#deliverResponse(r),
+    });
+
+    this.#setupHandlers();
+  }
+
+  get bot() {
+    return this.#bot;
+  }
+
+  start() {
+    log.info("Starting macroclaw...");
+    const cron = new CronScheduler(this.#config.workspace, {
+      onJob: (name, prompt, model) => this.#orchestrator.handleCron(name, prompt, model),
+    });
+    cron.start();
+    this.#bot.api.setMyCommands([
+      { command: "chatid", description: "Show current chat ID" },
+      { command: "session", description: "Show current session ID" },
+      { command: "bg", description: "List or spawn background agents" },
+    ]).catch((err) => log.error({ err }, "Failed to set commands"));
+    this.#bot.start({
+      onStart: (botInfo) => {
+        log.info({ username: botInfo.username, chatId: this.#config.authorizedChatId }, "Bot connected");
+      },
+    });
+  }
+
+  async #deliverResponse(response: OrchestratorResponse) {
+    if (response.files?.length) {
+      for (const filePath of response.files) {
+        await sendFile(this.#bot, this.#config.authorizedChatId, filePath);
+      }
+    }
+    await sendResponse(this.#bot, this.#config.authorizedChatId, response.message, response.buttons);
+  }
+
+  #setupHandlers() {
+    this.#bot.command("chatid", (ctx) => {
+      log.debug("Command /chatid");
+      ctx.reply(`Chat ID: \`${ctx.chat.id}\``, { parse_mode: "Markdown" });
+    });
+
+    this.#bot.command("session", (ctx) => {
+      if (ctx.chat.id.toString() !== this.#config.authorizedChatId) return;
+      log.debug("Command /session");
+      this.#orchestrator.handleSessionCommand();
+    });
+
+    this.#bot.command("bg", (ctx) => {
+      if (ctx.chat.id.toString() !== this.#config.authorizedChatId) return;
+      const prompt = ctx.match?.trim();
+      if (prompt) {
+        log.debug({ prompt }, "Command /bg spawn");
+        this.#orchestrator.handleBackgroundCommand(prompt);
+        return;
+      }
+      log.debug("Command /bg list");
+      this.#orchestrator.handleBackgroundList();
+    });
+
+    this.#bot.on("message:photo", async (ctx) => {
+      if (ctx.chat.id.toString() !== this.#config.authorizedChatId) return;
+      const photos = ctx.message.photo;
+      const largest = photos[photos.length - 1];
+      try {
+        const path = await downloadFile(this.#bot, largest.file_id, this.#config.botToken, "photo.jpg");
+        this.#orchestrator.handleMessage(ctx.message.caption ?? "", [path]);
+      } catch (err) {
+        log.error({ err }, "Photo download failed");
+        this.#orchestrator.handleMessage(`[File download failed: photo.jpg]\n${ctx.message.caption ?? ""}`);
+      }
+    });
+
+    this.#bot.on("message:document", async (ctx) => {
+      if (ctx.chat.id.toString() !== this.#config.authorizedChatId) return;
+      const doc = ctx.message.document;
+      const name = doc.file_name ?? "file";
+      try {
+        const path = await downloadFile(this.#bot, doc.file_id, this.#config.botToken, name);
+        this.#orchestrator.handleMessage(ctx.message.caption ?? "", [path]);
+      } catch (err) {
+        log.error({ err }, "Document download failed");
+        this.#orchestrator.handleMessage(`[File download failed: ${name}]\n${ctx.message.caption ?? ""}`);
+      }
+    });
+
+    this.#bot.on("message:voice", async (ctx) => {
+      if (ctx.chat.id.toString() !== this.#config.authorizedChatId) return;
+      if (!isSttAvailable()) {
+        await sendResponse(this.#bot, this.#config.authorizedChatId, "[Voice messages not available — set OPENAI_API_KEY to enable]");
+        return;
+      }
+      try {
+        const path = await downloadFile(this.#bot, ctx.message.voice.file_id, this.#config.botToken, "voice.ogg");
+        const text = await transcribe(path);
+        if (!text.trim()) {
+          await sendResponse(this.#bot, this.#config.authorizedChatId, "[Could not understand audio]");
+          return;
+        }
+        await sendResponse(this.#bot, this.#config.authorizedChatId, `[Received audio]: ${text}`);
+        this.#orchestrator.handleMessage(text);
+      } catch (err) {
+        log.error({ err }, "Voice transcription failed");
+        await sendResponse(this.#bot, this.#config.authorizedChatId, "[Failed to transcribe audio]");
+      }
+    });
+
+    this.#bot.on("callback_query:data", async (ctx) => {
+      await ctx.answerCallbackQuery();
+      const label = ctx.callbackQuery.data;
+      if (label === "_noop") return;
+      await ctx.editMessageReplyMarkup({ reply_markup: { inline_keyboard: [[{ text: `✓ ${label}`, callback_data: "_noop" }]] } });
+      if (ctx.chat?.id.toString() !== this.#config.authorizedChatId) return;
+      log.debug({ label }, "Button clicked");
+      this.#orchestrator.handleButton(label);
+    });
+
+    this.#bot.on("message:text", (ctx) => {
+      if (ctx.chat.id.toString() !== this.#config.authorizedChatId) {
+        log.debug({ chatId: ctx.chat.id }, "Unauthorized message");
+        return;
+      }
+
+      this.#orchestrator.handleMessage(ctx.message.text);
+    });
+
+    this.#bot.catch((err) => {
+      log.error({ err }, "Bot error");
+    });
+  }
+}

package/src/claude.integration-test.ts

@@ -0,0 +1,108 @@
+/**
+ * Integration test for Claude CLI structured output.
+ * Run manually: bun test src/claude.integration.test.ts --timeout 120000
+ */
+import { describe, expect, it } from "bun:test";
+import { randomUUID } from "node:crypto";
+import { Claude, type ClaudeResult, isDeferred } from "./claude";
+
+const WORKSPACE = "/tmp/macroclaw-integration-test";
+const SIMPLE_SCHEMA = JSON.stringify({
+  type: "object",
+  properties: {
+    action: { type: "string", enum: ["send", "silent"] },
+    actionReason: { type: "string" },
+    message: { type: "string" },
+  },
+  required: ["action", "actionReason"],
+  additionalProperties: false,
+});
+
+const FULL_SCHEMA = JSON.stringify({
+  type: "object",
+  properties: {
+    action: { type: "string", enum: ["send", "silent"], description: "'send' to reply to the user, 'silent' to do nothing" },
+    actionReason: { type: "string", description: "Why the agent chose this action (logged, not sent)" },
+    message: { type: "string", description: "The message to send to Telegram (required when action is 'send')" },
+    files: { type: "array", items: { type: "string" }, description: "Absolute paths to files to send to Telegram" },
+    backgroundAgents: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          prompt: { type: "string" },
+          model: { type: "string", enum: ["haiku", "sonnet", "opus"] },
+        },
+        required: ["name", "prompt"],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ["action", "actionReason"],
+  additionalProperties: false,
+});
+
+async function runSync(claude: Claude, ...args: Parameters<Claude["run"]>): Promise<ClaudeResult> {
+  const result = await claude.run(...args);
+  if (isDeferred(result)) throw new Error("Expected sync result, got deferred");
+  return result;
+}
+
+describe("claude CLI structured output", () => {
+  it("simple schema without system prompt", async () => {
+    const claude = new Claude({ workspace: WORKSPACE, jsonSchema: SIMPLE_SCHEMA });
+    const result = await runSync(claude, {
+      prompt: "Say hello",
+      sessionFlag: "--session-id",
+      sessionId: randomUUID(),
+      model: "haiku",
+    });
+
+    console.log("Simple (no sysprompt):", JSON.stringify(result, null, 2));
+    expect(result.structuredOutput).not.toBeNull();
+  }, 60_000);
+
+  it("simple schema with system prompt", async () => {
+    const claude = new Claude({ workspace: WORKSPACE, jsonSchema: SIMPLE_SCHEMA });
+    const result = await runSync(claude, {
+      prompt: "Say hello",
+      sessionFlag: "--session-id",
+      sessionId: randomUUID(),
+      model: "haiku",
+      systemPrompt: "You are a helpful assistant. This is a direct message from the user.",
+    });
+
+    console.log("Simple (with sysprompt):", JSON.stringify(result, null, 2));
+    expect(result.structuredOutput).not.toBeNull();
+  }, 60_000);
+
+  it("full schema with system prompt", async () => {
+    const claude = new Claude({ workspace: WORKSPACE, jsonSchema: FULL_SCHEMA });
+    const result = await runSync(claude, {
+      prompt: "Say hello",
+      sessionFlag: "--session-id",
+      sessionId: randomUUID(),
+      model: "haiku",
+      systemPrompt: "You are a helpful assistant. This is a direct message from the user.",
+    });
+
+    console.log("Full (with sysprompt):", JSON.stringify(result, null, 2));
+    expect(result.structuredOutput).not.toBeNull();
+  }, 60_000);
+
+  it("full schema with real system prompt and workspace", async () => {
+    const workspace = process.env.MACROCLAW_WORKSPACE ?? WORKSPACE;
+    const claude = new Claude({ workspace, jsonSchema: FULL_SCHEMA });
+    const result = await runSync(claude, {
+      prompt: "Say hello",
+      sessionFlag: "--session-id",
+      sessionId: randomUUID(),
+      model: "sonnet",
+      systemPrompt: `You are an AI assistant running inside macroclaw. This is a direct message from the user.`,
+    });
+
+    console.log("Full (real workspace):", JSON.stringify(result, null, 2));
+    expect(result.structuredOutput).not.toBeNull();
+  }, 120_000);
+});

package/src/claude.test.ts

@@ -0,0 +1,247 @@
+import { afterEach, describe, expect, it, mock } from "bun:test";
+import { Claude, type ClaudeDeferredResult, ClaudeParseError, ClaudeProcessError, type ClaudeResult, type ClaudeRunOptions, isDeferred } from "./claude";
+
+function jsonResult(structuredOutput: unknown, sessionId = "test-session-id"): string {
+  return JSON.stringify({
+    type: "result",
+    subtype: "success",
+    duration_ms: 1234,
+    total_cost_usd: 0.05,
+    result: "",
+    session_id: sessionId,
+    structured_output: structuredOutput,
+  });
+}
+
+const originalSpawn = Bun.spawn;
+
+afterEach(() => {
+  Bun.spawn = originalSpawn;
+});
+
+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 makeClaude() {
+  return new Claude({ workspace: TEST_WORKSPACE, jsonSchema: DUMMY_SCHEMA });
+}
+
+function opts(overrides?: Partial<ClaudeRunOptions>): ClaudeRunOptions {
+  return {
+    prompt: "test message",
+    sessionFlag: "--session-id",
+    sessionId: "sid-1",
+    ...overrides,
+  };
+}
+
+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;
+}
+
+describe("Claude", () => {
+  it("passes --session-id flag when given", 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 given", async () => {
+    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
+    const claude = makeClaude();
+    await claude.run(opts({ sessionFlag: "--resume", sessionId: "sid-2" }));
+    expect(Bun.spawn).toHaveBeenCalledWith(
+      expect.arrayContaining(["claude", "-p", "--resume", "sid-2"]),
+      expect.objectContaining({ cwd: TEST_WORKSPACE }),
+    );
+  });
+
+  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 }),
+    );
+  });
+
+  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 }),
+    );
+  });
+
+  it("passes --fork-session when forkSession is true", async () => {
+    mockSpawn({ stdout: jsonResult({ action: "send" }), exitCode: 0 });
+    const claude = makeClaude();
+    await claude.run(opts({ sessionFlag: "--resume", sessionId: "sid-fork", forkSession: true, prompt: "bg task" }));
+    expect(Bun.spawn).toHaveBeenCalledWith(
+      expect.arrayContaining(["--resume", "sid-fork", "--fork-session"]),
+      expect.objectContaining({ cwd: TEST_WORKSPACE }),
+    );
+  });
+
+  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");
+  });
+
+  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");
+  });
+
+  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");
+    }
+  });
+
+  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
+      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({ sessionFlag: "--resume", 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({ sessionFlag: "--resume", 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({ sessionFlag: "--resume", 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({ sessionFlag: "--resume", 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({ sessionFlag: "--resume", 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({ sessionFlag: "--resume", 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({ sessionFlag: "--resume", sessionId: "sid-12" }));
+    expect(result.structuredOutput).toEqual({ action: "send" });
+  });
+
+  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);
+  });
+});

package/src/claude.ts

@@ -0,0 +1,136 @@
+import { createLogger } from "./logger";
+
+const log = createLogger("claude");
+
+export interface ClaudeRunOptions {
+  prompt: string;
+  sessionFlag: "--resume" | "--session-id";
+  sessionId: string;
+  forkSession?: boolean;
+  model?: string;
+  systemPrompt?: string;
+  timeoutMs?: number;
+}
+
+export interface ClaudeResult {
+  structuredOutput: unknown;
+  sessionId: string;
+  result?: string;
+  duration?: string;
+  cost?: string;
+}
+
+export interface ClaudeDeferredResult {
+  deferred: true;
+  sessionId: string;
+  completion: Promise<ClaudeResult>;
+}
+
+export function isDeferred<T>(result: T | ClaudeDeferredResult): result is ClaudeDeferredResult {
+  return result != null && typeof result === "object" && "deferred" in result && (result as ClaudeDeferredResult).deferred === true;
+}
+
+export class ClaudeProcessError extends Error {
+  constructor(
+    public exitCode: number,
+    public stderr: string,
+  ) {
+    super(`Claude exited with code ${exitCode}:\n${stderr}`);
+  }
+}
+
+export class ClaudeParseError extends Error {
+  constructor(public raw: string) {
+    super(`Failed to parse Claude output as JSON`);
+  }
+}
+
+function parseEnvelope(stdout: string): ClaudeResult {
+  try {
+    const envelope = JSON.parse(stdout);
+    const duration = envelope.duration_ms ? `${(envelope.duration_ms / 1000).toFixed(1)}s` : undefined;
+    const cost = envelope.total_cost_usd ? `$${envelope.total_cost_usd.toFixed(4)}` : undefined;
+    const structuredOutput = envelope.structured_output ?? null;
+    if (!structuredOutput) {
+      log.debug({ envelope }, "No structured_output in envelope");
+    }
+    const sid = typeof envelope.session_id === "string" ? envelope.session_id : "";
+    const result = typeof envelope.result === "string" ? envelope.result : undefined;
+    log.debug({ duration, cost, sessionId: sid }, "Claude response received");
+    return { structuredOutput, sessionId: sid, result, duration, cost };
+  } catch {
+    log.warn({ stdout: stdout.slice(0, 200) }, "Failed to parse Claude stdout as JSON");
+    throw new ClaudeParseError(stdout);
+  }
+}
+
+async function awaitProcess(proc: { exited: Promise<number>; stdout: ReadableStream<Uint8Array> | null; stderr: ReadableStream<Uint8Array> | null }): Promise<ClaudeResult> {
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    log.error({ exitCode, stderr: stderr.slice(0, 200) }, "Claude process failed");
+    throw new ClaudeProcessError(exitCode, stderr);
+  }
+  const stdout = await new Response(proc.stdout).text();
+  return parseEnvelope(stdout);
+}
+
+export class Claude {
+  #workspace: string;
+  #jsonSchema: string;
+
+  constructor(config: { workspace: string; jsonSchema: string }) {
+    this.#workspace = config.workspace;
+    this.#jsonSchema = config.jsonSchema;
+  }
+
+  async run(options: ClaudeRunOptions): Promise<ClaudeResult | ClaudeDeferredResult> {
+    // Strip CLAUDECODE env var so nested claude sessions are allowed
+    const env = { ...process.env };
+    delete env.CLAUDECODE;
+
+    const args = ["claude", "-p", options.sessionFlag, options.sessionId, "--output-format", "json", "--json-schema", this.#jsonSchema];
+    if (options.forkSession) args.push("--fork-session");
+    if (options.model) args.push("--model", options.model);
+    if (options.systemPrompt) args.push("--append-system-prompt", options.systemPrompt);
+    args.push(options.prompt);
+
+    log.debug(
+      {
+        model: options.model,
+        sessionFlag: options.sessionFlag,
+        sessionId: options.sessionId,
+        promptLen: options.prompt.length,
+        hasSystemPrompt: !!options.systemPrompt,
+      },
+      "Sending to Claude",
+    );
+
+    const proc = Bun.spawn(args, {
+      cwd: this.#workspace,
+      env,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const completion = awaitProcess(proc);
+
+    if (!options.timeoutMs) {
+      return completion;
+    }
+
+    const result = await Promise.race([
+      completion.then((r) => ({ kind: "done" as const, value: r })),
+      new Promise<{ kind: "timeout" }>((resolve) => setTimeout(() => resolve({ kind: "timeout" }), options.timeoutMs)),
+    ]);
+
+    if (result.kind === "done") return result.value;
+
+    log.info({ timeoutMs: options.timeoutMs, sessionId: options.sessionId }, "Claude process timed out, deferring to background");
+    return {
+      deferred: true,
+      sessionId: options.sessionId,
+      completion,
+    };
+  }
+}