#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