@macpaw/cctk 1.0.0-beta.1

package/templates/claude/hooks/lib/cctk-paths.cjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Claude Code Toolkit Paths - Centralized path constants for all temporary/runtime files
+ *
+ * All Claude Code Toolkit temp files consolidated under /tmp/cctk/ namespace for:
+ * - Cleaner /tmp directory (single namespace)
+ * - Easier cleanup (rm -rf /tmp/cctk/)
+ * - Debugging (all state in one place)
+ * - No collisions with other tools
+ *
+ * @module cctk-paths
+ */
+
+const path = require('node:path');
+const os = require('node:os');
+const fs = require('node:fs');
+
+// Root directory for all Claude Code Toolkit temp files
+const CCTK_TMP_DIR = path.join(os.tmpdir(), 'cctk');
+
+// Session-specific marker files (per-session, no race conditions)
+const MARKERS_DIR = path.join(CCTK_TMP_DIR, 'markers');
+
+// Global calibration data (shared by design - records compact thresholds)
+const CALIBRATION_PATH = path.join(CCTK_TMP_DIR, 'calibration.json');
+
+// Debug logs directory
+const DEBUG_DIR = path.join(CCTK_TMP_DIR, 'debug');
+
+/**
+ * Ensure directory exists
+ * @param {string} dirPath - Directory path to create
+ */
+function ensureDir(dirPath) {
+  try {
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+  } catch (error) {
+    // Silent fail - non-critical, but log for debugging
+    if (process.env.CCTK_DEBUG) {
+      console.error(`[CK] Failed to create ${dirPath}: ${error.message}`);
+    }
+  }
+}
+
+/**
+ * Get marker file path for a session
+ * @param {string} sessionId - Session ID
+ * @returns {string} Full path to marker file
+ */
+function getMarkerPath(sessionId) {
+  return path.join(MARKERS_DIR, `${sessionId}.json`);
+}
+
+/**
+ * Get debug log path for a session
+ * @param {string} sessionId - Session ID
+ * @returns {string} Full path to debug log
+ */
+function getDebugLogPath(sessionId) {
+  return path.join(DEBUG_DIR, `${sessionId}.log`);
+}
+
+/**
+ * Initialize Claude Code Toolkit temp directories
+ * Call this at startup to ensure directories exist
+ */
+function initDirs() {
+  ensureDir(CCTK_TMP_DIR);
+  ensureDir(MARKERS_DIR);
+  ensureDir(DEBUG_DIR);
+}
+
+/**
+ * Clean up all Claude Code Toolkit temp files
+ * Useful for testing or manual cleanup
+ */
+function cleanAll() {
+  try {
+    if (fs.existsSync(CCTK_TMP_DIR)) {
+      fs.rmSync(CCTK_TMP_DIR, { recursive: true, force: true });
+    }
+  } catch {
+    // Silent fail
+  }
+}
+
+module.exports = {
+  // Directories
+  CCTK_TMP_DIR,
+  MARKERS_DIR,
+  DEBUG_DIR,
+
+  // Files
+  CALIBRATION_PATH,
+
+  // Helpers
+  ensureDir,
+  getMarkerPath,
+  getDebugLogPath,
+  initDirs,
+  cleanAll,
+};

package/templates/claude/hooks/lib/context-tracker.cjs

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Context Window Tracker - Self-healing context reset detection
+ *
+ * Marker schema:
+ * {
+ *   sessionId: string,
+ *   trigger: string,           // 'session_start_clear', 'manual', 'auto', 'new_session', 'token_drop'
+ *   baselineRecorded: boolean,
+ *   baseline: number,          // Token count at baseline
+ *   lastTokenTotal: number,    // For token drop detection (replaces global state)
+ *   timestamp: number
+ * }
+ *
+ * @module context-tracker
+ */
+
+const fs = require('node:fs');
+const { MARKERS_DIR, CALIBRATION_PATH, ensureDir, getMarkerPath } = require('./cctk-paths.cjs');
+
+// Token drop threshold for Layer 2 detection (50%)
+// Rationale: /compact typically reduces tokens by 60-80%, so 50% catches
+// context resets while avoiding false positives from normal token accumulation.
+// Exclusive: drops below (<) 50% trigger reset
+const TOKEN_DROP_THRESHOLD = 0.5;
+
+/**
+ * Get smart default compact threshold based on context window size
+ * Estimated defaults:
+ * - 200k window: ~77.5% (155k)
+ * - 1M window: ~33% (330k)
+ *
+ * @param {number} contextWindowSize - Model's context window size
+ * @returns {number} Estimated compact threshold in tokens
+ */
+function getDefaultCompactThreshold(contextWindowSize) {
+  const KNOWN_THRESHOLDS = {
+    200_000: 155_000,
+    1_000_000: 330_000,
+  };
+
+  if (KNOWN_THRESHOLDS[contextWindowSize]) {
+    return KNOWN_THRESHOLDS[contextWindowSize];
+  }
+
+  // Tiered defaults based on window size
+  if (contextWindowSize >= 1_000_000) {
+    return Math.floor(contextWindowSize * 0.33);
+  }
+
+
+return Math.floor(contextWindowSize * 0.775);
+}
+
+/**
+ * Read calibration data from file (recorded by PreCompact hook)
+ * @returns {Object} Calibration data keyed by context window size
+ */
+function readCalibration() {
+  try {
+    if (fs.existsSync(CALIBRATION_PATH)) {
+      return JSON.parse(fs.readFileSync(CALIBRATION_PATH, 'utf8'));
+    }
+  } catch {
+    // Silent fail - use defaults
+  }
+
+
+return {};
+}
+
+/**
+ * Get compact threshold, preferring calibrated value over default
+ * @param {number} contextWindowSize - Model's context window size
+ * @returns {number} Compact threshold in tokens
+ */
+function getCompactThreshold(contextWindowSize) {
+  const calibration = readCalibration();
+  const key = String(contextWindowSize);
+
+  if (calibration[key] && calibration[key].threshold > 0) {
+    return calibration[key].threshold;
+  }
+
+
+return getDefaultCompactThreshold(contextWindowSize);
+}
+
+/**
+ * Read marker file for a session
+ * Defensive: handles missing/empty/corrupt files gracefully
+ * @param {string} sessionId - Session ID
+ * @returns {Object|null} Marker data or null
+ */
+function readMarker(sessionId) {
+  try {
+    const markerPath = getMarkerPath(sessionId);
+
+
+    if (!fs.existsSync(markerPath)) return null;
+    const data = fs.readFileSync(markerPath, 'utf8');
+
+
+    if (!data.trim()) return null; // Catch empty/corrupt files
+    const marker = JSON.parse(data);
+
+    if (!marker || typeof marker.sessionId !== 'string') {
+      return null;
+    }
+
+
+return marker;
+  } catch {
+    // Silent fail - corrupt JSON or read error
+  }
+
+
+return null;
+}
+
+/**
+ * Write marker file for a session
+ * @param {string} sessionId - Session ID
+ * @param {Object} marker - Marker data
+ */
+function writeMarker(sessionId, marker) {
+  try {
+    ensureDir(MARKERS_DIR);
+    const markerPath = getMarkerPath(sessionId);
+
+
+    fs.writeFileSync(markerPath, JSON.stringify(marker));
+  } catch {
+    // Silent fail
+  }
+}
+
+/**
+ * Delete marker file for a session
+ * @param {string} sessionId - Session ID
+ */
+function deleteMarker(sessionId) {
+  try {
+    const markerPath = getMarkerPath(sessionId);
+
+
+    if (fs.existsSync(markerPath)) {
+      fs.unlinkSync(markerPath);
+    }
+  } catch {
+    // Silent fail
+  }
+}
+
+/**
+ * Layer 2: Detect significant token drop (50%+ reduction)
+ * Uses session-specific lastTokenTotal from marker (no global state)
+ * @param {number} currentTotal - Current cumulative token total
+ * @param {Object|null} marker - Session marker with lastTokenTotal
+ * @returns {boolean} True if token drop detected
+ */
+function detectTokenDrop(currentTotal, marker) {
+  if (!marker || !marker.lastTokenTotal || marker.lastTokenTotal <= 0 || currentTotal <= 0) {
+    return false;
+  }
+
+  // Token total dropped by more than 50%
+  const dropRatio = currentTotal / marker.lastTokenTotal;
+
+
+
+return dropRatio < TOKEN_DROP_THRESHOLD;
+}
+
+/**
+ * Layer 1: Check for explicit reset marker from hooks
+ * @param {Object|null} marker - Session marker
+ * @returns {{ shouldReset: boolean, trigger: string|null }}
+ */
+function checkResetMarker(marker) {
+  if (!marker) {
+    return { shouldReset: false, trigger: null };
+  }
+
+  // Check if marker indicates a reset (clear/compact)
+  const resetTriggers = ['clear', 'session_start_clear'];
+
+
+  if (resetTriggers.includes(marker.trigger)) {
+    return { shouldReset: true, trigger: marker.trigger };
+  }
+
+  return { shouldReset: false, trigger: marker.trigger };
+}
+
+/**
+ * Main context tracking function with 2-layer self-healing detection
+ *
+ * Layer 1: Hook markers (explicit reset from PreCompact/SessionStart)
+ * Layer 2: Token drop detection (50% threshold fallback)
+ *
+ * NO global state - all state is session-specific in marker files
+ *
+ * @param {Object} params - Tracking parameters
+ * @param {string} params.sessionId - Current session ID
+ * @param {number} params.contextInput - Input tokens
+ * @param {number} params.contextOutput - Output tokens
+ * @param {number} params.contextWindowSize - Model's context window size
+ * @returns {Object} { percentage, baseline, showCompactIndicator, resetLayer }
+ */
+function trackContext({ sessionId, contextInput, contextOutput, contextWindowSize }) {
+  const currentTotal = contextInput + contextOutput;
+  const compactThreshold = getCompactThreshold(contextWindowSize);
+  const effectiveSessionId = sessionId || 'default';
+
+  // Read session-specific marker (no global state!)
+  let marker = readMarker(effectiveSessionId);
+
+  // Track which layer triggered reset (for debugging)
+  let resetLayer = null;
+  let baseline = 0;
+  let showCompactIndicator = false;
+
+  // --- Layer 1: Hook marker system ---
+  // Markers from PreCompact/SessionStart hooks are explicit signals
+  const { shouldReset, trigger } = checkResetMarker(marker);
+
+
+  if (shouldReset) {
+    resetLayer = `marker_${trigger}`;
+    baseline = currentTotal;
+    // Clear the reset trigger after processing
+    marker = null; // Force fresh marker creation below
+  }
+
+  // --- Layer 2: Token drop detection (fallback for hook failures) ---
+  if (!resetLayer && detectTokenDrop(currentTotal, marker)) {
+    resetLayer = 'token_drop';
+    baseline = currentTotal;
+    marker = null; // Force fresh marker creation below
+  }
+
+  // --- No reset triggered - use existing marker/baseline ---
+  if (!resetLayer && marker) {
+    if (marker.baselineRecorded) {
+      // Use stored baseline
+      baseline = marker.baseline || 0;
+    } else {
+      // Marker exists but baseline not recorded yet (from PreCompact)
+      marker.baselineRecorded = true;
+      marker.baseline = currentTotal;
+      marker.lastTokenTotal = currentTotal;
+      writeMarker(effectiveSessionId, marker);
+      baseline = currentTotal;
+      // PreCompact triggers: "manual" (from /compact) or "auto" (from auto-compact)
+      showCompactIndicator = ['compact', 'manual', 'auto'].includes(marker.trigger);
+    }
+  }
+
+  // --- Create fresh marker if needed ---
+  if (!marker || resetLayer) {
+    const newMarker = {
+      sessionId: effectiveSessionId,
+      trigger: resetLayer || 'new_session',
+      baselineRecorded: true,
+      baseline: currentTotal,
+      lastTokenTotal: currentTotal,
+      timestamp: Date.now(),
+    };
+
+
+    writeMarker(effectiveSessionId, newMarker);
+    if (!resetLayer) {
+      baseline = currentTotal;
+    }
+  } else {
+    // Update lastTokenTotal for next token drop detection
+    marker.lastTokenTotal = currentTotal;
+    writeMarker(effectiveSessionId, marker);
+  }
+
+  // Calculate effective tokens (since baseline)
+  let effectiveTotal = baseline > 0 ? currentTotal - baseline : currentTotal;
+
+
+  if (effectiveTotal < 0) effectiveTotal = 0;
+
+  // Calculate percentage against compact threshold (not model limit)
+  const percentage = Math.min(100, Math.floor((effectiveTotal * 100) / compactThreshold));
+
+  return {
+    percentage,
+    baseline,
+    effectiveTotal,
+    compactThreshold,
+    showCompactIndicator,
+    resetLayer,
+  };
+}
+
+/**
+ * Write reset marker for session (called by SessionStart hook on /clear)
+ * @param {string} sessionId - Session ID
+ * @param {string} trigger - Reset trigger ('clear', 'compact', etc.)
+ */
+function writeResetMarker(sessionId, trigger = 'clear') {
+  const effectiveSessionId = sessionId || 'default';
+
+
+  ensureDir(MARKERS_DIR);
+  writeMarker(effectiveSessionId, {
+    sessionId: effectiveSessionId,
+    trigger: `session_start_${trigger}`,
+    baselineRecorded: false,
+    baseline: 0,
+    lastTokenTotal: 0,
+    timestamp: Date.now(),
+  });
+}
+
+/**
+ * Clear all markers (for testing/cleanup)
+ */
+function clearAllState() {
+  const { cleanAll } = require('./cctk-paths.cjs');
+
+
+  cleanAll();
+}
+
+module.exports = {
+  trackContext,
+  writeResetMarker,
+  clearAllState,
+  getCompactThreshold,
+  // Export for testing
+  detectTokenDrop,
+  checkResetMarker,
+  readMarker,
+  writeMarker,
+  deleteMarker,
+  TOKEN_DROP_THRESHOLD,
+  MARKERS_DIR,
+};