|
| 1 | +--- |
| 2 | +title: "58. Agent registration" |
| 3 | +status: Accepted |
| 4 | +relates_to: |
| 5 | + - agent-architecture |
| 6 | + - agent-infrastructure |
| 7 | +topics: |
| 8 | + - agents |
| 9 | + - per-repo |
| 10 | + - configuration |
| 11 | + - extensibility |
| 12 | +--- |
| 13 | + |
| 14 | +# 58. Agent registration |
| 15 | + |
| 16 | +Date: 2026-06-29 |
| 17 | + |
| 18 | +## Status |
| 19 | + |
| 20 | +Accepted |
| 21 | + |
| 22 | +## Context |
| 23 | + |
| 24 | +Which agents fullsend knows about is currently compiled into the binary. |
| 25 | +Scaffold-embedded harnesses (`internal/scaffold/fullsend-repo/harness/`) |
| 26 | +define the complete agent set, and `HarnessNames()` enumerates them |
| 27 | +from the embed. There is no mechanism for registering agents that live |
| 28 | +outside the scaffold — adding or extracting an agent requires a code |
| 29 | +change to the fullsend binary. |
| 30 | + |
| 31 | +The triage agent extraction to `fullsend-ai/agents` |
| 32 | +([ADR 0045](0045-forge-portable-harness-schema.md) Phase 4) is the |
| 33 | +first agent to move out of the scaffold. The registration mechanism |
| 34 | +must support both first-party extractions and user-defined agents |
| 35 | +without code changes. |
| 36 | + |
| 37 | +## Decision |
| 38 | + |
| 39 | +Make agent registration a **config-level concept**. Add an `agents` |
| 40 | +list to both `OrgConfig` and `PerRepoConfig`. (Note: ADR 0045 Phase 4 |
| 41 | +previously removed the `agents` block from `OrgConfig`; this re-adds |
| 42 | +a field with the same YAML key but different semantics — harness |
| 43 | +source URLs rather than role/name/slug identity tuples.) Each entry |
| 44 | +is a URL or local path, with an optional name override: |
| 45 | + |
| 46 | +```yaml |
| 47 | +agents: |
| 48 | + - https://raw.githubusercontent.com/fullsend-ai/agents/<sha>/harness/triage.yaml#sha256=<hash> |
| 49 | + - name: lint |
| 50 | + source: harness/my-linter.yaml |
| 51 | +``` |
| 52 | +
|
| 53 | +`fullsend run <name>` resolves agents from config at runtime, loading |
| 54 | +harnesses directly from URLs or local paths. No intermediate wrapper |
| 55 | +files are generated on disk — role and slug come from the harness |
| 56 | +content itself. Config entries merge additively with |
| 57 | +scaffold-discovered agents; collision is keyed by agent name (explicit |
| 58 | +`name` if set, otherwise derived from source filename) and resolved in |
| 59 | +favor of config, enabling gradual migration. Once all first-party agents are extracted, config |
| 60 | +becomes authoritative and the scaffold fallback is removed. |
| 61 | + |
| 62 | +A `fullsend agent` CLI subcommand (`add`, `list`, `update`, `remove`) |
| 63 | +manages entries (single-user CLI operations; no concurrency guard on |
| 64 | +config read/write) and auto-pins URLs to a commit SHA with an |
| 65 | +integrity hash. Per-repo config gains `allowed_remote_resources` so per-repo |
| 66 | +installs can validate base composition without an org config repo. |
| 67 | +Per-repo config is read from the **base branch**, not the PR branch, |
| 68 | +so a PR cannot inject an attacker-controlled `allowed_remote_resources` |
| 69 | +entry or agent source. |
| 70 | + |
| 71 | +See the [implementation plan](../plans/agent-registration.md) for |
| 72 | +phasing, schema details, CLI behavior, and migration mechanics. |
| 73 | + |
| 74 | +## Consequences |
| 75 | + |
| 76 | +- Anyone can add an agent to a fullsend installation via `fullsend agent add` — no code change required. |
| 77 | +- First-party and third-party agents follow the same registration path. |
| 78 | +- The additive merge model allows agents to be extracted from the scaffold one at a time without disrupting existing installations. |
| 79 | +- Per-repo installs no longer need org config for remote resource validation. |
| 80 | +- No forced migration — empty config falls back to scaffold discovery until populated. |
| 81 | +- The `agents` YAML key was previously used in `OrgConfig` with a different schema (role/name/slug identity tuples, removed by ADR 0045 Phase 4). The new schema (URL/path source entries) is incompatible; a custom unmarshaler detects and rejects old-format entries with a clear error message. |
| 82 | + |
| 83 | +## References |
| 84 | + |
| 85 | +- [ADR 0033](0033-per-repo-installation-mode.md) -- per-repo installation mode |
| 86 | +- [ADR 0038](0038-universal-harness-access.md) -- URL-based resource references and integrity hashes |
| 87 | +- [ADR 0045](0045-forge-portable-harness-schema.md) -- harness composition via `base:` URLs |
| 88 | +- [ADR 0057](0057-repos-management.md) -- repos management for per-repo installations |
| 89 | +- [Implementation plan](../plans/agent-registration.md) |
0 commit comments