cognitive-core 0.0.2 → 0.1.2

package/src/search/index.ts

@@ -0,0 +1,68 @@
+export {
+  TaskRouter,
+  createRouter,
+  type RoutingDecision,
+} from './router.js';
+
+export {
+  DirectSolver,
+  createSolver,
+  type SolverConfig,
+  type SolverResult,
+} from './solver.js';
+
+// Refinement types
+export {
+  type EvaluationResult,
+  type EvaluationIssue,
+  type EvaluationMethod,
+  type QualityLevel,
+  type FailureContext,
+  type RefinementResult,
+  type IssueType,
+  type IssueSeverity,
+  createEvaluationResult,
+  scoreToQuality,
+  isQualityAcceptable,
+  EvaluationResultSchema,
+  EvaluationIssueSchema,
+  QualityLevelSchema,
+  IssueSeveritySchema,
+  IssueTypeSchema,
+  EvaluationMethodSchema,
+} from './refinement-types.js';
+
+// Solution evaluator
+export {
+  SolutionEvaluator,
+  createSolutionEvaluator,
+  type EvaluatorConfig,
+  type VerificationFunction,
+  type VerificationResult,
+} from './evaluator.js';
+
+// Refinement loop
+export {
+  RefinementLoop,
+  createRefinementLoop,
+  type RefinementLoopConfig,
+} from './refinement-loop.js';
+
+// Team routing
+export {
+  TeamRouter,
+  createTeamRouter,
+  type TeamRouterConfig,
+  type TeamRecommendation,
+  type TeamRecommendationInput,
+} from './team-router.js';
+
+// Verification runner
+export {
+  VerificationRunner,
+  createVerificationRunner,
+  TestRunners,
+  type CommandVerificationConfig,
+  type CommandResult,
+  type VerificationIssue,
+} from './verification-runner.js';

package/src/search/refinement-loop.ts

@@ -0,0 +1,457 @@
+/**
+ * Refinement Loop
+ *
+ * Implements ReMem-style iterative refinement that improves solutions
+ * using memory-augmented feedback. The loop:
+ * 1. Evaluates solution quality
+ * 2. If not acceptable, injects failure context and retries
+ * 3. Continues until acceptable or max iterations reached
+ */
+
+import type { Task } from '../types/task.js';
+import type { Trajectory } from '../types/trajectory.js';
+import type { AgentManager } from '../runtime/manager.js';
+import type { MemorySystem, MemoryQueryResultV2 } from '../memory/system.js';
+import type { AgentSpawnConfig } from '../runtime/types.js';
+import type { AgenticTaskRunner } from '../workspace/runner.js';
+import { refinementAnalysisTemplate, type RefinementPlan } from '../workspace/templates/refinement-analysis.js';
+import {
+  type RefinementResult,
+  type EvaluationResult,
+  type FailureContext,
+} from './refinement-types.js';
+import { SolutionEvaluator, type EvaluatorConfig } from './evaluator.js';
+
+/**
+ * Configuration for the refinement loop
+ */
+export interface RefinementLoopConfig {
+  /** Maximum number of refinement iterations (default: 3) */
+  maxIterations?: number;
+  /** Minimum acceptable quality score (default: 0.7) */
+  minAcceptableScore?: number;
+  /** Whether to inject previous failure context (default: true) */
+  injectFailureContext?: boolean;
+  /** Whether to query memory for similar failures (default: true) */
+  queryFailureMemory?: boolean;
+  /** Evaluator configuration */
+  evaluatorConfig?: EvaluatorConfig;
+  /** Task strategies that should trigger refinement */
+  triggerOnStrategies?: Array<'direct' | 'adapt' | 'explore' | 'fallback'>;
+  /** Minimum confidence to skip refinement */
+  confidenceThreshold?: number;
+}
+
+/**
+ * Default refinement configuration
+ */
+const DEFAULT_CONFIG: Required<RefinementLoopConfig> = {
+  maxIterations: 3,
+  minAcceptableScore: 0.7,
+  injectFailureContext: true,
+  queryFailureMemory: true,
+  evaluatorConfig: {},
+  triggerOnStrategies: ['explore', 'fallback'],
+  confidenceThreshold: 0.85,
+};
+
+/**
+ * RefinementLoop - Iteratively improves solutions using feedback
+ */
+export class RefinementLoop {
+  private agentManager: AgentManager;
+  private memory: MemorySystem;
+  private taskRunner: AgenticTaskRunner | null = null;
+  private evaluator: SolutionEvaluator;
+  private config: Required<RefinementLoopConfig>;
+
+  constructor(
+    agentManager: AgentManager,
+    memory: MemorySystem,
+    config: RefinementLoopConfig = {}
+  ) {
+    this.agentManager = agentManager;
+    this.memory = memory;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.evaluator = new SolutionEvaluator(
+      agentManager,
+      this.config.evaluatorConfig
+    );
+  }
+
+  /**
+   * Set the task runner for workspace-based analysis.
+   * Enables structured refinement plans via refinementAnalysisTemplate,
+   * and delegates evaluation to solutionEvaluationTemplate.
+   */
+  setTaskRunner(runner: AgenticTaskRunner): void {
+    this.taskRunner = runner;
+    this.evaluator.setTaskRunner(runner);
+  }
+
+  /**
+   * Get the evaluator for registering domain verifiers
+   */
+  getEvaluator(): SolutionEvaluator {
+    return this.evaluator;
+  }
+
+  /**
+   * Check if refinement should be triggered based on strategy and confidence
+   */
+  shouldTriggerRefinement(
+    strategy: 'direct' | 'adapt' | 'explore' | 'fallback',
+    confidence?: number
+  ): boolean {
+    // Check if strategy is in trigger list
+    if (!this.config.triggerOnStrategies.includes(strategy)) {
+      return false;
+    }
+
+    // If confidence is high enough, skip refinement
+    if (
+      confidence !== undefined &&
+      confidence >= this.config.confidenceThreshold
+    ) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Run the refinement loop on an initial trajectory
+   */
+  async refine(
+    initialTrajectory: Trajectory,
+    spawnConfig: AgentSpawnConfig
+  ): Promise<RefinementResult> {
+    const evaluations: EvaluationResult[] = [];
+    let currentTrajectory = initialTrajectory;
+    let bestTrajectory = initialTrajectory;
+    let bestScore = 0;
+    let improved = false;
+
+    // Evaluate initial trajectory
+    const initialEval = await this.evaluator.evaluate(
+      currentTrajectory,
+      spawnConfig.task
+    );
+    evaluations.push(initialEval);
+    bestScore = initialEval.score;
+
+    // If initial is acceptable, return early
+    if (initialEval.acceptable && initialEval.score >= this.config.minAcceptableScore) {
+      return {
+        trajectory: currentTrajectory,
+        success: true,
+        iterations: 0,
+        evaluations,
+        improved: false,
+        bestScore: initialEval.score,
+      };
+    }
+
+    // Refinement loop
+    for (let iteration = 0; iteration < this.config.maxIterations; iteration++) {
+      // Build failure context
+      const failureContext: FailureContext = {
+        attemptedSolution: currentTrajectory.outcome.solution,
+        evaluation: evaluations[evaluations.length - 1],
+        stepsAttempted: currentTrajectory.steps.length,
+        previousAttempts: iteration + 1,
+      };
+
+      // Get refinement strategy: workspace-based when runner available
+      let refinementAdditions: string;
+      const plan = await this.getRefinementPlan(
+        currentTrajectory,
+        spawnConfig.task,
+        evaluations[evaluations.length - 1],
+        iteration + 1,
+      );
+
+      if (plan) {
+        // Use structured plan from template
+        refinementAdditions = this.formatRefinementPlan(plan, failureContext);
+      } else {
+        // Fallback: build prompt with memory-based context
+        let failureMemory: MemoryQueryResultV2 | undefined;
+        if (this.config.queryFailureMemory) {
+          failureMemory = await this.queryFailurePatterns(
+            spawnConfig.task,
+            failureContext
+          );
+        }
+        refinementAdditions = this.buildRefinementPrompt(
+          failureContext,
+          failureMemory
+        );
+      }
+
+      // Spawn refined agent
+      const refinedConfig: AgentSpawnConfig = {
+        ...spawnConfig,
+        systemPromptAdditions: [
+          spawnConfig.systemPromptAdditions,
+          refinementAdditions,
+        ]
+          .filter(Boolean)
+          .join('\n\n'),
+      };
+
+      const result = await this.agentManager.spawn(refinedConfig);
+      currentTrajectory = result.trajectory;
+
+      // Evaluate refined trajectory
+      const evaluation = await this.evaluator.evaluate(
+        currentTrajectory,
+        spawnConfig.task
+      );
+      evaluations.push(evaluation);
+
+      // Track best
+      if (evaluation.score > bestScore) {
+        bestScore = evaluation.score;
+        bestTrajectory = currentTrajectory;
+        improved = true;
+      }
+
+      // Check if acceptable
+      if (evaluation.acceptable && evaluation.score >= this.config.minAcceptableScore) {
+        return {
+          trajectory: currentTrajectory,
+          success: true,
+          iterations: iteration + 1,
+          evaluations,
+          improved,
+          bestScore,
+        };
+      }
+    }
+
+    // Return best trajectory after all iterations
+    return {
+      trajectory: bestTrajectory,
+      success: bestScore >= this.config.minAcceptableScore,
+      iterations: this.config.maxIterations,
+      evaluations,
+      improved,
+      bestScore,
+    };
+  }
+
+  /**
+   * Get a structured refinement plan via the workspace template.
+   * Returns null if taskRunner is unavailable or the template fails.
+   */
+  private async getRefinementPlan(
+    trajectory: Trajectory,
+    task: Task,
+    evaluation: EvaluationResult,
+    previousAttempts: number,
+  ): Promise<RefinementPlan | null> {
+    if (!this.taskRunner) return null;
+
+    try {
+      const result = await this.taskRunner.run(refinementAnalysisTemplate, {
+        trajectory,
+        task,
+        evaluation,
+        previousAttempts,
+      });
+      return result.output;
+    } catch (error) {
+      console.warn(
+        'Workspace-based refinement analysis failed, falling back to heuristic:',
+        error instanceof Error ? error.message : String(error)
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Format a structured RefinementPlan into prompt additions for the retry agent.
+   */
+  private formatRefinementPlan(
+    plan: RefinementPlan,
+    failureContext: FailureContext,
+  ): string {
+    const parts: string[] = [];
+
+    parts.push('## Root Cause Analysis');
+    parts.push('');
+    parts.push(`Previous attempt #${failureContext.previousAttempts} failed. Root causes identified:`);
+    for (const cause of plan.rootCauses) {
+      parts.push(`- ${cause}`);
+    }
+
+    parts.push('');
+    parts.push('## Recommended Strategy');
+    parts.push('');
+    parts.push(plan.strategy);
+
+    if (plan.steps.length > 0) {
+      parts.push('');
+      parts.push('## Specific Steps');
+      for (let i = 0; i < plan.steps.length; i++) {
+        parts.push(`${i + 1}. ${plan.steps[i]}`);
+      }
+    }
+
+    if (plan.avoidPatterns.length > 0) {
+      parts.push('');
+      parts.push('## Patterns to Avoid');
+      for (const pattern of plan.avoidPatterns) {
+        parts.push(`- DO NOT: ${pattern}`);
+      }
+    }
+
+    return parts.join('\n');
+  }
+
+  /**
+   * Query memory for similar failure patterns
+   */
+  private async queryFailurePatterns(
+    task: Task,
+    failureContext: FailureContext
+  ): Promise<MemoryQueryResultV2> {
+    // Build query from task and failure
+    const failureDescription = failureContext.evaluation.issues
+      .map((issue) => issue.description)
+      .join('; ');
+
+    const query = `${task.description} - failed with: ${failureDescription}`;
+
+    // Query memory for similar experiences and playbooks
+    const results = await this.memory.queryV2(query, {
+      domains: task.domain ? [task.domain] : undefined,
+      includeExperiences: true,
+      includePlaybooks: true,
+    });
+
+    // Filter to experiences that eventually succeeded after similar failures
+    // This gives us recovery strategies
+    const recoveryExperiences = results.experiences.filter(
+      (exp) =>
+        exp.experience.success &&
+        this.hasSimilarInitialFailure(exp.experience, failureContext)
+    );
+
+    return {
+      ...results,
+      experiences: recoveryExperiences.length > 0 ? recoveryExperiences : results.experiences,
+    };
+  }
+
+  /**
+   * Check if an experience had a similar initial failure pattern
+   */
+  private hasSimilarInitialFailure(
+    experience: { steps?: Array<{ observation?: string }>; solutionOutput: string },
+    failureContext: FailureContext
+  ): boolean {
+    // Look for similar error patterns in the experience's early steps
+    const failureKeywords = failureContext.evaluation.issues
+      .map((issue) => issue.description.toLowerCase().split(' '))
+      .flat()
+      .filter((word) => word.length > 4);
+
+    const experienceText = (
+      (experience.steps ?? [])
+        .map((s) => s.observation ?? '')
+        .join(' ') +
+      ' ' +
+      experience.solutionOutput
+    ).toLowerCase();
+
+    const matchCount = failureKeywords.filter((kw) =>
+      experienceText.includes(kw)
+    ).length;
+
+    return matchCount >= Math.min(2, failureKeywords.length / 2);
+  }
+
+  /**
+   * Build refinement prompt with failure context and memory
+   */
+  private buildRefinementPrompt(
+    failureContext: FailureContext,
+    failureMemory?: MemoryQueryResultV2
+  ): string {
+    const parts: string[] = [];
+
+    if (this.config.injectFailureContext) {
+      parts.push('## Previous Attempt Feedback');
+      parts.push('');
+      parts.push(
+        `Your previous attempt (iteration ${failureContext.previousAttempts}) had issues:`
+      );
+      parts.push('');
+
+      for (const issue of failureContext.evaluation.issues) {
+        const severity = issue.severity.toUpperCase();
+        parts.push(`- **[${severity}]** ${issue.type}: ${issue.description}`);
+        if (issue.suggestion) {
+          parts.push(`  *Suggestion:* ${issue.suggestion}`);
+        }
+      }
+
+      parts.push('');
+      parts.push(`Quality score: ${(failureContext.evaluation.score * 100).toFixed(0)}%`);
+      parts.push(`Assessment: ${failureContext.evaluation.quality}`);
+      parts.push('');
+    }
+
+    if (failureMemory && this.config.queryFailureMemory) {
+      // Add recovery playbooks from memory
+      if (failureMemory.playbooks.length > 0) {
+        parts.push('## Recovery Playbooks from Memory');
+        parts.push('');
+        for (const { playbook, score } of failureMemory.playbooks.slice(0, 3)) {
+          parts.push(
+            `- **${playbook.name}** (${(score * 100).toFixed(0)}% relevant)`
+          );
+          parts.push(`  Strategy: ${playbook.guidance.strategy}`);
+          if (playbook.guidance.steps && playbook.guidance.steps.length > 0) {
+            parts.push(`  Steps: ${playbook.guidance.steps.slice(0, 3).join(' → ')}`);
+          }
+        }
+        parts.push('');
+      }
+
+      // Add successful recovery experiences
+      if (failureMemory.experiences.length > 0) {
+        parts.push('## Similar Problems Successfully Solved');
+        parts.push('');
+        for (const { experience } of failureMemory.experiences.slice(0, 2)) {
+          parts.push(`- Task: ${experience.taskInput.slice(0, 150)}...`);
+          parts.push(`  Solution approach: ${experience.solutionOutput.slice(0, 200)}...`);
+        }
+        parts.push('');
+      }
+    }
+
+    parts.push('## Instructions for This Attempt');
+    parts.push('');
+    parts.push('Please address the issues identified above and try a different approach.');
+    parts.push('Focus on:');
+    parts.push('1. Avoiding the specific errors from the previous attempt');
+    parts.push('2. Using the recovery playbooks if applicable');
+    parts.push('3. Taking a more thorough or alternative approach');
+
+    return parts.join('\n');
+  }
+}
+
+/**
+ * Create a refinement loop
+ */
+export function createRefinementLoop(
+  agentManager: AgentManager,
+  memory: MemorySystem,
+  config?: RefinementLoopConfig
+): RefinementLoop {
+  return new RefinementLoop(agentManager, memory, config);
+}

package/src/search/refinement-types.ts

@@ -0,0 +1,159 @@
+/**
+ * Refinement Types
+ *
+ * Types for the ReMem-style refinement loop that iteratively
+ * improves solutions using memory-augmented feedback.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Issue type found during evaluation
+ */
+export const IssueTypeSchema = z.enum([
+  'incomplete',
+  'incorrect',
+  'inefficient',
+  'off_topic',
+  'error',
+]);
+
+export type IssueType = z.infer<typeof IssueTypeSchema>;
+
+/**
+ * Severity of an issue
+ */
+export const IssueSeveritySchema = z.enum(['critical', 'major', 'minor']);
+
+export type IssueSeverity = z.infer<typeof IssueSeveritySchema>;
+
+/**
+ * An issue found during solution evaluation
+ */
+export const EvaluationIssueSchema = z.object({
+  type: IssueTypeSchema,
+  description: z.string(),
+  severity: IssueSeveritySchema,
+  suggestion: z.string().optional(),
+});
+
+export type EvaluationIssue = z.infer<typeof EvaluationIssueSchema>;
+
+/**
+ * Quality assessment level
+ */
+export const QualityLevelSchema = z.enum([
+  'excellent',
+  'good',
+  'needs_work',
+  'poor',
+]);
+
+export type QualityLevel = z.infer<typeof QualityLevelSchema>;
+
+/**
+ * How the evaluation was performed
+ */
+export const EvaluationMethodSchema = z.enum([
+  'verification',
+  'agent',
+  'heuristic',
+]);
+
+export type EvaluationMethod = z.infer<typeof EvaluationMethodSchema>;
+
+/**
+ * Result of evaluating a solution's quality
+ */
+export const EvaluationResultSchema = z.object({
+  /** Overall quality assessment */
+  quality: QualityLevelSchema,
+  /** Numeric score (0-1) */
+  score: z.number().min(0).max(1),
+  /** Whether this solution is acceptable */
+  acceptable: z.boolean(),
+  /** Specific issues found */
+  issues: z.array(EvaluationIssueSchema),
+  /** How the evaluation was performed */
+  method: EvaluationMethodSchema,
+  /** Raw response from evaluator (for debugging) */
+  rawResponse: z.string().optional(),
+});
+
+export type EvaluationResult = z.infer<typeof EvaluationResultSchema>;
+
+/**
+ * Context about why a solution failed
+ */
+export interface FailureContext {
+  /** The solution that was attempted */
+  attemptedSolution: unknown;
+  /** Evaluation result */
+  evaluation: EvaluationResult;
+  /** Number of steps taken in the attempt */
+  stepsAttempted: number;
+  /** Number of previous refinement attempts */
+  previousAttempts: number;
+}
+
+/**
+ * Result of the refinement loop
+ */
+export interface RefinementResult {
+  /** Final trajectory after refinement */
+  trajectory: import('../types/trajectory.js').Trajectory;
+  /** Whether the final solution is acceptable */
+  success: boolean;
+  /** Number of refinement iterations performed */
+  iterations: number;
+  /** Evaluation results from each iteration */
+  evaluations: EvaluationResult[];
+  /** Whether refinement improved the solution */
+  improved: boolean;
+  /** Best score achieved during refinement */
+  bestScore: number;
+}
+
+/**
+ * Create an evaluation result
+ */
+export function createEvaluationResult(params: {
+  quality: QualityLevel;
+  score: number;
+  acceptable: boolean;
+  issues?: EvaluationIssue[];
+  method: EvaluationMethod;
+  rawResponse?: string;
+}): EvaluationResult {
+  return EvaluationResultSchema.parse({
+    quality: params.quality,
+    score: params.score,
+    acceptable: params.acceptable,
+    issues: params.issues ?? [],
+    method: params.method,
+    rawResponse: params.rawResponse,
+  });
+}
+
+/**
+ * Determine quality level from a numeric score
+ */
+export function scoreToQuality(score: number): QualityLevel {
+  if (score >= 0.85) return 'excellent';
+  if (score >= 0.7) return 'good';
+  if (score >= 0.4) return 'needs_work';
+  return 'poor';
+}
+
+/**
+ * Check if a quality level is acceptable
+ */
+export function isQualityAcceptable(
+  quality: QualityLevel,
+  minAcceptable: QualityLevel = 'good'
+): boolean {
+  const levels: QualityLevel[] = ['poor', 'needs_work', 'good', 'excellent'];
+  const qualityIndex = levels.indexOf(quality);
+  const minIndex = levels.indexOf(minAcceptable);
+  return qualityIndex >= minIndex;
+}