Skip to content

Commit ef6822c

Browse files
docs(internals): add a checklist for adding a provider
The rules for a new V2 provider were spread across providers.md, the capability and testing docs, and review comments, so a new driver could pass review without replay fixtures or with an imitated permission mode. This page collects them: choosing the integration shape, reporting only what the provider does, process and account boundaries, replay-backed tests, and where a driver plugs in. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 9a3070b commit ef6822c

3 files changed

Lines changed: 85 additions & 1 deletion

File tree

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ source alone does not explain. Most code changes do not need an internal documen
3838
- [Glossary](./internals/glossary.md)
3939
- [Connection runtime](./internals/connection-runtime.md)
4040
- [Providers](./internals/providers.md)
41+
- [Adding a provider](./internals/adding-a-provider.md)
4142
- [Pull request file revisions](./internals/pull-request-file-revisions.md)
4243
- [Model classification](./internals/model-manifest.md)
4344
- [Remote environments](./internals/remote.md)
Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Adding a provider
2+
3+
A provider integration is judged by whether every T3 feature behaves honestly on it, not by
4+
whether a turn runs. This page lists the decisions and evidence a new driver needs. The
5+
[provider constraints](./providers.md) and the
6+
[capability system](../orchestration-v2/provider-capability-system.md) explain why these rules exist.
7+
8+
## Choose the integration shape
9+
10+
- **ACP agents** start as [ACP Registry](../user/providers-acp.md) entries, which follow the ACP
11+
spec with no per-agent handling. An agent gets a dedicated driver only when it needs behavior the
12+
spec does not cover, and then it is a small flavor over the
13+
[shared ACP adapter](../../apps/server/src/orchestration-v2/Adapters/AcpAdapterV2.ts), like Grok
14+
and Antigravity. Never add agent-id checks to the generic registry adapter.
15+
- **Other protocols** get a native adapter that implements
16+
[`ProviderAdapterV2`](../../apps/server/src/orchestration-v2/ProviderAdapter.ts), like Codex,
17+
Claude, Cursor, OpenCode, Pi, and Muse.
18+
19+
Provider-specific behavior stays in the adapter and driver. Orchestration and clients read
20+
capabilities, never the driver kind.
21+
22+
## Report only what the provider does
23+
24+
- **Capabilities.** Set every flag in `OrchestrationV2ProviderCapabilities` to what the provider
25+
really does. Turn off fork, rollback, steering, or subagent support it lacks; orchestration then
26+
falls back, for example to portable context handoff for forks. A capability left on that fails
27+
at runtime is a bug.
28+
- **Permission modes.** Offer only modes the provider enforces natively, through
29+
`supportedRuntimeModes` in the provider presentation ([Grok](../../apps/server/src/provider/GrokProvider.ts)
30+
and [Pi](../../apps/server/src/provider/PiProvider.ts) are examples). Do not imitate a missing
31+
mode by answering approvals in T3: T3's check is weaker than the agent's own enforcement. The
32+
server runs an unoffered stored mode as Supervised
33+
([`RuntimePolicy.ts`](../../apps/server/src/orchestration-v2/RuntimePolicy.ts)).
34+
- **Approval and question options.** Pass the provider's own option IDs through unchanged. Every
35+
request needs a way to decline that the provider honors.
36+
- **Interaction modes.** Hide the plan toggle (`showInteractionModeToggle: false`) unless the
37+
provider's plan output becomes T3's proposed-plan card.
38+
39+
## Process, account, and setup boundaries
40+
41+
- **Instances.** Session state, catalogs, and credentials belong to a provider instance, not the
42+
driver. Remove ambient credentials the instance did not configure, so two instances cannot
43+
silently share an account or billing.
44+
- **Status checks.** Background status and model refreshes must not open a session that can start
45+
MCP servers, run hooks, or launch a login. Keep heavier probes behind an explicit refresh.
46+
- **T3 MCP tools.** Inject the thread's MCP server so agents can use T3's tools, and make a turn
47+
survive when that server is unreachable.
48+
- **Updates.** Run an update only through the installer that provably owns the binary; otherwise
49+
leave it manual. See [`providerMaintenance.ts`](../../apps/server/src/provider/providerMaintenance.ts).
50+
51+
## Tests
52+
53+
Prove adapter behavior with replay fixtures: a provider transcript replayed through the real
54+
orchestrator, adapter, and projections. See the [testing strategy](../orchestration-v2/testing-strategy.md).
55+
56+
- Record transcripts from the real provider with a recorder script in
57+
[`apps/server/scripts`](../../apps/server/scripts) (`record-*-replay-fixture.ts`). A new protocol
58+
usually needs its own recorder.
59+
- Cover the shared scenarios under
60+
[`testkit/fixtures`](../../apps/server/src/orchestration-v2/testkit/fixtures) that the provider
61+
supports: `simple`, `multi_turn`, `queued_turn`, `turn_interrupt`, `message_steering`,
62+
`provider_thread_resume`, and the `tool_call_*` approval cases. Add provider-specific fixtures
63+
for behavior the shared ones do not reach.
64+
- Unit tests are for pure logic and for failures a real provider cannot produce on demand. A test
65+
that drives the adapter with hand-written frames is a guess about the protocol; live testing
66+
regularly finds what those guesses missed.
67+
- A gated live test against the real binary is welcome, but it does not replace replays, because
68+
CI skips it.
69+
70+
## Where a driver plugs in
71+
72+
- **Contracts:** settings schema and patch, default model, and display name in
73+
[`packages/contracts`](../../packages/contracts/src). New providers are off by default.
74+
- **Server:** the driver in [`provider/Drivers`](../../apps/server/src/provider/Drivers) and its entry
75+
in [`builtInDrivers.ts`](../../apps/server/src/provider/builtInDrivers.ts). Also its position in
76+
the [status order](../../apps/server/src/provider/providerStatusCache.ts), a compatibility policy
77+
in [`model-manifest.json`](../../apps/server/src/provider/model-manifest.json) (bump `updatedAt`;
78+
see [model manifest](./model-manifest.md)), and text generation for titles and commit messages.
79+
- **Clients:** web settings metadata and badge, provider icons on web and mobile, and settings
80+
search terms.
81+
- **Docs:** a `docs/user/providers-<name>.md` guide in the product's voice, a row in the
82+
[install](../user/install.md#providers) table, and any provider difference that changes the
83+
[permission modes](../user/permission-modes.md) page.

‎docs/internals/providers.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ instead of spreading provider checks through orchestration and clients.
77

88
A driver kind identifies an integration; an instance identifies one configuration and account
99
lifecycle. Route work by instance, so two accounts using the same driver do not share mutable
10-
session or catalog state.
10+
session or catalog state. For a new driver, start with [adding a provider](./adding-a-provider.md).
1111

1212
## Process and account isolation
1313

0 commit comments

Comments
 (0)