From f0912c333cee64a3cc92e63394953ad0787c0182 Mon Sep 17 00:00:00 2001 From: Nathan Flurry Date: Wed, 4 Feb 2026 13:42:09 -0800 Subject: [PATCH] chore: specs for unimplemented work --- research/specs/command-shell-exec.md | 23 ++++++++++++++ research/specs/event-stream-parity.md | 23 ++++++++++++++ research/specs/filesystem-integration.md | 25 +++++++++++++++ research/specs/formatter-lsp.md | 21 +++++++++++++ research/specs/mcp-integration.md | 31 +++++++++++++++++++ research/specs/project-worktree.md | 27 ++++++++++++++++ research/specs/provider-auth.md | 26 ++++++++++++++++ research/specs/pty-management.md | 28 +++++++++++++++++ research/specs/search-symbol-indexing.md | 23 ++++++++++++++ research/specs/session-persistence.md | 39 ++++++++++++++++++++++++ research/specs/summarize-todo.md | 21 +++++++++++++ research/specs/toolcall-file-actions.md | 23 ++++++++++++++ research/specs/tui-control-flow.md | 32 +++++++++++++++++++ research/specs/vcs-integration.md | 25 +++++++++++++++ 14 files changed, 367 insertions(+) create mode 100644 research/specs/command-shell-exec.md create mode 100644 research/specs/event-stream-parity.md create mode 100644 research/specs/filesystem-integration.md create mode 100644 research/specs/formatter-lsp.md create mode 100644 research/specs/mcp-integration.md create mode 100644 research/specs/project-worktree.md create mode 100644 research/specs/provider-auth.md create mode 100644 research/specs/pty-management.md create mode 100644 research/specs/search-symbol-indexing.md create mode 100644 research/specs/session-persistence.md create mode 100644 research/specs/summarize-todo.md create mode 100644 research/specs/toolcall-file-actions.md create mode 100644 research/specs/tui-control-flow.md create mode 100644 research/specs/vcs-integration.md diff --git a/research/specs/command-shell-exec.md b/research/specs/command-shell-exec.md new file mode 100644 index 0000000..6980123 --- /dev/null +++ b/research/specs/command-shell-exec.md @@ -0,0 +1,23 @@ +# Spec: Command + Shell Execution + +**Proposed API Changes** +- Add command execution APIs to the core session manager (non-PTY, single-shot). +- Define output capture and error handling semantics in the session event stream. + +**Summary** +OpenCode routes for command/shell execution should run real commands in the session context and stream outputs to OpenCode message parts and events. + +**OpenCode Endpoints (Reference)** +- `GET /opencode/command` +- `POST /opencode/session/{sessionID}/command` +- `POST /opencode/session/{sessionID}/shell` + +**Core Functionality Required** +- Execute commands with cwd/env + timeout support. +- Capture stdout/stderr, exit code, and duration. +- Optional streaming output to session events. +- Map command output into OpenCode `message.part.updated` events. + +**OpenCode Compat Wiring + Tests** +- Replace stubs for `/command`, `/session/{sessionID}/command`, `/session/{sessionID}/shell`. +- Add E2E tests to run a simple command and validate output is returned and events are emitted. diff --git a/research/specs/event-stream-parity.md b/research/specs/event-stream-parity.md new file mode 100644 index 0000000..3532e02 --- /dev/null +++ b/research/specs/event-stream-parity.md @@ -0,0 +1,23 @@ +# Spec: Event Stream Parity + +**Proposed API Changes** +- Ensure all core session manager events map to OpenCode’s expected event types and sequencing. +- Provide structured, ordered event delivery with backpressure handling. + +**Summary** +OpenCode relies on SSE event streams for UI state. We need full parity in event ordering, types, and payloads, not just message/part events. + +**OpenCode Endpoints (Reference)** +- `GET /opencode/event` +- `GET /opencode/global/event` + +**Core Functionality Required** +- Deterministic event ordering and replay by offset. +- Explicit `session.status` transitions (busy/idle/error). +- `message.updated` and `message.part.updated` with full payloads. +- Permission and question events with full metadata. +- Error events with structured details. + +**OpenCode Compat Wiring + Tests** +- Replace partial event emission with full parity for all supported events. +- Add E2E tests that validate event ordering and type coverage in SSE streams. diff --git a/research/specs/filesystem-integration.md b/research/specs/filesystem-integration.md new file mode 100644 index 0000000..a9e3b38 --- /dev/null +++ b/research/specs/filesystem-integration.md @@ -0,0 +1,25 @@ +# Spec: Filesystem Integration + +**Proposed API Changes** +- Add a workspace filesystem service to the core session manager with path scoping and traversal protection. +- Expose file list/content/status APIs via the core service for reuse in OpenCode compat. + +**Summary** +Provide safe, read-oriented filesystem access needed by OpenCode for file listing, content retrieval, and status details within a session directory. + +**OpenCode Endpoints (Reference)** +- `GET /opencode/file` +- `GET /opencode/file/content` +- `GET /opencode/file/status` +- `GET /opencode/path` + +**Core Functionality Required** +- Path normalization and sandboxed root enforcement per session/project. +- File listing with filters (directory, glob, depth, hidden). +- File content retrieval with mime detection and optional range. +- File status (exists, type, size, last modified; optionally VCS status). +- Optional file tree caching for performance. + +**OpenCode Compat Wiring + Tests** +- Replace stubs for `/file`, `/file/content`, `/file/status`, and `/path`. +- Add E2E tests for reading content, listing directories, and invalid path handling. diff --git a/research/specs/formatter-lsp.md b/research/specs/formatter-lsp.md new file mode 100644 index 0000000..4ac3572 --- /dev/null +++ b/research/specs/formatter-lsp.md @@ -0,0 +1,21 @@ +# Spec: Formatter + LSP Integration + +**Proposed API Changes** +- Add a formatter service and LSP status registry to the core session manager. +- Provide per-language formatter availability and LSP server status. + +**Summary** +OpenCode surfaces formatter and LSP availability via dedicated endpoints. We need real integration (or at minimum, real status introspection). + +**OpenCode Endpoints (Reference)** +- `GET /opencode/formatter` +- `GET /opencode/lsp` + +**Core Functionality Required** +- Discover available formatters by language in the workspace. +- Track LSP server status (running, capabilities). +- Optional API to trigger formatting for a file (future extension). + +**OpenCode Compat Wiring + Tests** +- Replace stubs for `/formatter` and `/lsp`. +- Add E2E tests that validate formatter/LSP presence for fixture languages. diff --git a/research/specs/mcp-integration.md b/research/specs/mcp-integration.md new file mode 100644 index 0000000..fd45241 --- /dev/null +++ b/research/specs/mcp-integration.md @@ -0,0 +1,31 @@ +# Spec: MCP Integration + +**Proposed API Changes** +- Add an MCP server registry to the core session manager. +- Support MCP auth lifecycle and connect/disconnect operations. +- Expose tool discovery metadata for OpenCode tooling. + +**Summary** +OpenCode expects MCP server registration, authentication, and connectivity endpoints, plus tool discovery for those servers. + +**OpenCode Endpoints (Reference)** +- `GET /opencode/mcp` +- `POST /opencode/mcp` +- `POST /opencode/mcp/{name}/auth` +- `DELETE /opencode/mcp/{name}/auth` +- `POST /opencode/mcp/{name}/auth/callback` +- `POST /opencode/mcp/{name}/auth/authenticate` +- `POST /opencode/mcp/{name}/connect` +- `POST /opencode/mcp/{name}/disconnect` +- `GET /opencode/experimental/tool` +- `GET /opencode/experimental/tool/ids` + +**Core Functionality Required** +- Register MCP servers with config (url, transport, auth type). +- Auth flows (token exchange, callback handling). +- Connect/disconnect lifecycle and health. +- Tool listing and tool ID exposure for connected servers. + +**OpenCode Compat Wiring + Tests** +- Replace stubs for `/mcp*` and `/experimental/tool*`. +- Add E2E tests using a real MCP test server to validate auth + tool list flows. diff --git a/research/specs/project-worktree.md b/research/specs/project-worktree.md new file mode 100644 index 0000000..87d2d84 --- /dev/null +++ b/research/specs/project-worktree.md @@ -0,0 +1,27 @@ +# Spec: Project + Worktree Model + +**Proposed API Changes** +- Add a project/worktree manager to the core session manager. +- Expose project metadata and active worktree operations (create/list/reset/delete). + +**Summary** +OpenCode relies on project and worktree endpoints for context and repo operations. We need a real project model backed by the workspace and VCS. + +**OpenCode Endpoints (Reference)** +- `GET /opencode/project` +- `GET /opencode/project/current` +- `PATCH /opencode/project/{projectID}` +- `GET /opencode/experimental/worktree` +- `POST /opencode/experimental/worktree` +- `DELETE /opencode/experimental/worktree` +- `POST /opencode/experimental/worktree/reset` + +**Core Functionality Required** +- Project identity and metadata (id, title, directory, branch). +- Current project derivation by directory/session. +- Worktree creation/reset/delete tied to VCS. +- Return consistent IDs and location data. + +**OpenCode Compat Wiring + Tests** +- Replace stubs for `/project`, `/project/current`, `/project/{projectID}`, and `/experimental/worktree*` endpoints. +- Add E2E tests for worktree lifecycle and project metadata correctness. diff --git a/research/specs/provider-auth.md b/research/specs/provider-auth.md new file mode 100644 index 0000000..1ab638d --- /dev/null +++ b/research/specs/provider-auth.md @@ -0,0 +1,26 @@ +# Spec: Provider Auth Lifecycle + +**Proposed API Changes** +- Add provider credential management to the core session manager (integrated with existing credentials store). +- Expose OAuth and direct credential set/remove operations. + +**Summary** +OpenCode expects provider auth and OAuth endpoints. We need a real provider registry and credential storage that ties to agent configuration. + +**OpenCode Endpoints (Reference)** +- `GET /opencode/provider` +- `GET /opencode/provider/auth` +- `POST /opencode/provider/{providerID}/oauth/authorize` +- `POST /opencode/provider/{providerID}/oauth/callback` +- `PUT /opencode/auth/{providerID}` +- `DELETE /opencode/auth/{providerID}` + +**Core Functionality Required** +- Provider registry with models, capabilities, and connection state. +- OAuth initiation/callback handling with credential storage. +- Direct credential setting/removal. +- Mapping to agent manager credentials and environment. + +**OpenCode Compat Wiring + Tests** +- Replace stubs for `/provider`, `/provider/auth`, `/provider/{providerID}/oauth/*`, `/auth/{providerID}`. +- Add E2E tests for credential set/remove and provider list reflecting auth state. diff --git a/research/specs/pty-management.md b/research/specs/pty-management.md new file mode 100644 index 0000000..06aa62a --- /dev/null +++ b/research/specs/pty-management.md @@ -0,0 +1,28 @@ +# Spec: PTY Management + +**Proposed API Changes** +- Add a PTY manager to the core session manager to spawn, track, and stream terminal processes. +- Define a PTY IO channel for OpenCode connect operations (SSE or websocket). + +**Summary** +OpenCode expects a PTY lifecycle API with live IO. We need real PTY creation and streaming output/input handling. + +**OpenCode Endpoints (Reference)** +- `GET /opencode/pty` +- `POST /opencode/pty` +- `GET /opencode/pty/{ptyID}` +- `PUT /opencode/pty/{ptyID}` +- `DELETE /opencode/pty/{ptyID}` +- `GET /opencode/pty/{ptyID}/connect` + +**Core Functionality Required** +- Spawn PTY processes with configurable cwd/args/title/env. +- Track PTY state (running/exited), pid, exit code. +- Streaming output channel with backpressure handling. +- Input write support with safe buffering. +- Cleanup on session termination. + +**OpenCode Compat Wiring + Tests** +- Replace stubs for `/pty` and `/pty/{ptyID}` endpoints. +- Implement `/pty/{ptyID}/connect` streaming with real PTY IO. +- Add E2E tests for PTY spawn, output capture, and input echo. diff --git a/research/specs/search-symbol-indexing.md b/research/specs/search-symbol-indexing.md new file mode 100644 index 0000000..715e61d --- /dev/null +++ b/research/specs/search-symbol-indexing.md @@ -0,0 +1,23 @@ +# Spec: Search + Symbol Indexing + +**Proposed API Changes** +- Add a search/indexing service to the core session manager (ripgrep-backed initially). +- Expose APIs for text search, file search, and symbol search. + +**Summary** +OpenCode expects fast search endpoints for files, text, and symbols within a workspace. These must be safe and scoped. + +**OpenCode Endpoints (Reference)** +- `GET /opencode/find` +- `GET /opencode/find/file` +- `GET /opencode/find/symbol` + +**Core Functionality Required** +- Text search with pattern, case sensitivity, and result limits. +- File search with glob/substring match. +- Symbol indexing (language server or ctags-backed), with caching and incremental updates. +- Proper path scoping and escaping. + +**OpenCode Compat Wiring + Tests** +- Replace stubs for `/find`, `/find/file`, `/find/symbol`. +- Add E2E tests with a fixture repo verifying search hits. diff --git a/research/specs/session-persistence.md b/research/specs/session-persistence.md new file mode 100644 index 0000000..a8ca6ee --- /dev/null +++ b/research/specs/session-persistence.md @@ -0,0 +1,39 @@ +# Spec: Session Persistence & Metadata + +**Proposed API Changes** +- Add a persistent session store to the core session manager (pluggable backend, default on-disk). +- Expose session metadata fields in the core API: `title`, `parent_id`, `project_id`, `directory`, `version`, `share_url`, `created_at`, `updated_at`, `status`. +- Add session list/get/update/delete/fork/share/todo/diff/revert/unrevert/abort/init operations to the core API. + +**Summary** +Bring the core session manager to feature parity with OpenCode’s session metadata model. Sessions must be durable, queryable, and updatable, and must remain consistent with message history and event streams. + +**OpenCode Endpoints (Reference)** +- `GET /opencode/session` +- `POST /opencode/session` +- `GET /opencode/session/{sessionID}` +- `PATCH /opencode/session/{sessionID}` +- `DELETE /opencode/session/{sessionID}` +- `GET /opencode/session/status` +- `GET /opencode/session/{sessionID}/children` +- `POST /opencode/session/{sessionID}/fork` +- `POST /opencode/session/{sessionID}/share` +- `DELETE /opencode/session/{sessionID}/share` +- `GET /opencode/session/{sessionID}/todo` +- `GET /opencode/session/{sessionID}/diff` +- `POST /opencode/session/{sessionID}/revert` +- `POST /opencode/session/{sessionID}/unrevert` +- `POST /opencode/session/{sessionID}/abort` +- `POST /opencode/session/{sessionID}/init` + +**Core Functionality Required** +- Persistent storage for sessions and metadata (including parent/child relationships). +- Session status tracking (idle/busy/error) with timestamps. +- Share URL lifecycle (create/revoke). +- Forking semantics that clone metadata and link parent/child. +- Revert/unrevert bookkeeping tied to VCS snapshots (see VCS spec). +- Consistent ordering and deterministic IDs across restarts. + +**OpenCode Compat Wiring + Tests** +- Replace stubs for: `/session` (GET/POST), `/session/{sessionID}` (GET/PATCH/DELETE), `/session/status`, `/session/{sessionID}/children`, `/session/{sessionID}/fork`, `/session/{sessionID}/share` (POST/DELETE), `/session/{sessionID}/todo`, `/session/{sessionID}/diff`, `/session/{sessionID}/revert`, `/session/{sessionID}/unrevert`, `/session/{sessionID}/abort`, `/session/{sessionID}/init`. +- Extend opencode-compat E2E tests to verify persistence across server restarts and correct metadata updates. diff --git a/research/specs/summarize-todo.md b/research/specs/summarize-todo.md new file mode 100644 index 0000000..04defea --- /dev/null +++ b/research/specs/summarize-todo.md @@ -0,0 +1,21 @@ +# Spec: Session Summarization + Todo + +**Proposed API Changes** +- Add summarization and todo generation to the core session manager. +- Store summaries/todos as session artifacts with versioning. + +**Summary** +OpenCode expects session summarize and todo endpoints backed by actual model output. + +**OpenCode Endpoints (Reference)** +- `POST /opencode/session/{sessionID}/summarize` +- `GET /opencode/session/{sessionID}/todo` + +**Core Functionality Required** +- Generate a summary using the selected model/provider. +- Store and return the latest summary (and optionally history). +- Generate and store todo items derived from session activity. + +**OpenCode Compat Wiring + Tests** +- Replace stubs for `/session/{sessionID}/summarize` and `/session/{sessionID}/todo`. +- Add E2E tests validating summary content and todo list structure. diff --git a/research/specs/toolcall-file-actions.md b/research/specs/toolcall-file-actions.md new file mode 100644 index 0000000..84c677f --- /dev/null +++ b/research/specs/toolcall-file-actions.md @@ -0,0 +1,23 @@ +# Spec: Tool Calls + File Actions (Session Manager) + +**Proposed API Changes** +- Add tool call lifecycle tracking in the core session manager (call started, delta, completed, result). +- Add file action integration (write/patch/rename/delete) with audited events. + +**Summary** +OpenCode expects tool calls and file actions to surface through message parts and events. The core session manager must track tool call lifecycles and file actions reliably. + +**OpenCode Endpoints (Reference)** +- `GET /opencode/event` +- `GET /opencode/global/event` +- `POST /opencode/session/{sessionID}/message` + +**Core Functionality Required** +- Explicit tool call tracking with call IDs, arguments, outputs, timing, and status. +- File action execution (write/patch/rename/delete) with safe path scoping. +- Emission of file edit events tied to actual writes. +- Mapping tool call and file action data into universal events for conversion. + +**OpenCode Compat Wiring + Tests** +- Replace stubbed tool/file part generation with real data sourced from session manager tool/file APIs. +- Add E2E tests to validate tool call lifecycle events and file edit events. diff --git a/research/specs/tui-control-flow.md b/research/specs/tui-control-flow.md new file mode 100644 index 0000000..368018a --- /dev/null +++ b/research/specs/tui-control-flow.md @@ -0,0 +1,32 @@ +# Spec: TUI Control Flow + +**Proposed API Changes** +- Add a TUI control queue and state machine to the core session manager. +- Expose request/response transport for OpenCode TUI controls. + +**Summary** +OpenCode’s TUI endpoints allow a remote controller to drive the UI. We need a server-side queue for control messages and a way to emit responses. + +**OpenCode Endpoints (Reference)** +- `GET /opencode/tui/control/next` +- `POST /opencode/tui/control/response` +- `POST /opencode/tui/append-prompt` +- `POST /opencode/tui/clear-prompt` +- `POST /opencode/tui/execute-command` +- `POST /opencode/tui/open-help` +- `POST /opencode/tui/open-models` +- `POST /opencode/tui/open-sessions` +- `POST /opencode/tui/open-themes` +- `POST /opencode/tui/publish` +- `POST /opencode/tui/select-session` +- `POST /opencode/tui/show-toast` +- `POST /opencode/tui/submit-prompt` + +**Core Functionality Required** +- Persistent queue of pending UI control actions. +- Response correlation (request/response IDs). +- Optional integration with session events for UI feedback. + +**OpenCode Compat Wiring + Tests** +- Replace stubs for all `/tui/*` endpoints. +- Add E2E tests for control queue ordering and response handling. diff --git a/research/specs/vcs-integration.md b/research/specs/vcs-integration.md new file mode 100644 index 0000000..fbbcacb --- /dev/null +++ b/research/specs/vcs-integration.md @@ -0,0 +1,25 @@ +# Spec: VCS Integration + +**Proposed API Changes** +- Add a VCS service to the core session manager (Git-first) with status, diff, branch, and revert operations. +- Expose APIs for session-level diff and revert/unrevert semantics. + +**Summary** +Enable OpenCode endpoints that depend on repository state, diffs, and revert flows. + +**OpenCode Endpoints (Reference)** +- `GET /opencode/vcs` +- `GET /opencode/session/{sessionID}/diff` +- `POST /opencode/session/{sessionID}/revert` +- `POST /opencode/session/{sessionID}/unrevert` + +**Core Functionality Required** +- Repo discovery from session directory (with safe fallback). +- Status summary (branch, dirty files, ahead/behind). +- Diff generation (staged/unstaged, per file and full). +- Revert/unrevert mechanics with temporary snapshots or stashes. +- Integration with file status endpoint when available. + +**OpenCode Compat Wiring + Tests** +- Replace stubs for `/vcs`, `/session/{sessionID}/diff`, `/session/{sessionID}/revert`, `/session/{sessionID}/unrevert`. +- Add E2E tests that modify a fixture repo and validate diff + revert flows.