Module invocation 

Transport-neutral runtime invocation facade.

This module exposes a Socket.IO-inspired emit / on interaction model over AgentRuntime without binding to any wire protocol. Transport adapters (Socket.IO, gRPC, SSE, …) build on top of these types; the core runtime stays free of transport concerns.

emit / on semantics

emit starts a run — it builds an EmitRequest, converts it to a RunRequest, and hands it to AgentRuntime::run. Returns RunOutput when the run completes.

on subscribes to the runtime’s event bus. Every event from any run managed by the same AgentRuntime is received; the EventKind filter discards non-matching events before the handler fires. Handlers run on independently spawned tasks so a slow handler does not block event delivery for other subscribers.

Event ordering

A typical agent run produces events in this order:

RunStarted
  → ContextBuilt
  → ModelStarted → TextDelta* → ToolCallStarted? → ToolCallDelta* →
    ToolCallCompleted? → ToolExecutionStarted? → ToolExecutionFinished?
  → AssistantMessageCommitted → UsageRecorded
  → (loop: ContextBuilt → …)
  → RunCompleted | RunFailed | RunCancelled

Every event carries a run_id so handlers can correlate events belonging to the same run.

Event delivery guarantees

• At-least-once: events are delivered via a tokio::sync::broadcast channel. Lagging receivers miss events (signaled via tokio::sync::broadcast::error::RecvError::Lagged), which is silently skipped — the receiver misses those events.
• No backpressure: emit does not wait for on handlers to complete. The runtime publishes events to the broadcast channel and proceeds immediately.
• Ordered per-run: events from a single run are always published in order. Events from concurrent runs may interleave.
• Handler concurrency: if Control::set_concurrency_limit is set, a semaphore gates how many handler tasks may run concurrently. Without a limit, every matching event spawns an unbounded task.

Handler lifecycle

on returns an InvocationHandle. The underlying listener task runs until:

• The InvocationHandle is dropped (aborts the task), or
• The broadcast channel is closed (all AgentRuntime senders dropped).

Handler tasks already dispatched before the listener stops run to completion.

Cancellation

Cancellation is cooperative. Control::cancel sets a flag. emit checks the flag before invoking the request closure and before calling AgentRuntime::run; the listener loop inside on checks it before every event dispatch. The underlying runtime does not yet support hard cancellation of an in-flight model call.

Core surface

• EmitRequest builds a run request and hands it to AgentRuntime::run.
• RuntimeInvocation::on subscribes to the runtime event bus and dispatches matching events to user handlers on independent tasks.
• Control carries cooperative cancellation/timeout/concurrency state, plus a type-erased extension map for injecting shared data into handlers.
• InvocationHandle aborts its listener on drop.

Transport-adapter surface

InvocationEvent::Chat and the Chat* variants of EventKind are defined here so adapters reuse the same matching logic, but the core on implementation only surfaces AgentEvents from AgentRuntime::subscribe; chat-stream events require a streaming chat adapter that populates the Chat variant.

Structs

Control

Cooperative lifecycle handle shared across an invocation.

EmitRequest

Transport-neutral request for a single runtime invocation.

FileSessionDataStore

File-system SessionDataStore backed by JSON files.

InvocationHandle

Handle to a background listener task started by RuntimeInvocation::on.

InvocationSession

Invocation-time session context with temporary KV storage.

MemorySessionDataStore

In-memory SessionDataStore backed by a HashMap.

RuntimeInvocation

Transport-neutral invocation facade over AgentRuntime.

Enums

EventKind

Kind of event a caller can subscribe to via RuntimeInvocation::on.

InvocationError

Errors raised by the invocation facade.

InvocationEvent

Unified event envelope wrapping runtime and chat-stream events.

SessionDataError

Errors returned by SessionDataStore implementations.

Traits

SessionDataStore

Pluggable backend for per-session temporary key-value data.