thumbgate 1.14.1 → 1.16.0

package/scripts/harness-selector.js

@@ -9,20 +9,23 @@
  * Detection priority (first match wins):
  *   1. THUMBGATE_HARNESS env var — explicit override
  *   2. Tool-name heuristic (Edit/Write/MultiEdit → code-edit)
- *   3. Command-text heuristic (deploy keywords → deploy, SQL keywords → db-write)
+ *   3. Command-text heuristic (deploy keywords → deploy, SQL keywords → db-write, routines → routine)
  *   4. null → load only default.json + auto-promoted gates
  *
  * Each harness is ADDITIVE — default.json gates always load first.
  */
 
 const path = require('path');
+const fs = require('fs');
 
 const HARNESS_DIR = path.join(__dirname, '..', 'config', 'gates');
+const ROOT_DIR = path.join(__dirname, '..');
 
 const HARNESSES = Object.freeze({
   deploy: path.join(HARNESS_DIR, 'deploy.json'),
   'code-edit': path.join(HARNESS_DIR, 'code-edit.json'),
   'db-write': path.join(HARNESS_DIR, 'db-write.json'),
+  routine: path.join(HARNESS_DIR, 'routine.json'),
 });
 
 // ---------------------------------------------------------------------------
@@ -48,6 +51,14 @@ const DB_WRITE_PATTERNS = [
   /\.db\.exec\(|\.db\.prepare\(/i,
 ];
 
+const ROUTINE_PATTERNS = [
+  /\b(routine|scheduled agent|workspace agent|webhook trigger|post[-\s]?merge|nightly|daily audit)\b/i,
+  /\b(reasoning_effort|system prompt|developer message|verbosity|length limits)\b/i,
+  /\b(gpt-5\.5|gpt-5\.5-pro|xhigh|ultrathink)\b/i,
+  /\b(slack|salesforce|gmail|google drive|notion|jira|linear|atlassian)\b.*\b(send|post|write|update|delete|create)\b/i,
+  /\b(context|role|expectations|few[-\s]?shot|zero[-\s]?shot|prompt template|prompt library)\b/i,
+];
+
 const CODE_EDIT_TOOL_NAMES = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
 
 // ---------------------------------------------------------------------------
@@ -82,6 +93,9 @@ function selectHarness(toolName, toolInput) {
     if (DB_WRITE_PATTERNS.some((p) => p.test(commandText))) {
       return HARNESSES['db-write'];
     }
+    if (ROUTINE_PATTERNS.some((p) => p.test(commandText))) {
+      return HARNESSES.routine;
+    }
     if (DEPLOY_PATTERNS.some((p) => p.test(commandText))) {
       return HARNESSES['deploy'];
     }
@@ -113,6 +127,132 @@ function getHarnessPath(name) {
   return HARNESSES[name] ?? null;
 }
 
+function estimateTokenCount(text, charsPerToken = 4) {
+  const payload = String(text || '');
+  const divisor = Math.max(1, Number(charsPerToken) || 4);
+  return Math.ceil(Buffer.byteLength(payload, 'utf8') / divisor);
+}
+
+function readIfExists(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function readJsonIfExists(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function collectDefaultHarnessAuditInputs(rootDir = ROOT_DIR) {
+  const globalDocNames = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'];
+  const globalDocs = globalDocNames.map((name) => {
+    const content = readIfExists(path.join(rootDir, name));
+    return {
+      name,
+      chars: Buffer.byteLength(content, 'utf8'),
+      estimatedTokens: estimateTokenCount(content),
+      exists: content.length > 0,
+    };
+  });
+  const toolIndex = readJsonIfExists(path.join(rootDir, '.well-known', 'mcp', 'tools.json'));
+  const tools = Array.isArray(toolIndex && toolIndex.tools) ? toolIndex.tools : [];
+
+  return {
+    globalDocs,
+    mcpToolCount: tools.length,
+    progressiveToolIndexPresent: tools.some((tool) => typeof tool.schemaUrl === 'string'),
+    specializedHarnesses: listHarnesses(),
+  };
+}
+
+function scoreHarnessAudit(inputs = {}, options = {}) {
+  const globalDocs = Array.isArray(inputs.globalDocs) ? inputs.globalDocs : [];
+  const totalDocTokens = globalDocs.reduce((sum, doc) => sum + Number(doc.estimatedTokens || 0), 0);
+  const totalDocChars = globalDocs.reduce((sum, doc) => sum + Number(doc.chars || 0), 0);
+  const docTokenBudget = Number(options.docTokenBudget || 9000);
+  const docsOverBudget = totalDocTokens > docTokenBudget;
+  const mcpToolCount = Number(inputs.mcpToolCount || 0);
+  const progressiveToolIndexPresent = Boolean(inputs.progressiveToolIndexPresent);
+  const specializedHarnesses = Array.isArray(inputs.specializedHarnesses) ? inputs.specializedHarnesses : [];
+  const hasSpecializedHarnesses = specializedHarnesses.length >= 4;
+  const missingDocs = globalDocs.filter((doc) => doc.exists === false).map((doc) => doc.name);
+  const observations = [];
+  const recommendations = [];
+
+  let score = 100;
+  if (docsOverBudget) {
+    const overageRatio = totalDocTokens / docTokenBudget;
+    score -= Math.min(35, Math.ceil((overageRatio - 1) * 22));
+    observations.push(`Global agent docs use about ${totalDocTokens} tokens against a ${docTokenBudget} token harness budget.`);
+    recommendations.push('Move verbose runbooks into skills, guides, or tool help, then leave AGENTS.md/CLAUDE.md as short discovery pointers.');
+  } else {
+    observations.push(`Global agent docs stay within the ${docTokenBudget} token harness budget.`);
+  }
+
+  if (!progressiveToolIndexPresent && mcpToolCount > 12) {
+    score -= 25;
+    observations.push(`${mcpToolCount} MCP tools appear preload-only, which can push agents toward instruction bloat.`);
+    recommendations.push('Expose a lightweight MCP tool index with per-tool schema URLs so agents fetch schemas only when needed.');
+  } else if (progressiveToolIndexPresent) {
+    observations.push('Progressive MCP tool discovery is available through schema URLs.');
+  }
+
+  if (!hasSpecializedHarnesses) {
+    score -= 18;
+    observations.push('Fewer than four specialized gate harnesses are available for risky workflows.');
+    recommendations.push('Add workflow-specific harnesses for deploy, code-edit, database-write, and unattended routine actions so default gates stay lean.');
+  } else {
+    observations.push(`Specialized harnesses are available: ${specializedHarnesses.join(', ')}.`);
+  }
+
+  if (missingDocs.length > 0) {
+    score -= Math.min(12, missingDocs.length * 4);
+    recommendations.push(`Restore missing global discovery docs or remove stale references: ${missingDocs.join(', ')}.`);
+  }
+
+  if (recommendations.length === 0) {
+    recommendations.push('Keep using Research -> Plan -> Implement prompts and delegate only subtasks whose summaries are enough for the main context.');
+  } else {
+    recommendations.push('Use Research -> Plan -> Implement prompts so implementation starts after the harness has isolated only the needed context.');
+  }
+
+  const normalizedScore = Math.max(0, Math.min(100, score));
+  const status = normalizedScore >= 85 ? 'compounding' : normalizedScore >= 65 ? 'watch' : 'bloated';
+
+  return {
+    name: 'thumbgate-harness-optimization-audit',
+    status,
+    score: normalizedScore,
+    roiPriority: normalizedScore < 85 ? 'conversion' : 'retention',
+    totals: {
+      globalDocChars: totalDocChars,
+      globalDocEstimatedTokens: totalDocTokens,
+      mcpToolCount,
+      specializedHarnessCount: specializedHarnesses.length,
+    },
+    signals: {
+      docsOverBudget,
+      progressiveToolIndexPresent,
+      hasSpecializedHarnesses,
+      missingDocs,
+    },
+    observations,
+    recommendations,
+  };
+}
+
+function buildHarnessOptimizationAudit(options = {}) {
+  const rootDir = options.rootDir || ROOT_DIR;
+  const inputs = options.inputs || collectDefaultHarnessAuditInputs(rootDir);
+  return scoreHarnessAudit(inputs, options);
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -140,6 +280,10 @@ module.exports = {
   selectHarnessName,
   listHarnesses,
   getHarnessPath,
+  estimateTokenCount,
+  collectDefaultHarnessAuditInputs,
+  scoreHarnessAudit,
+  buildHarnessOptimizationAudit,
   extractCommandText,
   HARNESSES,
   DEPLOY_PATTERNS,

package/scripts/hybrid-supervisor-agent.js

@@ -0,0 +1,64 @@
+'use strict';
+
+function buildHybridSupervisorPlan(options = {}) {
+  const sources = options.sources || [
+    { id: 'feedback_log', type: 'jsonl', description: 'User thumbs-up/down and correction events.' },
+    { id: 'gate_metrics', type: 'sql', description: 'Gate blocks, warnings, pass rates, and timestamps.' },
+    { id: 'docs', type: 'vector', description: 'Public docs and operational guides.' },
+  ];
+
+  return {
+    pattern: 'multi_step_hybrid_supervisor',
+    sources,
+    sourceCount: sources.length,
+    steps: [
+      'classify query into structured, unstructured, graph, or mixed',
+      'decompose mixed queries into native-source subqueries',
+      'run complementary SQL, graph, and vector searches in parallel',
+      'join or reconcile result sets',
+      'self-correct with a different query path when overlap is empty',
+      'verify final answer against source-specific evidence',
+    ],
+    gates: [
+      'prefer native source queries over flattening everything into embeddings',
+      'limit initial deployments to 5-10 curated complementary sources',
+      'require plain-language source descriptions at ingestion',
+      'block final answers when structured and unstructured evidence conflict',
+    ],
+  };
+}
+
+function classifyHybridQuery(query = '') {
+  const text = String(query).toLowerCase();
+  const needsStructured = /\b(count|sum|trend|declin|increase|revenue|sales|rate|over time|sql|table)\b/.test(text);
+  const needsUnstructured = /\b(reviews?|feedback|reason|complaints?|docs?|semantic|why|quote|citation)\b/.test(text);
+  const needsGraph = /\b(similar|related|path|relationship|because|profile|like you)\b/.test(text);
+  if ([needsStructured, needsUnstructured, needsGraph].filter(Boolean).length >= 2) return 'hybrid';
+  if (needsStructured) return 'structured';
+  if (needsGraph) return 'graph';
+  if (needsUnstructured) return 'unstructured';
+  return 'general';
+}
+
+function evaluateHybridSupervisorRun(run = {}) {
+  const issues = [];
+  const queryType = classifyHybridQuery(run.query || '');
+  if (queryType === 'hybrid' && !run.decomposed) issues.push('hybrid_query_not_decomposed');
+  if (queryType === 'hybrid' && !run.parallelNativeQueries) issues.push('parallel_native_queries_required');
+  if (!run.sourceDescriptionsPresent) issues.push('missing_source_descriptions');
+  if ((run.sourceCount || 0) > 10 && !run.incrementalRollout) issues.push('too_many_sources_without_incremental_rollout');
+  if (run.emptyOverlap && !run.selfCorrected) issues.push('self_correction_required');
+  if (run.evidenceConflict && !run.escalated) issues.push('conflicting_evidence_requires_escalation');
+
+  return {
+    decision: issues.length ? 'warn' : 'allow',
+    issues,
+    queryType,
+  };
+}
+
+module.exports = {
+  buildHybridSupervisorPlan,
+  classifyHybridQuery,
+  evaluateHybridSupervisorRun,
+};

package/scripts/inference-cache-policy.js

@@ -0,0 +1,72 @@
+'use strict';
+
+function buildInferenceCachePolicy(options = {}) {
+  return {
+    policyId: 'llm_inference_cache',
+    layers: [
+      {
+        id: 'kv_cache',
+        owner: 'model_runtime',
+        enabled: true,
+        action: 'no app changes; rely on inference runtime',
+      },
+      {
+        id: 'prefix_cache',
+        owner: 'agent_harness',
+        enabled: options.prefixCache !== false,
+        action: 'place stable system prompt, docs, and examples before dynamic fields',
+      },
+      {
+        id: 'semantic_cache',
+        owner: 'application',
+        enabled: Boolean(options.semanticCache),
+        action: 'cache complete input/output pairs when paraphrased repeat volume is high',
+      },
+    ],
+    promptRules: [
+      'static content first',
+      'dynamic user/session/date fields last',
+      'deterministic JSON key order',
+      'no generated timestamps inside cached prefix',
+      'version cache keys with prompt and policy versions',
+    ],
+    invalidation: {
+      prefix: ['system_prompt_version', 'doc_version', 'tool_policy_version'],
+      semantic: ['answer_ttl', 'source_doc_version', 'safety_policy_version'],
+    },
+  };
+}
+
+function evaluateCacheCandidate(candidate = {}) {
+  const issues = [];
+  const repeatedPrefixTokens = Number(candidate.repeatedPrefixTokens || 0);
+  const requestsPerDay = Number(candidate.requestsPerDay || 0);
+  const semanticRepeatRate = Number(candidate.semanticRepeatRate || 0);
+
+  if (candidate.dynamicFieldsBeforeStatic) issues.push('dynamic_fields_break_prefix_cache');
+  if (!candidate.deterministicSerialization) issues.push('deterministic_serialization_required');
+  if (repeatedPrefixTokens >= 1024 && requestsPerDay >= 10 && !candidate.prefixCacheEnabled) {
+    issues.push('prefix_cache_high_roi_not_enabled');
+  }
+  if (candidate.semanticCacheEnabled && semanticRepeatRate < 0.15) {
+    issues.push('semantic_cache_overhead_not_justified');
+  }
+  if (candidate.semanticCacheEnabled && !candidate.ttl) {
+    issues.push('semantic_cache_ttl_required');
+  }
+
+  return {
+    decision: issues.length ? 'warn' : 'allow',
+    issues,
+    recommendedLayers: [
+      'kv_cache',
+      repeatedPrefixTokens >= 1024 && requestsPerDay >= 10 ? 'prefix_cache' : null,
+      semanticRepeatRate >= 0.15 ? 'semantic_cache' : null,
+    ].filter(Boolean),
+  };
+}
+
+module.exports = {
+  buildInferenceCachePolicy,
+  evaluateCacheCandidate,
+};

package/scripts/inference-economics.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+'use strict';
+
+function estimateDifficulty(input = {}) {
+  let score = 0;
+  const text = String(input.task || input.prompt || '');
+  if (text.length > 1200) score += 20;
+  if (/ambiguous|research|architecture|security|production|migration|legal|financial/i.test(text)) score += 25;
+  if (Number(input.dollarImpact || 0) >= 1000) score += 25;
+  if (Array.isArray(input.files) && input.files.length > 5) score += 15;
+  if (input.requiresHumanApproval === true) score += 15;
+  return Math.max(0, Math.min(100, score));
+}
+
+function planInferenceBudget(input = {}) {
+  const difficulty = Number.isFinite(input.difficulty) ? input.difficulty : estimateDifficulty(input);
+  const maxCostCents = Number.isFinite(Number(input.maxCostCents)) ? Number(input.maxCostCents) : 50;
+  let depth = 'shallow';
+  let reasoningEffort = 'low';
+  let expertCount = 1;
+  let humanHandoff = false;
+
+  if (difficulty >= 70) {
+    depth = 'deep';
+    reasoningEffort = 'high';
+    expertCount = 4;
+    humanHandoff = true;
+  } else if (difficulty >= 35) {
+    depth = 'standard';
+    reasoningEffort = 'medium';
+    expertCount = 2;
+  }
+
+  if (maxCostCents < 20 && depth === 'deep') {
+    depth = 'standard';
+    reasoningEffort = 'medium';
+  }
+
+  return {
+    difficulty,
+    maxCostCents,
+    depth,
+    reasoningEffort,
+    activeExperts: expertCount,
+    humanHandoff,
+    telemetry: ['difficulty', 'depth', 'reasoningEffort', 'activeExperts', 'latencyMs', 'costCents', 'outcome'],
+  };
+}
+
+module.exports = {
+  estimateDifficulty,
+  planInferenceBudget,
+};

package/scripts/internal-agent-bootstrap.js

@@ -12,13 +12,18 @@ const {
   constructContextPack,
   recordProvenance,
 } = require('./contextfs');
-const { planIntent } = require('./intent-router');
 const { formatCodeGraphRecallSection } = require('./codegraph-context');
 
 const KNOWN_SOURCES = new Set(['github', 'slack', 'linear', 'api', 'cli']);
 const DEFAULT_SOURCE = 'api';
 const DEFAULT_SANDBOX_ROOT = path.join(os.tmpdir(), 'thumbgate-internal-agent-sandboxes');
 
+function loadIntentRouterModule() {
+  const modulePath = path.resolve(__dirname, 'intent-router.js');
+  if (!fs.existsSync(modulePath)) return null;
+  return require(modulePath);
+}
+
 function normalizeText(value) {
   if (value === undefined || value === null) return '';
   return String(value).trim();
@@ -422,7 +427,12 @@ function bootstrapInternalAgent(options = {}) {
       baseRef: null,
     };
 
-  const plan = planIntent({
+  const intentRouter = loadIntentRouterModule();
+  if (!intentRouter) {
+    throw new Error('Internal agent bootstrap requires the ThumbGate private intent router runtime.');
+  }
+
+  const plan = intentRouter.planIntent({
     intentId: invocation.intentId,
     context: startupContext.text,
     mcpProfile: invocation.mcpProfile,

package/scripts/knowledge-layer-plan.js

@@ -0,0 +1,108 @@
+'use strict';
+
+function buildKnowledgeLayerPlan(options = {}) {
+  const domain = options.domain || 'agent_reliability';
+  const graph = options.graph || 'neo4j';
+
+  return {
+    domain,
+    graph,
+    memoryTiers: [
+      {
+        id: 'short_term',
+        purpose: 'Current session context so the agent does not re-ask answered questions.',
+        ttl: 'session',
+      },
+      {
+        id: 'long_term',
+        purpose: 'Durable user, product, workflow, and feedback profile facts.',
+        ttl: 'durable',
+      },
+      {
+        id: 'reasoning_memory',
+        purpose: 'Reusable decision paths that avoid recomputing expensive traversals.',
+        ttl: 'versioned',
+      },
+    ],
+    nodeTypes: [
+      'User',
+      'Agent',
+      'Workflow',
+      'Feedback',
+      'Gate',
+      'Decision',
+      'Evidence',
+      'Recommendation',
+      'Outcome',
+    ],
+    relationshipTypes: [
+      'GAVE_FEEDBACK',
+      'TRIGGERED_GATE',
+      'USED_EVIDENCE',
+      'RECOMMENDED_ACTION',
+      'PRODUCED_OUTCOME',
+      'SIMILAR_TO',
+      'REUSES_REASONING',
+    ],
+    highRoiUseCases: [
+      'conversion recommendations with explainable evidence paths',
+      'compute savings from reasoning-memory cache hits',
+      'compliance audit trail for why an agent recommended or blocked an action',
+      'closed-loop profile updates from every feedback, purchase, or outcome event',
+    ],
+    gates: [
+      'do not recommend without an evidence path',
+      'do not reuse reasoning memory when source facts changed',
+      'write audit node for every recommendation and blocked action',
+      'record outcome feedback to update profile and graph edges',
+    ],
+  };
+}
+
+function buildRecommendationEvidencePath(input = {}) {
+  const userId = input.userId || 'unknown_user';
+  const recommendationId = input.recommendationId || 'rec_pending';
+  const evidence = Array.isArray(input.evidence) ? input.evidence : [];
+  const similarProfiles = Array.isArray(input.similarProfiles) ? input.similarProfiles : [];
+
+  return {
+    recommendationId,
+    path: [
+      { type: 'User', id: userId },
+      ...similarProfiles.map((id) => ({ type: 'SimilarProfile', id })),
+      ...evidence.map((item, index) => ({
+        type: item.type || 'Evidence',
+        id: item.id || `evidence_${index + 1}`,
+        quote: item.quote || null,
+      })),
+      { type: 'Recommendation', id: recommendationId },
+    ],
+    explainable: evidence.length > 0,
+  };
+}
+
+function evaluateKnowledgeLayerRun(run = {}) {
+  const issues = [];
+  if (!run.userId) issues.push('missing_user_id');
+  if (!run.recommendationId) issues.push('missing_recommendation_id');
+  if (!run.evidencePath?.explainable) issues.push('missing_explainable_evidence_path');
+  if (!run.auditNodeId) issues.push('missing_audit_node_id');
+  if (run.reusedReasoning && !run.reasoningVersion) issues.push('missing_reasoning_version');
+  if (run.profileUpdate && !run.outcomeEventId) issues.push('missing_outcome_event_id');
+
+  return {
+    decision: issues.length ? 'warn' : 'allow',
+    issues,
+    roiSignals: [
+      run.reusedReasoning ? 'lower_graph_query_and_token_cost' : null,
+      run.profileUpdate ? 'closed_loop_personalization' : null,
+      run.auditNodeId ? 'compliance_trace_available' : null,
+    ].filter(Boolean),
+  };
+}
+
+module.exports = {
+  buildKnowledgeLayerPlan,
+  buildRecommendationEvidencePath,
+  evaluateKnowledgeLayerRun,
+};