🌐 Multi-Tenant Copilot Bridge Architecture & Governance

---

1. Constitutional Multi-Tenant Mandate

The cluster's headless Microsoft Copilot bridge is an **institutional, multi-tenant resource** shared across the entire Sovereign OS agent federation:

**Human Operators** (via https://os.predator.run/ Master Operator Console)

**Antigravity / Gemini Coding Agent** (via direct REST & CDP orchestration)

**Qwen 2.5 NPU Swarm** (on Lion node for sub-millisecond local inferences)

**Claude / DeepSeek Provers** (for formal mathematical & smart contract verification)

**Autonomic Watchdog Daemons** (for automated incident response and self-healing)

To prevent conflicting modifications, race conditions, keystroke contamination, or session invalidation, **all agents and operators MUST strictly adhere to this central specification**.

---

2. Infrastructure Topology (SSOT)

graph TD
    Agent1["👤 Human Operator (Console)"] -->|conversationId: operator:*| RestAPI
    Agent2["🤖 Antigravity / Gemini"] -->|conversationId: agent:antigravity:*| RestAPI
    Agent3["🦁 Qwen NPU Swarm"] -->|conversationId: agent:qwen:*| RestAPI
    Agent4["⚡ Autonomic Sentinel"] -->|conversationId: agent:sentinel:*| RestAPI

    subgraph Pod ["☸️ apex-cortex/gemma-cobrowser"]
        RestAPI["REST Bridge (Port 3456)"]
        CDP["Chrome DevTools Protocol (Port 9222)"]
        VNC["noVNC GUI Display :99 (Port 5900/6080)"]
        Profile["📁 /puppeteer_profile (PERMANENT AUTH SSOT)"]
        
        RestAPI --> CDP
        CDP --> Tabs["Target Tabs: Isolated by conversationId"]
        Tabs --> Profile
    end

Core Connection Parameters

Parameter	Value	Description
Kubernetes Pod	`apex-cortex/gemma-cobrowser-55584c4ffd-f5928`	Dedicated 24/7 cluster cobrowser
Node Location	`server` (`162.244.80.232` / Tailscale `100.97.133.107`)	Bare-metal Apex1 compute node
REST API URL	`http://10.43.134.153:3456` or `http://localhost:3456`	Direct headless chat, tasks, and debug endpoints
CDP Endpoint	`http://10.43.134.153:9222`	Chrome DevTools Protocol remote debugging
noVNC Web GUI	`http://100.97.133.107:6080/vnc.html`	Interactive display `:99` for biometric manual override
Profile Storage	`/puppeteer_profile`	Authenticated browser profile (NEVER WIPED)

---

3. Tenant Isolation & Session Namespacing

The Law of Conversation ID Namespacing

No agent may dispatch prompts to the default or unnamespaced conversation thread. Every API invocation MUST declare an explicit, namespaced conversationId:

Format: <tenant_type>:<agent_or_subsystem>:<ticket_or_session_id>

#### Canonical Namespace Prefixes:

1. operator:web:<session_uuid> — Human operator interactive sessions from os.predator.run.

2. agent:antigravity:<ticket_id> — Antigravity / Gemini architectural and coding tasks.

3. agent:qwen:<ticket_id> — Lion NPU local model triage and code reviews.

4. agent:sentinel:<run_id> — Autonomic playbooks and QA watchdogs.

5. council:<proposal_id> — Sovereign 5-Member Council legislative votes.

Isolated Tab Lifecycle

The bridge daemon inspects conversationId upon receiving POST /api/copilot/chat.

If a page matching the ID exists, it routes directly to that isolated tab.

If no matching tab exists, it spawns a dedicated Chromium page (Target.createTarget), injects the target URL (https://copilot.microsoft.com), and navigates in total isolation from other agent tabs.

Under zero circumstances may an agent call Page.bringToFront on an active tab belonging to another tenant.

---

4. Anti-Collision & Mutex Protocol

To guarantee that multiple agents never collide during state transitions:

1. **Valkey Distributed Lease (lock:copilot:bridge)**:

- When an agent initiates an operational reconfiguration (e.g., refreshing authentication or restarting the bridge daemon), it MUST acquire a Valkey lease:

`redis

SET lock:copilot:bridge <agent_id> NX EX 30

- Standard conversational queries do **not** require the mutex, as Chromium handles multi-tab CDP sessions concurrently.

2. **Zero Keystroke / Focus Leaks**:

- Keyboard events are dispatched strictly via CDP Input.dispatchKeyEvent addressed to the specific sessionId of that tenant's tab. OS-level window focus (xdotool, xwininfo) is strictly forbidden.

---

5. Absolute Profile Protection (Rule 13 Fail-Once Invariant)

> [!CAUTION]

> **Strict Prohibition of Profile Deletion (Rule 13)**:

> Agents MUST NEVER delete, wipe, rm -rf, or overwrite /puppeteer_profile, browser cookies, or user data directories inside gemma-cobrowser.

> All authenticated sessions (Microsoft Copilot, Schwab, Entra ID) belong to the human user.

> If a Chromium process deadlocks or crashes, agents may ONLY clear SingletonLock files (rm -f /puppeteer_profile/SingletonLock), NEVER the profile directory itself.

---

6. Git-Tracked Governance & Audit Trail

Every operational change to the Copilot bridge must be tracked in version control:

1. **Git Repository Tracking**:

- The cobrowser deployment manifests (k8s/gemma-cobrowser.yaml), Node.js bridge server code (server.js), and Dockerfile must reside in https://github.com/thealanphipps-del/sovereign-os under ops/cognitive_bridge/cobrowser/.

- Ad-hoc modifications via kubectl exec without a corresponding Git commit are strictly classified as Prime Directive #1 & #2 violations.

2. **Audit Logging in Valkey**:

- Every prompt and response turns are logged into Valkey under copilot:audit:<conversationId>:<timestamp> with token counts, latency metrics, and tenant identity.

3. **Bi-Directional Live Sync**:

- Any updates to bridge routes or environment variables trigger the LiveDocEngine bi-directional reflection loop, updating this documentation page automatically.