cua-spaces: agents and MCP

pub struct CapabilitiesReport {
  pub protocol: &'static str,
  pub statuses: Vec<&'static str>,
  pub event_kinds: &'static [&'static str],
  pub harnesses: Vec<HarnessInfo>,
  pub forwardable_env: Vec<&'static str>,
  pub runner: &'static str,
}

pub struct AgentKeys { /* private fields */ }
impl AgentKeys {
  fn new(store: Store) -> Self;
  fn unavailable(reason: &str) -> Self;
  fn available(&self) -> bool;
  fn list(&self) -> Result<Vec<KeyInfo>>;
  fn report(&self) -> Result<KeysReport>;
  fn set(&self, provider: &str, env: Option<&str>, value: &str) -> Result<KeyInfo>;
  fn remove(&self, env: &str) -> Result<bool>;
  fn names(&self) -> Vec<String>;
  fn values(&self, names: &[&str]) -> BTreeMap<String, String>;
}

pub struct KeyInfo {
  pub provider: String,
  pub env: String,
  pub last4: String,
  pub added_ms: u64,
}

pub struct KeysReport {
  pub keys: Vec<KeyInfo>,
  pub providers: Vec<Provider>,
  pub available: bool,
  pub unavailable: Option<String>,
}

pub struct Provider {
  pub id: &'static str,
  pub label: &'static str,
  pub env: &'static str,
}

pub struct McpServer { /* private fields */ }
impl McpServer {
  fn new(spaces: Spaces) -> Self;
  fn remote(backend: Arc<dyn ToolBackend>) -> Self;
  fn with_session_broker(self, broker: Arc<dyn SessionBroker>) -> Self;
  fn with_extension(self, extension: Arc<dyn ToolExtension>) -> Self;
  fn with_filter(self, filter: ToolFilter) -> Self;
  fn with_name(self, name: &'static str) -> Self;
  fn with_instructions(self, instructions: &'static str) -> Self;
  fn spaces(&self) -> Option<&Spaces>;
  fn tools_list(&self) -> Value;
  async fn call(&self, name: &str, arguments: Value) -> ToolOutcome;
  async fn handle(&self, message: Value) -> Option<Value>;
}

pub trait ToolBackend: Send + Sync {
  async fn call(&self, tool: &str, arguments: Value) -> ToolOutcome;
}

pub trait ToolExtension: Send + Sync {
  fn tools(&self) -> Vec<Value>;
  async fn call(&self, tool: &str, arguments: Value) -> Option<ToolOutcome>;
}

pub struct ToolOutcome {
  pub content: Vec<Value>,
  pub structured: Option<Value>,
  pub is_error: bool,
  pub meta: Option<Value>,
}
impl ToolOutcome {
  fn text(text: impl Into<String>) -> Self;
  fn json<T: Serialize>(value: &T) -> Self;
  fn error(e: &Error) -> Self;
  fn error_message(kind: &str, message: impl Into<String>) -> Self;
  fn first_text(&self) -> Option<&str>;
  fn to_result(&self) -> Value;
}

// mod agents
/// What every harness is, can and cannot ...
pub fn capabilities() -> CapabilitiesReport
/// Resolves `names` from this process's ...
pub fn env_from_host(names: &[String]) -> Result<(BTreeMap<String, String>, Vec<String>)>
/// `env_from_host` over the given saved ...
pub fn env_from_host_with(saved: &AgentKeys, names: &[String]) -> Result<(BTreeMap<String, String>, Vec<String>)>
/// The provider key variables a host may ...
pub fn forwardable_env() -> Vec<&'static str>
/// The first of `h`'s keys this server can ...
pub fn host_key(h: &Harness) -> Option<&'static str>
/// `host_key` given the names of the saved ...
pub fn host_key_with(h: &Harness, saved: &[String]) -> Option<&'static str>
/// The provider keys a run of `harness` ...
pub fn run_env(harness: &str, env: &BTreeMap<String, String>, env_from_host: &[String], custom_endpoint: bool) -> Result<(BTreeMap<String, String>, Vec<String>)>
/// `run_env` over the given saved keys.
pub fn run_env_with(saved: &AgentKeys, harness: &str, env: &BTreeMap<String, String>, env_from_host: &[String], custom_endpoint: bool) -> Result<(BTreeMap<String, String>, Vec<String>)>
/// The run options of an `agent_start` ...
pub fn start_options(a: &AgentStart) -> Result<(RunOptions, Vec<String>)>
/// `start_options` over the given saved ...
pub fn start_options_with(saved: &AgentKeys, a: &AgentStart) -> Result<(RunOptions, Vec<String>)>
 
// mod agents::keys
/// Runs one of `APP_METHODS` against ...
pub fn app_call(keys: &AgentKeys, name: &str, args: Value) -> Option<Result<KeysReport>>
/// `app_call` on this process's keys as a ...
pub fn app_tool(name: &str, args: Value) -> Option<ToolOutcome>
/// This process's agent keys: the default ...
pub fn global() -> &'static AgentKeys
/// Whether `name` is one of `APP_METHODS`.
pub fn is_app_method(name: &str) -> bool
/// The provider id for a variable: its ...
pub fn provider_of(env: &str) -> &'static str
/// Checks a name for an Other key: an env ...
pub fn validate_name(name: &str) -> Result<()>
 
// mod agents::telemetry
/// Before stopping `run_id`: records an ...
pub async fn before_stop(agents: &Agents, run_id: &str)
/// The error variant of `e` (never its ...
pub fn error_variant(e: &Error) -> &'static str
/// A run's status was read: records its ...
pub fn observe(info: &RunInfo)
/// Starting a run failed.
pub fn start_failed(harness: &str, space: &str, entry: &str, e: &Error)
/// A run was started from `entry` in the ...
pub fn started(agents: &Agents, space: &str, entry: &str, s: &Started)
/// A run was stopped before its first turn ...
pub fn stopped(run_id: &str)
/// Follows `run_id` in the background ...
pub fn watch(agents: Agents, run_id: String)
 
// mod mcp
/// Runs a Space-scoped contract tool ...
pub async fn call_on(space: &Space, tool: &str, arguments: Value) -> ToolOutcome
 
// mod mcp::http
/// The `/mcp` router.
pub fn router(server: McpServer, bearer: Option<String>) -> Router
/// Serves `router` on `listener` until the ...
pub async fn serve(server: McpServer, listener: TcpListener, bearer: Option<String>) -> Result<()>
 
// mod mcp::stdio
/// Serves until `input` reaches EOF.
pub async fn serve<R, W>(server: McpServer, input: R, output: W) -> Result<()> where R: AsyncRead + Unpin, W: AsyncWrite + Unpin + Send + 'static
/// Serves on the process's stdin/stdout.
pub async fn serve_process_stdio(server: McpServer) -> Result<()>

// mod agents
/// The extension operation `agent_start` ...
pub const WATCH_OP: &str = "agent_start.watch";
 
// mod agents::keys
/// The app's settings methods ...
pub const APP_METHODS: &[&str] = _;
/// Anthropic and OpenAI; anything else is ...
pub const PROVIDERS: &[Provider] = _;
/// The store's secret name.
pub const SECRET_NAME: &str = "agent-keys";
 
// mod agents::telemetry
/// How long a watcher follows a run before ...
pub const WATCH_FOR: Duration = _;
 
// mod mcp
/// Server instructions sent in ...
pub const INSTRUCTIONS: &str = /* ... */;
/// Server name in `initialize`.
pub const SERVER_NAME: &str = "cua-spaces";
/// Server version in `initialize`.
pub const SERVER_VERSION: &str = "0.1.0";
/// Tools `call_on` accepts.
pub const SPACE_SCOPED_TOOLS: &[&str] = _;
/// Protocol revisions this server accepts ...
pub const SUPPORTED_PROTOCOL_VERSIONS: [&str; 3] = _;
 
// mod mcp::codes
/// `tools/call` without a tool `name`.
pub const INVALID_PARAMS: i64 = -32602;
/// The message is not a JSON-RPC request ...
pub const INVALID_REQUEST: i64 = -32600;
/// An unknown method, or `tools/call` of a ...
pub const METHOD_NOT_FOUND: i64 = -32601;
/// The message is not valid JSON.
pub const PARSE_ERROR: i64 = -32700;
 
// mod mcp::http
/// Largest accepted request body (16 MiB).
pub const MAX_BODY_BYTES: usize = _;
/// Session header.
pub const SESSION_HEADER: &str = "mcp-session-id";
 
// mod mcp::stdio
/// Longest accepted message line (16 MiB).
pub const MAX_LINE_BYTES: usize = _;

// mod mcp
/// Which contract tools a server exposes ...
pub type ToolFilter = Arc<dyn Fn(&str) -> bool + Send + Sync>;