Hermes / OpenClaw Online Agent Runtime

Goal

Promote Hermes and OpenClaw from shadow-only adapter descriptions to real Online Agent workers without creating a second Task/claim protocol.

Both workers reuse the existing P1/P2 Online Agent lifecycle:

Online Task projected
→ capability-filtered poll
→ automatic claim
→ heartbeat
→ durable checkpoint
→ external Agent execution
→ attempt-aware result submission
→ official verification

They do not change the existing TaskPlane OpenClawAdapter/HermesAdapter shadow contract. Those adapters remain side-effect-free compatibility surfaces.

Execution action

The canonical execution envelope adds a read-only action:

action=agent_runtime
adapter=hermes | openclaw

The action requires capability agent.runtime.<adapter>, has an empty change set, no verification commands, and writer_lease=false.

project_online_task() copies only bounded task fields into the signed execution envelope:

goal;
instructions;
success criteria;
non-secret constraints.

The task may not choose a command, executable, URL, credential path, environment, or shell string.

Worker separation

The generic engineering worker defaults to:

AIOS_WORKER_ALLOWED_ADAPTERS=deterministic,source_capture,compact_interface_map,codex

so it skips Hermes/OpenClaw tasks before claim.

Dedicated services advertise:

Hermes:
  AIOS_WORKER_CAPABILITIES=agent.runtime.hermes
  AIOS_WORKER_ALLOWED_ADAPTERS=hermes

OpenClaw:
  AIOS_WORKER_CAPABILITIES=agent.runtime.openclaw
  AIOS_WORKER_ALLOWED_ADAPTERS=openclaw

This makes adapter selection a pre-claim capability/fleet decision instead of a post-claim failure.

Credential-isolated executor

The Online Agent worker itself still owns only Task API/Bridge coordination credentials. It writes a hash-bound request to /var/lib/aios-external-agent-executor.

aios-external-agent-executor.service runs as the existing uncredentialed engineering executor user. It has:

one provider-only LoadCredential projection for the model-ready OneAPI environment;
/etc/aios-gitops, /data/aios-gitops, and the original provider-secret directory inaccessible;
no repository path;
no shell execution;
loopback denied, preventing direct access to the AIOS Task/Bridge control plane;
only the staging OneAPI container address allowed for the installed Agent runtime/provider;
only the exchange directory writable.

The root-owned runtime profile in /etc/aios/external-agent-runtime.d/<runtime>.json decides the absolute executable, fixed non-secret environment, provider-only credential mapping, and I/O mode. A task cannot override any of these values. The profile may select OPENAI_API_KEY only from the systemd credential named aios-external-agent-oneapi-env; it cannot name a credential, inject an environment variable, or carry an inline secret. The runtime executor parses only the selected ONEAPI_REGULAR_TOKEN entry and does not expose the source file or other provider tiers to the child.

Runtime profile

A profile supports:

argv: fixed argv, absolute allowlisted executable;
input_mode: stdin_text, stdin_json, or file_json;
output_mode: stdout_text, stdout_json, or file_json;
timeout;
bounded output size.

{input_json} and {output_json} placeholders are allowed only for file modes. {prompt} is a root-profile-only argv placeholder populated from the bounded, signed task projection.

The repository includes the staging profile templates validated against the installed Hermes v0.20.0 and OpenClaw v2026.7.2-beta.7 CLIs. Before activation, the Agent must re-run the actual --help/version probes and install the profiles and static configs root-owned. If the installed CLI differs, update only the root-owned profile/config projection and record the observed command; do not modify the Task contract to compensate.

The provider projection is staging-only and uses the existing model-ready OneAPI source. It is not an AIOS Task, Bridge, GitOps, SSH, or Writer credential. Live activation remains blocked if the model-ready source cannot be projected through systemd or if the selected provider credential is missing/quota-invalid. This worker never passes API keys through task metadata or arbitrary environment variables.

Retry/restart

The external request ID is deterministic over Task/Job/execution digest/runtime. The exchange keeps the request/result across worker restart. A repeated attempt with the exact execution digest reuses the durable external result instead of invoking the Agent twice.

The normal P1 result idempotency/checkpoint path remains authoritative for Task result submission.

Result

Successful execution returns:

status=SUCCEEDED
classification=EXTERNAL_AGENT_RUNTIME_SUCCEEDED
execution_mode=agent_runtime
agent_runtime=hermes | openclaw
writer_lease=NONE
changed_files=[]
credential_material_exposed=false
control_plane_access_granted_to_runtime=false

This first runtime version is intentionally read-only with respect to the repository. Engineering changes continue to use assistant-authored deterministic plans and governed WriterLease/commit.

5.1 KiB Raw Blame History