prospero_types/

api.rs

//! Control-plane request/response DTOs — the write half of the HTTP contract.
//!
//! These live here rather than in `prospero-api` for the same reason the read
//! model moved in #98: `prospero-api` pulls axum, tokio, and `prospero-core`, so
//! nothing in it compiles to `wasm32`, and the Dioxus dashboard would otherwise
//! have to hand-duplicate every one of these types — reintroducing exactly the
//! client/server drift Rust/WASM was chosen to avoid.
//!
//! Each type derives **both** `Serialize` and `Deserialize`, so one definition
//! serves both ends: the server deserialises a request body the client
//! serialised, and the client deserialises a response the server serialised.
//! `prospero-api` re-exports all of them from their original paths, so serde
//! output and every import site are unchanged.
//!
//! Behaviour stays out: mapping a [`SpawnBody`] onto `prospero-core`'s
//! `SpawnRequest` is an adapter concern and lives in `prospero-api`, per
//! ADR 0006's one-directional `api → core` rule.

use serde::{Deserialize, Serialize};

use crate::model::{
    PermissionPosture, ProviderInfo, RepoProviderConfig, Source, WorkspaceConfig, WorkspaceHealth,
    WorkspaceSourceSpec, WorkspaceStatusInfo,
};

/// Backend capability signal for the dashboard (`GET /api/capabilities`).
///
/// Fixed for the process lifetime — the dashboard fetches it once and gates its
/// admin/registry controls on it, so it never offers operations the active
/// backend can't serve. (#99)
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(schemars::JsonSchema))]
pub struct Capabilities {
    /// Whether the workspace admin/config plane (add / remove / set-config) is
    /// available. `true` for the local backend (registry) and, as of #142, for
    /// k8s (a `Workspace`-CR editor). Only `false` if a backend leaves the
    /// `admin` seam unwired.
    pub admin: bool,
    /// Whether workspace create/config completes asynchronously — the dashboard
    /// uses this to (a) render the k8s config UI (named-provider list +
    /// Secret-reference credentials, vs the local single-provider env-var form)
    /// and (b) treat a save as *accepted, reconciling* rather than *done*.
    /// `false` for local, `true` for k8s. (#143)
    pub async_workspace_ops: bool,
}

/// Body for `POST /api/workspaces`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(schemars::JsonSchema))]
pub struct AddWorkspaceBody {
    /// Operator-chosen short name.
    pub name: String,
    /// LocalFleet checkout path. Ignored under k8s (sources come from `config`),
    /// so k8s requests may omit it.
    #[serde(default)]
    pub root: String,
    /// Backend-neutral initial configuration. Local reads the flattened
    /// single-provider/env subset; k8s reads sources/providers/etc.
    #[serde(default)]
    pub config: WorkspaceConfig,
}

/// Body for `PUT /api/workspaces/{name}/config`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(schemars::JsonSchema))]
pub struct SetConfigBody(pub WorkspaceConfig);

/// Body for `POST /api/workspaces/{repo}/agents`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(schemars::JsonSchema))]
pub struct SpawnBody {
    /// Initial prompt / task.
    pub prompt: String,
    /// Optional label.
    #[serde(default)]
    pub label: Option<String>,
    /// Optional model override.
    #[serde(default)]
    pub model: Option<String>,
    /// Isolation mode: `"worktree"` (default) or `"shared"`.
    #[serde(default)]
    pub isolation: Option<String>,
    /// Optional tool allowlist.
    #[serde(default)]
    pub tool_allowlist: Option<Vec<String>>,
    /// Run the agent in interactive mode (awaits operator input).
    #[serde(default)]
    pub interactive: bool,
    /// Optional agent-template / frontmatter markdown file path (#6).
    #[serde(default)]
    pub frontmatter_path: Option<String>,
    /// Which named workspace provider to bind (k8s config plane →
    /// `CalibanTask.providerRef`). `None` ⇒ the workspace's default (#142).
    #[serde(default)]
    pub provider_ref: Option<String>,
    /// Kill the agent after this many seconds of wall-clock time (#221).
    /// Absent ⇒ no limit. Enforced by prospero, not by the agent.
    #[serde(default)]
    pub timeout_secs: Option<u64>,
    /// How this session handles tool calls needing permission (#238). Absent ⇒
    /// [`PermissionPosture::Supervised`]. Asking for
    /// [`PermissionPosture::Unattended`] requires an `admin`-scope credential
    /// (ADR-0010); the handler rejects it otherwise.
    #[serde(default)]
    pub permission_posture: PermissionPosture,
}

impl SpawnBody {
    /// Whether this spawn should get an isolated git worktree.
    ///
    /// Isolation defaults to worktree; only the explicit string `"shared"` opts
    /// out. Kept here (not in the api adapter) because it is the *meaning of the
    /// field*, and both ends need to agree on it — the dashboard reads it back
    /// to render the isolation control.
    #[must_use]
    pub fn isolation_worktree(&self) -> bool {
        !matches!(self.isolation.as_deref(), Some("shared"))
    }
}

/// Response for a successful spawn.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(schemars::JsonSchema))]
pub struct SpawnedResponse {
    /// New agent id.
    pub agent_id: String,
    /// Owning workspace.
    pub workspace: String,
    /// Whether the agent runs in an isolated worktree.
    pub isolated: bool,
    /// Whether this request actually started a new agent, as opposed to
    /// resolving to one that was already running (#190).
    ///
    /// Spawning is idempotent, and under k8s the `CalibanTask` name is derived
    /// from the spec — so re-submitting an identical prompt attaches to the
    /// existing run. Clients must distinguish the two, or they report a launch
    /// that never happened.
    ///
    /// Defaults to `true` so a response from a pre-#190 daemon deserializes to
    /// the behaviour clients already assumed.
    #[serde(default = "default_created")]
    pub created: bool,
}

/// `SpawnedResponse::created`'s default — see that field.
fn default_created() -> bool {
    true
}

/// Body for `POST /api/agents/{id}/input`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(schemars::JsonSchema))]
pub struct AgentInputBody {
    /// Message text to inject into the interactive agent.
    pub text: String,
}

/// Response for `POST /api/agents/{id}/respawn`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(schemars::JsonSchema))]
pub struct RespawnedResponse {
    /// The new agent id.
    pub agent_id: String,
}

/// Payload of a `gap` SSE event on `GET /api/agents/{id}/stream`.
///
/// The bus dropped `skipped` events after `last_seq` because the subscriber
/// lagged (#28). The stream self-heals by replaying from the store, but the
/// signal is still sent so a client can say "some output was missed" rather
/// than silently rendering a discontinuous timeline.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(schemars::JsonSchema))]
pub struct GapSignal {
    /// How many events were dropped.
    pub skipped: u64,
    /// The last sequence number delivered before the gap.
    pub last_seq: u64,
}

/// A workspace summary (no agents) for `GET /api/workspaces`.
///
/// The tail fields are populated by the k8s config plane (from `Workspace` CRs)
/// and skipped for the local backend, so local responses are byte-for-byte
/// unchanged.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(schemars::JsonSchema))]
pub struct WorkspaceSummary {
    /// Registry name.
    pub name: String,
    /// Workspace root.
    pub root: String,
    /// The source checkouts under the workspace root (1..N).
    pub sources: Vec<Source>,
    /// Caliband health.
    pub health: WorkspaceHealth,
    /// Number of known agents.
    pub agent_count: usize,
    /// Provider/environment config for this workspace.
    pub config: RepoProviderConfig,
    /// Human-friendly label (k8s config plane).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub display_name: Option<String>,
    /// The workspace's configured source **specs** (k8s config plane).
    ///
    /// `sources` above is the *discovered* view — name and path only — because
    /// that is all a local checkout has. A k8s workspace's sources come from a
    /// `Workspace` CR and additionally carry the git remote and ref, and the
    /// config editor needs those to round-trip an edit: without them an
    /// operator editing a workspace would face blank remote fields and have to
    /// retype every one from memory. Empty for the local backend, so local
    /// responses are unchanged.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub source_specs: Vec<WorkspaceSourceSpec>,
    /// Named providers agents can bind to (k8s config plane).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub providers: Vec<ProviderInfo>,
    /// Provider bound when an agent requests none (k8s config plane).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub default_provider: Option<String>,
    /// Reconciliation status (k8s config plane); absent for local.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub status: Option<WorkspaceStatusInfo>,
}

/// How many agents reached each terminal state.
///
/// These are [`crate::AgentStatus`]'s terminal variants, counted from
/// `status_changed` transitions — deliberately *not* `AgentFinished.outcome`,
/// which carries caliban's open-ended result subtype ("EndOfTurn",
/// "max_turns") and cannot be charted as a fixed set.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(schemars::JsonSchema))]
pub struct OutcomeCounts {
    /// Finished successfully.
    pub done: u64,
    /// Finished with an error.
    pub failed: u64,
    /// Stopped via kill.
    pub killed: u64,
    /// Supervisor restarted while active.
    pub crashed: u64,
    /// Runs prospero killed for passing their wall-clock deadline (#221).
    /// Also counted in `killed` — the kill is real; this says it was policy.
    #[serde(default)]
    pub timed_out: u64,
}

impl OutcomeCounts {
    /// Total agents that reached any terminal state.
    pub fn total(&self) -> u64 {
        self.done + self.failed + self.killed + self.crashed
    }
}

/// One day's usage within a workspace — the unit the fleet charts plot.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(schemars::JsonSchema))]
pub struct UsageBucket {
    /// UTC day, `YYYY-MM-DD`.
    pub day: String,
    /// Summed run cost in USD.
    pub cost_usd: f64,
    /// Summed turns.
    pub turns: u64,
    /// Terminal outcomes recorded on this day.
    pub outcomes: OutcomeCounts,
}

/// One workspace's totals over the whole window, plus its daily series.
///
/// `cost_usd` and `outcomes` can legitimately disagree: an agent killed before
/// it reported a result contributes to `outcomes.killed` with no cost at all, so
/// a workspace may show outcomes against zero spend. Charts should not treat
/// that as missing data.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(schemars::JsonSchema))]
pub struct UsageGroup {
    /// Workspace name.
    pub workspace: String,
    /// Cost across the window.
    pub cost_usd: f64,
    /// Turns across the window.
    pub turns: u64,
    /// Terminal outcomes across the window.
    pub outcomes: OutcomeCounts,
    /// Per-day breakdown, ascending by day. Only days with activity appear.
    pub series: Vec<UsageBucket>,
}

/// The widest `GET /api/usage?days=` window the server answers (#255).
///
/// The server builds the window with `chrono::Duration::days`, which panics
/// past about 106 million days. A century is far beyond any retained history
/// and far inside that bound. Shared here so the server's limit and the CLI's
/// `--since` limit are one number, not two that can drift.
pub const MAX_USAGE_WINDOW_DAYS: i64 = 36_500;

/// `GET /api/usage` — aggregated spend and outcomes per workspace.
///
/// The window is echoed back so a client rendering an axis does not have to
/// re-derive the defaults the server applied.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(schemars::JsonSchema))]
pub struct UsageReport {
    /// Inclusive window start (RFC-3339).
    pub since: String,
    /// Exclusive window end (RFC-3339).
    pub until: String,
    /// One entry per workspace with activity, ordered by name.
    pub groups: Vec<UsageGroup>,
}

#[cfg(test)]
mod tests {
    use super::*;

    /// #238: an old client's body has no posture; it must mean supervised, and
    /// a spawn body must be able to ask for unattended.
    /// #221: a timeout is opt-in, and an old client's body simply has none.
    #[test]
    fn spawn_body_timeout_is_optional() {
        let body: SpawnBody = serde_json::from_str(r#"{"prompt":"hi"}"#).unwrap();
        assert_eq!(body.timeout_secs, None);

        let capped: SpawnBody =
            serde_json::from_str(r#"{"prompt":"hi","timeout_secs":3600}"#).unwrap();
        assert_eq!(capped.timeout_secs, Some(3600));
    }

    #[test]
    fn spawn_body_permission_posture_defaults_to_supervised() {
        let body: SpawnBody = serde_json::from_str(r#"{"prompt":"hi"}"#).unwrap();
        assert_eq!(body.permission_posture, PermissionPosture::Supervised);

        let unattended: SpawnBody =
            serde_json::from_str(r#"{"prompt":"hi","permission_posture":"unattended"}"#).unwrap();
        assert_eq!(unattended.permission_posture, PermissionPosture::Unattended);
    }

    /// The point of the move: every one of these round-trips through serde in
    /// *both* directions, so the client and the server can share one definition.
    #[test]
    fn every_dto_round_trips_in_both_directions() {
        macro_rules! round_trip {
            ($v:expr) => {{
                let v = $v;
                let json = serde_json::to_string(&v).unwrap();
                let back = serde_json::from_str(&json).unwrap();
                assert_eq!(v, back, "round-trip changed the value: {json}");
            }};
        }

        round_trip!(Capabilities {
            admin: true,
            async_workspace_ops: false,
        });
        round_trip!(AddWorkspaceBody {
            name: "ws".into(),
            root: "/w".into(),
            config: WorkspaceConfig::default(),
        });
        round_trip!(SetConfigBody(WorkspaceConfig::default()));
        round_trip!(SpawnBody {
            prompt: "p".into(),
            interactive: true,
            ..SpawnBody::default()
        });
        round_trip!(SpawnedResponse {
            agent_id: "a".into(),
            workspace: "w".into(),
            isolated: true,
            created: false,
        });
        round_trip!(AgentInputBody { text: "hi".into() });
        round_trip!(RespawnedResponse {
            agent_id: "a2".into(),
        });
        round_trip!(WorkspaceSummary {
            name: "ws".into(),
            root: "/w".into(),
            sources: vec![Source {
                name: "s".into(),
                path: "/w/s".into(),
            }],
            health: WorkspaceHealth::Healthy,
            agent_count: 1,
            config: RepoProviderConfig::default(),
            source_specs: Vec::new(),
            display_name: None,
            providers: Vec::new(),
            default_provider: None,
            status: None,
        });
    }

    /// #190: `created` was added after the fact, so a body from a pre-#190
    /// daemon omits it. It must read back as `true` — the launch-happened
    /// assumption every client already made — rather than failing to parse or
    /// silently claiming an attach.
    #[test]
    fn spawned_response_created_defaults_to_true_when_absent() {
        let legacy = r#"{"agent_id":"a","workspace":"w","isolated":true}"#;
        let parsed: SpawnedResponse = serde_json::from_str(legacy).expect("legacy body parses");
        assert!(parsed.created);

        let explicit = r#"{"agent_id":"a","workspace":"w","isolated":true,"created":false}"#;
        let parsed: SpawnedResponse = serde_json::from_str(explicit).expect("parses");
        assert!(!parsed.created, "an explicit false must survive");
    }

    #[test]
    fn isolation_defaults_to_worktree_and_only_shared_opts_out() {
        let default = SpawnBody::default();
        assert!(default.isolation_worktree());

        let worktree = SpawnBody {
            isolation: Some("worktree".into()),
            ..SpawnBody::default()
        };
        assert!(worktree.isolation_worktree());

        let shared = SpawnBody {
            isolation: Some("shared".into()),
            ..SpawnBody::default()
        };
        assert!(!shared.isolation_worktree());

        // An unrecognised value must not silently drop isolation.
        let nonsense = SpawnBody {
            isolation: Some("Shared".into()),
            ..SpawnBody::default()
        };
        assert!(nonsense.isolation_worktree());
    }

    /// The local backend's `GET /api/workspaces` payload must not gain k8s keys.
    #[test]
    fn local_workspace_summary_omits_the_k8s_tail() {
        let s = WorkspaceSummary {
            name: "ws".into(),
            root: "/w".into(),
            sources: vec![],
            health: WorkspaceHealth::Healthy,
            agent_count: 0,
            config: RepoProviderConfig::default(),
            source_specs: Vec::new(),
            display_name: None,
            providers: Vec::new(),
            default_provider: None,
            status: None,
        };
        let json = serde_json::to_string(&s).unwrap();
        for absent in [
            "display_name",
            "providers",
            "default_provider",
            "status",
            "source_specs",
        ] {
            assert!(!json.contains(absent), "{absent} leaked into {json}");
        }
    }
}