diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..a6b41ee --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,47 @@ +# Changelog + +All notable changes are documented here. Dates use ISO 8601 format. + +## [Unreleased] — 2026-08-13 + +### Added + +- Durable run-event streaming over Server-Sent Events, with reconnect-safe + cursors and a live TUI dashboard for graph state, attempts, evidence, + transcripts, budgets, permissions, and operator actions. +- Standalone Claude Code adapter with streamed transcripts, usage/cost + accounting, scoped permission mediation, and abort/retry handling. +- Permission-aware scheduler state: pending provider permissions pause attempt + budgets, move nodes to `blocked`, expose the requested tool/input to + operators, and resume only after an explicit decision. +- Worktree inspection and cleanup improvements, including preservation of dirty + worktrees and safe pruning of merged or stale clean worktrees. +- Workflow diagrams and a visual trust-loop/brand system in `docs/` and the + repository root. + +### Changed + +- Agent authorization is now fail-closed. Managed OpenCode roles refresh on + `corral init`, worktree sessions receive the managed policy, and provider + prompts select the role-specific agent. +- Gate pre-authorization is operator-only; model agents cannot grant that + authority to themselves. +- Graph validation accepts only supported agent roles and safe relative write + scopes. Scheduler verification rejects changes outside the declared scope. +- Planner and reviewer tool permissions default to deny, while workers require + approval for edits and shell commands. +- API-key material is kept in `.corral/api.key` instead of being duplicated in + project-readable config metadata. + +### Fixed + +- TUI event ordering, reconnect, terminal-run, and attention behavior. +- Attempt identity collisions across runs and event-subscriber loss after + overload. +- Retry feedback, reviewer read-only boundaries, and provider stream/usage + preservation. + +## [0.2.0] + +See the [v0.2.0 release](https://github.com/thiago-ss/corral/releases/tag/v0.2.0) +for the previous baseline. diff --git a/README.md b/README.md index 13737fa..38833e3 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![CI](https://img.shields.io/github/actions/workflow/status/thiago-ss/corral/ci.yml?branch=main&style=flat-square&label=CI&labelColor=191A16&color=1F7A50)](https://github.com/thiago-ss/corral/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/thiago-ss/corral?style=flat-square&labelColor=191A16&color=D8890B)](https://github.com/thiago-ss/corral/releases) [![Go](https://img.shields.io/badge/Go-1.26.5-2B63D9?style=flat-square&labelColor=191A16)](https://go.dev) [![License](https://img.shields.io/badge/license-MIT-1F7A50?style=flat-square&labelColor=191A16)](LICENSE) -[Why Corral](#why-corral) · [Default run](#the-default-run) · [Install](#quick-start) · [Architecture](#how-trust-is-built) +[Why Corral](#why-corral) · [Default run](#the-default-run) · [Install](#quick-start) · [Codex](docs/codex.md) · [Changelog](CHANGELOG.md) · [Architecture](#how-trust-is-built) **[Install and run →](#quick-start)** @@ -91,6 +91,12 @@ Inside OpenCode: set `autoApproveGates` when creating a run; model agents cannot grant that authority to themselves. +From Codex, use the terminal as the operator: run `corral up`, review a graph +through `/api/plan`, start it through `/api/runs`, and monitor it with +`corral tui` or `corral status`. The complete copy/paste flow, gate commands, +and operator prompt pattern live in [`docs/codex.md`](docs/codex.md). Codex is +not yet a native Corral executor; OpenCode runs the isolated worker sessions. + Or follow the same run from the terminal: ```sh diff --git a/docs/codex.md b/docs/codex.md new file mode 100644 index 0000000..a6301e6 --- /dev/null +++ b/docs/codex.md @@ -0,0 +1,113 @@ +# Using Corral from Codex + +Corral's production executor is OpenCode. Codex does not currently act as a +native Corral worker or planner, but Codex can operate Corral through its +terminal: start the local daemon, submit/review graphs, follow runs, and make +operator decisions. Agent execution still happens in isolated OpenCode +worktrees. + +## One-time setup + +From the repository you want Corral to manage, run this in a Codex terminal: + +```sh +corral up +corral doctor +``` + +`corral up` is idempotent. It creates `.corral/`, keeps the API key in +`.corral/api.key`, installs the OpenCode plugin/config, starts the daemon, and +checks health. Restart OpenCode after the first setup if you also use its +native Corral tools. + +If `corral` is not installed yet, install it first using the project +installation instructions in the README, or build the current checkout: + +```sh +go build -o corral ./cmd/corral +./corral up +``` + +## Recommended Codex workflow + +1. Ask Codex to inspect the repository and write a short goal and acceptance + criteria. +2. Ask Codex to submit the goal to Corral's planner API. Do not start the run + until you have inspected the returned graph. +3. Start the approved graph. Record the returned run ID. +4. Follow progress with `corral tui` or `corral status`. +5. Stop at human gates and inspect the evidence. Approve, reject, retry, steer, + or cancel only as the operator. +6. Export the audit record when the run completes. + +The following commands are a copy/paste API flow. They use the local operator +key generated by `corral init`: + +```sh +base="${CORRAL_DAEMON_URL:-http://127.0.0.1:4519}" +key="$(tr -d '\n' < .corral/api.key)" + +# Ask the read-only planner for a graph. +curl -fsS "$base/api/plan" \ + -H "Authorization: Bearer $key" \ + -H 'X-Corral-Role: operator' \ + -H 'Content-Type: application/json' \ + -d '{"goal":"Add CSV export for monthly expenses, with tests and documentation."}' \ + > /tmp/corral-plan.json + +# Review graph before starting any work. +jq . /tmp/corral-plan.json + +# Start only after the graph is approved. +run_id="$(curl -fsS "$base/api/runs" \ + -H "Authorization: Bearer $key" \ + -H 'X-Corral-Role: operator' \ + -H 'Content-Type: application/json' \ + --data-binary @/tmp/corral-plan.json | jq -r .runID)" +echo "run: $run_id" + +# Inspect/follow the run. +corral status +corral tui + +# Export the durable audit record after completion. +corral export "$run_id" --out ".corral/$run_id.json" +``` + +For a gate decision, first inspect the run in the TUI or with `GET +/api/runs/`, then call the operator endpoint. Replace `gate` with the +actual node ID: + +```sh +curl -fsS -X POST "$base/api/runs/$run_id/approve" \ + -H "Authorization: Bearer $key" \ + -H 'X-Corral-Role: operator' \ + -H 'Content-Type: application/json' \ + -d '{"nodeID":"gate"}' +``` + +Use `/reject`, `/retry`, `/steer`, `/cancel`, or `/permission` in the same way +when the evidence calls for another operator action. Never approve a gate +merely because an agent says it is safe; inspect the graph, diff, verification +result, and permission details first. + +## Prompt pattern for Codex + +This keeps Codex in an operator role while Corral owns execution: + +> Use Corral for this goal: ``. Inspect the repository first. Submit a +> plan, show me the graph and acceptance criteria, and wait for my approval. +> After I approve, start the run, report the run ID, monitor it, and stop at +> every human gate or permission request. Do not approve gates or permissions +> without my explicit instruction. At completion, summarize verification, +> changed files, and the audit export path. + +## Boundaries + +- Codex terminal commands use the operator API role; protect `.corral/api.key`. +- The daemon enforces role checks server-side; model agents cannot mint + operator gate authority. +- Work is performed by OpenCode sessions in isolated worktrees, then verified + before merge. +- There is no native Codex driver yet. Native Codex execution is a roadmap + item, not a capability this workflow silently substitutes.