ADR-0028: Admin Context Injection Pattern

Date: 2026-03-09 Status: Proposed Author: Architect Agent Supersedes: N/A

1. Context

PR-C1 requires the Bridge to pass a system snapshot ("Admin Context") to the Runtime for diagnostics and capabilities resolution. The AdminCopilotService in the analytics-platform already generates these snapshots for the UI.

2. Decision

We will formalize the Admin Context Injection as a mandatory Bridge-side responsibility before calling the Guardian layer.

2.1 Pattern Definition

1. Injection Point: OpenAiCompatService (the Bridge) invokes AdminCopilotService.getSnapshot() on every incoming request.
2. Metadata Enrichment: The Bridge maps the AdminCopilotSnapshot (services, config, models, capabilities) to the OpenClawGuardCoreAdminSnapshotInput shape.
3. Guard Entry: This snapshot is passed as a field in the OpenClawGuardCoreRequest.
4. Usage: The Guardian layer uses the snapshot to derive degradedMode and determine if a capability is resolveable via the "Typed" or "Heuristic" path.

2.2 Logic Flow

• Bridge -> AdminCopilotService.getSnapshot() -> Snapshot
• Bridge: Map Snapshot -> AdminSnapshotInput
• Bridge -> OpenClawGuardCore.processGuardedRequest({ ..., adminSnapshot: AdminSnapshotInput })
• Guardian: Derive integrationStatus from adminSnapshot.

3. Alternatives Considered

• Direct Coupling: Let the Runtime call AdminCopilotService. Rejected: Violates the desired isolation of the Runtime and increases Runtime initialization overhead.
• Cached Injection: Use a background-updated cache for the snapshot. Recommended for Phase 2: If per-request calls to Postgres/Redshift (via AdminCopilotService) prove too slow, we will move to a TTL-cached inject.

4. Consequences

Positive

• Consistency: The Bridge and Admin UI see the same "Status" (OK vs Degraded).
• Isolation: The Runtime logic remains "pure" and environment-agnostic.

Negative

• Latency: Initial implementation may add 10-50ms per request for the snapshot query.