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 keeps an open task current with a shared company
websocket and with polling fallbacks
> - In a busy company, one open task sent 35 to 60 API requests in 17
seconds, and each request waits on the database
> - Most of these requests were repeated reads: task summaries 22 times,
the task run list 11 times, task browsers 6 times, and the 60 KB agent
list 6 times
> - The cause is not the open task. Other agents' run and task events
invalidate company-wide lists on every 300 ms batch, and the task view
polls runs and browsers on fixed intervals even while the websocket is
open
> - This pull request spaces company-wide refreshes, and it lets the
websocket replace run and browser polling while it is connected
> - The benefit is about 79% fewer reads from an open task in a busy
company, with the same polling fallback when the connection is down
## Linked Issues or Issue Description
Refs #17608
Refs #9627
**What happened?**
An open task in a busy company sent the same reads again and again. In
one 17-second visit, the UI requested `issues/summaries` 22 times, the
task live runs 11 times, the task browsers 6 times, and the company
agent list 6 times. The company live runs and the task's child lists
(`parentId`, `createdFromIssueId`, `descendantOf`) were requested 2 to 3
times each.
**Expected behavior**
A busy company must not make an open task refetch company-wide lists on
every event batch. While the live connection is open, the UI must use
events, not fixed fast intervals, for task runs and browsers. The UI
must keep its polling fallback when the connection is closed.
**Steps to reproduce**
1. Open a task in a company where other agents run work.
2. Keep the task open for 17 seconds.
3. Count the API requests in the browser network panel.
**Paperclip version or commit**
Based on master at bd30ef8510.
## What Changed
- `ui/src/lib/query-invalidation-batcher.ts`: Add a minimum spacing
option to the invalidation batcher. A quiet lane flushes after the
normal batch interval. A busy lane flushes at most once per spacing
window. Add `createLaneRoutingBatcher`, which sends each invalidation to
one of two batchers by query key.
- `ui/src/context/LiveUpdatesProvider.tsx`: Route company-wide keys to a
5-second ambient lane. These keys are task lists and summaries, the
agent list, heartbeats, company live runs, sidebar badges, the
dashboard, costs and the company activity feed. All other keys, such as
task detail, comments, task runs and browsers, keep the 300 ms lane.
- `ui/src/lib/live-runs-cache.ts`: While the company connection is open,
a successful active run list or active run polls every 15 seconds
instead of every 1 or 3 seconds. Run lifecycle events already refresh
these queries, and progress events patch them.
- `ui/src/hooks/useTaskBrowsers.ts`: While the company connection is
open, stop browser polling when no browser can change state. Keep the
3-second poll for a starting, running, idle or stopping browser, and
when the connection is closed. The two callers pass the task's company.
Socket open and reconnect already reconcile this active query.
- `ui/src/lib/task-browsers-refresh.ts` and `LiveUpdatesProvider.tsx`:
On `browser.*` activity for a task, refresh that task's browser list. If
a read is in flight, one shared follow-up read runs after it settles, so
an older empty result cannot stop polling. Two views of the same task
share that follow-up. A list that no view observes becomes stale, so a
returning view reads it. When the connection opens or resyncs, each
browser list with a read in flight also gets one follow-up read, because
missed activity is not replayed.
- `doc/DATABASE.md`: Document the ambient lane and the new polling
contract.
- Tests: Add a fan-out test that replays a busy-company event stream for
17 seconds against an open task, plus unit tests for spacing, lane
routing, key classification, the run interval and the browser interval.
Update the recovery test for the connected active-run interval.
## Verification
Request count over a fixed 17-second open window
(`ui/src/context/LiveUpdatesProvider.fanout.test.ts`). The test mounts
the reads that an open, running task keeps active. It replays a busy
company: one run status event every second and one task activity event
every 0.7 seconds, none for the open task. Fake timers make each run
deterministic, so the spread is zero. The baseline used the same test
with master's batcher, run interval and browser interval.
| Read | Before | After |
| --- | ---: | ---: |
| Task summaries (sidebar) | 24 | 5 |
| Company agent list | 17 | 5 |
| Company live runs | 17 | 5 |
| Child list: parent | 24 | 5 |
| Child list: created from | 24 | 5 |
| Child list: descendants | 24 | 5 |
| Task live runs | 18 | 2 |
| Task browsers | 6 | 1 |
| **Total** | **154** | **33** |
The baseline numbers match the staging capture well (summaries 22,
browsers 6).
- `pnpm exec vitest run src/context/LiveUpdatesProvider*.test.*
src/lib/live-runs-cache.test.ts
src/lib/query-invalidation-batcher.test.ts
src/hooks/useTaskBrowsers.test.ts src/lib/task-browsers-refresh.test.ts
src/hooks/useTaskPluginPanels.test.tsx
src/components/task-side-panel/TaskSidePanel.test.tsx
src/pages/IssueDetail.test.tsx` (in `ui/`): all pass.
- `pnpm exec tsc --noEmit -p ui`: no errors in `ui/src`.
- `pnpm check:token-gates`: clean.
- Tests also prove these cases:
- With the connection closed, task runs still poll every second and
browsers every 3 seconds.
- With a quiet company, one event refreshes the summaries and child
lists after one normal batch.
- `browser.started` on the open task refreshes its browsers. The same
event on another task does not.
- A browser that starts during a slow empty read appears after that read
settles (`ui/src/lib/task-browsers-refresh.test.ts`). This test fails
when the refresh joins the older read.
- Two views and repeated events during one read cause one follow-up
read. This test fails without the shared queue.
- A list cached while the task was closed is read again when a view
returns.
- A connection that opens during an older empty browser read causes one
more read, so a browser that started while the socket was closed
appears. This test fails without the follow-up.
- Task detail, comments, task runs, browsers, attention and another
company's keys stay on the fast lane.
- An unrecognized active result keeps the fallback interval.
This is a local request-count proof. It does not include a timed browser
journey on a deployed instance.
## Risks
- Company-wide lists refresh at most once every 5 seconds from live
events, so they can be up to 5 seconds late. After 5 quiet seconds, an
event refreshes them in about 300 ms. Own mutations invalidate their
queries directly, so they do not wait.
- An active task run refreshes from events. Fields without an event,
such as output silence, can be up to 15 seconds late while the
connection is open. Reconnect still reconciles missed events.
- A browser that appears without activity is not shown until the next
activity or reconnect. Every browser lifecycle step logs activity on the
task, so this case is not expected.
- No server, schema or API change.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, 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
- [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>
269 lines
11 KiB
TypeScript
269 lines
11 KiB
TypeScript
import { getPageVisibility } from "./page-visibility";
|
|
import type { InvalidateQueryFilters, QueryClient } from "@tanstack/react-query";
|
|
|
|
/**
|
|
* Coalesces React Query invalidations triggered by the live-events stream.
|
|
*
|
|
* `LiveUpdatesProvider` used to call `queryClient.invalidateQueries(...)`
|
|
* synchronously for every websocket event. During an active agent run these
|
|
* fire many times per second, and each invalidation cascades into refetches
|
|
* and re-renders — the dominant source of steady-state CPU churn (and, over a
|
|
* long-lived tab, off-heap allocation growth).
|
|
*
|
|
* The batcher collects invalidation filters over a short window, de-duplicates
|
|
* identical ones, and flushes them in a single pass at most once per interval.
|
|
* A trailing-throttle (not a pure debounce) is used deliberately: during a
|
|
* continuous event stream a pure debounce would never flush, so UI updates
|
|
* would stall; throttling guarantees the buffered invalidations flush every
|
|
* `intervalMs`.
|
|
*/
|
|
export interface InvalidationBatcher {
|
|
/** Schedule an invalidation; resolves once the batched flush has run. */
|
|
schedule: (filters: InvalidateQueryFilters) => Promise<void>;
|
|
/** Flush any buffered invalidations immediately (e.g. before teardown). */
|
|
flush: () => Promise<void>;
|
|
dispose: () => void;
|
|
}
|
|
|
|
export const DEFAULT_INVALIDATION_INTERVAL_MS = 300;
|
|
|
|
type Deferred = { promise: Promise<void>; resolve: () => void };
|
|
|
|
function createDeferred(): Deferred {
|
|
let resolve!: () => void;
|
|
const promise = new Promise<void>((r) => {
|
|
resolve = r;
|
|
});
|
|
return { promise, resolve };
|
|
}
|
|
|
|
/**
|
|
* Minimum time between two flushes of the ambient lane. Company-wide lists and
|
|
* projections (sidebar task summaries, the agent list, issue lists, badges)
|
|
* change on almost every run or task event in a busy company. After the lane
|
|
* has been quiet for this interval, an event refreshes them within one normal
|
|
* batch. An event inside the interval waits until the interval ends, so the
|
|
* lane flushes at most once per interval instead of on every batch.
|
|
*/
|
|
export const AMBIENT_INVALIDATION_SPACING_MS = 5_000;
|
|
|
|
export function createInvalidationBatcher(
|
|
queryClient: Pick<QueryClient, "invalidateQueries">,
|
|
intervalMs: number = DEFAULT_INVALIDATION_INTERVAL_MS,
|
|
options: { minSpacingMs?: number } = {},
|
|
): InvalidationBatcher {
|
|
const minSpacingMs = options.minSpacingMs ?? 0;
|
|
// Start of the last flush that sent invalidations; spacing counts from it.
|
|
let lastFlushAt = Number.NEGATIVE_INFINITY;
|
|
// Keyed by a stable serialization of the filters so repeated invalidations of
|
|
// the same key (the common case) collapse to one entry.
|
|
const pending = new Map<string, InvalidateQueryFilters>();
|
|
let timer: ReturnType<typeof setTimeout> | null = null;
|
|
// Resolves when the currently-buffered window has been flushed. `schedule`
|
|
// hands this back so callers that await it observe the real invalidation.
|
|
let windowDeferred: Deferred | null = null;
|
|
|
|
const flush = async (): Promise<void> => {
|
|
if (timer !== null) {
|
|
clearTimeout(timer);
|
|
timer = null;
|
|
}
|
|
const deferred = windowDeferred;
|
|
windowDeferred = null;
|
|
if (pending.size === 0) {
|
|
deferred?.resolve();
|
|
return;
|
|
}
|
|
const filtersList = removeCoveredFilters([...pending.values()]);
|
|
pending.clear();
|
|
lastFlushAt = Date.now();
|
|
try {
|
|
await Promise.all(filtersList.map((filters) => queryClient.invalidateQueries(
|
|
getPageVisibility().visible ? filters : { ...filters, refetchType: "none" },
|
|
)));
|
|
} finally {
|
|
deferred?.resolve();
|
|
}
|
|
};
|
|
|
|
const schedule = (filters: InvalidateQueryFilters): Promise<void> => {
|
|
pending.set(serializeFilters(filters), filters);
|
|
if (windowDeferred === null) {
|
|
windowDeferred = createDeferred();
|
|
}
|
|
if (timer === null) {
|
|
// Leading edge: a quiet lane flushes after the normal batch interval.
|
|
// Trailing edge: a busy lane waits until its spacing has elapsed.
|
|
const delay = Math.max(intervalMs, lastFlushAt + minSpacingMs - Date.now());
|
|
timer = setTimeout(() => void flush(), delay);
|
|
}
|
|
return windowDeferred.promise;
|
|
};
|
|
|
|
const dispose = () => {
|
|
if (timer !== null) {
|
|
clearTimeout(timer);
|
|
timer = null;
|
|
}
|
|
pending.clear();
|
|
// Release any awaiters so they don't hang forever after teardown.
|
|
windowDeferred?.resolve();
|
|
windowDeferred = null;
|
|
};
|
|
|
|
return { schedule, flush, dispose };
|
|
}
|
|
|
|
let uniqueFilterCounter = 0;
|
|
|
|
const EXCLUDED_QUERY_KEYS = Symbol("excludedQueryKeys");
|
|
type QueryKeyPrefix = readonly unknown[];
|
|
type ExclusionPredicate = ((query: { queryKey: readonly unknown[] }) => boolean) & {
|
|
[EXCLUDED_QUERY_KEYS]: readonly QueryKeyPrefix[];
|
|
};
|
|
|
|
function startsWithKey(key: readonly unknown[], prefix: QueryKeyPrefix): boolean {
|
|
if (prefix.length > key.length) return false;
|
|
return prefix.every((part, index) => JSON.stringify(part) === JSON.stringify(key[index]));
|
|
}
|
|
|
|
/**
|
|
* A `predicate` that skips queries under the given key prefixes. Unlike an
|
|
* arbitrary predicate, the batcher can read its exclusions, so repeated
|
|
* invalidations with the same key and exclusions still coalesce into one, and
|
|
* the filter still covers its non-excluded children in the same batch.
|
|
*/
|
|
export function excludingQueryKeys(...excluded: QueryKeyPrefix[]): ExclusionPredicate {
|
|
const predicate = ((query: { queryKey: readonly unknown[] }) =>
|
|
!excluded.some((prefix) => startsWithKey(query.queryKey, prefix))) as ExclusionPredicate;
|
|
predicate[EXCLUDED_QUERY_KEYS] = excluded;
|
|
return predicate;
|
|
}
|
|
|
|
function readExclusions(filters: InvalidateQueryFilters): readonly QueryKeyPrefix[] | null {
|
|
const predicate = filters.predicate as Partial<ExclusionPredicate> | undefined;
|
|
if (typeof predicate !== "function") return [];
|
|
return predicate[EXCLUDED_QUERY_KEYS] ?? null;
|
|
}
|
|
|
|
function filterBehaviorKey(filters: InvalidateQueryFilters): string {
|
|
return JSON.stringify([
|
|
filters.type ?? "all",
|
|
filters.refetchType ?? filters.type ?? "active",
|
|
filters.stale ?? null,
|
|
filters.fetchStatus ?? null,
|
|
]);
|
|
}
|
|
|
|
/** A collection prefix already refreshes its children in the same batch. */
|
|
function removeCoveredFilters(filters: InvalidateQueryFilters[]): InvalidateQueryFilters[] {
|
|
// Each prefix keeps the exclusions of every filter that names it; a plain
|
|
// prefix has none.
|
|
const prefixesByBehavior = new Map<string, Map<string, Array<readonly QueryKeyPrefix[]>>>();
|
|
const isScalar = (value: unknown) => value === null || typeof value === "string"
|
|
|| typeof value === "boolean" || typeof value === "number" && Number.isFinite(value);
|
|
for (const filter of filters) {
|
|
const exclusions = readExclusions(filter);
|
|
if (!exclusions || filter.exact || !filter.queryKey?.every(isScalar)) continue;
|
|
const behavior = filterBehaviorKey(filter);
|
|
const prefixes = prefixesByBehavior.get(behavior) ?? new Map<string, Array<readonly QueryKeyPrefix[]>>();
|
|
const keyJson = JSON.stringify(filter.queryKey);
|
|
prefixes.set(keyJson, [...(prefixes.get(keyJson) ?? []), exclusions]);
|
|
prefixesByBehavior.set(behavior, prefixes);
|
|
}
|
|
return filters.filter(filter => {
|
|
const ownExclusions = readExclusions(filter);
|
|
if (!ownExclusions || !filter.queryKey) return true;
|
|
const prefixes = prefixesByBehavior.get(filterBehaviorKey(filter));
|
|
if (!prefixes) return true;
|
|
const key = filter.queryKey;
|
|
// An excluded subtree overlapping this filter's subtree is not refreshed by
|
|
// the covering prefix, so that prefix does not cover this filter.
|
|
const coveredBy = (exclusions: readonly QueryKeyPrefix[]) =>
|
|
!exclusions.some((excluded) => startsWithKey(key, excluded) || (!filter.exact && startsWithKey(excluded, key)));
|
|
// A non-exact filter covers itself, so only check its shorter prefixes.
|
|
// A filter with exclusions is also covered by a plain filter on its own key.
|
|
const hasExclusions = ownExclusions.length > 0;
|
|
const last = filter.exact || hasExclusions ? key.length : key.length - 1;
|
|
for (let length = 0; length <= last; length += 1) {
|
|
if (length > 0 && !isScalar(key[length - 1])) break;
|
|
const entries = prefixes.get(JSON.stringify(key.slice(0, length)));
|
|
const sameKeyNonExact = length === key.length && !filter.exact;
|
|
if (entries?.some((exclusions) => sameKeyNonExact ? exclusions.length === 0 : coveredBy(exclusions))) return false;
|
|
}
|
|
return true;
|
|
});
|
|
}
|
|
|
|
function serializeFilters(filters: InvalidateQueryFilters): string {
|
|
// A predicate is an opaque function — two predicate-based filters can never be
|
|
// proven equal, so never coalesce them (that would silently drop one). Give
|
|
// each its own key.
|
|
const exclusions = readExclusions(filters);
|
|
if (exclusions === null) {
|
|
return `__predicate__:${(uniqueFilterCounter += 1)}`;
|
|
}
|
|
// Query selection and refetch behavior both belong to the identity. In
|
|
// particular, dropping an idle/fresh filter in favor of a paused/stale one
|
|
// can lose the only refresh that actually matches a cached query.
|
|
try {
|
|
return JSON.stringify([
|
|
filters.queryKey ?? null,
|
|
filterBehaviorKey(filters),
|
|
filters.exact ?? false,
|
|
...(exclusions.length > 0 ? [{ excluding: exclusions }] : []),
|
|
]);
|
|
} catch {
|
|
// Non-serializable filter (shouldn't happen for our query keys) — fall back
|
|
// to a unique key so it is never dropped.
|
|
return `__nonserializable__:${(uniqueFilterCounter += 1)}`;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Wrap a QueryClient so `invalidateQueries` is routed through `batcher` while
|
|
* every other method (reads, `setQueryData`, …) passes straight through to the
|
|
* real client. Returned value is a `QueryClient` and can be used anywhere one
|
|
* is expected. Private class fields keep working because methods are bound to
|
|
* the real client via `Reflect.get(target, prop, target)`.
|
|
*
|
|
* The batched `invalidateQueries` returns a promise that resolves only after the
|
|
* flush actually runs, so callers that await it still observe completion.
|
|
*/
|
|
export function createCoalescingQueryClient(
|
|
queryClient: QueryClient,
|
|
batcher: InvalidationBatcher,
|
|
): QueryClient {
|
|
return new Proxy(queryClient, {
|
|
get(target, prop) {
|
|
if (prop === "invalidateQueries") {
|
|
return (filters?: InvalidateQueryFilters) => batcher.schedule(filters ?? {});
|
|
}
|
|
const value = Reflect.get(target, prop, target);
|
|
return typeof value === "function" ? value.bind(target) : value;
|
|
},
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Route invalidations to one of two batchers by query key. `isAmbient` selects
|
|
* the slower lane (see `AMBIENT_INVALIDATION_SPACING_MS`). Every other filter,
|
|
* including one without a query key, uses the fast lane.
|
|
*/
|
|
export function createLaneRoutingBatcher(
|
|
fast: InvalidationBatcher,
|
|
ambient: InvalidationBatcher,
|
|
isAmbient: (queryKey: readonly unknown[]) => boolean,
|
|
): InvalidationBatcher {
|
|
return {
|
|
schedule: (filters) => (filters.queryKey && isAmbient(filters.queryKey) ? ambient : fast).schedule(filters),
|
|
flush: async () => {
|
|
await Promise.all([fast.flush(), ambient.flush()]);
|
|
},
|
|
dispose: () => {
|
|
fast.dispose();
|
|
ambient.dispose();
|
|
},
|
|
};
|
|
}
|