Umbrella: Registry Copilot — embedded AI chat assistant (guide + agent builder)

## Umbrella: Registry Copilot

An AI chat assistant embedded in the registry UI as a **toggleable left-sidebar panel**, powered by Claude (Opus 4.8) on Amazon Bedrock. It helps users work with the registry conversationally and design agents from registry assets. This umbrella tracks the work across focused sub-issues.

## Problem

Users interact with the registry through forms, tables, and search — they must know which page to visit and how to craft queries. There is no conversational way to (a) get grounded answers to "how do I…" / "where is…", or (b) go from "I need an agent that does X" to a concrete, deployable design built from real registry assets.

## Sub-issues

- [ ] #1340 — **Chat panel & natural-language registry guide (advisory + discovery).** Foundational chat experience: toggleable sidebar, conversation persistence, LLM backend, agentic/semantic-search grounding. Answers how-to and discovery questions and deep-links to the right UI. Read-only (no agent design, no CRUD execution).
- [ ] #1341 — **Agent builder — design → YAML AgentSpec → AgentCore harness (Phases B+C).** Builds on #1340: recommends assets for a described agent, emits a framework-agnostic YAML `AgentSpec`, and an Amazon Bedrock AgentCore harness bundle deployable with one `aws bedrock-agentcore-control create-harness` call.

## Shared architecture (applies to all sub-issues)

- **UI:** toggleable left rail that swaps the existing nav for the Copilot chat (reuses `sidebarOpen`/`Layout.tsx`); gated by `COPILOT_ENABLED` (default false; flag exposed to all authenticated users so the toggle renders).
- **Inference:** Anthropic SDK `AnthropicBedrockMantle` client, default model `anthropic.claude-opus-4-8` (adaptive thinking + effort). LiteLLM remains for embeddings/search only. Dedicated `ThreadPoolExecutor`; zero overhead + routes 404 when disabled.
- **State:** no background agent process — a request-scoped tool-calling loop; multi-turn state persisted in DocumentDB (`copilot_conversations_{ns}`) and replayed each turn. Not Anthropic Managed Agents (unavailable on Bedrock).
- **Grounding:** the existing hybrid `POST /api/search/semantic` (extracted to an in-process `search_service`) provides visibility-filtered agentic search; it is the grounding mechanism for both guide answers and asset recommendations.
- **Streaming:** SSE over POST (fetch + ReadableStream client; 15s heartbeats; SSE-safe nginx location — triggers the MCP-canary test rule).
- **Guardrails:** optional Amazon Bedrock Guardrails via the decoupled `ApplyGuardrail` API (`COPILOT_GUARDRAIL_ID`), screening input/output.
- **Limits:** 200k tokens / 25 messages per conversation; per-user max conversations + concurrent streams.

## Out of scope (umbrella)

- Actual agent code generation (the downstream coding agent's job).
- Calling AWS / deploying agents on the user's behalf (we emit the bundle; the user runs the CLI).

## Future / deferred

- **Conversational registry operations (original "Phase A"):** registering/updating/toggling registry assets via chat with confirmations for destructive ops. The current guide sub-issue (#1340) is intentionally advisory-only; execute-via-chat can be a follow-up sub-issue once the foundation ships.
- Richer guardrails via OSS frameworks (NeMo Guardrails / Guardrails AI / LLM Guard) layered on `ApplyGuardrail`.
- AgentCore Identity credential-provider wiring (with the Egress Token Broker, #1265) to make authenticated registry MCP servers turnkey in the AgentCore bundle.

## Design docs

`.scratchpad/issue-744/`: `github-issue-744.md`, `lld-744.md` (Revisions v1.1 + v1.2), `review-744.md`, `testing-744.md`.

---
*Milestone: 1.27.0 — A2A Gateway & Registry Copilot.*