ADR-0008: hercules-workflow-server as separate .NET service

Status: Accepted Date: 2026-08-14

Context

BPMN-like multi-agent workflow orchestration needs:

• Durable execution (survives restart)
• Triggers (webhook, cron, future: file watcher, event bus)
• Execution history and state persistence
• Graph model interpreter/executor
• Multi-agent intent routing via /api/mesh/intent

Options: (a) part of Hercules.WebApi, (b) separate .NET service, (c) Node-сервис, (d) Studio-orchestrated (renderer/main).

Decision

Separate .NET service: hercules-workflow-server.

Two-phase approach:

• Stage 8a (MVP): Studio-orchestrated (Studio executor reads graph, calls /api/mesh/intent, monitors via long-poll). Graph stored in Studio SQLite. Not durable — Studio closed = workflow interrupted.
• Stage 8b (Production): hercules-workflow-server (.NET, separate process). Durable executor, triggers, history. Graph stored in workflow-server DB.

Rationale for separate .NET service

• Durable: workflow engine must survive Studio close; needs its own process
• Heavy: graph interpreter, retry logic, scheduling = non-trivial; don’t bloat agent WebApi
• Triggers: webhook endpoint + cron scheduler = always-on service
• .NET ecosystem: reuse mesh intent envelope, ITransport, ITaskQueue, IMeshStateStore from Hercules
• Auth: clientId/clientSecret (simplified, no JWT for MVP) — workflow-server generates credentials, Studio registers them with agents
• Separation of concerns: agent = conversational AI; workflow-server = process orchestration

Architecture (Stage 8b)

Studio ──(REST, apiKey)──▶ hercules-workflow-server
                                │
                                │ (mesh intent envelope)
                                ▼
                          Agent A, Agent B, Agent C
                          (HTTP /api/mesh/intent)

Workflow-server API

Endpoint	Auth	Description
POST /api/workflows	clientId/secret	Save workflow definition
GET /api/workflows	clientId/secret	List definitions
POST /api/workflows/{id}/run	clientId/secret	Start execution
GET /api/workflows/{id}/executions	clientId/secret	List executions
GET /api/workflows/executions/{eid}	clientId/secret	Execution status (node states)
POST /api/workflows/triggers/webhook/{token}	public (token)	Webhook trigger
GET /api/workflows/triggers/cron	clientId/secret	List cron triggers

Triggers (MVP)

• Webhook: HTTP POST to /api/workflows/triggers/webhook/{token} → start workflow
• Cron: Quartz/Hangfire scheduler → start workflow at cron expression

Triggers (future)

• File watcher (new file in directory)
• Event bus (Kafka/RabbitMQ/NATS)

Auth model

• Studio → Workflow-server: API key (generated by workflow-server at install)
• Workflow-server → Agent: clientId/clientSecret (simplified, no JWT for MVP). Agent recognizes workflow-server as trusted peer via mesh agent registration.

Consequences

• New .NET project in solution: src/workflow-server/Hercules.WorkflowServer.csproj
• Backend tasks task_104 (workflow-server) + task_105 (graph model + executor) + task_106-108 (persistence, parent/child, checkpoints)
• Studio Connection Manager supports workflow-server as separate source type
• Architecture laid out in Stage 0, implementation in Stage 8

Alternatives considered

• Part of Hercules.WebApi: bloats agent, couples orchestration with conversational AI, harder to scale independently
• Node service: team has .NET expertise for backend; mesh primitives are .NET
• Studio-orchestrated only: not durable, Studio close = workflow lost. Acceptable for MVP only