MAXIM
Reaching the Outside World and Handling Interrupts
An agent that can only talk to itself isn't very useful. Maxim's agentic upgrade adds three critical capabilities: external communication channels, interrupt handling for when humans need to override decisions, and mode-based containment that scales access with trust.
The gateway is a pure transport layer. It delivers messages when the agent tells it to and receives inbound messages into the bus. It has no opinion about when to notify or what to notify about — that's the agent's job.
Channels are pluggable transport adapters. Each channel handles a specific communication medium:
SMS + Voice via REST API. Outbound messages are immediate API calls. Inbound messages arrive via webhook.
The channel interface is intentionally minimal. Adding new channels requires implementing just send() and optionally call().
External messages are untrusted input. The gateway enforces strict separation between external data and internal control fields:
Two tools give the agent control over outbound communication:
| Tool | Parameters | Effect |
|---|---|---|
| send_message | channel, recipient, body | Calls gateway.send() → delivers via channel adapter |
| call_user | recipient, message | Calls gateway.call() → initiates voice call with TTS |
Both tools are registered in the tool registry during bootstrap and are subject to mode-based access gating. The agent decides when and what to communicate based on its reasoning — the gateway just delivers.
Biological agents can be interrupted. When something more urgent appears (a loud noise, a sudden threat), the current action is suspended and attention shifts. The prefrontal cortex mediates this via inhibitory control — the ability to stop an ongoing behavior. Maxim's preemption circuit provides the same capability: external signals (voice commands, inbound messages, hard stops) can interrupt the current goal.
The PreemptionCircuit evaluates incoming Percepts for urgency and can pause, redirect, or abort the current goal. It operates on a priority system:
Unconditional halt. Triggered by voice commands ("Maxim stop"), inbound messages matching the hard-stop whitelist, or safety circuit triggers. Cancels current goal, freezes motor output.
Suspend current goal and switch to a higher-priority one. Triggered by urgent user input or significant environmental changes. Current goal is preserved for potential resumption.
Pause goal execution for a duration. The agentic loop continues cycling but skips goal proposals while the hold is active. Used during mode transitions or when waiting for external input.
The preemption check happens early in each agent loop cycle, before goal proposals:
When the preemption circuit interrupts an action mid-execution, the system needs to know what was happening so it can either reverse it or resume it later. The ExecutionTracker captures pre-execution snapshots:
Execution tracking is wired into the agent loop's LLM action execution path (Section 4). Before each tool call, a snapshot is captured. If the preemption circuit fires mid-execution, the snapshot provides the context needed for graceful handling.
Trust scales with experience. A new agent shouldn't have filesystem root access. Maxim's tool registry enforces mode-based containment that limits capabilities based on the current operational mode:
| Mode | Filesystem Access | Directory Change | Tool Gating |
|---|---|---|---|
| passive | Restricted to .maxim_sandbox/ within CWD | Blocked | Read-only + network |
| active | Read/write within CWD | Can request | Full sandbox, execution requires approval |
| singularity | Full filesystem access | Unrestricted | All tools, constitution still applies |
Every filesystem tool (ReadFileTool, WriteFileTool, ExecuteFileTool, GlobTool, BashTool) receives an allowed_dirs parameter at construction time, enforced on every call. The sandbox is created automatically in passive/active modes.
Communication isn't just delivered — it's remembered. The ConversationManager tracks per-channel, per-participant exchanges and, when a conversation expires, archives it into Maxim's memory systems so the agent can learn from how it talks to people:
Each archived conversation publishes a summary Percept onto the agent bus (captured by the Hippocampus as an episodic memory) and, once it has at least three messages, records a conversation-level event in the NAc. Over time the NAc accumulates which channels and patterns matter.
Patterns that repeat enough are promoted to the SemanticPromoter during session-end consolidation, becoming ATL concepts ("user prefers brief updates" or "morning messages get faster responses").
Note: a dedicated CommunicationBridge abstraction described in earlier drafts is not part of the 1.0 surface — conversation learning flows through the ConversationManager archival path above.