@cnrai/pave 0.3.32 → 0.3.34

package/lib/compaction.js

@@ -0,0 +1,153 @@
+/**
+ * Shared constants and helpers for auto-compaction feature.
+ * This module has NO side effects when required - safe to import in tests.
+ *
+ * @module lib/compaction
+ */
+
+/**
+ * Allowlist of model IDs known to support compaction.
+ * This is a subset of models from opencode-lite/src/provider/models.js - only
+ * models verified to work well with compaction prompts are included.
+ * When an unknown model is specified, we fall back to a known model for compaction checks.
+ */
+const KNOWN_COMPACTION_MODELS = [
+  'claude-opus-4.5',
+  'claude-opus-4.6',
+  'claude-sonnet-4', // Canonical model advertised in CLI help
+  'claude-sonnet-4.5',
+  'claude-sonnet-4.6',
+  'claude-3-5-sonnet-20241022',
+  'claude-3-5-haiku-20241022',
+  'claude-3-opus-20240229',
+  'gpt-4',
+  'gpt-4-turbo',
+  'gpt-3.5-turbo',
+];
+
+/**
+ * Default provider ID when no provider prefix is given in the model string.
+ * Resolved at call time from env vars so tests/consumers can change env after require.
+ * Precedence: PAVE_COMPACT_MODEL > PAVE_MODEL > hardcoded default ('github-copilot')
+ */
+function getDefaultProviderIDForCompaction() {
+  const compactSpec = process.env.PAVE_COMPACT_MODEL;
+  if (compactSpec) {
+    // PAVE_COMPACT_MODEL is set - use its provider when both provider and model are non-empty.
+    if (compactSpec.includes('/')) {
+      const compactParts = compactSpec.split('/');
+      const compactProvider = (compactParts[0] || '').trim();
+      const compactModel = compactParts.slice(1).join('/').trim();
+      if (compactProvider && compactModel) return compactProvider;
+      // Empty provider but present model (e.g. "/model") -> treat like bare model ID
+      if (!compactProvider && compactModel) return 'github-copilot';
+      // Empty model (e.g. "provider/") -> fall through to PAVE_MODEL/default
+    } else {
+      // Bare model ID (no provider prefix) -> use hardcoded default provider without consulting PAVE_MODEL
+      return 'github-copilot';
+    }
+  }
+  const mainSpec = process.env.PAVE_MODEL;
+  if (mainSpec && mainSpec.includes('/')) {
+    const mainParts = mainSpec.split('/');
+    const mainProvider = (mainParts[0] || '').trim();
+    const mainModel = mainParts.slice(1).join('/').trim();
+    if (mainProvider && mainModel) return mainProvider;
+    // Empty provider but present model -> treat like bare model ID
+    if (!mainProvider && mainModel) return 'github-copilot';
+    // Malformed main spec -> fall through to hardcoded default
+  }
+  return 'github-copilot';
+}
+
+/**
+ * Default model ID for compaction operations.
+ * Resolved at call time from env vars so tests/consumers can change env after require.
+ * Precedence: PAVE_COMPACT_MODEL > PAVE_MODEL > hardcoded default ('claude-opus-4.5')
+ */
+function getDefaultModelIDForCompaction() {
+  const compactSpec = process.env.PAVE_COMPACT_MODEL;
+  if (compactSpec) {
+    let compactModel;
+    if (compactSpec.includes('/')) {
+      compactModel = compactSpec.split('/').slice(1).join('/').trim();
+    } else {
+      compactModel = compactSpec.trim();
+    }
+    if (compactModel) return compactModel;
+    // Malformed compact spec (e.g. "provider/") -> fall through to mainSpec/default
+  }
+  const mainSpec = process.env.PAVE_MODEL;
+  if (mainSpec) {
+    let mainModel;
+    if (mainSpec.includes('/')) {
+      mainModel = mainSpec.split('/').slice(1).join('/').trim();
+    } else {
+      mainModel = mainSpec.trim();
+    }
+    if (mainModel) return mainModel;
+    // Malformed main spec -> fall through to hardcoded default
+  }
+  return 'claude-opus-4.5';
+}
+
+/**
+ * Parse a model string into provider and model IDs for compaction operations.
+ * Model strings can be "provider/model" or just "model".
+ *
+ * @param {string} model - The model string to parse (e.g., "github-copilot/claude-opus-4.6" or "gpt-4")
+ * @returns {{ providerID: string, modelID: string, compactionModelID: string }}
+ */
+function parseModelForCompaction(model) {
+  // Resolve defaults at call time (not module-load time) so env var changes are respected
+  const defaultProviderID = getDefaultProviderIDForCompaction();
+  const defaultModelID = getDefaultModelIDForCompaction();
+
+  let providerID = defaultProviderID;
+  let modelID = defaultModelID;
+
+  if (model) {
+    if (model.includes('/')) {
+      const parts = model.split('/');
+      const parsedProvider = (parts[0] || '').trim();
+      const parsedModel = parts.slice(1).join('/').trim();
+      if (parsedProvider) providerID = parsedProvider;
+      // else: empty provider (e.g. "/model") -> keep default
+      if (parsedModel) modelID = parsedModel;
+      // else: empty model (e.g. "provider/") -> keep default
+    } else {
+      const trimmedModel = model.trim();
+      if (trimmedModel) modelID = trimmedModel;
+    }
+  }
+
+  // Use a known model for compaction checks if the parsed model is not in the registry.
+  // Also validate that defaultModelID is known; fall back to hardcoded default if env var
+  // specifies an unlisted model (e.g. PAVE_COMPACT_MODEL=gpt-4o).
+  const HARDCODED_COMPACTION_DEFAULT = 'claude-opus-4.5';
+  const knownFallback = KNOWN_COMPACTION_MODELS.includes(defaultModelID)
+    ? defaultModelID : HARDCODED_COMPACTION_DEFAULT;
+  const compactionModelID = KNOWN_COMPACTION_MODELS.includes(modelID) ? modelID : knownFallback;
+
+  return { providerID, modelID, compactionModelID };
+}
+
+module.exports = {
+  KNOWN_COMPACTION_MODELS,
+  // NOTE: DEFAULT_* are exported as getters so they reflect current env vars
+  // on each property access, e.g.:
+  //   const compaction = require('./compaction');
+  //   const modelIdNow = compaction.DEFAULT_MODEL_ID;
+  //
+  // Do NOT destructure these if you need dynamic behavior:
+  //   const { DEFAULT_MODEL_ID } = require('./compaction');
+  // This will snapshot the value at require time and will not see later
+  // process.env changes. Prefer calling the functions directly instead:
+  //   const { getDefaultModelIDForCompaction } = require('./compaction');
+  //   const modelIdNow = getDefaultModelIDForCompaction();
+  get DEFAULT_PROVIDER_ID() { return getDefaultProviderIDForCompaction(); },
+  get DEFAULT_MODEL_ID() { return getDefaultModelIDForCompaction(); },
+  getDefaultProviderIDForCompaction,
+  getDefaultModelIDForCompaction,
+  parseModelForCompaction,
+};

package/lib/duration.js

@@ -0,0 +1,94 @@
+/**
+ * Duration parsing and formatting utilities for PAVE agent mode
+ * Side-effect-free module that can be safely imported by tests
+ */
+
+// Maximum setTimeout delay (~24.8 days) - Node.js uses 32-bit signed integer for delays
+const MAX_SETTIMEOUT_MS = 2147483647;
+const MIN_SLEEP_MS = 1000; // Minimum 1 second to prevent tight loops
+
+/**
+ * Parse sleep duration string to milliseconds
+ * Supports: 5s (seconds), 5m (minutes), 1h (hours), 1d (days)
+ * @param {string|null|undefined} duration - Duration string (e.g., '30m', '1h', '5s'), or falsy value for default
+ * @returns {number} Duration in milliseconds (default: 5 minutes if not specified or empty)
+ */
+function parseSleepDuration(duration) {
+  if (!duration) return 5 * 60 * 1000; // Default: 5 minutes (handles null, undefined, empty string)
+
+  const match = duration.match(/^(\d+(?:\.\d+)?)\s*(s|sec|m|min|h|hr|hour|d|day)?$/i);
+  if (!match) {
+    throw new Error(`Invalid sleep duration: ${duration}. Use format like '30m', '1h', '5s'`);
+  }
+
+  const value = parseFloat(match[1]);
+  const unit = (match[2] || 'm').toLowerCase();
+
+  // Validate value is positive
+  if (value <= 0) {
+    throw new Error(`Sleep duration must be greater than 0. Got: ${duration}`);
+  }
+
+  let ms;
+  switch (unit) {
+    case 's':
+    case 'sec':
+      ms = value * 1000;
+      break;
+    case 'm':
+    case 'min':
+      ms = value * 60 * 1000;
+      break;
+    case 'h':
+    case 'hr':
+    case 'hour':
+      ms = value * 60 * 60 * 1000;
+      break;
+    case 'd':
+    case 'day':
+      ms = value * 24 * 60 * 60 * 1000;
+      break;
+    default:
+      ms = value * 60 * 1000; // Default to minutes
+  }
+
+  // Validate minimum sleep duration
+  if (ms < MIN_SLEEP_MS) {
+    throw new Error(`Sleep duration must be at least 1 second. Got: ${duration}`);
+  }
+
+  // Validate maximum sleep duration (setTimeout limit)
+  if (ms > MAX_SETTIMEOUT_MS) {
+    throw new Error(`Sleep duration exceeds maximum of ~24.8 days. Got: ${duration}. Use a smaller value.`);
+  }
+
+  return ms;
+}
+
+/**
+ * Format milliseconds to human-readable duration
+ * @param {number} ms - Duration in milliseconds
+ * @returns {string} Human-readable duration string
+ */
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) {
+    const seconds = ms / 1000;
+    const precision = Number.isInteger(seconds) ? 0 : 1;
+    return `${seconds.toFixed(precision)}s`;
+  }
+  if (ms < 3600000) {
+    const minutes = ms / 60000;
+    const precision = Number.isInteger(minutes) ? 0 : 1;
+    return `${minutes.toFixed(precision)}m`;
+  }
+  if (ms < 86400000) return `${(ms / 3600000).toFixed(1)}h`;
+  return `${(ms / 86400000).toFixed(1)}d`;
+}
+
+module.exports = {
+  parseSleepDuration,
+  formatDuration,
+  MAX_SETTIMEOUT_MS,
+  MIN_SLEEP_MS,
+};

package/lib/hash.js

@@ -0,0 +1,22 @@
+/**
+ * Simple string hash utility for SOUL content change detection.
+ *
+ * Uses a fast non-cryptographic hash (djb2) which is sufficient for
+ * detecting file content changes. Avoids depending on the 'crypto'
+ * module so that the same function can be used in sandboxed test
+ * environments where 'crypto' is not available.
+ *
+ * @param {string} str - Input string to hash
+ * @returns {string} Hex string hash
+ */
+function simpleHash(str) {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    // hash * 33 + char
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
+  }
+  // Convert to unsigned 32-bit hex string
+  return (hash >>> 0).toString(16);
+}
+
+module.exports = { simpleHash };