feat: implement web terminal for tool instances

- Add TerminalSession backend service for docker exec subprocess management
- Add TerminalManager for WebSocket session lifecycle management
- Create WebSocket endpoint at /ws/tool-instances/{id}/terminal
- Add session cookie authentication and instance ownership verification
- Install xterm.js with fit and web-links addons
- Create TerminalComponent with xterm.js integration
- Create TerminalPage with full-screen terminal view
- Add terminal route at /instances/:id/terminal
- Add terminal button to InstanceList for running instances
- Add terminal and arrow-left icons to icon registry
- Add comprehensive terminal CSS styles (dark theme, responsive)

Quality gates: typecheck ✓, lint ✓, build ✓, Python syntax ✓

apps/web/src/components/icon.tsx

@@ -32,6 +32,8 @@ import {
   ArrowSquareOut,
   Play,
   Stop,
+  Terminal,
+  ArrowLeft,
 } from "@phosphor-icons/react";
 
 export type IconName =
@@ -71,7 +73,9 @@ export type IconName =
   | "binary"
   | "external"
   | "play"
-  | "stop";
+  | "stop"
+  | "terminal"
+  | "arrow-left";
 
 const iconMap: Record<IconName, React.ComponentType<{ size?: number | string; weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone" }>> = {
   dashboard: House,
@@ -111,6 +115,8 @@ const iconMap: Record<IconName, React.ComponentType<{ size?: number | string; we
   external: ArrowSquareOut,
   play: Play,
   stop: Stop,
+  terminal: Terminal,
+  "arrow-left": ArrowLeft,
 };
 
 export interface IconProps {

apps/web/src/components/instance-list.tsx

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useState } from "react";
+import { useNavigate } from "react-router-dom";
 import { Icon } from "./icon";
 import type { ToolInstance } from "../api/sessions";
 import {
@@ -18,6 +19,7 @@ interface InstanceListProps {
 }
 
 export const InstanceList = ({ projectId, repoId, toolTypes }: InstanceListProps) => {
+  const navigate = useNavigate();
   const [instances, setInstances] = useState<ToolInstance[]>([]);
   const [loading, setLoading] = useState(false);
   const [showCreate, setShowCreate] = useState(false);
@@ -154,6 +156,16 @@ export const InstanceList = ({ projectId, repoId, toolTypes }: InstanceListProps
                     Open
                   </a>
                 )}
+                {instance.status === "running" && (
+                  <button
+                    className="secondary-button small"
+                    onClick={() => navigate(`/instances/${instance.id}/terminal`)}
+                    type="button"
+                  >
+                    <Icon name="terminal" size="sm" />
+                    Terminal
+                  </button>
+                )}
                 {instance.status !== "running" && (
                   <button
                     className="secondary-button small"

apps/web/src/components/terminal.tsx

@@ -0,0 +1,158 @@
+import React, { useEffect, useRef, useState } from "react";
+import { Terminal } from "xterm";
+import { FitAddon } from "xterm-addon-fit";
+import { WebLinksAddon } from "xterm-addon-web-links";
+import "xterm/css/xterm.css";
+
+interface TerminalProps {
+  instanceId: string;
+  onClose?: () => void;
+}
+
+export const TerminalComponent: React.FC<TerminalProps> = ({ instanceId, onClose }) => {
+  const terminalRef = useRef<HTMLDivElement>(null);
+  const wsRef = useRef<WebSocket | null>(null);
+  const [status, setStatus] = useState<"connecting" | "connected" | "disconnected" | "error">(
+    "connecting",
+  );
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!terminalRef.current) return;
+
+    // Initialize terminal
+    const term = new Terminal({
+      cursorBlink: true,
+      fontSize: 14,
+      fontFamily: 'Menlo, Monaco, "Courier New", monospace',
+      theme: {
+        background: "#1e1e1e",
+        foreground: "#d4d4d4",
+        cursor: "#d4d4d4",
+        selectionBackground: "#264f78",
+        black: "#000000",
+        red: "#cd3131",
+        green: "#0dbc79",
+        yellow: "#e5e510",
+        blue: "#2472c8",
+        magenta: "#bc3fbc",
+        cyan: "#11a8cd",
+        white: "#e5e5e5",
+        brightBlack: "#666666",
+        brightRed: "#f14c4c",
+        brightGreen: "#23d18b",
+        brightYellow: "#f5f543",
+        brightBlue: "#3b8eea",
+        brightMagenta: "#d670d6",
+        brightCyan: "#29b8db",
+        brightWhite: "#e5e5e5",
+      },
+    });
+
+    const fitAddon = new FitAddon();
+    term.loadAddon(fitAddon);
+    term.loadAddon(new WebLinksAddon());
+
+    term.open(terminalRef.current);
+    fitAddon.fit();
+
+    // Build WebSocket URL
+    const apiUrl = import.meta.env.VITE_API_BASE_URL || "";
+    const wsProtocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+    const wsHost = apiUrl.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+    const wsUrl = `${wsProtocol}//${wsHost}/ws/tool-instances/${instanceId}/terminal`;
+
+    // Connect WebSocket
+    const ws = new WebSocket(wsUrl);
+    wsRef.current = ws;
+
+    ws.onopen = () => {
+      setStatus("connected");
+      setError(null);
+    };
+
+    ws.onmessage = (event) => {
+      if (event.data instanceof Blob) {
+        event.data.arrayBuffer().then((buffer) => {
+          const data = new Uint8Array(buffer);
+          term.write(data);
+        });
+      } else if (typeof event.data === "string") {
+        try {
+          const msg = JSON.parse(event.data);
+          if (msg.type === "status" && msg.status === "connected") {
+            setStatus("connected");
+          }
+        } catch {
+          term.write(event.data);
+        }
+      }
+    };
+
+    ws.onclose = (event) => {
+      setStatus("disconnected");
+      if (event.code !== 1000) {
+        setError(`Connection closed (code: ${event.code})`);
+      }
+    };
+
+    ws.onerror = () => {
+      setStatus("error");
+      setError("WebSocket error");
+    };
+
+    // Handle terminal input
+    term.onData((data) => {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(data);
+      }
+    });
+
+    // Handle resize
+    const handleResize = () => {
+      fitAddon.fit();
+      const { cols, rows } = term;
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(
+          JSON.stringify({
+            type: "resize",
+            cols,
+            rows,
+          }),
+        );
+      }
+    };
+
+    window.addEventListener("resize", handleResize);
+
+    // Initial resize
+    setTimeout(handleResize, 100);
+
+    return () => {
+      window.removeEventListener("resize", handleResize);
+      ws.close();
+      term.dispose();
+    };
+  }, [instanceId]);
+
+  return (
+    <div className="terminal-wrapper">
+      <div className="terminal-header">
+        <div className="terminal-status">
+          <span
+            className={`status-dot ${status}`}
+            aria-label={`Terminal status: ${status}`}
+          />
+          <span className="status-text">{status}</span>
+        </div>
+        {onClose && (
+          <button className="terminal-close" onClick={onClose} type="button">
+            Close
+          </button>
+        )}
+      </div>
+      {error && <div className="terminal-error">{error}</div>}
+      <div ref={terminalRef} className="terminal-container" />
+    </div>
+  );
+};

apps/web/src/pages/terminal.tsx

@@ -0,0 +1,38 @@
+import React from "react";
+import { useNavigate, useParams } from "react-router-dom";
+import { TerminalComponent } from "../components/terminal";
+import { Icon } from "../components/icon";
+
+export const TerminalPage: React.FC = () => {
+  const { instanceId } = useParams<{ instanceId: string }>();
+  const navigate = useNavigate();
+
+  if (!instanceId) {
+    return (
+      <section className="stack">
+        <h1>Terminal</h1>
+        <p className="muted">No instance ID provided.</p>
+      </section>
+    );
+  }
+
+  return (
+    <section className="terminal-page">
+      <div className="terminal-page-header">
+        <button
+          className="secondary-button"
+          onClick={() => navigate(-1)}
+          type="button"
+        >
+          <Icon name="arrow-left" size="sm" />
+          Back
+        </button>
+        <h1>Terminal</h1>
+      </div>
+      <TerminalComponent
+        instanceId={instanceId}
+        onClose={() => navigate(-1)}
+      />
+    </section>
+  );
+};

apps/web/src/router.tsx

@@ -12,6 +12,7 @@ import { ProjectSettingsPage } from "./pages/project-settings";
 import { RepoWorkspace } from "./pages/repo-workspace";
 import { SSHKeysPage } from "./pages/ssh-keys";
 import { SettingsPage } from "./pages/settings";
+import { TerminalPage } from "./pages/terminal";
 import { ToolTypesPage } from "./pages/tool-types";
 
 export const AppRouter = () => {
@@ -36,6 +37,7 @@ export const AppRouter = () => {
         <Route path="profile" element={<ProfilePage />} />
         <Route path="settings" element={<SettingsPage />} />
         <Route path="tool-types" element={<ToolTypesPage />} />
+        <Route path="instances/:instanceId/terminal" element={<TerminalPage />} />
       </Route>
       <Route path="/404" element={<NotFoundPage />} />
       <Route path="*" element={<Navigate to="/404" replace />} />

apps/web/src/styles.css

@@ -2321,3 +2321,138 @@ a.nav-item,
   gap: var(--space-2);
   align-items: center;
 }
+
+/* ============================================
+   Terminal Styles
+   ============================================ */
+
+.terminal-page {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  padding: var(--space-4);
+  gap: var(--space-4);
+}
+
+.terminal-page-header {
+  display: flex;
+  align-items: center;
+  gap: var(--space-4);
+  flex-shrink: 0;
+}
+
+.terminal-page-header h1 {
+  margin: 0;
+}
+
+.terminal-wrapper {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  overflow: hidden;
+  background: #1e1e1e;
+}
+
+.terminal-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: var(--space-3) var(--space-4);
+  background: #2d2d2d;
+  border-bottom: 1px solid #3e3e3e;
+  flex-shrink: 0;
+}
+
+.terminal-status {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+}
+
+.status-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: #666;
+}
+
+.status-dot.connecting {
+  background: #f5f543;
+  animation: pulse 1.5s infinite;
+}
+
+.status-dot.connected {
+  background: #0dbc79;
+}
+
+.status-dot.disconnected,
+.status-dot.error {
+  background: #cd3131;
+}
+
+@keyframes pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.5;
+  }
+}
+
+.status-text {
+  font-size: 0.875rem;
+  color: #d4d4d4;
+  text-transform: capitalize;
+}
+
+.terminal-close {
+  padding: var(--space-1) var(--space-3);
+  background: transparent;
+  border: 1px solid #666;
+  border-radius: 6px;
+  color: #d4d4d4;
+  cursor: pointer;
+  font-size: 0.875rem;
+}
+
+.terminal-close:hover {
+  background: #3e3e3e;
+}
+
+.terminal-error {
+  padding: var(--space-3) var(--space-4);
+  background: #cd3131;
+  color: white;
+  font-size: 0.875rem;
+  flex-shrink: 0;
+}
+
+.terminal-container {
+  flex: 1;
+  min-height: 0;
+  padding: var(--space-2);
+}
+
+.terminal-container .xterm {
+  height: 100%;
+}
+
+.terminal-container .xterm-viewport {
+  background: #1e1e1e !important;
+}
+
+/* Responsive terminal */
+@media (max-width: 767px) {
+  .terminal-page {
+    padding: var(--space-2);
+    gap: var(--space-2);
+  }
+
+  .terminal-page-header h1 {
+    font-size: 1.25rem;
+  }
+}

apps/web/src/utils/icons.ts

@@ -31,6 +31,8 @@ import {
   ArrowSquareOut,
   Play,
   Stop,
+  Terminal,
+  ArrowLeft,
 } from "@phosphor-icons/react";
 
 export type IconName =
@@ -70,7 +72,9 @@ export type IconName =
   | "binary"
   | "external"
   | "play"
-  | "stop";
+  | "stop"
+  | "terminal"
+  | "arrow-left";
 
 export const iconRegistry: Record<
   IconName,
@@ -124,6 +128,8 @@ export const iconRegistry: Record<
   external: ArrowSquareOut,
   play: Play,
   stop: Stop,
+  terminal: Terminal,
+  "arrow-left": ArrowLeft,
 };
 
 export const iconCategories = {