everything-gemini 2.1.0 → 2.2.0

package/docs/index.html

@@ -595,7 +595,7 @@
       <!-- Metrics -->
       <div class="metrics">
         <div class="metric-card">
-          <div class="metric-value">63</div>
+          <div class="metric-value">68</div>
           <div class="metric-label">Progressive Skills</div>
         </div>
         <div class="metric-card">
@@ -603,7 +603,7 @@
           <div class="metric-label">Scoped Subagents</div>
         </div>
         <div class="metric-card">
-          <div class="metric-value">8</div>
+          <div class="metric-value">9</div>
           <div class="metric-label">Lifecycle Hooks</div>
         </div>
         <div class="metric-card">
@@ -670,6 +670,7 @@
       { name: "harness2-recursive-optimization", type: "skill", cat: "frontier", desc: "Google Research Harness² framework (arXiv:2610.14224), 8-surface architecture, test-time Propose-Probe-Compose recursive loops, and continual harness learning." },
       { name: "gemini-multimodal", type: "skill", cat: "frontier", desc: "Native visual reasoning over UI mockups, converting wireframes to frontend code, diagram-to-Mermaid extraction, and visual regression QA." },
       { name: "context-caching", type: "skill", cat: "frontier", desc: "1M-2M token context optimization with deterministic static prefix caching, skeleton ingestion, and ~75% cost savings." },
+      { name: "context-warmer", type: "skill", cat: "frontier", desc: "Automates workspace repository analysis, Knowledge Item clustering, and pre-warming prefix context caches before subagent execution." },
       { name: "gemini-grounding", type: "skill", cat: "frontier", desc: "Live Google Search grounding to eliminate hallucinations, verify real-time APIs, and retrieve breaking documentation." },
       { name: "rag-architect", type: "skill", cat: "frontier", desc: "Retrieval-augmented generation pipelines, semantic AST chunking, hybrid keyword-vector search, and Gemini re-ranking." },
       { name: "gemini-function-calling", type: "skill", cat: "frontier", desc: "Production function declarations, structured JSON output schemas (Pydantic), parallel tool execution, and error recovery." },
@@ -699,7 +700,11 @@
       { name: "agents/platform-engineer", type: "subagent", cat: "subagent", desc: "Cloud platform & IDP specialist authoring Terraform/OpenTofu, Kubernetes manifests, zero-trust network policies, and container right-sizing." },
       { name: "agents/mlops-engineer", type: "subagent", cat: "subagent", desc: "Specialist in AI model serving (Triton/vLLM), persistent vector stores (ChromaDB/Milvus), prefix context caching, and KEDA autoscaling." },
 
-      // Backend & Cloud Skills (34)
+      // Backend & Cloud Skills (38)
+      { name: "bigquery-vector-search", type: "skill", cat: "backend", desc: "Google BigQuery native vector search, VECTOR_SEARCH SQL statements, ML.GENERATE_TEXT_EMBEDDING, IVF indexing, and BigLake hybrid semantic RAG." },
+      { name: "cloud-run-agents", type: "skill", cat: "backend", desc: "Containerized autonomous agent hosting on Google Cloud Run, Cloud Run Jobs for Harness² recursive probing, Eventarc triggers, and NVIDIA L4 GPU acceleration." },
+      { name: "pubsub-event-mesh", type: "skill", cat: "backend", desc: "Google Cloud Pub/Sub asynchronous event mesh, exactly-once delivery, dead-letter queues, and schema-validated multi-agent message routing." },
+      { name: "spanner-graph-rag", type: "skill", cat: "backend", desc: "Google Cloud Spanner Graph schemas, ISO GQL queries, knowledge graph traversal, and hybrid graph-vector RAG pipelines for Gemini agents." },
       { name: "dataproc-spark-analytics", type: "skill", cat: "backend", desc: "Google Cloud Dataproc Serverless Spark, PySpark batch pipelines, Gemini embedding UDFs, BigLake vector indexing, and probe verification." },
       { name: "triton-inference-server", type: "skill", cat: "backend", desc: "NVIDIA Triton Inference Server multi-model serving, dynamic batching, GPU acceleration, TensorRT-LLM, and vLLM backends." },
       { name: "chromadb-vector-store", type: "skill", cat: "backend", desc: "Persistent vector database storage, Gemini embeddings, collection partitioning, metadata filtering, and semantic similarity search." },
@@ -750,11 +755,12 @@
       { name: "git-craftsman", type: "skill", cat: "devops", desc: "Conventional atomic commits, interactive rebasing, clean branch lifecycles, and git hygiene." },
       { name: "performance-profiler", type: "skill", cat: "devops", desc: "Application latency profiling, CPU/memory leak diagnosis, and slow query optimization." },
 
-      // Lifecycle Safety Hooks (8)
+      // Lifecycle Safety Hooks (9)
       { name: "gemini-shield", type: "hook", cat: "hook", desc: "Deterministic PreToolUse lifecycle gate blocking catastrophic commands (rm -rf, DROP TABLE, git push --force)." },
       { name: "safety-shield", type: "hook", cat: "hook", desc: "PreToolUse shell execution firewall that inspects CLI commands against safety rules before execution." },
       { name: "secret-scrubber", type: "hook", cat: "hook", desc: "PreToolUse security gate intercepting file write operations to block hardcoded API keys and private secrets." },
       { name: "budget-guard", type: "hook", cat: "hook", desc: "PreToolUse financial spend guardrail enforcing hard USD limits (MAX_USD_BUDGET) to prevent runaway agent loops." },
+      { name: "human-gate", type: "hook", cat: "hook", desc: "Event-driven Human-in-the-Loop gating intercepting modifications to agent harness surfaces (.agents/, rules/) requiring interactive approval." },
       { name: "auto-lint-formatter", type: "hook", cat: "hook", desc: "PostToolUse automated formatting with project linters (prettier, black, ruff, gofmt) immediately after file edits." },
       { name: "goal-verifier", type: "hook", cat: "hook", desc: "Stop hook intercepting agent exit, validating whether test suites pass or objectives are fulfilled before stopping." },
       { name: "ephemeral-context", type: "hook", cat: "hook", desc: "PreInvocation hook dynamically injecting repo context, alerts, and instructions into model reasoning turns." },

package/hooks/human-gate/hooks.json

@@ -0,0 +1,16 @@
+{
+  "human-gate": {
+    "PreToolUse": [
+      {
+        "matcher": "run_command|write_to_file|replace_file_content|multi_replace_file_content",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ./scripts/human-gate.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/human-gate/scripts/human-gate.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# HumanGate: Event-Driven Human-in-the-Loop Interceptor
+# Intercepts speculative mutations to agent harness surfaces (.agents/, rules/, hooks/)
+# and destructive administrative actions, ensuring human oversight before persistence.
+
+set -eo pipefail
+
+PAYLOAD=$(cat)
+
+CHECK_RESULT=$(node -e "
+try {
+  const p = JSON.parse(process.argv[1]);
+  const tool = p.toolCall?.name || '';
+  const args = p.toolCall?.args || {};
+
+  // 1. Inspect file writes and mutations to core agent governance files
+  const targetFile = args.TargetFile || args.path || args.file || '';
+  const sensitivePaths = [
+    'rules/common/GEMINI.md',
+    'rules/common/AGENTS.md',
+    '.agents/rules',
+    'hooks/',
+    'harness.yaml',
+    'harness.json'
+  ];
+
+  for (const s of sensitivePaths) {
+    if (targetFile.includes(s)) {
+      console.log(JSON.stringify({
+        decision: 'ask',
+        reason: '[HumanGate] Structural modification to agent harness surface (' + s + ') requires explicit engineer confirmation.'
+      }));
+      process.exit(0);
+    }
+  }
+
+  // 2. Inspect command-line actions for high-risk operations
+  const cmd = args.CommandLine || '';
+  const highRiskCmds = [
+    'gcloud projects delete',
+    'bq rm',
+    'terraform apply',
+    'kubectl apply',
+    'git push origin main',
+    'git push --force'
+  ];
+
+  for (const r of highRiskCmds) {
+    if (cmd.includes(r)) {
+      console.log(JSON.stringify({
+        decision: 'ask',
+        reason: '[HumanGate] High-impact command execution (' + r + ') requires explicit interactive confirmation.'
+      }));
+      process.exit(0);
+    }
+  }
+
+  // Safe to proceed
+  console.log(JSON.stringify({ decision: 'allow' }));
+} catch (err) {
+  // Graceful fallback to allow if payload parsing fails
+  console.log(JSON.stringify({ decision: 'allow' }));
+}
+" "$PAYLOAD")
+
+echo "$CHECK_RESULT"
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "everything-gemini",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Everything Gemini (everything-gemini) - The Ultimate Agent Harness, Multi-Agent Orchestrator & Performance Suite for Gemini & Google Antigravity",
   "main": "bin/everything-gemini",
   "bin": {

package/skills/bigquery-vector-search/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: bigquery-vector-search
+description: Implements Google BigQuery native vector search, VECTOR_SEARCH SQL statements, ML.GENERATE_TEXT_EMBEDDING, IVF indexing, and BigLake hybrid semantic RAG.
+---
+
+# BigQuery Vector Search & Semantic Analytics
+
+Architects, indexes, and queries large-scale vector embeddings directly inside Google BigQuery using native `VECTOR_SEARCH` syntax, Inverted File (IVF) vector indexes, and `ML.GENERATE_TEXT_EMBEDDING` with Gemini models.
+
+---
+
+## 1. Architecture: BigQuery In-Database Vector Analytics
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                            Google Cloud BigQuery                            │
+│                                                                             │
+│   ┌────────────────────┐      ┌──────────────────┐      ┌─────────────────┐ │
+│   │ Structured Records │      │ Unstructured     │      │ BigLake Object  │ │
+│   │ (SQL Tables)       │      │ Text & Metadata  │      │ Tables (GCS)    │ │
+│   └─────────┬──────────┘      └────────┬─────────┘      └────────┬────────┘ │
+│             │                          │                         │          │
+│             └──────────────────┬───────┴─────────────────────────┘          │
+│                                │                                            │
+│                                ▼                                            │
+│            ┌───────────────────────────────────────────────┐                │
+│            │ ML.GENERATE_TEXT_EMBEDDING (Vertex AI Gemini) │                │
+│            │ 768-dim embeddings stored as ARRAY<FLOAT64>   │                │
+│            └───────────────────────┬───────────────────────┘                │
+│                                    │                                        │
+│                                    ▼                                        │
+│            ┌───────────────────────────────────────────────┐                │
+│            │ IVF Vector Index (Inverted File Partitioning) │                │
+│            │ Distance: COSINE / EUCLIDEAN / DOT_PRODUCT    │                │
+│            └───────────────────────┬───────────────────────┘                │
+│                                    │                                        │
+│                                    ▼                                        │
+│            ┌───────────────────────────────────────────────┐                │
+│            │ VECTOR_SEARCH + Post-Filter SQL Join          │                │
+│            │ Sub-second Top-K nearest neighbor retrieval   │                │
+│            └───────────────────────────────────────────────┘                │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. IVF Vector Indexing
+
+BigQuery supports Inverted File Flat (IVF) indexes to partition vector space into Voronoi cells, accelerating approximate nearest neighbor (ANN) retrieval across billions of rows.
+
+```sql
+-- 1. Create native vector index on embedding column
+CREATE VECTOR INDEX IF NOT EXISTS knowledge_vector_idx
+ON `my_project.agent_knowledge.document_chunks`(embedding)
+STORING(chunk_id, doc_id, section_title)
+OPTIONS(
+  index_type = 'IVF',
+  distance_type = 'COSINE',
+  ivf_options = '{"num_lists": 1000}'
+);
+```
+
+- **`num_lists`**: The number of Voronoi partitions (rule of thumb: $\sqrt{N}$ where $N$ is row count).
+- **`distance_type`**: `COSINE` (recommended for normalized embeddings), `EUCLIDEAN`, or `DOT_PRODUCT`.
+- **`STORING`**: Co-locates frequently queried payload attributes in the vector index leaf nodes, eliminating secondary table lookups.
+
+---
+
+## 3. In-Database Embeddings Generation with Gemini
+
+Connect BigQuery directly to Vertex AI Gemini text-embedding models:
+
+```sql
+-- 1. Create connection to Vertex AI Remote Model
+CREATE OR REPLACE MODEL `my_project.agent_knowledge.gemini_embedding_model`
+REMOTE WITH CONNECTION `projects/my_project/locations/us-central1/connections/vertex-ai-conn`
+OPTIONS(
+  endpoint = 'text-embedding-004'
+);
+
+-- 2. Batch generate embeddings for newly inserted document chunks
+INSERT INTO `my_project.agent_knowledge.document_chunks` (chunk_id, doc_id, content, embedding)
+SELECT
+  ml_generate_embedding_result.chunk_id,
+  ml_generate_embedding_result.doc_id,
+  ml_generate_embedding_result.content,
+  ml_generate_embedding_result.text_embedding AS embedding
+FROM ML.GENERATE_TEXT_EMBEDDING(
+  MODEL `my_project.agent_knowledge.gemini_embedding_model`,
+  (
+    SELECT chunk_id, doc_id, content
+    FROM `my_project.agent_knowledge.raw_chunks`
+    WHERE processed_at IS NULL
+  ),
+  STRUCT(
+    'RETRIEVAL_DOCUMENT' AS task_type,
+    768 AS output_dimensionality
+  )
+) AS ml_generate_embedding_result;
+```
+
+---
+
+## 4. Native `VECTOR_SEARCH` Execution
+
+Query embeddings directly with sub-second latency and zero external vector database infrastructure:
+
+```sql
+-- Top-10 semantic search with structured tenant/date pre-filtering
+SELECT
+  base.chunk_id,
+  base.doc_id,
+  base.content,
+  distance
+FROM VECTOR_SEARCH(
+  TABLE `my_project.agent_knowledge.document_chunks`,
+  'embedding',
+  (
+    -- Embed user query dynamically using Gemini
+    SELECT text_embedding AS query_vector
+    FROM ML.GENERATE_TEXT_EMBEDDING(
+      MODEL `my_project.agent_knowledge.gemini_embedding_model`,
+      (SELECT 'What are the spend limit policies for autonomous subagents?' AS content),
+      STRUCT('RETRIEVAL_QUERY' AS task_type, 768 AS output_dimensionality)
+    )
+  ),
+  top_k => 10,
+  distance_type => 'COSINE',
+  options => '{"fraction_lists_to_search": 0.05}'
+);
+```
+
+- **`fraction_lists_to_search`**: Controls recall vs. latency tradeoff (0.01 to 0.20). Higher values increase recall at slightly higher compute cost.
+
+---
+
+## 5. Hybrid Search (Lexical BM25 + Semantic Vector)
+
+Combine BigQuery native search indexes (`SEARCH`) with `VECTOR_SEARCH` using Reciprocal Rank Fusion (RRF):
+
+```sql
+WITH vector_matches AS (
+  SELECT
+    base.chunk_id,
+    base.content,
+    ROW_NUMBER() OVER (ORDER BY distance ASC) AS vector_rank
+  FROM VECTOR_SEARCH(
+    TABLE `my_project.agent_knowledge.document_chunks`,
+    'embedding',
+    (SELECT text_embedding FROM ML.GENERATE_TEXT_EMBEDDING(
+      MODEL `my_project.agent_knowledge.gemini_embedding_model`,
+      (SELECT 'subagent spend guardrails' AS content),
+      STRUCT('RETRIEVAL_QUERY' AS task_type)
+    )),
+    top_k => 50,
+    distance_type => 'COSINE'
+  )
+),
+keyword_matches AS (
+  SELECT
+    chunk_id,
+    content,
+    ROW_NUMBER() OVER () AS keyword_rank
+  FROM `my_project.agent_knowledge.document_chunks`
+  WHERE SEARCH(content, 'guardrail spend budget ceiling')
+  LIMIT 50
+)
+SELECT
+  COALESCE(v.chunk_id, k.chunk_id) AS chunk_id,
+  COALESCE(v.content, k.content) AS content,
+  (
+    COALESCE(1.0 / (60 + v.vector_rank), 0.0) +
+    COALESCE(1.0 / (60 + k.keyword_rank), 0.0)
+  ) AS rrf_score
+FROM vector_matches v
+FULL OUTER JOIN keyword_matches k ON v.chunk_id = k.chunk_id
+ORDER BY rrf_score DESC
+LIMIT 10;
+```
+
+---
+
+## 6. Enterprise Best Practices & Anti-Patterns
+
+| Category | Recommended Pattern | Anti-Pattern |
+| :--- | :--- | :--- |
+| **Index Choice** | Use IVF with `num_lists` scaled to $\sqrt{N}$ for $N > 100,000$ rows | Querying `ARRAY<FLOAT64>` with brute-force `COSINE_DISTANCE()` |
+| **Payload Storage** | Store lightweight metadata with `STORING(...)` inside index | Joining 10 high-cardinality tables after vector search |
+| **Embedding Types** | Specify `RETRIEVAL_DOCUMENT` during indexing, `RETRIEVAL_QUERY` during search | Using default task types causing asymmetric vector drift |
+| **Partitioning** | Partition and cluster base table on tenant ID or ingestion date | Single unpartitioned table forcing full-table vector scans |
+
+---
+
+## 7. CLI Runbook (`bq` CLI)
+
+```bash
+# 1. Create BigQuery dataset for vector embeddings
+bq mk --dataset --location=us-central1 my_project:agent_knowledge
+
+# 2. Check vector index status and coverage
+bq show --format=prettyjson my_project:agent_knowledge.document_chunks | jq '.vectorSearchStatistics'
+
+# 3. Dry-run vector query to estimate bytes scanned
+bq query --use_legacy_sql=false --dry_run < vector_query.sql
+```

package/skills/cloud-run-agents/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: cloud-run-agents
+description: Packages, deploys, and scales autonomous Antigravity and Gemini agents on Google Cloud Run services and Cloud Run Jobs with Eventarc triggers and GPU scheduling.
+---
+
+# Cloud Run Autonomous Agents
+
+Packages, containerizes, and deploys autonomous Google Antigravity & Gemini agents on Google Cloud Run. Covers HTTP agent services, batch-oriented Cloud Run Jobs for recursive Harness² probing, Eventarc event triggers, and NVIDIA L4 GPU acceleration.
+
+---
+
+## 1. Architecture: Cloud Run Agent Execution Models
+
+```
+                                Google Cloud Run
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ 1. CLOUD RUN SERVICE (Interactive / Webhook Agents)                         │
+│    • Real-time Gemini Live WebSocket / HTTP streaming                        │
+│    • Automatic scale-to-zero when idle                                      │
+│    • Up to 60-minute request timeout with WebSockets enabled                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ 2. CLOUD RUN JOBS (Batch / Recursive Probing Agents)                         │
+│    • Long-running Harness² Propose-Probe-Compose workflows (up to 24 hours) │
+│    • Parallel array task execution for multi-candidate testing              │
+│    • Zero HTTP gateway overhead; triggered via Cloud Scheduler / Workflows │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ 3. CLOUD RUN WITH GPU (NVIDIA L4 / T4)                                      │
+│    • Co-locates agent logic with local verification models (vLLM / Triton)   │
+│    • Direct hardware acceleration for code analysis & AST parsing           │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Agent Container Specification (Dockerfile)
+
+Production multi-stage Dockerfile bundling the agent runtime, Node CLI, and Python SDK:
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM python:3.11-slim AS base
+
+ENV PYTHONUNBUFFERED=1 \
+    DEBIAN_FRONTEND=noninteractive \
+    PORT=8080
+
+WORKDIR /app
+
+# Install system dependencies & Node.js for CLI tools
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    git \
+    ca-certificates \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install everything-gemini CLI globally
+RUN npm install -g everything-gemini
+
+# Copy Python requirements & install
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy agent definitions and source code
+COPY . .
+
+# Run as non-root user for enterprise container security
+RUN useradd -m -u 10001 agentuser && chown -R agentuser:agentuser /app
+USER 10001
+
+EXPOSE 8080
+ENTRYPOINT ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]
+```
+
+---
+
+## 3. Cloud Run Service Deployment (`gcloud`)
+
+Deploy an interactive agent service with Workload Identity and automated secret injection:
+
+```bash
+gcloud run deploy antigravity-agent-service \
+  --image="gcr.io/my_project/antigravity-agent:v2.2.0" \
+  --region="us-central1" \
+  --platform="managed" \
+  --service-account="agent-runner@my_project.iam.gserviceaccount.com" \
+  --cpu=4 \
+  --memory=8Gi \
+  --concurrency=10 \
+  --timeout=3600 \
+  --min-instances=0 \
+  --max-instances=20 \
+  --set-env-vars="GEMINI_MODEL=gemini-2.0-flash,MAX_USD_BUDGET=15.00" \
+  --set-secrets="GEMINI_API_KEY=gemini-api-key:latest" \
+  --vpc-egress=private-ranges-only \
+  --ingress=internal-and-cloud-load-balancing
+```
+
+---
+
+## 4. Cloud Run Jobs for Harness² Recursive Probing
+
+When running test-time recursive optimization (Propose-Probe-Compose) that exceeds standard HTTP request limits, package the run into a Cloud Run Job:
+
+```bash
+# 1. Create Cloud Run Job with 3 parallel task instances
+gcloud run jobs create harness2-probe-runner \
+  --image="gcr.io/my_project/harness2-runner:v2.2.0" \
+  --region="us-central1" \
+  --tasks=3 \
+  --max-retries=1 \
+  --task-timeout=7200s \
+  --cpu=8 \
+  --memory=16Gi \
+  --command="everything-gemini" \
+  --args="harness2,run,--bench,local,--max-usd,25,--snapshot,--json"
+
+# 2. Trigger asynchronous execution of the probe job
+gcloud run jobs execute harness2-probe-runner --region="us-central1" --wait
+```
+
+---
+
+## 5. Eventarc Trigger Binding (Event-Driven Agent Workflow)
+
+Automatically invoke agents whenever new code repositories or error traces land in Cloud Storage:
+
+```bash
+gcloud eventarc triggers create trace-ingestion-trigger \
+  --location="us-central1" \
+  --destination-run-service="antigravity-agent-service" \
+  --destination-run-region="us-central1" \
+  --destination-run-path="/webhooks/trace-ingest" \
+  --event-filters="type=google.cloud.storage.object.v1.finalized" \
+  --event-filters="bucket=production-failure-traces" \
+  --service-account="eventarc-invoker@my_project.iam.gserviceaccount.com"
+```
+
+---
+
+## 6. NVIDIA L4 GPU Configuration
+
+Accelerate on-container verification models or local embedding calculations:
+
+```bash
+gcloud beta run deploy local-verifier-agent \
+  --image="gcr.io/my_project/verifier-agent-l4:latest" \
+  --region="us-central1" \
+  --cpu=8 \
+  --memory=32Gi \
+  --gpu=1 \
+  --gpu-type=nvidia-l4 \
+  --no-cpu-throttling \
+  --timeout=1800
+```
+
+---
+
+## 7. Enterprise Production Checklist
+
+| Category | Requirement | Verification Method |
+| :--- | :--- | :--- |
+| **IAM Security** | Dedicated service account with least-privilege Vertex AI roles | `roles/aiplatform.user` only; no Owner/Editor permissions |
+| **Secret Management** | Mount API keys directly from Google Secret Manager | Use `--set-secrets`; never bake keys into Docker layers |
+| **Budget Enforcement** | Enforce `--set-env-vars="MAX_USD_BUDGET=..."` bound to `budget-guard` | Verification in PreToolUse hook |
+| **Graceful Shutdown** | Handle `SIGTERM` within 10s to flush ephemeral logs to Cloud Storage | Python `signal.signal(signal.SIGTERM, handler)` |

package/skills/context-warmer/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: context-warmer
+description: Analyzes active repository workspace structure, clusters knowledge items, and pre-warms Gemini prefix context caches (1M-2M+ tokens) before long-running multi-agent invocations.
+---
+
+# Gemini Context Warmer (Prefix Cache Orchestration)
+
+Automates prefix context cache pre-warming for Google Gemini 2.0 and 3.8 models, maximizing cache hit rates, lowering token expenditure by up to 75%, and slashing time-to-first-token (TTFT) from seconds to milliseconds across long-running Antigravity agent loops.
+
+---
+
+## 1. Architectural Strategy
+
+Gemini Context Caching uses **deterministic prefix matching** over an immutable sequence of static tokens. The `context-warmer` skill structures repository knowledge into an optimal cache hierarchy:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ 1. FROZEN PREFIX (Cached via google-genai client.caches.create)             │
+│    ├── System Directives & Security Rules (rules/common/GEMINI.md)          │
+│    ├── Multi-Agent Interaction Protocols (rules/common/AGENTS.md)           │
+│    ├── Repository Structural Map & Dependency Schemas                       │
+│    └── Workspace Knowledge Items (<appDataDir>/knowledge/)                  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ 2. DYNAMIC TURN SUFFIX (Uncached - Sent with each execution turn)           │
+│    ├── Active User Objective & Incremental Task Diff                        │
+│    └── Recent Execution Logs / Transient Subagent Scratchpad                │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Thresholds & Cost Efficiency
+
+| Metric | Non-Cached Gemini Turn | Context-Warmed Prefix Cache | Efficiency Gain |
+| :--- | :--- | :--- | :--- |
+| **Input Cost** | $0.075 / 1M tokens | $0.01875 / 1M tokens | **75% Cost Reduction** |
+| **TTFT Latency** | 2,800ms - 4,500ms | 280ms - 450ms | **10x Faster First Token** |
+| **Minimum Tokens** | 1 token | 32,768 tokens minimum | Optimal at >100k tokens |
+| **Default TTL** | None (ephemeral) | 3,600s (1 hour, auto-refresh) | Sustained across sessions |
+
+---
+
+## 3. Python SDK Cache Warming Implementation
+
+Use the official `google-genai` SDK to construct and warm the persistent prefix cache before orchestrating subagents:
+
+```python
+import os
+from datetime import timedelta
+from google import genai
+from google.genai import types
+
+def prewarm_workspace_cache(
+    workspace_root: str,
+    model: str = "gemini-2.0-flash",
+    ttl_minutes: int = 60
+) -> str:
+    """Scans workspace KIs, builds frozen prefix content, and creates cached content resource."""
+    client = genai.Client()
+
+    # 1. Collate static rules and Knowledge Items (KIs)
+    static_documents = []
+    rules_path = os.path.join(workspace_root, "rules", "common", "GEMINI.md")
+    if os.path.exists(rules_path):
+        with open(rules_path, "r", encoding="utf-8") as f:
+            static_documents.append(f.read())
+
+    # 2. Gather repository knowledge items
+    ki_root = os.path.expanduser("~/.gemini/knowledge")
+    if os.path.exists(ki_root):
+        for root, _, files in os.walk(ki_root):
+            for file in files:
+                if file.endswith((".md", ".json", ".yaml")):
+                    with open(os.path.join(root, file), "r", encoding="utf-8") as f:
+                        static_documents.append(f.read())
+
+    combined_content = "\n\n---\n\n".join(static_documents)
+
+    # 3. Create frozen context cache
+    cache = client.caches.create(
+        model=model,
+        config=types.CreateCachedContentConfig(
+            contents=[types.Content(parts=[types.Part.from_text(combined_content)])],
+            display_name="everything-gemini-workspace-cache",
+            ttl=f"{ttl_minutes * 60}s",
+        )
+    )
+
+    print(f"🔥 Cache Warmed Successfully! Cache Name: {cache.name}")
+    print(f"⏱️  TTL: {ttl_minutes} minutes | Expires at: {cache.expire_time}")
+    return cache.name
+
+def invoke_cached_subagent(cache_name: str, task_prompt: str, model: str = "gemini-2.0-flash"):
+    """Invokes multi-agent query referencing the warmed prefix cache."""
+    client = genai.Client()
+    response = client.models.generate_content(
+        model=model,
+        contents=task_prompt,
+        config=types.GenerateContentConfig(
+            cached_content=cache_name,
+            temperature=0.2,
+        )
+    )
+    return response.text
+```
+
+---
+
+## 4. TypeScript / Node.js Warming Pattern
+
+```typescript
+import { GoogleGenAI } from '@google/genai';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export async function warmPrefixContext(repoRoot: string): Promise<string> {
+  const ai = new GoogleGenAI();
+  const rules = fs.readFileSync(path.join(repoRoot, 'rules', 'common', 'GEMINI.md'), 'utf8');
+
+  const cache = await ai.caches.create({
+    model: 'gemini-2.0-flash',
+    config: {
+      displayName: 'antigravity-repo-cache',
+      ttl: '3600s',
+      contents: [{ role: 'user', parts: [{ text: rules }] }]
+    }
+  });
+
+  return cache.name;
+}
+```
+
+---
+
+## 5. Verification Checklist
+
+- [ ] Static prefix exceeds the minimum 32k token threshold.
+- [ ] No variable nonces, random seeds, or dynamic timestamps are embedded in the static prefix.
+- [ ] Subagent invocations specify `cached_content=cache.name`.
+- [ ] TTL refreshed before expiration for long-running recursive optimization loops.