mermate-agentic-infra

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 lifecycl

SKILL.md

GitHub

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