cognitive-core 0.2.4 → 0.3.1

package/src/types/meta.ts

@@ -1,218 +0,0 @@
-/**
- * Meta Memory Types
- *
- * Types for meta-learning - learning about learning itself
- * Tracks routing decisions, memory effectiveness, and execution patterns
- */
-
-/**
- * MetaObservation - Records for learning about learning
- * Captures what happened during task execution for later analysis
- */
-export interface MetaObservation {
-  id: string;
-  trajectoryId: string;
-
-  // === ROUTING DECISION ===
-  routing: RoutingObservation;
-
-  // === MEMORY EFFECTIVENESS ===
-  memoryUsage: MemoryUsageObservation;
-
-  // === EXECUTION PATH ===
-  execution: ExecutionObservation;
-
-  // === OUTCOME ===
-  outcome: OutcomeObservation;
-
-  // === LESSONS (LLM-generated reflection) ===
-  lessons: LessonsLearned;
-
-  timestamp: Date;
-}
-
-/**
- * Observation about the routing decision
- */
-export interface RoutingObservation {
-  decision: RoutingDecisionType;
-  confidence: number;
-  reasoning: string;
-}
-
-export type RoutingDecisionType = 'adapt' | 'direct' | 'explore' | 'fallback';
-
-/**
- * Observation about memory retrieval effectiveness
- */
-export interface MemoryUsageObservation {
-  experiencesRetrieved: number;
-  playbooksApplied: string[]; // IDs of playbooks used
-  retrievalQuality: RetrievalQuality;
-}
-
-export type RetrievalQuality = 'helpful' | 'neutral' | 'misleading';
-
-/**
- * Observation about the execution path
- */
-export interface ExecutionObservation {
-  decompositionUsed: boolean;
-  refinementIterations: number;
-  backtrackingOccurred: boolean;
-  toolsUsed: string[];
-}
-
-/**
- * Observation about the outcome
- */
-export interface OutcomeObservation {
-  success: boolean;
-  quality: OutcomeQuality;
-  effortActual: number; // Actual LLM calls
-  effortEstimate: number; // What router predicted
-}
-
-export type OutcomeQuality = 'excellent' | 'good' | 'acceptable' | 'poor';
-
-/**
- * Lessons learned from the execution
- */
-export interface LessonsLearned {
-  whatWorked: string[];
-  whatFailed: string[];
-  suggestions: string[]; // How to do better next time
-}
-
-/**
- * MetaStrategy - Learned patterns about learning itself
- * Used to adjust routing and retrieval based on context
- */
-export interface MetaStrategy {
-  id: string;
-  name: string;
-
-  // When to apply this meta-strategy
-  condition: MetaStrategyCondition;
-
-  // What to do differently
-  adjustment: MetaStrategyAdjustment;
-
-  // Track effectiveness
-  applicationCount: number;
-  successRate: number;
-
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-/**
- * Conditions for applying a meta-strategy
- */
-export interface MetaStrategyCondition {
-  taskCharacteristics: string[]; // "multi-file change", "unfamiliar domain"
-  memoryState: string[]; // "no similar experiences", "low confidence"
-}
-
-/**
- * Adjustments to make when meta-strategy applies
- */
-export interface MetaStrategyAdjustment {
-  routingBias: Partial<Record<RoutingDecisionType, number>>;
-  retrievalModification: string; // "expand query", "include adjacent domains"
-  executionHint: string; // "prefer decomposition", "verify incrementally"
-}
-
-/**
- * Analysis of routing effectiveness
- */
-export interface RoutingAnalysis {
-  byDecision: Record<string, { total: number; successful: number }>;
-  recommendations: string[];
-}
-
-/**
- * Analysis of retrieval quality
- */
-export interface RetrievalAnalysis {
-  helpfulPatterns: string[];
-  misleadingPatterns: string[];
-  recommendations: string[];
-}
-
-/**
- * Statistics about meta-learning
- */
-export interface MetaStats {
-  totalObservations: number;
-  totalStrategies: number;
-  observationsByRouting: Record<RoutingDecisionType, number>;
-  averageSuccessRate: number;
-  recentTrend: 'improving' | 'stable' | 'declining';
-}
-
-/**
- * Context for meta-learning queries
- */
-export interface MetaContext {
-  taskCharacteristics: string[];
-  memoryState: string[];
-}
-
-/**
- * Create a new meta-observation with defaults
- */
-export function createMetaObservation(
-  input: Partial<MetaObservation> & {
-    trajectoryId: string;
-    routing: RoutingObservation;
-    outcome: OutcomeObservation;
-  }
-): MetaObservation {
-  return {
-    id: input.id ?? `meta-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-    trajectoryId: input.trajectoryId,
-    routing: input.routing,
-    memoryUsage: input.memoryUsage ?? {
-      experiencesRetrieved: 0,
-      playbooksApplied: [],
-      retrievalQuality: 'neutral',
-    },
-    execution: input.execution ?? {
-      decompositionUsed: false,
-      refinementIterations: 0,
-      backtrackingOccurred: false,
-      toolsUsed: [],
-    },
-    outcome: input.outcome,
-    lessons: input.lessons ?? {
-      whatWorked: [],
-      whatFailed: [],
-      suggestions: [],
-    },
-    timestamp: input.timestamp ?? new Date(),
-  };
-}
-
-/**
- * Create a new meta-strategy with defaults
- */
-export function createMetaStrategy(
-  input: Partial<MetaStrategy> & {
-    name: string;
-    condition: MetaStrategyCondition;
-    adjustment: MetaStrategyAdjustment;
-  }
-): MetaStrategy {
-  const now = new Date();
-  return {
-    id: input.id ?? `meta-strategy-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-    name: input.name,
-    condition: input.condition,
-    adjustment: input.adjustment,
-    applicationCount: input.applicationCount ?? 0,
-    successRate: input.successRate ?? 0,
-    createdAt: input.createdAt ?? now,
-    updatedAt: input.updatedAt ?? now,
-  };
-}

package/src/types/outcome.ts

@@ -1,66 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Outcome - The result of a task attempt
- */
-export const OutcomeSchema = z.object({
-  /** Whether the task was completed successfully */
-  success: z.boolean(),
-  /** Partial progress score (0.0-1.0) */
-  partialScore: z.number().min(0).max(1).default(0),
-  /** Error information if failed */
-  errorInfo: z.string().optional(),
-  /** Detailed verification results */
-  verificationDetails: z.record(z.unknown()).default({}),
-  /** The final solution/output */
-  solution: z.unknown().optional(),
-});
-
-export type Outcome = z.infer<typeof OutcomeSchema>;
-
-/**
- * Create a successful outcome
- */
-export function successOutcome(
-  solution: unknown,
-  details?: Record<string, unknown>
-): Outcome {
-  return OutcomeSchema.parse({
-    success: true,
-    partialScore: 1.0,
-    solution,
-    verificationDetails: details ?? {},
-  });
-}
-
-/**
- * Create a failed outcome
- */
-export function failureOutcome(
-  errorInfo: string,
-  partialScore = 0,
-  details?: Record<string, unknown>
-): Outcome {
-  return OutcomeSchema.parse({
-    success: false,
-    partialScore,
-    errorInfo,
-    verificationDetails: details ?? {},
-  });
-}
-
-/**
- * Create a partial outcome
- */
-export function partialOutcome(
-  partialScore: number,
-  solution: unknown,
-  details?: Record<string, unknown>
-): Outcome {
-  return OutcomeSchema.parse({
-    success: false,
-    partialScore,
-    solution,
-    verificationDetails: details ?? {},
-  });
-}

package/src/types/playbook.ts

@@ -1,215 +0,0 @@
-/**
- * Playbook Types
- *
- * Playbook - Adaptive guidance that evolves with experience
- * Merges ArcMemo strategies with Claudeception skills + Voyager evolution
- */
-
-/**
- * Playbook - The core learning unit that replaces Strategy + Skill
- * Provides adaptive guidance that evolves based on usage outcomes
- */
-export interface Playbook {
-  id: string;
-  name: string; // kebab-case identifier
-
-  // === APPLICABILITY (when to use) ===
-  applicability: PlaybookApplicability;
-
-  // === GUIDANCE (what to do) ===
-  guidance: PlaybookGuidance;
-
-  // === VERIFICATION (how to know it worked) ===
-  verification: PlaybookVerification;
-
-  // === EVOLUTION (Voyager-style learning) ===
-  evolution: PlaybookEvolution;
-
-  // === PROVENANCE ===
-  provenance?: PlaybookProvenance;
-
-  // === METADATA ===
-  confidence: number; // 0-1, grows with successful use
-  complexity: PlaybookComplexity;
-  estimatedEffort: number; // Rough LLM calls needed
-  embedding?: number[]; // For semantic search
-  createdAt: Date;
-  updatedAt: Date;
-
-  // === PUBLISH HINTS (optional, used by SkillPublisher) ===
-  /**
-   * Whether end-users can invoke this skill directly (e.g. via /slash-command).
-   * Propagated into the published SKILL.md frontmatter as `user-invocable`.
-   */
-  userInvocable?: boolean;
-  /**
-   * Arbitrary key-value metadata propagated verbatim into the published
-   * SKILL.md frontmatter `metadata:` block. Use for ecosystem-specific
-   * fields (audience, component, ecosystem) without changing the core schema.
-   */
-  publishMetadata?: Record<string, unknown>;
-}
-
-/**
- * When to apply this playbook
- */
-export interface PlaybookApplicability {
-  situations: string[]; // High-level: "debugging async code"
-  triggers: string[]; // Concrete: "Promise rejection", "TS2307"
-  antiPatterns: string[]; // When NOT to use (avoids false positives)
-  domains: string[]; // "typescript", "react", "api", "testing"
-}
-
-/**
- * What to do when the playbook applies
- */
-export interface PlaybookGuidance {
-  strategy: string; // High-level approach
-  tactics: string[]; // Mid-level steps
-  steps?: string[]; // Optional concrete commands
-  codeExample?: string; // Optional illustrative code
-}
-
-/**
- * How to verify the playbook worked
- */
-export interface PlaybookVerification {
-  successIndicators: string[]; // "Build passes", "Tests green"
-  failureIndicators: string[]; // "Same error", "New errors introduced"
-  rollbackStrategy?: string; // How to undo if it fails
-}
-
-/**
- * Provenance tracking - where a playbook came from
- */
-export type PlaybookOrigin = 'extracted' | 'curated' | 'imported' | 'manual';
-
-export interface PlaybookProvenance {
-  /** How the playbook was created */
-  origin: PlaybookOrigin;
-  /** For curated: relative path to source file (e.g. "playbooks/typescript-debugging.json") */
-  sourceFile?: string;
-  /** For imported: identifier of the source (e.g. "dash-agent", "community-pack") */
-  importedFrom?: string;
-  /** For curated: who authored it */
-  curatedBy?: string;
-  /** When this provenance was recorded */
-  recordedAt: Date;
-}
-
-/**
- * Evolution tracking for Voyager-style learning
- */
-export interface PlaybookEvolution {
-  version: string; // Semantic versioning
-  createdFrom: string[]; // Source trajectory IDs
-  failures: FailureRecord[]; // What went wrong
-  refinements: Refinement[]; // Context-specific adaptations
-  successCount: number;
-  failureCount: number;
-  lastUsed?: Date;
-  /** Resistance to confidence changes — grows with successful use breadth (EWC-inspired) */
-  consolidationStrength?: number; // default: 0, range [0, 10]
-  /** How many unique domains this playbook has succeeded in */
-  domainBreadth?: number; // default: 0
-}
-
-/**
- * Record of a failure when applying the playbook
- */
-export interface FailureRecord {
-  trajectoryId: string;
-  context: string; // What was different
-  failureMode: string; // How it failed
-  timestamp: Date;
-}
-
-/**
- * Context-specific refinement to the playbook
- */
-export interface Refinement {
-  context: string; // "monorepo", "esm", "legacy codebase"
-  addition: string; // "Also check workspace symlinks"
-  source: 'failure' | 'success' | 'manual';
-  addedAt: Date;
-}
-
-export type PlaybookComplexity = 'simple' | 'moderate' | 'complex';
-
-/**
- * Create a new playbook with defaults
- */
-export function createPlaybook(
-  input: Partial<Playbook> & {
-    name: string;
-    applicability: PlaybookApplicability;
-    guidance: PlaybookGuidance;
-  }
-): Playbook {
-  const now = new Date();
-  return {
-    id: input.id ?? `playbook-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-    name: input.name,
-    applicability: input.applicability,
-    guidance: input.guidance,
-    verification: input.verification ?? {
-      successIndicators: [],
-      failureIndicators: [],
-    },
-    evolution: input.evolution ?? {
-      version: '1.0.0',
-      createdFrom: [],
-      failures: [],
-      refinements: [],
-      successCount: 0,
-      failureCount: 0,
-    },
-    provenance: input.provenance ?? {
-      origin: 'extracted',
-      recordedAt: now,
-    },
-    confidence: input.confidence ?? 0.3, // Start with low confidence
-    complexity: input.complexity ?? 'moderate',
-    estimatedEffort: input.estimatedEffort ?? 3,
-    embedding: input.embedding,
-    userInvocable: input.userInvocable,
-    publishMetadata: input.publishMetadata,
-    createdAt: input.createdAt ?? now,
-    updatedAt: input.updatedAt ?? now,
-  };
-}
-
-/**
- * Bump playbook version
- */
-export function bumpPlaybookVersion(
-  playbook: Playbook,
-  type: 'major' | 'minor' | 'patch' = 'patch'
-): string {
-  const [major, minor, patch] = playbook.evolution.version.split('.').map(Number);
-  switch (type) {
-    case 'major':
-      return `${major + 1}.0.0`;
-    case 'minor':
-      return `${major}.${minor + 1}.0`;
-    case 'patch':
-    default:
-      return `${major}.${minor}.${patch + 1}`;
-  }
-}
-
-/**
- * Calculate playbook success rate
- */
-export function getPlaybookSuccessRate(playbook: Playbook): number {
-  const total = playbook.evolution.successCount + playbook.evolution.failureCount;
-  if (total === 0) return 0;
-  return playbook.evolution.successCount / total;
-}
-
-/**
- * Check if playbook has been used enough for reliable statistics
- */
-export function hasReliableStats(playbook: Playbook, minUses: number = 3): boolean {
-  return playbook.evolution.successCount + playbook.evolution.failureCount >= minUses;
-}

package/src/types/step.ts

@@ -1,40 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Step - A single action in a trajectory
- * Follows ReAct-style (Reasoning + Acting) pattern
- */
-export const StepSchema = z.object({
-  /** Optional reasoning/thought before action */
-  thought: z.string().optional(),
-  /** The action taken */
-  action: z.string(),
-  /** Result/observation from the action */
-  observation: z.string(),
-  /** Timestamp when step was executed */
-  timestamp: z.date().default(() => new Date()),
-  /** Additional metadata */
-  metadata: z.record(z.unknown()).default({}),
-  /** Credit attribution score (0-1), assigned during analysis */
-  attributionScore: z.number().min(0).max(1).optional(),
-});
-
-export type Step = z.infer<typeof StepSchema>;
-
-/**
- * Create a new step
- */
-export function createStep(params: {
-  thought?: string;
-  action: string;
-  observation: string;
-  metadata?: Record<string, unknown>;
-}): Step {
-  return StepSchema.parse({
-    thought: params.thought,
-    action: params.action,
-    observation: params.observation,
-    timestamp: new Date(),
-    metadata: params.metadata ?? {},
-  });
-}

package/src/types/task.ts

@@ -1,52 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Verification specification for validating task outcomes
- */
-export const VerificationSpecSchema = z.object({
-  type: z.enum(['exact_match', 'fuzzy_match', 'function', 'llm']),
-  expected: z.unknown().optional(),
-  tolerance: z.number().optional(),
-  verifier_id: z.string().optional(),
-});
-
-export type VerificationSpec = z.infer<typeof VerificationSpecSchema>;
-
-/**
- * Task - The fundamental unit of work
- * Represents what an agent needs to accomplish
- */
-export const TaskSchema = z.object({
-  id: z.string(),
-  domain: z.string(), // e.g., 'arc', 'swe', 'code', 'reasoning'
-  description: z.string(),
-  context: z.record(z.unknown()).default({}),
-  verification: VerificationSpecSchema.optional(),
-  embedding: z.array(z.number()).optional(),
-  metadata: z.record(z.unknown()).default({}),
-  createdAt: z.date().default(() => new Date()),
-});
-
-export type Task = z.infer<typeof TaskSchema>;
-
-/**
- * Create a new task with defaults
- */
-export function createTask(params: {
-  id?: string;
-  domain: string;
-  description: string;
-  context?: Record<string, unknown>;
-  verification?: VerificationSpec;
-  metadata?: Record<string, unknown>;
-}): Task {
-  return TaskSchema.parse({
-    id: params.id ?? crypto.randomUUID(),
-    domain: params.domain,
-    description: params.description,
-    context: params.context ?? {},
-    verification: params.verification,
-    metadata: params.metadata ?? {},
-    createdAt: new Date(),
-  });
-}