clawdash: agent context visibility (contracts + live assembled context)

[mostlydev]

Problem

Operators have no way to inspect what an agent actually sees at runtime. clawdash shows fleet health, topology, and schedules, but nothing about agent contracts, injected context, feeds, tools, memory, or model policy. Debugging agent behavior requires manually reading files under .claw-runtime/context/ and guessing what cllama assembled on any given turn.

Goals

1. Static contract view — inspect the compiled artifacts written by claw up for any agent: AGENTS.md, CLAWDAPUS.md, metadata, feeds manifest, tools manifest, memory config.
2. Live assembled context — see the exact system message, tools array, and memory recall block that cllama delivered to the provider on the most recent turn. Same execution path as real requests — validates actual output, not a reconstruction.
3. Single API convention — all observability queries go through claw-api. clawdash talks to one backend.

Design

Full design plan: docs/plans/2026-04-17-agent-context-visibility-design.md

Architecture

cllama (holds snapshot in memory)
  └─ GET /internal/context/<id>/snapshot  (internal only)
        │
        ▼
claw-api (single query surface)
  ├─ GET /agents                     (index, scope-filtered)
  ├─ GET /agents/<id>/contract       (static artifacts, credentials redacted)
  └─ GET /agents/<id>/context        (live, proxied from cllama)
        │
        ▼
clawdash (new Agents page with contract + live context tabs)

Key decisions

• cllama captures a ContextSnapshot after the full assembly sequence (memory recall → feeds → time → tools → model resolution) as a side effect of the real request flow. Stored in a sync.Map per agent, one entry each, overwritten per turn.
• claw-api proxies live context from cllama, reads static artifacts from the mounted context directory. Credentials are redacted (tokens in metadata, feeds, tools, memory, service-auth).
• New claw-dashboard principal — always created when claw-api exists, gives clawdash read access independent of the scheduler principal (which only exists when invokes are configured).
• New agent.context verb — gates all three endpoints. Scope filtering via a composite check (pod OR claw_id OR service) so self-principals can inspect their own service's agents.
• Snapshot captures candidate list, not single resolved model — model resolution produces a failover candidate list; pre-dispatch snapshot shows the resolution policy.

Implementation phases

1. cllama snapshot capture — struct, sync.Map, capture points in both OpenAI/Anthropic flows, internal endpoints
2. claw-api context endpoints — verb, principal, mounts, handlers, scope filtering
3. clawdash agents view — index page, detail page with contract/live tabs, nav integration

Non-goals

• Per-turn history browser (session history exists separately)
• Runtime context modification (write-plane concern)
• Replacing the cllama operator dashboard (stays for provider key management)

Review notes

Design went through two rounds of Codex review — 9 findings identified and addressed (3 credential leaks, auth wiring gaps, scope model mismatches, snapshot boundary issues). See the review fixes tables in the plan document.