Files
waggle-os/packages/agent/src/workflow-composer.ts
Oleg Maslov b20b138fe4 moving
2026-09-02 10:14:22 +02:00

422 lines
16 KiB
TypeScript

/**
* Workflow Composer — transforms a detected task shape into a WorkflowPlan
* with execution-mode selection, user-facing explanation, and optional
* WorkflowTemplate for sub-agent execution.
*
* Core principle: choose the lightest sufficient execution mode.
* Most tasks should resolve as direct or structured_single_agent.
* Sub-agent workflows are the heavy option, not the default.
*/
import type { TaskShape, TaskShapeType, ComponentPhase } from './task-shape.js';
import {
MAX_WORKFLOW_STEPS,
type WorkflowTemplate,
type WorkflowStep,
} from './subagent-orchestrator.js';
import type { LoadedSkill } from './prompt-loader.js';
import type { WorkflowHarness } from './workflow-harness.js';
import { matchHarness } from './builtin-harnesses.js';
import { FEATURE_FLAGS } from './feature-flags.js';
// ── Types ────────────────────────────────────────────────────────────
export type ExecutionMode =
| 'direct' // Agent handles directly, no special structure
| 'structured_single_agent' // Agent follows a structured plan, no sub-agents
| 'skill_guided' // Agent uses a loaded skill's workflow
| 'subagent_workflow' // Multi-agent orchestration via SubagentOrchestrator
| 'harnessed'; // State-machine harness with phase gates
export interface WorkflowPlan {
/** Recommended execution mode */
executionMode: ExecutionMode;
/** Why this mode was chosen (internal reasoning) */
modeReason: string;
/** What would trigger escalation to a heavier mode */
escalationTrigger: string;
/** User-facing explanation — concise, work-oriented */
explanation: string;
/** Structured steps for the agent to follow (all modes) */
steps: PlanStep[];
/** Full WorkflowTemplate — only present when executionMode is subagent_workflow */
template?: WorkflowTemplate;
/** Harness to use when executionMode is 'harnessed' */
harness?: WorkflowHarness;
/** Detected task shape that informed this plan */
shape: TaskShape;
}
export interface PlanStep {
/** Step name (human-readable) */
name: string;
/** What this step does */
action: string;
/** Which skill to use, if applicable */
skill?: string;
}
export interface ComposerContext {
/** Currently loaded skills */
skills?: LoadedSkill[];
/** Whether sub-agent spawning is available */
subAgentsAvailable?: boolean;
/** Message length as complexity signal */
messageLength?: number;
}
// ── Composer ─────────────────────────────────────────────────────────
export function composeWorkflow(
shape: TaskShape,
task: string,
context?: ComposerContext,
): WorkflowPlan {
const mode = selectExecutionMode(shape, task, context);
const steps = buildPlanSteps(shape, task, context);
const explanation = buildExplanation(shape, steps, mode);
const template = mode === 'subagent_workflow'
? buildTemplate(shape, task, steps)
: undefined;
const harness = mode === 'harnessed'
? matchHarness(task)
: undefined;
return {
executionMode: mode,
modeReason: explainModeChoice(mode, shape, context),
escalationTrigger: getEscalationTrigger(mode),
explanation,
steps,
template,
harness,
shape,
};
}
// ── Execution mode selection ─────────────────────────────────────────
function selectExecutionMode(shape: TaskShape, task?: string, context?: ComposerContext): ExecutionMode {
// Check for matching harness FIRST (opt-in via feature flag)
if (task && FEATURE_FLAGS.ADVANCED_WORKFLOWS) {
const harness = matchHarness(task);
if (harness) return 'harnessed';
}
// Check for matching skill
if (context?.skills && context.skills.length > 0) {
const matchingSkill = findMatchingSkill(shape, context.skills);
if (matchingSkill) return 'skill_guided';
}
// Simple/low-confidence → direct
if (shape.complexity === 'simple' || shape.confidence < 0.3) {
return 'direct';
}
// Moderate complexity, single shape → structured single agent
if (shape.complexity === 'moderate' && shape.type !== 'mixed') {
return 'structured_single_agent';
}
// Mixed with 2 phases → structured single agent (still manageable)
if (shape.type === 'mixed' && shape.phases && shape.phases.length <= 2) {
return 'structured_single_agent';
}
// Complex mixed (3+ phases) or complex single shape → sub-agent if available
if (shape.complexity === 'complex' && context?.subAgentsAvailable !== false) {
return 'subagent_workflow';
}
// Complex but no sub-agents → structured single agent (best effort)
if (shape.complexity === 'complex') {
return 'structured_single_agent';
}
// Default: structured single agent for anything moderate+
return 'structured_single_agent';
}
function findMatchingSkill(shape: TaskShape, skills: LoadedSkill[]): LoadedSkill | undefined {
const shapeKeywords: Record<string, string[]> = {
research: ['research', 'synthesis', 'investigate'],
compare: ['compare', 'decision-matrix', 'tradeoff'],
draft: ['draft', 'memo', 'write'],
review: ['review', 'code-review', 'critique'],
decide: ['decision', 'decide', 'risk-assessment'],
'plan-execute': ['plan', 'task-breakdown', 'daily-plan'],
};
const keywords = shapeKeywords[shape.type] ?? [];
return skills.find(s =>
keywords.some(k => s.name.includes(k) || s.content.toLowerCase().includes(k))
);
}
function explainModeChoice(mode: ExecutionMode, shape: TaskShape, context?: ComposerContext): string {
switch (mode) {
case 'direct':
return `Task is ${shape.complexity} with ${shape.confidence < 0.3 ? 'low' : 'clear'} structure — direct execution is sufficient.`;
case 'skill_guided':
return `A loaded skill matches this ${shape.type} task — using skill-guided execution.`;
case 'structured_single_agent':
return `Task has ${shape.type === 'mixed' ? 'multiple phases' : 'clear structure'} but can be handled in sequence without sub-agents.`;
case 'subagent_workflow':
return `Task is complex${shape.type === 'mixed' ? ` with ${shape.phases?.length ?? 3}+ phases` : ''} — parallel sub-agents will be more effective.`;
case 'harnessed':
return `Task matches a workflow harness with enforced phase gates — deterministic execution with validation.`;
}
}
function getEscalationTrigger(mode: ExecutionMode): string {
switch (mode) {
case 'direct':
return 'Escalate to structured plan if task turns out to have multiple distinct phases.';
case 'skill_guided':
return 'Escalate to structured plan if the skill does not cover all aspects of the task.';
case 'structured_single_agent':
return 'Escalate to sub-agent workflow if individual phases are each substantial enough to warrant parallel execution.';
case 'subagent_workflow':
return 'Already using the heaviest mode. Simplify if task turns out to be straightforward.';
case 'harnessed':
return 'Using deterministic harness. Escalate to sub-agent if phases need parallel execution.';
}
}
// ── Plan step construction ───────────────────────────────────────────
function buildPlanSteps(shape: TaskShape, task: string, context?: ComposerContext): PlanStep[] {
if (shape.type === 'mixed' && shape.phases) {
return buildMixedSteps(shape.phases, task, context);
}
return buildShapeSteps(shape.type, task, context);
}
function buildShapeSteps(
shapeType: TaskShapeType,
task: string,
context?: ComposerContext,
): PlanStep[] {
const matchedSkill = context?.skills
? findMatchingSkill({ type: shapeType } as TaskShape, context.skills)
: undefined;
switch (shapeType) {
case 'research':
return [
{ name: 'Gather sources', action: 'Search memory, web, and files for relevant information' },
{ name: 'Synthesize findings', action: 'Organize and synthesize raw findings into a coherent summary', skill: matchedSkill?.name },
];
case 'compare':
return [
{ name: 'Identify options', action: 'Clarify the options being compared and the criteria' },
{ name: 'Analyze each option', action: 'Evaluate each option against the criteria' },
{ name: 'Present comparison', action: 'Summarize tradeoffs and key differences', skill: matchedSkill?.name },
];
case 'draft':
return [
{ name: 'Gather context', action: 'Pull relevant context from memory and workspace' },
{ name: 'Write draft', action: 'Produce the requested document or content', skill: matchedSkill?.name },
];
case 'review':
return [
{ name: 'Read and understand', action: 'Read the material being reviewed' },
{ name: 'Identify issues', action: 'Evaluate for accuracy, completeness, clarity, and quality' },
{ name: 'Provide feedback', action: 'Present structured feedback with specific suggestions', skill: matchedSkill?.name },
];
case 'decide':
return [
{ name: 'Frame the decision', action: 'Clarify the question, constraints, and success criteria' },
{ name: 'Evaluate options', action: 'Assess each option against criteria' },
{ name: 'Recommend', action: 'Present recommendation with reasoning', skill: matchedSkill?.name },
];
case 'plan-execute':
return [
{ name: 'Analyze scope', action: 'Understand the full scope and constraints' },
{ name: 'Break into phases', action: 'Decompose into ordered, actionable phases' },
{ name: 'Identify risks', action: 'Flag dependencies, risks, and unknowns' },
{ name: 'Present plan', action: 'Deliver structured plan with clear next steps', skill: matchedSkill?.name },
];
default:
return [
{ name: 'Execute task', action: 'Handle the request directly' },
];
}
}
function buildMixedSteps(
phases: ComponentPhase[],
_task: string,
context?: ComposerContext,
): PlanStep[] {
const steps: PlanStep[] = [];
for (const phase of phases) {
const phaseSteps = buildShapeSteps(phase.shape, phase.trigger, context);
// For mixed tasks, take the key action from each phase (not all sub-steps)
if (phaseSteps.length <= 2) {
steps.push(...phaseSteps);
} else {
// Consolidate to the most important step per phase
steps.push({
name: `${capitalize(phase.shape)}`,
action: phaseSteps.map(s => s.action).join('; '),
skill: phaseSteps.find(s => s.skill)?.skill,
});
}
}
return steps;
}
// ── Template construction (only for subagent_workflow) ────────────────
function buildTemplate(shape: TaskShape, task: string, steps: PlanStep[]): WorkflowTemplate {
const workflowSteps: WorkflowStep[] = steps.map((step, i) => ({
name: step.name,
role: mapStepToRole(step),
task: `${step.action}:\n\n${task}`,
dependsOn: i > 0 ? [steps[i - 1].name] : undefined,
contextFrom: i > 0 ? steps.slice(0, i).map(s => s.name) : undefined,
maxTurns: 25,
}));
return {
name: `composed-${shape.type}`,
description: `Dynamically composed workflow for ${shape.type} task`,
steps: workflowSteps,
aggregation: 'last',
};
}
function mapStepToRole(step: PlanStep): string {
const action = step.action.toLowerCase();
if (action.includes('search') || action.includes('gather') || action.includes('research')) return 'researcher';
if (action.includes('write') || action.includes('draft') || action.includes('produce')) return 'writer';
if (action.includes('review') || action.includes('evaluate') || action.includes('critique')) return 'reviewer';
if (action.includes('plan') || action.includes('break') || action.includes('decompose')) return 'planner';
if (action.includes('synthesize') || action.includes('summarize') || action.includes('consolidate')) return 'synthesizer';
return 'analyst';
}
// ── User-facing explanation ──────────────────────────────────────────
function buildExplanation(shape: TaskShape, steps: PlanStep[], mode: ExecutionMode): string {
const stepCount = steps.length;
// Short intro based on mode
let intro: string;
switch (mode) {
case 'direct':
return `I'll handle this directly.`;
case 'skill_guided': {
const skill = steps.find(s => s.skill);
return `I'll use the **${skill?.skill}** skill to guide this.`;
}
case 'structured_single_agent':
intro = `I'd handle this in ${stepCount} step${stepCount > 1 ? 's' : ''}`;
break;
case 'subagent_workflow':
intro = `I'd run this as a ${stepCount}-step workflow with specialist agents`;
break;
case 'harnessed':
intro = `I'd execute this through a structured harness with ${stepCount} validated phase${stepCount > 1 ? 's' : ''}`;
break;
}
// Build step list
const stepDescs = steps.map((s, i) => {
const prefix = stepCount <= 3
? ['First', 'Then', 'Finally'][i] ?? `Step ${i + 1}`
: `${i + 1}.`;
return `${prefix}, ${s.action.charAt(0).toLowerCase()}${s.action.slice(1)}`;
});
return `${intro}:\n${stepDescs.join('\n')}`;
}
// ── Validation ───────────────────────────────────────────────────────
export interface ValidationError {
field: string;
message: string;
}
export function validateTemplate(template: WorkflowTemplate): ValidationError[] {
const errors: ValidationError[] = [];
if (!template.name) errors.push({ field: 'name', message: 'Template name is required' });
if (!template.steps || template.steps.length === 0) {
errors.push({ field: 'steps', message: 'At least one step is required' });
return errors;
}
const workerCount = template.steps.length + (template.aggregation === 'synthesize' ? 1 : 0);
if (workerCount > MAX_WORKFLOW_STEPS) {
errors.push({
field: 'steps',
message: `Workflow worker limit exceeded: ${workerCount} > ${MAX_WORKFLOW_STEPS}`,
});
return errors;
}
if (!['concatenate', 'last', 'synthesize'].includes(template.aggregation)) {
errors.push({ field: 'aggregation', message: `Invalid aggregation: ${template.aggregation}` });
}
const stepNames = new Set<string>();
for (const step of template.steps) {
if (!step.name) errors.push({ field: 'steps', message: 'Step name is required' });
if (!step.role) errors.push({ field: 'steps', message: `Step "${step.name}" requires a role` });
if (!step.task) errors.push({ field: 'steps', message: `Step "${step.name}" requires a task` });
if (stepNames.has(step.name)) {
errors.push({ field: 'steps', message: `Duplicate step name: ${step.name}` });
}
stepNames.add(step.name);
// Check dependency references
for (const dep of step.dependsOn ?? []) {
if (!stepNames.has(dep) && !template.steps.some(s => s.name === dep)) {
errors.push({ field: 'steps', message: `Step "${step.name}" depends on unknown step "${dep}"` });
}
}
}
// Check for cycles
if (hasCycle(template.steps)) {
errors.push({ field: 'steps', message: 'Workflow has circular dependencies' });
}
return errors;
}
function hasCycle(steps: WorkflowStep[]): boolean {
const visited = new Set<string>();
const inStack = new Set<string>();
const adjMap = new Map<string, string[]>();
for (const step of steps) {
adjMap.set(step.name, step.dependsOn ?? []);
}
function dfs(node: string): boolean {
if (inStack.has(node)) return true;
if (visited.has(node)) return false;
visited.add(node);
inStack.add(node);
for (const dep of adjMap.get(node) ?? []) {
if (dfs(dep)) return true;
}
inStack.delete(node);
return false;
}
for (const step of steps) {
if (dfs(step.name)) return true;
}
return false;
}
// ── Helpers ──────────────────────────────────────────────────────────
function capitalize(s: string): string {
return s.charAt(0).toUpperCase() + s.slice(1);
}