mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The board UI opens a task page as a chat. A hard load of a task URL starts one chat bootstrap request before the app's JavaScript runs. > - A returning browser also restores a saved read cache from local storage. This cache holds the core fields of recently opened tasks, but no chat history. > - The task page started the bootstrap only when the core task was not cached. A restored core task skipped it. The early bootstrap request ran, but nothing used its answer. > - So every first-frame read went to its own endpoint, and the comment input facts waited for the recent comments. A returning load was slower than a cold load: on staging, 3.6–3.8 s against 1.9–2.4 s. > - This pull request treats a task that only the saved cache holds as cold for the chat. The page adopts the bootstrap, the restored task's own revalidation shares it, and the answer replaces the restored data. > - The benefit is that a returning load is now faster than a cold load, not slower. ## Linked Issues or Issue Description **Describe the bug** A hard load of a task page is slower when the browser has a saved read cache than when it has none. Measured on staging on 2026-11-14 (hard load, JavaScript in the HTTP cache, 3 alternating pairs on one task): saved cache cleared 1.9–2.4 s, saved cache present 3.6–3.8 s, until the chat composer exists. **Steps to reproduce** 1. Open a task page so that the saved read cache (`paperclip:query-cache:v1:*`) holds it. 2. Close the tab and open the same task URL again. 3. Compare the time to the first chat frame with a load where the saved read cache is cleared. **Expected behavior** A load with a saved read cache is at least as fast as a load without one. The chat's first-frame reads share the one bootstrap request. **Actual behavior** With a saved read cache, the bootstrap request runs but its answer is not used. About 16 more per-endpoint reads run before the frame, and the frame waits for a second, serial wave of reads. Related: #20355 (chat bootstrap endpoints), #20592 (cold task open from one bootstrap), #20591 and #20594 (returning Mine inbox from the saved read cache), #21557 (cold-load perf spec). ## What Changed - `ui/src/lib/persisted-query-cache.ts`: records which queries a page restored from the saved read cache. `isRestoredSavedRead(client, key)` is true until a read or a local write in this page replaces that data. - `ui/src/pages/IssueDetail.tsx`: starts (or adopts) the chat bootstrap when the core task is missing or only restored. It passes the restored task's id and identifier as aliases, so reads keyed by the id share the request while it loads. - `ui/src/lib/issue-chat-bootstrap.ts`: `readFromIssueChatBootstrap` lets a key that holds only restored data share the bootstrap, like an empty key. `startIssueChatBootstrap` accepts aliases. - `ui/src/lib/issueChatBootstrapCache.ts` and `ui/src/lib/issueDetailCache.ts`: the bootstrap answer replaces restored data (core task under every ref). The restored core task's revalidation shares the bootstrap. A core task that was read in this page keeps its own small read. - `ui/src/hooks/useIssuePlanDocument.ts`: the first plan read shares the bootstrap's plan projection instead of reading `documents/plan` before the frame. - `tests/perf/issue-detail/cold-bootstrap.perf.spec.ts`: an always-on request-shape test for a returning load with a saved read cache, and an opt-in benchmark of alternating pairs (saved cache present and cleared). The harness now clears storage after the warm-up page closes, because closing the app saves its read cache again. - `ui/src/lib/restored-task-chat-bootstrap.test.ts`: unit tests for the restore-then-bootstrap path. - `tests/perf/issue-detail/README.md`: documents the returning-load test and benchmark. ## Verification Local production build (`PAPERCLIP_UI_DEV_MIDDLEWARE=false`), local_trusted instance, CDP delay of 300 ms on every API request, fresh browser context per run, JavaScript in the HTTP cache. Time from navigation start to the revealed history with the latest message and an editable composer. | Build | Saved read cache | Runs | Median | Spread | API requests before frame | Frame released by | | --- | --- | ---: | ---: | ---: | ---: | --- | | master `95a6ab31e6` | cleared | 5 | 913 ms | 908–957 | 33 | company list (shell stage 2) | | master `95a6ab31e6` | present | 5 | 1,204 ms | 1,178–1,215 | 49 | `activity?view=comment-inputs` (serial second wave) | | this PR | cleared | 7 | 942 ms | 925–997 | 35 | company list (shell stage 2) | | this PR | present | 7 | 573 ms | 566–658 | 37 | app boot and route mount (all task data is the bootstrap) | - Paired delta with this PR (present − cleared): median −376 ms over 7 pairs, all negative (−267 to −400). On master it was +292 ms over 5 pairs, all positive. - With an 800 ms API delay (this PR, 5 pairs): present 890 ms, released by the bootstrap response; cleared 1,910 ms. - Cold load with no app storage (existing benchmark, 7 runs): master 910 ms, this PR 939 ms. The host load average was about 20 during the PR run (other work on the machine). Requests before the frame are 35 in both. I make no claim of a cold change. - Request-shape tests (`cold-bootstrap.perf.spec.ts`): the new returning-load test fails on master (the timeline shows `?view=core`, `recent-comments`, `activity`, `runs`, `interactions`, `attachments`, `live-runs` before the frame) and passes with this PR. The existing cold test passes. - Unit tests: `restored-task-chat-bootstrap.test.ts` has 10 cases. With the behavior changes reverted (the restore marker kept so the file imports), 3 fail: the bootstrap refreshes the restored task and fills the chat, id-keyed reads share the loading bootstrap, and a partial answer. All 10 pass with this PR. The other 7 cases are guards that hold on both: a stale refresh reads the server, a failed bootstrap falls back, a 403 removes the restored task from memory and storage, another company's answer is not seeded, an answer is not used after another user signs in, and another user's saved task is not restored. - Focused Vitest: 27 files that use the changed modules, including `IssueDetail.test.tsx` and `TaskChatThread.test.tsx`: 1,208 passed. - Browser layout journeys against the PR build: `layout-stability.spec.ts` and `plan-startup.spec.ts`, 17 of 17 passed (reveal order, reading anchor, older history, Back, comment links, drafts during background refresh, failed and stalled reads with Retry, plan projection with stalled plan reads). - `pnpm verify` exit 2 (the README is a global CI input), so required CI supplies the broad coverage. Commands: ```sh cd ui && npx vitest run src/lib/restored-task-chat-bootstrap.test.ts PAPERCLIP_ISSUE_PERF_BASE_URL=http://127.0.0.1:<port> pnpm exec playwright test --config tests/perf/issue-detail/playwright.config.ts cold-bootstrap PAPERCLIP_ISSUE_PERF_BASE_URL=http://127.0.0.1:<port> PAPERCLIP_ISSUE_PERF_COLD_RUNS=7 pnpm exec playwright test --config tests/perf/issue-detail/playwright.config.ts cold-bootstrap -g returning ``` ## Risks - Low risk. The change only affects data that the saved read cache restored and that no read in this page has confirmed. Data read in this page keeps the old rule: a refresh asks the server. - The saved read cache content is unchanged. It still excludes comments and bootstrap payloads, so the first chat frame still needs one response (the bootstrap). It cannot appear before any task response without saving chat history, which the documented allowlist excludes. - If the bootstrap fails, stalls or omits the task, each read falls back to its own request, as on a cold load. A 403 or 404 on the restored task's fallback read removes it from memory and storage, as before. - Account changes: a bootstrap answer is bound to the session's user, as before. The saved cache restores data only for the same user. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file edits, browser automation through Playwright). ## 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 - [x] All Paperclip CI gates are green - [x] 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>
302 lines
12 KiB
TypeScript
302 lines
12 KiB
TypeScript
import type { QueryClient } from "@tanstack/react-query";
|
|
import type { InstanceExperimentalSettings, Issue, IssueComment } from "@paperclipai/shared";
|
|
import { issuesApi } from "@/api/issues";
|
|
import { getIssueRecentCommentsQueryOptions } from "./issue-comment-window-query";
|
|
import {
|
|
prefetchIssueChatHistory,
|
|
prefetchIssueCommentInputFacts,
|
|
recentIssueActivityQueryKey,
|
|
recentIssueRunWindowQueryKey,
|
|
} from "./issue-chat-history-queries";
|
|
import { readFromIssueChatBootstrap, startIssueChatBootstrap } from "./issue-chat-bootstrap";
|
|
import { isRestoredSavedRead } from "./persisted-query-cache";
|
|
import { queryKeys } from "@/lib/queryKeys";
|
|
import { getNextIssueCommentPageParam, ISSUE_COMMENT_PAGE_SIZE } from "@/lib/optimistic-issue-comments";
|
|
|
|
const ISSUE_DETAIL_QUERY_PREFIX = ["issues", "detail"] as const;
|
|
export const ISSUE_DETAIL_STALE_TIME_MS = 60_000;
|
|
/**
|
|
* Freshness window for a prefetched first comments page. Matches the global
|
|
* query staleTime so a warm navigation that arrives within the window renders
|
|
* the seeded comments without an immediate refetch (no loading state), while a
|
|
* later revisit still revalidates in the background.
|
|
*/
|
|
export const ISSUE_COMMENTS_PREFETCH_STALE_TIME_MS = 30_000;
|
|
|
|
function isNonEmptyString(value: unknown): value is string {
|
|
return typeof value === "string" && value.length > 0;
|
|
}
|
|
|
|
function collectIssueRefs(
|
|
issueRef: string | null | undefined,
|
|
issue?: Pick<Issue, "id" | "identifier"> | null,
|
|
): string[] {
|
|
const refs = new Set<string>();
|
|
if (isNonEmptyString(issueRef)) refs.add(issueRef);
|
|
if (isNonEmptyString(issue?.id)) refs.add(issue.id);
|
|
if (isNonEmptyString(issue?.identifier)) refs.add(issue.identifier);
|
|
return Array.from(refs);
|
|
}
|
|
|
|
function matchesIssueRef(issue: Pick<Issue, "id" | "identifier">, refs: Iterable<string>) {
|
|
const refSet = refs instanceof Set ? refs : new Set(refs);
|
|
return refSet.has(issue.id) || (!!issue.identifier && refSet.has(issue.identifier));
|
|
}
|
|
|
|
function isCompleteIssueSnapshot(value: unknown): value is Issue {
|
|
if (typeof value !== "object" || value === null) return false;
|
|
const issue = value as Partial<Issue>;
|
|
return (
|
|
issue.listProjection === undefined
|
|
&& isNonEmptyString(issue.id)
|
|
&& isNonEmptyString(issue.companyId)
|
|
&& typeof issue.title === "string"
|
|
&& typeof issue.status === "string"
|
|
&& typeof issue.workMode === "string"
|
|
&& typeof issue.priority === "string"
|
|
&& (issue.projectId === null || typeof issue.projectId === "string")
|
|
&& (issue.parentId === null || typeof issue.parentId === "string")
|
|
&& (issue.identifier === null || typeof issue.identifier === "string")
|
|
&& (issue.description === null || typeof issue.description === "string")
|
|
&& (issue.assigneeAgentId === null || typeof issue.assigneeAgentId === "string")
|
|
&& (issue.assigneeUserId === null || typeof issue.assigneeUserId === "string")
|
|
&& (issue.executionRunId === null || typeof issue.executionRunId === "string")
|
|
&& (issue.issueNumber === null || typeof issue.issueNumber === "number")
|
|
&& typeof issue.requestDepth === "number"
|
|
&& issue.createdAt != null
|
|
&& issue.updatedAt != null
|
|
);
|
|
}
|
|
|
|
function mergeIssueSnapshots(existing: Issue | undefined, incoming: Issue): Issue {
|
|
if (!existing) return incoming;
|
|
return {
|
|
...existing,
|
|
...incoming,
|
|
};
|
|
}
|
|
|
|
export function getIssueDetailCacheRefs(issue: Pick<Issue, "id" | "identifier">): string[] {
|
|
return collectIssueRefs(null, issue);
|
|
}
|
|
|
|
export function getCachedIssueDetail(
|
|
queryClient: QueryClient,
|
|
issueRef: string | null | undefined,
|
|
issue?: Pick<Issue, "id" | "identifier"> | null,
|
|
): Issue | undefined {
|
|
const refs = collectIssueRefs(issueRef, issue);
|
|
|
|
for (const ref of refs) {
|
|
const cached = queryClient.getQueryData<Issue>(queryKeys.issues.detail(ref));
|
|
if (isCompleteIssueSnapshot(cached)) return cached;
|
|
}
|
|
|
|
const cachedEntries = queryClient.getQueriesData<Issue>({ queryKey: ISSUE_DETAIL_QUERY_PREFIX });
|
|
return cachedEntries
|
|
// Core reads share invalidation/mutation updates with detail, but cannot
|
|
// stand in for its related data or suppress the enrichment request.
|
|
.filter(([key]) => key.length === ISSUE_DETAIL_QUERY_PREFIX.length + 1)
|
|
.map(([, cachedIssue]) => cachedIssue)
|
|
.find((cachedIssue): cachedIssue is Issue =>
|
|
isCompleteIssueSnapshot(cachedIssue) && matchesIssueRef(cachedIssue, refs)
|
|
);
|
|
}
|
|
|
|
export function seedIssueDetailCache(
|
|
queryClient: QueryClient,
|
|
issue: Issue,
|
|
options?: {
|
|
issueRef?: string | null;
|
|
},
|
|
): Issue {
|
|
if (!isCompleteIssueSnapshot(issue)) return issue;
|
|
|
|
const refs = collectIssueRefs(options?.issueRef, issue);
|
|
const merged = mergeIssueSnapshots(getCachedIssueDetail(queryClient, options?.issueRef, issue), issue);
|
|
|
|
for (const ref of refs) {
|
|
queryClient.setQueryData<Issue>(
|
|
queryKeys.issues.detail(ref),
|
|
(existing) => mergeIssueSnapshots(existing, merged),
|
|
);
|
|
}
|
|
|
|
return merged;
|
|
}
|
|
|
|
/** Retain authenticated core aliases and saved projections without replacing
|
|
* data already read or refreshed. Core entries never fill full-detail keys. */
|
|
export function seedIssueDetailProjections(
|
|
queryClient: QueryClient,
|
|
issue: Issue,
|
|
issueRef?: string | null,
|
|
) {
|
|
// Canonical navigation must not discard metadata just fetched through a UUID.
|
|
// Only the response's own refs are aliases; an arbitrary requested ref is not.
|
|
for (const ref of getIssueDetailCacheRefs(issue)) {
|
|
const key = [...queryKeys.issues.detail(ref), "core"];
|
|
if (queryClient.getQueryData(key) === undefined || isRestoredSavedRead(queryClient, key)) {
|
|
queryClient.setQueryData(key, issue);
|
|
}
|
|
}
|
|
const planKey = [...queryKeys.issues.documents(issue.id), "plan"];
|
|
if (issue.planDocument !== undefined && queryClient.getQueryData(planKey) === undefined) {
|
|
queryClient.setQueryData(planKey, issue.planDocument);
|
|
}
|
|
if (issue.workProducts !== undefined) {
|
|
for (const ref of collectIssueRefs(issueRef, issue)) {
|
|
const key = queryKeys.issues.workProducts(ref);
|
|
// The stored request can already be pending when core arrives. Its
|
|
// background refresh should not hold the first saved cards behind a gate.
|
|
if (queryClient.getQueryData(key) === undefined) {
|
|
queryClient.setQueryData(key, issue.workProducts);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
export function getIssueCoreQueryOptions(queryClient: QueryClient, issueRef: string) {
|
|
return {
|
|
queryKey: [...queryKeys.issues.detail(issueRef), "core"] as const,
|
|
queryFn: async ({ signal }: { signal: AbortSignal }) => {
|
|
const key = [...queryKeys.issues.detail(issueRef), "core"];
|
|
const read = () => issuesApi.getCore(issueRef, { signal });
|
|
// The header shows a restored task at once, so its revalidation can
|
|
// wait for the page's chat bootstrap. Otherwise this small read keeps
|
|
// the header from waiting on the larger bootstrap.
|
|
const issue = isRestoredSavedRead(queryClient, key)
|
|
? await readFromIssueChatBootstrap(queryClient, key, issueRef, (item) => item.issue, read)
|
|
: await read();
|
|
seedIssueDetailProjections(queryClient, issue, issueRef);
|
|
return issue;
|
|
},
|
|
};
|
|
}
|
|
|
|
export async function fetchIssueDetail(
|
|
queryClient: QueryClient,
|
|
issueRef: string,
|
|
options?: { signal?: AbortSignal },
|
|
): Promise<Issue> {
|
|
const issue = options ? await issuesApi.get(issueRef, options) : await issuesApi.get(issueRef);
|
|
seedIssueDetailProjections(queryClient, issue, issueRef);
|
|
return seedIssueDetailCache(queryClient, issue, { issueRef });
|
|
}
|
|
|
|
export function getIssueDetailQueryOptions(
|
|
queryClient: QueryClient,
|
|
issueRef: string,
|
|
options?: {
|
|
placeholderIssue?: Pick<Issue, "id" | "identifier"> | null;
|
|
},
|
|
) {
|
|
return {
|
|
queryKey: queryKeys.issues.detail(issueRef),
|
|
queryFn: ({ signal }: { signal?: AbortSignal }) => fetchIssueDetail(queryClient, issueRef, { signal }),
|
|
placeholderData: getCachedIssueDetail(queryClient, issueRef, options?.placeholderIssue ?? undefined),
|
|
};
|
|
}
|
|
|
|
export function prefetchIssueDetail(
|
|
queryClient: QueryClient,
|
|
issueRef: string,
|
|
options?: {
|
|
issue?: Issue | null;
|
|
},
|
|
) {
|
|
if (isCompleteIssueSnapshot(options?.issue)) {
|
|
seedIssueDetailCache(queryClient, options.issue, { issueRef });
|
|
}
|
|
|
|
return queryClient.prefetchQuery({
|
|
queryKey: queryKeys.issues.detail(issueRef),
|
|
queryFn: () => fetchIssueDetail(queryClient, issueRef),
|
|
staleTime: ISSUE_DETAIL_STALE_TIME_MS,
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Warm the first page of the issue-detail comment feed under the exact infinite
|
|
* query key IssueDetail mounts, so a subsequent navigation paints comments from
|
|
* cache instead of waiting on a fetch. Keyed by issue ref and always background
|
|
* revalidated by the mounted query, so it never surfaces stale cross-issue data.
|
|
*/
|
|
export function prefetchIssueComments(queryClient: QueryClient, issueRef: string) {
|
|
return queryClient.prefetchInfiniteQuery({
|
|
queryKey: queryKeys.issues.comments(issueRef),
|
|
queryFn: ({ pageParam }: { pageParam: string | null }) =>
|
|
issuesApi.listComments(issueRef, {
|
|
order: "desc",
|
|
limit: ISSUE_COMMENT_PAGE_SIZE,
|
|
...(pageParam ? { after: pageParam } : {}),
|
|
}),
|
|
initialPageParam: null as string | null,
|
|
getNextPageParam: (lastPage: IssueComment[]) =>
|
|
getNextIssueCommentPageParam(lastPage, ISSUE_COMMENT_PAGE_SIZE),
|
|
staleTime: ISSUE_COMMENTS_PREFETCH_STALE_TIME_MS,
|
|
pages: 1,
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Warm what a task's first frame needs before the person opens it.
|
|
*
|
|
* `history: true` also warms every other read that gates the compact chat's
|
|
* first reveal (activity, runs, comment input facts, interactions,
|
|
* attachments, live runs), in one chat-bootstrap request when none of them
|
|
* is cached yet. Callers
|
|
* pass it when an open is likely: a mouse or pen press, a click, keyboard
|
|
* selection, or a hover or focus that rests on the link. A pointer, touch or
|
|
* focus passing over rows warms only the issue and its recent comments.
|
|
*/
|
|
export function prefetchIssueDetailForNavigation(
|
|
queryClient: QueryClient,
|
|
issueRef: string,
|
|
options?: { issue?: Issue | null; history?: boolean },
|
|
) {
|
|
const fullHistory = queryClient.getQueryData(["issues", "history-expanded", issueRef]) === true
|
|
|| queryClient.getQueryData<InstanceExperimentalSettings>(queryKeys.instance.experimentalSettings)?.enableClassicTaskInterface === true;
|
|
if (fullHistory) {
|
|
return Promise.all([
|
|
prefetchIssueDetail(queryClient, issueRef, options),
|
|
prefetchIssueComments(queryClient, issueRef),
|
|
]);
|
|
}
|
|
if (isCompleteIssueSnapshot(options?.issue)) {
|
|
seedIssueDetailCache(queryClient, options.issue, { issueRef });
|
|
}
|
|
// A task with none of its chat history cached warms it in one bootstrap
|
|
// request; the recent-comments read below shares it. A task seen before
|
|
// refreshes and reconciles its cached reads one by one.
|
|
const coldChat = !!options?.history && [
|
|
recentIssueActivityQueryKey(issueRef),
|
|
recentIssueRunWindowQueryKey(issueRef),
|
|
queryKeys.issues.interactions(issueRef),
|
|
queryKeys.issues.attachments(issueRef),
|
|
queryKeys.issues.liveRuns(issueRef),
|
|
].every((key) => queryClient.getQueryData(key) === undefined);
|
|
const bootstrap = coldChat ? startIssueChatBootstrap(queryClient, options?.issue?.companyId, issueRef) : null;
|
|
const history = !!options?.history && !coldChat;
|
|
return Promise.all([
|
|
queryClient.prefetchQuery({
|
|
...getIssueCoreQueryOptions(queryClient, issueRef),
|
|
staleTime: ISSUE_COMMENTS_PREFETCH_STALE_TIME_MS,
|
|
}),
|
|
queryClient.prefetchQuery({
|
|
...getIssueRecentCommentsQueryOptions(queryClient, issueRef),
|
|
staleTime: ISSUE_COMMENTS_PREFETCH_STALE_TIME_MS,
|
|
}).then(() => history
|
|
// The chat also waits for the input facts of the comments it shows.
|
|
? prefetchIssueCommentInputFacts(queryClient, issueRef, ISSUE_COMMENTS_PREFETCH_STALE_TIME_MS)
|
|
: undefined),
|
|
...(bootstrap ? [bootstrap] : []),
|
|
...(history
|
|
? [prefetchIssueChatHistory(queryClient, issueRef, {
|
|
issue: options.issue ?? getCachedIssueDetail(queryClient, issueRef),
|
|
staleTime: ISSUE_COMMENTS_PREFETCH_STALE_TIME_MS,
|
|
})]
|
|
: []),
|
|
]);
|
|
}
|