The best way to control Claude Code, Codex and more from any computer or phone

main
md 177 lines 12.7 KB
Rendered Raw
1 # Provider constraints
2
3 Orchestration records intent and state without knowing which provider runs a thread. Provider
4 protocols, account ownership, permissions, and capabilities belong at the
5 [adapter boundary](../../packages/provider-core/src/server/ProviderAdapter.ts). Normalize there
6 instead of spreading provider checks through orchestration and clients.
7
8 A driver kind identifies an integration; an instance identifies one configuration and account
9 lifecycle. Route work by instance, so two accounts using the same driver do not share mutable
10 session or catalog state. For a new driver, start with [adding a provider](./adding-a-provider.md).
11
12 ## Process and account isolation
13
14 The `opencode` driver probes the installed version and runs the 1.x or 2.x runtime. OpenCode's MCP
15 registrations are directory-scoped, while T3's MCP connection is thread-scoped, so threads in one
16 directory must not share one T3 MCP entry.
17
18 - **1.x** uses one T3-managed chat server per thread, so threads cannot replace each other's
19 connection. Catalog and text-generation work can share the
20 [instance-owned helper](../../packages/provider-opencode/src/server/OpenCodeServerOwner.ts), which closes
21 after an idle period. See the [1.x adapter](../../packages/provider-opencode/src/server/adapter.ts).
22 - **2.x** serves every directory from one
23 [server per instance](../../packages/provider-opencode/src/server/v2/OpenCode2Server.ts). Each thread
24 registers its own `t3-code-<thread>` MCP entry, and session permission rules deny every other
25 thread's entry. See the [2.x adapter](../../packages/provider-opencode/src/server/v2/adapter.ts).
26
27 External OpenCode servers remain externally owned and can require an external restart to pick up
28 configuration changes. OpenCode stores "always" approval grants for the whole project. Automatic
29 full-access replies use `once` so they cannot widen a supervised thread's permissions on a shared
30 server. On 2.x, a session-wide approval also replies `once` and becomes T3's own rule on that session.
31
32 Pi runs the user's own `pi` install in RPC mode and owns native extension, package, and project
33 trust discovery. T3 injects only its namespaced MCP bridge, so a Pi session behaves as it does in
34 the Pi TUI. Pi session files back native resume, rollback, and same-instance thread forks.
35 Forks use Pi's CLI in the destination directory because RPC session switching retains the source
36 session's cwd. Provider switches still use portable handoff summaries.
37 See the [adapter](../../packages/provider-pi/src/server/adapter.ts).
38
39 Antigravity separates account profiles per instance while sharing installed executables across the
40 environment. The 1.5 CLI keeps every profile's sign-in in one OS keyring entry and ignores
41 `AGY_ACP_FORCE_FILE_STORAGE`; only its SSH-session check stores the sign-in in the profile, so Google
42 account instances launch with `SSH_CONNECTION` set and sign in with `--login`. Gemini Enterprise
43 has no such sign-in and still shares the keyring entry. The launch environment removes ambient Google credentials,
44 so an instance cannot silently use another account or billing project. The agent also resolves
45 its user-global skill directories under that profile, so the profile links those two directories
46 back to the user's real `~/.gemini`; MCP servers, hooks, and rules there stay out of the profile.
47 See [profile isolation](../../apps/server/src/provider/antigravityAuthSupport.ts).
48
49 The [Antigravity installer](../../apps/server/src/provider/AntigravityInstallation.ts) outlives
50 client connections and provider-instance rebuilds. Releases are immutable, with an atomic pointer
51 selecting the version for new processes. Running processes hold leases on their version. Updates
52 and removal must respect those leases instead of replacing executables under a running agent.
53
54 ## Setup must not happen as a health-check side effect
55
56 Opening a provider session can start MCP servers, run hooks, or launch a login browser.
57 [Grok probes](../../packages/provider-grok/src/server/status.ts) avoid authentication and
58 session creation for this reason. Antigravity likewise reserves authenticated catalog sessions for
59 explicit setup or model refresh; background checks use initialization only.
60
61 [Antigravity sign-in](../../apps/server/src/provider/AntigravityAuth.ts) belongs to the initiating
62 T3 auth session. The client carries the return URL back to the environment because the provider's
63 loopback listener may be on another machine. Forward only the callback for the owned pending flow;
64 a successful callback HTTP request is not proof that provider authentication finished. The native
65 process owns token exchange and storage.
66
67 Managed ChatGPT sign-in for a remote environment can finish on a local primary. The
68 [primary handoff](../../apps/server/src/provider/CodexChatGptHandoff.ts) uses an ephemeral
69 credential store and the destination's environment ID. It exchanges and verifies the code before
70 transferring the issued client registration and tokens. Only the destination persists and refreshes
71 that session; retaining a primary refresh session would race refresh-token rotation. Without a local
72 primary, the client uses the remote callback completion flow.
73
74 Antigravity sign-out closes admission to new processes and stops existing processes before clearing account
75 metadata. Otherwise a helper or resumed session could retain the old account. Cached model lists
76 do not establish current access, and an authoritative empty catalog must clear the old list.
77
78 Antigravity text-generation helpers deny tool requests, but native hooks and MCP configuration can
79 run before the prompt. They reject profiles with such configuration before launch. Prompt
80 instructions and tool denial do not create a native sandbox.
81 See [helper constraints](../../apps/server/src/textGeneration/AntigravityTextGeneration.ts).
82
83 ## Provider updates run only through the owning installer
84
85 A package manager runs only when the resolved executable's path proves it owns the install. Homebrew
86 and npm are proven by the real path (symlinks followed): a versioned keg or cask under
87 `brew --prefix`, or `<prefix>/lib/node_modules/<pkg>/` (Windows: the shim beside `node_modules`).
88 Native installer layouts and the global directories of pnpm, Bun, Yarn, and Vite+ may match on
89 either the resolved path or its real target, since those installers place real files or their own
90 symlinks there. Volta is proven by the package's image directory plus either its `volta-shim` link
91 or, on Windows, the exact cmd or bash forwarding script Volta generates; a custom script that merely
92 calls `volta run` does not qualify. When nothing is proven, Pi's and Grok's own updaters
93 (`pi update --self`, `grok update`) run instead, because each detects its installer itself; the
94 runner's version check catches an updater that exits 0 without updating. Claude, Codex, and OpenCode updaters only act on their own native layout, so
95 those providers stay manual-only unless that layout is proven. Mise is checked
96 first, since a `mise x` wrapper can sit at a native installer's path, and `MISE_DATA_DIR` can put
97 installs anywhere, so `mise which` is asked whenever mise is on `PATH`. Each driver names its fixed
98 mise tool; mise must resolve the binary and list it in an active install of that tool requested as
99 `latest`, which gets `mise upgrade <tool>`. T3 Code keeps launching the configured path, so that
100 path must be a shim or under the tool's `latest` link, which the upgrade repoints: a version
101 directory (including one `mise activate` put on `PATH`) would keep running the old binary until mise
102 prunes it. Everything else mise touches (fixed version paths, pinned tools, wrappers, OpenCode 1.x,
103 whose mise tool crosses into 2.x) stays manual-only, so T3 Code never edits mise config. Nix store installs stay manual-only too, since the store is read-only. `mise latest` supplies the version, because settings such as
104 `minimum_release_age` can hold mise behind npm. A Grok cask whose Homebrew prefix
105 cannot be verified also stays manual-only: `grok update` would install a second copy. npm updates pin `--prefix` because the
106 `npm` on `PATH` can belong to a different Node than the one that owns the provider. Homebrew
107 compares against `brew info` since casks trail npm by hours; native installs share npm's version
108 train, so the registry stays authoritative for them. A Chocolatey install of Claude stays
109 manual-only: its package directory is writable only by administrators, and `claude update` through
110 the shim installs a native copy elsewhere. The latest version comes from `choco search`, and the
111 card shows `choco upgrade claude-code` without running it.
112 See the [resolver](../../apps/server/src/provider/providerMaintenanceRunner.ts).
113
114 Ownership is cached per instance and re-read immediately before an update runs. The
115 [runner](../../apps/server/src/provider/providerMaintenanceRunner.ts) refuses when the lock key
116 changed since the advisory, and reports success only when the refreshed provider is still installed
117 with a readable, current version.
118
119 ## Protocol traps
120
121 Codex async questions arrive as notifications and are answered with a new user message. There is
122 no pending RPC response to send. The
123 [adapter](../../apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts) persists them as
124 `user_input_request` turn items and runtime requests with `responseCapability: { type: "message" }`.
125 Their execution nodes do not block the run. Web, desktop, and mobile use their normal question
126 panels, and requests remain pending after a turn finishes, a provider exits, or the server restarts.
127
128 `runtime-request.respond` reads the persisted request and question item, validates required
129 answers, and commits the resolution and a user message in one transaction. Repeating the same
130 command returns its receipt without posting the answer twice. The normal message path starts or
131 resumes a run, queues behind active work, or steers when the adapter supports it. Blocking questions
132 retain the provider's live response path. Do not infer that a request has disappeared merely because
133 it is outside the recent history window.
134
135 Native `/goal` state belongs to the provider and is mirrored on the provider thread. Codex starts
136 the next goal turn on its own milliseconds after the last one completes, so the
137 [adapter](../../apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts) keeps the run open
138 and adds that turn to it. One run can therefore own several native turns. `/goal` commands that
139 start no Codex turn settle on a provider turn without a native ref, which native rollback must
140 not count. Claude's SDK mode emits no goal events; its adapter reads goal state from the
141 synthetic command output and Stop hook feedback in the transcript.
142
143 Capabilities must describe what the provider can actually do. Antigravity can capture workspace
144 checkpoints but cannot roll back its conversation. The [checkpoint boundary](./overview.md#turn-completion-and-checkpoints)
145 therefore rejects revert before touching files. Native permission and question option IDs must
146 also survive normalization; a display label is not necessarily a valid reply.
147
148 ## Attachments and stored history
149
150 Attachments live outside the project workspace. The
151 [attachment boundary](../../apps/server/src/orchestration-v2/AttachmentClaims.ts) validates and claims
152 uploads for a thread; adapters choose native input formats for those environment-local files.
153 A path in the prompt does not grant filesystem access. Keep provider sandbox and approval rules
154 in force; copying uploads into the project to bypass them changes that boundary.
155
156 File attachments introduced a replay compatibility limit. Image-only clients cannot decode
157 file-bearing messages, and an image-only server can fail the entire environment's startup when
158 replaying one such event. Rollouts and downgrades must account for persisted history as well as
159 current client support.
160
161 ## Provider diagnostics
162
163 Native event logs retain lifecycle events, responses, and failures. Token deltas and duplicate raw
164 frames are filtered before adapters copy or redact payloads. The filter accepts both legacy native
165 events and v2 protocol envelopes; decode failures remain visible through diagnostic frames.
166
167 Log payloads have a 64 KiB encoded budget. Large or deeply nested payloads become structural
168 summaries that retain routing identifiers, methods, status, and error fields. Traversal is bounded
169 before redaction and serialization, so logging a large response does not require several full
170 copies. These limits apply to diagnostics; provider event handling is unchanged.
171
172 Codex resumes with metadata-only reads when it needs a thread's identity and update time. Its
173 initialization capabilities opt out of `turn/diff/updated`: T3 derives diffs from checkpoints.
174 The logger filters those notifications before traversal when an older provider still sends them.
175
176 Model classification has its own [manifest constraints](./model-manifest.md). Assistant-reference
177 handling is documented under [citations](./assistant-citations.md).