layered-soul/docs/CAPABILITY-ROUTING.md

# Capability-Based Task Routing

**LIVE VS PLANNED.** Colibri's capability matcher exists (Colibri daemon) and works for a single-host daemon/agent pool. **Cross-host transport is now LIVE** (2026-06-19): a `socat` bridge over Tailscale exposes osa's daemon, and a poller/worker loop runs assigned tasks across hosts — validated on the debby↔osa lane (colibri PR #83). Full capability-scored routing across all three hosts is maturing on top of this transport. Sections below are labelled `[LIVE]` or `[PLANNED]`.

**Principle: a tool that one OS can't support is not a loss — it's a routing
constraint.** In a multi-agent, multi-OS fleet we don't force every capability onto
every host. We let each host advertise what it can do, let each task declare what it
needs, and let the scheduler send the task to a host that qualifies. FreeBSD stays lean;
the capability simply lives where it's cheap.

## [LIVE] What Colibri already provides (single host)

The matching engine exists today in `colibri-daemon` — this is working, per-host:

- **Agents carry capability tags** — `agents.capabilities` (JSON array) in the store
  (`colibri-store` schema); registered via `colibri` client / `--capabilities`.
- **Tasks declare requirements** — jobs and intake requests carry `required_capabilities`
  (`colibri intake-task --capabilities <csv>`).
- **The scheduler matches** — `pick_agent(required, agents)` scores each idle/active agent
  with `capability_match_score` and picks the best fit.
- **Unmatched = parked, not failed** — if requirements are non-empty and no online agent
  matches, `pick_agent` returns `None`: the task is created but left **unassigned until a
  capable agent appears**.

> **Note:** the daemon itself listens on a **local Unix socket only**. Cross-host reach is
> provided by the bridge below, not by the daemon binding a network port directly.

## [LIVE] Cross-host topology

Implemented 2026-06-19 (colibri PR #83), using the `socat`-over-Tailscale approach:

- **`socat` bridge** (`colibri_bridge` rc.d, daemon(8)-supervised) maps osa's daemon Unix
  socket to a TCP port on the **Tailscale interface only** (`${OSA_TS_IP}:9190`, never
  `0.0.0.0`), with a `pf` rule on `tailscale0`. **osa is the always-on VPS** and hosts the
  board + orchestrator (hermes-osa); agents on debby/domedog reach it over the tailnet. (debby
  is an intermittent laptop — a client, never the hub.)
- **Poller/worker loop** — `colibri_poll.py` (filters by agent UUID) and
  `colibri_task_done.py` (transition-task), driven on the live 2 min / 5 min cadence by
  Hermes' internal scheduler (see `packaging/freebsd/colibri-agent-loop.md`), not OS cron.
- **Validated** on the debby↔osa lane (real tasks completed end-to-end). **domedog joined
  2026-06-19** via the same pattern — a client-side `socat` shim → osa `${OSA_TS_IP}:9190`.
- Alternative (heavier, not pursued): daemon-to-daemon federation.

## [LIVE] Capability vocabulary (initial)

| Piece                 | Status                                         | Action                         |
| --------------------- | ---------------------------------------------- | ------------------------------ |
| Capability vocabulary | tags are free-form (`rust`, `python`, `linux`) | Agree a shared tag set (below) |

Flat, explicit tags — the matcher does exact string comparison, no implied hierarchy.
Sourced from the probe and recorded per host in [`HOST-MATRIX.md`](./HOST-MATRIX.md).

| Category  | Tags                                 |
| --------- | ------------------------------------ |
| OS        | `linux`, `freebsd`                   |
| Isolation | `docker`, `freebsd-jail`             |
| Display   | `gui`, `screenshot`, `wayland`       |
| Hardware  | `gpu`, `zfs`                         |
| Runtime   | `python3.12`, `node24`, `rust`, `go` |
| Media     | `ffmpeg`, `pillow`/`image-render`    |

Hosts advertise only what they truly have. Actual registered agents (2026-06-19):

- **domedog (Linux, headless):** `linux`, `python3.12`, `rust`, `go`, `node`, `ffmpeg`,
  `image-render` — the media/compute lane. **No** `screenshot`/`gui` (headless VM), no `docker`.
- **debby / hermes-debby (Linux):** `linux`, `docker`, `shell`, `gateway`, `hermes`, `tailscale`.
- **osa / hermes-osa (FreeBSD):** `freebsd`, `shell`, `gateway`, `tailscale`, `rc.d`, `pf`,
  `nginx`, `acme`, `hermes` — no `image-render` (headless server; `py311-pillow` not installed
  there). The FreeBSD operator image enables it via `py311-pillow` (below).

## [DESIGN] Worked example: the tmux-screenshot skill

This illustrates the routing flow (now runnable over the [LIVE] cross-host topology above):

1. The FreeBSD operator image ships `py311-pillow` (clawdie-iso #85), so
   `clawdie-join-hive.sh` advertises `image-render` (Pillow on `python3` = 3.11) and
   `screenshot` when a display is present.
2. The skill manifest declares `required_capabilities: ["image-render"]` (or `screenshot`).
3. Both **domedog** (Linux) and the **FreeBSD operator image** advertise `image-render`.
   `screenshot` also needs a display, so a _headless_ host (domedog, osa) does not qualify —
   the operator image, with its XFCE session, does.
4. Colibri routes the task to a matching host automatically — **proven 19.jun.2026: an
   `image-render` task routed to domedog**; with no match it parks until a capable agent appears.

The capability moved hosts. It was never lost.

_See [`HIVE-ONBOARDING.md`](./HIVE-ONBOARDING.md) for the hive-onboarding vision built on
this routing layer, [`MCP-INTEGRATION.md`](./MCP-INTEGRATION.md) for connecting agents to the
board over MCP, [`AGENTS.md`](../AGENTS.md) for the agent matrix,
[`HOST-MATRIX.md`](./HOST-MATRIX.md) for per-host facts, and
[`TOOLCHAIN.md`](./TOOLCHAIN.md) for runtime versions._