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

#region FeatureSpec [C:3] [TYPE ADR] [SEMANTICS spec,requirements,feature,agent-chat,context,guardrails,tools] @BRIEF Refinement of agent chat logic: enriched context passing from frontend, guardrails card UX improvements, and tool execution optimisation. @RELATION DEPENDS_ON -> [ADR-0008:ADR] @RELATION DEPENDS_ON -> [ADR-0006:ADR] @RELATION DEPENDS_ON -> [ADR-0005:ADR]

Navigation (DSA Indexer keywords)

@SEMANTICS: spec, requirements, feature, agent-chat, context, guardrails, tools, hitl, confirmation, streaming, tool-execution

Feature Branch: 035-agent-chat-context
Created: 2026-07-04 | Status: Draft
Input: "доработка логики агентского чата - передача контекста из фронта, доработка guardrails cards, оптимизация tools etc"

Clarifications

Session 2026-07-04

• Страница /agent — выделенный модуль чата: Агент-чат — отдельная страница (/agent), на которую пользователь переходит по кнопке с любой страницы сервиса. Контекст страницы-источника передаётся через query-параметры URL при навигации: objectType, objectId, objectName, envId, route. Фронтенд на странице /agent читает эти параметры в onMount и формирует UIContext JSON. Контекст статичен в рамках визита на /agent — повторные сообщения используют тот же контекст. Смена окружения через EnvSelector возможна и обновляет envId для последующих сообщений. Пример: со страницы http://localhost:5173/dashboards/10?env_id=ss-dev кнопка «Спросить агента» ведёт на /agent?objectType=dashboard&objectId=10&objectName=Отчёт%20по%20энергопотреблению&envId=ss-dev&route=/dashboards/10.
• Инструменты, релевантные контексту: Список инструментов, доступных LLM, фильтруется (жёсткое исключение, не приоритизация) по objectType. dashboard → только дашборд-ориентированные инструменты; dataset → датасет-ориентированные; null/отсутствует → полный набор разрешённых инструментов. show_capabilities всегда включён.

User Scenarios

Each story is an independently testable unit. Prioritized P1 (MVP) → P2 → P3. All stories share @SEMANTICS domain keywords from the feature header.

Story 1 — Context-Aware Agent on /agent Page (P1)

Why P1: Пользователь переходит на выделенную страницу агента (/agent) с любой страницы сервиса по кнопке «Спросить агента». Контекст страницы-источника передаётся через query-параметры URL: objectType, objectId, objectName, envId, route. Агент, получив этот контекст, должен: (а) понимать, на каком объекте находился пользователь — отвечать контекстно без явного называния объекта; (б) фильтровать доступные инструменты по типу объекта — дашборд-ориентированные для дашборда, датасет-ориентированные для датасета. Контекст статичен в рамках визита на /agent; смена окружения через EnvSelector обновляет envId.

Independent Test: Со страницы дашборда (/dashboards/10?env_id=ss-dev) нажать «Спросить агента» → переход на /agent?objectType=dashboard&objectId=10&envId=ss-dev.... Спросить «расскажи про этот дашборд» — агент: (1) отвечает с информацией о дашборде id=10 не требуя названия; (2) использует только дашборд-ориентированные инструменты, а не общий список из 22 тулов.

Acceptance:

1. Given пользователь на странице дашборда нажимает «Спросить агента» и переходит на /agent?objectType=dashboard&objectId=10&envId=ss-dev When спрашивает «какой статус у этого дашборда?» Then агент понимает, что речь о дашборде id=10 в окружении ss-dev, и отвечает с git-статусом, датой изменения, результатами валидации — без явного указания названия или ID.
2. Given переход на /agent?objectType=dataset&objectId=15&envId=staging When агент вызван и спрашивают «есть ли проблемы с этим датасетом?» Then агент использует dataset id=15, staging и отвечает про маппинги, зависимости, статус ревью.
3. Given objectType: "dashboard" в контексте When агент формирует набор инструментов для LLM Then только дашборд-ориентированные инструменты (search_dashboards, get_health_summary, deploy_dashboard, run_llm_validation, run_llm_documentation, execute_migration, create_branch, commit_changes, show_capabilities) доступны; нерелевантные (superset_explore_database, run_backup и др.) — исключены.
4. Given objectType: "dataset" When агент формирует набор инструментов Then только датасет-ориентированные (superset_explore_database, superset_format_sql, superset_audit_permissions, superset_execute_sql, superset_create_dataset, search_dashboards, get_task_status, list_environments, show_capabilities) доступны.
5. Given пользователь переходит с дашборда A на страницу агента, затем возвращается и переходит с дашборда B When агент вызывается снова со страницы B Then новый objectId в URL — никакого залипания старого контекста.
6. Given пользователь на странице без контекстного объекта (переход с /settings) When агент вызывается (URL без objectType) Then агент работает в общем режиме с полным набором доступных инструментов.

---

Story 2 — Guardrails Card Refinement (P2)

Why P2: The current confirmation card shows tool name and arguments with a simple confirm/deny. Risk classification is a heuristic based on tool name prefixes only — it does not consider the environment (production vs staging), the scope of data affected, or the user's role. Users need richer context to make informed confirmation decisions, and guardrails should adapt to actual risk, not just tool category.

Independent Test: Trigger a guarded tool (e.g., deploy_dashboard to production) — the confirmation card shows environment badge («⚠️ PRODUCTION»), estimated impact scope («3 дашборда будут изменены»), and a contextualised warning. Trigger the same tool to staging — the card shows a lower-severity styling.

Acceptance:

1. Given the agent calls deploy_dashboard targeting the prod environment When a confirmation is triggered Then the card displays a «production» risk badge with destructive-tone styling, warns about the target environment, and requires explicit confirmation.
2. Given the same tool targets a dev or staging environment When a confirmation is triggered Then the card displays a lower-risk badge (info-tone), and the prompt is less alarming («Изменения в dev-окружении»).
3. Given the agent calls a read-only tool (e.g., search_dashboards) with HITL enabled When a confirmation is required Then the card clearly labels the action as «чтение данных» with distinct visual treatment (success-tone, no warning icon) — the user immediately distinguishes read from write confirmations.
4. Given the user's role lacks permission for a requested tool When the agent attempts the tool call Then the confirmation is pre-rejected server-side — the card displays «Недостаточно прав» with the required role shown and no confirm button (only a dismiss).
5. Given the user dismisses or denies a confirmation When the action is cancelled Then the agent does NOT proceed silently — it returns a clear cancellation message in the chat stream.

---

Story 3 — Tool Execution Optimisation (P3)

Why P3: The agent currently invokes tools via HTTP to FastAPI with no retry logic, no response-size awareness beyond a hard truncation limit, and no tool-level access control based on user role. Large responses waste LLM context window; network flakes cause avoidable failures; role-inappropriate tools unnecessarily confuse the LLM.

Independent Test: Trigger run_backup as an analyst user — the tool is not offered to the LLM. Trigger search_dashboards with a large result set — the response is intelligently summarised. Simulate a transient FastAPI error — the tool retries once and succeeds.

Acceptance:

1. Given the user has role analyst (no write permissions for git/deploy) When the agent's tool set is assembled Then write tools (deploy_dashboard, commit_changes, create_branch) are excluded from the LLM's available tools — the agent cannot even propose them.
2. Given a tool call to FastAPI returns a transient 502/503 error When the tool is a read-only query Then the agent retries once (with exponential backoff) before reporting failure to the user.
3. Given a tool returns >4000 characters of raw JSON When the response is prepared for the LLM Then structured data is summarised (top-N items + count) rather than hard-truncated mid-structure, preserving semantic value.
4. Given a tool invocation hangs (no response for 30 seconds) When the timeout elapses Then the agent receives a clear timeout error and can attempt an alternative approach or report the issue — the chat does not hang indefinitely.
5. Given the embedding router is available When the LLM selects tools Then the tool set passed to the LLM is restricted to the top-K semantically relevant tools (plus the mandatory capabilities tool), reducing prompt size and improving LLM tool-selection accuracy.

---

Edge Cases

• User navigates from dashboard page to /agent with context, closes tab, reopens from another dashboard → fresh context from new URL parameters.
• No environment is selected in the UI → переход на /agent без envId; agent operates in environment-agnostic mode (cannot use env-specific tools).
• The user's JWT expires mid-conversation → the next tool call fails with 401; agent reports «сессия истекла, обновите страницу» without retrying.
• Conversation is restored from history that was created before context enrichment → old messages lack uicontext JSON; agent gracefully degrades to «контекст недоступен».
• HITL confirmation is pending when the Gradio connection drops → state is preserved in the LangGraph checkpoint; on reconnect, the backend re-emits confirm_required for the pending checkpoint.
• Multiple browser tabs have the agent chat open → each tab derives independent context from its own URL parameters; no cross-tab interference.
• Malformed objectType in URL (e.g. ?objectType=invalid) → frontend treats as null; backend validation rejects unknown enum values with 422.

Requirements

Functional (IDs survive HCA 128× via hierarchical naming)

• AGCTX-FR-001: При переходе на /agent с любой страницы сервиса, страница-источник передаёт контекст через query-параметры URL: objectType, objectId, objectName, envId, route. Страница /agent читает параметры в onMount и формирует структурированный JSON-объект UIContext, который передаётся агенту при отправке сообщений.

• AGCTX-FR-002: The agent backend MUST receive the UIContext JSON and inject it into the system prompt / runtime context block in a machine-and-human-readable format, distinguishable from user message text.

• AGCTX-FR-003: Context is static for the duration of a /agent page visit. If the user navigates away and returns, fresh context is derived from new URL parameters. EnvId may be updated during the visit via EnvSelector (updateActiveEnv), which synchronises both the model atom and the envId sent with subsequent messages.

• AGCTX-FR-004: The UIContext payload MUST be versioned (contextVersion field, currently 1). Backend MUST validate: objectType enum ("dashboard"|"dataset"|"migration"), objectId format (numeric string or null), envId against known environments, max field lengths (objectName ≤ 256 chars), max payload size (4 KB malformed/oversized context MUST trigger a 422 error or be silently discarded with audit logging — never silently injected into the LLM prompt.

• AGCTX-FR-005: The agent backend MUST hard-filter (exclude, not deprioritise) the tool list by objectType: dashboard-oriented tools for dashboard context, dataset-oriented tools for dataset context, full tool set when objectType is null/absent. show_capabilities always included.

• AGGRD-FR-001: Guardrails risk classification MUST consider the target environment (prod vs staging vs dev) in addition to the tool name prefix.

• AGGRD-FR-002: The confirmation card UI MUST display environment context (badge, tone) and distinguish read vs write operations visually.

• AGGRD-FR-003: Permission-denied tool calls MUST be rejected server-side before confirmation is presented — the card shows «access denied» without a confirm button.

• AGGRD-FR-004: Cancelled confirmations MUST produce an explicit «operation cancelled» message in the chat stream.

• AGTL-FR-001: Tool availability MUST be filtered by user role — write tools excluded for read-only roles.

• AGTL-FR-002: Read-only tool HTTP calls MUST retry once with a fixed 1-second delay on transient errors (5xx, connection errors). Write/mutating tools MUST NOT auto-retry — raises immediately.

• AGTL-FR-003: Large tool responses (>4000 chars) MUST be structured-truncated (top-N items + total count for arrays; sentence-boundary truncation for text) rather than hard-truncated mid-structure.

• AGTL-FR-004: Tool execution MUST have a configurable timeout (default 30s); hanging calls MUST return a timeout error rather than block the chat. For write/mutating tools, timeout MUST produce «operation status unknown — check status» rather than automatic retry, as the backend mutation may have succeeded despite the timeout.

• AGTL-FR-005: Tool RBAC filtering MUST be enforced at TWO layers: (a) prompt-level — excluded tools are not presented to the LLM; (b) invocation-level — before executing any tool, the backend MUST validate the tool name against the user's role permissions even if it was filtered from the prompt. Rejected invocations emit permission_denied SSE event, not confirm_required.

• AGTL-FR-006: Embedding-based tool router integration (existing _embedding_router.py) is a SHOULD enhancement for post-MVP. When active, it restricts the tool list to top-K semantically relevant tools. Not required for initial release.

Key Entities

• UIContext: Structured JSON payload assembled by the frontend from URL query parameters at /agent page entry. Contains: objectType ("dashboard"|"dataset"|"migration"|null), objectId (string|null), objectName (string|null, max 256 chars), envId (string|null), route (string — source page route), contextVersion (number, currently 1). Static for the duration of the /agent visit. EnvId may be updated mid-visit via updateActiveEnv. Бэкенд валидирует все поля перед инжекцией в промпт.
• ContextToolAffinity: Server-side mapping from objectType → set of relevant tool operations. Used to prioritise/filter tools for the LLM. Example: dashboard → [search_dashboards, get_health_summary, deploy_dashboard, run_llm_validation, ...]; dataset → [superset_explore_database, superset_format_sql, superset_audit_permissions, ...]; none → all available tools.
• GuardrailDecision: Result of server-side guardrail evaluation. Contains: risk level (safe/guarded/dangerous), risk tone (success/warning/destructive), environment context, permission check result, recommended confirmation prompt. Used to render the confirmation card.
• ToolPermission: Mapping of tool operation → required role(s). Derived from the @assistant_tool decorator's permission_checks (ADR-0008). Used to filter the LLM's available tool set per user.
• ToolResponseSummary: Structured summary of a large tool response. Contains: result count, top-N items (trimmed), summary text, total items indicator. Generated server-side before the response enters the LLM context window.

Success Criteria

• SC-001: Агент, получивший контекст дашборда через /agent?objectType=dashboard&objectId=42&envId=ss-dev, в 100% тестовых сценариев правильно идентифицирует дашборд (id=42) и использует только дашборд-ориентированные инструменты — измерено через интеграционный тест с заданным контекстом.
• SC-002: Guardrails card renders with correct risk classification (read/write/dangerous + environment context) within 200ms of confirmation trigger — measured via browser performance API.
• SC-003: Tool invocation errors from transient FastAPI failures decrease by 50% relative to current baseline — измерено через structured audit log comparison за 1 week of operation after deployment.
• SC-004: Average tool response size entering the LLM context window decreases by 30% — measured via log analysis of response summarisation calls over 1 week of operation.
• SC-005: Zero cases where an analyst-role user can invoke a write tool (git deploy, dashboard migration, etc.) — verified via RBAC integration test at both prompt-filtering and invocation-enforcement layers.
• SC-006: 100% of malformed/oversized UIContext payloads are rejected or discarded with audit logging — verified via fuzzing test.

#endregion FeatureSpec