guild-agents 1.5.0 → 2.0.0

package/src/utils/dispatch.js

@@ -1,172 +0,0 @@
-/**
- * dispatch.js — Validation and resolution utilities for the Guild dispatch protocol.
- *
- * Provides functions to validate workflow step configurations, resolve agent
- * metadata from frontmatter, determine effective model tiers, and resolve
- * tiers to concrete model IDs.
- */
-
-import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
-import { parseFrontmatter } from './files.js';
-import { parseSkill } from './workflow-parser.js';
-import {
-  MODEL_TIERS,
-  FAILURE_STRATEGIES,
-  DEFAULT_AGENT_TIERS,
-  DEFAULT_MODEL_PROFILES,
-  FALLBACK_CHAIN,
-} from './dispatch-protocol.js';
-
-/**
- * Validates a workflow step configuration object.
- * @param {object} config - Step config with role, intent, model-tier, etc.
- * @returns {string[]} Array of error messages (empty means valid)
- */
-export function validateStepConfig(config) {
-  const errors = [];
-
-  if (!config.role) {
-    errors.push('Missing required field: role');
-  }
-
-  if (!config.intent) {
-    errors.push('Missing required field: intent');
-  }
-
-  if (config['model-tier'] && !MODEL_TIERS.includes(config['model-tier'])) {
-    errors.push(`Invalid model-tier: "${config['model-tier']}". Must be one of: ${MODEL_TIERS.join(', ')}`);
-  }
-
-  if (config['on-failure']) {
-    const isGoto = config['on-failure'].startsWith('goto:');
-    if (!FAILURE_STRATEGIES.includes(config['on-failure']) && !isGoto) {
-      errors.push(`Invalid on-failure: "${config['on-failure']}". Must be one of: ${FAILURE_STRATEGIES.join(', ')}, or goto:<step-id>`);
-    }
-  }
-
-  if (config['max-retries'] !== undefined) {
-    const val = config['max-retries'];
-    if (!Number.isInteger(val) || val < 1) {
-      errors.push(`Invalid max-retries: ${val}. Must be a positive integer`);
-    }
-  }
-
-  return errors;
-}
-
-/**
- * Reads agent metadata from the agent's markdown frontmatter.
- * @param {string} role - Agent role name (e.g., 'tech-lead')
- * @param {string} [projectRoot=process.cwd()] - Project root directory
- * @returns {{ name: string, role: string, defaultTier: string|undefined, [key: string]: unknown } | null}
- */
-export function resolveAgentMetadata(role, projectRoot = process.cwd()) {
-  const agentPath = join(projectRoot, '.claude', 'agents', `${role}.md`);
-
-  if (!existsSync(agentPath)) {
-    return null;
-  }
-
-  const content = readFileSync(agentPath, 'utf8');
-  const frontmatter = parseFrontmatter(content);
-
-  return {
-    ...frontmatter,
-    role,
-    defaultTier: frontmatter['default-tier'] || undefined,
-  };
-}
-
-/**
- * Resolves the effective model tier for a workflow step using the precedence chain:
- * 1. stepConfig['model-tier'] (explicit in workflow step)
- * 2. agentMetadata.defaultTier (from agent frontmatter)
- * 3. DEFAULT_AGENT_TIERS[role] (hardcoded defaults)
- * 4. 'execution' (ultimate fallback)
- *
- * @param {object} stepConfig - Workflow step with role and optional model-tier
- * @param {object|null} [agentMetadata=null] - Agent metadata from resolveAgentMetadata
- * @returns {string} One of MODEL_TIERS values
- */
-export function resolveEffectiveTier(stepConfig, agentMetadata = null) {
-  if (stepConfig['model-tier'] && MODEL_TIERS.includes(stepConfig['model-tier'])) {
-    return stepConfig['model-tier'];
-  }
-
-  if (agentMetadata?.defaultTier && MODEL_TIERS.includes(agentMetadata.defaultTier)) {
-    return agentMetadata.defaultTier;
-  }
-
-  const defaultTier = DEFAULT_AGENT_TIERS[stepConfig.role];
-  if (defaultTier) {
-    return defaultTier;
-  }
-
-  return 'execution';
-}
-
-/**
- * Resolves a model tier to a concrete model ID using a profile.
- * Applies the fallback chain if the tier is not found in the profile.
- *
- * @param {string} tier - One of MODEL_TIERS
- * @param {string|Record<string, string>} profile - Profile name ('max', 'pro') or custom mapping
- * @returns {string} Concrete model ID (e.g., 'claude-opus-4-6')
- * @throws {Error} If no model can be resolved after exhausting the fallback chain
- */
-export function resolveModel(tier, profile) {
-  const profileMap = typeof profile === 'string'
-    ? DEFAULT_MODEL_PROFILES[profile]
-    : profile;
-
-  if (!profileMap) {
-    throw new Error(`Unknown profile: "${profile}". Available: ${Object.keys(DEFAULT_MODEL_PROFILES).join(', ')}`);
-  }
-
-  let currentTier = tier;
-  const visited = new Set();
-
-  while (currentTier) {
-    if (visited.has(currentTier)) {
-      break;
-    }
-    visited.add(currentTier);
-
-    if (profileMap[currentTier]) {
-      return profileMap[currentTier];
-    }
-
-    currentTier = FALLBACK_CHAIN[currentTier];
-  }
-
-  throw new Error(`Cannot resolve model for tier "${tier}": no model available in profile after fallback chain`);
-}
-
-/**
- * Extracts dispatch configuration from skill markdown content.
- * Precedence: workflow steps (frontmatter) > null (legacy prose).
- *
- * Dependency direction: dispatch.js imports from workflow-parser.js.
- * Do not reverse this — workflow-parser.js must not import from dispatch.js.
- *
- * @param {string} skillMarkdown - Raw SKILL.md content
- * @returns {{ source: 'workflow', steps: Array<object> } | { source: null }}
- * @throws {Error} If YAML frontmatter is malformed (propagated from parseSkill)
- */
-export function extractDispatchConfigs(skillMarkdown) {
-  if (!skillMarkdown) {
-    return { source: null };
-  }
-
-  const skill = parseSkill(skillMarkdown);
-
-  if (skill.workflow && Array.isArray(skill.workflow.steps) && skill.workflow.steps.length > 0) {
-    return {
-      source: 'workflow',
-      steps: skill.workflow.steps,
-    };
-  }
-
-  return { source: null };
-}

package/src/utils/executor.js

@@ -1,293 +0,0 @@
-/**
- * executor.js — Execution loop for Guild workflow plans.
- *
- * Drives a plan to completion by iterating through steps, dispatching
- * agent steps to a provider function and system steps to local commands.
- * Supports parallel execution (v1.2) and delegation to sub-skills.
- */
-
-import { execFile } from 'child_process';
-import {
-  advanceStep,
-  getNextSteps,
-  isPlanComplete,
-  MAX_DELEGATION_DEPTH,
-  createExecutionPlan,
-} from './orchestrator.js';
-import {
-  buildStepContext,
-  recordStepTrace,
-  loadWorkflow,
-  resolveStepDispatch,
-} from './orchestrator-io.js';
-
-const SYSTEM_STEP_TIMEOUT = 120_000; // 2 minutes
-
-/**
- * Promisified execFile wrapper that always resolves (never rejects).
- *
- * @param {string} cmd - Command to execute
- * @param {string[]} args - Arguments
- * @param {object} opts - execFile options
- * @returns {Promise<{ stdout: string, stderr: string, exitCode: number }>}
- */
-function execFileAsync(cmd, args, opts) {
-  return new Promise((resolve) => {
-    execFile(cmd, args, opts, (error, stdout, stderr) => {
-      resolve({
-        stdout: stdout || '',
-        stderr: stderr || (error && error.message) || '',
-        exitCode: error ? (typeof error.code === 'number' ? error.code : 1) : 0,
-      });
-    });
-  });
-}
-
-/**
- * Executes a system step by running its commands or handling delegation.
- *
- * @param {object} step - System step definition
- * @param {object} [options={}] - Options
- * @param {string} [options.projectRoot=process.cwd()] - Working directory for commands
- * @returns {Promise<{ status: string, output: string }>}
- */
-async function executeSystemStep(step, options = {}) {
-  const { projectRoot = process.cwd() } = options;
-
-  if (step.commands && step.commands.length > 0) {
-    const outputs = [];
-    for (const cmd of step.commands) {
-      // v1.1: simple split — commands with quoted args or shell features
-      // are not supported. Use simple commands like "npm test".
-      const [bin, ...args] = cmd.split(' ');
-      const result = await execFileAsync(bin, args, {
-        cwd: projectRoot,
-        timeout: SYSTEM_STEP_TIMEOUT,
-      });
-
-      if (result.exitCode !== 0) {
-        return {
-          status: 'failed',
-          output: result.stderr || result.stdout || `Command failed: ${cmd}`,
-        };
-      }
-      outputs.push(result.stdout);
-    }
-    return { status: 'passed', output: outputs.join('\n') };
-  }
-
-  if (step.delegatesTo) {
-    return { status: 'passed', output: `System step with delegation — handled by executeDelegation` };
-  }
-
-  return { status: 'passed', output: 'System step completed' };
-}
-
-/**
- * Finds a step definition by ID across all groups in a plan.
- *
- * @param {object} plan - Execution plan
- * @param {string} stepId - Step ID to find
- * @returns {object|null}
- */
-function findStepInPlan(plan, stepId) {
-  for (const group of plan.groups) {
-    for (const step of group.steps) {
-      if (step.id === stepId) return step;
-    }
-  }
-  return null;
-}
-
-/**
- * Dispatches a single step (agent or system) and returns its result.
- *
- * @param {object} step - Step definition
- * @param {object} dispatch - Dispatch info for this step
- * @param {object} context - Execution context
- * @param {import('./orchestrator.js').ExecutionPlan} context.currentPlan - Current plan state
- * @param {Function} context.provider - Agent step provider
- * @param {string} context.projectRoot - Working directory
- * @param {string} context.skillBody - Skill body text
- * @param {object} context.executeOptions - Full options passed to execute()
- * @returns {Promise<{ status: string, output: string, outcome?: object, error?: string }>}
- */
-async function dispatchStep(step, dispatch, context) {
-  const { currentPlan, provider, projectRoot, skillBody, executeOptions } = context;
-
-  if (step.role === 'system' && step.delegatesTo) {
-    return executeDelegation(step, executeOptions);
-  }
-
-  if (step.role === 'system') {
-    return executeSystemStep(step, { projectRoot });
-  }
-
-  const stepContext = buildStepContext(step, currentPlan, { skillBody });
-  return provider(step, dispatch, stepContext);
-}
-
-/**
- * Executes a delegation step by loading and running the sub-skill.
- *
- * @param {object} step - Delegation step (with delegatesTo field)
- * @param {object} options - Execute options from parent
- * @returns {Promise<{ status: string, output: string, error?: string }>}
- */
-async function executeDelegation(step, options) {
-  const {
-    provider,
-    trace,
-    projectRoot,
-    profile = 'max',
-    onStepStart,
-    onStepEnd,
-    delegationDepth = 0,
-  } = options;
-
-  if (delegationDepth >= MAX_DELEGATION_DEPTH) {
-    return {
-      status: 'failed',
-      output: '',
-      error: `Delegation depth limit (${MAX_DELEGATION_DEPTH}) exceeded at step "${step.id}" delegating to "${step.delegatesTo}"`,
-    };
-  }
-
-  let subSkill;
-  try {
-    subSkill = loadWorkflow(step.delegatesTo);
-  } catch (err) {
-    return {
-      status: 'failed',
-      output: '',
-      error: `Failed to load delegated skill "${step.delegatesTo}": ${err.message}`,
-    };
-  }
-
-  const subPlan = createExecutionPlan(subSkill.workflow, {
-    skillName: subSkill.name || step.delegatesTo,
-  });
-
-  const subDispatchMap = {};
-  for (const group of subPlan.groups) {
-    for (const s of group.steps) {
-      subDispatchMap[s.id] = resolveStepDispatch(s, { profile, projectRoot });
-    }
-  }
-
-  const finalSubPlan = await execute(subPlan, subDispatchMap, {
-    provider,
-    trace,
-    projectRoot,
-    skillBody: subSkill.body || '',
-    onStepStart,
-    onStepEnd,
-    delegationDepth: delegationDepth + 1,
-    profile,
-  });
-
-  if (finalSubPlan.status === 'completed') {
-    return { status: 'passed', output: `Delegation to "${step.delegatesTo}" completed` };
-  }
-
-  return {
-    status: 'failed',
-    output: '',
-    error: `Delegated skill "${step.delegatesTo}" ended with status: ${finalSubPlan.status}`,
-  };
-}
-
-/**
- * Executes a workflow plan to completion.
- *
- * Drives the orchestrator state machine by repeatedly calling getNextSteps,
- * dispatching each step (agent via provider, system via local commands),
- * and advancing the plan with the result. Parallel groups are dispatched
- * concurrently via Promise.all.
- *
- * @param {import('./orchestrator.js').ExecutionPlan} plan - Initial execution plan
- * @param {Object.<string, import('./orchestrator-io.js').StepDispatchInfo>} dispatchInfoMap - Dispatch info per step
- * @param {object} [options={}] - Options
- * @param {Function} options.provider - Agent step provider: (step, dispatch, context) => { status, output, outcome?, error?, tokens? }
- * @param {object} [options.trace] - Trace context for recording step executions
- * @param {string} [options.projectRoot] - Working directory for system commands
- * @param {string} [options.skillBody=''] - Skill body text for context building
- * @param {Function} [options.onStepStart] - Callback before each step: (step, dispatch) => void
- * @param {Function} [options.onStepEnd] - Callback after each step: (step, result) => void
- * @param {number} [options.delegationDepth=0] - Current delegation nesting depth
- * @param {string} [options.profile='max'] - Model profile for delegation dispatch
- * @returns {Promise<import('./orchestrator.js').ExecutionPlan>} Final plan state
- */
-export async function execute(plan, dispatchInfoMap, options = {}) {
-  const {
-    provider,
-    trace,
-    projectRoot,
-    skillBody = '',
-    onStepStart,
-    onStepEnd,
-  } = options;
-
-  let currentPlan = plan;
-  let emptyIterations = 0;
-  const MAX_EMPTY_ITERATIONS = 100;
-
-  while (!isPlanComplete(currentPlan)) {
-    const { steps, skipped } = getNextSteps(currentPlan);
-
-    for (const stepId of skipped) {
-      currentPlan = advanceStep(currentPlan, stepId, { status: 'skipped' });
-
-      if (trace) {
-        const step = findStepInPlan(currentPlan, stepId);
-        const dispatch = dispatchInfoMap[stepId] || {};
-        if (step) {
-          recordStepTrace(trace, step, currentPlan.stepStates[stepId], dispatch);
-        }
-      }
-    }
-
-    if (steps.length === 0) {
-      if (isPlanComplete(currentPlan)) break;
-      if (++emptyIterations > MAX_EMPTY_ITERATIONS) {
-        currentPlan = { ...currentPlan, status: 'aborted' };
-        break;
-      }
-      continue;
-    }
-    emptyIterations = 0;
-
-    const dispatchContext = {
-      currentPlan,
-      provider,
-      projectRoot,
-      skillBody,
-      executeOptions: options,
-    };
-
-    const settled = await Promise.all(
-      steps.map(async (step) => {
-        const dispatch = dispatchInfoMap[step.id] || {};
-        onStepStart?.(step, dispatch);
-        const result = await dispatchStep(step, dispatch, dispatchContext);
-        return { step, dispatch, result };
-      })
-    );
-
-    for (const { step, dispatch, result } of settled) {
-      currentPlan = advanceStep(currentPlan, step.id, result);
-
-      if (trace) {
-        recordStepTrace(trace, step, currentPlan.stepStates[step.id], dispatch);
-      }
-
-      onStepEnd?.(step, result);
-    }
-  }
-
-  if (currentPlan.status === 'running' && isPlanComplete(currentPlan)) {
-    currentPlan = { ...currentPlan, status: 'completed' };
-  }
-
-  return currentPlan;
-}

package/src/utils/learnings-io.js

@@ -1,76 +0,0 @@
-/**
- * learnings-io.js — File I/O operations for compound learnings.
- *
- * Read, write, init, exists, and delete operations for .claude/guild/learnings.md.
- * Separated from the pure functions in learnings.js following the trace.js pattern.
- *
- * NOTE: File locking for concurrent access is intentionally omitted.
- * Concurrent workflow execution is a v2 concern — current Guild workflows
- * are single-session and sequential.
- */
-
-import { readFileSync, writeFileSync, existsSync, unlinkSync, mkdirSync } from 'fs';
-import { dirname } from 'path';
-import { GUILD_LEARNINGS_PATH, renderEmptyLearnings } from './learnings.js';
-
-/**
- * Reads the learnings file from disk.
- * Returns the raw content as a string, or null if the file does not exist.
- * @param {string} [filePath] - Override path (default: GUILD_LEARNINGS_PATH)
- * @returns {string | null}
- */
-export function readLearnings(filePath) {
-  const target = filePath || GUILD_LEARNINGS_PATH;
-  if (!existsSync(target)) return null;
-  return readFileSync(target, 'utf8');
-}
-
-/**
- * Writes content to the learnings file.
- * Creates parent directories if needed.
- * @param {string} content - Markdown content to write
- * @param {string} [filePath] - Override path (default: GUILD_LEARNINGS_PATH)
- */
-export function writeLearnings(content, filePath) {
-  const target = filePath || GUILD_LEARNINGS_PATH;
-  mkdirSync(dirname(target), { recursive: true });
-  writeFileSync(target, content, 'utf8');
-}
-
-/**
- * Checks whether the learnings file exists on disk.
- * @param {string} [filePath] - Override path (default: GUILD_LEARNINGS_PATH)
- * @returns {boolean}
- */
-export function learningsExist(filePath) {
-  const target = filePath || GUILD_LEARNINGS_PATH;
-  return existsSync(target);
-}
-
-/**
- * Initializes the learnings file with empty scaffold content.
- * No-ops if the file already exists.
- * @param {string} [projectName='Project'] - Project name for the header
- * @param {string} [filePath] - Override path (default: GUILD_LEARNINGS_PATH)
- * @returns {{ created: boolean }}
- */
-export function initLearnings(projectName = 'Project', filePath) {
-  const target = filePath || GUILD_LEARNINGS_PATH;
-  if (existsSync(target)) return { created: false };
-  mkdirSync(dirname(target), { recursive: true });
-  writeFileSync(target, renderEmptyLearnings(projectName), 'utf8');
-  return { created: true };
-}
-
-/**
- * Deletes the learnings file from disk.
- * Returns { deleted: false } if the file does not exist (no throw).
- * @param {string} [filePath] - Override path (default: GUILD_LEARNINGS_PATH)
- * @returns {{ deleted: boolean }}
- */
-export function deleteLearnings(filePath) {
-  const target = filePath || GUILD_LEARNINGS_PATH;
-  if (!existsSync(target)) return { deleted: false };
-  unlinkSync(target);
-  return { deleted: true };
-}