mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 11:54:35 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Mine inbox is the board's main list of work for one person; the
app saves its query cache in `localStorage` so a returning visit can
paint from it
> - On a hard load the saved cache gave no benefit: Mine restored its
rows but still held them until the first approvals, join-request and
dismissal reads answered, because those items sort in among task rows by
time and a late one would push rows down (#20407)
> - Those three reads were not saved, so every returning visit waited on
the network for items it showed a minute before
> - This pull request saves what Mine showed from those reads, as one
record per user and company, and lets it answer the wait on a returning
visit while every read refreshes in the background
> - The benefit is that a returning visit shows its rows with no API
response at all; the first visit keeps its bounded wait unchanged
## Linked Issues or Issue Description
**What happened?**
A returning hard load of `/:companyPrefix/issues?view=mine` with the
saved cache present (`paperclip:query-cache:v1:<user>:<company>`) showed
rows no sooner than with the cache cleared. On the hosted staging
instance, rows appeared about 40 ms after `GET
/companies/:id/join-requests?status=pending_approval` returned in 7 of
10 runs.
**Steps to reproduce**
1. Open Mine once so the app saves its query cache.
2. Delay API responses (for example 300 ms) and reload.
3. Rows appear only after the approvals and join-request reads answer.
**Expected behavior**
Rows show from the saved cache at once. The reads refresh in the
background.
Related: #20407 (kept approvals and join requests in the reveal gate),
#20408 and #20419 (Mine snapshot and its perf guard), #20591 (removes
the second wave of reads; merged), #20592 (task chat preload; merged).
## What Changed
- `ui/src/lib/inbox-mine-reveal-sources.ts` (new): the record `["inbox",
companyId, "mine-reveal-sources", userId]` holds the approvals visible
in Mine, the pending join requests, and the dismissals of those items
and of Mine's failed runs. A record over 256 KB is replaced by an empty
`incomplete` record that never answers the wait. `readMineRevealSources`
accepts a record only for the same user and company.
- `ui/src/lib/persisted-query-cache.ts`: the saved cache keeps that
record per user and company, only when its data names the same user and
company as its key.
- `ui/src/pages/Inbox.tsx`:
- Mine writes the record once approvals, join requests and dismissals
all have server answers.
- On a returning visit with a restored Mine snapshot, the saved
approvals, join requests and dismissals stand in while their reads are
pending, and after a transient failure. A refusal (401/403/404) or a
server answer replaces them. The first-attempt wait is skipped only when
saved values stand in; the first visit is unchanged.
- Selection fix: the selected row's key is recorded only when the
selection moves. Before, every list change recorded the row now at the
old index before the re-anchor ran, so a row inserted above the
selection (a late approval, or any live insert) moved the selection to
another row.
- `ui/src/hooks/useInboxBadge.ts`: `useInboxDismissals` takes an
optional saved `fallback` and returns `hasServerData`. Other callers are
unchanged.
- Tests:
- `Inbox.test.tsx`: a returning visit reveals rows and the saved
approval while the reads are pending, then keeps selection on the same
row when a newer approval arrives above it; a transient failure keeps
the saved approval and a 403 drops it; a record stamped for another user
is ignored and the page waits as a first visit does.
- `inbox-mine-reveal-sources.test.ts`: projection, size limit,
user/company checks, persistence scope.
- `persisted-query-cache.test.ts`: the record round-trips for the same
user, restores as invalidated, and another user's record is not saved.
- `useInboxDismissals.test.tsx`: fallback while pending, after a
transient failure, dropped after a refusal, and no fallback.
- `tests/perf/collections/mine-returning-visit.spec.ts` +
`returning-visit-fixture.ts`: production-build browser checks and the
timing case; README updated.
## Verification
- `cd ui && pnpm exec vitest run src/pages src/lib src/hooks
src/components/coordinator`: 453 files, 5574 tests pass.
- Browser checks on a disposable local instance (production UI build,
`local_trusted`, embedded PostgreSQL, Chromium headless, 1440×900):
`PAPERCLIP_COLLECTION_PERF_BASE_URL=http://127.0.0.1:<port> pnpm exec
playwright test --config tests/perf/collections/playwright.config.ts
mine-returning-visit.spec.ts`
- With every read of the company held, task rows and saved approvals
show and no company read has answered. Fails on `master`, passes here.
- An approval dismissed after the cache was saved stands in, then leaves
when the reads answer. Fails on `master` (no saved approvals), passes
here.
- Another company's Mine never shows the saved company's rows. Passes on
both.
- Timing (5 fresh contexts per arm, alternating saved/cleared, every API
response +300 ms, same instance and fixture, host load average about
20). "Responses before rows" counts API responses that finished before
the first row:
| Build | Saved cache: median (range) | Responses before rows | Cleared
cache: median (range) |
| --- | --- | --- | --- |
| `master` (`99edcd28a7`) | 1028 ms (906–3011) | 16–19 | 1502 ms
(1423–1592) |
| This PR | 625 ms (589–672) | 0 | 1632 ms (1359–1692) |
| This PR + #20591 | 625 ms (604–671) | 0 | 1495 ms (1398–1585) |
Saved cache: difference of medians 403 ms. The remaining 625 ms is
JavaScript download and route-chunk loading in a fresh browser context;
no API response precedes the rows. Cleared cache: no change is claimed;
the spread overlaps.
- Existing collection specs on this build: `parent-context.spec.ts`
passes; `startup-regressions.spec.ts` has 4 failures (partial
failure/context error and two 429 cases) that fail the same way on the
`master` build. `mine-workspaces.spec.ts` was not run (needs a database
URL for its fixture).
- Review follow-up (9da56b5515), each with a red/green test that fails
on the previous head:
- Once a saved record exists, each source's answer replaces its part at
once and a refusal (401/403/404) empties it, without waiting for the
other reads, so a reload never shows refused join requests or approvals.
- The selected row's key is also recorded when the recorded row has left
the list, so a new item arriving above the fallback row never becomes
the selection or the archive target.
- An optimistic dismissal and its rollback start from the saved
dismissals that stand in, not from an empty list.
After the rebase onto `origin/master`: `cd ui && pnpm exec vitest run
src/pages src/lib src/hooks src/context src/components/coordinator`
passes (a first run under host load average ~35 had 4 timeouts and two
files missing new dependencies; after `agent-preflight` the affected
files pass, 223 tests).
- `pnpm check:token-gates`: clean. `pnpm verify` selected broader
coverage (exit 2, perf fixture is a global CI input); required CI
supplies it.
- Not run: the hosted staging page, the full local Vitest suite.
## Risks
- Saved approvals can be stale until the read answers (or after a
transient failure). A stale approval shows briefly and its actions go to
the server, which answers with the current state. A 401/403/404 drops
the saved values.
- The record holds approval payloads and join requests for the signed-in
user's company in `localStorage`. It uses the saved cache's existing
projection (secret-like fields removed), the same per-user revocation on
sign-out, and a 256 KB limit.
- #20591 is merged, so this branch (rebased on it) gets one read of each
shell request. Without it, a returning visit still reconnects the live
socket when the session is verified; because rows now reveal sooner,
that reconnect refetches more reads (here: session, health, company list
and agents twice). With both, every shell read runs once.
- Relation to #20592 (task chat preload): both edit
`ui/src/pages/Inbox.tsx` in different places and merge cleanly in either
order (checked with `git merge-tree`). This PR does not preload
anything. #20592 starts its chat preload when `allLoaded` turns true;
with this PR that happens sooner on a returning visit, while the reads
still refresh in the background, so its preload overlaps that refresh.
#20592 is merged and this branch is rebased on it with no conflicts.
- The selection change affects every Inbox tab: the key is recorded when
the selection moves, not on every list change. Archive and removal still
clamp as before.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with
tool use (shell, file edits, Playwright). Standard context window,
reasoning enabled.
## 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>
184 lines
11 KiB
Markdown
184 lines
11 KiB
Markdown
# Tasks and Inbox cold-open checks
|
||
|
||
Run against a disposable local instance with production UI assets. The suite
|
||
creates 220 unassigned backlog tasks and 110 board approvals. It does not invoke
|
||
a model. The origin must be a loopback address.
|
||
|
||
```sh
|
||
pnpm --filter @paperclipai/ui build
|
||
PAPERCLIP_COLLECTION_PERF_BASE_URL=http://127.0.0.1:3219 \
|
||
pnpm exec playwright test --config tests/perf/collections/playwright.config.ts
|
||
```
|
||
|
||
Start the isolated instance with `PAPERCLIP_UI_DEV_MIDDLEWARE=false` to serve the
|
||
production build. The instance and its database must be disposable. These tests
|
||
retain and reuse their fixture in `test-results/collections/fixture.json`; they
|
||
only replace it when the previous company's API returns 404. Other errors fail.
|
||
|
||
The journeys check desktop and phone row budgets, incremental scrolling,
|
||
retained row identity and height, shared count-only navigation, the Coordinator
|
||
Inbox with Streamlined UI disabled, and the page-owned Needs You feed and Needs
|
||
attention task index. Screenshots and failure traces stay in `test-results`.
|
||
Request counts and row budgets are acceptance checks. They do not establish an
|
||
end-to-end latency improvement. Measure cold, warm, and Back timings separately
|
||
with the same fixture, assets, cache, viewport, and CPU/network settings.
|
||
|
||
`parent-context.spec.ts` holds the complete Mine response, including parent
|
||
metadata, then checks row geometry through deferred visible diagnostics. Mine
|
||
uses one assembled source read; it does not fetch parent or failed-task context
|
||
from the browser before reveal. Recent retains its separate index/context path.
|
||
`startup-regressions.spec.ts` covers session bootstrap and legacy fallback,
|
||
partial source errors, resolved failure context, scoped 429 recovery, and
|
||
archive/Undo persistence. Its authenticated session and failed-run responses are
|
||
simulated transport fixtures over a real local board. They do not prove hosted
|
||
login or model execution.
|
||
The embedded bootstrap case holds separate company/access responses until Mine
|
||
rows appear. Initial WebSocket reconciliation may request those endpoints in the
|
||
background; their responses must not block the first rows. Missing or mismatched
|
||
bootstrap data still requires the ordinary fallback reads.
|
||
The two 429 cases keep the existing automatic backoff and `Retry-After` policy.
|
||
They allow 45 seconds for its bounded retry window before exercising manual
|
||
Retry. Other cases keep the normal short assertion timeout. Timing samples do
|
||
not accelerate the browser clock.
|
||
|
||
`mine-workspaces.spec.ts` guards Mine against waiting on a company-wide
|
||
execution-workspace list. Its fixture (`workspace-fixture.ts`) adds a company
|
||
with 6,000 execution workspaces, 4,000 of them created for finished tasks, and
|
||
12 Mine tasks that each run in their own isolated workspace. The API cannot
|
||
create execution workspaces, so this fixture writes those rows to the instance
|
||
database. Set `PAPERCLIP_CONFIG` to the disposable instance's `config.json`
|
||
(embedded PostgreSQL), or `PAPERCLIP_COLLECTION_PERF_DATABASE_URL` to its
|
||
loopback database. The fixture is retained in
|
||
`test-results/collections/workspace-fixture.json` with the same 404 rule as the
|
||
main fixture. The spec routes isolated workspaces on for its own pages. It
|
||
checks that Mine requests only `ids`-filtered workspace summaries for the
|
||
workspaces its rows reference, that rows appear while those reads are held when
|
||
neither the Workspace column nor workspace grouping is active, and that the
|
||
Workspace column still shows each row's workspace name. Its timing case turns on
|
||
the real isolated-workspaces setting, restores it, and records cold time from
|
||
navigation start to the first Mine row (two frames after mount) over
|
||
`PAPERCLIP_COLLECTION_PERF_TIMING_RUNS` runs (default and minimum 5). It records
|
||
a native scenario without request interception and a separate diagnostic scenario that delays
|
||
workspace reads by 3 seconds. The timings are attached evidence, not budgets.
|
||
|
||
`shell-read-waves.spec.ts` hard loads Mine with every API response delayed
|
||
300 ms and counts the shell and inbox reads that used to repeat about 1.5–2.5 s
|
||
after load (session, health, company list, agents, inbox dismissals, user
|
||
directory, approvals, execution workspaces). With the saved query cache
|
||
(`paperclip:query-cache:v1:<user>:<company>`, primed by one earlier visit in
|
||
the same browser context) each read happens at most once and the live socket
|
||
opens once. Without it, the socket's catch-up read may repeat reads that
|
||
answered before the subscription, but never the session or health read. The
|
||
fixture (`returning-visit-fixture.ts`) is a company with 24 Mine tasks and
|
||
three pending board approvals, retained in
|
||
`test-results/collections/mine-returning-visit-fixture.json`.
|
||
|
||
`recent-task-open.spec.ts` covers opening a task from the sidebar's Recents.
|
||
It gives eight fixture tasks twelve saved comments each and seeds them as the
|
||
account's Recents. An idle Projects page must make exactly one
|
||
`issues/chat-bootstrap` request (at most ten tasks) and no per-task reads.
|
||
Clicking a preloaded task must show its latest comment without any of the
|
||
chat's first-frame reads (core issue, recent comments, comment input facts,
|
||
recent activity, recent runs, interactions, attachments, live and active run).
|
||
The full detail read and the task page's other side reads still follow the
|
||
first frame; the spec records them as an annotation. Its timing cases measure
|
||
click to the latest comment on screen over at least 5 fresh browser contexts
|
||
(empty HTTP cache and storage apart from Recents), natively and with 150 ms
|
||
added to every API response. They also record the idle page's API request
|
||
count. The timings are attached evidence, not budgets.
|
||
|
||
`mine-returning-visit.spec.ts` hard loads Mine with the saved query cache
|
||
(`paperclip:query-cache:v1:<user>:<company>`, primed by one earlier visit in
|
||
the same browser context). Its fixture (`returning-visit-fixture.ts`) is a
|
||
company with 24 Mine tasks and three pending board approvals, retained in
|
||
`test-results/collections/mine-returning-visit-fixture.json`. With every read
|
||
of that company held, Mine must show its task rows and saved approvals before
|
||
any of those reads answers. An approval dismissed after the cache was saved
|
||
stands in until the reads answer and then leaves. Another company's Mine never
|
||
shows the saved company's rows. Its timing case records time from navigation
|
||
start to the first Mine row with the saved cache and with it cleared, with
|
||
every API response delayed `PAPERCLIP_COLLECTION_PERF_API_DELAY_MS` (default
|
||
300 ms), over `PAPERCLIP_COLLECTION_PERF_TIMING_RUNS` alternating runs (default
|
||
and minimum 5). Each sample names the last API response before the rows and
|
||
counts the load's requests; `PAPERCLIP_COLLECTION_PERF_OUTPUT` writes the
|
||
report to a file. The timings are attached evidence, not budgets.
|
||
|
||
Run these focused browser checks before the full collection suite:
|
||
|
||
```sh
|
||
PAPERCLIP_COLLECTION_PERF_BASE_URL=http://127.0.0.1:<candidate-ui-port> \
|
||
pnpm exec playwright test --config tests/perf/collections/playwright.config.ts \
|
||
parent-context.spec.ts startup-regressions.spec.ts
|
||
```
|
||
|
||
To collect timings, build the pinned baseline production assets once and retain
|
||
that output. Build candidate UI assets only when their inputs change. Serve both
|
||
outputs from stable loopback origins. If server behavior changes, each origin
|
||
must proxy its matching pinned API revision against the same disposable database.
|
||
Using the candidate API for both arms proves only a UI comparison. Keep agents
|
||
and external providers inactive. Neither arm may migrate or reseed the shared
|
||
fixture during a comparison.
|
||
|
||
The harness checks the configured API against each UI proxy, records HTML and
|
||
entry-asset SHA-256 receipts, and records both serving API revisions. Supply full
|
||
source SHAs to label the client artifacts, then run:
|
||
|
||
```sh
|
||
INBOX_BASELINE_URL=http://127.0.0.1:<baseline-port> \
|
||
INBOX_CANDIDATE_URL=http://127.0.0.1:<candidate-port> \
|
||
INBOX_BASELINE_API_URL=http://127.0.0.1:<baseline-api-port> \
|
||
INBOX_CANDIDATE_API_URL=http://127.0.0.1:<candidate-api-port> \
|
||
INBOX_BASELINE_SOURCE_REVISION=<full-baseline-sha> \
|
||
INBOX_CANDIDATE_SOURCE_REVISION=<full-candidate-sha> \
|
||
node --import ./server/node_modules/tsx/dist/loader.mjs \
|
||
tests/perf/collections/measure-mine-context.ts
|
||
```
|
||
|
||
The script retains a four-parent, 30-child fixture, archives three completed
|
||
parents, and enables the personal Coordinator preference. Both APIs must expose
|
||
that same company. It runs five alternating pairs by default. `INBOX_PAIRS`,
|
||
`INBOX_FIXTURE_FILE`, and `INBOX_OUTPUT` override the count and evidence paths.
|
||
No request interception is used in timings.
|
||
`INBOX_NETWORK_LATENCY_MS` accepts an integer from 0 to 2000 and defaults to 0
|
||
(native loopback). A nonzero value uses Chromium CDP network emulation on every
|
||
page, with unlimited throughput and unchanged CPU. Record native and 100 ms
|
||
latency runs in separate `INBOX_OUTPUT` files; each sample labels its scenario.
|
||
CDP specifies minimum request-to-response-header latency. This controlled extra
|
||
round-trip scenario tests serial request dependencies; it does not prove hosted
|
||
latency or reproduce the full staging network.
|
||
|
||
By default, `INBOX_HTTP_CACHE=warm` warms each browser context once, then reloads
|
||
the document for each initial sample. This retains HTTP cache while clearing app
|
||
query state. `INBOX_HTTP_CACHE=cold` uses fresh browser contexts;
|
||
`INBOX_HTTP_CACHE=both` records these scenarios separately. Warm Recent-to-Mine
|
||
navigation and task-to-Mine Back retain query state. Use `INBOX_HEADFUL=1` and
|
||
`PAPERCLIP_PLAYWRIGHT_CHANNEL=chrome` when installed Chrome is the intended browser.
|
||
|
||
Initial readiness requires visible Mine rows plus two animation frames. The
|
||
report retains every sample and failure, exact row membership/order, row geometry,
|
||
asset identities, full API resource timings, request statuses and primary-request
|
||
start. Health, session, board access, companies and preferences remain timing
|
||
controls. A faster initial total alone does not attribute a gain to its final
|
||
context response. The fixed post-reveal window defaults to two seconds;
|
||
`INBOX_TAIL_MS` changes it, up to 30 seconds. Counts retain 429s and unfinished
|
||
requests rather than treating them as successful work. Use the same immutable
|
||
asset cache policy on both origins and stop builds and suites during timing runs.
|
||
|
||
Startup cases also check that shared collection controls do not require the
|
||
task-detail bundle before reveal, even when a different organization is remembered.
|
||
Code warms after the collection paints, or on task-link intent. A successful
|
||
immutable response allows module preloading to compile the cached chunk without
|
||
executing it. A failed fetch leaves the collection usable and permits navigation
|
||
without a document reload. Direct task URLs preload their static dependencies
|
||
while identity is pending. These cases must run with
|
||
production assets: development modules do not exercise the bundle boundaries.
|
||
|
||
The functional cases route feature settings and delayed responses. Routing
|
||
disables browser HTTP caching. For warm-cache timings, set the real local feature
|
||
settings and use fresh browser contexts without request interception. Keep normal
|
||
cache writes enabled so code warmed after paint can be used on the next task open.
|
||
Retain intercepted runs as separate diagnostic evidence.
|
||
Match the server's hashed asset cache policy (`public, max-age=31536000, immutable`);
|
||
Vite preview's default `no-cache` policy adds revalidation that the shipped server
|
||
does not require. Keep HTML uncached and return 404 for missing assets.
|