Skip to main content

yoagent_rutis/
lib.rs

1// The `doc(cfg)` feature badges, on docs.rs only; a no-op on stable.
2#![cfg_attr(docsrs, feature(doc_cfg))]
3//! **yoagent-rutis** — extend [yoagent](https://docs.rs/yoagent) agents at
4//! runtime with [rutis](https://docs.rs/rutis) plugins, in Rust, TypeScript
5//! (on Node or Bun), Python or Go.
6//!
7//! rutis (a Rust port of the Cordis plugin kernel) loads, unloads, reloads
8//! and hot-updates plugins, and tears down everything a plugin registered
9//! when it goes. This crate lets such plugins contribute to agents while
10//! they live, through **one yoagent [`Extension`](yoagent::Extension)**:
11//!
12//! 1. [`RutisBridge::install`] provides the `yoagent` [`Registry`] service on
13//!    the rutis root.
14//! 2. Plugins register a [`Handler`] — a name plus whichever hooks it
15//!    implements: `tools`, `before_tool`, `after_tool`, `before_model`,
16//!    `on_input`, `on_stop`, `finish`, `on_event`. A registration ends when
17//!    its plugin unloads.
18//! 3. [`RutisBridge::extension`] returns a [`RutisExtension`] the host
19//!    installs with `Agent::with_extension` (or `with_tree_extension`, so
20//!    plugin policy also covers sub-agents). Each run snapshots the
21//!    registered handlers at its start.
22//!
23//! Every agent event also goes, as an [`AgentEventEmitted`], to decoupled
24//! Rust observers ([`PluginCtxExt::on_agent_event`]) — in-process, never on
25//! the rutis bus.
26//!
27//! yoagent itself knows nothing about rutis; the bridge uses only yoagent's
28//! public API.
29//!
30//! TypeScript, Python and Go handlers (features `node`, `bun`, `python`, `go`, `websocket`)
31//! can return images in tool results and write logs into the host's
32//! `tracing` output (target `yoagent_rutis::plugin`). Plugins from other
33//! agent ecosystems — DSH tool plugins, pi extensions — plug in through
34//! adapters shipped in the crate's `plugins/` directory ([`adapters`] says
35//! where); see the [README](https://github.com/yologdev/yoagent/tree/main/integrations/yoagent-rutis)
36//! and its adapter contract. With the `probe` feature, `probe` loads such a
37//! package through its adapter and reports what an agent gets from it.
38//!
39//! # Host
40//!
41//! ```no_run
42//! use rutis::host::CtxHost; // `Ctx::root`, `shutdown` and the other host methods
43//! use rutis::Ctx;
44//! use yoagent::{provider::{MockProvider, ModelConfig}, Agent};
45//! use yoagent_rutis::RutisBridge;
46//!
47//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
48//! let root = Ctx::root()?;
49//! let bridge = RutisBridge::install(&root)?; // on the root, once
50//! let mut agent = Agent::from_provider(MockProvider::text("hi"), ModelConfig::mock())
51//!     .with_extension(bridge.extension());
52//!
53//! // Load plugins whenever you like; each run sees the ones active at its start.
54//! // root.plugin(MyPlugin);
55//!
56//! agent.prompt("hello").await;
57//! # Ok(()) }
58//! ```
59//!
60//! # Plugin
61//!
62//! ```
63//! use std::sync::Arc;
64//!
65//! use rutis::{Ctx, Plugin};
66//! use yoagent::ToolDecision;
67//! use yoagent_rutis::{Handler, PluginCtxExt, Registry};
68//!
69//! struct NoShell;
70//!
71//! impl Plugin for NoShell {
72//!     type Deps = Arc<Registry>; // wait for the bridge
73//!
74//!     async fn apply(&self, ctx: &Ctx, _registry: Arc<Registry>) -> rutis::Result<()> {
75//!         ctx.register_handler(Handler::new("no-shell").with_before_tool(|call| {
76//!             match call.tool.as_str() {
77//!                 "bash" => ToolDecision::Deny("shell access is disabled".into()),
78//!                 _ => ToolDecision::Allow,
79//!             }
80//!         }))?;
81//!         Ok(())
82//!     }
83//! }
84//! let _plugin = NoShell;
85//! ```
86//!
87//! [`AgentPlugin`] wraps a handler as a plugin in one expression.
88//!
89//! # Plugins in other languages
90//!
91//! With the `node`, `bun`, `python`, `go` or `websocket` feature (rutis-bridge 0.20),
92//! [`RutisBridge::install`] also provides the registry to plugins in other
93//! languages, as the host service `yoagent`. Such a plugin registers an
94//! object (a Python dict, a Go map of functions) of async functions, with the same hooks and the
95//! same plain-JSON arguments as a Rust [`Handler`]:
96//!
97//! ```ts
98//! const yoagent = ctx.use('yoagent')
99//! ctx.effect(yoagent.register('no-shell', {
100//!   async before_tool(call) {
101//!     if (call.tool === 'bash') return { deny: 'shell access is disabled' }
102//!   },
103//! }))
104//! ```
105//!
106//! The bridge never loads plugins nor starts runtimes: the host does, with
107//! rutis-host's `SpawnPlugin` for each runtime (since rutis 0.19 the
108//! language features enable only the `yoagent` service) and rutis-loader
109//! rows, sharing `yoagent` in its catalog. See the `languages` module (built
110//! with those features) and `plugins/yoagent.d.ts` in the repository.
111//!
112//! # Semantics worth knowing
113//!
114//! - **A run uses the handlers registered when it started.** A plugin
115//!   unloaded (or restarted / updated) mid-run leaves its handler in that run
116//!   but **unavailable**: its tools fail ("no longer available", or "plugin
117//!   unloaded during the call" for one in flight), its `before_tool` denies,
118//!   its `on_input` rejects, its `after_tool` withholds the result (without
119//!   failing a required run), its other hooks are skipped. Never rebound to the new generation. See
120//!   [`registry`].
121//! - **Names are unique across plugins**: handler names, and the names of
122//!   static tools. A clash is refused (`ErrorKind::ServiceExists`, logged;
123//!   no retry when the holder unloads). The agent's own tools win over plugin
124//!   tools.
125//! - **Policies gate every tool call** — the agent's own tools too, not only
126//!   plugin tools.
127//! - **Handlers combine like extensions**: in registration order, a `Deny`
128//!   wins, a `Modify` feeds the next handler, notes are joined. See
129//!   [`extension`].
130//! - **Fail closed where it guards**: a `before_tool` that errors, panics or
131//!   times out denies the call; an `on_input` rejects; an `after_tool`
132//!   withholds the result. Other hooks are skipped and logged — unless the
133//!   host made the extension [`required`](RutisExtension::required), when
134//!   they fail the run.
135//! - **No policy means allow**, including while a policy plugin reloads and
136//!   before it first loads, unless the host sets
137//!   [`require_policy`](RutisExtension::require_policy).
138//! - **A host that is not running** (the root shut down, disposed or
139//!   restarted since the bridge was installed) denies
140//!   every tool call and rejects every prompt.
141//! - **Finite default timeouts** per handler call (60 s policy hooks, 30 s
142//!   input, 5 s turn hooks), plus the run's cancellation through yoagent.
143//! - **Install on the root.** A bridge installed on a plugin's context reads
144//!   as stopped for good once that plugin unloads or reloads.
145//! - **Route rutis's `ErrorSink`** (default: stderr) into your logging with
146//!   `Ctx::root_with_sink`.
147
148pub mod adapters;
149pub mod bridge;
150pub mod events;
151pub mod extension;
152pub mod handler;
153mod host;
154#[cfg(any(
155    feature = "node",
156    feature = "python",
157    feature = "bun",
158    feature = "go",
159    feature = "websocket"
160))]
161#[cfg_attr(
162    docsrs,
163    doc(cfg(any(
164        feature = "node",
165        feature = "python",
166        feature = "bun",
167        feature = "go",
168        feature = "websocket"
169    )))
170)]
171pub mod languages;
172mod late;
173pub mod plugin;
174#[cfg(feature = "probe")]
175#[cfg_attr(docsrs, doc(cfg(feature = "probe")))]
176pub mod probe;
177pub mod registry;
178#[cfg(feature = "loader")]
179#[cfg_attr(docsrs, doc(cfg(feature = "loader")))]
180pub mod rows;
181
182pub use bridge::RutisBridge;
183pub use events::AgentEventEmitted;
184pub use extension::{
185    RutisExtension, DEFAULT_INPUT_TIMEOUT, DEFAULT_POLICY_TIMEOUT, DEFAULT_TURN_TIMEOUT,
186};
187pub use handler::{Handler, Input, RunInfo, Stop, ToolCall, Turn};
188pub use late::LateTools;
189pub use plugin::{AgentPlugin, PluginCtxExt};
190pub use registry::{HandlerInfo, HookTiming, Registry, ToolOwner};
191
192/// The rutis this bridge is built against (`0.20`, the release train shared
193/// with `rutis-bridge`, `rutis-loader` and `rutis-host`). Its types are part
194/// of this crate's API, so any rutis minor bump (0.20 → 0.21) is a
195/// yoagent-rutis minor bump.
196pub use rutis;