busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
082d6af3ab7b6eca4693ca215d4379bd3f4ea160
ss-tools/specs/035-agent-chat-context/plan.md
busya ff60865183 feat(agent-chat): 035-agent-chat-context — контекст, guardrails, tools, database discovery 
== User stories ==
US1: Контекст с дашборда/датасета → /agent с URL params
US2: Guardrails card — env badge, 7 risk tones, countdown, permission_denied
US3: Tools optimization — retry, timeout, summarise, RBAC + context affinity

== Backend ==
- _context.py (NEW): UIContext validation (7 checks)
- _tool_filter.py (NEW): RBAC + context affinity pipeline
- _confirmation.py: build_confirmation_contract_v2, permission_denied_payload
- tools.py: superset_list_databases, retry/summarise/timeout wrappers
- app.py: _inject_uicontext, _inject_env_id_into_tools, database
  prefetch в runtime context
- _persistence.py: prefetch_databases()
- agent_superset_explore.py: GET /databases endpoint
- _llm_async_http.py, _persistence.py: fix double /v1 в LLM URL
  (LM Studio Unexpected endpoint)

== Frontend ==
- AgentChatModel.svelte.ts: 5 atoms, 3 actions, countdown, context
- AgentChat.svelte: production banner, process steps, debug panel
- ConfirmationCard.svelte: 7 risk tones, permission_denied, countdown
- ToolCallCard.svelte: retrying/timeout/cancelled states
- StreamProcessor.svelte.ts: tool_retry, timeout, permission_denied
- TopNavbar: sparkles icon + Ассистент
- sidebarNavigation: AI section
- DashboardHeader, datasets/+page: contextual AI buttons
- Icon: sparkles, brain, cpu icons
- tailwind: assistant category colors
- i18n: en/ru nav keys

== Tests ==
- 159 backend agent tests (+16 US3: retry, timeout, summarise, contracts)
- 2544 frontend tests (+11 model + component tests)
- 15 JSON fixtures (10 API + 5 model)

== Specs ==
- specs/035-agent-chat-context/: spec, UX, plan, tasks, research,
  data-model, contracts, quickstart, traceability, fixtures, checklists

Closes #035
2026-07-04 22:47:17 +03:00

4.0 KiB
Raw Blame History

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.

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. Re-check after Phase 1: verify no contract exceeds 150 lines, no module exceeds 400 lines post-extension.

#endregion — plan metadata section