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.

perf(agent-runtimes): keep Hermes and OpenClaw agents warm between turns (#817)

Ruben Lütkef2b4aae47d03
diff --git a/docs/agent-runtimes.md b/docs/agent-runtimes.md
index 57a460fe1c..03c3ae00be 100644
--- a/docs/agent-runtimes.md
+++ b/docs/agent-runtimes.md
@@ -240,8 +240,33 @@ replayed during `session/load` is swallowed because the chat already shows it.
`approvals.mode: manual` and OpenClaw with `tools.exec.mode: ask`; every
request reaches Dodaios over ACP and is answered from the chat's stance —
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.
+- **Warm processes** (`warm.py`). An agent's runtime process stays up
+ between its turns, initialized and with its conversation open, so a message
+ only costs `session/prompt` (Hermes: first answer text 0.03 s instead of
+ 7 s; replay model). A turn borrows the process through a `Lease`, which the
+ CLI runner drives like a child process: the turn's stdout and stderr, a
+ stdin whose close ends the turn (not the process), and kill, which ends the
+ process. The process is reused only with exactly the launch it was started
+ for (argv, environment, working folder and the runtime's config files,
+ OpenClaw also the Gateway run); anything else retires it and starts a fresh
+ one. A turn without `resume` (a new conversation, a rollover) never reuses
+ the open Hermes session. Idle processes stop after 30 minutes, at most six
+ are kept per runtime, and `stop()` (updates, agent deleted) ends them.
+- **Warm-up when a chat opens.** `POST /api/agent-chat/sessions/{id}/warm`
+ (the agent's chat panel calls it when it opens, at most once a minute)
+ starts the agent's process (OpenClaw: its Gateway first) and opens its
+ conversation in the background. It makes no paid model call, runs only when
+ the agent's turn slot is free at once, re-reads the conversation id once it
+ holds the slot, and does nothing for an agent placed on another computer,
+ whose process starts there per turn. Each warm-up step has 45 s; a message
+ sent meanwhile waits for it and then runs on the warm process.
+- **Nothing slow in front of the first token.** Catalog facts for a model are
+ reused for 15 minutes and re-read in the background; an expired *ready*
+ runtime check (`--version`) is reused while it is checked again; the route
+ and the readiness check run concurrently.
+- **A finished turn ends.** After the prompt's answer the turn is over; a
+ process that is not warm 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,
@@ -255,15 +280,20 @@ replayed during `session/load` is swallowed because the chat already shows it.
- **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
+- **Nothing outlives the process.** The runtime runs in its own process
+ container (Job Object on Windows, process group on POSIX), the warm pool's
+ for a warm process and the turn's otherwise. 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).
+- **Process:** `hermes acp`, kept warm between turns (see above), stdin EOF
+ ends it (exit 0). Turns run with `HERMES_DISABLE_LAZY_INSTALLS=1`: Hermes
+ otherwise syncs its dependency environment, and retries a pending source
+ update tail, in front of the turn (60-190 s measured on Windows). Only the
+ setup job (`prepare_command`) runs without it.
- **Profiles of one Dodaios 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
@@ -288,8 +318,9 @@ replayed during `session/load` is swallowed because the chat already shows it.
Hermes migrates the file forward), `model.provider` / `model.default` /
`model.base_url`, `terminal.cwd` = the agent workspace, Hermes' own memory
and skill nudges off (Dodaios owns memory and skills), the `browser`,
- `computer_use` and `cronjob` toolsets always disabled (Dodaios has a visible
- browser and its own routines; Hermes' browser is a headless Chromium), and
+ `computer_use`, `cronjob` and `skills` toolsets always disabled (Dodaios has
+ a visible browser, its own routines and its own skills; Hermes' browser is a
+ headless Chromium, and its skill listing was a third of every prompt), and
`SOUL.md` = the agent's Dodaios briefing. The only key is the gateway token,
in the process environment.
- **Dodaios tools:** passed per session in `session/new` / `session/load`
@@ -327,12 +358,30 @@ replayed during `session/load` is swallowed because the chat already shows it.
upstream): Dodaios supervises an OpenClaw Gateway child with the embedding
preset (`OPENCLAW_SKIP_CHANNELS=1`, `OPENCLAW_NO_RESPAWN=1`,
`OPENCLAW_DISABLE_BONJOUR=1`, `OPENCLAW_EXEC_SHELL_SNAPSHOT=0`) and drives
- each turn through the version-matched `openclaw acp` bridge
- (`--url ws://127.0.0.1:<port> --session agent:main:main`). No hand-written
+ its turns through the version-matched `openclaw acp` bridge
+ (`--url ws://127.0.0.1:<port>`), kept warm between turns. `session/new`
+ names the conversation in its `_meta` (`sessionKey: agent:main:main`, and
+ `resetSession: true` for a fresh conversation), and each `session/prompt`
+ carries the agent's thinking level (`_meta.thinking`), so one bridge serves
+ every turn and a changed effort never restarts the Gateway. No hand-written
Gateway WebSocket client: its wire protocol requires an exact version match.
+- **Warm-up run.** A fresh Gateway sets its agent loop up on its first run
+ (session lifecycle, SQLite store, harness and context assembly, the MCP
+ connection: about 6 s on Windows; no setting skips it). When a chat opens,
+ Dodaios runs that first run in a session of its own
+ (`agent:main:dodaios-warmup`) inside `gateway.warming(token)`: while it
+ lasts, every model call of that agent's token is answered by Dodaios' model
+ gateway itself, whatever its prompt (no provider call, nothing billed). The
+ warm-up holds the agent's turn slot, so none of the person's turns runs on
+ that token meanwhile. A warm-up never resets the conversation; a fresh one
+ is reset by its own turn. The person's first message then reaches the
+ model in about 0.3 s (replay model).
- **Isolation:** one state directory (`OPENCLAW_STATE_DIR`,
`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.
+ loopback port, started when the agent's chat opens (or on its first turn)
+ and stopped after 30 idle minutes, together with its warm bridge. At most
+ three Gateways run at once (about 1.3 GB of memory each): the least
+ recently used idle one stops for a new one.
A changed config restarts the Gateway (with no turn in flight) instead of
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
@@ -349,7 +398,14 @@ replayed during `session/load` is swallowed because the chat already shows it.
`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`, `tools.deny` for native
- tools that duplicate Dodaios features (automations, messaging, the browser),
+ tools that duplicate Dodaios features (automations, messaging, the browser)
+ or serve OpenClaw's own apps (skill workshop, themes, dashboards, mobile
+ UI, progress cards, presence, portal, TTS, plugin management; their
+ schemas were about a quarter of every request),
+ `skills.workshop.autonomous.mode:"off"` (no skill review, a model call
+ nobody started, after a turn), `update.checkOnStart:false`,
+ `gateway.controlUi.enabled:false` (its asset build cost seconds of CPU after
+ every start),
`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
@@ -365,7 +421,7 @@ replayed during `session/load` is swallowed because the chat already shows it.
name (`jarvis__<tool>`, `mcp__jarvis__<tool>`) are read the same way
everywhere a tool name is matched (`dodaios/core/mcp_names.py`).
- **Sessions:** the fixed session key keeps one conversation across bridge
- processes; the ACP session id changes per process and is not stored.
+ processes and ACP sessions; the ACP session id is not stored.
- **Heartbeat:** OpenClaw runs a background model turn every 30 minutes by
default. Dodaios sets `heartbeat.every: "0m"` for every agent: nothing the
person did not start may bill a key.
diff --git a/dodaios/agent_chat/runner_acp.py b/dodaios/agent_chat/runner_acp.py
index 9f30ef3c7b..7e30afe61e 100644
--- a/dodaios/agent_chat/runner_acp.py
+++ b/dodaios/agent_chat/runner_acp.py
@@ -113,7 +113,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)
+ status = await asyncio.to_thread(runtime.detect, fast=True)
if not setting_up and manager.needed(runtime, status) is None:
return
await handle.emit(
@@ -134,6 +134,90 @@ async def _ready(handle: Any, runtime_name: str, runtime: Any) -> None:
raise CliUnavailable(f"{runtime.label} could not be set up. {reason}".strip())
+async def _runtime_turn(
+ session: Any,
+ agent: Any,
+ *,
+ cwd: Path,
+ resume: str | None,
+ tools: bool,
+ warm: bool,
+) -> RuntimeTurn:
+ """The runtime's view of one turn; raises ``RouteUnavailable``."""
+ from dodaios.agent_chat import dodaios_harness
+ from dodaios.agent_chat.effort import normalize_effort
+
+ 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,
+ )
+ plan_mode = session.permission_mode in ("plan", "read-only")
+ reasoning, vision = await asyncio.to_thread(model_capabilities, route.provider, route.model)
+ return RuntimeTurn(
+ agent_id=agent.agent_id,
+ agent_name=agent.name,
+ session_id=session.session_id,
+ workspace=cwd,
+ route=route,
+ resume=resume,
+ auto_approve=session.permission_mode == "bypass",
+ mcp_url=dodaios_harness.endpoint() if tools else None,
+ control_key=dodaios_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,
+ warm=warm,
+ )
+
+
+async def warm_session(session: Any, store: Any | None = None) -> bool:
+ """Get an agent's runtime ready before its next message (chat opened, typing).
+
+ Starts the agent's process (OpenClaw: its Gateway too) and opens the
+ conversation, so the message that follows only costs the model call.
+ No paid model call is made. ``False`` = nothing to warm (not a runtime
+ agent, not set up, a turn running, another computer). ``store`` re-reads
+ the chat's conversation id once the agent's slot is held.
+ """
+ from dodaios.agent_chat.runner_cli import _resolved_cwd
+
+ runtime_name = str(getattr(session, "runtime", "") or "")
+ agent_id = _agent_id(str(getattr(session, "session_id", "") or ""))
+ if runtime_name not in RUNNER_RUNTIMES.values() or not agent_id:
+ return False
+ from dodaios.society.remote import placement_for_session
+
+ if await placement_for_session(session) is not None:
+ return False # its process runs on the other computer, per turn
+ agent = await _agent(agent_id)
+ if agent is None:
+ return False
+ runtime = driver(runtime_name)
+ warm = getattr(runtime, "warm", None)
+ if warm is None:
+ return False
+ try:
+ turn = await _runtime_turn(
+ session, agent,
+ cwd=_resolved_cwd(session.cwd or Path.home()),
+ resume=session.vendor_session or None,
+ tools=True,
+ warm=True,
+ )
+ def latest_resume() -> str | None:
+ fresh = store.get_session(session.session_id) if store is not None else None
+ row = fresh if fresh is not None else session
+ return str(getattr(row, "vendor_session", "") or "") or None
+
+ return bool(await warm(turn, latest_resume))
+ except (RouteUnavailable, RuntimeUnavailable) as exc:
+ log.info("agent runtimes: %s not warmed: %s", runtime_name, exc)
+ return False
+
+
async def plan_runtime_turn(
handle: Any,
runner: str,
@@ -145,12 +229,9 @@ async def plan_runtime_turn(
) -> Any:
"""The ``CliPlan`` for one turn on ``runner``; raises ``CliUnavailable``."""
from dodaios import __version__
- from dodaios.agent_chat import dodaios_harness
from dodaios.agent_chat.runner_cli import (
- _PLAN_PREAMBLE,
- CliPlan,
+ _REMOTE_PLANNING,
CliUnavailable,
- _with_identity,
)
session = handle.session
@@ -159,59 +240,91 @@ async def plan_runtime_turn(
agent = await _agent(agent_id)
if agent is None:
raise CliUnavailable(f"{runtime_name.title()} runs society agents only.")
- try:
- 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,
+ plan_mode = session.permission_mode in ("plan", "read-only")
+ runtime = driver(runtime_name)
+ # The route (catalog facts, maybe a network read) and the runtime's
+ # readiness check are independent: neither waits for the other.
+ turn_task = asyncio.ensure_future(
+ _runtime_turn(
+ session, agent,
+ cwd=cwd,
+ resume=resume,
+ tools=not getattr(handle, "tools_disabled", False),
+ # A turn placed on another computer starts its process there.
+ warm=not _REMOTE_PLANNING.get(),
)
+ )
+ try:
+ await _ready(handle, runtime_name, runtime)
+ except BaseException:
+ turn_task.cancel()
+ raise
+ try:
+ turn = await turn_task
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 dodaios.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,
- session_id=session.session_id,
- workspace=cwd,
- route=route,
- resume=resume,
- auto_approve=session.permission_mode == "bypass",
- mcp_url=dodaios_harness.endpoint() if tools else None,
- control_key=dodaios_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)
+ route = turn.route
try:
launch = await runtime.launch(turn)
except RuntimeUnavailable as exc:
raise CliUnavailable(str(exc)) from exc
- try:
- failure = gateway.watch_failure(route.api_key or "", effort=session.effort or "")
- except Exception:
+
+ def release_launch() -> None:
+ lease = launch.proc
+ if lease is not None and not lease.finished:
+ # Planning ended before the turn ran: the process stays warm.
+ lease.finish()
if launch.release is not None:
launch.release()
+
+ try:
+ failure = gateway.watch_failure(route.api_key or "", effort=session.effort or "")
+ except BaseException:
+ release_launch()
raise
def release() -> None:
gateway.unwatch_failure(route.api_key or "", failure)
+ acp = plan.acp if plan is not None else None
if launch.invalidate is not None and (
handle.cancel.is_set()
or (failure.done() and not failure.cancelled())
+ or acp is None
or not acp.saw_result
or acp.status != "done"
):
launch.invalidate()
- if launch.release is not None:
- launch.release()
+ release_launch()
+
+ plan: Any = None
+ try:
+ plan = _plan(
+ handle, launch, turn, failure, release,
+ prompt=prompt, plan_mode=plan_mode, identity=identity, resume=resume,
+ client_version=__version__,
+ )
+ return plan
+ except BaseException:
+ # Never a warm process left leased (and the slot held) by a plan
+ # that was not handed to the runner.
+ release()
+ raise
+
+
+def _plan(
+ handle: Any,
+ launch: Any,
+ turn: RuntimeTurn,
+ failure: Any,
+ release: Any,
+ *,
+ prompt: str,
+ plan_mode: bool,
+ identity: Any | None,
+ resume: str | None,
+ client_version: str,
+) -> Any:
+ from dodaios.agent_chat.runner_cli import _PLAN_PREAMBLE, CliPlan, _with_identity
text = _PLAN_PREAMBLE + prompt if plan_mode else prompt
acp = AcpTurn(
@@ -222,9 +335,16 @@ async def plan_runtime_turn(
mcp_servers=launch.mcp_servers,
auto_allow=turn.auto_approve,
auto_deny=plan_mode,
- client_version=__version__,
+ client_version=client_version,
report_session=launch.vendor_session,
+ session_meta=launch.session_meta,
+ prompt_meta=launch.prompt_meta,
)
+ if launch.proc is not None:
+ # The agent's warm process: initialized, maybe with the session open.
+ acp.initialized = launch.proc.initialized
+ acp.open_session = launch.proc.open_session
+ launch.proc.turn = acp
return CliPlan(
argv=launch.argv,
env=launch.env,
@@ -235,4 +355,5 @@ async def plan_runtime_turn(
acp=acp,
after_turn=release,
provider_failure=failure,
+ proc=launch.proc,
)
diff --git a/dodaios/agent_chat/runner_cli.py b/dodaios/agent_chat/runner_cli.py
index d3bfb78dc6..588bf7b6ab 100644
--- a/dodaios/agent_chat/runner_cli.py
+++ b/dodaios/agent_chat/runner_cli.py
@@ -567,6 +567,10 @@ class CliPlan:
after_turn: Callable[[], None] | None = None
#: The local gateway knows failures that a runtime may render as prose.
provider_failure: Future[str] | None = None
+ #: A process that is already running (an agent runtime's warm process,
+ #: ``agent_runtimes.warm.Lease``): driven instead of spawning ``argv``.
+ #: Its owner contains it, so the turn adds no process tree of its own.
+ proc: Any | None = None
def claude_control_init() -> str:
@@ -3652,7 +3656,7 @@ async def _run_cli_once(
log.info("agent chat %s: %s argv=%s", handle.turn_id, runner, plan.argv[:6])
started_at = time.time()
tree = None
- if placement is None and (
+ if placement is None and plan.proc is None and (
getattr(handle, "goal_turn", False)
or (session.surface == "society" and session.permission_mode == "plan")
or plan.acp is not None
@@ -3661,7 +3665,9 @@ async def _run_cli_once(
tree = make_process_tree("chat-controlled-cli")
proc: Any
- if placement is not None:
+ if plan.proc is not None:
+ proc = plan.proc
+ elif placement is not None:
from dodaios.agent_chat.remote_cli import RemoteCliUnavailable, spawn
prompt_files: dict[str, str] = {}
@@ -4114,6 +4120,10 @@ async def _drive_cli(
if plan.acp is not None:
proc.stdin.write(plan.acp.opening_frame().encode("utf-8"))
await proc.stdin.drain()
+ if plan.acp.saw_result:
+ # Settled before a single frame (a warm process that cannot
+ # reopen the conversation): nothing more will come.
+ _close_stdin()
if plan.stdin_text is not None:
proc.stdin.write(plan.stdin_text.encode("utf-8"))
await proc.stdin.drain()
diff --git a/dodaios/agent_runtimes/acp.py b/dodaios/agent_runtimes/acp.py
index 393046bc57..b1c301c0da 100644
--- a/dodaios/agent_runtimes/acp.py
+++ b/dodaios/agent_runtimes/acp.py
@@ -8,7 +8,7 @@ through it instead of their CLI flags or internal APIs: an upstream update
keeps working as long as the protocol does.
One :class:`AcpTurn` drives one process from handshake to the prompt's
-response:
+response (a warm process, ``warm.Lease``, starts at the session or the prompt):
1. ``initialize`` (protocol version + client capabilities),
2. ``session/load`` of the stored conversation, or ``session/new``,
@@ -167,6 +167,17 @@ class AcpTurn:
#: What the chat stores as its vendor session instead of the ACP session
#: id (OpenClaw addresses the conversation by a fixed session key).
report_session: str | None = None
+ #: A warm process (``warm.Lease``) answered ``initialize`` already: its
+ #: result, so the turn starts at the session instead of the handshake.
+ initialized: dict[str, Any] | None = None
+ #: The ACP session already open in that process with this turn's
+ #: parameters: the turn goes straight to ``session/prompt``.
+ open_session: str = ""
+ #: ``_meta`` of ``session/new`` / ``session/load`` (OpenClaw: which
+ #: Gateway session, and whether to reset it) and of ``session/prompt``
+ #: (OpenClaw: this prompt's thinking level).
+ session_meta: dict[str, Any] | None = None
+ prompt_meta: dict[str, Any] | None = None
# --- fields the CLI runner reads after the turn ---
vendor_session: str | None = None
@@ -198,27 +209,28 @@ class AcpTurn:
# ------------------------------------------------------------------ frames
def opening_frame(self) -> str:
- """The ``initialize`` request, written as soon as the process starts."""
- return frame_line(
- {
- "jsonrpc": "2.0",
- "id": _INITIALIZE_ID,
- "method": "initialize",
- "params": {
- "protocolVersion": PROTOCOL_VERSION,
- # No fs / terminal capability: the agent uses its own tools
- # in its own working folder; Jarvis is not an editor.
- "clientCapabilities": {
- "fs": {"readTextFile": False, "writeTextFile": False},
- "terminal": False,
- },
- "clientInfo": {
- "name": self.client_name,
- "version": self.client_version or "0",
- },
- },
- }
- )
+ """The first request, written as soon as the process is there.
+
+ ``initialize`` for a fresh process. On a warm one (``initialized``)
+ the session request, or ``session/prompt`` straight away when the
+ session is already open.
+ """
+ if self.initialized is None:
+ return frame_line(
+ initialize_request(_INITIALIZE_ID, self.client_version, self.client_name)
+ )
+ self._take_initialize(self.initialized)
+ if self.open_session:
+ self._acp_session = self.open_session
+ self.vendor_session = self.report_session or self._acp_session
+ return frame_line(self._prompt_request())
+ request = self._session_request()
+ return frame_line(request) if request is not None else ""
+
+ @property
+ def acp_session(self) -> str:
+ """The ACP session the turn ran in ("" before it opened)."""
+ return self._acp_session
def cancel_frame(self) -> dict[str, Any] | None:
"""The ``session/cancel`` notification for the running prompt (``None`` when
@@ -242,7 +254,38 @@ class AcpTurn:
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]}
+ return session_params(self.cwd, self.mcp_servers, self.session_meta)
+
+ def _take_initialize(self, res: dict[str, Any]) -> None:
+ info = res.get("agentInfo") if isinstance(res.get("agentInfo"), dict) else {}
+ self.agent_name = str(info.get("name") or "")
+ self.agent_version = str(info.get("version") or "")
+ caps = (
+ res.get("agentCapabilities") if isinstance(res.get("agentCapabilities"), dict) else {}
+ )
+ self.can_load = bool(caps.get("loadSession"))
+
+ def _session_request(self) -> dict[str, Any] | None:
+ """``session/load`` or ``session/new``; ``None`` when the turn failed instead."""
+ if self.resume and self.can_load:
+ self._replaying = True
+ params = self._session_params() | {"sessionId": self.resume}
+ return _request(_SESSION_ID, "session/load", params)
+ if self.resume:
+ # The agent cannot reopen conversations: let the runner start
+ # fresh with the transcript in front instead.
+ self._fail(f"{RESUME_LOST_ERROR}: this agent cannot load sessions")
+ return None
+ return _request(_SESSION_ID, "session/new", self._session_params())
+
+ def _prompt_request(self) -> dict[str, Any]:
+ params: dict[str, Any] = {
+ "sessionId": self._acp_session,
+ "prompt": [{"type": "text", "text": self.prompt_text}],
+ }
+ if self.prompt_meta:
+ params["_meta"] = dict(self.prompt_meta)
+ return _request(_PROMPT_ID, "session/prompt", params)
# ---------------------------------------------------------------- dispatch
@@ -268,26 +311,10 @@ class AcpTurn:
if error is not None:
self._fail(f"ACP initialize failed: {_error_text(error)}")
return
- res = result if isinstance(result, dict) else {}
- info = res.get("agentInfo") if isinstance(res.get("agentInfo"), dict) else {}
- self.agent_name = str(info.get("name") or "")
- self.agent_version = str(info.get("version") or "")
- caps = (
- res.get("agentCapabilities")
- if isinstance(res.get("agentCapabilities"), dict)
- else {}
- )
- self.can_load = bool(caps.get("loadSession"))
- if self.resume and self.can_load:
- self._replaying = True
- params = self._session_params() | {"sessionId": self.resume}
- await io.write(_request(_SESSION_ID, "session/load", params))
- elif self.resume:
- # The agent cannot reopen conversations: let the runner start
- # fresh with the transcript in front instead.
- self._fail(f"{RESUME_LOST_ERROR}: this agent cannot load sessions")
- else:
- await io.write(_request(_SESSION_ID, "session/new", self._session_params()))
+ self._take_initialize(result if isinstance(result, dict) else {})
+ request = self._session_request()
+ if request is not None:
+ await io.write(request)
return
if rid == _SESSION_ID:
self._replaying = False
@@ -307,16 +334,7 @@ class AcpTurn:
self._fail("ACP session/new returned no session id")
return
self.vendor_session = self.report_session or self._acp_session
- await io.write(
- _request(
- _PROMPT_ID,
- "session/prompt",
- {
- "sessionId": self._acp_session,
- "prompt": [{"type": "text", "text": self.prompt_text}],
- },
- )
- )
+ await io.write(self._prompt_request())
return
if rid == _PROMPT_ID:
await self._flush_thought(io)
@@ -628,6 +646,37 @@ def _request(rid: int, method: str, params: dict[str, Any]) -> dict[str, Any]:
return {"jsonrpc": "2.0", "id": rid, "method": method, "params": params}
+def initialize_request(
+ rid: int | str, client_version: str = "", client_name: str = "personal-jarvis"
+) -> dict[str, Any]:
+ """The ``initialize`` request (protocol version + client capabilities)."""
+ return {
+ "jsonrpc": "2.0",
+ "id": rid,
+ "method": "initialize",
+ "params": {
+ "protocolVersion": PROTOCOL_VERSION,
+ # No fs / terminal capability: the agent uses its own tools in its
+ # own working folder; Dodaios is not an editor.
+ "clientCapabilities": {
+ "fs": {"readTextFile": False, "writeTextFile": False},
+ "terminal": False,
+ },
+ "clientInfo": {"name": client_name, "version": client_version or "0"},
+ },
+ }
+
+
+def session_params(
+ cwd: str, mcp_servers: list[McpServer], meta: dict[str, Any] | None = None
+) -> dict[str, Any]:
+ """``session/new`` / ``session/load`` parameters."""
+ params: dict[str, Any] = {"cwd": cwd, "mcpServers": [s.to_acp() for s in mcp_servers]}
+ if meta:
+ params["_meta"] = dict(meta)
+ return params
+
+
def frame_line(frame: dict[str, Any]) -> str:
"""One frame as the newline-terminated JSON line ACP expects on stdin."""
return json.dumps(frame, ensure_ascii=False) + "\n"
diff --git a/dodaios/agent_runtimes/base.py b/dodaios/agent_runtimes/base.py
index 2a421713c0..6b8dbc40db 100644
--- a/dodaios/agent_runtimes/base.py
+++ b/dodaios/agent_runtimes/base.py
@@ -27,6 +27,7 @@ import shlex
import shutil
import subprocess
import sys
+import threading
import time
from collections.abc import Callable
from dataclasses import dataclass, field
@@ -165,6 +166,9 @@ class RuntimeTurn:
#: it reasons / it reads images. Never inferred from a provider or model name.
reasoning: bool | None = None
vision: bool | None = None
+ #: Run on the agent's warm process (``warm.WarmPool``). ``False`` for a
+ #: turn whose process runs elsewhere (another computer over SSH).
+ warm: bool = True
@dataclass(slots=True)
@@ -186,13 +190,19 @@ class RuntimeLaunch:
release: Callable[[], None] | None = None
#: Prevent reusing a persistent gateway after an unconfirmed termination.
invalidate: Callable[[], None] | None = None
+ #: The agent's warm process for this turn (``warm.Lease``), already
+ #: initialized; ``None`` = start ``argv``.
+ proc: Any | None = None
+ #: ``_meta`` for ``session/new`` and for ``session/prompt``.
+ session_meta: dict[str, Any] | None = None
+ prompt_meta: dict[str, Any] | None = None
class AgentRuntimeDriver(Protocol):
name: str
label: str
- def detect(self, *, refresh: bool = False) -> RuntimeStatus: ...
+ def detect(self, *, refresh: bool = False, fast: bool = False) -> RuntimeStatus: ...
async def launch(self, turn: RuntimeTurn) -> RuntimeLaunch: ...
@@ -372,16 +382,19 @@ class TurnSlots:
"""Whether any turn holds a slot right now."""
return self.gate.turns > 0 or any(lock.locked() for lock in self._locks.values())
- async def acquire(self, key: str) -> Callable[[], None]:
+ async def acquire(self, key: str, *, wait_s: float | None = None) -> Callable[[], None]:
+ """The slot of ``key``; ``wait_s`` caps every wait (default: minutes)."""
+ slot_wait = _SLOT_WAIT_S if wait_s is None else wait_s
+ home_wait = _HOME_LOCK_WAIT_S if wait_s is None else wait_s
try:
- await self.gate.acquire_turn(_SLOT_WAIT_S)
+ await self.gate.acquire_turn(slot_wait)
except TimeoutError:
raise RuntimeUnavailable(
"Dodaios 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)
+ await asyncio.wait_for(lock.acquire(), timeout=slot_wait)
except TimeoutError:
self.gate.release_turn()
raise RuntimeUnavailable(
@@ -391,7 +404,7 @@ class TurnSlots:
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)
+ await home_lock.acquire(home_wait)
except (TimeoutError, OSError):
lock.release()
self.gate.release_turn()
@@ -642,6 +655,7 @@ class DetectCache:
def __init__(self) -> None:
self._value: RuntimeStatus | None = None
self._at = 0.0
+ self._refreshing = False
def get(self) -> RuntimeStatus | None:
if self._value is not None and time.monotonic() - self._at < _DETECT_TTL_S:
@@ -656,6 +670,31 @@ class DetectCache:
def clear(self) -> None:
self._value = None
+ def stale_ready(self, probe: Callable[[], RuntimeStatus]) -> RuntimeStatus | None:
+ """An expired answer that said *ready*, checked again in the background.
+
+ A turn must not wait for ``--version`` (1-2 s) only because the last
+ check is older than the TTL: the runtime that answered a few minutes
+ ago almost always still does. ``probe`` (``detect(refresh=True)``)
+ replaces the answer when it is done; the next turn sees it.
+ """
+ value = self._value
+ if value is None or not value.ready:
+ return None
+ if not self._refreshing:
+ self._refreshing = True
+
+ def run() -> None:
+ try:
+ probe()
+ except Exception as exc: # noqa: BLE001 - the next turn checks again
+ log.warning("agent runtimes: background runtime check failed: %s", exc)
+ finally:
+ self._refreshing = False
+
+ threading.Thread(target=run, name="runtime-detect", daemon=True).start()
+ return value
+
def persona_text(agent_name: str) -> str:
"""The runtime's own persona file: defer to the Jarvis briefing.
diff --git a/dodaios/agent_runtimes/gateway.py b/dodaios/agent_runtimes/gateway.py
index 0736315069..a8bb2407d9 100644
--- a/dodaios/agent_runtimes/gateway.py
+++ b/dodaios/agent_runtimes/gateway.py
@@ -38,7 +38,7 @@ import threading
import time
import uuid
from collections import OrderedDict
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Iterator
from concurrent.futures import Future
from dataclasses import dataclass, replace
from email.utils import parsedate_to_datetime
@@ -98,6 +98,14 @@ _GRANTS_MAX: Final[int] = 1024
_CLIENTS: dict[str, Any] = {}
_MODEL_LIMITS: dict[Grant, dict[str, ModelLimits]] = {}
_CATALOG: Any = None
+
+#: Catalog facts read for a turn are reused this long: a model's context
+#: window does not change between two messages, and the read (a provider's
+#: model list) sat in front of every turn's first token.
+_METADATA_TTL_S: Final[float] = 15 * 60
+#: ``(provider, account, model)`` -> (read at, catalog facts or ``None``).
+_METADATA: dict[tuple[str, str, str], tuple[float, Any]] = {}
+_METADATA_REFRESH: dict[tuple[str, str, str], asyncio.Task[Any]] = {}
_FAILURES: dict[Grant, Future[str]] = {}
_TURN_EFFORTS: dict[Grant, str] = {}
_COOLDOWNS: OrderedDict[tuple[str, str, str], float] = OrderedDict()
@@ -240,7 +248,41 @@ def model_limits(grant: Grant, model: str) -> ModelLimits:
async def refresh_model_limits(grant: Grant, model: str, config: Any) -> ModelLimits:
- """Read catalog facts only; unavailable metadata keeps the conservative budget."""
+ """Read catalog facts only; unavailable metadata keeps the conservative budget.
+
+ Facts read in the last :data:`_METADATA_TTL_S` answer at once; older
+ ones still answer at once and are read again in the background, so only
+ the very first turn on a model waits for the provider's list.
+ """
+ key = (grant.provider, grant.account_id, model)
+ cached = _METADATA.get(key)
+ if cached is None:
+ found, metadata = await _read_metadata(grant, model)
+ if not found:
+ return await asyncio.to_thread(model_limits, grant, model)
+ else:
+ read_at, metadata = cached
+ if time.monotonic() - read_at > _METADATA_TTL_S and key not in _METADATA_REFRESH:
+ task = asyncio.get_running_loop().create_task(_read_metadata(grant, model))
+ _METADATA_REFRESH[key] = task
+ task.add_done_callback(lambda done: _metadata_refreshed(key, done))
+ 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 _metadata_refreshed(key: tuple[str, str, str], task: asyncio.Task[Any]) -> None:
+ _METADATA_REFRESH.pop(key, None)
+ if not task.cancelled() and task.exception() is not None:
+ # The facts already held keep answering; the next turn tries again.
+ log.warning("runtime gateway: background metadata read failed: %s", task.exception())
+
+
+async def _read_metadata(grant: Grant, model: str) -> tuple[bool, Any]:
+ """``(read, facts)`` from the provider's model list; remembered when read."""
global _CATALOG # one lazy catalog cache; no work on the boot path
from types import SimpleNamespace
@@ -252,7 +294,7 @@ async def refresh_model_limits(grant: Grant, model: str, config: Any) -> ModelLi
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)
+ metadata: Any = SimpleNamespace(**row)
else:
if _CATALOG is None:
_CATALOG = await asyncio.to_thread(ModelCatalog)
@@ -261,13 +303,120 @@ async def refresh_model_limits(grant: Grant, model: str, config: Any) -> ModelLi
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)
+ return False, None
+ _METADATA[(grant.provider, grant.account_id, model)] = (time.monotonic(), metadata)
+ return True, metadata
+
+
+#: Grants in a warm-up run right now (:func:`warming`), with a nesting count.
+_WARMING: dict[Grant, int] = {}
+
+
+def warming(token: str) -> Iterator[None]:
+ """While inside, EVERY model call of this token is answered here.
+
+ A runtime sets its agent loop up lazily on its first run (OpenClaw:
+ seconds per Gateway start). Dodaios runs that first run before the
+ person's message, inside this block: whatever model calls the run makes
+ (the prompt, a retry, anything else) get a fixed reply from the gateway
+ itself. No provider call, nothing billed, no usage recorded. Fail-closed
+ by grant, never by matching prompt text. The caller holds the agent's
+ turn slot, so no turn of the person runs on this token meanwhile.
+ """
+ grant = verify(token)
+ if grant is None:
+ raise GatewayError("Unknown runtime gateway token.", status=401)
+ with _LOCK:
+ _WARMING[grant] = _WARMING.get(grant, 0) + 1
+ try:
+ yield
+ finally:
+ with _LOCK:
+ left = _WARMING.get(grant, 0) - 1
+ if left > 0:
+ _WARMING[grant] = left
+ else:
+ _WARMING.pop(grant, None)
+
+
+def is_warmup(grant: Grant) -> bool:
+ """Whether this grant's model calls belong to a warm-up run (:func:`warming`)."""
+ with _LOCK:
+ return _WARMING.get(grant, 0) > 0
+
+
+#: What a warm-up run's model call is answered with.
+_WARMUP_REPLY: Final[str] = "ok"
+
+
+async def warmup_chat_stream(model: str) -> AsyncIterator[bytes]:
+ chat_id = f"chatcmpl-warmup-{uuid.uuid4().hex}"
+ yield _chunk(chat_id, model, {"role": "assistant", "content": ""})
+ yield _chunk(chat_id, model, {"content": _WARMUP_REPLY})
+ yield _chunk(chat_id, model, {}, finish="stop", usage=_openai_usage({}))
+ yield b"data: [DONE]\n\n"
+
+
+def warmup_chat_completion(model: str) -> dict[str, Any]:
+ return {
+ "id": f"chatcmpl-warmup-{uuid.uuid4().hex}",
+ "object": "chat.completion",
+ "created": int(time.time()),
+ "model": model,
+ "choices": [
+ {
+ "index": 0,
+ "message": {"role": "assistant", "content": _WARMUP_REPLY},
+ "finish_reason": "stop",
+ }
+ ],
+ "usage": _openai_usage({}),
+ }
+
+
+def _warmup_response(model: str) -> tuple[dict[str, Any], dict[str, Any]]:
+ message = {
+ "id": f"msg_warmup_{uuid.uuid4().hex}",
+ "type": "message",
+ "role": "assistant",
+ "status": "completed",
+ "content": [{"type": "output_text", "text": _WARMUP_REPLY, "annotations": []}],
+ }
+ response = {
+ "id": f"resp_warmup_{uuid.uuid4().hex}",
+ "object": "response",
+ "created_at": int(time.time()),
+ "model": model,
+ "status": "completed",
+ "output": [message],
+ "usage": {"input_tokens": 0, "output_tokens": 0, "total_tokens": 0},
+ }
+ return message, response
+
+
+async def warmup_response_stream(model: str) -> AsyncIterator[bytes]:
+ message, response = _warmup_response(model)
+ started = {**response, "status": "in_progress", "output": []}
+ yield _sse({"type": "response.created", "response": started})
+ yield _sse({
+ "type": "response.output_item.added",
+ "output_index": 0,
+ "item": {**message, "status": "in_progress", "content": []},
+ })
+ part = {"item_id": message["id"], "output_index": 0, "content_index": 0}
+ yield _sse({
+ "type": "response.content_part.added", **part,
+ "part": {"type": "output_text", "text": "", "annotations": []},
+ })
+ yield _sse({"type": "response.output_text.delta", **part, "delta": _WARMUP_REPLY})
+ yield _sse({"type": "response.output_text.done", **part, "text": _WARMUP_REPLY})
+ yield _sse({"type": "response.output_item.done", "output_index": 0, "item": message})
+ yield _sse({"type": "response.completed", "response": response})
+
+
+def warmup_response(model: str) -> dict[str, Any]:
+ return _warmup_response(model)[1]
def watch_failure(token: str, *, effort: str = "") -> Future[str]:
@@ -1083,7 +1232,8 @@ async def _deltas(
login: str | None = None
try:
_require_turn(grant, signal)
- secret = get_jarvis_agent_secret(grant.provider)
+ # A keyring read: never on the event loop.
+ secret = await asyncio.to_thread(get_jarvis_agent_secret, grant.provider)
overrides = {grant.provider: secret} if secret else {}
with override_provider_secrets(overrides), usage_context(RUNTIME_CALLER):
on_login, login = await asyncio.to_thread(
@@ -1435,3 +1585,5 @@ def reset() -> None:
_FAILURES.clear()
_TURN_EFFORTS.clear()
_COOLDOWNS.clear()
+ _WARMING.clear()
+ _METADATA.clear()
diff --git a/dodaios/agent_runtimes/hermes.py b/dodaios/agent_runtimes/hermes.py
index 0d287c0aa3..c6958693bf 100644
--- a/dodaios/agent_runtimes/hermes.py
+++ b/dodaios/agent_runtimes/hermes.py
@@ -1,6 +1,8 @@
"""Hermes Agent as a society agent runtime (``docs/agent-runtimes.md``).
-One turn = one ``hermes acp`` process. Every agent is a Hermes *profile* of
+A turn runs on the agent's ``hermes acp`` process, which stays warm
+between turns (``warm.py``): started once, initialized, with the conversation
+open, so a message only costs ``session/prompt``. 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
@@ -81,9 +83,21 @@ _PROFILE_NAME: Final[re.Pattern[str]] = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$"
_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"})
+#: visible browser over MCP), background desktop control, Hermes' own
+#: scheduler (Dodaios owns routines and their budgets) and Hermes' bundled
+#: skill library (Dodaios owns skills on every runtime; its listing alone
+#: was a third of every request's prompt).
+_ALWAYS_DISABLED: Final[frozenset[str]] = frozenset(
+ {"browser", "computer_use", "cronjob", "skills"}
+)
+
+#: A warm-up only runs when the agent's turn slot is free at once.
+_WARM_SLOT_WAIT_S: Final[float] = 0.5
+
+#: A turn's Hermes never installs or syncs dependencies on its own: that
+#: work (up to minutes, before the first token) belongs to the setup job
+#: (:meth:`HermesRuntime.prepare_command`), which runs without this mark.
+_TURN_ENV: Final[dict[str, str]] = {"HERMES_DISABLE_LAZY_INSTALLS": "1"}
#: Effort levels Hermes accepts in ``agent.reasoning_effort``
#: (``hermes_constants.VALID_REASONING_EFFORTS`` plus ``none``).
@@ -226,17 +240,26 @@ class HermesRuntime:
label = LABEL
def __init__(self) -> None:
+ from dodaios.agent_runtimes.warm import WarmPool
+
self._detect = DetectCache()
self._slots = TurnSlots(NAME, lock_dir=lambda: base.runtimes_root() / "locks")
+ self._warm = WarmPool(NAME)
# ----------------------------------------------------------- detection
- def detect(self, *, refresh: bool = False) -> RuntimeStatus:
+ def detect(self, *, refresh: bool = False, fast: bool = False) -> RuntimeStatus:
+ """Installed, version, ready. ``fast`` (a turn): an expired *ready*
+ answer is used and checked again in the background."""
if refresh:
self._detect.clear()
cached = self._detect.get()
if cached is not None:
return cached
+ if fast:
+ stale = self._detect.stale_ready(lambda: self.detect(refresh=True))
+ if stale is not None:
+ return stale
from dodaios.agent_runtimes.path_cleanup import clean_user_path_once
clean_user_path_once()
@@ -358,8 +381,9 @@ class HermesRuntime:
return self._slots.busy()
async def stop(self, agent_id: str | None = None) -> None:
- """Hermes runs one process per turn; nothing stays behind between turns."""
- return
+ """Stop the warm processes of ``agent_id`` (all when ``None``)."""
+ keys = None if agent_id is None else {agent_id, f"{agent_id}~runs"}
+ await self._warm.stop(keys)
# -------------------------------------------------------------- launch
@@ -433,7 +457,7 @@ class HermesRuntime:
return config
async def launch(self, turn: RuntimeTurn) -> RuntimeLaunch:
- status = await asyncio.to_thread(self.detect)
+ status = await asyncio.to_thread(self.detect, fast=True)
if not status.ready:
raise RuntimeUnavailable(status.problem or "Hermes is not ready.")
binary = _binary()
@@ -441,11 +465,64 @@ class HermesRuntime:
raise RuntimeUnavailable("Hermes is not installed.")
release = await self._slots.acquire(home_key(turn.agent_id, turn.session_id))
try:
- return await self._launch(binary, turn, release)
+ launch = await self._launch(binary, turn, release)
+ if turn.warm:
+ launch.proc = await self._warm.lease(
+ home_key(turn.agent_id, turn.session_id), *self._warm_spec(launch, turn)
+ )
+ return launch
except BaseException:
release()
raise
+ async def warm(
+ self, turn: RuntimeTurn, latest_resume: Callable[[], str | None] | None = None
+ ) -> bool:
+ """Start the agent's process and open its conversation before a message.
+
+ Spends no model call. Skipped unless the agent's turn slot is free
+ right now. ``latest_resume`` re-reads the chat's conversation once the
+ slot is held (a turn may have finished since ``turn`` was built).
+ """
+ status = await asyncio.to_thread(self.detect)
+ binary = _binary()
+ if not status.ready or binary is None or self.needs_prepare(status):
+ return False
+ key = home_key(turn.agent_id, turn.session_id)
+ try:
+ release = await self._slots.acquire(key, wait_s=_WARM_SLOT_WAIT_S)
+ except RuntimeUnavailable:
+ return False # a turn (or another warm-up) has the agent right now
+ if latest_resume is not None:
+ turn.resume = latest_resume()
+ try:
+ launch = await self._launch(binary, turn, release)
+ return await self._warm.warm(key, *self._warm_spec(launch, turn))
+ finally:
+ release()
+
+ def _warm_spec(self, launch: RuntimeLaunch, turn: RuntimeTurn) -> tuple[Any, Any]:
+ from dodaios import __version__
+ from dodaios.agent_runtimes.acp import session_params
+ from dodaios.agent_runtimes.warm import SessionWant, WarmSpec, signature
+
+ spec = WarmSpec(
+ argv=launch.argv,
+ env=launch.env,
+ cwd=launch.cwd,
+ # Hermes reads its profile only at start: a changed one restarts.
+ signature=signature(
+ launch.argv, launch.env, str(launch.cwd),
+ self.config_for(turn), self._soul(turn),
+ ),
+ client_version=__version__,
+ )
+ want = SessionWant(
+ resume=launch.acp_resume,
+ params=session_params(str(launch.cwd), launch.mcp_servers),
+ )
+ return spec, want
+
async def _launch(
self, binary: str, turn: RuntimeTurn, release: Callable[[], None]
) -> RuntimeLaunch:
@@ -458,6 +535,7 @@ class HermesRuntime:
"HERMES_HOME": str(home),
# Only the Jarvis server handed over per session; none from config.
"HERMES_ACP_SKIP_CONFIGURED_MCP": "1",
+ **_TURN_ENV,
**turn.route.env(),
**_restore_key_aliases(turn.route.base_url, turn.route.api_key),
}
@@ -492,15 +570,18 @@ class HermesRuntime:
refresh_tool_search_cache(home, turn.resume)
write_json_if_changed(home / "config.yaml", self.config_for(turn))
- write_if_changed(
- home / "SOUL.md",
+ write_if_changed(home / "SOUL.md", self._soul(turn))
+
+ @staticmethod
+ def _soul(turn: RuntimeTurn) -> str:
+ return (
persona_text(turn.agent_name)
+ "Dodaios MCP tools are available through tool_search, tool_describe and "
"tool_call. For a task that needs Dodaios or a connected account, use "
"tool_search with the service and action, read the returned schema, "
"then invoke its exact tool name through tool_call. Search before "
"concluding a capability is missing. For a greeting or ordinary "
- "conversation, reply directly without searching for tools.\n",
+ "conversation, reply directly without searching for tools.\n"
)
diff --git a/dodaios/agent_runtimes/openclaw.py b/dodaios/agent_runtimes/openclaw.py
index 013a79ed68..e924dfc006 100644
--- a/dodaios/agent_runtimes/openclaw.py
+++ b/dodaios/agent_runtimes/openclaw.py
@@ -2,11 +2,12 @@
OpenClaw's documented embedding path is a supervised Gateway child plus its
own clients; Jarvis follows it exactly. Each agent gets its own state folder
-and its own loopback Gateway (started on the agent's first turn, stopped
-after :data:`IDLE_STOP_S` without one), and every turn runs the
-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.
+and its own loopback Gateway (started when the agent's chat is opened or on
+its first turn, stopped after :data:`IDLE_STOP_S` without one), and turns run
+on the version-matched ``openclaw acp`` bridge against it, which stays warm
+between turns (``warm.py``). 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
@@ -71,12 +72,23 @@ LABEL: Final[str] = "OpenClaw"
#: 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
+#: Stop an agent's Gateway after this long without a turn (with its warm
+#: bridge: ``warm.IDLE_STOP_S`` is the same).
+IDLE_STOP_S: Final[float] = 30 * 60
#: How long a Gateway may take to listen (16-46 s measured on Windows).
_START_TIMEOUT_S: Final[float] = 120.0
+#: Gateways kept running at once (about 1.3 GB of memory each); the least
+#: recently used idle one stops for a new one.
+_MAX_GATEWAYS: Final[int] = 3
+
+#: The Gateway session a warm-up run uses, never an agent's conversation.
+_WARMUP_SESSION_KEY: Final[str] = "agent:main:dodaios-warmup"
+
+#: A warm-up only runs when the agent's turn slot is free at once.
+_WARM_SLOT_WAIT_S: Final[float] = 0.5
+
#: How long ``openclaw doctor --fix`` may run before it is stopped.
_DOCTOR_TIMEOUT_S: Final[float] = 120.0
@@ -97,7 +109,8 @@ _EMBED_ENV: Final[dict[str, str]] = {
#: Native tools that duplicate a Jarvis feature (routines, messaging, other
#: devices, the visible browser) and would bypass Jarvis' own approvals and
-#: budgets.
+#: budgets, and tools for OpenClaw's own apps and dashboards no Dodaios agent
+#: has (their schemas were about a quarter of every request).
_ALWAYS_DENIED: Final[tuple[str, ...]] = (
"automations",
"message",
@@ -106,6 +119,17 @@ _ALWAYS_DENIED: Final[tuple[str, ...]] = (
"gateway",
"nodes",
"browser",
+ "skill_workshop",
+ "theme",
+ "dashboard",
+ "mobile_ui",
+ "progress_card",
+ "presence",
+ "portal",
+ "tts",
+ "github_identity_status",
+ "plugins",
+ "node_inference",
)
#: Bundled plugins no Jarvis agent loads: a headless browser, desktop control
@@ -283,6 +307,8 @@ class _Gateway:
last_used: float = field(default_factory=time.monotonic)
in_use: int = 0
poisoned: bool = False
+ #: Its first agent run (seconds of lazy set-up) is done.
+ warmed_up: bool = False
def alive(self) -> bool:
return self.proc.returncode is None
@@ -340,7 +366,10 @@ class OpenClawRuntime:
label = LABEL
def __init__(self) -> None:
+ from dodaios.agent_runtimes.warm import WarmPool
+
self._detect = DetectCache()
+ self._warm = WarmPool(NAME)
self._gateways: dict[str, _Gateway] = {}
self._locks: dict[str, asyncio.Lock] = {}
self._slots = TurnSlots(NAME, lock_dir=lambda: base.runtimes_root() / "locks")
@@ -352,12 +381,18 @@ class OpenClawRuntime:
# ----------------------------------------------------------- detection
- def detect(self, *, refresh: bool = False) -> RuntimeStatus:
+ def detect(self, *, refresh: bool = False, fast: bool = False) -> RuntimeStatus:
+ """Installed, version, ready. ``fast`` (a turn): an expired *ready*
+ answer is used and checked again in the background."""
if refresh:
self._detect.clear()
cached = self._detect.get()
if cached is not None:
return cached
+ if fast:
+ stale = self._detect.stale_ready(lambda: self.detect(refresh=True))
+ if stale is not None:
+ return stale
pin = versions.pin(NAME)
minimum = format_version(pin.minimum)
launcher = _launcher()
@@ -496,6 +531,9 @@ class OpenClawRuntime:
"port": port,
"bind": "loopback",
"auth": {"mode": "token", "token": token},
+ # Nobody opens OpenClaw's own web UI here; building its
+ # assets cost seconds of CPU after every start.
+ "controlUi": {"enabled": False},
},
"models": {"mode": "replace", "providers": {RUNTIME_PROVIDER_NAME: provider}},
"agents": {
@@ -510,7 +548,11 @@ class OpenClawRuntime:
"contextInjection": "never",
}
},
+ # The thinking level travels with each prompt (``_meta.thinking``),
+ # so a changed effort never restarts the Gateway.
"session": {"reset": {"mode": "none"}},
+ # Dodaios pins and updates OpenClaw; no network check per start.
+ "update": {"checkOnStart": False},
# 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.
@@ -530,9 +572,6 @@ class OpenClawRuntime:
# 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 dodaios.agent_chat.dodaios_harness import HEADER_NAME
from dodaios.core.branding import MCP_TOOLS_SERVER_NAME
@@ -557,7 +596,7 @@ class OpenClawRuntime:
# -------------------------------------------------------------- launch
async def launch(self, turn: RuntimeTurn) -> RuntimeLaunch:
- status = await asyncio.to_thread(self.detect)
+ status = await asyncio.to_thread(self.detect, fast=True)
if not status.ready:
raise RuntimeUnavailable(status.problem or "OpenClaw is not ready.")
launcher = _launcher()
@@ -567,10 +606,124 @@ class OpenClawRuntime:
# One turn at a time per Gateway: its config is this turn's.
release_slot = await self._slots.acquire(key)
try:
- return await self._launch(turn, key, launcher, release_slot)
+ launch, gateway = await self._launch(turn, key, launcher, release_slot)
except BaseException:
release_slot()
raise
+ try:
+ if turn.warm:
+ launch.proc = await self._warm.lease(
+ key, *self._warm_spec(key, launch, gateway)
+ )
+ return launch
+ except BaseException:
+ # The launch counts the Gateway as in use; only its release undoes it.
+ if launch.release is not None:
+ launch.release()
+ raise
+
+ async def warm(
+ self, turn: RuntimeTurn, latest_resume: Callable[[], str | None] | None = None
+ ) -> bool:
+ """Start the agent's Gateway and bridge before a message (no paid call).
+
+ The Gateway start is OpenClaw's slow part (16-46 s on Windows); done
+ while the person reads the chat, their message starts at the model.
+ Skipped unless the agent's turn slot is free right now. A warm-up
+ never resets the conversation: a fresh one is reset by its turn.
+ ``latest_resume`` re-reads the chat's conversation once the slot is
+ held (a turn may have finished since ``turn`` was built).
+ """
+ status = await asyncio.to_thread(self.detect)
+ launcher = _launcher()
+ if not status.ready or launcher is None:
+ return False
+ key = home_key(turn.agent_id, turn.session_id)
+ try:
+ release_slot = await self._slots.acquire(key, wait_s=_WARM_SLOT_WAIT_S)
+ except RuntimeUnavailable:
+ return False # a turn (or another warm-up) has the agent right now
+ if latest_resume is not None:
+ turn.resume = latest_resume()
+ try:
+ launch, gateway = await self._launch(turn, key, launcher, release_slot)
+ except BaseException:
+ release_slot()
+ raise
+ try:
+ spec, want = self._warm_spec(key, launch, gateway)
+ if not gateway.warmed_up and turn.route.api_key:
+ gateway.warmed_up = await self._warm_up_run(key, spec, launch, turn)
+ return await self._warm.warm(key, spec, want if turn.resume is not None else None)
+ finally:
+ if launch.release is not None:
+ launch.release()
+
+ async def _warm_up_run(
+ self, key: str, spec: Any, launch: RuntimeLaunch, turn: RuntimeTurn
+ ) -> bool:
+ """The Gateway's first agent run, before the person's message.
+
+ A fresh Gateway sets its agent loop up on its first run (about 6 s on
+ Windows, measured; no setting skips it). This run pays it in a
+ session of its own, and Dodaios' model gateway answers its model call
+ itself (``gateway.warmup_prompt``): no provider call, nothing billed.
+ """
+ from dodaios.agent_runtimes import gateway as model_gateway
+ from dodaios.agent_runtimes.acp import session_params
+
+ token = turn.route.api_key or ""
+ if model_gateway.verify(token) is None:
+ # A route that does not go through Dodaios' model gateway (only
+ # test rigs build one): nothing could stop its call from billing.
+ return False
+ started = time.monotonic()
+ params = session_params(
+ str(launch.cwd), [], {"sessionKey": _WARMUP_SESSION_KEY, "resetSession": True}
+ )
+ with model_gateway.warming(token):
+ done = await self._warm.exercise(key, spec, params, "Reply with: ok")
+ log.info("agent runtimes: OpenClaw warm-up run for %s %s in %.1f s",
+ key, "done" if done else "failed", time.monotonic() - started)
+ return done
+
+ def _warm_spec(
+ self, key: str, launch: RuntimeLaunch, gateway: _Gateway
+ ) -> tuple[Any, Any]:
+ """The bridge's launch and the session a turn wants on it.
+
+ The conversation lives in the Gateway under the agent's session key;
+ ``session/new`` names it (and resets it for a fresh conversation) in
+ its ``_meta``, so one bridge serves every turn of the agent."""
+ from dodaios import __version__
+ from dodaios.agent_runtimes.acp import session_params
+ from dodaios.agent_runtimes.warm import SessionWant, WarmSpec, signature
+
+ spec = WarmSpec(
+ argv=launch.argv,
+ env=launch.env,
+ cwd=launch.cwd,
+ # The bridge belongs to one Gateway run: a restarted Gateway (new
+ # config, new process) gets a new bridge.
+ signature=signature(
+ launch.argv, launch.env, str(launch.cwd), gateway.port, gateway.proc.pid
+ ),
+ client_version=__version__,
+ )
+ meta = launch.session_meta or {}
+ want = SessionWant(
+ resume=None,
+ params=session_params(str(launch.cwd), launch.mcp_servers, meta),
+ # A continued conversation: any open session on its key serves.
+ # A reset one: only a session opened (and reset) for it ahead.
+ bound=not meta.get("resetSession"),
+ # The session a reset turn opened serves the turns after it.
+ match=session_params(
+ str(launch.cwd), launch.mcp_servers,
+ {k: v for k, v in meta.items() if k != "resetSession"},
+ ),
+ )
+ return spec, want
async def _launch(
self,
@@ -578,7 +731,7 @@ class OpenClawRuntime:
key: str,
launcher: list[str],
release_slot: Callable[[], None],
- ) -> RuntimeLaunch:
+ ) -> tuple[RuntimeLaunch, _Gateway]:
home = await asyncio.to_thread(agent_home, NAME, key)
token = await asyncio.to_thread(_gateway_token, home)
gateway_env = child_env(
@@ -603,14 +756,8 @@ class OpenClawRuntime:
f"ws://127.0.0.1:{gateway.port}",
"--token-file",
str(home / "gateway.token"),
- "--session",
- session_key(turn.agent_id, turn.session_id),
]
- if turn.resume is None:
- # A fresh conversation (first turn, rollover): the Jarvis identity
- # and recent transcript lead the prompt, so the old one must go.
- argv.append("--reset-session")
- return RuntimeLaunch(
+ launch = RuntimeLaunch(
argv=argv,
env=child_env({**_EMBED_ENV, **_state_env(home)}),
cwd=turn.workspace,
@@ -618,7 +765,16 @@ class OpenClawRuntime:
vendor_session=session_key(turn.agent_id, turn.session_id),
release=release,
invalidate=lambda: setattr(gateway, "poisoned", True),
+ session_meta={
+ "sessionKey": session_key(turn.agent_id, turn.session_id),
+ # A fresh conversation (first turn, rollover): the Dodaios
+ # identity and recent transcript lead the prompt, so the old
+ # one must go.
+ "resetSession": turn.resume is None,
+ },
+ prompt_meta=prompt_meta(turn),
)
+ return launch, gateway
async def _ensure_gateway(
self,
@@ -653,6 +809,7 @@ class OpenClawRuntime:
await self._stop_gateway(current)
current = None
if current is None:
+ await self._make_room(key)
current = await self._start_gateway(
turn, key, home, port, token, env_hash, launcher, env
)
@@ -665,6 +822,19 @@ class OpenClawRuntime:
def _gateway_lock(self, key: str) -> asyncio.Lock:
return self._locks.setdefault(key, asyncio.Lock())
+ async def _make_room(self, starting: str) -> None:
+ """Stop the least recently used idle Gateway(s) above :data:`_MAX_GATEWAYS`."""
+ idle = [
+ g for k, g in self._gateways.items()
+ if k != starting and g.in_use == 0 and not self._gateway_lock(k).locked()
+ ]
+ while len(self._gateways) >= _MAX_GATEWAYS and idle:
+ oldest = min(idle, key=lambda g: g.last_used)
+ idle.remove(oldest)
+ log.info("agent runtimes: stopping OpenClaw gateway %s for %s", oldest.key, starting)
+ await self._warm.stop({oldest.key})
+ await self._stop_gateway(oldest)
+
async def _start_gateway(
self,
turn: RuntimeTurn,
@@ -760,7 +930,7 @@ class OpenClawRuntime:
break
if await _healthy(port) and proc.returncode is None:
return gateway
- await asyncio.sleep(0.5)
+ await asyncio.sleep(0.1)
except BaseException:
# A cancelled turn (Stop during a cold start) must not leave a
# Gateway behind with the key in its environment.
@@ -820,18 +990,29 @@ class OpenClawRuntime:
idle = time.monotonic() - gateway.last_used
if not gateway.alive() or idle > IDLE_STOP_S:
log.info("agent runtimes: stopping idle OpenClaw gateway %s", key)
+ await self._warm.stop({key})
await self._stop_gateway(gateway)
def busy(self) -> bool:
return self._slots.busy()
async def stop(self, agent_id: str | None = None) -> None:
+ await self._warm.stop(None if agent_id is None else {agent_id, f"{agent_id}~runs"})
for key, gateway in list(self._gateways.items()):
if agent_id is None or key in (agent_id, f"{agent_id}~runs"):
async with self._gateway_lock(key):
await self._stop_gateway(gateway)
+def prompt_meta(turn: RuntimeTurn) -> dict[str, Any] | None:
+ """``session/prompt`` ``_meta``: the agent's thinking level for this prompt.
+
+ Per prompt, not ``thinkingDefault`` in the config: a changed effort then
+ never restarts the Gateway. No level = the model's own default."""
+ thinking = "off" if turn.effort == "none" else turn.effort
+ return {"thinking": thinking} if thinking in _THINKING_LEVELS else None
+
+
def session_key(agent_id: str, chat_session_id: str) -> str:
"""The Gateway session for a chat: the agent's one conversation, or a
separate one per routine run so a run never resets the main chat."""
diff --git a/dodaios/agent_runtimes/warm.py b/dodaios/agent_runtimes/warm.py
new file mode 100644
index 0000000000..42a20637a8
--- /dev/null
+++ b/dodaios/agent_runtimes/warm.py
@@ -0,0 +1,691 @@
+"""Warm ACP processes: an agent's runtime process kept between its turns.
+
+Starting ``hermes acp`` or ``openclaw acp`` costs seconds before the model is
+even asked: an interpreter or Node.js start, imports, the ACP handshake, the
+MCP connection and the session load (measured 4-7 s per turn on Windows).
+A :class:`WarmPool` keeps one process per runtime home instead, already
+initialized and with the agent's conversation open, so a turn only sends
+``session/prompt``. A chat that is opened can start one before the first
+message (:meth:`WarmPool.warm`).
+
+A turn borrows the process through a :class:`Lease`, which looks like a child
+process to the CLI runner: this turn's stdout and stderr lines, a stdin whose
+``close()`` ends the turn (not the process), and ``kill()``, which ends the
+process. A process is only reused with exactly the launch it was started for
+(argv, environment, working folder and the runtime's config files, as
+:attr:`WarmSpec.signature`); anything else retires it and starts a fresh one.
+Idle processes are stopped after :data:`IDLE_STOP_S`, and at most
+:data:`MAX_WARM` are kept per runtime.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import collections
+import contextlib
+import hashlib
+import json
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Final
+
+from dodaios.agent_runtimes.acp import frame_line, initialize_request
+
+log = logging.getLogger(__name__)
+
+#: Stop a warm process after this long without a turn.
+IDLE_STOP_S: Final[float] = 30 * 60
+
+#: Warm processes kept per runtime; the least recently used one goes first.
+MAX_WARM: Final[int] = 6
+
+#: How long a new process may take to answer ``initialize``.
+_HANDSHAKE_TIMEOUT_S: Final[float] = 60.0
+
+#: How long one warm-up step (session open, warm-up run) may take. Short: a
+#: warm-up holds the agent's turn slot, so a message sent meanwhile waits.
+_WARM_STEP_TIMEOUT_S: Final[float] = 45.0
+
+#: One line read from the runtime may be this long (the CLI runner's limit).
+_READLINE_LIMIT: Final[int] = 16 * 1024 * 1024
+
+_INIT_ID: Final[str] = "dodaios-warm-init"
+_SESSION_ID: Final[str] = "dodaios-warm-session"
+_EXERCISE_SESSION_ID: Final[str] = "dodaios-warm-exercise-session"
+_EXERCISE_PROMPT_ID: Final[str] = "dodaios-warm-exercise-prompt"
+
+
+def signature(*parts: Any) -> str:
+ """A stable digest of launch inputs (secrets stay inside the digest)."""
+ blob = json.dumps(parts, sort_keys=True, default=str, ensure_ascii=False)
+ return hashlib.sha256(blob.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class WarmSpec:
+ """Everything one runtime process is started with."""
+
+ argv: list[str]
+ env: dict[str, str]
+ cwd: Path
+ #: Digest of the launch inputs, including the runtime config files the
+ #: process reads only at start.
+ signature: str
+ #: ``initialize``'s ``clientInfo.version``.
+ client_version: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class SessionWant:
+ """The ACP session a turn needs open."""
+
+ #: ``session/load`` id, or ``None`` for a fresh (or runtime-bound) session.
+ resume: str | None
+ #: ``session/new`` / ``session/load`` parameters (``cwd``, ``mcpServers``).
+ params: dict[str, Any]
+ #: An open session serves a turn without ``resume`` too: the runtime keeps
+ #: the conversation by its own key (OpenClaw), not by the ACP session id.
+ bound: bool = False
+ #: What an open session must have been opened with to serve this turn
+ #: (default: ``params``). OpenClaw leaves the one-time reset flag out, so
+ #: the session a reset turn opened serves the turns after it.
+ match: dict[str, Any] | None = None
+
+ @property
+ def key(self) -> str:
+ return signature(self.params if self.match is None else self.match)
+
+
+class _Stream:
+ """The stdout/stderr of one lease: the turn's lines, then EOF."""
+
+ def __init__(self) -> None:
+ self._queue: asyncio.Queue[bytes | BaseException] = asyncio.Queue()
+ self._eof = False
+
+ def feed(self, line: bytes | BaseException) -> None:
+ if not self._eof:
+ self._queue.put_nowait(line)
+
+ def feed_eof(self) -> None:
+ if not self._eof:
+ self._queue.put_nowait(b"")
+ self._eof = True
+
+ async def readline(self) -> bytes:
+ item = await self._queue.get()
+ if isinstance(item, BaseException):
+ raise item
+ if item == b"":
+ # Every later read is EOF too.
+ self._queue.put_nowait(b"")
+ return item
+
+
+class _Stdin:
+ """The lease's stdin: frames go to the runtime; ``close()`` ends the turn."""
+
+ def __init__(self, lease: Lease) -> None:
+ self._lease = lease
+
+ def write(self, data: bytes) -> None:
+ real = self._lease._proc.proc.stdin
+ if self._lease.finished or real is None or real.is_closing():
+ raise BrokenPipeError("the turn is over")
+ real.write(data)
+
+ async def drain(self) -> None:
+ real = self._lease._proc.proc.stdin
+ if real is not None and not self._lease.finished:
+ await real.drain()
+
+ def is_closing(self) -> bool:
+ real = self._lease._proc.proc.stdin
+ return self._lease.finished or real is None or real.is_closing()
+
+ def close(self) -> None:
+ self._lease.finish()
+
+
+class Lease:
+ """One turn on a warm process, shaped like ``asyncio.subprocess.Process``."""
+
+ #: Never a turn-host process (``runner_cli`` reads it).
+ hosted = False
+
+ def __init__(self, pool: WarmPool, proc: _WarmProcess, want: SessionWant) -> None:
+ self._pool = pool
+ self._proc = proc
+ self._want = want
+ self.stdout = _Stream()
+ self.stderr = _Stream()
+ self.stdin = _Stdin(self)
+ self._done = asyncio.Event()
+ self._returncode: int | None = None
+ #: The turn's ``AcpTurn``; read at the end to remember the open session.
+ self.turn: Any = None
+ #: ``initialize`` result of the process (the turn skips the request).
+ self.initialized: dict[str, Any] = dict(proc.initialized or {})
+ #: The ACP session already open with this turn's parameters ("" = none).
+ self.open_session = proc.session_for(want)
+
+ @property
+ def pid(self) -> int:
+ return int(self._proc.proc.pid)
+
+ @property
+ def returncode(self) -> int | None:
+ return self._returncode
+
+ @property
+ def finished(self) -> bool:
+ return self._returncode is not None
+
+ def finish(self) -> None:
+ """The turn is over; the process stays for the next one."""
+ if self.finished:
+ return
+ self._returncode = 0
+ turn = self.turn
+ session = ""
+ if turn is not None and getattr(turn, "saw_result", False):
+ session = str(getattr(turn, "acp_session", "") or "")
+ if getattr(turn, "status", "") != "done" and getattr(turn, "stop_reason", "") != (
+ "cancelled"
+ ):
+ session = "" # an error may have left the session half-way
+ self._end()
+ self._pool._returned(self._proc, self, session, self._want)
+
+ def kill(self) -> None:
+ """End the process itself (Stop, a stalled or failed turn)."""
+ if self.finished:
+ return
+ self._returncode = -9
+ self._end()
+ self._pool._discard(self._proc, "the turn ended it")
+
+ terminate = kill
+
+ def died(self, code: int | None) -> None:
+ if self.finished:
+ return
+ self._returncode = code if code is not None else -1
+ self._end()
+
+ def _end(self) -> None:
+ self.stdout.feed_eof()
+ self.stderr.feed_eof()
+ self._done.set()
+
+ async def wait(self) -> int:
+ await self._done.wait()
+ return int(self._returncode or 0)
+
+
+@dataclass(slots=True)
+class _WarmProcess:
+ key: str
+ spec_signature: str
+ proc: asyncio.subprocess.Process
+ tree: Any
+ tracker: Any
+ initialized: dict[str, Any] | None = None
+ #: The ACP session open in the process and the parameters it was opened with.
+ session: str = ""
+ session_key: str = ""
+ #: The session is a fresh one nobody prompted yet (``session/new`` ahead).
+ session_fresh: bool = False
+ lease: Lease | None = None
+ last_used: float = field(default_factory=time.monotonic)
+ pending: dict[str, asyncio.Future[dict[str, Any]]] = field(default_factory=dict)
+ stderr_tail: collections.deque[str] = field(
+ default_factory=lambda: collections.deque(maxlen=20)
+ )
+ tasks: list[asyncio.Task[None]] = field(default_factory=list)
+
+ def alive(self) -> bool:
+ return self.proc.returncode is None
+
+ def can_load(self) -> bool:
+ caps = (self.initialized or {}).get("agentCapabilities")
+ return isinstance(caps, dict) and bool(caps.get("loadSession"))
+
+ def session_for(self, want: SessionWant) -> str:
+ if not self.session or self.session_key != want.key:
+ return ""
+ if want.resume is not None:
+ return self.session if want.resume == self.session else ""
+ return self.session if (want.bound or self.session_fresh) else ""
+
+
+class WarmPool:
+ """The warm processes of one runtime, by runtime home key."""
+
+ def __init__(self, runtime: str) -> None:
+ self.runtime = runtime
+ self._procs: dict[str, _WarmProcess] = {}
+ self._locks: dict[str, asyncio.Lock] = {}
+ self._reaper: asyncio.Task[None] | None = None
+ #: Processes ended synchronously (:meth:`_discard`) still being reaped.
+ self._draining: set[asyncio.Task[None]] = set()
+
+ def _lock(self, key: str) -> asyncio.Lock:
+ return self._locks.setdefault(key, asyncio.Lock())
+
+ # --------------------------------------------------------------- public
+
+ async def lease(self, key: str, spec: WarmSpec, want: SessionWant) -> Lease | None:
+ """A warm process for this turn (started now when none fits).
+
+ ``None`` = no process could be prepared; the caller starts its turn
+ the ordinary way, whose errors then reach the chat with their reason.
+ Called with the turn slot of ``key`` held.
+ """
+ async with self._lock(key):
+ warm = await self._ready(key, spec)
+ if warm is None:
+ return None
+ if want.resume is not None and not warm.can_load():
+ await self._retire(warm, "it cannot reopen conversations")
+ return None
+ lease = Lease(self, warm, want)
+ warm.lease = lease
+ warm.last_used = time.monotonic()
+ if lease.open_session:
+ warm.session_fresh = False
+ log.info(
+ "agent runtimes: %s turn on a warm process (%s)",
+ self.runtime,
+ "session open" if lease.open_session else "session to open",
+ )
+ return lease
+
+ async def warm(self, key: str, spec: WarmSpec, want: SessionWant | None) -> bool:
+ """Start (or keep) the process for ``key`` and open the session ahead.
+
+ ``want=None``: the process only, no session. Called while nobody runs
+ a turn of ``key`` (the caller holds its turn slot). Spends no model
+ call: only the handshake and the session load.
+ """
+ async with self._lock(key):
+ warm = await self._ready(key, spec)
+ if warm is None:
+ return False
+ if want is None or warm.session_for(want):
+ return True
+ try:
+ await self._open_session(warm, want)
+ except (TimeoutError, OSError, RuntimeError) as exc:
+ log.info("agent runtimes: %s warm-up kept without a session: %s",
+ self.runtime, exc)
+ return warm.alive()
+
+ async def exercise(
+ self, key: str, spec: WarmSpec, params: dict[str, Any], text: str
+ ) -> bool:
+ """One throwaway prompt on the process, in a session of its own.
+
+ Some runtimes set their agent loop up lazily on the first prompt
+ (OpenClaw: seconds per Gateway start). Spent here, before the
+ person's message, it is not in front of their first token. The
+ caller makes sure the model call it causes bills nothing.
+ """
+ async with self._lock(key):
+ warm = await self._ready(key, spec)
+ if warm is None:
+ return False
+ try:
+ opened = await self._request(
+ warm,
+ _EXERCISE_SESSION_ID,
+ _rpc(_EXERCISE_SESSION_ID, "session/new", params),
+ timeout_s=_WARM_STEP_TIMEOUT_S,
+ )
+ session = str(opened.get("sessionId") or "")
+ if not session:
+ return False
+ await self._request(
+ warm,
+ _EXERCISE_PROMPT_ID,
+ _rpc(
+ _EXERCISE_PROMPT_ID,
+ "session/prompt",
+ {"sessionId": session, "prompt": [{"type": "text", "text": text}]},
+ ),
+ timeout_s=_WARM_STEP_TIMEOUT_S,
+ )
+ except (TimeoutError, OSError, RuntimeError) as exc:
+ log.info("agent runtimes: %s warm-up run failed: %s", self.runtime, exc)
+ return False
+ return True
+
+ def has(self, key: str, spec_signature: str | None = None) -> bool:
+ warm = self._procs.get(key)
+ return (
+ warm is not None
+ and warm.alive()
+ and (spec_signature is None or warm.spec_signature == spec_signature)
+ )
+
+ async def stop(self, keys: set[str] | None = None) -> None:
+ """Stop the warm processes of ``keys`` (all when ``None``)."""
+ for key, warm in list(self._procs.items()):
+ if keys is None or key in keys:
+ async with self._lock(key):
+ if self._procs.get(key) is warm:
+ await self._retire(warm, "stopped")
+ if self._draining:
+ await asyncio.gather(*list(self._draining), return_exceptions=True)
+
+ # -------------------------------------------------------------- process
+
+ async def _ready(self, key: str, spec: WarmSpec) -> _WarmProcess | None:
+ warm = self._procs.get(key)
+ if warm is not None and warm.lease is not None and not warm.lease.finished:
+ return None # a turn still owns it (never with the slot held)
+ if warm is not None and (
+ not warm.alive() or warm.spec_signature != spec.signature or warm.initialized is None
+ ):
+ reason = (
+ "it exited" if not warm.alive()
+ else "its launch changed" if warm.spec_signature != spec.signature
+ else "its handshake never finished"
+ )
+ await self._retire(warm, reason)
+ warm = None
+ if warm is None:
+ await self._make_room()
+ warm = await self._spawn(key, spec)
+ return warm
+
+ async def _spawn(self, key: str, spec: WarmSpec) -> _WarmProcess | None:
+ from dodaios.core.process_tree import (
+ TURN_MARKER_ENV,
+ DescendantTracker,
+ make_process_tree,
+ )
+ from dodaios.core.process_utils import NO_WINDOW_CREATIONFLAGS
+
+ env = dict(spec.env)
+ marker = ""
+ if os.name != "nt":
+ # Descendants that detach are still found by this mark (POSIX).
+ from uuid import uuid4
+
+ marker = uuid4().hex
+ env[TURN_MARKER_ENV] = marker
+ tree = make_process_tree(f"{self.runtime}-warm-{key}")
+ started = time.monotonic()
+ try:
+ proc = await asyncio.create_subprocess_exec(
+ *spec.argv,
+ cwd=str(spec.cwd),
+ env=env,
+ stdin=asyncio.subprocess.PIPE,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ creationflags=NO_WINDOW_CREATIONFLAGS,
+ start_new_session=os.name != "nt",
+ limit=_READLINE_LIMIT,
+ )
+ except (OSError, ValueError) as exc:
+ tree.close()
+ log.info("agent runtimes: %s warm process did not start: %s", self.runtime, exc)
+ return None
+ tree.assign(proc.pid)
+ tracker = DescendantTracker(proc.pid, interval_s=5.0, marker=marker or None)
+ tracker.start()
+ warm = _WarmProcess(key, spec.signature, proc, tree, tracker)
+ warm.tasks = [
+ asyncio.create_task(self._read_stdout(warm)),
+ asyncio.create_task(self._read_stderr(warm)),
+ ]
+ self._procs[key] = warm
+ self._ensure_reaper()
+ try:
+ result = await self._request(
+ warm, _INIT_ID, initialize_request(_INIT_ID, spec.client_version)
+ )
+ except (TimeoutError, OSError, RuntimeError) as exc:
+ tail = " | ".join(list(warm.stderr_tail)[-3:])
+ log.info("agent runtimes: %s warm process failed its handshake: %s %s",
+ self.runtime, exc, tail)
+ await self._retire(warm, "its handshake failed")
+ return None
+ except BaseException:
+ # Cancelled mid-handshake (Stop, app shutdown): never leave a
+ # half-started process for the next turn to pick up.
+ self._discard(warm, "its start was cancelled")
+ raise
+ warm.initialized = result
+ log.info(
+ "agent runtimes: %s warm process for %s ready in %.1f s",
+ self.runtime, key, time.monotonic() - started,
+ )
+ return warm
+
+ async def _open_session(self, warm: _WarmProcess, want: SessionWant) -> None:
+ params = dict(want.params)
+ if want.resume is not None:
+ if not warm.can_load():
+ return
+ result = await self._request(
+ warm, _SESSION_ID,
+ _rpc(_SESSION_ID, "session/load", params | {"sessionId": want.resume}),
+ timeout_s=_WARM_STEP_TIMEOUT_S,
+ )
+ if not result:
+ raise RuntimeError("the conversation could not be reopened")
+ warm.session, warm.session_fresh = want.resume, False
+ else:
+ result = await self._request(
+ warm, _SESSION_ID, _rpc(_SESSION_ID, "session/new", params),
+ timeout_s=_WARM_STEP_TIMEOUT_S,
+ )
+ session = str(result.get("sessionId") or "")
+ if not session:
+ raise RuntimeError("session/new returned no session id")
+ warm.session, warm.session_fresh = session, True
+ warm.session_key = want.key
+
+ async def _request(
+ self,
+ warm: _WarmProcess,
+ rid: str,
+ frame: dict[str, Any],
+ *,
+ timeout_s: float = _HANDSHAKE_TIMEOUT_S,
+ ) -> dict[str, Any]:
+ stdin = warm.proc.stdin
+ if stdin is None:
+ raise RuntimeError("no stdin")
+ future: asyncio.Future[dict[str, Any]] = asyncio.get_running_loop().create_future()
+ warm.pending[rid] = future
+ try:
+ stdin.write(frame_line(frame).encode("utf-8"))
+ await stdin.drain()
+ return await asyncio.wait_for(future, timeout=timeout_s)
+ finally:
+ warm.pending.pop(rid, None)
+
+ async def _read_stdout(self, warm: _WarmProcess) -> None:
+ stream = warm.proc.stdout
+ assert stream is not None
+ while True:
+ try:
+ raw = await stream.readline()
+ except ValueError as exc:
+ if warm.lease is not None and not warm.lease.finished:
+ warm.lease.stdout.feed(exc)
+ continue
+ log.info("agent runtimes: %s warm process sent an oversized line", self.runtime)
+ continue
+ if not raw:
+ break
+ lease = warm.lease
+ if lease is not None and not lease.finished:
+ lease.stdout.feed(raw)
+ continue
+ self._answer(warm, raw)
+ code = await warm.proc.wait()
+ if warm.lease is not None and len(warm.tasks) > 1:
+ # The turn reports why the process ended from its stderr: let the
+ # last lines arrive before the turn's streams close.
+ with contextlib.suppress(TimeoutError):
+ await asyncio.wait_for(asyncio.shield(warm.tasks[1]), timeout=2)
+ for future in warm.pending.values():
+ if not future.done():
+ future.set_exception(RuntimeError(f"the process exited ({code})"))
+ if warm.lease is not None:
+ warm.lease.died(code)
+ if self._procs.get(warm.key) is warm and warm.lease is None:
+ log.info("agent runtimes: %s warm process for %s exited (%s)",
+ self.runtime, warm.key, code)
+
+ def _answer(self, warm: _WarmProcess, raw: bytes) -> None:
+ """A line outside any turn: the pool's own requests, else dropped."""
+ try:
+ obj = json.loads(raw)
+ except ValueError: # runtime diagnostics between turns are not ACP frames
+ return
+ if not isinstance(obj, dict):
+ return
+ future = warm.pending.get(str(obj.get("id"))) if "method" not in obj else None
+ if future is not None and not future.done():
+ if isinstance(obj.get("error"), dict):
+ message = str(obj["error"].get("message") or "error")
+ future.set_exception(RuntimeError(message))
+ else:
+ result = obj.get("result")
+ future.set_result(result if isinstance(result, dict) else {})
+ return
+ if "method" in obj and obj.get("id") is not None:
+ # A request with no turn to answer it (a late permission ask).
+ reply = {
+ "jsonrpc": "2.0",
+ "id": obj.get("id"),
+ "error": {"code": -32601, "message": "no turn is running"},
+ }
+ stdin = warm.proc.stdin
+ if stdin is not None and not stdin.is_closing():
+ with contextlib.suppress(OSError, RuntimeError):
+ stdin.write(frame_line(reply).encode("utf-8"))
+
+ async def _read_stderr(self, warm: _WarmProcess) -> None:
+ stream = warm.proc.stderr
+ assert stream is not None
+ while True:
+ try:
+ raw = await stream.readline()
+ except ValueError:
+ continue # one oversized diagnostic line: dropped
+ if not raw:
+ return
+ lease = warm.lease
+ if lease is not None and not lease.finished:
+ lease.stderr.feed(raw)
+ else:
+ text = raw.decode("utf-8", errors="replace").rstrip()
+ if text:
+ warm.stderr_tail.append(text)
+
+ # ------------------------------------------------------------ lifecycle
+
+ def _returned(
+ self, warm: _WarmProcess, lease: Lease, session: str, want: SessionWant
+ ) -> None:
+ if warm.lease is lease:
+ warm.lease = None
+ warm.last_used = time.monotonic()
+ if session and warm.alive():
+ warm.session, warm.session_key, warm.session_fresh = session, want.key, False
+ else:
+ warm.session, warm.session_key, warm.session_fresh = "", "", False
+
+ def _discard(self, warm: _WarmProcess, reason: str) -> None:
+ """Synchronous retire, for a lease killed from a timer or callback."""
+ if self._procs.get(warm.key) is warm:
+ del self._procs[warm.key]
+ _kill_now(warm)
+ with contextlib.suppress(RuntimeError): # no running loop: nothing to reap on
+ task = asyncio.get_running_loop().create_task(_drained(warm))
+ self._draining.add(task)
+ task.add_done_callback(self._draining.discard)
+ log.info("agent runtimes: %s warm process for %s ended: %s",
+ self.runtime, warm.key, reason)
+
+ async def _retire(self, warm: _WarmProcess, reason: str) -> None:
+ if self._procs.get(warm.key) is warm:
+ del self._procs[warm.key]
+ if warm.lease is not None:
+ warm.lease.died(-9)
+ stdin = warm.proc.stdin
+ if warm.proc.returncode is None and stdin is not None and not stdin.is_closing():
+ # An ACP agent ends when its stdin closes; give it a moment.
+ stdin.close()
+ try:
+ await asyncio.wait_for(warm.proc.wait(), timeout=3)
+ except TimeoutError:
+ log.debug("agent runtimes: %s warm process ignored EOF", self.runtime)
+ _kill_now(warm)
+ await _drained(warm)
+ log.info("agent runtimes: %s warm process for %s stopped: %s",
+ self.runtime, warm.key, reason)
+
+ async def _make_room(self) -> None:
+ # Only idle processes whose key nobody is working on right now.
+ idle = [
+ w for w in self._procs.values()
+ if w.lease is None and not self._lock(w.key).locked()
+ ]
+ while len(self._procs) >= MAX_WARM and idle:
+ oldest = min(idle, key=lambda w: w.last_used)
+ idle.remove(oldest)
+ await self._retire(oldest, "too many warm processes")
+
+ def _ensure_reaper(self) -> None:
+ if self._reaper is None or self._reaper.done():
+ self._reaper = asyncio.get_running_loop().create_task(self._reap_idle())
+
+ async def _reap_idle(self) -> None:
+ while self._procs:
+ await asyncio.sleep(60)
+ now = time.monotonic()
+ for key, warm in list(self._procs.items()):
+ if warm.lease is not None:
+ continue
+ if not warm.alive() or now - warm.last_used > IDLE_STOP_S:
+ async with self._lock(key):
+ if self._procs.get(key) is warm and warm.lease is None:
+ await self._retire(warm, "idle")
+
+
+def _kill_now(warm: _WarmProcess) -> None:
+ if warm.proc.returncode is None:
+ with contextlib.suppress(ProcessLookupError, OSError):
+ warm.proc.kill()
+ # Whatever the runtime started (MCP servers, shell children) goes with it.
+ warm.tree.close()
+ warm.tracker.close()
+
+
+async def _drained(warm: _WarmProcess) -> None:
+ """Wait for a killed process and its pipe readers, so no pipe outlives them."""
+ with contextlib.suppress(TimeoutError, ProcessLookupError, OSError):
+ await asyncio.wait_for(warm.proc.wait(), timeout=5)
+ readers = [task for task in warm.tasks if task is not asyncio.current_task()]
+ if not readers:
+ return
+ _done, pending = await asyncio.wait(readers, timeout=2)
+ for task in pending:
+ task.cancel()
+ if pending:
+ await asyncio.gather(*pending, return_exceptions=True)
+
+
+def _rpc(rid: str, method: str, params: dict[str, Any]) -> dict[str, Any]:
+ return {"jsonrpc": "2.0", "id": rid, "method": method, "params": params}
diff --git a/dodaios/ui/web/agent_chat_routes.py b/dodaios/ui/web/agent_chat_routes.py
index 75d2c56cf6..b5cada7bb5 100644
--- a/dodaios/ui/web/agent_chat_routes.py
+++ b/dodaios/ui/web/agent_chat_routes.py
@@ -1249,6 +1249,47 @@ async def post_message(session_id: str, body: MessageBody, request: Request) ->
return {"turn_id": turn_id, "session_id": session_id}
+#: Warm-ups in flight, by chat session (one at a time; kept so they finish).
+_WARMING: dict[str, asyncio.Task[bool]] = {}
+
+
+ "/sessions/{session_id}/warm",
+ summary="Get a Hermes or OpenClaw agent ready before the next message",
+ description=(
+ "Starts the agent's runtime process and opens its conversation in the "
+ "background, so the message that follows answers without a start-up wait. "
+ "Makes no model call. A no-op for every other chat."
+ ),
+)
+async def warm_session(session_id: str, request: Request) -> dict[str, Any]:
+ 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")
+ if session.surface != "society" or not session.runtime:
+ return {"warming": False, "session_id": session_id}
+ running = _WARMING.get(session_id)
+ if running is None and not svc.is_running(session_id):
+ from dodaios.agent_chat.runner_acp import warm_session as warm
+
+ task = asyncio.create_task(
+ warm(session, svc.store), name=f"agent-runtime-warm-{session_id}"
+ )
+ _WARMING[session_id] = task
+
+ def done(finished: asyncio.Task[bool]) -> None:
+ _WARMING.pop(session_id, None)
+ if not finished.cancelled() and finished.exception() is not None:
+ log.warning(
+ "agent chat %s: runtime warm-up failed: %s", session_id, finished.exception()
+ )
+
+ task.add_done_callback(done)
+ running = task
+ return {"warming": running is not None, "session_id": session_id}
+
+
@router.post(
"/sessions/{session_id}/cancel",
summary="Stop the turn this chat session is running",
diff --git a/dodaios/ui/web/frontend/src/components/society/chat/AgentChatPanel.tsx b/dodaios/ui/web/frontend/src/components/society/chat/AgentChatPanel.tsx
index e5448445d5..d9fc7987a8 100644
--- a/dodaios/ui/web/frontend/src/components/society/chat/AgentChatPanel.tsx
+++ b/dodaios/ui/web/frontend/src/components/society/chat/AgentChatPanel.tsx
@@ -69,7 +69,7 @@ import { useRunLocale } from "@/components/runs/format";
import { cn } from "@/lib/utils";
import { societyDisplayName } from "@/lib/societyDisplayName";
import { createAgentChatStore, useAgentChatStore, type AgentChatStoreHook } from "@/store/agentChat";
-import type { AgentChatSurface, ApprovalDecision } from "@/lib/agentChatApi";
+import { warmAgentChatSession, type AgentChatSurface, type ApprovalDecision } from "@/lib/agentChatApi";
import { offeredModels, useSavedHiddenModels } from "@/lib/agentProviderPrefs";
import { AgentSwatch, agentColor } from "../AgentSwatch";
@@ -270,6 +270,9 @@ function SpecialistChat({ agent, roster, composerExtras }: AgentChatPanelProps)
useLayoutEffect(() => {
if (!sessionId) return;
openSession(sessionId);
+ // An agent on Hermes or OpenClaw starts its runtime while its chat is
+ // read, not after the first message is sent.
+ warmAgentChatSession(sessionId);
}, [sessionId, openSession]);
useEffect(() => {
diff --git a/dodaios/ui/web/frontend/src/lib/agentChatApi.ts b/dodaios/ui/web/frontend/src/lib/agentChatApi.ts
index e6b3c898b6..0098b7a5ca 100644
--- a/dodaios/ui/web/frontend/src/lib/agentChatApi.ts
+++ b/dodaios/ui/web/frontend/src/lib/agentChatApi.ts
@@ -462,6 +462,27 @@ export async function fetchAgentChatSession(
);
}
+/**
+ * Get a Hermes or OpenClaw agent ready before its next message: the backend
+ * starts the agent's runtime and opens its conversation in the background
+ * (no model call), so the reply starts without a start-up wait. Any other
+ * chat answers with a no-op. Fire and forget: a failed warm-up only means the
+ * next message pays the start-up itself.
+ */
+export function warmAgentChatSession(sessionId: string): void {
+ // Once a minute per chat at most: a remount or a second panel on the same
+ // chat finds the runtime warm already.
+ const now = Date.now();
+ if (now - (lastWarm.get(sessionId) ?? 0) < WARM_COOLDOWN_MS) return;
+ lastWarm.set(sessionId, now);
+ void fetch(`/api/agent-chat/sessions/${encodeURIComponent(sessionId)}/warm`, {
+ method: "POST",
+ }).catch(() => undefined);
+}
+
+const WARM_COOLDOWN_MS = 60_000;
+const lastWarm = new Map<string, number>();
+
export async function sendAgentChatMessage(
sessionId: string,
text: string,
diff --git a/dodaios/ui/web/runtime_gateway_routes.py b/dodaios/ui/web/runtime_gateway_routes.py
index ed39071274..e3798ced7f 100644
--- a/dodaios/ui/web/runtime_gateway_routes.py
+++ b/dodaios/ui/web/runtime_gateway_routes.py
@@ -51,12 +51,23 @@ async def runtime_gateway_chat(request: Request) -> Any:
"""One model call for a Hermes / OpenClaw agent, on its Dodaios provider."""
grant = _grant(request)
try:
- lease = gateway.capture_turn(grant)
+ # The runtime's warm-up run holds the agent's turn slot without a
+ # turn of the person: answered here, no provider call, nothing billed.
+ warmup = gateway.is_warmup(grant)
+ lease = None if warmup else gateway.capture_turn(grant)
if grant.provider == gateway.SUBSCRIPTION_PROVIDER:
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)
+ if warmup:
+ if body.get("stream") is True:
+ return StreamingResponse(
+ gateway.warmup_chat_stream(model),
+ media_type="text/event-stream",
+ headers={"Cache-Control": "no-cache"},
+ )
+ return gateway.warmup_chat_completion(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:
@@ -78,12 +89,22 @@ async def runtime_gateway_responses(request: Request) -> Any:
"""One model turn for a Hermes / OpenClaw agent, on its ChatGPT subscription."""
grant = _grant(request)
try:
- lease = gateway.capture_turn(grant)
+ # A warm-up run: answered here (see ``runtime_gateway_chat``).
+ warmup = gateway.is_warmup(grant)
+ lease = None if warmup else gateway.capture_turn(grant)
if grant.provider != gateway.SUBSCRIPTION_PROVIDER:
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 warmup:
+ if body.get("stream") is True:
+ return StreamingResponse(
+ gateway.warmup_response_stream(args["model"]),
+ media_type="text/event-stream",
+ headers={"Cache-Control": "no-cache"},
+ )
+ return gateway.warmup_response(args["model"])
if body.get("stream") is True:
events = await gateway.open_response_stream(grant, args, lease=lease)
return StreamingResponse(
diff --git a/scripts/spikes/agent_runtimes_e2e.py b/scripts/spikes/agent_runtimes_e2e.py
index 3cfbb23644..96ee0bfe2f 100644
--- a/scripts/spikes/agent_runtimes_e2e.py
+++ b/scripts/spikes/agent_runtimes_e2e.py
@@ -36,9 +36,12 @@ from tests.fakes.fake_openai_server import MODEL_ID, FakeOpenAIServer # noqa: E
class _IO:
- def __init__(self, proc: asyncio.subprocess.Process) -> None:
+ def __init__(self, proc: Any) -> None:
self.proc = proc
self.events: list[dict[str, Any]] = []
+ self.started = time.monotonic()
+ #: Seconds from the turn's start to its first answer text.
+ self.first_text_s: float | None = None
async def write(self, frame: dict[str, Any]) -> None:
assert self.proc.stdin is not None
@@ -46,6 +49,8 @@ class _IO:
await self.proc.stdin.drain()
async def emit(self, event: dict[str, Any]) -> None:
+ if self.first_text_s is None and event.get("kind") in ("text_delta", "assistant_text"):
+ self.first_text_s = time.monotonic() - self.started
self.events.append(event)
async def ask(self, call_id: str, name: str, args: dict[str, Any], summary: str) -> str:
@@ -53,8 +58,11 @@ class _IO:
async def _run(name: str, turn: RuntimeTurn, text: str) -> tuple[AcpTurn, _IO]:
+ """One turn the way the CLI runner drives it: on the agent's warm process
+ when the driver hands one over (``launch.proc``), else a fresh one."""
from dodaios.agent_runtimes import gateway
+ started = time.monotonic()
runtime = driver(name)
launch = await runtime.launch(turn)
acp = AcpTurn(
@@ -65,9 +73,15 @@ async def _run(name: str, turn: RuntimeTurn, text: str) -> tuple[AcpTurn, _IO]:
mcp_servers=launch.mcp_servers,
auto_allow=True,
report_session=launch.vendor_session,
+ session_meta=launch.session_meta,
+ prompt_meta=launch.prompt_meta,
)
+ if launch.proc is not None:
+ acp.initialized = launch.proc.initialized
+ acp.open_session = launch.proc.open_session
+ launch.proc.turn = acp
tree = make_process_tree("runtime-e2e")
- proc = None
+ proc = launch.proc
failure = None
token = turn.route.api_key or ""
try:
@@ -75,19 +89,21 @@ async def _run(name: str, turn: RuntimeTurn, text: str) -> tuple[AcpTurn, _IO]:
# Match the chat runner's ownership of each model-gateway turn.
failure = gateway.watch_failure(token, effort=turn.effort or "")
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)
+ if proc is None:
+ 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)
+ io.started = started
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()
@@ -124,6 +140,11 @@ async def _run(name: str, turn: RuntimeTurn, text: str) -> tuple[AcpTurn, _IO]:
launch.release()
+def _report(label: str, io: _IO) -> None:
+ first = f"{io.first_text_s:.2f} s" if io.first_text_s is not None else "never"
+ print(f"{label}: first answer text after {first}")
+
+
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():
@@ -250,6 +271,18 @@ 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")
+ _report("turn 1 (cold)", io1)
+ _report("turn 2 (warm process)", io2)
+ # The app restarted (or the agent idled out): the chat is opened, the
+ # runtime warms up while it is read, then the message is sent.
+ await driver(name).stop()
+ turn.resume = second.vendor_session
+ warmed = time.monotonic()
+ ready = await driver(name).warm(turn)
+ print(f"warm-up: {ready} in {time.monotonic() - warmed:.1f} s")
+ third, io3 = await _run(name, turn, "third message")
+ print("turn 3:", third.status, third.error, repr(third.result_text[:80]))
+ _report("turn 3 (after warm-up)", io3)
# Stopped first: a running Gateway holds some of its files open.
await driver(name).stop()
secret_leak = _key_on_disk(tmp / "agent_runtimes", key)
@@ -260,6 +293,7 @@ async def main(name: str) -> int:
ok = (
first.status == "done"
and second.status == "done"
+ and third.status == "done"
and history > 2
and not secret_leak
and path_kept
diff --git a/scripts/spikes/agent_runtimes_gateway_e2e.py b/scripts/spikes/agent_runtimes_gateway_e2e.py
index 3feeac1f3d..de4ce5dca8 100644
--- a/scripts/spikes/agent_runtimes_gateway_e2e.py
+++ b/scripts/spikes/agent_runtimes_gateway_e2e.py
@@ -34,6 +34,7 @@ sys.path.insert(0, str(ROOT))
sys.path.insert(0, str(ROOT / "scripts" / "spikes"))
from agent_runtimes_e2e import ( # noqa: E402
+ _report,
_run,
keep_user_path,
prepare,
@@ -288,12 +289,24 @@ async def _turns(name, provider, wanted, workspace, port, *, replay):
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.")
+ second, io2 = await _run(name, turn, "Which word did I ask you to remember? One word.")
print("turn 2:", second.status, second.error, repr(second.result_text[:120]))
+ _report("turn 2 (warm process)", io2)
+ # The app restarted: the chat is opened, the runtime warms up (OpenClaw:
+ # Gateway, bridge and a warm-up run answered by the gateway itself).
+ await driver(name).stop()
+ turn.resume = second.vendor_session
+ warmed = time.monotonic()
+ ready = await driver(name).warm(turn)
+ print(f"warm-up: {ready} in {time.monotonic() - warmed:.1f} s")
+ third, io3 = await _run(name, turn, "Which word did I ask you to remember? One word.")
+ print("turn 3:", third.status, third.error, repr(third.result_text[:120]))
+ _report("turn 3 (after warm-up)", io3)
await driver(name).stop()
ok = (
first.status == "done"
and second.status == "done"
+ and third.status == "done"
and "pelican" in second.result_text.lower()
)
print("RESULT:", "PASS" if ok else "FAIL")
diff --git a/tests/unit/agent_chat/test_agent_chat_service.py b/tests/unit/agent_chat/test_agent_chat_service.py
index 8618eca452..acdb5edbd8 100644
--- a/tests/unit/agent_chat/test_agent_chat_service.py
+++ b/tests/unit/agent_chat/test_agent_chat_service.py
@@ -900,3 +900,36 @@ def test_a_new_process_closes_turns_a_restart_left_open(tmp_path: Path) -> None:
finished = [e for e in store.list_events(done_chat.session_id) if e["kind"] == "turn_finished"]
assert len(finished) == 1
assert store.open_turns() == []
+
+
+def test_opening_a_runtime_agents_chat_warms_its_runtime(tmp_path: Path, monkeypatch):
+ """POST /warm starts a Hermes/OpenClaw agent's process ahead of the message;
+ every other chat answers with a no-op."""
+ from dodaios.agent_chat import runner_acp
+
+ warmed: list[str] = []
+
+ async def fake_warm(session, store=None) -> bool:
+ assert store is not None # the turn slot re-reads the conversation id
+ warmed.append(session.session_id)
+ return True
+
+ monkeypatch.setattr(runner_acp, "warm_session", fake_warm)
+ app = _app(tmp_path)
+ with TestClient(app) as client:
+ svc = app.state.agent_chat_factory()
+ app.state.agent_chat = svc
+ plain = svc.store.create_session(
+ provider="fakeprov", model="m", effort="", cwd=str(tmp_path)
+ )
+ agent = svc.store.create_session(
+ provider="ollama", model="m", effort="", cwd=str(tmp_path),
+ session_id="society:hermit", surface="society", runtime="hermes",
+ )
+ assert client.post(f"/api/agent-chat/sessions/{plain.session_id}/warm").json() == {
+ "warming": False, "session_id": plain.session_id,
+ }
+ answer = client.post(f"/api/agent-chat/sessions/{agent.session_id}/warm").json()
+ assert answer["warming"] is True
+ assert client.post("/api/agent-chat/sessions/nope/warm").status_code == 404
+ assert warmed == ["society:hermit"]
diff --git a/tests/unit/agent_runtimes/test_acp_runner.py b/tests/unit/agent_runtimes/test_acp_runner.py
index ea7ad5b398..7ae1bcbdaa 100644
--- a/tests/unit/agent_runtimes/test_acp_runner.py
+++ b/tests/unit/agent_runtimes/test_acp_runner.py
@@ -308,7 +308,7 @@ def test_gateway_failure_ends_the_real_acp_runner_and_recovery_keeps_the_questio
class Driver:
label = "Fake runtime"
- def detect(self):
+ def detect(self, **_kw):
return RuntimeStatus("hermes", self.label, installed=True, ready=True)
async def launch(self, turn):
diff --git a/tests/unit/agent_runtimes/test_runtime_configs.py b/tests/unit/agent_runtimes/test_runtime_configs.py
index 88d579e778..f0d2377abe 100644
--- a/tests/unit/agent_runtimes/test_runtime_configs.py
+++ b/tests/unit/agent_runtimes/test_runtime_configs.py
@@ -555,9 +555,15 @@ def test_hermes_writes_the_agents_effort(tmp_path, 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
+def test_openclaw_sends_the_agents_thinking_with_each_prompt(tmp_path, effort, expected):
+ from dodaios.agent_runtimes import openclaw
+
+ turn = _turn(tmp_path, effort=effort)
+ meta = openclaw.prompt_meta(turn)
+ assert (meta or {}).get("thinking") == expected
+ # Never in the config: a changed effort must not restart the Gateway.
+ config = OpenClawRuntime().config_for(turn, port=1, token=_TOKEN)
+ assert "thinkingDefault" not in config["agents"]["defaults"]
@pytest.mark.parametrize(
diff --git a/tests/unit/agent_runtimes/test_runtime_gateway.py b/tests/unit/agent_runtimes/test_runtime_gateway.py
index 8591d39f70..5fdca0773a 100644
--- a/tests/unit/agent_runtimes/test_runtime_gateway.py
+++ b/tests/unit/agent_runtimes/test_runtime_gateway.py
@@ -888,3 +888,75 @@ def test_vertex_runs_on_a_cloud_project_without_a_key(monkeypatch) -> None:
monkeypatch.setattr(config, "vertex_credential_configured", lambda *a: True)
assert model_map._checked_model(cfg, "vertex", "gemini-3-pro") == "gemini-3-pro"
+
+
+# --------------------------------------------------------------- warm-up runs
+
+
+def test_a_warm_up_run_is_answered_here_without_a_provider_call(fake, brain, guarded) -> None:
+ """While a runtime's warm-up run is in progress (its first agent run, before
+ the person's message), EVERY model call of that agent's token gets a fixed
+ reply from the gateway itself, whatever its prompt: nothing is billed."""
+ sub = gateway.grant_token("agent-1", "openai-codex")
+ key = gateway.grant_token("agent-1", "openai")
+ with gateway.warming(sub), gateway.warming(key):
+ answer = _post(guarded, sub, {
+ "model": "gpt-5.6-sol", "stream": True,
+ "input": [{"role": "user", "content": [{"type": "input_text", "text": "hi"}]}],
+ })
+ assert answer.status_code == 200, answer.text
+ frames = [
+ json.loads(line[5:]) for line in answer.text.splitlines() if line.startswith("data:")
+ ]
+ assert frames[0]["type"] == "response.created"
+ assert frames[-1]["type"] == "response.completed"
+ assert [f["delta"] for f in frames if f["type"] == "response.output_text.delta"] == ["ok"]
+ assert _post(guarded, sub, {"model": "gpt-5.6-sol", "input": "x"}).json()["status"] == (
+ "completed"
+ )
+
+ # Any prompt at all, a retry or a call nobody expected: still not forwarded.
+ streamed = _chat(guarded, key, {**_CHAT, "stream": True})
+ rows = streamed.text.splitlines()
+ lines = [line[5:].strip() for line in rows if line.startswith("data:")]
+ assert lines[-1] == "[DONE]"
+ text = "".join(
+ json.loads(line)["choices"][0]["delta"].get("content") or "" for line in lines[:-1]
+ )
+ assert text == "ok"
+ assert _chat(guarded, key, {**_CHAT, "stream": False}).json()["choices"][0][
+ "message"
+ ] == {"role": "assistant", "content": "ok"}
+ assert fake.calls == []
+ assert brain["requests"] == []
+ # Over: the agent's next call is a real one again.
+ _chat(guarded, key, {**_CHAT, "stream": True})
+ assert len(brain["requests"]) == 1
+
+
+def test_a_warm_up_needs_no_turn_of_the_person(fake, brain, guarded) -> None:
+ """Agent routes infer only inside a turn of the person; a warm-up run has
+ none (it holds the turn slot instead) and is still answered here, while
+ the same token outside a warm-up is refused as before."""
+ sub = gateway.grant_token("agent-1", "openai-codex", require_active_turn=True)
+ key = gateway.grant_token("agent-1", "openai", require_active_turn=True)
+ with gateway.warming(sub), gateway.warming(key):
+ answer = _post(guarded, sub, {"model": "gpt-5.6-sol", "input": "x"})
+ assert answer.status_code == 200, answer.text
+ assert answer.json()["status"] == "completed"
+ chat = _chat(guarded, key, {**_CHAT, "stream": False})
+ assert chat.status_code == 200, chat.text
+ assert chat.json()["choices"][0]["message"]["content"] == "ok"
+ assert _chat(guarded, key, {**_CHAT, "stream": False}).status_code == 409
+ assert fake.calls == [] and brain["requests"] == []
+
+
+def test_a_warm_up_covers_only_its_own_agent(fake, brain, guarded) -> None:
+ mine = gateway.grant_token("agent-1", "openai")
+ other = gateway.grant_token("agent-2", "openai")
+ with gateway.warming(mine):
+ answer = _chat(guarded, other, {**_CHAT, "stream": True})
+ assert answer.status_code == 200
+ assert len(brain["requests"]) == 1 # agent-2's own turn, on its own route
+ with pytest.raises(gateway.GatewayError), gateway.warming("jrg_unknown"):
+ pass
diff --git a/tests/unit/agent_runtimes/test_runtime_manager.py b/tests/unit/agent_runtimes/test_runtime_manager.py
index a66b13b124..5941715048 100644
--- a/tests/unit/agent_runtimes/test_runtime_manager.py
+++ b/tests/unit/agent_runtimes/test_runtime_manager.py
@@ -50,7 +50,7 @@ class FakeDriver:
self.is_busy = False
self.installs: list[str | None] = []
- def detect(self, *, refresh: bool = False) -> RuntimeStatus:
+ def detect(self, *, refresh: bool = False, fast: bool = False) -> RuntimeStatus:
self.refreshed += int(refresh)
fixed = self.marker is not None and self.marker.exists()
ready = self.ready or fixed
diff --git a/tests/unit/agent_runtimes/test_runtime_setup_turn.py b/tests/unit/agent_runtimes/test_runtime_setup_turn.py
index de06079a07..e41f4989f2 100644
--- a/tests/unit/agent_runtimes/test_runtime_setup_turn.py
+++ b/tests/unit/agent_runtimes/test_runtime_setup_turn.py
@@ -28,7 +28,7 @@ class Driver:
def __init__(self, ready: bool) -> None:
self.ready = ready
- def detect(self, *, refresh: bool = False) -> RuntimeStatus:
+ def detect(self, *, refresh: bool = False, fast: bool = False) -> RuntimeStatus:
return RuntimeStatus("hermes", "Hermes", installed=self.ready, ready=self.ready)
diff --git a/tests/unit/agent_runtimes/test_warm_pool.py b/tests/unit/agent_runtimes/test_warm_pool.py
new file mode 100644
index 0000000000..cb97c2a98e
--- /dev/null
+++ b/tests/unit/agent_runtimes/test_warm_pool.py
@@ -0,0 +1,294 @@
+"""Warm runtime processes: one ACP process serves an agent's turns one after another."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from dodaios.agent_chat import runner_acp
+from dodaios.agent_chat import runner_cli as rc
+from dodaios.agent_chat.runner_api import TurnHandle
+from dodaios.agent_chat.store import AgentChatSession
+from dodaios.agent_runtimes.acp import AcpTurn, session_params
+from dodaios.agent_runtimes.warm import SessionWant, WarmPool, WarmSpec, signature
+
+_AGENT = Path(__file__).resolve().parents[2] / "fakes" / "fake_acp_agent.py"
+
+
+def _session(tmp_path: Path, vendor: str | None) -> AgentChatSession:
+ return AgentChatSession(
+ session_id="society:hermit",
+ title="Hermit",
+ provider="local-openai",
+ model="fake-model",
+ effort="",
+ cwd=str(tmp_path),
+ permission_mode="bypass",
+ vendor_session=vendor,
+ created_ms=0,
+ updated_ms=0,
+ message_count=0,
+ preview="",
+ surface="society",
+ runtime="hermes",
+ )
+
+
+class _Rig:
+ """Turns through the CLI runner on a pool, the way the runtime drivers plan them."""
+
+ def __init__(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+ self.tmp_path = tmp_path
+ self.pool = WarmPool("hermes")
+ self.log = tmp_path / "frames.log"
+ self.config = "v1"
+ self.env = dict(os.environ)
+ self.env["FAKE_ACP_STORE"] = str(tmp_path / "store.json")
+ self.env["FAKE_ACP_LOG"] = str(self.log)
+ self.pids: list[int] = []
+ self.released = 0
+ monkeypatch.setattr(runner_acp, "plan_runtime_turn", self._plan)
+
+ def spec(self) -> WarmSpec:
+ argv = [sys.executable, str(_AGENT)]
+ return WarmSpec(
+ argv=argv,
+ env=self.env,
+ cwd=self.tmp_path,
+ signature=signature(argv, self.env, self.config),
+ )
+
+ def want(self, resume: str | None) -> SessionWant:
+ return SessionWant(resume=resume, params=session_params(str(self.tmp_path), []))
+
+ async def _plan(self, handle: Any, runner: str, *, prompt: str, cwd: Path, resume, identity):
+ lease = await self.pool.lease("hermit", self.spec(), self.want(resume))
+ assert lease is not None
+ self.pids.append(lease.pid)
+ acp = AcpTurn(
+ turn_id=handle.turn_id,
+ cwd=str(cwd),
+ prompt_text=prompt,
+ resume=resume,
+ auto_allow=True,
+ )
+ acp.initialized = lease.initialized
+ acp.open_session = lease.open_session
+ lease.turn = acp
+
+ def release() -> None:
+ if not lease.finished:
+ lease.finish()
+ self.released += 1
+
+ return rc.CliPlan(
+ argv=self.spec().argv,
+ env=self.env,
+ stdin_text=None,
+ shape="acp",
+ vendor_session=None,
+ keep_stdin=True,
+ acp=acp,
+ after_turn=release,
+ proc=lease,
+ )
+
+ async def turn(
+ self, text: str, vendor: str | None, *, cancel_after: float | None = None
+ ) -> tuple[str | None, list[dict[str, Any]]]:
+ events: list[dict[str, Any]] = []
+
+ async def emit(event: dict[str, Any]) -> None:
+ events.append(event)
+
+ async def ask(*_args: Any) -> str:
+ return "allow"
+
+ cancel = asyncio.Event()
+ handle = TurnHandle(
+ session=_session(self.tmp_path, vendor),
+ turn_id=f"t{len(self.pids) + 1}",
+ emit=emit,
+ request_approval=ask,
+ cancel=cancel,
+ )
+ if cancel_after is not None:
+ asyncio.get_running_loop().call_later(cancel_after, cancel.set)
+ vendor_out = await rc.run_cli_turn(handle, text, "hermes-cli")
+ return vendor_out, events
+
+ def methods(self) -> list[str]:
+ if not self.log.is_file():
+ return []
+ return [
+ json.loads(line).get("method", "")
+ for line in self.log.read_text(encoding="utf-8").splitlines()
+ if line.strip()
+ ]
+
+
+def _texts(events: list[dict[str, Any]]) -> list[str]:
+ return [e["payload"]["text"] for e in events if e["kind"] == "assistant_text"]
+
+
+def _finished(events: list[dict[str, Any]]) -> dict[str, Any]:
+ return next(e["payload"] for e in events if e["kind"] == "turn_finished")
+
+
+def test_the_second_turn_only_sends_its_prompt(monkeypatch, tmp_path):
+ rig = _Rig(monkeypatch, tmp_path)
+
+ async def scenario() -> None:
+ vendor, events = await rig.turn("hello", None)
+ assert vendor and _texts(events) == ["echo: hello"]
+ vendor2, events2 = await rig.turn("again", vendor)
+ assert vendor2 == vendor
+ assert _texts(events2) == ["echo: again"]
+ await rig.pool.stop()
+
+ asyncio.run(scenario())
+ assert rig.pids[0] == rig.pids[1] # one process for both turns
+ assert rig.methods() == [
+ "initialize",
+ "session/new",
+ "session/prompt",
+ "session/prompt", # no handshake, no reload: the session stayed open
+ ]
+ assert rig.released == 2
+
+
+def test_a_warm_up_opens_the_conversation_before_the_message(monkeypatch, tmp_path):
+ rig = _Rig(monkeypatch, tmp_path)
+
+ async def scenario() -> None:
+ vendor, _ = await rig.turn("first", None)
+ await rig.pool.stop() # the app restarted: no process left
+ assert await rig.pool.warm("hermit", rig.spec(), rig.want(vendor))
+ before = len(rig.methods())
+ vendor2, events = await rig.turn("second", vendor)
+ assert vendor2 == vendor and _texts(events) == ["echo: second"]
+ assert rig.methods()[before:] == ["session/prompt"]
+ await rig.pool.stop()
+
+ asyncio.run(scenario())
+ assert rig.methods().count("session/load") == 1 # done by the warm-up
+
+
+def test_a_changed_launch_starts_a_fresh_process(monkeypatch, tmp_path):
+ rig = _Rig(monkeypatch, tmp_path)
+
+ async def scenario() -> None:
+ vendor, _ = await rig.turn("hello", None)
+ rig.config = "v2" # the agent's model or tools changed
+ vendor2, events = await rig.turn("again", vendor)
+ assert vendor2 == vendor and _texts(events) == ["echo: again"]
+ await rig.pool.stop()
+
+ asyncio.run(scenario())
+ assert rig.pids[0] != rig.pids[1]
+ assert rig.methods().count("initialize") == 2
+ assert rig.methods().count("session/load") == 1 # the new process reopened it
+
+
+def test_a_fresh_conversation_never_reuses_the_open_one(monkeypatch, tmp_path):
+ rig = _Rig(monkeypatch, tmp_path)
+
+ async def scenario() -> None:
+ vendor, _ = await rig.turn("hello", None)
+ vendor2, _ = await rig.turn("rollover", None) # resume=None: a new conversation
+ assert vendor2 and vendor2 != vendor
+ await rig.pool.stop()
+
+ asyncio.run(scenario())
+ assert rig.pids[0] == rig.pids[1]
+ assert rig.methods().count("session/new") == 2
+
+
+def test_stop_ends_the_process_and_the_next_turn_starts_a_new_one(monkeypatch, tmp_path):
+ rig = _Rig(monkeypatch, tmp_path)
+
+ async def scenario() -> None:
+ vendor, _ = await rig.turn("hello", None)
+ _, events = await rig.turn("SLOW", vendor, cancel_after=0.5)
+ assert _finished(events)["status"] == "cancelled"
+ vendor3, events3 = await rig.turn("after", vendor)
+ assert _texts(events3) == ["echo: after"]
+ await rig.pool.stop()
+
+ asyncio.run(scenario())
+ # The stopped turn ran on the warm process; Stop ended that process (no
+ # frame of a stopped turn is trusted), so the next turn reopened the
+ # conversation on a fresh one.
+ assert rig.pids[0] == rig.pids[1] != rig.pids[2]
+ assert rig.methods().count("session/load") == 1
+
+
+def test_a_process_that_died_is_replaced(monkeypatch, tmp_path):
+ rig = _Rig(monkeypatch, tmp_path)
+
+ async def scenario() -> None:
+ vendor, _ = await rig.turn("hello", None)
+ _, events = await rig.turn("EXIT", vendor)
+ assert _finished(events)["status"] == "error"
+ _, events3 = await rig.turn("back", vendor)
+ assert _texts(events3) == ["echo: back"]
+ await rig.pool.stop()
+
+ asyncio.run(scenario())
+ assert rig.pids[1] != rig.pids[2]
+
+
+def test_a_cancelled_start_leaves_no_half_started_process(tmp_path):
+ """Stop during a warm process' handshake: nothing half-started stays for
+ the next turn to pick up."""
+ pool = WarmPool("hermes")
+ argv = [sys.executable, "-c", "import time; time.sleep(60)"] # never answers
+ spec = WarmSpec(argv=argv, env=dict(os.environ), cwd=tmp_path, signature="s")
+ want = SessionWant(resume=None, params=session_params(str(tmp_path), []))
+
+ async def scenario() -> None:
+ task = asyncio.create_task(pool.lease("hermit", spec, want))
+ await asyncio.sleep(0.5)
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ assert not pool.has("hermit")
+ await pool.stop()
+
+ asyncio.run(scenario())
+
+
+def test_a_reset_turns_session_serves_the_turns_after_it(monkeypatch, tmp_path):
+ """OpenClaw: the conversation is the runtime's own key; the session a
+ fresh (reset) turn opened keeps serving the turns that follow."""
+ rig = _Rig(monkeypatch, tmp_path)
+ reset = {"sessionKey": "agent:main:main", "resetSession": True}
+ keep = {"sessionKey": "agent:main:main", "resetSession": False}
+ match = session_params(str(tmp_path), [], {"sessionKey": "agent:main:main"})
+
+ def want(meta: dict[str, Any]) -> SessionWant:
+ return SessionWant(
+ resume=None, params=session_params(str(tmp_path), [], meta),
+ bound=not meta["resetSession"], match=match,
+ )
+
+ async def scenario() -> None:
+ first = await rig.pool.lease("hermit", rig.spec(), want(reset))
+ assert first is not None and first.open_session == ""
+ first.finish() # a turn that never prompted: nothing to keep
+ assert await rig.pool.warm("hermit", rig.spec(), want(keep))
+ second = await rig.pool.lease("hermit", rig.spec(), want(keep))
+ assert second is not None and second.open_session # opened ahead, bound
+ second.finish()
+ again = await rig.pool.lease("hermit", rig.spec(), want(reset))
+ assert again is not None and again.open_session == "" # a reset never reuses
+ again.finish()
+ await rig.pool.stop()
+
+ asyncio.run(scenario())