clawdie/layered-soul
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
layered-soul/docs/CAPABILITY-ROUTING.md
Sam & Claude a5139b5f7f security(docs): mask Tailscale IPs + bot handles behind fleet.env 
Real tailnet IPs and Telegram bot handles were being committed in docs/
memories/skills. Scrubbed all tracked markdown to ${VAR} placeholders; real
values now live in fleet.env (gitignored) and stay live via 'tailscale status'.

- add fleet.env.example (committed) + fleet.env (gitignored); .gitignore *.env
- AGENTS.md + HOST-MATRIX: masking convention so it can't recur
- also: domedog registered as Colibri agent (image-render/ffmpeg/build lane);
  correct CAPABILITY-ROUTING example to real registered caps (domedog headless)

Past commits not rewritten (history moves to Codeberg at v1.0); this fixes HEAD.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-19 18:19:32 +02:00

4.9 KiB
Raw Blame History

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. The debby orchestrator reaches it over the tailnet.
  • 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.

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 (Pillow dropped on FreeBSD).

[DESIGN] Worked example: the tmux-screenshot skill

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

  1. FreeBSD image drops Pillow — stays lean (pkg-list carries only python312).
  2. The skill manifest declares required_capabilities: ["image-render"] (or screenshot).
  3. Only a Linux host advertises these — today domedog carries image-render/ffmpeg (osa dropped Pillow). screenshot additionally needs a display, so a headless host does not qualify for it.
  4. Colibri routes the task to a matching host automatically — proven 2026-06-19: 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 MCP-INTEGRATION.md for connecting agents to the board over MCP (Colibri as the coordination hub), AGENTS.md for the agent matrix, HOST-MATRIX.md for per-host facts, and TOOLCHAIN.md for runtime versions.