cua-spaces: client

pub enum Node {
  Null,
  Bool(bool),
  Int(i64),
  Str(String),
  Array(Vec<Node>),
  Object(Vec<(String, Node)>),
}
impl Node {
  fn object(entries: Vec<(&str, Node)>) -> Node;
  fn string(value: impl Into<String>) -> Node;
  fn optional_string(value: &Option<String>) -> Node;
  fn optional_int(value: Option<i64>) -> Node;
  fn optional_bool(value: Option<bool>) -> Node;
  fn strings(values: &[String]) -> Node;
  fn to_json(&self) -> String;
}

pub struct Connection { /* private fields */ }
impl Connection {
  fn new(transport: Arc<dyn ToolTransport>) -> Self;
  fn transport(&self) -> Arc<dyn ToolTransport>;
  fn available_tools(&self) -> Result<Vec<String>>;
  fn call_tool_raw(&self, tool: &str, arguments_json: &str) -> Result<String>;
  fn spaces(&self) -> Result<Vec<SpaceInfo>>;
  fn attach(self: &Arc<Self>, space_id: &str, require_ready: bool) -> Result<Space>;
  fn create_space(self: &Arc<Self>, options: CreateSpaceOptions) -> Result<Space>;
  fn delete_space(&self, space_id: &str) -> Result<()>;
  fn add_space(&self, url: &str, token: Option<&str>, name: Option<&str>) -> Result<SpaceInfo>;
  fn remove_space(&self, space_id: &str) -> Result<()>;
  fn hotspot_start(&self, space_id: &str) -> Result<HotspotStatus>;
  fn hotspot_stop(&self) -> Result<HotspotStatus>;
  fn hotspot_status(&self) -> Result<HotspotStatus>;
  fn volume_ls(&self, path: &str, as_agent: Option<&str>, in_space: Option<&str>) -> Result<Map<String, Value>>;
  fn volume_read(&self, path: &str, version: Option<&str>, as_agent: Option<&str>, in_space: Option<&str>) -> Result<Map<String, Value>>;
  fn volume_write(&self, path: &str, content: &str, encoding: Option<&str>, if_etag: Option<&str>, create_only: bool, as_agent: Option<&str>) -> Result<Map<String, Value>>;
  fn volume_delete(&self, path: &str, if_etag: Option<&str>) -> Result<Map<String, Value>>;
  fn volume_history(&self, path: &str) -> Result<Map<String, Value>>;
  fn volume_restore(&self, path: &str, version: &str) -> Result<Map<String, Value>>;
  fn volume_grant(&self, principal: &str, prefix: &str, mode: &str, expires_in_secs: Option<u64>) -> Result<Map<String, Value>>;
  fn volume_revoke(&self, grant_id: &str) -> Result<Map<String, Value>>;
  fn volume_grants(&self, all: bool) -> Result<Map<String, Value>>;
  fn volume_request_access(&self, as_agent: &str, prefix: &str, mode: &str, reason: &str) -> Result<Map<String, Value>>;
  fn volume_requests(&self) -> Result<Map<String, Value>>;
  fn volume_approve(&self, request_id: &str) -> Result<Map<String, Value>>;
  fn volume_deny(&self, request_id: &str) -> Result<Map<String, Value>>;
  fn volume_audit(&self, limit: u32) -> Result<Map<String, Value>>;
  fn volume_storage(&self) -> Result<Map<String, Value>>;
  fn volume_storage_set(&self, update: Value) -> Result<Map<String, Value>>;
  fn volume_mount_status(&self) -> Result<Map<String, Value>>;
  fn volume_mount(&self) -> Result<Map<String, Value>>;
  fn volume_unmount(&self) -> Result<Map<String, Value>>;
  fn volume_sync_status(&self) -> Result<Map<String, Value>>;
  fn volume_sync_events(&self, since_seq: u64, wait_ms: u32) -> Result<Map<String, Value>>;
  fn volume_sync_resolve(&self, path: &str) -> Result<Map<String, Value>>;
  fn volume_cache_stats(&self) -> Result<Map<String, Value>>;
  fn volume_cache_set(&self, capacity_bytes: u64) -> Result<Map<String, Value>>;
  fn volume_cache_clear(&self) -> Result<Map<String, Value>>;
  fn cloud_status(&self, provider: Option<&str>) -> Result<Map<String, Value>>;
  fn cloud_connect(&self, target: Value, make_default: bool, ttl_hours: Option<u32>) -> Result<Map<String, Value>>;
  fn cloud_test(&self, target: Value) -> Result<Map<String, Value>>;
  fn cloud_disconnect(&self, provider: &str) -> Result<Map<String, Value>>;
  fn cloud_sweep(&self, provider: Option<&str>, dry_run: bool, all: bool) -> Result<Map<String, Value>>;
  fn create_persistent_agent(&self, name: &str, harness: &str, space_id: &str, model: Option<&str>, base_url: Option<&str>, env_from_host: &[String]) -> Result<Record>;
  fn persistent_agents(&self) -> Result<Vec<Record>>;
  fn remove_persistent_agent(&self, name: &str) -> Result<Record>;
  fn send_to_persistent_agent(&self, name: &str, text: &str) -> Result<Record>;
  fn save_agent_home(&self, name: &str) -> Result<Record>;
  fn pause_agent(&self, name: &str) -> Result<Record>;
  fn resume_agent(&self, name: &str, prompt: Option<&str>) -> Result<Record>;
  fn add_routine(&self, agent: &str, title: &str, prompt: &str, schedule: &RoutineSchedule) -> Result<Record>;
  fn routines(&self, agent: Option<&str>) -> Result<Vec<Record>>;
  fn remove_routine(&self, id: &str) -> Result<()>;
  fn set_routine_enabled(&self, id: &str, enabled: bool) -> Result<Record>;
  fn notify_user(&self, title: &str, body: &str) -> Result<String>;
  fn notifications(&self, unread_only: bool) -> Result<Vec<Record>>;
  fn mark_notifications_read(&self, ids: &[String]) -> Result<u64>;
  fn allow_computer(&self, agent: &str, machine: &str) -> Result<Record>;
  fn revoke_computer(&self, agent: &str, machine: Option<&str>) -> Result<u64>;
  fn computer_access(&self, agent: Option<&str>) -> Result<Vec<Record>>;
}

pub struct ToolCoverage {
  pub tool: String,
  pub sdk_symbol: String,
  pub providers: Vec<String>,
  pub metering: String,
}

pub struct InProcessTransport { /* private fields */ }
impl InProcessTransport {
  fn new(server: McpServer, runtime: Handle) -> Self;
}

pub struct LineFramer { /* private fields */ }
impl LineFramer {
  fn new(maximum_frame_bytes: usize) -> Self;
  fn maximum_frame_bytes(&self) -> usize;
  fn buffered_byte_count(&self) -> usize;
  fn append(&mut self, chunk: &[u8]);
  fn take_frame(&mut self) -> Result<Option<Vec<u8>>>;
  fn take_frames(&mut self) -> Result<Vec<Vec<u8>>>;
}

pub struct Admission {
  pub accepted: Vec<TransferCandidate>,
  pub rejected: Vec<Rejection>,
}

pub struct AgentEvent {
  pub run_id: String,
  pub line_index: u32,
  pub kind: AgentEventKind,
  pub text: String,
  pub state: Option<AgentState>,
  pub exit_code: Option<i32>,
  pub is_inferred: bool,
}

pub enum AgentEventKind {
  Text,
  StateChanged,
  Finished,
  Raw,
  ToolUse,
  Artifact,
  Question,
}
impl AgentEventKind {
  fn as_str(self) -> &'static str;
  fn is_inferred_only(self) -> bool;
}

pub struct AgentKindInfo {
  pub id: String,
  pub is_production_ready: bool,
}

pub struct AgentRunHandle {
  pub id: String,
  pub space: String,
  pub agent: String,
  pub turn_model: TurnModel,
  pub notes: Vec<String>,
  pub approvals_are_enforced: bool,
}
impl AgentRunHandle {
  fn directory(&self) -> String;
}

pub struct AgentStartRequest {
  pub agent: String,
  pub prompt: String,
  pub metadata: Vec<MetadataEntry>,
  pub shows_window: bool,
  pub timeout_seconds: Option<u32>,
}

pub enum AgentState {
  Running,
  AwaitingInput,
  Idle,
  Finished,
  Failed,
  Crashed,
  Unknown,
}
impl AgentState {
  fn from_wire(wire: Option<&str>) -> Self;
  fn as_str(self) -> &'static str;
  fn is_live(self) -> bool;
  fn has_ended(self) -> bool;
}

pub struct CreateSpaceOptions {
  pub image: Option<String>,
  pub on: Option<String>,
  pub kind: Option<String>,
  pub runtime: Option<String>,
  pub name: Option<String>,
  pub reuse: bool,
  pub wait: Option<bool>,
}

pub struct Delivery {
  pub run_id: String,
  pub accepted: bool,
  pub reason: String,
  pub state_at_refusal: Option<AgentState>,
  pub queued_for_ms: Option<u64>,
}
impl Delivery {
  fn decode(row: &Map<String, Value>, run_id: &str, queued_for_ms: Option<u64>) -> Self;
  fn required(self) -> Result<Delivery>;
}

pub enum DeliveryMode {
  RefuseIfBusy,
  AbandonCurrentTurn,
  QueueUntilIdle,
}

pub struct HarnessCapabilities {
  pub statuses: Vec<String>,
  pub harnesses: Vec<AgentKindInfo>,
  pub status_classifier: String,
}
impl HarnessCapabilities {
  fn decode(row: &Map<String, Value>) -> Self;
}

pub struct HotspotStatus {
  pub is_sharing: bool,
  pub space: Option<String>,
  pub detail: String,
}
impl HotspotStatus {
  fn decode(row: &Map<String, Value>) -> Self;
}

pub struct MetadataEntry {
  pub key: String,
  pub value: String,
}

pub struct ProviderCapabilities {
  pub provider: String,
  pub agents: bool,
  pub window_list: bool,
  pub upload: bool,
  pub download: bool,
  pub rcdp_streaming: bool,
  pub teleport: bool,
  pub provisioning: bool,
  pub server_backstop: bool,
  pub notes: Vec<String>,
}

pub struct Rejection {
  pub candidate: TransferCandidate,
  pub violation: String,
}

pub struct RemoteFile {
  pub path: String,
  pub name: String,
  pub byte_count: Option<u64>,
}

pub struct RunSnapshot {
  pub id: String,
  pub space: String,
  pub agent: String,
  pub state: AgentState,
  pub reason: String,
  pub accepts_message: bool,
  pub exit_code: Option<i32>,
  pub summary: String,
  pub output_tail: Option<String>,
  pub output_truncated: bool,
  pub created_at_ms: Option<i64>,
  pub reason_is_carried_forward: bool,
  pub raw_prompt: Option<String>,
}
impl RunSnapshot {
  fn decode(row: &Map<String, Value>, run_id: &str, space: &str, requested_tail: Option<u32>, previous: Option<&RunSnapshot>) -> Self;
  fn differs_visibly(&self, other: &RunSnapshot) -> bool;
}

pub struct SchedulerFacts {
  pub is_server_backed: bool,
  pub missed_slot_policy: String,
}

pub struct ServiceCatalog {
  pub service: String,
  pub tools: Vec<SpaceTool>,
  pub other_services: Vec<String>,
  pub instructions: Option<String>,
  pub not_ready_warning: Option<String>,
}
impl ServiceCatalog {
  fn is_empty_but_reachable(&self) -> bool;
}

pub struct SpaceInfo {
  pub id: String,
  pub provider: SpaceProvider,
  pub operating_system: String,
  pub state: SpaceState,
  pub raw_phase: String,
  pub ip_address: Option<String>,
}
impl SpaceInfo {
  fn from_row(row: &Map<String, Value>) -> Self;
  fn is_ready(&self) -> bool;
  fn capabilities(&self) -> ProviderCapabilities;
}

pub enum SpaceProvider {
  Local,
  Fleet,
  Direct,
  Demo,
  Unknown,
}
impl SpaceProvider {
  fn from_raw(raw: &str) -> Self;
  fn as_str(self) -> &'static str;
  fn home(self) -> &'static str;
  fn default_upload_directory(self) -> String;
  fn capabilities(self) -> ProviderCapabilities;
}

pub enum SpaceState {
  Ready,
  Starting,
  Stopped,
  Failed,
  Unknown,
}
impl SpaceState {
  fn from_phase(phase: &str) -> Self;
  fn is_ready(self) -> bool;
  fn as_str(self) -> &'static str;
}

pub struct SpaceTool {
  pub service: String,
  pub name: String,
  pub summary: String,
  pub input_schema_json: String,
}

pub struct SpaceWindow {
  pub id: String,
  pub app: String,
  pub title: String,
  pub width_px: u32,
  pub height_px: u32,
  pub scale_factor_hundredths: u32,
  pub visible: bool,
  pub process_id: Option<i32>,
}
impl SpaceWindow {
  fn from_row(row: &Map<String, Value>) -> Self;
  fn looks_like_rcdp_target(&self) -> bool;
}

pub struct StopOutcome {
  pub stopped: bool,
  pub alive: Option<bool>,
  pub reason: String,
}
impl StopOutcome {
  fn decode(row: &Map<String, Value>) -> Self;
}

pub struct StreamEndpoint {
  pub host: String,
  pub port: u16,
  pub driver_port: u16,
  pub token: String,
}
impl StreamEndpoint {
  fn from_row(row: &Map<String, Value>, fallback_host: Option<&str>) -> Self;
}

pub struct ToolContentPart {
  pub kind: String,
  pub text: String,
  pub data_base64: String,
  pub mime_type: String,
}

pub struct TransferCandidate {
  pub name: String,
  pub byte_count: u64,
}

pub struct TransferLimits {
  pub max_file_count: u32,
  pub max_bytes_per_file: u64,
  pub max_bytes_per_batch: u64,
  pub is_server_published: bool,
}
impl TransferLimits {
  fn conservative_default() -> Self;
  fn unlimited() -> Self;
  fn admit(&self, candidates: &[TransferCandidate]) -> Admission;
  fn check(&self, candidates: &[TransferCandidate]) -> Result<()>;
}

pub struct TurnModel {
  pub kind: String,
  pub accepts_follow_ups: bool,
}
impl TurnModel {
  fn from_row(row: &Map<String, Value>) -> Self;
}

pub struct UploadPlacement {
  pub kind: UploadPlacementKind,
  pub path: String,
}
impl UploadPlacement {
  fn collision_safe_default() -> Self;
}

pub enum UploadPlacementKind {
  ExactPath,
  CollisionSafe,
  Clobbering,
}

pub enum RoutineSchedule {
  EveryMinutes(i64),
  DailyAt(String),
  WeeklyOn(String),
}

pub struct ScriptedTransport { /* private fields */ }
impl ScriptedTransport {
  const SCRIPT_SCHEMA: &'static str = "cua.control.script/1";;
  fn from_script(script_json: &str) -> Result<Self>;
  fn calls(&self) -> Vec<(String, Value)>;
  fn call_count(&self) -> usize;
}

pub struct Space {
  pub info: SpaceInfo,
}
impl Space {
  fn id(&self) -> &str;
  fn provider(&self) -> SpaceProvider;
  fn capabilities(&self) -> ProviderCapabilities;
  fn home(&self) -> &'static str;
  fn connection(&self) -> Arc<Connection>;
  fn delete(&self) -> Result<()>;
  fn stop(&self) -> Result<Map<String, Value>>;
  fn start(&self) -> Result<Map<String, Value>>;
  fn share_with(&self, who: &str, role: &str) -> Result<Map<String, Value>>;
  fn unshare(&self, who: Option<&str>) -> Result<Map<String, Value>>;
  fn shares(&self) -> Result<Map<String, Value>>;
  fn relay_register(&self) -> Result<Map<String, Value>>;
  fn relay_unregister(&self) -> Result<Map<String, Value>>;
  fn bash(&self, command: &str) -> Result<String>;
  fn write_text(&self, text: &str, path: &str) -> Result<RemoteFile>;
  fn upload(&self, local_path: &str, placement: &UploadPlacement, byte_count: Option<u64>) -> Result<RemoteFile>;
  fn send_file(&self, local_path: &str, target_directory: Option<String>, respect_ignorefiles: Option<bool>) -> Result<String>;
  fn download(&self, remote_path: &str, into_directory: Option<String>) -> Result<String>;
  fn windows(&self) -> Result<Vec<SpaceWindow>>;
  fn window_of_process(&self, process_id: i32) -> Result<Option<SpaceWindow>>;
  fn stream_endpoint(&self, force_refresh: bool) -> Result<StreamEndpoint>;
  fn stream_window_to_operator_desktop(&self, window_id: &str) -> Result<()>;
  fn pin_picture_in_picture_on_operator_desktop(&self) -> Result<()>;
  fn unpin_picture_in_picture_from_operator_desktop(&self) -> Result<()>;
  fn open_viewer_on_operator_desktop(&self) -> Result<()>;
  fn service_catalog(&self, service: Option<String>, matching: Option<String>) -> Result<ServiceCatalog>;
  fn services(&self) -> Result<Vec<String>>;
  fn call_service_tool(&self, tool: &str, service: Option<String>, arguments_json: &str) -> Result<Vec<ToolContentPart>>;
  fn start_agent(&self, request: &AgentStartRequest) -> Result<AgentRunHandle>;
  fn run_status(&self, run_id: &str, tail: u32) -> Result<RunSnapshot>;
  fn runs(&self) -> Result<Vec<RunSnapshot>>;
  fn send_message(&self, run_id: &str, text: &str, mode: DeliveryMode, queue_timeout_ms: Option<u64>) -> Result<Delivery>;
  fn stop_run(&self, run_id: &str) -> Result<StopOutcome>;
  fn events_after(&self, run_id: &str, cursor: u64, max: u32) -> Result<Map<String, Value>>;
  fn interrupt_run(&self, run_id: &str) -> Result<bool>;
  fn harness_capabilities(&self) -> Result<HarnessCapabilities>;
  fn run_events(&self, run_id: &str, tail: u32) -> Result<Vec<AgentEvent>>;
  fn approve_run(&self, _run_id: &str, _decision: &str) -> Result<()>;
  fn teleport_manifest(&self, app: &str, scope: TeleportScope) -> Result<TeleportManifest>;
  fn teleport_send(&self, approval: &Approval) -> Result<TeleportReceipt>;
}

pub enum SpacesError {
  TransportUnavailable(String),
  TransportFraming(String),
  ToolFailed { tool: String, message: String },
  RpcFailed { method: String, code: i64, message: String },
  MalformedResponse { tool: String, detail: String },
  UnsupportedByProvider { tool: String, provider: String, detail: String },
  SpaceUnavailable(String, String),
  RunNotFound(String),
  LimitExceeded(String),
  WouldProvision(String),
  LocalFileUnavailable(String),
  TimedOut { waiting_for: String, after_ms: u64 },
  NotImplementedYet(String),
  TeleportRefused(String),
}
impl SpacesError {
  fn tag(&self) -> &'static str;
}

pub struct Approval { /* private fields */ }
impl Approval {
  fn app(&self) -> &str;
  fn scope(&self) -> TeleportScope;
  fn space(&self) -> &str;
  fn approved_bytes(&self) -> u64;
  fn approved_paths(&self) -> Vec<String>;
  fn uses_server_default(&self) -> bool;
}

pub struct TeleportItem {
  pub relative_path: String,
  pub label: String,
  pub estimated_bytes: u64,
  pub is_sensitive: bool,
  pub is_checked_by_default: bool,
  pub count: Option<u32>,
  pub count_noun: Option<String>,
  pub explanation: String,
}
impl TeleportItem {
  fn from_row(row: &Map<String, Value>) -> Self;
}

pub struct TeleportManifest {
  pub app: String,
  pub display_name: String,
  pub scope: TeleportScope,
  pub server_scope: String,
  pub items: Vec<TeleportItem>,
  pub total_estimated_bytes: u64,
  pub notes: Vec<String>,
}
impl TeleportManifest {
  fn decode(app: &str, scope: TeleportScope, payload: &Value) -> Self;
  fn sensitive_items(&self) -> Vec<TeleportItem>;
  fn default_selection(&self) -> Vec<TeleportItem>;
  fn login_only_selection(&self) -> Vec<TeleportItem>;
  fn approving(&self, space_id: &str, relative_paths: &[String], acknowledging_sensitive_items: bool) -> Result<Approval>;
  fn approving_server_default(&self, space_id: &str, acknowledging_sensitive_items: bool) -> Result<Approval>;
}

pub struct TeleportReceipt {
  pub app: String,
  pub space: String,
  pub method: String,
  pub transferred_paths: Vec<String>,
  pub raw_result: String,
}

pub enum TeleportScope {
  Full,
  Tabs,
}
impl TeleportScope {
  fn as_str(self) -> &'static str;
}

pub trait ToolTransport: Send + Sync {
  fn call_tool(&self, name: &str, arguments: &Value) -> Result<Value>;
  fn available_tools(&self) -> Result<Vec<String>>;
}

// mod client::conformance
/// Drive the whole typed control-plane ...
pub fn run_session(script_json: &str) -> Result<String>
/// The scripted backend the session runs ...
pub fn session_script() -> String
 
// mod client::coverage
/// The coverage table, in contract order ...
pub fn coverage() -> Vec<ToolCoverage>
 
// mod client::metadata
/// The metadata carried by a prompt echo ...
pub fn decode(text: &str) -> Vec<MetadataEntry>
/// The prompt as it should be sent.
pub fn encode(prompt: &str, metadata: &[MetadataEntry]) -> String
/// The text with the marker removed, for ...
pub fn strip(text: &str) -> String
 
// mod client::model
pub fn agent_kind(id: &str) -> AgentKindInfo
/// Split a snapshot into events, **without ...
pub fn events_from_snapshot(snapshot: &RunSnapshot) -> Vec<AgentEvent>
/// The provider half of a qualified Space ...
pub fn provider_prefix(space_id: &str) -> Option<&str>
pub fn scheduler_facts() -> SchedulerFacts
pub fn tool_content_parts(payload: &Value) -> Vec<ToolContentPart>
 
// mod client::transport
/// The **only** place `isError` is read ...
pub fn decode_tool_result(tool: &str, result: &Value) -> Result<Value>
/// The payload as an array, tolerating the ...
pub fn expect_array(payload: &Value, unwrapping: Option<&str>) -> Vec<Value>
/// The payload as an object, or a ...
pub fn expect_object(tool: &str, payload: &Value) -> Result<Map<String, Value>>

// mod client
/// The version of this client.
pub const VERSION: &str = "0.1.0";
 
// mod client::conformance
pub const SESSION_SCHEMA: &str = "cua.control.session/1";
 
// mod client::framing
/// 64 MiB.
pub const DEFAULT_MAXIMUM_FRAME_BYTES: usize = _;
 
// mod client::metadata
pub const CLOSE_MARKER: &str = "-->";
/// Recognisable, greppable, and last: so ...
pub const OPEN_MARKER: &str = "<!--cua-spaces-meta:";
 
// mod client::model
/// `false` in every shipping backend.
pub const APPROVALS_ARE_ENFORCED: bool = false;
/// The two harnesses that are wired end to ...
pub const PRODUCTION_READY_AGENTS: [&str; 2] = _;
pub const SCHEDULER_IS_SERVER_BACKED: bool = false;
 
// mod client::transport
pub const CLIENT_NAME: &str = "cua-spaces-client";
/// The MCP revision the client announces.
pub const CLIENT_PROTOCOL_VERSION: &str = "2024-11-05";
pub const CLIENT_VERSION: &str = "0.1.0";

// mod client
pub type Result<T> = Result<T, SpacesError>;
 
// mod client::persistent
/// One JSON record.
pub type Record = Map<String, Value>;