@twelvehart/orcats 0.0.0-seed.0 → 0.2.3

package/src/backends/claude-run.ts

@@ -0,0 +1,226 @@
+import type { z } from "zod";
+import {
+  claudeAcpCommand,
+  runAcpConversation
+} from "./acp-run.ts";
+import {
+  createClaudeStreamConsumer,
+  type ClaudeStreamOptions
+} from "./claude-stream-json.ts";
+import { composeBackendPrompt } from "./conversation-config.ts";
+import {
+  errorMessage,
+  runSubprocessConversation,
+  type SubprocessProcess,
+  type SubprocessSpawner
+} from "./subprocess-run.ts";
+import type { AutonomousRequest, LlmBackend } from "./types.ts";
+import { StreamConversation } from "../conversation/index.ts";
+import { backendFailed, jsonSchemaFromZod, type BackendConfig } from "../model/index.ts";
+
+export type ClaudeProcess = SubprocessProcess;
+export type ClaudeProcessSpawner = SubprocessSpawner;
+export type ClaudeTransport = "acp" | "stream-json";
+
+export interface ClaudeBackendOptions {
+  readonly command?: string;
+  readonly cwd?: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly capacity?: number;
+  readonly spawnProcess?: ClaudeProcessSpawner;
+  readonly spawnAcpProcess?: import("./acp-client.ts").AcpProcessSpawner;
+  readonly transport?: ClaudeTransport;
+  readonly acpCancelTimeoutMs?: number;
+  readonly config?: BackendConfig<"claude">;
+  readonly inactivityTimeoutMs?: number;
+  readonly wallClockTimeoutMs?: number;
+}
+
+interface ResolvedClaudeConfig<Output> {
+  model?: string;
+  systemPrompt?: string;
+  readOnly?: boolean;
+  selfManagedGit?: boolean;
+  retryAttempts?: number;
+  schema?: z.ZodType<Output>;
+  resumeSessionId?: string;
+}
+
+export function claudeStreamJsonArgs<Output>(config: ResolvedClaudeConfig<Output>): readonly string[] {
+  return [
+    "--print",
+    "--input-format",
+    "stream-json",
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    "--include-partial-messages",
+    ...(config.model ? ["--model", config.model] : []),
+    ...(config.resumeSessionId ? ["--resume", config.resumeSessionId] : []),
+    "--permission-mode",
+    config.readOnly ? "plan" : "bypassPermissions",
+    ...(config.schema ? ["--json-schema", JSON.stringify(jsonSchemaFromZod(config.schema))] : [])
+  ];
+}
+
+function userTurnLine(text: string): string {
+  return JSON.stringify({
+    type: "user",
+    message: { role: "user", content: [{ type: "text", text }] }
+  });
+}
+
+export async function runClaudeConversation<Output>(
+  request: AutonomousRequest<Output, "claude">,
+  options: ClaudeBackendOptions,
+  conversation: StreamConversation<"claude">,
+  setProcess: (process: ClaudeProcess) => void
+): Promise<void> {
+  const command = options.command ?? "claude";
+  const config = resolveClaudeConfig(request, options);
+
+  try {
+    const args = claudeStreamJsonArgs(config);
+    const consumerOptions: ClaudeStreamOptions<Output> =
+      config.schema === undefined ? {} : { schema: config.schema };
+
+    await runSubprocessConversation({
+      backend: "claude",
+      command,
+      args,
+      conversation,
+      setProcess,
+      stdin: "pipe",
+      ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+      ...(options.env === undefined ? {} : { env: options.env }),
+      ...(options.spawnProcess === undefined ? {} : { spawnProcess: options.spawnProcess }),
+      ...(options.inactivityTimeoutMs === undefined ? {} : { inactivityTimeoutMs: options.inactivityTimeoutMs }),
+      ...(options.wallClockTimeoutMs === undefined ? {} : { wallClockTimeoutMs: options.wallClockTimeoutMs }),
+      onStart: (process) => {
+        process.write?.(`${userTurnLine(composeBackendPrompt(request.prompt, config))}\n`);
+        process.endStdin?.();
+      },
+      createConsumer: () => createClaudeStreamConsumer(conversation, consumerOptions)
+    });
+  } catch (error) {
+    if (!conversation.signal.aborted) {
+      conversation.fail(backendFailed("claude", errorMessage(error)));
+    }
+  }
+}
+
+function resolveClaudeConfig<Output>(
+  request: AutonomousRequest<Output, "claude">,
+  options: ClaudeBackendOptions
+): ResolvedClaudeConfig<Output> {
+  const optionConfig = options.config;
+  const requestConfig = request.config;
+  const config: ResolvedClaudeConfig<Output> = {};
+  const model = requestConfig?.model ?? optionConfig?.model;
+  if (model !== undefined) config.model = model;
+  const systemPrompt = requestConfig?.systemPrompt ?? optionConfig?.systemPrompt;
+  if (systemPrompt !== undefined) config.systemPrompt = systemPrompt;
+  const readOnly = requestConfig?.readOnly ?? optionConfig?.readOnly;
+  if (readOnly !== undefined) config.readOnly = readOnly;
+  const selfManagedGit = requestConfig?.selfManagedGit ?? optionConfig?.selfManagedGit;
+  if (selfManagedGit !== undefined) config.selfManagedGit = selfManagedGit;
+  const retryAttempts = requestConfig?.retry?.attempts ?? optionConfig?.retry?.attempts;
+  if (retryAttempts !== undefined) config.retryAttempts = retryAttempts;
+  const schema =
+    requestConfig?.structuredOutput?.schema ??
+    request.schema ??
+    (optionConfig?.structuredOutput?.schema as z.ZodType<Output> | undefined);
+  if (schema !== undefined) config.schema = schema;
+  if (requestConfig?.resumeSessionId !== undefined)
+    config.resumeSessionId = String(requestConfig.resumeSessionId);
+  return config;
+}
+
+export function claude(options: ClaudeBackendOptions = {}): LlmBackend<"claude"> {
+  return {
+    tag: "claude",
+    autonomous<Output = unknown>(request: AutonomousRequest<Output, "claude">) {
+      let child: ClaudeProcess | undefined;
+      let cancelAcp: (() => Promise<void>) | undefined;
+      const config = resolveClaudeConfig(request, options);
+      const transport = resolveClaudeTransport(options, config);
+      const useAcp = transport === "acp";
+      const conversation = new StreamConversation({
+        backend: "claude",
+        capacity: options.capacity ?? 256,
+        canAskUser: false,
+        onCancel: async () => {
+          if (useAcp && cancelAcp) {
+            try {
+              await cancelAcp();
+            } catch (error) {
+              conversation.fail(backendFailed("claude", `Claude ACP cancellation failed: ${errorMessage(error)}`));
+            }
+            return;
+          }
+          child?.kill("SIGTERM");
+        }
+      });
+
+      queueMicrotask(() => {
+        if (conversation.signal.aborted) {
+          return;
+        }
+        if (useAcp) {
+          const acp = claudeAcpCommand();
+          void runAcpConversation(
+            request,
+            {
+              backend: "claude",
+              command: acp.command,
+              args: acp.args,
+              config,
+              ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+              ...(options.env === undefined ? {} : { env: options.env }),
+              ...(options.spawnAcpProcess === undefined ? {} : { spawnProcess: options.spawnAcpProcess }),
+              ...(options.acpCancelTimeoutMs === undefined ? {} : { cancelTimeoutMs: options.acpCancelTimeoutMs }),
+              ...(options.wallClockTimeoutMs === undefined ? {} : { requestTimeoutMs: options.wallClockTimeoutMs }),
+              ...(options.inactivityTimeoutMs === undefined ? {} : { inactivityTimeoutMs: options.inactivityTimeoutMs }),
+              setProcess: (process) => {
+                child = process;
+                if (conversation.signal.aborted) {
+                  process.kill("SIGTERM");
+                }
+              },
+              setCancel: (cancel) => {
+                cancelAcp = cancel;
+              }
+            },
+            conversation
+          );
+          return;
+        }
+        void runClaudeConversation(request, options, conversation, (process) => {
+          child = process;
+          if (conversation.signal.aborted) {
+            process.kill("SIGTERM");
+          }
+        });
+      });
+
+      return conversation;
+    }
+  };
+}
+
+function resolveClaudeTransport<Output>(
+  options: ClaudeBackendOptions,
+  config: ResolvedClaudeConfig<Output>
+): ClaudeTransport {
+  const transport = options.transport ?? process.env.ORCA_CLAUDE_TRANSPORT;
+  if (transport === "stream-json") {
+    return "stream-json";
+  }
+  if (transport !== undefined && transport !== "acp") {
+    throw new Error(`unsupported Claude transport ${transport}`);
+  }
+  if (config.model !== undefined || config.resumeSessionId !== undefined) {
+    return "stream-json";
+  }
+  return "acp";
+}

package/src/backends/claude-stream-json.ts

@@ -0,0 +1,273 @@
+import type { z } from "zod";
+import {
+  backendFailed,
+  parseStructuredOutput,
+  sessionId,
+  structuredOutputValidationFailed,
+  type RuntimeError
+} from "../model/index.ts";
+import {
+  collectConversation,
+  StreamConversation,
+  type ConversationCapture
+} from "../conversation/index.ts";
+
+interface ClaudeStreamLine {
+  readonly type?: string;
+  readonly subtype?: string;
+  readonly session_id?: string;
+  readonly result?: string;
+  readonly structured_output?: unknown;
+  readonly is_error?: boolean;
+  readonly event?: {
+    readonly type?: string;
+    readonly delta?: {
+      readonly type?: string;
+      readonly text?: string;
+    };
+  };
+  readonly message?: {
+    readonly content?: readonly ClaudeContentBlock[];
+  };
+}
+
+type ClaudeContentBlock =
+  | {
+      readonly type: "tool_use";
+      readonly id: string;
+      readonly name: string;
+      readonly input: unknown;
+    }
+  | {
+      readonly type: "tool_result";
+      readonly tool_use_id: string;
+      readonly content: unknown;
+      readonly is_error?: boolean;
+    }
+  | {
+      readonly type: "text";
+      readonly text: string;
+    };
+
+export type ClaudeParseResult = ConversationCapture<"claude">;
+
+export interface ClaudeStreamOptions<Output = unknown> {
+  readonly schema?: z.ZodType<Output>;
+}
+
+export async function collectClaudeStreamJson(lines: readonly string[]): Promise<ClaudeParseResult> {
+  return collectConversation({
+    backend: "claude",
+    consume: async (conversation) => {
+      await consumeClaudeStreamJson(lines, conversation);
+    }
+  });
+}
+
+export async function consumeClaudeStreamJson<Output = unknown>(
+  lines: readonly string[],
+  conversation: StreamConversation<"claude">,
+  options: ClaudeStreamOptions<Output> = {}
+): Promise<void> {
+  for (const raw of lines) {
+    if (raw.trim() === "") {
+      continue;
+    }
+
+    const line = parseClaudeLine(raw);
+    await consumeClaudeLine(line, conversation, options);
+  }
+}
+
+export interface ClaudeStreamConsumer {
+  readonly signal: AbortSignal;
+  consume(raw: string): Promise<void>;
+  finish(): void;
+}
+
+export function createClaudeStreamConsumer<Output = unknown>(
+  conversation: StreamConversation<"claude">,
+  options: ClaudeStreamOptions<Output> = {}
+): ClaudeStreamConsumer {
+  const controller = new AbortController();
+
+  return {
+    get signal() {
+      return controller.signal;
+    },
+
+    async consume(raw: string): Promise<void> {
+      if (controller.signal.aborted || raw.trim() === "") {
+        return;
+      }
+
+      let line: ClaudeStreamLine;
+      try {
+        line = parseClaudeLine(raw);
+      } catch (error) {
+        controller.abort();
+        const message = error instanceof Error ? error.message : String(error);
+        conversation.fail(backendFailed("claude", `invalid claude stream-json: ${message}`));
+        return;
+      }
+
+      await consumeClaudeLine(line, conversation, options);
+      if (line.type === "result") {
+        controller.abort();
+      }
+    },
+
+    finish(): void {
+      if (controller.signal.aborted) {
+        return;
+      }
+      controller.abort();
+      conversation.fail(
+        backendFailed("claude", "claude exited cleanly but never sent a result message")
+      );
+    }
+  };
+}
+
+function parseClaudeLine(raw: string): ClaudeStreamLine {
+  return JSON.parse(raw) as ClaudeStreamLine;
+}
+
+async function consumeClaudeLine<Output>(
+  line: ClaudeStreamLine,
+  conversation: StreamConversation<"claude">,
+  options: ClaudeStreamOptions<Output>
+): Promise<void> {
+  if (line.type === "stream_event") {
+    await consumeStreamEvent(line, conversation);
+    return;
+  }
+
+  if (line.type === "assistant" || line.type === "user") {
+    await consumeMessage(line, conversation);
+    return;
+  }
+
+  if (line.type === "result") {
+    await consumeResult(line, conversation, options);
+  }
+}
+
+async function consumeStreamEvent(
+  line: ClaudeStreamLine,
+  conversation: StreamConversation<"claude">
+): Promise<void> {
+  const delta = line.event?.delta;
+  if (line.event?.type === "content_block_delta" && delta?.type === "text_delta") {
+    await conversation.emit({ type: "assistant_text_delta", text: delta.text ?? "" });
+  }
+}
+
+async function consumeMessage(
+  line: ClaudeStreamLine,
+  conversation: StreamConversation<"claude">
+): Promise<void> {
+  const content = line.message?.content ?? [];
+  let endsAssistantTurn = false;
+
+  for (const block of content) {
+    switch (block.type) {
+      case "tool_use":
+        await conversation.emit({
+          type: "assistant_tool_call",
+          id: block.id,
+          name: block.name,
+          input: block.input
+        });
+        break;
+      case "tool_result":
+        await conversation.emit({
+          type: "tool_result",
+          toolCallId: block.tool_use_id,
+          output: block.content,
+          isError: block.is_error
+        });
+        break;
+      case "text":
+        await conversation.emit({ type: "assistant_text_delta", text: block.text });
+        break;
+    }
+
+    if (line.type === "assistant" && (block.type === "tool_use" || block.type === "text")) {
+      endsAssistantTurn = true;
+    }
+  }
+
+  if (endsAssistantTurn) {
+    await conversation.emit({ type: "assistant_turn_end" });
+  }
+}
+
+async function consumeResult<Output>(
+  line: ClaudeStreamLine,
+  conversation: StreamConversation<"claude">,
+  options: ClaudeStreamOptions<Output>
+): Promise<void> {
+  const structuredOutput = line.structured_output;
+  const output =
+    structuredOutput === undefined ? line.result ?? "" : JSON.stringify(structuredOutput);
+  const session = sessionId("claude", line.session_id ?? "");
+
+  if (line.subtype === "success" && !line.is_error) {
+    const structured = parseClaudeStructuredOutput(options.schema, output, structuredOutput);
+    if (structured.type === "failed") {
+      conversation.fail(structured.error);
+      return;
+    }
+    conversation.succeed({
+      backend: "claude",
+      sessionId: session,
+      output,
+      ...(structured.value === undefined ? {} : { structured: structured.value })
+    });
+    return;
+  }
+
+  await conversation.emit({
+    type: "error",
+    code: "backend_failed",
+    message: "session failed (see message above)"
+  });
+  conversation.fail(backendFailed("claude", `claude session failed: ${output}`));
+}
+
+function parseClaudeStructuredOutput<Output>(
+  schema: z.ZodType<Output> | undefined,
+  output: string,
+  structuredOutput: unknown
+):
+  | { readonly type: "success"; readonly value?: Output }
+  | { readonly type: "failed"; readonly error: RuntimeError } {
+  if (!schema) {
+    return { type: "success" };
+  }
+
+  let raw: unknown;
+  if (structuredOutput !== undefined) {
+    raw = structuredOutput;
+  } else {
+    try {
+      raw = JSON.parse(output) as unknown;
+    } catch {
+      return {
+        type: "failed",
+        error: structuredOutputValidationFailed({
+          raw: output,
+          issues: ["Claude structured output was not valid JSON"]
+        })
+      };
+    }
+  }
+
+  const parsed = parseStructuredOutput(schema, raw);
+  if (parsed.isErr()) {
+    return { type: "failed", error: parsed.error };
+  }
+
+  return { type: "success", value: parsed.value.value };
+}