Skip to content

update-api-plan.md

Latest commit

 

History

History
348 lines (319 loc) · 20.9 KB

update-api-plan.md

File metadata and controls

348 lines (319 loc) · 20.9 KB

OpenCode Full Monitor Parity TODO Tracker (API + UI)

Last updated: February 12, 2026

How to use this file

  • Use - [ ] for not started tasks.
  • Change to - [x] when done.
  • For in-progress items, keep - [ ] and append (in progress).
  • Add completion notes in Done Log with date and PR/commit refs.

Planning Work Already Completed

  • Baseline audited across:
    • opencode-research-web @ db0d852923de48800d813625690bcfa92ecb7302
    • anomalyco/opencode @ 8c7b35ad05c9dca5778501b287c5f17ee59dd0a2
    • Dimillian/CodexMonitor @ e67f9bdfd32d22917291e4cc7ddafd6b21f300ab
  • Parity target defined for first-class TUI workflow coverage.
  • Gap matrix and phased delivery plan created.
  • Constraints captured (local-first, autostart, Node runtime for process routes).

Guardrails (Do Not Break)

  • Keep app local-first.
  • Keep automatic OpenCode startup on research requests.
  • Keep runtime = 'nodejs' for process-spawning routes.
  • Preserve env-driven overrides (OPENCODE_COMMAND, OPENCODE_API_URL).
  • Keep current frontend contracts backward-compatible:
    • Query result: id, query, status, sessionId, answer, sources, metadata, timestamp
    • Sessions list: running, host, port, started, count, sessions
    • Session detail: running, host, port, started, session, messages, messageCount, latestMessageAt, activeToolCalls

P0 (Must) - Architecture + Session Workbench

API

  • Add GET /api/opencode/events SSE bridge for /event and /global/event.
  • Support query params on SSE route: scope=instance|global|both, autostart=0|1.
  • Emit normalized events with source tags and monotonic sequence IDs.
  • Extend GET /api/opencode/sessions with passthrough params: roots, start, search, limit.
  • Add optional detail includes on sessions route: include=messages,todo,diff,children.
  • Add GET /api/opencode/session/[sessionId]/timeline.
  • Add GET /api/opencode/session/[sessionId]/transcript with options:
    • thinking
    • toolDetails
    • assistantMetadata

UI

  • Introduce centralized monitor store/reducer with event-application model.
  • Prefer SSE updates with polling fallback.
  • Add event debug panel (recent normalized events + filters).
  • Add timeline drawer with per-message actions:
    • Revert
    • Copy
    • Fork from message
  • Add explicit Undo / Redo controls mapped to revert/unrevert semantics.
  • Add parent/child fork navigation UI.
  • Add session sidebar blocks:
    • Todo
    • Diff summary/details
    • Context/cost usage
  • Add transcript copy/export controls.

P1 (Must) - Composer + Runtime Controls

API

  • Add POST /api/opencode/action typed high-level action endpoint:
    • session
    • message
    • permission
    • question
    • provider
    • mcp
    • project
    • worktree
    • pty
    • global
  • Add schema validation + stable error envelopes to action route.
  • Extend GET /api/opencode/monitor include flags:
    • providers,agents,skills,commands,path,vcs,mcp,lsp,formatter,projects,config,openapi
  • Normalize monitor payload sections for:
    • mcp
    • lsp
    • formatter
    • projects
    • config

UI

  • Replace simple prompt textarea with advanced composer.
  • Add slash command autocomplete.
  • Add mention autocomplete for @file, @agent, MCP resources.
  • Add shell mode + command mode indicators.
  • Add image/file attachments in composer.
  • Add provider connect modal:
    • auth method discovery
    • OAuth authorize/callback
    • API key entry
  • Add model picker grouped by provider.
  • Add model variant selector.
  • Add agent picker and quick-cycle actions.
  • Add MCP panel:
    • status list
    • connect/disconnect
    • auth actions
    • resources preview

P2 (Should) - File/Project/Worktree/Config + Diagnostics

API

  • Add GET /api/opencode/files with modes:
    • findText -> /find
    • findFile -> /find/file
    • list -> /file
    • content -> /file/content
    • status -> /file/status
  • Add GET /api/opencode/system aggregate route for:
    • config
    • global/config
    • project
    • project/current
    • mcp
    • lsp
    • formatter
    • path
    • vcs
  • Extend GET /api/opencode/openapi with route metadata transform for UI form generation.

UI

  • Add file explorer/search/read/status module.
  • Add project list/current/update module.
  • Add worktree create/list/remove/reset module.
  • Add config editor for local + global config with diff/confirm.
  • Improve permission/question UI with richer typed context.
  • Expand status panel for LSP + formatter + plugin/config summaries.

P3 (Could) - PTY Terminal + Command Palette

API

  • Expose PTY lifecycle over HTTP (list/create/update/delete) as short-term baseline.
  • Run implementation spike for PTY websocket proxy feasibility in Next runtime.

UI

  • Add terminal dock with PTY session create/select/remove.
  • Add live PTY stream connection.
  • Add PTY input + resize actions.
  • Add reconnect handling for PTY sessions.
  • Add command palette parity for keyboard-driven operations.

Cross-Cutting Engineering Tasks

  • Build typed backend service adapter module (no scattered direct fetch in components).
  • Add event method-router layer before reducer mutation.
  • Keep optional/additive response fields only (no breaking contract changes).
  • Add compatibility checks when OpenCode API evolves.
  • Keep monitor payload size bounded (include flags + lazy loads).

UI IA Split (Dashboard vs Settings)

  • Add a dedicated /settings route and a clear nav affordance from /.
  • Keep / focused on active research flow:
    • engine/session status
    • composer and prompt execution
    • timeline/transcript/message inspection
    • event debug visibility used during live runs
  • Move advanced/operator panels from / to /settings:
    • theme + color scheme controls
    • provider connect/auth + model/agent controls
    • MCP panel
    • project/worktree/config modules
    • PTY terminal lifecycle/stream controls
    • permission/question queues
    • TUI controls
    • raw API explorer and high-impact session mutation runner
  • Preserve all existing endpoint contracts while relocating UI surfaces.
  • Re-run lint/build and smoke endpoints after route split.

Validation Checklist (Run Per Meaningful Change)

  • npm run lint
  • npm run build -- --webpack
  • Live smoke: GET /api/opencode/status
  • Live smoke: GET /api/opencode/sessions
  • Live smoke: GET /api/opencode/monitor
  • Live smoke: GET /api/opencode/events receives stream events
  • Live smoke: POST /api/query still autostarts OpenCode as needed
  • Verify metadata.opencode.started behavior unchanged
  • Verify session + message visibility in /api/opencode/sessions?sessionId=<id>

Definition of Done (Parity Milestone)

  • Manage sessions end-to-end in web UI:
    • create/select/search/fork/share/rename/archive/delete/undo/redo/summarize
  • Send prompts in normal/command/shell paths with mentions and attachments.
  • Handle permission and question prompts with full context.
  • Manage provider auth, models, agents, and variants.
  • Manage MCP connections/auth/resources.
  • Inspect todos/diffs/messages/timeline and export transcripts.
  • Use file/project/config/worktree workflows.
  • Monitor and operate runtime status with real-time updates.

Done Log

  • 2026-02-12: Added explicit guardrail automation and unified autostart query parsing:
    • Added shared query-flag parser (src/lib/opencode-route-utils.ts) and normalized all API route autostart reads to support 1|true and 0|false
    • Added scripts/check-guardrails.mjs + npm run check:guardrails to enforce key non-negotiables:
      • runtime = 'nodejs' on all src/app/api/**/route.ts handlers
      • local-first host fallback (127.0.0.1) in OpenCode glue
      • env-driven overrides (OPENCODE_API_URL, OPENCODE_COMMAND)
      • query autostart path via runResearchQuery() -> ensureOpenCodeServer()
    • Updated README.md command/verification docs and route query-param docs for consistent autostart=1|true notation
    • Verified with npm run check:guardrails, npm run lint, and npm run build -- --webpack
  • 2026-02-12: Removed legacy forced "research assistant" prompt wrapper from compatibility query flow:
    • buildResearchPrompt() now forwards raw query text only (no fixed 3-findings + sources template injection)
    • Updated docs/metadata wording to align with monitor/control-first app positioning
    • Verified with npm run lint and npm run build -- --webpack
  • 2026-02-12: Improved offline monitor resilience and query-failure transparency:
    • getOpenCodeMonitorSnapshot() now uses safe optional endpoint reads, preventing monitor route failures when OpenCode is offline
    • runResearchQuery() now propagates failure context (sessionId, startup context, elapsed processing time) from partial query flows
    • /api/query failure responses now include metadata.opencode and any available sessionId, preserving compatibility envelope while exposing failure state
    • Upgraded scripts/smoke-opencode-api.mjs to assert query autostart from stopped state and session detail visibility from returned sessionId
    • Verified with npm run lint, npm run build -- --webpack, and npm run smoke:api (query returned HTTP 500 while still passing contract/autostart/session-visibility assertions)
  • 2026-02-12: Hardened compatibility contracts and added repeatable API smoke verification:
    • POST /api/query now returns the legacy compatibility envelope for both success and failure paths (status, sessionId, answer, sources, metadata, timestamp always present)
    • GET /api/opencode/sessions list mode now preserves list-contract keys even on route errors (running, host, port, started, count, sessions) with additive error
    • Added scripts/smoke-opencode-api.mjs and npm run smoke:api to validate status/sessions/monitor/events/query contracts
    • Updated README.md verification docs with the new smoke workflow
    • Verified with npm run lint, npm run build -- --webpack, and npm run smoke:api (query returned HTTP 500 in this environment but contract check passed)
  • 2026-02-12: Improved composer mention handling across prompt/command/shell flows:
    • Added parser/normalizer for @file:, @agent:, and @mcp: mentions in composer text
    • Prompt/command payloads now append structured mention context blocks alongside attachment context
    • Shell mode now strips mentions from command text before dispatch and uses @agent: as fallback shell agent selection
    • Verified with npm run lint and npm run build -- --webpack
  • 2026-02-12: Expanded permission/question queue context handling for safer operator actions:
    • Enhanced permission context extraction to include permission name, patterns, always-allow candidates, metadata summaries, and tool call IDs
    • Enhanced question context extraction to include per-question headers/text/options and tool call IDs
    • Added reply template actions for questions (empty, first options) and used context-based default JSON payloads for reply submission
    • Verified with npm run lint and npm run build -- --webpack
  • 2026-02-12: Added session quick-action controls in dashboard session detail pane:
    • Added focused controls for rename, share, unshare, summarize, archive, and delete alongside existing undo/redo
    • Added session share-link surfacing + copy-link affordance when /session/:id/share returns a URL
    • Reused existing action plumbing and monitor/session refresh behavior to keep payload contracts unchanged
    • Verified with npm run lint and npm run build -- --webpack
  • 2026-02-12: Introduced centralized monitor store/reducer with event-application model:
    • Added src/lib/opencode-monitor/store.ts for reducer-managed monitor/session/event state
    • Refactored src/components/opencode-monitor-shell.tsx to use reducer-backed state transitions
    • Routed SSE lifecycle updates (connecting/ready/error) and debug event appends through reducer actions
    • Verified no contract regressions with npm run lint and npm run build -- --webpack
  • 2026-02-12: Implemented dashboard/settings route split with staged UI relocation:
    • Added shared shell component src/components/opencode-monitor-shell.tsx and route wrappers for / and /settings
    • Added in-app route affordance between Dashboard and Settings views
    • Kept core research loop on / (session monitor, session controls/composer, event stream, file explorer)
    • Moved advanced/admin controls behind settings mode (theme/scheme, runtime/provider, project/worktree/config, MCP, permission/question, TUI, API explorer)
    • Kept API payload contracts unchanged; verified with npm run lint and npm run build -- --webpack
  • 2026-02-12: Audited oversized root UI and documented dashboard vs settings migration boundaries (planning/docs only; no runtime behavior changes in this step).
  • 2026-02-12: Refactored oversized monitor/runtime modules without changing API/UI contracts:
    • Extracted monitor page shared model code into src/lib/opencode-monitor/{types,constants,utils}.ts
    • Slimmed src/app/page.tsx by importing shared monitor symbols/types from src/lib/opencode-monitor-page-shared.ts
    • Split OpenAPI compatibility logic into src/lib/opencode-openapi-compat.ts
    • Split OpenCode data/session parsing utilities into src/lib/opencode-data-utils.ts
    • Verified with npm run lint and npm run build -- --webpack
  • 2026-02-12: Added command palette parity for keyboard-driven operations:
    • Global shortcut Ctrl/Cmd + K opens a searchable command palette modal
    • Keyboard navigation (ArrowUp, ArrowDown, Enter, Escape) and click execution
    • Palette actions wired to monitor/session refresh, composer focus/send/clear, session undo/redo, PTY connect/disconnect/list refresh, and TUI shortcuts/command execution
  • 2026-02-12: Completed PTY terminal streaming parity slice in Terminal Dock:
    • Added direct browser websocket stream connection to OpenCode /pty/:ptyID/connect using status-derived apiUrl (with host/port fallback)
    • Added live output panel with cursor tracking and bounded buffer
    • Added PTY input send/send-line actions over websocket
    • Added PTY resize action wiring (size.cols / size.rows) via PTY update endpoint
    • Added reconnect handling with backoff, auto-connect/auto-reconnect toggles, and reconnect attempt indicators
    • Added additive status payload field apiUrl in getOpenCodeStatus() to support env override-safe websocket targeting
  • 2026-02-12: Added typed client backend adapter module (src/lib/opencode-api-client.ts) and refactored src/app/page.tsx to route API calls through the adapter (no direct component fetch calls remain).
  • 2026-02-12: Added an explicit event refresh method-router (resolveEventRefreshScope) so SSE event envelopes route to monitor-only vs monitor+session refresh paths before state updates/timer scheduling.
  • 2026-02-12: Added dedicated PTY lifecycle API routes:
    • GET|POST /api/opencode/pty for list/create
    • PATCH|DELETE /api/opencode/pty/:ptyId for update/delete
    • Updated README route docs and key-files list for PTY baseline coverage
  • 2026-02-12: Added a Terminal Dock UI panel for PTY session create/select/remove workflows:
    • Uses /api/opencode/pty and /api/opencode/pty/:ptyId routes via typed client adapter
    • Includes PTY session list/selection, create/update/delete payload actions, and response inspectors
  • 2026-02-12: Added OpenCode API compatibility checks against live OpenAPI snapshots:
    • Added additive monitor include flag compatibility
    • Added compatibility report generation (required/recommended endpoint+method checks) in src/lib/opencode.ts
    • Surfaced compatibility status/report in Engine Snapshot UI and updated README monitor docs
  • 2026-02-12: Added PTY websocket feasibility spike route:
    • GET /api/opencode/pty/:ptyId/connect probes upstream connect endpoint and reports feasibility diagnostics
    • Documents that transparent websocket upgrade proxying is not provided by the current Next route-handler path
  • 2026-02-12: Added bounded monitor queue limits for payload control:
    • Added additive monitor query params permissionLimit and questionLimit (default 80 each)
    • Wired limits through API route, backend snapshot builder, and typed client adapter
    • Updated README monitor query parameter documentation
  • 2026-02-11: Converted this document from narrative plan to checklist-style tracker.
  • 2026-02-11: Completed initial P0 API backend slice:
    • /api/opencode/events SSE bridge (scope, autostart, source-tagged normalized events with seq)
    • /api/opencode/sessions passthrough filters + detail includes (todo, diff, children)
    • /api/opencode/session/[sessionId]/timeline
    • /api/opencode/session/[sessionId]/transcript
    • Updated README API docs for these routes and query params
  • 2026-02-11: Completed major P0 session workbench UI slice:
    • SSE-first refresh strategy with polling fallback and reconnection
    • Event debug panel with source filtering and recent normalized event log
    • Timeline panel with per-message revert / copy / fork actions
    • Explicit session undo / redo controls
    • Parent/child navigation chips in session detail
    • Sidebar summaries for todo, diff, and context/cost status
    • Transcript copy/export controls backed by transcript API
  • 2026-02-11: Completed core P1 API control and monitor expansion:
    • Added typed POST /api/opencode/action for session/message/permission/question/provider/mcp/project/worktree/pty/global actions
    • Added stable validation and action-resolution error envelopes
    • Extended GET /api/opencode/monitor with include= flags
    • Added normalized optional monitor blocks for mcp, lsp, formatter, projects, and config
  • 2026-02-11: Completed first P1 composer UI parity slice:
    • Replaced basic prompt box with a mode-aware advanced composer (prompt, async, command, shell)
    • Added slash command autocomplete for fast mode switching (/prompt, /async, /command, /shell)
    • Added mention autocomplete for @file, @agent, and @mcp resource references
    • Added explicit command/shell mode indicators and shell agent selection
    • Added file/image attachments with compact inline context packaging for prompt/command dispatch
  • 2026-02-11: Stabilized verification baseline:
    • Excluded /reference mirror repositories from app lint/type-check scope (eslint + tsconfig)
    • Restored green checks for npm run lint and npm run build -- --webpack
  • 2026-02-11: Completed second P1 runtime control UI slice:
    • Added provider connect modal with auth method discovery, OAuth authorize/callback, and API key submission
    • Added provider-grouped model picker + model variant selector with session init apply action
    • Added agent picker with local cycle, TUI cycle, and quick apply to shell composer mode
    • Added MCP control panel with status, connect/disconnect/auth actions, and resource previews
  • 2026-02-11: Added /api/opencode/files mode-based passthrough route:
    • Supports findText, findFile, list, content, and status modes
    • Forwards additional query params to mapped OpenCode endpoints
  • 2026-02-11: Added /api/opencode/system aggregate route:
    • Supports additive include= selection across config/project/mcp/lsp/formatter/path/vcs snapshots
    • Returns per-section invocation result envelopes and aggregated errors
  • 2026-02-11: Extended /api/opencode/openapi with form metadata transform:
    • Adds additive routeMetadata entries (path params, query hints, per-method body requirement/templates)
    • Adds additive metadata envelope for generated timestamp and route metadata count
  • 2026-02-11: Added file explorer/search/read/status UI module:
    • New File Explorer panel in dashboard backed by /api/opencode/files
    • Supports findText, findFile, list, content, and status with optional extra query params
  • 2026-02-11: Added project list/current/update UI module:
    • New Project Module panel backed by /api/opencode/system?include=project,project/current
    • Supports prefilled JSON updates to POST /project/current and live snapshot refresh
  • 2026-02-11: Added worktree create/list/remove/reset UI module:
    • New Worktree Module panel backed by /experimental/worktree and /experimental/worktree/reset
    • Supports create/remove/reset JSON payloads and live list refresh
  • 2026-02-11: Added local/global config editor UI module:
    • New Config Editor panel with local and global JSON drafts
    • Includes line-change diff indicators and explicit confirm-before-apply flow
  • 2026-02-11: Improved permission/question and runtime status diagnostics:
    • Added typed context summaries in permission/question queues (session/tool/command/prompt/options hints)
    • Expanded engine snapshot with LSP, formatter, and config/plugin summary tiles