aevgarik/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'public-gh/master'

Browse Source 
* public-gh/master:
  Drop pnpm lockfile from PR
  Update ui/src/components/OnboardingWizard.tsx
  Update ui/src/components/OnboardingWizard.tsx
  Fix onboarding manual debug JSX
  Improve onboarding defaults and issue goal fallback
  Simplify adapter environment check: animate pass, show debug only on fail
  Show Claude Code and Codex as recommended, collapse other adapter types
  Animate onboarding layout when switching between Company and Agent steps
  Make onboarding wizard steps clickable tabs for easier dev navigation
  Add agent chat architecture plan
  Style tweaks for onboarding wizard step 1
  Add direct onboarding routes
This commit is contained in:
Dotta
2026-03-12 09:24:57 -05:00
parent 1d5e5247e8 55c145bff2
commit 890ff39bdb
10 changed files with 870 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files

329
doc/plans/agent-chat-ui-and-issue-backed-conversations.md Normal file
View File

@@ -0,0 +1,329 @@
# Agent Chat UI and Issue-Backed Conversations
## Context
`PAP-475` asks two related questions:
1. What UI kit should Paperclip use if we add a chat surface with an agent?
2. How should chat fit the product without breaking the current issue-centric model?
This is not only a component-library decision. In Paperclip today:
- V1 explicitly says communication is `tasks + comments only`, with no separate chat system.
- Issues already carry assignment, audit trail, billing code, project linkage, goal linkage, and active run linkage.
- Live run streaming already exists on issue detail pages.
- Agent sessions already persist by `taskKey`, and today `taskKey` falls back to `issueId`.
- The OpenClaw gateway adapter already supports an issue-scoped session key strategy.
That means the cheapest useful path is not "add a second messaging product inside Paperclip." It is "add a better conversational UI on top of issue and run primitives we already have."
## Current Constraints From the Codebase
### Durable work object
The durable object in Paperclip is the issue, not a chat thread.
- `IssueDetail` already combines comments, linked runs, live runs, and activity into one timeline.
- `CommentThread` already renders markdown comments and supports reply/reassignment flows.
- `LiveRunWidget` already renders streaming assistant/tool/system output for active runs.
### Session behavior
Session continuity is already task-shaped.
- `heartbeat.ts` derives `taskKey` from `taskKey`, then `taskId`, then `issueId`.
- `agent_task_sessions` stores session state per company + agent + adapter + task key.
- OpenClaw gateway supports `sessionKeyStrategy=issue|fixed|run`, and `issue` already matches the Paperclip mental model well.
That means "chat with the CEO about this issue" naturally maps to one durable session per issue today without inventing a second session system.
### Billing behavior
Billing is already issue-aware.
- `cost_events` can attach to `issueId`, `projectId`, `goalId`, and `billingCode`.
- heartbeat context already propagates issue linkage into runs and cost rollups.
If chat leaves the issue model, Paperclip would need a second billing story. That is avoidable.
## UI Kit Recommendation
## Recommendation: `assistant-ui`
Use `assistant-ui` as the chat presentation layer.
Why it fits Paperclip:
- It is a real chat UI kit, not just a hook.
- It is composable and aligned with shadcn-style primitives, which matches the current UI stack well.
- It explicitly supports custom backends, which matters because Paperclip talks to agents through issue comments, heartbeats, and run streams rather than direct provider calls.
- It gives us polished chat affordances quickly: message list, composer, streaming text, attachments, thread affordances, and markdown-oriented rendering.
Why not make "the Vercel one" the primary choice:
- Vercel AI SDK is stronger today than the older "just `useChat` over `/api/chat`" framing. Its transport layer is flexible and can support custom protocols.
- But AI SDK is still better understood here as a transport/runtime protocol layer than as the best end-user chat surface for Paperclip.
- Paperclip does not need Vercel to own message state, persistence, or the backend contract. Paperclip already has its own issue, run, and session model.
So the clean split is:
- `assistant-ui` for UI primitives
- Paperclip-owned runtime/store for state, persistence, and transport
- optional AI SDK usage later only if we want its stream protocol or client transport abstraction
## Product Options
### Option A: Separate chat object
Create a new top-level chat/thread model unrelated to issues.
Pros:
- clean mental model if users want freeform conversation
- easy to hide from issue boards
Cons:
- breaks the current V1 product decision that communication is issue-centric
- needs new persistence, billing, session, permissions, activity, and wakeup rules
- creates a second "why does this exist?" object beside issues
- makes "pick up an old chat" a separate retrieval problem
Verdict: not recommended for V1.
### Option B: Every chat is an issue
Treat chat as a UI mode over an issue. The issue remains the durable record.
Pros:
- matches current product spec
- billing, runs, comments, approvals, and activity already work
- sessions already resume on issue identity
- works with all adapters, including OpenClaw, without new agent auth or a second API surface
Cons:
- some chats are not really "tasks" in a board sense
- onboarding and review conversations may clutter normal issue lists
Verdict: best V1 foundation.
### Option C: Hybrid with hidden conversation issues
Back every conversation with an issue, but allow a conversation-flavored issue mode that is hidden from default execution boards unless promoted.
Pros:
- preserves the issue-centric backend
- gives onboarding/review chat a cleaner UX
- preserves billing and session continuity
Cons:
- requires extra UI rules and possibly a small schema or filtering addition
- can become a disguised second system if not kept narrow
Verdict: likely the right product shape after a basic issue-backed MVP.
## Recommended Product Model
### Phase 1 product decision
For the first implementation, chat should be issue-backed.
More specifically:
- the board opens a chat surface for an issue
- sending a message is a comment mutation on that issue
- the assigned agent is woken through the existing issue-comment flow
- streaming output comes from the existing live run stream for that issue
- durable assistant output remains comments and run history, not an extra transcript store
This keeps Paperclip honest about what it is:
- the control plane stays issue-centric
- chat is a better way to interact with issue work, not a new collaboration product
### Onboarding and CEO conversations
For onboarding, weekly reviews, and "chat with the CEO", use a conversation issue rather than a global chat tab.
Suggested shape:
- create a board-initiated issue assigned to the CEO
- mark it as conversation-flavored in UI treatment
- optionally hide it from normal issue boards by default later
- keep all cost/run/session linkage on that issue
This solves several concerns at once:
- no separate API key or direct provider wiring is needed
- the same CEO adapter is used
- old conversations are recovered through normal issue history
- the CEO can still create or update real child issues from the conversation
## Session Model
### V1
Use one durable conversation session per issue.
That already matches current behavior:
- adapter task sessions persist against `taskKey`
- `taskKey` already falls back to `issueId`
- OpenClaw already supports an issue-scoped session key
This means "resume the CEO conversation later" works by reopening the same issue and waking the same agent on the same issue.
### What not to add yet
Do not add multi-thread-per-issue chat in the first pass.
If Paperclip later needs several parallel threads on one issue, then add an explicit conversation identity and derive:
- `taskKey = issue:<issueId>:conversation:<conversationId>`
- OpenClaw `sessionKey = paperclip:conversation:<conversationId>`
Until that requirement becomes real, one issue == one durable conversation is the simpler and better rule.
## Billing Model
Chat should not invent a separate billing pipeline.
All chat cost should continue to roll up through the issue:
- `cost_events.issueId`
- project and goal rollups through existing relationships
- issue `billingCode` when present
If a conversation is important enough to exist, it is important enough to have a durable issue-backed audit and cost trail.
This is another reason ephemeral freeform chat should not be the default.
## UI Architecture
### Recommended stack
1. Keep Paperclip as the source of truth for message history and run state.
2. Add `assistant-ui` as the rendering/composer layer.
3. Build a Paperclip runtime adapter that maps:
- issue comments -> user/assistant messages
- live run deltas -> streaming assistant messages
- issue attachments -> chat attachments
4. Keep current markdown rendering and code-block support where possible.
### Interaction flow
1. Board opens issue detail in "Chat" mode.
2. Existing comment history is mapped into chat messages.
3. When the board sends a message:
- `POST /api/issues/{id}/comments`
- optionally interrupt the active run if the UX wants "send and replace current response"
4. Existing issue comment wakeup logic wakes the assignee.
5. Existing `/issues/{id}/live-runs` and `/issues/{id}/active-run` data feeds drive streaming.
6. When the run completes, durable state remains in comments/runs/activity as it does now.
### Why this fits the current code
Paperclip already has most of the backend pieces:
- issue comments
- run timeline
- run log and event streaming
- markdown rendering
- attachment support
- assignee wakeups on comments
The missing piece is mostly the presentation and the mapping layer, not a new backend domain.
## Agent Scope
Do not launch this as "chat with every agent."
Start narrower:
- onboarding chat with CEO
- workflow/review chat with CEO
- maybe selected exec roles later
Reasons:
- it keeps the feature from becoming a second inbox/chat product
- it limits permission and UX questions early
- it matches the stated product demand
If direct chat with other agents becomes useful later, the same issue-backed pattern can expand cleanly.
## Recommended Delivery Phases
### Phase 1: Chat UI on existing issues
- add a chat presentation mode to issue detail
- use `assistant-ui`
- map comments + live runs into the chat surface
- no schema change
- no new API surface
This is the highest-leverage step because it tests whether the UX is actually useful before product model expansion.
### Phase 2: Conversation-flavored issues for CEO chat
- add a lightweight conversation classification
- support creation of CEO conversation issues from onboarding and workflow entry points
- optionally hide these from normal backlog/board views by default
The smallest implementation could be a label or issue metadata flag. If it becomes important enough, then promote it to a first-class issue subtype later.
### Phase 3: Promotion and thread splitting only if needed
Only if we later see a real need:
- allow promoting a conversation to a formal task issue
- allow several threads per issue with explicit conversation identity
This should be demand-driven, not designed up front.
## Clear Recommendation
If the question is "what should we use?", the answer is:
- use `assistant-ui` for the chat UI
- do not treat raw Vercel AI SDK UI hooks as the main product answer
- keep chat issue-backed in V1
- use the current issue comment + run + session + billing model rather than inventing a parallel chat subsystem
If the question is "how should we think about chat in Paperclip?", the answer is:
- chat is a mode of interacting with issue-backed agent work
- not a separate product silo
- not an excuse to stop tracing work, cost, and session history back to the issue
## Implementation Notes
### Immediate implementation target
The most defensible first build is:
- add a chat tab or chat-focused layout on issue detail
- back it with the currently assigned agent on that issue
- use `assistant-ui` primitives over existing comments and live run events
### Defer these until proven necessary
- standalone global chat objects
- multi-thread chat inside one issue
- chat with every agent in the org
- a second persistence layer for message history
- separate cost tracking for chats
## References
- V1 communication model: `doc/SPEC-implementation.md`
- Current issue/comment/run UI: `ui/src/pages/IssueDetail.tsx`, `ui/src/components/CommentThread.tsx`, `ui/src/components/LiveRunWidget.tsx`
- Session persistence and task key derivation: `server/src/services/heartbeat.ts`, `packages/db/src/schema/agent_task_sessions.ts`
- OpenClaw session routing: `packages/adapters/openclaw-gateway/README.md`
- assistant-ui docs: <https://www.assistant-ui.com/docs>
- assistant-ui repo: <https://github.com/assistant-ui/assistant-ui>
- AI SDK transport docs: <https://ai-sdk.dev/docs/ai-sdk-ui/transport>