Runtime

The runtime is the central coordinator that manages agents and their tool schemas.

What the runtime does

Runtime<M, H> is generic over a model type M and a hook type H. It provides:

• Agent registry — stores named agents as immutable values in a BTreeMap
• Session store — manages conversation sessions, each behind Arc<Mutex<Session>>
• Tool schema store — holds tool definitions registered by hooks
• Execution dispatch — routes events to the correct agent and spawns async tasks

Creating a runtime

The runtime is built from a config and a hook:

let runtime = Runtime::new(model, hook).await?;

During construction, the hook's on_register_tools() is called to populate the tool schema store.

Sessions

Sessions are lightweight conversation containers. Each session holds a message history and is tied to one agent:

• create_session(agent, created_by) — creates a new session, returns its u64 ID
• close_session(id) — drops the session and frees its history
• send_to(session_id, content) / stream_to(session_id, content) — run the agent against a session's history

Sessions are stored behind Arc<Mutex<Session>>, so concurrent access to the same session is serialized. See sessions for CLI management.

Agent isolation

Agents are stored as plain immutable values — no Mutex wrapping. When add_agent(config) is called, the hook's on_build_agent enriches the config (injecting scope and system prompt extensions), then the agent is built with a filtered tool snapshot.

Concurrency is managed at the session level. Multiple sessions (potentially using the same agent) can run in parallel, each locked independently.

Tool dispatch

Tools are registered as schemas only (no handlers). When an agent requests a tool call, the runtime sends a ToolRequest through a channel. The hook handles the actual dispatch.

This separation means the runtime doesn't need to know how tools work — it just passes requests through.

Relation to the daemon

In a typical setup, you don't create a runtime directly. The daemon wraps the runtime and connects it to transports (socket, Telegram, Discord).

See agents for how individual agents execute, and hooks for how tools are registered.