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, fairness, and lifecycle counters.",
129        operations: &["session.task_scheduler_stats", "session.task_scheduler_health", "session.model_generation_pool_health", "session.model_middleware_health", "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: "evaluation_substrate",
169        category: "evaluation",
170        description: "Project bounded evidence, isolated auxiliary lifecycle, restart-safe dispatch claims, and immutable evaluation records through versioned boundaries.",
171        operations: &["evaluation.evidence", "evaluation.auxiliary", "evaluation.dispatch_ledger", "evaluation.result", "evaluation.result_store", "evaluation.wire_v1"],
172        host_owned: true,
173    },
174    CapabilitySpec {
175        id: "web_search",
176        category: "web",
177        description: "Search HTTP, native, RSS, and JavaScript-rendered engines through a3s-search v3.1.0.",
178        operations: &["session.web_search", "session.tool:web_search"],
179        host_owned: true,
180    },
181    CapabilitySpec {
182        id: "moli_runtime",
183        category: "web",
184        description: "Use a verified packaged or shared-cache Moli runtime with cross-process installation locking.",
185        operations: &["moli.default", "moli.ensure", "moli.packaged"],
186        host_owned: true,
187    },
188    CapabilitySpec {
189        id: "s3_workspace",
190        category: "workspace",
191        description: "Use an S3-compatible workspace backend with bounded reads and search.",
192        operations: &["session.workspace_backend:s3", "session.read_file", "session.write_file"],
193        host_owned: true,
194    },
195    CapabilitySpec {
196        id: "filesystem_agent_server",
197        category: "deployment",
198        description: "Serve agent directories with validated schedules, tools, readiness, and joined shutdown.",
199        operations: &["agent.serve_agent_dir", "serve.status", "serve.stop"],
200        host_owned: true,
201    },
202    CapabilitySpec {
203        id: "opentelemetry",
204        category: "observability",
205        description: "Export redacted runtime traces and metrics through the optional OTLP integration.",
206        operations: &["telemetry.init", "session.trace_events"],
207        host_owned: true,
208    },
209    CapabilitySpec {
210        id: "conversation",
211        category: "runtime",
212        description: "Send, run, stream, attach content, inspect history, and cancel transcript-affecting turns.",
213        operations: &["session.send", "session.run", "session.stream", "session.send_with_attachments", "session.history", "session.cancel"],
214        host_owned: false,
215    },
216    CapabilitySpec {
217        id: "run_control",
218        category: "runtime",
219        description: "Steer or cooperatively interrupt an active run with idempotent receipts and optimistic turn guards.",
220        operations: &["session.steer", "session.interrupt", "session.run_control_snapshot"],
221        host_owned: true,
222    },
223    CapabilitySpec {
224        id: "workspace_tools",
225        category: "workspace",
226        description: "Read, write, list, edit, patch, shell, glob, and grep through the governed workspace boundary.",
227        operations: &["session.read_file", "session.write_file", "session.ls", "session.edit_file", "session.patch_file", "session.bash", "session.glob", "session.grep", "session.git"],
228        host_owned: true,
229    },
230    CapabilitySpec {
231        id: "run_observability",
232        category: "observability",
233        description: "Inspect durable run snapshots, event pages, active tools, traces, and child-task state.",
234        operations: &["session.runs", "session.run_snapshot", "session.run_events", "session.run_event_page", "session.active_tools", "session.subagent_tasks"],
235        host_owned: false,
236    },
237    CapabilitySpec {
238        id: "governance",
239        category: "security",
240        description: "Configure permissions, confirmations, hooks, budgets, verification, sanitization, and sandbox policy.",
241        operations: &["session.pending_confirmations", "session.confirm_tool_use", "session.register_hook", "session.set_budget_guard", "session.verify_commands"],
242        host_owned: true,
243    },
244];
245
246/// Return the complete, ordered product capability inventory.
247pub fn sdk_capabilities() -> Vec<SdkCapability> {
248    CAPABILITY_SPECS
249        .iter()
250        .map(|spec| SdkCapability {
251            id: spec.id.to_owned(),
252            category: spec.category.to_owned(),
253            description: spec.description.to_owned(),
254            operations: spec
255                .operations
256                .iter()
257                .map(|value| (*value).to_owned())
258                .collect(),
259            host_owned: spec.host_owned,
260        })
261        .collect()
262}
263
264/// Return the schema identifier used by the inventory endpoint.
265pub const fn sdk_capabilities_schema() -> &'static str {
266    SDK_CAPABILITIES_SCHEMA_V1
267}
268
269#[cfg(test)]
270mod tests {
271    use super::*;
272    use std::collections::HashSet;
273
274    #[test]
275    fn inventory_is_stable_and_complete() {
276        let capabilities = sdk_capabilities();
277        assert!(capabilities.len() >= 20);
278        let ids = capabilities
279            .iter()
280            .map(|item| item.id.as_str())
281            .collect::<Vec<_>>();
282        assert_eq!(ids.len(), ids.iter().collect::<HashSet<_>>().len());
283        for capability in &capabilities {
284            assert!(!capability.category.is_empty());
285            assert!(!capability.description.is_empty());
286            assert!(!capability.operations.is_empty());
287        }
288        let required = [
289            "agent_runtime",
290            "conversation",
291            "governed_tools",
292            "web_search",
293            "moli_runtime",
294            "evaluation_substrate",
295            "persistence",
296            "governance",
297            "run_control",
298        ];
299        for id in required {
300            assert!(ids.contains(&id), "missing capability {id}");
301        }
302    }
303
304    #[test]
305    fn inventory_serializes_with_schema() {
306        let value = serde_json::json!({
307            "schema": sdk_capabilities_schema(),
308            "capabilities": sdk_capabilities(),
309        });
310        assert_eq!(value["schema"], SDK_CAPABILITIES_SCHEMA_V1);
311        assert!(value["capabilities"]
312            .as_array()
313            .is_some_and(|items| !items.is_empty()));
314    }
315}
a3s_code_core/sdk_capabilities.rs

a3s_code_core/
sdk_capabilities.rs
