paperclip/doc/plans/2026-03-13-plugin-kitchen-sink-example.md

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.