thumbgate 1.16.13 → 1.16.19

package/scripts/long-running-agent-context-guardrails.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+'use strict';
+
+const { listGateTemplates } = require('./gate-templates');
+
+const CATEGORY = 'Long-Running Agent Context';
+
+function normalizeBoolean(value) {
+  if (value === true) return true;
+  if (value === false || value === undefined || value === null) return false;
+  return /^(1|true|yes|on)$/i.test(String(value).trim());
+}
+
+function toNumber(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const num = Number(value);
+  return Number.isFinite(num) ? num : null;
+}
+
+function normalizeOptions(options = {}) {
+  return {
+    workflow: String(options.workflow || options.name || 'long-running-agent').trim() || 'long-running-agent',
+    requestCount: toNumber(options['request-count'] || options.requests),
+    outputMb: toNumber(options['output-mb'] || options['output-megabytes']),
+    directorJournal: normalizeBoolean(options['director-journal'] || options.journal),
+    criticReview: normalizeBoolean(options['critic-review'] || options.critic),
+    criticTimeline: normalizeBoolean(options['critic-timeline'] || options.timeline),
+    credibilityScores: normalizeBoolean(options['credibility-scores'] || options.credibility),
+    conflicts: normalizeBoolean(options.conflicts || options['conflict-resolution']),
+    rawChatOnly: normalizeBoolean(options['raw-chat-only'] || options['chat-log-only']),
+  };
+}
+
+function templateApplicability(template, options) {
+  if (template.id === 'require-director-journal-for-long-running-agent') {
+    return options.rawChatOnly ||
+      !options.directorJournal ||
+      (options.requestCount !== null && options.requestCount >= 25) ||
+      (options.outputMb !== null && options.outputMb >= 1);
+  }
+  if (template.id === 'require-critic-review-for-agent-findings') {
+    return !options.criticReview || !options.credibilityScores;
+  }
+  if (template.id === 'checkpoint-critic-timeline-conflict-resolution') {
+    return options.conflicts || !options.criticTimeline;
+  }
+  return false;
+}
+
+function buildSignals(options) {
+  return [
+    contextWindowSignal(options),
+    truthFilterSignal(options),
+    timelineConflictSignal(options),
+  ].filter(Boolean);
+}
+
+function contextWindowSignal(options) {
+  const bloated = options.rawChatOnly ||
+    (options.requestCount !== null && options.requestCount >= 25) ||
+    (options.outputMb !== null && options.outputMb >= 1);
+  if (!bloated) return null;
+  return {
+    id: 'context_window_bloat',
+    label: 'Context-window bloat risk',
+    values: [
+      options.rawChatOnly ? 'raw chat history only' : null,
+      options.requestCount !== null ? `${options.requestCount} requests` : null,
+      options.outputMb !== null ? `${options.outputMb}MB output` : null,
+    ].filter(Boolean),
+    risk: 'raw message accumulation degrades coherence and wastes context budget',
+  };
+}
+
+function truthFilterSignal(options) {
+  if (options.directorJournal && options.criticReview && options.credibilityScores) return null;
+  return {
+    id: 'missing_truth_filter',
+    label: 'Missing structured truth filter',
+    values: [
+      options.directorJournal ? null : 'no director journal',
+      options.criticReview ? null : 'no critic review',
+      options.credibilityScores ? null : 'no credibility scores',
+    ].filter(Boolean),
+    risk: 'agent summaries can become shared truth without evidence inspection',
+  };
+}
+
+function timelineConflictSignal(options) {
+  if (!options.conflicts && options.criticTimeline) return null;
+  return {
+    id: 'timeline_conflict',
+    label: 'Timeline conflict risk',
+    values: [
+      options.conflicts ? 'known conflicts' : null,
+      options.criticTimeline ? null : 'no critic timeline',
+    ].filter(Boolean),
+    risk: 'long-lived memory can retain duplicates, stale claims, or contradictory findings',
+  };
+}
+
+function buildLongRunningAgentContextGuardrailsPlan(rawOptions = {}, templatesPath) {
+  const options = normalizeOptions(rawOptions);
+  const templates = listGateTemplates(templatesPath)
+    .filter((template) => template.category === CATEGORY)
+    .map((template) => ({
+      ...template,
+      recommended: templateApplicability(template, options),
+    }));
+  const signals = buildSignals(options);
+  const recommendedTemplates = templates.filter((template) => template.recommended);
+
+  return {
+    name: 'thumbgate-long-running-agent-context-guardrails',
+    status: recommendedTemplates.length > 0 ? 'actionable' : 'ready',
+    workflow: options.workflow,
+    summary: {
+      signalCount: signals.length,
+      templateCount: templates.length,
+      recommendedTemplateCount: recommendedTemplates.length,
+      requestCount: options.requestCount,
+      outputMb: options.outputMb,
+    },
+    signals,
+    templates,
+    nextActions: [
+      'Persist a director journal with observations, decisions, questions, hypotheses, and open risks.',
+      'Run critic review over expert findings and attach credibility scores before promoting them to shared memory.',
+      'Maintain a critic timeline that deduplicates findings and resolves conflicts by strongest evidence.',
+      'Block long-running agent handoffs that rely only on accumulated chat logs.',
+    ],
+    exampleCommand: 'npx thumbgate long-running-agent-context-guardrails --request-count=80 --output-mb=3 --raw-chat-only --json',
+  };
+}
+
+function formatLongRunningAgentContextGuardrailsPlan(report) {
+  const lines = [
+    '',
+    'ThumbGate Long-Running Agent Context Guardrails',
+    '-'.repeat(50),
+    `Status  : ${report.status}`,
+    `Workflow: ${report.workflow}`,
+    `Signals : ${report.summary.signalCount}`,
+    `Templates: ${report.summary.recommendedTemplateCount}/${report.summary.templateCount} recommended`,
+  ];
+
+  if (report.signals.length > 0) {
+    lines.push('', 'Detected context risk signals:');
+    for (const signal of report.signals) {
+      lines.push(`  - ${signal.label}: ${signal.values.join(', ')}`);
+      lines.push(`    Risk: ${signal.risk}`);
+    }
+  }
+
+  lines.push('', 'Recommended templates:');
+  const recommended = report.templates.filter((template) => template.recommended);
+  if (recommended.length === 0) {
+    lines.push('  - No long-running context risks were passed. Start with --request-count, --raw-chat-only, or critic/journal flags.');
+  } else {
+    for (const template of recommended) {
+      lines.push(`  - ${template.id} [${template.defaultAction}]`);
+      lines.push(`    ${template.roi}`);
+    }
+  }
+
+  lines.push('', 'Next actions:');
+  for (const action of report.nextActions) lines.push(`  - ${action}`);
+  lines.push('', `Example: ${report.exampleCommand}`, '');
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = {
+  buildLongRunningAgentContextGuardrailsPlan,
+  formatLongRunningAgentContextGuardrailsPlan,
+  normalizeOptions,
+};

package/scripts/multimodal-retrieval-plan.js

@@ -1,7 +1,14 @@
 'use strict';
 
+const {
+  buildGeminiEmbeddingRolloutPlan,
+  GEMINI_EMBEDDING_2_MODEL,
+  MULTIMODAL_LIMITS,
+  RECOMMENDED_OUTPUT_DIMENSIONS,
+} = require('./gemini-embedding-policy');
+
 const DEFAULT_EVIDENCE_TYPES = ['screenshots', 'pdf_pages', 'proof_artifacts'];
-const DEFAULT_DIMS = [1024, 512, 256, 128, 64];
+const DEFAULT_DIMS = [...RECOMMENDED_OUTPUT_DIMENSIONS, 512, 256, 128, 64];
 
 function clampInteger(value, { min, max, fallback }) {
   const parsed = Number(value);
@@ -24,8 +31,8 @@ function dimensionPlan({ corpusItems, maxEmbeddingDim }) {
     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',
+      ? 'quality pass for launch-critical retrieval and holdout benchmarking'
+      : 'default cost-efficient Matryoshka pass for online agent recall',
   }));
 }
 
@@ -38,8 +45,8 @@ function buildMultimodalRetrievalPlan(args = {}) {
   });
   const maxEmbeddingDim = clampInteger(args.maxEmbeddingDim, {
     min: 64,
-    max: 2048,
-    fallback: 1024,
+    max: 3072,
+    fallback: 768,
   });
   const latencyBudgetMs = clampInteger(args.latencyBudgetMs, {
     min: 50,
@@ -49,20 +56,32 @@ function buildMultimodalRetrievalPlan(args = {}) {
   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;
+  const defaultDim = dims.some((entry) => entry.dim === 768) ? 768 : dims[0].dim;
+  const gemini = buildGeminiEmbeddingRolloutPlan({
+    corpusItems,
+    outputDimensionality: defaultDim,
+    task: args.task || 'search result',
+    useBatchApi: args.useBatchApi,
+  });
 
   return {
-    planVersion: '2026-04-20',
-    sourcePattern: 'multimodal Sentence Transformers visual document retrieval',
+    planVersion: '2026-05-04',
+    sourcePattern: `${GEMINI_EMBEDDING_2_MODEL} agentic multimodal RAG`,
     goal,
     evidenceTypes,
     architecture: {
-      stage1: 'Index screenshots, PDF pages, dashboard captures, and proof artifacts with a multimodal embedding model.',
+      stage1: 'Index screenshots, PDF pages, dashboard captures, and proof artifacts with Gemini Embedding 2 in one shared semantic space.',
       stage2: useReranker
-        ? 'Rerank the top candidates with a multimodal cross-encoder before using evidence in a gate, PR, or sales proof claim.'
+        ? 'Rerank the top candidates with query/document similarity and hard-negative checks 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.',
     },
+    geminiEmbedding2: {
+      model: GEMINI_EMBEDDING_2_MODEL,
+      modalityLimits: MULTIMODAL_LIMITS,
+      taskPrefixes: gemini.taskPrefixes,
+      batchApi: gemini.economics.batchApi,
+    },
     trainingData: {
       pilotSchema: ['query', 'image', 'negative_0'],
       hardNegativeStrategy: 'Pair each proof query with visually similar but wrong screenshots or PDF pages.',
@@ -82,7 +101,7 @@ function buildMultimodalRetrievalPlan(args = {}) {
       latencyBudgetMs,
       defaultEmbeddingDim: defaultDim,
       matryoshkaDimensions: dims,
-      compressionPath: 'Use Matryoshka truncation first, then quantization only after holdout quality is stable.',
+      compressionPath: 'Use Gemini Embedding 2 Matryoshka truncation first; start at 768 dimensions and benchmark 1536 only when recall misses justify the storage.',
     },
     thumbgateUseCases: [
       'Find the exact screenshot or proof artifact behind a completion claim.',
@@ -93,6 +112,7 @@ function buildMultimodalRetrievalPlan(args = {}) {
     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.',
+      'Use task prefixes at both index time and query time so short agent questions retrieve long proof artifacts correctly.',
       'Evaluate retrieval on holdout screenshots/PDF pages before replacing text-only recall.',
     ],
     nextActions: [

package/scripts/oss-pr-opportunity-scout.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_PACKAGE_PATH = path.join(__dirname, '..', 'package.json');
+const DEFAULT_OUTPUT_DIR = path.join(__dirname, '..', 'docs', 'marketing');
+const KNOWN_REPOS = Object.freeze({
+  '@anthropic-ai/sdk': 'anthropics/anthropic-sdk-typescript',
+  '@google/genai': 'googleapis/js-genai',
+  '@huggingface/transformers': 'huggingface/transformers.js',
+  '@lancedb/lancedb': 'lancedb/lancedb',
+  'apache-arrow': 'apache/arrow-js',
+  'better-sqlite3': 'WiseLibs/better-sqlite3',
+  dotenv: 'motdotla/dotenv',
+  'playwright-core': 'microsoft/playwright',
+  protobufjs: 'protobufjs/protobuf.js',
+  stripe: 'stripe/stripe-node',
+  '@changesets/changelog-github': 'changesets/changesets',
+  '@changesets/cli': 'changesets/changesets',
+  c8: 'bcoe/c8',
+  undici: 'nodejs/undici',
+});
+
+const BOUNTY_KEYWORDS = [
+  'bug bounty',
+  'bounty',
+  'good first issue',
+  'help wanted',
+  'security',
+  'repro',
+  'regression',
+  'docs',
+  'typescript',
+  'test failure',
+];
+
+function normalizeText(value) {
+  if (value === undefined || value === null) return '';
+  return String(value).trim();
+}
+
+function splitList(value) {
+  if (Array.isArray(value)) return value.map(String).map((item) => item.trim()).filter(Boolean);
+  return String(value || '').split(',').map((item) => item.trim()).filter(Boolean);
+}
+
+function slugify(value) {
+  return normalizeText(value)
+    .toLowerCase()
+    .split('')
+    .map((char) => (/[a-z0-9]/.test(char) ? char : '-'))
+    .join('')
+    .split('-')
+    .filter(Boolean)
+    .join('-');
+}
+
+function loadPackage(packagePath = DEFAULT_PACKAGE_PATH) {
+  return JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+}
+
+function dependencyNames(pkg = {}) {
+  return [
+    ...Object.keys(pkg.dependencies || {}),
+    ...Object.keys(pkg.devDependencies || {}),
+    ...Object.keys(pkg.optionalDependencies || {}),
+  ].sort((a, b) => a.localeCompare(b));
+}
+
+function repoFromDependency(name) {
+  return KNOWN_REPOS[name] || '';
+}
+
+function buildIssueSearchQueries(repo) {
+  return [
+    `repo:${repo} is:issue is:open label:"good first issue"`,
+    `repo:${repo} is:issue is:open label:"help wanted"`,
+    `repo:${repo} is:issue is:open bounty OR "bug bounty"`,
+    `repo:${repo} is:issue is:open regression test failure`,
+  ];
+}
+
+function scoreOpportunity(depName, repo, options = {}) {
+  let score = 0;
+  const reasons = [];
+  if (repo) {
+    score += 20;
+    reasons.push('known upstream repository');
+  }
+  if (/sdk|genai|stripe|playwright|lancedb|transformers|sqlite|undici/i.test(depName)) {
+    score += 20;
+    reasons.push('high product adjacency for agent tooling');
+  }
+  if (/anthropic|google|huggingface|stripe|microsoft|nodejs/i.test(repo)) {
+    score += 15;
+    reasons.push('large ecosystem visibility');
+  }
+  if (options.includeBounties) {
+    score += 10;
+    reasons.push('bounty search enabled');
+  }
+  if (/docs|changelog|dotenv|c8/i.test(depName)) {
+    score += 8;
+    reasons.push('lower-risk contribution surface');
+  }
+  return { score, reasons };
+}
+
+function buildOpportunity(depName, options = {}) {
+  const repo = repoFromDependency(depName);
+  const scoring = scoreOpportunity(depName, repo, options);
+  const repoUrl = repo ? `https://github.com/${repo}` : '';
+  return {
+    id: slugify(`${depName}-${repo || 'unknown'}`),
+    dependency: depName,
+    repo,
+    repoUrl,
+    score: scoring.score,
+    reasons: scoring.reasons,
+    issueSearchQueries: repo ? buildIssueSearchQueries(repo) : [],
+    bountyQueries: repo ? [
+      `repo:${repo} is:issue is:open "bug bounty"`,
+      `repo:${repo} is:issue is:open bounty security`,
+    ] : [],
+    safeFixLanes: [
+      'reproduce issue locally before claiming it is fixed',
+      'prefer docs, tests, typed edge cases, and minimal bug fixes',
+      'open one focused PR per issue after reading contribution guidelines',
+      'include ThumbGate only as a transparent proof note when relevant, never as hidden promotion',
+    ],
+    prReadinessGates: [
+      'issue linked or maintainer pain clearly documented',
+      'local reproduction or failing test captured',
+      'fix is minimal and scoped to the issue',
+      'tests or verification output attached',
+      'no bounty, security, or maintainer-policy claim without source link',
+    ],
+    outreachDraft: repo
+      ? `I found this while using ${depName} in ThumbGate. I reproduced the issue, added a minimal fix with tests, and kept the PR scoped to the maintainer's issue.`
+      : '',
+  };
+}
+
+function buildOssPrOpportunityScoutPlan(rawOptions = {}) {
+  const packagePath = normalizeText(rawOptions.packagePath || rawOptions['package-path']) || DEFAULT_PACKAGE_PATH;
+  const pkg = loadPackage(packagePath);
+  const explicitDeps = splitList(rawOptions.dependencies || rawOptions.deps);
+  const includeBounties = rawOptions.includeBounties !== false && rawOptions['include-bounties'] !== false;
+  const maxRepos = Math.max(1, Number.parseInt(String(rawOptions.maxRepos || rawOptions['max-repos'] || 12), 10) || 12);
+  const deps = explicitDeps.length ? explicitDeps : dependencyNames(pkg);
+  const opportunities = deps
+    .map((dep) => buildOpportunity(dep, { includeBounties }))
+    .filter((opportunity) => opportunity.repo)
+    .sort((left, right) => right.score - left.score || left.dependency.localeCompare(right.dependency))
+    .slice(0, maxRepos);
+
+  return {
+    name: 'thumbgate-oss-pr-opportunity-scout',
+    packagePath,
+    generatedAt: new Date().toISOString(),
+    status: opportunities.length ? 'ready_to_scout' : 'needs_repo_mapping',
+    summary: {
+      dependencyCount: deps.length,
+      mappedRepos: opportunities.length,
+      includeBounties,
+      topRepos: opportunities.slice(0, 5).map((item) => item.repo),
+    },
+    searchProtocol: {
+      issueLabels: ['good first issue', 'help wanted', 'bug', 'regression', 'documentation', 'security'],
+      bountyKeywords: BOUNTY_KEYWORDS,
+      antiSpamRule: 'Do not open a PR unless the issue is reproduced, the fix is minimal, and verification output is attached.',
+      promotionRule: 'Mention ThumbGate only as the toolchain context or proof discipline, not as unrelated advertising.',
+    },
+    opportunities,
+    automationCommands: [
+      'gh issue list --repo <owner/repo> --label "good first issue" --state open',
+      'gh issue list --repo <owner/repo> --search "bounty OR bug bounty OR regression"',
+      'gh repo fork <owner/repo> --clone',
+      'npx thumbgate require-evidence-for-claim --claim "fix is ready" before opening the PR',
+    ],
+    marketingAngle: {
+      headline: 'ThumbGate promotes itself by shipping proof-backed fixes, not drive-by ads.',
+      subhead: 'Find upstream repos we actually use, fix real issues with tests, and let maintainers see the agent-governance workflow in the PR evidence.',
+      replyDraft: 'This is a strong promotion loop as long as it is gated: use repos ThumbGate really depends on, fix issues maintainers already care about, attach reproduction plus tests, and make ThumbGate visible through the quality of the PR rather than a pitch.',
+    },
+  };
+}
+
+function formatOssPrOpportunityScoutPlan(report) {
+  const lines = [
+    '',
+    'ThumbGate OSS PR Opportunity Scout',
+    '-'.repeat(35),
+    `Status      : ${report.status}`,
+    `Package     : ${report.packagePath}`,
+    `Mapped repos: ${report.summary.mappedRepos}`,
+    '',
+    'Top opportunities:',
+  ];
+  for (const opportunity of report.opportunities.slice(0, 10)) {
+    lines.push(`  - ${opportunity.repo} (${opportunity.dependency}) score=${opportunity.score}`);
+    lines.push(`    Search: ${opportunity.issueSearchQueries[0]}`);
+  }
+  lines.push('', 'PR gates:');
+  for (const gate of report.searchProtocol.antiSpamRule ? [report.searchProtocol.antiSpamRule] : []) {
+    lines.push(`  - ${gate}`);
+  }
+  lines.push('', `Reply draft: ${report.marketingAngle.replyDraft}`, '');
+  return `${lines.join('\n')}\n`;
+}
+
+function writeOssPrOpportunityScoutPack(outputDir = DEFAULT_OUTPUT_DIR, options = {}) {
+  const report = buildOssPrOpportunityScoutPlan(options);
+  fs.mkdirSync(outputDir, { recursive: true });
+  const jsonPath = path.join(outputDir, 'oss-pr-opportunity-scout.json');
+  const markdownPath = path.join(outputDir, 'oss-pr-opportunity-scout.md');
+  fs.writeFileSync(jsonPath, `${JSON.stringify(report, null, 2)}\n`);
+  fs.writeFileSync(markdownPath, formatOssPrOpportunityScoutPlan(report));
+  return { report, jsonPath, markdownPath };
+}
+
+module.exports = {
+  KNOWN_REPOS,
+  buildIssueSearchQueries,
+  buildOpportunity,
+  buildOssPrOpportunityScoutPlan,
+  formatOssPrOpportunityScoutPlan,
+  writeOssPrOpportunityScoutPack,
+};
+
+function isCliInvocation(argv = process.argv) {
+  return Boolean(argv[1] && path.resolve(argv[1]) === __filename);
+}
+
+if (isCliInvocation()) {
+  const { jsonPath, markdownPath } = writeOssPrOpportunityScoutPack();
+  console.log(JSON.stringify({ jsonPath, markdownPath }, null, 2));
+}