guild-agents 1.4.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,183 +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.
- * Sequential execution only (v1.1); parallel groups deferred to v1.2.
- */
-
-import { execFile } from 'child_process';
-import {
-  advanceStep,
-  getNextSteps,
-  isPlanComplete,
-} from './orchestrator.js';
-import { buildStepContext, recordStepTrace } 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: `Delegation to "${step.delegatesTo}" skipped (v1.1)` };
-  }
-
-  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;
-}
-
-/**
- * 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.
- *
- * @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
- * @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);
-
-    // Advance skipped steps first
-    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 no executable steps remain, check completion again
-    if (steps.length === 0) {
-      if (isPlanComplete(currentPlan)) break;
-      if (++emptyIterations > MAX_EMPTY_ITERATIONS) {
-        currentPlan = { ...currentPlan, status: 'aborted' };
-        break;
-      }
-      continue;
-    }
-    emptyIterations = 0;
-
-    // v1.1: sequential execution — one step at a time
-    const step = steps[0];
-    const dispatch = dispatchInfoMap[step.id] || {};
-
-    onStepStart?.(step, dispatch);
-
-    let result;
-    if (step.role === 'system') {
-      result = await executeSystemStep(step, { projectRoot });
-    } else {
-      const context = buildStepContext(step, currentPlan, { skillBody });
-      result = await provider(step, dispatch, context);
-    }
-
-    currentPlan = advanceStep(currentPlan, step.id, result);
-
-    if (trace) {
-      recordStepTrace(trace, step, currentPlan.stepStates[step.id], dispatch);
-    }
-
-    onStepEnd?.(step, result);
-  }
-
-  // Mark plan as completed if all steps reached terminal state and plan is still running
-  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 };
-}

package/src/utils/learnings.js

@@ -1,204 +0,0 @@
-/**
- * learnings.js — Pure functions for compound learning.
- *
- * Constants, parsing, rendering, token estimation, and context injection.
- * Zero I/O, zero external dependencies — leaf module.
- */
-
-/** Fixed section names for the learnings file (spec section 3.3). */
-export const LEARNINGS_SECTIONS = [
-  'Project Patterns',
-  'Architecture Decisions',
-  'Past Issues & Resolutions',
-  'User Preferences',
-  'Agent Notes',
-];
-
-/** Maximum token budget for the learnings file. */
-export const TOKEN_BUDGET = 2000;
-
-/** Default path to the learnings file, relative to project root. */
-export const GUILD_LEARNINGS_PATH = '.claude/guild/learnings.md';
-
-/**
- * Estimates token count from text using a word-count heuristic.
- * Approximation: tokens ≈ ceil(words × 1.35).
- * @param {string | null | undefined} text
- * @returns {number}
- */
-export function estimateTokens(text) {
-  if (!text || !text.trim()) return 0;
-  const words = text.trim().split(/\s+/).length;
-  return Math.ceil(words * 1.35);
-}
-
-/**
- * Returns true if the estimated token count is within the budget.
- * @param {string | null | undefined} text
- * @param {number} [budget=TOKEN_BUDGET]
- * @returns {boolean}
- */
-export function isWithinBudget(text, budget = TOKEN_BUDGET) {
-  return estimateTokens(text) <= budget;
-}
-
-/**
- * Renders the initial/empty learnings file content.
- * @param {string} [projectName='Project']
- * @returns {string}
- */
-export function renderEmptyLearnings(projectName = 'Project') {
-  const lines = [];
-  lines.push(`# Guild Learnings — ${projectName}`);
-  lines.push('');
-  lines.push(`> Auto-generated by Guild. Last updated: ${new Date().toISOString()}`);
-  lines.push('> Total executions: 0');
-  lines.push('> Token budget: this file should stay under 2000 tokens');
-  lines.push('');
-
-  for (const section of LEARNINGS_SECTIONS) {
-    lines.push(`## ${section}`);
-    lines.push('');
-    lines.push('_No learnings yet._');
-    lines.push('');
-  }
-
-  return lines.join('\n');
-}
-
-const PLACEHOLDER_RE = /^_No learnings yet\._$/;
-const ENTRY_RE = /^- (.+)$/;
-const DISCOVERED_RE = /\(discovered: ([^)]+)\)/;
-
-/**
- * Parses a learnings.md file into a structured object.
- * @param {string | null | undefined} content
- * @returns {{ header: { project: string, lastUpdated: string, totalExecutions: number }, sections: Record<string, Array<{ text: string, discovered: string }>> }}
- */
-export function parseLearnings(content) {
-  const empty = {
-    header: { project: '', lastUpdated: '', totalExecutions: 0 },
-    sections: {},
-  };
-  for (const s of LEARNINGS_SECTIONS) empty.sections[s] = [];
-
-  if (!content || !content.trim()) return empty;
-
-  const lines = content.split('\n');
-  const result = { header: { project: '', lastUpdated: '', totalExecutions: 0 }, sections: {} };
-  for (const s of LEARNINGS_SECTIONS) result.sections[s] = [];
-
-  let currentSection = null;
-
-  for (const line of lines) {
-    // Parse H1 header
-    const h1Match = line.match(/^# Guild Learnings — (.+)$/);
-    if (h1Match) {
-      result.header.project = h1Match[1].trim();
-      continue;
-    }
-
-    // Parse header metadata
-    const updatedMatch = line.match(/^> Auto-generated by Guild\. Last updated: (.+)$/);
-    if (updatedMatch) {
-      result.header.lastUpdated = updatedMatch[1].trim();
-      continue;
-    }
-    const execMatch = line.match(/^> Total executions: (\d+)$/);
-    if (execMatch) {
-      result.header.totalExecutions = parseInt(execMatch[1], 10);
-      continue;
-    }
-
-    // Parse section headers
-    const h2Match = line.match(/^## (.+)$/);
-    if (h2Match) {
-      const sectionName = h2Match[1].trim();
-      if (LEARNINGS_SECTIONS.includes(sectionName)) {
-        currentSection = sectionName;
-      } else {
-        currentSection = null;
-      }
-      continue;
-    }
-
-    // Skip placeholders and blank lines
-    if (!currentSection) continue;
-    if (PLACEHOLDER_RE.test(line.trim())) continue;
-    if (!line.trim()) continue;
-
-    // Parse entries (lines starting with "- ")
-    const entryMatch = line.match(ENTRY_RE);
-    if (entryMatch) {
-      const text = entryMatch[1].trim();
-      const discoveredMatch = text.match(DISCOVERED_RE);
-      result.sections[currentSection].push({
-        text,
-        discovered: discoveredMatch ? discoveredMatch[1] : '',
-      });
-    }
-  }
-
-  return result;
-}
-
-/**
- * Renders a parsed learnings structure back to markdown.
- * @param {{ header: { project: string, lastUpdated: string, totalExecutions: number }, sections: Record<string, Array<{ text: string, discovered: string }>> }} parsed
- * @returns {string}
- */
-export function renderLearnings(parsed) {
-  const lines = [];
-  const project = parsed.header.project || 'Project';
-  const lastUpdated = parsed.header.lastUpdated || new Date().toISOString();
-  const totalExecutions = parsed.header.totalExecutions || 0;
-
-  lines.push(`# Guild Learnings — ${project}`);
-  lines.push('');
-  lines.push(`> Auto-generated by Guild. Last updated: ${lastUpdated}`);
-  lines.push(`> Total executions: ${totalExecutions}`);
-  lines.push('> Token budget: this file should stay under 2000 tokens');
-  lines.push('');
-
-  for (const section of LEARNINGS_SECTIONS) {
-    lines.push(`## ${section}`);
-    lines.push('');
-    const entries = parsed.sections[section] || [];
-    if (entries.length === 0) {
-      lines.push('_No learnings yet._');
-    } else {
-      for (const entry of entries) {
-        lines.push(`- ${entry.text}`);
-      }
-    }
-    lines.push('');
-  }
-
-  return lines.join('\n');
-}
-
-/**
- * Builds a context injection string from raw learnings content.
- * Wraps in <guild-learnings> tags per spec section 4.2.
- * Returns empty string for null/empty input.
- * @param {string | null | undefined} content
- * @returns {string}
- */
-export function buildContextInjection(content) {
-  if (!content || !content.trim()) return '';
-
-  const parsed = parseLearnings(content);
-  const hasEntries = LEARNINGS_SECTIONS.some(s => (parsed.sections[s] || []).length > 0);
-  if (!hasEntries) return '';
-
-  const lines = [];
-  lines.push('<guild-learnings>');
-  lines.push(content.trim());
-  lines.push('</guild-learnings>');
-  lines.push('');
-  lines.push('These are accumulated learnings from previous Guild executions on this project.');
-  lines.push('Use them to inform your work. Do not contradict established patterns unless');
-  lines.push('explicitly asked to change them.');
-
-  return lines.join('\n');
-}