thumbgate 1.8.0 → 1.10.1

package/scripts/multimodal-retrieval-plan.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const DEFAULT_EVIDENCE_TYPES = ['screenshots', 'pdf_pages', 'proof_artifacts'];
+const DEFAULT_DIMS = [1024, 512, 256, 128, 64];
+
+function clampInteger(value, { min, max, fallback }) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(parsed)));
+}
+
+function normalizeEvidenceTypes(value) {
+  if (!Array.isArray(value)) return DEFAULT_EVIDENCE_TYPES;
+  const normalized = value
+    .map((item) => String(item || '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '_'))
+    .filter(Boolean);
+  return normalized.length > 0 ? [...new Set(normalized)] : DEFAULT_EVIDENCE_TYPES;
+}
+
+function dimensionPlan({ corpusItems, maxEmbeddingDim }) {
+  const dims = DEFAULT_DIMS.filter((dim) => dim <= maxEmbeddingDim);
+  const selected = dims.length > 0 ? dims : [maxEmbeddingDim];
+  return selected.map((dim) => ({
+    dim,
+    estimatedFloat32Mb: Number(((corpusItems * dim * 4) / (1024 * 1024)).toFixed(2)),
+    useWhen: dim >= 1024
+      ? 'default quality pass for launch-critical retrieval'
+      : 'cost-down pass when storage or latency dominates',
+  }));
+}
+
+function buildMultimodalRetrievalPlan(args = {}) {
+  const evidenceTypes = normalizeEvidenceTypes(args.evidenceTypes);
+  const corpusItems = clampInteger(args.corpusItems, {
+    min: 100,
+    max: 10000000,
+    fallback: 5000,
+  });
+  const maxEmbeddingDim = clampInteger(args.maxEmbeddingDim, {
+    min: 64,
+    max: 2048,
+    fallback: 1024,
+  });
+  const latencyBudgetMs = clampInteger(args.latencyBudgetMs, {
+    min: 50,
+    max: 30000,
+    fallback: 750,
+  });
+  const useReranker = args.useReranker !== false;
+  const goal = String(args.goal || 'retrieve visual proof for agent-governance decisions').trim();
+  const dims = dimensionPlan({ corpusItems, maxEmbeddingDim });
+  const defaultDim = dims.some((entry) => entry.dim === 1024) ? 1024 : dims[0].dim;
+
+  return {
+    planVersion: '2026-04-20',
+    sourcePattern: 'multimodal Sentence Transformers visual document retrieval',
+    goal,
+    evidenceTypes,
+    architecture: {
+      stage1: 'Index screenshots, PDF pages, dashboard captures, and proof artifacts with a multimodal embedding model.',
+      stage2: useReranker
+        ? 'Rerank the top candidates with a multimodal cross-encoder before using evidence in a gate, PR, or sales proof claim.'
+        : 'Skip reranking for low-latency agent recall; require stronger holdout evaluation before shipping.',
+      fallback: 'Keep text-only search as a fallback for code, logs, markdown, and plain policy docs.',
+    },
+    trainingData: {
+      pilotSchema: ['query', 'image', 'negative_0'],
+      hardNegativeStrategy: 'Pair each proof query with visually similar but wrong screenshots or PDF pages.',
+      minimumPilot: 'Start with 300 labeled evaluation queries and at least one hard negative per query before finetuning.',
+    },
+    evaluation: {
+      baseline: 'Measure current text-only retrieval before any model changes.',
+      primaryMetric: 'NDCG@10',
+      secondaryMetrics: ['Recall@5', 'MAP', 'false_positive_gate_rate'],
+      holdoutSets: [
+        'agent failure screenshots',
+        'dashboard proof captures',
+        'visual docs that contain tables or charts',
+      ],
+    },
+    deployment: {
+      latencyBudgetMs,
+      defaultEmbeddingDim: defaultDim,
+      matryoshkaDimensions: dims,
+      compressionPath: 'Use Matryoshka truncation first, then quantization only after holdout quality is stable.',
+    },
+    thumbgateUseCases: [
+      'Find the exact screenshot or proof artifact behind a completion claim.',
+      'Retrieve visual evidence before approving a workflow-hardening sprint.',
+      'Rank dashboard captures and PDF runbook pages for GEO/SEO evidence pages.',
+      'Attach visual hard negatives to Autoresearch loops so agents cannot reward-hack by deleting hard cases.',
+    ],
+    guardrails: [
+      'Never promote visual retrieval results into claims without a linked artifact URL or local path.',
+      'Keep the multimodal index read-only for agent recall; gate training and index rebuilds behind explicit workflow checks.',
+      'Evaluate retrieval on holdout screenshots/PDF pages before replacing text-only recall.',
+    ],
+    nextActions: [
+      'Create a small visual proof corpus from existing public dashboard screenshots and proof artifacts.',
+      'Log query -> correct artifact -> hard negative triples during workflow sprint reviews.',
+      'Use Autoresearch to optimize NDCG@10 and latency only after the baseline corpus exists.',
+    ],
+  };
+}
+
+module.exports = {
+  buildMultimodalRetrievalPlan,
+  dimensionPlan,
+  normalizeEvidenceTypes,
+};

package/scripts/thompson-sampling.js

@@ -324,6 +324,48 @@ function samplePosteriors(model) {
   return samples;
 }
 
+/**
+ * Production/exploit-mode counterpart to `samplePosteriors`. Instead of
+ * drawing a random sample from each Beta posterior (which deliberately
+ * explores), return the posterior *mean* α/(α+β) for each category. Picking
+ * argmax over these means is the Bayes-optimal action under 0-1 loss when
+ * we only care about expected reward and do not need exploration.
+ *
+ * When to use which:
+ *   - `samplePosteriors` in training / learning mode — we want to try
+ *     under-sampled arms.
+ *   - `argmaxPosteriors` in production / hot-path mode — we want the
+ *     best-known lesson right now. The caller can still choose to mix the
+ *     two (e.g. ε-greedy) but that's out of scope here.
+ */
+function argmaxPosteriors(model) {
+  const means = {};
+  for (const [cat, params] of Object.entries(model.categories || {})) {
+    const alpha = Math.max(Number(params.alpha) || 0, 0.01);
+    const beta = Math.max(Number(params.beta) || 0, 0.01);
+    means[cat] = alpha / (alpha + beta);
+  }
+  return means;
+}
+
+/**
+ * Pick the single category with the highest posterior mean. Ties broken by
+ * lexicographic order for determinism. Returns `null` when no categories
+ * are present.
+ */
+function pickBestCategory(model) {
+  const means = argmaxPosteriors(model);
+  const keys = Object.keys(means);
+  if (keys.length === 0) return null;
+  // Use localeCompare for deterministic, locale-aware alphabetical tie-break.
+  keys.sort((a, b) => a.localeCompare(b));
+  let best = keys[0];
+  for (const key of keys) {
+    if (means[key] > means[best]) best = key;
+  }
+  return best;
+}
+
 // ---------------------------------------------------------------------------
 // Internal: Marsaglia-Tsang Gamma Sampling (2000)
 // ---------------------------------------------------------------------------
@@ -410,6 +452,8 @@ module.exports = {
   isCalibrated,
   getCalibration,
   samplePosteriors,
+  argmaxPosteriors,
+  pickBestCategory,
   HALF_LIFE_DAYS,
   DECAY_FLOOR,
   MIN_SAMPLES_THRESHOLD,

package/scripts/tool-registry.js

@@ -134,6 +134,25 @@ const TOOLS = [
       },
     },
   }),
+  readOnlyTool({
+    name: 'plan_multimodal_retrieval',
+    description: 'Plan a high-ROI multimodal retrieval rollout for screenshots, PDF pages, dashboard captures, and proof artifacts without starting GPU training.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        goal: { type: 'string', description: 'Business or workflow objective for visual/document retrieval.' },
+        evidenceTypes: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Evidence surfaces to include, such as screenshots, pdf_pages, proof_artifacts, dashboards, or videos.',
+        },
+        corpusItems: { type: 'number', description: 'Estimated number of visual artifacts or document pages to index.' },
+        maxEmbeddingDim: { type: 'number', description: 'Maximum embedding dimension to budget for Matryoshka-style truncation planning.' },
+        latencyBudgetMs: { type: 'number', description: 'Target retrieval latency budget for agent recall.' },
+        useReranker: { type: 'boolean', description: 'Whether to include a multimodal reranker stage after initial embedding retrieval.' },
+      },
+    },
+  }),
   destructiveTool({
     name: 'import_document',
     description: 'Import a local policy or runbook document into ThumbGate, normalize it for search, and propose provenance-backed gate candidates.',
@@ -872,6 +891,24 @@ const TOOLS = [
       },
     },
   }),
+  destructiveTool({
+    name: 'run_autoresearch',
+    description: 'Run a bounded metric-improvement loop: measure a baseline, test a hypothesis, require primary and holdout checks, then keep or discard the candidate mutation with proof.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        iterations: { type: 'number', description: 'Number of iterations to run. Capped at 5 per call; default 1.' },
+        targetName: { type: 'string', enum: ['half_life_days', 'decay_floor', 'prevention_min_occurrences', 'verification_max_retries', 'dpo_beta'], description: 'Optional evolution target to mutate.' },
+        nextValue: { type: 'number', description: 'Optional explicit candidate value for the target.' },
+        testCommand: { type: 'string', description: 'Primary metric command. Defaults to npm test.' },
+        holdoutCommands: { type: 'array', items: { type: 'string' }, description: 'Additional checks required before a candidate can be kept.' },
+        timeoutMs: { type: 'number', description: 'Per-command timeout in milliseconds. Capped at 600000; default 120000.' },
+        cwd: { type: 'string', description: 'Optional workspace directory for the evaluation commands.' },
+        researchQuery: { type: 'string', description: 'Optional research query used to build an autoresearch context brief.' },
+        paperLimit: { type: 'number', description: 'Maximum research papers to ingest when researchQuery is set. Capped at 10; default 5.' },
+      },
+    },
+  }),
   destructiveTool({
     name: 'schedule',
     description: 'Create, list, or delete scheduled tasks. Supports natural language scheduling like "daily 9:00", "weekly monday 8:30", "hourly". Installs as macOS LaunchAgent or Linux crontab.',

package/src/api/server.js

@@ -552,6 +552,169 @@ function getServerCardTools() {
   }));
 }
 
+function buildPublicUrl(hostedConfig, pathname) {
+  return `${hostedConfig.appOrigin}${pathname}`;
+}
+
+const VERIFICATION_EVIDENCE_URL = 'https://github.com/IgorGanapolsky/ThumbGate/blob/main/docs/VERIFICATION_EVIDENCE.md';
+
+function getToolDiscoveryIndex(hostedConfig) {
+  return MCP_TOOLS.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    annotations: tool.annotations || {},
+    schemaUrl: buildPublicUrl(hostedConfig, `/.well-known/mcp/tools/${encodeURIComponent(tool.name)}.json`),
+  }));
+}
+
+function getMcpSkillManifests(hostedConfig) {
+  return [
+    {
+      name: 'thumbgate',
+      title: 'ThumbGate Pre-Action Gates',
+      description: 'Capture feedback, recall lessons, generate rules, and block repeated agent mistakes before tool execution.',
+      triggers: ['thumbgate', 'pre-action gates', 'prevent repeated AI mistakes', 'agent feedback', 'PreToolUse hooks'],
+      recommendedFlow: [
+        'Recall lessons before risky work.',
+        'Plan high-risk actions with checkpoints.',
+        'Capture concrete thumbs-down/up feedback.',
+        'Inspect prevention_rules after repeats.',
+      ],
+      installCommand: 'npx thumbgate init',
+      contextUrl: buildPublicUrl(hostedConfig, '/public/llm-context.md'),
+      proofUrl: VERIFICATION_EVIDENCE_URL,
+    },
+    {
+      name: 'workflow-hardening-sprint',
+      title: 'Workflow Hardening Sprint',
+      description: 'Turn one repeated agent failure into an enforced gate with proof and rollout evidence.',
+      triggers: ['workflow hardening', 'team rollout', 'agent governance', 'approval boundary', 'audit trail'],
+      recommendedFlow: [
+        'Pick one costly repeated failure.',
+        'Import the policy or runbook.',
+        'Ship the gate with dashboard proof.',
+      ],
+      intakeUrl: buildPublicUrl(hostedConfig, '/#workflow-sprint-intake'),
+      proofUrl: VERIFICATION_EVIDENCE_URL,
+    },
+    {
+      name: 'visual-proof-retrieval',
+      title: 'Visual Proof Retrieval',
+      description: 'Use screenshots, PDF pages, dashboard captures, and proof artifacts as searchable evidence for agent-governance claims.',
+      triggers: ['visual document retrieval', 'multimodal embeddings', 'screenshots', 'PDF evidence', 'proof artifacts'],
+      recommendedFlow: [
+        'Plan the corpus and Matryoshka dimension budget.',
+        'Baseline text-only retrieval before finetuning.',
+        'Evaluate NDCG@10 on visual hard negatives.',
+        'Require artifact links before using retrieved evidence in claims.',
+      ],
+      contextUrl: buildPublicUrl(hostedConfig, '/public/llm-context.md'),
+      proofUrl: VERIFICATION_EVIDENCE_URL,
+    },
+  ];
+}
+
+function getMcpApplications(hostedConfig) {
+  return [
+    {
+      name: 'dashboard',
+      title: 'ThumbGate Dashboard',
+      description: 'Review feedback, gates, blocked actions, funnel metrics, and proof.',
+      url: buildPublicUrl(hostedConfig, '/dashboard'),
+      useWhen: 'Need proof before approving more autonomy.',
+    },
+    {
+      name: 'lessons',
+      title: 'Lessons',
+      description: 'Browse promoted lessons and corrective actions.',
+      url: buildPublicUrl(hostedConfig, '/lessons'),
+      useWhen: 'Need human-approved context before risk.',
+    },
+    {
+      name: 'guide',
+      title: 'Setup Guide',
+      description: 'Install ThumbGate for Claude Code, Cursor, Codex, Gemini CLI, Amp, OpenCode, and MCP agents.',
+      url: buildPublicUrl(hostedConfig, '/guide'),
+      useWhen: 'Need setup without searching the repo.',
+    },
+    {
+      name: 'workflow-sprint-intake',
+      title: 'Workflow Hardening Sprint Intake',
+      description: 'Submit a repeated agent failure for a proof-backed sprint.',
+      url: buildPublicUrl(hostedConfig, '/#workflow-sprint-intake'),
+      useWhen: 'Ready to convert mistakes into gates.',
+    },
+  ];
+}
+
+function getMcpDiscoveryManifest(hostedConfig) {
+  return {
+    schemaVersion: '2026-04-20',
+    name: 'thumbgate',
+    title: 'ThumbGate',
+    version: pkg.version,
+    description: 'Pre-Action Gates for AI coding agents: feedback, recall, prevention rules, and tool-call blocking.',
+    homepage: hostedConfig.appOrigin,
+    repository: 'https://github.com/IgorGanapolsky/ThumbGate',
+    package: {
+      registry: 'npm',
+      name: 'thumbgate',
+      installCommand: 'npx thumbgate init',
+    },
+    transport: {
+      type: 'streamable-http',
+      endpoint: buildPublicUrl(hostedConfig, '/mcp'),
+      unauthenticatedDiscovery: ['initialize', 'tools/list'],
+      authenticatedMethods: ['tools/call'],
+    },
+    discovery: {
+      serverCardUrl: buildPublicUrl(hostedConfig, '/.well-known/mcp/server-card.json'),
+      toolIndexUrl: buildPublicUrl(hostedConfig, '/.well-known/mcp/tools.json'),
+      toolSchemaUrlTemplate: buildPublicUrl(hostedConfig, '/.well-known/mcp/tools/{name}.json'),
+      skillsUrl: buildPublicUrl(hostedConfig, '/.well-known/mcp/skills.json'),
+      applicationsUrl: buildPublicUrl(hostedConfig, '/.well-known/mcp/applications.json'),
+      llmsTxtUrl: buildPublicUrl(hostedConfig, '/.well-known/llms.txt'),
+      progressive: {
+        pattern: 'Load manifest, inspect tools.json, fetch one tool schema only when needed.',
+        tokenStrategy: 'Do not preload every inputSchema. Use per-tool schema URLs.',
+      },
+    },
+    primaryFlows: [
+      {
+        name: 'capture-to-gate',
+        description: 'Capture feedback, retrieve lessons, generate rules, enforce a gate.',
+        tools: ['capture_feedback', 'search_lessons', 'prevention_rules', 'gate_stats'],
+      },
+      {
+        name: 'safe-autonomous-work',
+        description: 'Plan high-risk work, recall lessons, diagnose failures.',
+        tools: ['plan_intent', 'recall', 'diagnose_failure', 'feedback_summary'],
+      },
+      {
+        name: 'team-rollout-proof',
+        description: 'Show dashboard evidence, metrics, and sprint proof.',
+        tools: ['dashboard', 'get_business_metrics', 'construct_context_pack'],
+      },
+      {
+        name: 'metric-autoresearch',
+        description: 'Run bounded baseline -> hypothesis -> holdout loops with keep/discard proof.',
+        tools: ['get_business_metrics', 'construct_context_pack', 'run_autoresearch', 'require_evidence_for_claim'],
+      },
+      {
+        name: 'visual-proof-retrieval',
+        description: 'Plan screenshot/PDF/proof-artifact retrieval before investing in multimodal finetuning.',
+        tools: ['plan_multimodal_retrieval', 'search_thumbgate', 'construct_context_pack', 'require_evidence_for_claim'],
+      },
+    ],
+    skills: getMcpSkillManifests(hostedConfig),
+    applications: getMcpApplications(hostedConfig),
+    proof: {
+      verificationEvidenceUrl: VERIFICATION_EVIDENCE_URL,
+      llmContextUrl: buildPublicUrl(hostedConfig, '/public/llm-context.md'),
+    },
+  };
+}
+
 function createHttpError(statusCode, message) {
   const err = new Error(message);
   err.statusCode = statusCode;
@@ -3904,7 +4067,85 @@ async function addContext(){
       return;
     }
 
+    if (isGetLikeRequest && pathname === '/.well-known/mcp.json') {
+      sendJson(res, 200, getMcpDiscoveryManifest(hostedConfig), {}, {
+        headOnly: isHeadRequest,
+      });
+      return;
+    }
+
+    if (isGetLikeRequest && pathname === '/.well-known/mcp/tools.json') {
+      sendJson(res, 200, {
+        name: 'thumbgate',
+        version: pkg.version,
+        count: MCP_TOOLS.length,
+        tools: getToolDiscoveryIndex(hostedConfig),
+      }, {}, {
+        headOnly: isHeadRequest,
+      });
+      return;
+    }
+
+    if (isGetLikeRequest && pathname.startsWith('/.well-known/mcp/tools/') && pathname.endsWith('.json')) {
+      const encodedToolName = pathname.slice('/.well-known/mcp/tools/'.length, -'.json'.length);
+      let toolName = encodedToolName;
+      try {
+        toolName = decodeURIComponent(encodedToolName);
+      } catch (_err) {
+        sendJson(res, 400, {
+          error: 'invalid_tool_name',
+          toolIndexUrl: buildPublicUrl(hostedConfig, '/.well-known/mcp/tools.json'),
+        }, {}, {
+          headOnly: isHeadRequest,
+        });
+        return;
+      }
+      const tool = MCP_TOOLS.find((candidate) => candidate.name === toolName);
+      if (!tool) {
+        sendJson(res, 404, {
+          error: 'tool_not_found',
+          toolName,
+          toolIndexUrl: buildPublicUrl(hostedConfig, '/.well-known/mcp/tools.json'),
+        }, {}, {
+          headOnly: isHeadRequest,
+        });
+        return;
+      }
+      sendJson(res, 200, {
+        name: tool.name,
+        description: tool.description,
+        annotations: tool.annotations || {},
+        inputSchema: tool.inputSchema,
+      }, {}, {
+        headOnly: isHeadRequest,
+      });
+      return;
+    }
+
+    if (isGetLikeRequest && pathname === '/.well-known/mcp/skills.json') {
+      sendJson(res, 200, {
+        name: 'thumbgate',
+        version: pkg.version,
+        skills: getMcpSkillManifests(hostedConfig),
+      }, {}, {
+        headOnly: isHeadRequest,
+      });
+      return;
+    }
+
+    if (isGetLikeRequest && pathname === '/.well-known/mcp/applications.json') {
+      sendJson(res, 200, {
+        name: 'thumbgate',
+        version: pkg.version,
+        applications: getMcpApplications(hostedConfig),
+      }, {}, {
+        headOnly: isHeadRequest,
+      });
+      return;
+    }
+
     if (isGetLikeRequest && pathname === '/.well-known/mcp/server-card.json') {
+      const discoveryManifest = getMcpDiscoveryManifest(hostedConfig);
       sendJson(res, 200, {
         serverInfo: {
           name: 'thumbgate',
@@ -3913,7 +4154,12 @@ async function addContext(){
         name: 'thumbgate',
         description: 'Pre-action gates that physically block AI coding agents from repeating known mistakes. Captures feedback, auto-promotes failures into prevention rules, and enforces them via PreToolUse hooks. Works with Claude Code, Codex, Gemini, Amp, Cursor, OpenCode, and any MCP-compatible agent.',
         version: pkg.version,
+        transport: discoveryManifest.transport,
+        discovery: discoveryManifest.discovery,
         tools: getServerCardTools(),
+        skills: getMcpSkillManifests(hostedConfig),
+        applications: getMcpApplications(hostedConfig),
+        proof: discoveryManifest.proof,
         repository: 'https://github.com/IgorGanapolsky/ThumbGate',
         homepage: hostedConfig.appOrigin,
       }, {}, {