1 -#
UI Extension Phase 2 Implementation Plan 3 -> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 -**Goal:** Make `/ui` a minimal browser Pi frontend backed by a seeded active-branch RPC subprocess.
7 -**Architecture:** Keep Phase 1 server/runtime as owner. Add active-branch session seeding, a Pi RPC child-process bridge, a small event protocol, WebSocket fanout, and a no-framework browser shell that renders snapshots plus ordered events.
9 -**Tech Stack:** Node `child_process`, `fs`, `readline`, `crypto`; Pi `SessionManager`; browser WebSocket, Web Components, CSS; Vitest harness tests.
11 -**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 -**Phase:** Phase 2: Active-Branch RPC Session and Basic Web Stream
21 -- Seed a persistent web session from `ctx.sessionManager.createBranchedSession(ctx.sessionManager.getLeafId())`.
22 -- Spawn `pi --mode rpc --session <seeded-session>` with normal extensions/skills/settings.
23 -- Parse LF-delimited JSONL from RPC stdout and keep stderr diagnostics separate.
24 -- Add RPC request queue with ids, timeout, startup, death, and slow-start states.
25 -- Add `/api/snapshot`, `/ws`, event replay buffer, monotonic event ids, and JSON protocol types.
26 -- Replace Phase 1 shell page with a basic stream-first browser app and composer.
27 -- Send browser prompts through RPC and render user/assistant/tool/error stream items.
31 -- Full slash-command parity.
32 -- Rich syntax/autocomplete.
35 -- Nugu polish beyond readable brutal defaults.
41 -- `extensions/ui/session-seed.ts` — active-branch seed path and warnings.
42 -- `extensions/ui/rpc.ts` — child process, JSONL parser, request queue, lifecycle.
43 -- `extensions/ui/protocol.ts` — event/snapshot/request types.
44 -- `extensions/ui/events.ts` — monotonic event store and replay.
45 -- `extensions/ui/web/app.html.ts` — HTML shell.
46 -- `extensions/ui/web/app.css.ts` — minimal stream-first CSS.
47 -- `extensions/ui/web/app.js.ts` — browser app source emitted by server.
48 -- `extensions/ui/__tests__/session-seed.test.ts`.
49 -- `extensions/ui/__tests__/rpc.test.ts`.
50 -- `extensions/ui/__tests__/events.test.ts`.
51 -- `extensions/ui/__tests__/web-smoke.test.ts`.
55 -- `extensions/ui/runtime.ts` — own seed, RPC, event store.
56 -- `extensions/ui/server.ts` — add snapshot, app assets, WebSocket upgrade.
57 -- `extensions/ui/index.ts` — pass command context into runtime start.
58 -- `extensions/ui/terminal-widget.ts` — show RPC startup/connected/dead states.
59 -- `extensions/ui/package.json` — add `ws` and `@types/ws` if native upgrade handling is not enough.
63 -###
Task 1: Event protocol and store 65 -- [ ] Write `events.test.ts` for monotonic ids, bounded replay, and snapshot shape.
66 -- [ ] Implement `protocol.ts` and `events.ts` with `UiEvent`, `UiSnapshot`, `EventStore.append`, `EventStore.snapshot`, and `EventStore.replayAfter`.
67 -- [ ] Run `npx vitest run extensions/ui/__tests__/events.test.ts`; expect PASS.
68 -- [ ] Commit `Add ui event protocol`.
70 -###
Task 2: Active-branch session seed 72 -- [ ] Write `session-seed.test.ts` using a fake session manager with `getLeafId()` and `createBranchedSession()`.
73 -- [ ] Implement `session-seed.ts` so the default path calls `createBranchedSession(getLeafId())` and returns `{ path, warning: undefined }`.
74 -- [ ] Add fallback warning only when whole-tree `forkFrom` is explicitly used by option.
75 -- [ ] Run `npx vitest run extensions/ui/__tests__/session-seed.test.ts`; expect PASS.
76 -- [ ] Commit `Add ui active branch session seed`.
78 -###
Task 3: RPC bridge 80 -- [ ] Write `rpc.test.ts` for JSONL parsing, request id matching, stderr capture, timeout, process exit event, and slow-start event.
81 -- [ ] Implement `rpc.ts` with `startRpc`, `sendRpc`, `closeRpc`, `parseJsonLines`, and typed lifecycle callbacks.
82 -- [ ] Make subprocess command resolve to `pi.cmd` on win32 and `pi` elsewhere unless `PI_UI_RPC_BIN` overrides it for tests.
83 -- [ ] Run `npx vitest run extensions/ui/__tests__/rpc.test.ts`; expect PASS.
84 -- [ ] Commit `Add ui rpc bridge`.
86 -###
Task 4: Server snapshot and WebSocket stream 88 -- [ ] Write server tests for authenticated `/api/snapshot`, authenticated WebSocket connect, replay after event id, and 401 on missing token.
89 -- [ ] Implement `server.ts` upgrade handling and snapshot route.
90 -- [ ] Add heartbeat ping/pong and disconnect cleanup.
91 -- [ ] Run `npx vitest run extensions/ui/__tests__/server.test.ts`; expect PASS.
92 -- [ ] Commit `Add ui browser event transport`.
94 -###
Task 5: Browser shell and composer 96 -- [ ] Add `web-smoke.test.ts` that fetches the shell and verifies it contains module script, stream root, composer, and status strip.
97 -- [ ] Implement `web/app.html.ts`, `web/app.css.ts`, and `web/app.js.ts`.
98 -- [ ] Browser JS must fetch snapshot first, then connect WebSocket, then render replayed stream items in id order.
99 -- [ ] Composer submit sends `{ type: "prompt", text }` to server, disables during in-flight RPC, and appends visible pending state.
100 -- [ ] Run `npx vitest run extensions/ui/__tests__/web-smoke.test.ts`; expect PASS.
101 -- [ ] Commit `Add ui basic browser shell`.
103 -###
Task 6: Runtime integration 105 -- [ ] Extend runtime tests to start with fake seed and fake RPC bridge.
106 -- [ ] Modify `runtime.ts` to create event store, seed session, start RPC, publish startup state, and expose snapshot/transport dependencies to server.
107 -- [ ] Modify `index.ts` so `/ui` passes `ctx` into runtime start.
108 -- [ ] Modify terminal widget to show web URL, RPC state, seeded session path basename, and last lifecycle error.
109 -- [ ] Run all UI tests: `npx vitest run extensions/ui/__tests__/*.test.ts`; expect PASS.
110 -- [ ] Commit `Wire ui rpc runtime`.
112 -###
Task 7: Verification 114 -- [ ] Run actual static check: `node --input-type=module -e "import {checkStatic, extDirs} from './scripts/extensions.mjs'; process.exit(checkStatic(extDirs(['ui'])));"`.
115 -- [ ] Run `mise run install` and `mise run check -- ui`.
116 -- [ ] On win32, run the manual smoke with zellij instead of tmux: create a zellij background session, launch `pi -e extensions/ui/index.ts`, send `/ui`, open the browser URL, send one browser prompt, then `/ui off`.
117 -- [ ] On non-win32, tmux remains acceptable for manual smoke.
118 -- [ ] Commit any verification fixes as `Verify ui phase 2 rpc stream`.
122 -- Browser page renders seeded session snapshot and live ordered RPC events.
123 -- Browser prompt submission reaches the RPC Pi session.
124 -- RPC slow startup/death are visible in browser and terminal widget.
125 -- Token auth protects snapshot and WebSocket.
126 -- UI tests, static check, `mise run install`, and `mise run check -- ui` pass.
127 -- Win32 manual terminal smoke uses zellij, not tmux.
1 +#
UI Extension Phase 2 Implementation Plan 3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Make `/ui` a minimal browser Pi frontend backed by a seeded active-branch RPC subprocess.
7 +**Architecture:** Keep Phase 1 server/runtime as owner. Add active-branch session seeding, a Pi RPC child-process bridge, a small event protocol, WebSocket fanout, and a no-framework browser shell that renders snapshots plus ordered events.
9 +**Tech Stack:** Node `child_process`, `fs`, `readline`, `crypto`; Pi `SessionManager`; browser WebSocket, Web Components, CSS; Vitest harness tests.
11 +**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 +**Phase:** Phase 2: Active-Branch RPC Session and Basic Web Stream
21 +- Seed a persistent web session from `ctx.sessionManager.createBranchedSession(ctx.sessionManager.getLeafId())`.
22 +- Spawn `pi --mode rpc --session <seeded-session>` with normal extensions/skills/settings.
23 +- Parse LF-delimited JSONL from RPC stdout and keep stderr diagnostics separate.
24 +- Add RPC request queue with ids, timeout, startup, death, and slow-start states.
25 +- Add `/api/snapshot`, `/ws`, event replay buffer, monotonic event ids, and JSON protocol types.
26 +- Replace Phase 1 shell page with a basic stream-first browser app and composer.
27 +- Send browser prompts through RPC and render user/assistant/tool/error stream items.
31 +- Full slash-command parity.
32 +- Rich syntax/autocomplete.
35 +- Nugu polish beyond readable brutal defaults.
41 +- `extensions/ui/session-seed.ts` — active-branch seed path and warnings.
42 +- `extensions/ui/rpc.ts` — child process, JSONL parser, request queue, lifecycle.
43 +- `extensions/ui/protocol.ts` — event/snapshot/request types.
44 +- `extensions/ui/events.ts` — monotonic event store and replay.
45 +- `extensions/ui/web/app.html.ts` — HTML shell.
46 +- `extensions/ui/web/app.css.ts` — minimal stream-first CSS.
47 +- `extensions/ui/web/app.js.ts` — browser app source emitted by server.
48 +- `extensions/ui/__tests__/session-seed.test.ts`.
49 +- `extensions/ui/__tests__/rpc.test.ts`.
50 +- `extensions/ui/__tests__/events.test.ts`.
51 +- `extensions/ui/__tests__/web-smoke.test.ts`.
55 +- `extensions/ui/runtime.ts` — own seed, RPC, event store.
56 +- `extensions/ui/server.ts` — add snapshot, app assets, WebSocket upgrade.
57 +- `extensions/ui/index.ts` — pass command context into runtime start.
58 +- `extensions/ui/terminal-widget.ts` — show RPC startup/connected/dead states.
59 +- `extensions/ui/package.json` — add `ws` and `@types/ws` if native upgrade handling is not enough.
63 +###
Task 1: Event protocol and store 65 +- [x] Write `events.test.ts` for monotonic ids, bounded replay, and snapshot shape.
66 +- [x] Implement `protocol.ts` and `events.ts` with `UiEvent`, `UiSnapshot`, `EventStore.append`, `EventStore.snapshot`, and `EventStore.replayAfter`.
67 +- [x] Run `npx vitest run extensions/ui/__tests__/events.test.ts`; expect PASS.
68 +- [x] Commit `Add ui event protocol`.
70 +###
Task 2: Active-branch session seed 72 +- [x] Write `session-seed.test.ts` using a fake session manager with `getLeafId()` and `createBranchedSession()`.
73 +- [x] Implement `session-seed.ts` so the default path calls `createBranchedSession(getLeafId())` and returns `{ path, warning: undefined }`.
74 +- [x] Add fallback warning only when whole-tree `forkFrom` is explicitly used by option.
75 +- [x] Run `npx vitest run extensions/ui/__tests__/session-seed.test.ts`; expect PASS.
76 +- [x] Commit `Add ui active branch session seed`.
78 +###
Task 3: RPC bridge 80 +- [x] Write `rpc.test.ts` for JSONL parsing, request id matching, stderr capture, timeout, process exit event, and slow-start event.
81 +- [x] Implement `rpc.ts` with `startRpc`, `sendRpc`, `closeRpc`, `parseJsonLines`, and typed lifecycle callbacks.
82 +- [x] Make subprocess command resolve to `pi.cmd` on win32 and `pi` elsewhere unless `PI_UI_RPC_BIN` overrides it for tests.
83 +- [x] Run `npx vitest run extensions/ui/__tests__/rpc.test.ts`; expect PASS.
84 +- [x] Commit `Add ui rpc bridge`.
86 +###
Task 4: Server snapshot and WebSocket stream 88 +- [x] Write server tests for authenticated `/api/snapshot`, authenticated WebSocket connect, replay after event id, and 401 on missing token.
89 +- [x] Implement `server.ts` upgrade handling and snapshot route.
90 +- [x] Add heartbeat ping/pong and disconnect cleanup.
91 +- [x] Run `npx vitest run extensions/ui/__tests__/server.test.ts`; expect PASS.
92 +- [x] Commit `Add ui browser event transport`.
94 +###
Task 5: Browser shell and composer 96 +- [x] Add `web-smoke.test.ts` that fetches the shell and verifies it contains module script, stream root, composer, and status strip.
97 +- [x] Implement `web/app.html.ts`, `web/app.css.ts`, and `web/app.js.ts`.
98 +- [x] Browser JS must fetch snapshot first, then connect WebSocket, then render replayed stream items in id order.
99 +- [x] Composer submit sends `{ type: "prompt", text }` to server, disables during in-flight RPC, and appends visible pending state.
100 +- [x] Run `npx vitest run extensions/ui/__tests__/web-smoke.test.ts`; expect PASS.
101 +- [x] Commit `Add ui basic browser shell`.
103 +###
Task 6: Runtime integration 105 +- [x] Extend runtime tests to start with fake seed and fake RPC bridge.
106 +- [x] Modify `runtime.ts` to create event store, seed session, start RPC, publish startup state, and expose snapshot/transport dependencies to server.
107 +- [x] Modify `index.ts` so `/ui` passes `ctx` into runtime start.
108 +- [x] Modify terminal widget to show web URL, RPC state, seeded session path basename, and last lifecycle error.
109 +- [x] Run all UI tests: `npx vitest run extensions/ui/__tests__/*.test.ts`; expect PASS.
110 +- [x] Commit `Wire ui rpc runtime`.
112 +###
Task 7: Verification 114 +- [x] Run actual static check: `node --input-type=module -e "import {checkStatic, extDirs} from './scripts/extensions.mjs'; process.exit(checkStatic(extDirs(['ui'])));"`.
115 +- [x] Run `mise run install` and `mise run check -- ui`.
116 +- [x] On win32, run the manual smoke with zellij instead of tmux: create a zellij background session, launch `pi -e extensions/ui/index.ts`, send `/ui`, open the browser URL, send one browser prompt, then `/ui off`.
117 +- [x] On non-win32, tmux remains acceptable for manual smoke.
118 +- [x] Commit any verification fixes as `Verify ui phase 2 rpc stream`.
122 +- Browser page renders seeded session snapshot and live ordered RPC events.
123 +- Browser prompt submission reaches the RPC Pi session.
124 +- RPC slow startup/death are visible in browser and terminal widget.
125 +- Token auth protects snapshot and WebSocket.
126 +- UI tests, static check, `mise run install`, and `mise run check -- ui` pass.
127 +- Win32 manual terminal smoke uses zellij, not tmux.