Skip to content

Contracts

Contracts define stable runtime boundaries in mas-runtime. A contract describes what the kernel may call (tools, models, sessions, messaging, governance); a plugin implements one or more contracts.

Machine-readable registry: contracts-registry.yaml.

Implemented in this release (OSS)

These boundaries are wired in the kernel and exercised by tutorials and paper labs:

Contract / plugin Role
ToolContract Tool listing and invocation
MemoryContract Memory read/write at engine boundary
ContextContract / ContextManagerContract Prompt and conversation context
DesignPatternPlugin ReAct, chain-of-thought, single-pass lifecycles
EngineContract LLM, tool, and memory I/O
CtxAssembler Context / prompt assembly
ObservabilitySink / EventEmitter Trace and JSONL event emission
BudgetTracker + budget overlays Stateful token/cost governance (lifecycle-control.lab)

The plugin registry lists ingress/egress events and Python modules for each registered contract.

Taxonomy (design target)

The runtime design groups boundaries into three families. Additional contracts below are specified for extension authors; not all have standalone Python protocol classes in OSS yet.

Family Meaning Examples
Capability What the runtime can access or expose ToolContract, model access, SessionContract
Orchestration How control flows across agents WorkflowContract, delegation, transport
Governance What is permitted Budget, routing (sandbox/TBAC: internal-only)

For method signatures and implementation detail on implemented contracts, see developer contract reference in the repository (clone required).

Contract groups (developer reference)

Group Topics
Models, prompts, tools, memory Tool and model access, prompt assembly, memory backends
Sessions, checkpoints, context Session load/save, shared context, prompt context
Messaging & orchestration Sensors, transport, delegation, workflow
Control & observability Execution control, recorder / trace emission
Governance Budget, routing (sandbox/TBAC documented in mas-lab-internal)
Design patterns ReAct, chain-of-thought, single-pass lifecycles

Deep dives (GitHub): model & tools · state & context · messaging & orchestration · execution control · governance · design patterns

Governance (OSS)

Stateful governance plugins enforce policy across turns. The paper lifecycle-control lab stacks budget caps, guardrails, and HITL via overlays (e.g. budget-cap on budget_threshold).

Runtime implementation: BudgetTracker in runtime/src/mas/runtime/boundary/gov/budget.py. Design-target contract: BudgetContract (see dev governance.md).

Plugin registry (v2)

The registry maps contract IDs to Python modules and (where applicable) Mealy / TLA machines. Registered contracts in this release:

ID Role
DesignPatternPlugin Reasoning pattern scheduler (ReAct, CoT, single-pass)
EngineContract LLM, tool, and memory I/O
CtxAssembler Prompt / context assembly
HitlResponder Human-in-the-loop approval
ObservabilitySink Trace and event emission
EnvelopeProduct Contract-call envelope (governance + observability wrap)
EventEmitter JSONL / stderr event sinks (mas-ctl)
EventTransform Boundary → native / OTEL transforms

See contracts-registry.yaml for aliases, ingress/egress events, and bundled implementations.

Typical call paths

Tool execution

Runtime or planner
  -> ToolContract.list_tools()
  -> BudgetContract.on_pre_tool_call()
  -> ToolContract.call_tool()
  -> RecorderContract.emit()

Model execution

Runtime
  -> ModelAccessContract.on_collect_models()
  -> BudgetContract.on_pre_llm_call()
  -> ModelAccessContract.complete()
  -> BudgetContract.on_post_llm_call()
  -> RecorderContract.emit()

MAS orchestration

SensorContract.pull() or emit_event()
  -> SessionContract.load_session()
  -> WorkflowContract.run()
  -> DelegationContract.list_tools() and collect_context()
  -> MessageContract.send_message() or TransportContract.send()