Skip to content

Latest commit

 

History

History
320 lines (233 loc) · 11.6 KB

development.md

File metadata and controls

320 lines (233 loc) · 11.6 KB

Development guide

How to set up, build, run, and test Agent Orchestrator locally.

Prerequisites

Tool Minimum version Notes
Go 1.27.4 go version to check; install via go.dev
Node.js 24 node --version; install via nodejs.org
npm 10 Ships with Node.js
Nix (opt.) - nix develop drops you into a shell with all deps; see ../flake.nix

Additional runtime dependencies for the daemon:

  • git (for worktree creation and agent integration)
  • A running agent CLI (Claude Code, Codex, Aider, etc.). See the installation guide.

For source terminal runs on macOS, install/configure tmux; packaged builds bundle it. New macOS/Linux sessions use detached native PTY hosts, while old handles and host-start fallback use tmux. ao doctor still checks tmux on both.

Project layout

agent-orchestrator/
  backend/              # Go daemon (Cobra CLI, HTTP API, services, storage)
    cmd/ao/             # CLI entry point
    internal/           # All library code
      cli/              # CLI command implementations
      httpd/            # HTTP controllers, apispec, middleware
      service/          # Business logic layer
      domain/           # Domain types
      ports/            # Port interfaces (contracts)
      storage/          # SQLite migrations, queries, generated code
  frontend/             # Electron + React desktop app
    src/                # Renderer, main, preload
    e2e/                # Playwright end-to-end tests
  packages/
    mobile/             # React Native (Expo) mobile companion app
    ao/                 # Legacy npm CLI package (frozen)
  docs/                 # Architecture, ADRs, CLI docs, status
  CONTRIBUTING.md       # Contribution guide

Getting the code

git clone https://github.com/Untrivial-ai/agent-orchestrator.git
cd agent-orchestrator
npm ci

Branching

git checkout -b ao/my-feature-branch origin/main

Keep your branch up to date by rebasing on main:

git fetch origin
git rebase origin/main

Committing

Keep commits atomic. Use one logical change per commit. Stage related changes and commit with a conventional message:

git add <files>

Commit message tags:

Tag When to use
feat New feature
fix Bug fix
docs Documentation only
test Adding or fixing tests
refactor Code change with no functional change
chore Maintenance, tooling, dependencies

Use trailers to provide additional context:

git commit -m "fix: handle nil pointer in session lookup

The session resolver panicked when the store returned a nil session
without an error. Return ErrNotFound instead.

Signed-off-by: Your Name <your.email@example.com>
Co-authored-by: Contributor Name <contributor@example.com>"

Backend

Build

cd backend
go build ./...

Run the daemon

cd backend
# Start the daemon (loopback HTTP server on 127.0.0.1)
go run ./cmd/ao daemon

The CLI is built with Cobra. From backend/, run go run ./cmd/ao --help for available commands.

Run tests

cd backend
go test ./...              # all tests
go test -race ./...        # with race detection
go test -v ./internal/cli/ # a specific package

Lint

npm run lint

Code generation

Create new SQLite migrations from the repository root:

npm run migration:create -- add_reports

The command creates a Goose SQL template with a UTC YYYYMMDDHHMMSSsss ID. Fill in its SQL and append the generated ID and filename to shippedMigrations in backend/internal/storage/sqlite/migrate_burned_versions_test.go. Keep existing migration IDs, filenames, and SQL unchanged.

# Regenerate sqlc code after editing queries or schema
npm run sqlc

# Regenerate OpenAPI spec and frontend TypeScript types
npm run api

Frontend

Install dependencies

cd frontend
npm install

Run in development mode

cd frontend
npm run dev            # Electron dev mode
npm run dev:web        # Web-only (no Electron, for quick UI iteration)

Build

cd frontend
npm run package        # Package for current platform
npm run make           # Create distributables when platform packaging deps are installed

On a fresh Linux machine, treat npm run package as the default local build path. npm run make also needs Linux packaging tools that are not provided by a minimal setup or by nix develop today:

  • rpm / rpmbuild for the RPM target
  • the usual distro packaging toolchain required by Electron Forge makers

CI installs rpm explicitly before running npm run make. Do the same locally if you need Linux distributables, or skip npm run make on a fresh setup.

Run tests

cd frontend
npm run test           # Vitest unit tests in a simulated renderer environment
npm run test:e2e       # Playwright browser-based renderer E2E tests
npx playwright show-report  # View Playwright report

Typecheck

cd frontend
npm run typecheck

Or from repo root:

npm run frontend:typecheck

Mobile companion app

The mobile companion app is still being wired into the contributor docs. Do not assume packages/mobile/README.md is a complete setup guide on this branch. Until a tracked guide lands, use the desktop/backend workflow above and check open issues/PRs for current mobile-specific setup notes.

Running end-to-end

  1. Start the desktop app with npm run dev from frontend/.
  2. The Electron main process starts and supervises the loopback daemon for you.
  3. Use npm run dev:web only for renderer-only development; it does not launch Electron.

For CLI-only usage, open two terminals:

Terminal 1: start the daemon.

cd backend
go run ./cmd/ao daemon

Terminal 2: interact while the daemon is running.

cd backend
go run ./cmd/ao status
go run ./cmd/ao --help

Testing tips

Backend

  • Backend tests use httptest.Server and injected fakes. They do not require a real daemon.
  • Run the narrowest relevant test suite first (e.g. go test ./internal/cli/), then the full suite.

Frontend

  • Unit tests use Vitest and run in a simulated renderer environment.
  • E2E tests use Playwright against the web renderer started by npm run dev:web; they do not launch the full Electron app.
  • After changing API types, run npm run api from root to regenerate frontend/src/api/schema.ts.

Troubleshooting

Backend build / test failures

Symptom Likely cause Fix
go: go.mod requires go >= 1.27 Wrong Go version go version; install Go 1.27.4+ from go.dev
sqlc generate produces errors Query SQL syntax or schema migration issue Check backend/internal/storage/sqlite/queries/ for SQL syntax, placeholder counts, and referenced columns/tables; if you changed the schema, add a new migration in backend/internal/storage/sqlite/migrations/ instead of editing an existing one, then rerun npm run sqlc
openapi.yaml is stale Changed DTOs without regenerating Run npm run api from repo root
golangci-lint failures Linter version mismatch Install v2.14.0 or use npm run lint from root
Tests fail with "connection refused" Test tries real daemon Tests should use httptest; check for go test ./... without a live daemon

Frontend build / test failures

Symptom Likely cause Fix
npm run typecheck has type errors API types out of sync Run npm run api from repo root to regenerate
npm run dev fails on native modules Missing build tools Install Python + C++ build tools for node-gyp
npm install or npm ci fails Node.js version too old node --version; must be 24+ (see prerequisites above)
Blank window or crash on Linux Broken GPU driver stack Start with AO_DISABLE_GPU=1 to skip hardware acceleration

Code generation drift

If CI fails on the storage drift step of codegen-drift, run the pinned generator from the repository root and commit the generated storage changes together with their SQL/config source:

npm run sqlc
git diff --exit-code -- backend/internal/storage/sqlite/gen

The diff check should pass after committing the regenerated files. Do not edit gen/ by hand or use a different sqlc version; the version in package.json is authoritative. Review any unexpected query or generated type changes before committing. The storage tests also check that the config is valid YAML and keeps the boolean override for app_settings.cloud_offering.

If CI fails on the schema.ts drift step of codegen-drift, the OpenAPI-generated files are out of sync with source. Regenerate them locally and commit the updated files:

npm run api

If regeneration introduces unexpected diffs beyond your changes, check that your local tool versions match CI (Go 1.27.4+, Node 24, npm 10+).

OpenAPI spec and generated types

The API is defined in Go controller DTOs and operation registrations. Edit these source files, then regenerate:

npm run api

The generated artifacts are:

  • backend/internal/httpd/apispec/openapi.yaml
  • frontend/src/api/schema.ts

Both must be committed together with the Go changes. CI verifies they are in sync.