mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-16 14:40:49 +02:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - A stable agent persona is useful only when the same identity appears across the app. > - Lists, task messages, selectors, and activity feeds need inexpensive static avatars. > - Onboarding and agent headers need a larger character with expressions and pointer tracking. > - This pull request connects the persona foundation to those existing views and preserves onboarding draft assignments. > - Full-page stories and Linux checks make the placements and performance contract reviewable. ## Linked Issues or Issue Description **Problem or motivation** Agents need a stable visual identity in lists, tasks, onboarding, and configuration. External tools also need an image URL for that identity. **Proposed solution** Assign each agent a permanent palette from a fixed ClipLab character library. Store the assignment on the agent. Render and cache preset PNG URLs on demand. Use static images in dense views and one animated character in larger placements. **Alternatives considered** A generated image bundle requires a separate asset build. A live renderer in every avatar adds unnecessary work in large lists. Arbitrary uploaded images do not provide the requested shared character system. **Roadmap alignment** This improves agent identity across existing control-plane views. It preserves agent permissions, company boundaries, and status labels. ROADMAP.md has no separate ClipLab persona milestone. Related approaches: #2422 adds configurable image URLs and DiceBear generation; #5578 adds optional uploaded avatars. This work uses a fixed, versioned character library and preset URLs. ## What Changed - Replace agent icons with static persona images across lists, the sidebar, org charts, tasks, comments, selectors, activity, and dashboard views. - Put one animated character in the agent header. Let it follow the pointer across the page, with reduced-motion and touch fallbacks. - Add larger padded characters to agent creation. Keep the palette stable across draft refreshes and connection retries, then reveal it after success. - Pass appearance through shared projections rather than fetching each agent separately. - Add real full-page Storybook examples for the agent list, overview, task, dashboard, new-agent dialog, and connection page. - Add Linux screenshot, clipping, density, and 500-avatar performance checks. ## Verification - `pnpm -r typecheck`, `pnpm build`, and token gates pass on the rebased tree. Persona lifecycle tests pass. - The rebased feature passes 38 Linux screenshot/performance checks, including both display densities, corner pointer positions, and the no-WebGL/no-live-download contract for 500 avatars. - The final Linux persona suite passes all 38 visual, lifecycle, density, and full-page checks using the standard Storybook configuration and real on-demand avatar endpoint. - Final local focused verification: 45 avatar/native-recovery tests pass; UI identity/routine tests, typecheck/build, token gates, and Storybook build pass. - Current-head CI passes: full workspace/server tests, all serialized server groups, typecheck/release checks, build, canary validation, and end-to-end shards. The build passed after retrying a native-runner concurrency-test failure; its three targeted cases also pass locally. - Manual inspection covered stable identities in the app, header placement, full-page mouse tracking, onboarding size, and task/dashboard placements. ### Screenshots Linux captures use synthetic Storybook fixtures. Full-page captures use reduced motion. The live character, mouse tracking, and disposal are checked separately. <details> <summary>Agent overview with the character in its header</summary> <img src="https://raw.githubusercontent.com/paperclipai/paperclip/8c68f42b268ada22b67d79d0fe1bb0a2f84ec25c/screenshots/full-page-agent-overview.png" width="900" alt="Agent overview with the character in its header" /> </details> <details> <summary>Task messages and assignee identity</summary> <img src="https://raw.githubusercontent.com/paperclipai/paperclip/8c68f42b268ada22b67d79d0fe1bb0a2f84ec25c/screenshots/full-page-task.png" width="900" alt="Task messages and assignee identity" /> </details> <details> <summary>Larger onboarding character with room for expressions</summary> <img src="https://raw.githubusercontent.com/paperclipai/paperclip/8c68f42b268ada22b67d79d0fe1bb0a2f84ec25c/screenshots/full-page-meet-your-next-agent.png" width="900" alt="Larger onboarding character with room for expressions" /> </details> <details> <summary>Dashboard agent activity</summary> <img src="https://raw.githubusercontent.com/paperclipai/paperclip/8c68f42b268ada22b67d79d0fe1bb0a2f84ec25c/screenshots/full-page-company-dashboard.png" width="900" alt="Dashboard agent activity" /> </details> ## Risks - This PR depends on #13170, the persona foundation. Merge the foundation first, then retarget this PR to master. - Many placements change from icons to character silhouettes. Human avatars and authoritative agent status labels retain their existing behavior. - Only one character can render live per view. Reduced motion, hidden/offscreen content, touch input, and renderer failures use the defined fallbacks. - The full-page stories use fixture data. They do not contact a real company or complete real provider sign-in. ## Model Used OpenAI Codex, GPT-6 family. The exact model identifier and context window are not exposed in this session. Used code editing, shell execution, browser inspection, and Linux visual testing. ## 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 either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] 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 any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> Co-authored-by: Tonio <tonework@gmail.com> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
154 lines
5.5 KiB
TypeScript
154 lines
5.5 KiB
TypeScript
import { AgentCharacter } from "../AgentCharacter";
|
|
import { useState } from "react";
|
|
import { MotionConfig } from "motion/react";
|
|
|
|
import { Checkbox } from "../ui/checkbox";
|
|
import { AgentPreview } from "./AgentPreview";
|
|
import { CredentialModeLink } from "./CredentialModeLink";
|
|
import { FooterNav } from "./FooterNav";
|
|
import {
|
|
ModelSourceTiles,
|
|
type CredentialMode,
|
|
type ModelSource,
|
|
} from "./ModelSourceTiles";
|
|
import { OnboardingHeading } from "./OnboardingPrimitives";
|
|
import { PillGuy } from "./PillGuy";
|
|
import { SleepingZs } from "./SleepingZs";
|
|
import { Stepper } from "./Stepper";
|
|
|
|
/**
|
|
* A prototype of the connect step, from the PCLP-Onboarding file (nodes
|
|
* 2941:8291 and 2933:4592).
|
|
*
|
|
* A mock, not the shipped step. The wizard's real step 4 puts two adapter cards
|
|
* over an advanced-settings disclosure and probes the environment before
|
|
* hiring; none of that is wired up here. What is here is the part the design is
|
|
* actually asking a question about — how the row of sources reads as you point
|
|
* at it, pick one, and flip the whole row between subscription and API
|
|
* credentials — so it can be judged before any of that machinery is moved.
|
|
*
|
|
* It lives in `components/` rather than beside a story because two surfaces
|
|
* render it: the Storybook stories, and the standalone
|
|
* `connect-model-preview.html` entry that gets deployed for review. A copy in
|
|
* each would have drifted the moment one was tweaked.
|
|
*
|
|
* Nothing here reaches a backend, and it needs none of the app's providers —
|
|
* every piece it composes is presentational.
|
|
*/
|
|
|
|
/**
|
|
* The two sources the step offers, matching the shipped step's own list.
|
|
*
|
|
* Claude Code and Codex are the only adapters the display registry marks
|
|
* `recommended`, and the real step builds its row from exactly that filter — so
|
|
* a third tile here would be a design the wizard could never render. OpenCode
|
|
* was drawn at one point and is deliberately gone.
|
|
*/
|
|
const MODEL_SOURCES: ModelSource[] = [
|
|
{
|
|
id: "claude_local",
|
|
label: "Claude Code",
|
|
icon: <img src="/brands/claude-color.svg" alt="" className="size-full" />,
|
|
},
|
|
{
|
|
id: "codex_local",
|
|
label: "Codex",
|
|
icon: <img src="/brands/codex-color.svg" alt="" className="size-full" />,
|
|
},
|
|
];
|
|
|
|
/**
|
|
* Which control flips the credential mode. Two alternates of the same
|
|
* behaviour, kept side by side so they can be compared rather than argued
|
|
* about:
|
|
*
|
|
* `checkbox` is the Figma frames — a ticked box reading "Use API keys instead",
|
|
* which shows the current state plainly and costs a row of chrome.
|
|
*
|
|
* `link` is a line of text that renames itself on press. Lighter, and it turns
|
|
* the row into a single sentence, but it can only ever name the destination —
|
|
* so where you are now is left entirely to the tiles' tags.
|
|
*/
|
|
export type CredentialControl = "checkbox" | "link";
|
|
|
|
export function ConnectModelPreview({
|
|
initialSourceId = null,
|
|
initialUseApiKeys = false,
|
|
control = "checkbox",
|
|
}: {
|
|
initialSourceId?: string | null;
|
|
initialUseApiKeys?: boolean;
|
|
control?: CredentialControl;
|
|
}) {
|
|
const [selectedId, setSelectedId] = useState<string | null>(initialSourceId);
|
|
const [useApiKeys, setUseApiKeys] = useState(initialUseApiKeys);
|
|
const mode: CredentialMode = useApiKeys ? "api" : "subscription";
|
|
|
|
return (
|
|
// The arc's own convention: OS-level reduced motion neutralises the
|
|
// movement, and every piece below still arrives in its final state.
|
|
<MotionConfig reducedMotion="user">
|
|
<div className="w-(--sz-560px) max-w-full p-10">
|
|
{/* Connect is the arc's second step. `Stepper` carries its own bottom
|
|
margin, which is the gap the frame wants under the dots. */}
|
|
<Stepper step={2} />
|
|
|
|
<div className="flex flex-col items-center">
|
|
{/* `relative` is load-bearing: the sleep marks anchor to this box and
|
|
travel out past its top-right corner. */}
|
|
<div className="relative size-(--sz-72px)">
|
|
<AgentCharacter state="sleepy" muted size={128} className="size-full" />
|
|
<SleepingZs />
|
|
</div>
|
|
<AgentPreview agentName="Darnold" agentRole="" />
|
|
</div>
|
|
|
|
<div className="pt-6">
|
|
<OnboardingHeading
|
|
center
|
|
title="Connect a model"
|
|
lede="Paperclip works with your existing subscription or API keys."
|
|
/>
|
|
</div>
|
|
|
|
<div className="space-y-2 pt-12">
|
|
<ModelSourceTiles
|
|
label="Model source"
|
|
sources={MODEL_SOURCES}
|
|
mode={mode}
|
|
selectedId={selectedId}
|
|
onSelect={setSelectedId}
|
|
/>
|
|
|
|
{control === "link" ? (
|
|
<CredentialModeLink
|
|
mode={mode}
|
|
onChange={(next) => setUseApiKeys(next === "api")}
|
|
/>
|
|
) : (
|
|
<label className="flex cursor-pointer items-start gap-2.5 px-3 py-2">
|
|
<Checkbox
|
|
className="mt-0.5"
|
|
checked={useApiKeys}
|
|
onCheckedChange={(checked) => setUseApiKeys(checked === true)}
|
|
/>
|
|
<span className="text-sm font-medium text-foreground">
|
|
Use API keys instead
|
|
</span>
|
|
</label>
|
|
)}
|
|
</div>
|
|
|
|
{/* The CTA has nothing to connect until a source is picked, so it stays
|
|
disabled rather than failing on press. */}
|
|
<FooterNav
|
|
onBack={() => {}}
|
|
primaryLabel="Connect"
|
|
primaryDisabled={selectedId === null}
|
|
onPrimary={() => {}}
|
|
/>
|
|
</div>
|
|
</MotionConfig>
|
|
);
|
|
}
|