RFC: agent-context provider registry in buzz-acp (behavior-preserving; completes the registry-seam trio with #3167 / #3280)
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
**Motivation**
The ACP harness (`buzz-acp`) assembles an agent's `team_instructions` layer at startup by fetching one thing (the workspace Agent Guidelines doc) and folding it, inline, into the prompt. As Buzz leans further into agents as first-class participants, the number of things that legitimately want to contribute to an agent's standing context grows: workspace house-rules, per-team norms, channel-scoped policy, agent memory, and whatever future capabilities add (renderers/surfaces/bots-style extensions each may carry context). Today each new source means another hardcoded fetch-and-fold at the same site, in the harness's prompt-assembly path.
This is the same "central chokepoint" pattern the two companion proposals address on the relay (#3167, the kind registry) and the desktop client (#3280, the channel-feature registry). This is the third and smallest seam: the agent-context layer.
**Proposed solution**
Introduce a small `TeamContextProvider` trait and an ordered list the harness folds at startup, instead of a hardcoded single fetch:
- `TeamContextProvider::provide(ctx) -> Option` returns a provider's framed contribution (or `None`), where `ctx` carries what a provider needs (relay URL, keys).
- `build_team_instructions(providers, ctx, base)` runs the providers in order and joins their outputs with the base (persona/team) `team_instructions`.
- The existing Agent Guidelines fetch becomes one registered provider. Built-in context sources register through the same path, so it is behavior-preserving: the assembled `team_instructions` is identical to today's single-source fold (verifiable against the existing `house_rules_team_instructions` cases).
Object-safe async via the `Pin>` pattern already used by `buzz-workflow`'s `ActionSink`, so no new dependency (no `async-trait`).
The payoff: additional context sources become an ordered registration rather than another edit to the harness's prompt-assembly site, which matters as the agent surface grows.
**Alternatives considered**
- Keep folding each source inline (status quo) — every new context source keeps editing the same startup path, and ordering/precedence stays implicit.
- A config-only list of static strings — can't express sources that must be fetched or computed at startup (e.g. the relay-hosted guidelines doc).
**Additional context**
We have a complete working implementation, verified behavior-preserving against the existing `buzz-acp` tests (the assembled `team_instructions` matches the current fold across all guidelines/base combinations). It is the smallest of a coherent family of "registry seam" refactors we are proposing: relay event-kinds (#3167), desktop channel features (#3280), and this one for agent context. Each stands on its own and is behavior-preserving; together they make Buzz's extension points declarative instead of hand-wired. Happy to align on the trait surface and phasing before writing the PR.
Searched open issues and PRs for duplicates (agent context provider / team_instructions / agent guidelines): none found.
Contributor guide
Assessment
This issue has not been assessed yet.