@twelvehart/orcats 0.0.0-seed.0 → 0.2.3

package/src/run-output/index.ts

@@ -0,0 +1,319 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Usage } from "../model/index.ts";
+
+export type RunEvent =
+  | RunStartedEvent
+  | RunHeartbeatEvent
+  | RunFinishedEvent
+  | PreflightEvent
+  | StageEvent
+  | AgentActivityEvent
+  | CycleProgressEvent
+  | OutcomeEvent
+  | FailureEvent
+  | ArtifactEvent;
+
+export interface RunStartedEvent {
+  readonly type: "run_started";
+  readonly runId?: string;
+  readonly label?: string;
+  readonly backend?: string;
+}
+
+export interface RunHeartbeatEvent {
+  readonly type: "run_heartbeat";
+  readonly label?: string;
+  readonly elapsedMs?: number;
+}
+
+export interface RunFinishedEvent {
+  readonly type: "run_finished";
+  readonly label?: string;
+  readonly status: "success" | "failed";
+  readonly stopReason?: string;
+  readonly iterations?: number;
+  readonly error?: string;
+}
+
+export interface PreflightEvent {
+  readonly type: "preflight";
+  readonly name: string;
+  readonly status: "started" | "passed" | "failed" | "skipped";
+  readonly reason?: string;
+}
+
+export interface StageEvent {
+  readonly type: "stage";
+  readonly name: string;
+  readonly status: "started" | "running" | "completed" | "failed";
+  readonly durationMs?: number;
+  readonly message?: string;
+}
+
+export interface AgentActivityEvent {
+  readonly type: "agent_activity";
+  readonly activity: "started" | "tool_use" | "tool_result" | "assistant_summary" | "usage";
+  readonly backend?: string;
+  readonly name?: string;
+  readonly summary?: string;
+  readonly usage?: Usage;
+}
+
+export interface CycleBranchEvent {
+  readonly id: string;
+  readonly status: string;
+  readonly usage?: Usage | "unknown";
+}
+
+export interface CycleContextPressureEvent {
+  readonly offloadCount: number;
+  readonly compactionStages: readonly string[];
+  readonly tokensBefore: number;
+  readonly tokensAfter: number;
+  readonly observationCount: number;
+}
+
+export interface CycleProgressEvent {
+  readonly type: "cycle_progress";
+  readonly iteration: number;
+  readonly measure?: number;
+  readonly delta?: number;
+  readonly stopStatus?: string;
+  readonly usage?: Usage | "unknown";
+  readonly branches?: readonly CycleBranchEvent[];
+  readonly contextPressure?: CycleContextPressureEvent;
+}
+
+export interface OutcomeEvent {
+  readonly type: "outcome";
+  readonly file: string;
+  readonly verdict: string;
+  readonly durationMs?: number;
+  readonly reason?: string;
+}
+
+export interface FailureEvent {
+  readonly type: "failure";
+  readonly file: string;
+  readonly category?: string;
+  readonly durationMs?: number;
+  readonly message: string;
+}
+
+export interface ArtifactEvent {
+  readonly type: "artifact";
+  readonly artifact: string;
+  readonly path: string;
+  readonly label?: string;
+}
+
+export interface RunEventSink {
+  handle(event: RunEvent): void | Promise<void>;
+}
+
+export interface RunReporter {
+  emit(event: RunEvent): void;
+  events(): readonly RunEvent[];
+  flush(): Promise<void>;
+}
+
+export interface RunReporterOptions {
+  readonly sinks?: readonly RunEventSink[];
+}
+
+export interface RunNarrator {
+  summarize(events: readonly RunEvent[]): string | Promise<string>;
+}
+
+export interface RunPresenterOptions {
+  readonly env?: Record<string, string | undefined>;
+  readonly isTTY?: boolean;
+  readonly narration?: "disabled" | "enabled";
+  readonly narrator?: RunNarrator;
+  readonly writeDiagnostic?: (text: string) => void;
+  readonly writeOutput?: (text: string) => void;
+}
+
+const reporterStorage = new AsyncLocalStorage<RunReporter>();
+const reporterStack: RunReporter[] = [];
+
+export function activeRunReporter(): RunReporter | undefined {
+  return reporterStorage.getStore() ?? reporterStack.at(-1);
+}
+
+export async function withRunReporter<T>(
+  reporter: RunReporter | undefined,
+  fn: () => Promise<T> | T,
+): Promise<T> {
+  if (reporter === undefined) {
+    return await fn();
+  }
+  reporterStack.push(reporter);
+  try {
+    return await reporterStorage.run(reporter, async () => await fn());
+  } finally {
+    reporterStack.pop();
+  }
+}
+
+export function createRunReporter(options: RunReporterOptions = {}): RunReporter {
+  const events: RunEvent[] = [];
+  const pending: Promise<void>[] = [];
+  const sinks = options.sinks ?? [];
+
+  return {
+    emit(event) {
+      events.push(event);
+      for (const sink of sinks) {
+        try {
+          const result = sink.handle(event);
+          if (result instanceof Promise) {
+            pending.push(result.then(() => undefined, () => undefined));
+          }
+        } catch {
+          continue;
+        }
+      }
+    },
+    events() {
+      return [...events];
+    },
+    async flush() {
+      await Promise.allSettled(pending.splice(0));
+    },
+  };
+}
+
+export function createRunPresenter(options: RunPresenterOptions = {}): RunEventSink {
+  const env = options.env ?? process.env;
+  const isTTY = options.isTTY ?? process.stderr.isTTY;
+  const writeDiagnostic =
+    options.writeDiagnostic ??
+    ((text: string) => {
+      process.stderr.write(text);
+    });
+  const recent: RunEvent[] = [];
+
+  return {
+    async handle(event) {
+      recent.push(event);
+      writeDiagnostic(`${formatRunEvent(event, { env, isTTY })}\n`);
+
+      if (options.narration !== "enabled" || options.narrator === undefined || env.CI) {
+        return;
+      }
+
+      try {
+        const summary = await options.narrator.summarize([...recent]);
+        if (summary.trim().length > 0) {
+          writeDiagnostic(`${prefix({ env, isTTY })} narrator: ${summary.trim()}\n`);
+        }
+      } catch (error) {
+        writeDiagnostic(`${prefix({ env, isTTY })} narration unavailable: ${describeError(error)}\n`);
+      }
+    },
+  };
+}
+
+export function formatRunEvent(
+  event: RunEvent,
+  options: Pick<RunPresenterOptions, "env" | "isTTY"> = {},
+): string {
+  const head = prefix(options);
+  switch (event.type) {
+    case "run_started": {
+      const label = event.label ?? event.runId ?? "run";
+      const backend = event.backend === undefined ? "" : ` (backend=${event.backend})`;
+      return `${head} run started: ${label}${backend}`;
+    }
+    case "run_heartbeat":
+      return `${head} run active: ${event.label ?? "work"}${durationSuffix(event.elapsedMs)}`;
+    case "run_finished": {
+      const label = event.label ?? "run";
+      if (event.status === "failed") {
+        return `${head} failed: ${label}${event.error === undefined ? "" : `: ${event.error}`}`;
+      }
+      const reason = event.stopReason === undefined ? "completed" : `stopped (${event.stopReason})`;
+      const iterations = event.iterations === undefined ? "" : ` after ${String(event.iterations)} iteration(s)`;
+      return `${head} done: ${label} ${reason}${iterations}`;
+    }
+    case "preflight":
+      return `${head} preflight ${event.name} ${event.status}${event.reason === undefined ? "" : `: ${event.reason}`}`;
+    case "stage":
+      return `${head} stage ${event.name} ${event.status}${durationSuffix(event.durationMs)}${event.message === undefined ? "" : `: ${event.message}`}`;
+    case "agent_activity":
+      return formatAgentActivity(head, event);
+    case "cycle_progress":
+      return formatCycleProgress(head, event);
+    case "outcome":
+      return `${head} outcome ${event.file} ${event.verdict}${durationSuffix(event.durationMs)}${event.reason === undefined ? "" : `: ${event.reason}`}`;
+    case "failure":
+      return `${head} failure ${event.file}${event.category === undefined ? "" : ` ${event.category}`}${durationSuffix(event.durationMs)}: ${event.message}`;
+    case "artifact":
+      return `${head} artifact ${event.label ?? event.artifact}: ${event.path}`;
+  }
+}
+
+function formatAgentActivity(head: string, event: AgentActivityEvent): string {
+  const actor = event.backend === undefined ? "agent" : `agent ${event.backend}`;
+  switch (event.activity) {
+    case "started":
+      return `${head} ${actor} started`;
+    case "tool_use":
+      return `${head} ${actor} tool ${event.name ?? "unknown"}`;
+    case "tool_result":
+      return `${head} ${actor} tool result ${event.name ?? "unknown"}${event.summary === undefined ? "" : `: ${event.summary}`}`;
+    case "assistant_summary":
+      return `${head} ${actor}: ${event.summary ?? ""}`.trimEnd();
+    case "usage":
+      return `${head} ${actor} usage${event.usage === undefined ? "" : ` ${formatUsage(event.usage)}`}`;
+  }
+}
+
+function formatCycleProgress(head: string, event: CycleProgressEvent): string {
+  const fields = [`cycle ${String(event.iteration)}`];
+  if (event.measure !== undefined) fields.push(`measure=${String(event.measure)}`);
+  if (event.delta !== undefined) fields.push(`delta=${String(event.delta)}`);
+  if (event.stopStatus !== undefined) fields.push(`stop=${event.stopStatus}`);
+  if (event.usage !== undefined && event.usage !== "unknown") fields.push(formatUsage(event.usage));
+  if (event.usage === "unknown") fields.push("usage=unknown");
+  if (event.contextPressure !== undefined) {
+    fields.push(`context=${String(event.contextPressure.tokensBefore)}->${String(event.contextPressure.tokensAfter)}`);
+  }
+  return `${head} ${fields.join(" ")}`;
+}
+
+function prefix(options: Pick<RunPresenterOptions, "env" | "isTTY"> = {}): string {
+  const env = options.env ?? process.env;
+  const isTTY = options.isTTY ?? process.stderr.isTTY;
+  if (isTTY && !env.NO_COLOR && !env.CI) {
+    return "\u001b[36morca\u001b[0m |";
+  }
+  return "orcats |";
+}
+
+function durationSuffix(ms: number | undefined): string {
+  return ms === undefined ? "" : ` (${formatDuration(ms)})`;
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 1_000) return `${String(ms)}ms`;
+  const seconds = Math.floor(ms / 1_000);
+  if (seconds < 60) return `${String(seconds)}s`;
+  return `${String(Math.floor(seconds / 60))}m ${String(seconds % 60)}s`;
+}
+
+function formatUsage(usage: Usage): string {
+  const reasoning = usage.reasoning === undefined ? "" : ` reasoning=${String(usage.reasoning)}`;
+  return `usage=input=${String(usage.input)} output=${String(usage.output)}${reasoning}`;
+}
+
+function describeError(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}

package/src/runner/index.ts

@@ -0,0 +1 @@
+export * from "./typecheck.ts";

package/src/runner/typecheck.ts

@@ -0,0 +1,72 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { err, ok, type Result } from "neverthrow";
+import type { RuntimeError } from "../model/index.ts";
+import { runQuiet, type QuietProcResult } from "../tools/process.ts";
+
+export interface CommandRunner {
+  (command: string, args: readonly string[], options: { cwd: string }): Promise<Result<QuietProcResult, RuntimeError>>;
+}
+
+export interface TypecheckOptions {
+  readonly cwd: string;
+  readonly project?: string;
+  readonly skip?: boolean;
+  readonly runner?: CommandRunner;
+  readonly which?: (cwd: string) => string | null;
+}
+
+export interface TypecheckResult {
+  readonly skipped: boolean;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly reason?: "flag" | "tsc-not-found";
+}
+
+export async function runTypecheck(
+  options: TypecheckOptions
+): Promise<Result<TypecheckResult, RuntimeError>> {
+  if (options.skip) {
+    return ok({ skipped: true, reason: "flag", stdout: "", stderr: "" });
+  }
+
+  const command = options.which ? options.which(options.cwd) : defaultWhichTsc(options.cwd, options.project);
+  if (command === null) {
+    return ok({ skipped: true, reason: "tsc-not-found", stdout: "", stderr: "" });
+  }
+
+  const runner = options.runner ?? runQuiet;
+  const args = ["--noEmit"];
+  if (options.project) {
+    args.push("-p", options.project);
+  }
+
+  const result = await runner(command, args, { cwd: options.cwd });
+  if (result.isErr()) {
+    const error = result.error;
+    if (error._tag === "CommandFailed") {
+      return err({
+        _tag: "TypecheckFailed",
+        stdout: error.stdout,
+        stderr: error.stderr,
+        exitCode: error.exitCode
+      });
+    }
+    return err(error);
+  }
+
+  return ok({ skipped: false, stdout: result.value.stdout, stderr: result.value.stderr });
+}
+
+function defaultWhichTsc(cwd: string, project?: string): string | null {
+  if (!existsSync(resolve(cwd, project ?? "tsconfig.json"))) {
+    return null;
+  }
+
+  const localTsc = join(cwd, "node_modules", ".bin", "tsc");
+  if (existsSync(localTsc)) {
+    return localTsc;
+  }
+
+  return Bun.which("tsc");
+}

package/src/test-utils/fakes.ts

@@ -0,0 +1,260 @@
+import type { ConversationEvent, LlmResult } from "../model/index.ts";
+import { err, ok, type Result } from "neverthrow";
+import type { RuntimeError } from "../model/index.ts";
+import type { LlmBackend, LlmTool, AutonomousRequest } from "../backends/types.ts";
+import { StreamConversation, type Conversation } from "../conversation/conversation.ts";
+import { sessionId } from "../model/brand.ts";
+import type { BackendTag } from "../model/schemas.ts";
+import type { Sink, Source, SourceSubscription } from "../loop/io/index.ts";
+import type {
+  LinearAgentActivityInput,
+  LinearAgentSessionUpdateInput,
+  LinearIssueUpdateInput,
+  LinearTool,
+} from "../tools/index.ts";
+
+export interface FakeSubprocess {
+  readonly lines: readonly string[];
+  readonly stderr?: string;
+  readonly exitCode?: number;
+}
+
+export interface FakeHttpSseTransport {
+  readonly events: readonly string[];
+}
+
+export interface FakeRpcTransport<Request = unknown, Response = unknown> {
+  readonly requests: Request[];
+  readonly responses: Response[];
+}
+
+export interface FakeAgentRun {
+  readonly events: readonly ConversationEvent[];
+  readonly result: LlmResult;
+  readonly diff?: string;
+}
+
+export interface ScriptedFakeAgentStep {
+  readonly events?: readonly ConversationEvent[];
+  readonly output?: string;
+  readonly diff?: string;
+  readonly failure?: RuntimeError;
+}
+
+export interface ScriptedFakeAgent {
+  run(prompt: string): Promise<Result<FakeAgentRun, RuntimeError>>;
+  readonly prompts: readonly string[];
+}
+
+export function scriptedSubprocess(lines: readonly string[]): FakeSubprocess {
+  return { lines };
+}
+
+export function scriptedSse(events: readonly string[]): FakeHttpSseTransport {
+  return { events };
+}
+
+export function scriptedRpc<Request, Response>(
+  responses: readonly Response[]
+): FakeRpcTransport<Request, Response> {
+  return { requests: [], responses: [...responses] };
+}
+
+export function fakeAgentRun(events: readonly ConversationEvent[], result: LlmResult): FakeAgentRun {
+  return { events, result };
+}
+
+export interface FakeLlmBackend extends LlmBackend<"codex"> {
+  readonly calls: readonly string[];
+}
+
+export function fakeBackend(outputs: readonly string[]): FakeLlmBackend {
+  const queue = [...outputs];
+  const calls: string[] = [];
+  return {
+    tag: "codex" as const,
+    calls,
+    autonomous<Output>(request: AutonomousRequest<Output, "codex">): Conversation<"codex"> {
+      calls.push(request.prompt);
+      const output = queue.shift();
+      if (output === undefined) {
+        throw new Error(`fakeBackend: scripted outputs exhausted (${String(calls.length)} calls made)`);
+      }
+      const callIndex = calls.length;
+      const conv = new StreamConversation<"codex">({ backend: "codex" });
+      void Promise.resolve().then(async () => {
+        await conv.emit({ type: "assistant_text_delta", text: output });
+        await conv.emit({ type: "assistant_turn_end" });
+        conv.succeed({
+          backend: "codex",
+          sessionId: sessionId("codex", `fake-session-${String(callIndex)}`),
+          output,
+        });
+      });
+      return conv;
+    }
+  };
+}
+
+export interface EventRecorder<E = ConversationEvent> {
+  readonly push: (event: E) => void;
+  readonly events: () => readonly E[];
+}
+
+export function eventRecorder<E = ConversationEvent>(): EventRecorder<E> {
+  const captured: E[] = [];
+  return {
+    push: (event) => { captured.push(event); },
+    events: () => captured,
+  };
+}
+
+export function createFakeLlmTool(fake: FakeLlmBackend): LlmTool {
+  return {
+    autonomous<B extends BackendTag, Output>(_backend: LlmBackend<B>, req: AutonomousRequest<Output, B>) {
+      return fake.autonomous(req as unknown as AutonomousRequest<Output, "codex">) as unknown as Conversation<B>;
+    }
+  };
+}
+
+export function scriptedFakeAgent(steps: readonly ScriptedFakeAgentStep[]): ScriptedFakeAgent {
+  const prompts: string[] = [];
+  const queue = [...steps];
+
+  return {
+    prompts,
+    run(prompt) {
+      prompts.push(prompt);
+      const step = queue.shift();
+      if (!step) {
+        return Promise.resolve(err({
+          _tag: "BackendFailed",
+          backend: "codex",
+          message: "scripted fake agent exhausted"
+        }));
+      }
+      if (step.failure) {
+        return Promise.resolve(err(step.failure));
+      }
+      const run: FakeAgentRun = {
+        events: step.events ?? [],
+        result: {
+          backend: "codex",
+          sessionId: "fake-agent-session",
+          output: step.output ?? ""
+        }
+      };
+      return Promise.resolve(ok({
+        ...run,
+        ...(step.diff === undefined ? {} : { diff: step.diff })
+      }));
+    }
+  };
+}
+
+// --- Fake Source / Sink (loop-io spec): in-memory, so a loop runs end to end with no real ---
+// --- trigger or output IO. The fake sink captures emitted outputs; the fake source fires on demand. ---
+
+export interface FakeSource<E> extends Source<E> {
+  readonly kind: "manual";
+  /** Push a trigger event to the started handler. No-op until started / after stop. */
+  fire(event: E): void;
+  /** Whether a handler is currently subscribed. */
+  isStarted(): boolean;
+}
+
+export function fakeSource<E = void>(): FakeSource<E> {
+  let handler: ((event: E) => void) | undefined;
+  return {
+    kind: "manual",
+    isStarted: () => handler !== undefined,
+    fire(event) {
+      handler?.(event);
+    },
+    start(received) {
+      handler = received;
+      const sub: SourceSubscription = {
+        stop() {
+          handler = undefined;
+          return Promise.resolve(ok(undefined));
+        },
+      };
+      return Promise.resolve(ok(sub));
+    },
+  };
+}
+
+export interface FakeSink<A> extends Sink<A> {
+  readonly kind: "stdout";
+  /** Outputs captured by each successful emit, in order. */
+  emitted(): readonly A[];
+}
+
+/** A capturing Sink. With `failWith`, every emit returns `err(RuntimeError)` and captures nothing. */
+export function fakeSink<A = unknown>(options: { failWith?: RuntimeError } = {}): FakeSink<A> {
+  const captured: A[] = [];
+  const { failWith } = options;
+  return {
+    kind: "stdout",
+    emitted: () => captured,
+    emit(output) {
+      if (failWith !== undefined) {
+        return Promise.resolve(err(failWith));
+      }
+      captured.push(output);
+      return Promise.resolve(ok(undefined));
+    },
+  };
+}
+
+export interface FakeLinearTool extends LinearTool {
+  readonly issueComments: readonly { readonly issueId: string; readonly body: string }[];
+  readonly issueUpdates: readonly LinearIssueUpdateInput[];
+  readonly agentActivities: readonly LinearAgentActivityInput[];
+  readonly agentSessionUpdates: readonly LinearAgentSessionUpdateInput[];
+}
+
+export function createFakeLinearTool(): FakeLinearTool {
+  const issueComments: { readonly issueId: string; readonly body: string }[] = [];
+  const issueUpdates: LinearIssueUpdateInput[] = [];
+  const agentActivities: LinearAgentActivityInput[] = [];
+  const agentSessionUpdates: LinearAgentSessionUpdateInput[] = [];
+
+  return {
+    issueComments,
+    issueUpdates,
+    agentActivities,
+    agentSessionUpdates,
+    fetchIssue(input) {
+      return Promise.resolve(ok({ id: input.issueId }));
+    },
+    updateIssue(input) {
+      issueUpdates.push(input);
+      return Promise.resolve(ok({ id: input.issueId, title: input.title ?? null }));
+    },
+    createIssueComment(input) {
+      issueComments.push(input);
+      return Promise.resolve(ok({ id: `comment-${String(issueComments.length)}`, body: input.body }));
+    },
+    createAgentActivity(input) {
+      agentActivities.push(input);
+      return Promise.resolve(ok({
+        id: `activity-${String(agentActivities.length)}`,
+        body: input.body,
+        ...(input.type === undefined ? {} : { type: input.type }),
+      }));
+    },
+    updateAgentSession(input) {
+      agentSessionUpdates.push(input);
+      return Promise.resolve(ok({
+        id: input.agentSessionId,
+        ...(input.plan === undefined ? {} : { plan: input.plan }),
+        ...(input.externalUrl === undefined ? {} : { externalUrl: input.externalUrl }),
+        ...(input.externalUrls === undefined ? {} : { externalUrls: input.externalUrls }),
+      }));
+    },
+    getTeamWorkflowStates() {
+      return Promise.resolve(ok([]));
+    },
+  };
+}

package/src/test-utils/fixtures.ts

@@ -0,0 +1,33 @@
+import { readFile } from "node:fs/promises";
+import { isDeepStrictEqual } from "node:util";
+import { expect } from "bun:test";
+
+export async function readJsonFixture<T = unknown>(path: string): Promise<T> {
+  return JSON.parse(await readFile(path, "utf8")) as T;
+}
+
+export function assertExactJson(actual: unknown, expected: unknown): void {
+  expect(isDeepStrictEqual(actual, expected)).toBe(true);
+}
+
+export function stableJson(value: unknown): string {
+  return `${JSON.stringify(value, Object.keys(flattenKeys(value)).sort(), 2)}\n`;
+}
+
+function flattenKeys(value: unknown, keys: Record<string, true> = {}): Record<string, true> {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      flattenKeys(item, keys);
+    }
+    return keys;
+  }
+
+  if (value !== null && typeof value === "object") {
+    for (const [key, child] of Object.entries(value)) {
+      keys[key] = true;
+      flattenKeys(child, keys);
+    }
+  }
+
+  return keys;
+}

package/src/test-utils/index.ts

@@ -0,0 +1,3 @@
+export * from "./fakes.ts";
+export * from "./fixtures.ts";
+export * from "./tier2.ts";

package/src/test-utils/tier2.ts

@@ -0,0 +1,12 @@
+import { expect } from "bun:test";
+
+export interface Tier2Golden {
+  readonly commits: readonly string[];
+  readonly planFiles: Readonly<Record<string, string>>;
+  readonly terminal: readonly string[];
+  readonly events: readonly unknown[];
+}
+
+export function assertTier2Golden(actual: Tier2Golden, expected: Tier2Golden): void {
+  expect(actual).toEqual(expected);
+}