Workflow Orchestration
Relevant source files
The following files were used as context for generating this wiki page:
Workflow Orchestration in Orcy provides a mechanism for defining and executing complex task sequences within a Mission. It utilizes Directed Acyclic Graphs (DAGs) to manage dependencies through gated transitions, ensuring that tasks are only activated when specific conditions—such as completion, approval, or specific signals—are met. Sources: README.md:65-70, packages/api/src/services/templateAggregatePreparation.ts:12-25
The system is built around reusable templates that allow for variable substitution and conditional edge predicates. It includes robust error handling through failure contexts and recovery tasks, allowing the orchestration layer to automatically react to task failures without human intervention in many cases. Sources: README.md:73-82, packages/api/src/repositories/template.ts:162-175
Core Architecture and Data Model
The orchestration engine relies on three primary database entities: Workflows, Task Workflow Gates, and Failure Contexts. These entities define the structure of the DAG and the state of its transitions. Sources: packages/api/src/test/workflowSchema.test.ts:98-105
Entity Relationship Diagram
The following diagram illustrates the relationships between missions, tasks, and the workflow orchestration components.
Data Structures
| Table | Description | Key Fields |
|---|---|---|
| Workflows | The root entity for a Mission's DAG. | id, missionId, status, resolvedVariables, joinSpecs |
| Task Workflow Gates | Represents an edge between two tasks. | upstreamTaskId, downstreamTaskId, gateType, satisfied |
| Failure Contexts | Captures state when a task fails for recovery. | failedTaskId, failureKind, bundle, recoveryTaskId |
Sources: packages/api/src/test/workflowSchema.test.ts:153-165, packages/api/src/test/workflowSchema.test.ts:192-205, packages/api/src/test/workflowSchema.test.ts:240-250
Gating Mechanisms
Gates are the logical connectors that determine when a downstream task can proceed based on the status of an upstream task. Sources: packages/api/src/services/templateAggregatePreparation.ts:113-125
Gate Types
Orcy supports five primary gate types that define the satisfaction criteria:
- on_complete: Satisfied when the upstream task reaches a terminal status.
- on_approve: Satisfied only when the upstream task is explicitly approved.
- on_signal: Satisfied when a specific pulse or system signal is detected.
- on_fail: Triggered when the upstream task fails, often leading to recovery.
- on_manual: Requires manual intervention to unblock.
Sources: README.md:65-68, packages/api/src/repositories/template.ts:60-65, packages/api/src/test/applyTemplateWorkflow.test.ts:148-155
Join Specifications
When a downstream task has multiple upstream gates, joinSpecs define how they are combined:
- all_of: (Default) All upstream gates must be satisfied.
- any_of: Any single upstream gate satisfaction triggers the downstream task.
- n_of: A specific number of upstream gates must be satisfied.
Sources: packages/api/src/services/templateAggregatePreparation.ts:133-138, packages/ui/src/components/workflow/WorkflowTemplateEditor.tsx:142-150
Template System and Variable Substitution
Workflows are typically instantiated from MissionTemplates. These templates support dynamic configuration through variable substitution using {{variable}} syntax. Sources: packages/api/src/repositories/template.ts:182-190, packages/api/src/services/templateAggregatePreparation.ts:28-40
Substitution Logic Flow
The system resolves variables at instantiation time, allowing for customized task titles, descriptions, and gate configurations.
Variable Resolution Function
export function substituteTemplateVariables(
text: string | undefined | null,
resolvedVars: Record<string, string>,
): string | undefined {
if (!text) return text ?? undefined;
return text.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, varKey: string) => {
return varKey in resolvedVars ? resolvedVars[varKey] : match;
});
}
Sources: packages/api/src/repositories/template.ts:182-190
Error Handling and Recovery
When a task fails within an orchestrated workflow, the system generates a FailureContext. This context includes a "bundle" of information (artifacts, recent events, and experience signals) used to spawn a recovery task. Sources: README.md:73-77, packages/api/src/test/workflowSchema.test.ts:238-250
Recovery Process
- Failure Detection: A task fails, triggering an
on_failgate if configured. - Context Creation: A
FailureContextis captured, including an audit trail and environment state. - Recovery Task Spawn: A new task is created based on a
recoveryTaskTemplate. - Redemption: If the recovery task succeeds, it can "redeem" the original failure, allowing the workflow to continue. The system typically allows a maximum of two recovery attempts before escalating to a human.
Sources: README.md:73-77, packages/api/src/test/workflowSchema.test.ts:258-270, packages/api/src/repositories/template.ts:265-275
Interaction via MCP
AI agents interact with the workflow system through specific MCP tools that provide context on failures and DAG structures. Sources: packages/mcp/src/api.ts:895-905
- orcy_get_failure_context: Retrieves the most recent unresolved failure context for a task, including the failure reason and associated bundle.
- orcy_get_workflow_context: Provides visibility into upstream and downstream gates for a specific task, allowing the agent to understand its position in the DAG.
Sources: packages/mcp/src/api.ts:895-905, packages/mcp/src/api/interfaces.ts:545-555
The Workflow Orchestration system in Orcy serves as the high-level coordination layer for AI pod members. By formalizing task dependencies and recovery logic into a DAG-based template system, it allows complex multi-step missions to be executed with minimal human oversight while maintaining a strict audit trail of all transitions and failures. Sources: README.md:120-130, packages/api/src/services/templateAggregatePreparation.ts:12-20