Skip to main content
@clawboo/executor defines the one interface Clawboo uses to drive every runtime: the RuntimeAdapter trait. An adapter starts a run on its runtime and translates the runtime’s own frames into a shared RuntimeEvent stream. Every server path that drives a run (the executor runner, the team engine, 1:1 agent chat, the verification critic) reads that stream and never a runtime’s native format. Use this page when you change an adapter, consume the event stream, or add a runtime.

What the package holds

The package is pure: no workspace dependencies, no runtime dependencies and no node:* imports, so it builds browser-safe and is inlined into the CLI bundle. Its main entry (packages/executor/src/index.ts) exports:
  • the trait and its types (RuntimeAdapter, Capabilities, RunHandle, StartOpts, SteerResult, SteerOptions, SessionCodec);
  • the RuntimeEvent union and the assertExhaustive guard;
  • resolveRuntimeIntegration, which turns declared capabilities into an integration plan;
  • RuntimeRegistry, a Map wrapper the server does not use (see How the server builds adapters);
  • createAsyncQueue, the callback-to-iterator bridge;
  • the idle guard withIdleTimeout with DEFAULT_RUN_SILENT_TIMEOUT_MS and IDLE_ABORT_GRACE_MS;
  • the steering helpers steerThroughDriver and steeringOf;
  • the session-rotation helpers (shouldRotate, buildRotationHandoffNote, rotateSession, DEFAULT_ROTATION).
Two subpaths sit beside it. @clawboo/executor/contract holds the shared adapter test suite, which imports vitest, so it never rides the main entry. @clawboo/executor/tiers holds the prompt-tier helpers. The trait is deliberately narrow. Claiming a task, provisioning a worktree, running verification and writing the handoff belong to the executor runner. Which agents exist belongs to AgentSource. An adapter knows neither.

The six adapters

clawboo-mock synthesizes its whole event stream from directives in the message, so silence, a crash, an unresolved tool call or a slow start can be reproduced through the real server paths. It is listed only when CLAWBOO_ENABLE_MOCK_RUNTIME=1, never appears in a normal install, declares no steering and no worktrees, and does not run the contract suite.

The trait

Identity: id and participantKind

RuntimeId is an open set: 'openclaw' | 'claude-code' | 'codex' | 'hermes' | (string & {}). The (string & {}) member turns the named ids into autocomplete hints, so a new runtime id is a value, not a type change. participantKind is 'agent' | 'human'. Every adapter sets 'agent' and nothing in the code branches on it. 'human' is reserved so a person could later sit behind the same interface; there is no human-participant adapter.

capabilities()

capabilities() returns a Capabilities block. The base fields describe the runtime:
toolApproval: true describes the runtime, not Clawboo’s use of it. Clawboo drives Claude Code and Codex headless with their own approval prompts and sandboxes turned off: Claude Code with permissionMode: 'bypassPermissions' (plus allowDangerouslySkipPermissions: true), Codex with --dangerously-bypass-approvals-and-sandbox (or, through codex app-server, approval policy never and sandbox danger-full-access). Hermes runs with its own approval policy on (approvals.mode) and no sandbox, so it asks, on a Clawboo card, only before the commands that policy flags. A per-task git worktree keeps file changes apart when the executor runner provisions one; it is not a sandbox. See What agents can do.

Integration fields and resolveRuntimeIntegration

A second group of optional fields tells the host how deeply to integrate the runtime, so the host routes by declared data and never by a runtime-id switch:
  • runtimeClass?: 'wrapped-oneshot' | 'connected-substrate' | 'native'. A wrapped one-shot is driven one run at a time by a per-run driver: a process spawned per run (Claude Code, Codex), or a run on a long-lived server the host itself supervises (Hermes’s gateway); a connected substrate is a long-lived service the host drives over its live connection (OpenClaw); native is the in-process harness. Omitted means 'wrapped-oneshot'.
  • nativeHome?: { scope: 'per-identity' | 'per-run', persist: boolean }: a claim about the home directory the runtime accrues state in. The adapter never computes a path; the host materializes it.
  • nativeSkills? and nativeMemory?: 'preserve' | 'none', whether the runtime’s own on-disk skills or memory must survive across runs.
  • nativeChannels?: 'gateway' | 'none': whether the runtime owns its own delivery channels.
  • nativeScheduler?: boolean: informational only. The host’s scheduler always decides when work runs.
resolveRuntimeIntegration(caps) (packages/executor/src/integration.ts) turns those fields into the plan the host executes: coRunScheduler is always false. Preserve flags are clamped to a persistent home, so a misdeclared adapter degrades to the plain one-shot path instead of a contradictory plan. The executor runner refuses a connected home before it claims anything, and serializes runs of a persistent home per agent. What each adapter declares (packages/adapters/*/src/adapter.ts): Every real adapter declares resume: true and toolApproval: true; the mock declares both false. Native and Claude Code declare a 200,000-token context window; the others declare none, so the rotation watermark stays off for them. The runtime descriptor (RUNTIME_DESCRIPTORS in apps/web/server/lib/runtimes/descriptor.ts) answers a different question: how to install and authenticate a runtime (package, health binary, auth kind, vault env var). The class lives on the adapter because it describes how the host drives the runtime once it is online.

start() and the late-bound runId

start(task, opts) delivers the run’s opening message and returns a RunHandle:
runId is mutable and late-bound. A runtime usually reports its run id on the first lifecycle frame rather than from start(), so callers begin with runId: null, and events() re-binds run.runId from the first frame of each run. TaskHandle ({ taskId?, teamId? }) carries optional board references, so an adapter can run board-backed or ad hoc work. StartOpts carries the runtime-side agentId, the sessionKey, the message, an optional model and context block, and a childToolBlocklist of tools the run must not use (the runner passes ['sessions_send']). The blocklist is advisory for runtimes that cannot restrict tools per run, so the host also enforces the real limit elsewhere: the board’s depth cap, and for OpenClaw the sub-agent tools in the Gateway’s tools.deny.

events(): a continuous observer

events(run) returns an AsyncIterable<RuntimeEvent> for run.sessionKey.
events() is a continuous observer. A Gateway session hosts many successive runs on one sessionKey, so done and error are yielded as events but do not necessarily end the stream. The consumer ends observation itself (break or iterator.return()), which releases the subscription. For a one-shot CLI process the stream ends when the process exits. Either way, the consumer drives termination.
Adapters subscribe when events() is called, not on the first next(), so frames that arrive between subscription and the first pull are buffered rather than dropped. The OpenClaw adapter shows the shape: it subscribes through client.onEvent, filters frames by sessionKey, re-binds run.runId from each frame, maps frames to RuntimeEvents with mapFrameToRuntimeEvents, and unsubscribes only when the iterator’s return() runs.

abort(), setModel(), writeContext()

  • abort(run) cancels the live run. The OpenClaw adapter sends chat.abort when a runId is bound and always sends sessions.abort too, which covers the window before the run id binds and any queued work.
  • setModel(run, model) switches the model mid-session (OpenClaw: sessions.patch).
  • writeContext(run, key, value) writes a context file (OpenClaw: agents.files.set). It is not a mid-run channel: a spawned CLI never re-reads the file during a run, and a running OpenClaw session does not re-read an agent file. Use steer() for that.

steer(): a message into a running run

steer(run, text, opts?) puts a message in front of the model during the run it is aimed at. It is how a person’s comment on a task reaches the agent working on it. The adapter declares how in capabilities().steering:
  • 'live': the runtime takes the message into the turn in progress at its next boundary without stopping anything (Clawboo Native, Claude Code, Codex, OpenClaw and Hermes).
  • 'interrupt-resume': the runtime has no way in mid-run, so the driver stops the process and resumes the same session with the message as the next input (no adapter declares it today). The stop is absorbed inside the driver and never surfaces as a terminal event, so the host sees one run that carries on. An aborted terminal would otherwise reach the team engine’s failure path.
  • 'none' or omitted: no mid-run channel. A host must not call steer() on such a run.
steer() is optional and never throws. It resolves { delivered: true, mode } when the runtime accepted the message for this run, or { delivered: false, reason } with reason one of no-run, run-ended, unsupported or rejected (plus an optional detail). The server’s comment path saves first and steers second, so a refusal falls back to the next turn. On a team chat task it saves a wake: a steer that lands hands the comment to that run, and it counts as heard when the run ends well; otherwise the next turn’s ticket block carries it. On a task the task runner runs it writes the agent’s mailbox and marks the row delivered when the steer lands; otherwise the next run reads the mailbox. SteerOptions.passive marks an ambient note rather than a person’s instruction: it is delivered if the run reads input again, but never keeps a finishing run going and never stops a run (an 'interrupt-resume' adapter refuses it). Adapters with a per-run driver share their steer() body through steerThroughDriver(driver, text, mode, opts); steeringOf(caps) reads an omitted claim as 'none'. runSteering(run) (optional) says how one run takes a steer, for an adapter whose runs can differ from what capabilities() declares for new runs. The Hermes adapter has it and asks the run’s own driver, which answers live. The task card’s hint reads it, through GET /api/board/:taskId’s runSteering. Without it a run takes a steer the declared way.

sessionCodec and dispose

sessionCodec (optional) serializes a run’s session to a string and restores it; the runner uses it to persist a native session id for a same-runtime resume. dispose (optional) releases adapter-level resources.

The RuntimeEvent union

Every adapter normalizes its runtime’s signals into one union with seven kinds:
Each event carries a common envelope:
seq orders events that share a millisecond ts, so a consumer can always reconstruct causal order. The union encodes two real differences between runtimes in its types:
  1. Not every runtime reports USD. cost.costUsd is number | null, and estimated? marks a derived value. A runtime that cannot supply USD emits null rather than an invented number; the runner then estimates spend from the token usage (see the executor runner). local? marks a model the user’s own Ollama served, whose costUsd of 0 is exact rather than unknown.
  2. Not every runtime streams text. A runtime without deltas emits one text-delta carrying the whole message.
assertExhaustive(x: never): never guards switch statements over the union, so a new variant is a compile error at every switch that forgets it.

How the server builds adapters

The server does not keep a registry of adapter instances. apps/web/server/lib/runtimes/index.ts builds a fresh adapter for each run:
  • enabledRuntimeIds() lists the non-OpenClaw runtimes: the four real ones, plus clawboo-mock only when CLAWBOO_ENABLE_MOCK_RUNTIME=1.
  • adapterFactoryFor(id) returns a factory that takes a RuntimeRunContext (working directory, model, resume id, MCP base URL, memory scope, home directory, provider keys) and constructs the adapter wired to its real driver and health check. buildRuntimeAdapterFactories() maps every enabled id to its factory.
  • OpenClaw adapters are built per delivery over the server’s shared Gateway connection: buildOpenClawServerAdapter() (runtimes/serverAdapter.ts) for team chat, and the Routines wake bridge for OpenClaw routine fires.
RuntimeRegistry (register, unregister, get, has, ids, list) is exported from the package and unit-tested, but nothing in the server or the dashboard uses it.

Where runtimes are installed

The runtimes Clawboo installs, OpenClaw, the Claude Agent SDK and Codex, go into the runtimes folder, never npm’s global prefix. A global install failed with EACCES on a root-owned prefix, was stranded when nvm switched Node, and ran on whatever node came first on PATH. The user-facing rules and their messages are in The runtimes folder. apps/web/server/lib/runtimeFolder.ts owns the folder. It imports only Node built-ins, @clawboo/config and @clawboo/logger, because platform.ts, which nearly every runtime path imports, imports it. The record, <id>/clawboo-runtime.json (RuntimeInstallRecord, schema: 1), holds the current install’s folder, its version, the source spec, installedAt, the interpreter ({ path, version } of the Node that installed it) and launchers, each a name mapped to { command, args }. A launcher is a short script (#!/bin/sh with exec, or a .cmd file on Windows) that runs that absolute command with those arguments. apps/web/server/lib/runtimes/npmRuntimeInstall.ts installs one npm runtime with runNpmRuntimeInstall(rt), where rt is an NpmRuntime (id, spec, bins). npmInvocation() runs npm’s own npm-cli.js with process.execPath: the one beside that Node, Homebrew’s under its prefix, or the one behind the npm on PATH; only without any does it run npm itself. npm never runs through a shell, so a Windows npm.cmd without npm-cli.js beside it is not used. stableNodePath() (from runtimeFolder.ts) records a Homebrew node@<major> Node by its opt link, which survives brew upgrade, and a node formula’s Node by its keg. npmChildEnv() drops npm_config_global, npm_config_location and npm_config_prefix, puts this Node’s folder first on PATH, and sets PYTHONDONTWRITEBYTECODE=1 unless PYTHONDONTWRITEBYTECODE or PYTHONPYCACHEPREFIX is set (in any case on Windows), so a native part’s build writes no __pycache__ into npm’s own folder. npmInstallArgs() builds install --prefix <folder> --include=optional --no-global --location=project --no-fund --no-audit <spec>. On exit 0 it reads the package’s bin map and commits one launcher per name in bins, each { command: <that Node>, args: [script] }. Before the commit, an optional check(folder) may give a reason the new install cannot be used; the runtimes route passes one for the Agent SDK that requires its platform binary (agentSdkBinaryInInstall). It returns { child, result }, and every failure removes the folder and resolves with a code: RUNTIMES_DIR_REFUSED, NPM_MISSING, RUNTIMES_DIR_FAILED, SPAWN_THROW, SPAWN_ERROR, STOPPED, NOT_INSTALLED, NO_COMMAND, UNUSABLE, COMMIT_FAILED, npm’s own code from summarizeNpmFailure, else EXIT_<n>. POST /api/system/install-openclaw and POST /api/runtimes/:id/install both call it. A descriptor’s npmBins in runtimes/descriptor.ts names the commands: ['codex'] for Codex and [] for the Agent SDK, a library. Lookups put the runtimes folder first, then PATH, then the user-install folders:
  • resolveRuntimeBin(name) in apps/web/server/lib/platform.ts tries ownedRuntimeBin(name), then findExecutable(name), then extraBinDirs(). The Codex drivers, the install probe and the Runtimes panel go through it.
  • detectOpenClaw() in apps/web/server/lib/openclawDetect.ts returns Clawboo’s copy with source: 'clawboo', its recorded version and its node, without spawning it, else a PATH copy with source: 'path'. The status route reports its path. Device approval, the Gateway start (with its openclaw doctor --fix) and the model list in modelCache.ts start Clawboo’s copy as its recorded command and arguments, with no shell (openclawInvocation()), so a Windows path with a space works; a PATH copy runs as before.
  • ownAgentSdkDir() in apps/web/server/lib/runtimes/agentSdkBinary.ts finds the SDK in the current Claude Code install. The driver imports it by file URL, because a bare specifier searches only the node_modules folders around the server, and falls back to import('@anthropic-ai/claude-agent-sdk'). resolveAgentSdkBinary() follows the same order for the install probe, and for Clawboo’s copy accepts only a binary inside that install; the driver hands it to the SDK as pathToClaudeCodeExecutable, so the SDK never looks in folders above the install.

The async queue

Adapters bridge a callback source (a WebSocket onEvent, a subprocess stdout reader) into an AsyncIterable by pushing into createAsyncQueue<RuntimeEvent>() and letting the consumer pull with for await. The queue has one consumer. Backpressure is drop-oldest at max (default 1000), because orchestration cares about tool calls and done more than every text delta. close() ends the stream, and the iterator’s return() closes the queue, which is how events() releases its subscription.

The idle guard

withIdleTimeout(source, { idleMs, onIdle, graceMs? }) re-yields an event stream and bounds the silence between events. The timer resets on every event, so a long run that keeps streaming never trips it. Silence is counted in awake time (setAwakeTimeout), so a machine that sleeps does not trip it. When silence passes idleMs, onIdle() fires (the caller aborts the run there), then a grace window (IDLE_ABORT_GRACE_MS, 5 seconds) lets the adapter surface its own terminal before the stream ends. The executor runner, the team engine’s serverDeliver and the 1:1 chat’s driveAgentChat drain their runs through it; the other events() loops do not. Their ceiling is DEFAULT_RUN_SILENT_TIMEOUT_MS (30 minutes), overridable with CLAWBOO_RUN_SILENT_TIMEOUT_MS. The runner reports a silent timeout as a failed run with the cause stated, and a 1:1 chat that has not replied yet gets a notice that the run went quiet for too long.

The contract suite

Every real adapter passes one shared suite, runAdapterContract(harness) from @clawboo/executor/contract. The adapter supplies an AdapterTestHarness: how to make the adapter on a fake transport, start a run, emit a native frame, and read the side effects it issued. The harness translates abstract ContractFrames (delta, toolCall, final, aborted, error) into the runtime’s own frames, and the suite asserts on the normalized output:
  • id is a non-empty string and participantKind is 'agent' or 'human';
  • capabilities() returns a well-formed shape;
  • health() resolves within two seconds;
  • start() returns a handle with the adapter’s id and an unbound runId (null);
  • events() round-trips a stream that ends in done: success with strictly increasing seq;
  • runId binds late, from the first lifecycle frame;
  • abort() issues a cancel side effect and the stream surfaces done: aborted;
  • setModel() and writeContext() each issue their side effect.
vitest stays external in the package’s tsup config. A bundled copy would register describe and it on a detached collector, and an adapter’s contract tests would silently never run. Keeping it external binds the suite to the consumer’s vitest at runtime.
The package also tests the suite itself against a minimal InMemoryAdapter (packages/executor/src/__tests__/contract-selftest.test.ts), which doubles as the smallest reference implementation of the trait.

Prompt tiers: @clawboo/executor/tiers

The ./tiers subpath keeps a provider’s prompt cache warm. A prompt has three tiers, ordered by how often they change: assembleTiers(tiers) joins them in that order and returns the prompt, the stablePrefix (stable plus context, identical turn over turn), its UTF-8 byte length, and suggested cacheBreakpoints (byte offsets an Anthropic-style consumer can map to cache_control markers; OpenAI caches prefixes on its own and the OpenClaw Gateway owns its caching, so both ignore them). Two helpers keep the prefix stable:
  • sortToolDefs(defs) sorts tool definitions by name without mutating the input, because tool order is part of the cache key.
  • dateStamp(d) returns a YYYY-MM-DD (UTC) stamp. A minute or second timestamp in the prompt would bust the cache on every rebuild; a runtime that needs wall-clock time should get it from a tool.
The executor runner assembles every run’s prompt through assembleTiers (see Prompt assembly), and Clawboo Native’s conversation loop uses dateStamp for its date header.

Session rotation

The rotation helpers answer “the session ran out of room before the task finished”. Rotation happens between runs, never mid-generation, because the runtime owns its inner loop. shouldRotate fires when tokensUsed / contextWindow reaches thresholdPct (DEFAULT_ROTATION.thresholdPct, 0.85) and stays inert when the runtime declares no window. rotateSession takes the adapter, a restart closure (the host re-assembles the prompt with a short handoff note from buildRotationHandoffNote and calls adapter.start), and an optional recordRotation callback for lineage. DEFAULT_ROTATION.maxRotations (3) bounds the chain of successor sessions per task. The runner’s use of it is described in Session rotation.

Add a runtime

A new runtime touches more than the trait. Wire it in this order, and grep for an existing id such as 'hermes' to catch anything this list misses.
1

Write the adapter package

Create packages/adapters/<id> exporting a class that implements RuntimeAdapter. Declare only capabilities that are true; omit the integration fields you cannot back. Add a test that calls runAdapterContract from @clawboo/executor/contract against a fake driver, like the existing packages/adapters/*/src/__tests__/adapter.test.ts.
2

Write the server driver

Add a driver under apps/web/server/lib/runtimes/ that spawns or connects to the runtime and consumes a RuntimeRunContext (runtimes/types.ts). Honour ctx.cwd, ctx.homeDir, ctx.mcpBaseUrl and ctx.apiKeyEnv the way the existing drivers do.
3

Register the id and descriptor

Add the id to NonOpenClawRuntimeId and NON_OPENCLAW_RUNTIME_IDS, and a RUNTIME_DESCRIPTORS entry (package, npmBins for an npm runtime, the command for installing it by hand, health binary, auth kind, vault env var), in apps/web/server/lib/runtimes/descriptor.ts. An npm runtime installs through runNpmRuntimeInstall into the runtimes folder; see Where runtimes are installed.
4

Add the factory

Add a case to adapterFactoryFor() in apps/web/server/lib/runtimes/index.ts that builds the adapter over your driver, with a health check. Add the adapter package to apps/web/package.json.
5

Add a capability source

Implement a CapabilitySource in apps/web/server/lib/capabilitySource/, register it in capabilitySource/registry.ts, and add its id to CapabilitySourceId and SOURCE_IDS in packages/capability-registry/src/. See Capability and schedule sources.
6

Add an agent source

For a runtime whose agents live only in SQLite, add the id to CODING_RUNTIME_SOURCE_IDS in apps/web/server/lib/agentSource/registry.ts, which registers a RuntimeAgentSource for it. A runtime with its own upstream needs its own AgentSource. See AgentSource.
7

Declare agent files and prompt behaviour

Add a row to AGENT_FILE_RUNTIME_SUPPORT in packages/protocol/src/index.ts listing only the files the runtime really consumes. If it reads no persona file of its own, add it to RUNTIMES_WITHOUT_NATIVE_PERSONA in runtimes/personaBlock.ts, and check memoryGuidance.ts and teamChat/contextPreamble.ts.
8

Surface it in the dashboard

Add the id to the client RuntimeId union in packages/control-client/src/runtimes.ts and an entry to apps/web/src/features/runtimes/runtimeCatalog.ts, then follow the remaining UI references (brand mark, Boo variant, runtime pickers).
You should then see the runtime on the Runtimes settings panel, be able to create an agent on it, and run a board task on it through POST /api/runtimes/<id>/run.
Last modified on November 18, 2026