DottaandPaperclip
6dcf4160dd
## Thinking Path > - Paperclip lets people manage work done by agents. > - A standing agent chat can hold months of conversation. > - The chat route forced full-history mode, bypassing compact task loading. > - A cold visit fetched lifetime run summaries and hydrated historical transcripts. > - This PR starts with 20 recent messages and loads earlier pages on upward scroll. > - It preserves the reader's position, current questions, and draft while history grows. ## Linked Issues or Issue Description **What happened?** Standing agent chats forced full-history loading. A long conversation fetched full activity and run history before it became readable. Earlier comments also used an explicit load control. **Expected behavior** Open a small recent conversation quickly. Load older messages when the reader scrolls upward. Show an inline loading state. Keep the visible message and composer mounted through paging, live updates, and Back navigation. **Steps to reproduce** 1. Open a standing agent chat with hundreds of messages and completed runs. 2. Use a fresh browser query cache. 3. Observe full activity and run reads plus transcript requests for historical runs. 4. Compare the recent window and upward paging after this change. Related work: #18312 and #18323 restored compact task and collection loading. #14848 added reopening of visited agent chats. A GitHub search found no open PR for this chat-history optimization. ## What Changed - Return 20 contiguous recent comments for standing chats, with a stable oldest cursor. Keep the existing compact task exchange contract. Use the existing company/issue/time index for cursor reads. - Keep chats compact even if their task view previously expanded history. Retain observed messages through live catch-up and cache-backed return visits. - Keep fetched history pages, acknowledged sends, and the observed recent cursor separate. Reconcile live replies without losing history after a send or deleted cursor. - Hydrate metadata only for newly revealed message/run IDs; preserve prior batches while paging. Slow-send recovery refreshes the recent window. Receipts failures have an independent retry. - Hydrate run summaries only for loaded messages and the latest turn. Validate batches of at most 100 run IDs and keep the existing issue/company access rules. - Reuse hydrated terminal native streams when only history membership changes. Preserve retry, resume, mode changes, reconnect recovery, and interrupted recovery reads. - Load older messages, decision receipts, and task handoffs through upward scrolling. Support wheel, touch, and keyboard input. Keep pending questions visible. - Reserve a status slot while loading. Preserve a logical message anchor and the mounted composer. Pause failed page reads until an inline Retry. - Add database, route, controller, and scroll regressions, plus an opt-in production-build browser rig for long chats on desktop and mobile. Update design and feature/access documentation. ## Verification - The real PostgreSQL cold-open suite passes all 12 tests, including contiguous pages with equal timestamps, complete history, company denial, and scoped run IDs. - Activity route and OpenAPI suites pass 53 tests. The route run allowed local cold-import overhead; CI retains the repository's normal timeouts. - Three new paging regressions fail against the unchanged source. The candidate's focused paging/window suite passes 26 tests. Broader UI verification is recorded below when complete. - Desktop and mobile browser acceptance covers recent-only startup, per-frame reveal geometry, delayed and failed older pages, stable reading anchors and drafts, Back, older comment links, and one persisted live reply. - Full workspace typecheck and build passed locally. The final UI source also passes its typecheck and production build. - Affected UI suites pass: 212 controller/history/paging tests, 352 thread/scroller tests, 26 native-stream tests, plus metadata batching and live-cache hydration coverage. The issue mutation/access route suite passes 179 tests. - All 22 final desktop/mobile browser journeys pass, including delayed image growth. The isolated second-page request proof also passes six repeated desktop/mobile runs. A separate 6,000-message, 3,000-run fixture passes cold-open and delayed-paging checks on both screen sizes, still opening 20 messages and loading one 50-message page. - Final matched production timings use baseline `aa58fa1073` (`index-BaRiMbxd.js`) and candidate UI source `f9a26b9783` (`index-DPWTbsFF.js`, identical application source at final head `bf71ffd5af`). Chromium 151.0.7922.34, 1440×900, 4× CPU throttle, no added network latency, browser HTTP cache disabled, fresh application cache for each cold visit. Both variants block service workers and use the same warm local API server and immutable 600-message/300-run fixture. Only document HTML is intercepted for both variants; API requests are real. The common API revision is `109981f8c1`; subsequent commits change only UI and tests. | Usable conversation | Baseline median (range) | Candidate median (range) | | --- | --- | --- | | Cold direct URL | 6.57 s (5.69–7.45) | 3.07 s (2.50–3.28) | | Warm in-app return | 3.76 s (3.54–4.76) | 0.67 s (0.58–1.46) | | Back return | 2.53 s (2.12–4.20) | 0.51 s (0.47–1.18) | Five pairs alternate order. Every paired difference favors the candidate for all three journeys. Readiness requires a revealed, fully visible latest reply above the composer and an editable composer. Return timing starts after the Tasks route renders. Cold API requests fall from 953–954 to 71; API wire bytes fall from 517–559 KB to about 49 KB. Separate CPU profiles and request waterfalls confirm the removal of lifetime event hydration and are excluded from the five timing pairs. Both variants have the same expected missing optional plan document (404) and no browser exceptions. Control recent-window API reads have medians of 37 ms / 32 ms, with shared-host outliers up to 376 ms. The 6,000-message recent-window SQL uses `issue_comments_company_issue_created_at_idx` (22 index rows read for a 21-row probe). Geometry assertions retain a 2-pixel tolerance for the reading anchor and first-reveal layout. These are local synthetic measurements, not deployed staging latency. Earlier timing probes are excluded because they did not isolate service workers or composer clearance. Final head `bf71ffd5afb5684ba9105a3127f617e7adf5139c` has 55 successful checks, three optional skips and one neutral result, with no failures or pending checks. Greptile is 5/5 with no open review findings. ### Failure record Early local attempts exposed an unconditional scroller wrapper that changed the old task layout, and automatic retries on chat page failures. Both were corrected. The original task scroller structure stays in place. Metadata request assertions wait for initial connection recovery to settle, then verify only the new page’s reads; retry/resume/reconnect revalidation remains intentional. The initial review caught a send-before-scroll cache defect; its controller regression failed before the fix. Later rapid-paging checks caught scroll readiness being gated by metadata after the first reveal; readiness now stays enabled once revealed. Live replies use the separate acknowledged-message cache, then catch up from the server cursor. Visual review exposed a pagination wrapper bypassing existing composer clearance. The body is again a direct scroller child; cold-open browser checks require the full latest reply above the composer. A resize-observer regression failed before the fix and now passes. Controlled delayed inline images prove both pinned following and a stable reading anchor on desktop/mobile. The first performance fixture lacked valid native event envelopes and caused missing-log fallbacks. It is excluded from latency claims. The final fixture uses saved native assistant events and conversation session generations. The live test uses a temporary fixture-agent key, attributes the reply to an existing synthetic run, and revokes the key. It starts no model or agent process. Local database attempts failed during a Docker shutdown. The retained disposable database was restored and its suite passed. Early fixture errors included a missing conversation identity field and session generation. Mobile test setup also selected an offscreen sidebar link and reused queued human input. Optional announcements could intercept input; the fixture now dismisses them before the journeys. The scroll observer now waits for the delivered wheel event and settled animation frames, including when the viewport is already at the top. A concurrently running live test briefly changed another probe’s row count; the final acceptance and timing runs were sequential on separate fixtures. The final rig uses the visible mobile navigation and a saved agent reply. Anchor observation waits for the user's scroll to settle before measuring the effect of live updates. The full local `pnpm test:run` attempt hit repeated embedded PostgreSQL initialization failures and failures in untouched native-session executor suites; it was stopped after the repeated environment failures. The targeted real-PostgreSQL suite passed, and final-head CI is required before handoff. The first CI run also caught an exact mock expectation missing the added company scope; the expectation is updated and its 179-test suite passes. The final-head first CI attempt also stalled an assigned child task in the existing plan-approval scenario, then hit a heartbeat-run row lock timeout during fixture cleanup. The failed shard and aggregate check passed on an unchanged rerun of the same commit. Scenario assertions and timeouts were unchanged. The failure and rerun are retained in [CI run 41116120430](https://github.com/paperclipai/paperclip/actions/runs/41116120430). ## Risks - Historical transcript diagnostics no longer load on a cold chat open. Saved messages and conversation events remain available; diagnostic run views keep their full records. - Cursor paging must not omit comments with equal timestamps. Database tests cover timestamp/UUID ordering and the complete set. - Prepended or late content can move the reader. Browser checks cover retained row identity, viewport offsets, mounted drafts, and Back. Previously loaded pages stay in the query cache for its existing lifetime. - Local synthetic evidence does not establish deployed staging latency. This PR does not merge or deploy the change. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, tool use, and code execution. The exact backend deployment ID and context window were not exposed in 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 (affected checks; limits are recorded above) - [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>
9.5 KiB
Agent conversations and project handoff — agent access
Product map: Agent conversations and project handoff.
Feature ID: agent-chat.
Review date: 2026-10-12. Source commit: f981fa3cc10cb8663a87dec60345fbff46d54d0a.
This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. No live agent execution is claimed. Follow the map contract for format, permission checks, evidence and maintenance.
discovery
Capability ID: agent-chat/discovery.
Review: baseline.
API: present — representative operation IDs:
GET /api/companies/{companyId}/chats.GET /api/companies/{companyId}/chats/{agentRef}.
Agent access: restricted — Board-user REST; the responding agent gets its assigned
conversation context.
Policy: Conversation discovery/creation requires a board user and the Agent Chat gate; task access follows task visibility.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Agents cannot enumerate or create another person's standing chats. Detail route is missing from the generated API catalog.
history
Capability ID: agent-chat/history.
Review: baseline.
API: present — representative operation IDs:
GET /api/issues/{id}/recent-comments(20 contiguous comments for a standing chat).GET /api/issues/{id}/comments(cursor pages for older history).GET /api/issues/{id}/runs?runIds=...(at most 100 requested IDs, constrained to the accessible issue and company).POST /api/issues/{id}/comments.GET /api/issues/{id}/decision-receipts(own standing-chat board read).GET /api/issues/{id}/chat-handoffs(own standing-chat board read, paginated).
Agent access: partial — Assigned conversation task tools / REST for eligible task
history and replies.
Policy: Conversation discovery/creation requires a board user and the Agent Chat gate; task access follows task visibility.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Agent responses are supported; creating the person's chat and impersonating their messages are different actions.
Coordinator model/effort selection reuses PATCH /api/issues/{id} for the conversation's assigneeAdapterOverrides, followed by the existing idempotent board-user comments endpoint. It introduces no new route or actor authority and never changes the agent configuration. Settings and message admission are separate writes: a settings failure prevents submission; a later message failure may leave the selected conversation settings saved. Existing in-flight execution is not retroactively changed. UI tests cover ordering and first-message identity; provider/session behavior remains a separate live check.
Coordinator evidence: canonical chat projections return stable references to recorded task/decision rows, not copied agent prose. The caller must own and currently read the source conversation; source agent and session generation must still match the handoff, and each target task must remain readable. The projection does not give the coordinator new execution authority or wake it merely to repeat a human decision. The normal local-implicit/admin access exception remains unchanged.
GET /api/issues/{id}/pending-questions is a board-owned, read-authorized projection of canonical attention, limited to current chat handoffs plus ordinary tasks created by the caller and currently assigned to that chat’s agent. Direct tasks with any existing chat handoff are excluded from the direct-task branch. The same direct-task scope extends recorded-decision reads from the current chat boundary; pending direct-task questions remain actionable across resets. Question audience, dismissal, archive, snooze and task privacy come from the existing attention service. No copied interactions or new write authority are introduced. The read currently obtains one full authorized company attention snapshot when relevant tasks exist; no polling is added.
handoff
Capability ID: agent-chat/handoff.
Review: baseline.
API: present — representative operation IDs:
POST /api/companies/{companyId}/projects.POST /api/companies/{companyId}/issues.POST /api/issues/{id}/interactionswithsuggest_tasks.POST /api/issues/{id}/interactions/{interactionId}/accept.
Agent access: available — Native list_projects/create_project/create_task; project MCP
tools; REST.
Policy: Conversation discovery/creation requires a board user and the Agent Chat gate; task access follows task visibility.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Agent handoff is implemented; execution readiness, assignment permission, and repository access still apply.
Coordinator evidence: interaction service accepts authorized chat proposals through the normal issue creation service, with atomic initial-plan persistence and a durable originating-chat handoff. New chat handoffs default to the conversation agent when no agent or person is supplied. The effective default is included in assignment authorization before creation; explicit assignments retain company, invokability and access checks. Raw REST derives the default only from a verified same-company, same-agent run-bound conversation. Native/MCP creation and accepted suggestions follow the same owner policy. Suggestions alone have no task-creation effect. Accepted chat roots are standalone tasks; nested execution tasks retain normal parent/child rules. Source participant, session generation, task assignment and private-source inheritance are checked; quality confirmations remain separate from task completion and publication. Focused regression coverage does not claim live model/tool selection or external delivery verification. Additional coverage: the explicit chat feature evals exercise native task creation and completion delivery through the real chat UI. The chat directive tells agents to use company-prefixed relative task links or platform-supplied absolute origins. This adds no permission and does not qualify the whole capability or its denied cases.
conference-room
Capability ID: agent-chat/conference-room.
Review: baseline.
API: present — representative operation IDs:
POST /api/board/chat/stream.
Agent access: partial — Existing SSE client in local_trusted mode with the
experimental gate.
Policy: Conversation discovery/creation requires a board user and the Agent Chat gate; task access follows task visibility.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Not callable through generic REST tooling: protocol and deployment constraints apply. This route is not guarded by assertBoard, so its intended agent policy needs clarification.
Required quality-review handoff
request_human_input suggestions and native create_task accept the same optional requiredQualityReview contract; task creation persists it atomically. Execution uses existing confirmation/item-verdict interactions with explicit quality-review keys and exact document/attachment targets. The server stamps the current requirement fingerprint, forces human-only resolution, validates current targets, and independently prevents completion until every required output has human approval. Agents cannot remove or weaken an existing requirement. Existing task read/write company and actor checks remain authoritative. Publication/delivery authority is unchanged. Completion-only chat wakes receive bounded canonical decision references and guidance to reuse reviews, not start duplicate ones.
An attachment target is an exact immutable identity, not a mutable latest-output label. Registering another attachment does not automatically replace that required slot; the agent must request a fresh bound review for the replacement. Deduplicated task creation rejects a mismatched requested review contract, and an already-completed task must reopen before taking an unsatisfied requirement.