Runtime inventory and host status

← index

Colibri discovers the host in two complementary ways:

1. Runtime inventory — a one-shot probe that reports versions installed on

the machine (node, npm, pi, zot, package manager, OS, etc.).

2. Watchdog host status — a read-only, newline-framed Unix-socket call to

the Clawdie watchdog that returns live health metrics.

Both are intentionally additive: they read from Clawdie, they do not change

it. This page records the design of those read-only integrations.

Runtime inventory probe

The colibri-runtime-inventory binary (src/bin/runtime_inventory.rs) emits a

single JSON object matching the clawdie.runtime-version-inventory.v1 schema

from crates/colibri-contracts/src/lib.rs.

Detection strategy

Field	How it is detected
`host`	`COLIBRI_HOST` → `HOSTNAME` → `hostname` command → `"unknown"`
`os`	`uname -sr` + target architecture; falls back to `std::env::consts`
`node`	`node --version`
`npm`	`npm --version`
`npm_prefix`	`npm config get prefix`
`package_manager`	`pkg` on FreeBSD, otherwise `apt` / `dnf` / `brew`
`pi`	`PI_BIN` → `~/.npm-global/bin/pi` → `pi --version` → package.json of `@earendil-works/pi-coding-agent`
`zot`	`ZOT_BIN` → `zot --version` across PATH and candidate locations

Why this shape

pi is an npm package installed in node_modules, so version detection must

fall back to reading its package manifest when --version is missing.

zot is a single Go binary, so a plain --version probe is correct.
pi/zot are optional; a host that only runs one agent runtime should

still produce a valid inventory.

Watchdog host status

crates/colibri-runtime/src/lib.rs implements the watchdog reader. It connects

over a Unix domain socket, sends {"cmd":"status"}\n, reads back one

newline-terminated JSON line, and normalizes the response into HostStatus.

Socket path resolution

The search order lets operators, services, and test harnesses override the

socket location without recompiling:

1. COLIBRI_WATCHDOG_SOCKET (explicit override)

2. COLIBRI_SERVICE_NAME (default clawdie) → {service}-watchdog.sock

3. TMP_IPC_DIR/{service}-watchdog.sock

4. AGENT_TMP_DIR/ipc/{service}-watchdog.sock or

CLAWDIE_TMP_DIR/ipc/{service}-watchdog.sock

5. $HOME/clawdie-ai/tmp/ipc/{service}-watchdog.sock

6. tmp/ipc/{service}-watchdog.sock (final fallback)

Wire protocol

Framing: one line, newline-terminated.
Request: {"cmd":"status"}\n.
Expected response: {"ok": true, "data": { ... watchful host fields ... }}.
Timeout: 2 seconds by default, overridable in WatchdogReadOptions.

Normalization rules

normalize_watchdog_status() in crates/colibri-runtime/src/lib.rs is defensive:

Missing fields default to "unknown" for strings, 0 for counters, and

false for booleans.

controlplane_status is lifted from controlplane.overallStatus.
The original raw object is preserved under HostStatus.raw so callers can

access fields Colibri does not yet model.

Golden fixtures

crates/colibri-contracts/tests/golden.rs parses committed inventory and

host-status manifests in manifests/ and round-trips them through the Rust

structs. Those fixtures come from real hosts (osa, domedog, debby, the

operator USB) and are treated as cross-platform source material.

Runtime inventory and host status

Runtime inventory and host status

Runtime inventory probe

Detection strategy

Why this shape

Watchdog host status

Socket path resolution

Wire protocol

Normalization rules

Golden fixtures

See also