mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-11 21:59:38 +01:00
fix: fail closed on unusable Codex auth during sandbox auth merge
When reusing a Codex sandbox, the workspace-restore step now performs an auth-merge check before adopting the sandbox's auth.json. The merge fails closed when: - host or sandbox Codex auth is unusable (missing token or account) - the subscription payload shapes differ between host and sandbox - subscription account identities do not match Additional hardening: node absence on PATH during the embedded decision script now exits non-zero instead of silently falling through. Co-change comments link parseAuth (the embedded script) to hasUsableAuthPayload (codex-home.ts) so a future auth-format change cannot silently diverge between the two implementations. Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Harold KimandPaperclip committed
commit
98df214917
3422 files changed
+1614966
No files matched your search
@@ -0,0 +1,286 @@
|
||||
# Agent Configuration & Activity UI
|
||||
|
||||
## Context
|
||||
|
||||
Agents are the employees of a Paperclip company. Each agent has an adapter type (`claude_local`, `codex_local`, `process`, `http`) that determines how it runs, a position in the org chart (who it reports to), a heartbeat policy (how/when it wakes up), and a budget. The UI at `/agents` needs to support creating and configuring agents, viewing their org hierarchy, and inspecting what they've been doing -- their run history, live logs, and accumulated costs.
|
||||
|
||||
This spec covers three surfaces:
|
||||
|
||||
1. **Agent Creation Dialog** -- the "New Agent" flow
|
||||
2. **Agent Detail Page** -- configuration, activity, and logs
|
||||
3. **Agents List Page** -- improvements to the existing list
|
||||
|
||||
---
|
||||
|
||||
## 1. Agent Creation Dialog
|
||||
|
||||
Follows the existing `NewIssueDialog` / `NewProjectDialog` pattern: a `Dialog` component with expand/minimize toggle, company badge breadcrumb, and Cmd+Enter submit.
|
||||
|
||||
### Fields
|
||||
|
||||
**Identity (always visible):**
|
||||
|
||||
| Field | Control | Required | Default | Notes |
|
||||
|-------|---------|----------|---------|-------|
|
||||
| Name | Text input (large, auto-focused) | Yes | -- | e.g. "Alice", "Build Bot" |
|
||||
| Title | Text input (subtitle style) | No | -- | e.g. "VP of Engineering" |
|
||||
| Role | Chip popover (select) | No | `general` | Values from `AGENT_ROLES`: ceo, cto, cmo, cfo, engineer, designer, pm, qa, devops, researcher, general |
|
||||
| Reports To | Chip popover (agent select) | No | -- | Dropdown of existing agents in the company. If this is the first agent, auto-set role to `ceo` and gray out Reports To. Otherwise required unless role is `ceo`. |
|
||||
| Capabilities | Text input | No | -- | Free-text description of what this agent can do |
|
||||
|
||||
**Adapter (collapsible section, default open):**
|
||||
|
||||
| Field | Control | Default | Notes |
|
||||
|-------|---------|---------|-------|
|
||||
| Adapter Type | Chip popover (select) | `claude_local` | `claude_local`, `codex_local`, `process`, `http` |
|
||||
| Test environment | Button | -- | Runs adapter-specific diagnostics and returns pass/warn/fail checks for current unsaved config |
|
||||
| CWD | Text input | -- | Working directory for local adapters |
|
||||
| Prompt Template | Textarea | -- | Supports `{{ agent.id }}`, `{{ agent.name }}` etc. |
|
||||
| Model | Text input | -- | Optional model override |
|
||||
|
||||
**Adapter-specific fields (shown/hidden based on adapter type):**
|
||||
|
||||
*claude_local:*
|
||||
| Field | Control | Default |
|
||||
|-------|---------|---------|
|
||||
| Max Turns Per Run | Number input | 80 |
|
||||
| Skip Permissions | Toggle | true |
|
||||
|
||||
*codex_local:*
|
||||
| Field | Control | Default |
|
||||
|-------|---------|---------|
|
||||
| Search | Toggle | false |
|
||||
| Bypass Sandbox | Toggle | true |
|
||||
|
||||
*process:*
|
||||
| Field | Control | Default |
|
||||
|-------|---------|---------|
|
||||
| Command | Text input | -- |
|
||||
| Args | Text input (comma-separated) | -- |
|
||||
|
||||
*http:*
|
||||
| Field | Control | Default |
|
||||
|-------|---------|---------|
|
||||
| URL | Text input | -- |
|
||||
| Method | Select | POST |
|
||||
| Headers | Key-value pairs | -- |
|
||||
|
||||
**Runtime (collapsible section, default collapsed):**
|
||||
|
||||
| Field | Control | Default |
|
||||
|-------|---------|---------|
|
||||
| Context Mode | Chip popover | `thin` |
|
||||
| Monthly Budget (cents) | Number input | 0 |
|
||||
| Timeout (sec) | Number input | 900 |
|
||||
| Grace Period (sec) | Number input | 15 |
|
||||
| Extra Args | Text input | -- |
|
||||
| Env Vars | Key-value pair editor | -- |
|
||||
|
||||
**Heartbeat Policy (collapsible section, default collapsed):**
|
||||
|
||||
| Field | Control | Default |
|
||||
|-------|---------|---------|
|
||||
| Enabled | Toggle | true |
|
||||
| Interval (sec) | Number input | 300 |
|
||||
| Wake on Assignment | Toggle | true |
|
||||
| Wake on On-Demand | Toggle | true |
|
||||
| Wake on Automation | Toggle | true |
|
||||
| Cooldown (sec) | Number input | 10 |
|
||||
|
||||
### Behavior
|
||||
|
||||
- On submit, calls `agentsApi.create(companyId, data)` where `data` packs identity fields at the top level and adapter-specific fields into `adapterConfig` and heartbeat/runtime into `runtimeConfig`.
|
||||
- After creation, navigate to the new agent's detail page.
|
||||
- If the company has zero agents, pre-fill role as `ceo` and disable Reports To.
|
||||
- The adapter config section updates its visible fields when adapter type changes, preserving any shared field values (cwd, promptTemplate, etc.).
|
||||
|
||||
---
|
||||
|
||||
## 2. Agent Detail Page
|
||||
|
||||
Restructure the existing tabbed layout. Keep the header (name, role, title, status badge, action buttons) and add richer tabs.
|
||||
|
||||
### Header
|
||||
|
||||
```
|
||||
[StatusBadge] Agent Name [Invoke] [Pause/Resume] [...]
|
||||
Role / Title
|
||||
```
|
||||
|
||||
The `[...]` overflow menu contains: Terminate, Reset Session, Create API Key.
|
||||
|
||||
### Tabs
|
||||
|
||||
#### Overview Tab
|
||||
|
||||
Two-column layout: left column is a summary card, right column is the org position.
|
||||
|
||||
**Summary card:**
|
||||
- Adapter type + model (if set)
|
||||
- Heartbeat interval (e.g. "every 5 min") or "Disabled"
|
||||
- Last heartbeat time (relative, e.g. "3 min ago")
|
||||
- Session status: "Active (session abc123...)" or "No session"
|
||||
- Current month spend / budget with progress bar
|
||||
|
||||
**Org position card:**
|
||||
- Reports to: clickable agent name (links to their detail page)
|
||||
- Direct reports: list of agents who report to this agent (clickable)
|
||||
|
||||
#### Configuration Tab
|
||||
|
||||
Editable form with the same sections as the creation dialog (Adapter, Runtime, Heartbeat Policy) but pre-populated with current values. Uses inline editing -- click a value to edit, press Enter or blur to save via `agentsApi.update()`.
|
||||
|
||||
Sections:
|
||||
- **Identity**: name, title, role, reports to, capabilities
|
||||
- **Adapter Config**: all adapter-specific fields for the current adapter type
|
||||
- **Heartbeat Policy**: enable/disable, interval, wake-on triggers, cooldown
|
||||
- **Runtime**: context mode, budget, timeout, grace, env vars, extra args
|
||||
|
||||
Each section is a collapsible card. Save happens per-field (PATCH on blur/enter), not a single form submit. Validation errors show inline.
|
||||
|
||||
#### Runs Tab
|
||||
|
||||
This is the primary activity/history view. Shows a paginated list of heartbeat runs, most recent first.
|
||||
|
||||
**Run list item:**
|
||||
```
|
||||
[StatusIcon] #run-id-short source: timer 2 min ago 1.2k tokens $0.03
|
||||
"Reviewed 3 PRs and filed 2 issues"
|
||||
```
|
||||
|
||||
Fields per row:
|
||||
- Status icon (green check = succeeded, red X = failed, yellow spinner = running, gray clock = queued, orange timeout = timed_out, slash = cancelled)
|
||||
- Run ID (short, first 8 chars)
|
||||
- Invocation source chip (timer, assignment, on_demand, automation)
|
||||
- Relative timestamp
|
||||
- Token usage summary (total input + output)
|
||||
- Cost
|
||||
- Result summary (first line of result or error)
|
||||
|
||||
**Clicking a run** opens a run detail inline (accordion expand) or a slide-over panel showing:
|
||||
|
||||
- Full status timeline (queued -> running -> outcome) with timestamps
|
||||
- Session before/after
|
||||
- Token breakdown: input, output, cached input
|
||||
- Cost breakdown
|
||||
- Error message and error code (if failed)
|
||||
- Exit code and signal (if applicable)
|
||||
|
||||
**Log viewer** within the run detail:
|
||||
- Streams `heartbeat_run_events` for the run, ordered by `seq`
|
||||
- Each event rendered as a log line with timestamp, level (color-coded), and message
|
||||
- Events of type `stdout`/`stderr` shown in monospace
|
||||
- System events shown with distinct styling
|
||||
- For running runs, auto-scrolls and appends live via WebSocket events (`heartbeat.run.event`, `heartbeat.run.log`)
|
||||
- "View full log" link fetches from `heartbeatsApi.log(runId)` and shows in a scrollable monospace container
|
||||
- Truncation: show last 200 events by default, "Load more" button to fetch earlier events
|
||||
|
||||
#### Issues Tab
|
||||
|
||||
Keep as-is: list of issues assigned to this agent with status, clickable to navigate to issue detail.
|
||||
|
||||
#### Costs Tab
|
||||
|
||||
Expand the existing costs tab:
|
||||
|
||||
- **Cumulative totals** from `agent_runtime_state`: total input tokens, total output tokens, total cached tokens, total cost
|
||||
- **Monthly budget** progress bar (current month spend vs budget)
|
||||
- **Per-run cost table**: date, run ID, tokens in/out/cached, cost -- sortable by date or cost
|
||||
- **Chart** (stretch): simple bar chart of daily spend over last 30 days
|
||||
|
||||
### Properties Panel (Right Sidebar)
|
||||
|
||||
The existing `AgentProperties` panel continues to show the quick-glance info. Add:
|
||||
- Session ID (truncated, with copy button)
|
||||
- Last error (if any, in red)
|
||||
- Link to "View Configuration" (scrolls to / switches to Configuration tab)
|
||||
|
||||
---
|
||||
|
||||
## 3. Agents List Page
|
||||
|
||||
### Current state
|
||||
|
||||
Shows a flat list of agents with status badge, name, role, title, and budget bar.
|
||||
|
||||
### Improvements
|
||||
|
||||
**Add "New Agent" button** in the header (Plus icon + "New Agent"), opens the creation dialog.
|
||||
|
||||
**Add view toggle**: List view (current) and Org Chart view.
|
||||
|
||||
**Org Chart view:**
|
||||
- Tree layout showing reporting hierarchy
|
||||
- Each node shows: agent name, role, status badge
|
||||
- CEO at the top, direct reports below, etc.
|
||||
- Uses the `agentsApi.org(companyId)` endpoint which already returns `OrgNode[]`
|
||||
- Clicking a node navigates to agent detail
|
||||
|
||||
**List view improvements:**
|
||||
- Add adapter type as a small chip/tag on each row
|
||||
- Add "last active" relative timestamp
|
||||
- Add running indicator (animated dot) if agent currently has a running heartbeat
|
||||
|
||||
**Filtering:**
|
||||
- Tab filters: All, Active, Paused, Error (similar to Issues page pattern)
|
||||
|
||||
---
|
||||
|
||||
## 4. Component Inventory
|
||||
|
||||
New components needed:
|
||||
|
||||
| Component | Purpose |
|
||||
|-----------|---------|
|
||||
| `NewAgentDialog` | Agent creation form dialog |
|
||||
| `AgentConfigForm` | Shared form sections for create + edit (adapter, heartbeat, runtime) |
|
||||
| `AdapterConfigFields` | Conditional fields based on adapter type |
|
||||
| `HeartbeatPolicyFields` | Heartbeat configuration fields |
|
||||
| `EnvVarEditor` | Key-value pair editor for environment variables |
|
||||
| `RunListItem` | Single run row in the runs list |
|
||||
| `RunDetail` | Expanded run detail with log viewer |
|
||||
| `LogViewer` | Streaming log viewer with auto-scroll |
|
||||
| `OrgChart` | Tree visualization of agent hierarchy |
|
||||
| `AgentSelect` | Reusable agent picker (for Reports To, etc.) |
|
||||
|
||||
Reused existing components:
|
||||
- `StatusBadge`, `EntityRow`, `EmptyState`, `PropertyRow`
|
||||
- shadcn: `Dialog`, `Tabs`, `Button`, `Popover`, `Command`, `Separator`, `Toggle`
|
||||
|
||||
---
|
||||
|
||||
## 5. API Surface
|
||||
|
||||
All endpoints already exist. No new server work needed for V1.
|
||||
|
||||
| Action | Endpoint | Used by |
|
||||
|--------|----------|---------|
|
||||
| List agents | `GET /companies/:id/agents` | List page |
|
||||
| Get org tree | `GET /companies/:id/org` | Org chart view |
|
||||
| Create agent | `POST /companies/:id/agents` | Creation dialog |
|
||||
| Update agent | `PATCH /agents/:id` | Configuration tab |
|
||||
| Pause/Resume/Terminate | `POST /agents/:id/{action}` | Header actions |
|
||||
| Reset session | `POST /agents/:id/runtime-state/reset-session` | Overflow menu |
|
||||
| Create API key | `POST /agents/:id/keys` | Overflow menu |
|
||||
| Get runtime state | `GET /agents/:id/runtime-state` | Overview tab, properties panel |
|
||||
| Invoke/Wakeup | `POST /agents/:id/heartbeat/invoke` | Header invoke button |
|
||||
| List runs | `GET /companies/:id/heartbeat-runs?agentId=X` | Runs tab |
|
||||
| Cancel run | `POST /heartbeat-runs/:id/cancel` | Run detail |
|
||||
| Run events | `GET /heartbeat-runs/:id/events` | Log viewer |
|
||||
| Run log | `GET /heartbeat-runs/:id/log` | Full log view |
|
||||
|
||||
---
|
||||
|
||||
## 6. Implementation Order
|
||||
|
||||
1. **New Agent Dialog** -- unblocks agent creation from the UI
|
||||
2. **Agents List improvements** -- add New Agent button, tab filters, adapter chip, running indicator
|
||||
3. **Agent Detail: Configuration tab** -- editable adapter/heartbeat/runtime config
|
||||
4. **Agent Detail: Runs tab** -- run history list with status, tokens, cost
|
||||
5. **Agent Detail: Run Detail + Log Viewer** -- expandable run detail with streaming logs
|
||||
6. **Agent Detail: Overview tab** -- summary card, org position
|
||||
7. **Agent Detail: Costs tab** -- expanded cost breakdown
|
||||
8. **Org Chart view** -- tree visualization on list page
|
||||
9. **Properties panel updates** -- session ID, last error
|
||||
|
||||
Steps 1-5 are the core. Steps 6-9 are polish.
|
||||
@@ -0,0 +1,526 @@
|
||||
# ClipHub: Marketplace for Paperclip Team Configurations
|
||||
|
||||
> Supersession note: this marketplace plan predates the markdown-first company package direction. For the current package-format and import/export rollout plan, see `doc/plans/2026-03-13-company-import-export-v2.md` and `docs/companies/companies-spec.md`.
|
||||
|
||||
> The "app store" for whole-company AI teams — pre-built Paperclip configurations, agent blueprints, skills, and governance templates that ship real work from day one.
|
||||
|
||||
## 1. Vision & Positioning
|
||||
|
||||
**ClipHub** sells **entire team configurations** — org charts, agent roles, inter-agent workflows, governance rules, and project templates — for Paperclip-managed companies.
|
||||
|
||||
| Dimension | ClipHub |
|
||||
|---|---|
|
||||
| Unit of sale | Team blueprint (multi-agent org) |
|
||||
| Buyer | Founder / team lead spinning up an AI company |
|
||||
| Install target | Paperclip company (agents, projects, governance) |
|
||||
| Value prop | "Skip org design — get a shipping team in minutes" |
|
||||
| Price range | $0–$499 per blueprint (+ individual add-ons) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Product Taxonomy
|
||||
|
||||
### 2.1 Team Blueprints (primary product)
|
||||
|
||||
A complete Paperclip company configuration:
|
||||
|
||||
- **Org chart**: Agents with roles, titles, reporting chains, capabilities
|
||||
- **Agent configs**: Adapter type, model, prompt templates, instructions paths
|
||||
- **Governance rules**: Approval flows, budget limits, escalation chains
|
||||
- **Project templates**: Pre-configured projects with workspace settings
|
||||
- **Skills & instructions**: AGENTS.md / skill files bundled per agent
|
||||
|
||||
**Examples:**
|
||||
- "SaaS Startup Team" — CEO, CTO, Engineer, CMO, Designer ($199)
|
||||
- "Content Agency" — Editor-in-Chief, 3 Writers, SEO Analyst, Social Manager ($149)
|
||||
- "Dev Shop" — CTO, 2 Engineers, QA, DevOps ($99)
|
||||
- "Solo Founder + Crew" — CEO agent + 3 ICs across eng/marketing/ops ($79)
|
||||
|
||||
### 2.2 Agent Blueprints (individual agents within a team context)
|
||||
|
||||
Single-agent configurations designed to plug into a Paperclip org:
|
||||
|
||||
- Role definition, prompt template, adapter config
|
||||
- Reporting chain expectations (who they report to)
|
||||
- Skill bundles included
|
||||
- Governance defaults (budget, permissions)
|
||||
|
||||
**Examples:**
|
||||
- "Staff Engineer" — ships production code, manages PRs ($29)
|
||||
- "Growth Marketer" — content pipeline, SEO, social ($39)
|
||||
- "DevOps Agent" — CI/CD, deployment, monitoring ($29)
|
||||
|
||||
### 2.3 Skills (modular capabilities)
|
||||
|
||||
Portable skill files that any Paperclip agent can use:
|
||||
|
||||
- Markdown skill files with instructions
|
||||
- Tool configurations and shell scripts
|
||||
- Compatible with Paperclip's skill loading system
|
||||
|
||||
**Examples:**
|
||||
- "Git PR Workflow" — standardized PR creation and review (Free)
|
||||
- "Deployment Pipeline" — Cloudflare/Vercel deploy skill ($9)
|
||||
- "Customer Support Triage" — ticket classification and routing ($19)
|
||||
|
||||
### 2.4 Governance Templates
|
||||
|
||||
Pre-built approval flows and policies:
|
||||
|
||||
- Budget thresholds and approval chains
|
||||
- Cross-team delegation rules
|
||||
- Escalation procedures
|
||||
- Billing code structures
|
||||
|
||||
**Examples:**
|
||||
- "Startup Governance" — lightweight, CEO approves > $50 (Free)
|
||||
- "Enterprise Governance" — multi-tier approval, audit trail ($49)
|
||||
|
||||
---
|
||||
|
||||
## 3. Data Schemas
|
||||
|
||||
### 3.1 Listing
|
||||
|
||||
```typescript
|
||||
interface Listing {
|
||||
id: string;
|
||||
slug: string; // URL-friendly identifier
|
||||
type: 'team_blueprint' | 'agent_blueprint' | 'skill' | 'governance_template';
|
||||
title: string;
|
||||
tagline: string; // Short pitch (≤120 chars)
|
||||
description: string; // Markdown, full details
|
||||
|
||||
// Pricing
|
||||
price: number; // Cents (0 = free)
|
||||
currency: 'usd';
|
||||
|
||||
// Creator
|
||||
creatorId: string;
|
||||
creatorName: string;
|
||||
creatorAvatar: string | null;
|
||||
|
||||
// Categorization
|
||||
categories: string[]; // e.g. ['saas', 'engineering', 'marketing']
|
||||
tags: string[]; // e.g. ['claude', 'startup', '5-agent']
|
||||
agentCount: number | null; // For team blueprints
|
||||
|
||||
// Content
|
||||
previewImages: string[]; // Screenshots / org chart visuals
|
||||
readmeMarkdown: string; // Full README shown on detail page
|
||||
includedFiles: string[]; // List of files in the bundle
|
||||
|
||||
// Compatibility
|
||||
compatibleAdapters: string[]; // ['claude_local', 'codex_local', ...]
|
||||
requiredModels: string[]; // ['claude-opus-4-6', 'claude-sonnet-4-6']
|
||||
paperclipVersionMin: string; // Minimum Paperclip version
|
||||
|
||||
// Social proof
|
||||
installCount: number;
|
||||
rating: number | null; // 1.0–5.0
|
||||
reviewCount: number;
|
||||
|
||||
// Metadata
|
||||
version: string; // Semver
|
||||
publishedAt: string;
|
||||
updatedAt: string;
|
||||
status: 'draft' | 'published' | 'archived';
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Team Blueprint Bundle
|
||||
|
||||
```typescript
|
||||
interface TeamBlueprint {
|
||||
listingId: string;
|
||||
|
||||
// Org structure
|
||||
agents: AgentBlueprint[];
|
||||
reportingChain: { agentSlug: string; reportsTo: string | null }[];
|
||||
|
||||
// Governance
|
||||
governance: {
|
||||
approvalRules: ApprovalRule[];
|
||||
budgetDefaults: { role: string; monthlyCents: number }[];
|
||||
escalationChain: string[]; // Agent slugs in escalation order
|
||||
};
|
||||
|
||||
// Projects
|
||||
projects: ProjectTemplate[];
|
||||
|
||||
// Company-level config
|
||||
companyDefaults: {
|
||||
name: string;
|
||||
defaultModel: string;
|
||||
defaultAdapter: string;
|
||||
};
|
||||
}
|
||||
|
||||
interface AgentBlueprint {
|
||||
slug: string; // e.g. 'cto', 'engineer-1'
|
||||
name: string;
|
||||
role: string;
|
||||
title: string;
|
||||
icon: string;
|
||||
capabilities: string;
|
||||
promptTemplate: string;
|
||||
adapterType: string;
|
||||
adapterConfig: Record<string, any>;
|
||||
instructionsPath: string | null; // Path to AGENTS.md or similar
|
||||
skills: SkillBundle[];
|
||||
budgetMonthlyCents: number;
|
||||
permissions: {
|
||||
canCreateAgents: boolean;
|
||||
canApproveHires: boolean;
|
||||
};
|
||||
}
|
||||
|
||||
interface ProjectTemplate {
|
||||
name: string;
|
||||
description: string;
|
||||
workspace: {
|
||||
cwd: string | null;
|
||||
repoUrl: string | null;
|
||||
} | null;
|
||||
}
|
||||
|
||||
interface ApprovalRule {
|
||||
trigger: string; // e.g. 'hire_agent', 'budget_exceed'
|
||||
threshold: number | null;
|
||||
approverRole: string;
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Creator / Seller
|
||||
|
||||
```typescript
|
||||
interface Creator {
|
||||
id: string;
|
||||
userId: string; // Auth provider ID
|
||||
displayName: string;
|
||||
bio: string;
|
||||
avatarUrl: string | null;
|
||||
website: string | null;
|
||||
listings: string[]; // Listing IDs
|
||||
totalInstalls: number;
|
||||
totalRevenue: number; // Cents earned
|
||||
joinedAt: string;
|
||||
verified: boolean;
|
||||
payoutMethod: 'stripe_connect';
|
||||
stripeAccountId: string | null;
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 Purchase / Install
|
||||
|
||||
```typescript
|
||||
interface Purchase {
|
||||
id: string;
|
||||
listingId: string;
|
||||
buyerUserId: string;
|
||||
buyerCompanyId: string | null; // Target Paperclip company
|
||||
pricePaidCents: number;
|
||||
paymentIntentId: string | null; // Stripe
|
||||
installedAt: string | null; // When deployed to company
|
||||
status: 'pending' | 'completed' | 'refunded';
|
||||
createdAt: string;
|
||||
}
|
||||
```
|
||||
|
||||
### 3.5 Review
|
||||
|
||||
```typescript
|
||||
interface Review {
|
||||
id: string;
|
||||
listingId: string;
|
||||
authorUserId: string;
|
||||
authorDisplayName: string;
|
||||
rating: number; // 1–5
|
||||
title: string;
|
||||
body: string; // Markdown
|
||||
verifiedPurchase: boolean;
|
||||
createdAt: string;
|
||||
updatedAt: string;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Pages & Routes
|
||||
|
||||
### 4.1 Public Pages
|
||||
|
||||
| Route | Page | Description |
|
||||
|---|---|---|
|
||||
| `/` | Homepage | Hero, featured blueprints, popular skills, how it works |
|
||||
| `/browse` | Marketplace browse | Filterable grid of all listings |
|
||||
| `/browse?type=team_blueprint` | Team blueprints | Filtered to team configs |
|
||||
| `/browse?type=agent_blueprint` | Agent blueprints | Single-agent configs |
|
||||
| `/browse?type=skill` | Skills | Skill listings |
|
||||
| `/browse?type=governance_template` | Governance | Policy templates |
|
||||
| `/listings/:slug` | Listing detail | Full product page |
|
||||
| `/creators/:slug` | Creator profile | Bio, all listings, stats |
|
||||
| `/about` | About ClipHub | Mission, how it works |
|
||||
| `/pricing` | Pricing & fees | Creator revenue share, buyer info |
|
||||
|
||||
### 4.2 Authenticated Pages
|
||||
|
||||
| Route | Page | Description |
|
||||
|---|---|---|
|
||||
| `/dashboard` | Buyer dashboard | Purchased items, installed blueprints |
|
||||
| `/dashboard/purchases` | Purchase history | All transactions |
|
||||
| `/dashboard/installs` | Installations | Deployed blueprints with status |
|
||||
| `/creator` | Creator dashboard | Listing management, analytics |
|
||||
| `/creator/listings/new` | Create listing | Multi-step listing wizard |
|
||||
| `/creator/listings/:id/edit` | Edit listing | Modify existing listing |
|
||||
| `/creator/analytics` | Analytics | Revenue, installs, views |
|
||||
| `/creator/payouts` | Payouts | Stripe Connect payout history |
|
||||
|
||||
### 4.3 API Routes
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/listings` | Browse listings (filters: type, category, price range, sort) |
|
||||
| `GET` | `/api/listings/:slug` | Get listing detail |
|
||||
| `POST` | `/api/listings` | Create listing (creator auth) |
|
||||
| `PATCH` | `/api/listings/:id` | Update listing |
|
||||
| `DELETE` | `/api/listings/:id` | Archive listing |
|
||||
| `POST` | `/api/listings/:id/purchase` | Purchase listing (Stripe checkout) |
|
||||
| `POST` | `/api/listings/:id/install` | Install to Paperclip company |
|
||||
| `GET` | `/api/listings/:id/reviews` | Get reviews |
|
||||
| `POST` | `/api/listings/:id/reviews` | Submit review |
|
||||
| `GET` | `/api/creators/:slug` | Creator profile |
|
||||
| `GET` | `/api/creators/me` | Current creator profile |
|
||||
| `POST` | `/api/creators` | Register as creator |
|
||||
| `GET` | `/api/purchases` | Buyer's purchase history |
|
||||
| `GET` | `/api/analytics` | Creator analytics |
|
||||
|
||||
---
|
||||
|
||||
## 5. User Flows
|
||||
|
||||
### 5.1 Buyer: Browse → Purchase → Install
|
||||
|
||||
```
|
||||
Homepage → Browse marketplace → Filter by type/category
|
||||
→ Click listing → Read details, reviews, preview org chart
|
||||
→ Click "Buy" → Stripe checkout (or free install)
|
||||
→ Post-purchase: "Install to Company" button
|
||||
→ Select target Paperclip company (or create new)
|
||||
→ ClipHub API calls Paperclip API to:
|
||||
1. Create agents with configs from blueprint
|
||||
2. Set up reporting chains
|
||||
3. Create projects with workspace configs
|
||||
4. Apply governance rules
|
||||
5. Deploy skill files to agent instruction paths
|
||||
→ Redirect to Paperclip dashboard with new team running
|
||||
```
|
||||
|
||||
### 5.2 Creator: Build → Publish → Earn
|
||||
|
||||
```
|
||||
Sign up as creator → Connect Stripe
|
||||
→ "New Listing" wizard:
|
||||
Step 1: Type (team/agent/skill/governance)
|
||||
Step 2: Basic info (title, tagline, description, categories)
|
||||
Step 3: Upload bundle (JSON config + skill files + README)
|
||||
Step 4: Preview & org chart visualization
|
||||
Step 5: Pricing ($0–$499)
|
||||
Step 6: Publish
|
||||
→ Live on marketplace immediately
|
||||
→ Track installs, revenue, reviews on creator dashboard
|
||||
```
|
||||
|
||||
### 5.3 Creator: Export from Paperclip → Publish
|
||||
|
||||
```
|
||||
Running Paperclip company → "Export as Blueprint" (CLI or UI)
|
||||
→ Paperclip exports:
|
||||
- Agent configs (sanitized — no secrets)
|
||||
- Org chart / reporting chains
|
||||
- Governance rules
|
||||
- Project templates
|
||||
- Skill files
|
||||
→ Upload to ClipHub as new listing
|
||||
→ Edit details, set price, publish
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. UI Design Direction
|
||||
|
||||
### 6.1 Visual Language
|
||||
|
||||
- **Color palette**: Dark ink primary, warm sand backgrounds, accent color for CTAs (Paperclip brand blue/purple)
|
||||
- **Typography**: Clean sans-serif, strong hierarchy, monospace for technical details
|
||||
- **Cards**: Rounded corners, subtle shadows, clear pricing badges
|
||||
- **Org chart visuals**: Interactive tree/graph showing agent relationships in team blueprints
|
||||
|
||||
### 6.2 Key Design Elements
|
||||
|
||||
| Element | ClipHub |
|
||||
|---|---|
|
||||
| Product card | Org chart mini-preview + agent count badge |
|
||||
| Detail page | Interactive org chart + per-agent breakdown |
|
||||
| Install flow | One-click deploy to Paperclip company |
|
||||
| Social proof | "X companies running this blueprint" |
|
||||
| Preview | Live demo sandbox (stretch goal) |
|
||||
|
||||
### 6.3 Listing Card Design
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ [Org Chart Mini-Preview] │
|
||||
│ ┌─CEO─┐ │
|
||||
│ ├─CTO─┤ │
|
||||
│ └─ENG──┘ │
|
||||
│ │
|
||||
│ SaaS Startup Team │
|
||||
│ "Ship your MVP with a 5-agent │
|
||||
│ engineering + marketing team" │
|
||||
│ │
|
||||
│ 👥 5 agents ⬇ 234 installs │
|
||||
│ ★ 4.7 (12 reviews) │
|
||||
│ │
|
||||
│ By @masinov $199 [Buy] │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 6.4 Detail Page Sections
|
||||
|
||||
1. **Hero**: Title, tagline, price, install button, creator info
|
||||
2. **Org Chart**: Interactive visualization of agent hierarchy
|
||||
3. **Agent Breakdown**: Expandable cards for each agent — role, capabilities, model, skills
|
||||
4. **Governance**: Approval flows, budget structure, escalation chain
|
||||
5. **Included Projects**: Project templates with workspace configs
|
||||
6. **README**: Full markdown documentation
|
||||
7. **Reviews**: Star ratings + written reviews
|
||||
8. **Related Blueprints**: Cross-sell similar team configs
|
||||
9. **Creator Profile**: Mini bio, other listings
|
||||
|
||||
---
|
||||
|
||||
## 7. Installation Mechanics
|
||||
|
||||
### 7.1 Install API Flow
|
||||
|
||||
When a buyer clicks "Install to Company":
|
||||
|
||||
```
|
||||
POST /api/listings/:id/install
|
||||
{
|
||||
"targetCompanyId": "uuid", // Existing Paperclip company
|
||||
"overrides": { // Optional customization
|
||||
"agentModel": "claude-sonnet-4-6", // Override default model
|
||||
"budgetScale": 0.5, // Scale budgets
|
||||
"skipProjects": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The install handler:
|
||||
|
||||
1. Validates buyer owns the purchase
|
||||
2. Validates target company access
|
||||
3. For each agent in blueprint:
|
||||
- `POST /api/companies/:id/agents` (if `paperclip-create-agent` supports it, or via approval flow)
|
||||
- Sets adapter config, prompt template, instructions path
|
||||
4. Sets reporting chains
|
||||
5. Creates projects and workspaces
|
||||
6. Applies governance rules
|
||||
7. Deploys skill files to configured paths
|
||||
8. Returns summary of created resources
|
||||
|
||||
### 7.2 Conflict Resolution
|
||||
|
||||
- **Agent name collision**: Append `-2`, `-3` suffix
|
||||
- **Project name collision**: Prompt buyer to rename or skip
|
||||
- **Adapter mismatch**: Warn if blueprint requires adapter not available locally
|
||||
- **Model availability**: Warn if required model not configured
|
||||
|
||||
---
|
||||
|
||||
## 8. Revenue Model
|
||||
|
||||
| Fee | Amount | Notes |
|
||||
|---|---|---|
|
||||
| Creator revenue share | 90% of sale price | Minus Stripe processing (~2.9% + $0.30) |
|
||||
| Platform fee | 10% of sale price | ClipHub's cut |
|
||||
| Free listings | $0 | No fees for free listings |
|
||||
| Stripe Connect | Standard rates | Handled by Stripe |
|
||||
|
||||
---
|
||||
|
||||
## 9. Technical Architecture
|
||||
|
||||
### 9.1 Stack
|
||||
|
||||
- **Frontend**: Next.js (React), Tailwind CSS, same UI framework as Paperclip
|
||||
- **Backend**: Node.js API (or extend Paperclip server)
|
||||
- **Database**: Postgres (can share Paperclip's DB or separate)
|
||||
- **Payments**: Stripe Connect (marketplace mode)
|
||||
- **Storage**: S3/R2 for listing bundles and images
|
||||
- **Auth**: Shared with Paperclip auth (or OAuth2)
|
||||
|
||||
### 9.2 Integration with Paperclip
|
||||
|
||||
ClipHub can be:
|
||||
- **Option A**: A separate app that calls Paperclip's API to install blueprints
|
||||
- **Option B**: A built-in section of the Paperclip UI (`/marketplace` route)
|
||||
|
||||
Option B is simpler for MVP — adds routes to the existing Paperclip UI and API.
|
||||
|
||||
### 9.3 Bundle Format
|
||||
|
||||
Listing bundles are ZIP/tar archives containing:
|
||||
|
||||
```
|
||||
blueprint/
|
||||
├── manifest.json # Listing metadata + agent configs
|
||||
├── README.md # Documentation
|
||||
├── org-chart.json # Agent hierarchy
|
||||
├── governance.json # Approval rules, budgets
|
||||
├── agents/
|
||||
│ ├── ceo/
|
||||
│ │ ├── prompt.md # Prompt template
|
||||
│ │ ├── AGENTS.md # Instructions
|
||||
│ │ └── skills/ # Skill files
|
||||
│ ├── cto/
|
||||
│ │ ├── prompt.md
|
||||
│ │ ├── AGENTS.md
|
||||
│ │ └── skills/
|
||||
│ └── engineer/
|
||||
│ ├── prompt.md
|
||||
│ ├── AGENTS.md
|
||||
│ └── skills/
|
||||
└── projects/
|
||||
└── default/
|
||||
└── workspace.json # Project workspace config
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. MVP Scope
|
||||
|
||||
### Phase 1: Foundation
|
||||
- [ ] Listing schema and CRUD API
|
||||
- [ ] Browse page with filters (type, category, price)
|
||||
- [ ] Listing detail page with org chart visualization
|
||||
- [ ] Creator registration and listing creation wizard
|
||||
- [ ] Free installs only (no payments yet)
|
||||
- [ ] Install flow: blueprint → Paperclip company
|
||||
|
||||
### Phase 2: Payments & Social
|
||||
- [ ] Stripe Connect integration
|
||||
- [ ] Purchase flow
|
||||
- [ ] Review system
|
||||
- [ ] Creator analytics dashboard
|
||||
- [ ] "Export from Paperclip" CLI command
|
||||
|
||||
### Phase 3: Growth
|
||||
- [ ] Search with relevance ranking
|
||||
- [ ] Featured/trending listings
|
||||
- [ ] Creator verification program
|
||||
- [ ] Blueprint versioning and update notifications
|
||||
- [ ] Live demo sandbox
|
||||
- [ ] API for programmatic publishing
|
||||
Reference in new issue
Block a user