fix(opencode): handle child approvals, stops, and model catalogs (#8480)

Theo Browne committed 2 months agov0.0.36-nightly.20260828.1213

Commit cb49e5d1 parent 0009aac42 files · +7983 −675Browse files

Showing the changes to docs (3 of 42 files). Show all

Unified · Split

3 files

docs/README.md +1 −1
docs/internals/providers.md +45 −0
docs/user/providers-opencode.md +53 −0

@@ -13,7 +13,7 @@ · 12 unmodified lines
13	13	- [Keeping app and server in sync](./user/updating.md)
14	14	- [Source control integrations](./user/source-control.md)
15	15	- [Background service (Linux)](./user/background-service.md)
16		−- Providers: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md)
	16	+- Providers: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md) · [OpenCode](./user/providers-opencode.md)
17	17
18	18	Mobile app: [apps/mobile/README.md](../apps/mobile/README.md)
19	19

docs/internals/providers.md+45−0

@@ -39,6 +39,50 @@ directory to route session and turn operations for a thread, so callers name a t · 38 unmodified lines
39	39	Adding a driver means writing the driver plus adapter and adding it to `BUILT_IN_DRIVERS`. No
40	40	orchestration, contract, or client change is required for the common case.
41	41
	42	+## OpenCode server ownership and catalog
	43	+
	44	+Each OpenCode provider instance owns one lazy local server for catalog discovery and
	45	+text-generation helpers through [`OpenCodeServerOwner.ts`][opencode-server-owner]. Concurrent
	46	+borrowers share startup. The server closes 30 seconds after the last borrower releases it, or
	47	+when the provider instance closes. A failed or exited process can be started again on the next
	48	+use. An externally configured OpenCode server remains externally owned.
	49	+
	50	+The local server and its SDK clients use one resolved password. An explicit provider password
	51	+overrides `OPENCODE_SERVER_PASSWORD` in the spawned environment. Without an explicit password,
	52	+the client uses the password from the environment that the process inherits. External servers use
	53	+only their explicit provider password and never inherit the host's local password.
	54	+
	55	+Every server connection must pass the authenticated `/global/health` check before inventory or
	56	+session operations start. The response must contain a valid version at or above 1.14.19. Local
	57	+owners cache this result for the lifetime of the spawned process. External actions check once when
	58	+they create their server connection, not for each model or SDK request.
	59	+
	60	+Chat adapters keep their own server per thread. They register a thread-specific `t3-code` MCP
	61	+connection, while OpenCode stores MCP connections by directory. Sharing these chat servers
	62	+without changing MCP routing would let two threads in one directory replace each other's
	63	+connection.
	64	+
	65	+OpenCode loads its catalog through the HTTP API when an enabled provider instance starts. The
	66	+provider registry keeps the snapshot in memory and persists it in the existing per-instance cache.
	67	+Each `subscribeServerConfig` connection refreshes all providers, so a client reconnect reloads the
	68	+OpenCode catalog from the current helper. The `serverRefreshProviders` request also refreshes it.
	69	+Periodic OpenCode probes remain disabled. OpenCode reads credentials for each inventory request,
	70	+but its native configuration files can remain cached for the lifetime of the helper process. The
	71	+helper closes 30 seconds after its last inventory or text-generation borrower releases it. A
	72	+refresh after that idle period starts a new helper and reads file changes. Repeated refreshes and
	73	+active text-generation work can extend process reuse. Changes to the provider configuration or
	74	+environment replace the instance and start a new discovery. Changes to unrelated settings only
	75	+update snapshot enrichment. Other providers retain their existing refresh policy.
	76	+
	77	+T3 Code does not own an external OpenCode process. Native configuration changes there can require
	78	+an external reload or restart before T3 Code's next refresh sees them.
	79	+
	80	+The shared server's idle shutdown does not clear the catalog. Failed discovery keeps the last
	81	+known models, slash commands, and skills through the registry's existing merge rules. A successful
	82	+empty inventory is authoritative. Existing threads keep their explicit model identifier and
	83	+options when catalog metadata is missing; the catalog is not permission to choose a different
	84	+model for a thread.
	85	+
42	86	## Model manifest
43	87
44	88	The model picker's legacy section is driven by `apps/server/src/provider/model-manifest.json`, which
@@ -121,6 +165,7 @@ when a request opens (approval) or user input is requested, via · 76 unmodified lines
121	165	[cursor]: ../../apps/server/src/provider/Drivers/CursorDriver.ts
122	166	[grok]: ../../apps/server/src/provider/Drivers/GrokDriver.ts
123	167	[opencode]: ../../apps/server/src/provider/Drivers/OpenCodeDriver.ts
	168	+[opencode-server-owner]: ../../apps/server/src/provider/OpenCodeServerOwner.ts
124	169	[adapter]: ../../apps/server/src/provider/Services/ProviderAdapter.ts
125	170	[instances]: ../../apps/server/src/provider/Services/ProviderInstanceRegistry.ts
126	171	[registry]: ../../apps/server/src/provider/Services/ProviderAdapterRegistry.ts

docs/user/providers-opencode.md+53−0

@@ -0,0 +1,53 @@
	1	+# OpenCode
	2	+
	3	+T3 Code uses the OpenCode setup on the connected environment. With a remote environment, its
	4	+OpenCode login and configuration apply, not the setup on your desktop or phone.
	5	+
	6	+T3 Code requires OpenCode 1.14.19 or newer. It checks the server version before it loads models or
	7	+starts work. If the check fails, update OpenCode or fix the server URL and password, then refresh
	8	+the provider status. Reconnecting the client also runs the check again.
	9	+
	10	+## Server authentication
	11	+
	12	+Without a server URL, T3 Code starts a local OpenCode server. The process inherits
	13	+`OPENCODE_SERVER_PASSWORD` from the environment. A password in the provider settings overrides
	14	+that environment value for both the local process and T3 Code.
	15	+
	16	+With a server URL, T3 Code connects to that external server and uses only the password in the
	17	+provider settings. It does not send a local `OPENCODE_SERVER_PASSWORD` to an external server.
	18	+OpenCode uses this password for HTTP Basic authentication.
	19	+
	20	+## Refresh the model list
	21	+
	22	+T3 Code loads the model list when an enabled OpenCode provider starts and keeps the list in its
	23	+cache. Reconnecting a client or using a refresh control asks OpenCode for the list again. The
	24	+periodic provider health setting does not refresh OpenCode's catalog.
	25	+
	26	+After changing an OpenCode login or configuration outside T3 Code, open Settings > Providers,
	27	+select the environment, and choose Refresh provider status. Changing the provider's
	28	+configuration in T3 Code also replaces that provider connection.
	29	+
	30	+On mobile, open the thread settings and select Refresh models. The control stays disabled while
	31	+the refresh runs and shows an error if the refresh fails.
	32	+
	33	+OpenCode reads credential changes on each model-list request. Native OpenCode configuration files
	34	+can stay cached while the local helper is running. The helper closes after 30 seconds with no
	35	+model-list or text-generation work. Refresh after that idle period to start a new helper and read
	36	+the file changes. Repeated refreshes or active helper work can extend this wait.
	37	+
	38	+T3 Code does not own an external OpenCode server. Native configuration changes on that server can
	39	+require its own reload or restart before a refresh returns the new list.
	40	+
	41	+If a refresh fails, T3 Code keeps the last known models, slash commands, and skills. Fix the
	42	+connection, then refresh again. A successful refresh can remove entries that OpenCode no longer
	43	+offers.
	44	+
	45	+## Continue an existing thread
	46	+
	47	+An existing thread keeps its selected model and options when that model is temporarily absent
	48	+from the catalog. The web picker shows an Unavailable row and keeps saved option values visible
	49	+until the model metadata returns. T3 Code does not switch the thread to the first model in the
	50	+list.
	51	+
	52	+The stored selection does not guarantee that OpenCode can still run the model. If the provider
	53	+rejects it, select an available model before trying again.