ruvector 0.2.32 → 0.2.33

package/src/decompiler/witness.js

@@ -1,140 +1,140 @@
-/**
- * witness.js - SHA-256 witness chain generation and verification.
- *
- * A witness chain is a Merkle-like structure that cryptographically proves
- * the decompiled output derives from a specific input bundle.
- *
- * Chain structure:
- *   root = H(source_hash || module_hashes[0] || ... || module_hashes[n])
- *
- * Each entry records:
- *   { hash, label, parent }
- * so the chain can be verified without re-running the decompiler.
- */
-
-'use strict';
-
-const crypto = require('crypto');
-
-/**
- * Compute SHA-256 hash of a string or buffer.
- * @param {string|Buffer} data
- * @returns {string} hex-encoded hash
- */
-function sha256(data) {
-  return crypto.createHash('sha256').update(data).digest('hex');
-}
-
-/**
- * Build a witness chain from source and decompiled modules.
- *
- * @param {string} source - original bundle source code
- * @param {Array<{name: string, content: string}>} modules - decompiled modules
- * @returns {{
- *   source_hash: string,
- *   module_hashes: Array<{name: string, hash: string}>,
- *   root: string,
- *   chain: Array<{hash: string, label: string, parent: string|null}>,
- *   created: string,
- *   algorithm: string
- * }}
- */
-function buildWitnessChain(source, modules) {
-  const sourceHash = sha256(source);
-  const chain = [];
-  const moduleHashes = [];
-
-  // Root node: the source hash
-  chain.push({
-    hash: sourceHash,
-    label: 'source',
-    parent: null,
-  });
-
-  // One node per decompiled module
-  for (const mod of modules) {
-    const modHash = sha256(mod.content);
-    moduleHashes.push({ name: mod.name, hash: modHash });
-
-    chain.push({
-      hash: modHash,
-      label: `module:${mod.name}`,
-      parent: sourceHash,
-    });
-  }
-
-  // Compute Merkle root: H(source_hash || mod_hash_0 || ... || mod_hash_n)
-  const allHashes = sourceHash + moduleHashes.map((m) => m.hash).join('');
-  const root = sha256(allHashes);
-
-  chain.push({
-    hash: root,
-    label: 'root',
-    parent: sourceHash,
-  });
-
-  return {
-    source_hash: sourceHash,
-    module_hashes: moduleHashes,
-    root,
-    chain,
-    created: new Date().toISOString(),
-    algorithm: 'sha256',
-  };
-}
-
-/**
- * Verify a witness chain against a source file.
- *
- * @param {object} witness - the witness object (from buildWitnessChain)
- * @param {string} [sourceContent] - original source to verify against (optional)
- * @returns {{valid: boolean, chain_length: number, root: string, errors: string[]}}
- */
-function verifyWitnessChain(witness, sourceContent) {
-  const errors = [];
-
-  if (!witness || !witness.chain || !witness.root) {
-    return { valid: false, chain_length: 0, root: '', errors: ['Missing witness data'] };
-  }
-
-  // Verify source hash if content provided
-  if (sourceContent) {
-    const actualSourceHash = sha256(sourceContent);
-    if (actualSourceHash !== witness.source_hash) {
-      errors.push(
-        `Source hash mismatch: expected ${witness.source_hash}, got ${actualSourceHash}`,
-      );
-    }
-  }
-
-  // Verify chain integrity: each node's parent must exist in the chain
-  const hashSet = new Set(witness.chain.map((n) => n.hash));
-  for (const node of witness.chain) {
-    if (node.parent && !hashSet.has(node.parent)) {
-      errors.push(`Broken chain: node ${node.label} references missing parent ${node.parent}`);
-    }
-  }
-
-  // Recompute root from module hashes
-  if (witness.module_hashes && witness.source_hash) {
-    const allHashes =
-      witness.source_hash + witness.module_hashes.map((m) => m.hash).join('');
-    const expectedRoot = sha256(allHashes);
-    if (expectedRoot !== witness.root) {
-      errors.push(`Root mismatch: expected ${expectedRoot}, got ${witness.root}`);
-    }
-  }
-
-  return {
-    valid: errors.length === 0,
-    chain_length: witness.chain.length,
-    root: witness.root,
-    errors,
-  };
-}
-
-module.exports = {
-  sha256,
-  buildWitnessChain,
-  verifyWitnessChain,
-};
+/**
+ * witness.js - SHA-256 witness chain generation and verification.
+ *
+ * A witness chain is a Merkle-like structure that cryptographically proves
+ * the decompiled output derives from a specific input bundle.
+ *
+ * Chain structure:
+ *   root = H(source_hash || module_hashes[0] || ... || module_hashes[n])
+ *
+ * Each entry records:
+ *   { hash, label, parent }
+ * so the chain can be verified without re-running the decompiler.
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Compute SHA-256 hash of a string or buffer.
+ * @param {string|Buffer} data
+ * @returns {string} hex-encoded hash
+ */
+function sha256(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * Build a witness chain from source and decompiled modules.
+ *
+ * @param {string} source - original bundle source code
+ * @param {Array<{name: string, content: string}>} modules - decompiled modules
+ * @returns {{
+ *   source_hash: string,
+ *   module_hashes: Array<{name: string, hash: string}>,
+ *   root: string,
+ *   chain: Array<{hash: string, label: string, parent: string|null}>,
+ *   created: string,
+ *   algorithm: string
+ * }}
+ */
+function buildWitnessChain(source, modules) {
+  const sourceHash = sha256(source);
+  const chain = [];
+  const moduleHashes = [];
+
+  // Root node: the source hash
+  chain.push({
+    hash: sourceHash,
+    label: 'source',
+    parent: null,
+  });
+
+  // One node per decompiled module
+  for (const mod of modules) {
+    const modHash = sha256(mod.content);
+    moduleHashes.push({ name: mod.name, hash: modHash });
+
+    chain.push({
+      hash: modHash,
+      label: `module:${mod.name}`,
+      parent: sourceHash,
+    });
+  }
+
+  // Compute Merkle root: H(source_hash || mod_hash_0 || ... || mod_hash_n)
+  const allHashes = sourceHash + moduleHashes.map((m) => m.hash).join('');
+  const root = sha256(allHashes);
+
+  chain.push({
+    hash: root,
+    label: 'root',
+    parent: sourceHash,
+  });
+
+  return {
+    source_hash: sourceHash,
+    module_hashes: moduleHashes,
+    root,
+    chain,
+    created: new Date().toISOString(),
+    algorithm: 'sha256',
+  };
+}
+
+/**
+ * Verify a witness chain against a source file.
+ *
+ * @param {object} witness - the witness object (from buildWitnessChain)
+ * @param {string} [sourceContent] - original source to verify against (optional)
+ * @returns {{valid: boolean, chain_length: number, root: string, errors: string[]}}
+ */
+function verifyWitnessChain(witness, sourceContent) {
+  const errors = [];
+
+  if (!witness || !witness.chain || !witness.root) {
+    return { valid: false, chain_length: 0, root: '', errors: ['Missing witness data'] };
+  }
+
+  // Verify source hash if content provided
+  if (sourceContent) {
+    const actualSourceHash = sha256(sourceContent);
+    if (actualSourceHash !== witness.source_hash) {
+      errors.push(
+        `Source hash mismatch: expected ${witness.source_hash}, got ${actualSourceHash}`,
+      );
+    }
+  }
+
+  // Verify chain integrity: each node's parent must exist in the chain
+  const hashSet = new Set(witness.chain.map((n) => n.hash));
+  for (const node of witness.chain) {
+    if (node.parent && !hashSet.has(node.parent)) {
+      errors.push(`Broken chain: node ${node.label} references missing parent ${node.parent}`);
+    }
+  }
+
+  // Recompute root from module hashes
+  if (witness.module_hashes && witness.source_hash) {
+    const allHashes =
+      witness.source_hash + witness.module_hashes.map((m) => m.hash).join('');
+    const expectedRoot = sha256(allHashes);
+    if (expectedRoot !== witness.root) {
+      errors.push(`Root mismatch: expected ${expectedRoot}, got ${witness.root}`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    chain_length: witness.chain.length,
+    root: witness.root,
+    errors,
+  };
+}
+
+module.exports = {
+  sha256,
+  buildWitnessChain,
+  verifyWitnessChain,
+};

package/src/optimizer/context.js

@@ -0,0 +1,149 @@
+/**
+ * Context window optimization based on Claude Code's compaction internals.
+ *
+ * The decompilation of v2.1.91 revealed:
+ * - Compaction triggers at ~80% of the context window
+ * - The `clear_tool_uses_20250919` API feature enables server-side compaction
+ * - Deferred tool loading via ToolSearch saves ~2000 tokens per unused tool
+ * - Prompt cache sharing (`promptCacheSharingEnabled`) caches static prefixes
+ *
+ * This module helps RVAgent structure prompts and manage context to
+ * maximise cache hits and minimise unnecessary token usage.
+ */
+
+'use strict';
+
+const { TOOL_NAMES } = require('./tool-schemas');
+
+/** Default context window sizes by model family. */
+const MODEL_CONTEXT_SIZES = {
+  'claude-sonnet-4-20250514': 200000,
+  'claude-opus-4-20250514': 200000,
+  'claude-haiku-3.5': 200000,
+  default: 200000,
+};
+
+/** Approximate token overhead per tool schema sent in the system prompt. */
+const TOKENS_PER_TOOL_SCHEMA = 120;
+
+/**
+ * Build a deferred tool list — instead of sending all 25+ tool schemas
+ * up front (costing ~3000 tokens), only include the tools the task
+ * actually needs. The rest can be fetched on demand via ToolSearch.
+ *
+ * @param {string[]} requiredTools - tool names this task needs
+ * @returns {{ included: string[], deferred: string[], tokensSaved: number }}
+ */
+function buildDeferredToolList(requiredTools) {
+  const required = new Set(requiredTools || []);
+  const included = [];
+  const deferred = [];
+
+  for (const tool of TOOL_NAMES) {
+    if (required.has(tool)) {
+      included.push(tool);
+    } else {
+      deferred.push(tool);
+    }
+  }
+
+  const tokensSaved = deferred.length * TOKENS_PER_TOOL_SCHEMA;
+  return { included, deferred, tokensSaved };
+}
+
+/**
+ * Build a cache-optimised prompt structure.
+ *
+ * Claude Code's `promptCacheSharingEnabled` caches the longest common
+ * prefix across requests. To maximise cache hits:
+ * 1. Put static content first (tool schemas, CLAUDE.md rules)
+ * 2. Put dynamic/session-specific content after
+ *
+ * @param {string} staticRules  - stable content (tool schemas, rules)
+ * @param {string} dynamicContext - session-specific content (files, history)
+ * @returns {{ cached: string, dynamic: string, totalTokensEstimate: number }}
+ */
+function buildCacheOptimizedPrompt(staticRules, dynamicContext) {
+  const staticTokens = estimateTokens(staticRules);
+  const dynamicTokens = estimateTokens(dynamicContext);
+
+  return {
+    cached: staticRules,
+    dynamic: dynamicContext,
+    totalTokensEstimate: staticTokens + dynamicTokens,
+    cacheableTokens: staticTokens,
+  };
+}
+
+/**
+ * Determine whether compaction should be triggered.
+ *
+ * From the decompiled source, Claude Code triggers compaction when the
+ * token count reaches approximately 80% of the context window. This
+ * function mirrors that threshold.
+ *
+ * @param {number} tokenCount   - current token usage
+ * @param {number} [maxContext] - max context window (default 200000)
+ * @returns {boolean}
+ */
+function shouldCompact(tokenCount, maxContext) {
+  const max = maxContext || MODEL_CONTEXT_SIZES.default;
+  return tokenCount > max * 0.8;
+}
+
+/**
+ * Estimate the number of tokens in a string.
+ * Uses the common heuristic of ~4 characters per token for English text.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Recommend which tools to include for a given task type.
+ * This avoids sending all tool schemas when only a subset is needed.
+ *
+ * @param {string} taskType
+ * @returns {string[]}
+ */
+function recommendToolsForTask(taskType) {
+  const base = ['Read', 'Bash', 'Glob', 'Grep'];
+
+  const taskTools = {
+    coding: [...base, 'Edit', 'Write', 'Agent', 'ToolSearch'],
+    research: [...base, 'WebFetch', 'WebSearch', 'Agent'],
+    quickfix: [...base, 'Edit'],
+    planning: [...base, 'Agent', 'TodoWrite'],
+    background: [...base, 'Edit', 'Write', 'Agent'],
+    swarm: [...base, 'Edit', 'Write', 'Agent', 'ToolSearch'],
+    review: [...base],
+    ci: [...base, 'Edit', 'Write'],
+  };
+
+  return taskTools[taskType] || base;
+}
+
+/**
+ * Get context window size for a model identifier.
+ *
+ * @param {string} model
+ * @returns {number}
+ */
+function getContextSize(model) {
+  return MODEL_CONTEXT_SIZES[model] || MODEL_CONTEXT_SIZES.default;
+}
+
+module.exports = {
+  MODEL_CONTEXT_SIZES,
+  TOKENS_PER_TOOL_SCHEMA,
+  buildDeferredToolList,
+  buildCacheOptimizedPrompt,
+  shouldCompact,
+  estimateTokens,
+  recommendToolsForTask,
+  getContextSize,
+};

package/src/optimizer/index.js

@@ -0,0 +1,177 @@
+/**
+ * RVAgent Optimizer — Claude Code configuration profiles (ADR-139).
+ *
+ * Maps a task type (coding, research, quickfix, …) to an optimal set of
+ * `CLAUDE_CODE_*` environment variables and a permission mode. Profiles are
+ * derived from the decompiled Claude Code intelligence (see ADR-139) and are
+ * consumed by `npx ruvector optimize` and the settings generator.
+ *
+ * Public API:
+ *   - PERMISSION_MODES            — valid permission-mode strings
+ *   - listProfiles()              — array of profile names
+ *   - getProfile(name)            — { description, permissionMode, env } | null
+ *   - applyProfile(name)          — sets process.env, returns { applied, permissionMode } | null
+ *   - detectTaskType(prompt)      — infer a profile name from a free-text prompt
+ */
+
+'use strict';
+
+/** Permission modes understood by Claude Code's harness. */
+const PERMISSION_MODES = [
+  'default',
+  'acceptEdits',
+  'bypassPermissions',
+  'plan',
+  'dontAsk',
+  'auto',
+];
+
+/**
+ * Task profiles. Every env key MUST start with `CLAUDE_CODE_` and every
+ * `permissionMode` MUST be a member of {@link PERMISSION_MODES}.
+ */
+const PROFILES = {
+  coding: {
+    description: 'Implementation work — edits with checkpointing and thinking enabled',
+    permissionMode: 'acceptEdits',
+    env: {
+      CLAUDE_CODE_EFFORT_LEVEL: 'high',
+      CLAUDE_CODE_THINKING: '1',
+      CLAUDE_CODE_AUTO_COMPACT: '1',
+      CLAUDE_CODE_FILE_CHECKPOINTING: '1',
+    },
+  },
+  research: {
+    description: 'Investigation and analysis — read-heavy, no edits, deep reasoning',
+    permissionMode: 'default',
+    env: {
+      CLAUDE_CODE_EFFORT_LEVEL: 'high',
+      CLAUDE_CODE_THINKING: '1',
+      CLAUDE_CODE_AUTO_COMPACT: '1',
+    },
+  },
+  quickfix: {
+    description: 'Small, fast fixes — brief output, low effort, quick turnaround',
+    permissionMode: 'acceptEdits',
+    env: {
+      CLAUDE_CODE_BRIEF: '1',
+      CLAUDE_CODE_EFFORT_LEVEL: 'low',
+      CLAUDE_CODE_THINKING: '0',
+    },
+  },
+  planning: {
+    description: 'Architecture and design — plan mode, no edits until approved',
+    permissionMode: 'plan',
+    env: {
+      CLAUDE_CODE_EFFORT_LEVEL: 'high',
+      CLAUDE_CODE_THINKING: '1',
+    },
+  },
+  background: {
+    description: 'Long-running background/daemon work — autonomous, minimal prompts',
+    permissionMode: 'bypassPermissions',
+    env: {
+      CLAUDE_CODE_EFFORT_LEVEL: 'medium',
+      CLAUDE_CODE_AUTO_COMPACT: '1',
+      CLAUDE_CODE_PROMPT_SUGGESTION: '0',
+    },
+  },
+  swarm: {
+    description: 'Multi-agent swarm coordination — autonomous, hooks-driven',
+    permissionMode: 'bypassPermissions',
+    env: {
+      CLAUDE_CODE_EFFORT_LEVEL: 'medium',
+      CLAUDE_CODE_AUTO_COMPACT: '1',
+      CLAUDE_CODE_THINKING: '1',
+    },
+  },
+  review: {
+    description: 'Code review — read-only, no edits, thorough reasoning',
+    permissionMode: 'default',
+    env: {
+      CLAUDE_CODE_EFFORT_LEVEL: 'high',
+      CLAUDE_CODE_THINKING: '1',
+      CLAUDE_CODE_BRIEF: '0',
+    },
+  },
+  ci: {
+    description: 'CI / automation pipelines — fast, non-interactive, no suggestions',
+    permissionMode: 'dontAsk',
+    env: {
+      CLAUDE_CODE_FAST_MODE: '1',
+      CLAUDE_CODE_EFFORT_LEVEL: 'low',
+      CLAUDE_CODE_PROMPT_SUGGESTION: '0',
+    },
+  },
+};
+
+/**
+ * Keyword → profile rules, evaluated in order. The first rule whose regex
+ * matches the prompt wins, so more specific task types are listed first.
+ */
+const DETECTION_RULES = [
+  { type: 'quickfix', re: /\b(typo|quick\s?-?fix|one-?liner|small fix|rename)\b/i },
+  { type: 'ci', re: /\b(ci|cd|pipeline|github actions|workflow|deploy)\b/i },
+  { type: 'swarm', re: /\b(swarm|multi-?agent|coordinate|orchestrat\w*|hive)\b/i },
+  { type: 'background', re: /\b(background|daemon|monitor\w*|watch\b|long-?running)\b/i },
+  { type: 'review', re: /\b(review|pull request|\bpr\b|audit|critique)\b/i },
+  { type: 'planning', re: /\b(plan\w*|architect\w*|design|roadmap|strategy)\b/i },
+  { type: 'research', re: /\b(research|investigat\w*|explore|compare|survey)\b/i },
+  { type: 'coding', re: /\b(implement|code|build|add|write|refactor|create|fix|function|feature)\b/i },
+];
+
+/** List all available profile names. */
+function listProfiles() {
+  return Object.keys(PROFILES);
+}
+
+/** Return a profile by name, or `null` if it does not exist. */
+function getProfile(name) {
+  if (!name || !Object.prototype.hasOwnProperty.call(PROFILES, name)) {
+    return null;
+  }
+  return PROFILES[name];
+}
+
+/**
+ * Apply a profile's env vars to `process.env`. Returns `{ applied, permissionMode }`
+ * where `applied` is the map of env vars that were set, or `null` if the profile
+ * is unknown.
+ */
+function applyProfile(name) {
+  const profile = getProfile(name);
+  if (!profile) {
+    return null;
+  }
+  const applied = {};
+  for (const [key, val] of Object.entries(profile.env)) {
+    process.env[key] = val;
+    applied[key] = val;
+  }
+  return { applied, permissionMode: profile.permissionMode };
+}
+
+/**
+ * Infer the most likely task type from a free-text prompt. Defaults to
+ * `'coding'` for empty/unrecognised input.
+ */
+function detectTaskType(prompt) {
+  if (!prompt || typeof prompt !== 'string') {
+    return 'coding';
+  }
+  for (const rule of DETECTION_RULES) {
+    if (rule.re.test(prompt)) {
+      return rule.type;
+    }
+  }
+  return 'coding';
+}
+
+module.exports = {
+  PERMISSION_MODES,
+  PROFILES,
+  listProfiles,
+  getProfile,
+  applyProfile,
+  detectTaskType,
+};