cognitive-core 0.1.0 → 0.1.2

package/src/types/trajectory-source.ts

@@ -0,0 +1,47 @@
+import type { Trajectory } from './trajectory.js';
+import type { AnalysisResult } from '../learning/analyzer.js';
+
+// ============================================================================
+// Trajectory Source — formal interface for loading trajectories
+// ============================================================================
+
+/**
+ * A trajectory paired with its optional pre-computed analysis.
+ * If analysis is missing, the consumer should compute it.
+ */
+export interface TrajectoryWithAnalysis {
+  trajectory: Trajectory;
+  analysis?: AnalysisResult;
+}
+
+/**
+ * Options for filtering trajectories when loading.
+ */
+export interface TrajectoryLoadOptions {
+  /** Only load trajectories created after this date */
+  since?: Date;
+  /** Filter to a specific domain */
+  domain?: string;
+  /** Maximum number of trajectories to return */
+  limit?: number;
+  /** Only include successful trajectories */
+  successOnly?: boolean;
+}
+
+/**
+ * TrajectorySource — abstract interface for loading trajectories from
+ * different backends (in-memory arrays, filesystem, pipeline accumulators, etc.).
+ *
+ * Consumers of this interface (e.g. KnowledgeBank.extractFrom) don't care
+ * where trajectories come from — they just load and process them.
+ */
+export interface TrajectorySource {
+  /** Human-readable name for this source */
+  readonly name: string;
+
+  /** Load trajectories, optionally filtered */
+  load(options?: TrajectoryLoadOptions): Promise<TrajectoryWithAnalysis[]>;
+
+  /** Count available trajectories without loading them */
+  count(options?: TrajectoryLoadOptions): Promise<number>;
+}

package/src/utils/frontmatter.ts

@@ -0,0 +1,118 @@
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import {
+  KnowledgeNoteFrontmatterSchema,
+  type KnowledgeNoteFrontmatter,
+  type KnowledgeNote,
+} from '../types/knowledge.js';
+
+const FRONTMATTER_REGEX = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+
+/**
+ * Parse markdown content with YAML frontmatter into a KnowledgeNoteFrontmatter + body.
+ *
+ * Uses the `yaml` npm package for full-fidelity parsing (nested objects,
+ * arrays of objects, etc.). Validates against the Zod schema.
+ *
+ * Returns null frontmatter if the content has no frontmatter block or
+ * if the frontmatter fails validation (logged, not thrown).
+ */
+export function parseKnowledgeFrontmatter(content: string): {
+  frontmatter: KnowledgeNoteFrontmatter | null;
+  body: string;
+} {
+  const match = content.match(FRONTMATTER_REGEX);
+  if (!match) {
+    return { frontmatter: null, body: content };
+  }
+
+  const [, yamlBlock, body] = match;
+
+  try {
+    const raw = parseYaml(yamlBlock);
+    if (!raw || typeof raw !== 'object') {
+      return { frontmatter: null, body };
+    }
+
+    const parsed = KnowledgeNoteFrontmatterSchema.safeParse(raw);
+    if (!parsed.success) {
+      console.warn(
+        `[frontmatter] Validation failed for note: ${JSON.stringify(parsed.error.issues)}`
+      );
+      return { frontmatter: null, body };
+    }
+
+    return { frontmatter: parsed.data, body: body.trim() };
+  } catch (error) {
+    console.warn(
+      `[frontmatter] YAML parse error: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return { frontmatter: null, body: content };
+  }
+}
+
+/**
+ * Serialize a KnowledgeNoteFrontmatter into a YAML frontmatter block.
+ *
+ * Keeps simple top-level fields (created, updated, tags) in a format
+ * that minimem's simpler parser can partially read.
+ */
+export function serializeKnowledgeFrontmatter(
+  frontmatter: KnowledgeNoteFrontmatter
+): string {
+  // Build a clean object for serialization, omitting null/undefined/empty values
+  const obj: Record<string, unknown> = {
+    id: frontmatter.id,
+    type: frontmatter.type,
+  };
+
+  if (frontmatter.domain.length > 0) obj.domain = frontmatter.domain;
+  if (frontmatter.entities.length > 0) obj.entities = frontmatter.entities;
+  if (frontmatter.tags.length > 0) obj.tags = frontmatter.tags;
+
+  obj.confidence = frontmatter.confidence;
+  obj.source = frontmatter.source;
+
+  if (frontmatter.links.length > 0) obj.links = frontmatter.links;
+
+  obj.created = frontmatter.created;
+  obj.updated = frontmatter.updated;
+
+  if (frontmatter.supersedes) obj.supersedes = frontmatter.supersedes;
+
+  const yaml = stringifyYaml(obj, {
+    lineWidth: 120,
+    defaultKeyType: 'PLAIN',
+    defaultStringType: 'PLAIN',
+  });
+
+  return `---\n${yaml}---\n`;
+}
+
+/**
+ * Serialize a full KnowledgeNote (frontmatter + body) into markdown content.
+ */
+export function serializeKnowledgeNote(note: KnowledgeNote): string {
+  const header = serializeKnowledgeFrontmatter(note.frontmatter);
+  return `${header}\n${note.body}\n`;
+}
+
+/**
+ * Parse a full markdown file into a KnowledgeNote.
+ * Returns null if frontmatter is missing or invalid.
+ *
+ * @param content - The raw markdown file content
+ * @param filePath - The file path (stored on the note for reference)
+ */
+export function parseKnowledgeNote(
+  content: string,
+  filePath: string
+): KnowledgeNote | null {
+  const { frontmatter, body } = parseKnowledgeFrontmatter(content);
+  if (!frontmatter) return null;
+
+  return {
+    frontmatter,
+    body,
+    filePath,
+  };
+}

package/src/utils/index.ts

@@ -36,3 +36,10 @@ export {
   MCPGetPlaybooksByDomainSchema,
   type TaskInput,
 } from './validation.js';
+
+export {
+  parseKnowledgeFrontmatter,
+  serializeKnowledgeFrontmatter,
+  serializeKnowledgeNote,
+  parseKnowledgeNote,
+} from './frontmatter.js';

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 type { LearningPipeline } from '../learning/pipeline.js';
+import { createTask } from '../types/task.js';
+import type {
+  AgenticTaskTemplate,
+  AgenticTaskResult,
+  ProcessingContext,
+  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: LearningPipeline,
+    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: LearningPipeline,
+  config: AgenticTaskRunnerConfig,
+): AgenticTaskRunner {
+  return new AgenticTaskRunner(
+    workspaceManager,
+    agentManager,
+    memory,
+    learningPipeline,
+    config,
+  );
+}