mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-15 18:56:05 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The board UI keeps its caches fresh from live events in `LiveUpdatesProvider` > - Each task activity event invalidates the whole `["issues", companyId]` query prefix > - That prefix also holds the `@task` mention pool: the 100 most recently updated tasks, about 315 KB per response > - A chat turn emits many comment, status and run events, so an open task page downloads that list again for almost every event > - This pull request keeps the pool fresh from push events without a refetch per event: a closed server flag marks real membership or title changes, progress on pooled tasks reorders the cache in place, and other progress refetches at most once per 30 seconds > - The benefit is less bandwidth and CPU for users with an open task or chat, and smaller eval traces ## Linked Issues or Issue Description **What happened** While a task chat page is open, the browser repeats `GET /api/companies/:id/issues?limit=100&sortField=updated&sortDir=desc` (about 315 KB each). One 10-minute chat-eval attempt recorded about 194 of these requests. The trigger is `invalidateActivityQueries` in `ui/src/context/LiveUpdatesProvider.tsx`. For every `entityType: "issue"` activity event, it invalidates `queryKeys.issues.list(companyId)`. That prefix matches `queryKeys.issues.mentionPool(companyId)`, which `IssueDetail` (and `NewIssueDialog`) keep active for the `@task` picker. Invalidation refetches active queries and ignores `staleTime`. **Expected behavior** Comments, run progress and status changes on any task do not download the full mention pool again. The pool still updates when a task that the picker can show is created, deleted or renamed. **Steps to reproduce** 1. Run `pnpm dev` and create a company with about 140 tasks. 2. Open a task page, for example `/REF/issues/REF-1`. 3. Every 4 seconds for 15 rounds, post comments on the open task, on a task in the top 100, and on a task outside the top 100, and change the open task's priority (60 events). 4. Count requests to `issues?limit=100&sortField=updated`. Before this change there are 15 (about 3.3 MB). After this change there are 2 (about 480 KB). ## What Changed - New shared helper `issueActivityChangesTaskIdentity` (`packages/shared/src/issue-activity-identity.ts`). It is true for a created, deleted, hidden, unhidden or renamed task. - `server/src/realtime/live-events-ws.ts`: task `activity.logged` events now carry the closed boolean `taskIdentityChanged`. Authenticated sockets still get no `details`; the flag carries no task content. - `ui/src/context/LiveUpdatesProvider.tsx` refreshes the mention pool this way: - The task identity flag is true (or full details show a create, delete, hide, unhide or rename): the pool refetches at once. - Other events on a task already in the pool: the task moves to the front of the cached list. There is no request. The freshness clock does not change, and a pending invalidation is never overwritten. - Other events on a task outside the pool: one trailing refetch at most every 30 seconds, because the task can now be in the top 100. - The picker is closed: the pool is only marked stale. - `ui/src/lib/query-invalidation-batcher.ts`: new `excludingQueryKeys()` keyed exclusion predicate. The batcher coalesces it and uses it for prefix coverage. The broad `["issues", companyId]` invalidation uses it to skip the pool, so a burst is again one broad refresh per batch. - Tests: `ui/src/context/LiveUpdatesProvider.mention-pool.test.ts` (authenticated event shape, hide and unhide, the 30-second window, reorder safety, a burst through the batcher), new batcher tests, `packages/shared/src/issue-activity-identity.test.ts`, and socket assertions in `server/src/__tests__/live-events-toast.test.ts`. ## Verification - `cd ui && npx vitest run src/context/LiveUpdatesProvider src/lib/query-invalidation-batcher`: 231 tests pass. - `cd server && npx vitest run src/__tests__/live-events-toast.test.ts`: 11 tests pass. In authenticated mode the socket keeps `details` off and sends `taskIdentityChanged` (false for routine updates, true for a create, rename or hide). - `cd packages/shared && npx vitest run src/issue-activity-identity.test.ts`: 14 tests pass. - The new UI tests fail against the first commit of this PR: the authenticated burst, hide, unhide, the 30-second window and the batcher burst. - `tsc --noEmit` for ui, server and shared: no new errors. - Browser measurement: a local `pnpm dev` instance (local trusted), headless Chromium on a task page, 141 tasks, 60 events over about 63 seconds (the reproduction steps above): - Before (master UI): **15** mention-pool requests, about 3.3 MB. - After: **2** requests, about 480 KB (one per 30-second window). - Freshness after the fix: one rename, hide, unhide or create each caused **1** refetch. A priority change caused **0**. - I did not run a browser session in authenticated mode. The authenticated event shape is covered by the socket test and the UI unit tests. ## Risks - A task that moves into the top 100 can be missing from the `@task` picker for up to 30 seconds. - The cached order is approximate between refetches: a moved task goes to the front, but its `updatedAt` value is not changed. - Other queries under `["issues", companyId]` (descendants, created-from, summaries, onboarding first task) still refresh for each event batch. They are small, but they can get the same treatment later. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution in Claude Code. ## 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>
175 lines
7.2 KiB
TypeScript
175 lines
7.2 KiB
TypeScript
// @vitest-environment node
|
|
|
|
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
|
import { QueryClient, QueryObserver } from "@tanstack/react-query";
|
|
import type { Issue } from "@paperclipai/shared";
|
|
import { __liveUpdatesTestUtils } from "./LiveUpdatesProvider";
|
|
import { createCoalescingQueryClient, createInvalidationBatcher } from "../lib/query-invalidation-batcher";
|
|
import { queryKeys } from "../lib/queryKeys";
|
|
|
|
const COMPANY = "company-1";
|
|
const ACTOR = { userId: "user-1", agentId: null };
|
|
const POOL_KEY = queryKeys.issues.mentionPool(COMPANY);
|
|
const WINDOW_MS = __liveUpdatesTestUtils.MENTION_POOL_REFRESH_WINDOW_MS;
|
|
|
|
function task(id: string): Issue {
|
|
return { id, identifier: id.toUpperCase(), title: `Task ${id}` } as Issue;
|
|
}
|
|
|
|
function mountQuery(client: QueryClient, queryKey: readonly unknown[], data: unknown[] = []) {
|
|
const queryFn = vi.fn(async () => data);
|
|
const observer = new QueryObserver(client, { queryKey, queryFn, staleTime: 60_000 });
|
|
const unsubscribe = observer.subscribe(() => {});
|
|
return { queryFn, unsubscribe };
|
|
}
|
|
|
|
async function settle(ms = 0) {
|
|
await vi.advanceTimersByTimeAsync(ms);
|
|
}
|
|
|
|
/** Authenticated sockets carry no `details`, only the closed identity flag. */
|
|
function authenticatedEvent(entityId: string, action: string, taskIdentityChanged: boolean) {
|
|
return { entityType: "issue", entityId, action, actorType: "agent", actorId: "agent-1", taskIdentityChanged };
|
|
}
|
|
|
|
function emit(client: QueryClient, payload: Record<string, unknown>) {
|
|
__liveUpdatesTestUtils.invalidateActivityQueries(client, COMPANY, { entityType: "issue", ...payload }, ACTOR);
|
|
}
|
|
|
|
const POOL = [task("t1"), task("t2"), task("t3")];
|
|
|
|
describe("LiveUpdatesProvider @task mention pool", () => {
|
|
let client: QueryClient;
|
|
beforeEach(() => {
|
|
vi.useFakeTimers();
|
|
client = new QueryClient();
|
|
});
|
|
afterEach(() => {
|
|
client.clear();
|
|
vi.useRealTimers();
|
|
});
|
|
|
|
it("does not refetch for a burst of authenticated progress events on pooled tasks, and reorders in place", async () => {
|
|
const pool = mountQuery(client, POOL_KEY, POOL);
|
|
const otherList = mountQuery(client, [...queryKeys.issues.list(COMPANY), "descendants", "t1"]);
|
|
await settle();
|
|
expect(pool.queryFn).toHaveBeenCalledTimes(1);
|
|
|
|
for (let i = 0; i < 25; i += 1) {
|
|
emit(client, authenticatedEvent("t3", "issue.comment_added", false));
|
|
emit(client, authenticatedEvent("t3", "issue.updated", false));
|
|
emit(client, authenticatedEvent("t2", "issue.checked_out", false));
|
|
await settle();
|
|
}
|
|
await settle(WINDOW_MS * 2);
|
|
|
|
expect(pool.queryFn).toHaveBeenCalledTimes(1);
|
|
expect(client.getQueryData<Issue[]>(POOL_KEY)?.map((issue) => issue.id)).toEqual(["t2", "t3", "t1"]);
|
|
// Other company-scoped issue queries keep their live refresh.
|
|
expect(otherList.queryFn.mock.calls.length).toBeGreaterThan(1);
|
|
pool.unsubscribe();
|
|
otherList.unsubscribe();
|
|
});
|
|
|
|
it.each([
|
|
["an authenticated identity change", authenticatedEvent("t9", "issue.updated", true)],
|
|
["a created task", { entityId: "t9", action: "issue.created", details: { identifier: "T9" } }],
|
|
["a deleted task", { entityId: "t1", action: "issue.deleted", details: {} }],
|
|
["a renamed task", { entityId: "t1", action: "issue.updated", details: { title: "Renamed" } }],
|
|
["a hidden task", { entityId: "t1", action: "issue.updated", details: { hiddenAt: "2026-11-07T00:00:00.000Z" } }],
|
|
["an unhidden task", { entityId: "t1", action: "issue.updated", details: { hiddenAt: null } }],
|
|
])("refetches immediately for %s", async (_label, payload) => {
|
|
const pool = mountQuery(client, POOL_KEY, POOL);
|
|
await settle();
|
|
emit(client, payload);
|
|
await settle();
|
|
expect(pool.queryFn).toHaveBeenCalledTimes(2);
|
|
pool.unsubscribe();
|
|
});
|
|
|
|
it("refetches at most once per window when events touch tasks outside the pool", async () => {
|
|
const pool = mountQuery(client, POOL_KEY, POOL);
|
|
await settle();
|
|
|
|
for (let i = 0; i < 20; i += 1) {
|
|
emit(client, authenticatedEvent(`outside-${i}`, "issue.comment_added", false));
|
|
await settle(100);
|
|
}
|
|
expect(pool.queryFn).toHaveBeenCalledTimes(1);
|
|
|
|
// The trailing refresh lands one window after the last fetch.
|
|
await settle(WINDOW_MS);
|
|
expect(pool.queryFn).toHaveBeenCalledTimes(2);
|
|
|
|
// Quiet afterwards: no further refetch without new events.
|
|
await settle(WINDOW_MS * 2);
|
|
expect(pool.queryFn).toHaveBeenCalledTimes(2);
|
|
pool.unsubscribe();
|
|
});
|
|
|
|
it("only marks an unmounted pool stale", async () => {
|
|
const pool = mountQuery(client, POOL_KEY, POOL);
|
|
await settle();
|
|
pool.unsubscribe();
|
|
emit(client, authenticatedEvent("outside", "issue.updated", false));
|
|
await settle(WINDOW_MS * 2);
|
|
expect(pool.queryFn).toHaveBeenCalledTimes(1);
|
|
expect(client.getQueryState(POOL_KEY)?.isInvalidated).toBe(true);
|
|
});
|
|
|
|
it("keeps a pending refresh when a later event reorders a closed picker's pool", async () => {
|
|
const pool = mountQuery(client, POOL_KEY, POOL);
|
|
await settle();
|
|
pool.unsubscribe();
|
|
const fetchedAt = client.getQueryState(POOL_KEY)?.dataUpdatedAt;
|
|
// A rename while the picker is closed marks the pool stale without a fetch.
|
|
emit(client, { entityId: "t1", action: "issue.updated", details: { title: "Renamed" } });
|
|
emit(client, authenticatedEvent("t3", "issue.comment_added", false));
|
|
await settle();
|
|
const state = client.getQueryState(POOL_KEY);
|
|
expect(state?.isInvalidated).toBe(true);
|
|
expect(state?.dataUpdatedAt).toBe(fetchedAt);
|
|
|
|
// Reopening the picker within staleTime still fetches the renamed list.
|
|
const reopened = mountQuery(client, POOL_KEY, POOL);
|
|
await settle();
|
|
expect(reopened.queryFn).toHaveBeenCalledTimes(1);
|
|
reopened.unsubscribe();
|
|
});
|
|
|
|
it("does not reset the freshness clock when it reorders in place", async () => {
|
|
const pool = mountQuery(client, POOL_KEY, POOL);
|
|
await settle();
|
|
const fetchedAt = client.getQueryState(POOL_KEY)?.dataUpdatedAt;
|
|
await settle(5_000);
|
|
emit(client, authenticatedEvent("t3", "issue.comment_added", false));
|
|
await settle();
|
|
expect(client.getQueryData<Issue[]>(POOL_KEY)?.[0]?.id).toBe("t3");
|
|
expect(client.getQueryState(POOL_KEY)?.dataUpdatedAt).toBe(fetchedAt);
|
|
pool.unsubscribe();
|
|
});
|
|
|
|
it("coalesces a burst through the live-event batcher into one broad refresh", async () => {
|
|
const batcher = createInvalidationBatcher(client);
|
|
const coalescing = createCoalescingQueryClient(client, batcher);
|
|
const invalidate = vi.spyOn(client, "invalidateQueries");
|
|
const pool = mountQuery(client, POOL_KEY, POOL);
|
|
const otherList = mountQuery(client, [...queryKeys.issues.list(COMPANY), "descendants", "t1"]);
|
|
await settle();
|
|
|
|
for (let i = 0; i < 30; i += 1) {
|
|
__liveUpdatesTestUtils.invalidateActivityQueries(coalescing, COMPANY, authenticatedEvent("t1", "issue.comment_added", false), ACTOR);
|
|
}
|
|
await settle(1_000);
|
|
|
|
const broad = invalidate.mock.calls.filter(([filters]) =>
|
|
JSON.stringify(filters?.queryKey) === JSON.stringify(queryKeys.issues.list(COMPANY)));
|
|
expect(broad).toHaveLength(1);
|
|
expect(otherList.queryFn).toHaveBeenCalledTimes(2);
|
|
expect(pool.queryFn).toHaveBeenCalledTimes(1);
|
|
batcher.dispose();
|
|
pool.unsubscribe();
|
|
otherList.unsubscribe();
|
|
});
|
|
});
|