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): choose an agent's runtime (Jarvis, Hermes, OpenClaw)

rubenluetke10-beepf2354f47ffd4
diff --git a/jarvis/agent_chat/catalog.py b/jarvis/agent_chat/catalog.py
index 7eccc0e329..f71075d0a8 100644
--- a/jarvis/agent_chat/catalog.py
+++ b/jarvis/agent_chat/catalog.py
@@ -75,6 +75,10 @@ Runner = Literal[
"glm-cli",
"dsh-cli",
"cursor-cli",
+ # Society agent runtimes (``service.EXTERNAL_RUNTIME_RUNNERS``): picked by
+ # the agent's runtime, never by a provider row.
+ "hermes-cli",
+ "openclaw-cli",
]
diff --git a/jarvis/agent_chat/control.py b/jarvis/agent_chat/control.py
index d62a8d79ad..b2807b6ef4 100644
--- a/jarvis/agent_chat/control.py
+++ b/jarvis/agent_chat/control.py
@@ -28,9 +28,9 @@ _command_origin: ContextVar[CommandRequest | None] = ContextVar("chat_command_or
def supports_restricted_turn(session: Any) -> bool:
- from .service import resolve_runner
+ from .service import session_runner
- return resolve_runner(session.provider, surface=session.surface) not in ("kimi-cli", "dsh-cli")
+ return session_runner(session) not in ("kimi-cli", "dsh-cli")
class ChatControls:
@@ -349,10 +349,10 @@ class ChatControls:
from .events import make_event
from .permissions import ladder_key, normalize_permission, society_mode_supported
- from .service import resolve_runner
+ from .service import session_runner
session = self.service.store.get_session(sid)
- runner = resolve_runner(session.provider, surface=session.surface)
+ runner = session_runner(session)
ladder = ladder_key(session.surface, runner)
# /plan is a chat control, not a ladder choice: the Society ladder
# (bypass / ask / always ask) has no read-only rung, and folding
diff --git a/jarvis/agent_chat/control_eval.py b/jarvis/agent_chat/control_eval.py
index 935966f9ad..7d4ca1d910 100644
--- a/jarvis/agent_chat/control_eval.py
+++ b/jarvis/agent_chat/control_eval.py
@@ -20,7 +20,7 @@ async def evaluate_goal(
) -> GoalVerdict:
from .runner_api import TurnHandle, build_brain, supports_api_runner
from .runner_cli import run_cli_turn
- from .service import resolve_runner
+ from .service import session_runner
sources = {
str(e["seq"]): e
@@ -97,7 +97,7 @@ async def evaluate_goal(
if hasattr(result, "__await__"):
await result
else:
- runner = resolve_runner(session.provider, surface=session.surface)
+ runner = session_runner(session)
if runner not in (
"claude-cli",
"glm-cli",
diff --git a/jarvis/agent_chat/native_control.py b/jarvis/agent_chat/native_control.py
index 365a7de067..26c3f91e1b 100644
--- a/jarvis/agent_chat/native_control.py
+++ b/jarvis/agent_chat/native_control.py
@@ -81,9 +81,9 @@ class NativeClaudeGoal:
async def available(self, session: Any) -> bool:
from .runner_cli import ACCOUNT_OVERRIDE, _account_env, claude_argv_prefix
- from .service import resolve_runner
+ from .service import session_runner
- if resolve_runner(session.provider, surface=session.surface) not in (
+ if session_runner(session) not in (
"claude-cli",
"glm-cli",
):
@@ -201,7 +201,7 @@ class NativeClaudeGoal:
from .runner_api import TurnHandle
from .runner_cli import run_cli_turn
- from .service import resolve_runner
+ from .service import session_runner
session = service.store.get_session(sid)
if not session or not session.vendor_session:
@@ -223,7 +223,7 @@ class NativeClaudeGoal:
tools_disabled=True,
)
await run_cli_turn(
- handle, "/goal clear", resolve_runner(session.provider, surface=session.surface)
+ handle, "/goal clear", session_runner(session)
)
if any(
e["kind"] == "turn_finished" and e["payload"].get("status") != "done" for e in captured
@@ -398,9 +398,9 @@ class NativeCodexGoal:
async def available(self, session: Any) -> bool:
from .runner_cli import codex_argv_prefix
- from .service import resolve_runner
+ from .service import session_runner
- if resolve_runner(session.provider, surface=session.surface) != "codex-cli":
+ if session_runner(session) != "codex-cli":
return False
try:
prefix = codex_argv_prefix()
diff --git a/jarvis/agent_chat/permissions.py b/jarvis/agent_chat/permissions.py
index dd6a432a46..ab2a3ca512 100644
--- a/jarvis/agent_chat/permissions.py
+++ b/jarvis/agent_chat/permissions.py
@@ -393,7 +393,16 @@ def society_mode_supported(runner: str, mode: str) -> bool:
if mode == "bypass":
return True
if mode == "ask":
- return runner in {"brain", "codex-cli", "claude-cli", "glm-cli"}
+ # Hermes and OpenClaw ask over ACP (session/request_permission) before
+ # the actions their own approval policy marks as risky.
+ return runner in {
+ "brain",
+ "codex-cli",
+ "claude-cli",
+ "glm-cli",
+ "hermes-cli",
+ "openclaw-cli",
+ }
if mode == "always_ask":
return runner in {"brain", "codex-cli"}
return False
diff --git a/jarvis/agent_chat/service.py b/jarvis/agent_chat/service.py
index 8de865c782..9f51c866ed 100644
--- a/jarvis/agent_chat/service.py
+++ b/jarvis/agent_chat/service.py
@@ -80,7 +80,15 @@ def _claude_cli_installed() -> bool:
return bool(shutil.which("claude") or shutil.which("claude.cmd") or shutil.which("claude.exe"))
-def resolve_runner(provider: str, *, surface: str = "agent") -> str:
+#: Society agent runtimes that replace the provider's runner (``AgentRuntime``
+#: minus ``jarvis``), each answered by its ACP driver in ``runner_cli``.
+EXTERNAL_RUNTIME_RUNNERS: Final[dict[str, str]] = {
+ "hermes": "hermes-cli",
+ "openclaw": "openclaw-cli",
+}
+
+
+def resolve_runner(provider: str, *, surface: str = "agent", runtime: 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
@@ -94,6 +102,10 @@ def resolve_runner(provider: str, *, surface: str = "agent") -> str:
answers there — not even the dual Claude row, which runs on the Anthropic
API behind its key like every other seat.
"""
+ if runtime in EXTERNAL_RUNTIME_RUNNERS and surface == "society":
+ # A Hermes / OpenClaw agent: that runtime's loop answers every turn and
+ # the provider only names the model it is configured with.
+ return EXTERNAL_RUNTIME_RUNNERS[runtime]
kit = kit_for(surface)
api_runner = "brain" if kit.brain_runner else "api"
row = provider_row(provider)
@@ -111,6 +123,15 @@ def resolve_runner(provider: str, *, surface: str = "agent") -> str:
return row.runner
+def session_runner(session: Any) -> str:
+ """:func:`resolve_runner` for a stored chat session (its runtime included)."""
+ return resolve_runner(
+ session.provider,
+ surface=session.surface,
+ runtime=str(getattr(session, "runtime", "") or ""),
+ )
+
+
#: ``AgentChatStore.data_version`` after the front page's chat gave up its
#: CLI seats (2026-08-26) and its sessions moved to the API row of the same
#: brand. Bump — and add a branch in ``_retire_cli_seats``' caller — only for
@@ -877,7 +898,7 @@ class AgentChatService:
},
),
)
- runner = selected_runner or resolve_runner(session.provider, surface=session.surface)
+ runner = selected_runner or session_runner(session)
turn_started_emitted = True
await self._emit(
session_id,
@@ -1725,4 +1746,5 @@ __all__ = [
"SessionBusy",
"Subscriber",
"resolve_runner",
+ "session_runner",
]
diff --git a/jarvis/agent_chat/store.py b/jarvis/agent_chat/store.py
index de0ebca44a..1330042c0c 100644
--- a/jarvis/agent_chat/store.py
+++ b/jarvis/agent_chat/store.py
@@ -48,7 +48,8 @@ CREATE TABLE IF NOT EXISTS agent_chat_sessions (
message_count INTEGER NOT NULL DEFAULT 0,
preview TEXT NOT NULL DEFAULT '',
surface TEXT NOT NULL DEFAULT 'agent',
- account_id TEXT NOT NULL DEFAULT ''
+ account_id TEXT NOT NULL DEFAULT '',
+ runtime TEXT NOT NULL DEFAULT ''
);
CREATE TABLE IF NOT EXISTS agent_chat_events (
session_id TEXT NOT NULL,
@@ -127,6 +128,9 @@ class AgentChatSession:
#: The subscription seat (``jarvis.agent_accounts`` id) a CLI turn runs on;
#: empty = the platform's active account.
account_id: str = ""
+ #: A society agent's external runtime (``hermes`` / ``openclaw``,
+ #: ``docs/agent-runtimes.md``); empty = the provider picks the runner.
+ runtime: str = ""
def to_dict(self) -> dict[str, Any]:
return asdict(self)
@@ -178,6 +182,12 @@ class AgentChatStore:
self._conn.execute(
"ALTER TABLE agent_chat_sessions ADD COLUMN account_id TEXT NOT NULL DEFAULT ''"
)
+ if "runtime" not in have:
+ # The society agent's external runtime (hermes / openclaw); empty =
+ # the provider decides the runner (the pre-column behaviour).
+ self._conn.execute(
+ "ALTER TABLE agent_chat_sessions ADD COLUMN runtime TEXT NOT NULL DEFAULT ''"
+ )
def close(self) -> None:
with self._lock:
@@ -235,6 +245,7 @@ class AgentChatStore:
session_id: str | None = None,
surface: str = DEFAULT_SURFACE,
account_id: str = "",
+ runtime: str = "",
) -> AgentChatSession:
if surface not in SURFACES:
raise ValueError(f"surface must be one of {SURFACES}, not {surface!r}")
@@ -247,9 +258,22 @@ class AgentChatStore:
self._conn.execute(
"INSERT INTO agent_chat_sessions (session_id, title, provider, model, effort, "
"cwd, permission_mode, vendor_session, created_ms, updated_ms, message_count, "
- "preview, surface, account_id) "
- "VALUES (?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, 0, '', ?, ?)",
- (sid, title, provider, model, effort, cwd, mode, now, now, surface, account_id),
+ "preview, surface, account_id, runtime) "
+ "VALUES (?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, 0, '', ?, ?, ?)",
+ (
+ sid,
+ title,
+ provider,
+ model,
+ effort,
+ cwd,
+ mode,
+ now,
+ now,
+ surface,
+ account_id,
+ runtime,
+ ),
)
self._conn.commit()
session = self.get_session(sid)
@@ -308,6 +332,7 @@ class AgentChatStore:
"permission_mode",
"vendor_session",
"account_id",
+ "runtime",
}
updates = {k: v for k, v in fields.items() if k in allowed and v is not None}
if not updates:
@@ -545,4 +570,5 @@ class AgentChatStore:
preview=row["preview"],
surface=str(row["surface"] or DEFAULT_SURFACE),
account_id=str(row["account_id"] or "") if "account_id" in row.keys() else "",
+ runtime=str(row["runtime"] or "") if "runtime" in row.keys() else "",
)
diff --git a/jarvis/agent_chat/surface_kits.py b/jarvis/agent_chat/surface_kits.py
index 7ff7002fc1..a07977303c 100644
--- a/jarvis/agent_chat/surface_kits.py
+++ b/jarvis/agent_chat/surface_kits.py
@@ -194,10 +194,10 @@ async def _jarvis_completed(session: Any, completion: ChatCompletion) -> None:
def _society_history_start(session: Any) -> int:
- from jarvis.agent_chat.service import resolve_runner
+ from jarvis.agent_chat.service import session_runner
from jarvis.society.runtime import current_runtime
- if resolve_runner(session.provider, surface=session.surface) != "brain":
+ if session_runner(session) != "brain":
return 0 # Subscription seats retain their vendor's history/compaction contract.
runtime = current_runtime()
return runtime.conversations.checkpoint(session.session_id)[0] if runtime is not None else 0
diff --git a/jarvis/mcp/agents/portable.py b/jarvis/mcp/agents/portable.py
index c996f385a3..12da68205b 100644
--- a/jarvis/mcp/agents/portable.py
+++ b/jarvis/mcp/agents/portable.py
@@ -60,6 +60,7 @@ PORTABLE_FIELDS: Final[tuple[str, ...]] = (
"browser_mode",
"browser_allowed_domains",
"avatar",
+ "runtime",
)
#: Fields that must NEVER appear in a bundle, each for a stated reason. Checked
diff --git a/jarvis/society/chat_binding.py b/jarvis/society/chat_binding.py
index d49c2f23d3..c31dc070bd 100644
--- a/jarvis/society/chat_binding.py
+++ b/jarvis/society/chat_binding.py
@@ -86,6 +86,12 @@ def _workspace(cfg: Any, agent: AgentRecord) -> str:
return str(folder)
+def _session_runtime(agent: AgentRecord) -> str:
+ """The chat session's ``runtime`` column: empty for Jarvis' own runtime."""
+ runtime = str(getattr(agent, "runtime", "") or "jarvis")
+ return "" if runtime == "jarvis" else runtime
+
+
def ensure_session(
svc: Any,
cfg: Any,
@@ -106,7 +112,8 @@ def ensure_session(
from jarvis.agent_chat.service import resolve_runner
provider, model, effort = pair_for(cfg, agent)
- runner = resolve_runner(provider, surface=SURFACE)
+ runtime = _session_runtime(agent)
+ runner = resolve_runner(provider, surface=SURFACE, runtime=runtime)
legacy_mode = ""
if agent.approval_mode is None:
legacy_mode = normalize_permission(
@@ -143,6 +150,7 @@ def ensure_session(
session_id=session_id,
surface=SURFACE,
account_id=agent.account_id,
+ runtime=runtime,
)
if getattr(svc, "is_running", lambda _sid: False)(session_id):
# An active CLI turn still owns its provider-specific vendor session.
@@ -151,7 +159,12 @@ def ensure_session(
if existing.provider != provider or existing.model != model:
svc.store.reseat_session(session_id, provider=provider, model=model)
existing = svc.store.get_session(session_id)
- ladder = ladder_key(SURFACE, resolve_runner(provider, surface=SURFACE))
+ if getattr(existing, "runtime", "") != runtime:
+ # The vendor session belongs to the runtime the chat is leaving; the
+ # next turn opens a fresh one from the briefing and recent transcript.
+ svc.store.update_session(session_id, runtime=runtime, vendor_session="")
+ existing = svc.store.get_session(session_id)
+ ladder = ladder_key(SURFACE, runner)
if agent.approval_mode is None:
# Legacy roster rows encoded their chat stance in permission_ceiling.
mode = legacy_mode
diff --git a/jarvis/society/checkpoints.py b/jarvis/society/checkpoints.py
index 2e269a1b1d..686d1168c6 100644
--- a/jarvis/society/checkpoints.py
+++ b/jarvis/society/checkpoints.py
@@ -526,7 +526,8 @@ class CheckpointEngine:
try:
from jarvis.agent_chat.service import resolve_runner
- return resolve_runner(provider, surface="society").endswith("-cli")
+ runtime = str(getattr(agent, "runtime", "") or "")
+ return resolve_runner(provider, surface="society", runtime=runtime).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/events.py b/jarvis/society/events.py
index 69d095f764..2ca096e448 100644
--- a/jarvis/society/events.py
+++ b/jarvis/society/events.py
@@ -22,6 +22,7 @@ from jarvis.missions.ids import uuid7_str
__all__ = [
"AgentApprovalMode",
+ "AgentRuntime",
"AgentState",
"ApprovalState",
"BrowserMode",
@@ -128,6 +129,19 @@ class AgentApprovalMode(StrEnum):
ALWAYS_ASK = "always_ask"
+class AgentRuntime(StrEnum):
+ """The agent loop that executes an agent's turns (``docs/agent-runtimes.md``).
+
+ ``jarvis`` = Jarvis' own brain or the CLI seat the model picks; ``hermes``
+ and ``openclaw`` = those external agents, driven over ACP with the same
+ briefing, memory and Jarvis tools.
+ """
+
+ JARVIS = "jarvis"
+ HERMES = "hermes"
+ OPENCLAW = "openclaw"
+
+
class BrowserMode(StrEnum):
"""``own`` = the agent's persistent Chromium profile; ``attach`` = the
person's running Chrome over CDP."""
diff --git a/jarvis/society/roster.py b/jarvis/society/roster.py
index 3f8709cb41..45681eee10 100644
--- a/jarvis/society/roster.py
+++ b/jarvis/society/roster.py
@@ -31,6 +31,7 @@ from pydantic import ValidationError
from .companion import random_companion, validate_avatar_companion
from .events import (
AgentApprovalMode,
+ AgentRuntime,
AgentState,
BrowserMode,
Checkpoint,
@@ -183,6 +184,9 @@ class AgentRecord:
#: Where the agent's work executes: ``None`` = this computer, else the id
#: of a connected machine (``jarvis.computers``) reached over SSH.
computer_id: str | None = None
+ #: The agent loop that executes turns (``AgentRuntime``); ``jarvis`` for
+ #: every agent created before runtimes existed.
+ runtime: AgentRuntime = AgentRuntime.JARVIS
@property
def session_id(self) -> str:
@@ -226,6 +230,7 @@ class AgentRecord:
"browser_mode": str(self.browser_mode),
"browser_allowed_domains": list(self.browser_allowed_domains),
"computer_id": self.computer_id,
+ "runtime": str(self.runtime),
"session_id": self.session_id,
"created_ms": self.created_ms,
"updated_ms": self.updated_ms,
@@ -276,6 +281,7 @@ class AgentRecord:
str(x) for x in _loads(row.get("browser_allowed_domains_json"), [])
],
computer_id=str(row["computer_id"]) if row.get("computer_id") else None,
+ runtime=AgentRuntime(str(row.get("runtime") or "jarvis")),
created_ms=int(row.get("created_ms") or 0),
updated_ms=int(row.get("updated_ms") or 0),
)
@@ -311,6 +317,7 @@ _EDITABLE: Final[frozenset[str]] = frozenset(
"browser_mode",
"browser_allowed_domains",
"computer_id",
+ "runtime",
}
)
@@ -375,6 +382,15 @@ def _validate_computer(value: Any) -> str | None:
return computer_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:
+ raise RosterError(
+ FailureReason.BLOCKED_BY_POLICY,
+ "Hermes and OpenClaw agents run on this computer; clear the connected computer first",
+ )
+
+
def _coerce(field_name: str, value: Any) -> Any:
"""Validate one editable field and return its column value."""
if field_name == "name":
@@ -399,6 +415,8 @@ def _coerce(field_name: str, value: Any) -> Any:
return _enum(AgentApprovalMode, value, field_name)
if field_name == "browser_mode":
return _enum(BrowserMode, value, field_name)
+ if field_name == "runtime":
+ return _enum(AgentRuntime, value, field_name)
if field_name == "browser_allowed_domains":
if not isinstance(value, list) or not all(isinstance(x, str) for x in value):
raise RosterError(
@@ -564,6 +582,9 @@ class Roster:
raise RosterError(
FailureReason.TIER_NOT_ALLOWED, "the lead always runs on this computer"
)
+ if tier_value is Tier.LEAD and str(fields.get("runtime") or "jarvis") != "jarvis":
+ raise RosterError(FailureReason.TIER_NOT_ALLOWED, "the lead always runs on Jarvis")
+ _check_runtime_placement(fields.get("runtime"), fields.get("computer_id"))
if tier_value is Tier.LEAD and "approval_mode" in fields:
raise RosterError(
FailureReason.BLOCKED_BY_POLICY,
@@ -655,6 +676,8 @@ class Roster:
raise RosterError(
FailureReason.TIER_NOT_ALLOWED, "the lead always runs on this computer"
)
+ if key == "runtime" and agent_id == LEAD_AGENT_ID and str(value) != "jarvis":
+ raise RosterError(FailureReason.TIER_NOT_ALLOWED, "the lead always runs on Jarvis")
if key == "tier" and str(value) == str(Tier.LEAD) and agent_id != LEAD_AGENT_ID:
raise RosterError(FailureReason.TIER_NOT_ALLOWED, "only Jarvis is the lead")
if key == "parent_agent_id" and value:
@@ -665,6 +688,11 @@ class Roster:
if await self._store.get_agent_row(str(value)) is None:
raise RosterError(FailureReason.TARGET_UNKNOWN, f"parent {value!r} not found")
columns[_JSON_FIELDS.get(key, key)] = _coerce(key, value)
+ if "runtime" in columns or "computer_id" in columns:
+ _check_runtime_placement(
+ columns.get("runtime", current.get("runtime")),
+ columns.get("computer_id", current.get("computer_id")),
+ )
try:
await self._store.update_agent(agent_id, columns)
except sqlite3.IntegrityError as exc:
diff --git a/jarvis/society/society_schema.sql b/jarvis/society/society_schema.sql
index 9f4d5e1af6..6e6143e595 100644
--- a/jarvis/society/society_schema.sql
+++ b/jarvis/society/society_schema.sql
@@ -49,6 +49,8 @@ CREATE TABLE IF NOT EXISTS society_agents (
-- Where the agent's work executes: NULL = this computer, else the id of a
-- connected machine in jarvis/computers (a VPS or a local VM, over SSH).
computer_id TEXT DEFAULT NULL,
+ runtime TEXT NOT NULL DEFAULT 'jarvis'
+ CHECK (runtime IN ('jarvis', 'hermes', 'openclaw')),
created_ms INTEGER NOT NULL,
updated_ms INTEGER NOT NULL
);
diff --git a/jarvis/society/store.py b/jarvis/society/store.py
index 49ec42e64e..800a9794de 100644
--- a/jarvis/society/store.py
+++ b/jarvis/society/store.py
@@ -148,6 +148,13 @@ class SocietyStore:
"ALTER TABLE society_agents ADD COLUMN computer_id TEXT DEFAULT NULL"
)
log.info("society store: migration applied — added computer_id")
+ if "runtime" not in existing:
+ # Every existing agent keeps running on Jarvis' own runtime.
+ await self.conn.execute(
+ "ALTER TABLE society_agents ADD COLUMN runtime TEXT NOT NULL DEFAULT 'jarvis' "
+ "CHECK (runtime IN ('jarvis', 'hermes', 'openclaw'))"
+ )
+ log.info("society store: migration applied — added runtime")
await self._migrate_checkpoint_vocabulary()
async def _migrate_checkpoint_vocabulary(self) -> None:
diff --git a/jarvis/ui/web/frontend/src/lib/societyApi.ts b/jarvis/ui/web/frontend/src/lib/societyApi.ts
index 762e744cb7..dc11d07385 100644
--- a/jarvis/ui/web/frontend/src/lib/societyApi.ts
+++ b/jarvis/ui/web/frontend/src/lib/societyApi.ts
@@ -57,6 +57,9 @@ export type AgentApprovalMode = (typeof AGENT_APPROVAL_MODES)[number];
export const BROWSER_MODES = ["own", "attach"] as const;
export type BrowserMode = (typeof BROWSER_MODES)[number];
+/** The agent loop that runs an agent's turns (docs/agent-runtimes.md). */
+export const AGENT_RUNTIMES = ["jarvis", "hermes", "openclaw"] as const;
+export type AgentRuntime = (typeof AGENT_RUNTIMES)[number];
export const GRANT_MODES = ["all", "allowlist"] as const;
export type GrantMode = (typeof GRANT_MODES)[number];
@@ -167,6 +170,8 @@ export interface SocietyAgentRow {
browser_allowed_domains: string[];
/** Where the agent runs: null = this computer, else a connected computer id. */
computer_id: string | null;
+ /** The agent loop that runs its turns: Jarvis, Hermes or OpenClaw. */
+ runtime: AgentRuntime;
session_id: string;
created_ms: number;
updated_ms: number;
diff --git a/jarvis/ui/web/society_routes.py b/jarvis/ui/web/society_routes.py
index 91ac12b6ae..02f8deff7f 100644
--- a/jarvis/ui/web/society_routes.py
+++ b/jarvis/ui/web/society_routes.py
@@ -79,12 +79,14 @@ def _validated_chat_runner(
*,
approval_mode: str | None = None,
permission_ceiling: str | None = None,
+ runtime: 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
from jarvis.agent_chat.service import resolve_runner
- runner = resolve_runner(provider, surface="society")
+ chosen_runtime = str(runtime if runtime is not None else agent.runtime)
+ runner = resolve_runner(provider, surface="society", runtime=chosen_runtime)
mode = approval_mode if approval_mode is not None else (
str(agent.approval_mode) if agent.approval_mode is not None else ""
)
@@ -136,6 +138,8 @@ class CreateAgentBody(BaseModel):
browser_allowed_domains: list[str] | None = None
#: Where the agent runs: "" = this computer, else a connected computer id.
computer_id: str | None = None
+ #: The agent loop: "jarvis" (default), "hermes" or "openclaw".
+ runtime: str | None = None
#: Structured brief (jarvis.society.brief); rendered into ``description``.
mission: str | None = Field(default=None, max_length=2_000)
responsibilities: list[str] | None = None
@@ -173,6 +177,8 @@ class PatchAgentBody(BaseModel):
browser_allowed_domains: list[str] | None = None
#: Where the agent runs: "" = this computer, else a connected computer id.
computer_id: str | None = None
+ #: The agent loop: "jarvis" (default), "hermes" or "openclaw".
+ runtime: str | None = None
#: Structured brief (jarvis.society.brief); rendered into ``description``.
mission: str | None = Field(default=None, max_length=2_000)
responsibilities: list[str] | None = None
@@ -320,7 +326,10 @@ async def create_agent(body: CreateAgentBody, request: Request) -> dict[str, Any
from jarvis.agent_chat.permissions import society_mode_supported
from jarvis.agent_chat.service import resolve_runner
- if not society_mode_supported(resolve_runner(provider, surface="society"), requested_mode):
+ runner = resolve_runner(
+ provider, surface="society", runtime=str(fields.get("runtime") or "")
+ )
+ if not society_mode_supported(runner, requested_mode):
raise HTTPException(
422, "This runner cannot provide an actionable approval for that mode."
)
@@ -377,13 +386,16 @@ async def patch_agent(agent_id: str, body: PatchAgentBody, request: Request) ->
if has_brief(brief):
# A brief rewrites the standing instructions as a whole.
fields["description"] = compose_description(body.description or "", brief)
- if any(key in fields for key in ("provider", "approval_mode", "permission_ceiling")):
+ if any(
+ key in fields for key in ("provider", "approval_mode", "permission_ceiling", "runtime")
+ ):
_validated_chat_runner(
rt,
agent,
body.provider or agent.provider,
approval_mode=body.approval_mode,
permission_ceiling=fields.get("permission_ceiling"),
+ runtime=body.runtime,
)
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
@@ -771,6 +783,9 @@ class ModelBody(BaseModel):
model: str = ""
effort: str = ""
account_id: str = ""
+ #: Switch the agent loop with the model ("jarvis" / "hermes" / "openclaw");
+ #: None keeps the current runtime.
+ runtime: str | None = None
@router.get("/providers")
@@ -831,7 +846,7 @@ 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, runtime=body.runtime)
chat = rt._get_chat()
fields = {
"provider": body.provider.strip().lower(),
@@ -839,6 +854,9 @@ async def switch_agent_model(agent_id: str, body: ModelBody, request: Request) -
"effort": body.effort.strip(),
"account_id": body.account_id.strip(),
}
+ runtime_changed = body.runtime is not None and body.runtime != str(agent.runtime)
+ if body.runtime is not None:
+ fields["runtime"] = body.runtime
if chat is not None and hasattr(chat, "controls"):
from jarvis.society.roster import PAIR_SESSION_MARKER
@@ -866,6 +884,12 @@ async def switch_agent_model(agent_id: str, body: ModelBody, request: Request) -
reseated = session.session_id
except PermissionError as exc:
log.info("society: %s re-seat deferred: %s", agent.agent_id, exc)
+ if runtime_changed:
+ # Marks in the one chat where the new agent loop took over.
+ await svc.post_notice(
+ updated.session_id,
+ {"kind": "runtime_changed", "runtime": str(updated.runtime)},
+ )
return {
"agent": _agent_row(updated, request),
"runner": target_runner,
diff --git a/tests/unit/society/test_agent_runtime_field.py b/tests/unit/society/test_agent_runtime_field.py
new file mode 100644
index 0000000000..91265f9983
--- /dev/null
+++ b/tests/unit/society/test_agent_runtime_field.py
@@ -0,0 +1,155 @@
+"""An agent's runtime (jarvis / hermes / openclaw) from roster to chat runner."""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from jarvis.agent_chat.service import resolve_runner, session_runner
+from jarvis.agent_chat.store import AgentChatStore
+from jarvis.society.chat_binding import ensure_session
+from jarvis.society.events import AgentRuntime
+from jarvis.society.roster import Roster, RosterError
+from jarvis.society.runtime import SocietyRuntime
+from jarvis.society.store import SocietyStore
+
+
+async def roster(tmp_path: Path):
+ store = SocietyStore(tmp_path / "society.db")
+ await store.open()
+ try:
+ yield Roster(store)
+ finally:
+ await store.close()
+
+
+async def test_new_agents_run_on_jarvis_by_default(roster: Roster):
+ scout, _ = await roster.create(name="Scout")
+ assert scout.runtime is AgentRuntime.JARVIS
+ assert scout.to_dict()["runtime"] == "jarvis"
+
+
+async def test_runtime_is_chosen_at_create_and_editable(roster: Roster):
+ hermit, _ = await roster.create(name="Hermit", runtime="hermes")
+ assert hermit.runtime is AgentRuntime.HERMES
+ moved = await roster.update("hermit", {"runtime": "openclaw"})
+ assert moved.runtime is AgentRuntime.OPENCLAW
+ with pytest.raises(RosterError):
+ await roster.update("hermit", {"runtime": "skynet"})
+
+
+async def test_the_lead_always_runs_on_jarvis(roster: Roster):
+ jarvis, _ = await roster.create(name="Jarvis", tier="lead")
+ with pytest.raises(RosterError):
+ await roster.update(jarvis.agent_id, {"runtime": "hermes"})
+ with pytest.raises(RosterError):
+ await roster.create(name="Other", tier="lead", runtime="hermes")
+
+
+async def test_external_runtime_stays_on_this_computer(roster: Roster, monkeypatch):
+ from jarvis.society import roster as roster_mod
+
+ monkeypatch.setattr(roster_mod, "_validate_computer", lambda value: value or None)
+ remote, _ = await roster.create(name="Remote", computer_id="box-1")
+ with pytest.raises(RosterError):
+ await roster.update("remote", {"runtime": "hermes"})
+ with pytest.raises(RosterError):
+ await roster.create(name="Both", runtime="openclaw", computer_id="box-1")
+ local, _ = await roster.create(name="Local", runtime="hermes")
+ with pytest.raises(RosterError):
+ await roster.update(local.agent_id, {"computer_id": "box-1"})
+
+
+async def test_old_society_database_gains_the_runtime_column(tmp_path: Path):
+ db = tmp_path / "society.db"
+ store = SocietyStore(db)
+ await store.open()
+ await store.close()
+ conn = sqlite3.connect(db)
+ conn.execute("ALTER TABLE society_agents DROP COLUMN runtime")
+ conn.commit()
+ conn.close()
+ store = SocietyStore(db)
+ await store.open()
+ try:
+ agent, _ = await Roster(store).create(name="Scout")
+ assert agent.runtime is AgentRuntime.JARVIS
+ finally:
+ await store.close()
+
+
+def test_runtime_picks_the_runner_only_for_society_agents():
+ assert resolve_runner("openai", surface="society", runtime="hermes") == "hermes-cli"
+ assert resolve_runner("openai", surface="society", runtime="openclaw") == "openclaw-cli"
+ assert resolve_runner("openai", surface="society", runtime="") == resolve_runner(
+ "openai", surface="society"
+ )
+ # Runtimes belong to society agents; no other chat surface reads one.
+ assert resolve_runner("openai", surface="jarvis", runtime="hermes") == resolve_runner(
+ "openai", surface="jarvis"
+ )
+
+
+def test_chat_store_keeps_the_runtime(tmp_path: Path):
+ store = AgentChatStore(tmp_path / "agent_chat.db")
+ session = store.create_session(
+ provider="openai",
+ model="gpt-5.2",
+ effort="",
+ cwd=str(tmp_path),
+ surface="society",
+ session_id="society:hermit",
+ runtime="hermes",
+ )
+ assert session.runtime == "hermes"
+ assert session_runner(session) == "hermes-cli"
+ store.close()
+
+
+def test_old_chat_database_gains_the_runtime_column(tmp_path: Path):
+ db = tmp_path / "agent_chat.db"
+ AgentChatStore(db).close()
+ conn = sqlite3.connect(db)
+ conn.execute("ALTER TABLE agent_chat_sessions DROP COLUMN runtime")
+ conn.commit()
+ conn.close()
+ store = AgentChatStore(db)
+ session = store.create_session(provider="openai", model="", effort="", cwd=str(tmp_path))
+ assert session.runtime == ""
+ store.close()
+
+
+class _Svc:
+ def __init__(self, store: AgentChatStore) -> None:
+ self.store = store
+
+ def is_running(self, _session_id: str) -> bool:
+ return False
+
+
+async def test_switching_runtime_reseats_the_chat_and_drops_the_vendor_session(tmp_path: Path):
+ cfg = SimpleNamespace(memory=SimpleNamespace(data_dir=str(tmp_path / "data")))
+ rt = SocietyRuntime(tmp_path, seed_starter_team=False, cfg=lambda: cfg)
+ await rt.ensure_started()
+ svc = _Svc(AgentChatStore(tmp_path / "agent_chat.db"))
+ try:
+ agent, _ = await rt.roster.create(name="Hermit", provider="openai", model="gpt-5.2")
+ first = ensure_session(svc, cfg, agent)
+ assert first.runtime == ""
+ svc.store.update_session(first.session_id, vendor_session="claude-conv-1")
+
+ moved = await rt.roster.update(agent.agent_id, {"runtime": "hermes"})
+ reseated = ensure_session(svc, cfg, moved)
+ assert reseated.runtime == "hermes"
+ assert not reseated.vendor_session
+ assert session_runner(reseated) == "hermes-cli"
+
+ back = await rt.roster.update(agent.agent_id, {"runtime": "jarvis"})
+ assert ensure_session(svc, cfg, back).runtime == ""
+ finally:
+ svc.store.close()
+ await rt.close()
diff --git a/tests/unit/society/test_society_enum_parity.py b/tests/unit/society/test_society_enum_parity.py
index ee2444e566..82c2a27825 100644
--- a/tests/unit/society/test_society_enum_parity.py
+++ b/tests/unit/society/test_society_enum_parity.py
@@ -28,6 +28,7 @@ _PINS = [
(events.PermissionCeiling, "permission_ceiling", "PERMISSION_CEILINGS"),
(events.GrantMode, "grant_mode", "GRANT_MODES"),
(events.BrowserMode, "browser_mode", "BROWSER_MODES"),
+ (events.AgentRuntime, "runtime", "AGENT_RUNTIMES"),
(events.KnowledgeScope, "knowledge_scope", "KNOWLEDGE_SCOPES"),
(events.KnowledgeOrigin, "origin", "KNOWLEDGE_ORIGINS"),
(events.RoomState, None, "ROOM_STATES"),