The JSON API and its TypeScript types: brief, agents, projects, channels, messages, threads, inbox, search, the log and its stream (#11) e071e91a14ef

//! Emit TypeScript declarations for every API type, from their JSON

//! Schemas, so spectra-vscode and spectrahub-vscode can never drift from the server:

//!

//! `cargo run -p spectra-api --bin spectra-api-typescript > ts/index.d.ts`

use serde_json::Value;

fn ts_type(schema: &Value) -> String {

    if let Some(r) = schema.get("$ref").and_then(Value::as_str) {

        return r.rsplit('/').next().unwrap_or("unknown").to_string();

    }

    if let Some(e) = schema.get("enum").and_then(Value::as_array) {

        return e.iter().map(|v| serde_json::to_string(v).unwrap_or_default()).collect::<Vec<_>>().join(" | ");

    }

    if let Some(c) = schema.get("const") {

        return serde_json::to_string(c).unwrap_or_default();

    }

    if let Some(variants) = schema.get("oneOf").or_else(|| schema.get("anyOf")).and_then(Value::as_array) {

        return variants.iter().map(ts_type).collect::<Vec<_>>().join(" | ");

    }

    let nullable = schema.get("type").and_then(Value::as_array).is_some_and(|a| a.iter().any(|t| t == "null"));

    let ty = match schema.get("type") {

        Some(Value::String(t)) => t.clone(),

        Some(Value::Array(a)) => a.iter().filter_map(Value::as_str).find(|t| *t != "null").unwrap_or("unknown").to_string(),

        _ => {

            if schema.get("properties").is_some() {

                "object".into()

            } else {

                "unknown".into()

            }

        }

    };

    let base = match ty.as_str() {

        "string" => "string".to_string(),

        "integer" | "number" => "number".to_string(),

        "boolean" => "boolean".to_string(),

        "null" => "null".to_string(),

        "array" => format!("{}[]", schema.get("items").map(ts_type).unwrap_or_else(|| "unknown".into())),

        "object" => {

            let props = schema.get("properties").and_then(Value::as_object);

            let required: Vec<&str> =

                schema.get("required").and_then(Value::as_array).map(|a| a.iter().filter_map(Value::as_str).collect()).unwrap_or_default();

            match props {

                Some(p) => {

                    let fields: Vec<String> = p

                        .iter()

                        .map(|(k, v)| format!("  {k}{}: {};", if required.contains(&k.as_str()) { "" } else { "?" }, ts_type(v)))

                        .collect();

                    format!("{{\n{}\n}}", fields.join("\n"))

                }

                None => "Record<string, unknown>".into(),

            }

        }

        _ => "unknown".into(),

    };

    if nullable {

        format!("{base} | null")

    } else {

        base

    }

}

fn main() {

    println!("// Generated by `cargo run -p spectra-api --bin spectra-api-typescript`; do not edit.");

    println!("// Types of the Spectra JSON API (spec §18).\n");

    let mut printed = std::collections::BTreeSet::new();

    for (name, schema) in spectra_api::schemas() {

        let v = serde_json::to_value(&schema).unwrap();

        let defs = v.get("$defs").and_then(Value::as_object).cloned().unwrap_or_default();

        for (dname, dschema) in &defs {

            if printed.insert(dname.clone()) {

                println!("export type {dname} = {};\n", ts_type(dschema));

            }

        }

        if printed.insert(name.to_string()) {

            println!("export type {name} = {};\n", ts_type(&v));

        }

    }

}

// Generated by `cargo run -p spectra-api --bin spectra-api-typescript`; do not edit.

// Types of the Spectra JSON API (spec §18).

export type Problem = {

  detail?: string | null;

  status: number;

  title: string;

  type: string;

};

export type Version = {

  ledger_format: number;

  mcp_protocol_versions: string[];

  version: string;

};

export type Agent = {

  disabled: boolean;

  display: string;

  key: string;

  kind: string;

  name: string;

  owner: string;

  presence: string;

  project: string;

  status?: string | null;

};

export type Project = {

  depended_on_by: string[];

  depends_on: string[];

  name: string;

  path: string;

  remote?: string | null;

};

export type Channel = {

  display: string;

  id: string;

  kind: string;

  messages: number;

  name: string;

  purpose?: string | null;

};

export type Message = {

  at_ms: number;

  author: string;

  author_display: string;

  body: string;

  channel: string;

  id: string;

  kind: string;

  mentions: string[];

  redacted: boolean;

  refs: string[];

  replies: number;

  reply_to?: string | null;

};

export type Messages = {

  channel: string;

  items: Message[];

  next?: string | null;

};

export type NewMessage = {

  body: string;

  kind?: string | null;

  reply_to?: string | null;

};

export type Posted = {

  channel: string;

  duplicate: boolean;

  id: string;

};

export type InboxItem = {

  at_ms: number;

  channel: string;

  from: string;

  id: string;

  kind: string;

  summary: string;

};

export type Ack = {

  ids: string[];

  reaction?: string | null;

};

export type Hit = {

  at_ms: number;

  author: string;

  channel: string;

  id: string;

  snippet: string;

  thread?: string | null;

};

export type EventSummary = {

  actor: string;

  assurance: number;

  at_ms: number;

  hash: string;

  id: string;

  kind: string;

  method: string;

  seq: number;

  subject?: string | null;

};

export type Events = {

  items: EventSummary[];

  next?: number | null;

};

export type Brief = {

  actor: string;

  agents: Agent[];

  head: number;

  inbox: InboxItem[];

  project?: string | null;

  rules_version: string;

  unread: number;

  you: string;

};

//! The JSON API (spec §18): what spectra-vscode, scripts and SpectraHub

//! read and write. Every request is a signed request (spec §8.5); a read

//! may instead carry the owner's Radar session. Errors are RFC 7807

//! problems; lists page with `?after=`; reads carry an ETag.

use crate::http::{authenticate, AppState, PeerInfo};

use axum::body::Bytes;

use axum::extract::connect_info::ConnectInfo;

use axum::extract::{Path, Query, State};

use axum::http::{header, HeaderMap, StatusCode};

use axum::response::sse::{Event as SseEvent, KeepAlive, Sse};

use axum::response::{IntoResponse, Response};

use axum::routing::{get, post};

use axum::Router;

use futures::StreamExt;

use serde::Deserialize;

use spectra_api as api;

use spectra_core::authn::Caller;

use spectra_core::conversation::{self as conv, Author, Post, Posted, Signer};

use spectra_core::event::{Auth, Method};

use spectra_core::ids::now_ms;

use spectra_core::principals::Principal;

use std::time::Duration;

pub fn router(state: AppState) -> Router {

    Router::new()

        .route("/api/v1/health", get(health))

        .route("/api/v1/version", get(version))

        .route("/api/v1/brief", get(brief))

        .route("/api/v1/agents", get(agents))

        .route("/api/v1/projects", get(projects))

        .route("/api/v1/channels", get(channels))

        .route("/api/v1/channels/{name}/messages", get(messages).post(post_message))

        .route("/api/v1/threads/{id}", get(thread))

        .route("/api/v1/inbox", get(inbox))

        .route("/api/v1/inbox/ack", post(ack))

        .route("/api/v1/search", get(search))

        .route("/api/v1/events", get(events))

        .with_state(state)

}

/// An RFC 7807 problem.

pub fn problem(status: StatusCode, title: &str, detail: Option<String>) -> Response {

    let p = api::Problem { kind: "about:blank".into(), title: title.into(), status: status.as_u16(), detail };

    let mut r = (status, axum::Json(p)).into_response();

    r.headers_mut().insert(header::CONTENT_TYPE, "application/problem+json".parse().unwrap());

    r

}

fn bad(e: anyhow::Error) -> Response {

    problem(StatusCode::BAD_REQUEST, "the request cannot be done", Some(format!("{e:#}")))

}

/// JSON with an ETag; 304 when the client has it already.

fn json_etag<T: serde::Serialize>(headers: &HeaderMap, v: &T) -> Response {

    let body = serde_json::to_vec(v).unwrap_or_default();

    let tag = format!("\"{}\"", &blake3_hex(&body)[..32]);

    if headers.get(header::IF_NONE_MATCH).and_then(|h| h.to_str().ok()) == Some(tag.as_str()) {

        return StatusCode::NOT_MODIFIED.into_response();

    }

    ([(header::CONTENT_TYPE, "application/json".to_string()), (header::ETAG, tag)], body).into_response()

}

fn blake3_hex(b: &[u8]) -> String {

    hex::encode(*spectra_core::event::hash_body_plain(b))

}

/// Who is asking: a signed request, or for a read the owner's session.

async fn caller(

    st: &AppState,

    peer: PeerInfo,

    headers: &HeaderMap,

    method_path: &str,

    body: &[u8],

    read: bool,

) -> Result<Caller, Response> {

    if read && headers.get("spectra-key").is_none() {

        let cookie = headers.get(header::COOKIE).and_then(|c| c.to_str().ok()).unwrap_or("");

        let id = cookie.split(';').map(str::trim).find_map(|kv| kv.strip_prefix("spectra_session=")).unwrap_or("");

        if let Some(s) = st.sessions.get(id, now_ms()) {

            if !crate::http::origin_ok(headers, &st.origins) {

                return Err(problem(StatusCode::FORBIDDEN, "this origin may not read Spectra", None));

            }

            let key = oxy_core::hash::ObjectRef(s.key);

            let principal = st

                .daemon

                .principals

                .read()

                .await

                .principal(&key, now_ms())

                .map_err(|why| problem(StatusCode::UNAUTHORIZED, "not authenticated", Some(why)))?;

            return Ok(Caller {

                principal,

                auth: Auth { key: Some(s.key), method: Method::Session, assurance: 2, proof: Some(s.proof) },

                learn_uid: None,

            });

        }

    }

    authenticate(st, peer, headers, method_path, body).await.map_err(|_| {

        problem(

            StatusCode::UNAUTHORIZED,

            "not authenticated",

            Some("sign the request with your key (spectra's client does), or open Radar with `spectra open`".into()),

        )

    })

}

fn path_of(uri: &axum::http::Uri) -> String {

    uri.path_and_query().map(|p| p.as_str().to_string()).unwrap_or_else(|| uri.path().to_string())

}

macro_rules! who {

    ($st:expr, $peer:expr, $headers:expr, $uri:expr, $method:literal, $body:expr, $read:expr) => {

        match caller(&$st, $peer, &$headers, &format!("{} {}", $method, path_of(&$uri)), $body, $read).await {

            Ok(c) => c,

            Err(r) => return r,

        }

    };

}

async fn health() -> Response {

    axum::Json(serde_json::json!({ "ok": true })).into_response()

}

async fn version() -> Response {

    axum::Json(api::Version {

        version: env!("CARGO_PKG_VERSION").into(),

        ledger_format: spectra_core::LEDGER_FORMAT,

        mcp_protocol_versions: crate::PROTOCOL_VERSIONS.iter().map(|v| v.to_string()).collect(),

    })

    .into_response()

}

async fn agent_list(st: &AppState) -> Vec<api::Agent> {

    #[allow(clippy::type_complexity)]

    let rows: Vec<(String, String, String, String, String, Option<String>, Option<i64>)> = sqlx::query_as(

        "SELECT a.name, a.owner_name, a.key, a.kind, a.project, p.status_text, a.disabled_ms FROM agents a LEFT JOIN presence p ON p.agent = a.name ORDER BY a.name",

    )

    .fetch_all(st.daemon.ledger.pool())

    .await

    .unwrap_or_default();

    let presence = st.daemon.presence.lock().await;

    let now = now_ms();

    rows.into_iter()

        .map(|(name, owner, key, kind, project, status, disabled)| api::Agent {

            display: format!("{name} · {owner}'s agent"),

            presence: if disabled.is_some() { "offline".into() } else { presence.state(&name, now).into() },

            disabled: disabled.is_some(),

            name,

            owner,

            key,

            kind,

            project,

            status,

        })

        .collect()

}

async fn agents(

    State(st): State<AppState>,

    ConnectInfo(peer): ConnectInfo<PeerInfo>,

    headers: HeaderMap,

    uri: axum::http::Uri,

) -> Response {

    let _ = who!(st, peer, headers, uri, "GET", b"", true);

    json_etag(&headers, &agent_list(&st).await)

}

async fn projects(

    State(st): State<AppState>,

    ConnectInfo(peer): ConnectInfo<PeerInfo>,

    headers: HeaderMap,

    uri: axum::http::Uri,

) -> Response {

    let _ = who!(st, peer, headers, uri, "GET", b"", true);

    let pool = st.daemon.ledger.pool();

    let rows: Vec<(String, String, Option<String>)> =

        sqlx::query_as("SELECT name, path, remote FROM projects ORDER BY name").fetch_all(pool).await.unwrap_or_default();

    let mut out = Vec::new();

    for (name, path, remote) in rows {

        let depends_on = sqlx::query_scalar("SELECT depends_on FROM project_relations WHERE project = ? ORDER BY 1")

            .bind(&name)

            .fetch_all(pool)

            .await

            .unwrap_or_default();

        let depended_on_by = sqlx::query_scalar("SELECT project FROM project_relations WHERE depends_on = ? ORDER BY 1")

            .bind(&name)

            .fetch_all(pool)

            .await

            .unwrap_or_default();

        out.push(api::Project { name, path, remote, depends_on, depended_on_by });

    }

    json_etag(&headers, &out)

}

async fn channels(

    State(st): State<AppState>,

    ConnectInfo(peer): ConnectInfo<PeerInfo>,

    headers: HeaderMap,

    uri: axum::http::Uri,

) -> Response {

    let c = who!(st, peer, headers, uri, "GET", b"", true);

    let all = match conv::channels(&st.daemon.ledger).await {

        Ok(a) => a,

        Err(e) => return bad(e),

    };

    let mut out = Vec::new();

    for ch in all.into_iter().filter(|ch| conv::can_read(&c.principal, ch)) {

        let n: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM messages WHERE channel = ?")

            .bind(&ch.id)

            .fetch_one(st.daemon.ledger.pool())

            .await

            .unwrap_or(0);

        out.push(api::Channel { display: ch.display(), id: ch.id, name: ch.name, kind: ch.kind, purpose: ch.purpose, messages: n });

    }

    json_etag(&headers, &out)

}

async fn to_api(st: &AppState, m: conv::Message, ch: &str) -> api::Message {

    api::Message {

        author_display: conv::display_name(&st.daemon.ledger, &m.author).await,

        mentions: serde_json::from_str(&m.mentions).unwrap_or_default(),

        refs: serde_json::from_str(&m.refs).unwrap_or_default(),

        redacted: m.redacted.is_some(),

        id: m.id,

        channel: ch.to_string(),

        reply_to: m.reply_to,

        author: m.author,

        kind: m.kind,

        body: m.body,

        at_ms: m.at_ms,

        replies: m.replies,

    }

}

#[derive(Deserialize)]

struct PageQuery {

    after: Option<String>,

    limit: Option<u32>,

}

async fn messages(

    State(st): State<AppState>,

    ConnectInfo(peer): ConnectInfo<PeerInfo>,

    headers: HeaderMap,

    uri: axum::http::Uri,

    Path(name): Path<String>,

    Query(q): Query<PageQuery>,

) -> Response {

    let c = who!(st, peer, headers, uri, "GET", b"", true);

    let limit = q.limit.unwrap_or(50).clamp(1, 500);

    match conv::read(&st.daemon.ledger, &c.principal, Some(&name), None, q.after.as_deref(), limit).await {

        Ok((ch, msgs)) => {

            let next = (msgs.len() as u32 == limit).then(|| msgs.last().map(|m| m.id.clone())).flatten();

            let mut items = Vec::new();

            for m in msgs {

                items.push(to_api(&st, m, &ch.display()).await);

            }

            json_etag(&headers, &api::Messages { channel: ch.display(), items, next })

        }

        Err(e) => problem(StatusCode::NOT_FOUND, "no such channel, or not yours to read", Some(format!("{e:#}"))),

    }

}

async fn thread(

    State(st): State<AppState>,

    ConnectInfo(peer): ConnectInfo<PeerInfo>,

    headers: HeaderMap,

    uri: axum::http::Uri,

    Path(id): Path<String>,

    Query(q): Query<PageQuery>,

) -> Response {

    let c = who!(st, peer, headers, uri, "GET", b"", true);

    let limit = q.limit.unwrap_or(200).clamp(1, 500);

    match conv::read(&st.daemon.ledger, &c.principal, None, Some(&id), q.after.as_deref(), limit).await {

        Ok((ch, msgs)) => {

            let next = (msgs.len() as u32 == limit).then(|| msgs.last().map(|m| m.id.clone())).flatten();

            let mut items = Vec::new();

            for m in msgs {

                items.push(to_api(&st, m, &ch.display()).await);

            }

            json_etag(&headers, &api::Messages { channel: ch.display(), items, next })

        }

        Err(e) => problem(StatusCode::NOT_FOUND, "no such thread, or not yours to read", Some(format!("{e:#}"))),

    }

}

async fn post_message(

    State(st): State<AppState>,

    ConnectInfo(peer): ConnectInfo<PeerInfo>,

    headers: HeaderMap,

    uri: axum::http::Uri,

    Path(name): Path<String>,

    body: Bytes,

) -> Response {

    let c = who!(st, peer, headers, uri, "POST", &body, false);

    let n: api::NewMessage = match serde_json::from_slice(&body) {

        Ok(n) => n,

        Err(e) => return problem(StatusCode::BAD_REQUEST, "not a message", Some(e.to_string())),

    };

    let author = Author { principal: c.principal.clone(), signer: Signer::Request(c.auth.clone()) };

    let post = Post {

        channel: if n.reply_to.is_some() { None } else { Some(name) },

        body: n.body,

        reply_to: n.reply_to,

        kind: n.kind,

        ..Default::default()

    };

    match conv::post(&st.daemon.ledger, &author, post, now_ms()).await {

        Ok(Posted::Message { id, channel }) => {

            (StatusCode::CREATED, axum::Json(api::Posted { id, channel, duplicate: false })).into_response()

        }

        Ok(Posted::Duplicate { id }) => axum::Json(api::Posted { id, channel: String::new(), duplicate: true }).into_response(),

        Err(e) => bad(e),

    }

}

async fn inbox_items(st: &AppState, actor: &str) -> Vec<api::InboxItem> {

    conv::inbox(&st.daemon.ledger, actor, None)

        .await

        .unwrap_or_default()

        .into_iter()

        .map(|i| api::InboxItem { id: i.id, kind: i.kind, at_ms: i.at_ms, from: i.from, channel: i.channel, summary: i.summary })

        .collect()

}

async fn inbox(State(st): State<AppState>, ConnectInfo(peer): ConnectInfo<PeerInfo>, headers: HeaderMap, uri: axum::http::Uri) -> Response {

    let c = who!(st, peer, headers, uri, "GET", b"", true);

    json_etag(&headers, &inbox_items(&st, &c.principal.actor()).await)

}

async fn ack(

    State(st): State<AppState>,

    ConnectInfo(peer): ConnectInfo<PeerInfo>,

    headers: HeaderMap,

    uri: axum::http::Uri,

    body: Bytes,

) -> Response {

    let c = who!(st, peer, headers, uri, "POST", &body, false);

    let a: api::Ack = match serde_json::from_slice(&body) {

        Ok(a) => a,

        Err(e) => return problem(StatusCode::BAD_REQUEST, "not an ack", Some(e.to_string())),

    };

    let author = Author { principal: c.principal, signer: Signer::Request(c.auth) };

    match conv::ack(&st.daemon.ledger, &author, &a.ids, a.reaction.as_deref()).await {

        Ok(n) => axum::Json(serde_json::json!({ "read": n })).into_response(),

        Err(e) => bad(e),

    }

}

async fn brief(State(st): State<AppState>, ConnectInfo(peer): ConnectInfo<PeerInfo>, headers: HeaderMap, uri: axum::http::Uri) -> Response {

    let c = who!(st, peer, headers, uri, "GET", b"", true);

    let project = match &c.principal {

        Principal::Agent { project, .. } => Some(project.clone()),

        _ => None,

    };

    let rules = spectra_core::rules::compile(&st.daemon.data).map(|r| r.version).unwrap_or_default();

    let inbox = inbox_items(&st, &c.principal.actor()).await;

    let b = api::Brief {

        you: c.principal.display(),

        actor: c.principal.actor(),

        project,

        rules_version: rules,

        unread: inbox.len() as i64,

        inbox,

        agents: agent_list(&st).await,

        head: st.daemon.ledger.head().await.0,

    };

    json_etag(&headers, &b)

}

#[derive(Deserialize)]

struct SearchQuery {

    q: String,

    channel: Option<String>,

    author: Option<String>,

    since: Option<String>,

    limit: Option<u32>,

}

async fn search(

    State(st): State<AppState>,

    ConnectInfo(peer): ConnectInfo<PeerInfo>,

    headers: HeaderMap,

    uri: axum::http::Uri,

    Query(q): Query<SearchQuery>,

) -> Response {

    let c = who!(st, peer, headers, uri, "GET", b"", true);

    let since = q.since.as_deref().and_then(|s| crate::tools::parse_since(s, now_ms()));

    match conv::search(&st.daemon.ledger, &c.principal, &q.q, q.channel.as_deref(), q.author.as_deref(), since, q.limit.unwrap_or(20)).await

    {

        Ok(hits) => {

            let out: Vec<api::Hit> = hits

                .into_iter()

                .map(|h| api::Hit { id: h.id, channel: h.channel, author: h.author, at_ms: h.at_ms, snippet: h.snippet, thread: h.thread })

                .collect();

            json_etag(&headers, &out)

        }

        Err(e) => bad(e),

    }

}

#[derive(Deserialize)]

struct EventsQuery {

    after: Option<u64>,

    kind: Option<String>,

    limit: Option<u32>,

    follow: Option<u8>,

    /// With `follow`, end the stream after this many events.

    max: Option<usize>,

}

fn summary(e: &spectra_core::event::Event) -> api::EventSummary {

    api::EventSummary {

        seq: e.seq,

        id: e.id.clone(),

        at_ms: e.at_ms,

        kind: e.kind.clone(),

        actor: e.actor.clone(),

        subject: e.subject.clone(),

        method: e.auth.method.name().into(),

        assurance: e.auth.assurance,

        hash: hex::encode(e.hash),

    }

}

/// The log as summaries; `follow=1` streams new ones as SSE instead.

async fn events(

    State(st): State<AppState>,

    ConnectInfo(peer): ConnectInfo<PeerInfo>,

    headers: HeaderMap,

    uri: axum::http::Uri,

    Query(q): Query<EventsQuery>,

) -> Response {

    let c = who!(st, peer, headers, uri, "GET", b"", true);

    // The log is the owner's to read; an agent reads what concerns it

    // through the conversation and its inbox.

    if !matches!(c.principal, Principal::Owner { .. }) {

        return problem(StatusCode::FORBIDDEN, "the event log is the owner's", None);

    }

    if q.follow == Some(1) {

        let kind = q.kind.clone();

        let rx = st.daemon.ledger.subscribe();

        let stream = tokio_stream::wrappers::BroadcastStream::new(rx)

            .filter_map(move |e| {

                let kind = kind.clone();

                async move {

                    let e = e.ok()?;

                    if kind.as_ref().is_some_and(|k| *k != e.kind) {

                        return None;

                    }

                    Some(Ok::<_, std::convert::Infallible>(

                        SseEvent::default().data(serde_json::to_string(&summary(&e)).unwrap_or_default()),

                    ))

                }

            })

            .take(q.max.unwrap_or(usize::MAX));

        return Sse::new(stream).keep_alive(KeepAlive::new().interval(Duration::from_secs(15))).into_response();

    }

    let limit = q.limit.unwrap_or(100).clamp(1, 1000);

    let from = q.after.map(|a| a + 1).unwrap_or(1);

    let evs = match &q.kind {

        Some(k) => st.daemon.ledger.events_of_kinds(from, &[k.as_str()], limit).await,

        None => st.daemon.ledger.events(from, limit).await,

    };

    match evs {

        Ok(evs) => {

            let next = (evs.len() as u32 == limit).then(|| evs.last().map(|e| e.seq)).flatten();

            json_etag(&headers, &api::Events { items: evs.iter().map(summary).collect(), next })

        }

        Err(e) => bad(e),

    }

}

//! The owner's browser sign-in, shared by Radar and the API (spec §8.3): the owner's CLI signs a request for a

//! The JSON API (spec §18) against the real daemon: every endpoint, signed

//! by an agent and by the owner; problems for refusals; paging; ETags; the

//! event log as the owner's; and the live stream.

mod common;

use common::{add_agent, setup, Serving};

use serde_json::{json, Value};

use spectra_core::keys::KeyPair;

use spectra_mcp::client::Client;

async fn get(c: &Client, path: &str) -> Value {

    let r = c.send("GET", path, &[], vec![]).await.unwrap();

    assert_eq!(r.status, 200, "{path}: {}", String::from_utf8_lossy(&r.body));

    r.json().unwrap()

}

#[tokio::test]

async fn every_endpoint_for_an_agent_and_the_owner() {

    let dir = setup();

    let d = dir.path();

    let claude = add_agent(d, "claude-oxygen", &[]);

    let srv = Serving::start(d);

    let a = Client::new(&srv.socket, Some(claude));

    let owner = Client::new(&srv.socket, Some(KeyPair::load_home(&d.join("owner")).unwrap()));

    let anon = Client::new(&srv.socket, None);

    assert_eq!(get(&anon, "/api/v1/health").await["ok"], true);

    assert_eq!(get(&anon, "/api/v1/version").await["ledger_format"], 1);

    let r = anon.send("GET", "/api/v1/agents", &[], vec![]).await.unwrap();

    assert_eq!(r.status, 401);

    assert_eq!(r.header("content-type"), Some("application/problem+json"));

    assert_eq!(r.json().unwrap()["status"], 401);

    let b = get(&a, "/api/v1/brief").await;

    assert_eq!(b["you"], "claude-oxygen · Andy McCall's agent");

    assert_eq!(b["project"], "oxygen");

    assert_eq!(get(&a, "/api/v1/agents").await[0]["display"], "claude-oxygen · Andy McCall's agent");

    assert_eq!(get(&a, "/api/v1/projects").await[0]["name"], "oxygen");

    let chans = get(&a, "/api/v1/channels").await;

    assert!(chans.as_array().unwrap().iter().any(|c| c["display"] == "#general"));

    // Post, page, and read a thread.

    let mut first = String::new();

    for i in 0..5 {

        let r = a

            .send(

                "POST",

                "/api/v1/channels/general/messages",

                &[],

                serde_json::to_vec(&json!({ "body": format!("note {i} for @andy") })).unwrap(),

            )

            .await

            .unwrap();

        assert_eq!(r.status, 201, "{}", String::from_utf8_lossy(&r.body));

        if i == 0 {

            first = r.json().unwrap()["id"].as_str().unwrap().to_string();

        }

    }

    let p1 = get(&a, "/api/v1/channels/general/messages?limit=2").await;

    assert_eq!(p1["items"].as_array().unwrap().len(), 2);

    let r = a

        .send(

            "POST",

            "/api/v1/channels/general/messages",

            &[],

            serde_json::to_vec(&json!({ "body": "a reply", "reply_to": first })).unwrap(),

        )

        .await

        .unwrap();

    assert_eq!(r.status, 201);

    let t = get(&a, &format!("/api/v1/threads/{first}")).await;

    assert_eq!(t["items"].as_array().unwrap().len(), 2);

    let r = a.send("POST", "/api/v1/channels/system/messages", &[], serde_json::to_vec(&json!({ "body": "x" })).unwrap()).await.unwrap();

    assert_eq!((r.status, r.json().unwrap()["status"].as_u64()), (400, Some(400)), "#system refuses, as a problem");

    // The owner's inbox, acked; search.

    let inbox = get(&owner, "/api/v1/inbox").await;

    assert_eq!(inbox.as_array().unwrap().len(), 5);

    let ids: Vec<Value> = inbox.as_array().unwrap().iter().map(|i| i["id"].clone()).collect();

    let r = owner.send("POST", "/api/v1/inbox/ack", &[], serde_json::to_vec(&json!({ "ids": ids })).unwrap()).await.unwrap();

    assert_eq!(r.json().unwrap()["read"], 5);

    assert_eq!(get(&owner, "/api/v1/inbox").await.as_array().unwrap().len(), 0);

    assert_eq!(get(&a, "/api/v1/search?q=note&limit=3").await.as_array().unwrap().len(), 3);

    // ETags: the same answer twice is a 304.

    let r = a.send("GET", "/api/v1/projects", &[], vec![]).await.unwrap();

    let tag = r.header("etag").unwrap().to_string();

    assert_eq!(a.send("GET", "/api/v1/projects", &[("if-none-match", tag)], vec![]).await.unwrap().status, 304);

    // The log is the owner's; it pages; the stream follows.

    assert_eq!(a.send("GET", "/api/v1/events", &[], vec![]).await.unwrap().status, 403);

    let ev = get(&owner, "/api/v1/events?limit=5").await;

    assert_eq!(ev["items"][0]["kind"], "identity.owner");

    assert_eq!(ev["next"], 5);

    let posted = get(&owner, "/api/v1/events?kind=message.posted&limit=50").await;

    assert_eq!(posted["items"].as_array().unwrap().len(), 6);

    assert!(posted["items"].as_array().unwrap().iter().all(|e| e["method"] == "signature" && e["assurance"] == 2));

    let stream = tokio::spawn({

        let owner = Client::new(&srv.socket, Some(KeyPair::load_home(&d.join("owner")).unwrap()));

        async move { owner.send("GET", "/api/v1/events?follow=1&max=1&kind=message.posted", &[], vec![]).await.unwrap() }

    });

    tokio::time::sleep(std::time::Duration::from_millis(300)).await;

    a.send("POST", "/api/v1/channels/general/messages", &[], serde_json::to_vec(&json!({ "body": "streamed" })).unwrap()).await.unwrap();

    let s = tokio::time::timeout(std::time::Duration::from_secs(10), stream).await.expect("the stream ends after max events").unwrap();

    assert!(String::from_utf8_lossy(&s.body).contains("\"kind\":\"message.posted\""), "{}", String::from_utf8_lossy(&s.body));

    srv.stop();

}

- **Added: the JSON API and its TypeScript types (#11).** `/api/v1` has health, version, brief, agents, projects, channels, a channel's messages (read and post), threads, the inbox and ack, search, and the event log, which follows live as SSE (`?follow=1`). Requests are signed, or a read carries the owner's Radar session; refusals are RFC 7807 problems; lists page with `?after=`; reads carry an ETag. `crates/spectra-api` holds the types, and `make ts` writes `ts/index.d.ts` for the editor extensions.

name = "dyn-clone"

version = "1.0.20"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"

[[package]]

name = "ref-cast"

version = "1.0.27"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "7e440fb4e4b4147295338efb76001ab9e4efc0e5839df2c47fc5ac2381d365c3"

dependencies = [

 "ref-cast-impl",

]

[[package]]

name = "ref-cast-impl"

version = "1.0.27"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "92ecd8964f8453721699a1ed72037b0db49ce2f5a5138486ee89bed6f67cdf3a"

dependencies = [

 "proc-macro2",

 "quote",

 "syn 3.0.6",

]

[[package]]

]

[[package]]

name = "schemars"

version = "1.2.2"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "687274d293b6cdc6e73e0fee520bf2049650090d7164f87672d212a3c530cf4a"

dependencies = [

 "dyn-clone",

 "ref-cast",

 "schemars_derive",

 "serde",

 "serde_json",

name = "schemars_derive"

version = "1.2.2"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "d98c67716b46af2f0b8cf752abc930f6f9aecfbf671ecfb531db8a31dbe4e2ba"

dependencies = [

 "proc-macro2",

 "quote",

 "serde_derive_internals",

 "syn 3.0.6",

]

[[package]]

dependencies = [

 "proc-macro2",

 "quote",

 "syn 3.0.6",

]

[[package]]

name = "serde_derive_internals"

version = "0.30.0"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "f852137cce035d6a4df67ccce505ff6b3e9fd3a10e3e52b24dc71e650bb1a9bd"

 "schemars",

 "spectra-api",

use spectra_mcp::session::{self, Session};

}

impl RadarState {

    fn sessions(&self) -> &session::Sessions {

        &self.app.sessions

    }

    let state = RadarState { app };

        .and_then(|id| st.sessions().get(&id, now))

    let code = st.sessions().link(key, proof, now_ms());

    let Some(id) = q.code.and_then(|c| st.sessions().open(&c, now_ms())) else {

                st.sessions().close(&id);

schemars = { workspace = true, features = ["derive"] }

[[bin]]

name = "spectra-api-typescript"

path = "src/bin/typescript.rs"

//! `hub-api` is for OxygenHub. `make ts` writes `ts/index.d.ts` from them

//! for spectra-vscode and spectrahub-vscode, so the extensions can never

//! drift from the server.

use schemars::JsonSchema;

use serde::{Deserialize, Serialize};

/// An error, as RFC 7807 has it.

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct Problem {

    #[serde(rename = "type")]

    pub kind: String,

    pub title: String,

    pub status: u16,

    #[serde(skip_serializing_if = "Option::is_none")]

    pub detail: Option<String>,

}

/// `GET /api/v1/version`.

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct Version {

    pub version: String,

    pub ledger_format: u32,

    pub mcp_protocol_versions: Vec<String>,

}

/// An agent and its owner (spec §8.1).

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct Agent {

    pub name: String,

    /// `claude-oxygen · Andy McCall's agent`.

    pub display: String,

    pub owner: String,

    pub key: String,

    pub kind: String,

    pub project: String,

    /// online, busy, idle, blocked, paused or offline.

    pub presence: String,

    pub status: Option<String>,

    pub disabled: bool,

}

/// A project (spec §23.1).

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct Project {

    pub name: String,

    pub path: String,

    pub remote: Option<String>,

    pub depends_on: Vec<String>,

    pub depended_on_by: Vec<String>,

}

/// A channel (spec §10.1).

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct Channel {

    pub id: String,

    pub name: String,

    /// `#general`, `#oxygen`, or `@a+b` for a direct channel.

    pub display: String,

    pub kind: String,

    pub purpose: Option<String>,

    pub messages: i64,

}

/// A message (spec §10.3); a redacted one's body says so.

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct Message {

    pub id: String,

    pub channel: String,

    pub reply_to: Option<String>,

    pub author: String,

    pub author_display: String,

    pub kind: String,

    pub body: String,

    pub mentions: Vec<String>,

    pub refs: Vec<String>,

    pub at_ms: i64,

    pub replies: i64,

    pub redacted: bool,

}

/// A page of messages, oldest first; `next` is the cursor for the next page.

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct Messages {

    pub channel: String,

    pub items: Vec<Message>,

    pub next: Option<String>,

}

/// `POST /api/v1/channels/{name}/messages`.

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct NewMessage {

    pub body: String,

    #[serde(default)]

    pub reply_to: Option<String>,

    #[serde(default)]

    pub kind: Option<String>,

}

/// What a post did.

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct Posted {

    pub id: String,

    pub channel: String,

    /// True when it was dropped as a repeat of `id` within a minute.

    pub duplicate: bool,

}

/// An unread mention or direct message (spec §14.5).

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct InboxItem {

    pub id: String,

    pub kind: String,

    pub at_ms: i64,

    pub from: String,

    pub channel: String,

    pub summary: String,

}

/// `POST /api/v1/inbox/ack`.

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct Ack {

    pub ids: Vec<String>,

    #[serde(default)]

    pub reaction: Option<String>,

}

/// A search hit (spec §13.1).

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct Hit {

    pub id: String,

    pub channel: String,

    pub author: String,

    pub at_ms: i64,

    pub snippet: String,

    pub thread: Option<String>,

}

/// An event as the log and the stream show it: never its payload's data on

/// the stream, which says only what changed (spec §17.3).

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct EventSummary {

    pub seq: u64,

    pub id: String,

    pub at_ms: u64,

    pub kind: String,

    pub actor: String,

    pub subject: Option<String>,

    /// system, token, signature, passkey or session.

    pub method: String,

    pub assurance: u8,

    pub hash: String,

}

/// A page of the log, oldest first.

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct Events {

    pub items: Vec<EventSummary>,

    pub next: Option<u64>,

}

/// `GET /api/v1/brief`: who the caller is and what is waiting.

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct Brief {

    pub you: String,

    pub actor: String,

    pub project: Option<String>,

    pub rules_version: String,

    pub unread: i64,

    pub inbox: Vec<InboxItem>,

    pub agents: Vec<Agent>,

    pub head: u64,

}

/// Every type, with its schema, for `make ts`.

pub fn schemas() -> Vec<(&'static str, schemars::Schema)> {

    vec![

        ("Problem", schemars::schema_for!(Problem)),

        ("Version", schemars::schema_for!(Version)),

        ("Agent", schemars::schema_for!(Agent)),

        ("Project", schemars::schema_for!(Project)),

        ("Channel", schemars::schema_for!(Channel)),

        ("Message", schemars::schema_for!(Message)),

        ("Messages", schemars::schema_for!(Messages)),

        ("NewMessage", schemars::schema_for!(NewMessage)),

        ("Posted", schemars::schema_for!(Posted)),

        ("InboxItem", schemars::schema_for!(InboxItem)),

        ("Ack", schemars::schema_for!(Ack)),

        ("Hit", schemars::schema_for!(Hit)),

        ("EventSummary", schemars::schema_for!(EventSummary)),

        ("Events", schemars::schema_for!(Events)),

        ("Brief", schemars::schema_for!(Brief)),

    ]

}

spectra-api.workspace = true

    /// The owner's browser sessions (Radar's sign-in link).

    pub sessions: Arc<crate::session::Sessions>,

pub mod api;

pub mod session;

- [x] #11 JSON API and spectra-api types — done 2026-11-02: every 0.1 endpoint, problems, paging, ETags, the live log; types and ts/index.d.ts. How spectra-vscode will sign is spec open question 11.

11. **How spectra-vscode signs.** The API takes signed requests (§8.5), and an extension in TypeScript has no ML-DSA-65 of its own. Recommended: the extension runs `spectra` as a signing proxy over the socket (a `spectra api METHOD PATH` command that signs with the owner's key and prints the JSON), so no key ever leaves Rust; the alternative, a WebAssembly build of `oxy-core`'s signing, is heavier. Decide before spectra-vscode 0.1.

    let state = AppState { daemon: daemon.clone(), origins: Arc::new(origins), sessions: Default::default() };

    let app = spectra_mcp::http::router(state.clone()).merge(spectra_mcp::api::router(state.clone())).merge(radar::router(state));