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, click the agent avatar, name, or caret in the chat header to open the agent picker. They form one button with the same keyboard focus and action.

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.

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

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: 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. 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

• 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.