Struct BlockConfig 

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

Fields

script_path: PathBuf

project_root: PathBuf

relay_url: Option<String>

secret_key: Option<String>

Ed25519 secret key (64 hex chars). If None, a random keypair is generated. 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<String>

Prompt string injected as _PROMPT Lua global. None = global not set.

context: Option<String>

Context string injected as _CONTEXT Lua global. None = global not set.

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).

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).