cognitive-core 0.1.0 → 0.2.0

package/references/sessionlog/src/strategy/types.ts

@@ -0,0 +1,279 @@
+/**
+ * Strategy Engine Types
+ *
+ * Core types for the manual-commit strategy that orchestrates
+ * checkpoint creation, condensation, attribution, and commit hooks.
+ */
+
+import type { AgentType, CheckpointID, InitialAttribution, Summary, TokenUsage } from '../types.js';
+
+// ============================================================================
+// Strategy Constants
+// ============================================================================
+
+export const STRATEGY_NAME_MANUAL_COMMIT = 'manual-commit';
+export const MAX_COMMIT_TRAVERSAL_DEPTH = 1000;
+export const LOGS_ONLY_SCAN_LIMIT = 500;
+export const PROMPT_TRUNCATE_LENGTH = 500;
+export const STALE_SESSION_THRESHOLD_MS = 60 * 60 * 1000; // 1 hour
+
+// ============================================================================
+// Strategy Interface
+// ============================================================================
+
+export interface Strategy {
+  readonly name: string;
+
+  // Git hooks
+  prepareCommitMsg(commitMsgFile: string, source: string, sha: string): Promise<void>;
+  commitMsg(commitMsgFile: string): Promise<void>;
+  postCommit(): Promise<void>;
+  prePush(remote: string): Promise<void>;
+
+  // Session management
+  saveStep(step: StepContext): Promise<void>;
+  saveTaskStep(step: TaskStepContext): Promise<void>;
+
+  // Rewind
+  getRewindPoints(limit: number): Promise<RewindPoint[]>;
+  rewind(point: RewindPoint): Promise<void>;
+  canRewind(): Promise<[boolean, string]>;
+
+  // Condensation
+  condense(sessionID: string): Promise<CondensationResult>;
+
+  // Validation & Cleanup
+  validateRepository(): Promise<void>;
+  listOrphanedItems(): Promise<OrphanedItem[]>;
+}
+
+// ============================================================================
+// Step Context (checkpoint creation input)
+// ============================================================================
+
+export interface StepContext {
+  metadataDir: string;
+  metadataDirAbs: string;
+  commitMessage: string;
+  modifiedFiles: string[];
+  newFiles: string[];
+  deletedFiles: string[];
+  authorName: string;
+  authorEmail: string;
+  agentType: AgentType;
+  tokenUsage?: TokenUsage;
+  stepTranscriptIdentifier?: string;
+}
+
+export interface TaskStepContext {
+  sessionID: string;
+  toolUseID: string;
+  agentID?: string;
+  checkpointUUID: string;
+  modifiedFiles: string[];
+  newFiles: string[];
+  deletedFiles: string[];
+  transcriptPath?: string;
+  subagentTranscriptPath?: string;
+  commitMessage: string;
+  authorName: string;
+  authorEmail: string;
+  agentType: AgentType;
+  subagentType?: string;
+  taskDescription?: string;
+  todoContent?: string;
+  isIncremental: boolean;
+  incrementalSequence: number;
+  incrementalType?: string;
+  incrementalData?: Buffer;
+}
+
+// ============================================================================
+// Session State (strategy-level, extends base SessionState)
+// ============================================================================
+
+export interface StrategySessionState {
+  sessionID: string;
+  cliVersion?: string;
+  baseCommit: string;
+  attributionBaseCommit: string;
+  worktreePath: string;
+  worktreeID: string;
+  startedAt: Date;
+  lastInteractionTime?: Date;
+  turnID: string;
+  stepCount: number;
+  untrackedFilesAtStart: string[];
+  filesTouched: string[];
+  agentType: AgentType;
+  transcriptPath?: string;
+  firstPrompt?: string;
+  lastCheckpointID?: CheckpointID;
+  tokenUsage?: TokenUsage;
+  transcriptIdentifierAtStart?: string;
+  promptAttributions: PromptAttribution[];
+  pendingPromptAttribution?: PromptAttribution;
+  phase: 'idle' | 'active' | 'ended';
+}
+
+// ============================================================================
+// Prompt Attribution (per-checkpoint user edit tracking)
+// ============================================================================
+
+export interface PromptAttribution {
+  checkpointNumber: number;
+  userLinesAdded: number;
+  userLinesRemoved: number;
+  agentLinesAdded: number;
+  agentLinesRemoved: number;
+  userAddedPerFile: Record<string, number>;
+}
+
+// ============================================================================
+// Rewind Types
+// ============================================================================
+
+export interface RewindPoint {
+  id: string;
+  message: string;
+  metadataDir?: string;
+  date: Date;
+  isTaskCheckpoint: boolean;
+  isLogsOnly: boolean;
+  checkpointID?: CheckpointID;
+  agent?: AgentType;
+  sessionID?: string;
+  sessionPrompt?: string;
+  sessionCount: number;
+  sessionIDs: string[];
+  sessionPrompts?: string[];
+  toolUseID?: string;
+}
+
+export interface RewindPreview {
+  filesToRestore: string[];
+  filesToDelete: string[];
+}
+
+// ============================================================================
+// Condensation Result
+// ============================================================================
+
+export interface CondensationResult {
+  checkpointID: CheckpointID;
+  sessionsCondensed: number;
+  checkpointsCount: number;
+  filesTouched: string[];
+  tokenUsage?: TokenUsage;
+  attribution?: InitialAttribution;
+  summary?: Summary;
+}
+
+// ============================================================================
+// Checkpoint Info (from committed checkpoints)
+// ============================================================================
+
+export interface CheckpointInfo {
+  checkpointID: CheckpointID;
+  sessionID: string;
+  sessionCount: number;
+  sessionIDs: string[];
+  agent: AgentType;
+  createdAt: Date;
+}
+
+// ============================================================================
+// Session Info (for explain/resume)
+// ============================================================================
+
+export interface SessionInfo {
+  sessionID: string;
+  reference: string;
+  commitHash?: string;
+}
+
+// ============================================================================
+// Restore Types
+// ============================================================================
+
+export const enum SessionRestoreStatus {
+  New = 0,
+  Unchanged = 1,
+  CheckpointNewer = 2,
+  LocalNewer = 3,
+}
+
+export interface SessionRestoreInfo {
+  sessionID: string;
+  prompt: string;
+  status: SessionRestoreStatus;
+  localTime: Date;
+  checkpointTime: Date;
+}
+
+export interface RestoredSession {
+  sessionID: string;
+  agent: AgentType;
+  prompt: string;
+  createdAt?: string;
+}
+
+// ============================================================================
+// Orphaned Item (for cleanup)
+// ============================================================================
+
+export type OrphanedItemType = 'shadow-branch' | 'session-state';
+
+export interface OrphanedItem {
+  type: OrphanedItemType;
+  id: string;
+  reason: string;
+}
+
+// ============================================================================
+// Message Formatting
+// ============================================================================
+
+export function formatSubagentEndMessage(
+  subagentType: string | undefined,
+  taskDescription: string | undefined,
+  shortToolUseID: string,
+): string {
+  const parts: string[] = [];
+  if (subagentType) {
+    parts.push(`Task (${subagentType})`);
+  } else {
+    parts.push('Task');
+  }
+  if (taskDescription) {
+    // Truncate description to 50 chars
+    const desc =
+      taskDescription.length > 50 ? taskDescription.slice(0, 50) + '...' : taskDescription;
+    parts.push(desc);
+  }
+  parts.push(`[${shortToolUseID}]`);
+  return parts.join(' - ');
+}
+
+export function formatIncrementalSubject(
+  incrementalType: string | undefined,
+  subagentType: string | undefined,
+  taskDescription: string | undefined,
+  todoContent: string | undefined,
+  sequence: number,
+  shortToolUseID: string,
+): string {
+  const typeLabel = incrementalType || 'update';
+  const agentLabel = subagentType ? `(${subagentType})` : '';
+  const seqLabel = `#${sequence}`;
+
+  let descLabel = '';
+  if (todoContent) {
+    descLabel = todoContent.length > 40 ? todoContent.slice(0, 40) + '...' : todoContent;
+  } else if (taskDescription) {
+    descLabel =
+      taskDescription.length > 40 ? taskDescription.slice(0, 40) + '...' : taskDescription;
+  }
+
+  return `Task ${agentLabel} ${typeLabel} ${seqLabel}${descLabel ? ' - ' + descLabel : ''} [${shortToolUseID}]`.trim();
+}

package/references/sessionlog/src/summarize/claude-generator.ts

@@ -0,0 +1,115 @@
+/**
+ * Claude CLI Summary Generator
+ *
+ * Concrete implementation of the SummaryGenerator interface that
+ * shells out to the Claude CLI to generate session summaries.
+ */
+
+import { spawn } from 'node:child_process';
+import * as os from 'node:os';
+import type { Summary } from '../types.js';
+import {
+  formatCondensedTranscript,
+  buildSummarizationPrompt,
+  extractJSONFromMarkdown,
+  type SummarizeInput,
+  type SummaryGenerator,
+} from './summarize.js';
+
+/** Default model used for summarization. */
+export const DEFAULT_SUMMARIZE_MODEL = 'sonnet';
+
+export interface ClaudeGeneratorOptions {
+  /** Path to the claude CLI executable. Defaults to "claude". */
+  claudePath?: string;
+  /** Claude model to use for summarization. Defaults to "sonnet". */
+  model?: string;
+}
+
+/**
+ * Create a SummaryGenerator that shells out to the Claude CLI.
+ *
+ * The generator isolates the subprocess from the user's git repo by:
+ * - Running from os.tmpdir() to avoid git index pollution
+ * - Stripping GIT_* env vars to prevent recursive hook triggering
+ * - Using --setting-sources "" to skip all Claude settings
+ */
+export function createClaudeGenerator(options: ClaudeGeneratorOptions = {}): SummaryGenerator {
+  const claudePath = options.claudePath ?? 'claude';
+  const model = options.model ?? DEFAULT_SUMMARIZE_MODEL;
+
+  return {
+    async generate(input: SummarizeInput): Promise<Summary> {
+      const transcriptText = formatCondensedTranscript(input);
+      const prompt = buildSummarizationPrompt(transcriptText);
+
+      // Strip GIT_* env vars to isolate subprocess
+      const env: Record<string, string> = {};
+      for (const [key, val] of Object.entries(process.env)) {
+        if (!key.startsWith('GIT_') && val !== undefined) {
+          env[key] = val;
+        }
+      }
+
+      const stdout = await new Promise<string>((resolve, reject) => {
+        const child = spawn(
+          claudePath,
+          ['--print', '--output-format', 'json', '--model', model, '--setting-sources', ''],
+          {
+            cwd: os.tmpdir(),
+            env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 120_000,
+          },
+        );
+
+        const stdoutChunks: Buffer[] = [];
+        const stderrChunks: Buffer[] = [];
+
+        child.stdout.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
+        child.stderr.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
+
+        child.on('error', (err: NodeJS.ErrnoException) => {
+          if (err.code === 'ENOENT') {
+            reject(new Error(`claude CLI not found at "${claudePath}"`));
+          } else {
+            reject(new Error(`failed to run claude CLI: ${err.message}`));
+          }
+        });
+
+        child.on('close', (code) => {
+          if (code !== 0) {
+            const stderr = Buffer.concat(stderrChunks).toString('utf-8');
+            reject(new Error(`claude CLI failed (exit ${code}): ${stderr}`));
+          } else {
+            resolve(Buffer.concat(stdoutChunks).toString('utf-8'));
+          }
+        });
+
+        // Pass prompt via stdin
+        child.stdin.write(prompt);
+        child.stdin.end();
+      });
+
+      // Parse the CLI response (JSON with { result: "..." })
+      let cliResponse: { result: string };
+      try {
+        cliResponse = JSON.parse(stdout);
+      } catch {
+        throw new Error(`failed to parse claude CLI response: ${stdout.slice(0, 200)}`);
+      }
+
+      // The result field contains the actual JSON summary
+      const resultJSON = extractJSONFromMarkdown(cliResponse.result);
+
+      let summary: Summary;
+      try {
+        summary = JSON.parse(resultJSON);
+      } catch {
+        throw new Error(`failed to parse summary JSON: ${resultJSON.slice(0, 200)}`);
+      }
+
+      return summary;
+    },
+  };
+}