@twelvehart/orcats 0.0.0-seed.0 → 0.2.3

package/src/backends/codex-jsonl.ts

@@ -0,0 +1,339 @@
+import type { z } from "zod";
+import {
+  collectConversation,
+  StreamConversation,
+  type ConversationCapture
+} from "../conversation/index.ts";
+import {
+  backendFailed,
+  parseStructuredOutput,
+  sessionId,
+  structuredOutputValidationFailed,
+  unsupportedFeature,
+  type BackendApprovalPolicy,
+  type BackendSandboxMode,
+  type RuntimeError,
+  type Usage
+} from "../model/index.ts";
+
+interface CodexLine {
+  readonly type?: string;
+  readonly thread_id?: string;
+  readonly usage?: {
+    readonly input_tokens?: number;
+    readonly output_tokens?: number;
+    readonly reasoning_output_tokens?: number;
+  };
+  readonly item?: {
+    readonly id?: string;
+    readonly type?: string;
+    readonly text?: string;
+    readonly name?: string;
+    readonly server?: string;
+    readonly tool?: string;
+    readonly command?: unknown;
+    readonly path?: string;
+    readonly changes?: unknown;
+    readonly output?: unknown;
+    readonly arguments?: unknown;
+    readonly result?: {
+      readonly content?: ReadonlyArray<{ readonly text?: string }>;
+    } | null;
+    readonly error?: string | null;
+  };
+}
+
+export type CodexParseResult = ConversationCapture<"codex">;
+
+export interface CodexExecArgs {
+  readonly model?: string;
+  readonly approvalPolicy?: BackendApprovalPolicy;
+  readonly sandbox?: BackendSandboxMode;
+  readonly readOnly?: boolean;
+  readonly ignoreUserConfig?: boolean;
+  readonly outputSchemaPath?: string;
+  readonly resumeSessionId?: string;
+  readonly mcpServerUrl?: string;
+  readonly prompt?: string;
+}
+
+export function codexExecJsonlArgs(args: CodexExecArgs = {}): readonly string[] {
+  const sandbox = args.sandbox ?? (args.readOnly ? "read-only" : undefined);
+  const promptArgs = args.prompt === undefined ? [] : [args.prompt];
+  const commonArgs = [
+    "--json",
+    ...(args.ignoreUserConfig ? ["--ignore-user-config"] : []),
+    ...(args.model ? ["--model", args.model] : []),
+    ...(args.approvalPolicy ? ["-c", `approval_policy="${args.approvalPolicy}"`] : []),
+    ...(args.mcpServerUrl ? ["-c", `mcp_servers.orcats.url=${JSON.stringify(args.mcpServerUrl)}`] : []),
+    ...(args.outputSchemaPath ? ["--output-schema", args.outputSchemaPath] : [])
+  ];
+
+  if (args.resumeSessionId) {
+    return [
+      "exec",
+      "resume",
+      ...commonArgs,
+      // `codex exec resume` rejects the exec-only `--sandbox` flag; express the
+      // sandbox as the equivalent config override instead (same form as
+      // `approval_policy` above).
+      ...(sandbox ? ["-c", `sandbox_mode="${sandbox}"`] : []),
+      args.resumeSessionId,
+      ...promptArgs
+    ];
+  }
+
+  return [
+    "exec",
+    ...commonArgs,
+    ...(sandbox ? ["--sandbox", sandbox] : []),
+    ...promptArgs
+  ];
+}
+
+export interface CodexJsonlOptions<Output = unknown> {
+  readonly schema?: z.ZodType<Output>;
+  /** Interactive conversations surface the agent's `ask_user` call as a
+   * `user_question` event for the renderer. The answer is NOT routed here — Codex
+   * obtains it from the Orcats MCP HTTP bridge and re-emits it on the matching
+   * `item.completed`, which the tool-result branch turns into a `tool_result`.
+   * Autonomous conversations leave this false and reject `ask_user` explicitly. */
+  readonly interactive?: boolean;
+}
+
+export async function collectCodexJsonl<Output = unknown>(
+  lines: readonly string[],
+  options: CodexJsonlOptions<Output> = {}
+): Promise<CodexParseResult> {
+  return collectConversation({
+    backend: "codex",
+    consume: async (conversation) => {
+      await consumeCodexJsonl(lines, conversation, options);
+    }
+  });
+}
+
+export async function consumeCodexJsonl<Output = unknown>(
+  lines: readonly string[],
+  conversation: StreamConversation<"codex">,
+  options: CodexJsonlOptions<Output> = {}
+): Promise<void> {
+  const consumer = createCodexJsonlConsumer(conversation, options);
+  for (const raw of lines) {
+    await consumer.consume(raw);
+  }
+  consumer.finish();
+}
+
+export interface CodexJsonlConsumer {
+  readonly signal: AbortSignal;
+  consume(raw: string): Promise<void>;
+  finish(): void;
+}
+
+export function createCodexJsonlConsumer<Output = unknown>(
+  conversation: StreamConversation<"codex">,
+  options: CodexJsonlOptions<Output> = {}
+): CodexJsonlConsumer {
+  let threadId = "";
+  let output = "";
+  let lastAgentText = "";
+  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: CodexLine;
+      try {
+        line = JSON.parse(raw) as CodexLine;
+      } catch (error) {
+        controller.abort();
+        const message = error instanceof Error ? error.message : String(error);
+        conversation.fail(backendFailed("codex", `invalid codex JSONL: ${message}`));
+        return;
+      }
+
+      if (line.type === "thread.started") {
+        threadId = line.thread_id ?? threadId;
+        return;
+      }
+
+      if (line.type === "item.started" && isToolItem(line.item)) {
+        if (line.item.server === "orcats" && line.item.tool === "ask_user") {
+          if (options.interactive) {
+            // Surface the question for the renderer only. The answer travels
+            // Codex <-> Orcats MCP HTTP bridge and arrives on the matching
+            // `item.completed`, which the tool-result branch emits below.
+            const question = askUserQuestion(line.item.arguments);
+            await conversation.emit({ type: "user_question", question });
+            return;
+          }
+          controller.abort();
+          conversation.fail(
+            unsupportedFeature(
+              "codex ask_user",
+              "Codex ask_user MCP bridge requires an explicit interactive conversation"
+            )
+          );
+          return;
+        }
+        await conversation.emit({
+          type: "assistant_tool_call",
+          id: line.item.id ?? "",
+          name: toolName(line.item),
+          input: toolInput(line.item)
+        });
+        return;
+      }
+
+      if (line.type === "item.completed" && isToolItem(line.item)) {
+        await conversation.emit({
+          type: "tool_result",
+          toolCallId: line.item.id ?? "",
+          output: toolOutput(line.item),
+          ...(line.item.error ? { isError: true } : {})
+        });
+        if (line.item.error) {
+          controller.abort();
+          conversation.fail(backendFailed("codex", line.item.error));
+        }
+        return;
+      }
+
+      if (line.type === "item.completed" && line.item?.type === "agent_message") {
+        const text = line.item.text ?? "";
+        output += text;
+        lastAgentText = text;
+        await conversation.emit({ type: "assistant_text_delta", text });
+        return;
+      }
+
+      if (line.type === "turn.completed") {
+        await conversation.emit({ type: "assistant_turn_end" });
+        // Codex emits one agent_message per step (progress updates + final answer).
+        // Only the last message is the structured result; using `output` (all steps
+        // concatenated) produces invalid JSON when the schema is set.
+        const structured = parseCodexStructuredOutput(options.schema, lastAgentText || output);
+        if (structured.type === "failed") {
+          controller.abort();
+          conversation.fail(structured.error);
+          return;
+        }
+
+        controller.abort();
+        conversation.succeed({
+          backend: "codex",
+          sessionId: sessionId("codex", threadId),
+          output,
+          ...(structured.value === undefined ? {} : { structured: structured.value }),
+          usage: normalizeCodexUsage(line.usage)
+        });
+      }
+    },
+
+    finish(): void {
+      if (controller.signal.aborted) {
+        return;
+      }
+      controller.abort();
+      conversation.fail(backendFailed("codex", "codex stream ended before turn.completed"));
+    }
+  };
+}
+
+function parseCodexStructuredOutput<Output>(
+  schema: z.ZodType<Output> | undefined,
+  output: string
+):
+  | { readonly type: "success"; readonly value?: Output }
+  | { readonly type: "failed"; readonly error: RuntimeError } {
+  if (!schema) {
+    return { type: "success" };
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(output) as unknown;
+  } catch {
+    return {
+      type: "failed",
+      error: structuredOutputValidationFailed({
+        raw: output,
+        issues: ["Codex 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 };
+}
+
+function isToolItem(item: CodexLine["item"]): item is NonNullable<CodexLine["item"]> {
+  return (
+    item?.type === "mcp_tool_call" ||
+    item?.type === "command_execution" ||
+    item?.type === "file_change" ||
+    item?.type === "tool_call"
+  );
+}
+
+function toolName(item: NonNullable<CodexLine["item"]>): string {
+  if (item.type === "mcp_tool_call") {
+    return `${item.server ?? ""}.${item.tool ?? ""}`;
+  }
+  return item.name ?? item.tool ?? item.type ?? "tool_call";
+}
+
+function toolInput(item: NonNullable<CodexLine["item"]>): unknown {
+  if (item.arguments !== undefined) {
+    return item.arguments;
+  }
+  if (item.command !== undefined) {
+    return { command: item.command };
+  }
+  if (item.path !== undefined || item.changes !== undefined) {
+    return {
+      ...(item.path === undefined ? {} : { path: item.path }),
+      ...(item.changes === undefined ? {} : { changes: item.changes })
+    };
+  }
+  return {};
+}
+
+function toolOutput(item: NonNullable<CodexLine["item"]>): unknown {
+  if (item.output !== undefined) {
+    return item.output;
+  }
+  const content = item.result?.content?.map((part) => part.text ?? "").join("") ?? "";
+  if (content.length > 0) {
+    return content;
+  }
+  return item.error ?? "";
+}
+
+function askUserQuestion(input: unknown): string {
+  if (typeof input === "object" && input !== null && "question" in input) {
+    const question = (input as { readonly question?: unknown }).question;
+    return typeof question === "string" ? question : "";
+  }
+  return "";
+}
+
+function normalizeCodexUsage(usage: CodexLine["usage"]): Usage {
+  return {
+    input: usage?.input_tokens ?? 0,
+    output: usage?.output_tokens ?? 0,
+    ...(usage?.reasoning_output_tokens ? { reasoning: usage.reasoning_output_tokens } : {})
+  };
+}

package/src/backends/codex-run.ts

@@ -0,0 +1,177 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { z } from "zod";
+import {
+  codexExecJsonlArgs,
+  createCodexJsonlConsumer,
+  type CodexExecArgs
+} from "./codex-jsonl.ts";
+import { composeBackendPrompt } from "./conversation-config.ts";
+import {
+  errorMessage,
+  runSubprocessConversation,
+  type SubprocessProcess,
+  type SubprocessSpawner
+} from "./subprocess-run.ts";
+import type { AutonomousRequest } from "./types.ts";
+import {
+  createAskUserMcpServer,
+  type AskUserMcpServer,
+  type AskUserMcpServerOptions,
+  type AskUserResponder,
+  type StreamConversation
+} from "../conversation/index.ts";
+import {
+  backendFailed,
+  jsonSchemaFromZod,
+  type BackendApprovalPolicy,
+  type BackendConfig,
+  type BackendSandboxMode
+} from "../model/index.ts";
+
+export interface CodexBackendOptions
+  extends Omit<CodexExecArgs, "prompt" | "outputSchemaPath" | "resumeSessionId" | "mcpServerUrl"> {
+  readonly command?: string;
+  readonly cwd?: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly capacity?: number;
+  readonly spawnProcess?: CodexProcessSpawner;
+  readonly config?: BackendConfig<"codex">;
+  readonly askUser?: AskUserResponder;
+  readonly createAskUserServer?: (options: AskUserMcpServerOptions) => AskUserMcpServer;
+  readonly inactivityTimeoutMs?: number;
+  readonly wallClockTimeoutMs?: number;
+}
+
+/** Codex's subprocess handle is the shared {@link SubprocessProcess}; the alias
+ * is kept for the public API (tests and flow code import `CodexProcess`). */
+export type CodexProcess = SubprocessProcess;
+
+export type CodexProcessSpawner = SubprocessSpawner;
+
+export interface ResolvedCodexConfig<Output> {
+  model?: string;
+  systemPrompt?: string;
+  approvalPolicy?: BackendApprovalPolicy;
+  sandbox?: BackendSandboxMode;
+  readOnly?: boolean;
+  ignoreUserConfig?: boolean;
+  selfManagedGit?: boolean;
+  retryAttempts?: number;
+  schema?: z.ZodType<Output>;
+  outputSchemaPath?: string;
+  resumeSessionId?: string;
+  interactive?: boolean;
+  mcpServerUrl?: string;
+}
+
+export async function runCodexConversation<Output>(
+  request: AutonomousRequest<Output, "codex">,
+  options: CodexBackendOptions,
+  conversation: StreamConversation<"codex">,
+  setProcess: (process: CodexProcess) => void
+): Promise<void> {
+  const command = options.command ?? "codex";
+  const config = resolveCodexConfig(request, options);
+  let schemaDir: string | undefined;
+  let askUserServer: AskUserMcpServer | undefined;
+
+  try {
+    if (config.interactive) {
+      askUserServer = (options.createAskUserServer ?? createAskUserMcpServer)({
+        responder:
+          options.askUser ??
+          (() => {
+            throw new Error("interactive ask_user responder is not configured");
+          })
+      });
+      config.mcpServerUrl = askUserServer.url;
+    }
+
+    if (config.schema) {
+      schemaDir = await mkdtemp(join(tmpdir(), "orca-codex-schema-"));
+      config.outputSchemaPath = join(schemaDir, "output-schema.json");
+      await writeFile(
+        config.outputSchemaPath,
+        `${JSON.stringify(jsonSchemaFromZod(config.schema), null, 2)}\n`
+      );
+    }
+
+    const args = codexExecJsonlArgs({
+      prompt: composeBackendPrompt(request.prompt, config),
+      ...(config.model === undefined ? {} : { model: config.model }),
+      ...(config.approvalPolicy === undefined ? {} : { approvalPolicy: config.approvalPolicy }),
+      ...(config.sandbox === undefined ? {} : { sandbox: config.sandbox }),
+      ...(config.readOnly === undefined ? {} : { readOnly: config.readOnly }),
+      ...(config.ignoreUserConfig === undefined ? {} : { ignoreUserConfig: config.ignoreUserConfig }),
+      ...(config.outputSchemaPath === undefined ? {} : { outputSchemaPath: config.outputSchemaPath }),
+      ...(config.resumeSessionId === undefined ? {} : { resumeSessionId: config.resumeSessionId }),
+      ...(config.mcpServerUrl === undefined ? {} : { mcpServerUrl: config.mcpServerUrl })
+    });
+
+    await runSubprocessConversation({
+      backend: "codex",
+      command,
+      args,
+      conversation,
+      setProcess,
+      ...(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 }),
+      createConsumer: () =>
+        createCodexJsonlConsumer(conversation, {
+          ...(config.schema === undefined ? {} : { schema: config.schema }),
+          // The answer is routed by the MCP HTTP bridge (askUserServer), not the
+          // consumer; the consumer only surfaces the question for the renderer.
+          ...(config.interactive ? { interactive: true } : {})
+        })
+    });
+  } catch (error) {
+    if (!conversation.signal.aborted) {
+      conversation.fail(backendFailed("codex", errorMessage(error)));
+    }
+  } finally {
+    await askUserServer?.close();
+    if (schemaDir) {
+      await rm(schemaDir, { recursive: true, force: true });
+    }
+  }
+}
+
+export function resolveCodexConfig<Output>(
+  request: AutonomousRequest<Output, "codex">,
+  options: CodexBackendOptions
+): ResolvedCodexConfig<Output> {
+  const optionConfig = options.config;
+  const requestConfig = request.config;
+  const config: ResolvedCodexConfig<Output> = {};
+  const model = requestConfig?.model ?? optionConfig?.model ?? options.model;
+  if (model !== undefined) config.model = model;
+  const systemPrompt = requestConfig?.systemPrompt ?? optionConfig?.systemPrompt;
+  if (systemPrompt !== undefined) config.systemPrompt = systemPrompt;
+  const approvalPolicy =
+    requestConfig?.approvalPolicy ?? optionConfig?.approvalPolicy ?? options.approvalPolicy;
+  if (approvalPolicy !== undefined) config.approvalPolicy = approvalPolicy;
+  const sandbox = requestConfig?.sandbox ?? optionConfig?.sandbox ?? options.sandbox;
+  if (sandbox !== undefined) config.sandbox = sandbox;
+  const readOnly = requestConfig?.readOnly ?? optionConfig?.readOnly ?? options.readOnly;
+  if (readOnly !== undefined) config.readOnly = readOnly;
+  if (options.ignoreUserConfig !== undefined) config.ignoreUserConfig = options.ignoreUserConfig;
+  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);
+  const interactive = requestConfig?.interactive ?? optionConfig?.interactive;
+  if (interactive !== undefined) config.interactive = interactive;
+  return config;
+}

package/src/backends/codex.ts

@@ -0,0 +1,84 @@
+import type { AutonomousRequest, LlmBackend } from "./types.ts";
+import {
+  codexAcpCommand,
+  experimentalAcpBackendEnabled,
+  runAcpConversation
+} from "./acp-run.ts";
+import {
+  resolveCodexConfig,
+  runCodexConversation,
+  type CodexBackendOptions,
+  type CodexProcess
+} from "./codex-run.ts";
+import { StreamConversation } from "../conversation/index.ts";
+
+export type {
+  CodexBackendOptions,
+  CodexProcess,
+  CodexProcessSpawner
+} from "./codex-run.ts";
+
+export function codex(options: CodexBackendOptions = {}): LlmBackend<"codex"> {
+  return {
+    tag: "codex",
+    autonomous<Output = unknown>(request: AutonomousRequest<Output, "codex">) {
+      let child: CodexProcess | undefined;
+      let cancelAcp: (() => Promise<void>) | undefined;
+      const useAcp = experimentalAcpBackendEnabled("codex");
+      const conversation = new StreamConversation({
+        backend: "codex",
+        capacity: options.capacity ?? 256,
+        canAskUser: request.config?.interactive ?? options.config?.interactive ?? false,
+        onCancel: async () => {
+          if (useAcp && cancelAcp) {
+            await cancelAcp();
+            return;
+          }
+          child?.kill("SIGTERM");
+        }
+      });
+
+      queueMicrotask(() => {
+        if (conversation.signal.aborted) {
+          return;
+        }
+        if (useAcp) {
+          const acp = codexAcpCommand();
+          const config = resolveCodexConfig(request, options);
+          void runAcpConversation(
+            request,
+            {
+              backend: "codex",
+              command: acp.command,
+              args: acp.args,
+              config,
+              ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+              ...(options.env === undefined ? {} : { env: options.env }),
+              ...(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 runCodexConversation(request, options, conversation, (process) => {
+          child = process;
+          if (conversation.signal.aborted) {
+            process.kill("SIGTERM");
+          }
+        });
+      });
+
+      return conversation;
+    }
+  };
+}

package/src/backends/conversation-config.ts

@@ -0,0 +1,26 @@
+import type { z } from "zod";
+
+export interface SharedBackendConfig<Output> {
+  model?: string;
+  systemPrompt?: string;
+  readOnly?: boolean;
+  selfManagedGit?: boolean;
+  retryAttempts?: number;
+  schema?: z.ZodType<Output>;
+  resumeSessionId?: string;
+}
+
+export function composeBackendPrompt(prompt: string, config: SharedBackendConfig<unknown>): string {
+  return [
+    config.systemPrompt ? `System instructions:\n${config.systemPrompt}` : "",
+    config.selfManagedGit === false
+      ? "Git policy: Orca is the parent runtime. Do not create commits, branches, pushes, or pull requests; leave repository mutation to the parent workflow."
+      : "",
+    config.retryAttempts === undefined
+      ? ""
+      : `Retry policy: maximum attempts ${String(config.retryAttempts)}.`,
+    prompt
+  ]
+    .filter((part) => part.length > 0)
+    .join("\n\n");
+}

package/src/backends/index.ts

@@ -0,0 +1,13 @@
+export * from "./claude-run.ts";
+export * from "./conversation-config.ts";
+export * from "./claude-stream-json.ts";
+export * from "./codex.ts";
+export * from "./codex-jsonl.ts";
+export * from "./opencode-run.ts";
+export * from "./opencode-sse.ts";
+export * from "./pi-rpc.ts";
+export * from "./pi-run.ts";
+export * from "./select.ts";
+export * from "./subprocess-run.ts";
+export * from "./types.ts";
+export * from "./unsupported.ts";