Files
PaperClipAI/doc/ui-internals.md
T
DottaandPaperclip 7f9867895c fix(ui): keep automated work out of personal recents (#22024)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The sidebar helps each person return to their own work.
> - A task visit previously added any readable task to personal recents.
> - Automated updates also moved old tasks above newer personal work.
> - The Mine inbox already defines personal participation.
> - This pull request applies that rule to recent task candidates and
preserves their order during background updates.
> - Users can see current task status without a stream of unrelated
automated work.

## Linked Issues or Issue Description

**What happened?**

Routine tasks and imported GitHub review tasks appeared in personal
recents after a read. Later agent updates moved these tasks up the list.
A connected account or stored creator ID could make these tasks look
like personal work.

**Expected behavior**

A task must pass the viewer's existing Mine participation rule before it
appears in personal recents. Routine ownership, connected-account
provenance and reads alone do not qualify. A viewer can qualify through
manual creation, assignment, a direct comment, an allowed user action or
a live request addressed to them. Inbox archive state does not remove
personal history. Passive reads and machine updates must not advance its
order.

**Steps to reproduce**

1. Open an automated routine task or imported review task without
participating in it.
2. Check the sidebar recents.
3. Let an agent update an older task while newer personal work is in the
list.
4. Before this fix, the automated task appears and background updates
can move older tasks up.

## What Changed

- Add a viewer participation field to bounded navigation summaries.
Reuse the canonical Mine query and existing access checks. The field is
a read projection; no database migration is needed.
- Show only confirmed personal tasks. Remove old nonparticipants after a
successful read. Do not trust participation from local storage or full
task caches.
- Keep status and title snapshots current without changing personal
order. Explicit local edits and comments can advance recency.
- Migrate browser history once to a new storage version. Older tabs
cannot restore machine-driven ordering.
- Keep confirmed rows visible if a new batch request fails. Keep these
facts within the current account and company. Hidden candidates do not
bypass the one-second reorder delay.
- Record sidebar renames as local activity. Place a first passive visit
below existing history.
- Use the saved comment time for comments sent with reassignment or
custom run settings. Pending sends do not advance recency.
- Keep readable subtasks as context beneath qualifying parents. Keep
inbox archive independent of recents.
- Update the design rules, UI behavior notes, regression tests and
Runner source contract pin.

## Verification

- Current head: `92ece0e61859a6c54b714b3611f062ff9b5633bb`. The PR
merges cleanly with current master.
- Latest red/green: both configured-comment cases failed before the fix
and now pass. Reassignment and custom run settings advance recency only
after the comment saves, using its saved time.
- Latest local checks: 339 tests passed across IssueDetail and recent
storage, hooks and sidebar. UI typecheck and diff checks passed.
- Earlier local coverage: 592 targeted API/UI tests passed. After the
master conflict resolution, all 29 overlapping Gmail tests and the
548-input source registry check passed.
- Both Greptile and Paperclip Review report 5/5 on the current head. All
four review threads are resolved.
- Current-head [CI attempt
2](https://github.com/paperclipai/paperclip/actions/runs/44132164473)
passed, including the final verify gate, build, typecheck, browser
shards, serialized tests, Runner checks and all general-test shards. The
workspace-a (1/2) retry passed after the first attempt hit an
asynchronous jsdom/Radix event error in NewAgentDialog.
- `pnpm verify` requires broader CI because DESIGN.md changed. No full
local suite or deployed-browser acceptance was claimed. This change is
not deployed.

## Risks

- Unknown eligibility stays hidden until the summary succeeds. Failed
requests preserve saved candidates and previously confirmed state within
the current account and company, including after batch changes.
- This intentionally removes automated tasks from old personal history
when the viewer has no qualifying participation.
- Readable subtasks under a personal parent remain context. They do not
become independent recent entries from machine activity.
- No task ownership, routine definition, inbox membership or permission
rule changes.

## Model Used

OpenAI GPT-6, running as Codex, with reasoning, repository tools and
focused test execution. No additional model workers were used.

## 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

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-17 11:25:58 -06:00

17 KiB
Raw Blame History

Board UI internals

Browser-side behavior: the saved read cache, write and connection recovery, startup, and bundled fonts.

UI Fonts And Screenshots

The board UI ships its own sans-serif webfont assets in ui/public/fonts/. ui/src/index.css declares Inter v4.1 variable regular and italic faces and wires the Tailwind font-sans token to those bundled files before system fallbacks. Linux screenshot or Storybook capture jobs should not install host Inter packages or inject external font CSS to make Paperclip text render correctly.

Font assets live in Vite's public directory so pnpm --filter @paperclipai/ui build emits them under ui/dist/fonts/. The server package copies the same output into server/ui-dist/fonts/ through scripts/prepare-server-ui-dist.sh.

Recent task ordering

The streamlined sidebar keeps recent task candidates per company and account in browser storage. A task appears only after the authenticated navigation summary confirms personal participation using the same rule as Mine: manual creation, human assignment, a direct comment, a meaningful audited action, or a live request addressed to the viewer. Routine ownership, connected-account provenance and read-only visits do not qualify. Inbox archive is independent of this personal history. Readable children remain contextual navigation beneath a qualifying parent.

Local human actions advance recency. Passive visits and background title, status and readiness refreshes preserve the recorded time and never promote a task. New passive candidates enter below existing history without using server update time. A successful sidebar rename records explicit local human activity. Activity-only reorderings wait for one second without further activity changes; new and removed tasks appear immediately. Titles, status, and live indicators stay current during that delay.

The sidebar validates saved candidates with company/account-scoped summary queries, using bounded parallel chunks for long histories. Viewer participation and unread facts are session data and are never trusted from browser storage. Passive refreshes do not fetch full task details or inspect workspaces. Successful omissions remove unavailable tasks and nonparticipants; failed batch reads retain saved history and any previously confirmed session state, including after a change to the candidate batch. These confirmed facts never cross account or company scopes. Unverified history stays out of the visible list and does not affect the activity reorder delay. Existing full-detail cache data can update an entry only after the current account's summary confirms access. The first healthy live subscription reconciles domain data without re-fetching session and health; reconnects and visibility recovery retain full reconciliation.

Authenticated board startup

GET /api/auth/get-session can include an optional boardBootstrap for the same authenticated session or Cloud tenant actor. It contains accessible company snapshots and the existing current-board-access projection. Directory visibility through instance admin alone does not add accessible companies. The ordinary session schema stays compatible with clients that ignore this projection.

The browser seeds account-keyed navigation and board-access queries from this response, avoiding two serial startup reads. Normal company/access readers still own invalidation and refresh. A new successful session snapshot replaces older cached membership/access for a returning account once; later ordinary reads and mutations can update those queries. Missing, malformed, or failed optional bootstrap falls back to those readers; a failed session does not become an anonymous cache entry. Local trusted startup keeps its existing synthetic local-board principal.

Browser write recovery

Use useDurableAutosave for replayable field updates and useDurableSubmit for user submissions that have an idempotent server contract. Bind queued jobs to the original task and save callback. A task switch must not retarget pending work. Keep the original creation key when a restored draft needs its attachments again; attachment selection order does not create a new request. Document and decision writes with an uncertain response verify the saved result before reporting failure. Verification reads can themselves need retry. Conflicts and permanent failures must reach the caller. Once automatic attempts stop, show Resend now instead of promising another automatic attempt. See the hook, document, task creation and connected-task banner tests for these contracts.

Inline editors preserve typing through the first owner lookup and remount after a known draft owner changes. Connected-channel sends use account-scoped storage and publication queries; retries and receipts retain the original account generation. Returning to that account restores its saved send for an explicit same-key retry. Earlier unowned channel receipts are preserved without revealing or replaying their text. They require inspecting Activity before a new send because their original sender cannot be established safely. After checking Activity, a person can explicitly discard the unowned browser record to start a fresh update. This never replays the old text or cancels an already accepted publication; storage failures keep the hold in place.

Task-creation drafts and recovery state are account-scoped. A known account change remounts the dialog, clears staged in-memory files and stops old creates before any subsequent upload. An interrupted account-bound request stays pending under its original key; it is never relabelled as a provider refusal. Legacy unowned form drafts remain in browser storage but are not restored into another account. Storybook fixtures seed the same account-specific keys.

New-task submissions use useBackgroundSubmitQueue around useDurableSubmit. The account-scoped queue retains each request's original key and draft snapshot before the composer closes. The worker sends requests in order. A request with an uncertain receipt retains its key; a rejection restores the submitted draft or offers a retry beside a newer draft. Submitted files use separate IndexedDB keys for the account, company, and request, so finishing an older save cannot remove newer files. Each submitted request has its own local-storage entry. A write or receipt in one tab cannot replace another tab's queued requests. Legacy queue arrays migrate to separate entries before the shared array is removed. Legacy single-request recovery records remain readable.

New-task staged file bytes are stored in IndexedDB for the account and company. Writes merge the selected files with the current saved list in one read/write transaction. Removal and successful creation delete only the files that the mounted draft removed. Other open tabs keep their saved files across reloads.

Successful pending-record writes have the same readable size range as browser storage. In particular, a large task description cannot silently drop its creation key on reload. Reselected text documents recover their original file-to-document-key mapping before fingerprint comparison and upload. Document editors remount on subject changes, and a message attempt settles only once when a server receipt races its HTTP retry. Startup autosaves bind to the first resolved account; a later known-account change still cancels old work. Account-bound status changes and decisions also wait for the first lookup rather than rejecting an action made while it loads. Waiting work starts a bounded retry of a failed session lookup; exhaustion reaches the original error callback instead of leaving the operation pending. Removing that session scope cancels its lookup work. Account cancellation after an uncertain POST keeps the original request key. Comment retries check the original account generation at the click and again immediately before their POST, including after optimistic cache cancellation or conversation creation. A retained accepted comment returns its existing receipt before the route can reopen a completed task. server/src/services/issue-comment-receipt.ts completes reference and activity records for keyed board comments. It locks the same-company task before its comment, matching task and company deletion, comment removal and tombstoning. It repairs references and inserts a missing activity record in one transaction, and publishes after commit. The task uses FOR NO KEY UPDATE so concurrent comments can reference each other without blocking foreign-key checks. Both the initial send and a retained receipt use this owner so concurrent completion cannot duplicate the activity. Large comment request records use the same readable range as successful writes, including JSON-escaped bodies. Account changes retire only the original optimistic echo and cannot apply its rollback to the next account.

Browser realtime connection recovery

If a browser cannot construct a WebSocket, the live-update and run transcript clients use their disconnected retry paths. While the company event stream is disconnected, visible active queries refresh every 15 seconds. This fallback stops when the socket opens, the tab is hidden, or the provider unmounts. A reconnected socket also refreshes visible queries to recover missed events. Run log views retain their existing HTTP polling fallback.

Company context during hot reload

The company React context retains only its object identity in Vite's per-module hot.data. Provider values remain in the mounted React tree and keep their normal account scope. This lets a refreshed consumer read a provider from the preceding module version. Production builds do not use the development cache.

Run pnpm test:e2e:browser-context to test this with real Vite modules and Chromium. The test starts its own loopback Vite server and mocks API responses; it needs no running Paperclip instance or provider credentials. The same spec lives in the default test:e2e discovery tree, so the existing Chrome CI shards run it on pull requests.

Read resilience during deploys

Read surfaces use useQueryView and QueryErrorState. Transient refetch failures keep loaded data visible. An initial outage keeps a quiet placeholder until recovery. Authorization, missing resources and validation failures still show readable errors. Exhausted first reads on a reachable server offer Retry, including task filters and hierarchy reads. Health probes and the socket own app-wide recovery; a successful component load may be an older in-flight response or a local no-op. Sensitive manual reads use useResilientFetch; browser viewer URLs and pairing previews remain in component memory and never enter a shared cache.

Run node scripts/check-query-error-rendering.mjs. The guard now enforces across ui/src, including multiline expressions, and CI runs it as a policy check. Its small allowlist covers standalone preview/performance fixtures, transcript protocol result flags, and the existing account-resolution and Copilot discovery retry owners. These are not ordinary read-error renders. Additions require a specific reason; do not allowlist a page to hide an outage regression.

The browser saves a small read cache in paperclip:query-cache:v1:* local storage records. It contains session display identity, health and shell preferences, company and sidebar data, agent/project lists, plugin UI contribution metadata, the first inbox page (including up to 100 rows per legacy Inbox query), and up to 20 recently opened tasks. Records belong to one user and company, expire 24 hours after each read, and are discarded when the build changes. Normal in-memory query garbage collection does not erase saved recent tasks or extend their expiry. Builds without a source commit stamp skip read-cache hydration and persistence, but still revoke and clear saved reads on sign-out. Plugin contributions use the existing instance-wide query inside the user's root record. Session tokens, bootstrap payloads, documents, comments, browser viewer capabilities, pairing data, other queries and mutations are excluded, with one exception for the saved recent tasks below. Task content in this allowlist remains on the browser until expiry or sign-out; use the normal sign-out action to clear it across tabs.

The first chat frame of each saved recent task is also saved, so a hard load of a task the user opened before shows its conversation before any server response. The owner approved saving recent comments for this on 2026-11-14. The saved reads are only the ones that first frame waits for: the recent comments window (at most 50 comments, the newest ones), their input facts, recent activity, the recent run window, interactions, attachment metadata (never file contents), live and active runs, work products and the plan document. They follow the 20-task limit and are stored in the task's own user and company record. Each task's saved chat is limited to 192 KiB and all saved chat to 1 MiB, newest tasks first. A record that storage refuses is saved again without its chat, so saved chat never displaces the rest of the cache. The other field exclusions (tokens, credentials, environment values and the like) still apply. Saved chat expires 24 hours after it was read, like every other entry. A 401 or 403 on the task or on any of its chat reads, or a 404 on the task or its comments, removes the task and its saved chat from memory and storage at once. A 404 on a plan, run or work-product read does not, because it does not mean the task is gone (a task without a plan answers 404). Restored reads are shown immediately and revalidated through the page's chat bootstrap; its answer replaces them, and they never replace newer data already in the page. Account changes also detach pending shared GETs so a new user cannot join the previous user’s private reads. Editors that need fields excluded from the display cache, including bulk agent settings, fetch complete current data before opening.

Restored identity permits cached display only. Restored inline task drafts compare their saved base with a fresh field read before each replay; conflicting edits stay in the editor for review. Account-bound writes wait for a fresh server session and are cancelled if its user changes. A definitive session denial removes saved account reads. Service-worker updates reload hidden tabs only after connectivity is online and mutations, durable sends and autosaves have settled. Durable queues synchronously report each unresolved operation, including the intervals between online rate-limit retries. Sign-out revocation also works on plain-HTTP installs without crypto.randomUUID.

The read cache also retains up to 100 learned link previews for the current user and accessible companies, including unavailable results. Reloading restores the last known PR status without a provider request. Preview timestamps keep their original age: hover or keyboard focus reuses a fresh result and refreshes a stale one. Stale status stays visible until then. Preview retention uses the same 24-hour expiry, build boundary, membership checks, and sign-out cleanup as other saved reads. It does not add polling or fetch every PR on page load.

Embedded plan documents and preview work products are stripped from saved payloads. A denied task clears its UUID and identifier projections. Sign-out revocation markers contain no task content and remain after sign-out to reject stale records and delayed writes from older tabs. Session responses started before revocation cannot restore those reads, even before the storage event reaches the other tab.

Cached agents retain only safe adapter display fields and an empty runtime configuration. Their configuration objects remain present for existing display consumers; provider credentials and environment values are excluded.

A restored task shows its header and properties while uncached history is still loading. History is not persisted, and its normal placeholder remains until reads recover. The header stays visible across recovery.

Query-cache cleanup snapshots storage keys before deletion because native storage can reorder them as records are removed. Flush cleanup affects only its owning account and yields if another account becomes active.

Run pnpm exec playwright test -c tests/e2e/playwright.config.ts tests/e2e/disconnect-resilience.spec.ts for the built-UI outage regressions. The suite uses fresh isolated local data, 20-second API interceptions, and a controlled sign-out session response. It covers retained tasks, comment and document recovery, queued-comment reloads, cached settings/sidebar/task reads, legacy Inbox reloads, real error status handling and sign-out clearing across several company records. The existing CI e2e shards discover it automatically. A real hosted restart or deploy remains a separate acceptance check.