f2593b7905
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - People enter that work through the workspace, agent conversations, and tasks. > - Coordinator and Agent Chat still require experimental enrollment. > - Task link prefetches do not warm the compact queries used by the default task view. Chat also waits for a request when its navigation list already holds the conversation. > - This pull request makes Coordinator and Agent Chat standard and reuses the reads needed for navigation. > - People can choose Classic workspace in Experimental settings. Cached work can appear while fresh data loads. ## Linked Issues or Issue Description **What existing behavior does this improve?** Workspace selection, Agent Chat availability, and navigation between Chat, Tasks, and task details. **Subsystem affected** Cross-cutting: UI, workspace preferences, instance settings, and the database migration. **Current behavior** People must enable Coordinator and Agent Chat in Experimental settings. Opening a task can repeat requests because prefetch warms the full detail and comment queries, while the default view reads compact task data and a recent comment window. Opening Chat waits for a detail request even when the current person's conversation list contains it. **Proposed behavior** Coordinator is the standard workspace for everyone. Experimental settings offer Classic workspace, off by default. Old Coordinator experiment values do not select Classic. Agent Chat is available to everyone, including instances with an old saved or managed off value. Task link intent warms the queries used by the mounted view. Chat can use the current person's company-scoped conversation list during refresh. **Reason and benefit** People can use the standard workspace without setup. Repeat navigation can show cached content while the server refreshes it. **Breaking changes** Existing Coordinator experiment and Agent Chat off values no longer disable these surfaces. Classic requires an explicit new opt-in. The workspace API keeps its existing response shape and audit checks. The migration retains legacy values and adds a separate Classic preference. Execution permissions, company access, and chat privacy checks still apply. **Additional context** Roadmap check: this graduates existing surfaces and improves their navigation. It does not add a new agent execution capability. Duplicate searches found no open Coordinator workspace PR. Related server cache work, Refs: #17828, addresses compact issue-list invalidation; this PR addresses client navigation queries. ## What Changed - Add a default-off Classic workspace preference. Derive the existing workspace API response from that choice. Keep personal persistence, account isolation, and audited writes in the workspace preference service. - Replace the Coordinator experiment control with Classic workspace. Use Coordinator while preferences load. Update the existing settings examples and navigation recipe. - Retire the Agent Chat experiment control. Ignore old stored and managed off values. Retain the compatibility key and the existing execution and access checks. - Reuse account- and company-scoped chat list data with its original freshness timestamp. - Share compact task and recent-comment query options between prefetch and the task view. Keep full-history prefetch for Classic tasks and expanded history. - Add upgrade, replay, cache, account isolation, and browser switching regressions. Update product, database, development, and roadmap documentation. ## Verification - Targeted preference, settings, migration, cache, and UI regression tests passed during implementation. The cache tests hold refresh requests pending and check that content still renders. They also check account isolation and stale refresh behavior. - A real browser test verified fresh Coordinator defaults, Classic opt-in persistence, and return to Coordinator. It used an isolated source checkout with fresh data on macOS. - Token, migration numbering and safety, map, and Storybook catalog checks pass after the rebase. - Repository typecheck and build pass. Typecheck and token gates also pass after review repairs. The broad local run passed all six chat integration shards (1,931 tests). It then found the host-CLI-dependent recovery fixture described below. Its remaining duplicate work was stopped after the full current-head CI matrix passed; this is not a claim that the broad local command completed green. - Review repairs passed 419 UI/migration fixture tests, 19 Coordinator navigation tests, and all 214 tests in the five affected server suites. The 24 Chat/workspace browser tests pass, including standard Coordinator switching and explicit Classic persistence. - The broader browser repair run passed 85 tests. It retained two failed assertions and skipped five later serial cases. The affected files then passed all 11 tests after the fixes: reopen the desktop panel after reload and open More for Audit and Connectors. This includes the five serial cases that had not run. - The broad local suite exposed a recovery fixture that executed the host Codex CLI during a simulated remote probe. On a host with Codex 0.154.0, model fallback broke its fixed-model assertion. The fake sandbox now reports Codex 0.160.0. All 20 selected recovery/provider compatibility cases pass after the repair. - A CLI company import/export suite timed out during server startup in the second CI run. The port fallback is intentional in that fixture. No root cause was established. That suite passes on the final commit in CI. This records recovery, not a claimed product fix for the earlier timeout. - The first CI run exposed remaining assumptions about the retired flags and Classic UI. The repair commit updates those fixtures and navigation steps. It also restores the missing enabled Cases destination in Coordinator. Earlier local recovery attempts used the wrong fixture notification and advanced fake time during live execution; the corrected tests use the subscribed recovery queue and wall time during execution. - Greptile reviewed commit `98972b030d4505d838427a2fca6b196b8cad6d47` at **5/5** with no new comments. The original finding is resolved. - Current-head CI is green: **56 successful checks**, with three checks skipped by workflow filters. This includes typecheck, build, the complete Vitest matrix, all eight browser shards, Runner verification, release checks, and security checks. [Final CI run](https://github.com/paperclipai/paperclip/actions/runs/42132651414). - Typecheck caught missing `pid` and `startedAt` fields in the simulated command result. The fixture now returns the complete process contract, and the server test-layer typecheck passes. - Storybook catalog alignment was checked. Storybook play tests were not run. Hosted latency and cold bundle loading were not measured. ## Risks - The new default changes the workspace for people who previously left the Coordinator experiment off. They can opt into Classic in Experimental settings. - The additive migration must run before the new server code. It is safe to replay and preserves explicit Classic choices. - Cached content can be stale during background refresh. Existing query invalidation and source timestamps still control freshness. - These changes reduce avoidable loading waits. They do not establish a measured improvement in hosted request latency or initial bundle download time. ## Model Used OpenAI Codex, based on GPT-6, with reasoning, repository tools, code execution, and browser automation. The exact serving revision and context-window size are 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 - [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: Scott Tong <[email protected]> Co-authored-by: Paperclip <[email protected]>
11 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; 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
Proactive publication: native send_chat_message and
POST /api/agents/me/chat/messages accept only Markdown body and idempotency key.
The server derives company, sender and responsible human from the authenticated
run and atomically resolves the same per-agent/human conversation. This operation
is available independently of generic API tools, only to active standard task
runs with standard credentials. Skill-test and task-bridge credentials, persisted
skill-test runs, Ask/planning/review/watchdog, stale/stopped runs, revoked recipients and
restricted source tasks are denied. The shared comment boundary rejects other
agents and execution-task writes that bypass this path. Comment/audit persistence
retains real agent/run attribution and server-owned source provenance.
Credential scope, responsible human and external authorizer remain part of access
checks. API keys are rechecked under a row lock before the delivery commits.
New deliveries spend the existing shared per-run cross-issue influence budget;
receipt retries and recovery spend no extra slot. Exhaustion returns the standard 429
denial and rolls back the attempted delivery, including first-chat creation.
GET /api/companies/{companyId}/chats and its detail endpoint include the current
human's unread state. POST /api/issues/{id}/read accepts an optional
throughCommentId for the owning human's conversation. Concurrent unseen arrivals
remain unread. Source: delivery owner,
database tests, and
browser journey. Test definitions
are not evidence that a live provider or whole capability has been qualified.
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; 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; 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; 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.