cognitive-core 0.2.4 → 0.3.1

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

@@ -1,234 +0,0 @@
-/**
- * Trajectory Analysis Template
- *
- * Replaces the heuristic TrajectoryAnalyzer with workspace-based agentic analysis.
- * Consolidates credit assignment, key step identification, error pattern detection,
- * and abstractability assessment into a single template.
- *
- * - Simple, short successful trajectories → heuristic fallback (zero cost)
- * - Failed or complex trajectories → agent analyzes semantically
- */
-
-import type { WorkspaceHandle } from 'agent-workspace';
-import type { Trajectory, CreditStrategy } from '../../types/index.js';
-import type { AnalysisResult, ErrorPattern, TrainingExample } from '../../learning/analyzer.js';
-import { createAnalyzer } from '../../learning/analyzer.js';
-import type {
-  AgenticTaskTemplate,
-  AnalysisComplexity,
-  ProcessingContext,
-} from '../types.js';
-import type { ComputeRequirements } from '../../runtime/compute-provider.js';
-
-// ============================================================
-// Input / Output Types
-// ============================================================
-
-export interface TrajectoryAnalysisInput {
-  trajectory: Trajectory;
-  creditStrategy: CreditStrategy;
-}
-
-// Output is AnalysisResult (reused from learning/analyzer.ts)
-// No new types needed.
-
-// ============================================================
-// Template Implementation
-// ============================================================
-
-export const trajectoryAnalysisTemplate: AgenticTaskTemplate<
-  TrajectoryAnalysisInput,
-  AnalysisResult
-> = {
-  taskType: 'trajectory-analysis',
-  domain: 'trajectory-analysis',
-  description: 'Analyze agent trajectory for credit assignment, key steps, error patterns, and abstractability',
-
-  // === COMPLEXITY ASSESSMENT ===
-
-  assessComplexity(input: TrajectoryAnalysisInput): AnalysisComplexity {
-    const { trajectory } = input;
-
-    // Short successful trajectories → heuristic (existing analyzer is fine)
-    if (trajectory.steps.length <= 5 && trajectory.outcome.success) {
-      return 'heuristic';
-    }
-
-    // Very short trajectories (even if failed) → lightweight
-    if (trajectory.steps.length <= 3) {
-      return 'lightweight';
-    }
-
-    // Failed trajectories benefit most from semantic analysis
-    if (!trajectory.outcome.success) {
-      return 'standard';
-    }
-
-    // Long trajectories need agent to identify what actually mattered
-    if (trajectory.steps.length > 20) {
-      return 'standard';
-    }
-
-    return 'lightweight';
-  },
-
-  // === HEURISTIC FALLBACK ===
-
-  async heuristicFallback(input: TrajectoryAnalysisInput): Promise<AnalysisResult> {
-    const analyzer = createAnalyzer(input.creditStrategy);
-    return analyzer.analyze(input.trajectory);
-  },
-
-  // === WORKSPACE SETUP ===
-
-  async prepareWorkspace(
-    input: TrajectoryAnalysisInput,
-    handle: WorkspaceHandle
-  ): Promise<void> {
-    // Write trajectory context
-    const { trajectory } = input;
-    await handle.writeJson('input', 'context.json', {
-      taskId: trajectory.task.id,
-      taskDomain: trajectory.task.domain,
-      taskDescription: trajectory.task.description,
-      outcome: {
-        success: trajectory.outcome.success,
-        partialScore: trajectory.outcome.partialScore,
-        errorInfo: trajectory.outcome.errorInfo,
-      },
-      stepCount: trajectory.steps.length,
-      wallTimeSeconds: trajectory.wallTimeSeconds,
-      llmCalls: trajectory.llmCalls,
-      totalTokens: trajectory.totalTokens,
-    });
-
-    // Write steps as JSONL for efficient processing
-    await handle.writeJsonl('input', 'steps.jsonl',
-      trajectory.steps.map((step, i) => ({
-        index: i,
-        thought: step.thought,
-        action: step.action,
-        observation: step.observation,
-        metadata: step.metadata,
-      }))
-    );
-  },
-
-  // === PROMPT ===
-
-  buildTaskPrompt(input: TrajectoryAnalysisInput): string {
-    const { trajectory } = input;
-    const outcomeStr = trajectory.outcome.success ? 'SUCCESSFUL' : 'FAILED';
-
-    return [
-      `Analyze this ${outcomeStr} agent trajectory (${trajectory.steps.length} steps, ${trajectory.wallTimeSeconds}s wall time).`,
-      '',
-      'Read the trajectory from input/context.json and input/steps.jsonl.',
-      '',
-      'Perform the following analyses:',
-      '',
-      '1. **Credit Assignment**: For each step, assign an attribution score (0.0 to 1.0)',
-      '   indicating how much that step contributed to the final outcome.',
-      '   Consider causal impact, not just proximity to the end.',
-      '',
-      '2. **Key Steps**: Identify the indices of pivotal steps (attribution >= 0.15).',
-      '',
-      '3. **Error Patterns**: Detect any error patterns (type, signature, description, optional fix).',
-      '   Look for: timeouts, missing resources, syntax errors, type errors, repeated actions, loops.',
-      '',
-      '4. **Abstractability**: Is this trajectory worth extracting patterns from?',
-      '   Criteria: successful with >= 2 key steps, OR failed with clear error pattern and partial progress.',
-      '',
-      '5. **Training Examples**: Extract thought→action pairs from key steps.',
-      '',
-      'Write your analysis to output/analysis.json with this exact schema:',
-      '```json',
-      '{',
-      '  "success": boolean,',
-      '  "keySteps": number[],',
-      '  "stepAttribution": number[],',
-      '  "errorPatterns": [{ "type": string, "signature": string, "description": string, "suggestedFix"?: string }],',
-      '  "abstractable": boolean,',
-      '  "trainingExamples": [{ "input": string, "output": string, "stepIndex": number }]',
-      '}',
-      '```',
-    ].join('\n');
-  },
-
-  // === SKILLS & RESOURCES ===
-
-  getSkills() {
-    return [];
-  },
-
-  getResources() {
-    return [];
-  },
-
-  // === OUTPUT ===
-
-  outputConfig: {
-    files: [
-      {
-        path: 'analysis.json',
-        format: 'json' as const,
-        required: true,
-        description: 'Trajectory analysis result with credit assignment, key steps, error patterns',
-      },
-    ],
-  },
-
-  async collectOutput(handle: WorkspaceHandle): Promise<AnalysisResult> {
-    const raw = await handle.readJson('output', 'analysis.json');
-    const data = raw as Record<string, unknown>;
-
-    // Validate and coerce the output into AnalysisResult
-    return {
-      success: Boolean(data.success),
-      keySteps: Array.isArray(data.keySteps) ? data.keySteps.map(Number) : [],
-      stepAttribution: Array.isArray(data.stepAttribution)
-        ? data.stepAttribution.map(Number)
-        : [],
-      errorPatterns: Array.isArray(data.errorPatterns)
-        ? (data.errorPatterns as ErrorPattern[])
-        : [],
-      abstractable: Boolean(data.abstractable),
-      trainingExamples: Array.isArray(data.trainingExamples)
-        ? (data.trainingExamples as TrainingExample[])
-        : [],
-    };
-  },
-
-  async processOutput(
-    _output: AnalysisResult,
-    _input: TrajectoryAnalysisInput,
-    _context: ProcessingContext
-  ): Promise<void> {
-    // No side effects during analysis — the pipeline handles storage
-  },
-
-  // === COMPUTE ===
-
-  computeRequirements: {
-    mode: 'local',
-    complexity: 'lightweight',
-  },
-
-  getComputeRequirements(
-    _input: TrajectoryAnalysisInput,
-    complexity: AnalysisComplexity
-  ): ComputeRequirements {
-    return {
-      mode: 'local',
-      complexity,
-      // Standard analysis can take a bit longer
-      timeout: complexity === 'standard' ? 180_000 : 120_000,
-    };
-  },
-
-  // === CONFIG ===
-
-  agentType: 'claude-code',
-  timeout: 120_000,
-  captureToolCalls: true,
-};

package/src/workspace/templates/usage-inference.ts

@@ -1,163 +0,0 @@
-/**
- * Usage Inference Template
- *
- * Replaces the heuristic PlaybookUsageInference with workspace-based
- * semantic matching that determines which injected playbooks were
- * actually followed by the agent.
- *
- * - No playbooks or very few steps → heuristic fallback
- * - Otherwise → agent reads trajectory and judges playbook adherence
- */
-
-import type { WorkspaceHandle } from 'agent-workspace';
-import type { Trajectory, Playbook } from '../../types/index.js';
-import type { PlaybookUsageResult } from '../../learning/usage-inference.js';
-import { createUsageInference } from '../../learning/usage-inference.js';
-import type {
-  AgenticTaskTemplate,
-  AnalysisComplexity,
-} from '../types.js';
-
-// ============================================================
-// Input / Output Types
-// ============================================================
-
-export interface UsageInferenceInput {
-  trajectory: Trajectory;
-  injectedPlaybooks: Playbook[];
-}
-
-// Output: PlaybookUsageResult[] (reused from learning/usage-inference.ts)
-
-// ============================================================
-// Template Implementation
-// ============================================================
-
-export const usageInferenceTemplate: AgenticTaskTemplate<
-  UsageInferenceInput,
-  PlaybookUsageResult[]
-> = {
-  taskType: 'usage-inference',
-  domain: 'usage-inference',
-  description: 'Determine which injected playbooks were actually followed',
-
-  assessComplexity(input: UsageInferenceInput): AnalysisComplexity {
-    if (input.injectedPlaybooks.length === 0) return 'heuristic';
-    if (input.injectedPlaybooks.length <= 2 && input.trajectory.steps.length <= 10) {
-      return 'heuristic';
-    }
-    return 'lightweight';
-  },
-
-  async heuristicFallback(input: UsageInferenceInput): Promise<PlaybookUsageResult[]> {
-    const inference = createUsageInference();
-    return inference.inferUsage(input.trajectory, input.injectedPlaybooks);
-  },
-
-  async prepareWorkspace(
-    input: UsageInferenceInput,
-    handle: WorkspaceHandle
-  ): Promise<void> {
-    const { trajectory, injectedPlaybooks } = input;
-
-    // Write trajectory summary + steps
-    await handle.writeJson('input', 'trajectory.json', {
-      taskDescription: trajectory.task.description,
-      domain: trajectory.task.domain,
-      success: trajectory.outcome.success,
-      stepCount: trajectory.steps.length,
-      steps: trajectory.steps.map((step, i) => ({
-        index: i,
-        thought: step.thought,
-        action: step.action,
-        observation: step.observation?.slice(0, 300),
-      })),
-    });
-
-    // Write injected playbooks
-    await handle.writeJson('input', 'playbooks.json',
-      injectedPlaybooks.map(pb => ({
-        id: pb.id,
-        name: pb.name,
-        strategy: pb.guidance.strategy,
-        tactics: pb.guidance.tactics,
-        steps: pb.guidance.steps,
-        successIndicators: pb.verification.successIndicators,
-      }))
-    );
-  },
-
-  buildTaskPrompt(input: UsageInferenceInput): string {
-    return [
-      `Analyze whether the agent followed ${input.injectedPlaybooks.length} injected playbooks.`,
-      '',
-      'Read input/trajectory.json for the agent execution trace.',
-      'Read input/playbooks.json for the playbooks that were injected.',
-      '',
-      'For each playbook, determine:',
-      '1. Was the playbook guidance followed? Look for tactical alignment, not literal matches.',
-      '2. How confident are you? (0.0-1.0)',
-      '3. Was the outcome successful when following this guidance?',
-      '4. Which trajectory steps aligned with the playbook?',
-      '',
-      'Write results to output/usage.json:',
-      '```json',
-      '[',
-      '  {',
-      '    "playbookId": "id",',
-      '    "playbookName": "name",',
-      '    "wasUsed": boolean,',
-      '    "usageConfidence": 0.0-1.0,',
-      '    "wasSuccessful": boolean,',
-      '    "matchedSteps": [step indices],',
-      '    "context": "brief explanation of usage or non-usage"',
-      '  }',
-      ']',
-      '```',
-    ].join('\n');
-  },
-
-  getSkills() { return []; },
-  getResources() { return []; },
-
-  outputConfig: {
-    files: [
-      {
-        path: 'usage.json',
-        format: 'json' as const,
-        required: true,
-        description: 'Playbook usage inference results',
-      },
-    ],
-  },
-
-  async collectOutput(handle: WorkspaceHandle): Promise<PlaybookUsageResult[]> {
-    const raw = await handle.readJson('output', 'usage.json');
-    if (!Array.isArray(raw)) return [];
-
-    return (raw as Record<string, unknown>[]).map(item => ({
-      playbookId: String(item.playbookId ?? ''),
-      playbookName: String(item.playbookName ?? ''),
-      wasUsed: Boolean(item.wasUsed),
-      usageConfidence: typeof item.usageConfidence === 'number' ? item.usageConfidence : 0,
-      wasSuccessful: Boolean(item.wasSuccessful),
-      matchedSteps: Array.isArray(item.matchedSteps)
-        ? item.matchedSteps.map(Number)
-        : [],
-      context: item.context ? String(item.context) : undefined,
-    }));
-  },
-
-  async processOutput(): Promise<void> {
-    // Atlas handles storage and skill library recording
-  },
-
-  computeRequirements: {
-    mode: 'local',
-    complexity: 'lightweight',
-  },
-
-  agentType: 'claude-code',
-  timeout: 120_000,
-  captureToolCalls: true,
-};

package/src/workspace/types.ts

@@ -1,185 +0,0 @@
-import type {
-  TaskTemplate,
-  TaskComplexity,
-  SkillSpec,
-  ResourceSpec as BaseResourceSpec,
-} from 'agent-workspace';
-import type { MemorySystem, MemoryQueryResultV2 } from '../memory/system.js';
-import type { Trajectory } from '../types/index.js';
-import type { ComputeRequirements } from '../runtime/compute-provider.js';
-
-// Re-export agent-workspace types used by consumers
-export type { WorkspaceHandle, OutputSpec, OutputFileSpec, ValidationResult } from 'agent-workspace';
-export type { TaskTemplate, TaskComplexity, SkillSpec, TaskRunner, TaskResult, AgentBackend, AgentSpawnConfig, AgentResult, TaskRunnerHooks, TaskRunnerConfig } from 'agent-workspace';
-
-// ============================================================
-// Agent Skills
-// ============================================================
-
-/**
- * Skill to load into workspace skills/ directory.
- * Extends agent-workspace's SkillSpec with source tracking.
- */
-export interface AgentSkillSpec extends SkillSpec {
-  /** Source of this skill */
-  source: 'playbook-conversion' | 'curated' | 'extracted';
-}
-
-// ============================================================
-// Resources
-// ============================================================
-
-/**
- * Supplementary resource to load into workspace resources/ directory.
- * Extends agent-workspace's ResourceSpec with description.
- */
-export interface ResourceSpec extends BaseResourceSpec {
-  /** Description for the agent */
-  description?: string;
-}
-
-// ============================================================
-// Complexity Assessment
-// ============================================================
-
-/**
- * Backward-compatible alias for agent-workspace's TaskComplexity.
- */
-export type AnalysisComplexity = TaskComplexity;
-
-// ============================================================
-// Processing Context
-// ============================================================
-
-/**
- * Context passed to processOutput for storing/accumulating results.
- */
-/**
- * Minimal pipeline interface for workspace processing context.
- * Satisfied by both LearningPipeline and UnifiedLearningPipeline.
- */
-export interface TrajectoryProcessor {
-  processTrajectory(trajectory: Trajectory, ...args: unknown[]): Promise<unknown>;
-}
-
-export interface ProcessingContext {
-  memory: MemorySystem;
-  learningPipeline: TrajectoryProcessor;
-}
-
-// ============================================================
-// AgenticTaskTemplate
-// ============================================================
-
-/**
- * Declarative recipe for an agentic analysis task.
- *
- * Extends agent-workspace's TaskTemplate with cognitive-core-specific hooks
- * for memory injection, output processing, and compute requirements.
- *
- * TInput: the typed input data for this analysis
- * TOutput: the typed output the agent produces
- */
-export interface AgenticTaskTemplate<TInput, TOutput> extends TaskTemplate<TInput, TOutput> {
-  // === SKILLS (override with source tracking) ===
-
-  /**
-   * Skills to load into the workspace skills/ directory.
-   * Playbooks from memory are converted to skills via the converter.
-   */
-  getSkills(input: TInput): AgentSkillSpec[];
-
-  // === RESOURCES (override with description) ===
-
-  /**
-   * Supplementary resources for the workspace resources/ directory.
-   */
-  getResources(input: TInput): ResourceSpec[];
-
-  // === KNOWLEDGE (cognitive-core extension) ===
-
-  /**
-   * Additional memory queries beyond the automatic domain-scoped query.
-   */
-  getAdditionalKnowledge?(
-    input: TInput,
-    memory: MemorySystem
-  ): Promise<MemoryQueryResultV2>;
-
-  // === OUTPUT PROCESSING (cognitive-core extension) ===
-
-  /**
-   * Process the validated output — store results, accumulate for batch learning, etc.
-   */
-  processOutput(
-    output: TOutput,
-    input: TInput,
-    context: ProcessingContext
-  ): Promise<void>;
-
-  // === CONFIGURATION ===
-
-  /** Whether to capture detailed tool calls (default: true) */
-  captureToolCalls?: boolean;
-
-  // === COMPUTE (cognitive-core extension) ===
-
-  /**
-   * Static compute requirements for this template.
-   * Used by ComputeProvider to select appropriate backend.
-   */
-  computeRequirements?: ComputeRequirements;
-
-  /**
-   * Dynamic compute requirements based on input and assessed complexity.
-   * Overrides static computeRequirements when provided.
-   */
-  getComputeRequirements?(
-    input: TInput,
-    complexity: AnalysisComplexity
-  ): ComputeRequirements;
-}
-
-// ============================================================
-// Task Result
-// ============================================================
-
-/**
- * Result from running an agentic task.
- */
-export interface AgenticTaskResult<TOutput> {
-  /** The validated output */
-  output: TOutput;
-  /** Whether heuristic or agentic path was used */
-  method: 'heuristic' | 'agentic';
-  /** Trajectory ID of the analysis agent (if agentic) */
-  agentTrajectoryId?: string;
-  /** Execution metrics */
-  metrics: AgenticTaskMetrics;
-}
-
-/**
- * Metrics from an agentic task execution.
- */
-export interface AgenticTaskMetrics {
-  totalTimeMs: number;
-  tokensUsed: number;
-  toolCalls: number;
-}
-
-// ============================================================
-// Errors
-// ============================================================
-
-/**
- * Error thrown when agent output validation fails.
- */
-export class AgenticTaskOutputError extends Error {
-  constructor(
-    public readonly taskType: string,
-    public readonly cause: Error
-  ) {
-    super(`Agentic task '${taskType}' output validation failed: ${cause.message}`);
-    this.name = 'AgenticTaskOutputError';
-  }
-}