diff --git a/README.ja.md b/README.ja.md index 39c2492..73286f0 100644 --- a/README.ja.md +++ b/README.ja.md @@ -1,74 +1,26 @@ # Roboppi -[English](README.md) | 日本語 +

+ Roboppi +

-Roboppi（ろぼっぴ）は、エージェント（worker）の実行を安全に制御するための「実行制御ランタイム」です。 +[English](README.md) | 日本語 -Roboppi 自身が「エージェントとして仕事をする」ことは目的にしません。外部の worker CLI（OpenCode / Claude Code / Codex CLI / シェル）に重い作業（編集/コマンド/テスト）を委譲し、Roboppi は安全の不変条件（止める/制限する/観測する/隔離する）を強制します。 +Roboppi（ろぼっぴ）は、エージェント（worker）の実行を安全に制御するための「実行制御ランタイム」です。Roboppi 自身がエージェントとして仕事をするのではなく、外部の worker CLI（OpenCode / Claude Code / Codex CLI / シェル）に重い作業を委譲し、安全の不変条件（止める・制限する・観測する・隔離する）を強制します。 注意: 主な CLI/バイナリ名は `roboppi` です。 - 環境変数/状態ディレクトリ: `ROBOPPI_` / `.roboppi-loop/` を使います。 -## Roboppiでできること（Capabilities） - -実行制御（Core ランタイム）: - -- ハードな予算制約: timeout / max attempts / concurrency / RPS /（任意で）cost cap -- エンドツーエンドのキャンセル: Job -> Permit -> Worker を AbortSignal で伝播（best-effort で SIGTERM -> SIGKILL） -- 失敗の封じ込め: circuit breaker + backpressure（過負荷時の reject/defer/degrade） -- プロセス隔離: heavy work を別プロセスに委譲して blast radius を限定 -- 監査性: 構造化ログ + アーティファクト（stdout/stderr の要約、diff/patch、実行コマンド、時間など） - -ワークフロー（YAML オーケストレーション）: - -- 複数ステップの DAG 実行（`depends_on`）と並列度制御（`concurrency`） -- `context/` を使ったファイルベースの成果物受け渡し（`outputs` / `inputs`） -- 失敗ポリシー（`retry` / `continue` / `abort`）と自動リトライ -- `completion_check` + `max_iterations` による「完了するまでループ」 -- （任意）ループ収束ガード: 停滞検知 + スコープ/差分予算（`allowed_paths`, `max_changed_files`） - -自動化（Daemon モード）: - -- interval/cron/fswatch/webhook/command のイベントで workflow を常駐実行 -- evaluate/analyze ゲート（条件成立時だけ LLM/worker を走らせる） -- supervised 実行: Supervisor -> Core -> Worker のプロセスツリーを IPC で維持（socket transport あり） - -リポジトリ安全（git workspace）: +## 特徴 -- base branch の決定を固定化し、起動時 SHA を記録（追跡/再現性） -- Branch Lock: 実行中の repo/branch ドリフトを step 実行前に fail-fast -- Protected branch guard: `main` などへの直接編集をデフォルトでブロック（明示 override が必要） - -拡張性: - -- `WorkerAdapter` インタフェースで worker を追加 -- agent catalog（`agents.yaml`）で `step.agent` による再利用プロファイル - -スケジューリング（参照実装）: - -- 優先度付きジョブキュー（interactive vs batch） -- idempotency key による重複制御（`coalesce` / `latest-wins` / `reject`） -- リトライポリシー（指数バックオフ + jitter）と DLQ -- Core を起動/監視する Supervisor（クラッシュ/ハング対策） - -## アーキテクチャ（概要） - -Roboppi は 3 層構造として設計されています。 - -``` -Supervisor / Runner（policy, 親プロセス） - -> Core（mechanism, 子プロセス） - -> Worker プロセス（外部 CLI） -``` - -- Core が安全の不変条件（permits, budgets, cancellation, cutoffs）を保持します。 -- policy（順序、リトライ、重複制御など）は Supervisor/Runner 側に寄せて差し替え可能にします。 -- Core と Supervisor は JSON Lines IPC で通信します。 - -設計資料: - -- `docs/design.md` -- `docs/guide/architecture.md` +- ハードな予算制約 -- timeout / max attempts / concurrency / RPS / cost cap +- エンドツーエンドのキャンセル -- Job -> Permit -> Worker を AbortSignal で伝播 +- 失敗の封じ込め -- circuit breaker + backpressure による過負荷制御 +- プロセス隔離 -- heavy work を別プロセスに委譲して blast radius を限定 +- YAML ワークフロー -- DAG 実行、並列度制御、ループ完了判定、失敗ポリシー +- Daemon モード -- interval/cron/fswatch/webhook で workflow を常駐実行 +- ブランチ安全 -- base branch 固定、Branch Lock、保護ブランチガード +- 構造化ログとアーティファクト -- stdout/stderr 要約、diff/patch、実行コマンド、時間 ## インストール @@ -201,7 +153,72 @@ ROBOPPI_ROOT="$ROBOPPI_ROOT" bun run --cwd "$ROBOPPI_ROOT" src/workflow/run.ts \ - workflow は target workspace 内に `.roboppi-loop/` と `context/` を作ります（通常は gitignore 推奨）。 - PR 作成は `.roboppi-loop/enable_pr` による opt-in です。 -## Workflow YAML の最小例 +## アーキテクチャ（概要） + +Roboppi は 3 層構造として設計されています。 + +``` +Supervisor / Runner（policy, 親プロセス） + -> Core（mechanism, 子プロセス） + -> Worker プロセス（外部 CLI） +``` + +- Core が安全の不変条件（permits, budgets, cancellation, cutoffs）を保持します。 +- policy（順序、リトライ、重複制御など）は Supervisor/Runner 側に寄せて差し替え可能にします。 +- Core と Supervisor は JSON Lines IPC で通信します。 + +設計資料: + +- `docs/design.md` +- `docs/guide/architecture.md` + +--- + +## リファレンス + +### 機能の詳細 + +**実行制御（Core ランタイム）:** + +- ハードな予算制約: timeout / max attempts / concurrency / RPS /（任意で）cost cap +- エンドツーエンドのキャンセル: Job -> Permit -> Worker を AbortSignal で伝播（best-effort で SIGTERM -> SIGKILL） +- 失敗の封じ込め: circuit breaker + backpressure（過負荷時の reject/defer/degrade） +- プロセス隔離: heavy work を別プロセスに委譲して blast radius を限定 +- 監査性: 構造化ログ + アーティファクト（stdout/stderr の要約、diff/patch、実行コマンド、時間など） + +**ワークフロー（YAML オーケストレーション）:** + +- 複数ステップの DAG 実行（`depends_on`）と並列度制御（`concurrency`） +- `context/` を使ったファイルベースの成果物受け渡し（`outputs` / `inputs`） +- 失敗ポリシー（`retry` / `continue` / `abort`）と自動リトライ +- `completion_check` + `max_iterations` による「完了するまでループ」 +- （任意）ループ収束ガード: 停滞検知 + スコープ/差分予算（`allowed_paths`, `max_changed_files`） + +**自動化（Daemon モード）:** + +- interval/cron/fswatch/webhook/command のイベントで workflow を常駐実行 +- evaluate/analyze ゲート（条件成立時だけ LLM/worker を走らせる） +- supervised 実行: Supervisor -> Core -> Worker のプロセスツリーを IPC で維持（socket transport あり） + +**リポジトリ安全（git workspace）:** + +- base branch の決定を固定化し、起動時 SHA を記録（追跡/再現性） +- Branch Lock: 実行中の repo/branch ドリフトを step 実行前に fail-fast +- Protected branch guard: `main` などへの直接編集をデフォルトでブロック（明示 override が必要） + +**拡張性:** + +- `WorkerAdapter` インタフェースで worker を追加 +- agent catalog（`agents.yaml`）で `step.agent` による再利用プロファイル + +**スケジューリング（参照実装）:** + +- 優先度付きジョブキュー（interactive vs batch） +- idempotency key による重複制御（`coalesce` / `latest-wins` / `reject`） +- リトライポリシー（指数バックオフ + jitter）と DLQ +- Core を起動/監視する Supervisor（クラッシュ/ハング対策） + +### Workflow YAML の最小例 ```yaml name: build-test @@ -228,7 +245,7 @@ steps: 詳細: `docs/guide/workflow.md` -## Agent Catalog（再利用できるエージェント定義） +### Agent Catalog（再利用できるエージェント定義） 同じ worker/model/capabilities/base-instructions を繰り返す場合、外部 YAML（agent catalog）にまとめられます。 @@ -258,7 +275,7 @@ steps: - `docs/guides/agents.md` - `docs/guides/agents.ja.md` -## ブランチ安全（git workspace） +### ブランチ安全（git workspace） git repo に対する workflow 実行向けに、base branch 解決 / Branch Lock / 保護ブランチガードを提供します。 @@ -273,7 +290,7 @@ git repo に対する workflow 実行向けに、base branch 解決 / Branch Loc - `docs/guides/branch.md` - `docs/guides/branch.ja.md` -## Supervised IPC transport（supervised 実行） +### Supervised IPC transport（supervised 実行） supervised 実行では runner/daemon が Core 子プロセスを起動し、IPC 経由で step を委譲します。 diff --git a/README.md b/README.md index 1769aea..a01c242 100644 --- a/README.md +++ b/README.md @@ -6,73 +6,21 @@ English | [日本語](README.ja.md) -Roboppi (ろぼっぴ, pronounced "roh-boh-pee") is an execution-control runtime for agentic workers. - -It does not try to be "the agent". It enforces safety invariants around external worker CLIs (OpenCode / Claude Code / Codex CLI / plain shell), so your automation stops when it should, stays within budgets, and leaves a trail you can audit. +Roboppi (ろぼっぴ, pronounced "roh-boh-pee") is an execution-control runtime for agentic workers. It does not try to be "the agent" — it enforces safety invariants around external worker CLIs (OpenCode / Claude Code / Codex CLI / plain shell), so your automation stops when it should, stays within budgets, and leaves a trail you can audit. Note: the primary CLI/binary name is `roboppi`. - Env vars/state dirs: use `ROBOPPI_` / `.roboppi-loop/`. -## What Roboppi Can Do (Capabilities) - -Execution control (Core runtime): - -- Enforce hard budgets: timeouts, max attempts, concurrency, RPS, optional cost caps -- End-to-end cancellation: Job -> Permit -> Worker via AbortSignal (best-effort SIGTERM -> SIGKILL) -- Failure containment: circuit breakers + backpressure responses under overload -- Process isolation: delegate heavy work to separate worker processes (limit blast radius) -- Auditability: structured logs + artifacts (stdout/stderr summaries, diffs/patches, executed commands, timings) - -Workflow orchestration (YAML): - -- Run multi-step DAG workflows (`depends_on`) with optional parallelism (`concurrency`) -- Pass files between steps with declared `outputs`/`inputs` via a `context/` directory -- Automatic step retries and failure policy (`retry` / `continue` / `abort`) -- Loop until complete with `completion_check` + `max_iterations` -- Optional convergence guard for loops: stall detection + scope/diff budgets (`allowed_paths`, `max_changed_files`) - -Automation (Daemon mode): - -- Run workflows on interval/cron/fswatch/webhook/command events -- Optional evaluate/analyze gates (run LLM work only when conditions are met) -- Supervised execution: Supervisor -> Core -> Worker process tree via IPC (socket-based transport available) - -Repo safety (git workspaces): - -- Deterministic base branch resolution (records base commit SHA) -- Branch Lock drift detection (fail-fast before a step runs) -- Protected-branch guard to avoid direct edits on `main` (override must be explicit) - -Extensibility: - -- Add worker adapters behind a unified `WorkerAdapter` interface -- Reusable agent profiles via agent catalogs (`agents.yaml`) referenced by `step.agent` - -Scheduling (reference implementation): - -- Prioritized job queue (interactive vs batch) -- Deduplication via idempotency keys (`coalesce` / `latest-wins` / `reject`) -- Retry policy (exponential backoff + jitter) + DLQ storage -- Supervisor that launches/monitors the Core process (crash/hang handling) - -## Architecture (High Level) +## Features at a Glance -Roboppi is designed as a 3-layer system: - -``` -Supervisor / Runner (policy, parent process) - -> Core (mechanism, child process) - -> Worker processes (external CLIs) -``` - -- Core owns safety invariants (permits, budgets, cancellation, cutoffs). -- Policy (ordering, retries, dedup strategy) stays swappable at the supervisor/runner level. -- Core and supervisor communicate over JSON Lines IPC. - -Design docs: - -- `docs/design.md` -- `docs/guide/architecture.md` +- **Hard budget enforcement** — timeouts, max attempts, concurrency, RPS, cost caps +- **End-to-end cancellation** — Job to Permit to Worker via AbortSignal (SIGTERM then SIGKILL) +- **Failure containment** — circuit breakers and backpressure under overload +- **Process isolation** — delegate heavy work to separate worker processes, limiting blast radius +- **YAML workflow orchestration** — multi-step DAGs with parallelism, retries, and loop-until-complete +- **Daemon mode** — trigger workflows on interval, cron, fswatch, webhook, or command events +- **Branch safety** — base-branch resolution, drift detection, and protected-branch guards +- **Extensible worker adapters** — unified interface for OpenCode, Claude Code, Codex CLI, and custom agents ## Install @@ -208,7 +156,72 @@ Notes: - The workflow writes state/artifacts under `.roboppi-loop/` and `context/` inside the target workspace (typically gitignored). - PR creation is opt-in via `.roboppi-loop/enable_pr`. -## Workflow YAML At A Glance +## Architecture + +Roboppi is designed as a 3-layer system: + +``` +Supervisor / Runner (policy, parent process) + -> Core (mechanism, child process) + -> Worker processes (external CLIs) +``` + +- Core owns safety invariants (permits, budgets, cancellation, cutoffs). +- Policy (ordering, retries, dedup strategy) stays swappable at the supervisor/runner level. +- Core and supervisor communicate over JSON Lines IPC. + +Design docs: + +- `docs/design.md` +- `docs/guide/architecture.md` + +--- + +## Reference + +### Capabilities in Detail + +**Execution control (Core runtime):** + +- Enforce hard budgets: timeouts, max attempts, concurrency, RPS, optional cost caps +- End-to-end cancellation: Job -> Permit -> Worker via AbortSignal (best-effort SIGTERM -> SIGKILL) +- Failure containment: circuit breakers + backpressure responses under overload +- Process isolation: delegate heavy work to separate worker processes (limit blast radius) +- Auditability: structured logs + artifacts (stdout/stderr summaries, diffs/patches, executed commands, timings) + +**Workflow orchestration (YAML):** + +- Run multi-step DAG workflows (`depends_on`) with optional parallelism (`concurrency`) +- Pass files between steps with declared `outputs`/`inputs` via a `context/` directory +- Automatic step retries and failure policy (`retry` / `continue` / `abort`) +- Loop until complete with `completion_check` + `max_iterations` +- Optional convergence guard for loops: stall detection + scope/diff budgets (`allowed_paths`, `max_changed_files`) + +**Automation (Daemon mode):** + +- Run workflows on interval/cron/fswatch/webhook/command events +- Optional evaluate/analyze gates (run LLM work only when conditions are met) +- Supervised execution: Supervisor -> Core -> Worker process tree via IPC (socket-based transport available) + +**Repo safety (git workspaces):** + +- Deterministic base branch resolution (records base commit SHA) +- Branch Lock drift detection (fail-fast before a step runs) +- Protected-branch guard to avoid direct edits on `main` (override must be explicit) + +**Extensibility:** + +- Add worker adapters behind a unified `WorkerAdapter` interface +- Reusable agent profiles via agent catalogs (`agents.yaml`) referenced by `step.agent` + +**Scheduling (reference implementation):** + +- Prioritized job queue (interactive vs batch) +- Deduplication via idempotency keys (`coalesce` / `latest-wins` / `reject`) +- Retry policy (exponential backoff + jitter) + DLQ storage +- Supervisor that launches/monitors the Core process (crash/hang handling) + +### Workflow YAML At A Glance Minimal example: @@ -237,7 +250,7 @@ For loops: See `docs/guide/workflow.md` for the full schema. -## Agent Catalogs (Reusable Agent Profiles) +### Agent Catalogs (Reusable Agent Profiles) If you repeat the same worker/model/capabilities/base-instructions across steps, define an agent catalog: @@ -267,7 +280,7 @@ Docs: - `docs/guides/agents.md` - `docs/guides/agents.ja.md` -## Branch Safety (Git Workspaces) +### Branch Safety (Git Workspaces) For workflows that operate on git repos, Roboppi provides base-branch resolution, Branch Lock drift detection, and protected-branch guards. @@ -282,7 +295,7 @@ Docs: - `docs/guides/branch.md` - `docs/guides/branch.ja.md` -## Supervised IPC Transport (For `--supervised`) +### Supervised IPC Transport (For `--supervised`) Workflows/daemon run supervised by default. In supervised mode, the runner starts a Core child process and delegates steps over IPC.