[#6336] docs(services): Design asynchronous agent config refresh

[mmabrouk]

Context

An agent can commit a configuration revision while it is running, but the active runner continues with values resolved at run start. The earlier gateway-only refresh proposal solved one symptom and would have created a separate resolution path for each future live configuration facet.

This design PR is stacked on #6310 and tracks #6336. It defines contracts and implementation slices only; runtime implementation remains follow-up work.

Changes

The design replaces gateway-specific refresh with one private asynchronous path for the complete committed configuration.

Before:

commit -> gateway-specific stale flag -> gateway-specific pull

After:

commit -> private exact-revision event -> shared resolver -> full snapshot -> supported atomic facets

It pins committed and inline provenance, active-run targeting, ordering and supersession, per-facet desired and installed state, credential redaction, fail-closed tool updates, and lifecycle boundaries. Gateway execution is the first enabled facet. Its approval identity binds the shared tools generation, concrete toolkit version, provider-account binding, and canonical-action binding.

The related gateway and harness-reconciliation documents now point to the general design and use the same execution contracts.

Tests / notes

• git diff --check
• Rebased onto the latest feat/gateway-connection-rework, including toolkit-version pinning from fix(api,sdk,runner): pin Composio toolkit versions per run #6337.
• Ran repeated independent architecture and security consistency reviews until no blocking or high-severity findings remained.
• Documentation only; no runtime tests were required.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview	Aug 27, 2026 11:14pm

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

Review focus:

1. Confirm the private commit control record cannot enter model, session, trace, or public event surfaces.
2. Confirm the initial /run projection and asynchronous apply share one authoritative facet serializer.
3. Confirm per-facet state, supersession fencing, and lifecycle-deferred tools cannot report false convergence.
4. Confirm gateway approval and execution bind toolkit version, provider account, canonical action, and the currently installed composite generation.
5. Confirm trusted owner routing is treated as a rollout blocker for multi-replica HTTP deployments.