chore: specs for unimplemented work (#70)

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.