Skip to main content

Crate yoagent_rutis

Crate yoagent_rutis 

Source
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:

  1. RutisBridge::install provides the yoagent Registry service on the rutis root.
  2. 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.
  3. RutisBridge::extension returns a RutisExtension the host installs with Agent::with_extension (or with_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_tool denies, its on_input rejects, its after_tool withholds the result (without failing a required run), its other hooks are skipped. Never rebound to the new generation. See registry.
  • 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 Deny wins, a Modify feeds the next handler, notes are joined. See extension.
  • Fail closed where it guards: a before_tool that errors, panics or times out denies the call; an on_input rejects; an after_tool withholds the result. Other hooks are skipped and logged — unless the host made the extension required, 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 with Ctx::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 yoagent host service, as published in the crate (plugins/, without node_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.
languagesbun or go or node or python or websocket
Plugins in other languages — TypeScript / JavaScript on Node or Bun, Python and Go — through rutis-bridge 0.20 (the node, bun, python, go and websocket features).
plugin
The plugin side: contribute to agents from inside Plugin::apply.
probeprobe
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 the ecosystem_probe example) and hosts that vet a plugin before using it (yobuild check) share it.
registry
The yoagent registry: the handlers plugins registered, tied to the plugins’ lifecycles.
rowsloader
Waiting for plugin rows to run, with what keeps a row waiting.

Structs§

LateTools
The tools of restricted handlers that registered while a run was going, offered from the run’s next turn: a yoagent ToolSource paired with one RutisExtension — from late_tools — installed on the same agent: