ss-tools/specs/035-agent-chat-context/plan.md

Implementation Plan: Agent Chat Context & Guardrails Refinement

Branch: 035-agent-chat-context | Date: 2026-07-04 | Spec: 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