sim_lib_agent/
lib.rs

1//! Agent runtime surfaces for SIM: agents, tools, memory, patterns, fixtures,
2//! fairness facets, and model-fabric contract re-exports.
3//!
4//! Model placement is resolved through the `model/at` catalog. In-process
5//! runners and registry `site` exports share that catalog: a loaded native or
6//! wasm library can register an opaque site value under a placement symbol, and
7//! this crate adapts that value into an `EvalSite` without adding site behavior
8//! to the kernel. `model/cached` wraps placements in a content-addressed
9//! cassette, so successful inference replies are replayable by normalized
10//! request content, model identity, parameters, result shape, and capabilities.
11
12#![forbid(unsafe_code)]
13#![deny(missing_docs)]
14#![allow(deprecated)]
15
16mod agents;
17pub mod atelier;
18mod capabilities;
19mod cli;
20mod components;
21mod config_probe;
22#[cfg(feature = "cookbook")]
23mod cookbook_tools;
24mod core_tools;
25mod embed;
26mod fairness;
27mod functions;
28mod memory;
29mod model_privacy;
30mod multimodal;
31mod pattern;
32mod planning;
33mod reply;
34mod roles;
35mod runner_projection;
36/// Cookbook recipes for this lib, embedded at build time.
37pub static RECIPES: sim_cookbook::EmbeddedDir =
38    include!(concat!(env!("OUT_DIR"), "/cookbook_recipes.rs"));
39
40#[cfg(test)]
41mod tests;
42mod tool_projection;
43mod tools;
44mod util;
45
46use sim_kernel::{
47    AbiVersion, CapabilityName, Cx, Expr, Lib, LibManifest, LibTarget, Linker, Result, Symbol,
48    Version,
49};
50use sim_lib_server::{
51    EvalSite, install_server_lib, register_address_resolver, register_line_driver,
52};
53
54const AGENT_LIB_ID: &str = "agent";
55const SANDBOX_CAPABILITY: &str = "sandbox";
56const SANDBOX_SUBPROCESS_CAPABILITY: &str = "sandbox-subprocess";
57const SANDBOX_WASM_CAPABILITY: &str = "sandbox-wasm";
58const VOICE_CAPABILITY: &str = "voice";
59const AGENT_SPAWN_CAPABILITY: &str = "agent-spawn";
60const AGENT_REPLACE_CAPABILITY: &str = "agent-replace";
61const AGENT_REFLECT_CAPABILITY: &str = "agent-reflect";
62const SWARM_LAUNCH_CAPABILITY: &str = "swarm-launch";
63const TOOL_EXPORT_KIND: &str = "tool";
64/// Capability name granting an agent the right to drive an AI model runner.
65pub const AI_RUNNER_CAPABILITY: &str = "ai-runner";
66/// Capability name granting an AI runner outbound network access.
67pub const AI_RUNNER_NETWORK_CAPABILITY: &str = "ai-runner-network";
68/// Capability name granting an AI runner access to a local (on-host) model.
69pub const AI_RUNNER_LOCAL_CAPABILITY: &str = "ai-runner-local";
70/// Capability name granting an AI runner access to secret material (e.g. API keys).
71pub const AI_RUNNER_SECRET_CAPABILITY: &str = "ai-runner-secret";
72/// Capability name granting an AI runner use of a response cache.
73pub const AI_RUNNER_CACHE_CAPABILITY: &str = "ai-runner-cache";
74/// Capability name granting an AI runner permission to emit raw request/response logs.
75pub const AI_RUNNER_RAW_LOG_CAPABILITY: &str = "ai-runner-raw-log";
76/// Capability name granting authority to register or replace model placements.
77pub const AI_RUNNER_PLACEMENT_CAPABILITY: &str = "ai-runner-placement";
78
79#[cfg(test)]
80pub(crate) use agents::component_name;
81pub use agents::{Agent, AgentFabric, AgentManifest, AgentRef, Budget, ComponentRef, TopologyRef};
82use agents::{agent_line_driver_factory, resolve_agent_address};
83pub use atelier::{
84    AgentMission, AtelierAction, AtelierBackend, CONTRACT_NATIVE_SCHEMA,
85    ContractNativeAtelierReport, ContractNativeDeckSummary, ContractNativeGrammarSummary,
86    ContractNativeGuardDenial, ContractNativeProjectionSummary, ContractNativeRouteAttempt,
87    GuardCapability, GuardDecision, GuardEvaluation, GuardRefusal, RadarChunk, RadarError,
88    RadarHint, RadarIndex, RadarQuery, RadarReport, RadarResult, SelfHostingScenario, SourceSpan,
89    cassette_content_hash, contract_native_guard_denials, deterministic_contract_native_report,
90    evaluate_guarded_action, guard_action, retrieve_radar_hints, self_hosting_scenarios,
91    validate_self_hosting_scenarios,
92};
93pub(crate) use capabilities::{
94    edit_capability, exec_capability, find_capability, fs_read_capability, fs_write_capability,
95    net_http_capability, require_component_capability, require_fs_read_capability,
96    require_fs_write_capability, require_net_http_capability,
97};
98use cli::{agent_cli_exports, register_agent_cli};
99pub use components::RunnerBackend;
100pub(crate) use components::{
101    AgentComponent, ComponentBackend, RecorderBackend, capabilities_option, component_kind_symbol,
102    maybe_f64_option, maybe_u32_option, parse_component_options, path_option, string_option,
103    symbol_option,
104};
105pub use config_probe::{
106    AgentModelConfigProbe, AgentModelProviderPresence, agent_model_config_probe_symbol,
107    model_defaults_config_lib_symbol,
108};
109pub(crate) use embed::{cosine, embed};
110pub use fairness::*;
111use functions::{agent_exports, register_agent_functions};
112pub(crate) use memory::lock_entries;
113pub(crate) use memory::resolve_memory_backend;
114pub use memory::{
115    BlackboardMemory, FileMemory, MemoryBackend, MemoryKind, PersonaMemory, VectorMemory,
116    WorkingMemory,
117};
118pub use multimodal::{
119    FakeAsrFixture, FakeAsrRunner, FakeAsrSegment, FakeSensorFrame, FakeSensorStream,
120    FakeVisionFixture, FakeVisionRunner,
121};
122pub use pattern::{AgentPattern, AgentPatternSlot};
123pub use planning::{
124    Decomposition, PlanningOutput, PlanningTask, Reflection, decompose, decompose_and_run, reflect,
125};
126pub use roles::{AgentRole, stamp_envelope_role, stamp_frame_role};
127pub use runner_projection::{ExternalRunnerSpec, external_runner_value};
128pub use sim_lib_agent_runner_core::{
129    ModelBid, ModelCard, ModelEvent, ModelEventSink, ModelRequest, ModelResponse, ModelRunner,
130    ModelUsage,
131};
132pub use tool_projection::{ToolSpec, install_tool};
133pub use tools::Tool;
134pub(crate) use tools::ToolFilter;
135pub(crate) use util::{
136    installed_codecs, keyword, string_from_value, stringish_from_value, symbol_from_value,
137    u32_from_expr, u32_from_value, value_from_expr,
138};
139
140/// The agent runtime library, registering agent functions, tools, and CLI
141/// exports as a loadable SIM [`Lib`].
142pub struct AgentLib;
143
144impl Lib for AgentLib {
145    fn manifest(&self) -> LibManifest {
146        LibManifest {
147            id: Symbol::new(AGENT_LIB_ID),
148            version: Version(env!("CARGO_PKG_VERSION").to_owned()),
149            abi: AbiVersion { major: 0, minor: 1 },
150            target: LibTarget::HostRegistered,
151            requires: Vec::new(),
152            capabilities: Vec::new(),
153            exports: {
154                let mut exports = agent_exports();
155                exports.extend(agent_cli_exports());
156                exports
157            },
158        }
159    }
160
161    fn load(&self, cx: &mut sim_kernel::LoadCx, linker: &mut Linker<'_>) -> Result<()> {
162        register_agent_functions(cx, linker)?;
163        register_agent_cli(cx, linker)
164    }
165}
166
167/// Installs the agent library into `cx`, pulling in the server lib, registering
168/// the agent address resolver and line driver, and loading [`AgentLib`].
169pub fn install_agent_lib(cx: &mut Cx) -> Result<()> {
170    install_server_lib(cx)?;
171    register_address_resolver(Symbol::new("agent"), resolve_agent_address)?;
172    register_line_driver(Symbol::new("agent"), agent_line_driver_factory)?;
173    sim_lib_core::install_once(cx, &AgentLib)?;
174    core_tools::install_core_tools(cx)?;
175    #[cfg(feature = "cookbook")]
176    cookbook_tools::install_cookbook_tools(cx)?;
177    Ok(())
178}
179
180/// A pluggable agent building block (runner, tool, memory, planner, and so on)
181/// that participates in evaluation as an [`EvalSite`].
182pub trait Component: EvalSite {
183    /// Returns the kind of component this is.
184    fn kind(&self) -> ComponentKind;
185    /// Returns the component's name symbol.
186    fn name(&self) -> &Symbol;
187    /// Returns the capabilities this component requires or grants.
188    fn capabilities(&self) -> &[CapabilityName];
189    /// Produces a self-describing expression for inspection of this component.
190    fn reflect(&self, cx: &mut Cx) -> Result<Expr>;
191}
192
193#[derive(Clone, Debug, PartialEq, Eq)]
194/// The role a [`Component`] plays within an agent.
195pub enum ComponentKind {
196    /// Drives a model to produce responses.
197    Runner,
198    /// Exposes a callable tool the agent may invoke.
199    Tool,
200    /// Stores and retrieves agent memory.
201    Memory,
202    /// Decomposes tasks and plans agent execution.
203    Planner,
204    /// Scores or ranks candidate responses.
205    Judge,
206    /// Routes work among targets.
207    Router,
208    /// Shapes the agent's voice or style.
209    Persona,
210    /// Retrieves external context or documents.
211    Retriever,
212    /// Confines execution within a sandbox.
213    Sandbox,
214    /// Records transcripts, audits, or metrics.
215    Recorder,
216    /// Handles speech synthesis or recognition.
217    Voice,
218    /// Describes the agent network's topology.
219    Topology,
220    /// A custom component kind named by the given symbol.
221    Custom(Symbol),
222}
sim_lib_agent/lib.rs

sim_lib_agent/
lib.rs
