Operator Chat Rail
Shared chat plus traceable assistant rail for high-context workflows.
Install
One-line install
npx attrition-sh pack install operator-chat-rail
AGENTS.md snippet (Claude Code / Cursor)
# Operator Chat Rail # See: /packs/operator-chat-rail
Raw Markdown
Machine-readable body for agent ingestion or copy/paste.
Telemetry
Not yet measuredSummary
A proven interface pattern for apps that need collaborative chat in the center and a persistent agent rail for plan trace, tool execution, telemetry, sources, and quality checks.
Fit and expected payoff
When this pack earns its extra structure, when to skip it, and what it should improve.
Use when
Situations where this pack earns its extra structure.
- Users need to collaborate in a shared thread without losing assistant observability.
- You need durable streaming, not just a final answer blob.
- Operators must inspect plan steps, tool calls, sources, and quality checks after the run.
Avoid when
Keeps the pack from becoming a default hammer.
- The task is a single-user consumer chat with no need for traceability.
- The product does not require source auditability or operator cross-reference behavior.
What it improves
Expected outcomes if implemented well.
- The assistant becomes reviewable instead of magical.
- Streaming deltas map directly to visible plan and execution events.
- The same UI contract works across shared chat, workspace pages, and evaluation playback.
Minimal instructions
Smallest useful starting point.
Build the UI around two persistent surfaces: - centered shared thread for human conversation - expandable right rail for assistant trace The rail must show: - plan summary - planned and executed steps - tool call summaries - sources and clickable references - telemetry and quality checks Do not collapse all of this into one final markdown blob.
Full instructions
Complete natural-language instruction set.
You are building an operator-facing agent interface. Primary UX contract: 1. Keep the human conversation in the center of the screen. 2. Keep the assistant state in a dedicated right rail. 3. Stream state changes as durable events, not ephemeral UI-only spinners. The assistant rail should reveal: - what the assistant planned to do - what it actually executed - which tools were called and with what purpose - what sources were used - what quality or policy checks passed or failed The final answer should remain readable by itself, but the rail must preserve enough structure for an operator to verify the answer after the fact.
Evaluation checklist
These checks should pass before you consider the pattern production-ready.
- Does the answer remain readable without opening the trace?
- Can an operator inspect the exact plan and executed steps?
- Are citations or references visible and clickable when sources exist?
- Does the rail degrade gracefully when the run is deterministic or source-free?
Common failure modes
Every check below traces back to a specific production failure. Read as: "I would think about X because in production Y can happen."
- Mid
All trace data is dumped as raw JSON instead of operator-readable cards.
- Trigger
- (legacy — trigger not separated)
- Prevention
- (legacy — no explicit prevention)
- Mid
The chat waits for a final answer instead of streaming plan and execution deltas.
- Trigger
- (legacy — trigger not separated)
- Prevention
- (legacy — no explicit prevention)
- Mid
Sources exist in metadata but are not visible to the operator.
- Trigger
- (legacy — trigger not separated)
- Prevention
- (legacy — no explicit prevention)
Official docs and implementation references
Convex AI platform overview
Explains Convex AI building blocks such as AI Agent and Persistent Text Streaming.
https://www.convex.dev/aiPersistent Text Streaming component
Reference implementation for durable text streaming.
https://github.com/get-convex/persistent-text-streamingFloorAI case study repo
Proof that the centered thread + agent rail pattern works in a full application.
https://github.com/HomenShum/floorai