cognitive-core 0.2.1 → 0.2.3

package/src/memory/source-resolver.ts

@@ -0,0 +1,422 @@
+/**
+ * Source Resolver — Normalizes playbook sources (local paths, git URLs, shorthands)
+ * into local directory paths for the curated loader.
+ *
+ * Supports:
+ * - Local filesystem paths (pass-through)
+ * - Git URLs: "git:https://github.com/org/repo" or "git:https://github.com/org/repo#ref"
+ * - GitHub shorthand: "github:org/repo" or "github:org/repo#ref"
+ *
+ * Cloned repos are cached in a configurable directory (default: .atlas/curated-cache/).
+ * Cache freshness is controlled by maxAgeMs. Stale caches are refreshed on next resolve.
+ */
+
+import { execFile as execFileCb } from 'node:child_process';
+import { existsSync, statSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { mkdir, readFile, readdir } from 'node:fs/promises';
+import { promisify } from 'node:util';
+
+const execFile = promisify(execFileCb);
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Parsed git source components
+ */
+export interface ParsedGitSource {
+  url: string;
+  ref?: string;
+  cacheKey: string;
+}
+
+/**
+ * Manifest file (cognitive-core.json) at repo root
+ */
+export interface PlaybookManifest {
+  /** Relative path to playbook directory within the repo */
+  playbooks: string;
+  /** Optional version label */
+  version?: string;
+  /** Optional display name */
+  name?: string;
+  /** Optional description */
+  description?: string;
+}
+
+/**
+ * State persisted per resolved source (stored in system_state)
+ */
+export interface SourceState {
+  /** Original config source string */
+  source: string;
+  /** Resolved git URL (empty for local paths) */
+  url: string;
+  /** Requested ref (branch/tag/commit) */
+  ref: string;
+  /** Actual commit SHA loaded */
+  commitSha: string;
+  /** Local cache path */
+  cachePath: string;
+  /** Discovered playbook directory within cache */
+  playbookDir: string;
+  /** ISO timestamp of last successful load */
+  loadedAt: string;
+  /** Number of playbooks loaded from this source */
+  playbookCount: number;
+}
+
+/**
+ * Result of resolving a source
+ */
+export interface ResolveResult {
+  /** Local directory path containing playbook JSON files */
+  playbookDir: string;
+  /** Whether this is a git source */
+  isGit: boolean;
+  /** Commit SHA (only for git sources) */
+  commitSha?: string;
+  /** Whether the source was freshly cloned/updated */
+  updated: boolean;
+  /** Source identifier for provenance tracking */
+  sourceId: string;
+}
+
+/**
+ * Options for source resolution
+ */
+export interface ResolveOptions {
+  /** Cache directory (default: .atlas/curated-cache) */
+  cacheDir: string;
+  /** Maximum cache age in milliseconds before refreshing (default: 24h) */
+  maxAgeMs: number;
+  /** Force update regardless of cache age */
+  forceUpdate?: boolean;
+  /** Callback for loading/saving source state */
+  getSourceState?: (source: string) => SourceState | undefined;
+  setSourceState?: (source: string, state: SourceState) => void;
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Check if a source string is a git source (not a local path).
+ */
+export function isGitSource(source: string): boolean {
+  return (
+    source.startsWith('git:') ||
+    source.startsWith('github:') ||
+    source.startsWith('git@') ||
+    source.startsWith('git+')
+  );
+}
+
+/**
+ * Parse a git source string into URL and optional ref components.
+ *
+ * Supported formats:
+ * - "git:https://github.com/org/repo"
+ * - "git:https://github.com/org/repo#v1.0.0"
+ * - "github:org/repo"
+ * - "github:org/repo#branch"
+ */
+export function parseGitSource(source: string): ParsedGitSource {
+  let raw = source;
+
+  // Strip prefix
+  if (raw.startsWith('git:')) {
+    raw = raw.slice(4);
+  } else if (raw.startsWith('git+')) {
+    raw = raw.slice(4);
+  } else if (raw.startsWith('github:')) {
+    const rest = raw.slice(7); // "org/repo" or "org/repo#ref"
+    const [path, ref] = rest.split('#', 2);
+    const url = `https://github.com/${path}.git`;
+    const cacheKey = `github.com/${path}`;
+    return { url, ref, cacheKey };
+  }
+
+  // Parse ref from fragment
+  const hashIdx = raw.indexOf('#');
+  let url: string;
+  let ref: string | undefined;
+
+  if (hashIdx !== -1) {
+    url = raw.slice(0, hashIdx);
+    ref = raw.slice(hashIdx + 1);
+  } else {
+    url = raw;
+  }
+
+  // Ensure .git suffix for HTTPS URLs
+  if (url.startsWith('https://') && !url.endsWith('.git')) {
+    url += '.git';
+  }
+
+  // Build cache key from URL (strip protocol + .git suffix)
+  const cacheKey = url
+    .replace(/^https?:\/\//, '')
+    .replace(/\.git$/, '');
+
+  return { url, ref, cacheKey };
+}
+
+/**
+ * Resolve a playbook source to a local directory path.
+ *
+ * For local paths, returns the path as-is (after verifying it exists).
+ * For git sources, clones/updates to a cache directory and discovers
+ * the playbook directory within the repo.
+ */
+export async function resolvePlaybookSource(
+  source: string,
+  options: ResolveOptions,
+): Promise<ResolveResult | null> {
+  // Local path — pass through
+  if (!isGitSource(source)) {
+    if (!existsSync(source)) {
+      console.warn(`[source-resolver] Local path does not exist: ${source}`);
+      return null;
+    }
+    return {
+      playbookDir: source,
+      isGit: false,
+      updated: false,
+      sourceId: source,
+    };
+  }
+
+  // Git source — parse, clone/update, discover
+  const parsed = parseGitSource(source);
+  const cachePath = join(options.cacheDir, parsed.cacheKey);
+
+  try {
+    // Ensure cache parent dir exists
+    await mkdir(cachePath, { recursive: true });
+
+    const isCloned = existsSync(join(cachePath, '.git'));
+
+    if (!isCloned) {
+      // First-time clone
+      await gitClone(parsed.url, parsed.ref, cachePath);
+    } else if (shouldUpdate(source, options)) {
+      // Update existing cache
+      await gitUpdate(parsed.ref, cachePath);
+    }
+
+    // Get current commit SHA
+    const commitSha = await gitRevParse(cachePath);
+
+    // Check if we already loaded this exact SHA
+    const prevState = options.getSourceState?.(source);
+    if (prevState && prevState.commitSha === commitSha && !options.forceUpdate) {
+      return {
+        playbookDir: prevState.playbookDir,
+        isGit: true,
+        commitSha,
+        updated: false,
+        sourceId: source,
+      };
+    }
+
+    // Discover playbook directory
+    const playbookDir = await discoverPlaybookDir(cachePath);
+    if (!playbookDir) {
+      console.warn(`[source-resolver] No playbook directory found in ${source}`);
+      return null;
+    }
+
+    // Persist source state
+    const state: SourceState = {
+      source,
+      url: parsed.url,
+      ref: parsed.ref ?? '',
+      commitSha,
+      cachePath,
+      playbookDir,
+      loadedAt: new Date().toISOString(),
+      playbookCount: 0, // Updated by caller after loading
+    };
+    options.setSourceState?.(source, state);
+
+    return {
+      playbookDir,
+      isGit: true,
+      commitSha,
+      updated: true,
+      sourceId: source,
+    };
+  } catch (error) {
+    // If we have a cached version, use it despite the error
+    if (existsSync(join(cachePath, '.git'))) {
+      console.warn(
+        `[source-resolver] Failed to update ${source}, using cached version:`,
+        error instanceof Error ? error.message : String(error),
+      );
+      const prevState = options.getSourceState?.(source);
+      if (prevState) {
+        return {
+          playbookDir: prevState.playbookDir,
+          isGit: true,
+          commitSha: prevState.commitSha,
+          updated: false,
+          sourceId: source,
+        };
+      }
+      // Try to discover even without state
+      const playbookDir = await discoverPlaybookDir(cachePath);
+      if (playbookDir) {
+        return {
+          playbookDir,
+          isGit: true,
+          updated: false,
+          sourceId: source,
+        };
+      }
+    }
+
+    console.warn(
+      `[source-resolver] Failed to resolve ${source}, skipping:`,
+      error instanceof Error ? error.message : String(error),
+    );
+    return null;
+  }
+}
+
+// ============================================================================
+// Git operations
+// ============================================================================
+
+async function gitClone(url: string, ref: string | undefined, dest: string): Promise<void> {
+  // Remove the directory first since mkdir already created it
+  rmSync(dest, { recursive: true, force: true });
+
+  const args = ['clone', '--depth', '1', '--single-branch'];
+  if (ref) {
+    args.push('--branch', ref);
+  }
+  args.push(url, dest);
+
+  await execFile('git', args, { timeout: 60_000 });
+}
+
+async function gitUpdate(ref: string | undefined, cachePath: string): Promise<void> {
+  const fetchArgs = ['fetch', 'origin'];
+  if (ref) {
+    fetchArgs.push(ref);
+  }
+  await execFile('git', fetchArgs, { cwd: cachePath, timeout: 30_000 });
+
+  // Always use FETCH_HEAD — works for branches, tags, and commits.
+  // Using origin/${ref} would break for tags (refs/tags/*, not refs/remotes/origin/*).
+  await execFile('git', ['reset', '--hard', 'FETCH_HEAD'], {
+    cwd: cachePath,
+    timeout: 10_000,
+  });
+}
+
+async function gitRevParse(cachePath: string): Promise<string> {
+  const { stdout } = await execFile('git', ['rev-parse', 'HEAD'], {
+    cwd: cachePath,
+    timeout: 5_000,
+  });
+  return stdout.trim();
+}
+
+// ============================================================================
+// Playbook directory discovery
+// ============================================================================
+
+/**
+ * Discover the playbook directory within a cloned repo.
+ *
+ * Search order:
+ * 1. Manifest file (cognitive-core.json) at repo root
+ * 2. Convention: playbooks/ directory
+ * 3. Convention: curated-playbooks/ directory
+ * 4. Root directory if it contains .json files matching schema
+ */
+export async function discoverPlaybookDir(repoRoot: string): Promise<string | null> {
+  // 1. Check for manifest
+  const manifestPath = join(repoRoot, 'cognitive-core.json');
+  if (existsSync(manifestPath)) {
+    try {
+      const content = await readFile(manifestPath, 'utf-8');
+      const manifest = JSON.parse(content) as PlaybookManifest;
+      if (manifest.playbooks) {
+        const dir = join(repoRoot, manifest.playbooks);
+        if (existsSync(dir)) {
+          return dir;
+        }
+      }
+    } catch {
+      // Invalid manifest, fall through to convention
+    }
+  }
+
+  // 2. Convention: playbooks/
+  const playbooksDir = join(repoRoot, 'playbooks');
+  if (existsSync(playbooksDir) && statSync(playbooksDir).isDirectory()) {
+    return playbooksDir;
+  }
+
+  // 3. Convention: curated-playbooks/
+  const curatedDir = join(repoRoot, 'curated-playbooks');
+  if (existsSync(curatedDir) && statSync(curatedDir).isDirectory()) {
+    return curatedDir;
+  }
+
+  // 4. Check if root has JSON files that look like playbooks
+  if (await hasPlaybookJsonFiles(repoRoot)) {
+    return repoRoot;
+  }
+
+  return null;
+}
+
+/**
+ * Check if a directory contains at least one JSON file that looks like a playbook.
+ */
+async function hasPlaybookJsonFiles(dir: string): Promise<boolean> {
+  try {
+    const files = await readdir(dir);
+    const jsonFiles = files.filter(f => f.endsWith('.json'));
+    if (jsonFiles.length === 0) return false;
+
+    // Check first JSON file for required playbook fields
+    const content = await readFile(join(dir, jsonFiles[0]), 'utf-8');
+    const parsed = JSON.parse(content);
+    return !!(parsed.name && parsed.applicability && parsed.guidance);
+  } catch {
+    return false;
+  }
+}
+
+// ============================================================================
+// Cache management
+// ============================================================================
+
+/**
+ * Determine whether a cached source should be updated.
+ */
+function shouldUpdate(source: string, options: ResolveOptions): boolean {
+  if (options.forceUpdate) return true;
+
+  const state = options.getSourceState?.(source);
+  if (!state) return true; // No previous state, always update
+
+  const loadedAt = new Date(state.loadedAt).getTime();
+  const age = Date.now() - loadedAt;
+  return age > options.maxAgeMs;
+}
+
+/**
+ * Generate the system_state key for a source.
+ */
+export function sourceStateKey(source: string): string {
+  return `curated-source:${source}`;
+}

package/src/types/config.ts

@@ -513,6 +513,45 @@ export const SkillTreeConfigSchema = z.object({
   dbPath: z.string().default('skills.db'),
 });
 
+/**
+ * Curated playbook cache configuration (for git sources)
+ */
+export const CuratedCacheConfigSchema = z.object({
+  /** Cache directory for cloned repos (relative to storage.baseDir, default: curated-cache) */
+  dir: z.string().default('curated-cache'),
+  /** Maximum cache age in milliseconds before refreshing (default: 24h) */
+  maxAgeMs: z.number().default(24 * 60 * 60 * 1000),
+});
+
+export type CuratedCacheConfig = z.infer<typeof CuratedCacheConfigSchema>;
+
+/**
+ * Curated playbook configuration
+ */
+export const CuratedPlaybooksConfigSchema = z.object({
+  /** Load the bundled compound-engineering seed pack on init */
+  loadBundledSeedPack: z.boolean().default(false),
+  /** Additional directories to load curated playbooks from (backward compat) */
+  additionalDirs: z.array(z.string()).default([]),
+  /**
+   * Playbook sources — local paths or git URIs.
+   *
+   * Supported formats:
+   * - Local path: "/path/to/playbooks"
+   * - Git URL: "git:https://github.com/org/repo" or "git:https://github.com/org/repo#v1.0.0"
+   * - GitHub shorthand: "github:org/repo" or "github:org/repo#branch"
+   *
+   * Git sources are cloned to a local cache and refreshed based on cache.maxAgeMs.
+   */
+  sources: z.array(z.string()).default([]),
+  /** Cache configuration for git-based sources */
+  cache: CuratedCacheConfigSchema.default({}),
+  /** Re-create curated playbooks on each init (useful when updating seed files) */
+  recreateOnInit: z.boolean().default(false),
+});
+
+export type CuratedPlaybooksConfig = z.infer<typeof CuratedPlaybooksConfigSchema>;
+
 export type SkillTreeConfig = z.infer<typeof SkillTreeConfigSchema>;
 
 /**
@@ -570,6 +609,8 @@ export const AtlasConfigSchema = z.object({
   knowledgeBank: KnowledgeBankConfigSchema.default({}),
   /** Skill-tree storage configuration */
   skillTree: SkillTreeConfigSchema.default({}),
+  /** Curated playbook seeding configuration */
+  curatedPlaybooks: CuratedPlaybooksConfigSchema.default({}),
   /** Session bank configuration (Entire CLI integration) */
   sessionBank: SessionBankConfigSchema.default({}),
   /** Feature toggles for ruvector-inspired subsystems */
@@ -609,6 +650,11 @@ export function mergeConfig(
     teamLearning: { ...base.teamLearning, ...overrides.teamLearning },
     knowledgeBank: { ...base.knowledgeBank, ...overrides.knowledgeBank },
     skillTree: { ...base.skillTree, ...overrides.skillTree },
+    curatedPlaybooks: {
+      ...base.curatedPlaybooks,
+      ...overrides.curatedPlaybooks,
+      cache: { ...base.curatedPlaybooks.cache, ...overrides.curatedPlaybooks?.cache },
+    },
     sessionBank: { ...base.sessionBank, ...overrides.sessionBank },
     features: { ...base.features, ...overrides.features },
   });

package/src/types/index.ts

@@ -250,6 +250,8 @@ export {
   type GraphConfigType,
   type DefragConfig,
   type SkillTreeConfig,
+  type CuratedCacheConfig,
+  type CuratedPlaybooksConfig,
   type SessionBankConfig,
   type FeaturesConfig,
   type AtlasConfig,
@@ -282,6 +284,8 @@ export {
   TeamLearningConfigSchema,
   AgenticTaskRunnerConfigSchema,
   SkillTreeConfigSchema,
+  CuratedCacheConfigSchema,
+  CuratedPlaybooksConfigSchema,
   FeaturesConfigSchema,
   AtlasConfigSchema,
   createDefaultConfig,

package/src/workspace/types.ts

@@ -1,10 +1,16 @@
-import type { WorkspaceHandle, OutputSpec } from 'agent-workspace';
+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
@@ -12,13 +18,9 @@ export type { WorkspaceHandle, OutputSpec, OutputFileSpec, ValidationResult } fr
 
 /**
  * Skill to load into workspace skills/ directory.
- * Agent Skills open standard format (SKILL.md).
+ * Extends agent-workspace's SkillSpec with source tracking.
  */
-export interface AgentSkillSpec {
-  /** Skill directory name */
-  name: string;
-  /** SKILL.md content */
-  content: string;
+export interface AgentSkillSpec extends SkillSpec {
   /** Source of this skill */
   source: 'playbook-conversion' | 'curated' | 'extracted';
 }
@@ -29,14 +31,9 @@ export interface AgentSkillSpec {
 
 /**
  * Supplementary resource to load into workspace resources/ directory.
+ * Extends agent-workspace's ResourceSpec with description.
  */
-export interface ResourceSpec {
-  /** Path relative to resources/ directory */
-  path: string;
-  /** How to populate this resource */
-  type: 'directory' | 'file' | 'symlink';
-  /** Source path (for symlink/copy) or content (for file) */
-  source: string;
+export interface ResourceSpec extends BaseResourceSpec {
   /** Description for the agent */
   description?: string;
 }
@@ -46,13 +43,9 @@ export interface ResourceSpec {
 // ============================================================
 
 /**
- * Complexity level determines whether to use heuristic or agentic analysis.
+ * Backward-compatible alias for agent-workspace's TaskComplexity.
  */
-export type AnalysisComplexity =
-  | 'heuristic'    // Use heuristicFallback(), no agent needed
-  | 'lightweight'  // Agent with small budget, simple workspace
-  | 'standard'     // Agent with moderate budget, full workspace
-  | 'thorough';    // Agent with large budget, full workspace, more time
+export type AnalysisComplexity = TaskComplexity;
 
 // ============================================================
 // Processing Context
@@ -81,34 +74,14 @@ export interface ProcessingContext {
 /**
  * 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> {
-  /** Unique identifier for this task type */
-  taskType: string;
-
-  /** Domain for knowledge injection and meta-learning */
-  domain: string;
-
-  /** Human-readable description */
-  description: string;
-
-  // === WORKSPACE SETUP ===
-
-  /**
-   * Prepare the workspace filesystem from typed input.
-   * Uses the WorkspaceHandle to write input files via typed I/O methods.
-   */
-  prepareWorkspace(input: TInput, handle: WorkspaceHandle): Promise<void>;
-
-  /**
-   * Build the task description for the agent.
-   * Natural language prompt explaining what to do and what output to produce.
-   */
-  buildTaskPrompt(input: TInput): string;
-
-  // === SKILLS ===
+export interface AgenticTaskTemplate<TInput, TOutput> extends TaskTemplate<TInput, TOutput> {
+  // === SKILLS (override with source tracking) ===
 
   /**
    * Skills to load into the workspace skills/ directory.
@@ -116,14 +89,14 @@ export interface AgenticTaskTemplate<TInput, TOutput> {
    */
   getSkills(input: TInput): AgentSkillSpec[];
 
-  // === RESOURCES ===
+  // === RESOURCES (override with description) ===
 
   /**
    * Supplementary resources for the workspace resources/ directory.
    */
   getResources(input: TInput): ResourceSpec[];
 
-  // === KNOWLEDGE ===
+  // === KNOWLEDGE (cognitive-core extension) ===
 
   /**
    * Additional memory queries beyond the automatic domain-scoped query.
@@ -133,17 +106,7 @@ export interface AgenticTaskTemplate<TInput, TOutput> {
     memory: MemorySystem
   ): Promise<MemoryQueryResultV2>;
 
-  // === OUTPUT ===
-
-  /** Configuration defining the expected output shape */
-  outputConfig: OutputSpec;
-
-  /**
-   * Read and validate agent output from workspace.
-   * Uses the WorkspaceHandle to read output via typed I/O methods.
-   * Returns typed output or throws if validation fails.
-   */
-  collectOutput(handle: WorkspaceHandle): Promise<TOutput>;
+  // === OUTPUT PROCESSING (cognitive-core extension) ===
 
   /**
    * Process the validated output — store results, accumulate for batch learning, etc.
@@ -154,31 +117,12 @@ export interface AgenticTaskTemplate<TInput, TOutput> {
     context: ProcessingContext
   ): Promise<void>;
 
-  // === COMPLEXITY ASSESSMENT ===
-
-  /**
-   * Assess whether this input needs agentic analysis or heuristic fallback.
-   */
-  assessComplexity(input: TInput): AnalysisComplexity;
-
-  /**
-   * Heuristic fallback for simple cases.
-   * Called when assessComplexity returns 'heuristic'.
-   */
-  heuristicFallback?(input: TInput): Promise<TOutput>;
-
   // === CONFIGURATION ===
 
-  /** Agent type to spawn (default: 'claude-code') */
-  agentType?: string;
-
-  /** Timeout for the analysis agent (default: 120_000ms) */
-  timeout?: number;
-
   /** Whether to capture detailed tool calls (default: true) */
   captureToolCalls?: boolean;
 
-  // === COMPUTE ===
+  // === COMPUTE (cognitive-core extension) ===
 
   /**
    * Static compute requirements for this template.