bkinnightskytw
/
agent-orchestrator
mirror of https://github.com/ComposioHQ/agent-orchestrator.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 <noreply@anthropic.com>

* chore: format with prettier [skip ci]
This commit is contained in:
Harshit Singh Bhandari 2026-06-14 18:42:18 +05:30 committed by GitHub
parent c4961019d0
commit 7da911711f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
7 changed files with 144 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
AGENTS.md
View File

@ -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`.

15
README.md
View File

@ -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 <id>` | Fetch one project. |
| Project | `ao project set-config <id>` | Update per-project config. |
| Project | `ao project rm <id>` | 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.

3
docs/README.md
View File

@ -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

31
docs/architecture.md
View File

@ -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

5
docs/backend-code-structure.md
View File

@ -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

50
docs/cli/README.md
View File

@ -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 <command>
--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 <shell>` | 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 <id>` | `GET /api/v1/projects/{id}` |
| `ao project set-config <id>` | `PUT /api/v1/projects/{id}/config` |
| `ao project rm <id>` | `DELETE /api/v1/projects/{id}` |
| `ao spawn` | `POST /api/v1/sessions` |
| `ao session ls` | `GET /api/v1/sessions` |
| `ao session get <id>` | `GET /api/v1/sessions/{id}` |
| `ao session kill <id>` | `POST /api/v1/sessions/{id}/kill` |
| `ao session restore <id>` | `POST /api/v1/sessions/{id}/restore` |
| `ao session rename <id> <name>` | `PATCH /api/v1/sessions/{id}` |
| `ao session cleanup` | `POST /api/v1/sessions/cleanup` |
| `ao session claim-pr <id> <pr-ref>` | `POST /api/v1/sessions/{id}/pr/claim` |
| `ao orchestrator ls` | `GET /api/v1/orchestrators` |
| `ao send` | `POST /api/v1/sessions/{id}/send` |
| `ao hooks <agent> <event>` | `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.

89
docs/status.md
View File

@ -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).
</content>
</invoke>