diff --git a/docs/MULTI-AGENT-HOST-PLAN.md b/docs/MULTI-AGENT-HOST-PLAN.md index 969f9e6..c24613e 100644 --- a/docs/MULTI-AGENT-HOST-PLAN.md +++ b/docs/MULTI-AGENT-HOST-PLAN.md @@ -46,14 +46,14 @@ The multi-host stack lives **outside the Rust daemon**: ### Socket command inventory (17 commands, all Unix-socket) -| Category | Commands | -|----------|----------| -| Daemon | `status`, `glasspane-snapshot`, `set-cost-mode` | -| Session | `list-sessions`, `get-session`, `compact-session` | -| Agent process | `spawn-agent`, `kill-agent` | -| Board | `list-tasks`, `create-task`, `transition-task`, `claim-task`, `intake-task` | -| Agent registry | `register-agent`, `list-agents` | -| Skills | `list-skills`, `register-skill` | +| Category | Commands | +| -------------- | --------------------------------------------------------------------------- | +| Daemon | `status`, `glasspane-snapshot`, `set-cost-mode` | +| Session | `list-sessions`, `get-session`, `compact-session` | +| Agent process | `spawn-agent`, `kill-agent` | +| Board | `list-tasks`, `create-task`, `transition-task`, `claim-task`, `intake-task` | +| Agent registry | `register-agent`, `list-agents` | +| Skills | `list-skills`, `register-skill` | ### CLI surface (10 of 17 commands exposed) @@ -79,15 +79,15 @@ socket calls. ### What is NOT tested -| # | Gap | Severity | Linux-doable? | -|---|-----|----------|---------------| -| 1 | **Multi-agent task-board contention** — `pick_agent` only tested with 0-1 agents; no capability-based multi-agent assignment test; no same-agent-multiple-tasks test | High | Yes | -| 2 | **CLI surface gaps** — `claim-task`, `transition-task`, `register-agent`, `list-agents` have no CLI; remote agents forced to use raw Python | Medium | Yes | -| 3 | **Agent presence model** — no `host` column, no `last_seen`, no heartbeat/lease; cannot detect stale remote agents | High | Yes (schema change) | -| 4 | **Remote-safe task claim** — `claim_task` is a blind UPDATE, no concurrency safety, no lease/TTL | Medium | Yes | -| 5 | **Python polling scripts** — `colibri_poll.py` and `colibri_task_done.py` have zero test coverage | Medium | Yes | -| 6 | **TCP bridge round-trip** — socat bridge untested end-to-end | Medium | Partial (needs socat or FreeBSD) | -| 7 | **Cross-host coordination** — no test simulates a remote agent claiming/transitioning a task over the bridge | High | FreeBSD only | +| # | Gap | Severity | Linux-doable? | +| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------- | +| 1 | **Multi-agent task-board contention** — `pick_agent` only tested with 0-1 agents; no capability-based multi-agent assignment test; no same-agent-multiple-tasks test | High | Yes | +| 2 | **CLI surface gaps** — `claim-task`, `transition-task`, `register-agent`, `list-agents` have no CLI; remote agents forced to use raw Python | Medium | Yes | +| 3 | **Agent presence model** — no `host` column, no `last_seen`, no heartbeat/lease; cannot detect stale remote agents | High | Yes (schema change) | +| 4 | **Remote-safe task claim** — `claim_task` is a blind UPDATE, no concurrency safety, no lease/TTL | Medium | Yes | +| 5 | **Python polling scripts** — `colibri_poll.py` and `colibri_task_done.py` have zero test coverage | Medium | Yes | +| 6 | **TCP bridge round-trip** — socat bridge untested end-to-end | Medium | Partial (needs socat or FreeBSD) | +| 7 | **Cross-host coordination** — no test simulates a remote agent claiming/transitioning a task over the bridge | High | FreeBSD only | --- @@ -100,12 +100,12 @@ socket calls. Existing tests cover: best match (2 agents, different caps), offline exclusion, no-match, empty-required. Add: -| Test | What it proves | -|------|---------------| +| Test | What it proves | +| -------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `test_pick_agent_partial_match_wins_over_no_match` | Agent with `["rust","freebsd"]` beats agent with `["python"]` for required `["freebsd"]` | -| `test_pick_agent_tie_breaking` | Two agents with same score — verify deterministic tie-break (later name wins) | -| `test_pick_agent_multiple_required_capabilities` | Required `["rust","freebsd"]` — agent with both beats agent with one | -| `test_pick_agent_active_status_eligible` | `status: "active"` is treated same as `"idle"` (both eligible) | +| `test_pick_agent_tie_breaking` | Two agents with same score — verify deterministic tie-break (later name wins) | +| `test_pick_agent_multiple_required_capabilities` | Required `["rust","freebsd"]` — agent with both beats agent with one | +| `test_pick_agent_active_status_eligible` | `status: "active"` is treated same as `"idle"` (both eligible) | #### 1b. Multi-agent board integration test — new file `crates/colibri-daemon/tests/multi_agent_board.rs` @@ -150,6 +150,7 @@ tasks. #### 2a. Merge `feat/cli-register-agent` (existing branch, 64 lines, client-only) The branch is clean and ready: + - `Command::RegisterAgent { name, capabilities }` + `Command::ListAgents` - `parse_capabilities()` helper (reuses `--capability`/`--capabilities` pattern) - `DaemonClient::register_agent()` + `DaemonClient::list_agents()` @@ -170,6 +171,7 @@ colibri transition-task --task-id --status done|failed ``` Implementation: + - Add `Command::ClaimTask { task_id, agent_id }` and `Command::TransitionTask { task_id, status }` variants - Add `DaemonClient::claim_task()` and `DaemonClient::transition_task()` @@ -209,17 +211,17 @@ mesh.** ## Summary -| Phase | What | Files | Linux? | Status | -|-------|------|-------|--------|--------| -| 1a | `pick_agent` unit tests | `scheduler.rs` tests | Yes | Ready | -| 1b | Multi-agent board integration test | `tests/multi_agent_board.rs` (new) | Yes | Ready | -| 1c | Same-capability multi-task test | Same file | Yes | Ready | -| 2a | Merge `feat/cli-register-agent` | `colibri.rs` + `lib.rs` | Yes | Branch exists | -| 2b | Add `claim-task` + `transition-task` CLI | `colibri.rs` + `lib.rs` | Yes | Ready | -| 2c | CLI parse tests | `colibri.rs` tests | Yes | Ready | -| 3 | Agent presence schema | `schema.rs` + `lib.rs` + `socket.rs` | Yes | Deferred | -| 4 | Polling workflow test | `tests/` | Yes | Deferred (needs Phase 2) | -| 5 | TCP bridge validation | FreeBSD host | No | FreeBSD lane | +| Phase | What | Files | Linux? | Status | +| ----- | ---------------------------------------- | ------------------------------------ | ------ | ------------------------ | +| 1a | `pick_agent` unit tests | `scheduler.rs` tests | Yes | Ready | +| 1b | Multi-agent board integration test | `tests/multi_agent_board.rs` (new) | Yes | Ready | +| 1c | Same-capability multi-task test | Same file | Yes | Ready | +| 2a | Merge `feat/cli-register-agent` | `colibri.rs` + `lib.rs` | Yes | Branch exists | +| 2b | Add `claim-task` + `transition-task` CLI | `colibri.rs` + `lib.rs` | Yes | Ready | +| 2c | CLI parse tests | `colibri.rs` tests | Yes | Ready | +| 3 | Agent presence schema | `schema.rs` + `lib.rs` + `socket.rs` | Yes | Deferred | +| 4 | Polling workflow test | `tests/` | Yes | Deferred (needs Phase 2) | +| 5 | TCP bridge validation | FreeBSD host | No | FreeBSD lane | **Immediate scope:** Phases 1-2. All testable on Linux with `cargo test` + `cargo clippy` gate. No FreeBSD dependency for implementation. diff --git a/docs/README.md b/docs/README.md index f662b94..68d90b1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,17 +2,17 @@ A quick-reference guide to every document in this folder. -| Document | One-liner | Audience | -| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | --------------- | -| [`CLAWDIE-INSTALLER-HANDOFF.md`](CLAWDIE-INSTALLER-HANDOFF.md) | FreeBSD validation handoff for the `clawdie` installer | Codex (FreeBSD) | -| [`CLAWDIE-STUDIO-PROPOSAL.md`](CLAWDIE-STUDIO-PROPOSAL.md) | Zed/Claude Code + control plane integration (bare-metal deployment option) | Sam & agents | -| [`COLIBRI-EXTERNAL-MCP-PROTOTYPE.md`](COLIBRI-EXTERNAL-MCP-PROTOTYPE.md) | Colibri as MCP host for external stdio servers (jailed, 3-tier trust) | Agents | -| [`COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md`](COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md) | FreeBSD jail confinement for spawned agents — accepted & implemented | Rust agents | -| [`COLIBRI-SKILLS-PLAN.md`](COLIBRI-SKILLS-PLAN.md) | Skills catalog roadmap: read-only Phase 1, write-gated Phase 2+ | Agents | -| [`COLIBRI-TOKENOMICS-TRIFECTA.md`](COLIBRI-TOKENOMICS-TRIFECTA.md) | Strategic vision: useful tokens, cost-per-intelligence, measurement | All | -| [`HEADROOM-SIDECAR.md`](HEADROOM-SIDECAR.md) | Optional `headroom-ai` tool-result compression sidecar | Agents | -| [`INTEGRATION-LAYERED-SOUL.md`](INTEGRATION-LAYERED-SOUL.md) | How Colibri consumes `layered-soul` reviewed context today vs planned | Agents | -| [`ISO-ACCEPTANCE-RUNBOOK.md`](ISO-ACCEPTANCE-RUNBOOK.md) | Post-boot acceptance commands after staging Colibri into an ISO | Codex (FreeBSD) | -| [`ISO-SERVICE-LAYOUT.md`](ISO-SERVICE-LAYOUT.md) | `rc.conf` service layout for the ISO image | All | -| [`MULTI-AGENT-HOST-PLAN.md`](MULTI-AGENT-HOST-PLAN.md) | **Current sprint**: multi-agent task-board tests + CLI surface gaps | All agents | -| [`PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](PRIORITY-HANDOFF-ISO-SPAWN-COST.md) | ISO boot validation, Pi spawn path, cost mode enforcement (P2/P3 done) | All agents | +| Document | One-liner | Audience | +| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | --------------- | +| [`CLAWDIE-INSTALLER-HANDOFF.md`](CLAWDIE-INSTALLER-HANDOFF.md) | FreeBSD validation handoff for the `clawdie` installer | Codex (FreeBSD) | +| [`CLAWDIE-STUDIO-PROPOSAL.md`](CLAWDIE-STUDIO-PROPOSAL.md) | Zed/Claude Code + control plane integration (bare-metal deployment option) | Sam & agents | +| [`COLIBRI-EXTERNAL-MCP-PROTOTYPE.md`](COLIBRI-EXTERNAL-MCP-PROTOTYPE.md) | Colibri as MCP host for external stdio servers (jailed, 3-tier trust) | Agents | +| [`COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md`](COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md) | FreeBSD jail confinement for spawned agents — accepted & implemented | Rust agents | +| [`COLIBRI-SKILLS-PLAN.md`](COLIBRI-SKILLS-PLAN.md) | Skills catalog roadmap: read-only Phase 1, write-gated Phase 2+ | Agents | +| [`COLIBRI-TOKENOMICS-TRIFECTA.md`](COLIBRI-TOKENOMICS-TRIFECTA.md) | Strategic vision: useful tokens, cost-per-intelligence, measurement | All | +| [`HEADROOM-SIDECAR.md`](HEADROOM-SIDECAR.md) | Optional `headroom-ai` tool-result compression sidecar | Agents | +| [`INTEGRATION-LAYERED-SOUL.md`](INTEGRATION-LAYERED-SOUL.md) | How Colibri consumes `layered-soul` reviewed context today vs planned | Agents | +| [`ISO-ACCEPTANCE-RUNBOOK.md`](ISO-ACCEPTANCE-RUNBOOK.md) | Post-boot acceptance commands after staging Colibri into an ISO | Codex (FreeBSD) | +| [`ISO-SERVICE-LAYOUT.md`](ISO-SERVICE-LAYOUT.md) | `rc.conf` service layout for the ISO image | All | +| [`MULTI-AGENT-HOST-PLAN.md`](MULTI-AGENT-HOST-PLAN.md) | **Current sprint**: multi-agent task-board tests + CLI surface gaps | All agents | +| [`PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](PRIORITY-HANDOFF-ISO-SPAWN-COST.md) | ISO boot validation, Pi spawn path, cost mode enforcement (P2/P3 done) | All agents |