Files
PaperClipAI/ui/src/hooks/useRecentTaskOpenWarmup.test.tsx
T
DottaandClaude Opus 5.5 ee6922f705 perf(tasks): open recent tasks without waiting on a slow ten-task preload (#21939)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A person opens a task from the sidebar's Recent Tasks, the Inbox or
the Tasks list, and the task chat shows its first frame from a
`chat-bootstrap` read
> - On staging, a task opened from Recent Tasks soon after a page load
took 15.3 s to show its chat. The same task from the Inbox took 0.19 s
> - Two defects cause this. Every task's bootstrap paid a fixed ~1.8 s
for its latest runs. Recent Tasks preloaded ten tasks in one request
(17.7 s), and an open waited for that whole request
> - Recent Tasks also warmed its tasks only once per page load. Unread
cache entries are dropped after five minutes, so its tasks were cold for
the rest of the session
> - This pull request makes the runs read use indexes, lets an open read
its own task instead of waiting for a ten-task preload, and re-warms
Recent Tasks on navigation
> - The benefit is that a task from Recent Tasks opens as fast as from a
task list

## Linked Issues or Issue Description

Refs #19818, Refs #16713 (earlier proposals of the same `runsForIssue`
rewrite; this PR adds a query-plan regression test and the client
fixes).

**What happened?**
On staging, a click on a Recent Tasks link about 6 s after a page load
took 15.3 s until the chat thread showed. The Inbox opened the same task
in 0.19 s.

**Steps to reproduce**
1. Load a page with a populated Recent Tasks sidebar.
2. Within a few seconds, click a recent task.
3. The chat stays on its loading state for many seconds.

**Expected behavior**
The task opens about as fast as from the Inbox or the Tasks list.

**Root cause (measured on staging)**
- `GET /issues/:id/runs?view=recent` took 1.7–1.9 s of server time for
tasks with 1 to 24 runs. Every other first-frame read took 80–350 ms.
The query filtered with `issue_id = $1 OR EXISTS (activity_log … run_id
= heartbeat_runs.id)`, so Postgres walked every run of the company.
- The bootstrap reads two tasks at a time, so the Recents preload of ten
tasks took 17.7 s. Each task in a batch settles only with the whole
request, and the page's reads wait for it (up to the 5 s share deadline,
then read again under load).
- `useRecentTaskOpenWarmup` remembered preloaded task ids for the life
of the page and never preloaded them again.

## What Changed

- `activityService.runsForIssue`: select the task's runs by `id IN (runs
with issue_id = task UNION run ids from the task's activity)`. Each half
uses its own index. The results are the same.
- `startIssueChatBootstrap`: when the only request for a task is a
background batch that is still loading, send a request for that task
alone. All refs of the task point to the new request. The later batch
answer only fills keys that are still empty or older.
- `loadIssueChatBootstraps` (background): a task whose answer did not
arrive is not held back for five minutes, so the next preload can retry
it.
- `useRecentTaskOpenWarmup`: use the background preload (five-minute
repeat, the same as the cache GC time) and run again after each
navigation (`navigationKey`). It no longer keeps a per-page-load set.
`SidebarRecentTasks` and `CoordinatorSidebar` pass the pathname.

## Verification

- `server/src/__tests__/issue-runs-read-cost.test.ts` (new): a company
with 20,003 runs, and a task with 3 runs. EXPLAIN ANALYZE of the runs
reads examined **40,011** run rows before the fix and **15** after
(red/green). The test also checks the run order and the run that is
linked only through activity.
- `ui/src/lib/issue-chat-bootstrap.test.ts`: a new test opens a task
while a ten-task preload is still loading. Before the fix it timed out
waiting on the batch. After the fix it reads its own request. A second
new test checks that a single-task request is still shared.
- `ui/src/hooks/useRecentTaskOpenWarmup.test.tsx`: a new test re-warms
Recents on a navigation after five minutes (red on the old hook).
Another new test sends nothing for navigations inside five minutes.
- Existing suites pass: activity service/routes, task cold open, agent
conversations (197 tests); sidebar, Recents, navigation prefetch, issue
detail cache, IssueDetail (341 tests).
- `tsc --noEmit` is clean for `server` and `ui` (apart from the
pre-existing Storybook index errors).
- `pnpm verify` exits 2 (an opaque server setup dependency), so CI
supplies the broad coverage.
- After deploy: on staging, time a Recent Tasks click a few seconds
after a cold load, and time `runs?view=recent`.

## Risks

- Low risk. The SQL change keeps the same filter. It changes only how
Postgres finds the candidate runs. The existing activity tests cover
retry, credential and conversation cases.
- An open during a background preload now sends one more bootstrap
request for that task. This happens only on an open or a resting hover,
never for each row.
- Recents now sends at most one preload per five minutes while the
person navigates. It sends nothing while the tab is idle or hidden.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, browser measurement on staging, code execution).

## 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-16 15:26:22 -06:00

278 lines
12 KiB
TypeScript

// @vitest-environment jsdom
import { act } from "react";
import { createRoot, type Root } from "react-dom/client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { TASK_COLLECTION_PAINTED_EVENT } from "@/lib/issue-detail-preload-events";
import type { Issue } from "@paperclipai/shared";
import { seedIssueChatBootstrap, type IssueChatBootstrapEntry } from "@/lib/issueChatBootstrapCache";
import { queryKeys } from "@/lib/queryKeys";
import { CHAT_BOOTSTRAP_BACKGROUND_REPEAT_MS, resetIssueChatBootstrapsForTest } from "@/lib/issue-chat-bootstrap";
import { useRecentTaskOpenWarmup, type RecentTaskOpenWarmupTask } from "./useRecentTaskOpenWarmup";
const chatBootstrap = vi.hoisted(() => vi.fn());
vi.mock("@/api/issues", () => ({ issuesApi: { chatBootstrap } }));
// eslint-disable-next-line @typescript-eslint/no-explicit-any
(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
const tasks = (count: number): RecentTaskOpenWarmupTask[] =>
Array.from({ length: count }, (_, index) => ({ id: `id-${index}`, identifier: `PAP-${index}` }));
function bootstrapItem(index: number, companyId = "company-1"): IssueChatBootstrapEntry {
return {
ref: `id-${index}`,
issue: {
id: `id-${index}`, identifier: `PAP-${index}`, companyId, title: `Task ${index}`, status: "todo", priority: "medium",
workMode: "standard", projectId: null, parentId: null, description: null, assigneeAgentId: null, assigneeUserId: null,
executionRunId: null, issueNumber: index, requestDepth: 0, createdAt: new Date(0), updatedAt: new Date(0),
} as Issue,
recentComments: { comments: [], hasMore: false, oldestCommentId: null, latestCommentId: null },
commentInputFacts: [], recentActivity: [], recentRuns: [], interactions: [], attachments: [], liveRuns: [], activeRun: null,
};
}
/** Long enough for two frames and the idle fallback timer. */
const settle = () => act(async () => { await new Promise((resolve) => setTimeout(resolve, 400)); });
let container: HTMLDivElement;
let root: Root;
let queryClient: QueryClient;
let visibility: DocumentVisibilityState;
function Probe(props: { companyId: string | null; userId: string | null; tasks: RecentTaskOpenWarmupTask[]; navigationKey?: string }) {
useRecentTaskOpenWarmup(props);
return null;
}
function render(props: { companyId?: string | null; userId?: string | null; tasks: RecentTaskOpenWarmupTask[]; navigationKey?: string }) {
act(() => {
root.render(
<QueryClientProvider client={queryClient}>
<Probe companyId={props.companyId === undefined ? "company-1" : props.companyId} userId={props.userId ?? "user-1"} tasks={props.tasks} navigationKey={props.navigationKey} />
</QueryClientProvider>,
);
});
}
beforeEach(() => {
resetIssueChatBootstrapsForTest();
chatBootstrap.mockReset();
chatBootstrap.mockImplementation(async (_companyId: string, ids: string[]) => ({
items: ids.map((id) => bootstrapItem(Number(id.slice(3)))),
}));
visibility = "visible";
Object.defineProperty(document, "visibilityState", { configurable: true, get: () => visibility });
container = document.createElement("div");
document.body.appendChild(container);
root = createRoot(container);
queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
});
afterEach(() => {
vi.useRealTimers();
act(() => root.unmount());
container.remove();
queryClient.clear();
});
describe("useRecentTaskOpenWarmup", () => {
it("warms tasks added to Recents after the initial preload", async () => {
render({ tasks: tasks(2) });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(1);
render({ tasks: [tasks(3)[2]!, ...tasks(2)] });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(2);
expect(chatBootstrap.mock.calls[1]![1]).toEqual(["id-2"]);
expect(queryClient.getQueryData([...queryKeys.issues.detail("PAP-2"), "core"])).toMatchObject({ id: "id-2" });
});
it("reads the ten most recent tasks in one request once the page settles, and seeds them", async () => {
render({ tasks: tasks(12) });
expect(chatBootstrap).not.toHaveBeenCalled();
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(1);
expect(chatBootstrap.mock.calls[0]![0]).toBe("company-1");
expect(chatBootstrap.mock.calls[0]![1]).toEqual(tasks(10).map((task) => task.id));
expect(queryClient.getQueryData([...queryKeys.issues.detail("PAP-3"), "core"])).toMatchObject({ id: "id-3" });
render({ tasks: [...tasks(10)].reverse() });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(1);
});
it("warms only tasks that move into the ten top rows", async () => {
render({ tasks: tasks(12) });
await settle();
render({ tasks: [...tasks(12)].reverse() });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(2);
expect(chatBootstrap.mock.calls[1]![1]).toEqual(["id-11", "id-10"]);
});
it("does not consume a preload when rows change before the page settles", async () => {
let finish!: (value: string) => void;
void queryClient.fetchQuery({ queryKey: ["page-read"], queryFn: () => new Promise<string>((resolve) => { finish = resolve; }) });
render({ tasks: tasks(2) });
render({ tasks: [tasks(3)[2]!, ...tasks(2)] });
await settle();
expect(chatBootstrap).not.toHaveBeenCalled();
await act(async () => { finish("done"); });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(1);
expect(chatBootstrap.mock.calls[0]![1]).toEqual(["id-2", "id-0", "id-1"]);
});
it("allows a failed preload to retry on the next visit", async () => {
chatBootstrap.mockRejectedValueOnce(new Error("offline"));
render({ tasks: tasks(1) });
await settle();
act(() => root.unmount());
root = createRoot(container);
render({ tasks: tasks(1) });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(2);
expect(queryClient.getQueryData([...queryKeys.issues.detail("PAP-0"), "core"])).toMatchObject({ id: "id-0" });
});
it("warms the task-detail code only when Recents has a task", async () => {
const painted = vi.fn();
window.addEventListener(TASK_COLLECTION_PAINTED_EVENT, painted);
render({ tasks: [] });
await settle();
expect(painted).not.toHaveBeenCalled();
expect(chatBootstrap).not.toHaveBeenCalled();
render({ tasks: tasks(1) });
await settle();
expect(painted).toHaveBeenCalledTimes(1);
window.removeEventListener(TASK_COLLECTION_PAINTED_EVENT, painted);
});
it("waits for the page's own reads to finish", async () => {
let finish!: (value: string) => void;
void queryClient.fetchQuery({ queryKey: ["page-read"], queryFn: () => new Promise<string>((resolve) => { finish = resolve; }) });
render({ tasks: tasks(2) });
await settle();
expect(chatBootstrap).not.toHaveBeenCalled();
await act(async () => { finish("done"); });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(1);
});
it("makes no request while the tab is hidden", async () => {
visibility = "hidden";
render({ tasks: tasks(2) });
await settle();
expect(chatBootstrap).not.toHaveBeenCalled();
visibility = "visible";
act(() => { document.dispatchEvent(new Event("visibilitychange")); });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(1);
});
it("skips tasks whose first frame is cached and fresh, and makes no request when none is left", async () => {
// A full first frame for two tasks (as an earlier open or preload leaves it)...
seedIssueChatBootstrap(queryClient, bootstrapItem(0), { companyId: "company-1", requestedAt: Date.now() });
seedIssueChatBootstrap(queryClient, bootstrapItem(1), { companyId: "company-1", requestedAt: Date.now() });
// ...and a light warm (a brief hover) for the third, which is not a first frame.
queryClient.setQueryData([...queryKeys.issues.detail("PAP-2"), "core"], bootstrapItem(2).issue);
queryClient.setQueryData([...queryKeys.issues.comments("PAP-2"), "recent"], bootstrapItem(2).recentComments);
render({ tasks: tasks(3) });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(1);
expect(chatBootstrap.mock.calls[0]![1]).toEqual(["id-2"]);
// Now all three are cached in full: no request at all, even past the repeat window.
resetIssueChatBootstrapsForTest();
chatBootstrap.mockClear();
act(() => root.unmount());
root = createRoot(container);
render({ tasks: tasks(3) });
await settle();
expect(chatBootstrap).not.toHaveBeenCalled();
});
it("sends nothing new on navigations within five minutes of a warm", async () => {
render({ tasks: tasks(2), navigationKey: "/PAP/inbox" });
await settle();
render({ tasks: tasks(2), navigationKey: "/PAP/issues/PAP-9" });
await settle();
act(() => root.unmount());
root = createRoot(container);
render({ tasks: tasks(2), navigationKey: "/PAP/dashboard" });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(1);
});
it("warms Recents again on a navigation once the earlier warm may have been dropped", async () => {
// The sidebar stays mounted for hours; unread cache entries are dropped after five minutes.
vi.useFakeTimers({ toFake: ["Date"] });
render({ tasks: tasks(2), navigationKey: "/PAP/inbox" });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(1);
queryClient.clear();
vi.setSystemTime(Date.now() + CHAT_BOOTSTRAP_BACKGROUND_REPEAT_MS + 1);
render({ tasks: tasks(2), navigationKey: "/PAP/dashboard" });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(2);
expect(chatBootstrap.mock.calls[1]![1]).toEqual(["id-0", "id-1"]);
expect(queryClient.getQueryData([...queryKeys.issues.detail("PAP-1"), "core"])).toMatchObject({ id: "id-1" });
});
it("preloads the same task again for another account signed in within five minutes", async () => {
queryClient.setQueryData(queryKeys.auth.session, { user: { id: "user-1" } });
render({ tasks: tasks(1) });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(1);
// A sign-out clears the cached tasks; the next account opens the same task.
queryClient.clear();
queryClient.setQueryData(queryKeys.auth.session, { user: { id: "user-2" } });
act(() => root.unmount());
root = createRoot(container);
render({ userId: "user-2", tasks: tasks(1) });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(2);
expect(queryClient.getQueryData([...queryKeys.issues.detail("PAP-0"), "core"])).toMatchObject({ id: "id-0" });
});
it("never seeds another company's tasks", async () => {
render({ tasks: tasks(1) });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(1);
// Another person in the same browser is their own scope.
chatBootstrap.mockImplementationOnce(async () => ({ items: [bootstrapItem(5, "company-2")] }));
render({ userId: "user-2", tasks: tasks(6).slice(5) });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(2);
expect(queryClient.getQueryData([...queryKeys.issues.detail("PAP-5"), "core"])).toBeUndefined();
});
it("keeps an answer in flight when the sidebar unmounts, so a task opened meanwhile can use it", async () => {
let answer!: (value: unknown) => void;
chatBootstrap.mockImplementationOnce(() => new Promise((resolve) => { answer = resolve; }));
render({ tasks: tasks(1) });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(1);
act(() => root.unmount());
await act(async () => { answer({ items: [bootstrapItem(0)] }); });
expect(queryClient.getQueryData([...queryKeys.issues.detail("PAP-0"), "core"])).toMatchObject({ id: "id-0" });
root = createRoot(container);
});
it("drops the answer when the account changes before it arrives", async () => {
queryClient.setQueryData(queryKeys.auth.session, { user: { id: "user-1" } });
let answer!: (value: unknown) => void;
chatBootstrap.mockImplementationOnce(() => new Promise((resolve) => { answer = resolve; }));
render({ tasks: tasks(1) });
await settle();
expect(chatBootstrap).toHaveBeenCalledTimes(1);
act(() => { queryClient.setQueryData(queryKeys.auth.session, { user: { id: "user-2" } }); });
await act(async () => { answer({ items: [bootstrapItem(0)] }); });
expect(queryClient.getQueryData([...queryKeys.issues.detail("PAP-0"), "core"])).toBeUndefined();
expect(queryClient.getQueryData([...queryKeys.issues.detail("id-0"), "core"])).toBeUndefined();
});
});