700 lines
16 KiB
Markdown
700 lines
16 KiB
Markdown
# Kitchen Sink Plugin Plan
|
|
|
|
## Goal
|
|
|
|
Add a new first-party example plugin, `Kitchen Sink (Example)`, that demonstrates every currently implemented Paperclip plugin API surface in one place.
|
|
|
|
This plugin is meant to be:
|
|
|
|
- a living reference implementation for contributors
|
|
- a manual test harness for the plugin runtime
|
|
- a discoverable demo of what plugins can actually do today
|
|
|
|
It is not meant to be a polished end-user product plugin.
|
|
|
|
## Why
|
|
|
|
The current plugin system has a real API surface, but it is spread across:
|
|
|
|
- SDK docs
|
|
- SDK types
|
|
- plugin spec prose
|
|
- two example plugins that each show only a narrow slice
|
|
|
|
That makes it hard to answer basic questions like:
|
|
|
|
- what can plugins render?
|
|
- what can plugin workers actually do?
|
|
- which surfaces are real versus aspirational?
|
|
- how should a new plugin be structured in this repo?
|
|
|
|
The kitchen-sink plugin should answer those questions by example.
|
|
|
|
## Success Criteria
|
|
|
|
The plugin is successful if a contributor can install it and, without reading the SDK first, discover and exercise the current plugin runtime surface area from inside Paperclip.
|
|
|
|
Concretely:
|
|
|
|
- it installs from the bundled examples list
|
|
- it exposes at least one demo for every implemented worker API surface
|
|
- it exposes at least one demo for every host-mounted UI surface
|
|
- it clearly labels local-only / trusted-only demos
|
|
- it is safe enough for local development by default
|
|
- it doubles as a regression harness for plugin runtime changes
|
|
|
|
## Constraints
|
|
|
|
- Keep it instance-installed, not company-installed.
|
|
- Treat this as a trusted/local example plugin.
|
|
- Do not rely on cloud-safe runtime assumptions.
|
|
- Avoid destructive defaults.
|
|
- Avoid irreversible mutations unless they are clearly labeled and easy to undo.
|
|
|
|
## Source Of Truth For This Plan
|
|
|
|
This plan is based on the currently implemented SDK/types/runtime, not only the long-horizon spec.
|
|
|
|
Primary references:
|
|
|
|
- `packages/plugins/sdk/README.md`
|
|
- `packages/plugins/sdk/src/types.ts`
|
|
- `packages/plugins/sdk/src/ui/types.ts`
|
|
- `packages/shared/src/constants.ts`
|
|
- `packages/shared/src/types/plugin.ts`
|
|
|
|
## Current Surface Inventory
|
|
|
|
### Worker/runtime APIs to demonstrate
|
|
|
|
These are the concrete `ctx` clients currently exposed by the SDK:
|
|
|
|
- `ctx.config`
|
|
- `ctx.events`
|
|
- `ctx.jobs`
|
|
- `ctx.launchers`
|
|
- `ctx.http`
|
|
- `ctx.secrets`
|
|
- `ctx.assets`
|
|
- `ctx.activity`
|
|
- `ctx.state`
|
|
- `ctx.entities`
|
|
- `ctx.projects`
|
|
- `ctx.companies`
|
|
- `ctx.issues`
|
|
- `ctx.agents`
|
|
- `ctx.goals`
|
|
- `ctx.data`
|
|
- `ctx.actions`
|
|
- `ctx.streams`
|
|
- `ctx.tools`
|
|
- `ctx.metrics`
|
|
- `ctx.logger`
|
|
|
|
### UI surfaces to demonstrate
|
|
|
|
Surfaces defined in the SDK:
|
|
|
|
- `page`
|
|
- `settingsPage`
|
|
- `dashboardWidget`
|
|
- `sidebar`
|
|
- `sidebarPanel`
|
|
- `detailTab`
|
|
- `taskDetailView`
|
|
- `projectSidebarItem`
|
|
- `toolbarButton`
|
|
- `contextMenuItem`
|
|
- `commentAnnotation`
|
|
- `commentContextMenuItem`
|
|
|
|
### Current host confidence
|
|
|
|
Confirmed or strongly indicated as mounted in the current app:
|
|
|
|
- `page`
|
|
- `settingsPage`
|
|
- `dashboardWidget`
|
|
- `detailTab`
|
|
- `projectSidebarItem`
|
|
- comment surfaces
|
|
- launcher infrastructure
|
|
|
|
Need explicit validation before claiming full demo coverage:
|
|
|
|
- `sidebar`
|
|
- `sidebarPanel`
|
|
- `taskDetailView`
|
|
- `toolbarButton` as direct slot, distinct from launcher placement
|
|
- `contextMenuItem` as direct slot, distinct from comment menu and launcher placement
|
|
|
|
The implementation should keep a small validation checklist for these before we call the plugin "complete".
|
|
|
|
## Plugin Concept
|
|
|
|
The plugin should be named:
|
|
|
|
- display name: `Kitchen Sink (Example)`
|
|
- package: `@paperclipai/plugin-kitchen-sink-example`
|
|
- plugin id: `paperclip.kitchen-sink-example` or `paperclip-kitchen-sink-example`
|
|
|
|
Recommendation: use `paperclip-kitchen-sink-example` to match current in-repo example naming style.
|
|
|
|
Category mix:
|
|
|
|
- `ui`
|
|
- `automation`
|
|
- `workspace`
|
|
- `connector`
|
|
|
|
That is intentionally broad because the point is coverage.
|
|
|
|
## UX Shape
|
|
|
|
The plugin should have one main full-page demo console plus smaller satellites on other surfaces.
|
|
|
|
### 1. Plugin page
|
|
|
|
Primary route: the plugin `page` surface should be the central dashboard for all demos.
|
|
|
|
Recommended page sections:
|
|
|
|
- `Overview`
|
|
- what this plugin demonstrates
|
|
- current capabilities granted
|
|
- current host context
|
|
- `UI Surfaces`
|
|
- links explaining where each other surface should appear
|
|
- `Data + Actions`
|
|
- buttons and forms for bridge-driven worker demos
|
|
- `Events + Streams`
|
|
- emit event
|
|
- watch event log
|
|
- stream demo output
|
|
- `Paperclip Domain APIs`
|
|
- companies
|
|
- projects/workspaces
|
|
- issues
|
|
- goals
|
|
- agents
|
|
- `Local Workspace + Process`
|
|
- file listing
|
|
- file read/write scratch area
|
|
- child process demo
|
|
- `Jobs + Webhooks + Tools`
|
|
- job status
|
|
- webhook URL and recent deliveries
|
|
- declared tools
|
|
- `State + Entities + Assets`
|
|
- scoped state editor
|
|
- plugin entity inspector
|
|
- upload/generated asset demo
|
|
- `Observability`
|
|
- metrics written
|
|
- activity log samples
|
|
- latest worker logs
|
|
|
|
### 2. Dashboard widget
|
|
|
|
A compact widget on the main dashboard should show:
|
|
|
|
- plugin health
|
|
- count of demos exercised
|
|
- recent event/stream activity
|
|
- shortcut to the full plugin page
|
|
|
|
### 3. Project sidebar item
|
|
|
|
Add a `Kitchen Sink` link under each project that deep-links into a project-scoped plugin tab.
|
|
|
|
### 4. Detail tabs
|
|
|
|
Use detail tabs to demonstrate entity-context rendering on:
|
|
|
|
- `project`
|
|
- `issue`
|
|
- `agent`
|
|
- `goal`
|
|
|
|
Each tab should show:
|
|
|
|
- the host context it received
|
|
- the relevant entity fetch via worker bridge
|
|
- one small action scoped to that entity
|
|
|
|
### 5. Comment surfaces
|
|
|
|
Use issue comment demos to prove comment-specific extension points:
|
|
|
|
- `commentAnnotation`
|
|
- render parsed metadata below each comment
|
|
- show comment id, issue id, and a small derived status
|
|
- `commentContextMenuItem`
|
|
- add a menu action like `Copy Context To Kitchen Sink`
|
|
- action writes a plugin entity or state record for later inspection
|
|
|
|
### 6. Settings page
|
|
|
|
Custom `settingsPage` should be intentionally simple and operational:
|
|
|
|
- `About`
|
|
- `Danger / Trust Model`
|
|
- demo toggles
|
|
- local process defaults
|
|
- workspace scratch-path behavior
|
|
- secret reference inputs
|
|
- event/job/webhook sample config
|
|
|
|
This plugin should also keep the generic plugin settings `Status` tab useful by writing health, logs, and metrics.
|
|
|
|
## Feature Matrix
|
|
|
|
Each implemented worker API should have a visible demo.
|
|
|
|
### `ctx.config`
|
|
|
|
Demo:
|
|
|
|
- read live config
|
|
- show config JSON
|
|
- react to config changes without restart where possible
|
|
|
|
### `ctx.events`
|
|
|
|
Demos:
|
|
|
|
- emit a plugin event
|
|
- subscribe to plugin events
|
|
- subscribe to a core Paperclip event such as `issue.created`
|
|
- show recent received events in a timeline
|
|
|
|
### `ctx.jobs`
|
|
|
|
Demos:
|
|
|
|
- one scheduled heartbeat-style demo job
|
|
- one manual run button from the UI if host supports manual job trigger
|
|
- show last run result and timestamps
|
|
|
|
### `ctx.launchers`
|
|
|
|
Demos:
|
|
|
|
- declare launchers in manifest
|
|
- optionally register one runtime launcher from the worker
|
|
- show launcher metadata on the plugin page
|
|
|
|
### `ctx.http`
|
|
|
|
Demo:
|
|
|
|
- make a simple outbound GET request to a safe endpoint
|
|
- show status code, latency, and JSON result
|
|
|
|
Recommendation: default to a Paperclip-local endpoint or a stable public echo endpoint to avoid flaky docs.
|
|
|
|
### `ctx.secrets`
|
|
|
|
Demo:
|
|
|
|
- operator enters a secret reference in config
|
|
- plugin resolves it on demand
|
|
- UI only shows masked result length / success status, never raw secret
|
|
|
|
### `ctx.assets`
|
|
|
|
Demos:
|
|
|
|
- generate a text asset from the UI
|
|
- optionally upload a tiny JSON blob or screenshot-like text file
|
|
- show returned asset URL
|
|
|
|
### `ctx.activity`
|
|
|
|
Demo:
|
|
|
|
- button to write a plugin activity log entry against current company/entity
|
|
|
|
### `ctx.state`
|
|
|
|
Demos:
|
|
|
|
- instance-scoped state
|
|
- company-scoped state
|
|
- project-scoped state
|
|
- issue-scoped state
|
|
- delete/reset controls
|
|
|
|
Use a small state inspector/editor on the plugin page.
|
|
|
|
### `ctx.entities`
|
|
|
|
Demos:
|
|
|
|
- create plugin-owned sample records
|
|
- list/filter them
|
|
- show one realistic use case such as "copied comments" or "demo sync records"
|
|
|
|
### `ctx.projects`
|
|
|
|
Demos:
|
|
|
|
- list projects
|
|
- list project workspaces
|
|
- resolve primary workspace
|
|
- resolve workspace for issue
|
|
|
|
### `ctx.companies`
|
|
|
|
Demo:
|
|
|
|
- list companies and show current selected company
|
|
|
|
### `ctx.issues`
|
|
|
|
Demos:
|
|
|
|
- list issues in current company
|
|
- create issue
|
|
- update issue status/title
|
|
- list comments
|
|
- create comment
|
|
|
|
### `ctx.agents`
|
|
|
|
Demos:
|
|
|
|
- list agents
|
|
- invoke one agent with a test prompt
|
|
- pause/resume where safe
|
|
|
|
Agent mutation controls should be behind an explicit warning.
|
|
|
|
### `ctx.agents.sessions`
|
|
|
|
Demos:
|
|
|
|
- create agent chat session
|
|
- send message
|
|
- stream events back to the UI
|
|
- close session
|
|
|
|
This is a strong candidate for the best "wow" demo on the plugin page.
|
|
|
|
### `ctx.goals`
|
|
|
|
Demos:
|
|
|
|
- list goals
|
|
- create goal
|
|
- update status/title
|
|
|
|
### `ctx.data`
|
|
|
|
Use throughout the plugin for all read-side bridge demos.
|
|
|
|
### `ctx.actions`
|
|
|
|
Use throughout the plugin for all mutation-side bridge demos.
|
|
|
|
### `ctx.streams`
|
|
|
|
Demos:
|
|
|
|
- live event log stream
|
|
- token-style stream from an agent session relay
|
|
- fake progress stream for a long-running action
|
|
|
|
### `ctx.tools`
|
|
|
|
Demos:
|
|
|
|
- declare 2-3 simple agent tools
|
|
- tool 1: echo/diagnostics
|
|
- tool 2: project/workspace summary
|
|
- tool 3: create issue or write plugin state
|
|
|
|
The plugin page should list declared tools and show example input payloads.
|
|
|
|
### `ctx.metrics`
|
|
|
|
Demo:
|
|
|
|
- write a sample metric on each major demo action
|
|
- surface a small recent metrics table in the plugin page
|
|
|
|
### `ctx.logger`
|
|
|
|
Demo:
|
|
|
|
- every action logs structured entries
|
|
- plugin settings `Status` page then doubles as the log viewer
|
|
|
|
## Local Workspace And Process Demos
|
|
|
|
The plugin SDK intentionally leaves file/process operations to the plugin itself once it has workspace metadata.
|
|
|
|
The kitchen-sink plugin should demonstrate that explicitly.
|
|
|
|
### Workspace demos
|
|
|
|
- list files from a selected workspace
|
|
- read a file
|
|
- write to a plugin-owned scratch file
|
|
- optionally search files with `rg` if available
|
|
|
|
### Process demos
|
|
|
|
- run a short-lived command like `pwd`, `ls`, or `git status`
|
|
- stream stdout/stderr back to UI
|
|
- show exit code and timing
|
|
|
|
Important safeguards:
|
|
|
|
- default commands must be read-only
|
|
- no shell interpolation from arbitrary free-form input in v1
|
|
- provide a curated command list or a strongly validated command form
|
|
- clearly label this area as local-only and trusted-only
|
|
|
|
## Proposed Manifest Coverage
|
|
|
|
The plugin should aim to declare:
|
|
|
|
- `page`
|
|
- `settingsPage`
|
|
- `dashboardWidget`
|
|
- `detailTab` for `project`, `issue`, `agent`, `goal`
|
|
- `projectSidebarItem`
|
|
- `commentAnnotation`
|
|
- `commentContextMenuItem`
|
|
|
|
Then, after host validation, add if supported:
|
|
|
|
- `sidebar`
|
|
- `sidebarPanel`
|
|
- `taskDetailView`
|
|
- `toolbarButton`
|
|
- `contextMenuItem`
|
|
|
|
It should also declare one or more `ui.launchers` entries to exercise launcher behavior independently of slot rendering.
|
|
|
|
## Proposed Package Layout
|
|
|
|
New package:
|
|
|
|
- `packages/plugins/examples/plugin-kitchen-sink-example/`
|
|
|
|
Expected files:
|
|
|
|
- `package.json`
|
|
- `README.md`
|
|
- `tsconfig.json`
|
|
- `src/index.ts`
|
|
- `src/manifest.ts`
|
|
- `src/worker.ts`
|
|
- `src/ui/index.tsx`
|
|
- `src/ui/components/...`
|
|
- `src/ui/hooks/...`
|
|
- `src/lib/...`
|
|
- optional `scripts/build-ui.mjs` if UI bundling needs esbuild
|
|
|
|
## Proposed Internal Architecture
|
|
|
|
### Worker modules
|
|
|
|
Recommended split:
|
|
|
|
- `src/worker.ts`
|
|
- plugin definition and wiring
|
|
- `src/worker/data.ts`
|
|
- `ctx.data.register(...)`
|
|
- `src/worker/actions.ts`
|
|
- `ctx.actions.register(...)`
|
|
- `src/worker/events.ts`
|
|
- event subscriptions and event log buffer
|
|
- `src/worker/jobs.ts`
|
|
- scheduled job handlers
|
|
- `src/worker/tools.ts`
|
|
- tool declarations and handlers
|
|
- `src/worker/local-runtime.ts`
|
|
- file/process demos
|
|
- `src/worker/demo-store.ts`
|
|
- helpers for state/entities/assets/metrics
|
|
|
|
### UI modules
|
|
|
|
Recommended split:
|
|
|
|
- `src/ui/index.tsx`
|
|
- exported slot components
|
|
- `src/ui/page/KitchenSinkPage.tsx`
|
|
- `src/ui/settings/KitchenSinkSettingsPage.tsx`
|
|
- `src/ui/widgets/KitchenSinkDashboardWidget.tsx`
|
|
- `src/ui/tabs/ProjectKitchenSinkTab.tsx`
|
|
- `src/ui/tabs/IssueKitchenSinkTab.tsx`
|
|
- `src/ui/tabs/AgentKitchenSinkTab.tsx`
|
|
- `src/ui/tabs/GoalKitchenSinkTab.tsx`
|
|
- `src/ui/comments/KitchenSinkCommentAnnotation.tsx`
|
|
- `src/ui/comments/KitchenSinkCommentMenuItem.tsx`
|
|
- `src/ui/shared/...`
|
|
|
|
## Configuration Schema
|
|
|
|
The plugin should have a substantial but understandable `instanceConfigSchema`.
|
|
|
|
Recommended config fields:
|
|
|
|
- `enableDangerousDemos`
|
|
- `enableWorkspaceDemos`
|
|
- `enableProcessDemos`
|
|
- `showSidebarEntry`
|
|
- `showSidebarPanel`
|
|
- `showProjectSidebarItem`
|
|
- `showCommentAnnotation`
|
|
- `showCommentContextMenuItem`
|
|
- `showToolbarLauncher`
|
|
- `defaultDemoCompanyId` optional
|
|
- `secretRefExample`
|
|
- `httpDemoUrl`
|
|
- `processAllowedCommands`
|
|
- `workspaceScratchSubdir`
|
|
|
|
Defaults should keep risky behavior off.
|
|
|
|
## Safety Defaults
|
|
|
|
Default posture:
|
|
|
|
- UI and read-only demos on
|
|
- mutating domain demos on but explicitly labeled
|
|
- process demos off by default
|
|
- no arbitrary shell input by default
|
|
- no raw secret rendering ever
|
|
|
|
## Phased Build Plan
|
|
|
|
### Phase 1: Core plugin skeleton
|
|
|
|
- scaffold package
|
|
- add manifest, worker, UI entrypoints
|
|
- add README
|
|
- make it appear in bundled examples list
|
|
|
|
### Phase 2: Core, confirmed UI surfaces
|
|
|
|
- plugin page
|
|
- settings page
|
|
- dashboard widget
|
|
- project sidebar item
|
|
- detail tabs
|
|
|
|
### Phase 3: Core worker APIs
|
|
|
|
- config
|
|
- state
|
|
- entities
|
|
- companies/projects/issues/goals
|
|
- data/actions
|
|
- metrics/logger/activity
|
|
|
|
### Phase 4: Real-time and automation APIs
|
|
|
|
- streams
|
|
- events
|
|
- jobs
|
|
- webhooks
|
|
- agent sessions
|
|
- tools
|
|
|
|
### Phase 5: Local trusted runtime demos
|
|
|
|
- workspace file demos
|
|
- child process demos
|
|
- guarded by config
|
|
|
|
### Phase 6: Secondary UI surfaces
|
|
|
|
- comment annotation
|
|
- comment context menu item
|
|
- launchers
|
|
|
|
### Phase 7: Validation-only surfaces
|
|
|
|
Validate whether the current host truly mounts:
|
|
|
|
- `sidebar`
|
|
- `sidebarPanel`
|
|
- `taskDetailView`
|
|
- direct-slot `toolbarButton`
|
|
- direct-slot `contextMenuItem`
|
|
|
|
If mounted, add demos.
|
|
If not mounted, document them as SDK-defined but host-pending.
|
|
|
|
## Documentation Deliverables
|
|
|
|
The plugin should ship with a README that includes:
|
|
|
|
- what it demonstrates
|
|
- which surfaces are local-only
|
|
- how to install it
|
|
- where each UI surface should appear
|
|
- a mapping from demo card to SDK API
|
|
|
|
It should also be referenced from plugin docs as the "reference everything plugin".
|
|
|
|
## Testing And Verification
|
|
|
|
Minimum verification:
|
|
|
|
- package typecheck/build
|
|
- install from bundled example list
|
|
- page loads
|
|
- widget appears
|
|
- project tab appears
|
|
- comment surfaces render
|
|
- settings page loads
|
|
- key actions succeed
|
|
|
|
Recommended manual checklist:
|
|
|
|
- create issue from plugin
|
|
- create goal from plugin
|
|
- emit and receive plugin event
|
|
- stream action output
|
|
- open agent session and receive streamed reply
|
|
- upload an asset
|
|
- write plugin activity log
|
|
- run a safe local process demo
|
|
|
|
## Open Questions
|
|
|
|
1. Should the process demo remain curated-command-only in the first pass?
|
|
Recommendation: yes.
|
|
|
|
2. Should the plugin create throwaway "kitchen sink demo" issues/goals automatically?
|
|
Recommendation: no. Make creation explicit.
|
|
|
|
3. Should we expose unsupported-but-typed surfaces in the UI even if host mounting is not wired?
|
|
Recommendation: yes, but label them as `SDK-defined / host validation pending`.
|
|
|
|
4. Should agent mutation demos include pause/resume by default?
|
|
Recommendation: probably yes, but behind a warning block.
|
|
|
|
5. Should this plugin be treated as a supported regression harness in CI later?
|
|
Recommendation: yes. Long term, this should be the plugin-runtime smoke test package.
|
|
|
|
## Recommended Next Step
|
|
|
|
If this plan looks right, the next implementation pass should start by building only:
|
|
|
|
- package skeleton
|
|
- page
|
|
- settings page
|
|
- dashboard widget
|
|
- one project detail tab
|
|
- one issue detail tab
|
|
- the basic worker/action/data/state/event scaffolding
|
|
|
|
That is enough to lock the architecture before filling in every demo surface.
|