Distributed Mesh Execute — DAG-Based Workflow Orchestration
2026-03-24
Distributed Mesh Execute
What We Built
POST /v1/mesh/execute — a workflow orchestration endpoint that:
- Accepts a decomposed workflow as a DAG of steps with dependency declarations
- Validates the dependency graph (cycle detection, missing references, duplicates)
- Executes independent steps in parallel using
Promise.allSettled - Pipes step outputs as context into dependent steps
- Tracks cumulative cost against a budget limit
- Streams progress as SSE events (
step-started,step-completed,step-failed,workflow-completed,budget-exceeded)
Why It Matters
When brainstorm decomposes a complex task into sub-tasks, it needs a way to execute them across BR's model fleet in parallel. Steps that don't depend on each other run simultaneously on optimal models. This is the foundation for multi-agent workflow orchestration through BrainstormRouter.
Lockstep Traceability
| Surface | Status | Files |
|---|---|---|
| API | Implemented | src/api/routes/mesh-execute.ts |
| SDK-TS | Implemented | packages/sdk-ts/src/resources/mesh.ts, packages/sdk-ts/src/index.ts |
| SDK-PY | Implemented | packages/sdk-py/src/brainstormrouter/resources/mesh.py |
| MCP | Implemented | src/mcp/server.ts, src/mcp/tool-manifest.ts |
| Tests | Implemented | src/api/routes/mesh-execute.test.ts |
| CLI | N/A | No CLI commands needed |
| GTM | N/A | Internal API |
| Dashboard | N/A | Mesh visualization exists but execution monitoring is future |
Key Design Decisions
- Separate route file from
mesh.ts— mesh.ts is CAF/mTLS-focused (agent registry, heartbeat, invoke); mesh-execute is higher-level orchestration - Kahn's algorithm for DAG validation — topological sort produces execution layers (groups of parallel steps)
- In-memory execution (MVP) — step execution is simulated, consistent with phases 041-045
- SSE streaming via Hono's
streamSSE— real-time step progress events - Pre-flight + runtime budget enforcement — reject if estimated cost exceeds budget, abort mid-workflow if cumulative cost exceeds limit
- Diamond dependency pattern supported — steps with multiple dependencies wait for all to complete