OpenCode Agent
01a0ef46c9
- Add startup_command field to ToolType model and API - Execute startup command before interactive shell in terminal sessions - Add tmux and ranger to OpenCode container spec - Update Tool Workshop UI with startup_command input for terminal types - Add backend tests for startup_command CRUD operations - Sync specs: tool-terminal, tool-types-definition, opencode-web-server - New spec: tool-terminal-startup-command Quality gates: Frontend typecheck/lint passed. Backend tests blocked by environment (Python/Docker not available). OpenSpec: terminal-startup-and-container-tools
96 lines
2.7 KiB
Markdown
96 lines
2.7 KiB
Markdown
# Web Terminal Specification
|
|
|
|
## Purpose
|
|
|
|
Provide browser-based terminal access to running tool containers.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: WebSocket Terminal
|
|
|
|
The system SHALL provide terminal sessions via WebSocket.
|
|
|
|
#### Scenario: Open terminal
|
|
- GIVEN a running tool instance
|
|
- WHEN the user opens the terminal
|
|
- THEN a WebSocket connection is established
|
|
- AND a shell is spawned in the container via `docker exec`
|
|
|
|
#### Scenario: Open terminal with startup command
|
|
- GIVEN a running tool instance with a tool type that has `startup_command` set
|
|
- WHEN the user opens the terminal
|
|
- THEN a WebSocket connection is established
|
|
- AND the startup command is executed before the interactive shell
|
|
- AND the shell is spawned in the container via `docker exec`
|
|
|
|
#### Scenario: Open terminal without startup command
|
|
- GIVEN a running tool instance with a tool type that has no `startup_command`
|
|
- WHEN the user opens the terminal
|
|
- THEN a WebSocket connection is established
|
|
- AND the shell spawns directly without any startup execution
|
|
|
|
### Requirement: Terminal I/O
|
|
|
|
The system SHALL stream terminal I/O via WebSocket.
|
|
|
|
#### Scenario: Command execution
|
|
- GIVEN an active terminal session
|
|
- WHEN the user types a command
|
|
- THEN stdin is forwarded to the container shell
|
|
- AND stdout/stderr is streamed back to the browser
|
|
|
|
### Requirement: Terminal Resize
|
|
|
|
The system SHALL support terminal resize events.
|
|
|
|
#### Scenario: Resize terminal
|
|
- GIVEN an active terminal session
|
|
- WHEN the browser window is resized
|
|
- THEN the terminal dimensions (COLS, ROWS) are updated
|
|
- AND the shell receives the new size
|
|
|
|
### Requirement: Session Management
|
|
|
|
The system SHALL manage terminal sessions.
|
|
|
|
#### Scenario: Multiple sessions
|
|
- GIVEN a running tool instance
|
|
- WHEN multiple terminals are opened
|
|
- THEN each has an independent session
|
|
|
|
#### Scenario: Cleanup
|
|
- GIVEN an active terminal session
|
|
- WHEN the user disconnects
|
|
- THEN the session is cleaned up
|
|
- AND the shell process is terminated
|
|
|
|
#### Scenario: Reset terminal session runs startup command
|
|
- GIVEN an active terminal session
|
|
- WHEN the user resets the session
|
|
- THEN a new shell is spawned
|
|
- AND the startup command executes before the new interactive shell
|
|
|
|
### Requirement: Access Control
|
|
|
|
The system SHALL restrict terminal access.
|
|
|
|
#### Scenario: Unauthorized access
|
|
- GIVEN a tool instance owned by user A
|
|
- WHEN user B tries to access the terminal
|
|
- THEN the connection is rejected with 403
|
|
|
|
## Dependencies
|
|
|
|
- tool-instances (running containers)
|
|
- auth-oauth (authentication)
|
|
- xterm.js frontend library
|
|
- ptyprocess for pseudo-TTY
|
|
|
|
## Quality Gates
|
|
|
|
- `pytest` must pass
|
|
- `mypy .` must pass
|
|
- `ruff check .` must pass
|
|
- `npm run typecheck` must pass
|
|
- `npm run lint` must pass
|