Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

fix(agent-runtimes): make Hermes and OpenClaw agents production-grade on every OS (#460)

Ruben Lütke926faec8dbd1
diff --git a/.github/workflows/agent-runtimes-canary.yml b/.github/workflows/agent-runtimes-canary.yml
index b920ed697f..f281ec86a2 100644
--- a/.github/workflows/agent-runtimes-canary.yml
+++ b/.github/workflows/agent-runtimes-canary.yml
@@ -1,9 +1,15 @@
name: Agent runtimes canary
-# Installs the LATEST Hermes and OpenClaw with their own official installers and
-# drives two turns through Jarvis' runtime drivers against a scripted fake model
-# (scripts/spikes/agent_runtimes_e2e.py, tests/fakes/fake_openai_server.py).
-# Not part of the CI gate: an upstream release that breaks the integration
-# opens an issue here before a person runs into it. See docs/agent-runtimes.md.
+# Installs the LATEST Hermes and OpenClaw through the app's own setup job (the
+# pin is pointed at upstream latest in the canary's checkout only) and runs
+# scripts/ci/agent_runtime_e2e.py: two turns per model-gateway protocol against
+# scripted providers, the fake-model driver check, the runtime unit tests and
+# the PATH / shell-profile checks. No key, no network to a model. Every pull
+# request already proves the PINNED versions (ci.yml, agent-runtimes-e2e); this
+# checks what upstream ships next:
+# * green on every OS -> a pull request raises the pin in
+# jarvis/agent_runtimes/runtime-versions.json (scripts/ci/agent_runtime_suite.py);
+# * red on a schedule -> an issue, and the pin stays where it is.
+# See docs/agent-runtimes.md ("CI and release gates").
on:
schedule:
- cron: '17 5 * * 1'
@@ -23,31 +29,77 @@ jobs:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
persist-credentials: false
- - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
python-version: '3.12'
- name: Install the base app
run: python scripts/pip_install.py -e "."
- - name: Install Hermes (official installer, Linux/macOS)
- if: matrix.runtime == 'hermes' && runner.os != 'Windows'
- run: |
- curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-setup --non-interactive --skip-browser
- echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- - name: Install Hermes (official installer, Windows)
- if: matrix.runtime == 'hermes' && runner.os == 'Windows'
- shell: pwsh
- run: |
- & ([scriptblock]::Create((irm https://hermes-agent.nousresearch.com/install.ps1))) -SkipSetup -NonInteractive
- "$env:LOCALAPPDATA\hermes\bin" | Out-File -FilePath $env:GITHUB_PATH -Append -Encoding utf8
- - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- if: matrix.runtime == 'openclaw'
+ # The app's own setup installs whatever the pin names; in this checkout
+ # only, the pin points at upstream latest (newest OpenClaw on npm, the
+ # head of Hermes' default branch).
+ - name: Aim the app's setup at upstream latest
+ run: python scripts/ci/agent_runtime_suite.py --point-at-latest ${{ matrix.runtime }}
+ - name: Set up through the app, drive it, prove nothing else changed
+ run: python scripts/ci/agent_runtime_e2e.py ${{ matrix.runtime }} --allow-untested
+ - name: Record the version that passed
+ run: python scripts/ci/agent_runtime_suite.py --report ${{ matrix.runtime }} --out canary-report.json
+ - uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
with:
- node-version: '24'
- - name: Install OpenClaw (latest)
- if: matrix.runtime == 'openclaw'
- run: npm install -g openclaw@latest
- - name: Drive two turns through the Jarvis driver
- run: python scripts/spikes/agent_runtimes_e2e.py ${{ matrix.runtime }}
+ name: canary-report-${{ matrix.runtime }}-${{ matrix.os }}
+ path: canary-report.json
+ if-no-files-found: error
+ retention-days: 7
+ - name: Keep the runtime log of a failed run
+ if: failure()
+ uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
+ with:
+ name: canary-log-${{ matrix.runtime }}-${{ matrix.os }}
+ path: eval-results/
+ if-no-files-found: ignore
+ retention-days: 14
+
+ # Only what passed on all three OSes is recorded; a runtime with a red or
+ # missing OS keeps its pin (bump_from). A pull request opened with the
+ # workflow token starts no workflow by itself: CI runs when the merge train
+ # or a maintainer dispatches it, and that run is the pin's admission.
+ raise-pin:
+ needs: canary
+ if: ${{ !cancelled() }}
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ permissions:
+ contents: write
+ pull-requests: write
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ persist-credentials: false
+ - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+ with:
+ pattern: canary-report-*
+ path: reports
+ - name: Raise the pins every OS agreed on
+ id: bump
+ run: python3 scripts/ci/agent_runtime_suite.py --bump-from reports
+ - name: Open a pull request with the new pins
+ if: steps.bump.outputs.changed == 'true'
+ env:
+ GH_TOKEN: ${{ github.token }}
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+ run: |
+ branch="ci/agent-runtime-pins-${GITHUB_RUN_ID}"
+ git config user.name "github-actions[bot]"
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+ git switch -c "$branch"
+ git add jarvis/agent_runtimes/runtime-versions.json
+ git commit -m "chore(agent-runtimes): raise the tested runtime versions" \
+ -m "The weekly canary passed both model-gateway protocols on Linux, Windows and macOS: $RUN_URL"
+ git push "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "$branch"
+ gh pr create --repo "$GITHUB_REPOSITORY" --head "$branch" --base "$DEFAULT_BRANCH" \
+ --title "chore(agent-runtimes): raise the tested runtime versions" \
+ --body "The weekly canary drove the latest Hermes / OpenClaw through Jarvis' model gateway on every OS: $RUN_URL. Merging raises the version the app installs (see docs/agent-runtimes.md)."
+
report:
needs: canary
if: failure() && github.event_name == 'schedule'
@@ -62,4 +114,4 @@ jobs:
run: |
gh issue create --repo "$GITHUB_REPOSITORY" \
--title "Agent runtimes canary failed" \
- --body "The weekly canary could not drive the latest Hermes or OpenClaw release through Jarvis' runtime drivers. Run: $RUN_URL (see docs/agent-runtimes.md)."
+ --body "The weekly canary could not drive the latest Hermes or OpenClaw release through Jarvis' model gateway. The pinned versions stay in place. Run: $RUN_URL (see docs/agent-runtimes.md)."
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bd19f821e7..a82bcfcd44 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -106,6 +106,7 @@ jobs:
macos_desktop: ${{ steps.lanes.outputs.macos_desktop }}
installer: ${{ steps.lanes.outputs.installer }}
updater: ${{ steps.lanes.outputs.updater }}
+ agent_runtimes: ${{ steps.lanes.outputs.agent_runtimes }}
macos: ${{ steps.mode.outputs.macos }}
base: ${{ steps.mode.outputs.base }}
pr_mode: ${{ steps.mode.outputs.pr_mode }}
@@ -956,6 +957,112 @@ jobs:
force: ${{ needs.detect.outputs.full == 'true' }}
include_macos: ${{ needs.detect.outputs.macos == 'true' }}
+ # Hermes / OpenClaw society agents on every OS a person runs them on. The
+ # lane (scripts/ci/agent_runtime_suite.py) covers the runtimes AND the chat
+ # and society code that drives them, so a pull request proves macOS too,
+ # not only the nightly run. Fakes only: no key, no network to a model.
+ agent-runtimes-unit:
+ needs: detect
+ if: needs.detect.outputs.agent_runtimes == 'true'
+ strategy:
+ fail-fast: false
+ matrix:
+ os: [ubuntu-latest, windows-latest, macos-latest]
+ runs-on: ${{ matrix.os }}
+ timeout-minutes: 25
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ persist-credentials: false
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: "3.11"
+ - name: Portable base + focused runner
+ shell: bash
+ run: |
+ python -m pip install -e .
+ python -m pip install pytest pytest-asyncio
+ - name: Runtimes, chat and society suite
+ run: python scripts/ci/agent_runtime_suite.py
+
+ # A downloader's headless Linux server: no GPU, audio or desktop stack.
+ agent-runtimes-headless:
+ name: agent runtimes on python:3.11-slim
+ needs: detect
+ if: needs.detect.outputs.agent_runtimes == 'true'
+ runs-on: ubuntu-latest
+ container: python:3.11-slim
+ timeout-minutes: 30
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ persist-credentials: false
+ - name: Base install without system audio
+ run: |
+ python -m pip install -e .
+ python -m pip install pytest pytest-asyncio
+ - name: The runtime package imports without any optional stack
+ run: python -c "import jarvis.agent_runtimes.gateway, jarvis.agent_runtimes.manager, jarvis.agent_chat.runner_acp"
+ - name: Runtime suite
+ run: python scripts/ci/agent_runtime_suite.py --headless
+ # The container has no curl: the app's own Hermes setup must stop with a
+ # plain reason instead of "succeeding" on an empty download.
+ - name: Setup without curl fails with a plain reason
+ run: python scripts/ci/agent_runtime_e2e.py hermes --timeout 600 --expect-setup-failure "Setup needs curl"
+
+ # The REAL runtimes, installed the way the desktop app installs them: the
+ # app's own setup job (manager.wait_ready) at the pinned release from
+ # jarvis/agent_runtimes/runtime-versions.json, with a desktop app's PATH,
+ # never npm or a manual installer. Then two turns per model-gateway protocol
+ # against scripted providers, the fake-model driver check with turn-1
+ # budgets, the runtime unit tests on the same machine, and proof that the
+ # user PATH and shell profiles stayed put (scripts/ci/agent_runtime_e2e.py).
+ # No key, no network to a model. The weekly canary does the same at
+ # upstream latest and raises the pin.
+ agent-runtimes-e2e:
+ needs: detect
+ if: needs.detect.outputs.agent_runtimes == 'true'
+ strategy:
+ fail-fast: false
+ matrix:
+ os: [ubuntu-latest, windows-latest, macos-latest]
+ runtime: [hermes, openclaw]
+ runs-on: ${{ matrix.os }}
+ timeout-minutes: 45
+ steps:
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+ with:
+ persist-credentials: false
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: "3.12"
+ - name: Install the base app
+ run: |
+ python scripts/pip_install.py -e "."
+ python -m pip install pytest pytest-asyncio
+ # Downloads only: the private OpenClaw copy and uv's cache. Never Hermes'
+ # own home, so its install and prepare run for real on every pin.
+ - name: Reuse the pinned runtime downloads
+ uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+ with:
+ path: |
+ ~/.jarvis/agent_runtimes/openclaw-cli
+ ~/AppData/Local/Jarvis/agent_runtimes/openclaw-cli
+ ~/.cache/uv
+ ~/Library/Caches/uv
+ ~/AppData/Local/uv/cache
+ key: agent-runtimes-${{ matrix.runtime }}-${{ runner.os }}-${{ hashFiles('jarvis/agent_runtimes/runtime-versions.json') }}
+ - name: Set up through the app, drive it, prove nothing else changed
+ run: python scripts/ci/agent_runtime_e2e.py ${{ matrix.runtime }}
+ - name: Keep the setup and runtime logs of a failed run
+ if: failure()
+ uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
+ with:
+ name: agent-runtimes-e2e-${{ matrix.runtime }}-${{ matrix.os }}
+ path: eval-results/
+ if-no-files-found: ignore
+ retention-days: 7
+
# The ONE required check. Branch protection and the merge train read only
# this; a new job needs nothing but a line in `needs`.
gate:
@@ -984,6 +1091,9 @@ jobs:
- macos-desktop
- installer
- updater
+ - agent-runtimes-unit
+ - agent-runtimes-headless
+ - agent-runtimes-e2e
if: ${{ !cancelled() }}
runs-on: ubuntu-latest
timeout-minutes: 5
diff --git a/.gitignore b/.gitignore
index 59fa3441e6..975f94c0b2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -504,3 +504,4 @@ scripts/figures/cache/
# Launch-video renders from the /brag skill (thousands of frames).
brag-output/
+eval-results/
diff --git a/docs/agent-runtimes-eval.md b/docs/agent-runtimes-eval.md
new file mode 100644
index 0000000000..641a008967
--- /dev/null
+++ b/docs/agent-runtimes-eval.md
@@ -0,0 +1,131 @@
+# Agent runtime acceptance evidence
+
+Issue [#428](https://github.com/PersonalJarvis/PersonalJarvis/issues/428) is an
+epic, not a single defect. This document records a partial implementation and
+its evidence. It does **not** declare the epic or its child issues complete.
+
+## Scope and reproduction (2026-10-07)
+
+The issue, its comments, issues #418 through #427, and PR #416 were read before
+implementation. None of these issues had comments at investigation time.
+PR #416 was still open. The isolated local branch starts from its referenced
+commit `a00bcb868cc42913e63cd4c6839c2d7482027db7`.
+
+Three concrete problems were established:
+
+1. `runner_acp._denied_native` considered explicit denials but ignored an
+ allowlist's missing grants. Four new parameterized regression cases failed
+ on the original implementation. Native shell/browser access now requires
+ the corresponding grant for allowlist agents; explicit denial still wins.
+2. Hermes received no context length; OpenClaw always received 128,000 context
+ tokens and 8,192 output tokens. Gateway model rows carried no limits and did
+ not include arbitrary selected local models. The selected route, runtime
+ config, model discovery and Chat Completions output cap now share a budget.
+3. A real OpenClaw replay run logged `memory-core: created managed dreaming
+ cron job` even with heartbeat disabled. The driver now disables the memory
+ plugin/slot and the native scheduler as well. Jarvis owns those services.
+
+## Checks
+
+| Check | Result | What it establishes |
+|---|---|---|
+| Original runtime unit suite | 72 passed | Starting test baseline |
+| Native allowlist reproduction before fix | 4 failed, 5 passed | Missing grants were ignored |
+| Focused runtime/catalog/subscription/society suite | 304 passed | Backend regression coverage |
+| Routing, output filter, hangup parity, turn-language guards | 599 passed | Shared guards remain green |
+| New regressions on Linux, Python 3.11 slim | 32 passed | Model budgets, grants and probe process cleanup work in a Linux container |
+| Scoped Ruff and whitespace checks | Passed | Local static validation |
+| Windows OpenClaw, Responses replay | Two turns passed | Guarded gateway, streamed answer and resumed history; no live subscription call |
+| Windows OpenClaw, Chat Completions replay | Two turns passed | Actual runtime with scripted brain through the gateway and new config |
+| Windows Hermes 0.21.5, 32k Responses replay | Failed at `session/new` | Runtime requires at least 64,000 context tokens; accurately declaring 32k exposes that incompatibility |
+| Windows Hermes 0.21.5, 128k Responses replay | Two turns passed | Correctly declared scripted model, streamed response and resumed history |
+| Windows OpenClaw 2026.9.8, local Ollama qwen3.5:4b, 32k budget | Failed | Both turns completed with empty answer text; no behavioural acceptance claim |
+
+The OpenClaw Responses replay was run before disabling the native memory
+plugin; the Chat Completions replay used that final configuration. Replay
+tests validate transport and lifecycle, **not** model behaviour or token savings.
+The Linux container mounted the branch read-only and held no user credentials.
+It was a focused Python test run, not a fresh-machine runtime install.
+
+The Hermes SDK returned the actual context error in `error.data.details`.
+Jarvis now translates that recognized numeric error into an actionable message
+while continuing to withhold arbitrary upstream detail. The scripted replay
+model advertises 128k; real small models keep their real budget. No local model
+was silently reconfigured to meet Hermes' minimum.
+
+Relevant commands:
+
+```text
+python -m pytest tests/unit/agent_runtimes tests/unit/brain/test_model_catalog.py tests/unit/brain/test_model_catalog_local.py tests/unit/brain/test_model_catalog_optional_auth.py tests/unit/brain/test_model_catalog_parity.py tests/unit/live/test_subscription_reasoning.py tests/unit/society/test_surface.py -q
+python -m pytest tests/unit/brain/test_routing.py tests/unit/brain/test_output_filter.py tests/unit/sessions/test_hangup_reason_parity.py tests/unit/core/test_turn_language.py -q
+python scripts/spikes/agent_runtimes_gateway_e2e.py openclaw openai-codex --replay
+python scripts/spikes/agent_runtimes_gateway_e2e.py openclaw ollama --replay
+python scripts/spikes/agent_runtimes_gateway_e2e.py hermes openai-codex --replay
+```
+
+The smoke driver closes its process tree and releases the turn slot on success,
+spawn failure and cancellation. Gateway server threads and runtime supervisors
+are stopped in cleanup. Runtime state, catalog writes and usage records are
+temporary; failed probe logs are retained only in ignored `eval-results/`.
+Multi-turn probes refuse paid API providers because runtime retries cannot
+honor a one-call paid budget.
+
+## Remaining acceptance work
+
+### Default autonomy and full capacity follow-up
+
+The requested default is all capabilities with Bypass permissions, while
+explicit user choices remain authoritative. Existing roster and routine code
+already implements those defaults; tests now cover all three runtime choices.
+The original fixed 32k local allocation and output-context halving have been
+removed. A model declaring a 131,072-token window now exposes all 131,072 tokens
+instead of 32,768 on Ollama, and a declared 100,000-token output capacity is no
+longer reduced to 65,536. The gateway no longer clips requests at 128,000 tokens
+or treats an omitted request limit as 8,192. Unknown output limits remain unknown.
+Ollama profiles make the advertised allocation real; preparation failure stops
+the request instead of silently using a smaller base-model window. These are
+source and regression-test checks, not a large-context live hardware benchmark.
+
+| Issue | Remaining work |
+|---|---|
+| #418 | Hermetic full-backend behaviour evaluator, S1-S8 and maintainer daily tasks, machine-checked behaviour and cost/latency baseline for all three runtimes. Not implemented by this patch. |
+| #419 | Successful local-model behaviour and live subscription/authorized paid call; fresh Windows/Linux installs; real macOS and restart/UI acceptance. Hermes' 32k session failure is diagnosed above. |
+| #420 | Profile/discovery implementation and measured 70% input-token reduction without quality regression. No savings claim is made. |
+| #421 | Long-conversation/compaction evidence on both runtimes and a 32k local model. Metadata propagation and output clamping are implemented. |
+| #422 | Briefing changes justified by before/after behaviour results. |
+| #423 | Read-only active skill mirrors and native skill usage attribution. |
+| #424 | Cross-family fallback, cost policy and visible effective-provider notice. |
+| #425 | Canary execution on all OSes, verified manifest publication, pinned installs, initialize smoke and rollback. The workflow now checks both gateway protocols with scripted providers; it has not been dispatched. |
+| #426 | Cold/replay measurements before deciding on warm Hermes processes. |
+| #427 | Optional Claude Code backend spike and scope decision. |
+
+No issue was closed or modified; no workflow was dispatched, no PR published,
+and no changes pushed. The three to five maintainer-specific daily tasks were
+requested but were not supplied during this work.
+
+## Changed files
+
+Local desktop integration, 2026-10-07: the patch was applied to the normal
+checkout on top of `f2c336dce`, preserving the newer provider-login changes.
+The integration checks passed: 284 focused runtime/catalog/subscription tests,
+106 runtime tests using the desktop's Python 3.11 interpreter, and scoped Ruff.
+The pre-existing uncommitted changes in `docs/os-parity.md` were left untouched;
+the P-45 update remains available in the original isolated commit. Activation
+requires a desktop restart. The running app's lifecycle guard requires an
+explicit desktop-UI click and rejects Control-API restart requests.
+
+- `jarvis/agent_chat/runner_acp.py`: native grants and route preparation.
+- `jarvis/agent_runtimes/model_limits.py`, `model_map.py`, `gateway.py`, `acp.py`:
+ shared budgets, catalog refresh, discovery and output limits.
+- `jarvis/agent_runtimes/hermes.py`, `openclaw.py`: runtime configuration.
+- `jarvis/brain/model_catalog.py`, `jarvis/live/subscription_reasoning.py`:
+ preserve provider-declared limits, including catalog cache reloads.
+- `scripts/spikes/agent_runtimes_e2e.py`,
+ `scripts/spikes/agent_runtimes_gateway_e2e.py`: contained probes and replay.
+- `.github/workflows/agent-runtimes-canary.yml`: exercise both gateway protocols.
+- `tests/unit/agent_runtimes/test_model_limits.py`, `test_native_grants.py`,
+ `test_smoke_lifecycle.py`, `test_runtime_configs.py`, `test_runtime_gateway.py`;
+ `tests/unit/live/test_subscription_reasoning.py`;
+ `tests/fakes/fake_runtime_brain.py`: regression tests and scripted provider.
+- `.gitignore`, `docs/agent-runtimes.md`, `docs/os-parity.md`, this document:
+ local artifacts, behaviour description and explicit acceptance boundaries.
diff --git a/docs/agent-runtimes.md b/docs/agent-runtimes.md
index bc4d5f703d..35cda28cb1 100644
--- a/docs/agent-runtimes.md
+++ b/docs/agent-runtimes.md
@@ -20,23 +20,55 @@ Nobody installs Hermes or OpenClaw by hand (`jarvis/agent_runtimes/manager.py`):
- **Picking a runtime sets it up.** The dialog sends
`POST /api/agent-runtimes/{runtime}/ensure` as soon as Hermes or OpenClaw is
- picked; creating the agent sends it again. `ensure` runs the project's own
- installer when the runtime is missing (OpenClaw's also adds the Node.js it
- needs) and its own updater when it is too old. The agent can be created
- while that runs.
-- **A turn waits for the setup.** A turn on a runtime that is not ready posts
- a `runtime_setup` notice in the chat and waits for the job; a setup that
- fails ends the turn with its reason.
-- **Daily updates.** While any agent uses a runtime, the society runtime runs
- its updater once a day (first round 10 minutes after start), only when no
- turn of it is running. An update that leaves the runtime unable to start is
- repaired by a fresh install with the official installer.
+ picked; creating the agent sends it again. `ensure` starts whichever job the
+ runtime needs: an install when it is missing, an update when it is older
+ than the minimum, and for Hermes a one-time *prepare* of the data root its
+ agents share (below). The agent can be created while that runs.
+- **Pinned releases.** `jarvis/agent_runtimes/runtime-versions.json` names per
+ runtime a `minimum` (older installs are not ready) and a `tested` release
+ (Hermes also its source `commit` and the `config_version` it writes). Every
+ install and update goes to `tested`, never to upstream latest; `tested` is
+ bumped only from a green agent-runtimes canary run on all three OSes. A
+ newer install the person made themselves keeps running and is reported as
+ `untested` in `GET /api/agent-runtimes`.
+- **Installers.** Hermes: its official `install.ps1` / `install.sh` at the
+ pinned commit, without browser tools or desktop control
+ (`-SkipBrowser -SkipComputerUse` / `--skip-browser --skip-computer-use`).
+ OpenClaw: Jarvis installs its own copy into `<runtimes_root>/openclaw-cli`
+ with a private Node.js — `install-cli.sh --prefix … --version <tested>` on
+ macOS and Linux (no sudo, no shell-profile change), `install.ps1 -NodeOnly`
+ (a checksum-verified private Node.js, no `winget`/UAC prompt) plus that
+ Node's npm on Windows. Jarvis never updates the person's own OpenClaw; a
+ ready one they installed is used until Jarvis' copy exists. On macOS and
+ Linux the installer script is downloaded first and run under
+ `set -euo pipefail`, so a missing `curl`/`git`, an offline machine or a 404
+ fails the job with a plain reason (exit 90 names the missing tool); the
+ installer's last log line is the reason a waiting turn shows.
+- **Setup holds the runtime alone.** A job waits until no turn of its runtime
+ runs, and turns that arrive meanwhile wait for the job (`base.RuntimeGate`).
+ An update replaces files a running turn holds open; on Windows it cannot.
+- **A turn waits for the setup.** A turn on a runtime that needs a job posts a
+ `runtime_setup` notice in the chat and waits for it; a setup that fails ends
+ the turn with its reason.
+- **Daily round.** While any agent uses a runtime, the society runtime checks
+ it once a day (first round 10 minutes after start) and, only when no turn of
+ it runs, lifts an install older than `tested` up to it. An update that
+ leaves the runtime unable to start is repaired by a fresh install; when
+ that fails too, the last release that finished a setup ready
+ (`<runtimes_root>/<runtime>-last-good.json`) is reinstalled.
+- **Found without a restart.** Binary discovery re-checks the well-known
+ install folders on every call (`base.which`), searches the installers'
+ private Node.js and command folders, and merges the persistent PATH the
+ installer may have changed (Windows registry) after each job.
- **No version numbers in the UI.** The dialog says "Ready", "Setting up…" or
- "Sets itself up"; versions stay internal (the minimum versions gate
- readiness).
+ "Sets itself up"; versions stay internal.
None of this calls a model, so setup and updates never spend a key.
+Each app instance keeps its own runtime folders (`agent_runtimes` for the
+default app, `agent_runtimes-dev` for the dev instance), and a turn holds a
+cross-process lock on its folder.
+
## Models: Jarvis' model gateway
An agent on Hermes or OpenClaw never talks to a model vendor. Its runtime is
@@ -54,52 +86,111 @@ call with its own provider plugins (`gateway.py`,
working across Hermes and OpenClaw updates.
- **Every connected provider works.** The dialog lists what can answer right
now — a signed-in subscription first, then each provider with a saved key
- (the Agents-tier key wins, as for Jarvis' own agents) or a local server
- with an address. A new provider plugin in Jarvis is new to the runtimes too.
+ (the Agents-tier key wins, as for Jarvis' own agents), a local server with
+ an address, or Vertex AI on a Google Cloud project without a key. The
+ runtimes can use the providers listed in `model_map._ENDPOINTS`; a new
+ provider plugin needs an entry there too. A way of paying that exists but
+ is refused right now (a Claude login whose Extra Usage is off or spent) is
+ reported in `access_blocked` on `/api/agent-runtimes` with its reason code,
+ so the dialog shows it disabled.
- **Keys and logins stay in Jarvis.** The runtime gets a per-agent token
(`jrg_…`, process environment only); `SurfaceSecurity` accepts it on
`/api/runtime-gateway/` and nowhere else. Hermes finds it again on session
- restore through `OPENAI_BASE_URL` = the gateway URL.
+ restore through `OPENAI_BASE_URL` = the gateway URL. A token answers only
+ for the models its route registered, the gateway keeps at most 1024 grants
+ (never dropping one whose turn is running), and `gateway.revoke_agent()`
+ invalidates an agent's tokens when it is deleted or moved to another
+ provider.
- **Translation.** A Chat Completions request becomes a `BrainRequest`
(system text, messages with tool calls and results, function tools, max
tokens, effort); the plugin's stream becomes Chat Completions chunks with
tool calls and usage. Gemini's thought signature, which the OpenAI shape has
- no field for, is kept per tool-call id and sent back with the call. The
+ no field for, is kept per tool-call id and sent back with the call; a call
+ without one (a restart in between, the later calls of a parallel step)
+ still replays as a native call with Google's validator sentinel. The
plugin runs in a task of its own and hands deltas over a queue: its key
- override and cost caller are context variables, and a streamed response is
- read by another task.
+ override, cost caller and agent request profile are context variables, and
+ a streamed response is read by another task. `prompt_tokens` counts the
+ whole prompt, cache reads and writes included, because both runtimes
+ compress from it. A provider's "cut off" stop (`max_tokens`, Gemini's
+ `MAX_TOKENS`, Anthropic's `model_context_window_exceeded`) stays `length`
+ even with tool calls, so a truncated call is retried, never run.
+- **Agent request profile.** The plugins were tuned for voice; the gateway
+ runs them with a profile the voice path never sets
+ (`plugins/brain/_agent_profile.py`): a 300 s read timeout for hosted
+ providers and 900 s for local servers (a reasoning model thinks for
+ minutes before its first token), no temperature unless the runtime chose
+ one, and Anthropic prompt-cache breakpoints on system, tools and the
+ latest message. One provider brain, with its HTTP client, is kept per
+ session, model and credential (LRU of 32) instead of one per call.
- **Failures.** A provider error before the first token becomes an HTTP
- status the runtime backs off on (429 rate limit, 401 refused key, 502
- otherwise); after streaming began it is an `error` chunk. Either way the
- message is Jarvis' own, never the provider's body. Refusals no retry can
- fix are told apart first (`provider_errors.py`): an empty balance or zero
- quota is 402 `billing` even when the provider sent 429 (OpenAI does), a
- provider that cannot be reached (a stopped local server) is 503
- `provider_unreachable`. Hermes treats 402 as billing and stops instead of
- retrying.
-- **Costs.** Every call goes through the plugin, so it lands in the cost
- ledger (caller `agent-runtime`).
+ status and code the runtime acts on; after streaming began it is an `error`
+ chunk (`response.failed` on the subscription). The message is Jarvis' own,
+ never the provider's body; the body goes to the log as one bounded,
+ redacted WARNING line. `provider_errors.py` tells the cases apart: 402
+ `billing` (also when OpenAI sends 429 for an empty balance), 400
+ `context_length_exceeded` (worded "context length exceeded", which both
+ runtimes read as "compress and resend"), 504 `timeout` ("took too long",
+ not "not reachable"), 503 `provider_unreachable` / `provider_overloaded`,
+ 404 `model_not_found`, 400 `tools_unsupported` / `invalid_tool_schema` /
+ `invalid_request`, 401 `provider_auth` / `claude_login_expired`, 429
+ `rate_limited` with a cooldown, 502 `provider_error`. Only the codes no
+ runtime can recover from end the Jarvis turn at once
+ (`provider_errors.TERMINAL_CODES`: billing, Extra Usage, refused key or
+ login, unknown model, tool refusals, rate limit); an overflow, a timeout or
+ an overloaded provider goes back to the runtime's own retry and
+ compression.
+- **Costs.** Every gateway call is metered into the cost ledger (caller
+ `agent-runtime`). From the first metered call on, the cost report bills
+ Hermes / OpenClaw turns from those rows and skips the runtime's own turn
+ report, so no call is counted twice.
+- **Model budgets.** The route refreshes catalog metadata with a bounded wait
+ before writing the runtime config. Hermes receives `model.context_length`;
+ OpenClaw receives `contextWindow` and `maxTokens`. Gateway model discovery
+ includes the selected local model and its limits. A request that names no
+ output limit gets the declared output maximum, but never more than the
+ context window leaves after a conservative prompt estimate (OpenRouter's
+ upstreams and vLLM refuse `prompt + max_tokens > context`, and many models
+ declare an output maximum as large as the window); an explicit request
+ limit is kept, capped at the model's maximum. Ollama uses the `num_ctx`
+ chosen on the model card (bounded by the native window) and otherwise
+ 65,536 tokens, never the whole native window by default: Ollama reserves
+ the KV cache up front, and a 30B model at 256k needs about 45 GB. Its
+ provider prepares an isolated model profile with that allocation before
+ inference. An explicit positive `num_predict` remains effective. Unknown output capacity
+ is omitted from runtime metadata rather than invented as an 8k limit; a
+ request with neither metadata nor an explicit budget uses the brain's normal
+ request default. Unknown context still uses plugin metadata (32k otherwise)
+ until the catalog can establish the real capacity.
- **ChatGPT subscription.** Handing the login to the runtime would make a
second program refresh it, and OAuth refresh tokens are single-use:
whichever refreshed first would break the other, including the person's
own Codex login. The gateway answers with Jarvis' subscription client on the
agent's Codex account, whose refresh is coordinated in one place
(`live/subscription_auth.py`); a failure mid-stream is `response.failed`.
+ A runtime's thinking level is snapped to one the selected ChatGPT model
+ offers (from the account's catalog, no inference), and a `system` or
+ `developer` input message moves into the instructions, which ChatGPT's
+ backend requires.
- **Claude subscription: billed as extra usage.** Claude runs on an
Anthropic API key when one is saved. Without one, the gateway answers on
the person's live Claude Code login (read-only: only the Claude CLI renews
- it, so an expired login waits until Claude Code runs again). Anthropic bills
+ it, so an expired login fails with `claude_login_expired` and says to open
+ Claude Code once). Anthropic bills
a subscription used outside Claude Code as extra usage, not from the plan's
limits, so the model picker labels that seat "billed as extra usage"
(`login_providers` on `/api/agent-runtimes`). A Claude login (`sk-ant-oat…`)
saved in the Anthropic API-key slot is never sent as an API key.
- Measured 2026-10-07: with Extra Usage turned off on the account, Haiku
- still answers from the plan, while Sonnet, Opus and Fable get a bare 429
- `rate_limit_error` although the plan has room. The gateway then reads the
- account's usage report (`/api/oauth/usage`, no inference) and says why:
- Extra Usage off or its monthly limit spent (402), or a plan window really
- used up (429 until its reset). The gateway sends Anthropic the agent's own
- request; it never presents itself as Claude Code.
+ Measured 2026-10-07: Anthropic serves a subscription to Hermes and
+ OpenClaw only from the account's Extra Usage ("Third-party apps now draw
+ from your extra usage, not your plan limits", HTTP 400; Sonnet, Opus and
+ Fable sometimes answer a bare 429 instead), for every model including
+ Haiku. Before the runtime starts, `route_for` reads the account's usage
+ report (`/api/oauth/usage`, no inference, cached two minutes) and refuses
+ the turn at once when Extra Usage is off or its monthly limit is spent;
+ a refusal that still arrives is reported as 402 with the same reason. The
+ gateway sends Anthropic the agent's own request; it never presents itself
+ as Claude Code.
`scripts/spikes/agent_runtimes_gateway_e2e.py <runtime> <provider> [model]`
runs two real turns through the gateway (route built by `route_for`, the real
@@ -109,7 +200,9 @@ event format. Verified 2026-10-06: Hermes and OpenClaw on a local Ollama model
history carried into the second turn, no error chunk. Against the live
subscription the account was at its usage limit; that error reached Hermes as
`response.failed`. API-key providers share the plugin path with Ollama but
-were not called live (no paid test calls).
+were not called live (no paid test calls). Re-run 2026-10-07 with `--replay`
+after the gateway hardening: Hermes and OpenClaw on Chat Completions and
+Hermes on the subscription, two turns each, all passing.
The runtime decides which agent loop, native tools and session store a turn
uses. Everything that makes a Jarvis agent stays in Jarvis and is identical
@@ -149,17 +242,56 @@ replayed during `session/load` is swallowed because the chat already shows it.
Bypass allows without a card, Ask shows the card, Plan refuses.
- **A finished turn ends.** After the prompt's answer the runtime gets ten
seconds to exit on its own, then it is ended; the answer already stands.
+- **Stop is a real stop.** Stop, the turn deadline, a provider failure and the
+ stall watchdog first send ACP `session/cancel` and give the runtime five
+ seconds to end its turn, then kill it. An OpenClaw run lives in its Gateway,
+ so killing the bridge alone would leave it calling the model and running
+ tools.
+- **Stall watchdog.** The runtime must open its session within 7 minutes (it
+ may finish its own setup first); afterwards the model must say something
+ within 5 minutes. The counter resets on every ACP frame and pauses while a
+ tool runs or an approval card is open. A stalled turn ends with a plain
+ reason instead of holding the agent's folder for the full hour.
+- **Incomplete answers say so.** `stopReason` `max_tokens`,
+ `max_turn_requests` or `cancelled` without any text is the turn's error;
+ with text the answer stands and a `stop_reason` notice marks it incomplete.
+- **Nothing outlives the turn.** The runtime runs in the turn's process
+ container (Job Object on Windows, process group on POSIX). On POSIX its
+ descendants are also recorded while it runs, so a shell command it started
+ under `setsid` (Hermes does that for every command) is reaped with the turn: the tree is walked while the runtime lives, and every descendant inherits a per-turn `JARVIS_TURN_MARK`, so one that detached between two walks is still found by its environment.
+ A frame larger than the 16 MB read limit ends the turn with a plain error.
## Hermes
- **Process:** `hermes acp`, one process per turn, stdin EOF ends it (exit 0).
-- **Isolation:** one Hermes profile per agent, `HERMES_HOME` under Jarvis' data
- directory. The user's own `~/.hermes` / default profile is never touched.
-- **Config Jarvis writes** (`config.yaml`): `model.provider` / `model.default` /
+- **Profiles of one Jarvis data root:** every agent folder is a Hermes profile,
+ `HERMES_HOME=<runtimes_root>/hermes-home/profiles/<agent>`. Hermes keeps its
+ Python dependency environment (about 700 MB) per *data root*, and a profile
+ shares its root's. With a root per agent, every agent's first turn — and the
+ first after every Hermes update — spent about two minutes building its own
+ (measured 84–136 s); now the setup job prepares the shared root once per
+ Hermes build (`hermes profile list` under a setup profile, 37–45 s measured
+ on Windows) and a first turn starts in seconds (6.8–8.3 s measured, replay
+ model). The root is Jarvis' own, not the person's Hermes home: a profile of
+ their home would read, and rotate, their own Hermes logins through Hermes'
+ global-root credential fallback.
+- **Never on the user's PATH:** Hermes' home maintenance publishes launchers
+ into `<data root>/bin` and, on Windows, registers that folder in the user's
+ PATH. The shared root keeps a *file* named `bin`, so that step fails before
+ it touches the registry; on macOS and Linux the config sets
+ `cli.expose_on_path: false`. Older builds left one PATH entry per agent
+ folder; `path_cleanup` removes exactly those (entries inside an
+ `agent_runtimes` folder) once per app run. An agent's old folder is moved:
+ its session store is copied into the profile, then the old folder and its
+ private environment are removed.
+- **Config Jarvis writes** (`config.yaml`): `_config_version` from the pins (so
+ Hermes migrates the file forward), `model.provider` / `model.default` /
`model.base_url`, `terminal.cwd` = the agent workspace, Hermes' own memory
- and skill nudges off (Jarvis owns memory and skills), and `SOUL.md` = the
- agent's Jarvis briefing. The only key is the gateway token, in the process
- environment.
+ and skill nudges off (Jarvis owns memory and skills), the `browser`,
+ `computer_use` and `cronjob` toolsets always disabled (Jarvis has a visible
+ browser and its own routines; Hermes' browser is a headless Chromium), and
+ `SOUL.md` = the agent's Jarvis briefing. The only key is the gateway token,
+ in the process environment.
- **Jarvis tools:** passed per session in `session/new` / `session/load`
`mcpServers` (HTTP with headers); `HERMES_ACP_SKIP_CONFIGURED_MCP=1` keeps
any configured servers out. Hermes names them `mcp__jarvis__<tool>`.
@@ -172,14 +304,19 @@ replayed during `session/load` is swallowed because the chat already shows it.
`key_env`. Jarvis therefore also writes `model.base_url` and passes the
gateway token as `OPENAI_API_KEY` with `OPENAI_BASE_URL` = the gateway URL,
the pair that path reads, in that one process' environment only.
-- **Tool search:** Hermes defers MCP schemas behind its own `tool_search` by
- default; OpenClaw does the same for local models. Both are switched off for
- agent profiles (`tools.tool_search: false`, `tools.toolSearch: false`): in a
- live turn a 9B local model never found the deferred Jarvis tools, and with
- them offered directly both runtimes called `society_wiki_note` correctly.
- The price is prompt size — about 69k input tokens per model call instead of
- about 27k on a fresh Hermes session (prompt caching covers roughly half of
- it from the second call on).
+- **Tool search:** Hermes agents keep MCP schemas behind Hermes' own
+ `tool_search` (`tools.tool_search.enabled: on`, listing capped at 2000
+ tokens): connected accounts can expose hundreds of tools, and offering them
+ all cost about 69k input tokens per call. The profile's `SOUL.md` tells the
+ model to search, describe and call through `tool_search` / `tool_describe` /
+ `tool_call` and to answer greetings directly; a resumed session's pinned
+ eager tool catalog is invalidated first (`tool_snapshot.py`) so the deferred
+ configuration takes effect. OpenClaw still offers the tools directly
+ (`tools.toolSearch: false`): a 9B local model never found deferred tools there.
+- **Not yet covered:** Hermes discovers ambient credentials (for example the
+ GitHub CLI's `gh auth token` for Copilot) into each profile's credential
+ pool. Jarvis' config never routes a model call to them; switching the
+ discovery off needs an upstream setting.
## OpenClaw
@@ -194,16 +331,29 @@ replayed during `session/load` is swallowed because the chat already shows it.
`OPENCLAW_CONFIG_PATH`) and one Gateway per agent folder, on its own
loopback port, started on the first turn and stopped after 15 idle minutes.
A changed config restarts the Gateway (with no turn in flight) instead of
- trusting its file watcher to have reloaded in time. Start-up is
- about 16 s on Windows with the preset (measured with 2026.9.8). The user's
- own `~/.openclaw` and their Gateway service are never touched.
+ trusting its file watcher to have reloaded in time. Start-up took 17–26 s
+ on Windows with the plugins below denied (46 s before). The user's own
+ `~/.openclaw` and their Gateway service are never touched.
+- **Supervision:** the Gateway counts as ready when `GET /healthz` answers 200
+ from a live child — a bare TCP accept could be another program that took
+ the port, which is retried once on a fresh port. Each folder's Gateway holds
+ a cross-process lock and records `gateway.pid` (pid, port, creation time); a
+ Gateway an earlier app left running after a crash or force-quit (POSIX,
+ where no Job Object reaps it) is stopped before a new one starts — only the
+ recorded process, never a recycled pid. Descendants that left its process
+ group are reaped with it.
- **Config Jarvis writes** (`openclaw.json`, only long-stable keys):
`gateway.{mode,port,bind,auth}`, `models.providers.<id>` for the agent's
model, `agents.defaults.{model.primary,workspace,heartbeat.every:"0m"}`,
- `session.reset.mode:"none"`, `mcp.servers.jarvis`, and `tools.deny` for
- native tools that duplicate Jarvis features (automations, messaging).
- A Gateway exit code 78 (invalid config) runs
- `openclaw doctor --fix --yes --non-interactive` once, then retries.
+ `session.reset.mode:"none"`, `mcp.servers.jarvis`, `tools.deny` for native
+ tools that duplicate Jarvis features (automations, messaging, the browser),
+ `plugins.deny` for the bundled browser, canvas, desktop-control
+ (`cua-computer`), device-pairing, file-transfer, location, voice, GitHub and
+ Linux-node plugins, and `logging.file` inside the agent's state folder
+ (OpenClaw otherwise appends every Gateway's log to one shared temp-folder
+ file). A Gateway exit code 78 (invalid config) runs
+ `openclaw doctor --fix --yes --non-interactive` once (contained, killed
+ after two minutes), then retries.
- **Jarvis tools:** OpenClaw rejects per-session `mcpServers`, so the Jarvis
server is configured in the agent's own state directory. Values such as
`${JARVIS_CONTROL_API_KEY}` are substituted from the Gateway's environment,
@@ -214,8 +364,14 @@ replayed during `session/load` is swallowed because the chat already shows it.
- **Heartbeat:** OpenClaw runs a background model turn every 30 minutes by
default. Jarvis sets `heartbeat.every: "0m"` for every agent: nothing the
person did not start may bill a key.
-- **Node:** OpenClaw 2026.9 requires Node `>=24.16 <25 || >=26.1`. The runtime
- manager reports an unsuitable Node instead of failing a turn.
+ Its native cron scheduler and memory-core plugin/slot are also disabled:
+ disabling heartbeat alone still allowed a managed dreaming job at startup.
+- **Node:** OpenClaw 2026.9 requires Node `>=24.16 <25 || >=26.1`. Jarvis' own
+ copy brings Node 24.21; a person's own install on an unsuitable Node is
+ reported (`problem_kind: node`) and replaced by Jarvis' copy.
+- **Not yet covered:** on Windows a Gateway is stopped with
+ `TerminateProcess`, skipping its own shutdown drain; a graceful stop needs a
+ console-less signal path upstream.
## Spike
@@ -237,6 +393,33 @@ model through Jarvis' own drivers (profile and config writing, process
environment, the OpenClaw Gateway supervisor): two turns in one conversation,
no key written into the runtime's folder, no process left behind.
+## CI and release gates
+
+A change the `agent_runtimes` lane covers (the runtimes, the chat and society
+code that drives them, their fakes and spikes; the table lives in
+`scripts/ci/agent_runtime_suite.py`) runs three jobs, and `CI gate` waits for
+each of them:
+
+| Job | Where | What it proves |
+|---|---|---|
+| `agent-runtimes-unit` | Linux, Windows, macOS on the portable base install | The runtime drivers, gateway, ACP runner, chat service, send queue, controls, society binding, roster, routines and society routes (`python scripts/ci/agent_runtime_suite.py`). Fakes only. |
+| `agent-runtimes-headless` | `python:3.11-slim` | The runtime package imports and its tests pass on a server with no GPU, audio or desktop stack, and the app's Hermes setup without curl stops with "Setup needs curl". |
+| `agent-runtimes-e2e` | Linux, Windows, macOS × Hermes, OpenClaw | `scripts/ci/agent_runtime_e2e.py`: the app's own setup job (`manager.wait_ready`) installs the release pinned in `jarvis/agent_runtimes/runtime-versions.json` with a desktop app's PATH, never npm or a manual installer. Then two turns per model-gateway protocol against scripted providers (`--replay`), the fake-model driver check with turn-1 budgets (Hermes 30 s, OpenClaw 90 s), `pytest tests/unit/agent_runtimes`, and proof that the Windows user PATH gained no `agent_runtimes` entry and OpenClaw edited no shell profile. No key and no network to a model. |
+
+The impact selection of the Windows pull-request leg adds the same suite
+whenever the lane is on, so a runtime change also runs the chat and society
+tests, not only the tests that import the changed module.
+
+`agent-runtimes-canary.yml` runs weekly and on dispatch. In its own checkout
+it points the pin at upstream latest (`agent_runtime_suite.py
+--point-at-latest`) and runs the same app-setup check on all three OSes. When a runtime passes on every OS, the
+`raise-pin` job records its version (and Hermes' upstream commit from
+`hermes --version`, never a local checkout's HEAD; the installers pin Hermes
+by `--commit` / `-Commit`) and opens a pull request that changes
+`runtime-versions.json`. That pull request is the admission of a new upstream
+release: its CI run is the pinned check above. A failed scheduled canary opens
+an issue and leaves the pin where it is.
+
## Code map
| Piece | Where |
@@ -246,6 +429,10 @@ no key written into the runtime's folder, no process left behind.
| Jarvis provider → runtime endpoint and key | `jarvis/agent_runtimes/model_map.py` |
| Hermes driver | `jarvis/agent_runtimes/hermes.py` |
| OpenClaw driver and Gateway supervisor | `jarvis/agent_runtimes/openclaw.py` |
+| Pinned releases (minimum, tested, Hermes commit) and their reader | `jarvis/agent_runtimes/runtime-versions.json`, `jarvis/agent_runtimes/versions.py` |
+| One-time cleanup of PATH entries older setups left behind | `jarvis/agent_runtimes/path_cleanup.py` |
+| Every process a runtime starts, tracked for shutdown | `jarvis/core/process_tree.py` (`DescendantTracker`) |
+| CI: lane table, pins for CI, canary pin raise; setup-through-the-app check | `scripts/ci/agent_runtime_suite.py`, `scripts/ci/agent_runtime_e2e.py` |
| Turn planning for the chat | `jarvis/agent_chat/runner_acp.py` |
| Process, pump, rollover, approvals (shared with every CLI seat) | `jarvis/agent_chat/runner_cli.py` |
| The agent's `runtime` field | `jarvis/society/roster.py`, `society_schema.sql` |
diff --git a/docs/ci-pipeline.md b/docs/ci-pipeline.md
index 8c94ce7fe5..148c4ab8bb 100644
--- a/docs/ci-pipeline.md
+++ b/docs/ci-pipeline.md
@@ -27,7 +27,7 @@ agent branch ──► pull request ──► CI (lanes) ──► CI gate ─
| `tests windows` | The whole suite in four shards on every run with the python lane, pull requests included, so Windows-only failures block before the merge. | — |
| `tests macos 1..3` | Nightly and manual runs only (~10x runner cost). | — |
| `test report + floor` | Proves the six Linux shards cover every discovered file exactly once, enforces the min-passed floor, and on main refreshes the duration cache. Detection freezes one shared duration snapshot for all shards, including partial reruns. | `scripts/ci/ratchet_tests.py` |
-| Lanes | `frontend`, `jarvisctl`, `deps`, `realtime` (3 OS + slim container), `updater` (3 OS: in-app update, native handover, restart helper), `dragdrop`, `browser`, `macOS desktop`, `installer smoke` — each only when its paths change. | — |
+| Lanes | `frontend`, `jarvisctl`, `deps`, `realtime` (3 OS + slim container), `updater` (3 OS: in-app update, native handover, restart helper), `agent runtimes` (3 OS + slim container + the real Hermes and OpenClaw at their pinned version; see [agent-runtimes.md](agent-runtimes.md#ci-and-release-gates)), `dragdrop`, `browser`, `macOS desktop`, `installer smoke` — each only when its paths change. | — |
| `release qualification` | Tag CI requires a full run with macOS and the browser-auth E2E evidence gate: a plugin labeled verified needs a completed journey, every completed journey ships as verified, and every other plugin ships labeled preview. The step summary counts both. Ordinary branch/PR/nightly CI skips this release-only job. | `scripts/ci/check_plugin_auth_contract.py --require-e2e-pass` |
| `CI gate` | Aggregates every job. **The only required check**, on the pull request and again on its merge-queue group. A missing or skipped selected lane fails. Unselected lanes may skip; nightly is strict except event-specific jobs. | `scripts/ci/required_results.py` |
diff --git a/docs/os-parity.md b/docs/os-parity.md
index 175ffecb63..6958c21aea 100644
--- a/docs/os-parity.md
+++ b/docs/os-parity.md
@@ -1285,7 +1285,7 @@ build: the first release with this code needs one live update per OS.
| P-41 | Medium | Dictation final pass | The dictation lane reads its final pass on the machine, in front of any configured cloud provider, through the same out-of-process worker the live preview uses (`jarvis.dictation.preview_worker`) with a stronger checkpoint (`[dictation].local_model`, default `large-v3-turbo`, `int8_float16`, beam 5). 2026-09-02 forensics: 220 of 220 dictations had run on a cloud recognizer the settings did not name, because the VOICE lane had been moved there to keep CUDA out of the desktop process, and the dictation lane inherited the move — round-trips as lag, near-empty answers on 25 s windows as "truncated window" repairs. The provider declines itself with a CROSSABLE failure (HTTP-503-shaped, `LocalEngineUnavailable`) so the configured provider is one step behind on every press and never a restart away: too little free accelerator memory (`[dictation].local_min_free_gb`, default 1.5; an UNKNOWN reading never blocks), a worker that only comes up on the CPU, a missing local runtime, a worker that died. A call abandoned at its ceiling leaves its answer in the pipe, so the next call kills that worker instead of reading it (AP-24) | `jarvis/dictation/local_final.py::LocalFinalSTT`, `jarvis/speech/pipeline.py::_dictation_local_final`, `_dictation_stt`, `jarvis/dictation/local_preview.py::_spawn_worker_model` (`compute`), `preview_worker.py` (`beam_size`, `segments`), `jarvis/hardware/detection.py::free_accelerator_gb` | Windows/Linux with an NVIDIA card and the local runtime: the final pass runs locally when ≥ 1.5 GB is free, else the cloud chain. macOS: no NVIDIA reading → the memory gate passes as unknown, and the worker's own device ladder decides; a CPU-only worker is declined for the final pass (a beam decode of a 25 s window on a CPU is slower than the cloud it would replace), so Apple Silicon stays on the configured provider until a Metal-backed runtime exists. Headless `python:3.11-slim` (no `faster-whisper`): the provider is never built and the chain is exactly what it was. Switch: `[dictation].local_engine = false`. Guards: `tests/unit/dictation/test_local_final.py`, `test_preview_worker.py` |
| P-41 | Low | CLI install / connect terminal | Pressing **Install** or **Connect** in the CLI section opens a REAL terminal window and runs the command there, because an interactive OAuth login belongs in a shell the user can see and type into. That spawn was Windows-only until 2026-08-28 (`wt` -> `pwsh` -> `powershell`), so on macOS and Linux the two buttons reported "No external terminal available" and no CLI could be installed from the app at all. macOS now goes through `osascript` to Terminal.app, Linux through the first of seven emulators that exists (Debian's `x-terminal-emulator` alternative first, so the user's own default wins), and the window is held open afterwards the way `-NoExit` holds it on Windows. One install click now carries all the way to signed in: the terminal runs the install, refreshes PATH in that same shell, and continues into the CLI's login command, stopping at the first step that fails. The chain operator differs per OS on purpose — Windows PowerShell 5.1 is a possible fallback shell and `&&` is a parser error there, so the Windows spelling nests `if ($?)` instead | `jarvis/clis/external_terminal.py` (`_spawn_windows`, `_spawn_macos`, `_spawn_linux`, `chain_commands`, `path_refresh_command`), `jarvis/ui/web/cli_routes.py::spawn_external`, `tests/unit/clis/test_install_path.py` | Windows: verified live (wt path, composed install+login command). macOS/Linux: same code path, the branch itself unverified from this machine. A box with no screen has no window to open, so there the endpoint falls back to the in-app streaming install job and the UI says so instead of claiming a terminal appeared — a headless server can still install a CLI, it just cannot run an interactive login |
| P-42 | High | Outbound sockets (every lane) | Every connection borrows an ephemeral port from a pool the OS owns, and a closed one keeps that port through TIME_WAIT. The ceiling and the linger differ per OS, and so does what gives out first: **Windows** 16 384 ports / 120 s — the tightest by far, and the port pool is what empties, which stops EVERY process on the machine from connecting (the desktop appears frozen, then heals itself when TIME_WAIT expires); **Linux** 28 232 ports / 60 s, but `RLIMIT_NOFILE` is normally the tighter of the two (1024 on a stock `python:3.11-slim`), so the backend dies of EMFILE while the desktop around it is fine; **macOS** 16 384 ports / 15 s, so it recovers fastest. BUG-215 was the Windows shape: an unjittered wake storm (one socket per pane, per window, per instance, all on one `visibilitychange`) on top of a standing per-call-client burn. The rule that follows is to cap the burst, never to widen a limit — code that fits the Windows budget fits everywhere | `jarvis/ui/web/frontend/src/lib/connectBudget.ts` (`jitteredDelay`, `spreadDelay`, `requestConnect`), `jarvis/core/http_pool.py` (`HttpClientPool`, `SyncHttpClientPool`, `default_limits`), `jarvis/core/socket_budget.py` (`read_platform_limits`, `take_census`, `SocketBudgetWatchdog`), `jarvis/realtime/local_server/supervisor.py::_port_open` (`SO_LINGER`) | Identical on all three: one shared connect budget in the frontend, pooled keep-alive clients in Python, and a watchdog armed by BOTH entry points (desktop shell and `--headless`) that reads the ceiling per platform — `netsh` on Windows (parsed as integers, because it translates its own field names), `/proc/sys/net/ipv4/ip_local_port_range` plus `RLIMIT_NOFILE` on Linux, `sysctl net.inet.ip.portrange.*` on macOS. A host that answers none of them falls back to the documented default and says the number was assumed; a host with no ceiling at all logs one line and throttles nothing, because a watchdog that cannot see must never be what stops the app working. macOS additionally refuses the system-wide socket table to an unprivileged process, so the census there counts this process only and labels the number a floor. Guards: `tests/contract/test_socket_budget.py` (all three hosts faked, plus a German and a Japanese `netsh`), `tests/unit/core/test_socket_budget_watchdog.py`, `jarvis/ui/web/frontend/src/lib/connectBudget.test.ts` |
-| P-45 | Medium | Hermes / OpenClaw agent runtimes | A society agent can run on Hermes or OpenClaw instead of Jarvis' own loop (docs/agent-runtimes.md). Both are separately installed programs driven over ACP: Hermes as one `hermes acp` process per turn on the agent's own `HERMES_HOME`, OpenClaw through `openclaw acp` against a supervised per-agent Gateway. Process containment differs per OS exactly as for every CLI seat: a Job Object on Windows, a process group on POSIX; killing the app reaps the OpenClaw Gateway on Windows (verified live), on POSIX the Gateway is also stopped by the society shutdown and the idle reaper. Install and update use each project's own installer per OS (`install.ps1` on Windows, `install.sh` on macOS/Linux, Hermes' `hermes update`, OpenClaw's `openclaw update --no-restart`) and run on their own: when an agent is set to a runtime that is missing or too old, before a turn on it, and once a day while an agent uses it (only when no turn runs). OpenClaw needs Node.js 24.16+ or 26.1+; its installer provisions a private Node.js where the system one is older | `jarvis/agent_runtimes/` (`hermes.py`, `openclaw.py`, `base.py::child_env`, `manager.py`), `jarvis/agent_chat/runner_acp.py`, `jarvis/core/process_tree.py` | Windows: both runtimes verified live 2026-10-06 (Hermes 0.20.6, OpenClaw 2026.9.8, local Ollama model, memory read and write through the Jarvis tools). macOS/Linux: the same code path, verified only by the weekly `agent-runtimes-canary.yml` workflow (latest Hermes and OpenClaw, fake model). Headless `python:3.11-slim`: nothing is installed or started unless an agent is switched to a runtime; Hermes' Linux installer needs git and curl, OpenClaw needs a supported Node.js. Guards: `tests/unit/agent_runtimes/`, `tests/unit/society/test_agent_runtime_field.py` |
+| P-45 | Medium | Hermes / OpenClaw agent runtimes | A society agent can run on Hermes or OpenClaw instead of Jarvis' own loop (docs/agent-runtimes.md), driven over ACP: Hermes as one `hermes acp` process per turn, every agent a profile of one Jarvis-owned Hermes data root (`<runtimes_root>/hermes-home/profiles/<agent>`, one shared dependency environment, prepared by the setup job); OpenClaw through `openclaw acp` against a supervised per-agent Gateway. Setup goes to the pinned `tested` release (`runtime-versions.json`) per OS: Hermes' `install.ps1` / `install.sh` at the pinned commit without browser tools or desktop control; OpenClaw as Jarvis' own copy with a private Node.js — `install.ps1 -NodeOnly` plus that Node's npm on Windows (no winget/UAC), `install-cli.sh --prefix` on macOS/Linux (no sudo). POSIX installer scripts are downloaded first and run under `set -euo pipefail`, so a missing `curl`/`git` or a failed download fails the job with a plain reason. Containment differs per OS exactly as for every CLI seat: a Job Object on Windows; a process group on POSIX plus a descendant tracker that also reaps children started under `setsid` (Hermes runs shell commands that way), found by tree walks and by a per-turn environment mark every descendant inherits, and a `gateway.pid` sweep that stops a Gateway a crashed app left behind (POSIX only — the Job Object already reaps it on Windows). Hermes' Windows home maintenance would register its data root's `bin` on the user's PATH; a `bin` file blocks that, POSIX uses `cli.expose_on_path: false`, and stale entries from older builds are removed once per run. Stop sends ACP `session/cancel` before any kill, and a stall watchdog ends a turn whose runtime stopped responding | `jarvis/agent_runtimes/` (`hermes.py`, `openclaw.py`, `base.py` (`which`, `RuntimeGate`, `HomeFileLock`, `posix_installer`, `windows_installer`), `manager.py`, `versions.py`, `runtime-versions.json`, `path_cleanup.py`), `jarvis/agent_chat/runner_cli.py` (ACP cancel + stall watchdog), `jarvis/core/process_tree.py::DescendantTracker`, `jarvis/core/path_augment.py::refresh_from_persistent_path` | Windows: verified 2026-10-07 with Hermes 0.21.5 and OpenClaw 2026.9.8 through the replay e2e spikes (both model-gateway protocols; Hermes prepare 37–45 s once, first turn 6.8–8.3 s; OpenClaw first turn 31–55 s including the Gateway cold start; the user PATH unchanged, checked against the registry), and through `tests/unit/agent_runtimes/` (fake ACP agent, fake OpenClaw CLI, injected registry). macOS/Linux: the same code paths; the setsid reaping, `flock` locks, `install-cli.sh` and `pipefail` wrapper run only on POSIX CI runners (unit tests, `agent-runtimes-canary.yml`), not verified on a real Mac or Linux desktop from this machine. Headless `python:3.11-slim`: nothing is installed or started unless an agent is switched to a runtime; without `curl`/`git` the setup fails with that reason instead of reporting success. Guards: `tests/unit/agent_runtimes/`, `tests/unit/society/test_agent_runtime_field.py` |
## Agent conversation continuity and learning (2026-09-07)
diff --git a/jarvis.spec b/jarvis.spec
index 18bcd1c9a0..fc58a1bf25 100644
--- a/jarvis.spec
+++ b/jarvis.spec
@@ -92,6 +92,10 @@ datas.append((str(PROJECT_ROOT / "jarvis/society/browser/native_window.py"), "ja
datas.append((str(PROJECT_ROOT / "jarvis/society/browser/manual_chrome.py"), "jarvis/society/browser"))
datas.append((str(PROJECT_ROOT / "jarvis/society/browser/window_actions.py"), "jarvis/society/browser"))
datas.append((str(PROJECT_ROOT / "jarvis/society/browser/pointer.py"), "jarvis/society/browser"))
+# The Hermes / OpenClaw pins (agent_runtimes/versions.py). The package-data
+# sweep below also finds them; named here so a narrower sweep cannot drop them
+# and send a frozen app's setup to upstream latest.
+datas.append((str(PROJECT_ROOT / "jarvis/agent_runtimes/runtime-versions.json"), "jarvis/agent_runtimes"))
# The local voice engine runs in its OWN Python environment, so a frozen build
# must ship its sources as plain files: setup copies them into the engine home
diff --git a/jarvis/agent_chat/control.py b/jarvis/agent_chat/control.py
index b2807b6ef4..28b53ef40c 100644
--- a/jarvis/agent_chat/control.py
+++ b/jarvis/agent_chat/control.py
@@ -262,6 +262,12 @@ class ChatControls:
if state.goal and state.goal.status == "active":
return {"started": sid in self.jobs}
if not state.last_request or state.last_status not in ("interrupted", "failed"):
+ if self._last_failure_was_not_yours(sid):
+ raise ValueError(
+ "The task that failed last came from Jarvis, a teammate or a "
+ "routine, not from you, so /continue cannot resume it. Ask the "
+ "agent yourself, or let the sender try again."
+ )
raise ValueError("There is no interrupted task to continue")
return {
"turn_id": await self._send(
@@ -528,6 +534,25 @@ class ChatControls:
state.last_status = "failed"
await self.publish(state)
+ def _last_failure_was_not_yours(self, sid: str) -> bool:
+ """Whether the chat's latest turn failed and the person did not start it.
+
+ The service emits a person's ``user_message`` right before its
+ ``turn_started``; work delivered by Jarvis, a teammate or a routine has
+ none, and ``/continue`` only resumes the person's own request
+ (``turn_completed``).
+ """
+ events = self.service.store.list_events(sid)
+ finished = [e for e in events if e["kind"] == "turn_finished"]
+ if not finished or finished[-1]["payload"].get("status") not in ("error", "cancelled"):
+ return False
+ turn_id = finished[-1]["payload"].get("turn_id")
+ for index, event in enumerate(events):
+ if event["kind"] == "turn_started" and event["payload"].get("turn_id") == turn_id:
+ before = [e for e in events[:index] if e["kind"] != "notice"]
+ return not before or before[-1]["kind"] != "user_message"
+ return False
+
async def turn_completed(
self, sid: str, turn_id: str, text: str, direct_user: bool, read_only: bool
) -> None:
diff --git a/jarvis/agent_chat/events.py b/jarvis/agent_chat/events.py
index 9322e051f2..045e66ad19 100644
--- a/jarvis/agent_chat/events.py
+++ b/jarvis/agent_chat/events.py
@@ -26,7 +26,9 @@ Kinds (``payload`` keys in brackets):
``tool_call`` [turn_id, call_id, name, input]
``tool_result`` [turn_id, call_id, output, is_error, duration_ms]
``approval_required`` [turn_id, approval_id, call_id, name, input, summary]
-``approval_resolved`` [turn_id, approval_id, decision] decision: allow | deny
+``approval_resolved`` [turn_id, approval_id, decision] decision: allow |
+ allow_always | deny | cancel | expired (nothing waits
+ on the card any more: a restart, or the call asked again)
``question_required`` [turn_id, question_id, asker, questions, deferred?] — a question
card; ``deferred`` = an end-of-turn card (turn_prompts)
whose answers go to the agent as the next message
diff --git a/jarvis/agent_chat/runner_acp.py b/jarvis/agent_chat/runner_acp.py
index ad67f24c5a..4d084d26e7 100644
--- a/jarvis/agent_chat/runner_acp.py
+++ b/jarvis/agent_chat/runner_acp.py
@@ -12,20 +12,18 @@ driver in ``jarvis.agent_runtimes``). The turn itself is driven over ACP by
from __future__ import annotations
import asyncio
-import functools
import logging
from pathlib import Path
from typing import Any
-from jarvis.agent_runtimes import RUNNER_RUNTIMES, driver
+from jarvis.agent_runtimes import RUNNER_RUNTIMES, driver, gateway
from jarvis.agent_runtimes.acp import AcpTurn
from jarvis.agent_runtimes.base import RuntimeTurn, RuntimeUnavailable
-from jarvis.agent_runtimes.model_map import RouteUnavailable, route_for
+from jarvis.agent_runtimes.model_map import RouteUnavailable, prepare_route
log = logging.getLogger(__name__)
-#: Society capability ids whose explicit denial switches the runtime's own
-#: matching tools off as well.
+#: Native tools must honor the same capability selection as the MCP surface.
_NATIVE_GROUPS: dict[str, str] = {"core:shell": "shell", "core:browser": "web"}
@@ -59,8 +57,43 @@ def _config() -> Any:
return load_config()
+#: ``supported_parameters`` a catalog lists for a model that reasons.
+_REASONING_PARAMETERS: frozenset[str] = frozenset(
+ {"reasoning", "include_reasoning", "reasoning_effort"}
+)
+
+
+def model_capabilities(provider: str, model: str) -> tuple[bool | None, bool | None]:
+ """``(reasons, reads_images)`` as the model catalog DECLARES them.
+
+ ``None`` = the catalog says nothing (no cached entry, or a provider whose
+ feed carries no such field): the runtime keeps its own default. Never a
+ provider- or model-name rule (AP-21). Blocking (catalog cache file).
+ """
+ from jarvis.brain.model_catalog import ModelCatalog
+
+ try:
+ info = ModelCatalog().cached_model(provider, model)
+ except Exception as exc: # noqa: BLE001 — an unreadable cache means "unknown"
+ log.debug("agent runtimes: catalog entry of %s/%s unreadable: %s", provider, model, exc)
+ return None, None
+ if info is None:
+ return None, None
+ params = info.supported_parameters
+ inputs = info.input_modalities
+ reasons = bool(_REASONING_PARAMETERS & set(params)) if params is not None else None
+ vision = ("image" in inputs) if inputs is not None else None
+ return reasons, vision
+
+
def _denied_native(agent: Any, plan_mode: bool) -> frozenset[str]:
- denied = {group for cap, group in _NATIVE_GROUPS.items() if cap in (agent.denies or [])}
+ grants = set(agent.grants or [])
+ denies = set(agent.denies or [])
+ denied = {
+ group
+ for cap, group in _NATIVE_GROUPS.items()
+ if cap in denies or (str(agent.grant_mode) == "allowlist" and cap not in grants)
+ }
if plan_mode:
denied.add("shell")
return frozenset(denied)
@@ -81,7 +114,7 @@ async def _ready(handle: Any, runtime_name: str, runtime: Any) -> None:
current = manager.job(runtime_name)
setting_up = current is not None and current.state == "running"
status = await asyncio.to_thread(runtime.detect)
- if status.ready and not setting_up:
+ if not setting_up and manager.needed(runtime, status) is None:
return
await handle.emit(
make_event(
@@ -97,8 +130,7 @@ async def _ready(handle: Any, runtime_name: str, runtime: Any) -> None:
)
status = await manager.wait_ready(runtime_name)
if not status.ready:
- current = manager.job(runtime_name)
- reason = (current.message if current is not None else "") or status.problem
+ reason = manager.failure_reason(runtime_name) or status.problem
raise CliUnavailable(f"{runtime.label} could not be set up. {reason}".strip())
@@ -128,20 +160,19 @@ async def plan_runtime_turn(
if agent is None:
raise CliUnavailable(f"{runtime_name.title()} runs society agents only.")
try:
- route = await asyncio.to_thread(
- functools.partial(
- route_for,
- _config(),
- session.provider,
- session.model,
- agent_id=agent.agent_id,
- account_id=getattr(session, "account_id", "") or "",
- )
+ route = await prepare_route(
+ _config(), session.provider, session.model,
+ agent_id=agent.agent_id,
+ account_id=getattr(session, "account_id", "") or "",
+ session_id=session.session_id,
)
except RouteUnavailable as exc:
raise CliUnavailable(str(exc)) from exc
plan_mode = session.permission_mode in ("plan", "read-only")
tools = not getattr(handle, "tools_disabled", False)
+ from jarvis.agent_chat.effort import normalize_effort
+
+ reasoning, vision = await asyncio.to_thread(model_capabilities, route.provider, route.model)
turn = RuntimeTurn(
agent_id=agent.agent_id,
agent_name=agent.name,
@@ -153,6 +184,9 @@ async def plan_runtime_turn(
mcp_url=jarvis_harness.endpoint() if tools else None,
control_key=jarvis_harness.control_key() if tools else None,
denied_native=_denied_native(agent, plan_mode),
+ effort=normalize_effort(session.provider, getattr(session, "effort", "") or ""),
+ reasoning=reasoning,
+ vision=vision,
)
runtime = driver(runtime_name)
await _ready(handle, runtime_name, runtime)
@@ -160,6 +194,18 @@ async def plan_runtime_turn(
launch = await runtime.launch(turn)
except RuntimeUnavailable as exc:
raise CliUnavailable(str(exc)) from exc
+ try:
+ failure = gateway.watch_failure(route.api_key or "")
+ except Exception:
+ if launch.release is not None:
+ launch.release()
+ raise
+
+ def release() -> None:
+ gateway.unwatch_failure(route.api_key or "", failure)
+ if launch.release is not None:
+ launch.release()
+
text = _PLAN_PREAMBLE + prompt if plan_mode else prompt
acp = AcpTurn(
turn_id=handle.turn_id,
@@ -180,5 +226,6 @@ async def plan_runtime_turn(
vendor_session=None,
keep_stdin=True,
acp=acp,
- after_turn=launch.release,
+ after_turn=release,
+ provider_failure=failure,
)
diff --git a/jarvis/agent_chat/runner_cli.py b/jarvis/agent_chat/runner_cli.py
index c911d250f3..82a9126c22 100644
--- a/jarvis/agent_chat/runner_cli.py
+++ b/jarvis/agent_chat/runner_cli.py
@@ -63,6 +63,7 @@ import shutil
import time
import uuid
from collections.abc import Callable
+from concurrent.futures import Future
from contextlib import contextmanager
from contextvars import ContextVar
from dataclasses import dataclass, field, replace
@@ -463,6 +464,8 @@ class CliPlan:
acp: Any | None = None
#: Called once the process is gone (a runtime releasing its Gateway).
after_turn: Callable[[], None] | None = None
+ #: The local gateway knows failures that a runtime may render as prose.
+ provider_failure: Future[str] | None = None
def claude_control_init() -> str:
@@ -492,6 +495,30 @@ def claude_control_init() -> str:
)
+def claude_session_rules(tool_name: str, suggestions: Any) -> list[dict[str, Any]]:
+ """What "Always allow" answers Claude Code: its own rule, for this session.
+
+ A ``can_use_tool`` request carries ``permission_suggestions`` — the rule
+ its own prompt would offer ("don't ask again for git log commands here").
+ Those name a settings file as their destination; the chat keeps them to
+ the running session, so a click never writes into the person's repo or
+ user settings. Without a suggestion the tool itself is allowed.
+ """
+ rules = [
+ {**rule, "destination": "session"}
+ for rule in (suggestions if isinstance(suggestions, list) else [])
+ if isinstance(rule, dict) and rule.get("type")
+ ]
+ return rules or [
+ {
+ "type": "addRules",
+ "rules": [{"toolName": tool_name}],
+ "behavior": "allow",
+ "destination": "session",
+ }
+ ]
+
+
def claude_stream_input(prompt: str) -> str:
"""One NDJSON user message for ``--input-format stream-json``."""
return (
@@ -1382,6 +1409,21 @@ _CLAUDE_CODE_RUNNERS: Final[frozenset[str]] = frozenset({"claude-cli", "glm-cli"
#: How long an ACP runtime may keep running after it answered the prompt.
_ACP_EXIT_GRACE_S: Final[float] = 10.0
+#: An ACP runtime gets this long after ``session/cancel`` to end its turn
+#: itself (an OpenClaw run lives in its Gateway, so killing the bridge alone
+#: would leave it working and billing) before the process is killed.
+_ACP_CANCEL_GRACE_S: Final[float] = 5.0
+
+#: Stall watchdog for ACP turns (AP-19), checked every tick:
+#: * the runtime must open its session within the handshake limit — generous,
+#: since a runtime may finish its own setup first (Hermes after an update);
+#: * afterwards, the model must say something within the idle limit. The
+#: counter resets on every frame, and pauses while a tool runs or the
+#: person has an approval card open (both take as long as they take).
+_ACP_HANDSHAKE_TIMEOUT_S: Final[float] = 420.0
+_ACP_IDLE_TIMEOUT_S: Final[float] = 300.0
+_ACP_WATCH_TICK_S: Final[float] = 2.0
+
def _release_plan(plan: CliPlan | None) -> None:
"""Run a plan's ``after_turn`` once (an external runtime's turn slot)."""
@@ -3588,6 +3630,14 @@ async def _spawn_child(
plan: CliPlan, cwd: Path, tree: Any, runner: str
) -> asyncio.subprocess.Process | _Outcome:
"""Start the CLI as this process's own child (no turn host)."""
+ if plan.acp is not None and plan.env is not None and os.name != "nt":
+ # Every descendant inherits this mark, so the turn's tracker finds a
+ # detached one even when no snapshot saw it (POSIX; Windows: the job).
+ from uuid import uuid4
+
+ from jarvis.core.process_tree import TURN_MARKER_ENV
+
+ plan.env[TURN_MARKER_ENV] = uuid4().hex
try:
proc = await asyncio.create_subprocess_exec(
*plan.argv,
@@ -3652,10 +3702,20 @@ async def _drive_cli(
plain_id = f"plain-{handle.turn_id}"
stderr_tail: list[str] = []
+ def _provider_error() -> str | None:
+ signal = plan.provider_failure
+ if signal is not None and signal.done() and not signal.cancelled():
+ return signal.result()
+ return None
+
async def _drain_stderr() -> None:
assert proc.stderr is not None
while True:
- line = await proc.stderr.readline()
+ try:
+ line = await proc.stderr.readline()
+ except ValueError:
+ # A diagnostic line past the read limit: dropped, never fatal.
+ continue
if not line:
return
text = line.decode("utf-8", errors="replace").rstrip()
@@ -3675,10 +3735,25 @@ async def _drive_cli(
)
async def _pump_stdout() -> None:
- nonlocal grace_kill
+ nonlocal grace_kill, status, error_text
assert proc.stdout is not None
while True:
- raw = await proc.stdout.readline()
+ try:
+ raw = await proc.stdout.readline()
+ except ValueError:
+ # One line past _READLINE_LIMIT. For an ACP runtime that is a
+ # broken frame of the turn itself: end it with a plain reason
+ # instead of an unhandled error. Other CLIs: skip the line.
+ if plan.acp is None:
+ continue
+ status = "error"
+ error_text = (
+ f"{runner} sent a message larger than "
+ f"{_READLINE_LIMIT // (1024 * 1024)} MB; the turn was stopped."
+ )
+ _kill(proc)
+ return
+ activity[0] = time.monotonic()
if hosted and getattr(proc, "handed_over", False):
return
if not raw:
@@ -3706,8 +3781,16 @@ async def _drive_cli(
translate(obj, state)
continue
if plan.acp is not None:
+ if _provider_error():
+ # Do not present a runtime's synthetic error prose as an
+ # assistant answer, or process tools after the failure.
+ continue
await plan.acp.on_message(obj, acp_io)
if plan.acp.saw_result:
+ if tracker is not None:
+ # Last look at its children while the runtime still
+ # lives: once it exits, detached ones are orphans.
+ tracker.snapshot()
# The prompt answered; closing stdin lets the runtime exit.
# One that keeps running anyway (a child holding the pipe)
# is ended so the chat is not held busy by a finished turn.
@@ -3794,6 +3877,13 @@ async def _drive_cli(
)
if decision in {"allow", "allow_always"}:
body: dict[str, Any] = {"behavior": "allow", "updatedInput": req.get("input") or {}}
+ if decision == "allow_always" and subtype == "can_use_tool":
+ # Without a rule the CLI asked again at the very next call of
+ # this turn: the session's new access mode only reaches the
+ # next process.
+ body["updatedPermissions"] = claude_session_rules(
+ tool_name, req.get("permission_suggestions")
+ )
if bridge is not None and subtype == "can_use_tool":
# A Jarvis tool the CLI just asked about will hit the executor's
# own gate over MCP in a moment; the person has answered once.
@@ -3894,8 +3984,78 @@ async def _drive_cli(
if not plan.keep_stdin:
_close_stdin()
+ async def _acp_cancel() -> None:
+ """Ask an ACP runtime to end its turn (``session/cancel``), then wait briefly.
+
+ Killing the process alone is not a stop for every runtime: an OpenClaw
+ run lives in its Gateway and keeps calling the model and running
+ tools after its bridge dies. The caller kills afterwards either way.
+ """
+ if plan.acp is None or hosted or proc.returncode is not None:
+ return
+ frame = plan.acp.cancel_frame()
+ if frame is None:
+ return
+ from jarvis.agent_runtimes.acp import frame_line
+
+ await _write_stdin(frame_line(frame))
+ deadline = time.monotonic() + _ACP_CANCEL_GRACE_S
+ while time.monotonic() < deadline:
+ if plan.acp.saw_result or proc.returncode is not None:
+ return
+ await asyncio.sleep(0.1)
+
async def _watch_cancel() -> None:
await handle.cancel.wait()
+ await _acp_cancel()
+ _kill(proc)
+
+ async def _watch_provider_failure() -> None:
+ nonlocal status, error_text
+ if plan.provider_failure is None:
+ return
+ error_text = await asyncio.wrap_future(plan.provider_failure)
+ status = "error"
+ await _acp_cancel()
+ if tree is not None:
+ # Descendants can hold stdout open after the runtime exits. Reap
+ # the containment group now, before waiting for either pipe.
+ tree.close()
+ _kill(proc)
+
+ async def _watch_stall() -> None:
+ """End an ACP turn whose runtime stopped making progress (AP-19)."""
+ nonlocal status, error_text
+ acp = plan.acp
+ if acp is None or hosted:
+ return
+ started = time.monotonic()
+ reason = ""
+ while not acp.saw_result and proc.returncode is None:
+ await asyncio.sleep(_ACP_WATCH_TICK_S)
+ now = time.monotonic()
+ if approval_pending[0] or acp.tool_running():
+ activity[0] = now # a person or a tool sets this pace
+ continue
+ if not acp.handshaken:
+ if now - started > _ACP_HANDSHAKE_TIMEOUT_S:
+ reason = (
+ f"{runner} did not open its session within "
+ f"{int(_ACP_HANDSHAKE_TIMEOUT_S // 60)} minutes; the turn was stopped."
+ )
+ break
+ continue
+ if now - activity[0] > _ACP_IDLE_TIMEOUT_S:
+ reason = (
+ f"{runner} stopped responding (nothing for "
+ f"{int(_ACP_IDLE_TIMEOUT_S // 60)} minutes); the turn was stopped."
+ )
+ break
+ if not reason or acp.saw_result:
+ return
+ log.warning("agent chat %s: %s", handle.turn_id, reason)
+ status, error_text = "error", reason
+ await _acp_cancel()
_kill(proc)
class _AcpIO:
@@ -3910,7 +4070,12 @@ async def _drive_cli(
await handle.emit(event)
async def ask(self, call_id: str, name: str, args: dict[str, Any], summary: str) -> str:
- decision = await handle.request_approval(call_id, name, args, summary)
+ approval_pending[0] = True
+ try:
+ decision = await handle.request_approval(call_id, name, args, summary)
+ finally:
+ approval_pending[0] = False
+ activity[0] = time.monotonic()
if decision in {"allow", "allow_always"} and bridge is not None:
# A Jarvis tool the runtime just asked about reaches the
# executor's own gate over MCP next; the person answered once.
@@ -3919,11 +4084,24 @@ async def _drive_cli(
acp_io = _AcpIO()
grace_kill: asyncio.TimerHandle | None = None
+ # Stall watchdog state: the last stdout frame, and an open approval card.
+ activity = [time.monotonic()]
+ approval_pending = [False]
+ # POSIX: descendants that leave the process group (setsid) are remembered
+ # while the runtime runs and reaped with it (Windows: the job object).
+ tracker = None
+ if plan.acp is not None and tree is not None and not hosted and placement is None:
+ from jarvis.core.process_tree import TURN_MARKER_ENV, DescendantTracker
+
+ tracker = DescendantTracker(proc.pid, marker=(plan.env or {}).get(TURN_MARKER_ENV))
+ tracker.start()
pump = asyncio.create_task(_pump_stdout())
drain = asyncio.create_task(_drain_stderr())
feeder = asyncio.create_task(_feed_stdin())
watcher = asyncio.create_task(_watch_cancel())
+ provider_watcher = asyncio.create_task(_watch_provider_failure())
+ stall_watcher = asyncio.create_task(_watch_stall())
try:
# EOF is not process exit: a CLI may close both pipes and keep
# running. The deadline must also cover waiting for the process.
@@ -3940,6 +4118,7 @@ async def _drive_cli(
proc.returncode,
pump.done(),
)
+ await _acp_cancel()
_kill(proc)
status = "error"
error_text = f"{runner} did not finish within {int(_TURN_TIMEOUT_S)} s."
@@ -3953,10 +4132,17 @@ async def _drive_cli(
raise
finally:
watcher.cancel()
+ provider_watcher.cancel()
+ stall_watcher.cancel()
for task in (pump, drain, feeder):
if not task.done():
task.cancel()
- await asyncio.gather(watcher, pump, drain, feeder, return_exceptions=True)
+ await asyncio.gather(
+ watcher, provider_watcher, stall_watcher, pump, drain, feeder,
+ return_exceptions=True,
+ )
+ if tracker is not None:
+ tracker.close()
if tree is not None:
tree.close()
if proc.returncode is None and not getattr(proc, "detached", False):
@@ -3981,6 +4167,8 @@ async def _drive_cli(
error_text = "The process that ran this agent stopped unexpectedly."
if handle.cancel.is_set():
status = "cancelled"
+ elif provider_error := _provider_error():
+ status, error_text = "error", provider_error
elif status == "done":
if state.status == "error":
status, error_text = (
diff --git a/jarvis/agent_chat/send_queue.py b/jarvis/agent_chat/send_queue.py
index dff43741ab..34b753b5ca 100644
--- a/jarvis/agent_chat/send_queue.py
+++ b/jarvis/agent_chat/send_queue.py
@@ -6,7 +6,11 @@ turn is still running. Instead of a "turn already running" refusal, the
message waits here and starts as the next turn once the agent's seat is free.
The queue lives in memory and is bounded per chat, in size and in waiting
-time. Every queued message is a ``message_queued`` notice in the chat; when it
+time. While the chat's own turn runs, that turn bounds the wait (its setup,
+slot and run timeouts: a Hermes or OpenClaw agent's first turn may install
+its runtime for many minutes); :data:`MAX_WAIT_S` counts only the time the
+chat is idle yet still cannot take the message, and :data:`MAX_TOTAL_WAIT_S`
+caps the wait as a whole. Every queued message is a ``message_queued`` notice in the chat; when it
starts (or cannot be sent) a ``message_dequeued`` notice with the same
``queue_id`` replaces it, so the timeline shows a waiting message exactly
while it waits. A restart forgets the queue, so opening the chat afterwards
@@ -25,12 +29,26 @@ from typing import Any, Final
log = logging.getLogger(__name__)
-__all__ = ["MAX_QUEUED", "MAX_WAIT_S", "QueueFull", "close_orphans", "send_or_queue"]
+__all__ = [
+ "MAX_QUEUED",
+ "MAX_TOTAL_WAIT_S",
+ "MAX_WAIT_S",
+ "QueueFull",
+ "close_orphans",
+ "send_or_queue",
+]
#: Messages one chat may hold while its agent works.
MAX_QUEUED: Final[int] = 5
-#: How long a message may wait for the agent before it is reported unsent.
+#: How long a message may wait while the chat is idle but the agent's seat is
+#: still taken elsewhere (another of its chats, a delegation), before it is
+#: reported unsent.
MAX_WAIT_S: Final[float] = 600.0
+#: The longest any message waits, a running turn included. Above the longest
+#: turn the runner allows: a runtime setup (30 min, ``agent_runtimes.manager``),
+#: the runtime's turn slot (15 min, ``agent_runtimes.base``) and the run (60 min,
+#: ``runner_cli._TURN_TIMEOUT_S``).
+MAX_TOTAL_WAIT_S: Final[float] = 2.5 * 3600
#: How often a waiting chat checks whether its agent is free (seconds).
_POLL_S: Final[float] = 0.5
#: How far back opening a chat looks for waiting notices a restart orphaned.
@@ -50,6 +68,8 @@ class _Queued:
attachments: list[dict[str, Any]] | None
tool_choices: list[str] | None
queued_at: float = 0.0
+ #: Seconds the chat was idle yet could not take this message.
+ blocked_s: float = 0.0
@dataclass(slots=True)
@@ -157,22 +177,27 @@ async def _drain_loop(svc: Any, session_id: str, pending: _ChatQueue) -> None:
from jarvis.agent_chat.service import SessionBusy
loop = asyncio.get_running_loop()
+ checked = loop.time()
while pending.items:
# Jitter only spreads polls of several waiting chats; it is not security.
await asyncio.sleep(_POLL_S + random.uniform(0, _POLL_S / 2)) # noqa: S311
+ now = loop.time()
+ step, checked = now - checked, now
head = pending.items[0]
- if loop.time() - head.queued_at > MAX_WAIT_S:
+ if head.blocked_s > MAX_WAIT_S or now - head.queued_at > MAX_TOTAL_WAIT_S:
# The agent stayed busy too long: report it instead of waiting forever.
pending.items.popleft()
await _fail(svc, session_id, head)
continue
if svc.is_running(session_id):
+ # The chat's own turn bounds this wait with its own timeouts.
continue
try:
await svc.send(
session_id, head.text, head.attachments, tool_choices=head.tool_choices
)
except SessionBusy: # the seat is still taken: this message simply waits longer
+ head.blocked_s += step
continue
except Exception: # noqa: BLE001 — reported in the chat, then the next one runs
# The detail stays in the log; a provider's text never reaches the chat.
diff --git a/jarvis/agent_chat/service.py b/jarvis/agent_chat/service.py
index d933bb5469..8518245812 100644
--- a/jarvis/agent_chat/service.py
+++ b/jarvis/agent_chat/service.py
@@ -26,6 +26,7 @@ import re
import shutil
import sqlite3
import time
+import traceback
import uuid
from collections.abc import Callable
from dataclasses import replace
@@ -67,6 +68,18 @@ from jarvis.society.delivery import IncomingMessage
log = logging.getLogger(__name__)
+
+def _stop_caller() -> str:
+ """The code that asked a turn to stop, as ``module:function`` hops.
+
+ A stopped turn otherwise only says "cancelled"; this names the path that
+ ended it (HTTP stop, goal pause, society runtime, browser cancel).
+ """
+ frames = traceback.extract_stack(limit=6)[:-2]
+ return " <- ".join(
+ f"{Path(frame.filename).stem}:{frame.name}" for frame in reversed(frames)
+ )
+
#: What a turn cut off by a restart says (``_seal_orphaned_turns``).
_ORPHANED_TURN_ERROR: Final = (
"Jarvis restarted while this turn was running. "
@@ -366,6 +379,10 @@ class AgentChatService:
self._event_listeners: list[Callable[[str, dict[str, Any]], None]] = []
self._approvals: dict[str, asyncio.Future[str]] = {}
self._approval_session: dict[str, str] = {}
+ # Cards a restart left unanswered on a thread turn the turn host kept
+ # running, by (session, turn, call): the CLI asks again and that card
+ # answers it (_hold_unanswered_approvals).
+ self._unanswered: dict[tuple[str, str, str], str] = {}
# Questions an agent is waiting on (questions.py), by question id.
self._questions: dict[str, _OpenQuestion] = {}
self._question_tasks: set[asyncio.Task[None]] = set()
@@ -569,10 +586,19 @@ class AgentChatService:
stance=session.permission_mode if kit.uses_stance else "",
control_service=self,
)
+ superseded = self._hold_unanswered_approvals(session_id, turn_id, handle.history)
async def _carry_on() -> None:
finished = False
try:
+ for approval_id in superseded:
+ await self._emit(
+ session_id,
+ make_event(
+ "approval_resolved",
+ {"turn_id": turn_id, "approval_id": approval_id, "decision": "expired"},
+ ),
+ )
vendor = await resume_hosted_cli_turn(handle, proc)
finished = True
if vendor and vendor != session.vendor_session:
@@ -619,6 +645,8 @@ class AgentChatService:
self._approval_session.pop(aid, None)
if fut is not None and not fut.done():
fut.set_result("cancel")
+ for key in [k for k in self._unanswered if k[:2] == (session_id, turn_id)]:
+ self._unanswered.pop(key, None)
self._cancel_questions(session_id)
if finished and kit.turn_prompts:
try:
@@ -629,6 +657,45 @@ class AgentChatService:
run.task = asyncio.create_task(_carry_on(), name=f"agent-chat-{turn_id[:8]}")
run.ready.set()
+ def _hold_unanswered_approvals(
+ self, session_id: str, turn_id: str, history: list[dict[str, Any]]
+ ) -> list[str]:
+ """Keep a restart's open approval cards for the CLI to ask again.
+
+ The previous process waited on the card's answer when it quit; the CLI
+ in the turn host still waits on its permission prompt, and the host
+ replays that line because it was never acknowledged, so the resumed
+ runner asks again. That question must reuse the card already on screen:
+ a fresh id left the old card on top of the composer, and its buttons
+ answered "no such pending approval" for ever (2026-10-06). The newest
+ open card per tool call is held for :meth:`_ask`; the ids returned are
+ older duplicates (or cards without a call id) that only get closed.
+ """
+ open_by_call: dict[str, list[str]] = {}
+ resolved: set[str] = set()
+ for event in history:
+ payload = event.get("payload") or {}
+ if str(payload.get("turn_id") or "") != turn_id:
+ continue
+ approval_id = str(payload.get("approval_id") or "")
+ if not approval_id:
+ continue
+ if event.get("kind") == "approval_resolved":
+ resolved.add(approval_id)
+ elif event.get("kind") == "approval_required":
+ call_id = str(payload.get("call_id") or "")
+ open_by_call.setdefault(call_id, []).append(approval_id)
+ superseded: list[str] = []
+ for call_id, ids in open_by_call.items():
+ still_open = [aid for aid in dict.fromkeys(ids) if aid not in resolved]
+ if not still_open:
+ continue
+ if call_id:
+ self._unanswered[(session_id, turn_id, call_id)] = still_open[-1]
+ still_open = still_open[:-1]
+ superseded.extend(still_open)
+ return superseded
+
def _retire_cli_seats(self) -> None:
"""Move chats off a CLI seat their surface no longer offers.
@@ -1472,6 +1539,12 @@ class AgentChatService:
# The CLI keeps working in the turn host; the next app
# start carries this turn on, so it stays open.
raise
+ log.info(
+ "agent chat %s: turn %s task was cancelled (stop flag %s)",
+ session_id,
+ turn_id,
+ "set" if run.cancel.is_set() else "NOT set",
+ )
await self._emit(
session_id,
make_event(
@@ -1759,6 +1832,12 @@ class AgentChatService:
if expected_turn_id is not None and run.turn_id != expected_turn_id:
return False
run.cancel.set()
+ log.info(
+ "agent chat %s: turn %s told to stop by %s",
+ session_id,
+ run.turn_id,
+ _stop_caller(),
+ )
if run.task is None and run.setup_task is not None:
run.setup_task.cancel()
for aid in self.pending_approvals(session_id):
@@ -1846,7 +1925,10 @@ class AgentChatService:
args: dict[str, Any],
summary: str,
) -> str:
- approval_id = uuid.uuid4().hex
+ # The same tool call asked again after a restart answers on the card
+ # the person already sees (_hold_unanswered_approvals).
+ held = self._unanswered.pop((session_id, turn_id, call_id), "") if call_id else ""
+ approval_id = held if held and held not in self._approvals else uuid.uuid4().hex
loop = asyncio.get_running_loop()
fut: asyncio.Future[str] = loop.create_future()
self._approvals[approval_id] = fut
@@ -1914,6 +1996,39 @@ class AgentChatService:
fut.set_result(decision)
return True
+ async def close_stale_approval(self, session_id: str, approval_id: str) -> bool:
+ """Close a card the transcript still shows open but nothing waits on.
+
+ Its asker is gone — an app restart took the waiting call with it, or
+ the CLI asked again under another card. Answering it can change
+ nothing, so the card is closed for good instead of offering buttons
+ that fail on every click and come back on every reload. Returns
+ whether such a card was found.
+ """
+ if approval_id in self._approvals:
+ return False
+ turn_id = ""
+ for event in await asyncio.to_thread(self.store.list_events, session_id):
+ payload = event.get("payload") or {}
+ if str(payload.get("approval_id") or "") != approval_id:
+ continue
+ if event.get("kind") == "approval_resolved":
+ return False
+ if event.get("kind") == "approval_required":
+ turn_id = str(payload.get("turn_id") or "")
+ if not turn_id:
+ return False
+ for key in [k for k, v in self._unanswered.items() if v == approval_id]:
+ self._unanswered.pop(key, None)
+ await self._emit(
+ session_id,
+ make_event(
+ "approval_resolved",
+ {"turn_id": turn_id, "approval_id": approval_id, "decision": "expired"},
+ ),
+ )
+ return True
+
# ------------------------------------------------------------ questions
async def open_questions(
diff --git a/jarvis/agent_chat/task_recovery.py b/jarvis/agent_chat/task_recovery.py
index 311bdb2fdd..b90d0d98ed 100644
--- a/jarvis/agent_chat/task_recovery.py
+++ b/jarvis/agent_chat/task_recovery.py
@@ -37,6 +37,9 @@ _TERMINAL = (
"not authenticated",
"quota",
"credit balance",
+ "http 429",
+ "rate limit",
+ "rate-limited",
)
_DISCOVERY = frozenset({"toolsearch", "list_tools", "tools-list", "search_tools"})
diff --git a/jarvis/agent_runtimes/acp.py b/jarvis/agent_runtimes/acp.py
index 42d8cf7db0..67409906fb 100644
--- a/jarvis/agent_runtimes/acp.py
+++ b/jarvis/agent_runtimes/acp.py
@@ -55,6 +55,13 @@ RESUME_LOST_ERROR: Final[str] = "ACP session not found"
#: JSON-RPC "method not found".
_METHOD_NOT_FOUND: Final[int] = -32601
+#: ``stopReason`` values that end a turn before its answer was complete.
+_STOPPED_EARLY: Final[dict[str, str]] = {
+ "max_tokens": "The answer stopped at the model's output limit.",
+ "max_turn_requests": "The agent reached its step limit for one turn.",
+ "cancelled": "The turn was cancelled before it finished.",
+}
+
#: ``mcp_<server>_<tool>`` (Hermes) and ``<server>__<tool>`` spellings of a
#: Jarvis MCP tool, normalised to the ``mcp__jarvis__<tool>`` form the
#: society checkpoints and quests read.
@@ -203,6 +210,27 @@ class AcpTurn:
}
)
+ def cancel_frame(self) -> dict[str, Any] | None:
+ """The ``session/cancel`` notification for the running prompt (``None`` when
+ no prompt is in flight). The agent answers the prompt with
+ ``stopReason: cancelled`` once its turn has wound down."""
+ if not self._acp_session or self.saw_result:
+ return None
+ return {
+ "jsonrpc": "2.0",
+ "method": "session/cancel",
+ "params": {"sessionId": self._acp_session},
+ }
+
+ @property
+ def handshaken(self) -> bool:
+ """Whether the session is open (``session/new`` / ``session/load`` answered)."""
+ return bool(self._acp_session)
+
+ def tool_running(self) -> bool:
+ """Whether a tool call started and has not reported its end yet."""
+ return any(call not in self._finished_tools for call in self._tool_started)
+
def _session_params(self) -> dict[str, Any]:
return {"cwd": self.cwd, "mcpServers": [s.to_acp() for s in self.mcp_servers]}
@@ -292,8 +320,21 @@ class AcpTurn:
self._take_usage(res.get("usage"))
if self.stop_reason == "refusal" and not self.emitted_text:
self._fail("The model refused this request.")
- elif self.stop_reason in {"max_tokens", "max_turn_requests"} and not self.emitted_text:
- self._fail(f"The agent stopped early ({self.stop_reason}).")
+ elif self.stop_reason in _STOPPED_EARLY and not self.emitted_text:
+ self._fail(_STOPPED_EARLY[self.stop_reason])
+ elif self.stop_reason in _STOPPED_EARLY:
+ # The answer stands, but the chat says it is not the whole one.
+ await io.emit(
+ make_event(
+ "notice",
+ {
+ "kind": "stop_reason",
+ "turn_id": self.turn_id,
+ "stop_reason": self.stop_reason,
+ "text": _STOPPED_EARLY[self.stop_reason],
+ },
+ )
+ )
return
async def _on_agent_request(self, obj: dict[str, Any], method: str, io: AcpIO) -> None:
@@ -542,6 +583,21 @@ def _tool_name(update: dict[str, Any]) -> str:
def _error_text(error: dict[str, Any]) -> str:
message = str(error.get("message") or "error")
data = error.get("data")
+ if isinstance(data, dict):
+ # Hermes' ACP SDK nests this local configuration failure under
+ # details. Translate only the known numeric contract; never expose
+ # arbitrary upstream details (which may contain provider bodies).
+ detail = str(data.get("details") or "")
+ bounds = re.search(
+ r"context window of ([\d,]+) tokens, which is below the minimum "
+ r"([\d,]+) required by Hermes Agent\.", detail,
+ )
+ if bounds:
+ actual, minimum = bounds.groups()
+ return (
+ f"Hermes requires at least {minimum} context tokens; this model has {actual}. "
+ "Increase the model context in Settings or choose a model with a larger window."
+ )
if isinstance(data, str) and data:
return f"{message}: {data}"
if isinstance(data, dict) and data.get("message"):
diff --git a/jarvis/agent_runtimes/base.py b/jarvis/agent_runtimes/base.py
index 42e2e282a9..930de00ea3 100644
--- a/jarvis/agent_runtimes/base.py
+++ b/jarvis/agent_runtimes/base.py
@@ -18,10 +18,12 @@ The program itself is the standard install the official installer makes.
from __future__ import annotations
import asyncio
+import contextlib
import json
import logging
import os
import re
+import shlex
import shutil
import subprocess
import sys
@@ -115,6 +117,11 @@ class RuntimeStatus:
problem_kind: str = ""
#: The official install/update command, for display.
install_hint: str = ""
+ #: Ready, but newer than the release the canary verified (still runs).
+ untested: bool = False
+ #: The first line of ``--version`` (names the exact build, not just the
+ #: release); internal, never shown.
+ build: str = ""
def to_dict(self) -> dict[str, Any]:
return {
@@ -127,6 +134,7 @@ class RuntimeStatus:
"problem": self.problem,
"problem_kind": self.problem_kind,
"install_hint": self.install_hint,
+ "untested": self.untested,
}
@@ -150,6 +158,13 @@ class RuntimeTurn:
control_key: str | None = None
#: Native capability groups this agent may not use (``"shell"``, ``"web"``).
denied_native: frozenset[str] = frozenset()
+ #: The agent's reasoning effort on Jarvis' ladder (``none`` … ``max``);
+ #: ``""`` = the model's own default.
+ effort: str = ""
+ #: What the model catalog DECLARES about the model (``None`` = unknown):
+ #: it reasons / it reads images. Never inferred from a provider or model name.
+ reasoning: bool | None = None
+ vision: bool | None = None
@dataclass(slots=True)
@@ -198,6 +213,9 @@ class AgentRuntimeDriver(Protocol):
#: How long a turn waits for the agent's previous turn on the same runtime.
_SLOT_WAIT_S: Final[float] = 15 * 60
+#: How long a turn waits for another process to let go of the agent's folder.
+_HOME_LOCK_WAIT_S: Final[float] = 60.0
+
def home_key(agent_id: str, chat_session_id: str) -> str:
"""Which runtime folder a chat's turns use.
@@ -209,16 +227,140 @@ def home_key(agent_id: str, chat_session_id: str) -> str:
return agent_id if chat_session_id == f"society:{agent_id}" else f"{agent_id}~runs"
+class RuntimeGate:
+ """Turns share a runtime; its setup jobs (install, update, prepare) take it alone.
+
+ An updater replaces files a running turn holds open (on Windows it cannot)
+ and stops the runtime's background processes, so a setup job waits until
+ no turn runs, and turns that arrive meanwhile wait for the job.
+ """
+
+ def __init__(self) -> None:
+ self.turns = 0
+ self._exclusive = False
+ self._exclusive_waiting = 0
+ self._waiters: list[asyncio.Future[None]] = []
+
+ def _notify(self) -> None:
+ waiters, self._waiters = self._waiters, []
+ for waiter in waiters:
+ if not waiter.done():
+ waiter.set_result(None)
+
+ async def _wait_until(self, ready: Callable[[], bool], timeout_s: float) -> None:
+ loop = asyncio.get_running_loop()
+ deadline = loop.time() + timeout_s
+ while not ready():
+ left = deadline - loop.time()
+ if left <= 0:
+ raise TimeoutError
+ waiter: asyncio.Future[None] = loop.create_future()
+ self._waiters.append(waiter)
+ with contextlib.suppress(TimeoutError): # re-checked by the loop condition
+ await asyncio.wait_for(waiter, left)
+
+ async def acquire_turn(self, timeout_s: float) -> None:
+ await self._wait_until(
+ lambda: not self._exclusive and not self._exclusive_waiting, timeout_s
+ )
+ self.turns += 1
+
+ def release_turn(self) -> None:
+ self.turns = max(0, self.turns - 1)
+ self._notify()
+
+ @contextlib.asynccontextmanager
+ async def exclusive(self, timeout_s: float) -> Any:
+ """Hold the runtime alone; raises ``TimeoutError`` when turns keep running."""
+ self._exclusive_waiting += 1
+ try:
+ await self._wait_until(lambda: not self._exclusive and self.turns == 0, timeout_s)
+ finally:
+ self._exclusive_waiting -= 1
+ self._notify()
+ self._exclusive = True
+ try:
+ yield
+ finally:
+ self._exclusive = False
+ self._notify()
+
+
+class HomeFileLock:
+ """A cross-process lock on one runtime folder (``msvcrt`` / ``flock``).
+
+ Within one app the asyncio slot already serialises turns; this keeps a
+ second process (a stale app that did not exit, a script) from running the
+ same agent folder at the same time. The OS drops it when the holder dies.
+ """
+
+ def __init__(self, path: Path) -> None:
+ self.path = path
+ self._fd: int | None = None
+
+ def try_acquire(self) -> bool:
+ self.path.parent.mkdir(parents=True, exist_ok=True)
+ fd = os.open(self.path, os.O_RDWR | os.O_CREAT, 0o600)
+ try:
+ os.lseek(fd, 0, os.SEEK_SET)
+ if sys.platform == "win32":
+ import msvcrt
+
+ msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+ else:
+ import fcntl
+
+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+ except OSError: # held elsewhere: the caller retries or gives up
+ os.close(fd)
+ return False
+ self._fd = fd
+ return True
+
+ async def acquire(self, timeout_s: float) -> None:
+ loop = asyncio.get_running_loop()
+ deadline = loop.time() + timeout_s
+ while not self.try_acquire():
+ if loop.time() >= deadline:
+ raise TimeoutError
+ await asyncio.sleep(0.25)
+
+ def release(self) -> None:
+ fd, self._fd = self._fd, None
+ if fd is None:
+ return
+ try:
+ os.lseek(fd, 0, os.SEEK_SET)
+ if sys.platform == "win32":
+ import msvcrt
+
+ msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+ else:
+ import fcntl
+
+ fcntl.flock(fd, fcntl.LOCK_UN)
+ except OSError as exc: # closing the descriptor below releases it anyway
+ log.debug("agent runtimes: unlocking %s failed: %s", self.path, exc)
+ finally:
+ os.close(fd)
+
+
class TurnSlots:
- """One turn at a time per runtime folder.
+ """One turn at a time per runtime folder, inside the runtime's shared gate.
The runtime's config is written per turn; two turns sharing one folder
would read each other's settings. A turn waits for the previous one
(the agent's chat already queues its own messages), and gives up with a
- plain message after :data:`_SLOT_WAIT_S`.
+ plain message after :data:`_SLOT_WAIT_S`. With ``lock_dir`` the folder is
+ also locked against other processes (:class:`HomeFileLock`).
"""
- def __init__(self) -> None:
+ def __init__(
+ self, runtime: str = "runtime", *, lock_dir: Callable[[], Path] | None = None
+ ) -> None:
+ self.runtime = runtime
+ self.gate = RuntimeGate()
+ self._lock_dir = lock_dir
self._locks: dict[str, asyncio.Lock] = {}
def lock(self, key: str) -> asyncio.Lock:
@@ -226,48 +368,99 @@ class TurnSlots:
def busy(self) -> bool:
"""Whether any turn holds a slot right now."""
- return any(lock.locked() for lock in self._locks.values())
+ return self.gate.turns > 0 or any(lock.locked() for lock in self._locks.values())
async def acquire(self, key: str) -> Callable[[], None]:
+ try:
+ await self.gate.acquire_turn(_SLOT_WAIT_S)
+ except TimeoutError:
+ raise RuntimeUnavailable(
+ "Jarvis is still setting this runtime up; try again in a few minutes."
+ ) from None
lock = self.lock(key)
try:
await asyncio.wait_for(lock.acquire(), timeout=_SLOT_WAIT_S)
except TimeoutError:
+ self.gate.release_turn()
raise RuntimeUnavailable(
"This agent is still busy with another task; try again when it is done."
) from None
+ home_lock: HomeFileLock | None = None
+ if self._lock_dir is not None:
+ home_lock = HomeFileLock(self._lock_dir() / f"{self.runtime}-{safe_key(key)}.lock")
+ try:
+ await home_lock.acquire(_HOME_LOCK_WAIT_S)
+ except (TimeoutError, OSError):
+ lock.release()
+ self.gate.release_turn()
+ raise RuntimeUnavailable(
+ "Another Jarvis process is running this agent right now; try again "
+ "when it is done."
+ ) from None
released = False
def release() -> None:
nonlocal released
if not released:
released = True
+ if home_lock is not None:
+ home_lock.release()
lock.release()
+ self.gate.release_turn()
return release
+def _instance_root() -> Path:
+ from jarvis.core.instance import current_instance
+ from jarvis.core.paths import user_data_dir
+
+ identity = current_instance()
+ name = "agent_runtimes" if identity.is_default else f"agent_runtimes-{identity.name}"
+ return user_data_dir() / name
+
+
def runtimes_root() -> Path:
+ """Every runtime folder of THIS app instance.
+
+ The dev instance keeps its own (``agent_runtimes-dev``): its agents live in
+ their own database, and two apps must never run one agent folder at once.
+ """
+ return _instance_root()
+
+
+def tools_root() -> Path:
+ """Where this instance keeps the runtime programs Jarvis installed itself.
+
+ The same folder as :func:`runtimes_root` today, but resolved on its own: a
+ caller that moves the agent folders elsewhere (the e2e spikes keep agent
+ state in a temporary folder) must still find the installed program.
+ """
+ return _instance_root()
+
+
+def legacy_runtimes_root() -> Path:
+ """Where builds before the per-instance layout kept every runtime folder."""
from jarvis.core.paths import user_data_dir
return user_data_dir() / "agent_runtimes"
+def private_dir(path: Path) -> Path:
+ """Create ``path`` readable by this user only (POSIX ``0700``)."""
+ path.mkdir(parents=True, exist_ok=True, mode=0o700)
+ return path
+
+
+def safe_key(key: str) -> str:
+ """A folder name for a runtime home key (``<agent>`` / ``<agent>~runs``)."""
+ return re.sub(r"[^A-Za-z0-9_.-]", "_", key) or "agent"
+
+
def agent_home(runtime: str, agent_id: str) -> Path:
"""The runtime's own state folder for one agent (created on demand)."""
- safe = re.sub(r"[^A-Za-z0-9_.-]", "_", agent_id) or "agent"
- root = runtimes_root() / runtime
- home = root / safe
- legacy_profile = any((home / name).is_file() for name in ("config.yaml", "state.db", "SOUL.md"))
- if runtime == "hermes" and not legacy_profile:
- # Hermes treats an arbitrary HERMES_HOME as a separate installation:
- # every new bot otherwise rebuilds Python dependencies before ACP can
- # answer. Native profile layout shares only the installation while
- # keeping config, credentials and conversations in separate homes.
- # Existing homes retain their state and native session identifiers.
- home = root / "profiles" / safe
- home.mkdir(parents=True, exist_ok=True)
- return home
+ root = private_dir(runtimes_root())
+ return private_dir(root / runtime / safe_key(agent_id))
def child_env(extra: dict[str, str] | None = None) -> dict[str, str]:
@@ -280,8 +473,12 @@ def child_env(extra: dict[str, str] | None = None) -> dict[str, str]:
return env
-def write_if_changed(path: Path, text: str) -> bool:
- """Write UTF-8 text when it differs; True when the file changed."""
+def write_if_changed(path: Path, text: str, *, private: bool = False) -> bool:
+ """Write UTF-8 text when it differs; True when the file changed.
+
+ ``private`` creates the file readable by this user only (POSIX ``0600``)
+ from its first byte, not after a ``chmod``.
+ """
try:
if path.read_text(encoding="utf-8") == text:
return False
@@ -289,7 +486,11 @@ def write_if_changed(path: Path, text: str) -> bool:
pass
path.parent.mkdir(parents=True, exist_ok=True)
tmp = path.with_suffix(path.suffix + ".tmp")
- tmp.write_text(text, encoding="utf-8")
+ with contextlib.suppress(FileNotFoundError):
+ tmp.unlink()
+ fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600 if private else 0o666)
+ with os.fdopen(fd, "w", encoding="utf-8", newline="") as handle:
+ handle.write(text)
os.replace(tmp, path)
return True
@@ -298,6 +499,64 @@ def write_json_if_changed(path: Path, data: dict[str, Any]) -> bool:
return write_if_changed(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+#: Exit code of the installer wrapper when a tool it needs is missing.
+SETUP_MISSING_TOOL_EXIT: Final[int] = 90
+
+
+def posix_installer(
+ url: str, args: list[str], *, requires: tuple[str, ...] = ()
+) -> list[str]:
+ """argv that runs an official ``install.sh`` so that its failures fail the job.
+
+ ``curl … | bash`` exits with bash's status: a missing curl, an offline
+ machine or a 404 hands bash an empty script and the "install" succeeds.
+ Here the script is downloaded first (``set -euo pipefail``), the tools it
+ needs are checked with a plain message, and the installer's own exit
+ status is the job's. Arguments travel as positional parameters, never
+ spliced into the script text.
+ """
+ tools = " ".join(shlex.quote(tool) for tool in ("curl", *requires) if tool)
+ script = (
+ "set -euo pipefail\n"
+ f"for tool in {tools}; do\n"
+ ' if ! command -v "$tool" >/dev/null 2>&1; then\n'
+ ' echo "Setup needs $tool. Install it with your system package manager, '
+ 'then try again." >&2\n'
+ f" exit {SETUP_MISSING_TOOL_EXIT}\n"
+ " fi\n"
+ "done\n"
+ 'script="$(mktemp)"\n'
+ "trap 'rm -f \"$script\"' EXIT\n"
+ f'curl -fsSL --proto "=https" --tlsv1.2 -o "$script" {shlex.quote(url)}\n'
+ 'bash "$script" "$@"\n'
+ )
+ return ["bash", "-c", script, "jarvis-setup", *args]
+
+
+def ps_quote(value: str) -> str:
+ """A PowerShell single-quoted string literal."""
+ return "'" + value.replace("'", "''") + "'"
+
+
+def windows_installer(body: str) -> list[str]:
+ """argv that runs PowerShell installer ``body`` and fails the job on any error."""
+ script = (
+ "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue'; "
+ "[Net.ServicePointManager]::SecurityProtocol = "
+ "[Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12; "
+ + body
+ )
+ return [
+ "powershell",
+ "-NoProfile",
+ "-NonInteractive",
+ "-ExecutionPolicy",
+ "Bypass",
+ "-Command",
+ script,
+ ]
+
+
def parse_version(text: str) -> tuple[int, int, int] | None:
match = _VERSION_RE.search(text or "")
if not match:
@@ -339,9 +598,33 @@ def first_existing(candidates: list[Path]) -> Path | None:
return None
-def which(*names: str) -> str | None:
+def which(
+ *names: str,
+ skip: Callable[[str], bool] | None = None,
+ extra_dirs: tuple[Path, ...] = (),
+) -> str | None:
+ """The first of ``names`` on PATH, then in ``extra_dirs``.
+
+ PATH is first topped up with the well-known install folders a GUI-launched
+ app does not inherit (``path_augment``) — re-checked on every call, so a
+ runtime an in-app setup job just installed is found without a restart.
+ ``skip`` drops PATH entries that must never answer (stale shims).
+ """
+ try:
+ from jarvis.core.path_augment import ensure_cli_paths
+
+ ensure_cli_paths()
+ except Exception as exc: # noqa: BLE001 — augmentation is best-effort; PATH as is
+ log.debug("agent runtimes: PATH augmentation failed: %s", exc)
+ entries = [
+ entry
+ for entry in os.environ.get("PATH", "").split(os.pathsep)
+ if entry and not (skip is not None and skip(entry))
+ ]
+ entries += [str(directory) for directory in extra_dirs]
+ search = os.pathsep.join(entries)
for name in names:
- found = shutil.which(name)
+ found = shutil.which(name, path=search)
if found:
return found
return None
diff --git a/jarvis/agent_runtimes/gateway.py b/jarvis/agent_runtimes/gateway.py
index a97aa015d5..c6d0ab0977 100644
--- a/jarvis/agent_runtimes/gateway.py
+++ b/jarvis/agent_runtimes/gateway.py
@@ -32,15 +32,20 @@ import asyncio
import contextlib
import json
import logging
+import math
import secrets
import threading
import time
import uuid
from collections import OrderedDict
from collections.abc import AsyncIterator
-from dataclasses import dataclass
+from concurrent.futures import Future
+from dataclasses import dataclass, replace
+from email.utils import parsedate_to_datetime
from typing import Any, Final
+from jarvis.agent_runtimes.model_limits import ModelLimits, resolve_limits
+
log = logging.getLogger(__name__)
#: Every gateway route lives under this path (``surface_security`` accepts a
@@ -55,19 +60,18 @@ SUBSCRIPTION_PROVIDER: Final[str] = "openai-codex"
class GatewayError(Exception):
"""A request the gateway cannot answer; ``status`` is the HTTP code."""
- def __init__(self, message: str, *, status: int = 400, code: str = "invalid_request") -> None:
+ def __init__(
+ self,
+ message: str,
+ *,
+ status: int = 400,
+ code: str = "invalid_request",
+ retry_after: float | None = None,
+ ) -> None:
super().__init__(message)
self.status = status
self.code = code
-
-
-def _subscription_message(exc: Exception) -> str:
- """Fixed wording for a failed subscription call; no exception text leaves."""
- from jarvis.live.subscription_auth import SubscriptionAuthError
-
- if isinstance(exc, SubscriptionAuthError) or getattr(exc, "code", "") == "login":
- return "The ChatGPT subscription needs a new sign-in in Jarvis."
- return "The ChatGPT subscription could not answer this turn."
+ self.retry_after = retry_after
@dataclass(frozen=True, slots=True)
@@ -78,39 +82,128 @@ class Grant:
provider: str
#: The provider account (``jarvis.agent_accounts``); "" = the active one.
account_id: str = ""
+ #: The runtime profile: direct chat and serialized scheduled runs differ.
+ scope: str = ""
_LOCK = threading.Lock()
_GRANTS: dict[str, Grant] = {}
-_TOKENS: dict[Grant, str] = {}
+_TOKENS: OrderedDict[Grant, str] = OrderedDict()
+#: Grants kept at once. Each chat session mints its own; the least recently
+#: minted one is forgotten first (its next turn simply mints a new token).
+_GRANTS_MAX: Final[int] = 1024
_CLIENTS: dict[str, Any] = {}
+_MODEL_LIMITS: dict[Grant, dict[str, ModelLimits]] = {}
+_CATALOG: Any = None
+_FAILURES: dict[Grant, Future[str]] = {}
+_COOLDOWNS: OrderedDict[tuple[str, str, str], float] = OrderedDict()
+_DEFAULT_COOLDOWN_S: Final = 30.0
#: Gemini's thought signature per tool call id: the OpenAI wire shape has no
#: field for it, and the next request must carry it back with the call.
_SIGNATURES: OrderedDict[str, str] = OrderedDict()
_SIGNATURES_MAX: Final[int] = 4096
-#: The finish reasons a Chat Completions client knows.
-_FINISH: Final[dict[str, str]] = {"max_tokens": "length", "length": "length"}
+#: Provider stop reasons that mean "cut off", in lower case without an enum
+#: prefix (Gemini's ``FinishReason.MAX_TOKENS``, Anthropic's
+#: ``model_context_window_exceeded``), and those that mean "withheld".
+_LENGTH_REASONS: Final[frozenset[str]] = frozenset(
+ {"length", "max_tokens", "model_context_window_exceeded"}
+)
+_FILTER_REASONS: Final[frozenset[str]] = frozenset(
+ {"content_filter", "safety", "refusal", "recitation", "blocklist", "prohibited_content",
+ "spii"}
+)
+
+
+def _finish(raw: Any) -> str:
+ """A provider stop reason as one Chat Completions knows."""
+ name = str(raw).rsplit(".", 1)[-1].strip().lower()
+ if name in _LENGTH_REASONS:
+ return "length"
+ if name in _FILTER_REASONS:
+ return "content_filter"
+ return "stop"
+
+
+def _final_finish(finish: str, calls: int) -> str:
+ """Tool calls end a normal turn, but a cut-off answer stays "length": a
+ tool call truncated by the output limit has broken arguments, and the
+ runtimes retry it with a larger budget instead of running it."""
+ return "tool_calls" if calls and finish == "stop" else finish
_EFFORTS: Final[frozenset[str]] = frozenset(
{"none", "minimal", "low", "medium", "high", "xhigh", "max"}
)
-def grant_token(agent_id: str, provider: str, account_id: str = "") -> str:
+def grant_token(agent_id: str, provider: str, account_id: str = "", *, scope: str = "") -> str:
"""The token one agent's runtime presents (stable for the app's lifetime,
so a runtime that keeps a process between turns is not restarted)."""
- grant = Grant(agent_id, provider, account_id)
+ grant = Grant(agent_id, provider, account_id, scope)
with _LOCK:
token = _TOKENS.get(grant)
if token is None:
token = f"jrg_{secrets.token_urlsafe(32)}"
_TOKENS[grant] = token
_GRANTS[token] = grant
+ _TOKENS.move_to_end(grant)
+ stale = [
+ old for old in list(_TOKENS)[: max(0, len(_TOKENS) - _GRANTS_MAX)]
+ if old not in _FAILURES # never a grant whose turn is running
+ ]
+ for old in stale:
+ _forget(old)
return token
+def _forget(grant: Grant) -> None:
+ """Drop one grant's token and model registrations. Holds ``_LOCK``."""
+ old_token = _TOKENS.pop(grant, None)
+ if old_token is not None:
+ _GRANTS.pop(old_token, None)
+ _MODEL_LIMITS.pop(grant, None)
+
+
+def revoke_agent(agent_id: str) -> int:
+ """Invalidate every token minted for ``agent_id`` (the agent was deleted
+ or switched to another provider or model): a runtime still holding one
+ gets 401 instead of spending on the old route. Returns how many."""
+ with _LOCK:
+ grants = [grant for grant in _TOKENS if grant.agent_id == agent_id]
+ for grant in grants:
+ _forget(grant)
+ brains = [key for key in _BRAINS if key and key[0] == agent_id]
+ slots = [_BRAINS.pop(key) for key in brains]
+ for slot in slots:
+ slot.retired = True
+ if slot.users == 0:
+ _close_later(slot.brain)
+ return len(grants)
+
+
+def check_model(grant: Grant, model: str) -> None:
+ """Refuse a model the grant was not routed to.
+
+ A token speaks for one agent on the model its route registered; without
+ this check anything holding it could pick a costlier model on the same
+ key. A grant minted without a route has nothing registered and is not
+ restricted.
+ """
+ with _LOCK:
+ allowed = set(_MODEL_LIMITS.get(grant, {}))
+ if not allowed:
+ return
+ if {model, f"{model}:latest", model.removesuffix(":latest")} & allowed:
+ return
+ raise GatewayError(
+ f"This agent runs on {', '.join(sorted(allowed))}; its token cannot use {model}. "
+ "Choose the model in the agent's settings.",
+ status=404,
+ code="model_not_found",
+ )
+
+
def verify(token: str) -> Grant | None:
"""The grant behind ``token``; ``None`` for anything Jarvis did not mint."""
if not token.startswith("jrg_"):
@@ -119,6 +212,165 @@ def verify(token: str) -> Grant | None:
return _GRANTS.get(token)
+def register_model(token: str, model: str, limits: ModelLimits) -> None:
+ """Keep the selected model discoverable, including arbitrary local model ids."""
+ with _LOCK:
+ grant = _GRANTS[token]
+ _MODEL_LIMITS.setdefault(grant, {})[model] = limits
+
+
+def model_limits(grant: Grant, model: str) -> ModelLimits:
+ with _LOCK:
+ found = _MODEL_LIMITS.get(grant, {}).get(model)
+ if found is not None:
+ return found
+ from jarvis.brain.model_catalog import ModelCatalog
+ from jarvis.core.config import load_config
+
+ return resolve_limits(
+ load_config(), grant.provider, model, ModelCatalog().cached_model(grant.provider, model)
+ )
+
+
+async def refresh_model_limits(grant: Grant, model: str, config: Any) -> ModelLimits:
+ """Read catalog facts only; unavailable metadata keeps the conservative budget."""
+ global _CATALOG # one lazy catalog cache; no work on the boot path
+ from types import SimpleNamespace
+
+ from jarvis.brain.model_catalog import ModelCatalog
+ from jarvis.live.subscription_auth import SubscriptionAuthError
+ from jarvis.live.subscription_reasoning import SubscriptionReasoningError
+
+ try:
+ if grant.provider == SUBSCRIPTION_PROVIDER:
+ rows = await asyncio.wait_for(_client(grant.account_id).list_models(), timeout=5)
+ row = next((row for row in rows if row.get("id") == model), {})
+ metadata = SimpleNamespace(**row)
+ else:
+ if _CATALOG is None:
+ _CATALOG = await asyncio.to_thread(ModelCatalog)
+ catalog = await asyncio.wait_for(_CATALOG.list_models(grant.provider), timeout=5)
+ aliases = {model, f"{model}:latest"} if grant.provider == "ollama" else {model}
+ metadata = next((row for row in catalog.models if row.id in aliases), None)
+ except (TimeoutError, SubscriptionAuthError, SubscriptionReasoningError):
+ log.info("runtime gateway: model metadata unavailable for %s", grant.provider)
+ return await asyncio.to_thread(model_limits, grant, model)
+ if metadata is None or (
+ not getattr(metadata, "context_length", None)
+ and not getattr(metadata, "max_output_tokens", None)
+ ):
+ return await asyncio.to_thread(model_limits, grant, model)
+ return resolve_limits(config, grant.provider, model, metadata)
+
+
+def watch_failure(token: str) -> Future[str]:
+ """Observe this session's current turn, across the HTTP and runner loops."""
+ with _LOCK:
+ grant = _GRANTS[token]
+ if grant in _FAILURES:
+ raise RuntimeError("A runtime turn already owns this gateway session.")
+ signal: Future[str] = Future()
+ _FAILURES[grant] = signal
+ return signal
+
+
+def unwatch_failure(token: str, signal: Future[str]) -> None:
+ with _LOCK:
+ grant = _GRANTS.get(token)
+ if _FAILURES.get(grant) is signal:
+ del _FAILURES[grant]
+
+
+def _watch_for(grant: Grant) -> Future[str] | None:
+ with _LOCK:
+ return _FAILURES.get(grant)
+
+
+def _retry_after(exc: Exception) -> float | None:
+ """Read only Retry-After, never copy a provider's body or other headers."""
+ response = getattr(exc, "response", None)
+ headers = getattr(response, "headers", None) or getattr(exc, "headers", None) or {}
+ raw = next(
+ (v for k, v in headers.items() if str(k).lower() == "retry-after"),
+ getattr(exc, "retry_after", None),
+ )
+ if raw is None:
+ return None
+ try:
+ seconds = float(raw)
+ except (TypeError, ValueError):
+ try:
+ seconds = parsedate_to_datetime(str(raw)).timestamp() - time.time()
+ except (TypeError, ValueError, OverflowError):
+ log.debug("runtime gateway: invalid Retry-After ignored; using the default cooldown")
+ return None
+ return max(0.0, seconds) if math.isfinite(seconds) else None
+
+
+def whole_seconds(seconds: float) -> int:
+ """Seconds to tell a person or a ``Retry-After`` header: rounded up, but
+ floating-point dust (30.000000001) never becomes an extra second."""
+ return max(0, math.ceil(round(seconds, 3)))
+
+
+def _limited(provider: str, seconds: float) -> GatewayError:
+ return GatewayError(
+ f"{provider} returned HTTP 429 (rate limit). Try again in {whole_seconds(seconds)} s, "
+ "or choose another connected model in the agent's settings. "
+ "No fallback provider was called.",
+ status=429,
+ code="rate_limited",
+ retry_after=seconds,
+ )
+
+
+def check_cooldown(provider: str, model: str, account_id: str = "") -> None:
+ """Reject early, without spawning a runtime or spending another model call."""
+ key = (provider, account_id, model)
+ with _LOCK:
+ remaining = _COOLDOWNS.get(key, 0.0) - time.monotonic()
+ if remaining <= 0:
+ _COOLDOWNS.pop(key, None)
+ if remaining > 0:
+ raise _limited(provider, remaining)
+
+
+def _report_failure(
+ grant: Grant,
+ model: str,
+ failure: GatewayError,
+ signal: Future[str] | None,
+) -> GatewayError:
+ if failure.status == 429:
+ seconds = failure.retry_after if failure.retry_after is not None else _DEFAULT_COOLDOWN_S
+ key = (grant.provider, grant.account_id, model)
+ with _LOCK:
+ now = time.monotonic()
+ until = max(_COOLDOWNS.get(key, 0.0), now + seconds)
+ seconds = until - now
+ _COOLDOWNS[key] = until
+ _COOLDOWNS.move_to_end(key)
+ while len(_COOLDOWNS) > 512:
+ _COOLDOWNS.popitem(last=False)
+ failure = _limited(grant.provider, seconds)
+ from jarvis.agent_runtimes.provider_errors import is_terminal
+
+ # Only a failure no runtime can recover from ends the turn here. A
+ # timeout, an overloaded provider or a context overflow goes back to the
+ # runtime, whose own retry and conversation compression handle it.
+ if signal is not None and is_terminal(failure.code):
+ # A request captures its turn's signal before awaiting the provider.
+ # Late failures therefore cannot stop a later turn on the same session.
+ from concurrent.futures import InvalidStateError
+
+ try:
+ signal.set_result(str(failure))
+ except InvalidStateError:
+ # A previous failure or runner cleanup already settled this signal.
+ log.debug("runtime gateway: failure signal was already settled")
+ return failure
+
+
def base_url() -> str | None:
"""The gateway's URL on this app's server, or ``None`` before it bound."""
from jarvis.core import runtime_refs
@@ -139,11 +391,17 @@ def _client(account_id: str) -> Any:
with _LOCK:
found = _CLIENTS.get(account_id)
if found is None:
+ from jarvis.core.http_pool import HttpClientPool
from jarvis.live.subscription_auth import SubscriptionAuth
from jarvis.live.subscription_reasoning import SubscriptionReasoning
auth = SubscriptionAuth(account_id)
- found = SubscriptionReasoning(credentials=auth.credentials)
+ # Its own client with the agent-scale read timeout: a long
+ # thinking phase sends nothing for minutes.
+ found = SubscriptionReasoning(
+ credentials=auth.credentials,
+ http_pool=HttpClientPool(timeout_s=_HOSTED_READ_TIMEOUT_S),
+ )
_CLIENTS[account_id] = found
return found
@@ -170,6 +428,14 @@ def _function_tool(tool: Any) -> dict[str, Any] | None:
return out
+def _is_system(item: dict[str, Any]) -> bool:
+ # A runtime writes its system prompt as "developer" for a reasoning model;
+ # ChatGPT's backend takes either only as instructions.
+ return item.get("role") in ("system", "developer") and item.get("type", "message") == (
+ "message"
+ )
+
+
def request_args(body: Any) -> dict[str, Any]:
"""The subscription client's arguments for one Responses request body."""
if not isinstance(body, dict):
@@ -187,13 +453,19 @@ def request_args(body: Any) -> dict[str, Any]:
else:
raise GatewayError("The request input must be text or a list of items.")
instructions = body.get("instructions")
+ # ChatGPT's backend refuses a system message in the input ("System
+ # messages are not allowed", live 2026-10-07: every OpenClaw turn on the
+ # subscription). Its place is the instructions, which OpenClaw leaves empty.
+ system = [_text(item.get("content")) for item in items if _is_system(item)]
+ items = [item for item in items if not _is_system(item)]
+ parts = [instructions if isinstance(instructions, str) else "", *system]
tools = [found for tool in body.get("tools") or [] if (found := _function_tool(tool))]
reasoning = body.get("reasoning") if isinstance(body.get("reasoning"), dict) else {}
effort = reasoning.get("effort") if isinstance(reasoning.get("effort"), str) else ""
return {
"model": model.strip(),
"input": items,
- "instructions": instructions if isinstance(instructions, str) else "",
+ "instructions": "\n\n".join(part for part in parts if part.strip()),
"tools": tools,
"reasoning_effort": effort,
}
@@ -220,13 +492,53 @@ async def stream_response(grant: Grant, args: dict[str, Any]) -> AsyncIterator[b
from jarvis.live.subscription_auth import SubscriptionAuthError
from jarvis.live.subscription_reasoning import SubscriptionReasoningError
+ model = str(args.get("model") or "")
+ signal = _watch_for(grant)
+ started = False
try:
- async for event in _client(grant.account_id).stream(**args):
- yield _sse(event)
- except (SubscriptionReasoningError, SubscriptionAuthError) as exc:
- log.info("runtime gateway: %s turn failed (%s)", grant.agent_id, type(exc).__name__)
- code = getattr(exc, "code", "subscription_unavailable")
- yield _sse(_failed_event(_subscription_message(exc), code))
+ check_cooldown(grant.provider, model, grant.account_id)
+ client = _client(grant.account_id)
+ args = await _snapped_effort(client, args)
+ async with contextlib.aclosing(client.stream(**args)) as upstream:
+ async for event in upstream:
+ started = True
+ yield _sse(event)
+ except (SubscriptionReasoningError, SubscriptionAuthError, GatewayError) as exc:
+ failure = _report_failure(grant, model, _subscription_failure(grant, exc), signal)
+ if not started:
+ raise failure from exc
+ yield _sse(_failed_event(str(failure), failure.code))
+
+
+async def _snapped_effort(client: Any, args: dict[str, Any]) -> dict[str, Any]:
+ """``args`` with the runtime's thinking level snapped to one the model offers."""
+ effort = str(args.get("reasoning_effort") or "")
+ snap = getattr(client, "snap_effort", None)
+ if not effort or not callable(snap):
+ return args
+ return {**args, "reasoning_effort": await snap(str(args.get("model") or ""), effort)}
+
+
+async def open_response_stream(grant: Grant, args: dict[str, Any]) -> AsyncIterator[bytes]:
+ """Check upstream acceptance before committing an HTTP 200 SSE response."""
+ events = stream_response(grant, args)
+ try:
+ first = await anext(events)
+ except StopAsyncIteration as exc:
+ raise GatewayError("ChatGPT ended without an answer.", status=502) from exc
+ except BaseException:
+ await events.aclose()
+ raise
+
+ async def accepted() -> AsyncIterator[bytes]:
+ try:
+ yield first
+ async for event in events:
+ yield event
+ finally:
+ await events.aclose()
+
+ return accepted()
async def complete_response(grant: Grant, args: dict[str, Any]) -> dict[str, Any]:
@@ -234,24 +546,102 @@ async def complete_response(grant: Grant, args: dict[str, Any]) -> dict[str, Any
from jarvis.live.subscription_auth import SubscriptionAuthError
from jarvis.live.subscription_reasoning import SubscriptionReasoningError
+ model = str(args.get("model") or "")
+ signal = _watch_for(grant)
try:
+ check_cooldown(grant.provider, model, grant.account_id)
items: list[dict[str, Any]] = []
- async for event in _client(grant.account_id).stream(**args):
- finished = event.get("response")
- if event.get("type") == "response.output_item.done" and isinstance(
- event.get("item"), dict
- ):
- items.append(event["item"])
- if event.get("type") == "response.completed" and isinstance(finished, dict):
- # ChatGPT's backend streams the output items and sends the
- # completed response with an empty ``output``.
- return {**finished, "output": finished.get("output") or items}
- except (SubscriptionReasoningError, SubscriptionAuthError) as exc:
- log.info("runtime gateway: %s call failed (%s)", grant.agent_id, type(exc).__name__)
- raise GatewayError(
- _subscription_message(exc), status=502, code="subscription_unavailable"
- ) from exc
- raise GatewayError("ChatGPT ended without an answer.", status=502, code="incomplete")
+ client = _client(grant.account_id)
+ args = await _snapped_effort(client, args)
+ async with contextlib.aclosing(client.stream(**args)) as upstream:
+ async for event in upstream:
+ finished = event.get("response")
+ if event.get("type") == "response.output_item.done" and isinstance(
+ event.get("item"), dict
+ ):
+ items.append(event["item"])
+ if event.get("type") == "response.completed" and isinstance(finished, dict):
+ # ChatGPT's backend streams the output items and sends the
+ # completed response with an empty ``output``.
+ return {**finished, "output": finished.get("output") or items}
+ except (SubscriptionReasoningError, SubscriptionAuthError, GatewayError) as exc:
+ raise _report_failure(grant, model, _subscription_failure(grant, exc), signal) from exc
+ raise _report_failure(
+ grant,
+ model,
+ GatewayError("ChatGPT ended without an answer.", status=502, code="incomplete"),
+ signal,
+ )
+
+
+#: The subscription client's request-failure codes, as the gateway's codes.
+_SUBSCRIPTION_CODES: Final[dict[str, str]] = {
+ "invalid_function_parameters": "invalid_tool_schema",
+ "invalid_tool_schema": "invalid_tool_schema",
+ "model_not_found": "model_not_found",
+}
+
+
+def _subscription_message(exc: Exception) -> str:
+ """Fixed wording for a failed subscription call; no exception text leaves."""
+ from jarvis.live.subscription_auth import SubscriptionAuthError
+
+ if isinstance(exc, SubscriptionAuthError) or getattr(exc, "code", "") == "login":
+ return "The ChatGPT subscription needs a new sign-in in Jarvis."
+ return "The ChatGPT subscription could not answer this turn."
+
+
+def _subscription_failure(grant: Grant, exc: Exception) -> GatewayError:
+ """A subscription failure as a status and code the runtime can act on.
+
+ Only fixed wording chosen by the failure's kind leaves the gateway, never
+ exception text (CodeQL py/stack-trace-exposure); the code decides whether
+ the turn ends (a terminal code) or the runtime handles it (overflow:
+ compress). The details go to the log.
+ """
+ from jarvis.live.subscription_auth import SubscriptionAuthError
+
+ if isinstance(exc, GatewayError) or getattr(exc, "status", 0) == 429:
+ return _failure(grant.provider, exc)
+ log.warning(
+ "runtime gateway: %s subscription call failed: %s", grant.agent_id, _describe(exc)
+ )
+ sign_in = "The ChatGPT subscription needs a new sign-in in Jarvis."
+ if isinstance(exc, SubscriptionAuthError):
+ return GatewayError(sign_in, status=401, code="provider_auth")
+ status = getattr(exc, "status", 0)
+ code = str(getattr(exc, "code", "") or "")
+ if code == "context_length_exceeded":
+ return GatewayError(
+ "Context length exceeded: this request is longer than the selected ChatGPT "
+ "model's context. Compress or shorten the conversation and send it again.",
+ status=400,
+ code="context_length_exceeded",
+ )
+ if status in (401, 403):
+ return GatewayError(sign_in, status=401, code="provider_auth")
+ if status == 404 or code == "model_not_found":
+ return GatewayError(
+ "The selected model is unavailable on this ChatGPT subscription.",
+ status=404,
+ code="model_not_found",
+ )
+ if status in (400, 413, 422):
+ mapped = _SUBSCRIPTION_CODES.get(code, "invalid_request")
+ text = (
+ "ChatGPT rejected a tool schema in this request."
+ if mapped == "invalid_tool_schema"
+ else "ChatGPT rejected this request."
+ )
+ text = f"{text[:-1]} (HTTP {int(status)})."
+ return GatewayError(text, status=400, code=mapped)
+ return GatewayError(_subscription_message(exc), status=502, code="subscription_unavailable")
+
+
+def _describe(exc: BaseException) -> str:
+ from jarvis.agent_runtimes.provider_errors import describe
+
+ return describe(exc)
async def list_models(grant: Grant) -> list[dict[str, Any]]:
@@ -265,7 +655,13 @@ async def list_models(grant: Grant) -> list[dict[str, Any]]:
row = provider_row(grant.provider)
models = [model.id for model in row.curated_models] if row is not None else []
- return [{"id": model, "object": "model", "owned_by": grant.provider} for model in models]
+ with _LOCK:
+ models = list(dict.fromkeys([*models, *_MODEL_LIMITS.get(grant, {})]))
+ return [
+ {"id": model, "object": "model", "owned_by": grant.provider,
+ **(await asyncio.to_thread(model_limits, grant, model)).wire()}
+ for model in models
+ ]
from jarvis.live.subscription_auth import SubscriptionAuthError
from jarvis.live.subscription_reasoning import SubscriptionReasoningError
@@ -276,11 +672,19 @@ async def list_models(grant: Grant) -> list[dict[str, Any]]:
raise GatewayError(
_subscription_message(exc), status=502, code="subscription_unavailable"
) from exc
- return [
- {"id": row["id"], "object": "model", "owned_by": "openai"}
- for row in rows
- if isinstance(row.get("id"), str)
- ]
+ from types import SimpleNamespace
+
+ result = []
+ for row in rows:
+ model = row.get("id")
+ if not isinstance(model, str):
+ continue
+ with _LOCK:
+ limits = _MODEL_LIMITS.get(grant, {}).get(model)
+ if limits is None:
+ limits = resolve_limits(None, grant.provider, model, SimpleNamespace(**row))
+ result.append({"id": model, "object": "model", "owned_by": "openai", **limits.wire()})
+ return result
# ------------------------------------------------- chat completions (API keys)
@@ -321,7 +725,8 @@ def _arguments(raw: Any) -> dict[str, Any]:
return raw
try:
parsed = json.loads(raw) if isinstance(raw, str) and raw.strip() else {}
- except ValueError: # unparsable tool arguments become an empty object
+ except ValueError:
+ log.info("runtime gateway: malformed tool arguments replaced with an empty object")
return {}
return parsed if isinstance(parsed, dict) else {}
@@ -339,6 +744,12 @@ def _signature(call_id: str) -> str:
return _SIGNATURES.get(call_id, "")
+def temperature_given(body: Any) -> bool:
+ """Whether a Chat Completions body chose a sampling temperature."""
+ value = body.get("temperature") if isinstance(body, dict) else None
+ return isinstance(value, int | float) and not isinstance(value, bool)
+
+
def chat_request(body: Any) -> tuple[str, Any]:
"""``(model, BrainRequest)`` for one Chat Completions request body."""
from jarvis.core.protocols import BrainMessage, BrainRequest
@@ -405,7 +816,9 @@ def chat_request(body: Any) -> tuple[str, Any]:
"input_schema": found["parameters"],
}
)
- limit = body.get("max_completion_tokens") or body.get("max_tokens") or 8192
+ limit = body.get("max_completion_tokens", body.get("max_tokens"))
+ if limit is not None and (isinstance(limit, bool) or not isinstance(limit, int) or limit < 1):
+ raise GatewayError("The output token limit must be a positive integer.")
temperature = body.get("temperature")
reasoning = body.get("reasoning") if isinstance(body.get("reasoning"), dict) else {}
effort = body.get("reasoning_effort") or reasoning.get("effort")
@@ -414,61 +827,190 @@ def chat_request(body: Any) -> tuple[str, Any]:
tools=tuple(tools),
system="\n\n".join(system) or None,
temperature=float(temperature) if isinstance(temperature, int | float) else 0.7,
- max_tokens=max(1, min(int(limit) if isinstance(limit, int) else 8192, 128_000)),
+ # Zero is internal only: resolve an omitted limit from this model's
+ # actual capacity before handing the request to a provider.
+ max_tokens=limit if limit is not None else 0,
stream=True,
reasoning_effort=effort if effort in _EFFORTS else None,
)
-def _failure(provider: str, exc: Exception) -> GatewayError:
- """A provider error as a status the runtime can back off on, and a plain
- message — never the provider's own response body."""
- from jarvis.agent_runtimes.provider_errors import classify
-
- if (refusal := classify(provider, exc)) is not None:
- # No credits, provider unreachable, Claude Extra Usage off: a retry
- # cannot help, so the runtime must not read it as a rate limit.
- failure = GatewayError(refusal.message, status=refusal.status, code=refusal.code)
- failure.retry_after = refusal.retry_after
- return failure
- status = getattr(exc, "status_code", None) or getattr(exc, "status", None)
- if not isinstance(status, int):
- response = getattr(exc, "response", None)
- status = getattr(response, "status_code", None)
- if status == 429:
- return GatewayError(
- f"{provider} is rate-limiting this key; try again shortly.",
- status=429,
- code="rate_limited",
- )
- if status in (401, 403):
- return GatewayError(
- f"{provider} refused the saved key. Check it in Settings → API keys.",
- status=401,
- code="provider_auth",
- )
+def _failure(provider: str, exc: Exception, model: str = "") -> GatewayError:
+ """A provider error as a status and code the runtime acts on, and a plain
+ message — never the provider's own response body (that goes to the log,
+ bounded and redacted)."""
+ from jarvis.agent_runtimes.provider_errors import gateway_refusal
+
+ if isinstance(exc, GatewayError):
+ return exc
+ log.warning("runtime gateway: %s call failed: %s", provider, _describe(exc))
+ refusal = gateway_refusal(provider, exc, model)
return GatewayError(
- f"{provider} could not answer ({type(exc).__name__}).",
- status=502,
- code="provider_error",
+ refusal.message,
+ status=refusal.status,
+ code=refusal.code,
+ retry_after=_retry_after(exc) if refusal.code == "rate_limited" else None,
)
_DONE: Final = object()
+#: How long an agent call may stay silent. A reasoning model can think for
+#: minutes before its first token, and a local server on a CPU prefills a
+#: long agent prompt for longer still; Hermes itself waits 180 s for a hosted
+#: and 900 s for a local endpoint. The voice path keeps its own short limits.
+_HOSTED_READ_TIMEOUT_S: Final = 300.0
+_LOCAL_READ_TIMEOUT_S: Final = 900.0
+
+#: Provider brains kept between calls (one per session, model and credential).
+_BRAINS_MAX: Final = 32
+
+
+@dataclass(slots=True)
+class _BrainSlot:
+ """One cached provider brain, and how many calls are using it."""
+
+ brain: Any
+ users: int = 0
+ retired: bool = False
+
+
+_BRAINS: OrderedDict[tuple[str, ...], _BrainSlot] = OrderedDict()
+_CLOSING: set[asyncio.Task[None]] = set()
+
+
+def _profile(provider: str, *, temperature_given: bool) -> Any:
+ from jarvis.agent_runtimes.model_map import is_local
+ from jarvis.plugins.brain._agent_profile import AgentRequestProfile
+
+ return AgentRequestProfile(
+ read_timeout_s=_LOCAL_READ_TIMEOUT_S if is_local(provider) else _HOSTED_READ_TIMEOUT_S,
+ # A tool loop resends the same prefix every round; caching it is
+ # what makes a long agent turn affordable on Anthropic.
+ prompt_cache=True,
+ omit_temperature=not temperature_given,
+ )
+
+
+def _brain_key(grant: Grant, model: str, login: str | None) -> tuple[str, ...]:
+ """The cache key: the session, the model and the credential in use.
+
+ Blocking (keyring); run in a thread under the key override, so a changed
+ key or server address makes a new brain instead of reusing a stale client.
+ """
+ import hashlib
+
+ if login:
+ material = f"login:{login}"
+ else:
+ from jarvis.core.config import resolve_provider_endpoint
+
+ try:
+ endpoint = resolve_provider_endpoint(grant.provider)
+ material = f"{endpoint.base_url or ''}|{endpoint.credential or ''}"
+ except Exception as exc: # noqa: BLE001 — no fingerprint just means no reuse
+ log.debug(
+ "runtime gateway: no credential fingerprint for %s (%s)",
+ grant.provider,
+ type(exc).__name__,
+ )
+ material = uuid.uuid4().hex
+ digest = hashlib.sha256(material.encode("utf-8")).hexdigest()[:16]
+ return (grant.agent_id, grant.scope, grant.provider, grant.account_id, model, digest)
+
+
+def _new_brain(provider: str, model: str, login: str | None) -> Any:
+ from jarvis.agent_chat.runner_api import build_brain
+ from jarvis.brain.usage_meter import meter_brain
+
+ if login:
+ # No API key: the person's Claude Code login answers, which
+ # Anthropic bills as extra usage.
+ from jarvis.plugins.brain.claude_api import ClaudeAPIBrain
+
+ brain = ClaudeAPIBrain(model=model or None, auth_token=login)
+ else:
+ brain = build_brain(provider, model)
+ # Every call the agent makes lands in the cost ledger, under the caller
+ # tag of the call.
+ return meter_brain(brain, provider)
+
+
+def _acquire_brain(key: tuple[str, ...], factory: Any) -> _BrainSlot:
+ """The cached brain for ``key`` (built on first use), marked in use.
+
+ A brain keeps its HTTP client: every round of a tool loop reuses one
+ connection instead of a new TLS handshake and an unclosed client.
+ """
+ retired: list[_BrainSlot] = []
+ with _LOCK:
+ slot = _BRAINS.get(key)
+ if slot is None:
+ slot = _BrainSlot(factory())
+ _BRAINS[key] = slot
+ while len(_BRAINS) > _BRAINS_MAX:
+ _, old = _BRAINS.popitem(last=False)
+ old.retired = True
+ retired.append(old)
+ _BRAINS.move_to_end(key)
+ slot.users += 1
+ for old in retired:
+ if old.users == 0:
+ _close_later(old.brain)
+ return slot
+
+
+def _release_brain(slot: _BrainSlot) -> None:
+ with _LOCK:
+ slot.users -= 1
+ close = slot.retired and slot.users == 0
+ if close:
+ _close_later(slot.brain)
+
+
+def _close_later(brain: Any) -> None:
+ """Close a brain's HTTP client in the background (best effort)."""
+ try:
+ loop = asyncio.get_running_loop()
+ except RuntimeError:
+ return # no loop (tests, shutdown): the client goes with the object
+ task = loop.create_task(_close_brain(brain))
+ _CLOSING.add(task)
+ task.add_done_callback(_CLOSING.discard)
+
+
+async def _close_brain(brain: Any) -> None:
+ import inspect
+
+ client = getattr(getattr(brain, "unwrapped", brain), "_client", None)
+ for name in ("aclose", "close"):
+ close = getattr(client, name, None)
+ if not callable(close):
+ continue
+ try:
+ result = close()
+ if inspect.isawaitable(result):
+ await result
+ except Exception as exc: # noqa: BLE001 — closing an idle client is best effort
+ log.debug("runtime gateway: closing a provider client failed (%s)", exc)
+ return
+
async def _deltas(grant: Grant, model: str, request: Any) -> AsyncIterator[Any]:
"""The provider plugin's stream, with the Agents-tier key and cost caller.
The plugin runs in a task of its own and hands its deltas over a queue:
- the key override and the cost caller are context variables, and a
- streamed response is read by a different task than the one that opened
- it — a context variable set there could not be reset (``ValueError``).
+ the key override, the cost caller and the agent request profile are
+ context variables, and a streamed response is read by a different task
+ than the one that opened it — a context variable set there could not be
+ reset (``ValueError``). The task copies the caller's context, so the
+ profile the caller set (:func:`_with_profile`) reaches the plugin.
"""
- from jarvis.agent_chat.runner_api import build_brain
- from jarvis.agent_runtimes.model_map import login_token_for
+ from jarvis.agent_runtimes.model_map import login_route
+ from jarvis.agent_runtimes.provider_errors import login_expired
from jarvis.core.config import get_jarvis_agent_secret, override_provider_secrets
from jarvis.costs.ledger import usage_context
+ from jarvis.costs.model import RUNTIME_CALLER
queue: asyncio.Queue[Any] = asyncio.Queue(maxsize=256)
@@ -477,18 +1019,26 @@ async def _deltas(grant: Grant, model: str, request: Any) -> AsyncIterator[Any]:
try:
secret = get_jarvis_agent_secret(grant.provider)
overrides = {grant.provider: secret} if secret else {}
- with override_provider_secrets(overrides), usage_context("agent-runtime"):
- login = await asyncio.to_thread(login_token_for, grant.provider, grant.account_id)
- if login:
- # No API key: the person's Claude Code login answers,
- # which Anthropic bills as extra usage.
- from jarvis.plugins.brain.claude_api import ClaudeAPIBrain
-
- brain = ClaudeAPIBrain(model=model or None, auth_token=login)
- else:
- brain = build_brain(grant.provider, model)
- async for delta in brain.complete(request):
- await queue.put(delta)
+ with override_provider_secrets(overrides), usage_context(RUNTIME_CALLER):
+ on_login, login = await asyncio.to_thread(
+ login_route, grant.provider, grant.account_id
+ )
+ if on_login and not login:
+ # Only the Claude CLI renews the login; without it the
+ # API-key path would only say "no key".
+ raise login_expired()
+ key = await asyncio.to_thread(_brain_key, grant, model, login)
+ slot = _acquire_brain(key, lambda: _new_brain(grant.provider, model, login))
+ try:
+ brain = slot.brain
+ configure_context = getattr(brain, "set_context_window", None)
+ if callable(configure_context):
+ limits = await asyncio.to_thread(model_limits, grant, model)
+ configure_context(limits.context_window)
+ async for delta in brain.complete(request):
+ await queue.put(delta)
+ finally:
+ _release_brain(slot)
await queue.put(_DONE)
except Exception as exc: # noqa: BLE001 — handed to the reader, which reports it
if login:
@@ -514,6 +1064,18 @@ async def _deltas(grant: Grant, model: str, request: Any) -> AsyncIterator[Any]:
await task
+def _with_profile(provider: str, temperature_given: bool) -> Any:
+ """Set the agent request profile while a call's plugin task is started."""
+ from jarvis.plugins.brain._agent_profile import PROFILE
+
+ token = PROFILE.set(_profile(provider, temperature_given=temperature_given))
+ try:
+ yield
+ finally:
+ PROFILE.reset(token)
+
+
def _chunk(chat_id: str, model: str, delta: dict[str, Any], **extra: Any) -> bytes:
body: dict[str, Any] = {
"id": chat_id,
@@ -526,13 +1088,38 @@ def _chunk(chat_id: str, model: str, delta: dict[str, Any], **extra: Any) -> byt
return f"data: {json.dumps(body, ensure_ascii=False)}\n\n".encode()
-def _openai_usage(usage: dict[str, int]) -> dict[str, int]:
- prompt = int(usage.get("input_tokens", 0))
+def _merge_usage(total: dict[str, int], usage: dict[str, Any]) -> None:
+ """Fold one usage block in. A plugin reports a call once, but a split or
+ cumulative report must not count the same tokens twice: keep the highest
+ figure per key."""
+ for key, value in usage.items():
+ try:
+ total[key] = max(total.get(key, 0), int(value or 0))
+ except (TypeError, ValueError):
+ log.debug("runtime gateway: non-numeric usage %r ignored", key)
+
+
+def _openai_usage(usage: dict[str, int]) -> dict[str, Any]:
+ """The plugin's usage in the Chat Completions shape.
+
+ The plugins report ``input_tokens`` as the UNCACHED share
+ (``jarvis.brain.usage_meter``); Chat Completions' ``prompt_tokens``
+ counts the whole prompt, cache reads and writes included. Hermes and
+ OpenClaw size the conversation from it and compress when it nears the
+ context window, so the cached share must be in it.
+ """
+ cached = int(usage.get("cache_hit_tokens", 0))
+ written = int(usage.get("cache_write_tokens", 0))
+ prompt = int(usage.get("input_tokens", 0)) + cached + written
completion = int(usage.get("output_tokens", 0))
+ details: dict[str, int] = {"cached_tokens": cached}
+ if written:
+ details["cache_write_tokens"] = written
return {
"prompt_tokens": prompt,
"completion_tokens": completion,
"total_tokens": prompt + completion,
+ "prompt_tokens_details": details,
}
@@ -552,34 +1139,46 @@ def _tool_call(index: int, call: dict[str, Any]) -> dict[str, Any]:
}
-async def open_chat_stream(grant: Grant, model: str, request: Any) -> AsyncIterator[bytes]:
+async def open_chat_stream(
+ grant: Grant, model: str, request: Any, *, temperature_given: bool = True
+) -> AsyncIterator[bytes]:
"""The answer as Chat Completions chunks.
The provider's first delta is awaited before this returns, so a failure
up front (bad key, rate limit) becomes an HTTP status the runtime can act
on; a failure after streaming began arrives as an ``error`` chunk.
+ ``temperature_given`` is whether the runtime chose a temperature.
"""
+ limits = await asyncio.to_thread(model_limits, grant, model)
+ request = _with_output_capacity(request, limits)
stream = _deltas(grant, model, request)
started = time.monotonic()
+ signal = _watch_for(grant)
try:
- first = await anext(stream, None)
- except Exception as exc: # noqa: BLE001 — becomes the runtime's HTTP error, logged below
- log.info("runtime gateway: %s on %s failed up front (%s)", grant.agent_id,
- grant.provider, type(exc).__name__)
- raise _failure(grant.provider, exc) from exc
- return _chat_chunks(grant, model, stream, first, started)
+ check_cooldown(grant.provider, model, grant.account_id)
+ # The plugin task starts on the first delta and keeps this profile.
+ with _with_profile(grant.provider, temperature_given):
+ first = await anext(stream, None)
+ except Exception as exc: # noqa: BLE001 — becomes the runtime's HTTP error; _failure logs it
+ raise _report_failure(grant, model, _failure(grant.provider, exc, model), signal) from exc
+ return _chat_chunks(grant, model, stream, first, started, signal)
async def _chat_chunks(
- grant: Grant, model: str, stream: AsyncIterator[Any], first: Any, started: float
+ grant: Grant,
+ model: str,
+ stream: AsyncIterator[Any],
+ first: Any,
+ started: float,
+ signal: Future[str] | None = None,
) -> AsyncIterator[bytes]:
chat_id = f"chatcmpl-{uuid.uuid4().hex}"
usage: dict[str, int] = {}
calls = 0
finish = "stop"
- yield _chunk(chat_id, model, {"role": "assistant", "content": ""})
delta = first
try:
+ yield _chunk(chat_id, model, {"role": "assistant", "content": ""})
while delta is not None:
if delta.content:
yield _chunk(chat_id, model, {"content": delta.content})
@@ -587,53 +1186,70 @@ async def _chat_chunks(
yield _chunk(chat_id, model, {"tool_calls": [_tool_call(calls, delta.tool_call)]})
calls += 1
if delta.usage:
- for key, value in delta.usage.items():
- usage[key] = usage.get(key, 0) + int(value or 0)
+ _merge_usage(usage, delta.usage)
if delta.finish_reason:
- finish = _FINISH.get(delta.finish_reason, "stop")
+ finish = _finish(delta.finish_reason)
delta = await anext(stream, None)
except Exception as exc: # noqa: BLE001 — the stream already began: an error chunk tells the runtime
- failure = _failure(grant.provider, exc)
- log.info("runtime gateway: %s on %s failed mid-stream (%s)", grant.agent_id,
- grant.provider, type(exc).__name__)
+ failure = _report_failure(grant, model, _failure(grant.provider, exc, model), signal)
payload = {"error": {"message": str(failure), "type": failure.code, "code": failure.code}}
yield f"data: {json.dumps(payload)}\n\n".encode()
return
+ finally:
+ # The runner stops on a provider failure; a closed HTTP client must
+ # also release the plugin task if it was suspended between deltas.
+ close = getattr(stream, "aclose", None)
+ if close is not None:
+ await close()
yield _chunk(
chat_id,
model,
{},
- finish="tool_calls" if calls else finish,
+ finish=_final_finish(finish, calls),
usage=_openai_usage(usage),
)
yield b"data: [DONE]\n\n"
log.info(
"runtime gateway: %s on %s/%s answered in %.1f s (%s in, %s out, %d tool calls)",
- grant.agent_id, grant.provider, model, time.monotonic() - started,
- usage.get("input_tokens", 0), usage.get("output_tokens", 0), calls,
+ grant.agent_id,
+ grant.provider,
+ model,
+ time.monotonic() - started,
+ usage.get("input_tokens", 0),
+ usage.get("output_tokens", 0),
+ calls,
)
-async def complete_chat(grant: Grant, model: str, request: Any) -> dict[str, Any]:
+async def complete_chat(
+ grant: Grant, model: str, request: Any, *, temperature_given: bool = True
+) -> dict[str, Any]:
"""The finished ``chat.completion`` for a runtime that did not ask to stream."""
+ limits = await asyncio.to_thread(model_limits, grant, model)
+ request = _with_output_capacity(request, limits)
stream = _deltas(grant, model, request)
text: list[str] = []
calls: list[dict[str, Any]] = []
usage: dict[str, int] = {}
finish = "stop"
+ signal = _watch_for(grant)
try:
- async for delta in stream:
+ check_cooldown(grant.provider, model, grant.account_id)
+ with _with_profile(grant.provider, temperature_given):
+ # The plugin task starts on the first delta and keeps this profile.
+ delta = await anext(stream, None)
+ while delta is not None:
if delta.content:
text.append(delta.content)
if delta.tool_call:
calls.append(_tool_call(len(calls), delta.tool_call))
if delta.usage:
- for key, value in delta.usage.items():
- usage[key] = usage.get(key, 0) + int(value or 0)
+ _merge_usage(usage, delta.usage)
if delta.finish_reason:
- finish = _FINISH.get(delta.finish_reason, "stop")
- except Exception as exc: # noqa: BLE001 — becomes the runtime's HTTP error
- raise _failure(grant.provider, exc) from exc
+ finish = _finish(delta.finish_reason)
+ delta = await anext(stream, None)
+ except Exception as exc: # noqa: BLE001 — becomes the runtime's HTTP error; _failure logs it
+ raise _report_failure(grant, model, _failure(grant.provider, exc, model), signal) from exc
message: dict[str, Any] = {"role": "assistant", "content": "".join(text) or None}
if calls:
message["tool_calls"] = [{k: v for k, v in call.items() if k != "index"} for call in calls]
@@ -643,16 +1259,73 @@ async def complete_chat(grant: Grant, model: str, request: Any) -> dict[str, Any
"created": int(time.time()),
"model": model,
"choices": [
- {"index": 0, "message": message, "finish_reason": "tool_calls" if calls else finish}
+ {"index": 0, "message": message, "finish_reason": _final_finish(finish, len(calls))}
],
"usage": _openai_usage(usage),
}
+#: Output budget kept free of the prompt estimate when a request names no
+#: limit, and the smallest budget ever sent (a prompt this close to the
+#: window is refused as a context overflow, which the runtime compresses).
+_BUDGET_MARGIN_TOKENS: Final = 1024
+_MIN_OUTPUT_TOKENS: Final = 1024
+#: A conservative characters-per-token ratio: code and non-English text run
+#: closer to three than to the usual four, and overestimating the prompt only
+#: shortens the budget.
+_CHARS_PER_TOKEN: Final = 3
+_IMAGE_TOKENS: Final = 1600
+
+
+def _prompt_tokens_estimate(request: Any) -> int:
+ """A rough upper estimate of the request's prompt size, in tokens."""
+ chars = len(request.system or "") + len(json.dumps(list(request.tools), default=str))
+ images = 0
+ for message in request.messages:
+ content = message.content
+ chars += len(content) if isinstance(content, str) else len(json.dumps(content, default=str))
+ images += len(message.images)
+ return chars // _CHARS_PER_TOKEN + images * _IMAGE_TOKENS
+
+
+def _with_output_capacity(request: Any, limits: ModelLimits) -> Any:
+ """The request with its output budget settled.
+
+ An explicit runtime limit is kept (capped at the model's maximum). With
+ none, the model's maximum is used, but never more than the context window
+ leaves after the prompt: OpenRouter's upstreams, vLLM and other servers
+ refuse ``prompt + max_tokens > context`` outright, and many models declare
+ an output maximum as large as the whole window.
+ """
+ from jarvis.core.protocols import BrainRequest
+
+ maximum = limits.max_output_tokens
+ if request.max_tokens:
+ requested = request.max_tokens
+ return replace(
+ request, max_tokens=min(requested, maximum) if maximum is not None else requested
+ )
+ budget = maximum or BrainRequest.__dataclass_fields__["max_tokens"].default
+ room = limits.context_window - _prompt_tokens_estimate(request) - _BUDGET_MARGIN_TOKENS
+ return replace(request, max_tokens=max(min(budget, room), _MIN_OUTPUT_TOKENS))
+
+
def reset() -> None:
"""Forget every token, client and remembered signature (tests)."""
+ global _CATALOG
+ _CATALOG = None
+ with _LOCK:
+ brains = list(_BRAINS.values())
+ _BRAINS.clear()
+ for slot in brains:
+ slot.retired = True
+ if slot.users == 0:
+ _close_later(slot.brain)
with _LOCK:
_GRANTS.clear()
_TOKENS.clear()
_CLIENTS.clear()
_SIGNATURES.clear()
+ _MODEL_LIMITS.clear()
+ _FAILURES.clear()
+ _COOLDOWNS.clear()
diff --git a/jarvis/agent_runtimes/hermes.py b/jarvis/agent_runtimes/hermes.py
index e103804d78..bfef4d2d14 100644
--- a/jarvis/agent_runtimes/hermes.py
+++ b/jarvis/agent_runtimes/hermes.py
@@ -1,10 +1,22 @@
"""Hermes Agent as a society agent runtime (``docs/agent-runtimes.md``).
-One turn = one ``hermes acp`` process with ``HERMES_HOME`` pointed at the
-agent's own profile folder. Jarvis writes that profile's ``config.yaml``
-(JSON, which is valid YAML) and ``SOUL.md`` before every turn and hands the
-Jarvis MCP server over per session; the profile keeps Hermes' own session
-store, so ``session/load`` reopens the agent's one conversation.
+One turn = one ``hermes acp`` process. Every agent is a Hermes *profile* of
+one Hermes data root that Jarvis owns (``<runtimes_root>/hermes-home``):
+``HERMES_HOME`` points at ``hermes-home/profiles/<agent>``. Jarvis writes the
+profile's ``config.yaml`` (JSON, which is valid YAML) and ``SOUL.md`` before
+every turn and hands the Jarvis MCP server over per session; the profile keeps
+Hermes' own session store, so ``session/load`` reopens the agent's one
+conversation.
+
+Why profiles of one root, not one root per agent: Hermes keeps its Python
+dependency environment per data root. A root per agent made the first turn of
+every agent (and the first after every Hermes update) build a ~700 MB
+environment for about two minutes, and Hermes' Windows home maintenance put
+every agent folder on the user's PATH. Profiles share their root's
+environment, which the setup job prepares (:meth:`HermesRuntime.prepare_command`)
+before a turn needs it. The root is Jarvis' own, not the person's Hermes home:
+a profile of the person's root would read (and rotate) their own Hermes
+logins through Hermes' global-root credential fallback.
Hermes' self-learning extras (memory nudges, background review, curator,
skill-creation nudges, title generation) are switched off: Jarvis owns
@@ -16,13 +28,17 @@ option degrades to Hermes' default instead of breaking the turn.
from __future__ import annotations
import asyncio
+import hashlib
+import logging
import os
import re
+import shutil
from collections.abc import Callable
from pathlib import Path
from typing import Any, Final
from urllib.parse import urlsplit
+from jarvis.agent_runtimes import base, versions
from jarvis.agent_runtimes.acp import McpServer
from jarvis.agent_runtimes.base import (
DetectCache,
@@ -31,7 +47,6 @@ from jarvis.agent_runtimes.base import (
RuntimeTurn,
RuntimeUnavailable,
TurnSlots,
- agent_home,
child_env,
first_existing,
format_version,
@@ -39,26 +54,59 @@ from jarvis.agent_runtimes.base import (
is_windows,
parse_version,
persona_text,
+ posix_installer,
+ private_dir,
+ ps_quote,
run_version,
+ safe_key,
which,
+ windows_installer,
write_if_changed,
write_json_if_changed,
)
from jarvis.agent_runtimes.model_map import KEY_ENV_VAR, RUNTIME_PROVIDER_NAME
+log = logging.getLogger(__name__)
+
NAME: Final[str] = "hermes"
LABEL: Final[str] = "Hermes"
-#: Oldest release verified to persist ACP sessions and accept per-session MCP
-#: servers (spike 2026-10-06). Older installs are offered an update.
-MINIMUM_VERSION: Final[tuple[int, int, int]] = (0, 20, 6)
-
_INSTALL_URL_PS1: Final[str] = "https://hermes-agent.nousresearch.com/install.ps1"
_INSTALL_URL_SH: Final[str] = "https://hermes-agent.nousresearch.com/install.sh"
+#: Hermes' own profile-name rule (``hermes_cli.main._PROFILE_NAME_RE``).
+_PROFILE_NAME: Final[re.Pattern[str]] = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+
+#: The profile the setup job runs Hermes under to prepare the shared root.
+_SETUP_KEY: Final[str] = "~setup"
+
+#: Hermes toolsets no Jarvis agent gets: a headless Chromium (Jarvis has a
+#: visible browser over MCP), background desktop control, and Hermes' own
+#: scheduler (Jarvis owns routines and their budgets).
+_ALWAYS_DISABLED: Final[frozenset[str]] = frozenset({"browser", "computer_use", "cronjob"})
+
+#: Effort levels Hermes accepts in ``agent.reasoning_effort``
+#: (``hermes_constants.VALID_REASONING_EFFORTS`` plus ``none``).
+_HERMES_EFFORTS: Final[frozenset[str]] = frozenset(
+ {"none", "minimal", "low", "medium", "high", "xhigh", "max"}
+)
+
+_BIN_BLOCKER_TEXT: Final[str] = (
+ "Personal Jarvis keeps this a file on purpose. Hermes' home maintenance\n"
+ "publishes launchers into <data root>/bin and puts that folder on the\n"
+ "user's PATH on Windows; a file here makes that step a no-op for the data\n"
+ "root Jarvis' agents use, so they never change the user's PATH.\n"
+)
+
def _binary() -> str | None:
- found = which("hermes", "hermes.exe", "hermes.cmd")
+ """The person's Hermes launcher, never one inside a Jarvis agent folder.
+
+ Builds before the profile layout left per-agent ``bin`` folders on the
+ user's PATH (``path_cleanup`` removes them); a stale one must not shadow
+ the real install.
+ """
+ found = which("hermes", "hermes.exe", "hermes.cmd", skip=_in_jarvis_data)
if found:
return found
home = Path.home()
@@ -70,19 +118,116 @@ def _binary() -> str | None:
return str(found_path) if found_path else None
+def _in_jarvis_data(directory: str) -> bool:
+ from jarvis.agent_runtimes.path_cleanup import is_jarvis_hermes_bin
+
+ return is_jarvis_hermes_bin(directory)
+
+
def _install_hint() -> str:
if is_windows():
return f"iex (irm {_INSTALL_URL_PS1})"
return f"curl -fsSL {_INSTALL_URL_SH} | bash"
+# ------------------------------------------------------------------ layout
+
+
+def hermes_root() -> Path:
+ """The Hermes data root every Jarvis agent profile shares."""
+ return base.runtimes_root() / "hermes-home"
+
+
+def profile_name(key: str) -> str:
+ """Hermes profile name for a runtime home key (``<agent>`` / ``<agent>~runs``)."""
+ agent, runs = (key[: -len("~runs")], True) if key.endswith("~runs") else (key, False)
+ slug = re.sub(r"[^a-z0-9_-]+", "-", agent.lower()).strip("-_") or "agent"
+ digest = hashlib.sha256(key.encode("utf-8")).hexdigest()[:6]
+ if runs or slug != agent or len(slug) > 48:
+ # Lowercased, shortened or a routine folder: the hash keeps two keys
+ # that slug alike ("Ada" / "ada", "x~runs" / "x-runs") apart.
+ slug = f"{slug[:48].rstrip('-_') or 'agent'}-{'runs-' if runs else ''}{digest}"
+ name = slug[:64]
+ return name if _PROFILE_NAME.match(name) else f"agent-{digest}"
+
+
+def _root_config(pin: versions.Pin) -> dict[str, Any]:
+ config: dict[str, Any] = {
+ # Never put Jarvis' data root on the user's PATH (honoured on POSIX;
+ # the ``bin`` file covers Windows).
+ "cli": {"expose_on_path": False},
+ "approvals": {"mode": "manual"},
+ }
+ if pin.config_version is not None:
+ config["_config_version"] = pin.config_version
+ return config
+
+
+def prepare_root() -> Path:
+ """Create the shared root: marker config, ``profiles/``, the ``bin`` blocker."""
+ root = private_dir(hermes_root())
+ private_dir(root / "profiles")
+ # A root ``config.yaml`` is also what makes Hermes accept ``root/profiles``
+ # as a real profiles folder (``hermes_constants._is_hermes_profiles_root``).
+ write_json_if_changed(root / "config.yaml", _root_config(versions.pin(NAME)))
+ blocker = root / "bin"
+ if blocker.is_dir() and not blocker.is_symlink():
+ shutil.rmtree(blocker, ignore_errors=True)
+ if not blocker.exists():
+ write_if_changed(blocker, _BIN_BLOCKER_TEXT)
+ return root
+
+
+def profile_home(key: str) -> Path:
+ """The agent's Hermes profile folder (created on demand, with its root)."""
+ root = prepare_root()
+ home = private_dir(root / "profiles" / profile_name(key))
+ _adopt_legacy_home(key, home)
+ return home
+
+
+def _adopt_legacy_home(key: str, home: Path) -> None:
+ """Carry an agent's conversation over from the old per-agent data root.
+
+ Builds before the profile layout kept ``agent_runtimes/hermes/<agent>``,
+ each with its own ~700 MB dependency environment. The session store moves
+ into the profile (so the agent keeps its Hermes context); the old folder,
+ everything else in it rebuildable, is removed once that copy succeeded.
+ """
+ from jarvis.core.instance import current_instance
+
+ if not current_instance().is_default:
+ return # the old folders belong to the default app's agents
+ legacy = base.legacy_runtimes_root() / NAME / safe_key(key)
+ if not legacy.is_dir():
+ return
+ try:
+ if not (home / "state.db").exists():
+ for name in ("state.db", "state.db-wal", "state.db-shm"):
+ if (legacy / name).is_file():
+ shutil.copy2(legacy / name, home / name)
+ if (legacy / "sessions").is_dir():
+ shutil.copytree(legacy / "sessions", home / "sessions", dirs_exist_ok=True)
+ except OSError as exc:
+ log.warning("agent runtimes: Hermes sessions of %s not carried over: %s", key, exc)
+ return
+ shutil.rmtree(legacy, ignore_errors=True)
+ log.info("agent runtimes: moved Hermes agent %s into its profile", key)
+ parent = legacy.parent
+ try:
+ if parent.is_dir() and not any(parent.iterdir()):
+ parent.rmdir()
+ except OSError as exc:
+ log.debug("agent runtimes: legacy Hermes folder kept: %s", exc)
+
+
class HermesRuntime:
name = NAME
label = LABEL
def __init__(self) -> None:
self._detect = DetectCache()
- self._slots = TurnSlots()
+ self._slots = TurnSlots(NAME, lock_dir=lambda: base.runtimes_root() / "locks")
# ----------------------------------------------------------- detection
@@ -92,7 +237,11 @@ class HermesRuntime:
cached = self._detect.get()
if cached is not None:
return cached
- minimum = format_version(MINIMUM_VERSION)
+ from jarvis.agent_runtimes.path_cleanup import clean_user_path_once
+
+ clean_user_path_once()
+ pin = versions.pin(NAME)
+ minimum = format_version(pin.minimum)
binary = _binary()
if binary is None:
return self._detect.put(
@@ -106,7 +255,8 @@ class HermesRuntime:
install_hint=_install_hint(),
)
)
- version = parse_version(run_version([binary, "--version"]))
+ output = run_version([binary, "--version"])
+ version = parse_version(output)
if version is None:
return self._detect.put(
RuntimeStatus(
@@ -119,7 +269,7 @@ class HermesRuntime:
install_hint=_install_hint(),
)
)
- ready = version >= MINIMUM_VERSION
+ ready = version >= pin.minimum
return self._detect.put(
RuntimeStatus(
NAME,
@@ -131,25 +281,79 @@ class HermesRuntime:
problem="" if ready else f"Hermes {minimum} or newer is needed. Update it.",
problem_kind="" if ready else "outdated",
install_hint=_install_hint(),
+ untested=ready and pin.tested is not None and version > pin.tested,
+ build=output.splitlines()[0].strip() if output else "",
)
)
- def install_command(self) -> list[str] | None:
+ def install_command(self, revision: str | None = None) -> list[str] | None:
+ """The official installer, at the pinned commit (or ``revision``, a rollback).
+
+ Without browser tools (a headless Chromium) or desktop control: Jarvis
+ agents use Jarvis' visible browser and never Hermes' computer use.
+ """
+ commit = revision or versions.pin(NAME).commit
if is_windows():
- script = (
- f"& ([scriptblock]::Create((irm {_INSTALL_URL_PS1}))) -SkipSetup -NonInteractive"
+ flags = "-SkipSetup -NonInteractive -SkipBrowser -SkipComputerUse"
+ if commit:
+ flags += f" -Commit {ps_quote(commit)}"
+ return windows_installer(
+ f"& ([scriptblock]::Create((Invoke-RestMethod {_INSTALL_URL_PS1}))) {flags}"
)
- return ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", script]
- return [
- "bash",
- "-c",
- f"curl -fsSL {_INSTALL_URL_SH} | bash -s -- --skip-setup --non-interactive",
- ]
+ args = ["--skip-setup", "--non-interactive", "--skip-browser", "--skip-computer-use"]
+ if commit:
+ args += ["--commit", commit]
+ return posix_installer(_INSTALL_URL_SH, args, requires=("git",))
def update_command(self) -> list[str] | None:
+ """Update to the tested release: the installer at its pinned commit.
+
+ ``hermes update`` would go to upstream latest, which no canary has
+ seen; only a broken pins file falls back to it.
+ """
+ if versions.pin(NAME).commit:
+ return self.install_command()
binary = _binary()
return [binary, "update", "--yes"] if binary else None
+ def revision(self, status: RuntimeStatus) -> str:
+ """What a rollback reinstalls: the build's upstream commit."""
+ match = re.search(r"upstream ([0-9a-f]{7,40})|\.g([0-9a-f]{7,40})\b", status.build)
+ return (match.group(1) or match.group(2)) if match else ""
+
+ @property
+ def gate(self) -> Any:
+ return self._slots.gate
+
+ # ------------------------------------------------------------- prepare
+
+ def needs_prepare(self, status: RuntimeStatus) -> bool:
+ """Whether the shared root's environment was not yet built for this build."""
+ if not status.ready or not status.build:
+ return False
+ try:
+ done = (hermes_root() / ".jarvis-prepared").read_text(encoding="utf-8").strip()
+ except OSError: # never prepared on this machine
+ return True
+ return done != status.build
+
+ def mark_prepared(self, status: RuntimeStatus) -> None:
+ if status.build:
+ write_if_changed(hermes_root() / ".jarvis-prepared", status.build + "\n")
+
+ def prepare_command(self) -> tuple[list[str], dict[str, str]] | None:
+ """Build the shared root's dependency environment ahead of the first turn.
+
+ ``hermes profile list`` passes through Hermes' launch preparation (a
+ version query skips it), which syncs the data root's environment once
+ per Hermes build; afterwards every agent's first turn starts at once.
+ """
+ binary = _binary()
+ if binary is None:
+ return None
+ home = profile_home(_SETUP_KEY)
+ return [binary, "profile", "list"], child_env({"HERMES_HOME": str(home)})
+
def busy(self) -> bool:
return self._slots.busy()
@@ -172,6 +376,7 @@ class HermesRuntime:
# Session restore rebuilds the agent from the stored endpoint and
# reads the key next to a matching ``model.base_url``.
"base_url": route.base_url,
+ "context_length": route.context_window,
}
if route.api_key:
provider["key_env"] = KEY_ENV_VAR
@@ -182,6 +387,16 @@ class HermesRuntime:
"model": model,
"providers": {RUNTIME_PROVIDER_NAME: provider},
"terminal": {"cwd": str(turn.workspace)},
+ # Jarvis ends failed turns and retains the user's request. Do not
+ # stack Hermes retries, recovery cycles or paid fallback routes.
+ "agent": {
+ "api_max_retries": 1,
+ "auto_recovery_cycles": 0,
+ "disabled_toolsets": sorted(
+ _ALWAYS_DISABLED | _disabled_toolsets(turn.denied_native)
+ ),
+ },
+ "fallback_model": None,
# Jarvis owns memory and skills on every runtime.
"memory": {
"memory_enabled": False,
@@ -203,10 +418,18 @@ class HermesRuntime:
# never depends on which session wrote it last. Never the "smart"
# guardian, which spends model calls of its own.
"approvals": {"mode": "manual"},
+ # Never put the data root on the user's PATH (POSIX; see prepare_root).
+ "cli": {"expose_on_path": False},
}
- disabled = sorted(_disabled_toolsets(turn.denied_native))
- if disabled:
- config["agent"] = {"disabled_toolsets": disabled}
+ if turn.effort in _HERMES_EFFORTS:
+ # Hermes' ACP sessions resolve this per model (agent.reasoning_effort;
+ # "none" disables reasoning). No level = the model's own default.
+ config["agent"]["reasoning_effort"] = turn.effort
+ config_version = versions.pin(NAME).config_version
+ if config_version is not None:
+ # Without it Hermes reads the file as pre-version-12 and refuses to
+ # migrate it (logged on every Hermes update).
+ config["_config_version"] = config_version
return config
async def launch(self, turn: RuntimeTurn) -> RuntimeLaunch:
@@ -227,7 +450,7 @@ class HermesRuntime:
self, binary: str, turn: RuntimeTurn, release: Callable[[], None]
) -> RuntimeLaunch:
home = await asyncio.to_thread(
- agent_home, NAME, home_key(turn.agent_id, turn.session_id)
+ profile_home, home_key(turn.agent_id, turn.session_id)
)
await asyncio.to_thread(self._write_profile, home, turn)
env = child_env(
diff --git a/jarvis/agent_runtimes/manager.py b/jarvis/agent_runtimes/manager.py
index 81ce7fc234..2f64fd19d5 100644
--- a/jarvis/agent_runtimes/manager.py
+++ b/jarvis/agent_runtimes/manager.py
@@ -1,18 +1,23 @@
"""Install and keep Hermes / OpenClaw current with their own official tools.
Nobody sets either runtime up by hand. Choosing Hermes or OpenClaw for an
-agent starts :func:`ensure`: the project's own installer when it is missing
-(OpenClaw's also adds the Node.js it needs), its own updater when it is too
-old. A turn that finds its runtime not ready waits for that job
-(:func:`wait_ready`). While any agent uses a runtime, :func:`keep_current`
-runs the updater once a day when no turn of it is running; an update that
-leaves the runtime unable to start is repaired by a fresh install.
-
-One job per runtime at a time; its output goes to a log file whose tail the
-UI can show. Before an update every running process of that runtime is
-stopped — on Windows a running Hermes venv or OpenClaw Gateway would hold
-files the updater must replace. None of this calls a model, so nothing here
-spends a key.
+agent starts :func:`ensure`: the project's own installer when it is missing,
+an update when it is too old, and (Hermes) a one-time preparation of the
+data root Jarvis' agents share, so no turn pays for it. A turn that finds its
+runtime not ready waits for that job (:func:`wait_ready`).
+
+Every install and update goes to the release the agent-runtimes canary
+verified (``runtime-versions.json``, see ``versions``), never to upstream
+latest. While any agent uses a runtime, :func:`keep_current` brings an older
+install up to that release once a day when no turn of it is running. A setup
+that leaves the runtime unable to start is repaired by a fresh install, and
+when that fails too, by reinstalling the last release that worked.
+
+One job per runtime at a time, holding the runtime alone (``RuntimeGate``):
+it waits for running turns and new turns wait for it — an updater replaces
+files a running turn holds (on Windows it cannot). Its output goes to a log
+file whose tail the UI and the turn's error show. None of this calls a model,
+so nothing here spends a key.
"""
from __future__ import annotations
@@ -20,22 +25,32 @@ from __future__ import annotations
import asyncio
import contextlib
import logging
+import shutil
import time
-from collections.abc import Awaitable, Callable
+from collections.abc import AsyncIterator, Awaitable, Callable
from dataclasses import dataclass, field
+from pathlib import Path
from typing import Any, Final, Literal
-from jarvis.agent_runtimes import RUNTIME_NAMES, driver
-from jarvis.agent_runtimes.base import RuntimeStatus, child_env, runtimes_root
+from jarvis.agent_runtimes import RUNTIME_NAMES, base, driver, versions
+from jarvis.agent_runtimes.base import (
+ SETUP_MISSING_TOOL_EXIT,
+ RuntimeStatus,
+ child_env,
+ parse_version,
+)
log = logging.getLogger(__name__)
-JobKind = Literal["install", "update"]
+JobKind = Literal["install", "update", "prepare"]
JobState = Literal["running", "done", "failed"]
#: An installer that has not finished in this long is stopped.
_JOB_TIMEOUT_S: Final[float] = 30 * 60
+#: How long a setup job waits for running turns before it gives up.
+_GATE_WAIT_S: Final[float] = 20 * 60
+
#: First automatic update round after the app starts, then one per day.
_FIRST_UPDATE_DELAY_S: Final[float] = 10 * 60
_UPDATE_EVERY_S: Final[float] = 24 * 60 * 60
@@ -68,8 +83,8 @@ _JOBS: dict[str, RuntimeJob] = {}
_TASKS: dict[str, asyncio.Task[None]] = {}
-def _log_path(runtime: str) -> Any:
- root = runtimes_root()
+def _log_path(runtime: str) -> Path:
+ root = base.runtimes_root()
root.mkdir(parents=True, exist_ok=True)
return root / f"{runtime}-setup.log"
@@ -98,16 +113,24 @@ async def statuses(*, refresh: bool = False) -> list[dict[str, Any]]:
return out
+def _command(target: Any, kind: JobKind) -> tuple[list[str], dict[str, str] | None] | None:
+ if kind == "prepare":
+ prepare = getattr(target, "prepare_command", None)
+ return prepare() if prepare is not None else None
+ argv = target.install_command() if kind == "install" else target.update_command()
+ return (argv, None) if argv else None
+
+
async def start(runtime: str, kind: JobKind) -> RuntimeJob:
- """Start an install or update job; returns the running job if one exists."""
+ """Start an install, update or prepare job; returns the running job if one exists."""
if runtime not in RUNTIME_NAMES:
raise KeyError(runtime)
current = _JOBS.get(runtime)
if current is not None and current.state == "running":
return current
target = driver(runtime)
- argv = target.install_command() if kind == "install" else target.update_command()
- if not argv:
+ command = await asyncio.to_thread(_command, target, kind)
+ if not command:
failed = RuntimeJob(
runtime, kind, state="failed", message=f"{target.label} is not installed."
)
@@ -116,33 +139,35 @@ async def start(runtime: str, kind: JobKind) -> RuntimeJob:
return failed
new_job = RuntimeJob(runtime, kind)
_JOBS[runtime] = new_job
- _TASKS[runtime] = asyncio.get_running_loop().create_task(_run_job(new_job, argv))
+ _TASKS[runtime] = asyncio.get_running_loop().create_task(_run_job(new_job, *command))
return new_job
-def _needed(status: RuntimeStatus) -> JobKind | None:
- """Which job makes ``status`` ready; ``None`` when it already is."""
+def needed(target: Any, status: RuntimeStatus) -> JobKind | None:
+ """Which job makes ``status`` ready to run turns; ``None`` when it already is."""
if status.ready:
- return None
+ prepare = getattr(target, "needs_prepare", None)
+ return "prepare" if prepare is not None and prepare(status) else None
if not status.installed or status.problem_kind == "node":
- # OpenClaw's own installer is also what adds the Node.js it needs.
+ # Jarvis' own OpenClaw copy brings the Node.js it needs.
return "install"
return "update"
async def ensure(runtime: str) -> RuntimeJob | None:
- """Start the install or update ``runtime`` needs; ``None`` when it is ready."""
+ """Start the job ``runtime`` needs; ``None`` when it is ready."""
current = _JOBS.get(runtime)
if current is not None and current.state == "running":
return current
- status = await asyncio.to_thread(driver(runtime).detect, refresh=True)
- kind = _needed(status)
+ target = driver(runtime)
+ status = await asyncio.to_thread(target.detect, refresh=True)
+ kind = needed(target, status)
if kind is None:
return None
log.info(
"agent runtimes: %s is not ready (%s), starting its %s",
runtime,
- status.problem_kind,
+ status.problem_kind or "not prepared",
kind,
)
return await start(runtime, kind)
@@ -159,33 +184,100 @@ async def wait_ready(runtime: str, *, timeout_s: float = _JOB_TIMEOUT_S) -> Runt
return await asyncio.to_thread(driver(runtime).detect)
-async def _run_job(current: RuntimeJob, argv: list[str]) -> None:
+def failure_reason(runtime: str) -> str:
+ """Why the last setup of ``runtime`` failed, for the chat ("" when it did not)."""
+ current = _JOBS.get(runtime)
+ if current is None or current.state != "failed":
+ return ""
+ return current.message
+
+
+async def _alone(target: Any) -> AsyncIterator[None]:
+ gate = getattr(target, "gate", None)
+ if gate is None:
+ yield
+ return
+ async with gate.exclusive(_GATE_WAIT_S):
+ yield
+
+
+async def _run_job(current: RuntimeJob, argv: list[str], env: dict[str, str] | None) -> None:
+ target = driver(current.runtime)
try:
- await _run(current, argv)
- if current.kind != "update":
- return
- status = await asyncio.to_thread(driver(current.runtime).detect, refresh=True)
- if status.ready:
- return
- # The updater left a runtime that cannot start: the project's own
- # installer replaces it.
- install = driver(current.runtime).install_command()
- if not install:
- return
- log.warning(
- "agent runtimes: %s is not ready after its update (%s); reinstalling",
- current.runtime,
- status.problem_kind,
- )
- repair = RuntimeJob(current.runtime, "install")
- _JOBS[current.runtime] = repair
- await _run(repair, install)
+ try:
+ async with _alone(target):
+ await _run_setup(current, argv, env)
+ except TimeoutError: # reported through the job's state and message below
+ current.state = "failed"
+ current.finished_ms = int(time.time() * 1000)
+ current.message = (
+ f"{target.label} could not be set up while its agents kept working. "
+ "It is tried again when they are done."
+ )
finally:
_TASKS.pop(current.runtime, None)
+async def _run_setup(current: RuntimeJob, argv: list[str], env: dict[str, str] | None) -> None:
+ """The job, then whatever it still owes: repair, rollback, prepare."""
+ target = driver(current.runtime)
+ await _run(current, argv, env)
+ status = await asyncio.to_thread(target.detect, refresh=True)
+ if current.kind == "prepare":
+ if current.state == "done":
+ await asyncio.to_thread(target.mark_prepared, status)
+ return
+ if not status.ready and current.kind == "update":
+ # The update left a runtime that cannot start: a fresh install.
+ status = await _follow_up(current.runtime, "install", target.install_command())
+ if not status.ready:
+ status = await _roll_back(current.runtime, target, status)
+ if status.ready:
+ revision = getattr(target, "revision", None)
+ await asyncio.to_thread(
+ versions.remember_good,
+ current.runtime,
+ status.version,
+ revision(status) if revision is not None else "",
+ )
+ if needed(target, status) == "prepare":
+ command = target.prepare_command()
+ if command:
+ await _follow_up(current.runtime, "prepare", *command)
+
+
+async def _follow_up(
+ runtime: str, kind: JobKind, argv: list[str] | None, env: dict[str, str] | None = None
+) -> RuntimeStatus:
+ target = driver(runtime)
+ if argv:
+ log.info("agent runtimes: %s %s follows", runtime, kind)
+ follow = RuntimeJob(runtime, kind)
+ _JOBS[runtime] = follow
+ await _run(follow, argv, env)
+ status = await asyncio.to_thread(target.detect, refresh=True)
+ if kind == "prepare" and follow.state == "done":
+ await asyncio.to_thread(target.mark_prepared, status)
+ return status
+ return await asyncio.to_thread(target.detect, refresh=True)
+
+
+async def _roll_back(runtime: str, target: Any, status: RuntimeStatus) -> RuntimeStatus:
+ """Reinstall the last release that finished a setup ready, when it differs."""
+ good = await asyncio.to_thread(versions.last_good, runtime)
+ revision = str((good or {}).get("revision") or "")
+ if not good or not revision:
+ return status
+ if parse_version(str(good.get("version"))) == versions.pin(runtime).tested:
+ return status # the release that just failed: nothing older to go back to
+ argv = target.install_command(revision)
+ log.warning("agent runtimes: %s rolls back to %s", runtime, good.get("version"))
+ return await _follow_up(runtime, "install", argv)
+
+
async def keep_current(in_use: Callable[[], Awaitable[set[str]]]) -> None:
- """Update the runtimes agents use once a day, while none of their turns runs.
+ """Bring the runtimes agents use up to the tested release, once a day.
``in_use`` answers which runtimes at least one agent is set to. Runs until
cancelled (the society runtime owns the task); a failed round is logged
@@ -214,14 +306,37 @@ async def _update_when_idle(name: str) -> None:
if current is not None and current.state == "running":
return
status = await asyncio.to_thread(target.detect, refresh=True)
- kind: JobKind = "update" if status.installed and status.problem_kind != "node" else "install"
+ kind = needed(target, status)
+ if kind is None:
+ tested = versions.pin(name).tested
+ installed = parse_version(status.version)
+ if tested is None or installed is None or installed >= tested:
+ return # at (or past) the tested release: nothing to do
+ kind = "update"
await start(name, kind)
task = _TASKS.get(name)
if task is not None:
await asyncio.shield(task)
-async def _run(current: RuntimeJob, argv: list[str]) -> None:
+def _missing_launcher(argv: list[str]) -> str:
+ """A plain reason when the shell an installer needs is missing ("" otherwise)."""
+ head = Path(argv[0]).name.lower() if argv else ""
+ if head in {"bash", "powershell", "powershell.exe", "pwsh"} and shutil.which(argv[0]) is None:
+ return f"Setup needs {argv[0]}, which is not installed on this computer."
+ return ""
+
+
+def _failure_message(label: str, kind: str, code: int, runtime: str) -> str:
+ tail = [line.strip() for line in log_tail(runtime, 3) if line.strip()]
+ last = tail[-1][:300] if tail else ""
+ if code == SETUP_MISSING_TOOL_EXIT and last:
+ return last
+ message = f"{label} {kind} failed (exit {code})."
+ return f"{message} {last}" if last else message
+
+
+async def _run(current: RuntimeJob, argv: list[str], env: dict[str, str] | None = None) -> None:
from jarvis.core.process_tree import make_process_tree
from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS
@@ -229,17 +344,23 @@ async def _run(current: RuntimeJob, argv: list[str]) -> None:
if current.kind == "update":
await target.stop()
path = _log_path(current.runtime)
+ missing = _missing_launcher(argv)
tree = make_process_tree(f"{current.runtime}-{current.kind}")
try:
+ if missing:
+ path.write_text(missing + "\n", encoding="utf-8")
+ raise OSError(missing)
with path.open("wb") as handle:
- handle.write(f"$ {' '.join(argv)}\n".encode())
+ # Only the program and its first argument: an inline script body
+ # is long and says nothing the log below does not.
+ handle.write(f"$ {' '.join(argv[:2])} ...\n".encode())
handle.flush()
proc = await asyncio.create_subprocess_exec(
*argv,
stdin=asyncio.subprocess.DEVNULL,
stdout=handle,
stderr=handle,
- env=child_env(),
+ env=env if env is not None else child_env(),
creationflags=NO_WINDOW_CREATIONFLAGS,
start_new_session=True,
)
@@ -254,10 +375,10 @@ async def _run(current: RuntimeJob, argv: list[str]) -> None:
current.exit_code = code
current.state = "done" if code == 0 else "failed"
if code != 0 and not current.message:
- current.message = f"{target.label} {current.kind} failed (exit {code})."
+ current.message = _failure_message(target.label, current.kind, code, current.runtime)
except OSError as exc:
current.state = "failed"
- current.message = f"Could not start the {current.kind}: {exc}"
+ current.message = missing or f"Could not start the {current.kind}: {exc}"
log.warning("agent runtimes: %s %s could not start: %s", current.runtime, current.kind, exc)
finally:
tree.close()
@@ -266,5 +387,17 @@ async def _run(current: RuntimeJob, argv: list[str]) -> None:
# Cancelled (app shutdown): never leave a job that looks alive.
current.state = "failed"
current.message = current.message or f"The {current.kind} was interrupted."
- # ``--version`` spawns a process: off the event loop.
+ # What the installer registered on the persistent PATH is visible from now
+ # on (never a Jarvis agent folder); ``--version`` spawns: off the loop.
+ await asyncio.to_thread(_refresh_path)
await asyncio.to_thread(target.detect, refresh=True)
+
+
+def _refresh_path() -> None:
+ from jarvis.agent_runtimes.path_cleanup import is_jarvis_hermes_bin
+ from jarvis.core.path_augment import refresh_from_persistent_path
+
+ try:
+ refresh_from_persistent_path(skip=is_jarvis_hermes_bin)
+ except OSError as exc: # the registry is unreadable: the well-known folders still apply
+ log.debug("agent runtimes: persistent PATH not read: %s", exc)
diff --git a/jarvis/agent_runtimes/model_limits.py b/jarvis/agent_runtimes/model_limits.py
new file mode 100644
index 0000000000..883717ebd8
--- /dev/null
+++ b/jarvis/agent_runtimes/model_limits.py
@@ -0,0 +1,79 @@
+"""One model budget for the runtime config and gateway, without inference calls."""
+
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass
+from typing import Any
+
+#: The Ollama context an agent gets when the person chose none. A model's
+#: native window is often 256k, and Ollama allocates the whole KV cache up
+#: front: a 30B model at 256k needs about 45 GB and froze a 32 GB desktop.
+#: 64k is the smallest window Hermes accepts (its minimum is 64,000) and fits
+#: ordinary machines; a larger ``num_ctx`` on the model card is honoured.
+OLLAMA_DEFAULT_CONTEXT = 65_536
+
+
+@dataclass(frozen=True, slots=True)
+class ModelLimits:
+ context_window: int = 32_768
+ max_output_tokens: int | None = None
+
+ def wire(self) -> dict[str, int]:
+ # Hermes probes context_length / max_output_tokens; OpenClaw receives
+ # the same values as contextWindow / maxTokens in its provider config.
+ result = {"context_length": self.context_window}
+ if self.max_output_tokens is not None:
+ result["max_output_tokens"] = self.max_output_tokens
+ return result
+
+
+def positive_int(value: Any) -> int | None:
+ return value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else None
+
+
+def resolve_limits(config: Any, provider: str, model: str, metadata: Any = None) -> ModelLimits:
+ """Prefer declared per-model limits; use the plugin's budget when unknown.
+
+ Ollama uses the person's ``num_ctx`` (bounded by the native window), and
+ otherwise :data:`OLLAMA_DEFAULT_CONTEXT` (bounded the same way), never the
+ whole native window by default. The gateway configures that allocation on
+ the provider before inference.
+ No model names, vendor guesses, credentials or model calls are involved.
+ """
+ from jarvis.agent_chat.runner_api import BRAIN_BY_PROVIDER
+
+ defaults = ModelLimits()
+ context = defaults.context_window
+ output = defaults.max_output_tokens
+ plugin = BRAIN_BY_PROVIDER.get(provider)
+ if plugin is not None:
+ module, name = plugin
+ cls = getattr(importlib.import_module(module), name)
+ context = positive_int(getattr(cls, "context_window", None)) or context
+ output = positive_int(getattr(cls, "max_output_tokens", None)) or output
+ elif provider == "openai-codex":
+ from jarvis.live.subscription_reasoning import SubscriptionReasoningBrain
+
+ context = SubscriptionReasoningBrain.context_window
+ declared_context = positive_int(getattr(metadata, "context_length", None))
+ declared_output = positive_int(getattr(metadata, "max_output_tokens", None))
+ if declared_context is not None:
+ context = declared_context
+ if declared_output is not None:
+ output = declared_output
+ if provider == "ollama":
+ providers = getattr(getattr(config, "brain", None), "providers", {})
+ options = getattr(providers.get(provider), "models", {})
+ selected = options.get(model) or options.get(f"{model}:latest")
+ allocated = positive_int(getattr(selected, "num_ctx", None))
+ if allocated:
+ context = min(allocated, declared_context or allocated)
+ else:
+ context = min(context, OLLAMA_DEFAULT_CONTEXT)
+ requested_output = positive_int(getattr(selected, "num_predict", None))
+ if requested_output is not None:
+ output = min(requested_output, declared_output or requested_output)
+ # Report capacity, not an arbitrary input/output split. Unknown output
+ # capacity stays unknown instead of inventing an 8k ceiling.
+ return ModelLimits(context, min(output, context) if output is not None else None)
diff --git a/jarvis/agent_runtimes/model_map.py b/jarvis/agent_runtimes/model_map.py
index 37b60109b0..6601ea29c2 100644
--- a/jarvis/agent_runtimes/model_map.py
+++ b/jarvis/agent_runtimes/model_map.py
@@ -17,8 +17,9 @@ Claude Code as extra usage (pay as you go), so the picker says so.
from __future__ import annotations
+import asyncio
import logging
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
from typing import Any, Final, Literal
log = logging.getLogger(__name__)
@@ -47,6 +48,9 @@ class _Endpoint:
#: Without an API key, the person's Claude Code login answers instead
#: (billed by Anthropic as extra usage, not from the plan's limits).
claude_login: bool = False
+ #: May authenticate without a key: Google Cloud Application Default
+ #: Credentials for a configured project (Vertex AI).
+ cloud_project: bool = False
#: Jarvis provider id (``agent_chat.catalog`` / ``core.config``) -> endpoint.
@@ -57,6 +61,7 @@ _ENDPOINTS: Final[dict[str, _Endpoint]] = {
"openrouter": _Endpoint("https://openrouter.ai/api/v1"),
"nvidia": _Endpoint("https://integrate.api.nvidia.com/v1"),
"gemini": _Endpoint("https://generativelanguage.googleapis.com/v1beta/openai"),
+ "vertex": _Endpoint("https://aiplatform.googleapis.com", cloud_project=True),
"ollama": _Endpoint(None, keyless=True, local_server=True),
"local-openai": _Endpoint(None, keyless=True, local_server=True),
"openai-codex": _Endpoint(None, subscription=True),
@@ -77,6 +82,8 @@ class ModelRoute:
transport: Transport
#: ``None`` for a keyless local server.
api_key: str | None
+ context_window: int = 32_768
+ max_output_tokens: int | None = None
def env(self) -> dict[str, str]:
"""The child environment that carries the key (empty when keyless)."""
@@ -124,19 +131,26 @@ def _saved_key(provider: str, endpoint: _Endpoint) -> str | None:
return _api_key(provider, resolved.credential)
-def login_token_for(provider: str, account_id: str = "") -> str | None:
- """The Claude login ``provider`` answers on, or ``None`` when it runs on
- an API key (or cannot use a login at all). ``account_id`` may pin the
- agent to its key or to the login (``catalog.ACCESS_ACCOUNTS``); without a
- pin the API key wins. Blocking (keyring)."""
+def login_route(provider: str, account_id: str = "") -> tuple[bool, str | None]:
+ """Whether ``provider`` answers on the person's Claude Code login for
+ ``account_id``, and that login's live bearer (``None`` once it expired).
+ ``account_id`` may pin the agent to its key or to the login
+ (``catalog.ACCESS_ACCOUNTS``); without a pin the API key wins. Blocking
+ (keyring)."""
from jarvis.agent_chat.catalog import API_KEY_ACCOUNT, SUBSCRIPTION_ACCOUNT
endpoint = _ENDPOINTS.get(provider)
if endpoint is None or not endpoint.claude_login or account_id == API_KEY_ACCOUNT:
- return None
+ return False, None
if account_id != SUBSCRIPTION_ACCOUNT and _saved_key(provider, endpoint) is not None:
- return None
- return claude_login_token()
+ return False, None
+ return True, claude_login_token()
+
+
+def login_token_for(provider: str, account_id: str = "") -> str | None:
+ """The Claude login ``provider`` answers on, or ``None`` when it runs on
+ an API key (or cannot use a login at all). Blocking (keyring)."""
+ return login_route(provider, account_id)[1]
def login_providers() -> list[str]:
@@ -163,10 +177,36 @@ def access_choices() -> dict[str, list[str]]:
return choices
+def access_blocked() -> dict[str, dict[str, str]]:
+ """Per provider that can pay two ways, the ways that exist but are refused
+ right now, with the refusal's code: a live Claude Code login whose Extra
+ Usage is off (``extra_usage_off``) or spent (``extra_usage_spent``) — the
+ only way Anthropic serves a subscription to Hermes and OpenClaw. The
+ "New agent" dialog shows such a way disabled with its reason. Blocking
+ (keyring, one cached usage GET, no inference)."""
+ from jarvis.agent_runtimes.provider_errors import login_blocked
+
+ blocked: dict[str, dict[str, str]] = {}
+ for name, endpoint in _ENDPOINTS.items():
+ if not endpoint.claude_login:
+ continue
+ token = claude_login_token()
+ refusal = login_blocked(token, "") if token else None
+ if refusal is not None:
+ blocked[name] = {"subscription": refusal.code}
+ return blocked
+
+
def supports(provider: str) -> bool:
return provider in _ENDPOINTS
+def is_local(provider: str) -> bool:
+ """Whether ``provider`` is a model server the person runs themselves."""
+ endpoint = _ENDPOINTS.get(provider)
+ return endpoint is not None and endpoint.local_server
+
+
def usable_providers(config: Any) -> list[str]:
"""Supported providers that can run right now: a saved key, a keyless
local server with an address, or a signed-in subscription (listed
@@ -266,6 +306,11 @@ def _checked_model(config: Any, provider: str, model: str, *, account_id: str =
"Claude needs an Anthropic API key or a live Claude Code login. Connect "
"one in Settings → API keys, or open Claude Code once to renew its login."
)
+ if key is None and endpoint.cloud_project:
+ from jarvis.core.config import vertex_credential_configured
+
+ if vertex_credential_configured():
+ key = "" # the Cloud project signs the requests (no key)
if key is None and not endpoint.keyless and not endpoint.claude_login:
raise RouteUnavailable(
f"No API key is saved for {provider}. Connect it in Settings → API keys."
@@ -276,22 +321,79 @@ def _checked_model(config: Any, provider: str, model: str, *, account_id: str =
return chosen
+def _check_login_billing(provider: str, model: str, account_id: str) -> None:
+ """Fail before the runtime starts when Anthropic will refuse the Claude
+ login: it bills third-party apps only as Extra Usage (off or spent here).
+ Blocking (keyring, one cached usage GET)."""
+ login = login_token_for(provider, account_id)
+ if not login:
+ return
+ from jarvis.agent_runtimes.provider_errors import login_blocked
+
+ refusal = login_blocked(login, model)
+ if refusal is not None:
+ raise RouteUnavailable(refusal.message)
+
+
def route_for(
- config: Any, provider: str, model: str, *, agent_id: str = "", account_id: str = ""
+ config: Any,
+ provider: str,
+ model: str,
+ *,
+ agent_id: str = "",
+ account_id: str = "",
+ session_id: str = "",
) -> ModelRoute:
"""The agent's route through Jarvis' gateway. Blocking (keyring): call it
in a thread. The token speaks for ``agent_id`` on ``provider`` (and, for
the subscription, on that Codex ``account_id``)."""
chosen = _checked_model(config, provider, model, account_id=account_id)
+ _check_login_billing(provider, chosen, account_id)
from jarvis.agent_runtimes import gateway
-
+ from jarvis.agent_runtimes.base import home_key
+ from jarvis.agent_runtimes.model_limits import resolve_limits
+ from jarvis.brain.model_catalog import ModelCatalog
+
+ try:
+ gateway.check_cooldown(provider, chosen, account_id)
+ except gateway.GatewayError as exc:
+ raise RouteUnavailable(str(exc)) from exc
base_url = gateway.base_url()
if not base_url:
raise RouteUnavailable("Jarvis' model gateway is not up yet. Try again in a moment.")
+ limits = resolve_limits(config, provider, chosen, ModelCatalog().cached_model(provider, chosen))
+ token = gateway.grant_token(
+ agent_id, provider, account_id,
+ scope=home_key(agent_id, session_id) if session_id else "",
+ )
+ gateway.register_model(token, chosen, limits)
return ModelRoute(
provider=provider,
model=chosen,
base_url=base_url,
transport="responses" if _ENDPOINTS[provider].subscription else "chat_completions",
- api_key=gateway.grant_token(agent_id, provider, account_id),
+ api_key=token,
+ context_window=limits.context_window,
+ max_output_tokens=limits.max_output_tokens,
+ )
+
+
+async def prepare_route(
+ config: Any, provider: str, model: str, *, agent_id: str = "", account_id: str = "",
+ session_id: str = "",
+) -> ModelRoute:
+ """Refresh catalog metadata before writing either runtime's configuration."""
+ from jarvis.agent_runtimes import gateway
+
+ route = await asyncio.to_thread(
+ route_for, config, provider, model, agent_id=agent_id, account_id=account_id,
+ session_id=session_id,
+ )
+ assert route.api_key is not None
+ grant = gateway.verify(route.api_key)
+ assert grant is not None
+ limits = await gateway.refresh_model_limits(grant, route.model, config)
+ gateway.register_model(route.api_key, route.model, limits)
+ return replace(
+ route, context_window=limits.context_window, max_output_tokens=limits.max_output_tokens
)
diff --git a/jarvis/agent_runtimes/openclaw.py b/jarvis/agent_runtimes/openclaw.py
index 68ae0f6f75..5e8295f848 100644
--- a/jarvis/agent_runtimes/openclaw.py
+++ b/jarvis/agent_runtimes/openclaw.py
@@ -8,6 +8,12 @@ version-matched ``openclaw acp`` bridge against it. No Gateway WebSocket
client is written here: that wire protocol requires an exact version match,
the bridge that ships with the install always has it.
+Jarvis installs its own copy, at the tested release, into
+``<tools_root>/openclaw-cli`` with a private Node.js: no administrator
+rights, no system Node, no PATH change, and the person's own OpenClaw is
+never updated by Jarvis. A ready OpenClaw the person installed themselves is
+used until Jarvis' copy exists.
+
The config Jarvis writes uses only long-stable keys. The model key and the
Jarvis control key reach OpenClaw as ``${ENV}`` references the Gateway
substitutes from its own environment, so neither is written to disk. A config
@@ -31,8 +37,10 @@ from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Final
+from jarvis.agent_runtimes import base, versions
from jarvis.agent_runtimes.base import (
DetectCache,
+ HomeFileLock,
RuntimeLaunch,
RuntimeStatus,
RuntimeTurn,
@@ -44,8 +52,12 @@ from jarvis.agent_runtimes.base import (
home_key,
is_windows,
parse_version,
+ posix_installer,
+ ps_quote,
run_version,
+ safe_key,
which,
+ windows_installer,
write_if_changed,
write_json_if_changed,
)
@@ -56,22 +68,25 @@ log = logging.getLogger(__name__)
NAME: Final[str] = "openclaw"
LABEL: Final[str] = "OpenClaw"
-#: Oldest release verified with the embedding preset, ``openclaw acp`` against
-#: an isolated Gateway and config-level MCP with ``${ENV}`` substitution.
-MINIMUM_VERSION: Final[tuple[int, int, int]] = (2026, 9, 8)
-
#: The one conversation of an agent inside its own state folder.
SESSION_KEY: Final[str] = "agent:main:main"
#: Stop an agent's Gateway after this long without a turn.
IDLE_STOP_S: Final[float] = 15 * 60
-#: How long a Gateway may take to listen (about 16 s measured on Windows).
+#: How long a Gateway may take to listen (16-46 s measured on Windows).
_START_TIMEOUT_S: Final[float] = 120.0
+#: How long ``openclaw doctor --fix`` may run before it is stopped.
+_DOCTOR_TIMEOUT_S: Final[float] = 120.0
+
#: ``EX_CONFIG``: the Gateway refused its configuration.
_EXIT_CONFIG: Final[int] = 78
+#: Node.js for Jarvis' private copy (the release OpenClaw's own user-space
+#: installer pins; inside the engine range below).
+_PRIVATE_NODE_VERSION: Final[str] = "24.21.0"
+
#: The embedding preset from OpenClaw's embedding guide.
_EMBED_ENV: Final[dict[str, str]] = {
"OPENCLAW_DISABLE_BONJOUR": "1",
@@ -81,7 +96,8 @@ _EMBED_ENV: Final[dict[str, str]] = {
}
#: Native tools that duplicate a Jarvis feature (routines, messaging, other
-#: devices) and would bypass Jarvis' own approvals and budgets.
+#: devices, the visible browser) and would bypass Jarvis' own approvals and
+#: budgets.
_ALWAYS_DENIED: Final[tuple[str, ...]] = (
"automations",
"message",
@@ -89,28 +105,100 @@ _ALWAYS_DENIED: Final[tuple[str, ...]] = (
"conversations_turn",
"gateway",
"nodes",
+ "browser",
+)
+
+#: Bundled plugins no Jarvis agent loads: a headless browser, desktop control
+#: (cua-computer), device pairing and file transfer to other devices,
+#: location, voice, and an own GitHub login. The provider adapters stay;
+#: Jarvis' model gateway speaks their wire formats. Each one also costs
+#: Gateway start-up time (15 s for the plugin load, measured 2026-10-07).
+_DENIED_PLUGINS: Final[tuple[str, ...]] = (
+ "browser",
+ "canvas",
+ "cua-computer",
+ "device-pair",
+ "file-transfer",
+ "geolocation",
+ "github",
+ "linux-node",
+ "talk-voice",
)
_CONTROL_KEY_ENV: Final[str] = "JARVIS_CONTROL_API_KEY"
+#: ``agents.defaults.thinkingDefault`` levels OpenClaw accepts ("none" -> "off").
+_THINKING_LEVELS: Final[frozenset[str]] = frozenset(
+ {"off", "minimal", "low", "medium", "high", "xhigh", "max"}
+)
+
_INSTALL_URL_PS1: Final[str] = "https://openclaw.ai/install.ps1"
_INSTALL_URL_SH: Final[str] = "https://openclaw.ai/install.sh"
+#: OpenClaw's user-space installer: a private Node.js under ``--prefix``, no sudo.
+_INSTALL_CLI_URL_SH: Final[str] = "https://openclaw.ai/install-cli.sh"
+
+
+# ------------------------------------------------------------------ install
+
+
+def cli_prefix() -> Path:
+ """Where Jarvis keeps its own OpenClaw and the Node.js it runs on."""
+ return base.tools_root() / "openclaw-cli"
+
+
+def _private_launcher() -> list[str] | None:
+ prefix = cli_prefix()
+ if is_windows():
+ node = prefix / "node" / "node.exe"
+ entry = prefix / "pkg" / "node_modules" / "openclaw" / "openclaw.mjs"
+ return [str(node), str(entry)] if node.is_file() and entry.is_file() else None
+ wrapper = prefix / "bin" / "openclaw"
+ return [str(wrapper)] if wrapper.is_file() and os.access(wrapper, os.X_OK) else None
+
+
+def _installer_node_dirs() -> tuple[Path, ...]:
+ """Private Node.js folders OpenClaw's own installers create (never on PATH here)."""
+ dirs = [Path.home() / ".openclaw" / "tools" / "node" / "bin"]
+ local = os.environ.get("LOCALAPPDATA")
+ if local:
+ dirs.append(Path(local) / "OpenClaw" / "deps" / "portable-node")
+ return tuple(dirs)
+
+
+def _installer_bin_dirs() -> tuple[Path, ...]:
+ """Folders OpenClaw's installers put the command into besides npm's own."""
+ home = Path.home()
+ return (home / ".openclaw" / "bin", home / ".npm-global" / "bin")
+
+
+def _node() -> str | None:
+ # The installers' private Node first: it exists because the system one
+ # was missing or unsuitable.
+ for directory in _installer_node_dirs():
+ for name in ("node.exe", "node") if is_windows() else ("node",):
+ candidate = directory / name
+ if candidate.is_file():
+ return str(candidate)
+ return which("node", "node.exe")
def _launcher() -> list[str] | None:
- """How to start the installed OpenClaw CLI.
+ """How to start OpenClaw: Jarvis' own copy, else the person's install.
On Windows the npm shim is a ``.cmd`` file; running ``node openclaw.mjs``
directly keeps cmd.exe (and its argument quoting) out of the way. The
package's own launcher still picks OpenClaw's private Node runtime when
the system Node is too old.
"""
- shim = which("openclaw", "openclaw.cmd", "openclaw.exe")
+ private = _private_launcher()
+ if private is not None:
+ return private
+ shim = which("openclaw", "openclaw.cmd", "openclaw.exe", extra_dirs=_installer_bin_dirs())
if not shim:
return None
path = Path(shim)
if is_windows() and path.suffix.lower() in {".cmd", ".bat", ".ps1", ""}:
- node = which("node", "node.exe")
+ node = _node()
# A global install keeps the package beside the shim; a project
# install keeps the shim in node_modules/.bin.
for entry in (
@@ -130,9 +218,11 @@ def _node_supported(version: tuple[int, int, int] | None) -> bool:
def _private_node_present() -> bool:
- base = os.environ.get("OPENCLAW_HOME")
- root = Path(base) if base else Path.home() / ".openclaw"
- return (root / "tools" / "cli-node").is_dir()
+ base_dir = os.environ.get("OPENCLAW_HOME")
+ root = Path(base_dir) if base_dir else Path.home() / ".openclaw"
+ if (root / "tools" / "cli-node").is_dir():
+ return True
+ return any(directory.is_dir() for directory in _installer_node_dirs())
def _install_hint() -> str:
@@ -141,23 +231,41 @@ def _install_hint() -> str:
return f"curl -fsSL {_INSTALL_URL_SH} | bash -s -- --no-onboard"
+# ------------------------------------------------------------------ gateway
+
+
def _free_port() -> int:
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
sock.bind(("127.0.0.1", 0))
return int(sock.getsockname()[1])
-async def _listening(port: int) -> bool:
+async def _healthy(port: int) -> bool:
+ """Whether OpenClaw's Gateway answers its unauthenticated ``/healthz`` probe.
+
+ A bare TCP accept is not enough: another program may have taken the port
+ between choosing it and the Gateway binding it.
+ """
try:
- _reader, writer = await asyncio.wait_for(
+ reader, writer = await asyncio.wait_for(
asyncio.open_connection("127.0.0.1", port), timeout=2
)
except (OSError, TimeoutError): # not listening yet: the caller polls again
return False
- writer.close()
- with contextlib.suppress(OSError):
- await writer.wait_closed()
- return True
+ try:
+ writer.write(
+ f"GET /healthz HTTP/1.1\r\nHost: 127.0.0.1:{port}\r\nConnection: close\r\n\r\n".encode()
+ )
+ await writer.drain()
+ status = await asyncio.wait_for(reader.readline(), timeout=3)
+ except (OSError, TimeoutError): # still starting: the caller polls again
+ return False
+ finally:
+ writer.close()
+ with contextlib.suppress(OSError):
+ await writer.wait_closed()
+ parts = status.decode("latin-1", errors="replace").split()
+ return len(parts) >= 2 and parts[1] == "200"
@dataclass(slots=True)
@@ -170,6 +278,8 @@ class _Gateway:
proc: asyncio.subprocess.Process
tree: Any
log_handle: Any
+ lock: HomeFileLock
+ tracker: Any
last_used: float = field(default_factory=time.monotonic)
in_use: int = 0
@@ -177,6 +287,53 @@ class _Gateway:
return self.proc.returncode is None
+def _pid_file(home: Path) -> Path:
+ return home / "gateway.pid"
+
+
+def _write_pid_file(home: Path, pid: int, port: int) -> None:
+ import psutil
+
+ try:
+ created = psutil.Process(pid).create_time()
+ except psutil.Error: # gone already: nothing to sweep later
+ return
+ write_json_if_changed(_pid_file(home), {"pid": pid, "port": port, "created": created})
+
+
+def _reap_stale_gateway(home: Path) -> bool:
+ """Stop a Gateway an earlier app process left running (crash, force-quit).
+
+ Only the process recorded in this folder's ``gateway.pid`` — same pid,
+ same creation time, a ``gateway run`` command line — and its descendants.
+ Called with the folder's Gateway lock held, so its owner is gone.
+ """
+ path = _pid_file(home)
+ try:
+ record = json.loads(path.read_text(encoding="utf-8"))
+ except (OSError, ValueError): # no record: nothing was left behind
+ return False
+ import psutil
+
+ killed = False
+ try:
+ proc = psutil.Process(int(record["pid"]))
+ cmdline = " ".join(proc.cmdline())
+ same = abs(proc.create_time() - float(record["created"])) <= 1.0
+ if same and "gateway" in cmdline and "run" in cmdline:
+ for child in proc.children(recursive=True):
+ with contextlib.suppress(psutil.Error):
+ child.kill()
+ proc.kill()
+ killed = True
+ log.info("agent runtimes: stopped an OpenClaw gateway left by an earlier run")
+ except (psutil.Error, KeyError, TypeError, ValueError) as exc:
+ log.debug("agent runtimes: stale gateway record ignored: %s", exc)
+ with contextlib.suppress(OSError):
+ path.unlink()
+ return killed
+
+
class OpenClawRuntime:
name = NAME
label = LABEL
@@ -185,9 +342,13 @@ class OpenClawRuntime:
self._detect = DetectCache()
self._gateways: dict[str, _Gateway] = {}
self._locks: dict[str, asyncio.Lock] = {}
- self._slots = TurnSlots()
+ self._slots = TurnSlots(NAME, lock_dir=lambda: base.runtimes_root() / "locks")
self._reaper: asyncio.Task[None] | None = None
+ @property
+ def gate(self) -> Any:
+ return self._slots.gate
+
# ----------------------------------------------------------- detection
def detect(self, *, refresh: bool = False) -> RuntimeStatus:
@@ -196,7 +357,8 @@ class OpenClawRuntime:
cached = self._detect.get()
if cached is not None:
return cached
- minimum = format_version(MINIMUM_VERSION)
+ pin = versions.pin(NAME)
+ minimum = format_version(pin.minimum)
launcher = _launcher()
if launcher is None:
return self._detect.put(
@@ -210,24 +372,28 @@ class OpenClawRuntime:
install_hint=_install_hint(),
)
)
- version = parse_version(run_version([*launcher, "--version"]))
+ output = run_version([*launcher, "--version"])
+ version = parse_version(output)
problem = ""
kind = ""
if version is None:
problem = "OpenClaw is installed but did not report its version."
kind = "no_version"
- elif version < MINIMUM_VERSION:
+ elif version < pin.minimum:
problem = f"OpenClaw {minimum} or newer is needed. Update it."
kind = "outdated"
- else:
- node = which("node", "node.exe")
+ elif _private_launcher() is None:
+ # The person's own install runs on whatever Node.js they have;
+ # Jarvis' copy brings its own.
+ node = _node()
node_version = parse_version(run_version([node, "--version"])) if node else None
if not _node_supported(node_version) and not _private_node_present():
problem = (
- "OpenClaw needs Node.js 24.16+ or 26.1+. Run the OpenClaw "
- "installer once; it adds a suitable Node.js for OpenClaw only."
+ "OpenClaw needs Node.js 24.16+ or 26.1+. Jarvis installs its own "
+ "copy of OpenClaw with a suitable Node.js."
)
kind = "node"
+ ready = not problem
return self._detect.put(
RuntimeStatus(
NAME,
@@ -235,31 +401,65 @@ class OpenClawRuntime:
installed=True,
version=format_version(version) if version else "",
minimum_version=minimum,
- ready=not problem,
+ ready=ready,
problem=problem,
problem_kind=kind,
install_hint=_install_hint(),
+ untested=bool(
+ ready and version and pin.tested is not None and version > pin.tested
+ ),
+ build=output.splitlines()[0].strip() if output else "",
)
)
- def install_command(self) -> list[str] | None:
+ def install_command(self, revision: str | None = None) -> list[str] | None:
+ """Install Jarvis' own copy at the tested release (or ``revision``).
+
+ Windows: OpenClaw's installer provides only the private, checksum-
+ verified Node.js (``-NodeOnly``; its full mode would try ``winget``
+ first, a machine-wide install behind a UAC prompt), then that Node's
+ npm installs the package into Jarvis' folder. macOS/Linux: OpenClaw's
+ user-space installer does both under ``--prefix`` without sudo.
+ """
+ version = revision or versions.pin(NAME).tested_text or "latest"
+ prefix = cli_prefix()
if is_windows():
- script = (
- f"& ([scriptblock]::Create((iwr -useb {_INSTALL_URL_PS1}))) -NoOnboard"
+ node_dir = prefix / "node"
+ npm_cli = node_dir / "node_modules" / "npm" / "bin" / "npm-cli.js"
+ body = (
+ f"& ([scriptblock]::Create((Invoke-RestMethod {_INSTALL_URL_PS1}))) "
+ f"-NodeOnly -NodePrefix {ps_quote(str(node_dir))} "
+ f"-NodeVersion {ps_quote(_PRIVATE_NODE_VERSION)}; "
+ # npm runs package scripts through ``cmd /c node ...``: without
+ # this, ``node`` is the system's (CI: 22, rejected by OpenClaw's
+ # preinstall) or missing. This install process only, never PATH.
+ f"$env:Path = {ps_quote(str(node_dir) + ';')} + $env:Path; "
+ f"& {ps_quote(str(node_dir / 'node.exe'))} {ps_quote(str(npm_cli))} "
+ f"install -g --prefix {ps_quote(str(prefix / 'pkg'))} "
+ f"{ps_quote('openclaw@' + version)} --no-fund --no-audit --loglevel=error; "
+ "exit $LASTEXITCODE"
)
- return ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", script]
- return ["bash", "-c", f"curl -fsSL {_INSTALL_URL_SH} | bash -s -- --no-onboard"]
+ return windows_installer(body)
+ return posix_installer(
+ _INSTALL_CLI_URL_SH,
+ ["--prefix", str(prefix), "--version", version, "--no-onboard"],
+ requires=("git",),
+ )
def update_command(self) -> list[str] | None:
- launcher = _launcher()
- # No restart: Jarvis supervises its own Gateways and the person's own
- # Gateway service is theirs to restart.
- return [*launcher, "update", "--yes", "--no-restart"] if launcher else None
+ """Update = install Jarvis' copy at the tested release; never ``openclaw update``,
+ which goes to upstream latest and would update the person's own install."""
+ return self.install_command()
+
+ def revision(self, status: RuntimeStatus) -> str:
+ """What a rollback reinstalls: the release itself."""
+ return status.version
# -------------------------------------------------------------- config
def config_for(self, turn: RuntimeTurn, *, port: int, token: str) -> dict[str, Any]:
route = turn.route
+ home = base.runtimes_root() / NAME / safe_key(home_key(turn.agent_id, turn.session_id))
provider: dict[str, Any] = {
"baseUrl": route.base_url,
# A keyless local server still needs a non-empty value.
@@ -272,15 +472,19 @@ class OpenClawRuntime:
{
"id": route.model,
"name": route.model,
- "input": ["text"],
- "contextWindow": 128_000,
- "maxTokens": 8_192,
+ # Declared catalog capabilities only; OpenClaw's defaults
+ # (no reasoning, text only) stand for an unknown model.
+ "input": ["text", "image"] if turn.vision else ["text"],
+ **({"reasoning": True} if turn.reasoning else {}),
+ "contextWindow": route.context_window,
+ **({"maxTokens": route.max_output_tokens}
+ if route.max_output_tokens is not None else {}),
}
],
}
denied = list(_ALWAYS_DENIED)
if "web" in turn.denied_native:
- denied += ["browser", "web_search", "web_fetch"]
+ denied += ["web_search", "web_fetch"]
# "ask" relays every exec approval over ACP; Jarvis answers it from the
# chat's stance (Bypass allows without a card), so the file does not
# change with the stance of whichever turn wrote it.
@@ -306,17 +510,25 @@ class OpenClawRuntime:
}
},
"session": {"reset": {"mode": "none"}},
- # Jarvis owns scheduling and memory. The native memory plugin
- # can create its own jobs even with heartbeat disabled.
+ # Heartbeat is only one background caller. The memory plugin can
+ # create dreaming jobs at startup even with heartbeat disabled.
+ # Jarvis owns memory and scheduling; neither may call this key.
"cron": {"enabled": False},
"plugins": {
+ "deny": list(_DENIED_PLUGINS),
"slots": {"memory": "none"},
"entries": {"memory-core": {"enabled": False}},
},
# Jarvis' tools offered directly, never behind OpenClaw's tool search
# (on by default for local models; smaller models miss deferred tools).
"tools": {"deny": denied, "exec": {"mode": exec_mode}, "toolSearch": False},
+ # The agent's log stays in its own folder, never in the shared
+ # temp-folder log every OpenClaw on the machine appends to.
+ "logging": {"file": str(home / "state" / "logs" / "openclaw.log")},
}
+ thinking = "off" if turn.effort == "none" else turn.effort
+ if thinking in _THINKING_LEVELS:
+ config["agents"]["defaults"]["thinkingDefault"] = thinking
if turn.mcp_url and turn.control_key:
from jarvis.agent_chat.jarvis_harness import HEADER_NAME
@@ -435,7 +647,9 @@ class OpenClawRuntime:
await self._stop_gateway(current)
current = None
if current is None:
- current = await self._start_gateway(key, home, port, env_hash, launcher, env)
+ current = await self._start_gateway(
+ turn, key, home, port, token, env_hash, launcher, env
+ )
self._gateways[key] = current
current.in_use += 1
current.last_used = time.monotonic()
@@ -447,16 +661,59 @@ class OpenClawRuntime:
async def _start_gateway(
self,
+ turn: RuntimeTurn,
key: str,
home: Path,
port: int,
+ token: str,
env_hash: str,
launcher: list[str],
env: dict[str, str],
+ ) -> _Gateway:
+ # The folder's Gateway belongs to one process: an app that died without
+ # stopping it (crash, force-quit, kill) left its pid behind.
+ lock = HomeFileLock(home / "gateway.lock")
+ if not await asyncio.to_thread(lock.try_acquire):
+ raise RuntimeUnavailable(
+ "Another Jarvis process runs this agent's OpenClaw right now. Close it, "
+ "then try again."
+ )
+ try:
+ await asyncio.to_thread(_reap_stale_gateway, home)
+ gateway = await self._spawn_until_ready(key, home, port, env_hash, launcher, env, lock)
+ if gateway is None:
+ # The port was taken before the Gateway bound it: once more on a
+ # fresh port.
+ port = _free_port()
+ await asyncio.to_thread(
+ write_json_if_changed,
+ home / "openclaw.json",
+ self.config_for(turn, port=port, token=token),
+ )
+ gateway = await self._spawn_until_ready(
+ key, home, port, env_hash, launcher, env, lock, last_try=True
+ )
+ assert gateway is not None
+ return gateway
+ except BaseException:
+ lock.release()
+ raise
+
+ async def _spawn_until_ready(
+ self,
+ key: str,
+ home: Path,
+ port: int,
+ env_hash: str,
+ launcher: list[str],
+ env: dict[str, str],
+ lock: HomeFileLock,
*,
repaired: bool = False,
- ) -> _Gateway:
- from jarvis.core.process_tree import make_process_tree
+ last_try: bool = False,
+ ) -> _Gateway | None:
+ """Start the Gateway and wait until it answers; ``None`` = retry on a new port."""
+ from jarvis.core.process_tree import DescendantTracker, make_process_tree
from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS
log_path = home / "gateway.log"
@@ -484,35 +741,43 @@ class OpenClawRuntime:
tree.close()
raise RuntimeUnavailable(f"OpenClaw could not start: {exc}") from exc
tree.assign(proc.pid)
- gateway = _Gateway(key, home, port, env_hash, proc, tree, handle)
+ tracker = DescendantTracker(proc.pid, interval_s=5.0)
+ tracker.start()
+ gateway = _Gateway(key, home, port, env_hash, proc, tree, handle, lock, tracker)
+ await asyncio.to_thread(_write_pid_file, home, proc.pid, port)
log.info("agent runtimes: OpenClaw gateway %s starting on %s", key, port)
+ started = time.monotonic()
try:
- deadline = time.monotonic() + _START_TIMEOUT_S
+ deadline = started + _START_TIMEOUT_S
while time.monotonic() < deadline:
if proc.returncode is not None:
break
- if await _listening(port):
+ if await _healthy(port) and proc.returncode is None:
return gateway
await asyncio.sleep(0.5)
except BaseException:
# A cancelled turn (Stop during a cold start) must not leave a
# Gateway behind with the key in its environment.
- await asyncio.shield(self._stop_gateway(gateway))
+ await asyncio.shield(self._stop_gateway(gateway, keep_lock=True))
raise
returncode = proc.returncode
- await self._stop_gateway(gateway)
+ await self._stop_gateway(gateway, keep_lock=True)
if returncode == _EXIT_CONFIG and not repaired:
log.warning("agent runtimes: OpenClaw rejected its config; running doctor --fix")
await _run_doctor(launcher, env, home)
- return await self._start_gateway(
- key, home, port, env_hash, launcher, env, repaired=True
+ return await self._spawn_until_ready(
+ key, home, port, env_hash, launcher, env, lock,
+ repaired=True, last_try=last_try,
)
+ if returncode is not None and returncode != _EXIT_CONFIG and not last_try:
+ if time.monotonic() - started < _START_TIMEOUT_S / 2:
+ return None
tail = _log_tail(log_path)
if returncode is None:
raise RuntimeUnavailable("OpenClaw did not start within two minutes." + tail)
raise RuntimeUnavailable(f"OpenClaw stopped while starting (exit {returncode})." + tail)
- async def _stop_gateway(self, gateway: _Gateway) -> None:
+ async def _stop_gateway(self, gateway: _Gateway, *, keep_lock: bool = False) -> None:
if self._gateways.get(gateway.key) is gateway:
del self._gateways[gateway.key]
if gateway.proc.returncode is None:
@@ -523,10 +788,16 @@ class OpenClawRuntime:
except TimeoutError:
log.info("agent runtimes: OpenClaw gateway %s ignored terminate", gateway.port)
# Closing the container reaps whatever the Gateway started (MCP servers,
- # exec children), including a Gateway that ignored terminate.
+ # exec children), including a Gateway that ignored terminate; the
+ # tracker reaps children that left its process group (POSIX).
gateway.tree.close()
+ gateway.tracker.close()
with contextlib.suppress(OSError):
gateway.log_handle.close()
+ with contextlib.suppress(OSError):
+ _pid_file(gateway.home).unlink()
+ if not keep_lock:
+ gateway.lock.release()
def _ensure_reaper(self) -> None:
if self._reaper is None or self._reaper.done():
@@ -581,16 +852,18 @@ def _gateway_token(home: Path) -> str:
except OSError: # no token yet: one is minted below
pass
token = secrets.token_urlsafe(32)
- write_if_changed(path, token)
- with contextlib.suppress(OSError):
- path.chmod(0o600)
- (home / "state").mkdir(parents=True, exist_ok=True)
+ # Readable by this user only from its first byte (POSIX 0600).
+ write_if_changed(path, token, private=True)
+ (home / "state").mkdir(parents=True, exist_ok=True, mode=0o700)
return token
async def _run_doctor(launcher: list[str], env: dict[str, str], home: Path) -> None:
+ from jarvis.core.process_tree import make_process_tree
from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS
+ tree = make_process_tree("openclaw-doctor")
+ proc: asyncio.subprocess.Process | None = None
try:
proc = await asyncio.create_subprocess_exec(
*launcher,
@@ -604,10 +877,18 @@ async def _run_doctor(launcher: list[str], env: dict[str, str], home: Path) -> N
stdout=asyncio.subprocess.DEVNULL,
stderr=asyncio.subprocess.DEVNULL,
creationflags=NO_WINDOW_CREATIONFLAGS,
+ start_new_session=os.name != "nt",
)
- await asyncio.wait_for(proc.wait(), timeout=120)
+ tree.assign(proc.pid)
+ await asyncio.wait_for(proc.wait(), timeout=_DOCTOR_TIMEOUT_S)
except (OSError, TimeoutError) as exc:
log.warning("agent runtimes: openclaw doctor --fix failed: %s", exc)
+ if proc is not None and proc.returncode is None:
+ with contextlib.suppress(ProcessLookupError, OSError):
+ proc.kill()
+ finally:
+ # Never leave a doctor running: the next start reads the same config.
+ tree.close()
def _log_tail(path: Path, lines: int = 6) -> str:
diff --git a/jarvis/agent_runtimes/path_cleanup.py b/jarvis/agent_runtimes/path_cleanup.py
new file mode 100644
index 0000000000..c60bc47181
--- /dev/null
+++ b/jarvis/agent_runtimes/path_cleanup.py
@@ -0,0 +1,132 @@
+"""Remove the user-PATH entries older Jarvis builds let Hermes register.
+
+Hermes' home maintenance mirrors its Windows installer: it stages launchers in
+``<data root>\\bin`` and prepends that folder to the user's PATH
+(``hermes_cli._launchers._expose_windows_user_bin``). Earlier Jarvis builds
+gave every agent its own data root, so every agent folder (and every test's
+temporary folder) ended up on the user's PATH, in front of the real Hermes.
+The profile layout in ``hermes.py`` stops new entries; this module takes the
+old ones out again, once per process, touching nothing but entries that point
+into a Jarvis ``agent_runtimes`` folder.
+
+The registry is injectable so tests never read or write the real one.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import sys
+from collections.abc import MutableMapping
+from typing import Final, Protocol
+
+log = logging.getLogger(__name__)
+
+#: ``...\\agent_runtimes[-<instance>]\\hermes\\<agent>\\bin`` (old per-agent
+#: data roots, including tests' temporary ones) and the shared root's ``bin``.
+_JARVIS_HERMES_BIN: Final[re.Pattern[str]] = re.compile(
+ r"[\\/]agent_runtimes(?:-[a-z0-9-]+)?[\\/](?:hermes[\\/][^\\/]+|hermes-home)[\\/]bin[\\/]?$",
+ re.IGNORECASE,
+)
+
+_done = False
+
+
+class UserPathStore(Protocol):
+ """Where the user's persistent PATH lives (HKCU\\Environment on Windows)."""
+
+ def read(self) -> tuple[str, int] | None:
+ """The stored value and its registry type, or ``None`` when there is none."""
+ ...
+
+ def write(self, value: str, kind: int) -> None: ...
+
+
+class _WindowsUserPath:
+ def read(self) -> tuple[str, int] | None:
+ import winreg
+
+ access = winreg.KEY_QUERY_VALUE
+ with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment", 0, access) as key:
+ try:
+ value, kind = winreg.QueryValueEx(key, "Path")
+ except FileNotFoundError: # no user PATH at all: nothing to clean
+ return None
+ return str(value), int(kind)
+
+ def write(self, value: str, kind: int) -> None:
+ import ctypes
+ import winreg
+
+ access = winreg.KEY_SET_VALUE
+ with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment", 0, access) as key:
+ winreg.SetValueEx(key, "Path", 0, kind, value)
+ # WM_SETTINGCHANGE so new terminals see the cleaned PATH.
+ ctypes.windll.user32.SendMessageTimeoutW( # type: ignore[attr-defined]
+ 0xFFFF, 0x1A, 0, "Environment", 0x0002, 5000, None
+ )
+
+
+def is_jarvis_hermes_bin(entry: str) -> bool:
+ """Whether a PATH entry is a Hermes ``bin`` folder inside Jarvis' data."""
+ expanded = os.path.expandvars(entry.strip().strip('"'))
+ return bool(expanded) and bool(_JARVIS_HERMES_BIN.search(expanded))
+
+
+def _without(value: str, separator: str) -> tuple[str, list[str]]:
+ kept: list[str] = []
+ removed: list[str] = []
+ for part in value.split(separator):
+ (removed if part and is_jarvis_hermes_bin(part) else kept).append(part)
+ return separator.join(kept), removed
+
+
+def clean_user_path(
+ *,
+ store: UserPathStore | None = None,
+ environ: MutableMapping[str, str] | None = None,
+) -> list[str]:
+ """Drop Jarvis' Hermes ``bin`` entries from the user PATH and this process.
+
+ Returns the removed registry entries. Windows only (POSIX installs never
+ had them: Hermes honours ``cli.expose_on_path`` there); a no-op elsewhere
+ unless a ``store`` is injected.
+ """
+ env = os.environ if environ is None else environ
+ current = env.get("PATH", "")
+ if current:
+ cleaned, dropped = _without(current, os.pathsep)
+ if dropped:
+ env["PATH"] = cleaned
+ if store is None:
+ if sys.platform != "win32":
+ return []
+ store = _WindowsUserPath()
+ stored = store.read()
+ if stored is None:
+ return []
+ value, kind = stored
+ cleaned, removed = _without(value, ";")
+ if removed:
+ store.write(cleaned, kind)
+ log.info("agent runtimes: removed %d stale Hermes PATH entries", len(removed))
+ return removed
+
+
+def clean_user_path_once() -> None:
+ """:func:`clean_user_path` the first time a Hermes turn or setup runs."""
+ global _done
+ if _done:
+ return
+ _done = True
+ if os.environ.get("PYTEST_CURRENT_TEST"):
+ # A test that reaches the real driver never edits this machine's
+ # registry; the cleanup itself is tested with an injected store.
+ return
+ try:
+ clean_user_path()
+ except OSError as exc:
+ # The registry may be locked down by policy; Hermes still runs, the
+ # stale entries only shadow the user's own ``hermes`` command.
+ log.warning("agent runtimes: could not clean the user PATH: %s", exc)
diff --git a/jarvis/agent_runtimes/provider_errors.py b/jarvis/agent_runtimes/provider_errors.py
index 8ed71c928f..64b64853c7 100644
--- a/jarvis/agent_runtimes/provider_errors.py
+++ b/jarvis/agent_runtimes/provider_errors.py
@@ -2,29 +2,41 @@
A provider's HTTP status alone misleads: OpenAI answers an empty credit
balance with 429, OpenRouter with 402, and Anthropic refuses a Claude
-subscription used outside Claude Code with a bare 429 ``rate_limit_error``
-while the plan still has room. Each of those reads as "rate limited, try
+subscription used by a third-party app with a 400 or a bare 429
+``rate_limit_error`` while the plan still has room. Each of those reads as "rate limited, try
again in 30 s" — and no retry will ever succeed. This module tells them apart:
* **No credits / no quota** on a key -> 402 ``billing`` (a runtime does not
retry it; Hermes classifies 402 as billing and stops).
* **Provider not reachable** (a local model server that is not running, no
network) -> 503 ``provider_unreachable``.
-* **Claude subscription**: Anthropic serves a subscription outside Claude Code
- only through the account's Extra Usage for most models. A 429 on the login
- is explained from the account's own usage report (``/api/oauth/usage``, the
- endpoint Claude Code reads; it spends no inference): the plan window really
- is used up, or Extra Usage is turned off / its monthly limit is spent.
+* **Context too long** -> 400 ``context_length_exceeded`` with the words
+ "context length exceeded", which both runtimes read as "compress the
+ conversation and send it again".
+* **Took too long** (a read timeout while the model was still working) -> 504
+ ``timeout``, never "not reachable".
+* **Model not offered**, **tools not supported**, **tool schema refused** ->
+ 404 ``model_not_found`` / 400 ``tools_unsupported`` / 400
+ ``invalid_tool_schema``: deterministic, so nothing retries them.
+* **Claude subscription**: Anthropic serves a subscription to third-party
+ apps such as Hermes and OpenClaw only from the account's Extra Usage
+ ("Third-party apps now draw from your extra usage, not your plan limits"),
+ answering 400 or a bare 429 otherwise. The account's own usage report
+ (``/api/oauth/usage``, the endpoint Claude Code reads; no inference) says
+ whether Extra Usage is off or its monthly limit is spent, so a turn can
+ fail at once (``login_blocked``) instead of after a runtime start.
Messages never copy the provider's response body; the body is only matched.
+:func:`describe` gives a bounded, redacted line for the log, so a failed
+turn can be diagnosed without reproducing it.
"""
from __future__ import annotations
import asyncio
import logging
+import re
from dataclasses import dataclass
-from datetime import UTC, datetime
from typing import Any, Final
from jarvis.core.http_pool import SyncHttpClientPool
@@ -58,23 +70,95 @@ _BILLING_PHRASES: Final[tuple[str, ...]] = (
#: Transport failures, by class name across the SDKs (openai, anthropic,
#: httpx): the name is the stable capability signal, a class import is not.
+#: A connect failure means nothing answered; it is checked before the
+#: timeouts below, because the SDKs wrap a connect timeout in their timeout
+#: class.
_UNREACHABLE_ERRORS: Final[frozenset[str]] = frozenset(
- {"APIConnectionError", "APITimeoutError", "ConnectError", "ConnectTimeout"}
+ {"APIConnectionError", "ConnectError", "ConnectTimeout"}
)
+_CONNECT_ERRORS: Final[frozenset[str]] = frozenset({"ConnectError", "ConnectTimeout"})
-_HTTP_POOL: Final = SyncHttpClientPool(timeout_s=8.0)
+#: The model was reached and did not answer in time (a long thinking phase,
+#: a slow local prefill): worth another try, never "start the server".
+_TIMEOUT_ERRORS: Final[frozenset[str]] = frozenset(
+ {
+ "APITimeoutError",
+ "ReadTimeout",
+ "WriteTimeout",
+ "PoolTimeout",
+ "TimeoutException",
+ "TimeoutError",
+ }
+)
-_CLAUDE_USAGE_URL: Final[str] = "https://api.anthropic.com/api/oauth/usage"
-_CLAUDE_OAUTH_BETA: Final[str] = "oauth-2025-04-20"
+#: A request longer than the model's context window, in each provider's
+#: words (OpenAI/OpenRouter/vLLM, Anthropic, Gemini, llama.cpp). Matched in
+#: lower case, on a 4xx or a status-less stream error only.
+_OVERFLOW_CODES: Final[frozenset[str]] = frozenset(
+ {"context_length_exceeded", "string_above_max_length", "request_too_large"}
+)
+_OVERFLOW_PHRASES: Final[tuple[str, ...]] = (
+ "context length",
+ "context_length",
+ "maximum context",
+ "context window",
+ "prompt is too long",
+ "input is too long",
+ "too many tokens",
+ "exceeds the maximum number of tokens",
+ "input token count",
+ "max_model_len",
+ "maximum allowed input length",
+ "reduce the length of the messages",
+)
+
+_MODEL_MISSING_CODES: Final[frozenset[str]] = frozenset({"model_not_found"})
+_TOOLS_UNSUPPORTED_PHRASES: Final[tuple[str, ...]] = (
+ "does not support tools",
+ "tools are not supported",
+ "tool use is not supported",
+ "does not support function calling",
+ "function calling is not enabled",
+ "tool calling is not supported",
+)
+_TOOL_SCHEMA_CODES: Final[frozenset[str]] = frozenset(
+ {"invalid_function_parameters", "invalid_tool_schema"}
+)
+_TOOL_SCHEMA_PHRASES: Final[tuple[str, ...]] = (
+ "invalid schema for function",
+ "input_schema",
+ "function_declarations",
+ "json schema is invalid",
+)
+
+#: Codes after which the Jarvis turn ends at once: no retry, compression or
+#: wait inside the runtime changes the answer (a rate limit carries the
+#: cooldown the person is told about). Every other failure goes back to the
+#: runtime, whose own retry and compression handle it.
+TERMINAL_CODES: Final[frozenset[str]] = frozenset(
+ {
+ "billing",
+ "extra_usage_off",
+ "extra_usage_spent",
+ "provider_auth",
+ "claude_login_expired",
+ "model_not_found",
+ "invalid_tool_schema",
+ "tools_unsupported",
+ "rate_limited",
+ }
+)
-#: The plan windows in the usage report, named the way a person reads them.
-_CLAUDE_WINDOWS: Final[tuple[tuple[str, str], ...]] = (
- ("five_hour", "5-hour"),
- ("seven_day", "weekly"),
- ("seven_day_opus", "weekly Opus"),
- ("seven_day_sonnet", "weekly Sonnet"),
+#: Key- and token-shaped strings masked in :func:`describe`.
+_SECRET_RE: Final = re.compile(
+ r"(sk-[A-Za-z0-9_\-]{6,}|AIza[0-9A-Za-z_\-]{10,}|jrg_[A-Za-z0-9_\-]{6,}"
+ r"|[Bb]earer\s+[A-Za-z0-9._\-]{10,}|eyJ[A-Za-z0-9._\-]{20,})"
)
+_HTTP_POOL: Final = SyncHttpClientPool(timeout_s=8.0)
+
+_CLAUDE_USAGE_URL: Final[str] = "https://api.anthropic.com/api/oauth/usage"
+_CLAUDE_OAUTH_BETA: Final[str] = "oauth-2025-04-20"
@dataclass(frozen=True, slots=True)
class Refusal:
@@ -83,8 +167,6 @@ class Refusal:
status: int
code: str
message: str
- #: Seconds until the refusal lifts, when the provider says so.
- retry_after: float | None = None
class ProviderRefusal(Exception):
@@ -96,21 +178,29 @@ class ProviderRefusal(Exception):
def _status(exc: BaseException) -> int | None:
- status = getattr(exc, "status_code", None) or getattr(exc, "status", None)
- if not isinstance(status, int):
- status = getattr(getattr(exc, "response", None), "status_code", None)
- return status if isinstance(status, int) else None
+ for value in (
+ getattr(exc, "status_code", None),
+ getattr(exc, "status", None),
+ # google-genai: ``code`` is the HTTP status, ``status`` its name.
+ getattr(exc, "code", None),
+ getattr(getattr(exc, "response", None), "status_code", None),
+ ):
+ if isinstance(value, int) and not isinstance(value, bool) and 100 <= value < 600:
+ return value
+ return None
def _codes_and_text(exc: BaseException) -> tuple[set[str], str]:
"""The structured error codes and the lower-cased text, for matching only."""
codes: set[str] = set()
body = getattr(exc, "body", None)
+ if body is None:
+ body = getattr(exc, "details", None) # google-genai
error = body.get("error", body) if isinstance(body, dict) else None
for source in (exc, error if isinstance(error, dict) else None):
if source is None:
continue
- for field in ("code", "type"):
+ for field in ("code", "type", "status"):
value = source.get(field) if isinstance(source, dict) else getattr(source, field, None)
if isinstance(value, str) and value:
codes.add(value.lower())
@@ -135,6 +225,7 @@ _LABELS: Final[dict[str, str]] = {
"openrouter": "OpenRouter",
"nvidia": "NVIDIA",
"gemini": "Google Gemini",
+ "vertex": "Google Vertex AI",
"ollama": "Ollama",
"local-openai": "The local model server",
}
@@ -144,12 +235,18 @@ def _label(provider: str) -> str:
return _LABELS.get(provider, provider)
-def classify(provider: str, exc: BaseException) -> Refusal | None:
+def _class_names(exc: BaseException) -> set[str]:
+ return {cls.__name__ for err in _chain(exc) for cls in type(err).__mro__}
+
+
+def classify(provider: str, exc: BaseException, model: str = "") -> Refusal | None:
"""The actionable refusal behind ``exc``, or ``None`` for an ordinary error."""
if isinstance(exc, ProviderRefusal):
return exc.refusal
status = _status(exc)
codes, text = _codes_and_text(exc)
+ if status in (400, 402, 403, 429) and "extra usage" in text:
+ return _extra_usage_off("")
if status == 402 or (
status in (400, 403, 429)
and (codes & _BILLING_CODES or any(phrase in text for phrase in _BILLING_PHRASES))
@@ -161,88 +258,186 @@ def classify(provider: str, exc: BaseException) -> Refusal | None:
"will not help. Top it up with the provider, or choose another connected "
"model in the agent's settings.",
)
- if status is None and any(
- cls.__name__ in _UNREACHABLE_ERRORS for err in _chain(exc) for cls in type(err).__mro__
+ if (status in (400, 413, 422) or status is None) and (
+ codes & _OVERFLOW_CODES or any(phrase in text for phrase in _OVERFLOW_PHRASES)
):
return Refusal(
- 503,
- "provider_unreachable",
- f"{_label(provider)} is not reachable. If it is a model server on this "
- "computer, start it; otherwise check the connection, or choose another "
- "model in the agent's settings.",
+ 400,
+ "context_length_exceeded",
+ "Context length exceeded: the conversation is longer than "
+ f"{model or 'the model'}'s context window on {_label(provider)}. Compress "
+ "or shorten the conversation and send it again.",
+ )
+ if status in (400, 422) and any(phrase in text for phrase in _TOOLS_UNSUPPORTED_PHRASES):
+ return Refusal(
+ 400,
+ "tools_unsupported",
+ f"{model or 'This model'} on {_label(provider)} cannot call tools, which the "
+ "agent needs. Choose a model with tool support in the agent's settings.",
+ )
+ if status in (400, 422) and (
+ codes & _TOOL_SCHEMA_CODES or any(phrase in text for phrase in _TOOL_SCHEMA_PHRASES)
+ ):
+ return Refusal(
+ 400,
+ "invalid_tool_schema",
+ f"{_label(provider)} refused one of the agent's tool definitions, so the "
+ "request cannot succeed as it is. Turn off the newest tool or MCP server, or "
+ "choose another model.",
+ )
+ if status == 404 or (status in (400, None) and codes & _MODEL_MISSING_CODES):
+ return Refusal(
+ 404,
+ "model_not_found",
+ f"{_label(provider)} does not offer the model "
+ f"{model or 'selected for this agent'} (or its server address is wrong). "
+ "Choose another model in the agent's settings, or pull it first if it is a "
+ "local model.",
)
+ if status is None:
+ names = _class_names(exc)
+ if names & _CONNECT_ERRORS:
+ return _unreachable(provider)
+ if names & _TIMEOUT_ERRORS:
+ return Refusal(
+ 504,
+ "timeout",
+ f"{_label(provider)} took too long to answer {model or 'this request'}. "
+ "Try again; a long request on a slow or busy model can take minutes.",
+ )
+ if names & _UNREACHABLE_ERRORS:
+ return _unreachable(provider)
return None
+def _unreachable(provider: str) -> Refusal:
+ return Refusal(
+ 503,
+ "provider_unreachable",
+ f"{_label(provider)} is not reachable. If it is a model server on this "
+ "computer, start it; otherwise check the connection, or choose another "
+ "model in the agent's settings.",
+ )
+
+
+def gateway_refusal(provider: str, exc: BaseException, model: str = "") -> Refusal:
+ """Every provider failure as the status, code and message a runtime gets."""
+ found = classify(provider, exc, model)
+ if found is not None:
+ return found
+ status = _status(exc)
+ if status == 429:
+ return Refusal(429, "rate_limited", f"{provider} returned HTTP 429 (rate limit).")
+ if status in (401, 403):
+ return Refusal(
+ 401,
+ "provider_auth",
+ f"{_label(provider)} refused the saved key. Check it in Settings → API keys.",
+ )
+ if status in (503, 529):
+ return Refusal(
+ 503,
+ "provider_overloaded",
+ f"{_label(provider)} is overloaded right now (HTTP {status}). Try again shortly.",
+ )
+ if status is not None and 400 <= status < 500:
+ return Refusal(
+ 400,
+ "invalid_request",
+ f"{_label(provider)} rejected the request (HTTP {status}, {type(exc).__name__}).",
+ )
+ return Refusal(502, "provider_error", f"{provider} could not answer ({type(exc).__name__}).")
+
+
+def is_terminal(code: str) -> bool:
+ """Whether a failure with ``code`` ends the Jarvis turn at once."""
+ return code in TERMINAL_CODES
+
+
+def describe(exc: BaseException, limit: int = 400) -> str:
+ """A one-line, bounded, redacted account of ``exc`` for the log.
+
+ Provider error messages name the parameter, code and limit that failed;
+ they do not echo the conversation. Anything shaped like a key or bearer
+ token is masked, and the line is cut at ``limit`` characters.
+ """
+ status = _status(exc)
+ codes, _text = _codes_and_text(exc)
+ message = _SECRET_RE.sub("[redacted]", " ".join(str(exc).split()))
+ if len(message) > limit:
+ message = message[:limit] + "…"
+ parts = [type(exc).__name__]
+ if status is not None:
+ parts.append(f"status={status}")
+ if codes:
+ parts.append("codes=" + ",".join(sorted(codes)[:4]))
+ return f"{' '.join(parts)}: {message}"
+
+
# ------------------------------------------------------------ Claude login
-def _reset(raw: Any) -> datetime | None:
- if not isinstance(raw, str) or not raw:
- return None
- try:
- when = datetime.fromisoformat(raw.replace("Z", "+00:00"))
- except ValueError: # an unreadable reset time means no known reset
- return None
- return when if when.tzinfo else when.replace(tzinfo=UTC)
+def _login_expired() -> Refusal:
+ return Refusal(
+ 401,
+ "claude_login_expired",
+ "Anthropic refused the Claude Code login this agent runs on: it expired or was "
+ "signed out. Open Claude Code once to renew it, or connect an Anthropic API key "
+ "in Settings → API keys.",
+ )
+
+
+def login_expired() -> ProviderRefusal:
+ """The refusal for an agent routed to a Claude login that is not live."""
+ return ProviderRefusal(_login_expired())
+
+
+def _extra_usage_off(model: str) -> Refusal:
+ return Refusal(
+ 402,
+ "extra_usage_off",
+ f"Anthropic bills {model or 'Claude'} used by Hermes or OpenClaw on a Claude "
+ "subscription as Extra Usage, never from the plan's limits, and Extra Usage "
+ "is turned off for this Claude account, so retrying will not help. Turn it "
+ "on at claude.ai under Settings → Usage, connect an Anthropic API key, or "
+ "choose another provider in the agent's settings.",
+ )
+
+def _extra_usage_spent(model: str) -> Refusal:
+ return Refusal(
+ 402,
+ "extra_usage_spent",
+ "This Claude account's Extra Usage limit for the month is spent, and "
+ f"Anthropic bills {model or 'Claude'} used by Hermes or OpenClaw only as "
+ "Extra Usage. Raise the limit at claude.ai under Settings → Usage, connect "
+ "an Anthropic API key, or choose another provider in the agent's settings.",
+ )
-def login_refusal(usage: Any, model: str, *, now: datetime | None = None) -> Refusal | None:
- """Why Anthropic refused a Claude-login call, from the account's usage report.
- ``None`` when the report explains nothing (then it was an ordinary rate
- limit). Pure, so it is tested without the network.
+def login_refusal(usage: Any, model: str) -> Refusal | None:
+ """Why Anthropic refuses a Claude-login call from Hermes or OpenClaw.
+
+ Anthropic serves a subscription to third-party apps only from the
+ account's Extra Usage ("Third-party apps now draw from your extra usage,
+ not your plan limits", live 2026-10-07), so the plan's own windows say
+ nothing here. ``None`` when the report explains nothing. Pure.
"""
- if not isinstance(usage, dict):
- return None
- now = now or datetime.now(UTC)
- for field, name in _CLAUDE_WINDOWS:
- window = usage.get(field)
- if not isinstance(window, dict):
- continue
- utilization = window.get("utilization")
- if not isinstance(utilization, int | float) or utilization < 100:
- continue
- reset = _reset(window.get("resets_at"))
- wait = max(0.0, (reset - now).total_seconds()) if reset else None
- when = ""
- if reset is not None:
- local = reset.astimezone()
- when = f" It resets at {local:%H:%M} on {local:%d.%m.}"
- return Refusal(
- 429,
- "rate_limited",
- f"Your Claude plan's {name} limit is used up.{when}. Choose another "
- "connected model in the agent's settings to keep working now.",
- retry_after=wait,
- )
- extra = usage.get("extra_usage")
+ extra = usage.get("extra_usage") if isinstance(usage, dict) else None
if not isinstance(extra, dict):
return None
- shown = model or "This Claude model"
if extra.get("is_enabled") is False:
- return Refusal(
- 402,
- "extra_usage_off",
- f"Anthropic runs {shown} for Hermes and OpenClaw on your Claude "
- "subscription only as Extra Usage (paid on top of the plan), and Extra "
- "Usage is turned off for your Claude account, so retrying will not help. "
- "Turn it on at claude.ai under Settings → Usage, run this agent on a "
- "Claude Haiku model (covered by your plan), connect an Anthropic API key, "
- "or choose another provider in the agent's settings.",
- )
+ return _extra_usage_off(model)
if extra.get("spend_limit_reached") is True:
- return Refusal(
- 402,
- "extra_usage_spent",
- f"Your Claude Extra Usage limit for this month is spent, and Anthropic runs "
- f"{shown} for Hermes and OpenClaw only as Extra Usage. Raise the limit at "
- "claude.ai under Settings → Usage, or choose another provider in the "
- "agent's settings.",
- )
+ return _extra_usage_spent(model)
return None
+#: The last usage report per login, so routing does not ask on every turn.
+_REPORTS: dict[str, tuple[float, Any]] = {}
+_REPORT_TTL_S: Final = 120.0
+
+
def _claude_usage(token: str) -> Any:
"""The login's usage report, or ``None``. Blocking; never logs the token."""
try:
@@ -267,12 +462,41 @@ def _claude_usage(token: str) -> Any:
return None
+def login_blocked(token: str, model: str) -> Refusal | None:
+ """A refusal known before any model call: Extra Usage off or spent.
+
+ Blocking (one cached GET, no inference). Lets a turn fail at once with the
+ reason instead of starting a runtime that can only be refused.
+ """
+ import hashlib
+ import time
+
+ key = hashlib.sha256(token.encode()).hexdigest()
+ cached = _REPORTS.get(key)
+ if cached is not None and time.monotonic() - cached[0] < _REPORT_TTL_S:
+ usage = cached[1]
+ else:
+ usage = _claude_usage(token)
+ if usage is not None:
+ _REPORTS[key] = (time.monotonic(), usage)
+ return login_refusal(usage, model)
+
+
async def explain_login_refusal(exc: BaseException, token: str, model: str) -> BaseException:
"""``exc`` replaced by a :class:`ProviderRefusal` when the account explains it."""
- if _status(exc) != 429:
+ status = _status(exc)
+ if status == 401:
+ return login_expired()
+ if status not in (400, 402, 403, 429):
return exc
+ _codes, text = _codes_and_text(exc)
+ if status in (400, 402, 403) and "extra usage" not in text:
+ # A 403 on a login is the login itself; a 400 is an ordinary bad request.
+ return login_expired() if status == 403 else exc
usage = await asyncio.to_thread(_claude_usage, token)
refusal = login_refusal(usage, model)
+ if refusal is None and "extra usage" in text:
+ refusal = _extra_usage_off(model)
if refusal is None:
return exc
log.info("runtime gateway: Claude login refused %s (%s)", model, refusal.code)
diff --git a/jarvis/agent_runtimes/runtime-versions.json b/jarvis/agent_runtimes/runtime-versions.json
new file mode 100644
index 0000000000..312ae3d815
--- /dev/null
+++ b/jarvis/agent_runtimes/runtime-versions.json
@@ -0,0 +1,13 @@
+{
+ "_comment": "Runtime versions Jarvis installs and updates to. 'minimum' gates readiness; 'tested' is the release the agent-runtimes canary verified on Windows, macOS and Linux. Setup and daily updates go to 'tested' only, never to upstream latest. Bump 'tested' only from a green canary run (docs/agent-runtimes.md).",
+ "hermes": {
+ "minimum": "0.20.6",
+ "tested": "0.21.5",
+ "commit": "ed2dd0b35ced262f9c3f6f5d78cb4c831edc5245",
+ "config_version": 50
+ },
+ "openclaw": {
+ "minimum": "2026.9.8",
+ "tested": "2026.9.8"
+ }
+}
diff --git a/jarvis/agent_runtimes/versions.py b/jarvis/agent_runtimes/versions.py
new file mode 100644
index 0000000000..b55512d43a
--- /dev/null
+++ b/jarvis/agent_runtimes/versions.py
@@ -0,0 +1,102 @@
+"""The runtime versions Jarvis installs, updates to and accepts.
+
+``runtime-versions.json`` (next to this module) names, per runtime:
+
+* ``minimum`` — older installs are not ready and get updated;
+* ``tested`` — the release the agent-runtimes canary verified on all three
+ OSes. Setup and the daily update go to exactly this release, never to
+ upstream latest; a newer install still runs but is reported as untested;
+* ``commit`` (Hermes) — the source commit of ``tested`` for its installer;
+* ``config_version`` (Hermes) — the config schema ``tested`` writes, so Hermes
+ migrates Jarvis' config forward instead of calling it unmigratable.
+
+A last-good record per runtime (``<runtimes_root>/<runtime>-last-good.json``)
+remembers the release that last finished a setup ready, for rollback.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from functools import cache
+from pathlib import Path
+from typing import Any, Final
+
+from jarvis.agent_runtimes import base
+from jarvis.agent_runtimes.base import format_version, parse_version, write_json_if_changed
+
+log = logging.getLogger(__name__)
+
+_PINS_FILE: Final[Path] = Path(__file__).with_name("runtime-versions.json")
+
+#: Used only when the pins file is missing from a broken package: readiness
+#: still gates on these, and setup falls back to the projects' latest release.
+_FALLBACK_MINIMUM: Final[dict[str, str]] = {"hermes": "0.20.6", "openclaw": "2026.9.8"}
+
+
+@dataclass(frozen=True, slots=True)
+class Pin:
+ runtime: str
+ minimum: tuple[int, int, int]
+ #: ``None`` when the pins file could not be read.
+ tested: tuple[int, int, int] | None
+ commit: str = ""
+ config_version: int | None = None
+
+ @property
+ def tested_text(self) -> str:
+ return format_version(self.tested) if self.tested else ""
+
+
+def _version(raw: Any, field: str, runtime: str) -> tuple[int, int, int]:
+ parsed = parse_version(str(raw or ""))
+ if parsed is None:
+ raise ValueError(f"runtime-versions.json: {runtime}.{field} is not a version")
+ return parsed
+
+
+@cache
+def pin(runtime: str) -> Pin:
+ """The pinned versions of ``runtime``."""
+ try:
+ data = json.loads(_PINS_FILE.read_text(encoding="utf-8"))
+ row = data[runtime]
+ config_version = row.get("config_version")
+ return Pin(
+ runtime,
+ minimum=_version(row.get("minimum"), "minimum", runtime),
+ tested=_version(row.get("tested"), "tested", runtime),
+ commit=str(row.get("commit") or ""),
+ config_version=int(config_version) if config_version is not None else None,
+ )
+ except (OSError, ValueError, KeyError, TypeError) as exc:
+ log.warning("agent runtimes: pinned versions unavailable (%s); using minimums only", exc)
+ minimum = parse_version(_FALLBACK_MINIMUM.get(runtime, "0.0.0")) or (0, 0, 0)
+ return Pin(runtime, minimum=minimum, tested=None)
+
+
+def _last_good_path(runtime: str) -> Path:
+ return base.runtimes_root() / f"{runtime}-last-good.json"
+
+
+def last_good(runtime: str) -> dict[str, str] | None:
+ """The newest release that finished a setup ready (``version``, ``revision``).
+
+ ``revision`` is what the driver's installer reinstalls it from (a Hermes
+ commit, an OpenClaw release).
+ """
+ try:
+ data = json.loads(_last_good_path(runtime).read_text(encoding="utf-8"))
+ except (OSError, ValueError): # no record yet: nothing to roll back to
+ return None
+ return data if isinstance(data, dict) and data.get("version") else None
+
+
+def remember_good(runtime: str, version: str, revision: str = "") -> None:
+ """Record ``version`` as the runtime's last good release."""
+ if not version:
+ return
+ path = _last_good_path(runtime)
+ path.parent.mkdir(parents=True, exist_ok=True)
+ write_json_if_changed(path, {"version": version, "revision": revision})
diff --git a/jarvis/agentic_ide/file_editing.py b/jarvis/agentic_ide/file_editing.py
index ab4cf7f004..04fda88cce 100644
--- a/jarvis/agentic_ide/file_editing.py
+++ b/jarvis/agentic_ide/file_editing.py
@@ -26,6 +26,7 @@ from __future__ import annotations
import codecs
import hashlib
+import logging
import os
import shutil
import stat
@@ -41,6 +42,8 @@ from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS
from .folders import _SKIP_DIRS
+log = logging.getLogger(__name__)
+
__all__ = [
"MAX_EDITABLE_BYTES",
"EditConflict",
diff --git a/jarvis/agentic_ide/file_search.py b/jarvis/agentic_ide/file_search.py
index 1c7c0f586f..e4c9a84162 100644
--- a/jarvis/agentic_ide/file_search.py
+++ b/jarvis/agentic_ide/file_search.py
@@ -15,6 +15,7 @@ number of matches and the time spent are capped. A capped answer says so
from __future__ import annotations
import fnmatch
+import logging
import os
import re
import time
@@ -30,6 +31,8 @@ from .file_editing import (
write_text_file,
)
+log = logging.getLogger(__name__)
+
__all__ = [
"MAX_MATCHES",
"SearchOptions",
diff --git a/jarvis/brain/model_catalog.py b/jarvis/brain/model_catalog.py
index 41e394ef9f..045608d456 100644
--- a/jarvis/brain/model_catalog.py
+++ b/jarvis/brain/model_catalog.py
@@ -172,12 +172,11 @@ class ModelInfo:
# only source, and every new model generation shipped as "$0.00" until
# someone noticed (2026-07-28 and 2026-08-18 audits).
pricing: tuple[float, float] | None = None
- # Local-server facts from Ollama's ``/api/show`` (``model_info.<arch>.
- # context_length`` and ``details``). ``None`` for every gateway/cloud
- # catalog — they carry no such manifest — so nothing downstream changes for
- # them. Read by the Local models section and the per-model option sheet
- # (native context caps the ``num_ctx`` chips).
+ # Declared token limits from provider catalogs or Ollama's /api/show.
+ # Unknown limits remain None; runtime adapters use conservative defaults.
+ # Native context also caps the local model option sheet's num_ctx chips.
context_length: int | None = None
+ max_output_tokens: int | None = None
quantization_level: str | None = None
parameter_size: str | None = None
# Release time (Unix seconds) where the catalog publishes one — OpenRouter
@@ -920,7 +919,11 @@ def parse_models_response(provider: str, payload: dict) -> list[ModelInfo]:
if not gemini_entry_serves_generate_content(m):
continue
label = (m.get("displayName") or "").strip() or raw
- out.append(ModelInfo(id=raw, label=label, output_modalities=_output_modalities(m)))
+ out.append(ModelInfo(
+ id=raw, label=label, output_modalities=_output_modalities(m),
+ context_length=_positive_limit(m.get("inputTokenLimit")),
+ max_output_tokens=_positive_limit(m.get("outputTokenLimit")),
+ ))
return out
# OpenAI-compatible shape (OpenAI / Anthropic / Grok / OpenRouter).
@@ -938,11 +941,21 @@ def parse_models_response(provider: str, payload: dict) -> list[ModelInfo]:
supported_parameters=_supported_parameters(m),
pricing=_pricing(m),
created=_created(m),
+ context_length=_positive_limit(m.get("context_length") or m.get("context_window")),
+ max_output_tokens=_positive_limit(
+ m.get("max_output_tokens")
+ or (m["top_provider"].get("max_completion_tokens")
+ if isinstance(m.get("top_provider"), dict) else None)
+ ),
)
)
return out
+def _positive_limit(value: object) -> int | None:
+ return value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else None
+
+
def _created(entry: dict) -> float | None:
"""The entry's ``created`` Unix timestamp, or None when absent/non-numeric."""
raw = entry.get("created")
@@ -1744,6 +1757,8 @@ class ModelCatalog:
if isinstance(m.get("created"), int | float)
else None
),
+ context_length=_positive_limit(m.get("context_length")),
+ max_output_tokens=_positive_limit(m.get("max_output_tokens")),
)
for m in entry.get("models", [])
]
@@ -1778,6 +1793,10 @@ class ModelCatalog:
),
**({"pricing": list(m.pricing)} if m.pricing is not None else {}),
**({"created": m.created} if m.created is not None else {}),
+ **({"context_length": m.context_length}
+ if m.context_length is not None else {}),
+ **({"max_output_tokens": m.max_output_tokens}
+ if m.max_output_tokens is not None else {}),
}
for m in models
],
@@ -1803,6 +1822,14 @@ class ModelCatalog:
# -- public API ----------------------------------------------------
+ def cached_model(self, provider: str, model: str) -> ModelInfo | None:
+ """Read existing model metadata without network or inference work."""
+ entry = self._cache.get(provider)
+ if entry is None:
+ return None
+ aliases = {model, f"{model}:latest"} if provider == "ollama" else {model}
+ return next((item for item in entry[1] if item.id in aliases), None)
+
async def list_models(self, provider: str, *, force_refresh: bool = False) -> CatalogResult:
"""Return the catalog for ``provider`` with an honest ``source`` flag.
@@ -2065,7 +2092,13 @@ class ModelCatalog:
return replace(
info,
input_modalities=("text", "image") if "vision" in declared else ("text",),
- supported_parameters=("tools",) if "tools" in declared else (),
+ # Ollama names thinking models "thinking"; the gateway
+ # catalogs call the same fact "reasoning".
+ supported_parameters=tuple(
+ param
+ for param, capability in (("tools", "tools"), ("reasoning", "thinking"))
+ if capability in declared
+ ),
context_length=native_context_length(shown.get("model_info")),
quantization_level=str(details.get("quantization_level") or "") or None,
parameter_size=str(details.get("parameter_size") or "") or None,
diff --git a/jarvis/core/path_augment.py b/jarvis/core/path_augment.py
index c11285080a..b9017913d6 100644
--- a/jarvis/core/path_augment.py
+++ b/jarvis/core/path_augment.py
@@ -26,6 +26,7 @@ import logging
import os
import shutil
import sys
+from collections.abc import Callable
from pathlib import Path
log = logging.getLogger(__name__)
@@ -50,6 +51,8 @@ def _posix_candidates() -> list[str]:
str(home / ".npm-global" / "bin"),
# Volta pins a single stable shim dir.
str(home / ".volta" / "bin"),
+ # OpenClaw's user-space installer (install-cli.sh) and its default prefix.
+ str(home / ".openclaw" / "bin"),
]
if sys.platform.startswith("linux"):
dirs.append("/snap/bin")
@@ -90,6 +93,9 @@ def _windows_candidates() -> list[str]:
if local:
# User-scoped Node installers commonly use this UAC-free location.
dirs.append(os.path.join(local, "Programs", "nodejs"))
+ # The official Hermes Agent installer (install.ps1) stages its
+ # launchers here and registers the folder on the registry PATH only.
+ dirs.append(os.path.join(local, "hermes", "bin"))
# The official Antigravity PowerShell/CMD installer uses this directory.
dirs.append(os.path.join(local, "agy", "bin"))
# winget's shim dir lands on the *registry* PATH only — a running
@@ -179,6 +185,65 @@ def ensure_cli_paths() -> list[str]:
return added
+def _registry_paths() -> list[str]:
+ """The user's and the machine's persistent PATH (Windows registry)."""
+ import winreg
+
+ values: list[str] = []
+ for hive, key_path in (
+ (winreg.HKEY_CURRENT_USER, "Environment"),
+ (
+ winreg.HKEY_LOCAL_MACHINE,
+ r"SYSTEM\CurrentControlSet\Control\Session Manager\Environment",
+ ),
+ ):
+ try:
+ with winreg.OpenKey(hive, key_path, 0, winreg.KEY_QUERY_VALUE) as key:
+ value, _kind = winreg.QueryValueEx(key, "Path")
+ except OSError: # no such value or no access: that hive adds nothing
+ continue
+ values.append(str(value))
+ return values
+
+
+def refresh_from_persistent_path(
+ read: Callable[[], list[str]] | None = None,
+ *,
+ skip: Callable[[str], bool] | None = None,
+) -> list[str]:
+ """Append entries an installer just added to the persistent PATH.
+
+ An installer run by the app (Hermes, OpenClaw, Node.js) registers its
+ folder in the user's or the machine's PATH, which a running process never
+ sees. Windows only (POSIX installers edit shell profiles, which
+ ``ensure_cli_paths`` covers with the folders they use); ``read`` is
+ injectable for tests. Existing entries keep priority; ``skip`` drops
+ entries that must never be used. Returns the appended folders.
+ """
+ if read is None:
+ if sys.platform != "win32":
+ return []
+ read = _registry_paths
+ current = os.environ.get("PATH", "")
+ seen = {os.path.normcase(os.path.normpath(p)) for p in current.split(os.pathsep) if p}
+ added: list[str] = []
+ for value in read():
+ for raw in value.split(";"):
+ entry = os.path.expandvars(raw.strip().strip('"'))
+ if not entry or (skip is not None and skip(entry)):
+ continue
+ key = os.path.normcase(os.path.normpath(entry))
+ if key in seen or not os.path.isdir(entry):
+ continue
+ seen.add(key)
+ added.append(entry)
+ if added:
+ joined = os.pathsep.join(added)
+ os.environ["PATH"] = f"{current}{os.pathsep}{joined}" if current else joined
+ log.info("PATH refreshed with %d folder(s) from the persistent PATH", len(added))
+ return added
+
+
def resolve_node_executable() -> str | None:
"""Return an absolute Node.js executable, including stale-GUI-PATH hosts."""
ensure_cli_paths()
@@ -196,4 +261,9 @@ def resolve_node_executable() -> str | None:
return None
-__all__ = ["candidate_dirs", "ensure_cli_paths", "resolve_node_executable"]
+__all__ = [
+ "candidate_dirs",
+ "ensure_cli_paths",
+ "refresh_from_persistent_path",
+ "resolve_node_executable",
+]
diff --git a/jarvis/core/process_tree.py b/jarvis/core/process_tree.py
index a1f924526e..0169a09f36 100644
--- a/jarvis/core/process_tree.py
+++ b/jarvis/core/process_tree.py
@@ -48,7 +48,7 @@ import signal
import sys
import threading
from ctypes import wintypes
-from typing import Protocol
+from typing import Any, Protocol
from loguru import logger
@@ -322,4 +322,129 @@ def make_process_tree(name: str) -> ProcessTree:
return _NoContainment(name)
-__all__ = ["GRACE_S", "ProcessTree", "make_process_tree"]
+#: Environment variable a tracked process and all its descendants inherit; a
+#: descendant that detached before any snapshot saw it is still found by it.
+TURN_MARKER_ENV = "JARVIS_TURN_MARK"
+
+
+class DescendantTracker:
+ """Remember every descendant of a process while it runs; kill survivors at close.
+
+ A process group is not a tree: a child that calls ``setsid`` (Hermes runs
+ every shell command that way, and so do many dev servers) leaves its
+ parent's group, and ``killpg`` never reaches it. Once its parent exits it
+ is reparented and nothing can find it any more. So the tree is walked
+ while the parent still lives (every :data:`interval_s`, and once more at
+ close), and :meth:`close` kills whatever it saw that still runs. A pid is
+ only ever killed when its creation time matches what was recorded, so a
+ recycled pid is never touched.
+
+ Windows needs none of this — a Job Object follows descendants by itself —
+ so there :meth:`start` and :meth:`close` do nothing.
+ """
+
+ def __init__(
+ self,
+ pid: int,
+ *,
+ interval_s: float = 1.0,
+ enabled: bool | None = None,
+ marker: str | None = None,
+ ) -> None:
+ self.pid = pid
+ #: Value of :data:`TURN_MARKER_ENV` in the tracked process' environment.
+ self.marker = marker
+ self.interval_s = interval_s
+ self.seen: dict[int, float] = {}
+ self._task: Any = None
+ self._enabled = sys.platform != "win32" if enabled is None else enabled
+
+ def snapshot(self) -> None:
+ if not self._enabled:
+ return
+ try:
+ import psutil
+
+ root = psutil.Process(self.pid)
+ for child in root.children(recursive=True):
+ try:
+ self.seen.setdefault(child.pid, child.create_time())
+ except (psutil.NoSuchProcess, psutil.AccessDenied):
+ continue # exited meanwhile or not ours to inspect: nothing to reap
+ except Exception as exc: # noqa: BLE001 - the parent is gone or psutil is unusable
+ logger.debug("descendant snapshot of {} skipped: {}", self.pid, exc)
+
+ def start(self) -> None:
+ """Begin watching (call from a running event loop)."""
+ if not self._enabled:
+ return
+ import asyncio
+
+ async def _watch() -> None:
+ while True:
+ self.snapshot()
+ await asyncio.sleep(self.interval_s)
+
+ self._task = asyncio.get_running_loop().create_task(_watch())
+
+ def close(self) -> list[int]:
+ """Stop watching and kill every recorded descendant still alive."""
+ if self._task is not None:
+ self._task.cancel()
+ self._task = None
+ if not self._enabled:
+ return []
+ self.snapshot()
+ killed: list[int] = []
+ try:
+ import psutil
+ except ImportError: # pragma: no cover - psutil is a base dependency
+ return killed
+ for pid, created in self.seen.items():
+ try:
+ proc = psutil.Process(pid)
+ if abs(proc.create_time() - created) > 1.0:
+ continue # the pid was recycled: never ours
+ proc.kill()
+ killed.append(pid)
+ except (psutil.NoSuchProcess, psutil.AccessDenied):
+ continue # already gone, or not ours to kill: the good outcome
+ killed.extend(self._reap_marked(set(killed)))
+ if killed:
+ logger.info("Reaped {} detached descendant(s) of pid {}", len(killed), self.pid)
+ return killed
+
+ def _reap_marked(self, done: set[int]) -> list[int]:
+ """Kill processes that still carry this turn's marker in their environment.
+
+ A child that called ``setsid`` between two snapshots and whose parent
+ then exited is an orphan no tree walk can reach (CI 2026-10-08); it
+ still inherited the marker. Processes another user owns are skipped.
+ """
+ if not self.marker:
+ return []
+ import os
+
+ import psutil
+
+ killed: list[int] = []
+ for proc in psutil.process_iter():
+ if proc.pid in done or proc.pid == os.getpid():
+ continue
+ try:
+ if proc.environ().get(TURN_MARKER_ENV) != self.marker:
+ continue
+ proc.kill()
+ killed.append(proc.pid)
+ except (psutil.Error, OSError):
+ continue # gone, a zombie, or not ours to read: nothing to reap
+ return killed
+
+
+__all__ = [
+ "GRACE_S",
+ "TURN_MARKER_ENV",
+ "DescendantTracker",
+ "ProcessTree",
+ "make_process_tree",
+]
diff --git a/jarvis/costs/ledger.py b/jarvis/costs/ledger.py
index 74930a0f52..2fa00ff39a 100644
--- a/jarvis/costs/ledger.py
+++ b/jarvis/costs/ledger.py
@@ -303,10 +303,32 @@ def read_usage(path: Path, since_ms: int, until_ms: int) -> Iterator[UsageRow]:
conn.close()
+def first_call_ms(path: Path, caller: str) -> int | None:
+ """When ``caller`` first wrote a row, or ``None`` (no file, no rows)."""
+ if not path.exists():
+ return None
+ try:
+ conn = sqlite3.connect(f"file:{path.as_posix()}?mode=ro", uri=True, timeout=5.0)
+ except sqlite3.Error as exc:
+ log.warning("usage ledger: %s not readable (%s)", path, exc)
+ return None
+ try:
+ row = conn.execute(
+ "SELECT MIN(ts_ms) FROM llm_usage WHERE caller = ?", (caller,)
+ ).fetchone()
+ except sqlite3.Error as exc:
+ log.warning("usage ledger: read failed (%s)", exc)
+ return None
+ finally:
+ conn.close()
+ return int(row[0]) if row and row[0] is not None else None
+
+
__all__ = [
"DB_NAME",
"UsageRow",
"current_caller",
+ "first_call_ms",
"flush",
"ledger_path",
"read_usage",
diff --git a/jarvis/costs/model.py b/jarvis/costs/model.py
index 333e10a576..22013da2e9 100644
--- a/jarvis/costs/model.py
+++ b/jarvis/costs/model.py
@@ -88,6 +88,14 @@ SURFACES: tuple[str, ...] = (
SURFACE_BACKGROUND,
)
+# The ledger caller of every model call a Hermes / OpenClaw agent makes
+# through Jarvis' model gateway, and the chat runners those agents run on.
+# Once the gateway metered its calls, its ledger rows are the bill for those
+# turns: a runtime's own usage report may be missing or approximate, and
+# counting both would bill each call twice.
+RUNTIME_CALLER = "agent-runtime"
+RUNTIME_RUNNERS: frozenset[str] = frozenset({"hermes-cli", "openclaw-cli"})
+
# Runners whose usage object follows the OpenAI convention: ``input_tokens``
# INCLUDES the cached share, so the cached count is subtracted before pricing.
# Anthropic-style runners report the two disjoint and need nothing.
diff --git a/jarvis/costs/sources.py b/jarvis/costs/sources.py
index 13fa5520a5..0b63991997 100644
--- a/jarvis/costs/sources.py
+++ b/jarvis/costs/sources.py
@@ -19,7 +19,7 @@ from pathlib import Path
from typing import Any
from .ledger import DB_NAME as LEDGER_DB_NAME
-from .ledger import read_usage
+from .ledger import first_call_ms, read_usage
from .model import (
MISSION_SUBSCRIPTION_CLIS,
OPENAI_CONVENTION_RUNNERS,
@@ -31,6 +31,8 @@ from .model import (
ROLE_TOOL,
ROLE_TTS,
ROLE_WORKER,
+ RUNTIME_CALLER,
+ RUNTIME_RUNNERS,
SUBSCRIPTION_RUNNERS,
SURFACE_AGENT_CHAT,
SURFACE_AGENTIC_IDE,
@@ -328,8 +330,14 @@ _AGENT_CACHED_KEYS = (
)
-def _agent_chat_entries(path: Path | None, since_ms: int, until_ms: int) -> Iterator[CostEntry]:
- """One entry per finished agent-chat turn (Claude Code, Codex, …)."""
+def _agent_chat_entries(
+ path: Path | None, since_ms: int, until_ms: int, runtime_metered_from: int | None = None
+) -> Iterator[CostEntry]:
+ """One entry per finished agent-chat turn (Claude Code, Codex, …).
+
+ A Hermes / OpenClaw turn from ``runtime_metered_from`` on is skipped: the
+ model gateway wrote each of its calls to the ledger, which bills it.
+ """
conn = _connect(path)
if conn is None:
return
@@ -394,6 +402,12 @@ def _agent_chat_entries(path: Path | None, since_ms: int, until_ms: int) -> Iter
continue
session = sessions.get(str(row["session_id"] or ""))
start = starts.get(str(payload.get("turn_id") or ""), {})
+ if (
+ runtime_metered_from is not None
+ and start.get("runner", "") in RUNTIME_RUNNERS
+ and _int(row["ts_ms"]) >= runtime_metered_from
+ ):
+ continue
if start.get("runner", "") in OPENAI_CONVENTION_RUNNERS:
# Same asymmetry the CLI index documents: the OpenAI usage
# object counts cache hits INSIDE input_tokens. Summing both
@@ -716,10 +730,12 @@ def _ledger_entries(path: Path | None, since_ms: int, until_ms: int) -> Iterator
recorded_usd=row.cost_usd,
tokens_cached=row.tokens_cached,
)
+ # A Hermes / OpenClaw agent's model call is agent work, not background.
+ runtime = row.caller == RUNTIME_CALLER
yield CostEntry(
ts_ms=row.ts_ms,
- surface=SURFACE_BACKGROUND,
- role=ROLE_BACKGROUND,
+ surface=SURFACE_AGENT_CHAT if runtime else SURFACE_BACKGROUND,
+ role=ROLE_AGENT if runtime else ROLE_BACKGROUND,
provider=row.provider or "unknown",
model=row.model,
tokens_in=row.tokens_in,
@@ -728,7 +744,10 @@ def _ledger_entries(path: Path | None, since_ms: int, until_ms: int) -> Iterator
cost_usd=cost,
price_source=source,
ref_id="",
- label=_clip(row.label or row.caller or "background"),
+ label=_clip(
+ row.label or ("Hermes / OpenClaw agent" if runtime else row.caller)
+ or "background"
+ ),
)
@@ -742,7 +761,12 @@ def collect_entries(
"""Every priced line item across all sources, newest last."""
entries: list[CostEntry] = []
entries.extend(_voice_entries(sources.sessions_db, since_ms, until_ms))
- entries.extend(_agent_chat_entries(sources.agent_chat_db, since_ms, until_ms))
+ runtime_metered_from = (
+ first_call_ms(sources.ledger_db, RUNTIME_CALLER) if sources.ledger_db else None
+ )
+ entries.extend(
+ _agent_chat_entries(sources.agent_chat_db, since_ms, until_ms, runtime_metered_from)
+ )
entries.extend(_mission_entries(sources.missions_db, since_ms, until_ms))
entries.extend(_speech_entries(sources.sessions_db, since_ms, until_ms))
entries.extend(
diff --git a/jarvis/live/subscription_reasoning.py b/jarvis/live/subscription_reasoning.py
index 5259625349..1b79ba2107 100644
--- a/jarvis/live/subscription_reasoning.py
+++ b/jarvis/live/subscription_reasoning.py
@@ -8,6 +8,7 @@ There is no CLI turn, autonomous harness, hosted tool, or API-key fallback here.
from __future__ import annotations
import json
+import logging
import re
from collections.abc import AsyncIterator, Awaitable, Callable
from typing import Any
@@ -20,6 +21,15 @@ from jarvis.live.subscription_auth import SubscriptionCredentials
_BASE_URL = "https://chatgpt.com/backend-api/codex"
_MAX_EVENT_CHARS = 2 * 1024 * 1024
_MAX_CATALOG_BYTES = 4 * 1024 * 1024
+_MAX_ERROR_BYTES = 64 * 1024
+_REQUEST_FAILURES = {
+ "invalid_function_parameters": "ChatGPT rejected a tool schema in this request.",
+ "invalid_tool_schema": "ChatGPT rejected a tool schema in this request.",
+ "context_length_exceeded": "This request exceeds the selected ChatGPT model's context limit.",
+ "model_not_found": "The selected model is unavailable on this ChatGPT subscription.",
+ "invalid_request_error": "ChatGPT rejected this request.",
+}
+log = logging.getLogger(__name__)
_SAFE_CODE = re.compile(r"^[a-zA-Z0-9_.-]{1,96}$")
_SAFE_EFFORT = re.compile(r"^[a-z][a-z0-9_-]{0,31}$")
_KNOWN_EFFORTS = frozenset({"none", "minimal", "low", "medium", "high", "xhigh", "max"})
@@ -31,14 +41,25 @@ _LIGHTEST_FIRST = ("none", "minimal", "low", "medium", "high", "xhigh", "max")
class SubscriptionReasoningError(RuntimeError):
def __init__(
- self, message: str, *, code: str = "subscription_unavailable", status: int = 0
+ self,
+ message: str,
+ *,
+ code: str = "subscription_unavailable",
+ status: int = 0,
+ retry_after: str | None = None,
) -> None:
super().__init__(message)
self.code = code
self.status = status
+ self.retry_after = retry_after
-def _failure(status: int = 0, payload: Any = None) -> SubscriptionReasoningError:
+def _failure(
+ status: int = 0,
+ payload: Any = None,
+ *,
+ retry_after: str | None = None,
+) -> SubscriptionReasoningError:
error = payload.get("error", {}) if isinstance(payload, dict) else {}
if not isinstance(error, dict):
error = {}
@@ -50,6 +71,7 @@ def _failure(status: int = 0, payload: Any = None) -> SubscriptionReasoningError
"rate_limit_exceeded",
"subscription_sharing_usage_limit_exceeded",
}:
+ status = 429
message = (
"The selected ChatGPT subscription reached a usage limit. "
"Try again after its allowance resets."
@@ -59,12 +81,57 @@ def _failure(status: int = 0, payload: Any = None) -> SubscriptionReasoningError
"ChatGPT subscription access was rejected. "
"Check the selected account and sign in again if needed."
)
+ elif status in (400, 404, 413, 422):
+ if code not in _REQUEST_FAILURES:
+ code = "invalid_request_error"
+ message = (
+ f"{_REQUEST_FAILURES[code]} (HTTP {status}). "
+ "Check the model, conversation and tool settings before trying again."
+ )
else:
message = (
"ChatGPT subscription reasoning failed. "
"Try again later; no API billing fallback was used."
)
- return SubscriptionReasoningError(message, code=code, status=status)
+ return SubscriptionReasoningError(message, code=code, status=status, retry_after=retry_after)
+
+
+def _invalid_request(message: str) -> SubscriptionReasoningError:
+ """A request this client refuses before sending it: never worth a retry."""
+ return SubscriptionReasoningError(message, code="invalid_request_error", status=400)
+
+
+async def _http_failure(response: Any) -> SubscriptionReasoningError:
+ """Read bounded error metadata, never expose provider text or request content."""
+ import httpx
+
+ raw = bytearray()
+ try:
+ async for chunk in response.aiter_bytes():
+ if len(raw) + len(chunk) > _MAX_ERROR_BYTES:
+ raw.clear()
+ break
+ raw.extend(chunk)
+ except httpx.HTTPError:
+ # Headers already established rejection; a broken error body must not
+ # turn a permanent 400 into a retryable network failure.
+ raw.clear()
+ payload: Any = None
+ if raw:
+ try:
+ payload = json.loads(raw)
+ except ValueError:
+ pass # HTML, malformed JSON and oversized bodies use the HTTP status alone.
+ failure = _failure(response.status_code, payload)
+ # Preserve throttling instructions for gateway backoff without copying any
+ # other headers. Existing consumers may read this optional exception field.
+ failure.retry_after = response.headers.get("retry-after")
+ log.info(
+ "ChatGPT subscription request rejected: status=%s category=%s",
+ failure.status,
+ failure.code if failure.code in _REQUEST_FAILURES else "subscription_unavailable",
+ )
+ return failure
class SubscriptionReasoning:
@@ -110,7 +177,7 @@ class SubscriptionReasoning:
if response.status_code == 401 and attempt == 0:
continue
if response.status_code != 200:
- raise _failure(response.status_code)
+ raise await _http_failure(response)
if len(response.content) > _MAX_CATALOG_BYTES:
raise SubscriptionReasoningError("The ChatGPT model catalog is too large.")
try:
@@ -132,6 +199,13 @@ class SubscriptionReasoning:
"id": slug,
"label": str(row.get("display_name") or slug),
}
+ for source, target in (
+ ("context_window", "context_length"),
+ ("max_output_tokens", "max_output_tokens"),
+ ):
+ value = row.get(source)
+ if isinstance(value, int) and not isinstance(value, bool) and value > 0:
+ model[target] = value
levels = row.get("supported_reasoning_levels")
if isinstance(levels, list):
efforts: list[str] = []
@@ -169,15 +243,13 @@ class SubscriptionReasoning:
import httpx
if not model.strip():
- raise SubscriptionReasoningError(
+ raise _invalid_request(
"Select a ChatGPT subscription thinking model before starting voice."
)
if any(tool.get("type") != "function" for tool in tools):
- raise SubscriptionReasoningError(
- "Subscription reasoning accepts only Jarvis function tools."
- )
+ raise _invalid_request("Subscription reasoning accepts only Jarvis function tools.")
if reasoning_effort and not _SAFE_EFFORT.fullmatch(reasoning_effort):
- raise SubscriptionReasoningError("The subscription thinking effort is invalid.")
+ raise _invalid_request("The subscription thinking effort is invalid.")
if reasoning_effort in {"none", "minimal"}:
reasoning_effort = await self._lightest_effort(model, reasoning_effort)
if reasoning_effort and reasoning_effort not in _KNOWN_EFFORTS:
@@ -186,12 +258,12 @@ class SubscriptionReasoning:
if model not in self._model_efforts:
await self.list_models()
if reasoning_effort not in self._model_efforts.get(model, ()):
- raise SubscriptionReasoningError(
+ raise _invalid_request(
"The selected ChatGPT model does not advertise this thinking effort."
)
supported = self._model_efforts.get(model)
if reasoning_effort and supported is not None and reasoning_effort not in supported:
- raise SubscriptionReasoningError(
+ raise _invalid_request(
"The selected ChatGPT model does not support this thinking effort."
)
reasoning = {"summary": "auto"}
@@ -221,7 +293,7 @@ class SubscriptionReasoning:
if response.status_code == 401 and attempt == 0:
continue
if response.status_code != 200:
- raise _failure(response.status_code)
+ raise await _http_failure(response)
async for event in self._events(response):
yield event
return
@@ -230,6 +302,36 @@ class SubscriptionReasoning:
raise _failure() from exc
raise _failure(401)
+ async def snap_effort(self, model: str, requested: str) -> str:
+ """The level ``model`` offers closest to ``requested`` ("" = its default).
+
+ A runtime asks for the level its own settings name; a ChatGPT model
+ offers only some (no ``max`` on one, no ``none`` on another). A level
+ the model lacks becomes the highest one it offers below it, else its
+ lightest, so the request is never refused for the level alone. Unknown
+ capabilities (the catalog is unreachable) keep a known level as is and
+ drop an unknown one to the model's default. One catalog request at
+ most, no inference.
+ """
+ if not requested:
+ return ""
+ if model not in self._model_efforts:
+ try:
+ await self.list_models()
+ except SubscriptionReasoningError: # no catalog: the backend validates the level
+ return requested if requested in _KNOWN_EFFORTS else ""
+ supported = self._model_efforts.get(model, ())
+ if not supported:
+ return requested if requested in _KNOWN_EFFORTS else ""
+ if requested in supported:
+ return requested
+ if requested in _LIGHTEST_FIRST:
+ ceiling = _LIGHTEST_FIRST.index(requested)
+ lower = [e for e in _LIGHTEST_FIRST[: ceiling + 1] if e in supported]
+ if lower:
+ return lower[-1]
+ return next((e for e in _LIGHTEST_FIRST if e in supported), "")
+
async def _lightest_effort(self, model: str, requested: str) -> str:
"""``requested`` when the model offers it, else its lightest level ("" = default)."""
if model not in self._model_efforts:
diff --git a/jarvis/plugins/brain/_agent_profile.py b/jarvis/plugins/brain/_agent_profile.py
new file mode 100644
index 0000000000..3422983154
--- /dev/null
+++ b/jarvis/plugins/brain/_agent_profile.py
@@ -0,0 +1,56 @@
+"""How an agent's model call differs from a voice turn, for the brain plugins.
+
+The plugins were tuned for the voice path: a 30 s read timeout so a hung
+provider fails over fast, a temperature on every request, no prompt caching
+unless a global switch is on. A Hermes / OpenClaw agent calling through
+Jarvis' model gateway needs the opposite: a reasoning model may think for
+minutes before its first token and a local server may prefill for longer,
+the runtime decides sampling itself, and a tool loop resends the same long
+prefix every round.
+
+The gateway sets :data:`PROFILE` in the task that runs the plugin; every
+other caller leaves it unset, so the voice path sends exactly what it did.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class AgentRequestProfile:
+ """One agent call's needs (``None`` fields keep the plugin's default)."""
+
+ #: Seconds a stream may stay silent before the call fails.
+ read_timeout_s: float | None = None
+ #: Mark the request's stable prefix for the provider's prompt cache.
+ prompt_cache: bool = False
+ #: The caller chose no temperature: send none, the model's default applies.
+ omit_temperature: bool = False
+
+
+PROFILE: ContextVar[AgentRequestProfile | None] = ContextVar(
+ "jarvis_agent_request_profile", default=None
+)
+
+
+def current() -> AgentRequestProfile | None:
+ return PROFILE.get()
+
+
+def http_timeout(*, connect: float = 5.0) -> Any:
+ """An ``httpx.Timeout`` for the active profile, or ``None`` without one."""
+ profile = PROFILE.get()
+ if profile is None or profile.read_timeout_s is None:
+ return None
+ import httpx
+
+ return httpx.Timeout(connect=connect, read=profile.read_timeout_s, write=60.0, pool=30.0)
+
+
+def sends_temperature() -> bool:
+ """Whether the request should carry a temperature."""
+ profile = PROFILE.get()
+ return not (profile is not None and profile.omit_temperature)
diff --git a/jarvis/plugins/brain/_anthropic_base.py b/jarvis/plugins/brain/_anthropic_base.py
index d60a9c85af..998640ead6 100644
--- a/jarvis/plugins/brain/_anthropic_base.py
+++ b/jarvis/plugins/brain/_anthropic_base.py
@@ -13,6 +13,8 @@ from typing import Any, Final
from jarvis.core.protocols import BrainDelta, BrainMessage, BrainRequest
+from . import _agent_profile
+
# Reuse the tested tool-name sanitizer/map (regex [^A-Za-z0-9_-] + dedup). Its
# 64-char cap is stricter than Anthropic's 128 but still valid, so a slash/dot/
# colon MCP name (jarvis/mcp/adapter.py) no longer trips Anthropic's
@@ -102,6 +104,37 @@ def _to_anthropic_messages(messages: tuple[BrainMessage, ...]) -> list[dict[str,
return out
+#: A prompt-cache breakpoint with the default five-minute lifetime: a tool
+#: loop's next round arrives well within it, and it costs no beta header.
+_EPHEMERAL: Final[dict[str, str]] = {"type": "ephemeral"}
+
+
+def _cache_last_message(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """``messages`` with a cache breakpoint on the last content block.
+
+ Anthropic reads the cache up to the longest marked prefix it has seen, so
+ one rolling breakpoint at the end lets every tool round reuse the whole
+ conversation before it instead of paying the full input rate again.
+ """
+ if not messages:
+ return messages
+ last = dict(messages[-1])
+ content = last.get("content")
+ if isinstance(content, str):
+ if not content:
+ return messages
+ blocks: list[dict[str, Any]] = [{"type": "text", "text": content}]
+ elif isinstance(content, list) and content and isinstance(content[-1], dict):
+ blocks = [dict(block) if isinstance(block, dict) else block for block in content]
+ else:
+ return messages
+ if blocks[-1].get("type") == "text" and not blocks[-1].get("text"):
+ return messages # an empty text block may not carry a breakpoint
+ blocks[-1] = {**blocks[-1], "cache_control": dict(_EPHEMERAL)}
+ last["content"] = blocks
+ return [*messages[:-1], last]
+
+
def _extract_system(messages: tuple[BrainMessage, ...], extra_system: str | None) -> str | None:
"""Collects all role=system messages + the extra extra_system."""
parts: list[str] = []
@@ -247,6 +280,8 @@ async def stream_complete(
# tool schema as the cache boundary (Anthropic caches everything up
# to and including the marked block).
prompt_cache_enabled = os.environ.get(_ENV_PROMPT_CACHE) == "1"
+ profile = _agent_profile.current()
+ agent_cache = profile is not None and profile.prompt_cache
extra_headers: dict[str, str] = {}
system_payload: Any = system
if prompt_cache_enabled and system:
@@ -266,6 +301,16 @@ async def stream_complete(
cached_tools[-1]["cache_control"] = {"type": "ephemeral", "ttl": "1h"}
tools_payload = cached_tools
extra_headers.setdefault("anthropic-beta", _ANTHROPIC_CACHE_TTL_BETA)
+ if agent_cache:
+ # An agent's tool loop resends system, tools and the whole history on
+ # every round: mark all three (at most four breakpoints in total).
+ if system and not prompt_cache_enabled:
+ system_payload = [{"type": "text", "text": system, "cache_control": dict(_EPHEMERAL)}]
+ if tools_payload and not prompt_cache_enabled:
+ cached_tools = [dict(t) for t in tools_payload]
+ cached_tools[-1]["cache_control"] = dict(_EPHEMERAL)
+ tools_payload = cached_tools
+ messages = _cache_last_message(messages)
kwargs: dict[str, Any] = {
"model": model,
@@ -275,8 +320,12 @@ async def stream_complete(
# `temperature` is deprecated on reasoning models (opus-4.x, sonnet-4.x).
# Only send it for explicitly classic models; on the new defaults,
# temperature=1 is hardcoded on the backend anyway.
- if not _is_reasoning_model(model):
+ if not _is_reasoning_model(model) and _agent_profile.sends_temperature():
kwargs["temperature"] = req.temperature
+ # An agent call may think for minutes; the voice path's short client
+ # timeout is replaced only while an agent request profile is active.
+ if (timeout := _agent_profile.http_timeout()) is not None:
+ kwargs["timeout"] = timeout
# A requested reasoning effort (the agent chat's picker) becomes
# ``output_config.effort`` plus adaptive thinking on the models that
# take it; the voice brain never sets one and sends exactly what it did.
diff --git a/jarvis/plugins/brain/_openai_base.py b/jarvis/plugins/brain/_openai_base.py
index 6ba19db866..ab3472e9ba 100644
--- a/jarvis/plugins/brain/_openai_base.py
+++ b/jarvis/plugins/brain/_openai_base.py
@@ -18,6 +18,8 @@ import httpx
from jarvis.core.protocols import BrainDelta, BrainMessage, BrainRequest
+from . import _agent_profile
+
log = logging.getLogger(__name__)
#: Shared HTTP timeout for every openai-SDK-based brain (openai / grok /
@@ -429,6 +431,8 @@ def _responses_kwargs_from_chat(chat_kwargs: dict[str, Any]) -> dict[str, Any]:
)
if max_out:
out["max_output_tokens"] = max(int(max_out), _RESPONSES_MIN_OUTPUT_TOKENS)
+ if chat_kwargs.get("timeout") is not None:
+ out["timeout"] = chat_kwargs["timeout"]
if chat_kwargs.get("tools"):
out["tools"] = _tools_responses_format(list(chat_kwargs["tools"]))
return out
@@ -521,9 +525,14 @@ async def stream_complete(
extra_body: dict[str, Any] | None = None,
supports_vision: bool = True,
assistant_tool_call_extra_content: dict[str, Any] | None = None,
+ send_temperature: bool | None = None,
) -> AsyncIterator[BrainDelta]:
"""Streaming run against OpenAI-compatible Chat-Completions.
+ ``send_temperature`` ``None`` follows the agent request profile (an agent
+ that chose no temperature sends none); ``True`` always sends it — a
+ provider's own per-model temperature setting.
+
`supports_vision` is passed through to the message builder — when `False`,
`BrainMessage.images` are dropped and a WARN is logged.
@@ -547,9 +556,15 @@ async def stream_complete(
"model": model,
"messages": messages,
"max_tokens": req.max_tokens,
- "temperature": req.temperature,
"stream": True,
}
+ if send_temperature or (send_temperature is None and _agent_profile.sends_temperature()):
+ kwargs["temperature"] = req.temperature
+ # An agent call may legitimately stay silent for minutes (a reasoning
+ # model thinking, a local server prefilling); the client's voice-tuned
+ # read timeout would cut it off. Unset for every other caller.
+ if (timeout := _agent_profile.http_timeout()) is not None:
+ kwargs["timeout"] = timeout
# stream_options only exists since openai>=1.30. On old SDKs (e.g. 1.10)
# the unconditional call would raise a TypeError and crash the plugin
# chain with "AsyncCompletions.create() got an unexpected keyword argument"
diff --git a/jarvis/plugins/brain/gemini.py b/jarvis/plugins/brain/gemini.py
index 19cd4bf639..3c467a23e9 100644
--- a/jarvis/plugins/brain/gemini.py
+++ b/jarvis/plugins/brain/gemini.py
@@ -28,6 +28,7 @@ from uuid import uuid4
from jarvis.core import config as cfg
from jarvis.core.protocols import BrainDelta, BrainMessage, BrainRequest
+from . import _agent_profile
from ._openai_base import CLIENT_TIMEOUT, stream_complete
log = logging.getLogger(__name__)
@@ -47,8 +48,9 @@ _TRANSPORT_OPENAI_COMPAT = "openai-compatible"
# assistant function-call step. Jarvis deliberately normalizes provider output
# into BrainDelta/BrainMessage instead of retaining the raw response object, so
# Google's documented validator sentinel is the honest compatibility value.
+_SKIP_SIGNATURE = "skip_thought_signature_validator"
_TOOL_HISTORY_EXTRA_CONTENT = {
- "google": {"thought_signature": "skip_thought_signature_validator"},
+ "google": {"thought_signature": _SKIP_SIGNATURE},
}
# Latency-Sprint-2: ENV switch for the context cache. BrainManager sets this
@@ -244,8 +246,22 @@ def _to_gemini_contents(
the ``extract_leaked_tool_calls`` recovery has to repair — observed on
every delegated research turn). ``tool_name_map`` (original → wire name)
keeps history names consistent with the sanitized declarations.
+
+ A call without its own thought signature (the 2nd..nth call of a
+ parallel step, which Gemini never signs, or any call after the signature
+ was lost) still replays as a ``functionCall``; the step's first call then
+ carries Google's documented validator sentinel. The results of one
+ parallel step go back in ONE content, one ``functionResponse`` per call,
+ and a result without a tool name takes the name of its call.
"""
name_map = tool_name_map or {}
+ call_names = {
+ str(part.get("id")): str(part.get("name") or "")
+ for m in messages
+ if m.role == "assistant" and isinstance(m.content, list)
+ for part in m.content
+ if isinstance(part, dict) and part.get("type") == "tool_use" and part.get("id")
+ }
contents: list[dict[str, Any]] = []
for m in messages:
if m.role == "system":
@@ -266,20 +282,24 @@ def _to_gemini_contents(
result_text = "\n".join(t for t in inner if t) or json.dumps(payload, default=str)
else:
result_text = str(payload)
- tool_name = m.name or ""
- contents.append(
- {
- "role": "user",
- "parts": [
- {
- "functionResponse": {
- "name": name_map.get(tool_name, tool_name),
- "response": {"result": result_text},
- }
- }
- ],
+ tool_name = m.name or call_names.get(m.tool_call_id or "", "")
+ response = {
+ "functionResponse": {
+ "name": name_map.get(tool_name, tool_name),
+ "response": {"result": result_text},
}
- )
+ }
+ previous = contents[-1] if contents else None
+ if (
+ previous is not None
+ and previous["role"] == "user"
+ and previous["parts"]
+ and all("functionResponse" in part for part in previous["parts"])
+ ):
+ # The next result of the same parallel step.
+ previous["parts"].append(response)
+ else:
+ contents.append({"role": "user", "parts": [response]})
continue
# `getattr` for backwards-compat (Protocol pre-Wave-1-B1 had no images).
@@ -295,28 +315,25 @@ def _to_gemini_contents(
elif part.get("type") == "text":
if part.get("text"):
parts.append({"text": str(part["text"])})
- elif (
- part.get("type") == "tool_use"
- and role == "model"
- and isinstance(part.get("thought_signature"), str)
- and part["thought_signature"]
- ):
- # Native replay is only VALID with the original
- # thought_signature: Gemini 3 thinking models 400 on a
- # replayed functionCall part without it. The stream loop
- # captures it (base64) on every native call, so this
- # covers all Gemini-originated calls.
+ elif part.get("type") == "tool_use" and role == "model":
+ # Gemini 3 thinking models 400 on a replayed step whose
+ # first functionCall lacks its thought_signature. The
+ # stream loop captures it (base64) on every signed call;
+ # where it is missing, the sentinel stands in.
call_name = str(part.get("name", ""))
call_args = part.get("input")
- parts.append(
- {
- "functionCall": {
- "name": name_map.get(call_name, call_name),
- "args": call_args if isinstance(call_args, dict) else {},
- },
- "thought_signature": part["thought_signature"],
+ call: dict[str, Any] = {
+ "functionCall": {
+ "name": name_map.get(call_name, call_name),
+ "args": call_args if isinstance(call_args, dict) else {},
}
- )
+ }
+ signature = part.get("thought_signature")
+ if isinstance(signature, str) and signature:
+ call["thought_signature"] = signature
+ elif not any("functionCall" in earlier for earlier in parts):
+ call["thought_signature"] = _SKIP_SIGNATURE
+ parts.append(call)
else:
# Unknown block type: keep the previous lossless behavior.
parts.append({"text": json.dumps(part, default=str)})
@@ -1054,10 +1071,11 @@ class GeminiBrain:
if req.system:
system_parts.append(req.system)
- config_dict: dict[str, Any] = {
- "temperature": req.temperature,
- "max_output_tokens": req.max_tokens,
- }
+ config_dict: dict[str, Any] = {"max_output_tokens": req.max_tokens}
+ if _agent_profile.sends_temperature():
+ # An agent that chose no temperature gets the model's default
+ # (Gemini 3 is tuned for 1.0 and may loop below it).
+ config_dict["temperature"] = req.temperature
system_text = "\n\n".join(system_parts) if system_parts else ""
# One pass builds both the outbound declarations and the name map.
tools_payload, _tool_name_map = _build_gemini_tool_declarations(req.tools)
diff --git a/jarvis/plugins/brain/ollama.py b/jarvis/plugins/brain/ollama.py
index 388485eeb0..d471b5d4ac 100644
--- a/jarvis/plugins/brain/ollama.py
+++ b/jarvis/plugins/brain/ollama.py
@@ -164,6 +164,7 @@ class OllamaBrain:
self._client: Any = None
self._server_root: str | None = None
self._credential: str | None = None
+ self._requested_context_window: int | None = None
# Discovery cache per requirement profile (tools, vision) — a plain
# chat turn may run a smaller model than a tool turn or an image turn
# without re-asking the server every time.
@@ -176,6 +177,12 @@ class OllamaBrain:
def can_call_tools(self) -> bool:
return self.supports_tools
+ def set_context_window(self, tokens: int) -> None:
+ """Allocate the gateway's resolved context on this instance only."""
+ if isinstance(tokens, bool) or not isinstance(tokens, int) or tokens < 1:
+ raise ValueError("Context window must be a positive integer")
+ self._requested_context_window = tokens
+
def _resolve_root(self) -> str:
if self._server_root is None:
ep = cfg.resolve_provider_endpoint(
@@ -347,10 +354,16 @@ class OllamaBrain:
# the next synchronous resolver question.
self.supports_vision = True
run_model, req = await self._apply_model_options(model, req)
+ # A temperature the person set on the model card is sent even to an
+ # agent that chose none; otherwise the agent request profile decides.
+ options = self._model_options(model)
+ send_temperature = True if options is not None and options.temperature is not None else None
# Invariant at this point: either the request carries no images, or the
# model just negotiated declares ``vision`` — so the streamer may encode
# them.
- async for delta in stream_complete(client, run_model, req, supports_vision=True):
+ async for delta in stream_complete(
+ client, run_model, req, supports_vision=True, send_temperature=send_temperature
+ ):
yield delta
def _model_options(self, model: str) -> OllamaModelOptions | None:
@@ -382,6 +395,12 @@ class OllamaBrain:
against the real window instead of the class floor.
"""
opts = self._model_options(model)
+ if self._requested_context_window is not None:
+ if opts is not None and opts.num_ctx and opts.num_ctx < self._requested_context_window:
+ raise RuntimeError("The local model context changed. Start the turn again.")
+ opts = (opts or OllamaModelOptions()).model_copy(
+ update={"num_ctx": self._requested_context_window}
+ )
if opts is None:
return model, req
from jarvis.brain.ollama_profiles import ( # noqa: PLC0415 — lazy (AP-26)
@@ -397,6 +416,12 @@ class OllamaBrain:
try:
run_model = await ensure_profile(root, model, opts)
except Exception as exc: # noqa: BLE001 — degrade to the base model, say so
+ if self._requested_context_window is not None:
+ # The runtime already budgets against this window. Sending
+ # to the base model would silently serve a smaller context.
+ raise RuntimeError(
+ "Could not prepare the selected local model context."
+ ) from exc
log.warning(
"ollama: profile for %s unavailable, running the base model (%s)",
model,
diff --git a/jarvis/society/roster.py b/jarvis/society/roster.py
index 6499456f57..ef2d0cb8d3 100644
--- a/jarvis/society/roster.py
+++ b/jarvis/society/roster.py
@@ -19,6 +19,7 @@ from __future__ import annotations
import asyncio
import json
+import logging
import re
import secrets
import sqlite3
@@ -44,6 +45,8 @@ from .events import (
from .failure_reasons import FailureReason
from .store import SocietyStore
+log = logging.getLogger(__name__)
+
__all__ = [
"AgentRecord",
"LEAD_AGENT_ID",
@@ -376,6 +379,40 @@ def _validate_computer(value: Any) -> str | None:
return computer_id
+#: Roster columns whose change moves an agent off the model route its
+#: Hermes / OpenClaw runtime was granted.
+_SEAT_COLUMNS: Final[tuple[str, ...]] = ("provider", "model", "account_id")
+
+
+def _seat_left(before: dict[str, Any], after: dict[str, Any]) -> bool:
+ """Whether a runtime agent's model gateway grants stopped being its own.
+
+ True for an agent on Hermes / OpenClaw whose provider, model or paying
+ account changed, or that was archived.
+ """
+ if str(after.get("runtime") or "jarvis") == "jarvis":
+ return False
+ if str(after.get("state") or "") == str(AgentState.ARCHIVED) != str(before.get("state") or ""):
+ return True
+ return any(str(before.get(key) or "") != str(after.get(key) or "") for key in _SEAT_COLUMNS)
+
+
+def _revoke_runtime_grants(agent_id: str) -> None:
+ """Drop the agent's model gateway tokens, so a runtime process still
+ holding one cannot spend the old seat; the next turn is granted anew."""
+ from jarvis.agent_runtimes import gateway
+
+ revoke = getattr(gateway, "revoke_agent", None)
+ if revoke is None: # a build without grant revocation: tokens end with the app
+ return
+ try:
+ revoked = revoke(agent_id)
+ except Exception: # noqa: BLE001 — the roster change stands; the stale grant is logged
+ log.warning("society: runtime grants of %s not revoked", agent_id, exc_info=True)
+ return
+ log.info("society: revoked %s runtime gateway grant(s) of %s", revoked, agent_id)
+
+
def _check_runtime_placement(runtime: Any, computer_id: Any) -> None:
"""An external runtime (Hermes, OpenClaw) runs on this computer only, for now."""
if str(runtime or "jarvis") != "jarvis" and computer_id:
@@ -723,6 +760,8 @@ class Roster:
assert row is not None
record = await self._hydrate(row)
await self.refresh()
+ if _seat_left(current, row):
+ _revoke_runtime_grants(agent_id)
return record
async def archive(self, agent_id: str) -> AgentRecord:
diff --git a/jarvis/society/routine_runner.py b/jarvis/society/routine_runner.py
index 187cb68213..408bb176ce 100644
--- a/jarvis/society/routine_runner.py
+++ b/jarvis/society/routine_runner.py
@@ -152,6 +152,12 @@ def _run_runtime(agent: Any, provider: str) -> str:
return "" if resolve_runner(provider, surface=SURFACE).endswith("-cli") else runtime
+def _left_runtime(agent: Any, run_runtime: str) -> str:
+ """The owner's Hermes / OpenClaw runtime this run does NOT use, or ""."""
+ owner = str(getattr(agent, "runtime", "") or "jarvis")
+ return owner if owner != "jarvis" and not run_runtime else ""
+
+
async def run_owned_routine(
runtime: Any,
task_id: str,
@@ -189,6 +195,7 @@ async def run_owned_routine(
# conservative; later permission expansion never widens the saved grant.
order = {"ask": 0, "accept-edits": 1, "bypass": 2}
permission_mode = min((saved_mode, origin.permission_mode), key=lambda m: order.get(m, -1))
+ run_runtime = _run_runtime(agent, provider)
session = service.store.create_session(
session_id=f"{agent.session_id}{ROUTINE_SESSION_MARKER}{task_id}:{uuid4().hex}",
surface=SURFACE,
@@ -199,7 +206,7 @@ async def run_owned_routine(
cwd=_workspace(cfg, agent),
permission_mode=permission_mode,
title=f"{agent.name} · Routine {task_id}",
- runtime=_run_runtime(agent, provider),
+ runtime=run_runtime,
)
# Persist the link before starting work, including runs that fail or are cancelled.
task_store, _ = runtime.task_services()
@@ -207,6 +214,28 @@ async def run_owned_routine(
await task_store.append_step(
task_id, "log", {"event": "routine_chat", "session_id": session.session_id}
)
+ left = _left_runtime(agent, run_runtime)
+ if left:
+ # A run pinned to a seat its owner's runtime cannot drive runs on
+ # Jarvis' own loop; the run log and its chat say so instead of silently.
+ note = (
+ f"This run uses Jarvis' own runtime, not {left}: its model "
+ f"({provider}) is a seat {left} cannot drive."
+ )
+ if task_store is not None:
+ await task_store.append_step(
+ task_id,
+ "log",
+ {"event": "routine_runtime_fallback", "runtime": left, "provider": provider,
+ "text": note},
+ )
+ try:
+ await service.post_notice(
+ session.session_id,
+ {"kind": "routine_runtime_fallback", "runtime": left, "text": note},
+ )
+ except Exception: # noqa: BLE001 — the run log above already holds the note
+ log.warning("society: runtime note not posted for %s", task_id, exc_info=True)
# Legacy tasks contain an identity snapshot. The live briefing owns identity now.
_, separator, original = prompt.partition("\nRoutine:\n")
task = original if separator else prompt
diff --git a/jarvis/society/seat_brain.py b/jarvis/society/seat_brain.py
index 5e6836f23b..afc6a47b92 100644
--- a/jarvis/society/seat_brain.py
+++ b/jarvis/society/seat_brain.py
@@ -111,11 +111,38 @@ def agent_seat(config: Any, agent: Any) -> Seat:
if not provider:
raise SeatUnavailable("this agent's chat names no provider")
account = getattr(agent, "account_id", "") if provider == agent.provider else ""
+ if str(getattr(agent, "runtime", "") or "jarvis") != "jarvis":
+ return _runtime_seat(provider, model or "", account)
return Seat(
provider, model or "", resolve_runner(provider, surface="society", account_id=account)
)
+def _runtime_seat(provider: str, model: str, account: str) -> Seat:
+ """The seat of a Hermes / OpenClaw agent: the auth its gateway route uses.
+
+ Jarvis' model gateway answers such an agent on the provider's API key, or
+ on the Claude login when the agent is pinned to it or no key is saved
+ (``model_map.login_token_for``). ``resolve_runner`` alone would prefer
+ Claude Code for an unpinned agent, so its reviews would run on the plan
+ while its chat bills the key. The login is reachable for a review only
+ through Claude Code; without it the seat is unavailable, never a key.
+ """
+ from jarvis.agent_chat.catalog import API_KEY_ACCOUNT, SUBSCRIPTION_ACCOUNT
+ from jarvis.agent_chat.service import resolve_runner
+ from jarvis.agent_runtimes.model_map import login_token_for
+
+ on_login = login_token_for(provider, account) is not None
+ pinned = SUBSCRIPTION_ACCOUNT if on_login else API_KEY_ACCOUNT
+ runner = resolve_runner(provider, surface="society", account_id=pinned)
+ if on_login and runner in _KEYED_RUNNERS:
+ raise SeatUnavailable(
+ "this agent's chat runs on the Claude login, which only Claude Code can "
+ "use for a review, and Claude Code is not installed"
+ )
+ return Seat(provider, model, runner)
+
+
def jarvis_seat(config: Any) -> Seat:
"""The Jarvis lead's seat: what the front-page chat answers on right now.
diff --git a/jarvis/ui/web/agent_chat_routes.py b/jarvis/ui/web/agent_chat_routes.py
index 0edc0f1929..e7f6ee69b3 100644
--- a/jarvis/ui/web/agent_chat_routes.py
+++ b/jarvis/ui/web/agent_chat_routes.py
@@ -213,7 +213,7 @@ async def run_chat_command(
session_id: str, body: CommandRequest, request: Request
) -> CommandResult:
try:
- return await _service(request).controls.execute(session_id, body)
+ return await (await _async_service(request)).controls.execute(session_id, body)
except ValueError as exc:
raise HTTPException(409, str(exc)) from exc
@@ -350,7 +350,7 @@ def schedule_turn_reattach(state: Any) -> asyncio.Task[None] | None:
await asyncio.sleep(_REATTACH_DELAY_S)
if not await asyncio.to_thread(turn_host_client.may_hold_turns):
return
- if _service_from_state(state) is None:
+ if (await asyncio.to_thread(_service_from_state, state)) is None:
log.warning("agent chat: thread turns wait — the chat service could not be built")
return loop.create_task(_run(), name="agent-chat-boot-reattach")
@@ -363,6 +363,16 @@ def _service(request: Request) -> AgentChatService:
return svc
+async def _async_service(request: Request) -> AgentChatService:
+ """Wait for lazy construction without holding the serving event loop."""
+ service = getattr(request.app.state, "agent_chat", None)
+ if service is not None:
+ return service
+ # Sync routes can already own the construction lock. Waiting on that lock
+ # here freezes HTTP, voice, and callbacks needed by the builder itself.
+ return await asyncio.to_thread(_service, request)
+
+
def _ws_service(ws: WebSocket) -> AgentChatService | None:
app = ws.scope.get("app")
return _service_from_state(app.state) if app is not None else None
@@ -423,7 +433,7 @@ async def get_catalog(
has no CLI seats, so it is offered only the providers whose own API a
brain plugin drives — and no CLI is probed for its model list either.
"""
- svc = _service(request)
+ svc = (await _async_service(request))
cli_seats = kit_for(surface).cli_seats
from jarvis.agent_chat.runner_cli import cli_catalog_scope
@@ -525,7 +535,7 @@ async def get_composer_tools(
"""Discover tools for the Jarvis chat without executing any capability."""
from jarvis.agent_chat.tool_catalog import discover
- svc = _service(request)
+ svc = (await _async_service(request))
if provider and not any(row.id == provider for row in rows_for("jarvis")):
raise HTTPException(status_code=400, detail="Unknown chat provider")
pending = asyncio.create_task(
@@ -570,7 +580,7 @@ async def get_typeahead(
commands and plugins, the folder's own, or the files under it — and a
trigger the seat does not honour answers with an empty list.
"""
- svc = _service(request)
+ svc = (await _async_service(request))
runner = resolve_runner(provider, surface=surface) if provider else "api"
folder = _validate_cwd(cwd) or svc.default_cwd(surface)
# A society chat completes its own teammates, capabilities and learned
@@ -789,7 +799,7 @@ async def get_provider_health(
these in when they land. A row that does not finish inside the sweep
ceiling comes back ``unknown`` and is drawn exactly as it was before.
"""
- _service(request) # 503 like every other route when the chat is off
+ (await _async_service(request)) # 503 like every other route when the chat is off
from jarvis.brain.provider_health_ledger import ledger_version
from jarvis.core.config import secret_generation
@@ -1016,7 +1026,7 @@ async def list_subagents(session_id: str, request: Request) -> dict[str, Any]:
"""
from jarvis.agent_chat.subagent_transcripts import codex_homes, codex_subagents
- svc = _service(request)
+ svc = (await _async_service(request))
session = svc.store.get_session(session_id)
if session is None:
raise HTTPException(status_code=404, detail="session not found")
@@ -1035,7 +1045,7 @@ async def list_subagents(session_id: str, request: Request) -> dict[str, Any]:
async def patch_session(
session_id: str, body: PatchSessionBody, request: Request
) -> dict[str, Any]:
- svc = _service(request)
+ svc = (await _async_service(request))
existing = svc.store.get_session(session_id)
if existing is None:
raise HTTPException(status_code=404, detail="session not found")
@@ -1142,7 +1152,7 @@ async def patch_session(
@router.delete("/sessions/{session_id}")
async def delete_session(session_id: str, request: Request) -> dict[str, Any]:
- svc = _service(request)
+ svc = (await _async_service(request))
if svc.store.get_session(session_id) is None:
raise HTTPException(status_code=404, detail="session not found")
await svc.controls.pause(session_id, "Session deleted")
@@ -1168,7 +1178,7 @@ async def post_message(session_id: str, body: MessageBody, request: Request) ->
raise HTTPException(status_code=422, detail=str(exc)) from exc
from jarvis.agent_chat.send_queue import QueueFull, send_or_queue
- svc = _service(request)
+ svc = (await _async_service(request))
token = client_timezone.set(body.timezone)
try:
# A created agent's chat queues a message behind its running turn
@@ -1202,7 +1212,7 @@ async def post_message(session_id: str, body: MessageBody, request: Request) ->
openapi_extra={"x-jarvis-dangerous": True},
)
async def cancel_turn(session_id: str, request: Request) -> dict[str, Any]:
- svc = _service(request)
+ svc = (await _async_service(request))
if svc.store.get_session(session_id) is None:
raise HTTPException(status_code=404, detail="session not found")
session = svc.store.get_session(session_id)
@@ -1231,11 +1241,21 @@ async def cancel_turn(session_id: str, request: Request) -> dict[str, Any]:
async def resolve_approval(
session_id: str, approval_id: str, body: ApprovalBody, request: Request
) -> dict[str, Any]:
- svc = _service(request)
+ svc = (await _async_service(request))
if body.decision not in DECISIONS:
raise HTTPException(status_code=400, detail=f"decision must be one of {list(DECISIONS)}")
ok = svc.resolve_approval(session_id, approval_id, body.decision)
if not ok:
+ if await svc.close_stale_approval(session_id, approval_id):
+ # The card outlived what it asked for (an app restart, a second
+ # card for the same call); it is closed now and nothing ran.
+ raise HTTPException(
+ status_code=410,
+ detail=(
+ "This request expired and nothing ran; "
+ "the agent asks again if it still needs it."
+ ),
+ )
raise HTTPException(status_code=404, detail="no such pending approval")
return {"ok": True, "approval_id": approval_id, "decision": body.decision}
@@ -1247,7 +1267,7 @@ async def resolve_approval(
async def answer_question(
session_id: str, question_id: str, body: QuestionAnswerBody, request: Request
) -> dict[str, Any]:
- svc = _service(request)
+ svc = (await _async_service(request))
try:
ok = svc.resolve_question(
session_id,
@@ -1280,7 +1300,7 @@ async def answer_question(
summary="Close an agent's question card and let its recommendations apply",
)
async def skip_question(session_id: str, question_id: str, request: Request) -> dict[str, Any]:
- svc = _service(request)
+ svc = (await _async_service(request))
try:
ok = svc.skip_question(session_id, question_id) or await svc.skip_turn_question(
session_id, question_id
@@ -1297,7 +1317,7 @@ async def skip_question(session_id: str, question_id: str, request: Request) ->
summary="Answer a coding agent's plan card: build it, or keep planning",
)
async def resolve_plan(session_id: str, body: PlanBody, request: Request) -> dict[str, Any]:
- svc = _service(request)
+ svc = (await _async_service(request))
try:
ok = await svc.resolve_turn_plan(session_id, body.turn_id, body.decision)
except ValueError as exc:
@@ -1345,7 +1365,7 @@ async def attach_files(
composer's own ``cwd``, then the surface's default working directory. So an
attach works before the first message, when no session exists yet.
"""
- svc = _service(request)
+ svc = (await _async_service(request))
folder = ""
if session_id:
session = svc.store.get_session(session_id)
@@ -1430,7 +1450,7 @@ async def attachment_file(cwd: str, reference: str) -> Any:
@router.post("/pick-folder")
async def pick_folder(body: PickFolderBody, request: Request) -> dict[str, Any]:
"""Open the system folder dialog (desktop only) and return the choice."""
- _service(request)
+ (await _async_service(request))
try:
from jarvis.agentic_ide import native_picker
except Exception as exc: # noqa: BLE001 — no picker module on this install
@@ -1465,7 +1485,7 @@ async def session_stream(ws: WebSocket, session_id: str) -> None:
``{"type": "ping"}`` every 20 s of silence so a proxy keeps the socket.
"""
await ws.accept()
- svc = _ws_service(ws)
+ svc = (await asyncio.to_thread(_ws_service, ws))
if svc is None:
await ws.close(code=1011, reason="agent chat not ready")
return
diff --git a/jarvis/ui/web/agent_runtime_routes.py b/jarvis/ui/web/agent_runtime_routes.py
index 170e67203e..278e57440e 100644
--- a/jarvis/ui/web/agent_runtime_routes.py
+++ b/jarvis/ui/web/agent_runtime_routes.py
@@ -16,6 +16,7 @@ from fastapi import APIRouter, HTTPException, Request
from jarvis.agent_runtimes import RUNTIME_NAMES, manager
from jarvis.agent_runtimes.model_map import (
+ access_blocked,
access_choices,
login_providers,
subscription_providers,
@@ -25,9 +26,10 @@ from jarvis.agent_runtimes.model_map import (
router = APIRouter(prefix="/api/agent-runtimes", tags=["agent-runtimes"])
-#: ``[checked_at, providers, login_providers, access_choices]``: the keyring is read at most
-#: every few seconds, since the UI polls this route while an install runs.
-_USABLE_CACHE: list[Any] = [float("-inf"), [], [], {}]
+#: ``[checked_at, providers, login_providers, access_choices, access_blocked]``: the
+#: keyring is read at most every few seconds, since the UI polls this route while an
+#: install runs.
+_USABLE_CACHE: list[Any] = [float("-inf"), [], [], {}, {}]
_USABLE_TTL_S = 10.0
@@ -39,7 +41,10 @@ async def list_agent_runtimes(request: Request, refresh: bool = False) -> dict[s
every provider the runtimes can drive once connected; ``login_providers``:
usable ones that answer on a Claude login, billed as extra usage;
``access``: for a provider that can pay two ways, which ways work now —
- ``"api"`` and/or ``"subscription"``)."""
+ ``"api"`` and/or ``"subscription"``; ``access_blocked``: per provider and
+ way, the reason code a way is refused right now, e.g.
+ ``{"claude-api": {"subscription": "extra_usage_off"}}`` — the dialog shows
+ that way disabled with its reason)."""
now = time.monotonic()
if refresh or now - _USABLE_CACHE[0] > _USABLE_TTL_S:
config = getattr(request.app.state, "config", None)
@@ -53,6 +58,7 @@ async def list_agent_runtimes(request: Request, refresh: bool = False) -> dict[s
usable,
await asyncio.to_thread(login_providers),
await asyncio.to_thread(access_choices),
+ await asyncio.to_thread(access_blocked),
]
return {
"runtimes": await manager.statuses(refresh=refresh),
@@ -61,6 +67,7 @@ async def list_agent_runtimes(request: Request, refresh: bool = False) -> dict[s
"subscription_providers": sorted(subscription_providers()),
"login_providers": list(_USABLE_CACHE[2]),
"access": dict(_USABLE_CACHE[3]),
+ "access_blocked": dict(_USABLE_CACHE[4]),
}
diff --git a/jarvis/ui/web/frontend/src/components/agentic/threads/ThreadSubagents.tsx b/jarvis/ui/web/frontend/src/components/agentic/threads/ThreadSubagents.tsx
index b411b573f7..2c17f4d435 100644
--- a/jarvis/ui/web/frontend/src/components/agentic/threads/ThreadSubagents.tsx
+++ b/jarvis/ui/web/frontend/src/components/agentic/threads/ThreadSubagents.tsx
@@ -12,8 +12,12 @@ import { shortCount, subagentCounts, subagentEntry, type SubagentEntry } from ".
* and the header of an opened sub-agent's own conversation.
*/
-/** Opens a sub-agent's conversation by the id of the call that spawned it. */
-export const OpenSubagent = createContext<(id: string) => void>(() => {});
+/**
+ * Opens a sub-agent's conversation by the id of the call that spawned it.
+ * Null where no conversation can be opened (an agent chat): the card then
+ * only reports the sub-agent.
+ */
+export const OpenSubagent = createContext<((id: string) => void) | null>(null);
const STATUS_WORD: Record<SubagentStatus, string> = {
running: "Working",
@@ -76,15 +80,30 @@ function statusLine(entry: SubagentEntry): string {
/**
* Where the main agent spawned a sub-agent: one card with its task, what it
- * is doing or how it ended, and what it spent. A click opens its conversation.
+ * is doing or how it ended, and what it spent. Where its conversation can be
+ * opened, a click opens it.
*/
export function SubagentCard({ block, turn }: { block: ToolBlock; turn: TurnItem }) {
const open = useContext(OpenSubagent);
const entry = useMemo(() => subagentEntry(block, turn), [block, turn]);
const running = entry.status === "running";
+ const card = "group/agent flex w-full min-w-0 items-center gap-3 rounded-xl border border-border bg-card px-3 py-2.5 text-left";
+ const body = <SubagentCardBody entry={entry} running={running} />;
+ if (!open) return <div data-testid="thread-subagent-card" data-status={entry.status} className={card}>{body}</div>;
return <button type="button" onClick={() => open(entry.id)} data-testid="thread-subagent-card" data-status={entry.status}
aria-label={`Open sub-agent ${entry.title}, ${STATUS_WORD[entry.status].toLowerCase()}`}
- className="group/agent flex w-full min-w-0 items-center gap-3 rounded-xl border border-border bg-card px-3 py-2.5 text-left transition-colors hover:border-border-strong hover:bg-secondary/50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
+ className={cn(card, "transition-colors hover:border-border-strong hover:bg-secondary/50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring")}>
+ {body}
+ <span className="flex shrink-0 items-center gap-1 text-xs text-muted-foreground transition-colors group-hover/agent:text-foreground">
+ <MessageSquare aria-hidden className="h-3.5 w-3.5" />
+ <span className="hidden sm:inline">Open</span>
+ <ChevronRight aria-hidden className="h-3.5 w-3.5" />
+ </span>
+ </button>;
+}
+
+function SubagentCardBody({ entry, running }: { entry: SubagentEntry; running: boolean }) {
+ return <>
<span aria-hidden className="relative flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-secondary text-foreground-secondary">
<Bot className="h-4 w-4" strokeWidth={1.75} />
<span className="absolute -bottom-1 -right-1 flex h-4 w-4 items-center justify-center rounded-full border border-border bg-card">
@@ -102,12 +121,7 @@ export function SubagentCard({ block, turn }: { block: ToolBlock; turn: TurnItem
<SubagentMeta entry={entry} />
</span>
</span>
- <span className="flex shrink-0 items-center gap-1 text-xs text-muted-foreground transition-colors group-hover/agent:text-foreground">
- <MessageSquare aria-hidden className="h-3.5 w-3.5" />
- <span className="hidden sm:inline">Open</span>
- <ChevronRight aria-hidden className="h-3.5 w-3.5" />
- </span>
- </button>;
+ </>;
}
/** "3 sub-agents · 2 working · 1 waiting" — the switcher's own count. */
diff --git a/jarvis/ui/web/frontend/src/components/agentic/threads/ThreadTimeline.tsx b/jarvis/ui/web/frontend/src/components/agentic/threads/ThreadTimeline.tsx
index ad27f34762..500de4c29a 100644
--- a/jarvis/ui/web/frontend/src/components/agentic/threads/ThreadTimeline.tsx
+++ b/jarvis/ui/web/frontend/src/components/agentic/threads/ThreadTimeline.tsx
@@ -1,11 +1,13 @@
import { createContext, memo, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from "react";
import { ArrowDown, Bot, Brain, Check, ChevronDown, ChevronRight, Copy, Diff, FileText, Hammer, MessageCircleQuestion, ShieldAlert, X } from "lucide-react";
import { ChatMarkdown } from "@/components/agentchat/ChatMarkdown";
+import { QuestionCard } from "@/components/agentchat/QuestionCard";
import type { TextBlock, TimelineItem, ToolBlock, TurnBlock, TurnItem, UserItem } from "@/components/agentchat/reduce";
import { toolDiff, type DiffFile } from "@/components/agentchat/toolDiff";
import { CallMark, StretchMark } from "@/components/agentchat/TraceTimeline";
-import { readableOutput, traceDuration, type Call } from "@/components/agentchat/traceEntries";
-import { useT } from "@/i18n";
+import { plural, readableOutput, traceDuration, type Call } from "@/components/agentchat/traceEntries";
+import { fill, useT } from "@/i18n";
+import type { ApprovalDecision } from "@/lib/agentChatApi";
import { robustCopy } from "@/lib/clipboard";
import { cn } from "@/lib/utils";
import { buildThreadRows, isFailed, thoughtGist, type ThreadRow, type WorkGroup, type WorkItem } from "./threadWork";
@@ -163,6 +165,7 @@ export function callPictures(blocks: TurnBlock[]): CallPictures {
/** What a call opened to: its pictures, the diff it made, else what ran and what came back. */
function CallDetails({ call }: { call: Call }) {
+ const t = useT();
const block = call.block;
const pictures = useContext(CallMedia).get(block.callId);
const diff = useMemo(() => toolDiff(block.name, block.input, block.output), [block.name, block.input, block.output]);
@@ -179,7 +182,7 @@ function CallDetails({ call }: { call: Call }) {
{input && input !== "{}" && <pre className="m-0 max-h-48 overflow-auto rounded-lg bg-secondary px-3 py-2 font-mono text-xs leading-5 text-muted-foreground scrollbar-jarvis">{input}</pre>}
{output
? <pre className={cn("m-0 max-h-72 overflow-auto whitespace-pre-wrap rounded-lg border border-border px-3 py-2 font-mono text-xs leading-5 scrollbar-jarvis", block.isError ? "text-destructive" : "text-foreground-secondary")}>{output}</pre>
- : block.output === null ? null : <p className="text-xs text-muted-foreground">No output.</p>}
+ : block.output === null ? null : <p className="text-xs text-muted-foreground">{t("thread_turn.no_output")}</p>}
</div>;
}
@@ -196,11 +199,12 @@ function useDisclosure(onOpenChange?: OpenChange): [boolean, () => void] {
}
function CallRow({ call, stamp, grouped = false, onOpenChange }: { call: Call; stamp?: number; grouped?: boolean; onOpenChange?: OpenChange }) {
+ const t = useT();
const [open, toggle] = useDisclosure(onOpenChange);
const failed = isFailed(call);
const running = call.status === "running";
const detail = call.detail || call.result;
- const tail = failed && call.reason ? call.reason : call.status === "interrupted" ? "interrupted" : "";
+ const tail = failed && call.reason ? call.reason : call.status === "interrupted" ? t("thread_turn.interrupted") : "";
// The shine paints the label's own text, so a running row is one run of words.
const label = running
? [call.text, detail].filter(Boolean).join(" ")
@@ -212,7 +216,7 @@ function CallRow({ call, stamp, grouped = false, onOpenChange }: { call: Call; s
return <WorkRow
icon={<span className={cn("flex items-center justify-center", failed && "text-destructive/70")}><CallMark call={call} /></span>}
label={label}
- ariaLabel={failed ? `${call.text}, failed` : undefined}
+ ariaLabel={failed ? fill(t("thread_turn.call_failed"), { call: call.text }) : undefined}
trailing={<>
<DiffStat added={call.added} removed={call.removed} />
{failed && <X aria-hidden className="h-3 w-3 shrink-0 text-destructive/70" />}
@@ -251,7 +255,8 @@ function ThoughtView({ text }: { text: string }) {
/** The wordless thought the running turn is having: one live "Thinking" step. */
function ThinkingRow({ grouped = false }: { grouped?: boolean }) {
- return <WorkRow icon={<Brain strokeWidth={1.75} />} label="Thinking" grouped={grouped} live />;
+ const t = useT();
+ return <WorkRow icon={<Brain strokeWidth={1.75} />} label={t("thread_turn.thinking")} grouped={grouped} live />;
}
/**
@@ -273,6 +278,7 @@ const FADE = "1.5rem";
* its end; opening a step lifts the height cap so its detail reads in full.
*/
function StepList({ items, running, follow }: { items: WorkItem[]; running: boolean; follow: boolean }) {
+ const t = useT();
const box = useRef<HTMLDivElement | null>(null);
const atEnd = useRef(true);
const [edges, setEdges] = useState({ top: false, bottom: false });
@@ -306,7 +312,7 @@ function StepList({ items, running, follow }: { items: WorkItem[]; running: bool
const mask = edges.top || edges.bottom
? `linear-gradient(to bottom, ${edges.top ? "transparent" : "black"} 0, black ${FADE}, black calc(100% - ${FADE}), ${edges.bottom ? "transparent" : "black"} 100%)`
: undefined;
- return <div ref={box} role="region" aria-label="Steps" tabIndex={-1} onScroll={measure}
+ return <div ref={box} role="region" aria-label={t("thread_turn.steps")} tabIndex={-1} onScroll={measure}
className="overflow-y-auto overflow-x-hidden rounded-md scrollbar-jarvis"
style={{ maxHeight: openSteps > 0 ? undefined : "min(18rem, 50dvh)", maskImage: mask, WebkitMaskImage: mask }}>
<div className="flex min-w-0 flex-col">
@@ -335,12 +341,13 @@ function GroupMark({ group }: { group: WorkGroup }) {
* still close it.
*/
function WorkGroupView({ group, running }: { group: WorkGroup; running: boolean }) {
+ const t = useT();
const [open, setOpen] = useState(group.live);
if (group.items.length === 1) return <StepRow item={group.items[0]} running={running} />;
return <WorkRow
icon={<GroupMark group={group} />}
label={group.summary}
- ariaLabel={group.live ? `${group.summary}, ${group.items.length} steps so far` : undefined}
+ ariaLabel={group.live ? fill(t("thread_turn.steps_so_far"), { summary: group.summary, count: group.items.length }) : undefined}
trailing={<DiffStat added={group.added} removed={group.removed} />}
stamp={group.startedMs}
live={group.live}
@@ -464,6 +471,8 @@ function ChangeCount({ added, removed, className }: { added: number; removed: nu
* "Show changes" opens every diff at once.
*/
export function ChangedFiles({ turn }: { turn: TurnItem }) {
+ const t = useT();
+ const lang = t("trace_report.locale");
const root = useContext(ThreadFolder);
const rows = useMemo(() => changedFiles(turn), [turn]);
const [openPaths, setOpenPaths] = useState<ReadonlySet<string>>(() => new Set());
@@ -484,8 +493,8 @@ export function ChangedFiles({ turn }: { turn: TurnItem }) {
setOpenPaths(new Set(rows.map((row) => row.path)));
setExpanded(true);
};
- const title = `${rows.length} ${rows.length === 1 ? "file" : "files"} changed`;
- return <section aria-label="Changed files" data-testid="thread-changed-files" className="mt-3 overflow-hidden rounded-xl border border-border bg-card">
+ const title = fill(t(`thread_turn.files_changed_${plural(lang, rows.length)}`), { count: rows.length });
+ return <section aria-label={t("thread_turn.changed_files")} data-testid="thread-changed-files" className="mt-3 overflow-hidden rounded-xl border border-border bg-card">
<div className="flex items-center gap-3 border-b border-border px-3 py-3">
<span aria-hidden className="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-secondary text-foreground-secondary">
<span className="flex h-5 w-5 items-center justify-center rounded-[5px] border-[1.5px] border-current"><Diff className="h-3 w-3" strokeWidth={2.25} /></span>
@@ -496,7 +505,7 @@ export function ChangedFiles({ turn }: { turn: TurnItem }) {
</div>
<button type="button" aria-pressed={allOpen} onClick={toggleAll}
className="shrink-0 rounded-lg border border-border bg-background px-3 py-1.5 text-sm text-foreground hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
- {allOpen ? "Hide changes" : "Show changes"}
+ {t(allOpen ? "thread_turn.hide_changes" : "thread_turn.show_changes")}
</button>
</div>
<ul>
@@ -521,7 +530,7 @@ export function ChangedFiles({ turn }: { turn: TurnItem }) {
</ul>
{hidden > 0 && <button type="button" aria-expanded={expanded} onClick={() => setExpanded(!expanded)}
className="flex w-full items-center gap-1.5 px-3 py-2 text-left text-sm text-foreground-secondary hover:bg-secondary/60 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring">
- {expanded ? "Collapse files" : `Show ${hidden} more ${hidden === 1 ? "file" : "files"}`}
+ {expanded ? t("thread_turn.collapse_files") : fill(t(`thread_turn.more_files_${plural(lang, hidden)}`), { count: hidden })}
<ChevronDown aria-hidden className={cn("h-4 w-4 transition-transform duration-200", expanded && "rotate-180")} />
</button>}
</section>;
@@ -531,14 +540,59 @@ function answerText(turn: TurnItem): string {
return turn.blocks.filter((block): block is TextBlock => block.kind === "text").map((block) => block.text.trim()).filter(Boolean).join("\n\n");
}
-function pendingLabel(block: ToolBlock): { icon: ReactNode; text: string } | null {
- if (block.question && !block.question.closed) return { icon: <MessageCircleQuestion className="h-3.5 w-3.5" />, text: "Waiting for your answer below" };
+/** How a surface answers an approval: by its id, with the person's decision. */
+export type Decide = (id: string, decision: ApprovalDecision) => void | Promise<void>;
+
+/** A call still waiting for the person: an open question or an undecided approval. */
+function waitsForPerson(block: ToolBlock): boolean {
+ return Boolean(block.question && !block.question.closed) || Boolean(block.approval && block.approval.decision === null);
+}
+
+function pendingLabel(block: ToolBlock, t: (key: string) => string): { icon: ReactNode; text: string } | null {
+ if (block.question && !block.question.closed) return { icon: <MessageCircleQuestion className="h-3.5 w-3.5" />, text: t("thread_turn.waiting_answer") };
if (block.approval && block.approval.decision === null) {
- return { icon: <ShieldAlert className="h-3.5 w-3.5" />, text: `Waiting for approval — ${block.approval.summary || block.name}` };
+ return { icon: <ShieldAlert className="h-3.5 w-3.5" />, text: fill(t("thread_turn.waiting_approval"), { summary: block.approval.summary || block.name }) };
}
return null;
}
+/**
+ * An approval answered in the turn itself: the waiting line, what the agent
+ * asks for, and the three answers under it.
+ */
+function ApprovalPrompt({ block, onDecide }: { block: ToolBlock; onDecide?: Decide }) {
+ const t = useT();
+ const [busy, setBusy] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+ const approval = block.approval;
+ if (!approval) return null;
+ const decide = async (decision: ApprovalDecision) => {
+ if (!onDecide || busy) return;
+ setBusy(true);
+ setError(null);
+ try { await onDecide(approval.approvalId, decision); }
+ catch (err) { setError(err instanceof Error ? err.message : String(err)); }
+ finally { setBusy(false); }
+ };
+ return <div className="min-w-0" role="group" aria-label={t("work_trace.approval")} data-testid="thread-approval">
+ <WorkRow icon={<ShieldAlert strokeWidth={1.75} />} label={t("thread_turn.approval_waiting")} live />
+ <div className="mb-1.5 ml-7 space-y-2 text-sm">
+ {approval.summary && <p className="m-0 text-foreground [overflow-wrap:anywhere]">{approval.summary}</p>}
+ {onDecide
+ ? <div className="flex flex-wrap gap-2">
+ {(["allow", "allow_always", "deny"] as const).map((decision) => <button key={decision} type="button" disabled={busy}
+ onClick={() => void decide(decision)}
+ className={cn("rounded-md px-3 py-1.5 text-xs focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50",
+ decision === "allow" ? "bg-primary text-primary-foreground hover:opacity-90" : "border border-border text-foreground hover:bg-secondary")}>
+ {t(`work_trace.${decision}`)}
+ </button>)}
+ </div>
+ : <p className="m-0 text-xs text-muted-foreground">{t("work_trace.approval_elsewhere")}</p>}
+ {error && <p role="alert" className="m-0 text-xs text-destructive">{error}</p>}
+ </div>
+ </div>;
+}
+
/**
* A finished turn read the short way: everything up to its last step folds
* behind one "Worked for …" line, and the text written after that step — the
@@ -552,10 +606,42 @@ export function foldFinished(rows: ThreadRow[]): { work: ThreadRow[]; answer: Th
return { work: rows.slice(0, last + 1), answer: rows.slice(last + 1) };
}
-const TurnView = memo(function TurnView({ turn }: { turn: TurnItem }) {
+/** "Working for 12s" with the ticking clock in place of the duration. */
+function WorkingFor({ since }: { since: number }) {
+ const t = useT();
+ const [before, after = ""] = t("thread_turn.working_for").split("{duration}");
+ return <>{before}<Elapsed since={since} />{after}</>;
+}
+
+export interface ThreadTurnProps {
+ turn: TurnItem;
+ /**
+ * Where the person answers a waiting call. A thread answers in its
+ * composer, so the turn only says it waits; an agent chat ("inline") draws
+ * the question card and the approval buttons in the turn itself.
+ */
+ prompts?: "composer" | "inline";
+ onDecide?: Decide;
+ /**
+ * Steps that belong to this turn's work without being blocks of it (a
+ * memory receipt posted after the turn). They sit with the work, above the
+ * answer, and fold with it.
+ */
+ extras?: { key: string; node: ReactNode }[];
+ /** A quiet note on a finished turn's closing line: tokens, cost. */
+ receipt?: ReactNode;
+}
+
+/**
+ * One turn of a conversation the way a thread reads it. The Agentic IDE's
+ * threads and every agent chat draw their turns with it, so a turn looks and
+ * behaves the same wherever it is read — streaming, finished or reloaded.
+ */
+export const ThreadTurn = memo(function ThreadTurn({ turn, prompts = "composer", onDecide, extras, receipt }: ThreadTurnProps) {
const t = useT();
const lang = t("trace_report.locale");
const running = turn.status === "running";
+ const inline = prompts === "inline";
const pictures = useMemo(() => callPictures(turn.blocks), [turn.blocks]);
const rows = useMemo(
() => buildThreadRows(turn.blocks, { t, lang, status: turn.status }).filter((row) => !(row.kind === "text" && pictures.moved.has(row.block.id))),
@@ -567,47 +653,72 @@ const TurnView = memo(function TurnView({ turn }: { turn: TurnItem }) {
const { work, answer: tail } = useMemo(() => (running ? { work: rows, answer: [] } : foldFinished(rows)), [rows, running]);
// The sub-agents it spawned stay in view under the fold: each opens its own conversation.
const agents = useMemo(() => work.filter((row) => row.kind === "agent"), [work]);
+ // A call that still waits for the person never folds away.
+ const waiting = useMemo(() => work.filter((row) => row.kind === "pending" && waitsForPerson(row.block)), [work]);
const agentsWorking = useMemo(() => running ? listSubagents([turn]).filter((entry) => entry.status === "running").length : 0, [turn, running]);
- const folded = !running && work.length > 0;
+ const extraRows = extras ?? [];
+ const folded = !running && (work.length > 0 || extraRows.length > 0);
const duration = turn.durationMs != null ? traceDuration(turn.durationMs) : "";
- const foldLabel = turn.status === "cancelled" ? `Stopped${duration ? ` after ${duration}` : ""}`
- : turn.status === "error" ? `Failed${duration ? ` after ${duration}` : ""}`
- : `Worked${duration ? ` for ${duration}` : ""}`;
+ const timed = (key: string) => duration ? fill(t(`thread_turn.${key}_after`), { duration }) : t(`thread_turn.${key}`);
+ const workedFor = duration ? fill(t("thread_turn.worked_for"), { duration }) : "";
+ const foldLabel = turn.status === "cancelled" ? timed("stopped")
+ : turn.status === "error" ? timed("failed")
+ : workedFor || t("thread_turn.worked");
+ const closing = turn.status === "cancelled" ? timed("stopped")
+ : turn.status === "error" ? timed("failed")
+ : answer ? workedFor : timed("no_answer");
const renderRow = (row: ThreadRow) => {
if (row.kind === "work") return <WorkGroupView key={row.id} group={row} running={running} />;
if (row.kind === "thought") return <ThoughtView key={row.id} text={row.text} />;
if (row.kind === "text") return <div key={row.id} className={cn(PROSE, THREAD_MEDIA)}><ChatMarkdown text={row.text} /></div>;
if (row.kind === "agent") return <SubagentCard key={row.id} block={row.block} turn={turn} />;
- const pending = pendingLabel(row.block);
+ if (inline) {
+ if (row.block.question) return <QuestionCard key={row.id} question={row.block.question} />;
+ if (row.block.approval && row.block.approval.decision === null) return <ApprovalPrompt key={row.id} block={row.block} onDecide={onDecide} />;
+ return null;
+ }
+ const pending = pendingLabel(row.block, t);
return pending ? <WorkRow key={row.id} icon={pending.icon} label={pending.text} live /> : null;
};
- return <CallMedia.Provider value={pictures.byCall}><div className="space-y-1.5" data-testid="thread-turn" data-status={turn.status}>
+ const extraNodes = extraRows.map((extra) => <div key={`extra:${extra.key}`} className="min-w-0">{extra.node}</div>);
+ // A running turn's streaming answer is its tail; extra steps go above it.
+ const shown = folded ? tail : rows;
+ let extraAt = shown.length;
+ if (!folded) while (extraAt > 0 && shown[extraAt - 1].kind === "text") extraAt--;
+ return <CallMedia.Provider value={pictures.byCall}><div className="min-w-0 space-y-1.5" data-testid="thread-turn" data-status={turn.status}>
{folded && <div>
<button type="button" aria-expanded={workOpen} onClick={() => setWorkOpen((value) => !value)} data-testid="thread-worked-for"
className="flex h-7 items-center gap-1 rounded-md px-1 text-sm text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
<span className="tabular-nums">{foldLabel}</span>
<ChevronRight aria-hidden className={cn("h-3.5 w-3.5 transition-transform duration-150", workOpen && "rotate-90")} />
</button>
- {workOpen && <div className="space-y-1.5 pb-2 pt-1" data-testid="thread-worked-steps">{work.filter((row) => row.kind !== "agent").map(renderRow)}</div>}
+ {workOpen && <div className="space-y-1.5 pb-2 pt-1" data-testid="thread-worked-steps">
+ {work.filter((row) => row.kind !== "agent" && !waiting.includes(row)).map(renderRow)}
+ {extraNodes}
+ </div>}
<div aria-hidden className="mt-1 border-b border-border/70" />
</div>}
{folded && agents.length > 0 && <div className="space-y-1.5 pt-1" data-testid="thread-turn-subagents">{agents.map(renderRow)}</div>}
- {(folded ? tail : rows).map(renderRow)}
+ {folded && waiting.map(renderRow)}
+ {shown.slice(0, extraAt).map(renderRow)}
+ {!folded && extraNodes}
+ {shown.slice(extraAt).map(renderRow)}
{running
? <div className="flex h-6 min-w-0 items-center px-1 text-sm leading-relaxed text-muted-foreground" data-testid="thread-working">
- <span className="whitespace-nowrap">Working for <Elapsed since={turn.startedMs} />
- {agentsWorking > 0 && <> · {agentsWorking} {agentsWorking === 1 ? "sub-agent" : "sub-agents"} working</>}</span>
+ <span className="whitespace-nowrap"><WorkingFor since={turn.startedMs} />
+ {agentsWorking > 0 && <> · {fill(t(`thread_turn.subagents_working_${plural(lang, agentsWorking)}`), { count: agentsWorking })}</>}</span>
</div>
: <>
{turn.status === "error" && turn.error && <p role="alert" className="rounded-lg border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive">{turn.error}</p>}
<ChangedFiles turn={turn} />
- <div className="flex items-center gap-1.5 pt-1 text-xs text-muted-foreground">
- {!folded && <span>
- {turn.status === "cancelled" ? "Stopped" : turn.status === "error" ? "Failed" : answer ? "" : "Finished without an answer"}
- {duration && <>{turn.status === "done" && answer ? "Worked for " : " after "}{duration}</>}
+ <div className="flex items-center gap-1.5 pt-1 text-xs text-muted-foreground" data-testid="thread-turn-closing">
+ {!folded && closing && <span>{closing}</span>}
+ {folded && !answer && <span>{t("thread_turn.no_answer")}</span>}
+ {receipt && <span className="inline-flex items-center gap-1.5 tabular-nums">
+ {((!folded && closing) || (folded && !answer)) && <span aria-hidden className="text-muted-foreground/50">·</span>}
+ {receipt}
</span>}
- {folded && !answer && <span>Finished without an answer</span>}
- {answer && <CopyButton text={answer} label="Copy answer" />}
+ {answer && <CopyButton text={answer} label={t("thread_turn.copy_answer")} />}
</div>
</>}
</div></CallMedia.Provider>;
@@ -620,7 +731,7 @@ function ErrorLine({ text }: { text: string }) {
/** One item of the conversation, drawn by its kind. */
function ItemView({ item }: { item: TimelineItem }) {
if (item.type === "user") return <UserBubble item={item} />;
- if (item.type === "turn") return <TurnView turn={item} />;
+ if (item.type === "turn") return <ThreadTurn turn={item} />;
if (item.type === "error") return <ErrorLine text={item.text} />;
if (item.type === "notice") {
return <p className="text-center text-xs text-muted-foreground">{item.agentName ? `${item.agentName}: ` : ""}{item.text}</p>;
diff --git a/jarvis/ui/web/frontend/src/components/agentic/threads/ThreadTurn.test.tsx b/jarvis/ui/web/frontend/src/components/agentic/threads/ThreadTurn.test.tsx
new file mode 100644
index 0000000000..61469579e3
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/agentic/threads/ThreadTurn.test.tsx
@@ -0,0 +1,84 @@
+import { act, cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ToolBlock, TurnBlock, TurnItem, TurnStatus } from "@/components/agentchat/reduce";
+import { ThreadTurn } from "./ThreadTimeline";
+
+const tool = (id: string, command: string, over: Partial<ToolBlock> = {}): ToolBlock => ({
+ kind: "tool", callId: id, name: "Bash", input: { command }, output: "ok", isError: false,
+ durationMs: 300, approval: null, startedMs: 1, ...over,
+});
+const thought = (id: string, text: string, live = false): TurnBlock => ({ kind: "reasoning", id, text, durationMs: live ? null : 4200, live, startedMs: 1 });
+
+function turn(blocks: TurnBlock[], status: TurnStatus = "done"): TurnItem {
+ return {
+ type: "turn", id: "t1", provider: "claude-api", model: "", effort: "", runner: "", status, blocks,
+ startedMs: Date.now(), durationMs: status === "running" ? null : 5000, usage: null, liveUsage: null, costUsd: null, error: null,
+ };
+}
+
+afterEach(cleanup);
+
+/** The thread turn as an agent chat draws it: questions and approvals answered in place. */
+describe("a thread turn in an agent chat", () => {
+ it("reads a streaming turn like a thread and folds it once it answered", () => {
+ const blocks = [thought("r1", "**Checking the inbox**\n\nThree new mails."), tool("c1", "gh pr list"), tool("c2", "gh pr view 3", { output: null, durationMs: null })];
+ const { rerender } = render(<ThreadTurn turn={turn(blocks, "running")} prompts="inline" />);
+ // The worded thought is one short line; the running group stays open with its steps.
+ expect(screen.getByTestId("thread-thought").textContent).toContain("Checking the inbox");
+ expect(screen.queryByText("Three new mails.")).toBeNull();
+ expect(screen.getByRole("button", { name: /steps so far/ }).getAttribute("aria-expanded")).toBe("true");
+ expect(screen.getByTestId("thread-working").textContent).toMatch(/^Working for /);
+ const done = [...blocks.slice(0, 2), { ...blocks[2], output: "ok", durationMs: 200 } as ToolBlock, { kind: "text" as const, id: "a", text: "Two PRs wait for review." }];
+ rerender(<ThreadTurn turn={turn(done)} prompts="inline" receipt="1.2k tokens" />);
+ // Finished: only the answer and the "Worked for" line stay; one tap brings the work back.
+ expect(screen.getByText("Two PRs wait for review.")).toBeTruthy();
+ expect(screen.queryByTestId("thread-thought")).toBeNull();
+ expect(screen.getByTestId("thread-worked-for").textContent).toContain("Worked for 5.0s");
+ expect(screen.getByTestId("thread-turn-closing").textContent).toContain("1.2k tokens");
+ fireEvent.click(screen.getByTestId("thread-worked-for"));
+ expect(screen.getByTestId("thread-thought").textContent).toContain("Checking the inbox");
+ });
+
+ it("never draws a thought the model did not put into words", () => {
+ render(<ThreadTurn turn={turn([thought("r1", ""), tool("c1", "ls"), { kind: "text", id: "a", text: "Done." }])} prompts="inline" />);
+ fireEvent.click(screen.getByTestId("thread-worked-for"));
+ expect(screen.queryByTestId("thread-thought")).toBeNull();
+ expect(screen.queryByText("Thinking")).toBeNull();
+ });
+
+ it("answers an approval in place and keeps it out of the fold", async () => {
+ const onDecide = vi.fn();
+ const asking = tool("c2", "git push", { output: null, durationMs: null, approval: { approvalId: "ap1", summary: "Push to origin?", decision: null } });
+ render(<ThreadTurn turn={turn([tool("c1", "git status"), asking, thought("r1", "Waiting on the push.")])} prompts="inline" onDecide={onDecide} />);
+ // The turn ended while it waited: the work folds, the approval stays in view.
+ expect(screen.getByTestId("thread-worked-for")).toBeTruthy();
+ expect(screen.getByText("Push to origin?")).toBeTruthy();
+ await act(async () => { fireEvent.click(screen.getByRole("button", { name: "Approve" })); });
+ expect(onDecide).toHaveBeenCalledWith("ap1", "allow");
+ });
+
+ it("says a thread waits for its composer when prompts are answered there", () => {
+ const asking = tool("c1", "git push", { output: null, durationMs: null, approval: { approvalId: "ap1", summary: "Push to origin?", decision: null } });
+ render(<ThreadTurn turn={turn([asking], "running")} />);
+ expect(screen.getByText("Waiting for approval — Push to origin?")).toBeTruthy();
+ expect(screen.queryByRole("button", { name: "Approve" })).toBeNull();
+ });
+
+ it("folds memory receipts with the work, above the answer", () => {
+ const extras = [{ key: "m1", node: <span>MEMORY-STEP</span> }];
+ render(<ThreadTurn turn={turn([{ kind: "text", id: "a", text: "Noted." }])} prompts="inline" extras={extras} />);
+ expect(screen.queryByText("MEMORY-STEP")).toBeNull();
+ fireEvent.click(screen.getByTestId("thread-worked-for"));
+ const html = document.body.innerHTML;
+ expect(html.indexOf("MEMORY-STEP")).toBeGreaterThan(-1);
+ expect(html.indexOf("MEMORY-STEP")).toBeLessThan(html.indexOf("Noted."));
+ });
+
+ it("reports a sub-agent without offering to open it where no conversation opens", () => {
+ const task = tool("c1", "", { name: "Task", input: { description: "Scan the repo", prompt: "Scan" }, output: null, durationMs: null });
+ render(<ThreadTurn turn={turn([task], "running")} prompts="inline" />);
+ const card = screen.getByTestId("thread-subagent-card");
+ expect(card.tagName).toBe("DIV");
+ expect(screen.queryByRole("button", { name: /Open sub-agent/ })).toBeNull();
+ });
+});
diff --git a/jarvis/ui/web/frontend/src/components/society/card/RuntimePicker.test.tsx b/jarvis/ui/web/frontend/src/components/society/card/RuntimePicker.test.tsx
index 0e2faee1c4..ee86074359 100644
--- a/jarvis/ui/web/frontend/src/components/society/card/RuntimePicker.test.tsx
+++ b/jarvis/ui/web/frontend/src/components/society/card/RuntimePicker.test.tsx
@@ -54,6 +54,33 @@ describe("RuntimeChoice", () => {
expect(ensure).not.toHaveBeenCalled();
});
+ test("a screen reader hears each runtime's setup state, and arrow keys move the pick", async () => {
+ const onChange = vi.fn();
+ withData(
+ data(status("hermes", true), status("openclaw", false, job("openclaw", "running"))),
+ <RuntimeChoice value="hermes" onChange={onChange} />,
+ );
+ const hermes = await screen.findByRole("radio", { name: "society.runtime.hermes" });
+ const openclaw = screen.getByRole("radio", { name: "society.runtime.openclaw" });
+ await waitFor(() => expect(
+ document.getElementById(openclaw.getAttribute("aria-describedby") ?? "")?.textContent,
+ ).toBe("society.runtime.setting_up"));
+ expect(screen.getAllByRole("radio").map((radio) => radio.tabIndex)).toEqual([-1, 0, -1]);
+ fireEvent.keyDown(hermes, { key: "ArrowRight" });
+ expect(onChange).toHaveBeenCalledWith("openclaw");
+ expect(document.activeElement).toBe(openclaw);
+ fireEvent.keyDown(hermes, { key: "ArrowLeft" });
+ expect(onChange).toHaveBeenLastCalledWith("jarvis");
+ });
+
+ test("a ready runtime newer than the tested release says so, without a version number", async () => {
+ const newer = { ...status("hermes", true), untested: true };
+ withData(data(newer, status("openclaw", true)), <RuntimeChoice value="hermes" onChange={vi.fn()} />);
+ expect(await screen.findByText("society.runtime.ready_untested")).toBeTruthy();
+ expect(screen.getByTestId("runtime-untested").textContent).toBe("society.runtime.untested_hint");
+ expect(screen.queryByText(/1\.2\.3/)).toBeNull();
+ });
+
test("never shows a version number", async () => {
withData(data(status("hermes", true), status("openclaw", true)), <RuntimeChoice value="hermes" onChange={vi.fn()} />);
expect(await screen.findAllByText("society.runtime.ready")).toHaveLength(2);
diff --git a/jarvis/ui/web/frontend/src/components/society/card/RuntimePicker.tsx b/jarvis/ui/web/frontend/src/components/society/card/RuntimePicker.tsx
index 0e314c16be..dfca4e7981 100644
--- a/jarvis/ui/web/frontend/src/components/society/card/RuntimePicker.tsx
+++ b/jarvis/ui/web/frontend/src/components/society/card/RuntimePicker.tsx
@@ -7,7 +7,7 @@
* up to date on its own. The UI only says whether it is ready or still being
* set up — never a version number.
*/
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useId, useRef, useState, type KeyboardEvent } from "react";
import { useQuery, useQueryClient } from "@tanstack/react-query";
import { Loader2 } from "lucide-react";
import { ProviderLogo } from "@/components/providers/ProviderLogo";
@@ -82,6 +82,11 @@ function RuntimeSetupNote({ status, onRetry, error }: {
}) {
const t = useT();
const state = setupState(status);
+ if (state === "ready" && status?.untested) {
+ return <p className="text-xs text-muted-foreground" data-testid="runtime-untested">
+ {fill(t("society.runtime.untested_hint"), t(`society.runtime.${status.runtime}`))}
+ </p>;
+ }
if (state === "ready" || !status) return null;
const label = t(`society.runtime.${status.runtime}`);
const failure = error ?? (state === "failed" ? status.job?.message || status.job?.log_tail.at(-1) || status.problem : null);
@@ -118,6 +123,8 @@ export function RuntimeChoice({ value, onChange, disabled = false }: {
const chosen = value === "jarvis" ? undefined : byName.get(value);
const chosenState = value === "jarvis" ? "ready" : setupState(chosen);
+ const id = useId();
+ const cards = useRef<Partial<Record<AgentRuntime, HTMLButtonElement | null>>>({});
const asked = useRef(new Set<string>());
const loaded = Boolean(runtimes.data);
useEffect(() => {
@@ -128,23 +135,41 @@ export function RuntimeChoice({ value, onChange, disabled = false }: {
void ensure(value);
}, [value, loaded, chosenState, ensure]);
+ function onKeyDown(event: KeyboardEvent<HTMLButtonElement>, runtime: AgentRuntime) {
+ // One tab stop; arrow keys move the choice (the WAI-ARIA radio pattern).
+ const step = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 }[event.key];
+ if (!step) return;
+ event.preventDefault();
+ const index = AGENT_RUNTIMES.indexOf(runtime);
+ const next = AGENT_RUNTIMES[(index + step + AGENT_RUNTIMES.length) % AGENT_RUNTIMES.length];
+ onChange(next);
+ cards.current[next]?.focus();
+ }
+
return (
<div className="flex flex-col gap-2" data-testid="runtime-choice">
- <div className="grid grid-cols-3 gap-2" role="radiogroup" aria-label={t("society.runtime.title")}>
+ <div className="grid grid-cols-3 gap-2" role="radiogroup" aria-label={t("society.runtime.title")}
+ aria-describedby={`${id}-hint`}>
{AGENT_RUNTIMES.map((runtime) => {
const label = t(`society.runtime.${runtime}`);
const state = runtime === "jarvis" ? null : setupState(byName.get(runtime));
+ const untested = state === "ready" && Boolean(byName.get(runtime)?.untested);
return (
<button
key={runtime}
+ ref={(node) => { cards.current[runtime] = node; }}
type="button"
role="radio"
aria-checked={value === runtime}
aria-label={label}
+ // The name stays the runtime; its setup state is read as the description.
+ aria-describedby={`${id}-state-${runtime}`}
+ tabIndex={value === runtime ? 0 : -1}
disabled={disabled}
onClick={() => onChange(runtime)}
+ onKeyDown={(event) => onKeyDown(event, runtime)}
className={cn(
- "flex flex-col items-start gap-1 rounded-lg border p-2.5 text-left transition-colors disabled:opacity-50",
+ "flex flex-col items-start gap-1 rounded-lg border p-2.5 text-left transition-colors disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
value === runtime
? "border-border-strong bg-secondary text-foreground"
: "border-border text-muted-foreground hover:bg-secondary",
@@ -154,13 +179,13 @@ export function RuntimeChoice({ value, onChange, disabled = false }: {
<RuntimeMark runtime={runtime} label={label} />
{label}
</span>
- <span className="inline-flex items-center gap-1 text-[11px] leading-snug">
+ <span id={`${id}-state-${runtime}`} className="inline-flex items-center gap-1 text-[11px] leading-snug">
{state === "setting_up" ? <Loader2 className="size-3 animate-spin" aria-hidden /> : null}
{t(
state === null
? "society.runtime.built_in"
: state === "ready"
- ? "society.runtime.ready"
+ ? untested ? "society.runtime.ready_untested" : "society.runtime.ready"
: state === "setting_up"
? "society.runtime.setting_up"
: "society.runtime.auto_setup",
@@ -170,7 +195,7 @@ export function RuntimeChoice({ value, onChange, disabled = false }: {
);
})}
</div>
- <p className="text-xs text-muted-foreground">{t(`society.runtime.${value}_hint`)}</p>
+ <p id={`${id}-hint`} className="text-xs text-muted-foreground">{t(`society.runtime.${value}_hint`)}</p>
{value !== "jarvis" ? (
<RuntimeSetupNote status={chosen} error={error} onRetry={() => void ensure(value)} />
) : null}
diff --git a/jarvis/ui/web/frontend/src/components/society/chat/AgentChatPanel.tsx b/jarvis/ui/web/frontend/src/components/society/chat/AgentChatPanel.tsx
index 41bf51a1de..b87e7ee327 100644
--- a/jarvis/ui/web/frontend/src/components/society/chat/AgentChatPanel.tsx
+++ b/jarvis/ui/web/frontend/src/components/society/chat/AgentChatPanel.tsx
@@ -60,7 +60,8 @@ import {
type TurnItem,
type UserItem,
} from "@/components/agentchat/reduce";
-import { TurnTrace } from "@/components/agentchat/WorkTrace";
+import { ThreadTurn } from "@/components/agentic/threads/ThreadTimeline";
+import { formatTokens, outputTokens } from "@/components/agentchat/toolView";
import { VoiceStage } from "@/components/home/VoiceStage";
import { ProviderLogo } from "@/components/providers/ProviderLogo";
import { useT } from "@/i18n";
@@ -770,7 +771,7 @@ function TimeStamp({ ms }: { ms: number }) {
* summary underneath, muted — it is the society reporting, not Jarvis
* speaking, so it never wears an assistant bubble.
*/
-function NoticeLine({ item }: { item: NoticeItem }) {
+export function NoticeLine({ item }: { item: NoticeItem }) {
const t = useT();
if (item.kind === "memory_updated") return <MemoryUpdateNotice item={item} />;
if (item.kind === "message_queued") {
@@ -792,6 +793,20 @@ function NoticeLine({ item }: { item: NoticeItem }) {
{runtime ? t("society.runtime.setting_up_chat").replace("{0}", t(`society.runtime.${runtime}`)) : item.text}
</p>;
}
+ if (item.kind === "stop_reason") {
+ // A runtime turn that ended early: the answer above stands, but is cut off.
+ const reason = String(item.data.stop_reason ?? "");
+ const known = ["max_tokens", "max_turn_requests", "cancelled"].includes(reason);
+ return <p role="note" className="py-1 text-xs italic text-muted-foreground" data-testid="stop-reason-notice">
+ {known ? t(`society.chat.stop_reason_${reason}`) : item.text}
+ </p>;
+ }
+ if (item.kind === "routine_runtime_fallback") {
+ const runtime = String(item.data.runtime ?? "");
+ return <p className="py-1 text-center text-[11px] text-muted-foreground" data-testid="routine-runtime-fallback">
+ {runtime ? t("society.runtime.routine_fallback").replace(/\{0\}/g, t(`society.runtime.${runtime}`)) : item.text}
+ </p>;
+ }
if (item.kind === "routine_run") {
const sessionId = String(item.data.session_id ?? "");
const agentId = item.agentId || String(item.data.agent_id ?? "");
@@ -1037,11 +1052,20 @@ function TurnBubble({
memory?: NoticeItem[];
onDecide: (approvalId: string, decision: ApprovalDecision) => Promise<void>;
}) {
+ const t = useT();
const extras = useMemo(
() => memory?.map((notice) => ({ key: notice.id, node: <MemoryUpdateNotice item={notice} inTrace /> })),
[memory],
);
- return <TurnTrace turn={item} conversation extras={extras} onDecide={onDecide} renderText={(text) => <Prose text={text} />} />;
+ // What the turn spent: output tokens only (BUG-173), and the cost when billed.
+ const tokens = outputTokens(item.usage ?? item.liveUsage);
+ const spent = [
+ tokens !== null && tokens > 0 ? `${formatTokens(tokens)} ${t("agent_chat.tokens")}` : "",
+ item.costUsd !== null && item.costUsd > 0 ? `$${item.costUsd.toFixed(4)}` : "",
+ ].filter(Boolean).join(" · ");
+ // An agent's turn reads exactly like a coding thread's turn in the Agentic
+ // IDE; only its questions and approvals are answered in place.
+ return <ThreadTurn turn={item} prompts="inline" onDecide={onDecide} extras={extras} receipt={spent || undefined} />;
}
/**
diff --git a/jarvis/ui/web/frontend/src/components/society/chat/AgentModelPicker.tsx b/jarvis/ui/web/frontend/src/components/society/chat/AgentModelPicker.tsx
index 76af358b5e..4a1b063485 100644
--- a/jarvis/ui/web/frontend/src/components/society/chat/AgentModelPicker.tsx
+++ b/jarvis/ui/web/frontend/src/components/society/chat/AgentModelPicker.tsx
@@ -9,10 +9,11 @@ import { useT } from "@/i18n";
import type { CuratedModel } from "@/lib/agentChatApi";
import { cn } from "@/lib/utils";
import { effortsFor, type BrainSeat } from "../create/brainPicker";
-import { useUpdateAgentModel, type SocietyAgent } from "../data";
+import { RuntimeProviderUnsupported, useUpdateAgentModel, type SocietyAgent } from "../data";
import { rankModels } from "@/lib/modelRanking";
import { orderBy, useProviderOrder } from "@/lib/providerOrder";
-import { collapsibleModels, matchesModel, modelEffort, modelGroupOrder, modelSeats, providerTitle, runtimeSeats, visibleModels } from "./modelChoices";
+import { collapsibleModels, matchesModel, modelEffort, modelGroupOrder, modelSeats, providerTitle, runtimeSeats, seatBlocked, visibleModels } from "./modelChoices";
+import { blockedReasonKey } from "../create/seatChoice";
import { useModelMenuData } from "./useModelMenuData";
import { RuntimeStatusRow, useAgentRuntimes } from "../card/RuntimePicker";
@@ -73,6 +74,9 @@ export function AgentModelPicker({ agent, busy, onSavingChange }: {
return runtimeSeats(all, list(supportedKey), list(gatewayKey), list(loginKey));
}, [options, providers, live, defaultModelLabel, external, supportedKey, gatewayKey, loginKey]);
const currentAccount = (seat: BrainSeat) => accounts[seat.provider.id] ?? (agent.provider === seat.provider.id ? agent.accountId ?? "" : "");
+ // A seat the provider refuses right now (Claude's login with Extra Usage off)
+ // stays visible with its reason; its models cannot be picked.
+ const blockedFor = (seat: BrainSeat) => external ? seatBlocked(seat, runtimes.data?.access_blocked, currentAccount(seat)) : "";
const preferredEffort = (seat: BrainSeat, model: CuratedModel) => modelEffort(seat, model.id, seat.provider.id === agent.provider ? agent.effort : seat.provider.default_effort);
// useT returns a new function each render; memoize by its actual labels.
const titleKey = JSON.stringify(seats.map((seat) => providerTitle(seat, t)));
@@ -186,7 +190,9 @@ export function AgentModelPicker({ agent, busy, onSavingChange }: {
await update(agent.agentId, { provider: seat.provider.id, model: model.id, effort, account_id: currentAccount(seat) });
setOpen(false); setSubmenu(null); trigger.current?.focus();
} catch (err) {
- setError(`${t("society.chat.model_save_failed")} (${err instanceof Error ? err.message : String(err)})`);
+ setError(err instanceof RuntimeProviderUnsupported
+ ? t("society.runtime.provider_unsupported")
+ : `${t("society.chat.model_save_failed")} (${err instanceof Error ? err.message : String(err)})`);
} finally {
inFlight.current = false; setSaving(false); onSavingChange(false);
}
@@ -227,7 +233,7 @@ export function AgentModelPicker({ agent, busy, onSavingChange }: {
const isFavorite = favorites.includes(value);
const starLabel = t(isFavorite ? "agent_chat.favorite_remove" : "agent_chat.favorite_add");
return <div key={value} className={cn("group flex items-center", selected && "bg-secondary/70")}>
- <button type="button" role="menuitemradio" aria-checked={selected} disabled={busy || saving} data-menu-choice
+ <button type="button" role="menuitemradio" aria-checked={selected} disabled={busy || saving || Boolean(blockedFor(seat))} data-menu-choice
onKeyDown={(event) => {
if (event.key === "ArrowRight" && effortsFor(seat, model.id).length) {
event.preventDefault(); event.stopPropagation();
@@ -332,6 +338,9 @@ export function AgentModelPicker({ agent, busy, onSavingChange }: {
<Users className="h-3 w-3 shrink-0" aria-hidden /><span className="truncate">{seat.accounts.find((account) => account.id === currentAccount(seat))?.label ?? t("society.chat.model_active_account")}</span><ChevronDown className="h-2.5 w-2.5 shrink-0" aria-hidden />
</button> : null}
</div>
+ {blockedFor(seat) ? <p role="note" className="px-3 pb-1 text-xs text-warning" data-testid={`agent-model-blocked-${seat.provider.id}`}>
+ {t(blockedReasonKey(blockedFor(seat)))}
+ </p> : null}
<div id={choicesId}>
{lineup.map(toRow)}
{folded.length ? <button type="button" data-menu-choice disabled={busy || saving} aria-expanded={olderOpen} onClick={toggleOlder}
diff --git a/jarvis/ui/web/frontend/src/components/society/chat/MemoryUpdateNotice.tsx b/jarvis/ui/web/frontend/src/components/society/chat/MemoryUpdateNotice.tsx
index 26df5972d2..09c1057163 100644
--- a/jarvis/ui/web/frontend/src/components/society/chat/MemoryUpdateNotice.tsx
+++ b/jarvis/ui/web/frontend/src/components/society/chat/MemoryUpdateNotice.tsx
@@ -7,8 +7,8 @@ const MemoryFileViewer = lazy(() => import("./MemoryFileViewer").then(module =>
/**
* The "Memory updated" receipt. Inside a turn (`inTrace`) it is one quiet
- * step of the reasoning trace, drawn like a tool row; standalone (no turn
- * before it) it keeps the centred chip.
+ * step of the turn's work, drawn like a work-log row of a thread; standalone
+ * (no turn before it) it keeps the centred chip.
*/
export function MemoryUpdateNotice({ item, inTrace = false }: { item: NoticeItem; inTrace?: boolean }) {
const t = useT();
@@ -21,10 +21,10 @@ export function MemoryUpdateNotice({ item, inTrace = false }: { item: NoticeItem
const label = `${t("society.chat.memory_updated")} · ${path.split("/").at(-1)}`;
return <>
{inTrace ? (
- <button type="button" onClick={() => setOpen(true)} data-trace-memory={item.id} className="group/trace flex w-full min-w-0 items-start gap-3 rounded-md py-1 text-left text-sm leading-6 text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
- <span aria-hidden className="trace-node"><FilePenLine className="h-3.5 w-3.5 shrink-0" /></span>
- <span className="min-w-0 flex-1 truncate text-foreground-secondary">{label}</span>
- <ChevronRight aria-hidden className="mt-[5px] h-3.5 w-3.5 shrink-0 opacity-40 transition group-hover/trace:opacity-90" />
+ <button type="button" onClick={() => setOpen(true)} data-trace-memory={item.id} className="group/row flex min-h-6 w-full min-w-0 items-center gap-2.5 rounded-md py-1.5 text-left text-base leading-6 text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring">
+ <span aria-hidden className="flex h-6 w-4 shrink-0 items-center justify-center"><FilePenLine className="h-4 w-4" strokeWidth={1.75} /></span>
+ <span className="min-w-0 truncate transition-colors group-hover/row:text-foreground">{label}</span>
+ <ChevronRight aria-hidden className="h-3.5 w-3.5 shrink-0 opacity-0 transition duration-200 group-hover/row:opacity-70 group-focus-visible/row:opacity-70" />
</button>
) : (
<button type="button" onClick={() => setOpen(true)} className="mx-auto my-3 flex max-w-[min(100%,36rem)] select-none items-center gap-2 rounded-lg bg-secondary px-3 py-2 text-left text-xs text-foreground hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
diff --git a/jarvis/ui/web/frontend/src/components/society/chat/RuntimeNotices.test.tsx b/jarvis/ui/web/frontend/src/components/society/chat/RuntimeNotices.test.tsx
new file mode 100644
index 0000000000..959b7b0a40
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/society/chat/RuntimeNotices.test.tsx
@@ -0,0 +1,37 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+
+import type { NoticeItem } from "@/components/agentchat/reduce";
+import { NoticeLine } from "./AgentChatPanel";
+
+vi.mock("@/i18n", () => ({ useT: () => (key: string) => key, fill: (text: string) => text }));
+afterEach(cleanup);
+
+function notice(kind: string, data: Record<string, unknown>, text = "English from the runtime"): NoticeItem {
+ return {
+ type: "notice", id: "n1", kind, text, agentName: "", agentId: "", status: "", tsMs: 1, resolved: "",
+ data: { kind, ...data },
+ };
+}
+
+it("says in the person's language that a runtime answer was cut off", () => {
+ render(<NoticeLine item={notice("stop_reason", { stop_reason: "max_tokens", turn_id: "t1" })} />);
+ const line = screen.getByTestId("stop-reason-notice");
+ expect(line.textContent).toBe("society.chat.stop_reason_max_tokens");
+ expect(line.getAttribute("role")).toBe("note");
+});
+
+it("falls back to the runtime's sentence for a stop reason it does not know", () => {
+ render(<NoticeLine item={notice("stop_reason", { stop_reason: "something_new" })} />);
+ expect(screen.getByTestId("stop-reason-notice").textContent).toBe("English from the runtime");
+});
+
+it("names the runtime a routine run did not use", () => {
+ render(<NoticeLine item={notice("routine_runtime_fallback", { runtime: "hermes" })} />);
+ expect(screen.getByTestId("routine-runtime-fallback").textContent).toBe("society.runtime.routine_fallback");
+});
+
+it("announces a runtime setup, the one-time Hermes prepare included", () => {
+ render(<NoticeLine item={notice("runtime_setup", { runtime: "hermes", turn_id: "t1" })} />);
+ expect(screen.getByTestId("runtime-setup-notice").textContent).toBe("society.runtime.setting_up_chat");
+});
diff --git a/jarvis/ui/web/frontend/src/components/society/chat/modelChoices.test.ts b/jarvis/ui/web/frontend/src/components/society/chat/modelChoices.test.ts
index 6c730925e0..7e8134c359 100644
--- a/jarvis/ui/web/frontend/src/components/society/chat/modelChoices.test.ts
+++ b/jarvis/ui/web/frontend/src/components/society/chat/modelChoices.test.ts
@@ -1,7 +1,7 @@
import { expect, test } from "vitest";
import type { ProviderOption } from "@/store/agentChat";
import type { SocietyProviderRow } from "@/lib/societyApi";
-import { isFreeOpenCodeModel, modelEffort, modelSeats, visibleModels } from "./modelChoices";
+import { isFreeOpenCodeModel, modelEffort, modelSeats, seatBlocked, visibleModels } from "./modelChoices";
const option = (overrides: Partial<ProviderOption> = {}): ProviderOption => ({
id: "cli", label: "CLI", family: "cli", runner: "grok-cli", connected: false,
@@ -56,3 +56,13 @@ test("the default model never authorizes a disconnected, missing, or API seat",
const [seat] = modelSeats([option({ runner: "api", cli_installed: null, connected: true, curated_models: [] })], [], {});
expect(seat.provider.curated_models).toEqual([]);
});
+
+test("a Claude login seat is blocked while the backend refuses it, an API seat is not", () => {
+ const blocked = { "claude-api": { subscription: "extra_usage_off" } };
+ const [login] = modelSeats([option({ id: "claude-api", family: "claude", runner: "brain", connected: true })], [], {});
+ expect(seatBlocked({ ...login, extraUsage: true }, blocked)).toBe("extra_usage_off");
+ expect(seatBlocked({ ...login, kind: "api", extraUsage: false }, blocked)).toBe("");
+ // An agent pinned to the subscription pays by login even where an API key exists.
+ expect(seatBlocked({ ...login, kind: "api", extraUsage: false }, blocked, "subscription")).toBe("extra_usage_off");
+ expect(seatBlocked({ ...login, extraUsage: true }, undefined)).toBe("");
+});
diff --git a/jarvis/ui/web/frontend/src/components/society/chat/modelChoices.ts b/jarvis/ui/web/frontend/src/components/society/chat/modelChoices.ts
index 08afe2a611..21036319f6 100644
--- a/jarvis/ui/web/frontend/src/components/society/chat/modelChoices.ts
+++ b/jarvis/ui/web/frontend/src/components/society/chat/modelChoices.ts
@@ -78,6 +78,24 @@ export function runtimeSeats(
} : seat);
}
+/**
+ * Why a Hermes / OpenClaw seat cannot answer right now ("" when it can): the
+ * provider refuses the way this seat pays (`/api/agent-runtimes` →
+ * `access_blocked`). Claude's login is refused while its Extra Usage is off;
+ * the seat pays that way when it is the login seat (`extraUsage`) or the
+ * agent is pinned to its subscription (`account_id` "subscription").
+ */
+export function seatBlocked(
+ seat: BrainSeat,
+ blocked: Record<string, Record<string, string>> | undefined,
+ pinnedAccount = "",
+): string {
+ const refused = blocked?.[seat.provider.id];
+ if (!refused || typeof refused !== "object") return "";
+ const way = seat.extraUsage || pinnedAccount === "subscription" ? "subscription" : seat.kind;
+ return typeof refused[way] === "string" ? refused[way] : "";
+}
+
/** A CLI catalog narrowed to real model ids: its aliases mean nothing to an API. */
export function apiModels(models: CuratedModel[]): CuratedModel[] {
return models.filter((model) => /\d/.test(model.id));
diff --git a/jarvis/ui/web/frontend/src/components/society/create/AccessChoice.tsx b/jarvis/ui/web/frontend/src/components/society/create/AccessChoice.tsx
new file mode 100644
index 0000000000..7415612e3a
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/society/create/AccessChoice.tsx
@@ -0,0 +1,85 @@
+/**
+ * "How it pays" in the New-agent dialog: subscription, API key or local, as
+ * one radio group. Arrow keys move the choice (one tab stop, the WAI-ARIA
+ * radio pattern); an access the provider refuses right now (`blocked`) is
+ * shown disabled with its reason, so the person learns why before the first
+ * message would fail.
+ */
+import { useId, useRef, type KeyboardEvent } from "react";
+import { useT } from "@/i18n";
+import { cn } from "@/lib/utils";
+import { blockedReasonKey, type AccessOption } from "./seatChoice";
+
+export function AccessChoice({ options, value, hint, disabled, onChange }: {
+ options: AccessOption[];
+ /** The picked kind; "" when no access can be picked. */
+ value: string;
+ /** The sentence under the group that explains the picked access. */
+ hint: string;
+ disabled: boolean;
+ onChange: (kind: string) => void;
+}) {
+ const t = useT();
+ const id = useId();
+ const buttons = useRef<(HTMLButtonElement | null)[]>([]);
+ const open = options.filter((option) => !option.blocked);
+ const focusKind = open.some((option) => option.kind === value) ? value : open[0]?.kind ?? "";
+
+ function onKeyDown(event: KeyboardEvent<HTMLButtonElement>, kind: string) {
+ const step = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 }[event.key];
+ if (!step || open.length < 2) return;
+ event.preventDefault();
+ const index = open.findIndex((option) => option.kind === kind);
+ const next = open[(index + step + open.length) % open.length];
+ onChange(next.kind);
+ buttons.current[options.indexOf(next)]?.focus();
+ }
+
+ return (
+ <div className="flex flex-col gap-1.5 text-sm">
+ <span className="font-medium" id={`${id}-label`}>{t("society.create_agent.access_label")}</span>
+ <div
+ className="flex gap-1 rounded-lg border border-border p-1"
+ role="radiogroup"
+ aria-labelledby={`${id}-label`}
+ aria-describedby={hint ? `${id}-hint` : undefined}
+ data-testid="create-agent-access"
+ >
+ {options.map((entry, index) => {
+ const checked = entry.kind === value && !entry.blocked;
+ return (
+ <button
+ key={entry.kind}
+ ref={(node) => { buttons.current[index] = node; }}
+ type="button"
+ role="radio"
+ aria-checked={checked}
+ aria-describedby={entry.blocked ? `${id}-blocked-${entry.kind}` : undefined}
+ tabIndex={entry.kind === focusKind && !entry.blocked ? 0 : -1}
+ disabled={disabled || Boolean(entry.blocked)}
+ onClick={() => onChange(entry.kind)}
+ onKeyDown={(event) => onKeyDown(event, entry.kind)}
+ className={cn(
+ "min-w-0 flex-1 truncate rounded-md px-3 py-1.5 text-sm transition-colors disabled:opacity-50",
+ "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+ checked
+ ? "bg-secondary text-foreground"
+ : "text-muted-foreground hover:bg-secondary hover:text-foreground",
+ entry.blocked && "line-through hover:bg-transparent hover:text-muted-foreground",
+ )}
+ >
+ {t(`society.create.kind_${entry.kind}`)}
+ </button>
+ );
+ })}
+ </div>
+ {hint ? <p id={`${id}-hint`} className="text-xs text-muted-foreground">{hint}</p> : null}
+ {options.filter((entry) => entry.blocked).map((entry) => (
+ <p key={entry.kind} id={`${id}-blocked-${entry.kind}`} role="note" className="text-xs text-warning"
+ data-testid={`create-agent-access-blocked-${entry.kind}`}>
+ {t(blockedReasonKey(entry.blocked ?? ""))}
+ </p>
+ ))}
+ </div>
+ );
+}
diff --git a/jarvis/ui/web/frontend/src/components/society/create/CreateAgentDialog.test.tsx b/jarvis/ui/web/frontend/src/components/society/create/CreateAgentDialog.test.tsx
index c668689b6f..f5de6f70dc 100644
--- a/jarvis/ui/web/frontend/src/components/society/create/CreateAgentDialog.test.tsx
+++ b/jarvis/ui/web/frontend/src/components/society/create/CreateAgentDialog.test.tsx
@@ -18,7 +18,8 @@ const { createAgent, ensureRuntime, runtimes, menu } = vi.hoisted(() => ({
}));
vi.mock("../data", async () => {
class AgentNameTaken extends Error {}
- return { AgentNameTaken, useCreateSocietyAgent: () => createAgent };
+ class RuntimeProviderUnsupported extends Error {}
+ return { AgentNameTaken, RuntimeProviderUnsupported, useCreateSocietyAgent: () => createAgent };
});
vi.mock("../chat/useModelMenuData", () => ({
useModelMenuData: () => ({
@@ -124,6 +125,77 @@ describe("CreateAgentDialog", () => {
});
});
+ test("a Claude login Anthropic refuses is shown with its reason and the API key is used", async () => {
+ runtimes.value = {
+ ...READY,
+ supported_providers: ["claude-api", "openai"],
+ login_providers: ["claude-api"],
+ access: { "claude-api": ["api", "subscription"] },
+ access_blocked: { "claude-api": { subscription: "extra_usage_off" } },
+ };
+ menu.options = [CLAUDE];
+ createAgent.mockResolvedValue({ agentId: "agent-6" });
+ mount();
+ act(() => { useCreateAgentDialog.getState().request().catch(() => undefined); });
+ fireEvent.click(await screen.findByRole("radio", { name: "society.runtime.hermes" }));
+ const subscription = await screen.findByRole("radio", { name: "society.create.kind_subscription" });
+ await waitFor(() => expect((subscription as HTMLButtonElement).disabled).toBe(true));
+ expect(subscription.getAttribute("aria-checked")).toBe("false");
+ const reason = screen.getByTestId("create-agent-access-blocked-subscription");
+ expect(reason.textContent).toBe("society.create_agent.access_blocked_extra_usage_off");
+ expect(subscription.getAttribute("aria-describedby")).toBe(reason.id);
+ expect(screen.getByRole("radio", { name: "society.create.kind_api" }).getAttribute("aria-checked")).toBe("true");
+ fireEvent.click(screen.getByTestId("create-agent-submit"));
+ await waitFor(() => expect(createAgent).toHaveBeenCalled());
+ expect(createAgent.mock.calls[0][0]).toMatchObject({ runtime: "hermes", provider: "claude-api", accountId: "api-key" });
+ });
+
+ test("with only a refused Claude login the agent cannot be created, and the reason is shown", async () => {
+ runtimes.value = {
+ ...READY,
+ supported_providers: ["claude-api"],
+ login_providers: ["claude-api"],
+ access: { "claude-api": ["subscription"] },
+ access_blocked: { "claude-api": { subscription: "extra_usage_spent" } },
+ };
+ menu.options = [CLAUDE];
+ mount();
+ act(() => { useCreateAgentDialog.getState().request().catch(() => undefined); });
+ fireEvent.click(await screen.findByRole("radio", { name: "society.runtime.hermes" }));
+ expect((await screen.findByTestId("create-agent-access-blocked-subscription")).textContent)
+ .toBe("society.create_agent.access_blocked_extra_usage_spent");
+ expect((screen.getByTestId("create-agent-submit") as HTMLButtonElement).disabled).toBe(true);
+ expect(screen.queryByTestId("create-agent-model")).toBeNull();
+ });
+
+ test("arrow keys move the access choice and only one radio is a tab stop", async () => {
+ runtimes.value = { ...READY, access: { "claude-api": ["api", "subscription"] } };
+ menu.options = [CLAUDE, OPENAI];
+ mount();
+ act(() => { useCreateAgentDialog.getState().request().catch(() => undefined); });
+ const subscription = await screen.findByRole("radio", { name: "society.create.kind_subscription" });
+ await waitFor(() => expect(subscription.getAttribute("aria-checked")).toBe("true"));
+ const api = await screen.findByRole("radio", { name: "society.create.kind_api" });
+ await waitFor(() => expect(subscription.getAttribute("aria-checked")).toBe("true"));
+ expect([subscription.tabIndex, api.tabIndex]).toEqual([0, -1]);
+ fireEvent.keyDown(subscription, { key: "ArrowRight" });
+ await waitFor(() => expect(api.getAttribute("aria-checked")).toBe("true"));
+ expect(document.activeElement).toBe(api);
+ expect([subscription.tabIndex, api.tabIndex]).toEqual([-1, 0]);
+ expect(screen.getByTestId("create-agent-access").getAttribute("aria-describedby")).toBeTruthy();
+ });
+
+ test("a provider Hermes cannot drive is explained in the person's language", async () => {
+ const { RuntimeProviderUnsupported } = await import("../data");
+ createAgent.mockRejectedValue(new RuntimeProviderUnsupported("Hermes and OpenClaw run on ..."));
+ mount();
+ act(() => { useCreateAgentDialog.getState().request().catch(() => undefined); });
+ fireEvent.click(await screen.findByRole("radio", { name: "society.runtime.hermes" }));
+ await screen.findByTestId("create-agent-provider");
+ fireEvent.click(screen.getByTestId("create-agent-submit"));
+ expect(await screen.findByText("society.runtime.provider_unsupported")).toBeTruthy();
+ });
+
test("a Jarvis agent with nothing connected still starts on the chat's seat", async () => {
menu.options = [];
createAgent.mockResolvedValue({ agentId: "agent-5" });
diff --git a/jarvis/ui/web/frontend/src/components/society/create/CreateAgentDialog.tsx b/jarvis/ui/web/frontend/src/components/society/create/CreateAgentDialog.tsx
index 461b865840..1b375087f0 100644
--- a/jarvis/ui/web/frontend/src/components/society/create/CreateAgentDialog.tsx
+++ b/jarvis/ui/web/frontend/src/components/society/create/CreateAgentDialog.tsx
@@ -17,15 +17,15 @@ import { AgentMark } from "@/components/agentic/AgentMark";
import { ProviderLogo } from "@/components/providers/ProviderLogo";
import { useT } from "@/i18n";
import type { AgentRuntime } from "@/lib/societyApi";
-import { cn } from "@/lib/utils";
-import { AgentNameTaken, useCreateSocietyAgent } from "../data";
+import { AgentNameTaken, RuntimeProviderUnsupported, useCreateSocietyAgent } from "../data";
import { defaultCompanion, type CompanionAppearance } from "../companion/appearance";
import { RuntimeChoice, useAgentRuntimes } from "../card/RuntimePicker";
import { modelSeats, runtimeSeats } from "../chat/modelChoices";
import { useModelMenuData } from "../chat/useModelMenuData";
import { accountChoice, accountHint } from "./brainPicker";
import { useCreateAgentDialog } from "./createAgentStore";
-import { accessModels, defaultModel, providerChoices, type AccessOption } from "./seatChoice";
+import { AccessChoice } from "./AccessChoice";
+import { accessModels, defaultModel, pickableOption, providerChoices, type AccessBlocked, type AccessOption } from "./seatChoice";
const CompanionEditor = lazy(() =>
import("../companion/CompanionEditor").then((m) => ({ default: m.CompanionEditor })),
@@ -71,17 +71,21 @@ function CreateAgentDialog() {
const gatewayKey = list(data?.subscription_providers).join(",");
const loginKey = list(data?.login_providers).join(",");
const accessKey = JSON.stringify(data?.access && typeof data.access === "object" ? data.access : {});
+ // Refusals only concern Hermes / OpenClaw (Claude's login billed as Extra Usage).
+ const blockedKey = JSON.stringify(external && data?.access_blocked && typeof data.access_blocked === "object" ? data.access_blocked : {});
const choices = useMemo(() => {
const all = modelSeats(menu.options, Array.isArray(menu.providers) ? menu.providers : [], menu.live, defaultModelLabel);
const split = (key: string) => key.split(",").filter(Boolean);
const seats = external ? runtimeSeats(all, split(supportedKey), split(gatewayKey), split(loginKey)) : all;
- return providerChoices(seats, JSON.parse(accessKey) as Record<string, string[]>, external);
- }, [menu.options, menu.providers, menu.live, defaultModelLabel, external, supportedKey, gatewayKey, loginKey, accessKey]);
+ return providerChoices(seats, JSON.parse(accessKey) as Record<string, string[]>, external, JSON.parse(blockedKey) as AccessBlocked);
+ }, [menu.options, menu.providers, menu.live, defaultModelLabel, external, supportedKey, gatewayKey, loginKey, accessKey, blockedKey]);
// The person's picks stay while they are offered; a pick that disappears (a
// key removed, another runtime chosen) falls back to the first one left.
- const chosen = choices.find((choice) => choice.id === providerId) ?? choices[0] ?? null;
- const option: AccessOption | null = chosen?.options.find((entry) => entry.kind === kind) ?? chosen?.options[0] ?? null;
+ const chosen = choices.find((choice) => choice.id === providerId)
+ ?? choices.find((choice) => pickableOption(choice)) ?? choices[0] ?? null;
+ // A refused access is listed with its reason but never picked.
+ const option: AccessOption | null = pickableOption(chosen, kind);
const models = accessModels(option);
const accounts = accountChoice(option?.seat ?? null);
const modelValue = models.some((entry) => entry.id === model) ? model : defaultModel(option);
@@ -116,7 +120,9 @@ function CreateAgentDialog() {
setError(
exc instanceof AgentNameTaken
? t("society.create_agent.name_taken")
- : exc instanceof Error ? exc.message : String(exc),
+ : exc instanceof RuntimeProviderUnsupported
+ ? t("society.runtime.provider_unsupported")
+ : exc instanceof Error ? exc.message : String(exc),
);
setSaving(false);
}
@@ -167,7 +173,7 @@ function CreateAgentDialog() {
<div className="flex flex-col gap-1.5 text-sm">
<span className="font-medium">{t("society.create_agent.provider_label")}</span>
- {chosen && option ? (
+ {chosen ? (
<BrandedSelect
value={chosen.id}
onValueChange={(next) => { setProviderId(next); setKind(""); setAccount(""); }}
@@ -192,38 +198,14 @@ function CreateAgentDialog() {
)}
</div>
- {chosen && option ? (
- <div className="flex flex-col gap-1.5 text-sm">
- <span className="font-medium">{t("society.create_agent.access_label")}</span>
- <div
- className="flex gap-1 rounded-lg border border-border p-1"
- role="radiogroup"
- aria-label={t("society.create_agent.access_label")}
- data-testid="create-agent-access"
- >
- {chosen.options.map((entry) => (
- <button
- key={entry.kind}
- type="button"
- role="radio"
- aria-checked={entry.kind === option.kind}
- disabled={saving}
- onClick={() => { setKind(entry.kind); setAccount(""); }}
- className={cn(
- "min-w-0 flex-1 truncate rounded-md px-3 py-1.5 text-sm transition-colors disabled:opacity-50",
- entry.kind === option.kind
- ? "bg-secondary text-foreground"
- : "text-muted-foreground hover:bg-secondary hover:text-foreground",
- )}
- >
- {t(`society.create.kind_${entry.kind}`)}
- </button>
- ))}
- </div>
- <p className="text-xs text-muted-foreground">
- {t(option.extraUsage ? "society.create_agent.access_extra_usage" : `society.create_agent.access_hint_${option.kind}`)}
- </p>
- </div>
+ {chosen ? (
+ <AccessChoice
+ options={chosen.options}
+ value={option?.kind ?? ""}
+ hint={option ? t(option.extraUsage ? "society.create_agent.access_extra_usage" : `society.create_agent.access_hint_${option.kind}`) : ""}
+ disabled={saving}
+ onChange={(next) => { setKind(next); setAccount(""); }}
+ />
) : null}
{chosen && option && accounts.length ? (
diff --git a/jarvis/ui/web/frontend/src/components/society/create/seatChoice.test.ts b/jarvis/ui/web/frontend/src/components/society/create/seatChoice.test.ts
index b818e45111..ba95a498f5 100644
--- a/jarvis/ui/web/frontend/src/components/society/create/seatChoice.test.ts
+++ b/jarvis/ui/web/frontend/src/components/society/create/seatChoice.test.ts
@@ -8,7 +8,9 @@ import type { BrainSeat } from "./brainPicker";
import {
accessModels,
API_KEY_ACCOUNT,
+ blockedReasonKey,
defaultModel,
+ pickableOption,
providerChoices,
SUBSCRIPTION_ACCOUNT,
} from "./seatChoice";
@@ -94,6 +96,49 @@ describe("providerChoices", () => {
it("lists providers with a subscription before key-only and local ones", () => {
expect(providerChoices([ollama, openai, claude]).map((c) => c.id)).toEqual(["claude", "openai", "ollama"]);
});
+
+ it("shows a refused Claude login with its reason but never picks it", () => {
+ const seats = runtimeSeats([claude, openai], ["claude-api", "openai"], [], ["claude-api"]);
+ const choices = providerChoices(
+ seats, { "claude-api": ["api", "subscription"] }, true,
+ { "claude-api": { subscription: "extra_usage_off" } },
+ );
+ const claudeChoice = choices.find((c) => c.id === "claude")!;
+ expect(claudeChoice.options.map((o) => [o.kind, o.blocked ?? ""])).toEqual([
+ ["subscription", "extra_usage_off"],
+ ["api", ""],
+ ]);
+ expect(pickableOption(claudeChoice, "subscription")?.kind).toBe("api");
+ });
+
+ it("lists a refused access the backend no longer names as working", () => {
+ const seats = runtimeSeats([claude], ["claude-api"], [], ["claude-api"]);
+ const [choice] = providerChoices(seats, {}, true, { "claude-api": { subscription: "extra_usage_spent" } });
+ expect(choice.options.map((o) => [o.kind, o.blocked])).toEqual([["subscription", "extra_usage_spent"]]);
+ expect(pickableOption(choice)).toBeNull();
+ });
+
+ it("sorts a provider whose every access is refused last", () => {
+ const seats = runtimeSeats([claude, openai], ["claude-api", "openai"], [], ["claude-api"]);
+ const order = providerChoices(seats, { "claude-api": ["subscription"] }, true, {
+ "claude-api": { subscription: "extra_usage_off" },
+ }).map((c) => c.id);
+ expect(order).toEqual(["openai", "claude"]);
+ });
+
+ it("tolerates a backend without access_blocked", () => {
+ const seats = runtimeSeats([claude], ["claude-api"], [], ["claude-api"]);
+ const [choice] = providerChoices(seats, { "claude-api": ["subscription"] }, true);
+ expect(choice.options.every((o) => !o.blocked)).toBe(true);
+ });
+});
+
+describe("blockedReasonKey", () => {
+ it("explains known refusals and falls back to a plain sentence", () => {
+ expect(blockedReasonKey("extra_usage_off")).toBe("society.create_agent.access_blocked_extra_usage_off");
+ expect(blockedReasonKey("extra_usage_spent")).toBe("society.create_agent.access_blocked_extra_usage_spent");
+ expect(blockedReasonKey("something_new")).toBe("society.create_agent.access_blocked");
+ });
});
describe("defaultModel", () => {
diff --git a/jarvis/ui/web/frontend/src/components/society/create/seatChoice.ts b/jarvis/ui/web/frontend/src/components/society/create/seatChoice.ts
index 87763cc8d9..5a9710c80c 100644
--- a/jarvis/ui/web/frontend/src/components/society/create/seatChoice.ts
+++ b/jarvis/ui/web/frontend/src/components/society/create/seatChoice.ts
@@ -12,7 +12,12 @@
* `account_id` (`jarvis/agent_chat/catalog.py` → `ACCESS_ACCOUNTS`).
*
* Only what is connected on this machine is listed (maintainer, 2026-09-02):
- * an access that does not work is not shown, never greyed out.
+ * an access that does not work is not shown, never greyed out. The one
+ * exception is an access the provider is known to refuse right now although
+ * it is connected (`access_blocked`: Claude's login on Hermes / OpenClaw
+ * while the account's Extra Usage is off or spent). It is listed with its
+ * reason and cannot be picked, so the person learns why before the first
+ * message fails.
*
* Pure: no fetch, no store, so it is unit-tested with plain rows.
*/
@@ -35,8 +40,14 @@ export interface AccessOption {
accountId: string;
/** Billed per use outside the plan (Claude on Hermes / OpenClaw). */
extraUsage: boolean;
+ /** Why the provider refuses this access right now (a refusal code such as
+ * `extra_usage_off`); a blocked access is shown but cannot be picked. */
+ blocked?: string;
}
+/** Per provider id and access kind, the refusal code (`/api/agent-runtimes`). */
+export type AccessBlocked = Record<string, Record<string, string>>;
+
export interface ProviderChoice {
id: string;
label: string;
@@ -67,9 +78,16 @@ function brandOf(seat: BrainSeat): string {
return SAME_BRAND[family] ?? family;
}
-function optionsFor(seat: BrainSeat, ways: readonly string[] | undefined, external: boolean): AccessOption[] {
+function optionsFor(
+ seat: BrainSeat,
+ named: readonly string[] | undefined,
+ external: boolean,
+ blocked: Record<string, string> = {},
+): AccessOption[] {
const single: AccessOption = { kind: seat.kind, seat, accountId: "", extraUsage: Boolean(seat.extraUsage) };
- if (!ways) return [single];
+ const refused = Object.keys(blocked).filter((way) => !named?.includes(way));
+ if (!named && !refused.length) return [single];
+ const ways = [...(named ?? []), ...refused];
// A dual row: the backend named the ways that work right now.
const viaKey: BrainSeat = {
...seat,
@@ -86,9 +104,28 @@ function optionsFor(seat: BrainSeat, ways: readonly string[] | undefined, extern
: { kind: "subscription", seat: { ...seat, kind: "subscription" }, accountId: SUBSCRIPTION_ACCOUNT, extraUsage: false });
}
if (ways.includes("api")) options.push({ kind: "api", seat: viaKey, accountId: API_KEY_ACCOUNT, extraUsage: false });
+ for (const option of options) {
+ if (blocked[option.kind]) option.blocked = blocked[option.kind];
+ }
return options.length ? options : [single];
}
+/** Refusal codes with their own explanation (`provider_errors.py`). */
+const BLOCKED_REASONS = new Set(["extra_usage_off", "extra_usage_spent"]);
+
+/** The i18n key that explains a blocked access in plain words. */
+export function blockedReasonKey(code: string): string {
+ return BLOCKED_REASONS.has(code)
+ ? `society.create_agent.access_blocked_${code}`
+ : "society.create_agent.access_blocked";
+}
+
+/** The access to use: ``kind`` when it can be picked, else the first that can. */
+export function pickableOption(choice: ProviderChoice | null, kind = ""): AccessOption | null {
+ const open = choice?.options.filter((option) => !option.blocked) ?? [];
+ return open.find((option) => option.kind === kind) ?? open[0] ?? null;
+}
+
/**
* The providers to offer, best access first: a provider with a subscription
* comes before one with only an API key (a plan already paid for beats a
@@ -98,6 +135,7 @@ export function providerChoices(
seats: BrainSeat[],
access: Record<string, readonly string[]> = {},
external = false,
+ accessBlocked: AccessBlocked = {},
): ProviderChoice[] {
const byBrand = new Map<string, ProviderChoice>();
for (const seat of seats) {
@@ -115,12 +153,15 @@ export function providerChoices(
};
byBrand.set(id, choice);
}
- for (const option of optionsFor(seat, access[seat.provider.id], external)) {
+ const blocked = accessBlocked[seat.provider.id];
+ for (const option of optionsFor(seat, access[seat.provider.id], external, blocked && typeof blocked === "object" ? blocked : {})) {
// One row per way of paying: the first seat of a kind wins.
if (!choice.options.some((known) => known.kind === option.kind)) choice.options.push(option);
}
}
- const best = (choice: ProviderChoice) => Math.min(...choice.options.map((option) => KIND_ORDER[option.kind]));
+ // A provider whose every access is refused right now sorts last.
+ const best = (choice: ProviderChoice) => Math.min(
+ ...choice.options.map((option) => (option.blocked ? 10 : 0) + KIND_ORDER[option.kind]));
return [...byBrand.values()]
.map((choice) => ({ ...choice, options: [...choice.options].sort((a, b) => KIND_ORDER[a.kind] - KIND_ORDER[b.kind]) }))
.sort((a, b) => best(a) - best(b) || a.label.localeCompare(b.label));
diff --git a/jarvis/ui/web/frontend/src/components/society/data.ts b/jarvis/ui/web/frontend/src/components/society/data.ts
index dc190a90ec..0cfb553fdf 100644
--- a/jarvis/ui/web/frontend/src/components/society/data.ts
+++ b/jarvis/ui/web/frontend/src/components/society/data.ts
@@ -36,6 +36,28 @@ export class AgentNameTaken extends Error {
}
}
+/** Hermes / OpenClaw cannot drive the chosen provider (422
+ * `runtime_provider_unsupported`); the UI shows its own translated sentence. */
+export class RuntimeProviderUnsupported extends Error {
+ constructor(detail: string) {
+ super(detail);
+ this.name = "RuntimeProviderUnsupported";
+ }
+}
+
+/** The error a failed society request stands for: a typed one when the
+ * backend names a reason the UI explains itself, else its detail text. */
+export function requestError(body: { detail?: unknown } | null, fallback: string): Error {
+ const reason = body?.detail;
+ if (typeof reason === "string") return new Error(reason);
+ if (reason && typeof reason === "object") {
+ const typed = reason as { reason?: unknown; detail?: unknown };
+ const text = typeof typed.detail === "string" ? typed.detail : fallback;
+ return typed.reason === "runtime_provider_unsupported" ? new RuntimeProviderUnsupported(text) : new Error(text);
+ }
+ return new Error(fallback);
+}
+
/** MASTERPLAN §2.5 — exactly one lead (Jarvis), orchestrators may ASSIGN. */
export type AgentTier = "lead" | "orchestrator" | "specialist";
@@ -431,15 +453,7 @@ export function useCreateSocietyAgent() {
body: JSON.stringify(body),
});
if (!res.ok) {
- const detail = (await res.json().catch(() => null)) as { detail?: unknown } | null;
- const reason = detail?.detail;
- throw new Error(
- typeof reason === "string"
- ? reason
- : reason && typeof reason === "object" && "detail" in reason
- ? String((reason as { detail: unknown }).detail)
- : `create ${res.status}`,
- );
+ throw requestError((await res.json().catch(() => null)) as { detail?: unknown } | null, `create ${res.status}`);
}
const created = (await res.json()) as { agent: SocietyAgentRow; created?: boolean };
if (created.created === false) throw new AgentNameTaken();
@@ -543,9 +557,8 @@ export function useUpdateAgentModel() {
body: JSON.stringify(choice),
});
if (!res.ok) {
- // A 422 explains itself ("Hermes and OpenClaw run on an API key…").
- const body = (await res.json().catch(() => null)) as { detail?: unknown } | null;
- throw new Error(typeof body?.detail === "string" ? body.detail : `HTTP ${res.status}`);
+ // A 422 explains itself; a runtime that cannot drive the provider is typed.
+ throw requestError((await res.json().catch(() => null)) as { detail?: unknown } | null, `HTTP ${res.status}`);
}
const body = await res.json() as { agent: SocietyAgentRow };
const updated = rowToAgent(body.agent);
diff --git a/jarvis/ui/web/frontend/src/components/society/requestError.test.ts b/jarvis/ui/web/frontend/src/components/society/requestError.test.ts
new file mode 100644
index 0000000000..7a6430588a
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/society/requestError.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { requestError, RuntimeProviderUnsupported } from "./data";
+
+describe("requestError", () => {
+ it("types a runtime that cannot drive the provider, so the UI can translate it", () => {
+ const error = requestError({ detail: { reason: "runtime_provider_unsupported", detail: "English text" } }, "HTTP 422");
+ expect(error).toBeInstanceOf(RuntimeProviderUnsupported);
+ expect(error.message).toBe("English text");
+ });
+
+ it("keeps a plain detail and falls back to the status", () => {
+ expect(requestError({ detail: "plain" }, "HTTP 422")).not.toBeInstanceOf(RuntimeProviderUnsupported);
+ expect(requestError({ detail: "plain" }, "HTTP 422").message).toBe("plain");
+ expect(requestError({ detail: { reason: "other" } }, "HTTP 409").message).toBe("HTTP 409");
+ expect(requestError(null, "create 500").message).toBe("create 500");
+ });
+});
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/de.json b/jarvis/ui/web/frontend/src/i18n/locales/de.json
index f4041eb402..3c18e1c90a 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/de.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/de.json
@@ -5649,6 +5649,9 @@
"coding_thread_author": "Geschrieben von {0}",
"message_not_sent": "Nicht gesendet: {0}",
"context_rollover": "Frischer Arbeitskontext – Gedächtnis und letzte Nachrichten übernommen",
+ "stop_reason_max_tokens": "Die Antwort endete am Ausgabelimit des Modells und ist vielleicht unvollständig.",
+ "stop_reason_max_turn_requests": "Der Agent hat sein Schrittlimit für einen Durchgang erreicht; die Arbeit ist vielleicht nicht fertig.",
+ "stop_reason_cancelled": "Der Durchgang wurde abgebrochen, bevor er fertig war.",
"allow_always": "Immer erlauben",
"history_chats": "Chats",
"history_voice": "Sprache",
@@ -5799,6 +5802,9 @@
"access_hint_api": "Wird pro Nutzung über deinen API-Schlüssel abgerechnet.",
"access_hint_local": "Läuft mit einem Modell auf diesem Computer — keine Kosten pro Nachricht.",
"access_extra_usage": "Läuft über deinen Claude-Code-Login. Anthropic rechnet das als Extra Usage ab, außerhalb der Limits deines Abos.",
+ "access_blocked": "Der Anbieter lehnt diese Zahlungsart gerade ab. Wähle eine andere.",
+ "access_blocked_extra_usage_off": "Nicht verfügbar: Extra Usage ist für dieses Claude-Konto ausgeschaltet, und Anthropic rechnet Hermes und OpenClaw nur als Extra Usage ab. Schalte es auf claude.ai unter Einstellungen → Nutzung ein oder nutze einen API-Schlüssel.",
+ "access_blocked_extra_usage_spent": "Nicht verfügbar: Das Extra-Usage-Limit dieses Claude-Kontos ist für diesen Monat aufgebraucht. Erhöhe es auf claude.ai unter Einstellungen → Nutzung oder nutze einen API-Schlüssel.",
"account_label": "Konto",
"active_account": "Aktives Konto",
"model_label": "Modell",
@@ -5826,7 +5832,11 @@
"setting_up_hint": "{0} wird gerade auf diesem Computer eingerichtet. Du kannst den Agenten schon anlegen; er antwortet, sobald die Einrichtung fertig ist.",
"auto_setup_hint": "Jarvis installiert {0} selbst und hält es aktuell.",
"setup_failed": "Einrichtung nicht abgeschlossen: {0}",
+ "provider_unsupported": "Hermes und OpenClaw laufen mit einem API-Schlüssel, einem lokalen Modellserver oder dem ChatGPT-Abo. Wähle eines davon für diesen Agenten.",
"setting_up_chat": "{0} wird auf diesem Computer eingerichtet. Beim ersten Mal dauert das ein paar Minuten; deine Nachricht wird beantwortet, sobald alles bereit ist.",
+ "routine_fallback": "Dieser Lauf nutzt Jarvis' eigene Laufzeit, nicht {0}: Das für die Routine gewählte Modell kann {0} nicht ansteuern.",
+ "ready_untested": "Bereit · neuer als getestet",
+ "untested_hint": "{0} ist neuer als die Version, die Jarvis getestet hat. Es läuft trotzdem.",
"retry": "Erneut versuchen"
},
"approval_mode": {
@@ -6146,6 +6156,37 @@
"own_words": "deine eigene Antwort",
"unanswered": "Nicht beantwortet – der Durchlauf wurde beendet."
},
+ "thread_turn": {
+ "worked": "Gearbeitet",
+ "worked_for": "{duration} gearbeitet",
+ "working_for": "Arbeitet seit {duration}",
+ "stopped": "Gestoppt",
+ "stopped_after": "Nach {duration} gestoppt",
+ "failed": "Fehlgeschlagen",
+ "failed_after": "Nach {duration} fehlgeschlagen",
+ "no_answer": "Ohne Antwort beendet",
+ "no_answer_after": "Nach {duration} ohne Antwort beendet",
+ "thinking": "Denkt nach",
+ "copy_answer": "Antwort kopieren",
+ "waiting_answer": "Wartet unten auf deine Antwort",
+ "waiting_approval": "Wartet auf Freigabe — {summary}",
+ "approval_waiting": "Wartet auf deine Freigabe",
+ "no_output": "Keine Ausgabe.",
+ "interrupted": "unterbrochen",
+ "call_failed": "{call}, fehlgeschlagen",
+ "steps": "Schritte",
+ "steps_so_far": "{summary}, bisher {count} Schritte",
+ "subagents_working_one": "{count} Sub-Agent arbeitet",
+ "subagents_working_other": "{count} Sub-Agenten arbeiten",
+ "files_changed_one": "{count} Datei geändert",
+ "files_changed_other": "{count} Dateien geändert",
+ "changed_files": "Geänderte Dateien",
+ "show_changes": "Änderungen zeigen",
+ "hide_changes": "Änderungen ausblenden",
+ "more_files_one": "{count} weitere Datei zeigen",
+ "more_files_other": "{count} weitere Dateien zeigen",
+ "collapse_files": "Dateien einklappen"
+ },
"work_trace": {
"tool_failed": "Eine Tool-Aktion ist fehlgeschlagen",
"question": "Wartet auf deine Antwort",
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/en.json b/jarvis/ui/web/frontend/src/i18n/locales/en.json
index 9f0187fdb7..e1ec1eb056 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/en.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/en.json
@@ -5649,6 +5649,9 @@
"coding_thread_author": "Written by {0}",
"message_not_sent": "Not sent: {0}",
"context_rollover": "Fresh working context — memory and recent messages carried over",
+ "stop_reason_max_tokens": "The answer stopped at the model's output limit; it may be incomplete.",
+ "stop_reason_max_turn_requests": "The agent reached its step limit for one turn; the work may be unfinished.",
+ "stop_reason_cancelled": "The turn was cancelled before it finished.",
"allow_always": "Always allow",
"history_chats": "Chats",
"history_voice": "Voice",
@@ -5799,6 +5802,9 @@
"access_hint_api": "Billed per use to your API key.",
"access_hint_local": "Runs on a model on this computer — no cost per message.",
"access_extra_usage": "Runs on your Claude Code login. Anthropic bills this as extra usage, outside your plan's limits.",
+ "access_blocked": "The provider refuses this way of paying right now. Pick another one.",
+ "access_blocked_extra_usage_off": "Not available: Extra Usage is turned off for this Claude account, and Anthropic bills Hermes and OpenClaw only as Extra Usage. Turn it on at claude.ai under Settings → Usage, or use an API key.",
+ "access_blocked_extra_usage_spent": "Not available: this Claude account's Extra Usage limit for the month is spent. Raise it at claude.ai under Settings → Usage, or use an API key.",
"account_label": "Account",
"active_account": "Active account",
"model_label": "Model",
@@ -5826,7 +5832,11 @@
"setting_up_hint": "{0} is being set up on this computer. You can create the agent now; it answers as soon as the setup is done.",
"auto_setup_hint": "Jarvis installs {0} by itself and keeps it up to date.",
"setup_failed": "Setup did not finish: {0}",
+ "provider_unsupported": "Hermes and OpenClaw run on an API key, a local model server or the ChatGPT subscription. Pick one of those for this agent.",
"setting_up_chat": "Setting up {0} on this computer. The first time takes a few minutes; your message is answered as soon as it is ready.",
+ "routine_fallback": "This run uses Jarvis' own runtime, not {0}: the model chosen for the routine is one {0} cannot drive.",
+ "ready_untested": "Ready · newer than tested",
+ "untested_hint": "{0} is newer than the version Jarvis has tested. It still runs.",
"retry": "Try again"
},
"approval_mode": {
@@ -6146,6 +6156,37 @@
"own_words": "your own answer",
"unanswered": "Not answered — the turn ended."
},
+ "thread_turn": {
+ "worked": "Worked",
+ "worked_for": "Worked for {duration}",
+ "working_for": "Working for {duration}",
+ "stopped": "Stopped",
+ "stopped_after": "Stopped after {duration}",
+ "failed": "Failed",
+ "failed_after": "Failed after {duration}",
+ "no_answer": "Finished without an answer",
+ "no_answer_after": "Finished without an answer after {duration}",
+ "thinking": "Thinking",
+ "copy_answer": "Copy answer",
+ "waiting_answer": "Waiting for your answer below",
+ "waiting_approval": "Waiting for approval — {summary}",
+ "approval_waiting": "Waiting for your approval",
+ "no_output": "No output.",
+ "interrupted": "interrupted",
+ "call_failed": "{call}, failed",
+ "steps": "Steps",
+ "steps_so_far": "{summary}, {count} steps so far",
+ "subagents_working_one": "{count} sub-agent working",
+ "subagents_working_other": "{count} sub-agents working",
+ "files_changed_one": "{count} file changed",
+ "files_changed_other": "{count} files changed",
+ "changed_files": "Changed files",
+ "show_changes": "Show changes",
+ "hide_changes": "Hide changes",
+ "more_files_one": "Show {count} more file",
+ "more_files_other": "Show {count} more files",
+ "collapse_files": "Collapse files"
+ },
"work_trace": {
"tool_failed": "A tool action failed",
"question": "Waiting for your answer",
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/es.json b/jarvis/ui/web/frontend/src/i18n/locales/es.json
index 1f793b97b6..d041207383 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/es.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/es.json
@@ -5649,6 +5649,9 @@
"coding_thread_author": "Escrito por {0}",
"message_not_sent": "No enviado: {0}",
"context_rollover": "Contexto de trabajo nuevo: se conservan la memoria y los mensajes recientes",
+ "stop_reason_max_tokens": "La respuesta se detuvo en el límite de salida del modelo; puede estar incompleta.",
+ "stop_reason_max_turn_requests": "El agente alcanzó su límite de pasos para un turno; el trabajo puede estar sin terminar.",
+ "stop_reason_cancelled": "El turno se canceló antes de terminar.",
"allow_always": "Permitir siempre",
"history_chats": "Chats",
"history_voice": "Voz",
@@ -5799,6 +5802,9 @@
"access_hint_api": "Se cobra por uso a tu clave de API.",
"access_hint_local": "Funciona con un modelo en este ordenador, sin coste por mensaje.",
"access_extra_usage": "Funciona con tu inicio de sesión de Claude Code. Anthropic lo cobra como uso adicional, fuera de los límites de tu plan.",
+ "access_blocked": "El proveedor rechaza ahora esta forma de pago. Elige otra.",
+ "access_blocked_extra_usage_off": "No disponible: el uso adicional está desactivado en esta cuenta de Claude, y Anthropic cobra Hermes y OpenClaw solo como uso adicional. Actívalo en claude.ai en Configuración → Uso, o usa una clave de API.",
+ "access_blocked_extra_usage_spent": "No disponible: el límite mensual de uso adicional de esta cuenta de Claude está agotado. Súbelo en claude.ai en Configuración → Uso, o usa una clave de API.",
"account_label": "Cuenta",
"active_account": "Cuenta activa",
"model_label": "Modelo",
@@ -5826,7 +5832,11 @@
"setting_up_hint": "{0} se está configurando en este equipo. Ya puedes crear el agente; responderá en cuanto termine la configuración.",
"auto_setup_hint": "Jarvis instala {0} por sí mismo y lo mantiene actualizado.",
"setup_failed": "La instalación no terminó: {0}",
+ "provider_unsupported": "Hermes y OpenClaw funcionan con una clave de API, un servidor de modelos local o la suscripción de ChatGPT. Elige una de esas opciones para este agente.",
"setting_up_chat": "Configurando {0} en este equipo. La primera vez tarda unos minutos; tu mensaje se responde en cuanto esté listo.",
+ "routine_fallback": "Esta ejecución usa el entorno propio de Jarvis, no {0}: {0} no puede usar el modelo elegido para la rutina.",
+ "ready_untested": "Listo · más nuevo que lo probado",
+ "untested_hint": "{0} es más nuevo que la versión que Jarvis ha probado. Sigue funcionando.",
"retry": "Reintentar"
},
"approval_mode": {
@@ -6146,6 +6156,37 @@
"own_words": "tu propia respuesta",
"unanswered": "Sin responder: el turno terminó."
},
+ "thread_turn": {
+ "worked": "Trabajó",
+ "worked_for": "Trabajó durante {duration}",
+ "working_for": "Trabajando desde hace {duration}",
+ "stopped": "Detenido",
+ "stopped_after": "Detenido tras {duration}",
+ "failed": "Falló",
+ "failed_after": "Falló tras {duration}",
+ "no_answer": "Terminó sin respuesta",
+ "no_answer_after": "Terminó sin respuesta tras {duration}",
+ "thinking": "Pensando",
+ "copy_answer": "Copiar respuesta",
+ "waiting_answer": "Esperando tu respuesta abajo",
+ "waiting_approval": "Esperando aprobación — {summary}",
+ "approval_waiting": "Esperando tu aprobación",
+ "no_output": "Sin salida.",
+ "interrupted": "interrumpido",
+ "call_failed": "{call}, falló",
+ "steps": "Pasos",
+ "steps_so_far": "{summary}, {count} pasos hasta ahora",
+ "subagents_working_one": "{count} subagente trabajando",
+ "subagents_working_other": "{count} subagentes trabajando",
+ "files_changed_one": "{count} archivo cambiado",
+ "files_changed_other": "{count} archivos cambiados",
+ "changed_files": "Archivos cambiados",
+ "show_changes": "Mostrar cambios",
+ "hide_changes": "Ocultar cambios",
+ "more_files_one": "Mostrar {count} archivo más",
+ "more_files_other": "Mostrar {count} archivos más",
+ "collapse_files": "Contraer archivos"
+ },
"work_trace": {
"tool_failed": "Falló una acción de herramienta",
"question": "Esperando tu respuesta",
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/zh.json b/jarvis/ui/web/frontend/src/i18n/locales/zh.json
index a0cfa84abb..163a555b1f 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/zh.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/zh.json
@@ -4458,6 +4458,7 @@
"close": "关闭",
"cancel": "取消",
"save": "保存",
+ "save_add": "添加 CLI",
"saving": "正在保存…",
"name": "名称",
"name_placeholder": "Antigravity",
@@ -4467,11 +4468,14 @@
"command_hint": "就是你在终端里启动它时输入的内容。",
"command_shell_hint": "因为这条命令不止一个程序,所以会通过 shell 运行。整行执行完后窗格会关闭。",
"description_label": "描述",
+ "optional": "可选",
"description_placeholder": "用一句话说明这个 CLI 是什么。",
"at_reference": "将拖入的文件写成 @path",
"at_reference_hint": "大多数现代编程 CLI 会把 @path 当作要打开的文件。关闭此项则会把路径加引号粘贴。",
"pick_logo": "选择图标",
"remove_logo": "移除图标",
+ "remove_logo_short": "移除",
+ "logo_label": "图标",
"edit_named": "编辑 {0}",
"remove_named": "移除 {0}",
"gone": "该 CLI 已不在列表中。",
@@ -5651,6 +5655,9 @@
"coding_thread_author": "由 {0} 撰写",
"message_not_sent": "未发送:{0}",
"context_rollover": "已换用新的工作上下文——记忆和最近的消息已带过来",
+ "stop_reason_max_tokens": "回答在模型的输出上限处停止,可能不完整。",
+ "stop_reason_max_turn_requests": "智能体已达到单轮的步骤上限,工作可能尚未完成。",
+ "stop_reason_cancelled": "本轮在完成前被取消。",
"allow_always": "始终允许",
"history_chats": "对话",
"history_voice": "语音",
@@ -5801,6 +5808,9 @@
"access_hint_api": "按使用量从你的 API 密钥计费。",
"access_hint_local": "使用这台电脑上的模型运行,每条消息无费用。",
"access_extra_usage": "使用你的 Claude Code 登录运行。Anthropic 将其按额外用量计费,不计入你的套餐额度。",
+ "access_blocked": "提供商目前拒绝这种付费方式。请选择其他方式。",
+ "access_blocked_extra_usage_off": "不可用:此 Claude 账户已关闭额外用量,而 Anthropic 只按额外用量为 Hermes 和 OpenClaw 计费。请在 claude.ai 的“设置 → 用量”中开启,或使用 API 密钥。",
+ "access_blocked_extra_usage_spent": "不可用:此 Claude 账户本月的额外用量额度已用完。请在 claude.ai 的“设置 → 用量”中提高额度,或使用 API 密钥。",
"account_label": "账号",
"active_account": "当前账号",
"model_label": "模型",
@@ -5828,7 +5838,11 @@
"setting_up_hint": "正在这台电脑上安装 {0}。你现在就可以创建智能体,安装完成后它就会回复。",
"auto_setup_hint": "Jarvis 会自动安装 {0} 并保持更新。",
"setup_failed": "安装未完成:{0}",
+ "provider_unsupported": "Hermes 和 OpenClaw 需要使用 API 密钥、本地模型服务器或 ChatGPT 订阅运行。请为此智能体选择其中一种。",
"setting_up_chat": "正在这台电脑上安装 {0}。第一次需要几分钟,准备好后会立即回复你的消息。",
+ "routine_fallback": "本次运行使用 Jarvis 自己的运行时,而不是 {0}:为此例行任务选择的模型无法由 {0} 驱动。",
+ "ready_untested": "就绪 · 比已测试版本更新",
+ "untested_hint": "{0} 比 Jarvis 测试过的版本更新,仍可运行。",
"retry": "重试"
},
"approval_mode": {
@@ -6148,6 +6162,37 @@
"own_words": "你自己的回答",
"unanswered": "未回答——本轮已结束。"
},
+ "thread_turn": {
+ "worked": "已工作",
+ "worked_for": "已工作 {duration}",
+ "working_for": "已工作 {duration}",
+ "stopped": "已停止",
+ "stopped_after": "{duration} 后停止",
+ "failed": "失败",
+ "failed_after": "{duration} 后失败",
+ "no_answer": "已结束,没有回答",
+ "no_answer_after": "{duration} 后结束,没有回答",
+ "thinking": "思考中",
+ "copy_answer": "复制回答",
+ "waiting_answer": "等待你在下方回答",
+ "waiting_approval": "等待批准 — {summary}",
+ "approval_waiting": "等待你的批准",
+ "no_output": "无输出。",
+ "interrupted": "已中断",
+ "call_failed": "{call},失败",
+ "steps": "步骤",
+ "steps_so_far": "{summary},目前 {count} 步",
+ "subagents_working_one": "{count} 个子代理正在工作",
+ "subagents_working_other": "{count} 个子代理正在工作",
+ "files_changed_one": "已更改 {count} 个文件",
+ "files_changed_other": "已更改 {count} 个文件",
+ "changed_files": "已更改的文件",
+ "show_changes": "显示更改",
+ "hide_changes": "隐藏更改",
+ "more_files_one": "再显示 {count} 个文件",
+ "more_files_other": "再显示 {count} 个文件",
+ "collapse_files": "收起文件"
+ },
"work_trace": {
"tool_failed": "一个工具操作失败",
"question": "等待你的回答",
diff --git a/jarvis/ui/web/frontend/src/lib/agentRuntimesApi.ts b/jarvis/ui/web/frontend/src/lib/agentRuntimesApi.ts
index 58e6f6fe9d..3a97251f37 100644
--- a/jarvis/ui/web/frontend/src/lib/agentRuntimesApi.ts
+++ b/jarvis/ui/web/frontend/src/lib/agentRuntimesApi.ts
@@ -9,7 +9,8 @@ export type ExternalRuntime = Exclude<AgentRuntime, "jarvis">;
export interface AgentRuntimeJob {
runtime: ExternalRuntime;
- kind: "install" | "update";
+ /** `prepare` is Hermes' one-time first start after its install. */
+ kind: "install" | "update" | "prepare";
state: "running" | "done" | "failed";
started_ms: number;
finished_ms: number | null;
@@ -31,6 +32,9 @@ export interface AgentRuntimeStatus {
/** The same as a key the UI translates. */
problem_kind: "" | "not_installed" | "outdated" | "node" | "no_version";
install_hint: string;
+ /** Ready, but newer than the release Jarvis' canary tested (it still runs).
+ * Absent on an older backend. */
+ untested?: boolean;
job: AgentRuntimeJob | null;
}
@@ -50,6 +54,11 @@ export interface AgentRuntimesResponse {
/** Per provider that can pay two ways (Claude: API key or Claude Code
* login), the ways that work right now: "api" and/or "subscription". */
access?: Record<string, string[]>;
+ /** Per provider and way of paying, the refusal code of an access that is
+ * connected but refused right now (Claude's login while its Extra Usage
+ * is off: `{"claude-api": {"subscription": "extra_usage_off"}}`). Absent
+ * on an older backend. */
+ access_blocked?: Record<string, Record<string, string>>;
}
async function json<T>(url: string, init?: RequestInit): Promise<T> {
diff --git a/jarvis/ui/web/runtime_gateway_routes.py b/jarvis/ui/web/runtime_gateway_routes.py
index 921392d86d..f092320254 100644
--- a/jarvis/ui/web/runtime_gateway_routes.py
+++ b/jarvis/ui/web/runtime_gateway_routes.py
@@ -32,6 +32,9 @@ def _error(exc: gateway.GatewayError) -> JSONResponse:
return JSONResponse(
{"error": {"message": str(exc), "type": exc.code, "code": exc.code}},
status_code=exc.status,
+ headers={"Retry-After": str(gateway.whole_seconds(exc.retry_after))}
+ if exc.retry_after is not None
+ else None,
)
@@ -51,12 +54,19 @@ async def runtime_gateway_chat(request: Request) -> Any:
raise gateway.GatewayError("This agent's subscription answers on /responses.")
body = await _body(request)
model, brain_request = gateway.chat_request(body)
+ gateway.check_model(grant, model)
+ # A runtime that sets no temperature gets the model's own default.
+ temperature_given = gateway.temperature_given(body)
if body.get("stream") is True:
- chunks = await gateway.open_chat_stream(grant, model, brain_request)
+ chunks = await gateway.open_chat_stream(
+ grant, model, brain_request, temperature_given=temperature_given
+ )
return StreamingResponse(
chunks, media_type="text/event-stream", headers={"Cache-Control": "no-cache"}
)
- return await gateway.complete_chat(grant, model, brain_request)
+ return await gateway.complete_chat(
+ grant, model, brain_request, temperature_given=temperature_given
+ )
except gateway.GatewayError as exc:
return _error(exc)
@@ -70,9 +80,11 @@ async def runtime_gateway_responses(request: Request) -> Any:
raise gateway.GatewayError("This agent's provider answers on /chat/completions.")
body = await _body(request)
args = gateway.request_args(body)
+ gateway.check_model(grant, args["model"])
if body.get("stream") is True:
+ events = await gateway.open_response_stream(grant, args)
return StreamingResponse(
- gateway.stream_response(grant, args),
+ events,
media_type="text/event-stream",
headers={"Cache-Control": "no-cache"},
)
diff --git a/jarvis/ui/web/society_routes.py b/jarvis/ui/web/society_routes.py
index 2aabf05982..8bb8963568 100644
--- a/jarvis/ui/web/society_routes.py
+++ b/jarvis/ui/web/society_routes.py
@@ -72,6 +72,17 @@ def _typed_error(exc: RosterError | RoomError) -> HTTPException:
)
+#: The 422 for a provider Hermes / OpenClaw cannot drive. ``reason`` lets the
+#: UI show its own translated sentence; ``detail`` is for the CLI and logs.
+_RUNTIME_PROVIDER_UNSUPPORTED: dict[str, str] = {
+ "reason": "runtime_provider_unsupported",
+ "detail": (
+ "Hermes and OpenClaw run on an API key, a local model server or the "
+ "ChatGPT subscription. Pick one of those for this agent."
+ ),
+}
+
+
def _validated_chat_runner(
rt: SocietyRuntime,
agent: AgentRecord,
@@ -90,11 +101,7 @@ def _validated_chat_runner(
from jarvis.agent_runtimes.model_map import supports
if not supports(provider):
- raise HTTPException(
- 422,
- "Hermes and OpenClaw run on an API key or a local model. "
- "Pick one of those for this agent.",
- )
+ raise HTTPException(422, _RUNTIME_PROVIDER_UNSUPPORTED)
runner = resolve_runner(
provider,
surface="society",
@@ -343,11 +350,7 @@ async def create_agent(body: CreateAgentBody, request: Request) -> dict[str, Any
from jarvis.agent_runtimes.model_map import supports
if not supports(provider):
- raise HTTPException(
- 422,
- "Hermes and OpenClaw run on an API key or a local model. "
- "Pick one of those for this agent first.",
- )
+ raise HTTPException(422, _RUNTIME_PROVIDER_UNSUPPORTED)
if provider:
from jarvis.agent_chat.permissions import society_mode_supported
from jarvis.agent_chat.service import resolve_runner
diff --git a/pyproject.toml b/pyproject.toml
index 61842cc6af..a176c34b41 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -889,6 +889,9 @@ jarvis = [
"skills/safe_imports.txt",
"core/review/verdict_schema.json",
"society/mars/definition.json",
+ # The Hermes / OpenClaw releases setup installs and accepts
+ # (agent_runtimes/versions.py); without it setup falls back to latest.
+ "agent_runtimes/runtime-versions.json",
# Seed catalogs (CLI tools / skills / marketplace plugins) — named
# explicitly rather than a repo-wide "**/*.json" glob, which would also
# sweep in jarvis/ui/web/frontend's SOURCE config (package.json,
diff --git a/scripts/ci/agent_runtime_e2e.py b/scripts/ci/agent_runtime_e2e.py
new file mode 100644
index 0000000000..7e71de6c3a
--- /dev/null
+++ b/scripts/ci/agent_runtime_e2e.py
@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""Install a real Hermes / OpenClaw the way the desktop app does, then drive it.
+
+Run by the ``agent-runtimes-e2e`` CI job and the weekly canary, one runtime
+per call, on Linux, Windows and macOS:
+
+1. The process runs with a desktop app's PATH (POSIX ``/usr/bin:/bin`` plus
+ this Python; Windows the default system folders plus this Python), so a
+ setup that only works from a developer's shell fails here.
+2. ``manager.wait_ready`` installs and prepares the runtime through the app's
+ own setup job: the pinned release (``runtime-versions.json``), its private
+ Node.js for OpenClaw, Hermes' one-time prepare. No npm, no manual installer.
+3. The spikes run two turns per model-gateway protocol against scripted
+ providers (``--replay``) and the fake-model driver check; turn 1 must stay
+ inside its budget.
+4. ``pytest tests/unit/agent_runtimes`` runs on the same machine.
+5. Nothing persistent may change: the Windows user PATH gains no
+ ``agent_runtimes`` entry, and OpenClaw edits no POSIX shell profile.
+
+``--expect-setup-failure TEXT`` is the bare-container leg: setup must fail
+with a reason containing ``TEXT`` (``python:3.11-slim`` has no curl).
+
+ python scripts/ci/agent_runtime_e2e.py hermes
+ python scripts/ci/agent_runtime_e2e.py openclaw --allow-untested # canary
+ python scripts/ci/agent_runtime_e2e.py hermes --expect-setup-failure "Setup needs curl"
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+RUNTIMES = ("hermes", "openclaw")
+
+#: Turn-1 budget after the one-time prepare, in seconds.
+TURN_BUDGET_S = {"hermes": 30.0, "openclaw": 90.0}
+_TURN = re.compile(r"turn 1 took ([0-9.]+) s")
+_PROFILES = (".profile", ".bashrc", ".zshrc")
+#: Runtimes whose official installer may write a POSIX shell profile.
+_PROFILE_EDITS_ALLOWED = frozenset({"hermes"})
+
+
+def desktop_path() -> str:
+ """The PATH a desktop app starts with, plus the interpreter running it."""
+ python_dir = str(Path(sys.executable).resolve().parent)
+ if os.name == "nt":
+ root = os.environ.get("SystemRoot", r"C:\Windows")
+ parts = [
+ rf"{root}\System32",
+ root,
+ rf"{root}\System32\Wbem",
+ rf"{root}\System32\WindowsPowerShell\v1.0",
+ ]
+ else:
+ parts = ["/usr/bin", "/bin"]
+ return os.pathsep.join([*parts, python_dir])
+
+
+def _user_path_entries() -> list[str]:
+ """The Windows user PATH (``HKCU\\Environment``); empty elsewhere."""
+ if os.name != "nt":
+ return []
+ import winreg
+
+ try:
+ with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment") as key:
+ value, _kind = winreg.QueryValueEx(key, "Path")
+ except OSError: # no user PATH at all: nothing to compare
+ return []
+ return [entry for entry in str(value).split(";") if entry]
+
+
+def _profiles() -> dict[str, str]:
+ if os.name == "nt":
+ return {}
+ home = Path.home()
+ return {
+ name: (home / name).read_text(encoding="utf-8", errors="replace")
+ if (home / name).exists()
+ else ""
+ for name in _PROFILES
+ }
+
+
+def _run(argv: list[str], env: dict[str, str]) -> tuple[int, str]:
+ print("$", " ".join(argv), flush=True)
+ proc = subprocess.run( # noqa: S603 — this interpreter and repo scripts
+ argv, cwd=REPO_ROOT, env=env, capture_output=True, text=True,
+ encoding="utf-8", errors="replace", check=False,
+ creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+ )
+ output = proc.stdout + proc.stderr
+ print(output, flush=True)
+ return proc.returncode, output
+
+
+def _setup(runtime: str, timeout_s: float) -> tuple[object, object, str]:
+ import asyncio
+
+ from jarvis.agent_runtimes import manager
+
+ status = asyncio.run(manager.wait_ready(runtime, timeout_s=timeout_s))
+ job = manager.job(runtime)
+ print("status:", status.to_dict(), flush=True)
+ print("job:", job.to_dict() if job is not None else None, flush=True)
+ return status, job, manager.failure_reason(runtime)
+
+
+def _keep_setup_log(runtime: str) -> None:
+ """Copy the setup log where the job uploads diagnostics from."""
+ from jarvis.agent_runtimes import base
+
+ log = base.runtimes_root() / f"{runtime}-setup.log"
+ if log.exists():
+ target = REPO_ROOT / "eval-results" / f"{runtime}-setup.log"
+ target.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copyfile(log, target)
+ print("setup log kept:", target, flush=True)
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+ parser.add_argument("runtime", choices=RUNTIMES)
+ parser.add_argument("--timeout", type=float, default=2400.0, help="Setup wait, seconds.")
+ parser.add_argument(
+ "--allow-untested", action="store_true",
+ help="Accept a release newer than the pin (the canary installs upstream latest).",
+ )
+ parser.add_argument("--expect-setup-failure", default="", metavar="TEXT")
+ args = parser.parse_args(argv)
+
+ os.environ["PATH"] = desktop_path()
+ sys.path.insert(0, str(REPO_ROOT))
+ env = dict(os.environ)
+ print("PATH:", env["PATH"], flush=True)
+ user_path, profiles = _user_path_entries(), _profiles()
+ problems: list[str] = []
+
+ status, job, reason = _setup(args.runtime, args.timeout)
+ if args.expect_setup_failure:
+ if getattr(status, "ready", False) or args.expect_setup_failure not in reason:
+ problems.append(
+ f"setup should fail with {args.expect_setup_failure!r}; "
+ f"ready={getattr(status, 'ready', None)} reason={reason!r}"
+ )
+ _keep_setup_log(args.runtime)
+ return _verdict(problems)
+
+ ready = bool(getattr(status, "ready", False))
+ untested = bool(getattr(status, "untested", False))
+ job_ok = job is None or getattr(job, "state", "") == "done"
+ if not ready or not job_ok or (untested and not args.allow_untested):
+ problems.append(f"setup: ready={ready} untested={untested} job_ok={job_ok} {reason}")
+ _keep_setup_log(args.runtime)
+ return _verdict(problems)
+
+ spikes = [
+ [sys.executable, "scripts/spikes/agent_runtimes_gateway_e2e.py", args.runtime,
+ "openai-codex", "--replay"],
+ [sys.executable, "scripts/spikes/agent_runtimes_gateway_e2e.py", args.runtime,
+ "ollama", "--replay"],
+ [sys.executable, "scripts/spikes/agent_runtimes_e2e.py", args.runtime],
+ ]
+ budget = TURN_BUDGET_S[args.runtime]
+ for spike in spikes:
+ code, output = _run(spike, env)
+ if code != 0:
+ problems.append(f"{' '.join(spike[1:])} exited {code}")
+ for took in (float(value) for value in _TURN.findall(output)):
+ if took >= budget:
+ name = " ".join(spike[1:])
+ problems.append(f"{name}: turn 1 took {took:.1f} s >= {budget:.0f} s")
+
+ code, _ = _run([sys.executable, "-m", "pytest", "tests/unit/agent_runtimes", "-q",
+ "-p", "no:cacheprovider"], env)
+ if code != 0:
+ problems.append(f"pytest tests/unit/agent_runtimes exited {code}")
+
+ gained = [e for e in _user_path_entries() if e not in user_path and "agent_runtimes" in e]
+ if gained:
+ problems.append(f"the Windows user PATH gained {gained}")
+ for name, before in profiles.items():
+ after = _profiles().get(name, "")
+ if after != before:
+ print(f"~/{name} changed during {args.runtime} setup", flush=True)
+ if args.runtime not in _PROFILE_EDITS_ALLOWED:
+ problems.append(f"{args.runtime} changed ~/{name}")
+ if problems:
+ _keep_setup_log(args.runtime)
+ return _verdict(problems)
+
+
+def _verdict(problems: list[str]) -> int:
+ for problem in problems:
+ print("FAIL:", problem, flush=True)
+ print("RESULT:", "FAIL" if problems else "PASS", flush=True)
+ return 1 if problems else 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/ci/agent_runtime_suite.py b/scripts/ci/agent_runtime_suite.py
new file mode 100644
index 0000000000..ff46cac3dc
--- /dev/null
+++ b/scripts/ci/agent_runtime_suite.py
@@ -0,0 +1,316 @@
+#!/usr/bin/env python3
+"""The Hermes / OpenClaw agent-runtime lane: which changes reach it, what it runs.
+
+One table for three consumers, so they cannot drift apart:
+
+* ``classify_changes.py`` turns the ``agent_runtimes`` lane on for
+ :data:`PREFIXES` / :data:`FILES`;
+* ``select_tests.py`` adds :data:`SUITE` to an impact selection that touches
+ the lane, so a change to the runtimes also runs the chat and society code
+ that drives them (not only the tests that import the changed module);
+* the ``agent-runtimes-unit`` / ``agent-runtimes-headless`` CI jobs run
+ ``python scripts/ci/agent_runtime_suite.py`` — the same command on every OS.
+
+The real-binary check (``scripts/spikes/agent_runtimes_gateway_e2e.py
+--replay``) is a separate job: it needs Hermes or OpenClaw installed.
+
+ python scripts/ci/agent_runtime_suite.py # run the suite
+ python scripts/ci/agent_runtime_suite.py --list # print the test paths
+ python scripts/ci/agent_runtime_suite.py --headless # the slim-container subset
+ python scripts/ci/agent_runtime_suite.py --pin hermes # install pin -> $GITHUB_OUTPUT
+ python scripts/ci/agent_runtime_suite.py --bump openclaw --version 2026.9.8
+
+The pin comes from ``jarvis/agent_runtimes/runtime-versions.json``:
+``{"hermes": {"tested": "0.21.5", "commit": "<sha>"}, "openclaw": {"tested":
+"2026.9.8"}}``. Hermes is pinned by ``commit`` (its installers take
+``--commit`` / ``-Commit``; a version string alone cannot select a release),
+OpenClaw by ``tested`` (an npm version). A missing file or key means latest:
+the lane still runs, it just proves the newest upstream instead of the pin.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+MANIFEST = REPO_ROOT / "jarvis" / "agent_runtimes" / "runtime-versions.json"
+RUNTIMES: tuple[str, ...] = ("hermes", "openclaw")
+_VERSION = re.compile(r"[0-9A-Za-z][0-9A-Za-z.+-]{0,63}")
+_COMMIT = re.compile(r"[0-9a-f]{40}")
+
+#: Code whose change can break an agent on Hermes or OpenClaw.
+PREFIXES: tuple[str, ...] = (
+ "jarvis/agent_runtimes/",
+ "tests/unit/agent_runtimes/",
+ "scripts/spikes/agent_runtimes_",
+)
+FILES: frozenset[str] = frozenset(
+ {
+ "jarvis/agent_chat/runner_acp.py",
+ "jarvis/agent_chat/runner_cli.py",
+ "jarvis/agent_chat/service.py",
+ "jarvis/agent_chat/send_queue.py",
+ "jarvis/agent_chat/control.py",
+ "jarvis/agent_chat/task_recovery.py",
+ "jarvis/agent_chat/catalog.py",
+ "jarvis/society/chat_binding.py",
+ "jarvis/society/roster.py",
+ "jarvis/society/routine_runner.py",
+ "jarvis/society/seat_brain.py",
+ "jarvis/ui/web/agent_runtime_routes.py",
+ "jarvis/ui/web/runtime_gateway_routes.py",
+ "jarvis/ui/web/society_routes.py",
+ "tests/fakes/fake_acp_agent.py",
+ "tests/fakes/fake_runtime_brain.py",
+ "scripts/ci/agent_runtime_suite.py",
+ "scripts/ci/agent_runtime_e2e.py",
+ }
+)
+
+#: Unit and integration tests of the runtimes and of the chat / society code
+#: that drives them. Fakes only: no runtime binary, no network, no key.
+SUITE: tuple[str, ...] = (
+ "tests/unit/agent_runtimes",
+ "tests/unit/agent_chat/test_agent_chat_service.py",
+ "tests/unit/agent_chat/test_controls.py",
+ "tests/unit/agent_chat/test_send_queue.py",
+ "tests/unit/agent_chat/test_task_recovery.py",
+ "tests/unit/agent_chat/test_turn_host.py",
+ "tests/unit/society/test_agent_runtime_field.py",
+ "tests/unit/society/test_chat_binding.py",
+ "tests/unit/society/test_roster.py",
+ "tests/unit/society/test_routines.py",
+ "tests/unit/society/test_seat_brain_runtime.py",
+ "tests/unit/society/test_runtime_grant_revocation.py",
+ "tests/unit/ui/web/test_society_routes.py",
+ "tests/contract/test_routine_chats.py",
+)
+
+#: What must pass on a bare ``python:3.11-slim`` (no GPU, audio, desktop).
+HEADLESS: tuple[str, ...] = ("tests/unit/agent_runtimes",)
+
+
+def touches(path: str) -> bool:
+ """Whether a changed repo-relative path reaches the runtime lane."""
+ path = path.strip().replace("\\", "/")
+ return path.startswith(PREFIXES) or path in FILES
+
+
+def _existing(paths: tuple[str, ...]) -> list[str]:
+ missing = [path for path in paths if not (REPO_ROOT / path).exists()]
+ if missing:
+ # A renamed test must be renamed here too; a silent skip would shrink
+ # the lane's evidence without anyone noticing.
+ raise SystemExit(f"agent runtime suite names missing tests: {', '.join(missing)}")
+ return list(paths)
+
+
+def _manifest(path: Path) -> dict:
+ try:
+ data = json.loads(path.read_text(encoding="utf-8"))
+ except FileNotFoundError:
+ return {}
+ return data if isinstance(data, dict) else {}
+
+
+def pin(runtime: str, path: Path = MANIFEST) -> dict[str, str]:
+ """How CI installs ``runtime``: ``version`` (shown), ``npm_spec`` (OpenClaw)
+ and ``hermes_commit`` ("" = the installer's default branch, latest)."""
+ entry = _manifest(path).get(runtime)
+ if isinstance(entry, str):
+ entry = {"tested": entry}
+ elif not isinstance(entry, dict):
+ entry = {}
+ version = str(entry.get("tested") or "")
+ commit = str(entry.get("commit") or "")
+ # Values reach a shell command line: accept only plain versions and SHAs.
+ version = version if _VERSION.fullmatch(version) else ""
+ commit = commit if _COMMIT.fullmatch(commit) else ""
+ return {
+ "version": version or "latest",
+ "npm_spec": f"openclaw@{version or 'latest'}",
+ "hermes_commit": commit,
+ }
+
+
+def bump(runtime: str, version: str, commit: str = "", path: Path = MANIFEST) -> bool:
+ """Record ``version`` (and Hermes' ``commit``) as tested; True when it changed."""
+ if not _VERSION.fullmatch(version) or (commit and not _COMMIT.fullmatch(commit)):
+ raise SystemExit(f"refusing to record an unexpected version {version!r} / {commit!r}")
+ data = _manifest(path)
+ entry = data.get(runtime) if isinstance(data.get(runtime), dict) else {}
+ updated = {**entry, "tested": version, **({"commit": commit} if commit else {})}
+ if updated == entry:
+ return False
+ data[runtime] = updated
+ path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+ return True
+
+
+def bump_from(folder: Path, path: Path = MANIFEST, *, expected_reports: int = 3) -> bool:
+ """Raise each runtime's pin to what the canary proved on EVERY OS.
+
+ ``folder`` holds one ``report`` JSON per green canary job. A runtime is
+ raised only when all ``expected_reports`` OS jobs reported the same
+ version and commit; one missing or disagreeing OS keeps the old pin.
+ """
+ seen: dict[str, list[tuple[str, str]]] = {}
+ for file in sorted(folder.rglob("*.json")):
+ data = json.loads(file.read_text(encoding="utf-8"))
+ if isinstance(data, dict) and data.get("runtime") in RUNTIMES:
+ seen.setdefault(data["runtime"], []).append(
+ (str(data.get("version") or ""), str(data.get("commit") or ""))
+ )
+ changed = False
+ for runtime, reports in seen.items():
+ if len(reports) != expected_reports or len(set(reports)) != 1:
+ print(f"{runtime}: {len(reports)} report(s) {sorted(set(reports))}; pin kept")
+ continue
+ version, commit = reports[0]
+ changed = bump(runtime, version, commit, path) or changed
+ return changed
+
+
+def _git(*args: str) -> str:
+ return subprocess.run( # noqa: S603 — fixed git query
+ ["git", *args],
+ capture_output=True,
+ text=True,
+ check=False,
+ creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+ ).stdout.strip()
+
+
+def _hermes_commit(upstream: str = "") -> str:
+ """The full UPSTREAM commit of the installed Hermes.
+
+ ``upstream`` is the short sha from ``hermes --version`` ("upstream
+ ed2dd0b3"); a checkout's HEAD may carry local commits no other machine
+ can install, so it is used only on a clean checkout without that line.
+ """
+ home = Path(os.environ.get("HERMES_HOME") or Path.home() / ".hermes")
+ local = os.environ.get("LOCALAPPDATA")
+ candidates = [home / "hermes-agent"]
+ if local:
+ candidates.insert(0, Path(local) / "hermes" / "hermes-agent")
+ for checkout in candidates:
+ if not (checkout / ".git").exists():
+ continue
+ found = _git("-C", str(checkout), "rev-parse", f"{upstream or 'HEAD'}^{{commit}}")
+ if _COMMIT.fullmatch(found):
+ return found
+ return ""
+
+
+def report(runtime: str) -> dict[str, str]:
+ """What the canary just proved: the installed version (and Hermes' commit)."""
+ sys.path.insert(0, str(REPO_ROOT))
+ from jarvis.agent_runtimes import driver
+
+ target = driver(runtime)
+ status = target.detect(refresh=True)
+ if not status.ready or not _VERSION.fullmatch(status.version or ""):
+ raise SystemExit(f"{runtime} is not ready to report ({status.problem or 'no version'})")
+ commit = ""
+ if runtime == "hermes":
+ revision = getattr(target, "revision", None)
+ upstream = revision(status) if callable(revision) else ""
+ commit = _hermes_commit(upstream if re.fullmatch(r"[0-9a-f]{7,40}", upstream) else "")
+ if not commit:
+ # Without an upstream commit the pin cannot select this release.
+ raise SystemExit("the installed Hermes' upstream commit could not be read")
+ return {"runtime": runtime, "version": status.version, "commit": commit}
+
+
+def point_at_latest(runtime: str, path: Path = MANIFEST) -> dict[str, str]:
+ """Aim the app's own setup at upstream latest (the canary's checkout only).
+
+ OpenClaw: ``tested`` = the newest npm release. Hermes: ``commit`` = the
+ head of its default branch; ``tested`` stays, so the install reports as
+ untested until the canary's pull request raises it.
+ """
+ data = _manifest(path)
+ entry = data.get(runtime) if isinstance(data.get(runtime), dict) else {}
+ if runtime == "openclaw":
+ npm = shutil.which("npm") or shutil.which("npm.cmd")
+ latest = subprocess.run( # noqa: S603 — fixed registry query
+ [npm or "npm", "view", "openclaw", "version"],
+ capture_output=True, text=True, check=False,
+ creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+ ).stdout.strip()
+ if not _VERSION.fullmatch(latest):
+ raise SystemExit(f"npm named no OpenClaw release ({latest!r})")
+ entry = {**entry, "tested": latest}
+ else:
+ head = _git("ls-remote", "https://github.com/NousResearch/hermes-agent", "HEAD").split()
+ if not head or not _COMMIT.fullmatch(head[0]):
+ raise SystemExit("the Hermes repository named no head commit")
+ entry = {**entry, "commit": head[0]}
+ data[runtime] = entry
+ path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+ return {key: str(value) for key, value in entry.items()}
+
+
+def _emit(values: dict[str, str]) -> None:
+ lines = [f"{key}={value}" for key, value in values.items()]
+ output = os.environ.get("GITHUB_OUTPUT")
+ if output:
+ with open(output, "a", encoding="utf-8") as handle:
+ handle.write("\n".join(lines) + "\n")
+ print("\n".join(lines))
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+ parser.add_argument("--list", action="store_true", help="Print the test paths and exit.")
+ parser.add_argument("--headless", action="store_true", help="Only the slim-container subset.")
+ parser.add_argument("--pin", choices=RUNTIMES, help="Print how CI installs this runtime.")
+ parser.add_argument("--bump", choices=RUNTIMES, help="Record --version as tested.")
+ parser.add_argument("--version", default="", help="With --bump: the version that passed.")
+ parser.add_argument("--commit", default="", help="With --bump hermes: its commit.")
+ parser.add_argument("--report", choices=RUNTIMES, help="Write the installed version as JSON.")
+ parser.add_argument(
+ "--point-at-latest", choices=RUNTIMES, help="Canary: set the pin to upstream latest."
+ )
+ parser.add_argument("--out", type=Path, help="With --report: the JSON file to write.")
+ parser.add_argument(
+ "--bump-from", type=Path, help="Record every report JSON in this folder that agrees."
+ )
+ args, extra = parser.parse_known_args(argv)
+ if args.point_at_latest:
+ _emit(point_at_latest(args.point_at_latest))
+ return 0
+ if args.report:
+ found = report(args.report)
+ if args.out:
+ args.out.write_text(json.dumps(found), encoding="utf-8")
+ _emit(found)
+ return 0
+ if args.bump_from:
+ _emit({"changed": "true" if bump_from(args.bump_from) else "false"})
+ return 0
+ if args.pin:
+ _emit(pin(args.pin))
+ return 0
+ if args.bump:
+ _emit({"changed": "true" if bump(args.bump, args.version, args.commit) else "false"})
+ return 0
+ tests = _existing(HEADLESS if args.headless else SUITE)
+ if args.list:
+ print("\n".join(tests))
+ return 0
+ command = [sys.executable, "-m", "pytest", *tests, "-q", "-p", "no:cacheprovider", *extra]
+ # No CREATE_NO_WINDOW: this runs in a CI console, and on Windows that flag
+ # detaches pytest from it, so its report would vanish.
+ return subprocess.call(command, cwd=REPO_ROOT) # noqa: S603 — this interpreter
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/ci/classify_changes.py b/scripts/ci/classify_changes.py
index f0161e1a6b..d58d0f563d 100644
--- a/scripts/ci/classify_changes.py
+++ b/scripts/ci/classify_changes.py
@@ -36,6 +36,12 @@ import sys
from collections.abc import Iterable
from pathlib import Path
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+ sys.path.insert(0, str(_REPO_ROOT))
+
+from scripts.ci import agent_runtime_suite # noqa: E402
+
# Trees the Python suite never reads (verified by grepping tests/ for each).
# Everything NOT listed keeps the python lane on — unknown means relevant.
_PY_IRRELEVANT_PREFIXES = (
@@ -233,6 +239,7 @@ LANES = (
"macos_desktop",
"installer",
"updater",
+ "agent_runtimes",
)
@@ -276,6 +283,10 @@ def classify(paths: Iterable[str], *, full: bool = False) -> dict[str, bool]:
"macos_desktop": _any(changed, _MACOS_PREFIXES, _MACOS_FILES),
"installer": _any(changed, _INSTALLER_PREFIXES, _INSTALLER_FILES),
"updater": _any(changed, _UPDATER_PREFIXES, _UPDATER_FILES),
+ # Hermes / OpenClaw agents, proven on all three OSes and with the
+ # real runtimes (scripts/ci/agent_runtime_suite.py owns the table).
+ "agent_runtimes": any(agent_runtime_suite.touches(p) for p in changed)
+ or _any(changed, (), _DEPS_FILES),
"full": False,
}
diff --git a/scripts/ci/required_results.py b/scripts/ci/required_results.py
index 711c8f2f81..4c1faf0c89 100644
--- a/scripts/ci/required_results.py
+++ b/scripts/ci/required_results.py
@@ -36,6 +36,7 @@ LANE_JOBS = {
"browser": {"browser"},
"installer": {"installer"},
"updater": {"updater"},
+ "agent_runtimes": {"agent-runtimes-unit", "agent-runtimes-headless", "agent-runtimes-e2e"},
}
diff --git a/scripts/ci/run_tests_parallel.py b/scripts/ci/run_tests_parallel.py
index 830cc60173..24d7a529c2 100644
--- a/scripts/ci/run_tests_parallel.py
+++ b/scripts/ci/run_tests_parallel.py
@@ -56,6 +56,12 @@ MAX_FILE_TIMEOUT = 900.0
BATCH_TARGET_SECONDS = 45.0
BATCH_MAX_FILES = 12
_OK_EXIT_CODES = {0, 5} # 5 = every test deselected / none collected
+# A new batch waits while less than this much memory is left to commit. A local
+# run shares the machine with the user's apps: eight batches on a box already
+# near its commit limit once ran Windows out of virtual memory, and every
+# process that allocated next (a Claude Code pane, OBS) died with 0xC0000409.
+MEMORY_RESERVE_BYTES = 6 * 1024**3
+MEMORY_POLL_SECONDS = 2.0
# --------------------------------------------------------------------------- discovery
@@ -138,6 +144,89 @@ def file_timeout(file: str, durations: dict[str, float]) -> float:
# --------------------------------------------------------------------------- execution
+def available_memory() -> int | None:
+ """Bytes the OS can still hand out, or None where it cannot be read.
+
+ Windows reports the commit headroom (RAM plus page file): that is the
+ limit an allocation fails against. Linux reports MemAvailable.
+ """
+ if os.name == "nt":
+ import ctypes
+
+ class _MemoryStatusEx(ctypes.Structure):
+ _fields_ = [
+ ("dwLength", ctypes.c_ulong),
+ ("dwMemoryLoad", ctypes.c_ulong),
+ ("ullTotalPhys", ctypes.c_ulonglong),
+ ("ullAvailPhys", ctypes.c_ulonglong),
+ ("ullTotalPageFile", ctypes.c_ulonglong),
+ ("ullAvailPageFile", ctypes.c_ulonglong),
+ ("ullTotalVirtual", ctypes.c_ulonglong),
+ ("ullAvailVirtual", ctypes.c_ulonglong),
+ ("ullAvailExtendedVirtual", ctypes.c_ulonglong),
+ ]
+
+ status = _MemoryStatusEx()
+ status.dwLength = ctypes.sizeof(_MemoryStatusEx)
+ if not ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(status)):
+ return None
+ return int(status.ullAvailPageFile)
+ try:
+ with open("/proc/meminfo", encoding="ascii") as meminfo:
+ for line in meminfo:
+ if line.startswith("MemAvailable:"):
+ return int(line.split()[1]) * 1024
+ except (OSError, ValueError):
+ return None # macOS and other systems without /proc: no gate
+ return None
+
+
+class MemoryGate:
+ """Holds back a new batch while the machine is short of memory.
+
+ A batch only waits while another one is running, so the gate can slow a
+ run down but never stall it: with nothing else in flight the next batch
+ always starts, and its finish is what frees the memory others wait for.
+ """
+
+ def __init__(
+ self,
+ reserve: int = MEMORY_RESERVE_BYTES,
+ probe=available_memory,
+ poll_seconds: float = MEMORY_POLL_SECONDS,
+ ):
+ self.reserve = reserve
+ self.probe = probe
+ self.poll_seconds = poll_seconds
+ self.running = 0
+ self.waits = 0
+ self._cond = threading.Condition()
+
+ def _short(self) -> bool:
+ free = self.probe()
+ return free is not None and free < self.reserve
+
+ def acquire(self) -> None:
+ with self._cond:
+ warned = False
+ while self.running > 0 and self._short():
+ if not warned:
+ self.waits += 1
+ warned = True
+ print(
+ f"[runner] under {self.reserve // 1024**3} GiB memory left; "
+ f"waiting for one of {self.running} running batches",
+ flush=True,
+ )
+ self._cond.wait(self.poll_seconds)
+ self.running += 1
+
+ def release(self) -> None:
+ with self._cond:
+ self.running -= 1
+ self._cond.notify_all()
+
+
@dataclass
class RunResult:
files: list[str]
@@ -214,10 +303,17 @@ def parse_junit(path: Path, files: list[str]) -> tuple[list[str], dict[str, floa
class Runner:
- def __init__(self, args: argparse.Namespace, durations: dict[str, float], workdir: Path):
+ def __init__(
+ self,
+ args: argparse.Namespace,
+ durations: dict[str, float],
+ workdir: Path,
+ gate: MemoryGate | None = None,
+ ):
self.args = args
self.durations = durations
self.workdir = workdir
+ self.gate = gate or MemoryGate()
self._seq = 0
self._lock = threading.Lock()
@@ -254,24 +350,28 @@ class Runner:
popen_kwargs["creationflags"] = getattr(subprocess, "CREATE_NO_WINDOW", 0)
else:
popen_kwargs["start_new_session"] = True
+ self.gate.acquire()
started = time.monotonic()
timed_out = False
- with log.open("wb") as sink:
- proc = subprocess.Popen( # noqa: S603
- cmd,
- cwd=REPO_ROOT,
- stdout=sink,
- stderr=subprocess.STDOUT,
- stdin=subprocess.DEVNULL,
- env=env,
- **popen_kwargs, # type: ignore[arg-type]
- )
- try:
- exit_code = proc.wait(timeout=timeout)
- except subprocess.TimeoutExpired:
- timed_out = True
- _kill_tree(proc)
- exit_code = proc.wait()
+ try:
+ with log.open("wb") as sink:
+ proc = subprocess.Popen( # noqa: S603
+ cmd,
+ cwd=REPO_ROOT,
+ stdout=sink,
+ stderr=subprocess.STDOUT,
+ stdin=subprocess.DEVNULL,
+ env=env,
+ **popen_kwargs, # type: ignore[arg-type]
+ )
+ try:
+ exit_code = proc.wait(timeout=timeout)
+ except subprocess.TimeoutExpired:
+ timed_out = True
+ _kill_tree(proc)
+ exit_code = proc.wait()
+ finally:
+ self.gate.release()
duration = time.monotonic() - started
failed, seconds, counts = parse_junit(junit, files)
tail = ""
diff --git a/scripts/ci/select_tests.py b/scripts/ci/select_tests.py
index efb83e6622..24b297e874 100644
--- a/scripts/ci/select_tests.py
+++ b/scripts/ci/select_tests.py
@@ -12,6 +12,8 @@ Selection is textual and deliberately generous — FAIL OPEN:
(import or monkeypatch target) and every ``test_b*.py``;
* any other changed file (frontend source, docs, assets) selects the tests
that mention its path or its file stem;
+* a change the agent-runtime lane covers adds that lane's whole suite
+ (``agent_runtime_suite.SUITE``);
* conftest, packaging, lockfiles or the pipeline itself select EVERYTHING,
and so does a selection larger than :data:`ALL_RATIO` of the suite.
@@ -31,6 +33,7 @@ REPO_ROOT = Path(__file__).resolve().parents[2]
if str(REPO_ROOT) not in sys.path:
sys.path.insert(0, str(REPO_ROOT))
+from scripts.ci import agent_runtime_suite # noqa: E402
from scripts.ci.run_tests_parallel import discover # noqa: E402
ALL_RATIO = 0.35
@@ -97,6 +100,11 @@ def select(changed: list[str], tests: list[str], texts: dict[str, str]) -> tuple
chosen.add(test)
if touches_product:
chosen.update(t for t in SMOKE if t in test_set)
+ if any(agent_runtime_suite.touches(path) for path in changed):
+ # The runtimes are driven by the chat and the society; a change on
+ # either side runs the whole chain, not only the importing tests.
+ for entry in agent_runtime_suite.SUITE:
+ chosen.update(t for t in tests if t == entry or t.startswith(entry.rstrip("/") + "/"))
if len(chosen) > ALL_RATIO * max(1, len(tests)):
return "all", list(tests)
if not chosen:
diff --git a/scripts/spikes/agent_runtimes_e2e.py b/scripts/spikes/agent_runtimes_e2e.py
index 941422a5a3..322b2c25ac 100644
--- a/scripts/spikes/agent_runtimes_e2e.py
+++ b/scripts/spikes/agent_runtimes_e2e.py
@@ -17,6 +17,7 @@ import json
import os
import sys
import tempfile
+import time
import uuid
from pathlib import Path
from typing import Any
@@ -29,10 +30,10 @@ from jarvis.agent_runtimes.acp import AcpTurn, frame_line # noqa: E402
from jarvis.agent_runtimes.base import RuntimeTurn # noqa: E402
from jarvis.agent_runtimes.model_map import ModelRoute # noqa: E402
from jarvis.core.control_key import get_control_key # noqa: E402
+from jarvis.core.process_tree import make_process_tree # noqa: E402
+from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS # noqa: E402
from tests.fakes.fake_openai_server import MODEL_ID, FakeOpenAIServer # noqa: E402
-_STDERR = Path(tempfile.gettempdir()) / "jarvis-runtime-e2e-stderr.log"
-
class _IO:
def __init__(self, proc: asyncio.subprocess.Process) -> None:
@@ -63,37 +64,120 @@ async def _run(name: str, turn: RuntimeTurn, text: str) -> tuple[AcpTurn, _IO]:
auto_allow=True,
report_session=launch.vendor_session,
)
+ tree = make_process_tree("runtime-e2e")
+ proc = None
+ try:
+ with (turn.workspace.parent / "runtime-stderr.log").open("ab") as stderr:
+ proc = await asyncio.create_subprocess_exec(
+ *launch.argv,
+ cwd=str(launch.cwd),
+ env=launch.env,
+ stdin=asyncio.subprocess.PIPE,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=stderr,
+ limit=16 * 1024 * 1024,
+ creationflags=NO_WINDOW_CREATIONFLAGS,
+ start_new_session=os.name != "nt",
+ )
+ tree.assign(proc.pid)
+ io = _IO(proc)
+ assert proc.stdin is not None and proc.stdout is not None
+ proc.stdin.write(acp.opening_frame().encode("utf-8"))
+ await proc.stdin.drain()
+
+ async def pump() -> None:
+ assert proc.stdout is not None and proc.stdin is not None
+ while raw := await proc.stdout.readline():
+ try:
+ obj = json.loads(raw)
+ except ValueError:
+ continue # upstream diagnostic output is not an ACP frame
+ if isinstance(obj, dict):
+ await acp.on_message(obj, io)
+ if acp.saw_result and not proc.stdin.is_closing():
+ proc.stdin.close()
+
+ await asyncio.wait_for(pump(), timeout=180)
+ await asyncio.wait_for(proc.wait(), timeout=30)
+ return acp, io
+ finally:
+ tree.close()
+ try:
+ if proc is not None:
+ if proc.returncode is None:
+ try:
+ proc.kill()
+ except ProcessLookupError:
+ pass # the process tree already reaped it
+ await asyncio.wait_for(proc.wait(), timeout=10)
+ finally:
+ if launch.release is not None:
+ launch.release()
+
+
+def _key_on_disk(root: Path, key: str) -> bool:
+ for path in root.rglob("*") if root.exists() else ():
+ if "installs" in path.parts or not path.is_file():
+ continue
+ try:
+ if path.stat().st_size < 5_000_000 and key in path.read_text(
+ encoding="utf-8", errors="replace"
+ ):
+ return True
+ except OSError: # locked by a process the runtime left: reported below
+ print(" unreadable:", path.name)
+ return False
+
+
+def keep_user_path() -> None:
+ """A spike never edits the machine's PATH: the app's one-time cleanup of
+ stale Hermes entries (``path_cleanup``) stays the app's job."""
+ from jarvis.agent_runtimes import path_cleanup
+
+ path_cleanup._done = True # noqa: SLF001 — the spike opts out of an app duty
+
+
+def user_path_snapshot() -> str:
+ """The user's persistent PATH (Windows), to prove a run never changed it."""
+ if sys.platform != "win32":
+ return ""
+ import winreg
+
+ with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment") as key:
+ try:
+ return str(winreg.QueryValueEx(key, "Path")[0])
+ except FileNotFoundError:
+ return ""
+
+
+async def prepare(name: str) -> float:
+ """Run the runtime's setup preparation (Hermes: the shared data root) like
+ the setup job does, before any turn; returns how long it took."""
+ command = getattr(driver(name), "prepare_command", lambda: None)()
+ if not command:
+ return 0.0
+ argv, env = command
+ started = time.monotonic()
+ tree = make_process_tree("runtime-e2e-prepare")
proc = await asyncio.create_subprocess_exec(
- *launch.argv,
- cwd=str(launch.cwd),
- env=launch.env,
- stdin=asyncio.subprocess.PIPE,
- stdout=asyncio.subprocess.PIPE,
- stderr=_STDERR.open("ab"),
- limit=16 * 1024 * 1024,
+ *argv,
+ env=env,
+ stdin=asyncio.subprocess.DEVNULL,
+ stdout=asyncio.subprocess.DEVNULL,
+ stderr=asyncio.subprocess.DEVNULL,
+ creationflags=NO_WINDOW_CREATIONFLAGS,
+ start_new_session=os.name != "nt",
)
- io = _IO(proc)
- assert proc.stdin is not None and proc.stdout is not None
- proc.stdin.write(acp.opening_frame().encode("utf-8"))
- await proc.stdin.drain()
-
- async def pump() -> None:
- assert proc.stdout is not None and proc.stdin is not None
- while raw := await proc.stdout.readline():
- try:
- obj = json.loads(raw)
- except ValueError:
- continue
- if isinstance(obj, dict):
- await acp.on_message(obj, io)
- if acp.saw_result and not proc.stdin.is_closing():
- proc.stdin.close()
-
- await asyncio.wait_for(pump(), timeout=180)
- await asyncio.wait_for(proc.wait(), timeout=30)
- if launch.release is not None:
- launch.release()
- return acp, io
+ tree.assign(proc.pid)
+ try:
+ code = await asyncio.wait_for(proc.wait(), timeout=1800)
+ finally:
+ tree.close()
+ elapsed = time.monotonic() - started
+ print(f"prepare: exit {code} in {elapsed:.1f} s")
+ if code == 0:
+ driver(name).mark_prepared(driver(name).detect(refresh=True))
+ return elapsed
async def main(name: str) -> int:
@@ -101,13 +185,20 @@ async def main(name: str) -> int:
base.runtimes_root = lambda: tmp / "agent_runtimes" # keep the real data dir clean
workspace = tmp / "workspace"
workspace.mkdir()
+ keep_user_path() # before detect(): it would run the app's PATH cleanup
status = driver(name).detect(refresh=True)
print("detect:", status.to_dict())
if not status.ready:
return 2
+ path_before = user_path_snapshot()
+ await prepare(name)
with FakeOpenAIServer() as server:
key = "sk-e2e-" + uuid.uuid4().hex
- route = ModelRoute("local-openai", MODEL_ID, server.base_url, "chat_completions", None)
+ # The key travels like the gateway token: process environment only.
+ route = ModelRoute(
+ "local-openai", MODEL_ID, server.base_url, "chat_completions", key,
+ context_window=131_072, # Hermes refuses models below 64k
+ )
# JARVIS_E2E_MCP=<url>|<agent id>: hand the runtime a running Jarvis'
# MCP server (a dev instance) and make the fake model call a real tool.
mcp = os.environ.get("JARVIS_E2E_MCP", "")
@@ -130,7 +221,9 @@ async def main(name: str) -> int:
if mcp_url
else "first message"
)
+ started = time.monotonic()
first, io1 = await _run(name, turn, opening)
+ print(f"turn 1 took {time.monotonic() - started:.1f} s")
if server.requests:
offered = [
(t.get("function") or {}).get("name", "")
@@ -148,19 +241,20 @@ async def main(name: str) -> int:
print("turn 2:", second.status, second.error, repr(second.result_text[:80]))
history = len(server.requests[-1].get("messages", [])) if server.requests else 0
print(" model saw", history, "messages on turn 2")
- home = tmp / "agent_runtimes" / name / agent_id
- written = sorted(p.name for p in home.iterdir())
- print(" runtime home:", written)
- secret_leak = any(
- p.is_file()
- and p.stat().st_size < 5_000_000
- and key in p.read_text(encoding="utf-8", errors="replace")
- for p in home.rglob("*")
- )
- # Only a fixed word is printed: never anything derived from the key.
- print(" key written to disk:", "YES" if secret_leak else "no")
+ # Stopped first: a running Gateway holds some of its files open.
await driver(name).stop()
- ok = first.status == "done" and second.status == "done" and history > 2 and not secret_leak
+ secret_leak = _key_on_disk(tmp / "agent_runtimes", key)
+ # Only a fixed word is printed: never anything derived from the key.
+ print(" key written to disk:", "YES" if secret_leak else "no")
+ path_kept = user_path_snapshot() == path_before
+ print(" user PATH unchanged:", "yes" if path_kept else "NO")
+ ok = (
+ first.status == "done"
+ and second.status == "done"
+ and history > 2
+ and not secret_leak
+ and path_kept
+ )
print("RESULT:", "PASS" if ok else "FAIL")
return 0 if ok else 1
diff --git a/scripts/spikes/agent_runtimes_gateway_e2e.py b/scripts/spikes/agent_runtimes_gateway_e2e.py
index 8a6fa99b39..b3d48dbb9c 100644
--- a/scripts/spikes/agent_runtimes_gateway_e2e.py
+++ b/scripts/spikes/agent_runtimes_gateway_e2e.py
@@ -13,8 +13,9 @@ state lands in a temporary folder.
python scripts/spikes/agent_runtimes_gateway_e2e.py openclaw openai-codex
python scripts/spikes/agent_runtimes_gateway_e2e.py hermes openai-codex --replay
-``--replay`` keeps ChatGPT out of it (no allowance used): the subscription
-answers from a stand-in in its own event format.
+``--replay`` uses a scripted provider: ``openai-codex`` checks Responses and
+``ollama`` checks Chat Completions (no network to a model, no allowance used).
+Failed runs retain their diagnostic log under ``eval-results/`` (gitignored).
"""
from __future__ import annotations
@@ -25,17 +26,23 @@ import sys
import tempfile
import threading
import time
+from contextlib import contextmanager
from pathlib import Path
ROOT = Path(__file__).resolve().parents[2]
sys.path.insert(0, str(ROOT))
sys.path.insert(0, str(ROOT / "scripts" / "spikes"))
-from agent_runtimes_e2e import _run # noqa: E402
+from agent_runtimes_e2e import ( # noqa: E402
+ _run,
+ keep_user_path,
+ prepare,
+ user_path_snapshot,
+)
from jarvis.agent_runtimes import base, driver, gateway # noqa: E402
from jarvis.agent_runtimes.base import RuntimeTurn # noqa: E402
-from jarvis.agent_runtimes.model_map import route_for # noqa: E402
+from jarvis.agent_runtimes.model_map import prepare_route # noqa: E402
from jarvis.core import runtime_refs # noqa: E402
from jarvis.core.config import load_config # noqa: E402
@@ -46,7 +53,8 @@ def _free_port() -> int:
return int(sock.getsockname()[1])
-def _serve(port: int) -> None:
+@contextmanager
+def _serve(port: int):
import uvicorn
from fastapi import FastAPI
@@ -57,13 +65,21 @@ def _serve(port: int) -> None:
app.include_router(router)
guarded = SurfaceSecurity(app, control_key_validator=lambda token: False)
config = uvicorn.Config(guarded, host="127.0.0.1", port=port, log_level="warning")
- threading.Thread(target=uvicorn.Server(config).run, daemon=True).start()
- for _ in range(100):
- with socket.socket() as sock:
- if sock.connect_ex(("127.0.0.1", port)) == 0:
+ server = uvicorn.Server(config)
+ thread = threading.Thread(target=server.run, daemon=True)
+ thread.start()
+ try:
+ for _ in range(100):
+ if server.started:
+ yield
return
- time.sleep(0.05)
- raise RuntimeError("the gateway did not start")
+ time.sleep(0.05)
+ raise RuntimeError("the gateway did not start")
+ finally:
+ server.should_exit = True
+ thread.join(timeout=5)
+ if thread.is_alive():
+ raise RuntimeError("the gateway did not stop")
class _ReplayUpstream:
@@ -141,7 +157,8 @@ class _ReplayUpstream:
}
async def list_models(self) -> list[dict]:
- return [{"id": "gpt-replay", "label": "Replay"}]
+ return [{"id": "gpt-replay", "label": "Replay", "context_length": 128000,
+ "max_output_tokens": 8192}]
async def _pick_model(wanted: str) -> str:
@@ -154,27 +171,107 @@ async def _pick_model(wanted: str) -> str:
async def main(name: str, provider: str, wanted: str) -> int:
+ # This two-turn smoke may cause runtime retries. It cannot enforce a paid
+ # one-call budget; refuse paid providers instead of silently overspending.
+ if provider not in {"ollama", "local-openai", "openai-codex"}:
+ raise ValueError("This multi-turn smoke supports local models and subscriptions only.")
+ replay = wanted == "--replay"
+ from jarvis.agent_chat import runner_api
+ from jarvis.brain.model_catalog import ModelCatalog
+ from jarvis.costs import ledger
+
+ previous_client = gateway._client
+ previous_ready = gateway.subscription_ready
+ previous_build = runner_api.build_brain
+ previous_catalog = gateway._CATALOG
+ previous_ledger = ledger.ledger_path()
+ previous_root = base.runtimes_root
+ previous_url = runtime_refs.get_api_base_url()
if wanted == "--replay":
wanted = "gpt-replay"
upstream = _ReplayUpstream()
gateway._client = lambda account_id: upstream # noqa: SLF001 — the spike's stand-in
gateway.subscription_ready = lambda account_id="": True
- tmp = Path(tempfile.mkdtemp(prefix=f"jarvis-{name}-sub-e2e-"))
- base.runtimes_root = lambda: tmp / "agent_runtimes"
+ from tests.fakes.fake_runtime_brain import ReplayRuntimeBrain
+
+ runner_api.build_brain = lambda provider, model: ReplayRuntimeBrain()
+ try:
+ with tempfile.TemporaryDirectory(prefix=f"jarvis-{name}-gateway-e2e-") as directory:
+ tmp = Path(directory)
+ base.runtimes_root = lambda: tmp / "agent_runtimes"
+ ledger.set_ledger_path(tmp / "usage.db")
+ gateway._CATALOG = ModelCatalog(cache_path=tmp / "catalog.json")
+ result = 1
+ try:
+ result = await _check(name, provider, wanted, tmp, replay=replay)
+ return result
+ finally:
+ await driver(name).stop()
+ await asyncio.to_thread(ledger.flush)
+ # Gateway calls are metered: the ledger writer holds usage.db in
+ # this folder open, so it is closed (pointed back) before the
+ # folder is removed — on Windows an open file blocks that.
+ await asyncio.to_thread(ledger.set_ledger_path, previous_ledger)
+ gateway._CATALOG = previous_catalog
+ if result != 0:
+ log = tmp / "runtime-stderr.log"
+ if log.exists():
+ target = ROOT / "eval-results" / f"{name}-{time.time_ns()}.log"
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_bytes(log.read_bytes())
+ print("diagnostic:", target)
+ finally:
+ gateway._client = previous_client
+ gateway.subscription_ready = previous_ready
+ runner_api.build_brain = previous_build
+ gateway._CATALOG = previous_catalog
+ ledger.set_ledger_path(previous_ledger)
+ base.runtimes_root = previous_root
+ runtime_refs.set_api_base_url(previous_url or "")
+
+
+async def _check(name: str, provider: str, wanted: str, tmp: Path, *, replay: bool) -> int:
workspace = tmp / "workspace"
workspace.mkdir()
+ keep_user_path() # before detect(): it would run the app's PATH cleanup
status = driver(name).detect(refresh=True)
print("detect:", status.ready, status.problem)
if not status.ready:
return 2
+ path_before = user_path_snapshot()
+ await prepare(name)
port = _free_port()
- _serve(port)
+ with _serve(port):
+ result = await _turns(name, provider, wanted, workspace, port, replay=replay)
+ if user_path_snapshot() != path_before:
+ print("user PATH changed: FAIL")
+ return 1
+ print("user PATH unchanged: yes")
+ return result
+
+
+async def _turns(name, provider, wanted, workspace, port, *, replay):
runtime_refs.set_api_base_url(f"http://127.0.0.1:{port}")
model = await _pick_model(wanted) if provider == "openai-codex" else wanted
- route = await asyncio.to_thread(
- route_for, load_config(), provider, model, agent_id="sub-e2e-agent"
- )
+ if replay:
+ from jarvis.core.config import BrainProviderConfig, JarvisConfig, OllamaModelOptions
+
+ replay_config = JarvisConfig()
+ replay_config.brain.providers["ollama"] = BrainProviderConfig(
+ models={model: OllamaModelOptions(num_ctx=128000)}
+ )
+
+ # No catalog lookup to a real server on the Chat Completions replay.
+ if provider != "openai-codex":
+ from jarvis.agent_runtimes.model_map import route_for
+
+ route = route_for(replay_config, provider, model, agent_id="sub-e2e-agent")
+ else:
+ route = await prepare_route(replay_config, provider, model, agent_id="sub-e2e-agent")
+ else:
+ route = await prepare_route(load_config(), provider, model, agent_id="sub-e2e-agent")
print("route:", route.provider, route.model, route.transport, route.base_url)
+ print("limits:", route.context_window, route.max_output_tokens)
turn = RuntimeTurn(
agent_id="sub-e2e-agent",
agent_name="Probe",
@@ -186,7 +283,9 @@ async def main(name: str, provider: str, wanted: str) -> int:
mcp_url=None,
control_key=None,
)
+ started = time.monotonic()
first, _io1 = await _run(name, turn, "Remember the word PELICAN. Reply with exactly: READY")
+ print(f"turn 1 took {time.monotonic() - started:.1f} s")
print("turn 1:", first.status, first.error, repr(first.result_text[:120]))
turn.resume = first.vendor_session
second, _io2 = await _run(name, turn, "Which word did I ask you to remember? One word.")
diff --git a/tests/contract/test_routine_chats.py b/tests/contract/test_routine_chats.py
index 098d3d4a32..7f069cb7c6 100644
--- a/tests/contract/test_routine_chats.py
+++ b/tests/contract/test_routine_chats.py
@@ -156,3 +156,48 @@ async def test_cancelling_routine_preserves_main_chat(world, monkeypatch, via_ch
if not routine.done():
routine.cancel()
await asyncio.gather(routine, return_exceptions=True)
+
+
+async def test_a_run_that_leaves_its_owners_runtime_says_so(world, tmp_path, monkeypatch):
+ from dataclasses import replace
+
+ from jarvis.society import routine_runner
+ from jarvis.society.events import AgentRuntime
+
+ runtime, service, _, _ = world
+ store = TaskStore(tmp_path / "tasks.db")
+ await store.init()
+ runtime.task_services = lambda: (store, None)
+ hermes = replace(await runtime.roster.get("mailbox"), runtime=AgentRuntime.HERMES)
+ get = runtime.roster.get
+
+ async def roster_get(agent_id):
+ return hermes if agent_id == "mailbox" else await get(agent_id)
+
+ monkeypatch.setattr(runtime.roster, "get", roster_get)
+ # The run's seat is one Hermes cannot drive: it runs on Jarvis' own loop.
+ monkeypatch.setattr(routine_runner, "_run_runtime", lambda agent, provider: "")
+ spec = build_task_spec(hermes, title="Inbox", prompt="Read mail", schedule={"kind": "every"})
+ task_id = str(await store.insert(spec))
+ try:
+ await run_owned_routine(runtime, task_id, spec.tags, spec.action.prompt)
+ steps = [step["payload"] for step in (await store.get(task_id))["steps"]]
+ notes = [p for p in steps if p.get("event") == "routine_runtime_fallback"]
+ assert len(notes) == 1 and notes[0]["runtime"] == "hermes"
+ run = next(p["session_id"] for p in steps if p.get("event") == "routine_chat")
+ notices = [
+ e["payload"] for e in service.store.list_events(run) if e["kind"] == "notice"
+ ]
+ assert [n["kind"] for n in notices] == ["routine_runtime_fallback"]
+ finally:
+ await store.close()
+
+
+def test_only_a_run_off_its_owners_external_runtime_is_noted():
+ from types import SimpleNamespace
+
+ from jarvis.society.routine_runner import _left_runtime
+
+ assert _left_runtime(SimpleNamespace(runtime="hermes"), "") == "hermes"
+ assert _left_runtime(SimpleNamespace(runtime="openclaw"), "openclaw") == ""
+ assert _left_runtime(SimpleNamespace(runtime="jarvis"), "") == ""
diff --git a/tests/fakes/fake_acp_agent.py b/tests/fakes/fake_acp_agent.py
index dfb66a6977..8407687c9a 100644
--- a/tests/fakes/fake_acp_agent.py
+++ b/tests/fakes/fake_acp_agent.py
@@ -19,8 +19,19 @@ What a prompt does depends on its text:
* contains ``FAIL`` — the prompt request answers a JSON-RPC error;
* contains ``HANG`` — answers, then keeps running after stdin closes (a
runtime whose child holds the pipe);
+* contains ``SLOW`` — streams "working", then waits; a ``session/cancel``
+ ends the prompt with ``stopReason: cancelled`` (and is logged), unless
+ ``FAKE_ACP_IGNORE_CANCEL`` is set;
+* contains ``TOOLWAIT`` — starts a tool call and never finishes it;
+* contains ``SETSID`` — starts a child in its own session (POSIX ``setsid``)
+ that sleeps, writes its pid to ``FAKE_ACP_CHILD_FILE``, then answers;
+* contains ``BIG`` — first sends one line of ``FAKE_ACP_BIG_BYTES`` bytes;
+* contains ``EXIT`` — exits with status 3 without answering;
+* contains ``MAXTOK`` — answers text, then ``stopReason: max_tokens``;
* otherwise — ``echo: <text>`` streamed in two chunks plus a thought.
+``FAKE_ACP_MODE=hang-after-init`` answers ``initialize`` and then nothing.
+
``session/load`` of an unknown id answers ``{}`` (Hermes' behaviour).
"""
@@ -31,8 +42,10 @@ import os
import sys
import time
import uuid
+from http.client import HTTPConnection
from pathlib import Path
from typing import Any
+from urllib.parse import urlsplit
def _store_path() -> Path | None:
@@ -86,9 +99,87 @@ def _read() -> dict[str, Any] | None:
def _prompt(rid: Any, session_id: str, text: str, store: dict[str, list[str]]) -> None:
store.setdefault(session_id, []).append(text)
_save_store(store)
+ if endpoint := os.environ.get("FAKE_ACP_GATEWAY"):
+ url = urlsplit(endpoint)
+ assert url.scheme == "http" and url.hostname == "127.0.0.1"
+ connection = HTTPConnection(url.hostname, url.port, timeout=5)
+ try:
+ connection.request(
+ "POST",
+ url.path + "/chat/completions",
+ body=json.dumps(
+ {
+ "model": "fake-model",
+ "messages": [{"role": "user", "content": text}],
+ }
+ ),
+ headers={
+ "Authorization": "Bearer " + os.environ["FAKE_ACP_TOKEN"],
+ "Content-Type": "application/json",
+ },
+ )
+ response = connection.getresponse()
+ if response.status < 400:
+ result = json.load(response)
+ _text(session_id, result["choices"][0]["message"]["content"])
+ else:
+ # Reproduce runtimes that retry for minutes or render an
+ # upstream failure as a normal, completed assistant response.
+ if os.environ.get("FAKE_ACP_RETRY_WAIT"):
+ time.sleep(600)
+ _text(
+ session_id, "custom rate-limited every one of 3 attempts; hermes fallback add"
+ )
+ finally:
+ connection.close()
+ _send({"jsonrpc": "2.0", "id": rid, "result": {"stopReason": "end_turn"}})
+ return
if "FAIL" in text:
_send({"jsonrpc": "2.0", "id": rid, "error": {"code": -32000, "message": "model down"}})
return
+ if "EXIT" in text:
+ sys.exit(3)
+ if "BIG" in text:
+ size = int(os.environ.get("FAKE_ACP_BIG_BYTES", str(17 * 1024 * 1024)))
+ sys.stdout.write("x" * size + "\n")
+ sys.stdout.flush()
+ if "SLOW" in text or "TOOLWAIT" in text:
+ if "TOOLWAIT" in text:
+ _update(
+ session_id,
+ {
+ "sessionUpdate": "tool_call",
+ "toolCallId": "tc-wait",
+ "title": "terminal",
+ "kind": "execute",
+ "status": "in_progress",
+ "rawInput": {"command": "sleep 600"},
+ },
+ )
+ else:
+ _text(session_id, "working")
+ while True:
+ frame = _read()
+ if frame is None:
+ return
+ if frame.get("method") == "session/cancel" and not os.environ.get(
+ "FAKE_ACP_IGNORE_CANCEL"
+ ):
+ _send({"jsonrpc": "2.0", "id": rid, "result": {"stopReason": "cancelled"}})
+ return
+ if "SETSID" in text:
+ import subprocess
+
+ child = subprocess.Popen( # noqa: S603 — a sleeping copy of this interpreter
+ [sys.executable, "-c", "import time; time.sleep(600)"],
+ start_new_session=os.name != "nt",
+ stdin=subprocess.DEVNULL,
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL,
+ )
+ child_file = os.environ.get("FAKE_ACP_CHILD_FILE")
+ if child_file:
+ Path(child_file).write_text(str(child.pid), encoding="utf-8")
if "ASK" in text:
_send(
{
@@ -141,7 +232,7 @@ def _prompt(rid: Any, session_id: str, text: str, store: dict[str, list[str]]) -
"jsonrpc": "2.0",
"id": rid,
"result": {
- "stopReason": "end_turn",
+ "stopReason": "max_tokens" if "MAXTOK" in text else "end_turn",
"usage": {"inputTokens": 11, "outputTokens": 7, "totalTokens": 18},
},
}
@@ -159,6 +250,11 @@ def main() -> int:
method = frame.get("method")
rid = frame.get("id")
params = frame.get("params") or {}
+ if method == "initialize" and os.environ.get("FAKE_ACP_MODE") == "hang-after-init":
+ _send({"jsonrpc": "2.0", "id": rid, "result": {"protocolVersion": 1}})
+ while _read() is not None:
+ pass # never opens a session; ends with stdin
+ return 0
if method == "initialize":
_send(
{
diff --git a/tests/fakes/fake_openclaw.py b/tests/fakes/fake_openclaw.py
new file mode 100644
index 0000000000..f4ce829bbd
--- /dev/null
+++ b/tests/fakes/fake_openclaw.py
@@ -0,0 +1,62 @@
+"""A stand-in for the ``openclaw`` CLI, for Gateway supervision tests.
+
+Run as ``python tests/fakes/fake_openclaw.py <args>``. Understands:
+
+* ``--version`` — prints ``OpenClaw 2026.9.8 (fake)``;
+* ``gateway run --port N`` — serves ``GET /healthz`` (200) on 127.0.0.1:N
+ until killed; exits 1 at once when the port is taken;
+* ``doctor --fix ...`` — writes ``doctor.done`` into the working folder.
+
+``FAKE_OPENCLAW_MODE``:
+
+* ``config-once`` — the Gateway exits 78 (``EX_CONFIG``) until doctor ran;
+* ``doctor-hang`` — doctor writes its pid to ``doctor.pid`` and sleeps.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+
+
+class _Health(BaseHTTPRequestHandler):
+ def do_GET(self) -> None: # noqa: N802 — http.server API
+ ok = self.path == "/healthz"
+ self.send_response(200 if ok else 404)
+ self.end_headers()
+ self.wfile.write(b"ok" if ok else b"no")
+
+ def log_message(self, format: str, *args: object) -> None: # noqa: A002
+ return
+
+
+def main(argv: list[str]) -> int:
+ mode = os.environ.get("FAKE_OPENCLAW_MODE", "")
+ if argv[:1] == ["--version"]:
+ print("OpenClaw 2026.9.8 (fake)")
+ return 0
+ if argv[:1] == ["doctor"]:
+ if mode == "doctor-hang":
+ Path("doctor.pid").write_text(str(os.getpid()), encoding="utf-8")
+ time.sleep(600)
+ Path("doctor.done").write_text("1", encoding="utf-8")
+ return 0
+ if argv[:2] == ["gateway", "run"]:
+ if mode == "config-once" and not Path("doctor.done").exists():
+ return 78
+ port = int(argv[argv.index("--port") + 1])
+ try:
+ server = HTTPServer(("127.0.0.1", port), _Health)
+ except OSError:
+ return 1 # EADDRINUSE: the port was taken
+ server.serve_forever()
+ return 0
+ print(f"fake openclaw: unsupported {argv}", file=sys.stderr)
+ return 2
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/tests/fakes/fake_runtime_brain.py b/tests/fakes/fake_runtime_brain.py
new file mode 100644
index 0000000000..acc8f12a87
--- /dev/null
+++ b/tests/fakes/fake_runtime_brain.py
@@ -0,0 +1,14 @@
+"""Scripted gateway provider for real runtime transport checks, never inference."""
+
+from jarvis.core.protocols import BrainDelta
+
+
+class ReplayRuntimeBrain:
+ context_window = 128000
+
+ async def complete(self, request):
+ assistant = any(message.role == "assistant" for message in request.messages)
+ remembered = any("PELICAN" in str(message.content) for message in request.messages)
+ answer = ("PELICAN" if remembered else "UNKNOWN") if assistant else "READY"
+ yield BrainDelta(content=answer)
+ yield BrainDelta(usage={"input_tokens": 10, "output_tokens": 2}, finish_reason="stop")
diff --git a/tests/unit/agent_chat/test_agent_chat_service.py b/tests/unit/agent_chat/test_agent_chat_service.py
index 56fb82a520..4e127945ef 100644
--- a/tests/unit/agent_chat/test_agent_chat_service.py
+++ b/tests/unit/agent_chat/test_agent_chat_service.py
@@ -800,6 +800,48 @@ def test_allow_always_on_a_kit_that_handles_it_does_not_flip_the_mode(
asyncio.run(scenario())
+def test_a_card_nothing_waits_on_closes_when_clicked(tmp_path: Path) -> None:
+ """A click on a card whose asker is gone closes it for good; nothing runs."""
+
+ async def scenario() -> None:
+ svc = AgentChatService(AgentChatStore(":memory:"))
+ session = svc.store.create_session(
+ provider="claude-api", model="m", effort="medium", cwd=str(tmp_path)
+ )
+ sid = session.session_id
+ payload = {"turn_id": "t1", "approval_id": "gone", "call_id": "c1", "name": "Bash"}
+ svc.store.append_event(sid, {"kind": "turn_started", "ts_ms": 1, "payload": {"turn_id": "t1"}})
+ svc.store.append_event(sid, {"kind": "approval_required", "ts_ms": 2, "payload": payload})
+
+ assert not svc.resolve_approval(sid, "gone", "allow")
+ assert await svc.close_stale_approval(sid, "gone")
+ last = svc.store.list_events(sid)[-1]
+ assert last["kind"] == "approval_resolved"
+ assert last["payload"] == {"turn_id": "t1", "approval_id": "gone", "decision": "expired"}
+ # Closed once; an id the chat never showed is not invented into it.
+ assert not await svc.close_stale_approval(sid, "gone")
+ assert not await svc.close_stale_approval(sid, "never-shown")
+ assert len(svc.store.list_events(sid)) == 3
+
+ asyncio.run(scenario())
+
+
+def test_the_approval_route_answers_410_for_an_expired_card(tmp_path: Path) -> None:
+ app = _app(tmp_path)
+ with TestClient(app) as client:
+ svc = app.state.agent_chat_factory()
+ app.state.agent_chat = svc
+ sid = svc.store.create_session(
+ provider="claude-api", model="m", effort="medium", cwd=str(tmp_path)
+ ).session_id
+ payload = {"turn_id": "t1", "approval_id": "gone", "call_id": "c1", "name": "Bash"}
+ svc.store.append_event(sid, {"kind": "approval_required", "ts_ms": 2, "payload": payload})
+ expired = client.post(f"/api/agent-chat/sessions/{sid}/approvals/gone", json={"decision": "allow"})
+ assert expired.status_code == 410
+ unknown = client.post(f"/api/agent-chat/sessions/{sid}/approvals/nope", json={"decision": "allow"})
+ assert unknown.status_code == 404
+
+
def test_a_new_process_closes_turns_a_restart_left_open(tmp_path: Path) -> None:
"""A turn whose runner died with the old process ends as failed, not Working for ever."""
db = tmp_path / "agent_chat.db"
diff --git a/tests/unit/agent_chat/test_cli_catalog_isolation.py b/tests/unit/agent_chat/test_cli_catalog_isolation.py
index 043c692e86..b28fb21130 100644
--- a/tests/unit/agent_chat/test_cli_catalog_isolation.py
+++ b/tests/unit/agent_chat/test_cli_catalog_isolation.py
@@ -71,7 +71,7 @@ async def test_catalog_route_uses_session_seat_and_keeps_empty_results(monkeypat
default_cwd=lambda surface: str(tmp_path),
)
monkeypatch.setattr(agent_accounts, "resolve", lambda account: SimpleNamespace(id=account))
- monkeypatch.setattr(routes, "_service", lambda request: service)
+ request = SimpleNamespace(app=SimpleNamespace(state=SimpleNamespace(agent_chat=service)))
monkeypatch.setattr(routes, "_cli_installed", lambda runner: True)
seen = []
@@ -81,7 +81,7 @@ async def test_catalog_route_uses_session_seat_and_keeps_empty_results(monkeypat
monkeypatch.setattr(routes, "_live_cli_models", live)
before = rc.ACCOUNT_OVERRIDE.get()
- result = await routes.get_catalog(None, session_id="chat", account_id="wrong-seat")
+ result = await routes.get_catalog(request, session_id="chat", account_id="wrong-seat")
assert seen == [("seat-two", tmp_path)]
assert rc.ACCOUNT_OVERRIDE.get() == before
codex = next(row for row in result["providers"] if row["id"] == "openai-codex")
diff --git a/tests/unit/agent_chat/test_controls.py b/tests/unit/agent_chat/test_controls.py
index 68767206cc..d99780a5df 100644
--- a/tests/unit/agent_chat/test_controls.py
+++ b/tests/unit/agent_chat/test_controls.py
@@ -109,6 +109,57 @@ async def test_rejected_message_cannot_replace_a_newer_control_status() -> None:
assert controls.state(sid).last_status == "failed"
+async def test_continue_preserves_a_rate_limited_question_and_its_approval_mode():
+ svc = FakeService()
+ sid = seat(svc)
+ question = "Was ist deine Aufgabe"
+ svc.store.append_event(sid, make_event("user_message", {"text": question}))
+ svc.store.append_event(
+ sid,
+ make_event(
+ "turn_finished",
+ {
+ "turn_id": "limited",
+ "status": "error",
+ "error": "HTTP 429; use /continue later",
+ },
+ ),
+ )
+ controls = ChatControls(svc, adapters=[])
+ result = await controls.execute(sid, request("continue"))
+ assert result.status == "started"
+ await svc.wait_turn(sid)
+ assert question in svc.sent[-1][0]
+ assert svc.store.list_events(sid)[0]["payload"]["text"] == question
+ session = svc.store.get_session(sid)
+ assert session.permission_mode == "ask" and session.provider == "openai"
+
+
+async def test_continue_names_why_a_delegated_failure_cannot_be_resumed():
+ svc = FakeService()
+ sid = seat(svc)
+ # A teammate's message: delivered without a user_message, then rate limited.
+ svc.store.append_event(sid, make_event("turn_started", {"turn_id": "incoming"}))
+ svc.store.append_event(
+ sid,
+ make_event("turn_finished", {"turn_id": "incoming", "status": "error", "error": "429"}),
+ )
+ controls = ChatControls(svc, adapters=[])
+ result = await controls.execute(sid, request("continue"))
+ assert result.status == "failed"
+ assert "not from you" in result.error
+ assert svc.sent == []
+
+
+async def test_continue_without_any_failure_says_there_is_nothing_to_continue():
+ svc = FakeService()
+ sid = seat(svc)
+ controls = ChatControls(svc, adapters=[])
+ result = await controls.execute(sid, request("continue"))
+ assert result.status == "failed"
+ assert result.error == "There is no interrupted task to continue"
+
+
def test_plan_build_and_review_preserve_original_permissions_and_history() -> None:
async def scenario() -> None:
svc = FakeService()
diff --git a/tests/unit/agent_chat/test_send_queue.py b/tests/unit/agent_chat/test_send_queue.py
index 55607c856f..a29ea9b8cd 100644
--- a/tests/unit/agent_chat/test_send_queue.py
+++ b/tests/unit/agent_chat/test_send_queue.py
@@ -18,6 +18,8 @@ class BusyChat:
def __init__(self, surface: str = "society") -> None:
self.surface = surface
self.busy: set[str] = set()
+ #: Idle chats whose agent is busy elsewhere: ``send`` still refuses.
+ self.refusing: set[str] = set()
self.sent: list[tuple[str, str]] = []
self.notices: list[tuple[str, dict]] = []
self.fail_next = False
@@ -32,7 +34,7 @@ class BusyChat:
return session_id in self.busy
async def send(self, session_id, text, attachments=None, *, tool_choices=None) -> str:
- if session_id in self.busy:
+ if session_id in self.busy or session_id in self.refusing:
raise SessionBusy(session_id)
if self.fail_next:
self.fail_next = False
@@ -152,11 +154,40 @@ async def test_a_message_that_fails_to_start_is_reported_and_the_next_runs():
assert "refused" not in failed[0]["text"]
-async def test_a_message_that_waits_too_long_is_reported(monkeypatch):
+async def test_a_message_behind_a_long_running_turn_still_runs(monkeypatch):
+ # A Hermes agent's first turn may set its runtime up for many minutes; the
+ # message behind it waits for that turn, not for a fixed idle timer.
+ monkeypatch.setattr(send_queue, "MAX_WAIT_S", 0.03)
+ chat = BusyChat()
+ chat.busy.add("society:scout")
+ queue_id = (await send_or_queue(chat, "society:scout", "after the setup"))[1]
+ await asyncio.sleep(0.15)
+ assert not any(p.get("status") == "failed" for _, p in chat.notices)
+ chat.busy.clear()
+ await _until(lambda: chat.sent)
+ assert chat.sent == [("society:scout", "after the setup")]
+ assert any(p == {"kind": "message_dequeued", "queue_id": queue_id, "status": "sent"}
+ for _, p in chat.notices)
+
+
+async def test_a_message_the_idle_chat_cannot_take_is_reported(monkeypatch):
monkeypatch.setattr(send_queue, "MAX_WAIT_S", 0.05)
chat = BusyChat()
chat.busy.add("society:scout")
queue_id = (await send_or_queue(chat, "society:scout", "too late"))[1]
+ chat.busy.clear()
+ chat.refusing.add("society:scout") # the agent works in another chat
+ await _until(lambda: any(p.get("status") == "failed" for _, p in chat.notices))
+ assert chat.sent == []
+ failed = [p for _, p in chat.notices if p.get("status") == "failed"]
+ assert failed[0]["queue_id"] == queue_id
+
+
+async def test_a_message_that_waits_too_long_is_reported(monkeypatch):
+ monkeypatch.setattr(send_queue, "MAX_TOTAL_WAIT_S", 0.05)
+ chat = BusyChat()
+ chat.busy.add("society:scout")
+ queue_id = (await send_or_queue(chat, "society:scout", "too late"))[1]
await _until(lambda: any(p.get("status") == "failed" for _, p in chat.notices))
assert chat.sent == []
failed = [p for _, p in chat.notices if p.get("status") == "failed"]
diff --git a/tests/unit/agent_chat/test_service_startup_responsive.py b/tests/unit/agent_chat/test_service_startup_responsive.py
new file mode 100644
index 0000000000..d584c33ca2
--- /dev/null
+++ b/tests/unit/agent_chat/test_service_startup_responsive.py
@@ -0,0 +1,77 @@
+"""First chat requests must not block the loop behind a service builder thread."""
+
+import asyncio
+import threading
+from types import SimpleNamespace
+
+import pytest
+
+from jarvis.ui.web import agent_chat_routes as routes
+
+
+async def test_catalog_waits_for_one_service_without_blocking_the_event_loop(monkeypatch):
+ entered = threading.Event()
+ finish = threading.Event()
+ loop_was_blocked = []
+ builds = []
+ service = SimpleNamespace(
+ default_cwd=lambda _surface: ".",
+ store=SimpleNamespace(chat_selection=lambda: None),
+ )
+
+ def factory():
+ builds.append(True)
+ entered.set()
+ if not finish.wait(2):
+ loop_was_blocked.append(True)
+ return service
+
+ async def models():
+ return {}
+
+ monkeypatch.setattr(routes, "_live_cli_models", models)
+ monkeypatch.setattr(routes, "_catalog_rows", lambda *_args: [])
+ state = SimpleNamespace(agent_chat=None, agent_chat_factory=factory)
+ request = SimpleNamespace(app=SimpleNamespace(state=state))
+ owner = asyncio.create_task(asyncio.to_thread(routes._service_from_state, state))
+ try:
+ assert await asyncio.to_thread(entered.wait, 2)
+ # Construction needs the loop to make progress. A blocking Lock on
+ # this thread deadlocks it until the test's emergency deadline expires.
+ asyncio.get_running_loop().call_soon(finish.set)
+ result = await routes.get_catalog(request, surface="jarvis")
+ assert result["providers"] == []
+ assert not loop_was_blocked
+ assert len(builds) == 1
+ assert await owner is state.agent_chat is service
+ finally:
+ finish.set()
+ await owner
+
+
+async def test_cancelled_request_does_not_abandon_or_duplicate_service_construction():
+ entered = threading.Event()
+ finish = threading.Event()
+ service = object()
+ builds = []
+
+ def factory():
+ builds.append(True)
+ entered.set()
+ assert finish.wait(2)
+ return service
+
+ state = SimpleNamespace(agent_chat=None, agent_chat_factory=factory)
+ request = SimpleNamespace(app=SimpleNamespace(state=state))
+ first = asyncio.create_task(routes._async_service(request))
+ try:
+ assert await asyncio.to_thread(entered.wait, 2)
+ first.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await first
+ second = asyncio.create_task(routes._async_service(request))
+ finish.set()
+ assert await second is service
+ assert state.agent_chat is service and len(builds) == 1
+ finally:
+ finish.set()
diff --git a/tests/unit/agent_chat/test_task_recovery.py b/tests/unit/agent_chat/test_task_recovery.py
index f2678ce4e2..718811cf56 100644
--- a/tests/unit/agent_chat/test_task_recovery.py
+++ b/tests/unit/agent_chat/test_task_recovery.py
@@ -87,6 +87,9 @@ def test_empty_discovery_is_not_success_and_does_not_depend_on_reply_language():
"auth_failed",
"invalid token",
"quota exceeded",
+ "HTTP 429",
+ "rate limit",
+ "custom rate-limited every one of 3 attempts",
],
)
def test_real_blockers_do_not_trigger_automatic_workarounds(reason):
@@ -223,6 +226,24 @@ async def test_user_denial_never_starts_a_second_attempt(turn, monkeypatch):
assert len(attempts) == 1
+async def test_rate_limit_after_unfinished_tools_never_starts_automatic_recovery(turn, monkeypatch):
+ handle, events, origin = turn
+ attempts = []
+
+ async def once(handle, *args, **kwargs):
+ attempts.append(1)
+ await handle.emit(make_event("tool_call", {"call_id": "c", "name": "Read"}))
+ await handle.emit(
+ make_event("tool_result", {"call_id": "c", "output": "not found", "is_error": True})
+ )
+ return runner_cli._Outcome("error", "HTTP 429 (rate limit).", {}, None, "existing")
+
+ monkeypatch.setattr(runner_cli, "_run_cli_once", once)
+ await runner_cli.run_cli_turn(handle, origin.user_text, "hermes-cli", identity=True)
+ assert len(attempts) == 1
+ assert events[-1]["payload"]["status"] == "error"
+
+
async def test_resolved_language_remains_visible_to_the_caller(turn, monkeypatch):
handle, _, origin = turn
diff --git a/tests/unit/agent_chat/test_turn_host.py b/tests/unit/agent_chat/test_turn_host.py
index 7555ad8272..d10df36e87 100644
--- a/tests/unit/agent_chat/test_turn_host.py
+++ b/tests/unit/agent_chat/test_turn_host.py
@@ -331,6 +331,85 @@ async def test_a_restarted_app_carries_on_the_thread_turn_the_host_kept(
assert store.open_turns() == []
+async def test_a_restarted_app_asks_again_on_the_card_already_on_screen(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, app_host_mode: Any
+) -> None:
+ """The replayed permission prompt reuses the open card instead of stacking a dead one.
+
+ 2026-10-06: after a restart the thread showed "Approval needed (2)" — the
+ card from before the restart on top, whose buttons answered "no such
+ pending approval", and the live one hidden behind it.
+ """
+ monkeypatch.setattr(turn_host_client, "spool_dir", lambda: tmp_path / "spool")
+ monkeypatch.setattr(turn_host_client, "_host_alive", lambda state: False)
+
+ async def no_live_host(*, start: bool = True) -> None:
+ return None
+
+ monkeypatch.setattr(turn_host_client, "get_client", no_live_host)
+ db = tmp_path / "agent_chat.db"
+ store = AgentChatStore(db)
+ session = store.create_session(
+ provider="claude-api", model="m", effort="medium", cwd=str(tmp_path), surface="agent"
+ )
+ sid = session.session_id
+
+ def card(approval_id: str, call_id: str) -> dict[str, Any]:
+ payload = {"turn_id": "t1", "approval_id": approval_id, "call_id": call_id, "name": "Bash"}
+ return {"kind": "approval_required", "ts_ms": 2_000, "payload": payload}
+
+ store.append_event(sid, {"kind": "turn_started", "ts_ms": 1_000, "payload": {"turn_id": "t1"}})
+ # Two restarts already stacked two cards for the same call; one card has no call id.
+ for event in (card("first", "tu1"), card("second", "tu1"), card("loose", "")):
+ store.append_event(sid, event)
+ lines = [
+ _CLAUDE_LINES[0],
+ _CLAUDE_LINES[2],
+ {
+ "type": "control_request",
+ "request_id": "r1",
+ "request": {
+ "subtype": "can_use_tool",
+ "tool_name": "Bash",
+ "input": {"command": "ls"},
+ "tool_use_id": "tu1",
+ },
+ },
+ *_CLAUDE_LINES[3:],
+ ]
+ record = _spool_record(tmp_path, session_id=sid, turn_id="t1", acked=2)
+ record["stdout"] = [json.dumps(line) for line in lines]
+ Path(record["spool_path"]).write_text(json.dumps(record), encoding="utf-8")
+
+ svc = AgentChatService(AgentChatStore(db))
+ await svc.wait_reattached()
+ for _ in range(200):
+ if svc.pending_approvals(sid):
+ break
+ await asyncio.sleep(0.02)
+ assert svc.pending_approvals(sid) == ["second"]
+ closed = {
+ e["payload"]["approval_id"]: e["payload"]["decision"]
+ for e in store.list_events(sid)
+ if e["kind"] == "approval_resolved"
+ }
+ assert closed == {"first": "expired", "loose": "expired"}
+ asked = [e["payload"] for e in store.list_events(sid) if e["kind"] == "approval_required"]
+ assert asked[-1]["approval_id"] == "second"
+ assert asked[-1]["call_id"] == "tu1"
+
+ assert svc.resolve_approval(sid, "second", "allow")
+ run = svc._running.get(sid)
+ if run is not None and run.task is not None:
+ await asyncio.wait_for(run.task, timeout=10)
+ events = store.list_events(sid)
+ resolved = [e["payload"] for e in events if e["kind"] == "approval_resolved"]
+ assert resolved[-1] == {"turn_id": "t1", "approval_id": "second", "decision": "allow"}
+ assert events[-1]["kind"] == "turn_finished"
+ assert events[-1]["payload"]["status"] == "done"
+ assert svc._unanswered == {}
+
+
def test_tests_and_scripts_never_reach_the_users_turn_host() -> None:
host_mode.reset()
assert not turn_host_client.host_available()
diff --git a/tests/unit/agent_runtimes/conftest.py b/tests/unit/agent_runtimes/conftest.py
new file mode 100644
index 0000000000..b84464f5a3
--- /dev/null
+++ b/tests/unit/agent_runtimes/conftest.py
@@ -0,0 +1,25 @@
+"""Every runtime test runs against a private user-data folder.
+
+Runtime code derives its folders from ``jarvis.core.paths.user_data_dir`` (agent
+folders, Jarvis' own OpenClaw copy, the last-good pins). A test that redirected
+only ``runtimes_root`` once wrote stub binaries into the person's real
+``agent_runtimes/openclaw-cli`` (2026-10-07), which the live app would then
+have tried to run. The whole package is redirected here instead.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+
[email protected](autouse=True)
+def _private_user_data(
+ monkeypatch: pytest.MonkeyPatch, tmp_path_factory: pytest.TempPathFactory
+) -> Path:
+ from jarvis.core import paths
+
+ root = tmp_path_factory.mktemp("jarvis-user-data")
+ monkeypatch.setattr(paths, "user_data_dir", lambda: root)
+ return root
diff --git a/tests/unit/agent_runtimes/test_acp_runner.py b/tests/unit/agent_runtimes/test_acp_runner.py
index b7259291d2..2b2eeac15a 100644
--- a/tests/unit/agent_runtimes/test_acp_runner.py
+++ b/tests/unit/agent_runtimes/test_acp_runner.py
@@ -5,8 +5,12 @@ from __future__ import annotations
import asyncio
import json
import os
+import socket
import sys
+import threading
+import time
from pathlib import Path
+from types import SimpleNamespace
from typing import Any
import pytest
@@ -211,3 +215,321 @@ def test_the_turn_slot_is_released_once_after_a_normal_turn(monkeypatch, tmp_pat
released: list[int] = []
_turn(monkeypatch, tmp_path, "hello", released=released)
assert released == [1]
+
+
+def model_gateway(monkeypatch):
+ """A real loopback gateway with a fake provider, never a vendor connection."""
+ import uvicorn
+ from fastapi import FastAPI
+
+ from jarvis.agent_runtimes import gateway
+ from jarvis.core.protocols import BrainDelta
+ from jarvis.ui.web.runtime_gateway_routes import router
+ from jarvis.ui.web.surface_security import SurfaceSecurity
+
+ state = {"limited": True, "calls": []}
+
+ class Limit(Exception):
+ status_code = 429
+ headers = {"Retry-After": "60"}
+
+ async def deltas(grant, model, request):
+ state["calls"].append((grant, request))
+ if state["limited"]:
+ raise Limit("private provider body")
+ yield BrainDelta(content="I review contributor pull requests for security issues.")
+
+ monkeypatch.setattr(gateway, "_deltas", deltas)
+ gateway.reset()
+ app = FastAPI()
+ app.include_router(router)
+ secured = SurfaceSecurity(app, control_key_validator=lambda _token: False)
+ sock = socket.socket()
+ sock.bind(("127.0.0.1", 0))
+ server = uvicorn.Server(uvicorn.Config(secured, log_level="critical", lifespan="off"))
+ thread = threading.Thread(target=server.run, kwargs={"sockets": [sock]}, daemon=True)
+ thread.start()
+ try:
+ deadline = time.monotonic() + 5
+ while not server.started and time.monotonic() < deadline:
+ time.sleep(0.01)
+ assert server.started
+ yield f"http://127.0.0.1:{sock.getsockname()[1]}{gateway.BASE_PATH}", state
+ finally:
+ server.should_exit = True
+ thread.join(timeout=5)
+ sock.close()
+ gateway.reset()
+ assert not thread.is_alive()
+
+
[email protected]("wait", [False, True], ids=["false-success", "long-retry"])
+def test_gateway_failure_ends_the_real_acp_runner_and_recovery_keeps_the_question(
+ monkeypatch,
+ tmp_path,
+ model_gateway,
+ wait,
+):
+ from jarvis.agent_runtimes import gateway
+ from jarvis.agent_runtimes.base import RuntimeLaunch, RuntimeStatus
+ from jarvis.agent_runtimes.model_map import ModelRoute
+
+ endpoint, state = model_gateway
+ released = []
+
+ class Driver:
+ label = "Fake runtime"
+
+ def detect(self):
+ return RuntimeStatus("hermes", self.label, installed=True, ready=True)
+
+ async def launch(self, turn):
+ env = dict(os.environ)
+ env.update(
+ FAKE_ACP_GATEWAY=endpoint,
+ FAKE_ACP_TOKEN=turn.route.api_key,
+ FAKE_ACP_STORE=str(tmp_path / "gateway-store.json"),
+ )
+ if wait:
+ env["FAKE_ACP_RETRY_WAIT"] = "1"
+ return RuntimeLaunch(
+ argv=[sys.executable, str(_AGENT)],
+ env=env,
+ cwd=tmp_path,
+ acp_resume=turn.resume,
+ release=lambda: released.append(1),
+ )
+
+ async def agent(_agent_id):
+ return SimpleNamespace(
+ agent_id="hermit", name="Hermit", denies=[], grants=[], grant_mode="all",
+ )
+
+ async def route(_cfg, provider, model, *, agent_id, account_id, session_id):
+ return ModelRoute(
+ provider,
+ model,
+ endpoint,
+ "chat_completions",
+ gateway.grant_token(agent_id, provider, account_id, scope=session_id),
+ )
+
+ monkeypatch.setattr(runner_acp, "driver", lambda _name: Driver())
+ monkeypatch.setattr(runner_acp, "_agent", agent)
+ monkeypatch.setattr(runner_acp, "_config", lambda: None)
+ monkeypatch.setattr(runner_acp, "prepare_route", route)
+
+ async def run(vendor=None):
+ events = []
+
+ async def emit(event):
+ events.append(event)
+
+ async def ask(*args):
+ pytest.fail("The test asks no tool permission")
+
+ handle = TurnHandle(
+ session=_session(tmp_path, vendor=vendor, mode="ask"),
+ turn_id="test-rate-limit",
+ emit=emit,
+ request_approval=ask,
+ cancel=asyncio.Event(),
+ )
+ result = await asyncio.wait_for(
+ rc.run_cli_turn(handle, "Was ist deine Aufgabe", "hermes-cli"),
+ timeout=10,
+ )
+ return result, events
+
+ vendor, events = asyncio.run(run())
+ assert _finished(events)["status"] == "error"
+ assert "HTTP 429" in _finished(events)["error"]
+ assert "Try again in" in _finished(events)["error"]
+ assert "/continue" not in _finished(events)["error"]
+ assert _texts(events) == []
+ assert len(state["calls"]) == 1 and released == [1]
+ assert not gateway._FAILURES
+ history = json.loads((tmp_path / "gateway-store.json").read_text(encoding="utf-8"))
+ assert any("Was ist deine Aufgabe" in prompt for turns in history.values() for prompt in turns)
+
+ # Simulate the provider's cooldown expiring, then resume the saved session.
+ gateway._COOLDOWNS.clear()
+ state["limited"] = False
+ _, recovered = asyncio.run(run(vendor))
+ assert _finished(recovered)["status"] == "done"
+ assert _texts(recovered) == ["I review contributor pull requests for security issues."]
+ assert len(state["calls"]) == 2 and released == [1, 1]
+ assert not gateway._FAILURES
+
+
+# ------------------------------------------- cancel, watchdog, containment
+
+
+def _run_live(
+ monkeypatch: pytest.MonkeyPatch,
+ tmp_path: Path,
+ text: str,
+ *,
+ env: dict[str, str] | None = None,
+ mode: str = "bypass",
+ cancel_after: float | None = None,
+ ask_delay: float = 0.0,
+) -> tuple[list[dict[str, Any]], Path]:
+ """One turn against the fake agent; returns its events and frame log."""
+ frames = tmp_path / "frames.log"
+
+ async def fake_plan(handle: Any, runner: str, *, prompt: str, cwd: Path, resume, identity):
+ child_env = dict(os.environ)
+ child_env.update(FAKE_ACP_STORE=str(tmp_path / "store.json"), FAKE_ACP_LOG=str(frames))
+ child_env.update(env or {})
+ return rc.CliPlan(
+ argv=[sys.executable, str(_AGENT)],
+ env=child_env,
+ stdin_text=None,
+ shape="acp",
+ vendor_session=None,
+ keep_stdin=True,
+ acp=AcpTurn(
+ turn_id=handle.turn_id,
+ cwd=str(cwd),
+ prompt_text=prompt,
+ auto_allow=mode == "bypass",
+ ),
+ )
+
+ monkeypatch.setattr(runner_acp, "plan_runtime_turn", fake_plan)
+ events: list[dict[str, Any]] = []
+
+ async def emit(event: dict[str, Any]) -> None:
+ events.append(event)
+
+ async def ask(call_id: str, name: str, args: dict[str, Any], summary: str) -> str:
+ await asyncio.sleep(ask_delay)
+ return "allow"
+
+ async def run() -> None:
+ handle = TurnHandle(
+ session=_session(tmp_path, vendor=None, mode=mode),
+ turn_id="t-live",
+ emit=emit,
+ request_approval=ask,
+ cancel=asyncio.Event(),
+ )
+ if cancel_after is not None:
+ asyncio.get_running_loop().call_later(cancel_after, handle.cancel.set)
+ await asyncio.wait_for(rc.run_cli_turn(handle, text, "hermes-cli"), timeout=60)
+
+ asyncio.run(run())
+ return events, frames
+
+
+def _methods(frames: Path) -> list[str]:
+ if not frames.is_file():
+ return []
+ return [
+ str(json.loads(line).get("method") or "")
+ for line in frames.read_text(encoding="utf-8").splitlines()
+ if line.strip()
+ ]
+
+
+def test_stop_asks_the_runtime_to_cancel_before_killing_it(monkeypatch, tmp_path):
+ """An OpenClaw run lives in its Gateway: killing the bridge alone never stops it."""
+ started = time.monotonic()
+ events, frames = _run_live(monkeypatch, tmp_path, "SLOW please", cancel_after=1.5)
+ assert _finished(events)["status"] == "cancelled"
+ assert "session/cancel" in _methods(frames)
+ assert time.monotonic() - started < 15
+
+
+def test_a_runtime_that_ignores_cancel_is_still_ended(monkeypatch, tmp_path):
+ monkeypatch.setattr(rc, "_ACP_CANCEL_GRACE_S", 0.5)
+ events, frames = _run_live(
+ monkeypatch, tmp_path, "SLOW", env={"FAKE_ACP_IGNORE_CANCEL": "1"}, cancel_after=1.0
+ )
+ assert _finished(events)["status"] == "cancelled"
+ assert "session/cancel" in _methods(frames)
+
+
+def test_a_runtime_that_never_opens_its_session_is_stopped(monkeypatch, tmp_path):
+ monkeypatch.setattr(rc, "_ACP_HANDSHAKE_TIMEOUT_S", 1.0)
+ monkeypatch.setattr(rc, "_ACP_WATCH_TICK_S", 0.2)
+ events, _ = _run_live(monkeypatch, tmp_path, "hi", env={"FAKE_ACP_MODE": "hang-after-init"})
+ finished = _finished(events)
+ assert finished["status"] == "error"
+ assert "did not open its session" in finished["error"]
+
+
+def test_a_silent_model_is_stopped_with_a_plain_reason(monkeypatch, tmp_path):
+ monkeypatch.setattr(rc, "_ACP_IDLE_TIMEOUT_S", 1.0)
+ monkeypatch.setattr(rc, "_ACP_WATCH_TICK_S", 0.2)
+ events, frames = _run_live(monkeypatch, tmp_path, "SLOW")
+ finished = _finished(events)
+ assert finished["status"] == "error"
+ assert "stopped responding" in finished["error"]
+ assert "session/cancel" in _methods(frames)
+
+
+def test_a_long_tool_call_is_not_a_stall(monkeypatch, tmp_path):
+ monkeypatch.setattr(rc, "_ACP_IDLE_TIMEOUT_S", 0.5)
+ monkeypatch.setattr(rc, "_ACP_WATCH_TICK_S", 0.1)
+ events, _ = _run_live(monkeypatch, tmp_path, "TOOLWAIT", cancel_after=2.5)
+ # Ended by the person after 2.5 s, not by the 0.5 s watchdog.
+ assert _finished(events)["status"] == "cancelled"
+
+
+def test_an_open_approval_card_is_not_a_stall(monkeypatch, tmp_path):
+ monkeypatch.setattr(rc, "_ACP_IDLE_TIMEOUT_S", 0.5)
+ monkeypatch.setattr(rc, "_ACP_WATCH_TICK_S", 0.1)
+ events, _ = _run_live(monkeypatch, tmp_path, "ASK now", mode="ask", ask_delay=2.0)
+ assert _finished(events)["status"] == "done"
+ assert _texts(events) == ["permission: yes"]
+
+
+def test_an_oversized_frame_ends_the_turn_cleanly(monkeypatch, tmp_path):
+ monkeypatch.setattr(rc, "_READLINE_LIMIT", 64 * 1024)
+ events, _ = _run_live(monkeypatch, tmp_path, "BIG", env={"FAKE_ACP_BIG_BYTES": "200000"})
+ finished = _finished(events)
+ assert finished["status"] == "error"
+ assert "larger than" in finished["error"]
+
+
+def test_a_runtime_that_exits_without_answering_is_an_error(monkeypatch, tmp_path):
+ events, _ = _run_live(monkeypatch, tmp_path, "EXIT now")
+ finished = _finished(events)
+ assert finished["status"] == "error"
+ assert "3" in (finished["error"] or "")
+
+
+def test_a_cut_off_answer_stands_and_says_so(monkeypatch, tmp_path):
+ events, _ = _run_live(monkeypatch, tmp_path, "MAXTOK")
+ assert _finished(events)["status"] == "done"
+ assert _texts(events) == ["echo: MAXTOK"]
+ notices = [e["payload"] for e in events if e["kind"] == "notice"]
+ assert [n["stop_reason"] for n in notices] == ["max_tokens"]
+
+
+def test_a_detached_child_of_the_runtime_is_reaped_with_the_turn(monkeypatch, tmp_path):
+ """Hermes starts shell commands in their own session (POSIX setsid);
+ killpg never reaches them, the descendant tracker does (Windows: the job)."""
+ import psutil
+
+ child_file = tmp_path / "child.pid"
+ events, _ = _run_live(
+ monkeypatch, tmp_path, "SETSID", env={"FAKE_ACP_CHILD_FILE": str(child_file)}
+ )
+ assert _finished(events)["status"] == "done"
+ pid = int(child_file.read_text(encoding="utf-8"))
+
+ def running() -> bool:
+ # Gone or a zombie both mean reaped; the pid can vanish between calls.
+ try:
+ return psutil.Process(pid).status() != psutil.STATUS_ZOMBIE
+ except psutil.NoSuchProcess:
+ return False
+
+ deadline = time.monotonic() + 5
+ while running() and time.monotonic() < deadline:
+ time.sleep(0.1)
+ assert not running()
\ No newline at end of file
diff --git a/tests/unit/agent_runtimes/test_full_model_capacity.py b/tests/unit/agent_runtimes/test_full_model_capacity.py
new file mode 100644
index 0000000000..fa49df7e17
--- /dev/null
+++ b/tests/unit/agent_runtimes/test_full_model_capacity.py
@@ -0,0 +1,162 @@
+"""Use model capacity by default and retain explicit user/request limits."""
+
+import pytest
+
+from jarvis.agent_runtimes import gateway
+from jarvis.agent_runtimes.model_limits import ModelLimits, resolve_limits
+from jarvis.brain.model_catalog import ModelInfo
+from jarvis.core.config import OllamaModelOptions
+from jarvis.core.protocols import BrainDelta, BrainMessage, BrainRequest
+from jarvis.plugins.brain.ollama import OllamaBrain
+
+
+def test_known_output_capacity_is_not_halved():
+ info = ModelInfo("m", "M", context_length=131072, max_output_tokens=100000)
+ assert resolve_limits(None, "openai", "m", info) == ModelLimits(131072, 100000)
+
+
+def test_unknown_output_capacity_does_not_claim_an_eight_k_limit():
+ limits = resolve_limits(None, "openai", "m")
+ assert limits.max_output_tokens is None
+ assert "max_output_tokens" not in limits.wire()
+ req = BrainRequest(messages=(), max_tokens=64000)
+ assert gateway._with_output_capacity(req, limits).max_tokens == 64000
+
+
[email protected]("streaming", [True, False])
[email protected]("requested,expected", [(None, 200000), (180000, 180000), (512, 512)])
+async def test_gateway_uses_model_maximum_when_omitted(monkeypatch, streaming, requested, expected):
+ gateway.reset()
+ token = gateway.grant_token("full", "openai")
+ gateway.register_model(token, "m", ModelLimits(1000000, 200000))
+ body = {"model": "m", "messages": [{"role": "user", "content": "hello"}]}
+ if requested is not None:
+ body["max_completion_tokens"] = requested
+ model, request = gateway.chat_request(body)
+ seen = []
+
+ async def deltas(grant, model, request):
+ seen.append(request.max_tokens)
+ yield BrainDelta(content="done", finish_reason="stop")
+
+ monkeypatch.setattr(gateway, "_deltas", deltas)
+ try:
+ if streaming:
+ stream = await gateway.open_chat_stream(gateway.verify(token), model, request)
+ _ = [chunk async for chunk in stream]
+ else:
+ await gateway.complete_chat(gateway.verify(token), model, request)
+ assert seen == [expected]
+ finally:
+ gateway.reset()
+
+
[email protected]("bad", [True, 0, -1, "8192"])
+def test_invalid_explicit_limits_are_rejected(bad):
+ with pytest.raises(gateway.GatewayError, match="positive integer"):
+ gateway.chat_request(
+ {"model": "m", "messages": [{"role": "user", "content": "hi"}], "max_tokens": bad}
+ )
+
+
+async def test_ollama_really_allocates_the_advertised_context(monkeypatch):
+ from jarvis.brain import ollama_profiles
+
+ configured = OllamaModelOptions(temperature=0.2)
+ brain = OllamaBrain(model="m")
+ other = OllamaBrain(model="m")
+ monkeypatch.setattr(brain, "_model_options", lambda model: configured)
+ monkeypatch.setattr(brain, "_resolve_root", lambda: "http://local.invalid")
+ seen = []
+
+ async def profile(root, model, options):
+ seen.append(options)
+ return "prepared-profile"
+
+ monkeypatch.setattr(ollama_profiles, "ensure_profile", profile)
+ # This is the already resolved limit; the resolver preserves user limits.
+ brain.set_context_window(131072)
+ model, _ = await brain._apply_model_options("m", BrainRequest(messages=()))
+ assert model == "prepared-profile"
+ assert seen[0].num_ctx == brain.context_window == 131072
+ assert seen[0].temperature == 0.2
+ assert configured.num_ctx is None # no mutation of saved settings
+ assert other._requested_context_window is None
+
+
+async def test_a_new_user_limit_is_not_overwritten_by_an_older_plan(monkeypatch):
+ brain = OllamaBrain(model="m")
+ brain.set_context_window(131072)
+ monkeypatch.setattr(brain, "_model_options", lambda model: OllamaModelOptions(num_ctx=16384))
+ with pytest.raises(RuntimeError, match="context changed"):
+ await brain._apply_model_options("m", BrainRequest(messages=()))
+
+
+async def test_ollama_does_not_silently_serve_a_smaller_context(monkeypatch):
+ from jarvis.brain import ollama_profiles
+
+ brain = OllamaBrain(model="m")
+ brain.set_context_window(131072)
+ monkeypatch.setattr(brain, "_model_options", lambda model: None)
+ monkeypatch.setattr(brain, "_resolve_root", lambda: "http://local.invalid")
+
+ async def fail(*args):
+ raise RuntimeError("provider-private-body")
+
+ monkeypatch.setattr(ollama_profiles, "ensure_profile", fail)
+ with pytest.raises(RuntimeError, match="Could not prepare") as caught:
+ await brain._apply_model_options("m", BrainRequest(messages=()))
+ assert "private" not in str(caught.value)
+
+
+async def test_gateway_configures_capable_brain_before_inference(monkeypatch):
+ from jarvis.agent_chat import runner_api
+ from jarvis.core import config
+
+ gateway.reset()
+ token = gateway.grant_token("full", "ollama")
+ gateway.register_model(token, "m", ModelLimits(131072))
+ seen = []
+
+ class Brain:
+ def set_context_window(self, tokens):
+ seen.append(tokens)
+
+ async def complete(self, request):
+ assert seen == [131072]
+ yield BrainDelta(content="ok")
+
+ monkeypatch.setattr(runner_api, "build_brain", lambda provider, model: Brain())
+ monkeypatch.setattr(config, "get_jarvis_agent_secret", lambda provider: None)
+ try:
+ result = [
+ d async for d in gateway._deltas(gateway.verify(token), "m", BrainRequest(messages=()))
+ ]
+ assert result[0].content == "ok"
+ finally:
+ gateway.reset()
+
+
+def test_an_omitted_limit_never_asks_for_more_than_the_context_leaves():
+ """OpenRouter declares max_completion_tokens == context_length for many
+ models; asking for all of it beside any prompt is refused upstream."""
+ limits = ModelLimits(163_840, 163_840)
+ prompt = "x" * 300_000 # about 100k tokens at three characters per token
+ # max_tokens=0: what chat_request builds when the runtime named no limit.
+ req = BrainRequest(messages=(BrainMessage("user", prompt),), max_tokens=0)
+ budget = gateway._with_output_capacity(req, limits).max_tokens
+ assert budget <= 163_840 - 100_000 - 1024
+ assert budget > 50_000
+
+
+def test_an_explicit_limit_is_the_runtimes_choice():
+ limits = ModelLimits(163_840, 163_840)
+ req = BrainRequest(messages=(BrainMessage("user", "x" * 300_000),), max_tokens=120_000)
+ assert gateway._with_output_capacity(req, limits).max_tokens == 120_000
+
+
+def test_a_nearly_full_window_still_sends_a_small_budget():
+ limits = ModelLimits(32_768, None)
+ req = BrainRequest(messages=(BrainMessage("user", "x" * 120_000),), max_tokens=0)
+ assert gateway._with_output_capacity(req, limits).max_tokens == 1024
+
diff --git a/tests/unit/agent_runtimes/test_gateway_brains.py b/tests/unit/agent_runtimes/test_gateway_brains.py
new file mode 100644
index 0000000000..4285f37c8a
--- /dev/null
+++ b/tests/unit/agent_runtimes/test_gateway_brains.py
@@ -0,0 +1,258 @@
+"""How the model gateway runs a provider plugin for a Hermes / OpenClaw agent.
+
+One brain (and HTTP client) per session, model and credential instead of one
+per call; an agent request profile the voice path never sees: agent-scale
+read timeouts, the runtime's own sampling choice, Anthropic prompt caching.
+No provider is contacted: the plugins run against stand-in SDK clients.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+
+from jarvis.agent_runtimes import gateway
+from jarvis.agent_runtimes.model_limits import ModelLimits
+from jarvis.core.protocols import BrainDelta, BrainMessage, BrainRequest
+from jarvis.plugins.brain import _agent_profile
+
+_BODY = {"model": "m", "messages": [{"role": "user", "content": "Hi"}]}
+
+
+class _Client:
+ def __init__(self) -> None:
+ self.closed = False
+
+ async def aclose(self) -> None:
+ self.closed = True
+
+
+class _Brain:
+ """A plugin stand-in that records the profile its call ran under."""
+
+ built: list[_Brain] = []
+
+ def __init__(self, provider: str, model: str) -> None:
+ self._model = model
+ self._client = _Client()
+ self.profiles: list[Any] = []
+ _Brain.built.append(self)
+
+ async def complete(self, request: BrainRequest) -> AsyncIterator[BrainDelta]:
+ self.profiles.append(_agent_profile.current())
+ yield BrainDelta(content="ok", finish_reason="stop")
+
+
+def plugins(monkeypatch: pytest.MonkeyPatch) -> dict[str, str]:
+ import jarvis.agent_chat.runner_api as runner_api
+ import jarvis.core.config as config
+
+ credential = {"key": "sk-first"}
+ _Brain.built = []
+ monkeypatch.setattr(runner_api, "build_brain", _Brain)
+ monkeypatch.setattr(config, "get_jarvis_agent_secret", lambda provider: None)
+ monkeypatch.setattr(
+ config,
+ "resolve_provider_endpoint",
+ lambda provider, **kwargs: SimpleNamespace(base_url=None, credential=credential["key"]),
+ )
+ gateway.reset()
+ yield credential
+ gateway.reset()
+
+
+async def _call(grant: gateway.Grant, body: dict[str, Any] = _BODY) -> None:
+ gateway._MODEL_LIMITS.setdefault(grant, {})["m"] = ModelLimits(200_000, 8_000)
+ model, request = gateway.chat_request(body)
+ stream = await gateway.open_chat_stream(
+ grant, model, request, temperature_given=gateway.temperature_given(body)
+ )
+ async for _ in stream:
+ pass
+
+
+async def test_a_tool_loop_reuses_one_brain_and_its_client(plugins) -> None:
+ grant = gateway.Grant("agent-1", "openai", scope="s1")
+ for _ in range(3):
+ await _call(grant)
+ assert len(_Brain.built) == 1
+
+
+async def test_a_changed_key_or_another_session_gets_its_own_brain(plugins) -> None:
+ await _call(gateway.Grant("agent-1", "openai", scope="s1"))
+ await _call(gateway.Grant("agent-1", "openai", scope="s2"))
+ plugins["key"] = "sk-rotated"
+ await _call(gateway.Grant("agent-1", "openai", scope="s1"))
+ assert len(_Brain.built) == 3
+
+
+async def test_reset_closes_the_idle_clients(plugins) -> None:
+ await _call(gateway.Grant("agent-1", "openai"))
+ client = _Brain.built[0]._client
+ gateway.reset()
+ await asyncio.sleep(0)
+ await asyncio.sleep(0)
+ assert client.closed
+
+
+async def test_an_evicted_brain_in_use_is_closed_only_after_its_call(plugins) -> None:
+ slot = gateway._acquire_brain(("in-use",), lambda: _Brain("openai", "m"))
+ for index in range(gateway._BRAINS_MAX):
+ gateway._release_brain(gateway._acquire_brain((str(index),),
+ lambda: _Brain("openai", "m")))
+ await asyncio.sleep(0)
+ assert slot.retired and not slot.brain._client.closed
+ gateway._release_brain(slot)
+ await asyncio.sleep(0)
+ await asyncio.sleep(0)
+ assert slot.brain._client.closed
+
+
[email protected](("provider", "read_timeout"), [("openai", 300.0), ("ollama", 900.0)])
+async def test_an_agent_call_runs_under_the_agent_profile(plugins, provider, read_timeout) -> None:
+ await _call(gateway.Grant("agent-1", provider))
+ await _call(gateway.Grant("agent-1", provider), {**_BODY, "temperature": 0.2})
+ first, second = _Brain.built[0].profiles
+ assert first.read_timeout_s == read_timeout and first.prompt_cache
+ assert first.omit_temperature and not second.omit_temperature
+ # The profile never leaks out of the call.
+ assert _agent_profile.current() is None
+
+
+# ------------------------------------------------- the plugins under a profile
+
+
+class _Recorder:
+ """Captures the SDK call's keyword arguments and returns an empty stream."""
+
+ def __init__(self) -> None:
+ self.kwargs: dict[str, Any] = {}
+
+
+def _openai_client(recorder: _Recorder) -> Any:
+ async def create(**kwargs: Any) -> Any:
+ recorder.kwargs = kwargs
+
+ async def chunks() -> AsyncIterator[Any]:
+ delta = SimpleNamespace(content="ok", tool_calls=None)
+ yield SimpleNamespace(
+ choices=[SimpleNamespace(delta=delta, finish_reason="stop")], usage=None
+ )
+
+ return chunks()
+
+ return SimpleNamespace(
+ chat=SimpleNamespace(completions=SimpleNamespace(create=create)), base_url="stand-in"
+ )
+
+
+async def _openai_kwargs(profile: Any) -> dict[str, Any]:
+ from jarvis.plugins.brain._openai_base import stream_complete
+
+ recorder = _Recorder()
+ token = _agent_profile.PROFILE.set(profile)
+ try:
+ request = BrainRequest(messages=(BrainMessage("user", "Hi"),), max_tokens=64)
+ async for _ in stream_complete(_openai_client(recorder), "m", request):
+ pass
+ finally:
+ _agent_profile.PROFILE.reset(token)
+ return recorder.kwargs
+
+
+async def test_the_voice_path_sends_what_it_always_sent() -> None:
+ kwargs = await _openai_kwargs(None)
+ assert kwargs["temperature"] == 0.7 and "timeout" not in kwargs
+
+
+async def test_an_agent_call_gets_a_long_read_timeout_and_no_invented_temperature() -> None:
+ profile = _agent_profile.AgentRequestProfile(read_timeout_s=300.0, omit_temperature=True)
+ kwargs = await _openai_kwargs(profile)
+ assert "temperature" not in kwargs
+ assert kwargs["timeout"].read == 300.0 and kwargs["timeout"].connect == 5.0
+
+
+class _AnthropicStream:
+ def __init__(self, recorder: _Recorder, kwargs: dict[str, Any]) -> None:
+ recorder.kwargs = kwargs
+
+ async def __aenter__(self) -> _AnthropicStream:
+ return self
+
+ async def __aexit__(self, *exc: Any) -> None:
+ return None
+
+ def __aiter__(self) -> AsyncIterator[Any]:
+ async def events() -> AsyncIterator[Any]:
+ yield SimpleNamespace(
+ type="message_delta",
+ delta=SimpleNamespace(stop_reason="end_turn"),
+ usage=SimpleNamespace(input_tokens=5, output_tokens=1),
+ )
+
+ return events()
+
+
+async def _anthropic_kwargs(profile: Any, messages: tuple[BrainMessage, ...]) -> dict[str, Any]:
+ from jarvis.plugins.brain._anthropic_base import stream_complete
+
+ recorder = _Recorder()
+ client = SimpleNamespace(
+ messages=SimpleNamespace(stream=lambda **kwargs: _AnthropicStream(recorder, kwargs))
+ )
+ request = BrainRequest(
+ messages=messages,
+ system="You are Probe.",
+ tools=({"name": "read_file", "input_schema": {"type": "object"}},),
+ max_tokens=64,
+ )
+ token = _agent_profile.PROFILE.set(profile)
+ try:
+ async for _ in stream_complete(client, "claude-3-5-haiku-latest", request):
+ pass
+ finally:
+ _agent_profile.PROFILE.reset(token)
+ return recorder.kwargs
+
+
+async def test_an_agent_tool_loop_on_claude_is_prompt_cached(monkeypatch) -> None:
+ monkeypatch.delenv("JARVIS_ANTHROPIC_PROMPT_CACHE", raising=False) # the voice switch
+ profile = _agent_profile.AgentRequestProfile(
+ read_timeout_s=300.0, prompt_cache=True, omit_temperature=True
+ )
+ history = (
+ BrainMessage("user", "Read a.txt"),
+ BrainMessage("assistant", [{"type": "tool_use", "id": "t1", "name": "read_file",
+ "input": {"path": "a.txt"}}]),
+ BrainMessage("tool", "file body", tool_call_id="t1"),
+ )
+ kwargs = await _anthropic_kwargs(profile, history)
+ assert kwargs["system"][0]["cache_control"] == {"type": "ephemeral"}
+ assert kwargs["tools"][-1]["cache_control"] == {"type": "ephemeral"}
+ last = kwargs["messages"][-1]["content"][-1]
+ assert last["type"] == "tool_result" and last["cache_control"] == {"type": "ephemeral"}
+ # Earlier turns are untouched: one rolling breakpoint at the end.
+ assert "cache_control" not in str(kwargs["messages"][:-1])
+ assert "temperature" not in kwargs and kwargs["timeout"].read == 300.0
+
+
+async def test_the_voice_path_to_claude_is_unchanged(monkeypatch) -> None:
+ monkeypatch.delenv("JARVIS_ANTHROPIC_PROMPT_CACHE", raising=False)
+ kwargs = await _anthropic_kwargs(None, (BrainMessage("user", "Hi"),))
+ assert kwargs["system"] == "You are Probe."
+ assert kwargs["messages"] == [{"role": "user", "content": "Hi"}]
+ assert kwargs["temperature"] == 0.7 and "timeout" not in kwargs
+
+
+def test_the_subscription_client_waits_for_long_thinking() -> None:
+ gateway.reset()
+ try:
+ client = gateway._client("account-a")
+ assert client._pool._timeout_s == gateway._HOSTED_READ_TIMEOUT_S
+ finally:
+ gateway.reset()
diff --git a/tests/unit/agent_runtimes/test_hermes_profiles.py b/tests/unit/agent_runtimes/test_hermes_profiles.py
new file mode 100644
index 0000000000..ae27fd53da
--- /dev/null
+++ b/tests/unit/agent_runtimes/test_hermes_profiles.py
@@ -0,0 +1,194 @@
+"""Hermes agents as profiles of one Jarvis-owned data root.
+
+A data root per agent made every agent's first turn build a ~700 MB Python
+environment for about two minutes, and Hermes' Windows home maintenance put
+every agent folder on the user's PATH. These tests pin the layout that
+prevents both, the one-time cleanup of the old PATH entries, and the move of
+an agent's conversation out of its old folder.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+from pathlib import Path
+
+import pytest
+
+from jarvis.agent_runtimes import base, hermes, path_cleanup
+from jarvis.agent_runtimes.base import RuntimeStatus, RuntimeTurn
+from jarvis.agent_runtimes.model_map import ModelRoute
+
+_HERMES_PROFILE_NAME = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+
+
+def roots(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ monkeypatch.setattr(base, "runtimes_root", lambda: tmp_path / "agent_runtimes")
+ monkeypatch.setattr(base, "legacy_runtimes_root", lambda: tmp_path / "legacy_runtimes")
+ return tmp_path
+
+
+def _hermes_data_root(hermes_home: Path, native_home: Path) -> Path:
+ """Hermes' own rule (``hermes_constants.get_default_hermes_root``)."""
+ try:
+ hermes_home.resolve().relative_to(native_home.resolve())
+ return native_home
+ except ValueError:
+ return hermes_home.parent.parent if hermes_home.parent.name == "profiles" else hermes_home
+
+
+def test_profile_names_are_valid_and_never_collide():
+ keys = ["hermit", "Hermit", "hermit~runs", "hermit-runs", "agent-148d4d71", "a" * 80, "é"]
+ names = [hermes.profile_name(key) for key in keys]
+ assert all(_HERMES_PROFILE_NAME.match(name) for name in names), names
+ assert len(set(names)) == len(names)
+ assert hermes.profile_name("agent-148d4d71") == "agent-148d4d71" # readable when it can be
+
+
+def test_every_agent_shares_one_jarvis_data_root(roots):
+ chat = hermes.profile_home("hermit")
+ runs = hermes.profile_home("hermit~runs")
+ other = hermes.profile_home("scout")
+ native = roots / "home" / ".hermes"
+ data_roots = {_hermes_data_root(home, native) for home in (chat, runs, other)}
+ # One dependency environment for all of them, and never the person's own root.
+ assert data_roots == {hermes.hermes_root()}
+ assert native not in data_roots
+
+
+def test_the_shared_root_never_reaches_the_users_path(roots):
+ root = hermes.prepare_root()
+ config = json.loads((root / "config.yaml").read_text(encoding="utf-8"))
+ assert config["cli"]["expose_on_path"] is False # Hermes honours it on POSIX
+ # Windows: Hermes stages launchers in <root>/bin and registers that folder;
+ # a file there makes the step fail before it touches the registry.
+ assert (root / "bin").is_file()
+
+
+def test_a_bin_folder_hermes_already_made_is_replaced_by_the_blocker(roots):
+ root = hermes.hermes_root()
+ (root / "bin").mkdir(parents=True)
+ (root / "bin" / "hermes.cmd").write_text("@echo off\n", encoding="utf-8")
+ hermes.prepare_root()
+ assert (root / "bin").is_file()
+
+
+def test_an_agents_old_conversation_moves_into_its_profile(roots):
+ legacy = roots / "legacy_runtimes" / "hermes" / "hermit"
+ (legacy / "sessions").mkdir(parents=True)
+ (legacy / "state.db").write_bytes(b"sqlite")
+ (legacy / "sessions" / "s1.json").write_text("{}", encoding="utf-8")
+ (legacy / "installs" / "abc").mkdir(parents=True) # the old 700 MB environment
+ home = hermes.profile_home("hermit")
+ assert (home / "state.db").read_bytes() == b"sqlite"
+ assert (home / "sessions" / "s1.json").is_file()
+ assert not legacy.exists()
+
+
+def test_an_existing_profile_conversation_is_never_overwritten(roots):
+ home = hermes.profile_home("hermit")
+ (home / "state.db").write_bytes(b"current")
+ legacy = roots / "legacy_runtimes" / "hermes" / "hermit"
+ legacy.mkdir(parents=True)
+ (legacy / "state.db").write_bytes(b"old")
+ hermes.profile_home("hermit")
+ assert (home / "state.db").read_bytes() == b"current"
+
+
+def test_a_turn_runs_with_its_profile_as_hermes_home(roots):
+ turn = RuntimeTurn(
+ agent_id="hermit",
+ agent_name="Hermit",
+ session_id="society:hermit",
+ workspace=roots,
+ route=ModelRoute("ollama", "qwen3", "http://127.0.0.1:11434/v1", "chat_completions", None),
+ resume=None,
+ auto_approve=True,
+ )
+ launch = asyncio.run(hermes.HermesRuntime()._launch("hermes", turn, lambda: None))
+ home = Path(launch.env["HERMES_HOME"])
+ assert home.parent == hermes.hermes_root() / "profiles"
+ assert (home / "config.yaml").is_file() and (home / "SOUL.md").is_file()
+
+
+def test_the_setup_job_prepares_the_shared_root_once_per_build(roots, monkeypatch):
+ monkeypatch.setattr(hermes, "_binary", lambda: "hermes")
+ runtime = hermes.HermesRuntime()
+ argv, env = runtime.prepare_command() or ([], {})
+ assert argv == ["hermes", "profile", "list"] # passes Hermes' launch preparation
+ assert Path(env["HERMES_HOME"]).parent == hermes.hermes_root() / "profiles"
+ status = RuntimeStatus("hermes", "Hermes", installed=True, ready=True, build="v1 abc")
+ assert runtime.needs_prepare(status)
+ runtime.mark_prepared(status)
+ assert not runtime.needs_prepare(status)
+ newer = RuntimeStatus("hermes", "Hermes", installed=True, ready=True, build="v1 def")
+ assert runtime.needs_prepare(newer)
+
+
+def test_a_stale_agent_launcher_on_path_never_answers(tmp_path, monkeypatch):
+ stale = tmp_path / "Jarvis" / "agent_runtimes" / "hermes" / "agent-1" / "bin"
+ real = tmp_path / "hermes" / "bin"
+ for folder in (stale, real):
+ folder.mkdir(parents=True)
+ launcher = folder / ("hermes.cmd" if os.name == "nt" else "hermes")
+ launcher.write_text("", encoding="utf-8")
+ launcher.chmod(0o755)
+ monkeypatch.setenv("PATH", os.pathsep.join([str(stale), str(real)]))
+ import jarvis.core.path_augment as path_augment
+
+ monkeypatch.setattr(path_augment, "ensure_cli_paths", lambda: [])
+ found = hermes._binary()
+ assert found is not None and Path(found).parent == real
+
+
+# -------------------------------------------------------------- PATH cleanup
+
+
+class _Store:
+ def __init__(self, value: str, kind: int = 2) -> None:
+ self.value, self.kind, self.writes = value, kind, 0
+
+ def read(self) -> tuple[str, int] | None:
+ return self.value, self.kind
+
+ def write(self, value: str, kind: int) -> None:
+ self.value, self.kind, self.writes = value, kind, self.writes + 1
+
+
+def test_the_cleanup_removes_only_jarvis_hermes_folders():
+ keep = [
+ r"C:\Users\Ada\AppData\Local\hermes\bin",
+ r"%LOCALAPPDATA%\Programs\nodejs",
+ r"C:\Users\Ada\.local\bin",
+ ]
+ drop = [
+ r"C:\Users\Ada\AppData\Local\Jarvis\agent_runtimes\hermes\agent-148d4d71\bin",
+ r"C:\Users\ADA~1\AppData\Local\Temp\jarvis-hermes-e2e-x\agent_runtimes\hermes\e2e\bin",
+ r"C:\Users\Ada\AppData\Local\Jarvis\agent_runtimes-dev\hermes-home\bin",
+ ]
+ store = _Store(";".join([drop[0], keep[0], drop[1], keep[1], drop[2], keep[2]]))
+ environ = {"PATH": os.pathsep.join([*drop, *keep]) if os.name == "nt" else "/usr/bin"}
+ removed = path_cleanup.clean_user_path(store=store, environ=environ)
+ assert removed == drop
+ assert store.value == ";".join(keep) and store.kind == 2 # REG_EXPAND_SZ kept
+ if os.name == "nt":
+ assert environ["PATH"] == os.pathsep.join(keep)
+
+
+def test_a_clean_path_is_never_rewritten():
+ store = _Store(r"C:\Windows;C:\Users\Ada\AppData\Local\hermes\bin")
+ assert path_cleanup.clean_user_path(store=store, environ={}) == []
+ assert store.writes == 0
+
+
+def test_the_dev_instance_never_takes_the_default_apps_old_folders(roots, monkeypatch):
+ monkeypatch.setenv("JARVIS_INSTANCE", "dev")
+ legacy = roots / "legacy_runtimes" / "hermes" / "hermit"
+ legacy.mkdir(parents=True)
+ (legacy / "state.db").write_bytes(b"default app's")
+ home = hermes.profile_home("hermit")
+ assert not (home / "state.db").exists()
+ assert (legacy / "state.db").exists()
\ No newline at end of file
diff --git a/tests/unit/agent_runtimes/test_model_limits.py b/tests/unit/agent_runtimes/test_model_limits.py
new file mode 100644
index 0000000000..aaa6509560
--- /dev/null
+++ b/tests/unit/agent_runtimes/test_model_limits.py
@@ -0,0 +1,236 @@
+"""Runtime configs and both gateway response modes share the model budget."""
+
+import pytest
+
+from jarvis.agent_runtimes import gateway
+from jarvis.agent_runtimes.base import RuntimeTurn
+from jarvis.agent_runtimes.hermes import HermesRuntime
+from jarvis.agent_runtimes.model_limits import ModelLimits, resolve_limits
+from jarvis.agent_runtimes.model_map import ModelRoute, prepare_route
+from jarvis.agent_runtimes.openclaw import OpenClawRuntime
+from jarvis.brain.model_catalog import CatalogResult, ModelCatalog, ModelInfo, parse_models_response
+from jarvis.core.config import BrainProviderConfig, JarvisConfig, OllamaModelOptions
+from jarvis.core.protocols import BrainDelta, BrainRequest
+
+
+def config(context=None, output=None):
+ cfg = JarvisConfig()
+ cfg.brain.providers["ollama"] = BrainProviderConfig(
+ models={"small:latest": OllamaModelOptions(num_ctx=context, num_predict=output)}
+ )
+ return cfg
+
+
+ ("allocated", "native", "expected"),
+ [
+ (8192, 131072, 8192),
+ (65536, 16384, 16384),
+ (65536, None, 65536),
+ (None, 8192, 8192),
+ # No num_ctx chosen: a bounded default, never the whole native window
+ # (Ollama allocates it up front; 256k froze a 32 GB desktop).
+ (None, 262144, 65536),
+ (None, 131072, 65536),
+ (None, None, 32768),
+ # A larger window chosen on the model card is honoured.
+ (131072, 262144, 131072),
+ ],
+)
+def test_local_allocation_is_bounded_by_native_context(allocated, native, expected):
+ metadata = ModelInfo("small:latest", "Small", context_length=native)
+ limits = resolve_limits(config(allocated), "ollama", "small", metadata)
+ assert limits.context_window == expected
+ assert limits.max_output_tokens is None
+
+
+def test_per_model_output_and_large_catalog_limits():
+ limits = resolve_limits(config(8192, 1024), "ollama", "small")
+ assert limits == ModelLimits(8192, 1024)
+ large = ModelInfo("large", "Large", context_length=1_000_000, max_output_tokens=65536)
+ assert resolve_limits(config(), "openrouter", "large", large) == ModelLimits(1_000_000, 65536)
+ small = ModelInfo("small", "Small", context_length=8192, max_output_tokens=1024)
+ assert resolve_limits(config(8192, 64000), "ollama", "small", small).max_output_tokens == 1024
+
+
[email protected]("context,output", [(8192, 1024), (1_000_000, 65536)])
+def test_both_runtime_configs_use_the_resolved_model(context, output, tmp_path):
+ route = ModelRoute(
+ "ollama", "small", "http://localhost/gateway", "chat_completions", None, context, output
+ )
+ turn = RuntimeTurn("eval", "Eval", "society:eval", tmp_path, route, None, False)
+ assert HermesRuntime().config_for(turn)["model"]["context_length"] == context
+ runtime_config = OpenClawRuntime().config_for(turn, port=1, token="test") # noqa: S106
+ model = runtime_config["models"]["providers"]["jarvis"]["models"][0]
+ assert (model["contextWindow"], model["maxTokens"]) == (context, output)
+
+
[email protected]("streaming", [True, False])
+async def test_gateway_clamps_output_before_provider_call(monkeypatch, streaming):
+ gateway.reset()
+ token = gateway.grant_token("eval", "ollama")
+ gateway.register_model(token, "small", ModelLimits(8192, 1024))
+ grant = gateway.verify(token)
+ requests = []
+
+ async def deltas(_grant, _model, request):
+ requests.append(request)
+ yield BrainDelta(content="answer", finish_reason="stop")
+
+ monkeypatch.setattr(gateway, "_deltas", deltas)
+ request = BrainRequest(messages=(), max_tokens=64000)
+ if streaming:
+ result = await gateway.open_chat_stream(grant, "small", request)
+ assert b"answer" in b"".join([part async for part in result])
+ else:
+ result = await gateway.complete_chat(grant, "small", request)
+ assert result["choices"][0]["message"]["content"] == "answer"
+ assert requests[0].max_tokens == 1024
+ assert request.max_tokens == 64000 # the caller's frozen request is unchanged
+ gateway.reset()
+
+
+async def test_custom_local_model_is_discoverable_with_its_limits():
+ gateway.reset()
+ token = gateway.grant_token("eval", "ollama")
+ gateway.register_model(token, "custom-small", ModelLimits(8192, 1024))
+ rows = await gateway.list_models(gateway.verify(token))
+ row = next(row for row in rows if row["id"] == "custom-small")
+ assert row["context_length"] == 8192 and row["max_output_tokens"] == 1024
+ gateway.reset()
+
+
+def test_catalog_metadata_survives_restart(tmp_path):
+ path = tmp_path / "catalog.json"
+ catalog = ModelCatalog(cache_path=path)
+ catalog._cache["ollama"] = (
+ 1.0,
+ [ModelInfo("small:latest", "Small", context_length=8192, max_output_tokens=1024)],
+ )
+ catalog._save_cache()
+ restored = ModelCatalog(cache_path=path).cached_model("ollama", "small")
+ assert restored.context_length == 8192 and restored.max_output_tokens == 1024
+
+
+ "provider,payload,expected",
+ [
+ (
+ "gemini",
+ {
+ "models": [
+ {"name": "models/small", "inputTokenLimit": 16384, "outputTokenLimit": 2048}
+ ]
+ },
+ (16384, 2048),
+ ),
+ (
+ "openrouter",
+ {
+ "data": [
+ {
+ "id": "large",
+ "context_length": 1000000,
+ "top_provider": {"max_completion_tokens": 65536},
+ }
+ ]
+ },
+ (1000000, 65536),
+ ),
+ (
+ "local-openai",
+ {"data": [{"id": "small", "context_window": 8192, "max_output_tokens": 1024}]},
+ (8192, 1024),
+ ),
+ (
+ "openai",
+ {"data": [{"id": "unknown", "context_length": True, "max_output_tokens": -1}]},
+ (None, None),
+ ),
+ ],
+)
+def test_declared_limits_are_preserved_without_model_name_guesses(provider, payload, expected):
+ row = parse_models_response(provider, payload)[0]
+ assert (row.context_length, row.max_output_tokens) == expected
+
+
+async def test_prepare_refreshes_limits_before_runtime_config(monkeypatch):
+ import jarvis.agent_runtimes.model_map as mapping
+
+ gateway.reset()
+ token = gateway.grant_token("eval", "ollama")
+ route = ModelRoute("ollama", "small", "http://localhost/gateway", "chat_completions", token)
+ monkeypatch.setattr(mapping, "route_for", lambda *args, **kwargs: route)
+
+ class Catalog:
+ async def list_models(self, provider):
+ assert provider == "ollama"
+ return CatalogResult(
+ provider, (ModelInfo("small:latest", "Small", context_length=8192),), "live", 1.0
+ )
+
+ monkeypatch.setattr(gateway, "_CATALOG", Catalog())
+ actual = await prepare_route(config(65536), "ollama", "small", agent_id="eval")
+ assert actual.context_window == 8192
+ assert gateway.model_limits(gateway.verify(token), "small").context_window == 8192
+ gateway.reset()
+
+
+async def test_subscription_catalog_limits_are_account_specific(monkeypatch):
+ gateway.reset()
+
+ class Subscription:
+ async def list_models(self):
+ return [{"id": "large", "context_length": 400000, "max_output_tokens": 64000}]
+
+ accounts = []
+
+ def client(account_id):
+ accounts.append(account_id)
+ return Subscription()
+
+ monkeypatch.setattr(gateway, "_client", client)
+ limits = await gateway.refresh_model_limits(
+ gateway.Grant("eval", "openai-codex", "seat-2"), "large", config()
+ )
+ assert accounts == ["seat-2"]
+ assert limits == ModelLimits(400000, 64000)
+ rows = await gateway.list_models(gateway.Grant("eval", "openai-codex", "seat-2"))
+ assert rows[0]["context_length"] == 400000
+ assert rows[0]["max_output_tokens"] == 64000
+
+
+async def test_unavailable_metadata_preserves_the_prepared_limits(monkeypatch):
+ gateway.reset()
+ token = gateway.grant_token("eval", "openai-codex")
+ gateway.register_model(token, "selected", ModelLimits(16000, 2000))
+
+ class Subscription:
+ async def list_models(self):
+ raise TimeoutError
+
+ monkeypatch.setattr(gateway, "_client", lambda _: Subscription())
+ limits = await gateway.refresh_model_limits(gateway.verify(token), "selected", config())
+ assert limits == ModelLimits(16000, 2000)
+
+
+def test_hermes_minimum_context_error_is_actionable_without_raw_details():
+ from jarvis.agent_runtimes.acp import _error_text
+
+ error = {
+ "message": "Internal error",
+ "data": {
+ "details": (
+ "Model private-model has a context window of 32,768 tokens, "
+ "which is below the minimum 64,000 required by Hermes Agent. "
+ "private-provider-body"
+ )
+ },
+ }
+ message = _error_text(error)
+ assert "32,768" in message and "64,000" in message and "Settings" in message
+ assert "private" not in message
+ assert (
+ _error_text({"message": "Internal error", "data": {"details": "private"}})
+ == "Internal error"
+ )
diff --git a/tests/unit/agent_runtimes/test_native_grants.py b/tests/unit/agent_runtimes/test_native_grants.py
new file mode 100644
index 0000000000..9ae05ccf63
--- /dev/null
+++ b/tests/unit/agent_runtimes/test_native_grants.py
@@ -0,0 +1,26 @@
+"""Native runtime tools must not circumvent the agent's capability selection."""
+
+from types import SimpleNamespace
+
+import pytest
+
+from jarvis.agent_chat.runner_acp import _denied_native
+
+
+ ("mode", "grants", "denies", "plan", "expected"),
+ [
+ ("all", [], [], False, set()),
+ ("allowlist", [], [], False, {"shell", "web"}),
+ ("allowlist", ["core:browser"], [], False, {"shell"}),
+ ("allowlist", ["core:shell"], [], False, {"web"}),
+ ("allowlist", ["core:shell", "core:browser"], [], False, set()),
+ ("allowlist", ["core:browser"], ["core:browser"], False, {"shell", "web"}),
+ ("all", [], ["core:browser"], True, {"shell", "web"}),
+ ("all", [], ["core:shell"], False, {"shell"}),
+ ("all", [], [], True, {"shell"}),
+ ],
+)
+def test_native_tools_obey_allowlist_denies_and_plan(mode, grants, denies, plan, expected):
+ agent = SimpleNamespace(grant_mode=mode, grants=grants, denies=denies)
+ assert _denied_native(agent, plan) == frozenset(expected)
diff --git a/tests/unit/agent_runtimes/test_openclaw_gateway.py b/tests/unit/agent_runtimes/test_openclaw_gateway.py
new file mode 100644
index 0000000000..778bf7b2fc
--- /dev/null
+++ b/tests/unit/agent_runtimes/test_openclaw_gateway.py
@@ -0,0 +1,231 @@
+"""OpenClaw Gateway supervision against a stand-in CLI (no real OpenClaw)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import psutil
+import pytest
+
+from jarvis.agent_runtimes import base, openclaw
+from jarvis.agent_runtimes.base import HomeFileLock, RuntimeTurn, RuntimeUnavailable
+from jarvis.agent_runtimes.model_map import ModelRoute
+from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS
+
+_FAKE = Path(__file__).resolve().parents[2] / "fakes" / "fake_openclaw.py"
+_LAUNCHER = [sys.executable, str(_FAKE)]
+
+
+def home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ monkeypatch.setattr(base, "runtimes_root", lambda: tmp_path / "rt")
+ folder = tmp_path / "rt" / "openclaw" / "hermit"
+ folder.mkdir(parents=True)
+ return folder
+
+
+def _turn(tmp_path: Path) -> RuntimeTurn:
+ return RuntimeTurn(
+ agent_id="hermit",
+ agent_name="Hermit",
+ session_id="society:hermit",
+ workspace=tmp_path,
+ route=ModelRoute("ollama", "qwen3", "http://127.0.0.1:11434/v1", "chat_completions", None),
+ resume=None,
+ auto_approve=True,
+ )
+
+
+async def _start(runtime: openclaw.OpenClawRuntime, home: Path, port: int, env=None):
+ return await runtime._start_gateway(
+ _turn(home.parent), "hermit", home, port, "tok", "h", _LAUNCHER, env or {}
+ )
+
+
+def _env(**extra: str) -> dict[str, str]:
+ import os
+
+ env = dict(os.environ)
+ env.update(extra)
+ return env
+
+
+def test_a_started_gateway_is_recorded_and_stopping_clears_it(home):
+ async def run() -> None:
+ runtime = openclaw.OpenClawRuntime()
+ gateway = await _start(runtime, home, openclaw._free_port(), _env())
+ record = json.loads((home / "gateway.pid").read_text(encoding="utf-8"))
+ assert record["pid"] == gateway.proc.pid and record["port"] == gateway.port
+ await runtime._stop_gateway(gateway)
+ assert not (home / "gateway.pid").exists()
+ # The folder's Gateway lock is free again.
+ again = HomeFileLock(home / "gateway.lock")
+ assert again.try_acquire()
+ again.release()
+
+ asyncio.run(run())
+
+
+def test_a_gateway_left_by_a_crashed_app_is_stopped_before_a_new_one(home):
+ port = openclaw._free_port()
+ orphan = subprocess.Popen( # noqa: S603 — the stand-in, started by this test
+ [*_LAUNCHER, "gateway", "run", "--port", str(port)],
+ cwd=home,
+ creationflags=NO_WINDOW_CREATIONFLAGS,
+ )
+ try:
+ created = psutil.Process(orphan.pid).create_time()
+ (home / "gateway.pid").write_text(
+ json.dumps({"pid": orphan.pid, "port": port, "created": created}), encoding="utf-8"
+ )
+ assert openclaw._reap_stale_gateway(home)
+ orphan.wait(timeout=10)
+ assert not (home / "gateway.pid").exists()
+ finally:
+ if orphan.poll() is None:
+ orphan.kill()
+
+
+def test_a_recycled_pid_is_never_killed(home):
+ bystander = subprocess.Popen( # noqa: S603 — started by this test
+ [sys.executable, "-c", "import time; time.sleep(60)"],
+ creationflags=NO_WINDOW_CREATIONFLAGS,
+ )
+ try:
+ (home / "gateway.pid").write_text(
+ json.dumps({"pid": bystander.pid, "port": 1, "created": 12345.0}), encoding="utf-8"
+ )
+ assert not openclaw._reap_stale_gateway(home)
+ assert bystander.poll() is None
+ finally:
+ bystander.kill()
+
+
+def test_a_second_process_never_runs_the_same_agents_gateway(home):
+ holder = HomeFileLock(home / "gateway.lock")
+ assert holder.try_acquire()
+ try:
+ with pytest.raises(RuntimeUnavailable, match="Another Jarvis process"):
+ asyncio.run(_start(openclaw.OpenClawRuntime(), home, openclaw._free_port(), _env()))
+ finally:
+ holder.release()
+
+
+def test_a_port_taken_before_the_gateway_binds_is_retried_on_a_fresh_one(home, monkeypatch):
+ blocker = socket.socket()
+ blocker.bind(("127.0.0.1", 0))
+ blocker.listen()
+ taken = blocker.getsockname()[1]
+
+ async def run() -> None:
+ runtime = openclaw.OpenClawRuntime()
+ gateway = await _start(runtime, home, taken, _env())
+ try:
+ assert gateway.port != taken
+ assert await openclaw._healthy(gateway.port)
+ written = json.loads((home / "openclaw.json").read_text(encoding="utf-8"))
+ assert written["gateway"]["port"] == gateway.port
+ finally:
+ await runtime._stop_gateway(gateway)
+
+ try:
+ asyncio.run(run())
+ finally:
+ blocker.close()
+
+
+def test_a_foreign_listener_is_not_a_ready_gateway():
+ """A bare TCP accept on the port proves nothing; /healthz must answer 200."""
+ server = socket.socket()
+ server.bind(("127.0.0.1", 0))
+ server.listen()
+ port = server.getsockname()[1]
+
+ async def probe() -> bool:
+ return await openclaw._healthy(port)
+
+ try:
+ assert asyncio.run(probe()) is False
+ finally:
+ server.close()
+
+
+def test_a_rejected_config_gets_one_doctor_pass(home):
+ async def run() -> None:
+ runtime = openclaw.OpenClawRuntime()
+ gateway = await _start(
+ runtime, home, openclaw._free_port(), _env(FAKE_OPENCLAW_MODE="config-once")
+ )
+ try:
+ assert (home / "doctor.done").exists()
+ finally:
+ await runtime._stop_gateway(gateway)
+
+ asyncio.run(run())
+
+
+def test_a_hanging_doctor_is_stopped(home, monkeypatch):
+ monkeypatch.setattr(openclaw, "_DOCTOR_TIMEOUT_S", 1.0)
+ asyncio.run(
+ openclaw._run_doctor(_LAUNCHER, _env(FAKE_OPENCLAW_MODE="doctor-hang"), home)
+ )
+ pid = int((home / "doctor.pid").read_text(encoding="utf-8"))
+ deadline = time.monotonic() + 5
+ while psutil.pid_exists(pid) and time.monotonic() < deadline:
+ time.sleep(0.1)
+ try:
+ survivor = psutil.Process(pid).status() != psutil.STATUS_ZOMBIE
+ except psutil.NoSuchProcess: # gone between checks: reaped
+ survivor = False
+ assert not survivor
+
+
+def test_jarvis_prefers_its_own_copy_of_openclaw(tmp_path, monkeypatch):
+ monkeypatch.setattr(base, "runtimes_root", lambda: tmp_path)
+ prefix = openclaw.cli_prefix()
+ if openclaw.is_windows():
+ (prefix / "node").mkdir(parents=True)
+ (prefix / "node" / "node.exe").write_bytes(b"")
+ entry = prefix / "pkg" / "node_modules" / "openclaw"
+ entry.mkdir(parents=True)
+ (entry / "openclaw.mjs").write_text("", encoding="utf-8")
+ else:
+ (prefix / "bin").mkdir(parents=True)
+ wrapper = prefix / "bin" / "openclaw"
+ wrapper.write_text("#!/bin/sh\n", encoding="utf-8")
+ wrapper.chmod(0o755)
+ launcher = openclaw._launcher()
+ assert launcher is not None and Path(launcher[0]).is_relative_to(prefix)
+
+
+def test_an_install_outside_path_is_found(tmp_path, monkeypatch):
+ """OpenClaw's installers use folders a GUI-launched app does not have on PATH."""
+ import jarvis.core.path_augment as path_augment
+
+ monkeypatch.setattr(base, "runtimes_root", lambda: tmp_path / "rt")
+ monkeypatch.setattr(path_augment, "ensure_cli_paths", lambda: [])
+ monkeypatch.setenv("PATH", str(tmp_path / "empty"))
+ bin_dir = tmp_path / "home" / ".openclaw" / "bin"
+ bin_dir.mkdir(parents=True)
+ name = "openclaw.exe" if openclaw.is_windows() else "openclaw"
+ (bin_dir / name).write_bytes(b"")
+ (bin_dir / name).chmod(0o755)
+ monkeypatch.setattr(openclaw, "_installer_bin_dirs", lambda: (bin_dir,))
+ launcher = openclaw._launcher()
+ assert launcher is not None and Path(launcher[0]).parent == bin_dir
+
+
+def test_moving_the_agent_folders_keeps_the_installed_openclaw(monkeypatch, tmp_path):
+ """The e2e spikes keep agent state in a temp dir; they must still find the
+ private OpenClaw the app installed (CI 2026-10-07: "not installed")."""
+ from jarvis.agent_runtimes import base, openclaw
+
+ installed = openclaw.cli_prefix()
+ monkeypatch.setattr(base, "runtimes_root", lambda: tmp_path / "agent_runtimes")
+ assert openclaw.cli_prefix() == installed
diff --git a/tests/unit/agent_runtimes/test_provider_errors.py b/tests/unit/agent_runtimes/test_provider_errors.py
index 09b1f7c5a9..60d4d863c8 100644
--- a/tests/unit/agent_runtimes/test_provider_errors.py
+++ b/tests/unit/agent_runtimes/test_provider_errors.py
@@ -2,14 +2,14 @@
Measured live 2026-10-07: an empty OpenAI balance answers 429, OpenRouter 402,
a stopped local server times out, and Anthropic refuses a Claude subscription
-outside Claude Code with a bare 429 while the plan has room (Extra Usage off).
+used by Hermes or OpenClaw with a 400 ("Third-party apps now draw from your
+extra usage, not your plan limits") or a bare 429 while the plan has room.
All of them used to read as "rate limited, try again in 30 s".
"""
from __future__ import annotations
from collections.abc import AsyncIterator
-from datetime import UTC, datetime
from typing import Any
import pytest
@@ -69,8 +69,25 @@ def test_an_ordinary_rate_limit_stays_unclassified() -> None:
assert classify("openai", ProviderStatusError(500)) is None
+class ConnectTimeout(Exception):
+ """httpx's connect timeout: nothing accepted the connection."""
+
+
+class ReadTimeout(Exception):
+ """httpx's read timeout: the server was reached and went quiet."""
+
+
+def _timeout(cause: Exception) -> APITimeoutError:
+ """An SDK timeout wrapping the transport error, as openai/anthropic raise it."""
+ try:
+ raise APITimeoutError("Request timed out.") from cause
+ except APITimeoutError as exc:
+ return exc
+
+
def test_a_stopped_local_server_is_unreachable() -> None:
- refusal = classify("local-openai", APITimeoutError("Request timed out."))
+ # Windows refuses a closed localhost port only after the connect timeout.
+ refusal = classify("local-openai", _timeout(ConnectTimeout("connect timed out")))
assert refusal is not None
assert (refusal.status, refusal.code) == (503, "provider_unreachable")
@@ -78,14 +95,105 @@ def test_a_stopped_local_server_is_unreachable() -> None:
def test_a_wrapped_transport_error_is_found_in_the_chain() -> None:
try:
try:
- raise APITimeoutError("timed out")
- except APITimeoutError as inner:
+ raise ConnectTimeout("timed out")
+ except ConnectTimeout as inner:
raise RuntimeError("stream failed") from inner
except RuntimeError as outer:
refusal = classify("ollama", outer)
assert refusal is not None and refusal.code == "provider_unreachable"
+def test_a_model_that_took_too_long_is_a_timeout_not_unreachable() -> None:
+ refusal = classify("openai", _timeout(ReadTimeout("read timed out")), "gpt-5.5")
+ assert refusal is not None
+ assert (refusal.status, refusal.code) == (504, "timeout")
+ assert "took too long" in refusal.message and "start it" not in refusal.message
+
+
+_OVERFLOWS = [
+ # OpenAI / OpenRouter
+ ProviderStatusError(
+ 400,
+ {"error": {"code": "context_length_exceeded", "type": "invalid_request_error"}},
+ "This model's maximum context length is 400000 tokens.",
+ ),
+ # Anthropic
+ ProviderStatusError(
+ 400,
+ {"type": "error", "error": {"type": "invalid_request_error"}},
+ "prompt is too long: 210000 tokens > 200000 maximum",
+ ),
+ # vLLM / local servers
+ ProviderStatusError(400, None, "max_tokens is too large: this exceeds max_model_len"),
+ # A stream error event without a status
+ RuntimeError("Responses API stream failed: Your input exceeds the context window"),
+]
+
+
[email protected]("exc", _OVERFLOWS)
+def test_a_context_overflow_tells_the_runtime_to_compress(exc: Exception) -> None:
+ refusal = provider_errors.gateway_refusal("openai", exc, "gpt-5.5")
+ assert (refusal.status, refusal.code) == (400, "context_length_exceeded")
+ # Hermes and OpenClaw both match these words to compress and resend.
+ assert "context length exceeded" in refusal.message.lower()
+ assert not provider_errors.is_terminal(refusal.code)
+
+
+def test_a_gemini_overflow_is_found_on_the_genai_error_shape() -> None:
+ class ClientError(Exception): # google-genai: ``code`` int, ``status`` name
+ def __init__(self) -> None:
+ super().__init__("400 INVALID_ARGUMENT. The input token count (1200000) exceeds "
+ "the maximum number of tokens allowed (1048576).")
+ self.code = 400
+ self.status = "INVALID_ARGUMENT"
+ self.details = {"error": {"code": 400, "status": "INVALID_ARGUMENT"}}
+
+ refusal = provider_errors.gateway_refusal("gemini", ClientError())
+ assert refusal.code == "context_length_exceeded"
+
+
+ ("exc", "status", "code"),
+ [
+ (ProviderStatusError(404, {"error": {"code": "model_not_found"}}, "no such model"),
+ 404, "model_not_found"),
+ (ProviderStatusError(400, None, "registry.ollama.ai/library/gemma:2b does not support "
+ "tools"), 400, "tools_unsupported"),
+ (ProviderStatusError(400, {"error": {"code": "invalid_function_parameters"}},
+ "Invalid schema for function 'x'"), 400, "invalid_tool_schema"),
+ (ProviderStatusError(400, None, "messages.3: unexpected role"), 400, "invalid_request"),
+ (ProviderStatusError(529, None, "Overloaded"), 503, "provider_overloaded"),
+ (ProviderStatusError(500, None, "boom"), 502, "provider_error"),
+ (ProviderStatusError(401, None, "invalid x-api-key"), 401, "provider_auth"),
+ ],
+)
+def test_every_provider_failure_gets_an_actionable_status(exc, status, code) -> None:
+ refusal = provider_errors.gateway_refusal("ollama", exc, "gemma:2b")
+ assert (refusal.status, refusal.code) == (status, code)
+ assert "must never" not in refusal.message
+
+
+def test_only_unrecoverable_failures_end_the_turn() -> None:
+ terminal = {"billing", "extra_usage_off", "provider_auth", "claude_login_expired",
+ "model_not_found", "invalid_tool_schema", "tools_unsupported", "rate_limited"}
+ recoverable = {"context_length_exceeded", "timeout", "provider_overloaded",
+ "provider_error", "invalid_request", "provider_unreachable"}
+ assert all(provider_errors.is_terminal(code) for code in terminal)
+ assert not any(provider_errors.is_terminal(code) for code in recoverable)
+
+
+def test_the_log_line_is_bounded_and_masks_credentials() -> None:
+ exc = ProviderStatusError(
+ 401, {"error": {"code": "invalid_api_key"}},
+ "Incorrect API key provided: sk-proj-abcdefghijklmnop. Bearer abcdefghijklmnopqrst "
+ + "x" * 900,
+ )
+ line = provider_errors.describe(exc)
+ assert "sk-proj-abcdefghijklmnop" not in line and "abcdefghijklmnopqrst" not in line
+ assert "status=401" in line and "invalid_api_key" in line
+ assert len(line) < 520
+
+
def test_extra_usage_off_explains_a_claude_login_refusal() -> None:
usage = {**_USAGE_ROOM, "extra_usage": {"is_enabled": False, "user_disabled": True}}
refusal = login_refusal(usage, "claude-sonnet-5-5")
@@ -101,17 +209,39 @@ def test_a_spent_extra_usage_limit_is_named() -> None:
assert refusal is not None and refusal.code == "extra_usage_spent"
-def test_a_used_up_plan_window_waits_until_its_reset() -> None:
- usage = {
- "five_hour": {"utilization": 100.0, "resets_at": "2026-10-07T12:00:00+00:00"},
- "extra_usage": {"is_enabled": False},
+def test_anthropics_third_party_wording_is_extra_usage() -> None:
+ body = {
+ "type": "error",
+ "error": {
+ "type": "invalid_request_error",
+ "message": "Third-party apps now draw from your extra usage, not your plan "
+ "limits. Add more at claude.ai/settings/usage and keep going.",
+ },
}
- now = datetime(2026, 10, 7, 11, 0, tzinfo=UTC)
- refusal = login_refusal(usage, "claude-sonnet-5-5", now=now)
+ refusal = classify("claude-api", ProviderStatusError(400, body))
assert refusal is not None
- assert refusal.status == 429
- assert refusal.retry_after == pytest.approx(3600)
- assert "5-hour" in refusal.message
+ assert (refusal.status, refusal.code) == (402, "extra_usage_off")
+
+
+def test_a_plan_window_says_nothing_about_third_party_use() -> None:
+ usage = {"five_hour": {"utilization": 100.0}, "extra_usage": {"is_enabled": True}}
+ assert login_refusal(usage, "claude-haiku-4-5") is None
+
+
+def test_a_blocked_login_is_known_before_any_model_call(monkeypatch) -> None:
+ calls: list[str] = []
+
+ def usage(token: str) -> dict[str, Any]:
+ calls.append(token)
+ return {**_USAGE_ROOM, "extra_usage": {"is_enabled": False}}
+
+ monkeypatch.setattr(provider_errors, "_claude_usage", usage)
+ monkeypatch.setattr(provider_errors, "_REPORTS", {})
+ first = provider_errors.login_blocked(_BEARER, "claude-haiku-4-5")
+ second = provider_errors.login_blocked(_BEARER, "claude-haiku-4-5")
+ assert first is not None and first.code == "extra_usage_off"
+ assert second == first
+ assert calls == [_BEARER] # cached: routing asks once, not every turn
def test_a_report_without_an_explanation_changes_nothing() -> None:
@@ -148,7 +278,7 @@ async def test_a_claude_login_429_is_explained_from_the_usage_report(monkeypatch
seen.append(token)
return {**_USAGE_ROOM, "extra_usage": {"is_enabled": False}}
- monkeypatch.setattr(model_map, "login_token_for", lambda provider, account: _BEARER)
+ monkeypatch.setattr(model_map, "login_route", lambda provider, account: (True, _BEARER))
monkeypatch.setattr(config, "get_jarvis_agent_secret", lambda provider: None)
monkeypatch.setattr(claude_api, "ClaudeAPIBrain", RefusingBrain)
monkeypatch.setattr(provider_errors, "_claude_usage", usage)
@@ -182,3 +312,45 @@ async def test_a_non_streaming_subscription_answer_keeps_its_output(monkeypatch)
finally:
gateway.reset()
assert answer["output"] == [item]
+
+
+def test_a_route_refuses_a_blocked_claude_login_before_the_runtime_starts(monkeypatch) -> None:
+ import jarvis.agent_runtimes.model_map as model_map
+
+ monkeypatch.setattr(model_map, "login_token_for", lambda provider, account: _BEARER)
+ blocked = provider_errors._extra_usage_off
+ monkeypatch.setattr(provider_errors, "login_blocked", lambda token, model: blocked(model))
+ with pytest.raises(model_map.RouteUnavailable, match="Extra Usage"):
+ model_map._check_login_billing("claude-api", "claude-haiku-4-5", "")
+
+
+def test_an_api_key_route_never_reads_the_login(monkeypatch) -> None:
+ import jarvis.agent_runtimes.model_map as model_map
+
+ monkeypatch.setattr(model_map, "login_token_for", lambda provider, account: None)
+ model_map._check_login_billing("claude-api", "claude-haiku-4-5", "api-key")
+
+
+def test_a_system_message_moves_into_the_instructions() -> None:
+ """ChatGPT's backend refuses system input items (OpenClaw sends one)."""
+ args = gateway.request_args(
+ {
+ "model": "gpt-6.1-sol",
+ "instructions": "",
+ "input": [
+ {"type": "message", "role": "system", "content": "You are Lumen."},
+ {"type": "message", "role": "user", "content": [
+ {"type": "input_text", "text": "Hi"},
+ ]},
+ ],
+ }
+ )
+ assert args["instructions"] == "You are Lumen."
+ assert [item["role"] for item in args["input"]] == ["user"]
+
+
+def test_floating_point_dust_never_adds_a_second_to_the_wait() -> None:
+ """Windows CI said "Try again in 31 s" for a 30 s cooldown (30.000000001)."""
+ assert gateway.whole_seconds(30.000000001) == 30
+ assert gateway.whole_seconds(30.4) == 31
+ assert gateway.whole_seconds(-1.0) == 0
diff --git a/tests/unit/agent_runtimes/test_runtime_configs.py b/tests/unit/agent_runtimes/test_runtime_configs.py
index 302dc2e561..e015538c71 100644
--- a/tests/unit/agent_runtimes/test_runtime_configs.py
+++ b/tests/unit/agent_runtimes/test_runtime_configs.py
@@ -103,6 +103,14 @@ def test_hermes_self_learning_extras_stay_off(tmp_path):
assert config["skills"]["creation_nudge_interval"] == 0
+def test_hermes_has_one_attempt_and_no_automatic_recovery_or_fallback(tmp_path):
+ config = HermesRuntime().config_for(_turn(tmp_path, denied_native=frozenset({"shell"})))
+ assert config["agent"]["api_max_retries"] == 1
+ assert config["agent"]["auto_recovery_cycles"] == 0
+ assert config["fallback_model"] is None
+ assert "terminal" in config["agent"]["disabled_toolsets"]
+
+
def test_hermes_discovers_connected_tools_with_explicit_persona_guidance(tmp_path):
"""Large catalogs stay lazy, and the persona explains how to reach them."""
runtime = HermesRuntime()
@@ -118,34 +126,6 @@ def test_hermes_discovers_connected_tools_with_explicit_persona_guidance(tmp_pat
assert "Search before concluding a capability is missing" in persona
-def test_hermes_profiles_share_installation_but_keep_agent_state_separate(tmp_path, monkeypatch):
- from jarvis.agent_runtimes import base
-
- monkeypatch.setattr(base, "runtimes_root", lambda: tmp_path)
- first = base.agent_home("hermes", "first")
- second = base.agent_home("hermes", "second")
- routine = base.agent_home("hermes", base.home_key("first", "society:first:routine:1"))
- assert first.parent == second.parent == routine.parent == tmp_path / "hermes" / "profiles"
- assert len({first, second, routine}) == 3
- (first / "state.db").write_bytes(b"private conversation")
- assert not (second / "state.db").exists()
- assert not (routine / "state.db").exists()
- assert base.agent_home("hermes", "first") == first
- assert base.agent_home("hermes", "profiles") == first.parent / "profiles"
-
-
-def test_existing_runtime_homes_keep_their_native_sessions(tmp_path, monkeypatch):
- from jarvis.agent_runtimes import base
-
- monkeypatch.setattr(base, "runtimes_root", lambda: tmp_path)
- legacy = tmp_path / "hermes" / "existing"
- legacy.mkdir(parents=True)
- (legacy / "state.db").write_bytes(b"existing session")
- assert base.agent_home("hermes", "existing") == legacy
- assert (legacy / "state.db").read_bytes() == b"existing session"
- assert base.agent_home("openclaw", "first") == tmp_path / "openclaw" / "first"
-
-
def test_hermes_always_asks_jarvis_and_never_the_guardian(tmp_path):
"""The stance is answered over ACP, so the file never depends on it."""
runtime = HermesRuntime()
@@ -156,7 +136,22 @@ def test_hermes_always_asks_jarvis_and_never_the_guardian(tmp_path):
def test_hermes_denied_shell_disables_its_terminal(tmp_path):
config = HermesRuntime().config_for(_turn(tmp_path, denied_native=frozenset({"shell"})))
- assert set(config["agent"]["disabled_toolsets"]) == {"terminal", "code_execution"}
+ assert {"terminal", "code_execution"} <= set(config["agent"]["disabled_toolsets"])
+
+
+def test_hermes_never_gets_a_headless_browser_desktop_control_or_own_scheduler(tmp_path):
+ """Jarvis' visible browser and routines only; never an invisible Chromium."""
+ config = HermesRuntime().config_for(_turn(tmp_path))
+ assert {"browser", "computer_use", "cronjob"} <= set(config["agent"]["disabled_toolsets"])
+ assert "terminal" not in config["agent"]["disabled_toolsets"]
+
+
+def test_hermes_config_never_exposes_the_data_root_and_carries_its_schema(tmp_path):
+ from jarvis.agent_runtimes import versions
+
+ config = HermesRuntime().config_for(_turn(tmp_path))
+ assert config["cli"]["expose_on_path"] is False
+ assert config["_config_version"] == versions.pin("hermes").config_version
def test_a_keyless_local_model_writes_no_key_reference(tmp_path):
@@ -203,6 +198,27 @@ def test_openclaw_never_runs_background_turns_or_persona_files(tmp_path):
assert "automations" in config["tools"]["deny"]
assert config["tools"]["toolSearch"] is False
assert config["gateway"]["bind"] == "loopback"
+ assert config["cron"]["enabled"] is False
+ assert config["plugins"]["slots"]["memory"] == "none"
+ assert config["plugins"]["entries"]["memory-core"]["enabled"] is False
+
+
+def test_openclaw_loads_no_browser_desktop_or_device_plugins(tmp_path):
+ config = OpenClawRuntime().config_for(_turn(tmp_path), port=4321, token=_TOKEN)
+ denied = set(config["plugins"]["deny"])
+ assert {"browser", "cua-computer", "device-pair", "file-transfer"} <= denied
+ # The provider adapters stay: Jarvis' gateway speaks their wire formats.
+ assert not denied & {"openai", "anthropic", "ollama"}
+ assert "browser" in config["tools"]["deny"]
+
+
+def test_openclaw_logs_into_the_agents_own_folder(tmp_path, monkeypatch):
+ from jarvis.agent_runtimes import base
+
+ monkeypatch.setattr(base, "runtimes_root", lambda: tmp_path / "rt")
+ config = OpenClawRuntime().config_for(_turn(tmp_path), port=4321, token=_TOKEN)
+ log_file = Path(config["logging"]["file"])
+ assert log_file.is_relative_to(tmp_path / "rt" / "openclaw" / "hermit")
def test_openclaw_exec_mode_follows_grants_not_the_stance(tmp_path):
@@ -309,6 +325,25 @@ def test_the_chatgpt_subscription_speaks_responses(gateway_up, monkeypatch):
assert gateway.verify(route.api_key or "") == gateway.Grant("agent-1", "openai-codex", "acct")
+def test_chat_and_routine_routes_have_stable_separate_failure_scopes(gateway_up):
+ with override_provider_secrets({"openai": _SECRET}):
+ routes = [route_for(_cfg(), "openai", "m", agent_id="a", session_id=sid)
+ for sid in ("society:a", "society:a:routine:r1", "society:a:routine:r2")]
+ assert routes[0].api_key != routes[1].api_key
+ assert routes[1].api_key == routes[2].api_key
+
+
+def test_a_rate_limited_route_refuses_before_starting_a_runtime(gateway_up):
+ gateway = gateway_up
+ grant = gateway.Grant("a", "openai")
+ gateway._report_failure(
+ grant, "m", gateway.GatewayError("limited", status=429, retry_after=60), None,
+ )
+ with override_provider_secrets({"openai": _SECRET}):
+ with pytest.raises(RouteUnavailable, match="HTTP 429"):
+ route_for(_cfg(), "openai", "m", agent_id="a", session_id="society:a")
+
+
def test_a_missing_key_is_reported_in_plain_words(gateway_up):
with override_provider_secrets({"openrouter": None}), pytest.raises(RouteUnavailable) as err:
route_for(_cfg(), "openrouter", "some/model")
@@ -438,3 +473,68 @@ async def test_turn_slots_run_one_turn_at_a_time():
second = await asyncio.wait_for(waiting, timeout=1)
second()
other()
+
+
+# ------------------------------------------------- effort and capabilities
+
+
+ ("effort", "expected"),
+ [("high", "high"), ("none", "none"), ("xhigh", "xhigh"), ("", None), ("bogus", None)],
+)
+def test_hermes_writes_the_agents_effort(tmp_path, effort, expected):
+ config = HermesRuntime().config_for(_turn(tmp_path, effort=effort))
+ assert config["agent"].get("reasoning_effort") == expected
+
+
+ ("effort", "expected"),
+ [("high", "high"), ("none", "off"), ("minimal", "minimal"), ("", None), ("bogus", None)],
+)
+def test_openclaw_writes_the_agents_thinking_default(tmp_path, effort, expected):
+ config = OpenClawRuntime().config_for(_turn(tmp_path, effort=effort), port=1, token=_TOKEN)
+ assert config["agents"]["defaults"].get("thinkingDefault") == expected
+
+
+ ("reasoning", "vision", "inputs", "reasons"),
+ [
+ (True, True, ["text", "image"], True),
+ (False, False, ["text"], None),
+ (None, None, ["text"], None), # unknown: OpenClaw's own defaults stand
+ ],
+)
+def test_openclaw_declares_only_capabilities_the_catalog_names(
+ tmp_path, reasoning, vision, inputs, reasons
+):
+ turn = _turn(tmp_path, reasoning=reasoning, vision=vision)
+ model = OpenClawRuntime().config_for(turn, port=1, token=_TOKEN)["models"]["providers"][
+ "jarvis"
+ ]["models"][0]
+ assert model["input"] == inputs
+ assert model.get("reasoning") is reasons
+
+
+def test_capabilities_come_from_the_catalog_never_the_name(monkeypatch):
+ from jarvis.agent_chat import runner_acp
+ from jarvis.brain import model_catalog
+ from jarvis.brain.model_catalog import ModelInfo
+
+ rows = {
+ ("openrouter", "a/thinks-sees"): ModelInfo(
+ id="a/thinks-sees",
+ label="x",
+ input_modalities=("text", "image"),
+ supported_parameters=("tools", "reasoning"),
+ ),
+ ("ollama", "plain"): ModelInfo(
+ id="plain", label="x", input_modalities=("text",), supported_parameters=("tools",)
+ ),
+ }
+ monkeypatch.setattr(
+ model_catalog.ModelCatalog, "cached_model", lambda self, p, m: rows.get((p, m))
+ )
+ assert runner_acp.model_capabilities("openrouter", "a/thinks-sees") == (True, True)
+ assert runner_acp.model_capabilities("ollama", "plain") == (False, False)
+ # A name that "sounds" capable but has no catalog entry stays unknown.
+ assert runner_acp.model_capabilities("openai", "gpt-vision-reasoner") == (None, None)
\ No newline at end of file
diff --git a/tests/unit/agent_runtimes/test_runtime_gateway.py b/tests/unit/agent_runtimes/test_runtime_gateway.py
index a20848fbe8..f76a61f123 100644
--- a/tests/unit/agent_runtimes/test_runtime_gateway.py
+++ b/tests/unit/agent_runtimes/test_runtime_gateway.py
@@ -9,6 +9,7 @@ from __future__ import annotations
import json
from collections.abc import AsyncIterator
+from types import SimpleNamespace
from typing import Any
import pytest
@@ -136,10 +137,10 @@ def test_a_failure_mid_stream_arrives_as_response_failed(fake, guarded) -> None:
answer = _post(guarded, token, {"model": "gpt-5.6-sol", "input": "Hi", "stream": True})
frames = [json.loads(line[5:]) for line in answer.text.splitlines() if line.startswith("data:")]
assert frames[-1]["type"] == "response.failed"
- message = frames[-1]["response"]["error"]["message"]
- # Fixed wording only: the client's exception text never leaves the gateway.
- assert "login expired" not in message
- assert message == "The ChatGPT subscription needs a new sign-in in Jarvis."
+ # Fixed wording only: no exception text leaves the gateway (CodeQL 769).
+ assert frames[-1]["response"]["error"]["message"] == (
+ "The ChatGPT subscription needs a new sign-in in Jarvis."
+ )
def test_models_are_listed_in_the_openai_shape(fake, guarded) -> None:
@@ -149,7 +150,8 @@ def test_models_are_listed_in_the_openai_shape(fake, guarded) -> None:
)
assert answer.json() == {
"object": "list",
- "data": [{"id": "gpt-5.6-sol", "object": "model", "owned_by": "openai"}],
+ "data": [{"id": "gpt-5.6-sol", "object": "model", "owned_by": "openai",
+ "context_length": 128000}],
}
@@ -171,9 +173,10 @@ def test_a_gateway_token_opens_nothing_but_the_gateway(fake, guarded) -> None:
class _ProviderError(Exception):
- def __init__(self, status: int) -> None:
+ def __init__(self, status: int, headers: dict[str, str] | None = None) -> None:
super().__init__("provider body that must never reach the runtime")
self.status_code = status
+ self.headers = headers or {}
@pytest.fixture
@@ -186,10 +189,10 @@ def brain(monkeypatch: pytest.MonkeyPatch) -> dict[str, Any]:
async def deltas(grant: gateway.Grant, model: str, request: Any) -> AsyncIterator[Any]:
state["requests"].append((grant, model, request))
if state["fail"] is not None:
- raise _ProviderError(state["fail"])
+ raise _ProviderError(state["fail"], state.get("headers"))
yield BrainDelta(content="Looking")
if state["fail_late"] is not None:
- raise _ProviderError(state["fail_late"])
+ raise _ProviderError(state["fail_late"], state.get("headers"))
yield BrainDelta(
tool_call={
"id": "call_1",
@@ -280,7 +283,12 @@ def test_chat_streams_text_and_tool_calls_in_the_openai_shape(brain, guarded) ->
calls = [call for d in deltas for call in d.get("tool_calls") or []]
assert calls[0]["function"] == {"name": "read_file", "arguments": '{"path": "a.txt"}'}
assert chunks[-1]["choices"][0]["finish_reason"] == "tool_calls"
- assert chunks[-1]["usage"] == {"prompt_tokens": 12, "completion_tokens": 3, "total_tokens": 15}
+ assert chunks[-1]["usage"] == {
+ "prompt_tokens": 12,
+ "completion_tokens": 3,
+ "total_tokens": 15,
+ "prompt_tokens_details": {"cached_tokens": 0},
+ }
grant, model, _request = brain["requests"][0]
assert grant.provider == "openai" and model == "gpt-5.2"
@@ -323,6 +331,120 @@ def test_a_rate_limit_up_front_is_a_429_without_the_provider_body(brain, guarded
assert "never reach" not in answer.text
[email protected]("stream", [False, True])
+def test_retry_after_blocks_repeated_calls_and_expires(brain, guarded, monkeypatch, stream):
+ now = [100.0]
+ monkeypatch.setattr(gateway.time, "monotonic", lambda: now[0])
+ brain.update(fail=429, headers={"Retry-After": "90"})
+ token = gateway.grant_token("agent-1", "openai", scope="chat")
+ signal = gateway.watch_failure(token)
+ answer = _chat(guarded, token, {**_CHAT, "stream": stream})
+ assert answer.status_code == 429 and answer.headers["Retry-After"] == "90"
+ assert "Try again in 90 s" in signal.result(timeout=1)
+ assert "/continue" not in signal.result() # only the person's own turns resume
+ assert "fallback provider was called" in answer.text
+ assert "never reach" not in signal.result()
+ gateway.unwatch_failure(token, signal)
+
+ # A second agent on the same model/key must also respect the cooldown.
+ other = gateway.grant_token("agent-2", "openai")
+ now[0] += 40
+ assert _chat(guarded, other, _CHAT).headers["Retry-After"] == "50"
+ assert len(brain["requests"]) == 1
+ brain["fail"] = None
+ now[0] += 50
+ assert _chat(guarded, token, _CHAT).status_code == 200
+ assert len(brain["requests"]) == 2
+
+
+ "raw, expected",
+ [
+ ("12.3", 12.3),
+ ("0", 0),
+ ("-1", 0),
+ ("NaN", None),
+ ("Infinity", None),
+ ("invalid", None),
+ ("Wed, 21 Oct 2015 07:28:00 GMT", 60),
+ ],
+)
+def test_retry_after_parses_numeric_and_http_date_without_provider_body(monkeypatch, raw, expected):
+ monkeypatch.setattr(gateway.time, "time", lambda: 1445412420.0)
+ failure = gateway._failure("openai", _ProviderError(429, {"rEtRy-AfTeR": raw}))
+ assert failure.retry_after == expected
+ assert "never reach" not in str(failure)
+
+
+def test_a_long_limit_returns_immediately_without_waiting_or_fallback(brain, guarded):
+ brain.update(fail=429, headers={"Retry-After": "86400"})
+ token = gateway.grant_token("agent-1", "claude-api")
+ answer = _chat(guarded, token, _CHAT)
+ assert answer.headers["Retry-After"] == "86400"
+ assert len(brain["requests"]) == 1
+ assert brain["requests"][0][0].provider == "claude-api"
+
+
+def test_missing_retry_after_uses_short_conservative_cooldown(brain, guarded):
+ brain["fail"] = 429
+ token = gateway.grant_token("agent-1", "openai")
+ assert _chat(guarded, token, _CHAT).headers["Retry-After"] == "30"
+ assert _chat(guarded, token, _CHAT).status_code == 429
+ assert len(brain["requests"]) == 1
+
+
+def test_routine_failure_cannot_end_the_direct_chat(brain, guarded):
+ chat = gateway.grant_token("agent-1", "openai", scope="agent-1")
+ routine = gateway.grant_token("agent-1", "openai", scope="agent-1~runs")
+ assert chat != routine
+ chat_signal, routine_signal = gateway.watch_failure(chat), gateway.watch_failure(routine)
+ brain["fail"] = 429
+ _chat(guarded, routine, _CHAT)
+ assert routine_signal.done() and not chat_signal.done()
+ gateway.unwatch_failure(chat, chat_signal)
+ gateway.unwatch_failure(routine, routine_signal)
+
+
+def test_late_failure_keeps_the_old_turn_identity(brain):
+ token = gateway.grant_token("agent-1", "openai", scope="chat")
+ old = gateway.watch_failure(token)
+ gateway.unwatch_failure(token, old)
+ current = gateway.watch_failure(token)
+ gateway._report_failure(
+ gateway.verify(token), "m", gateway._failure("openai", _ProviderError(429)), old
+ )
+ assert old.done() and not current.done()
+ gateway.unwatch_failure(token, current)
+
+
+def test_midstream_rate_limit_stops_the_runner_without_done(brain, guarded):
+ token = gateway.grant_token("agent-1", "openai")
+ signal = gateway.watch_failure(token)
+ brain.update(fail_late=429, headers={"Retry-After": "3"})
+ response = _chat(guarded, token, {**_CHAT, "stream": True})
+ assert "Looking" in response.text and "[DONE]" not in response.text
+ assert "HTTP 429" in signal.result(timeout=1)
+ gateway.unwatch_failure(token, signal)
+
+
+def test_subscription_limit_never_uses_the_api_path(fake, guarded, monkeypatch):
+ async def limited(**kwargs):
+ fake.calls.append(kwargs)
+ raise SubscriptionReasoningError("usage limit", status=429, retry_after="120")
+ yield # pragma: no cover - keep this a stream
+
+ monkeypatch.setattr(fake, "stream", limited)
+ token = gateway.grant_token("agent-1", "openai-codex", "account-a")
+ signal = gateway.watch_failure(token)
+ answer = _post(guarded, token, {"model": "m", "input": "hello"})
+ assert answer.status_code == 429 and answer.headers["Retry-After"] == "120"
+ assert "openai-codex" in signal.result(timeout=1)
+ _post(guarded, token, {"model": "m", "input": "hello"})
+ assert len(fake.calls) == 1
+ gateway.check_cooldown("openai-codex", "m", "account-b")
+ gateway.unwatch_failure(token, signal)
+
+
def test_a_failure_mid_stream_is_an_error_chunk(brain, guarded) -> None:
brain["fail_late"] = 500
token = gateway.grant_token("agent-1", "openai")
@@ -331,6 +453,27 @@ def test_a_failure_mid_stream_is_an_error_chunk(brain, guarded) -> None:
assert "never reach" not in answer.text
+async def test_a_closed_stream_releases_the_provider_generator(monkeypatch):
+ from jarvis.core.protocols import BrainDelta
+
+ closed = []
+
+ async def deltas(*_args):
+ try:
+ yield BrainDelta(content="partial")
+ yield BrainDelta(content="more")
+ finally:
+ closed.append(True)
+
+ gateway.reset()
+ monkeypatch.setattr(gateway, "_deltas", deltas)
+ model, request = gateway.chat_request(_CHAT)
+ stream = await gateway.open_chat_stream(gateway.Grant("a", "openai"), model, request)
+ await anext(stream)
+ await stream.aclose()
+ assert closed == [True]
+
+
def test_each_shape_answers_only_its_own_providers(brain, guarded) -> None:
subscription = gateway.grant_token("agent-1", "openai-codex")
assert _chat(guarded, subscription, _CHAT).status_code == 400
@@ -343,7 +486,8 @@ def test_api_key_models_come_from_jarvis_catalog(guarded) -> None:
from jarvis.agent_chat.catalog import provider_row
with_catalog = next(
- name for name in ("claude-api", "openai", "gemini", "grok")
+ name
+ for name in ("claude-api", "openai", "gemini", "grok")
if (row := provider_row(name)) is not None and row.curated_models
)
token = gateway.grant_token("agent-1", with_catalog)
@@ -379,3 +523,360 @@ def test_a_streamed_answer_ends_cleanly_with_the_real_key_and_cost_context(
assert answer.status_code == 200
assert '"error"' not in answer.text
assert answer.text.rstrip().endswith("data: [DONE]")
+
+
+# ------------------------------------------------ which failures end the turn
+
+
+class _Overflow(Exception):
+ status_code = 400
+ body = {"error": {"code": "context_length_exceeded", "type": "invalid_request_error"}}
+
+
[email protected]("stream", [False, True])
+def test_a_context_overflow_goes_back_to_the_runtime_to_compress(brain, guarded, monkeypatch,
+ stream) -> None:
+ async def deltas(grant, model, request):
+ raise _Overflow("This model's maximum context length is 400000 tokens.")
+ yield # pragma: no cover — keep this a stream
+
+ monkeypatch.setattr(gateway, "_deltas", deltas)
+ token = gateway.grant_token("agent-1", "openai")
+ signal = gateway.watch_failure(token)
+ answer = _chat(guarded, token, {**_CHAT, "stream": stream})
+ assert answer.status_code == 400
+ error = answer.json()["error"]
+ assert error["code"] == "context_length_exceeded"
+ assert "context length exceeded" in error["message"].lower()
+ # The runtime compresses and resends; the Jarvis turn keeps running.
+ assert not signal.done()
+ gateway.unwatch_failure(token, signal)
+
+
[email protected](("status", "expected"), [(500, 502), (529, 503)])
+def test_a_transient_provider_failure_leaves_the_retry_to_the_runtime(
+ brain, guarded, status, expected
+) -> None:
+ brain["fail"] = status
+ token = gateway.grant_token("agent-1", "openai")
+ signal = gateway.watch_failure(token)
+ assert _chat(guarded, token, {**_CHAT, "stream": True}).status_code == expected
+ assert not signal.done()
+ gateway.unwatch_failure(token, signal)
+
+
+def test_a_refused_key_ends_the_turn_at_once(brain, guarded) -> None:
+ brain["fail"] = 401
+ token = gateway.grant_token("agent-1", "openai")
+ signal = gateway.watch_failure(token)
+ answer = _chat(guarded, token, _CHAT)
+ assert answer.status_code == 401 and answer.json()["error"]["code"] == "provider_auth"
+ assert "API keys" in signal.result(timeout=1)
+ gateway.unwatch_failure(token, signal)
+
+
+def test_a_subscription_overflow_tells_the_runtime_to_compress(fake, guarded, monkeypatch):
+ async def overflow(**kwargs):
+ raise SubscriptionReasoningError(
+ "This request exceeds the selected ChatGPT model's context limit. (HTTP 400)",
+ code="context_length_exceeded",
+ status=400,
+ )
+ yield # pragma: no cover - keep this a stream
+
+ monkeypatch.setattr(fake, "stream", overflow)
+ token = gateway.grant_token("agent-1", "openai-codex")
+ signal = gateway.watch_failure(token)
+ answer = _post(guarded, token, {"model": "m", "input": "hello", "stream": True})
+ assert answer.status_code == 400
+ assert answer.json()["error"]["code"] == "context_length_exceeded"
+ assert "context length exceeded" in answer.json()["error"]["message"].lower()
+ assert not signal.done()
+ gateway.unwatch_failure(token, signal)
+
+
+def test_a_subscription_overflow_mid_stream_keeps_its_code(fake, guarded, monkeypatch):
+ async def overflow(**kwargs):
+ yield {"type": "response.created", "response": {"id": "r1"}}
+ raise SubscriptionReasoningError("ChatGPT subscription reasoning failed.",
+ code="context_length_exceeded")
+
+ monkeypatch.setattr(fake, "stream", overflow)
+ token = gateway.grant_token("agent-1", "openai-codex")
+ answer = _post(guarded, token, {"model": "m", "input": "hello", "stream": True})
+ failed = [json.loads(line[5:]) for line in answer.text.splitlines()
+ if line.startswith("data:") and "response.failed" in line]
+ assert failed[0]["response"]["error"]["code"] == "context_length_exceeded"
+
+
+async def test_an_expired_claude_login_says_how_to_renew_it(monkeypatch) -> None:
+ import jarvis.agent_runtimes.model_map as model_map
+ import jarvis.core.config as config
+ from jarvis.agent_runtimes.provider_errors import ProviderRefusal
+ from jarvis.core.protocols import BrainMessage, BrainRequest
+
+ monkeypatch.setattr(model_map, "login_route", lambda provider, account: (True, None))
+ monkeypatch.setattr(config, "get_jarvis_agent_secret", lambda provider: None)
+ request = BrainRequest(messages=(BrainMessage("user", "Hi"),), max_tokens=16)
+ with pytest.raises(ProviderRefusal) as caught:
+ async for _ in gateway._deltas(gateway.Grant("a", "claude-api"), "claude-x", request):
+ pass
+ failure = gateway._failure("claude-api", caught.value)
+ assert (failure.status, failure.code) == (401, "claude_login_expired")
+ assert "Open Claude Code" in str(failure)
+
+
+async def test_a_request_the_subscription_client_refuses_is_a_400_not_a_retry():
+ from jarvis.live.subscription_reasoning import SubscriptionReasoning
+
+ async def credentials(**kwargs):
+ raise AssertionError("refused before any credential is read")
+
+ client = SubscriptionReasoning(credentials)
+ with pytest.raises(SubscriptionReasoningError) as caught:
+ async for _ in client.stream(model="m", input=[], instructions="", tools=[],
+ reasoning_effort="NOT AN EFFORT"):
+ pass
+ failure = gateway._subscription_failure(gateway.Grant("a", "openai-codex"), caught.value)
+ assert (failure.status, failure.code) == (400, "invalid_request")
+
+
[email protected]("stream", [False, True])
+def test_the_prompt_size_includes_cached_tokens(brain, guarded, monkeypatch, stream) -> None:
+ """Hermes compresses from ``prompt_tokens``; the plugins report only the
+ uncached share as ``input_tokens``. A long tool loop is mostly cache."""
+ from jarvis.core.protocols import BrainDelta
+
+ async def deltas(grant, model, request):
+ yield BrainDelta(content="ok", finish_reason="stop")
+ yield BrainDelta(usage={"input_tokens": 1_200, "output_tokens": 40,
+ "cache_hit_tokens": 98_000, "cache_write_tokens": 500})
+
+ monkeypatch.setattr(gateway, "_deltas", deltas)
+ token = gateway.grant_token("agent-1", "openai")
+ answer = _chat(guarded, token, {**_CHAT, "stream": stream})
+ if stream:
+ lines = [line[5:].strip() for line in answer.text.splitlines()
+ if line.startswith("data:")]
+ usage = json.loads(lines[-2])["usage"]
+ else:
+ usage = answer.json()["usage"]
+ assert usage == {
+ "prompt_tokens": 99_700,
+ "completion_tokens": 40,
+ "total_tokens": 99_740,
+ "prompt_tokens_details": {"cached_tokens": 98_000, "cache_write_tokens": 500},
+ }
+
+
+class _StreamOf:
+ """An OpenAI SDK stream stand-in: async-iterates prepared chunks."""
+
+ def __init__(self, chunks: list[Any]) -> None:
+ self._chunks = chunks
+
+ def __aiter__(self) -> AsyncIterator[Any]:
+ async def chunks() -> AsyncIterator[Any]:
+ for chunk in self._chunks:
+ yield chunk
+
+ return chunks()
+
+
+def _sdk_chunk(*, finish: str | None = None, tool_args: str | None = None) -> Any:
+ from types import SimpleNamespace
+
+ calls = None
+ if tool_args is not None:
+ calls = [SimpleNamespace(index=0, id="call_9", function=SimpleNamespace(
+ name="write_file", arguments=tool_args))]
+ delta = SimpleNamespace(content=None, tool_calls=calls)
+ return SimpleNamespace(choices=[SimpleNamespace(delta=delta, finish_reason=finish)],
+ usage=None)
+
+
[email protected]("stream", [False, True])
+def test_a_tool_call_cut_off_by_the_output_limit_stays_length(
+ brain, guarded, monkeypatch, stream
+) -> None:
+ """The real OpenAI-compatible adapter on a stream the output limit cut
+ off mid-arguments: the runtime must see "length", never a finished
+ tool call it would run with broken input."""
+ from types import SimpleNamespace
+
+ from jarvis.plugins.brain import _openai_base
+
+ class Completions:
+ async def create(self, **kwargs: Any) -> Any:
+ return _StreamOf([_sdk_chunk(tool_args='{"path": "a.py", "content": "def f():'),
+ _sdk_chunk(finish="length")])
+
+ client = SimpleNamespace(chat=SimpleNamespace(completions=Completions()), base_url="fake")
+
+ async def deltas(grant, model, request):
+ async for delta in _openai_base.stream_complete(client, model, request):
+ yield delta
+
+ monkeypatch.setattr(gateway, "_deltas", deltas)
+ token = gateway.grant_token("agent-1", "openai")
+ answer = _chat(guarded, token, {**_CHAT, "stream": stream})
+ if stream:
+ lines = [line[5:].strip() for line in answer.text.splitlines()
+ if line.startswith("data:")]
+ finish = json.loads(lines[-2])["choices"][0]["finish_reason"]
+ else:
+ finish = answer.json()["choices"][0]["finish_reason"]
+ assert finish == "length"
+
+
+ ("raw", "expected"),
+ [
+ ("FinishReason.MAX_TOKENS", "length"), # google-genai's enum as str()
+ ("max_tokens", "length"),
+ ("model_context_window_exceeded", "length"),
+ ("FinishReason.SAFETY", "content_filter"),
+ ("refusal", "content_filter"),
+ ("end_turn", "stop"),
+ ("tool_use", "stop"),
+ ],
+)
+def test_provider_stop_reasons_become_chat_completions_ones(raw, expected) -> None:
+ assert gateway._finish(raw) == expected
+
+
+def test_every_gateway_call_lands_in_the_cost_ledger(monkeypatch, guarded, tmp_path) -> None:
+ import jarvis.agent_chat.runner_api as runner_api
+ import jarvis.core.config as config
+ from jarvis.agent_runtimes.model_limits import ModelLimits
+ from jarvis.core.protocols import BrainDelta
+ from jarvis.costs import ledger
+
+ class Brain:
+ _model = "gpt-5.2"
+
+ async def complete(self, request: Any) -> AsyncIterator[BrainDelta]:
+ yield BrainDelta(content="OK", finish_reason="stop")
+ yield BrainDelta(usage={"input_tokens": 200, "output_tokens": 9,
+ "cache_hit_tokens": 1_800})
+
+ monkeypatch.setattr(runner_api, "build_brain", lambda provider, model: Brain())
+ monkeypatch.setattr(config, "get_jarvis_agent_secret", lambda provider: None)
+ ledger.set_ledger_path(tmp_path / "llm_usage.db")
+ gateway.reset()
+ try:
+ token = gateway.grant_token("agent-1", "openai")
+ gateway.register_model(token, "gpt-5.2", ModelLimits(400_000, 128_000))
+ assert _chat(guarded, token, {**_CHAT, "stream": True}).status_code == 200
+ assert _chat(guarded, token, _CHAT).status_code == 200
+ ledger.flush()
+ rows = list(ledger.read_usage(tmp_path / "llm_usage.db", 0, 2**62))
+ finally:
+ ledger.set_ledger_path(None)
+ gateway.reset()
+ assert [(r.provider, r.model, r.caller) for r in rows] == [
+ ("openai", "gpt-5.2", "agent-runtime")
+ ] * 2
+ assert (rows[0].tokens_in, rows[0].tokens_out, rows[0].tokens_cached) == (200, 9, 1_800)
+
+
+# --------------------------------------------------------- grant lifecycle
+
+
+def test_a_token_only_speaks_for_the_models_its_route_registered(brain, guarded) -> None:
+ from jarvis.agent_runtimes.model_limits import ModelLimits
+
+ token = gateway.grant_token("agent-1", "openai")
+ gateway.register_model(token, "gpt-5.2", ModelLimits())
+ assert _chat(guarded, token, _CHAT).status_code == 200
+ costly = _chat(guarded, token, {**_CHAT, "model": "gpt-5.5-pro"})
+ assert costly.status_code == 404
+ assert costly.json()["error"]["code"] == "model_not_found"
+ assert len(brain["requests"]) == 1
+
+
+def test_an_ollama_tag_and_its_latest_alias_are_one_model(brain, guarded) -> None:
+ from jarvis.agent_runtimes.model_limits import ModelLimits
+
+ token = gateway.grant_token("agent-1", "ollama")
+ gateway.register_model(token, "qwen3.5:latest", ModelLimits())
+ assert _chat(guarded, token, {**_CHAT, "model": "qwen3.5"}).status_code == 200
+
+
+def test_a_revoked_agent_token_is_refused(brain, guarded) -> None:
+ token = gateway.grant_token("agent-1", "openai", scope="s1")
+ other = gateway.grant_token("agent-2", "openai")
+ assert gateway.revoke_agent("agent-1") == 1
+ assert _chat(guarded, token, _CHAT).status_code == 401
+ assert _chat(guarded, other, _CHAT).status_code == 200
+ assert gateway.grant_token("agent-1", "openai", scope="s1") != token
+
+
+def test_old_session_grants_are_forgotten_but_never_a_running_turn(monkeypatch) -> None:
+ gateway.reset()
+ monkeypatch.setattr(gateway, "_GRANTS_MAX", 2)
+ first = gateway.grant_token("agent-1", "openai", scope="s1")
+ running = gateway.watch_failure(first)
+ second = gateway.grant_token("agent-1", "openai", scope="s2")
+ third = gateway.grant_token("agent-1", "openai", scope="s3")
+ fourth = gateway.grant_token("agent-1", "openai", scope="s4")
+ assert gateway.verify(first) is not None # its turn is still running
+ assert gateway.verify(second) is None
+ assert gateway.verify(third) is not None and gateway.verify(fourth) is not None
+ gateway.unwatch_failure(first, running)
+ gateway.reset()
+
+
+ ("requested", "offered", "expected"),
+ [
+ ("max", ("low", "medium", "high", "xhigh"), "xhigh"),
+ ("high", ("low", "medium", "high"), "high"),
+ ("none", ("low", "medium"), "low"),
+ ("xhigh", ("medium",), "medium"),
+ ("turbo", ("low", "medium"), "low"),
+ ],
+)
+async def test_a_runtime_thinking_level_snaps_to_one_the_model_offers(requested, offered,
+ expected) -> None:
+ from jarvis.live.subscription_reasoning import SubscriptionReasoning
+
+ async def credentials(**kwargs):
+ raise AssertionError("no catalog request is needed")
+
+ client = SubscriptionReasoning(credentials)
+ client._model_efforts = {"gpt-x": offered}
+ args = {"model": "gpt-x", "input": [], "instructions": "", "tools": [],
+ "reasoning_effort": requested}
+ assert (await gateway._snapped_effort(client, args))["reasoning_effort"] == expected
+
+
+def test_a_developer_message_also_moves_into_the_instructions() -> None:
+ args = gateway.request_args(
+ {
+ "model": "m",
+ "instructions": "",
+ "input": [
+ {"type": "message", "role": "developer", "content": "You are Probe."},
+ {"role": "user", "content": [{"type": "input_text", "text": "Hi"}]},
+ ],
+ }
+ )
+ assert args["instructions"] == "You are Probe."
+ assert [item["role"] for item in args["input"]] == ["user"]
+
+
+def test_vertex_runs_on_a_cloud_project_without_a_key(monkeypatch) -> None:
+ import jarvis.agent_runtimes.model_map as model_map
+ import jarvis.core.config as config
+ from jarvis.core.config import override_provider_secrets
+
+ cfg = SimpleNamespace(brain=SimpleNamespace(providers={}))
+ assert "vertex" in model_map.supported_providers()
+ with override_provider_secrets({"vertex": None}):
+ monkeypatch.setattr(config, "vertex_credential_configured", lambda *a: False)
+ with pytest.raises(model_map.RouteUnavailable, match="No API key"):
+ model_map._checked_model(cfg, "vertex", "gemini-3-pro")
+ monkeypatch.setattr(config, "vertex_credential_configured", lambda *a: True)
+ assert model_map._checked_model(cfg, "vertex", "gemini-3-pro") == "gemini-3-pro"
+
diff --git a/tests/unit/agent_runtimes/test_runtime_lifecycle.py b/tests/unit/agent_runtimes/test_runtime_lifecycle.py
new file mode 100644
index 0000000000..0d99960e5e
--- /dev/null
+++ b/tests/unit/agent_runtimes/test_runtime_lifecycle.py
@@ -0,0 +1,195 @@
+"""Folder layout per app instance, pinned versions, PATH refresh, descendant reaping."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import psutil
+import pytest
+
+from jarvis.agent_runtimes import base, hermes, versions
+from jarvis.core import path_augment
+from jarvis.core.process_tree import DescendantTracker
+from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS
+
+
+def test_each_app_instance_keeps_its_own_runtime_folders(monkeypatch, tmp_path):
+ monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))
+ monkeypatch.delenv("JARVIS_INSTANCE", raising=False)
+ default = base.runtimes_root()
+ monkeypatch.setenv("JARVIS_INSTANCE", "dev")
+ dev = base.runtimes_root()
+ assert default != dev and dev.name == "agent_runtimes-dev"
+ assert base.legacy_runtimes_root() == default
+
+
+def test_the_pins_name_a_tested_release_at_or_above_the_minimum():
+ for runtime in ("hermes", "openclaw"):
+ pin = versions.pin(runtime)
+ assert pin.tested is not None and pin.tested >= pin.minimum, runtime
+ assert len(versions.pin("hermes").commit) == 40
+ assert versions.pin("hermes").config_version
+
+
+def _fake_hermes(tmp_path: Path, version_line: str) -> str:
+ script = tmp_path / "hermes_fake.py"
+ script.write_text(f"print({version_line!r})\n", encoding="utf-8")
+ return str(script)
+
+
+ ("line", "ready", "untested"),
+ [
+ ("Hermes Agent v0.21.5+1.gabc (2026.9.24)", True, False),
+ ("Hermes Agent v9.0.0 (2027.1.1)", True, True),
+ ("Hermes Agent v0.1.0 (2025.1.1)", False, False),
+ ],
+)
+def test_a_newer_release_runs_but_is_reported_untested(
+ tmp_path, monkeypatch, line, ready, untested
+):
+ script = _fake_hermes(tmp_path, line)
+ monkeypatch.setattr(hermes, "_binary", lambda: sys.executable)
+ monkeypatch.setattr(
+ hermes, "run_version", lambda argv: base.run_version([sys.executable, script])
+ )
+ status = hermes.HermesRuntime().detect(refresh=True)
+ assert (status.ready, status.untested) == (ready, untested)
+ assert status.build == line
+ assert status.to_dict()["untested"] is untested
+
+
+def test_a_runtime_installed_mid_session_is_found_without_a_restart(tmp_path, monkeypatch):
+ fresh = tmp_path / "Programs" / "fresh"
+ fresh.mkdir(parents=True)
+ monkeypatch.setenv("PATH", str(tmp_path / "old"))
+ added = path_augment.refresh_from_persistent_path(
+ lambda: [f"{tmp_path / 'old'};{fresh};{tmp_path / 'missing'}"],
+ skip=lambda entry: "skipme" in entry,
+ )
+ assert added == [str(fresh)]
+ assert str(fresh) in __import__("os").environ["PATH"]
+ # Idempotent: nothing is added twice.
+ assert path_augment.refresh_from_persistent_path(lambda: [str(fresh)]) == []
+
+
+def test_jarvis_hermes_folders_are_never_taken_from_the_persistent_path(tmp_path, monkeypatch):
+ from jarvis.agent_runtimes.path_cleanup import is_jarvis_hermes_bin
+
+ stale = tmp_path / "Jarvis" / "agent_runtimes" / "hermes" / "agent-1" / "bin"
+ stale.mkdir(parents=True)
+ monkeypatch.setenv("PATH", "")
+ added = path_augment.refresh_from_persistent_path(
+ lambda: [str(stale)], skip=is_jarvis_hermes_bin
+ )
+ assert added == []
+
+
+def test_a_detached_grandchild_is_reaped_with_its_parent(tmp_path):
+ """POSIX: a setsid'd child leaves the process group; the tracker still has it."""
+ pid_file = tmp_path / "grandchild.pid"
+ code = (
+ "import os, subprocess, sys, time; "
+ "child = subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(60)'], "
+ "start_new_session=os.name != 'nt'); "
+ f"open({str(pid_file)!r}, 'w').write(str(child.pid)); time.sleep(60)"
+ )
+ parent = subprocess.Popen( # noqa: S603 — started and ended by this test
+ [sys.executable, "-c", code], creationflags=NO_WINDOW_CREATIONFLAGS
+ )
+ try:
+ deadline = time.monotonic() + 15
+ while not pid_file.exists() and time.monotonic() < deadline:
+ time.sleep(0.05)
+ grandchild = int(pid_file.read_text(encoding="utf-8"))
+ tracker = DescendantTracker(parent.pid, enabled=True)
+ tracker.snapshot()
+ parent.kill()
+ parent.wait(timeout=10)
+ assert grandchild in tracker.close()
+ proc = psutil.Process(grandchild)
+ # Not our child: wait() would block on a zombie nobody reaps (a
+ # container without an init process). Dead or zombie is the outcome.
+ deadline = time.monotonic() + 10
+ while proc.is_running() and proc.status() != psutil.STATUS_ZOMBIE:
+ if time.monotonic() > deadline:
+ break
+ time.sleep(0.05)
+ except psutil.NoSuchProcess:
+ pass
+ finally:
+ if parent.poll() is None:
+ parent.kill()
+ try:
+ survivor = psutil.Process(grandchild).status() != psutil.STATUS_ZOMBIE
+ except psutil.NoSuchProcess: # gone between checks: reaped
+ survivor = False
+ assert not survivor
+
+
+async def test_turns_and_setup_jobs_share_one_gate():
+ gate = base.RuntimeGate()
+ await gate.acquire_turn(1)
+ entered = []
+
+ async def setup() -> None:
+ async with gate.exclusive(5):
+ entered.append(gate.turns)
+
+ import asyncio
+
+ job = asyncio.ensure_future(setup())
+ await asyncio.sleep(0.1)
+ assert entered == [] # waits for the running turn
+ gate.release_turn()
+ await asyncio.wait_for(job, 2)
+ assert entered == [0]
+ with pytest.raises(TimeoutError):
+ async with gate.exclusive(0.1):
+ await gate.acquire_turn(0.1) # no turn starts while setup holds it
+
+
+def test_a_detached_child_no_snapshot_saw_is_found_by_its_turn_mark():
+ """CI 2026-10-08: a setsid child appeared between two snapshots, its parent
+ exited, and the tree walk could no longer reach it. It still carries the
+ turn's inherited environment mark."""
+ import os
+ import uuid
+
+ from jarvis.core.process_tree import TURN_MARKER_ENV
+
+ mark = uuid.uuid4().hex
+ env = {**os.environ, TURN_MARKER_ENV: mark}
+ orphan = subprocess.Popen( # noqa: S603 — started and ended by this test
+ [sys.executable, "-c", "import time; time.sleep(60)"],
+ env=env,
+ start_new_session=os.name != "nt",
+ creationflags=NO_WINDOW_CREATIONFLAGS,
+ )
+ try:
+ tracker = DescendantTracker(999_999_999, enabled=True, marker=mark) # parent long gone
+ assert orphan.pid in tracker.close()
+ orphan.wait(timeout=10)
+ finally:
+ if orphan.poll() is None:
+ orphan.kill()
+
+
+def test_an_unmarked_process_is_never_touched():
+ import os
+
+ bystander = subprocess.Popen( # noqa: S603 — started and ended by this test
+ [sys.executable, "-c", "import time; time.sleep(60)"],
+ creationflags=NO_WINDOW_CREATIONFLAGS,
+ )
+ try:
+ tracker = DescendantTracker(999_999_999, enabled=True, marker="not-this-turn")
+ assert bystander.pid not in tracker.close()
+ assert bystander.poll() is None
+ finally:
+ bystander.kill()
+ bystander.wait(timeout=10)
+ assert os.getpid() # this process is never a candidate either
diff --git a/tests/unit/agent_runtimes/test_runtime_manager.py b/tests/unit/agent_runtimes/test_runtime_manager.py
index bc1e67df94..160e9949f8 100644
--- a/tests/unit/agent_runtimes/test_runtime_manager.py
+++ b/tests/unit/agent_runtimes/test_runtime_manager.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import asyncio
+import os
import sys
from pathlib import Path
from types import SimpleNamespace
@@ -34,6 +35,7 @@ class FakeDriver:
installed: bool = True,
update_fixes: bool = True,
marker: Path | None = None,
+ version: str = "1.0.0",
) -> None:
self.name = name
self.label = name.title()
@@ -42,9 +44,11 @@ class FakeDriver:
self.installed = installed
self.update_fixes = update_fixes
self.marker = marker
+ self.version = version
self.stopped = 0
self.refreshed = 0
self.is_busy = False
+ self.installs: list[str | None] = []
def detect(self, *, refresh: bool = False) -> RuntimeStatus:
self.refreshed += int(refresh)
@@ -56,7 +60,7 @@ class FakeDriver:
self.name,
self.label,
installed=installed,
- version="1.0.0",
+ version=self.version,
ready=ready,
problem="" if ready else "not ready",
problem_kind=kind,
@@ -67,12 +71,16 @@ class FakeDriver:
code = f"print('{word}'); {write}raise SystemExit({self.exit_code})"
return [sys.executable, "-c", code]
- def install_command(self) -> list[str]:
- return self._script("installing", True)
+ def install_command(self, revision: str | None = None) -> list[str]:
+ self.installs.append(revision)
+ return self._script(f"installing {revision or 'tested'}", True)
def update_command(self) -> list[str]:
return self._script("updating", self.update_fixes)
+ def revision(self, status: RuntimeStatus) -> str:
+ return status.version
+
def busy(self) -> bool:
return self.is_busy
@@ -80,6 +88,12 @@ class FakeDriver:
self.stopped += 1
[email protected](autouse=True)
+def _no_persistent_path(monkeypatch: pytest.MonkeyPatch):
+ """Setup jobs never read this machine's registry PATH in tests."""
+ monkeypatch.setattr(manager, "_refresh_path", lambda: None)
+
+
@pytest.fixture
def fakes(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
monkeypatch.setattr(base, "runtimes_root", lambda: tmp_path)
@@ -196,6 +210,7 @@ async def test_an_update_that_leaves_the_runtime_broken_is_repaired_by_an_instal
async def test_the_daily_update_waits_while_a_turn_runs(fakes):
+ fakes["hermes"].version = "0.0.1" # older than the tested release
fakes["hermes"].is_busy = True
await manager._update_when_idle("hermes")
assert manager.job("hermes") is None
@@ -205,8 +220,20 @@ async def test_the_daily_update_waits_while_a_turn_runs(fakes):
assert manager.job("hermes").state == "done"
+async def test_the_daily_update_never_moves_past_the_tested_release(fakes):
+ from jarvis.agent_runtimes import versions
+
+ tested = versions.pin("hermes").tested_text
+ for installed in (tested, "999.0.0"):
+ fakes["hermes"].version = installed
+ await manager._update_when_idle("hermes")
+ assert manager.job("hermes") is None, installed
+
+
async def test_the_daily_round_updates_only_runtimes_an_agent_uses(fakes, monkeypatch):
monkeypatch.setattr(manager, "_FIRST_UPDATE_DELAY_S", 0)
+ fakes["hermes"].version = "0.0.1"
+ fakes["openclaw"].version = "0.0.1"
rounds: list[int] = []
async def in_use() -> set[str]:
@@ -258,9 +285,204 @@ def test_a_claude_login_in_the_api_key_slot_is_not_an_api_key(fakes, monkeypatch
assert "claude-api" not in body["supported_providers"]
assert body["login_providers"] == []
# A live login: Claude is offered, marked as running on the login.
+ import jarvis.agent_runtimes.provider_errors as provider_errors
+
monkeypatch.setattr(model_map, "claude_login_token", lambda: login)
+ monkeypatch.setattr(provider_errors, "_REPORTS", {})
+ monkeypatch.setattr(provider_errors, "_claude_usage", lambda token: {})
routes._USABLE_CACHE[:] = [float("-inf"), [], []]
with override_provider_secrets(secrets):
body = TestClient(app).get("/api/agent-runtimes").json()
assert "claude-api" in body["supported_providers"]
assert body["login_providers"] == ["claude-api"]
+ assert body["access_blocked"] == {}
+ # Extra Usage off: the way exists, the dialog shows it disabled with why.
+ monkeypatch.setattr(provider_errors, "_REPORTS", {})
+ monkeypatch.setattr(
+ provider_errors, "_claude_usage", lambda token: {"extra_usage": {"is_enabled": False}}
+ )
+ routes._USABLE_CACHE[:] = [float("-inf"), [], []]
+ with override_provider_secrets(secrets):
+ body = TestClient(app).get("/api/agent-runtimes").json()
+ assert body["access_blocked"] == {"claude-api": {"subscription": "extra_usage_off"}}
+
+
+# ------------------------------------------------- gate, prepare, rollback
+
+
+class GatedDriver(FakeDriver):
+ """A fake driver with the real shared/exclusive runtime gate."""
+
+ def __init__(self, *args, **kwargs) -> None:
+ super().__init__(*args, **kwargs)
+ self.gate = base.RuntimeGate()
+ self.prepared: list[str] = []
+ self.prepare_needed = False
+
+ def needs_prepare(self, status: RuntimeStatus) -> bool:
+ return self.prepare_needed and not self.prepared
+
+ def prepare_command(self) -> tuple[list[str], dict[str, str]]:
+ return [sys.executable, "-c", "print('preparing')"], dict(os.environ)
+
+ def mark_prepared(self, status: RuntimeStatus) -> None:
+ self.prepared.append(status.version)
+
+
+async def test_an_update_waits_for_a_running_turn_and_holds_new_turns(fakes, monkeypatch):
+ gated = GatedDriver("openclaw")
+ monkeypatch.setitem(runtimes._DRIVERS, "openclaw", gated)
+ await gated.gate.acquire_turn(1) # a turn is running
+ started = await manager.start("openclaw", "update")
+ await asyncio.sleep(0.3)
+ assert started.state == "running" and gated.stopped == 0 # nothing touched yet
+ # A new turn arriving now waits for the update, not the other way round.
+ with pytest.raises(TimeoutError):
+ await gated.gate.acquire_turn(0.2)
+ gated.gate.release_turn()
+ done = await _finish("openclaw")
+ assert done.state == "done" and gated.stopped == 1
+ await gated.gate.acquire_turn(1) # turns run again afterwards
+ gated.gate.release_turn()
+
+
+async def test_a_ready_runtime_that_needs_preparing_gets_a_prepare_job(fakes, monkeypatch):
+ gated = GatedDriver("hermes")
+ gated.prepare_needed = True
+ monkeypatch.setitem(runtimes._DRIVERS, "hermes", gated)
+ started = await manager.ensure("hermes")
+ assert started is not None and started.kind == "prepare"
+ status = await manager.wait_ready("hermes", timeout_s=30)
+ assert status.ready and gated.prepared == ["1.0.0"]
+ assert await manager.ensure("hermes") is None # prepared once per build
+
+
+async def test_a_failed_setup_rolls_back_to_the_last_good_release(unset, monkeypatch):
+ from jarvis.agent_runtimes import versions
+
+ broken = FakeDriver("openclaw", ready=False, update_fixes=False, exit_code=1)
+ monkeypatch.setitem(runtimes._DRIVERS, "openclaw", broken)
+ versions.remember_good("openclaw", "2026.1.1", "2026.1.1")
+ await manager.start("openclaw", "update")
+ await manager.wait_ready("openclaw", timeout_s=30)
+ # Update failed -> fresh install of the tested release -> back to last good.
+ assert broken.installs == [None, "2026.1.1"]
+
+
+async def test_a_successful_setup_is_remembered_for_rollback(unset):
+ from jarvis.agent_runtimes import versions
+
+ await manager.ensure("hermes")
+ await manager.wait_ready("hermes", timeout_s=30)
+ assert versions.last_good("hermes") == {"version": "1.0.0", "revision": "1.0.0"}
+
+
+async def test_a_missing_tool_is_the_reason_the_chat_shows(fakes, monkeypatch):
+ code = (
+ "import sys; print('Setup needs git. Install it with your system package manager, "
+ f"then try again.', file=sys.stderr); raise SystemExit({base.SETUP_MISSING_TOOL_EXIT})"
+ )
+ monkeypatch.setattr(
+ fakes["hermes"], "install_command", lambda revision=None: [sys.executable, "-c", code]
+ )
+ await manager.start("hermes", "install")
+ done = await _finish("hermes")
+ assert done.state == "failed"
+ assert manager.failure_reason("hermes").startswith("Setup needs git.")
+
+
+async def test_a_failed_job_names_the_installers_last_words(fakes, monkeypatch):
+ code = "print('download refused: HTTP 404'); raise SystemExit(22)"
+ monkeypatch.setattr(
+ fakes["hermes"], "install_command", lambda revision=None: [sys.executable, "-c", code]
+ )
+ await manager.start("hermes", "install")
+ done = await _finish("hermes")
+ assert "exit 22" in done.message and "HTTP 404" in done.message
+
+
+async def test_a_missing_shell_fails_plainly(fakes, monkeypatch):
+ monkeypatch.setattr(
+ fakes["hermes"], "install_command", lambda revision=None: ["bash", "-c", "true"]
+ )
+ monkeypatch.setattr(manager.shutil, "which", lambda name: None)
+ await manager.start("hermes", "install")
+ done = await _finish("hermes")
+ assert done.state == "failed" and "Setup needs bash" in done.message
+
+
+# ------------------------------------------------------ installer wrappers
+
+
+def _bash() -> str | None:
+ import shutil
+
+ found = shutil.which("bash")
+ if sys.platform == "win32" and (not found or "system32" in found.lower()):
+ # WSL's launcher is not a POSIX shell for this process; Git for
+ # Windows' bash is.
+ git_bash = Path(os.environ.get("ProgramFiles", r"C:\Program Files")) / "Git/bin/bash.exe"
+ return str(git_bash) if git_bash.is_file() else None
+ return found
+
+
[email protected](_bash() is None, reason="no bash on this machine")
+def test_the_posix_installer_reports_a_missing_tool():
+ import subprocess
+
+ argv = base.posix_installer(
+ "https://example.invalid/install.sh", ["--x"], requires=("jarvis-no-such-tool",)
+ )
+ done = subprocess.run([_bash(), *argv[1:]], capture_output=True, text=True, timeout=60)
+ assert done.returncode == base.SETUP_MISSING_TOOL_EXIT
+ # The first missing tool is named: curl itself on a bare container.
+ import shutil
+
+ first = "curl" if shutil.which("curl") is None else "jarvis-no-such-tool"
+ assert f"Setup needs {first}" in done.stderr
+
+
[email protected](_bash() is None, reason="no bash on this machine")
+def test_the_posix_installer_fails_when_the_download_fails():
+ """``curl | bash`` reported success here (bash ran an empty script)."""
+ import shutil
+ import subprocess
+
+ if shutil.which("curl") is None:
+ pytest.skip("no curl on this machine")
+ argv = base.posix_installer("https://127.0.0.1:9/install.sh", ["--x"])
+ done = subprocess.run([_bash(), *argv[1:]], capture_output=True, text=True, timeout=60)
+ assert done.returncode != 0
+
+
+def test_installers_are_pinned_and_skip_the_browser_and_desktop_control(monkeypatch):
+ from jarvis.agent_runtimes import hermes, openclaw, versions
+
+ for windows in (True, False):
+ monkeypatch.setattr(hermes, "is_windows", lambda w=windows: w)
+ monkeypatch.setattr(openclaw, "is_windows", lambda w=windows: w)
+ text = " ".join(hermes.HermesRuntime().install_command() or [])
+ assert versions.pin("hermes").commit in text
+ assert ("-SkipBrowser" in text) if windows else ("--skip-browser" in text)
+ assert "computer" in text.lower()
+ claw = " ".join(openclaw.OpenClawRuntime().install_command() or [])
+ assert versions.pin("openclaw").tested_text in claw
+ if windows:
+ # Private Node only: never the full installer that tries winget (UAC).
+ assert "-NodeOnly" in claw and "winget" not in claw
+ else:
+ assert "install-cli.sh" in claw and "--prefix" in claw
+ # Updates go to the same pinned release, never to upstream latest.
+ assert "update" not in (hermes.HermesRuntime().update_command() or [])
+
+
+def test_the_windows_openclaw_install_runs_npm_scripts_on_the_private_node(monkeypatch):
+ """npm runs OpenClaw's preinstall via ``cmd /c node``; CI's system Node 22
+ was picked and rejected (2026-10-07). The private Node must come first."""
+ from jarvis.agent_runtimes import openclaw
+
+ monkeypatch.setattr(openclaw, "is_windows", lambda: True)
+ text = " ".join(openclaw.OpenClawRuntime().install_command() or [])
+ node_dir = str(openclaw.cli_prefix() / "node")
+ path_set = text.index("$env:Path = '" + node_dir + ";'")
+ assert path_set < text.index("npm-cli.js")
diff --git a/tests/unit/agent_runtimes/test_smoke_lifecycle.py b/tests/unit/agent_runtimes/test_smoke_lifecycle.py
new file mode 100644
index 0000000000..a86d9b94ed
--- /dev/null
+++ b/tests/unit/agent_runtimes/test_smoke_lifecycle.py
@@ -0,0 +1,72 @@
+"""A failed or cancelled live probe must release its turn and reap its process."""
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+from jarvis.agent_runtimes.base import RuntimeLaunch, RuntimeTurn
+from jarvis.agent_runtimes.model_map import ModelRoute
+from scripts.spikes import agent_runtimes_e2e as smoke
+
+
+def setup_probe(monkeypatch, tmp_path, *, missing=False):
+ released = []
+ workspace = tmp_path / "workspace"
+ workspace.mkdir()
+ route = ModelRoute("ollama", "fake", "http://localhost", "chat_completions", None)
+ turn = RuntimeTurn("test", "Test", "society:test", workspace, route, None, False)
+ fake = Path(__file__).resolve().parents[2] / "fakes" / "fake_acp_agent.py"
+
+ class Runtime:
+ async def launch(self, _turn):
+ return RuntimeLaunch(
+ argv=[str(tmp_path / "nonexistent")] if missing else [sys.executable, str(fake)],
+ env={**os.environ, "FAKE_ACP_STORE": str(tmp_path / "store.json")},
+ cwd=workspace,
+ release=lambda: released.append(True),
+ )
+
+ monkeypatch.setattr(smoke, "driver", lambda _name: Runtime())
+ return turn, released
+
+
+async def test_spawn_failure_releases_slot(monkeypatch, tmp_path):
+ turn, released = setup_probe(monkeypatch, tmp_path, missing=True)
+ with pytest.raises(OSError):
+ await smoke._run("fake", turn, "hello")
+ assert released == [True]
+
+
+async def test_cancellation_reaps_the_child_and_releases_slot(monkeypatch, tmp_path):
+ turn, released = setup_probe(monkeypatch, tmp_path)
+ spawned = asyncio.Event()
+ processes = []
+ create = asyncio.create_subprocess_exec
+
+ async def capture(*args, **kwargs):
+ proc = await create(*args, **kwargs)
+ processes.append(proc)
+ spawned.set()
+ return proc
+
+ monkeypatch.setattr(smoke.asyncio, "create_subprocess_exec", capture)
+ task = asyncio.create_task(smoke._run("fake", turn, "HANG"))
+ try:
+ await asyncio.wait_for(spawned.wait(), 5)
+ finally:
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ assert released == [True]
+ assert processes[0].returncode is not None
+
+
+async def test_success_releases_slot(monkeypatch, tmp_path):
+ turn, released = setup_probe(monkeypatch, tmp_path)
+ result, _io = await smoke._run("fake", turn, "hello")
+ assert result.status == "done"
+ assert result.result_text == "echo: hello"
+ assert released == [True]
diff --git a/tests/unit/agent_runtimes/test_subscription_rejections.py b/tests/unit/agent_runtimes/test_subscription_rejections.py
new file mode 100644
index 0000000000..10792cc2cd
--- /dev/null
+++ b/tests/unit/agent_runtimes/test_subscription_rejections.py
@@ -0,0 +1,155 @@
+"""A rejected subscription request must not become a retryable server failure."""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from jarvis.agent_runtimes import gateway
+from jarvis.core.http_pool import HttpClientPool
+from jarvis.live.subscription_auth import SubscriptionCredentials
+from jarvis.live.subscription_reasoning import SubscriptionReasoning
+from jarvis.ui.web.runtime_gateway_routes import router
+
+
[email protected]("stream", [False, True])
+ ("status", "code", "hint", "expected"),
+ [
+ (400, "invalid_function_parameters", "tool schema", (400, "invalid_tool_schema")),
+ (400, "context_length_exceeded", "context", (400, "context_length_exceeded")),
+ (404, "model_not_found", "model", (404, "model_not_found")),
+ (422, "invalid_request_error", "HTTP 422", (400, "invalid_request")),
+ (400, "private-code-must-not-leak", "HTTP 400", (400, "invalid_request")),
+ ],
+)
+def test_rejection_preserves_status_and_safe_reason(
+ monkeypatch, stream, status, code, hint, expected
+):
+ requests = []
+
+ async def credentials(**kwargs):
+ return SubscriptionCredentials("fixture-token", "fixture-account")
+
+ def upstream(request):
+ requests.append(request)
+ return httpx.Response(
+ status,
+ json={"error": {"code": code, "message": "private-provider-body"}},
+ )
+
+ client = SubscriptionReasoning(
+ credentials, http_pool=HttpClientPool(transport=httpx.MockTransport(upstream))
+ )
+ gateway.reset()
+ monkeypatch.setattr(gateway, "_client", lambda account_id: client)
+ token = gateway.grant_token("rejection-test", "openai-codex")
+ app = FastAPI()
+ app.include_router(router)
+ with TestClient(app) as local:
+ response = local.post(
+ f"{gateway.BASE_PATH}/responses",
+ headers={"Authorization": f"Bearer {token}"},
+ json={"model": "selected", "input": "Hi", "stream": stream},
+ )
+ gateway.reset()
+
+ error = response.json()["error"]
+ assert (response.status_code, error["code"]) == expected
+ assert hint in error["message"]
+ assert "private-provider-body" not in response.text
+ assert "private-code-must-not-leak" not in response.text
+ assert len(requests) == 1
+
+
[email protected]("body", [b"not JSON", b"x" * 70_000], ids=["invalid", "oversized"])
+async def test_invalid_error_bodies_still_report_rejection_without_leaking(body):
+ from jarvis.live.subscription_reasoning import SubscriptionReasoningError
+
+ async def credentials(**kwargs):
+ return SubscriptionCredentials("fixture-token", "fixture-account")
+
+ client = SubscriptionReasoning(
+ credentials,
+ http_pool=HttpClientPool(
+ transport=httpx.MockTransport(lambda request: httpx.Response(400, content=body))
+ ),
+ )
+ try:
+ with pytest.raises(SubscriptionReasoningError, match="HTTP 400") as caught:
+ async for _ in client.stream(model="selected", input=[], instructions="", tools=[]):
+ pass
+ assert caught.value.status == 400
+ assert caught.value.code == "invalid_request_error"
+ assert body.decode() not in str(caught.value)
+ finally:
+ await client.aclose()
+
+
+async def test_rejection_after_stream_start_stays_an_sse_failure(monkeypatch):
+ from jarvis.live.subscription_reasoning import SubscriptionReasoningError
+
+ class FailingStream:
+ async def stream(self, **kwargs):
+ yield {"type": "response.created", "response": {"id": "fixture"}}
+ raise SubscriptionReasoningError("Request rejected.", status=400)
+
+ gateway.reset()
+ monkeypatch.setattr(gateway, "_client", lambda account_id: FailingStream())
+ events = [
+ json.loads(frame.decode().split("data: ")[1])
+ async for frame in gateway.stream_response(gateway.Grant("test", "openai-codex"), {})
+ ]
+ assert [event["type"] for event in events] == ["response.created", "response.failed"]
+ gateway.reset()
+
+
+async def test_broken_error_body_keeps_the_received_http_status():
+ from jarvis.live.subscription_reasoning import SubscriptionReasoningError
+
+ class BrokenBody(httpx.AsyncByteStream):
+ async def __aiter__(self):
+ raise httpx.ReadError("private transport diagnostics")
+ yield b"" # pragma: no cover - async iterator protocol
+
+ async def credentials(**kwargs):
+ return SubscriptionCredentials("fixture-token", "fixture-account")
+
+ client = SubscriptionReasoning(
+ credentials,
+ http_pool=HttpClientPool(
+ transport=httpx.MockTransport(lambda request: httpx.Response(400, stream=BrokenBody()))
+ ),
+ )
+ try:
+ with pytest.raises(SubscriptionReasoningError, match="HTTP 400") as caught:
+ async for _ in client.stream(model="selected", input=[], instructions="", tools=[]):
+ pass
+ assert caught.value.status == 400
+ assert "private" not in str(caught.value)
+ finally:
+ await client.aclose()
+
+
+async def test_closing_an_accepted_response_closes_the_upstream(monkeypatch):
+ closed = []
+
+ class Stream:
+ async def stream(self, **kwargs):
+ try:
+ yield {"type": "response.created", "response": {"id": "fixture"}}
+ yield {"type": "response.output_text.delta", "delta": "text"}
+ finally:
+ closed.append(True)
+
+ gateway.reset()
+ monkeypatch.setattr(gateway, "_client", lambda account_id: Stream())
+ events = await gateway.open_response_stream(gateway.Grant("test", "openai-codex"), {})
+ await anext(events)
+ await events.aclose()
+ assert closed == [True]
+ gateway.reset()
diff --git a/tests/unit/brain/test_gemini_native_tool_history.py b/tests/unit/brain/test_gemini_native_tool_history.py
index a8e511f85c..477b5ae916 100644
--- a/tests/unit/brain/test_gemini_native_tool_history.py
+++ b/tests/unit/brain/test_gemini_native_tool_history.py
@@ -94,7 +94,11 @@ def test_tool_result_becomes_unwrapped_function_response() -> None:
assert "tool_result" not in response["response"]["result"]
-def test_signature_less_tool_use_keeps_text_form() -> None:
+def test_a_signature_less_call_replays_natively_with_the_sentinel() -> None:
+ """A call whose signature is gone (an app restart between rounds, a
+ second instance) must still be a functionCall: as text it breaks the
+ call/response pairing (400) and teaches the model to call tools in prose.
+ Google documents the sentinel for exactly this reconstruction."""
contents = _to_gemini_contents(
(
BrainMessage(
@@ -109,12 +113,52 @@ def test_signature_less_tool_use_keeps_text_form() -> None:
),
)
- parts = contents[0]["parts"]
- assert all("functionCall" not in p for p in parts), (
- "a signature-less call must NOT replay natively — Gemini 3 rejects "
- "functionCall parts without their thought_signature (400)"
+ (part,) = contents[0]["parts"]
+ assert part["functionCall"] == {"name": "search_web", "args": {"query": "divo"}}
+ assert part["thought_signature"] == "skip_thought_signature_validator"
+
+
+def test_a_parallel_step_replays_every_call_and_answers_them_in_one_turn() -> None:
+ """Gemini signs only the first call of a parallel step."""
+ contents = _to_gemini_contents(
+ (
+ BrainMessage(role="user", content="read a and b"),
+ BrainMessage(
+ role="assistant",
+ content=[
+ {"type": "tool_use", "id": "c1", "name": "read_file",
+ "input": {"path": "a"}, "thought_signature": "U0lH"},
+ {"type": "tool_use", "id": "c2", "name": "read_file",
+ "input": {"path": "b"}},
+ ],
+ ),
+ BrainMessage(role="tool", content="A", tool_call_id="c1", name="read_file"),
+ BrainMessage(role="tool", content="B", tool_call_id="c2", name="read_file"),
+ ),
)
- assert any("tool_use" in str(p.get("text", "")) for p in parts)
+
+ calls = contents[1]["parts"]
+ assert [c["functionCall"]["args"] for c in calls] == [{"path": "a"}, {"path": "b"}]
+ assert calls[0]["thought_signature"] == "U0lH"
+ assert "thought_signature" not in calls[1] # only the step's first call is checked
+ assert len(contents) == 3
+ responses = [p["functionResponse"]["response"]["result"] for p in contents[2]["parts"]]
+ assert responses == ["A", "B"]
+
+
+def test_a_tool_result_without_a_name_takes_its_calls_name() -> None:
+ """OpenClaw sends tool results without a name; Gemini refuses an empty one."""
+ contents = _to_gemini_contents(
+ (
+ BrainMessage(
+ role="assistant",
+ content=[{"type": "tool_use", "id": "c1", "name": "read_file", "input": {}}],
+ ),
+ BrainMessage(role="tool", content="body", tool_call_id="c1"),
+ ),
+ )
+
+ assert contents[1]["parts"][0]["functionResponse"]["name"] == "read_file"
def test_plain_turns_keep_their_shape() -> None:
diff --git a/tests/unit/brain/test_model_catalog_local.py b/tests/unit/brain/test_model_catalog_local.py
index 4eccb18487..5ca9008a44 100644
--- a/tests/unit/brain/test_model_catalog_local.py
+++ b/tests/unit/brain/test_model_catalog_local.py
@@ -282,10 +282,11 @@ async def test_ollama_catalog_carries_declared_capabilities(tmp_path, monkeypatc
text-only install came to advertise vision to Screen Context.
"""
client = _FakeOllamaClient(
- {"models": [{"name": "qwen3.5:9b"}, {"name": "qwen3-vl:8b"}]},
+ {"models": [{"name": "qwen3.5:9b"}, {"name": "qwen3-vl:8b"}, {"name": "deepseek-r1:14b"}]},
{
"qwen3.5:9b": ["completion", "tools"],
"qwen3-vl:8b": ["completion", "tools", "vision"],
+ "deepseek-r1:14b": ["completion", "thinking"],
},
)
_local_env(monkeypatch)
@@ -295,7 +296,9 @@ async def test_ollama_catalog_carries_declared_capabilities(tmp_path, monkeypatc
caps = {m.id: (m.input_modalities, m.supported_parameters) for m in result.models}
assert caps["qwen3.5:9b"] == (("text",), ("tools",))
assert caps["qwen3-vl:8b"] == (("text", "image"), ("tools",))
- assert sorted(client.shown) == ["qwen3-vl:8b", "qwen3.5:9b"]
+ # Ollama's "thinking" is the catalogs' "reasoning" (runtimes read it).
+ assert caps["deepseek-r1:14b"] == (("text",), ("reasoning",))
+ assert sorted(client.shown) == ["deepseek-r1:14b", "qwen3-vl:8b", "qwen3.5:9b"]
async def test_ollama_catalog_drops_embedding_only_downloads(tmp_path, monkeypatch) -> None:
diff --git a/tests/unit/ci/test_agent_runtime_lane.py b/tests/unit/ci/test_agent_runtime_lane.py
new file mode 100644
index 0000000000..abebeea593
--- /dev/null
+++ b/tests/unit/ci/test_agent_runtime_lane.py
@@ -0,0 +1,217 @@
+"""The Hermes / OpenClaw CI lane: what turns it on, what it must prove, its pins."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import pytest
+import yaml
+
+from scripts.ci import agent_runtime_suite, classify_changes, required_results, select_tests
+
+ROOT = Path(__file__).resolve().parents[3]
+LANE_JOBS = {"agent-runtimes-unit", "agent-runtimes-headless", "agent-runtimes-e2e"}
+
+
+ "path",
+ [
+ "jarvis/agent_runtimes/gateway.py",
+ "jarvis\\agent_runtimes\\hermes.py",
+ "jarvis/agent_chat/runner_acp.py",
+ "jarvis/society/chat_binding.py",
+ "jarvis/ui/web/society_routes.py",
+ "tests/fakes/fake_acp_agent.py",
+ "scripts/spikes/agent_runtimes_gateway_e2e.py",
+ "requirements.txt",
+ ],
+)
+def test_runtime_paths_turn_the_lane_on(path):
+ assert classify_changes.classify([path])["agent_runtimes"] is True
+
+
+def test_an_unrelated_change_leaves_the_lane_off():
+ assert classify_changes.classify(["jarvis/appshot/region.py"])["agent_runtimes"] is False
+
+
+def test_a_pipeline_change_runs_the_lane_too():
+ assert classify_changes.classify(["scripts/ci/run_gates.py"])["agent_runtimes"] is True
+
+
+def _needs(lane: bool, **results: str) -> dict:
+ outputs = {flag: "false" for flag in required_results.LANE_JOBS}
+ outputs.update(full="false", macos="false", macos_desktop="false", release="false")
+ outputs["agent_runtimes"] = "true" if lane else "false"
+ needs = {"detect": {"result": "success", "outputs": outputs}}
+ # Every pipeline also requires the always-on jobs (gates, workflow audit).
+ always = required_results.expected_jobs(dict.fromkeys(outputs, "false")) - {"detect"}
+ needs.update({job: {"result": "success"} for job in always})
+ needs.update({job: {"result": result} for job, result in results.items()})
+ return needs
+
+
+def test_the_gate_requires_every_runtime_job_when_the_lane_is_on():
+ verdict = required_results.evaluate(
+ _needs(True, **dict.fromkeys(LANE_JOBS, "skipped")), pipeline=True
+ )
+ assert verdict["ok"] is False
+ assert LANE_JOBS <= set(verdict["failed"])
+ passing = required_results.evaluate(
+ _needs(True, **dict.fromkeys(LANE_JOBS, "success")), pipeline=True
+ )
+ assert passing["ok"] is True
+
+
+def test_the_gate_accepts_skipped_runtime_jobs_when_the_lane_is_off():
+ verdict = required_results.evaluate(
+ _needs(False, **dict.fromkeys(LANE_JOBS, "skipped")), pipeline=True
+ )
+ assert verdict["ok"] is True
+
+
+def test_a_runtime_change_selects_the_chat_and_society_chain():
+ tests = [
+ "tests/unit/agent_runtimes/test_acp_runner.py",
+ "tests/unit/agent_chat/test_send_queue.py",
+ "tests/unit/society/test_chat_binding.py",
+ *[f"tests/unit/other/test_{i}.py" for i in range(40)],
+ ]
+ mode, chosen = select_tests.select(
+ ["jarvis/agent_runtimes/manager.py"], tests, dict.fromkeys(tests, "")
+ )
+ assert mode == "selected"
+ assert set(tests[:3]) <= set(chosen)
+
+
+def test_the_suite_names_only_tests_that_exist():
+ for entry in (*agent_runtime_suite.SUITE, *agent_runtime_suite.HEADLESS):
+ assert (ROOT / entry).exists(), entry
+ for path in agent_runtime_suite.FILES:
+ assert (ROOT / path).exists(), path
+
+
+def test_ci_runs_the_lane_on_every_os_and_the_gate_waits_for_it():
+ jobs = yaml.safe_load((ROOT / ".github/workflows/ci.yml").read_text(encoding="utf-8"))["jobs"]
+ assert "agent_runtimes" in jobs["detect"]["outputs"]
+ assert LANE_JOBS <= set(jobs["gate"]["needs"])
+ oses = {"ubuntu-latest", "windows-latest", "macos-latest"}
+ assert set(jobs["agent-runtimes-unit"]["strategy"]["matrix"]["os"]) == oses
+ e2e = jobs["agent-runtimes-e2e"]["strategy"]["matrix"]
+ assert set(e2e["os"]) == oses
+ assert set(e2e["runtime"]) == {"hermes", "openclaw"}
+ assert jobs["agent-runtimes-headless"]["container"] == "python:3.11-slim"
+ for job in LANE_JOBS:
+ assert jobs[job]["if"] == "needs.detect.outputs.agent_runtimes == 'true'"
+
+
+# ------------------------------------------------------------------ pins
+
+
+def test_no_manifest_means_latest(tmp_path):
+ found = agent_runtime_suite.pin("openclaw", tmp_path / "absent.json")
+ assert found == {"version": "latest", "npm_spec": "openclaw@latest", "hermes_commit": ""}
+
+
+def test_a_pin_selects_the_npm_version_and_the_hermes_commit(tmp_path):
+ manifest = tmp_path / "runtime-versions.json"
+ commit = "a" * 40
+ manifest.write_text(
+ json.dumps({"hermes": {"tested": "0.21.5", "commit": commit}, "openclaw": "2026.9.8"}),
+ encoding="utf-8",
+ )
+ assert agent_runtime_suite.pin("hermes", manifest)["hermes_commit"] == commit
+ assert agent_runtime_suite.pin("openclaw", manifest)["npm_spec"] == "[email protected]"
+
+
+def test_a_pin_that_could_inject_a_command_is_ignored(tmp_path):
+ manifest = tmp_path / "runtime-versions.json"
+ manifest.write_text(
+ json.dumps({"hermes": {"tested": "1; rm -rf /", "commit": "main && curl x"}}),
+ encoding="utf-8",
+ )
+ found = agent_runtime_suite.pin("hermes", manifest)
+ assert found["version"] == "latest" and found["hermes_commit"] == ""
+
+
+def _report(folder: Path, name: str, runtime: str, version: str, commit: str = "") -> None:
+ (folder / name).mkdir(parents=True)
+ (folder / name / "canary-report.json").write_text(
+ json.dumps({"runtime": runtime, "version": version, "commit": commit}), encoding="utf-8"
+ )
+
+
+def test_the_canary_raises_a_pin_only_when_every_os_agrees(tmp_path):
+ manifest = tmp_path / "runtime-versions.json"
+ manifest.write_text(json.dumps({"openclaw": {"minimum": "2026.9.8"}}), encoding="utf-8")
+ reports = tmp_path / "reports"
+ for os_name in ("ubuntu", "windows", "macos"):
+ _report(reports, f"canary-report-openclaw-{os_name}", "openclaw", "2026.10.1")
+ _report(reports, "canary-report-hermes-ubuntu", "hermes", "0.22.0", "b" * 40)
+ _report(reports, "canary-report-hermes-windows", "hermes", "0.22.0", "b" * 40)
+ assert agent_runtime_suite.bump_from(reports, manifest) is True
+ data = json.loads(manifest.read_text(encoding="utf-8"))
+ assert data["openclaw"] == {"minimum": "2026.9.8", "tested": "2026.10.1"}
+ assert "hermes" not in data # macOS did not report: the pin is kept
+
+
+def test_disagreeing_oses_keep_the_pin(tmp_path):
+ manifest = tmp_path / "runtime-versions.json"
+ reports = tmp_path / "reports"
+ _report(reports, "a", "openclaw", "2026.10.1")
+ _report(reports, "b", "openclaw", "2026.10.1")
+ _report(reports, "c", "openclaw", "2026.10.2")
+ assert agent_runtime_suite.bump_from(reports, manifest) is False
+ assert not manifest.exists()
+
+
+def test_the_pins_file_of_the_runtimes_keeps_its_comment_and_extra_keys(tmp_path):
+ manifest = tmp_path / "runtime-versions.json"
+ manifest.write_text(
+ json.dumps({
+ "_comment": "Raised by the canary.",
+ "hermes": {"minimum": "0.20.6", "tested": "0.21.5", "commit": "c" * 40,
+ "config_version": 50},
+ }),
+ encoding="utf-8",
+ )
+ assert agent_runtime_suite.pin("hermes", manifest)["hermes_commit"] == "c" * 40
+ reports = tmp_path / "reports"
+ for os_name in ("ubuntu", "windows", "macos"):
+ _report(reports, os_name, "hermes", "0.22.0", "d" * 40)
+ assert agent_runtime_suite.bump_from(reports, manifest) is True
+ data = json.loads(manifest.read_text(encoding="utf-8"))
+ assert data["_comment"] == "Raised by the canary."
+ assert data["hermes"] == {
+ "minimum": "0.20.6", "tested": "0.22.0", "commit": "d" * 40, "config_version": 50,
+ }
+
+
+def test_the_e2e_check_runs_with_a_desktop_apps_path(monkeypatch):
+ from scripts.ci import agent_runtime_e2e
+
+ monkeypatch.setenv("PATH", "/home/dev/.local/bin")
+ entries = agent_runtime_e2e.desktop_path().split(os.pathsep)
+ assert "/home/dev/.local/bin" not in entries
+ assert str(Path(sys.executable).resolve().parent) == entries[-1]
+
+
+def test_the_e2e_check_reads_every_turn_budget_line():
+ from scripts.ci import agent_runtime_e2e
+
+ output = "prepare: exit 0 in 41.0 s\nturn 1 took 12.5 s\n...\nturn 1 took 31.0 s\n"
+ assert [float(v) for v in agent_runtime_e2e._TURN.findall(output)] == [12.5, 31.0]
+ assert agent_runtime_e2e.TURN_BUDGET_S == {"hermes": 30.0, "openclaw": 90.0}
+
+
+def test_the_runtime_pins_ship_in_the_wheel_and_the_frozen_app():
+ import tomllib
+
+ pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))
+ assert "agent_runtimes/runtime-versions.json" in (
+ pyproject["tool"]["setuptools"]["package-data"]["jarvis"]
+ )
+ spec = (ROOT / "jarvis.spec").read_text(encoding="utf-8")
+ assert '"jarvis/agent_runtimes/runtime-versions.json"), "jarvis/agent_runtimes")' in spec
diff --git a/tests/unit/ci/test_pipeline_scripts.py b/tests/unit/ci/test_pipeline_scripts.py
index f969396863..4a8befa7fc 100644
--- a/tests/unit/ci/test_pipeline_scripts.py
+++ b/tests/unit/ci/test_pipeline_scripts.py
@@ -8,6 +8,7 @@ import shlex
import shutil
import subprocess
import sys
+import threading
from pathlib import Path
import pytest
@@ -253,6 +254,58 @@ def test_runner_reports_failures_and_passes(tmp_path):
assert any(fid.endswith("::test_bad") for fid in report["failed_ids"])
+def test_memory_probe_reads_this_machine():
+ free = run_tests_parallel.available_memory()
+ assert free is None or free > 0
+
+
+def test_memory_gate_never_holds_back_the_only_batch():
+ gate = run_tests_parallel.MemoryGate(reserve=10, probe=lambda: 0, poll_seconds=0.01)
+ gate.acquire()
+ assert gate.running == 1
+ assert gate.waits == 0
+
+
+def test_memory_gate_holds_a_second_batch_until_memory_frees():
+ free = {"bytes": 0}
+ gate = run_tests_parallel.MemoryGate(reserve=10, probe=lambda: free["bytes"], poll_seconds=0.01)
+ gate.acquire()
+ entered = threading.Event()
+
+ def second() -> None:
+ gate.acquire()
+ entered.set()
+
+ worker = threading.Thread(target=second, daemon=True)
+ worker.start()
+ assert not entered.wait(0.2)
+ assert gate.waits == 1
+ free["bytes"] = 100
+ assert entered.wait(2)
+ worker.join(2)
+ assert gate.running == 2
+
+
+def test_memory_gate_lets_a_waiting_batch_in_when_the_others_finish():
+ gate = run_tests_parallel.MemoryGate(reserve=10, probe=lambda: 0, poll_seconds=0.01)
+ gate.acquire()
+ entered = threading.Event()
+ worker = threading.Thread(target=lambda: (gate.acquire(), entered.set()), daemon=True)
+ worker.start()
+ assert not entered.wait(0.2)
+ gate.release()
+ assert entered.wait(2)
+ worker.join(2)
+
+
+def test_memory_gate_is_open_where_memory_cannot_be_read():
+ gate = run_tests_parallel.MemoryGate(reserve=10, probe=lambda: None)
+ gate.acquire()
+ gate.acquire()
+ assert gate.running == 2
+ assert gate.waits == 0
+
+
# --------------------------------------------------------------------------- ratchet
diff --git a/tests/unit/costs/test_cost_read_model.py b/tests/unit/costs/test_cost_read_model.py
index e42dc65f80..56cc375bd9 100644
--- a/tests/unit/costs/test_cost_read_model.py
+++ b/tests/unit/costs/test_cost_read_model.py
@@ -728,3 +728,52 @@ def test_a_session_counts_the_same_whatever_grain_the_report_draws_at(
assert len(hourly) == 3
assert len(daily) == len(hourly)
assert sum(e.tokens_total for e in daily) == sum(e.tokens_total for e in hourly)
+
+
+# ---------------------------------------------------------------------------
+# Hermes / OpenClaw: the model gateway's ledger rows are the bill
+# ---------------------------------------------------------------------------
+
+
+def _runtime_turn(turn_id: str, ts_ms: int, seq: int) -> list[tuple]:
+ return [
+ ("chat-3", seq, ts_ms, "turn_started", json.dumps(
+ {"turn_id": turn_id, "runner": "hermes-cli", "provider": "openai",
+ "model": "gpt-5.5"})),
+ ("chat-3", seq + 1, ts_ms + 500, "turn_finished", json.dumps(
+ {"turn_id": turn_id, "status": "done",
+ "usage": {"input_tokens": 5_000, "output_tokens": 100}})),
+ ]
+
+
+def test_gateway_metered_runtime_turns_are_billed_once(tmp_path: Path) -> None:
+ from jarvis.costs import ledger
+
+ chat = tmp_path / "agent_chat.db"
+ conn = sqlite3.connect(chat)
+ conn.executescript(_AGENT_CHAT_DDL)
+ conn.executemany(
+ "INSERT INTO agent_chat_events (session_id, seq, ts_ms, kind, payload) VALUES (?,?,?,?,?)",
+ # One turn before the gateway metered anything, one after.
+ _runtime_turn("t-old", T0, 1) + _runtime_turn("t-new", T0 + 60_000, 3),
+ )
+ conn.commit()
+ conn.close()
+ usage = tmp_path / "llm_usage.db"
+ ledger.set_ledger_path(usage)
+ try:
+ for offset in (60_100, 60_200):
+ ledger.record_usage(provider="openai", model="gpt-5.5", tokens_in=2_000,
+ tokens_out=50, caller="agent-runtime", ts_ms=T0 + offset)
+ ledger.flush()
+ finally:
+ ledger.set_ledger_path(None)
+
+ entries = collect_entries(CostSources(agent_chat_db=chat, ledger_db=usage))
+ agent = [e for e in entries if e.surface == "agent-chat"]
+ # The old turn from its own report, the new one only as two gateway calls.
+ assert sorted((e.ts_ms, e.tokens_in) for e in agent) == [
+ (T0 + 500, 5_000), (T0 + 60_100, 2_000), (T0 + 60_200, 2_000)
+ ]
+ assert all(e.role == "agent" for e in agent)
+
diff --git a/tests/unit/live/test_subscription_reasoning.py b/tests/unit/live/test_subscription_reasoning.py
index f764c00855..d404d5b6d5 100644
--- a/tests/unit/live/test_subscription_reasoning.py
+++ b/tests/unit/live/test_subscription_reasoning.py
@@ -123,11 +123,28 @@ async def test_usage_limit_midstream_is_safe_and_terminal():
with pytest.raises(SubscriptionReasoningError, match="usage limit") as caught:
await _collect(reasoning)
assert caught.value.code == "usage_limit_reached"
+ assert caught.value.status == 429
assert "sensitive-provider-body" not in str(caught.value)
assert credentials.calls == [False]
await reasoning.aclose()
+async def test_http_rate_limit_keeps_retry_after_without_retrying_or_refreshing():
+ requests = []
+
+ def limited(request):
+ requests.append(request)
+ return httpx.Response(429, headers={"Retry-After": "3600"}, text="sensitive-body")
+
+ reasoning, credentials = _reasoning(limited)
+ with pytest.raises(SubscriptionReasoningError) as caught:
+ await _collect(reasoning)
+ assert caught.value.status == 429 and caught.value.retry_after == "3600"
+ assert "sensitive-body" not in str(caught.value)
+ assert credentials.calls == [False] and len(requests) == 1
+ await reasoning.aclose()
+
+
@pytest.mark.asyncio
async def test_hosted_tool_is_rejected_before_auth_or_network():
def forbidden(_request):
@@ -201,6 +218,8 @@ async def test_catalog_efforts_and_default_are_preserved_without_provider_metada
{"effort": "bad\nvalue"},
],
"default_reasoning_level": "low",
+ "context_window": 400000,
+ "max_output_tokens": 64000,
}
]
},
@@ -212,6 +231,8 @@ async def test_catalog_efforts_and_default_are_preserved_without_provider_metada
"label": "Selected",
"efforts": ["low", "max", "ultra"],
"default_effort": "low",
+ "context_length": 400000,
+ "max_output_tokens": 64000,
}
]
await reasoning.aclose()
diff --git a/tests/unit/society/test_review_responsiveness.py b/tests/unit/society/test_review_responsiveness.py
index 9a39b6ab2c..913ba16f74 100644
--- a/tests/unit/society/test_review_responsiveness.py
+++ b/tests/unit/society/test_review_responsiveness.py
@@ -38,7 +38,9 @@ async def test_review_seat_construction_keeps_loop_responsive(monkeypatch, no_ag
registry = RecordingRegistry(["openai"], on_instantiate=slow_build)
monkeypatch.setattr(resolver, "_get_registry", lambda: registry)
runtime = SimpleNamespace(config=lambda: None, skills_for=lambda agent_id: None)
- agent = SimpleNamespace(provider="openai", model="test-model", effort="low", agent_id="test")
+ agent = SimpleNamespace(
+ provider="openai", model="test-model", effort="low", agent_id="test", account_id=""
+ )
task = asyncio.create_task(_ask(runtime, agent, "Evidence"))
try:
await asyncio.wait_for(entered.wait(), timeout=2)
@@ -59,6 +61,8 @@ async def test_unavailable_review_seat_finishes_without_stop_iteration(monkeypat
monkeypatch.setattr(resolver, "_get_registry", lambda: registry)
runtime = SimpleNamespace(config=lambda: None, skills_for=lambda agent_id: None)
# A coding CLI with no background brain in this app: nothing can answer.
- agent = SimpleNamespace(provider="cursor", model="", effort="low", agent_id="test")
+ agent = SimpleNamespace(
+ provider="cursor", model="", effort="low", agent_id="test", account_id=""
+ )
assert await asyncio.wait_for(_ask(runtime, agent, "Evidence"), timeout=2) is None
assert registry.built == []
diff --git a/tests/unit/society/test_roster.py b/tests/unit/society/test_roster.py
index 2eeb3d8838..07a6a59793 100644
--- a/tests/unit/society/test_roster.py
+++ b/tests/unit/society/test_roster.py
@@ -39,8 +39,9 @@ def test_canonical_session_is_a_pure_function():
assert canonical_session_id("scout") == "society:scout"
-async def test_create_then_adopt_by_name(roster: Roster):
- scout, created = await roster.create(name="Scout", title="Research scout")
[email protected]("runtime", ["jarvis", "hermes", "openclaw"])
+async def test_create_then_adopt_by_name(roster: Roster, runtime):
+ scout, created = await roster.create(name="Scout", title="Research scout", runtime=runtime)
assert created is True
assert scout.agent_id == "scout"
assert scout.tier is Tier.SPECIALIST
diff --git a/tests/unit/society/test_runtime_grant_revocation.py b/tests/unit/society/test_runtime_grant_revocation.py
new file mode 100644
index 0000000000..a80fcd9b3c
--- /dev/null
+++ b/tests/unit/society/test_runtime_grant_revocation.py
@@ -0,0 +1,74 @@
+"""A runtime agent's gateway grants end with the seat they were made for."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from jarvis.agent_runtimes import gateway
+from jarvis.society.roster import Roster
+from jarvis.society.store import SocietyStore
+
+
+class FakeGateway:
+ """Records revocations; ``fail`` makes the next call raise."""
+
+ def __init__(self) -> None:
+ self.revoked: list[str] = []
+ self.fail = False
+
+ def revoke_agent(self, agent_id: str) -> int:
+ if self.fail:
+ self.fail = False
+ raise RuntimeError("gateway gone")
+ self.revoked.append(agent_id)
+ return 1
+
+
+async def roster(tmp_path: Path):
+ store = SocietyStore(tmp_path / "society.db")
+ await store.open()
+ try:
+ yield Roster(store)
+ finally:
+ await store.close()
+
+
+def fake(monkeypatch) -> FakeGateway:
+ fake = FakeGateway()
+ monkeypatch.setattr(gateway, "revoke_agent", fake.revoke_agent, raising=False)
+ return fake
+
+
+async def test_a_new_provider_model_or_account_revokes_the_old_grants(roster, fake):
+ await roster.create(name="Hermit", runtime="hermes", provider="openai", model="gpt-5.5")
+ await roster.update("hermit", {"model": "gpt-5.2"})
+ await roster.update("hermit", {"provider": "ollama", "model": "qwen3:8b"})
+ await roster.update("hermit", {"account_id": "api-key"})
+ assert fake.revoked == ["hermit", "hermit", "hermit"]
+
+
+async def test_archiving_a_runtime_agent_revokes_its_grants(roster, fake):
+ await roster.create(name="Claw", runtime="openclaw", provider="openai", model="gpt-5.5")
+ await roster.archive("claw")
+ assert fake.revoked == ["claw"]
+
+
+async def test_other_edits_and_jarvis_agents_keep_their_grants(roster, fake):
+ await roster.create(name="Hermit", runtime="hermes", provider="openai", model="gpt-5.5")
+ await roster.update("hermit", {"title": "Scout", "model": "gpt-5.5"})
+ await roster.create(name="Plain", provider="openai", model="gpt-5.5")
+ await roster.update("plain", {"model": "gpt-5.2"})
+ await roster.archive("plain")
+ assert fake.revoked == []
+
+
+async def test_a_failed_revocation_never_undoes_the_roster_change(roster, fake):
+ await roster.create(name="Hermit", runtime="hermes", provider="openai", model="gpt-5.5")
+ fake.fail = True
+ updated = await roster.update("hermit", {"model": "gpt-5.2"})
+ assert updated.model == "gpt-5.2"
+ assert fake.revoked == []
diff --git a/tests/unit/society/test_seat_brain_runtime.py b/tests/unit/society/test_seat_brain_runtime.py
new file mode 100644
index 0000000000..8f0500a708
--- /dev/null
+++ b/tests/unit/society/test_seat_brain_runtime.py
@@ -0,0 +1,68 @@
+"""A Hermes / OpenClaw agent's memory reviews run on the auth its chat uses."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from jarvis.agent_chat import service
+from jarvis.agent_runtimes import model_map
+from jarvis.society import seat_brain
+
+
+def _agent(runtime: str = "hermes", account_id: str = "") -> SimpleNamespace:
+ return SimpleNamespace(
+ provider="claude-api",
+ model="claude-opus-5",
+ effort="",
+ account_id=account_id,
+ runtime=runtime,
+ )
+
+
+def claude_code_installed(monkeypatch):
+ monkeypatch.setattr(service, "_claude_cli_installed", lambda: True)
+
+
+def _login(monkeypatch, *, live: bool) -> list[tuple[str, str]]:
+ asked: list[tuple[str, str]] = []
+
+ def login_token_for(provider: str, account_id: str = "") -> str | None:
+ asked.append((provider, account_id))
+ return "sk-ant-oat-test" if live else None
+
+ monkeypatch.setattr(model_map, "login_token_for", login_token_for)
+ return asked
+
+
+def test_an_agent_whose_chat_bills_the_key_reviews_on_the_key(monkeypatch, claude_code_installed):
+ _login(monkeypatch, live=False)
+ seat = seat_brain.agent_seat(None, _agent())
+ # Before: Claude Code answered (the plan) while the chat billed the API key.
+ assert seat.keyed
+ assert seat.provider == "claude-api" and seat.model == "claude-opus-5"
+
+
+def test_an_agent_on_the_claude_login_reviews_through_claude_code(
+ monkeypatch, claude_code_installed
+):
+ asked = _login(monkeypatch, live=True)
+ seat = seat_brain.agent_seat(None, _agent(account_id="subscription"))
+ assert seat.runner == "claude-cli"
+ assert asked == [("claude-api", "subscription")]
+
+
+def test_a_login_seat_without_claude_code_is_unavailable_never_a_key(monkeypatch):
+ _login(monkeypatch, live=True)
+ monkeypatch.setattr(service, "_claude_cli_installed", lambda: False)
+ with pytest.raises(seat_brain.SeatUnavailable):
+ seat_brain.agent_seat(None, _agent())
+
+
+def test_a_jarvis_agent_keeps_its_runner(monkeypatch, claude_code_installed):
+ asked = _login(monkeypatch, live=False)
+ seat = seat_brain.agent_seat(None, _agent(runtime="jarvis"))
+ assert seat.runner == "claude-cli"
+ assert asked == []
diff --git a/tests/unit/society/test_seat_memory.py b/tests/unit/society/test_seat_memory.py
index 55a4ed92f6..c091f8836d 100644
--- a/tests/unit/society/test_seat_memory.py
+++ b/tests/unit/society/test_seat_memory.py
@@ -48,7 +48,9 @@ def agent_keys(monkeypatch):
def _agent(provider: str, model: str = "", agent_id: str = "scout") -> SimpleNamespace:
- return SimpleNamespace(provider=provider, model=model, effort="", agent_id=agent_id)
+ return SimpleNamespace(
+ provider=provider, model=model, effort="", agent_id=agent_id, account_id=""
+ )
def _runtime(cfg=None) -> SimpleNamespace:
diff --git a/tests/unit/ui/web/test_society_routes.py b/tests/unit/ui/web/test_society_routes.py
index d22cadbf7c..2924f5dba2 100644
--- a/tests/unit/ui/web/test_society_routes.py
+++ b/tests/unit/ui/web/test_society_routes.py
@@ -549,3 +549,16 @@ def test_pausing_moves_the_figure_home(memory_client):
assert c.get("/api/society/agents/scout").json()["agent"]["checkpoint"] == "gate"
res = c.patch("/api/society/agents/scout", json={"state": "paused"})
assert res.json()["agent"]["checkpoint"] == "idle"
+
+
+def test_a_runtime_agent_on_an_unsupported_provider_names_a_translatable_reason(client):
+ c, _ = client
+ res = c.post(
+ "/api/society/agents",
+ json={"name": "Rune", "runtime": "hermes", "provider": "no-such-vendor", "model": "x"},
+ )
+ assert res.status_code == 422
+ detail = res.json()["detail"]
+ # The UI shows its own sentence for the reason; the detail names every way that works.
+ assert detail["reason"] == "runtime_provider_unsupported"
+ assert "ChatGPT subscription" in detail["detail"]