layered-soul/docs/CAPABILITY-ROUTING.md

# Capability-Based Task Routing

**LIVE VS PLANNED: this document describes the intended architecture.** Colibri's capability matcher exists (Colibri daemon) and works for a single-host daemon/agent pool. Cross-host routing across debby/domedog/osa is **not live yet** — that is the next wiring step. 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**.

> **Important caveat:** the daemon listens on a **local Unix socket only**. This means today the agent pool is per-host. An agent on osa cannot pick up a task from debby's daemon automatically.

## [PLANNED] Cross-host topology

To route *across* hosts, agents on every host must be visible to one scheduler. Not implemented yet. Recommended approach:

- **Central orchestrator daemon on debby (Hermes).** Agents on domedog/osa reach its
  socket over Tailscale (forwarded via SSH/`socat`). Hermes is already the designated
  orchestrator, so this matches the agent matrix.
- Alternative (heavier, deferred): 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. Example from the current fleet:

- **domedog / debby (Linux):** `linux`, `docker`, `gui`, `screenshot`, `image-render`, …
- **osa (FreeBSD):** `freebsd`, `freebsd-jail`, `zfs`, `rust`, … (no `screenshot`/`image-render`)

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

This illustrates the intended routing flow (requires [PLANNED] cross-host topology above):

1. FreeBSD image drops Pillow — stays lean (`pkg-list` carries only `python312`).
2. The skill manifest declares `required_capabilities: ["screenshot"]` (or `image-render`).
3. Only Linux hosts advertise `screenshot` (Pillow is trivial there).
4. Colibri routes any screenshot task to debby/domedog automatically; if both are offline
   the task parks until one returns.

The capability moved hosts. It was never lost.

_See [`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._