Files
PaperClipAI/ui/src/components/task-chat/TaskChatTurnStatusIsland.test.tsx
T
DottaandClaude Opus 5.5 8227259d86 feat(task-chat): show the agent's native plan as a task list above the composer (#19252)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents run through the native runner. The runner turns each
harness's native plan into a canonical `plan.updated` event.
> - The task chat did not show these plans. A small "Step 2 / 5" pill
showed the checklist only on hover, and in live runs it received no plan
data.
> - Live tests found three breaks. The UI flattened `plan.updated` into
tool rows. Headless Claude Code hides its task tools from current
models. Codex ships its `update_plan` tool disabled.
> - This pull request fixes the three breaks and replaces the pill with
a docked plan card above the composer.
> - The benefit is that users see what the agent finished, what it does
now, and what comes next. The view is the same for Claude, Codex, Grok
and Copilot.

## Linked Issues or Issue Description

**Subsystem affected**
Task chat UI (turn status island), native runner ACPX launch environment
for Claude, and native runner Codex app-server launch arguments.

**Problem or motivation**
Harnesses report native plans, and the runner records them as
`plan.updated` events. Users do not see them. The live transcript
builder converts `plan.updated` into generic tool rows, so the plan
steps are lost. Claude Code in headless mode does not offer
TaskCreate/TaskUpdate for current models, so Claude never makes a plan.
Codex 0.160 has `update_plan` disabled by default, so Codex writes its
checklist into a Paperclip document instead.

**Proposed solution**
Keep the full plan snapshot in the live transcript. Enable the Claude
task tools with `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` in the ACPX launch
environment. Enable the Codex plan tool with
`tools.update_plan.enabled=true`. Show the plan as a docked card with
clear rules for when it shows, collapses and hides.

**Alternatives considered**
Show the plan only in the hover popover (the old behavior). Users did
not find it. Write the plan into the issue Plan document. That mixes a
per-turn checklist with the reviewed planning document.

**Roadmap alignment**
This makes existing native runner plan events visible. It adds no new
protocol or data model.

**Additional context**
Grok and Copilot needed no harness change. Cursor could not start in a
local worktree instance (an unrelated startup admission problem), so
this PR does not verify Cursor.

## What Changed

- `ui/src/components/transcript/native-run-events.ts`: keep
`plan.updated` as `provider_activity` with family `plan` and the full
payload, not as a tool row.
- `ui/src/components/task-chat/TaskChatTurnStatusIsland.tsx`: replace
the hover pill with a docked plan card. It shows done, current, upcoming
and blocked steps, a progress bar and file-change totals.
- Visibility rules: hidden with no steps and after the run ends;
collapses when all steps are done; header only for one-step plans and
while a question or approval is pending; window around the current step
for plans over 7 steps; collapsed by default on mobile.
- `ui/src/components/TaskChatThread.tsx`: pass `defaultCollapsed`
(mobile) and `compact` (pending runtime request), and reset the card per
run.
- `ui/src/components/task-chat/transcript-adapter.ts`: keep the `failed`
step status.
- `packages/paperclip-runner/src/drivers/acpx/environment.ts`: set
`CLAUDE_CODE_ENABLE_TODO_TOOLS=1` for Claude launches. A host value
cannot turn it off.
-
`packages/paperclip-runner/src/drivers/codex/codex-security-config.ts`:
add `-c tools.update_plan.enabled=true` before the policy overrides and
the `app-server` subcommand.
- `ui/storybook/stories/tasks/task-chat-agent-plan.stories.tsx`: new
story for each state. It uses the production composer dock, composer and
question takeover.
- Tests for all of the above. `ui/src/index.css` replaces the unused
popover size token with a list max-height token.

## Verification

- `pnpm --filter @paperclipai/ui exec vitest run
src/components/transcript src/components/task-chat
src/components/TaskChatThread.test.tsx src/adapters/paperclip-runner`
(1345 tests pass).
- `pnpm --filter @paperclipai/paperclip-runner exec vitest run
src/drivers/acpx/environment.test.ts src/drivers/codex` (pass).
- UI and runner typecheck are clean. `pnpm check:token-gates` is clean.
- Storybook: open "Tasks and conversations / … / Task chat / Agent
plan". The "All States Gallery" story shows every state. "Live Run
Simulation" animates a run.
- Live test on a local worktree instance with real API keys: a
multi-step task for each harness. The card showed and updated during the
run for Claude (Opus 5.5), Codex (gpt-5.6-sol), Grok (grok-4.7) and
Copilot (gpt-5.6-luna). For Claude the card collapsed when all steps
were done and hid after the run ended.
- Codex probe: `codex exec` with the pinned 0.160 binary reports no
`update_plan` tool by default and reports the tool with `-c
tools.update_plan.enabled=true`.

## Risks

- Claude and Codex now get their plan tools. Agents can spend a few
tokens on plan updates. The tools are standard harness features.
- The Codex flag goes before the web-search and project-instruction
policy overrides, so the existing policy tail check still holds.
- Runs that finish fast show the card only briefly. This is the intended
hide rule.
- Cursor plan display is not verified.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edit, browser automation) and extended reasoning.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 09:09:39 -06:00

221 lines
9.2 KiB
TypeScript

// @vitest-environment jsdom
import { act } from "react";
import { createRoot, type Root } from "react-dom/client";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import type { TaskChatItem, TaskChatProviderActivityItem } from "./task-chat-model";
import {
TaskChatTurnStatusIsland,
taskChatTurnPlanRows,
taskChatTurnPlanSegment,
taskChatTurnStatusModel,
} from "./TaskChatTurnStatusIsland";
function plan(steps: TaskChatProviderActivityItem["steps"], transcriptIndex = 1): TaskChatProviderActivityItem {
return {
id: "plan",
kind: "protocol",
surface: "provider_activity",
family: "plan",
eventType: "plan.updated",
status: "running",
title: "Plan",
details: [],
steps,
links: [],
children: [],
transcriptIndex,
};
}
const workspace: TaskChatItem = {
id: "workspace",
kind: "protocol",
surface: "workspace_change",
changeSetId: "turn-1:workspace",
revision: 2,
source: "harness_reported",
complete: false,
files: [
{ path: "one.ts", operation: "modify", previousPath: null, additions: 4, deletions: 2, binary: false, diff: null },
{ path: "two.ts", operation: "create", previousPath: null, additions: 8, deletions: 0, binary: false, diff: null },
],
totals: { files: 2, additions: 12, deletions: 2 },
patchArtifactRef: null,
};
describe("TaskChatTurnStatusIsland", () => {
let container: HTMLDivElement;
let root: Root;
beforeEach(() => {
container = document.createElement("div");
document.body.appendChild(container);
root = createRoot(container);
});
afterEach(() => {
act(() => root.unmount());
document.body.replaceChildren();
});
it("selects in-progress, blocked, pending, then final completed steps", () => {
const inProgress = taskChatTurnStatusModel([plan([
{ id: "one", label: "Done", status: "completed" },
{ id: "two", label: "Active", status: "in_progress" },
{ id: "three", label: "Later", status: "pending" },
])]);
expect(inProgress?.segments[0]).toMatchObject({ kind: "plan", currentStepIndex: 1, complete: false });
const blocked = taskChatTurnStatusModel([plan([
{ id: "one", label: "Blocked", status: "blocked" },
{ id: "two", label: "Later", status: "pending" },
])]);
expect(blocked?.segments[0]).toMatchObject({ kind: "plan", currentStepIndex: 0 });
const completed = taskChatTurnStatusModel([plan([
{ id: "one", label: "Done", status: "completed" },
{ id: "two", label: "Also done", status: "completed" },
])]);
expect(completed?.segments[0]).toMatchObject({ kind: "plan", currentStepIndex: 1, complete: true });
});
it("uses the latest plan snapshot and combines it with diff totals", () => {
const model = taskChatTurnStatusModel([
plan([{ id: "old", label: "Old", status: "in_progress" }], 1),
workspace,
plan([
{ id: "one", label: "Inspect", status: "completed" },
{ id: "two", label: "Build", status: "in_progress" },
], 3),
]);
expect(model?.segments).toEqual([
expect.objectContaining({ kind: "plan", currentStepIndex: 1 }),
{ kind: "workspace_diff", files: 2, additions: 12, deletions: 2 },
]);
});
function render(model: NonNullable<ReturnType<typeof taskChatTurnStatusModel>>, props: { defaultCollapsed?: boolean; compact?: boolean } = {}) {
act(() => root.render(<TaskChatTurnStatusIsland model={model} {...props} />));
return container.querySelector<HTMLElement>('[data-testid="task-chat-turn-status-island"]')!;
}
const checklist = () => container.querySelector('[aria-label="Within-turn checklist"]');
const header = () => container.querySelector<HTMLElement>('[data-testid="task-chat-turn-plan-header"]')!;
it("shows the checklist inline with the current step highlighted", () => {
const island = render(taskChatTurnStatusModel([
plan([
{ id: "one", label: "Inspect", status: "completed" },
{ id: "two", label: "Build the island", status: "in_progress" },
{ id: "three", label: "Verify", status: "pending" },
]),
workspace,
])!);
expect(island.getAttribute("data-plan-state")).toBe("active");
expect(container.querySelector('[data-testid="task-chat-turn-plan-headline"]')?.textContent).toBe("Build the island");
expect(container.querySelector('[data-testid="task-chat-turn-plan-progress"]')?.textContent).toContain("1/3");
expect(island.textContent).toContain("+12");
expect(checklist()?.textContent).toContain("Inspect");
expect(checklist()?.textContent).toContain("Verify");
expect(checklist()?.querySelector('[aria-current="step"]')?.textContent).toContain("Build the island");
expect(header().getAttribute("aria-expanded")).toBe("true");
});
it("collapses and reopens from the header", () => {
render(taskChatTurnStatusModel([plan([
{ id: "one", label: "Inspect", status: "completed" },
{ id: "two", label: "Build", status: "in_progress" },
])])!);
expect(document.getElementById(header().getAttribute("aria-controls")!)).toBe(checklist());
act(() => header().click());
expect(checklist()).toBeNull();
expect(header().getAttribute("aria-expanded")).toBe("false");
expect(header().hasAttribute("aria-controls")).toBe(false);
act(() => header().click());
expect(checklist()).not.toBeNull();
});
it("auto-collapses a completed plan but lets the viewer reopen it", () => {
render(taskChatTurnStatusModel([plan([
{ id: "one", label: "Inspect", status: "completed" },
{ id: "two", label: "Build", status: "completed" },
])])!);
expect(container.querySelector('[data-testid="task-chat-turn-plan-headline"]')?.textContent).toBe("All 2 steps done");
expect(checklist()).toBeNull();
act(() => header().click());
expect(checklist()?.querySelector('[aria-current="step"]')).toBeNull();
});
it("headlines blocked and not-yet-started plans", () => {
render(taskChatTurnStatusModel([plan([
{ id: "one", label: "Inspect", status: "completed" },
{ id: "two", label: "Run tests", status: "blocked" },
])])!);
expect(container.querySelector('[data-testid="task-chat-turn-plan-headline"]')?.textContent).toBe("Blocked: Run tests");
expect(container.querySelector('[data-plan-state]')?.getAttribute("data-plan-state")).toBe("blocked");
render(taskChatTurnStatusModel([plan([
{ id: "a", label: "Inspect", status: "pending" },
{ id: "b", label: "Build", status: "pending" },
], 2)])!);
expect(container.querySelector('[data-testid="task-chat-turn-plan-headline"]')?.textContent).toBe("Up next: Inspect");
});
it("renders header-only for single steps, compact mode, and collapsed-by-default", () => {
const twoSteps = taskChatTurnStatusModel([plan([
{ id: "one", label: "Inspect", status: "in_progress" },
{ id: "two", label: "Build", status: "pending" },
])])!;
render(taskChatTurnStatusModel([plan([{ id: "one", label: "Answer", status: "in_progress" }])])!);
expect(checklist()).toBeNull();
expect(header().tagName).toBe("DIV");
act(() => root.unmount());
root = createRoot(container);
render(twoSteps, { compact: true });
expect(checklist()).toBeNull();
expect(header().tagName).toBe("DIV");
act(() => root.unmount());
root = createRoot(container);
render(twoSteps, { defaultCollapsed: true });
expect(checklist()).toBeNull();
expect(header().getAttribute("aria-expanded")).toBe("false");
});
it("windows long plans around the current step and expands on demand", () => {
const labels = Array.from({ length: 12 }, (_, index) => `Step ${index + 1}`);
const steps = labels.map((label, index) => ({
id: `s${index}`,
label,
status: index < 6 ? "completed" as const : index === 6 ? "in_progress" as const : "pending" as const,
}));
const segment = taskChatTurnPlanSegment(steps);
const rows = taskChatTurnPlanRows(segment, false);
expect(rows[0]).toEqual({ kind: "earlier", count: 5, allCompleted: true });
expect(rows.filter((row) => row.kind === "step")).toHaveLength(5);
expect(rows.at(-1)).toEqual({ kind: "more", count: 2 });
expect(taskChatTurnPlanRows(segment, true)).toHaveLength(12);
expect(taskChatTurnPlanRows(taskChatTurnPlanSegment(steps.slice(0, 7)), false)).toHaveLength(7);
render(taskChatTurnStatusModel([plan(steps)])!);
expect(checklist()?.querySelectorAll("[data-step-status]")).toHaveLength(5);
act(() => container.querySelector<HTMLButtonElement>('[data-testid="task-chat-turn-plan-more"]')!.click());
expect(checklist()?.querySelectorAll("[data-step-status]")).toHaveLength(12);
});
it("renders diff-only status as a pill without a checklist", () => {
const island = render(taskChatTurnStatusModel([workspace])!);
expect(island.tagName).toBe("DIV");
expect(island.getAttribute("role")).toBe("status");
expect(island.textContent).toContain("2 files changed");
expect(island.textContent).toContain("+12");
expect(checklist()).toBeNull();
});
it("hides empty snapshots", () => {
expect(taskChatTurnStatusModel([])).toBeNull();
expect(taskChatTurnStatusModel([plan([]), { ...workspace, files: [], totals: { files: 0, additions: 0, deletions: 0 } }])).toBeNull();
});
});