guild-agents 0.3.1 → 1.1.0

package/src/utils/learnings.js

@@ -0,0 +1,204 @@
+/**
+ * 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');
+}

package/src/utils/orchestrator-io.js

@@ -0,0 +1,356 @@
+/**
+ * orchestrator-io.js — I/O layer for the Guild runtime orchestrator.
+ *
+ * Handles file I/O, skill loading, dispatch resolution, learnings injection,
+ * and trace management. Depends on the pure orchestrator.js for plan logic.
+ *
+ * Re-exports all public functions from orchestrator.js for a single import point.
+ */
+
+import { join } from 'path';
+import { loadSkill } from './skill-loader.js';
+import { resolveAgentMetadata, resolveEffectiveTier, resolveModel } from './dispatch.js';
+import { createTrace, recordStep, finalizeTrace } from './trace.js';
+import { buildContextInjection } from './learnings.js';
+import { readLearnings } from './learnings-io.js';
+import {
+  createExecutionPlan,
+  advanceStep,
+  getNextSteps,
+  isPlanComplete,
+  parseCondition,
+  evaluateCondition,
+  shouldRetry,
+  resolveFailureTarget,
+  expandDelegation,
+} from './orchestrator.js';
+
+// Re-export all public functions from orchestrator.js
+export {
+  createExecutionPlan,
+  advanceStep,
+  getNextSteps,
+  isPlanComplete,
+  parseCondition,
+  evaluateCondition,
+  shouldRetry,
+  resolveFailureTarget,
+  expandDelegation,
+};
+
+// Also re-export constants
+export { DEFAULT_CIRCUIT_BREAKER_LIMIT, MAX_DELEGATION_DEPTH } from './orchestrator.js';
+
+/**
+ * @typedef {Object} StepDispatchInfo
+ * @property {'system'|'agent'} role - Whether this is a system or agent step
+ * @property {string|null} tier - Resolved model tier (null for system steps)
+ * @property {string|null} model - Resolved concrete model ID (null for system steps)
+ * @property {boolean} fallback - Whether a fallback model was used
+ * @property {object|null} agentMetadata - Agent frontmatter metadata (null for system steps)
+ */
+
+/**
+ * Resolves dispatch information for a workflow step.
+ * System role steps return minimal dispatch info (no model).
+ * Agent steps resolve tier and model using the dispatch utilities.
+ *
+ * @param {object} step - Workflow step definition
+ * @param {object} [options={}] - Options
+ * @param {string} [options.profile='max'] - Model profile name
+ * @param {string} [options.projectRoot=process.cwd()] - Project root for agent lookup
+ * @returns {StepDispatchInfo}
+ */
+export function resolveStepDispatch(step, options = {}) {
+  const { profile = 'max', projectRoot = process.cwd() } = options;
+
+  if (step.role === 'system') {
+    return {
+      role: 'system',
+      tier: null,
+      model: null,
+      fallback: false,
+      agentMetadata: null,
+    };
+  }
+
+  const agentMetadata = resolveAgentMetadata(step.role, projectRoot);
+
+  // Build a step config object compatible with resolveEffectiveTier
+  const stepConfig = {
+    role: step.role,
+    'model-tier': step.modelTier,
+  };
+
+  const tier = resolveEffectiveTier(stepConfig, agentMetadata);
+
+  // W4: resolveModel already handles the fallback chain internally;
+  // a single try-catch is sufficient here.
+  let model;
+  let fallback;
+
+  try {
+    model = resolveModel(tier, profile);
+    fallback = false;
+  } catch {
+    model = null;
+    fallback = false;
+  }
+
+  return {
+    role: 'agent',
+    tier,
+    model,
+    fallback,
+    agentMetadata,
+  };
+}
+
+/**
+ * Loads and validates a skill workflow from disk.
+ *
+ * @param {string} skillName - Name of the skill directory
+ * @param {object} [options={}] - Options
+ * @param {string} [options.basePath] - Override base path for skills directory
+ * @returns {{ workflow: object, body: string, name: string }}
+ * @throws {Error} If skill not found, has no workflow, or has validation errors
+ */
+export function loadWorkflow(skillName, options = {}) {
+  const skill = options.basePath
+    ? loadSkill(skillName, options.basePath)
+    : loadSkill(skillName);
+
+  if (!skill.workflow) {
+    throw new Error(
+      `Skill "${skillName}" has no workflow definition. Only skills with a workflow block can be orchestrated.`
+    );
+  }
+
+  if (skill.errors && skill.errors.length > 0) {
+    throw new Error(
+      `Skill "${skillName}" has workflow validation errors:\n${skill.errors.join('\n')}`
+    );
+  }
+
+  return {
+    workflow: skill.workflow,
+    body: skill.body,
+    name: skill.name || skillName,
+  };
+}
+
+/**
+ * Builds the context string for a step's execution.
+ * Combines step intent, learnings injection, skill body, and required step outcomes.
+ *
+ * @param {object} step - Workflow step definition
+ * @param {import('./orchestrator.js').ExecutionPlan} plan - Current execution plan
+ * @param {object} [options={}] - Options
+ * @param {string} [options.learningsPath] - Override path for learnings file
+ * @param {string} [options.skillBody=''] - Skill body (markdown prose)
+ * @returns {string} Context string for the step
+ */
+export function buildStepContext(step, plan, options = {}) {
+  const { skillBody = '' } = options;
+  const parts = [];
+
+  // Step intent
+  parts.push(`## Task: ${step.intent}`);
+  parts.push('');
+
+  // Learnings injection (graceful degradation if reading fails)
+  try {
+    const learningsContent = readLearnings(options.learningsPath || undefined);
+    if (learningsContent) {
+      const injection = buildContextInjection(learningsContent);
+      if (injection) {
+        parts.push(injection);
+        parts.push('');
+      }
+    }
+  } catch {
+    // Learnings reading failed — continue without them
+  }
+
+  // Skill body (prose instructions)
+  if (skillBody && skillBody.trim()) {
+    parts.push('## Skill Instructions');
+    parts.push('');
+    parts.push(skillBody.trim());
+    parts.push('');
+  }
+
+  // Outcomes from required steps
+  if (step.requires && step.requires.length > 0) {
+    const requiredOutcomes = [];
+    for (const requirement of step.requires) {
+      // Find which step produces this requirement
+      for (const group of plan.groups) {
+        for (const s of group.steps) {
+          const state = plan.stepStates[s.id];
+          if (state && state.outcome && s.produces && s.produces.includes(requirement)) {
+            if (state.outcome[requirement] !== undefined) {
+              requiredOutcomes.push({ field: requirement, value: state.outcome[requirement], fromStep: s.id });
+            }
+          }
+        }
+      }
+    }
+
+    if (requiredOutcomes.length > 0) {
+      parts.push('## Inputs from previous steps');
+      parts.push('');
+      for (const item of requiredOutcomes) {
+        parts.push(`### ${item.field} (from step: ${item.fromStep})`);
+        parts.push('');
+        parts.push(String(item.value));
+        parts.push('');
+      }
+    }
+  }
+
+  return parts.join('\n').trimEnd();
+}
+
+/**
+ * Records a step execution in the trace context.
+ *
+ * @param {import('./trace.js').TraceContext} traceCtx - Active trace context
+ * @param {object} step - Step definition
+ * @param {import('./orchestrator.js').StepState} stepState - Final state of the step
+ * @param {StepDispatchInfo} dispatchInfo - Resolved dispatch information
+ * @returns {import('./trace.js').TraceContext} Updated trace context (same reference)
+ */
+export function recordStepTrace(traceCtx, step, stepState, dispatchInfo) {
+  const started = new Date().toISOString();
+
+  return recordStep(traceCtx, {
+    role: step.role,
+    intent: step.intent,
+    tier: dispatchInfo.tier || 'system',
+    model: dispatchInfo.model || 'none',
+    fallback: dispatchInfo.fallback,
+    started,
+    // TODO(v2): capture actual wall-clock duration and token usage from step executor
+    duration: 0,
+    tokens: 0,
+    result: stepState.status === 'passed' ? 'pass' : stepState.status === 'skipped' ? 'skip' : 'fail',
+  });
+}
+
+/**
+ * Finalizes a workflow trace and produces an execution summary.
+ *
+ * testsPass and lintPass are derived from gate steps whose intent contains
+ * the keywords "test" or "lint" respectively. They can be overridden via
+ * options when the caller has better information.
+ *
+ * @param {import('./trace.js').TraceContext} traceCtx - Completed trace context
+ * @param {import('./orchestrator.js').ExecutionPlan} plan - Final execution plan
+ * @param {object} [options={}] - Optional overrides
+ * @param {boolean} [options.testsPass] - Override for testsPass (derived from gate steps if omitted)
+ * @param {boolean} [options.lintPass] - Override for lintPass (derived from gate steps if omitted)
+ * @returns {{ trace: object, executionSummary: string }}
+ */
+export function finalizeWorkflowTrace(traceCtx, plan, options = {}) {
+  const allStates = Object.values(plan.stepStates);
+  const anyFailed = allStates.some(s => s.status === 'failed');
+
+  // Derive testsPass / lintPass from gate steps when not explicitly provided
+  let testsPass = options.testsPass;
+  let lintPass = options.lintPass;
+
+  if (testsPass === undefined || lintPass === undefined) {
+    for (const group of plan.groups) {
+      for (const step of group.steps) {
+        if (!step.gate) continue;
+        const state = plan.stepStates[step.id];
+        const passed = state && state.status === 'passed';
+        const intent = (step.intent || '').toLowerCase();
+        if (testsPass === undefined && intent.includes('test')) {
+          testsPass = passed;
+        }
+        if (lintPass === undefined && intent.includes('lint')) {
+          lintPass = passed;
+        }
+      }
+    }
+    // Fall back to true when no matching gate step found (v1 behaviour)
+    if (testsPass === undefined) testsPass = true;
+    if (lintPass === undefined) lintPass = true;
+  }
+
+  const summary = {
+    result: anyFailed || plan.status === 'aborted' || plan.status === 'circuit-breaker' ? 'fail' : 'pass',
+    testsPass,
+    lintPass,
+  };
+
+  const trace = finalizeTrace(traceCtx, summary);
+
+  return {
+    trace,
+    executionSummary: trace.executionSummary,
+  };
+}
+
+/**
+ * Main entry point for the orchestrator.
+ * Loads the workflow, creates an execution plan, resolves dispatch for all steps,
+ * and creates a trace context. In v1, this produces the plan only (no step execution).
+ *
+ * @param {string} skillName - Name of the skill to orchestrate
+ * @param {string} [input=''] - User input / feature description
+ * @param {object} [options={}] - Options
+ * @param {string} [options.profile='max'] - Model profile
+ * @param {string} [options.projectRoot=process.cwd()] - Project root
+ * @param {string} [options.basePath] - Override skills base path
+ * @param {string} [options.tracesDir] - Override traces directory
+ * @param {string} [options.traceLevel='default'] - Trace level
+ * @param {number} [options.circuitBreakerLimit] - Override circuit breaker limit
+ * @returns {Promise<{
+ *   plan: import('./orchestrator.js').ExecutionPlan,
+ *   trace: import('./trace.js').TraceContext,
+ *   dispatchInfoMap: Object.<string, StepDispatchInfo>,
+ *   input: string
+ * }>}
+ */
+export async function orchestrate(skillName, input = '', options = {}) {
+  const {
+    profile = 'max',
+    projectRoot = process.cwd(),
+    tracesDir,
+    traceLevel = 'default',
+    circuitBreakerLimit,
+  } = options;
+
+  // Load workflow
+  const loadOpts = {};
+  if (options.basePath) {
+    loadOpts.basePath = options.basePath;
+  }
+
+  const { workflow, name } = loadWorkflow(skillName, loadOpts);
+
+  // Create execution plan
+  const planOptions = { skillName: name || skillName };
+  if (circuitBreakerLimit !== undefined) {
+    planOptions.circuitBreakerLimit = circuitBreakerLimit;
+  }
+  const plan = createExecutionPlan(workflow, planOptions);
+
+  // Resolve dispatch info for all steps (for plan introspection/display)
+  const dispatchInfoMap = {};
+  for (const group of plan.groups) {
+    for (const step of group.steps) {
+      dispatchInfoMap[step.id] = resolveStepDispatch(step, { profile, projectRoot });
+    }
+  }
+
+  // W8: return dispatchInfoMap and input as separate result fields instead of
+  // mutating traceCtx, keeping the trace context pure.
+  const traceDirResolved = tracesDir || join(projectRoot, '.claude', 'guild', 'traces');
+  const traceCtx = createTrace(skillName, traceLevel, traceDirResolved);
+
+  return { plan, trace: traceCtx, dispatchInfoMap, input };
+}