[jannikluhn]

Built on #34 (feat/parallelization); merge that PR first. Most of this PR is tests, test helpers, an example, and documentation for the new runtime.

What this does

Adds createOpenClawRuntime, exported from @shutter-network/concorde/openclaw, as an alternative to the pi runtime. It connects Concorde to an OpenClaw daemon. The gateway, components, and signal handlers work with either runtime.

To switch the application to OpenClaw, replace the runtime constructor:

-const runtime = createPiRuntime({ host, port, sessionsDir })
+const runtime = createOpenClawRuntime({
+  url: "ws://agent:18789",
+  token: process.env.OPENCLAW_GATEWAY_TOKEN,
+  deviceKey: createPrivateKey(readFileSync(DEVICE_KEY_FILE)), // must be an Ed25519 private key
+  agentId: "concorde", // optional if the daemon hosts one agent
+})

One run, end to end

sequenceDiagram
    participant W as Signal worker
    participant R as OpenClaw runtime
    participant D as OpenClaw daemon
    W->>R: run(prompt)
    R->>D: Connect with token and signed device challenge (operator.read + operator.write)
    R->>D: sessions.messages.subscribe { key: session }
    R->>D: chat.send { sessionKey: session, message, deliver: false }
    D-->>R: session.message with usage and __openclaw.runId, once per model call
    D-->>R: chat with state final, error, or aborted and runId
    R->>D: Close connection
    R-->>W: { ok, usage[], limited? }

Loading

The daemon broadcasts events for multiple runs over each connection. The runtime filters run events by runId and usage records by __openclaw.runId. It subscribes before sending the prompt so it does not miss usage records.

Every send uses deliver: false, which disables replies through OpenClaw's own channels. The agent must use Concorde's messenger to send messages to users.

How it differs from pi

	pi	OpenClaw
Agent process	A listener starts one process per connection.	All runs use the same daemon, with a separate connection per run.
Connection authentication	None.	A shared token and a signed Ed25519 device challenge. Approve the device once on the daemon host; the runtime writes no credentials to disk.
Session names	Names become files under sessionsDir and follow pi's naming rules.	Names become the last part of agent:<agentId>:<name>. They must be nonblank, lowercase, at most 512 characters, and contain no colons or surrounding whitespace. main and global are reserved. These checks prevent OpenClaw's name normalization from merging distinct sessions.
Usage reporting	Reported directly on the RPC stream.	Read from model-call records in the session subscription and converted to the same usage format.
Usage limit	Aborts the run and reports partial usage for the interrupted call.	Sends chat.abort. OpenClaw does not report usage for the interrupted call, so the recorded total can understate the run's cost.

Each runtime now validates its own session names. Both accept run_<uuid>, the format the worker uses when it creates a session. Tests cover that shared requirement.

What is in the tree

src/openclaw/
├── runtime.ts             # validation, run lifecycle, and usage limits
├── connection.ts          # official client, device signing, and connection failures
├── session-names.ts       # session name validation
├── usage.ts               # convert session.message records to UsageReport
├── *.test.ts              # tests using a simulated daemon
└── agent-instance.test.ts # tests using the real daemon image, pinned to 2026.8.1
src/test-support/
├── openclaw-daemon.ts     # in-process WebSocket daemon for tests
└── openclaw-runtime.ts    # shared test helpers
examples/06_openclaw/      # minimal application, with pairing instructions in its README

Adds @openclaw/gateway-client and @openclaw/gateway-protocol at ^2026.8.1. Imports are restricted to src/openclaw/ by the Biome configuration and a test. Connections require a matching protocol version, so an incompatible daemon produces a connection error. The container test uses a pinned daemon image.

Verification

Validation reported for this branch:

• npm run check: 634 tests pass.
• npm run check:package and npm run check:docs pass.
• npm run test:container tests a real OpenClaw daemon: an unapproved device gets pairing instructions, approval through the daemon's CLI allows subsequent runs, two prompts continue the same session and return usage, and exceeding a usage limit returns limited: true with one usage record.
• The 06_openclaw example was run under Compose using a locally packed package. Device pairing, pairing approval surviving a restart, and a run reaching the model provider were checked. Sending an agent reply through the messenger was not verified because no model key was available.

Notes for the reviewer

• The example installs Concorde from the registry. It needs a release that includes /openclaw before it can run without local package overrides.
• The existing intermittent failure in the database listener tests remains: it appears in the full suite, while the tests pass on their own.
• totalTokens is calculated as input + output + cacheRead + cacheWrite, as required by UsageReport. This also matches the observed daemon records.
• The glossary, architecture document, and editing guide now describe connections for both pi and OpenClaw.