The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
plugin spec draft ideas v0
Dottadf0f101fbd4e
diff --git a/doc/plugins/PLUGIN_SPEC.md b/doc/plugins/PLUGIN_SPEC.mdnew file mode 100644index 0000000000..5c3d399352--- /dev/null+++ b/doc/plugins/PLUGIN_SPEC.md@@ -0,0 +1,1140 @@+# Paperclip Plugin System Specification++Status: proposed complete spec for the post-V1 plugin system++This document is the complete specification for Paperclip's plugin and extension architecture.+It expands the brief plugin notes in [doc/SPEC.md](../SPEC.md) and should be read alongside the comparative analysis in [doc/plugins/ideas-from-opencode.md](./ideas-from-opencode.md).++This is not part of the V1 implementation contract in [doc/SPEC-implementation.md](../SPEC-implementation.md).+It is the full target architecture for the plugin system that should follow V1.++## 1. Scope++This spec covers:++- plugin packaging and installation+- runtime model+- trust model+- capability system+- UI extension surfaces+- event, job, and webhook surfaces+- workspace-oriented extension surfaces+- Postgres persistence for extensions+- operator workflows+- compatibility and upgrade rules++This spec does not cover:++- a public marketplace+- cloud/SaaS multi-tenancy+- arbitrary third-party schema migrations in the first plugin version+- arbitrary frontend bundle injection in the first plugin version++## 2. Core Assumptions++Paperclip plugin design is based on the following assumptions:++1. Paperclip is single-tenant and self-hosted.+2. Plugin installation is global to the instance.+3. "Companies" remain core Paperclip business objects, but they are not plugin trust boundaries.+4. Board governance, approval gates, budget hard-stops, and core task invariants remain owned by Paperclip core.+5. Projects already have a real workspace model via `project_workspaces`, and local/runtime plugins should build on that instead of inventing a separate workspace abstraction.++## 3. Goals++The plugin system must:++1. Let operators install global instance-wide plugins.+2. Let plugins add major capabilities without editing Paperclip core.+3. Keep core governance and auditing intact.+4. Support both local/runtime plugins and external SaaS connectors.+5. Support future plugin categories such as:+ - new agent adapters+ - revenue tracking+ - knowledge base+ - issue tracker sync+ - metrics/dashboards+ - file/project tooling+6. Use simple, explicit, typed contracts.+7. Keep failures isolated so one plugin does not crash the entire instance.++## 4. Non-Goals++The first plugin system must not:++1. Allow arbitrary plugins to override core routes or core invariants.+2. Allow arbitrary plugins to mutate approval, auth, issue checkout, or budget enforcement logic.+3. Allow arbitrary third-party plugins to run free-form DB migrations.+4. Depend on project-local plugin folders such as `.paperclip/plugins`.+5. Depend on automatic install-and-execute behavior at server startup from arbitrary config files.++## 5. Terminology++### 5.1 Instance++The single Paperclip deployment an operator installs and controls.++### 5.2 Company++A first-class Paperclip business object inside the instance.++### 5.3 Project Workspace++A workspace attached to a project through `project_workspaces`.+This is the primary local runtime anchor for file, terminal, git, and process tooling.++### 5.4 Platform Module++A trusted in-process extension loaded directly by Paperclip core.++Examples:++- agent adapters+- storage providers+- secret providers+- run-log backends++### 5.5 Plugin++An installable instance-wide extension package loaded through the Paperclip plugin runtime.++Examples:++- Linear sync+- GitHub Issues sync+- Grafana widgets+- Stripe revenue sync+- file browser+- terminal+- git workflow++### 5.6 Plugin Worker++The runtime process used for a plugin.+In this spec, third-party plugins run out-of-process by default.++### 5.7 Capability++A named permission the host grants to a plugin.+Plugins may only call host APIs that are covered by granted capabilities.++## 6. Extension Classes++Paperclip has two extension classes.++## 6.1 Platform Modules++Platform modules are:++- trusted+- in-process+- host-integrated+- low-level++They use explicit registries, not the general plugin worker protocol.++Platform module surfaces:++- `registerAgentAdapter()`+- `registerStorageProvider()`+- `registerSecretProvider()`+- `registerRunLogStore()`+- future `registerWorkspaceRuntime()` if needed++Platform modules are the right place for:++- new agent adapter packages+- new storage backends+- new secret backends+- other host-internal systems that need direct process or DB integration++## 6.2 Plugins++Plugins are:++- globally installed per instance+- loaded through the plugin runtime+- additive+- capability-gated+- isolated from core via a stable SDK and host protocol++Plugin categories:++- `connector`+- `workspace`+- `automation`+- `ui`++A plugin may declare more than one category.++## 7. Project Workspaces Are The Local Tooling Anchor++Paperclip already has a concrete workspace model:++- projects expose `workspaces`+- projects expose `primaryWorkspace`+- the database contains `project_workspaces`+- project routes already manage workspaces+- heartbeat resolution already prefers project workspaces before falling back to task-session or agent-home workspaces++Therefore:++1. File plugins should browse project workspaces first.+2. Terminal sessions should launch against project workspaces by default.+3. Git plugins should treat the selected project workspace as the repo root anchor.+4. Process/server tracking should attach to project workspaces whenever possible.+5. Issue and agent views may deep-link into project workspace context.++Project workspaces may exist in two modes:++- local directory mode: `cwd` is present+- repo-only mode: `repoUrl` and optional `repoRef` exist, but there is no local `cwd`++Plugins must handle repo-only workspaces explicitly:++- they may show metadata+- they may show sync state+- they may not assume local file/PTY/git access until a real `cwd` exists++## 8. Installation Model++Plugin installation is global and operator-driven.++There is no per-company install table and no per-company enable/disable switch.++If a plugin needs business-object-specific mappings, those are stored as plugin configuration or plugin state.++Examples:++- one global Linear plugin install+- mappings from company A to Linear team X and company B to Linear team Y+- one global git plugin install+- per-project workspace state stored under `project_workspace`++## 8.1 On-Disk Layout++Plugins live under the Paperclip instance directory.++Suggested layout:++- `~/.paperclip/instances/default/plugins/package.json`+- `~/.paperclip/instances/default/plugins/node_modules/`+- `~/.paperclip/instances/default/plugins/.cache/`+- `~/.paperclip/instances/default/data/plugins/<plugin-id>/`++The package install directory and the plugin data directory are separate.++## 8.2 Operator Commands++Paperclip should add CLI commands:++- `pnpm paperclipai plugin list`+- `pnpm paperclipai plugin install <package[@version]>`+- `pnpm paperclipai plugin uninstall <plugin-id>`+- `pnpm paperclipai plugin upgrade <plugin-id> [version]`+- `pnpm paperclipai plugin doctor <plugin-id>`++These commands are instance-level operations.++## 8.3 Install Process++The install process is:++1. Resolve npm package and version.+2. Install into the instance plugin directory.+3. Read and validate plugin manifest.+4. Reject incompatible plugin API versions.+5. Display requested capabilities to the operator.+6. Persist install record in Postgres.+7. Start plugin worker and run health/validation.+8. Mark plugin `ready` or `error`.++## 9. Load Order And Precedence++Load order must be deterministic.++1. core platform modules+2. built-in first-party plugins+3. installed plugins sorted by:+ - explicit operator-configured order if present+ - otherwise manifest `id`++Rules:++- plugin contributions are additive by default+- plugins may not override core routes or core actions by name collision+- if two plugins contribute the same route slug or UI slot id, the host must reject startup or force the operator to resolve the collision explicitly++## 10. Package Contract++Each plugin package must export a manifest and a worker entrypoint.++Suggested package layout:++- `dist/manifest.js`+- `dist/worker.js`++Suggested `package.json` keys:++```json+{+ "name": "@paperclip/plugin-linear",+ "version": "0.1.0",+ "paperclipPlugin": {+ "manifest": "./dist/manifest.js",+ "worker": "./dist/worker.js"+ }+}+```++## 10.1 Manifest Shape++Normative manifest shape:++```ts+export interface PaperclipPluginManifestV1 {+ id: string;+ apiVersion: 1;+ version: string;+ displayName: string;+ description: string;+ categories: Array<"connector" | "workspace" | "automation" | "ui">;+ minimumPaperclipVersion?: string;+ capabilities: string[];+ entrypoints: {+ worker: string;+ };+ instanceConfigSchema?: JsonSchema;+ jobs?: PluginJobDeclaration[];+ webhooks?: PluginWebhookDeclaration[];+ ui?: PluginUiDeclaration;+}+```++Rules:++- `id` must be globally unique+- `id` should normally equal the npm package name+- `apiVersion` must match the host-supported plugin API version+- `capabilities` must be static and install-time visible+- config schema must be JSON Schema compatible++## 11. Runtime Model++## 11.1 Process Model++Third-party plugins run out-of-process by default.++Default runtime:++- Paperclip server starts one worker process per installed plugin+- the worker process is a Node process+- host and worker communicate over JSON-RPC on stdio++This design provides:++- failure isolation+- clearer logging boundaries+- easier resource limits+- a cleaner trust boundary than arbitrary in-process execution++## 11.2 Host Responsibilities++The host is responsible for:++- package install+- manifest validation+- capability enforcement+- process supervision+- job scheduling+- webhook routing+- activity log writes+- secret resolution+- workspace service enforcement+- UI route registration++## 11.3 Worker Responsibilities++The plugin worker is responsible for:++- validating its own config+- handling domain events+- handling scheduled jobs+- handling webhooks+- producing UI view models+- invoking host services through the SDK+- reporting health information++## 11.4 Failure Policy++If a worker fails:++- mark plugin status `error`+- surface error in plugin health UI+- keep the rest of the instance running+- retry start with bounded backoff+- do not drop other plugins or core services++## 12. Host-Worker Protocol++The host must support the following worker RPC methods.++Required methods:++- `initialize(input)`+- `health()`+- `shutdown()`++Optional methods:++- `validateConfig(input)`+- `onEvent(input)`+- `runJob(input)`+- `handleWebhook(input)`+- `getPageModel(input)`+- `getWidgetModel(input)`+- `getDetailTabModel(input)`+- `performAction(input)`++### 12.1 `initialize`++Called once on worker startup.++Input includes:++- plugin manifest+- resolved plugin config+- instance info+- host API version++### 12.2 `health`++Returns:++- status+- current error if any+- optional plugin-reported diagnostics++### 12.3 `validateConfig`++Runs after config changes and startup.++Returns:++- `ok`+- warnings+- errors++### 12.4 `onEvent`++Receives one typed Paperclip domain event.++Delivery semantics:++- at least once+- plugin must be idempotent+- no global ordering guarantee across all event types+- per-entity ordering is best effort but not guaranteed after retries++### 12.5 `runJob`++Runs a declared scheduled job.++The host provides:++- job key+- trigger source+- run id+- schedule metadata++### 12.6 `handleWebhook`++Receives inbound webhook payload routed by the host.++The host provides:++- endpoint key+- headers+- raw body+- parsed body if applicable+- request id++### 12.7 `getPageModel`++Returns a schema-driven view model for the plugin's main page.++### 12.8 `getWidgetModel`++Returns a schema-driven view model for a dashboard widget.++### 12.9 `getDetailTabModel`++Returns a schema-driven view model for a project, issue, agent, goal, or run detail tab.++### 12.10 `performAction`++Runs an explicit plugin action initiated by the board UI.++Examples:++- "resync now"+- "link GitHub issue"+- "create branch from issue"+- "restart process"++## 13. SDK Surface++Plugins do not talk to the DB directly.+Plugins do not read raw secret material from persisted config.+Plugins do not touch the filesystem directly outside the host services.++The SDK exposed to workers must provide typed host clients.++Required SDK clients:++- `ctx.config`+- `ctx.events`+- `ctx.jobs`+- `ctx.http`+- `ctx.secrets`+- `ctx.assets`+- `ctx.activity`+- `ctx.state`+- `ctx.entities`+- `ctx.projects`+- `ctx.issues`+- `ctx.agents`+- `ctx.goals`+- `ctx.workspace`+- `ctx.logger`++## 13.1 Example SDK Shape++```ts+export interface PluginContext {+ manifest: PaperclipPluginManifestV1;+ config: {+ get(): Promise<Record<string, unknown>>;+ };+ events: {+ on(name: string, fn: (event: unknown) => Promise<void>): void;+ };+ jobs: {+ register(key: string, input: { cron: string }, fn: (job: PluginJobContext) => Promise<void>): void;+ };+ state: {+ get(input: ScopeKey): Promise<unknown | null>;+ set(input: ScopeKey, value: unknown): Promise<void>;+ delete(input: ScopeKey): Promise<void>;+ };+ entities: {+ upsert(input: PluginEntityUpsert): Promise<void>;+ list(input: PluginEntityQuery): Promise<PluginEntityRecord[]>;+ };+ workspace: WorkspacePluginApi;+}+```++## 14. Capability Model++Capabilities are mandatory and static.+Every plugin declares them up front.++The host enforces capabilities in the SDK layer and refuses calls outside the granted set.++## 14.1 Capability Categories++### Data Read++- `companies.read`+- `projects.read`+- `project.workspaces.read`+- `issues.read`+- `issue.comments.read`+- `agents.read`+- `goals.read`+- `activity.read`+- `costs.read`++### Data Write++- `issues.create`+- `issues.update`+- `issue.comments.create`+- `assets.write`+- `assets.read`+- `activity.log.write`+- `metrics.write`++### Runtime / Integration++- `events.subscribe`+- `jobs.schedule`+- `webhooks.receive`+- `http.outbound`+- `secrets.read-ref`++### UI++- `instance.settings.register`+- `ui.sidebar.register`+- `ui.page.register`+- `ui.detailTab.register`+- `ui.dashboardWidget.register`+- `ui.action.register`++### Workspace++- `workspace.fs.read`+- `workspace.fs.write`+- `workspace.fs.stat`+- `workspace.fs.search`+- `workspace.pty.open`+- `workspace.pty.input`+- `workspace.pty.resize`+- `workspace.pty.terminate`+- `workspace.pty.subscribe`+- `workspace.git.status`+- `workspace.git.diff`+- `workspace.git.log`+- `workspace.git.branch.create`+- `workspace.git.commit`+- `workspace.git.worktree.create`+- `workspace.git.push`+- `workspace.process.register`+- `workspace.process.list`+- `workspace.process.read`+- `workspace.process.terminate`+- `workspace.process.restart`+- `workspace.process.logs.read`+- `workspace.http.probe`++## 14.2 Forbidden Capabilities++The host must not expose capabilities for:++- approval decisions+- budget override+- auth bypass+- issue checkout lock override+- direct DB access+- direct filesystem access outside approved workspace services++## 14.3 Upgrade Rules++If a plugin upgrade adds capabilities:++1. the host must mark the plugin `upgrade_pending`+2. the operator must explicitly approve the new capability set+3. the new version does not become `ready` until approval completes++## 15. Event System++The host must emit typed domain events that plugins may subscribe to.++Minimum event set:++- `company.created`+- `company.updated`+- `project.created`+- `project.updated`+- `project.workspace_created`+- `project.workspace_updated`+- `project.workspace_deleted`+- `issue.created`+- `issue.updated`+- `issue.comment.created`+- `agent.created`+- `agent.updated`+- `agent.status_changed`+- `agent.run.started`+- `agent.run.finished`+- `agent.run.failed`+- `agent.run.cancelled`+- `approval.created`+- `approval.decided`+- `cost_event.created`+- `activity.logged`++Each event must include:++- event id+- event type+- occurred at+- actor metadata when applicable+- primary entity metadata+- typed payload++## 16. Scheduled Jobs++Plugins may declare scheduled jobs in their manifest.++Job rules:++1. Each job has a stable `job_key`.+2. The host is the scheduler of record.+3. The host prevents overlapping execution of the same plugin/job combination unless explicitly allowed later.+4. Every job run is recorded in Postgres.+5. Failed jobs are retryable.++## 17. Webhooks++Plugins may declare webhook endpoints in their manifest.++Webhook route shape:++- `POST /api/plugins/:pluginId/webhooks/:endpointKey`++Rules:++1. The host owns the public route.+2. The worker receives the request body through `handleWebhook`.+3. Signature verification happens in plugin code using secret refs resolved by the host.+4. Every delivery is recorded.+5. Webhook handling must be idempotent.++## 18. UI Extension Model++The first plugin UI system is schema-driven.++The host renders plugin data using built-in UI components.+Plugins return view models, not arbitrary React bundles.++## 18.1 Global Operator Routes++- `/settings/plugins`+- `/settings/plugins/:pluginId`++These routes are instance-level.++## 18.2 Company-Context Routes++- `/:companyPrefix/plugins/:pluginId`++These routes exist because the board UI is organized around companies even though plugin installation is global.++## 18.3 Detail Tabs++Plugins may add tabs to:++- project detail+- issue detail+- agent detail+- goal detail+- run detail++Recommended route pattern:++- `/:companyPrefix/<entity>/:id?tab=<plugin-tab-id>`++## 18.4 Dashboard Widgets++Plugins may add cards or sections to the dashboard.++## 18.5 Sidebar Entries++Plugins may add sidebar links to:++- global plugin settings+- company-context plugin pages++## 18.6 Allowed View Model Types++The host should support a limited set of schema-rendered components:++- metric cards+- status lists+- tables+- timeseries charts+- markdown text+- key/value blocks+- action bars+- log views+- JSON/debug views++Arbitrary frontend bundle injection is explicitly out of scope for the first plugin system.++## 19. Workspace Service APIs++Workspace service APIs are the foundation for local tooling plugins.++All workspace APIs must route through the host and validate against known project workspace roots.++## 19.1 Project Workspace APIs++Required host APIs:++- list project workspaces+- get project primary workspace+- resolve project workspace from issue+- resolve current workspace from agent/run when available++## 19.2 File APIs++- read file+- write file+- stat path+- search path or filename+- list directory++All file APIs take a resolved workspace anchor plus a relative path.++## 19.3 PTY APIs++- open terminal session+- send input+- resize+- terminate+- subscribe to output++PTY sessions should default to the selected project workspace when one exists.++## 19.4 Git APIs++- status+- diff+- log+- branch create+- worktree create+- commit+- push++Git APIs require a local `cwd`.+If the workspace is repo-only, the host must reject local git operations until a local checkout exists.++## 19.5 Process APIs++- register process+- list processes+- read process metadata+- terminate+- restart+- read logs+- probe health endpoint++Process tracking should attach to `project_workspace` when possible.++## 20. Persistence And Postgres++## 20.1 Database Principles++1. Core Paperclip data stays in first-party tables.+2. Most plugin-owned data starts in generic extension tables.+3. Plugin data should scope to existing Paperclip objects before new tables are introduced.+4. Arbitrary third-party schema migrations are out of scope for the first plugin system.++## 20.2 Core Table Reuse++If data becomes part of the actual Paperclip product model, it should become a first-party table.++Examples:++- `project_workspaces` is already first-party+- if Paperclip later decides git state is core product data, it should become a first-party table too++## 20.3 Required Tables++### `plugins`++- `id` uuid pk+- `plugin_key` text unique not null+- `package_name` text not null+- `version` text not null+- `api_version` int not null+- `categories` text[] not null+- `manifest_json` jsonb not null+- `status` enum: `installed | ready | error | upgrade_pending`+- `install_order` int null+- `installed_at` timestamptz not null+- `updated_at` timestamptz not null+- `last_error` text null++Indexes:++- unique `plugin_key`+- `status`++### `plugin_config`++- `id` uuid pk+- `plugin_id` uuid fk `plugins.id` unique not null+- `config_json` jsonb not null+- `installed_at` timestamptz not null+- `updated_at` timestamptz not null+- `last_error` text null++### `plugin_state`++- `id` uuid pk+- `plugin_id` uuid fk `plugins.id` not null+- `scope_kind` enum: `instance | company | project | project_workspace | agent | issue | goal | run`+- `scope_id` uuid/text null+- `namespace` text not null+- `state_key` text not null+- `value_json` jsonb not null+- `updated_at` timestamptz not null++Constraints:++- unique `(plugin_id, scope_kind, scope_id, namespace, state_key)`++Examples:++- Linear external IDs keyed by `issue`+- GitHub sync cursors keyed by `project`+- file browser preferences keyed by `project_workspace`+- git branch metadata keyed by `project_workspace`+- process metadata keyed by `project_workspace` or `run`++### `plugin_jobs`++- `id` uuid pk+- `plugin_id` uuid fk `plugins.id` not null+- `scope_kind` enum nullable+- `scope_id` uuid/text null+- `job_key` text not null+- `schedule` text null+- `status` enum: `idle | queued | running | error`+- `next_run_at` timestamptz null+- `last_started_at` timestamptz null+- `last_finished_at` timestamptz null+- `last_succeeded_at` timestamptz null+- `last_error` text null++Constraints:++- unique `(plugin_id, scope_kind, scope_id, job_key)`++### `plugin_job_runs`++- `id` uuid pk+- `plugin_job_id` uuid fk `plugin_jobs.id` not null+- `plugin_id` uuid fk `plugins.id` not null+- `status` enum: `queued | running | succeeded | failed | cancelled`+- `trigger` enum: `schedule | manual | retry`+- `started_at` timestamptz null+- `finished_at` timestamptz null+- `error` text null+- `details_json` jsonb null++Indexes:++- `(plugin_id, started_at desc)`+- `(plugin_job_id, started_at desc)`++### `plugin_webhook_deliveries`++- `id` uuid pk+- `plugin_id` uuid fk `plugins.id` not null+- `scope_kind` enum nullable+- `scope_id` uuid/text null+- `endpoint_key` text not null+- `status` enum: `received | processed | failed | ignored`+- `request_id` text null+- `headers_json` jsonb null+- `body_json` jsonb null+- `received_at` timestamptz not null+- `handled_at` timestamptz null+- `response_code` int null+- `error` text null++Indexes:++- `(plugin_id, received_at desc)`+- `(plugin_id, endpoint_key, received_at desc)`++### `plugin_entities` (optional but recommended)++- `id` uuid pk+- `plugin_id` uuid fk `plugins.id` not null+- `entity_type` text not null+- `scope_kind` enum not null+- `scope_id` uuid/text null+- `external_id` text null+- `title` text null+- `status` text null+- `data_json` jsonb not null+- `created_at` timestamptz not null+- `updated_at` timestamptz not null++Indexes:++- `(plugin_id, entity_type, external_id)` unique when `external_id` is not null+- `(plugin_id, scope_kind, scope_id, entity_type)`++Use cases:++- imported Linear issues+- imported GitHub issues+- plugin-owned process records+- plugin-owned external metric bindings++## 20.4 Activity Log Changes++The activity log should extend `actor_type` to include `plugin`.++New actor enum:++- `agent`+- `user`+- `system`+- `plugin`++Plugin-originated mutations should write:++- `actor_type = plugin`+- `actor_id = <plugin-id>`++## 20.5 Plugin Migrations++The first plugin system does not allow arbitrary third-party migrations.++Later, if custom tables become necessary, the system may add a trusted-module-only migration path.++## 21. Secrets++Plugin config must never persist raw secret values.++Rules:++1. Plugin config stores secret refs only.+2. Secret refs resolve through the existing Paperclip secret provider system.+3. Plugin workers receive resolved secrets only at execution time.+4. Secret values must never be written to:+ - plugin config JSON+ - activity logs+ - webhook delivery rows+ - error messages++## 22. Auditing++All plugin-originated mutating actions must be auditable.++Minimum requirements:++- activity log entry for every mutation+- job run history+- webhook delivery history+- plugin health page+- install/upgrade history in `plugins`++## 23. Operator UX++## 23.1 Global Settings++Global plugin settings page must show:++- installed plugins+- versions+- status+- requested capabilities+- current errors+- install/upgrade/remove actions++## 23.2 Plugin Settings Page++Each plugin may expose:++- config form derived from `instanceConfigSchema`+- health details+- recent job history+- recent webhook history+- capability list++Route:++- `/settings/plugins/:pluginId`++## 23.3 Company-Context Plugin Page++Each plugin may expose a company-context main page:++- `/:companyPrefix/plugins/:pluginId`++This page is where board users do most day-to-day work.++## 24. Example Mappings++This spec directly supports the following plugin types:++- `@paperclip/plugin-workspace-files`+- `@paperclip/plugin-terminal`+- `@paperclip/plugin-git`+- `@paperclip/plugin-linear`+- `@paperclip/plugin-github-issues`+- `@paperclip/plugin-grafana`+- `@paperclip/plugin-runtime-processes`+- `@paperclip/plugin-stripe`++## 25. Compatibility And Versioning++Rules:++1. Host supports one or more explicit plugin API versions.+2. Plugin manifest declares exactly one `apiVersion`.+3. Host rejects unsupported versions at install time.+4. SDK packages are versioned with the host protocol.+5. Plugin upgrades are explicit operator actions.+6. Capability expansion requires explicit operator approval.++## 26. Recommended Delivery Order++## Phase 1++- plugin manifest+- install/list/remove/upgrade CLI+- global settings UI+- plugin process manager+- capability enforcement+- `plugins`, `plugin_config`, `plugin_state`, `plugin_jobs`, `plugin_job_runs`, `plugin_webhook_deliveries`+- event bus+- jobs+- webhooks+- settings page+- dashboard widget/page/tab schema rendering++This phase is enough for:++- Linear+- GitHub Issues+- Grafana+- Stripe++## Phase 2++- project workspace service built on `project_workspaces`+- file APIs+- PTY APIs+- git APIs+- process APIs+- project-context tabs for plugin pages++This phase is enough for:++- file browser+- terminal+- git workflow+- process/server tracking++## Phase 3++- optional `plugin_entities`+- richer action systems+- trusted-module migration path if truly needed+- optional richer frontend extension model+- plugin ecosystem/distribution work++## 27. Final Design Decision++Paperclip should not implement a generic in-process hook bag modeled directly after local coding tools.++Paperclip should implement:++- trusted platform modules for low-level host integration+- globally installed out-of-process plugins for additive instance-wide capabilities+- schema-driven UI contributions+- project workspace-based local tooling+- generic extension tables for most plugin state+- strict preservation of core governance and audit rules++That is the complete target design for the Paperclip plugin system.diff --git a/doc/plugins/ideas-from-opencode.md b/doc/plugins/ideas-from-opencode.mdnew file mode 100644index 0000000000..ac4077f7f3--- /dev/null+++ b/doc/plugins/ideas-from-opencode.md@@ -0,0 +1,1637 @@+# Plugin Ideas From OpenCode++Status: design report, not a V1 commitment++Paperclip V1 explicitly excludes a plugin framework in [doc/SPEC-implementation.md](../SPEC-implementation.md), but the long-horizon spec says the architecture should leave room for extensions. This report studies the `opencode` plugin system and translates the useful patterns into a Paperclip-shaped design.++Assumption for this document: Paperclip is a single-tenant operator-controlled instance. Plugin installation should therefore be global across the instance. "Companies" are still first-class Paperclip objects, but they are organizational records, not tenant-isolation boundaries for plugin trust or installation.++## Executive Summary++`opencode` has a real plugin system already. It is intentionally low-friction:++- plugins are plain JS/TS modules+- they load from local directories and npm packages+- they can hook many runtime events+- they can add custom tools+- they can extend provider auth flows+- they run in-process and can mutate runtime behavior directly++That model works well for a local coding tool. It should not be copied literally into Paperclip.++The main conclusion is:++- Paperclip should copy `opencode`'s typed SDK, deterministic loading, low authoring friction, and clear extension surfaces.+- Paperclip should not copy `opencode`'s trust model, project-local plugin loading, "override by name collision" behavior, or arbitrary in-process mutation hooks for core business logic.+- Paperclip should use multiple extension classes instead of one generic plugin bag:+ - trusted in-process modules for low-level platform concerns like agent adapters, storage providers, secret providers, and possibly run-log backends+ - out-of-process plugins for most third-party integrations like Linear, GitHub Issues, Grafana, Stripe, and schedulers+ - schema-driven UI contributions for dashboard widgets, settings panels, and company pages+ - a typed event bus plus scheduled jobs for automation++If Paperclip does this well, the examples you listed become straightforward:++- file browser / terminal / git workflow / child process tracking become workspace-runtime plugins built on first-party primitives+- Linear / GitHub / Grafana / Stripe become connector plugins+- future knowledge base and accounting features can also fit the same model++## Sources Examined++I cloned `anomalyco/opencode` and reviewed commit:++- `a965a062595403a8e0083e85770315d5dc9628ab`++Primary files reviewed:++- `https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/plugin/src/index.ts`+- `https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/plugin/src/tool.ts`+- `https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/plugin/index.ts`+- `https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/config/config.ts`+- `https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/tool/registry.ts`+- `https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/provider/auth.ts`+- `https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/web/src/content/docs/plugins.mdx`+- `https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/web/src/content/docs/custom-tools.mdx`+- `https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/web/src/content/docs/ecosystem.mdx`++Relevant Paperclip files reviewed for current extension seams:++- [server/src/adapters/registry.ts](../../server/src/adapters/registry.ts)+- [ui/src/adapters/registry.ts](../../ui/src/adapters/registry.ts)+- [server/src/storage/provider-registry.ts](../../server/src/storage/provider-registry.ts)+- [server/src/secrets/provider-registry.ts](../../server/src/secrets/provider-registry.ts)+- [server/src/services/run-log-store.ts](../../server/src/services/run-log-store.ts)+- [server/src/services/activity-log.ts](../../server/src/services/activity-log.ts)+- [doc/SPEC.md](../SPEC.md)+- [doc/SPEC-implementation.md](../SPEC-implementation.md)++## What OpenCode Actually Implements++## 1. Plugin authoring API++`opencode` exposes a small package, `@opencode-ai/plugin`, with a typed `Plugin` function and a typed `tool()` helper.++Core shape:++- a plugin is an async function that receives a context object+- the plugin returns a `Hooks` object+- hooks are optional+- plugins can also contribute tools and auth providers++The plugin init context includes:++- an SDK client+- current project info+- current directory+- current git worktree+- server URL+- Bun shell access++That is important: `opencode` gives plugins rich runtime power immediately, not a narrow capability API.++## 2. Hook model++The hook set is broad. It includes:++- event subscription+- config-time hook+- message hooks+- model parameter/header hooks+- permission decision hooks+- shell env injection+- tool execution before/after hooks+- tool definition mutation+- compaction prompt customization+- text completion transforms++The implementation pattern is very simple:++- core code constructs an `output` object+- each matching plugin hook runs sequentially+- hooks mutate the `output`+- final mutated output is used by core++This is elegant and easy to extend.++It is also extremely powerful. A plugin can change auth headers, model params, permission answers, tool inputs, tool descriptions, and shell environment.++## 3. Plugin discovery and load order++`opencode` supports two plugin sources:++- local files+- npm packages++Local directories:++- `~/.config/opencode/plugins/`+- `.opencode/plugins/`++Npm plugins:++- listed in config under `plugin: []`++Load order is deterministic and documented:++1. global config+2. project config+3. global plugin directory+4. project plugin directory++Important details:++- config arrays are concatenated rather than replaced+- duplicate plugin names are deduplicated with higher-precedence entries winning+- internal first-party plugins and default plugins are also loaded through the plugin pipeline++This gives `opencode` a real precedence model rather than "whatever loaded last by accident."++## 4. Dependency handling++For local config/plugin directories, `opencode` will:++- ensure a `package.json` exists+- inject `@opencode-ai/plugin`+- run `bun install`++That lets local plugins and local custom tools import dependencies.++This is excellent for local developer ergonomics.++It is not a safe default for an operator-controlled control plane server.++## 5. Error handling++Plugin load failures do not hard-crash the runtime by default.++Instead, `opencode`:++- logs the error+- publishes a session error event+- continues loading other plugins++That is a good operational pattern. One bad plugin should not brick the entire product unless the operator has explicitly configured it as required.++## 6. Tools are a first-class extension point++`opencode` has two ways to add tools:++- export tools directly from a plugin via `hook.tool`+- define local files in `.opencode/tools/` or global tools directories++The tool API is strong:++- tools have descriptions+- tools have Zod schemas+- tool execution gets context like session ID, message ID, directory, and worktree+- tools are merged into the same registry as built-in tools+- tool definitions themselves can be mutated by a `tool.definition` hook++The most aggressive part of the design:++- custom tools can override built-in tools by name++That is very powerful for a local coding assistant.+It is too dangerous for Paperclip core actions.++## 7. Auth is also a plugin surface++`opencode` allows plugins to register auth methods for providers.++A plugin can contribute:++- auth method metadata+- prompt flows+- OAuth flows+- API key flows+- request loaders that adapt provider behavior after auth succeeds++This is a strong pattern worth copying. Integrations often need custom auth UX and token handling.++## 8. Ecosystem evidence++The ecosystem page is the best proof that the model is working in practice.+Community plugins already cover:++- sandbox/workspace systems+- auth providers+- session headers / telemetry+- memory/context features+- scheduling+- notifications+- worktree helpers+- background agents+- monitoring++That validates the main thesis: a simple typed plugin API can create real ecosystem velocity.++## What OpenCode Gets Right++## 1. Separate plugin SDK from host runtime++This is one of the best parts of the design.++- plugin authors code against a clean public package+- host internals can evolve behind the loader+- runtime code and plugin code have a clean contract boundary++Paperclip should absolutely do this.++## 2. Deterministic loading and precedence++`opencode` is explicit about:++- where plugins come from+- how config merges+- what order wins++Paperclip should copy this discipline.++## 3. Low-ceremony authoring++A plugin author does not have to learn a giant framework.++- export async function+- return hooks+- optionally export tools++That simplicity matters.++## 4. Typed tool definitions++The `tool()` helper is excellent:++- typed+- schema-based+- easy to document+- easy for runtime validation++Paperclip should adopt this style for plugin actions, automations, and UI schemas.++## 5. Built-in features and plugins use similar shapes++`opencode` uses the same hook system for internal and external plugin-style behavior in several places.+That reduces special cases.++Paperclip can benefit from that with adapters, secret backends, storage providers, and connector modules.++## 6. Incremental extension, not giant abstraction upfront++`opencode` did not design a giant marketplace platform first.+It added concrete extension points that real features needed.++That is the correct mindset for Paperclip too.++## What Paperclip Should Not Copy Directly++## 1. In-process arbitrary plugin code as the default++`opencode` is basically a local agent runtime, so unsandboxed plugin execution is acceptable for its audience.++Paperclip is a control plane for an operator-managed instance with company objects.+The risk profile is different:++- secrets matter+- approval gates matter+- budgets matter+- mutating actions require auditability++Default third-party plugins should not run with unrestricted in-process access to server memory, DB handles, and secrets.++## 2. Project-local plugin loading++`opencode` has project-local plugin folders because the tool is centered around a codebase.++Paperclip is not project-scoped. It is instance-scoped.+The comparable unit is:++- instance-installed plugin package++Paperclip should not auto-load arbitrary code from a workspace repo like `.paperclip/plugins` or project directories.++## 3. Arbitrary mutation hooks on core business decisions++Hooks like:++- `permission.ask`+- `tool.execute.before`+- `chat.headers`+- `shell.env`++make sense in `opencode`.++For Paperclip, equivalent hooks into:++- approval decisions+- issue checkout semantics+- activity log behavior+- budget enforcement++would be a mistake.++Core invariants should stay in core code, not become hook-rewritable.++## 4. Override-by-name collision++Allowing a plugin to replace a built-in tool by name is useful in a local agent product.++Paperclip should not allow plugins to silently replace:++- core routes+- core mutating actions+- auth behaviors+- permission evaluators+- budget logic+- audit logic++Extension should be additive or explicitly delegated, never accidental shadowing.++## 5. Auto-install and execute from user config++`opencode`'s "install dependencies at startup" flow is ergonomic.+For Paperclip it would be risky because it combines:++- package installation+- code loading+- execution++inside the control-plane server startup path.++Paperclip should require an explicit operator install step.++## Why Paperclip Needs A Different Shape++The products are solving different problems.++| Topic | OpenCode | Paperclip |+|---|---|---|+| Primary unit | local project/worktree | single-tenant operator instance with company objects |+| Trust assumption | local power user on own machine | operator managing one trusted Paperclip instance |+| Failure blast radius | local session/runtime | entire company control plane |+| Extension style | mutate runtime behavior freely | preserve governance and auditability |+| UI model | local app can load local behavior | board UI must stay coherent and safe |+| Security model | host-trusted local plugins | needs capability boundaries and auditability |++That means Paperclip should borrow the good ideas from `opencode` but use a stricter architecture.++## Paperclip Already Has Useful Pre-Plugin Seams++Paperclip has several extension-like seams already:++- server adapter registry: [server/src/adapters/registry.ts](../../server/src/adapters/registry.ts)+- UI adapter registry: [ui/src/adapters/registry.ts](../../ui/src/adapters/registry.ts)+- storage provider registry: [server/src/storage/provider-registry.ts](../../server/src/storage/provider-registry.ts)+- secret provider registry: [server/src/secrets/provider-registry.ts](../../server/src/secrets/provider-registry.ts)+- pluggable run-log store seam: [server/src/services/run-log-store.ts](../../server/src/services/run-log-store.ts)+- activity log and live event emission: [server/src/services/activity-log.ts](../../server/src/services/activity-log.ts)++This is good news.+Paperclip does not need to invent extensibility from scratch.+It needs to unify and harden existing seams.++## Recommended Paperclip Plugin Model++## 1. Use multiple extension classes++Do not create one giant `hooks` object for everything.++Use distinct plugin classes with different trust models.++| Extension class | Examples | Runtime model | Trust level | Why |+|---|---|---|---|---|+| Platform module | agent adapters, storage providers, secret providers, run-log backends | in-process | highly trusted | tight integration, performance, low-level APIs |+| Connector plugin | Linear, GitHub Issues, Grafana, Stripe | out-of-process worker or sidecar | medium | external sync, safer isolation, clearer failure boundary |+| Workspace plugin | file browser, terminal, git workflow, child process/server tracking | mixed: core workspace services plus plugin descriptors | high | needs local OS/workspace primitives but should reuse core services |+| UI contribution | dashboard widgets, settings forms, company panels | schema-driven first, remote React later if needed | medium | safer than arbitrary frontend code |+| Automation plugin | alerts, schedulers, sync jobs, webhook processors | out-of-process | medium | event-driven automation is a natural plugin fit |++This split is the most important design recommendation in this report.++## 2. Keep low-level modules separate from third-party plugins++Paperclip already has this pattern implicitly:++- adapters are one thing+- storage providers are another+- secret providers are another++Keep that separation.++I would formalize it like this:++- `module` means trusted code loaded by the host for low-level runtime services+- `plugin` means integration code that talks to Paperclip through a typed plugin protocol and capability model++This avoids trying to force Stripe, a PTY terminal, and a new agent adapter into the same abstraction.++## 3. Prefer event-driven extensions over core-logic mutation++For third-party plugins, the primary API should be:++- subscribe to typed domain events+- read instance state, including company-bound business records when relevant+- register webhooks+- run scheduled jobs+- write plugin-owned state+- add additive UI surfaces+- invoke explicit Paperclip actions through the API++Do not make third-party plugins responsible for:++- deciding whether an approval passes+- intercepting issue checkout semantics+- rewriting activity log behavior+- overriding budget hard-stops++Those are core invariants.++## 4. Start with schema-driven UI contributions++Arbitrary third-party React bundles inside the board UI are possible later, but they should not be the first version.++First version should let plugins contribute:++- settings sections defined by JSON schema+- dashboard widgets with server-provided data+- sidebar entries with fixed shell rendering+- detail-page tabs that render plugin data through core UI components++Why:++- simpler to secure+- easier to keep visually coherent+- easier to preserve context and auditability+- easier to test++Later, if needed, Paperclip can support richer frontend extensions through versioned remote modules.++## 5. Make installation global and keep mappings/config separate++`opencode` is mostly user-level local config.+Paperclip should treat plugin installation as a global instance-level action.++Examples:++- install `@paperclip/plugin-linear` once+- make it available everywhere immediately+- optionally store mappings over Paperclip objects if one company maps to a different Linear team than another++## 6. Use project workspaces as the primary anchor for local tooling++Paperclip already has a concrete workspace model for projects:++- projects expose `workspaces` and `primaryWorkspace`+- the database already has `project_workspaces`+- project routes already support creating, updating, and deleting workspaces+- heartbeat resolution already prefers project workspaces before falling back to task-session or agent-home workspaces++That means local/runtime plugins should generally anchor themselves to projects first, not invent a parallel workspace model.++Practical guidance:++- file browser should browse project workspaces first+- terminal sessions should be launchable from a project workspace+- git should treat the project workspace as the repo root anchor+- dev server and child-process tracking should attach to project workspaces+- issue and agent views can still deep-link into the relevant project workspace context++In other words:++- `project` is the business object+- `project_workspace` is the local runtime anchor+- plugins should build on that instead of creating an unrelated workspace model first++## A Concrete SDK Shape For Paperclip++An intentionally narrow first pass could look like this:++```ts+import { definePlugin, z } from "@paperclipai/plugin-sdk";++export default definePlugin({+ id: "@paperclip/plugin-linear",+ version: "0.1.0",+ kind: ["connector", "ui"],+ capabilities: [+ "events.subscribe",+ "jobs.schedule",+ "http.outbound",+ "instance.settings",+ "dashboard.widget",+ "secrets.read-ref",+ ],+ instanceConfigSchema: z.object({+ linearBaseUrl: z.string().url().optional(),+ companyMappings: z.array(+ z.object({+ companyId: z.string(),+ teamId: z.string(),+ apiTokenSecretRef: z.string(),+ }),+ ).default([]),+ }),+ async register(ctx) {+ ctx.jobs.register("linear-pull", { cron: "*/5 * * * *" }, async (job) => {+ // sync Linear issues into plugin-owned state or explicit Paperclip entities+ });++ ctx.events.on("issue.created", async (event) => {+ // optional outbound sync+ });++ ctx.ui.registerDashboardWidget({+ id: "linear-health",+ title: "Linear",+ loader: async ({ companyId }) => ({ status: "ok" }),+ });+ },+});+```++The important point is not the exact syntax.+The important point is the contract shape:++- typed manifest+- explicit capabilities+- explicit global config with optional company mappings+- event subscriptions+- jobs+- additive UI contributions++## Recommended Core Extension Surfaces++## 1. Platform module surfaces++These should stay close to the current registry style.++Candidates:++- `registerAgentAdapter()`+- `registerStorageProvider()`+- `registerSecretProvider()`+- `registerRunLogStore()`+- maybe `registerWorkspaceRuntime()` later++These are trusted platform modules, not casual plugins.++## 2. Connector plugin surfaces++These are the best near-term plugin candidates.++Capabilities:++- subscribe to domain events+- define scheduled sync jobs+- expose plugin-specific API routes under `/api/plugins/:pluginId/...`+- use company secret refs+- write plugin state+- publish dashboard data+- log activity through core APIs++Examples:++- Linear issue sync+- GitHub issue sync+- Grafana dashboard cards+- Stripe MRR / subscription rollups++## 3. Workspace-runtime surfaces++Your local-ops examples need first-party primitives plus plugin contributions.++Examples:++- file browser+- terminal+- git workflow+- child process tracking+- local dev server tracking++These should not be arbitrary third-party code directly poking the host filesystem and PTY layer through ad-hoc hooks.+Instead, Paperclip should add first-party services such as:++- project workspace service built on `project_workspaces`+- PTY session service+- process registry+- git service+- dev-server registry++Then plugins can add:++- UI panels on top of those services+- automations+- annotations+- external sync logic++This keeps sensitive local-machine behavior centralized and auditable.++## 4. UI contribution surfaces++Recommended first version:++- dashboard widgets+- settings panels+- detail-page tabs+- sidebar sections+- action buttons that invoke plugin routes++Recommended later version:++- richer remote UI modules++Recommended never or only with extreme caution:++- arbitrary override of core pages+- arbitrary replacement of routing/auth/layout logic++## Governance And Safety Requirements++Any Paperclip plugin system has to preserve core control-plane invariants from the repo docs.++That means:++- plugin install is global to the instance+- "companies" remain business objects in the API and data model, not tenant boundaries+- approval gates remain core-owned+- budget hard-stops remain core-owned+- mutating actions are activity-logged+- secrets remain ref-based and redacted in logs++I would require the following for every plugin:++## 1. Capability declaration++Every plugin declares a static capability set such as:++- `companies.read`+- `issues.read`+- `issues.write`+- `events.subscribe`+- `jobs.schedule`+- `http.outbound`+- `webhooks.receive`+- `assets.read`+- `assets.write`+- `workspace.pty`+- `workspace.fs.read`+- `workspace.fs.write`+- `secrets.read-ref`++The board/operator sees this before installation.++## 2. Global installation++A plugin is installed once and becomes available across the instance.+If it needs mappings over specific Paperclip objects, those are plugin data, not enable/disable boundaries.++## 3. Activity logging++Plugin-originated mutations should flow through the same activity log mechanism, with actor identity like:++- `actor_type = system`+- `actor_id = plugin:@paperclip/plugin-linear`++or a dedicated `plugin` actor type if you want stronger semantics later.++## 4. Health and failure reporting++Each plugin should expose:++- enabled/disabled state+- last successful run+- last error+- recent webhook/job history++One broken plugin must not break the rest of the company.++## 5. Secret handling++Plugins should receive secret refs, not raw secret values in config persistence.+Resolution should go through the existing secret provider abstraction.++## 6. Resource limits++Plugins should have:++- timeout limits+- concurrency limits+- retry policies+- optional per-plugin budgets++This matters especially for sync connectors and workspace plugins.++## Data Model Additions To Consider++I would avoid "arbitrary third-party plugin-defined SQL migrations" in the first version.+That is too much power too early.++The right mental model is:++- reuse core tables when the data is clearly part of Paperclip itself+- use generic extension tables for most plugin-owned state+- only allow plugin-specific tables later, and only for trusted platform modules or a tightly controlled migration workflow++## Recommended Postgres Strategy For Extensions++### 1. Core tables stay core++If a concept is becoming part of Paperclip's actual product model, it should get a normal first-party table.++Examples:++- `project_workspaces` is already a core table because project workspaces are now part of Paperclip itself+- if a future "project git state" becomes a core feature rather than plugin-owned metadata, that should also be a first-party table++### 2. Most plugins should start in generic extension tables++For most plugins, the host should provide a few generic persistence tables and the plugin stores namespaced records there.++This keeps the system manageable:++- simpler migrations+- simpler backup/restore+- simpler portability story+- easier operator review+- fewer chances for plugin schema drift to break the instance++### 3. Scope plugin data to Paperclip objects before adding custom schemas++A lot of plugin data naturally hangs off existing Paperclip objects:++- project workspace plugin state should often scope to `project` or `project_workspace`+- issue sync state should scope to `issue`+- metrics widgets may scope to `company`, `project`, or `goal`+- process tracking may scope to `project_workspace`, `agent`, or `run`++That gives a good default keying model before introducing custom tables.++### 4. Add trusted module migrations later, not arbitrary plugin migrations now++If Paperclip eventually needs extension-owned tables, I would only allow that for:++- trusted first-party packages+- trusted platform modules+- maybe explicitly installed admin-reviewed plugins with pinned versions++I would not let random third-party plugins run free-form schema migrations on startup.++Instead, add a controlled mechanism later if it becomes necessary.++## Suggested baseline extension tables++## 1. `plugins`++Instance-level installation record.++Suggested fields:++- `id`+- `package_name`+- `version`+- `kind`+- `manifest_json`+- `installed_at`+- `status`++## 2. `plugin_config`++Instance-level plugin config.++Suggested fields:++- `id`+- `plugin_id`+- `config_json`+- `installed_at`+- `updated_at`+- `last_error`++## 3. `plugin_state`++Generic key/value state for plugins.++Suggested fields:++- `id`+- `plugin_id`+- `scope_kind` (`instance | company | project | project_workspace | agent | issue | goal | run`)+- `scope_id` nullable+- `namespace`+- `state_key`+- `value_json`+- `updated_at`++This is enough for many connectors before allowing custom tables.++Examples:++- Linear external IDs keyed by `issue`+- GitHub sync cursors keyed by `project`+- file browser preferences keyed by `project_workspace`+- git branch metadata keyed by `project_workspace`+- process metadata keyed by `project_workspace` or `run`++## 4. `plugin_jobs`++Scheduled job and run tracking.++Suggested fields:++- `id`+- `plugin_id`+- `scope_kind` nullable+- `scope_id` nullable+- `job_key`+- `status`+- `last_started_at`+- `last_finished_at`+- `last_error`++## 5. `plugin_webhook_deliveries`++If plugins expose webhooks, delivery history is worth storing.++Suggested fields:++- `id`+- `plugin_id`+- `scope_kind` nullable+- `scope_id` nullable+- `endpoint_key`+- `status`+- `received_at`+- `response_code`+- `error`++## 6. Maybe later: `plugin_entities`++If generic plugin state becomes too limiting, add a structured, queryable entity table for connector records before allowing arbitrary plugin migrations.++Suggested fields:++- `id`+- `plugin_id`+- `entity_type`+- `scope_kind`+- `scope_id`+- `external_id`+- `title`+- `status`+- `data_json`+- `updated_at`++This is a useful middle ground:++- much more queryable than opaque key/value state+- still avoids letting every plugin create its own relational schema immediately++## How The Requested Examples Map To This Model++| Use case | Best fit | Core primitives needed | Notes |+|---|---|---|---|+| File browser | workspace plugin + schema UI | project workspaces, file API, audit rules | best anchored on project detail pages |+| Terminal | workspace plugin + PTY service | project workspaces, PTY/session service, process limits, audit events | should launch against a project workspace by default |+| Git workflow | workspace plugin | project workspaces, git service, repo/worktree model | project workspace is the natural repo anchor |+| Linear issue tracking | connector plugin | jobs, webhooks, secret refs, issue sync API | very strong plugin candidate |+| GitHub issue tracking | connector plugin | jobs, webhooks, secret refs | very strong plugin candidate |+| Grafana metrics | connector plugin + dashboard widget | outbound HTTP, widget API | probably read-only first |+| Child process/server tracking | workspace plugin | project workspaces, process registry, server heartbeat model | should attach processes to project workspaces when possible |+| Stripe revenue tracking | connector plugin | secret refs, scheduled sync, company metrics API | strong plugin candidate and aligns with future spec direction |++# Plugin Examples++## Workspace File Browser++Package idea: `@paperclip/plugin-workspace-files`++This plugin lets the board inspect project workspaces, agent workspaces, generated artifacts, and issue-related files without dropping to the shell. It is useful for:++- browsing files inside project workspaces+- debugging what an agent changed+- reviewing generated outputs before approval+- attaching files from a workspace to issues+- understanding repo layout for a company+- inspecting agent home workspaces in local-trusted mode++### UX++- Settings page: `/settings/plugins/workspace-files`+- Main page: `/:companyPrefix/plugins/workspace-files`+- Project tab: `/:companyPrefix/projects/:projectId?tab=files`+- Optional issue tab: `/:companyPrefix/issues/:issueId?tab=files`+- Optional agent tab: `/:companyPrefix/agents/:agentId?tab=workspace`++Main screens and interactions:++- Plugin settings:+ - choose whether the plugin defaults to `project.primaryWorkspace`+ - choose which project workspaces are visible+ - choose whether file writes are allowed or read-only+ - choose whether hidden files are visible+- Main explorer page:+ - project picker at the top+ - workspace picker scoped to the selected project's `workspaces`+ - tree view on the left+ - file preview pane on the right+ - search box for filename/path search+ - actions: copy path, download file, attach to issue, open diff+- Project tab:+ - opens directly into the project's primary workspace+ - lets the board switch among all project workspaces+ - shows workspace metadata like `cwd`, `repoUrl`, and `repoRef`+- Issue tab:+ - resolves the issue's project and opens that project's workspace context+ - shows files linked to the issue+ - lets the board pull files from the project workspace into issue attachments+ - shows the path and last modified info for each linked file+- Agent tab:+ - shows the agent's current resolved workspace+ - if the run is attached to a project, links back to the project workspace view+ - lets the board inspect files the agent is currently touching++Core workflows:++- Board opens a project and browses its primary workspace files.+- Board switches from one project workspace to another when a project has multiple checkouts or repo references.+- Board opens an issue, attaches a generated artifact from the file browser, and leaves a review comment.+- Board opens an agent detail page to inspect the exact files behind a failing run.++### Hooks needed++Recommended capabilities and extension points:++- `instance.settings.register`+- `ui.sidebar.register`+- `ui.page.register`+- `ui.detailTab.register` for `project`, `issue`, and `agent`+- `projects.read`+- `project.workspaces.read`+- `workspace.fs.read`+- optional `workspace.fs.write`+- `workspace.fs.stat`+- `workspace.fs.search`+- optional `assets.write`+- `activity.log.write`++Optional event subscriptions:++- `events.subscribe(agent.run.started)`+- `events.subscribe(agent.run.finished)`+- `events.subscribe(issue.attachment.created)`++Important constraint:++- the plugin should never read arbitrary host paths directly+- it should treat project workspaces as the canonical local file roots when a project is present+- it should only use first-party workspace/file APIs that enforce approved workspace roots++## Workspace Terminal++Package idea: `@paperclip/plugin-terminal`++This plugin gives the board a controlled terminal UI for project workspaces and agent workspaces. It is useful for:++- debugging stuck runs+- verifying environment state+- running targeted manual commands+- watching long-running commands+- pairing a human operator with an agent workflow++### UX++- Settings page: `/settings/plugins/terminal`+- Main page: `/:companyPrefix/plugins/terminal`+- Project tab: `/:companyPrefix/projects/:projectId?tab=terminal`+- Optional agent tab: `/:companyPrefix/agents/:agentId?tab=terminal`+- Optional run tab: `/:companyPrefix/agents/:agentId/runs/:runId?tab=terminal`++Main screens and interactions:++- Plugin settings:+ - allowed shells and shell policy+ - whether commands are read-only, free-form, or allow-listed+ - whether terminals require an explicit operator confirmation before launch+ - whether new terminal sessions default to the project's primary workspace+- Terminal home page:+ - list of active terminal sessions+ - button to open a new session+ - project picker, then workspace picker from that project's workspaces+ - optional agent association+ - terminal panel with input, resize, and reconnect support+ - controls: interrupt, kill, clear, save transcript+- Project terminal tab:+ - opens a session already scoped to the project's primary workspace+ - lets the board switch among the project's configured workspaces+ - shows recent commands and related process/server state for that project+- Agent terminal tab:+ - opens a session already scoped to the agent's workspace+ - shows recent related runs and commands+- Run terminal tab:+ - lets the board inspect the environment around a specific failed run++Core workflows:++- Board opens a terminal against an agent workspace to reproduce a failing command.+- Board opens a project page and launches a terminal directly in that project's primary workspace.+- Board watches a long-running dev server or test command from the terminal page.+- Board kills or interrupts a runaway process from the same UI.++### Hooks needed++Recommended capabilities and extension points:++- `instance.settings.register`+- `ui.sidebar.register`+- `ui.page.register`+- `ui.detailTab.register` for `project`, `agent`, and `run`+- `projects.read`+- `project.workspaces.read`+- `workspace.pty.open`+- `workspace.pty.input`+- `workspace.pty.resize`+- `workspace.pty.terminate`+- `workspace.pty.subscribe`+- `workspace.process.read`+- `activity.log.write`++Optional event subscriptions:++- `events.subscribe(agent.run.started)`+- `events.subscribe(agent.run.failed)`+- `events.subscribe(agent.run.cancelled)`++Important constraint:++- shell spawning must stay in a first-party PTY service+- the plugin should orchestrate and render sessions, not spawn raw host processes by itself++## Git Workflow++Package idea: `@paperclip/plugin-git`++This plugin adds repo-aware workflow tooling around issues and workspaces. It is useful for:++- branch creation tied to issues+- quick diff review+- commit and worktree visibility+- PR preparation+- treating the project's primary workspace as the canonical repo anchor+- seeing whether an agent's workspace is clean or dirty++### UX++- Settings page: `/settings/plugins/git`+- Main page: `/:companyPrefix/plugins/git`+- Project tab: `/:companyPrefix/projects/:projectId?tab=git`+- Optional issue tab: `/:companyPrefix/issues/:issueId?tab=git`+- Optional agent tab: `/:companyPrefix/agents/:agentId?tab=git`++Main screens and interactions:++- Plugin settings:+ - branch naming template+ - optional remote provider token secret ref+ - whether write actions are enabled or read-only+ - whether the plugin always uses `project.primaryWorkspace` unless a different project workspace is chosen+- Git overview page:+ - project picker and workspace picker+ - current branch+ - ahead/behind status+ - dirty files summary+ - recent commits+ - active worktrees+ - actions: refresh, create branch, create worktree, stage all, commit, open diff+- Project tab:+ - opens in the project's primary workspace+ - shows workspace metadata and repo binding (`cwd`, `repoUrl`, `repoRef`)+ - shows branch, diff, and commit history for that project workspace+- Issue tab:+ - resolves the issue's project and uses that project's workspace context+ - "create branch from issue" action+ - diff view scoped to the project's selected workspace+ - link branch/worktree metadata to the issue+- Agent tab:+ - shows the agent's branch, worktree, and dirty state+ - shows recent commits produced by that agent+ - if the agent is working inside a project workspace, links back to the project git tab++Core workflows:++- Board creates a branch from an issue and ties it to the project's primary workspace.+- Board opens a project page and reviews the diff for that project's workspace without leaving Paperclip.+- Board reviews the diff after a run without leaving Paperclip.+- Board opens a worktree list to understand parallel branches across agents.++### Hooks needed++Recommended capabilities and extension points:++- `instance.settings.register`+- `ui.sidebar.register`+- `ui.page.register`+- `ui.detailTab.register` for `project`, `issue`, and `agent`+- `ui.action.register`+- `projects.read`+- `project.workspaces.read`+- `workspace.git.status`+- `workspace.git.diff`+- `workspace.git.log`+- `workspace.git.branch.create`+- optional `workspace.git.commit`+- optional `workspace.git.worktree.create`+- optional `workspace.git.push`+- `activity.log.write`++Optional event subscriptions:++- `events.subscribe(issue.created)`+- `events.subscribe(issue.updated)`+- `events.subscribe(agent.run.finished)`++Important constraint:++- GitHub/GitLab PR creation should likely live in a separate connector plugin rather than overloading the local git plugin++## Linear Issue Tracking++Package idea: `@paperclip/plugin-linear`++This plugin syncs Paperclip work with Linear. It is useful for:++- importing backlog from Linear+- linking Paperclip issues to Linear issues+- syncing status, comments, and assignees+- mapping company goals/projects to external product planning+- giving board operators a single place to see sync health++### UX++- Settings page: `/settings/plugins/linear`+- Main page: `/:companyPrefix/plugins/linear`+- Dashboard widget: `/:companyPrefix/dashboard`+- Optional issue tab: `/:companyPrefix/issues/:issueId?tab=linear`+- Optional project tab: `/:companyPrefix/projects/:projectId?tab=linear`++Main screens and interactions:++- Plugin settings:+ - Linear API token secret ref+ - workspace/team/project mappings+ - status mapping between Paperclip and Linear+ - sync direction: import only, export only, bidirectional+ - comment sync toggle+- Linear overview page:+ - sync health card+ - recent sync jobs+ - mapped projects and teams+ - unresolved conflicts queue+ - import actions for teams, projects, and issues+- Issue tab:+ - linked Linear issue key and URL+ - sync status and last synced time+ - actions: link existing, create in Linear, resync now, unlink+ - timeline of synced comments/status changes+- Dashboard widget:+ - open sync errors+ - imported vs linked issues count+ - recent webhook/job failures++Core workflows:++- Board enables the plugin, maps a Linear team, and imports a backlog into Paperclip.+- Paperclip issue status changes push to Linear and Linear comments arrive back through webhooks.+- Board resolves mapping conflicts from the plugin page instead of silently drifting state.++### Hooks needed++Recommended capabilities and extension points:++- `instance.settings.register`+- `ui.sidebar.register`+- `ui.page.register`+- `ui.dashboardWidget.register`+- `ui.detailTab.register` for `issue` and `project`+- `events.subscribe(issue.created)`+- `events.subscribe(issue.updated)`+- `events.subscribe(issue.comment.created)`+- `events.subscribe(project.updated)`+- `jobs.schedule`+- `webhooks.receive`+- `http.outbound`+- `secrets.read-ref`+- `plugin.state.read`+- `plugin.state.write`+- optional `issues.create`+- optional `issues.update`+- optional `issue.comments.create`+- `activity.log.write`++Important constraint:++- webhook processing should be idempotent and conflict-aware+- external IDs and sync cursors belong in plugin-owned state, not inline on core issue rows in the first version++## GitHub Issue Tracking++Package idea: `@paperclip/plugin-github-issues`++This plugin syncs Paperclip issues with GitHub Issues and optionally links PRs. It is useful for:++- importing repo backlogs+- mirroring issue status and comments+- linking PRs to Paperclip issues+- tracking cross-repo work from inside one company view+- bridging engineering workflow with Paperclip task governance++### UX++- Settings page: `/settings/plugins/github-issues`+- Main page: `/:companyPrefix/plugins/github-issues`+- Dashboard widget: `/:companyPrefix/dashboard`+- Optional issue tab: `/:companyPrefix/issues/:issueId?tab=github`+- Optional project tab: `/:companyPrefix/projects/:projectId?tab=github`++Main screens and interactions:++- Plugin settings:+ - GitHub App or PAT secret ref+ - org/repo mappings+ - label/status mapping+ - whether PR linking is enabled+ - whether new Paperclip issues should create GitHub issues automatically+- GitHub overview page:+ - repo mapping list+ - sync health and recent webhook events+ - import backlog action+ - queue of unlinked GitHub issues+- Issue tab:+ - linked GitHub issue and optional linked PRs+ - actions: create GitHub issue, link existing issue, unlink, resync+ - comment/status sync timeline+- Dashboard widget:+ - open PRs linked to active Paperclip issues+ - webhook failures+ - sync lag metrics++Core workflows:++- Board imports GitHub Issues for a repo into Paperclip.+- GitHub webhooks update status/comment state in Paperclip.+- A PR is linked back to the Paperclip issue so the board can follow delivery status.++### Hooks needed++Recommended capabilities and extension points:++- `instance.settings.register`+- `ui.sidebar.register`+- `ui.page.register`+- `ui.dashboardWidget.register`+- `ui.detailTab.register` for `issue` and `project`+- `events.subscribe(issue.created)`+- `events.subscribe(issue.updated)`+- `events.subscribe(issue.comment.created)`+- `jobs.schedule`+- `webhooks.receive`+- `http.outbound`+- `secrets.read-ref`+- `plugin.state.read`+- `plugin.state.write`+- optional `issues.create`+- optional `issues.update`+- optional `issue.comments.create`+- `activity.log.write`++Important constraint:++- keep "local git state" and "remote GitHub issue state" in separate plugins even if they work together++## Grafana Metrics++Package idea: `@paperclip/plugin-grafana`++This plugin surfaces external metrics and dashboards inside Paperclip. It is useful for:++- company KPI visibility+- infrastructure/incident monitoring+- showing deploy, traffic, latency, or revenue charts next to work+- creating Paperclip issues from anomalous metrics++### UX++- Settings page: `/settings/plugins/grafana`+- Main page: `/:companyPrefix/plugins/grafana`+- Dashboard widgets: `/:companyPrefix/dashboard`+- Optional goal tab: `/:companyPrefix/goals/:goalId?tab=metrics`++Main screens and interactions:++- Plugin settings:+ - Grafana base URL+ - service account token secret ref+ - dashboard and panel mappings+ - refresh interval+ - optional alert threshold rules+- Dashboard widgets:+ - one or more metric cards on the main dashboard+ - quick trend view and last refresh time+ - link out to Grafana and link in to the full Paperclip plugin page+- Full metrics page:+ - selected dashboard panels embedded or proxied+ - metric selector+ - time range selector+ - "create issue from anomaly" action+- Goal tab:+ - metric cards relevant to a specific goal or project++Core workflows:++- Board sees service degradation or business KPI movement directly on the Paperclip dashboard.+- Board clicks into the full metrics page to inspect the relevant Grafana panels.+- Board creates a Paperclip issue from a threshold breach with a metric snapshot attached.++### Hooks needed++Recommended capabilities and extension points:++- `instance.settings.register`+- `ui.dashboardWidget.register`+- `ui.page.register`+- `ui.detailTab.register` for `goal` or `project`+- `jobs.schedule`+- `http.outbound`+- `secrets.read-ref`+- `plugin.state.read`+- `plugin.state.write`+- optional `issues.create`+- optional `assets.write`+- `activity.log.write`++Optional event subscriptions:++- `events.subscribe(goal.created)`+- `events.subscribe(project.updated)`++Important constraint:++- start read-only first+- do not make Grafana alerting logic part of Paperclip core; keep it as additive signal and issue creation++## Child Process / Server Tracking++Package idea: `@paperclip/plugin-runtime-processes`++This plugin tracks long-lived local processes and dev servers started in project workspaces. It is useful for:++- seeing which agent started which local service+- tracking ports, health, and uptime+- restarting failed dev servers+- exposing process state alongside issue and run state+- making local development workflows visible to the board++### UX++- Settings page: `/settings/plugins/runtime-processes`+- Main page: `/:companyPrefix/plugins/runtime-processes`+- Dashboard widget: `/:companyPrefix/dashboard`+- Process detail page: `/:companyPrefix/plugins/runtime-processes/:processId`+- Project tab: `/:companyPrefix/projects/:projectId?tab=processes`+- Optional agent tab: `/:companyPrefix/agents/:agentId?tab=processes`++Main screens and interactions:++- Plugin settings:+ - whether manual process registration is allowed+ - health check behavior+ - whether operators can stop/restart processes+ - log retention preferences+- Process list page:+ - status table with name, command, cwd, owner agent, port, uptime, and health+ - filters for running/exited/crashed processes+ - actions: inspect, stop, restart, tail logs+- Project tab:+ - filters the process list to the project's workspaces+ - shows which workspace each process belongs to+ - groups processes by project workspace+- Process detail page:+ - process metadata+ - live log tail+ - health check history+ - links to associated issue or run+- Agent tab:+ - shows processes started by or assigned to that agent++Core workflows:++- An agent starts a dev server; the first-party process service registers it and the plugin renders it.+- Board opens a project and immediately sees the processes attached to that project's workspace.+- Board sees a crashed process on the dashboard and restarts it from the plugin page.+- Board attaches process logs to an issue when debugging a failure.++### Hooks needed++Recommended capabilities and extension points:++- `instance.settings.register`+- `ui.sidebar.register`+- `ui.page.register`+- `ui.dashboardWidget.register`+- `ui.detailTab.register` for `project` and `agent`+- `projects.read`+- `project.workspaces.read`+- `workspace.process.register`+- `workspace.process.list`+- `workspace.process.read`+- optional `workspace.process.terminate`+- optional `workspace.process.restart`+- `workspace.process.logs.read`+- optional `workspace.http.probe`+- `plugin.state.read`+- `plugin.state.write`+- `activity.log.write`++Optional event subscriptions:++- `events.subscribe(agent.run.started)`+- `events.subscribe(agent.run.finished)`+- `events.subscribe(process.started)`+- `events.subscribe(process.exited)`++Important constraint:++- this should be built on a first-party process registry+- the plugin should not own raw child-process spawning on its own++## Stripe Revenue Tracking++Package idea: `@paperclip/plugin-stripe`++This plugin pulls Stripe revenue and subscription data into Paperclip. It is useful for:++- showing MRR and churn next to company goals+- tracking trials, conversions, and failed payments+- letting the board connect revenue movement to ongoing work+- enabling future financial dashboards beyond token costs++### UX++- Settings page: `/settings/plugins/stripe`+- Main page: `/:companyPrefix/plugins/stripe`+- Dashboard widgets: `/:companyPrefix/dashboard`+- Optional company/goal metric tabs if those surfaces exist later++Main screens and interactions:++- Plugin settings:+ - Stripe secret key secret ref+ - account selection if needed+ - metric definitions such as MRR treatment and trial handling+ - sync interval+ - webhook signing secret ref+- Dashboard widgets:+ - MRR card+ - active subscriptions+ - trial-to-paid conversion+ - failed payment alerts+- Stripe overview page:+ - time series charts+ - recent customer/subscription events+ - webhook health+ - sync history+ - action: create issue from billing anomaly++Core workflows:++- Board enables the plugin and connects a Stripe account.+- Webhooks and scheduled reconciliation keep plugin state current.+- Revenue widgets appear on the main dashboard and can be linked to company goals.+- Failed payment spikes or churn events can generate Paperclip issues for follow-up.++### Hooks needed++Recommended capabilities and extension points:++- `instance.settings.register`+- `ui.dashboardWidget.register`+- `ui.page.register`+- `jobs.schedule`+- `webhooks.receive`+- `http.outbound`+- `secrets.read-ref`+- `plugin.state.read`+- `plugin.state.write`+- `company.metrics.write`+- optional `issues.create`+- `activity.log.write`++Important constraint:++- Stripe data should stay additive to Paperclip core+- it should not leak into core budgeting logic, which is specifically about model/token spend in V1++## Specific Patterns From OpenCode Worth Adopting++## Adopt++- separate SDK package from runtime loader+- deterministic load order and precedence+- very small authoring API+- typed schemas for plugin inputs/config/tools+- internal extensions using the same registration shapes as external ones when reasonable+- plugin load errors isolated from host startup when possible+- explicit community-facing plugin docs and example templates++## Adapt, not copy++- local path loading+- dependency auto-install+- hook mutation model+- built-in override behavior+- broad runtime context objects++## Avoid++- project-local arbitrary code loading+- implicit trust of npm packages at startup+- plugins overriding core invariants+- unsandboxed in-process execution as the default extension model++## Suggested Rollout Plan++## Phase 0: Harden the seams that already exist++- formalize adapter/storage/secret/run-log registries as "platform modules"+- remove ad-hoc fallback behavior where possible+- document stable registration contracts++## Phase 1: Add connector plugins first++This is the highest-value, lowest-risk plugin category.++Build:++- plugin manifest+- global install/update lifecycle+- global plugin config and optional company-mapping storage+- secret ref access+- typed domain event subscription+- scheduled jobs+- webhook endpoints+- activity logging helpers+- dashboard widget and settings-panel contributions++This phase would immediately cover:++- Linear+- GitHub+- Grafana+- Stripe++## Phase 2: Add workspace services and workspace plugins++Build first-party primitives:++- project workspace service built on `project_workspaces`+- PTY/session service+- file service+- git service+- process/service tracker++Then expose additive plugin/UI surfaces on top.++This phase covers:++- file browser+- terminal+- git workflow+- child process/server tracking++## Phase 3: Consider richer UI and plugin packaging++Only after phases 1 and 2 are stable:++- richer frontend extension support+- signed/verified plugin packages+- plugin marketplace+- optional custom plugin storage backends or migrations++## Recommended Architecture Decision++If I had to collapse this report into one architectural decision, it would be:++Paperclip should not implement "an OpenCode-style generic in-process hook system."+Paperclip should implement "a plugin platform with multiple trust tiers":++- trusted platform modules for low-level runtime integration+- typed out-of-process plugins for instance-wide integrations and automation+- schema-driven UI contributions+- core-owned invariants that plugins can observe and act around, but not replace++That gets the upside of `opencode`'s extensibility without importing the wrong threat model.++## Concrete Next Steps I Would Take In Paperclip++1. Write a short extension architecture RFC that formalizes the distinction between `platform modules` and `plugins`.+2. Introduce a small plugin manifest type in `packages/shared` and a `plugins` install/config section in the instance config.+3. Build a typed domain event bus around existing activity/live-event patterns, but keep core invariants non-hookable.+4. Implement connector-plugin MVP only: global install/config, secret refs, jobs, webhooks, settings panel, dashboard widget.+5. Treat workspace features as a separate track that starts by building core workspace primitives, not raw plugin hooks.