Thinking Path

Hermes WebUI needs a power-user path for running quick workspace commands without leaving the active conversation. The feature is useful only if it preserves the chat workflow instead of turning the composer into a crowded control strip.

This PR originally explored a composer-adjacent terminal. After Aron’s Discord feedback and the UI/UX philosophy doc, the implementation pivoted:

• no permanent terminal icon in the composer primary row
• /terminal is the V1 entry point
• the terminal renders as a separate conversation-pane utility window, visually similar to the approval-card layer
• the card can expand, collapse into a dock, or close completely
• terminal output stays outside chat history and model context by default

UI/UX Alignment

This follows the direction in Aron’s UI/UX philosophy:

• Keep primary surfaces quiet: the title bar, sidebar session rows, message lines, and composer row do not get another always-visible control.
• Use progressive disclosure: /terminal keeps the feature reachable without making every user see it all the time.
• Show detail where detail belongs: terminal output lives in a dedicated workspace utility surface, not as transcript content.
• Separate concerns: the terminal is neither an assistant message nor a composer footer extension. It is a conversation-pane utility window that sits near the composer because it supports the current conversation’s workspace.
• Preserve mobile/narrow-surface discipline: V1 avoids adding another small unlabeled icon to the crowded composer row.

Alternatives considered and rejected:

• Permanent composer toolbar button: too much pressure on an already crowded primary surface.
• Full panel below the composer: visually reads as a composer attachment and weakens separation of concerns.
• Transcript message/card: misleading, because terminal output is not conversation history.
• Topbar/sidebar entry: potentially valid later, but broader than V1 and not clearly session/workspace scoped.

What Changed

• Adds a /terminal slash command that opens the workspace terminal.
• Adds backend PTY endpoints for terminal lifecycle:
  • start
  • input
  • output streaming
  • resize
  • close
• Adds an xterm.js-powered frontend terminal surface.
• Opens the shell in the active session workspace through the trusted workspace resolution path.
• Adds terminal actions:
  • Clear
  • Copy output
  • Restart
  • Collapse
  • Expand
  • Close
• Adds a collapsed dock state so users can keep a running terminal without leaving the full terminal window open.
• Adds bounded desktop resizing for the expanded terminal card.
• Reserves transcript/composer space so the terminal does not cover the latest assistant response during command/chat alternation.
• Keeps terminal output independent from chat history. V1 does not auto-send output to the composer or transcript.
• Adds theme and locale coverage for the new terminal UI.
• Adds service-worker coverage for the new terminal module.

Visual Validation Notes

The latest local visual pass covered these states:

1. Slash-command entry: typing /te shows /terminal as a command option without adding a permanent composer icon.
2. Expanded terminal: the terminal appears as a narrower conversation-pane utility window, slightly behind/above the composer, with Clear / Copy output / Restart / Collapse / Close actions.
3. Command output: commands such as ls and pwd render inside the xterm surface with readable dark-theme output.
4. Collapsed dock: the terminal can collapse into a compact dock attached above the composer, with explicit Expand and Close actions.

Why It Matters

• Power users can run quick workspace commands without switching to an external terminal and manually cd-ing into the active workspace.
• The terminal stays tied to the current conversation workspace, which makes the selected workspace more actionable.
• The UI remains restrained: the feature is available on demand, not permanently visible.
• The transcript remains clean because shell output is not automatically inserted into model context.

Technical Notes

• The backend uses a per-session PTY process instead of subprocess.run, so prompts, ANSI output, interactive programs, and resize behavior work like a real shell.
• Terminal environment setup is per process and does not mutate global os.environ.
• Output streams over SSE and is written into xterm on the frontend.
• Restart ignores stale output events from the previous terminal instance.
• Close releases the PTY. Collapse only hides the expanded surface and keeps the terminal available.
• The frontend refits xterm after open, resize, collapse/expand, and theme changes.
• xterm assets remain pinned CDN assets with SRI, matching the app’s no-build-step architecture.

Verification

Passed:

node --check static/terminal.js static/i18n.js static/commands.js static/ui.js static/messages.js static/workspace.js static/sessions.js static/panels.js static/boot.js
pytest -q tests/test_embedded_workspace_terminal.py tests/test_approval_card_layering.py tests/test_workspace_panel_session_list.py tests/test_mobile_layout.py tests/test_chinese_locale.py::test_chinese_locale_covers_english_keys tests/test_korean_locale.py::test_korean_locale_matches_english_key_coverage tests/test_russian_locale.py::test_russian_locale_covers_english_keys tests/test_spanish_locale.py::test_spanish_locale_covers_english_keys
git diff --check origin/master...HEAD

Result:

60 passed

Additional verification already performed during the PR iteration:

• focused terminal and approval-card tests passed
• locale key coverage failures introduced by the terminal strings were fixed
• local browser/manual validation covered open, command execution, collapse, expand, resize, and close
• user visual testing confirmed the final expanded and collapsed states behave as expected

Full-suite note:

• The documented pytest tests/ -v --timeout=60 command could not run in this local environment because the pytest-timeout plugin is not installed here.
• A fallback full-suite run was executed earlier. It exposed PR-related locale coverage gaps, which are now fixed. The remaining failures were in unrelated model resolver, redaction, and CSRF areas and were not changed in this PR.

Risks / Follow-ups

• This adds a browser-accessible shell for trusted workspaces, so the security boundary should be reviewed carefully.
• V1 does not include terminal tabs, persisted terminal history, or terminal-output-to-chat insertion.
• A future explicit “send terminal output to chat” action can be discussed separately, but this PR intentionally keeps terminal output out of model context.
• If Hermes later introduces a formal secondary composer row or workspace command center, the entry point can move there without changing the PTY foundation.

Model Used

• OpenAI GPT-5 via Codex desktop
• Coordinator/worker workflow with local shell verification and user manual visual testing