cognitive-core 0.1.0 → 0.1.2

package/src/runtime/types.ts

@@ -1,5 +1,6 @@
 import type { Task, Trajectory } from '../types/index.js';
 import type { MemoryQueryResultV2 } from '../memory/system.js';
+import type { ComputeRequirements } from './compute-provider.js';
 
 /**
  * Message in an agent conversation
@@ -73,6 +74,8 @@ export interface AgentSpawnConfig {
   onToolCall?: (toolCall: ToolCall) => void;
   /** Additional backend-specific options */
   backendOptions?: Record<string, unknown>;
+  /** Compute requirements for provider-based backend resolution */
+  computeRequirements?: ComputeRequirements;
 }
 
 /**
@@ -155,3 +158,41 @@ export interface AgentObserverCallbacks {
   onSessionEnd?: (session: AgentSession, trajectory: Trajectory) => void;
   onError?: (session: AgentSession, error: Error) => void;
 }
+
+/**
+ * Options passed to an AgentDelegate when executing a task
+ */
+export interface AgentDelegateOptions {
+  /** Working directory for execution */
+  cwd: string;
+  /** System context (formatted knowledge + skill context) */
+  systemContext?: string;
+  /** Timeout in milliseconds */
+  timeoutMs?: number;
+}
+
+/**
+ * Result returned by an AgentDelegate after execution
+ */
+export interface AgentDelegateResult {
+  /** Whether the execution succeeded */
+  success: boolean;
+  /** Text output from the agent */
+  output: string;
+  /** Optional structured output */
+  structured?: unknown;
+  /** Optional trajectory — when provided, used directly for full learning fidelity */
+  trajectory?: Trajectory;
+}
+
+/**
+ * AgentDelegate — lets callers provide their own agent instances.
+ *
+ * When set on AgentManager, bypasses backend resolution and compute provider.
+ * The caller owns all lifecycle, tracking, and billing. cognitive-core only
+ * sends a prompt + context and receives a result.
+ */
+export interface AgentDelegate {
+  /** Execute a task with the given prompt and options */
+  execute(prompt: string, options: AgentDelegateOptions): Promise<AgentDelegateResult>;
+}

package/src/search/evaluator.ts

@@ -10,6 +10,8 @@
 import type { Trajectory } from '../types/trajectory.js';
 import type { Task } from '../types/task.js';
 import type { AgentManager } from '../runtime/manager.js';
+import type { AgenticTaskRunner } from '../workspace/runner.js';
+import { solutionEvaluationTemplate } from '../workspace/templates/solution-evaluation.js';
 import {
   type EvaluationResult,
   createEvaluationResult,
@@ -70,6 +72,7 @@ const DEFAULT_CONFIG: Required<EvaluatorConfig> = {
  */
 export class SolutionEvaluator {
   private agentManager: AgentManager | null;
+  private taskRunner: AgenticTaskRunner | null = null;
   private config: Required<EvaluatorConfig>;
   private verifiers: Map<string, VerificationFunction> = new Map();
 
@@ -81,6 +84,14 @@ export class SolutionEvaluator {
     this.config = { ...DEFAULT_CONFIG, ...config };
   }
 
+  /**
+   * Set the task runner for workspace-based evaluation.
+   * When set, evaluation delegates to solutionEvaluationTemplate.
+   */
+  setTaskRunner(runner: AgenticTaskRunner): void {
+    this.taskRunner = runner;
+  }
+
   /**
    * Register a verification function for a task domain
    */
@@ -109,20 +120,34 @@ export class SolutionEvaluator {
       }
     }
 
-    // 2. Try ACP agent evaluation
+    // 2. Try workspace-based evaluation (preferred)
+    if (this.taskRunner) {
+      try {
+        const result = await this.taskRunner.run(solutionEvaluationTemplate, {
+          trajectory,
+          task,
+        });
+        return result.output;
+      } catch (error) {
+        console.warn(
+          'Workspace-based evaluation failed, falling back:',
+          error instanceof Error ? error.message : String(error)
+        );
+      }
+    }
+
+    // 3. Try ad-hoc ACP agent evaluation
     if (this.agentManager) {
       try {
         const agentResult = await this.evaluateWithAgent(trajectory, task);
         return agentResult;
       } catch (error) {
-        // Fall through to heuristic if agent fails
         const errorMsg = error instanceof Error ? error.message : String(error);
-        // Log warning but continue to heuristic
         console.warn(`Agent evaluation failed, falling back to heuristic: ${errorMsg}`);
       }
     }
 
-    // 3. Fall back to heuristic evaluation
+    // 4. Fall back to heuristic evaluation
     return this.evaluateHeuristic(trajectory, task);
   }
 

package/src/search/index.ts

@@ -48,6 +48,15 @@ export {
   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,

package/src/search/refinement-loop.ts

@@ -13,6 +13,8 @@ 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,
@@ -59,6 +61,7 @@ const DEFAULT_CONFIG: Required<RefinementLoopConfig> = {
 export class RefinementLoop {
   private agentManager: AgentManager;
   private memory: MemorySystem;
+  private taskRunner: AgenticTaskRunner | null = null;
   private evaluator: SolutionEvaluator;
   private config: Required<RefinementLoopConfig>;
 
@@ -76,6 +79,16 @@ export class RefinementLoop {
     );
   }
 
+  /**
+   * 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
    */
@@ -149,21 +162,33 @@ export class RefinementLoop {
         previousAttempts: iteration + 1,
       };
 
-      // Query memory for similar failures if enabled
-      let failureMemory: MemoryQueryResultV2 | undefined;
-      if (this.config.queryFailureMemory) {
-        failureMemory = await this.queryFailurePatterns(
-          spawnConfig.task,
-          failureContext
+      // 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
         );
       }
 
-      // Build refinement prompt
-      const refinementAdditions = this.buildRefinementPrompt(
-        failureContext,
-        failureMemory
-      );
-
       // Spawn refined agent
       const refinedConfig: AgentSpawnConfig = {
         ...spawnConfig,
@@ -216,6 +241,75 @@ export class RefinementLoop {
     };
   }
 
+  /**
+   * 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
    */