@twelvehart/orcats 0.0.0-seed.0 → 0.2.3

package/LICENSE

@@ -0,0 +1,48 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" or "Your" shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. Derivative Works shall not include works that remain separable from, or merely link or bind by name to the interfaces of, the Work.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner.
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+(c) You must retain all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+(d) If the Work includes a NOTICE text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+8. Limitation of Liability. In no event and under no legal theory shall any Contributor be liable to You for damages arising in any way out of the use of or inability to use the Work.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer support, warranty, indemnity, or other liability obligations. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility.

package/NOTICE

@@ -0,0 +1,5 @@
+Orca TypeScript
+Copyright 2026 Ahmad Ragab
+
+This project is a derivative TypeScript port of Orca by VirtusLab.
+The original Orca project is licensed under the Apache License, Version 2.0.

package/README.md

@@ -0,0 +1,399 @@
+# Orcats
+
+Orcats is a Bun and TypeScript workflow runner for deterministic coding-agent work.
+
+Write a direct-style TypeScript flow, choose a backend such as Claude, Codex, OpenCode, or Pi, and let Orcats provide the runtime pieces around it: a flow context, normalized conversation results, filesystem and git helpers, persistent plans, loop execution, review loops, fixtures, and a CLI runner.
+
+Use Orcats when you want coding-agent work to be expressed as code instead of a one-off prompt.
+
+## Status
+
+The package is version `0.2.3`. Install the public npm package for normal project use:
+
+```bash
+npm i @twelvehart/orcats
+```
+
+The package provides the TypeScript authoring API and the Bun-backed `orcats` CLI shim. GitHub Release binaries remain available when you need a standalone executable with no project `node_modules`.
+
+Canonical repository: <https://github.com/ASRagab/orca-ts>
+
+Documentation website: <https://ASRagab.github.io/orca-ts/>
+
+## Quickstart
+
+### Requirements
+
+- Bun `>=1.3.0` for project installs and source development
+- Git
+- At least one configured backend CLI when running live flows
+
+### Install
+
+Use this when you are writing and versioning flows in a project:
+
+```bash
+npm i @twelvehart/orcats
+npm i -D typescript
+bunx -p @twelvehart/orcats orcats --version
+```
+
+`typescript` is only needed for editor feedback and the CLI typecheck preflight. Bun `>=1.3.0` must be on `PATH` because the npm CLI shim runs with Bun.
+
+Flow files import from `@twelvehart/orcats`:
+
+```ts
+import { flow, llm, selectBackend } from "@twelvehart/orcats";
+```
+
+Run a flow with:
+
+```bash
+bunx -p @twelvehart/orcats orcats --backend claude hello.ts
+```
+
+### Optional Standalone Binary
+
+Use this when you want to run a flow on a Unix-like machine without creating a package first:
+
+```bash
+curl -fsSL https://github.com/ASRagab/orca-ts/releases/latest/download/install.sh | bash
+```
+
+Pin a version or change the install directory with environment variables:
+
+```bash
+ORCA_VERSION=0.2.3 ORCA_INSTALL_DIR="$HOME/.local/bin" \
+  bash <(curl -fsSL https://github.com/ASRagab/orca-ts/releases/download/v0.2.3/install.sh)
+```
+
+The standalone binary embeds the runtime API, so it can run a flow that imports from `@twelvehart/orcats` even when the flow project has no `node_modules`. If the project has its own `@twelvehart/orcats` package dependency, that project copy wins.
+
+### Source Checkout
+
+Use this for contributing to Orca itself.
+
+```bash
+git clone https://github.com/ASRagab/orca-ts.git
+cd orca-ts
+bun install --frozen-lockfile
+bun run verify
+```
+
+`bun run verify` runs typecheck, unit tests, docs site build, doc-link checking, fixture validation, release metadata validation, declaration generation, the facade gate, and a compiled binary smoke test. It does not require live backend credentials.
+
+## Write Your First Flow
+
+Create `hello.ts`:
+
+```ts
+import { flow, llm, selectBackend } from "@twelvehart/orcats";
+
+await flow()(async () => {
+  const selected = selectBackend({ default: "claude" });
+  try {
+    const conversation = llm().autonomous(selected.backend, {
+      prompt: "Say hello from an autonomous Orca flow."
+    });
+
+    const outcome = await conversation.awaitResult();
+    if (outcome.type !== "success") {
+      throw new Error(`Backend failed with outcome: ${outcome.type}`);
+    }
+
+    console.log(outcome.result.output);
+  } finally {
+    await selected.shutdown?.();
+  }
+});
+```
+
+Run it with the CLI:
+
+```bash
+bunx -p @twelvehart/orcats orcats --backend claude hello.ts
+```
+
+Inside this repository, examples import from `./src/index.ts`. Package consumers should import from `@twelvehart/orcats`.
+
+## Configure Backends
+
+Orca normalizes backend output into one `Conversation` model, but each backend still needs its native CLI or server to be installed and authenticated.
+
+| Backend | Flow constructor | Runtime requirement |
+| --- | --- | --- |
+| Claude | `claude()` | `claude-agent-acp` on `PATH`, or `ORCA_CLAUDE_ACP_COMMAND` set; use `ORCA_CLAUDE_TRANSPORT=stream-json` to fall back to the authenticated `claude` CLI |
+| Codex | `codex()` | `codex` CLI on `PATH` and authenticated |
+| OpenCode | `opencode()` | `opencode` CLI on `PATH` and authenticated; Orca manages `opencode serve` |
+| Pi | `pi()` | `pi` CLI on `PATH` and authenticated |
+
+Autonomous conversations are intended to complete without asking the human for input. If a backend needs credentials, approvals, or login setup, configure that backend before running the flow.
+
+### Selecting A Backend At Run Time
+
+`selectBackend()` reads `ORCA_BACKEND` and returns the selected backend plus an optional `shutdown` hook:
+
+```ts
+const selected = selectBackend({
+  default: "codex",
+  perBackend: {
+    codex: { approvalPolicy: "never" },
+    opencode: { model: "provider/model" }
+  }
+});
+```
+
+Precedence:
+
+1. `ORCA_BACKEND` overrides `default`.
+2. `ORCA_BACKEND_MODEL` overrides `perBackend[tag].model` and `config.model`.
+3. Flow code that calls `claude()`, `codex()`, `opencode()`, or `pi()` directly pins the backend and ignores `--backend`.
+
+## Loops
+
+A loop is a flow that repeats a cycle until a measurable goal is met. Use it when the work has a progress signal: failing gates, pending tasks, open issues, confidence, or a fixed cycle count.
+
+```ts
+import { codex, loop, untilManifestComplete, type TaskManifest } from "@twelvehart/orcats";
+
+const result = await loop<TaskManifest>("ralph")
+  .reason(codex(), { prompt: "Pick the next pending task and implement it." })
+  .step("mark-one-task-complete", passOneTask)
+  .until(untilManifestComplete())
+  .guard({ maxIterations: 10 })
+  .run(manifest);
+```
+
+Presets such as `untilManifestComplete()`, `untilGatesGreen()`, `untilNoIssues()`, `untilConfident(threshold)`, and `times(n)` supply the convergence measure. Add `.guard({ maxIterations, wallClockMs, tokenBudget })` for seatbelts. A loop with no preset or custom `.measure()` fails before it runs.
+
+Loop execution owns recurrence, cycle reports, guards, token budgets, and optional context pressure. `fixLoop` remains the public generic convergence primitive over the same execution path; `executeLoop` is internal. Managed context is explicit: pass `context` to `.run()` when you want model-visible observations compacted/offloaded. Without it, raw reason/step observations are not captured.
+
+Distributable loops live as import-safe modules under `.orca/loops/` and export `defineLoop({ name, source, sink, onTrigger })`. Use `orcats loops` to list them, `orcats run <loop>` to run one firing, and `orcats serve <loop>` to host the trigger. `orcats run` and served children share one firing contract for event decoding, `defineLoop().run`, sink emission, diagnostics, and stop-reason exit codes.
+
+Start with the full guide: [Loops](docs/loops.md). It covers the first-loop tutorial, presets, custom measures, state stores, fan-out/fan-in, loop modules, `orcats run/serve/loops`, recipes, troubleshooting, and migration from legacy workflow scripts.
+
+## CLI Reference
+
+```bash
+orcats [--backend <name>] [--no-typecheck] <flow.ts> [-- <task args>]
+orcats run <loop>      # run a loop once; exit status reflects the stop reason
+orcats serve <loop>    # host a loop's trigger, spawning a child process per firing
+orcats loops           # list defined loops with their source and sink
+orcats --version
+```
+
+| Command | Meaning |
+| --- | --- |
+| `<flow.ts>` | Legacy script path: import and run a flow file (unchanged behavior) |
+| `run <loop>` | Run a loop once. `<loop>` is a loop module path or a registered loop name; exit code reflects the stop reason |
+| `serve <loop>` | Run a thin supervisor that owns the loop's trigger `Source` and spawns one isolated child process per firing through the shared firing contract |
+| `loops` | Discover and list loops from `.orca/loops/` without firing any trigger, backend, or sink |
+
+| Option | Meaning |
+| --- | --- |
+| `--backend <name>` | Validates the tag and sets `ORCA_BACKEND`, which `selectBackend()` reads |
+| `--no-typecheck` | Skips the `tsc --noEmit` pre-flight and sets `ORCA_TYPECHECK_SKIPPED=1` |
+| `--version`, `-v` | Prints `orcats <version>` |
+| `--help`, `-h` | Prints usage |
+| `-- <task args>` | Everything after `--` is the flow/loop task input, read via `flowArgs()` |
+
+Loop verbs and the legacy script path share one preflight: the typecheck guard, `--backend`, and the `--` task-arg channel apply to all of them. By default, the CLI typechecks the current project before importing when it can find project typecheck setup: `typescript`, `tsconfig.json`, and a local `@twelvehart/orcats` package dependency. A standalone binary flow in a zero-project directory without `tsconfig.json` skips this guard. Use `--no-typecheck` only when you intentionally want to skip it.
+
+During a run, Orcats writes synthesized progress diagnostics to stderr from structured run-output events. Stdout stays reserved for explicit flow output and loop sink payloads.
+
+The default state adapter needs no service. Use the sqlite store when a loop needs local crash recovery or longer-lived checkpoint history.
+
+## Examples
+
+The best way to learn the authoring model is to start with the examples.
+
+| Example | What it shows |
+| --- | --- |
+| `examples/runnable/01-simple/index.ts` | Minimal autonomous flow that honors `--backend` through `selectBackend()` |
+| `examples/implement.ts` | Plan, implement, review, and fix loop |
+| `examples/implement-enhanced.ts` | Larger implementation loop shape |
+| `examples/issue-pr.ts` | Issue-to-PR style workflow |
+| `examples/issue-pr-bugfix.ts` | Bugfix-oriented issue workflow |
+| `examples/linear-ticket-triage.ts` | Linear ticket triage loop with fake Linear and Slack IO |
+| `examples/multi-backend-compare.ts` | Comparing backend behavior |
+| `examples/epic.ts` | Structured output with a Zod schema and a directly pinned `codex()` backend |
+| `examples/loop-single-cycle.ts` | A single-cycle preset loop (`loop()` + `untilManifestComplete()`), runnable with no real backend |
+| `examples/loop-gated-task.ts` | A gate-converging loop using `untilGatesGreen()` |
+| `examples/loop-fanout.ts` | A fan-out / fan-in loop: bounded-concurrency branches joined through a reducer |
+| `examples/loop-persisted-state.ts` | Snapshot state store checkpoint, history, branch, and merge |
+| `examples/loop-served-trigger.ts` | Import-safe `defineLoop()` module for `.orca/loops/` |
+| `workflows/ai-slop-cleanup.ts` | Full dogfood workflow with monitoring support |
+
+## Agent Skills
+
+Installable Agent Skills under `skills/` take a coding agent from "I have an
+Orcats automation idea" to a saved, self-validating workflow or loop module — in
+**any** git-backed repo, not just TypeScript projects. They compose as a
+pipeline:
+
+| Skill | Purpose |
+| --- | --- |
+| `skills/orcats-setup` | Install or verify the `orcats` CLI and verify at least one backend (claude/codex/opencode/pi) is authenticated; re-runnable as a doctor |
+| `skills/orcats-author` | Detect the target repo's real test/lint commands, interview for the workflow or loop shape, generate an artifact that typechecks, and respect the loop execution/source/sink contracts |
+| `skills/orcats-flow` | Run a saved workflow or loop with monitoring, detect stalls from progress/context-pressure evidence rather than slowness, and heal backend/auth/non-convergence failures within safety bounds |
+
+### Install The Skills
+
+The skills install with the [`skills` CLI](https://github.com/vercel-labs/skills)
+(`npx skills`), which reads the `skills/<name>/` directories in this repo and
+copies each into your coding agent's skills directory:
+
+```bash
+# See which skills the repo provides
+npx skills add ASRagab/orca-ts --list
+
+# Install all three, user-level (works for every detected agent)
+npx skills add ASRagab/orca-ts --skill '*' --global
+
+# Or install one skill to one agent (e.g. Claude Code)
+npx skills add ASRagab/orca-ts --skill orcats-setup --agent claude-code
+```
+
+Without `--global` the skills install into the current repo's agent directory
+(project scope). Install order does not matter, but the intended flow is
+`orcats-setup` → `orcats-author` → `orcats-flow`. Each skill is a
+self-contained directory — its `SKILL.md` plus its own `scripts/`, `reference/`,
+and flow templates — so there is no shared payload to install separately.
+
+Before the repo is public, install from a local checkout instead:
+
+```bash
+git clone https://github.com/ASRagab/orca-ts.git
+npx skills add ./orca-ts --skill '*' --global
+```
+
+### Run A Saved Workflow
+
+Saved one-shot workflows live at the target repo's `.orca/workflows/<name>.ts`
+and are triggered through the Orcats CLI:
+
+```bash
+orcats --backend <tag> .orca/workflows/<name>.ts [-- "<task args>"]
+```
+
+Reusable loop modules live under `.orca/loops/<name>.ts` and use the loop CLI:
+
+```bash
+orcats loops
+orcats run <name-or-path>
+orcats serve <name-or-path>
+```
+
+Detailed guidance lives in each skill's `SKILL.md`.
+
+## Guides And Reference
+
+| Document | Purpose |
+| --- | --- |
+| [Backend reference](docs/backends.md) | Backend adapter behavior and live smoke details |
+| [Saved workflows](docs/workflows.md) | Generated workflow gates, baseline policy, and runbook behavior |
+| [Loops](docs/loops.md) | Loop tutorial, recipes, API notes, state, distribution, and troubleshooting |
+| [Plans](docs/plans.md) | Persistent plan helpers under `.orca/` |
+| [Review automation](docs/review.md) | Reviewer prompts, review loops, and fix execution |
+| [Parity harness](docs/parity.md) | Fixture tiers, schema exports, and backend parity checks |
+| [Distribution](docs/distribution.md) | npm package, GitHub Release binaries, installer, and embedded import notes |
+| [Release checks](docs/release.md) | Release runbook |
+| [Project language](CONTEXT.md) | Terminology used in code, docs, and agent work |
+| [Agent notes](AGENTS.md) | Contributor and agent-facing implementation context |
+
+## Public API Surface
+
+The root export re-exports the main authoring modules:
+
+```ts
+import {
+  captureDirtyBaselineSnapshot,
+  claude,
+  codex,
+  currentFlowContext,
+  flow,
+  llm,
+  loop,
+  opencode,
+  pi,
+  plan,
+  review,
+  resolveBaselinePolicy,
+  runBaselineGate,
+  selectBackend,
+  z
+} from "@twelvehart/orcats";
+```
+
+The package metadata exposes these entry points:
+
+| Entry point | Purpose |
+| --- | --- |
+| `@twelvehart/orcats` | Root flow authoring API |
+| `@twelvehart/orcats/model` | Shared model types and schemas |
+| `@twelvehart/orcats/testing` | Test helpers |
+| `bin.orcats` | Bun CLI shim installed by the npm package and source checkouts; release installs use the compiled standalone binary |
+
+## Development Commands
+
+```bash
+bun run typecheck
+bun test
+bun run docs:check
+bun run lint
+bun run validate:fixtures
+bun run validate:release
+bun run validate:package
+bun run build:types
+bun run build:binary
+bun run build:release
+bun run smoke:package
+bun run smoke:binary
+```
+
+Run the full deterministic gate before opening a pull request:
+
+```bash
+bun run verify
+```
+
+Run a live backend smoke only in an environment configured for that backend:
+
+```bash
+ORCA_REAL_BACKEND_SMOKE=1 ORCA_REAL_BACKEND=codex bun test tests/integration/real-backend-smoke.test.ts
+ORCA_REAL_BACKEND_SMOKE=1 ORCA_REAL_BACKEND=claude bun test tests/integration/real-backend-smoke.test.ts
+ORCA_REAL_BACKEND_SMOKE=1 ORCA_REAL_BACKEND=opencode bun test tests/integration/real-backend-smoke.test.ts
+ORCA_REAL_BACKEND_SMOKE=1 ORCA_REAL_BACKEND=pi bun test tests/integration/real-backend-smoke.test.ts
+```
+
+## Troubleshooting
+
+| Problem | What to check |
+| --- | --- |
+| `bun` is missing or too old | Install Bun `>=1.3.0` for source/project workflows; standalone binaries do not need Bun |
+| CLI prints typecheck errors | Run `bun run typecheck`, fix the TypeScript errors, then rerun the flow |
+| `orcats` is not found after npm install | Run it through the local package bin with `bunx -p @twelvehart/orcats orcats`, or add `node_modules/.bin` to your script path |
+| `orcats: missing project typecheck setup` warning | Add `typescript`, `tsconfig.json`, and a local `@twelvehart/orcats` package dependency in the flow project to restore the typecheck guard |
+| Live flow cannot start a backend | Confirm the backend CLI or adapter is on `PATH`, authenticated, and usable outside Orcats |
+| `--backend` seems to do nothing | The flow must call `selectBackend()`; direct `claude()`/`codex()` calls pin the backend |
+| Installer fails on checksum | Re-run; if persistent, download the tarball and `SHA256SUMS.txt` from the release page manually |
+| Live backend smoke is skipped | Set `ORCA_REAL_BACKEND_SMOKE=1` and choose `ORCA_REAL_BACKEND` |
+| OpenCode process keeps running | Own the backend instance and call `opencode().shutdown()` when your program is done |
+
+## Contributing
+
+Keep README content focused on users first: what Orca is, how to install it, how to run it, how to write flows, and where to find reference material.
+
+Implementation history, parity notes, and agent-specific guidance belong in `AGENTS.md`, `CONTEXT.md`, `docs/`, or archived OpenSpec changes rather than in the quickstart path.
+
+Before submitting changes, run:
+
+```bash
+bun run verify
+```
+
+## License And Attribution
+
+Orcats is licensed under Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+
+Scala Orca by VirtusLab was the starting point and reference for this TypeScript-native reimagining. The original Orca project is Apache-2.0 licensed.

package/bin/orcats

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { main } from "../src/cli/main.ts";
+
+await main();

package/dist/backends/acp-client.d.ts

@@ -0,0 +1,74 @@
+export type AcpId = number | string;
+export interface AcpErrorPayload {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+}
+export interface AcpRequestMessage {
+    readonly jsonrpc: "2.0";
+    readonly id: AcpId;
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface AcpNotificationMessage {
+    readonly jsonrpc: "2.0";
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface AcpResponseMessage {
+    readonly jsonrpc: "2.0";
+    readonly id: AcpId;
+    readonly result?: unknown;
+    readonly error?: AcpErrorPayload;
+}
+export type AcpIncomingMessage = AcpRequestMessage | AcpNotificationMessage;
+export interface AcpProcess {
+    readonly stdout: AsyncIterable<string | Uint8Array>;
+    readonly stderr?: AsyncIterable<string | Uint8Array>;
+    readonly exit: Promise<number | null>;
+    write(data: string): void;
+    endStdin(): void;
+    kill(signal?: NodeJS.Signals): void;
+}
+export interface AcpSpawnOptions {
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export type AcpProcessSpawner = (command: string, args: readonly string[], options: AcpSpawnOptions) => AcpProcess;
+export type AcpRequestHandler = (message: AcpRequestMessage) => unknown;
+export interface AcpClientOptions {
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly capacity?: number;
+    readonly requestTimeoutMs?: number;
+    readonly spawnProcess?: AcpProcessSpawner;
+    readonly handleRequest?: AcpRequestHandler;
+    readonly onIncomingMessage?: () => void;
+}
+export declare class AcpClient {
+    private readonly options;
+    readonly process: AcpProcess;
+    private readonly queue;
+    private readonly pending;
+    private readonly closedState;
+    private nextId;
+    private closed;
+    readonly stderr: Promise<string>;
+    readonly done: Promise<void>;
+    constructor(options: AcpClientOptions);
+    messages(): AsyncIterable<AcpIncomingMessage>;
+    request<T = unknown>(method: string, params?: unknown): Promise<T>;
+    notify(method: string, params?: unknown): void;
+    close(signal?: NodeJS.Signals, force?: boolean): void;
+    private readLoop;
+    private route;
+    private respondToRequest;
+    private finish;
+    private fail;
+    private write;
+}
+export declare function createAcpClient(options: AcpClientOptions): AcpClient;
+export declare function spawnAcpProcess(command: string, args: readonly string[], options: AcpSpawnOptions): AcpProcess;
+//# sourceMappingURL=acp-client.d.ts.map

package/dist/backends/acp-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-client.d.ts","sourceRoot":"","sources":["../../src/backends/acp-client.ts"],"names":[],"mappings":"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"}

package/dist/backends/acp-run.d.ts

@@ -0,0 +1,31 @@
+import { type AcpProcess, type AcpProcessSpawner } from "./acp-client.ts";
+import { type SharedBackendConfig } from "./conversation-config.ts";
+import type { AutonomousRequest } from "./types.ts";
+import type { StreamConversation } from "../conversation/index.ts";
+import { type BackendTag } from "../model/index.ts";
+export interface AcpBackendRuntimeOptions<B extends BackendTag, Output = unknown> {
+    readonly backend: B;
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly config?: SharedBackendConfig<Output>;
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly spawnProcess?: AcpProcessSpawner;
+    readonly setProcess: (process: AcpProcess) => void;
+    readonly setCancel: (cancel: () => Promise<void>) => void;
+    readonly cancelTimeoutMs?: number;
+    readonly shutdownTimeoutMs?: number;
+    readonly requestTimeoutMs?: number;
+    readonly inactivityTimeoutMs?: number;
+}
+export declare function experimentalAcpBackendEnabled(backend: "claude" | "codex"): boolean;
+export declare function claudeAcpCommand(): {
+    readonly command: string;
+    readonly args: readonly string[];
+};
+export declare function codexAcpCommand(): {
+    readonly command: string;
+    readonly args: readonly string[];
+};
+export declare function runAcpConversation<Output, B extends "claude" | "codex">(request: AutonomousRequest<Output, B>, options: AcpBackendRuntimeOptions<B, Output>, conversation: StreamConversation<B>): Promise<void>;
+//# sourceMappingURL=acp-run.d.ts.map

package/dist/backends/acp-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-run.d.ts","sourceRoot":"","sources":["../../src/backends/acp-run.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,iBAAiB,EAEvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC1F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAML,KAAK,UAAU,EAEhB,MAAM,mBAAmB,CAAC;AAI3B,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,GAAG,OAAO;IAC9E,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC9C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAC;IACnD,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;IAC1D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,GAAG,OAAO,CAMlF;AAED,wBAAgB,gBAAgB,IAAI;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAEjG;AAED,wBAAgB,eAAe,IAAI;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAchG;AAaD,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,CAAC,SAAS,QAAQ,GAAG,OAAO,EAC3E,OAAO,EAAE,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,EACrC,OAAO,EAAE,wBAAwB,CAAC,CAAC,EAAE,MAAM,CAAC,EAC5C,YAAY,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,IAAI,CAAC,CA6Hf"}

package/dist/backends/claude-run.d.ts

@@ -0,0 +1,35 @@
+import type { z } from "zod";
+import { type SubprocessProcess, type SubprocessSpawner } from "./subprocess-run.ts";
+import type { AutonomousRequest, LlmBackend } from "./types.ts";
+import { StreamConversation } from "../conversation/index.ts";
+import { 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 declare function claudeStreamJsonArgs<Output>(config: ResolvedClaudeConfig<Output>): readonly string[];
+export declare function runClaudeConversation<Output>(request: AutonomousRequest<Output, "claude">, options: ClaudeBackendOptions, conversation: StreamConversation<"claude">, setProcess: (process: ClaudeProcess) => void): Promise<void>;
+export declare function claude(options?: ClaudeBackendOptions): LlmBackend<"claude">;
+export {};
+//# sourceMappingURL=claude-run.d.ts.map

package/dist/backends/claude-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-run.d.ts","sourceRoot":"","sources":["../../src/backends/claude-run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAU7B,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEzF,MAAM,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAC9C,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;AACrD,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,aAAa,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAC7C,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,iBAAiB,EAAE,iBAAiB,CAAC;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC1C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,UAAU,oBAAoB,CAAC,MAAM;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,oBAAoB,CAAC,MAAM,CAAC,GAAG,SAAS,MAAM,EAAE,CAepG;AASD,wBAAsB,qBAAqB,CAAC,MAAM,EAChD,OAAO,EAAE,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,EAC5C,OAAO,EAAE,oBAAoB,EAC7B,YAAY,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EAC1C,UAAU,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,GAC3C,OAAO,CAAC,IAAI,CAAC,CAgCf;AA6BD,wBAAgB,MAAM,CAAC,OAAO,GAAE,oBAAyB,GAAG,UAAU,CAAC,QAAQ,CAAC,CAsE/E"}

package/dist/backends/claude-stream-json.d.ts

@@ -0,0 +1,15 @@
+import type { z } from "zod";
+import { StreamConversation, type ConversationCapture } from "../conversation/index.ts";
+export type ClaudeParseResult = ConversationCapture<"claude">;
+export interface ClaudeStreamOptions<Output = unknown> {
+    readonly schema?: z.ZodType<Output>;
+}
+export declare function collectClaudeStreamJson(lines: readonly string[]): Promise<ClaudeParseResult>;
+export declare function consumeClaudeStreamJson<Output = unknown>(lines: readonly string[], conversation: StreamConversation<"claude">, options?: ClaudeStreamOptions<Output>): Promise<void>;
+export interface ClaudeStreamConsumer {
+    readonly signal: AbortSignal;
+    consume(raw: string): Promise<void>;
+    finish(): void;
+}
+export declare function createClaudeStreamConsumer<Output = unknown>(conversation: StreamConversation<"claude">, options?: ClaudeStreamOptions<Output>): ClaudeStreamConsumer;
+//# sourceMappingURL=claude-stream-json.d.ts.map

package/dist/backends/claude-stream-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-stream-json.d.ts","sourceRoot":"","sources":["../../src/backends/claude-stream-json.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQ7B,OAAO,EAEL,kBAAkB,EAClB,KAAK,mBAAmB,EACzB,MAAM,0BAA0B,CAAC;AAuClC,MAAM,MAAM,iBAAiB,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;AAE9D,MAAM,WAAW,mBAAmB,CAAC,MAAM,GAAG,OAAO;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;CACrC;AAED,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAOlG;AAED,wBAAsB,uBAAuB,CAAC,MAAM,GAAG,OAAO,EAC5D,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,YAAY,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EAC1C,OAAO,GAAE,mBAAmB,CAAC,MAAM,CAAM,GACxC,OAAO,CAAC,IAAI,CAAC,CASf;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,wBAAgB,0BAA0B,CAAC,MAAM,GAAG,OAAO,EACzD,YAAY,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EAC1C,OAAO,GAAE,mBAAmB,CAAC,MAAM,CAAM,GACxC,oBAAoB,CAuCtB"}