cognitive-core 0.1.0 → 0.2.0

package/src/workspace/index.ts

@@ -0,0 +1,48 @@
+// Workspace management (from agent-workspace package)
+export { WorkspaceManager, WorkspaceHandle } from 'agent-workspace';
+
+// Workspace types
+export {
+  type OutputSpec,
+  type OutputFileSpec,
+  type ValidationResult,
+  type AgentSkillSpec,
+  type ResourceSpec,
+  type AnalysisComplexity,
+  type ProcessingContext,
+  type AgenticTaskTemplate,
+  type AgenticTaskResult,
+  type AgenticTaskMetrics,
+  AgenticTaskOutputError,
+} from './types.js';
+
+// AgenticTaskRunner
+export {
+  AgenticTaskRunner,
+  createAgenticTaskRunner,
+} from './runner.js';
+
+// Playbook ↔ Skill converter
+export {
+  convertPlaybooksToSkills,
+  generateSkillMd,
+  parseSkillMdToPlaybook,
+} from './skill-converter.js';
+
+// Templates
+export {
+  trajectoryAnalysisTemplate,
+  type TrajectoryAnalysisInput,
+  playbookExtractionTemplate,
+  type PlaybookExtractionInput,
+  usageInferenceTemplate,
+  type UsageInferenceInput,
+  metaReflectionTemplate,
+  type MetaReflectionInput,
+  type MetaReflectionOutput,
+  solutionEvaluationTemplate,
+  type SolutionEvaluationInput,
+  refinementAnalysisTemplate,
+  type RefinementAnalysisInput,
+  type RefinementPlan,
+} from './templates/index.js';

package/src/workspace/runner.ts

@@ -0,0 +1,281 @@
+import type { WorkspaceManager, WorkspaceHandle } from 'agent-workspace';
+import type { AgentManager } from '../runtime/manager.js';
+import type { MemorySystem, MemoryQueryResultV2 } from '../memory/system.js';
+import { createTask } from '../types/task.js';
+import type {
+  AgenticTaskTemplate,
+  AgenticTaskResult,
+  ProcessingContext,
+  TrajectoryProcessor,
+  AnalysisComplexity,
+} from './types.js';
+import { AgenticTaskOutputError } from './types.js';
+import type { AgenticTaskRunnerConfig } from '../types/config.js';
+
+/**
+ * AgenticTaskRunner — orchestrates the full lifecycle of agentic analysis tasks.
+ *
+ * Flow:
+ * 1. Check complexity → use heuristic fallback for simple inputs
+ * 2. Create workspace and populate input files
+ * 3. Load skills and resources
+ * 4. Query knowledge for injection
+ * 5. Spawn agent with workspace as cwd
+ * 6. Validate and collect output
+ * 7. Process output (store, accumulate)
+ * 8. Route analysis agent's trajectory through learning pipeline
+ * 9. Cleanup workspace
+ */
+export class AgenticTaskRunner {
+  constructor(
+    private workspaceManager: WorkspaceManager,
+    private agentManager: AgentManager,
+    private memory: MemorySystem,
+    private learningPipeline: TrajectoryProcessor,
+    private config: AgenticTaskRunnerConfig
+  ) {}
+
+  /**
+   * Run an agentic analysis task.
+   */
+  async run<TInput, TOutput>(
+    template: AgenticTaskTemplate<TInput, TOutput>,
+    input: TInput
+  ): Promise<AgenticTaskResult<TOutput>> {
+    const startTime = Date.now();
+
+    // Step 1: Complexity assessment
+    const complexity = template.assessComplexity(input);
+
+    if (complexity === 'heuristic' && template.heuristicFallback) {
+      const output = await template.heuristicFallback(input);
+      return {
+        output,
+        method: 'heuristic',
+        metrics: {
+          totalTimeMs: Date.now() - startTime,
+          tokensUsed: 0,
+          toolCalls: 0,
+        },
+      };
+    }
+
+    // Step 2: Create workspace (with skills/ as additional directory)
+    const handle = await this.workspaceManager.create(template.taskType, {
+      additionalDirs: ['skills'],
+    });
+    let failed = false;
+
+    try {
+      // Step 3: Populate input files via handle
+      await template.prepareWorkspace(input, handle);
+
+      // Step 4: Populate skills
+      const skills = template.getSkills(input);
+      for (const skill of skills) {
+        await handle.writeRaw('skills', `${skill.name}/SKILL.md`, skill.content);
+      }
+
+      // Step 5: Populate resources
+      const resources = template.getResources(input);
+      for (const resource of resources) {
+        switch (resource.type) {
+          case 'file':
+            await handle.writeRaw('resources', resource.path, resource.source);
+            break;
+          case 'symlink':
+            await handle.symlink('resources', resource.path, resource.source);
+            break;
+          case 'directory':
+            await handle.copyDir('resources', resource.path, resource.source);
+            break;
+        }
+      }
+
+      // Step 6: Query knowledge
+      const knowledge = await this.getKnowledge(template, input);
+
+      // Step 7: Spawn agent
+      const task = createTask({
+        domain: template.domain,
+        description: template.buildTaskPrompt(input),
+        context: {
+          workspaceId: handle.id,
+          taskType: template.taskType,
+        },
+      });
+
+      // Resolve compute requirements (dynamic > static > none)
+      const computeRequirements = template.getComputeRequirements
+        ? template.getComputeRequirements(input, complexity)
+        : template.computeRequirements;
+
+      const agentResult = await this.agentManager.spawn({
+        agentType: template.agentType ?? 'claude-code',
+        task,
+        cwd: handle.path,
+        injectedKnowledge: knowledge,
+        captureToolCalls: template.captureToolCalls ?? true,
+        timeout: this.getTimeout(template, complexity),
+        computeRequirements,
+      });
+
+      // Step 8: Validate output
+      const validation = await handle.validateOutput(template.outputConfig);
+      if (!validation.valid) {
+        const errorMessages = validation.errors.map(e => `${e.path}: ${e.message}`).join(', ');
+        throw new AgenticTaskOutputError(
+          template.taskType,
+          new Error(`Output validation failed: ${errorMessages}`)
+        );
+      }
+
+      // Step 9: Collect and validate output
+      const output = await this.collectWithRetry(template, handle);
+
+      // Step 10: Process output
+      const context: ProcessingContext = {
+        memory: this.memory,
+        learningPipeline: this.learningPipeline,
+      };
+      await template.processOutput(output, input, context);
+
+      // Step 11: Meta-learning — analysis agent's trajectory
+      await this.learningPipeline.processTrajectory(agentResult.trajectory);
+
+      return {
+        output,
+        method: 'agentic',
+        agentTrajectoryId: agentResult.trajectory.id,
+        metrics: {
+          totalTimeMs: agentResult.metrics.totalTime,
+          tokensUsed: agentResult.metrics.tokenEstimate ?? 0,
+          toolCalls: agentResult.metrics.toolCallCount,
+        },
+      };
+    } catch (error) {
+      failed = true;
+      throw error;
+    } finally {
+      // Step 12: Cleanup
+      const shouldCleanup = this.config.cleanupWorkspaces &&
+        !(failed && this.config.keepFailedWorkspaces);
+      if (shouldCleanup) {
+        await this.workspaceManager.cleanup(handle);
+      }
+    }
+  }
+
+  /**
+   * Query knowledge for the analysis agent.
+   * Combines domain-scoped query + template-specific additional queries.
+   */
+  private async getKnowledge<TInput, TOutput>(
+    template: AgenticTaskTemplate<TInput, TOutput>,
+    input: TInput
+  ): Promise<MemoryQueryResultV2> {
+    // Always query for playbooks in the template's domain
+    const domainKnowledge = await this.memory.queryV2(
+      template.description,
+      { domains: [template.domain] }
+    );
+
+    // Template-specific additional knowledge
+    if (template.getAdditionalKnowledge) {
+      const additional = await template.getAdditionalKnowledge(input, this.memory);
+      return mergeKnowledge(domainKnowledge, additional);
+    }
+
+    return domainKnowledge;
+  }
+
+  /**
+   * Collect output with retry on validation failure.
+   */
+  private async collectWithRetry<TInput, TOutput>(
+    template: AgenticTaskTemplate<TInput, TOutput>,
+    handle: WorkspaceHandle,
+    maxRetries: number = 1
+  ): Promise<TOutput> {
+    let lastError: Error | undefined;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await template.collectOutput(handle);
+      } catch (error) {
+        lastError = error as Error;
+        if (attempt < maxRetries) {
+          // Brief pause before retry
+          await new Promise(resolve => setTimeout(resolve, 500));
+        }
+      }
+    }
+    throw new AgenticTaskOutputError(template.taskType, lastError!);
+  }
+
+  /**
+   * Get timeout based on template default and complexity.
+   */
+  private getTimeout<TInput, TOutput>(
+    template: AgenticTaskTemplate<TInput, TOutput>,
+    complexity: AnalysisComplexity
+  ): number {
+    const base = template.timeout ?? 120_000;
+    switch (complexity) {
+      case 'lightweight': return Math.min(base, 60_000);
+      case 'standard': return base;
+      case 'thorough': return base * 2;
+      default: return base;
+    }
+  }
+}
+
+/**
+ * Merge two knowledge query results, deduplicating playbooks by ID.
+ */
+function mergeKnowledge(
+  base: MemoryQueryResultV2,
+  additional?: MemoryQueryResultV2
+): MemoryQueryResultV2 {
+  if (!additional) return base;
+
+  const seenPlaybookIds = new Set(base.playbooks.map(p => p.playbook.id));
+  const mergedPlaybooks = [...base.playbooks];
+  for (const match of additional.playbooks) {
+    if (!seenPlaybookIds.has(match.playbook.id)) {
+      mergedPlaybooks.push(match);
+      seenPlaybookIds.add(match.playbook.id);
+    }
+  }
+
+  const seenExpIds = new Set(base.experiences.map(e => e.experience.id));
+  const mergedExperiences = [...base.experiences];
+  for (const exp of additional.experiences) {
+    if (!seenExpIds.has(exp.experience.id)) {
+      mergedExperiences.push(exp);
+    }
+  }
+
+  return {
+    playbooks: mergedPlaybooks,
+    experiences: mergedExperiences,
+  };
+}
+
+/**
+ * Create an AgenticTaskRunner instance.
+ */
+export function createAgenticTaskRunner(
+  workspaceManager: WorkspaceManager,
+  agentManager: AgentManager,
+  memory: MemorySystem,
+  learningPipeline: TrajectoryProcessor,
+  config: AgenticTaskRunnerConfig,
+): AgenticTaskRunner {
+  return new AgenticTaskRunner(
+    workspaceManager,
+    agentManager,
+    memory,
+    learningPipeline,
+    config,
+  );
+}

package/src/workspace/skill-converter.ts

@@ -0,0 +1,288 @@
+import type { Playbook } from '../types/playbook.js';
+import type { AgentSkillSpec } from './types.js';
+
+/**
+ * Convert Playbooks to Agent Skills (SKILL.md format).
+ * Playbooks are cognitive-core's internal format; SKILL.md is the
+ * portable open standard used in agentic workspaces.
+ */
+export function convertPlaybooksToSkills(playbooks: Playbook[]): AgentSkillSpec[] {
+  return playbooks.map(playbook => ({
+    name: playbook.name,
+    content: generateSkillMd(playbook),
+    source: 'playbook-conversion' as const,
+  }));
+}
+
+/**
+ * Generate a SKILL.md file from a Playbook.
+ */
+export function generateSkillMd(playbook: Playbook): string {
+  const sections: string[] = [];
+
+  // Title
+  sections.push(`# ${formatName(playbook.name)}`);
+  sections.push('');
+
+  // When to Use
+  if (playbook.applicability.situations.length > 0) {
+    sections.push('## When to Use');
+    sections.push('');
+    for (const situation of playbook.applicability.situations) {
+      sections.push(`- ${situation}`);
+    }
+    sections.push('');
+  }
+
+  // Triggers
+  if (playbook.applicability.triggers.length > 0) {
+    sections.push('## Triggers');
+    sections.push('');
+    for (const trigger of playbook.applicability.triggers) {
+      sections.push(`- ${trigger}`);
+    }
+    sections.push('');
+  }
+
+  // When NOT to Use
+  if (playbook.applicability.antiPatterns.length > 0) {
+    sections.push('## When NOT to Use');
+    sections.push('');
+    for (const anti of playbook.applicability.antiPatterns) {
+      sections.push(`- ${anti}`);
+    }
+    sections.push('');
+  }
+
+  // Strategy
+  sections.push('## Strategy');
+  sections.push('');
+  sections.push(playbook.guidance.strategy);
+  sections.push('');
+
+  // Tactics
+  if (playbook.guidance.tactics.length > 0) {
+    sections.push('## Tactics');
+    sections.push('');
+    for (const tactic of playbook.guidance.tactics) {
+      sections.push(`- ${tactic}`);
+    }
+    sections.push('');
+  }
+
+  // Steps
+  if (playbook.guidance.steps && playbook.guidance.steps.length > 0) {
+    sections.push('## Steps');
+    sections.push('');
+    for (let i = 0; i < playbook.guidance.steps.length; i++) {
+      sections.push(`${i + 1}. ${playbook.guidance.steps[i]}`);
+    }
+    sections.push('');
+  }
+
+  // Code Example
+  if (playbook.guidance.codeExample) {
+    sections.push('## Example');
+    sections.push('');
+    sections.push('```');
+    sections.push(playbook.guidance.codeExample);
+    sections.push('```');
+    sections.push('');
+  }
+
+  // Verification
+  if (playbook.verification.successIndicators.length > 0 ||
+      playbook.verification.failureIndicators.length > 0) {
+    sections.push('## Verification');
+    sections.push('');
+    if (playbook.verification.successIndicators.length > 0) {
+      sections.push('**Success indicators:**');
+      for (const indicator of playbook.verification.successIndicators) {
+        sections.push(`- ${indicator}`);
+      }
+    }
+    if (playbook.verification.failureIndicators.length > 0) {
+      sections.push('');
+      sections.push('**Failure indicators:**');
+      for (const indicator of playbook.verification.failureIndicators) {
+        sections.push(`- ${indicator}`);
+      }
+    }
+    sections.push('');
+  }
+
+  // Context-specific refinements
+  if (playbook.evolution.refinements.length > 0) {
+    sections.push('## Context Notes');
+    sections.push('');
+    for (const refinement of playbook.evolution.refinements) {
+      sections.push(`- **${refinement.context}**: ${refinement.addition}`);
+    }
+    sections.push('');
+  }
+
+  // Metadata footer
+  sections.push('---');
+  sections.push('');
+  sections.push(`*Confidence: ${Math.round(playbook.confidence * 100)}% | ` +
+    `Complexity: ${playbook.complexity} | ` +
+    `Domains: ${playbook.applicability.domains.join(', ') || 'general'}*`);
+
+  return sections.join('\n');
+}
+
+/**
+ * Parse a SKILL.md file back into Playbook fields.
+ * Best-effort parsing — handles optional/missing sections gracefully.
+ */
+export function parseSkillMdToPlaybook(skillMd: string, skillName: string): Partial<Playbook> {
+  const sections = parseSections(skillMd);
+
+  const situations = extractListItems(sections['when to use'] ?? '');
+  const triggers = extractListItems(sections['triggers'] ?? '');
+  const antiPatterns = extractListItems(sections['when not to use'] ?? '');
+  const strategy = (sections['strategy'] ?? '').trim();
+  const tactics = extractListItems(sections['tactics'] ?? '');
+  const steps = extractNumberedItems(sections['steps'] ?? '');
+  const codeExample = extractCodeBlock(sections['example'] ?? '');
+
+  const verificationContent = sections['verification'] ?? '';
+  const successIndicators = extractListAfterHeading(verificationContent, 'Success indicators');
+  const failureIndicators = extractListAfterHeading(verificationContent, 'Failure indicators');
+
+  // Parse metadata from footer
+  const domains: string[] = [];
+  let confidence = 0.5;
+  let complexity: 'simple' | 'moderate' | 'complex' = 'moderate';
+
+  const metaMatch = skillMd.match(/\*Confidence:\s*(\d+)%\s*\|\s*Complexity:\s*(\w+)\s*\|\s*Domains:\s*(.+?)\*/);
+  if (metaMatch) {
+    confidence = parseInt(metaMatch[1], 10) / 100;
+    complexity = metaMatch[2] as 'simple' | 'moderate' | 'complex';
+    const domainStr = metaMatch[3].trim();
+    if (domainStr && domainStr !== 'general') {
+      domains.push(...domainStr.split(',').map(d => d.trim()));
+    }
+  }
+
+  return {
+    name: skillName,
+    applicability: {
+      situations,
+      triggers,
+      antiPatterns,
+      domains,
+    },
+    guidance: {
+      strategy,
+      tactics,
+      steps: steps.length > 0 ? steps : undefined,
+      codeExample: codeExample || undefined,
+    },
+    verification: {
+      successIndicators,
+      failureIndicators,
+    },
+    confidence,
+    complexity,
+  };
+}
+
+// ================================================================
+// Helpers
+// ================================================================
+
+/**
+ * Convert kebab-case name to title case.
+ */
+function formatName(name: string): string {
+  return name
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+/**
+ * Parse markdown into sections by h2 headers.
+ */
+function parseSections(md: string): Record<string, string> {
+  const sections: Record<string, string> = {};
+  const lines = md.split('\n');
+  let currentSection = '';
+  let currentContent: string[] = [];
+
+  for (const line of lines) {
+    const h2Match = line.match(/^##\s+(.+)/);
+    if (h2Match) {
+      if (currentSection) {
+        sections[currentSection.toLowerCase()] = currentContent.join('\n');
+      }
+      currentSection = h2Match[1].trim();
+      currentContent = [];
+    } else {
+      currentContent.push(line);
+    }
+  }
+
+  if (currentSection) {
+    sections[currentSection.toLowerCase()] = currentContent.join('\n');
+  }
+
+  return sections;
+}
+
+/**
+ * Extract bullet list items from a markdown section.
+ */
+function extractListItems(content: string): string[] {
+  return content
+    .split('\n')
+    .filter(line => line.match(/^\s*-\s+/))
+    .map(line => line.replace(/^\s*-\s+/, '').trim())
+    .filter(item => item.length > 0);
+}
+
+/**
+ * Extract numbered list items from a markdown section.
+ */
+function extractNumberedItems(content: string): string[] {
+  return content
+    .split('\n')
+    .filter(line => line.match(/^\s*\d+\.\s+/))
+    .map(line => line.replace(/^\s*\d+\.\s+/, '').trim())
+    .filter(item => item.length > 0);
+}
+
+/**
+ * Extract a fenced code block from a markdown section.
+ */
+function extractCodeBlock(content: string): string {
+  const match = content.match(/```[\w]*\n([\s\S]*?)```/);
+  return match ? match[1].trim() : '';
+}
+
+/**
+ * Extract list items that follow a bold heading within a section.
+ */
+function extractListAfterHeading(content: string, heading: string): string[] {
+  const lines = content.split('\n');
+  const results: string[] = [];
+  let capturing = false;
+
+  for (const line of lines) {
+    if (line.includes(`**${heading}`)) {
+      capturing = true;
+      continue;
+    }
+    if (capturing) {
+      if (line.match(/^\s*-\s+/)) {
+        results.push(line.replace(/^\s*-\s+/, '').trim());
+      } else if (line.trim() === '' || line.match(/^\*\*/)) {
+        // Empty line or new bold heading stops capture
+        capturing = false;
+      }
+    }
+  }
+
+  return results;
+}

package/src/workspace/templates/index.ts

@@ -0,0 +1,64 @@
+// Trajectory Analysis (replaces TrajectoryAnalyzer — tasks 1-4)
+export {
+  trajectoryAnalysisTemplate,
+  type TrajectoryAnalysisInput,
+} from './trajectory-analysis.js';
+
+// Playbook Extraction (replaces PlaybookExtractor + LLMPlaybookExtractor — tasks 5-6)
+export {
+  playbookExtractionTemplate,
+  type PlaybookExtractionInput,
+} from './playbook-extraction.js';
+
+// Usage Inference (replaces PlaybookUsageInference — task 7)
+export {
+  usageInferenceTemplate,
+  type UsageInferenceInput,
+} from './usage-inference.js';
+
+// Meta-Reflection (replaces MetaLearner.generateReflection — task 8)
+export {
+  metaReflectionTemplate,
+  type MetaReflectionInput,
+  type MetaReflectionOutput,
+} from './meta-reflection.js';
+
+// Solution Evaluation (enhances SolutionEvaluator — task 9)
+export {
+  solutionEvaluationTemplate,
+  type SolutionEvaluationInput,
+} from './solution-evaluation.js';
+
+// Refinement Analysis (enhances RefinementLoop — task 10)
+export {
+  refinementAnalysisTemplate,
+  type RefinementAnalysisInput,
+  type RefinementPlan,
+} from './refinement-analysis.js';
+
+// Knowledge Extraction (semantic memory — Phase 2)
+export {
+  knowledgeExtractionTemplate,
+  type KnowledgeExtractionInput,
+} from './knowledge-extraction.js';
+
+// Knowledge Defragmentation (semantic memory — Phase 3)
+export {
+  knowledgeDefragTemplate,
+  type KnowledgeDefragInput,
+} from './knowledge-defrag.js';
+
+// Team Trajectory Analysis (team-aware learning — task 13)
+export {
+  teamTrajectoryAnalysisTemplate,
+  type TeamTrajectoryAnalysisInput,
+} from './team-trajectory-analysis.js';
+
+// Team Playbook Extraction (team-aware learning — task 14)
+export {
+  teamPlaybookExtractionTemplate,
+  type TeamPlaybookExtractionInput,
+  type TeamPlaybookExtractionOutput,
+  type TeamPlaybookUpdate,
+  type RolePlaybookUpdate,
+} from './team-playbook-extraction.js';