64 lines
5.7 KiB
Markdown
64 lines
5.7 KiB
Markdown
# 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
|