From 789b658a1c022cd0c2e130e37e2ff1e7ed8816e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Flor=C3=AAncio?= Date: Thu, 30 Jul 2026 14:47:49 +0100 Subject: [PATCH] feat: distinguish workflow completion in task sidebar (#2058) --- .../task/chat/message-list-native.tsx | 16 ++- apps/web/components/task/task-item.test.tsx | 39 ++++--- apps/web/components/task/task-item.tsx | 19 ++- .../task-session-sidebar-aggregate.test.ts | 10 +- .../task/task-session-sidebar-aggregate.ts | 7 +- .../components/task/task-switcher.test.tsx | 72 +++++++++++- apps/web/components/task/task-switcher.tsx | 8 +- apps/web/e2e/pages/session-page.ts | 21 +++- .../e2e/tests/chat/auto-scroll-toggle.spec.ts | 11 +- ...e-sidebar-workflow-completion-icon.spec.ts | 62 ++++++++++ .../task/sidebar-settled-spinner.spec.ts | 4 +- .../sidebar-workflow-completion-icon.spec.ts | 58 +++++++++ .../sidebar-task-completion-icons/plan.md | 110 ++++++++++++++++++ .../task-01-sidebar-completion-icons.md | 97 +++++++++++++++ docs/specs/INDEX.md | 1 + .../specs/ui/sidebar-task-completion-icons.md | 51 ++++++++ 16 files changed, 544 insertions(+), 42 deletions(-) create mode 100644 apps/web/e2e/tests/task/mobile-sidebar-workflow-completion-icon.spec.ts create mode 100644 apps/web/e2e/tests/task/sidebar-workflow-completion-icon.spec.ts create mode 100644 docs/plans/sidebar-task-completion-icons/plan.md create mode 100644 docs/plans/sidebar-task-completion-icons/task-01-sidebar-completion-icons.md create mode 100644 docs/specs/ui/sidebar-task-completion-icons.md diff --git a/apps/web/components/task/chat/message-list-native.tsx b/apps/web/components/task/chat/message-list-native.tsx index 0ca1141357..a86da7ad86 100644 --- a/apps/web/components/task/chat/message-list-native.tsx +++ b/apps/web/components/task/chat/message-list-native.tsx @@ -210,11 +210,10 @@ function NativeMessageListBody({ footerActionMessages={footerActionMessages} /> - {/* Bottom anchor — browser keeps scroll pinned here when new content - appends, but only while auto-scroll is enabled: without disabling - the anchor too, the browser's native scroll-anchoring keeps - tracking the bottom on its own and defeats the toggle for a user - who disables from the current bottom. */} + {/* Bottom anchor keeps the view pinned while auto-scroll is enabled. + The scroll container disables anchoring entirely while it is off, + so status/footer updates cannot choose a different anchor and move + the frozen transcript. */}
); @@ -287,7 +286,12 @@ export const NativeMessageList = memo( ); return ( - + {stickyPromptBar} { - it("keeps the review check when the session is idle after a turn", () => { + it("shows a dashed progress check when the session is idle after a non-final turn", () => { renderTaskItem({ sessionState: "WAITING_FOR_INPUT" }); - expect(screen.queryByTestId(REVIEW_ICON_TEST_ID)).not.toBeNull(); + expect(screen.queryByTestId(TURN_FINISHED_ICON_TEST_ID)).not.toBeNull(); + expect(screen.queryByTestId(WORKFLOW_COMPLETE_ICON_TEST_ID)).toBeNull(); expect(screen.queryByTestId(WAITING_FOR_INPUT_ICON_TEST_ID)).toBeNull(); }); + it("shows the continuous check when the finished turn is on the final workflow step", () => { + renderTaskItem({ sessionState: "COMPLETED", isOnLastWorkflowStep: true }); + + expect(screen.queryByTestId(WORKFLOW_COMPLETE_ICON_TEST_ID)).not.toBeNull(); + expect(screen.queryByTestId(TURN_FINISHED_ICON_TEST_ID)).toBeNull(); + }); + it("shows question icon when a clarification is pending", () => { renderTaskItem({ sessionState: "WAITING_FOR_INPUT", hasPendingClarification: true }); expect(screen.queryByTestId(WAITING_FOR_INPUT_ICON_TEST_ID)).not.toBeNull(); - expect(screen.queryByTestId(REVIEW_ICON_TEST_ID)).toBeNull(); + expect(screen.queryByTestId(TURN_FINISHED_ICON_TEST_ID)).toBeNull(); }); it("shows question icon when task state is waiting for input", () => { renderTaskItem({ state: "WAITING_FOR_INPUT", hasPendingClarification: false }); expect(screen.queryByTestId(WAITING_FOR_INPUT_ICON_TEST_ID)).not.toBeNull(); - expect(screen.queryByTestId(REVIEW_ICON_TEST_ID)).toBeNull(); + expect(screen.queryByTestId(TURN_FINISHED_ICON_TEST_ID)).toBeNull(); }); it("shows alert icon when a permission request is pending", () => { renderTaskItem({ sessionState: "WAITING_FOR_INPUT", hasPendingPermission: true }); expect(screen.queryByTestId(PENDING_PERMISSION_ICON_TEST_ID)).not.toBeNull(); - expect(screen.queryByTestId(REVIEW_ICON_TEST_ID)).toBeNull(); + expect(screen.queryByTestId(TURN_FINISHED_ICON_TEST_ID)).toBeNull(); expect(screen.queryByTestId(WAITING_FOR_INPUT_ICON_TEST_ID)).toBeNull(); }); @@ -125,7 +134,7 @@ describe("TaskItem status icon", () => { it("does not show preparing spinner for a review task whose session transiently hits STARTING", () => { renderTaskItem({ state: "REVIEW", sessionState: "STARTING" }); - expect(screen.queryByTestId(REVIEW_ICON_TEST_ID)).not.toBeNull(); + expect(screen.queryByTestId(TURN_FINISHED_ICON_TEST_ID)).not.toBeNull(); expect(screen.queryByTestId(RUNNING_ICON_TEST_ID)).toBeNull(); }); @@ -139,10 +148,10 @@ describe("TaskItem status icon", () => { expect(icon.classList.contains(PREPARING_SPINNER_CLASS)).toBe(false); }); - it("keeps the review check for completed review tasks", () => { + it("shows a progress check for completed review tasks without final-step context", () => { renderTaskItem({ sessionState: "COMPLETED" }); - expect(screen.queryByTestId(REVIEW_ICON_TEST_ID)).not.toBeNull(); + expect(screen.queryByTestId(TURN_FINISHED_ICON_TEST_ID)).not.toBeNull(); expect(screen.queryByTestId(WAITING_FOR_INPUT_ICON_TEST_ID)).toBeNull(); }); @@ -152,7 +161,7 @@ describe("TaskItem status icon", () => { const errorIcon = screen.getByTestId(AGENT_ERROR_ICON_TEST_ID); expect(errorIcon).not.toBeNull(); expect(errorIcon.classList.contains("cursor-help")).toBe(true); - expect(screen.queryByTestId(REVIEW_ICON_TEST_ID)).not.toBeNull(); + expect(screen.queryByTestId(TURN_FINISHED_ICON_TEST_ID)).not.toBeNull(); }); }); @@ -194,7 +203,7 @@ describe("TaskItem background-running indicator", () => { expect(icon.parentElement?.classList.contains("focus-visible:ring-2")).toBe(true); expect(screen.getByLabelText("Background work is running")).not.toBeNull(); expect(screen.queryByTestId(RUNNING_ICON_TEST_ID)).toBeNull(); - expect(screen.queryByTestId(REVIEW_ICON_TEST_ID)).toBeNull(); + expect(screen.queryByTestId(TURN_FINISHED_ICON_TEST_ID)).toBeNull(); }); it("reads background from the task aggregate even when the most-active client session is done", () => { @@ -209,7 +218,7 @@ describe("TaskItem background-running indicator", () => { }); expect(screen.queryByTestId(BACKGROUND_ICON_TEST_ID)).not.toBeNull(); - expect(screen.queryByTestId(REVIEW_ICON_TEST_ID)).toBeNull(); + expect(screen.queryByTestId(TURN_FINISHED_ICON_TEST_ID)).toBeNull(); }); it("shows pending clarification instead of background-running", () => { @@ -259,7 +268,7 @@ describe("TaskItem background-running indicator", () => { hasPendingPermission: true, }); - expect(screen.queryByTestId(REVIEW_ICON_TEST_ID)).toBeNull(); + expect(screen.queryByTestId(TURN_FINISHED_ICON_TEST_ID)).toBeNull(); expect(screen.queryByTestId(PENDING_PERMISSION_ICON_TEST_ID)).not.toBeNull(); expect(screen.queryByTestId(WAITING_FOR_INPUT_ICON_TEST_ID)).toBeNull(); }); @@ -277,7 +286,7 @@ describe("TaskItem background-running indicator", () => { expect(icon.getAttribute(DATA_LOADING_PHASE)).toBe(RUNNING_PHASE); expect(icon.classList.contains(YELLOW_SPINNER_CLASS)).toBe(true); expect(screen.queryByTestId(BACKGROUND_ICON_TEST_ID)).toBeNull(); - expect(screen.queryByTestId(REVIEW_ICON_TEST_ID)).toBeNull(); + expect(screen.queryByTestId(TURN_FINISHED_ICON_TEST_ID)).toBeNull(); }); it("falls back to the generating spinner when the aggregate substate is unknown", () => { @@ -337,7 +346,7 @@ describe("TaskItem background-running lifecycle", () => { , ); - expect(screen.queryByTestId(REVIEW_ICON_TEST_ID)).not.toBeNull(); + expect(screen.queryByTestId(TURN_FINISHED_ICON_TEST_ID)).not.toBeNull(); expect(screen.queryByTestId(BACKGROUND_ICON_TEST_ID)).toBeNull(); expect(screen.queryByTestId(RUNNING_ICON_TEST_ID)).toBeNull(); }); diff --git a/apps/web/components/task/task-item.tsx b/apps/web/components/task/task-item.tsx index 3d035b3c20..c9359a2a5e 100644 --- a/apps/web/components/task/task-item.tsx +++ b/apps/web/components/task/task-item.tsx @@ -9,6 +9,7 @@ import { IconDots, IconGitPullRequest, IconMessageQuestion, + IconProgressCheck, IconPinFilled, IconShieldQuestion, } from "@tabler/icons-react"; @@ -68,6 +69,8 @@ type TaskItemProps = { hasPendingPermission?: boolean; parentTaskTitle?: string; isSubTask?: boolean; + /** Whether the task is currently on the final ordered step of its workflow. */ + isOnLastWorkflowStep?: boolean; /** * Nesting depth in the sidebar tree (0 = root). Drives left indentation so * arbitrarily deep subtask trees read as a hierarchy. Falls back to @@ -194,6 +197,7 @@ function TaskStateIcon({ isInProgress, hasPendingClarification, hasPendingPermission, + isOnLastWorkflowStep, }: { sessionState?: TaskSessionState; state?: TaskState; @@ -201,6 +205,7 @@ function TaskStateIcon({ isInProgress: boolean; hasPendingClarification?: boolean; hasPendingPermission?: boolean; + isOnLastWorkflowStep?: boolean; }) { if (shouldUsePermissionTaskIcon(hasPendingPermission)) { return ( @@ -259,9 +264,17 @@ function TaskStateIcon({ ); } if (classifyTask(sessionState, state) === "review") { + if (isOnLastWorkflowStep) { + return ( + + ); + } return ( - ); @@ -478,6 +491,7 @@ export const TaskItem = memo(function TaskItem({ issueInfo, isPinned, agentErrorMessage, + isOnLastWorkflowStep = false, }: TaskItemProps) { const effectiveMenuOpen = menuOpen || isDeleting === true; const isInProgress = computeIsInProgress(state, sessionState); @@ -506,6 +520,7 @@ export const TaskItem = memo(function TaskItem({ isInProgress={isInProgress} hasPendingClarification={hasPendingClarification} hasPendingPermission={hasPendingPermission} + isOnLastWorkflowStep={isOnLastWorkflowStep} /> { expect(result.allTasks.find((t) => t.id === "t2")).toBeDefined(); }); - it("does not overwrite snapshot steps when the workflow already has a snapshot", () => { + it("prefers live active steps when the workflow snapshot is stale", () => { const snapshots: WorkflowSnapshotMap = { "wf-1": makeSnapshot([makeStep("s1", 0, { title: "Snapshot Step" })], []), }; @@ -117,9 +117,13 @@ describe("aggregateSidebarTasks", () => { snapshots, "wf-1", [], - [makeStep("s1", 0, { title: "Active Step" })], + [makeStep("s1", 2, { title: "Active Step" })], ); - expect(result.stepsByWorkflowId["wf-1"][0].title).toBe("Snapshot Step"); + expect(result.stepsByWorkflowId["wf-1"][0].title).toBe("Active Step"); + expect(result.allSteps.find((step) => step.id === "s1")).toMatchObject({ + title: "Active Step", + position: 2, + }); }); it("deduplicates steps across workflows by id", () => { diff --git a/apps/web/components/task/task-session-sidebar-aggregate.ts b/apps/web/components/task/task-session-sidebar-aggregate.ts index c31de73ddc..e209a39cd5 100644 --- a/apps/web/components/task/task-session-sidebar-aggregate.ts +++ b/apps/web/components/task/task-session-sidebar-aggregate.ts @@ -99,8 +99,11 @@ function applyActiveKanbanFallback( activeSteps: KanbanState["steps"], acc: Acc, ): void { - if (!acc.wfSteps[activeWorkflowId] && activeSteps.length > 0) { - for (const step of activeSteps) if (!acc.stepMap.has(step.id)) acc.stepMap.set(step.id, step); + // The active kanban slice receives live workflow-step WS updates. Prefer it + // over an existing snapshot so completion icons reflect creates, deletes, + // and reorders without waiting for the next full snapshot refresh. + if (activeSteps.length > 0) { + for (const step of activeSteps) acc.stepMap.set(step.id, step); acc.wfSteps[activeWorkflowId] = [...activeSteps].sort((a, b) => a.position - b.position); } // Hydrator's mergeKanbanTasks accumulates tasks across workflow switches, so diff --git a/apps/web/components/task/task-switcher.test.tsx b/apps/web/components/task/task-switcher.test.tsx index 034f694f96..4c211e94dd 100644 --- a/apps/web/components/task/task-switcher.test.tsx +++ b/apps/web/components/task/task-switcher.test.tsx @@ -1,5 +1,5 @@ import { afterEach, describe, expect, it, vi } from "vitest"; -import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react"; +import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react"; import { StateProvider } from "@/components/state-provider"; import { ToastProvider } from "@/components/toast-provider"; import { TaskSwitcher, type TaskSwitcherItem } from "./task-switcher"; @@ -16,8 +16,12 @@ function Providers({ children }: { children: React.ReactNode }) { ); } -function item(id: string, parentTaskId?: string): TaskSwitcherItem { - return { id, title: id, state: "IN_PROGRESS", parentTaskId }; +function item( + id: string, + parentTaskId?: string, + overrides: Partial = {}, +): TaskSwitcherItem { + return { id, title: id, state: "IN_PROGRESS", parentTaskId, ...overrides }; } // root → child → grandchild (depth 2) @@ -140,6 +144,68 @@ describe("TaskSwitcher — nested subtasks beyond depth 1", () => { }); }); +describe("TaskSwitcher — workflow completion icons", () => { + it("derives workflow completion from the final ordered step for each task", () => { + const finalStepId = "step-final"; + const groupedTasks = [ + item("Turn finished", undefined, { + state: "REVIEW", + sessionState: "COMPLETED", + workflowId: "workflow-1", + workflowStepId: "step-middle", + }), + item("Workflow complete", undefined, { + state: "REVIEW", + sessionState: "COMPLETED", + workflowId: "workflow-1", + workflowStepId: finalStepId, + }), + item("Missing workflow metadata", undefined, { + state: "REVIEW", + sessionState: "COMPLETED", + }), + ]; + + render( + + + , + ); + + const turnFinishedRow = screen + .getByText("Turn finished") + .closest("[data-testid='sidebar-task-item']"); + const workflowCompleteRow = screen + .getByText("Workflow complete") + .closest("[data-testid='sidebar-task-item']"); + const missingMetadataRow = screen + .getByText("Missing workflow metadata") + .closest("[data-testid='sidebar-task-item']"); + + expect(within(turnFinishedRow!).getByTestId("task-state-turn-finished")).toBeTruthy(); + expect(within(turnFinishedRow!).queryByTestId("task-state-workflow-complete")).toBeNull(); + expect(within(workflowCompleteRow!).getByTestId("task-state-workflow-complete")).toBeTruthy(); + expect(within(workflowCompleteRow!).queryByTestId("task-state-turn-finished")).toBeNull(); + expect(within(missingMetadataRow!).getByTestId("task-state-turn-finished")).toBeTruthy(); + expect(within(missingMetadataRow!).queryByTestId("task-state-workflow-complete")).toBeNull(); + }); +}); + describe("TaskSwitcher — bulk pin menu", () => { it("offers bulk unpin when every selected root task is pinned", () => { render( diff --git a/apps/web/components/task/task-switcher.tsx b/apps/web/components/task/task-switcher.tsx index 8f6eb52676..3e302ff6ab 100644 --- a/apps/web/components/task/task-switcher.tsx +++ b/apps/web/components/task/task-switcher.tsx @@ -223,9 +223,8 @@ function TaskRow({ ...props }: TaskRowProps) { const isSelected = task.id === selectedTaskId || task.id === activeTaskId; - const isMultiSelected = selectedTaskIds?.has(task.id) ?? false; - const isSelecting = (selectedTaskIds?.size ?? 0) > 0; const taskSteps = task.workflowId ? stepsByWorkflowId?.[task.workflowId] : undefined; + const stepId = task.workflowStepId; return ( - dispatchSidebarRowClick(e, task.id, isSelecting, { + dispatchSidebarRowClick(e, task.id, (selectedTaskIds?.size ?? 0) > 0, { onSelectTask, onToggleSelectTask, onSelectTaskRange, @@ -280,6 +279,7 @@ function TaskRow({ issueInfo={task.issueInfo} agentErrorMessage={task.agentErrorMessage} isSubTask={isSubTask} + isOnLastWorkflowStep={!!stepId && taskSteps?.at(-1)?.id === stepId} depth={depth} subtaskCount={subtaskToggle?.subtaskCount} subtasksCollapsed={subtaskToggle?.subtasksCollapsed} diff --git a/apps/web/e2e/pages/session-page.ts b/apps/web/e2e/pages/session-page.ts index 1e7510c508..be04af2b2d 100644 --- a/apps/web/e2e/pages/session-page.ts +++ b/apps/web/e2e/pages/session-page.ts @@ -1,9 +1,9 @@ import { type Locator, type Page, expect } from "@playwright/test"; -/** Maps old state-section labels to the new per-task state icon data-testid. */ +/** Maps state-section labels to the per-task state icon data-testid. */ function sectionLabelToStateTestId(label: string): string { if (label === "Running") return "task-state-running"; - if (label === "Turn Finished") return "task-state-review"; + if (label === "Turn Finished") return "task-state-turn-finished"; return "task-state-backlog"; } @@ -286,6 +286,13 @@ export class SessionPage { * Accepts "Turn Finished" (review/completed), "Running" (in-progress), or "Backlog". */ sidebarSection(label: string): Locator { + if (label === "Turn Finished") { + return this.sidebar + .locator( + '[data-testid="task-state-turn-finished"], [data-testid="task-state-workflow-complete"]', + ) + .first(); + } const testId = sectionLabelToStateTestId(label); return this.sidebar.getByTestId(testId).first(); } @@ -295,6 +302,16 @@ export class SessionPage { * Accepts "Turn Finished" (review/completed), "Running" (in-progress), or "Backlog". */ taskInSection(title: string, sectionLabel: string): Locator { + if (sectionLabel === "Turn Finished") { + return this.sidebar + .getByTestId("sidebar-task-item") + .filter({ has: this.page.getByText(title, { exact: false }) }) + .filter({ + has: this.page.locator( + '[data-testid="task-state-turn-finished"], [data-testid="task-state-workflow-complete"]', + ), + }); + } const testId = sectionLabelToStateTestId(sectionLabel); return this.sidebar .getByTestId("sidebar-task-item") diff --git a/apps/web/e2e/tests/chat/auto-scroll-toggle.spec.ts b/apps/web/e2e/tests/chat/auto-scroll-toggle.spec.ts index b1bc82984a..d0cb6572d5 100644 --- a/apps/web/e2e/tests/chat/auto-scroll-toggle.spec.ts +++ b/apps/web/e2e/tests/chat/auto-scroll-toggle.spec.ts @@ -146,10 +146,12 @@ test.describe("Transcript auto-scroll toggle", () => { await waitForOverflow(testPage); const list = chatList(testPage); - // The renderer auto-scrolls to the bottom by default, so this should - // already hold — assert it explicitly so the test fails loudly if that - // assumption ever breaks instead of silently passing for the wrong - // reason. + // A task can become idle just before the final layout settles. Explicitly + // place the view at the bottom so this test isolates the disabled-at-bottom + // behavior instead of relying on that timing. + await list.evaluate((el) => { + el.scrollTop = el.scrollHeight; + }); await expect .poll(async () => list.evaluate((el) => el.scrollHeight - el.scrollTop - el.clientHeight), { timeout: 5_000, @@ -161,6 +163,7 @@ test.describe("Transcript auto-scroll toggle", () => { const toggle = session.chatStatusBar().getByTestId("auto-scroll-toggle-button"); await toggle.click(); await expect(toggle).toHaveAttribute("aria-pressed", "false"); + await expect(list).toHaveCSS("overflow-anchor", "none"); // A new message arrives while disabled from the true bottom. The // browser's native bottom overflow-anchor must not override the diff --git a/apps/web/e2e/tests/task/mobile-sidebar-workflow-completion-icon.spec.ts b/apps/web/e2e/tests/task/mobile-sidebar-workflow-completion-icon.spec.ts new file mode 100644 index 0000000000..235e91a9c1 --- /dev/null +++ b/apps/web/e2e/tests/task/mobile-sidebar-workflow-completion-icon.spec.ts @@ -0,0 +1,62 @@ +import { expect, test } from "../../fixtures/test-base"; +import { SessionPage } from "../../pages/session-page"; + +test.describe("Mobile sidebar workflow completion icons", () => { + test("keeps the finished-turn distinction in the phone task drawer", async ({ + testPage, + apiClient, + seedData, + prCapture, + }) => { + const finalSeedStep = seedData.steps.at(-1); + if (!finalSeedStep) throw new Error("seed workflow has no steps"); + + const finalStep = await apiClient.createWorkflowStep( + seedData.workflowId, + "Mobile completion icon final step", + finalSeedStep.position + 1, + ); + const turnFinishedTask = await apiClient.seedTask( + seedData.workspaceId, + "Mobile sidebar turn finished", + { + workflow_id: seedData.workflowId, + workflow_step_id: seedData.startStepId, + state: "REVIEW", + }, + ); + const workflowCompleteTask = await apiClient.seedTask( + seedData.workspaceId, + "Mobile sidebar workflow complete", + { + workflow_id: seedData.workflowId, + workflow_step_id: finalStep.id, + state: "REVIEW", + }, + ); + + await testPage.goto(`/t/${workflowCompleteTask.task_id}`); + const session = new SessionPage(testPage); + await session.waitForLoad(); + await testPage.getByTestId("mobile-session-menu").tap(); + + const drawer = testPage.getByRole("dialog", { name: "Tasks" }); + const turnFinishedRow = drawer.getByTestId("sidebar-task-item").filter({ + hasText: "Mobile sidebar turn finished", + }); + const workflowCompleteRow = drawer.getByTestId("sidebar-task-item").filter({ + hasText: "Mobile sidebar workflow complete", + }); + await expect(turnFinishedRow).toBeVisible(); + await expect(workflowCompleteRow).toBeVisible(); + await expect(turnFinishedRow.getByTestId("task-state-turn-finished")).toBeVisible(); + await expect(workflowCompleteRow.getByTestId("task-state-workflow-complete")).toBeVisible(); + await expect(turnFinishedRow.getByTestId("task-state-workflow-complete")).toHaveCount(0); + await expect(workflowCompleteRow.getByTestId("task-state-turn-finished")).toHaveCount(0); + + expect(workflowCompleteTask.task_id).not.toBe(turnFinishedTask.task_id); + await prCapture.screenshot("mobile-sidebar-workflow-completion-icons", { + caption: "Mobile task drawer distinguishes a finished turn from workflow completion.", + }); + }); +}); diff --git a/apps/web/e2e/tests/task/sidebar-settled-spinner.spec.ts b/apps/web/e2e/tests/task/sidebar-settled-spinner.spec.ts index bdfeecb27b..106a8aa4c6 100644 --- a/apps/web/e2e/tests/task/sidebar-settled-spinner.spec.ts +++ b/apps/web/e2e/tests/task/sidebar-settled-spinner.spec.ts @@ -96,6 +96,8 @@ test.describe("Sidebar spinner clears when a session settles", () => { }); // Settled turn with no pending clarification buckets into "review". - await expect(settledRow.getByTestId("task-state-review")).toBeVisible({ timeout: 10_000 }); + await expect(settledRow.getByTestId("task-state-turn-finished")).toBeVisible({ + timeout: 10_000, + }); }); }); diff --git a/apps/web/e2e/tests/task/sidebar-workflow-completion-icon.spec.ts b/apps/web/e2e/tests/task/sidebar-workflow-completion-icon.spec.ts new file mode 100644 index 0000000000..597c7ee32c --- /dev/null +++ b/apps/web/e2e/tests/task/sidebar-workflow-completion-icon.spec.ts @@ -0,0 +1,58 @@ +import { expect, test } from "../../fixtures/test-base"; +import { SessionPage } from "../../pages/session-page"; + +test.describe("Sidebar workflow completion icons", () => { + test("distinguishes a finished turn from a completed workflow", async ({ + testPage, + apiClient, + seedData, + prCapture, + }) => { + const finalSeedStep = seedData.steps.at(-1); + if (!finalSeedStep) throw new Error("seed workflow has no steps"); + + const finalStep = await apiClient.createWorkflowStep( + seedData.workflowId, + "Completion icon final step", + finalSeedStep.position + 1, + ); + const turnFinishedTask = await apiClient.seedTask( + seedData.workspaceId, + "Sidebar turn finished", + { + workflow_id: seedData.workflowId, + workflow_step_id: seedData.startStepId, + state: "REVIEW", + }, + ); + const workflowCompleteTask = await apiClient.seedTask( + seedData.workspaceId, + "Sidebar workflow complete", + { + workflow_id: seedData.workflowId, + workflow_step_id: finalStep.id, + state: "REVIEW", + }, + ); + + await testPage.goto(`/t/${workflowCompleteTask.task_id}`); + const session = new SessionPage(testPage); + await session.waitForLoad(); + + const turnFinishedRow = session.sidebarTaskItem("Sidebar turn finished"); + const workflowCompleteRow = session.sidebarTaskItem("Sidebar workflow complete"); + await expect(turnFinishedRow).toBeVisible(); + await expect(workflowCompleteRow).toBeVisible(); + await expect(turnFinishedRow.getByTestId("task-state-turn-finished")).toBeVisible(); + await expect(turnFinishedRow.getByTestId("task-state-workflow-complete")).toHaveCount(0); + await expect(workflowCompleteRow.getByTestId("task-state-workflow-complete")).toBeVisible(); + await expect(workflowCompleteRow.getByTestId("task-state-turn-finished")).toHaveCount(0); + + // Keep the created task referenced so the route setup remains explicit if the fixture + // changes its task cleanup behavior. + expect(workflowCompleteTask.task_id).not.toBe(turnFinishedTask.task_id); + await prCapture.screenshot("desktop-sidebar-workflow-completion-icons", { + caption: "Desktop task sidebar distinguishes a finished turn from workflow completion.", + }); + }); +}); diff --git a/docs/plans/sidebar-task-completion-icons/plan.md b/docs/plans/sidebar-task-completion-icons/plan.md new file mode 100644 index 0000000000..0ebae1be22 --- /dev/null +++ b/docs/plans/sidebar-task-completion-icons/plan.md @@ -0,0 +1,110 @@ +--- +spec: docs/specs/ui/sidebar-task-completion-icons.md +created: 2026-07-30 +status: completed +--- + +# Implementation Plan: Sidebar Task Completion Icons + +## Overview + +Use the workflow-step ordering already loaded by the shared task switcher to distinguish a +finished turn from a finished workflow. The change remains frontend-only: derive final-step +membership while rendering each shared row, select the appropriate Tabler icon in `TaskItem`, +and prove the behavior in unit tests and both desktop and phone task-switcher surfaces. + +## Frontend + +### Shared task-row derivation + +- In `apps/web/components/task/task-switcher.tsx`, compare each task's `workflowStepId` with the + last entry in `stepsByWorkflowId[task.workflowId]`. +- Pass the result into `TaskItem`. An absent workflow, absent step list, empty step list, or + unmatched step resolves to `false`, so incomplete information never claims workflow + completion. +- Reuse the ordered step arrays produced by `aggregateSidebarTasks`; no store, API, or snapshot + shape changes are needed. + +### Completion icon rendering + +- In `apps/web/components/task/task-item.tsx`, add `IconProgressCheck` from + `@tabler/icons-react`. +- In the existing `classifyTask(...) === "review"` branch, render the current green + `IconCircleCheck` only when the task is on its workflow's last step. Otherwise render the + green `IconProgressCheck`. +- Give the two states stable semantic test selectors and migrate existing sidebar status tests + from the generic review selector. Keep the established icon size, alignment, and green color. +- Leave the permission, clarification, foreground/background activity, preparing, running, and + backlog branches unchanged and ahead of completion rendering. + +## Tests + +- **What:** a finished turn on a non-final or unknown step renders `progress-check`, while the + same state on the final step renders `circle-check`. + **Files:** `apps/web/components/task/task-item.test.tsx` and + `apps/web/components/task/task-switcher.test.tsx`. + **How:** component tests cover icon selection and verify that the switcher derives final-step + membership from the task's own workflow steps. +- **What:** active and pending states still override either completion icon. + **File:** `apps/web/components/task/task-item.test.tsx`. + **How:** retain and update the existing precedence tests. + +## E2E Tests + +- **Scenario:** finished tasks on non-final and final steps show the dashed progress check and + continuous completion check in the desktop sidebar. + **File:** `apps/web/e2e/tests/task/sidebar-workflow-completion-icon.spec.ts`. + **What to verify:** seed two `REVIEW` tasks in one workflow, open a task detail route, and + assert the two semantic icon selectors in their sidebar rows. +- **Scenario:** the same two tasks show the same distinction in the phone task-switcher drawer. + **File:** `apps/web/e2e/tests/task/mobile-sidebar-workflow-completion-icon.spec.ts`. + **What to verify:** open the task switcher from the mobile session top bar and assert both row + icons inside the drawer. +- Update `apps/web/e2e/tests/task/sidebar-settled-spinner.spec.ts` so its existing non-final + settled-turn assertion expects the progress-check selector. + +## Mobile Parity + +The nearest shipped mobile exemplar is +`apps/web/components/task/mobile/session-task-switcher-sheet.tsx`. It already renders the shared +`TaskSwitcher` and `TaskItem`, so the phone drawer receives the same state derivation without a +separate presentation or duplicated business rule. This is an icon-only content change: the +existing drawer entry point, hierarchy, tap behavior, touch targets, safe-area handling, and +scroll owner remain unchanged. The focused `mobile-chrome` Playwright scenario is the rendered +mobile check. + +## Implementation Waves + +Wave 1 (sequential): + +- [x] [Task 01: Differentiate sidebar completion icons](task-01-sidebar-completion-icons.md) — done + +## Verification + +```bash +cd apps && pnpm --filter @kandev/web test -- \ + components/task/task-item.test.tsx \ + components/task/task-switcher.test.tsx +cd apps/web && pnpm e2e:run tests/task/sidebar-workflow-completion-icon.spec.ts \ + -- --project=chromium +cd apps/web && pnpm e2e:run tests/task/mobile-sidebar-workflow-completion-icon.spec.ts \ + -- --project=mobile-chrome +cd apps/web && pnpm run typecheck +``` + +## Risks + +- Workflow step arrays must remain ordered; `aggregateSidebarTasks` currently sorts every + workflow by `position` before passing them to `TaskSwitcher`. +- Missing or temporarily stale workflow metadata must not display a false workflow-complete + check, hence the exact-match rule and progress-check fallback. +- Existing tests and external selectors may still refer to `task-state-review`; migrate all + in-repository uses in the same change and keep the new semantic selectors scoped to the two + completion outcomes. + +## Documentation Impact + +No public documentation changes are required. This plan adds the internal product spec +`docs/specs/ui/sidebar-task-completion-icons.md`; the change does not alter commands, settings, +APIs, workflows, or public terminology. No ADR is warranted because the implementation reuses +existing frontend state and establishes no new architectural boundary. diff --git a/docs/plans/sidebar-task-completion-icons/task-01-sidebar-completion-icons.md b/docs/plans/sidebar-task-completion-icons/task-01-sidebar-completion-icons.md new file mode 100644 index 0000000000..e82ae5e88a --- /dev/null +++ b/docs/plans/sidebar-task-completion-icons/task-01-sidebar-completion-icons.md @@ -0,0 +1,97 @@ +--- +id: "01-sidebar-completion-icons" +title: "Differentiate sidebar completion icons" +status: done +wave: 1 +depends_on: [] +plan: "plan.md" +spec: "../../specs/ui/sidebar-task-completion-icons.md" +--- + +# Task 01: Differentiate Sidebar Completion Icons + +## Acceptance + +- Finished tasks on non-final, unknown, or unmatched workflow steps render the green Tabler + `progress-check`; finished tasks on the final ordered step render the existing green + `circle-check`. +- The desktop sidebar and mobile task-switcher drawer use the same derivation and selectors, + while every higher-priority active or pending icon remains unchanged. +- Focused component, desktop Playwright, mobile Playwright, and frontend typecheck commands pass. + +## TDD Sequence + +1. RED: add component cases proving non-final, final, and missing-step behavior plus switcher + derivation from the task's own workflow. +2. RED: add desktop and `mobile-chrome` Playwright scenarios that distinguish the two rendered + icons in real task rows. +3. GREEN: thread final-step membership through the shared task switcher and render + `IconProgressCheck` or `IconCircleCheck` in the existing review branch. +4. REFACTOR: keep the final-step comparison local and readable, migrate generic review-icon + selectors, and preserve the current state-precedence ordering. + +## Verification + +```bash +cd apps && pnpm --filter @kandev/web test -- \ + components/task/task-item.test.tsx \ + components/task/task-switcher.test.tsx +cd apps/web && pnpm e2e:run tests/task/sidebar-workflow-completion-icon.spec.ts \ + -- --project=chromium +cd apps/web && pnpm e2e:run tests/task/mobile-sidebar-workflow-completion-icon.spec.ts \ + -- --project=mobile-chrome +cd apps/web && pnpm run typecheck +``` + +## Files likely touched + +- `apps/web/components/task/task-switcher.tsx` +- `apps/web/components/task/task-switcher.test.tsx` +- `apps/web/components/task/task-item.tsx` +- `apps/web/components/task/task-item.test.tsx` +- `apps/web/e2e/tests/task/sidebar-settled-spinner.spec.ts` +- `apps/web/e2e/tests/task/sidebar-workflow-completion-icon.spec.ts` +- `apps/web/e2e/tests/task/mobile-sidebar-workflow-completion-icon.spec.ts` +- `docs/specs/ui/sidebar-task-completion-icons.md` +- `docs/specs/INDEX.md` +- `docs/plans/sidebar-task-completion-icons/plan.md` +- `docs/plans/sidebar-task-completion-icons/task-01-sidebar-completion-icons.md` + +## Dependencies + +None. The shared sidebar already receives ordered steps for every loaded workflow. + +## Parallelism + +Sequential. Production rendering, shared desktop/mobile behavior, and selector migration touch +the same components and tests. + +## Inputs + +- `docs/specs/ui/sidebar-task-completion-icons.md`, especially the exact-match fallback and state + precedence scenarios. +- `docs/plans/sidebar-task-completion-icons/plan.md`. +- Existing status precedence in `apps/web/components/task/task-item.tsx`. +- Existing per-workflow ordering in + `apps/web/components/task/task-session-sidebar-aggregate.ts`. +- Mobile exemplar `apps/web/components/task/mobile/session-task-switcher-sheet.tsx`. + +## Risks + +- Do not infer completion from `TaskState.COMPLETED` alone; workflow completion is defined by + current-step membership. +- Do not let a missing step list render the continuous workflow-complete check. +- Keep the shared row path so desktop and mobile cannot drift. + +## Verification Results + +- Component tests: 40 passed. +- Desktop completion-icon E2E: passed. +- Mobile completion-icon E2E: passed. +- Sidebar status regression E2E: passed. +- Frontend lint and typecheck: passed. + +## Output contract + +Report RED failures, the final-step derivation, selectors migrated, exact files changed, +component/E2E/typecheck results, blockers or risks, and the task/plan status updates. diff --git a/docs/specs/INDEX.md b/docs/specs/INDEX.md index 3dfb71f8f0..c3bef98ed6 100644 --- a/docs/specs/INDEX.md +++ b/docs/specs/INDEX.md @@ -125,6 +125,7 @@ Subscription quota tracking and per-agent cheap-model profile routing. | [review-file-status](ui/review-file-status.md) | building | | [review-markdown-preview](ui/review-markdown-preview.md) | draft | | [sidebar-view-creation](ui/sidebar-view-creation.md) | shipped | +| [sidebar-task-completion-icons](ui/sidebar-task-completion-icons.md) | shipped | | [slash-command-composer](ui/slash-command-composer.md) | shipped | | [entity-reference-composer](ui/entity-reference-composer.md) | draft | | [settings-manual-save](ui/settings-manual-save.md) | shipped | diff --git a/docs/specs/ui/sidebar-task-completion-icons.md b/docs/specs/ui/sidebar-task-completion-icons.md new file mode 100644 index 0000000000..c0c95aa528 --- /dev/null +++ b/docs/specs/ui/sidebar-task-completion-icons.md @@ -0,0 +1,51 @@ +--- +status: shipped +created: 2026-07-30 +owner: kandev +--- + +# Sidebar Task Completion Icons + +## Why + +The task sidebar currently gives every finished turn the same green circled check, so users +cannot tell whether the agent merely finished its current turn or the task also reached the end +of its workflow. + +## What + +- A task with a finished turn that is not on the last step of its workflow shows the green + `progress-check` icon with a dashed circular outline. +- A task with a finished turn that is on the last step of its workflow keeps the current green + `circle-check` icon with a continuous circular outline. +- The last step is the final ordered step of the workflow that owns the task. +- Only an exact match between the task's current step and its workflow's last known step is + treated as workflow completion. Missing workflow or step data uses the progress-check icon + rather than claiming the workflow is complete. +- Desktop sidebar rows and the mobile task-switcher drawer expose the same distinction through + their shared task-row rendering. +- Running, background work, scheduling, pending clarification, pending permission, backlog, + failure, and cancellation icon precedence remains unchanged. + +## Scenarios + +- **GIVEN** a task whose turn is finished on a non-final workflow step, **WHEN** the task appears + in the desktop sidebar, **THEN** its green status icon is `progress-check` with a dashed circle. +- **GIVEN** a task whose turn is finished on the final workflow step, **WHEN** the task appears in + the desktop sidebar, **THEN** its green status icon is the existing continuous + `circle-check`. +- **GIVEN** finished tasks on non-final and final workflow steps, **WHEN** the user opens the + mobile task-switcher drawer, **THEN** the rows show the same progress-versus-complete icon + distinction as desktop. +- **GIVEN** a finished task whose workflow steps are unavailable or do not contain its current + step, **WHEN** the row renders, **THEN** it shows `progress-check`. +- **GIVEN** a task with a higher-priority active or pending state, **WHEN** the row renders, + **THEN** that existing state icon is shown regardless of the task's workflow position. + +## Out of scope + +- Changing task or session lifecycle states, workflow transitions, or step ordering. +- Changing status icons on kanban cards, graphs, task headers, recent-task switchers, or Office + surfaces. +- Adding backend, API, persistence, or feature-flag state. +- Changing sidebar or mobile task-switcher layout, navigation, touch targets, or scroll behavior.