Expand description
yoagent-rutis — extend yoagent agents at runtime with rutis plugins, in Rust, TypeScript (on Node or Bun), Python or Go.
rutis (a Rust port of the Cordis plugin kernel) loads, unloads, reloads
and hot-updates plugins, and tears down everything a plugin registered
when it goes. This crate lets such plugins contribute to agents while
they live, through one yoagent Extension:
RutisBridge::installprovides theyoagentRegistryservice on the rutis root.- Plugins register a
Handler— a name plus whichever hooks it implements:tools,before_tool,after_tool,before_model,on_input,on_stop,finish,on_event. A registration ends when its plugin unloads. RutisBridge::extensionreturns aRutisExtensionthe host installs withAgent::with_extension(orwith_tree_extension, so plugin policy also covers sub-agents). Each run snapshots the registered handlers at its start.
Every agent event also goes, as an AgentEventEmitted, to decoupled
Rust observers (PluginCtxExt::on_agent_event) — in-process, never on
the rutis bus.
yoagent itself knows nothing about rutis; the bridge uses only yoagent’s public API.
TypeScript, Python and Go handlers (features node, bun, python, go, websocket)
can return images in tool results and write logs into the host’s
tracing output (target yoagent_rutis::plugin). Plugins from other
agent ecosystems — DSH tool plugins, pi extensions — plug in through
adapters shipped in the crate’s plugins/ directory (adapters says
where); see the README
and its adapter contract. With the probe feature, probe loads such a
package through its adapter and reports what an agent gets from it.
§Host
use rutis::host::CtxHost; // `Ctx::root`, `shutdown` and the other host methods
use rutis::Ctx;
use yoagent::{provider::{MockProvider, ModelConfig}, Agent};
use yoagent_rutis::RutisBridge;
let root = Ctx::root()?;
let bridge = RutisBridge::install(&root)?; // on the root, once
let mut agent = Agent::from_provider(MockProvider::text("hi"), ModelConfig::mock())
.with_extension(bridge.extension());
// Load plugins whenever you like; each run sees the ones active at its start.
// root.plugin(MyPlugin);
agent.prompt("hello").await;§Plugin
use std::sync::Arc;
use rutis::{Ctx, Plugin};
use yoagent::ToolDecision;
use yoagent_rutis::{Handler, PluginCtxExt, Registry};
struct NoShell;
impl Plugin for NoShell {
type Deps = Arc<Registry>; // wait for the bridge
async fn apply(&self, ctx: &Ctx, _registry: Arc<Registry>) -> rutis::Result<()> {
ctx.register_handler(Handler::new("no-shell").with_before_tool(|call| {
match call.tool.as_str() {
"bash" => ToolDecision::Deny("shell access is disabled".into()),
_ => ToolDecision::Allow,
}
}))?;
Ok(())
}
}
let _plugin = NoShell;AgentPlugin wraps a handler as a plugin in one expression.
§Plugins in other languages
With the node, bun, python, go or websocket feature (rutis-bridge 0.20),
RutisBridge::install also provides the registry to plugins in other
languages, as the host service yoagent. Such a plugin registers an
object (a Python dict, a Go map of functions) of async functions, with the same hooks and the
same plain-JSON arguments as a Rust Handler:
const yoagent = ctx.use('yoagent')
ctx.effect(yoagent.register('no-shell', {
async before_tool(call) {
if (call.tool === 'bash') return { deny: 'shell access is disabled' }
},
}))The bridge never loads plugins nor starts runtimes: the host does, with
rutis-host’s SpawnPlugin for each runtime (since rutis 0.19 the
language features enable only the yoagent service) and rutis-loader
rows, sharing yoagent in its catalog. See the languages module (built
with those features) and plugins/yoagent.d.ts in the repository.
§Semantics worth knowing
- A run uses the handlers registered when it started. A plugin
unloaded (or restarted / updated) mid-run leaves its handler in that run
but unavailable: its tools fail (“no longer available”, or “plugin
unloaded during the call” for one in flight), its
before_tooldenies, itson_inputrejects, itsafter_toolwithholds the result (without failing a required run), its other hooks are skipped. Never rebound to the new generation. Seeregistry. - Names are unique across plugins: handler names, and the names of
static tools. A clash is refused (
ErrorKind::ServiceExists, logged; no retry when the holder unloads). The agent’s own tools win over plugin tools. - Policies gate every tool call — the agent’s own tools too, not only plugin tools.
- Handlers combine like extensions: in registration order, a
Denywins, aModifyfeeds the next handler, notes are joined. Seeextension. - Fail closed where it guards: a
before_toolthat errors, panics or times out denies the call; anon_inputrejects; anafter_toolwithholds the result. Other hooks are skipped and logged — unless the host made the extensionrequired, when they fail the run. - No policy means allow, including while a policy plugin reloads and
before it first loads, unless the host sets
require_policy. - A host that is not running (the root shut down, disposed or restarted since the bridge was installed) denies every tool call and rejects every prompt.
- Finite default timeouts per handler call (60 s policy hooks, 30 s input, 5 s turn hooks), plus the run’s cancellation through yoagent.
- Install on the root. A bridge installed on a plugin’s context reads as stopped for good once that plugin unloads or reloads.
- Route rutis’s
ErrorSink(default: stderr) into your logging withCtx::root_with_sink.
Re-exports§
pub use bridge::RutisBridge;pub use events::AgentEventEmitted;pub use extension::RutisExtension;pub use extension::DEFAULT_INPUT_TIMEOUT;pub use extension::DEFAULT_POLICY_TIMEOUT;pub use extension::DEFAULT_TURN_TIMEOUT;pub use handler::Handler;pub use handler::Input;pub use handler::RunInfo;pub use handler::Stop;pub use handler::ToolCall;pub use handler::Turn;pub use plugin::AgentPlugin;pub use plugin::PluginCtxExt;pub use registry::HandlerInfo;pub use registry::HookTiming;pub use registry::Registry;pub use registry::ToolOwner;pub use rutis;
Modules§
- adapters
- Where this crate’s adapter files are: the pi and DSH adapters and the
TypeScript declarations of the
yoagenthost service, as published in the crate (plugins/, withoutnode_modules). - bridge
- The host side: install the bridge on a rutis context and hand its extension to agents.
- events
- Agent events for Rust observers:
AgentEventEmitted. - extension
- The bridge as one yoagent
Extension:RutisExtension. - handler
- Handlers: what a plugin registers with the bridge.
- languages
bunorgoornodeorpythonorwebsocket - Plugins in other languages — TypeScript / JavaScript on Node or Bun,
Python and Go — through rutis-bridge 0.20
(the
node,bun,python,goandwebsocketfeatures). - plugin
- The plugin side: contribute to agents from inside
Plugin::apply. - probe
probe - Loads one third-party plugin package through its adapter, as an agent
would, and reports what yoagent gets from it — without calling a tool or
asking a model. The compatibility matrix (
scripts/ecosystem-matrix.mjs, through theecosystem_probeexample) and hosts that vet a plugin before using it (yobuild check) share it. - registry
- The
yoagentregistry: the handlers plugins registered, tied to the plugins’ lifecycles. - rows
loader - Waiting for plugin rows to run, with what keeps a row waiting.
Structs§
- Late
Tools - The tools of restricted handlers that registered while a run was going,
offered from the run’s next turn: a yoagent
ToolSourcepaired with oneRutisExtension— fromlate_tools— installed on the same agent: