boocode/openspec/changes/v2-3-provider-lifecycle/proposal.md

v2.3 Provider lifecycle (Paseo-style registry)

Status: ✅ Shipped across v2.5.4–v2.5.13 (2026-05-29; reconciled 2026-05-31) — all 6 phases live; only the 3 optional Tier-2 items deferred
Depends on: v2.2 Paseo providers (snapshot, modes, commands, ACP dispatch)
Reference fork: /opt/forks/paseo
Related deferred work: docs/DEFERRED-WORK.md §2 (cold-probe skip)

Shipped mapping (reconciled 2026-05-31): Phase 1 → v2.5.4, Phase 2 → v2.5.5, Phase 3 → v2.5.6, Phase 4 → v2.5.12, Phase 5 → v2.5.13, Phase 6 docs → v2.5.13/v2.5.14. Deferred (tasks O.1–O.3): WS provider_snapshot_updated frame, available_agents.enabled column, diagnostic row-click modal — tracked in docs/DEFERRED-WORK.md. (Cursor was retired in v2.5.3, so the success-criterion mention below is historical.)

Why

BooCode v2.2 copied Paseo’s snapshot wire shape (modes, thinking, commands) but not Paseo’s provider lifecycle:

• Providers are hardcoded in provider-registry.ts; adding one requires a code change and redeploy.
• Uninstalled agents disappear from the picker instead of showing “not installed.”
• There is no enable/disable toggle — every probed binary appears.
• Every snapshot cache miss runs a full cold ACP probe for all installed agents (5–30s).

Paseo’s model (see /opt/forks/paseo/public-docs/providers.md) treats providers as registered entries in a config-backed registry, then probes the machine for readiness, then lets the user toggle visibility. That fits a one-person homelab: edit JSON, refresh, flip a switch — no TypeScript deploy for each new ACP CLI.

Scope

In scope

1. Config file /data/coder-providers.json — add/disable/custom ACP providers without code changes
2. Merged registry — built-ins + config overrides at runtime
3. Snapshot lifecycle — loading | ready | unavailable | error; always list registered providers; enabled flag
4. Two-tier probe — fast binary check vs slow ACP session (DB last_probed_at gate)
5. Generic ACP dispatch — config entries spawn via { command, env } without new acp-spawn cases
6. HTTP API — read/patch config, per-provider refresh, optional diagnostic
7. Web UI — settings drawer: provider list, enable toggle, refresh, add-from-catalog (curated ~5–10 entries)
8. Tests + docs — snapshot unit tests, BOOCODER.md refresh contract

Out of scope (this batch)

• Full Paseo ACP catalog (30+ agents) — curate a small local catalog only
• React Native settings app port
• Replacing acp-dispatch.ts with Paseo’s ACPAgentClient hierarchy
• Voice provider stack
• MCP list_providers / inspect_provider tools (Tier 2 follow-up)
• WS push of snapshot updates (Tier 2 follow-up)

Non-goals

• Multi-user provider prefs (single-user homelab)
• Installing CLIs from the UI (link to install instructions only, like Paseo)
• Removing available_agents table — keep it as probe cache, extend with enabled or mirror config

Success criteria

• ✅ Add amp-acp via catalog → appears in picker after refresh without coder redeploy (catalog smoke-test entry; per boocode_code_review_v2.md §5m, Amp itself is paid-cloud, not a usable local provider)
• ✅ Disable goose in settings → gone from picker, still visible as “Disabled” in settings
• ✅ opencode not on PATH → shows “Not installed” in settings, hidden from picker
• ✅ Second snapshot open within warm window completes in <500ms (no ACP spawns)
• ✅ POST /api/providers/refresh still runs full cold probe
• ✅ Existing v2.2 dispatch unchanged for built-ins (opencode, claude, qwen, goose — cursor + copilot retired v2.5.3)

Deliverables

Doc	Purpose
design.md	Full architecture, schemas, file map, Tier 3 reference
tasks.md	Numbered implementation checklist