yoi/crates/worker/src/skill.rs

use serde::{Deserialize, Serialize};

use crate::worker::WorkspaceClient;

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum SkillDiagnosticSeverity {
    Error,
    Warning,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SkillDiagnostic {
    pub severity: SkillDiagnosticSeverity,
    pub code: String,
    pub message: String,
    /// Path-free authority/provenance label such as `builtin:foo` or `workspace:foo`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub source: Option<String>,
}

impl SkillDiagnostic {
    pub fn error(
        code: impl Into<String>,
        message: impl Into<String>,
        source: Option<String>,
    ) -> Self {
        Self {
            severity: SkillDiagnosticSeverity::Error,
            code: code.into(),
            message: message.into(),
            source,
        }
    }

    pub fn warning(
        code: impl Into<String>,
        message: impl Into<String>,
        source: Option<String>,
    ) -> Self {
        Self {
            severity: SkillDiagnosticSeverity::Warning,
            code: code.into(),
            message: message.into(),
            source,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum SkillSourceKind {
    Builtin,
    Workspace,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SkillProvenance {
    pub kind: SkillSourceKind,
    /// Stable path-free id: `builtin:<name>` or `workspace:<name>`.
    pub id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SkillResourceRef {
    pub kind: String,
    /// Skill-relative resource name/path. Never an absolute filesystem path.
    pub name: String,
    pub supported: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub diagnostic: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SkillCatalogEntry {
    pub name: String,
    pub description: String,
    pub provenance: SkillProvenance,
    #[serde(default)]
    pub overrides: Vec<SkillProvenance>,
    #[serde(default)]
    pub diagnostics: Vec<SkillDiagnostic>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SkillCatalogResponse {
    /// Authority label for diagnostics; callers must not interpret it as a path.
    pub authority: String,
    #[serde(default)]
    pub entries: Vec<SkillCatalogEntry>,
    #[serde(default)]
    pub diagnostics: Vec<SkillDiagnostic>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SkillDetailResponse {
    pub name: String,
    pub description: String,
    pub provenance: SkillProvenance,
    #[serde(default)]
    pub overrides: Vec<SkillProvenance>,
    #[serde(default)]
    pub diagnostics: Vec<SkillDiagnostic>,
    /// Full SKILL.md contents. This is intentionally omitted from catalog responses.
    pub body: String,
    #[serde(default)]
    pub allowed_tools: Vec<String>,
    /// Explicitly documents that allowed-tools is parsed only as an experimental hint.
    pub allowed_tools_status: String,
    #[serde(default)]
    pub resources: Vec<SkillResourceRef>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SkillActivationResponse {
    pub name: String,
    pub provenance: SkillProvenance,
    #[serde(default)]
    pub diagnostics: Vec<SkillDiagnostic>,
    /// Full SKILL.md contents to append to Worker history on explicit activation.
    pub body: String,
}

#[derive(Debug, thiserror::Error)]
pub enum SkillClientError {
    #[error("workspace client is unavailable: {0}")]
    Unavailable(String),
    #[error("workspace client kind `{0}` does not expose direct Skill HTTP operations")]
    UnsupportedClient(String),
    #[error("Skill request failed: {0}")]
    Request(#[from] reqwest::Error),
    #[error("Skill API response JSON is invalid: {0}")]
    Json(#[from] serde_json::Error),
    #[error("Skill API returned HTTP {status}: {body}")]
    Http {
        status: reqwest::StatusCode,
        body: String,
    },
    #[error("invalid Skill API base URL: {0}")]
    InvalidBaseUrl(String),
}

impl WorkspaceClient {
    pub fn list_skills(&self) -> Result<SkillCatalogResponse, SkillClientError> {
        self.get_skill_json("skills")
    }

    pub fn read_skill(&self, name: &str) -> Result<SkillDetailResponse, SkillClientError> {
        self.get_skill_json(&format!("skills/{name}"))
    }

    pub fn activate_skill(&self, name: &str) -> Result<SkillActivationResponse, SkillClientError> {
        self.get_skill_json(&format!("skills/{name}/activate"))
    }

    fn get_skill_json<T: for<'de> Deserialize<'de>>(
        &self,
        path: &str,
    ) -> Result<T, SkillClientError> {
        let Self::Http {
            workspace_id,
            base_url,
        } = self
        else {
            return match self {
                Self::Available { kind } => Err(SkillClientError::UnsupportedClient(kind.clone())),
                Self::Unavailable { reason } => Err(SkillClientError::Unavailable(reason.clone())),
                Self::Http { .. } => unreachable!(),
            };
        };
        if base_url.trim().is_empty() {
            return Err(SkillClientError::InvalidBaseUrl(base_url.clone()));
        }
        let base = base_url.trim_end_matches('/');
        let url = format!("{base}/api/w/{workspace_id}/{path}");
        let response = reqwest::blocking::Client::new().get(url).send()?;
        let status = response.status();
        let body = response.text()?;
        if !status.is_success() {
            return Err(SkillClientError::Http { status, body });
        }
        Ok(serde_json::from_str(&body)?)
    }
}

#[cfg(test)]
mod tests {
    use std::io::{BufRead, BufReader, Write};
    use std::net::TcpListener;
    use std::thread;

    use super::*;

    #[test]
    fn http_workspace_client_fetches_skill_catalog_from_backend_endpoint() {
        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
        let addr = listener.local_addr().unwrap();
        let handle = thread::spawn(move || {
            let (mut stream, _) = listener.accept().unwrap();
            let mut reader = BufReader::new(stream.try_clone().unwrap());
            let mut request_line = String::new();
            reader.read_line(&mut request_line).unwrap();
            assert!(request_line.starts_with("GET /api/w/ws-1/skills HTTP/1.1"));
            loop {
                let mut line = String::new();
                reader.read_line(&mut line).unwrap();
                if line == "\r\n" || line.is_empty() {
                    break;
                }
            }
            let body = serde_json::json!({
                "authority": "workspace-backend-skills-v0",
                "entries": [{
                    "name": "triage-errors",
                    "description": "Use when triaging errors.",
                    "provenance": { "kind": "workspace", "id": "workspace:triage-errors" },
                    "overrides": [],
                    "diagnostics": []
                }],
                "diagnostics": []
            })
            .to_string();
            write!(
                stream,
                "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\n\r\n{}",
                body.len(),
                body
            )
            .unwrap();
        });

        let client = WorkspaceClient::http("ws-1", format!("http://{addr}"));
        let catalog = client.list_skills().unwrap();
        assert_eq!(catalog.entries[0].name, "triage-errors");
        assert_eq!(catalog.entries[0].provenance.id, "workspace:triage-errors");
        handle.join().unwrap();
    }
}