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.

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 for the agent matrix, HOST-MATRIX.md for per-host facts, and TOOLCHAIN.md for runtime versions.