130 lines
7.7 KiB
Markdown
130 lines
7.7 KiB
Markdown
# Design: typed per-project configuration
|
|
|
|
Status: **partially implemented** — `ProjectConfig` is typed, validated,
|
|
persisted (one `projects.config` JSON column), and surfaced via
|
|
`ao project set-config` + `PUT /projects/{id}/config`. The struct deliberately
|
|
carries only fields with a live consumer: `defaultBranch`, `env`, `symlinks`,
|
|
`postCreate`, `agentConfig`, and the `worker`/`orchestrator` role overrides are
|
|
wired at spawn; `sessionPrefix` feeds the display prefix. Settings whose
|
|
consumers do not yet exist — per-project `tracker`/`scm` config and prompt
|
|
`rules` — are intentionally **not** modeled yet and land in focused follow-up
|
|
PRs alongside the code that reads them (see "Sequencing" below). Cross-agent
|
|
`agentConfig.model`/`permissions` support is tracked in #157.
|
|
|
|
## Goal
|
|
|
|
Every per-project setting the legacy `agent-orchestrator.yaml` carried under
|
|
`projects:` should live as **typed, validated state** in SQLite, reachable
|
|
through exactly two entry points:
|
|
|
|
1. **CLI** — `ao project ...` (thin client → daemon HTTP)
|
|
2. **UI** — the dashboard project settings form
|
|
|
|
There is no YAML loader in the Go rewrite, so this is not about parsing a file —
|
|
it is about giving each former YAML field a typed home, a validation owner, and a
|
|
CLI/API/UI surface. No setting should be a free-form `map[string]any`.
|
|
|
|
## Principle: typed over map
|
|
|
|
The legacy `agentConfig` was an open `map` (`.passthrough()`), which is why early
|
|
storage modeled it as `map[string]any`. That defers validation to spawn time and
|
|
forces the UI to render raw JSON. We instead model each setting as a **typed Go
|
|
struct** with a `Validate()` method, so:
|
|
|
|
- bad values are rejected when **set** (CLI/API), not silently dropped at spawn;
|
|
- the OpenAPI spec and frontend TS types are generated with real fields;
|
|
- the UI renders a typed form instead of a JSON textarea.
|
|
|
|
Adapter-specific keys, if ever needed, become typed fields owned by `domain`
|
|
rather than an escape-hatch map.
|
|
|
|
## Field catalog (legacy `projects.<id>`) and target home
|
|
|
|
| YAML field | Type | Storage today | Target |
|
|
| --------------------------------- | ---------------------- | ----------------------------------- | ---------------------------------------------------- |
|
|
| `name` | string | `projects.display_name` | done |
|
|
| `repo` | string | `projects.repo_origin_url` | done |
|
|
| `path` | string | `projects.path` | done |
|
|
| `defaultBranch` | string | hardcoded `"main"` | `projects.default_branch` |
|
|
| `sessionPrefix` | string | derived | `projects.session_prefix` |
|
|
| `agentConfig` | `{model, permissions}` | **`projects.agent_config` (typed)** | **done (this PR)** |
|
|
| `orchestrator`/`worker` overrides | `{agent, agentConfig}` | — | typed role-override columns/blob |
|
|
| `env` | `map[string]string` | — | `project_env` table (key/value rows) |
|
|
| `symlinks` | `[]string` | — | `projects.symlinks` (JSON) |
|
|
| `postCreate` | `[]string` | — | `projects.post_create` (JSON) |
|
|
| `agentRules` / `agentRulesFile` | string | partial (`SpawnConfig.AgentRules`) | `projects.agent_rules*` |
|
|
| `orchestratorRules` | string | — | `projects.orchestrator_rules` |
|
|
| `tracker` | `{plugin, …}` | DTO stub only | `projects.tracker` (typed blob) + adapter validation |
|
|
| `scm` | `{plugin, webhook{…}}` | DTO stub only | `projects.scm` (typed blob) + adapter validation |
|
|
| `opencodeIssueSessionStrategy` | enum | — | `projects.opencode_session_strategy` |
|
|
| `reactions` | per-project overrides | — | `project_reactions` (own slice) |
|
|
|
|
## Typed model
|
|
|
|
```go
|
|
// domain
|
|
type AgentConfig struct { // implemented
|
|
Model string `json:"model,omitempty"`
|
|
Permissions PermissionMode `json:"permissions,omitempty"`
|
|
}
|
|
func (c AgentConfig) Validate() error { ... }
|
|
|
|
// implemented today — only fields with a live consumer are modeled
|
|
type ProjectConfig struct {
|
|
DefaultBranch string
|
|
SessionPrefix string
|
|
AgentConfig AgentConfig
|
|
Worker RoleOverride // {Harness, AgentConfig}
|
|
Orchestrator RoleOverride
|
|
Env map[string]string
|
|
Symlinks []string
|
|
PostCreate []string
|
|
// future slices add fields here as their consumers land:
|
|
// AgentRules / AgentRulesFile / OrchestratorRules (prompt rules)
|
|
// Tracker TrackerConfig // adapter-validated
|
|
// SCM SCMConfig // adapter-validated
|
|
}
|
|
```
|
|
|
|
Each leaf type owns a `Validate()`. Plugin-shaped settings (`tracker`, `scm`)
|
|
delegate to the selected adapter, mirroring how `agentConfig` is consumed by the
|
|
agent adapter.
|
|
|
|
## Storage strategy
|
|
|
|
- **Scalar fields** (`default_branch`, `session_prefix`, `agent_rules`, enums) →
|
|
their own typed columns on `projects`.
|
|
- **Small structured blobs** (`agent_config`, `tracker`, `scm`, `symlinks`,
|
|
`post_create`) → nullable JSON columns, marshaled/unmarshaled in the store
|
|
(the pattern this PR established for `agent_config`).
|
|
- **Unbounded key/value sets** (`env`) → a child table keyed by `project_id`.
|
|
- **Its own domain** (`reactions`) → a separate slice; reactions already have a
|
|
reaction engine to integrate with.
|
|
|
|
## Surface (per field)
|
|
|
|
- **API** — extend the projects controller. Field groups get focused routes
|
|
(e.g. `PUT /projects/{id}/agent-config`, `PUT /projects/{id}/env`) rather than
|
|
one mega-PUT, so partial updates are clean and the OpenAPI stays legible.
|
|
- **CLI** — typed flags on `ao project` subcommands (e.g.
|
|
`ao project set-config --model --permission`, `ao project env set KEY=VAL`).
|
|
- **UI** — a generated typed form per group, driven by the OpenAPI schema.
|
|
|
|
## Sequencing (one slice per PR)
|
|
|
|
1. **agentConfig (typed)** — _this PR_. Establishes the typed+validated+surfaced
|
|
pattern end to end.
|
|
2. **Project identity scalars** — `default_branch`, `session_prefix` (stop
|
|
hardcoding/deriving them).
|
|
3. **Workspace provisioning** — `env`, `symlinks`, `postCreate` (these change
|
|
spawn/workspace wiring, so grouped).
|
|
4. **Rules** — `agentRules`, `agentRulesFile`, `orchestratorRules` (consolidate
|
|
the partial `SpawnConfig.AgentRules` path).
|
|
5. **Role overrides** — `worker` / `orchestrator` `{agent, agentConfig}`.
|
|
6. **Tracker / SCM per-project** — typed blobs with adapter-owned validation.
|
|
7. **Per-project reactions** — integrate with the reaction engine.
|
|
|
|
Each slice is independently shippable and follows the same shape: domain type +
|
|
`Validate()` → storage (column or blob or table) → service set/get → API route →
|
|
CLI flags → UI form → tests.
|