cognitive-core 0.1.0 → 0.2.0

package/src/search/team-router.ts

@@ -0,0 +1,459 @@
+/**
+ * Team Router
+ *
+ * Recommends team composition for a given task description.
+ * Queries team playbooks and experiences from memory, scores matches,
+ * and applies team meta-strategies to adjust recommendations.
+ *
+ * The team-level analog of TaskRouter.
+ */
+
+import type {
+  TeamPlaybook,
+  RolePlaybook,
+  TeamCompositionGuidance,
+  TeamCoordinationGuidance,
+  TeamRoleSpec,
+} from '../types/index.js';
+import type { TeamExperienceMemory } from '../memory/team-experience.js';
+import type { TeamMetaLearner } from '../learning/team-meta-learner.js';
+
+// ============================================================
+// Configuration
+// ============================================================
+
+export interface TeamRouterConfig {
+  /** Minimum playbook confidence to use directly */
+  minPlaybookConfidence: number;
+  /** How many playbook candidates to retrieve */
+  maxCandidates: number;
+  /** How many role playbooks to include per role */
+  maxRolePlaybooksPerRole: number;
+  /** Whether to include similar experiences in reasoning */
+  includeSimilarExperiences: boolean;
+}
+
+const DEFAULT_CONFIG: TeamRouterConfig = {
+  minPlaybookConfidence: 0.4,
+  maxCandidates: 5,
+  maxRolePlaybooksPerRole: 2,
+  includeSimilarExperiences: true,
+};
+
+// ============================================================
+// Output Types
+// ============================================================
+
+/**
+ * Result from team recommendation.
+ */
+export interface TeamRecommendation {
+  /** Matched team playbook (if any) */
+  playbook?: TeamPlaybook;
+  /** Recommended composition */
+  composition: TeamCompositionGuidance;
+  /** Recommended coordination */
+  coordination: TeamCoordinationGuidance;
+  /** Role playbooks for each recommended role */
+  rolePlaybooks: RolePlaybook[];
+  /** Confidence in this recommendation (0-1) */
+  confidence: number;
+  /** Reasoning for this recommendation */
+  reasoning: string;
+  /** Meta-strategies that were applied */
+  appliedMetaStrategies: string[];
+  /** Export as OpenTeams team.yaml format */
+  asTeamYaml(): string;
+}
+
+/**
+ * Task input for team recommendation.
+ */
+export interface TeamRecommendationInput {
+  description: string;
+  domain: string;
+  complexity: 'simple' | 'moderate' | 'complex' | 'epic';
+  constraints?: {
+    maxAgents?: number;
+    maxTokenBudget?: number;
+    preferredTopology?: string;
+  };
+}
+
+// ============================================================
+// Default fallback composition
+// ============================================================
+
+function defaultComposition(
+  input: TeamRecommendationInput
+): TeamCompositionGuidance {
+  // Simple tasks → flat 2-agent team, complex → wave with planner
+  if (input.complexity === 'simple') {
+    return {
+      topology: 'flat',
+      roles: [
+        {
+          role: 'executor',
+          rationale: 'Execute the task directly',
+          capabilities: ['task execution'],
+          optional: false,
+          modelTier: 'balanced',
+          spawnAs: 'root',
+        },
+      ],
+      spawnRules: {},
+      enforcement: 'permissive',
+    };
+  }
+
+  const roles: TeamRoleSpec[] = [
+    {
+      role: 'planner',
+      rationale: 'Decompose and plan the work',
+      capabilities: ['planning', 'decomposition'],
+      optional: false,
+      modelTier: 'capable',
+      spawnAs: 'root',
+    },
+    {
+      role: 'executor',
+      rationale: 'Execute planned tasks',
+      capabilities: ['task execution'],
+      optional: false,
+      modelTier: 'balanced',
+      spawnAs: 'companion',
+    },
+  ];
+
+  if (input.complexity === 'complex' || input.complexity === 'epic') {
+    roles.push({
+      role: 'reviewer',
+      rationale: 'Verify completed work',
+      capabilities: ['review', 'verification'],
+      optional: true,
+      modelTier: 'capable',
+      spawnAs: 'on-demand',
+    });
+  }
+
+  return {
+    topology: input.complexity === 'epic' ? 'hierarchical' : 'wave',
+    roles,
+    spawnRules: { planner: ['executor', 'reviewer'] },
+    enforcement: 'permissive',
+  };
+}
+
+function defaultCoordination(
+  input: TeamRecommendationInput
+): TeamCoordinationGuidance {
+  return {
+    executionModel:
+      input.complexity === 'simple'
+        ? 'sequential'
+        : 'wave-parallel',
+    channels: [],
+    interactionPatterns: [],
+    delegationStrategy: 'auto',
+  };
+}
+
+// ============================================================
+// YAML export
+// ============================================================
+
+function compositionToYaml(
+  rec: Omit<TeamRecommendation, 'asTeamYaml'>
+): string {
+  const lines: string[] = [
+    '# Team configuration generated by cognitive-core',
+    `# Confidence: ${rec.confidence.toFixed(2)}`,
+    '',
+    'team:',
+    `  topology: ${rec.composition.topology}`,
+    `  enforcement: ${rec.composition.enforcement}`,
+    '',
+    '  roles:',
+  ];
+
+  for (const role of rec.composition.roles) {
+    lines.push(`    - name: ${role.role}`);
+    lines.push(`      rationale: "${role.rationale}"`);
+    lines.push(`      optional: ${role.optional}`);
+    if (role.modelTier) {
+      lines.push(`      model_tier: ${role.modelTier}`);
+    }
+    lines.push(`      spawn_as: ${role.spawnAs}`);
+    if (role.capabilities.length > 0) {
+      lines.push(`      capabilities:`);
+      for (const cap of role.capabilities) {
+        lines.push(`        - ${cap}`);
+      }
+    }
+  }
+
+  if (Object.keys(rec.composition.spawnRules).length > 0) {
+    lines.push('');
+    lines.push('  spawn_rules:');
+    for (const [parent, children] of Object.entries(rec.composition.spawnRules)) {
+      lines.push(`    ${parent}: [${children.join(', ')}]`);
+    }
+  }
+
+  lines.push('');
+  lines.push('  coordination:');
+  lines.push(`    execution_model: ${rec.coordination.executionModel}`);
+  lines.push(`    delegation_strategy: ${rec.coordination.delegationStrategy}`);
+
+  if (rec.coordination.channels.length > 0) {
+    lines.push('    channels:');
+    for (const ch of rec.coordination.channels) {
+      lines.push(`      - name: ${ch.name}`);
+      lines.push(`        signals: [${ch.signals.join(', ')}]`);
+      lines.push(`        subscribers: [${ch.subscribers.join(', ')}]`);
+      lines.push(`        emitters: [${ch.emitters.join(', ')}]`);
+    }
+  }
+
+  if (rec.coordination.interactionPatterns.length > 0) {
+    lines.push('    interaction_patterns:');
+    for (const pat of rec.coordination.interactionPatterns) {
+      lines.push(`      - name: ${pat.name}`);
+      lines.push(`        roles: [${pat.roles.join(', ')}]`);
+      lines.push(`        frequency: ${pat.frequency}`);
+    }
+  }
+
+  if (rec.coordination.checkpoints && rec.coordination.checkpoints.length > 0) {
+    lines.push('    checkpoints:');
+    for (const cp of rec.coordination.checkpoints) {
+      lines.push(`      - ${cp}`);
+    }
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ============================================================
+// Team Router
+// ============================================================
+
+export class TeamRouter {
+  private memory: TeamExperienceMemory;
+  private config: TeamRouterConfig;
+  private metaLearner?: TeamMetaLearner;
+
+  constructor(
+    memory: TeamExperienceMemory,
+    config?: Partial<TeamRouterConfig>,
+    metaLearner?: TeamMetaLearner
+  ) {
+    this.memory = memory;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.metaLearner = metaLearner;
+  }
+
+  /**
+   * Set the team meta learner (can be set after construction).
+   */
+  setMetaLearner(metaLearner: TeamMetaLearner): void {
+    this.metaLearner = metaLearner;
+  }
+
+  /**
+   * Recommend a team composition for a given task.
+   */
+  async recommend(input: TeamRecommendationInput): Promise<TeamRecommendation> {
+    // 1. Find matching team playbooks
+    const playbookMatches = await this.memory.findMatchingTeamPlaybooks({
+      taskType: input.description,
+      domain: input.domain,
+      complexity: input.complexity,
+      topology: input.constraints?.preferredTopology,
+      k: this.config.maxCandidates,
+    });
+
+    // 2. Compute base recommendation
+    let recommendation = this.computeBaseRecommendation(input, playbookMatches);
+
+    // 3. Apply constraints
+    recommendation = this.applyConstraints(recommendation, input);
+
+    // 4. Attach role playbooks for each recommended role
+    const rolePlaybooks = await this.findRolePlaybooks(recommendation, input);
+    recommendation.rolePlaybooks = rolePlaybooks;
+
+    // 5. Apply meta-learning adjustments
+    if (this.metaLearner) {
+      try {
+        recommendation = await this.metaLearner.adjustRecommendation(
+          recommendation,
+          input
+        );
+      } catch (error) {
+        console.error(
+          '[TeamRouter] Meta-learning adjustment failed, using base recommendation:',
+          error instanceof Error ? error.message : String(error)
+        );
+      }
+    }
+
+    return recommendation;
+  }
+
+  /**
+   * Compute base recommendation from playbook matches.
+   */
+  private computeBaseRecommendation(
+    input: TeamRecommendationInput,
+    playbookMatches: Array<{ playbook: TeamPlaybook; score: number }>
+  ): TeamRecommendation {
+    // Filter to playbooks above minimum confidence
+    const viable = playbookMatches.filter(
+      (m) => m.playbook.confidence >= this.config.minPlaybookConfidence
+    );
+
+    if (viable.length > 0) {
+      // Use the best matching playbook
+      const best = viable[0];
+      const rec: Omit<TeamRecommendation, 'asTeamYaml'> = {
+        playbook: best.playbook,
+        composition: best.playbook.composition,
+        coordination: best.playbook.coordination,
+        rolePlaybooks: [],
+        confidence: Math.min(best.score * best.playbook.confidence, 0.95),
+        reasoning: `Matched team playbook "${best.playbook.name}" (score: ${best.score.toFixed(2)}, confidence: ${best.playbook.confidence.toFixed(2)})`,
+        appliedMetaStrategies: [],
+      };
+
+      return { ...rec, asTeamYaml: () => compositionToYaml(rec) };
+    }
+
+    // No viable playbook — build a default recommendation
+    const composition = defaultComposition(input);
+    const coordination = defaultCoordination(input);
+
+    const rec: Omit<TeamRecommendation, 'asTeamYaml'> = {
+      composition,
+      coordination,
+      rolePlaybooks: [],
+      confidence: 0.3,
+      reasoning: 'No matching team playbook found; using default composition based on complexity',
+      appliedMetaStrategies: [],
+    };
+
+    return { ...rec, asTeamYaml: () => compositionToYaml(rec) };
+  }
+
+  /**
+   * Apply user constraints to the recommendation.
+   */
+  private applyConstraints(
+    recommendation: TeamRecommendation,
+    input: TeamRecommendationInput
+  ): TeamRecommendation {
+    const constraints = input.constraints;
+    if (!constraints) return recommendation;
+
+    let modified = false;
+    const reasons: string[] = [];
+
+    // Apply max agents constraint
+    if (
+      constraints.maxAgents &&
+      recommendation.composition.roles.length > constraints.maxAgents
+    ) {
+      // Keep only essential (non-optional) roles, then trim to fit
+      const essential = recommendation.composition.roles.filter((r) => !r.optional);
+      const optional = recommendation.composition.roles.filter((r) => r.optional);
+
+      let roles: TeamRoleSpec[];
+      if (essential.length >= constraints.maxAgents) {
+        roles = essential.slice(0, constraints.maxAgents);
+      } else {
+        const remaining = constraints.maxAgents - essential.length;
+        roles = [...essential, ...optional.slice(0, remaining)];
+      }
+
+      recommendation = {
+        ...recommendation,
+        composition: { ...recommendation.composition, roles },
+      };
+      reasons.push(`Trimmed to ${constraints.maxAgents} agents`);
+      modified = true;
+    }
+
+    // Apply preferred topology
+    if (
+      constraints.preferredTopology &&
+      recommendation.composition.topology !== constraints.preferredTopology
+    ) {
+      recommendation = {
+        ...recommendation,
+        composition: {
+          ...recommendation.composition,
+          topology: constraints.preferredTopology as TeamCompositionGuidance['topology'],
+        },
+      };
+      reasons.push(`Topology set to ${constraints.preferredTopology}`);
+      modified = true;
+    }
+
+    if (modified) {
+      recommendation.reasoning += `. Constraints applied: ${reasons.join('; ')}`;
+      // Slightly lower confidence when constraints override
+      recommendation.confidence = Math.max(0.15, recommendation.confidence * 0.9);
+
+      // Rebuild asTeamYaml with updated data
+      const rec = recommendation;
+      recommendation.asTeamYaml = () => compositionToYaml(rec);
+    }
+
+    return recommendation;
+  }
+
+  /**
+   * Find role playbooks for each role in the recommendation.
+   */
+  private async findRolePlaybooks(
+    recommendation: TeamRecommendation,
+    input: TeamRecommendationInput
+  ): Promise<RolePlaybook[]> {
+    const rolePlaybooks: RolePlaybook[] = [];
+
+    for (const roleSpec of recommendation.composition.roles) {
+      const matches = await this.memory.findMatchingRolePlaybooks({
+        role: roleSpec.role,
+        topology: recommendation.composition.topology,
+        domain: input.domain,
+        taskType: input.description,
+        k: this.config.maxRolePlaybooksPerRole,
+      });
+
+      for (const match of matches) {
+        rolePlaybooks.push(match.playbook);
+      }
+    }
+
+    return rolePlaybooks;
+  }
+
+  /**
+   * Update configuration.
+   */
+  updateConfig(config: Partial<TeamRouterConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+}
+
+/**
+ * Create a TeamRouter instance.
+ */
+export function createTeamRouter(
+  memory: TeamExperienceMemory,
+  config?: Partial<TeamRouterConfig>,
+  metaLearner?: TeamMetaLearner
+): TeamRouter {
+  return new TeamRouter(memory, config, metaLearner);
+}

package/src/session-bank/git-reader.ts

@@ -0,0 +1,200 @@
+import { execFile } from 'node:child_process';
+
+// ─── CheckpointGitReader ────────────────────────────────────────────
+// Low-level git plumbing for reading from SessionLog checkpoint orphan
+// branches without checking them out.
+// Uses only git commands, no fs access.
+// ─────────────────────────────────────────────────────────────────────
+
+export interface GitReaderOptions {
+  repoPath: string;
+  branch?: string;
+  /** Trailer keys to search for checkpoint IDs in commit messages.
+   *  Defaults to ['Sessionlog-Checkpoint']. */
+  trailerKeys?: string[];
+}
+
+export class CheckpointGitReader {
+  readonly repoPath: string;
+  readonly branch: string;
+  private trailerKeys: string[];
+
+  constructor(options: GitReaderOptions) {
+    this.repoPath = options.repoPath;
+    this.branch = options.branch ?? 'sessionlog/checkpoints/v1';
+    this.trailerKeys = options.trailerKeys ?? ['Sessionlog-Checkpoint'];
+  }
+
+  /** Check if the orphan branch exists in this repo */
+  async branchExists(): Promise<boolean> {
+    try {
+      await this.git(['rev-parse', '--verify', this.branch]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * List all checkpoint directories.
+   * Returns paths like ["a3/b2c4d5e6f7", "f1/0a9b8c7d6e5f", ...]
+   */
+  async listCheckpoints(): Promise<string[]> {
+    // First list shard directories (2-char hex prefixes)
+    let shardOutput: string;
+    try {
+      shardOutput = await this.git([
+        'ls-tree',
+        '--name-only',
+        this.branch,
+      ]);
+    } catch {
+      return [];
+    }
+
+    const shards = shardOutput
+      .split('\n')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+
+    // For each shard, list checkpoint subdirectories
+    const checkpoints: string[] = [];
+    for (const shard of shards) {
+      try {
+        const innerOutput = await this.git([
+          'ls-tree',
+          '--name-only',
+          this.branch,
+          shard + '/',
+        ]);
+        const entries = innerOutput
+          .split('\n')
+          .map((e) => e.trim())
+          .filter((e) => e.length > 0);
+        checkpoints.push(...entries);
+      } catch {
+        // Skip shards that fail to list
+      }
+    }
+
+    return checkpoints;
+  }
+
+  /**
+   * List session subdirectories within a checkpoint.
+   * Returns numeric session indices like ["0", "1"].
+   */
+  async listSessions(checkpointPath: string): Promise<string[]> {
+    try {
+      const output = await this.git([
+        'ls-tree',
+        '--name-only',
+        this.branch,
+        checkpointPath + '/',
+      ]);
+      return output
+        .split('\n')
+        .map((e) => e.trim())
+        .filter((e) => e.length > 0)
+        // Extract just the directory name from the full path
+        .map((e) => {
+          const parts = e.split('/');
+          return parts[parts.length - 1];
+        })
+        // Keep only numeric directories (sessions), skip "tasks", "metadata.json" etc.
+        .filter((e) => /^\d+$/.test(e));
+    } catch {
+      return [];
+    }
+  }
+
+  /** Read a single file from the orphan branch */
+  async readFile(path: string): Promise<string> {
+    return this.git(['show', `${this.branch}:${path}`]);
+  }
+
+  /**
+   * Read multiple files in batch.
+   * Returns Map<path, content>. Missing files are omitted.
+   */
+  async readFiles(paths: string[]): Promise<Map<string, string>> {
+    const result = new Map<string, string>();
+
+    // Use parallel readFile calls (git show is fast for individual files)
+    const settled = await Promise.allSettled(
+      paths.map(async (path) => {
+        const content = await this.readFileOrNull(path);
+        return { path, content };
+      }),
+    );
+
+    for (const entry of settled) {
+      if (entry.status === 'fulfilled' && entry.value.content !== null) {
+        result.set(entry.value.path, entry.value.content);
+      }
+    }
+
+    return result;
+  }
+
+  /** Read a file, returning null if it doesn't exist */
+  async readFileOrNull(path: string): Promise<string | null> {
+    try {
+      return await this.readFile(path);
+    } catch {
+      return null;
+    }
+  }
+
+  /** Get the HEAD commit SHA of the orphan branch */
+  async getBranchHead(): Promise<string | null> {
+    try {
+      const sha = await this.git(['rev-parse', this.branch]);
+      return sha.trim();
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Find a checkpoint trailer value for a given commit.
+   * Tries each configured trailer key in order.
+   * Returns the checkpoint ID or null.
+   */
+  async getCheckpointTrailer(commitSha: string): Promise<string | null> {
+    for (const key of this.trailerKeys) {
+      try {
+        const output = await this.git([
+          'log',
+          `--format=%(trailers:key=${key},valueonly)`,
+          commitSha,
+          '-1',
+        ]);
+        const value = output.trim();
+        if (value) return value;
+      } catch {
+        // Try next key
+      }
+    }
+    return null;
+  }
+
+  // ── Private ──────────────────────────────────────────────────
+
+  private git(args: string[]): Promise<string> {
+    return new Promise((resolve, reject) => {
+      execFile(
+        'git',
+        ['-C', this.repoPath, ...args],
+        { maxBuffer: 100 * 1024 * 1024 }, // 100MB for large transcripts
+        (error, stdout, stderr) => {
+          if (error) {
+            reject(new Error(`git ${args[0]} failed: ${stderr || error.message}`));
+          } else {
+            resolve(stdout);
+          }
+        },
+      );
+    });
+  }
+}

package/src/session-bank/index.ts

@@ -0,0 +1,26 @@
+export { SessionBank } from './session-bank.js';
+export { CheckpointGitReader, type GitReaderOptions } from './git-reader.js';
+export {
+  CheckpointParser,
+  detectFormat,
+  type CheckpointFormat,
+  type ParsedMetadata,
+} from './parser.js';
+export type {
+  SessionRecord,
+  SessionMetadata,
+  TranscriptMessage,
+  ContentBlock,
+  TextBlock,
+  ToolUseBlock,
+  ToolResultBlock,
+  SessionSummary,
+  TokenUsage,
+  Attribution,
+  SessionSource,
+  CheckpointRef,
+  SessionQuery,
+  SessionQueryResult,
+  ProcessingLogEntry,
+  SessionBankOptions,
+} from './types.js';