Cast Agent
Cast Agent is the Coven-native substrate manager and agent backend inside CastCodes.
Cast Agent
Cast Agent is the Coven-native substrate manager and AI agent backend inside CastCodes. It gives the first-party workspace a concrete backend for gateway health, streaming messages, local session visibility, and host-substrate collection.
Cast Agent is a client-side backend, not the daemon authority layer. It can collect context and submit requests, but Coven daemon validation still owns project-root, cwd, harness, session, and action safety.
Implemented Shape
The current CastCodes implementation already gives Cast Agent enough shape to document as a first-party architecture layer.
| Surface | Status | Purpose |
|---|---|---|
crates/cast_agent crate | Implemented | Standalone Cast Agent backend crate. |
| Dedicated Tokio runtime | Implemented | Runs gateway and substrate work off the UI thread. |
| Gateway health probe | Implemented | Tracks availability and powers status UI. |
| Gateway status pill | Implemented | Shows reachable/degraded state in the agent panel. |
| Coven Sessions section | Implemented | Lists active Coven sessions in the workspace. |
| Session click-through | Implemented | Opens a session row in a new CastCodes tab at the session cwd. |
| Streaming responses | Implemented | Streams gateway message chunks over WebSocket. |
| Host substrate bridge | Implemented | Collects active file, panes, cwd, git branch, and diagnostics for gateway requests. |
Substrate Inputs
| Input | Source | Use |
|---|---|---|
| Active file | Editor host | Gives the agent the focused file context. |
| Open panes | Workspace host | Shows visible sessions, tabs, cwd, and active pane state. |
| Shell cwd | Local substrate collector | Anchors requests in current project context. |
| Git branch | Local substrate collector | Adds repository state to the request context. |
| Recent diagnostics | LSP publishers | Surfaces errors and warnings without requiring manual copy/paste. |
| Optional pane context | Legacy bridge or host integration | Adds extra cockpit state when available, but never as a hard dependency. |
Gateway and Daemon Split
Cast Agent may talk to both Coven Gateway and the local Coven daemon. Keep those roles distinct in docs and client behavior.
| Target | Transport | Role | Authority posture |
|---|---|---|---|
| Coven Gateway | HTTP + WebSocket | Health checks, message requests, and streaming responses. | Not a replacement for local daemon validation. |
| Coven daemon | HTTP over local Unix socket | Session records, events, launch/input/kill behavior, and local runtime state. | Rust authority boundary. |
| Harness CLIs | Daemon-spawned PTY | Codex, Claude Code, and future harness execution. | Launched only through daemon validation. |
Degradation
Cast Agent should stay useful when remote or optional pieces are unavailable.
| Condition | Behavior |
|---|---|
| Gateway health check fails | Keep the agent panel usable and show a degraded status. |
| Session listing transport fails | Fall back to cached session data when available. |
| Optional pane bridge is absent | Return empty optional pane context instead of blocking the agent. |
| Daemon rejects a request | Surface the daemon error; do not retry by bypassing policy. |
Client Rule
Cast Agent can make Coven feel native inside CastCodes, but it must keep the same client rule as every other integration: improve UX locally, then submit structured requests to the authority layer.
Last updated on