aios/services/aios-agent-runtime-broker/RUNTIME_CONTRACT.md

Autonomous Engineering Runtime Contract v1

The Online Agent Worker and the Hermes/Codex engineering runtime are separate security domains.

The worker owns:

• Agent Task polling, atomic claim, task lease and heartbeat;
• intent resolution and restart state;
• authoritative repository/base selection;
• independent diff inspection and secret checks;
• verification command allowlisting and re-execution;
• Governed GitOps task/lease/commit;
• final result submission.

The runtime broker and Hermes/Codex backend do not receive:

• Agent Task API token;
• task lease token;
• governed writer lease or Bridge credential;
• authority repository write access.

stdin request

The backend configured behind the broker receives one JSON object:

schema = aios.online-agent.runtime-request.v1

It contains task goal/instructions/success criteria and a pinned disposable worktree path. The backend may inspect and modify that worktree. It must not commit or push.

stdout response

The backend returns one JSON object:

{
  "schema": "aios.online-agent.runtime-result.v1",
  "status": "COMPLETED",
  "summary": "root cause and implementation summary",
  "verification": [
    {
      "label": "focused test",
      "argv": ["/usr/bin/python3", "-m", "pytest", "-q", "tests/test_x.py"],
      "cwd": ".",
      "timeout_seconds": 600
    }
  ],
  "evidence": {
    "root_cause": "..."
  }
}

status may also be BLOCKED or FAILED.

The worker ignores any backend claim about changed files and independently reads Git state. It also reruns verification requests through its local command allowlist.

Real runtime requirement

A chat/router/WeChat Hermes service is not an engineering backend. A compliant backend must be able to read and mutate the disposable worktree and emit the runtime result schema above.

The exact Hermes/Codex CLI/API must be discovered from the installed runtime. Do not invent flags. /etc/aios/agent-runtime-hermes.conf contains only non-secret backend command configuration. Any model/runtime credential must be delivered to the broker/backend through its own systemd credential projection, never through the Online Agent worker token.

OpenClaw headless engineering backend

For hosts that have a current OpenClaw CLI, use the bundled openclaw_engineering_backend.py.

The wrapper invokes the documented headless coding entry point:

openclaw agent exec --message-file - --cwd <pinned-worktree> --model <model> --auth-env-only --timeout <seconds> --json

It deliberately does not use the Gateway/WeChat/chat route. agent exec runs an embedded, one-shot agent turn and scopes its workspace/tool working directory to --cwd.

Provider credentials, if required, are projected into the broker service under separate systemd credentials and mapped to provider environment variables only for the OpenClaw child. The Online Agent Task token and writer lease remain absent.

Before enabling the autonomous worker, run a disposable broker self-test that proves OpenClaw changes the requested worktree while Git HEAD remains at the base OID.