feat(cast_agent): enforce the coven.daemon.v1 handshake

[BunsDev]

Description

What: Enforces the mandatory coven.daemon.v1 handshake on the Unix daemon transport. GET /api/v1/health responses are now classified per docs/CLIENT-INTEGRATION.md in OpenCoven/coven: apiVersion must equal "coven.daemon.v1", and the capabilities block is parsed and cached. The gateway tracks a ConnectionState (Unknown | Unreachable | Incompatible | Ready) instead of a bare bool; is_available() derives from it, and connection_state() is exposed through CastAgent, CastAgentRuntime, and the ai facade.

Why: Skipping the handshake means depending on undefined response shapes from a future daemon — any 2xx (even an HTML error page or a v2 daemon) previously read as "healthy". The version gate turns that into a distinct, user-explainable state. This also unblocks capability-gated features: panel surfaces can now ask connection_state().capabilities() instead of probing endpoints blind.

How:

• crates/cast_agent/src/handshake.rs (new) — response shapes (DaemonHealth, DaemonCapabilities) and the pure classify_health_response(status, body); additive daemon fields are ignored, missing fields degrade to "capability absent", never a parse error.
• crates/cast_agent/src/gateway.rs — health_probe() runs the classification on Unix and stores the outcome in an RwLock<ConnectionState> (was AtomicBool). The legacy TCP bridge predates the versioned contract and keeps its any-2xx semantics with conservatively empty capabilities.
• app/src/agent_panel/view/composer.rs — a daemon conversation's inactive composer now names the real fix: offline → Start it with `coven daemon start`.; version mismatch → "Update Coven or CastCodes." (selection is pure via DaemonLink + inactive_placeholder_for).
• CAST-AGENT.md — health endpoint + failure-mode docs updated.
• app/src/workspace/mod.rs — one-line ordering fix: the key-binding builder calls were overwriting the Trigger::Custom on the ToggleUnifiedAgentPanel binding, so Mac menu construction couldn't resolve the item name and a debug_assert aborted every debug build at boot (all UI integration tests included). with_custom_action now comes last, matching every other custom-action binding; the menu keystroke comes from custom_tag_to_keystroke.

Linked Issue

No tracked GitHub issue — this lands the handshake requirement from the Coven daemon client-integration contract (docs/CLIENT-INTEGRATION.md, OpenCoven/coven). Follows up #156 (wire CastCodes to the live daemon) and builds on the unified agent panel surface (#210, #216).

• The linked issue is labeled ready-to-spec or ready-to-implement. (n/a — no tracked issue)

Testing

Three layers of automated coverage, all CI-runnable:

• Unit — handshake::tests (8 tests): version match/mismatch/missing, unparseable body, non-2xx, additive-field tolerance, capability defaults.
• Socket — crates/cast_agent/tests/handshake_probe.rs (new, 4 tests): GatewayClient::health_probe() against an in-process stub daemon on a real Unix socket — contract health → Ready with cached capabilities; wrong apiVersion → Incompatible, recovering to Ready on the next probe; missing socket / HTTP 500 → Unreachable.
• Full-app integration — test_daemon_conversation_composer_names_daemon_fix (new, crates/integration/src/test/agent_panel.rs, registered in ui_tests.rs): boots the app, seeds a daemon conversation through the production refresh path, dispatches WorkspaceAction::OpenChatSession, and asserts the panel opens, binds LiveDaemon, and the composer placeholder names coven daemon start. Helpers live in app/src/integration_testing/agent_panel/.

Verified locally:

• cargo nextest run -p cast_agent — 58 passed (incl. the 4 new socket tests)
• cargo nextest run -p warp-app -E 'test(/agent_panel/)' — 4 passed (default features, i.e. the not(cast-agent) cfg)
• cargo clippy -p cast_agent -p ai --all-targets --tests -- -D warnings — clean
• cargo clippy -p warp-app --features cast-agent --all-targets -- -D warnings — clean (the cast-agent cfg)
• cargo clippy -p warp-app --features integration_tests,cast-agent --all-targets -- -D warnings — clean
• cargo clippy -p integration --all-targets -- -D warnings + cargo check -p integration --all-targets — clean
• cargo fmt -- --check, ./script/check_ai_attribution, ./script/check_rebrand — clean

Integration test executed locally: the abort that previously blocked every UI integration test on this machine was root-caused to the ToggleUnifiedAgentPanel binding losing its Trigger::Custom (see the workspace fix above). With the fix, test_daemon_conversation_composer_names_daemon_fix passes 3 consecutive runs via the integration binary, and the pre-existing baseline test_add_many_sessions passes again. Full workspace presubmit was not run; the targeted gates above cover every touched crate and both cast-agent cfg branches.

• Dogfooded against real daemons (in lieu of a hand-driven ./script/run pass — the default ./script/run build does not enable the cast-agent feature; the end-to-end integration test boots the real app UI instead):
  • Live daemon (Ready path): production GatewayClient over the auto-detected ~/.coven/coven.sock against the running coven daemon — health_probe() → Ready, api_version: coven.daemon.v1, full capabilities cached; is_available() flipped false→true.
  • Offline path: test_daemon_conversation_composer_names_daemon_fix boots the app and asserts the composer names coven daemon start.
  • Version-mismatch path: socket tests drive Incompatible → recovery on a real Unix socket; inactive_placeholder_names_the_daemon_fix pins the "Update Coven or CastCodes." copy.

Review Follow-ups

• 81052466 — is_available() reads readiness through the RwLock guard instead of cloning the full ConnectionState on every poll/render (review thread).
• 084af73c — two fixes from a deeper review pass:
  • Handshake now gates the background loops. The session/familiar refresh loop previously polled /api/v1/sessions unconditionally, even against a daemon classified Incompatible. Each cycle now re-probes health first and skips the fetches unless the daemon answered Ready. New regression test refresh_loop_never_polls_sessions_while_daemon_is_off_contract (path-counting stub daemon: /health keeps polling, /sessions is never touched while off-contract).
  • Windows build fix. handshake::{self, ...} was only used inside cfg(unix) branches and tripped -D warnings on the Windows clippy job; the module import is now #[cfg(unix)], matching the existing anyhow pattern. Verified with cargo check -p cast_agent --target x86_64-pc-windows-msvc.

Updated verification at HEAD: cargo nextest run -p cast_agent 63/63, clippy (-D warnings) clean, Windows cross-check clean, integration test passing.

Agent Mode

• CastCodes Agent Mode — PR via CastCodes. Join OpenCoven on Discord for support.

CHANGELOG-IMPROVEMENT: The agent panel now tells you exactly how to recover when the Coven daemon is offline (coven daemon start) or speaks an incompatible API version, instead of showing a generic message.

[Copilot]

Pull request overview

This PR hardens CastCodes’ Coven daemon integration by enforcing the mandatory coven.daemon.v1 handshake on the Unix-socket transport, upgrading availability tracking from a boolean to a structured ConnectionState, and wiring that state through cast_agent → ai facade → unified agent panel UI (including more actionable inactive-composer placeholders). It also adds unit/socket/integration coverage and fixes a Mac keybinding builder ordering issue that could abort debug builds.

Changes:

• Add cast_agent::handshake with DaemonHealth/DaemonCapabilities and pure classify_health_response, and have the Unix transport health probe cache a ConnectionState (Unknown | Unreachable | Incompatible | Ready) instead of a bool.
• Expose connection_state() through CastAgent, CastAgentRuntime, and crates/ai, and update the unified agent panel composer to select offline/incompatible placeholders via a pure DaemonLink projection.
• Add new socket-level handshake probe tests and a full-app integration test asserting the daemon-offline composer placeholder names coven daemon start.

Verdict

Request changes (per repo review guidance for UI-impacting changes): please include manual testing evidence (screenshot/screen recording) for the updated unified agent panel placeholder behavior. Additionally, address the GatewayClient::is_available() performance regression noted in review comments (it currently clones the full ConnectionState).

Reviewed changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
crates/integration/tests/integration/ui_tests.rs	Registers the new agent panel integration test in the UI suite.
crates/integration/src/test/agent_panel.rs	Adds an end-to-end integration test for the daemon-offline composer placeholder flow.
crates/integration/src/test.rs	Wires the new agent_panel test module into the integration test harness exports.
crates/integration/src/bin/integration.rs	Registers the new integration test in the standalone integration binary.
crates/cast_agent/tests/handshake_probe.rs	Adds Unix-socket end-to-end tests asserting health_probe() enforces the handshake and caches capabilities/state.
crates/cast_agent/src/runtime.rs	Exposes CastAgentRuntime::connection_state() and a global connection_state() convenience accessor.
crates/cast_agent/src/lib.rs	Exports handshake types/constants and the new connection_state() API through the crate surface.
crates/cast_agent/src/handshake.rs	Introduces handshake models and classification logic for /api/v1/health.
crates/cast_agent/src/gateway.rs	Replaces AtomicBool availability with RwLock<ConnectionState> and enforces the handshake on Unix transport.
crates/cast_agent/src/agent.rs	Exposes CastAgent::connection_state() for UI-facing consumers.
crates/ai/src/lib.rs	Re-exports handshake state/types and connection_state() through the ::ai::cast_agent facade.
CAST-AGENT.md	Updates health/handshake documentation and failure-mode behavior.
app/src/workspace/mod.rs	Fixes keybinding builder ordering so with_custom_action() isn’t overwritten (Mac menu name resolution).
app/src/integration_testing/mod.rs	Exposes a new integration_testing::agent_panel helper module.
app/src/integration_testing/agent_panel/mod.rs	Adds integration-test helpers for seeding/opening daemon conversations and reading composer placeholder selection.
app/src/agent_panel/view/composer.rs	Adds DaemonLink projection and pure placeholder selection (inactive_placeholder_for) keyed off handshake outcome.
app/src/agent_panel/view_tests.rs	Adds unit test coverage for the new placeholder selection logic.
app/src/agent_panel/strings.rs	Adds new user-facing offline/incompatible daemon placeholder strings.
.gitignore	Ignores /.playwright-cli artifacts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 2 comments.

[Copilot]

Copilot reviewed 18 out of 19 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

crates/cast_agent/src/gateway.rs:241

• The doc comment on GatewayClient::connection_state() says it is "Cheap" to call on the UI thread, but the implementation clones the full ConnectionState (including Strings inside DaemonHealth/DaemonCapabilities). That clone can allocate on frequent UI calls, so the comment is misleading; either clarify that this accessor clones (and is_available() is the cheap readiness check), or introduce a lightweight projection accessor for render loops.

    /// Latest handshake outcome. Cheap, sync, safe on the UI thread.
    pub fn connection_state(&self) -> ConnectionState {
        self.state
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner())