PaperClipAI/maps/feature-map/agent-chat.md

navigation

navigation
section sectionOrder order Tasks and conversations 20 40

Agent conversations and project handoff

A person can hold a persistent conversation with an agent, return to its history, and hand useful work into a project or task. The gated conference-room chat is a separate conversation surface.

Feature ID: agent-chat.

Implementation: agent chat, chat landing, conference room.

Agent access: companion.

Sub-features

• discovery: agent-chat/discovery — find an agent and reopen an accessible recent conversation.
• history: agent-chat/history — send messages, inspect replies/files, and return to the same conversation.
• handoff: agent-chat/handoff — create or identify a project/task from chat and follow the resulting work.
• conference-room: agent-chat/conference-room — use the separately gated board chat without assuming parity with agent chat.

How to get to it (user POV)

agent-conversation

Task and routine results can arrive proactively in the agent's standing chat. Each message has a source-task link; the agent row and Chat navigation indicate unread messages, including first delivery before any human chat. Foreground messages at the bottom of the chat are marked read with a comment cutoff. The existing ordering and per-human/company isolation remain in effect.

Open /chats, choose an agent, or use /chats/:agentRef and its conversation sidebar.

With Coordinator enabled, the composer exposes the shared model/thinking-level picker for supported agents. The agent stays fixed in this control; switching agents remains in the chat header. Choices save as conversation overrides on send, preserving the agent's configuration. A first message creates the conversation before saving settings and submitting through the ordered comments endpoint.

Standing chats open with the latest 20 contiguous messages. Scroll upward to fetch earlier messages, answer receipts, and created tasks. The loading indicator stays in the thread; history failures offer an inline Retry while preserving the draft and reading position. Opening a chat does not fetch its lifetime comment, activity, or run history. Already observed messages survive live refresh and Back within the query-cache session.

Click an agent's name or avatar above a message or active turn to open that agent's overview in the current company. The identity keeps its existing appearance, with no underline on hover. Identities without an agent ID remain plain text.

Coordinator answer receipts from this conversation jump to the answer bubble without leaving chat. Answer updates from an execution task link to that source task and its decision context. Compact document links read “Open [document title] in the sidebar”.

project-handoff

Ask for project work in Agent Chat and follow its created project/task links. New tasks and accepted task suggestions default to the agent in that conversation. An explicitly requested agent or person takes precedence; no best-fit agent routing is inferred. Ordinary task creation outside chat keeps its existing assignment behavior.

conference-room

Open /board-chat only when its conference-room gate is enabled.

Driving it with Playwright and the Paperclip CLI

Preconditions: follow the baseline. Enable the applicable chat feature, use a configured test agent, and distinguish model replies from a mocked conversation fixture.

agent-conversation

Local browser recipe: long-chat startup and scrolling, with fixture and command details in the performance README. It covers recent-only reveal, delayed and failed pages, Back, older comment links, and live refresh. Synthetic local data is not deployed acceptance evidence.

Automated: chat landing checks recent-chat routing; conversation service covers persisted conversation behavior.

Automated: proactive delivery exercises native/HTTP delivery, concurrency, retries, authority, privacy, active turns, resets and unread cutoffs. Read visibility checks foreground/bottom gating and unseen arrivals. The routine digest journey uses real app APIs and a deterministic process agent to verify first-chat discovery, unread state across reloads, source navigation and follow-up context. It does not qualify live PR retrieval or a model's editorial choices.

Automated: composer picker covers fixed-agent model/effort selection on desktop and mobile; composer covers Coordinator gating and settings submission without reassignment. Task detail verifies canonical first/existing-chat IDs, settings-before-comment ordering, and no comment submission when settings fail to save. These tests mock the API and do not prove provider execution with the chosen model.

Automated: conversation delivery checks that paused or otherwise non-invokable agents leave comments pending without aborting startup recovery, and that a later unpause allows one delivery. The test persists queue admissions only; it does not start agents or providers. Automated: historical chat keeps an older conversation reachable after a cached roster refresh ends in HTTP 429. It checks lookup Retry and preserves permission and company boundaries. This is component evidence with real query state, not live provider proof.

Automated: thread and composer keeps an in-flight attachment through first-chat creation on desktop and mobile, while initial history for an existing conversation stays deferred. The first-upload browser journey checks the visible file chip, server attachment, no premature agent run, and attachment count after send and reload. That journey uses a simulated agent.

Manual: In a conversation with no messages, attach a file before the first send. Confirm the same file stays in the composer after the chat is created. Send it once, reload, and confirm the file and message remain.

Manual: Start a conversation, send a recognizable request, and inspect its reply. Click the responding agent's name, return with Back, then click its avatar; both should open that agent's overview without changing companies. Check that the identity looks unchanged at rest and on hover on desktop and mobile. Navigate away and reopen the same history. Use /new for a fresh session within the same standing conversation. Test an unavailable historical agent and an inaccessible saved conversation; verify no cross-user or cross-company history appears.

project-handoff

Automated: chat project tools checks tool contracts; live model choice and UI handoff require a manual run.

Automated: Coordinator handoffs checks that a suggested task remains a proposal until acceptance, that its task, initial plan and source-chat audience are saved atomically, and that retries do not create another task. A conversation is a privacy/provenance source rather than a structural task parent. The same tests cover compact canonical decision receipts, exact uploaded-artifact bindings, current task access, reset-session boundaries, and pagination of older handoffs. Explicit live evals: chat feature journeys send natural requests to save a backlog task or delegate an announcement. They check project/assignee, execution or non-execution, saved output, return to chat, and click the actual same-instance task link after reload. Registration alone does not establish a pass. Production chat guidance uses company-prefixed relative task links unless the platform supplied a verified absolute origin.

Manual: Ask the configured agent to create bounded project work, inspect the proposed/created target, and open the resulting task. Verify the request context and intended project survived and the task produces a useful output.

Manual: With the personal Coordinator workspace enabled, discuss a vague request until the agent suggests a task. Confirm that no execution task exists before acceptance. Accept it, stay in chat, and open the created card on demand. An explicit request to create a task may create it directly under normal authority. Approve a work product or answer a question in its task or Needs You, then return to the originating chat. Its compact update should link to the exact recorded decision and reviewed artifact, without needing another coordinator turn. Approval of artifact quality alone must not publish it or complete the task.

Coordinator task clarification: create a task with only a description. When material context is missing, native task guidance asks one focused canonical question inside that task. Its actionable form is also projected into Needs You and the originating standing chat; direct user-created tasks appear in the assigned agent’s standing chat. Answer on either surface and verify the pending card/count clear and a compact recorded answer replaces it in chat. This projection is event-refreshed and does not wake another agent merely to repeat the question. Current direct-task questions survive a chat reset; their answered receipts start at the current chat boundary. The task brief remains editable context, not another stored question. Model choice and actual resumed execution still require live verification.

conference-room

Automated: board chat gate proves route gating, not a live conversation.

Preconditions for this entry point: local_trusted mode and an installed, authenticated claude CLI, in addition to the Conference Room flag. These are separate from Agent Chat's configured-agent prerequisites.

Manual: Check disabled access first, enable in the disposable instance, then send and reload a conversation. Inspect the actual responding agent and persisted history; report this result separately from Agent Chat.

Gotchas

• Coordinator Markdown references to a standing agent conversation display “Chat with [agent]” and route to that chat, preserving anchors. Labels resolve once from the existing current-person/current-company chat list and agent roster; no task status glyph or task quicklook is shown for these references. Ordinary task links retain their existing treatment.

• Idle chat is not failed execution.

• See steering for in-flight messages and questions for interactions.

• An API tool test does not prove that every harness will choose the same handoff tool.

Storybook verification

conference-room

Capability ID: agent-chat/conference-room.

Scope: ui Storybook: Conference-room flag disabled, empty/history/reply, busy and explicit failure states. Production: Exercise separate BoardChat route gate, local-trusted deployment and authenticated Claude CLI; send/reload real conversation with responding agent attribution. Sources: Source: BoardChat.tsx, board-chat.ts. Tests: BoardChat.test.tsx, board-chat-route-feature-flag.test.ts

Explicit output quality review (Coordinator functional slice)

Accepted suggestions and native explicit task creation may carry requiredQualityReview into the task's existing execution policy. The opt-in requirement names output slots and is separate from the existing reviewer eligibility policy. Each slot requires a canonical human verdict bound to an exact current output document revision or attachment identity. Plans, questions, file presence, model completion claims, rejected/deferred verdicts and stale versions do not satisfy it. Only a human may change an existing requirement. Quality approval does not publish or automatically complete the task. Tasks without this optional requirement retain existing completion behavior.

Owning service: server/src/services/required-quality-review.ts; enforcement: interaction creation, issue update, native completion feedback/finalization. Focused proof: server/src/__tests__/required-quality-review.test.ts plus native arbiter and chat completion delivery tests. Completion updates include bounded canonical output-decision identities for linking existing review, never worker-authored review prose. These tests do not establish unattended live provider reliability.

Attachment approval is for the exact immutable file identity. Removal or a mismatched hash invalidates that target; registering a replacement beside the approved file does not redefine its output slot. A replacement requires a fresh bound review. Document targets additionally track the current revision.