everything-gemini 2.2.0 → 2.7.0

package/skills/ebpf-microvm-sandbox/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: ebpf-microvm-sandbox
+description: Enforces rootless ephemeral Micro-VM isolation, Linux Landlock filesystem jails, and Cilium eBPF network filtering for zero-trust speculative tool and code execution.
+---
+
+# eBPF Micro-VM Sandbox (`ebpf-microvm-sandbox`)
+
+Provides kernel-enforced rootless ephemeral Micro-VM isolation (Firecracker and gVisor), Linux Landlock path jails, seccomp-bpf syscall filtering, and Cilium eBPF network security for untrusted, speculative tool execution in Google Antigravity and Gemini agent loops.
+
+---
+
+## 1. Architectural Model: Kernel-Enforced Isolation Hierarchy
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    ZERO-TRUST AGENT SANDBOX RUNTIME                         │
+│                                                                             │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 1. Antigravity Agent Runtime (Host Process)                         │   │
+│   │    • Speculative tool proposal (e.g. `run_command`, `eval_python`)  │   │
+│   │    • Intercepted by PreToolUse Lifecycle Security Hook              │   │
+│   └──────────────────────────────────┬──────────────────────────────────┘   │
+│                                      │                                      │
+│                                      ▼                                      │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 2. OPA Policy Gatekeeper & Sandbox Dispatcher                       │   │
+│   │    • Validates command safety signature and environment constraints │   │
+│   │    • Allocates ephemeral rootless micro-VM workspace                │   │
+│   └──────────────────────────────────┬──────────────────────────────────┘   │
+│                                      │                                      │
+│                                      ▼                                      │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 3. Ephemeral Micro-VM Jail (Firecracker / gVisor runsc)              │   │
+│   │    ┌────────────────────────────────────────────────────────────┐   │   │
+│   │    │ A. Filesystem: Linux Landlock V4 ephemeral copy-on-write   │   │   │
+│   │    │    • Host files outside sandbox mounted READ-ONLY          │   │   │
+│   │    │    • Temp workdir deleted on tool completion               │   │   │
+│   │    ├────────────────────────────────────────────────────────────┤   │   │
+│   │    │ B. Syscalls: Strict Seccomp-BPF whitelist filter           │   │   │
+│   │    │    • Blocks ptrace, mount, bpf, reboot, setuid, unshare    │   │   │
+│   │    ├────────────────────────────────────────────────────────────┤   │   │
+│   │    │ C. Network: Cilium eBPF Socket Filtering & Egress Policy   │   │   │
+│   │    │    • Strict CIDR whitelist (e.g. npmjs, pypi, googleapis)  │   │   │
+│   │    │    • Blocks RFC 1918 internal subnets & cloud metadata IPs │   │   │
+│   │    └────────────────────────────────────────────────────────────┘   │   │
+│   └──────────────────────────────────┬──────────────────────────────────┘   │
+│                                      │                                      │
+│                                      ▼                                      │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 4. Execution Telemetry & Differential Sync                          │   │
+│   │    • Captured stdout, stderr, exit code, and modified file diffs    │   │
+│   │    • Automatic rollback on policy violation or timeout abort        │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Kernel Security Primitives
+
+### A. Linux Landlock V4 Path Rules
+- Speculative tools receive scoped path access:
+  - `LANDLOCK_ACCESS_FS_READ`: Allowed on workspace root.
+  - `LANDLOCK_ACCESS_FS_WRITE`: Confined strictly to `/tmp/agent-sandbox/<execution-id>`.
+  - Sensitive paths (`~/.ssh`, `~/.aws`, `~/.config/gcloud`, `/etc/shadow`) are masked with empty dummy inodes.
+
+### B. Seccomp-BPF Syscall Restriction
+- The sandbox enforces an allow-list BPF program at `execve`:
+  ```text
+  ALLOWED: read, write, openat, close, fstat, lseek, mmap, mprotect, munmap, brk, exit_group
+  DENIED (SIGKILL): ptrace, process_vm_readv, init_module, kexec_load, bpf, clone(NEWUSER)
+  ```
+
+### C. Cilium eBPF Network Quarantine
+- Egress is strictly blocked to Cloud Metadata Endpoints:
+  - `169.254.169.254/32` (AWS/GCP Instance Metadata Service)
+  - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` (Internal LAN)
+- Only TLS port 443 egress to explicit DNS-validated dependency endpoints is permitted.
+
+---
+
+## 3. Operational Recipes
+
+### Launching an Isolated Speculative Command
+```bash
+# Verify sandbox status and host kernel security primitives
+everything-gemini doctor --profile full
+
+# Run speculative untrusted build in micro-VM jail
+everything-gemini resilience inject --target "speculative-build" --sandbox microvm
+```
+
+### Landlock Python Runner Pattern
+```python
+from google_antigravity.security import EphemeralMicroVMSandbox
+
+with EphemeralMicroVMSandbox(
+    memory_mb=512,
+    cpu_limit=1.0,
+    allow_network=False,
+    timeout_sec=30
+) as sandbox:
+    result = sandbox.exec(["python3", "-c", "import os; print(os.listdir('.'))"])
+    print(f"Sandbox Exit Code: {result.exit_code}")
+    print(f"Sandbox Output: {result.stdout}")
+```
+
+---
+
+## 4. Cross-Reference & Links
+- See [skills/ebpf-sandbox-enforcer/SKILL.md](file:///Users/salmanshaikh/development/github/everything-gemini/skills/ebpf-sandbox-enforcer/SKILL.md) for Landlock baseline rules.
+- See [skills/opa-gatekeeper-policy/SKILL.md](file:///Users/salmanshaikh/development/github/everything-gemini/skills/opa-gatekeeper-policy/SKILL.md) for OPA policy syntax.
+- See [agents/security-auditor.md](file:///Users/salmanshaikh/development/github/everything-gemini/agents/security-auditor.md) for automated vulnerability auditing.

package/skills/ebpf-sandbox-enforcer/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: ebpf-sandbox-enforcer
+description: Enforces zero-trust rootless micro-VM and eBPF kernel security boundaries for speculative agent tool executions and container sandboxes.
+---
+
+# eBPF Sandbox Enforcer & Zero-Trust Tool Isolation
+
+Implements kernel-level zero-trust security isolation, rootless micro-VM sandboxing, Landlock filesystem restriction, and Cilium eBPF network filtering for speculative agent tool executions within Google Antigravity and Everything Gemini workflows.
+
+---
+
+## 1. Architecture: Kernel-Level Agent Sandboxing
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                   KERNEL-LEVEL AGENT SECURITY BOUNDARY                      │
+│                                                                             │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ Speculative Agent Tool Execution (`run_command`, `write_to_file`)   │   │
+│   └──────────────────────────────────┬──────────────────────────────────┘   │
+│                                      │                                      │
+│                                      ▼                                      │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 1. User-Space Policy Interceptor (`gemini-shield` & OPA Rego)       │   │
+│   │    • Validates command AST, blocks `rm -rf`, detects token leakages │   │
+│   └──────────────────────────────────┬──────────────────────────────────┘   │
+│                                      │                                      │
+│                                      ▼                                      │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 2. Linux Landlock & Seccomp-BPF Syscall Filter                      │   │
+│   │    • Traps unauthorized `execve`, `ptrace`, `setuid`, and `chroot`  │   │
+│   │    • Restricts filesystem I/O strictly to isolated `./scratch/` dir │   │
+│   └──────────────────────────────────┬──────────────────────────────────┘   │
+│                                      │                                      │
+│                                      ▼                                      │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 3. Cilium eBPF Socket Filter (L3/L4/L7 Network Egress)             │   │
+│   │    • Blocks outbound internet access to non-whitelisted IPs         │   │
+│   │    • Allows Google Cloud APIs (`*.googleapis.com`) on TLS 443      │   │
+│   │    • Drops all lateral movement probes to internal Kubernetes pods  │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Kernel Enforcement Mechanisms
+
+### A. Landlock Filesystem Sandboxing
+Speculative agent mutations are restricted to the local workspace directory or an ephemeral scratch area. System directories (`/etc`, `/usr`, `/root`, `~/.ssh`) are marked strictly `LANDLOCK_ACCESS_FS_READ` or completely denied:
+
+```c
+// Example Landlock ruleset structure for agent tool sandbox
+#include <linux/landlock.h>
+#include <sys/prctl.h>
+
+int enforce_agent_landlock(const char *allowed_dir) {
+    int ruleset_fd = landlock_create_ruleset(&ruleset_attr, sizeof(ruleset_attr), 0);
+    // Add rule: allowed_dir gets read/write/truncate/execute
+    // System directories remain read-only or inaccessible
+    prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0);
+    landlock_restrict_self(ruleset_fd, 0);
+    return 0;
+}
+```
+
+### B. Cilium eBPF Network Security Policy (CNP)
+Prevents data exfiltration or reverse shells when the agent runs third-party build scripts or untrusted dependencies:
+
+```yaml
+apiVersion: "cilium.io/v2"
+kind: CiliumNetworkPolicy
+metadata:
+  name: "agent-tool-sandbox-egress"
+spec:
+  endpointSelector:
+    matchLabels:
+      role: "autonomous-agent-worker"
+  egress:
+    - toFQDNs:
+        - matchPattern: "*.googleapis.com"
+        - matchName: "github.com"
+      toPorts:
+        - ports:
+            - port: "443"
+              protocol: TCP
+    - toEntities:
+        - cluster
+      toPorts:
+        - ports:
+            - port: "53"
+              protocol: UDP
+```
+
+---
+
+## 3. Best Practices & Isolation Checklist
+
+1. **Rootless Execution**: Never execute autonomous agent commands as `root` (UID 0). Always run inside an unprivileged user namespace (`UID 10001`).
+2. **Ephemeral Disks**: Speculative test runs must target tmpfs or overlayfs volumes that can be unmounted and discarded in $<100\text{ms}$.
+3. **Audit Telemetry**: Feed eBPF syscall audit logs (`bpftool prog tracelog`) into the Mission Control UI to detect anomalous fork storms or socket scans.

package/skills/envoy-ai-gateway/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: envoy-ai-gateway
+description: Configure and deploy Envoy Proxy AI Gateway for Gemini models with token-aware rate limiting, multi-model circuit breakers, active health checks, and zero-trust mTLS termination.
+---
+
+# Envoy Proxy AI Gateway (Multi-Model Traffic Director & Circuit Breaking)
+
+Deploys and configures high-performance Envoy Proxy AI Gateways tailored for Google Gemini APIs and autonomous agent clusters. Provides token-aware rate limiting, active health checking, automatic circuit breaking across Gemini Flash, Pro, and Extended Thinking tiers, and zero-trust mTLS proxying.
+
+---
+
+## 1. AI Gateway Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          ENVOY PROXY AI GATEWAY                             │
+│                                                                             │
+│   Agent Workflows (gRPC / HTTPS)                                            │
+│                 │                                                           │
+│                 ▼                                                           │
+│   ┌───────────────────────────┐                                             │
+│   │ Envoy Proxy AI Gateway    │◄──── Token-Aware Rate Limiter (Redis)       │
+│   │ (Filter Chain & Router)   │◄──── W3C Tracecontext Injector              │
+│   └─────────────┬─────────────┘                                             │
+│                 │                                                           │
+│                 ├── 90% Primary Route ──► Gemini 2.0 Flash (Fast Tool Use)  │
+│                 │                                                           │
+│                 ├── Circuit Broken?  ──► Gemini 3.8 Pro (Fallback Tier)     │
+│                 │                                                           │
+│                 └── High Complexity? ──► Gemini 3.8 Thinking (Extended)     │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Envoy Proxy Configuration (`envoy.yaml`)
+
+Below is the production Envoy proxy configuration routing requests to Google Gemini with outlier detection, retry backoff, and local rate limiting:
+
+```yaml
+static_resources:
+  listeners:
+  - name: gemini_ingress_listener
+    address:
+      socket_address:
+        address: 0.0.0.0
+        port_value: 8443
+    filter_chains:
+    - transport_socket:
+        name: envoy.transport_sockets.tls
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
+          common_tls_context:
+            tls_certificates:
+            - certificate_chain: { filename: "/etc/envoy/certs/server.crt" }
+              private_key: { filename: "/etc/envoy/certs/server.key" }
+      filters:
+      - name: envoy.filters.network.http_connection_manager
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+          stat_prefix: ingress_gemini
+          route_config:
+            name: gemini_api_routes
+            virtual_hosts:
+            - name: gemini_service
+              domains: ["*"]
+              routes:
+              - match:
+                  prefix: "/v1beta/models/gemini-2.0-flash"
+                route:
+                  cluster: gemini_api_upstream
+                  timeout: 10s
+                  retry_policy:
+                    retry_on: "5xx,connect-failure,refused-stream,429"
+                    num_retries: 3
+                    retry_back_off:
+                      base_interval: 250ms
+                      max_interval: 2s
+              - match:
+                  prefix: "/v1beta/models/gemini-3.8-thinking"
+                route:
+                  cluster: gemini_api_upstream
+                  timeout: 60s
+          http_filters:
+          - name: envoy.filters.http.local_ratelimit
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
+              stat_prefix: http_local_rate_limiter
+              token_bucket:
+                max_tokens: 1000
+                tokens_per_fill: 100
+                fill_interval: 1s
+              filter_enabled:
+                default_value: { numerator: 100, denominator: HUNDRED }
+              filter_enforced:
+                default_value: { numerator: 100, denominator: HUNDRED }
+          - name: envoy.filters.http.router
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+
+  clusters:
+  - name: gemini_api_upstream
+    type: LOGICAL_DNS
+    dns_lookup_family: V4_ONLY
+    connect_timeout: 2s
+    lb_policy: ROUND_ROBIN
+    circuit_breakers:
+      thresholds:
+      - priority: DEFAULT
+        max_connections: 500
+        max_pending_requests: 100
+        max_requests: 1000
+        max_retries: 3
+    outlier_detection:
+      consecutive_5xx: 3
+      interval: 10s
+      base_ejection_time: 30s
+      max_ejection_percent: 50
+    load_assignment:
+      cluster_name: gemini_api_upstream
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: generativelanguage.googleapis.com
+                port_value: 443
+    transport_socket:
+      name: envoy.transport_sockets.tls
+      typed_config:
+        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
+        sni: generativelanguage.googleapis.com
+```
+
+---
+
+## 3. Kubernetes Deployment Manifest
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: envoy-gemini-gateway
+  namespace: agent-runtime
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: envoy-gemini-gateway
+  template:
+    metadata:
+      labels:
+        app: envoy-gemini-gateway
+    spec:
+      containers:
+      - name: envoy
+        image: envoyproxy/envoy:v1.31-latest
+        ports:
+        - containerPort: 8443
+        volumeMounts:
+        - name: envoy-config
+          mountPath: /etc/envoy
+      volumes:
+      - name: envoy-config
+        configMap:
+          name: envoy-gemini-config
+```
+
+---
+
+## 4. Key Performance Indicators & Metrics
+
+- **Ejection Rate (`envoy.cluster.outlier_detection.ejections_enforced`)**: Alerts on sustained API throttling.
+- **Circuit Breakers (`envoy.cluster.circuit_breakers.default.rq_open`)**: Triggers immediate failover to backup model tiers.
+- **P99 Proxy Overhead**: Sub-1.5ms added latency across TLS handshake and routing filters.

package/skills/ephemeral-swarm-orchestrator/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: ephemeral-swarm-orchestrator
+description: Dynamically synthesizes, deploys, and reclaims ephemeral multi-agent swarms for cross-repository parallel refactoring and consensus aggregation.
+---
+
+# Ephemeral Swarm Orchestrator (Swarm Intelligence)
+
+Implements dynamic on-demand synthesis, parallel task decomposition, distributed cross-repository execution, consensus aggregation, and lifecycle reclamation of ephemeral micro-agent swarms for Google Gemini and Antigravity.
+
+---
+
+## 1. Architecture: Dynamic Ephemeral Micro-Agent Swarm
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                   EPHEMERAL SWARM ORCHESTRATION PIPELINE                    │
+│                                                                             │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 1. Swarm Coordinator & Planner Decomposition                        │   │
+│   │    • Complex multi-repo goal or massive refactor prompt              │   │
+│   │    • Decomposed into DAG of atomic micro-tasks with input contracts  │   │
+│   └──────────────────────────────────┬──────────────────────────────────┘   │
+│                                      │                                      │
+│                                      ▼                                      │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 2. Dynamic Ephemeral Specialist Synthesis                           │   │
+│   │    • Synthesizes targeted micro-agent definitions in memory          │   │
+│   │    • E.g. `spanner-deadlock-tuner`, `grpc-schema-validator`          │   │
+│   │    • Mounts minimal progressive skills & scoped tool permissions    │   │
+│   └──────────────────────────────────┬──────────────────────────────────┘   │
+│                                      │                                      │
+│                                      ▼                                      │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 3. Parallel Worker Swarm Execution (Pub/Sub & Cloud Run Jobs)       │   │
+│   │    ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐ │   │
+│   │    │ Worker #1 (RepoA)│  │ Worker #2 (RepoB)│  │ Worker #3 (Infra)│ │   │
+│   │    └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘ │   │
+│   └─────────────┼─────────────────────┼─────────────────────┼───────────┘   │
+│                 └─────────────────────┼─────────────────────┘               │
+│                                       ▼                                     │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 4. Majority Consensus & Multi-Agent Voting                          │   │
+│   │    • Aggregates diff proposals across parallel micro-agents         │   │
+│   │    • Conflict resolution via Byzantine/majority agreement matrix   │   │
+│   └──────────────────────────────────┬──────────────────────────────────┘   │
+│                                      │                                      │
+│                                      ▼                                      │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ 5. Ephemeral Harness Teardown & Lifecycle Reclamation               │   │
+│   │    • Verifies property-based unit & integration tests               │   │
+│   │    • Distills learned instincts into persistent memory              │   │
+│   │    • Decommissions worker contexts and purges memory state          │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Core Operational Pillars
+
+### A. Dynamic Specialist Synthesis
+Traditional multi-agent frameworks rely on rigid, static subagent registries. The Ephemeral Swarm Orchestrator dynamically constructs targeted agent personalities and tool contracts based on task requirements:
+
+```json
+{
+  "swarm_id": "swarm-20261022-spanner-sync",
+  "coordinator": "swarm-coordinator",
+  "topology": "hierarchical",
+  "workers": [
+    {
+      "id": "worker-schema-evaluator",
+      "specialization": "spanner-ddl-auditor",
+      "scoped_skills": ["spanner-change-streams", "security-audit"],
+      "permitted_tools": ["view_file", "grep_search", "run_command"],
+      "token_budget": 8000
+    },
+    {
+      "id": "worker-migration-author",
+      "specialization": "liquibase-migration-writer",
+      "scoped_skills": ["database-migrator", "tdd-workflow"],
+      "permitted_tools": ["write_to_file", "replace_file_content", "run_command"],
+      "token_budget": 12000
+    }
+  ]
+}
+```
+
+### B. Consensus & Voting Protocol
+When multiple micro-agents generate speculative patches or architectural proposals, the swarm coordinator invokes a multi-agent voting round:
+1. **P2P Cross-Verification**: Worker 1 reviews Worker 2's AST patch.
+2. **Deterministic Test Execution**: Candidate diffs are executed against property-based tests in isolated ephemeral directories.
+3. **Quorum Verification**: A change requires $\ge 67\%$ consensus agreement before promotion into the primary branch.
+
+### C. Resource Reclamation & Zero Leaks
+Upon completion or failure, the swarm executor executes cleanup routines:
+* Terminates background worker processes and subprocess handles.
+* Deletes scratch directories and temporary SQLite / DuckDB scratchpads.
+* Commits learned operational invariants into `.agents/hooks/learned-instincts/`.
+
+---
+
+## 3. CLI Commands
+
+```bash
+# 1. Spawn an ephemeral swarm with 3 parallel workers
+everything-gemini swarm spawn "refactor auth middleware to zero-trust mTLS" --workers 3
+
+# 2. Inspect active swarm topology and worker state
+everything-gemini swarm status --json
+
+# 3. Force teardown and reclaim all active worker resources
+everything-gemini swarm reclaim --dry-run
+```
+
+---
+
+## 4. Anti-Patterns & Safety Guardrails
+
+| Anti-Pattern | Operational Risk | Swarm Enforced Fix |
+| :--- | :--- | :--- |
+| **Unbounded Worker Spawning** | Exponential token burn and process fork bomb | Hard worker ceiling (`--max-workers 8`) enforced by `budget-guard`. |
+| **Shared State Collisions** | Merge conflicts and dirty git tree states | Each worker operates in an isolated temporary worktree with git rollback snapshots. |
+| **Zombie Subagents** | Orphaned background processes leaking memory | Mandatory timeout watchdog (`--timeout-sec 300`) with auto-reclamation. |
+| **Single-Agent Bias** | Hallucinated code passes without review | Two-agent peer verification required on all synthesized diffs. |

package/skills/gemini-live-multimodal/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: gemini-live-multimodal
+description: Implements real-time bidirectional streaming audio and video pair-programming with the Gemini Live API, WebSocket protocols, ephemeral tokens, and voice activity detection.
+---
+
+# Gemini Live Multimodal (Bidirectional Audio/Visual Streaming)
+
+Implements real-time, low-latency, bidirectional audio/video interaction with Google Gemini models (Gemini 2.0 Flash and Gemini Live) using WebSockets, Ephemeral Client Tokens, Voice Activity Detection (VAD), and live screen/DOM streaming.
+
+---
+
+## 1. Architecture: Bidirectional Gemini Live API
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                             GEMINI LIVE RUNTIME                             │
+│                                                                             │
+│   ┌─────────────────────┐   Audio (PCM 16kHz)   ┌─────────────────────────┐ │
+│   │ Developer Audio     │──────────────────────►│ Google GenAI Live API   │ │
+│   │ (Microphone Input)  │                       │ (wss://generativelanguage│ │
+│   └─────────────────────┘                       │  .googleapis.com/ws)    │ │
+│                                                 │                         │ │
+│   ┌─────────────────────┐   Frames (JPEG/WebP)  │ • Voice Activity Detect │ │
+│   │ Active Screen / IDE │──────────────────────►│ • Extended Reasoning    │ │
+│   │ (Visual Context)    │                       │ • Sub-second TTFT Voice │ │
+│   └─────────────────────┘                       └───────────┬─────────────┘ │
+│                                                             │               │
+│   ┌─────────────────────┐   Synthesized Audio (24kHz)       │               │
+│   │ Agent Voice Stream  │◄──────────────────────────────────┘               │
+│   │ (Speaker Output)    │                                                   │
+│   └─────────────────────┘                                                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Ephemeral Session Token Minting
+
+For enterprise browser/IDE security, never expose primary API keys on clients. Mint short-lived ephemeral tokens from your secure backend:
+
+```python
+import os
+from google import genai
+from google.genai import types
+
+client = genai.Client()
+
+def create_ephemeral_live_session(user_id: str, ttl_seconds: int = 1800) -> str:
+    """Mints an ephemeral session token with pre-configured system instructions."""
+    session = client.aio.live.create_session_token(
+        model="gemini-2.0-flash-exp",
+        config=types.LiveConnectConfig(
+            response_modalities=[types.LiveModality.AUDIO],
+            system_instruction=types.Content(
+                parts=[types.Part.from_text(
+                    "You are an expert pair-programming agent inside Antigravity. "
+                    "Analyze screen frames and audio simultaneously. Be concise and actionable."
+                )]
+            ),
+            speech_config=types.SpeechConfig(
+                voice_config=types.VoiceConfig(
+                    prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Aoede")
+                )
+            )
+        )
+    )
+    return session.token
+```
+
+---
+
+## 3. Bidirectional WebSocket Audio Streaming (Python Client)
+
+Connects to the Gemini Live WebSocket endpoint and streams audio bi-directionally:
+
+```python
+import asyncio
+import websockets
+import json
+
+LIVE_WS_URL = "wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateContent"
+
+async def stream_live_pair_programming(api_key: str):
+    url = f"{LIVE_WS_URL}?key={api_key}"
+    
+    async with websockets.connect(url) as ws:
+        # 1. Send initial session handshake
+        setup_message = {
+            "setup": {
+                "model": "models/gemini-2.0-flash-exp",
+                "generation_config": {
+                    "response_modalities": ["AUDIO"],
+                    "speech_config": {
+                        "voice_config": {
+                            "prebuilt_voice_config": {"voice_name": "Puck"}
+                        }
+                    }
+                }
+            }
+        }
+        await ws.send(json.dumps(setup_message))
+        
+        # 2. Receive live audio chunks & emit to speaker
+        async for raw_msg in ws:
+            response = json.loads(raw_msg)
+            server_content = response.get("serverContent", {})
+            model_turn = server_content.get("modelTurn", {})
+            
+            for part in model_turn.get("parts", []):
+                inline_data = part.get("inlineData", {})
+                if inline_data.get("mimeType", "").startswith("audio/"):
+                    pcm_chunk = inline_data.get("data")
+                    # Send to audio output buffer
+```
+
+---
+
+## 4. Visual Screen Frame Injection
+
+Inject captured screen frames at 1 frame per second to ground audio conversation in visual code context:
+
+```python
+import base64
+
+async def send_screen_frame(ws, jpeg_bytes: bytes):
+    """Encodes a screen capture and sends it as a visual context turn."""
+    frame_payload = {
+        "realtime_input": {
+            "media_chunks": [
+                {
+                    "mime_type": "image/jpeg",
+                    "data": base64.b64encode(jpeg_bytes).decode("utf-8")
+                }
+            ]
+        }
+    }
+    await ws.send(json.dumps(frame_payload))
+```
+
+---
+
+## 5. Enterprise Best Practices & Anti-Patterns
+
+| Category | Recommended Pattern | Anti-Pattern |
+| :--- | :--- | :--- |
+| **Authentication** | Ephemeral tokens with 30m TTL minted by backend | Hardcoding permanent API keys in frontend bundles |
+| **Audio Format** | PCM 16-bit little-endian at 16,000Hz mono | Compressed MP3 with variable bitrates causing VAD jitter |
+| **Video Cadence** | Throttled keyframes at 1 FPS or on viewport change | 60 FPS full video ingestion saturating network bandwidth |
+| **Voice Activity** | Enable built-in server-side Voice Activity Detection | Client-side manual push-to-talk creating unnatural latency |