everything-gemini 2.1.0 → 2.2.0

package/skills/pubsub-event-mesh/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: pubsub-event-mesh
+description: Implements Google Cloud Pub/Sub asynchronous event mesh architectures, exactly-once delivery, dead-letter queues, and schema-validated multi-agent message routing.
+---
+
+# Google Cloud Pub/Sub Multi-Agent Event Mesh
+
+Architects and deploys scalable, decoupled asynchronous messaging pipelines for autonomous multi-agent coordination using Google Cloud Pub/Sub. Covers dead-letter queues (DLQ), exactly-once delivery, schema validation (Protobuf / Avro), and resilient streaming subscribers.
+
+---
+
+## 1. Architecture: Multi-Agent Asynchronous Event Mesh
+
+```
+                     Google Cloud Pub/Sub Event Mesh
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              AGENT WORKFLOW BUS                             │
+│                                                                             │
+│   ┌─────────────────────┐                   ┌───────────────────────────┐   │
+│   │ Subagent Initiator  │                   │ Schema Validator          │   │
+│   │ (e.g. Planner)      │                   │ (Protobuf / Avro Message) │   │
+│   └──────────┬──────────┘                   └─────────────┬─────────────┘   │
+│              │                                            │                 │
+│              ▼                                            ▼                 │
+│       [topic: agent-tasks] ───────────────────────► [topic: agent-tasks]    │
+│              │                                                              │
+│              ├─────────────────────────────┬────────────────────────────┐   │
+│              ▼                             ▼                            ▼   │
+│   ┌──────────────────────┐      ┌──────────────────────┐     ┌──────────┴─┐ │
+│   │ Subscription:        │      │ Subscription:        │     │ DLQ Topic: │ │
+│   │ Code Reviewer Agent  │      │ Security Audit Agent │     │ agent-dlq  │ │
+│   │ (Exactly-Once Ack)   │      │ (Streaming Pull)     │     │ (Max Retries)│
+│   └──────────────────────┘      └──────────────────────┘     └────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Infrastructure Setup (`gcloud`)
+
+Provision an enterprise topic with Dead-Letter Queue (DLQ) isolation and exactly-once delivery:
+
+```bash
+# 1. Create Dead-Letter Queue (DLQ) topic and subscription for failed task events
+gcloud pubsub topics create agent-task-dlq
+gcloud pubsub subscriptions create agent-task-dlq-sub --topic=agent-task-dlq
+
+# 2. Create primary agent task topic
+gcloud pubsub topics create agent-task-bus \
+  --message-retention-duration=7d
+
+# 3. Create consumer subscription with exactly-once delivery and DLQ routing
+gcloud pubsub subscriptions create code-reviewer-sub \
+  --topic=agent-task-bus \
+  --ack-deadline=120 \
+  --enable-exactly-once-delivery \
+  --dead-letter-topic=agent-task-dlq \
+  --max-delivery-attempts=5 \
+  --min-retry-delay=10s \
+  --max-retry-delay=600s
+```
+
+---
+
+## 3. Python Event Mesh Publisher
+
+Publishes structured multi-agent execution events with idempotency ordering keys and tracing attributes:
+
+```python
+import json
+import uuid
+from google.cloud import pubsub_v1
+
+publisher = pubsub_v1.PublisherClient()
+topic_path = publisher.topic_path("my_project", "agent-task-bus")
+
+def publish_agent_task(
+    task_id: str,
+    target_agent: str,
+    payload: dict,
+    correlation_id: str = None
+) -> str:
+    """Publishes an agent task with ordering key and strict metadata tags."""
+    correlation_id = correlation_id or str(uuid.uuid4())
+    
+    message_data = json.dumps({
+        "taskId": task_id,
+        "targetAgent": target_agent,
+        "payload": payload,
+        "timestamp": "2026-10-21T11:00:00Z"
+    }).encode("utf-8")
+
+    # Publish with attributes for server-side subscription filtering
+    future = publisher.publish(
+        topic_path,
+        data=message_data,
+        target_agent=target_agent,
+        correlation_id=correlation_id,
+        ordering_key=task_id  # Ensures sequential processing for the same task
+    )
+    
+    message_id = future.result()
+    print(f"🚀 Published task {task_id} to Pub/Sub (Msg ID: {message_id})")
+    return message_id
+```
+
+---
+
+## 4. Streaming Pull Subscriber with Backpressure
+
+Consumes tasks asynchronously, processes execution via subagents, and deterministically acknowledges messages:
+
+```python
+from google.cloud import pubsub_v1
+import time
+
+subscriber = pubsub_v1.SubscriberClient()
+sub_path = subscriber.subscription_path("my_project", "code-reviewer-sub")
+
+def callback(message: pubsub_v1.subscriber.message.Message):
+    print(f"📥 Received task event: {message.message_id}")
+    task_payload = json.loads(message.data.decode("utf-8"))
+    
+    try:
+        # Execute agent task logic
+        print(f"🤖 Processing task for {task_payload.get('targetAgent')}...")
+        # (Invoke subagent logic here)
+        
+        # Acknowledge receipt upon successful execution
+        message.ack()
+        print(f"✅ Successfully acknowledged message {message.message_id}")
+    except Exception as exc:
+        print(f"❌ Task processing failed: {exc}")
+        # Negative acknowledgment triggers retry / DLQ forwarding
+        message.nack()
+
+# Configure flow control to prevent memory exhaustion during spikes
+flow_control = pubsub_v1.types.FlowControl(
+    max_messages=10,
+    max_bytes=50 * 1024 * 1024  # 50MB
+)
+
+streaming_pull = subscriber.subscribe(
+    sub_path,
+    callback=callback,
+    flow_control=flow_control
+)
+
+print(f"🎧 Listening for agent tasks on {sub_path}...")
+try:
+    streaming_pull.result()
+except KeyboardInterrupt:
+    streaming_pull.cancel()
+```
+
+---
+
+## 5. Subscription-Level Filtering
+
+Avoid spinning up unnecessary subagents by filtering messages at the Pub/Sub server level:
+
+```bash
+# Create subscription that ONLY receives tasks addressed to 'security-auditor'
+gcloud pubsub subscriptions create security-auditor-sub \
+  --topic=agent-task-bus \
+  --message-filter='attributes.target_agent = "security-auditor"' \
+  --enable-exactly-once-delivery
+```
+
+---
+
+## 6. Resilience & Anti-Patterns Checklist
+
+| Category | Recommended Pattern | Anti-Pattern |
+| :--- | :--- | :--- |
+| **Delivery Guarantee** | Enable `--enable-exactly-once-delivery` for state mutation events | Using default at-least-once for irreversible codebase commits |
+| **Dead Lettering** | Always bind `--dead-letter-topic` with `--max-delivery-attempts=5` | Infinite retry loops crashing worker containers on poisoned tasks |
+| **Flow Control** | Restrict concurrent in-flight messages with `FlowControl(max_messages=10)` | Unbounded pulling leading to OOM kills during burst invocations |
+| **Ordering** | Use `ordering_key` when tasks depend on prerequisite steps | Random partition dispatch causing out-of-order build/deploy tasks |

package/skills/spanner-graph-rag/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: spanner-graph-rag
+description: Implements Google Cloud Spanner Graph schemas, ISO GQL queries, knowledge graph traversal, and hybrid graph-vector RAG pipelines for Gemini agents.
+---
+
+# Spanner Graph & Knowledge Graph RAG
+
+Designs, provisions, and queries distributed enterprise knowledge graphs using Google Cloud Spanner Graph. Implements ISO GQL (Graph Query Language) multi-hop traversals, cyclic graph pattern matching, and hybrid Graph-Vector RAG to eliminate hallucinations across complex organizational entity networks.
+
+---
+
+## 1. Architecture: Graph-Grounded Agentic Reasoning
+
+```
+                                Google Cloud Spanner
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       SPANNER DISTRIBUTED GRAPH ENGINE                      │
+│                                                                             │
+│   ┌─────────────────────┐                   ┌───────────────────────────┐   │
+│   │ Node Table: Account │                   │ Node Table: Microservice  │   │
+│   │ (Enterprise Org)    │                   │ (Infrastructure Artifact) │   │
+│   └──────────┬──────────┘                   └─────────────┬─────────────┘   │
+│              │                                            │                 │
+│              │       Edge: OWNS             Edge: CALLS   │                 │
+│              └────────────────► [TEAM] ───────────────────┘                 │
+│                                   │                                         │
+│                                   ▼                                         │
+│                    ┌─────────────────────────────┐                          │
+│                    │ Edge: MUTATES_RESOURCE      │                          │
+│                    │ Destination: Cloud Database │                          │
+│                    └──────────────┬──────────────┘                          │
+│                                   │                                         │
+│                                   ▼                                         │
+│            ┌───────────────────────────────────────────────┐                │
+│            │ ISO GQL Multi-Hop Graph Traversal             │                │
+│            │ MATCH (t:Team)-[:CALLS*1..3]->(m:Service)     │                │
+│            └──────────────────────┬────────────────────────┘                │
+│                                   │ Grounded Entity Context                 │
+│                                   ▼                                         │
+│            ┌───────────────────────────────────────────────┐                │
+│            │ Gemini 2.0 / 3.8 Reasoning & Action Engine    │                │
+│            │ Zero hallucination on architectural blast radius│               │
+│            └───────────────────────────────────────────────┘                │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Spanner Graph DDL (`CREATE PROPERTY GRAPH`)
+
+Define nodes, edges, and relationship labels on top of strongly consistent Spanner tables:
+
+```sql
+-- 1. Base Relational Tables
+CREATE TABLE Services (
+  service_id STRING(64) NOT NULL,
+  name STRING(128) NOT NULL,
+  tier STRING(32) NOT NULL,
+  owner_team STRING(64) NOT NULL,
+  created_at TIMESTAMP OPTIONS (allow_commit_timestamp = true)
+) PRIMARY KEY (service_id);
+
+CREATE TABLE Dependencies (
+  caller_id STRING(64) NOT NULL,
+  target_id STRING(64) NOT NULL,
+  protocol STRING(32) NOT NULL,
+  criticality STRING(16) NOT NULL,
+  CONSTRAINT FK_Caller FOREIGN KEY (caller_id) REFERENCES Services (service_id),
+  CONSTRAINT FK_Target FOREIGN KEY (target_id) REFERENCES Services (service_id)
+) PRIMARY KEY (caller_id, target_id);
+
+-- 2. Property Graph Definition (ISO GQL Standard)
+CREATE PROPERTY GRAPH ServiceArchitectureGraph
+  VERTEX TABLES (
+    Services
+      LABEL Service
+      PROPERTIES (service_id, name, tier, owner_team)
+  )
+  EDGE TABLES (
+    Dependencies
+      SOURCE KEY (caller_id) REFERENCES Services (service_id)
+      DESTINATION KEY (target_id) REFERENCES Services (service_id)
+      LABEL CALLS
+      PROPERTIES (protocol, criticality)
+  );
+```
+
+---
+
+## 3. ISO GQL Graph Traversal Queries
+
+Execute declarative graph pattern matching directly in Spanner SQL:
+
+```sql
+-- Multi-hop blast-radius query: Find all downstream services impacted by an outage
+GRAPH ServiceArchitectureGraph
+MATCH (root:Service {service_id: 'payment-gateway'})
+      -[:CALLS*1..3]-> (downstream:Service)
+WHERE downstream.tier = 'TIER_1'
+RETURN DISTINCT
+  root.name AS failing_service,
+  downstream.name AS impacted_dependency,
+  downstream.owner_team AS oncall_team;
+```
+
+---
+
+## 4. Python SDK Graph-Vector RAG Pipeline
+
+Combines topological graph queries with Gemini reasoning to assess infrastructure change risk:
+
+```python
+from google.cloud import spanner
+from google import genai
+
+spanner_client = spanner.Client()
+instance = spanner_client.instance("production-instance")
+database = instance.database("architecture-db")
+gemini_client = genai.Client()
+
+def analyze_architectural_blast_radius(failing_service_id: str) -> str:
+    """Executes ISO GQL query in Spanner Graph and reasons over downstream risks with Gemini."""
+    gql_query = """
+    GRAPH ServiceArchitectureGraph
+    MATCH (s:Service {service_id: @serviceId})-[e:CALLS*1..4]->(dep:Service)
+    RETURN DISTINCT s.name AS root_service, dep.name AS dependency, dep.tier AS tier, dep.owner_team AS team
+    """
+    
+    with database.snapshot() as snapshot:
+        results = list(snapshot.execute_sql(
+            gql_query,
+            params={"serviceId": failing_service_id},
+            param_types={"serviceId": spanner.param_types.STRING}
+        ))
+    
+    # Format graph path topology into structured context
+    graph_context = "\n".join([
+        f"- Dependency: {row[1]} (Tier: {row[2]}, Team: {row[3]})"
+        for row in results
+    ])
+    
+    # Reason with Gemini using strictly grounded graph topology
+    prompt = f"""
+    The following microservice is experiencing an outage: {failing_service_id}
+    Here is the verified dependency graph topology from Spanner Graph:
+    {graph_context}
+    
+    Provide an actionable incident response triage plan, identifying on-call escalations.
+    """
+    
+    response = gemini_client.models.generate_content(
+        model="gemini-2.0-flash",
+        contents=prompt
+    )
+    return response.text
+```
+
+---
+
+## 5. Enterprise Best Practices & Anti-Patterns
+
+| Category | Recommended Pattern | Anti-Pattern |
+| :--- | :--- | :--- |
+| **Topology Modeling** | Use Directed Property Graphs with foreign keys enforcing referential integrity | Storing graph edges in unindexed JSON arrays |
+| **Path Search Depth** | Bound variable-length path traversals (e.g. `[:CALLS*1..4]`) | Unbounded path queries (`[:CALLS*]`) causing exponential scans |
+| **Hybrid RAG** | Retrieve exact entity graph topology from Spanner before prompt construction | Letting LLMs guess multi-hop dependencies from vector embeddings alone |
+| **Transactions** | Execute read-only graph traversals inside Spanner read-only snapshots | Mixing long-running graph analyses into interactive read-write transactions |

package/tests/cli.test.js

@@ -90,10 +90,10 @@ it('should benchmark ecosystem components and output valid JSON with --json', ()
   const res = runCli('benchmark --json');
   assert.strictEqual(res.status, 0);
   const data = JSON.parse(res.stdout);
-  assert.strictEqual(data.totalComponents, 84);
-  assert.strictEqual(data.progressiveSkillsCount, 63);
+  assert.strictEqual(data.totalComponents, 90);
+  assert.strictEqual(data.progressiveSkillsCount, 68);
   assert.strictEqual(data.scopedAgentsCount, 13);
-  assert.strictEqual(data.lifecycleHooksCount, 8);
+  assert.strictEqual(data.lifecycleHooksCount, 9);
   assert(data.totalRunbookTokens > 15000, 'Expected >15,000 runbook tokens');
   assert(data.estimatedTokensSavedPerTurn > 8000, 'Expected significant token savings');
 });
@@ -316,7 +316,7 @@ try {
     const dryRes = runCli(`bundle --output "${bundleTarget}" --dry-run`);
     assert.strictEqual(dryRes.status, 0);
     assert.match(dryRes.stdout, /DRY RUN MODE ACTIVATED/);
-    assert.match(dryRes.stdout, /Skills to bundle: 63/);
+    assert.match(dryRes.stdout, /Skills to bundle: 68/);
     assert.strictEqual(fs.existsSync(bundleTarget), false, 'Dry run should not create destination directory');
 
     // JSON Dry-run mode
@@ -324,7 +324,7 @@ try {
     assert.strictEqual(jsonRes.status, 0);
     const dryData = JSON.parse(jsonRes.stdout);
     assert.strictEqual(dryData.dryRun, true);
-    assert.strictEqual(dryData.manifest.components.totalCount, 84);
+    assert.strictEqual(dryData.manifest.components.totalCount, 90);
 
     // Live mode
     const liveRes = runCli(`bundle --output "${bundleTarget}"`);
@@ -477,9 +477,9 @@ try {
     assert.strictEqual(jsonRes.status, 0);
     const dryData = JSON.parse(jsonRes.stdout);
     assert.strictEqual(dryData.dryRun, true);
-    assert.strictEqual(dryData.manifest.metrics.total_skills, 63);
+    assert.strictEqual(dryData.manifest.metrics.total_skills, 68);
     assert.strictEqual(dryData.manifest.metrics.total_subagents, 13);
-    assert.strictEqual(dryData.manifest.metrics.total_hooks, 8);
+    assert.strictEqual(dryData.manifest.metrics.total_hooks, 9);
 
     // Live mode
     const liveRes = runCli(`harness2 "${h2Target}"`);
@@ -524,14 +524,14 @@ try {
   });
 
   // Benchmark Components Verification
-  it('should report 84 components, 63 skills, and 13 subagents in benchmark --json', () => {
+  it('should report 90 components, 68 skills, and 13 subagents in benchmark --json', () => {
     const res = runCli('benchmark --json');
     assert.strictEqual(res.status, 0);
     const data = JSON.parse(res.stdout);
-    assert.strictEqual(data.totalComponents, 84, 'Total components should be 84');
-    assert.strictEqual(data.progressiveSkillsCount, 63, 'Progressive skills should be 63');
+    assert.strictEqual(data.totalComponents, 90, 'Total components should be 90');
+    assert.strictEqual(data.progressiveSkillsCount, 68, 'Progressive skills should be 68');
     assert.strictEqual(data.scopedAgentsCount, 13, 'Scoped agents should be 13');
-    assert.strictEqual(data.lifecycleHooksCount, 8, 'Lifecycle hooks should be 8');
+    assert.strictEqual(data.lifecycleHooksCount, 9, 'Lifecycle hooks should be 9');
   });
 
   // Harness² Run & Ingest-Trace tests
@@ -583,6 +583,25 @@ try {
     assert.match(res.stdout, /PreToolUse/);
   });
 
+  it('should display info for context-warmer skill and human-gate hook', () => {
+    const resSkill = runCli('info context-warmer');
+    assert.strictEqual(resSkill.status, 0);
+    assert.match(resSkill.stdout, /context-warmer/);
+
+    const resHook = runCli('info human-gate');
+    assert.strictEqual(resHook.status, 0);
+    assert.match(resHook.stdout, /human-gate/);
+    assert.match(resHook.stdout, /PreToolUse/);
+  });
+
+  it('should display info for v2.2.0 skills (bigquery-vector-search, cloud-run-agents, pubsub-event-mesh, spanner-graph-rag)', () => {
+    for (const skill of ['bigquery-vector-search', 'cloud-run-agents', 'pubsub-event-mesh', 'spanner-graph-rag']) {
+      const res = runCli(`info ${skill}`);
+      assert.strictEqual(res.status, 0);
+      assert.match(res.stdout, new RegExp(skill));
+    }
+  });
+
 } finally {
   try {
     fs.rmSync(tempWorkspace, { recursive: true, force: true });