a3s_code_core/
sdk_capabilities.rs

1//! Cross-language SDK capability contract.
2//!
3//! The Rust core has a deliberately larger implementation surface than any
4//! one FFI binding (for example, Rust hosts can provide native trait objects).
5//! This module is the single source of truth for the *product* capability
6//! surface.  Every official SDK exposes this inventory verbatim so an
7//! embedding application can discover features instead of guessing from
8//! package versions or parsing tool definitions.
9
10use serde::{Deserialize, Serialize};
11
12/// Schema identifier for [`SdkCapability`] values.
13pub const SDK_CAPABILITIES_SCHEMA_V1: &str = "a3s-code/sdk-capabilities/v1";
14
15/// A product capability exposed by the Core and its official SDKs.
16///
17/// `host_owned` means that the embedding application supplies policy,
18/// credentials, or a lifecycle owner.  It does not mean that the capability
19/// is unavailable to an SDK; the SDK exposes the same typed operation and the
20/// host remains responsible for the external resource.
21#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
22pub struct SdkCapability {
23    /// Stable snake-case identifier.
24    pub id: String,
25    /// Broad area used for UI grouping and telemetry.
26    pub category: String,
27    /// Human-readable contract summary.
28    pub description: String,
29    /// Canonical operation names. Language bindings map these to their naming
30    /// conventions (for example `web_search` becomes `webSearch` in Node).
31    pub operations: Vec<String>,
32    /// Whether the host owns policy, credentials, or an external lifecycle.
33    pub host_owned: bool,
34}
35
36struct CapabilitySpec {
37    id: &'static str,
38    category: &'static str,
39    description: &'static str,
40    operations: &'static [&'static str],
41    host_owned: bool,
42}
43
44// Keep this list in a stable product-facing order.  It intentionally follows the
45// capability map in README.md and includes the release/runtime surfaces that
46// are not model-visible tools (events, persistence, protocol, and Moli).
47const CAPABILITY_SPECS: &[CapabilitySpec] = &[
48    CapabilitySpec {
49        id: "agent_runtime",
50        category: "runtime",
51        description: "Create agents, bind workspaces, resume, replace, and close sessions.",
52        operations: &["agent.create", "agent.session", "agent.resume_session", "agent.close"],
53        host_owned: false,
54    },
55    CapabilitySpec {
56        id: "governed_tools",
57        category: "execution",
58        description: "Invoke built-in and MCP tools through validation, policy, confirmation, hooks, budgets, and tracing.",
59        operations: &["session.tool", "session.governed_tool", "session.tool_definitions"],
60        host_owned: true,
61    },
62    CapabilitySpec {
63        id: "code_intelligence",
64        category: "workspace",
65        description: "Query saved-file symbols, navigation, and diagnostics when a language service is available.",
66        operations: &["session.tool:code_symbols", "session.tool:code_navigation", "session.tool:code_diagnostics"],
67        host_owned: true,
68    },
69    CapabilitySpec {
70        id: "workspace_retrieval",
71        category: "workspace",
72        description: "Run exact, lexical, symbol, semantic, and hybrid retrieval with bounded session-owned state.",
73        operations: &["session.workspace_retrieval_status", "session.semantic_search", "session.hybrid_search"],
74        host_owned: true,
75    },
76    CapabilitySpec {
77        id: "context_memory",
78        category: "context",
79        description: "Use working, short-term, durable, and semantic memory with typed health and recall APIs.",
80        operations: &["session.memory", "session.remember", "session.recall", "session.memory_stats"],
81        host_owned: true,
82    },
83    CapabilitySpec {
84        id: "cognitive_packages",
85        category: "context",
86        description: "Bind exact cited cognitive knowledge generations supplied by an authoritative host.",
87        operations: &["session.cognitive_package_binding", "session.current_cognitive_package_binding"],
88        host_owned: true,
89    },
90    CapabilitySpec {
91        id: "use_runtime_tasks",
92        category: "integration",
93        description: "Project host-owned A3S Use runtime tasks as governed model and direct-tool capabilities.",
94        operations: &["session.tool:use_runtime_task"],
95        host_owned: true,
96    },
97    CapabilitySpec {
98        id: "model_adapters",
99        category: "model",
100        description: "Resolve configured Anthropic, OpenAI-compatible, and custom host model adapters.",
101        operations: &["agent.create", "session.send", "session.stream"],
102        host_owned: true,
103    },
104    CapabilitySpec {
105        id: "structured_output",
106        category: "model",
107        description: "Request schema-constrained model output with validation and bounded repair.",
108        operations: &["session.send", "session.run", "session.task"],
109        host_owned: true,
110    },
111    CapabilitySpec {
112        id: "mcp_and_skills",
113        category: "extension",
114        description: "Discover and mutate isolated MCP servers and filesystem or inline Skills.",
115        operations: &["session.add_mcp", "session.remove_mcp", "session.mcps", "session.add_skill", "session.skill_names"],
116        host_owned: true,
117    },
118    CapabilitySpec {
119        id: "planning_delegation",
120        category: "orchestration",
121        description: "Run plans, worker agents, delegated tasks, bounded fan-out, and cancellation.",
122        operations: &["session.task", "session.tasks", "session.parallel_task", "session.register_worker_agent"],
123        host_owned: true,
124    },
125    CapabilitySpec {
126        id: "priority_scheduling",
127        category: "orchestration",
128        description: "Share bounded priority/FIFO admission and observe scheduler occupancy.",
129        operations: &["session.task_scheduler_stats", "session.queue_stats", "session.set_lane_handler"],
130        host_owned: false,
131    },
132    CapabilitySpec {
133        id: "programmable_workflows",
134        category: "orchestration",
135        description: "Execute bounded QuickJS programs and resumable parallel or Flow-backed workflows.",
136        operations: &["session.program", "session.parallel", "session.parallel_resumable", "session.workflow_step"],
137        host_owned: true,
138    },
139    CapabilitySpec {
140        id: "persistence",
141        category: "state",
142        description: "Atomically save and restore session state, runs, artifacts, traces, and verification evidence.",
143        operations: &["session.save", "agent.resume_session", "session.get_artifact"],
144        host_owned: true,
145    },
146    CapabilitySpec {
147        id: "state_graph",
148        category: "state",
149        description: "Maintain hash-linked state graph events, patches, forks, and deterministic diffs.",
150        operations: &["state_graph.create", "state_graph.restore", "state_graph.propose_patch", "state_graph.diff"],
151        host_owned: true,
152    },
153    CapabilitySpec {
154        id: "agent_release_contract",
155        category: "deployment",
156        description: "Validate versioned asset manifests, provenance, and compatibility before activation.",
157        operations: &["release.admit", "release.bind_publication", "release.verify"],
158        host_owned: true,
159    },
160    CapabilitySpec {
161        id: "agent_protocol",
162        category: "transport",
163        description: "Serve versioned session/run start, cancellation, recovery, and event-page protocols.",
164        operations: &["agent_protocol.start", "agent_protocol.cancel", "agent_protocol.recover", "agent_protocol.events"],
165        host_owned: true,
166    },
167    CapabilitySpec {
168        id: "web_search",
169        category: "web",
170        description: "Search HTTP, native, RSS, and JavaScript-rendered engines through a3s-search v3.1.0.",
171        operations: &["session.web_search", "session.tool:web_search"],
172        host_owned: true,
173    },
174    CapabilitySpec {
175        id: "moli_runtime",
176        category: "web",
177        description: "Use a verified packaged or shared-cache Moli runtime with cross-process installation locking.",
178        operations: &["moli.default", "moli.ensure", "moli.packaged"],
179        host_owned: true,
180    },
181    CapabilitySpec {
182        id: "s3_workspace",
183        category: "workspace",
184        description: "Use an S3-compatible workspace backend with bounded reads and search.",
185        operations: &["session.workspace_backend:s3", "session.read_file", "session.write_file"],
186        host_owned: true,
187    },
188    CapabilitySpec {
189        id: "filesystem_agent_server",
190        category: "deployment",
191        description: "Serve agent directories with validated schedules, tools, readiness, and joined shutdown.",
192        operations: &["agent.serve_agent_dir", "serve.status", "serve.stop"],
193        host_owned: true,
194    },
195    CapabilitySpec {
196        id: "opentelemetry",
197        category: "observability",
198        description: "Export redacted runtime traces and metrics through the optional OTLP integration.",
199        operations: &["telemetry.init", "session.trace_events"],
200        host_owned: true,
201    },
202    CapabilitySpec {
203        id: "conversation",
204        category: "runtime",
205        description: "Send, run, stream, attach content, inspect history, and cancel transcript-affecting turns.",
206        operations: &["session.send", "session.run", "session.stream", "session.send_with_attachments", "session.history", "session.cancel"],
207        host_owned: false,
208    },
209    CapabilitySpec {
210        id: "run_control",
211        category: "runtime",
212        description: "Steer or cooperatively interrupt an active run with idempotent receipts and optimistic turn guards.",
213        operations: &["session.steer", "session.interrupt", "session.run_control_snapshot"],
214        host_owned: true,
215    },
216    CapabilitySpec {
217        id: "workspace_tools",
218        category: "workspace",
219        description: "Read, write, list, edit, patch, shell, glob, and grep through the governed workspace boundary.",
220        operations: &["session.read_file", "session.write_file", "session.ls", "session.edit_file", "session.patch_file", "session.bash", "session.glob", "session.grep", "session.git"],
221        host_owned: true,
222    },
223    CapabilitySpec {
224        id: "run_observability",
225        category: "observability",
226        description: "Inspect durable run snapshots, event pages, active tools, traces, and child-task state.",
227        operations: &["session.runs", "session.run_snapshot", "session.run_events", "session.run_event_page", "session.active_tools", "session.subagent_tasks"],
228        host_owned: false,
229    },
230    CapabilitySpec {
231        id: "governance",
232        category: "security",
233        description: "Configure permissions, confirmations, hooks, budgets, verification, sanitization, and sandbox policy.",
234        operations: &["session.pending_confirmations", "session.confirm_tool_use", "session.register_hook", "session.set_budget_guard", "session.verify_commands"],
235        host_owned: true,
236    },
237];
238
239/// Return the complete, ordered product capability inventory.
240pub fn sdk_capabilities() -> Vec<SdkCapability> {
241    CAPABILITY_SPECS
242        .iter()
243        .map(|spec| SdkCapability {
244            id: spec.id.to_owned(),
245            category: spec.category.to_owned(),
246            description: spec.description.to_owned(),
247            operations: spec
248                .operations
249                .iter()
250                .map(|value| (*value).to_owned())
251                .collect(),
252            host_owned: spec.host_owned,
253        })
254        .collect()
255}
256
257/// Return the schema identifier used by the inventory endpoint.
258pub const fn sdk_capabilities_schema() -> &'static str {
259    SDK_CAPABILITIES_SCHEMA_V1
260}
261
262#[cfg(test)]
263mod tests {
264    use super::*;
265    use std::collections::HashSet;
266
267    #[test]
268    fn inventory_is_stable_and_complete() {
269        let capabilities = sdk_capabilities();
270        assert!(capabilities.len() >= 20);
271        let ids = capabilities
272            .iter()
273            .map(|item| item.id.as_str())
274            .collect::<Vec<_>>();
275        assert_eq!(ids.len(), ids.iter().collect::<HashSet<_>>().len());
276        for capability in &capabilities {
277            assert!(!capability.category.is_empty());
278            assert!(!capability.description.is_empty());
279            assert!(!capability.operations.is_empty());
280        }
281        let required = [
282            "agent_runtime",
283            "conversation",
284            "governed_tools",
285            "web_search",
286            "moli_runtime",
287            "persistence",
288            "governance",
289            "run_control",
290        ];
291        for id in required {
292            assert!(ids.contains(&id), "missing capability {id}");
293        }
294    }
295
296    #[test]
297    fn inventory_serializes_with_schema() {
298        let value = serde_json::json!({
299            "schema": sdk_capabilities_schema(),
300            "capabilities": sdk_capabilities(),
301        });
302        assert_eq!(value["schema"], SDK_CAPABILITIES_SCHEMA_V1);
303        assert!(value["capabilities"]
304            .as_array()
305            .is_some_and(|items| !items.is_empty()));
306    }
307}
a3s_code_core/sdk_capabilities.rs

a3s_code_core/
sdk_capabilities.rs
