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: "workspace_tools",
211        category: "workspace",
212        description: "Read, write, list, edit, patch, shell, glob, and grep through the governed workspace boundary.",
213        operations: &["session.read_file", "session.write_file", "session.ls", "session.edit_file", "session.patch_file", "session.bash", "session.glob", "session.grep", "session.git"],
214        host_owned: true,
215    },
216    CapabilitySpec {
217        id: "run_observability",
218        category: "observability",
219        description: "Inspect durable run snapshots, event pages, active tools, traces, and child-task state.",
220        operations: &["session.runs", "session.run_snapshot", "session.run_events", "session.run_event_page", "session.active_tools", "session.subagent_tasks"],
221        host_owned: false,
222    },
223    CapabilitySpec {
224        id: "governance",
225        category: "security",
226        description: "Configure permissions, confirmations, hooks, budgets, verification, sanitization, and sandbox policy.",
227        operations: &["session.pending_confirmations", "session.confirm_tool_use", "session.register_hook", "session.set_budget_guard", "session.verify_commands"],
228        host_owned: true,
229    },
230];
231
232/// Return the complete, ordered product capability inventory.
233pub fn sdk_capabilities() -> Vec<SdkCapability> {
234    CAPABILITY_SPECS
235        .iter()
236        .map(|spec| SdkCapability {
237            id: spec.id.to_owned(),
238            category: spec.category.to_owned(),
239            description: spec.description.to_owned(),
240            operations: spec
241                .operations
242                .iter()
243                .map(|value| (*value).to_owned())
244                .collect(),
245            host_owned: spec.host_owned,
246        })
247        .collect()
248}
249
250/// Return the schema identifier used by the inventory endpoint.
251pub const fn sdk_capabilities_schema() -> &'static str {
252    SDK_CAPABILITIES_SCHEMA_V1
253}
254
255#[cfg(test)]
256mod tests {
257    use super::*;
258    use std::collections::HashSet;
259
260    #[test]
261    fn inventory_is_stable_and_complete() {
262        let capabilities = sdk_capabilities();
263        assert!(capabilities.len() >= 20);
264        let ids = capabilities
265            .iter()
266            .map(|item| item.id.as_str())
267            .collect::<Vec<_>>();
268        assert_eq!(ids.len(), ids.iter().collect::<HashSet<_>>().len());
269        for capability in &capabilities {
270            assert!(!capability.category.is_empty());
271            assert!(!capability.description.is_empty());
272            assert!(!capability.operations.is_empty());
273        }
274        let required = [
275            "agent_runtime",
276            "conversation",
277            "governed_tools",
278            "web_search",
279            "moli_runtime",
280            "persistence",
281            "governance",
282        ];
283        for id in required {
284            assert!(ids.contains(&id), "missing capability {id}");
285        }
286    }
287
288    #[test]
289    fn inventory_serializes_with_schema() {
290        let value = serde_json::json!({
291            "schema": sdk_capabilities_schema(),
292            "capabilities": sdk_capabilities(),
293        });
294        assert_eq!(value["schema"], SDK_CAPABILITIES_SCHEMA_V1);
295        assert!(value["capabilities"]
296            .as_array()
297            .is_some_and(|items| !items.is_empty()));
298    }
299}
a3s_code_core/sdk_capabilities.rs

a3s_code_core/
sdk_capabilities.rs
