@twelvehart/orcats 0.0.0-seed.0 → 0.2.3

package/src/backends/pi-run.ts

@@ -0,0 +1,154 @@
+import { mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { z } from "zod";
+import { composeBackendPrompt } from "./conversation-config.ts";
+import { createPiRpcConsumer, piPromptCommand, piRpcArgs, type PiRpcOptions } from "./pi-rpc.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, type BackendConfig } from "../model/index.ts";
+
+export type PiProcess = SubprocessProcess;
+export type PiProcessSpawner = SubprocessSpawner;
+
+export interface PiBackendOptions {
+  readonly command?: string;
+  readonly cwd?: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly capacity?: number;
+  readonly spawnProcess?: PiProcessSpawner;
+  readonly config?: BackendConfig<"pi">;
+  readonly inactivityTimeoutMs?: number;
+  readonly wallClockTimeoutMs?: number;
+  /** Base directory for per-session Pi `--session-dir`s. Defaults to the OS temp dir. */
+  readonly sessionsDir?: string;
+}
+
+interface ResolvedPiConfig<Output> {
+  model?: string;
+  systemPrompt?: string;
+  readOnly?: boolean;
+  selfManagedGit?: boolean;
+  retryAttempts?: number;
+  schema?: z.ZodType<Output>;
+  resumeSessionId?: string;
+}
+
+/** Pi's read-only tool allow-list (Scala `PiArgs.ReadOnlyTools`). */
+const READ_ONLY_TOOLS = ["read", "grep", "find", "ls"] as const;
+
+/** Build the `pi --mode rpc` argv (Scala `PiArgs.rpc`): session dir, `--continue`
+ * on resume, model, and the read-only `--tools` gate. The prompt is sent as a
+ * stdin RPC command, not on argv. */
+function piArgs<Output>(sessionDir: string, config: ResolvedPiConfig<Output>): readonly string[] {
+  return [
+    ...piRpcArgs(sessionDir),
+    ...(config.resumeSessionId ? ["--continue"] : []),
+    ...(config.model ? ["--model", config.model] : []),
+    ...(config.readOnly ? ["--tools", READ_ONLY_TOOLS.join(",")] : [])
+  ];
+}
+
+export async function runPiConversation<Output>(
+  request: AutonomousRequest<Output, "pi">,
+  options: PiBackendOptions,
+  conversation: StreamConversation<"pi">,
+  setProcess: (process: PiProcess) => void
+): Promise<void> {
+  const command = options.command ?? "pi";
+  const config = resolvePiConfig(request, options);
+
+  try {
+    const piSessionId = config.resumeSessionId ?? crypto.randomUUID();
+    const sessionDir = join(options.sessionsDir ?? tmpdir(), `orca-pi-${piSessionId}`);
+    // Synchronous so the process spawns within the first microtask (matching
+    // codex/claude): a cancel right after start still finds the child to kill.
+    mkdirSync(sessionDir, { recursive: true });
+
+    const args = piArgs(sessionDir, config);
+    const consumerOptions: PiRpcOptions<Output> =
+      config.schema === undefined ? {} : { schema: config.schema };
+
+    await runSubprocessConversation({
+      backend: "pi",
+      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?.(`${piPromptCommand(composeBackendPrompt(request.prompt, config))}\n`);
+        // Pi rpc keeps reading stdin for the next command; leave it open. The
+        // shared helper kills the process once `agent_end` settles the turn.
+      },
+      createConsumer: () => createPiRpcConsumer(conversation, piSessionId, consumerOptions)
+    });
+  } catch (error) {
+    if (!conversation.signal.aborted) {
+      conversation.fail(backendFailed("pi", errorMessage(error)));
+    }
+  }
+}
+
+function resolvePiConfig<Output>(
+  request: AutonomousRequest<Output, "pi">,
+  options: PiBackendOptions
+): ResolvedPiConfig<Output> {
+  const optionConfig = options.config;
+  const requestConfig = request.config;
+  const config: ResolvedPiConfig<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 pi(options: PiBackendOptions = {}): LlmBackend<"pi"> {
+  return {
+    tag: "pi",
+    autonomous<Output = unknown>(request: AutonomousRequest<Output, "pi">) {
+      let child: PiProcess | undefined;
+      const conversation = new StreamConversation({
+        backend: "pi",
+        capacity: options.capacity ?? 256,
+        canAskUser: false,
+        onCancel: () => {
+          child?.kill("SIGTERM");
+        }
+      });
+
+      queueMicrotask(() => {
+        void runPiConversation(request, options, conversation, (process) => {
+          child = process;
+        });
+      });
+
+      return conversation;
+    }
+  };
+}

package/src/backends/select.ts

@@ -0,0 +1,77 @@
+import { BackendTagSchema, type BackendConfig, type BackendTag } from "../model/index.ts";
+import { claude } from "./claude-run.ts";
+import { codex } from "./codex.ts";
+import { opencode } from "./opencode-run.ts";
+import { pi } from "./pi-run.ts";
+import type { LlmBackend } from "./types.ts";
+
+export type PortableBackendConfig = Omit<BackendConfig, "resumeSessionId" | "structuredOutput">;
+
+export interface SelectBackendOptions {
+  readonly default: BackendTag;
+  readonly config?: PortableBackendConfig;
+  readonly perBackend?: Partial<Record<BackendTag, PortableBackendConfig>>;
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+export interface SelectedBackend {
+  readonly tag: BackendTag;
+  readonly backend: LlmBackend;
+  readonly model?: string;
+  readonly shutdown?: () => Promise<void>;
+}
+
+export function selectBackend(options: SelectBackendOptions): SelectedBackend {
+  const env = options.env ?? process.env;
+  const raw = env.ORCA_BACKEND;
+  const candidate = raw === undefined || raw === "" ? options.default : raw;
+  const parsed = BackendTagSchema.safeParse(candidate);
+  if (!parsed.success) {
+    throw new Error(
+      `Unsupported backend "${candidate}" (expected one of: ${BackendTagSchema.options.join(", ")})`
+    );
+  }
+
+  const tag = parsed.data;
+  const mergedConfig: PortableBackendConfig = {
+    ...(options.config ?? {}),
+    ...(options.perBackend?.[tag] ?? {})
+  };
+  const model = env.ORCA_BACKEND_MODEL === undefined || env.ORCA_BACKEND_MODEL === ""
+    ? mergedConfig.model
+    : env.ORCA_BACKEND_MODEL;
+  const config: PortableBackendConfig = {
+    ...mergedConfig,
+    ...(model === undefined ? {} : { model })
+  };
+
+  switch (tag) {
+    case "claude":
+      return {
+        tag,
+        backend: claude({ config }),
+        ...(model === undefined ? {} : { model })
+      };
+    case "codex":
+      return {
+        tag,
+        backend: codex({ config }),
+        ...(model === undefined ? {} : { model })
+      };
+    case "opencode": {
+      const backend = opencode({ config });
+      return {
+        tag,
+        backend,
+        ...(model === undefined ? {} : { model }),
+        shutdown: () => backend.shutdown()
+      };
+    }
+    case "pi":
+      return {
+        tag,
+        backend: pi({ config }),
+        ...(model === undefined ? {} : { model })
+      };
+  }
+}

package/src/backends/subprocess-run.ts

@@ -0,0 +1,305 @@
+import { spawn } from "node:child_process";
+import {
+  backendFailed,
+  type BackendTag
+} from "../model/index.ts";
+import type { StreamConversation } from "../conversation/index.ts";
+
+const DefaultSubprocessInactivityTimeoutMs = 120_000;
+
+interface Deferred<T> {
+  readonly promise: Promise<T>;
+  resolve(value: T | PromiseLike<T>): void;
+  reject(reason?: unknown): void;
+}
+const DefaultSubprocessWallClockTimeoutMs = 600_000;
+
+/** A spawned agent subprocess: a stdout (and optional stderr) line/byte stream,
+ * an exit promise, a kill signal, and — for backends that feed their prompt over
+ * stdin (claude, pi) — an optional write/end pair. Codex leaves stdin ignored and
+ * never touches these. */
+export interface SubprocessProcess {
+  readonly stdout: AsyncIterable<string | Uint8Array>;
+  readonly stderr?: AsyncIterable<string | Uint8Array>;
+  readonly exit: Promise<number | null>;
+  kill(signal?: NodeJS.Signals): void;
+  write?(data: string): void;
+  endStdin?(): void;
+}
+
+export interface SubprocessSpawnOptions {
+  readonly cwd?: string;
+  readonly env?: NodeJS.ProcessEnv;
+  /** Whether stdin is wired. Defaults to "ignore" so codex stays byte-identical;
+   * claude/pi pass "pipe" to write the opening user turn. */
+  readonly stdin?: "ignore" | "pipe";
+}
+
+export type SubprocessSpawner = (
+  command: string,
+  args: readonly string[],
+  options: SubprocessSpawnOptions
+) => SubprocessProcess;
+
+/** The per-line consumer half a backend supplies: incremental `consume(line)`
+ * plus a `finish()` that the helper calls after a clean (zero-exit) stream end.
+ * `signal` aborts once the turn is settled — required for persistent processes
+ * (pi rpc) that don't exit after a turn. */
+export interface SubprocessConsumer {
+  readonly signal: AbortSignal;
+  consume(raw: string): Promise<void>;
+  finish(): void;
+}
+
+export interface RunSubprocessOptions<B extends BackendTag> {
+  readonly backend: B;
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly conversation: StreamConversation<B>;
+  readonly createConsumer: () => SubprocessConsumer;
+  readonly cwd?: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly stdin?: "ignore" | "pipe";
+  readonly spawnProcess?: SubprocessSpawner;
+  /** Fail when stdout produces no line for this many ms. Defaults to 120s. */
+  readonly inactivityTimeoutMs?: number;
+  /** Fail after this absolute turn duration even if stdout stays active. Defaults to 600s. */
+  readonly wallClockTimeoutMs?: number;
+  /** Records the spawned process so the accessor can `kill` it on cancellation. */
+  readonly setProcess?: (process: SubprocessProcess) => void;
+  /** Runs right after spawn (before the read loop) — claude/pi write the opening
+   * user turn to stdin and close it here. */
+  readonly onStart?: (process: SubprocessProcess) => void | Promise<void>;
+}
+
+type SubprocessTimeoutKind = "inactivity" | "wallclock";
+
+interface SubprocessTimeout {
+  readonly type: "timeout";
+  readonly kind: SubprocessTimeoutKind;
+}
+
+/** Shared spawn → stdout-line-stream → consumer → outcome plumbing for
+ * subprocess-stream backends (codex, claude, pi). Owns process spawn, line
+ * splitting, stderr capture, non-zero-exit failure, cancellation checks, and
+ * timeout settlement; the per-backend command/args builder and line consumer
+ * plug in.
+ *
+ * The helper deliberately does NOT catch spawn / stream / consumer exceptions —
+ * each driver wraps the call in its own try/catch/finally so spawn-error→fail and
+ * resource teardown stay synchronous with the failure (matters for deterministic
+ * cleanup ordering; see codex's ask_user bridge). Use {@link errorMessage} +
+ * {@link backendFailed} in that catch. */
+export async function runSubprocessConversation<B extends BackendTag>(
+  options: RunSubprocessOptions<B>
+): Promise<void> {
+  const { conversation, backend } = options;
+  const spawnProcess = options.spawnProcess ?? spawnSubprocess;
+  const spawnOptions: { cwd?: string; env?: NodeJS.ProcessEnv; stdin?: "ignore" | "pipe" } = {};
+  if (options.cwd !== undefined) {
+    spawnOptions.cwd = options.cwd;
+  }
+  if (options.env !== undefined) {
+    spawnOptions.env = options.env;
+  }
+  if (options.stdin !== undefined) {
+    spawnOptions.stdin = options.stdin;
+  }
+
+  const process = spawnProcess(options.command, options.args, spawnOptions);
+  options.setProcess?.(process);
+
+  const stderr = collectText(process.stderr);
+  await options.onStart?.(process);
+
+  const timeout: Deferred<SubprocessTimeout> = Promise.withResolvers<SubprocessTimeout>();
+  const inactivityMs = options.inactivityTimeoutMs ?? DefaultSubprocessInactivityTimeoutMs;
+  const wallClockMs = options.wallClockTimeoutMs ?? DefaultSubprocessWallClockTimeoutMs;
+  let timeoutSettled = false;
+  let inactivityTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const settleTimeout = (kind: SubprocessTimeoutKind): void => {
+    if (timeoutSettled) {
+      return;
+    }
+    timeoutSettled = true;
+    process.kill("SIGTERM");
+    timeout.resolve({ type: "timeout", kind });
+  };
+  const resetInactivityTimer = (): void => {
+    clearTimeout(inactivityTimer);
+    inactivityTimer = setTimeout(() => {
+      settleTimeout("inactivity");
+    }, Math.max(inactivityMs, 0));
+  };
+
+  const wallClockTimer = setTimeout(() => {
+    settleTimeout("wallclock");
+  }, Math.max(wallClockMs, 0));
+  resetInactivityTimer();
+
+  try {
+    const consumer = options.createConsumer();
+    const lines = splitLines(process.stdout)[Symbol.asyncIterator]();
+    for (;;) {
+      const next: IteratorResult<string> | SubprocessTimeout = await Promise.race([lines.next(), timeout.promise]);
+      if (isSubprocessTimeout(next)) {
+        failSubprocessTimeout(conversation, backend, next.kind, inactivityMs, wallClockMs);
+        return;
+      }
+      if (next.done) {
+        break;
+      }
+      resetInactivityTimer();
+      if (conversation.signal.aborted) {
+        return;
+      }
+      await consumer.consume(next.value);
+      if (consumer.signal.aborted) {
+        // Kill the child once the consumer has settled the conversation on a
+        // terminal event (success, modeled failure, or early parse/tool error).
+        // Safe because we only reach here after consuming that event — the agent's
+        // session rollout is already flushed — and it stops a persistent process
+        // (pi rpc) or a stalled CLI from lingering after Orca has the outcome.
+        process.kill();
+        break;
+      }
+    }
+
+    // The consumer already settled the conversation (success/failure); the
+    // exit-code path below is only for a stream that ended without one.
+    if (consumer.signal.aborted) {
+      return;
+    }
+
+    const exit: number | null | SubprocessTimeout = await Promise.race([process.exit, timeout.promise]);
+    if (isSubprocessTimeout(exit)) {
+      failSubprocessTimeout(conversation, backend, exit.kind, inactivityMs, wallClockMs);
+      return;
+    }
+    const stderrText = (await stderr).trim();
+    if (conversation.signal.aborted) {
+      return;
+    }
+
+    if (exit !== 0) {
+      const exitCodeText = exit === null ? "unknown" : String(exit);
+      conversation.fail(
+        backendFailed(
+          backend,
+          `${backend} exited with code ${exitCodeText}${stderrText ? `: ${stderrText}` : ""}`
+        )
+      );
+      return;
+    }
+
+    consumer.finish();
+  } finally {
+    clearTimeout(inactivityTimer);
+    clearTimeout(wallClockTimer);
+  }
+}
+
+export function spawnSubprocess(
+  command: string,
+  args: readonly string[],
+  options: SubprocessSpawnOptions
+): SubprocessProcess {
+  const stdinMode = options.stdin ?? "ignore";
+  const child = spawn(command, [...args], {
+    cwd: options.cwd,
+    env: options.env,
+    stdio: [stdinMode === "pipe" ? "pipe" : "ignore", "pipe", "pipe"]
+  });
+
+  if (!child.stdout) {
+    throw new Error(`failed to capture stdout for ${command}`);
+  }
+
+  const exit = Promise.withResolvers<number | null>();
+  child.on("error", exit.reject);
+  child.on("close", exit.resolve);
+
+  return {
+    stdout: child.stdout,
+    ...(child.stderr ? { stderr: child.stderr } : {}),
+    exit: exit.promise,
+    kill(signal?: NodeJS.Signals) {
+      child.kill(signal);
+    },
+    write(data: string) {
+      child.stdin?.write(data);
+    },
+    endStdin() {
+      child.stdin?.end();
+    }
+  };
+}
+
+export async function* splitLines(
+  chunks: AsyncIterable<string | Uint8Array>
+): AsyncIterable<string> {
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  for await (const chunk of chunks) {
+    buffer += decodeChunk(decoder, chunk);
+    let newlineIndex = buffer.indexOf("\n");
+    while (newlineIndex !== -1) {
+      const line = buffer.slice(0, newlineIndex).replace(/\r$/, "");
+      buffer = buffer.slice(newlineIndex + 1);
+      yield line;
+      newlineIndex = buffer.indexOf("\n");
+    }
+  }
+
+  buffer += decoder.decode();
+  if (buffer.length > 0) {
+    yield buffer.replace(/\r$/, "");
+  }
+}
+
+export async function collectText(
+  chunks: AsyncIterable<string | Uint8Array> | undefined
+): Promise<string> {
+  if (!chunks) {
+    return "";
+  }
+
+  const decoder = new TextDecoder();
+  const text: string[] = [];
+  for await (const chunk of chunks) {
+    text.push(decodeChunk(decoder, chunk));
+  }
+  text.push(decoder.decode());
+  return text.join("");
+}
+
+function decodeChunk(decoder: TextDecoder, chunk: string | Uint8Array): string {
+  return typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+}
+
+function isSubprocessTimeout(value: IteratorResult<string> | number | null | SubprocessTimeout): value is SubprocessTimeout {
+  return typeof value === "object" && value !== null && (value as { readonly type?: unknown }).type === "timeout";
+}
+
+function failSubprocessTimeout<B extends BackendTag>(
+  conversation: StreamConversation<B>,
+  backend: B,
+  kind: SubprocessTimeoutKind,
+  inactivityMs: number,
+  wallClockMs: number
+): void {
+  if (conversation.signal.aborted) {
+    return;
+  }
+  const message =
+    kind === "inactivity"
+      ? `${backend} emitted no stdout for ${String(inactivityMs)}ms; treating the turn as stalled`
+      : `${backend} turn exceeded ${String(wallClockMs)}ms wall-clock limit`;
+  conversation.fail(backendFailed(backend, message));
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/backends/types.ts

@@ -0,0 +1,29 @@
+import type { z } from "zod";
+import type { Conversation } from "../conversation/index.ts";
+import type { BackendConfig, BackendTag } from "../model/index.ts";
+export type {
+  BackendApprovalPolicy,
+  BackendConfig,
+  BackendResult,
+  BackendRetryConfig,
+  BackendSandboxMode,
+  StructuredOutputConfig
+} from "../model/index.ts";
+
+export interface AutonomousRequest<Output = unknown, B extends BackendTag = BackendTag> {
+  readonly prompt: string;
+  readonly schema?: z.ZodType<Output>;
+  readonly config?: BackendConfig<B, Output>;
+}
+
+export interface LlmBackend<B extends BackendTag = BackendTag> {
+  readonly tag: B;
+  autonomous<Output = unknown>(request: AutonomousRequest<Output, B>): Conversation<B>;
+}
+
+export interface LlmTool {
+  autonomous<B extends BackendTag, Output = unknown>(
+    backend: LlmBackend<B>,
+    request: AutonomousRequest<Output, B>
+  ): Conversation<B>;
+}

package/src/backends/unsupported.ts

@@ -0,0 +1,48 @@
+import type { AutonomousRequest, LlmBackend } from "./types.ts";
+import { StreamConversation } from "../conversation/index.ts";
+import {
+  backendFailed,
+  sessionId,
+  unsupportedFeature,
+  type BackendTag,
+  type SessionId
+} from "../model/index.ts";
+
+export function unsupportedBackend<B extends BackendTag>(tag: B): LlmBackend<B> {
+  return {
+    tag,
+    autonomous(request: AutonomousRequest) {
+      const conversation = new StreamConversation({ backend: tag });
+      queueMicrotask(() => {
+        if (request.config?.resumeSessionId) {
+          conversation.fail(
+            unsupportedFeature(`${tag} resume`, `${tag} backend does not support session resume`)
+          );
+          return;
+        }
+        if (request.schema || request.config?.structuredOutput) {
+          conversation.fail(
+            unsupportedFeature(
+              `${tag} structured output`,
+              `${tag} backend does not support live structured output`
+            )
+          );
+          return;
+        }
+        conversation.fail(backendFailed(tag, `${tag} backend is not implemented yet`));
+      });
+      return conversation;
+    }
+  };
+}
+
+export function fakeResult<B extends BackendTag>(
+  backend: B,
+  output: string
+): { readonly backend: B; readonly sessionId: SessionId<B>; readonly output: string } {
+  return {
+    backend,
+    sessionId: sessionId(backend, `${backend}-fake-session`),
+    output
+  };
+}