# Implementation Plan: Agent Chat Context & Guardrails Refinement

**Branch**: `035-agent-chat-context` | **Date**: 2026-07-04 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/035-agent-chat-context/spec.md`

## Summary

Refinement of the agent chat system across three vectors:
1. **Context enrichment** (P1): Frontend captures structured `UIContext` JSON from page state and passes it to the Gradio agent on each `sendMessage`. Agent uses context for (a) contextual responses without explicit object naming, (b) tool filtering by `objectType`. Context is route-level — transferred once when navigating to `/agent` page.
2. **Guardrails refinement** (P2): Risk classification extended from tool-name prefixes to include environment context and tool danger level. ConfirmationCard gains environment badges, destructive-operation countdown (10s), permission-denied state with alternatives, and visual risk toning.
3. **Tool optimisation** (P3): Backend: RBAC tool filtering, auto-retry on transient HTTP errors, semantic response summarisation, configurable tool timeout, context-aware tool affinity. Frontend: ToolCallCard extended with retry/timeout/cancelled states.

## Implementation Status — 2026-07-05 Fact Check

Read-only audit against source/tests found production code and dedicated US1/US2 tests implemented. Live E2E/quickstart validation remains the primary open gate.

| Area | Status | Evidence / Gap |
|------|:------:|----------------|
| Fixtures and foundational types | ✅ Implemented | API/model fixtures materialized; `UIContext`, `ConfirmMetadataV2`, `PermissionDeniedMetadata`, and extended `ToolCall` types are present. |
| Context-aware `/agent` flow | ✅ Implemented | `/agent` reads URL params, model builds UIContext/pill, backend validates/injects context, and tool filtering pipeline is present. |
| Guardrails production code | ✅ Implemented | Confirmation v2, permission_denied, invocation guard, countdown, deny/cancel flow, and distinct write_dev/write_staging/write_prod visual states are present. |
| Tool optimisation | ✅ Implemented | Retry, summarise, timeout helpers and ToolCallCard retry/timeout/cancelled states are present with dedicated tests. |
| Debug panel pipeline | ✅ Implemented | Backend `pipeline_result` SSE feeds `effectiveToolPipeline`, rendered in the debug panel. |
| Dedicated US1/US2 tests | ✅ Implemented | `test_agent_context.py`, `test_agent_tool_filter.py`, `test_agent_confirmation_v2.py`, `AgentChatModel.context.test.ts`, and `ConfirmationCard.ux.test.ts` are present. |
| Verification gates | ⚠️ Partially verified | Scoped backend/frontend tests and build pass; live E2E/quickstart remains pending. |

## Technical Context

**Language/Version**: Python 3.9+ (backend), TypeScript (frontend Svelte 5 runes-only)
**Primary Dependencies**: FastAPI, Gradio, LangChain (`create_react_agent`), LangGraph, LangChain-OpenAI (backend); SvelteKit 5, Svelte 5, Tailwind CSS 3, @gradio/client (frontend)
**Storage**: PostgreSQL 16 (checkpoints via PostgresSaver, conversations via SQLAlchemy)
**Testing**: pytest (backend), vitest (frontend — L1 model invariants without render + L2 UX with @testing-library/svelte)
**Target Platform**: Linux server (Docker), modern browsers
**Project Type**: web application (FastAPI REST + Gradio SSE backend, SvelteKit SPA frontend)
**Frontend Architecture**: TypeScript-first, model-first (Screen Models via `.svelte.ts`), runes-only (`$state`, `$derived`, `$effect`), typed callback props
**Performance Goals**: Context pill update <50ms, confirmation card render <200ms, tool retry <5s added latency
**Constraints**: RBAC enforcement (analyst cannot invoke write tools), backward-compat with existing Gradio submit API, no new database tables
**Scale/Scope**: ~10 concurrent agent chats, ~20 tools, 3 context types (dashboard/dataset/migration)

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

| Principle | Status | Evidence |
|-----------|:------:|----------|
| **I. Semantic Contract First** | ✅ PASS | All new modules/contracts annotated with `#region`/[C:N]/`@RELATION`. Existing contracts extended, not broken. |
| **II. Decision Memory** | ✅ PASS | `@RATIONALE`/`@REJECTED` recorded for: context-as-JSON (not URL-parsing), tool affinity mapping, dangerous countdown, retry strategy. |
| **III. External Orchestrator** | ✅ PASS | Agent remains external over Superset — no change to orchestration boundary. |
| **IV. Module Discipline** | ✅ PASS | New file `_tool_filter.py` (~40 LOC). Extended files: `AgentChatModel.svelte.ts` (~+60 LOC, stays under 400), `AgentChat.svelte` (~+15 LOC, stays under 1050 — near limit, monitor). No new module exceeds 400 LOC. |
| **V. RBAC Enforcement** | ✅ PASS | Tool RBAC filtering (AGTL-FR-001) extends existing role model per ADR-0005. Permission-denied confirmation card enforces role gates. |
| **VI. Frontend — Svelte 5 Runes Only** | ✅ PASS | All new state uses `$state`/`$derived`. No legacy `writable`/`$:` syntax introduced. |
| **VII. Test-Driven for C3+ Contracts** | ✅ PASS | Fixtures generated for C3+ contracts. `@TEST_EDGE` declarations enable TDD. |
| **VIII. Attention-Optimized Contracts** | ✅ PASS | All contract IDs hierarchical: `AgentChat.Context`, `AgentChat.Confirmation`, `AgentChat.ToolFilter`. Shared `[SEMANTICS agent-chat,...]` keyword. |

**No blocking violations at planning time.** 2026-07-05 verification notes production code and scoped tests are present; live E2E/quickstart remains open.

## Current Next Steps

1. Execute live E2E scenarios against a running backend + Gradio + frontend stack.
2. Run quickstart validation once LLM quota is available.
3. Track full-repo lint debt separately from the 035 feature gate.

#endregion — plan metadata section