thumbgate 1.26.0 → 1.26.2

package/public/index.html

@@ -20,7 +20,7 @@ __GOOGLE_SITE_VERIFICATION_META__
 <meta property="og:image" content="https://thumbgate.ai/og.png">
 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:image" content="https://thumbgate.ai/og.png">
-<meta name="thumbgate-version" content="1.26.0">
+<meta name="thumbgate-version" content="1.26.2">
 <meta name="keywords" content="ThumbGate, thumbgate, AI agent orchestration, AI experience orchestration, agentic development cycle, AC/DC framework, Guide Generate Verify Solve, agent enforcement layer, save LLM tokens, reduce Claude API cost, reduce OpenAI cost, AI agent token savings, prevent LLM retries, prevent hallucination retries, stop AI token waste, pre-action checks, agent governance, Claude Code, Cursor, Codex, Gemini, Amp, Cline, OpenCode, workflow hardening, context engineering, AI authenticity, brand authenticity AI">
 <link rel="canonical" href="__APP_ORIGIN__/">
 <link rel="alternate" type="text/markdown" title="ThumbGate LLM context" href="__APP_ORIGIN__/llm-context.md">
@@ -1536,6 +1536,14 @@ __GA_BOOTSTRAP__
         <div class="faq-q" role="button" tabindex="0" aria-expanded="false" onclick="toggleFaq(this)" onkeydown="handleFaqKeydown(event)">What does Pro cost?</div>
         <div class="faq-a">Pro is $19/mo or $149/yr for individual operators and bills immediately through Stripe. Team is $49/seat/mo with a 3-seat minimum and starts through the workflow intake so scope, shared rules, and rollout proof are explicit before a team rollout.</div>
       </div>
+      <div class="faq-item">
+        <div class="faq-q" role="button" tabindex="0" aria-expanded="false" onclick="toggleFaq(this)" onkeydown="handleFaqKeydown(event)">Does ThumbGate support enterprise Google Cloud / Vertex AI?</div>
+        <div class="faq-a">Yes! ThumbGate features a zero-friction enterprise setup path via <code>npx thumbgate setup-vertex</code>. This command automatically detects your active gcloud session, enables the Vertex AI API on your Google Cloud project, and configures secure Application Default Credentials (ADC) to route all evaluations within your corporate VPC.</div>
+      </div>
+      <div class="faq-item">
+        <div class="faq-q" role="button" tabindex="0" aria-expanded="false" onclick="toggleFaq(this)" onkeydown="handleFaqKeydown(event)">How does ThumbGate contain enterprise API costs?</div>
+        <div class="faq-a">ThumbGate prevents runaway API costs through a local client-side token ledger (FrontierBudget) that enforces strict cost-containment limits (such as keeping monthly costs under $10/mo). Because GCP billing console alerts are delayed, our local circuit breaker halts runaway agent loops in milliseconds to guarantee budget protection.</div>
+      </div>
     </div>
   </div>
 </section>
@@ -1586,7 +1594,7 @@ __GA_BOOTSTRAP__
       <a href="https://www.linkedin.com/in/igorganapolsky" target="_blank" rel="noopener">LinkedIn</a>
       <a href="/blog">Blog</a>
     </div>
-    <span class="footer-copy">© 2026 ThumbGate · MIT License · npm v1.26.0</span>
+    <span class="footer-copy">© 2026 ThumbGate · MIT License · npm v1.26.2</span>
   </div>
 </footer>
 

package/public/numbers.html

@@ -25,7 +25,7 @@
   "alternateName": "thumbgate",
   "applicationCategory": "DeveloperApplication",
   "operatingSystem": "Cross-platform, Node.js >=18.18.0",
-  "softwareVersion": "1.26.0",
+  "softwareVersion": "1.26.2",
   "url": "https://thumbgate.ai/numbers",
   "dateModified": "2026-05-07",
   "creator": {
@@ -202,7 +202,7 @@
 <main class="container">
   <h1>The Numbers</h1>
   <p class="subtitle">Generated first-party operational snapshot from the ThumbGate runtime. This is not customer traction, install volume, revenue, or proof that a configured gate has fired.</p>
-  <div class="freshness">Updated: 2026-05-07 · Version 1.26.0</div>
+  <div class="freshness">Updated: 2026-05-07 · Version 1.26.2</div>
   <div class="truth-note"><strong>Read this first:</strong> configured checks are inventory. Recorded blocks and warnings are usage evidence. This snapshot currently reports 0 recorded hard-block event(s) and 0 recorded warning event(s).</div>
 
   <h2>Gate enforcement</h2>

package/scripts/action-receipts.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Action Receipts — outcome-paired lessons.
+ *
+ * Pairs each tracked tool call with its concrete result (diff / exit code /
+ * test outcome / state hash) so that a promoted prevention rule can encode
+ * "this action -> this outcome" rather than only a bare thumbs signal.
+ *
+ * Receipts are persisted as JSONL beside the other feedback artifacts
+ * (FEEDBACK_DIR/action-receipts.jsonl) using the same project-scoped
+ * resolution as the rest of the feedback pipeline (feedback-paths).
+ *
+ * This module is self-contained: it only depends on feedback-paths + fs and
+ * makes no edits to shared files. It is consumed from the MCP adapter wiring
+ * step (record_action_receipt / get_action_receipts tools) and threads into
+ * capture_feedback's lesson pipeline + construct_context_pack.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getFeedbackPaths } = require('./feedback-paths');
+
+const RECEIPTS_FILE = 'action-receipts.jsonl';
+
+/**
+ * Resolve the absolute path to the receipts JSONL for the active project.
+ * @param {object} [options] - Passed through to getFeedbackPaths (e.g. for tests).
+ * @returns {string}
+ */
+function getReceiptsPath(options = {}) {
+  const { FEEDBACK_DIR } = getFeedbackPaths(options);
+  return path.join(FEEDBACK_DIR, RECEIPTS_FILE);
+}
+
+function ensureDirFor(filePath) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  } catch {
+    // best-effort; write will surface a real error if the dir truly cannot exist
+  }
+}
+
+function safeString(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  try {
+    return String(value);
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Build a short, human-readable summary of a tool input for the paired-lesson
+ * string. Never throws; clamps length so the lesson stays compact.
+ * @param {*} toolInput
+ * @returns {string}
+ */
+function summarizeInput(toolInput) {
+  if (toolInput === null || toolInput === undefined) return '';
+  if (typeof toolInput === 'string') return clampText(toolInput, 120);
+
+  if (typeof toolInput === 'object') {
+    // Prefer the most lesson-relevant keys when present.
+    const preferredKeys = ['file', 'filePath', 'path', 'command', 'cmd', 'query', 'pattern'];
+    for (const key of preferredKeys) {
+      if (toolInput[key]) {
+        return `${key}=${clampText(safeString(toolInput[key]), 100)}`;
+      }
+    }
+    try {
+      return clampText(JSON.stringify(toolInput), 120);
+    } catch {
+      return '';
+    }
+  }
+
+  return clampText(safeString(toolInput), 120);
+}
+
+function clampText(text, max) {
+  const str = safeString(text);
+  if (str.length <= max) return str;
+  return `${str.slice(0, Math.max(0, max - 1))}…`;
+}
+
+/**
+ * Derive a compact outcome descriptor from an outcome object.
+ * @param {object} outcome
+ * @returns {string}
+ */
+function summarizeOutcome(outcome) {
+  if (!outcome || typeof outcome !== 'object') return 'unknown outcome';
+  const parts = [];
+  if (outcome.testOutcome) parts.push(`tests:${clampText(safeString(outcome.testOutcome), 40)}`);
+  if (outcome.exitCode !== undefined && outcome.exitCode !== null) {
+    parts.push(`exit:${outcome.exitCode}`);
+  }
+  if (outcome.diff) {
+    const diffStr = safeString(outcome.diff);
+    parts.push(`diff:${diffStr.length}b`);
+  }
+  if (outcome.stateHash) parts.push(`hash:${clampText(safeString(outcome.stateHash), 12)}`);
+  return parts.length > 0 ? parts.join(' ') : 'no outcome fields';
+}
+
+/**
+ * Normalize a raw record_action_receipt payload into a stored receipt object.
+ * Accepts either a nested { outcome: {...} } shape or flat top-level fields
+ * (diff / exitCode / testOutcome / stateHash) as the MCP tool surfaces them.
+ * @param {object} params
+ * @returns {object}
+ */
+function normalizeReceipt(params = {}) {
+  const outcomeSource = (params.outcome && typeof params.outcome === 'object')
+    ? params.outcome
+    : params;
+
+  const outcome = {
+    diff: outcomeSource.diff !== undefined ? outcomeSource.diff : null,
+    exitCode: (outcomeSource.exitCode !== undefined && outcomeSource.exitCode !== null)
+      ? Number(outcomeSource.exitCode)
+      : null,
+    testOutcome: outcomeSource.testOutcome !== undefined ? outcomeSource.testOutcome : null,
+    stateHash: outcomeSource.stateHash !== undefined ? outcomeSource.stateHash : null,
+  };
+
+  return {
+    actionId: safeString(params.actionId) || null,
+    toolName: params.toolName !== undefined ? safeString(params.toolName) : null,
+    toolInput: params.toolInput !== undefined ? params.toolInput : null,
+    outcome,
+    recordedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Append a receipt to the JSONL ledger.
+ * @param {object} params - { actionId, toolName, toolInput, outcome:{ diff, exitCode, testOutcome, stateHash } }
+ * @param {object} [options] - feedback-paths options (e.g. for tests).
+ * @returns {object} The stored receipt record (with recorded:true).
+ */
+function recordReceipt(params = {}, options = {}) {
+  const receipt = normalizeReceipt(params);
+  const receiptsPath = getReceiptsPath(options);
+  ensureDirFor(receiptsPath);
+  fs.appendFileSync(receiptsPath, `${JSON.stringify(receipt)}\n`, 'utf8');
+  return { recorded: true, ...receipt };
+}
+
+/**
+ * Read all receipts from the ledger (oldest first). Tolerates malformed lines.
+ * @param {object} [options]
+ * @returns {object[]}
+ */
+function readAllReceipts(options = {}) {
+  const receiptsPath = getReceiptsPath(options);
+  let raw;
+  try {
+    raw = fs.readFileSync(receiptsPath, 'utf8');
+  } catch {
+    return [];
+  }
+  const receipts = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      receipts.push(JSON.parse(trimmed));
+    } catch {
+      // skip malformed line
+    }
+  }
+  return receipts;
+}
+
+/**
+ * Return the most recent receipt for a given actionId, or null.
+ * @param {string} actionId
+ * @param {object} [options]
+ * @returns {object|null}
+ */
+function getReceiptForAction(actionId, options = {}) {
+  if (!actionId) return null;
+  const target = safeString(actionId);
+  const receipts = readAllReceipts(options);
+  for (let i = receipts.length - 1; i >= 0; i -= 1) {
+    if (safeString(receipts[i].actionId) === target) return receipts[i];
+  }
+  return null;
+}
+
+/**
+ * Return the last n receipts (most recent last, preserving chronological order).
+ * @param {number} [n=20]
+ * @param {object} [options]
+ * @returns {object[]}
+ */
+function getRecentReceipts(n = 20, options = {}) {
+  const limit = Number.isFinite(Number(n)) && Number(n) > 0 ? Math.floor(Number(n)) : 20;
+  const receipts = readAllReceipts(options);
+  return receipts.slice(-limit);
+}
+
+/**
+ * Build the "action -> outcome" lesson string for a matched receipt.
+ * @param {object} receipt
+ * @returns {string}
+ */
+function buildOutcomePairedLesson(receipt) {
+  if (!receipt) return '';
+  const toolName = safeString(receipt.toolName) || 'action';
+  const inputSummary = summarizeInput(receipt.toolInput);
+  const outcomeSummary = summarizeOutcome(receipt.outcome);
+  return `${toolName}(${inputSummary}) -> ${outcomeSummary}`;
+}
+
+/**
+ * Resolve which actionId a feedback payload refers to. Supports both the
+ * legacy `lastAction` shape (object or string) and a flat `actionId` field.
+ * @param {object} feedbackParams
+ * @returns {string|null}
+ */
+function resolveFeedbackActionId(feedbackParams = {}) {
+  if (feedbackParams.actionId) return safeString(feedbackParams.actionId);
+
+  const lastAction = feedbackParams.lastAction;
+  if (!lastAction) return null;
+  if (typeof lastAction === 'string') return safeString(lastAction);
+  if (typeof lastAction === 'object') {
+    if (lastAction.actionId) return safeString(lastAction.actionId);
+    if (lastAction.id) return safeString(lastAction.id);
+  }
+  return null;
+}
+
+/**
+ * Enrich a capture_feedback payload with the most recent matching receipt's
+ * outcome so the lesson pipeline encodes action->outcome. If no receipt
+ * matches, the original payload is returned unchanged (never throws).
+ * @param {object} feedbackParams
+ * @param {object} [options]
+ * @returns {object}
+ */
+function pairFeedbackWithReceipt(feedbackParams = {}, options = {}) {
+  const actionId = resolveFeedbackActionId(feedbackParams);
+  if (!actionId) return feedbackParams;
+
+  let receipt = null;
+  try {
+    receipt = getReceiptForAction(actionId, options);
+  } catch {
+    return feedbackParams;
+  }
+  if (!receipt) return feedbackParams;
+
+  const outcomePairedLesson = buildOutcomePairedLesson(receipt);
+
+  return {
+    ...feedbackParams,
+    outcome: { ...receipt.outcome },
+    outcomePairedLesson,
+    receiptActionId: actionId,
+  };
+}
+
+/**
+ * Build construct_context_pack-shaped candidate entries from receipts that
+ * match a free-text query. Returns [{ namespace, text, score }].
+ * @param {string} query
+ * @param {number} [limit=5]
+ * @param {object} [options]
+ * @returns {Array<{namespace:string, text:string, score:number}>}
+ */
+function buildReceiptContextEntries(query, limit = 5, options = {}) {
+  const cap = Number.isFinite(Number(limit)) && Number(limit) > 0 ? Math.floor(Number(limit)) : 5;
+  const receipts = readAllReceipts(options);
+  if (receipts.length === 0) return [];
+
+  const queryTokens = safeString(query)
+    .toLowerCase()
+    .split(/[^a-z0-9]+/i)
+    .filter(Boolean);
+
+  const scored = receipts.map((receipt) => {
+    const lesson = buildOutcomePairedLesson(receipt);
+    const haystack = `${lesson} ${safeString(receipt.toolName)} ${summarizeInput(receipt.toolInput)}`.toLowerCase();
+    let score = 0;
+    for (const token of queryTokens) {
+      if (haystack.includes(token)) score += 1;
+    }
+    const text = `${lesson} [outcome: ${summarizeOutcome(receipt.outcome)}]`;
+    return { namespace: 'action-receipts', text, score };
+  });
+
+  // When the query is empty, surface the most recent receipts (score 0 but
+  // still useful for the pack); otherwise rank by token overlap.
+  const ranked = queryTokens.length === 0
+    ? scored.slice(-cap).reverse()
+    : scored
+      .filter((entry) => entry.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, cap);
+
+  return ranked;
+}
+
+module.exports = {
+  RECEIPTS_FILE,
+  getReceiptsPath,
+  recordReceipt,
+  readAllReceipts,
+  getReceiptForAction,
+  getRecentReceipts,
+  buildOutcomePairedLesson,
+  pairFeedbackWithReceipt,
+  buildReceiptContextEntries,
+  // exposed for testing / reuse
+  summarizeInput,
+  summarizeOutcome,
+  resolveFeedbackActionId,
+};

package/scripts/cli-schema.js

@@ -51,6 +51,20 @@ const CLI_COMMANDS = [
       { name: 'json',            type: 'boolean', description: 'Output as JSON' },
     ],
   },
+  {
+    name: 'feedback-self-test',
+    aliases: ['dogfood'],
+    description: 'Prove thumbs feedback capture works in the current runtime',
+    group: 'capture',
+    mcpTool: 'capture_feedback',
+    flags: [
+      { name: 'feedback',     type: 'string',  description: 'Signal to test: up or down (default down)' },
+      { name: 'context',      type: 'string',  description: 'Context to store in the test capture' },
+      { name: 'persist',      type: 'boolean', description: 'Use the active ThumbGate store instead of an isolated test store' },
+      { name: 'feedback-dir', type: 'string',  description: 'Explicit feedback directory for the self-test' },
+      { name: 'json',         type: 'boolean', description: 'Output as JSON' },
+    ],
+  },
 
   // -------------------------------------------------------------------------
   // Discovery
@@ -590,6 +604,16 @@ const CLI_COMMANDS = [
       { name: 'info',    type: 'boolean', description: 'Show Pro feature list' },
     ],
   },
+  {
+    name: 'brain',
+    description: 'Build the agent-readable context brain (lessons + rules + gates + project context)',
+    group: 'ops',
+    flags: [
+      { name: 'write', type: 'boolean', description: 'Save to .thumbgate/BRAIN.md (versioned, deterministic)' },
+      { name: 'limit', type: 'number',  description: 'Max lessons to include (default 15)' },
+      { name: 'json',  type: 'boolean', description: 'Output the structured model as JSON' },
+    ],
+  },
 ];
 
 /**

package/scripts/dashboard.js

@@ -17,6 +17,7 @@ const { filterEntriesForWindow, resolveAnalyticsWindow } = require('./analytics-
 const { resolveHostedBillingConfig } = require('./hosted-config');
 const { generateAgentReadinessReport } = require('./agent-readiness');
 const { summarizeGateTemplates } = require('./gate-templates');
+const { mergeRepeatMetricIntoGateStats } = require('./repeat-metric');
 const { buildPredictiveInsights } = loadOptionalModule('./predictive-insights', () => ({
   buildPredictiveInsights: () => ({
     upgradePropensity: {
@@ -1613,7 +1614,11 @@ function generateDashboard(feedbackDir, options = {}) {
   const billingSummary = options.billingSummary || getBillingSummary(analyticsWindow);
 
   const approval = computeApprovalStats(entries);
-  const gateStats = computeGateStats();
+  // Surface the "repeat-attempts blocked before execution" metric on the
+  // dashboard JSON and the /v1/dashboard HTTP route. Use the non-mutating
+  // helper (mirrors server-stdio.js) instead of mutating computeGateStats()'s
+  // return value. (mergeRepeatMetricIntoGateStats is imported at top of file.)
+  const gateStats = mergeRepeatMetricIntoGateStats(computeGateStats());
   const prevention = computePreventionImpact(feedbackDir, gateStats);
   const trend = computeSessionTrend(entries, 10);
   const health = computeSystemHealth(feedbackDir, gateStats);

package/scripts/gates-engine.js

@@ -3,8 +3,9 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const crypto = require('crypto');
-const { execSync, execFileSync } = require('child_process');
+const { execFileSync } = require('child_process');
 const { loadOptionalModule } = require('./private-core-boundary');
 
 const { isProTier, isInTrialPeriod, FREE_TIER_MAX_GATES, FREE_TIER_DAILY_BLOCKS, todayKey } = require('./rate-limiter');
@@ -30,10 +31,12 @@ function computeExecutableHash(command) {
     const firstWord = command.trim().split(/\s+/)[0];
     if (!firstWord) return null;
 
-    // Resolve absolute path using 'which'
+    // Resolve absolute path using 'which'. Use execFileSync (no shell) and pass
+    // firstWord as an argv element, never interpolated into a command string, so
+    // a hostile `command` value cannot inject shell metacharacters here.
     let fullPath;
     try {
-      fullPath = execSync(`which ${firstWord}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      fullPath = execFileSync('which', [firstWord], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
     } catch (e) {
       // If 'which' fails, it might be an absolute path or a non-existent command
       fullPath = path.isAbsolute(firstWord) ? firstWord : null;
@@ -65,12 +68,28 @@ const { recordAuditEvent, auditToFeedback } = require('./audit-trail');
 
 const DEFAULT_CONFIG_PATH = path.join(__dirname, '..', 'config', 'gates', 'default.json');
 const DEFAULT_CLAIM_GATES_PATH = path.join(__dirname, '..', 'config', 'gates', 'claim-verification.json');
-const STATE_PATH = path.join(process.env.HOME || '/tmp', '.thumbgate', 'gate-state.json');
-const CONSTRAINTS_PATH = path.join(process.env.HOME || '/tmp', '.thumbgate', 'session-constraints.json');
-const STATS_PATH = path.join(process.env.HOME || '/tmp', '.thumbgate', 'gate-stats.json');
-const SESSION_ACTIONS_PATH = path.join(process.env.HOME || '/tmp', '.thumbgate', 'session-actions.json');
-const CUSTOM_CLAIM_GATES_PATH = path.join(process.env.HOME || '/tmp', '.thumbgate', 'claim-verification.json');
-const GOVERNANCE_STATE_PATH = path.join(process.env.HOME || '/tmp', '.thumbgate', 'governance-state.json');
+
+function resolveThumbgateStateDir() {
+  if (process.env.THUMBGATE_STATE_DIR) return process.env.THUMBGATE_STATE_DIR;
+
+  if (process.env.XDG_STATE_HOME) {
+    return path.join(process.env.XDG_STATE_HOME, 'thumbgate');
+  }
+
+  if (process.env.CODEX_SANDBOX) {
+    return path.join(os.tmpdir(), 'thumbgate');
+  }
+
+  return path.join(process.env.HOME || os.tmpdir(), '.thumbgate');
+}
+
+const STATE_DIR = resolveThumbgateStateDir();
+const STATE_PATH = path.join(STATE_DIR, 'gate-state.json');
+const CONSTRAINTS_PATH = path.join(STATE_DIR, 'session-constraints.json');
+const STATS_PATH = path.join(STATE_DIR, 'gate-stats.json');
+const SESSION_ACTIONS_PATH = path.join(STATE_DIR, 'session-actions.json');
+const CUSTOM_CLAIM_GATES_PATH = path.join(STATE_DIR, 'claim-verification.json');
+const GOVERNANCE_STATE_PATH = path.join(STATE_DIR, 'governance-state.json');
 const TTL_MS = 5 * 60 * 1000; // 5 minutes
 const SESSION_ACTION_TTL_MS = 60 * 60 * 1000; // 1 hour
 const PROTECTED_APPROVAL_TTL_MS = 60 * 60 * 1000; // 1 hour

package/scripts/llm-client.js

@@ -12,19 +12,20 @@ const DEFAULT_MODEL = MODELS.FAST;
 const DEFAULT_MAX_TOKENS = 1024;
 const DEFAULT_CACHE_TTL = '5m';
 
-let _client = null;
+let _anthropicClient = null;
+let _geminiClient = null;
 
 function isAvailable() {
   return Boolean(process.env.ANTHROPIC_API_KEY);
 }
 
 function getClient() {
-  if (_client) return _client;
+  if (_anthropicClient) return _anthropicClient;
   if (!isAvailable()) return null;
   try {
     const Anthropic = require('@anthropic-ai/sdk');
-    _client = new Anthropic();
-    return _client;
+    _anthropicClient = new Anthropic();
+    return _anthropicClient;
   } catch {
     return null;
   }
@@ -138,7 +139,92 @@ function parseClaudeJson(text) {
   }
 }
 
+async function callGeminiInternal(options = {}) {
+  const env = process.env;
+  const { detectInferenceBackend } = require('./local-model-profile');
+  const providerMode = detectInferenceBackend(env).providerMode;
+
+  try {
+    const { GoogleGenAI } = require('@google/genai');
+    if (!_geminiClient) {
+      if (providerMode === 'vertex') {
+        _geminiClient = new GoogleGenAI({
+          enterprise: true,
+          project: env.VERTEX_PROJECT_ID || 'ai-revenue28-webhook',
+          location: env.VERTEX_LOCATION || 'us-central1',
+        });
+      } else {
+        _geminiClient = new GoogleGenAI({
+          apiKey: env.GEMINI_API_KEY,
+        });
+      }
+    }
+
+    const contents = convertMessagesToGemini(options.messages, options.userPrompt);
+    const config = {};
+    if (options.systemPrompt) {
+      config.systemInstruction = options.systemPrompt;
+    }
+    if (Number.isFinite(options.temperature)) {
+      config.temperature = options.temperature;
+    }
+    if (options.maxTokens) {
+      config.maxOutputTokens = options.maxTokens;
+    }
+
+    const response = await runStep('llm.callGemini', {
+      retries: 2,
+      logger: (msg) => console.warn(msg),
+    }, async () => _geminiClient.models.generateContent({
+      model: options.model,
+      contents,
+      config,
+    }));
+
+    return {
+      text: response.text || '',
+      usage: response.usageMetadata ? {
+        input_tokens: response.usageMetadata.promptTokenCount,
+        output_tokens: response.usageMetadata.candidatesTokenCount,
+      } : null,
+      stopReason: response.candidates?.[0]?.finishReason || null,
+      id: null,
+      model: options.model,
+    };
+  } catch (err) {
+    console.error('Gemini/Vertex AI execution error:', err);
+    return null;
+  }
+}
+
+function convertMessagesToGemini(messages, userPrompt) {
+  const list = Array.isArray(messages) && messages.length > 0
+    ? messages
+    : [{ role: 'user', content: userPrompt }];
+
+  return list.map((msg) => {
+    const role = msg.role === 'assistant' ? 'model' : 'user';
+    let text = '';
+    if (typeof msg.content === 'string') {
+      text = msg.content;
+    } else if (Array.isArray(msg.content)) {
+      text = msg.content.map((c) => c.text || '').join('');
+    } else if (msg.content && typeof msg.content === 'object') {
+      text = msg.content.text || JSON.stringify(msg.content);
+    }
+    return {
+      role,
+      parts: [{ text }],
+    };
+  });
+}
+
 async function callClaudeInternal(options = {}) {
+  const modelName = options.model || '';
+  if (modelName.startsWith('gemini') || modelName.startsWith('vertex')) {
+    return callGeminiInternal(options);
+  }
+
   const client = getClient();
   if (!client) return null;
 

package/scripts/local-model-profile.js

@@ -111,7 +111,8 @@ function isSparseAttentionFamily(modelFamily) {
 
 function resolveProviderMode(env = process.env) {
   const explicit = normalizeSlug(env.THUMBGATE_PROVIDER_MODE || env.THUMBGATE_MODEL_PROVIDER_MODE);
-  if (explicit === 'local' || explicit === 'managed') return explicit;
+  if (explicit === 'local' || explicit === 'managed' || explicit === 'vertex') return explicit;
+  if (env.VERTEX_PROJECT_ID || env.VERTEX_API_ENDPOINT) return 'vertex';
   if (env.THUMBGATE_LOCAL_MODEL_FAMILY || env.THUMBGATE_LOCAL_MODEL_SERVER) return 'local';
   return 'managed';
 }
@@ -133,6 +134,7 @@ function resolveModelFamily(env = process.env) {
 }
 
 function buildBackendLabel(providerMode, modelFamily) {
+  if (providerMode === 'vertex') return 'Vertex AI secure cloud backend';
   if (providerMode === 'managed') return 'Managed API backend';
   if (modelFamily.startsWith('deepseek')) return 'Local DeepSeek sparse backend';
   if (modelFamily.startsWith('glm')) return 'Local GLM sparse backend';
@@ -148,14 +150,18 @@ function detectInferenceBackend(env = process.env) {
     && supportsSparseAttention
     && INDEXCACHE_SERVER_ENGINES.has(serverEngine);
   const indexCacheEnabled = indexCacheEligible && parseBoolean(env.THUMBGATE_INDEXCACHE_ENABLED, false);
-  const id = providerMode === 'managed'
-    ? 'managed-api'
-    : supportsSparseAttention
-      ? `local-${modelFamily}-sparse`
-      : 'local-dense';
+  const id = providerMode === 'vertex'
+    ? 'vertex-api'
+    : providerMode === 'managed'
+      ? 'managed-api'
+      : supportsSparseAttention
+        ? `local-${modelFamily}-sparse`
+        : 'local-dense';
 
   let rationale = 'Baseline backend with no sparse-attention acceleration.';
-  if (providerMode === 'managed') {
+  if (providerMode === 'vertex') {
+    rationale = 'Vertex AI secure cloud backend providing compliant enterprise Gemini models inside VPC boundary.';
+  } else if (providerMode === 'managed') {
     rationale = 'Managed API path does not expose sparse-attention kernel controls like IndexCache.';
   } else if (indexCacheEnabled) {
     rationale = `Local ${modelFamily} backend is sparse-attention capable and IndexCache-ready on ${serverEngine}.`;
@@ -336,7 +342,8 @@ function resolveModelRole(role, env) {
   const envKey = `THUMBGATE_MODEL_ROLE_${normalized.toUpperCase()}`;
   const modelFamily = resolveModelFamily(e);
   const isLocalGlm = modelFamily.startsWith('glm');
-  const provider = isLocalGlm ? 'local' : 'gemini';
+  const providerMode = resolveProviderMode(e);
+  const provider = isLocalGlm ? 'local' : (providerMode === 'vertex' ? 'vertex' : 'gemini');
   const defaultModel = isLocalGlm ? (GLM_MODEL_ROLES[normalized] || MODEL_ROLES[normalized]) : MODEL_ROLES[normalized];
   const model = (e[envKey] && String(e[envKey]).trim()) || defaultModel;
   return { role: normalized, model, provider, envKey };