mco-runtime.architecture.json

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "MCO Runtime Architecture",
    "subtitle": "mco-org/mco · explicit provider policy · parallel invocation · durable raw answers",
    "output": "docs/cases/mco-runtime.architecture.html",
    "animation": "trace",
    "visual_preset": "signal-flow",
    "quality_profile": "showcase",
    "repository": {
      "url": "https://github.com/mco-org/mco",
      "revision": "9f1a1cf1afdc04d7b5406782b40dfec76d9bc798"
    },
    "views": [
      {
        "id": "dispatch-path",
        "label": "Dispatch path",
        "focus": ["callers", "entry", "router", "policy", "workflow", "adapters", "provider_clis"],
        "note": "An explicit provider team crosses one validated execution-policy boundary before MCO starts parallel work."
      },
      {
        "id": "answer-evidence",
        "label": "Answer evidence",
        "focus": ["adapters", "answer_transport", "artifacts", "consumers"],
        "note": "Provider output is decoded and persisted without turning raw answers into an automatic decision."
      },
      {
        "id": "durable-sessions",
        "label": "Durable sessions",
        "focus": ["router", "session_daemon", "session_state"],
        "note": "Detached local workers use Unix sockets plus state.json and history.jsonl for resumable sessions."
      }
    ]
  },
  "components": [
    {
      "id": "callers",
      "type": "external",
      "label": "Callers",
      "sublabel": "human · coding agent",
      "pos": [5, 250],
      "size": [130, 60]
    },
    {
      "id": "entry",
      "type": "frontend",
      "label": "Entry Surfaces",
      "sublabel": "npm shim · Python CLI · MCP",
      "pos": [175, 250],
      "size": [160, 60],
      "sources": [
        { "path": "bin/mco.js", "line": 1, "label": "npm entry" },
        { "path": "runtime/mcp_server.py", "line": 108, "end_line": 153, "label": "MCP entry" }
      ]
    },
    {
      "id": "router",
      "type": "backend",
      "label": "Command Router",
      "sublabel": "run · review · doctor · session",
      "pos": [360, 250],
      "size": [180, 60],
      "sources": [
        { "path": "runtime/cli.py", "line": 1945, "label": "CLI main" }
      ]
    },
    {
      "id": "config",
      "type": "database",
      "label": "Config + Selection",
      "sublabel": "files · explicit provider team",
      "pos": [565, 110],
      "size": [175, 60],
      "tag": "no silent team",
      "sources": [
        { "path": "runtime/config.py", "line": 24, "label": "Review config" }
      ]
    },
    {
      "id": "policy",
      "type": "security",
      "label": "Execution Policy",
      "sublabel": "read_only · write · yolo",
      "pos": [565, 250],
      "size": [175, 60],
      "tag": "explicit boundary",
      "sources": [
        { "path": "runtime/policy.py", "line": 34, "label": "Provider policy" }
      ]
    },
    {
      "id": "workflow",
      "type": "backend",
      "label": "Invocation Workflow",
      "sublabel": "parallel · chain · debate · synthesize",
      "pos": [765, 250],
      "size": [220, 60],
      "sources": [
        { "path": "runtime/invocation_runtime.py", "line": 696, "label": "Workflow entry" },
        { "path": "runtime/invocation_runtime.py", "line": 156, "label": "Single invocation" }
      ]
    },
    {
      "id": "adapters",
      "type": "messagebus",
      "label": "Provider Adapters",
      "sublabel": "shim / ACP · detect · run · poll · cancel",
      "pos": [1010, 250],
      "size": [230, 60],
      "sources": [
        { "path": "runtime/adapters/__init__.py", "line": 57, "label": "Adapter registry" },
        { "path": "runtime/contracts.py", "line": 77, "label": "Provider contract" }
      ]
    },
    {
      "id": "provider_clis",
      "type": "external",
      "label": "Provider CLIs",
      "sublabel": "Claude · Codex · Pi · 7 more",
      "pos": [1035, 0],
      "size": [180, 60]
    },
    {
      "id": "answer_transport",
      "type": "messagebus",
      "label": "Answer Transport",
      "sublabel": "plain · JSON · JSONL · ACP events",
      "pos": [765, 420],
      "size": [190, 60],
      "sources": [
        { "path": "runtime/answer_transport.py", "line": 79, "label": "Transport decoders" }
      ]
    },
    {
      "id": "artifacts",
      "type": "cloud",
      "label": "Invocation Artifacts",
      "sublabel": "answers · result.md · run.json",
      "pos": [1010, 420],
      "size": [170, 60],
      "tag": "raw evidence",
      "sources": [
        { "path": "runtime/invocation_artifacts.py", "line": 8, "label": "Artifact writer" }
      ]
    },
    {
      "id": "consumers",
      "type": "external",
      "label": "Output Consumers",
      "sublabel": "terminal · calling agent · CI",
      "pos": [1005, 520],
      "size": [180, 60]
    },
    {
      "id": "session_daemon",
      "type": "backend",
      "label": "Session Daemon",
      "sublabel": "detached worker · Unix socket",
      "pos": [365, 420],
      "size": [170, 60],
      "sources": [
        { "path": "runtime/session/daemon.py", "line": 50, "label": "Daemon context" }
      ]
    },
    {
      "id": "session_state",
      "type": "database",
      "label": "Session State",
      "sublabel": "state.json · history.jsonl",
      "pos": [565, 420],
      "size": [170, 60],
      "tag": ".mco/sessions",
      "sources": [
        { "path": "runtime/session/state.py", "line": 25, "label": "Session state" }
      ]
    }
  ],
  "boundaries": [
    {
      "kind": "region",
      "label": "mco local package / Python runtime",
      "wraps": ["entry", "router", "config", "policy", "workflow", "adapters", "answer_transport", "artifacts", "session_daemon", "session_state"]
    },
    {
      "kind": "security-group",
      "label": "explicit execution-policy boundary",
      "wraps": ["policy", "workflow", "adapters"]
    }
  ],
  "connections": [
    {
      "id": "caller-entry",
      "from": "callers",
      "to": "entry",
      "variant": "emphasis"
    },
    {
      "id": "entry-route",
      "from": "entry",
      "to": "router",
      "variant": "emphasis"
    },
    {
      "id": "route-policy",
      "from": "router",
      "to": "policy",
      "variant": "security"
    },
    {
      "id": "config-policy",
      "from": "config",
      "to": "policy",
      "variant": "security",
      "fromSide": "bottom",
      "toSide": "top"
    },
    {
      "id": "policy-workflow",
      "from": "policy",
      "to": "workflow",
      "variant": "emphasis"
    },
    {
      "id": "workflow-adapters",
      "from": "workflow",
      "to": "adapters",
      "variant": "emphasis"
    },
    {
      "id": "adapters-providers",
      "from": "adapters",
      "to": "provider_clis",
      "label": "native CLI / ACP",
      "variant": "emphasis",
      "fromSide": "top",
      "toSide": "bottom"
    },
    {
      "id": "adapters-answer",
      "from": "adapters",
      "to": "answer_transport",
      "label": "decode events",
      "labelAt": [995, 365],
      "fromSide": "bottom",
      "toSide": "top"
    },
    {
      "id": "answer-artifacts",
      "from": "answer_transport",
      "to": "artifacts",
      "variant": "emphasis"
    },
    {
      "id": "artifacts-consumers",
      "from": "artifacts",
      "to": "consumers",
      "label": "raw answers",
      "labelAt": [1095, 510],
      "variant": "emphasis",
      "fromSide": "bottom",
      "toSide": "top"
    },
    {
      "id": "router-session",
      "from": "router",
      "to": "session_daemon",
      "label": "start · send · resume",
      "labelAt": [450, 365],
      "variant": "dashed",
      "fromSide": "bottom",
      "toSide": "top",
      "route": "straight"
    },
    {
      "id": "session-state",
      "from": "session_daemon",
      "to": "session_state",
      "label": "persist",
      "labelAt": [550, 406],
      "variant": "dashed"
    }
  ],
  "cards": [
    {
      "dot": "cyan",
      "title": "Source-backed dispatch",
      "items": [
        "runtime/cli.py requires an explicit provider or named agent team",
        "runtime/policy.py validates models, context, permissions, and risk",
        "runtime/invocation_runtime.py owns parallelism, timeouts, and cancellation"
      ]
    },
    {
      "dot": "emerald",
      "title": "Raw-answer contract",
      "items": [
        "Adapters keep each provider CLI behind one shared runtime contract",
        "answer_transport.py decodes output without inventing findings or consensus",
        "Artifacts persist answers and run metadata for terminal, agents, or CI"
      ]
    },
    {
      "dot": "violet",
      "title": "Real repository proof",
      "items": [
        "Repository: github.com/mco-org/mco",
        "Source snapshot: main @ 9f1a1cf",
        "Evidence read: README, CLI, policy, adapters, invocation runtime, sessions"
      ]
    }
  ]
}