@twelvehart/orcats 0.0.0-seed.0 → 0.2.3

package/src/conversation/conversation.ts

@@ -0,0 +1,109 @@
+import { err, ok, type Result } from "neverthrow";
+import {
+  type BackendResult,
+  type BackendTag,
+  type ConversationEvent,
+  type RuntimeError,
+  unsupportedFeature
+} from "../model/index.ts";
+import { BoundedAsyncQueue } from "./queue.ts";
+
+export type Outcome<B extends BackendTag = BackendTag> =
+  | { readonly type: "success"; readonly result: BackendResult<B> }
+  | { readonly type: "cancelled"; readonly reason?: string }
+  | { readonly type: "failed"; readonly error: RuntimeError };
+
+export interface Conversation<B extends BackendTag = BackendTag> {
+  readonly backend: B;
+  readonly canAskUser: boolean;
+  readonly signal: AbortSignal;
+  events(): AsyncIterable<ConversationEvent>;
+  awaitResult(): Promise<Outcome<B>>;
+  cancel(reason?: string): Promise<void>;
+}
+
+export interface StreamConversationOptions<B extends BackendTag> {
+  readonly backend: B;
+  readonly capacity?: number;
+  readonly canAskUser?: boolean;
+  readonly onCancel?: (reason?: string) => Promise<void> | void;
+}
+
+export class StreamConversation<B extends BackendTag> implements Conversation<B> {
+  private readonly abortController = new AbortController();
+
+  readonly canAskUser: boolean;
+  readonly signal = this.abortController.signal;
+
+  private readonly queue: BoundedAsyncQueue<ConversationEvent>;
+  private readonly outcome: Promise<Outcome<B>>;
+  private settle!: (outcome: Outcome<B>) => void;
+  private settled = false;
+
+  constructor(private readonly options: StreamConversationOptions<B>) {
+    this.queue = new BoundedAsyncQueue(options.capacity ?? 32);
+    this.canAskUser = options.canAskUser ?? false;
+    this.outcome = new Promise((resolve) => {
+      this.settle = resolve;
+    });
+  }
+
+  get backend(): B {
+    return this.options.backend;
+  }
+
+  events(): AsyncIterable<ConversationEvent> {
+    return this.queue;
+  }
+
+  awaitResult(): Promise<Outcome<B>> {
+    return this.outcome;
+  }
+
+  async emit(event: ConversationEvent): Promise<Result<void, RuntimeError>> {
+    let unsupportedReason: string | undefined;
+
+    if (event.type === "user_question" && !this.canAskUser) {
+      unsupportedReason = "Human interaction events require an explicit interactive conversation";
+    } else if (event.type === "approve_tool") {
+      unsupportedReason = "Live approval events are unsupported for autonomous execution";
+    }
+
+    if (unsupportedReason !== undefined) {
+      const error = unsupportedFeature(event.type, unsupportedReason);
+      this.fail(error);
+      return err(error);
+    }
+
+    await this.queue.push(event);
+    return ok(undefined);
+  }
+
+  succeed(result: BackendResult<B>): void {
+    this.complete({ type: "success", result });
+  }
+
+  fail(error: RuntimeError): void {
+    this.complete({ type: "failed", error });
+  }
+
+  async cancel(reason?: string): Promise<void> {
+    if (this.settled) {
+      return;
+    }
+
+    this.abortController.abort(reason);
+    await this.options.onCancel?.(reason);
+    this.complete(reason === undefined ? { type: "cancelled" } : { type: "cancelled", reason });
+  }
+
+  private complete(outcome: Outcome<B>): void {
+    if (this.settled) {
+      return;
+    }
+
+    this.settled = true;
+    this.queue.close();
+    this.settle(outcome);
+  }
+}

package/src/conversation/harness.ts

@@ -0,0 +1,39 @@
+import {
+  backendFailed,
+  type BackendTag,
+  type ConversationEvent
+} from "../model/index.ts";
+import { StreamConversation, type Outcome } from "./conversation.ts";
+
+export interface ConversationCapture<B extends BackendTag> {
+  readonly events: readonly ConversationEvent[];
+  readonly outcome: Outcome<B>;
+}
+
+export interface ConversationHarnessOptions<B extends BackendTag> {
+  readonly backend: B;
+  readonly capacity?: number;
+  readonly canAskUser?: boolean;
+  readonly consume: (conversation: StreamConversation<B>) => Promise<void> | void;
+}
+
+export async function collectConversation<B extends BackendTag>(
+  options: ConversationHarnessOptions<B>
+): Promise<ConversationCapture<B>> {
+  const { backend, consume, ...conversationOptions } = options;
+  const conversation = new StreamConversation({ backend, ...conversationOptions });
+
+  try {
+    await consume(conversation);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    conversation.fail(backendFailed(backend, message));
+  }
+
+  const events: ConversationEvent[] = [];
+  for await (const event of conversation.events()) {
+    events.push(event);
+  }
+
+  return { events, outcome: await conversation.awaitResult() };
+}

package/src/conversation/index.ts

@@ -0,0 +1,4 @@
+export * from "./ask-user.ts";
+export * from "./conversation.ts";
+export * from "./harness.ts";
+export * from "./queue.ts";

package/src/conversation/queue.ts

@@ -0,0 +1,86 @@
+export class BoundedAsyncQueue<T> implements AsyncIterable<T> {
+  private readonly items: T[] = [];
+  private readonly takers: Array<(value: IteratorResult<T>) => void> = [];
+  private readonly pushWaiters: Array<() => void> = [];
+  private closed = false;
+  private iteratorStarted = false;
+
+  constructor(private readonly capacity: number) {
+    if (capacity < 1) {
+      throw new Error("Queue capacity must be at least 1");
+    }
+  }
+
+  async push(item: T): Promise<void> {
+    this.ensureOpen();
+
+    while (this.items.length >= this.capacity) {
+      // Result-only callers never iterate, so a full queue would park the
+      // producer (and the backend turn loop behind it) forever: without a
+      // consumer, evict the oldest event instead of blocking.
+      if (!this.iteratorStarted) {
+        this.items.shift();
+        break;
+      }
+      await new Promise<void>((resolve) => this.pushWaiters.push(resolve));
+      this.ensureOpen();
+    }
+
+    const taker = this.takers.shift();
+    if (taker) {
+      taker({ value: item, done: false });
+      return;
+    }
+
+    this.items.push(item);
+  }
+
+  close(): void {
+    if (this.closed) {
+      return;
+    }
+
+    this.closed = true;
+    for (const resolve of this.pushWaiters) {
+      resolve();
+    }
+    this.pushWaiters.length = 0;
+    for (const taker of this.takers) {
+      taker({ value: undefined, done: true });
+    }
+    this.takers.length = 0;
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    if (this.iteratorStarted) {
+      throw new Error("Queue supports a single consumer");
+    }
+
+    this.iteratorStarted = true;
+
+    return {
+      next: () => this.next()
+    };
+  }
+
+  private async next(): Promise<IteratorResult<T>> {
+    const item = this.items.shift();
+    if (item !== undefined) {
+      const waiter = this.pushWaiters.shift();
+      waiter?.();
+      return { value: item, done: false };
+    }
+
+    if (this.closed) {
+      return { value: undefined, done: true };
+    }
+
+    return new Promise<IteratorResult<T>>((resolve) => this.takers.push(resolve));
+  }
+
+  private ensureOpen(): void {
+    if (this.closed) {
+      throw new Error("Queue is closed");
+    }
+  }
+}

package/src/flow/accessors.ts

@@ -0,0 +1,43 @@
+import { currentFlowContext } from "./context.ts";
+
+export const flowContext = currentFlowContext;
+
+export function fs() {
+  return currentFlowContext().fs;
+}
+
+export function git() {
+  return currentFlowContext().git;
+}
+
+export function gh() {
+  return currentFlowContext().gh;
+}
+
+export function linear() {
+  return currentFlowContext().linear;
+}
+
+export function terminal() {
+  return currentFlowContext().terminal;
+}
+
+export function command() {
+  return currentFlowContext().command;
+}
+
+export function llm() {
+  return currentFlowContext().llm;
+}
+
+export function plan() {
+  return currentFlowContext().plan;
+}
+
+export function review() {
+  return currentFlowContext().review;
+}
+
+export function reporter() {
+  return currentFlowContext().reporter;
+}

package/src/flow/approvals.ts

@@ -0,0 +1,10 @@
+export interface ToolApprovalRequest {
+  readonly toolName: string;
+  readonly input: unknown;
+}
+
+export function requestToolApproval(request: ToolApprovalRequest): never {
+  throw new Error(
+    `Tool approval for ${request.toolName} is intentionally unsupported in v1`
+  );
+}

package/src/flow/args.ts

@@ -0,0 +1,26 @@
+export const FLOW_ARGS_ENV = "ORCA_FLOW_ARGS";
+
+// User task tokens are everything after a standalone `--`, so CLI flags and the
+// flow path never leak into a flow's task input. No `--` means no task args.
+export function extractFlowArgs(argv: readonly string[]): string[] {
+  const separator = argv.indexOf("--");
+  return separator === -1 ? [] : argv.slice(separator + 1);
+}
+
+// The arguments a flow should treat as its task input. The orcats CLI captures
+// the post-`--` tokens and forwards them via ORCA_FLOW_ARGS; a flow run directly
+// (e.g. `bun flow.ts -- foo`) falls back to parsing argv.
+export function flowArgs(): string[] {
+  const raw = process.env[FLOW_ARGS_ENV];
+  if (raw !== undefined) {
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (Array.isArray(parsed)) {
+        return parsed.filter((arg): arg is string => typeof arg === "string");
+      }
+    } catch {
+      // malformed env — fall back to argv parsing below
+    }
+  }
+  return extractFlowArgs(process.argv.slice(2));
+}

package/src/flow/context.ts

@@ -0,0 +1,106 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createFsTool, type FsTool } from "../tools/fs.ts";
+import { createGitTool, type GitTool } from "../tools/git.ts";
+import { createGitHubTool, type GitHubTool } from "../tools/github.ts";
+import { createLinearTool, type LinearTool } from "../tools/linear.ts";
+import { createCommandTool, type CommandTool } from "../tools/process.ts";
+import { createTerminalTool, type TerminalTool } from "../tools/terminal.ts";
+import type { LlmTool } from "../backends/index.ts";
+import {
+  defaultPlanPath,
+  implementTaskLoop,
+  recoverPlan,
+  writePlan
+} from "../plan/index.ts";
+import { createReviewTool, type ReviewTool } from "../review/index.ts";
+import {
+  activeRunReporter,
+  createRunReporter,
+  type RunReporter,
+} from "../run-output/index.ts";
+
+export interface PlanTool {
+  readonly defaultPath: typeof defaultPlanPath;
+  readonly write: typeof writePlan;
+  readonly recover: typeof recoverPlan;
+  readonly implementTaskLoop: typeof implementTaskLoop;
+  interactive(): never;
+}
+
+export interface FlowContext {
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly fs: FsTool;
+  readonly git: GitTool;
+  readonly gh: GitHubTool;
+  readonly linear: LinearTool;
+  readonly terminal: TerminalTool;
+  readonly command: CommandTool;
+  readonly llm: LlmTool;
+  readonly plan: PlanTool;
+  readonly review: ReviewTool;
+  readonly reporter: RunReporter;
+}
+
+export type FlowOverrides = Partial<Omit<FlowContext, "args">>;
+
+const storage = new AsyncLocalStorage<FlowContext>();
+
+export function flow<T>(
+  args: readonly string[] = [],
+  overrides: FlowOverrides = {}
+): (fn: () => Promise<T> | T) => Promise<T> {
+  const context = createDefaultFlowContext(args, overrides);
+  return async (fn) => await storage.run(context, async () => await fn());
+}
+
+export function currentFlowContext(): FlowContext {
+  const context = storage.getStore();
+  if (!context) {
+    throw new Error("No active Orca flow context");
+  }
+  return context;
+}
+
+export function createDefaultFlowContext(
+  args: readonly string[],
+  overrides: FlowOverrides = {}
+): FlowContext {
+  const cwd = overrides.cwd ?? process.cwd();
+  const reporter = overrides.reporter ?? activeRunReporter() ?? createRunReporter();
+
+  return {
+    args,
+    cwd,
+    fs: overrides.fs ?? createFsTool(),
+    git: overrides.git ?? createGitTool(cwd),
+    gh: overrides.gh ?? createGitHubTool(cwd),
+    linear: overrides.linear ?? createLinearTool(),
+    terminal: overrides.terminal ?? createTerminalTool({ reporter }),
+    command: overrides.command ?? createCommandTool(cwd),
+    llm: overrides.llm ?? createDefaultLlmTool(),
+    plan: overrides.plan ?? createDefaultPlanTool(),
+    review: overrides.review ?? createReviewTool(),
+    reporter
+  };
+}
+
+function createDefaultLlmTool(): LlmTool {
+  return {
+    autonomous(backend, request) {
+      return backend.autonomous(request);
+    }
+  };
+}
+
+function createDefaultPlanTool(): PlanTool {
+  return {
+    defaultPath: defaultPlanPath,
+    write: writePlan,
+    recover: recoverPlan,
+    implementTaskLoop,
+    interactive() {
+      throw new Error("Plan.interactive is intentionally unsupported in v1");
+    }
+  };
+}

package/src/flow/index.ts

@@ -0,0 +1,4 @@
+export * from "./accessors.ts";
+export * from "./approvals.ts";
+export * from "./args.ts";
+export * from "./context.ts";

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from "./backends/index.ts";
+export * from "./baseline/index.ts";
+export * from "./conversation/index.ts";
+export * from "./flow/index.ts";
+export * from "./loop/index.ts";
+export * from "./model/index.ts";
+export * from "./monitor/index.ts";
+export * from "./plan/index.ts";
+export * from "./review/index.ts";
+export * from "./runner/index.ts";
+export * from "./run-output/index.ts";
+export * from "./tools/index.ts";
+export { z } from "zod";
+// Re-exported so flows (including standalone runs that only get the embedded
+// @twelvehart/orcats surface) can build fixLoop/Result values without a neverthrow dep.
+export { err, ok } from "neverthrow";
+export type { Result } from "neverthrow";