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	- [Keeping app and server in sync](./user/updating.md)	13	- [Keeping app and server in sync](./user/updating.md)
14	- [Source control integrations](./user/source-control.md)	14	- [Source control integrations](./user/source-control.md)
15	- [Background service (Linux)](./user/background-service.md)	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	Mobile app: [apps/mobile/README.md](../apps/mobile/README.md)	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	Adding a driver means writing the driver plus adapter and adding it to `BUILT_IN_DRIVERS`. No	39	Adding a driver means writing the driver plus adapter and adding it to `BUILT_IN_DRIVERS`. No
40	orchestration, contract, or client change is required for the common case.	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	## Model manifest	86	## Model manifest
43		87
44	The model picker's legacy section is driven by `apps/server/src/provider/model-manifest.json`, which	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	[cursor]: ../../apps/server/src/provider/Drivers/CursorDriver.ts	165	[cursor]: ../../apps/server/src/provider/Drivers/CursorDriver.ts
122	[grok]: ../../apps/server/src/provider/Drivers/GrokDriver.ts	166	[grok]: ../../apps/server/src/provider/Drivers/GrokDriver.ts
123	[opencode]: ../../apps/server/src/provider/Drivers/OpenCodeDriver.ts	167	[opencode]: ../../apps/server/src/provider/Drivers/OpenCodeDriver.ts
		168	[opencode-server-owner]: ../../apps/server/src/provider/OpenCodeServerOwner.ts
124	[adapter]: ../../apps/server/src/provider/Services/ProviderAdapter.ts	169	[adapter]: ../../apps/server/src/provider/Services/ProviderAdapter.ts
125	[instances]: ../../apps/server/src/provider/Services/ProviderInstanceRegistry.ts	170	[instances]: ../../apps/server/src/provider/Services/ProviderInstanceRegistry.ts
126	[registry]: ../../apps/server/src/provider/Services/ProviderAdapterRegistry.ts	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.