hyperpolymath
diff --git a/‎cartridges/agent-mcp/AGENT-MCP-REPORT.adoc‎
Lines changed: 277 additions & 0 deletions b/‎cartridges/agent-mcp/AGENT-MCP-REPORT.adoc‎
Lines changed: 277 additions & 0 deletions
@@ -0,0 +1,277 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+= Agent-MCP Cartridge — Technical Report
+Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+:toc: left
+:toclevels: 3
+:icons: font
+:source-highlighter: rouge
+
+== Executive Summary
+
+Agent-MCP is a formally verified agentic orchestration cartridge for the BoJ (Bundle of Joy) server. It enforces Boyd's OODA loop (Observe → Orient → Decide → Act) as a dependent-type state machine, making it *impossible* for an AI agent to act without first observing, orienting, and deciding. This prevents the "shoot first, think later" anti-pattern that plagues autonomous AI systems.
+
+The cartridge is accessible via *9 protocol transports*: REST, gRPC, GraphQL, WebSocket, JSON-RPC 2.0, MQTT, tRPC, SOAP, and Cap'n Proto — supporting everything from web dashboards to multi-agent swarms.
+
+== Architecture
+
+=== The ABI-FFI-Adapter Triple
+
+[source]
+----
+   Idris2 ABI (SafeOODA.idr, Protocol.idr)
+        │  ValidOODA proof: impossible to skip stages
+        │  Dependent types enforce state machine correctness
+        ▼
+   Zig FFI (agent_ffi.zig)
+        │  32 concurrent sessions, mutex-protected
+        │  30+ tests, C-ABI exports
+        ▼
+   V-lang Adapters (9 protocol servers)
+        │  REST, gRPC, GraphQL, WebSocket, JSON-RPC,
+        │  MQTT, tRPC, SOAP, Cap'n Proto
+        ▼
+   AI Agents (Claude, Gemini, custom agents, bot fleets)
+----
+
+=== Why This Architecture Matters
+
+* The *Idris2 layer* makes invalid state transitions a compile-time error. There is no `ValidOODA Observe Act` constructor — the type system physically prevents it.
+* The *Zig layer* manages 32 concurrent agent sessions with mutex-protected state, ensuring thread safety under load.
+* The *V-lang layer* exposes session management through every protocol pattern, from request/response to pub/sub to binary RPC.
+
+== Core Logic
+
+=== The OODA State Machine
+
+Every AI agent session follows a strict cycle:
+
+[source]
+----
+    ┌──────────┐
+    │ OBSERVE  │ ◄─── Gather data, read context
+    └────┬─────┘
+         │ (only valid transition)
+    ┌────▼─────┐
+    │  ORIENT  │ ◄─── Analyse, interpret, contextualise
+    └────┬─────┘
+         │ (only valid transition)
+    ┌────▼─────┐
+    │  DECIDE  │ ◄─── Choose action, plan execution
+    └────┬─────┘
+         │ (only valid transition)
+    ┌────▼─────┐
+    │   ACT    │ ◄─── Execute the decision
+    └────┬─────┘
+         │ (loops back)
+         └──────────► OBSERVE (new loop, loopCount++)
+
+    Any state ──► HALTED (emergency stop)
+    HALTED ──► OBSERVE (resume)
+----
+
+=== Valid Transitions (Idris2 Proof)
+
+[cols="1,1,1", options="header"]
+|===
+| From | To | Allowed?
+
+| Observe | Orient | *Yes* — must analyse before deciding
+| Observe | Decide | *No* — cannot skip analysis
+| Observe | Act | *No* — cannot skip analysis AND decision
+| Orient | Decide | *Yes* — must decide before acting
+| Orient | Act | *No* — cannot skip decision
+| Decide | Act | *Yes* — execute the decision
+| Act | Observe | *Yes* — new loop begins
+| Any | Halted | *Yes* — emergency stop always available
+| Halted | Observe | *Yes* — resume with fresh observation
+|===
+
+The `ValidOODA` dependent type in Idris2 has exactly 9 constructors — one for each valid transition. Any other transition is a *type error at compile time*.
+
+=== Tool Call Safety
+
+Not all agent actions are equal. Agent-MCP classifies tool calls by risk:
+
+[cols="1,1,1", options="header"]
+|===
+| Tool Call Type | Has Side Effects? | Requires Safety Check?
+
+| Execute | Yes | *Yes*
+| Query | No | No
+| Transform | No | No
+| Communicate | Yes | No
+| Delegate | Yes | *Yes*
+| Escalate | Yes | *Yes*
+|===
+
+=== Safety Gate
+
+Before execution, a safety check determines whether to proceed:
+
+[cols="1,1,1", options="header"]
+|===
+| Safety Outcome | Allows Execution? | Needs Human?
+
+| Approved | *Yes* | No
+| Denied | No | No
+| Escalated | No | *Yes*
+| Timeout | No | No
+| Sandboxed | *Yes* (isolated) | No
+| Human Required | No | *Yes*
+|===
+
+=== Multi-Agent Coordination
+
+[cols="1,1", options="header"]
+|===
+| Strategy | Description
+
+| Solo | Single agent, no coordination
+| Collaborative | Agents share information and goals
+| Competitive | Agents compete for best solution
+| Hierarchical | Manager agent delegates to workers
+| Swarm | Emergent behaviour from simple rules
+| Consensus | Agents vote before acting
+|===
+
+=== Agent Memory Types
+
+[cols="1,1,1", options="header"]
+|===
+| Memory Type | Persistent? | Scope
+
+| Working | No | Current session only
+| Episodic | Yes | Event history
+| Semantic | Yes | Knowledge base
+| Procedural | Yes | Skills and procedures
+| Shared | Yes | Across all agents
+|===
+
+== Protocol Transports
+
+=== 9 Protocols Available
+
+[cols="1,1,2", options="header"]
+|===
+| Protocol | Adapter File | Best For
+
+| *REST* | `agent_adapter.v` | Standard web APIs, Claude MCP bridge
+| *gRPC* | `agent_grpc.v` | Microservice agent orchestration
+| *GraphQL* | `agent_graphql.v` | Agent dashboards, flexible session queries
+| *WebSocket* | `agent_websocket.v` | Real-time OODA state streaming, live monitoring
+| *JSON-RPC 2.0* | `agent_jsonrpc.v` | MCP native protocol, batch operations
+| *MQTT* | `agent_mqtt.v` | Distributed agent swarms, edge agents
+| *tRPC* | `agent_trpc.v` | Type-safe frontend agent controls
+| *SOAP* | `agent_soap.v` | Enterprise workflow integration
+| *Cap'n Proto* | `agent_capnproto.v` | High-performance multi-agent coordination
+|===
+
+=== Protocol Selection Guide
+
+* *Building an agent dashboard?* → GraphQL or WebSocket
+* *Orchestrating a bot fleet?* → gRPC or MQTT
+* *Connecting from an MCP client?* → JSON-RPC (native MCP protocol)
+* *Running agents on edge devices?* → MQTT
+* *Enterprise workflow integration?* → SOAP
+* *Maximum throughput agent swarm?* → Cap'n Proto or gRPC
+* *Simple single-agent integration?* → REST
+
+== Specific Agentic Server Types
+
+=== 1. OODA Compliance Gateway
+
+The most common deployment: every AI agent in an organisation must register a session with Agent-MCP before it can act. The gateway enforces that no agent skips the Observe → Orient → Decide sequence.
+
+*Example flow*: Claude Code starts a task → creates OODA session → Observes (reads code) → Orients (analyses patterns) → Decides (plans changes) → Acts (writes code) → loops back to Observe.
+
+=== 2. Multi-Agent Swarm Controller
+
+Uses MQTT to coordinate dozens of agents working on the same problem. Each agent has its own OODA session; the controller uses the `Consensus` coordination strategy to aggregate decisions before any agent acts.
+
+*Example*: 6 bots in the gitbot-fleet (Rhodibot, Echidnabot, Sustainabot, Panicbot, Glambot, Seambot) each run independent OODA loops, but coordinate via Agent-MCP before making changes to shared repositories.
+
+=== 3. Safety-Critical Agent Sandbox
+
+For high-risk agent actions (code deployment, database migrations, financial transactions), Agent-MCP gates every `Execute` tool call through the safety check. Only `Approved` or `Sandboxed` outcomes allow execution.
+
+*Example*: AI-assisted database migration — agent Observes schema, Orients by checking foreign keys, Decides on migration plan, but Act is blocked until safety check returns `Approved` (human reviews the plan).
+
+=== 4. Hierarchical Agent Orchestrator
+
+Uses gRPC for high-throughput manager → worker delegation. The manager agent runs its own OODA loop, and in the `Act` phase, delegates sub-tasks to worker agents, each with their own enforced OODA sessions.
+
+*Example*: Project manager agent decomposes a feature request → delegates sub-tasks to coding agent, testing agent, documentation agent → each worker follows its own OODA cycle → results flow back to manager's next Observe phase.
+
+=== 5. Agent Audit Trail
+
+Every OODA transition is a logged event. Using WebSocket streaming, a compliance dashboard shows real-time agent activity: which agents are in which OODA phase, how many loops they've completed, whether any have been halted.
+
+*Example*: Regulatory compliance — financial institution must prove that every AI decision followed a structured process. Agent-MCP's OODA log provides a formal audit trail with cryptographic attestation.
+
+=== 6. Adaptive Agent Learning
+
+Uses the `Episodic` and `Procedural` memory types to build agent skills over time. After each OODA loop, the agent stores what worked (episodic memory) and extracts reusable procedures (procedural memory).
+
+*Example*: DevOps agent learns from incident response — each incident is an OODA loop, the agent builds procedural memory of "when X alert fires, check Y then Z", getting faster with each iteration.
+
+== Value Beyond Current Implementation
+
+=== What We Have Now
+
+* Dependent-type proof that OODA stages cannot be skipped
+* 32 concurrent agent sessions with thread-safe management
+* 9 protocol transports for universal accessibility
+* Tool call classification with safety gates
+* Multi-agent coordination strategies
+* Cognitive memory type system
+
+=== What This Enables That Nothing Else Does
+
+1. *Provably Safe Agents*: No other agent framework mathematically guarantees that agents follow a structured decision loop. Agent-MCP's `ValidOODA` proof type makes "act without thinking" a *type error*, not a runtime bug.
+
+2. *Universal Agent Protocol*: The same OODA enforcement works over MQTT (for a Raspberry Pi agent), WebSocket (for a browser-based agent), gRPC (for a Kubernetes agent), and SOAP (for a bank's agent system) — all with the same formal guarantees.
+
+3. *Safety as Architecture*: Tool call classification and safety gates are not config — they are type-level properties. The system knows that `Execute` has side effects and `Query` doesn't, and enforces safety checks accordingly.
+
+4. *Coordination Without Chaos*: The 6 coordination strategies are not just labels — they prescribe how agents interact. `Consensus` means agents vote before acting; `Hierarchical` means only the manager can delegate. The protocol enforces this.
+
+5. *Memory as a Type System*: The 5 memory types aren't just storage categories — `Working` memory is explicitly non-persistent (disappears with the session), while `Shared` memory is explicitly cross-agent. This prevents accidental state leakage.
+
+== Roadmap
+
+=== Short-Term (v0.3.0)
+
+* [ ] *Session persistence*: Save/restore agent sessions across restarts (currently in-memory only)
+* [ ] *OODA metrics*: Track average time per phase, loop completion rate, halt frequency
+* [ ] *WebSocket state streaming*: Subscribe to specific session IDs for targeted monitoring
+* [ ] *Tool call logging*: Record every tool invocation with timestamp, inputs, outputs, safety check result
+* [ ] *MQTT retained messages*: Last-known state available to new subscribers
+
+=== Medium-Term (v0.4.0)
+
+* [ ] *Plan execution engine*: The 7 `PlanStep` types (Action, Condition, Loop, Branch, Parallel, Checkpoint, Rollback) become executable — agents submit plans, Agent-MCP validates and executes them step by step
+* [ ] *Agent capability model*: Define what tools each agent is allowed to use (per-session capability sets)
+* [ ] *Cross-session coordination*: Agents in different sessions can coordinate without sharing state (message-passing only)
+* [ ] *Rollback support*: If an `Act` fails, automatically roll back to the last `Checkpoint` in the plan
+* [ ] *GraphQL subscriptions*: Real-time OODA state changes via GraphQL subscription
+* [ ] *Cap'n Proto streaming*: Bidirectional streaming for high-throughput swarm coordination
+
+=== Long-Term (v1.0)
+
+* [ ] *Formal verification of coordination*: Prove that `Consensus` coordination never deadlocks and always terminates (using Idris2 totality checker)
+* [ ] *Agent identity and attestation*: Each agent cryptographically signs its OODA transitions, creating a tamper-proof audit trail
+* [ ] *OODA composition*: Nest OODA loops — an `Act` phase can contain a sub-OODA cycle for fine-grained decision-making
+* [ ] *Temporal logic properties*: Prove liveness (agents always eventually act) and safety (agents never act without deciding) using CTL model checking
+* [ ] *Agent marketplace*: Community-contributed agent templates with pre-defined OODA patterns, tool call sets, and coordination strategies
+* [ ] *Cross-cartridge agent workflows*: Agent-MCP orchestrates multi-cartridge workflows (e.g., agent uses NeSy-MCP for decision verification, Database-MCP for data access, Git-MCP for code changes — all within a single OODA loop)
+* [ ] *Self-improving agents*: Agents analyse their own OODA loop performance and suggest optimisations to their observation and orientation strategies
+
+=== Protocol Evolution
+
+* [ ] *HTTP/2 native gRPC*: Upgrade from JSON-over-HTTP to full Protobuf transport via Zig FFI
+* [ ] *QUIC transport*: UDP-based low-latency transport for swarm gossip
+* [ ] *NATS/JetStream*: Cloud-native messaging for distributed agent coordination
+* [ ] *OpenTelemetry integration*: Emit OODA transitions as OTel spans with distributed trace context
+* [ ] *MCP native transport*: Direct MCP stdio bridge without HTTP intermediary
+* [ ] *Agent-to-Agent protocol*: Purpose-built binary protocol for direct agent communication without broker overhead