cognitive-core 0.1.0 → 0.2.0

package/src/bin/commands/sessions.ts

@@ -0,0 +1,221 @@
+/**
+ * Session bank CLI commands.
+ *
+ * SessionBank is standalone — it reads SessionLog checkpoint data from
+ * orphan branches and does NOT depend on Atlas.
+ */
+
+import { join } from 'node:path';
+import { SessionBank } from '../../session-bank/session-bank.js';
+import type { SessionQuery, SessionRecord } from '../../session-bank/types.js';
+import type { CLIOptions } from '../cli-utils.js';
+import { outputJson, resolveStorageDir } from '../cli-utils.js';
+
+// ─── Local Lifecycle Wrapper ──────────────────────────────────────────
+
+async function withSessionBank<T>(
+  options: CLIOptions,
+  fn: (bank: SessionBank) => Promise<T>,
+): Promise<T> {
+  const stateDir = join(options.dir || resolveStorageDir(), 'session-bank');
+  const bank = new SessionBank({
+    repoPath: options.repo || process.cwd(),
+    stateDir,
+  });
+  try {
+    await bank.init();
+    if (!bank.isAvailable()) {
+      throw new Error(
+        'SessionLog not available. No checkpoint branch found in this repository.',
+      );
+    }
+    return await fn(bank);
+  } finally {
+    await bank.close();
+  }
+}
+
+// ─── Formatters ───────────────────────────────────────────────────────
+
+function formatSessionLine(s: SessionRecord): string {
+  const date = s.metadata.createdAt.toISOString().slice(0, 19).replace('T', ' ');
+  const files = s.metadata.filesTouched.length;
+  const agent = s.metadata.agent || 'unknown';
+  const branch = s.metadata.branch || '-';
+  return [
+    `  ${s.sessionId}`,
+    `    Checkpoint: ${s.checkpointId}`,
+    `    Date:       ${date}`,
+    `    Branch:     ${branch}`,
+    `    Agent:      ${agent}`,
+    `    Files:      ${files}`,
+  ].join('\n');
+}
+
+// ─── Subcommands ──────────────────────────────────────────────────────
+
+async function sessionsList(options: CLIOptions): Promise<void> {
+  await withSessionBank(options, async (bank) => {
+    let sessions = await bank.discover();
+
+    // Sort newest first
+    sessions.sort(
+      (a, b) => b.metadata.createdAt.getTime() - a.metadata.createdAt.getTime(),
+    );
+
+    // Apply limit
+    if (options.limit && options.limit > 0) {
+      sessions = sessions.slice(0, options.limit);
+    }
+
+    if (options.format === 'json') {
+      const summaries = sessions.map((s) => ({
+        sessionId: s.sessionId,
+        checkpointId: s.checkpointId,
+        createdAt: s.metadata.createdAt.toISOString(),
+        branch: s.metadata.branch,
+        agent: s.metadata.agent,
+        filesCount: s.metadata.filesTouched.length,
+        hasSummary: s.summary !== undefined,
+      }));
+      outputJson(summaries);
+      return;
+    }
+
+    if (sessions.length === 0) {
+      console.log('No sessions found.');
+      return;
+    }
+
+    console.log(`Found ${sessions.length} session(s):\n`);
+    for (const s of sessions) {
+      console.log(formatSessionLine(s));
+      console.log('');
+    }
+  });
+}
+
+async function sessionsGet(
+  sessionId: string,
+  options: CLIOptions,
+): Promise<void> {
+  await withSessionBank(options, async (bank) => {
+    const record = await bank.getBySessionId(sessionId);
+
+    if (!record) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    if (options.format === 'json') {
+      outputJson(record);
+      return;
+    }
+
+    const date = record.metadata.createdAt.toISOString().slice(0, 19).replace('T', ' ');
+    console.log(`Session: ${record.sessionId}`);
+    console.log(`Checkpoint: ${record.checkpointId}`);
+    console.log(`Date: ${date}`);
+    console.log(`Branch: ${record.metadata.branch}`);
+    console.log(`Agent: ${record.metadata.agent}`);
+    console.log(`Strategy: ${record.metadata.strategy}`);
+    console.log(`Files touched: ${record.metadata.filesTouched.length}`);
+    console.log(`Transcript messages: ${record.transcript.length}`);
+
+    if (record.summary) {
+      console.log('');
+      console.log('Summary:');
+      console.log(`  Intent: ${record.summary.intent}`);
+      console.log(`  Outcome: ${record.summary.outcome}`);
+    }
+
+    if (record.tokenUsage) {
+      console.log('');
+      console.log('Token usage:');
+      console.log(`  Input:  ${record.tokenUsage.inputTokens}`);
+      console.log(`  Output: ${record.tokenUsage.outputTokens}`);
+      console.log(`  Total:  ${record.tokenUsage.total}`);
+    }
+  });
+}
+
+async function sessionsQuery(options: CLIOptions): Promise<void> {
+  await withSessionBank(options, async (bank) => {
+    const query: SessionQuery = {};
+
+    if (options.agent) query.agent = options.agent;
+    if (options.since) query.since = new Date(options.since);
+    if (options.before) query.before = new Date(options.before);
+    if (options.limit) query.limit = options.limit;
+    if (options.branch) query.branch = options.branch;
+
+    const result = await bank.query(query);
+
+    if (options.format === 'json') {
+      const summaries = result.sessions.map((s) => ({
+        sessionId: s.sessionId,
+        checkpointId: s.checkpointId,
+        createdAt: s.metadata.createdAt.toISOString(),
+        branch: s.metadata.branch,
+        agent: s.metadata.agent,
+        filesCount: s.metadata.filesTouched.length,
+        hasSummary: s.summary !== undefined,
+      }));
+      outputJson({ sessions: summaries, total: result.total });
+      return;
+    }
+
+    if (result.sessions.length === 0) {
+      console.log('No sessions match the query.');
+      return;
+    }
+
+    console.log(`${result.sessions.length} of ${result.total} session(s):\n`);
+    for (const s of result.sessions) {
+      console.log(formatSessionLine(s));
+      console.log('');
+    }
+  });
+}
+
+// ─── Dispatcher ───────────────────────────────────────────────────────
+
+export async function sessionsCommand(
+  command: string,
+  positional: string[],
+  options: CLIOptions,
+): Promise<void> {
+  switch (command) {
+    case 'list':
+      await sessionsList(options);
+      break;
+
+    case 'get':
+      if (!positional[0]) {
+        console.error('Usage: cogcore sessions get <session-id>');
+        process.exit(1);
+      }
+      await sessionsGet(positional[0], options);
+      break;
+
+    case 'query':
+      await sessionsQuery(options);
+      break;
+
+    default:
+      console.log(`
+Sessions — interact with SessionLog checkpoint data
+
+Usage:
+  cogcore sessions list    [--limit <n>] [--json]
+  cogcore sessions get     <session-id> [--json]
+  cogcore sessions query   [--agent <name>] [--branch <branch>]
+                                  [--since <date>] [--before <date>]
+                                  [--limit <n>] [--json]
+`);
+      if (command) {
+        console.error(`Unknown sessions subcommand: ${command}`);
+        process.exit(1);
+      }
+      break;
+  }
+}

package/src/bin/commands/skills.ts

@@ -0,0 +1,146 @@
+/**
+ * Skills CLI commands — list, stats, refresh.
+ */
+
+import { getPlaybookSuccessRate } from '../../types/playbook.js';
+import {
+  type CLIOptions,
+  withAtlas,
+  requireSkillLibrary,
+} from '../cli-utils.js';
+
+export async function skillsCommand(
+  command: string,
+  _positional: string[],
+  options: CLIOptions,
+): Promise<void> {
+  switch (command) {
+    case 'list':
+      return skillsList(options);
+    case 'stats':
+      return skillsStats(options);
+    case 'refresh':
+      return skillsRefresh(options);
+    default:
+      if (command) {
+        console.error(`Unknown skills command: ${command}`);
+      }
+      console.log('Usage: cogcore skills <command>\n');
+      console.log('Commands:');
+      console.log('  list     List skills (--tier core|domain)');
+      console.log('  stats    Show skill library statistics');
+      console.log('  refresh  Refresh skill tiers');
+      process.exit(command ? 1 : 0);
+  }
+}
+
+async function skillsList(options: CLIOptions): Promise<void> {
+  await withAtlas(options, async (atlas) => {
+    const lib = requireSkillLibrary(atlas);
+
+    let playbooks;
+    if (options.tier === 'core') {
+      playbooks = lib.getCoreSkills();
+    } else if (options.tier === 'domain') {
+      playbooks = [];
+      for (const domain of lib.getDomains()) {
+        playbooks.push(...lib.getDomainSkills(domain));
+      }
+    } else {
+      playbooks = [...lib.getCoreSkills()];
+      for (const domain of lib.getDomains()) {
+        for (const pb of lib.getDomainSkills(domain)) {
+          if (!playbooks.some((p) => p.id === pb.id)) {
+            playbooks.push(pb);
+          }
+        }
+      }
+    }
+
+    const coreIds = new Set(lib.getCoreSkills().map((c) => c.id));
+
+    if (options.format === 'json') {
+      const results = playbooks.map((pb) => ({
+        id: pb.id,
+        name: pb.name,
+        confidence: pb.confidence,
+        domains: pb.applicability.domains,
+        tier: coreIds.has(pb.id) ? 'core' : 'domain',
+        successRate: getPlaybookSuccessRate(pb),
+      }));
+      console.log(JSON.stringify(results, null, 2));
+    } else {
+      if (playbooks.length === 0) {
+        console.log('No skills found.');
+        return;
+      }
+      console.log(`Found ${playbooks.length} skill(s):\n`);
+      for (const pb of playbooks) {
+        const tier = coreIds.has(pb.id) ? 'core' : 'domain';
+        const confidence = Math.round(pb.confidence * 100);
+        const successRate = Math.round(getPlaybookSuccessRate(pb) * 100);
+        const domains = pb.applicability.domains.join(', ');
+        console.log(`  ${pb.id}  ${pb.name}`);
+        console.log(`    Tier: ${tier}  Confidence: ${confidence}%  Success: ${successRate}%  Domains: ${domains}`);
+      }
+    }
+  });
+}
+
+async function skillsStats(options: CLIOptions): Promise<void> {
+  await withAtlas(options, async (atlas) => {
+    const lib = requireSkillLibrary(atlas);
+    const stats = lib.getStats();
+
+    if (options.format === 'json') {
+      console.log(JSON.stringify(stats, null, 2));
+    } else {
+      console.log('Skill Library Stats:\n');
+      console.log(`  Core skills: ${stats.coreSkillCount}`);
+      const domainEntries = Object.entries(stats.domainSkillCounts);
+      if (domainEntries.length > 0) {
+        console.log('  Domain skills:');
+        for (const [domain, count] of domainEntries) {
+          console.log(`    ${domain}: ${count}`);
+        }
+      } else {
+        console.log('  Domain skills: (none)');
+      }
+      console.log(`  Last refresh: ${stats.lastRefresh?.toISOString() ?? 'never'}`);
+      const failureEntries = Object.entries(stats.consecutiveFailures);
+      if (failureEntries.length > 0) {
+        console.log('  Consecutive failures:');
+        for (const [id, count] of failureEntries) {
+          console.log(`    ${id}: ${count}`);
+        }
+      }
+    }
+  });
+}
+
+async function skillsRefresh(options: CLIOptions): Promise<void> {
+  await withAtlas(options, async (atlas) => {
+    const lib = requireSkillLibrary(atlas);
+    const result = await lib.refreshTiers();
+
+    if (options.format === 'json') {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log('Tier refresh complete.\n');
+      if (result.promoted.length > 0) {
+        console.log(`  Promoted: ${result.promoted.join(', ')}`);
+      }
+      if (result.demoted.length > 0) {
+        console.log(`  Demoted: ${result.demoted.join(', ')}`);
+      }
+      console.log(`  Core count: ${result.coreCount}`);
+      const domainEntries = Object.entries(result.domainCounts);
+      if (domainEntries.length > 0) {
+        console.log('  Domain counts:');
+        for (const [domain, count] of domainEntries) {
+          console.log(`    ${domain}: ${count}`);
+        }
+      }
+    }
+  });
+}

package/src/embeddings/index.ts

@@ -30,6 +30,9 @@ export {
   type VectorSearchResult,
 } from './vector-store.js';
 
+// Inverted index (candidate narrowing)
+export { InvertedIndex } from './inverted-index.js';
+
 // Embedding manager (main interface)
 export {
   EmbeddingManager,

package/src/embeddings/inverted-index.ts

@@ -0,0 +1,134 @@
+/**
+ * Inverted Index
+ *
+ * Lightweight inverted index mapping tokens → document IDs for fast candidate
+ * narrowing. Used as an acceleration structure before expensive similarity
+ * scoring — not a replacement for scoring.
+ *
+ * Reuses the same tokenization approach as BM25Index (lowercase, split on
+ * whitespace/punctuation, filter stopwords).
+ */
+
+/**
+ * Inverted index for fast candidate set narrowing
+ */
+export class InvertedIndex {
+  private postings: Map<string, Set<string>> = new Map();
+  private docTokens: Map<string, string[]> = new Map();
+
+  /**
+   * Add a document to the index
+   */
+  add(id: string, content: string): void {
+    // Remove existing entry if updating
+    if (this.docTokens.has(id)) {
+      this.remove(id);
+    }
+
+    const tokens = this.tokenize(content);
+    this.docTokens.set(id, tokens);
+
+    for (const token of tokens) {
+      let posting = this.postings.get(token);
+      if (!posting) {
+        posting = new Set();
+        this.postings.set(token, posting);
+      }
+      posting.add(id);
+    }
+  }
+
+  /**
+   * Remove a document from the index
+   */
+  remove(id: string): boolean {
+    const tokens = this.docTokens.get(id);
+    if (!tokens) return false;
+
+    for (const token of tokens) {
+      const posting = this.postings.get(token);
+      if (posting) {
+        posting.delete(id);
+        if (posting.size === 0) {
+          this.postings.delete(token);
+        }
+      }
+    }
+
+    this.docTokens.delete(id);
+    return true;
+  }
+
+  /**
+   * Check if a document exists in the index
+   */
+  has(id: string): boolean {
+    return this.docTokens.has(id);
+  }
+
+  /**
+   * Get candidate document IDs for a query, ranked by number of matching tokens.
+   * Returns at most maxCandidates results.
+   */
+  getCandidates(query: string, maxCandidates = 50): string[] {
+    const queryTokens = this.tokenize(query);
+    if (queryTokens.length === 0) return [];
+
+    // Count matching tokens per document
+    const scores = new Map<string, number>();
+
+    for (const token of queryTokens) {
+      const posting = this.postings.get(token);
+      if (!posting) continue;
+      for (const id of posting) {
+        scores.set(id, (scores.get(id) ?? 0) + 1);
+      }
+    }
+
+    // Sort by match count descending, take top maxCandidates
+    return Array.from(scores.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, maxCandidates)
+      .map(([id]) => id);
+  }
+
+  /**
+   * Get the number of documents in the index
+   */
+  size(): number {
+    return this.docTokens.size;
+  }
+
+  /**
+   * Clear the entire index
+   */
+  clear(): void {
+    this.postings.clear();
+    this.docTokens.clear();
+  }
+
+  /**
+   * Tokenize text — lowercase, split on non-word chars, filter stopwords and short tokens
+   */
+  private tokenize(text: string): string[] {
+    return text
+      .toLowerCase()
+      .replace(/[^\w\s]/g, ' ')
+      .split(/\s+/)
+      .filter((t) => t.length > 1)
+      .filter((t) => !STOP_WORDS.has(t));
+  }
+}
+
+/**
+ * Common English stop words (same set as BM25Index)
+ */
+const STOP_WORDS = new Set([
+  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'for', 'from',
+  'has', 'he', 'in', 'is', 'it', 'its', 'of', 'on', 'or', 'that',
+  'the', 'to', 'was', 'were', 'will', 'with', 'this', 'but', 'they',
+  'have', 'had', 'what', 'when', 'where', 'who', 'which', 'why', 'how',
+  'all', 'each', 'every', 'both', 'few', 'more', 'most', 'other', 'some',
+  'such', 'no', 'nor', 'not', 'only', 'own', 'same', 'so', 'than', 'too',
+  'very', 'can', 'just', 'should', 'now',
+]);

package/src/embeddings/manager.ts

@@ -20,7 +20,9 @@ export interface SearchResult {
 export interface EmbeddingManagerOptions {
   /** Embedding provider (null for BM25-only mode) */
   provider?: EmbeddingProvider | null;
-  /** Path to sqlite-vec database file */
+  /** Shared DB connection from SqlitePersistence (preferred) */
+  db?: import('better-sqlite3').Database;
+  /** Path to sqlite-vec database file (legacy: separate DB file) */
   vectorStorePath?: string;
   /** Embedding dimension (required if provider is set) */
   dimension?: number;
@@ -42,15 +44,18 @@ export class EmbeddingManager {
 
   constructor(options: EmbeddingManagerOptions) {
     this.provider = options.provider ?? null;
-    this.useVectorSearch = this.provider !== null && !!options.vectorStorePath;
+    this.useVectorSearch = this.provider !== null && !!(options.vectorStorePath || options.db);
 
-    // Initialize vector store if we have a provider and path
-    if (this.useVectorSearch && options.vectorStorePath) {
+    // Initialize vector store if we have a provider and a DB source
+    if (this.useVectorSearch) {
       const dimension = options.dimension ?? this.provider!.dimension;
-      this.vectorStore = new SqliteVectorStore({
-        dbPath: options.vectorStorePath,
-        dimension,
-      });
+      if (options.db) {
+        this.vectorStore = new SqliteVectorStore({ db: options.db, dimension });
+      } else if (options.vectorStorePath) {
+        this.vectorStore = new SqliteVectorStore({ dbPath: options.vectorStorePath, dimension });
+      } else {
+        this.vectorStore = null;
+      }
     } else {
       this.vectorStore = null;
     }

package/src/embeddings/provider.ts

@@ -193,7 +193,7 @@ export class LocalEmbeddingProvider implements EmbeddingProvider {
 
   private async doInitialize(): Promise<void> {
     try {
-      // Dynamic import to avoid issues if transformers.js isn't installed
+      // Dynamic import — @huggingface/transformers is an optional dependency
       const { pipeline } = await import("@huggingface/transformers");
 
       // Create feature-extraction pipeline for embeddings
@@ -202,6 +202,14 @@ export class LocalEmbeddingProvider implements EmbeddingProvider {
       });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
+      if (
+        message.includes("Cannot find module") ||
+        message.includes("ERR_MODULE_NOT_FOUND")
+      ) {
+        throw new Error(
+          `Local embeddings require @huggingface/transformers. Install it with: npm install @huggingface/transformers`,
+        );
+      }
       throw new Error(
         `Failed to initialize local embedding model "${this.modelName}": ${message}`,
       );
@@ -244,9 +252,8 @@ export class LocalEmbeddingProvider implements EmbeddingProvider {
    */
   async isModelCached(): Promise<boolean> {
     try {
+      // Returns false if @huggingface/transformers is not installed
       const { env } = await import("@huggingface/transformers");
-      // Check if model files exist in cache
-      // This is a simplified check - the actual cache structure may vary
       return env.cacheDir !== undefined;
     } catch {
       return false;

package/src/embeddings/vector-store.ts

@@ -24,20 +24,29 @@ export class SqliteVectorStore {
   private dimension: number;
   private tableName: string;
   private initialized: boolean = false;
+  private ownsDb: boolean;
 
   constructor(options: {
-    dbPath: string;
+    db?: Database.Database;     // Shared DB connection (preferred)
+    dbPath?: string;            // Legacy: opens own connection
     dimension: number;
     tableName?: string;
   }) {
     this.dimension = options.dimension;
     this.tableName = options.tableName ?? 'atlas_embeddings';
 
-    // Create or open the database
-    this.db = new Database(options.dbPath);
-
-    // Load the sqlite-vec extension
-    sqliteVec.load(this.db);
+    if (options.db) {
+      this.db = options.db;
+      this.ownsDb = false;
+      // sqlite-vec may already be loaded on shared connection
+      try { sqliteVec.load(this.db); } catch { /* already loaded */ }
+    } else if (options.dbPath) {
+      this.db = new Database(options.dbPath);
+      this.ownsDb = true;
+      sqliteVec.load(this.db);
+    } else {
+      throw new Error('Either db or dbPath must be provided');
+    }
 
     this.initialize();
   }
@@ -312,10 +321,12 @@ export class SqliteVectorStore {
   }
 
   /**
-   * Close the database connection
+   * Close the database connection (only if this instance owns it)
    */
   close(): void {
-    this.db.close();
+    if (this.ownsDb) {
+      this.db.close();
+    }
   }
 
   /**
@@ -345,7 +356,8 @@ export class SqliteVectorStore {
  * Create a new vector store
  */
 export function createVectorStore(options: {
-  dbPath: string;
+  db?: Database.Database;
+  dbPath?: string;
   dimension: number;
   tableName?: string;
 }): SqliteVectorStore {