Files

T

OpenCode Agent 01a0ef46c9 feat: terminal startup command and container tools

- 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

2026-05-24 22:21:55 +00:00

2.7 KiB

Raw Blame History

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

2.7 KiB Raw Blame History