feat: vendor xterm.js — fully offline, no CDN (v0.2.0)

README.md

@@ -42,8 +42,8 @@ A terminal is **interactive shell access on the host**. This plugin:
 
 - **protoAgent ≥ 0.27.0** (console views + WebSocket-through-the-fleet-proxy, #883).
 - A **Unix PTY** (Linux/macOS). Windows is not supported (no `pywinpty` yet).
-- No pip deps (the PTY is stdlib). xterm.js loads from jsDelivr — needs network at
-  view-load time (vendoring is a planned follow-up for airgapped installs).
+- No pip deps (the PTY is stdlib). xterm.js + addons are **vendored** (`vendor/`) and
+  served locally by the plugin — **works offline / airgapped**, no CDN.
 
 ## Install — no restart needed
 
@@ -84,8 +84,8 @@ Then open the **Terminal** rail icon. (Make sure the host has an operator bearer
 
 ## Roadmap
 
-v1 is a solid single terminal session per view. Possible next steps: multi-session
-tabs, split panes, a search overlay, vendored xterm assets (offline), Windows
-(`pywinpty`). PRs welcome.
+A solid single terminal session per view. Possible next steps: multi-session tabs,
+split panes, a search overlay, Windows (`pywinpty`). PRs welcome.
 
-Ships **disabled**; nothing runs until you enable it.
+Enabled by default once installed (the WS bearer gate is the protection) — disable
+with `plugins.disabled: [terminal]`.

api.py

@@ -18,6 +18,7 @@
 import json
 import logging
 import os
+from pathlib import Path
 
 from fastapi import WebSocket  # module-level so the websocket route's annotation resolves
 
@@ -26,6 +27,15 @@
 
 log = logging.getLogger("protoagent.plugins.terminal")
 
+# Vendored xterm assets served locally (offline — no CDN). Whitelisted by name.
+_VENDOR_DIR = Path(__file__).resolve().parent / "vendor"
+_VENDOR_TYPES = {
+    "xterm.js": "application/javascript",
+    "xterm.css": "text/css",
+    "addon-fit.js": "application/javascript",
+    "addon-web-links.js": "application/javascript",
+}
+
 
 def expected_token() -> str:
     """The operator bearer a WS must match — the host's configured token. Lazy host
@@ -56,8 +66,8 @@ def scrub_keys() -> list[str]:
 
 
 def build_router(cfg: dict):
-    from fastapi import APIRouter
-    from fastapi.responses import HTMLResponse
+    from fastapi import APIRouter, HTTPException
+    from fastapi.responses import FileResponse, HTMLResponse
 
     router = APIRouter()
     shell = (cfg or {}).get("shell") or ""
@@ -67,6 +77,15 @@ def build_router(cfg: dict):
     async def _view():
         return HTMLResponse(PAGE)
 
+    @router.get("/static/{name}")
+    async def _static(name: str):
+        # Vendored xterm assets (offline). Whitelisted — no path traversal.
+        media = _VENDOR_TYPES.get(name)
+        path = _VENDOR_DIR / name
+        if media is None or not path.is_file():
+            raise HTTPException(404)
+        return FileResponse(path, media_type=media)
+
     @router.websocket("/ws")
     async def _ws(ws: WebSocket):
         if not verify_token(expected_token(), ws.query_params.get("token", "")):

protoagent.plugin.yaml

@@ -1,6 +1,6 @@
 id: terminal
 name: Terminal
-version: 0.1.1
+version: 0.2.0
 description: >-
   A full terminal in the protoAgent console — an xterm.js view wired to a real PTY
   shell over a WebSocket. The terminal is themed from the protoAgent design system
@@ -33,5 +33,5 @@ views:
 
 # Declarative transparency (surfaced in the console; not enforced).
 capabilities:
-  network: ["cdn.jsdelivr.net"]   # xterm.js + addons are loaded from jsDelivr (v1; vendoring is a follow-up)
+  network: []                     # none — xterm.js + addons are VENDORED + served locally (offline)
   filesystem: full                # it spawns an interactive shell — full host access for the operator

pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "terminal-plugin"
-version = "0.1.1"            # keep in lockstep with protoagent.plugin.yaml (a test enforces it)
+version = "0.2.0"            # keep in lockstep with protoagent.plugin.yaml (a test enforces it)
 description = "A full terminal (xterm.js + a real PTY over WebSocket) as a protoAgent console plugin."
 requires-python = ">=3.11"
 
-# No runtime pip deps: the PTY backend is stdlib (pty/os/fcntl/termios), and the host
-# (protoAgent) provides fastapi + langchain-core. The frontend loads xterm.js from a
-# CDN. The only OS requirement is a Unix PTY (Linux/macOS); Windows is unsupported.
+# No runtime pip deps: the PTY backend is stdlib (pty/os/fcntl/termios), the host
+# (protoAgent) provides fastapi + langchain-core, and xterm.js is VENDORED + served
+# locally (offline — no CDN). The only OS requirement is a Unix PTY (Linux/macOS).
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"

tests/test_api.py

@@ -49,6 +49,16 @@ def test_view_served_on_the_public_path():
     assert r.status_code == 200 and "xterm" in r.text.lower()
 
 
+def test_vendored_assets_served_locally():
+    c = TestClient(_app())
+    js = c.get("/plugins/terminal/static/xterm.js")
+    assert js.status_code == 200 and "javascript" in js.headers["content-type"]
+    assert c.get("/plugins/terminal/static/xterm.css").status_code == 200
+    assert c.get("/plugins/terminal/static/addon-fit.js").status_code == 200
+    # whitelist only — an unknown name is 404 (no traversal)
+    assert c.get("/plugins/terminal/static/secret.py").status_code == 404
+
+
 # ── the bearer gate over the wire ───────────────────────────────────────────────
 
 

tests/test_packaging.py

@@ -43,8 +43,9 @@ def test_view_page_pulls_in_the_protoagent_theme_and_four_rules():
     # rule 3 (slug base) + rule 4 (DS kit) — the gated channel is the WS, not apiFetch.
     assert 'location.pathname.split("/plugins/")' in PAGE
     assert "/_ds/plugin-kit.css" in PAGE and "/_ds/plugin-kit.js" in PAGE
-    # the terminal itself: xterm + the WS to the PTY bridge carrying the bearer.
-    assert "@xterm/xterm" in PAGE and "new Terminal(" in PAGE
+    # the terminal itself: VENDORED xterm (offline — no CDN) + the WS to the PTY bridge.
+    assert "/plugins/terminal/static/" in PAGE and "xterm.js" in PAGE and "new Terminal(" in PAGE
+    assert "cdn.jsdelivr" not in PAGE and "https://" not in PAGE  # fully self-served, no CDN
     assert "/plugins/terminal/ws?token=" in PAGE
     # THE theme requirement: xterm's theme is built from protoAgent's --pl-* tokens,
     # and re-applied live on a re-theme (MutationObserver on :root).

vendor/xterm.css

@@ -0,0 +1,218 @@
+/**
+ * Copyright (c) 2014 The xterm.js authors. All rights reserved.
+ * Copyright (c) 2012-2013, Christopher Jeffrey (MIT License)
+ * https://github.com/chjj/term.js
+ * @license MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * Originally forked from (with the author's permission):
+ *   Fabrice Bellard's javascript vt100 for jslinux:
+ *   http://bellard.org/jslinux/
+ *   Copyright (c) 2011 Fabrice Bellard
+ *   The original design remains. The terminal itself
+ *   has been extended to include xterm CSI codes, among
+ *   other features.
+ */
+
+/**
+ *  Default styles for xterm.js
+ */
+
+.xterm {
+    cursor: text;
+    position: relative;
+    user-select: none;
+    -ms-user-select: none;
+    -webkit-user-select: none;
+}
+
+.xterm.focus,
+.xterm:focus {
+    outline: none;
+}
+
+.xterm .xterm-helpers {
+    position: absolute;
+    top: 0;
+    /**
+     * The z-index of the helpers must be higher than the canvases in order for
+     * IMEs to appear on top.
+     */
+    z-index: 5;
+}
+
+.xterm .xterm-helper-textarea {
+    padding: 0;
+    border: 0;
+    margin: 0;
+    /* Move textarea out of the screen to the far left, so that the cursor is not visible */
+    position: absolute;
+    opacity: 0;
+    left: -9999em;
+    top: 0;
+    width: 0;
+    height: 0;
+    z-index: -5;
+    /** Prevent wrapping so the IME appears against the textarea at the correct position */
+    white-space: nowrap;
+    overflow: hidden;
+    resize: none;
+}
+
+.xterm .composition-view {
+    /* TODO: Composition position got messed up somewhere */
+    background: #000;
+    color: #FFF;
+    display: none;
+    position: absolute;
+    white-space: nowrap;
+    z-index: 1;
+}
+
+.xterm .composition-view.active {
+    display: block;
+}
+
+.xterm .xterm-viewport {
+    /* On OS X this is required in order for the scroll bar to appear fully opaque */
+    background-color: #000;
+    overflow-y: scroll;
+    cursor: default;
+    position: absolute;
+    right: 0;
+    left: 0;
+    top: 0;
+    bottom: 0;
+}
+
+.xterm .xterm-screen {
+    position: relative;
+}
+
+.xterm .xterm-screen canvas {
+    position: absolute;
+    left: 0;
+    top: 0;
+}
+
+.xterm .xterm-scroll-area {
+    visibility: hidden;
+}
+
+.xterm-char-measure-element {
+    display: inline-block;
+    visibility: hidden;
+    position: absolute;
+    top: 0;
+    left: -9999em;
+    line-height: normal;
+}
+
+.xterm.enable-mouse-events {
+    /* When mouse events are enabled (eg. tmux), revert to the standard pointer cursor */
+    cursor: default;
+}
+
+.xterm.xterm-cursor-pointer,
+.xterm .xterm-cursor-pointer {
+    cursor: pointer;
+}
+
+.xterm.column-select.focus {
+    /* Column selection mode */
+    cursor: crosshair;
+}
+
+.xterm .xterm-accessibility:not(.debug),
+.xterm .xterm-message {
+    position: absolute;
+    left: 0;
+    top: 0;
+    bottom: 0;
+    right: 0;
+    z-index: 10;
+    color: transparent;
+    pointer-events: none;
+}
+
+.xterm .xterm-accessibility-tree:not(.debug) *::selection {
+  color: transparent;
+}
+
+.xterm .xterm-accessibility-tree {
+  user-select: text;
+  white-space: pre;
+}
+
+.xterm .live-region {
+    position: absolute;
+    left: -9999px;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+}
+
+.xterm-dim {
+    /* Dim should not apply to background, so the opacity of the foreground color is applied
+     * explicitly in the generated class and reset to 1 here */
+    opacity: 1 !important;
+}
+
+.xterm-underline-1 { text-decoration: underline; }
+.xterm-underline-2 { text-decoration: double underline; }
+.xterm-underline-3 { text-decoration: wavy underline; }
+.xterm-underline-4 { text-decoration: dotted underline; }
+.xterm-underline-5 { text-decoration: dashed underline; }
+
+.xterm-overline {
+    text-decoration: overline;
+}
+
+.xterm-overline.xterm-underline-1 { text-decoration: overline underline; }
+.xterm-overline.xterm-underline-2 { text-decoration: overline double underline; }
+.xterm-overline.xterm-underline-3 { text-decoration: overline wavy underline; }
+.xterm-overline.xterm-underline-4 { text-decoration: overline dotted underline; }
+.xterm-overline.xterm-underline-5 { text-decoration: overline dashed underline; }
+
+.xterm-strikethrough {
+    text-decoration: line-through;
+}
+
+.xterm-screen .xterm-decoration-container .xterm-decoration {
+	z-index: 6;
+	position: absolute;
+}
+
+.xterm-screen .xterm-decoration-container .xterm-decoration.xterm-decoration-top-layer {
+	z-index: 7;
+}
+
+.xterm-decoration-overview-ruler {
+    z-index: 8;
+    position: absolute;
+    top: 0;
+    right: 0;
+    pointer-events: none;
+}
+
+.xterm-decoration-top {
+    z-index: 2;
+    position: relative;
+}