cognitive-core 0.1.0 → 0.2.0

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

@@ -0,0 +1,485 @@
+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

@@ -0,0 +1,176 @@
+// ─── 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

@@ -4,3 +4,26 @@ export {
   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

@@ -0,0 +1,23 @@
+/**
+ * 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;
+}