Modules

This page documents MobKit v0.8.34 (mirrored from v0.8.34). Modules are application-supplied subprocess capability boundaries. MobKit starts the configured modules, records startup health transitions, and routes module calls over either MCP or the generic JSON-line boundary. Durable scheduling and gating are runtime services, not modules.

Module configuration

ModuleConfig contains exactly four fields:

ModuleConfig {
    id: "router".to_string(),
    command: "/opt/my-app/bin/router-module".to_string(),
    args: vec![],
    restart_policy: RestartPolicy::OnFailure,
}

Field	Type	Description
`id`	`String`	Module identifier
`command`	`String`	Executable to spawn
`args`	`Vec<String>`	Arguments passed to the executable
`restart_policy`	`RestartPolicy`	`never`, `on_failure`, or `always`

Restart budgets and backoff are runtime options. OnFailure retries a failed generic subprocess start within its budget. Always can also restart a successful generic subprocess start within its budget. MCP module startup is a one-shot tool probe and does not use those restart loops.

Discovery

DiscoverySpec names a namespace and the configured module IDs the runtime should start:

DiscoverySpec {
    namespace: "production".to_string(),
    modules: vec![
        "router".to_string(),
        "delivery".to_string(),
        "memory".to_string(),
    ],
}

At bootstrap, every ID in discovery.modules must have a matching ModuleConfig. A missing configuration is a startup error. A configured module that reaches a terminal start error instead contributes a supervisor.warning event and bootstrap continues to the next module.

Pre-spawn environment

PreSpawnData associates environment entries with one module:

PreSpawnData {
    module_id: "router".to_string(),
    env: vec![
        ("MOBKIT_MODULE_BOUNDARY".to_string(), "mcp".to_string()),
    ],
}

Set MOBKIT_MODULE_BOUNDARY=mcp to select the MCP boundary. Other environment entries can carry module-specific configuration or secret references.

Core modules

Three module IDs have hard MCP requirements:

Module ID	Runtime use	Required MCP tool
`router`	Resolve a recipient into a trusted route	`routing.resolve`
`delivery`	Dispatch a validated delivery request	`delivery.send`
`memory`	Read conflict state for runtime gating	`memory.conflict_read`

For these IDs, a call fails closed if MOBKIT_MODULE_BOUNDARY=mcp is absent or the required tool is unavailable. The following related runtime surfaces are not module tools:

Runtime-route list, add, and delete
Delivery history and idempotency
All gating evaluate, pending, decide, and audit operations
The operational assertion and conflict ledger: mobkit/memory/stores, mobkit/memory/index, and mobkit/memory/query
The separate identity agent-memory API: mobkit/agent_memory/recall when a provider is configured, plus mobkit/agent_memory/remember, mobkit/agent_memory/forget, mobkit/agent_memory/update, and mobkit/agent_memory/manifest when the provider supports each capability
Agent-memory record-engine surfaces for quarantine review and steward consolidation

The operational ledger and the identity agent-memory record layer are distinct authorities. The ledger owns assertion and conflict index/query state consumed by gating. Quarantine review and steward consolidation belong to the agent-memory record-engine layer. Non-core module IDs may use the MCP marker or the generic JSON-line subprocess boundary. Scheduling is owned by Meerkat’s ScheduleService. See Scheduling.

Startup health

ModuleHealthState has five values:

State	Meaning during startup supervision
`Starting`	Startup or MCP probing began
`Healthy`	The generic boundary yielded its first valid event, or the MCP tool probe succeeded
`Failed`	A startup attempt or MCP probe failed
`Restarting`	A generic subprocess retry is about to run
`Stopped`	Startup ended without a live module

Each ModuleHealthTransition records module_id, optional from state, to state, and attempt number. Transitions are retained in SupervisorReport; they are not emitted as health_transition unified events. A successful MCP probe emits event_type: "mcp.ready" with the discovered tool names. A terminal startup error emits event_type: "supervisor.warning" with the error payload. The ModulesStarted lifecycle stage means startup attempts have completed, not that every module is healthy.

Trusted module manifest

load_trusted_mobkit_modules_from_toml accepts a [[modules]] manifest:

[[modules]]
id = "router"
command = "/opt/my-app/bin/router-module"
args = []
restart_policy = "on_failure"

[[modules]]
id = "delivery"
command = "/opt/my-app/bin/delivery-module"

The trusted-manifest loader validates non-empty IDs and commands, defaults missing args to an empty list, and defaults a missing restart_policy to on_failure. The executable names and their implementations belong to the host application.

Getting started

Core concepts

Guides

Module configuration

Discovery

Pre-spawn environment

Core modules

Startup health

Trusted module manifest

See also

​Module configuration

​Discovery

​Pre-spawn environment

​Core modules

​Startup health

​Trusted module manifest

​See also

Module configuration

Discovery

Pre-spawn environment

Core modules

Startup health

Trusted module manifest

See also