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.

feat(society): let one agent pin Claude to its API key or its subscription

rubenluetke10-beepe4535638bdc7
diff --git a/jarvis/agent_chat/catalog.py b/jarvis/agent_chat/catalog.py
index b02194bbcc..1d4ca1e8ed 100644
--- a/jarvis/agent_chat/catalog.py
+++ b/jarvis/agent_chat/catalog.py
@@ -445,6 +445,19 @@ def offers(surface: str, provider_id: str) -> bool:
return any(row.id == pid for row in rows_for(surface))
+#: Reserved ``account_id`` values on a dual row (``claude-api``: one id for a
+#: subscription login AND an API key). They pin one agent's seat to one way of
+#: paying, chosen in the "New agent" dialog; ``""`` keeps the automatic choice
+#: (the API Keys page's setting, then whichever credential is there).
+#: ``API_KEY_ACCOUNT`` runs on the provider's saved API key.
+API_KEY_ACCOUNT: Final[str] = "api-key"
+#: ``SUBSCRIPTION_ACCOUNT`` runs on the subscription login even when an API key
+#: is saved too (Hermes / OpenClaw: Claude Code's login, billed as extra usage).
+SUBSCRIPTION_ACCOUNT: Final[str] = "subscription"
+#: Both reserved values: never the id of a real login.
+ACCESS_ACCOUNTS: Final[frozenset[str]] = frozenset({API_KEY_ACCOUNT, SUBSCRIPTION_ACCOUNT})
+
+
#: A CLI-only row and the API row of the same brand. A chat that was seated
#: on a vendor CLI before the front page dropped its CLI seats moves across
#: this map instead of being stranded on a provider its picker no longer
diff --git a/jarvis/agent_chat/runner_cli.py b/jarvis/agent_chat/runner_cli.py
index f04850851c..c911d250f3 100644
--- a/jarvis/agent_chat/runner_cli.py
+++ b/jarvis/agent_chat/runner_cli.py
@@ -343,6 +343,14 @@ def _remember_models(runner: str, rows: list[dict[str, Any]] | None) -> None:
prepared[runner] = rows
+def _login_id(account_id: str) -> str:
+ """The login an account id names; ``""`` (the active one) for a reserved
+ access value (``catalog.ACCESS_ACCOUNTS``), which names no login."""
+ from jarvis.agent_chat.catalog import ACCESS_ACCOUNTS
+
+ return "" if account_id in ACCESS_ACCOUNTS else account_id
+
+
def _account_env(platform: str) -> dict[str, str]:
"""The child environment for the subscription seat of ``platform`` — the
turn's pinned account when its session names one, else the active one."""
@@ -353,7 +361,7 @@ def _account_env(platform: str) -> dict[str, str]:
try:
from jarvis import agent_accounts
- requested = ACCOUNT_OVERRIDE.get()
+ requested = _login_id(ACCOUNT_OVERRIDE.get())
pinned = agent_accounts.resolve(requested or None)
if requested and pinned is None:
raise CliUnavailable(
@@ -368,7 +376,7 @@ def _account_env(platform: str) -> dict[str, str]:
except CliUnavailable:
raise
except Exception as exc: # noqa: BLE001 — unsupported platforms use native credentials
- if ACCOUNT_OVERRIDE.get() and pinned_platform in (None, platform):
+ if _login_id(ACCOUNT_OVERRIDE.get()) and pinned_platform in (None, platform):
raise CliUnavailable("The selected subscription account could not be loaded.") from exc
log.debug("CLI account layer unavailable for %s (%s)", platform, type(exc).__name__)
env = dict(os.environ)
diff --git a/jarvis/agent_chat/service.py b/jarvis/agent_chat/service.py
index e74c35a5c4..cb5955bebd 100644
--- a/jarvis/agent_chat/service.py
+++ b/jarvis/agent_chat/service.py
@@ -139,7 +139,9 @@ EXTERNAL_RUNTIME_RUNNERS: Final[dict[str, str]] = {
}
-def resolve_runner(provider: str, *, surface: str = "agent", runtime: str = "") -> str:
+def resolve_runner(
+ provider: str, *, surface: str = "agent", runtime: str = "", account_id: str = ""
+) -> str:
"""Which runner answers for ``provider`` on this machine, right now.
``claude-api`` is dual: Claude Code (the CLI) when it is installed — that
@@ -152,6 +154,10 @@ def resolve_runner(provider: str, *, surface: str = "agent", runtime: str = "")
(``SurfaceKit.cli_seats``, maintainer 2026-08-26), so a vendor CLI never
answers there — not even the dual Claude row, which runs on the Anthropic
API behind its key like every other seat.
+
+ ``account_id`` is the seat's login, or a reserved access value
+ (``catalog.ACCESS_ACCOUNTS``) that pins the dual Claude row to its API key
+ or to its subscription for one agent, over the API Keys page's setting.
"""
if runtime in EXTERNAL_RUNTIME_RUNNERS and surface == "society":
# A Hermes / OpenClaw agent: that runtime's loop answers every turn and
@@ -171,8 +177,11 @@ def resolve_runner(provider: str, *, surface: str = "agent", runtime: str = "")
# The API Keys page can set the agents' Claude to its key instead of
# the subscription; that choice narrows the agents' surface only.
from jarvis.agent_chat.agent_provider_prefs import forces_api
+ from jarvis.agent_chat.catalog import API_KEY_ACCOUNT, SUBSCRIPTION_ACCOUNT
- if forces_api(row.id, surface):
+ if account_id == API_KEY_ACCOUNT:
+ return api_runner
+ if account_id != SUBSCRIPTION_ACCOUNT and forces_api(row.id, surface):
return api_runner
return "claude-cli" if _claude_cli_installed() else api_runner
if row.runner == "api":
@@ -186,6 +195,7 @@ def session_runner(session: Any) -> str:
session.provider,
surface=session.surface,
runtime=str(getattr(session, "runtime", "") or ""),
+ account_id=str(getattr(session, "account_id", "") or ""),
)
@@ -689,7 +699,8 @@ class AgentChatService:
f"Provider {provider!r} is not offered on the {surface!r} chat. "
"That chat runs on a provider API behind a key, not on a vendor CLI."
)
- ladder = ladder_key(surface, resolve_runner(provider, surface=surface))
+ runner = resolve_runner(provider, surface=surface, account_id=account_id)
+ ladder = ladder_key(surface, runner)
permission_mode = normalize_permission(ladder, permission_mode)
eff = normalize_effort(provider, effort) if effort is not None else ""
if effort is None:
diff --git a/jarvis/agent_runtimes/gateway.py b/jarvis/agent_runtimes/gateway.py
index a3cbca604d..8da2740009 100644
--- a/jarvis/agent_runtimes/gateway.py
+++ b/jarvis/agent_runtimes/gateway.py
@@ -446,7 +446,7 @@ async def _deltas(grant: Grant, model: str, request: Any) -> AsyncIterator[Any]:
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)
+ 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.
diff --git a/jarvis/agent_runtimes/model_map.py b/jarvis/agent_runtimes/model_map.py
index e0f312fddf..37b60109b0 100644
--- a/jarvis/agent_runtimes/model_map.py
+++ b/jarvis/agent_runtimes/model_map.py
@@ -115,18 +115,26 @@ def _api_key(provider: str, credential: str | None) -> str | None:
return key
-def login_token_for(provider: str) -> str | None:
- """The Claude login ``provider`` answers on, or ``None`` when it has an
- API key (or cannot use a login at all). Blocking (keyring)."""
- endpoint = _ENDPOINTS.get(provider)
- if endpoint is None or not endpoint.claude_login:
- return None
+def _saved_key(provider: str, endpoint: _Endpoint) -> str | None:
from jarvis.core.config import resolve_provider_endpoint
resolved = resolve_provider_endpoint(
provider, vendor_default_base_url=endpoint.default_base_url
)
- if _api_key(provider, resolved.credential) is not 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)."""
+ 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
+ if account_id != SUBSCRIPTION_ACCOUNT and _saved_key(provider, endpoint) is not None:
return None
return claude_login_token()
@@ -137,6 +145,24 @@ def login_providers() -> list[str]:
return [name for name in _ENDPOINTS if login_token_for(name)]
+def access_choices() -> dict[str, list[str]]:
+ """Per provider that can pay two ways (Claude: API key or Claude Code
+ login), the ways that work right now: ``"api"`` and/or ``"subscription"``.
+ The "New agent" dialog offers exactly these. Blocking (keyring)."""
+ choices: dict[str, list[str]] = {}
+ for name, endpoint in _ENDPOINTS.items():
+ if not endpoint.claude_login:
+ continue
+ found: list[str] = []
+ if _saved_key(name, endpoint) is not None:
+ found.append("api")
+ if claude_login_token() is not None:
+ found.append("subscription")
+ if found:
+ choices[name] = found
+ return choices
+
+
def supports(provider: str) -> bool:
return provider in _ENDPOINTS
@@ -222,6 +248,19 @@ def _checked_model(config: Any, provider: str, model: str, *, account_id: str =
)
# The Agents-tier key wins over the shared one, exactly as the gateway uses it.
key = _api_key(provider, resolved.credential)
+ if endpoint.claude_login:
+ from jarvis.agent_chat.catalog import API_KEY_ACCOUNT, SUBSCRIPTION_ACCOUNT
+
+ if account_id == API_KEY_ACCOUNT and key is None:
+ raise RouteUnavailable(
+ "This agent runs on an Anthropic API key, and none is saved. Connect "
+ "one in Settings → API keys, or switch the agent to the subscription."
+ )
+ if account_id == SUBSCRIPTION_ACCOUNT and not claude_login_token():
+ raise RouteUnavailable(
+ "This agent runs on the Claude Code login, and it is not live. Open "
+ "Claude Code once to renew it, or switch the agent to an API key."
+ )
if key is None and endpoint.claude_login and not claude_login_token():
raise RouteUnavailable(
"Claude needs an Anthropic API key or a live Claude Code login. Connect "
diff --git a/jarvis/society/chat_binding.py b/jarvis/society/chat_binding.py
index 134a330fba..55093ba5d9 100644
--- a/jarvis/society/chat_binding.py
+++ b/jarvis/society/chat_binding.py
@@ -110,11 +110,11 @@ def ensure_session(
society_mode_supported,
stance_of,
)
- from jarvis.agent_chat.service import resolve_runner
+ from jarvis.agent_chat.service import resolve_runner, session_runner
provider, model, effort = pair_for(cfg, agent)
runtime = _session_runtime(agent)
- runner = resolve_runner(provider, surface=SURFACE, runtime=runtime)
+ runner = resolve_runner(provider, surface=SURFACE, runtime=runtime, account_id=agent.account_id)
legacy_mode = ""
if agent.approval_mode is None:
legacy_mode = normalize_permission(
@@ -196,6 +196,11 @@ def ensure_session(
updates: dict[str, str] = {}
if getattr(existing, "account_id", "") != agent.account_id:
updates["account_id"] = agent.account_id
+ if session_runner(existing) != runner:
+ # Another way of paying moved the chat to another runner (Claude:
+ # subscription CLI <-> API key), which cannot resume the old one's
+ # vendor conversation; the next turn opens a fresh one.
+ updates["vendor_session"] = ""
if effort and existing.effort != effort:
updates["effort"] = effort
if existing.permission_mode != mode:
diff --git a/jarvis/society/checkpoints.py b/jarvis/society/checkpoints.py
index 686d1168c6..6e7d70896f 100644
--- a/jarvis/society/checkpoints.py
+++ b/jarvis/society/checkpoints.py
@@ -527,7 +527,10 @@ class CheckpointEngine:
from jarvis.agent_chat.service import resolve_runner
runtime = str(getattr(agent, "runtime", "") or "")
- return resolve_runner(provider, surface="society", runtime=runtime).endswith("-cli")
+ account = str(getattr(agent, "account_id", "") or "")
+ return resolve_runner(
+ provider, surface="society", runtime=runtime, account_id=account
+ ).endswith("-cli")
except Exception: # noqa: BLE001 — a missing catalog row is not a seat
log.debug("society checkpoints: runner lookup failed for %s", provider, exc_info=True)
return False
diff --git a/jarvis/society/seat_brain.py b/jarvis/society/seat_brain.py
index 7c0904df61..01d88e6f7b 100644
--- a/jarvis/society/seat_brain.py
+++ b/jarvis/society/seat_brain.py
@@ -110,7 +110,10 @@ def agent_seat(config: Any, agent: Any) -> Seat:
raise SeatUnavailable(str(exc) or "no provider can run this agent's chat") from None
if not provider:
raise SeatUnavailable("this agent's chat names no provider")
- return Seat(provider, model or "", resolve_runner(provider, surface="society"))
+ account = agent.account_id if provider == agent.provider else ""
+ return Seat(
+ provider, model or "", resolve_runner(provider, surface="society", account_id=account)
+ )
def jarvis_seat(config: Any) -> Seat:
diff --git a/jarvis/ui/web/agent_runtime_routes.py b/jarvis/ui/web/agent_runtime_routes.py
index dd77405e1f..170e67203e 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_choices,
login_providers,
subscription_providers,
supported_providers,
@@ -24,9 +25,9 @@ from jarvis.agent_runtimes.model_map import (
router = APIRouter(prefix="/api/agent-runtimes", tags=["agent-runtimes"])
-#: ``[checked_at, providers, login_providers]``: 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]``: 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
@@ -36,7 +37,9 @@ async def list_agent_runtimes(request: Request, refresh: bool = False) -> dict[s
plus the Jarvis providers an agent on such a runtime can use right now
(``supported_providers``: saved key or local server; ``all_providers``:
every provider the runtimes can drive once connected; ``login_providers``:
- usable ones that answer on a Claude login, billed as extra usage)."""
+ 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"``)."""
now = time.monotonic()
if refresh or now - _USABLE_CACHE[0] > _USABLE_TTL_S:
config = getattr(request.app.state, "config", None)
@@ -45,13 +48,19 @@ async def list_agent_runtimes(request: Request, refresh: bool = False) -> dict[s
config = await asyncio.to_thread(load_config)
usable = await asyncio.to_thread(usable_providers, config)
- _USABLE_CACHE[:] = [now, usable, await asyncio.to_thread(login_providers)]
+ _USABLE_CACHE[:] = [
+ now,
+ usable,
+ await asyncio.to_thread(login_providers),
+ await asyncio.to_thread(access_choices),
+ ]
return {
"runtimes": await manager.statuses(refresh=refresh),
"supported_providers": list(_USABLE_CACHE[1]),
"all_providers": sorted(supported_providers()),
"subscription_providers": sorted(subscription_providers()),
"login_providers": list(_USABLE_CACHE[2]),
+ "access": dict(_USABLE_CACHE[3]),
}
diff --git a/jarvis/ui/web/society_routes.py b/jarvis/ui/web/society_routes.py
index a4d28c858b..2aabf05982 100644
--- a/jarvis/ui/web/society_routes.py
+++ b/jarvis/ui/web/society_routes.py
@@ -79,6 +79,7 @@ def _validated_chat_runner(
*,
approval_mode: str | None = None,
permission_ceiling: str | None = None,
+ account_id: str | None = None,
) -> str:
"""Reject a runner change that cannot honor the effective chat approval."""
from jarvis.agent_chat.permissions import normalize_permission, society_mode_supported
@@ -94,7 +95,12 @@ def _validated_chat_runner(
"Hermes and OpenClaw run on an API key or a local model. "
"Pick one of those for this agent.",
)
- runner = resolve_runner(provider, surface="society", runtime=chosen_runtime)
+ runner = resolve_runner(
+ provider,
+ surface="society",
+ runtime=chosen_runtime,
+ account_id=agent.account_id if account_id is None else account_id,
+ )
mode = approval_mode if approval_mode is not None else (
str(agent.approval_mode) if agent.approval_mode is not None else ""
)
@@ -347,7 +353,10 @@ async def create_agent(body: CreateAgentBody, request: Request) -> dict[str, Any
from jarvis.agent_chat.service import resolve_runner
runner = resolve_runner(
- provider, surface="society", runtime=str(fields.get("runtime") or "")
+ provider,
+ surface="society",
+ runtime=str(fields.get("runtime") or ""),
+ account_id=str(fields.get("account_id") or ""),
)
if not society_mode_supported(runner, requested_mode):
raise HTTPException(
@@ -426,6 +435,7 @@ async def patch_agent(agent_id: str, body: PatchAgentBody, request: Request) ->
body.provider or agent.provider,
approval_mode=body.approval_mode,
permission_ceiling=fields.get("permission_ceiling"),
+ account_id=body.account_id,
)
if ("title" in fields or "description" in fields) and "focus" not in fields:
# A prose edit must not wipe what the agent earned in its chat: the
@@ -948,7 +958,9 @@ async def switch_agent_model(agent_id: str, body: ModelBody, request: Request) -
422,
{"reason": str(FailureReason.BLOCKED_BY_POLICY), "detail": "provider not offered"},
)
- target_runner = _validated_chat_runner(rt, agent, body.provider)
+ target_runner = _validated_chat_runner(
+ rt, agent, body.provider, account_id=body.account_id.strip()
+ )
chat = rt._get_chat()
fields = {
"provider": body.provider.strip().lower(),
diff --git a/tests/unit/agent_chat/test_agent_chat_core.py b/tests/unit/agent_chat/test_agent_chat_core.py
index a0233d90a0..07cec4f879 100644
--- a/tests/unit/agent_chat/test_agent_chat_core.py
+++ b/tests/unit/agent_chat/test_agent_chat_core.py
@@ -582,6 +582,40 @@ def test_resolve_runner_per_surface(monkeypatch):
assert svc_mod.resolve_runner("no-such-provider", surface="jarvis") == "unknown"
+def test_an_agent_can_pin_claude_to_its_api_key_or_its_subscription(monkeypatch):
+ """The "New agent" dialog's access choice beats the API Keys page's setting."""
+ from jarvis.agent_chat import agent_provider_prefs
+ from jarvis.agent_chat import service as svc_mod
+ from jarvis.agent_chat.catalog import API_KEY_ACCOUNT, SUBSCRIPTION_ACCOUNT
+
+ monkeypatch.setattr(svc_mod, "_claude_cli_installed", lambda: True)
+ monkeypatch.setattr(agent_provider_prefs, "forces_api", lambda *_: False)
+ api_runner = svc_mod.resolve_runner("openai", surface="society")
+ assert svc_mod.resolve_runner("claude-api", surface="society") == "claude-cli"
+ assert (
+ svc_mod.resolve_runner("claude-api", surface="society", account_id=API_KEY_ACCOUNT)
+ == api_runner
+ )
+ monkeypatch.setattr(agent_provider_prefs, "forces_api", lambda *_: True)
+ assert svc_mod.resolve_runner("claude-api", surface="society") == api_runner
+ assert (
+ svc_mod.resolve_runner("claude-api", surface="society", account_id=SUBSCRIPTION_ACCOUNT)
+ == "claude-cli"
+ )
+ # A real login id keeps the page's setting, exactly as before.
+ assert svc_mod.resolve_runner("claude-api", surface="society", account_id="acct") == api_runner
+ # Only the dual row reads the pin.
+ assert svc_mod.resolve_runner("openai-codex", account_id=API_KEY_ACCOUNT) == "codex-cli"
+
+
+def test_a_reserved_access_value_never_names_a_login():
+ from jarvis.agent_chat.catalog import API_KEY_ACCOUNT, SUBSCRIPTION_ACCOUNT
+ from jarvis.agent_chat.runner_cli import _login_id
+
+ assert _login_id(API_KEY_ACCOUNT) == "" and _login_id(SUBSCRIPTION_ACCOUNT) == ""
+ assert _login_id("acct-1") == "acct-1" and _login_id("") == ""
+
+
def test_the_jarvis_surface_offers_api_and_cli_seats():
"""Jarvis shares the IDE's provider seats; API-only surfaces remain filtered."""
from jarvis.agent_chat.catalog import PROVIDER_ROWS, offers, rows_for
diff --git a/tests/unit/agent_runtimes/test_runtime_configs.py b/tests/unit/agent_runtimes/test_runtime_configs.py
index c7faf346d4..51e4c14c5b 100644
--- a/tests/unit/agent_runtimes/test_runtime_configs.py
+++ b/tests/unit/agent_runtimes/test_runtime_configs.py
@@ -303,6 +303,35 @@ def test_claude_without_a_key_runs_on_the_claude_code_login(gateway_up, monkeypa
assert model_map.login_token_for("openai") is None
+def test_an_agent_can_pin_claude_to_the_key_or_the_login(gateway_up, monkeypatch):
+ import jarvis.agent_runtimes.model_map as model_map
+ from jarvis.agent_chat.catalog import API_KEY_ACCOUNT, SUBSCRIPTION_ACCOUNT
+
+ live = "sk-ant-" + "oat01-" + "z" * 20
+ monkeypatch.setattr(model_map, "claude_login_token", lambda: live)
+ with override_provider_secrets({"claude-api": _SECRET}):
+ # Both ways work: the dialog offers both, the key stays the default.
+ assert model_map.access_choices() == {"claude-api": ["api", "subscription"]}
+ assert model_map.login_token_for("claude-api") is None
+ assert model_map.login_token_for("claude-api", API_KEY_ACCOUNT) is None
+ assert model_map.login_token_for("claude-api", SUBSCRIPTION_ACCOUNT) == live
+ route = route_for(
+ _cfg(), "claude-api", "claude-sonnet-5", agent_id="a", account_id=SUBSCRIPTION_ACCOUNT
+ )
+ grant = gateway_up.verify(route.api_key or "")
+ assert grant == gateway_up.Grant("a", "claude-api", SUBSCRIPTION_ACCOUNT)
+ with override_provider_secrets({"claude-api": None}):
+ assert model_map.access_choices() == {"claude-api": ["subscription"]}
+ assert model_map.login_token_for("claude-api", API_KEY_ACCOUNT) is None
+ with pytest.raises(RouteUnavailable, match="API key"):
+ route_for(_cfg(), "claude-api", "claude-sonnet-5", account_id=API_KEY_ACCOUNT)
+ monkeypatch.setattr(model_map, "claude_login_token", lambda: None)
+ with override_provider_secrets({"claude-api": _SECRET}):
+ assert model_map.access_choices() == {"claude-api": ["api"]}
+ with pytest.raises(RouteUnavailable, match="Claude Code login"):
+ route_for(_cfg(), "claude-api", "claude-sonnet-5", account_id=SUBSCRIPTION_ACCOUNT)
+
+
def test_the_claude_login_brain_sends_a_bearer_not_an_api_key():
from jarvis.plugins.brain.claude_api import ClaudeAPIBrain