cognitive-core 0.2.5 → 0.3.1

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

@@ -1,485 +0,0 @@
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { CheckpointGitReader } from './git-reader.js';
-import { CheckpointParser } from './parser.js';
-import type {
-  SessionRecord,
-  CheckpointRef,
-  SessionQuery,
-  SessionQueryResult,
-  SessionBankOptions,
-  ProcessingLogEntry,
-} from './types.js';
-
-// ─── SessionBank ────────────────────────────────────────────────────
-// Main facade for reading SessionLog checkpoint data from orphan
-// branches. Read-only.
-// ─────────────────────────────────────────────────────────────────────
-
-const DEFAULT_BRANCH = 'sessionlog/checkpoints/v1';
-
-interface CachedSession {
-  record: SessionRecord;
-  hasTranscript: boolean;
-}
-
-interface ProcessingState {
-  entries: ProcessingLogEntry[];
-  sessionIds: Set<string>;
-}
-
-export class SessionBank {
-  private reader: CheckpointGitReader;
-  private parser: CheckpointParser;
-  private stateDir: string;
-  private cacheEnabled: boolean;
-  private repoPath: string;
-  private explicitBranch: string | undefined;
-
-  private available = false;
-  private initialized = false;
-  private detectedBranch: string = '';
-
-  // Cache
-  private cachedBranchHead: string | null = null;
-  private sessionCache = new Map<string, CachedSession>();
-  private checkpointCache: CheckpointRef[] | null = null;
-
-  // Processing state
-  private processingState: ProcessingState = {
-    entries: [],
-    sessionIds: new Set(),
-  };
-
-  constructor(options?: SessionBankOptions) {
-    this.repoPath = options?.repoPath ?? process.cwd();
-    this.explicitBranch = options?.branch;
-    this.stateDir = options?.stateDir ?? join(this.repoPath, '.atlas', 'session-bank');
-    this.cacheEnabled = options?.cache ?? true;
-
-    // Initial reader with explicit or default branch
-    const branch = this.explicitBranch ?? DEFAULT_BRANCH;
-    this.reader = new CheckpointGitReader({
-      repoPath: this.repoPath,
-      branch,
-      trailerKeys: options?.trailerKeys,
-    });
-    this.parser = new CheckpointParser();
-  }
-
-  // ── Lifecycle ──────────────────────────────────────────────────
-
-  async init(): Promise<void> {
-    this.available = await this.reader.branchExists();
-    if (this.available) {
-      this.detectedBranch = this.reader.branch;
-    }
-
-    await this.loadProcessingState();
-    if (this.available) {
-      this.cachedBranchHead = await this.reader.getBranchHead();
-    }
-    this.initialized = true;
-  }
-
-  isAvailable(): boolean {
-    return this.available;
-  }
-
-  /** The orphan branch name that was detected or configured. */
-  getBranch(): string {
-    return this.detectedBranch;
-  }
-
-  async close(): Promise<void> {
-    await this.saveProcessingState();
-  }
-
-  // ── Discovery (metadata-only, fast) ───────────────────────────
-
-  async listCheckpoints(): Promise<CheckpointRef[]> {
-    this.ensureInitialized();
-    if (!this.available) return [];
-
-    await this.ensureCacheValid();
-    if (this.checkpointCache) return this.checkpointCache;
-
-    const checkpointPaths = await this.reader.listCheckpoints();
-    const refs: CheckpointRef[] = [];
-
-    for (const path of checkpointPaths) {
-      try {
-        const rootMeta = await this.reader.readFileOrNull(
-          `${path}/metadata.json`,
-        );
-        if (rootMeta) {
-          const ref = this.parser.parseCheckpointSummary(rootMeta, path);
-          refs.push(ref);
-        }
-      } catch {
-        // Skip corrupt checkpoints
-      }
-    }
-
-    if (this.cacheEnabled) {
-      this.checkpointCache = refs;
-    }
-    return refs;
-  }
-
-  async discover(): Promise<SessionRecord[]> {
-    this.ensureInitialized();
-    if (!this.available) return [];
-
-    const refs = await this.listCheckpoints();
-    const sessions: SessionRecord[] = [];
-
-    for (const ref of refs) {
-      const sessionIndices = await this.reader.listSessions(ref.path);
-
-      for (const idx of sessionIndices) {
-        const cacheKey = `${ref.path}/${idx}`;
-        const cached = this.sessionCache.get(cacheKey);
-        if (cached) {
-          sessions.push(cached.record);
-          continue;
-        }
-
-        try {
-          const metaJson = await this.reader.readFile(
-            `${ref.path}/${idx}/metadata.json`,
-          );
-          const parsed = this.parser.parseMetadata(metaJson);
-
-          const record: SessionRecord = {
-            sessionId: parsed.sessionId,
-            checkpointId: parsed.checkpointId,
-            metadata: parsed.metadata,
-            transcript: [], // lazy — not loaded during discover
-            summary: parsed.summary,
-            tokenUsage: parsed.tokenUsage,
-            attribution: parsed.attribution,
-            source: {
-              branch: this.detectedBranch,
-              checkpointPath: ref.path,
-              sessionIndex: idx,
-            },
-          };
-
-          if (this.cacheEnabled) {
-            this.sessionCache.set(cacheKey, {
-              record,
-              hasTranscript: false,
-            });
-          }
-          sessions.push(record);
-        } catch {
-          // Skip sessions with unreadable metadata
-        }
-      }
-    }
-
-    return sessions;
-  }
-
-  async count(query?: SessionQuery): Promise<number> {
-    const sessions = await this.discover();
-    return this.filterByMetadata(sessions, query).length;
-  }
-
-  // ── Querying (loads transcripts on demand) ────────────────────
-
-  async query(query?: SessionQuery): Promise<SessionQueryResult> {
-    this.ensureInitialized();
-    if (!this.available) return { sessions: [], total: 0 };
-
-    // Discover all sessions (metadata only)
-    let sessions = await this.discover();
-
-    // Apply metadata-based filters first
-    sessions = this.filterByMetadata(sessions, query);
-    const total = sessions.length;
-
-    // Sort
-    const sort = query?.sort ?? 'newest';
-    sessions.sort((a, b) => {
-      const diff = a.metadata.createdAt.getTime() - b.metadata.createdAt.getTime();
-      return sort === 'newest' ? -diff : diff;
-    });
-
-    // Apply limit
-    if (query?.limit && query.limit > 0) {
-      sessions = sessions.slice(0, query.limit);
-    }
-
-    // Load transcripts for matching sessions
-    const fullSessions = await Promise.all(
-      sessions.map((s) => this.loadTranscript(s)),
-    );
-
-    // Apply search filter (requires transcript)
-    let result = fullSessions;
-    if (query?.search) {
-      const needle = query.search.toLowerCase();
-      result = result.filter((s) =>
-        s.transcript.some((msg) =>
-          msg.role === 'user' &&
-          msg.content.some(
-            (b) =>
-              b.type === 'text' &&
-              (b as { text: string }).text.toLowerCase().includes(needle),
-          ),
-        ),
-      );
-    }
-
-    return { sessions: result, total };
-  }
-
-  async getBySessionId(sessionId: string): Promise<SessionRecord | undefined> {
-    const sessions = await this.discover();
-    const match = sessions.find((s) => s.sessionId === sessionId);
-    if (!match) return undefined;
-    return this.loadTranscript(match);
-  }
-
-  async getByCheckpointId(checkpointId: string): Promise<SessionRecord[]> {
-    // Derive path from checkpoint ID
-    const shard = checkpointId.slice(0, 2);
-    const rest = checkpointId.slice(2);
-    const path = `${shard}/${rest}`;
-
-    const sessionIndices = await this.reader.listSessions(path);
-    const sessions: SessionRecord[] = [];
-
-    for (const idx of sessionIndices) {
-      try {
-        const metaJson = await this.reader.readFile(
-          `${path}/${idx}/metadata.json`,
-        );
-        const transcriptJsonl = await this.reader.readFileOrNull(
-          `${path}/${idx}/full.jsonl`,
-        );
-        const record = this.parser.parseSession(
-          metaJson,
-          transcriptJsonl ?? '',
-          path,
-          idx,
-          this.detectedBranch,
-        );
-        sessions.push(record);
-      } catch {
-        // Skip sessions with errors
-      }
-    }
-
-    return sessions;
-  }
-
-  async getByCommit(commitSha: string): Promise<SessionRecord[]> {
-    const checkpointId = await this.reader.getCheckpointTrailer(commitSha);
-    if (!checkpointId) return [];
-    return this.getByCheckpointId(checkpointId);
-  }
-
-  // ── Processing Tracking ───────────────────────────────────────
-
-  async markProcessed(
-    sessionId: string,
-    metadata?: Record<string, unknown>,
-  ): Promise<void> {
-    const entry: ProcessingLogEntry = {
-      sessionId,
-      processedAt: new Date(),
-      metadata,
-    };
-    this.processingState.entries.push(entry);
-    this.processingState.sessionIds.add(sessionId);
-    await this.saveProcessingState();
-  }
-
-  isProcessed(sessionId: string): boolean {
-    return this.processingState.sessionIds.has(sessionId);
-  }
-
-  getProcessingLog(): ProcessingLogEntry[] {
-    return [...this.processingState.entries];
-  }
-
-  // ── Cache Management ──────────────────────────────────────────
-
-  invalidateCache(): void {
-    this.sessionCache.clear();
-    this.checkpointCache = null;
-    this.cachedBranchHead = null;
-  }
-
-  // ── Private helpers ───────────────────────────────────────────
-
-  private ensureInitialized(): void {
-    if (!this.initialized) {
-      throw new Error(
-        'SessionBank not initialized. Call init() first.',
-      );
-    }
-  }
-
-  private async ensureCacheValid(): Promise<void> {
-    if (!this.cacheEnabled) return;
-
-    const currentHead = await this.reader.getBranchHead();
-    if (currentHead !== this.cachedBranchHead) {
-      this.invalidateCache();
-      this.cachedBranchHead = currentHead;
-    }
-  }
-
-  private filterByMetadata(
-    sessions: SessionRecord[],
-    query?: SessionQuery,
-  ): SessionRecord[] {
-    if (!query) return sessions;
-
-    let result = sessions;
-
-    if (query.since) {
-      const since = query.since.getTime();
-      result = result.filter(
-        (s) => s.metadata.createdAt.getTime() >= since,
-      );
-    }
-
-    if (query.before) {
-      const before = query.before.getTime();
-      result = result.filter(
-        (s) => s.metadata.createdAt.getTime() < before,
-      );
-    }
-
-    if (query.branch) {
-      result = result.filter((s) => s.metadata.branch === query.branch);
-    }
-
-    if (query.agent) {
-      result = result.filter((s) => s.metadata.agent === query.agent);
-    }
-
-    if (query.strategy) {
-      result = result.filter((s) => s.metadata.strategy === query.strategy);
-    }
-
-    if (query.hasSummary !== undefined) {
-      result = result.filter(
-        (s) => (s.summary !== undefined) === query.hasSummary,
-      );
-    }
-
-    if (query.unprocessedOnly) {
-      result = result.filter((s) => !this.isProcessed(s.sessionId));
-    }
-
-    return result;
-  }
-
-  private async loadTranscript(
-    session: SessionRecord,
-  ): Promise<SessionRecord> {
-    // Check if transcript is already loaded
-    if (session.transcript.length > 0) return session;
-
-    const cacheKey = `${session.source.checkpointPath}/${session.source.sessionIndex}`;
-    const cached = this.sessionCache.get(cacheKey);
-    if (cached?.hasTranscript) return cached.record;
-
-    const basePath = `${session.source.checkpointPath}/${session.source.sessionIndex}`;
-
-    // Try single file first
-    let transcriptContent = await this.reader.readFileOrNull(
-      `${basePath}/full.jsonl`,
-    );
-
-    if (transcriptContent === null) {
-      // Try chunked format
-      const chunks: string[] = [];
-      for (let i = 1; ; i++) {
-        const chunkNum = String(i).padStart(3, '0');
-        const chunk = await this.reader.readFileOrNull(
-          `${basePath}/full.jsonl.${chunkNum}`,
-        );
-        if (chunk === null) break;
-        chunks.push(chunk);
-      }
-      if (chunks.length > 0) {
-        transcriptContent = chunks.join('\n');
-      }
-    }
-
-    const transcript = transcriptContent
-      ? this.parser.parseTranscript(transcriptContent)
-      : [];
-
-    const fullRecord: SessionRecord = { ...session, transcript };
-
-    if (this.cacheEnabled) {
-      this.sessionCache.set(cacheKey, {
-        record: fullRecord,
-        hasTranscript: true,
-      });
-    }
-
-    return fullRecord;
-  }
-
-  private async loadProcessingState(): Promise<void> {
-    try {
-      const raw = await readFile(
-        join(this.stateDir, 'processed.json'),
-        'utf-8',
-      );
-      const data = JSON.parse(raw) as {
-        entries?: Array<{
-          sessionId: string;
-          processedAt: string;
-          metadata?: Record<string, unknown>;
-        }>;
-      };
-
-      const entries: ProcessingLogEntry[] = (data.entries ?? []).map((e) => ({
-        sessionId: e.sessionId,
-        processedAt: new Date(e.processedAt),
-        metadata: e.metadata,
-      }));
-
-      this.processingState = {
-        entries,
-        sessionIds: new Set(entries.map((e) => e.sessionId)),
-      };
-    } catch {
-      // No existing state — start fresh
-      this.processingState = { entries: [], sessionIds: new Set() };
-    }
-  }
-
-  private async saveProcessingState(): Promise<void> {
-    try {
-      await mkdir(this.stateDir, { recursive: true });
-      await writeFile(
-        join(this.stateDir, 'processed.json'),
-        JSON.stringify(
-          {
-            entries: this.processingState.entries.map((e) => ({
-              sessionId: e.sessionId,
-              processedAt: e.processedAt.toISOString(),
-              metadata: e.metadata,
-            })),
-          },
-          null,
-          2,
-        ),
-        'utf-8',
-      );
-    } catch {
-      // Best-effort persistence
-    }
-  }
-}

package/src/session-bank/types.ts

@@ -1,176 +0,0 @@
-// ─── Session Bank Types ───────────────────────────────────────────────
-// Standalone types for reading SessionLog checkpoint data from orphan
-// branches. Zero imports from cognitive-core — this module can be
-// extracted.
-// ─────────────────────────────────────────────────────────────────────
-
-// ─── Content Blocks (transcript) ────────────────────────────────────
-
-export interface TextBlock {
-  type: 'text';
-  text: string;
-}
-
-export interface ToolUseBlock {
-  type: 'tool_use';
-  id: string;
-  name: string;
-  input: Record<string, unknown>;
-}
-
-export interface ToolResultBlock {
-  type: 'tool_result';
-  toolUseId: string;
-  content: string;
-  isError?: boolean;
-}
-
-export type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock;
-
-// ─── Transcript Message ─────────────────────────────────────────────
-
-export interface TranscriptMessage {
-  /** Message role */
-  role: 'user' | 'assistant';
-  /** Unique message identifier */
-  uuid: string;
-  /** Content blocks (always an array, even for plain text) */
-  content: ContentBlock[];
-  /** Index in original JSONL file */
-  lineIndex: number;
-}
-
-// ─── Session Summary (from checkpoint AI summarizer) ────────────────
-
-export interface SessionSummary {
-  intent: string;
-  outcome: string;
-  learnings: {
-    repoPatterns: string[];
-    codeFindings: string[];
-    workflowPractices: string[];
-  };
-  frictionPoints: string[];
-  openItems: string[];
-}
-
-// ─── Token Usage ────────────────────────────────────────────────────
-
-export interface TokenUsage {
-  inputTokens: number;
-  cacheCreationTokens: number;
-  cacheReadTokens: number;
-  outputTokens: number;
-  apiCallCount: number;
-  subagentUsage?: TokenUsage[];
-  /** Computed: sum of input + output + cache tokens */
-  total: number;
-}
-
-// ─── Attribution ────────────────────────────────────────────────────
-
-export interface Attribution {
-  agentLinesAdded: number;
-  humanAdditions: number;
-  humanModifications: number;
-  humanRemovals: number;
-  totalCommittedLines: number;
-  /** 0-1 percentage of agent contribution */
-  agentContribution: number;
-}
-
-// ─── Session Metadata ───────────────────────────────────────────────
-
-export interface SessionMetadata {
-  cliVersion: string;
-  strategy: 'manual-commit' | 'auto-commit';
-  createdAt: Date;
-  branch: string;
-  agent: string;
-  filesTouched: string[];
-  isTask: boolean;
-  toolUseId?: string;
-  /** Line offset into the JSONL transcript */
-  checkpointTranscriptStart: number;
-}
-
-// ─── Session Source (provenance) ────────────────────────────────────
-
-export interface SessionSource {
-  /** Orphan branch name */
-  branch: string;
-  /** Path on branch: "<id[:2]>/<id[2:]>" */
-  checkpointPath: string;
-  /** Session subdirectory index: "0", "1", etc. */
-  sessionIndex: string;
-  /** Git commit SHA on the orphan branch */
-  commitSha?: string;
-  /** Git commit SHA on the source branch linked via trailer */
-  linkedCommitSha?: string;
-}
-
-// ─── SessionRecord — the primary data type ──────────────────────────
-
-export interface SessionRecord {
-  sessionId: string;
-  checkpointId: string;
-  metadata: SessionMetadata;
-  transcript: TranscriptMessage[];
-  summary?: SessionSummary;
-  tokenUsage: TokenUsage;
-  attribution?: Attribution;
-  source: SessionSource;
-}
-
-// ─── Checkpoint Reference (lightweight, no transcript) ──────────────
-
-export interface CheckpointRef {
-  checkpointId: string;
-  sessionIds: string[];
-  path: string;
-  sessionCount: number;
-}
-
-// ─── Query Types ────────────────────────────────────────────────────
-
-export interface SessionQuery {
-  since?: Date;
-  before?: Date;
-  branch?: string;
-  agent?: string;
-  search?: string;
-  strategy?: 'manual-commit' | 'auto-commit';
-  hasSummary?: boolean;
-  limit?: number;
-  sort?: 'newest' | 'oldest';
-  unprocessedOnly?: boolean;
-}
-
-export interface SessionQueryResult {
-  sessions: SessionRecord[];
-  total: number;
-}
-
-// ─── Processing Log ─────────────────────────────────────────────────
-
-export interface ProcessingLogEntry {
-  sessionId: string;
-  processedAt: Date;
-  metadata?: Record<string, unknown>;
-}
-
-// ─── Options ────────────────────────────────────────────────────────
-
-export interface SessionBankOptions {
-  /** Git repository path (default: process.cwd()) */
-  repoPath?: string;
-  /** Orphan branch name (default: 'sessionlog/checkpoints/v1'). */
-  branch?: string;
-  /** Directory to store processing state (default: '.atlas/session-bank') */
-  stateDir?: string;
-  /** Enable in-memory caching of parsed sessions (default: true) */
-  cache?: boolean;
-  /** Trailer keys to search for checkpoint IDs in commit messages.
-   *  Defaults to ['Sessionlog-Checkpoint']. */
-  trailerKeys?: string[];
-}

package/src/surfacing/index.ts

@@ -1,29 +0,0 @@
-export {
-  SkillLibrary,
-  createSkillLibrary,
-  type AgentSkills,
-  type TierRefreshResult,
-} from './skill-library.js';
-
-export {
-  TeamSkillLibrary,
-  createTeamSkillLibrary,
-  type TeamSkillLibraryConfig,
-  type RankedTeamPlaybook,
-  type RankedRolePlaybook,
-  type TeamOutcomeFeedback,
-  type RoleOutcomeFeedback,
-  type TeamAgentSkills,
-} from './team-skill-library.js';
-
-export type {
-  PublishResult,
-  DeprecateResult,
-} from './publisher.js';
-
-export {
-  SkillPublisher,
-  convertPlaybookToSkill,
-} from './skill-publisher.js';
-
-export { SqliteStorageAdapter } from './sqlite-storage-adapter.js';

package/src/surfacing/publisher.ts

@@ -1,23 +0,0 @@
-/**
- * Skill Publishing Types
- *
- * Result types for publishing graduated playbooks to skill-tree's
- * StorageAdapter. cognitive-core imports Skill and StorageAdapter
- * directly from skill-tree — no duplicate interfaces needed.
- */
-
-/** Result of publishing a skill */
-export interface PublishResult {
-  published: boolean;
-  skillId: string;
-  version: string;
-  isUpdate: boolean;
-  error?: string;
-}
-
-/** Result of deprecating a skill */
-export interface DeprecateResult {
-  deprecated: boolean;
-  skillId: string;
-  error?: string;
-}