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

#region Tasks [C:3] [TYPE ADR] [SEMANTICS tasks,implementation,agent-chat] @defgroup Tasks Implementation tasks for 035-agent-chat-context v2 — Path B model with /agent page, two-layer RBAC, permission_denied flow, and structured truncation.

Input: Design documents from /specs/035-agent-chat-context/ Prerequisites: plan.md ✅, spec.md ✅, research.md ✅, data-model.md ✅, contracts/modules.md ✅

Format: [ID] [P?] [Story] Description

---

Phase 1: Setup

• T001 [P] Materialize API fixtures from specs/035-agent-chat-context/fixtures/api/ into backend/tests/fixtures/agent/
• T002 [P] Materialize model fixtures from specs/035-agent-chat-context/fixtures/model/ into frontend/src/lib/models/__fixtures__/agent/
• T003 Verify toolchain: cd backend && source .venv/bin/activate && python -m pytest --co -q, cd frontend && npm run test -- --run

---

Phase 2: Foundational

• T004 [P] Define UIContext, ConfirmMetadataV2, PermissionDeniedMetadata, extended ToolCall in frontend/src/lib/models/AgentChatTypes.ts @POST: UIContext with objectType, objectId, objectName(string|null max 256), envId, route, contextVersion(1) @POST: PermissionDeniedMetadata {type, tool_name, required_role, user_role, alternatives} @POST: ToolCallStatus extended with "retrying"|"timeout"|"cancelled"; ToolCall +isWriteTool?

• T005 [P] Create backend/src/agent/_context.py — UIContext validation @POST: validate_uicontext(payload) → validated dict or ValidationError @TEST_EDGE: valid→returns, invalid_objectType→422, oversized>4KB→413, objectName>256→422

• T006 Create backend/src/agent/_tool_filter.py — tool selection pipeline + invocation guard @POST: build_tool_pipeline(tools, user_role, object_type) → filtered list. Order: RBAC→context. @POST: enforce_tool_permission(tool_name, user_role) → allowed or yield permission_denied SSE @POST: _CONTEXT_TOOL_AFFINITY dict (dashboard 9, dataset 8, migration 5 tools) @POST: _TOOL_PERMISSIONS dict (7 admin-only tools) @RATIONALE: Ordered pipeline. Two-layer enforcement per AGTL-FR-005. @REJECTED: Embedding-first routing — postponed to post-MVP (AGTL-FR-006).

---

Phase 3: User Story 1 — Context-Aware Agent (P1)

Goal: Agent on /agent page receives context from URL params, filters tools by objectType.

Tests for US1

• T007 [P] [US1] L1 model test for setUIContextFromParams + contextPillLabel in frontend/src/lib/models/__tests__/AgentChatModel.context.test.ts @TEST_FIXTURE: full_params → uiContext populated, pill="📋 dashboard #42 · ss-dev" @TEST_FIXTURE: no_params → uiContext null, pill="⚪ Контекст не выбран" @TEST_FIXTURE: malformed_objectType → treated as null

• T008 [P] [US1] Contract test for agent_handler uicontext in backend/tests/test_agent_context.py @TEST_FIXTURE: null→22 tools, dashboard→9 tools, invalid_json→no error+audit log, malformed_objectType→422

• T009 [P] [US1] Contract test for build_tool_pipeline in backend/tests/test_agent_tool_filter.py @TEST_FIXTURE: null→all RBAC-allowed, dashboard+analyst→dashboard tools minus admin, unknown→graceful fallback

Implementation for US1

• T010 [US1] Implement setUIContextFromParams + contextPillLabel in frontend/src/lib/models/AgentChatModel.svelte.ts @ACTION: parse URLSearchParams, validate objectType enum, set uiContext with contextVersion=1 @POST: contextPillLabel derived: icon+type+id+env or "⚪ Контекст не выбран"

• T011 [US1] Implement onMount context init in frontend/src/routes/agent/+page.svelte @RELATION BINDS_TO -> [AgentChat.Model] import { page } from "$app/stores"; onMount: URLSearchParams($page.url.search) → setUIContextFromParams

• T012 [US1] Implement process steps update in frontend/src/lib/components/agent/AgentChat.svelte First step label uses model.contextPillLabel. Remaining steps unchanged. @RELATION BINDS_TO -> [AgentChat.Model]

• T013 [US1] Implement _inject_uicontext in backend/src/agent/app.py @POST: Appends [USER CONTEXT — informational] block. Explicitly marked "not instructions" for prompt-injection protection.

• T014 [US1] Implement agent_handler uicontext param in backend/src/agent/app.py @PRE: uicontext_str at position 6 (appended, default None). Validated via validate_uicontext. @POST: injected into runtime context. Tools filtered via build_tool_pipeline. @SIDE_EFFECT: UIContext logged via logger.reason. Validation failures logged via logger.explore. RATIONALE: Appended at end — backward-compat for existing 6-arg Gradio clients.

• T015 [P] [US1] Implement isProdContext + showProdWarning + prod banner in frontend/src/lib/models/AgentChatModel.svelte.ts + AgentChat.svelte isProdContext = $derived((uiContext?.envId?.toLowerCase().includes("prod")) || _activeEnvId?.toLowerCase().includes("prod")) Prod banner using <Icon name="warning"> from $lib/ui (existing). bg-warning-light background. @UX_STATE: prod_env→bg-warning-light+banner; non_prod→standard

• T016 [US1] Implement updateActiveEnv in frontend/src/lib/models/AgentChatModel.svelte.ts @ACTION: syncs _activeEnvId AND uiContext.envId to prevent silent desync @POST: both atoms updated. isProdContext $derived recomputes.

Verification for US1

• T017 [US1] Run backend tests: cd backend && source .venv/bin/activate && python -m pytest tests/test_agent_context.py tests/test_agent_tool_filter.py -v
• T018 [US1] Run frontend tests: cd frontend && npm run test -- --run frontend/src/lib/models/__tests__/AgentChatModel.context.test.ts
• T019 [US1] E2E: navigate /dashboards/10?env_id=ss-dev → click Agent → /agent?objectType=dashboard&objectId=10&envId=ss-dev → pill shows dashboard context

---

Phase 4: User Story 2 — Guardrails Refinement (P2)

Goal: Confirmation card with env badge, risk toning, 10s model-owned countdown, permission_denied as separate SSE event.

Tests for US2

• T020 [P] [US2] Contract test for build_confirmation_contract_v2 + permission denied in backend/tests/test_agent_confirmation_v2.py @TEST_FIXTURE: deploy_prod→guarded+prod, delete_any→dangerous, read_only→safe @TEST_FIXTURE: analyst_deploy→permission_denied SSE (NOT confirm_required) @TEST_FIXTURE: env_resolution: tool_args.prod > submit.staging > uiContext.dev

• T021 [P] [US2] L2 UX test for ConfirmationCard 7+1 states in frontend/src/lib/components/assistant/__tests__/ConfirmationCard.ux.test.ts Verify: read→success, write_staging→warning+badge, write_prod→destructive+PROD, write_dev→info Verify: dangerous→destructive+model-owned countdown, permission_denied→muted+lock (separate event)

Implementation for US2

• T022 [US2] Implement build_confirmation_contract_v2 in backend/src/agent/_confirmation.py @POST: three-axis risk. Env resolution: tool_args.env_id>submit envId>UIContext.envId>null. Env normalization via substring match. @DATA_CONTRACT: (tool_name, tool_args, user_role, target_env)→ConfirmMetadataV2 RATIONALE: Three-axis replaces prefix heuristic; env resolution prevents guardrail misclassification.

• T023 [US2] Implement yield_permission_denied in backend/src/agent/_confirmation.py @POST: Yields SSE type="permission_denied" (NOT confirm_required). Bypasses HITL checkpoint. RATIONALE: Security — forbidden calls must not enter guarded checkpoint.

• T024 [US2] Implement enforce_tool_permission invocation guard in backend/src/agent/_tool_filter.py @POST: Called before every tool execution. Checks user_role vs _TOOL_PERMISSIONS. Denied→yield permission_denied. @RATIONALE: Two-layer enforcement — catches hallucinated/replayed/direct calls bypassing prompt filter.

• T025 [US2] Implement ConfirmationCard env badge + 7 risk tones in frontend/src/lib/components/assistant/ConfirmationCard.svelte Uses <Button> from $lib/ui (existing), <Icon> from $lib/ui (existing) @UX_STATE: 7 states (read, write_dev, write_staging, write_prod, dangerous, loading_confirm, loading_deny)

• T026 [US2] Implement model-owned dangerous countdown in frontend/src/lib/models/AgentChatModel.svelte.ts startDangerousCountdown(): setInterval 1s decrement on this.dangerousCountdown. Component reads model atom only. @RATIONALE: Single source of truth — eliminates model/component timer race condition.

• T027 [US2] Implement dangerous countdown UI in frontend/src/lib/components/assistant/ConfirmationCard.svelte Button disabled while model.dangerousCountdown>0. Text: "💀 Удалить (N)". aria-live="assertive" every 1s. Reads model.dangerousCountdown — no component timer.

• T028 [US2] Implement permission_denied handler in frontend/src/lib/models/AgentChat.StreamProcessor.svelte.ts case "permission_denied": render card with 🔒, required_role, alternatives. "Закрыть" only.

• T029 [US2] Implement cancelled tool card for deny flow in frontend/src/lib/models/AgentChat.StreamProcessor.svelte.ts + ToolCallCard.svelte confirm_resolved deny → push ToolCall status="cancelled". Also yield agent message "⏹️ Операция отменена".

Verification for US2

• T030 [US2] Run backend tests: cd backend && source .venv/bin/activate && python -m pytest tests/test_agent_confirmation_v2.py -v
• T031 [US2] Run frontend tests: cd frontend && npm run test -- --run frontend/src/lib/components/assistant/__tests__/ConfirmationCard.ux.test.ts
• T032 [US2] Manual: deploy to prod→destructive+PROD badge. delete→10s countdown. analyst→permission_denied (no confirm button)

---

Phase 5: User Story 3 — Tool Optimisation (P3)

Goal: Fixed-delay retry, structured truncation, configurable timeout (write-safe), invocation RBAC guard.

Tests for US3

• T033 [P] [US3] Contract test for _retry_read_tool in backend/tests/test_agent_retry.py @TEST_FIXTURE: first_502→retries+success, both_502→exhausted, write_tool→no retry

• T034 [P] [US3] Contract test for _summarise_response in backend/tests/test_agent_summarise.py array 50→"Found 50...+45 more", object→keys+sample, text→sentence-boundary truncation, short→unchanged

• T035 [P] [US3] Contract test for _execute_with_timeout in backend/tests/test_agent_timeout.py @TEST_EDGE: complete_under→normal, read_exceed→retryable timeout, write_exceed→retryable=false status_unknown

• T036 [P] [US3] L2 UX test for ToolCallCard states in frontend/src/lib/components/assistant/__tests__/ToolCallCard.ux.test.ts retrying→spinner+attempt, read_timeout→⏱️+retry button, write_timeout→⏱️+"check status" (no retry), cancelled→🚫

Implementation for US3

• T037 [US3] Implement _retry_read_tool in backend/src/agent/tools.py @PRE: tool risk_level="safe". Error 5xx/ConnectError. Fixed 1s asyncio.sleep. @POST: retry once. Yields tool_retry SSE. Exhaust→raises retry_exhausted. RATIONALE: Single fixed retry catches ~80% transient failures. Read-only only.

• T038 [US3] Implement _summarise_response in backend/src/agent/tools.py @POST: >4000 chars + JSON array→"Found N: -item1...+ (N-5) more". Object→keys+sample. Text→sentence-boundary cut. RATIONALE: Structured truncation preserves context better than hard cut.

• T039 [US3] Implement _execute_with_timeout in backend/src/agent/tools.py @PRE: asyncio.wait_for(tool_fn, 30s). is_write param. @POST: timeout→tool_timeout SSE. Write: is_write_tool=true, retryable=false. RATIONALE: Write tool timeout ≠ mutation didn't happen. No retry — check status instead.

• T040 [US3] Implement tool_retry + tool_timeout handlers in frontend/src/lib/models/AgentChat.StreamProcessor.svelte.ts case "tool_retry": ToolCall status="retrying". case "tool_timeout": status="timeout", isWriteTool→no retry button.

• T041 [US3] Implement retry+timeout states in frontend/src/lib/components/assistant/ToolCallCard.svelte retrying: "Повторная попытка... ({N}/{M})". Read timeout: ⏱️+retry btn. Write timeout: ⏱️+"Operation status unknown" (no btn). Uses <Button variant="secondary" size="xs"> from $lib/ui (existing).

• T042 [US3] Implement debug panel context sections in frontend/src/lib/components/agent/AgentChat.svelte Add "Контекст страницы" (JSON.stringify uiContext) + "Pipeline" (effective tool list after filtering) sections to debug panel. Tool list data comes from backend SSE debug event (pipeline_result) — NOT frontend reconstruction.

Verification for US3

• T043 [US3] Run backend tests: cd backend && source .venv/bin/activate && python -m pytest tests/test_agent_retry.py tests/test_agent_summarise.py tests/test_agent_timeout.py -v
• T044 [US3] Run frontend tests: cd frontend && npm run test -- --run frontend/src/lib/components/assistant/__tests__/ToolCallCard.ux.test.ts
• T045 [US3] Manual: 502→auto-retry→success. Large→top-5. Analyst→write tools excluded+invocation guard active.

---

Phase 6: Polish & Cross-Cutting

• T046 [P] Full backend: cd backend && source .venv/bin/activate && python -m pytest -v
• T047 [P] Full frontend: cd frontend && npm run test
• T048 [P] Backend lint: cd backend && python -m ruff check .
• T049 [P] Frontend lint: cd frontend && npm run lint
• T050 [P] Frontend build: cd frontend && npm run build
• T051 Attention compliance audit — verify ATTN_1-4 on all new/changed contracts
• T052 E2E verification per quickstart.md
• T053 Run quickstart validation

---

Dependencies

Phase 1 → Phase 2 → US1(P1) → US2(P2) ∥ US3(P3) → Phase 6

US2 and US3 can proceed in parallel after US1 base.

Parallel Opportunities

Phase 1: T001∥T002 | Phase 2: T004∥T005∥T006 | US1: T007∥T008∥T009, T015∥(T010→T011) | US2: T020∥T021 | US3: T033∥T034∥T035∥T036 | Phase 6: T046∥T047∥T048∥T049∥T050

Notes

• Gradio uicontext at position END (6), not middle — backward-compat
• Permission denied: SSE type="permission_denied", bypasses HITL
• Countdown: model-owned, component reads only
• Write timeout: no retry
• No initialContext in store — context from URL params only
• RBAC: two-layer (prompt filter + invocation guard)

#endregion Tasks