openAgent

1# TUI Package Extraction
2 
3## Goal
4 
5Move the canonical OpenCode terminal application from
6`packages/opencode/src/cli/cmd/tui` into a self-contained workspace package while
7the legacy CLI and the new CLI continue to use the same implementation.
8 
9Target package:
10 
11```text
12packages/tui
13name: @opencode-ai/tui
14```
15 
16Target dependency graph:
17 
18```text
19packages/opencode ---\
20                      > @opencode-ai/tui -> @opencode-ai/sdk
21packages/cli --------/
22```
23 
24The TUI may directly depend on terminal and UI infrastructure such as
25`@opentui/core`, `@opentui/solid`, `@opentui/keymap`, `solid-js`, Effect, and
26generic presentation libraries. It must not depend on `packages/opencode`,
27`packages/cli`, or `@opencode-ai/core`.
28 
29The SDK is the TUI's OpenCode boundary. Missing backend data or operations must
30be added to the server API and generated SDK rather than imported from backend
31implementation modules.
32 
33## Migration Rules
34 
35- Keep one canonical implementation of every TUI feature. Do not copy the full
36  TUI into `packages/cli` and synchronize two trees.
37- Land each section below independently and commit it before starting the next
38  section.
39- Keep each intermediate commit buildable and type-safe.
40- Continue integrating team changes into whichever location is canonical for a
41  file at that point in the migration.
42- Use temporary compatibility re-exports only when they materially reduce the
43  size or conflict risk of a section. Mark them for removal in a later section.
44- Do not preserve private imports by creating aliases from `packages/tui` back
45  into `packages/opencode`.
46- Do not replace private `packages/opencode` imports with `@opencode-ai/core`
47  imports merely to make the package compile.
48- Keep tool rendering tolerant of unknown tools and wire-format changes. Local
49  checks over `unknown` input and metadata are acceptable; importing backend
50  tool implementations for type safety is not.
51- Keep legacy CLI command parsing, server startup, worker management,
52  authentication, and config discovery outside `@opencode-ai/tui`.
53 
54## Ownership Boundary
55 
56### `@opencode-ai/tui` Owns
57 
58- OpenTUI renderer lifecycle shared by both CLI hosts
59- Solid application composition
60- Components, routes, dialogs, themes, keymaps, and UI primitives
61- SDK client synchronization and event consumption
62- Tool-call and tool-result presentation
63- TUI-facing plugin contracts and presentation slots
64- Resolved TUI configuration types, defaults, and pure validation
65- Terminal behavior such as selection, clipboard integration, and local editor
66  launching when it is not host-specific
67- TUI-local persistence such as prompt history, stash, frecency, selected model,
68  and selected theme
69- Presentation utilities such as locale formatting, error display, record
70  checks, duration formatting, and layout helpers
71 
72### CLI Hosts Own
73 
74- Command definitions and argument parsing
75- Starting, locating, and stopping servers and workers
76- Authentication and transport construction
77- Process-level signal policy
78- Config file discovery, precedence, migration, and environment substitution
79- Plugin package discovery, installation, and backend activation
80- Upgrade checks and installation metadata
81- Executable build wiring and worker path defines
82 
83### Server And SDK Own
84 
85- OpenCode domain data displayed by the TUI
86- Session, message, workspace, file, provider, model, agent, and permission
87  operations
88- Retry, revert, fork, share, and other backend actions
89- Stable wire shapes for tool parts and plugin metadata
90- Server capabilities needed to conditionally expose UI behavior
91 
92## Current Boundary
93 
94The canonical implementation currently lives under:
95 
96```text
97packages/opencode/src/cli/cmd/tui
98```
99 
100Its private dependency on `packages/opencode` is primarily expressed through
101the `@/*` TypeScript alias, which resolves to `packages/opencode/src/*`.
102`@tui/*` imports are internal to the TUI and are not themselves a package
103boundary problem.
104 
105The main private dependency groups are:
106 
107- `@/util/*`: presentation helpers plus filesystem/process/RPC helpers
108- `@/tool/*`: backend tool implementations used by renderers
109- `@/session/*`, `@/provider/*`, and `@/reference/*`: backend data and actions
110- `@/config/*`: config discovery, parsing, variables, and plugin resolution
111- `@/plugin/*`: plugin loading and installation
112- `@/cli/*`: yargs adapters, network setup, errors, and CLI presentation
113- `@/server/*`: authentication and embedded server behavior
114- `Global.Path`, `Flag`, and process environment reads
115 
116The initial extraction should reduce these dependencies in place before moving
117the application root.
118 
119## Section 1: Create The Package Skeleton
120 
121Status: Completed. The private `@opencode-ai/tui` workspace package now has an
122independent OpenTUI Solid JSX configuration, narrow root export, package-local
123alias, and in-memory render smoke test. Neither CLI consumes the package yet.
124 
125Create `packages/tui` without moving the application root yet.
126 
127Tasks:
128 
129- Add `packages/tui/package.json` with the name `@opencode-ai/tui`.
130- Add a package `tsconfig.json` configured for OpenTUI Solid JSX.
131- Add `bunfig.toml` with the OpenTUI Solid preload for package-local development
132  and tests.
133- Add package scripts for `typecheck` and package-local tests.
134- Add direct dependencies used by the TUI. Do not rely on workspace hoisting.
135- Add a narrow package export, initially only the package root and any explicit
136  testing entrypoint needed by migrated tests.
137- Establish a package-local import convention. A local alias such as `@tui/*`
138  is acceptable, but it must resolve entirely inside `packages/tui`.
139- Add a minimal package entrypoint and smoke test proving OpenTUI Solid TSX can
140  typecheck and render.
141- Do not make either CLI consume the package yet.
142 
143Exit criteria:
144 
145- `packages/tui` typechecks independently.
146- Its test command runs from `packages/tui`.
147- The package has no dependency on `opencode`, `@opencode-ai/cli`, or
148  `@opencode-ai/core`.
149 
150Checkpoint commit:
151 
152```text
153feat(tui): add standalone package skeleton
154```
155 
156## Section 2: Move Presentation Utilities And Leaf UI
157 
158Status: Completed. Presentation utilities, bundled themes and their pure theme
159engine, keybinding/keymap mechanics, and low-coupling border, link, and spinner
160primitives now live in `@opencode-ai/tui`. The legacy host consumes explicit
161package exports and retains only integration wrappers or compatibility
162re-exports where backend and process concerns have not moved yet.
163 
164Move low-coupling code first so subsequent team changes land in the new package
165without waiting for the application root migration.
166 
167Tasks:
168 
169- Move TUI presentation utilities into `packages/tui/src/util`, including the
170  portions of locale, error display, record checks, duration formatting, and
171  small functional helpers used by TUI code.
172- Move pure TUI utilities already under the old TUI directory.
173- Move themes and bundled theme JSON files.
174- Move UI primitives and leaf components that have no private backend imports.
175- Move pure keybinding schemas and keymap helpers that do not read host flags.
176- Move related unit and snapshot tests.
177- Update remaining old-tree consumers to import the new canonical modules.
178- Use temporary compatibility re-exports from old TUI paths only if needed to
179  avoid a large unrelated import rewrite.
180- Do not move `Filesystem`, `Process`, `Rpc`, worker startup, or config discovery
181  as generic utilities in this section.
182 
183Exit criteria:
184 
185- Moved files have no `@/...` imports.
186- Tests for moved code run from `packages/tui`.
187- Existing legacy TUI behavior and typecheck remain unchanged.
188 
189Checkpoint commit:
190 
191```text
192refactor(tui): move presentation utilities and primitives
193```
194 
195## Section 3: Remove Backend Tool Implementation Imports
196 
197Status: Completed. Legacy and V2 tool renderers now dispatch on SDK wire names,
198accept `Record<string, unknown>` input and metadata, and use local guards for
199nested presentation data. Web-search labels and structured metadata extraction
200are TUI-owned, unknown tools retain the generic fallback, and no TUI source
201imports backend tool implementations. The route components remain in the legacy
202tree until the SDK state and route move in Section 6.
203 
204Make tool rendering depend only on SDK wire data and local presentation logic.
205 
206Tasks:
207 
208- Remove imports from `@/tool/*` in TUI routes and feature plugins.
209- Key built-in renderers by SDK tool name strings such as `read`, `write`,
210  `edit`, `apply_patch`, `grep`, `glob`, `bash`, `question`, and `task`.
211- Treat tool input, output metadata, and plugin-defined fields as `unknown` at
212  the package boundary.
213- Add small local type guards only where a renderer needs a particular field.
214- Preserve a generic fallback renderer for unknown and plugin-provided tools.
215- Keep renderer failures local: malformed metadata must not crash the entire
216  session view.
217- Replace backend-derived labels or IDs with TUI-owned presentation constants or
218  SDK-provided values.
219- Move the affected tool presentation components and tests to `packages/tui`.
220 
221Exit criteria:
222 
223- No TUI source imports `@/tool/*`.
224- Unknown tools render through the generic fallback.
225- Existing built-in tool snapshots remain equivalent unless intentionally
226  updated and reviewed.
227 
228Checkpoint commit:
229 
230```text
231refactor(tui): decouple tool rendering from backend tools
232```
233 
234## Section 4: Make Runtime Inputs Explicit
235 
236Status: Completed for the shared runtime contract and legacy host. The TUI now
237receives immutable launch-directory, path, capability, terminal/editor, startup,
238and build inputs through `@opencode-ai/tui/runtime`. Movable app, component,
239route, and feature-plugin code no longer reads OpenCode globals or process state;
240command, config, plugin-loading, custom-theme discovery, editor/clipboard, and
241Windows lifecycle adapters remain host-owned. `packages/cli` does not consume
242this contract yet; that integration remains deferred to Section 9.
243 
244Replace process-global OpenCode state with resolved TUI inputs.
245 
246Define narrow inputs rather than one unstructured host object. Expected groups
247include:
248 
249```ts
250type TuiCapabilities = {
251  mouse: boolean
252  copyOnSelect: boolean
253  terminalTitle: boolean
254  workspaces: boolean
255  showTimeToFirstDraw: boolean
256}
257 
258type TuiPaths = {
259  home: string
260  state: string
261  config: string
262  data: string
263}
264 
265type TuiBuildInfo = {
266  version: string
267  channel?: string
268}
269```
270 
271Tasks:
272 
273- Inventory direct reads of `Flag`, `Global.Path`, and relevant environment
274  variables in movable TUI code.
275- Pass resolved capabilities into the application/provider tree.
276- Pass local path roots or a narrow TUI storage capability into persistence
277  contexts.
278- Pass build/version information explicitly.
279- Keep environment reads needed by legacy command or worker startup in
280  `packages/opencode` adapters.
281- Give `packages/tui` sensible host-neutral defaults only when behavior is truly
282  local to a terminal client.
283- Move contexts and components after their global dependencies are removed.
284 
285Exit criteria:
286 
287- Movable TUI code does not import `Flag` or `Global`.
288- TUI tests can supply deterministic capabilities and storage paths.
289- The legacy host constructs the required input through the public package API;
290  the new CLI integration remains deferred to Section 9.
291 
292Checkpoint commit:
293 
294```text
295refactor(tui): make runtime capabilities explicit
296```
297 
298## Section 5: Separate Resolved TUI Config From Host Config Loading
299 
300Status: Completed for the package config contract and legacy host adapter.
301`@opencode-ai/tui/config` now owns schemas, defaults, keybind resolution, the
302resolved config type, and the Solid config provider. The legacy host retains
303file discovery, precedence, JSONC parsing, substitutions, migration,
304source-relative sound paths, plugin origins, dependency installation, and
305Effect services. `packages/cli` remains untouched until Section 9.
306 
307Move config semantics needed by rendering while retaining filesystem discovery
308and migration in the legacy host.
309 
310Tasks:
311 
312- Move TUI config schemas, keybind schemas, defaults, and pure resolution to
313  `packages/tui`.
314- Define the resolved config accepted by the public TUI entrypoint.
315- Keep config path discovery, project/global precedence, migration, variable
316  expansion, and plugin package installation in `packages/opencode` initially.
317- Make the legacy host produce the same resolved config shape.
318- Add a new CLI adapter that can initially provide defaults or its own resolved
319  configuration.
320- Update schema-generation imports to use the package's explicit config export
321  if schema generation still needs TUI schemas.
322- Move pure config tests; retain discovery and migration integration tests in
323  `packages/opencode`.
324 
325Exit criteria:
326 
327- `packages/tui` does not import `@/config/*`.
328- Config discovery can change without changing TUI rendering code.
329- The old CLI still honors existing config precedence and migration behavior.
330 
331Checkpoint commit:
332 
333```text
334refactor(tui): separate config resolution from loading
335```
336 
337## Section 6: Move SDK State, Routes, And Backend Operations
338 
339Status: Completed for the SDK/domain boundary. SDK, project, event, legacy sync,
340V2 sync, local model state, prompt persistence, and pure prompt helpers are now
341canonical in `@opencode-ai/tui`. Configured references resolve through the new
342generated `reference.list` SDK operation; prompt payloads rely on optional
343server-assigned IDs; local attachment reads use the package platform contract.
344Legacy route files remain in place until the plugin slot boundary and app-root
345move, but their only private dependencies are plugin presentation or local host
346adapters rather than OpenCode domain implementations.
347 
348Make the SDK the only OpenCode domain boundary used by the TUI.
349 
350Tasks:
351 
352- Move SDK client providers, event synchronization, routes, prompt UI, and
353  session views into `packages/tui`.
354- Replace direct imports from `@/session/*`, `@/provider/*`, `@/reference/*`,
355  `@/lsp/*`, and other backend domains with SDK data or TUI-owned presentation
356  helpers.
357- Replace direct backend actions such as retry with SDK calls.
358- For each missing operation, add or adjust the server endpoint, regenerate the
359  JavaScript SDK with `./packages/sdk/js/script/build.ts`, and consume the
360  generated SDK API.
361- Keep transport creation outside the package. Accept a base URL, headers,
362  custom fetch, event source, or constructed SDK client as appropriate.
363- Keep local-only UI state in the TUI package rather than adding it to the
364  server API.
365- Move affected tests and fixtures. Use real SDK/server integration where
366  practical instead of mocking backend modules.
367 
368Exit criteria:
369 
370- Domain-facing TUI code imports OpenCode data and operations only from
371  `@opencode-ai/sdk`.
372- No TUI source imports private session, provider, reference, LSP, server, or
373  core domain implementations.
374- SDK generation is clean after any API changes.
375 
376Checkpoint strategy:
377 
378This section may be split into multiple commits when an SDK gap is substantial.
379Each commit must leave both the old TUI host and package tests working. Suggested
380commit pattern:
381 
382```text
383feat(sdk): expose <operation> for tui clients
384refactor(tui): move <area> to sdk boundary
385```
386 
387Final section checkpoint:
388 
389```text
390refactor(tui): move sdk state and routes into package
391```
392 
393## Section 7: Isolate Plugin Presentation From Plugin Loading
394 
395Status: Completed. Plugin slots, route registration, TUI-facing APIs, runtime
396presentation state, and built-in feature plugins now live in
397`@opencode-ai/tui`. The legacy host injects a narrow plugin host that retains
398discovery, installation, manifest/config mutation, external module execution,
399pure-mode filtering, and cleanup ownership. Missing or failing plugin hosts
400degrade to the base TUI without blocking startup.
401 
402Keep plugin UI extensibility without importing the legacy plugin installer and
403loader into the TUI package.
404 
405Tasks:
406 
407- Move plugin presentation slots, route contracts, and TUI-facing APIs into
408  `packages/tui` or the existing public plugin TUI contract package.
409- Keep package discovery, installation, manifest resolution, backend activation,
410  and process lifecycle in the host.
411- Define the serialized or runtime plugin presentation data the TUI requires.
412- Prefer SDK-delivered plugin metadata when the behavior must also work for a
413  remote server.
414- Make plugin absence or incompatibility degrade gracefully.
415- Move plugin rendering tests to `packages/tui`; retain installation/loading
416  integration tests in `packages/opencode`.
417 
418Exit criteria:
419 
420- `packages/tui` does not import `@/plugin/*` or the old TUI plugin runtime.
421- Remote and local TUI clients have a defined plugin behavior.
422- Plugin UI failures cannot prevent the base TUI from starting.
423 
424Checkpoint commit:
425 
426```text
427refactor(tui): separate plugin presentation from loading
428```
429 
430## Section 8: Move The Application Root And Renderer Lifecycle
431 
432Status: Completed. `packages/tui` now owns the canonical application root,
433provider composition, routes, components, parser presentation, renderer
434configuration, and renderer lifecycle. Process mutation, Windows console
435handling, backend worker startup, config loading, plugin loading, native audio,
436and legacy platform implementations remain injected host adapters. Old source
437paths are temporary compatibility re-exports for the legacy command host.
438 
439Move the canonical app composition after its dependencies have already crossed
440the package boundary.
441 
442Tasks:
443 
444- Move `app.tsx`, remaining providers, routes, components, attention handling,
445  keymaps, and renderer lifecycle to `packages/tui`.
446- Export a narrow public API such as:
447 
448```ts
449export type TuiInput = {
450  url: string
451  directory?: string
452  headers?: RequestInit["headers"]
453  fetch?: typeof fetch
454  config: TuiConfig.Resolved
455  capabilities: TuiCapabilities
456  paths: TuiPaths
457}
458 
459export function run(input: TuiInput): TuiHandle
460export function createRenderer(config: TuiConfig.Resolved): Promise<CliRenderer>
461```
462 
463- Preserve the existing lifecycle guarantees: readiness, waiting until exit,
464  idempotent cleanup, renderer destruction, SIGHUP handling where appropriate,
465  and terminal restoration.
466- Keep Windows process adapters outside the package if they mutate host process
467  state; invoke them from CLI adapters around the package lifecycle.
468- Keep OpenTUI parser-worker embedding in executable build scripts.
469- Move app lifecycle and rendering tests to `packages/tui`.
470 
471Exit criteria:
472 
473- `packages/tui` contains the canonical application root.
474- The package has no imports from `packages/opencode`, `packages/cli`, or
475  `@opencode-ai/core`.
476- The package public API is sufficient for both old and new CLI adapters.
477 
478Checkpoint commit:
479 
480```text
481refactor(tui): move application root into package
482```
483 
484## Section 9: Convert Both CLIs To Thin Adapters
485 
486Status: Completed. The legacy thread and attach commands now lazily invoke the
487public `@opencode-ai/tui` root while retaining worker/server/config/plugin and
488process adapters. The new CLI default command launches the same package against
489its authenticated daemon transport with a minimal local platform/host. Missing
490legacy provider/config APIs currently degrade to the shared provider-connect
491screen; source and compiled new-CLI behavior match, while named commands remain
492outside the TUI path.
493 
494Make both executable packages consume the same TUI package.
495 
496Tasks:
497 
498- Keep the legacy yargs commands corresponding to current `thread.ts` and
499  `attach.ts` in `packages/opencode`.
500- Keep the legacy embedded worker and server startup in `packages/opencode`.
501- Change those adapters to load config, create transport inputs, and call the
502  public `@opencode-ai/tui` API.
503- Change `packages/cli`'s default command handler to call the same public API.
504- Remove the temporary `packages/cli/src/tui` shell after the shared package is
505  integrated.
506- Remove duplicated OpenTUI lifecycle code from both hosts.
507- Ensure non-TUI subcommands remain lazily isolated from OpenTUI startup.
508- Update executable build scripts to bundle the shared package, parser worker,
509  assets, and any retained host worker.
510 
511Exit criteria:
512 
513- Both CLIs launch the same package implementation.
514- There is no duplicate TUI source tree in `packages/cli`.
515- Legacy attach and local-worker modes still work.
516- Named non-TUI commands do not launch or eagerly initialize the TUI.
517 
518Checkpoint commit:
519 
520```text
521refactor(cli): share tui package across command hosts
522```
523 
524## Section 10: Remove Compatibility Paths And Finish Ownership
525 
526Status: Completed. Package source imports are self-contained, package exports
527are narrowed to active host contracts, package-owned tests and snapshots live
528under `packages/tui`, and the obsolete compatibility tree has been removed.
529Legacy command, worker, config, plugin-loader, process, editor, audio, and event
530adapters now live in explicit host-owned locations outside `src/cli/cmd/tui/`.
531 
532Delete migration scaffolding only after both hosts consume the package.
533 
534Tasks:
535 
536- Remove old TUI compatibility re-exports and the obsolete directory tree under
537  `packages/opencode/src/cli/cmd/tui`.
538- Retain and relocate only true host adapters such as legacy commands, worker,
539  transport setup, and config loading.
540- Remove obsolete `@tui/*` path mappings from `packages/opencode`.
541- Remove stale test fixtures and update all imports to package exports.
542- Narrow `@opencode-ai/tui` exports to intentional public entrypoints.
543- Verify package manifests list every direct dependency and no accidental
544  dependency is supplied only by workspace hoisting.
545- Update repository documentation describing TUI ownership and development.
546 
547Exit criteria:
548 
549- No production import references the old TUI source location.
550- No source under `packages/tui` imports `@/...`, `@opencode-ai/core`, or either
551  executable package.
552- The old TUI directory contains no canonical implementation files.
553- The dependency graph has no cycle.
554 
555Checkpoint commit:
556 
557```text
558refactor(tui): complete standalone package extraction
559```
560 
561## Invariants To Preserve
562 
563- There is one canonical TUI implementation at every migration stage.
564- Legacy TUI behavior remains available until its host is intentionally removed.
565- The default new CLI command launches the TUI, while named subcommands continue
566  to route to their own handlers.
567- Renderer cleanup restores the terminal on normal exit, interruption, startup
568  failure, and renderer destruction.
569- TUI package imports do not reach into executable or backend implementation
570  packages.
571- SDK wire data is treated as the source of truth for OpenCode domain state.
572- Unknown tools and plugin data render safely without backend type imports.
573- Remote-server use remains possible; the TUI must not require an in-process
574  backend implementation.
575- TUI-local persistence remains local and does not become server state unless
576  there is an explicit product requirement.
577- Team changes should be moved with their canonical file, not manually copied
578  between old and new implementations.
579 
580## Verification Gates
581 
582Run verification after every section, adding narrower tests for the area being
583moved.
584 
585Package checks:
586 
587```text
588cd packages/tui && bun typecheck
589cd packages/tui && bun test
590cd packages/opencode && bun typecheck
591cd packages/cli && bun typecheck
592```
593 
594Dependency checks:
595 
596```text
597rg "from ['\"]@/" packages/tui/src
598rg '@opencode-ai/core|packages/opencode|packages/cli' packages/tui
599rg 'src/cli/cmd/tui|@tui/' packages/opencode/src packages/opencode/test
600```
601 
602SDK checks when server APIs change:
603 
604```text
605./packages/sdk/js/script/build.ts
606git diff --check
607```
608 
609Interactive smoke checks should run in `tmux` so the terminal can be captured
610and cleaned up reliably:
611 
612- Start the legacy local TUI and confirm initial render.
613- Start legacy attach mode against a server.
614- Start the new CLI default command and confirm it renders the same package.
615- Exit each mode with Ctrl-C and verify the process and terminal are restored.
616- Run representative named commands in both CLIs and verify they do not launch
617  the TUI.
618 
619Compiled checks:
620 
621- Build the current-platform `packages/opencode` binary.
622- Build the current-platform `packages/cli` binary.
623- Run TUI and non-TUI smoke checks against both compiled binaries.
624- Verify theme JSON, audio assets, OpenTUI parser worker, and retained backend
625  worker assets are included.
626 
627## Progress Tracking
628 
629- [x] Section 1: Create the package skeleton
630- [x] Section 2: Move presentation utilities and leaf UI
631- [x] Section 3: Remove backend tool implementation imports
632- [x] Section 4: Make runtime inputs explicit
633- [x] Section 5: Separate resolved TUI config from host config loading
634- [x] Section 6: Move SDK state, routes, and backend operations
635- [x] Section 7: Isolate plugin presentation from plugin loading
636- [x] Section 8: Move the application root and renderer lifecycle
637- [x] Section 9: Convert both CLIs to thin adapters
638- [x] Section 10: Remove compatibility paths and finish ownership
639 
640Update each section's status and this checklist in the same commit that completes
641the section.
642