Skip to content

Commit 96717c1

Browse files
committed
feat(tui): improve session fork handling
1 parent e312f0d commit 96717c1

24 files changed

Lines changed: 335 additions & 387 deletions

‎.opencode/skills/debug-opencode/SKILL.md‎

Lines changed: 0 additions & 163 deletions
This file was deleted.

‎packages/cli/AGENTS.md‎

Lines changed: 2 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -3,96 +3,5 @@
33
## Migration context
44

55
- The TUI is being ported from legacy APIs to the new V2 APIs. New and migrated TUI behavior should use `sdk.client.v2` and the location-scoped data in `packages/tui/src/context/data.tsx` instead of adding dependencies on legacy sync state.
6-
- Preserve established TUI behavior unless the task intentionally changes it. When behavior, copy, keyboard interaction, or layout is unclear, compare the local V2 TUI with the latest released legacy TUI.
7-
- Run both versions in separate Terminal Control sessions and save PNG-only captures at equivalent states:
8-
9-
```bash
10-
# From packages/cli: local V2 TUI
11-
termctrl start opencode-v2-dev --host opentui --cols 112 --rows 34 -- bun dev
12-
13-
# Released legacy TUI behavior reference
14-
termctrl start opencode-legacy --host opentui --cols 112 --rows 34 -- bunx opencode-ai@latest
15-
16-
termctrl save opencode-v2-dev --format png --out /tmp/opencode/v2.png
17-
termctrl save opencode-legacy --format png --out /tmp/opencode/legacy.png
18-
```
19-
20-
- Use the same viewport and send equivalent inputs to both sessions before comparing screenshots. The released CLI is a behavioral reference, not a source of V2 API design; keep the local implementation on V2 endpoints.
21-
- Stop both sessions after comparison: `termctrl stop opencode-v2-dev` and `termctrl stop opencode-legacy`.
22-
23-
## Interactive debugging
24-
25-
- This package is the V2 CLI adapter. Run its `dev` script when testing the TUI; do not use the repository-root `bun dev`, which launches the legacy `packages/opencode` CLI.
26-
- Run commands from `packages/cli`. Use `bun dev` for most debugging so the TUI starts with a private V2 server.
27-
- Use `termctrl` for interactive checks instead of starting the TUI as a blocking foreground process. It provides a real PTY, handles OpenTUI's host handshake, and can save reviewable screenshots.
28-
- Use a dedicated session name and do not reuse or kill an unrelated session.
29-
30-
```bash
31-
termctrl start opencode-v2-dev --host opentui --cols 112 --rows 34 -- bun dev
32-
termctrl wait opencode-v2-dev "Ask anything" --timeout 20000
33-
termctrl show opencode-v2-dev
34-
```
35-
36-
- Wait for visible text before interacting instead of relying on fixed sleeps. Use the text expected from the screen under test, such as `Ask anything` or `Connect a provider`.
37-
- Drive the running TUI with `termctrl send`. Prefix typed input with `text:` and send control keys separately so the interaction matches real terminal input.
38-
39-
```bash
40-
termctrl send opencode-v2-dev 'text:example prompt' enter
41-
termctrl send opencode-v2-dev ctrl-c
42-
```
43-
44-
- Use `termctrl show` after each meaningful interaction and inspect the full visible screen for rendering errors, stale state, error toasts, and unexpected exits.
45-
- Save PNG evidence for every user-visible bug and fix. Do not save text captures; inspect the rendered PNG. Write temporary captures outside the repository unless the artifact is intended to be committed.
46-
47-
```bash
48-
termctrl save opencode-v2-dev --format png --out /tmp/opencode/v2-tui.png
49-
```
50-
51-
- For resize-sensitive changes, resize the viewport, wait for the expected content, and capture the screen again:
52-
53-
```bash
54-
termctrl resize opencode-v2-dev --cols 100 --rows 30
55-
termctrl show opencode-v2-dev
56-
```
57-
58-
- Source changes may require restarting the process. Use `termctrl restart opencode-v2-dev` rather than assuming the running TUI reloaded the change.
59-
- To exercise background-service behavior, use `bun dev service start`, `bun dev service status`, and `bun dev service stop`.
60-
- Always clean up the Terminal Control session when the check is complete:
61-
62-
```bash
63-
termctrl stop opencode-v2-dev
64-
```
65-
66-
## Server/API debugging
67-
68-
- Use `bun dev api --help` from `packages/cli` to inspect the API debugging command. It sends one request to the V2 server using the same daemon discovery/auth path as the CLI.
69-
- Use `bun dev api` to introspect the server-side data backing the TUI. This is useful when debugging UI bugs: compare what the screen renders with the raw session, message, event, agent, or health data returned by the API to determine whether the bug is in the server state, the client data layer, or the TUI rendering.
70-
- `bun dev api` accepts either an OpenAPI operation ID or a raw HTTP method plus path:
71-
72-
```bash
73-
bun dev api get /health
74-
bun dev api get /openapi.json
75-
bun dev api <operationId> --param key=value
76-
```
77-
78-
- Pass JSON request bodies with `--data`/`-d`; the command sets `content-type: application/json` automatically unless you provide a header. Add extra headers with `--header`/`-H name:value`.
79-
- If no compatible background server is registered, `bun dev api` starts one through the daemon service. Use `bun dev service status`, `bun dev service restart`, and `bun dev service stop` when you need explicit lifecycle control.
80-
- Prefer raw method/path calls for quick server debugging and operation IDs when exercising documented OpenAPI routes with path or query parameters.
81-
82-
## Debugger
83-
84-
- To debug the V2 CLI or TUI with Bun's inspector, launch the CLI entrypoint through Terminal Control with an inspector URL, then attach a debugger to that URL:
85-
86-
```bash
87-
termctrl start opencode-v2-debug --host opentui --cols 112 --rows 34 -- \
88-
bun run --inspect=ws://localhost:6499/ src/index.ts
89-
```
90-
91-
- Use `--inspect-wait` or `--inspect-brk` when execution must pause until the debugger attaches.
92-
- Use `termctrl logs opencode-v2-debug` for inspector output or startup failures emitted before the TUI renderer starts. Use `termctrl show` for the visible full-screen TUI.
93-
94-
## Verification
95-
96-
- Run `bun typecheck` from `packages/cli` after CLI adapter changes.
97-
- Run `bun typecheck` and `bun test` from `packages/tui` after shared TUI changes. Do not run tests from the repository root.
98-
- Treat automated checks and Terminal Control smoke tests as complementary. For user-visible changes, verify initial render, the changed interaction, Ctrl-C exit behavior, and save a screenshot of the corrected state.
6+
- Preserve established TUI behavior unless the task intentionally changes it.
7+
- Load the `opencode-dev` skill before interactively running, debugging, or verifying opencode's V2 CLI, TUI, or server.

‎packages/client/src/promise/generated/types.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,7 @@ export type SessionListOutput = {
326326
readonly data: ReadonlyArray<{
327327
readonly id: string
328328
readonly parentID?: string
329+
readonly fork?: { readonly sessionID: string; readonly messageID?: string }
329330
readonly projectID: string
330331
readonly agent?: string
331332
readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string }
@@ -388,6 +389,7 @@ export type SessionCreateOutput = {
388389
readonly data: {
389390
readonly id: string
390391
readonly parentID?: string
392+
readonly fork?: { readonly sessionID: string; readonly messageID?: string }
391393
readonly projectID: string
392394
readonly agent?: string
393395
readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string }
@@ -426,6 +428,7 @@ export type SessionGetOutput = {
426428
readonly data: {
427429
readonly id: string
428430
readonly parentID?: string
431+
readonly fork?: { readonly sessionID: string; readonly messageID?: string }
429432
readonly projectID: string
430433
readonly agent?: string
431434
readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string }
@@ -465,6 +468,7 @@ export type SessionForkOutput = {
465468
readonly data: {
466469
readonly id: string
467470
readonly parentID?: string
471+
readonly fork?: { readonly sessionID: string; readonly messageID?: string }
468472
readonly projectID: string
469473
readonly agent?: string
470474
readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string }

‎packages/core/schema.json‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
{
22
"version": "7",
33
"dialect": "sqlite",
4-
"id": "992b24b9-f3e9-41f5-87a5-4917d1423169",
4+
"id": "95328a41-789d-44de-9643-6ac6ecd6b4ec",
55
"prevIds": [
6-
"96e9fe64-660f-4a73-9414-b38bb7eac290"
6+
"992b24b9-f3e9-41f5-87a5-4917d1423169"
77
],
88
"ddl": [
99
{
@@ -1166,6 +1166,26 @@
11661166
"entityType": "columns",
11671167
"table": "session"
11681168
},
1169+
{
1170+
"type": "text",
1171+
"notNull": false,
1172+
"autoincrement": false,
1173+
"default": null,
1174+
"generated": null,
1175+
"name": "fork_session_id",
1176+
"entityType": "columns",
1177+
"table": "session"
1178+
},
1179+
{
1180+
"type": "text",
1181+
"notNull": false,
1182+
"autoincrement": false,
1183+
"default": null,
1184+
"generated": null,
1185+
"name": "fork_message_id",
1186+
"entityType": "columns",
1187+
"table": "session"
1188+
},
11691189
{
11701190
"type": "text",
11711191
"notNull": true,
@@ -2252,4 +2272,4 @@
22522272
}
22532273
],
22542274
"renames": []
2255-
}
2275+
}

‎packages/core/src/database/migration.gen.ts‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)