@bitseek/hermes-webui 0.1.0-beta.0

package/vendor/agent-frontend-shell/.github/workflows/tests.yml

@@ -0,0 +1,88 @@
+name: Tests
+
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+
+jobs:
+  # Forward-looking Python lint gate (ruff). The Python twin of the ESLint runtime
+  # guard. Runs the curated [tool.ruff] ruleset (E9 + F + B) but only on lines this
+  # PR adds/modifies vs the merge-base — so it keeps NEW code clean without demanding
+  # a reformat of the existing tree's cosmetic backlog (#3273). Fast, fails early.
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Need history so the gate can diff against the merge-base with master.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Ensure origin/master ref is available for the diff gate
+        run: git fetch --no-tags --depth=1 origin master || true
+
+      - name: Ruff forward gate (new/changed lines only)
+        run: python3 scripts/ruff_lint.py --diff origin/master
+
+      - name: Ruff whole-tree report (informational — never blocks)
+        if: always()
+        run: python3 scripts/ruff_lint.py --all
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      # Don't cancel the other shards/versions when one fails — we want the full
+      # failure picture across the matrix in a single run.
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+        # Split the suite across 3 parallel shards per Python version. pytest-shard
+        # partitions tests deterministically by test-id hash; the suite was made
+        # shard-safe (no cross-test state leakage) so every shard passes
+        # independently. See docs/agent-memory note on test-suite shard-safety.
+        # NOTE: pytest-shard is 0-indexed — shard ids must be 0..num_shards-1.
+        # Using 1-based ids would crash the out-of-range job AND silently skip
+        # shard 0's tests.
+        shard: [0, 1, 2]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+          cache-dependency-path: |
+            **/setup.cfg
+            **/requirements*.txt
+            **/pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install "pyyaml>=6.0" pytest pytest-timeout pytest-asyncio pytest-shard
+          # ruff is installed so tests/test_ruff_forward_lint.py runs its E9/F821
+          # tree-clean assertions in-suite (mirrors how eslint is available for
+          # tests/test_static_js_runtime_lint.py). If install fails the test
+          # skips cleanly — it never blocks the matrix.
+          pip install ruff || echo "ruff install failed — test_ruff_forward_lint.py will skip"
+          # Install the `mcp` package so tests/test_mcp_server.py runs in CI.
+          # The package is an optional runtime dep of mcp_server.py — users
+          # who run the MCP integration install it themselves; CI installs
+          # it so test coverage exists. If mcp install fails (Python 3.13
+          # wheel not yet available, etc.), tests/test_mcp_server.py uses
+          # importorskip and the matrix stays green.
+          pip install mcp || echo "mcp install failed — test_mcp_server.py will importorskip"
+
+      - name: Run tests (shard ${{ matrix.shard }} of 3)
+        run: pytest tests/ -v --timeout=60 --shard-id=${{ matrix.shard }} --num-shards=3

package/vendor/agent-frontend-shell/.vscode/launch.json

@@ -0,0 +1,59 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "▶ Server (直接启动)",
+      "type": "debugpy",
+      "request": "launch",
+      "program": "${workspaceFolder}/server.py",
+      "console": "integratedTerminal",
+      "cwd": "${workspaceFolder}",
+      "envFile": "${workspaceFolder}/.env",
+      "justMyCode": false
+    },
+    {
+      "name": "▶ Server (含 extensions)",
+      "type": "debugpy",
+      "request": "launch",
+      "program": "${workspaceFolder}/server.py",
+      "console": "integratedTerminal",
+      "cwd": "${workspaceFolder}",
+      "envFile": "${workspaceFolder}/.env",
+      "env": {
+        "HERMES_WEBUI_EXTENSION_DIR": "${workspaceFolder}/extensions"
+      },
+      "justMyCode": false
+    },
+    {
+      "name": "▶ Bootstrap (完整启动)",
+      "type": "debugpy",
+      "request": "launch",
+      "program": "${workspaceFolder}/bootstrap.py",
+      "args": ["--no-browser"],
+      "console": "integratedTerminal",
+      "cwd": "${workspaceFolder}",
+      "envFile": "${workspaceFolder}/.env",
+      "justMyCode": false
+    },
+    {
+      "name": "▶ 当前文件",
+      "type": "debugpy",
+      "request": "launch",
+      "program": "${file}",
+      "console": "integratedTerminal",
+      "cwd": "${workspaceFolder}",
+      "envFile": "${workspaceFolder}/.env",
+      "justMyCode": false
+    },
+    {
+      "name": "🔗 附加到已运行进程 (5678)",
+      "type": "debugpy",
+      "request": "attach",
+      "connect": {
+        "host": "127.0.0.1",
+        "port": 5678
+      },
+      "justMyCode": false
+    }
+  ]
+}

package/vendor/agent-frontend-shell/.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+  "python.analysis.extraPaths": [
+    "${workspaceFolder}"
+  ],
+  "python.analysis.typeCheckingMode": "off",
+  "python.analysis.diagnosticMode": "openFilesOnly",
+  "editor.rulers": [88, 120],
+  "files.exclude": {
+    "**/__pycache__": true,
+    "**/*.pyc": true,
+    ".git": true
+  }
+}

package/vendor/agent-frontend-shell/AGENTS.md

@@ -0,0 +1,80 @@
+# Agent instructions for Hermes WebUI
+
+This file is the shared entry point for AI assistants working in this
+repository. Keep it project-specific and safe to publish. Do not put personal
+machine setup, private network details, credentials, tokens, or local-only
+workflow notes here.
+
+## Read first
+
+Before making changes, read:
+
+1. `README.md`
+2. `CONTRIBUTING.md`
+3. `docs/CONTRACTS.md`
+4. `CHANGELOG.md`
+
+For architecture, testing, or setup work, also read the matching reference:
+
+- `ARCHITECTURE.md` for design constraints and current module layout
+- `TESTING.md` for local verification commands and manual test guidance
+- `docs/onboarding.md` for first-run onboarding behavior
+- `docs/troubleshooting.md` for diagnostic flows
+- `docs/rfcs/README.md` for larger RFCs and state/durability contracts
+
+For UI or UX work, read `docs/UIUX-GUIDE.md` and `DESIGN.md` before
+changing layout, interaction flow, themes, chat rendering, or composer chrome.
+
+## Onboarding and reinstall support
+
+If the task involves install, reinstall, bootstrap, first-run onboarding,
+provider setup, local model server setup, Docker onboarding, WSL onboarding, or
+support for a failed first run, read `docs/onboarding-agent-checklist.md`
+before running commands or inspecting logs.
+
+Follow that checklist's safety rules:
+
+- use isolated `HERMES_HOME` and `HERMES_WEBUI_STATE_DIR` for trials unless the
+  human explicitly asks to use real state
+- do not delete or overwrite a real `~/.hermes` directory without explicit
+  approval
+- do not print API keys, OAuth tokens, cookies, full `.env` files, full
+  `auth.json` files, or password hashes
+- collect non-secret status and log evidence before recommending a fix
+
+## Contribution style
+
+- Keep one logical change per PR; split unrelated refactors or cleanup.
+- Read `docs/CONTRACTS.md` and the linked contract/RFC for the touched
+  subsystem before editing.
+- Prefer the existing Python + vanilla JavaScript structure. Do not add
+  dependencies, build tools, frameworks, or long-lived processes without clear
+  justification and a rollback story.
+- Update docs when changing setup, onboarding, runtime behavior, architecture,
+  testing guidance, or user-facing workflows.
+- Update `CHANGELOG.md` for user-visible behavior, setup, workflow, or
+  documentation changes that should be release-note ready.
+- For UI or UX changes, include before/after evidence and test relevant
+  desktop, narrow, and mobile states.
+- For behavior changes, add or update automated tests where practical and list
+  the manual verification performed.
+- For runtime, streaming, recovery, replay, compression, or sidebar metadata
+  changes, name the state layer being mutated and prove the relevant invariant.
+
+## Local state and secrets
+
+Hermes WebUI can read and write real agent state, sessions, workspaces,
+credentials, and cron data. Treat local validation as potentially destructive
+unless you have confirmed the active state directories.
+
+Prefer isolated trial state for experiments:
+
+```bash
+HERMES_HOME=/tmp/hermes-webui-agent-home \
+HERMES_WEBUI_STATE_DIR=/tmp/hermes-webui-agent-state \
+HERMES_WEBUI_PORT=8789 \
+python3 bootstrap.py
+```
+
+Do not include private machine instructions in this tracked file. Use a
+git-ignored local note for personal workflow details.