cognitive-core 0.0.2 → 0.1.2

package/src/utils/validation.ts

@@ -0,0 +1,286 @@
+/**
+ * Input validation utilities
+ * Provides validation helpers for API boundaries
+ */
+
+import { z } from 'zod';
+
+/**
+ * Validation error with details
+ */
+export class ValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly field: string,
+    public readonly value: unknown
+  ) {
+    super(`Validation error for '${field}': ${message}`);
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * Validate a string field
+ */
+export function validateString(
+  value: unknown,
+  field: string,
+  options?: {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    allowEmpty?: boolean;
+  }
+): string {
+  if (typeof value !== 'string') {
+    throw new ValidationError(`Expected string, got ${typeof value}`, field, value);
+  }
+
+  const str = value;
+  const opts = options ?? {};
+
+  if (!opts.allowEmpty && str.trim().length === 0) {
+    throw new ValidationError('Cannot be empty', field, value);
+  }
+
+  if (opts.minLength !== undefined && str.length < opts.minLength) {
+    throw new ValidationError(`Must be at least ${opts.minLength} characters`, field, value);
+  }
+
+  if (opts.maxLength !== undefined && str.length > opts.maxLength) {
+    throw new ValidationError(`Must be at most ${opts.maxLength} characters`, field, value);
+  }
+
+  if (opts.pattern && !opts.pattern.test(str)) {
+    throw new ValidationError(`Does not match required pattern`, field, value);
+  }
+
+  return str;
+}
+
+/**
+ * Validate an optional string field
+ */
+export function validateOptionalString(
+  value: unknown,
+  field: string,
+  options?: {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+  }
+): string | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  return validateString(value, field, options);
+}
+
+/**
+ * Validate a number field
+ */
+export function validateNumber(
+  value: unknown,
+  field: string,
+  options?: {
+    min?: number;
+    max?: number;
+    integer?: boolean;
+  }
+): number {
+  if (typeof value !== 'number' || isNaN(value)) {
+    throw new ValidationError(`Expected number, got ${typeof value}`, field, value);
+  }
+
+  const opts = options ?? {};
+
+  if (opts.integer && !Number.isInteger(value)) {
+    throw new ValidationError('Must be an integer', field, value);
+  }
+
+  if (opts.min !== undefined && value < opts.min) {
+    throw new ValidationError(`Must be at least ${opts.min}`, field, value);
+  }
+
+  if (opts.max !== undefined && value > opts.max) {
+    throw new ValidationError(`Must be at most ${opts.max}`, field, value);
+  }
+
+  return value;
+}
+
+/**
+ * Validate an optional number field
+ */
+export function validateOptionalNumber(
+  value: unknown,
+  field: string,
+  options?: {
+    min?: number;
+    max?: number;
+    integer?: boolean;
+  }
+): number | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  return validateNumber(value, field, options);
+}
+
+/**
+ * Validate an array field
+ */
+export function validateArray<T>(
+  value: unknown,
+  field: string,
+  itemValidator: (item: unknown, index: number) => T,
+  options?: {
+    minLength?: number;
+    maxLength?: number;
+  }
+): T[] {
+  if (!Array.isArray(value)) {
+    throw new ValidationError(`Expected array, got ${typeof value}`, field, value);
+  }
+
+  const opts = options ?? {};
+
+  if (opts.minLength !== undefined && value.length < opts.minLength) {
+    throw new ValidationError(`Must have at least ${opts.minLength} items`, field, value);
+  }
+
+  if (opts.maxLength !== undefined && value.length > opts.maxLength) {
+    throw new ValidationError(`Must have at most ${opts.maxLength} items`, field, value);
+  }
+
+  return value.map((item, index) => itemValidator(item, index));
+}
+
+/**
+ * Validate a vector (array of numbers) for embeddings
+ */
+export function validateVector(
+  value: unknown,
+  field: string,
+  expectedDimension?: number
+): number[] {
+  if (!Array.isArray(value)) {
+    throw new ValidationError(`Expected array, got ${typeof value}`, field, value);
+  }
+
+  for (let i = 0; i < value.length; i++) {
+    if (typeof value[i] !== 'number' || isNaN(value[i])) {
+      throw new ValidationError(
+        `Element at index ${i} is not a valid number`,
+        field,
+        value[i]
+      );
+    }
+  }
+
+  if (expectedDimension !== undefined && value.length !== expectedDimension) {
+    throw new ValidationError(
+      `Expected dimension ${expectedDimension}, got ${value.length}`,
+      field,
+      value
+    );
+  }
+
+  return value as number[];
+}
+
+/**
+ * Validate task input parameters
+ */
+export const TaskInputSchema = z.object({
+  description: z.string().min(1, 'Task description cannot be empty'),
+  domain: z.string().default('general'),
+  context: z.record(z.unknown()).default({}),
+  constraints: z.array(z.string()).default([]),
+  metadata: z.record(z.unknown()).default({}),
+});
+
+export type TaskInput = z.infer<typeof TaskInputSchema>;
+
+/**
+ * Validate task input
+ */
+export function validateTaskInput(input: unknown): TaskInput {
+  const result = TaskInputSchema.safeParse(input);
+  if (!result.success) {
+    const firstError = result.error.errors[0];
+    throw new ValidationError(
+      firstError.message,
+      firstError.path.join('.'),
+      input
+    );
+  }
+  return result.data;
+}
+
+/**
+ * Validate trajectory step count
+ */
+export function validateTrajectoryStepCount(
+  stepCount: number,
+  options?: {
+    minSteps?: number;
+    maxSteps?: number;
+  }
+): void {
+  const opts = options ?? { minSteps: 1, maxSteps: 10000 };
+
+  if (stepCount < (opts.minSteps ?? 1)) {
+    throw new ValidationError(
+      `Must have at least ${opts.minSteps ?? 1} steps`,
+      'steps',
+      stepCount
+    );
+  }
+
+  if (opts.maxSteps !== undefined && stepCount > opts.maxSteps) {
+    throw new ValidationError(
+      `Must have at most ${opts.maxSteps} steps`,
+      'steps',
+      stepCount
+    );
+  }
+}
+
+/**
+ * MCP tool argument validation schemas
+ */
+export const MCPSearchPlaybooksSchema = z.object({
+  query: z.string().min(1, 'Query cannot be empty'),
+  domain: z.string().optional(),
+  maxResults: z.number().int().min(1).max(50).optional(),
+});
+
+export const MCPGetPlaybookDetailsSchema = z.object({
+  playbookId: z.string().min(1, 'Playbook ID cannot be empty'),
+});
+
+export const MCPGetPlaybooksByDomainSchema = z.object({
+  domain: z.string().min(1, 'Domain cannot be empty'),
+  maxResults: z.number().int().min(1).max(100).optional(),
+});
+
+/**
+ * Validate MCP tool arguments
+ */
+export function validateMCPArgs<T>(
+  schema: z.ZodSchema<T>,
+  args: unknown,
+  toolName: string
+): T {
+  const result = schema.safeParse(args);
+  if (!result.success) {
+    const firstError = result.error.errors[0];
+    throw new ValidationError(
+      `Invalid arguments for ${toolName}: ${firstError.message}`,
+      firstError.path.join('.') || 'arguments',
+      args
+    );
+  }
+  return result.data;
+}

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,
+  );
+}