cognitive-core 0.1.0 → 0.2.0

package/src/workspace/templates/meta-reflection.ts

@@ -0,0 +1,208 @@
+/**
+ * Meta-Reflection Template
+ *
+ * Replaces MetaLearner.generateReflection() with workspace-based
+ * semantic reflection that analyzes what worked and why.
+ *
+ * - Clear success with high confidence routing → heuristic fallback
+ * - Failures or uncertain outcomes → agent reflects on execution
+ */
+
+import type { WorkspaceHandle } from 'agent-workspace';
+import type { Trajectory } from '../../types/index.js';
+import type { PlaybookMatch } from '../../memory/playbook.js';
+import type {
+  AgenticTaskTemplate,
+  AnalysisComplexity,
+} from '../types.js';
+
+// ============================================================
+// Input / Output Types
+// ============================================================
+
+export interface MetaReflectionInput {
+  trajectory: Trajectory;
+  routingDecision: {
+    strategy: string;
+    confidence: number;
+    estimatedBudget: number;
+    reasoning: string;
+  };
+  playbooksUsed: PlaybookMatch[];
+}
+
+/**
+ * Simplified meta-reflection output.
+ * The full MetaObservation is constructed by the MetaLearner after
+ * receiving this output, so we only need the core reflection data.
+ */
+export interface MetaReflectionOutput {
+  /** Was the retrieval helpful, neutral, or misleading? */
+  retrievalQuality: 'helpful' | 'neutral' | 'misleading';
+  /** Overall outcome quality */
+  outcomeQuality: 'excellent' | 'good' | 'acceptable' | 'poor';
+  /** What worked well */
+  whatWorked: string[];
+  /** What failed or was suboptimal */
+  whatFailed: string[];
+  /** Suggestions for improvement */
+  suggestions: string[];
+  /** Whether decomposition was used */
+  decompositionUsed: boolean;
+  /** Whether backtracking occurred */
+  backtrackingOccurred: boolean;
+  /** Estimated refinement iterations */
+  refinementIterations: number;
+}
+
+// ============================================================
+// Template Implementation
+// ============================================================
+
+export const metaReflectionTemplate: AgenticTaskTemplate<
+  MetaReflectionInput,
+  MetaReflectionOutput
+> = {
+  taskType: 'meta-reflection',
+  domain: 'meta-reflection',
+  description: 'Reflect on task execution to generate meta-learning observations',
+
+  assessComplexity(input: MetaReflectionInput): AnalysisComplexity {
+    // Clear success with high confidence → heuristic
+    if (
+      input.trajectory.outcome.success &&
+      input.routingDecision.confidence > 0.8
+    ) {
+      return 'heuristic';
+    }
+    return 'lightweight';
+  },
+
+  async heuristicFallback(input: MetaReflectionInput): Promise<MetaReflectionOutput> {
+    const { trajectory, routingDecision, playbooksUsed } = input;
+    const wasSuccessful = trajectory.outcome.success;
+    const actualEffort = trajectory.llmCalls ?? trajectory.steps.length;
+    const effortRatio = actualEffort / routingDecision.estimatedBudget;
+
+    return {
+      retrievalQuality: playbooksUsed.length === 0 ? 'neutral'
+        : wasSuccessful ? 'helpful' : 'neutral',
+      outcomeQuality: !wasSuccessful ? 'poor'
+        : effortRatio <= 0.5 ? 'excellent'
+        : effortRatio <= 1.0 ? 'good'
+        : effortRatio <= 2.0 ? 'acceptable' : 'poor',
+      whatWorked: wasSuccessful
+        ? [`${routingDecision.strategy} routing led to success`]
+        : [],
+      whatFailed: wasSuccessful
+        ? []
+        : [`${routingDecision.strategy} routing did not lead to success`],
+      suggestions: wasSuccessful ? [] : ['Consider alternative approaches'],
+      decompositionUsed: trajectory.steps.some(
+        s => s.thought?.includes('break') || s.thought?.includes('step by step')
+      ),
+      backtrackingOccurred: false,
+      refinementIterations: 0,
+    };
+  },
+
+  async prepareWorkspace(
+    input: MetaReflectionInput,
+    handle: WorkspaceHandle
+  ): Promise<void> {
+    const { trajectory, routingDecision, playbooksUsed } = input;
+
+    await handle.writeJson('input', 'context.json', {
+      routing: routingDecision,
+      outcome: trajectory.outcome,
+      stepCount: trajectory.steps.length,
+      wallTimeSeconds: trajectory.wallTimeSeconds,
+      playbooksInjected: playbooksUsed.map(pm => ({
+        name: pm.playbook.name,
+        strategy: pm.playbook.guidance.strategy,
+        score: pm.score,
+        matchType: pm.matchType,
+      })),
+    });
+
+    await handle.writeJsonl('input', 'steps.jsonl',
+      trajectory.steps.map((step, i) => ({
+        index: i,
+        thought: step.thought?.slice(0, 200),
+        action: step.action.slice(0, 200),
+        observation: step.observation?.slice(0, 200),
+      }))
+    );
+  },
+
+  buildTaskPrompt(input: MetaReflectionInput): string {
+    const outcome = input.trajectory.outcome.success ? 'SUCCESSFUL' : 'FAILED';
+    return [
+      `Reflect on this ${outcome} task execution.`,
+      '',
+      'Read input/context.json for routing decision and outcome.',
+      'Read input/steps.jsonl for the execution trace.',
+      '',
+      'Analyze:',
+      '1. Was the retrieved knowledge helpful, neutral, or misleading?',
+      '2. What outcome quality level (excellent/good/acceptable/poor)?',
+      '3. What worked well? What failed?',
+      '4. What suggestions for future similar tasks?',
+      '5. Was decomposition used? Did backtracking occur?',
+      '',
+      'Write to output/reflection.json with this schema:',
+      '```json',
+      '{',
+      '  "retrievalQuality": "helpful" | "neutral" | "misleading",',
+      '  "outcomeQuality": "excellent" | "good" | "acceptable" | "poor",',
+      '  "whatWorked": ["..."],',
+      '  "whatFailed": ["..."],',
+      '  "suggestions": ["..."],',
+      '  "decompositionUsed": boolean,',
+      '  "backtrackingOccurred": boolean,',
+      '  "refinementIterations": number',
+      '}',
+      '```',
+    ].join('\n');
+  },
+
+  getSkills() { return []; },
+  getResources() { return []; },
+
+  outputConfig: {
+    files: [{
+      path: 'reflection.json',
+      format: 'json' as const,
+      required: true,
+      description: 'Meta-reflection on task execution',
+    }],
+  },
+
+  async collectOutput(handle: WorkspaceHandle): Promise<MetaReflectionOutput> {
+    const raw = await handle.readJson('output', 'reflection.json') as Record<string, unknown>;
+    return {
+      retrievalQuality: (['helpful', 'neutral', 'misleading'].includes(String(raw.retrievalQuality))
+        ? raw.retrievalQuality : 'neutral') as MetaReflectionOutput['retrievalQuality'],
+      outcomeQuality: (['excellent', 'good', 'acceptable', 'poor'].includes(String(raw.outcomeQuality))
+        ? raw.outcomeQuality : 'poor') as MetaReflectionOutput['outcomeQuality'],
+      whatWorked: Array.isArray(raw.whatWorked) ? raw.whatWorked.map(String) : [],
+      whatFailed: Array.isArray(raw.whatFailed) ? raw.whatFailed.map(String) : [],
+      suggestions: Array.isArray(raw.suggestions) ? raw.suggestions.map(String) : [],
+      decompositionUsed: Boolean(raw.decompositionUsed),
+      backtrackingOccurred: Boolean(raw.backtrackingOccurred),
+      refinementIterations: typeof raw.refinementIterations === 'number'
+        ? raw.refinementIterations : 0,
+    };
+  },
+
+  async processOutput(): Promise<void> {},
+
+  agentType: 'claude-code',
+  timeout: 120_000,
+  captureToolCalls: true,
+
+  computeRequirements: {
+    mode: 'local',
+    complexity: 'lightweight',
+  },
+};

package/src/workspace/templates/playbook-extraction.ts

@@ -0,0 +1,240 @@
+/**
+ * Playbook Extraction Template
+ *
+ * Replaces both PlaybookExtractor (heuristic) and LLMPlaybookExtractor
+ * with a unified workspace-based agentic extraction.
+ *
+ * - Small batches (<=3 trajectories) → heuristic fallback
+ * - Larger batches → agent semantically identifies patterns and creates playbooks
+ */
+
+import type { WorkspaceHandle } from 'agent-workspace';
+import type { Trajectory, Playbook } from '../../types/index.js';
+import type { AnalysisResult } from '../../learning/analyzer.js';
+import type {
+  ExtractedPlaybooks,
+} from '../../learning/playbook-extractor.js';
+import { createPlaybookExtractor } from '../../learning/playbook-extractor.js';
+import type {
+  AgenticTaskTemplate,
+  AnalysisComplexity,
+} from '../types.js';
+import type { ComputeRequirements } from '../../runtime/compute-provider.js';
+
+// ============================================================
+// Input / Output Types
+// ============================================================
+
+export interface PlaybookExtractionInput {
+  trajectories: Trajectory[];
+  analyses: AnalysisResult[];
+  existingPlaybooks: Playbook[];
+}
+
+// Output is ExtractedPlaybooks (reused from learning/playbook-extractor.ts)
+
+// ============================================================
+// Template Implementation
+// ============================================================
+
+export const playbookExtractionTemplate: AgenticTaskTemplate<
+  PlaybookExtractionInput,
+  ExtractedPlaybooks
+> = {
+  taskType: 'playbook-extraction',
+  domain: 'playbook-extraction',
+  description: 'Extract reusable playbooks from trajectory batch',
+
+  assessComplexity(input: PlaybookExtractionInput): AnalysisComplexity {
+    if (input.trajectories.length <= 3) return 'heuristic';
+    if (input.trajectories.length > 10) return 'thorough';
+    return 'standard';
+  },
+
+  async heuristicFallback(input: PlaybookExtractionInput): Promise<ExtractedPlaybooks> {
+    const extractor = createPlaybookExtractor();
+    return extractor.extract(
+      input.trajectories,
+      input.analyses,
+      input.existingPlaybooks
+    );
+  },
+
+  async prepareWorkspace(
+    input: PlaybookExtractionInput,
+    handle: WorkspaceHandle
+  ): Promise<void> {
+    // Write summary
+    const successCount = input.analyses.filter(a => a.success).length;
+    const domains = [...new Set(input.trajectories.map(t => t.task.domain))];
+    await handle.writeJson('input', 'summary.json', {
+      batchSize: input.trajectories.length,
+      domains,
+      successRate: input.trajectories.length > 0
+        ? successCount / input.trajectories.length
+        : 0,
+      existingPlaybookCount: input.existingPlaybooks.length,
+    });
+
+    // Write each trajectory with its analysis
+    for (let i = 0; i < input.trajectories.length; i++) {
+      const traj = input.trajectories[i];
+      const analysis = input.analyses[i];
+      await handle.writeJson('input', `trajectories/${traj.id}.json`, {
+        id: traj.id,
+        domain: traj.task.domain,
+        description: traj.task.description,
+        outcome: traj.outcome,
+        stepCount: traj.steps.length,
+        keySteps: analysis.keySteps,
+        abstractable: analysis.abstractable,
+        errorPatterns: analysis.errorPatterns,
+        // Include only key steps to keep workspace focused
+        steps: analysis.keySteps.map(idx => ({
+          index: idx,
+          thought: traj.steps[idx]?.thought,
+          action: traj.steps[idx]?.action,
+          observation: traj.steps[idx]?.observation,
+        })),
+      });
+    }
+
+    // Write existing playbook summaries for deduplication
+    for (const playbook of input.existingPlaybooks) {
+      await handle.writeJson('input', `existing-playbooks/${playbook.id}.json`, {
+        id: playbook.id,
+        name: playbook.name,
+        strategy: playbook.guidance.strategy,
+        tactics: playbook.guidance.tactics,
+        domains: playbook.applicability.domains,
+        successCount: playbook.evolution.successCount,
+        failureCount: playbook.evolution.failureCount,
+      });
+    }
+  },
+
+  buildTaskPrompt(input: PlaybookExtractionInput): string {
+    return [
+      `Extract reusable playbooks from ${input.trajectories.length} agent trajectories.`,
+      '',
+      'Read input/summary.json for batch overview.',
+      'Read input/trajectories/*.json for individual trajectory data.',
+      'Read input/existing-playbooks/*.json to avoid duplicating existing playbooks.',
+      '',
+      'For each pattern you identify:',
+      '1. Check if it overlaps with an existing playbook (if so, create an update, not a new playbook)',
+      '2. Extract a clear strategy and tactical steps',
+      '3. Identify when the playbook applies and when it should NOT apply',
+      '',
+      'Write results to output/extraction.json with this schema:',
+      '```json',
+      '{',
+      '  "new": [',
+      '    {',
+      '      "name": "descriptive-name",',
+      '      "strategy": "high-level approach",',
+      '      "tactics": ["step1", "step2"],',
+      '      "situations": ["when to apply"],',
+      '      "triggers": ["keywords or patterns"],',
+      '      "antiPatterns": ["when NOT to apply"],',
+      '      "domains": ["applicable domains"],',
+      '      "confidence": 0.0-1.0',
+      '    }',
+      '  ],',
+      '  "updates": [',
+      '    {',
+      '      "id": "existing-playbook-id",',
+      '      "newTrigger": "optional new trigger",',
+      '      "newAntiPattern": "optional new anti-pattern",',
+      '      "refinementContext": "when this refinement applies",',
+      '      "refinementAddition": "what to add to the playbook"',
+      '    }',
+      '  ]',
+      '}',
+      '```',
+    ].join('\n');
+  },
+
+  getSkills() { return []; },
+  getResources() { return []; },
+
+  outputConfig: {
+    files: [
+      {
+        path: 'extraction.json',
+        format: 'json' as const,
+        required: true,
+        description: 'Extracted playbooks and updates to existing playbooks',
+      },
+    ],
+  },
+
+  async collectOutput(handle: WorkspaceHandle): Promise<ExtractedPlaybooks> {
+    const raw = await handle.readJson('output', 'extraction.json') as Record<string, unknown>;
+    const { createPlaybook } = await import('../../types/index.js');
+
+    const newPlaybooks: Playbook[] = [];
+    if (Array.isArray(raw.new)) {
+      for (const item of raw.new as Record<string, unknown>[]) {
+        newPlaybooks.push(createPlaybook({
+          name: String(item.name ?? 'Unnamed Playbook'),
+          guidance: {
+            strategy: String(item.strategy ?? ''),
+            tactics: Array.isArray(item.tactics) ? item.tactics.map(String) : [],
+          },
+          applicability: {
+            situations: Array.isArray(item.situations) ? item.situations.map(String) : [],
+            triggers: Array.isArray(item.triggers) ? item.triggers.map(String) : [],
+            antiPatterns: Array.isArray(item.antiPatterns) ? item.antiPatterns.map(String) : [],
+            domains: Array.isArray(item.domains) ? item.domains.map(String) : [],
+          },
+          confidence: typeof item.confidence === 'number' ? item.confidence : 0.5,
+          complexity: 'moderate',
+        }));
+      }
+    }
+
+    const updates: ExtractedPlaybooks['updates'] = [];
+    if (Array.isArray(raw.updates)) {
+      for (const item of raw.updates as Record<string, unknown>[]) {
+        updates.push({
+          id: String(item.id ?? ''),
+          newTrigger: item.newTrigger ? String(item.newTrigger) : undefined,
+          newAntiPattern: item.newAntiPattern ? String(item.newAntiPattern) : undefined,
+          refinement: item.refinementContext ? {
+            context: String(item.refinementContext),
+            addition: String(item.refinementAddition ?? ''),
+            source: 'success' as const,
+            addedAt: new Date(),
+          } : undefined,
+        });
+      }
+    }
+
+    return { new: newPlaybooks, updates };
+  },
+
+  async processOutput(): Promise<void> {
+    // Pipeline handles storage
+  },
+
+  computeRequirements: {
+    mode: 'local',
+    complexity: 'standard',
+  },
+
+  getComputeRequirements(
+    _input: PlaybookExtractionInput,
+    complexity: AnalysisComplexity
+  ): ComputeRequirements {
+    return {
+      mode: 'local',
+      complexity,
+      timeout: complexity === 'thorough' ? 300_000 : 180_000,
+    };
+  },
+
+  agentType: 'claude-code',
+  timeout: 180_000,
+  captureToolCalls: true,
+};

package/src/workspace/templates/refinement-analysis.ts

@@ -0,0 +1,162 @@
+/**
+ * Refinement Analysis Template
+ *
+ * Enhances the RefinementLoop's failure analysis with workspace-based
+ * root cause analysis. Instead of just retrying, the agent analyzes
+ * WHY the previous attempt failed and produces a targeted strategy.
+ *
+ * - First failure → lightweight analysis
+ * - Repeated failures → standard deeper analysis
+ */
+
+import type { WorkspaceHandle } from 'agent-workspace';
+import type { Trajectory, Task } from '../../types/index.js';
+import type { EvaluationResult } from '../../search/refinement-types.js';
+import type {
+  AgenticTaskTemplate,
+  AnalysisComplexity,
+} from '../types.js';
+import type { ComputeRequirements } from '../../runtime/compute-provider.js';
+
+// ============================================================
+// Input / Output Types
+// ============================================================
+
+export interface RefinementAnalysisInput {
+  trajectory: Trajectory;
+  task: Task;
+  evaluation: EvaluationResult;
+  previousAttempts: number;
+}
+
+export interface RefinementPlan {
+  /** Root causes identified for the failure */
+  rootCauses: string[];
+  /** Recommended strategy for the next attempt */
+  strategy: string;
+  /** Specific steps to take */
+  steps: string[];
+  /** Patterns to avoid (from previous failure) */
+  avoidPatterns: string[];
+}
+
+// ============================================================
+// Template Implementation
+// ============================================================
+
+export const refinementAnalysisTemplate: AgenticTaskTemplate<
+  RefinementAnalysisInput,
+  RefinementPlan
+> = {
+  taskType: 'refinement-analysis',
+  domain: 'refinement-analysis',
+  description: 'Analyze failure and plan refinement strategy',
+
+  assessComplexity(input: RefinementAnalysisInput): AnalysisComplexity {
+    // First failure → lightweight
+    if (input.previousAttempts <= 1) return 'lightweight';
+    // Repeated failures → deeper analysis
+    return 'standard';
+  },
+
+  // No heuristic fallback — refinement always benefits from semantic reasoning
+
+  async prepareWorkspace(
+    input: RefinementAnalysisInput,
+    handle: WorkspaceHandle
+  ): Promise<void> {
+    const { trajectory, task, evaluation, previousAttempts } = input;
+
+    await handle.writeJson('input', 'context.json', {
+      task: {
+        description: task.description,
+        domain: task.domain,
+      },
+      evaluation: {
+        quality: evaluation.quality,
+        score: evaluation.score,
+        issues: evaluation.issues,
+      },
+      previousAttempts,
+      outcome: trajectory.outcome,
+    });
+
+    await handle.writeJsonl('input', 'steps.jsonl',
+      trajectory.steps.map((step, i) => ({
+        index: i,
+        thought: step.thought?.slice(0, 300),
+        action: step.action.slice(0, 300),
+        observation: step.observation?.slice(0, 300),
+      }))
+    );
+  },
+
+  buildTaskPrompt(input: RefinementAnalysisInput): string {
+    const attemptNum = input.previousAttempts + 1;
+    return [
+      `This is attempt #${attemptNum}. The previous attempt failed with quality "${input.evaluation.quality}" (score: ${input.evaluation.score}).`,
+      '',
+      'Read input/context.json for task, evaluation, and outcome details.',
+      'Read input/steps.jsonl for the execution trace.',
+      '',
+      'Perform root cause analysis:',
+      '1. Why did the previous attempt fail? Identify specific root causes.',
+      '2. What strategy should the next attempt use?',
+      '3. What specific steps should be taken?',
+      '4. What patterns from the failed attempt should be avoided?',
+      '',
+      'Write to output/plan.json:',
+      '```json',
+      '{',
+      '  "rootCauses": ["cause1", "cause2"],',
+      '  "strategy": "high-level approach for next attempt",',
+      '  "steps": ["specific step 1", "specific step 2"],',
+      '  "avoidPatterns": ["pattern to avoid 1", "pattern to avoid 2"]',
+      '}',
+      '```',
+    ].join('\n');
+  },
+
+  getSkills() { return []; },
+  getResources() { return []; },
+
+  outputConfig: {
+    files: [{
+      path: 'plan.json',
+      format: 'json' as const,
+      required: true,
+      description: 'Refinement plan with root causes and strategy',
+    }],
+  },
+
+  async collectOutput(handle: WorkspaceHandle): Promise<RefinementPlan> {
+    const raw = await handle.readJson('output', 'plan.json') as Record<string, unknown>;
+    return {
+      rootCauses: Array.isArray(raw.rootCauses) ? raw.rootCauses.map(String) : [],
+      strategy: String(raw.strategy ?? ''),
+      steps: Array.isArray(raw.steps) ? raw.steps.map(String) : [],
+      avoidPatterns: Array.isArray(raw.avoidPatterns) ? raw.avoidPatterns.map(String) : [],
+    };
+  },
+
+  async processOutput(): Promise<void> {},
+
+  computeRequirements: {
+    mode: 'local',
+    complexity: 'lightweight',
+  },
+
+  getComputeRequirements(
+    _input: RefinementAnalysisInput,
+    complexity: AnalysisComplexity
+  ): ComputeRequirements {
+    return {
+      mode: 'local',
+      complexity,
+    };
+  },
+
+  agentType: 'claude-code',
+  timeout: 120_000,
+  captureToolCalls: true,
+};