# 🏗️ v2.1 Technical Spec: The "Self-Healing" Sovereign Expansion

## 🎯 Vision
Transform the **AgentOps Cockpit** from a diagnostic auditor into an **Autonomous Maintenance Plane**. v2.1 focuses on eliminating operational friction and closing the loop between anomaly detection and remediation.

---

## 🛠️ 1. Unified Sovereign Authentication (`cockpit auth`)
**Problem**: Manual registry authentication (`UV_EXTRA_INDEX_URL`) is the #1 friction point in enterprise environments.

**Proposed Implementation**:
*   **Command**: `cockpit auth login [google|aws|azure]`
*   **Mechanism**:
    *   **GCP**: Automates `gcloud auth print-access-token` and injects it into a temporary `.uvconfig` or environment state.
    *   **AWS**: Leverages `boto3` session credentials to authenticate against CodeArtifact.
*   **Feature**: **Zero-Config Resiliency (Smart Registry Failover)**. Cockpit detects if the user is in a "Cordoned Environment" (401/403 errors) when checking for the `agentops-cockpit` package or during dependency resolution. It automatically retries against public PyPI or suggests the `--public` failover immediately without requiring a manual handbook lookup.

## 🐍 2. Language-Native Scaffolding
**Problem**: Current scaffolding logic (e.g., `policy_engine.ts`) is biased toward TypeScript, creating a language mismatch in Python-only or Go-only agent silos.

**Proposed Implementation**:
*   **Runtime Detection**: The `DiscoveryEngine` identifies the dominant language of the agent silo (searching for `requirements.txt`, `package.json`, or `go.mod`).
*   **Polyglot Generators**:
    *   **Python**: Generates `policy_engine.py` using Pydantic for validation.
    *   **TypeScript**: Generates `policy_engine.ts` (Current Baseline).
    *   **Go**: Generates `policy_engine.go` with structured validation patterns.

## 🏗️ 3. AST-Aware Surgical Patching (Beyond Scaffolding)
**Problem**: "Auto-fix" currently focuses on infrastructure (scaffolding). It identifies "Missing Props" but does not surgically edit existing UI components.

**Proposed Implementation**:
*   **Targeted UI Injection**: Inject `surfaceId` or telemetry props into recognized React/TSX components using specialized parsers.
*   **Client Wrapping**: Automatically wrap LLM clients (OpenAI, Gemini) with Cockpit `@telemetry` or `@cost_control` decorators.
*   **Linting Remediation**: Fix tactical lint errors surgically (e.g., converting E701 one-liners to multi-line blocks) while preserving the "creative spark" of the surrounding logic.

## 📊 4. Compacted Fleet Reporting (UX Compaction)
**Problem**: Running audits on large fleets (`--workspace`) results in extremely verbose output, making it hard to find the "forest for the trees."

**Proposed Implementation**:
*   **Compacted View**: Implement a "Jetstream" progress view. Instead of full boxes for every agent, use a single dynamic table that updates in real-time.
*   **The "Forest" Dashboard**: Only show full detail for agents with "Critical" findings. "Green" agents are summarized in a single-line status row.

## 📡 4. "Live Wire" Telemetry Integration
**Problem**: The current Anomaly SME relies on manual file-based logs or simulations.

**Proposed Implementation**:
*   **Connectors**: Add a `telemetry/connectors/` directory.
    *   **GCP Connector**: Listens to Cloud Logging via Pub/Sub.
    *   **BigQuery Connector**: Queries the "Evidence Lake" in real-time.
*   **Real-time SME**: The `AnomalySME` becomes a long-running process (`cockpit fleet watch --live`) that processes events as they happen, triggering alerts or "Mothball" signals instantly.

## 📐 5. Unified CLI Schema (DX Standard)
**Problem**: Inconsistent flags (`--path` vs `--agent` vs `--name`) lead to user frustration.

**Proposed Implementation**:
*   **The "Target" Standard**: All commands will adopt a unified naming convention using Typer aliases:
    *   **`--target` / `-t`**: For file system paths.
    *   **`--id`**: For unique agent identifiers in the fleet.
    *   **`--apply` / `-f`**: For all auto-remediation triggers.
*   **Global Help**: A unified `cockpit --help` that groups commands by **Lifecycle Phase** (Build -> Certify -> Run -> Govern).

---

## 🧠 Strategic Wishlist (v2.1+)
*   **Financial Guardrails (Auto-Downgrade)**: Automatically generate `model_routing.json` to map simple tasks to SLMs (Gemma Flash/GPT-4o-mini) when the Economist detect "Token Hemorrhage."
*   **The Architect's Simulation**: A "Shadow Mode" evaluation that compares original vs. hardened output to ensure security didn't break functionality.
*   **Protocol Hub**: A built-in MCP server for automated cross-agent certification.

**Status**: *High-Fidelity Evolution Phase (Target: v2.1.0-alpha)*
