Modules

Runtime modules, environments and adapters

MCI uses modules to execute code and communicate with end services.

Module Types

MCI coordinates two module types:

1. Environment modules

   • Execute process code in an isolated runtime.
   • Expose generated bindings for available services and tools.
   • Stream stdout, stderr, and structured output updates.

2. Adapter modules

   • Receive invocation requests from environments.
   • Translate those requests to target protocols and service contracts.
   • Return normalized results back to the environment.

Adapter modules are what make MCI protocol-agnostic at the end-service level. MCI itself exposes an HTTP REST API, while adapters can connect to end services over different protocols and standards.

Adapter responsibilities (implementation details)

• Parse and register service definitions (see AdapterModule.register).
• Maintain per-service configuration and secret snapshots via setServiceConfig / setServiceSecret.
• Translate environment invoke calls into HTTP requests (or other protocols) and normalize responses (invoke).
• Emit errors with structured payloads that the server inspects and surfaces to callers.

Adapter modules are typically implemented as small shim layers that translate between a service manifest and the runtime protocol used by the target service. In this repository AdapterModule implements JSON manifest parsing, endpoint resolution, and POST-style invocation semantics.

Pooling

Modules are managed by pools to avoid repeated cold starts and reduce execution overhead.

• Environment pool: allocates and releases staged environment modules.
• Adapter pool: allocates and releases adapter modules with current service configuration and secrets.

At runtime, modules are leased to executions and released back to their pool after use.

Pools in the implementation do not create many independent instances by default. Instead they maintain a staged active module and use lease counting to manage concurrent access. When a staged module is replaced, the previous module is retired and cleaned up once its leases drop to zero.

Hydration

Hydration loads runtime data into modules so they can execute correctly.

Environment hydration

• Loads staged service and tool definitions.
• Generates service/tool bindings that process code can call.

Environment hydration applies staged service manifests into the environment runtime so code executed inside the environment can call tools via generated bindings.

Environment modules expose generated bindings using setServiceManifestBindings and updateServiceManifestBindings. These bindings are visible to transpiled code running in the environment and map tool invocations to runtime-built invoke calls.

Environment modules also provide runtime events and outputs that the host listens to:

• stdout: emitted when the environment worker writes to stdout
• stderr: emitted when the environment worker writes to stderr
• output: emitted when the environment sends structured output patches (key/value)

The environment execution is driven by a worker-thread process. The environment’s execute(code, options) method runs transpiled code in the worker, wires up stream handling, enforces timeouts, and returns an execution status (success or failed). The environment provides kill() to forcibly terminate a running worker.

Adapter hydration

• Loads service configuration snapshots.
• Loads service secret snapshots.
• Applies updated configuration and secrets during restage.

Adapter pool staging loads a snapshot of configurations and secrets from the database and applies them to a new AdapterModule instance via setServiceConfigs and setServiceSecrets.

Module Lifecycle

1. Instantiate module
2. Hydrate module with current definitions and runtime data
3. Stage module in pool as ready
4. Allocate module for execution
5. Release module back to pool
6. Recycle/Retire module when unhealthy or outdated

Lifecycle notes (implementation)

• Staging is guarded by a stagingPromise to avoid concurrent staging attempts.
• When a new staged module replaces the active one, the previous module is retired and either killed immediately if it has no leases or left to be killed after active leases finish.
• If staging fails, the pool records the failure state and keeps the previously staged module (if any) available.

Failure Handling

If a module execution fails, times out, or health checks fail, the module is recycled or retired and replaced by a newly staged module.

Module health checks and recycling are implemented in the process execution path. When an execution finishes or errors, the runtime inspects module health (e.g., isHealthy / isValid hooks) and either returns the module to the pool or recycles/destroys it.

Environment health and recycling

After process execution, the runtime evaluates the environment module’s health. Implementations may provide isHealthy or isValid hooks and a status field. If an environment is unhealthy or reported timeout/failed, the pool will recycle or destroy that module and stage a replacement to keep the pool ready.