Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-19 10:36:26 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
codex/plugin-task-execution
PaperClipAI/packages/paperclip-runner/docs/design/live-console-component-decisions.md
T
Dotta 560e7e48b5 feat(runner): add SDK and developer tooling (#12608) 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner package already provides the production protocol and
execution spine.
> - Contributors still need stable SDK surfaces, deterministic test
tools, and local inspection tools.
> - Those surfaces share generated contracts and must change as one
package boundary.
> - This pull request adds the package-local SDK, labs, examples, and
drift checks.
> - The benefit is a reviewable developer platform that does not change
application execution selection.

## Linked Issues or Issue Description

**Subsystem affected**

`packages/paperclip-runner` — runner SDK, conformance tools, and
developer tooling.

**Problem or motivation**

The production runner spine is present, but package consumers cannot
build deterministic integrations, inspect sessions, or verify
provider-neutral behavior through supported surfaces.

**Proposed solution**

Add browser, React, standalone, live-session, scenario, conformance, and
evaluation surfaces. Add generated contract inventories and
package-local verification scripts. Keep production application routing
unchanged.

**Alternatives considered**

We considered splitting each generated catalog, SDK surface, and demo
into separate pull requests. Those changes share exports, fixtures, and
drift gates. Splitting them would create intermediate package states
that do not build.

**Roadmap alignment**

No overlapping item appears in `ROADMAP.md`. This work extends the
runner package that is already on `master`.

## What Changed

- Add browser, React, standalone, live-session, and issue-thread SDK
surfaces.
- Add deterministic mock control-plane, scenario, conformance, replay,
and evaluation tools.
- Add bounded Codex, OpenCode, and ACPX development transports and
fixtures.
- Keep deferred managed-provider execution fail-closed. Persisted
compatibility data remains readable.
- Add generated capability inventories with their source files and drift
checks.
- Add examples, package documentation, browser checks, and
clean-consumer checks.
- Preserve the reviewed protocol bounds, replay compatibility aliases,
process environment isolation, and semantic redaction limits.
- Update the ACPX package patch that the existing workspace patch
registry already tracks.
- Do not change `pnpm-lock.yaml`, repository workflows, server runtime
selection, or the application UI.

## Verification

GitHub Actions is the verification authority for this pull request. The
repository CI, package TypeScript and Rust checks, package tests,
generated-output drift checks, browser checks, security scans, and
Greptile review must pass on the exact head.

Local test suites were not run because this series uses parallel GitHub
Actions for verification.

## Risks

This is a large greenfield package change. The main risks are public
export drift, generated-output drift, and optional React consumer
compatibility. Package boundary checks, clean-consumer checks, and
browser tests cover those risks. Production adapter selection and server
execution are outside this pull request.

## Stack

1. **This PR:** runner SDK and developer tooling.
2. [Codex production server
integration](https://github.com/paperclipai/paperclip/pull/12616).
3. [Provider-neutral task-thread
UI](https://github.com/paperclipai/paperclip/pull/12617).

## Model Used

OpenAI Codex, GPT-5, high-reasoning mode, with tool use and code
execution.

## 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 described the issue in-PR following the feature request
template
- [x] I have not referenced internal/instance-local Paperclip issues or
links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id
- [ ] 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 risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
2026-08-31 21:33:11 -05:00

144 lines
9.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Live console Component Decision Record — shadcn/ui and Vercel AI Elements
Status: **approved** (UX gate TASK-16832, 2026-08-08). Sources checked
2026-08-08 against the live shadcn/ui and AI Elements documentation; this
supersedes and extends the
[2026-08-07 compatibility note](../research/2026-08-07-ui-library-compatibility.md)
for the authorized Live console browser surface.
## 1. Ground rules (binding on the implementation)
1. **Protocol authority.** The package's canonical PRP events and
`SessionSnapshot` reducer state are the only data contract. Third-party
chat message types, AI SDK `UIMessage`/message-part types, and
component-local state machines must not become inputs to, or shadows of,
the runner protocol. Adapted components accept props typed against
`src/reducer/session-reducer.ts` / `src/contracts/*` shapes only.
2. **Source adaptation, not dependency adoption.** Components are copied into
`devtools/browser/src/components/` and rewritten in the established local
idiom: plain function components, `data-slot` attributes, semantic `ui-*`
class names, all visual values from the token layer in `src/styles.css`.
No Tailwind, no `class-variance-authority`, no `radix-ui` runtime, no
`cn()` utility chain, no AI SDK. (Precedent: `components/ui/button.tsx`
already follows this idiom from the earlier phases.)
3. **Dependency budget: zero new runtime dependencies** for the demo app
beyond the existing `react`/`react-dom`. Every candidate below that would
pull a runtime dep (radix primitives, `cmdk`, `streamdown`, `shiki`,
`use-stick-to-bottom`, `nanoid`, `zod`) is either rebuilt on native
platform primitives (`<dialog>`, `<details>`, ARIA patterns) or rejected.
Rationale: Live console is a proof under `packages/paperclip-runner/` that
SDK will freeze into an SDK — every dependency added here becomes an
SDK liability decision later.
4. **Accessibility parity or better.** Where we rebuild a radix-backed
pattern on native primitives, the keyboard/SR contract in interaction map
§10 is the acceptance bar; "the library would have done it" is not
available as an excuse once we adapt source.
5. **Token gaps are system changes.** Live console needs a few new tokens (see
§5). Add them to `src/styles.css` `:root` in one commit with this record —
never inline values in component files.
## 2. Existing package-local primitives — REUSE
| Component | Decision | Notes |
|---|---|---|
| `ui/button.tsx` | Reuse | Add `ui-button--danger` and `ui-button--ghost` class variants (CSS only) for Stop / Cancel actions. |
| `ui/badge.tsx` | Reuse | Status badges for turn/request/connection states. |
| `ui/card.tsx` | Reuse | Base for request cards, manifest rows, inspector panels. |
| `ui/textarea.tsx` | Reuse | Composer input (wrapped with auto-grow behavior). |
## 3. Vercel AI Elements — decisions per primitive
AI Elements is a shadcn-registry distribution targeting React 19 + Tailwind 4
with Next.js + AI SDK prerequisites (docs, checked 2026-08-08). The turnkey
stack does not fit this standalone Vite package (already established in the
2026-08-07 note). We adapt **shapes and interaction patterns from source**,
re-typed to reducer snapshots and restyled to tokens.
**ADAPT (5):**
| Primitive | Adapted as | What we keep | What we change |
|---|---|---|---|
| `Conversation` | `ui/conversation.tsx` | stick-to-bottom semantics, "jump to latest" affordance, `role="log"` | drop `use-stick-to-bottom` dep — implement with a scroll listener + `scrollTo`; wire unseen-count from reducer timeline length |
| `Message` | `ui/message.tsx` | role-based alignment/grouping anatomy, avatar-less compact variant | props become `SessionItemSnapshot`; roles extended with `reasoning`/`tool`/`system`; no AI SDK message parts |
| `PromptInput` | `ui/composer.tsx` | textarea + action-row anatomy, submit-on-Enter, status-driven submit button | add Send/Steer/Stop tri-state from interaction map §1–§3; no attachments, no model picker, no AI SDK `sendMessage` |
| `Reasoning` | `ui/reasoning-item.tsx` | collapsible streaming reasoning with auto-open-while-streaming, duration caption | rebuild on `<details>`/summary with ARIA disclosure; content = plain streamed text (no markdown dep) |
| `Tool` | `ui/tool-item.tsx` | collapsible tool block: header (name + status badge) / input / output sections | status enum mapped from canonical item/turn events, not AI SDK `ToolUIPart` states; payloads render in `<pre>` |
**REJECT (with reasons; revisit in SDK where noted):**
| Primitive | Reason |
|---|---|
| `Response` (streamed markdown) | pulls `streamdown`/markdown pipeline; tracer renders exact text — markdown prettification can hide protocol truth. SDK candidate for the SDK console. |
| `CodeBlock` | needs `shiki` highlighting dep; `<pre>` + mono token suffices for a tracer. SDK candidate. |
| `Actions` (retry/like/copy row) | retry/regenerate/vote have no protocol backing; copy-to-clipboard is implemented locally in the inspector. |
| `Branch` | message branching does not exist in the PRP session model. |
| `Sources` / `InlineCitation` | no citation events in the protocol. |
| `Task` | overlapping with adapted `Tool`; subagent lineage uses the tree (map §6), not a task widget. |
| `ChainOfThought` | duplicate of `Reasoning` at higher visual weight. |
| `Context` (token/cost meter) | usage belongs in the inspector Session tab as plain data; a persistent meter overweights cost in a tracer. SDK candidate. |
| `Artifact`, `WebPreview`, `Image`, `Attachments`, `OpenIn`, `Suggestion`, `Queue` | no protocol counterpart in Live console; adopting them would invent affordances the runner cannot honor (fabricated-controls rule). |
| `Loader`/`Shimmer` | trivially replaced by a token-compliant CSS pulse honoring `prefers-reduced-motion`. |
## 4. shadcn/ui — decisions per primitive
**ADAPT (6):**
| Primitive | Adapted as | Implementation note |
|---|---|---|
| `Tabs` | `ui/tabs.tsx` | inspector tabs + mobile segments; WAI-ARIA tabs pattern, roving tabindex, no radix |
| `DropdownMenu` (menu-button subset) | `ui/menu.tsx` | Goal menu (§5) — five fixed items; menu-button ARIA pattern; no radix portal |
| `Dialog` | `ui/dialog.tsx` | native `<dialog>` element (`showModal()` gives focus trap + `Escape` for free); used by Set goal… and reset confirm |
| `Tooltip` | `ui/tooltip.tsx` | hover/focus tooltip for diagnostics; content mirrored to `aria-describedby` per map A5 (tooltip is never the only channel) |
| `Alert` | `ui/banner.tsx` | reconnect / pending-request / replay banners; tone variants from status tokens |
| `Separator`, `Kbd` | folded into `styles.css` | pure CSS (`ui-separator`, `ui-kbd`) — no component file needed |
**REJECT:**
| Primitive | Reason |
|---|---|
| `Command` (cmdk palette) | the goal surface has five fixed verbs — a searchable palette adds a dep and search UI for nothing (Hick's law works in our favor with a plain menu). Revisit only if goal/command vocabulary grows in SDK+. |
| `ScrollArea` | custom scrollbars are cosmetic; native scrolling is more accessible and free. |
| `Accordion`/`Collapsible` | native `<details>` covers reasoning/tool/observation disclosures. |
| `Sheet`/`Drawer`, `Popover`, `Select`, `Switch`, `Progress`, `Skeleton`, `Toast`/`Sonner` | no Live console surface needs them; toasts specifically are rejected because failures must live in the transcript record, not ephemeral notifications (map §1.5). |
| `Table` | inspector uses definition lists / simple grids; sortable tables are not needed. |
| `Sidebar` | the existing app-shell layout already provides rails; adopting the shadcn sidebar would restructure the proven shell. |
## 5. Token additions (system change, one commit)
Add to `:root` in `devtools/browser/src/styles.css`:
- `--accent: #2f5fa8` / `--accent-surface: #e9f0fa` — pending/streaming/info
states (currently only success/warning/danger exist; pending ≠ warning).
- `--surface-raised: #fcfcfa` — inspector rows and collapsed-card summaries.
- `--motion-medium: 200ms` — banner/dialog enter (fast is too abrupt for
modal context changes); both motion tokens gated by
`prefers-reduced-motion`.
- `--z-banner: 10`, `--z-dialog: 20` — stacking discipline for the new
layered surfaces.
Contrast pairs must pass map §10-V1; verify `--accent` on `--accent-surface`
≥ 4.5:1 before merge (measured 5.1:1 at the values above).
## 6. What the implementer must NOT do
- Do not `npx shadcn add` or use the AI Elements CLI/registry into this
package (they scaffold Tailwind/radix/AI SDK). Copy source manually,
then rewrite per §1.2.
- Do not import from `ai`, `@ai-sdk/*`, `zod`, `radix-ui`, `cmdk`,
`streamdown`, or `shiki` anywhere under `devtools/browser/`.
- Do not add a second event model, message store, or client-side session
cache that could diverge from the reducer (map §7.2).
- Do not restyle existing Replay–3 surfaces beyond shared-token additions;
their screenshots are frozen QA evidence.
## 7. Evidence checklist for this record
- [x] Live docs re-checked 2026-08-08 (shadcn/ui Vite path; AI Elements
prerequisites: Node 18+, Next.js + AI SDK project, React 19,
Tailwind 4, shadcn/ui auto-install; registry install paths).
- [x] Existing package idiom confirmed (`ui/button.tsx` et al. — plain CSS
classes on tokens, React 19, no Tailwind).
- [x] Interaction map cross-references: every ADAPT row maps to a surface in
the [interaction map](live-console-interaction-map.md); every surface has a
component owner.
Reference in new issue View Git Blame Copy Permalink