ss-tools/specs/035-agent-chat-context/contracts/modules.md

#region ModulesContract [C:4] [TYPE ADR] [SEMANTICS contracts,modules,agent-chat]
@defgroup Contracts Module and function contracts for 035-agent-chat-context implementation.
@RATIONALE Content model updated for Path B (/agent dedicated page), Gradio payload safety, two-layer RBAC enforcement, and permission_denied flow separation.
@REJECTED Path A (drawer panel on any page) — rejected in favor of dedicated /agent route for simpler state management.

#region AgentChat.LangGraph.Handler [C:4] [TYPE Function] [SEMANTICS agent-chat,handler,context]
# @ingroup AgentChat
# @BRIEF Extended agent_handler — accepts uicontext JSON appended at end of positional args, injects into runtime context, filters tools by objectType.
# @PRE JWT valid, user authenticated. uicontext_str is valid JSON or None.
# @POST UIContext injected into system prompt. Tools filtered by objectType. Stream unchanged for uicontext=None (backward-compat).
# @SIDE_EFFECT Calls LLM, invokes tools, writes checkpoints. UIContext validated and logged via CoT logger.
# @RELATION DEPENDS_ON -> [AgentChat.ToolFilter]
# @RELATION DEPENDS_ON -> [AgentChat.Confirmation]
# @DATA_CONTRACT Input: (message, history, convId, userId, userJwt, envId, uicontext_str?) -> Output: AsyncGenerator[str]
# @TEST_EDGE: null_uicontext -> All 22 tools passed to LLM (backward-compat).
# @TEST_EDGE: dashboard_context -> Only 9 dashboard tools passed.
# @TEST_EDGE: invalid_json_uicontext -> Gracefully ignored with audit log, all tools passed.
# @TEST_EDGE: malformed_objectType -> Rejected with 422, audit log written.
# @RATIONALE uicontext_str appended at END of positional args (position 6) — inserting in the middle would break existing Gradio clients that pass 6 args. Null default ensures zero breakage.
# @REJECTED Middle-position insertion — rejected: breaking change for existing Gradio clients.
#endregion AgentChat.LangGraph.Handler

#region AgentChat.ToolFilter [C:3] [TYPE Module] [SEMANTICS agent-chat,tools,filter,context]
# @defgroup AgentChat Context-aware tool filtering by objectType.
# @LAYER Service
# @RELATION DEPENDS_ON -> [AgentChat.Tools]

# #region AgentChat.ToolFilter.Pipeline [C:4] [TYPE Function] [SEMANTICS agent-chat,tools,filter,pipeline]
# @ingroup AgentChat
# @BRIEF Canonical tool selection pipeline — applies in order: RBAC filter → context affinity filter.
# @POST Returns list[BaseTool] after applying: (1) role-based exclusion, (2) context-type hard filter. show_capabilities always included.
# @SIDE_EFFECT CoT logs reason for each excluded tool.
# @RELATION DEPENDS_ON -> [AgentChat.Tools]
# @DATA_CONTRACT Input: (all_tools, user_role, object_type) -> Output: filtered_tools
# @RATIONALE Ordered pipeline ensures RBAC is enforced FIRST (security), then context filtering (UX). Two-layer: prompt filtering + invocation enforcement (see AGTL-FR-005).
# @REJECTED Embedding-based filtering — rejected for initial release; postponed to post-MVP (AGTL-FR-006).
# @TEST_EDGE: null_objectType -> Returns all RBAC-allowed tools.
# @TEST_EDGE: dashboard+analyst -> Returns 9 dashboard tools minus any requiring admin.
# @TEST_EDGE: unknown_objectType -> Returns all RBAC-allowed tools (graceful fallback).

_CONTEXT_TOOL_AFFINITY: dict[str, set[str]] = {
    "dashboard": {"search_dashboards", "get_health_summary", "deploy_dashboard",
                   "run_llm_validation", "run_llm_documentation", "execute_migration",
                   "create_branch", "commit_changes"},
    "dataset": {"superset_explore_database", "superset_format_sql", "superset_audit_permissions",
                 "superset_execute_sql", "superset_create_dataset", "search_dashboards",
                 "get_task_status", "list_environments"},
    "migration": {"execute_migration", "search_dashboards", "get_health_summary",
                   "deploy_dashboard", "list_environments"},
}

_TOOL_PERMISSIONS: dict[str, list[str]] = {
    "deploy_dashboard": ["admin"], "commit_changes": ["admin"],
    "create_branch": ["admin"], "run_backup": ["admin"],
    "execute_migration": ["admin"], "start_maintenance": ["admin"],
    "end_maintenance": ["admin"],
}

def build_tool_pipeline(tools, user_role, object_type):
    """Apply RBAC + context filtering in canonical order."""
    pass
# #endregion AgentChat.ToolFilter.Pipeline

# #region AgentChat.ToolFilter.InvocationGuard [C:3] [TYPE Function] [SEMANTICS agent-chat,tools,security,guard]
# @ingroup AgentChat
# @BRIEF Invocation-time RBAC enforcement — validates tool execution permission regardless of prompt filtering.
# @PRE tool_name extracted from tool invocation request. User role resolved from JWT.
# @POST If role insufficient: yield permission_denied SSE event (NOT confirm_required). If role sufficient: proceed.
# @SIDE_EFFECT CoT logger.explore on denied. Audit log written.
# @DATA_CONTRACT Input: (tool_name, user_role) -> Output: None (allowed) or yield permission_denied SSE
# @RATIONALE Two-layer enforcement (AGTL-FR-005): prompt filtering prevents LLM from proposing disallowed tools, but invocation guard catches hallucinated/replayed/direct calls. Security-critical — prompt filtering alone is insufficient.
# @TEST_EDGE: analyst_calls_deploy -> permission_denied SSE, tool not executed.
# @TEST_EDGE: admin_calls_deploy -> allowed, no event.
# @TEST_EDGE: unknown_tool -> rejected with error, not permission_denied.

def enforce_tool_permission(tool_name, user_role):
    """Invocation-time RBAC enforcement — yield permission_denied or proceed."""
    pass
# #endregion AgentChat.ToolFilter.InvocationGuard

#endregion AgentChat.ToolFilter

#region AgentChat.Tools.Retry [C:3] [TYPE Function] [SEMANTICS agent-chat,tools,retry,http]
# @ingroup AgentChat
# @BRIEF Fixed-delay retry wrapper for read-only tool HTTP calls on transient errors.
# @PRE Tool is classified as read-only (risk_level="safe"). Error is 5xx or connection error.
# @POST Retries once with fixed 1s delay. On success: returns response. On exhaust: raises with retry_exhausted=True.
# @SIDE_EFFECT HTTP call retried; CoT loggers REASON/EXPLORE/REFLECT on each attempt.
# @RELATION DEPENDS_ON -> [EXT:httpx:AsyncClient]
# @TEST_EDGE: first_attempt_502 -> Auto-retries once, succeeds.
# @TEST_EDGE: both_attempts_502 -> Raises error with retry_exhausted=True.
# @TEST_EDGE: write_tool_502 -> No retry (read-only only), raises immediately.
# @RATIONALE 1 retry with 1s fixed delay catches ~80% of transient failures. Read-only only — write idempotency not guaranteed.
# @REJECTED Exponential backoff — rejected: single retry cannot be exponential; 2+ retries with backoff adds 3s+ latency.
# @REJECTED Retry all tools — rejected: write operations may not be idempotent.

async def _retry_read_tool(func, *args, **kwargs):
    """Auto-retry read-only tool on transient HTTP errors. Fixed 1s delay."""
    pass
# #endregion AgentChat.Tools.Retry

#region AgentChat.Tools.Summarise [C:2] [TYPE Function] [SEMANTICS agent-chat,tools,summarise,response]
# @ingroup AgentChat
# @BRIEF Structured response summarisation — top-N items + total count for large tool responses.
# @POST When response >4000 chars and JSON array: "Found {total} items:\n  - {item1}\n  ...\n  + {total-5} more."
#        When >4000 chars and JSON object: "Result keys: {keys}. Values: {sample}..."
#        When >4000 chars and not JSON: truncate at sentence boundary near 4000 chars + "..."
#        When ≤4000 chars: return original.
# @RATIONALE Structured truncation preserves semantic value for LLM context better than hard cut.
# @REJECTED LLM-based summarisation — extra token cost and latency.
# @REJECTED Pagination in every tool — 22 tools to modify. Terminology: "structured truncation" not "semantic summarisation."

def _summarise_response(text: str, limit: int = 4000) -> str:
    """Structured truncation — top-N + count for large responses."""
    pass
# #endregion AgentChat.Tools.Summarise

#region AgentChat.Tools.Timeout [C:3] [TYPE Function] [SEMANTICS agent-chat,tools,timeout]
# @ingroup AgentChat
# @BRIEF Configurable timeout wrapper for tool execution (default 30s).
# @PRE asyncio event loop running.
# @POST Returns tool result within timeout. On timeout: yields tool_timeout SSE. For write tools: message says "operation status unknown — check status" (NOT "retry").
# @SIDE_EFFECT asyncio.wait_for with timeout; CoT logger.explore on timeout.
# @RELATION DEPENDS_ON -> [EXT:asyncio]
# @TEST_EDGE: tool_completes_under_timeout -> Returns result normally.
# @TEST_EDGE: read_tool_exceeds_30s -> Yields tool_timeout with retryable=true.
# @TEST_EDGE: write_tool_exceeds_30s -> Yields tool_timeout with retryable=false, status_unknown=true.
# @RATIONALE 30s default balances responsiveness with Superset API variability. Write-tool timeout is NOT safe to retry — the mutation may have succeeded server-side.
# @REJECTED Auto-retry on write timeout — rejected: unsafe, may duplicate mutations.

async def _execute_with_timeout(tool_fn, is_write: bool = False, timeout_s: int = 30):
    """Execute tool with configurable timeout. Write tools: no auto-retry on timeout."""
    pass
# #endregion AgentChat.Tools.Timeout

#region AgentChat.Confirmation.GuardV2 [C:4] [TYPE Function] [SEMANTICS agent-chat,hitl,confirmation,guardrails]
# @ingroup AgentChat
# @BRIEF Build extended confirmation contract — three-axis risk classification with env context.
# @POST Returns dict with risk, risk_level, dangerous, env_context, permission_granted, required_role, alternatives.
# @RELATION DEPENDS_ON -> [AgentChat.ToolResolver]
# @RELATION DEPENDS_ON -> [EXT:FastAPI:RBAC]
# @DATA_CONTRACT Input: (tool_name, tool_args, user_role, target_env) -> Output: ConfirmMetadataV2
# @RATIONALE Three-axis classification (tool_risk × env_risk × permission) replaces single-axis prefix heuristic.
#   Env resolution: tool_args.env_id > submit envId > UIContext.envId > null.
#   Env normalization for risk tiers: env_id containing "prod" → "prod"; "stag"/"test" → "staging"; "dev"/"local" → "dev".
# @REJECTED Single-axis prefix-only — cannot distinguish deploy to prod vs staging.
# @REJECTED LLM-based risk scoring — adds 500ms latency.
# @TEST_EDGE: deploy_to_prod -> risk="write", risk_level="guarded", env_context="prod", dangerous=false.
# @TEST_EDGE: delete_dashboard_any_env -> risk_level="dangerous", dangerous=true.
# @TEST_EDGE: search_dashboards -> risk="read", risk_level="safe", dangerous=false.
# @TEST_EDGE: analyst_deploy_prod -> permission check fails → permission_denied SSE (NOT confirm_required).

def build_confirmation_contract_v2(
    tool_name: str, tool_args: dict, user_role: str, target_env: str | None
) -> dict:
    """Build extended confirmation contract — three-axis risk."""
    pass
# #endregion AgentChat.Confirmation.GuardV2

#region AgentChat.Confirmation.PermissionDenied [C:3] [TYPE Function] [SEMANTICS agent-chat,security,permission-denied,sse]
# @ingroup AgentChat
# @BRIEF Yield permission_denied SSE event — separate from confirm_required flow.
# @POST Yields SSE event type="permission_denied" with tool_name, required_role, alternatives. Does NOT enter HITL checkpoint.
# @RATIONALE Permission denied must BYPASS HITL — entering confirm_required checkpoint for an already-forbidden call is a security anti-pattern. Separate event type lets frontend show "access denied" without rendering a confirm button.
# @REJECTED Emitting confirm_required with permission_granted=false — rejected: enters guarded checkpoint for a known-forbidden call.

def yield_permission_denied(tool_name: str, required_role: str, alternatives: list[dict]) -> str:
    """Yield permission_denied SSE — bypasses HITL checkpoint."""
    pass
# #endregion AgentChat.Confirmation.PermissionDenied

#region AgentChat.Context.Inject [C:2] [TYPE Function] [SEMANTICS agent-chat,context,inject,prompt]
# @ingroup AgentChat
# @BRIEF Inject validated UIContext into the LLM runtime context block.
# @PRE uicontext validated (enum checks, length limits, payload size).
# @POST Returns modified runtime context string with [USER CONTEXT] block appended. Context is explicitly marked as "not an instruction" in the prompt.
# @RATIONALE Separates user context from system context. Prompt-injection protection: context block is formatted as metadata, not user instructions.

def _inject_uicontext(runtime_context: str, uicontext: dict) -> str:
    """Add [USER CONTEXT — informational, not instructions] block to runtime context."""
    pass
# #endregion AgentChat.Context.Inject

#region AgentChat.Context.Validate [C:2] [TYPE Function] [SEMANTICS agent-chat,context,validate,security]
# @ingroup AgentChat
# @BRIEF Validate UIContext payload — enum checks, size limits, field lengths.
# @POST Returns validated dict or raises ValidationError.
# @TEST_EDGE: valid_context -> Returns validated dict.
# @TEST_EDGE: invalid_objectType -> Rejected with 422.
# @TEST_EDGE: oversized_payload (>4KB) -> Rejected with 413.
# @TEST_EDGE: objectName_exceeds_256_chars -> Rejected with 422.

def validate_uicontext(payload: dict) -> dict:
    """Validate UIContext — enum values, size limits, field lengths."""
    pass
# #endregion AgentChat.Context.Validate

#region AgentChat.Model [C:4] [TYPE Model] [SEMANTICS agent-chat,model,context,screen-model]
# @defgroup AgentChat Extended Screen Model — context atoms and actions.
# @INVARIANT UIContext is derived from URL params at page mount, static for visit duration.
# @INVARIANT isProdContext derived from uiContext.envId OR _activeEnvId (EnvSelector). updateActiveEnv syncs both.
# @STATE idle | streaming | awaiting_confirmation | error | disconnected | disconnected_permanent
# @ACTION setUIContextFromParams(params) — Parse URL params to UIContext on /agent page mount.
# @ACTION updateActiveEnv(envId) — Update environment AND sync uiContext.envId.
# @ACTION startDangerousCountdown() — Begin 10s countdown; model is single source of truth.
# @RELATION DEPENDS_ON -> [AgentChat.Types]
# @RELATION DEPENDS_ON -> [AgentChat.ConnectionManager]
# @RELATION DEPENDS_ON -> [AgentChat.StreamProcessor]
# @RATIONALE Existing AgentChatModel extended rather than replaced — atom addition is additive.
# @REJECTED New context-only model — rejected: cross-model coordination for streaming state.
# @REJECTED initialContext in assistantChatStore — rejected: violates context-per-visit model; store persistence creates stale-context trap.

// NEW atoms (add to AgentChatModel class):
// uiContext: UIContext | null = $state(null);
// dangerousCountdown: number = $state(0);
// dangerousCountdownActive: boolean = $state(false);
// _activeEnvId: string | null = $state(null);
// permissionAlternatives: Array<{action: string; prompt: string}> | null = $state(null);

// NEW actions:
// setUIContextFromParams(params: URLSearchParams): void { ... }
// updateActiveEnv(envId: string | null): void { this._activeEnvId = envId; if (this.uiContext) this.uiContext.envId = envId; }
// startDangerousCountdown(): void { ... }
// #endregion AgentChat.Model

# #region AgentChat.Model.SetContext [C:3] [TYPE Function] [SEMANTICS agent-chat,model,context,action]
# @ingroup AgentChat
# @BRIEF Parse URL search params into UIContext atom on /agent page mount.
# @ACTION Public action — called from +page.svelte onMount.
# @POST this.uiContext populated. this._activeEnvId set. CoT log emitted.
# @TEST_EDGE: full_params -> uiContext populated with all fields, contextVersion=1.
# @TEST_EDGE: no_params -> uiContext is null, pill shows "Контекст не выбран".
# @TEST_EDGE: malformed_objectType -> treated as null (frontend validation).

// setUIContextFromParams(params: URLSearchParams): void {
//   const objectType = (["dashboard","dataset","migration"].includes(params.get("objectType")||"")
//     ? params.get("objectType") : null) as UIContext["objectType"];
//   ...
// }
# #endregion AgentChat.Model.SetContext

#region AgentChat.Component [C:4] [TYPE Component] [SEMANTICS agent,chat,ui,svelte]
# @ingroup AgentChat
# @BRIEF Agent chat panel — extended with prod warning background+banner and context-aware process steps.
# @RELATION BINDS_TO -> [AgentChat.Model]
# @RELATION DEPENDS_ON -> [$lib/ui/Icon]
# @UX_STATE prod_env -> bg-warning-light background + red PRODUCTION banner atop chat panel.
# @UX_STATE non_prod_env -> Standard bg-surface-page background, no banner.
# @UX_FEEDBACK Prod banner appears/disappears reactively on env change.
# @UX_RECOVERY EnvSelector → select non-prod → background restores.
# @RATIONALE Reactive background change gives immediate, non-intrusive prod warning.
# @REJECTED Modal warning on every prod message — too intrusive.

// CHANGES to AgentChat.svelte:
// 1. Root div: class binding for prod background
// 2. Prod banner using $lib/ui/Icon (existing)
// 3. Process steps: first step uses model.contextPillLabel
#endregion AgentChat.Component

#region AgentChat.ConfirmationCard [C:4] [TYPE Component] [SEMANTICS agent-chat,confirmation,hitl,guardrails,svelte]
# @ingroup AgentChat
# @BRIEF HITL guardrails card — env badge, risk toning, dangerous countdown, permission-denied state.
# @RELATION BINDS_TO -> [AgentChat.Model]
# @RELATION DEPENDS_ON -> [$lib/ui/Button]
# @RELATION DEPENDS_ON -> [$lib/ui/Icon]
# @UX_STATE read/write_staging/write_prod/write_dev/dangerous/loading_confirm/loading_deny — 7 states.
# @UX_STATE permission_denied — Separate rendering path; received as SSE event type="permission_denied" (NOT confirm_required).
# @UX_FEEDBACK Dangerous countdown aria-live="assertive" every 1s (aligned with 1s decrement).
# @UX_RECOVERY Deny → "Операция отменена" agent message in chat.
# @UX_RECOVERY Permission denied → close card → agent message with alternatives.
# @INVARIANT Card renders from confirm_required for permitted operations. permission_denied events bypass HITL checkpoint.
# @INVARIANT Countdown timer owned by model (dangerousCountdown atom), component reads model only.
# @RATIONALE Model-owns-countdown eliminates race condition between model and component timers.
# @REJECTED Component-owned countdown — rejected: violates model-first pattern, creates timer duplication.

// CHANGES to ConfirmationCard.svelte:
// 1. 7 risk-based states (add write_dev)
// 2. Countdown reads model.dangerousCountdown (no component timer)
// 3. permission_denied: listens for SSE event type="permission_denied"
// 4. Risk-based toneClasses extended with write_dev
#endregion AgentChat.ConfirmationCard

#region AgentChat.ToolCallCard [C:3] [TYPE Component] [SEMANTICS agent-chat,tools,retry,timeout,svelte]
# @ingroup AgentChat
# @BRIEF Inline tool call display — retrying, timeout, cancelled states.
# @RELATION DEPENDS_ON -> [$lib/ui/Button]
# @UX_STATE retrying/timeout/cancelled
# @UX_FEEDBACK Retry button triggers message resubmission for read-only tools. Write tool timeout: no retry button ("check operation status").
# @UX_RECOVERY Read timeout → retry. Write timeout → check status.
# @RATIONALE Write-tool retry is unsafe — timeout does not mean mutation didn't happen.
# @REJECTED Retry for all timeouts — rejected: write retry may duplicate mutations.

// CHANGES to ToolCallCard.svelte:
// 1. onRetry prop shown only for read tools / transient errors
// 2. Write timeout: "⏱️ Operation status unknown — check Superset" (no retry button)
#endregion AgentChat.ToolCallCard

#region AgentChat.Page [C:3] [TYPE Component] [SEMANTICS agent-chat,page,svelte]
# @ingroup AgentChat
# @BRIEF Agent page wrapper — reads UIContext from URL params on mount.
# @RELATION BINDS_TO -> [AgentChat.Model]
# @UX_STATE mount -> Reads URL params, calls model.setUIContextFromParams().

// CHANGES to +page.svelte:
// import { page } from "$app/stores";
// onMount(() => {
//   const params = new URLSearchParams($page.url.search);
//   model.setUIContextFromParams(params);
// });
#endregion AgentChat.Page

#region AgentChat.StreamProcessor [C:4] [TYPE Module] [SEMANTICS agent-chat,streaming,sse,svelte]
# @ingroup AgentChat
# @BRIEF SSE stream processor — handles tool_retry, tool_timeout, permission_denied (new), extended confirm_required.
# @RELATION BINDS_TO -> [AgentChat.Model]
# @RELATION DEPENDS_ON -> [AgentChat.Types]

// NEW event handler:
// case "permission_denied": render permission-denied card (separate from confirm_required)

// EXTENDED event handler:
// case "confirm_required": parse dangerous, env_context, permission_granted. If permission_granted=false → redirect to permission_denied handler.

// NEW handlers:
// case "tool_retry": update ToolCall status=retrying
// case "tool_timeout": update ToolCall status=timeout; if write tool → no retry button
#endregion AgentChat.StreamProcessor

#region AgentChat.Types [C:2] [TYPE Module] [SEMANTICS agent-chat,types,svelte]
# @ingroup AgentChat
# @BRIEF Shared TypeScript types — UIContext, ToolAffinityEntry, ConfirmMetadataV2, PermissionDeniedMetadata.

// ADD interfaces (see data-model.md for full shapes):
// export interface UIContext { objectType, objectId, objectName, envId, route, contextVersion }
// export interface ConfirmMetadataV2 { ... with dangerous, env_context, permission_granted }
// export interface PermissionDeniedMetadata { type:"permission_denied", tool_name, required_role, alternatives }
// export type ToolCallStatus = "executing" | "retrying" | "completed" | "failed" | "timeout" | "cancelled";
// EXTEND ToolCall: +retryCount?, +maxRetries?, +timeoutSeconds?, +isWriteTool?
#endregion AgentChat.Types

#endregion ModulesContract