Architecture and boundaries

AXLR is the execution entry point of the product stack and separates the execution core from its hosts. It grew from simplifying underpass-runtime's execution layer, with Pi as a conceptual reference for a compact tool surface. AXLR owns the agent loop, local tools, session state and execution approvals. KMP owns durable, evidence-backed agent memory. MADE owns workflow state, orchestration and human decision records. The engines are separate MCP servers; an installed catalogue entry is not an active connection. The root module has no terminal dependency. The tui/ module contains shared agent/session use cases plus the console and HTTP service adapters. The JSON worker is another host adapter with a one-request lifecycle; a library host supplies its own loop.

flowchart TB
    subgraph Hosts
      T[axlr-tui]
      H[axlr-serve · mTLS API]
      W[JSON worker]
      G[Go application]
    end
    T --> A[Application use cases]
    H --> A
    W --> A
    G --> A
    A --> D[Domain commands and values]
    A --> L[Local file and process adapters]
    A --> P[Plugin tool port]
    P --> M[MCP manager and client]
    T --> O[OpenRouter or local model adapter]
    G --> O
    T --> S[Private session and config storage]
    H --> J[Sessions · events · idempotency · audit]
    M --> K[KMP memory engine]
    M --> C[MADE orchestration engine]

Package	Responsibility
domain/	Validated values, local commands and results, model messages and tool calls
application/	Ports and use cases; no terminal rendering
adapters/local/	Workspace file operations and local process execution
dto/	Strict JSON worker request and response contract
runtime/	Executor composition, codecs, request and response mapping, bounds
plugins/	Explicit MCP manifest and allowed-tool enforcement
mcpclient/	Named MCP stdio and Streamable HTTP sessions
adapters/openrouter/	Model request and response mapping, completion and SSE streaming, for OpenRouter or any configured OpenAI-compatible endpoint
cmd/axlr/	One-request JSON process adapter
tui/domain/, tui/application/	Session/mode policy, bounded model context, turn loop, host controls and workflow driver
tui/adapters/terminal/, tui/cmd/axlr-tui/	Console UI and composition, models, approvals, package browsing and engine preparation
tui/adapters/ceremonyhost/, tui/adapters/madesetup/	Pinned MADE procedures, actual check execution, KMP outcome calls and operator preparation
tui/application/ plans	ceremony_plan.go (decompose verification, approval), ceremony_task.go (start, red, green, hand-back), ceremony_sync.go (integrate, reconcile), plans.go (the background runner)
tui/adapters/typesafe/	TypeSafe Jev judgement client behind JudgementPort, used by axlr_judge and the final check
tui/adapters/localmodels/	Routing of configured local models to their servers, the merged /model catalog and each model's context window
tui/adapters/storage/, tui/adapters/diagnostics/	Private sessions, settings, MCP config and diagnostics
tui/service/, tui/cmd/axlr-serve/	HTTP/mTLS adapter, principal roles, event journals, direct calls, idempotency and remote engines

Authority🔗

The worker's trusted-local profile and the console run with the host account's permissions. os.Root anchors file operations inside the selected workspace. The exec program, its arguments and connected MCP servers can act with broader account authority; the console therefore shows local tool calls for review and persists explicit per-server MCP approval policies. The JSON worker and root library have no interactive approval layer; their host must enforce one if needed. Console work modes additionally restrict local operations. Saved approvals/full autonomy do not override a restricted mode or the first approval of a workflow check command. External MCP calls retain their own policy and engine authorization.

No tool is registered through directory scanning. A forged tool is registered only by axlr_forge_tool, which writes its files under the workspace's .axlr/tools/<name>/ and records their digests in the console's private state (<state>/axlr/forged-tools/), so files that arrive with a checkout are not tools; axlr_run_tool refuses a tool whose files changed since it was forged and runs it through local_exec, under that tool's approval and confinement; axlr_remove_tool deletes a registered tool's directory and its registration, and nothing it has not registered. A manifest must name the MCP transport and its allowed tools. AXLR's package catalogue reads the Codex plugin format into AXLR's own storage and can register declared MCP servers. Skills and MCP declarations are the supported compatibility surface; other package files are retained but not activated. /mcp remains the source of truth for active connections. Model output does not grant a capability; the host's registry and policy decide what can run.

Composition boundaries🔗

The console wires package/skill discovery, six work modes, engine setup/update and the MADE workflow driver. The driver invokes registered made and optional kmp tools directly through the execution port for its bookkeeping; those calls are not individual model approval dialogs. The user selects the driven procedure and approves its check command. Engine-side grants remain essential.

The session lifecycle runs the memory's and the orchestrator's protocols for every session (its context, agent, instance and turns) without naming either engine in tui/application or tui/domain: the application knows two roles, memory and orchestrator, through its ports (MemoryIdentity, MemoryAgentsPort, MemoryPort, JournalPort, RecallPort, CeremonyEnginePort, OrchestratorPreparationPort). What the console owns of each plugin tool (hidden from the model with a refusal, the argument that carries the session's memory context, the memory write) is a domain.ToolSurface the engine adapter decides when the catalog registers the tool (ceremonyhost.Surface), frozen in the session's snapshot; the engines' paragraphs of the model's orientation come from EngineGuidancePort (ceremonyhost.Guidance). Another memory or orchestrator is an adapter that implements those ports and that table. See the decoupling design; the workflow driver that predates the lifecycle still names made and kmp and is the listed follow-up.

Self-repair adds a coordinator in tui/application (SelfRepair) that validates the agent's request against the session transcript, keeps the repair registry and drives a second session in the background; an agent-requested improvement goes through the same coordinator and registry, in a session in /improve. That session gets its own AXLR runtime rooted in the clone (a second runtime.Executor, tool runner, forge and workflow driver, composed in tui/cmd/axlr-tui), while the model client, the session store and the MCP manager are shared. The console never changes its own executable; a merged repair is reported to the origin session with the build it still runs.

The HTTP binary reuses turn use cases but wires only the configured remote KMP/MADE adapters, manual tool policy and the model client. It does not wire package skills, mode selection or CeremonyDriver. HTTP session creation accepts a model, not a mode or plugin configuration. Readiness performs model-configuration and engine-discovery checks, not a paid model turn or authorization test for every engine operation.

The driver checks exact 2.0 definition digests before start. Its optional KMP integration uses ws:<session-id> and best-effort recall/outcome recording. Stable project recall and graph relations are explicit agent work. Workflows separates this driver from the embedded 1.0 skill catalogue.

State and failure🔗

The JSON worker closes after one response. A long-lived Go host can reuse an executor and MCP manager. The TUI stores private sessions and preferences locally, with one writer lock per open session. It restores interrupted work without executing pending calls until the person explicitly continues. Mode and workflow data are stored in session sidecars; the model receives a bounded projection while the full transcript remains available. The HTTP service persists sessions, journals, direct calls, idempotency and audit under a dedicated state directory and requires one replica.

AXLR distinguishes validation rejection, operation failure, cancellation and timeout. A timed out or disconnected effectful call may already have acted. Neither the worker nor MCP client treats a missing response as proof of no effect. The service can mark interrupted direct effects uncertain; the operator reconciles against the external target. Recovery covers these boundaries.

Provenance and design record🔗

AXLR is a focused rewrite of an execution layer in the earlier Underpass runtime. Pi influenced the choice of a compact tool surface; AXLR does not use Pi code or runtime. Dated plans, specs and diagnostics explain how the current shape was reached. Use the current guides for operational behavior.