/** * 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 = { 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(); 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(); const inStack = new Set(); const adjMap = new Map(); 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); }