From 7da911711fa667f5706a922ced9f69f6b6a710a1 Mon Sep 17 00:00:00 2001 From: Harshit Singh Bhandari Date: Sun, 14 Jun 2026 18:42:18 +0530 Subject: [PATCH] docs: sync documentation with current state of main (#228) * docs: sync documentation with current state of main The rewrite is further along than several docs claimed. Bring the docs in line with the actual code on main: - status.md: rewrite the stale "session HTTP routes not wired yet" / "next integration work" framing into a shipped vs in-flight breakdown. - cli/README.md: document the full product command surface (project, session, spawn, send, orchestrator) instead of "not present yet". - architecture.md: correct the package layout (service/{pr,review}, observe/scm, observe/reaper, daemon, config) and add the no_signal status to the derivation precedence. - backend-code-structure.md: add service/review and observe/scm. - README.md: expand the agent-adapter list (20+), add project set-config, and describe the frontend as the real wired supervisor it is. - AGENTS.md / docs/README.md: drop "placeholder frontend" wording and add the agent-adapter doc to the index. Co-Authored-By: Claude Opus 4.8 * chore: format with prettier [skip ci] --- AGENTS.md | 4 +- README.md | 15 ++++-- docs/README.md | 3 +- docs/architecture.md | 31 +++++++----- docs/backend-code-structure.md | 5 +- docs/cli/README.md | 50 ++++++++++++++----- docs/status.md | 89 ++++++++++++++++++++++++++-------- 7 files changed, 144 insertions(+), 53 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a8fcf7e94..b7f36fb38 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,7 @@ Operational guidance for coding agents working in this repository. Keep changes ## Repo layout - `backend/` — Go rewrite of Agent Orchestrator: Cobra `ao` CLI, loopback HTTP daemon, services, SQLite storage, lifecycle/reaper, runtime/workspace/agent/tracker adapters, terminal mux, and tests. -- `frontend/` — placeholder Electron + TypeScript shell. Treat it as a thin supervisor/UI surface; do not move daemon logic into it. +- `frontend/` — Electron + React supervisor wired to the daemon via the generated typed client. Treat it as a thin supervisor/UI surface; do not move daemon logic into it. - `docs/` — current architecture/status notes. Start here before changing lifecycle, CLI, agents, storage, or daemon behavior. - `test/` — external smoke/e2e assets, including the CLI fresh-install container check. - `.github/workflows/` — CI definitions. Mirror these commands locally when possible. @@ -46,7 +46,7 @@ npm run build - `README.md` — current run/config/test quickstart. - `docs/README.md` — docs index. - `docs/architecture.md` — backend mental model, package layout, lifecycle/session/service boundaries, and load-bearing rules. -- `docs/status.md` — current implementation state and next integration work. +- `docs/status.md` — what is shipped on `main` today and what is still in flight. - `docs/cli/README.md` — intended CLI shape: thin Cobra client over daemon HTTP, never direct storage/runtime access. - `docs/agent/README.md` — agent adapter contract and hook behavior. - `CLAUDE.md` — compatibility pointer for Claude Code; it directs agents back to `AGENTS.md`. diff --git a/README.md b/README.md index b8122082b..5fcf05d9d 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,11 @@ and [`AGENTS.md`](AGENTS.md) for the contributor / worker contract. (`backend/internal/observe/scm/`): polling loop, ETag guards, semantic diffing, CI/check/review-thread tracking, and lifecycle nudges for CI failures, review feedback, and merge conflicts. -- Agent adapters under `backend/internal/adapters/agent/`: `claude-code`, - `codex`, `opencode`, `grok`, `cursor`, `qwen`, `copilot`, `kimi`, plus - shared activity-dispatch / hook utilities. +- A 20+ agent adapter platform under `backend/internal/adapters/agent/` + (`claude-code`, `codex`, `cursor`, `opencode`, `aider`, `amp`, `goose`, + `copilot`, `grok`, `qwen`, `kimi`, `crush`, `cline`, `droid`, and more), + registered through a shared registry with common activity-dispatch / hook + utilities. - SQLite store (`backend/internal/storage/sqlite/`) with sqlc-generated queries, DB-triggered change-data-capture into `change_log`, and a CDC poller/broadcaster (`backend/internal/cdc/`) feeding in-process subscribers @@ -89,6 +91,7 @@ below groups what's on `main` today. | Project | `ao project add` | Register a local git repo as a project. | | Project | `ao project ls` | List registered projects. | | Project | `ao project get ` | Fetch one project. | +| Project | `ao project set-config ` | Update per-project config. | | Project | `ao project rm ` | Remove a project. | | Session | `ao spawn` | Spawn a worker session in a registered project. | | Session | `ao session ls` | List sessions (filter by project, include terminated). | @@ -165,8 +168,10 @@ Current `main` ships the CLI surface above, the SCM observer end-to-end adapter platform, and the CDC pipeline with SSE replay. The Tracker observer ([#112](https://github.com/aoagents/agent-orchestrator/issues/112)) and live `pr_*` event consumers ([#110](https://github.com/aoagents/agent-orchestrator/issues/110)) -are in flight. The Electron supervisor under `frontend/` is still a placeholder -shell — daemon logic stays in the Go backend. +are in flight. The Electron + React supervisor under `frontend/` is real and +wired to the daemon over the generated typed client (projects/sessions board, +session view, terminal pane, pull-requests page); all daemon logic stays in the +Go backend. Tracking milestone: [`rewrite`](https://github.com/aoagents/agent-orchestrator/milestone/1) on GitHub. diff --git a/docs/README.md b/docs/README.md index 106087685..43c06876b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,7 +15,8 @@ Start with [architecture.md](architecture.md) for the current backend model and | [architecture.md](architecture.md) | Current backend model, package layout, status derivation, persistence/CDC, and load-bearing rules. | | [backend-code-structure.md](backend-code-structure.md) | Package ownership rules for the Go backend: domain, services, ports, adapters, storage, HTTP, CLI, and daemon wiring. | | [cli/README.md](cli/README.md) | CLI commands and daemon control surface. | -| [status.md](status.md) | Current implementation shape, build/test command, and next integration work. | +| [agent/README.md](agent/README.md) | Agent adapter contract, hook methodology, and session-info derivation. | +| [status.md](status.md) | What is shipped on `main` today and what is still in flight. | | [stack.md](stack.md) | Accepted library/runtime choices, pending stack decisions, and dependencies explicitly avoided for V1. | ## Mental model diff --git a/docs/architecture.md b/docs/architecture.md index c3c26affa..bf22974e4 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -23,17 +23,21 @@ record plus PR facts while assembling controller-facing read models. ## Package layout ``` -backend/internal/domain shared vocabulary and API status value types -backend/internal/ports inbound/outbound interfaces -backend/internal/service controller-facing services and read-model assembly -backend/internal/session_manager internal session command manager -backend/internal/lifecycle runtime/activity/spawn/termination session fact reducer -backend/internal/pr PR observation ingestion -backend/internal/storage SQLite persistence and DB-triggered CDC -backend/internal/cdc change-log poller and broadcaster -backend/internal/httpd daemon HTTP surface -backend/internal/terminal WebSocket terminal multiplexer -backend/internal/adapters Zellij/git-worktree/GitHub adapters +backend/internal/domain shared vocabulary and API status value types +backend/internal/ports inbound/outbound interfaces +backend/internal/service/{project,session,pr,review} + controller-facing services and read-model assembly +backend/internal/session_manager internal session command manager +backend/internal/lifecycle runtime/activity/spawn/termination session fact reducer +backend/internal/observe/scm SCM (GitHub) observer loop feeding PR facts +backend/internal/observe/reaper runtime liveness observation loop +backend/internal/storage SQLite persistence and DB-triggered CDC +backend/internal/cdc change-log poller and broadcaster +backend/internal/httpd daemon HTTP surface (REST + SSE + terminal mux) +backend/internal/terminal WebSocket terminal multiplexer +backend/internal/adapters agent/Zellij/git-worktree/GitHub SCM + tracker adapters +backend/internal/daemon production wiring and shutdown +backend/internal/config daemon env/default config ``` ## Status derivation @@ -46,7 +50,10 @@ applies this rough precedence: 3. Open PR facts drive PR pipeline statuses: `ci_failed`, `draft`, `changes_requested`, `mergeable`, `approved`, `review_pending`, `pr_open`. 4. `activity_state=active` → `working`. -5. Everything else → `idle`. +5. A signal-capable harness that has never sent a hook callback past the + ~90s spawn grace → `no_signal` (a broken hook pipeline is visible rather + than reported as a confident `idle`). Hook-less harnesses stay `idle`. +6. Everything else → `idle`. ## Lifecycle manager diff --git a/docs/backend-code-structure.md b/docs/backend-code-structure.md index efee5d58f..c197e43af 100644 --- a/docs/backend-code-structure.md +++ b/docs/backend-code-structure.md @@ -59,6 +59,7 @@ Current examples: internal/service/project internal/service/session internal/service/pr +internal/service/review ``` Belongs here: @@ -333,9 +334,11 @@ backend/ project/ # project API/use-case boundary session/ # session API/use-case boundary pr/ # PR observation/action service + review/ # code-review API/use-case boundary internal/session_manager/ # internal session command engine internal/lifecycle/ # durable lifecycle fact reducer - internal/observe/reaper/ # runtime observation loop + internal/observe/scm/ # SCM (GitHub) observer loop + internal/observe/reaper/ # runtime liveness observation loop internal/storage/sqlite/ # DB, migrations, queries, generated sqlc, stores internal/cdc/ # change_log poller and broadcaster internal/terminal/ # terminal session protocol and PTY handling diff --git a/docs/cli/README.md b/docs/cli/README.md index 923854c35..6d21fa565 100644 --- a/docs/cli/README.md +++ b/docs/cli/README.md @@ -7,20 +7,48 @@ call runtime, workspace, tracker, or agent adapters in-process. ## Current commands +Every product command resolves to a daemon HTTP route. Run `ao +--help` for the authoritative flag shape. + +### Daemon control + | Command | Purpose | | ----------------------------- | ------------------------------------------------------------------------------------------- | | `ao start` | Start the daemon in the background and wait for `/readyz`. | -| `ao status` | Report daemon state from `running.json`, process liveness, `/healthz`, and `/readyz`. | -| `ao status --json` | Emit the same daemon state as machine-readable JSON. | | `ao stop` | Gracefully stop the daemon via loopback `POST /shutdown` after verifying daemon identity. | -| `ao doctor` | Check config, data directory, DB-file presence, daemon state, `git`, and optional `zellij`. | -| `ao doctor --json` | Emit doctor checks as JSON. | +| `ao status` / `--json` | Report daemon state from `running.json`, process liveness, `/healthz`, and `/readyz`. | +| `ao doctor` / `--json` | Check config, data directory, DB-file presence, daemon state, `git`, and optional `zellij`. | | `ao completion ` | Generate completions for `bash`, `zsh`, `fish`, or `powershell`. | | `ao version` / `ao --version` | Print build metadata. | | `ao daemon` | Hidden internal daemon entrypoint used by `ao start`. | +### Product commands + +| Command | Daemon route | +| ----------------------------------- | ---------------------------------------------- | +| `ao project add` | `POST /api/v1/projects` | +| `ao project ls` | `GET /api/v1/projects` | +| `ao project get ` | `GET /api/v1/projects/{id}` | +| `ao project set-config ` | `PUT /api/v1/projects/{id}/config` | +| `ao project rm ` | `DELETE /api/v1/projects/{id}` | +| `ao spawn` | `POST /api/v1/sessions` | +| `ao session ls` | `GET /api/v1/sessions` | +| `ao session get ` | `GET /api/v1/sessions/{id}` | +| `ao session kill ` | `POST /api/v1/sessions/{id}/kill` | +| `ao session restore ` | `POST /api/v1/sessions/{id}/restore` | +| `ao session rename ` | `PATCH /api/v1/sessions/{id}` | +| `ao session cleanup` | `POST /api/v1/sessions/cleanup` | +| `ao session claim-pr ` | `POST /api/v1/sessions/{id}/pr/claim` | +| `ao orchestrator ls` | `GET /api/v1/orchestrators` | +| `ao send` | `POST /api/v1/sessions/{id}/send` | +| `ao hooks ` | `POST /api/v1/sessions/{id}/activity` (hidden) | + `go run .` in `backend/` remains a compatibility wrapper around the daemon. +PR and review actions (merge, resolve-comments, review execute/send) are +HTTP-only today and driven by the frontend; there are no `ao pr` / `ao review` +commands yet. + ## Configuration The CLI and daemon share the same environment-driven config: @@ -55,15 +83,13 @@ export AO_PORT=3037 rm -rf "$tmp" ``` -## Product commands not present yet +## Adding new commands -The backend has project, session, lifecycle, terminal, and CDC building blocks, -but the public CLI currently exposes only daemon-control commands. Add product -commands only when a daemon HTTP route owns the corresponding mutation/read: - -- `ao project ...` should call project HTTP routes. -- `ao spawn`, `ao session ...`, and `ao send` should call session/messaging HTTP routes. -- `ao events ...` should call CDC/event HTTP routes. +Add a product command only when a daemon HTTP route owns the corresponding +mutation/read; the CLI must call that route rather than reimplementing daemon +behavior. Commands not yet exposed but with backend routes in place include +`ao events ...` (over the CDC/SSE endpoint) and CLI parity for PR/review +actions. Do not port old in-process TypeScript CLI behavior that mixed command handling with storage and runtime implementation details. diff --git a/docs/status.md b/docs/status.md index 1da4946a3..70320e07b 100644 --- a/docs/status.md +++ b/docs/status.md @@ -1,31 +1,80 @@ # agent-orchestrator status -Current main contains the Go backend daemon, Cobra CLI foundation, SQLite store, -CDC poller/broadcaster, lifecycle/session services, terminal mux, project API -controller/manager work, runtime/workspace/tracker adapters, and CDC-backed event rows. +Current `main` ships a working single-user local loop: the Go daemon and the +Electron/React frontend both drive a live daemon over HTTP/SSE/WebSocket. The +core GitHub flow works end-to-end: add project → spawn session/orchestrator → +attach terminal → observe PR → merge. ## Build & test +The local gate is the backend Go build and race-enabled test suite: + ```bash -npm run lint +cd backend && go build ./... && go test -race ./... ``` -## Current shape +`npm run lint` (from the repo root) runs `go test ./...` plus golangci-lint. +Frontend checks live under `frontend/` (`npm run typecheck`, `npm run build`). +See [`AGENTS.md`](../AGENTS.md) for the regen workflow when touching the API +surface (`npm run sqlc`, `npm run api`). -- CLI: `ao start`, `status`, `stop`, `doctor`, `completion`, `version`, and the - hidden daemon entrypoint. -- Session facts: `activity_state` and `is_terminated`; display status is derived - from those plus PR facts. -- SQLite: migrations create projects, sessions, PR/check/comment, and `change_log` tables. -- CDC: DB triggers append to `change_log`; the poller broadcasts live events. -- Session Manager: internal spawn/kill/restore/send/cleanup over runtime, - workspace, agent, store, messenger, and lifecycle ports. -- Service package: controller-facing session boundary that delegates commands to - the manager and assembles list/get/spawn/restore read models with display status. - Daemon HTTP routes for session commands are not wired yet. +## Shipped -## Next integration work +### Backend (Go daemon) -- Wire production agent adapters. -- Finish project/session HTTP routes and CLI product commands. -- Add SSE/event read endpoints over the CDC log. +- Loopback-only HTTP daemon (chi router, CORS, per-request timeout, + `/healthz` / `/readyz` / `/shutdown`). +- SQLite store with goose migrations and sqlc-generated queries; DB + trigger-based change-data-capture into `change_log`. +- CDC poller + broadcaster feeding in-process subscribers and the SSE stream + at `GET /api/v1/events` (with `Last-Event-ID` replay). +- Full session lifecycle over HTTP: list, get, spawn, kill, restore, rename, + rollback, cleanup, send, activity, PR claim/list. Orchestrator routes + (list/spawn/get) are wired too. +- Project CRUD plus per-project config (`PUT /projects/{id}/config`). +- PR action engine wired into the API: `POST /prs/{id}/merge` and + `/prs/{id}/resolve-comments`. +- Review routes registered: `GET /reviews`, `POST /reviews/execute`, + `POST /reviews/{id}/send`. +- SCM observer (`internal/observe/scm`) wired into the daemon: GitHub provider, + lazy/non-blocking auth, per-PR polling with ETag guards and semantic diffing, + feeding PR facts into lifecycle, which sends agent nudges for CI failures, + review feedback, and merge conflicts. +- Terminal mux over WebSocket (`/mux`): per-client `zellij attach` PTY. +- Lifecycle reducer plus reaper (`internal/observe/reaper`). +- Agent adapter platform under `internal/adapters/agent/` (20+ adapters) with a + registry and `ao hooks` activity dispatch. +- OpenAPI spec generated from Go DTOs; frontend TS types generated from it and + drift-checked in CI. + +### Frontend (Electron + React) + +- Electron + React 19 + TanStack Router/Query + Tailwind + shadcn primitives. +- Real daemon wiring via the generated `openapi-fetch` typed client + (`src/api/schema.ts`); mock data only in `VITE_NO_ELECTRON` web-preview mode. +- Electron main handles daemon discovery, launch, and status reporting. +- Shell: sidebar (projects + sessions, add/remove project), sessions board, + session view + inspector, project settings, pull-requests page, + spawn-orchestrator flow. +- Terminal pane (xterm) over the mux WebSocket, with a live SSE events + connection and port-rebind on daemon restart. + +## In flight / not yet a runtime feature + +- **Tracker lane**: GitHub tracker adapter exists, but there is no daemon + observer loop or agent-lifecycle→issue mirroring yet, so the tracker does + nothing at runtime ([#112](https://github.com/aoagents/agent-orchestrator/issues/112)). +- **Notifications**: design/in-flight only; no shipped backend notifier or UI + center. +- **Live PR/tracker fact surfacing**: the observer writes facts, but exposing + the full `pr_*` / `tracker_*` CDC events to live consumers + ([#110](https://github.com/aoagents/agent-orchestrator/issues/110)) and in + `ao session get` ([#111](https://github.com/aoagents/agent-orchestrator/issues/111)) + is still open. +- **CLI parity for PR/review actions**: merge, resolve-comments, and review are + HTTP-only (frontend-driven); there are no `ao pr` / `ao review` commands. + +Tracking milestone: +[`rewrite`](https://github.com/aoagents/agent-orchestrator/milestone/1). + +