Struct BlockConfig 

pub struct BlockConfig {
    pub script: ScriptSource,
    pub project_root: PathBuf,
    pub relay_url: Option<String>,
    pub secret_key: Option<SecretKeySource>,
    pub mcp_rpc_timeout: Duration,
    pub prompt: Option<PromptSource>,
    pub context: Option<PromptSource>,
    pub host_handlers: HashMap<String, Arc<dyn Handler>>,
    pub host_handler: Option<Arc<dyn Handler>>,
    pub auto_serve_bus: bool,
    pub shutdown_token: Option<CancellationToken>,
}

Fields

script: ScriptSource

Lua script to execute. See ScriptSource for the supported shapes (filesystem path / inline source / embedded default agent invoker).

project_root: PathBuf

relay_url: Option<String>

secret_key: Option<SecretKeySource>

Ed25519 secret key for mesh identity. See SecretKeySource for the supported shapes (inline 64-hex / environment variable). None generates a random keypair. Required to talk to registry/ACL-gated hosted meshes.

mcp_rpc_timeout: Duration

Per-RPC timeout for every MCP round-trip (connect / list / call). Defaults to agent_block_mcp::DEFAULT_RPC_TIMEOUT.

prompt: Option<PromptSource>

Prompt payload injected as _PROMPT Lua global. See PromptSource for the supported shapes. None leaves the global unset.

context: Option<PromptSource>

Context payload injected as _CONTEXT Lua global (typically the system prompt). Same shape rules as Self::prompt.

host_handlers: HashMap<String, Arc<dyn Handler>>

Host-side Rust handlers pre-installed on the EventBus before the user script starts. Each entry registers handler against kind via EventBus::on, so a script-side bus.emit(kind, payload) is captured by the Rust handler rather than dispatched to a Lua function.

Intended for SDK consumers that embed agent-block-core and need to receive script output programmatically (e.g. a Spawner adapter that turns LLM script output into a typed WorkerResult). Lua-side bus.on(kind, fn) registrations layered on top of the handler Isle are still possible, but the EventBus dispatches a single handler per kind (last-write-wins), so host-side and Lua-side registrations on the same kind collide; choose one side per routing key.

Defaults to an empty map (no host handlers).

host_handler: Option<Arc<dyn Handler>>

Single host-side Rust handler that catches every event regardless of kind. Internally registered via EventBus::on_any, so it acts as a fallback when no entry in Self::host_handlers matches the incoming kind.

This is the SDK-embed 1-shot sink: SDK consumers do not need to invent or coordinate a string kind between the Lua script and their Rust code. The agent invoker’s emit-kind is irrelevant — the handler receives every event.

Use this when you want a single Rust handler to receive results (typical embedded use). Use Self::host_handlers instead when you actually need string-keyed routing (multi-source / multi- handler dispatch). The two may coexist: kind-specific handlers in host_handlers take precedence, and this single handler is the fallback for unmatched kinds.

Defaults to None.

auto_serve_bus: bool

When true, the EventBus dispatcher loop is driven in the background for the duration of the script and shut down gracefully after the script completes. Required for SDK-embed callers that supply Self::host_handlers and need bus.emit(kind, payload) events emitted from the script to actually reach those handlers without requiring the script to call bus.serve() (which blocks on SIGTERM / Ctrl+C and never returns under programmatic embedding).

After the script finishes, the dispatcher is given a grace window (AGENT_BLOCK_TASK_GRACE_MS, default 1000ms) to drain queued events and finish any in-flight handler, then is cancelled.

Mutually exclusive with Lua-side bus.serve(): enabling this flag takes ownership of the EventBus before the script runs, so a script that calls bus.on(...) followed by bus.serve() will error (“bus.serve() has already taken ownership”). Use this flag when the script’s sole purpose is to push events to host handlers.

Defaults to false (legacy behavior: dispatcher only runs when the script calls bus.serve()).

shutdown_token: Option<CancellationToken>

Optional caller-supplied cancellation token. When cancelled, the in-flight script is interrupted via the Isle’s debug-hook cancel path, the auto-serve dispatcher (if any) is shut down, and run() returns Err(BlockError::Cancelled).

Intended for SDK consumers that spawn run() as a tokio task and need an out-of-band abort signal (timeouts, parent-task cancellation propagation, user-driven stop). The token is observed across the coroutine_eval await; once cancellation propagates, the shutdown sequence (MCP disconnect, Isle drivers, auto-serve dispatcher) still runs so file descriptors and remote handles are released.

Defaults to None (legacy behavior: run() only completes when the script returns naturally).