Struct HostContext 

pub struct HostContext {

    pub project_root: PathBuf,
    pub mesh_agent: Option<Arc<MeshAgent>>,
    pub mcp_manager: Arc<RwLock<McpManager>>,
    pub http_client: Client,
    pub sql_conn: SqliteConn,
    pub kv_conn: SqliteConn,
    pub ts_isle: AsyncIsle,
    pub isle: Arc<AsyncIsle>,
    pub handler_isle: Arc<AsyncIsle>,
    pub bus_tx: Sender<Event>,
    pub event_bus: Arc<Mutex<Option<EventBus>>>,
    pub fs_snapshots: SnapshotStore,
    pub knl_logs: Logs,
    pub knl_store: PathBuf,
    pub session_labels: Map<String, Value>,
}

Shared context passed into Lua bridge functions.

Fields

project_root: PathBuf

mesh_agent: Option<Arc<MeshAgent>>

Connected mesh agent (present only when the mesh feature is enabled and a relay URL was supplied).

mcp_manager: Arc<RwLock<McpManager>>

http_client: Client

Shared async HTTP client for http.* bridge.

sql_conn: SqliteConn

The connection behind the sql.* bridge (user tables).

Opened by the host and handed to mlua-batteries-sqlite, which runs every statement inside tokio::task::spawn_blocking and takes the mutex there, not on the VM thread — so no lock guard and no blocking call crosses an .await, and the Lua VM yields while SQLite works.

kv_conn: SqliteConn

The connection behind the kv.* bridge (__kv table only).

A separate database from sql_conn, so KV scratch state and user SQL data do not share WAL, page cache, or backup lifecycle.

ts_isle: AsyncIsle

Handle to the SQLite connection thread behind the ts.* bridge (TSDB — time-series table).

A third database, on a file of its own, so the TSDB’s WAL shares neither page cache nor backup lifecycle with kv/sql. Unlike the two beside it, this connection is not shared but confined: it lives on that thread, and std.ts sends statements to it and awaits them. Different route, same rule — the Lua VM never waits on SQLite.

isle: Arc<AsyncIsle>

Async handle to the main Isle Lua VM that runs the user script via coroutine_eval. After Subtask 2, bridge::bus no longer dispatches handlers against this Isle; handlers live on handler_isle instead. The field is retained because bridge code still keyed to the main Isle (future coroutine_call back-edges, introspection APIs) may need it, and removing it would force another HostContext reshape.

handler_isle: Arc<AsyncIsle>

Dedicated Isle for EventBus handler execution. Lua handlers registered via bus.on / bus.on_any run here so that CPU-bound handler code does not occupy the main Isle’s LocalSet and block grace timers / shutdown wakers on the main VM side.

Used by bridge::bus to forward handler bytecode (Function::dump(true) → handler_isle.exec(...)) and by LuaHandler::call to dispatch via coroutine_call("__bus_dispatch", ...).

bus_tx: Sender<Event>

Ingress sender for the EventBus. Adapters (mesh / webhook / …) clone this and push Events. The mesh adapter captures its own clone at MeshAgent::connect time, so nothing reads the field itself today — kept pub so a further adapter can be wired without reopening this.

event_bus: Arc<Mutex<Option<EventBus>>>

Mutex-wrapped Option<EventBus> so bus.on / bus.on_any can lock briefly from sync Lua context, and bus.serve can Option::take ownership before entering the long-lived run() await (avoiding the await-holding-lock anti-pattern on a std::sync::Mutex).

fs_snapshots: SnapshotStore

Pre-edit file contents captured by std.fs.edit, consumed by std.fs.rollback. One level per path — enough to discard the last edit, which is what a build-and-fix loop needs when it decides an iteration made things worse.

knl_logs: Logs

The event logs every knl session’s stream lives in.

A log is a database — one writer thread, read-only connections beside it — and it is opened once per file per process, so two sessions on one file are two streams of one log. A session holds a handle on the log rather than the log itself, which is what lets the drop backstop work: a handle nobody closed submits its session_closed from Drop, without waiting, and the log is still there to run it because its lifetime is the host’s rather than the session’s.

Cloneable and shared, like the isle handles beside it; the run loop drains it once, in [shutdown], after the Lua VM is gone.

knl_store: PathBuf

The database a knl session opened without a store lands in.

{base_dir}/projects/<slug>/knl.sqlite, resolved by crate::bridge::config::knl_path from the project root above, or whatever AGENT_BLOCK_KNL_PATH names. The host owns it for the same reason it owns the sql / kv / ts files: where a script’s state goes is the host’s answer, not the script’s.

One file per project, so every default session is a stream in it — which is what lets a tree opened from a default parent exist at all (a child is opened on its parent’s database, and the in-memory one locks per table under its shared cache). store = "mem" remains the explicit way to ask for the process-local database instead.

The directory is created at start, beside the other three; the file itself is SQLite’s to create, on the first session that needs it.

session_labels: Map<String, Value>

What this process is, as labels every session it opens is recorded with (BlockConfig::session_labels).

The host’s half of knl.open{ meta = … }: a caller that runs the same block many times over — a job manager, most of all — says which run this process is, and every session opened here carries it. A script’s own labels win on a key they both name, because the script is the one naming what it is recording.

Empty is the ordinary case: a script run by hand is not a run of anything, and its sessions carry no label.

Implementations

impl HostContext

pub fn mesh_agent_id(&self) -> Option<String>

Agent id of the connected mesh agent, if any.

Returns Some(agent_id) when the mesh feature is enabled and a mesh agent is connected. Keeps the #[cfg(feature = "mesh")] gating out of bridge call sites that only need a fallback agent-id string.

Trait Implementations

impl Clone for HostContext

fn clone(&self) -> HostContext

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.