DottaandPaperclip
b40e6edaea
## Thinking Path > - Paperclip helps people manage AI agents and their work. > - Mine shows the work and failures that need the viewing user's attention. > - A reload waits for account access, task rows, parent captions and failure state. > - Those reads form several browser request stages before useful rows appear. > - Live invalidations can also restart the same task-list request more than once. > - This change supplies startup data together and removes redundant refresh work. > - It preserves current authority, failure presentation, archive state and row stability. ## Linked Issues or Issue Description Refs #18645. Related: #18642. This change implements the read-receipt behavior independently on current master. It does not use that PR's branch or patch. **What happened?** Mine starts its primary request after the session, company and board-access reads. It then requests parent captions and rich failure context. Four observed loads spent another 0.45–0.70 seconds after the primary rows arrived. One slower load waited 1.71 seconds for parent context. The same run observed two HTTP 429 responses. These timings identify request waits; they do not attribute the delay to SQL or Node CPU. Read receipts also invalidate general task collections and dashboards. Overlapping parent and child invalidations can start two requests and abort the first. **Expected behavior** The initial page should use one account-safe startup projection and one complete Mine response. A read receipt should refresh the affected viewer's inbox state. Each invalidation batch should refresh a covered query once. Required captions and current failure state must be ready before first reveal. Existing rows should remain usable during a transient refresh error. **Steps to reproduce** 1. Open a populated Mine inbox with parent tasks outside the visible index and a current failed run. 2. Reload with browser HTTP cache retained and application query state empty. 3. Inspect the session, company, board access, task-index and context request sequence. 4. Open or mark a task read and inspect the unrelated collection refetches. **Paperclip version or commit** Baseline: `44a9a043b80c18314d8dd89556f444dae696d3d6`. **Deployment mode** Authenticated board UI. Local proof uses the real APIs and database with a synthetic session resolver. No hosted candidate deployment is claimed. ## What Changed - Add optional, same-user `boardBootstrap` data to the existing session response. Seed account-keyed company and board-access reads from it. Keep ordinary endpoint reads for fallback, retry and live reconciliation. A returning account cannot reuse revoked cached access. Cache collection and later real refetches remain effective. - Add the board-only Mine snapshot endpoint. Reuse the canonical issue selector, private-task filtering, run-read decisions, secret redaction and interruption/recovery presentation. Assemble the fixed 100-task page, parent captions and bounded 200-run failure window on the server. Start independent reads together. Optional source errors keep successful task rows usable. - Keep array-shaped source caches for archive and undo. Key Mine source, context and reveal state by account. Validate the response's user stamp before committing it. Remove array-only cross-tab Mine broadcasts, which cannot carry its paired failure context. The server retains authenticated in-flight coalescing. - Scope read-receipt invalidation to the affected viewer's inbox, badges and chat unread state. Keep company and task audit views fresh. Preserve genuine task mutations, run updates and subscription-gap reconciliation. - Remove covered scalar-prefix invalidations within a batch. Preserve predicates, exact matches and different query/refetch constraints. A later event can still refresh again. - Retire Mine in-flight reuse after local company activity or run lifecycle changes. A post-archive read starts fresh. Old work keeps its admission slot until it settles, even if every HTTP client aborts. The eight-compute limit stays in place. - Add API, component and browser regressions. Extend the production timing harness with matching API/UI artifact receipts, retained-cache reloads, request status counts, layout checks and optional controlled network latency. Update API and verification documentation. ## Verification - Full `pnpm -r typecheck` passes. - Full `pnpm build` passes. - Token gates, map checks and diff whitespace checks pass. - 72 Inbox component tests pass. Startup-specific checks pass, including account switching, revoked cached access, malformed/absent bootstrap data and cache collection. The canonical authenticated bootstrap route also passes against real PostgreSQL. - Six real PostgreSQL Mine route cases pass, including full equivalence with legacy authorized projections, privacy, fixed bounds, membership revocation, coalescing, archive freshness and aborted-client admission. Four focused legacy coordinator controls pass. Six assembly tests pass. - Refetch and invalidation regressions pass. Meaningful pre-fix tests observed two request starts and one abort for overlapping invalidations; the fix produces one start and no abort. The archive race test observed the post-archive GET joining the old body before the fix. - All 11 existing startup browser checks pass, including Tasks/Mine code loading, desktop/mobile bounds, non-streamlined Coordinator, task navigation, failed preloading and Back position. The nine focused startup, fallback, partial-source error, rate-limit recovery, archive/undo and geometry cases also pass. The 429 cases use the inherited retry window. Archive and keyboard undo are corroborated through the real API and reload. Authentication and failure fault injection in these cases are explicitly simulated. - Matched production before/after timings are complete. Full aggregate Vitest coverage is left to CI. At 15:15 UTC, the final-head runner gate and `review` workflow pass. The 45 build/test/policy jobs are queued; the Build job has no `ubuntu-latest` runner assigned and has executed no steps, so remote aggregate results remain unverified. Paperclip Review and Superagent Security Scan are in progress. Superseded runs for this PR were cancelled. No current-head check has reported a failure; the CI checklist remains open. The remaining step is runner allocation and completion of those external checks; persistent queueing needs the repository CI owner's attention. - Greptile completed on final head `ecde295565309275c4f2fae903caf6892f1eaafd` at 5/5. The map-scope finding is fixed and resolved; there are no open review threads. ### Matched browser timings Five alternating baseline/candidate pairs per network scenario, measured serially in headful Chrome 156.0.8078.80 on Apple silicon with Node 24.22.2 and a 1440×900 viewport. Both production UIs use their matching real API revision against one fixed disposable PostgreSQL fixture: 34 tasks, 31 visible task rows, one paused agent and one terminal failure. No active agent/provider work. HTTP cache is retained; each initial sample reloads the document and clears application query state. Warm navigation and Back retain query state. CPU and throughput are native. The 100ms scenario uses CDP minimum request-to-response-header latency without request interception. It is a controlled request-dependency experiment, not a staging reproduction. Values are median milliseconds with min–max in parentheses. Paired saving is baseline minus candidate for each alternating pair; its median differs from the difference of arm medians. Positive saving favors the candidate. | Network / journey | Baseline | Candidate | Median paired saving | | --- | ---: | ---: | ---: | | Native / initial rows | 187.6 (128.9–208.5) | 191.7 (130.3–210.9) | −23.3 | | Native / Recent → Mine | 100.17 (99.90–101.87) | 100.07 (99.88–101.37) | −0.16 | | Native / task → Back | 70.45 (56.63–72.02) | 66.64 (56.52–67.71) | +4.94 | | 100ms / initial rows | 930.3 (914.1–1015.7) | 799.0 (697.1–826.0) | +211.8 | | 100ms / Recent → Mine | 100.09 (97.73–100.16) | 100.18 (96.65–100.98) | −0.02 | | 100ms / task → Back | 74.97 (62.77–75.82) | 75.47 (61.51–76.19) | +0.35 | The controlled-latency initial pairs all improve, saving 108.3–217.0ms. Native initial pairs have mixed signs (−67.5 to +78.1ms), so they establish no reliable native page-speed improvement. Warm and Back timings are effectively unchanged. Median primary-request start is 110.4→135.2ms natively and 497.8→480.9ms with 100ms latency; these runs do not establish a large startup-only timing gain. API requests through the two-second post-reveal window fall from median 32 (32–37) to 27 (25–28) natively, and 37 (33–38) to 30 (25–32) with 100ms latency. All 20 samples preserve the same ordered 31 task links, first-row DOM identity and geometry. All recorded API responses are HTTP 200; zero unfinished requests, 429s or JavaScript errors. Lower 429 incidence on staging remains unproven. Measured source: baseline `44a9a043b80c18314d8dd89556f444dae696d3d6`, candidate `4c12b2ef0ecf0754676e99bd6b9399e84408646c`. Final head `ecde295565309275c4f2fae903caf6892f1eaafd` changes only two feature-map files and existing browser test expectations since that measured candidate; production executable inputs are identical to the measured candidate. Asset hashes, API health revision receipts and every raw sample were retained. These results do not claim hosted-page improvement or deployment of this PR. ## Risks - Startup enrichment adds work to the session read. Failure of this optional projection falls back to the ordinary company and access endpoints. It does not invalidate a valid session or replace per-request server authorization. - Account changes, stale cache entries and same-company navigation can expose old presentation data. Account keys, principal stamps, reveal scopes and canonical bootstrap replacement have dedicated negative cases. Permission failures hide cached task rows; transient network, 429 and 5xx failures preserve them. - Current failure state can differ from the historical failed run. The snapshot uses the existing canonical rich projection and verified missing-ID coverage. Partial context failures retain an explicit retry path. - Mutation retirement follows events delivered to the current server process. This adds no cross-replica invalidation protocol or distributed read-after-write guarantee. - New UI assets require the matching API. Older UI/session consumers retain their existing response and endpoint behavior. There is no database migration, provider call or deployment change. ## Model Used OpenAI Codex, based on GPT-6, with reasoning, code execution, browser automation and delegated source review. The exact runtime model ID and context-window size are not exposed by this session. ## 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 - [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>
13 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Inbox, decisions, and search
People find work that needs their attention, distinguish unread activity from required decisions, archive handled items, and search across the company.
Feature ID: inbox-search.
Implementation: inbox, decisions, search.
Agent access: companion.
Sub-features
views:inbox-search/views— use Mine, Recent, Unread, Blocked, and broader task views.triage:inbox-search/triage— read or archive attention items without pretending the underlying task is complete.decisions:inbox-search/decisions— open the source of a decision and act in the right context.search:inbox-search/search— query company work and follow a result to its original record.toasts:inbox-search/toasts— receive live task notifications only for personal participation or explicit mentions.
How to get to it (user POV)
inbox
Use Inbox links or the corresponding task views when the combined list is enabled.
decisions
Open /decisions, then a queue at /decisions/queues/:key and its source item.
With Settings → Experimental → Coordinator workspace enabled, /decisions
is Needs You. Pending cards use the existing attention feed and canonical
resolvers. Tasks → Needs attention projects the same feed as distinct tasks.
Search, filter by agent/project, sort, and group by task/agent/project apply to
both open decisions and the visible Recent Decisions receipts. Successful
resolutions resize into compact receipts while the same contained Gather Light
effect used for task creation runs concurrently. The receipt stays in its card
position until that treatment finishes, then settles under Recent Decisions.
Motion follows the saved history result; failed saves retain the actionable card,
reduced motion settles immediately, and revisiting history does not replay it. The initial
24-hour display window is an experimental assumption, not data deletion.
Resolving an artifact decision does not itself complete its task. If the task
remains in review without a maintained reviewer or continuation, its separate
canonical stalled-review item stays in Needs You and Tasks → Needs attention.
Coordinator presents the existing recovery actions with Mark task done as
the task-level verdict, distinct from the saved artifact receipt.
Open Decision history on this surface for the paginated history sidebar; it merges answered questions and confirmations with Decisions-v1 outcomes.
search
Open /search or the navigation search entry.
toasts
Keep a company page open while another person or agent updates a task. See toast semantics for eligibility and suppression rules.
Driving it with Playwright and the Paperclip CLI
Preconditions: follow the baseline. Seed assigned, unread, blocked, and resolved tasks plus a pending decision. Record the combined Inbox/Tasks experimental setting.
inbox
Automated: archive routes cover server mutations. Task-list helpers cover search URLs, pagination, and presentation constants; they do not render the combined Inbox/Tasks page. Reading, archiving, and navigating that page remain manual checks.
Automated: Issue service regressions cover exclusion of historical automatic read cleanup from user participation, unread counts, and activity timestamps while retaining explicit user decisions and audit history.
Automated: Source regressions cover channel attribution, imported comments, direct participation, addressed requests, unread results, and access checks. Routine regressions cover fresh, coalesced, and skipped manual runs. The source regressions also create an addressed request through the service for a human assignee. They check unread lists, flags, and counts, plus exclusion of historical questions and closed requests while preserving authorization requests.
Manual: Seed GitHub, Slack, scheduled routine, and manual routine tasks. Attribution, imported comments, and reading alone keep them outside Mine. Direct board/API comments, human assignment, and open addressed requests admit them. Resolve the request and check that another valid reason is needed. Inbox discovery and Blocked hide unrelated automation by default; the Show agent-created tasks checkbox reveals it without subscribing the user. Reload and verify membership, unread badges, archive/resurfacing, and preference persistence.
Manual: Read an unread task, return to Unread, archive a handled item, and reload. Verify personal triage state changes while task status stays correct. Switch users and companies to check isolation.
Seed a completed task whose only activity under the viewing user is automatic read cleanup. Refresh Mine and Unread: the task must not appear through that participation, while the cleanup remains in activity history. Record an explicit user recovery decision on a separate task and verify it still counts. This browser journey remains manual.
Cold-open verification: load Mine with its snapshot response delayed while approvals resolve. Only the stable list placeholder should appear until the initial sources settle; a failed-run row must not jump when tasks arrive. Release visible-row details separately and compare row/title bounds. Mine reads its own 100-row snapshot with parent/run context; sidebar badges use the count endpoint. The Inbox component checks cover the source barrier and selected-source query; badge tests cover unread counts. Browser timing and layout proof remain separate from these tests.
decisions
Automated: decision queues covers route behavior. End-to-end queue-to-source navigation is manual.
Manual: Open a pending decision, follow its source, resolve it through the supported control, and reload the queue. Confirm it retires only after the decision persisted and unrelated pending items remain.
Coordinator regression sources: canonical history exercises real PostgreSQL cross-source pagination, answered-question retention, company/private-task isolation, and private v1 targets. Attention service regressions cover pending question forms and confirmations in persistent agent chats, removal after an answer with retained history, and company/task-visibility/addressee checks. Idle chats without structured requests remain absent. The Needs You component test checks that a chat-sourced canonical question reaches its original resolver and context. It also checks simultaneous resize/light and delayed movement to Recent Decisions. Shared card-motion tests cover reduced-motion settlement and returning to a resolved card without replay. The decision-motion stories exercise real Needs You/resolver components with isolated approval, question, and failed-save responses. Projection helpers cover distinct pending task membership and presentation-only recency decay. Browser verification must additionally approve copy, approve a visual, and answer a question; confirm three retained receipts, task/chat consistency, resize/collapse motion, and exact task context on receipt click. Turning the setting off restores the classic surface.
search
Automated: search page and company search service cover UI and server search separately.
Manual: Search a unique task title and content phrase, open the result, and compare the actual record. Test filters, no results, and a second company. Verify stale results do not expose inaccessible data.
toasts
Automated: persisted eligibility
checks creation, assignment, comments, mentions, deliberate edits, excluded read
activity, company isolation, local-board, and persisted run-task attribution.
Socket delivery checks
viewer-specific projection; UI delivery
checks eligibility gating, cache updates, stale callbacks, and existing suppression.
UI cache handling checks visible
comment refresh when authenticated events omit hydration metadata.
The task toasts follow personal involvement in multiplayer case in the
authenticated browser suite
exercises quiet unrelated updates, read-only visits, first/historical mentions,
self-activity, and visible-task suppression against persisted data.
Manual: Use two authenticated browser sessions in the same isolated company. Create separate tasks for each person and use one shared agent. From a company task list, verify that the other person's unrelated task updates produce no toast but still refresh the list. Comment on one of their tasks, then have them update it: a toast should appear. Repeat using assignment, a deliberate edit, and a first explicit user mention in a comment or description. Reload before a later update to prove eligibility does not depend on browser history. Mere viewing, agent ownership, responsible-user attribution, and parent participation must remain quiet. Task-linked failures follow the same participation rule; generic agent errors remain quiet. Repeat while viewing the relevant task and after switching company/account to verify suppression and isolation.
Gotchas
-
Command-palette and keyboard entry points also reach search. Verify quick-filter/query handoff separately from opening the full search route.
-
Notifications do not grant task access or change Mine membership.
-
A feature-map recipe and mocked UI tests do not prove live multiplayer behavior.
-
Combined Inbox/Tasks requires both
enableCombinedInboxTasksandenableStreamlinedUi. Standalone Inbox tests render archive/read controls and toolbars; this is not live multi-user evidence. -
Personal archival is not task cancellation or completion.
-
Legacy Inbox routes can redirect to the combined task view; record which host actually rendered.
-
Search service tests do not establish the relevance quality of every query.
Storybook verification
views
Capability ID: inbox-search/views.
Scope: ui Storybook: Mine/Recent/Unread/Blocked and broader task views; combined versus standalone host; loading/empty/error/filter states. Production: Use persisted personal participation/read data; verify scoped counts and list navigation/reload; automatic read cleanup must not create Mine membership. Sources: Source: Inbox.tsx, Issues.tsx. Tests: Inbox.test.tsx, Issues.test.tsx, issues-service.test.ts
toasts
Capability ID: inbox-search/toasts.
Scope: ui Storybook: Eligible live task toast, explicit mention, quiet unrelated event, own-action/visible-task suppression, dedupe and company/account switch. Production: Persisted participation and mentions determine per-viewer socket eligibility; quiet events still refresh caches; reload retains eligibility, unauthorized resources remain denied. Sources: Source: ToastViewport.tsx, ToastContext.tsx, LiveUpdatesProvider.tsx, task-toast-eligibility.ts. Tests: ToastContext.test.tsx, ToastViewport.test.tsx, LiveUpdatesProvider.hook.test.tsx, task-toast-eligibility.test.ts, live-events-toast.test.ts, multi-user-authenticated.spec.ts