Mermate Agentic Infra

---
name: mermate-agentic-infra
description: Core agentic infrastructure of the Mermate application — detached agent sessions (run/finalize/attach/stop), agent modes, depth scoring and role caps, Opseeq stage-event bridge with heartbeat lifecycle, run lineage and trace store, boot/health gates, and the Python MCP bridge. Use when working on server/routes/agent.js, opseeq-bridge.js, run tracking, server boot/health, mcp_service/, or cross-cutting pipeline behavior rather than a single tab.
---

# Mermate Agentic Infrastructure

Operates under `mermate` master invariants; Lamport standards via `specification-master-agent`. This skill owns the machinery *between* the tabs; tab-specific work belongs to the `mermate-tab-*` skills.

## 1. Agent Sessions (server/routes/agent.js, public/js/mermaid-gpt-agent.js)
- Two-phase flow: **Phase 1** `POST /api/agent/run` (planning → refinement → preview render → pause for notes) → **Phase 2** `POST /api/agent/finalize` (apply notes → final Max render).
- **Detached sessions**: owned by session, not SSE connection; events buffered for replay. Reattach `GET /api/agent/attach/:sessionId`, stop `POST /api/agent/stop/:sessionId`, list `GET /api/agent/active`, modes `GET /api/agent/modes`.
- Grace: 300s no-listener timeout (`MERMATE_AGENT_GRACE`); sessions retained 10 min after completion; frontend persists session id in localStorage (`MermaidAgent.SESSION_KEY`).
- Agent modes: `code-review`, `thinking`, `optimize-mmd`, `tla-verify`, `tla-optimize`, `ts-generate`, `ts-optimize`, `full-build`.

**Invariants**
1. A session's event stream is replayable: reattach after refresh delivers buffered events in order; no event is lost to a dropped SSE connection.
2. Terminal SSE events are never dropped: `preview_ready`, `final_render`, `done`, `error`.
3. Depth scoring gates fan-out: `depthScore` (0–1) → tier shallow/medium/deep → role cap 2/3/4, reported as `agent_depth_score` to Opseeq.

## 2. Opseeq Bridge (server/services/opseeq-bridge.js)
- `OPSEEQ_URL` default `http://localhost:9090`; `reportStage(runId, stageEvent)` is **fire-and-forget** — WebSocket first, HTTP fallback (at-least-once), local persistence via `traceStore.append()`. Opseeq dedupes on `(run_id, stage, ts)`.
- Stage events: `render_start/complete/failed`, `agent_depth_score/planning/preview/finalize`, `tla_complete/failed`, `ts_complete/partial/failed`.
- Heartbeat lifecycle (server/index.js): frontend pings `POST /api/opseeq/heartbeat`; >60s silence (`OPSEEQ_HEARTBEAT_TIMEOUT_MS`) stops the container; boot gate polls ≤30s; warm-up failure is non-fatal.

**Invariants**
4. The pipeline never blocks on Opseeq: gateway down → `fallback_events` in the trace, render still succeeds.
5. Boot waits are bounded (server 30s gate; frontend 4×2s warm poll + 20s heartbeat badge) — no unbounded stall on optional infrastructure.

## 3. Run Lineage & Traces
- Every run: `run_id` + JSON lineage in `runs/`, artifacts in `flows/`, archived sources in `archs/`.
- Read paths: `GET /api/runs`, `GET /api/artifacts/:run_id`, `GET /api/runs/:runId/bundle`, `GET /api/mermate/trace/:run_id` (server/routes/trace.js).
- Search/projects: server/routes/search.js over DuckDB (`server/backend/query`).

**Invariant**
6. Lineage is append-only and auditable: a trace read back via `/api/mermate/trace/:run_id` reconstructs the run's stage order without gaps.

## 4. MCP Bridge (mcp_service/ — Python)
- `server.py` (tools, stage map) / `client.py` (HTTP+SSE transport); thin layer over Express — no synthetic workflows. Stage map: render, tla, ts, rust, tsx, agent_preview, agent_finalize, agent_session, runs, artifacts, bundle, guide, specula, trace, tla_harness.
- Config: `.mcp.json` → `.venv-mcp/bin/python -m mcp_service`, `MERMATE_URL=http://127.0.0.1:3333`, `OPENCLAW_URL=http://127.0.0.1:8787`. External servers: `opseeq` (SSE, :9090/mcp), `synth` (`synthesis-mcp`, stdio — external, not in this repo).
- Authoring discipline: see `mermate-openclaw-mcp` (.agents) — maintained under `ponytail`.

## 5. Boot & Health
- `npm start` → `server/index.js` :3333; `GET /api/health` reports copilot, Opseeq (healthy/warming), toolchain status.
- Setup: `docs/installation.md` (`./mermaid.sh start`, optional Ollama/OpenAI providers, `.env`).

## Anti-Patterns (Reject)
- Coupling a stage's success path to Opseeq availability.
- Session state keyed to SSE connection instead of session id.
- New MCP tools that don't map to a real Express route.
- Unbounded waits/retries anywhere in boot, heartbeat, or telemetry.

## Verification
- `node --test test/test-e2e-tandem.js` — full tandem loop incl. trace correlation + `fallback_events`
- `node --test test/test-e2e-agent.js` — agent workflow
- `python3 -m unittest test/test_mermate_mcp_service.py` — MCP bridge
- `curl -s http://localhost:3333/api/health | python3 -m json.tool`