Skip to content

The open-source app everyone uses to manage agents at work

Add plugin framework and settings UI

Dotta80cdbdbd47ce
diff --git a/doc/plugins/PLUGIN_SPEC.md b/doc/plugins/PLUGIN_SPEC.md
index 896f51152b..65fabac0fe 100644
--- a/doc/plugins/PLUGIN_SPEC.md
+++ b/doc/plugins/PLUGIN_SPEC.md
@@ -8,6 +8,26 @@ It expands the brief plugin notes in [doc/SPEC.md](../SPEC.md) and should be rea
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.
+## Current implementation caveats
+
+The code in this repo now includes an early plugin runtime and admin UI, but it does not yet deliver the full deployment model described in this spec.
+
+Today, the practical deployment model is:
+
+- single-tenant
+- self-hosted
+- single-node or otherwise filesystem-persistent
+
+Current limitations to keep in mind:
+
+- Runtime installs assume a writable local filesystem for the plugin package directory and plugin data directory.
+- Runtime npm installs assume `npm` is available in the running environment and that the host can reach the configured package registry.
+- Published npm packages are the intended install artifact for deployed plugins.
+- The repo example plugins under `packages/plugins/examples/` are development conveniences. They work from a source checkout and should not be assumed to exist in a generic published build unless they are explicitly shipped with that build.
+- Dynamic plugin install is not yet cloud-ready for horizontally scaled or ephemeral deployments. There is no shared artifact store, install coordination, or cross-node distribution layer yet.
+
+In practice, that means the current implementation is a good fit for local development and self-hosted persistent deployments, but not yet for multi-instance cloud plugin distribution.
+
## 1. Scope
This spec covers:
@@ -212,6 +232,8 @@ Suggested layout:
The package install directory and the plugin data directory are separate.
+This on-disk model is the reason the current implementation expects a persistent writable host filesystem. Cloud-safe artifact replication is future work.
+
## 8.2 Operator Commands
Paperclip should add CLI commands:
@@ -237,6 +259,8 @@ The install process is:
7. Start plugin worker and run health/validation.
8. Mark plugin `ready` or `error`.
+For the current implementation, this install flow should be read as a single-host workflow. A successful install writes packages to the local host, and other app nodes will not automatically receive that plugin unless a future shared distribution mechanism is added.
+
## 9. Load Order And Precedence
Load order must be deterministic.
diff --git a/packages/db/src/migrations/0028_plugin_tables.sql b/packages/db/src/migrations/0028_plugin_tables.sql
new file mode 100644
index 0000000000..8ee0d93787
--- /dev/null
+++ b/packages/db/src/migrations/0028_plugin_tables.sql
@@ -0,0 +1,177 @@
+-- Rollback:
+-- DROP INDEX IF EXISTS "plugin_logs_level_idx";
+-- DROP INDEX IF EXISTS "plugin_logs_plugin_time_idx";
+-- DROP INDEX IF EXISTS "plugin_company_settings_company_plugin_uq";
+-- DROP INDEX IF EXISTS "plugin_company_settings_plugin_idx";
+-- DROP INDEX IF EXISTS "plugin_company_settings_company_idx";
+-- DROP INDEX IF EXISTS "plugin_webhook_deliveries_key_idx";
+-- DROP INDEX IF EXISTS "plugin_webhook_deliveries_status_idx";
+-- DROP INDEX IF EXISTS "plugin_webhook_deliveries_plugin_idx";
+-- DROP INDEX IF EXISTS "plugin_job_runs_status_idx";
+-- DROP INDEX IF EXISTS "plugin_job_runs_plugin_idx";
+-- DROP INDEX IF EXISTS "plugin_job_runs_job_idx";
+-- DROP INDEX IF EXISTS "plugin_jobs_unique_idx";
+-- DROP INDEX IF EXISTS "plugin_jobs_next_run_idx";
+-- DROP INDEX IF EXISTS "plugin_jobs_plugin_idx";
+-- DROP INDEX IF EXISTS "plugin_entities_external_idx";
+-- DROP INDEX IF EXISTS "plugin_entities_scope_idx";
+-- DROP INDEX IF EXISTS "plugin_entities_type_idx";
+-- DROP INDEX IF EXISTS "plugin_entities_plugin_idx";
+-- DROP INDEX IF EXISTS "plugin_state_plugin_scope_idx";
+-- DROP INDEX IF EXISTS "plugin_config_plugin_id_idx";
+-- DROP INDEX IF EXISTS "plugins_status_idx";
+-- DROP INDEX IF EXISTS "plugins_plugin_key_idx";
+-- DROP TABLE IF EXISTS "plugin_logs";
+-- DROP TABLE IF EXISTS "plugin_company_settings";
+-- DROP TABLE IF EXISTS "plugin_webhook_deliveries";
+-- DROP TABLE IF EXISTS "plugin_job_runs";
+-- DROP TABLE IF EXISTS "plugin_jobs";
+-- DROP TABLE IF EXISTS "plugin_entities";
+-- DROP TABLE IF EXISTS "plugin_state";
+-- DROP TABLE IF EXISTS "plugin_config";
+-- DROP TABLE IF EXISTS "plugins";
+
+CREATE TABLE "plugins" (
+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+ "plugin_key" text NOT NULL,
+ "package_name" text NOT NULL,
+ "package_path" text,
+ "version" text NOT NULL,
+ "api_version" integer DEFAULT 1 NOT NULL,
+ "categories" jsonb DEFAULT '[]'::jsonb NOT NULL,
+ "manifest_json" jsonb NOT NULL,
+ "status" text DEFAULT 'installed' NOT NULL,
+ "install_order" integer,
+ "last_error" text,
+ "installed_at" timestamp with time zone DEFAULT now() NOT NULL,
+ "updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_config" (
+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+ "plugin_id" uuid NOT NULL,
+ "config_json" jsonb DEFAULT '{}'::jsonb NOT NULL,
+ "last_error" text,
+ "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+ "updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_state" (
+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+ "plugin_id" uuid NOT NULL,
+ "scope_kind" text NOT NULL,
+ "scope_id" text,
+ "namespace" text DEFAULT 'default' NOT NULL,
+ "state_key" text NOT NULL,
+ "value_json" jsonb NOT NULL,
+ "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+ CONSTRAINT "plugin_state_unique_entry_idx" UNIQUE NULLS NOT DISTINCT("plugin_id","scope_kind","scope_id","namespace","state_key")
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_entities" (
+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+ "plugin_id" uuid NOT NULL,
+ "entity_type" text NOT NULL,
+ "scope_kind" text NOT NULL,
+ "scope_id" text,
+ "external_id" text,
+ "title" text,
+ "status" text,
+ "data" jsonb DEFAULT '{}'::jsonb NOT NULL,
+ "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+ "updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_jobs" (
+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+ "plugin_id" uuid NOT NULL,
+ "job_key" text NOT NULL,
+ "schedule" text NOT NULL,
+ "status" text DEFAULT 'active' NOT NULL,
+ "last_run_at" timestamp with time zone,
+ "next_run_at" timestamp with time zone,
+ "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+ "updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_job_runs" (
+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+ "job_id" uuid NOT NULL,
+ "plugin_id" uuid NOT NULL,
+ "trigger" text NOT NULL,
+ "status" text DEFAULT 'pending' NOT NULL,
+ "duration_ms" integer,
+ "error" text,
+ "logs" jsonb DEFAULT '[]'::jsonb NOT NULL,
+ "started_at" timestamp with time zone,
+ "finished_at" timestamp with time zone,
+ "created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_webhook_deliveries" (
+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+ "plugin_id" uuid NOT NULL,
+ "webhook_key" text NOT NULL,
+ "external_id" text,
+ "status" text DEFAULT 'pending' NOT NULL,
+ "duration_ms" integer,
+ "error" text,
+ "payload" jsonb NOT NULL,
+ "headers" jsonb DEFAULT '{}'::jsonb NOT NULL,
+ "started_at" timestamp with time zone,
+ "finished_at" timestamp with time zone,
+ "created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_company_settings" (
+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+ "company_id" uuid NOT NULL,
+ "plugin_id" uuid NOT NULL,
+ "settings_json" jsonb DEFAULT '{}'::jsonb NOT NULL,
+ "last_error" text,
+ "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+ "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+ "enabled" boolean DEFAULT true NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "plugin_logs" (
+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+ "plugin_id" uuid NOT NULL,
+ "level" text NOT NULL DEFAULT 'info',
+ "message" text NOT NULL,
+ "meta" jsonb,
+ "created_at" timestamp with time zone NOT NULL DEFAULT now()
+);
+--> statement-breakpoint
+ALTER TABLE "plugin_config" ADD CONSTRAINT "plugin_config_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_state" ADD CONSTRAINT "plugin_state_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_entities" ADD CONSTRAINT "plugin_entities_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_jobs" ADD CONSTRAINT "plugin_jobs_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_job_runs" ADD CONSTRAINT "plugin_job_runs_job_id_plugin_jobs_id_fk" FOREIGN KEY ("job_id") REFERENCES "public"."plugin_jobs"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_job_runs" ADD CONSTRAINT "plugin_job_runs_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_webhook_deliveries" ADD CONSTRAINT "plugin_webhook_deliveries_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_company_settings" ADD CONSTRAINT "plugin_company_settings_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_company_settings" ADD CONSTRAINT "plugin_company_settings_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "plugin_logs" ADD CONSTRAINT "plugin_logs_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "plugins_plugin_key_idx" ON "plugins" USING btree ("plugin_key");--> statement-breakpoint
+CREATE INDEX "plugins_status_idx" ON "plugins" USING btree ("status");--> statement-breakpoint
+CREATE UNIQUE INDEX "plugin_config_plugin_id_idx" ON "plugin_config" USING btree ("plugin_id");--> statement-breakpoint
+CREATE INDEX "plugin_state_plugin_scope_idx" ON "plugin_state" USING btree ("plugin_id","scope_kind");--> statement-breakpoint
+CREATE INDEX "plugin_entities_plugin_idx" ON "plugin_entities" USING btree ("plugin_id");--> statement-breakpoint
+CREATE INDEX "plugin_entities_type_idx" ON "plugin_entities" USING btree ("entity_type");--> statement-breakpoint
+CREATE INDEX "plugin_entities_scope_idx" ON "plugin_entities" USING btree ("scope_kind","scope_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "plugin_entities_external_idx" ON "plugin_entities" USING btree ("plugin_id","entity_type","external_id");--> statement-breakpoint
+CREATE INDEX "plugin_jobs_plugin_idx" ON "plugin_jobs" USING btree ("plugin_id");--> statement-breakpoint
+CREATE INDEX "plugin_jobs_next_run_idx" ON "plugin_jobs" USING btree ("next_run_at");--> statement-breakpoint
+CREATE UNIQUE INDEX "plugin_jobs_unique_idx" ON "plugin_jobs" USING btree ("plugin_id","job_key");--> statement-breakpoint
+CREATE INDEX "plugin_job_runs_job_idx" ON "plugin_job_runs" USING btree ("job_id");--> statement-breakpoint
+CREATE INDEX "plugin_job_runs_plugin_idx" ON "plugin_job_runs" USING btree ("plugin_id");--> statement-breakpoint
+CREATE INDEX "plugin_job_runs_status_idx" ON "plugin_job_runs" USING btree ("status");--> statement-breakpoint
+CREATE INDEX "plugin_webhook_deliveries_plugin_idx" ON "plugin_webhook_deliveries" USING btree ("plugin_id");--> statement-breakpoint
+CREATE INDEX "plugin_webhook_deliveries_status_idx" ON "plugin_webhook_deliveries" USING btree ("status");--> statement-breakpoint
+CREATE INDEX "plugin_webhook_deliveries_key_idx" ON "plugin_webhook_deliveries" USING btree ("webhook_key");--> statement-breakpoint
+CREATE INDEX "plugin_company_settings_company_idx" ON "plugin_company_settings" USING btree ("company_id");--> statement-breakpoint
+CREATE INDEX "plugin_company_settings_plugin_idx" ON "plugin_company_settings" USING btree ("plugin_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "plugin_company_settings_company_plugin_uq" ON "plugin_company_settings" USING btree ("company_id","plugin_id");--> statement-breakpoint
+CREATE INDEX "plugin_logs_plugin_time_idx" ON "plugin_logs" USING btree ("plugin_id","created_at");--> statement-breakpoint
+CREATE INDEX "plugin_logs_level_idx" ON "plugin_logs" USING btree ("level");
diff --git a/packages/db/src/migrations/meta/_journal.json b/packages/db/src/migrations/meta/_journal.json
index 80a1dfbd1d..63c1808782 100644
--- a/packages/db/src/migrations/meta/_journal.json
+++ b/packages/db/src/migrations/meta/_journal.json
@@ -197,6 +197,13 @@
"when": 1773150731736,
"tag": "0027_tranquil_tenebrous",
"breakpoints": true
+ },
+ {
+ "idx": 28,
+ "version": "7",
+ "when": 1773417600000,
+ "tag": "0028_plugin_tables",
+ "breakpoints": true
}
]
-}
\ No newline at end of file
+}
diff --git a/packages/db/src/schema/index.ts b/packages/db/src/schema/index.ts
index 3416ea9a04..25904f702f 100644
--- a/packages/db/src/schema/index.ts
+++ b/packages/db/src/schema/index.ts
@@ -32,3 +32,11 @@ export { approvalComments } from "./approval_comments.js";
export { activityLog } from "./activity_log.js";
export { companySecrets } from "./company_secrets.js";
export { companySecretVersions } from "./company_secret_versions.js";
+export { plugins } from "./plugins.js";
+export { pluginConfig } from "./plugin_config.js";
+export { pluginCompanySettings } from "./plugin_company_settings.js";
+export { pluginState } from "./plugin_state.js";
+export { pluginEntities } from "./plugin_entities.js";
+export { pluginJobs, pluginJobRuns } from "./plugin_jobs.js";
+export { pluginWebhookDeliveries } from "./plugin_webhooks.js";
+export { pluginLogs } from "./plugin_logs.js";
diff --git a/packages/db/src/schema/plugin_company_settings.ts b/packages/db/src/schema/plugin_company_settings.ts
new file mode 100644
index 0000000000..87d4b4af08
--- /dev/null
+++ b/packages/db/src/schema/plugin_company_settings.ts
@@ -0,0 +1,41 @@
+import { pgTable, uuid, text, timestamp, jsonb, index, uniqueIndex, boolean } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+import { plugins } from "./plugins.js";
+
+/**
+ * `plugin_company_settings` table — stores operator-managed plugin settings
+ * scoped to a specific company.
+ *
+ * This is distinct from `plugin_config`, which stores instance-wide plugin
+ * configuration. Each company can have at most one settings row per plugin.
+ *
+ * Rows represent explicit overrides from the default company behavior:
+ * - no row => plugin is enabled for the company by default
+ * - row with `enabled = false` => plugin is disabled for that company
+ * - row with `enabled = true` => plugin remains enabled and stores company settings
+ */
+export const pluginCompanySettings = pgTable(
+ "plugin_company_settings",
+ {
+ id: uuid("id").primaryKey().defaultRandom(),
+ companyId: uuid("company_id")
+ .notNull()
+ .references(() => companies.id, { onDelete: "cascade" }),
+ pluginId: uuid("plugin_id")
+ .notNull()
+ .references(() => plugins.id, { onDelete: "cascade" }),
+ enabled: boolean("enabled").notNull().default(true),
+ settingsJson: jsonb("settings_json").$type<Record<string, unknown>>().notNull().default({}),
+ lastError: text("last_error"),
+ createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+ updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+ },
+ (table) => ({
+ companyIdx: index("plugin_company_settings_company_idx").on(table.companyId),
+ pluginIdx: index("plugin_company_settings_plugin_idx").on(table.pluginId),
+ companyPluginUq: uniqueIndex("plugin_company_settings_company_plugin_uq").on(
+ table.companyId,
+ table.pluginId,
+ ),
+ }),
+);
diff --git a/packages/db/src/schema/plugin_config.ts b/packages/db/src/schema/plugin_config.ts
new file mode 100644
index 0000000000..24407b9780
--- /dev/null
+++ b/packages/db/src/schema/plugin_config.ts
@@ -0,0 +1,30 @@
+import { pgTable, uuid, text, timestamp, jsonb, uniqueIndex } from "drizzle-orm/pg-core";
+import { plugins } from "./plugins.js";
+
+/**
+ * `plugin_config` table — stores operator-provided instance configuration
+ * for each plugin (one row per plugin, enforced by a unique index on
+ * `plugin_id`).
+ *
+ * The `config_json` column holds the values that the operator enters in the
+ * plugin settings UI. These values are validated at runtime against the
+ * plugin's `instanceConfigSchema` from the manifest.
+ *
+ * @see PLUGIN_SPEC.md §21.3
+ */
+export const pluginConfig = pgTable(
+ "plugin_config",
+ {
+ id: uuid("id").primaryKey().defaultRandom(),
+ pluginId: uuid("plugin_id")
+ .notNull()
+ .references(() => plugins.id, { onDelete: "cascade" }),
+ configJson: jsonb("config_json").$type<Record<string, unknown>>().notNull().default({}),
+ lastError: text("last_error"),
+ createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+ updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+ },
+ (table) => ({
+ pluginIdIdx: uniqueIndex("plugin_config_plugin_id_idx").on(table.pluginId),
+ }),
+);
diff --git a/packages/db/src/schema/plugin_entities.ts b/packages/db/src/schema/plugin_entities.ts
new file mode 100644
index 0000000000..5f73230452
--- /dev/null
+++ b/packages/db/src/schema/plugin_entities.ts
@@ -0,0 +1,54 @@
+import {
+ pgTable,
+ uuid,
+ text,
+ timestamp,
+ jsonb,
+ index,
+ uniqueIndex,
+} from "drizzle-orm/pg-core";
+import { plugins } from "./plugins.js";
+import type { PluginStateScopeKind } from "@paperclipai/shared";
+
+/**
+ * `plugin_entities` table — persistent high-level mapping between Paperclip
+ * objects and external plugin-defined entities.
+ *
+ * This table is used by plugins (e.g. `linear`, `github`) to store pointers
+ * to their respective external IDs for projects, issues, etc. and to store
+ * their custom data.
+ *
+ * Unlike `plugin_state`, which is for raw K-V persistence, `plugin_entities`
+ * is intended for structured object mappings that the host can understand
+ * and query for cross-plugin UI integration.
+ *
+ * @see PLUGIN_SPEC.md §21.3
+ */
+export const pluginEntities = pgTable(
+ "plugin_entities",
+ {
+ id: uuid("id").primaryKey().defaultRandom(),
+ pluginId: uuid("plugin_id")
+ .notNull()
+ .references(() => plugins.id, { onDelete: "cascade" }),
+ entityType: text("entity_type").notNull(),
+ scopeKind: text("scope_kind").$type<PluginStateScopeKind>().notNull(),
+ scopeId: text("scope_id"), // NULL for global scope (text to match plugin_state.scope_id)
+ externalId: text("external_id"), // ID in the external system
+ title: text("title"),
+ status: text("status"),
+ data: jsonb("data").$type<Record<string, unknown>>().notNull().default({}),
+ createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+ updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+ },
+ (table) => ({
+ pluginIdx: index("plugin_entities_plugin_idx").on(table.pluginId),
+ typeIdx: index("plugin_entities_type_idx").on(table.entityType),
+ scopeIdx: index("plugin_entities_scope_idx").on(table.scopeKind, table.scopeId),
+ externalIdx: uniqueIndex("plugin_entities_external_idx").on(
+ table.pluginId,
+ table.entityType,
+ table.externalId,
+ ),
+ }),
+);
diff --git a/packages/db/src/schema/plugin_jobs.ts b/packages/db/src/schema/plugin_jobs.ts
new file mode 100644
index 0000000000..fec0d0c423
--- /dev/null
+++ b/packages/db/src/schema/plugin_jobs.ts
@@ -0,0 +1,102 @@
+import {
+ pgTable,
+ uuid,
+ text,
+ integer,
+ timestamp,
+ jsonb,
+ index,
+ uniqueIndex,
+} from "drizzle-orm/pg-core";
+import { plugins } from "./plugins.js";
+import type { PluginJobStatus, PluginJobRunStatus, PluginJobRunTrigger } from "@paperclipai/shared";
+
+/**
+ * `plugin_jobs` table — registration and runtime configuration for
+ * scheduled jobs declared by plugins in their manifests.
+ *
+ * Each row represents one scheduled job entry for a plugin. The
+ * `job_key` matches the key declared in the manifest's `jobs` array.
+ * The `schedule` column stores the cron expression or interval string
+ * used by the job scheduler to decide when to fire the job.
+ *
+ * Status values:
+ * - `active` — job is enabled and will run on schedule
+ * - `paused` — job is temporarily disabled by the operator
+ * - `error` — job has been disabled due to repeated failures
+ *
+ * @see PLUGIN_SPEC.md §21.3 — `plugin_jobs`
+ */
+export const pluginJobs = pgTable(
+ "plugin_jobs",
+ {
+ id: uuid("id").primaryKey().defaultRandom(),
+ /** FK to the owning plugin. Cascades on delete. */
+ pluginId: uuid("plugin_id")
+ .notNull()
+ .references(() => plugins.id, { onDelete: "cascade" }),
+ /** Identifier matching the key in the plugin manifest's `jobs` array. */
+ jobKey: text("job_key").notNull(),
+ /** Cron expression (e.g. `"0 * * * *"`) or interval string. */
+ schedule: text("schedule").notNull(),
+ /** Current scheduling state. */
+ status: text("status").$type<PluginJobStatus>().notNull().default("active"),
+ /** Timestamp of the most recent successful execution. */
+ lastRunAt: timestamp("last_run_at", { withTimezone: true }),
+ /** Pre-computed timestamp of the next scheduled execution. */
+ nextRunAt: timestamp("next_run_at", { withTimezone: true }),
+ createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+ updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+ },
+ (table) => ({
+ pluginIdx: index("plugin_jobs_plugin_idx").on(table.pluginId),
+ nextRunIdx: index("plugin_jobs_next_run_idx").on(table.nextRunAt),
+ uniqueJobIdx: uniqueIndex("plugin_jobs_unique_idx").on(table.pluginId, table.jobKey),
+ }),
+);
+
+/**
+ * `plugin_job_runs` table — immutable execution history for plugin-owned jobs.
+ *
+ * Each row is created when a job run begins and updated when it completes.
+ * Rows are never modified after `status` reaches a terminal value
+ * (`succeeded` | `failed` | `cancelled`).
+ *
+ * Trigger values:
+ * - `scheduled` — fired automatically by the cron/interval scheduler
+ * - `manual` — triggered by an operator via the admin UI or API
+ *
+ * @see PLUGIN_SPEC.md §21.3 — `plugin_job_runs`
+ */
+export const pluginJobRuns = pgTable(
+ "plugin_job_runs",
+ {
+ id: uuid("id").primaryKey().defaultRandom(),
+ /** FK to the parent job definition. Cascades on delete. */
+ jobId: uuid("job_id")
+ .notNull()
+ .references(() => pluginJobs.id, { onDelete: "cascade" }),
+ /** Denormalized FK to the owning plugin for efficient querying. Cascades on delete. */
+ pluginId: uuid("plugin_id")
+ .notNull()
+ .references(() => plugins.id, { onDelete: "cascade" }),
+ /** What caused this run to start (`"scheduled"` or `"manual"`). */
+ trigger: text("trigger").$type<PluginJobRunTrigger>().notNull(),
+ /** Current lifecycle state of this run. */
+ status: text("status").$type<PluginJobRunStatus>().notNull().default("pending"),
+ /** Wall-clock duration in milliseconds. Null until the run finishes. */
+ durationMs: integer("duration_ms"),
+ /** Error message if `status === "failed"`. */
+ error: text("error"),
+ /** Ordered list of log lines emitted during this run. */
+ logs: jsonb("logs").$type<string[]>().notNull().default([]),
+ startedAt: timestamp("started_at", { withTimezone: true }),
+ finishedAt: timestamp("finished_at", { withTimezone: true }),
+ createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+ },
+ (table) => ({
+ jobIdx: index("plugin_job_runs_job_idx").on(table.jobId),
+ pluginIdx: index("plugin_job_runs_plugin_idx").on(table.pluginId),
+ statusIdx: index("plugin_job_runs_status_idx").on(table.status),
+ }),
+);
diff --git a/packages/db/src/schema/plugin_logs.ts b/packages/db/src/schema/plugin_logs.ts
new file mode 100644
index 0000000000..d32908f16c
--- /dev/null
+++ b/packages/db/src/schema/plugin_logs.ts
@@ -0,0 +1,43 @@
+import {
+ pgTable,
+ uuid,
+ text,
+ timestamp,
+ jsonb,
+ index,
+} from "drizzle-orm/pg-core";
+import { plugins } from "./plugins.js";
+
+/**
+ * `plugin_logs` table — structured log storage for plugin workers.
+ *
+ * Each row stores a single log entry emitted by a plugin worker via
+ * `ctx.logger.info(...)` etc. Logs are queryable by plugin, level, and
+ * time range to support the operator logs panel and debugging workflows.
+ *
+ * Rows are inserted by the host when handling `log` notifications from
+ * the worker process. A capped retention policy can be applied via
+ * periodic cleanup (e.g. delete rows older than 7 days).
+ *
+ * @see PLUGIN_SPEC.md §26 — Observability
+ */
+export const pluginLogs = pgTable(
+ "plugin_logs",
+ {
+ id: uuid("id").primaryKey().defaultRandom(),
+ pluginId: uuid("plugin_id")
+ .notNull()
+ .references(() => plugins.id, { onDelete: "cascade" }),
+ level: text("level").notNull().default("info"),
+ message: text("message").notNull(),
+ meta: jsonb("meta").$type<Record<string, unknown>>(),
+ createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+ },
+ (table) => ({
+ pluginTimeIdx: index("plugin_logs_plugin_time_idx").on(
+ table.pluginId,
+ table.createdAt,
+ ),
+ levelIdx: index("plugin_logs_level_idx").on(table.level),
+ }),
+);
diff --git a/packages/db/src/schema/plugin_state.ts b/packages/db/src/schema/plugin_state.ts
new file mode 100644
index 0000000000..600797fa95
--- /dev/null
+++ b/packages/db/src/schema/plugin_state.ts
@@ -0,0 +1,90 @@
+import {
+ pgTable,
+ uuid,
+ text,
+ timestamp,
+ jsonb,
+ index,
+ unique,
+} from "drizzle-orm/pg-core";
+import type { PluginStateScopeKind } from "@paperclipai/shared";
+import { plugins } from "./plugins.js";
+
+/**
+ * `plugin_state` table — scoped key-value storage for plugin workers.
+ *
+ * Each row stores a single JSON value identified by
+ * `(plugin_id, scope_kind, scope_id, namespace, state_key)`. Plugins use
+ * this table through `ctx.state.get()`, `ctx.state.set()`, and
+ * `ctx.state.delete()` in the SDK.
+ *
+ * Scope kinds determine the granularity of isolation:
+ * - `instance` — one value shared across the whole Paperclip instance
+ * - `company` — one value per company
+ * - `project` — one value per project
+ * - `project_workspace` — one value per project workspace
+ * - `agent` — one value per agent
+ * - `issue` — one value per issue
+ * - `goal` — one value per goal
+ * - `run` — one value per agent run
+ *
+ * The `namespace` column defaults to `"default"` and can be used to
+ * logically group keys without polluting the root namespace.
+ *
+ * @see PLUGIN_SPEC.md §21.3 — `plugin_state`
+ */
+export const pluginState = pgTable(
+ "plugin_state",
+ {
+ id: uuid("id").primaryKey().defaultRandom(),
+ /** FK to the owning plugin. Cascades on delete. */
+ pluginId: uuid("plugin_id")
+ .notNull()
+ .references(() => plugins.id, { onDelete: "cascade" }),
+ /** Granularity of the scope (e.g. `"instance"`, `"project"`, `"issue"`). */
+ scopeKind: text("scope_kind").$type<PluginStateScopeKind>().notNull(),
+ /**
+ * UUID or text identifier for the scoped object.
+ * Null for `instance` scope (which has no associated entity).
+ */
+ scopeId: text("scope_id"),
+ /**
+ * Sub-namespace to avoid key collisions within a scope.
+ * Defaults to `"default"` if the plugin does not specify one.
+ */
+ namespace: text("namespace").notNull().default("default"),
+ /** The key identifying this state entry within the namespace. */
+ stateKey: text("state_key").notNull(),
+ /** JSON-serializable value stored by the plugin. */
+ valueJson: jsonb("value_json").notNull(),
+ /** Timestamp of the most recent write. */
+ updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+ },
+ (table) => ({
+ /**
+ * Unique constraint enforces that there is at most one value per
+ * (plugin, scope kind, scope id, namespace, key) tuple.
+ *
+ * `nullsNotDistinct()` is required so that `scope_id IS NULL` entries
+ * (used by `instance` scope) are treated as equal by PostgreSQL rather
+ * than as distinct nulls — otherwise the upsert target in `set()` would
+ * fail to match existing rows and create duplicates.
+ *
+ * Requires PostgreSQL 15+.
+ */
+ uniqueEntry: unique("plugin_state_unique_entry_idx")
+ .on(
+ table.pluginId,
+ table.scopeKind,
+ table.scopeId,
+ table.namespace,
+ table.stateKey,
+ )
+ .nullsNotDistinct(),
+ /** Speed up lookups by plugin + scope kind (most common access pattern). */
+ pluginScopeIdx: index("plugin_state_plugin_scope_idx").on(
+ table.pluginId,
+ table.scopeKind,
+ ),
+ }),
+);
diff --git a/packages/db/src/schema/plugin_webhooks.ts b/packages/db/src/schema/plugin_webhooks.ts
new file mode 100644
index 0000000000..0580e97073
--- /dev/null
+++ b/packages/db/src/schema/plugin_webhooks.ts
@@ -0,0 +1,65 @@
+import {
+ pgTable,
+ uuid,
+ text,
+ integer,
+ timestamp,
+ jsonb,
+ index,
+} from "drizzle-orm/pg-core";
+import { plugins } from "./plugins.js";
+import type { PluginWebhookDeliveryStatus } from "@paperclipai/shared";
+
+/**
+ * `plugin_webhook_deliveries` table — inbound webhook delivery history for plugins.
+ *
+ * When an external system sends an HTTP POST to a plugin's registered webhook
+ * endpoint (e.g. `/api/plugins/:pluginKey/webhooks/:webhookKey`), the server
+ * creates a row in this table before dispatching the payload to the plugin
+ * worker. This provides an auditable log of every delivery attempt.
+ *
+ * The `webhook_key` matches the key declared in the plugin manifest's
+ * `webhooks` array. `external_id` is an optional identifier supplied by the
+ * remote system (e.g. a GitHub delivery GUID) that can be used to detect
+ * and reject duplicate deliveries.
+ *
+ * Status values:
+ * - `pending` — received but not yet dispatched to the worker
+ * - `processing` — currently being handled by the plugin worker
+ * - `succeeded` — worker processed the payload successfully
+ * - `failed` — worker returned an error or timed out
+ *
+ * @see PLUGIN_SPEC.md §21.3 — `plugin_webhook_deliveries`
+ */
+export const pluginWebhookDeliveries = pgTable(
+ "plugin_webhook_deliveries",
+ {
+ id: uuid("id").primaryKey().defaultRandom(),
+ /** FK to the owning plugin. Cascades on delete. */
+ pluginId: uuid("plugin_id")
+ .notNull()
+ .references(() => plugins.id, { onDelete: "cascade" }),
+ /** Identifier matching the key in the plugin manifest's `webhooks` array. */
+ webhookKey: text("webhook_key").notNull(),
+ /** Optional de-duplication ID provided by the external system. */
+ externalId: text("external_id"),
+ /** Current delivery state. */
+ status: text("status").$type<PluginWebhookDeliveryStatus>().notNull().default("pending"),
+ /** Wall-clock processing duration in milliseconds. Null until delivery finishes. */
+ durationMs: integer("duration_ms"),
+ /** Error message if `status === "failed"`. */
+ error: text("error"),
+ /** Raw JSON body of the inbound HTTP request. */
+ payload: jsonb("payload").$type<Record<string, unknown>>().notNull(),
+ /** Relevant HTTP headers from the inbound request (e.g. signature headers). */
+ headers: jsonb("headers").$type<Record<string, string>>().notNull().default({}),
+ startedAt: timestamp("started_at", { withTimezone: true }),
+ finishedAt: timestamp("finished_at", { withTimezone: true }),
+ createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+ },
+ (table) => ({
+ pluginIdx: index("plugin_webhook_deliveries_plugin_idx").on(table.pluginId),
+ statusIdx: index("plugin_webhook_deliveries_status_idx").on(table.status),
+ keyIdx: index("plugin_webhook_deliveries_key_idx").on(table.webhookKey),
+ }),
+);
diff --git a/packages/db/src/schema/plugins.ts b/packages/db/src/schema/plugins.ts
new file mode 100644
index 0000000000..948e5d6043
--- /dev/null
+++ b/packages/db/src/schema/plugins.ts
@@ -0,0 +1,45 @@
+import {
+ pgTable,
+ uuid,
+ text,
+ integer,
+ timestamp,
+ jsonb,
+ index,
+ uniqueIndex,
+} from "drizzle-orm/pg-core";
+import type { PluginCategory, PluginStatus, PaperclipPluginManifestV1 } from "@paperclipai/shared";
+
+/**
+ * `plugins` table — stores one row per installed plugin.
+ *
+ * Each plugin is uniquely identified by `plugin_key` (derived from
+ * the manifest `id`). The full manifest is persisted as JSONB in
+ * `manifest_json` so the host can reconstruct capability and UI
+ * slot information without loading the plugin package.
+ *
+ * @see PLUGIN_SPEC.md §21.3
+ */
+export const plugins = pgTable(
+ "plugins",
+ {
+ id: uuid("id").primaryKey().defaultRandom(),
+ pluginKey: text("plugin_key").notNull(),
+ packageName: text("package_name").notNull(),
+ version: text("version").notNull(),
+ apiVersion: integer("api_version").notNull().default(1),
+ categories: jsonb("categories").$type<PluginCategory[]>().notNull().default([]),
+ manifestJson: jsonb("manifest_json").$type<PaperclipPluginManifestV1>().notNull(),
+ status: text("status").$type<PluginStatus>().notNull().default("installed"),
+ installOrder: integer("install_order"),
+ /** Resolved package path for local-path installs; used to find worker entrypoint. */
+ packagePath: text("package_path"),
+ lastError: text("last_error"),
+ installedAt: timestamp("installed_at", { withTimezone: true }).notNull().defaultNow(),
+ updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+ },
+ (table) => ({
+ pluginKeyIdx: uniqueIndex("plugins_plugin_key_idx").on(table.pluginKey),
+ statusIdx: index("plugins_status_idx").on(table.status),
+ }),
+);
diff --git a/packages/plugins/create-paperclip-plugin/README.md b/packages/plugins/create-paperclip-plugin/README.md
new file mode 100644
index 0000000000..46519da14e
--- /dev/null
+++ b/packages/plugins/create-paperclip-plugin/README.md
@@ -0,0 +1,38 @@
+# @paperclipai/create-paperclip-plugin
+
+Scaffolding tool for creating new Paperclip plugins.
+
+```bash
+npx @paperclipai/create-paperclip-plugin my-plugin
+```
+
+Or with options:
+
+```bash
+npx @paperclipai/create-paperclip-plugin @acme/my-plugin \
+ --template connector \
+ --category connector \
+ --display-name "Acme Connector" \
+ --description "Syncs Acme data into Paperclip" \
+ --author "Acme Inc"
+```
+
+Supported templates: `default`, `connector`, `workspace`
+Supported categories: `connector`, `workspace`, `automation`, `ui`
+
+Generates:
+- typed manifest + worker entrypoint
+- example UI widget using `@paperclipai/plugin-sdk/ui`
+- test file using `@paperclipai/plugin-sdk/testing`
+- `esbuild` and `rollup` config files using SDK bundler presets
+- dev server script for hot-reload (`paperclip-plugin-dev-server`)
+
+## Workflow after scaffolding
+
+```bash
+cd my-plugin
+pnpm install
+pnpm dev # watch worker + manifest + ui bundles
+pnpm dev:ui # local UI preview server with hot-reload events
+pnpm test
+```
diff --git a/packages/plugins/create-paperclip-plugin/package.json b/packages/plugins/create-paperclip-plugin/package.json
new file mode 100644
index 0000000000..e863cd6c9b
--- /dev/null
+++ b/packages/plugins/create-paperclip-plugin/package.json
@@ -0,0 +1,40 @@
+{
+ "name": "@paperclipai/create-paperclip-plugin",
+ "version": "0.1.0",
+ "type": "module",
+ "bin": {
+ "create-paperclip-plugin": "./dist/index.js"
+ },
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "publishConfig": {
+ "access": "public",
+ "bin": {
+ "create-paperclip-plugin": "./dist/index.js"
+ },
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.js"
+ }
+ },
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts"
+ },
+ "files": [
+ "dist"
+ ],
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "typecheck": "tsc --noEmit"
+ },
+ "dependencies": {
+ "@paperclipai/plugin-sdk": "workspace:*"
+ },
+ "devDependencies": {
+ "@types/node": "^24.6.0",
+ "typescript": "^5.7.3"
+ }
+}
diff --git a/packages/plugins/create-paperclip-plugin/src/index.ts b/packages/plugins/create-paperclip-plugin/src/index.ts
new file mode 100644
index 0000000000..6d0e6c2d4e
--- /dev/null
+++ b/packages/plugins/create-paperclip-plugin/src/index.ts
@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+
+const VALID_TEMPLATES = ["default", "connector", "workspace"] as const;
+type PluginTemplate = (typeof VALID_TEMPLATES)[number];
+const VALID_CATEGORIES = new Set(["connector", "workspace", "automation", "ui"] as const);
+
+export interface ScaffoldPluginOptions {
+ pluginName: string;
+ outputDir: string;
+ template?: PluginTemplate;
+ displayName?: string;
+ description?: string;
+ author?: string;
+ category?: "connector" | "workspace" | "automation" | "ui";
+}
+
+/** Validate npm-style plugin package names (scoped or unscoped). */
+export function isValidPluginName(name: string): boolean {
+ const scopedPattern = /^@[a-z0-9_-]+\/[a-z0-9._-]+$/;
+ const unscopedPattern = /^[a-z0-9._-]+$/;
+ return scopedPattern.test(name) || unscopedPattern.test(name);
+}
+
+/** Convert `@scope/name` to an output directory basename (`name`). */
+function packageToDirName(pluginName: string): string {
+ return pluginName.replace(/^@[^/]+\//, "");
+}
+
+/** Convert an npm package name into a manifest-safe plugin id. */
+function packageToManifestId(pluginName: string): string {
+ if (!pluginName.startsWith("@")) {
+ return pluginName;
+ }
+
+ return pluginName.slice(1).replace("/", ".");
+}
+
+/** Build a human-readable display name from package name tokens. */
+function makeDisplayName(pluginName: string): string {
+ const raw = packageToDirName(pluginName).replace(/[._-]+/g, " ").trim();
+ return raw
+ .split(/\s+/)
+ .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+ .join(" ");
+}
+
+function writeFile(target: string, content: string) {
+ fs.mkdirSync(path.dirname(target), { recursive: true });
+ fs.writeFileSync(target, content);
+}
+
+function quote(value: string): string {
+ return JSON.stringify(value);
+}
+
+/**
+ * Generate a complete Paperclip plugin starter project.
+ *
+ * Output includes manifest/worker/UI entries, SDK harness tests, bundler presets,
+ * and a local dev server script for hot-reload workflow.
+ */
+export function scaffoldPluginProject(options: ScaffoldPluginOptions): string {
+ const template = options.template ?? "default";
+ if (!VALID_TEMPLATES.includes(template)) {
+ throw new Error(`Invalid template '${template}'. Expected one of: ${VALID_TEMPLATES.join(", ")}`);
+ }
+
+ if (!isValidPluginName(options.pluginName)) {
+ throw new Error("Invalid plugin name. Must be lowercase and may include scope, dots, underscores, or hyphens.");
+ }
+
+ if (options.category && !VALID_CATEGORIES.has(options.category)) {
+ throw new Error(`Invalid category '${options.category}'. Expected one of: ${[...VALID_CATEGORIES].join(", ")}`);
+ }
+
+ const outputDir = path.resolve(options.outputDir);
+ if (fs.existsSync(outputDir)) {
+ throw new Error(`Directory already exists: ${outputDir}`);
+ }
+
+ const displayName = options.displayName ?? makeDisplayName(options.pluginName);
+ const description = options.description ?? "A Paperclip plugin";
+ const author = options.author ?? "Plugin Author";
+ const category = options.category ?? (template === "workspace" ? "workspace" : "connector");
+ const manifestId = packageToManifestId(options.pluginName);
+
+ fs.mkdirSync(outputDir, { recursive: true });
+
+ const packageJson = {
+ name: options.pluginName,
+ version: "0.1.0",
+ type: "module",
+ private: true,
+ description,
+ scripts: {
+ build: "node ./esbuild.config.mjs",
+ "build:rollup": "rollup -c",
+ dev: "node ./esbuild.config.mjs --watch",
+ "dev:ui": "paperclip-plugin-dev-server --root . --ui-dir dist/ui --port 4177",
+ test: "vitest run",
+ typecheck: "tsc --noEmit"
+ },
+ paperclipPlugin: {
+ manifest: "./dist/manifest.js",
+ worker: "./dist/worker.js",
+ ui: "./dist/ui/"
+ },
+ keywords: ["paperclip", "plugin", category],
+ author,
+ license: "MIT",
+ dependencies: {
+ "@paperclipai/plugin-sdk": "^1.0.0"
+ },
+ devDependencies: {
+ "@rollup/plugin-node-resolve": "^16.0.1",
+ "@rollup/plugin-typescript": "^12.1.2",
+ "@types/node": "^24.6.0",
+ "@types/react": "^19.0.8",
+ esbuild: "^0.27.3",
+ rollup: "^4.38.0",
+ tslib: "^2.8.1",
+ typescript: "^5.7.3",
+ vitest: "^3.0.5"
+ },
+ peerDependencies: {
+ react: ">=18"
+ }
+ };
+
+ writeFile(path.join(outputDir, "package.json"), `${JSON.stringify(packageJson, null, 2)}\n`);
+
+ const tsconfig = {
+ compilerOptions: {
+ target: "ES2022",
+ module: "NodeNext",
+ moduleResolution: "NodeNext",
+ lib: ["ES2022", "DOM"],
+ jsx: "react-jsx",
+ strict: true,
+ skipLibCheck: true,
+ declaration: true,
+ declarationMap: true,
+ sourceMap: true,
+ outDir: "dist",
+ rootDir: "src"
+ },
+ include: ["src", "tests"],
+ exclude: ["dist", "node_modules"]
+ };
+
+ writeFile(path.join(outputDir, "tsconfig.json"), `${JSON.stringify(tsconfig, null, 2)}\n`);
+
+ writeFile(
+ path.join(outputDir, "esbuild.config.mjs"),
+ `import esbuild from "esbuild";
+import { createPluginBundlerPresets } from "@paperclipai/plugin-sdk/bundlers";
+
+const presets = createPluginBundlerPresets({ uiEntry: "src/ui/index.tsx" });
+const watch = process.argv.includes("--watch");
+
+const workerCtx = await esbuild.context(presets.esbuild.worker);
+const manifestCtx = await esbuild.context(presets.esbuild.manifest);
+const uiCtx = await esbuild.context(presets.esbuild.ui);
+
+if (watch) {
+ await Promise.all([workerCtx.watch(), manifestCtx.watch(), uiCtx.watch()]);
+ console.log("esbuild watch mode enabled for worker, manifest, and ui");
+} else {
+ await Promise.all([workerCtx.rebuild(), manifestCtx.rebuild(), uiCtx.rebuild()]);
+ await Promise.all([workerCtx.dispose(), manifestCtx.dispose(), uiCtx.dispose()]);
+}
+`,
+ );
+
+ writeFile(
+ path.join(outputDir, "rollup.config.mjs"),
+ `import { nodeResolve } from "@rollup/plugin-node-resolve";
+import typescript from "@rollup/plugin-typescript";
+import { createPluginBundlerPresets } from "@paperclipai/plugin-sdk/bundlers";
+
+const presets = createPluginBundlerPresets({ uiEntry: "src/ui/index.tsx" });
+
+function withPlugins(config) {
+ if (!config) return null;
+ return {
+ ...config,
+ plugins: [
+ nodeResolve({
+ extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs"],
+ }),
+ typescript({
+ tsconfig: "./tsconfig.json",
+ declaration: false,
+ declarationMap: false,
+ }),
+ ],
+ };
+}
+
+export default [
+ withPlugins(presets.rollup.manifest),
+ withPlugins(presets.rollup.worker),
+ withPlugins(presets.rollup.ui),
+].filter(Boolean);
+`,
+ );
+
+ writeFile(
+ path.join(outputDir, "src", "manifest.ts"),
+ `import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+
+const manifest: PaperclipPluginManifestV1 = {
+ id: ${quote(manifestId)},
+ apiVersion: 1,
+ version: "0.1.0",
+ displayName: ${quote(displayName)},
+ description: ${quote(description)},
+ author: ${quote(author)},
+ categories: [${quote(category)}],
+ capabilities: [
+ "events.subscribe",
+ "plugin.state.read",
+ "plugin.state.write"
+ ],
+ entrypoints: {
+ worker: "./dist/worker.js",
+ ui: "./dist/ui"
+ },
+ ui: {
+ slots: [
+ {
+ type: "dashboardWidget",
+ id: "health-widget",
+ displayName: ${quote(`${displayName} Health`)},
+ exportName: "DashboardWidget"
+ }
+ ]
+ }
+};
+
+export default manifest;
+`,
+ );
+
+ writeFile(
+ path.join(outputDir, "src", "worker.ts"),
+ `import { definePlugin, runWorker } from "@paperclipai/plugin-sdk";
+
+const plugin = definePlugin({
+ async setup(ctx) {
+ ctx.events.on("issue.created", async (event) => {
+ const issueId = event.entityId ?? "unknown";
+ await ctx.state.set({ scopeKind: "issue", scopeId: issueId, stateKey: "seen" }, true);
+ ctx.logger.info("Observed issue.created", { issueId });
+ });
+
+ ctx.data.register("health", async () => {
+ return { status: "ok", checkedAt: new Date().toISOString() };
+ });
+
+ ctx.actions.register("ping", async () => {
+ ctx.logger.info("Ping action invoked");
+ return { pong: true, at: new Date().toISOString() };
+ });
+ },
+
+ async onHealth() {
+ return { status: "ok", message: "Plugin worker is running" };
+ }
+});
+
+export default plugin;
+runWorker(plugin, import.meta.url);
+`,
+ );
+
+ writeFile(
+ path.join(outputDir, "src", "ui", "index.tsx"),
+ `import { MetricCard, StatusBadge, usePluginAction, usePluginData, type PluginWidgetProps } from "@paperclipai/plugin-sdk/ui";
+
+type HealthData = {
+ status: "ok" | "degraded" | "error";
+ checkedAt: string;
+};
+
+export function DashboardWidget(_props: PluginWidgetProps) {
+ const { data, loading, error } = usePluginData<HealthData>("health");
+ const ping = usePluginAction("ping");
+
+ if (loading) return <div>Loading plugin health...</div>;
+ if (error) return <StatusBadge label={error.message} status="error" />;
+
+ return (
+ <div style={{ display: "grid", gap: "0.5rem" }}>
+ <MetricCard label="Health" value={data?.status ?? "unknown"} />
+ <button onClick={() => void ping()}>Ping Worker</button>
+ </div>
+ );
+}
+`,
+ );
+
+ writeFile(
+ path.join(outputDir, "tests", "plugin.spec.ts"),
+ `import { describe, expect, it } from "vitest";
+import { createTestHarness } from "@paperclipai/plugin-sdk/testing";
+import manifest from "../src/manifest.js";
+import plugin from "../src/worker.js";
+
+describe("plugin scaffold", () => {
+ it("registers data + actions and handles events", async () => {
+ const harness = createTestHarness({ manifest, capabilities: [...manifest.capabilities, "events.emit"] });
+ await plugin.definition.setup(harness.ctx);
+
+ await harness.emit("issue.created", { issueId: "iss_1" }, { entityId: "iss_1", entityType: "issue" });
+ expect(harness.getState({ scopeKind: "issue", scopeId: "iss_1", stateKey: "seen" })).toBe(true);
+
+ const data = await harness.getData<{ status: string }>("health");
+ expect(data.status).toBe("ok");
+
+ const action = await harness.performAction<{ pong: boolean }>("ping");
+ expect(action.pong).toBe(true);
+ });
+});
+`,
+ );
+
+ writeFile(
+ path.join(outputDir, "README.md"),
+ `# ${displayName}
+
+${description}
+
+## Development
+
+\`\`\`bash
+pnpm install
+pnpm dev # watch builds
+pnpm dev:ui # local dev server with hot-reload events
+pnpm test
+\`\`\`
+
+## Install Into Paperclip
+
+\`\`\`bash
+pnpm paperclipai plugin install ./
+\`\`\`
+
+## Build Options
+
+- \`pnpm build\` uses esbuild presets from \`@paperclipai/plugin-sdk/bundlers\`.
+- \`pnpm build:rollup\` uses rollup presets from the same SDK.
+`,
+ );
+
+ writeFile(path.join(outputDir, ".gitignore"), "dist\nnode_modules\n");
+
+ return outputDir;
+}
+
+function parseArg(name: string): string | undefined {
+ const index = process.argv.indexOf(name);
+ if (index === -1) return undefined;
+ return process.argv[index + 1];
+}
+
+/** CLI wrapper for `scaffoldPluginProject`. */
+function runCli() {
+ const pluginName = process.argv[2];
+ if (!pluginName) {
+ // eslint-disable-next-line no-console
+ console.error("Usage: create-paperclip-plugin <name> [--template default|connector|workspace] [--output <dir>]");
+ process.exit(1);
+ }
+
+ const template = (parseArg("--template") ?? "default") as PluginTemplate;
+ const outputRoot = parseArg("--output") ?? process.cwd();
+ const targetDir = path.resolve(outputRoot, packageToDirName(pluginName));
+
+ const out = scaffoldPluginProject({
+ pluginName,
+ outputDir: targetDir,
+ template,
+ displayName: parseArg("--display-name"),
+ description: parseArg("--description"),
+ author: parseArg("--author"),
+ category: parseArg("--category") as ScaffoldPluginOptions["category"] | undefined,
+ });
+
+ // eslint-disable-next-line no-console
+ console.log(`Created plugin scaffold at ${out}`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+ runCli();
+}
diff --git a/packages/plugins/create-paperclip-plugin/tsconfig.json b/packages/plugins/create-paperclip-plugin/tsconfig.json
new file mode 100644
index 0000000000..90314411a4
--- /dev/null
+++ b/packages/plugins/create-paperclip-plugin/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../../tsconfig.json",
+ "compilerOptions": {
+ "outDir": "dist",
+ "rootDir": "src",
+ "types": ["node"]
+ },
+ "include": ["src"]
+}
diff --git a/packages/plugins/examples/plugin-file-browser-example/README.md b/packages/plugins/examples/plugin-file-browser-example/README.md
new file mode 100644
index 0000000000..ca02fcf73e
--- /dev/null
+++ b/packages/plugins/examples/plugin-file-browser-example/README.md
@@ -0,0 +1,62 @@
+# File Browser Example Plugin
+
+Example Paperclip plugin that demonstrates:
+
+- **projectSidebarItem** — An optional "Files" link under each project in the sidebar that opens the project detail with this plugin’s tab selected. This is controlled by plugin settings and defaults to off.
+- **detailTab** (entityType project) — A project detail tab with a workspace-path selector, a desktop two-column layout (file tree left, editor right), and a mobile one-panel flow with a back button from editor to file tree, including save support.
+
+This is a repo-local example plugin for development. It should not be assumed to ship in a generic production build unless it is explicitly included.
+
+## Slots
+
+| Slot | Type | Description |
+|---------------------|---------------------|--------------------------------------------------|
+| Files (sidebar) | `projectSidebarItem`| Optional link under each project → project detail + tab. |
+| Files (tab) | `detailTab` | Responsive tree/editor layout with save support.|
+
+## Settings
+
+- `Show Files in Sidebar` — toggles the project sidebar link on or off. Defaults to off.
+- `Comment File Links` — controls whether comment annotations and the comment context-menu action are shown.
+
+## Capabilities
+
+- `ui.sidebar.register` — project sidebar item
+- `ui.detailTab.register` — project detail tab
+- `projects.read` — resolve project
+- `project.workspaces.read` — list workspaces and read paths for file access
+
+## Worker
+
+- **getData `workspaces`** — `ctx.projects.listWorkspaces(projectId, companyId)` (ordered, primary first).
+- **getData `fileList`** — `{ projectId, workspaceId, directoryPath? }` → list directory entries for the workspace root or a subdirectory (Node `fs`).
+- **getData `fileContent`** — `{ projectId, workspaceId, filePath }` → read file content using workspace-relative paths (Node `fs`).
+- **performAction `writeFile`** — `{ projectId, workspaceId, filePath, content }` → write the current editor buffer back to disk.
+
+## Local Install (Dev)
+
+From the repo root, build the plugin and install it by local path:
+
+```bash
+pnpm --filter @paperclipai/plugin-file-browser-example build
+pnpm paperclipai plugin install ./packages/plugins/examples/plugin-file-browser-example
+```
+
+To uninstall:
+
+```bash
+pnpm paperclipai plugin uninstall paperclip-file-browser-example --force
+```
+
+**Local development notes:**
+
+- **Build first.** The host resolves the worker from the manifest `entrypoints.worker` (e.g. `./dist/worker.js`). Run `pnpm build` in the plugin directory before installing so the worker file exists.
+- **Dev-only install path.** This local-path install flow assumes this monorepo checkout is present on disk. For deployed installs, publish an npm package instead of depending on `packages/plugins/examples/...` existing on the host.
+- **Reinstall after pulling.** If you installed a plugin by local path before the server stored `package_path`, the plugin may show status **error** (worker not found). Uninstall and install again so the server persists the path and can activate the plugin.
+- Optional: use `paperclip-plugin-dev-server` for UI hot-reload with `devUiUrl` in plugin config.
+
+## Structure
+
+- `src/manifest.ts` — manifest with `projectSidebarItem` and `detailTab` (entityTypes `["project"]`).
+- `src/worker.ts` — data handlers for workspaces, file list, file content.
+- `src/ui/index.tsx` — `FilesLink` (sidebar) and `FilesTab` (workspace path selector + two-panel file tree/editor).
diff --git a/packages/plugins/examples/plugin-file-browser-example/package.json b/packages/plugins/examples/plugin-file-browser-example/package.json
new file mode 100644
index 0000000000..86c720d43d
--- /dev/null
+++ b/packages/plugins/examples/plugin-file-browser-example/package.json
@@ -0,0 +1,42 @@
+{
+ "name": "@paperclipai/plugin-file-browser-example",
+ "version": "0.1.0",
+ "description": "Example plugin: project sidebar Files link + project detail tab with workspace selector and file browser",
+ "type": "module",
+ "private": true,
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "paperclipPlugin": {
+ "manifest": "./dist/manifest.js",
+ "worker": "./dist/worker.js",
+ "ui": "./dist/ui/"
+ },
+ "scripts": {
+ "prebuild": "node ../../../../scripts/ensure-plugin-build-deps.mjs",
+ "build": "tsc && node ./scripts/build-ui.mjs",
+ "clean": "rm -rf dist",
+ "typecheck": "pnpm --filter @paperclipai/plugin-sdk build && tsc --noEmit"
+ },
+ "dependencies": {
+ "@codemirror/lang-javascript": "^6.2.2",
+ "@codemirror/language": "^6.11.0",
+ "@codemirror/state": "^6.4.0",
+ "@codemirror/view": "^6.28.0",
+ "@lezer/highlight": "^1.2.1",
+ "@paperclipai/plugin-sdk": "workspace:*",
+ "codemirror": "^6.0.1"
+ },
+ "devDependencies": {
+ "@types/node": "^24.6.0",
+ "@types/react": "^19.0.8",
+ "@types/react-dom": "^19.0.3",
+ "esbuild": "^0.27.3",
+ "react": "^19.0.0",
+ "react-dom": "^19.0.0",
+ "typescript": "^5.7.3"
+ },
+ "peerDependencies": {
+ "react": ">=18"
+ }
+}
diff --git a/packages/plugins/examples/plugin-file-browser-example/scripts/build-ui.mjs b/packages/plugins/examples/plugin-file-browser-example/scripts/build-ui.mjs
new file mode 100644
index 0000000000..5cd75637cf
--- /dev/null
+++ b/packages/plugins/examples/plugin-file-browser-example/scripts/build-ui.mjs
@@ -0,0 +1,24 @@
+import esbuild from "esbuild";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+
+await esbuild.build({
+ entryPoints: [path.join(packageRoot, "src/ui/index.tsx")],
+ outfile: path.join(packageRoot, "dist/ui/index.js"),
+ bundle: true,
+ format: "esm",
+ platform: "browser",
+ target: ["es2022"],
+ sourcemap: true,
+ external: [
+ "react",
+ "react-dom",
+ "react/jsx-runtime",
+ "@paperclipai/plugin-sdk/ui",
+ ],
+ logLevel: "info",
+});
diff --git a/packages/plugins/examples/plugin-file-browser-example/src/index.ts b/packages/plugins/examples/plugin-file-browser-example/src/index.ts
new file mode 100644
index 0000000000..f301da5d92
--- /dev/null
+++ b/packages/plugins/examples/plugin-file-browser-example/src/index.ts
@@ -0,0 +1,2 @@
+export { default as manifest } from "./manifest.js";
+export { default as worker } from "./worker.js";
diff --git a/packages/plugins/examples/plugin-file-browser-example/src/manifest.ts b/packages/plugins/examples/plugin-file-browser-example/src/manifest.ts
new file mode 100644
index 0000000000..027c134b1c
--- /dev/null
+++ b/packages/plugins/examples/plugin-file-browser-example/src/manifest.ts
@@ -0,0 +1,85 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+
+const PLUGIN_ID = "paperclip-file-browser-example";
+const FILES_SIDEBAR_SLOT_ID = "files-link";
+const FILES_TAB_SLOT_ID = "files-tab";
+const COMMENT_FILE_LINKS_SLOT_ID = "comment-file-links";
+const COMMENT_OPEN_FILES_SLOT_ID = "comment-open-files";
+
+const manifest: PaperclipPluginManifestV1 = {
+ id: PLUGIN_ID,
+ apiVersion: 1,
+ version: "0.2.0",
+ displayName: "File Browser (Example)",
+ description: "Example plugin that adds a Files link under each project in the sidebar, a file browser + editor tab on the project detail page, and per-comment file link annotations with a context menu action to open referenced files.",
+ author: "Paperclip",
+ categories: ["workspace", "ui"],
+ capabilities: [
+ "ui.sidebar.register",
+ "ui.detailTab.register",
+ "ui.commentAnnotation.register",
+ "ui.action.register",
+ "projects.read",
+ "project.workspaces.read",
+ "issue.comments.read",
+ "plugin.state.read",
+ ],
+ instanceConfigSchema: {
+ type: "object",
+ properties: {
+ showFilesInSidebar: {
+ type: "boolean",
+ title: "Show Files in Sidebar",
+ default: false,
+ description: "Adds the Files link under each project in the sidebar.",
+ },
+ commentAnnotationMode: {
+ type: "string",
+ title: "Comment File Links",
+ enum: ["annotation", "contextMenu", "both", "none"],
+ default: "both",
+ description: "Controls which comment extensions are active: 'annotation' shows file links below each comment, 'contextMenu' adds an \"Open in Files\" action to the comment menu, 'both' enables both, 'none' disables comment features.",
+ },
+ },
+ },
+ entrypoints: {
+ worker: "./dist/worker.js",
+ ui: "./dist/ui",
+ },
+ ui: {
+ slots: [
+ {
+ type: "projectSidebarItem",
+ id: FILES_SIDEBAR_SLOT_ID,
+ displayName: "Files",
+ exportName: "FilesLink",
+ entityTypes: ["project"],
+ order: 10,
+ },
+ {
+ type: "detailTab",
+ id: FILES_TAB_SLOT_ID,
+ displayName: "Files",
+ exportName: "FilesTab",
+ entityTypes: ["project"],
+ order: 10,
+ },
+ {
+ type: "commentAnnotation",
+ id: COMMENT_FILE_LINKS_SLOT_ID,
+ displayName: "File Links",
+ exportName: "CommentFileLinks",
+ entityTypes: ["comment"],
+ },
+ {
+ type: "commentContextMenuItem",
+ id: COMMENT_OPEN_FILES_SLOT_ID,
+ displayName: "Open in Files",
+ exportName: "CommentOpenFiles",
+ entityTypes: ["comment"],
+ },
+ ],
+ },
+};
+
+export default manifest;
diff --git a/packages/plugins/examples/plugin-file-browser-example/src/ui/index.tsx b/packages/plugins/examples/plugin-file-browser-example/src/ui/index.tsx
new file mode 100644
index 0000000000..0e12d903dc
--- /dev/null
+++ b/packages/plugins/examples/plugin-file-browser-example/src/ui/index.tsx
@@ -0,0 +1,815 @@
+import type {
+ PluginProjectSidebarItemProps,
+ PluginDetailTabProps,
+ PluginCommentAnnotationProps,
+ PluginCommentContextMenuItemProps,
+} from "@paperclipai/plugin-sdk/ui";
+import { usePluginAction, usePluginData } from "@paperclipai/plugin-sdk/ui";
+import { useMemo, useState, useEffect, useRef, type MouseEvent, type RefObject } from "react";
+import { EditorView } from "@codemirror/view";
+import { basicSetup } from "codemirror";
+import { javascript } from "@codemirror/lang-javascript";
+import { HighlightStyle, syntaxHighlighting } from "@codemirror/language";
+import { tags } from "@lezer/highlight";
+
+const PLUGIN_KEY = "paperclip-file-browser-example";
+const FILES_TAB_SLOT_ID = "files-tab";
+
+const editorBaseTheme = {
+ "&": {
+ height: "100%",
+ },
+ ".cm-scroller": {
+ overflow: "auto",
+ fontFamily:
+ "ui-monospace, SFMono-Regular, SF Mono, Menlo, Monaco, Consolas, Liberation Mono, monospace",
+ fontSize: "13px",
+ lineHeight: "1.6",
+ },
+ ".cm-content": {
+ padding: "12px 14px 18px",
+ },
+};
+
+const editorDarkTheme = EditorView.theme({
+ ...editorBaseTheme,
+ "&": {
+ ...editorBaseTheme["&"],
+ backgroundColor: "oklch(0.23 0.02 255)",
+ color: "oklch(0.93 0.01 255)",
+ },
+ ".cm-gutters": {
+ backgroundColor: "oklch(0.25 0.015 255)",
+ color: "oklch(0.74 0.015 255)",
+ borderRight: "1px solid oklch(0.34 0.01 255)",
+ },
+ ".cm-activeLine, .cm-activeLineGutter": {
+ backgroundColor: "oklch(0.30 0.012 255 / 0.55)",
+ },
+ ".cm-selectionBackground, .cm-content ::selection": {
+ backgroundColor: "oklch(0.42 0.02 255 / 0.45)",
+ },
+ "&.cm-focused .cm-selectionBackground": {
+ backgroundColor: "oklch(0.47 0.025 255 / 0.5)",
+ },
+ ".cm-cursor, .cm-dropCursor": {
+ borderLeftColor: "oklch(0.93 0.01 255)",
+ },
+ ".cm-matchingBracket": {
+ backgroundColor: "oklch(0.37 0.015 255 / 0.5)",
+ color: "oklch(0.95 0.01 255)",
+ outline: "none",
+ },
+ ".cm-nonmatchingBracket": {
+ color: "oklch(0.70 0.08 24)",
+ },
+}, { dark: true });
+
+const editorLightTheme = EditorView.theme({
+ ...editorBaseTheme,
+ "&": {
+ ...editorBaseTheme["&"],
+ backgroundColor: "color-mix(in oklab, var(--card) 92%, var(--background))",
+ color: "var(--foreground)",
+ },
+ ".cm-content": {
+ ...editorBaseTheme[".cm-content"],
+ caretColor: "var(--foreground)",
+ },
+ ".cm-gutters": {
+ backgroundColor: "color-mix(in oklab, var(--card) 96%, var(--background))",
+ color: "var(--muted-foreground)",
+ borderRight: "1px solid var(--border)",
+ },
+ ".cm-activeLine, .cm-activeLineGutter": {
+ backgroundColor: "color-mix(in oklab, var(--accent) 52%, transparent)",
+ },
+ ".cm-selectionBackground, .cm-content ::selection": {
+ backgroundColor: "color-mix(in oklab, var(--accent) 72%, transparent)",
+ },
+ "&.cm-focused .cm-selectionBackground": {
+ backgroundColor: "color-mix(in oklab, var(--accent) 84%, transparent)",
+ },
+ ".cm-cursor, .cm-dropCursor": {
+ borderLeftColor: "color-mix(in oklab, var(--foreground) 88%, transparent)",
+ },
+ ".cm-matchingBracket": {
+ backgroundColor: "color-mix(in oklab, var(--accent) 45%, transparent)",
+ color: "var(--foreground)",
+ outline: "none",
+ },
+ ".cm-nonmatchingBracket": {
+ color: "var(--destructive)",
+ },
+});
+
+const editorDarkHighlightStyle = HighlightStyle.define([
+ { tag: tags.keyword, color: "oklch(0.78 0.025 265)" },
+ { tag: [tags.name, tags.variableName], color: "oklch(0.88 0.01 255)" },
+ { tag: [tags.string, tags.special(tags.string)], color: "oklch(0.80 0.02 170)" },
+ { tag: [tags.number, tags.bool, tags.null], color: "oklch(0.79 0.02 95)" },
+ { tag: [tags.comment, tags.lineComment, tags.blockComment], color: "oklch(0.64 0.01 255)" },
+ { tag: [tags.function(tags.variableName), tags.labelName], color: "oklch(0.84 0.018 220)" },
+ { tag: [tags.typeName, tags.className], color: "oklch(0.82 0.02 245)" },
+ { tag: [tags.operator, tags.punctuation], color: "oklch(0.77 0.01 255)" },
+ { tag: [tags.invalid, tags.deleted], color: "oklch(0.70 0.08 24)" },
+]);
+
+const editorLightHighlightStyle = HighlightStyle.define([
+ { tag: tags.keyword, color: "oklch(0.45 0.07 270)" },
+ { tag: [tags.name, tags.variableName], color: "oklch(0.28 0.01 255)" },
+ { tag: [tags.string, tags.special(tags.string)], color: "oklch(0.45 0.06 165)" },
+ { tag: [tags.number, tags.bool, tags.null], color: "oklch(0.48 0.08 90)" },
+ { tag: [tags.comment, tags.lineComment, tags.blockComment], color: "oklch(0.53 0.01 255)" },
+ { tag: [tags.function(tags.variableName), tags.labelName], color: "oklch(0.42 0.07 220)" },
+ { tag: [tags.typeName, tags.className], color: "oklch(0.40 0.06 245)" },
+ { tag: [tags.operator, tags.punctuation], color: "oklch(0.36 0.01 255)" },
+ { tag: [tags.invalid, tags.deleted], color: "oklch(0.55 0.16 24)" },
+]);
+
+type Workspace = { id: string; projectId: string; name: string; path: string; isPrimary: boolean };
+type FileEntry = { name: string; path: string; isDirectory: boolean };
+type FileTreeNodeProps = {
+ entry: FileEntry;
+ companyId: string | null;
+ projectId: string;
+ workspaceId: string;
+ selectedPath: string | null;
+ onSelect: (path: string) => void;
+ depth?: number;
+};
+
+const PathLikePattern = /[\\/]/;
+const WindowsDrivePathPattern = /^[A-Za-z]:[\\/]/;
+const UuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function isLikelyPath(pathValue: string): boolean {
+ const trimmed = pathValue.trim();
+ return PathLikePattern.test(trimmed) || WindowsDrivePathPattern.test(trimmed);
+}
+
+function workspaceLabel(workspace: Workspace): string {
+ const pathLabel = workspace.path.trim();
+ const nameLabel = workspace.name.trim();
+ const hasPathLabel = isLikelyPath(pathLabel) && !UuidPattern.test(pathLabel);
+ const hasNameLabel = nameLabel.length > 0 && !UuidPattern.test(nameLabel);
+ const baseLabel = hasPathLabel ? pathLabel : hasNameLabel ? nameLabel : "";
+ if (!baseLabel) {
+ return workspace.isPrimary ? "(no workspace path) (primary)" : "(no workspace path)";
+ }
+
+ return workspace.isPrimary ? `${baseLabel} (primary)` : baseLabel;
+}
+
+function useIsMobile(breakpointPx = 768): boolean {
+ const [isMobile, setIsMobile] = useState(() =>
+ typeof window !== "undefined" ? window.innerWidth < breakpointPx : false,
+ );
+
+ useEffect(() => {
+ if (typeof window === "undefined") return;
+ const mediaQuery = window.matchMedia(`(max-width: ${breakpointPx - 1}px)`);
+ const update = () => setIsMobile(mediaQuery.matches);
+ update();
+ mediaQuery.addEventListener("change", update);
+ return () => mediaQuery.removeEventListener("change", update);
+ }, [breakpointPx]);
+
+ return isMobile;
+}
+
+function useIsDarkMode(): boolean {
+ const [isDarkMode, setIsDarkMode] = useState(() =>
+ typeof document !== "undefined" && document.documentElement.classList.contains("dark"),
+ );
+
+ useEffect(() => {
+ if (typeof document === "undefined") return;
+ const root = document.documentElement;
+ const update = () => setIsDarkMode(root.classList.contains("dark"));
+ update();
+
+ const observer = new MutationObserver(update);
+ observer.observe(root, { attributes: true, attributeFilter: ["class"] });
+ return () => observer.disconnect();
+ }, []);
+
+ return isDarkMode;
+}
+
+function useAvailableHeight(
+ ref: RefObject<HTMLElement | null>,
+ options?: { bottomPadding?: number; minHeight?: number },
+): number | null {
+ const bottomPadding = options?.bottomPadding ?? 24;
+ const minHeight = options?.minHeight ?? 384;
+ const [height, setHeight] = useState<number | null>(null);
+
+ useEffect(() => {
+ if (typeof window === "undefined") return;
+
+ const update = () => {
+ const element = ref.current;
+ if (!element) return;
+ const rect = element.getBoundingClientRect();
+ const nextHeight = Math.max(minHeight, Math.floor(window.innerHeight - rect.top - bottomPadding));
+ setHeight(nextHeight);
+ };
+
+ update();
+ window.addEventListener("resize", update);
+ window.addEventListener("orientationchange", update);
+
+ const observer = typeof ResizeObserver !== "undefined"
+ ? new ResizeObserver(() => update())
+ : null;
+ if (observer && ref.current) observer.observe(ref.current);
+
+ return () => {
+ window.removeEventListener("resize", update);
+ window.removeEventListener("orientationchange", update);
+ observer?.disconnect();
+ };
+ }, [bottomPadding, minHeight, ref]);
+
+ return height;
+}
+
+function FileTreeNode({
+ entry,
+ companyId,
+ projectId,
+ workspaceId,
+ selectedPath,
+ onSelect,
+ depth = 0,
+}: FileTreeNodeProps) {
+ const [isExpanded, setIsExpanded] = useState(false);
+ const isSelected = selectedPath === entry.path;
+
+ if (entry.isDirectory) {
+ return (
+ <li>
+ <button
+ type="button"
+ className="flex w-full items-center gap-2 rounded-none px-2 py-1.5 text-left text-sm text-foreground hover:bg-accent/60"
+ style={{ paddingLeft: `${depth * 14 + 8}px` }}
+ onClick={() => setIsExpanded((value) => !value)}
+ aria-expanded={isExpanded}
+ >
+ <span className="w-3 text-xs text-muted-foreground">{isExpanded ? "▾" : "▸"}</span>
+ <span className="truncate font-medium">{entry.name}</span>
+ </button>
+ {isExpanded ? (
+ <ExpandedDirectoryChildren
+ directoryPath={entry.path}
+ companyId={companyId}
+ projectId={projectId}
+ workspaceId={workspaceId}
+ selectedPath={selectedPath}
+ onSelect={onSelect}
+ depth={depth}
+ />
+ ) : null}
+ </li>
+ );
+ }
+
+ return (
+ <li>
+ <button
+ type="button"
+ className={`block w-full rounded-none px-2 py-1.5 text-left text-sm transition-colors ${
+ isSelected ? "bg-accent text-foreground" : "text-muted-foreground hover:bg-accent/50 hover:text-foreground"
+ }`}
+ style={{ paddingLeft: `${depth * 14 + 23}px` }}
+ onClick={() => onSelect(entry.path)}
+ >
+ <span className="truncate">{entry.name}</span>
+ </button>
+ </li>
+ );
+}
+
+function ExpandedDirectoryChildren({
+ directoryPath,
+ companyId,
+ projectId,
+ workspaceId,
+ selectedPath,
+ onSelect,
+ depth,
+}: {
+ directoryPath: string;
+ companyId: string | null;
+ projectId: string;
+ workspaceId: string;
+ selectedPath: string | null;
+ onSelect: (path: string) => void;
+ depth: number;
+}) {
+ const { data: childData } = usePluginData<{ entries: FileEntry[] }>("fileList", {
+ companyId,
+ projectId,
+ workspaceId,
+ directoryPath,
+ });
+ const children = childData?.entries ?? [];
+
+ if (children.length === 0) {
+ return null;
+ }
+
+ return (
+ <ul className="space-y-0.5">
+ {children.map((child) => (
+ <FileTreeNode
+ key={child.path}
+ entry={child}
+ companyId={companyId}
+ projectId={projectId}
+ workspaceId={workspaceId}
+ selectedPath={selectedPath}
+ onSelect={onSelect}
+ depth={depth + 1}
+ />
+ ))}
+ </ul>
+ );
+}
+
+/**
+ * Project sidebar item: link "Files" that opens the project detail with the Files plugin tab.
+ */
+export function FilesLink({ context }: PluginProjectSidebarItemProps) {
+ const { data: config, loading: configLoading } = usePluginData<PluginConfig>("plugin-config", {});
+ const showFilesInSidebar = config?.showFilesInSidebar ?? false;
+
+ if (configLoading || !showFilesInSidebar) {
+ return null;
+ }
+
+ const projectId = context.entityId;
+ const projectRef = (context as PluginProjectSidebarItemProps["context"] & { projectRef?: string | null })
+ .projectRef
+ ?? projectId;
+ const prefix = context.companyPrefix ? `/${context.companyPrefix}` : "";
+ const tabValue = `plugin:${PLUGIN_KEY}:${FILES_TAB_SLOT_ID}`;
+ const href = `${prefix}/projects/${projectRef}?tab=${encodeURIComponent(tabValue)}`;
+ const isActive = typeof window !== "undefined" && (() => {
+ const pathname = window.location.pathname.replace(/\/+$/, "");
+ const segments = pathname.split("/").filter(Boolean);
+ const projectsIndex = segments.indexOf("projects");
+ const activeProjectRef = projectsIndex >= 0 ? segments[projectsIndex + 1] ?? null : null;
+ const activeTab = new URLSearchParams(window.location.search).get("tab");
+ if (activeTab !== tabValue) return false;
+ if (!activeProjectRef) return false;
+ return activeProjectRef === projectId || activeProjectRef === projectRef;
+ })();
+
+ const handleClick = (event: MouseEvent<HTMLAnchorElement>) => {
+ if (
+ event.defaultPrevented
+ || event.button !== 0
+ || event.metaKey
+ || event.ctrlKey
+ || event.altKey
+ || event.shiftKey
+ ) {
+ return;
+ }
+
+ event.preventDefault();
+ window.history.pushState({}, "", href);
+ window.dispatchEvent(new PopStateEvent("popstate"));
+ };
+
+ return (
+ <a
+ href={href}
+ onClick={handleClick}
+ aria-current={isActive ? "page" : undefined}
+ className={`block px-3 py-1 text-[12px] truncate transition-colors ${
+ isActive
+ ? "bg-accent text-foreground font-medium"
+ : "text-muted-foreground hover:text-foreground hover:bg-accent/50"
+ }`}
+ >
+ Files
+ </a>
+ );
+}
+
+/**
+ * Project detail tab: workspace selector, file tree, and CodeMirror editor.
+ */
+export function FilesTab({ context }: PluginDetailTabProps) {
+ const companyId = context.companyId;
+ const projectId = context.entityId;
+ const isMobile = useIsMobile();
+ const isDarkMode = useIsDarkMode();
+ const panesRef = useRef<HTMLDivElement | null>(null);
+ const availableHeight = useAvailableHeight(panesRef, {
+ bottomPadding: isMobile ? 16 : 24,
+ minHeight: isMobile ? 320 : 420,
+ });
+ const { data: workspacesData } = usePluginData<Workspace[]>("workspaces", {
+ projectId,
+ companyId,
+ });
+ const workspaces = workspacesData ?? [];
+ const workspaceSelectKey = workspaces.map((w) => `${w.id}:${workspaceLabel(w)}`).join("|");
+ const [workspaceId, setWorkspaceId] = useState<string | null>(null);
+ const resolvedWorkspaceId = workspaceId ?? workspaces[0]?.id ?? null;
+ const selectedWorkspace = useMemo(
+ () => workspaces.find((w) => w.id === resolvedWorkspaceId) ?? null,
+ [workspaces, resolvedWorkspaceId],
+ );
+
+ const fileListParams = useMemo(
+ () => (selectedWorkspace ? { projectId, companyId, workspaceId: selectedWorkspace.id } : {}),
+ [companyId, projectId, selectedWorkspace],
+ );
+ const { data: fileListData, loading: fileListLoading } = usePluginData<{ entries: FileEntry[] }>(
+ "fileList",
+ fileListParams,
+ );
+ const entries = fileListData?.entries ?? [];
+
+ // Track the `?file=` query parameter across navigations (popstate).
+ const [urlFilePath, setUrlFilePath] = useState<string | null>(() => {
+ if (typeof window === "undefined") return null;
+ return new URLSearchParams(window.location.search).get("file") || null;
+ });
+ const lastConsumedFileRef = useRef<string | null>(null);
+
+ useEffect(() => {
+ if (typeof window === "undefined") return;
+ const onNav = () => {
+ const next = new URLSearchParams(window.location.search).get("file") || null;
+ setUrlFilePath(next);
+ };
+ window.addEventListener("popstate", onNav);
+ return () => window.removeEventListener("popstate", onNav);
+ }, []);
+
+ const [selectedPath, setSelectedPath] = useState<string | null>(null);
+ useEffect(() => {
+ setSelectedPath(null);
+ setMobileView("browser");
+ lastConsumedFileRef.current = null;
+ }, [selectedWorkspace?.id]);
+
+ // When a file path appears (or changes) in the URL and workspace is ready, select it.
+ useEffect(() => {
+ if (!urlFilePath || !selectedWorkspace) return;
+ if (lastConsumedFileRef.current === urlFilePath) return;
+ lastConsumedFileRef.current = urlFilePath;
+ setSelectedPath(urlFilePath);
+ setMobileView("editor");
+ }, [urlFilePath, selectedWorkspace]);
+
+ const fileContentParams = useMemo(
+ () =>
+ selectedPath && selectedWorkspace
+ ? { projectId, companyId, workspaceId: selectedWorkspace.id, filePath: selectedPath }
+ : null,
+ [companyId, projectId, selectedWorkspace, selectedPath],
+ );
+ const fileContentResult = usePluginData<{ content: string | null; error?: string }>(
+ "fileContent",
+ fileContentParams ?? {},
+ );
+ const { data: fileContentData, refresh: refreshFileContent } = fileContentResult;
+ const writeFile = usePluginAction("writeFile");
+ const editorRef = useRef<HTMLDivElement | null>(null);
+ const viewRef = useRef<EditorView | null>(null);
+ const loadedContentRef = useRef("");
+ const [isDirty, setIsDirty] = useState(false);
+ const [isSaving, setIsSaving] = useState(false);
+ const [saveMessage, setSaveMessage] = useState<string | null>(null);
+ const [saveError, setSaveError] = useState<string | null>(null);
+ const [mobileView, setMobileView] = useState<"browser" | "editor">("browser");
+
+ useEffect(() => {
+ if (!editorRef.current) return;
+ const content = fileContentData?.content ?? "";
+ loadedContentRef.current = content;
+ setIsDirty(false);
+ setSaveMessage(null);
+ setSaveError(null);
+ if (viewRef.current) {
+ viewRef.current.destroy();
+ viewRef.current = null;
+ }
+ const view = new EditorView({
+ doc: content,
+ extensions: [
+ basicSetup,
+ javascript(),
+ isDarkMode ? editorDarkTheme : editorLightTheme,
+ syntaxHighlighting(isDarkMode ? editorDarkHighlightStyle : editorLightHighlightStyle),
+ EditorView.updateListener.of((update) => {
+ if (!update.docChanged) return;
+ const nextValue = update.state.doc.toString();
+ setIsDirty(nextValue !== loadedContentRef.current);
+ setSaveMessage(null);
+ setSaveError(null);
+ }),
+ ],
+ parent: editorRef.current,
+ });
+ viewRef.current = view;
+ return () => {
+ view.destroy();
+ viewRef.current = null;
+ };
+ }, [fileContentData?.content, selectedPath, isDarkMode]);
+
+ useEffect(() => {
+ const handleKeydown = (event: KeyboardEvent) => {
+ if (!(event.metaKey || event.ctrlKey) || event.key.toLowerCase() !== "s") {
+ return;
+ }
+ if (!selectedWorkspace || !selectedPath || !isDirty || isSaving) {
+ return;
+ }
+ event.preventDefault();
+ void handleSave();
+ };
+
+ window.addEventListener("keydown", handleKeydown);
+ return () => window.removeEventListener("keydown", handleKeydown);
+ }, [selectedWorkspace, selectedPath, isDirty, isSaving]);
+
+ async function handleSave() {
+ if (!selectedWorkspace || !selectedPath || !viewRef.current) {
+ return;
+ }
+ const content = viewRef.current.state.doc.toString();
+ setIsSaving(true);
+ setSaveError(null);
+ setSaveMessage(null);
+ try {
+ await writeFile({
+ projectId,
+ companyId,
+ workspaceId: selectedWorkspace.id,
+ filePath: selectedPath,
+ content,
+ });
+ loadedContentRef.current = content;
+ setIsDirty(false);
+ setSaveMessage("Saved");
+ refreshFileContent();
+ } catch (error) {
+ setSaveError(error instanceof Error ? error.message : String(error));
+ } finally {
+ setIsSaving(false);
+ }
+ }
+
+ return (
+ <div className="space-y-4">
+ <div className="rounded-lg border border-border bg-card p-4">
+ <label className="text-sm font-medium text-muted-foreground">Workspace</label>
+ <select
+ key={workspaceSelectKey}
+ className="mt-2 block w-full rounded-md border border-input bg-background px-3 py-2 text-sm"
+ value={resolvedWorkspaceId ?? ""}
+ onChange={(e) => setWorkspaceId(e.target.value || null)}
+ >
+ {workspaces.map((w) => {
+ const label = workspaceLabel(w);
+ return (
+ <option key={`${w.id}:${label}`} value={w.id} label={label} title={label}>
+ {label}
+ </option>
+ );
+ })}
+ </select>
+ </div>
+
+ <div
+ ref={panesRef}
+ className="min-h-0"
+ style={{
+ display: isMobile ? "block" : "grid",
+ gap: "1rem",
+ gridTemplateColumns: isMobile ? undefined : "320px minmax(0, 1fr)",
+ height: availableHeight ? `${availableHeight}px` : undefined,
+ minHeight: isMobile ? "20rem" : "26rem",
+ }}
+ >
+ <div
+ className="flex min-h-0 flex-col overflow-hidden rounded-lg border border-border bg-card"
+ style={{ display: isMobile && mobileView === "editor" ? "none" : "flex" }}
+ >
+ <div className="border-b border-border px-3 py-2 text-xs font-medium uppercase tracking-[0.12em] text-muted-foreground">
+ File Tree
+ </div>
+ <div className="min-h-0 flex-1 overflow-auto p-2">
+ {selectedWorkspace ? (
+ fileListLoading ? (
+ <p className="px-2 py-3 text-sm text-muted-foreground">Loading files...</p>
+ ) : entries.length > 0 ? (
+ <ul className="space-y-0.5">
+ {entries.map((entry) => (
+ <FileTreeNode
+ key={entry.path}
+ entry={entry}
+ companyId={companyId}
+ projectId={projectId}
+ workspaceId={selectedWorkspace.id}
+ selectedPath={selectedPath}
+ onSelect={(path) => {
+ setSelectedPath(path);
+ setMobileView("editor");
+ }}
+ />
+ ))}
+ </ul>
+ ) : (
+ <p className="px-2 py-3 text-sm text-muted-foreground">No files found in this workspace.</p>
+ )
+ ) : (
+ <p className="px-2 py-3 text-sm text-muted-foreground">Select a workspace to browse files.</p>
+ )}
+ </div>
+ </div>
+ <div
+ className="flex min-h-0 flex-col overflow-hidden rounded-lg border border-border bg-card"
+ style={{ display: isMobile && mobileView === "browser" ? "none" : "flex" }}
+ >
+ <div className="sticky top-0 z-10 flex items-center justify-between gap-3 border-b border-border bg-card px-4 py-2">
+ <div className="min-w-0">
+ <button
+ type="button"
+ className="mb-2 inline-flex rounded-md border border-input bg-background px-2 py-1 text-xs font-medium text-muted-foreground"
+ style={{ display: isMobile ? "inline-flex" : "none" }}
+ onClick={() => setMobileView("browser")}
+ >
+ Back to files
+ </button>
+ <div className="text-xs font-medium uppercase tracking-[0.12em] text-muted-foreground">Editor</div>
+ <div className="truncate text-sm text-foreground">{selectedPath ?? "No file selected"}</div>
+ </div>
+ <div className="flex items-center gap-3">
+ <button
+ type="button"
+ className="rounded-md border border-input bg-background px-3 py-1.5 text-sm font-medium text-foreground transition-colors hover:bg-accent disabled:cursor-not-allowed disabled:opacity-50"
+ disabled={!selectedWorkspace || !selectedPath || !isDirty || isSaving}
+ onClick={() => void handleSave()}
+ >
+ {isSaving ? "Saving..." : "Save"}
+ </button>
+ </div>
+ </div>
+ {isDirty || saveMessage || saveError ? (
+ <div className="border-b border-border px-4 py-2 text-xs">
+ {saveError ? (
+ <span className="text-destructive">{saveError}</span>
+ ) : saveMessage ? (
+ <span className="text-emerald-600">{saveMessage}</span>
+ ) : (
+ <span className="text-muted-foreground">Unsaved changes</span>
+ )}
+ </div>
+ ) : null}
+ {selectedPath && fileContentData?.error && fileContentData.error !== "Missing file context" ? (
+ <div className="border-b border-border px-4 py-2 text-xs text-destructive">{fileContentData.error}</div>
+ ) : null}
+ <div ref={editorRef} className="min-h-0 flex-1 overflow-auto overscroll-contain" />
+ </div>
+ </div>
+ </div>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Comment Annotation: renders detected file links below each comment
+// ---------------------------------------------------------------------------
+
+type PluginConfig = {
+ showFilesInSidebar?: boolean;
+ commentAnnotationMode: "annotation" | "contextMenu" | "both" | "none";
+};
+
+/**
+ * Per-comment annotation showing file-path-like links extracted from the
+ * comment body. Each link navigates to the project Files tab with the
+ * matching path pre-selected.
+ *
+ * Respects the `commentAnnotationMode` instance config — hidden when mode
+ * is `"contextMenu"` or `"none"`.
+ */
+function buildFileBrowserHref(prefix: string, projectId: string | null, filePath: string): string {
+ if (!projectId) return "#";
+ const tabValue = `plugin:${PLUGIN_KEY}:${FILES_TAB_SLOT_ID}`;
+ return `${prefix}/projects/${projectId}?tab=${encodeURIComponent(tabValue)}&file=${encodeURIComponent(filePath)}`;
+}
+
+function navigateToFileBrowser(href: string, event: MouseEvent<HTMLAnchorElement>) {
+ if (
+ event.defaultPrevented
+ || event.button !== 0
+ || event.metaKey
+ || event.ctrlKey
+ || event.altKey
+ || event.shiftKey
+ ) {
+ return;
+ }
+ event.preventDefault();
+ window.history.pushState({}, "", href);
+ window.dispatchEvent(new PopStateEvent("popstate"));
+}
+
+export function CommentFileLinks({ context }: PluginCommentAnnotationProps) {
+ const { data: config } = usePluginData<PluginConfig>("plugin-config", {});
+ const mode = config?.commentAnnotationMode ?? "both";
+
+ const { data } = usePluginData<{ links: string[] }>("comment-file-links", {
+ commentId: context.entityId,
+ issueId: context.parentEntityId,
+ companyId: context.companyId,
+ });
+
+ if (mode === "contextMenu" || mode === "none") return null;
+ if (!data?.links?.length) return null;
+
+ const prefix = context.companyPrefix ? `/${context.companyPrefix}` : "";
+ const projectId = context.projectId;
+
+ return (
+ <div className="flex flex-wrap items-center gap-1.5">
+ <span className="text-[10px] font-medium uppercase tracking-wider text-muted-foreground">Files:</span>
+ {data.links.map((link) => {
+ const href = buildFileBrowserHref(prefix, projectId, link);
+ return (
+ <a
+ key={link}
+ href={href}
+ onClick={(e) => navigateToFileBrowser(href, e)}
+ className="inline-flex items-center rounded-md border border-border bg-accent/30 px-1.5 py-0.5 text-xs font-mono text-primary hover:bg-accent/60 hover:underline transition-colors"
+ title={`Open ${link} in file browser`}
+ >
+ {link}
+ </a>
+ );
+ })}
+ </div>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Comment Context Menu Item: "Open in Files" action per comment
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-comment context menu item that appears in the comment "more" (⋮) menu.
+ * Extracts file paths from the comment body and, if any are found, renders
+ * a button to open the first file in the project Files tab.
+ *
+ * Respects the `commentAnnotationMode` instance config — hidden when mode
+ * is `"annotation"` or `"none"`.
+ */
+export function CommentOpenFiles({ context }: PluginCommentContextMenuItemProps) {
+ const { data: config } = usePluginData<PluginConfig>("plugin-config", {});
+ const mode = config?.commentAnnotationMode ?? "both";
+
+ const { data } = usePluginData<{ links: string[] }>("comment-file-links", {
+ commentId: context.entityId,
+ issueId: context.parentEntityId,
+ companyId: context.companyId,
+ });
+
+ if (mode === "annotation" || mode === "none") return null;
+ if (!data?.links?.length) return null;
+
+ const prefix = context.companyPrefix ? `/${context.companyPrefix}` : "";
+ const projectId = context.projectId;
+
+ return (
+ <div>
+ <div className="px-2 py-1 text-[10px] font-medium uppercase tracking-wider text-muted-foreground">
+ Files
+ </div>
+ {data.links.map((link) => {
+ const href = buildFileBrowserHref(prefix, projectId, link);
+ const fileName = link.split("/").pop() ?? link;
+ return (
+ <a
+ key={link}
+ href={href}
+ onClick={(e) => navigateToFileBrowser(href, e)}
+ className="flex w-full items-center gap-2 rounded px-2 py-1 text-xs text-foreground hover:bg-accent transition-colors"
+ title={`Open ${link} in file browser`}
+ >
+ <span className="truncate font-mono">{fileName}</span>
+ </a>
+ );
+ })}
+ </div>
+ );
+}
diff --git a/packages/plugins/examples/plugin-file-browser-example/src/worker.ts b/packages/plugins/examples/plugin-file-browser-example/src/worker.ts
new file mode 100644
index 0000000000..1c39af75bc
--- /dev/null
+++ b/packages/plugins/examples/plugin-file-browser-example/src/worker.ts
@@ -0,0 +1,226 @@
+import { definePlugin, runWorker } from "@paperclipai/plugin-sdk";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const PLUGIN_NAME = "file-browser-example";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const PATH_LIKE_PATTERN = /[\\/]/;
+const WINDOWS_DRIVE_PATH_PATTERN = /^[A-Za-z]:[\\/]/;
+
+function looksLikePath(value: string): boolean {
+ const normalized = value.trim();
+ return (PATH_LIKE_PATTERN.test(normalized) || WINDOWS_DRIVE_PATH_PATTERN.test(normalized))
+ && !UUID_PATTERN.test(normalized);
+}
+
+function sanitizeWorkspacePath(pathValue: string): string {
+ return looksLikePath(pathValue) ? pathValue.trim() : "";
+}
+
+function resolveWorkspace(workspacePath: string, requestedPath?: string): string | null {
+ const root = path.resolve(workspacePath);
+ const resolved = requestedPath ? path.resolve(root, requestedPath) : root;
+ const relative = path.relative(root, resolved);
+ if (relative.startsWith("..") || path.isAbsolute(relative)) {
+ return null;
+ }
+ return resolved;
+}
+
+/**
+ * Regex that matches file-path-like tokens in comment text.
+ * Captures tokens that either start with `.` `/` `~` or contain a `/`
+ * (directory separator), plus bare words that could be filenames with
+ * extensions (e.g. `README.md`). The file-extension check in
+ * `extractFilePaths` filters out non-file matches.
+ */
+const FILE_PATH_REGEX = /(?:^|[\s(`"'])([^\s,;)}`"'>\]]*\/[^\s,;)}`"'>\]]+|[.\/~][^\s,;)}`"'>\]]+|[a-zA-Z0-9_-]+\.[a-zA-Z0-9]{1,10}(?:\/[^\s,;)}`"'>\]]+)?)/g;
+
+/** Common file extensions to recognise path-like tokens as actual file references. */
+const FILE_EXTENSION_REGEX = /\.[a-zA-Z0-9]{1,10}$/;
+
+/**
+ * Tokens that look like paths but are almost certainly URL route segments
+ * (e.g. `/projects/abc`, `/settings`, `/dashboard`).
+ */
+const URL_ROUTE_PATTERN = /^\/(?:projects|issues|agents|settings|dashboard|plugins|api|auth|admin)\b/i;
+
+function extractFilePaths(body: string): string[] {
+ const paths = new Set<string>();
+ for (const match of body.matchAll(FILE_PATH_REGEX)) {
+ const raw = match[1];
+ // Strip trailing punctuation that isn't part of a path
+ const cleaned = raw.replace(/[.:,;!?)]+$/, "");
+ if (cleaned.length <= 1) continue;
+ // Must have a file extension (e.g. .ts, .json, .md)
+ if (!FILE_EXTENSION_REGEX.test(cleaned)) continue;
+ // Skip things that look like URL routes
+ if (URL_ROUTE_PATTERN.test(cleaned)) continue;
+ paths.add(cleaned);
+ }
+ return [...paths];
+}
+
+const plugin = definePlugin({
+ async setup(ctx) {
+ ctx.logger.info(`${PLUGIN_NAME} plugin setup`);
+
+ // Expose the current plugin config so UI components can read the
+ // commentAnnotationMode setting and hide themselves when disabled.
+ ctx.data.register("plugin-config", async () => {
+ const config = await ctx.state.get({ scopeKind: "instance", stateKey: "config" }) as Record<string, unknown> | null;
+ return {
+ showFilesInSidebar: config?.showFilesInSidebar === true,
+ commentAnnotationMode: config?.commentAnnotationMode ?? "both",
+ };
+ });
+
+ // Fetch a comment by ID and extract file-path-like tokens from its body.
+ ctx.data.register("comment-file-links", async (params: Record<string, unknown>) => {
+ const commentId = typeof params.commentId === "string" ? params.commentId : "";
+ const issueId = typeof params.issueId === "string" ? params.issueId : "";
+ const companyId = typeof params.companyId === "string" ? params.companyId : "";
+ if (!commentId || !issueId || !companyId) return { links: [] };
+ try {
+ const comments = await ctx.issues.listComments(issueId, companyId);
+ const comment = comments.find((c) => c.id === commentId);
+ if (!comment?.body) return { links: [] };
+ return { links: extractFilePaths(comment.body) };
+ } catch (err) {
+ ctx.logger.warn("Failed to fetch comment for file link extraction", { commentId, error: String(err) });
+ return { links: [] };
+ }
+ });
+
+ ctx.data.register("workspaces", async (params: Record<string, unknown>) => {
+ const projectId = params.projectId as string;
+ const companyId = typeof params.companyId === "string" ? params.companyId : "";
+ if (!projectId || !companyId) return [];
+ const workspaces = await ctx.projects.listWorkspaces(projectId, companyId);
+ return workspaces.map((w) => ({
+ id: w.id,
+ projectId: w.projectId,
+ name: w.name,
+ path: sanitizeWorkspacePath(w.path),
+ isPrimary: w.isPrimary,
+ }));
+ });
+
+ ctx.data.register(
+ "fileList",
+ async (params: Record<string, unknown>) => {
+ const projectId = params.projectId as string;
+ const companyId = typeof params.companyId === "string" ? params.companyId : "";
+ const workspaceId = params.workspaceId as string;
+ const directoryPath = typeof params.directoryPath === "string" ? params.directoryPath : "";
+ if (!projectId || !companyId || !workspaceId) return { entries: [] };
+ const workspaces = await ctx.projects.listWorkspaces(projectId, companyId);
+ const workspace = workspaces.find((w) => w.id === workspaceId);
+ if (!workspace) return { entries: [] };
+ const workspacePath = sanitizeWorkspacePath(workspace.path);
+ if (!workspacePath) return { entries: [] };
+ const dirPath = resolveWorkspace(workspacePath, directoryPath);
+ if (!dirPath) {
+ return { entries: [] };
+ }
+ if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) {
+ return { entries: [] };
+ }
+ const names = fs.readdirSync(dirPath).sort((a, b) => a.localeCompare(b));
+ const entries = names.map((name) => {
+ const full = path.join(dirPath, name);
+ const stat = fs.lstatSync(full);
+ const relativePath = path.relative(workspacePath, full);
+ return {
+ name,
+ path: relativePath,
+ isDirectory: stat.isDirectory(),
+ };
+ }).sort((a, b) => {
+ if (a.isDirectory !== b.isDirectory) return a.isDirectory ? -1 : 1;
+ return a.name.localeCompare(b.name);
+ });
+ return { entries };
+ },
+ );
+
+ ctx.data.register(
+ "fileContent",
+ async (params: Record<string, unknown>) => {
+ const projectId = params.projectId as string;
+ const companyId = typeof params.companyId === "string" ? params.companyId : "";
+ const workspaceId = params.workspaceId as string;
+ const filePath = params.filePath as string;
+ if (!projectId || !companyId || !workspaceId || !filePath) {
+ return { content: null, error: "Missing file context" };
+ }
+ const workspaces = await ctx.projects.listWorkspaces(projectId, companyId);
+ const workspace = workspaces.find((w) => w.id === workspaceId);
+ if (!workspace) return { content: null, error: "Workspace not found" };
+ const workspacePath = sanitizeWorkspacePath(workspace.path);
+ if (!workspacePath) return { content: null, error: "Workspace has no path" };
+ const fullPath = resolveWorkspace(workspacePath, filePath);
+ if (!fullPath) {
+ return { content: null, error: "Path outside workspace" };
+ }
+ try {
+ const content = fs.readFileSync(fullPath, "utf-8");
+ return { content };
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ return { content: null, error: message };
+ }
+ },
+ );
+
+ ctx.actions.register(
+ "writeFile",
+ async (params: Record<string, unknown>) => {
+ const projectId = params.projectId as string;
+ const companyId = typeof params.companyId === "string" ? params.companyId : "";
+ const workspaceId = params.workspaceId as string;
+ const filePath = typeof params.filePath === "string" ? params.filePath.trim() : "";
+ if (!filePath) {
+ throw new Error("filePath must be a non-empty string");
+ }
+ const content = typeof params.content === "string" ? params.content : null;
+ if (!projectId || !companyId || !workspaceId) {
+ throw new Error("Missing workspace context");
+ }
+ const workspaces = await ctx.projects.listWorkspaces(projectId, companyId);
+ const workspace = workspaces.find((w) => w.id === workspaceId);
+ if (!workspace) {
+ throw new Error("Workspace not found");
+ }
+ const workspacePath = sanitizeWorkspacePath(workspace.path);
+ if (!workspacePath) {
+ throw new Error("Workspace has no path");
+ }
+ if (content === null) {
+ throw new Error("Missing file content");
+ }
+ const fullPath = resolveWorkspace(workspacePath, filePath);
+ if (!fullPath) {
+ throw new Error("Path outside workspace");
+ }
+ const stat = fs.statSync(fullPath);
+ if (!stat.isFile()) {
+ throw new Error("Selected path is not a file");
+ }
+ fs.writeFileSync(fullPath, content, "utf-8");
+ return {
+ ok: true,
+ path: filePath,
+ bytes: Buffer.byteLength(content, "utf-8"),
+ };
+ },
+ );
+ },
+
+ async onHealth() {
+ return { status: "ok", message: `${PLUGIN_NAME} ready` };
+ },
+});
+
+export default plugin;
+runWorker(plugin, import.meta.url);
diff --git a/packages/plugins/examples/plugin-file-browser-example/tsconfig.json b/packages/plugins/examples/plugin-file-browser-example/tsconfig.json
new file mode 100644
index 0000000000..3482c1738c
--- /dev/null
+++ b/packages/plugins/examples/plugin-file-browser-example/tsconfig.json
@@ -0,0 +1,10 @@
+{
+ "extends": "../../../../tsconfig.json",
+ "compilerOptions": {
+ "outDir": "dist",
+ "rootDir": "src",
+ "lib": ["ES2023", "DOM"],
+ "jsx": "react-jsx"
+ },
+ "include": ["src"]
+}
diff --git a/packages/plugins/examples/plugin-hello-world-example/README.md b/packages/plugins/examples/plugin-hello-world-example/README.md
new file mode 100644
index 0000000000..889c9d257d
--- /dev/null
+++ b/packages/plugins/examples/plugin-hello-world-example/README.md
@@ -0,0 +1,38 @@
+# @paperclipai/plugin-hello-world-example
+
+First-party reference plugin showing the smallest possible UI extension.
+
+## What It Demonstrates
+
+- a manifest with a `dashboardWidget` UI slot
+- `entrypoints.ui` wiring for plugin UI bundles
+- a minimal React widget rendered in the Paperclip dashboard
+- reading host context (`companyId`) from `PluginWidgetProps`
+- worker lifecycle hooks (`setup`, `onHealth`) for basic runtime observability
+
+## API Surface
+
+- This example does not add custom HTTP endpoints.
+- The widget is discovered/rendered through host-managed plugin APIs (for example `GET /api/plugins/ui-contributions`).
+
+## Notes
+
+This is intentionally simple and is designed as the quickest "hello world" starting point for UI plugin authors.
+It is a repo-local example plugin for development, not a plugin that should be assumed to ship in generic production builds.
+
+## Local Install (Dev)
+
+From the repo root, build the plugin and install it by local path:
+
+```bash
+pnpm --filter @paperclipai/plugin-hello-world-example build
+pnpm paperclipai plugin install ./packages/plugins/examples/plugin-hello-world-example
+```
+
+**Local development notes:**
+
+- **Build first.** The host resolves the worker from the manifest `entrypoints.worker` (e.g. `./dist/worker.js`). Run `pnpm build` in the plugin directory before installing so the worker file exists.
+- **Dev-only install path.** This local-path install flow assumes a source checkout with this example package present on disk. For deployed installs, publish an npm package instead of relying on the monorepo example path.
+- **Reinstall after pulling.** If you installed a plugin by local path before the server stored `package_path`, the plugin may show status **error** (worker not found). Uninstall and install again so the server persists the path and can activate the plugin:
+ `pnpm paperclipai plugin uninstall paperclip.hello-world-example --force` then
+ `pnpm paperclipai plugin install ./packages/plugins/examples/plugin-hello-world-example`.
diff --git a/packages/plugins/examples/plugin-hello-world-example/package.json b/packages/plugins/examples/plugin-hello-world-example/package.json
new file mode 100644
index 0000000000..5d055caa35
--- /dev/null
+++ b/packages/plugins/examples/plugin-hello-world-example/package.json
@@ -0,0 +1,35 @@
+{
+ "name": "@paperclipai/plugin-hello-world-example",
+ "version": "0.1.0",
+ "description": "First-party reference plugin that adds a Hello World dashboard widget",
+ "type": "module",
+ "private": true,
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "paperclipPlugin": {
+ "manifest": "./dist/manifest.js",
+ "worker": "./dist/worker.js",
+ "ui": "./dist/ui/"
+ },
+ "scripts": {
+ "prebuild": "node ../../../../scripts/ensure-plugin-build-deps.mjs",
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "typecheck": "pnpm --filter @paperclipai/plugin-sdk build && tsc --noEmit"
+ },
+ "dependencies": {
+ "@paperclipai/plugin-sdk": "workspace:*"
+ },
+ "devDependencies": {
+ "@types/node": "^24.6.0",
+ "@types/react": "^19.0.8",
+ "@types/react-dom": "^19.0.3",
+ "react": "^19.0.0",
+ "react-dom": "^19.0.0",
+ "typescript": "^5.7.3"
+ },
+ "peerDependencies": {
+ "react": ">=18"
+ }
+}
diff --git a/packages/plugins/examples/plugin-hello-world-example/src/index.ts b/packages/plugins/examples/plugin-hello-world-example/src/index.ts
new file mode 100644
index 0000000000..f301da5d92
--- /dev/null
+++ b/packages/plugins/examples/plugin-hello-world-example/src/index.ts
@@ -0,0 +1,2 @@
+export { default as manifest } from "./manifest.js";
+export { default as worker } from "./worker.js";
diff --git a/packages/plugins/examples/plugin-hello-world-example/src/manifest.ts b/packages/plugins/examples/plugin-hello-world-example/src/manifest.ts
new file mode 100644
index 0000000000..2fcd80779c
--- /dev/null
+++ b/packages/plugins/examples/plugin-hello-world-example/src/manifest.ts
@@ -0,0 +1,39 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+
+/**
+ * Stable plugin ID used by host registration and namespacing.
+ */
+const PLUGIN_ID = "paperclip.hello-world-example";
+const PLUGIN_VERSION = "0.1.0";
+const DASHBOARD_WIDGET_SLOT_ID = "hello-world-dashboard-widget";
+const DASHBOARD_WIDGET_EXPORT_NAME = "HelloWorldDashboardWidget";
+
+/**
+ * Minimal manifest demonstrating a UI-only plugin with one dashboard widget slot.
+ */
+const manifest: PaperclipPluginManifestV1 = {
+ id: PLUGIN_ID,
+ apiVersion: 1,
+ version: PLUGIN_VERSION,
+ displayName: "Hello World Widget (Example)",
+ description: "Reference UI plugin that adds a simple Hello World widget to the Paperclip dashboard.",
+ author: "Paperclip",
+ categories: ["ui"],
+ capabilities: ["ui.dashboardWidget.register"],
+ entrypoints: {
+ worker: "./dist/worker.js",
+ ui: "./dist/ui",
+ },
+ ui: {
+ slots: [
+ {
+ type: "dashboardWidget",
+ id: DASHBOARD_WIDGET_SLOT_ID,
+ displayName: "Hello World",
+ exportName: DASHBOARD_WIDGET_EXPORT_NAME,
+ },
+ ],
+ },
+};
+
+export default manifest;
diff --git a/packages/plugins/examples/plugin-hello-world-example/src/ui/index.tsx b/packages/plugins/examples/plugin-hello-world-example/src/ui/index.tsx
new file mode 100644
index 0000000000..10e12fb0d4
--- /dev/null
+++ b/packages/plugins/examples/plugin-hello-world-example/src/ui/index.tsx
@@ -0,0 +1,17 @@
+import type { PluginWidgetProps } from "@paperclipai/plugin-sdk/ui";
+
+const WIDGET_LABEL = "Hello world plugin widget";
+
+/**
+ * Example dashboard widget showing the smallest possible UI contribution.
+ */
+export function HelloWorldDashboardWidget({ context }: PluginWidgetProps) {
+ return (
+ <section aria-label={WIDGET_LABEL}>
+ <strong>Hello world</strong>
+ <div>This widget was added by @paperclipai/plugin-hello-world-example.</div>
+ {/* Include host context so authors can see where scoped IDs come from. */}
+ <div>Company context: {context.companyId}</div>
+ </section>
+ );
+}
diff --git a/packages/plugins/examples/plugin-hello-world-example/src/worker.ts b/packages/plugins/examples/plugin-hello-world-example/src/worker.ts
new file mode 100644
index 0000000000..07c7fbeaf3
--- /dev/null
+++ b/packages/plugins/examples/plugin-hello-world-example/src/worker.ts
@@ -0,0 +1,27 @@
+import { definePlugin, runWorker } from "@paperclipai/plugin-sdk";
+
+const PLUGIN_NAME = "hello-world-example";
+const HEALTH_MESSAGE = "Hello World example plugin ready";
+
+/**
+ * Worker lifecycle hooks for the Hello World reference plugin.
+ * This stays intentionally small so new authors can copy the shape quickly.
+ */
+const plugin = definePlugin({
+ /**
+ * Called when the host starts the plugin worker.
+ */
+ async setup(ctx) {
+ ctx.logger.info(`${PLUGIN_NAME} plugin setup complete`);
+ },
+
+ /**
+ * Called by the host health probe endpoint.
+ */
+ async onHealth() {
+ return { status: "ok", message: HEALTH_MESSAGE };
+ },
+});
+
+export default plugin;
+runWorker(plugin, import.meta.url);
diff --git a/packages/plugins/examples/plugin-hello-world-example/tsconfig.json b/packages/plugins/examples/plugin-hello-world-example/tsconfig.json
new file mode 100644
index 0000000000..3482c1738c
--- /dev/null
+++ b/packages/plugins/examples/plugin-hello-world-example/tsconfig.json
@@ -0,0 +1,10 @@
+{
+ "extends": "../../../../tsconfig.json",
+ "compilerOptions": {
+ "outDir": "dist",
+ "rootDir": "src",
+ "lib": ["ES2023", "DOM"],
+ "jsx": "react-jsx"
+ },
+ "include": ["src"]
+}
diff --git a/packages/plugins/sdk/README.md b/packages/plugins/sdk/README.md
new file mode 100644
index 0000000000..66cdebcb54
--- /dev/null
+++ b/packages/plugins/sdk/README.md
@@ -0,0 +1,959 @@
+# `@paperclipai/plugin-sdk`
+
+Official TypeScript SDK for Paperclip plugin authors.
+
+- **Worker SDK:** `@paperclipai/plugin-sdk` — `definePlugin`, context, lifecycle
+- **UI SDK:** `@paperclipai/plugin-sdk/ui` — React hooks, components, slot props
+- **Testing:** `@paperclipai/plugin-sdk/testing` — in-memory host harness
+- **Bundlers:** `@paperclipai/plugin-sdk/bundlers` — esbuild/rollup presets
+- **Dev server:** `@paperclipai/plugin-sdk/dev-server` — static UI server + SSE reload
+
+Reference: `doc/plugins/PLUGIN_SPEC.md`
+
+## Package surface
+
+| Import | Purpose |
+|--------|--------|
+| `@paperclipai/plugin-sdk` | Worker entry: `definePlugin`, `runWorker`, context types, protocol helpers |
+| `@paperclipai/plugin-sdk/ui` | UI entry: `usePluginData`, `usePluginAction`, `usePluginStream`, `useHostContext`, shared components |
+| `@paperclipai/plugin-sdk/ui/hooks` | Hooks only |
+| `@paperclipai/plugin-sdk/ui/types` | UI types and slot prop interfaces |
+| `@paperclipai/plugin-sdk/ui/components` | `MetricCard`, `StatusBadge`, `Spinner`, `ErrorBoundary`, etc. |
+| `@paperclipai/plugin-sdk/testing` | `createTestHarness` for unit/integration tests |
+| `@paperclipai/plugin-sdk/bundlers` | `createPluginBundlerPresets` for worker/manifest/ui builds |
+| `@paperclipai/plugin-sdk/dev-server` | `startPluginDevServer`, `getUiBuildSnapshot` |
+| `@paperclipai/plugin-sdk/protocol` | JSON-RPC protocol types and helpers (advanced) |
+| `@paperclipai/plugin-sdk/types` | Worker context and API types (advanced) |
+
+## Manifest entrypoints
+
+In your plugin manifest you declare:
+
+- **`entrypoints.worker`** (required) — Path to the worker bundle (e.g. `dist/worker.js`). The host loads this and calls `setup(ctx)`.
+- **`entrypoints.ui`** (required if you use UI) — Path to the UI bundle directory. The host loads components from here for slots and launchers.
+
+## Install
+
+```bash
+pnpm add @paperclipai/plugin-sdk
+```
+
+## Current deployment caveats
+
+The SDK is stable enough for local development and first-party examples, but the runtime deployment model is still early.
+
+- Local-path installs and the repo example plugins are development workflows. They assume the plugin source checkout exists on disk.
+- For deployed plugins, publish an npm package and install that package into the Paperclip instance at runtime.
+- The current host runtime expects a writable filesystem, `npm` available at runtime, and network access to the package registry used for plugin installation.
+- Dynamic plugin install is currently best suited to single-node persistent deployments. Multi-instance cloud deployments still need a shared artifact/distribution model before runtime installs are reliable across nodes.
+
+If you are authoring a plugin for others to deploy, treat npm-packaged installation as the supported path and treat repo-local example installs as a development convenience.
+
+## Worker quick start
+
+```ts
+import { definePlugin, runWorker } from "@paperclipai/plugin-sdk";
+
+const plugin = definePlugin({
+ async setup(ctx) {
+ ctx.events.on("issue.created", async (event) => {
+ ctx.logger.info("Issue created", { issueId: event.entityId });
+ });
+
+ ctx.data.register("health", async () => ({ status: "ok" }));
+ ctx.actions.register("ping", async () => ({ pong: true }));
+
+ ctx.tools.register("calculator", {
+ displayName: "Calculator",
+ description: "Basic math",
+ parametersSchema: {
+ type: "object",
+ properties: { a: { type: "number" }, b: { type: "number" } },
+ required: ["a", "b"]
+ }
+ }, async (params) => {
+ const { a, b } = params as { a: number; b: number };
+ return { content: `Result: ${a + b}`, data: { result: a + b } };
+ });
+ },
+});
+
+export default plugin;
+runWorker(plugin, import.meta.url);
+```
+
+**Note:** `runWorker(plugin, import.meta.url)` must be called so that when the host runs your worker (e.g. `node dist/worker.js`), the RPC host starts and the process stays alive. When the file is imported (e.g. for tests), the main-module check prevents the host from starting.
+
+### Worker lifecycle and context
+
+**Lifecycle (definePlugin):**
+
+| Hook | Purpose |
+|------|--------|
+| `setup(ctx)` | **Required.** Called once at startup. Register event handlers, jobs, data/actions/tools, etc. |
+| `onHealth?()` | Optional. Return `{ status, message?, details? }` for health dashboard. |
+| `onConfigChanged?(newConfig)` | Optional. Apply new config without restart; if omitted, host restarts worker. |
+| `onShutdown?()` | Optional. Clean up before process exit (limited time window). |
+| `onValidateConfig?(config)` | Optional. Return `{ ok, warnings?, errors? }` for settings UI / Test Connection. |
+| `onWebhook?(input)` | Optional. Handle `POST /api/plugins/:pluginId/webhooks/:endpointKey`; required if webhooks declared. |
+
+**Context (`ctx`) in setup:** `config`, `events`, `jobs`, `launchers`, `http`, `secrets`, `assets`, `activity`, `state`, `entities`, `projects`, `companies`, `issues`, `agents`, `goals`, `data`, `actions`, `streams`, `tools`, `metrics`, `logger`, `manifest`. All host APIs are capability-gated; declare capabilities in the manifest.
+
+**Agents:** `ctx.agents.invoke(agentId, companyId, opts)` for one-shot invocation. `ctx.agents.sessions` for two-way chat: `create`, `list`, `sendMessage` (with streaming `onEvent` callback), `close`. See the [Plugin Authoring Guide](../../doc/plugins/PLUGIN_AUTHORING_GUIDE.md#agent-sessions-two-way-chat) for details.
+
+**Jobs:** Declare in `manifest.jobs` with `jobKey`, `displayName`, `schedule` (cron). Register handler with `ctx.jobs.register(jobKey, fn)`. **Webhooks:** Declare in `manifest.webhooks` with `endpointKey`; handle in `onWebhook(input)`. **State:** `ctx.state.get/set/delete(scopeKey)`; scope kinds: `instance`, `company`, `project`, `project_workspace`, `agent`, `issue`, `goal`, `run`.
+
+## Events
+
+Subscribe in `setup` with `ctx.events.on(name, handler)` or `ctx.events.on(name, filter, handler)`. Emit plugin-scoped events with `ctx.events.emit(name, companyId, payload)` (requires `events.emit`).
+
+**Core domain events (subscribe with `events.subscribe`):**
+
+| Event | Typical entity |
+|-------|-----------------|
+| `company.created`, `company.updated` | company |
+| `project.created`, `project.updated` | project |
+| `project.workspace_created`, `project.workspace_updated`, `project.workspace_deleted` | project_workspace |
+| `issue.created`, `issue.updated`, `issue.comment.created` | issue |
+| `agent.created`, `agent.updated`, `agent.status_changed` | agent |
+| `agent.run.started`, `agent.run.finished`, `agent.run.failed`, `agent.run.cancelled` | run |
+| `goal.created`, `goal.updated` | goal |
+| `approval.created`, `approval.decided` | approval |
+| `cost_event.created` | cost |
+| `activity.logged` | activity |
+
+**Plugin-to-plugin:** Subscribe to `plugin.<pluginId>.<eventName>` (e.g. `plugin.acme.linear.sync-done`). Emit with `ctx.events.emit("sync-done", companyId, payload)`; the host namespaces it automatically.
+
+**Filter (optional):** Pass a second argument to `on()`: `{ projectId?, companyId?, agentId? }` so the host only delivers matching events.
+
+**Company-scoped delivery:** Events with a `companyId` are only delivered to plugins that are enabled for that company. If a company has disabled a plugin via settings, that plugin's handlers will not receive events belonging to that company. Events without a `companyId` are delivered to all subscribers.
+
+## Scheduled (recurring) jobs
+
+Plugins can declare **scheduled jobs** that the host runs on a cron schedule. Use this for recurring tasks like syncs, digest reports, or cleanup.
+
+1. **Capability:** Add `jobs.schedule` to `manifest.capabilities`.
+2. **Declare jobs** in `manifest.jobs`: each entry has `jobKey`, `displayName`, optional `description`, and `schedule` (a 5-field cron expression).
+3. **Register a handler** in `setup()` with `ctx.jobs.register(jobKey, async (job) => { ... })`.
+
+**Cron format** (5 fields: minute, hour, day-of-month, month, day-of-week):
+
+| Field | Values | Example |
+|-------------|----------|---------|
+| minute | 0–59 | `0`, `*/15` |
+| hour | 0–23 | `2`, `*` |
+| day of month | 1–31 | `1`, `*` |
+| month | 1–12 | `*` |
+| day of week | 0–6 (Sun=0) | `*`, `1-5` |
+
+Examples: `"0 * * * *"` = every hour at minute 0; `"*/5 * * * *"` = every 5 minutes; `"0 2 * * *"` = daily at 2:00.
+
+**Job handler context** (`PluginJobContext`):
+
+| Field | Type | Description |
+|-------------|----------|-------------|
+| `jobKey` | string | Matches the manifest declaration. |
+| `runId` | string | UUID for this run. |
+| `trigger` | `"schedule" \| "manual" \| "retry"` | What caused this run. |
+| `scheduledAt` | string | ISO 8601 time when the run was scheduled. |
+
+Runs can be triggered by the **schedule**, **manually** from the UI/API, or as a **retry** (when an operator re-runs a job after a failure). Re-throw from the handler to mark the run as failed; the host records the failure. The host does not automatically retry—operators can trigger another run manually from the UI or API.
+
+Example:
+
+**Manifest** — include `jobs.schedule` and declare the job:
+
+```ts
+// In your manifest (e.g. manifest.ts):
+const manifest = {
+ // ...
+ capabilities: ["jobs.schedule", "plugin.state.write"],
+ jobs: [
+ {
+ jobKey: "heartbeat",
+ displayName: "Heartbeat",
+ description: "Runs every 5 minutes",
+ schedule: "*/5 * * * *",
+ },
+ ],
+ // ...
+};
+```
+
+**Worker** — register the handler in `setup()`:
+
+```ts
+ctx.jobs.register("heartbeat", async (job) => {
+ ctx.logger.info("Heartbeat run", { runId: job.runId, trigger: job.trigger });
+ await ctx.state.set({ scopeKind: "instance", stateKey: "last-heartbeat" }, new Date().toISOString());
+});
+```
+
+## UI slots and launchers
+
+Slots are mount points for plugin React components. Launchers are host-rendered entry points (buttons, menu items) that open plugin UI. Declare slots in `manifest.ui.slots` with `type`, `id`, `displayName`, `exportName`; for context-sensitive slots add `entityTypes`. Declare launchers in `manifest.ui.launchers` (or legacy `manifest.launchers`).
+
+### Slot types / launcher placement zones
+
+The same set of values is used as **slot types** (where a component mounts) and **launcher placement zones** (where a launcher can appear). Hierarchy:
+
+| Slot type / placement zone | Scope | Entity types (when context-sensitive) |
+|----------------------------|-------|---------------------------------------|
+| `page` | Global | — |
+| `sidebar` | Global | — |
+| `sidebarPanel` | Global | — |
+| `settingsPage` | Global | — |
+| `dashboardWidget` | Global | — |
+| `detailTab` | Entity | `project`, `issue`, `agent`, `goal`, `run` |
+| `taskDetailView` | Entity | (task/issue context) |
+| `commentAnnotation` | Entity | `comment` |
+| `commentContextMenuItem` | Entity | `comment` |
+| `projectSidebarItem` | Entity | `project` |
+| `toolbarButton` | Entity | varies by host surface |
+| `contextMenuItem` | Entity | varies by host surface |
+
+**Scope** describes whether the slot requires an entity to render. **Global** slots render without a specific entity but still receive the active `companyId` through `PluginHostContext` — use it to scope data fetches to the current company. **Entity** slots additionally require `entityId` and `entityType` (e.g. a detail tab on a specific issue).
+
+**Entity types** (for `entityTypes` on slots): `project` \| `issue` \| `agent` \| `goal` \| `run` \| `comment`. Full list: import `PLUGIN_UI_SLOT_TYPES` and `PLUGIN_UI_SLOT_ENTITY_TYPES` from `@paperclipai/plugin-sdk`.
+
+### Slot component descriptions
+
+#### `page`
+
+A full-page extension mounted at `/plugins/:pluginId` (global) or `/:company/plugins/:pluginId` (company-scoped). Use this for rich, standalone plugin experiences such as dashboards, configuration wizards, or multi-step workflows. Receives `PluginPageProps` with `context.companyId` set to the active company. Requires the `ui.page.register` capability.
+
+#### `sidebar`
+
+Adds a navigation-style entry to the main company sidebar navigation area, rendered alongside the core nav items (Dashboard, Issues, Goals, etc.). Use this for lightweight, always-visible links or status indicators that feel native to the sidebar. Receives `PluginSidebarProps` with `context.companyId` set to the active company. Requires the `ui.sidebar.register` capability.
+
+#### `sidebarPanel`
+
+Renders richer inline content in a dedicated panel area below the company sidebar navigation sections. Use this for mini-widgets, summary cards, quick-action panels, or at-a-glance status views that need more vertical space than a nav link. Receives `context.companyId` set to the active company via `useHostContext()`. Requires the `ui.sidebar.register` capability.
+
+#### `settingsPage`
+
+Replaces the auto-generated JSON Schema settings form with a custom React component. Use this when the default form is insufficient — for example, when your plugin needs multi-step configuration, OAuth flows, "Test Connection" buttons, or rich input controls. Receives `PluginSettingsPageProps` with `context.companyId` set to the active company. The component is responsible for reading and writing config through the bridge (via `usePluginData` and `usePluginAction`).
+
+#### `dashboardWidget`
+
+A card or section rendered on the main dashboard. Use this for at-a-glance metrics, status indicators, or summary views that surface plugin data alongside core Paperclip information. Receives `PluginWidgetProps` with `context.companyId` set to the active company. Requires the `ui.dashboardWidget.register` capability.
+
+#### `detailTab`
+
+An additional tab on a project, issue, agent, goal, or run detail page. Rendered when the user navigates to that entity's detail view. Receives `PluginDetailTabProps` with `context.companyId` set to the active company and `context.entityId` / `context.entityType` guaranteed to be non-null, so you can immediately scope data fetches to the relevant entity. Specify which entity types the tab applies to via the `entityTypes` array in the manifest slot declaration. Requires the `ui.detailTab.register` capability.
+
+#### `taskDetailView`
+
+A specialized slot rendered in the context of a task or issue detail view. Similar to `detailTab` but designed for inline content within the task detail layout rather than a separate tab. Receives `context.companyId`, `context.entityId`, and `context.entityType` like `detailTab`. Requires the `ui.detailTab.register` capability.
+
+#### `projectSidebarItem`
+
+A link or small component rendered **once per project** under that project's row in the sidebar Projects list. Use this to add project-scoped navigation entries (e.g. "Files", "Linear Sync") that deep-link into a plugin detail tab: `/:company/projects/:projectRef?tab=plugin:<key>:<slotId>`. Receives `PluginProjectSidebarItemProps` with `context.companyId` set to the active company, `context.entityId` set to the project id, and `context.entityType` set to `"project"`. Use the optional `order` field in the manifest slot to control sort position. Requires the `ui.sidebar.register` capability.
+
+#### `toolbarButton`
+
+A button rendered in the toolbar of a host surface (e.g. project detail, issue detail). Use this for short-lived, contextual actions like triggering a sync, opening a picker, or running a quick command. The component can open a plugin-owned modal internally for confirmations or compact forms. Receives `context.companyId` set to the active company; entity context varies by host surface. Requires the `ui.action.register` capability.
+
+#### `contextMenuItem`
+
+An entry added to a right-click or overflow context menu on a host surface. Use this for secondary actions that apply to the entity under the cursor (e.g. "Copy to Linear", "Re-run analysis"). Receives `context.companyId` set to the active company; entity context varies by host surface. Requires the `ui.action.register` capability.
+
+#### `commentAnnotation`
+
+A per-comment annotation region rendered below each individual comment in the issue detail timeline. Use this to augment comments with parsed file links, sentiment badges, inline actions, or any per-comment metadata. Receives `PluginCommentAnnotationProps` with `context.entityId` set to the comment UUID, `context.entityType` set to `"comment"`, `context.parentEntityId` set to the parent issue UUID, `context.projectId` set to the issue's project (if any), and `context.companyPrefix` set to the active company slug. Requires the `ui.commentAnnotation.register` capability.
+
+#### `commentContextMenuItem`
+
+A per-comment context menu item rendered in the "more" dropdown menu (⋮) on each comment in the issue detail timeline. Use this to add per-comment actions such as "Create sub-issue from comment", "Translate", "Flag for review", or custom plugin actions. Receives `PluginCommentContextMenuItemProps` with `context.entityId` set to the comment UUID, `context.entityType` set to `"comment"`, `context.parentEntityId` set to the parent issue UUID, `context.projectId` set to the issue's project (if any), and `context.companyPrefix` set to the active company slug. Plugins can open drawers, modals, or popovers scoped to that comment. The ⋮ menu button only appears on comments where at least one plugin renders visible content. Requires the `ui.action.register` capability.
+
+### Launcher actions and render options
+
+| Launcher action | Description |
+|-----------------|-------------|
+| `navigate` | Navigate to a route (plugin or host). |
+| `openModal` | Open a modal. |
+| `openDrawer` | Open a drawer. |
+| `openPopover` | Open a popover. |
+| `performAction` | Run an action (e.g. call plugin). |
+| `deepLink` | Deep link to plugin or external URL. |
+
+| Render option | Values | Description |
+|---------------|--------|-------------|
+| `environment` | `hostInline`, `hostOverlay`, `hostRoute`, `external`, `iframe` | Container the launcher expects after activation. |
+| `bounds` | `inline`, `compact`, `default`, `wide`, `full` | Size hint for overlays/drawers. |
+
+### Capabilities
+
+Declare in `manifest.capabilities`. Grouped by scope:
+
+| Scope | Capability |
+|-------|------------|
+| **Company** | `companies.read` |
+| | `projects.read` |
+| | `project.workspaces.read` |
+| | `issues.read` |
+| | `issue.comments.read` |
+| | `agents.read` |
+| | `goals.read` |
+| | `goals.create` |
+| | `goals.update` |
+| | `activity.read` |
+| | `costs.read` |
+| | `issues.create` |
+| | `issues.update` |
+| | `issue.comments.create` |
+| | `assets.write` |
+| | `assets.read` |
+| | `activity.log.write` |
+| | `metrics.write` |
+| **Instance** | `instance.settings.register` |
+| | `plugin.state.read` |
+| | `plugin.state.write` |
+| **Runtime** | `events.subscribe` |
+| | `events.emit` |
+| | `jobs.schedule` |
+| | `webhooks.receive` |
+| | `http.outbound` |
+| | `secrets.read-ref` |
+| **Agent** | `agent.tools.register` |
+| | `agents.invoke` |
+| | `agent.sessions.create` |
+| | `agent.sessions.list` |
+| | `agent.sessions.send` |
+| | `agent.sessions.close` |
+| **UI** | `ui.sidebar.register` |
+| | `ui.page.register` |
+| | `ui.detailTab.register` |
+| | `ui.dashboardWidget.register` |
+| | `ui.commentAnnotation.register` |
+| | `ui.action.register` |
+
+Full list in code: import `PLUGIN_CAPABILITIES` from `@paperclipai/plugin-sdk`.
+
+## UI quick start
+
+```tsx
+import { usePluginData, usePluginAction, MetricCard } from "@paperclipai/plugin-sdk/ui";
+
+export function DashboardWidget() {
+ const { data } = usePluginData<{ status: string }>("health");
+ const ping = usePluginAction("ping");
+ return (
+ <div>
+ <MetricCard label="Health" value={data?.status ?? "unknown"} />
+ <button onClick={() => void ping()}>Ping</button>
+ </div>
+ );
+}
+```
+
+### Hooks reference
+
+#### `usePluginData<T>(key, params?)`
+
+Fetches data from the worker's registered `getData` handler. Re-fetches when `params` changes. Returns `{ data, loading, error, refresh }`.
+
+```tsx
+import { usePluginData, Spinner, StatusBadge } from "@paperclipai/plugin-sdk/ui";
+
+interface SyncStatus {
+ lastSyncAt: string;
+ syncedCount: number;
+ healthy: boolean;
+}
+
+export function SyncStatusWidget({ context }: PluginWidgetProps) {
+ const { data, loading, error, refresh } = usePluginData<SyncStatus>("sync-status", {
+ companyId: context.companyId,
+ });
+
+ if (loading) return <Spinner />;
+ if (error) return <StatusBadge label={error.message} status="error" />;
+
+ return (
+ <div>
+ <StatusBadge label={data!.healthy ? "Healthy" : "Unhealthy"} status={data!.healthy ? "ok" : "error"} />
+ <p>Synced {data!.syncedCount} items</p>
+ <p>Last sync: {data!.lastSyncAt}</p>
+ <button onClick={refresh}>Refresh</button>
+ </div>
+ );
+}
+```
+
+#### `usePluginAction(key)`
+
+Returns an async function that calls the worker's `performAction` handler. Throws `PluginBridgeError` on failure.
+
+```tsx
+import { useState } from "react";
+import { usePluginAction, type PluginBridgeError } from "@paperclipai/plugin-sdk/ui";
+
+export function ResyncButton({ context }: PluginWidgetProps) {
+ const resync = usePluginAction("resync");
+ const [busy, setBusy] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+
+ async function handleClick() {
+ setBusy(true);
+ setError(null);
+ try {
+ await resync({ companyId: context.companyId });
+ } catch (err) {
+ setError((err as PluginBridgeError).message);
+ } finally {
+ setBusy(false);
+ }
+ }
+
+ return (
+ <div>
+ <button onClick={handleClick} disabled={busy}>
+ {busy ? "Syncing..." : "Resync Now"}
+ </button>
+ {error && <p style={{ color: "red" }}>{error}</p>}
+ </div>
+ );
+}
+```
+
+#### `useHostContext()`
+
+Reads the active company, project, entity, and user context. Use this to scope data fetches and actions.
+
+```tsx
+import { useHostContext, usePluginData } from "@paperclipai/plugin-sdk/ui";
+import type { PluginDetailTabProps } from "@paperclipai/plugin-sdk/ui";
+
+export function IssueLinearLink({ context }: PluginDetailTabProps) {
+ const { companyId, entityId, entityType } = context;
+ const { data } = usePluginData<{ url: string }>("linear-link", {
+ companyId,
+ issueId: entityId,
+ });
+
+ if (!data?.url) return <p>No linked Linear issue.</p>;
+ return <a href={data.url} target="_blank" rel="noopener">View in Linear</a>;
+}
+```
+
+#### `usePluginStream<T>(channel, options?)`
+
+Subscribes to a real-time event stream pushed from the plugin worker via SSE. The worker pushes events using `ctx.streams.emit(channel, event)` and the hook receives them as they arrive. Returns `{ events, lastEvent, connecting, connected, error, close }`.
+
+```tsx
+import { usePluginStream } from "@paperclipai/plugin-sdk/ui";
+
+interface ChatToken {
+ text: string;
+}
+
+export function ChatMessages({ context }: PluginWidgetProps) {
+ const { events, connected, close } = usePluginStream<ChatToken>("chat-stream", {
+ companyId: context.companyId ?? undefined,
+ });
+
+ return (
+ <div>
+ {events.map((e, i) => <span key={i}>{e.text}</span>)}
+ {connected && <span className="pulse" />}
+ <button onClick={close}>Stop</button>
+ </div>
+ );
+}
+```
+
+The SSE connection targets `GET /api/plugins/:pluginId/bridge/stream/:channel?companyId=...`. The host bridge manages the EventSource lifecycle; `close()` terminates the connection.
+
+### Shared components reference
+
+All components are provided by the host at runtime and match the host design tokens. Import from `@paperclipai/plugin-sdk/ui` or `@paperclipai/plugin-sdk/ui/components`.
+
+#### `MetricCard`
+
+Displays a single metric value with optional trend and sparkline.
+
+```tsx
+<MetricCard label="Issues Synced" value={142} unit="issues" trend={{ direction: "up", percentage: 12 }} />
+<MetricCard label="API Latency" value="45ms" sparkline={[52, 48, 45, 47, 45]} />
+```
+
+#### `StatusBadge`
+
+Inline status indicator with semantic color.
+
+```tsx
+<StatusBadge label="Connected" status="ok" />
+<StatusBadge label="Rate Limited" status="warning" />
+<StatusBadge label="Auth Failed" status="error" />
+```
+
+#### `DataTable`
+
+Sortable, paginated table.
+
+```tsx
+<DataTable
+ columns={[
+ { key: "name", header: "Name", sortable: true },
+ { key: "status", header: "Status", width: "100px" },
+ { key: "updatedAt", header: "Updated", render: (v) => new Date(v as string).toLocaleDateString() },
+ ]}
+ rows={issues}
+ totalCount={totalCount}
+ page={page}
+ pageSize={25}
+ onPageChange={setPage}
+ onSort={(key, dir) => setSortBy({ key, dir })}
+/>
+```
+
+#### `TimeseriesChart`
+
+Line or bar chart for time-series data.
+
+```tsx
+<TimeseriesChart
+ title="Sync Frequency"
+ data={[
+ { timestamp: "2026-03-01T00:00:00Z", value: 24 },
+ { timestamp: "2026-03-02T00:00:00Z", value: 31 },
+ { timestamp: "2026-03-03T00:00:00Z", value: 28 },
+ ]}
+ type="bar"
+ yLabel="Syncs"
+ height={250}
+/>
+```
+
+#### `ActionBar`
+
+Row of action buttons wired to the plugin bridge.
+
+```tsx
+<ActionBar
+ actions={[
+ { label: "Sync Now", actionKey: "sync", variant: "primary" },
+ { label: "Clear Cache", actionKey: "clear-cache", confirm: true, confirmMessage: "Delete all cached data?" },
+ ]}
+ onSuccess={(key) => data.refresh()}
+ onError={(key, err) => console.error(key, err)}
+/>
+```
+
+#### `LogView`, `JsonTree`, `KeyValueList`, `MarkdownBlock`
+
+```tsx
+<LogView entries={logEntries} maxHeight="300px" autoScroll />
+<JsonTree data={debugPayload} defaultExpandDepth={3} />
+<KeyValueList pairs={[{ label: "Plugin ID", value: pluginId }, { label: "Version", value: "1.2.0" }]} />
+<MarkdownBlock content="**Bold** text and `code` blocks are supported." />
+```
+
+#### `Spinner`, `ErrorBoundary`
+
+```tsx
+<Spinner size="lg" label="Loading plugin data..." />
+
+<ErrorBoundary fallback={<p>Something went wrong.</p>} onError={(err) => console.error(err)}>
+ <MyPluginContent />
+</ErrorBoundary>
+```
+
+### Slot component props
+
+Each slot type receives a typed props object with `context: PluginHostContext`. Import from `@paperclipai/plugin-sdk/ui`.
+
+| Slot type | Props interface | `context` extras |
+|-----------|----------------|------------------|
+| `page` | `PluginPageProps` | — |
+| `sidebar` | `PluginSidebarProps` | — |
+| `settingsPage` | `PluginSettingsPageProps` | — |
+| `dashboardWidget` | `PluginWidgetProps` | — |
+| `detailTab` | `PluginDetailTabProps` | `entityId: string`, `entityType: string` |
+| `commentAnnotation` | `PluginCommentAnnotationProps` | `entityId: string`, `entityType: "comment"`, `parentEntityId: string`, `projectId`, `companyPrefix` |
+| `commentContextMenuItem` | `PluginCommentContextMenuItemProps` | `entityId: string`, `entityType: "comment"`, `parentEntityId: string`, `projectId`, `companyPrefix` |
+| `projectSidebarItem` | `PluginProjectSidebarItemProps` | `entityId: string`, `entityType: "project"` |
+
+Example detail tab with entity context:
+
+```tsx
+import type { PluginDetailTabProps } from "@paperclipai/plugin-sdk/ui";
+import { usePluginData, KeyValueList, Spinner } from "@paperclipai/plugin-sdk/ui";
+
+export function AgentMetricsTab({ context }: PluginDetailTabProps) {
+ const { data, loading } = usePluginData<Record<string, string>>("agent-metrics", {
+ agentId: context.entityId,
+ companyId: context.companyId,
+ });
+
+ if (loading) return <Spinner />;
+ if (!data) return <p>No metrics available.</p>;
+
+ return (
+ <KeyValueList
+ pairs={Object.entries(data).map(([label, value]) => ({ label, value }))}
+ />
+ );
+}
+```
+
+## Launcher surfaces and modals
+
+V1 does not provide a dedicated `modal` slot. Plugins can either:
+
+- declare concrete UI mount points in `ui.slots`
+- declare host-rendered entry points in `ui.launchers`
+
+Supported launcher placement zones currently mirror the major host surfaces such as `projectSidebarItem`, `toolbarButton`, `detailTab`, `settingsPage`, and `contextMenuItem`. Plugins may still open their own local modal from those entry points when needed.
+
+Declarative launcher example:
+
+```json
+{
+ "ui": {
+ "launchers": [
+ {
+ "id": "sync-project",
+ "displayName": "Sync",
+ "placementZone": "toolbarButton",
+ "entityTypes": ["project"],
+ "action": {
+ "type": "openDrawer",
+ "target": "sync-project"
+ },
+ "render": {
+ "environment": "hostOverlay",
+ "bounds": "wide"
+ }
+ }
+ ]
+ }
+}
+```
+
+The host returns launcher metadata from `GET /api/plugins/ui-contributions` alongside slot declarations.
+
+When a launcher opens a host-owned overlay or page, `useHostContext()`,
+`usePluginData()`, and `usePluginAction()` receive the current
+`renderEnvironment` through the bridge. Use that to tailor compact modal UI vs.
+full-page layouts without adding custom route parsing in the plugin.
+
+## Project sidebar item
+
+Plugins can add a link under each project in the sidebar via the `projectSidebarItem` slot. This is the recommended slot-based launcher pattern for project-scoped workflows because it can deep-link into a richer plugin tab. The component is rendered once per project with that project’s id in `context.entityId`. Declare the slot and capability in your manifest:
+
+```json
+{
+ "ui": {
+ "slots": [
+ {
+ "type": "projectSidebarItem",
+ "id": "files",
+ "displayName": "Files",
+ "exportName": "FilesLink",
+ "entityTypes": ["project"]
+ }
+ ]
+ },
+ "capabilities": ["ui.sidebar.register", "ui.detailTab.register"]
+}
+```
+
+Minimal React component that links to the project’s plugin tab (see project detail tabs in the spec):
+
+```tsx
+import type { PluginProjectSidebarItemProps } from "@paperclipai/plugin-sdk/ui";
+
+export function FilesLink({ context }: PluginProjectSidebarItemProps) {
+ const projectId = context.entityId;
+ const prefix = context.companyPrefix ? `/${context.companyPrefix}` : "";
+ const projectRef = projectId; // or resolve from host; entityId is project id
+ return (
+ <a href={`${prefix}/projects/${projectRef}?tab=plugin:your-plugin:files`}>
+ Files
+ </a>
+ );
+}
+```
+
+Use optional `order` in the slot to sort among other project sidebar items. See §19.5.1 in the plugin spec and project detail plugin tabs (§19.3) for the full flow.
+
+## Toolbar launcher with a local modal
+
+For short-lived actions, mount a `toolbarButton` and open a plugin-owned modal inside the component. Use `useHostContext()` to scope the action to the current company or project.
+
+```json
+{
+ "ui": {
+ "slots": [
+ {
+ "type": "toolbarButton",
+ "id": "sync-toolbar-button",
+ "displayName": "Sync",
+ "exportName": "SyncToolbarButton"
+ }
+ ]
+ },
+ "capabilities": ["ui.action.register"]
+}
+```
+
+```tsx
+import { useState } from "react";
+import {
+ ErrorBoundary,
+ Spinner,
+ useHostContext,
+ usePluginAction,
+} from "@paperclipai/plugin-sdk/ui";
+
+export function SyncToolbarButton() {
+ const context = useHostContext();
+ const syncProject = usePluginAction("sync-project");
+ const [open, setOpen] = useState(false);
+ const [submitting, setSubmitting] = useState(false);
+ const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+ async function confirm() {
+ if (!context.projectId) return;
+ setSubmitting(true);
+ setErrorMessage(null);
+ try {
+ await syncProject({ projectId: context.projectId });
+ setOpen(false);
+ } catch (err) {
+ setErrorMessage(err instanceof Error ? err.message : "Sync failed");
+ } finally {
+ setSubmitting(false);
+ }
+ }
+
+ return (
+ <ErrorBoundary>
+ <button type="button" onClick={() => setOpen(true)}>
+ Sync
+ </button>
+ {open ? (
+ <div
+ role="dialog"
+ aria-modal="true"
+ className="fixed inset-0 z-50 flex items-center justify-center bg-black/40 p-4"
+ onClick={() => !submitting && setOpen(false)}
+ >
+ <div
+ className="w-full max-w-md rounded-lg bg-background p-4 shadow-xl"
+ onClick={(event) => event.stopPropagation()}
+ >
+ <h2 className="text-base font-semibold">Sync this project?</h2>
+ <p className="mt-2 text-sm text-muted-foreground">
+ Queue a sync for <code>{context.projectId}</code>.
+ </p>
+ {errorMessage ? (
+ <p className="mt-2 text-sm text-destructive">{errorMessage}</p>
+ ) : null}
+ <div className="mt-4 flex justify-end gap-2">
+ <button type="button" onClick={() => setOpen(false)}>
+ Cancel
+ </button>
+ <button type="button" onClick={() => void confirm()} disabled={submitting}>
+ {submitting ? <Spinner size="sm" /> : "Run sync"}
+ </button>
+ </div>
+ </div>
+ </div>
+ ) : null}
+ </ErrorBoundary>
+ );
+}
+```
+
+Prefer deep-linkable tabs and pages for primary workflows. Reserve plugin-owned modals for confirmations, pickers, and compact editors.
+
+## Real-time streaming (`ctx.streams`)
+
+Plugins can push real-time events from the worker to the UI using server-sent events (SSE). This is useful for streaming LLM tokens, live sync progress, or any push-based data.
+
+### Worker side
+
+In `setup()`, use `ctx.streams` to open a channel, emit events, and close when done:
+
+```ts
+const plugin = definePlugin({
+ async setup(ctx) {
+ ctx.actions.register("chat", async (params) => {
+ const companyId = params.companyId as string;
+ ctx.streams.open("chat-stream", companyId);
+
+ for await (const token of streamFromLLM(params.prompt as string)) {
+ ctx.streams.emit("chat-stream", { text: token });
+ }
+
+ ctx.streams.close("chat-stream");
+ return { ok: true };
+ });
+ },
+});
+```
+
+**API:**
+
+| Method | Description |
+|--------|-------------|
+| `ctx.streams.open(channel, companyId)` | Open a named stream channel and associate it with a company. Sends a `streams.open` notification to the host. |
+| `ctx.streams.emit(channel, event)` | Push an event to the channel. The `companyId` is automatically resolved from the prior `open()` call. |
+| `ctx.streams.close(channel)` | Close the channel and clear the company mapping. Sends a `streams.close` notification. |
+
+Stream notifications are fire-and-forget JSON-RPC messages (no `id` field). They are sent via `notifyHost()` synchronously during handler execution.
+
+### UI side
+
+Use the `usePluginStream` hook (see [Hooks reference](#usepluginstreamtchannel-options) above) to subscribe to events from the UI.
+
+### Host-side architecture
+
+The host maintains an in-memory `PluginStreamBus` that fans out worker notifications to connected SSE clients:
+
+1. Worker emits `streams.emit` notification via stdout
+2. Host (`plugin-worker-manager`) receives the notification and publishes to `PluginStreamBus`
+3. SSE endpoint (`GET /api/plugins/:pluginId/bridge/stream/:channel?companyId=...`) subscribes to the bus and writes events to the response
+
+The bus is keyed by `pluginId:channel:companyId`, so multiple UI clients can subscribe to the same stream independently.
+
+### Streaming agent responses to the UI
+
+`ctx.streams` and `ctx.agents.sessions` are complementary. The worker sits between them, relaying agent events to the browser in real time:
+
+```
+UI ──usePluginAction──▶ Worker ──sessions.sendMessage──▶ Agent
+UI ◀──usePluginStream── Worker ◀──onEvent callback────── Agent
+```
+
+The agent doesn't know about streams — the worker decides what to relay. Encode the agent ID in the channel name to scope streams per agent.
+
+**Worker:**
+
+```ts
+ctx.actions.register("ask-agent", async (params) => {
+ const { agentId, companyId, prompt } = params as {
+ agentId: string; companyId: string; prompt: string;
+ };
+
+ const channel = `agent:${agentId}`;
+ ctx.streams.open(channel, companyId);
+
+ const session = await ctx.agents.sessions.create(agentId, companyId);
+
+ await ctx.agents.sessions.sendMessage(session.sessionId, companyId, {
+ prompt,
+ onEvent: (event) => {
+ ctx.streams.emit(channel, {
+ type: event.eventType, // "chunk" | "done" | "error"
+ text: event.message ?? "",
+ });
+ },
+ });
+
+ ctx.streams.close(channel);
+ return { sessionId: session.sessionId };
+});
+```
+
+**UI:**
+
+```tsx
+import { useState } from "react";
+import { usePluginAction, usePluginStream } from "@paperclipai/plugin-sdk/ui";
+
+interface AgentEvent {
+ type: "chunk" | "done" | "error";
+ text: string;
+}
+
+export function AgentChat({ agentId, companyId }: { agentId: string; companyId: string }) {
+ const askAgent = usePluginAction("ask-agent");
+ const { events, connected, close } = usePluginStream<AgentEvent>(`agent:${agentId}`, { companyId });
+ const [prompt, setPrompt] = useState("");
+
+ async function send() {
+ setPrompt("");
+ await askAgent({ agentId, companyId, prompt });
+ }
+
+ return (
+ <div>
+ <div>{events.filter(e => e.type === "chunk").map((e, i) => <span key={i}>{e.text}</span>)}</div>
+ <input value={prompt} onChange={(e) => setPrompt(e.target.value)} />
+ <button onClick={send}>Send</button>
+ {connected && <button onClick={close}>Stop</button>}
+ </div>
+ );
+}
+```
+
+## Agent sessions (two-way chat)
+
+Plugins can hold multi-turn conversational sessions with agents:
+
+```ts
+// Create a session
+const session = await ctx.agents.sessions.create(agentId, companyId);
+
+// Send a message and stream the response
+await ctx.agents.sessions.sendMessage(session.sessionId, companyId, {
+ prompt: "Help me triage this issue",
+ onEvent: (event) => {
+ if (event.eventType === "chunk") console.log(event.message);
+ if (event.eventType === "done") console.log("Stream complete");
+ },
+});
+
+// List active sessions
+const sessions = await ctx.agents.sessions.list(agentId, companyId);
+
+// Close when done
+await ctx.agents.sessions.close(session.sessionId, companyId);
+```
+
+Requires capabilities: `agent.sessions.create`, `agent.sessions.list`, `agent.sessions.send`, `agent.sessions.close`.
+
+Exported types: `AgentSession`, `AgentSessionEvent`, `AgentSessionSendResult`, `PluginAgentSessionsClient`.
+
+## Testing utilities
+
+```ts
+import { createTestHarness } from "@paperclipai/plugin-sdk/testing";
+import plugin from "../src/worker.js";
+import manifest from "../src/manifest.js";
+
+const harness = createTestHarness({ manifest });
+await plugin.definition.setup(harness.ctx);
+await harness.emit("issue.created", { issueId: "iss_1" }, { entityId: "iss_1", entityType: "issue" });
+```
+
+## Bundler presets
+
+```ts
+import { createPluginBundlerPresets } from "@paperclipai/plugin-sdk/bundlers";
+
+const presets = createPluginBundlerPresets({ uiEntry: "src/ui/index.tsx" });
+// presets.esbuild.worker / presets.esbuild.manifest / presets.esbuild.ui
+// presets.rollup.worker / presets.rollup.manifest / presets.rollup.ui
+```
+
+## Local dev server (hot-reload events)
+
+```bash
+paperclip-plugin-dev-server --root . --ui-dir dist/ui --port 4177
+```
+
+Or programmatically:
+
+```ts
+import { startPluginDevServer } from "@paperclipai/plugin-sdk/dev-server";
+const server = await startPluginDevServer({ rootDir: process.cwd() });
+```
+
+Dev server endpoints:
+- `GET /__paperclip__/health` returns `{ ok, rootDir, uiDir }`
+- `GET /__paperclip__/events` streams `reload` SSE events on UI build changes
diff --git a/packages/plugins/sdk/package.json b/packages/plugins/sdk/package.json
new file mode 100644
index 0000000000..d5e5c19cf9
--- /dev/null
+++ b/packages/plugins/sdk/package.json
@@ -0,0 +1,124 @@
+{
+ "name": "@paperclipai/plugin-sdk",
+ "version": "1.0.0",
+ "description": "Stable public API for Paperclip plugins — worker-side context and UI bridge hooks",
+ "type": "module",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.js"
+ },
+ "./protocol": {
+ "types": "./dist/protocol.d.ts",
+ "import": "./dist/protocol.js"
+ },
+ "./types": {
+ "types": "./dist/types.d.ts",
+ "import": "./dist/types.js"
+ },
+ "./ui": {
+ "types": "./dist/ui/index.d.ts",
+ "import": "./dist/ui/index.js"
+ },
+ "./ui/hooks": {
+ "types": "./dist/ui/hooks.d.ts",
+ "import": "./dist/ui/hooks.js"
+ },
+ "./ui/types": {
+ "types": "./dist/ui/types.d.ts",
+ "import": "./dist/ui/types.js"
+ },
+ "./ui/components": {
+ "types": "./dist/ui/components.d.ts",
+ "import": "./dist/ui/components.js"
+ },
+ "./testing": {
+ "types": "./dist/testing.d.ts",
+ "import": "./dist/testing.js"
+ },
+ "./bundlers": {
+ "types": "./dist/bundlers.d.ts",
+ "import": "./dist/bundlers.js"
+ },
+ "./dev-server": {
+ "types": "./dist/dev-server.d.ts",
+ "import": "./dist/dev-server.js"
+ }
+ },
+ "bin": {
+ "paperclip-plugin-dev-server": "./dist/dev-cli.js"
+ },
+ "publishConfig": {
+ "access": "public",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.js"
+ },
+ "./protocol": {
+ "types": "./dist/protocol.d.ts",
+ "import": "./dist/protocol.js"
+ },
+ "./types": {
+ "types": "./dist/types.d.ts",
+ "import": "./dist/types.js"
+ },
+ "./ui": {
+ "types": "./dist/ui/index.d.ts",
+ "import": "./dist/ui/index.js"
+ },
+ "./ui/hooks": {
+ "types": "./dist/ui/hooks.d.ts",
+ "import": "./dist/ui/hooks.js"
+ },
+ "./ui/types": {
+ "types": "./dist/ui/types.d.ts",
+ "import": "./dist/ui/types.js"
+ },
+ "./ui/components": {
+ "types": "./dist/ui/components.d.ts",
+ "import": "./dist/ui/components.js"
+ },
+ "./testing": {
+ "types": "./dist/testing.d.ts",
+ "import": "./dist/testing.js"
+ },
+ "./bundlers": {
+ "types": "./dist/bundlers.d.ts",
+ "import": "./dist/bundlers.js"
+ },
+ "./dev-server": {
+ "types": "./dist/dev-server.d.ts",
+ "import": "./dist/dev-server.js"
+ }
+ },
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts"
+ },
+ "files": [
+ "dist"
+ ],
+ "scripts": {
+ "build": "pnpm --filter @paperclipai/shared build && tsc",
+ "clean": "rm -rf dist",
+ "typecheck": "pnpm --filter @paperclipai/shared build && tsc --noEmit",
+ "dev:server": "tsx src/dev-cli.ts"
+ },
+ "dependencies": {
+ "@paperclipai/shared": "workspace:*",
+ "zod": "^3.24.2"
+ },
+ "devDependencies": {
+ "@types/node": "^24.6.0",
+ "@types/react": "^19.0.8",
+ "typescript": "^5.7.3"
+ },
+ "peerDependencies": {
+ "react": ">=18"
+ },
+ "peerDependenciesMeta": {
+ "react": {
+ "optional": true
+ }
+ }
+}
diff --git a/packages/plugins/sdk/src/bundlers.ts b/packages/plugins/sdk/src/bundlers.ts
new file mode 100644
index 0000000000..a8ec6850cf
--- /dev/null
+++ b/packages/plugins/sdk/src/bundlers.ts
@@ -0,0 +1,161 @@
+/**
+ * Bundling presets for Paperclip plugins.
+ *
+ * These helpers return plain config objects so plugin authors can use them
+ * with esbuild or rollup without re-implementing host contract defaults.
+ */
+
+export interface PluginBundlerPresetInput {
+ pluginRoot?: string;
+ manifestEntry?: string;
+ workerEntry?: string;
+ uiEntry?: string;
+ outdir?: string;
+ sourcemap?: boolean;
+ minify?: boolean;
+}
+
+export interface EsbuildLikeOptions {
+ entryPoints: string[];
+ outdir: string;
+ bundle: boolean;
+ format: "esm";
+ platform: "node" | "browser";
+ target: string;
+ sourcemap?: boolean;
+ minify?: boolean;
+ external?: string[];
+}
+
+export interface RollupLikeConfig {
+ input: string;
+ output: {
+ dir: string;
+ format: "es";
+ sourcemap?: boolean;
+ entryFileNames?: string;
+ };
+ external?: string[];
+ plugins?: unknown[];
+}
+
+export interface PluginBundlerPresets {
+ esbuild: {
+ worker: EsbuildLikeOptions;
+ ui?: EsbuildLikeOptions;
+ manifest: EsbuildLikeOptions;
+ };
+ rollup: {
+ worker: RollupLikeConfig;
+ ui?: RollupLikeConfig;
+ manifest: RollupLikeConfig;
+ };
+}
+
+/**
+ * Build esbuild/rollup baseline configs for plugin worker, manifest, and UI bundles.
+ *
+ * The presets intentionally externalize host/runtime deps (`react`, SDK packages)
+ * to match the Paperclip plugin loader contract.
+ */
+export function createPluginBundlerPresets(input: PluginBundlerPresetInput = {}): PluginBundlerPresets {
+ const uiExternal = [
+ "@paperclipai/plugin-sdk/ui",
+ "@paperclipai/plugin-sdk/ui/hooks",
+ "@paperclipai/plugin-sdk/ui/components",
+ "react",
+ "react-dom",
+ "react/jsx-runtime",
+ ];
+
+ const outdir = input.outdir ?? "dist";
+ const workerEntry = input.workerEntry ?? "src/worker.ts";
+ const manifestEntry = input.manifestEntry ?? "src/manifest.ts";
+ const uiEntry = input.uiEntry;
+ const sourcemap = input.sourcemap ?? true;
+ const minify = input.minify ?? false;
+
+ const esbuildWorker: EsbuildLikeOptions = {
+ entryPoints: [workerEntry],
+ outdir,
+ bundle: true,
+ format: "esm",
+ platform: "node",
+ target: "node20",
+ sourcemap,
+ minify,
+ external: ["@paperclipai/plugin-sdk", "@paperclipai/plugin-sdk/ui", "react", "react-dom"],
+ };
+
+ const esbuildManifest: EsbuildLikeOptions = {
+ entryPoints: [manifestEntry],
+ outdir,
+ bundle: false,
+ format: "esm",
+ platform: "node",
+ target: "node20",
+ sourcemap,
+ };
+
+ const esbuildUi = uiEntry
+ ? {
+ entryPoints: [uiEntry],
+ outdir: `${outdir}/ui`,
+ bundle: true,
+ format: "esm" as const,
+ platform: "browser" as const,
+ target: "es2022",
+ sourcemap,
+ minify,
+ external: uiExternal,
+ }
+ : undefined;
+
+ const rollupWorker: RollupLikeConfig = {
+ input: workerEntry,
+ output: {
+ dir: outdir,
+ format: "es",
+ sourcemap,
+ entryFileNames: "worker.js",
+ },
+ external: ["@paperclipai/plugin-sdk", "react", "react-dom"],
+ };
+
+ const rollupManifest: RollupLikeConfig = {
+ input: manifestEntry,
+ output: {
+ dir: outdir,
+ format: "es",
+ sourcemap,
+ entryFileNames: "manifest.js",
+ },
+ external: ["@paperclipai/plugin-sdk"],
+ };
+
+ const rollupUi = uiEntry
+ ? {
+ input: uiEntry,
+ output: {
+ dir: `${outdir}/ui`,
+ format: "es" as const,
+ sourcemap,
+ entryFileNames: "index.js",
+ },
+ external: uiExternal,
+ }
+ : undefined;
+
+ return {
+ esbuild: {
+ worker: esbuildWorker,
+ manifest: esbuildManifest,
+ ...(esbuildUi ? { ui: esbuildUi } : {}),
+ },
+ rollup: {
+ worker: rollupWorker,
+ manifest: rollupManifest,
+ ...(rollupUi ? { ui: rollupUi } : {}),
+ },
+ };
+}
diff --git a/packages/plugins/sdk/src/define-plugin.ts b/packages/plugins/sdk/src/define-plugin.ts
new file mode 100644
index 0000000000..43fefdd281
--- /dev/null
+++ b/packages/plugins/sdk/src/define-plugin.ts
@@ -0,0 +1,255 @@
+/**
+ * `definePlugin` — the top-level helper for authoring a Paperclip plugin.
+ *
+ * Plugin authors call `definePlugin()` and export the result as the default
+ * export from their worker entrypoint. The host imports the worker module,
+ * calls `setup()` with a `PluginContext`, and from that point the plugin
+ * responds to events, jobs, webhooks, and UI requests through the context.
+ *
+ * @see PLUGIN_SPEC.md §14.1 — Example SDK Shape
+ *
+ * @example
+ * ```ts
+ * // dist/worker.ts
+ * import { definePlugin } from "@paperclipai/plugin-sdk";
+ *
+ * export default definePlugin({
+ * async setup(ctx) {
+ * ctx.logger.info("Linear sync plugin starting");
+ *
+ * // Subscribe to events
+ * ctx.events.on("issue.created", async (event) => {
+ * const config = await ctx.config.get();
+ * await ctx.http.fetch(`https://api.linear.app/...`, {
+ * method: "POST",
+ * headers: { Authorization: `Bearer ${await ctx.secrets.resolve(config.apiKeyRef as string)}` },
+ * body: JSON.stringify({ title: event.payload.title }),
+ * });
+ * });
+ *
+ * // Register a job handler
+ * ctx.jobs.register("full-sync", async (job) => {
+ * ctx.logger.info("Running full-sync job", { runId: job.runId });
+ * // ... sync logic
+ * });
+ *
+ * // Register data for the UI
+ * ctx.data.register("sync-health", async ({ companyId }) => {
+ * const state = await ctx.state.get({
+ * scopeKind: "company",
+ * scopeId: String(companyId),
+ * stateKey: "last-sync",
+ * });
+ * return { lastSync: state };
+ * });
+ * },
+ * });
+ * ```
+ */
+
+import type { PluginContext } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Health check result
+// ---------------------------------------------------------------------------
+
+/**
+ * Optional plugin-reported diagnostics returned from the `health()` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.2 — `health`
+ */
+export interface PluginHealthDiagnostics {
+ /** Machine-readable status: `"ok"` | `"degraded"` | `"error"`. */
+ status: "ok" | "degraded" | "error";
+ /** Human-readable description of the current health state. */
+ message?: string;
+ /** Plugin-reported key-value diagnostics (e.g. connection status, queue depth). */
+ details?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Config validation result
+// ---------------------------------------------------------------------------
+
+/**
+ * Result returned from the `validateConfig()` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.3 — `validateConfig`
+ */
+export interface PluginConfigValidationResult {
+ /** Whether the config is valid. */
+ ok: boolean;
+ /** Non-fatal warnings about the config. */
+ warnings?: string[];
+ /** Validation errors (populated when `ok` is `false`). */
+ errors?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Webhook handler input
+// ---------------------------------------------------------------------------
+
+/**
+ * Input received by the plugin worker's `handleWebhook` handler.
+ *
+ * @see PLUGIN_SPEC.md §13.7 — `handleWebhook`
+ */
+export interface PluginWebhookInput {
+ /** Endpoint key matching the manifest declaration. */
+ endpointKey: string;
+ /** Inbound request headers. */
+ headers: Record<string, string | string[]>;
+ /** Raw request body as a UTF-8 string. */
+ rawBody: string;
+ /** Parsed JSON body (if applicable and parseable). */
+ parsedBody?: unknown;
+ /** Unique request identifier for idempotency checks. */
+ requestId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin definition
+// ---------------------------------------------------------------------------
+
+/**
+ * The plugin definition shape passed to `definePlugin()`.
+ *
+ * The only required field is `setup`, which receives the `PluginContext` and
+ * is where the plugin registers its handlers (events, jobs, data, actions,
+ * tools, etc.).
+ *
+ * All other lifecycle hooks are optional. If a hook is not implemented the
+ * host applies default behaviour (e.g. restarting the worker on config change
+ * instead of calling `onConfigChanged`).
+ *
+ * @see PLUGIN_SPEC.md §13 — Host-Worker Protocol
+ */
+export interface PluginDefinition {
+ /**
+ * Called once when the plugin worker starts up, after `initialize` completes.
+ *
+ * This is where the plugin registers all its handlers: event subscriptions,
+ * job handlers, data/action handlers, and tool registrations. Registration
+ * must be synchronous after `setup` resolves — do not register handlers
+ * inside async callbacks that may resolve after `setup` returns.
+ *
+ * @param ctx - The full plugin context provided by the host
+ */
+ setup(ctx: PluginContext): Promise<void>;
+
+ /**
+ * Called when the host wants to know if the plugin is healthy.
+ *
+ * The host polls this on a regular interval and surfaces the result in the
+ * plugin health dashboard. If not implemented, the host infers health from
+ * worker process liveness.
+ *
+ * @see PLUGIN_SPEC.md §13.2 — `health`
+ */
+ onHealth?(): Promise<PluginHealthDiagnostics>;
+
+ /**
+ * Called when the operator updates the plugin's instance configuration at
+ * runtime, without restarting the worker.
+ *
+ * If not implemented, the host restarts the worker to apply the new config.
+ *
+ * @param newConfig - The newly resolved configuration
+ * @see PLUGIN_SPEC.md §13.4 — `configChanged`
+ */
+ onConfigChanged?(newConfig: Record<string, unknown>): Promise<void>;
+
+ /**
+ * Called when the host is about to shut down the plugin worker.
+ *
+ * The worker has at most 10 seconds (configurable via plugin config) to
+ * finish in-flight work and resolve this promise. After the deadline the
+ * host sends SIGTERM, then SIGKILL.
+ *
+ * @see PLUGIN_SPEC.md §12.5 — Graceful Shutdown Policy
+ */
+ onShutdown?(): Promise<void>;
+
+ /**
+ * Called to validate the current plugin configuration.
+ *
+ * The host calls this:
+ * - after the plugin starts (to surface config errors immediately)
+ * - after the operator saves a new config (to validate before persisting)
+ * - via the "Test Connection" button in the settings UI
+ *
+ * @param config - The configuration to validate
+ * @see PLUGIN_SPEC.md §13.3 — `validateConfig`
+ */
+ onValidateConfig?(config: Record<string, unknown>): Promise<PluginConfigValidationResult>;
+
+ /**
+ * Called to handle an inbound webhook delivery.
+ *
+ * The host routes `POST /api/plugins/:pluginId/webhooks/:endpointKey` to
+ * this handler. The plugin is responsible for signature verification using
+ * a resolved secret ref.
+ *
+ * If not implemented but webhooks are declared in the manifest, the host
+ * returns HTTP 501 for webhook deliveries.
+ *
+ * @param input - Webhook delivery metadata and payload
+ * @see PLUGIN_SPEC.md §13.7 — `handleWebhook`
+ */
+ onWebhook?(input: PluginWebhookInput): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// PaperclipPlugin — the sealed object returned by definePlugin()
+// ---------------------------------------------------------------------------
+
+/**
+ * The sealed plugin object returned by `definePlugin()`.
+ *
+ * Plugin authors export this as the default export from their worker
+ * entrypoint. The host imports it and calls the lifecycle methods.
+ *
+ * @see PLUGIN_SPEC.md §14 — SDK Surface
+ */
+export interface PaperclipPlugin {
+ /** The original plugin definition passed to `definePlugin()`. */
+ readonly definition: PluginDefinition;
+}
+
+// ---------------------------------------------------------------------------
+// definePlugin — top-level factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Define a Paperclip plugin.
+ *
+ * Call this function in your worker entrypoint and export the result as the
+ * default export. The host will import the module and call lifecycle methods
+ * on the returned object.
+ *
+ * @param definition - Plugin lifecycle handlers
+ * @returns A sealed `PaperclipPlugin` object for the host to consume
+ *
+ * @example
+ * ```ts
+ * import { definePlugin } from "@paperclipai/plugin-sdk";
+ *
+ * export default definePlugin({
+ * async setup(ctx) {
+ * ctx.logger.info("Plugin started");
+ * ctx.events.on("issue.created", async (event) => {
+ * // handle event
+ * });
+ * },
+ *
+ * async onHealth() {
+ * return { status: "ok" };
+ * },
+ * });
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §14.1 — Example SDK Shape
+ */
+export function definePlugin(definition: PluginDefinition): PaperclipPlugin {
+ return Object.freeze({ definition });
+}
diff --git a/packages/plugins/sdk/src/dev-cli.ts b/packages/plugins/sdk/src/dev-cli.ts
new file mode 100644
index 0000000000..7c1b0e2b6e
--- /dev/null
+++ b/packages/plugins/sdk/src/dev-cli.ts
@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { startPluginDevServer } from "./dev-server.js";
+
+function parseArg(flag: string): string | undefined {
+ const index = process.argv.indexOf(flag);
+ if (index < 0) return undefined;
+ return process.argv[index + 1];
+}
+
+/**
+ * CLI entrypoint for the local plugin UI preview server.
+ *
+ * This is intentionally minimal and delegates all serving behavior to
+ * `startPluginDevServer` so tests and programmatic usage share one path.
+ */
+async function main() {
+ const rootDir = parseArg("--root") ?? process.cwd();
+ const uiDir = parseArg("--ui-dir") ?? "dist/ui";
+ const host = parseArg("--host") ?? "127.0.0.1";
+ const rawPort = parseArg("--port") ?? "4177";
+ const port = Number.parseInt(rawPort, 10);
+ if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+ throw new Error(`Invalid --port value: ${rawPort}`);
+ }
+
+ const server = await startPluginDevServer({
+ rootDir: path.resolve(rootDir),
+ uiDir,
+ host,
+ port,
+ });
+
+ // eslint-disable-next-line no-console
+ console.log(`Paperclip plugin dev server listening at ${server.url}`);
+
+ const shutdown = async () => {
+ await server.close();
+ process.exit(0);
+ };
+
+ process.on("SIGINT", () => {
+ void shutdown();
+ });
+ process.on("SIGTERM", () => {
+ void shutdown();
+ });
+}
+
+void main().catch((error) => {
+ // eslint-disable-next-line no-console
+ console.error(error instanceof Error ? error.message : String(error));
+ process.exit(1);
+});
diff --git a/packages/plugins/sdk/src/dev-server.ts b/packages/plugins/sdk/src/dev-server.ts
new file mode 100644
index 0000000000..2eadff81b7
--- /dev/null
+++ b/packages/plugins/sdk/src/dev-server.ts
@@ -0,0 +1,228 @@
+import { createReadStream, existsSync, statSync, watch } from "node:fs";
+import { mkdir, readdir, stat } from "node:fs/promises";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import path from "node:path";
+
+export interface PluginDevServerOptions {
+ /** Plugin project root. Defaults to `process.cwd()`. */
+ rootDir?: string;
+ /** Relative path from root to built UI assets. Defaults to `dist/ui`. */
+ uiDir?: string;
+ /** Bind port for local preview server. Defaults to `4177`. */
+ port?: number;
+ /** Bind host. Defaults to `127.0.0.1`. */
+ host?: string;
+}
+
+export interface PluginDevServer {
+ url: string;
+ close(): Promise<void>;
+}
+
+interface Closeable {
+ close(): void;
+}
+
+function contentType(filePath: string): string {
+ if (filePath.endsWith(".js")) return "text/javascript; charset=utf-8";
+ if (filePath.endsWith(".css")) return "text/css; charset=utf-8";
+ if (filePath.endsWith(".json")) return "application/json; charset=utf-8";
+ if (filePath.endsWith(".html")) return "text/html; charset=utf-8";
+ if (filePath.endsWith(".svg")) return "image/svg+xml";
+ return "application/octet-stream";
+}
+
+function normalizeFilePath(baseDir: string, reqPath: string): string {
+ const pathname = reqPath.split("?")[0] || "/";
+ const resolved = pathname === "/" ? "/index.js" : pathname;
+ const absolute = path.resolve(baseDir, `.${resolved}`);
+ const normalizedBase = `${path.resolve(baseDir)}${path.sep}`;
+ if (!absolute.startsWith(normalizedBase) && absolute !== path.resolve(baseDir)) {
+ throw new Error("path traversal blocked");
+ }
+ return absolute;
+}
+
+function send404(res: ServerResponse) {
+ res.statusCode = 404;
+ res.setHeader("Content-Type", "application/json; charset=utf-8");
+ res.end(JSON.stringify({ error: "Not found" }));
+}
+
+function sendJson(res: ServerResponse, value: unknown) {
+ res.statusCode = 200;
+ res.setHeader("Content-Type", "application/json; charset=utf-8");
+ res.end(JSON.stringify(value));
+}
+
+async function ensureUiDir(uiDir: string): Promise<void> {
+ if (existsSync(uiDir)) return;
+ await mkdir(uiDir, { recursive: true });
+}
+
+async function listFilesRecursive(dir: string): Promise<string[]> {
+ const out: string[] = [];
+ const entries = await readdir(dir, { withFileTypes: true });
+ for (const entry of entries) {
+ const abs = path.join(dir, entry.name);
+ if (entry.isDirectory()) {
+ out.push(...await listFilesRecursive(abs));
+ } else if (entry.isFile()) {
+ out.push(abs);
+ }
+ }
+ return out;
+}
+
+function snapshotSignature(rows: Array<{ file: string; mtimeMs: number }>): string {
+ return rows.map((row) => `${row.file}:${Math.trunc(row.mtimeMs)}`).join("|");
+}
+
+async function startUiWatcher(uiDir: string, onReload: (filePath: string) => void): Promise<Closeable> {
+ try {
+ // macOS/Windows support recursive native watching.
+ const watcher = watch(uiDir, { recursive: true }, (_eventType, filename) => {
+ if (!filename) return;
+ onReload(path.join(uiDir, filename));
+ });
+ return watcher;
+ } catch {
+ // Linux may reject recursive watch. Fall back to polling snapshots.
+ let previous = snapshotSignature(
+ (await getUiBuildSnapshot(path.dirname(uiDir), path.basename(uiDir))).map((row) => ({
+ file: row.file,
+ mtimeMs: row.mtimeMs,
+ })),
+ );
+
+ const timer = setInterval(async () => {
+ try {
+ const nextRows = await getUiBuildSnapshot(path.dirname(uiDir), path.basename(uiDir));
+ const next = snapshotSignature(nextRows);
+ if (next === previous) return;
+ previous = next;
+ onReload("__snapshot__");
+ } catch {
+ // Ignore transient read errors while bundlers are writing files.
+ }
+ }, 500);
+
+ return {
+ close() {
+ clearInterval(timer);
+ },
+ };
+ }
+}
+
+/**
+ * Start a local static server for plugin UI assets with SSE reload events.
+ *
+ * Endpoint summary:
+ * - `GET /__paperclip__/health` for diagnostics
+ * - `GET /__paperclip__/events` for hot-reload stream
+ * - Any other path serves files from the configured UI build directory
+ */
+export async function startPluginDevServer(options: PluginDevServerOptions = {}): Promise<PluginDevServer> {
+ const rootDir = path.resolve(options.rootDir ?? process.cwd());
+ const uiDir = path.resolve(rootDir, options.uiDir ?? "dist/ui");
+ const host = options.host ?? "127.0.0.1";
+ const port = options.port ?? 4177;
+
+ await ensureUiDir(uiDir);
+
+ const sseClients = new Set<ServerResponse>();
+
+ const handleRequest = async (req: IncomingMessage, res: ServerResponse) => {
+ const url = req.url ?? "/";
+
+ if (url === "/__paperclip__/health") {
+ sendJson(res, { ok: true, rootDir, uiDir });
+ return;
+ }
+
+ if (url === "/__paperclip__/events") {
+ res.writeHead(200, {
+ "Content-Type": "text/event-stream",
+ "Cache-Control": "no-cache, no-transform",
+ Connection: "keep-alive",
+ });
+ res.write(`event: connected\ndata: {"ok":true}\n\n`);
+ sseClients.add(res);
+ req.on("close", () => {
+ sseClients.delete(res);
+ });
+ return;
+ }
+
+ try {
+ const filePath = normalizeFilePath(uiDir, url);
+ if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+ send404(res);
+ return;
+ }
+
+ res.statusCode = 200;
+ res.setHeader("Content-Type", contentType(filePath));
+ createReadStream(filePath).pipe(res);
+ } catch {
+ send404(res);
+ }
+ };
+
+ const server = createServer((req, res) => {
+ void handleRequest(req, res);
+ });
+
+ const notifyReload = (filePath: string) => {
+ const rel = path.relative(uiDir, filePath);
+ const payload = JSON.stringify({ type: "reload", file: rel, at: new Date().toISOString() });
+ for (const client of sseClients) {
+ client.write(`event: reload\ndata: ${payload}\n\n`);
+ }
+ };
+
+ const watcher = await startUiWatcher(uiDir, notifyReload);
+
+ await new Promise<void>((resolve, reject) => {
+ server.once("error", reject);
+ server.listen(port, host, () => resolve());
+ });
+
+ const address = server.address();
+ const actualPort = address && typeof address === "object" ? (address as AddressInfo).port : port;
+
+ return {
+ url: `http://${host}:${actualPort}`,
+ async close() {
+ watcher.close();
+ for (const client of sseClients) {
+ client.end();
+ }
+ await new Promise<void>((resolve, reject) => {
+ server.close((err) => (err ? reject(err) : resolve()));
+ });
+ },
+ };
+}
+
+/**
+ * Return a stable file+mtime snapshot for a built plugin UI directory.
+ *
+ * Used by the polling watcher fallback and useful for tests that need to assert
+ * whether a UI build has changed between runs.
+ */
+export async function getUiBuildSnapshot(rootDir: string, uiDir = "dist/ui"): Promise<Array<{ file: string; mtimeMs: number }>> {
+ const baseDir = path.resolve(rootDir, uiDir);
+ if (!existsSync(baseDir)) return [];
+ const files = await listFilesRecursive(baseDir);
+ const rows = await Promise.all(files.map(async (filePath) => {
+ const fileStat = await stat(filePath);
+ return {
+ file: path.relative(baseDir, filePath),
+ mtimeMs: fileStat.mtimeMs,
+ };
+ }));
+ return rows.sort((a, b) => a.file.localeCompare(b.file));
+}
diff --git a/packages/plugins/sdk/src/host-client-factory.ts b/packages/plugins/sdk/src/host-client-factory.ts
new file mode 100644
index 0000000000..82d2b42fc4
--- /dev/null
+++ b/packages/plugins/sdk/src/host-client-factory.ts
@@ -0,0 +1,563 @@
+/**
+ * Host-side client factory — creates capability-gated handler maps for
+ * servicing worker→host JSON-RPC calls.
+ *
+ * When a plugin worker calls `ctx.state.get(...)` inside its process, the
+ * SDK serializes the call as a JSON-RPC request over stdio. On the host side,
+ * the `PluginWorkerManager` receives the request and dispatches it to the
+ * handler registered for that method. This module provides a factory that
+ * creates those handlers for all `WorkerToHostMethods`, with automatic
+ * capability enforcement.
+ *
+ * ## Design
+ *
+ * 1. **Capability gating**: Each handler checks the plugin's declared
+ * capabilities before executing. If the plugin lacks a required capability,
+ * the handler throws a `CapabilityDeniedError` (which the worker manager
+ * translates into a JSON-RPC error response with code
+ * `CAPABILITY_DENIED`).
+ *
+ * 2. **Service adapters**: The caller provides a `HostServices` object with
+ * concrete implementations of each platform service. The factory wires
+ * each handler to the appropriate service method.
+ *
+ * 3. **Type safety**: The returned handler map is typed as
+ * `WorkerToHostHandlers` (from `plugin-worker-manager.ts`) so it plugs
+ * directly into `WorkerStartOptions.hostHandlers`.
+ *
+ * @example
+ * ```ts
+ * const handlers = createHostClientHandlers({
+ * pluginId: "acme.linear",
+ * capabilities: manifest.capabilities,
+ * services: {
+ * config: { get: () => registry.getConfig(pluginId) },
+ * state: { get: ..., set: ..., delete: ... },
+ * entities: { upsert: ..., list: ... },
+ * // ... all services
+ * },
+ * });
+ *
+ * await workerManager.startWorker("acme.linear", {
+ * // ...
+ * hostHandlers: handlers,
+ * });
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §13 — Host-Worker Protocol
+ * @see PLUGIN_SPEC.md §15 — Capability Model
+ */
+
+import type { PluginCapability } from "@paperclipai/shared";
+import type { WorkerToHostMethods, WorkerToHostMethodName } from "./protocol.js";
+import { PLUGIN_RPC_ERROR_CODES } from "./protocol.js";
+
+// ---------------------------------------------------------------------------
+// Error types
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when a plugin calls a host method it does not have the capability for.
+ *
+ * The `code` field is set to `PLUGIN_RPC_ERROR_CODES.CAPABILITY_DENIED` so
+ * the worker manager can propagate it as the correct JSON-RPC error code.
+ */
+export class CapabilityDeniedError extends Error {
+ override readonly name = "CapabilityDeniedError";
+ readonly code = PLUGIN_RPC_ERROR_CODES.CAPABILITY_DENIED;
+
+ constructor(pluginId: string, method: string, capability: PluginCapability) {
+ super(
+ `Plugin "${pluginId}" is missing required capability "${capability}" for method "${method}"`,
+ );
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Host service interfaces
+// ---------------------------------------------------------------------------
+
+/**
+ * Service adapters that the host must provide. Each property maps to a group
+ * of `WorkerToHostMethods`. The factory wires JSON-RPC params to these
+ * function signatures.
+ *
+ * All methods return promises to support async I/O (database, HTTP, etc.).
+ */
+export interface HostServices {
+ /** Provides `config.get`. */
+ config: {
+ get(): Promise<Record<string, unknown>>;
+ };
+
+ /** Provides `state.get`, `state.set`, `state.delete`. */
+ state: {
+ get(params: WorkerToHostMethods["state.get"][0]): Promise<WorkerToHostMethods["state.get"][1]>;
+ set(params: WorkerToHostMethods["state.set"][0]): Promise<void>;
+ delete(params: WorkerToHostMethods["state.delete"][0]): Promise<void>;
+ };
+
+ /** Provides `entities.upsert`, `entities.list`. */
+ entities: {
+ upsert(params: WorkerToHostMethods["entities.upsert"][0]): Promise<WorkerToHostMethods["entities.upsert"][1]>;
+ list(params: WorkerToHostMethods["entities.list"][0]): Promise<WorkerToHostMethods["entities.list"][1]>;
+ };
+
+ /** Provides `events.emit`. */
+ events: {
+ emit(params: WorkerToHostMethods["events.emit"][0]): Promise<void>;
+ };
+
+ /** Provides `http.fetch`. */
+ http: {
+ fetch(params: WorkerToHostMethods["http.fetch"][0]): Promise<WorkerToHostMethods["http.fetch"][1]>;
+ };
+
+ /** Provides `secrets.resolve`. */
+ secrets: {
+ resolve(params: WorkerToHostMethods["secrets.resolve"][0]): Promise<string>;
+ };
+
+ /** Provides `assets.upload`, `assets.getUrl`. */
+ assets: {
+ upload(params: WorkerToHostMethods["assets.upload"][0]): Promise<WorkerToHostMethods["assets.upload"][1]>;
+ getUrl(params: WorkerToHostMethods["assets.getUrl"][0]): Promise<string>;
+ };
+
+ /** Provides `activity.log`. */
+ activity: {
+ log(params: {
+ companyId: string;
+ message: string;
+ entityType?: string;
+ entityId?: string;
+ metadata?: Record<string, unknown>;
+ }): Promise<void>;
+ };
+
+ /** Provides `metrics.write`. */
+ metrics: {
+ write(params: WorkerToHostMethods["metrics.write"][0]): Promise<void>;
+ };
+
+ /** Provides `log`. */
+ logger: {
+ log(params: WorkerToHostMethods["log"][0]): Promise<void>;
+ };
+
+ /** Provides `companies.list`, `companies.get`. */
+ companies: {
+ list(params: WorkerToHostMethods["companies.list"][0]): Promise<WorkerToHostMethods["companies.list"][1]>;
+ get(params: WorkerToHostMethods["companies.get"][0]): Promise<WorkerToHostMethods["companies.get"][1]>;
+ };
+
+ /** Provides `projects.list`, `projects.get`, `projects.listWorkspaces`, `projects.getPrimaryWorkspace`, `projects.getWorkspaceForIssue`. */
+ projects: {
+ list(params: WorkerToHostMethods["projects.list"][0]): Promise<WorkerToHostMethods["projects.list"][1]>;
+ get(params: WorkerToHostMethods["projects.get"][0]): Promise<WorkerToHostMethods["projects.get"][1]>;
+ listWorkspaces(params: WorkerToHostMethods["projects.listWorkspaces"][0]): Promise<WorkerToHostMethods["projects.listWorkspaces"][1]>;
+ getPrimaryWorkspace(params: WorkerToHostMethods["projects.getPrimaryWorkspace"][0]): Promise<WorkerToHostMethods["projects.getPrimaryWorkspace"][1]>;
+ getWorkspaceForIssue(params: WorkerToHostMethods["projects.getWorkspaceForIssue"][0]): Promise<WorkerToHostMethods["projects.getWorkspaceForIssue"][1]>;
+ };
+
+ /** Provides `issues.list`, `issues.get`, `issues.create`, `issues.update`, `issues.listComments`, `issues.createComment`. */
+ issues: {
+ list(params: WorkerToHostMethods["issues.list"][0]): Promise<WorkerToHostMethods["issues.list"][1]>;
+ get(params: WorkerToHostMethods["issues.get"][0]): Promise<WorkerToHostMethods["issues.get"][1]>;
+ create(params: WorkerToHostMethods["issues.create"][0]): Promise<WorkerToHostMethods["issues.create"][1]>;
+ update(params: WorkerToHostMethods["issues.update"][0]): Promise<WorkerToHostMethods["issues.update"][1]>;
+ listComments(params: WorkerToHostMethods["issues.listComments"][0]): Promise<WorkerToHostMethods["issues.listComments"][1]>;
+ createComment(params: WorkerToHostMethods["issues.createComment"][0]): Promise<WorkerToHostMethods["issues.createComment"][1]>;
+ };
+
+ /** Provides `agents.list`, `agents.get`, `agents.pause`, `agents.resume`, `agents.invoke`. */
+ agents: {
+ list(params: WorkerToHostMethods["agents.list"][0]): Promise<WorkerToHostMethods["agents.list"][1]>;
+ get(params: WorkerToHostMethods["agents.get"][0]): Promise<WorkerToHostMethods["agents.get"][1]>;
+ pause(params: WorkerToHostMethods["agents.pause"][0]): Promise<WorkerToHostMethods["agents.pause"][1]>;
+ resume(params: WorkerToHostMethods["agents.resume"][0]): Promise<WorkerToHostMethods["agents.resume"][1]>;
+ invoke(params: WorkerToHostMethods["agents.invoke"][0]): Promise<WorkerToHostMethods["agents.invoke"][1]>;
+ };
+
+ /** Provides `agents.sessions.create`, `agents.sessions.list`, `agents.sessions.sendMessage`, `agents.sessions.close`. */
+ agentSessions: {
+ create(params: WorkerToHostMethods["agents.sessions.create"][0]): Promise<WorkerToHostMethods["agents.sessions.create"][1]>;
+ list(params: WorkerToHostMethods["agents.sessions.list"][0]): Promise<WorkerToHostMethods["agents.sessions.list"][1]>;
+ sendMessage(params: WorkerToHostMethods["agents.sessions.sendMessage"][0]): Promise<WorkerToHostMethods["agents.sessions.sendMessage"][1]>;
+ close(params: WorkerToHostMethods["agents.sessions.close"][0]): Promise<void>;
+ };
+
+ /** Provides `goals.list`, `goals.get`, `goals.create`, `goals.update`. */
+ goals: {
+ list(params: WorkerToHostMethods["goals.list"][0]): Promise<WorkerToHostMethods["goals.list"][1]>;
+ get(params: WorkerToHostMethods["goals.get"][0]): Promise<WorkerToHostMethods["goals.get"][1]>;
+ create(params: WorkerToHostMethods["goals.create"][0]): Promise<WorkerToHostMethods["goals.create"][1]>;
+ update(params: WorkerToHostMethods["goals.update"][0]): Promise<WorkerToHostMethods["goals.update"][1]>;
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Factory input
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for `createHostClientHandlers`.
+ */
+export interface HostClientFactoryOptions {
+ /** The plugin ID. Used for error messages and logging. */
+ pluginId: string;
+
+ /**
+ * The capabilities declared by the plugin in its manifest. The factory
+ * enforces these at runtime before delegating to the service adapter.
+ */
+ capabilities: readonly PluginCapability[];
+
+ /**
+ * Concrete implementations of host platform services. Each handler in the
+ * returned map delegates to the corresponding service method.
+ */
+ services: HostServices;
+}
+
+// ---------------------------------------------------------------------------
+// Handler map type (compatible with WorkerToHostHandlers from worker manager)
+// ---------------------------------------------------------------------------
+
+/**
+ * A handler function for a specific worker→host method.
+ */
+type HostHandler<M extends WorkerToHostMethodName> = (
+ params: WorkerToHostMethods[M][0],
+) => Promise<WorkerToHostMethods[M][1]>;
+
+/**
+ * A complete map of all worker→host method handlers.
+ *
+ * This type matches `WorkerToHostHandlers` from `plugin-worker-manager.ts`
+ * but makes every handler required (the factory always provides all handlers).
+ */
+export type HostClientHandlers = {
+ [M in WorkerToHostMethodName]: HostHandler<M>;
+};
+
+// ---------------------------------------------------------------------------
+// Capability → method mapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps each worker→host RPC method to the capability required to invoke it.
+ * Methods without a capability requirement (e.g. `config.get`, `log`) are
+ * mapped to `null`.
+ *
+ * @see PLUGIN_SPEC.md §15 — Capability Model
+ */
+const METHOD_CAPABILITY_MAP: Record<WorkerToHostMethodName, PluginCapability | null> = {
+ // Config — always allowed
+ "config.get": null,
+
+ // State
+ "state.get": "plugin.state.read",
+ "state.set": "plugin.state.write",
+ "state.delete": "plugin.state.write",
+
+ // Entities — no specific capability required (plugin-scoped by design)
+ "entities.upsert": null,
+ "entities.list": null,
+
+ // Events
+ "events.emit": "events.emit",
+
+ // HTTP
+ "http.fetch": "http.outbound",
+
+ // Secrets
+ "secrets.resolve": "secrets.read-ref",
+
+ // Assets
+ "assets.upload": "assets.write",
+ "assets.getUrl": "assets.read",
+
+ // Activity
+ "activity.log": "activity.log.write",
+
+ // Metrics
+ "metrics.write": "metrics.write",
+
+ // Logger — always allowed
+ "log": null,
+
+ // Companies
+ "companies.list": "companies.read",
+ "companies.get": "companies.read",
+
+ // Projects
+ "projects.list": "projects.read",
+ "projects.get": "projects.read",
+ "projects.listWorkspaces": "project.workspaces.read",
+ "projects.getPrimaryWorkspace": "project.workspaces.read",
+ "projects.getWorkspaceForIssue": "project.workspaces.read",
+
+ // Issues
+ "issues.list": "issues.read",
+ "issues.get": "issues.read",
+ "issues.create": "issues.create",
+ "issues.update": "issues.update",
+ "issues.listComments": "issue.comments.read",
+ "issues.createComment": "issue.comments.create",
+
+ // Agents
+ "agents.list": "agents.read",
+ "agents.get": "agents.read",
+ "agents.pause": "agents.pause",
+ "agents.resume": "agents.resume",
+ "agents.invoke": "agents.invoke",
+
+ // Agent Sessions
+ "agents.sessions.create": "agent.sessions.create",
+ "agents.sessions.list": "agent.sessions.list",
+ "agents.sessions.sendMessage": "agent.sessions.send",
+ "agents.sessions.close": "agent.sessions.close",
+
+ // Goals
+ "goals.list": "goals.read",
+ "goals.get": "goals.read",
+ "goals.create": "goals.create",
+ "goals.update": "goals.update",
+};
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a complete handler map for all worker→host JSON-RPC methods.
+ *
+ * Each handler:
+ * 1. Checks the plugin's declared capabilities against the required capability
+ * for the method (if any).
+ * 2. Delegates to the corresponding service adapter method.
+ * 3. Returns the service result, which is serialized as the JSON-RPC response
+ * by the worker manager.
+ *
+ * If a capability check fails, the handler throws a `CapabilityDeniedError`
+ * with code `CAPABILITY_DENIED`. The worker manager catches this and sends a
+ * JSON-RPC error response to the worker, which surfaces as a `JsonRpcCallError`
+ * in the plugin's SDK client.
+ *
+ * @param options - Plugin ID, capabilities, and service adapters
+ * @returns A handler map suitable for `WorkerStartOptions.hostHandlers`
+ */
+export function createHostClientHandlers(
+ options: HostClientFactoryOptions,
+): HostClientHandlers {
+ const { pluginId, services } = options;
+ const capabilitySet = new Set<PluginCapability>(options.capabilities);
+
+ /**
+ * Assert that the plugin has the required capability for a method.
+ * Throws `CapabilityDeniedError` if the capability is missing.
+ */
+ function requireCapability(
+ method: WorkerToHostMethodName,
+ ): void {
+ const required = METHOD_CAPABILITY_MAP[method];
+ if (required === null) return; // No capability required
+ if (capabilitySet.has(required)) return;
+ throw new CapabilityDeniedError(pluginId, method, required);
+ }
+
+ /**
+ * Create a capability-gated proxy handler for a method.
+ *
+ * @param method - The RPC method name (used for capability lookup)
+ * @param handler - The actual handler implementation
+ * @returns A wrapper that checks capabilities before delegating
+ */
+ function gated<M extends WorkerToHostMethodName>(
+ method: M,
+ handler: HostHandler<M>,
+ ): HostHandler<M> {
+ return async (params: WorkerToHostMethods[M][0]) => {
+ requireCapability(method);
+ return handler(params);
+ };
+ }
+
+ // -------------------------------------------------------------------------
+ // Build the complete handler map
+ // -------------------------------------------------------------------------
+
+ return {
+ // Config
+ "config.get": gated("config.get", async () => {
+ return services.config.get();
+ }),
+
+ // State
+ "state.get": gated("state.get", async (params) => {
+ return services.state.get(params);
+ }),
+ "state.set": gated("state.set", async (params) => {
+ return services.state.set(params);
+ }),
+ "state.delete": gated("state.delete", async (params) => {
+ return services.state.delete(params);
+ }),
+
+ // Entities
+ "entities.upsert": gated("entities.upsert", async (params) => {
+ return services.entities.upsert(params);
+ }),
+ "entities.list": gated("entities.list", async (params) => {
+ return services.entities.list(params);
+ }),
+
+ // Events
+ "events.emit": gated("events.emit", async (params) => {
+ return services.events.emit(params);
+ }),
+
+ // HTTP
+ "http.fetch": gated("http.fetch", async (params) => {
+ return services.http.fetch(params);
+ }),
+
+ // Secrets
+ "secrets.resolve": gated("secrets.resolve", async (params) => {
+ return services.secrets.resolve(params);
+ }),
+
+ // Assets
+ "assets.upload": gated("assets.upload", async (params) => {
+ return services.assets.upload(params);
+ }),
+ "assets.getUrl": gated("assets.getUrl", async (params) => {
+ return services.assets.getUrl(params);
+ }),
+
+ // Activity
+ "activity.log": gated("activity.log", async (params) => {
+ return services.activity.log(params);
+ }),
+
+ // Metrics
+ "metrics.write": gated("metrics.write", async (params) => {
+ return services.metrics.write(params);
+ }),
+
+ // Logger
+ "log": gated("log", async (params) => {
+ return services.logger.log(params);
+ }),
+
+ // Companies
+ "companies.list": gated("companies.list", async (params) => {
+ return services.companies.list(params);
+ }),
+ "companies.get": gated("companies.get", async (params) => {
+ return services.companies.get(params);
+ }),
+
+ // Projects
+ "projects.list": gated("projects.list", async (params) => {
+ return services.projects.list(params);
+ }),
+ "projects.get": gated("projects.get", async (params) => {
+ return services.projects.get(params);
+ }),
+ "projects.listWorkspaces": gated("projects.listWorkspaces", async (params) => {
+ return services.projects.listWorkspaces(params);
+ }),
+ "projects.getPrimaryWorkspace": gated("projects.getPrimaryWorkspace", async (params) => {
+ return services.projects.getPrimaryWorkspace(params);
+ }),
+ "projects.getWorkspaceForIssue": gated("projects.getWorkspaceForIssue", async (params) => {
+ return services.projects.getWorkspaceForIssue(params);
+ }),
+
+ // Issues
+ "issues.list": gated("issues.list", async (params) => {
+ return services.issues.list(params);
+ }),
+ "issues.get": gated("issues.get", async (params) => {
+ return services.issues.get(params);
+ }),
+ "issues.create": gated("issues.create", async (params) => {
+ return services.issues.create(params);
+ }),
+ "issues.update": gated("issues.update", async (params) => {
+ return services.issues.update(params);
+ }),
+ "issues.listComments": gated("issues.listComments", async (params) => {
+ return services.issues.listComments(params);
+ }),
+ "issues.createComment": gated("issues.createComment", async (params) => {
+ return services.issues.createComment(params);
+ }),
+
+ // Agents
+ "agents.list": gated("agents.list", async (params) => {
+ return services.agents.list(params);
+ }),
+ "agents.get": gated("agents.get", async (params) => {
+ return services.agents.get(params);
+ }),
+ "agents.pause": gated("agents.pause", async (params) => {
+ return services.agents.pause(params);
+ }),
+ "agents.resume": gated("agents.resume", async (params) => {
+ return services.agents.resume(params);
+ }),
+ "agents.invoke": gated("agents.invoke", async (params) => {
+ return services.agents.invoke(params);
+ }),
+
+ // Agent Sessions
+ "agents.sessions.create": gated("agents.sessions.create", async (params) => {
+ return services.agentSessions.create(params);
+ }),
+ "agents.sessions.list": gated("agents.sessions.list", async (params) => {
+ return services.agentSessions.list(params);
+ }),
+ "agents.sessions.sendMessage": gated("agents.sessions.sendMessage", async (params) => {
+ return services.agentSessions.sendMessage(params);
+ }),
+ "agents.sessions.close": gated("agents.sessions.close", async (params) => {
+ return services.agentSessions.close(params);
+ }),
+
+ // Goals
+ "goals.list": gated("goals.list", async (params) => {
+ return services.goals.list(params);
+ }),
+ "goals.get": gated("goals.get", async (params) => {
+ return services.goals.get(params);
+ }),
+ "goals.create": gated("goals.create", async (params) => {
+ return services.goals.create(params);
+ }),
+ "goals.update": gated("goals.update", async (params) => {
+ return services.goals.update(params);
+ }),
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Utility: getRequiredCapability
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the capability required for a given worker→host method, or `null` if
+ * no capability is required.
+ *
+ * Useful for inspecting capability requirements without calling the factory.
+ *
+ * @param method - The worker→host method name
+ * @returns The required capability, or `null`
+ */
+export function getRequiredCapability(
+ method: WorkerToHostMethodName,
+): PluginCapability | null {
+ return METHOD_CAPABILITY_MAP[method];
+}
diff --git a/packages/plugins/sdk/src/index.ts b/packages/plugins/sdk/src/index.ts
new file mode 100644
index 0000000000..60c59f6aad
--- /dev/null
+++ b/packages/plugins/sdk/src/index.ts
@@ -0,0 +1,287 @@
+/**
+ * `@paperclipai/plugin-sdk` — Paperclip plugin worker-side SDK.
+ *
+ * This is the main entrypoint for plugin worker code. For plugin UI bundles,
+ * import from `@paperclipai/plugin-sdk/ui` instead.
+ *
+ * @example
+ * ```ts
+ * // Plugin worker entrypoint (dist/worker.ts)
+ * import { definePlugin, runWorker, z } from "@paperclipai/plugin-sdk";
+ *
+ * const plugin = definePlugin({
+ * async setup(ctx) {
+ * ctx.logger.info("Plugin starting up");
+ *
+ * ctx.events.on("issue.created", async (event) => {
+ * ctx.logger.info("Issue created", { issueId: event.entityId });
+ * });
+ *
+ * ctx.jobs.register("full-sync", async (job) => {
+ * ctx.logger.info("Starting full sync", { runId: job.runId });
+ * // ... sync implementation
+ * });
+ *
+ * ctx.data.register("sync-health", async ({ companyId }) => {
+ * const state = await ctx.state.get({
+ * scopeKind: "company",
+ * scopeId: String(companyId),
+ * stateKey: "last-sync-at",
+ * });
+ * return { lastSync: state };
+ * });
+ * },
+ *
+ * async onHealth() {
+ * return { status: "ok" };
+ * },
+ * });
+ *
+ * export default plugin;
+ * runWorker(plugin, import.meta.url);
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §14 — SDK Surface
+ * @see PLUGIN_SPEC.md §29.2 — SDK Versioning
+ */
+
+// ---------------------------------------------------------------------------
+// Main factory
+// ---------------------------------------------------------------------------
+
+export { definePlugin } from "./define-plugin.js";
+export { createTestHarness } from "./testing.js";
+export { createPluginBundlerPresets } from "./bundlers.js";
+export { startPluginDevServer, getUiBuildSnapshot } from "./dev-server.js";
+export { startWorkerRpcHost, runWorker } from "./worker-rpc-host.js";
+export {
+ createHostClientHandlers,
+ getRequiredCapability,
+ CapabilityDeniedError,
+} from "./host-client-factory.js";
+
+// JSON-RPC protocol helpers and constants
+export {
+ JSONRPC_VERSION,
+ JSONRPC_ERROR_CODES,
+ PLUGIN_RPC_ERROR_CODES,
+ HOST_TO_WORKER_REQUIRED_METHODS,
+ HOST_TO_WORKER_OPTIONAL_METHODS,
+ MESSAGE_DELIMITER,
+ createRequest,
+ createSuccessResponse,
+ createErrorResponse,
+ createNotification,
+ isJsonRpcRequest,
+ isJsonRpcNotification,
+ isJsonRpcResponse,
+ isJsonRpcSuccessResponse,
+ isJsonRpcErrorResponse,
+ serializeMessage,
+ parseMessage,
+ JsonRpcParseError,
+ JsonRpcCallError,
+ _resetIdCounter,
+} from "./protocol.js";
+
+// ---------------------------------------------------------------------------
+// Type exports
+// ---------------------------------------------------------------------------
+
+// Plugin definition and lifecycle types
+export type {
+ PluginDefinition,
+ PaperclipPlugin,
+ PluginHealthDiagnostics,
+ PluginConfigValidationResult,
+ PluginWebhookInput,
+} from "./define-plugin.js";
+export type {
+ TestHarness,
+ TestHarnessOptions,
+ TestHarnessLogEntry,
+} from "./testing.js";
+export type {
+ PluginBundlerPresetInput,
+ PluginBundlerPresets,
+ EsbuildLikeOptions,
+ RollupLikeConfig,
+} from "./bundlers.js";
+export type { PluginDevServer, PluginDevServerOptions } from "./dev-server.js";
+export type {
+ WorkerRpcHostOptions,
+ WorkerRpcHost,
+ RunWorkerOptions,
+} from "./worker-rpc-host.js";
+export type {
+ HostServices,
+ HostClientFactoryOptions,
+ HostClientHandlers,
+} from "./host-client-factory.js";
+
+// JSON-RPC protocol types
+export type {
+ JsonRpcId,
+ JsonRpcRequest,
+ JsonRpcSuccessResponse,
+ JsonRpcError,
+ JsonRpcErrorResponse,
+ JsonRpcResponse,
+ JsonRpcNotification,
+ JsonRpcMessage,
+ JsonRpcErrorCode,
+ PluginRpcErrorCode,
+ InitializeParams,
+ InitializeResult,
+ ConfigChangedParams,
+ ValidateConfigParams,
+ OnEventParams,
+ RunJobParams,
+ GetDataParams,
+ PerformActionParams,
+ ExecuteToolParams,
+ PluginModalBoundsRequest,
+ PluginRenderCloseEvent,
+ PluginLauncherRenderContextSnapshot,
+ HostToWorkerMethods,
+ HostToWorkerMethodName,
+ WorkerToHostMethods,
+ WorkerToHostMethodName,
+ HostToWorkerRequest,
+ HostToWorkerResponse,
+ WorkerToHostRequest,
+ WorkerToHostResponse,
+ WorkerToHostNotifications,
+ WorkerToHostNotificationName,
+} from "./protocol.js";
+
+// Plugin context and all client interfaces
+export type {
+ PluginContext,
+ PluginConfigClient,
+ PluginEventsClient,
+ PluginJobsClient,
+ PluginLaunchersClient,
+ PluginHttpClient,
+ PluginSecretsClient,
+ PluginAssetsClient,
+ PluginActivityClient,
+ PluginActivityLogEntry,
+ PluginStateClient,
+ PluginEntitiesClient,
+ PluginProjectsClient,
+ PluginCompaniesClient,
+ PluginIssuesClient,
+ PluginAgentsClient,
+ PluginAgentSessionsClient,
+ AgentSession,
+ AgentSessionEvent,
+ AgentSessionSendResult,
+ PluginGoalsClient,
+ PluginDataClient,
+ PluginActionsClient,
+ PluginStreamsClient,
+ PluginToolsClient,
+ PluginMetricsClient,
+ PluginLogger,
+} from "./types.js";
+
+// Supporting types for context clients
+export type {
+ ScopeKey,
+ EventFilter,
+ PluginEvent,
+ PluginJobContext,
+ PluginLauncherRegistration,
+ ToolRunContext,
+ ToolResult,
+ PluginEntityUpsert,
+ PluginEntityRecord,
+ PluginEntityQuery,
+ PluginWorkspace,
+ Company,
+ Project,
+ Issue,
+ IssueComment,
+ Agent,
+ Goal,
+} from "./types.js";
+
+// Manifest and constant types re-exported from @paperclipai/shared
+// Plugin authors import manifest types from here so they have a single
+// dependency (@paperclipai/plugin-sdk) for all plugin authoring needs.
+export type {
+ PaperclipPluginManifestV1,
+ PluginJobDeclaration,
+ PluginWebhookDeclaration,
+ PluginToolDeclaration,
+ PluginUiSlotDeclaration,
+ PluginUiDeclaration,
+ PluginLauncherActionDeclaration,
+ PluginLauncherRenderDeclaration,
+ PluginLauncherDeclaration,
+ PluginMinimumHostVersion,
+ PluginRecord,
+ PluginConfig,
+ JsonSchema,
+ PluginStatus,
+ PluginCategory,
+ PluginCapability,
+ PluginUiSlotType,
+ PluginUiSlotEntityType,
+ PluginLauncherPlacementZone,
+ PluginLauncherAction,
+ PluginLauncherBounds,
+ PluginLauncherRenderEnvironment,
+ PluginStateScopeKind,
+ PluginJobStatus,
+ PluginJobRunStatus,
+ PluginJobRunTrigger,
+ PluginWebhookDeliveryStatus,
+ PluginEventType,
+ PluginBridgeErrorCode,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Zod re-export
+// ---------------------------------------------------------------------------
+
+/**
+ * Zod is re-exported for plugin authors to use when defining their
+ * `instanceConfigSchema` and tool `parametersSchema`.
+ *
+ * Plugin authors do not need to add a separate `zod` dependency.
+ *
+ * @see PLUGIN_SPEC.md §14.1 — Example SDK Shape
+ *
+ * @example
+ * ```ts
+ * import { z } from "@paperclipai/plugin-sdk";
+ *
+ * const configSchema = z.object({
+ * apiKey: z.string().describe("Your API key"),
+ * workspace: z.string().optional(),
+ * });
+ * ```
+ */
+export { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Constants re-exports (for plugin code that needs to check values at runtime)
+// ---------------------------------------------------------------------------
+
+export {
+ PLUGIN_API_VERSION,
+ PLUGIN_STATUSES,
+ PLUGIN_CATEGORIES,
+ PLUGIN_CAPABILITIES,
+ PLUGIN_UI_SLOT_TYPES,
+ PLUGIN_UI_SLOT_ENTITY_TYPES,
+ PLUGIN_STATE_SCOPE_KINDS,
+ PLUGIN_JOB_STATUSES,
+ PLUGIN_JOB_RUN_STATUSES,
+ PLUGIN_JOB_RUN_TRIGGERS,
+ PLUGIN_WEBHOOK_DELIVERY_STATUSES,
+ PLUGIN_EVENT_TYPES,
+ PLUGIN_BRIDGE_ERROR_CODES,
+} from "@paperclipai/shared";
diff --git a/packages/plugins/sdk/src/protocol.ts b/packages/plugins/sdk/src/protocol.ts
new file mode 100644
index 0000000000..211f2573b5
--- /dev/null
+++ b/packages/plugins/sdk/src/protocol.ts
@@ -0,0 +1,1038 @@
+/**
+ * JSON-RPC 2.0 message types and protocol helpers for the host ↔ worker IPC
+ * channel.
+ *
+ * The Paperclip plugin runtime uses JSON-RPC 2.0 over stdio to communicate
+ * between the host process and each plugin worker process. This module defines:
+ *
+ * - Core JSON-RPC 2.0 envelope types (request, response, notification, error)
+ * - Standard and plugin-specific error codes
+ * - Typed method maps for host→worker and worker→host calls
+ * - Helper functions for creating well-formed messages
+ *
+ * @see PLUGIN_SPEC.md §12.1 — Process Model
+ * @see PLUGIN_SPEC.md §13 — Host-Worker Protocol
+ * @see https://www.jsonrpc.org/specification
+ */
+
+import type {
+ PaperclipPluginManifestV1,
+ PluginLauncherBounds,
+ PluginLauncherRenderContextSnapshot,
+ PluginLauncherRenderEnvironment,
+ PluginStateScopeKind,
+ Company,
+ Project,
+ Issue,
+ IssueComment,
+ Agent,
+ Goal,
+} from "@paperclipai/shared";
+export type { PluginLauncherRenderContextSnapshot } from "@paperclipai/shared";
+
+import type {
+ PluginEvent,
+ PluginJobContext,
+ PluginWorkspace,
+ ToolRunContext,
+ ToolResult,
+} from "./types.js";
+import type {
+ PluginHealthDiagnostics,
+ PluginConfigValidationResult,
+ PluginWebhookInput,
+} from "./define-plugin.js";
+
+// ---------------------------------------------------------------------------
+// JSON-RPC 2.0 — Core Protocol Types
+// ---------------------------------------------------------------------------
+
+/** The JSON-RPC protocol version. Always `"2.0"`. */
+export const JSONRPC_VERSION = "2.0" as const;
+
+/**
+ * A unique request identifier. JSON-RPC 2.0 allows strings or numbers;
+ * we use strings (UUIDs or monotonic counters) for all Paperclip messages.
+ */
+export type JsonRpcId = string | number;
+
+/**
+ * A JSON-RPC 2.0 request message.
+ *
+ * The host sends requests to the worker (or vice versa) and expects a
+ * matching response with the same `id`.
+ */
+export interface JsonRpcRequest<
+ TMethod extends string = string,
+ TParams = unknown,
+> {
+ readonly jsonrpc: typeof JSONRPC_VERSION;
+ /** Unique request identifier. Must be echoed in the response. */
+ readonly id: JsonRpcId;
+ /** The RPC method name to invoke. */
+ readonly method: TMethod;
+ /** Structured parameters for the method call. */
+ readonly params: TParams;
+}
+
+/**
+ * A JSON-RPC 2.0 success response.
+ */
+export interface JsonRpcSuccessResponse<TResult = unknown> {
+ readonly jsonrpc: typeof JSONRPC_VERSION;
+ /** Echoed request identifier. */
+ readonly id: JsonRpcId;
+ /** The method return value. */
+ readonly result: TResult;
+ readonly error?: never;
+}
+
+/**
+ * A JSON-RPC 2.0 error object embedded in an error response.
+ */
+export interface JsonRpcError<TData = unknown> {
+ /** Machine-readable error code. */
+ readonly code: number;
+ /** Human-readable error message. */
+ readonly message: string;
+ /** Optional structured error data. */
+ readonly data?: TData;
+}
+
+/**
+ * A JSON-RPC 2.0 error response.
+ */
+export interface JsonRpcErrorResponse<TData = unknown> {
+ readonly jsonrpc: typeof JSONRPC_VERSION;
+ /** Echoed request identifier. */
+ readonly id: JsonRpcId | null;
+ readonly result?: never;
+ /** The error object. */
+ readonly error: JsonRpcError<TData>;
+}
+
+/**
+ * A JSON-RPC 2.0 response — either success or error.
+ */
+export type JsonRpcResponse<TResult = unknown, TData = unknown> =
+ | JsonRpcSuccessResponse<TResult>
+ | JsonRpcErrorResponse<TData>;
+
+/**
+ * A JSON-RPC 2.0 notification (a request with no `id`).
+ *
+ * Notifications are fire-and-forget — no response is expected.
+ */
+export interface JsonRpcNotification<
+ TMethod extends string = string,
+ TParams = unknown,
+> {
+ readonly jsonrpc: typeof JSONRPC_VERSION;
+ readonly id?: never;
+ /** The notification method name. */
+ readonly method: TMethod;
+ /** Structured parameters for the notification. */
+ readonly params: TParams;
+}
+
+/**
+ * Any well-formed JSON-RPC 2.0 message (request, response, or notification).
+ */
+export type JsonRpcMessage =
+ | JsonRpcRequest
+ | JsonRpcResponse
+ | JsonRpcNotification;
+
+// ---------------------------------------------------------------------------
+// Error Codes
+// ---------------------------------------------------------------------------
+
+/**
+ * Standard JSON-RPC 2.0 error codes.
+ *
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
+export const JSONRPC_ERROR_CODES = {
+ /** Invalid JSON was received by the server. */
+ PARSE_ERROR: -32700,
+ /** The JSON sent is not a valid Request object. */
+ INVALID_REQUEST: -32600,
+ /** The method does not exist or is not available. */
+ METHOD_NOT_FOUND: -32601,
+ /** Invalid method parameter(s). */
+ INVALID_PARAMS: -32602,
+ /** Internal JSON-RPC error. */
+ INTERNAL_ERROR: -32603,
+} as const;
+
+export type JsonRpcErrorCode =
+ (typeof JSONRPC_ERROR_CODES)[keyof typeof JSONRPC_ERROR_CODES];
+
+/**
+ * Paperclip plugin-specific error codes.
+ *
+ * These live in the JSON-RPC "server error" reserved range (-32000 to -32099)
+ * as specified by JSON-RPC 2.0 for implementation-defined server errors.
+ *
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+export const PLUGIN_RPC_ERROR_CODES = {
+ /** The worker process is not running or not reachable. */
+ WORKER_UNAVAILABLE: -32000,
+ /** The plugin does not have the required capability for this operation. */
+ CAPABILITY_DENIED: -32001,
+ /** The worker reported an unhandled error during method execution. */
+ WORKER_ERROR: -32002,
+ /** The method call timed out waiting for the worker response. */
+ TIMEOUT: -32003,
+ /** The worker does not implement the requested optional method. */
+ METHOD_NOT_IMPLEMENTED: -32004,
+ /** A catch-all for errors that do not fit other categories. */
+ UNKNOWN: -32099,
+} as const;
+
+export type PluginRpcErrorCode =
+ (typeof PLUGIN_RPC_ERROR_CODES)[keyof typeof PLUGIN_RPC_ERROR_CODES];
+
+// ---------------------------------------------------------------------------
+// Host → Worker Method Signatures (§13 Host-Worker Protocol)
+// ---------------------------------------------------------------------------
+
+/**
+ * Input for the `initialize` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.1 — `initialize`
+ */
+export interface InitializeParams {
+ /** Full plugin manifest snapshot. */
+ manifest: PaperclipPluginManifestV1;
+ /** Resolved operator configuration (validated against `instanceConfigSchema`). */
+ config: Record<string, unknown>;
+ /** Instance-level metadata. */
+ instanceInfo: {
+ /** UUID of this Paperclip instance. */
+ instanceId: string;
+ /** Semver version of the running Paperclip host. */
+ hostVersion: string;
+ };
+ /** Host API version. */
+ apiVersion: number;
+}
+
+/**
+ * Result returned by the `initialize` RPC method.
+ */
+export interface InitializeResult {
+ /** Whether initialization succeeded. */
+ ok: boolean;
+ /** Optional methods the worker has implemented (e.g. "validateConfig", "onEvent"). */
+ supportedMethods?: string[];
+}
+
+/**
+ * Input for the `configChanged` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.4 — `configChanged`
+ */
+export interface ConfigChangedParams {
+ /** The newly resolved configuration. */
+ config: Record<string, unknown>;
+}
+
+/**
+ * Input for the `validateConfig` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.3 — `validateConfig`
+ */
+export interface ValidateConfigParams {
+ /** The configuration to validate. */
+ config: Record<string, unknown>;
+}
+
+/**
+ * Input for the `onEvent` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.5 — `onEvent`
+ */
+export interface OnEventParams {
+ /** The domain event to deliver. */
+ event: PluginEvent;
+}
+
+/**
+ * Input for the `runJob` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.6 — `runJob`
+ */
+export interface RunJobParams {
+ /** Job execution context. */
+ job: PluginJobContext;
+}
+
+/**
+ * Input for the `getData` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.8 — `getData`
+ */
+export interface GetDataParams {
+ /** Plugin-defined data key (e.g. `"sync-health"`). */
+ key: string;
+ /** Context and query parameters from the UI. */
+ params: Record<string, unknown>;
+ /** Optional launcher/container metadata from the host render environment. */
+ renderEnvironment?: PluginLauncherRenderContextSnapshot | null;
+}
+
+/**
+ * Input for the `performAction` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.9 — `performAction`
+ */
+export interface PerformActionParams {
+ /** Plugin-defined action key (e.g. `"resync"`). */
+ key: string;
+ /** Action parameters from the UI. */
+ params: Record<string, unknown>;
+ /** Optional launcher/container metadata from the host render environment. */
+ renderEnvironment?: PluginLauncherRenderContextSnapshot | null;
+}
+
+/**
+ * Input for the `executeTool` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.10 — `executeTool`
+ */
+export interface ExecuteToolParams {
+ /** Tool name (without plugin namespace prefix). */
+ toolName: string;
+ /** Parsed parameters matching the tool's declared schema. */
+ parameters: unknown;
+ /** Agent run context. */
+ runContext: ToolRunContext;
+}
+
+// ---------------------------------------------------------------------------
+// UI launcher / modal host interaction payloads
+// ---------------------------------------------------------------------------
+
+/**
+ * Bounds request issued by a plugin UI running inside a host-managed launcher
+ * container such as a modal, drawer, or popover.
+ */
+export interface PluginModalBoundsRequest {
+ /** High-level size preset requested from the host. */
+ bounds: PluginLauncherBounds;
+ /** Optional explicit width override in CSS pixels. */
+ width?: number;
+ /** Optional explicit height override in CSS pixels. */
+ height?: number;
+ /** Optional lower bounds for host resizing decisions. */
+ minWidth?: number;
+ minHeight?: number;
+ /** Optional upper bounds for host resizing decisions. */
+ maxWidth?: number;
+ maxHeight?: number;
+}
+
+/**
+ * Reason metadata supplied by host-managed close lifecycle callbacks.
+ */
+export interface PluginRenderCloseEvent {
+ reason:
+ | "escapeKey"
+ | "backdrop"
+ | "hostNavigation"
+ | "programmatic"
+ | "submit"
+ | "unknown";
+ nativeEvent?: unknown;
+}
+
+/**
+ * Map of host→worker RPC method names to their `[params, result]` types.
+ *
+ * This type is the single source of truth for all methods the host can call
+ * on a worker. Used by both the host dispatcher and the worker handler to
+ * ensure type safety across the IPC boundary.
+ */
+export interface HostToWorkerMethods {
+ /** @see PLUGIN_SPEC.md §13.1 */
+ initialize: [params: InitializeParams, result: InitializeResult];
+ /** @see PLUGIN_SPEC.md §13.2 */
+ health: [params: Record<string, never>, result: PluginHealthDiagnostics];
+ /** @see PLUGIN_SPEC.md §12.5 */
+ shutdown: [params: Record<string, never>, result: void];
+ /** @see PLUGIN_SPEC.md §13.3 */
+ validateConfig: [params: ValidateConfigParams, result: PluginConfigValidationResult];
+ /** @see PLUGIN_SPEC.md §13.4 */
+ configChanged: [params: ConfigChangedParams, result: void];
+ /** @see PLUGIN_SPEC.md §13.5 */
+ onEvent: [params: OnEventParams, result: void];
+ /** @see PLUGIN_SPEC.md §13.6 */
+ runJob: [params: RunJobParams, result: void];
+ /** @see PLUGIN_SPEC.md §13.7 */
+ handleWebhook: [params: PluginWebhookInput, result: void];
+ /** @see PLUGIN_SPEC.md §13.8 */
+ getData: [params: GetDataParams, result: unknown];
+ /** @see PLUGIN_SPEC.md §13.9 */
+ performAction: [params: PerformActionParams, result: unknown];
+ /** @see PLUGIN_SPEC.md §13.10 */
+ executeTool: [params: ExecuteToolParams, result: ToolResult];
+}
+
+/** Union of all host→worker method names. */
+export type HostToWorkerMethodName = keyof HostToWorkerMethods;
+
+/** Required methods the worker MUST implement. */
+export const HOST_TO_WORKER_REQUIRED_METHODS: readonly HostToWorkerMethodName[] = [
+ "initialize",
+ "health",
+ "shutdown",
+] as const;
+
+/** Optional methods the worker MAY implement. */
+export const HOST_TO_WORKER_OPTIONAL_METHODS: readonly HostToWorkerMethodName[] = [
+ "validateConfig",
+ "configChanged",
+ "onEvent",
+ "runJob",
+ "handleWebhook",
+ "getData",
+ "performAction",
+ "executeTool",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Worker → Host Method Signatures (SDK client calls)
+// ---------------------------------------------------------------------------
+
+/**
+ * Map of worker→host RPC method names to their `[params, result]` types.
+ *
+ * These represent the SDK client calls that the worker makes back to the
+ * host to access platform services (state, entities, config, etc.).
+ */
+export interface WorkerToHostMethods {
+ // Config
+ "config.get": [params: Record<string, never>, result: Record<string, unknown>];
+
+ // State
+ "state.get": [
+ params: { scopeKind: string; scopeId?: string; namespace?: string; stateKey: string },
+ result: unknown,
+ ];
+ "state.set": [
+ params: { scopeKind: string; scopeId?: string; namespace?: string; stateKey: string; value: unknown },
+ result: void,
+ ];
+ "state.delete": [
+ params: { scopeKind: string; scopeId?: string; namespace?: string; stateKey: string },
+ result: void,
+ ];
+
+ // Entities
+ "entities.upsert": [
+ params: {
+ entityType: string;
+ scopeKind: PluginStateScopeKind;
+ scopeId?: string;
+ externalId?: string;
+ title?: string;
+ status?: string;
+ data: Record<string, unknown>;
+ },
+ result: {
+ id: string;
+ entityType: string;
+ scopeKind: PluginStateScopeKind;
+ scopeId: string | null;
+ externalId: string | null;
+ title: string | null;
+ status: string | null;
+ data: Record<string, unknown>;
+ createdAt: string;
+ updatedAt: string;
+ },
+ ];
+ "entities.list": [
+ params: {
+ entityType?: string;
+ scopeKind?: PluginStateScopeKind;
+ scopeId?: string;
+ externalId?: string;
+ limit?: number;
+ offset?: number;
+ },
+ result: Array<{
+ id: string;
+ entityType: string;
+ scopeKind: PluginStateScopeKind;
+ scopeId: string | null;
+ externalId: string | null;
+ title: string | null;
+ status: string | null;
+ data: Record<string, unknown>;
+ createdAt: string;
+ updatedAt: string;
+ }>,
+ ];
+
+ // Events
+ "events.emit": [
+ params: { name: string; companyId: string; payload: unknown },
+ result: void,
+ ];
+
+ // HTTP
+ "http.fetch": [
+ params: { url: string; init?: Record<string, unknown> },
+ result: { status: number; statusText: string; headers: Record<string, string>; body: string },
+ ];
+
+ // Secrets
+ "secrets.resolve": [
+ params: { secretRef: string },
+ result: string,
+ ];
+
+ // Assets
+ "assets.upload": [
+ params: { filename: string; contentType: string; data: string },
+ result: { assetId: string; url: string },
+ ];
+ "assets.getUrl": [
+ params: { assetId: string },
+ result: string,
+ ];
+
+ // Activity
+ "activity.log": [
+ params: {
+ companyId: string;
+ message: string;
+ entityType?: string;
+ entityId?: string;
+ metadata?: Record<string, unknown>;
+ },
+ result: void,
+ ];
+
+ // Metrics
+ "metrics.write": [
+ params: { name: string; value: number; tags?: Record<string, string> },
+ result: void,
+ ];
+
+ // Logger
+ "log": [
+ params: { level: "info" | "warn" | "error" | "debug"; message: string; meta?: Record<string, unknown> },
+ result: void,
+ ];
+
+ // Companies (read)
+ "companies.list": [
+ params: { limit?: number; offset?: number },
+ result: Company[],
+ ];
+ "companies.get": [
+ params: { companyId: string },
+ result: Company | null,
+ ];
+
+ // Projects (read)
+ "projects.list": [
+ params: { companyId: string; limit?: number; offset?: number },
+ result: Project[],
+ ];
+ "projects.get": [
+ params: { projectId: string; companyId: string },
+ result: Project | null,
+ ];
+ "projects.listWorkspaces": [
+ params: { projectId: string; companyId: string },
+ result: PluginWorkspace[],
+ ];
+ "projects.getPrimaryWorkspace": [
+ params: { projectId: string; companyId: string },
+ result: PluginWorkspace | null,
+ ];
+ "projects.getWorkspaceForIssue": [
+ params: { issueId: string; companyId: string },
+ result: PluginWorkspace | null,
+ ];
+
+ // Issues
+ "issues.list": [
+ params: {
+ companyId: string;
+ projectId?: string;
+ assigneeAgentId?: string;
+ status?: string;
+ limit?: number;
+ offset?: number;
+ },
+ result: Issue[],
+ ];
+ "issues.get": [
+ params: { issueId: string; companyId: string },
+ result: Issue | null,
+ ];
+ "issues.create": [
+ params: {
+ companyId: string;
+ projectId?: string;
+ goalId?: string;
+ parentId?: string;
+ title: string;
+ description?: string;
+ priority?: string;
+ assigneeAgentId?: string;
+ },
+ result: Issue,
+ ];
+ "issues.update": [
+ params: {
+ issueId: string;
+ patch: Record<string, unknown>;
+ companyId: string;
+ },
+ result: Issue,
+ ];
+ "issues.listComments": [
+ params: { issueId: string; companyId: string },
+ result: IssueComment[],
+ ];
+ "issues.createComment": [
+ params: { issueId: string; body: string; companyId: string },
+ result: IssueComment,
+ ];
+
+ // Agents (read)
+ "agents.list": [
+ params: { companyId: string; status?: string; limit?: number; offset?: number },
+ result: Agent[],
+ ];
+ "agents.get": [
+ params: { agentId: string; companyId: string },
+ result: Agent | null,
+ ];
+
+ // Agents (write)
+ "agents.pause": [
+ params: { agentId: string; companyId: string },
+ result: Agent,
+ ];
+ "agents.resume": [
+ params: { agentId: string; companyId: string },
+ result: Agent,
+ ];
+ "agents.invoke": [
+ params: { agentId: string; companyId: string; prompt: string; reason?: string },
+ result: { runId: string },
+ ];
+
+ // Agent Sessions
+ "agents.sessions.create": [
+ params: { agentId: string; companyId: string; taskKey?: string; reason?: string },
+ result: { sessionId: string; agentId: string; companyId: string; status: "active" | "closed"; createdAt: string },
+ ];
+ "agents.sessions.list": [
+ params: { agentId: string; companyId: string },
+ result: Array<{ sessionId: string; agentId: string; companyId: string; status: "active" | "closed"; createdAt: string }>,
+ ];
+ "agents.sessions.sendMessage": [
+ params: { sessionId: string; companyId: string; prompt: string; reason?: string },
+ result: { runId: string },
+ ];
+ "agents.sessions.close": [
+ params: { sessionId: string; companyId: string },
+ result: void,
+ ];
+
+ // Goals
+ "goals.list": [
+ params: { companyId: string; level?: string; status?: string; limit?: number; offset?: number },
+ result: Goal[],
+ ];
+ "goals.get": [
+ params: { goalId: string; companyId: string },
+ result: Goal | null,
+ ];
+ "goals.create": [
+ params: {
+ companyId: string;
+ title: string;
+ description?: string;
+ level?: string;
+ status?: string;
+ parentId?: string;
+ ownerAgentId?: string;
+ },
+ result: Goal,
+ ];
+ "goals.update": [
+ params: {
+ goalId: string;
+ patch: Record<string, unknown>;
+ companyId: string;
+ },
+ result: Goal,
+ ];
+}
+
+/** Union of all worker→host method names. */
+export type WorkerToHostMethodName = keyof WorkerToHostMethods;
+
+// ---------------------------------------------------------------------------
+// Worker→Host Notification Types (fire-and-forget, no response)
+// ---------------------------------------------------------------------------
+
+/**
+ * Typed parameter shapes for worker→host JSON-RPC notifications.
+ *
+ * Notifications are fire-and-forget — the worker does not wait for a response.
+ * These are used for streaming events and logging, not for request-response RPCs.
+ */
+export interface WorkerToHostNotifications {
+ /**
+ * Forward a stream event to connected SSE clients.
+ *
+ * Emitted by the worker for each event on a stream channel. The host
+ * publishes to the PluginStreamBus, which fans out to all SSE clients
+ * subscribed to the (pluginId, channel, companyId) tuple.
+ *
+ * The `event` payload is JSON-serializable and sent as SSE `data:`.
+ * The default SSE event type is `"message"`.
+ */
+ "streams.emit": {
+ channel: string;
+ companyId: string;
+ event: unknown;
+ };
+
+ /**
+ * Signal that a stream channel has been opened.
+ *
+ * Emitted when the worker calls `ctx.streams.open(channel, companyId)`.
+ * UI clients may use this to display a "connected" indicator or begin
+ * buffering input. The host tracks open channels so it can emit synthetic
+ * close events if the worker crashes.
+ */
+ "streams.open": {
+ channel: string;
+ companyId: string;
+ };
+
+ /**
+ * Signal that a stream channel has been closed.
+ *
+ * Emitted when the worker calls `ctx.streams.close(channel)`, or
+ * synthetically by the host when a worker process exits with channels
+ * still open. UI clients should treat this as terminal and disconnect
+ * the SSE connection.
+ */
+ "streams.close": {
+ channel: string;
+ companyId: string;
+ };
+}
+
+/** Union of all worker→host notification method names. */
+export type WorkerToHostNotificationName = keyof WorkerToHostNotifications;
+
+// ---------------------------------------------------------------------------
+// Typed Request / Response Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * A typed JSON-RPC request for a specific host→worker method.
+ */
+export type HostToWorkerRequest<M extends HostToWorkerMethodName> =
+ JsonRpcRequest<M, HostToWorkerMethods[M][0]>;
+
+/**
+ * A typed JSON-RPC success response for a specific host→worker method.
+ */
+export type HostToWorkerResponse<M extends HostToWorkerMethodName> =
+ JsonRpcSuccessResponse<HostToWorkerMethods[M][1]>;
+
+/**
+ * A typed JSON-RPC request for a specific worker→host method.
+ */
+export type WorkerToHostRequest<M extends WorkerToHostMethodName> =
+ JsonRpcRequest<M, WorkerToHostMethods[M][0]>;
+
+/**
+ * A typed JSON-RPC success response for a specific worker→host method.
+ */
+export type WorkerToHostResponse<M extends WorkerToHostMethodName> =
+ JsonRpcSuccessResponse<WorkerToHostMethods[M][1]>;
+
+// ---------------------------------------------------------------------------
+// Message Factory Functions
+// ---------------------------------------------------------------------------
+
+/** Counter for generating unique request IDs when no explicit ID is provided. */
+let _nextId = 1;
+
+/** Wrap around before reaching Number.MAX_SAFE_INTEGER to prevent precision loss. */
+const MAX_SAFE_RPC_ID = Number.MAX_SAFE_INTEGER - 1;
+
+/**
+ * Create a JSON-RPC 2.0 request message.
+ *
+ * @param method - The RPC method name
+ * @param params - Structured parameters
+ * @param id - Optional explicit request ID (auto-generated if omitted)
+ */
+export function createRequest<TMethod extends string>(
+ method: TMethod,
+ params: unknown,
+ id?: JsonRpcId,
+): JsonRpcRequest<TMethod> {
+ if (_nextId >= MAX_SAFE_RPC_ID) {
+ _nextId = 1;
+ }
+ return {
+ jsonrpc: JSONRPC_VERSION,
+ id: id ?? _nextId++,
+ method,
+ params,
+ };
+}
+
+/**
+ * Create a JSON-RPC 2.0 success response.
+ *
+ * @param id - The request ID being responded to
+ * @param result - The result value
+ */
+export function createSuccessResponse<TResult>(
+ id: JsonRpcId,
+ result: TResult,
+): JsonRpcSuccessResponse<TResult> {
+ return {
+ jsonrpc: JSONRPC_VERSION,
+ id,
+ result,
+ };
+}
+
+/**
+ * Create a JSON-RPC 2.0 error response.
+ *
+ * @param id - The request ID being responded to (null if the request ID could not be determined)
+ * @param code - Machine-readable error code
+ * @param message - Human-readable error message
+ * @param data - Optional structured error data
+ */
+export function createErrorResponse<TData = unknown>(
+ id: JsonRpcId | null,
+ code: number,
+ message: string,
+ data?: TData,
+): JsonRpcErrorResponse<TData> {
+ const response: JsonRpcErrorResponse<TData> = {
+ jsonrpc: JSONRPC_VERSION,
+ id,
+ error: data !== undefined
+ ? { code, message, data }
+ : { code, message } as JsonRpcError<TData>,
+ };
+ return response;
+}
+
+/**
+ * Create a JSON-RPC 2.0 notification (fire-and-forget, no response expected).
+ *
+ * @param method - The notification method name
+ * @param params - Structured parameters
+ */
+export function createNotification<TMethod extends string>(
+ method: TMethod,
+ params: unknown,
+): JsonRpcNotification<TMethod> {
+ return {
+ jsonrpc: JSONRPC_VERSION,
+ method,
+ params,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Type Guards
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a value is a well-formed JSON-RPC 2.0 request.
+ *
+ * A request has `jsonrpc: "2.0"`, a string `method`, and an `id`.
+ */
+export function isJsonRpcRequest(value: unknown): value is JsonRpcRequest {
+ if (typeof value !== "object" || value === null) return false;
+ const obj = value as Record<string, unknown>;
+ return (
+ obj.jsonrpc === JSONRPC_VERSION &&
+ typeof obj.method === "string" &&
+ "id" in obj &&
+ obj.id !== undefined &&
+ obj.id !== null
+ );
+}
+
+/**
+ * Check whether a value is a well-formed JSON-RPC 2.0 notification.
+ *
+ * A notification has `jsonrpc: "2.0"`, a string `method`, but no `id`.
+ */
+export function isJsonRpcNotification(
+ value: unknown,
+): value is JsonRpcNotification {
+ if (typeof value !== "object" || value === null) return false;
+ const obj = value as Record<string, unknown>;
+ return (
+ obj.jsonrpc === JSONRPC_VERSION &&
+ typeof obj.method === "string" &&
+ !("id" in obj)
+ );
+}
+
+/**
+ * Check whether a value is a well-formed JSON-RPC 2.0 response (success or error).
+ */
+export function isJsonRpcResponse(value: unknown): value is JsonRpcResponse {
+ if (typeof value !== "object" || value === null) return false;
+ const obj = value as Record<string, unknown>;
+ return (
+ obj.jsonrpc === JSONRPC_VERSION &&
+ "id" in obj &&
+ ("result" in obj || "error" in obj)
+ );
+}
+
+/**
+ * Check whether a JSON-RPC response is a success response.
+ */
+export function isJsonRpcSuccessResponse(
+ response: JsonRpcResponse,
+): response is JsonRpcSuccessResponse {
+ return "result" in response && !("error" in response && response.error !== undefined);
+}
+
+/**
+ * Check whether a JSON-RPC response is an error response.
+ */
+export function isJsonRpcErrorResponse(
+ response: JsonRpcResponse,
+): response is JsonRpcErrorResponse {
+ return "error" in response && response.error !== undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Serialization Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Line delimiter for JSON-RPC messages over stdio.
+ *
+ * Each message is a single line of JSON terminated by a newline character.
+ * This follows the newline-delimited JSON (NDJSON) convention.
+ */
+export const MESSAGE_DELIMITER = "\n" as const;
+
+/**
+ * Serialize a JSON-RPC message to a newline-delimited string for transmission
+ * over stdio.
+ *
+ * @param message - Any JSON-RPC message (request, response, or notification)
+ * @returns The JSON string terminated with a newline
+ */
+export function serializeMessage(message: JsonRpcMessage): string {
+ return JSON.stringify(message) + MESSAGE_DELIMITER;
+}
+
+/**
+ * Parse a JSON string into a JSON-RPC message.
+ *
+ * Returns the parsed message or throws a `JsonRpcParseError` if the input
+ * is not valid JSON or does not conform to the JSON-RPC 2.0 structure.
+ *
+ * @param line - A single line of JSON text (with or without trailing newline)
+ * @returns The parsed JSON-RPC message
+ * @throws {JsonRpcParseError} If parsing fails
+ */
+export function parseMessage(line: string): JsonRpcMessage {
+ const trimmed = line.trim();
+ if (trimmed.length === 0) {
+ throw new JsonRpcParseError("Empty message");
+ }
+
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(trimmed);
+ } catch {
+ throw new JsonRpcParseError(`Invalid JSON: ${trimmed.slice(0, 200)}`);
+ }
+
+ if (typeof parsed !== "object" || parsed === null) {
+ throw new JsonRpcParseError("Message must be a JSON object");
+ }
+
+ const obj = parsed as Record<string, unknown>;
+
+ if (obj.jsonrpc !== JSONRPC_VERSION) {
+ throw new JsonRpcParseError(
+ `Invalid or missing jsonrpc version (expected "${JSONRPC_VERSION}", got ${JSON.stringify(obj.jsonrpc)})`,
+ );
+ }
+
+ // It's a valid JSON-RPC 2.0 envelope — return as-is and let the caller
+ // use the type guards for more specific classification.
+ return parsed as JsonRpcMessage;
+}
+
+// ---------------------------------------------------------------------------
+// Error Classes
+// ---------------------------------------------------------------------------
+
+/**
+ * Error thrown when a JSON-RPC message cannot be parsed.
+ */
+export class JsonRpcParseError extends Error {
+ override readonly name = "JsonRpcParseError";
+ constructor(message: string) {
+ super(message);
+ }
+}
+
+/**
+ * Error thrown when a JSON-RPC call fails with a structured error response.
+ *
+ * Captures the full `JsonRpcError` so callers can inspect the code and data.
+ */
+export class JsonRpcCallError extends Error {
+ override readonly name = "JsonRpcCallError";
+ /** The JSON-RPC error code. */
+ readonly code: number;
+ /** Optional structured error data from the response. */
+ readonly data: unknown;
+
+ constructor(error: JsonRpcError) {
+ super(error.message);
+ this.code = error.code;
+ this.data = error.data;
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Reset helper (testing only)
+// ---------------------------------------------------------------------------
+
+/**
+ * Reset the internal request ID counter. **For testing only.**
+ *
+ * @internal
+ */
+export function _resetIdCounter(): void {
+ _nextId = 1;
+}
diff --git a/packages/plugins/sdk/src/testing.ts b/packages/plugins/sdk/src/testing.ts
new file mode 100644
index 0000000000..ee8a38cefd
--- /dev/null
+++ b/packages/plugins/sdk/src/testing.ts
@@ -0,0 +1,720 @@
+import { randomUUID } from "node:crypto";
+import type {
+ PaperclipPluginManifestV1,
+ PluginCapability,
+ PluginEventType,
+ Company,
+ Project,
+ Issue,
+ IssueComment,
+ Agent,
+ Goal,
+} from "@paperclipai/shared";
+import type {
+ EventFilter,
+ PluginContext,
+ PluginEntityRecord,
+ PluginEntityUpsert,
+ PluginJobContext,
+ PluginLauncherRegistration,
+ PluginEvent,
+ ScopeKey,
+ ToolResult,
+ ToolRunContext,
+ PluginWorkspace,
+ AgentSession,
+ AgentSessionEvent,
+} from "./types.js";
+
+export interface TestHarnessOptions {
+ /** Plugin manifest used to seed capability checks and metadata. */
+ manifest: PaperclipPluginManifestV1;
+ /** Optional capability override. Defaults to `manifest.capabilities`. */
+ capabilities?: PluginCapability[];
+ /** Initial config returned by `ctx.config.get()`. */
+ config?: Record<string, unknown>;
+}
+
+export interface TestHarnessLogEntry {
+ level: "info" | "warn" | "error" | "debug";
+ message: string;
+ meta?: Record<string, unknown>;
+}
+
+export interface TestHarness {
+ /** Fully-typed in-memory plugin context passed to `plugin.setup(ctx)`. */
+ ctx: PluginContext;
+ /** Seed host entities for `ctx.companies/projects/issues/agents/goals` reads. */
+ seed(input: {
+ companies?: Company[];
+ projects?: Project[];
+ issues?: Issue[];
+ issueComments?: IssueComment[];
+ agents?: Agent[];
+ goals?: Goal[];
+ }): void;
+ setConfig(config: Record<string, unknown>): void;
+ /** Dispatch a host or plugin event to registered handlers. */
+ emit(eventType: PluginEventType | `plugin.${string}`, payload: unknown, base?: Partial<PluginEvent>): Promise<void>;
+ /** Execute a previously-registered scheduled job handler. */
+ runJob(jobKey: string, partial?: Partial<PluginJobContext>): Promise<void>;
+ /** Invoke a `ctx.data.register(...)` handler by key. */
+ getData<T = unknown>(key: string, params?: Record<string, unknown>): Promise<T>;
+ /** Invoke a `ctx.actions.register(...)` handler by key. */
+ performAction<T = unknown>(key: string, params?: Record<string, unknown>): Promise<T>;
+ /** Execute a registered tool handler via `ctx.tools.execute(...)`. */
+ executeTool<T = ToolResult>(name: string, params: unknown, runCtx?: Partial<ToolRunContext>): Promise<T>;
+ /** Read raw in-memory state for assertions. */
+ getState(input: ScopeKey): unknown;
+ /** Simulate a streaming event arriving for an active session. */
+ simulateSessionEvent(sessionId: string, event: Omit<AgentSessionEvent, "sessionId">): void;
+ logs: TestHarnessLogEntry[];
+ activity: Array<{ message: string; entityType?: string; entityId?: string; metadata?: Record<string, unknown> }>;
+ metrics: Array<{ name: string; value: number; tags?: Record<string, string> }>;
+}
+
+type EventRegistration = {
+ name: PluginEventType | `plugin.${string}`;
+ filter?: EventFilter;
+ fn: (event: PluginEvent) => Promise<void>;
+};
+
+function normalizeScope(input: ScopeKey): Required<Pick<ScopeKey, "scopeKind" | "stateKey">> & Pick<ScopeKey, "scopeId" | "namespace"> {
+ return {
+ scopeKind: input.scopeKind,
+ scopeId: input.scopeId,
+ namespace: input.namespace ?? "default",
+ stateKey: input.stateKey,
+ };
+}
+
+function stateMapKey(input: ScopeKey): string {
+ const normalized = normalizeScope(input);
+ return `${normalized.scopeKind}|${normalized.scopeId ?? ""}|${normalized.namespace}|${normalized.stateKey}`;
+}
+
+function allowsEvent(filter: EventFilter | undefined, event: PluginEvent): boolean {
+ if (!filter) return true;
+ if (filter.companyId && filter.companyId !== String((event.payload as Record<string, unknown> | undefined)?.companyId ?? "")) return false;
+ if (filter.projectId && filter.projectId !== String((event.payload as Record<string, unknown> | undefined)?.projectId ?? "")) return false;
+ if (filter.agentId && filter.agentId !== String((event.payload as Record<string, unknown> | undefined)?.agentId ?? "")) return false;
+ return true;
+}
+
+function requireCapability(manifest: PaperclipPluginManifestV1, allowed: Set<PluginCapability>, capability: PluginCapability) {
+ if (allowed.has(capability)) return;
+ throw new Error(`Plugin '${manifest.id}' is missing required capability '${capability}' in test harness`);
+}
+
+function requireCompanyId(companyId?: string): string {
+ if (!companyId) throw new Error("companyId is required for this operation");
+ return companyId;
+}
+
+function isInCompany<T extends { companyId: string | null | undefined }>(
+ record: T | null | undefined,
+ companyId: string,
+): record is T {
+ return Boolean(record && record.companyId === companyId);
+}
+
+/**
+ * Create an in-memory host harness for plugin worker tests.
+ *
+ * The harness enforces declared capabilities and simulates host APIs, so tests
+ * can validate plugin behavior without spinning up the Paperclip server runtime.
+ */
+export function createTestHarness(options: TestHarnessOptions): TestHarness {
+ const manifest = options.manifest;
+ const capabilitySet = new Set(options.capabilities ?? manifest.capabilities);
+ let currentConfig = { ...(options.config ?? {}) };
+
+ const logs: TestHarnessLogEntry[] = [];
+ const activity: TestHarness["activity"] = [];
+ const metrics: TestHarness["metrics"] = [];
+
+ const state = new Map<string, unknown>();
+ const entities = new Map<string, PluginEntityRecord>();
+ const entityExternalIndex = new Map<string, string>();
+ const assets = new Map<string, { contentType: string; data: Uint8Array }>();
+
+ const companies = new Map<string, Company>();
+ const projects = new Map<string, Project>();
+ const issues = new Map<string, Issue>();
+ const issueComments = new Map<string, IssueComment[]>();
+ const agents = new Map<string, Agent>();
+ const goals = new Map<string, Goal>();
+ const projectWorkspaces = new Map<string, PluginWorkspace[]>();
+
+ const sessions = new Map<string, AgentSession>();
+ const sessionEventCallbacks = new Map<string, (event: AgentSessionEvent) => void>();
+
+ const events: EventRegistration[] = [];
+ const jobs = new Map<string, (job: PluginJobContext) => Promise<void>>();
+ const launchers = new Map<string, PluginLauncherRegistration>();
+ const dataHandlers = new Map<string, (params: Record<string, unknown>) => Promise<unknown>>();
+ const actionHandlers = new Map<string, (params: Record<string, unknown>) => Promise<unknown>>();
+ const toolHandlers = new Map<string, (params: unknown, runCtx: ToolRunContext) => Promise<ToolResult>>();
+
+ const ctx: PluginContext = {
+ manifest,
+ config: {
+ async get() {
+ return { ...currentConfig };
+ },
+ },
+ events: {
+ on(name: PluginEventType | `plugin.${string}`, filterOrFn: EventFilter | ((event: PluginEvent) => Promise<void>), maybeFn?: (event: PluginEvent) => Promise<void>): () => void {
+ requireCapability(manifest, capabilitySet, "events.subscribe");
+ let registration: EventRegistration;
+ if (typeof filterOrFn === "function") {
+ registration = { name, fn: filterOrFn };
+ } else {
+ if (!maybeFn) throw new Error("event handler is required");
+ registration = { name, filter: filterOrFn, fn: maybeFn };
+ }
+ events.push(registration);
+ return () => {
+ const idx = events.indexOf(registration);
+ if (idx !== -1) events.splice(idx, 1);
+ };
+ },
+ async emit(name, companyId, payload) {
+ requireCapability(manifest, capabilitySet, "events.emit");
+ await harness.emit(`plugin.${manifest.id}.${name}`, payload, { companyId });
+ },
+ },
+ jobs: {
+ register(key, fn) {
+ requireCapability(manifest, capabilitySet, "jobs.schedule");
+ jobs.set(key, fn);
+ },
+ },
+ launchers: {
+ register(launcher) {
+ launchers.set(launcher.id, launcher);
+ },
+ },
+ http: {
+ async fetch(url, init) {
+ requireCapability(manifest, capabilitySet, "http.outbound");
+ return fetch(url, init);
+ },
+ },
+ secrets: {
+ async resolve(secretRef) {
+ requireCapability(manifest, capabilitySet, "secrets.read-ref");
+ return `resolved:${secretRef}`;
+ },
+ },
+ assets: {
+ async upload(filename, contentType, data) {
+ requireCapability(manifest, capabilitySet, "assets.write");
+ const assetId = `asset_${randomUUID()}`;
+ assets.set(assetId, { contentType, data: data instanceof Uint8Array ? data : new Uint8Array(data) });
+ return { assetId, url: `memory://assets/${filename}` };
+ },
+ async getUrl(assetId) {
+ requireCapability(manifest, capabilitySet, "assets.read");
+ if (!assets.has(assetId)) throw new Error(`Asset not found: ${assetId}`);
+ return `memory://assets/${assetId}`;
+ },
+ },
+ activity: {
+ async log(entry) {
+ requireCapability(manifest, capabilitySet, "activity.log.write");
+ activity.push(entry);
+ },
+ },
+ state: {
+ async get(input) {
+ requireCapability(manifest, capabilitySet, "plugin.state.read");
+ return state.has(stateMapKey(input)) ? state.get(stateMapKey(input)) : null;
+ },
+ async set(input, value) {
+ requireCapability(manifest, capabilitySet, "plugin.state.write");
+ state.set(stateMapKey(input), value);
+ },
+ async delete(input) {
+ requireCapability(manifest, capabilitySet, "plugin.state.write");
+ state.delete(stateMapKey(input));
+ },
+ },
+ entities: {
+ async upsert(input: PluginEntityUpsert) {
+ const externalKey = input.externalId
+ ? `${input.entityType}|${input.scopeKind}|${input.scopeId ?? ""}|${input.externalId}`
+ : null;
+ const existingId = externalKey ? entityExternalIndex.get(externalKey) : undefined;
+ const existing = existingId ? entities.get(existingId) : undefined;
+ const now = new Date().toISOString();
+ const previousExternalKey = existing?.externalId
+ ? `${existing.entityType}|${existing.scopeKind}|${existing.scopeId ?? ""}|${existing.externalId}`
+ : null;
+ const record: PluginEntityRecord = existing
+ ? {
+ ...existing,
+ entityType: input.entityType,
+ scopeKind: input.scopeKind,
+ scopeId: input.scopeId ?? null,
+ externalId: input.externalId ?? null,
+ title: input.title ?? null,
+ status: input.status ?? null,
+ data: input.data,
+ updatedAt: now,
+ }
+ : {
+ id: randomUUID(),
+ entityType: input.entityType,
+ scopeKind: input.scopeKind,
+ scopeId: input.scopeId ?? null,
+ externalId: input.externalId ?? null,
+ title: input.title ?? null,
+ status: input.status ?? null,
+ data: input.data,
+ createdAt: now,
+ updatedAt: now,
+ };
+ entities.set(record.id, record);
+ if (previousExternalKey && previousExternalKey !== externalKey) {
+ entityExternalIndex.delete(previousExternalKey);
+ }
+ if (externalKey) entityExternalIndex.set(externalKey, record.id);
+ return record;
+ },
+ async list(query) {
+ let out = [...entities.values()];
+ if (query.entityType) out = out.filter((r) => r.entityType === query.entityType);
+ if (query.scopeKind) out = out.filter((r) => r.scopeKind === query.scopeKind);
+ if (query.scopeId) out = out.filter((r) => r.scopeId === query.scopeId);
+ if (query.externalId) out = out.filter((r) => r.externalId === query.externalId);
+ if (query.offset) out = out.slice(query.offset);
+ if (query.limit) out = out.slice(0, query.limit);
+ return out;
+ },
+ },
+ projects: {
+ async list(input) {
+ requireCapability(manifest, capabilitySet, "projects.read");
+ const companyId = requireCompanyId(input?.companyId);
+ let out = [...projects.values()];
+ out = out.filter((project) => project.companyId === companyId);
+ if (input?.offset) out = out.slice(input.offset);
+ if (input?.limit) out = out.slice(0, input.limit);
+ return out;
+ },
+ async get(projectId, companyId) {
+ requireCapability(manifest, capabilitySet, "projects.read");
+ const project = projects.get(projectId);
+ return isInCompany(project, companyId) ? project : null;
+ },
+ async listWorkspaces(projectId, companyId) {
+ requireCapability(manifest, capabilitySet, "project.workspaces.read");
+ if (!isInCompany(projects.get(projectId), companyId)) return [];
+ return projectWorkspaces.get(projectId) ?? [];
+ },
+ async getPrimaryWorkspace(projectId, companyId) {
+ requireCapability(manifest, capabilitySet, "project.workspaces.read");
+ if (!isInCompany(projects.get(projectId), companyId)) return null;
+ const workspaces = projectWorkspaces.get(projectId) ?? [];
+ return workspaces.find((workspace) => workspace.isPrimary) ?? null;
+ },
+ async getWorkspaceForIssue(issueId, companyId) {
+ requireCapability(manifest, capabilitySet, "project.workspaces.read");
+ const issue = issues.get(issueId);
+ if (!isInCompany(issue, companyId)) return null;
+ const projectId = (issue as unknown as Record<string, unknown>)?.projectId as string | undefined;
+ if (!projectId) return null;
+ if (!isInCompany(projects.get(projectId), companyId)) return null;
+ const workspaces = projectWorkspaces.get(projectId) ?? [];
+ return workspaces.find((workspace) => workspace.isPrimary) ?? null;
+ },
+ },
+ companies: {
+ async list(input) {
+ requireCapability(manifest, capabilitySet, "companies.read");
+ let out = [...companies.values()];
+ if (input?.offset) out = out.slice(input.offset);
+ if (input?.limit) out = out.slice(0, input.limit);
+ return out;
+ },
+ async get(companyId) {
+ requireCapability(manifest, capabilitySet, "companies.read");
+ return companies.get(companyId) ?? null;
+ },
+ },
+ issues: {
+ async list(input) {
+ requireCapability(manifest, capabilitySet, "issues.read");
+ const companyId = requireCompanyId(input?.companyId);
+ let out = [...issues.values()];
+ out = out.filter((issue) => issue.companyId === companyId);
+ if (input?.projectId) out = out.filter((issue) => issue.projectId === input.projectId);
+ if (input?.assigneeAgentId) out = out.filter((issue) => issue.assigneeAgentId === input.assigneeAgentId);
+ if (input?.status) out = out.filter((issue) => issue.status === input.status);
+ if (input?.offset) out = out.slice(input.offset);
+ if (input?.limit) out = out.slice(0, input.limit);
+ return out;
+ },
+ async get(issueId, companyId) {
+ requireCapability(manifest, capabilitySet, "issues.read");
+ const issue = issues.get(issueId);
+ return isInCompany(issue, companyId) ? issue : null;
+ },
+ async create(input) {
+ requireCapability(manifest, capabilitySet, "issues.create");
+ const now = new Date();
+ const record: Issue = {
+ id: randomUUID(),
+ companyId: input.companyId,
+ projectId: input.projectId ?? null,
+ goalId: input.goalId ?? null,
+ parentId: input.parentId ?? null,
+ title: input.title,
+ description: input.description ?? null,
+ status: "todo",
+ priority: input.priority ?? "medium",
+ assigneeAgentId: input.assigneeAgentId ?? null,
+ assigneeUserId: null,
+ checkoutRunId: null,
+ executionRunId: null,
+ executionAgentNameKey: null,
+ executionLockedAt: null,
+ createdByAgentId: null,
+ createdByUserId: null,
+ issueNumber: null,
+ identifier: null,
+ requestDepth: 0,
+ billingCode: null,
+ assigneeAdapterOverrides: null,
+ executionWorkspaceSettings: null,
+ startedAt: null,
+ completedAt: null,
+ cancelledAt: null,
+ hiddenAt: null,
+ createdAt: now,
+ updatedAt: now,
+ };
+ issues.set(record.id, record);
+ return record;
+ },
+ async update(issueId, patch, companyId) {
+ requireCapability(manifest, capabilitySet, "issues.update");
+ const record = issues.get(issueId);
+ if (!isInCompany(record, companyId)) throw new Error(`Issue not found: ${issueId}`);
+ const updated: Issue = {
+ ...record,
+ ...patch,
+ updatedAt: new Date(),
+ };
+ issues.set(issueId, updated);
+ return updated;
+ },
+ async listComments(issueId, companyId) {
+ requireCapability(manifest, capabilitySet, "issue.comments.read");
+ if (!isInCompany(issues.get(issueId), companyId)) return [];
+ return issueComments.get(issueId) ?? [];
+ },
+ async createComment(issueId, body, companyId) {
+ requireCapability(manifest, capabilitySet, "issue.comments.create");
+ const parentIssue = issues.get(issueId);
+ if (!isInCompany(parentIssue, companyId)) {
+ throw new Error(`Issue not found: ${issueId}`);
+ }
+ const now = new Date();
+ const comment: IssueComment = {
+ id: randomUUID(),
+ companyId: parentIssue.companyId,
+ issueId,
+ authorAgentId: null,
+ authorUserId: null,
+ body,
+ createdAt: now,
+ updatedAt: now,
+ };
+ const current = issueComments.get(issueId) ?? [];
+ current.push(comment);
+ issueComments.set(issueId, current);
+ return comment;
+ },
+ },
+ agents: {
+ async list(input) {
+ requireCapability(manifest, capabilitySet, "agents.read");
+ const companyId = requireCompanyId(input?.companyId);
+ let out = [...agents.values()];
+ out = out.filter((agent) => agent.companyId === companyId);
+ if (input?.status) out = out.filter((agent) => agent.status === input.status);
+ if (input?.offset) out = out.slice(input.offset);
+ if (input?.limit) out = out.slice(0, input.limit);
+ return out;
+ },
+ async get(agentId, companyId) {
+ requireCapability(manifest, capabilitySet, "agents.read");
+ const agent = agents.get(agentId);
+ return isInCompany(agent, companyId) ? agent : null;
+ },
+ async pause(agentId, companyId) {
+ requireCapability(manifest, capabilitySet, "agents.pause");
+ const cid = requireCompanyId(companyId);
+ const agent = agents.get(agentId);
+ if (!isInCompany(agent, cid)) throw new Error(`Agent not found: ${agentId}`);
+ if (agent!.status === "terminated") throw new Error("Cannot pause terminated agent");
+ const updated: Agent = { ...agent!, status: "paused", updatedAt: new Date() };
+ agents.set(agentId, updated);
+ return updated;
+ },
+ async resume(agentId, companyId) {
+ requireCapability(manifest, capabilitySet, "agents.resume");
+ const cid = requireCompanyId(companyId);
+ const agent = agents.get(agentId);
+ if (!isInCompany(agent, cid)) throw new Error(`Agent not found: ${agentId}`);
+ if (agent!.status === "terminated") throw new Error("Cannot resume terminated agent");
+ if (agent!.status === "pending_approval") throw new Error("Pending approval agents cannot be resumed");
+ const updated: Agent = { ...agent!, status: "idle", updatedAt: new Date() };
+ agents.set(agentId, updated);
+ return updated;
+ },
+ async invoke(agentId, companyId, opts) {
+ requireCapability(manifest, capabilitySet, "agents.invoke");
+ const cid = requireCompanyId(companyId);
+ const agent = agents.get(agentId);
+ if (!isInCompany(agent, cid)) throw new Error(`Agent not found: ${agentId}`);
+ if (
+ agent!.status === "paused" ||
+ agent!.status === "terminated" ||
+ agent!.status === "pending_approval"
+ ) {
+ throw new Error(`Agent is not invokable in its current state: ${agent!.status}`);
+ }
+ return { runId: randomUUID() };
+ },
+ sessions: {
+ async create(agentId, companyId, opts) {
+ requireCapability(manifest, capabilitySet, "agent.sessions.create");
+ const cid = requireCompanyId(companyId);
+ const agent = agents.get(agentId);
+ if (!isInCompany(agent, cid)) throw new Error(`Agent not found: ${agentId}`);
+ const session: AgentSession = {
+ sessionId: randomUUID(),
+ agentId,
+ companyId: cid,
+ status: "active",
+ createdAt: new Date().toISOString(),
+ };
+ sessions.set(session.sessionId, session);
+ return session;
+ },
+ async list(agentId, companyId) {
+ requireCapability(manifest, capabilitySet, "agent.sessions.list");
+ const cid = requireCompanyId(companyId);
+ return [...sessions.values()].filter(
+ (s) => s.agentId === agentId && s.companyId === cid && s.status === "active",
+ );
+ },
+ async sendMessage(sessionId, companyId, opts) {
+ requireCapability(manifest, capabilitySet, "agent.sessions.send");
+ const session = sessions.get(sessionId);
+ if (!session || session.status !== "active") throw new Error(`Session not found or closed: ${sessionId}`);
+ if (session.companyId !== companyId) throw new Error(`Session not found: ${sessionId}`);
+ if (opts.onEvent) {
+ sessionEventCallbacks.set(sessionId, opts.onEvent);
+ }
+ return { runId: randomUUID() };
+ },
+ async close(sessionId, companyId) {
+ requireCapability(manifest, capabilitySet, "agent.sessions.close");
+ const session = sessions.get(sessionId);
+ if (!session) throw new Error(`Session not found: ${sessionId}`);
+ if (session.companyId !== companyId) throw new Error(`Session not found: ${sessionId}`);
+ session.status = "closed";
+ sessionEventCallbacks.delete(sessionId);
+ },
+ },
+ },
+ goals: {
+ async list(input) {
+ requireCapability(manifest, capabilitySet, "goals.read");
+ const companyId = requireCompanyId(input?.companyId);
+ let out = [...goals.values()];
+ out = out.filter((goal) => goal.companyId === companyId);
+ if (input?.level) out = out.filter((goal) => goal.level === input.level);
+ if (input?.status) out = out.filter((goal) => goal.status === input.status);
+ if (input?.offset) out = out.slice(input.offset);
+ if (input?.limit) out = out.slice(0, input.limit);
+ return out;
+ },
+ async get(goalId, companyId) {
+ requireCapability(manifest, capabilitySet, "goals.read");
+ const goal = goals.get(goalId);
+ return isInCompany(goal, companyId) ? goal : null;
+ },
+ async create(input) {
+ requireCapability(manifest, capabilitySet, "goals.create");
+ const now = new Date();
+ const record: Goal = {
+ id: randomUUID(),
+ companyId: input.companyId,
+ title: input.title,
+ description: input.description ?? null,
+ level: input.level ?? "task",
+ status: input.status ?? "planned",
+ parentId: input.parentId ?? null,
+ ownerAgentId: input.ownerAgentId ?? null,
+ createdAt: now,
+ updatedAt: now,
+ };
+ goals.set(record.id, record);
+ return record;
+ },
+ async update(goalId, patch, companyId) {
+ requireCapability(manifest, capabilitySet, "goals.update");
+ const record = goals.get(goalId);
+ if (!isInCompany(record, companyId)) throw new Error(`Goal not found: ${goalId}`);
+ const updated: Goal = {
+ ...record,
+ ...patch,
+ updatedAt: new Date(),
+ };
+ goals.set(goalId, updated);
+ return updated;
+ },
+ },
+ data: {
+ register(key, handler) {
+ dataHandlers.set(key, handler);
+ },
+ },
+ actions: {
+ register(key, handler) {
+ actionHandlers.set(key, handler);
+ },
+ },
+ streams: (() => {
+ const channelCompanyMap = new Map<string, string>();
+ return {
+ open(channel: string, companyId: string) {
+ channelCompanyMap.set(channel, companyId);
+ },
+ emit(_channel: string, _event: unknown) {
+ // No-op in test harness — events are not forwarded
+ },
+ close(channel: string) {
+ channelCompanyMap.delete(channel);
+ },
+ };
+ })(),
+ tools: {
+ register(name, _decl, fn) {
+ requireCapability(manifest, capabilitySet, "agent.tools.register");
+ toolHandlers.set(name, fn);
+ },
+ },
+ metrics: {
+ async write(name, value, tags) {
+ requireCapability(manifest, capabilitySet, "metrics.write");
+ metrics.push({ name, value, tags });
+ },
+ },
+ logger: {
+ info(message, meta) {
+ logs.push({ level: "info", message, meta });
+ },
+ warn(message, meta) {
+ logs.push({ level: "warn", message, meta });
+ },
+ error(message, meta) {
+ logs.push({ level: "error", message, meta });
+ },
+ debug(message, meta) {
+ logs.push({ level: "debug", message, meta });
+ },
+ },
+ };
+
+ const harness: TestHarness = {
+ ctx,
+ seed(input) {
+ for (const row of input.companies ?? []) companies.set(row.id, row);
+ for (const row of input.projects ?? []) projects.set(row.id, row);
+ for (const row of input.issues ?? []) issues.set(row.id, row);
+ for (const row of input.issueComments ?? []) {
+ const list = issueComments.get(row.issueId) ?? [];
+ list.push(row);
+ issueComments.set(row.issueId, list);
+ }
+ for (const row of input.agents ?? []) agents.set(row.id, row);
+ for (const row of input.goals ?? []) goals.set(row.id, row);
+ },
+ setConfig(config) {
+ currentConfig = { ...config };
+ },
+ async emit(eventType, payload, base) {
+ const event: PluginEvent = {
+ eventId: base?.eventId ?? randomUUID(),
+ eventType,
+ companyId: base?.companyId ?? "test-company",
+ occurredAt: base?.occurredAt ?? new Date().toISOString(),
+ actorId: base?.actorId,
+ actorType: base?.actorType,
+ entityId: base?.entityId,
+ entityType: base?.entityType,
+ payload,
+ };
+
+ for (const handler of events) {
+ const exactMatch = handler.name === event.eventType;
+ const wildcardPluginAll = handler.name === "plugin.*" && String(event.eventType).startsWith("plugin.");
+ const wildcardPluginOne = String(handler.name).endsWith(".*")
+ && String(event.eventType).startsWith(String(handler.name).slice(0, -1));
+ if (!exactMatch && !wildcardPluginAll && !wildcardPluginOne) continue;
+ if (!allowsEvent(handler.filter, event)) continue;
+ await handler.fn(event);
+ }
+ },
+ async runJob(jobKey, partial = {}) {
+ const handler = jobs.get(jobKey);
+ if (!handler) throw new Error(`No job handler registered for '${jobKey}'`);
+ await handler({
+ jobKey,
+ runId: partial.runId ?? randomUUID(),
+ trigger: partial.trigger ?? "manual",
+ scheduledAt: partial.scheduledAt ?? new Date().toISOString(),
+ });
+ },
+ async getData<T = unknown>(key: string, params: Record<string, unknown> = {}) {
+ const handler = dataHandlers.get(key);
+ if (!handler) throw new Error(`No data handler registered for '${key}'`);
+ return await handler(params) as T;
+ },
+ async performAction<T = unknown>(key: string, params: Record<string, unknown> = {}) {
+ const handler = actionHandlers.get(key);
+ if (!handler) throw new Error(`No action handler registered for '${key}'`);
+ return await handler(params) as T;
+ },
+ async executeTool<T = ToolResult>(name: string, params: unknown, runCtx: Partial<ToolRunContext> = {}) {
+ const handler = toolHandlers.get(name);
+ if (!handler) throw new Error(`No tool handler registered for '${name}'`);
+ const ctxToPass: ToolRunContext = {
+ agentId: runCtx.agentId ?? "agent-test",
+ runId: runCtx.runId ?? randomUUID(),
+ companyId: runCtx.companyId ?? "company-test",
+ projectId: runCtx.projectId ?? "project-test",
+ };
+ return await handler(params, ctxToPass) as T;
+ },
+ getState(input) {
+ return state.get(stateMapKey(input));
+ },
+ simulateSessionEvent(sessionId, event) {
+ const cb = sessionEventCallbacks.get(sessionId);
+ if (!cb) throw new Error(`No active session event callback for session: ${sessionId}`);
+ cb({ ...event, sessionId });
+ },
+ logs,
+ activity,
+ metrics,
+ };
+
+ return harness;
+}
diff --git a/packages/plugins/sdk/src/types.ts b/packages/plugins/sdk/src/types.ts
new file mode 100644
index 0000000000..82940c7fef
--- /dev/null
+++ b/packages/plugins/sdk/src/types.ts
@@ -0,0 +1,1116 @@
+/**
+ * Core types for the Paperclip plugin worker-side SDK.
+ *
+ * These types define the stable public API surface that plugin workers import
+ * from `@paperclipai/plugin-sdk`. The host provides a concrete implementation
+ * of `PluginContext` to the plugin at initialisation time.
+ *
+ * @see PLUGIN_SPEC.md §14 — SDK Surface
+ * @see PLUGIN_SPEC.md §29.2 — SDK Versioning
+ */
+
+import type {
+ PaperclipPluginManifestV1,
+ PluginStateScopeKind,
+ PluginEventType,
+ PluginToolDeclaration,
+ PluginLauncherDeclaration,
+ Company,
+ Project,
+ Issue,
+ IssueComment,
+ Agent,
+ Goal,
+} from "@paperclipai/shared";
+
+// ---------------------------------------------------------------------------
+// Re-exports from @paperclipai/shared (plugin authors import from one place)
+// ---------------------------------------------------------------------------
+
+export type {
+ PaperclipPluginManifestV1,
+ PluginJobDeclaration,
+ PluginWebhookDeclaration,
+ PluginToolDeclaration,
+ PluginUiSlotDeclaration,
+ PluginUiDeclaration,
+ PluginLauncherActionDeclaration,
+ PluginLauncherRenderDeclaration,
+ PluginLauncherDeclaration,
+ PluginMinimumHostVersion,
+ PluginRecord,
+ PluginConfig,
+ JsonSchema,
+ PluginStatus,
+ PluginCategory,
+ PluginCapability,
+ PluginUiSlotType,
+ PluginUiSlotEntityType,
+ PluginLauncherPlacementZone,
+ PluginLauncherAction,
+ PluginLauncherBounds,
+ PluginLauncherRenderEnvironment,
+ PluginStateScopeKind,
+ PluginJobStatus,
+ PluginJobRunStatus,
+ PluginJobRunTrigger,
+ PluginWebhookDeliveryStatus,
+ PluginEventType,
+ PluginBridgeErrorCode,
+ Company,
+ Project,
+ Issue,
+ IssueComment,
+ Agent,
+ Goal,
+} from "@paperclipai/shared";
+
+// ---------------------------------------------------------------------------
+// Scope key — identifies where plugin state is stored
+// ---------------------------------------------------------------------------
+
+/**
+ * A scope key identifies the exact location where plugin state is stored.
+ * Scope is partitioned by `scopeKind` and optional `scopeId`.
+ *
+ * Examples:
+ * - `{ scopeKind: "instance" }` — single global value for the whole instance
+ * - `{ scopeKind: "project", scopeId: "proj-uuid" }` — per-project state
+ * - `{ scopeKind: "issue", scopeId: "iss-uuid" }` — per-issue state
+ *
+ * @see PLUGIN_SPEC.md §21.3 `plugin_state`
+ */
+export interface ScopeKey {
+ /** What kind of Paperclip object this state is scoped to. */
+ scopeKind: PluginStateScopeKind;
+ /** UUID or text identifier for the scoped object. Omit for `instance` scope. */
+ scopeId?: string;
+ /** Optional sub-namespace within the scope to avoid key collisions. Defaults to `"default"`. */
+ namespace?: string;
+ /** The state key within the namespace. */
+ stateKey: string;
+}
+
+// ---------------------------------------------------------------------------
+// Event types
+// ---------------------------------------------------------------------------
+
+/**
+ * Optional filter applied when subscribing to an event. The host evaluates
+ * the filter server-side so filtered-out events never cross the process boundary.
+ *
+ * All filter fields are optional. If omitted the plugin receives every event
+ * of the subscribed type.
+ *
+ * @see PLUGIN_SPEC.md §16.1 — Event Filtering
+ */
+export interface EventFilter {
+ /** Only receive events for this project. */
+ projectId?: string;
+ /** Only receive events for this company. */
+ companyId?: string;
+ /** Only receive events for this agent. */
+ agentId?: string;
+ /** Additional arbitrary filter fields. */
+ [key: string]: unknown;
+}
+
+/**
+ * Envelope wrapping every domain event delivered to a plugin worker.
+ *
+ * @see PLUGIN_SPEC.md §16 — Event System
+ */
+export interface PluginEvent<TPayload = unknown> {
+ /** Unique event identifier (UUID). */
+ eventId: string;
+ /** The event type (e.g. `"issue.created"`). */
+ eventType: PluginEventType | `plugin.${string}`;
+ /** ISO 8601 timestamp when the event occurred. */
+ occurredAt: string;
+ /** ID of the actor that caused the event, if applicable. */
+ actorId?: string;
+ /** Type of actor: `"user"`, `"agent"`, `"system"`, or `"plugin"`. */
+ actorType?: "user" | "agent" | "system" | "plugin";
+ /** Primary entity involved in the event. */
+ entityId?: string;
+ /** Type of the primary entity. */
+ entityType?: string;
+ /** UUID of the company this event belongs to. */
+ companyId: string;
+ /** Typed event payload. */
+ payload: TPayload;
+}
+
+// ---------------------------------------------------------------------------
+// Job context
+// ---------------------------------------------------------------------------
+
+/**
+ * Context passed to a plugin job handler when the host triggers a scheduled run.
+ *
+ * @see PLUGIN_SPEC.md §13.6 — `runJob`
+ */
+export interface PluginJobContext {
+ /** Stable job key matching the declaration in the manifest. */
+ jobKey: string;
+ /** UUID for this specific job run instance. */
+ runId: string;
+ /** What triggered this run. */
+ trigger: "schedule" | "manual" | "retry";
+ /** ISO 8601 timestamp when the run was scheduled to start. */
+ scheduledAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Tool run context
+// ---------------------------------------------------------------------------
+
+/**
+ * Run context passed to a plugin tool handler when an agent invokes the tool.
+ *
+ * @see PLUGIN_SPEC.md §13.10 — `executeTool`
+ */
+export interface ToolRunContext {
+ /** UUID of the agent invoking the tool. */
+ agentId: string;
+ /** UUID of the current agent run. */
+ runId: string;
+ /** UUID of the company the run belongs to. */
+ companyId: string;
+ /** UUID of the project the run belongs to. */
+ projectId: string;
+}
+
+/**
+ * Result returned from a plugin tool handler.
+ *
+ * @see PLUGIN_SPEC.md §13.10 — `executeTool`
+ */
+export interface ToolResult {
+ /** String content returned to the agent. Required for success responses. */
+ content?: string;
+ /** Structured data returned alongside or instead of string content. */
+ data?: unknown;
+ /** If present, indicates the tool call failed. */
+ error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin entity store
+// ---------------------------------------------------------------------------
+
+/**
+ * Input for creating or updating a plugin-owned entity.
+ *
+ * @see PLUGIN_SPEC.md §21.3 `plugin_entities`
+ */
+export interface PluginEntityUpsert {
+ /** Plugin-defined entity type (e.g. `"linear-issue"`, `"github-pr"`). */
+ entityType: string;
+ /** Scope where this entity lives. */
+ scopeKind: PluginStateScopeKind;
+ /** Optional scope ID. */
+ scopeId?: string;
+ /** External identifier in the remote system (e.g. Linear issue ID). */
+ externalId?: string;
+ /** Human-readable title for display in the Paperclip UI. */
+ title?: string;
+ /** Optional status string. */
+ status?: string;
+ /** Full entity data blob. Must be JSON-serializable. */
+ data: Record<string, unknown>;
+}
+
+/**
+ * A plugin-owned entity record as returned by `ctx.entities.list()`.
+ *
+ * @see PLUGIN_SPEC.md §21.3 `plugin_entities`
+ */
+export interface PluginEntityRecord {
+ /** UUID primary key. */
+ id: string;
+ /** Plugin-defined entity type. */
+ entityType: string;
+ /** Scope kind. */
+ scopeKind: PluginStateScopeKind;
+ /** Scope ID, if any. */
+ scopeId: string | null;
+ /** External identifier, if any. */
+ externalId: string | null;
+ /** Human-readable title. */
+ title: string | null;
+ /** Status string. */
+ status: string | null;
+ /** Full entity data. */
+ data: Record<string, unknown>;
+ /** ISO 8601 creation timestamp. */
+ createdAt: string;
+ /** ISO 8601 last-updated timestamp. */
+ updatedAt: string;
+}
+
+/**
+ * Query parameters for `ctx.entities.list()`.
+ */
+export interface PluginEntityQuery {
+ /** Filter by entity type. */
+ entityType?: string;
+ /** Filter by scope kind. */
+ scopeKind?: PluginStateScopeKind;
+ /** Filter by scope ID. */
+ scopeId?: string;
+ /** Filter by external ID. */
+ externalId?: string;
+ /** Maximum number of results to return. */
+ limit?: number;
+ /** Number of results to skip (for pagination). */
+ offset?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Project workspace metadata (read-only via ctx.projects)
+// ---------------------------------------------------------------------------
+
+/**
+ * Workspace metadata provided by the host. Plugins use this to resolve local
+ * filesystem paths for file browsing, git, terminal, and process operations.
+ *
+ * @see PLUGIN_SPEC.md §7 — Project Workspaces
+ * @see PLUGIN_SPEC.md §20 — Local Tooling
+ */
+export interface PluginWorkspace {
+ /** UUID primary key. */
+ id: string;
+ /** UUID of the parent project. */
+ projectId: string;
+ /** Display name for this workspace. */
+ name: string;
+ /** Absolute filesystem path to the workspace directory. */
+ path: string;
+ /** Whether this is the project's primary workspace. */
+ isPrimary: boolean;
+ /** ISO 8601 creation timestamp. */
+ createdAt: string;
+ /** ISO 8601 last-updated timestamp. */
+ updatedAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Host API surfaces exposed via PluginContext
+// ---------------------------------------------------------------------------
+
+/**
+ * `ctx.config` — read resolved operator configuration for this plugin.
+ *
+ * Plugin workers receive the resolved config at initialisation. Use `get()`
+ * to access the current configuration at any time. The host calls
+ * `configChanged` on the worker when the operator updates config at runtime.
+ *
+ * @see PLUGIN_SPEC.md §13.3 — `validateConfig`
+ * @see PLUGIN_SPEC.md §13.4 — `configChanged`
+ */
+export interface PluginConfigClient {
+ /**
+ * Returns the resolved operator configuration for this plugin instance.
+ * Values are validated against the plugin's `instanceConfigSchema` by the
+ * host before being passed to the worker.
+ */
+ get(): Promise<Record<string, unknown>>;
+}
+
+/**
+ * `ctx.events` — subscribe to and emit Paperclip domain events.
+ *
+ * Requires `events.subscribe` capability for `on()`.
+ * Requires `events.emit` capability for `emit()`.
+ *
+ * @see PLUGIN_SPEC.md §16 — Event System
+ */
+export interface PluginEventsClient {
+ /**
+ * Subscribe to a core Paperclip domain event or a plugin-namespaced event.
+ *
+ * @param name - Event type, e.g. `"issue.created"` or `"plugin.@acme/linear.sync-done"`
+ * @param fn - Async event handler
+ */
+ on(name: PluginEventType | `plugin.${string}`, fn: (event: PluginEvent) => Promise<void>): () => void;
+
+ /**
+ * Subscribe to an event with an optional server-side filter.
+ *
+ * @param name - Event type
+ * @param filter - Server-side filter evaluated before dispatching to the worker
+ * @param fn - Async event handler
+ * @returns An unsubscribe function that removes the handler
+ */
+ on(name: PluginEventType | `plugin.${string}`, filter: EventFilter, fn: (event: PluginEvent) => Promise<void>): () => void;
+
+ /**
+ * Emit a plugin-namespaced event. Other plugins with `events.subscribe` can
+ * subscribe to it using `"plugin.<pluginId>.<eventName>"`.
+ *
+ * Requires the `events.emit` capability.
+ *
+ * Plugin-emitted events are automatically namespaced: if the plugin ID is
+ * `"acme.linear"` and the event name is `"sync-done"`, the full event type
+ * becomes `"plugin.acme.linear.sync-done"`.
+ *
+ * @see PLUGIN_SPEC.md §16.2 — Plugin-to-Plugin Events
+ *
+ * @param name - Bare event name (e.g. `"sync-done"`)
+ * @param companyId - UUID of the company this event belongs to
+ * @param payload - JSON-serializable event payload
+ */
+ emit(name: string, companyId: string, payload: unknown): Promise<void>;
+}
+
+/**
+ * `ctx.jobs` — register handlers for scheduled jobs declared in the manifest.
+ *
+ * Requires `jobs.schedule` capability.
+ *
+ * @see PLUGIN_SPEC.md §17 — Scheduled Jobs
+ */
+export interface PluginJobsClient {
+ /**
+ * Register a handler for a scheduled job.
+ *
+ * The `key` must match a `jobKey` declared in the plugin manifest.
+ * The host calls this handler according to the job's declared `schedule`.
+ *
+ * @param key - Job key matching the manifest declaration
+ * @param fn - Async job handler
+ */
+ register(key: string, fn: (job: PluginJobContext) => Promise<void>): void;
+}
+
+/**
+ * A runtime launcher registration uses the same declaration shape as a
+ * manifest launcher entry.
+ */
+export type PluginLauncherRegistration = PluginLauncherDeclaration;
+
+/**
+ * `ctx.launchers` — register launcher declarations at runtime.
+ */
+export interface PluginLaunchersClient {
+ /**
+ * Register launcher metadata for host discovery.
+ *
+ * If a launcher with the same id is registered more than once, the latest
+ * declaration replaces the previous one.
+ */
+ register(launcher: PluginLauncherRegistration): void;
+}
+
+/**
+ * `ctx.http` — make outbound HTTP requests.
+ *
+ * Requires `http.outbound` capability.
+ *
+ * @see PLUGIN_SPEC.md §15.1 — Capabilities: Runtime/Integration
+ */
+export interface PluginHttpClient {
+ /**
+ * Perform an outbound HTTP request.
+ *
+ * The host enforces `http.outbound` capability before allowing the call.
+ * Plugins may also use standard Node `fetch` or other libraries directly —
+ * this client exists for host-managed tracing and audit logging.
+ *
+ * @param url - Target URL
+ * @param init - Standard `RequestInit` options
+ * @returns The response
+ */
+ fetch(url: string, init?: RequestInit): Promise<Response>;
+}
+
+/**
+ * `ctx.secrets` — resolve secret references.
+ *
+ * Requires `secrets.read-ref` capability.
+ *
+ * Plugins store secret *references* in their config (e.g. a secret name).
+ * This client resolves the reference through the Paperclip secret provider
+ * system and returns the resolved value at execution time.
+ *
+ * @see PLUGIN_SPEC.md §22 — Secrets
+ */
+export interface PluginSecretsClient {
+ /**
+ * Resolve a secret reference to its current value.
+ *
+ * The reference is a string identifier pointing to a secret configured
+ * in the Paperclip secret provider (e.g. `"MY_API_KEY"`).
+ *
+ * Secret values are resolved at call time and must never be cached or
+ * written to logs, config, or other persistent storage.
+ *
+ * @param secretRef - The secret reference string from plugin config
+ * @returns The resolved secret value
+ */
+ resolve(secretRef: string): Promise<string>;
+}
+
+/**
+ * `ctx.assets` — read and write assets (files, images, etc.).
+ *
+ * `assets.read` capability required for `getUrl()`.
+ * `assets.write` capability required for `upload()`.
+ *
+ * @see PLUGIN_SPEC.md §15.1 — Capabilities: Data Write
+ */
+export interface PluginAssetsClient {
+ /**
+ * Upload an asset (e.g. a screenshot or generated file).
+ *
+ * @param filename - Name for the asset file
+ * @param contentType - MIME type
+ * @param data - Raw asset data as a Buffer or Uint8Array
+ * @returns The asset ID and public URL
+ */
+ upload(filename: string, contentType: string, data: Buffer | Uint8Array): Promise<{ assetId: string; url: string }>;
+
+ /**
+ * Get the public URL for an existing asset by ID.
+ *
+ * @param assetId - Asset identifier
+ * @returns The public URL
+ */
+ getUrl(assetId: string): Promise<string>;
+}
+
+/**
+ * Input for writing a plugin activity log entry.
+ *
+ * @see PLUGIN_SPEC.md §21.4 — Activity Log Changes
+ */
+export interface PluginActivityLogEntry {
+ /** UUID of the company this activity belongs to. Required for auditing. */
+ companyId: string;
+ /** Human-readable description of the activity. */
+ message: string;
+ /** Optional entity type this activity relates to. */
+ entityType?: string;
+ /** Optional entity ID this activity relates to. */
+ entityId?: string;
+ /** Optional additional metadata. */
+ metadata?: Record<string, unknown>;
+}
+
+/**
+ * `ctx.activity` — write plugin-originated activity log entries.
+ *
+ * Requires `activity.log.write` capability.
+ *
+ * @see PLUGIN_SPEC.md §21.4 — Activity Log Changes
+ */
+export interface PluginActivityClient {
+ /**
+ * Write an activity log entry attributed to this plugin.
+ *
+ * The host writes the entry with `actor_type = plugin` and
+ * `actor_id = <pluginId>`.
+ *
+ * @param entry - The activity log entry to write
+ */
+ log(entry: PluginActivityLogEntry): Promise<void>;
+}
+
+/**
+ * `ctx.state` — read and write plugin-scoped key-value state.
+ *
+ * Each plugin gets an isolated namespace: state written by plugin A can never
+ * be read or overwritten by plugin B. Within a plugin, state is partitioned by
+ * a five-part composite key: `(pluginId, scopeKind, scopeId, namespace, stateKey)`.
+ *
+ * **Scope kinds**
+ *
+ * | `scopeKind` | `scopeId` | Typical use |
+ * |-------------|-----------|-------------|
+ * | `"instance"` | omit | Global flags, last full-sync timestamps |
+ * | `"company"` | company UUID | Per-company sync cursors |
+ * | `"project"` | project UUID | Per-project settings, branch tracking |
+ * | `"project_workspace"` | workspace UUID | Per-workspace state |
+ * | `"agent"` | agent UUID | Per-agent memory |
+ * | `"issue"` | issue UUID | Idempotency keys, linked external IDs |
+ * | `"goal"` | goal UUID | Per-goal progress |
+ * | `"run"` | run UUID | Per-run checkpoints |
+ *
+ * **Namespaces**
+ *
+ * The optional `namespace` field (default: `"default"`) lets you group related
+ * keys within a scope without risking collisions between different logical
+ * subsystems inside the same plugin.
+ *
+ * **Security**
+ *
+ * Never store resolved secret values. Store only secret references and resolve
+ * them at call time via `ctx.secrets.resolve()`.
+ *
+ * @example
+ * ```ts
+ * // Instance-global flag
+ * await ctx.state.set({ scopeKind: "instance", stateKey: "schema-version" }, 2);
+ *
+ * // Idempotency key per issue
+ * const synced = await ctx.state.get({ scopeKind: "issue", scopeId: issueId, stateKey: "synced-to-linear" });
+ * if (!synced) {
+ * await syncToLinear(issueId);
+ * await ctx.state.set({ scopeKind: "issue", scopeId: issueId, stateKey: "synced-to-linear" }, true);
+ * }
+ *
+ * // Per-project, namespaced for two integrations
+ * await ctx.state.set({ scopeKind: "project", scopeId: projectId, namespace: "linear", stateKey: "cursor" }, cursor);
+ * await ctx.state.set({ scopeKind: "project", scopeId: projectId, namespace: "github", stateKey: "last-event" }, eventId);
+ * ```
+ *
+ * `plugin.state.read` capability required for `get()`.
+ * `plugin.state.write` capability required for `set()` and `delete()`.
+ *
+ * @see PLUGIN_SPEC.md §21.3 `plugin_state`
+ */
+export interface PluginStateClient {
+ /**
+ * Read a state value.
+ *
+ * Returns the stored JSON value as-is, or `null` if no entry has been set
+ * for this scope+key combination. Falsy values (`false`, `0`, `""`) are
+ * returned correctly and are not confused with "not set".
+ *
+ * @param input - Scope key identifying the entry to read
+ * @returns The stored JSON value, or `null` if no value has been set
+ */
+ get(input: ScopeKey): Promise<unknown>;
+
+ /**
+ * Write a state value. Creates the row if it does not exist; replaces it
+ * atomically (upsert) if it does. Safe to call concurrently.
+ *
+ * Any JSON-serializable value is accepted: objects, arrays, strings,
+ * numbers, booleans, and `null`.
+ *
+ * @param input - Scope key identifying the entry to write
+ * @param value - JSON-serializable value to store
+ */
+ set(input: ScopeKey, value: unknown): Promise<void>;
+
+ /**
+ * Delete a state value. No-ops silently if the entry does not exist
+ * (idempotent by design — safe to call without prior `get()`).
+ *
+ * @param input - Scope key identifying the entry to delete
+ */
+ delete(input: ScopeKey): Promise<void>;
+}
+
+/**
+ * `ctx.entities` — create and query plugin-owned entity records.
+ *
+ * @see PLUGIN_SPEC.md §21.3 `plugin_entities`
+ */
+export interface PluginEntitiesClient {
+ /**
+ * Create or update a plugin entity record (upsert by `externalId` within
+ * the given scope, or by `id` if provided).
+ *
+ * @param input - Entity data to upsert
+ */
+ upsert(input: PluginEntityUpsert): Promise<PluginEntityRecord>;
+
+ /**
+ * Query plugin entity records.
+ *
+ * @param query - Filter criteria
+ * @returns Matching entity records
+ */
+ list(query: PluginEntityQuery): Promise<PluginEntityRecord[]>;
+}
+
+/**
+ * `ctx.projects` — read project and workspace metadata.
+ *
+ * Requires `projects.read` capability.
+ * Requires `project.workspaces.read` capability for workspace operations.
+ *
+ * @see PLUGIN_SPEC.md §7 — Project Workspaces
+ */
+export interface PluginProjectsClient {
+ /**
+ * List projects visible to the plugin.
+ *
+ * Requires the `projects.read` capability.
+ */
+ list(input: { companyId: string; limit?: number; offset?: number }): Promise<Project[]>;
+
+ /**
+ * Get a single project by ID.
+ *
+ * Requires the `projects.read` capability.
+ */
+ get(projectId: string, companyId: string): Promise<Project | null>;
+
+ /**
+ * List all workspaces attached to a project.
+ *
+ * @param projectId - UUID of the project
+ * @param companyId - UUID of the company that owns the project
+ * @returns All workspaces for the project, ordered with primary first
+ */
+ listWorkspaces(projectId: string, companyId: string): Promise<PluginWorkspace[]>;
+
+ /**
+ * Get the primary workspace for a project.
+ *
+ * @param projectId - UUID of the project
+ * @param companyId - UUID of the company that owns the project
+ * @returns The primary workspace, or `null` if no workspace is configured
+ */
+ getPrimaryWorkspace(projectId: string, companyId: string): Promise<PluginWorkspace | null>;
+
+ /**
+ * Resolve the primary workspace for an issue by looking up the issue's
+ * project and returning its primary workspace.
+ *
+ * This is a convenience method that combines `issues.get()` and
+ * `getPrimaryWorkspace()` in a single RPC call.
+ *
+ * @param issueId - UUID of the issue
+ * @param companyId - UUID of the company that owns the issue
+ * @returns The primary workspace for the issue's project, or `null` if
+ * the issue has no project or the project has no workspace
+ *
+ * @see PLUGIN_SPEC.md §20 — Local Tooling
+ */
+ getWorkspaceForIssue(issueId: string, companyId: string): Promise<PluginWorkspace | null>;
+}
+
+/**
+ * `ctx.data` — register `getData` handlers that back `usePluginData()` in the
+ * plugin's frontend components.
+ *
+ * The plugin's UI calls `usePluginData(key, params)` which routes through the
+ * host bridge to the worker's registered handler.
+ *
+ * @see PLUGIN_SPEC.md §13.8 — `getData`
+ */
+export interface PluginDataClient {
+ /**
+ * Register a handler for a plugin-defined data key.
+ *
+ * @param key - Stable string identifier for this data type (e.g. `"sync-health"`)
+ * @param handler - Async function that receives request params and returns JSON-serializable data
+ */
+ register(key: string, handler: (params: Record<string, unknown>) => Promise<unknown>): void;
+}
+
+/**
+ * `ctx.actions` — register `performAction` handlers that back
+ * `usePluginAction()` in the plugin's frontend components.
+ *
+ * @see PLUGIN_SPEC.md §13.9 — `performAction`
+ */
+export interface PluginActionsClient {
+ /**
+ * Register a handler for a plugin-defined action key.
+ *
+ * @param key - Stable string identifier for this action (e.g. `"resync"`)
+ * @param handler - Async function that receives action params and returns a result
+ */
+ register(key: string, handler: (params: Record<string, unknown>) => Promise<unknown>): void;
+}
+
+/**
+ * `ctx.tools` — register handlers for agent tools declared in the manifest.
+ *
+ * Requires `agent.tools.register` capability.
+ *
+ * Tool names are automatically namespaced by plugin ID at runtime.
+ *
+ * @see PLUGIN_SPEC.md §11 — Agent Tools
+ */
+export interface PluginToolsClient {
+ /**
+ * Register a handler for a plugin-contributed agent tool.
+ *
+ * @param name - Tool name matching the manifest declaration (without namespace prefix)
+ * @param declaration - Tool metadata (displayName, description, parametersSchema)
+ * @param fn - Async handler that executes the tool
+ */
+ register(
+ name: string,
+ declaration: Pick<PluginToolDeclaration, "displayName" | "description" | "parametersSchema">,
+ fn: (params: unknown, runCtx: ToolRunContext) => Promise<ToolResult>,
+ ): void;
+}
+
+/**
+ * `ctx.logger` — structured logging from the plugin worker.
+ *
+ * Log output is captured by the host, stored, and surfaced in the plugin
+ * health dashboard.
+ *
+ * @see PLUGIN_SPEC.md §26.1 — Logging
+ */
+export interface PluginLogger {
+ /** Log an informational message. */
+ info(message: string, meta?: Record<string, unknown>): void;
+ /** Log a warning. */
+ warn(message: string, meta?: Record<string, unknown>): void;
+ /** Log an error. */
+ error(message: string, meta?: Record<string, unknown>): void;
+ /** Log a debug message (may be suppressed in production). */
+ debug(message: string, meta?: Record<string, unknown>): void;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin metrics
+// ---------------------------------------------------------------------------
+
+/**
+ * `ctx.metrics` — write plugin-contributed metrics.
+ *
+ * Requires `metrics.write` capability.
+ *
+ * @see PLUGIN_SPEC.md §15.1 — Capabilities: Data Write
+ */
+export interface PluginMetricsClient {
+ /**
+ * Write a numeric metric data point.
+ *
+ * @param name - Metric name (plugin-namespaced by the host)
+ * @param value - Numeric value
+ * @param tags - Optional key-value tags for filtering
+ */
+ write(name: string, value: number, tags?: Record<string, string>): Promise<void>;
+}
+
+/**
+ * `ctx.companies` — read company metadata.
+ *
+ * Requires `companies.read` capability.
+ */
+export interface PluginCompaniesClient {
+ /**
+ * List companies visible to this plugin.
+ */
+ list(input?: { limit?: number; offset?: number }): Promise<Company[]>;
+
+ /**
+ * Get one company by ID.
+ */
+ get(companyId: string): Promise<Company | null>;
+}
+
+/**
+ * `ctx.issues` — read and mutate issues plus comments.
+ *
+ * Requires:
+ * - `issues.read` for read operations
+ * - `issues.create` for create
+ * - `issues.update` for update
+ * - `issue.comments.read` for `listComments`
+ * - `issue.comments.create` for `createComment`
+ */
+export interface PluginIssuesClient {
+ list(input: {
+ companyId: string;
+ projectId?: string;
+ assigneeAgentId?: string;
+ status?: Issue["status"];
+ limit?: number;
+ offset?: number;
+ }): Promise<Issue[]>;
+ get(issueId: string, companyId: string): Promise<Issue | null>;
+ create(input: {
+ companyId: string;
+ projectId?: string;
+ goalId?: string;
+ parentId?: string;
+ title: string;
+ description?: string;
+ priority?: Issue["priority"];
+ assigneeAgentId?: string;
+ }): Promise<Issue>;
+ update(
+ issueId: string,
+ patch: Partial<Pick<
+ Issue,
+ "title" | "description" | "status" | "priority" | "assigneeAgentId"
+ >>,
+ companyId: string,
+ ): Promise<Issue>;
+ listComments(issueId: string, companyId: string): Promise<IssueComment[]>;
+ createComment(issueId: string, body: string, companyId: string): Promise<IssueComment>;
+}
+
+/**
+ * `ctx.agents` — read and manage agents.
+ *
+ * Requires `agents.read` for reads; `agents.pause` / `agents.resume` /
+ * `agents.invoke` for write operations.
+ */
+export interface PluginAgentsClient {
+ list(input: { companyId: string; status?: Agent["status"]; limit?: number; offset?: number }): Promise<Agent[]>;
+ get(agentId: string, companyId: string): Promise<Agent | null>;
+ /** Pause an agent. Throws if agent is terminated or not found. Requires `agents.pause`. */
+ pause(agentId: string, companyId: string): Promise<Agent>;
+ /** Resume a paused agent (sets status to idle). Throws if terminated, pending_approval, or not found. Requires `agents.resume`. */
+ resume(agentId: string, companyId: string): Promise<Agent>;
+ /** Invoke (wake up) an agent with a prompt payload. Throws if paused, terminated, pending_approval, or not found. Requires `agents.invoke`. */
+ invoke(agentId: string, companyId: string, opts: { prompt: string; reason?: string }): Promise<{ runId: string }>;
+ /** Create, message, and close agent chat sessions. Requires `agent.sessions.*` capabilities. */
+ sessions: PluginAgentSessionsClient;
+}
+
+// ---------------------------------------------------------------------------
+// Agent Sessions — two-way chat with agents
+// ---------------------------------------------------------------------------
+
+/**
+ * Represents an active conversational session with an agent.
+ * Maps to an `AgentTaskSession` row on the host.
+ */
+export interface AgentSession {
+ sessionId: string;
+ agentId: string;
+ companyId: string;
+ status: "active" | "closed";
+ createdAt: string;
+}
+
+/**
+ * A streaming event received during a session's `sendMessage` call.
+ * Delivered via JSON-RPC notifications from host to worker.
+ */
+export interface AgentSessionEvent {
+ sessionId: string;
+ runId: string;
+ seq: number;
+ /** The kind of event: "chunk" for output data, "status" for run state changes, "done" for end-of-stream, "error" for failures. */
+ eventType: "chunk" | "status" | "done" | "error";
+ stream: "stdout" | "stderr" | "system" | null;
+ message: string | null;
+ payload: Record<string, unknown> | null;
+}
+
+/**
+ * Result of sending a message to a session.
+ */
+export interface AgentSessionSendResult {
+ runId: string;
+}
+
+/**
+ * `ctx.agents.sessions` — create, message, and close agent chat sessions.
+ *
+ * Requires `agent.sessions.create` for create, `agent.sessions.list` for list,
+ * `agent.sessions.send` for sendMessage, `agent.sessions.close` for close.
+ */
+export interface PluginAgentSessionsClient {
+ /** Create a new conversational session with an agent. Requires `agent.sessions.create`. */
+ create(agentId: string, companyId: string, opts?: {
+ taskKey?: string;
+ reason?: string;
+ }): Promise<AgentSession>;
+
+ /** List active sessions for an agent owned by this plugin. Requires `agent.sessions.list`. */
+ list(agentId: string, companyId: string): Promise<AgentSession[]>;
+
+ /**
+ * Send a message to a session and receive streaming events via the `onEvent` callback.
+ * Returns immediately with `{ runId }`. Events are delivered asynchronously.
+ * Requires `agent.sessions.send`.
+ */
+ sendMessage(sessionId: string, companyId: string, opts: {
+ prompt: string;
+ reason?: string;
+ onEvent?: (event: AgentSessionEvent) => void;
+ }): Promise<AgentSessionSendResult>;
+
+ /** Close a session, releasing resources. Requires `agent.sessions.close`. */
+ close(sessionId: string, companyId: string): Promise<void>;
+}
+
+/**
+ * `ctx.goals` — read and mutate goals.
+ *
+ * Requires:
+ * - `goals.read` for read operations
+ * - `goals.create` for create
+ * - `goals.update` for update
+ */
+export interface PluginGoalsClient {
+ list(input: {
+ companyId: string;
+ level?: Goal["level"];
+ status?: Goal["status"];
+ limit?: number;
+ offset?: number;
+ }): Promise<Goal[]>;
+ get(goalId: string, companyId: string): Promise<Goal | null>;
+ create(input: {
+ companyId: string;
+ title: string;
+ description?: string;
+ level?: Goal["level"];
+ status?: Goal["status"];
+ parentId?: string;
+ ownerAgentId?: string;
+ }): Promise<Goal>;
+ update(
+ goalId: string,
+ patch: Partial<Pick<
+ Goal,
+ "title" | "description" | "level" | "status" | "parentId" | "ownerAgentId"
+ >>,
+ companyId: string,
+ ): Promise<Goal>;
+}
+
+// ---------------------------------------------------------------------------
+// Streaming (worker → UI push channel)
+// ---------------------------------------------------------------------------
+
+/**
+ * `ctx.streams` — push real-time events from the worker to the plugin UI.
+ *
+ * The worker opens a named channel, emits events on it, and closes it when
+ * done. On the UI side, `usePluginStream(channel)` receives these events in
+ * real time via SSE.
+ *
+ * Streams are scoped to `(pluginId, channel, companyId)`. Multiple UI clients
+ * can subscribe to the same channel concurrently.
+ *
+ * @example
+ * ```ts
+ * // Worker: stream chat tokens to the UI
+ * ctx.streams.open("chat", companyId);
+ * for await (const token of tokenStream) {
+ * ctx.streams.emit("chat", { type: "token", text: token });
+ * }
+ * ctx.streams.close("chat");
+ * ```
+ *
+ * @see usePluginStream in `@paperclipai/plugin-sdk/ui`
+ */
+export interface PluginStreamsClient {
+ /**
+ * Open a named stream channel. Optional — `emit()` implicitly opens if needed.
+ * Sends a `stream:open` event to connected UI clients.
+ */
+ open(channel: string, companyId: string): void;
+
+ /**
+ * Push an event to all UI clients subscribed to this channel.
+ *
+ * @param channel - Stream channel name (e.g. `"chat"`, `"logs"`)
+ * @param event - JSON-serializable event payload
+ */
+ emit(channel: string, event: unknown): void;
+
+ /**
+ * Close a stream channel. Sends a `stream:close` event to connected UI
+ * clients so they know no more events will arrive.
+ */
+ close(channel: string): void;
+}
+
+// ---------------------------------------------------------------------------
+// Full plugin context
+// ---------------------------------------------------------------------------
+
+/**
+ * The full plugin context object passed to the plugin worker at initialisation.
+ *
+ * This is the central interface plugin authors use to interact with the host.
+ * Every client is capability-gated: calling a client method without the
+ * required capability declared in the manifest results in a runtime error.
+ *
+ * @example
+ * ```ts
+ * import { definePlugin } from "@paperclipai/plugin-sdk";
+ *
+ * export default definePlugin({
+ * async setup(ctx) {
+ * ctx.events.on("issue.created", async (event) => {
+ * ctx.logger.info("Issue created", { issueId: event.entityId });
+ * });
+ *
+ * ctx.data.register("sync-health", async ({ companyId }) => {
+ * const state = await ctx.state.get({ scopeKind: "company", scopeId: String(companyId), stateKey: "last-sync" });
+ * return { lastSync: state };
+ * });
+ * },
+ * });
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §14 — SDK Surface
+ */
+export interface PluginContext {
+ /** The plugin's manifest as validated at install time. */
+ manifest: PaperclipPluginManifestV1;
+
+ /** Read resolved operator configuration. */
+ config: PluginConfigClient;
+
+ /** Subscribe to and emit domain events. Requires `events.subscribe` / `events.emit`. */
+ events: PluginEventsClient;
+
+ /** Register handlers for scheduled jobs. Requires `jobs.schedule`. */
+ jobs: PluginJobsClient;
+
+ /** Register launcher metadata that the host can surface in plugin UI entry points. */
+ launchers: PluginLaunchersClient;
+
+ /** Make outbound HTTP requests. Requires `http.outbound`. */
+ http: PluginHttpClient;
+
+ /** Resolve secret references. Requires `secrets.read-ref`. */
+ secrets: PluginSecretsClient;
+
+ /** Read and write assets. Requires `assets.read` / `assets.write`. */
+ assets: PluginAssetsClient;
+
+ /** Write activity log entries. Requires `activity.log.write`. */
+ activity: PluginActivityClient;
+
+ /** Read and write scoped plugin state. Requires `plugin.state.read` / `plugin.state.write`. */
+ state: PluginStateClient;
+
+ /** Create and query plugin-owned entity records. */
+ entities: PluginEntitiesClient;
+
+ /** Read project and workspace metadata. Requires `projects.read` / `project.workspaces.read`. */
+ projects: PluginProjectsClient;
+
+ /** Read company metadata. Requires `companies.read`. */
+ companies: PluginCompaniesClient;
+
+ /** Read and write issues/comments. Requires issue capabilities. */
+ issues: PluginIssuesClient;
+
+ /** Read and manage agents. Requires `agents.read` for reads; `agents.pause` / `agents.resume` / `agents.invoke` for write ops. */
+ agents: PluginAgentsClient;
+
+ /** Read and mutate goals. Requires `goals.read` for reads; `goals.create` / `goals.update` for write ops. */
+ goals: PluginGoalsClient;
+
+ /** Register getData handlers for the plugin's UI components. */
+ data: PluginDataClient;
+
+ /** Register performAction handlers for the plugin's UI components. */
+ actions: PluginActionsClient;
+
+ /** Push real-time events from the worker to the plugin UI via SSE. */
+ streams: PluginStreamsClient;
+
+ /** Register agent tool handlers. Requires `agent.tools.register`. */
+ tools: PluginToolsClient;
+
+ /** Write plugin metrics. Requires `metrics.write`. */
+ metrics: PluginMetricsClient;
+
+ /** Structured logger. Output is captured and surfaced in the plugin health dashboard. */
+ logger: PluginLogger;
+}
diff --git a/packages/plugins/sdk/src/ui/components.ts b/packages/plugins/sdk/src/ui/components.ts
new file mode 100644
index 0000000000..b93c1db44e
--- /dev/null
+++ b/packages/plugins/sdk/src/ui/components.ts
@@ -0,0 +1,310 @@
+/**
+ * Shared UI component declarations for plugin frontends.
+ *
+ * These components are exported from `@paperclipai/plugin-sdk/ui` and are
+ * provided by the host at runtime. They match the host's design tokens and
+ * visual language, reducing the boilerplate needed to build consistent plugin UIs.
+ *
+ * **Plugins are not required to use these components.** They exist to reduce
+ * boilerplate and keep visual consistency. A plugin may render entirely custom
+ * UI using any React component library.
+ *
+ * Component implementations are provided by the host — plugin bundles contain
+ * only the type declarations; the runtime implementations are injected via the
+ * host module registry.
+ *
+ * @see PLUGIN_SPEC.md §19.6 — Shared Components In `@paperclipai/plugin-sdk/ui`
+ */
+
+import type React from "react";
+import { renderSdkUiComponent } from "./runtime.js";
+
+// ---------------------------------------------------------------------------
+// Component prop interfaces
+// ---------------------------------------------------------------------------
+
+/**
+ * A trend value that can accompany a metric.
+ * Positive values indicate upward trends; negative values indicate downward trends.
+ */
+export interface MetricTrend {
+ /** Direction of the trend. */
+ direction: "up" | "down" | "flat";
+ /** Percentage change value (e.g. `12.5` for 12.5%). */
+ percentage?: number;
+}
+
+/** Props for `MetricCard`. */
+export interface MetricCardProps {
+ /** Short label describing the metric (e.g. `"Synced Issues"`). */
+ label: string;
+ /** The metric value to display. */
+ value: number | string;
+ /** Optional trend indicator. */
+ trend?: MetricTrend;
+ /** Optional sparkline data (array of numbers, latest last). */
+ sparkline?: number[];
+ /** Optional unit suffix (e.g. `"%"`, `"ms"`). */
+ unit?: string;
+}
+
+/** Status variants for `StatusBadge`. */
+export type StatusBadgeVariant = "ok" | "warning" | "error" | "info" | "pending";
+
+/** Props for `StatusBadge`. */
+export interface StatusBadgeProps {
+ /** Human-readable label. */
+ label: string;
+ /** Visual variant determining colour. */
+ status: StatusBadgeVariant;
+}
+
+/** A single column definition for `DataTable`. */
+export interface DataTableColumn<T = Record<string, unknown>> {
+ /** Column key, matching a field on the row object. */
+ key: keyof T & string;
+ /** Column header label. */
+ header: string;
+ /** Optional custom cell renderer. */
+ render?: (value: unknown, row: T) => React.ReactNode;
+ /** Whether this column is sortable. */
+ sortable?: boolean;
+ /** CSS width (e.g. `"120px"`, `"20%"`). */
+ width?: string;
+}
+
+/** Props for `DataTable`. */
+export interface DataTableProps<T = Record<string, unknown>> {
+ /** Column definitions. */
+ columns: DataTableColumn<T>[];
+ /** Row data. Each row should have a stable `id` field. */
+ rows: T[];
+ /** Whether the table is currently loading. */
+ loading?: boolean;
+ /** Message shown when `rows` is empty. */
+ emptyMessage?: string;
+ /** Total row count for pagination (if different from `rows.length`). */
+ totalCount?: number;
+ /** Current page (0-based, for pagination). */
+ page?: number;
+ /** Rows per page (for pagination). */
+ pageSize?: number;
+ /** Callback when page changes. */
+ onPageChange?: (page: number) => void;
+ /** Callback when a column header is clicked to sort. */
+ onSort?: (key: string, direction: "asc" | "desc") => void;
+}
+
+/** A single data point for `TimeseriesChart`. */
+export interface TimeseriesDataPoint {
+ /** ISO 8601 timestamp. */
+ timestamp: string;
+ /** Numeric value. */
+ value: number;
+ /** Optional label for the point. */
+ label?: string;
+}
+
+/** Props for `TimeseriesChart`. */
+export interface TimeseriesChartProps {
+ /** Series data. */
+ data: TimeseriesDataPoint[];
+ /** Chart title. */
+ title?: string;
+ /** Y-axis label. */
+ yLabel?: string;
+ /** Chart type. Defaults to `"line"`. */
+ type?: "line" | "bar";
+ /** Height of the chart in pixels. Defaults to `200`. */
+ height?: number;
+ /** Whether the chart is currently loading. */
+ loading?: boolean;
+}
+
+/** Props for `MarkdownBlock`. */
+export interface MarkdownBlockProps {
+ /** Markdown content to render. */
+ content: string;
+}
+
+/** A single key-value pair for `KeyValueList`. */
+export interface KeyValuePair {
+ /** Label for the key. */
+ label: string;
+ /** Value to display. May be a string, number, or a React node. */
+ value: React.ReactNode;
+}
+
+/** Props for `KeyValueList`. */
+export interface KeyValueListProps {
+ /** Pairs to render in the list. */
+ pairs: KeyValuePair[];
+}
+
+/** A single action button for `ActionBar`. */
+export interface ActionBarItem {
+ /** Button label. */
+ label: string;
+ /** Action key to call via the plugin bridge. */
+ actionKey: string;
+ /** Optional parameters to pass to the action handler. */
+ params?: Record<string, unknown>;
+ /** Button variant. Defaults to `"default"`. */
+ variant?: "default" | "primary" | "destructive";
+ /** Whether to show a confirmation dialog before executing. */
+ confirm?: boolean;
+ /** Text for the confirmation dialog (used when `confirm` is true). */
+ confirmMessage?: string;
+}
+
+/** Props for `ActionBar`. */
+export interface ActionBarProps {
+ /** Action definitions. */
+ actions: ActionBarItem[];
+ /** Called after an action succeeds. Use to trigger data refresh. */
+ onSuccess?: (actionKey: string, result: unknown) => void;
+ /** Called when an action fails. */
+ onError?: (actionKey: string, error: unknown) => void;
+}
+
+/** A single log line for `LogView`. */
+export interface LogViewEntry {
+ /** ISO 8601 timestamp. */
+ timestamp: string;
+ /** Log level. */
+ level: "info" | "warn" | "error" | "debug";
+ /** Log message. */
+ message: string;
+ /** Optional structured metadata. */
+ meta?: Record<string, unknown>;
+}
+
+/** Props for `LogView`. */
+export interface LogViewProps {
+ /** Log entries to display. */
+ entries: LogViewEntry[];
+ /** Maximum height of the scrollable container (CSS value). Defaults to `"400px"`. */
+ maxHeight?: string;
+ /** Whether to auto-scroll to the latest entry. */
+ autoScroll?: boolean;
+ /** Whether the log is currently loading. */
+ loading?: boolean;
+}
+
+/** Props for `JsonTree`. */
+export interface JsonTreeProps {
+ /** The data to render as a collapsible JSON tree. */
+ data: unknown;
+ /** Initial depth to expand. Defaults to `2`. */
+ defaultExpandDepth?: number;
+}
+
+/** Props for `Spinner`. */
+export interface SpinnerProps {
+ /** Size of the spinner. Defaults to `"md"`. */
+ size?: "sm" | "md" | "lg";
+ /** Accessible label for the spinner (used as `aria-label`). */
+ label?: string;
+}
+
+/** Props for `ErrorBoundary`. */
+export interface ErrorBoundaryProps {
+ /** Content to render inside the error boundary. */
+ children: React.ReactNode;
+ /** Optional custom fallback to render when an error is caught. */
+ fallback?: React.ReactNode;
+ /** Called when an error is caught, for logging or reporting. */
+ onError?: (error: Error, info: React.ErrorInfo) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Component declarations (provided by host at runtime)
+// ---------------------------------------------------------------------------
+
+// These are declared as ambient values so plugin TypeScript code can import
+// and use them with full type-checking. The host's module registry provides
+// the concrete React component implementations at bundle load time.
+
+/**
+ * Displays a single metric with an optional trend indicator and sparkline.
+ *
+ * @see PLUGIN_SPEC.md §19.6 — Shared Components
+ */
+function createSdkUiComponent<TProps>(name: string): React.ComponentType<TProps> {
+ return function PaperclipSdkUiComponent(props: TProps) {
+ return renderSdkUiComponent(name, props) as React.ReactNode;
+ };
+}
+
+export const MetricCard = createSdkUiComponent<MetricCardProps>("MetricCard");
+
+/**
+ * Displays an inline status badge (ok / warning / error / info / pending).
+ *
+ * @see PLUGIN_SPEC.md §19.6 — Shared Components
+ */
+export const StatusBadge = createSdkUiComponent<StatusBadgeProps>("StatusBadge");
+
+/**
+ * Sortable, paginated data table.
+ *
+ * @see PLUGIN_SPEC.md §19.6 — Shared Components
+ */
+export const DataTable = createSdkUiComponent<DataTableProps>("DataTable");
+
+/**
+ * Line or bar chart for time-series data.
+ *
+ * @see PLUGIN_SPEC.md §19.6 — Shared Components
+ */
+export const TimeseriesChart = createSdkUiComponent<TimeseriesChartProps>("TimeseriesChart");
+
+/**
+ * Renders Markdown text as HTML.
+ *
+ * @see PLUGIN_SPEC.md §19.6 — Shared Components
+ */
+export const MarkdownBlock = createSdkUiComponent<MarkdownBlockProps>("MarkdownBlock");
+
+/**
+ * Renders a definition-list of label/value pairs.
+ *
+ * @see PLUGIN_SPEC.md §19.6 — Shared Components
+ */
+export const KeyValueList = createSdkUiComponent<KeyValueListProps>("KeyValueList");
+
+/**
+ * Row of action buttons wired to the plugin bridge's `performAction` handlers.
+ *
+ * @see PLUGIN_SPEC.md §19.6 — Shared Components
+ */
+export const ActionBar = createSdkUiComponent<ActionBarProps>("ActionBar");
+
+/**
+ * Scrollable, timestamped log output viewer.
+ *
+ * @see PLUGIN_SPEC.md §19.6 — Shared Components
+ */
+export const LogView = createSdkUiComponent<LogViewProps>("LogView");
+
+/**
+ * Collapsible JSON tree for debugging or raw data inspection.
+ *
+ * @see PLUGIN_SPEC.md §19.6 — Shared Components
+ */
+export const JsonTree = createSdkUiComponent<JsonTreeProps>("JsonTree");
+
+/**
+ * Loading indicator.
+ *
+ * @see PLUGIN_SPEC.md §19.6 — Shared Components
+ */
+export const Spinner = createSdkUiComponent<SpinnerProps>("Spinner");
+
+/**
+ * React error boundary that prevents plugin rendering errors from crashing
+ * the host page.
+ *
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+export const ErrorBoundary = createSdkUiComponent<ErrorBoundaryProps>("ErrorBoundary");
diff --git a/packages/plugins/sdk/src/ui/hooks.ts b/packages/plugins/sdk/src/ui/hooks.ts
new file mode 100644
index 0000000000..fdba2fe39e
--- /dev/null
+++ b/packages/plugins/sdk/src/ui/hooks.ts
@@ -0,0 +1,153 @@
+import type { PluginDataResult, PluginActionFn, PluginHostContext, PluginStreamResult } from "./types.js";
+import { getSdkUiRuntimeValue } from "./runtime.js";
+
+// ---------------------------------------------------------------------------
+// usePluginData
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch data from the plugin worker's registered `getData` handler.
+ *
+ * Calls `ctx.data.register(key, handler)` in the worker and returns the
+ * result as reactive state. Re-fetches when `params` changes.
+ *
+ * @template T The expected shape of the returned data
+ * @param key - The data key matching the handler registered with `ctx.data.register()`
+ * @param params - Optional parameters forwarded to the handler
+ * @returns `PluginDataResult<T>` with `data`, `loading`, `error`, and `refresh`
+ *
+ * @example
+ * ```tsx
+ * function SyncWidget({ context }: PluginWidgetProps) {
+ * const { data, loading, error } = usePluginData<SyncHealth>("sync-health", {
+ * companyId: context.companyId,
+ * });
+ *
+ * if (loading) return <Spinner />;
+ * if (error) return <div>Error: {error.message}</div>;
+ * return <MetricCard label="Synced Issues" value={data!.syncedCount} />;
+ * }
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §13.8 — `getData`
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+export function usePluginData<T = unknown>(
+ key: string,
+ params?: Record<string, unknown>,
+): PluginDataResult<T> {
+ const impl = getSdkUiRuntimeValue<
+ (nextKey: string, nextParams?: Record<string, unknown>) => PluginDataResult<T>
+ >("usePluginData");
+ return impl(key, params);
+}
+
+// ---------------------------------------------------------------------------
+// usePluginAction
+// ---------------------------------------------------------------------------
+
+/**
+ * Get a callable function that invokes the plugin worker's registered
+ * `performAction` handler.
+ *
+ * The returned function is async and throws a `PluginBridgeError` on failure.
+ *
+ * @param key - The action key matching the handler registered with `ctx.actions.register()`
+ * @returns An async function that sends the action to the worker and resolves with the result
+ *
+ * @example
+ * ```tsx
+ * function ResyncButton({ context }: PluginWidgetProps) {
+ * const resync = usePluginAction("resync");
+ * const [error, setError] = useState<string | null>(null);
+ *
+ * async function handleClick() {
+ * try {
+ * await resync({ companyId: context.companyId });
+ * } catch (err) {
+ * setError((err as PluginBridgeError).message);
+ * }
+ * }
+ *
+ * return <button onClick={handleClick}>Resync Now</button>;
+ * }
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §13.9 — `performAction`
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+export function usePluginAction(key: string): PluginActionFn {
+ const impl = getSdkUiRuntimeValue<(nextKey: string) => PluginActionFn>("usePluginAction");
+ return impl(key);
+}
+
+// ---------------------------------------------------------------------------
+// useHostContext
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the current host context (active company, project, entity, user).
+ *
+ * Use this to know which context the plugin component is being rendered in
+ * so you can scope data requests and actions accordingly.
+ *
+ * @returns The current `PluginHostContext`
+ *
+ * @example
+ * ```tsx
+ * function IssueTab() {
+ * const { companyId, entityId } = useHostContext();
+ * const { data } = usePluginData("linear-link", { issueId: entityId });
+ * return <div>{data?.linearIssueUrl}</div>;
+ * }
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §19 — UI Extension Model
+ */
+export function useHostContext(): PluginHostContext {
+ const impl = getSdkUiRuntimeValue<() => PluginHostContext>("useHostContext");
+ return impl();
+}
+
+// ---------------------------------------------------------------------------
+// usePluginStream
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribe to a real-time event stream pushed from the plugin worker.
+ *
+ * Opens an SSE connection to `GET /api/plugins/:pluginId/bridge/stream/:channel`
+ * and accumulates events as they arrive. The worker pushes events using
+ * `ctx.streams.emit(channel, event)`.
+ *
+ * @template T The expected shape of each streamed event
+ * @param channel - The stream channel name (must match what the worker uses in `ctx.streams.emit`)
+ * @param options - Optional configuration for the stream
+ * @returns `PluginStreamResult<T>` with `events`, `lastEvent`, connection status, and `close()`
+ *
+ * @example
+ * ```tsx
+ * function ChatMessages() {
+ * const { events, connected, close } = usePluginStream<ChatToken>("chat-stream");
+ *
+ * return (
+ * <div>
+ * {events.map((e, i) => <span key={i}>{e.text}</span>)}
+ * {connected && <span className="pulse" />}
+ * <button onClick={close}>Stop</button>
+ * </div>
+ * );
+ * }
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §19.8 — Real-Time Streaming
+ */
+export function usePluginStream<T = unknown>(
+ channel: string,
+ options?: { companyId?: string },
+): PluginStreamResult<T> {
+ const impl = getSdkUiRuntimeValue<
+ (nextChannel: string, nextOptions?: { companyId?: string }) => PluginStreamResult<T>
+ >("usePluginStream");
+ return impl(channel, options);
+}
diff --git a/packages/plugins/sdk/src/ui/index.ts b/packages/plugins/sdk/src/ui/index.ts
new file mode 100644
index 0000000000..05fdad6319
--- /dev/null
+++ b/packages/plugins/sdk/src/ui/index.ts
@@ -0,0 +1,125 @@
+/**
+ * `@paperclipai/plugin-sdk/ui` — Paperclip plugin UI SDK.
+ *
+ * Import this subpath from plugin UI bundles (React components that run in
+ * the host frontend). Do **not** import this from plugin worker code.
+ *
+ * The worker-side SDK is available from `@paperclipai/plugin-sdk` (root).
+ *
+ * @see PLUGIN_SPEC.md §19.0.1 — Plugin UI SDK
+ * @see PLUGIN_SPEC.md §29.2 — SDK Versioning
+ *
+ * @example
+ * ```tsx
+ * // Plugin UI bundle entry (dist/ui/index.tsx)
+ * import {
+ * usePluginData,
+ * usePluginAction,
+ * useHostContext,
+ * MetricCard,
+ * StatusBadge,
+ * Spinner,
+ * } from "@paperclipai/plugin-sdk/ui";
+ * import type { PluginWidgetProps } from "@paperclipai/plugin-sdk/ui";
+ *
+ * export function DashboardWidget({ context }: PluginWidgetProps) {
+ * const { data, loading, error } = usePluginData("sync-health", {
+ * companyId: context.companyId,
+ * });
+ * const resync = usePluginAction("resync");
+ *
+ * if (loading) return <Spinner />;
+ * if (error) return <div>Error: {error.message}</div>;
+ *
+ * return (
+ * <div>
+ * <MetricCard label="Synced Issues" value={data!.syncedCount} />
+ * <button onClick={() => resync({ companyId: context.companyId })}>
+ * Resync Now
+ * </button>
+ * </div>
+ * );
+ * }
+ * ```
+ */
+
+/**
+ * Bridge hooks for plugin UI components to communicate with the plugin worker.
+ *
+ * - `usePluginData(key, params)` — fetch data from the worker's `getData` handler
+ * - `usePluginAction(key)` — get a callable that invokes the worker's `performAction` handler
+ * - `useHostContext()` — read the current active company, project, entity, and user IDs
+ * - `usePluginStream(channel)` — subscribe to real-time SSE events from the worker
+ */
+export {
+ usePluginData,
+ usePluginAction,
+ useHostContext,
+ usePluginStream,
+} from "./hooks.js";
+
+// Bridge error and host context types
+export type {
+ PluginBridgeError,
+ PluginBridgeErrorCode,
+ PluginHostContext,
+ PluginModalBoundsRequest,
+ PluginRenderCloseEvent,
+ PluginRenderCloseHandler,
+ PluginRenderCloseLifecycle,
+ PluginRenderEnvironmentContext,
+ PluginLauncherBounds,
+ PluginLauncherRenderEnvironment,
+ PluginDataResult,
+ PluginActionFn,
+ PluginStreamResult,
+} from "./types.js";
+
+// Slot component prop interfaces
+export type {
+ PluginPageProps,
+ PluginWidgetProps,
+ PluginDetailTabProps,
+ PluginSidebarProps,
+ PluginProjectSidebarItemProps,
+ PluginCommentAnnotationProps,
+ PluginCommentContextMenuItemProps,
+ PluginSettingsPageProps,
+} from "./types.js";
+
+// Shared UI components
+export {
+ MetricCard,
+ StatusBadge,
+ DataTable,
+ TimeseriesChart,
+ MarkdownBlock,
+ KeyValueList,
+ ActionBar,
+ LogView,
+ JsonTree,
+ Spinner,
+ ErrorBoundary,
+} from "./components.js";
+
+// Shared component prop types (for plugin authors who need to extend them)
+export type {
+ MetricCardProps,
+ MetricTrend,
+ StatusBadgeProps,
+ StatusBadgeVariant,
+ DataTableProps,
+ DataTableColumn,
+ TimeseriesChartProps,
+ TimeseriesDataPoint,
+ MarkdownBlockProps,
+ KeyValueListProps,
+ KeyValuePair,
+ ActionBarProps,
+ ActionBarItem,
+ LogViewProps,
+ LogViewEntry,
+ JsonTreeProps,
+ SpinnerProps,
+ ErrorBoundaryProps,
+} from "./components.js";
diff --git a/packages/plugins/sdk/src/ui/runtime.ts b/packages/plugins/sdk/src/ui/runtime.ts
new file mode 100644
index 0000000000..998428e970
--- /dev/null
+++ b/packages/plugins/sdk/src/ui/runtime.ts
@@ -0,0 +1,51 @@
+type PluginBridgeRegistry = {
+ react?: {
+ createElement?: (type: unknown, props?: Record<string, unknown> | null) => unknown;
+ } | null;
+ sdkUi?: Record<string, unknown> | null;
+};
+
+type GlobalBridge = typeof globalThis & {
+ __paperclipPluginBridge__?: PluginBridgeRegistry;
+};
+
+function getBridgeRegistry(): PluginBridgeRegistry | undefined {
+ return (globalThis as GlobalBridge).__paperclipPluginBridge__;
+}
+
+function missingBridgeValueError(name: string): Error {
+ return new Error(
+ `Paperclip plugin UI runtime is not initialized for "${name}". ` +
+ 'Ensure the host loaded the plugin bridge before rendering this UI module.',
+ );
+}
+
+export function getSdkUiRuntimeValue<T>(name: string): T {
+ const value = getBridgeRegistry()?.sdkUi?.[name];
+ if (value === undefined) {
+ throw missingBridgeValueError(name);
+ }
+ return value as T;
+}
+
+export function renderSdkUiComponent<TProps>(
+ name: string,
+ props: TProps,
+): unknown {
+ const registry = getBridgeRegistry();
+ const component = registry?.sdkUi?.[name];
+ if (component === undefined) {
+ throw missingBridgeValueError(name);
+ }
+
+ const createElement = registry?.react?.createElement;
+ if (typeof createElement === "function") {
+ return createElement(component, props as Record<string, unknown>);
+ }
+
+ if (typeof component === "function") {
+ return component(props);
+ }
+
+ throw new Error(`Paperclip plugin UI component "${name}" is not callable`);
+}
diff --git a/packages/plugins/sdk/src/ui/types.ts b/packages/plugins/sdk/src/ui/types.ts
new file mode 100644
index 0000000000..267b10b5ad
--- /dev/null
+++ b/packages/plugins/sdk/src/ui/types.ts
@@ -0,0 +1,358 @@
+/**
+ * Paperclip plugin UI SDK — types for plugin frontend components.
+ *
+ * Plugin UI bundles import from `@paperclipai/plugin-sdk/ui`. This subpath
+ * provides the bridge hooks, component prop interfaces, and error types that
+ * plugin React components use to communicate with the host.
+ *
+ * Plugin UI bundles are loaded as ES modules into designated extension slots.
+ * All communication with the plugin worker goes through the host bridge — plugin
+ * components must NOT access host internals or call host APIs directly.
+ *
+ * @see PLUGIN_SPEC.md §19 — UI Extension Model
+ * @see PLUGIN_SPEC.md §19.0.1 — Plugin UI SDK
+ * @see PLUGIN_SPEC.md §29.2 — SDK Versioning
+ */
+
+import type {
+ PluginBridgeErrorCode,
+ PluginLauncherBounds,
+ PluginLauncherRenderEnvironment,
+} from "@paperclipai/shared";
+import type {
+ PluginLauncherRenderContextSnapshot,
+ PluginModalBoundsRequest,
+ PluginRenderCloseEvent,
+} from "../protocol.js";
+
+// Re-export PluginBridgeErrorCode for plugin UI authors
+export type {
+ PluginBridgeErrorCode,
+ PluginLauncherBounds,
+ PluginLauncherRenderEnvironment,
+} from "@paperclipai/shared";
+export type {
+ PluginLauncherRenderContextSnapshot,
+ PluginModalBoundsRequest,
+ PluginRenderCloseEvent,
+} from "../protocol.js";
+
+// ---------------------------------------------------------------------------
+// Bridge error
+// ---------------------------------------------------------------------------
+
+/**
+ * Structured error returned by the bridge when a UI → worker call fails.
+ *
+ * Plugin components receive this in `usePluginData()` as the `error` field
+ * and may encounter it as a thrown value from `usePluginAction()`.
+ *
+ * Error codes:
+ * - `WORKER_UNAVAILABLE` — plugin worker is not running
+ * - `CAPABILITY_DENIED` — plugin lacks the required capability
+ * - `WORKER_ERROR` — worker returned an error from its handler
+ * - `TIMEOUT` — worker did not respond within the configured timeout
+ * - `UNKNOWN` — unexpected bridge-level failure
+ *
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+export interface PluginBridgeError {
+ /** Machine-readable error code. */
+ code: PluginBridgeErrorCode;
+ /** Human-readable error message. */
+ message: string;
+ /**
+ * Original error details from the worker, if available.
+ * Only present when `code === "WORKER_ERROR"`.
+ */
+ details?: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Host context available to all plugin components
+// ---------------------------------------------------------------------------
+
+/**
+ * Read-only host context passed to every plugin component via `useHostContext()`.
+ *
+ * Plugin components use this to know which company, project, or entity is
+ * currently active so they can scope their data requests accordingly.
+ *
+ * @see PLUGIN_SPEC.md §19 — UI Extension Model
+ */
+export interface PluginHostContext {
+ /** UUID of the currently active company, if any. */
+ companyId: string | null;
+ /** URL prefix for the current company (e.g. `"my-company"`). */
+ companyPrefix: string | null;
+ /** UUID of the currently active project, if any. */
+ projectId: string | null;
+ /** UUID of the current entity (for detail tab contexts), if any. */
+ entityId: string | null;
+ /** Type of the current entity (e.g. `"issue"`, `"agent"`). */
+ entityType: string | null;
+ /**
+ * UUID of the parent entity when rendering nested slots.
+ * For `commentAnnotation` slots this is the issue ID containing the comment.
+ */
+ parentEntityId?: string | null;
+ /** UUID of the current authenticated user. */
+ userId: string | null;
+ /** Runtime metadata for the host container currently rendering this plugin UI. */
+ renderEnvironment?: PluginRenderEnvironmentContext | null;
+}
+
+/**
+ * Async-capable callback invoked during a host-managed close lifecycle.
+ */
+export type PluginRenderCloseHandler = (
+ event: PluginRenderCloseEvent,
+) => void | Promise<void>;
+
+/**
+ * Close lifecycle hooks available when the plugin UI is rendered inside a
+ * host-managed launcher environment.
+ */
+export interface PluginRenderCloseLifecycle {
+ /** Register a callback before the host closes the current environment. */
+ onBeforeClose?(handler: PluginRenderCloseHandler): () => void;
+ /** Register a callback after the host closes the current environment. */
+ onClose?(handler: PluginRenderCloseHandler): () => void;
+}
+
+/**
+ * Runtime information about the host container currently rendering a plugin UI.
+ */
+export interface PluginRenderEnvironmentContext
+ extends PluginLauncherRenderContextSnapshot {
+ /** Optional host callback for requesting new bounds while a modal is open. */
+ requestModalBounds?(request: PluginModalBoundsRequest): Promise<void>;
+ /** Optional close lifecycle callbacks for host-managed overlays. */
+ closeLifecycle?: PluginRenderCloseLifecycle | null;
+}
+
+// ---------------------------------------------------------------------------
+// Slot component prop interfaces
+// ---------------------------------------------------------------------------
+
+/**
+ * Props passed to a plugin page component.
+ *
+ * A page is a full-page extension at `/plugins/:pluginId` or `/:company/plugins/:pluginId`.
+ *
+ * @see PLUGIN_SPEC.md §19.1 — Global Operator Routes
+ * @see PLUGIN_SPEC.md §19.2 — Company-Context Routes
+ */
+export interface PluginPageProps {
+ /** The current host context. */
+ context: PluginHostContext;
+}
+
+/**
+ * Props passed to a plugin dashboard widget component.
+ *
+ * A dashboard widget is rendered as a card or section on the main dashboard.
+ *
+ * @see PLUGIN_SPEC.md §19.4 — Dashboard Widgets
+ */
+export interface PluginWidgetProps {
+ /** The current host context. */
+ context: PluginHostContext;
+}
+
+/**
+ * Props passed to a plugin detail tab component.
+ *
+ * A detail tab is rendered as an additional tab on a project, issue, agent,
+ * goal, or run detail page.
+ *
+ * @see PLUGIN_SPEC.md §19.3 — Detail Tabs
+ */
+export interface PluginDetailTabProps {
+ /** The current host context, always including `entityId` and `entityType`. */
+ context: PluginHostContext & {
+ entityId: string;
+ entityType: string;
+ };
+}
+
+/**
+ * Props passed to a plugin sidebar component.
+ *
+ * A sidebar entry adds a link or section to the application sidebar.
+ *
+ * @see PLUGIN_SPEC.md §19.5 — Sidebar Entries
+ */
+export interface PluginSidebarProps {
+ /** The current host context. */
+ context: PluginHostContext;
+}
+
+/**
+ * Props passed to a plugin project sidebar item component.
+ *
+ * A project sidebar item is rendered **once per project** under that project's
+ * row in the sidebar Projects list. The host passes the current project's id
+ * in `context.entityId` and `context.entityType` is `"project"`.
+ *
+ * Use this slot to add a link (e.g. "Files", "Linear Sync") that navigates to
+ * the project detail with a plugin tab selected: `/projects/:projectRef?tab=plugin:key:slotId`.
+ *
+ * @see PLUGIN_SPEC.md §19.5.1 — Project sidebar items
+ */
+export interface PluginProjectSidebarItemProps {
+ /** Host context plus entityId (project id) and entityType "project". */
+ context: PluginHostContext & {
+ entityId: string;
+ entityType: "project";
+ };
+}
+
+/**
+ * Props passed to a plugin comment annotation component.
+ *
+ * A comment annotation is rendered below each individual comment in the
+ * issue detail timeline. The host passes the comment ID as `entityId`
+ * and `"comment"` as `entityType`, plus the parent issue ID as
+ * `parentEntityId` so the plugin can scope data fetches to both.
+ *
+ * Use this slot to augment comments with parsed file links, sentiment
+ * badges, inline actions, or any per-comment metadata.
+ *
+ * @see PLUGIN_SPEC.md §19.6 — Comment Annotations
+ */
+export interface PluginCommentAnnotationProps {
+ /** Host context with comment and parent issue identifiers. */
+ context: PluginHostContext & {
+ /** UUID of the comment being annotated. */
+ entityId: string;
+ /** Always `"comment"` for comment annotation slots. */
+ entityType: "comment";
+ /** UUID of the parent issue containing this comment. */
+ parentEntityId: string;
+ };
+}
+
+/**
+ * Props passed to a plugin comment context menu item component.
+ *
+ * A comment context menu item is rendered in a "more" dropdown menu on
+ * each comment in the issue detail timeline. The host passes the comment
+ * ID as `entityId` and `"comment"` as `entityType`, plus the parent
+ * issue ID as `parentEntityId`.
+ *
+ * Use this slot to add per-comment actions such as "Create sub-issue from
+ * comment", "Translate", "Flag for review", or any custom plugin action.
+ *
+ * @see PLUGIN_SPEC.md §19.7 — Comment Context Menu Items
+ */
+export interface PluginCommentContextMenuItemProps {
+ /** Host context with comment and parent issue identifiers. */
+ context: PluginHostContext & {
+ /** UUID of the comment this menu item acts on. */
+ entityId: string;
+ /** Always `"comment"` for comment context menu item slots. */
+ entityType: "comment";
+ /** UUID of the parent issue containing this comment. */
+ parentEntityId: string;
+ };
+}
+
+/**
+ * Props passed to a plugin settings page component.
+ *
+ * Overrides the auto-generated JSON Schema form when the plugin declares
+ * a `settingsPage` UI slot. The component is responsible for reading and
+ * writing config through the bridge.
+ *
+ * @see PLUGIN_SPEC.md §19.8 — Plugin Settings UI
+ */
+export interface PluginSettingsPageProps {
+ /** The current host context. */
+ context: PluginHostContext;
+}
+
+// ---------------------------------------------------------------------------
+// usePluginData hook return type
+// ---------------------------------------------------------------------------
+
+/**
+ * Return value of `usePluginData(key, params)`.
+ *
+ * Mirrors a standard async data-fetching hook pattern:
+ * exactly one of `data` or `error` is non-null at any time (unless `loading`).
+ *
+ * @template T The type of the data returned by the worker handler
+ *
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+export interface PluginDataResult<T = unknown> {
+ /** The data returned by the worker's `getData` handler. `null` while loading or on error. */
+ data: T | null;
+ /** `true` while the initial request or a refresh is in flight. */
+ loading: boolean;
+ /** Bridge error if the request failed. `null` on success or while loading. */
+ error: PluginBridgeError | null;
+ /**
+ * Manually trigger a data refresh.
+ * Useful for poll-based updates or post-action refreshes.
+ */
+ refresh(): void;
+}
+
+// ---------------------------------------------------------------------------
+// usePluginAction hook return type
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// usePluginStream hook return type
+// ---------------------------------------------------------------------------
+
+/**
+ * Return value of `usePluginStream<T>(channel)`.
+ *
+ * Provides a growing array of events pushed from the plugin worker via SSE,
+ * plus connection status metadata.
+ *
+ * @template T The type of each event emitted by the worker
+ *
+ * @see PLUGIN_SPEC.md §19.8 — Real-Time Streaming
+ */
+export interface PluginStreamResult<T = unknown> {
+ /** All events received so far, in arrival order. */
+ events: T[];
+ /** The most recently received event, or `null` if none yet. */
+ lastEvent: T | null;
+ /** `true` while the SSE connection is being established. */
+ connecting: boolean;
+ /** `true` once the SSE connection is open and receiving events. */
+ connected: boolean;
+ /** Error if the SSE connection failed or was interrupted. `null` otherwise. */
+ error: Error | null;
+ /** Close the SSE connection and stop receiving events. */
+ close(): void;
+}
+
+// ---------------------------------------------------------------------------
+// usePluginAction hook return type
+// ---------------------------------------------------------------------------
+
+/**
+ * Return value of `usePluginAction(key)`.
+ *
+ * Returns an async function that, when called, sends an action request
+ * to the worker's `performAction` handler and returns the result.
+ *
+ * On failure, the async function throws a `PluginBridgeError`.
+ *
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ *
+ * @example
+ * ```tsx
+ * const resync = usePluginAction("resync");
+ * <button onClick={() => resync({ companyId }).catch(err => console.error(err))}>
+ * Resync Now
+ * </button>
+ * ```
+ */
+export type PluginActionFn = (params?: Record<string, unknown>) => Promise<unknown>;
diff --git a/packages/plugins/sdk/src/worker-rpc-host.ts b/packages/plugins/sdk/src/worker-rpc-host.ts
new file mode 100644
index 0000000000..05e5f3b5da
--- /dev/null
+++ b/packages/plugins/sdk/src/worker-rpc-host.ts
@@ -0,0 +1,1221 @@
+/**
+ * Worker-side RPC host — runs inside the child process spawned by the host.
+ *
+ * This module is the worker-side counterpart to the server's
+ * `PluginWorkerManager`. It:
+ *
+ * 1. Reads newline-delimited JSON-RPC 2.0 requests from **stdin**
+ * 2. Dispatches them to the appropriate plugin handler (events, jobs, tools, …)
+ * 3. Writes JSON-RPC 2.0 responses back on **stdout**
+ * 4. Provides a concrete `PluginContext` whose SDK client methods (e.g.
+ * `ctx.state.get()`, `ctx.events.emit()`) send JSON-RPC requests to the
+ * host on stdout and await responses on stdin.
+ *
+ * ## Message flow
+ *
+ * ```
+ * Host (parent) Worker (this module)
+ * | |
+ * |--- request(initialize) -------------> | → calls plugin.setup(ctx)
+ * |<-- response(ok:true) ---------------- |
+ * | |
+ * |--- request(onEvent) ----------------> | → dispatches to registered handler
+ * |<-- response(void) ------------------ |
+ * | |
+ * |<-- request(state.get) --------------- | ← SDK client call from plugin code
+ * |--- response(result) ----------------> |
+ * | |
+ * |--- request(shutdown) ---------------> | → calls plugin.onShutdown()
+ * |<-- response(void) ------------------ |
+ * | (process exits)
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §12 — Process Model
+ * @see PLUGIN_SPEC.md §13 — Host-Worker Protocol
+ * @see PLUGIN_SPEC.md §14 — SDK Surface
+ */
+
+import path from "node:path";
+import { createInterface, type Interface as ReadlineInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+
+import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";
+
+import type { PaperclipPlugin } from "./define-plugin.js";
+import type {
+ PluginHealthDiagnostics,
+ PluginConfigValidationResult,
+ PluginWebhookInput,
+} from "./define-plugin.js";
+import type {
+ PluginContext,
+ PluginEvent,
+ PluginJobContext,
+ PluginLauncherRegistration,
+ ScopeKey,
+ ToolRunContext,
+ ToolResult,
+ EventFilter,
+ AgentSessionEvent,
+} from "./types.js";
+import type {
+ JsonRpcId,
+ JsonRpcRequest,
+ JsonRpcResponse,
+ InitializeParams,
+ InitializeResult,
+ ConfigChangedParams,
+ ValidateConfigParams,
+ OnEventParams,
+ RunJobParams,
+ GetDataParams,
+ PerformActionParams,
+ ExecuteToolParams,
+ WorkerToHostMethodName,
+ WorkerToHostMethods,
+} from "./protocol.js";
+import {
+ JSONRPC_VERSION,
+ JSONRPC_ERROR_CODES,
+ PLUGIN_RPC_ERROR_CODES,
+ createRequest,
+ createSuccessResponse,
+ createErrorResponse,
+ createNotification,
+ parseMessage,
+ serializeMessage,
+ isJsonRpcRequest,
+ isJsonRpcResponse,
+ isJsonRpcNotification,
+ isJsonRpcSuccessResponse,
+ isJsonRpcErrorResponse,
+ JsonRpcParseError,
+ JsonRpcCallError,
+} from "./protocol.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for starting the worker-side RPC host.
+ */
+export interface WorkerRpcHostOptions {
+ /**
+ * The plugin definition returned by `definePlugin()`.
+ *
+ * The worker entrypoint should import its plugin and pass it here.
+ */
+ plugin: PaperclipPlugin;
+
+ /**
+ * Input stream to read JSON-RPC messages from.
+ * Defaults to `process.stdin`.
+ */
+ stdin?: NodeJS.ReadableStream;
+
+ /**
+ * Output stream to write JSON-RPC messages to.
+ * Defaults to `process.stdout`.
+ */
+ stdout?: NodeJS.WritableStream;
+
+ /**
+ * Default timeout (ms) for worker→host RPC calls.
+ * Defaults to 30 000 ms.
+ */
+ rpcTimeoutMs?: number;
+}
+
+/**
+ * A running worker RPC host instance.
+ *
+ * Returned by `startWorkerRpcHost()`. Callers (usually just the worker
+ * bootstrap) hold a reference so they can inspect status or force-stop.
+ */
+export interface WorkerRpcHost {
+ /** Whether the host is currently running and listening for messages. */
+ readonly running: boolean;
+
+ /**
+ * Stop the RPC host immediately. Closes readline, rejects pending
+ * outbound calls, and does NOT call the plugin's shutdown hook (that
+ * should have already been called via the `shutdown` RPC method).
+ */
+ stop(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Internal: event registration
+// ---------------------------------------------------------------------------
+
+interface EventRegistration {
+ name: string;
+ filter?: EventFilter;
+ fn: (event: PluginEvent) => Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default timeout for worker→host RPC calls. */
+const DEFAULT_RPC_TIMEOUT_MS = 30_000;
+
+// ---------------------------------------------------------------------------
+// startWorkerRpcHost
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for runWorker when testing (optional stdio to avoid using process streams).
+ * When both stdin and stdout are provided, the "is main module" check is skipped
+ * and the host is started with these streams. Used by tests.
+ */
+export interface RunWorkerOptions {
+ stdin?: NodeJS.ReadableStream;
+ stdout?: NodeJS.WritableStream;
+}
+
+/**
+ * Start the worker when this module is the process entrypoint.
+ *
+ * Call this at the bottom of your worker file so that when the host runs
+ * `node dist/worker.js`, the RPC host starts and the process stays alive.
+ * When the module is imported (e.g. for re-exports or tests), nothing runs.
+ *
+ * When `options.stdin` and `options.stdout` are provided (e.g. in tests),
+ * the main-module check is skipped and the host is started with those streams.
+ *
+ * @example
+ * ```ts
+ * const plugin = definePlugin({ ... });
+ * export default plugin;
+ * runWorker(plugin, import.meta.url);
+ * ```
+ */
+export function runWorker(
+ plugin: PaperclipPlugin,
+ moduleUrl: string,
+ options?: RunWorkerOptions,
+): WorkerRpcHost | void {
+ if (
+ options?.stdin != null &&
+ options?.stdout != null
+ ) {
+ return startWorkerRpcHost({
+ plugin,
+ stdin: options.stdin,
+ stdout: options.stdout,
+ });
+ }
+ const entry = process.argv[1];
+ if (typeof entry !== "string") return;
+ const thisFile = path.resolve(fileURLToPath(moduleUrl));
+ const entryPath = path.resolve(entry);
+ if (thisFile === entryPath) {
+ startWorkerRpcHost({ plugin });
+ }
+}
+
+/**
+ * Start the worker-side RPC host.
+ *
+ * This function is typically called from a thin bootstrap script that is the
+ * actual entrypoint of the child process:
+ *
+ * ```ts
+ * // worker-bootstrap.ts
+ * import plugin from "./worker.js";
+ * import { startWorkerRpcHost } from "@paperclipai/plugin-sdk";
+ *
+ * startWorkerRpcHost({ plugin });
+ * ```
+ *
+ * The host begins listening on stdin immediately. It does NOT call
+ * `plugin.definition.setup()` yet — that happens when the host sends the
+ * `initialize` RPC.
+ *
+ * @returns A handle for inspecting or stopping the RPC host
+ */
+export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost {
+ const { plugin } = options;
+ const stdinStream = options.stdin ?? process.stdin;
+ const stdoutStream = options.stdout ?? process.stdout;
+ const rpcTimeoutMs = options.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS;
+
+ // -----------------------------------------------------------------------
+ // State
+ // -----------------------------------------------------------------------
+
+ let running = true;
+ let initialized = false;
+ let manifest: PaperclipPluginManifestV1 | null = null;
+ let currentConfig: Record<string, unknown> = {};
+
+ // Plugin handler registrations (populated during setup())
+ const eventHandlers: EventRegistration[] = [];
+ const jobHandlers = new Map<string, (job: PluginJobContext) => Promise<void>>();
+ const launcherRegistrations = new Map<string, PluginLauncherRegistration>();
+ const dataHandlers = new Map<string, (params: Record<string, unknown>) => Promise<unknown>>();
+ const actionHandlers = new Map<string, (params: Record<string, unknown>) => Promise<unknown>>();
+ const toolHandlers = new Map<string, {
+ declaration: Pick<import("@paperclipai/shared").PluginToolDeclaration, "displayName" | "description" | "parametersSchema">;
+ fn: (params: unknown, runCtx: ToolRunContext) => Promise<ToolResult>;
+ }>();
+
+ // Agent session event callbacks (populated by sendMessage, cleared by close)
+ const sessionEventCallbacks = new Map<string, (event: AgentSessionEvent) => void>();
+
+ // Pending outbound (worker→host) requests
+ const pendingRequests = new Map<string | number, {
+ resolve: (response: JsonRpcResponse) => void;
+ timer: ReturnType<typeof setTimeout>;
+ }>();
+ let nextOutboundId = 1;
+ const MAX_OUTBOUND_ID = Number.MAX_SAFE_INTEGER - 1;
+
+ // -----------------------------------------------------------------------
+ // Outbound messaging (worker → host)
+ // -----------------------------------------------------------------------
+
+ function sendMessage(message: unknown): void {
+ if (!running) return;
+ const serialized = serializeMessage(message as any);
+ stdoutStream.write(serialized);
+ }
+
+ /**
+ * Send a typed JSON-RPC request to the host and await the response.
+ */
+ function callHost<M extends WorkerToHostMethodName>(
+ method: M,
+ params: WorkerToHostMethods[M][0],
+ timeoutMs?: number,
+ ): Promise<WorkerToHostMethods[M][1]> {
+ return new Promise<WorkerToHostMethods[M][1]>((resolve, reject) => {
+ if (!running) {
+ reject(new Error(`Cannot call "${method}" — worker RPC host is not running`));
+ return;
+ }
+
+ if (nextOutboundId >= MAX_OUTBOUND_ID) {
+ nextOutboundId = 1;
+ }
+ const id = nextOutboundId++;
+ const timeout = timeoutMs ?? rpcTimeoutMs;
+ let settled = false;
+
+ const settle = <T>(fn: (value: T) => void, value: T): void => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ pendingRequests.delete(id);
+ fn(value);
+ };
+
+ const timer = setTimeout(() => {
+ settle(
+ reject,
+ new JsonRpcCallError({
+ code: PLUGIN_RPC_ERROR_CODES.TIMEOUT,
+ message: `Worker→host call "${method}" timed out after ${timeout}ms`,
+ }),
+ );
+ }, timeout);
+
+ pendingRequests.set(id, {
+ resolve: (response: JsonRpcResponse) => {
+ if (isJsonRpcSuccessResponse(response)) {
+ settle(resolve, response.result as WorkerToHostMethods[M][1]);
+ } else if (isJsonRpcErrorResponse(response)) {
+ settle(reject, new JsonRpcCallError(response.error));
+ } else {
+ settle(reject, new Error(`Unexpected response format for "${method}"`));
+ }
+ },
+ timer,
+ });
+
+ try {
+ const request = createRequest(method, params, id);
+ sendMessage(request);
+ } catch (err) {
+ settle(reject, err instanceof Error ? err : new Error(String(err)));
+ }
+ });
+ }
+
+ /**
+ * Send a JSON-RPC notification to the host (fire-and-forget).
+ */
+ function notifyHost(method: string, params: unknown): void {
+ try {
+ sendMessage(createNotification(method, params));
+ } catch {
+ // Swallow — the host may have closed stdin
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ // Build the PluginContext (SDK surface for plugin code)
+ // -----------------------------------------------------------------------
+
+ function buildContext(): PluginContext {
+ return {
+ get manifest() {
+ if (!manifest) throw new Error("Plugin context accessed before initialization");
+ return manifest;
+ },
+
+ config: {
+ async get() {
+ return callHost("config.get", {} as Record<string, never>);
+ },
+ },
+
+ events: {
+ on(
+ name: string,
+ filterOrFn: EventFilter | ((event: PluginEvent) => Promise<void>),
+ maybeFn?: (event: PluginEvent) => Promise<void>,
+ ): () => void {
+ let registration: EventRegistration;
+ if (typeof filterOrFn === "function") {
+ registration = { name, fn: filterOrFn };
+ } else {
+ if (!maybeFn) throw new Error("Event handler function is required");
+ registration = { name, filter: filterOrFn, fn: maybeFn };
+ }
+ eventHandlers.push(registration);
+ return () => {
+ const idx = eventHandlers.indexOf(registration);
+ if (idx !== -1) eventHandlers.splice(idx, 1);
+ };
+ },
+
+ async emit(name: string, companyId: string, payload: unknown): Promise<void> {
+ await callHost("events.emit", { name, companyId, payload });
+ },
+ },
+
+ jobs: {
+ register(key: string, fn: (job: PluginJobContext) => Promise<void>): void {
+ jobHandlers.set(key, fn);
+ },
+ },
+
+ launchers: {
+ register(launcher: PluginLauncherRegistration): void {
+ launcherRegistrations.set(launcher.id, launcher);
+ },
+ },
+
+ http: {
+ async fetch(url: string, init?: RequestInit): Promise<Response> {
+ const serializedInit: Record<string, unknown> = {};
+ if (init) {
+ if (init.method) serializedInit.method = init.method;
+ if (init.headers) {
+ // Normalize headers to a plain object
+ if (init.headers instanceof Headers) {
+ const obj: Record<string, string> = {};
+ init.headers.forEach((v, k) => { obj[k] = v; });
+ serializedInit.headers = obj;
+ } else if (Array.isArray(init.headers)) {
+ const obj: Record<string, string> = {};
+ for (const [k, v] of init.headers) obj[k] = v;
+ serializedInit.headers = obj;
+ } else {
+ serializedInit.headers = init.headers;
+ }
+ }
+ if (init.body !== undefined && init.body !== null) {
+ serializedInit.body = typeof init.body === "string"
+ ? init.body
+ : String(init.body);
+ }
+ }
+
+ const result = await callHost("http.fetch", {
+ url,
+ init: Object.keys(serializedInit).length > 0 ? serializedInit : undefined,
+ });
+
+ // Reconstruct a Response-like object from the serialized result
+ return new Response(result.body, {
+ status: result.status,
+ statusText: result.statusText,
+ headers: result.headers,
+ });
+ },
+ },
+
+ secrets: {
+ async resolve(secretRef: string): Promise<string> {
+ return callHost("secrets.resolve", { secretRef });
+ },
+ },
+
+ assets: {
+ async upload(
+ filename: string,
+ contentType: string,
+ data: Buffer | Uint8Array,
+ ): Promise<{ assetId: string; url: string }> {
+ // Base64-encode binary data for JSON serialization
+ const base64 = Buffer.from(data).toString("base64");
+ return callHost("assets.upload", {
+ filename,
+ contentType,
+ data: base64,
+ });
+ },
+
+ async getUrl(assetId: string): Promise<string> {
+ return callHost("assets.getUrl", { assetId });
+ },
+ },
+
+ activity: {
+ async log(entry): Promise<void> {
+ await callHost("activity.log", {
+ companyId: entry.companyId,
+ message: entry.message,
+ entityType: entry.entityType,
+ entityId: entry.entityId,
+ metadata: entry.metadata,
+ });
+ },
+ },
+
+ state: {
+ async get(input: ScopeKey): Promise<unknown> {
+ return callHost("state.get", {
+ scopeKind: input.scopeKind,
+ scopeId: input.scopeId,
+ namespace: input.namespace,
+ stateKey: input.stateKey,
+ });
+ },
+
+ async set(input: ScopeKey, value: unknown): Promise<void> {
+ await callHost("state.set", {
+ scopeKind: input.scopeKind,
+ scopeId: input.scopeId,
+ namespace: input.namespace,
+ stateKey: input.stateKey,
+ value,
+ });
+ },
+
+ async delete(input: ScopeKey): Promise<void> {
+ await callHost("state.delete", {
+ scopeKind: input.scopeKind,
+ scopeId: input.scopeId,
+ namespace: input.namespace,
+ stateKey: input.stateKey,
+ });
+ },
+ },
+
+ entities: {
+ async upsert(input) {
+ return callHost("entities.upsert", {
+ entityType: input.entityType,
+ scopeKind: input.scopeKind,
+ scopeId: input.scopeId,
+ externalId: input.externalId,
+ title: input.title,
+ status: input.status,
+ data: input.data,
+ });
+ },
+
+ async list(query) {
+ return callHost("entities.list", {
+ entityType: query.entityType,
+ scopeKind: query.scopeKind,
+ scopeId: query.scopeId,
+ externalId: query.externalId,
+ limit: query.limit,
+ offset: query.offset,
+ });
+ },
+ },
+
+ projects: {
+ async list(input) {
+ return callHost("projects.list", {
+ companyId: input.companyId,
+ limit: input.limit,
+ offset: input.offset,
+ });
+ },
+
+ async get(projectId: string, companyId: string) {
+ return callHost("projects.get", { projectId, companyId });
+ },
+
+ async listWorkspaces(projectId: string, companyId: string) {
+ return callHost("projects.listWorkspaces", { projectId, companyId });
+ },
+
+ async getPrimaryWorkspace(projectId: string, companyId: string) {
+ return callHost("projects.getPrimaryWorkspace", { projectId, companyId });
+ },
+
+ async getWorkspaceForIssue(issueId: string, companyId: string) {
+ return callHost("projects.getWorkspaceForIssue", { issueId, companyId });
+ },
+ },
+
+ companies: {
+ async list(input) {
+ return callHost("companies.list", {
+ limit: input?.limit,
+ offset: input?.offset,
+ });
+ },
+
+ async get(companyId: string) {
+ return callHost("companies.get", { companyId });
+ },
+ },
+
+ issues: {
+ async list(input) {
+ return callHost("issues.list", {
+ companyId: input.companyId,
+ projectId: input.projectId,
+ assigneeAgentId: input.assigneeAgentId,
+ status: input.status,
+ limit: input.limit,
+ offset: input.offset,
+ });
+ },
+
+ async get(issueId: string, companyId: string) {
+ return callHost("issues.get", { issueId, companyId });
+ },
+
+ async create(input) {
+ return callHost("issues.create", {
+ companyId: input.companyId,
+ projectId: input.projectId,
+ goalId: input.goalId,
+ parentId: input.parentId,
+ title: input.title,
+ description: input.description,
+ priority: input.priority,
+ assigneeAgentId: input.assigneeAgentId,
+ });
+ },
+
+ async update(issueId: string, patch, companyId: string) {
+ return callHost("issues.update", {
+ issueId,
+ patch: patch as Record<string, unknown>,
+ companyId,
+ });
+ },
+
+ async listComments(issueId: string, companyId: string) {
+ return callHost("issues.listComments", { issueId, companyId });
+ },
+
+ async createComment(issueId: string, body: string, companyId: string) {
+ return callHost("issues.createComment", { issueId, body, companyId });
+ },
+ },
+
+ agents: {
+ async list(input) {
+ return callHost("agents.list", {
+ companyId: input.companyId,
+ status: input.status,
+ limit: input.limit,
+ offset: input.offset,
+ });
+ },
+
+ async get(agentId: string, companyId: string) {
+ return callHost("agents.get", { agentId, companyId });
+ },
+
+ async pause(agentId: string, companyId: string) {
+ return callHost("agents.pause", { agentId, companyId });
+ },
+
+ async resume(agentId: string, companyId: string) {
+ return callHost("agents.resume", { agentId, companyId });
+ },
+
+ async invoke(agentId: string, companyId: string, opts: { prompt: string; reason?: string }) {
+ return callHost("agents.invoke", { agentId, companyId, prompt: opts.prompt, reason: opts.reason });
+ },
+
+ sessions: {
+ async create(agentId: string, companyId: string, opts?: { taskKey?: string; reason?: string }) {
+ return callHost("agents.sessions.create", {
+ agentId,
+ companyId,
+ taskKey: opts?.taskKey,
+ reason: opts?.reason,
+ });
+ },
+
+ async list(agentId: string, companyId: string) {
+ return callHost("agents.sessions.list", { agentId, companyId });
+ },
+
+ async sendMessage(sessionId: string, companyId: string, opts: {
+ prompt: string;
+ reason?: string;
+ onEvent?: (event: AgentSessionEvent) => void;
+ }) {
+ if (opts.onEvent) {
+ sessionEventCallbacks.set(sessionId, opts.onEvent);
+ }
+ try {
+ return await callHost("agents.sessions.sendMessage", {
+ sessionId,
+ companyId,
+ prompt: opts.prompt,
+ reason: opts.reason,
+ });
+ } catch (err) {
+ sessionEventCallbacks.delete(sessionId);
+ throw err;
+ }
+ },
+
+ async close(sessionId: string, companyId: string) {
+ sessionEventCallbacks.delete(sessionId);
+ await callHost("agents.sessions.close", { sessionId, companyId });
+ },
+ },
+ },
+
+ goals: {
+ async list(input) {
+ return callHost("goals.list", {
+ companyId: input.companyId,
+ level: input.level,
+ status: input.status,
+ limit: input.limit,
+ offset: input.offset,
+ });
+ },
+
+ async get(goalId: string, companyId: string) {
+ return callHost("goals.get", { goalId, companyId });
+ },
+
+ async create(input) {
+ return callHost("goals.create", {
+ companyId: input.companyId,
+ title: input.title,
+ description: input.description,
+ level: input.level,
+ status: input.status,
+ parentId: input.parentId,
+ ownerAgentId: input.ownerAgentId,
+ });
+ },
+
+ async update(goalId: string, patch, companyId: string) {
+ return callHost("goals.update", {
+ goalId,
+ patch: patch as Record<string, unknown>,
+ companyId,
+ });
+ },
+ },
+
+ data: {
+ register(key: string, handler: (params: Record<string, unknown>) => Promise<unknown>): void {
+ dataHandlers.set(key, handler);
+ },
+ },
+
+ actions: {
+ register(key: string, handler: (params: Record<string, unknown>) => Promise<unknown>): void {
+ actionHandlers.set(key, handler);
+ },
+ },
+
+ streams: (() => {
+ // Track channel → companyId so emit/close don't require companyId
+ const channelCompanyMap = new Map<string, string>();
+ return {
+ open(channel: string, companyId: string): void {
+ channelCompanyMap.set(channel, companyId);
+ notifyHost("streams.open", { channel, companyId });
+ },
+ emit(channel: string, event: unknown): void {
+ const companyId = channelCompanyMap.get(channel) ?? "";
+ notifyHost("streams.emit", { channel, companyId, event });
+ },
+ close(channel: string): void {
+ const companyId = channelCompanyMap.get(channel) ?? "";
+ channelCompanyMap.delete(channel);
+ notifyHost("streams.close", { channel, companyId });
+ },
+ };
+ })(),
+
+ tools: {
+ register(
+ name: string,
+ declaration: Pick<import("@paperclipai/shared").PluginToolDeclaration, "displayName" | "description" | "parametersSchema">,
+ fn: (params: unknown, runCtx: ToolRunContext) => Promise<ToolResult>,
+ ): void {
+ toolHandlers.set(name, { declaration, fn });
+ },
+ },
+
+ metrics: {
+ async write(name: string, value: number, tags?: Record<string, string>): Promise<void> {
+ await callHost("metrics.write", { name, value, tags });
+ },
+ },
+
+ logger: {
+ info(message: string, meta?: Record<string, unknown>): void {
+ notifyHost("log", { level: "info", message, meta });
+ },
+ warn(message: string, meta?: Record<string, unknown>): void {
+ notifyHost("log", { level: "warn", message, meta });
+ },
+ error(message: string, meta?: Record<string, unknown>): void {
+ notifyHost("log", { level: "error", message, meta });
+ },
+ debug(message: string, meta?: Record<string, unknown>): void {
+ notifyHost("log", { level: "debug", message, meta });
+ },
+ },
+ };
+ }
+
+ const ctx = buildContext();
+
+ // -----------------------------------------------------------------------
+ // Inbound message handling (host → worker)
+ // -----------------------------------------------------------------------
+
+ /**
+ * Handle an incoming JSON-RPC request from the host.
+ *
+ * Dispatches to the correct handler based on the method name.
+ */
+ async function handleHostRequest(request: JsonRpcRequest): Promise<void> {
+ const { id, method, params } = request;
+
+ try {
+ const result = await dispatchMethod(method, params);
+ sendMessage(createSuccessResponse(id, result ?? null));
+ } catch (err) {
+ const errorMessage = err instanceof Error ? err.message : String(err);
+ // Propagate specific error codes from handler errors (e.g.
+ // METHOD_NOT_FOUND, METHOD_NOT_IMPLEMENTED) — fall back to
+ // WORKER_ERROR for untyped exceptions.
+ const errorCode =
+ typeof (err as any)?.code === "number"
+ ? (err as any).code
+ : PLUGIN_RPC_ERROR_CODES.WORKER_ERROR;
+
+ sendMessage(createErrorResponse(id, errorCode, errorMessage));
+ }
+ }
+
+ /**
+ * Dispatch a host→worker method call to the appropriate handler.
+ */
+ async function dispatchMethod(method: string, params: unknown): Promise<unknown> {
+ switch (method) {
+ case "initialize":
+ return handleInitialize(params as InitializeParams);
+
+ case "health":
+ return handleHealth();
+
+ case "shutdown":
+ return handleShutdown();
+
+ case "validateConfig":
+ return handleValidateConfig(params as ValidateConfigParams);
+
+ case "configChanged":
+ return handleConfigChanged(params as ConfigChangedParams);
+
+ case "onEvent":
+ return handleOnEvent(params as OnEventParams);
+
+ case "runJob":
+ return handleRunJob(params as RunJobParams);
+
+ case "handleWebhook":
+ return handleWebhook(params as PluginWebhookInput);
+
+ case "getData":
+ return handleGetData(params as GetDataParams);
+
+ case "performAction":
+ return handlePerformAction(params as PerformActionParams);
+
+ case "executeTool":
+ return handleExecuteTool(params as ExecuteToolParams);
+
+ default:
+ throw Object.assign(
+ new Error(`Unknown method: ${method}`),
+ { code: JSONRPC_ERROR_CODES.METHOD_NOT_FOUND },
+ );
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ // Host→Worker method handlers
+ // -----------------------------------------------------------------------
+
+ async function handleInitialize(params: InitializeParams): Promise<InitializeResult> {
+ if (initialized) {
+ throw new Error("Worker already initialized");
+ }
+
+ manifest = params.manifest;
+ currentConfig = params.config;
+
+ // Call the plugin's setup function
+ await plugin.definition.setup(ctx);
+
+ initialized = true;
+
+ // Report which optional methods this plugin implements
+ const supportedMethods: string[] = [];
+ if (plugin.definition.onValidateConfig) supportedMethods.push("validateConfig");
+ if (plugin.definition.onConfigChanged) supportedMethods.push("configChanged");
+ if (plugin.definition.onHealth) supportedMethods.push("health");
+ if (plugin.definition.onShutdown) supportedMethods.push("shutdown");
+
+ return { ok: true, supportedMethods };
+ }
+
+ async function handleHealth(): Promise<PluginHealthDiagnostics> {
+ if (plugin.definition.onHealth) {
+ return plugin.definition.onHealth();
+ }
+ // Default: report OK if the worker is alive
+ return { status: "ok" };
+ }
+
+ async function handleShutdown(): Promise<void> {
+ if (plugin.definition.onShutdown) {
+ await plugin.definition.onShutdown();
+ }
+
+ // Schedule cleanup after we send the response.
+ // Use setImmediate to let the response flush before exiting.
+ // Only call process.exit() when running with real process streams.
+ // When custom streams are provided (tests), just clean up.
+ setImmediate(() => {
+ cleanup();
+ if (!options.stdin && !options.stdout) {
+ process.exit(0);
+ }
+ });
+ }
+
+ async function handleValidateConfig(
+ params: ValidateConfigParams,
+ ): Promise<PluginConfigValidationResult> {
+ if (!plugin.definition.onValidateConfig) {
+ throw Object.assign(
+ new Error("validateConfig is not implemented by this plugin"),
+ { code: PLUGIN_RPC_ERROR_CODES.METHOD_NOT_IMPLEMENTED },
+ );
+ }
+ return plugin.definition.onValidateConfig(params.config);
+ }
+
+ async function handleConfigChanged(params: ConfigChangedParams): Promise<void> {
+ currentConfig = params.config;
+
+ if (plugin.definition.onConfigChanged) {
+ await plugin.definition.onConfigChanged(params.config);
+ }
+ }
+
+ async function handleOnEvent(params: OnEventParams): Promise<void> {
+ const event = params.event;
+
+ for (const registration of eventHandlers) {
+ // Check event type match
+ const exactMatch = registration.name === event.eventType;
+ const wildcardPluginAll =
+ registration.name === "plugin.*" &&
+ event.eventType.startsWith("plugin.");
+ const wildcardPluginOne =
+ registration.name.endsWith(".*") &&
+ event.eventType.startsWith(registration.name.slice(0, -1));
+
+ if (!exactMatch && !wildcardPluginAll && !wildcardPluginOne) continue;
+
+ // Check filter
+ if (registration.filter && !allowsEvent(registration.filter, event)) continue;
+
+ try {
+ await registration.fn(event);
+ } catch (err) {
+ // Log error but continue processing other handlers so one failing
+ // handler doesn't prevent the rest from running.
+ notifyHost("log", {
+ level: "error",
+ message: `Event handler for "${registration.name}" failed: ${
+ err instanceof Error ? err.message : String(err)
+ }`,
+ meta: { eventType: event.eventType, stack: err instanceof Error ? err.stack : undefined },
+ });
+ }
+ }
+ }
+
+ async function handleRunJob(params: RunJobParams): Promise<void> {
+ const handler = jobHandlers.get(params.job.jobKey);
+ if (!handler) {
+ throw new Error(`No handler registered for job "${params.job.jobKey}"`);
+ }
+ await handler(params.job);
+ }
+
+ async function handleWebhook(params: PluginWebhookInput): Promise<void> {
+ if (!plugin.definition.onWebhook) {
+ throw Object.assign(
+ new Error("handleWebhook is not implemented by this plugin"),
+ { code: PLUGIN_RPC_ERROR_CODES.METHOD_NOT_IMPLEMENTED },
+ );
+ }
+ await plugin.definition.onWebhook(params);
+ }
+
+ async function handleGetData(params: GetDataParams): Promise<unknown> {
+ const handler = dataHandlers.get(params.key);
+ if (!handler) {
+ throw new Error(`No data handler registered for key "${params.key}"`);
+ }
+ return handler(
+ params.renderEnvironment === undefined
+ ? params.params
+ : { ...params.params, renderEnvironment: params.renderEnvironment },
+ );
+ }
+
+ async function handlePerformAction(params: PerformActionParams): Promise<unknown> {
+ const handler = actionHandlers.get(params.key);
+ if (!handler) {
+ throw new Error(`No action handler registered for key "${params.key}"`);
+ }
+ return handler(
+ params.renderEnvironment === undefined
+ ? params.params
+ : { ...params.params, renderEnvironment: params.renderEnvironment },
+ );
+ }
+
+ async function handleExecuteTool(params: ExecuteToolParams): Promise<ToolResult> {
+ const entry = toolHandlers.get(params.toolName);
+ if (!entry) {
+ throw new Error(`No tool handler registered for "${params.toolName}"`);
+ }
+ return entry.fn(params.parameters, params.runContext);
+ }
+
+ // -----------------------------------------------------------------------
+ // Event filter helper
+ // -----------------------------------------------------------------------
+
+ function allowsEvent(filter: EventFilter, event: PluginEvent): boolean {
+ const payload = event.payload as Record<string, unknown> | undefined;
+
+ if (filter.companyId !== undefined) {
+ const companyId = event.companyId ?? String(payload?.companyId ?? "");
+ if (companyId !== filter.companyId) return false;
+ }
+
+ if (filter.projectId !== undefined) {
+ const projectId = event.entityType === "project"
+ ? event.entityId
+ : String(payload?.projectId ?? "");
+ if (projectId !== filter.projectId) return false;
+ }
+
+ if (filter.agentId !== undefined) {
+ const agentId = event.entityType === "agent"
+ ? event.entityId
+ : String(payload?.agentId ?? "");
+ if (agentId !== filter.agentId) return false;
+ }
+
+ return true;
+ }
+
+ // -----------------------------------------------------------------------
+ // Inbound response handling (host → worker, response to our outbound call)
+ // -----------------------------------------------------------------------
+
+ function handleHostResponse(response: JsonRpcResponse): void {
+ const id = response.id;
+ if (id === null || id === undefined) return;
+
+ const pending = pendingRequests.get(id);
+ if (!pending) return;
+
+ clearTimeout(pending.timer);
+ pendingRequests.delete(id);
+ pending.resolve(response);
+ }
+
+ // -----------------------------------------------------------------------
+ // Incoming line handler
+ // -----------------------------------------------------------------------
+
+ function handleLine(line: string): void {
+ if (!line.trim()) return;
+
+ let message: unknown;
+ try {
+ message = parseMessage(line);
+ } catch (err) {
+ if (err instanceof JsonRpcParseError) {
+ // Send parse error response
+ sendMessage(
+ createErrorResponse(
+ null,
+ JSONRPC_ERROR_CODES.PARSE_ERROR,
+ `Parse error: ${err.message}`,
+ ),
+ );
+ }
+ return;
+ }
+
+ if (isJsonRpcResponse(message)) {
+ // This is a response to one of our outbound worker→host calls
+ handleHostResponse(message);
+ } else if (isJsonRpcRequest(message)) {
+ // This is a host→worker RPC call — dispatch it
+ handleHostRequest(message as JsonRpcRequest).catch((err) => {
+ // Unhandled error in the async handler — send error response
+ const errorMessage = err instanceof Error ? err.message : String(err);
+ const errorCode = (err as any)?.code ?? PLUGIN_RPC_ERROR_CODES.WORKER_ERROR;
+ try {
+ sendMessage(
+ createErrorResponse(
+ (message as JsonRpcRequest).id,
+ typeof errorCode === "number" ? errorCode : PLUGIN_RPC_ERROR_CODES.WORKER_ERROR,
+ errorMessage,
+ ),
+ );
+ } catch {
+ // Cannot send response, stdout may be closed
+ }
+ });
+ } else if (isJsonRpcNotification(message)) {
+ // Dispatch host→worker push notifications
+ const notif = message as { method: string; params?: unknown };
+ if (notif.method === "agents.sessions.event" && notif.params) {
+ const event = notif.params as AgentSessionEvent;
+ const cb = sessionEventCallbacks.get(event.sessionId);
+ if (cb) cb(event);
+ }
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ // Cleanup
+ // -----------------------------------------------------------------------
+
+ function cleanup(): void {
+ running = false;
+
+ // Close readline
+ if (readline) {
+ readline.close();
+ readline = null;
+ }
+
+ // Reject all pending outbound calls
+ for (const [id, pending] of pendingRequests) {
+ clearTimeout(pending.timer);
+ pending.resolve(
+ createErrorResponse(
+ id,
+ PLUGIN_RPC_ERROR_CODES.WORKER_UNAVAILABLE,
+ "Worker RPC host is shutting down",
+ ) as JsonRpcResponse,
+ );
+ }
+ pendingRequests.clear();
+ sessionEventCallbacks.clear();
+ }
+
+ // -----------------------------------------------------------------------
+ // Bootstrap: wire up stdin readline
+ // -----------------------------------------------------------------------
+
+ let readline: ReadlineInterface | null = createInterface({
+ input: stdinStream as NodeJS.ReadableStream,
+ crlfDelay: Infinity,
+ });
+
+ readline.on("line", handleLine);
+
+ // If stdin closes, we should exit gracefully
+ readline.on("close", () => {
+ if (running) {
+ cleanup();
+ if (!options.stdin && !options.stdout) {
+ process.exit(0);
+ }
+ }
+ });
+
+ // Handle uncaught errors in the worker process.
+ // Only install these when using the real process streams (not in tests
+ // where the caller provides custom streams).
+ if (!options.stdin && !options.stdout) {
+ process.on("uncaughtException", (err) => {
+ notifyHost("log", {
+ level: "error",
+ message: `Uncaught exception: ${err.message}`,
+ meta: { stack: err.stack },
+ });
+ // Give the notification a moment to flush, then exit
+ setTimeout(() => process.exit(1), 100);
+ });
+
+ process.on("unhandledRejection", (reason) => {
+ const message = reason instanceof Error ? reason.message : String(reason);
+ const stack = reason instanceof Error ? reason.stack : undefined;
+ notifyHost("log", {
+ level: "error",
+ message: `Unhandled rejection: ${message}`,
+ meta: { stack },
+ });
+ });
+ }
+
+ // -----------------------------------------------------------------------
+ // Return the handle
+ // -----------------------------------------------------------------------
+
+ return {
+ get running() {
+ return running;
+ },
+
+ stop() {
+ cleanup();
+ },
+ };
+}
diff --git a/packages/plugins/sdk/tsconfig.json b/packages/plugins/sdk/tsconfig.json
new file mode 100644
index 0000000000..d62ebdff94
--- /dev/null
+++ b/packages/plugins/sdk/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../../tsconfig.json",
+ "compilerOptions": {
+ "outDir": "dist",
+ "rootDir": "src",
+ "types": ["node", "react"]
+ },
+ "include": ["src"]
+}
diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.ts
index bf2d366539..9aa3a00275 100644
--- a/packages/shared/src/constants.ts
+++ b/packages/shared/src/constants.ts
@@ -26,7 +26,6 @@ export const AGENT_ADAPTER_TYPES = [
"http",
"claude_local",
"codex_local",
- "gemini_local",
"opencode_local",
"pi_local",
"cursor",
@@ -213,6 +212,9 @@ export const LIVE_EVENT_TYPES = [
"heartbeat.run.log",
"agent.status",
"activity.logged",
+ "plugin.ui.updated",
+ "plugin.worker.crashed",
+ "plugin.worker.restarted",
] as const;
export type LiveEventType = (typeof LIVE_EVENT_TYPES)[number];
@@ -246,3 +248,311 @@ export const PERMISSION_KEYS = [
"joins:approve",
] as const;
export type PermissionKey = (typeof PERMISSION_KEYS)[number];
+
+// ---------------------------------------------------------------------------
+// Plugin System — see doc/plugins/PLUGIN_SPEC.md for the full specification
+// ---------------------------------------------------------------------------
+
+/**
+ * The current version of the Plugin API contract.
+ *
+ * Increment this value whenever a breaking change is made to the plugin API
+ * so that the host can reject incompatible plugin manifests.
+ *
+ * @see PLUGIN_SPEC.md §4 — Versioning
+ */
+export const PLUGIN_API_VERSION = 1 as const;
+
+/**
+ * Lifecycle statuses for an installed plugin.
+ *
+ * State machine: installed → ready | error, ready → disabled | error | upgrade_pending | uninstalled,
+ * disabled → ready | uninstalled, error → ready | uninstalled,
+ * upgrade_pending → ready | error | uninstalled, uninstalled → installed (reinstall).
+ *
+ * @see {@link PluginStatus} — inferred union type
+ * @see PLUGIN_SPEC.md §21.3 `plugins.status`
+ */
+export const PLUGIN_STATUSES = [
+ "installed",
+ "ready",
+ "disabled",
+ "error",
+ "upgrade_pending",
+ "uninstalled",
+] as const;
+export type PluginStatus = (typeof PLUGIN_STATUSES)[number];
+
+/**
+ * Plugin classification categories. A plugin declares one or more categories
+ * in its manifest to describe its primary purpose.
+ *
+ * @see PLUGIN_SPEC.md §6.2
+ */
+export const PLUGIN_CATEGORIES = [
+ "connector",
+ "workspace",
+ "automation",
+ "ui",
+] as const;
+export type PluginCategory = (typeof PLUGIN_CATEGORIES)[number];
+
+/**
+ * Named permissions the host grants to a plugin. Plugins declare required
+ * capabilities in their manifest; the host enforces them at runtime via the
+ * plugin capability validator.
+ *
+ * Grouped into: Data Read, Data Write, Plugin State, Runtime/Integration,
+ * Agent Tools, and UI.
+ *
+ * @see PLUGIN_SPEC.md §15 — Capability Model
+ */
+export const PLUGIN_CAPABILITIES = [
+ // Data Read
+ "companies.read",
+ "projects.read",
+ "project.workspaces.read",
+ "issues.read",
+ "issue.comments.read",
+ "agents.read",
+ "goals.read",
+ "goals.create",
+ "goals.update",
+ "activity.read",
+ "costs.read",
+ // Data Write
+ "issues.create",
+ "issues.update",
+ "issue.comments.create",
+ "agents.pause",
+ "agents.resume",
+ "agents.invoke",
+ "agent.sessions.create",
+ "agent.sessions.list",
+ "agent.sessions.send",
+ "agent.sessions.close",
+ "assets.write",
+ "assets.read",
+ "activity.log.write",
+ "metrics.write",
+ // Plugin State
+ "plugin.state.read",
+ "plugin.state.write",
+ // Runtime / Integration
+ "events.subscribe",
+ "events.emit",
+ "jobs.schedule",
+ "webhooks.receive",
+ "http.outbound",
+ "secrets.read-ref",
+ // Agent Tools
+ "agent.tools.register",
+ // UI
+ "instance.settings.register",
+ "ui.sidebar.register",
+ "ui.page.register",
+ "ui.detailTab.register",
+ "ui.dashboardWidget.register",
+ "ui.commentAnnotation.register",
+ "ui.action.register",
+] as const;
+export type PluginCapability = (typeof PLUGIN_CAPABILITIES)[number];
+
+/**
+ * UI extension slot types. Each slot type corresponds to a mount point in the
+ * Paperclip UI where plugin components can be rendered.
+ *
+ * @see PLUGIN_SPEC.md §19 — UI Extension Model
+ */
+export const PLUGIN_UI_SLOT_TYPES = [
+ "page",
+ "detailTab",
+ "taskDetailView",
+ "dashboardWidget",
+ "sidebar",
+ "sidebarPanel",
+ "projectSidebarItem",
+ "toolbarButton",
+ "contextMenuItem",
+ "commentAnnotation",
+ "commentContextMenuItem",
+ "settingsPage",
+] as const;
+export type PluginUiSlotType = (typeof PLUGIN_UI_SLOT_TYPES)[number];
+
+/**
+ * Launcher placement zones describe where a plugin-owned launcher can appear
+ * in the host UI. These are intentionally aligned with current slot surfaces
+ * so manifest authors can describe launch intent without coupling to a single
+ * component implementation detail.
+ */
+export const PLUGIN_LAUNCHER_PLACEMENT_ZONES = [
+ "page",
+ "detailTab",
+ "taskDetailView",
+ "dashboardWidget",
+ "sidebar",
+ "sidebarPanel",
+ "projectSidebarItem",
+ "toolbarButton",
+ "contextMenuItem",
+ "commentAnnotation",
+ "commentContextMenuItem",
+ "settingsPage",
+] as const;
+export type PluginLauncherPlacementZone = (typeof PLUGIN_LAUNCHER_PLACEMENT_ZONES)[number];
+
+/**
+ * Launcher action kinds describe what the launcher does when activated.
+ */
+export const PLUGIN_LAUNCHER_ACTIONS = [
+ "navigate",
+ "openModal",
+ "openDrawer",
+ "openPopover",
+ "performAction",
+ "deepLink",
+] as const;
+export type PluginLauncherAction = (typeof PLUGIN_LAUNCHER_ACTIONS)[number];
+
+/**
+ * Optional size hints the host can use when rendering plugin-owned launcher
+ * destinations such as overlays, drawers, or full page handoffs.
+ */
+export const PLUGIN_LAUNCHER_BOUNDS = [
+ "inline",
+ "compact",
+ "default",
+ "wide",
+ "full",
+] as const;
+export type PluginLauncherBounds = (typeof PLUGIN_LAUNCHER_BOUNDS)[number];
+
+/**
+ * Render environments describe the container a launcher expects after it is
+ * activated. The current host may map these to concrete UI primitives.
+ */
+export const PLUGIN_LAUNCHER_RENDER_ENVIRONMENTS = [
+ "hostInline",
+ "hostOverlay",
+ "hostRoute",
+ "external",
+ "iframe",
+] as const;
+export type PluginLauncherRenderEnvironment =
+ (typeof PLUGIN_LAUNCHER_RENDER_ENVIRONMENTS)[number];
+
+/**
+ * Entity types that a `detailTab` UI slot can attach to.
+ *
+ * @see PLUGIN_SPEC.md §19.3 — Detail Tabs
+ */
+export const PLUGIN_UI_SLOT_ENTITY_TYPES = [
+ "project",
+ "issue",
+ "agent",
+ "goal",
+ "run",
+ "comment",
+] as const;
+export type PluginUiSlotEntityType = (typeof PLUGIN_UI_SLOT_ENTITY_TYPES)[number];
+
+/**
+ * Scope kinds for plugin state storage. Determines the granularity at which
+ * a plugin stores key-value state data.
+ *
+ * @see PLUGIN_SPEC.md §21.3 `plugin_state.scope_kind`
+ */
+export const PLUGIN_STATE_SCOPE_KINDS = [
+ "instance",
+ "company",
+ "project",
+ "project_workspace",
+ "agent",
+ "issue",
+ "goal",
+ "run",
+] as const;
+export type PluginStateScopeKind = (typeof PLUGIN_STATE_SCOPE_KINDS)[number];
+
+/** Statuses for a plugin's scheduled job definition. */
+export const PLUGIN_JOB_STATUSES = [
+ "active",
+ "paused",
+ "failed",
+] as const;
+export type PluginJobStatus = (typeof PLUGIN_JOB_STATUSES)[number];
+
+/** Statuses for individual job run executions. */
+export const PLUGIN_JOB_RUN_STATUSES = [
+ "pending",
+ "queued",
+ "running",
+ "succeeded",
+ "failed",
+ "cancelled",
+] as const;
+export type PluginJobRunStatus = (typeof PLUGIN_JOB_RUN_STATUSES)[number];
+
+/** What triggered a particular job run. */
+export const PLUGIN_JOB_RUN_TRIGGERS = [
+ "schedule",
+ "manual",
+ "retry",
+] as const;
+export type PluginJobRunTrigger = (typeof PLUGIN_JOB_RUN_TRIGGERS)[number];
+
+/** Statuses for inbound webhook deliveries. */
+export const PLUGIN_WEBHOOK_DELIVERY_STATUSES = [
+ "pending",
+ "success",
+ "failed",
+] as const;
+export type PluginWebhookDeliveryStatus = (typeof PLUGIN_WEBHOOK_DELIVERY_STATUSES)[number];
+
+/**
+ * Core domain event types that plugins can subscribe to via the
+ * `events.subscribe` capability.
+ *
+ * @see PLUGIN_SPEC.md §16 — Event System
+ */
+export const PLUGIN_EVENT_TYPES = [
+ "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",
+ "goal.created",
+ "goal.updated",
+ "approval.created",
+ "approval.decided",
+ "cost_event.created",
+ "activity.logged",
+] as const;
+export type PluginEventType = (typeof PLUGIN_EVENT_TYPES)[number];
+
+/**
+ * Error codes returned by the plugin bridge when a UI → worker call fails.
+ *
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+export const PLUGIN_BRIDGE_ERROR_CODES = [
+ "WORKER_UNAVAILABLE",
+ "CAPABILITY_DENIED",
+ "WORKER_ERROR",
+ "TIMEOUT",
+ "UNKNOWN",
+] as const;
+export type PluginBridgeErrorCode = (typeof PLUGIN_BRIDGE_ERROR_CODES)[number];
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 1a222f2778..9931594361 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -31,6 +31,23 @@ export {
JOIN_REQUEST_TYPES,
JOIN_REQUEST_STATUSES,
PERMISSION_KEYS,
+ PLUGIN_API_VERSION,
+ PLUGIN_STATUSES,
+ PLUGIN_CATEGORIES,
+ PLUGIN_CAPABILITIES,
+ PLUGIN_UI_SLOT_TYPES,
+ PLUGIN_UI_SLOT_ENTITY_TYPES,
+ PLUGIN_LAUNCHER_PLACEMENT_ZONES,
+ PLUGIN_LAUNCHER_ACTIONS,
+ PLUGIN_LAUNCHER_BOUNDS,
+ PLUGIN_LAUNCHER_RENDER_ENVIRONMENTS,
+ PLUGIN_STATE_SCOPE_KINDS,
+ PLUGIN_JOB_STATUSES,
+ PLUGIN_JOB_RUN_STATUSES,
+ PLUGIN_JOB_RUN_TRIGGERS,
+ PLUGIN_WEBHOOK_DELIVERY_STATUSES,
+ PLUGIN_EVENT_TYPES,
+ PLUGIN_BRIDGE_ERROR_CODES,
type CompanyStatus,
type DeploymentMode,
type DeploymentExposure,
@@ -61,6 +78,22 @@ export {
type JoinRequestType,
type JoinRequestStatus,
type PermissionKey,
+ type PluginStatus,
+ type PluginCategory,
+ type PluginCapability,
+ type PluginUiSlotType,
+ type PluginUiSlotEntityType,
+ type PluginLauncherPlacementZone,
+ type PluginLauncherAction,
+ type PluginLauncherBounds,
+ type PluginLauncherRenderEnvironment,
+ type PluginStateScopeKind,
+ type PluginJobStatus,
+ type PluginJobRunStatus,
+ type PluginJobRunTrigger,
+ type PluginWebhookDeliveryStatus,
+ type PluginEventType,
+ type PluginBridgeErrorCode,
} from "./constants.js";
export type {
@@ -129,6 +162,28 @@ export type {
AgentEnvConfig,
CompanySecret,
SecretProviderDescriptor,
+ JsonSchema,
+ PluginJobDeclaration,
+ PluginWebhookDeclaration,
+ PluginToolDeclaration,
+ PluginUiSlotDeclaration,
+ PluginLauncherActionDeclaration,
+ PluginLauncherRenderDeclaration,
+ PluginLauncherRenderContextSnapshot,
+ PluginLauncherDeclaration,
+ PluginMinimumHostVersion,
+ PluginUiDeclaration,
+ PaperclipPluginManifestV1,
+ PluginRecord,
+ PluginStateRecord,
+ PluginConfig,
+ PluginCompanySettings,
+ CompanyPluginAvailability,
+ PluginEntityRecord,
+ PluginEntityQuery,
+ PluginJobRecord,
+ PluginJobRunRecord,
+ PluginWebhookDeliveryRecord,
} from "./types/index.js";
export {
@@ -238,6 +293,45 @@ export {
type CompanyPortabilityExport,
type CompanyPortabilityPreview,
type CompanyPortabilityImport,
+ jsonSchemaSchema,
+ pluginJobDeclarationSchema,
+ pluginWebhookDeclarationSchema,
+ pluginToolDeclarationSchema,
+ pluginUiSlotDeclarationSchema,
+ pluginLauncherActionDeclarationSchema,
+ pluginLauncherRenderDeclarationSchema,
+ pluginLauncherDeclarationSchema,
+ pluginManifestV1Schema,
+ installPluginSchema,
+ upsertPluginConfigSchema,
+ patchPluginConfigSchema,
+ upsertPluginCompanySettingsSchema,
+ updateCompanyPluginAvailabilitySchema,
+ listCompanyPluginAvailabilitySchema,
+ updatePluginStatusSchema,
+ uninstallPluginSchema,
+ pluginStateScopeKeySchema,
+ setPluginStateSchema,
+ listPluginStateSchema,
+ type PluginJobDeclarationInput,
+ type PluginWebhookDeclarationInput,
+ type PluginToolDeclarationInput,
+ type PluginUiSlotDeclarationInput,
+ type PluginLauncherActionDeclarationInput,
+ type PluginLauncherRenderDeclarationInput,
+ type PluginLauncherDeclarationInput,
+ type PluginManifestV1Input,
+ type InstallPlugin,
+ type UpsertPluginConfig,
+ type PatchPluginConfig,
+ type UpsertPluginCompanySettings,
+ type UpdateCompanyPluginAvailability,
+ type ListCompanyPluginAvailability,
+ type UpdatePluginStatus,
+ type UninstallPlugin,
+ type PluginStateScopeKey,
+ type SetPluginState,
+ type ListPluginState,
} from "./validators/index.js";
export { API_PREFIX, API } from "./api.js";
diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts
index 07862c581e..7dfb0a3311 100644
--- a/packages/shared/src/types/index.ts
+++ b/packages/shared/src/types/index.ts
@@ -79,3 +79,27 @@ export type {
CompanyPortabilityImportResult,
CompanyPortabilityExportRequest,
} from "./company-portability.js";
+export type {
+ JsonSchema,
+ PluginJobDeclaration,
+ PluginWebhookDeclaration,
+ PluginToolDeclaration,
+ PluginUiSlotDeclaration,
+ PluginLauncherActionDeclaration,
+ PluginLauncherRenderDeclaration,
+ PluginLauncherRenderContextSnapshot,
+ PluginLauncherDeclaration,
+ PluginMinimumHostVersion,
+ PluginUiDeclaration,
+ PaperclipPluginManifestV1,
+ PluginRecord,
+ PluginStateRecord,
+ PluginConfig,
+ PluginCompanySettings,
+ CompanyPluginAvailability,
+ PluginEntityRecord,
+ PluginEntityQuery,
+ PluginJobRecord,
+ PluginJobRunRecord,
+ PluginWebhookDeliveryRecord,
+} from "./plugin.js";
diff --git a/packages/shared/src/types/plugin.ts b/packages/shared/src/types/plugin.ts
new file mode 100644
index 0000000000..6254a7bb7d
--- /dev/null
+++ b/packages/shared/src/types/plugin.ts
@@ -0,0 +1,545 @@
+import type {
+ PluginStatus,
+ PluginCategory,
+ PluginCapability,
+ PluginUiSlotType,
+ PluginUiSlotEntityType,
+ PluginStateScopeKind,
+ PluginLauncherPlacementZone,
+ PluginLauncherAction,
+ PluginLauncherBounds,
+ PluginLauncherRenderEnvironment,
+} from "../constants.js";
+
+// ---------------------------------------------------------------------------
+// JSON Schema placeholder – plugins declare config schemas as JSON Schema
+// ---------------------------------------------------------------------------
+
+/**
+ * A JSON Schema object used for plugin config schemas and tool parameter schemas.
+ * Plugins provide these as plain JSON Schema compatible objects.
+ */
+export type JsonSchema = Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// Manifest sub-types — nested declarations within PaperclipPluginManifestV1
+// ---------------------------------------------------------------------------
+
+/**
+ * Declares a scheduled job a plugin can run.
+ *
+ * @see PLUGIN_SPEC.md §17 — Scheduled Jobs
+ */
+export interface PluginJobDeclaration {
+ /** Stable identifier for this job, unique within the plugin. */
+ jobKey: string;
+ /** Human-readable name shown in the operator UI. */
+ displayName: string;
+ /** Optional description of what the job does. */
+ description?: string;
+ /** Cron expression for the schedule (e.g. "star/15 star star star star" or "0 * * * *"). */
+ schedule?: string;
+}
+
+/**
+ * Declares a webhook endpoint the plugin can receive.
+ * Route: `POST /api/plugins/:pluginId/webhooks/:endpointKey`
+ *
+ * @see PLUGIN_SPEC.md §18 — Webhooks
+ */
+export interface PluginWebhookDeclaration {
+ /** Stable identifier for this endpoint, unique within the plugin. */
+ endpointKey: string;
+ /** Human-readable name shown in the operator UI. */
+ displayName: string;
+ /** Optional description of what this webhook handles. */
+ description?: string;
+}
+
+/**
+ * Declares an agent tool contributed by the plugin. Tools are namespaced
+ * by plugin ID at runtime (e.g. `linear:search-issues`).
+ *
+ * Requires the `agent.tools.register` capability.
+ *
+ * @see PLUGIN_SPEC.md §11 — Agent Tools
+ */
+export interface PluginToolDeclaration {
+ /** Tool name, unique within the plugin. Namespaced by plugin ID at runtime. */
+ name: string;
+ /** Human-readable name shown to agents and in the UI. */
+ displayName: string;
+ /** Description provided to the agent so it knows when to use this tool. */
+ description: string;
+ /** JSON Schema describing the tool's input parameters. */
+ parametersSchema: JsonSchema;
+}
+
+/**
+ * Declares a UI extension slot the plugin fills with a React component.
+ *
+ * @see PLUGIN_SPEC.md §19 — UI Extension Model
+ */
+export interface PluginUiSlotDeclaration {
+ /** The type of UI mount point (page, detailTab, taskDetailView, toolbarButton, etc.). */
+ type: PluginUiSlotType;
+ /** Unique slot identifier within the plugin. */
+ id: string;
+ /** Human-readable name shown in navigation or tab labels. */
+ displayName: string;
+ /** Which export name in the UI bundle provides this component. */
+ exportName: string;
+ /**
+ * Entity targets for context-sensitive slots.
+ * Required for `detailTab`, `taskDetailView`, and `contextMenuItem`.
+ */
+ entityTypes?: PluginUiSlotEntityType[];
+ /**
+ * Optional ordering hint within a slot surface. Lower numbers appear first.
+ * Defaults to host-defined ordering if omitted.
+ */
+ order?: number;
+}
+
+/**
+ * Describes the action triggered by a plugin launcher surface.
+ */
+export interface PluginLauncherActionDeclaration {
+ /** What kind of launch behavior the host should perform. */
+ type: PluginLauncherAction;
+ /**
+ * Stable target identifier or URL. The meaning depends on `type`
+ * (for example a route, tab key, action key, or external URL).
+ */
+ target: string;
+ /** Optional arbitrary parameters passed along to the target. */
+ params?: Record<string, unknown>;
+}
+
+/**
+ * Optional render metadata for the destination opened by a launcher.
+ */
+export interface PluginLauncherRenderDeclaration {
+ /** High-level container the launcher expects the host to use. */
+ environment: PluginLauncherRenderEnvironment;
+ /** Optional size hint for the destination surface. */
+ bounds?: PluginLauncherBounds;
+}
+
+/**
+ * Serializable runtime snapshot of the host launcher/container environment.
+ */
+export interface PluginLauncherRenderContextSnapshot {
+ /** The current launcher/container environment selected by the host. */
+ environment: PluginLauncherRenderEnvironment | null;
+ /** Launcher id that opened this surface, if any. */
+ launcherId: string | null;
+ /** Current host-applied bounds hint for the environment, if any. */
+ bounds: PluginLauncherBounds | null;
+}
+
+/**
+ * Declares a plugin launcher surface independent of the low-level slot
+ * implementation that mounts it.
+ */
+export interface PluginLauncherDeclaration {
+ /** Stable identifier for this launcher, unique within the plugin. */
+ id: string;
+ /** Human-readable label shown for the launcher. */
+ displayName: string;
+ /** Optional description for operator-facing docs or future UI affordances. */
+ description?: string;
+ /** Where in the host UI this launcher should be placed. */
+ placementZone: PluginLauncherPlacementZone;
+ /** Optional export name in the UI bundle when the launcher has custom UI. */
+ exportName?: string;
+ /**
+ * Optional entity targeting for context-sensitive launcher zones.
+ * Reuses the same entity union as UI slots for consistency.
+ */
+ entityTypes?: PluginUiSlotEntityType[];
+ /** Optional ordering hint within the placement zone. */
+ order?: number;
+ /** What should happen when the launcher is activated. */
+ action: PluginLauncherActionDeclaration;
+ /** Optional render/container hints for the launched destination. */
+ render?: PluginLauncherRenderDeclaration;
+}
+
+/**
+ * Lower-bound semver requirement for the Paperclip host.
+ *
+ * The host should reject installation when its running version is lower than
+ * the declared minimum.
+ */
+export type PluginMinimumHostVersion = string;
+
+/**
+ * Groups plugin UI declarations that are served from the shared UI bundle
+ * root declared in `entrypoints.ui`.
+ */
+export interface PluginUiDeclaration {
+ /** UI extension slots this plugin fills. */
+ slots?: PluginUiSlotDeclaration[];
+ /** Declarative launcher metadata for host-mounted plugin entry points. */
+ launchers?: PluginLauncherDeclaration[];
+}
+
+// ---------------------------------------------------------------------------
+// Plugin Manifest V1
+// ---------------------------------------------------------------------------
+
+/**
+ * The manifest shape every plugin package must export.
+ * See PLUGIN_SPEC.md §10.1 for the normative definition.
+ */
+export interface PaperclipPluginManifestV1 {
+ /** Globally unique plugin identifier (e.g. `"acme.linear-sync"`). Must be lowercase alphanumeric with dots, hyphens, or underscores. */
+ id: string;
+ /** Plugin API version. Must be `1` for the current spec. */
+ apiVersion: 1;
+ /** Semver version of the plugin package (e.g. `"1.2.0"`). */
+ version: string;
+ /** Human-readable name (max 100 chars). */
+ displayName: string;
+ /** Short description (max 500 chars). */
+ description: string;
+ /** Author name (max 200 chars). May include email in angle brackets, e.g. `"Jane Doe <[email protected]>"`. */
+ author: string;
+ /** One or more categories classifying this plugin. */
+ categories: PluginCategory[];
+ /**
+ * Minimum host version required (semver lower bound).
+ * Preferred generic field for new manifests.
+ */
+ minimumHostVersion?: PluginMinimumHostVersion;
+ /**
+ * Legacy alias for `minimumHostVersion`.
+ * Kept for backwards compatibility with existing manifests and docs.
+ */
+ minimumPaperclipVersion?: PluginMinimumHostVersion;
+ /** Capabilities this plugin requires from the host. Enforced at runtime. */
+ capabilities: PluginCapability[];
+ /** Entrypoint paths relative to the package root. */
+ entrypoints: {
+ /** Path to the worker entrypoint (required). */
+ worker: string;
+ /** Path to the UI bundle directory (required when `ui.slots` is declared). */
+ ui?: string;
+ };
+ /** JSON Schema for operator-editable instance configuration. */
+ instanceConfigSchema?: JsonSchema;
+ /** Scheduled jobs this plugin declares. Requires `jobs.schedule` capability. */
+ jobs?: PluginJobDeclaration[];
+ /** Webhook endpoints this plugin declares. Requires `webhooks.receive` capability. */
+ webhooks?: PluginWebhookDeclaration[];
+ /** Agent tools this plugin contributes. Requires `agent.tools.register` capability. */
+ tools?: PluginToolDeclaration[];
+ /**
+ * Legacy top-level launcher declarations.
+ * Prefer `ui.launchers` for new manifests.
+ */
+ launchers?: PluginLauncherDeclaration[];
+ /** UI bundle declarations. Requires `entrypoints.ui` when populated. */
+ ui?: PluginUiDeclaration;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin Record – represents a row in the `plugins` table
+// ---------------------------------------------------------------------------
+
+/**
+ * Domain type for an installed plugin as persisted in the `plugins` table.
+ * See PLUGIN_SPEC.md §21.3 for the schema definition.
+ */
+export interface PluginRecord {
+ /** UUID primary key. */
+ id: string;
+ /** Unique key derived from `manifest.id`. Used for lookups. */
+ pluginKey: string;
+ /** npm package name (e.g. `"@acme/plugin-linear"`). */
+ packageName: string;
+ /** Installed semver version. */
+ version: string;
+ /** Plugin API version from the manifest. */
+ apiVersion: number;
+ /** Plugin categories from the manifest. */
+ categories: PluginCategory[];
+ /** Full manifest snapshot persisted at install/upgrade time. */
+ manifestJson: PaperclipPluginManifestV1;
+ /** Current lifecycle status. */
+ status: PluginStatus;
+ /** Deterministic load order (null if not yet assigned). */
+ installOrder: number | null;
+ /** Resolved package path for local-path installs; used to find worker entrypoint. */
+ packagePath: string | null;
+ /** Most recent error message, or operator-provided disable reason. */
+ lastError: string | null;
+ /** Timestamp when the plugin was first installed. */
+ installedAt: Date;
+ /** Timestamp of the most recent status or metadata change. */
+ updatedAt: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin State – represents a row in the `plugin_state` table
+// ---------------------------------------------------------------------------
+
+/**
+ * Domain type for a single scoped key-value entry in the `plugin_state` table.
+ * Plugins read and write these entries through `ctx.state` in the SDK.
+ *
+ * The five-part composite key `(pluginId, scopeKind, scopeId, namespace, stateKey)`
+ * uniquely identifies a state entry.
+ *
+ * @see PLUGIN_SPEC.md §21.3 — `plugin_state`
+ */
+export interface PluginStateRecord {
+ /** UUID primary key. */
+ id: string;
+ /** FK to `plugins.id`. */
+ pluginId: string;
+ /** Granularity of the scope. */
+ scopeKind: PluginStateScopeKind;
+ /**
+ * UUID or text identifier for the scoped object.
+ * `null` for `instance` scope (no associated entity).
+ */
+ scopeId: string | null;
+ /**
+ * Sub-namespace within the scope to avoid key collisions.
+ * Defaults to `"default"` if not explicitly set by the plugin.
+ */
+ namespace: string;
+ /** The key for this state entry within the namespace. */
+ stateKey: string;
+ /** Stored JSON value. May be any JSON-serializable type. */
+ valueJson: unknown;
+ /** Timestamp of the most recent write. */
+ updatedAt: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin Config – represents a row in the `plugin_config` table
+// ---------------------------------------------------------------------------
+
+/**
+ * Domain type for a plugin's instance configuration as persisted in the
+ * `plugin_config` table.
+ * See PLUGIN_SPEC.md §21.3 for the schema definition.
+ */
+export interface PluginConfig {
+ /** UUID primary key. */
+ id: string;
+ /** FK to `plugins.id`. Unique — each plugin has at most one config row. */
+ pluginId: string;
+ /** Operator-provided configuration values (validated against `instanceConfigSchema`). */
+ configJson: Record<string, unknown>;
+ /** Most recent config validation error, if any. */
+ lastError: string | null;
+ /** Timestamp when the config row was created. */
+ createdAt: Date;
+ /** Timestamp of the most recent config update. */
+ updatedAt: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Company Plugin Availability / Settings
+// ---------------------------------------------------------------------------
+
+/**
+ * Domain type for a plugin's company-scoped settings row as persisted in the
+ * `plugin_company_settings` table.
+ *
+ * This is separate from instance-wide `PluginConfig`: the plugin remains
+ * installed globally, while each company can store its own plugin settings and
+ * availability state independently.
+ */
+export interface PluginCompanySettings {
+ /** UUID primary key. */
+ id: string;
+ /** FK to `companies.id`. */
+ companyId: string;
+ /** FK to `plugins.id`. */
+ pluginId: string;
+ /** Explicit availability override for this company/plugin pair. */
+ enabled: boolean;
+ /** Company-scoped plugin settings payload. */
+ settingsJson: Record<string, unknown>;
+ /** Most recent company-scoped validation or availability error, if any. */
+ lastError: string | null;
+ /** Timestamp when the settings row was created. */
+ createdAt: Date;
+ /** Timestamp of the most recent settings update. */
+ updatedAt: Date;
+}
+
+/**
+ * API response shape describing whether a plugin is available to a specific
+ * company and, when present, the company-scoped settings row backing that
+ * availability.
+ */
+export interface CompanyPluginAvailability {
+ companyId: string;
+ pluginId: string;
+ /** Stable manifest/plugin key for display and route generation. */
+ pluginKey: string;
+ /** Human-readable plugin name. */
+ pluginDisplayName: string;
+ /** Current instance-wide plugin lifecycle status. */
+ pluginStatus: PluginStatus;
+ /**
+ * Whether the plugin is currently available to the company.
+ * When no `plugin_company_settings` row exists yet, the plugin is enabled
+ * by default for the company.
+ */
+ available: boolean;
+ /** Company-scoped settings, defaulting to an empty object when unavailable. */
+ settingsJson: Record<string, unknown>;
+ /** Most recent company-scoped error, if any. */
+ lastError: string | null;
+ /** Present when availability is backed by a persisted settings row. */
+ createdAt: Date | null;
+ /** Present when availability is backed by a persisted settings row. */
+ updatedAt: Date | null;
+}
+
+/**
+ * Query filter for `ctx.entities.list`.
+ */
+export interface PluginEntityQuery {
+ /** Optional filter by entity type (e.g. 'project', 'issue'). */
+ entityType?: string;
+ /** Optional filter by external system identifier. */
+ externalId?: string;
+ /** Maximum number of records to return. Defaults to 100. */
+ limit?: number;
+ /** Number of records to skip. Defaults to 0. */
+ offset?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin Entity – represents a row in the `plugin_entities` table
+// ---------------------------------------------------------------------------
+
+/**
+ * Domain type for an external entity mapping as persisted in the `plugin_entities` table.
+ */
+export interface PluginEntityRecord {
+ /** UUID primary key. */
+ id: string;
+ /** FK to `plugins.id`. */
+ pluginId: string;
+ /** Plugin-defined entity type. */
+ entityType: string;
+ /** Scope where this entity lives. */
+ scopeKind: PluginStateScopeKind;
+ /** UUID or text identifier for the scoped object. */
+ scopeId: string | null;
+ /** External identifier in the remote system. */
+ externalId: string | null;
+ /** Human-readable title. */
+ title: string | null;
+ /** Optional status string. */
+ status: string | null;
+ /** Full entity data blob. */
+ data: Record<string, unknown>;
+ /** ISO 8601 creation timestamp. */
+ createdAt: Date;
+ /** ISO 8601 last-updated timestamp. */
+ updatedAt: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin Job – represents a row in the `plugin_jobs` table
+// ---------------------------------------------------------------------------
+
+/**
+ * Domain type for a registered plugin job as persisted in the `plugin_jobs` table.
+ */
+export interface PluginJobRecord {
+ /** UUID primary key. */
+ id: string;
+ /** FK to `plugins.id`. */
+ pluginId: string;
+ /** Job key matching the manifest declaration. */
+ jobKey: string;
+ /** Cron expression for the schedule. */
+ schedule: string;
+ /** Current job status. */
+ status: "active" | "paused" | "failed";
+ /** Last time the job was executed. */
+ lastRunAt: Date | null;
+ /** Next scheduled execution time. */
+ nextRunAt: Date | null;
+ /** ISO 8601 creation timestamp. */
+ createdAt: Date;
+ /** ISO 8601 last-updated timestamp. */
+ updatedAt: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin Job Run – represents a row in the `plugin_job_runs` table
+// ---------------------------------------------------------------------------
+
+/**
+ * Domain type for a job execution history record.
+ */
+export interface PluginJobRunRecord {
+ /** UUID primary key. */
+ id: string;
+ /** FK to `plugin_jobs.id`. */
+ jobId: string;
+ /** FK to `plugins.id`. */
+ pluginId: string;
+ /** What triggered this run. */
+ trigger: "schedule" | "manual" | "retry";
+ /** Current run status. */
+ status: "pending" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
+ /** Run duration in milliseconds. */
+ durationMs: number | null;
+ /** Error message if the run failed. */
+ error: string | null;
+ /** Run logs. */
+ logs: string[];
+ /** ISO 8601 start timestamp. */
+ startedAt: Date | null;
+ /** ISO 8601 finish timestamp. */
+ finishedAt: Date | null;
+ /** ISO 8601 creation timestamp. */
+ createdAt: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin Webhook Delivery – represents a row in the `plugin_webhook_deliveries` table
+// ---------------------------------------------------------------------------
+
+/**
+ * Domain type for an inbound webhook delivery record.
+ */
+export interface PluginWebhookDeliveryRecord {
+ /** UUID primary key. */
+ id: string;
+ /** FK to `plugins.id`. */
+ pluginId: string;
+ /** Webhook endpoint key matching the manifest. */
+ webhookKey: string;
+ /** External identifier from the remote system. */
+ externalId: string | null;
+ /** Delivery status. */
+ status: "pending" | "success" | "failed";
+ /** Processing duration in milliseconds. */
+ durationMs: number | null;
+ /** Error message if processing failed. */
+ error: string | null;
+ /** Webhook payload. */
+ payload: Record<string, unknown>;
+ /** Webhook headers. */
+ headers: Record<string, string>;
+ /** ISO 8601 start timestamp. */
+ startedAt: Date | null;
+ /** ISO 8601 finish timestamp. */
+ finishedAt: Date | null;
+ /** ISO 8601 creation timestamp. */
+ createdAt: Date;
+}
diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.ts
index ad74a1e870..687dd1adb0 100644
--- a/packages/shared/src/validators/index.ts
+++ b/packages/shared/src/validators/index.ts
@@ -137,3 +137,45 @@ export {
type UpdateMemberPermissions,
type UpdateUserCompanyAccess,
} from "./access.js";
+
+export {
+ jsonSchemaSchema,
+ pluginJobDeclarationSchema,
+ pluginWebhookDeclarationSchema,
+ pluginToolDeclarationSchema,
+ pluginUiSlotDeclarationSchema,
+ pluginLauncherActionDeclarationSchema,
+ pluginLauncherRenderDeclarationSchema,
+ pluginLauncherDeclarationSchema,
+ pluginManifestV1Schema,
+ installPluginSchema,
+ upsertPluginConfigSchema,
+ patchPluginConfigSchema,
+ upsertPluginCompanySettingsSchema,
+ updateCompanyPluginAvailabilitySchema,
+ listCompanyPluginAvailabilitySchema,
+ updatePluginStatusSchema,
+ uninstallPluginSchema,
+ pluginStateScopeKeySchema,
+ setPluginStateSchema,
+ listPluginStateSchema,
+ type PluginJobDeclarationInput,
+ type PluginWebhookDeclarationInput,
+ type PluginToolDeclarationInput,
+ type PluginUiSlotDeclarationInput,
+ type PluginLauncherActionDeclarationInput,
+ type PluginLauncherRenderDeclarationInput,
+ type PluginLauncherDeclarationInput,
+ type PluginManifestV1Input,
+ type InstallPlugin,
+ type UpsertPluginConfig,
+ type PatchPluginConfig,
+ type UpsertPluginCompanySettings,
+ type UpdateCompanyPluginAvailability,
+ type ListCompanyPluginAvailability,
+ type UpdatePluginStatus,
+ type UninstallPlugin,
+ type PluginStateScopeKey,
+ type SetPluginState,
+ type ListPluginState,
+} from "./plugin.js";
diff --git a/packages/shared/src/validators/plugin.ts b/packages/shared/src/validators/plugin.ts
new file mode 100644
index 0000000000..be9b2d5b49
--- /dev/null
+++ b/packages/shared/src/validators/plugin.ts
@@ -0,0 +1,694 @@
+import { z } from "zod";
+import {
+ PLUGIN_STATUSES,
+ PLUGIN_CATEGORIES,
+ PLUGIN_CAPABILITIES,
+ PLUGIN_UI_SLOT_TYPES,
+ PLUGIN_UI_SLOT_ENTITY_TYPES,
+ PLUGIN_LAUNCHER_PLACEMENT_ZONES,
+ PLUGIN_LAUNCHER_ACTIONS,
+ PLUGIN_LAUNCHER_BOUNDS,
+ PLUGIN_LAUNCHER_RENDER_ENVIRONMENTS,
+ PLUGIN_STATE_SCOPE_KINDS,
+} from "../constants.js";
+
+// ---------------------------------------------------------------------------
+// JSON Schema placeholder – a permissive validator for JSON Schema objects
+// ---------------------------------------------------------------------------
+
+/**
+ * Permissive validator for JSON Schema objects. Accepts any `Record<string, unknown>`
+ * that contains at least a `type`, `$ref`, or composition keyword (`oneOf`/`anyOf`/`allOf`).
+ * Empty objects are also accepted.
+ *
+ * Used to validate `instanceConfigSchema` and `parametersSchema` fields in the
+ * plugin manifest without fully parsing JSON Schema.
+ *
+ * @see PLUGIN_SPEC.md §10.1 — Manifest shape
+ */
+export const jsonSchemaSchema = z.record(z.unknown()).refine(
+ (val) => {
+ // Must have a "type" field if non-empty, or be a valid JSON Schema object
+ if (Object.keys(val).length === 0) return true;
+ return typeof val.type === "string" || val.$ref !== undefined || val.oneOf !== undefined || val.anyOf !== undefined || val.allOf !== undefined;
+ },
+ { message: "Must be a valid JSON Schema object (requires at least a 'type', '$ref', or composition keyword)" },
+);
+
+// ---------------------------------------------------------------------------
+// Manifest sub-type schemas
+// ---------------------------------------------------------------------------
+
+/**
+ * Validates a {@link PluginJobDeclaration} — a scheduled job declared in the
+ * plugin manifest. Requires `jobKey` and `displayName`; `description` and
+ * `schedule` (cron expression) are optional.
+ *
+ * @see PLUGIN_SPEC.md §17 — Scheduled Jobs
+ */
+/**
+ * Validates a cron expression has exactly 5 whitespace-separated fields,
+ * each containing only valid cron characters (digits, *, /, -, ,).
+ *
+ * Valid tokens per field: *, N, N-M, N/S, * /S, N-M/S, and comma-separated lists.
+ */
+const CRON_FIELD_PATTERN = /^(\*(?:\/[0-9]+)?|[0-9]+(?:-[0-9]+)?(?:\/[0-9]+)?)(?:,(\*(?:\/[0-9]+)?|[0-9]+(?:-[0-9]+)?(?:\/[0-9]+)?))*$/;
+
+function isValidCronExpression(expression: string): boolean {
+ const trimmed = expression.trim();
+ if (!trimmed) return false;
+ const fields = trimmed.split(/\s+/);
+ if (fields.length !== 5) return false;
+ return fields.every((f) => CRON_FIELD_PATTERN.test(f));
+}
+
+export const pluginJobDeclarationSchema = z.object({
+ jobKey: z.string().min(1),
+ displayName: z.string().min(1),
+ description: z.string().optional(),
+ schedule: z.string().refine(
+ (val) => isValidCronExpression(val),
+ { message: "schedule must be a valid 5-field cron expression (e.g. '*/15 * * * *')" },
+ ).optional(),
+});
+
+export type PluginJobDeclarationInput = z.infer<typeof pluginJobDeclarationSchema>;
+
+/**
+ * Validates a {@link PluginWebhookDeclaration} — a webhook endpoint declared
+ * in the plugin manifest. Requires `endpointKey` and `displayName`.
+ *
+ * @see PLUGIN_SPEC.md §18 — Webhooks
+ */
+export const pluginWebhookDeclarationSchema = z.object({
+ endpointKey: z.string().min(1),
+ displayName: z.string().min(1),
+ description: z.string().optional(),
+});
+
+export type PluginWebhookDeclarationInput = z.infer<typeof pluginWebhookDeclarationSchema>;
+
+/**
+ * Validates a {@link PluginToolDeclaration} — an agent tool contributed by the
+ * plugin. Requires `name`, `displayName`, `description`, and a valid
+ * `parametersSchema`. Requires the `agent.tools.register` capability.
+ *
+ * @see PLUGIN_SPEC.md §11 — Agent Tools
+ */
+export const pluginToolDeclarationSchema = z.object({
+ name: z.string().min(1),
+ displayName: z.string().min(1),
+ description: z.string().min(1),
+ parametersSchema: jsonSchemaSchema,
+});
+
+export type PluginToolDeclarationInput = z.infer<typeof pluginToolDeclarationSchema>;
+
+/**
+ * Validates a {@link PluginUiSlotDeclaration} — a UI extension slot the plugin
+ * fills with a React component. Includes `superRefine` checks for slot-specific
+ * requirements such as `entityTypes` for context-sensitive slots.
+ *
+ * @see PLUGIN_SPEC.md §19 — UI Extension Model
+ */
+export const pluginUiSlotDeclarationSchema = z.object({
+ type: z.enum(PLUGIN_UI_SLOT_TYPES),
+ id: z.string().min(1),
+ displayName: z.string().min(1),
+ exportName: z.string().min(1),
+ entityTypes: z.array(z.enum(PLUGIN_UI_SLOT_ENTITY_TYPES)).optional(),
+ order: z.number().int().optional(),
+}).superRefine((value, ctx) => {
+ // context-sensitive slots require explicit entity targeting.
+ const entityScopedTypes = ["detailTab", "taskDetailView", "contextMenuItem", "commentAnnotation", "commentContextMenuItem", "projectSidebarItem"];
+ if (
+ entityScopedTypes.includes(value.type)
+ && (!value.entityTypes || value.entityTypes.length === 0)
+ ) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: `${value.type} slots require at least one entityType`,
+ path: ["entityTypes"],
+ });
+ }
+ // projectSidebarItem only makes sense for entityType "project".
+ if (value.type === "projectSidebarItem" && value.entityTypes && !value.entityTypes.includes("project")) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "projectSidebarItem slots require entityTypes to include \"project\"",
+ path: ["entityTypes"],
+ });
+ }
+ // commentAnnotation only makes sense for entityType "comment".
+ if (value.type === "commentAnnotation" && value.entityTypes && !value.entityTypes.includes("comment")) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "commentAnnotation slots require entityTypes to include \"comment\"",
+ path: ["entityTypes"],
+ });
+ }
+ // commentContextMenuItem only makes sense for entityType "comment".
+ if (value.type === "commentContextMenuItem" && value.entityTypes && !value.entityTypes.includes("comment")) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "commentContextMenuItem slots require entityTypes to include \"comment\"",
+ path: ["entityTypes"],
+ });
+ }
+});
+
+export type PluginUiSlotDeclarationInput = z.infer<typeof pluginUiSlotDeclarationSchema>;
+
+const entityScopedLauncherPlacementZones = [
+ "detailTab",
+ "taskDetailView",
+ "contextMenuItem",
+ "commentAnnotation",
+ "commentContextMenuItem",
+ "projectSidebarItem",
+] as const;
+
+const launcherBoundsByEnvironment: Record<
+ (typeof PLUGIN_LAUNCHER_RENDER_ENVIRONMENTS)[number],
+ readonly (typeof PLUGIN_LAUNCHER_BOUNDS)[number][]
+> = {
+ hostInline: ["inline", "compact", "default"],
+ hostOverlay: ["compact", "default", "wide", "full"],
+ hostRoute: ["default", "wide", "full"],
+ external: [],
+ iframe: ["compact", "default", "wide", "full"],
+};
+
+/**
+ * Validates the action payload for a declarative plugin launcher.
+ */
+export const pluginLauncherActionDeclarationSchema = z.object({
+ type: z.enum(PLUGIN_LAUNCHER_ACTIONS),
+ target: z.string().min(1),
+ params: z.record(z.unknown()).optional(),
+}).superRefine((value, ctx) => {
+ if (value.type === "performAction" && value.target.includes("/")) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "performAction launchers must target an action key, not a route or URL",
+ path: ["target"],
+ });
+ }
+
+ if (value.type === "navigate" && /^https?:\/\//.test(value.target)) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "navigate launchers must target a host route, not an absolute URL",
+ path: ["target"],
+ });
+ }
+});
+
+export type PluginLauncherActionDeclarationInput =
+ z.infer<typeof pluginLauncherActionDeclarationSchema>;
+
+/**
+ * Validates optional render hints for a plugin launcher destination.
+ */
+export const pluginLauncherRenderDeclarationSchema = z.object({
+ environment: z.enum(PLUGIN_LAUNCHER_RENDER_ENVIRONMENTS),
+ bounds: z.enum(PLUGIN_LAUNCHER_BOUNDS).optional(),
+}).superRefine((value, ctx) => {
+ if (!value.bounds) {
+ return;
+ }
+
+ const supportedBounds = launcherBoundsByEnvironment[value.environment];
+ if (!supportedBounds.includes(value.bounds)) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: `bounds "${value.bounds}" is not supported for render environment "${value.environment}"`,
+ path: ["bounds"],
+ });
+ }
+});
+
+export type PluginLauncherRenderDeclarationInput =
+ z.infer<typeof pluginLauncherRenderDeclarationSchema>;
+
+/**
+ * Validates declarative launcher metadata in a plugin manifest.
+ */
+export const pluginLauncherDeclarationSchema = z.object({
+ id: z.string().min(1),
+ displayName: z.string().min(1),
+ description: z.string().optional(),
+ placementZone: z.enum(PLUGIN_LAUNCHER_PLACEMENT_ZONES),
+ exportName: z.string().min(1).optional(),
+ entityTypes: z.array(z.enum(PLUGIN_UI_SLOT_ENTITY_TYPES)).optional(),
+ order: z.number().int().optional(),
+ action: pluginLauncherActionDeclarationSchema,
+ render: pluginLauncherRenderDeclarationSchema.optional(),
+}).superRefine((value, ctx) => {
+ if (
+ entityScopedLauncherPlacementZones.some((zone) => zone === value.placementZone)
+ && (!value.entityTypes || value.entityTypes.length === 0)
+ ) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: `${value.placementZone} launchers require at least one entityType`,
+ path: ["entityTypes"],
+ });
+ }
+
+ if (
+ value.placementZone === "projectSidebarItem"
+ && value.entityTypes
+ && !value.entityTypes.includes("project")
+ ) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "projectSidebarItem launchers require entityTypes to include \"project\"",
+ path: ["entityTypes"],
+ });
+ }
+
+ if (value.action.type === "performAction" && value.render) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "performAction launchers cannot declare render hints",
+ path: ["render"],
+ });
+ }
+
+ if (
+ ["openModal", "openDrawer", "openPopover"].includes(value.action.type)
+ && !value.render
+ ) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: `${value.action.type} launchers require render metadata`,
+ path: ["render"],
+ });
+ }
+
+ if (value.action.type === "openModal" && value.render?.environment === "hostInline") {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "openModal launchers cannot use the hostInline render environment",
+ path: ["render", "environment"],
+ });
+ }
+
+ if (
+ value.action.type === "openDrawer"
+ && value.render
+ && !["hostOverlay", "iframe"].includes(value.render.environment)
+ ) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "openDrawer launchers must use hostOverlay or iframe render environments",
+ path: ["render", "environment"],
+ });
+ }
+
+ if (value.action.type === "openPopover" && value.render?.environment === "hostRoute") {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "openPopover launchers cannot use the hostRoute render environment",
+ path: ["render", "environment"],
+ });
+ }
+});
+
+export type PluginLauncherDeclarationInput = z.infer<typeof pluginLauncherDeclarationSchema>;
+
+// ---------------------------------------------------------------------------
+// Plugin Manifest V1 schema
+// ---------------------------------------------------------------------------
+
+/**
+ * Zod schema for {@link PaperclipPluginManifestV1} — the complete runtime
+ * validator for plugin manifests read at install time.
+ *
+ * Field-level constraints (see PLUGIN_SPEC.md §10.1 for the normative rules):
+ *
+ * | Field | Type | Constraints |
+ * |--------------------------|------------|----------------------------------------------|
+ * | `id` | string | `^[a-z0-9][a-z0-9._-]*$` |
+ * | `apiVersion` | literal 1 | must equal `PLUGIN_API_VERSION` |
+ * | `version` | string | semver (`\d+\.\d+\.\d+`) |
+ * | `displayName` | string | 1–100 chars |
+ * | `description` | string | 1–500 chars |
+ * | `author` | string | 1–200 chars |
+ * | `categories` | enum[] | at least one; values from PLUGIN_CATEGORIES |
+ * | `minimumHostVersion` | string? | semver lower bound if present, no leading `v`|
+ * | `minimumPaperclipVersion`| string? | legacy alias of `minimumHostVersion` |
+ * | `capabilities` | enum[] | at least one; values from PLUGIN_CAPABILITIES|
+ * | `entrypoints.worker` | string | min 1 char |
+ * | `entrypoints.ui` | string? | required when `ui.slots` is declared |
+ *
+ * Cross-field rules enforced via `superRefine`:
+ * - `entrypoints.ui` required when `ui.slots` declared
+ * - `agent.tools.register` capability required when `tools` declared
+ * - `jobs.schedule` capability required when `jobs` declared
+ * - `webhooks.receive` capability required when `webhooks` declared
+ * - duplicate `jobs[].jobKey` values are rejected
+ * - duplicate `webhooks[].endpointKey` values are rejected
+ * - duplicate `tools[].name` values are rejected
+ * - duplicate `ui.slots[].id` values are rejected
+ *
+ * @see PLUGIN_SPEC.md §10.1 — Manifest shape
+ * @see {@link PaperclipPluginManifestV1} — the inferred TypeScript type
+ */
+export const pluginManifestV1Schema = z.object({
+ id: z.string().min(1).regex(
+ /^[a-z0-9][a-z0-9._-]*$/,
+ "Plugin id must start with a lowercase alphanumeric and contain only lowercase letters, digits, dots, hyphens, or underscores",
+ ),
+ apiVersion: z.literal(1),
+ version: z.string().min(1).regex(
+ /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/,
+ "Version must follow semver (e.g. 1.0.0 or 1.0.0-beta.1)",
+ ),
+ displayName: z.string().min(1).max(100),
+ description: z.string().min(1).max(500),
+ author: z.string().min(1).max(200),
+ categories: z.array(z.enum(PLUGIN_CATEGORIES)).min(1),
+ minimumHostVersion: z.string().regex(
+ /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/,
+ "minimumHostVersion must follow semver (e.g. 1.0.0)",
+ ).optional(),
+ minimumPaperclipVersion: z.string().regex(
+ /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/,
+ "minimumPaperclipVersion must follow semver (e.g. 1.0.0)",
+ ).optional(),
+ capabilities: z.array(z.enum(PLUGIN_CAPABILITIES)).min(1),
+ entrypoints: z.object({
+ worker: z.string().min(1),
+ ui: z.string().min(1).optional(),
+ }),
+ instanceConfigSchema: jsonSchemaSchema.optional(),
+ jobs: z.array(pluginJobDeclarationSchema).optional(),
+ webhooks: z.array(pluginWebhookDeclarationSchema).optional(),
+ tools: z.array(pluginToolDeclarationSchema).optional(),
+ launchers: z.array(pluginLauncherDeclarationSchema).optional(),
+ ui: z.object({
+ slots: z.array(pluginUiSlotDeclarationSchema).min(1).optional(),
+ launchers: z.array(pluginLauncherDeclarationSchema).optional(),
+ }).optional(),
+}).superRefine((manifest, ctx) => {
+ // ── Entrypoint ↔ UI slot consistency ──────────────────────────────────
+ // Plugins that declare UI slots must also declare a UI entrypoint so the
+ // host knows where to load the bundle from (PLUGIN_SPEC.md §10.1).
+ const hasUiSlots = (manifest.ui?.slots?.length ?? 0) > 0;
+ const hasUiLaunchers = (manifest.ui?.launchers?.length ?? 0) > 0;
+ if ((hasUiSlots || hasUiLaunchers) && !manifest.entrypoints.ui) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "entrypoints.ui is required when ui.slots or ui.launchers are declared",
+ path: ["entrypoints", "ui"],
+ });
+ }
+
+ if (
+ manifest.minimumHostVersion
+ && manifest.minimumPaperclipVersion
+ && manifest.minimumHostVersion !== manifest.minimumPaperclipVersion
+ ) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "minimumHostVersion and minimumPaperclipVersion must match when both are declared",
+ path: ["minimumHostVersion"],
+ });
+ }
+
+ // ── Capability ↔ feature declaration consistency ───────────────────────
+ // The host enforces capabilities at install and runtime. A plugin must
+ // declare every capability it needs up-front; silently having more features
+ // than capabilities would cause runtime rejections.
+
+ // tools require agent.tools.register (PLUGIN_SPEC.md §11)
+ if (manifest.tools && manifest.tools.length > 0) {
+ if (!manifest.capabilities.includes("agent.tools.register")) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "Capability 'agent.tools.register' is required when tools are declared",
+ path: ["capabilities"],
+ });
+ }
+ }
+
+ // jobs require jobs.schedule (PLUGIN_SPEC.md §17)
+ if (manifest.jobs && manifest.jobs.length > 0) {
+ if (!manifest.capabilities.includes("jobs.schedule")) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "Capability 'jobs.schedule' is required when jobs are declared",
+ path: ["capabilities"],
+ });
+ }
+ }
+
+ // webhooks require webhooks.receive (PLUGIN_SPEC.md §18)
+ if (manifest.webhooks && manifest.webhooks.length > 0) {
+ if (!manifest.capabilities.includes("webhooks.receive")) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "Capability 'webhooks.receive' is required when webhooks are declared",
+ path: ["capabilities"],
+ });
+ }
+ }
+
+ // ── Uniqueness checks ──────────────────────────────────────────────────
+ // Duplicate keys within a plugin's own manifest are always a bug. The host
+ // would not know which declaration takes precedence, so we reject early.
+
+ // job keys must be unique within the plugin (used as identifiers in the DB)
+ if (manifest.jobs) {
+ const jobKeys = manifest.jobs.map((j) => j.jobKey);
+ const duplicates = jobKeys.filter((key, i) => jobKeys.indexOf(key) !== i);
+ if (duplicates.length > 0) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: `Duplicate job keys: ${[...new Set(duplicates)].join(", ")}`,
+ path: ["jobs"],
+ });
+ }
+ }
+
+ // webhook endpoint keys must be unique within the plugin (used in routes)
+ if (manifest.webhooks) {
+ const endpointKeys = manifest.webhooks.map((w) => w.endpointKey);
+ const duplicates = endpointKeys.filter((key, i) => endpointKeys.indexOf(key) !== i);
+ if (duplicates.length > 0) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: `Duplicate webhook endpoint keys: ${[...new Set(duplicates)].join(", ")}`,
+ path: ["webhooks"],
+ });
+ }
+ }
+
+ // tool names must be unique within the plugin (namespaced at runtime)
+ if (manifest.tools) {
+ const toolNames = manifest.tools.map((t) => t.name);
+ const duplicates = toolNames.filter((name, i) => toolNames.indexOf(name) !== i);
+ if (duplicates.length > 0) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: `Duplicate tool names: ${[...new Set(duplicates)].join(", ")}`,
+ path: ["tools"],
+ });
+ }
+ }
+
+ // UI slot ids must be unique within the plugin (namespaced at runtime)
+ if (manifest.ui) {
+ if (manifest.ui.slots) {
+ const slotIds = manifest.ui.slots.map((s) => s.id);
+ const duplicates = slotIds.filter((id, i) => slotIds.indexOf(id) !== i);
+ if (duplicates.length > 0) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: `Duplicate UI slot ids: ${[...new Set(duplicates)].join(", ")}`,
+ path: ["ui", "slots"],
+ });
+ }
+ }
+ }
+
+ // launcher ids must be unique within the plugin
+ const allLaunchers = [
+ ...(manifest.launchers ?? []),
+ ...(manifest.ui?.launchers ?? []),
+ ];
+ if (allLaunchers.length > 0) {
+ const launcherIds = allLaunchers.map((launcher) => launcher.id);
+ const duplicates = launcherIds.filter((id, i) => launcherIds.indexOf(id) !== i);
+ if (duplicates.length > 0) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: `Duplicate launcher ids: ${[...new Set(duplicates)].join(", ")}`,
+ path: manifest.ui?.launchers ? ["ui", "launchers"] : ["launchers"],
+ });
+ }
+ }
+});
+
+export type PluginManifestV1Input = z.infer<typeof pluginManifestV1Schema>;
+
+// ---------------------------------------------------------------------------
+// Plugin installation / registration request
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema for installing (registering) a plugin.
+ * The server receives the packageName and resolves the manifest from the
+ * installed package.
+ */
+export const installPluginSchema = z.object({
+ packageName: z.string().min(1),
+ version: z.string().min(1).optional(),
+ /** Set by loader for local-path installs so the worker can be resolved. */
+ packagePath: z.string().min(1).optional(),
+});
+
+export type InstallPlugin = z.infer<typeof installPluginSchema>;
+
+// ---------------------------------------------------------------------------
+// Plugin config (instance configuration) schemas
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema for creating or updating a plugin's instance configuration.
+ * configJson is validated permissively here; runtime validation against
+ * the plugin's instanceConfigSchema is done at the service layer.
+ */
+export const upsertPluginConfigSchema = z.object({
+ configJson: z.record(z.unknown()),
+});
+
+export type UpsertPluginConfig = z.infer<typeof upsertPluginConfigSchema>;
+
+/**
+ * Schema for partially updating a plugin's instance configuration.
+ * Allows a partial merge of config values.
+ */
+export const patchPluginConfigSchema = z.object({
+ configJson: z.record(z.unknown()),
+});
+
+export type PatchPluginConfig = z.infer<typeof patchPluginConfigSchema>;
+
+// ---------------------------------------------------------------------------
+// Company plugin availability / settings schemas
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema for creating or replacing company-scoped plugin settings.
+ *
+ * Company-specific settings are stored separately from instance-level
+ * `plugin_config`, allowing the host to expose a company availability toggle
+ * without changing the global install state of the plugin.
+ */
+export const upsertPluginCompanySettingsSchema = z.object({
+ settingsJson: z.record(z.unknown()).optional().default({}),
+ lastError: z.string().nullable().optional(),
+});
+
+export type UpsertPluginCompanySettings = z.infer<typeof upsertPluginCompanySettingsSchema>;
+
+/**
+ * Schema for mutating a plugin's availability for a specific company.
+ *
+ * `available=false` lets callers disable access without uninstalling the
+ * plugin globally. Optional `settingsJson` supports carrying company-specific
+ * configuration alongside the availability update.
+ */
+export const updateCompanyPluginAvailabilitySchema = z.object({
+ available: z.boolean(),
+ settingsJson: z.record(z.unknown()).optional(),
+ lastError: z.string().nullable().optional(),
+});
+
+export type UpdateCompanyPluginAvailability = z.infer<typeof updateCompanyPluginAvailabilitySchema>;
+
+/**
+ * Query schema for company plugin availability list endpoints.
+ */
+export const listCompanyPluginAvailabilitySchema = z.object({
+ available: z.boolean().optional(),
+});
+
+export type ListCompanyPluginAvailability = z.infer<typeof listCompanyPluginAvailabilitySchema>;
+
+// ---------------------------------------------------------------------------
+// Plugin status update
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema for updating a plugin's lifecycle status. Used by the lifecycle
+ * manager to persist state transitions.
+ *
+ * @see {@link PLUGIN_STATUSES} for the valid status values
+ */
+export const updatePluginStatusSchema = z.object({
+ status: z.enum(PLUGIN_STATUSES),
+ lastError: z.string().nullable().optional(),
+});
+
+export type UpdatePluginStatus = z.infer<typeof updatePluginStatusSchema>;
+
+// ---------------------------------------------------------------------------
+// Plugin uninstall
+// ---------------------------------------------------------------------------
+
+/** Schema for the uninstall request. `removeData` controls hard vs soft delete. */
+export const uninstallPluginSchema = z.object({
+ removeData: z.boolean().optional().default(false),
+});
+
+export type UninstallPlugin = z.infer<typeof uninstallPluginSchema>;
+
+// ---------------------------------------------------------------------------
+// Plugin state (key-value storage) schemas
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema for a plugin state scope key — identifies the exact location where
+ * state is stored. Used by the `ctx.state.get()`, `ctx.state.set()`, and
+ * `ctx.state.delete()` SDK methods.
+ *
+ * @see PLUGIN_SPEC.md §21.3 `plugin_state`
+ */
+export const pluginStateScopeKeySchema = z.object({
+ scopeKind: z.enum(PLUGIN_STATE_SCOPE_KINDS),
+ scopeId: z.string().min(1).optional(),
+ namespace: z.string().min(1).optional(),
+ stateKey: z.string().min(1),
+});
+
+export type PluginStateScopeKey = z.infer<typeof pluginStateScopeKeySchema>;
+
+/**
+ * Schema for setting a plugin state value.
+ */
+export const setPluginStateSchema = z.object({
+ scopeKind: z.enum(PLUGIN_STATE_SCOPE_KINDS),
+ scopeId: z.string().min(1).optional(),
+ namespace: z.string().min(1).optional(),
+ stateKey: z.string().min(1),
+ /** JSON-serializable value to store. */
+ value: z.unknown(),
+});
+
+export type SetPluginState = z.infer<typeof setPluginStateSchema>;
+
+/**
+ * Schema for querying plugin state entries. All fields are optional to allow
+ * flexible list queries (e.g. all state for a plugin within a scope).
+ */
+export const listPluginStateSchema = z.object({
+ scopeKind: z.enum(PLUGIN_STATE_SCOPE_KINDS).optional(),
+ scopeId: z.string().min(1).optional(),
+ namespace: z.string().min(1).optional(),
+});
+
+export type ListPluginState = z.infer<typeof listPluginStateSchema>;
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 014e14123b..4ac3cfcc5f 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,6 +1,8 @@
packages:
- packages/*
- packages/adapters/*
+ - packages/plugins/*
+ - packages/plugins/examples/*
- server
- ui
- cli
diff --git a/scripts/ensure-plugin-build-deps.mjs b/scripts/ensure-plugin-build-deps.mjs
new file mode 100644
index 0000000000..f8470da1d6
--- /dev/null
+++ b/scripts/ensure-plugin-build-deps.mjs
@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(scriptDir, "..");
+const tscCliPath = path.join(rootDir, "node_modules", "typescript", "bin", "tsc");
+
+const buildTargets = [
+ {
+ name: "@paperclipai/shared",
+ output: path.join(rootDir, "packages/shared/dist/index.js"),
+ tsconfig: path.join(rootDir, "packages/shared/tsconfig.json"),
+ },
+ {
+ name: "@paperclipai/plugin-sdk",
+ output: path.join(rootDir, "packages/plugins/sdk/dist/index.js"),
+ tsconfig: path.join(rootDir, "packages/plugins/sdk/tsconfig.json"),
+ },
+];
+
+if (!fs.existsSync(tscCliPath)) {
+ throw new Error(`TypeScript CLI not found at ${tscCliPath}`);
+}
+
+for (const target of buildTargets) {
+ if (fs.existsSync(target.output)) {
+ continue;
+ }
+
+ const result = spawnSync(process.execPath, [tscCliPath, "-p", target.tsconfig], {
+ cwd: rootDir,
+ stdio: "inherit",
+ });
+
+ if (result.error) {
+ throw result.error;
+ }
+
+ if (result.status !== 0) {
+ process.exit(result.status ?? 1);
+ }
+}
diff --git a/server/package.json b/server/package.json
index cd30cf13ee..2e56ae5d76 100644
--- a/server/package.json
+++ b/server/package.json
@@ -30,7 +30,7 @@
"postpack": "rm -rf ui-dist",
"clean": "rm -rf dist",
"start": "node dist/index.js",
- "typecheck": "tsc --noEmit"
+ "typecheck": "pnpm --filter @paperclipai/plugin-sdk build && tsc --noEmit"
},
"dependencies": {
"@aws-sdk/client-s3": "^3.888.0",
@@ -43,7 +43,10 @@
"@paperclipai/adapter-pi-local": "workspace:*",
"@paperclipai/adapter-utils": "workspace:*",
"@paperclipai/db": "workspace:*",
+ "@paperclipai/plugin-sdk": "workspace:*",
"@paperclipai/shared": "workspace:*",
+ "ajv": "^8.18.0",
+ "ajv-formats": "^3.0.1",
"better-auth": "1.4.18",
"detect-port": "^2.1.0",
"dotenv": "^17.0.1",
diff --git a/server/src/__tests__/plugin-worker-manager.test.ts b/server/src/__tests__/plugin-worker-manager.test.ts
new file mode 100644
index 0000000000..53ed57bbba
--- /dev/null
+++ b/server/src/__tests__/plugin-worker-manager.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { appendStderrExcerpt, formatWorkerFailureMessage } from "../services/plugin-worker-manager.js";
+
+describe("plugin-worker-manager stderr failure context", () => {
+ it("appends worker stderr context to failure messages", () => {
+ expect(
+ formatWorkerFailureMessage(
+ "Worker process exited (code=1, signal=null)",
+ "TypeError: Unknown file extension \".ts\"",
+ ),
+ ).toBe(
+ "Worker process exited (code=1, signal=null)\n\nWorker stderr:\nTypeError: Unknown file extension \".ts\"",
+ );
+ });
+
+ it("does not duplicate stderr that is already present", () => {
+ const message = [
+ "Worker process exited (code=1, signal=null)",
+ "",
+ "Worker stderr:",
+ "TypeError: Unknown file extension \".ts\"",
+ ].join("\n");
+
+ expect(
+ formatWorkerFailureMessage(message, "TypeError: Unknown file extension \".ts\""),
+ ).toBe(message);
+ });
+
+ it("keeps only the latest stderr excerpt", () => {
+ let excerpt = "";
+ excerpt = appendStderrExcerpt(excerpt, "first line");
+ excerpt = appendStderrExcerpt(excerpt, "second line");
+
+ expect(excerpt).toContain("first line");
+ expect(excerpt).toContain("second line");
+
+ excerpt = appendStderrExcerpt(excerpt, "x".repeat(9_000));
+
+ expect(excerpt).not.toContain("first line");
+ expect(excerpt).not.toContain("second line");
+ expect(excerpt.length).toBeLessThanOrEqual(8_000);
+ });
+});
diff --git a/server/src/app.ts b/server/src/app.ts
index 6871552a57..52e067826b 100644
--- a/server/src/app.ts
+++ b/server/src/app.ts
@@ -24,7 +24,23 @@ import { sidebarBadgeRoutes } from "./routes/sidebar-badges.js";
import { llmRoutes } from "./routes/llms.js";
import { assetRoutes } from "./routes/assets.js";
import { accessRoutes } from "./routes/access.js";
+import { pluginRoutes } from "./routes/plugins.js";
+import { pluginUiStaticRoutes } from "./routes/plugin-ui-static.js";
import { applyUiBranding } from "./ui-branding.js";
+import { logger } from "./middleware/logger.js";
+import { DEFAULT_LOCAL_PLUGIN_DIR, pluginLoader } from "./services/plugin-loader.js";
+import { createPluginWorkerManager } from "./services/plugin-worker-manager.js";
+import { createPluginJobScheduler } from "./services/plugin-job-scheduler.js";
+import { pluginJobStore } from "./services/plugin-job-store.js";
+import { createPluginToolDispatcher } from "./services/plugin-tool-dispatcher.js";
+import { pluginLifecycleManager } from "./services/plugin-lifecycle.js";
+import { createPluginJobCoordinator } from "./services/plugin-job-coordinator.js";
+import { buildHostServices, flushPluginLogBuffer } from "./services/plugin-host-services.js";
+import { createPluginEventBus } from "./services/plugin-event-bus.js";
+import { createPluginDevWatcher } from "./services/plugin-dev-watcher.js";
+import { createPluginHostServiceCleanup } from "./services/plugin-host-service-cleanup.js";
+import { pluginRegistryService } from "./services/plugin-registry.js";
+import { createHostClientHandlers } from "@paperclipai/plugin-sdk";
import type { BetterAuthSessionResult } from "./auth/better-auth.js";
type UiMode = "none" | "static" | "vite-dev";
@@ -41,13 +57,20 @@ export async function createApp(
bindHost: string;
authReady: boolean;
companyDeletionEnabled: boolean;
+ instanceId?: string;
+ hostVersion?: string;
+ localPluginDir?: string;
betterAuthHandler?: express.RequestHandler;
resolveSession?: (req: ExpressRequest) => Promise<BetterAuthSessionResult | null>;
},
) {
const app = express();
- app.use(express.json());
+ app.use(express.json({
+ verify: (req, _res, buf) => {
+ (req as unknown as { rawBody: Buffer }).rawBody = buf;
+ },
+ }));
app.use(httpLogger);
const privateHostnameGateEnabled =
opts.deploymentMode === "authenticated" && opts.deploymentExposure === "private";
@@ -114,6 +137,75 @@ export async function createApp(
api.use(activityRoutes(db));
api.use(dashboardRoutes(db));
api.use(sidebarBadgeRoutes(db));
+ const hostServicesDisposers = new Map<string, () => void>();
+ const workerManager = createPluginWorkerManager();
+ const pluginRegistry = pluginRegistryService(db);
+ const eventBus = createPluginEventBus({
+ async isPluginEnabledForCompany(pluginKey, companyId) {
+ const plugin = await pluginRegistry.getByKey(pluginKey);
+ if (!plugin) return false;
+ const availability = await pluginRegistry.getCompanyAvailability(companyId, plugin.id);
+ return availability?.available ?? true;
+ },
+ });
+ const jobStore = pluginJobStore(db);
+ const lifecycle = pluginLifecycleManager(db, { workerManager });
+ const scheduler = createPluginJobScheduler({
+ db,
+ jobStore,
+ workerManager,
+ });
+ const toolDispatcher = createPluginToolDispatcher({
+ workerManager,
+ lifecycleManager: lifecycle,
+ db,
+ });
+ const jobCoordinator = createPluginJobCoordinator({
+ db,
+ lifecycle,
+ scheduler,
+ jobStore,
+ });
+ const hostServiceCleanup = createPluginHostServiceCleanup(lifecycle, hostServicesDisposers);
+ const loader = pluginLoader(
+ db,
+ { localPluginDir: opts.localPluginDir ?? DEFAULT_LOCAL_PLUGIN_DIR },
+ {
+ workerManager,
+ eventBus,
+ jobScheduler: scheduler,
+ jobStore,
+ toolDispatcher,
+ lifecycleManager: lifecycle,
+ instanceInfo: {
+ instanceId: opts.instanceId ?? "default",
+ hostVersion: opts.hostVersion ?? "0.0.0",
+ },
+ buildHostHandlers: (pluginId, manifest) => {
+ const notifyWorker = (method: string, params: unknown) => {
+ const handle = workerManager.getWorker(pluginId);
+ if (handle) handle.notify(method, params);
+ };
+ const services = buildHostServices(db, pluginId, manifest.id, eventBus, notifyWorker);
+ hostServicesDisposers.set(pluginId, () => services.dispose());
+ return createHostClientHandlers({
+ pluginId,
+ capabilities: manifest.capabilities,
+ services,
+ });
+ },
+ },
+ );
+ api.use(
+ pluginRoutes(
+ db,
+ loader,
+ { scheduler, jobStore },
+ { workerManager },
+ { toolDispatcher },
+ { workerManager },
+ ),
+ );
api.use(
accessRoutes(db, {
deploymentMode: opts.deploymentMode,
@@ -126,6 +218,9 @@ export async function createApp(
app.use("/api", (_req, res) => {
res.status(404).json({ error: "API route not found" });
});
+ app.use(pluginUiStaticRoutes(db, {
+ localPluginDir: opts.localPluginDir ?? DEFAULT_LOCAL_PLUGIN_DIR,
+ }));
const __dirname = path.dirname(fileURLToPath(import.meta.url));
if (opts.uiMode === "static") {
@@ -179,5 +274,33 @@ export async function createApp(
app.use(errorHandler);
+ jobCoordinator.start();
+ scheduler.start();
+ void toolDispatcher.initialize().catch((err) => {
+ logger.error({ err }, "Failed to initialize plugin tool dispatcher");
+ });
+ const devWatcher = createPluginDevWatcher(
+ lifecycle,
+ async (pluginId) => (await pluginRegistry.getById(pluginId))?.packagePath ?? null,
+ );
+ void loader.loadAll().then((result) => {
+ if (!result) return;
+ for (const loaded of result.results) {
+ if (loaded.success && loaded.plugin.packagePath) {
+ devWatcher.watch(loaded.plugin.id, loaded.plugin.packagePath);
+ }
+ }
+ }).catch((err) => {
+ logger.error({ err }, "Failed to load ready plugins on startup");
+ });
+ process.once("exit", () => {
+ devWatcher.close();
+ hostServiceCleanup.disposeAll();
+ hostServiceCleanup.teardown();
+ });
+ process.once("beforeExit", () => {
+ void flushPluginLogBuffer();
+ });
+
return app;
}
diff --git a/server/src/routes/plugin-ui-static.ts b/server/src/routes/plugin-ui-static.ts
new file mode 100644
index 0000000000..2784f59303
--- /dev/null
+++ b/server/src/routes/plugin-ui-static.ts
@@ -0,0 +1,496 @@
+/**
+ * @fileoverview Plugin UI static file serving route
+ *
+ * Serves plugin UI bundles from the plugin's dist/ui/ directory under the
+ * `/_plugins/:pluginId/ui/*` namespace. This is specified in PLUGIN_SPEC.md
+ * §19.0.3 (Bundle Serving).
+ *
+ * Plugin UI bundles are pre-built ESM that the host serves as static assets.
+ * The host dynamically imports the plugin's UI entry module from this path,
+ * resolves the named export declared in `ui.slots[].exportName`, and mounts
+ * it into the extension slot.
+ *
+ * Security:
+ * - Path traversal is prevented by resolving the requested path and verifying
+ * it stays within the plugin's UI directory.
+ * - Only plugins in 'ready' status have their UI served.
+ * - Only plugins that declare `entrypoints.ui` serve UI bundles.
+ *
+ * Cache Headers:
+ * - Files with content-hash patterns in their name (e.g., `index-a1b2c3d4.js`)
+ * receive `Cache-Control: public, max-age=31536000, immutable`.
+ * - Other files receive `Cache-Control: public, max-age=0, must-revalidate`
+ * with ETag-based conditional request support.
+ *
+ * @module server/routes/plugin-ui-static
+ * @see doc/plugins/PLUGIN_SPEC.md §19.0.3 — Bundle Serving
+ * @see doc/plugins/PLUGIN_SPEC.md §25.4.5 — Frontend Cache Invalidation
+ */
+
+import { Router } from "express";
+import path from "node:path";
+import fs from "node:fs";
+import crypto from "node:crypto";
+import type { Db } from "@paperclipai/db";
+import { pluginRegistryService } from "../services/plugin-registry.js";
+import { logger } from "../middleware/logger.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Regex to detect content-hashed filenames.
+ *
+ * Matches patterns like:
+ * - `index-a1b2c3d4.js`
+ * - `styles.abc123def.css`
+ * - `chunk-ABCDEF01.mjs`
+ *
+ * The hash portion must be at least 8 hex characters to avoid false positives.
+ */
+const CONTENT_HASH_PATTERN = /[.-][a-fA-F0-9]{8,}\.\w+$/;
+
+/**
+ * Cache-Control header for content-hashed files.
+ * These files are immutable by definition (the hash changes when content changes).
+ */
+/** 1 year in seconds — standard for content-hashed immutable resources. */
+const ONE_YEAR_SECONDS = 365 * 24 * 60 * 60; // 31_536_000
+const CACHE_CONTROL_IMMUTABLE = `public, max-age=${ONE_YEAR_SECONDS}, immutable`;
+
+/**
+ * Cache-Control header for non-hashed files.
+ * These files must be revalidated on each request (ETag-based).
+ */
+const CACHE_CONTROL_REVALIDATE = "public, max-age=0, must-revalidate";
+
+/**
+ * MIME types for common plugin UI bundle file extensions.
+ */
+const MIME_TYPES: Record<string, string> = {
+ ".js": "application/javascript; charset=utf-8",
+ ".mjs": "application/javascript; charset=utf-8",
+ ".css": "text/css; charset=utf-8",
+ ".json": "application/json; charset=utf-8",
+ ".map": "application/json; charset=utf-8",
+ ".html": "text/html; charset=utf-8",
+ ".svg": "image/svg+xml",
+ ".png": "image/png",
+ ".jpg": "image/jpeg",
+ ".jpeg": "image/jpeg",
+ ".gif": "image/gif",
+ ".webp": "image/webp",
+ ".woff": "font/woff",
+ ".woff2": "font/woff2",
+ ".ttf": "font/ttf",
+ ".eot": "application/vnd.ms-fontobject",
+ ".ico": "image/x-icon",
+ ".txt": "text/plain; charset=utf-8",
+};
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a plugin's UI directory from its package location.
+ *
+ * The plugin's `packageName` is stored in the DB. We resolve the package path
+ * from the local plugin directory (DEFAULT_LOCAL_PLUGIN_DIR) by looking in
+ * `node_modules`. If the plugin was installed from a local path, the manifest
+ * `entrypoints.ui` path is resolved relative to the package directory.
+ *
+ * @param localPluginDir - The plugin installation directory
+ * @param packageName - The npm package name
+ * @param entrypointsUi - The UI entrypoint path from the manifest (e.g., "./dist/ui/")
+ * @returns Absolute path to the UI directory, or null if not found
+ */
+export function resolvePluginUiDir(
+ localPluginDir: string,
+ packageName: string,
+ entrypointsUi: string,
+ packagePath?: string | null,
+): string | null {
+ // For local-path installs, prefer the persisted package path.
+ if (packagePath) {
+ const resolvedPackagePath = path.resolve(packagePath);
+ if (fs.existsSync(resolvedPackagePath)) {
+ const uiDirFromPackagePath = path.resolve(resolvedPackagePath, entrypointsUi);
+ if (
+ uiDirFromPackagePath.startsWith(resolvedPackagePath)
+ && fs.existsSync(uiDirFromPackagePath)
+ ) {
+ return uiDirFromPackagePath;
+ }
+ }
+ }
+
+ // Resolve the package root within the local plugin directory's node_modules.
+ // npm installs go to <localPluginDir>/node_modules/<packageName>/
+ let packageRoot: string;
+ if (packageName.startsWith("@")) {
+ // Scoped package: @scope/name -> node_modules/@scope/name
+ packageRoot = path.join(localPluginDir, "node_modules", ...packageName.split("/"));
+ } else {
+ packageRoot = path.join(localPluginDir, "node_modules", packageName);
+ }
+
+ // If the standard location doesn't exist, the plugin may have been installed
+ // from a local path. Try to check if the package.json is accessible at the
+ // computed path or if the package is found elsewhere.
+ if (!fs.existsSync(packageRoot)) {
+ // For local-path installs, the packageName may be a directory that doesn't
+ // live inside node_modules. Check if the package exists directly at the
+ // localPluginDir level.
+ const directPath = path.join(localPluginDir, packageName);
+ if (fs.existsSync(directPath)) {
+ packageRoot = directPath;
+ } else {
+ return null;
+ }
+ }
+
+ // Resolve the UI directory relative to the package root
+ const uiDir = path.resolve(packageRoot, entrypointsUi);
+
+ // Verify the resolved UI directory exists and is actually inside the package
+ if (!fs.existsSync(uiDir)) {
+ return null;
+ }
+
+ return uiDir;
+}
+
+/**
+ * Compute an ETag from file stat (size + mtime).
+ * This is a lightweight approach that avoids reading the file content.
+ */
+function computeETag(size: number, mtimeMs: number): string {
+ const ETAG_VERSION = "v2";
+ const hash = crypto
+ .createHash("md5")
+ .update(`${ETAG_VERSION}:${size}-${mtimeMs}`)
+ .digest("hex")
+ .slice(0, 16);
+ return `"${hash}"`;
+}
+
+// ---------------------------------------------------------------------------
+// Route factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for the plugin UI static route.
+ */
+export interface PluginUiStaticRouteOptions {
+ /**
+ * The local plugin installation directory.
+ * This is where plugins are installed via `npm install --prefix`.
+ * Defaults to the standard `~/.paperclip/plugins/` location.
+ */
+ localPluginDir: string;
+}
+
+/**
+ * Create an Express router that serves plugin UI static files.
+ *
+ * This route handles `GET /_plugins/:pluginId/ui/*` requests by:
+ * 1. Looking up the plugin in the registry by ID or key
+ * 2. Verifying the plugin is in 'ready' status with UI declared
+ * 3. Resolving the file path within the plugin's dist/ui/ directory
+ * 4. Serving the file with appropriate cache headers
+ *
+ * @param db - Database connection for plugin registry lookups
+ * @param options - Configuration options
+ * @returns Express router
+ */
+export function pluginUiStaticRoutes(db: Db, options: PluginUiStaticRouteOptions) {
+ const router = Router();
+ const registry = pluginRegistryService(db);
+ const log = logger.child({ service: "plugin-ui-static" });
+
+ /**
+ * GET /_plugins/:pluginId/ui/*
+ *
+ * Serve a static file from a plugin's UI bundle directory.
+ *
+ * The :pluginId parameter accepts either:
+ * - Database UUID
+ * - Plugin key (e.g., "acme.linear")
+ *
+ * The wildcard captures the relative file path within the UI directory.
+ *
+ * Cache strategy:
+ * - Content-hashed filenames → immutable, 1-year max-age
+ * - Other files → must-revalidate with ETag
+ */
+ router.get("/_plugins/:pluginId/ui/*filePath", async (req, res) => {
+ const { pluginId } = req.params;
+
+ // Extract the relative file path from the named wildcard.
+ // In Express 5 with path-to-regexp v8, named wildcards may return
+ // an array of path segments or a single string.
+ const rawParam = req.params.filePath;
+ const rawFilePath = Array.isArray(rawParam)
+ ? rawParam.join("/")
+ : rawParam as string | undefined;
+
+ if (!rawFilePath || rawFilePath.length === 0) {
+ res.status(400).json({ error: "File path is required" });
+ return;
+ }
+
+ // Step 1: Look up the plugin
+ let plugin = null;
+ try {
+ plugin = await registry.getById(pluginId);
+ } catch (error) {
+ const maybeCode =
+ typeof error === "object" && error !== null && "code" in error
+ ? (error as { code?: unknown }).code
+ : undefined;
+ if (maybeCode !== "22P02") {
+ throw error;
+ }
+ }
+ if (!plugin) {
+ plugin = await registry.getByKey(pluginId);
+ }
+
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ // Step 2: Verify the plugin is ready and has UI declared
+ if (plugin.status !== "ready") {
+ res.status(403).json({
+ error: `Plugin UI is not available (status: ${plugin.status})`,
+ });
+ return;
+ }
+
+ const manifest = plugin.manifestJson;
+ if (!manifest?.entrypoints?.ui) {
+ res.status(404).json({ error: "Plugin does not declare a UI bundle" });
+ return;
+ }
+
+ // Step 2b: Check for devUiUrl in plugin config — proxy to local dev server
+ // when a plugin author has configured a dev server URL for hot-reload.
+ // See PLUGIN_SPEC.md §27.2 — Local Development Workflow
+ try {
+ const configRow = await registry.getConfig(plugin.id);
+ const devUiUrl =
+ configRow &&
+ typeof configRow === "object" &&
+ "configJson" in configRow &&
+ (configRow as { configJson: Record<string, unknown> }).configJson?.devUiUrl;
+
+ if (typeof devUiUrl === "string" && devUiUrl.length > 0) {
+ // Dev proxy is only available in development mode
+ if (process.env.NODE_ENV === "production") {
+ log.warn(
+ { pluginId: plugin.id },
+ "plugin-ui-static: devUiUrl ignored in production",
+ );
+ // Fall through to static file serving below
+ } else {
+ // Guard against rawFilePath overriding the base URL via protocol
+ // scheme (e.g. "https://evil.com/x") or protocol-relative paths
+ // (e.g. "//evil.com/x") which cause `new URL(path, base)` to
+ // ignore the base entirely.
+ // Normalize percent-encoding so encoded slashes (%2F) can't bypass
+ // the protocol/path checks below.
+ let decodedPath: string;
+ try {
+ decodedPath = decodeURIComponent(rawFilePath);
+ } catch {
+ res.status(400).json({ error: "Invalid file path" });
+ return;
+ }
+ if (
+ decodedPath.includes("://") ||
+ decodedPath.startsWith("//") ||
+ decodedPath.startsWith("\\\\")
+ ) {
+ res.status(400).json({ error: "Invalid file path" });
+ return;
+ }
+
+ // Proxy the request to the dev server
+ const targetUrl = new URL(rawFilePath, devUiUrl.endsWith("/") ? devUiUrl : devUiUrl + "/");
+
+ // SSRF protection: only allow http/https and localhost targets for dev proxy
+ if (targetUrl.protocol !== "http:" && targetUrl.protocol !== "https:") {
+ res.status(400).json({ error: "devUiUrl must use http or https protocol" });
+ return;
+ }
+
+ // Dev proxy is restricted to loopback addresses only.
+ // Validate the *constructed* targetUrl hostname (not the base) to
+ // catch any path-based override that slipped past the checks above.
+ const devHost = targetUrl.hostname;
+ const isLoopback =
+ devHost === "localhost" ||
+ devHost === "127.0.0.1" ||
+ devHost === "::1" ||
+ devHost === "[::1]";
+ if (!isLoopback) {
+ log.warn(
+ { pluginId: plugin.id, devUiUrl, host: devHost },
+ "plugin-ui-static: devUiUrl must target localhost, rejecting proxy",
+ );
+ res.status(400).json({ error: "devUiUrl must target localhost" });
+ return;
+ }
+
+ log.debug(
+ { pluginId: plugin.id, devUiUrl, targetUrl: targetUrl.href },
+ "plugin-ui-static: proxying to devUiUrl",
+ );
+
+ try {
+ const controller = new AbortController();
+ const timeout = setTimeout(() => controller.abort(), 10_000);
+ try {
+ const upstream = await fetch(targetUrl.href, { signal: controller.signal });
+ if (!upstream.ok) {
+ res.status(upstream.status).json({
+ error: `Dev server returned ${upstream.status}`,
+ });
+ return;
+ }
+
+ const contentType = upstream.headers.get("content-type");
+ if (contentType) res.set("Content-Type", contentType);
+ res.set("Cache-Control", "no-cache, no-store, must-revalidate");
+
+ const body = await upstream.arrayBuffer();
+ res.send(Buffer.from(body));
+ return;
+ } finally {
+ clearTimeout(timeout);
+ }
+ } catch (proxyErr) {
+ log.warn(
+ {
+ pluginId: plugin.id,
+ devUiUrl,
+ err: proxyErr instanceof Error ? proxyErr.message : String(proxyErr),
+ },
+ "plugin-ui-static: failed to proxy to devUiUrl, falling back to static",
+ );
+ // Fall through to static serving below
+ }
+ }
+ }
+ } catch {
+ // Config lookup failure is non-fatal — fall through to static serving
+ }
+
+ // Step 3: Resolve the plugin's UI directory
+ const uiDir = resolvePluginUiDir(
+ options.localPluginDir,
+ plugin.packageName,
+ manifest.entrypoints.ui,
+ plugin.packagePath,
+ );
+
+ if (!uiDir) {
+ log.warn(
+ { pluginId: plugin.id, pluginKey: plugin.pluginKey, packageName: plugin.packageName },
+ "plugin-ui-static: UI directory not found on disk",
+ );
+ res.status(404).json({ error: "Plugin UI directory not found" });
+ return;
+ }
+
+ // Step 4: Resolve the requested file path and prevent traversal (including symlinks)
+ const resolvedFilePath = path.resolve(uiDir, rawFilePath);
+
+ // Step 5: Check that the file exists and is a regular file
+ let fileStat: fs.Stats;
+ try {
+ fileStat = fs.statSync(resolvedFilePath);
+ } catch {
+ res.status(404).json({ error: "File not found" });
+ return;
+ }
+
+ // Security: resolve symlinks via realpathSync and verify containment.
+ // This prevents symlink-based traversal that string-based startsWith misses.
+ let realFilePath: string;
+ let realUiDir: string;
+ try {
+ realFilePath = fs.realpathSync(resolvedFilePath);
+ realUiDir = fs.realpathSync(uiDir);
+ } catch {
+ res.status(404).json({ error: "File not found" });
+ return;
+ }
+
+ const relative = path.relative(realUiDir, realFilePath);
+ if (relative.startsWith("..") || path.isAbsolute(relative)) {
+ res.status(403).json({ error: "Access denied" });
+ return;
+ }
+
+ if (!fileStat.isFile()) {
+ res.status(404).json({ error: "File not found" });
+ return;
+ }
+
+ // Step 6: Determine cache strategy based on filename
+ const basename = path.basename(resolvedFilePath);
+ const isContentHashed = CONTENT_HASH_PATTERN.test(basename);
+
+ // Step 7: Set cache headers
+ if (isContentHashed) {
+ res.set("Cache-Control", CACHE_CONTROL_IMMUTABLE);
+ } else {
+ res.set("Cache-Control", CACHE_CONTROL_REVALIDATE);
+
+ // Compute and set ETag for conditional request support
+ const etag = computeETag(fileStat.size, fileStat.mtimeMs);
+ res.set("ETag", etag);
+
+ // Check If-None-Match for 304 Not Modified
+ const ifNoneMatch = req.headers["if-none-match"];
+ if (ifNoneMatch === etag) {
+ res.status(304).end();
+ return;
+ }
+ }
+
+ // Step 8: Set Content-Type
+ const ext = path.extname(resolvedFilePath).toLowerCase();
+ const contentType = MIME_TYPES[ext];
+ if (contentType) {
+ res.set("Content-Type", contentType);
+ }
+
+ // Step 9: Set CORS headers (plugin UI may be loaded from different origin in dev)
+ res.set("Access-Control-Allow-Origin", "*");
+
+ // Step 10: Send the file
+ // The plugin source can live in Git worktrees (e.g. ".worktrees/...").
+ // `send` defaults to dotfiles:"ignore", which treats dot-directories as
+ // not found. We already enforce traversal safety above, so allow dot paths.
+ res.sendFile(resolvedFilePath, { dotfiles: "allow" }, (err) => {
+ if (err) {
+ log.error(
+ { err, pluginId: plugin.id, filePath: resolvedFilePath },
+ "plugin-ui-static: error sending file",
+ );
+ // Only send error if headers haven't been sent yet
+ if (!res.headersSent) {
+ res.status(500).json({ error: "Failed to serve file" });
+ }
+ }
+ });
+ });
+
+ return router;
+}
diff --git a/server/src/routes/plugins.ts b/server/src/routes/plugins.ts
new file mode 100644
index 0000000000..2d6382a9b3
--- /dev/null
+++ b/server/src/routes/plugins.ts
@@ -0,0 +1,2417 @@
+/**
+ * @fileoverview Plugin management REST API routes
+ *
+ * This module provides Express routes for managing the complete plugin lifecycle:
+ * - Listing and filtering plugins by status
+ * - Installing plugins from npm or local paths
+ * - Uninstalling plugins (soft delete or hard purge)
+ * - Enabling/disabling plugins
+ * - Running health diagnostics
+ * - Upgrading plugins
+ * - Retrieving UI slot contributions for frontend rendering
+ * - Discovering and executing plugin-contributed agent tools
+ *
+ * All routes require board-level authentication (assertBoard middleware).
+ *
+ * @module server/routes/plugins
+ * @see doc/plugins/PLUGIN_SPEC.md for the full plugin specification
+ */
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { Router } from "express";
+import type { Request, Response } from "express";
+import { and, desc, eq, gte } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import { companies, pluginLogs, pluginWebhookDeliveries } from "@paperclipai/db";
+import type {
+ PluginStatus,
+ PaperclipPluginManifestV1,
+ PluginBridgeErrorCode,
+ PluginLauncherRenderContextSnapshot,
+ UpdateCompanyPluginAvailability,
+} from "@paperclipai/shared";
+import {
+ PLUGIN_STATUSES,
+ updateCompanyPluginAvailabilitySchema,
+} from "@paperclipai/shared";
+import { pluginRegistryService } from "../services/plugin-registry.js";
+import { pluginLifecycleManager } from "../services/plugin-lifecycle.js";
+import { getPluginUiContributionMetadata, pluginLoader } from "../services/plugin-loader.js";
+import { logActivity } from "../services/activity-log.js";
+import { publishGlobalLiveEvent } from "../services/live-events.js";
+import type { PluginJobScheduler } from "../services/plugin-job-scheduler.js";
+import type { PluginJobStore } from "../services/plugin-job-store.js";
+import type { PluginWorkerManager } from "../services/plugin-worker-manager.js";
+import type { PluginStreamBus } from "../services/plugin-stream-bus.js";
+import type { PluginToolDispatcher } from "../services/plugin-tool-dispatcher.js";
+import type { ToolRunContext } from "@paperclipai/plugin-sdk";
+import { JsonRpcCallError, PLUGIN_RPC_ERROR_CODES } from "@paperclipai/plugin-sdk";
+import { assertBoard, assertCompanyAccess, getActorInfo } from "./authz.js";
+import { validateInstanceConfig } from "../services/plugin-config-validator.js";
+
+/** UI slot declaration extracted from plugin manifest */
+type PluginUiSlotDeclaration = NonNullable<NonNullable<PaperclipPluginManifestV1["ui"]>["slots"]>[number];
+/** Launcher declaration extracted from plugin manifest */
+type PluginLauncherDeclaration = NonNullable<PaperclipPluginManifestV1["launchers"]>[number];
+
+/**
+ * Normalized UI contribution for frontend slot host consumption.
+ * Only includes plugins in 'ready' state with non-empty slot declarations.
+ */
+type PluginUiContribution = {
+ pluginId: string;
+ pluginKey: string;
+ displayName: string;
+ version: string;
+ updatedAt: string;
+ /**
+ * Relative path within the plugin's UI directory to the entry module
+ * (e.g. `"index.js"`). The frontend constructs the full import URL as
+ * `/_plugins/${pluginId}/ui/${uiEntryFile}`.
+ */
+ uiEntryFile: string;
+ slots: PluginUiSlotDeclaration[];
+ launchers: PluginLauncherDeclaration[];
+};
+
+/** Request body for POST /api/plugins/install */
+interface PluginInstallRequest {
+ /** npm package name (e.g., @paperclip/plugin-linear) or local path */
+ packageName: string;
+ /** Target version for npm packages (optional, defaults to latest) */
+ version?: string;
+ /** True if packageName is a local filesystem path */
+ isLocalPath?: boolean;
+}
+
+interface AvailablePluginExample {
+ packageName: string;
+ pluginKey: string;
+ displayName: string;
+ description: string;
+ localPath: string;
+ tag: "example";
+}
+
+/** Response body for GET /api/plugins/:pluginId/health */
+interface PluginHealthCheckResult {
+ pluginId: string;
+ status: string;
+ healthy: boolean;
+ checks: Array<{
+ name: string;
+ passed: boolean;
+ message?: string;
+ }>;
+ lastError?: string;
+}
+
+/** UUID v4 regex used for plugin ID route resolution. */
+const UUID_REGEX =
+ /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "../../..");
+
+const BUNDLED_PLUGIN_EXAMPLES: AvailablePluginExample[] = [
+ {
+ packageName: "@paperclipai/plugin-hello-world-example",
+ pluginKey: "paperclip.hello-world-example",
+ displayName: "Hello World Widget (Example)",
+ description: "Reference UI plugin that adds a simple Hello World widget to the Paperclip dashboard.",
+ localPath: "packages/plugins/examples/plugin-hello-world-example",
+ tag: "example",
+ },
+ {
+ packageName: "@paperclipai/plugin-file-browser-example",
+ pluginKey: "paperclip-file-browser-example",
+ displayName: "File Browser (Example)",
+ description: "Example plugin that adds a Files link in project navigation plus a project detail file browser.",
+ localPath: "packages/plugins/examples/plugin-file-browser-example",
+ tag: "example",
+ },
+];
+
+function listBundledPluginExamples(): AvailablePluginExample[] {
+ return BUNDLED_PLUGIN_EXAMPLES.flatMap((plugin) => {
+ const absoluteLocalPath = path.resolve(REPO_ROOT, plugin.localPath);
+ if (!existsSync(absoluteLocalPath)) return [];
+ return [{ ...plugin, localPath: absoluteLocalPath }];
+ });
+}
+
+/**
+ * Resolve a plugin by either database ID or plugin key.
+ *
+ * Lookup order:
+ * - UUID-like IDs: getById first, then getByKey.
+ * - Scoped package keys (e.g. "@scope/name"): getByKey only, never getById.
+ * - Other non-UUID IDs: try getById first (test/memory registries may allow this),
+ * then fallback to getByKey. Any UUID parse error from getById is ignored.
+ *
+ * @param registry - The plugin registry service instance
+ * @param pluginId - Either a database UUID or plugin key (manifest id)
+ * @returns Plugin record or null if not found
+ */
+async function resolvePlugin(
+ registry: ReturnType<typeof pluginRegistryService>,
+ pluginId: string,
+) {
+ const isUuid = UUID_REGEX.test(pluginId);
+ const isScopedPackageKey = pluginId.startsWith("@") || pluginId.includes("/");
+
+ // Scoped package IDs are valid plugin keys but invalid UUIDs.
+ // Skip getById() entirely to avoid Postgres uuid parse errors.
+ if (isScopedPackageKey && !isUuid) {
+ return registry.getByKey(pluginId);
+ }
+
+ try {
+ const byId = await registry.getById(pluginId);
+ if (byId) return byId;
+ } catch (error) {
+ const maybeCode =
+ typeof error === "object" && error !== null && "code" in error
+ ? (error as { code?: unknown }).code
+ : undefined;
+ // Ignore invalid UUID cast errors and continue with key lookup.
+ if (maybeCode !== "22P02") {
+ throw error;
+ }
+ }
+
+ return registry.getByKey(pluginId);
+}
+
+async function isPluginAvailableForCompany(
+ registry: ReturnType<typeof pluginRegistryService>,
+ companyId: string,
+ pluginId: string,
+): Promise<boolean> {
+ const availability = await registry.getCompanyAvailability(companyId, pluginId);
+ return availability?.available === true;
+}
+
+/**
+ * Optional dependencies for plugin job scheduling routes.
+ *
+ * When provided, job-related routes (list jobs, list runs, trigger job) are
+ * mounted. When omitted, the routes return 501 Not Implemented.
+ */
+export interface PluginRouteJobDeps {
+ /** The job scheduler instance. */
+ scheduler: PluginJobScheduler;
+ /** The job persistence store. */
+ jobStore: PluginJobStore;
+}
+
+/**
+ * Optional dependencies for plugin webhook routes.
+ *
+ * When provided, the webhook ingestion route is enabled. When omitted,
+ * webhook POST requests return 501 Not Implemented.
+ */
+export interface PluginRouteWebhookDeps {
+ /** The worker manager for dispatching handleWebhook RPC calls. */
+ workerManager: PluginWorkerManager;
+}
+
+/**
+ * Optional dependencies for plugin tool routes.
+ *
+ * When provided, tool discovery and execution routes are enabled.
+ * When omitted, the tool routes return 501 Not Implemented.
+ */
+export interface PluginRouteToolDeps {
+ /** The tool dispatcher for listing and executing plugin tools. */
+ toolDispatcher: PluginToolDispatcher;
+}
+
+/**
+ * Optional dependencies for plugin UI bridge routes.
+ *
+ * When provided, the getData and performAction bridge proxy routes are enabled,
+ * allowing plugin UI components to communicate with their worker backend via
+ * `usePluginData()` and `usePluginAction()` hooks.
+ *
+ * @see PLUGIN_SPEC.md §13.8 — `getData`
+ * @see PLUGIN_SPEC.md §13.9 — `performAction`
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+export interface PluginRouteBridgeDeps {
+ /** The worker manager for dispatching getData/performAction RPC calls. */
+ workerManager: PluginWorkerManager;
+ /** Optional stream bus for SSE push from worker to UI. */
+ streamBus?: PluginStreamBus;
+}
+
+/** Request body for POST /api/plugins/tools/execute */
+interface PluginToolExecuteRequest {
+ /** Fully namespaced tool name (e.g., "acme.linear:search-issues"). */
+ tool: string;
+ /** Parameters matching the tool's declared JSON Schema. */
+ parameters?: unknown;
+ /** Agent run context. */
+ runContext: ToolRunContext;
+}
+
+/**
+ * Create Express router for plugin management API.
+ *
+ * Routes provided:
+ *
+ * | Method | Path | Description |
+ * |--------|------|-------------|
+ * | GET | /plugins | List all plugins (optional ?status= filter) |
+ * | GET | /plugins/ui-contributions | Get UI slots from ready plugins |
+ * | GET | /plugins/:pluginId | Get single plugin by ID or key |
+ * | POST | /plugins/install | Install from npm or local path |
+ * | DELETE | /plugins/:pluginId | Uninstall (optional ?purge=true) |
+ * | POST | /plugins/:pluginId/enable | Enable a plugin |
+ * | POST | /plugins/:pluginId/disable | Disable a plugin |
+ * | GET | /plugins/:pluginId/health | Run health diagnostics |
+ * | POST | /plugins/:pluginId/upgrade | Upgrade to newer version |
+ * | GET | /plugins/:pluginId/jobs | List jobs for a plugin |
+ * | GET | /plugins/:pluginId/jobs/:jobId/runs | List runs for a job |
+ * | POST | /plugins/:pluginId/jobs/:jobId/trigger | Manually trigger a job |
+ * | POST | /plugins/:pluginId/webhooks/:endpointKey | Receive inbound webhook |
+ * | GET | /plugins/tools | List all available plugin tools |
+ * | GET | /plugins/tools?pluginId=... | List tools for a specific plugin |
+ * | POST | /plugins/tools/execute | Execute a plugin tool |
+ * | GET | /plugins/:pluginId/config | Get current plugin config |
+ * | POST | /plugins/:pluginId/config | Save (upsert) plugin config |
+ * | POST | /plugins/:pluginId/config/test | Test config via validateConfig RPC |
+ * | GET | /companies/:companyId/plugins | List company-scoped plugin availability |
+ * | GET | /companies/:companyId/plugins/:pluginId | Get company-scoped plugin availability |
+ * | PUT | /companies/:companyId/plugins/:pluginId | Save company-scoped plugin availability/settings |
+ * | POST | /plugins/:pluginId/bridge/data | Proxy getData to plugin worker |
+ * | POST | /plugins/:pluginId/bridge/action | Proxy performAction to plugin worker |
+ * | POST | /plugins/:pluginId/data/:key | Proxy getData to plugin worker (key in URL) |
+ * | POST | /plugins/:pluginId/actions/:key | Proxy performAction to plugin worker (key in URL) |
+ * | GET | /plugins/:pluginId/bridge/stream/:channel | SSE stream from worker to UI |
+ * | GET | /plugins/:pluginId/dashboard | Aggregated health dashboard data |
+ *
+ * **Route Ordering Note:** Static routes (like /ui-contributions, /tools) must be
+ * registered before parameterized routes (like /:pluginId) to prevent Express from
+ * matching them as a plugin ID.
+ *
+ * @param db - Database connection instance
+ * @param jobDeps - Optional job scheduling dependencies
+ * @param webhookDeps - Optional webhook ingestion dependencies
+ * @param toolDeps - Optional tool dispatcher dependencies
+ * @param bridgeDeps - Optional bridge proxy dependencies for getData/performAction
+ * @returns Express router with plugin routes mounted
+ */
+export function pluginRoutes(
+ db: Db,
+ loader: ReturnType<typeof pluginLoader>,
+ jobDeps?: PluginRouteJobDeps,
+ webhookDeps?: PluginRouteWebhookDeps,
+ toolDeps?: PluginRouteToolDeps,
+ bridgeDeps?: PluginRouteBridgeDeps,
+) {
+ const router = Router();
+ const registry = pluginRegistryService(db);
+ const lifecycle = pluginLifecycleManager(db, {
+ loader,
+ workerManager: bridgeDeps?.workerManager ?? webhookDeps?.workerManager,
+ });
+
+ async function resolvePluginAuditCompanyIds(req: Request): Promise<string[]> {
+ if (typeof (db as { select?: unknown }).select === "function") {
+ const rows = await db
+ .select({ id: companies.id })
+ .from(companies);
+ return rows.map((row) => row.id);
+ }
+
+ if (req.actor.type === "agent" && req.actor.companyId) {
+ return [req.actor.companyId];
+ }
+
+ if (req.actor.type === "board") {
+ return req.actor.companyIds ?? [];
+ }
+
+ return [];
+ }
+
+ async function logPluginMutationActivity(
+ req: Request,
+ action: string,
+ entityId: string,
+ details: Record<string, unknown>,
+ ): Promise<void> {
+ const companyIds = await resolvePluginAuditCompanyIds(req);
+ if (companyIds.length === 0) return;
+
+ const actor = getActorInfo(req);
+ await Promise.all(companyIds.map((companyId) =>
+ logActivity(db, {
+ companyId,
+ actorType: actor.actorType,
+ actorId: actor.actorId,
+ agentId: actor.agentId,
+ runId: actor.runId,
+ action,
+ entityType: "plugin",
+ entityId,
+ details,
+ })));
+ }
+
+ /**
+ * GET /api/plugins
+ *
+ * List all installed plugins, optionally filtered by lifecycle status.
+ *
+ * Query params:
+ * - `status` (optional): Filter by lifecycle status. Must be one of the
+ * values in `PLUGIN_STATUSES` (`installed`, `ready`, `error`,
+ * `upgrade_pending`, `uninstalled`). Returns HTTP 400 if the value is
+ * not a recognised status string.
+ *
+ * Response: `PluginRecord[]`
+ */
+ router.get("/plugins", async (req, res) => {
+ assertBoard(req);
+ const rawStatus = req.query.status;
+ if (rawStatus !== undefined) {
+ if (typeof rawStatus !== "string" || !(PLUGIN_STATUSES as readonly string[]).includes(rawStatus)) {
+ res.status(400).json({
+ error: `Invalid status '${String(rawStatus)}'. Must be one of: ${PLUGIN_STATUSES.join(", ")}`,
+ });
+ return;
+ }
+ }
+ const status = rawStatus as PluginStatus | undefined;
+ const plugins = status
+ ? await registry.listByStatus(status)
+ : await registry.listInstalled();
+ res.json(plugins);
+ });
+
+ /**
+ * GET /api/plugins/examples
+ *
+ * Return first-party example plugins bundled in this repo, if present.
+ * These can be installed through the normal local-path install flow.
+ */
+ router.get("/plugins/examples", async (req, res) => {
+ assertBoard(req);
+ res.json(listBundledPluginExamples());
+ });
+
+ // IMPORTANT: Static routes must come before parameterized routes
+ // to avoid Express matching "ui-contributions" as a :pluginId
+
+ /**
+ * GET /api/plugins/ui-contributions
+ *
+ * Return UI contributions from all plugins in 'ready' state.
+ * Used by the frontend to discover plugin UI slots and launcher metadata.
+ *
+ * The response is normalized for the frontend slot host:
+ * - Only includes plugins with at least one declared UI slot or launcher
+ * - Excludes plugins with null/missing manifestJson (defensive)
+ * - Slots are extracted from manifest.ui.slots
+ * - Launchers are aggregated from legacy manifest.launchers and manifest.ui.launchers
+ *
+ * Query params:
+ * - `companyId` (optional): filters out plugins disabled for the target
+ * company and applies `assertCompanyAccess`
+ *
+ * Example response:
+ * ```json
+ * [
+ * {
+ * "pluginId": "plg_123",
+ * "pluginKey": "paperclip.claude-usage",
+ * "displayName": "Claude Usage",
+ * "version": "1.0.0",
+ * "uiEntryFile": "index.js",
+ * "slots": [],
+ * "launchers": [
+ * {
+ * "id": "claude-usage-toolbar",
+ * "displayName": "Claude Usage",
+ * "placementZone": "toolbarButton",
+ * "action": { "type": "openModal", "target": "ClaudeUsageView" },
+ * "render": { "environment": "hostOverlay", "bounds": "wide" }
+ * }
+ * ]
+ * }
+ * ]
+ * ```
+ *
+ * Response: PluginUiContribution[]
+ */
+ router.get("/plugins/ui-contributions", async (req, res) => {
+ assertBoard(req);
+ const companyId = typeof req.query.companyId === "string" ? req.query.companyId : undefined;
+ if (companyId) {
+ assertCompanyAccess(req, companyId);
+ }
+
+ const plugins = await registry.listByStatus("ready");
+ const availablePluginIds = companyId
+ ? new Set(
+ (await registry.listCompanyAvailability(companyId, { available: true }))
+ .map((entry) => entry.pluginId),
+ )
+ : null;
+
+ const contributions: PluginUiContribution[] = plugins
+ .filter((plugin) => availablePluginIds === null || availablePluginIds.has(plugin.id))
+ .map((plugin) => {
+ // Safety check: manifestJson should always exist for ready plugins, but guard against null
+ const manifest = plugin.manifestJson;
+ if (!manifest) return null;
+
+ const uiMetadata = getPluginUiContributionMetadata(manifest);
+ if (!uiMetadata) return null;
+
+ return {
+ pluginId: plugin.id,
+ pluginKey: plugin.pluginKey,
+ displayName: manifest.displayName,
+ version: plugin.version,
+ updatedAt: plugin.updatedAt.toISOString(),
+ uiEntryFile: uiMetadata.uiEntryFile,
+ slots: uiMetadata.slots,
+ launchers: uiMetadata.launchers,
+ };
+ })
+ .filter((item): item is PluginUiContribution => item !== null);
+ res.json(contributions);
+ });
+
+ // ===========================================================================
+ // Company-scoped plugin settings / availability routes
+ // ===========================================================================
+
+ /**
+ * GET /api/companies/:companyId/plugins
+ *
+ * List every installed plugin as it applies to a specific company. Plugins
+ * are enabled by default; rows in `plugin_company_settings` only store
+ * explicit overrides and any company-scoped settings payload.
+ *
+ * Query params:
+ * - `available` (optional): `true` or `false` filter
+ */
+ router.get("/companies/:companyId/plugins", async (req, res) => {
+ assertBoard(req);
+ const { companyId } = req.params;
+ assertCompanyAccess(req, companyId);
+
+ let available: boolean | undefined;
+ const rawAvailable = req.query.available;
+ if (rawAvailable !== undefined) {
+ if (rawAvailable === "true") available = true;
+ else if (rawAvailable === "false") available = false;
+ else {
+ res.status(400).json({ error: '"available" must be "true" or "false"' });
+ return;
+ }
+ }
+
+ const result = await registry.listCompanyAvailability(companyId, { available });
+ res.json(result);
+ });
+
+ /**
+ * GET /api/companies/:companyId/plugins/:pluginId
+ *
+ * Resolve one plugin's effective availability for a company, whether that
+ * result comes from the default-enabled baseline or a persisted override row.
+ */
+ router.get("/companies/:companyId/plugins/:pluginId", async (req, res) => {
+ assertBoard(req);
+ const { companyId, pluginId } = req.params;
+ assertCompanyAccess(req, companyId);
+
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin || plugin.status === "uninstalled") {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ const result = await registry.getCompanyAvailability(companyId, plugin.id);
+ if (!result) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ res.json(result);
+ });
+
+ /**
+ * PUT /api/companies/:companyId/plugins/:pluginId
+ *
+ * Persist a company-scoped availability override. This never changes the
+ * instance-wide install state of the plugin; it only controls whether the
+ * selected company can see UI contributions and invoke plugin-backed actions.
+ */
+ router.put("/companies/:companyId/plugins/:pluginId", async (req, res) => {
+ assertBoard(req);
+ const { companyId, pluginId } = req.params;
+ assertCompanyAccess(req, companyId);
+
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin || plugin.status === "uninstalled") {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ const parsed = updateCompanyPluginAvailabilitySchema.safeParse(req.body);
+ if (!parsed.success) {
+ res.status(400).json({ error: parsed.error.issues[0]?.message ?? "Invalid request body" });
+ return;
+ }
+
+ try {
+ const result = await registry.updateCompanyAvailability(
+ companyId,
+ plugin.id,
+ parsed.data as UpdateCompanyPluginAvailability,
+ );
+ const actor = getActorInfo(req);
+ await logActivity(db, {
+ companyId,
+ actorType: actor.actorType,
+ actorId: actor.actorId,
+ agentId: actor.agentId,
+ runId: actor.runId,
+ action: "plugin.company_settings.updated",
+ entityType: "plugin_company_settings",
+ entityId: `${companyId}:${plugin.id}`,
+ details: {
+ pluginId: plugin.id,
+ pluginKey: plugin.pluginKey,
+ available: result.available,
+ settingsJson: result.settingsJson,
+ lastError: result.lastError,
+ },
+ });
+ res.json(result);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ res.status(400).json({ error: message });
+ }
+ });
+
+ // ===========================================================================
+ // Tool discovery and execution routes
+ // ===========================================================================
+
+ /**
+ * GET /api/plugins/tools
+ *
+ * List all available plugin-contributed tools in an agent-friendly format.
+ *
+ * Query params:
+ * - `pluginId` (optional): Filter to tools from a specific plugin
+ *
+ * Response: `AgentToolDescriptor[]`
+ * Errors: 501 if tool dispatcher is not configured
+ */
+ router.get("/plugins/tools", async (req, res) => {
+ assertBoard(req);
+
+ if (!toolDeps) {
+ res.status(501).json({ error: "Plugin tool dispatch is not enabled" });
+ return;
+ }
+
+ const pluginId = req.query.pluginId as string | undefined;
+ const companyId = typeof req.query.companyId === "string" ? req.query.companyId : undefined;
+ if (companyId) {
+ assertCompanyAccess(req, companyId);
+ }
+
+ const filter = pluginId ? { pluginId } : undefined;
+ const tools = toolDeps.toolDispatcher.listToolsForAgent(filter);
+ if (!companyId) {
+ res.json(tools);
+ return;
+ }
+
+ const availablePluginIds = new Set(
+ (await registry.listCompanyAvailability(companyId, { available: true }))
+ .map((entry) => entry.pluginId),
+ );
+ res.json(tools.filter((tool) => availablePluginIds.has(tool.pluginId)));
+ });
+
+ /**
+ * Reject company-scoped plugin access when the plugin is disabled for the
+ * target company. This guard is reused across UI bridge and tool execution
+ * endpoints so every runtime surface honors the same availability rule.
+ */
+ async function enforceCompanyPluginAvailability(
+ companyId: string,
+ pluginId: string,
+ res: Response,
+ ): Promise<boolean> {
+ if (!await isPluginAvailableForCompany(registry, companyId, pluginId)) {
+ res.status(403).json({
+ error: `Plugin "${pluginId}" is not enabled for company "${companyId}"`,
+ });
+ return false;
+ }
+
+ return true;
+ }
+
+ /**
+ * POST /api/plugins/tools/execute
+ *
+ * Execute a plugin-contributed tool by its namespaced name.
+ *
+ * This is the primary endpoint used by the agent service to invoke
+ * plugin tools during an agent run.
+ *
+ * Request body:
+ * - `tool`: Fully namespaced tool name (e.g., "acme.linear:search-issues")
+ * - `parameters`: Parameters matching the tool's declared JSON Schema
+ * - `runContext`: Agent run context with agentId, runId, companyId, projectId
+ *
+ * Response: `ToolExecutionResult`
+ * Errors:
+ * - 400 if request validation fails
+ * - 404 if tool is not found
+ * - 501 if tool dispatcher is not configured
+ * - 502 if the plugin worker is unavailable or the RPC call fails
+ */
+ router.post("/plugins/tools/execute", async (req, res) => {
+ assertBoard(req);
+
+ if (!toolDeps) {
+ res.status(501).json({ error: "Plugin tool dispatch is not enabled" });
+ return;
+ }
+
+ const body = (req.body as PluginToolExecuteRequest | undefined);
+ if (!body) {
+ res.status(400).json({ error: "Request body is required" });
+ return;
+ }
+
+ const { tool, parameters, runContext } = body;
+
+ // Validate required fields
+ if (!tool || typeof tool !== "string") {
+ res.status(400).json({ error: '"tool" is required and must be a string' });
+ return;
+ }
+
+ if (!runContext || typeof runContext !== "object") {
+ res.status(400).json({ error: '"runContext" is required and must be an object' });
+ return;
+ }
+
+ if (!runContext.agentId || !runContext.runId || !runContext.companyId || !runContext.projectId) {
+ res.status(400).json({
+ error: '"runContext" must include agentId, runId, companyId, and projectId',
+ });
+ return;
+ }
+
+ assertCompanyAccess(req, runContext.companyId);
+
+ // Verify the tool exists
+ const registeredTool = toolDeps.toolDispatcher.getTool(tool);
+ if (!registeredTool) {
+ res.status(404).json({ error: `Tool "${tool}" not found` });
+ return;
+ }
+
+ if (!await enforceCompanyPluginAvailability(runContext.companyId, registeredTool.pluginDbId, res)) {
+ return;
+ }
+
+ try {
+ const result = await toolDeps.toolDispatcher.executeTool(
+ tool,
+ parameters ?? {},
+ runContext,
+ );
+ res.json(result);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+
+ // Distinguish between "worker not running" (502) and other errors (500)
+ if (message.includes("not running") || message.includes("worker")) {
+ res.status(502).json({ error: message });
+ } else {
+ res.status(500).json({ error: message });
+ }
+ }
+ });
+
+ /**
+ * POST /api/plugins/install
+ *
+ * Install a plugin from npm or a local filesystem path.
+ *
+ * Request body:
+ * - packageName: npm package name or local path (required)
+ * - version: Target version for npm packages (optional)
+ * - isLocalPath: Set true if packageName is a local path
+ *
+ * The installer:
+ * 1. Downloads from npm or loads from local path
+ * 2. Validates the manifest (schema + capability consistency)
+ * 3. Registers in the database
+ * 4. Transitions to `ready` state if no new capability approval is needed
+ *
+ * Response: `PluginRecord`
+ *
+ * Errors:
+ * - `400` — validation failure or install error (package not found, bad manifest, etc.)
+ * - `500` — installation succeeded but manifest is missing (indicates a loader bug)
+ */
+ router.post("/plugins/install", async (req, res) => {
+ assertBoard(req);
+ const { packageName, version, isLocalPath } = req.body as PluginInstallRequest;
+
+ // Input validation
+ if (!packageName || typeof packageName !== "string") {
+ res.status(400).json({ error: "packageName is required and must be a string" });
+ return;
+ }
+
+ if (version !== undefined && typeof version !== "string") {
+ res.status(400).json({ error: "version must be a string if provided" });
+ return;
+ }
+
+ if (isLocalPath !== undefined && typeof isLocalPath !== "boolean") {
+ res.status(400).json({ error: "isLocalPath must be a boolean if provided" });
+ return;
+ }
+
+ // Validate package name format
+ const trimmedPackage = packageName.trim();
+ if (trimmedPackage.length === 0) {
+ res.status(400).json({ error: "packageName cannot be empty" });
+ return;
+ }
+
+ // Basic security check for package name (prevent injection)
+ if (!isLocalPath && /[<>:"|?*]/.test(trimmedPackage)) {
+ res.status(400).json({ error: "packageName contains invalid characters" });
+ return;
+ }
+
+ try {
+ const installOptions = isLocalPath
+ ? { localPath: trimmedPackage }
+ : { packageName: trimmedPackage, version: version?.trim() };
+
+ const discovered = await loader.installPlugin(installOptions);
+
+ if (!discovered.manifest) {
+ res.status(500).json({ error: "Plugin installed but manifest is missing" });
+ return;
+ }
+
+ // Transition to ready state
+ const existingPlugin = await registry.getByKey(discovered.manifest.id);
+ if (existingPlugin) {
+ await lifecycle.load(existingPlugin.id);
+ // Plugins should be enabled by default for all companies after install.
+ // Best-effort: default behavior is still enabled when no row exists.
+ try {
+ await registry.seedEnabledForAllCompanies(existingPlugin.id);
+ } catch {
+ // no-op
+ }
+ const updated = await registry.getById(existingPlugin.id);
+ await logPluginMutationActivity(req, "plugin.installed", existingPlugin.id, {
+ pluginId: existingPlugin.id,
+ pluginKey: existingPlugin.pluginKey,
+ packageName: updated?.packageName ?? existingPlugin.packageName,
+ version: updated?.version ?? existingPlugin.version,
+ source: isLocalPath ? "local_path" : "npm",
+ });
+ publishGlobalLiveEvent({ type: "plugin.ui.updated", payload: { pluginId: existingPlugin.id, action: "installed" } });
+ res.json(updated);
+ } else {
+ // This shouldn't happen since installPlugin already registers in the DB
+ res.status(500).json({ error: "Plugin installed but not found in registry" });
+ }
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ res.status(400).json({ error: message });
+ }
+ });
+
+ // ===========================================================================
+ // UI Bridge proxy routes (getData / performAction)
+ // ===========================================================================
+
+ /** Request body for POST /api/plugins/:pluginId/bridge/data */
+ interface PluginBridgeDataRequest {
+ /** Plugin-defined data key (e.g. `"sync-health"`). */
+ key: string;
+ /** Optional company scope for enforcing company plugin availability. */
+ companyId?: string;
+ /** Optional context and query parameters from the UI. */
+ params?: Record<string, unknown>;
+ /** Optional host launcher/render metadata for the worker bridge call. */
+ renderEnvironment?: PluginLauncherRenderContextSnapshot | null;
+ }
+
+ /** Request body for POST /api/plugins/:pluginId/bridge/action */
+ interface PluginBridgeActionRequest {
+ /** Plugin-defined action key (e.g. `"resync"`). */
+ key: string;
+ /** Optional company scope for enforcing company plugin availability. */
+ companyId?: string;
+ /** Optional parameters from the UI. */
+ params?: Record<string, unknown>;
+ /** Optional host launcher/render metadata for the worker bridge call. */
+ renderEnvironment?: PluginLauncherRenderContextSnapshot | null;
+ }
+
+ /** Response envelope for bridge errors. */
+ interface PluginBridgeErrorResponse {
+ code: PluginBridgeErrorCode;
+ message: string;
+ details?: unknown;
+ }
+
+ /**
+ * Map a worker RPC error to a bridge-level error code.
+ *
+ * JsonRpcCallError carries numeric codes from the plugin RPC error code space.
+ * This helper maps them to the string error codes defined in PluginBridgeErrorCode.
+ *
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+ function mapRpcErrorToBridgeError(err: unknown): PluginBridgeErrorResponse {
+ if (err instanceof JsonRpcCallError) {
+ switch (err.code) {
+ case PLUGIN_RPC_ERROR_CODES.WORKER_UNAVAILABLE:
+ return {
+ code: "WORKER_UNAVAILABLE",
+ message: err.message,
+ details: err.data,
+ };
+ case PLUGIN_RPC_ERROR_CODES.CAPABILITY_DENIED:
+ return {
+ code: "CAPABILITY_DENIED",
+ message: err.message,
+ details: err.data,
+ };
+ case PLUGIN_RPC_ERROR_CODES.TIMEOUT:
+ return {
+ code: "TIMEOUT",
+ message: err.message,
+ details: err.data,
+ };
+ case PLUGIN_RPC_ERROR_CODES.WORKER_ERROR:
+ return {
+ code: "WORKER_ERROR",
+ message: err.message,
+ details: err.data,
+ };
+ default:
+ return {
+ code: "UNKNOWN",
+ message: err.message,
+ details: err.data,
+ };
+ }
+ }
+
+ const message = err instanceof Error ? err.message : String(err);
+
+ // Worker not running — surface as WORKER_UNAVAILABLE
+ if (message.includes("not running") || message.includes("not registered")) {
+ return {
+ code: "WORKER_UNAVAILABLE",
+ message,
+ };
+ }
+
+ return {
+ code: "UNKNOWN",
+ message,
+ };
+ }
+
+ /**
+ * POST /api/plugins/:pluginId/bridge/data
+ *
+ * Proxy a `getData` call from the plugin UI to the plugin worker.
+ *
+ * This is the server-side half of the `usePluginData(key, params)` bridge hook.
+ * The frontend sends a POST with the data key and optional params; the host
+ * forwards the call to the worker via the `getData` RPC method and returns
+ * the result.
+ *
+ * Request body:
+ * - `key`: Plugin-defined data key (e.g. `"sync-health"`)
+ * - `params`: Optional query parameters forwarded to the worker handler
+ *
+ * Response: The raw result from the worker's `getData` handler
+ *
+ * Error response body follows the `PluginBridgeError` shape:
+ * `{ code: PluginBridgeErrorCode, message: string, details?: unknown }`
+ *
+ * Errors:
+ * - 400 if request validation fails
+ * - 404 if plugin not found
+ * - 501 if bridge deps are not configured
+ * - 502 if the worker is unavailable or returns an error
+ *
+ * @see PLUGIN_SPEC.md §13.8 — `getData`
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+ router.post("/plugins/:pluginId/bridge/data", async (req, res) => {
+ assertBoard(req);
+
+ if (!bridgeDeps) {
+ res.status(501).json({ error: "Plugin bridge is not enabled" });
+ return;
+ }
+
+ const { pluginId } = req.params;
+
+ // Resolve plugin
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ // Validate plugin is in ready state
+ if (plugin.status !== "ready") {
+ const bridgeError: PluginBridgeErrorResponse = {
+ code: "WORKER_UNAVAILABLE",
+ message: `Plugin is not ready (current status: ${plugin.status})`,
+ };
+ res.status(502).json(bridgeError);
+ return;
+ }
+
+ // Validate request body
+ const body = req.body as PluginBridgeDataRequest | undefined;
+ if (!body || !body.key || typeof body.key !== "string") {
+ res.status(400).json({ error: '"key" is required and must be a string' });
+ return;
+ }
+
+ if (body.companyId) {
+ assertCompanyAccess(req, body.companyId);
+ if (!await enforceCompanyPluginAvailability(body.companyId, plugin.id, res)) {
+ return;
+ }
+ }
+
+ try {
+ const result = await bridgeDeps.workerManager.call(
+ plugin.id,
+ "getData",
+ {
+ key: body.key,
+ params: body.params ?? {},
+ renderEnvironment: body.renderEnvironment ?? null,
+ },
+ );
+ res.json({ data: result });
+ } catch (err) {
+ const bridgeError = mapRpcErrorToBridgeError(err);
+ res.status(502).json(bridgeError);
+ }
+ });
+
+ /**
+ * POST /api/plugins/:pluginId/bridge/action
+ *
+ * Proxy a `performAction` call from the plugin UI to the plugin worker.
+ *
+ * This is the server-side half of the `usePluginAction(key)` bridge hook.
+ * The frontend sends a POST with the action key and optional params; the host
+ * forwards the call to the worker via the `performAction` RPC method and
+ * returns the result.
+ *
+ * Request body:
+ * - `key`: Plugin-defined action key (e.g. `"resync"`)
+ * - `params`: Optional parameters forwarded to the worker handler
+ *
+ * Response: The raw result from the worker's `performAction` handler
+ *
+ * Error response body follows the `PluginBridgeError` shape:
+ * `{ code: PluginBridgeErrorCode, message: string, details?: unknown }`
+ *
+ * Errors:
+ * - 400 if request validation fails
+ * - 404 if plugin not found
+ * - 501 if bridge deps are not configured
+ * - 502 if the worker is unavailable or returns an error
+ *
+ * @see PLUGIN_SPEC.md §13.9 — `performAction`
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+ router.post("/plugins/:pluginId/bridge/action", async (req, res) => {
+ assertBoard(req);
+
+ if (!bridgeDeps) {
+ res.status(501).json({ error: "Plugin bridge is not enabled" });
+ return;
+ }
+
+ const { pluginId } = req.params;
+
+ // Resolve plugin
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ // Validate plugin is in ready state
+ if (plugin.status !== "ready") {
+ const bridgeError: PluginBridgeErrorResponse = {
+ code: "WORKER_UNAVAILABLE",
+ message: `Plugin is not ready (current status: ${plugin.status})`,
+ };
+ res.status(502).json(bridgeError);
+ return;
+ }
+
+ // Validate request body
+ const body = req.body as PluginBridgeActionRequest | undefined;
+ if (!body || !body.key || typeof body.key !== "string") {
+ res.status(400).json({ error: '"key" is required and must be a string' });
+ return;
+ }
+
+ if (body.companyId) {
+ assertCompanyAccess(req, body.companyId);
+ if (!await enforceCompanyPluginAvailability(body.companyId, plugin.id, res)) {
+ return;
+ }
+ }
+
+ try {
+ const result = await bridgeDeps.workerManager.call(
+ plugin.id,
+ "performAction",
+ {
+ key: body.key,
+ params: body.params ?? {},
+ renderEnvironment: body.renderEnvironment ?? null,
+ },
+ );
+ res.json({ data: result });
+ } catch (err) {
+ const bridgeError = mapRpcErrorToBridgeError(err);
+ res.status(502).json(bridgeError);
+ }
+ });
+
+ // ===========================================================================
+ // URL-keyed bridge routes (key as path parameter)
+ // ===========================================================================
+
+ /**
+ * POST /api/plugins/:pluginId/data/:key
+ *
+ * Proxy a `getData` call from the plugin UI to the plugin worker, with the
+ * data key specified as a URL path parameter instead of in the request body.
+ *
+ * This is a REST-friendly alternative to `POST /plugins/:pluginId/bridge/data`.
+ * The frontend bridge hooks use this endpoint for cleaner URLs.
+ *
+ * Request body (optional):
+ * - `params`: Optional query parameters forwarded to the worker handler
+ *
+ * Response: The raw result from the worker's `getData` handler wrapped as `{ data: T }`
+ *
+ * Error response body follows the `PluginBridgeError` shape:
+ * `{ code: PluginBridgeErrorCode, message: string, details?: unknown }`
+ *
+ * Errors:
+ * - 404 if plugin not found
+ * - 501 if bridge deps are not configured
+ * - 502 if the worker is unavailable or returns an error
+ *
+ * @see PLUGIN_SPEC.md §13.8 — `getData`
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+ router.post("/plugins/:pluginId/data/:key", async (req, res) => {
+ assertBoard(req);
+
+ if (!bridgeDeps) {
+ res.status(501).json({ error: "Plugin bridge is not enabled" });
+ return;
+ }
+
+ const { pluginId, key } = req.params;
+
+ // Resolve plugin
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ // Validate plugin is in ready state
+ if (plugin.status !== "ready") {
+ const bridgeError: PluginBridgeErrorResponse = {
+ code: "WORKER_UNAVAILABLE",
+ message: `Plugin is not ready (current status: ${plugin.status})`,
+ };
+ res.status(502).json(bridgeError);
+ return;
+ }
+
+ const body = req.body as {
+ companyId?: string;
+ params?: Record<string, unknown>;
+ renderEnvironment?: PluginLauncherRenderContextSnapshot | null;
+ } | undefined;
+
+ if (body?.companyId) {
+ assertCompanyAccess(req, body.companyId);
+ if (!await enforceCompanyPluginAvailability(body.companyId, plugin.id, res)) {
+ return;
+ }
+ }
+
+ try {
+ const result = await bridgeDeps.workerManager.call(
+ plugin.id,
+ "getData",
+ {
+ key,
+ params: body?.params ?? {},
+ renderEnvironment: body?.renderEnvironment ?? null,
+ },
+ );
+ res.json({ data: result });
+ } catch (err) {
+ const bridgeError = mapRpcErrorToBridgeError(err);
+ res.status(502).json(bridgeError);
+ }
+ });
+
+ /**
+ * POST /api/plugins/:pluginId/actions/:key
+ *
+ * Proxy a `performAction` call from the plugin UI to the plugin worker, with
+ * the action key specified as a URL path parameter instead of in the request body.
+ *
+ * This is a REST-friendly alternative to `POST /plugins/:pluginId/bridge/action`.
+ * The frontend bridge hooks use this endpoint for cleaner URLs.
+ *
+ * Request body (optional):
+ * - `params`: Optional parameters forwarded to the worker handler
+ *
+ * Response: The raw result from the worker's `performAction` handler wrapped as `{ data: T }`
+ *
+ * Error response body follows the `PluginBridgeError` shape:
+ * `{ code: PluginBridgeErrorCode, message: string, details?: unknown }`
+ *
+ * Errors:
+ * - 404 if plugin not found
+ * - 501 if bridge deps are not configured
+ * - 502 if the worker is unavailable or returns an error
+ *
+ * @see PLUGIN_SPEC.md §13.9 — `performAction`
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+ router.post("/plugins/:pluginId/actions/:key", async (req, res) => {
+ assertBoard(req);
+
+ if (!bridgeDeps) {
+ res.status(501).json({ error: "Plugin bridge is not enabled" });
+ return;
+ }
+
+ const { pluginId, key } = req.params;
+
+ // Resolve plugin
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ // Validate plugin is in ready state
+ if (plugin.status !== "ready") {
+ const bridgeError: PluginBridgeErrorResponse = {
+ code: "WORKER_UNAVAILABLE",
+ message: `Plugin is not ready (current status: ${plugin.status})`,
+ };
+ res.status(502).json(bridgeError);
+ return;
+ }
+
+ const body = req.body as {
+ companyId?: string;
+ params?: Record<string, unknown>;
+ renderEnvironment?: PluginLauncherRenderContextSnapshot | null;
+ } | undefined;
+
+ if (body?.companyId) {
+ assertCompanyAccess(req, body.companyId);
+ if (!await enforceCompanyPluginAvailability(body.companyId, plugin.id, res)) {
+ return;
+ }
+ }
+
+ try {
+ const result = await bridgeDeps.workerManager.call(
+ plugin.id,
+ "performAction",
+ {
+ key,
+ params: body?.params ?? {},
+ renderEnvironment: body?.renderEnvironment ?? null,
+ },
+ );
+ res.json({ data: result });
+ } catch (err) {
+ const bridgeError = mapRpcErrorToBridgeError(err);
+ res.status(502).json(bridgeError);
+ }
+ });
+
+ // ===========================================================================
+ // SSE stream bridge route
+ // ===========================================================================
+
+ /**
+ * GET /api/plugins/:pluginId/bridge/stream/:channel
+ *
+ * Server-Sent Events endpoint for real-time streaming from plugin worker to UI.
+ *
+ * The worker pushes events via `ctx.streams.emit(channel, event)` which arrive
+ * as JSON-RPC notifications to the host, get published on the PluginStreamBus,
+ * and are fanned out to all connected SSE clients matching (pluginId, channel,
+ * companyId).
+ *
+ * Query parameters:
+ * - `companyId` (required): Scope events to a specific company
+ *
+ * SSE event types:
+ * - `message`: A data event from the worker (default)
+ * - `open`: The worker opened the stream channel
+ * - `close`: The worker closed the stream channel — client should disconnect
+ *
+ * Errors:
+ * - 400 if companyId is missing
+ * - 404 if plugin not found
+ * - 501 if bridge deps or stream bus are not configured
+ */
+ router.get("/plugins/:pluginId/bridge/stream/:channel", async (req, res) => {
+ assertBoard(req);
+
+ if (!bridgeDeps?.streamBus) {
+ res.status(501).json({ error: "Plugin stream bridge is not enabled" });
+ return;
+ }
+
+ const { pluginId, channel } = req.params;
+ const companyId = req.query.companyId as string | undefined;
+
+ if (!companyId) {
+ res.status(400).json({ error: '"companyId" query parameter is required' });
+ return;
+ }
+
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ assertCompanyAccess(req, companyId);
+
+ if (!await enforceCompanyPluginAvailability(companyId, plugin.id, res)) {
+ return;
+ }
+
+ // Set SSE headers
+ res.writeHead(200, {
+ "Content-Type": "text/event-stream",
+ "Cache-Control": "no-cache",
+ "Connection": "keep-alive",
+ "X-Accel-Buffering": "no",
+ });
+ res.flushHeaders();
+
+ // Send initial comment to establish the connection
+ res.write(":ok\n\n");
+
+ let unsubscribed = false;
+ const safeUnsubscribe = () => {
+ if (!unsubscribed) {
+ unsubscribed = true;
+ unsubscribe();
+ }
+ };
+
+ const unsubscribe = bridgeDeps.streamBus.subscribe(
+ plugin.id,
+ channel,
+ companyId,
+ (event, eventType) => {
+ if (unsubscribed || !res.writable) return;
+ try {
+ if (eventType !== "message") {
+ res.write(`event: ${eventType}\n`);
+ }
+ res.write(`data: ${JSON.stringify(event)}\n\n`);
+ } catch {
+ // Connection closed or write error — stop delivering
+ safeUnsubscribe();
+ }
+ },
+ );
+
+ req.on("close", safeUnsubscribe);
+ res.on("error", safeUnsubscribe);
+ });
+
+ /**
+ * GET /api/plugins/:pluginId
+ *
+ * Get detailed information about a single plugin.
+ *
+ * The :pluginId parameter accepts either:
+ * - Database UUID (e.g., "abc123-def456")
+ * - Plugin key (e.g., "acme.linear")
+ *
+ * Response: PluginRecord
+ * Errors: 404 if plugin not found
+ */
+ router.get("/plugins/:pluginId", async (req, res) => {
+ assertBoard(req);
+ const { pluginId } = req.params;
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ // Enrich with worker capabilities when available
+ const worker = bridgeDeps?.workerManager.getWorker(plugin.id);
+ const supportsConfigTest = worker
+ ? worker.supportedMethods.includes("validateConfig")
+ : false;
+
+ res.json({ ...plugin, supportsConfigTest });
+ });
+
+ /**
+ * DELETE /api/plugins/:pluginId
+ *
+ * Uninstall a plugin.
+ *
+ * Query params:
+ * - purge: If "true", permanently delete all plugin data (hard delete)
+ * Otherwise, soft-delete with 30-day data retention
+ *
+ * Response: PluginRecord (the deleted record)
+ * Errors: 404 if plugin not found, 400 for lifecycle errors
+ */
+ router.delete("/plugins/:pluginId", async (req, res) => {
+ assertBoard(req);
+ const { pluginId } = req.params;
+ const purge = req.query.purge === "true";
+
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ try {
+ const result = await lifecycle.unload(plugin.id, purge);
+ await logPluginMutationActivity(req, "plugin.uninstalled", plugin.id, {
+ pluginId: plugin.id,
+ pluginKey: plugin.pluginKey,
+ purge,
+ });
+ publishGlobalLiveEvent({ type: "plugin.ui.updated", payload: { pluginId: plugin.id, action: "uninstalled" } });
+ res.json(result);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ res.status(400).json({ error: message });
+ }
+ });
+
+ /**
+ * POST /api/plugins/:pluginId/enable
+ *
+ * Enable a plugin that is currently disabled or in error state.
+ *
+ * Transitions the plugin to 'ready' state after loading and validation.
+ *
+ * Response: PluginRecord
+ * Errors: 404 if plugin not found, 400 for lifecycle errors
+ */
+ router.post("/plugins/:pluginId/enable", async (req, res) => {
+ assertBoard(req);
+ const { pluginId } = req.params;
+
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ try {
+ const result = await lifecycle.enable(plugin.id);
+ await logPluginMutationActivity(req, "plugin.enabled", plugin.id, {
+ pluginId: plugin.id,
+ pluginKey: plugin.pluginKey,
+ version: result?.version ?? plugin.version,
+ });
+ publishGlobalLiveEvent({ type: "plugin.ui.updated", payload: { pluginId: plugin.id, action: "enabled" } });
+ res.json(result);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ res.status(400).json({ error: message });
+ }
+ });
+
+ /**
+ * POST /api/plugins/:pluginId/disable
+ *
+ * Disable a running plugin.
+ *
+ * Request body (optional):
+ * - reason: Human-readable reason for disabling
+ *
+ * The plugin transitions to 'installed' state and stops processing events.
+ *
+ * Response: PluginRecord
+ * Errors: 404 if plugin not found, 400 for lifecycle errors
+ */
+ router.post("/plugins/:pluginId/disable", async (req, res) => {
+ assertBoard(req);
+ const { pluginId } = req.params;
+ const body = req.body as { reason?: string } | undefined;
+ const reason = body?.reason;
+
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ try {
+ const result = await lifecycle.disable(plugin.id, reason);
+ await logPluginMutationActivity(req, "plugin.disabled", plugin.id, {
+ pluginId: plugin.id,
+ pluginKey: plugin.pluginKey,
+ reason: reason ?? null,
+ });
+ publishGlobalLiveEvent({ type: "plugin.ui.updated", payload: { pluginId: plugin.id, action: "disabled" } });
+ res.json(result);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ res.status(400).json({ error: message });
+ }
+ });
+
+ /**
+ * GET /api/plugins/:pluginId/health
+ *
+ * Run health diagnostics on a plugin.
+ *
+ * Performs the following checks:
+ * 1. Registry: Plugin is registered in the database
+ * 2. Manifest: Manifest is valid and parseable
+ * 3. Status: Plugin is in 'ready' state
+ * 4. Error state: Plugin has no unhandled errors
+ *
+ * Response: PluginHealthCheckResult
+ * Errors: 404 if plugin not found
+ */
+ router.get("/plugins/:pluginId/health", async (req, res) => {
+ assertBoard(req);
+ const { pluginId } = req.params;
+
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ const checks: PluginHealthCheckResult["checks"] = [];
+
+ // Check 1: Plugin is registered
+ checks.push({
+ name: "registry",
+ passed: true,
+ message: "Plugin found in registry",
+ });
+
+ // Check 2: Manifest is valid
+ const hasValidManifest = Boolean(plugin.manifestJson?.id);
+ checks.push({
+ name: "manifest",
+ passed: hasValidManifest,
+ message: hasValidManifest ? "Manifest is valid" : "Manifest is invalid or missing",
+ });
+
+ // Check 3: Plugin status
+ const isHealthy = plugin.status === "ready";
+ checks.push({
+ name: "status",
+ passed: isHealthy,
+ message: `Current status: ${plugin.status}`,
+ });
+
+ // Check 4: No last error
+ const hasNoError = !plugin.lastError;
+ if (!hasNoError) {
+ checks.push({
+ name: "error_state",
+ passed: false,
+ message: plugin.lastError ?? undefined,
+ });
+ }
+
+ const result: PluginHealthCheckResult = {
+ pluginId: plugin.id,
+ status: plugin.status,
+ healthy: isHealthy && hasValidManifest && hasNoError,
+ checks,
+ lastError: plugin.lastError ?? undefined,
+ };
+
+ res.json(result);
+ });
+
+ /**
+ * GET /api/plugins/:pluginId/logs
+ *
+ * Query recent log entries for a plugin.
+ *
+ * Query params:
+ * - limit: Maximum number of entries (default 25, max 500)
+ * - level: Filter by log level (info, warn, error, debug)
+ * - since: ISO timestamp to filter logs newer than this time
+ *
+ * Response: Array of log entries, newest first.
+ */
+ router.get("/plugins/:pluginId/logs", async (req, res) => {
+ assertBoard(req);
+ const { pluginId } = req.params;
+
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ const limit = Math.min(Math.max(parseInt(req.query.limit as string, 10) || 25, 1), 500);
+ const level = req.query.level as string | undefined;
+ const since = req.query.since as string | undefined;
+
+ const conditions = [eq(pluginLogs.pluginId, plugin.id)];
+ if (level) {
+ conditions.push(eq(pluginLogs.level, level));
+ }
+ if (since) {
+ const sinceDate = new Date(since);
+ if (!isNaN(sinceDate.getTime())) {
+ conditions.push(gte(pluginLogs.createdAt, sinceDate));
+ }
+ }
+
+ const rows = await db
+ .select()
+ .from(pluginLogs)
+ .where(and(...conditions))
+ .orderBy(desc(pluginLogs.createdAt))
+ .limit(limit);
+
+ res.json(rows);
+ });
+
+ /**
+ * POST /api/plugins/:pluginId/upgrade
+ *
+ * Upgrade a plugin to a newer version.
+ *
+ * Request body (optional):
+ * - version: Target version (defaults to latest)
+ *
+ * If the upgrade adds new capabilities, the plugin transitions to
+ * 'upgrade_pending' state for board approval. Otherwise, it goes
+ * directly to 'ready'.
+ *
+ * Response: PluginRecord
+ * Errors: 404 if plugin not found, 400 for lifecycle errors
+ */
+ router.post("/plugins/:pluginId/upgrade", async (req, res) => {
+ assertBoard(req);
+ const { pluginId } = req.params;
+ const body = req.body as { version?: string } | undefined;
+ const version = body?.version;
+
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ try {
+ // Upgrade the plugin - this would typically:
+ // 1. Download the new version
+ // 2. Compare capabilities
+ // 3. If new capabilities, mark as upgrade_pending
+ // 4. Otherwise, transition to ready
+ const result = await lifecycle.upgrade(plugin.id, version);
+ await logPluginMutationActivity(req, "plugin.upgraded", plugin.id, {
+ pluginId: plugin.id,
+ pluginKey: plugin.pluginKey,
+ previousVersion: plugin.version,
+ version: result?.version ?? plugin.version,
+ targetVersion: version ?? null,
+ });
+ publishGlobalLiveEvent({ type: "plugin.ui.updated", payload: { pluginId: plugin.id, action: "upgraded" } });
+ res.json(result);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ res.status(400).json({ error: message });
+ }
+ });
+
+ // ===========================================================================
+ // Plugin configuration routes
+ // ===========================================================================
+
+ /**
+ * GET /api/plugins/:pluginId/config
+ *
+ * Retrieve the current instance configuration for a plugin.
+ *
+ * Returns the `PluginConfig` record if one exists, or `null` if the plugin
+ * has not yet been configured.
+ *
+ * Response: `PluginConfig | null`
+ * Errors: 404 if plugin not found
+ */
+ router.get("/plugins/:pluginId/config", async (req, res) => {
+ assertBoard(req);
+ const { pluginId } = req.params;
+
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ const config = await registry.getConfig(plugin.id);
+ res.json(config);
+ });
+
+ /**
+ * POST /api/plugins/:pluginId/config
+ *
+ * Save (create or replace) the instance configuration for a plugin.
+ *
+ * The caller provides the full `configJson` object. The server persists it
+ * via `registry.upsertConfig()`.
+ *
+ * Request body:
+ * - `configJson`: Configuration values matching the plugin's `instanceConfigSchema`
+ *
+ * Response: `PluginConfig`
+ * Errors:
+ * - 400 if request validation fails
+ * - 404 if plugin not found
+ */
+ router.post("/plugins/:pluginId/config", async (req, res) => {
+ assertBoard(req);
+ const { pluginId } = req.params;
+
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ const body = req.body as { configJson?: Record<string, unknown> } | undefined;
+ if (!body?.configJson || typeof body.configJson !== "object") {
+ res.status(400).json({ error: '"configJson" is required and must be an object' });
+ return;
+ }
+
+ // Strip devUiUrl unless the caller is an instance admin. devUiUrl activates
+ // a dev-proxy in the static file route that could be abused for SSRF if any
+ // board-level user were allowed to set it.
+ if (
+ "devUiUrl" in body.configJson &&
+ !(req.actor.type === "board" && req.actor.isInstanceAdmin)
+ ) {
+ delete body.configJson.devUiUrl;
+ }
+
+ // Validate configJson against the plugin's instanceConfigSchema (if declared).
+ // This ensures CLI/API callers get the same validation the UI performs client-side.
+ const schema = plugin.manifestJson?.instanceConfigSchema;
+ if (schema && Object.keys(schema).length > 0) {
+ const validation = validateInstanceConfig(body.configJson, schema);
+ if (!validation.valid) {
+ res.status(400).json({
+ error: "Configuration does not match the plugin's instanceConfigSchema",
+ fieldErrors: validation.errors,
+ });
+ return;
+ }
+ }
+
+ try {
+ const result = await registry.upsertConfig(plugin.id, {
+ configJson: body.configJson,
+ });
+ await logPluginMutationActivity(req, "plugin.config.updated", plugin.id, {
+ pluginId: plugin.id,
+ pluginKey: plugin.pluginKey,
+ configKeyCount: Object.keys(body.configJson).length,
+ });
+
+ // Notify the running worker about the config change (PLUGIN_SPEC §25.4.4).
+ // If the worker implements onConfigChanged, send the new config via RPC.
+ // If it doesn't (METHOD_NOT_IMPLEMENTED), restart the worker so it picks
+ // up the new config on re-initialize. If no worker is running, skip.
+ if (bridgeDeps?.workerManager.isRunning(plugin.id)) {
+ try {
+ await bridgeDeps.workerManager.call(
+ plugin.id,
+ "configChanged",
+ { config: body.configJson },
+ );
+ } catch (rpcErr) {
+ if (
+ rpcErr instanceof JsonRpcCallError &&
+ rpcErr.code === PLUGIN_RPC_ERROR_CODES.METHOD_NOT_IMPLEMENTED
+ ) {
+ // Worker doesn't handle live config — restart it.
+ try {
+ await lifecycle.restartWorker(plugin.id);
+ } catch {
+ // Restart failure is non-fatal for the config save response.
+ }
+ }
+ // Other RPC errors (timeout, unavailable) are non-fatal — config is
+ // already persisted and will take effect on next worker restart.
+ }
+ }
+
+ res.json(result);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ res.status(400).json({ error: message });
+ }
+ });
+
+ /**
+ * POST /api/plugins/:pluginId/config/test
+ *
+ * Test a plugin configuration without persisting it by calling the plugin
+ * worker's `validateConfig` RPC method.
+ *
+ * Only works when the plugin's worker implements `onValidateConfig`.
+ * If the worker does not implement the method, returns
+ * `{ valid: false, supported: false, message: "..." }` with HTTP 200.
+ *
+ * Request body:
+ * - `configJson`: Configuration values to validate
+ *
+ * Response: `{ valid: boolean; message?: string; supported?: boolean }`
+ * Errors:
+ * - 400 if request validation fails
+ * - 404 if plugin not found
+ * - 501 if bridge deps (worker manager) are not configured
+ * - 502 if the worker is unavailable
+ */
+ router.post("/plugins/:pluginId/config/test", async (req, res) => {
+ assertBoard(req);
+
+ if (!bridgeDeps) {
+ res.status(501).json({ error: "Plugin bridge is not enabled" });
+ return;
+ }
+
+ const { pluginId } = req.params;
+
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ if (plugin.status !== "ready") {
+ res.status(400).json({
+ error: `Plugin is not ready (current status: ${plugin.status})`,
+ });
+ return;
+ }
+
+ const body = req.body as { configJson?: Record<string, unknown> } | undefined;
+ if (!body?.configJson || typeof body.configJson !== "object") {
+ res.status(400).json({ error: '"configJson" is required and must be an object' });
+ return;
+ }
+
+ // Fast schema-level rejection before hitting the worker RPC.
+ const schema = plugin.manifestJson?.instanceConfigSchema;
+ if (schema && Object.keys(schema).length > 0) {
+ const validation = validateInstanceConfig(body.configJson, schema);
+ if (!validation.valid) {
+ res.status(400).json({
+ error: "Configuration does not match the plugin's instanceConfigSchema",
+ fieldErrors: validation.errors,
+ });
+ return;
+ }
+ }
+
+ try {
+ const result = await bridgeDeps.workerManager.call(
+ plugin.id,
+ "validateConfig",
+ { config: body.configJson },
+ );
+
+ // The worker returns PluginConfigValidationResult { ok, warnings?, errors? }
+ // Map to the frontend-expected shape { valid, message? }
+ if (result.ok) {
+ const warningText = result.warnings?.length
+ ? `Warnings: ${result.warnings.join("; ")}`
+ : undefined;
+ res.json({ valid: true, message: warningText });
+ } else {
+ const errorText = result.errors?.length
+ ? result.errors.join("; ")
+ : "Configuration validation failed.";
+ res.json({ valid: false, message: errorText });
+ }
+ } catch (err) {
+ // If the worker does not implement validateConfig, return a structured response
+ if (
+ err instanceof JsonRpcCallError &&
+ err.code === PLUGIN_RPC_ERROR_CODES.METHOD_NOT_IMPLEMENTED
+ ) {
+ res.json({
+ valid: false,
+ supported: false,
+ message: "This plugin does not support configuration testing.",
+ });
+ return;
+ }
+
+ // Worker unavailable or other RPC errors
+ const bridgeError = mapRpcErrorToBridgeError(err);
+ res.status(502).json(bridgeError);
+ }
+ });
+
+ // ===========================================================================
+ // Job scheduling routes
+ // ===========================================================================
+
+ /**
+ * GET /api/plugins/:pluginId/jobs
+ *
+ * List all scheduled jobs for a plugin.
+ *
+ * Query params:
+ * - `status` (optional): Filter by job status (`active`, `paused`, `failed`)
+ *
+ * Response: PluginJobRecord[]
+ * Errors: 404 if plugin not found
+ */
+ router.get("/plugins/:pluginId/jobs", async (req, res) => {
+ assertBoard(req);
+ if (!jobDeps) {
+ res.status(501).json({ error: "Job scheduling is not enabled" });
+ return;
+ }
+
+ const { pluginId } = req.params;
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ const rawStatus = req.query.status as string | undefined;
+ const validStatuses = ["active", "paused", "failed"];
+ if (rawStatus !== undefined && !validStatuses.includes(rawStatus)) {
+ res.status(400).json({
+ error: `Invalid status '${rawStatus}'. Must be one of: ${validStatuses.join(", ")}`,
+ });
+ return;
+ }
+
+ try {
+ const jobs = await jobDeps.jobStore.listJobs(
+ plugin.id,
+ rawStatus as "active" | "paused" | "failed" | undefined,
+ );
+ res.json(jobs);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ res.status(500).json({ error: message });
+ }
+ });
+
+ /**
+ * GET /api/plugins/:pluginId/jobs/:jobId/runs
+ *
+ * List execution history for a specific job.
+ *
+ * Query params:
+ * - `limit` (optional): Maximum number of runs to return (default: 50)
+ *
+ * Response: PluginJobRunRecord[]
+ * Errors: 404 if plugin not found
+ */
+ router.get("/plugins/:pluginId/jobs/:jobId/runs", async (req, res) => {
+ assertBoard(req);
+ if (!jobDeps) {
+ res.status(501).json({ error: "Job scheduling is not enabled" });
+ return;
+ }
+
+ const { pluginId, jobId } = req.params;
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ const job = await jobDeps.jobStore.getJobByIdForPlugin(plugin.id, jobId);
+ if (!job) {
+ res.status(404).json({ error: "Job not found" });
+ return;
+ }
+
+ const limit = req.query.limit ? parseInt(req.query.limit as string, 10) : 25;
+ if (isNaN(limit) || limit < 1 || limit > 500) {
+ res.status(400).json({ error: "limit must be a number between 1 and 500" });
+ return;
+ }
+
+ try {
+ const runs = await jobDeps.jobStore.listRunsByJob(jobId, limit);
+ res.json(runs);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ res.status(500).json({ error: message });
+ }
+ });
+
+ /**
+ * POST /api/plugins/:pluginId/jobs/:jobId/trigger
+ *
+ * Manually trigger a job execution outside its cron schedule.
+ *
+ * Creates a run with `trigger: "manual"` and dispatches immediately.
+ * The response returns before the job completes (non-blocking).
+ *
+ * Response: `{ runId: string, jobId: string }`
+ * Errors:
+ * - 404 if plugin not found
+ * - 400 if job not found, not active, already running, or worker unavailable
+ */
+ router.post("/plugins/:pluginId/jobs/:jobId/trigger", async (req, res) => {
+ assertBoard(req);
+ if (!jobDeps) {
+ res.status(501).json({ error: "Job scheduling is not enabled" });
+ return;
+ }
+
+ const { pluginId, jobId } = req.params;
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ const job = await jobDeps.jobStore.getJobByIdForPlugin(plugin.id, jobId);
+ if (!job) {
+ res.status(404).json({ error: "Job not found" });
+ return;
+ }
+
+ try {
+ const result = await jobDeps.scheduler.triggerJob(jobId, "manual");
+ res.json(result);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ res.status(400).json({ error: message });
+ }
+ });
+
+ // ===========================================================================
+ // Webhook ingestion route
+ // ===========================================================================
+
+ /**
+ * POST /api/plugins/:pluginId/webhooks/:endpointKey
+ *
+ * Receive an inbound webhook delivery for a plugin.
+ *
+ * This route is called by external systems (e.g. GitHub, Linear, Stripe) to
+ * deliver webhook payloads to a plugin. The host validates that:
+ * 1. The plugin exists and is in 'ready' state
+ * 2. The plugin declares the `webhooks.receive` capability
+ * 3. The `endpointKey` matches a declared webhook in the manifest
+ *
+ * The delivery is recorded in the `plugin_webhook_deliveries` table and
+ * dispatched to the worker via the `handleWebhook` RPC method.
+ *
+ * **Note:** This route does NOT require board authentication — webhook
+ * endpoints must be publicly accessible for external callers. Signature
+ * verification is the plugin's responsibility.
+ *
+ * Response: `{ deliveryId: string, status: string }`
+ * Errors:
+ * - 404 if plugin not found or endpointKey not declared
+ * - 400 if plugin is not in ready state or lacks webhooks.receive capability
+ * - 502 if the worker is unavailable or the RPC call fails
+ */
+ router.post("/plugins/:pluginId/webhooks/:endpointKey", async (req, res) => {
+ if (!webhookDeps) {
+ res.status(501).json({ error: "Webhook ingestion is not enabled" });
+ return;
+ }
+
+ const { pluginId, endpointKey } = req.params;
+
+ // Step 1: Resolve the plugin
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ // Step 2: Validate the plugin is in 'ready' state
+ if (plugin.status !== "ready") {
+ res.status(400).json({
+ error: `Plugin is not ready (current status: ${plugin.status})`,
+ });
+ return;
+ }
+
+ // Step 3: Validate the plugin has webhooks.receive capability
+ const manifest = plugin.manifestJson;
+ if (!manifest) {
+ res.status(400).json({ error: "Plugin manifest is missing" });
+ return;
+ }
+
+ const capabilities = manifest.capabilities ?? [];
+ if (!capabilities.includes("webhooks.receive")) {
+ res.status(400).json({
+ error: "Plugin does not have the webhooks.receive capability",
+ });
+ return;
+ }
+
+ // Step 4: Validate the endpointKey exists in the manifest's webhook declarations
+ const declaredWebhooks = manifest.webhooks ?? [];
+ const webhookDecl = declaredWebhooks.find(
+ (w) => w.endpointKey === endpointKey,
+ );
+ if (!webhookDecl) {
+ res.status(404).json({
+ error: `Webhook endpoint '${endpointKey}' is not declared by this plugin`,
+ });
+ return;
+ }
+
+ // Step 5: Extract request data
+ const requestId = randomUUID();
+ const rawHeaders: Record<string, string> = {};
+ for (const [key, value] of Object.entries(req.headers)) {
+ if (typeof value === "string") {
+ rawHeaders[key] = value;
+ } else if (Array.isArray(value)) {
+ rawHeaders[key] = value.join(", ");
+ }
+ }
+
+ // Use the raw buffer stashed by the express.json() `verify` callback.
+ // This preserves the exact bytes the provider signed, whereas
+ // JSON.stringify(req.body) would re-serialize and break HMAC verification.
+ const stashedRaw = (req as unknown as { rawBody?: Buffer }).rawBody;
+ const rawBody = stashedRaw ? stashedRaw.toString("utf-8") : "";
+ const parsedBody = req.body as unknown;
+ const payload = (req.body as Record<string, unknown> | undefined) ?? {};
+
+ // Step 6: Record the delivery in the database
+ const startedAt = new Date();
+ const [delivery] = await db
+ .insert(pluginWebhookDeliveries)
+ .values({
+ pluginId: plugin.id,
+ webhookKey: endpointKey,
+ status: "pending",
+ payload,
+ headers: rawHeaders,
+ startedAt,
+ })
+ .returning({ id: pluginWebhookDeliveries.id });
+
+ // Step 7: Dispatch to the worker via handleWebhook RPC
+ try {
+ await webhookDeps.workerManager.call(plugin.id, "handleWebhook", {
+ endpointKey,
+ headers: req.headers as Record<string, string | string[]>,
+ rawBody,
+ parsedBody,
+ requestId,
+ });
+
+ // Step 8: Update delivery record to success
+ const finishedAt = new Date();
+ const durationMs = finishedAt.getTime() - startedAt.getTime();
+ await db
+ .update(pluginWebhookDeliveries)
+ .set({
+ status: "success",
+ durationMs,
+ finishedAt,
+ })
+ .where(eq(pluginWebhookDeliveries.id, delivery.id));
+
+ res.status(200).json({
+ deliveryId: delivery.id,
+ status: "success",
+ });
+ } catch (err) {
+ // Step 8 (error): Update delivery record to failed
+ const finishedAt = new Date();
+ const durationMs = finishedAt.getTime() - startedAt.getTime();
+ const errorMessage = err instanceof Error ? err.message : String(err);
+
+ await db
+ .update(pluginWebhookDeliveries)
+ .set({
+ status: "failed",
+ durationMs,
+ error: errorMessage,
+ finishedAt,
+ })
+ .where(eq(pluginWebhookDeliveries.id, delivery.id));
+
+ res.status(502).json({
+ deliveryId: delivery.id,
+ status: "failed",
+ error: errorMessage,
+ });
+ }
+ });
+
+ // ===========================================================================
+ // Plugin health dashboard — aggregated diagnostics for the settings page
+ // ===========================================================================
+
+ /**
+ * GET /api/plugins/:pluginId/dashboard
+ *
+ * Aggregated health dashboard data for a plugin's settings page.
+ *
+ * Returns worker diagnostics (status, uptime, crash history), recent job
+ * runs, recent webhook deliveries, and the current health check result —
+ * all in a single response to avoid multiple round-trips.
+ *
+ * Response: PluginDashboardData
+ * Errors: 404 if plugin not found
+ */
+ router.get("/plugins/:pluginId/dashboard", async (req, res) => {
+ assertBoard(req);
+ const { pluginId } = req.params;
+
+ const plugin = await resolvePlugin(registry, pluginId);
+ if (!plugin) {
+ res.status(404).json({ error: "Plugin not found" });
+ return;
+ }
+
+ // --- Worker diagnostics ---
+ let worker: {
+ status: string;
+ pid: number | null;
+ uptime: number | null;
+ consecutiveCrashes: number;
+ totalCrashes: number;
+ pendingRequests: number;
+ lastCrashAt: number | null;
+ nextRestartAt: number | null;
+ } | null = null;
+
+ // Try bridgeDeps first (primary source for worker manager), fallback to webhookDeps
+ const wm = bridgeDeps?.workerManager ?? webhookDeps?.workerManager ?? null;
+ if (wm) {
+ const handle = wm.getWorker(plugin.id);
+ if (handle) {
+ const diag = handle.diagnostics();
+ worker = {
+ status: diag.status,
+ pid: diag.pid,
+ uptime: diag.uptime,
+ consecutiveCrashes: diag.consecutiveCrashes,
+ totalCrashes: diag.totalCrashes,
+ pendingRequests: diag.pendingRequests,
+ lastCrashAt: diag.lastCrashAt,
+ nextRestartAt: diag.nextRestartAt,
+ };
+ }
+ }
+
+ // --- Recent job runs (last 10, newest first) ---
+ let recentJobRuns: Array<{
+ id: string;
+ jobId: string;
+ jobKey?: string;
+ trigger: string;
+ status: string;
+ durationMs: number | null;
+ error: string | null;
+ startedAt: string | null;
+ finishedAt: string | null;
+ createdAt: string;
+ }> = [];
+
+ if (jobDeps) {
+ try {
+ const runs = await jobDeps.jobStore.listRunsByPlugin(plugin.id, undefined, 10);
+ // Also fetch job definitions so we can include jobKey
+ const jobs = await jobDeps.jobStore.listJobs(plugin.id);
+ const jobKeyMap = new Map(jobs.map((j) => [j.id, j.jobKey]));
+
+ recentJobRuns = runs
+ .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime())
+ .map((r) => ({
+ id: r.id,
+ jobId: r.jobId,
+ jobKey: jobKeyMap.get(r.jobId) ?? undefined,
+ trigger: r.trigger,
+ status: r.status,
+ durationMs: r.durationMs,
+ error: r.error,
+ startedAt: r.startedAt ? new Date(r.startedAt).toISOString() : null,
+ finishedAt: r.finishedAt ? new Date(r.finishedAt).toISOString() : null,
+ createdAt: new Date(r.createdAt).toISOString(),
+ }));
+ } catch {
+ // Job data unavailable — leave empty
+ }
+ }
+
+ // --- Recent webhook deliveries (last 10, newest first) ---
+ let recentWebhookDeliveries: Array<{
+ id: string;
+ webhookKey: string;
+ status: string;
+ durationMs: number | null;
+ error: string | null;
+ startedAt: string | null;
+ finishedAt: string | null;
+ createdAt: string;
+ }> = [];
+
+ try {
+ const deliveries = await db
+ .select({
+ id: pluginWebhookDeliveries.id,
+ webhookKey: pluginWebhookDeliveries.webhookKey,
+ status: pluginWebhookDeliveries.status,
+ durationMs: pluginWebhookDeliveries.durationMs,
+ error: pluginWebhookDeliveries.error,
+ startedAt: pluginWebhookDeliveries.startedAt,
+ finishedAt: pluginWebhookDeliveries.finishedAt,
+ createdAt: pluginWebhookDeliveries.createdAt,
+ })
+ .from(pluginWebhookDeliveries)
+ .where(eq(pluginWebhookDeliveries.pluginId, plugin.id))
+ .orderBy(desc(pluginWebhookDeliveries.createdAt))
+ .limit(10);
+
+ recentWebhookDeliveries = deliveries.map((d) => ({
+ id: d.id,
+ webhookKey: d.webhookKey,
+ status: d.status,
+ durationMs: d.durationMs,
+ error: d.error,
+ startedAt: d.startedAt ? d.startedAt.toISOString() : null,
+ finishedAt: d.finishedAt ? d.finishedAt.toISOString() : null,
+ createdAt: d.createdAt.toISOString(),
+ }));
+ } catch {
+ // Webhook data unavailable — leave empty
+ }
+
+ // --- Health check (same logic as GET /health) ---
+ const checks: PluginHealthCheckResult["checks"] = [];
+
+ checks.push({
+ name: "registry",
+ passed: true,
+ message: "Plugin found in registry",
+ });
+
+ const hasValidManifest = Boolean(plugin.manifestJson?.id);
+ checks.push({
+ name: "manifest",
+ passed: hasValidManifest,
+ message: hasValidManifest ? "Manifest is valid" : "Manifest is invalid or missing",
+ });
+
+ const isHealthy = plugin.status === "ready";
+ checks.push({
+ name: "status",
+ passed: isHealthy,
+ message: `Current status: ${plugin.status}`,
+ });
+
+ const hasNoError = !plugin.lastError;
+ if (!hasNoError) {
+ checks.push({
+ name: "error_state",
+ passed: false,
+ message: plugin.lastError ?? undefined,
+ });
+ }
+
+ const health: PluginHealthCheckResult = {
+ pluginId: plugin.id,
+ status: plugin.status,
+ healthy: isHealthy && hasValidManifest && hasNoError,
+ checks,
+ lastError: plugin.lastError ?? undefined,
+ };
+
+ res.json({
+ pluginId: plugin.id,
+ worker,
+ recentJobRuns,
+ recentWebhookDeliveries,
+ health,
+ checkedAt: new Date().toISOString(),
+ });
+ });
+
+ return router;
+}
diff --git a/server/src/services/cron.ts b/server/src/services/cron.ts
new file mode 100644
index 0000000000..2b9e09e337
--- /dev/null
+++ b/server/src/services/cron.ts
@@ -0,0 +1,373 @@
+/**
+ * Lightweight cron expression parser and next-run calculator.
+ *
+ * Supports standard 5-field cron expressions:
+ *
+ * ┌────────────── minute (0–59)
+ * │ ┌──────────── hour (0–23)
+ * │ │ ┌────────── day of month (1–31)
+ * │ │ │ ┌──────── month (1–12)
+ * │ │ │ │ ┌────── day of week (0–6, Sun=0)
+ * │ │ │ │ │
+ * * * * * *
+ *
+ * Supported syntax per field:
+ * - `*` — any value
+ * - `N` — exact value
+ * - `N-M` — range (inclusive)
+ * - `N/S` — start at N, step S (within field bounds)
+ * - `* /S` — every S (from field min) [no space — shown to avoid comment termination]
+ * - `N-M/S` — range with step
+ * - `N,M,...` — list of values, ranges, or steps
+ *
+ * @module
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A parsed cron schedule. Each field is a sorted array of valid integer values
+ * for that field.
+ */
+export interface ParsedCron {
+ minutes: number[];
+ hours: number[];
+ daysOfMonth: number[];
+ months: number[];
+ daysOfWeek: number[];
+}
+
+// ---------------------------------------------------------------------------
+// Field bounds
+// ---------------------------------------------------------------------------
+
+interface FieldSpec {
+ min: number;
+ max: number;
+ name: string;
+}
+
+const FIELD_SPECS: FieldSpec[] = [
+ { min: 0, max: 59, name: "minute" },
+ { min: 0, max: 23, name: "hour" },
+ { min: 1, max: 31, name: "day of month" },
+ { min: 1, max: 12, name: "month" },
+ { min: 0, max: 6, name: "day of week" },
+];
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a single cron field token (e.g. `"5"`, `"1-3"`, `"* /10"`, `"1,3,5"`).
+ *
+ * @returns Sorted deduplicated array of matching integer values within bounds.
+ * @throws {Error} on invalid syntax or out-of-range values.
+ */
+function parseField(token: string, spec: FieldSpec): number[] {
+ const values = new Set<number>();
+
+ // Split on commas first — each part can be a value, range, or step
+ const parts = token.split(",");
+
+ for (const part of parts) {
+ const trimmed = part.trim();
+ if (trimmed === "") {
+ throw new Error(`Empty element in cron ${spec.name} field`);
+ }
+
+ // Check for step syntax: "X/S" where X is "*" or a range or a number
+ const slashIdx = trimmed.indexOf("/");
+ if (slashIdx !== -1) {
+ const base = trimmed.slice(0, slashIdx);
+ const stepStr = trimmed.slice(slashIdx + 1);
+ const step = parseInt(stepStr, 10);
+ if (isNaN(step) || step <= 0) {
+ throw new Error(
+ `Invalid step "${stepStr}" in cron ${spec.name} field`,
+ );
+ }
+
+ let rangeStart = spec.min;
+ let rangeEnd = spec.max;
+
+ if (base === "*") {
+ // */S — every S from field min
+ } else if (base.includes("-")) {
+ // N-M/S — range with step
+ const [a, b] = base.split("-").map((s) => parseInt(s, 10));
+ if (isNaN(a!) || isNaN(b!)) {
+ throw new Error(
+ `Invalid range "${base}" in cron ${spec.name} field`,
+ );
+ }
+ rangeStart = a!;
+ rangeEnd = b!;
+ } else {
+ // N/S — start at N, step S
+ const start = parseInt(base, 10);
+ if (isNaN(start)) {
+ throw new Error(
+ `Invalid start "${base}" in cron ${spec.name} field`,
+ );
+ }
+ rangeStart = start;
+ }
+
+ validateBounds(rangeStart, spec);
+ validateBounds(rangeEnd, spec);
+
+ for (let i = rangeStart; i <= rangeEnd; i += step) {
+ values.add(i);
+ }
+ continue;
+ }
+
+ // Check for range syntax: "N-M"
+ if (trimmed.includes("-")) {
+ const [aStr, bStr] = trimmed.split("-");
+ const a = parseInt(aStr!, 10);
+ const b = parseInt(bStr!, 10);
+ if (isNaN(a) || isNaN(b)) {
+ throw new Error(
+ `Invalid range "${trimmed}" in cron ${spec.name} field`,
+ );
+ }
+ validateBounds(a, spec);
+ validateBounds(b, spec);
+ if (a > b) {
+ throw new Error(
+ `Invalid range ${a}-${b} in cron ${spec.name} field (start > end)`,
+ );
+ }
+ for (let i = a; i <= b; i++) {
+ values.add(i);
+ }
+ continue;
+ }
+
+ // Wildcard
+ if (trimmed === "*") {
+ for (let i = spec.min; i <= spec.max; i++) {
+ values.add(i);
+ }
+ continue;
+ }
+
+ // Single value
+ const val = parseInt(trimmed, 10);
+ if (isNaN(val)) {
+ throw new Error(
+ `Invalid value "${trimmed}" in cron ${spec.name} field`,
+ );
+ }
+ validateBounds(val, spec);
+ values.add(val);
+ }
+
+ if (values.size === 0) {
+ throw new Error(`Empty result for cron ${spec.name} field`);
+ }
+
+ return [...values].sort((a, b) => a - b);
+}
+
+function validateBounds(value: number, spec: FieldSpec): void {
+ if (value < spec.min || value > spec.max) {
+ throw new Error(
+ `Value ${value} out of range [${spec.min}–${spec.max}] for cron ${spec.name} field`,
+ );
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a cron expression string into a structured {@link ParsedCron}.
+ *
+ * @param expression — A standard 5-field cron expression.
+ * @returns Parsed cron with sorted valid values for each field.
+ * @throws {Error} on invalid syntax.
+ *
+ * @example
+ * ```ts
+ * const parsed = parseCron("0 * * * *"); // every hour at minute 0
+ * // parsed.minutes === [0]
+ * // parsed.hours === [0,1,2,...,23]
+ * ```
+ */
+export function parseCron(expression: string): ParsedCron {
+ const trimmed = expression.trim();
+ if (!trimmed) {
+ throw new Error("Cron expression must not be empty");
+ }
+
+ const tokens = trimmed.split(/\s+/);
+ if (tokens.length !== 5) {
+ throw new Error(
+ `Cron expression must have exactly 5 fields, got ${tokens.length}: "${trimmed}"`,
+ );
+ }
+
+ return {
+ minutes: parseField(tokens[0]!, FIELD_SPECS[0]!),
+ hours: parseField(tokens[1]!, FIELD_SPECS[1]!),
+ daysOfMonth: parseField(tokens[2]!, FIELD_SPECS[2]!),
+ months: parseField(tokens[3]!, FIELD_SPECS[3]!),
+ daysOfWeek: parseField(tokens[4]!, FIELD_SPECS[4]!),
+ };
+}
+
+/**
+ * Validate a cron expression string. Returns `null` if valid, or an error
+ * message string if invalid.
+ *
+ * @param expression — A cron expression string to validate.
+ * @returns `null` on success, error message on failure.
+ */
+export function validateCron(expression: string): string | null {
+ try {
+ parseCron(expression);
+ return null;
+ } catch (err) {
+ return err instanceof Error ? err.message : String(err);
+ }
+}
+
+/**
+ * Calculate the next run time after `after` for the given parsed cron schedule.
+ *
+ * Starts from the minute immediately following `after` and walks forward
+ * until a matching minute is found (up to a safety limit of ~4 years to
+ * prevent infinite loops on impossible schedules).
+ *
+ * @param cron — Parsed cron schedule.
+ * @param after — The reference date. The returned date will be strictly after this.
+ * @returns The next matching `Date`, or `null` if no match found within the search window.
+ */
+export function nextCronTick(cron: ParsedCron, after: Date): Date | null {
+ // Work in local minutes — start from the minute after `after`
+ const d = new Date(after.getTime());
+ // Advance to the next whole minute
+ d.setUTCSeconds(0, 0);
+ d.setUTCMinutes(d.getUTCMinutes() + 1);
+
+ // Safety: search up to 4 years worth of minutes (~2.1M iterations max).
+ // Uses 366 to account for leap years.
+ const MAX_CRON_SEARCH_YEARS = 4;
+ const maxIterations = MAX_CRON_SEARCH_YEARS * 366 * 24 * 60;
+
+ for (let i = 0; i < maxIterations; i++) {
+ const month = d.getUTCMonth() + 1; // 1-12
+ const dayOfMonth = d.getUTCDate(); // 1-31
+ const dayOfWeek = d.getUTCDay(); // 0-6
+ const hour = d.getUTCHours(); // 0-23
+ const minute = d.getUTCMinutes(); // 0-59
+
+ // Check month
+ if (!cron.months.includes(month)) {
+ // Skip to the first day of the next matching month
+ advanceToNextMonth(d, cron.months);
+ continue;
+ }
+
+ // Check day of month AND day of week (both must match)
+ if (!cron.daysOfMonth.includes(dayOfMonth) || !cron.daysOfWeek.includes(dayOfWeek)) {
+ // Advance one day
+ d.setUTCDate(d.getUTCDate() + 1);
+ d.setUTCHours(0, 0, 0, 0);
+ continue;
+ }
+
+ // Check hour
+ if (!cron.hours.includes(hour)) {
+ // Advance to next matching hour within the day
+ const nextHour = findNext(cron.hours, hour);
+ if (nextHour !== null) {
+ d.setUTCHours(nextHour, 0, 0, 0);
+ } else {
+ // No matching hour left today — advance to next day
+ d.setUTCDate(d.getUTCDate() + 1);
+ d.setUTCHours(0, 0, 0, 0);
+ }
+ continue;
+ }
+
+ // Check minute
+ if (!cron.minutes.includes(minute)) {
+ const nextMin = findNext(cron.minutes, minute);
+ if (nextMin !== null) {
+ d.setUTCMinutes(nextMin, 0, 0);
+ } else {
+ // No matching minute left this hour — advance to next hour
+ d.setUTCHours(d.getUTCHours() + 1, 0, 0, 0);
+ }
+ continue;
+ }
+
+ // All fields match!
+ return new Date(d.getTime());
+ }
+
+ // No match found within the search window
+ return null;
+}
+
+/**
+ * Convenience: parse a cron expression and compute the next run time.
+ *
+ * @param expression — 5-field cron expression string.
+ * @param after — Reference date (defaults to `new Date()`).
+ * @returns The next matching Date, or `null` if no match within 4 years.
+ * @throws {Error} if the cron expression is invalid.
+ */
+export function nextCronTickFromExpression(
+ expression: string,
+ after: Date = new Date(),
+): Date | null {
+ const cron = parseCron(expression);
+ return nextCronTick(cron, after);
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the next value in `sortedValues` that is greater than `current`.
+ * Returns `null` if no such value exists.
+ */
+function findNext(sortedValues: number[], current: number): number | null {
+ for (const v of sortedValues) {
+ if (v > current) return v;
+ }
+ return null;
+}
+
+/**
+ * Advance `d` (mutated in place) to midnight UTC of the first day of the next
+ * month whose 1-based month number is in `months`.
+ */
+function advanceToNextMonth(d: Date, months: number[]): void {
+ let year = d.getUTCFullYear();
+ let month = d.getUTCMonth() + 1; // 1-based
+
+ // Walk months forward until we find one in the set (max 48 iterations = 4 years)
+ for (let i = 0; i < 48; i++) {
+ month++;
+ if (month > 12) {
+ month = 1;
+ year++;
+ }
+ if (months.includes(month)) {
+ d.setUTCFullYear(year, month - 1, 1);
+ d.setUTCHours(0, 0, 0, 0);
+ return;
+ }
+ }
+}
diff --git a/server/src/services/live-events.ts b/server/src/services/live-events.ts
index 1421d07d96..7db40d4967 100644
--- a/server/src/services/live-events.ts
+++ b/server/src/services/live-events.ts
@@ -34,7 +34,21 @@ export function publishLiveEvent(input: {
return event;
}
+export function publishGlobalLiveEvent(input: {
+ type: LiveEventType;
+ payload?: LiveEventPayload;
+}) {
+ const event = toLiveEvent({ companyId: "*", type: input.type, payload: input.payload });
+ emitter.emit("*", event);
+ return event;
+}
+
export function subscribeCompanyLiveEvents(companyId: string, listener: LiveEventListener) {
emitter.on(companyId, listener);
return () => emitter.off(companyId, listener);
}
+
+export function subscribeGlobalLiveEvents(listener: LiveEventListener) {
+ emitter.on("*", listener);
+ return () => emitter.off("*", listener);
+}
diff --git a/server/src/services/plugin-capability-validator.ts b/server/src/services/plugin-capability-validator.ts
new file mode 100644
index 0000000000..56b22f5829
--- /dev/null
+++ b/server/src/services/plugin-capability-validator.ts
@@ -0,0 +1,451 @@
+/**
+ * PluginCapabilityValidator — enforces the capability model at both
+ * install-time and runtime.
+ *
+ * Every plugin declares the capabilities it requires in its manifest
+ * (`manifest.capabilities`). This service checks those declarations
+ * against a mapping of operations → required capabilities so that:
+ *
+ * 1. **Install-time validation** — `validateManifestCapabilities()`
+ * ensures that declared features (tools, jobs, webhooks, UI slots)
+ * have matching capability entries, giving operators clear feedback
+ * before a plugin is activated.
+ *
+ * 2. **Runtime gating** — `checkOperation()` / `assertOperation()` are
+ * called on every worker→host bridge call to enforce least-privilege
+ * access. If a plugin attempts an operation it did not declare, the
+ * call is rejected with a 403 error.
+ *
+ * @see PLUGIN_SPEC.md §15 — Capability Model
+ * @see host-client-factory.ts — SDK-side capability gating
+ */
+import type {
+ PluginCapability,
+ PaperclipPluginManifestV1,
+ PluginUiSlotType,
+ PluginLauncherPlacementZone,
+} from "@paperclipai/shared";
+import { forbidden } from "../errors.js";
+import { logger } from "../middleware/logger.js";
+
+// ---------------------------------------------------------------------------
+// Capability requirement mappings
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps high-level operations to the capabilities they require.
+ *
+ * When the bridge receives a call from a plugin worker, the host looks up
+ * the operation in this map and checks the plugin's declared capabilities.
+ * If any required capability is missing, the call is rejected.
+ *
+ * @see PLUGIN_SPEC.md §15 — Capability Model
+ */
+const OPERATION_CAPABILITIES: Record<string, readonly PluginCapability[]> = {
+ // Data read operations
+ "companies.list": ["companies.read"],
+ "companies.get": ["companies.read"],
+ "projects.list": ["projects.read"],
+ "projects.get": ["projects.read"],
+ "project.workspaces.list": ["project.workspaces.read"],
+ "project.workspaces.get": ["project.workspaces.read"],
+ "issues.list": ["issues.read"],
+ "issues.get": ["issues.read"],
+ "issue.comments.list": ["issue.comments.read"],
+ "issue.comments.get": ["issue.comments.read"],
+ "agents.list": ["agents.read"],
+ "agents.get": ["agents.read"],
+ "goals.list": ["goals.read"],
+ "goals.get": ["goals.read"],
+ "activity.list": ["activity.read"],
+ "activity.get": ["activity.read"],
+ "costs.list": ["costs.read"],
+ "costs.get": ["costs.read"],
+ "assets.list": ["assets.read"],
+ "assets.get": ["assets.read"],
+
+ // Data write operations
+ "issues.create": ["issues.create"],
+ "issues.update": ["issues.update"],
+ "issue.comments.create": ["issue.comments.create"],
+ "assets.upload": ["assets.write"],
+ "assets.delete": ["assets.write"],
+ "activity.log": ["activity.log.write"],
+ "metrics.write": ["metrics.write"],
+
+ // Plugin state operations
+ "plugin.state.get": ["plugin.state.read"],
+ "plugin.state.list": ["plugin.state.read"],
+ "plugin.state.set": ["plugin.state.write"],
+ "plugin.state.delete": ["plugin.state.write"],
+
+ // Runtime / Integration operations
+ "events.subscribe": ["events.subscribe"],
+ "events.emit": ["events.emit"],
+ "jobs.schedule": ["jobs.schedule"],
+ "jobs.cancel": ["jobs.schedule"],
+ "webhooks.receive": ["webhooks.receive"],
+ "http.request": ["http.outbound"],
+ "secrets.resolve": ["secrets.read-ref"],
+
+ // Agent tools
+ "agent.tools.register": ["agent.tools.register"],
+ "agent.tools.execute": ["agent.tools.register"],
+};
+
+/**
+ * Maps UI slot types to the capability required to register them.
+ *
+ * @see PLUGIN_SPEC.md §19 — UI Extension Model
+ */
+const UI_SLOT_CAPABILITIES: Record<PluginUiSlotType, PluginCapability> = {
+ sidebar: "ui.sidebar.register",
+ sidebarPanel: "ui.sidebar.register",
+ projectSidebarItem: "ui.sidebar.register",
+ page: "ui.page.register",
+ detailTab: "ui.detailTab.register",
+ taskDetailView: "ui.detailTab.register",
+ dashboardWidget: "ui.dashboardWidget.register",
+ toolbarButton: "ui.action.register",
+ contextMenuItem: "ui.action.register",
+ commentAnnotation: "ui.commentAnnotation.register",
+ commentContextMenuItem: "ui.action.register",
+ settingsPage: "instance.settings.register",
+};
+
+/**
+ * Launcher placement zones align with host UI surfaces and therefore inherit
+ * the same capability requirements as the equivalent slot type.
+ */
+const LAUNCHER_PLACEMENT_CAPABILITIES: Record<
+ PluginLauncherPlacementZone,
+ PluginCapability
+> = {
+ page: "ui.page.register",
+ detailTab: "ui.detailTab.register",
+ taskDetailView: "ui.detailTab.register",
+ dashboardWidget: "ui.dashboardWidget.register",
+ sidebar: "ui.sidebar.register",
+ sidebarPanel: "ui.sidebar.register",
+ projectSidebarItem: "ui.sidebar.register",
+ toolbarButton: "ui.action.register",
+ contextMenuItem: "ui.action.register",
+ commentAnnotation: "ui.commentAnnotation.register",
+ commentContextMenuItem: "ui.action.register",
+ settingsPage: "instance.settings.register",
+};
+
+/**
+ * Maps feature declarations in the manifest to their required capabilities.
+ */
+const FEATURE_CAPABILITIES: Record<string, PluginCapability> = {
+ tools: "agent.tools.register",
+ jobs: "jobs.schedule",
+ webhooks: "webhooks.receive",
+};
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of a capability check. When `allowed` is false, `missing` contains
+ * the capabilities that the plugin does not declare but the operation requires.
+ */
+export interface CapabilityCheckResult {
+ allowed: boolean;
+ missing: PluginCapability[];
+ operation?: string;
+ pluginId?: string;
+}
+
+// ---------------------------------------------------------------------------
+// PluginCapabilityValidator interface
+// ---------------------------------------------------------------------------
+
+export interface PluginCapabilityValidator {
+ /**
+ * Check whether a plugin has a specific capability.
+ */
+ hasCapability(
+ manifest: PaperclipPluginManifestV1,
+ capability: PluginCapability,
+ ): boolean;
+
+ /**
+ * Check whether a plugin has all of the specified capabilities.
+ */
+ hasAllCapabilities(
+ manifest: PaperclipPluginManifestV1,
+ capabilities: PluginCapability[],
+ ): CapabilityCheckResult;
+
+ /**
+ * Check whether a plugin has at least one of the specified capabilities.
+ */
+ hasAnyCapability(
+ manifest: PaperclipPluginManifestV1,
+ capabilities: PluginCapability[],
+ ): boolean;
+
+ /**
+ * Check whether a plugin is allowed to perform the named operation.
+ *
+ * Operations are mapped to required capabilities via OPERATION_CAPABILITIES.
+ * Unknown operations are rejected by default.
+ */
+ checkOperation(
+ manifest: PaperclipPluginManifestV1,
+ operation: string,
+ ): CapabilityCheckResult;
+
+ /**
+ * Assert that a plugin is allowed to perform an operation.
+ * Throws a 403 HttpError if the capability check fails.
+ */
+ assertOperation(
+ manifest: PaperclipPluginManifestV1,
+ operation: string,
+ ): void;
+
+ /**
+ * Assert that a plugin has a specific capability.
+ * Throws a 403 HttpError if the capability is missing.
+ */
+ assertCapability(
+ manifest: PaperclipPluginManifestV1,
+ capability: PluginCapability,
+ ): void;
+
+ /**
+ * Check whether a plugin can register the given UI slot type.
+ */
+ checkUiSlot(
+ manifest: PaperclipPluginManifestV1,
+ slotType: PluginUiSlotType,
+ ): CapabilityCheckResult;
+
+ /**
+ * Validate that a manifest's declared capabilities are consistent with its
+ * declared features (tools, jobs, webhooks, UI slots).
+ *
+ * Returns all missing capabilities rather than failing on the first one.
+ * This is useful for install-time validation to give comprehensive feedback.
+ */
+ validateManifestCapabilities(
+ manifest: PaperclipPluginManifestV1,
+ ): CapabilityCheckResult;
+
+ /**
+ * Get the capabilities required for a named operation.
+ * Returns an empty array if the operation is unknown.
+ */
+ getRequiredCapabilities(operation: string): readonly PluginCapability[];
+
+ /**
+ * Get the capability required for a UI slot type.
+ */
+ getUiSlotCapability(slotType: PluginUiSlotType): PluginCapability;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a PluginCapabilityValidator.
+ *
+ * This service enforces capability gates for plugin operations. The host
+ * uses it to verify that a plugin's declared capabilities permit the
+ * operation it is attempting, both at install time (manifest validation)
+ * and at runtime (bridge call gating).
+ *
+ * Usage:
+ * ```ts
+ * const validator = pluginCapabilityValidator();
+ *
+ * // Runtime: gate a bridge call
+ * validator.assertOperation(plugin.manifestJson, "issues.create");
+ *
+ * // Install time: validate manifest consistency
+ * const result = validator.validateManifestCapabilities(manifest);
+ * if (!result.allowed) {
+ * throw badRequest("Missing capabilities", result.missing);
+ * }
+ * ```
+ */
+export function pluginCapabilityValidator(): PluginCapabilityValidator {
+ const log = logger.child({ service: "plugin-capability-validator" });
+
+ // -----------------------------------------------------------------------
+ // Internal helpers
+ // -----------------------------------------------------------------------
+
+ function capabilitySet(manifest: PaperclipPluginManifestV1): Set<PluginCapability> {
+ return new Set(manifest.capabilities);
+ }
+
+ function buildForbiddenMessage(
+ manifest: PaperclipPluginManifestV1,
+ operation: string,
+ missing: PluginCapability[],
+ ): string {
+ return (
+ `Plugin '${manifest.id}' is not allowed to perform '${operation}'. ` +
+ `Missing required capabilities: ${missing.join(", ")}`
+ );
+ }
+
+ // -----------------------------------------------------------------------
+ // Public API
+ // -----------------------------------------------------------------------
+
+ return {
+ hasCapability(manifest, capability) {
+ return manifest.capabilities.includes(capability);
+ },
+
+ hasAllCapabilities(manifest, capabilities) {
+ const declared = capabilitySet(manifest);
+ const missing = capabilities.filter((cap) => !declared.has(cap));
+ return {
+ allowed: missing.length === 0,
+ missing,
+ pluginId: manifest.id,
+ };
+ },
+
+ hasAnyCapability(manifest, capabilities) {
+ const declared = capabilitySet(manifest);
+ return capabilities.some((cap) => declared.has(cap));
+ },
+
+ checkOperation(manifest, operation) {
+ const required = OPERATION_CAPABILITIES[operation];
+
+ if (!required) {
+ log.warn(
+ { pluginId: manifest.id, operation },
+ "capability check for unknown operation – rejecting by default",
+ );
+ return {
+ allowed: false,
+ missing: [],
+ operation,
+ pluginId: manifest.id,
+ };
+ }
+
+ const declared = capabilitySet(manifest);
+ const missing = required.filter((cap) => !declared.has(cap));
+
+ if (missing.length > 0) {
+ log.debug(
+ { pluginId: manifest.id, operation, missing },
+ "capability check failed",
+ );
+ }
+
+ return {
+ allowed: missing.length === 0,
+ missing,
+ operation,
+ pluginId: manifest.id,
+ };
+ },
+
+ assertOperation(manifest, operation) {
+ const result = this.checkOperation(manifest, operation);
+ if (!result.allowed) {
+ const msg = result.missing.length > 0
+ ? buildForbiddenMessage(manifest, operation, result.missing)
+ : `Plugin '${manifest.id}' attempted unknown operation '${operation}'`;
+ throw forbidden(msg);
+ }
+ },
+
+ assertCapability(manifest, capability) {
+ if (!this.hasCapability(manifest, capability)) {
+ throw forbidden(
+ `Plugin '${manifest.id}' lacks required capability '${capability}'`,
+ );
+ }
+ },
+
+ checkUiSlot(manifest, slotType) {
+ const required = UI_SLOT_CAPABILITIES[slotType];
+ if (!required) {
+ return {
+ allowed: false,
+ missing: [],
+ operation: `ui.${slotType}.register`,
+ pluginId: manifest.id,
+ };
+ }
+
+ const has = manifest.capabilities.includes(required);
+ return {
+ allowed: has,
+ missing: has ? [] : [required],
+ operation: `ui.${slotType}.register`,
+ pluginId: manifest.id,
+ };
+ },
+
+ validateManifestCapabilities(manifest) {
+ const declared = capabilitySet(manifest);
+ const allMissing: PluginCapability[] = [];
+
+ // Check feature declarations → required capabilities
+ for (const [feature, requiredCap] of Object.entries(FEATURE_CAPABILITIES)) {
+ const featureValue = manifest[feature as keyof PaperclipPluginManifestV1];
+ if (Array.isArray(featureValue) && featureValue.length > 0) {
+ if (!declared.has(requiredCap)) {
+ allMissing.push(requiredCap);
+ }
+ }
+ }
+
+ // Check UI slots → required capabilities
+ const uiSlots = manifest.ui?.slots ?? [];
+ if (uiSlots.length > 0) {
+ for (const slot of uiSlots) {
+ const requiredCap = UI_SLOT_CAPABILITIES[slot.type];
+ if (requiredCap && !declared.has(requiredCap)) {
+ if (!allMissing.includes(requiredCap)) {
+ allMissing.push(requiredCap);
+ }
+ }
+ }
+ }
+
+ // Check launcher declarations → required capabilities
+ const launchers = [
+ ...(manifest.launchers ?? []),
+ ...(manifest.ui?.launchers ?? []),
+ ];
+ if (launchers.length > 0) {
+ for (const launcher of launchers) {
+ const requiredCap = LAUNCHER_PLACEMENT_CAPABILITIES[launcher.placementZone];
+ if (requiredCap && !declared.has(requiredCap) && !allMissing.includes(requiredCap)) {
+ allMissing.push(requiredCap);
+ }
+ }
+ }
+
+ return {
+ allowed: allMissing.length === 0,
+ missing: allMissing,
+ pluginId: manifest.id,
+ };
+ },
+
+ getRequiredCapabilities(operation) {
+ return OPERATION_CAPABILITIES[operation] ?? [];
+ },
+
+ getUiSlotCapability(slotType) {
+ return UI_SLOT_CAPABILITIES[slotType];
+ },
+ };
+}
diff --git a/server/src/services/plugin-config-validator.ts b/server/src/services/plugin-config-validator.ts
new file mode 100644
index 0000000000..9e06457281
--- /dev/null
+++ b/server/src/services/plugin-config-validator.ts
@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Validates plugin instance configuration against its JSON Schema.
+ *
+ * Uses Ajv to validate `configJson` values against the `instanceConfigSchema`
+ * declared in a plugin's manifest. This ensures that invalid configuration is
+ * rejected at the API boundary, not discovered later at worker startup.
+ *
+ * @module server/services/plugin-config-validator
+ */
+
+import Ajv, { type ErrorObject } from "ajv";
+import addFormats from "ajv-formats";
+import type { JsonSchema } from "@paperclipai/shared";
+
+export interface ConfigValidationResult {
+ valid: boolean;
+ errors?: { field: string; message: string }[];
+}
+
+/**
+ * Validate a config object against a JSON Schema.
+ *
+ * @param configJson - The configuration values to validate.
+ * @param schema - The JSON Schema from the plugin manifest's `instanceConfigSchema`.
+ * @returns Validation result with structured field errors on failure.
+ */
+export function validateInstanceConfig(
+ configJson: Record<string, unknown>,
+ schema: JsonSchema,
+): ConfigValidationResult {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ const AjvCtor = (Ajv as any).default ?? Ajv;
+ const ajv = new AjvCtor({ allErrors: true });
+ // ajv-formats v3 default export is a FormatsPlugin object; call it as a plugin.
+ const applyFormats = (addFormats as any).default ?? addFormats;
+ applyFormats(ajv);
+ const validate = ajv.compile(schema);
+ const valid = validate(configJson);
+
+ if (valid) {
+ return { valid: true };
+ }
+
+ const errors = (validate.errors ?? []).map((err: ErrorObject) => ({
+ field: err.instancePath || "/",
+ message: err.message ?? "validation failed",
+ }));
+
+ return { valid: false, errors };
+}
diff --git a/server/src/services/plugin-dev-watcher.ts b/server/src/services/plugin-dev-watcher.ts
new file mode 100644
index 0000000000..156b236818
--- /dev/null
+++ b/server/src/services/plugin-dev-watcher.ts
@@ -0,0 +1,189 @@
+/**
+ * PluginDevWatcher — watches local-path plugin directories for file changes
+ * and triggers worker restarts so plugin authors get a fast rebuild-and-reload
+ * cycle without manually restarting the server.
+ *
+ * Only plugins installed from a local path (i.e. those with a non-null
+ * `packagePath` in the DB) are watched. File changes in the plugin's package
+ * directory trigger a debounced worker restart via the lifecycle manager.
+ *
+ * @see PLUGIN_SPEC.md §27.2 — Local Development Workflow
+ */
+import { watch, type FSWatcher } from "node:fs";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { logger } from "../middleware/logger.js";
+import type { PluginLifecycleManager } from "./plugin-lifecycle.js";
+
+const log = logger.child({ service: "plugin-dev-watcher" });
+
+/** Debounce interval for file changes (ms). */
+const DEBOUNCE_MS = 500;
+
+export interface PluginDevWatcher {
+ /** Start watching a local-path plugin directory. */
+ watch(pluginId: string, packagePath: string): void;
+ /** Stop watching a specific plugin. */
+ unwatch(pluginId: string): void;
+ /** Stop all watchers and clean up. */
+ close(): void;
+}
+
+export type ResolvePluginPackagePath = (
+ pluginId: string,
+) => Promise<string | null | undefined>;
+
+export interface PluginDevWatcherFsDeps {
+ existsSync?: typeof existsSync;
+ watch?: typeof watch;
+}
+
+/**
+ * Create a PluginDevWatcher that monitors local plugin directories and
+ * restarts workers on file changes.
+ */
+export function createPluginDevWatcher(
+ lifecycle: PluginLifecycleManager,
+ resolvePluginPackagePath?: ResolvePluginPackagePath,
+ fsDeps?: PluginDevWatcherFsDeps,
+): PluginDevWatcher {
+ const watchers = new Map<string, FSWatcher>();
+ const debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
+ const fileExists = fsDeps?.existsSync ?? existsSync;
+ const watchFs = fsDeps?.watch ?? watch;
+
+ function watchPlugin(pluginId: string, packagePath: string): void {
+ // Don't double-watch
+ if (watchers.has(pluginId)) return;
+
+ const absPath = path.resolve(packagePath);
+ if (!fileExists(absPath)) {
+ log.warn(
+ { pluginId, packagePath: absPath },
+ "plugin-dev-watcher: package path does not exist, skipping watch",
+ );
+ return;
+ }
+
+ try {
+ const watcher = watchFs(absPath, { recursive: true }, (_event, filename) => {
+ // Ignore node_modules and hidden files inside the plugin dir
+ if (
+ filename &&
+ (filename.includes("node_modules") || filename.startsWith("."))
+ ) {
+ return;
+ }
+
+ // Debounce: multiple rapid file changes collapse into one restart
+ const existing = debounceTimers.get(pluginId);
+ if (existing) clearTimeout(existing);
+
+ debounceTimers.set(
+ pluginId,
+ setTimeout(() => {
+ debounceTimers.delete(pluginId);
+ log.info(
+ { pluginId, changedFile: filename },
+ "plugin-dev-watcher: file change detected, restarting worker",
+ );
+
+ lifecycle.restartWorker(pluginId).catch((err) => {
+ log.warn(
+ {
+ pluginId,
+ err: err instanceof Error ? err.message : String(err),
+ },
+ "plugin-dev-watcher: failed to restart worker after file change",
+ );
+ });
+ }, DEBOUNCE_MS),
+ );
+ });
+
+ watchers.set(pluginId, watcher);
+ log.info(
+ { pluginId, packagePath: absPath },
+ "plugin-dev-watcher: watching local plugin for changes",
+ );
+ } catch (err) {
+ log.warn(
+ {
+ pluginId,
+ packagePath: absPath,
+ err: err instanceof Error ? err.message : String(err),
+ },
+ "plugin-dev-watcher: failed to start file watcher",
+ );
+ }
+ }
+
+ function unwatchPlugin(pluginId: string): void {
+ const watcher = watchers.get(pluginId);
+ if (watcher) {
+ watcher.close();
+ watchers.delete(pluginId);
+ }
+ const timer = debounceTimers.get(pluginId);
+ if (timer) {
+ clearTimeout(timer);
+ debounceTimers.delete(pluginId);
+ }
+ }
+
+ function close(): void {
+ lifecycle.off("plugin.loaded", handlePluginLoaded);
+ lifecycle.off("plugin.enabled", handlePluginEnabled);
+ lifecycle.off("plugin.disabled", handlePluginDisabled);
+ lifecycle.off("plugin.unloaded", handlePluginUnloaded);
+
+ for (const [pluginId] of watchers) {
+ unwatchPlugin(pluginId);
+ }
+ }
+
+ async function watchLocalPluginById(pluginId: string): Promise<void> {
+ if (!resolvePluginPackagePath) return;
+
+ try {
+ const packagePath = await resolvePluginPackagePath(pluginId);
+ if (!packagePath) return;
+ watchPlugin(pluginId, packagePath);
+ } catch (err) {
+ log.warn(
+ {
+ pluginId,
+ err: err instanceof Error ? err.message : String(err),
+ },
+ "plugin-dev-watcher: failed to resolve plugin package path",
+ );
+ }
+ }
+
+ function handlePluginLoaded(payload: { pluginId: string }): void {
+ void watchLocalPluginById(payload.pluginId);
+ }
+
+ function handlePluginEnabled(payload: { pluginId: string }): void {
+ void watchLocalPluginById(payload.pluginId);
+ }
+
+ function handlePluginDisabled(payload: { pluginId: string }): void {
+ unwatchPlugin(payload.pluginId);
+ }
+
+ function handlePluginUnloaded(payload: { pluginId: string }): void {
+ unwatchPlugin(payload.pluginId);
+ }
+
+ lifecycle.on("plugin.loaded", handlePluginLoaded);
+ lifecycle.on("plugin.enabled", handlePluginEnabled);
+ lifecycle.on("plugin.disabled", handlePluginDisabled);
+ lifecycle.on("plugin.unloaded", handlePluginUnloaded);
+
+ return {
+ watch: watchPlugin,
+ unwatch: unwatchPlugin,
+ close,
+ };
+}
diff --git a/server/src/services/plugin-event-bus.ts b/server/src/services/plugin-event-bus.ts
new file mode 100644
index 0000000000..78184b47e9
--- /dev/null
+++ b/server/src/services/plugin-event-bus.ts
@@ -0,0 +1,515 @@
+/**
+ * PluginEventBus — typed in-process event bus for the Paperclip plugin system.
+ *
+ * Responsibilities:
+ * - Deliver core domain events to subscribing plugin workers (server-side).
+ * - Apply `EventFilter` server-side so filtered-out events never reach the handler.
+ * - Namespace plugin-emitted events as `plugin.<pluginId>.<eventName>`.
+ * - Guard the core namespace: plugins may not emit events with the `plugin.` prefix.
+ * - Isolate subscriptions per plugin — a plugin cannot enumerate or interfere with
+ * another plugin's subscriptions.
+ * - Support wildcard subscriptions via prefix matching (e.g. `plugin.acme.linear.*`).
+ *
+ * The bus operates in-process. In the full out-of-process architecture the host
+ * calls `bus.emit()` after receiving events from the DB/queue layer, and the bus
+ * forwards to handlers that proxy the call to the relevant worker process via IPC.
+ * That IPC layer is separate; this module only handles routing and filtering.
+ *
+ * @see PLUGIN_SPEC.md §16 — Event System
+ * @see PLUGIN_SPEC.md §16.1 — Event Filtering
+ * @see PLUGIN_SPEC.md §16.2 — Plugin-to-Plugin Events
+ */
+
+import type { PluginEventType } from "@paperclipai/shared";
+import type { PluginEvent, EventFilter } from "@paperclipai/plugin-sdk";
+
+// ---------------------------------------------------------------------------
+// Internal types
+// ---------------------------------------------------------------------------
+
+/**
+ * A registered subscription record stored per plugin.
+ */
+interface Subscription {
+ /** The event name or prefix pattern this subscription matches. */
+ eventPattern: string;
+ /** Optional server-side filter applied before delivery. */
+ filter: EventFilter | null;
+ /** Async handler to invoke when a matching event passes the filter. */
+ handler: (event: PluginEvent) => Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Pattern matching helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if the event type matches the subscription pattern.
+ *
+ * Matching rules:
+ * - Exact match: `"issue.created"` matches `"issue.created"`.
+ * - Wildcard suffix: `"plugin.acme.*"` matches any event type that starts with
+ * `"plugin.acme."`. The wildcard `*` is only supported as a trailing token.
+ *
+ * No full glob syntax is supported — only trailing `*` after a `.` separator.
+ */
+function matchesPattern(eventType: string, pattern: string): boolean {
+ if (pattern === eventType) return true;
+
+ // Trailing wildcard: "plugin.foo.*" → prefix is "plugin.foo."
+ if (pattern.endsWith(".*")) {
+ const prefix = pattern.slice(0, -1); // remove the trailing "*", keep the "."
+ return eventType.startsWith(prefix);
+ }
+
+ return false;
+}
+
+/**
+ * Returns true if the event passes all fields of the filter.
+ * A `null` or empty filter object passes all events.
+ *
+ * **Resolution strategy per field:**
+ *
+ * - `projectId` — checked against `event.entityId` when `entityType === "project"`,
+ * otherwise against `payload.projectId`. This covers both direct project events
+ * (e.g. `project.created`) and secondary events that embed a project reference in
+ * their payload (e.g. `issue.created` with `payload.projectId`).
+ *
+ * - `companyId` — always resolved from `payload.companyId`. Core domain events that
+ * belong to a company embed the company ID in their payload.
+ *
+ * - `agentId` — checked against `event.entityId` when `entityType === "agent"`,
+ * otherwise against `payload.agentId`. Covers both direct agent lifecycle events
+ * (e.g. `agent.created`) and run-level events with `payload.agentId` (e.g.
+ * `agent.run.started`).
+ *
+ * Multiple filter fields are ANDed — all specified fields must match.
+ */
+function passesFilter(event: PluginEvent, filter: EventFilter | null): boolean {
+ if (!filter) return true;
+
+ const payload = event.payload as Record<string, unknown> | null;
+
+ if (filter.projectId !== undefined) {
+ const projectId = event.entityType === "project"
+ ? event.entityId
+ : (typeof payload?.projectId === "string" ? payload.projectId : undefined);
+ if (projectId !== filter.projectId) return false;
+ }
+
+ if (filter.companyId !== undefined) {
+ if (event.companyId !== filter.companyId) return false;
+ }
+
+ if (filter.agentId !== undefined) {
+ const agentId = event.entityType === "agent"
+ ? event.entityId
+ : (typeof payload?.agentId === "string" ? payload.agentId : undefined);
+ if (agentId !== filter.agentId) return false;
+ }
+
+ return true;
+}
+
+// ---------------------------------------------------------------------------
+// Company availability checker
+// ---------------------------------------------------------------------------
+
+/**
+ * Callback that checks whether a plugin is enabled for a given company.
+ *
+ * The event bus calls this during `emit()` to enforce company-scoped delivery:
+ * events are only delivered to a plugin if the plugin is enabled for the
+ * company that owns the event.
+ *
+ * Implementations should be fast — the bus caches results internally with a
+ * short TTL so the checker is not invoked on every single event.
+ *
+ * @param pluginKey The plugin registry key — the string passed to `forPlugin()`
+ * (e.g. `"acme.linear"`). This is the same key used throughout the bus
+ * internally and should not be confused with a numeric or UUID plugin ID.
+ * @param companyId UUID of the company to check availability for.
+ *
+ * Return `true` if the plugin is enabled (or if no settings row exists, i.e.
+ * default-enabled), `false` if the company has explicitly disabled the plugin.
+ */
+export type CompanyAvailabilityChecker = (
+ pluginKey: string,
+ companyId: string,
+) => Promise<boolean>;
+
+/**
+ * Options for {@link createPluginEventBus}.
+ */
+export interface PluginEventBusOptions {
+ /**
+ * Optional checker that gates event delivery per company.
+ *
+ * When provided, the bus will skip delivery to a plugin if the checker
+ * returns `false` for the `(pluginKey, event.companyId)` pair, where
+ * `pluginKey` is the registry key supplied to `forPlugin()`. Results are
+ * cached with a short TTL (30 s) to avoid excessive lookups.
+ *
+ * When omitted, no company-scoping is applied (useful in tests).
+ */
+ isPluginEnabledForCompany?: CompanyAvailabilityChecker;
+}
+
+// Default cache TTL in milliseconds (30 seconds).
+const AVAILABILITY_CACHE_TTL_MS = 30_000;
+
+// Maximum number of entries in the availability cache before it is cleared.
+// Prevents unbounded memory growth in long-running processes with many unique
+// (pluginKey, companyId) pairs. A full clear is intentionally simple — the
+// cache is advisory (performance only) and a miss merely triggers one extra
+// async lookup.
+const MAX_AVAILABILITY_CACHE_SIZE = 10_000;
+
+// ---------------------------------------------------------------------------
+// Event bus factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates and returns a new `PluginEventBus` instance.
+ *
+ * A single bus instance should be shared across the server process. Each
+ * plugin interacts with the bus through a scoped handle obtained via
+ * {@link PluginEventBus.forPlugin}.
+ *
+ * @example
+ * ```ts
+ * const bus = createPluginEventBus();
+ *
+ * // Give the Linear plugin a scoped handle
+ * const linearBus = bus.forPlugin("acme.linear");
+ *
+ * // Subscribe from the plugin's perspective
+ * linearBus.subscribe("issue.created", async (event) => {
+ * // handle event
+ * });
+ *
+ * // Emit a core domain event (called by the host, not the plugin)
+ * await bus.emit({
+ * eventId: "evt-1",
+ * eventType: "issue.created",
+ * occurredAt: new Date().toISOString(),
+ * entityId: "iss-1",
+ * entityType: "issue",
+ * payload: { title: "Fix login bug", projectId: "proj-1" },
+ * });
+ * ```
+ */
+export function createPluginEventBus(options?: PluginEventBusOptions): PluginEventBus {
+ const checker = options?.isPluginEnabledForCompany ?? null;
+
+ // Subscription registry: pluginKey → list of subscriptions
+ const registry = new Map<string, Subscription[]>();
+
+ // Short-TTL cache for company availability lookups: "pluginKey\0companyId" → { enabled, expiresAt }
+ const availabilityCache = new Map<string, { enabled: boolean; expiresAt: number }>();
+
+ function cacheKey(pluginKey: string, companyId: string): string {
+ return `${pluginKey}\0${companyId}`;
+ }
+
+ /**
+ * Check whether a plugin is enabled for a company, using the cached result
+ * when available and falling back to the injected checker.
+ */
+ async function isEnabledForCompany(pluginKey: string, companyId: string): Promise<boolean> {
+ if (!checker) return true;
+
+ const key = cacheKey(pluginKey, companyId);
+ const cached = availabilityCache.get(key);
+ if (cached && cached.expiresAt > Date.now()) {
+ return cached.enabled;
+ }
+
+ const enabled = await checker(pluginKey, companyId);
+ if (availabilityCache.size >= MAX_AVAILABILITY_CACHE_SIZE) {
+ availabilityCache.clear();
+ }
+ availabilityCache.set(key, { enabled, expiresAt: Date.now() + AVAILABILITY_CACHE_TTL_MS });
+ return enabled;
+ }
+
+ /**
+ * Retrieve or create the subscription list for a plugin.
+ */
+ function subsFor(pluginId: string): Subscription[] {
+ let subs = registry.get(pluginId);
+ if (!subs) {
+ subs = [];
+ registry.set(pluginId, subs);
+ }
+ return subs;
+ }
+
+ /**
+ * Emit an event envelope to all matching subscribers across all plugins.
+ *
+ * Subscribers are called concurrently (Promise.all). Each handler's errors
+ * are caught individually and collected in the returned `errors` array so a
+ * single misbehaving plugin cannot interrupt delivery to other plugins.
+ */
+ async function emit(event: PluginEvent): Promise<PluginEventBusEmitResult> {
+ const errors: Array<{ pluginId: string; error: unknown }> = [];
+ const promises: Promise<void>[] = [];
+
+ // Pre-compute company availability for all registered plugins when the
+ // event carries a companyId and a checker is configured. This batches
+ // the (potentially async) lookups so we don't interleave them with
+ // handler dispatch.
+ let disabledPlugins: Set<string> | null = null;
+ if (checker && event.companyId) {
+ const pluginKeys = Array.from(registry.keys());
+ const checks = await Promise.all(
+ pluginKeys.map(async (pluginKey) => ({
+ pluginKey,
+ enabled: await isEnabledForCompany(pluginKey, event.companyId!),
+ })),
+ );
+ disabledPlugins = new Set(checks.filter((c) => !c.enabled).map((c) => c.pluginKey));
+ }
+
+ for (const [pluginId, subs] of registry) {
+ // Skip delivery to plugins that are disabled for this company.
+ if (disabledPlugins?.has(pluginId)) continue;
+
+ for (const sub of subs) {
+ if (!matchesPattern(event.eventType, sub.eventPattern)) continue;
+ if (!passesFilter(event, sub.filter)) continue;
+
+ // Use Promise.resolve().then() so that synchronous throws from handlers
+ // are also caught inside the promise chain. Calling
+ // Promise.resolve(syncThrowingFn()) does NOT catch sync throws — the
+ // throw escapes before Promise.resolve() can wrap it. Using .then()
+ // ensures the call is deferred into the microtask queue where all
+ // exceptions become rejections. Each .catch() swallows the rejection
+ // and records it — the promise always resolves, so Promise.all never rejects.
+ promises.push(
+ Promise.resolve().then(() => sub.handler(event)).catch((error: unknown) => {
+ errors.push({ pluginId, error });
+ }),
+ );
+ }
+ }
+
+ await Promise.all(promises);
+ return { errors };
+ }
+
+ /**
+ * Remove all subscriptions for a plugin (e.g. on worker shutdown or uninstall).
+ */
+ function clearPlugin(pluginId: string): void {
+ registry.delete(pluginId);
+ }
+
+ /**
+ * Return a scoped handle for a specific plugin. The handle exposes only the
+ * plugin's own subscription list and enforces the plugin namespace on `emit`.
+ */
+ function forPlugin(pluginId: string): ScopedPluginEventBus {
+ return {
+ /**
+ * Subscribe to a core domain event or a plugin-namespaced event.
+ *
+ * For wildcard subscriptions use a trailing `.*` pattern, e.g.
+ * `"plugin.acme.linear.*"`.
+ *
+ * Requires the `events.subscribe` capability (capability enforcement is
+ * done by the host layer before calling this method).
+ */
+ subscribe(
+ eventPattern: PluginEventType | `plugin.${string}`,
+ fnOrFilter: EventFilter | ((event: PluginEvent) => Promise<void>),
+ maybeFn?: (event: PluginEvent) => Promise<void>,
+ ): void {
+ let filter: EventFilter | null = null;
+ let handler: (event: PluginEvent) => Promise<void>;
+
+ if (typeof fnOrFilter === "function") {
+ handler = fnOrFilter;
+ } else {
+ filter = fnOrFilter;
+ if (!maybeFn) throw new Error("Handler function is required when a filter is provided");
+ handler = maybeFn;
+ }
+
+ subsFor(pluginId).push({ eventPattern, filter, handler });
+ },
+
+ /**
+ * Emit a plugin-namespaced event. The event type is automatically
+ * prefixed with `plugin.<pluginId>.` so:
+ * - `emit("sync-done", payload)` becomes `"plugin.acme.linear.sync-done"`.
+ *
+ * Requires the `events.emit` capability (enforced by the host layer).
+ *
+ * @throws {Error} if `name` already contains the `plugin.` prefix
+ * (prevents cross-namespace spoofing).
+ */
+ async emit(name: string, companyId: string, payload: unknown): Promise<PluginEventBusEmitResult> {
+ if (!name || name.trim() === "") {
+ throw new Error(`Plugin "${pluginId}" must provide a non-empty event name.`);
+ }
+
+ if (!companyId || companyId.trim() === "") {
+ throw new Error(`Plugin "${pluginId}" must provide a companyId when emitting events.`);
+ }
+
+ if (name.startsWith("plugin.")) {
+ throw new Error(
+ `Plugin "${pluginId}" must not include the "plugin." prefix when emitting events. ` +
+ `Emit the bare event name (e.g. "sync-done") and the bus will namespace it automatically.`,
+ );
+ }
+
+ const eventType = `plugin.${pluginId}.${name}` as const;
+ const event: PluginEvent = {
+ eventId: crypto.randomUUID(),
+ eventType,
+ companyId,
+ occurredAt: new Date().toISOString(),
+ actorType: "plugin",
+ actorId: pluginId,
+ payload,
+ };
+
+ return emit(event);
+ },
+
+ /** Remove all subscriptions registered by this plugin. */
+ clear(): void {
+ clearPlugin(pluginId);
+ },
+ };
+ }
+
+ return {
+ emit,
+ forPlugin,
+ clearPlugin,
+ /** Expose subscription count for a plugin (useful for tests and diagnostics). */
+ subscriptionCount(pluginId?: string): number {
+ if (pluginId !== undefined) {
+ return registry.get(pluginId)?.length ?? 0;
+ }
+ let total = 0;
+ for (const subs of registry.values()) total += subs.length;
+ return total;
+ },
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Result returned from `emit()`. Handler errors are collected and returned
+ * rather than thrown so a single misbehaving plugin cannot block delivery to
+ * other plugins.
+ */
+export interface PluginEventBusEmitResult {
+ /** Errors thrown by individual handlers, keyed by the plugin that failed. */
+ errors: Array<{ pluginId: string; error: unknown }>;
+}
+
+/**
+ * The full event bus — held by the host process.
+ *
+ * Call `forPlugin(id)` to obtain a `ScopedPluginEventBus` for each plugin worker.
+ */
+export interface PluginEventBus {
+ /**
+ * Emit a typed domain event to all matching subscribers.
+ *
+ * Called by the host when a domain event occurs (e.g. from the DB layer or
+ * message queue). All registered subscriptions across all plugins are checked.
+ */
+ emit(event: PluginEvent): Promise<PluginEventBusEmitResult>;
+
+ /**
+ * Get a scoped handle for a specific plugin worker.
+ *
+ * The scoped handle isolates the plugin's subscriptions and enforces the
+ * plugin namespace on outbound events.
+ */
+ forPlugin(pluginId: string): ScopedPluginEventBus;
+
+ /**
+ * Remove all subscriptions for a plugin (called on worker shutdown/uninstall).
+ */
+ clearPlugin(pluginId: string): void;
+
+ /**
+ * Return the total number of active subscriptions, or the count for a
+ * specific plugin if `pluginId` is provided.
+ */
+ subscriptionCount(pluginId?: string): number;
+}
+
+/**
+ * A plugin-scoped view of the event bus. Handed to the plugin worker (or its
+ * host-side proxy) during initialisation.
+ *
+ * Plugins use this to:
+ * 1. Subscribe to domain events (with optional server-side filter).
+ * 2. Emit plugin-namespaced events for other plugins to consume.
+ *
+ * Note: `subscribe` overloads mirror the `PluginEventsClient.on()` interface
+ * from the SDK. `emit` intentionally returns `PluginEventBusEmitResult` rather
+ * than `void` so the host layer can inspect handler errors; the SDK-facing
+ * `PluginEventsClient.emit()` wraps this and returns `void`.
+ */
+export interface ScopedPluginEventBus {
+ /**
+ * Subscribe to a core domain event or a plugin-namespaced event.
+ *
+ * **Pattern syntax:**
+ * - Exact match: `"issue.created"` — receives only that event type.
+ * - Wildcard suffix: `"plugin.acme.linear.*"` — receives all events emitted by
+ * the `acme.linear` plugin. The `*` is supported only as a trailing token after
+ * a `.` separator; no other glob syntax is supported.
+ * - Top-level plugin wildcard: `"plugin.*"` — receives all plugin-emitted events
+ * regardless of which plugin emitted them.
+ *
+ * Wildcards apply only to the `plugin.*` namespace. Core domain events must be
+ * subscribed to by exact name (e.g. `"issue.created"`, not `"issue.*"`).
+ *
+ * An optional `EventFilter` can be passed as the second argument to perform
+ * server-side pre-filtering; filtered-out events are never delivered to the handler.
+ */
+ subscribe(
+ eventPattern: PluginEventType | `plugin.${string}`,
+ fn: (event: PluginEvent) => Promise<void>,
+ ): void;
+ subscribe(
+ eventPattern: PluginEventType | `plugin.${string}`,
+ filter: EventFilter,
+ fn: (event: PluginEvent) => Promise<void>,
+ ): void;
+
+ /**
+ * Emit a plugin-namespaced event. The bus automatically prepends
+ * `plugin.<pluginId>.` to the `name`, so passing `"sync-done"` from plugin
+ * `"acme.linear"` produces the event type `"plugin.acme.linear.sync-done"`.
+ *
+ * @param name Bare event name (e.g. `"sync-done"`). Must be non-empty and
+ * must not include the `plugin.` prefix — the bus adds that automatically.
+ * @param companyId UUID of the company this event belongs to.
+ * @param payload Arbitrary JSON-serializable data to attach to the event.
+ *
+ * @throws {Error} if `name` is empty or whitespace-only.
+ * @throws {Error} if `name` starts with `"plugin."` (namespace spoofing guard).
+ */
+ emit(name: string, companyId: string, payload: unknown): Promise<PluginEventBusEmitResult>;
+
+ /**
+ * Remove all subscriptions registered by this plugin.
+ */
+ clear(): void;
+}
diff --git a/server/src/services/plugin-host-service-cleanup.ts b/server/src/services/plugin-host-service-cleanup.ts
new file mode 100644
index 0000000000..cd197f7fa7
--- /dev/null
+++ b/server/src/services/plugin-host-service-cleanup.ts
@@ -0,0 +1,59 @@
+import type { PluginLifecycleManager } from "./plugin-lifecycle.js";
+
+type LifecycleLike = Pick<PluginLifecycleManager, "on" | "off">;
+
+export interface PluginWorkerRuntimeEvent {
+ type: "plugin.worker.crashed" | "plugin.worker.restarted";
+ pluginId: string;
+}
+
+export interface PluginHostServiceCleanupController {
+ handleWorkerEvent(event: PluginWorkerRuntimeEvent): void;
+ disposeAll(): void;
+ teardown(): void;
+}
+
+export function createPluginHostServiceCleanup(
+ lifecycle: LifecycleLike,
+ disposers: Map<string, () => void>,
+): PluginHostServiceCleanupController {
+ const runDispose = (pluginId: string, remove = false) => {
+ const dispose = disposers.get(pluginId);
+ if (!dispose) return;
+ dispose();
+ if (remove) {
+ disposers.delete(pluginId);
+ }
+ };
+
+ const handleWorkerStopped = ({ pluginId }: { pluginId: string }) => {
+ runDispose(pluginId);
+ };
+
+ const handlePluginUnloaded = ({ pluginId }: { pluginId: string }) => {
+ runDispose(pluginId, true);
+ };
+
+ lifecycle.on("plugin.worker_stopped", handleWorkerStopped);
+ lifecycle.on("plugin.unloaded", handlePluginUnloaded);
+
+ return {
+ handleWorkerEvent(event) {
+ if (event.type === "plugin.worker.crashed") {
+ runDispose(event.pluginId);
+ }
+ },
+
+ disposeAll() {
+ for (const dispose of disposers.values()) {
+ dispose();
+ }
+ disposers.clear();
+ },
+
+ teardown() {
+ lifecycle.off("plugin.worker_stopped", handleWorkerStopped);
+ lifecycle.off("plugin.unloaded", handlePluginUnloaded);
+ },
+ };
+}
diff --git a/server/src/services/plugin-host-services.ts b/server/src/services/plugin-host-services.ts
new file mode 100644
index 0000000000..d7910e97ed
--- /dev/null
+++ b/server/src/services/plugin-host-services.ts
@@ -0,0 +1,1077 @@
+import type { Db } from "@paperclipai/db";
+import { pluginLogs, agentTaskSessions as agentTaskSessionsTable } from "@paperclipai/db";
+import { eq, and, like, desc } from "drizzle-orm";
+import type {
+ HostServices,
+ Company,
+ Agent,
+ Project,
+ Issue,
+ Goal,
+ PluginWorkspace,
+ IssueComment,
+} from "@paperclipai/plugin-sdk";
+import { companyService } from "./companies.js";
+import { agentService } from "./agents.js";
+import { projectService } from "./projects.js";
+import { issueService } from "./issues.js";
+import { goalService } from "./goals.js";
+import { heartbeatService } from "./heartbeat.js";
+import { subscribeCompanyLiveEvents } from "./live-events.js";
+import { randomUUID } from "node:crypto";
+import { activityService } from "./activity.js";
+import { costService } from "./costs.js";
+import { assetService } from "./assets.js";
+import { pluginRegistryService } from "./plugin-registry.js";
+import { pluginStateStore } from "./plugin-state-store.js";
+import { createPluginSecretsHandler } from "./plugin-secrets-handler.js";
+import { logActivity } from "./activity-log.js";
+import type { PluginEventBus } from "./plugin-event-bus.js";
+import { lookup as dnsLookup } from "node:dns/promises";
+import type { IncomingMessage, RequestOptions as HttpRequestOptions } from "node:http";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { isIP } from "node:net";
+import { logger } from "../middleware/logger.js";
+
+// ---------------------------------------------------------------------------
+// SSRF protection for plugin HTTP fetch
+// ---------------------------------------------------------------------------
+
+/** Maximum time (ms) a plugin fetch request may take before being aborted. */
+const PLUGIN_FETCH_TIMEOUT_MS = 30_000;
+
+/** Maximum time (ms) to wait for a DNS lookup before aborting. */
+const DNS_LOOKUP_TIMEOUT_MS = 5_000;
+
+/** Only these protocols are allowed for plugin HTTP requests. */
+const ALLOWED_PROTOCOLS = new Set(["http:", "https:"]);
+
+/**
+ * Check if an IP address is in a private/reserved range (RFC 1918, loopback,
+ * link-local, etc.) that plugins should never be able to reach.
+ *
+ * Handles IPv4-mapped IPv6 addresses (e.g. ::ffff:127.0.0.1) which Node's
+ * dns.lookup may return depending on OS configuration.
+ */
+function isPrivateIP(ip: string): boolean {
+ const lower = ip.toLowerCase();
+
+ // Unwrap IPv4-mapped IPv6 addresses (::ffff:x.x.x.x) and re-check as IPv4
+ const v4MappedMatch = lower.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+ if (v4MappedMatch && v4MappedMatch[1]) return isPrivateIP(v4MappedMatch[1]);
+
+ // IPv4 patterns
+ if (ip.startsWith("10.")) return true;
+ if (ip.startsWith("172.")) {
+ const second = parseInt(ip.split(".")[1]!, 10);
+ if (second >= 16 && second <= 31) return true;
+ }
+ if (ip.startsWith("192.168.")) return true;
+ if (ip.startsWith("127.")) return true; // loopback
+ if (ip.startsWith("169.254.")) return true; // link-local
+ if (ip === "0.0.0.0") return true;
+
+ // IPv6 patterns
+ if (lower === "::1") return true; // loopback
+ if (lower.startsWith("fc") || lower.startsWith("fd")) return true; // ULA
+ if (lower.startsWith("fe80")) return true; // link-local
+ if (lower === "::") return true;
+
+ return false;
+}
+
+/**
+ * Validate a URL for plugin fetch: protocol whitelist + private IP blocking.
+ *
+ * SSRF Prevention Strategy:
+ * 1. Parse and validate the URL syntax
+ * 2. Enforce protocol whitelist (http/https only)
+ * 3. Resolve the hostname to IP(s) via DNS
+ * 4. Validate that ALL resolved IPs are non-private
+ * 5. Pin the first safe IP into the URL so fetch() does not re-resolve DNS
+ *
+ * This prevents DNS rebinding attacks where an attacker controls DNS to
+ * resolve to a safe IP during validation, then to a private IP when fetch() runs.
+ *
+ * @returns Request-routing metadata used to connect directly to the resolved IP
+ * while preserving the original hostname for HTTP Host and TLS SNI.
+ */
+interface ValidatedFetchTarget {
+ parsedUrl: URL;
+ resolvedAddress: string;
+ hostHeader: string;
+ tlsServername?: string;
+ useTls: boolean;
+}
+
+async function validateAndResolveFetchUrl(urlString: string): Promise<ValidatedFetchTarget> {
+ let parsed: URL;
+ try {
+ parsed = new URL(urlString);
+ } catch {
+ throw new Error(`Invalid URL: ${urlString}`);
+ }
+
+ if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+ throw new Error(
+ `Disallowed protocol "${parsed.protocol}" — only http: and https: are permitted`,
+ );
+ }
+
+ // Resolve the hostname to an IP and check for private ranges.
+ // We pin the resolved IP into the URL to eliminate the TOCTOU window
+ // between DNS resolution here and the second resolution fetch() would do.
+ const originalHostname = parsed.hostname.replace(/^\[|\]$/g, ""); // strip IPv6 brackets
+ const hostHeader = parsed.host; // includes port if non-default
+
+ // Race the DNS lookup against a timeout to prevent indefinite hangs
+ // when DNS is misconfigured or unresponsive.
+ const dnsPromise = dnsLookup(originalHostname, { all: true });
+ const timeoutPromise = new Promise<never>((_, reject) => {
+ setTimeout(
+ () => reject(new Error(`DNS lookup timed out after ${DNS_LOOKUP_TIMEOUT_MS}ms for ${originalHostname}`)),
+ DNS_LOOKUP_TIMEOUT_MS,
+ );
+ });
+
+ try {
+ const results = await Promise.race([dnsPromise, timeoutPromise]);
+ if (results.length === 0) {
+ throw new Error(`DNS resolution returned no results for ${originalHostname}`);
+ }
+
+ // Filter to only non-private IPs instead of rejecting the entire request
+ // when some IPs are private. This handles multi-homed hosts that resolve
+ // to both private and public addresses.
+ const safeResults = results.filter((entry) => !isPrivateIP(entry.address));
+ if (safeResults.length === 0) {
+ throw new Error(
+ `All resolved IPs for ${originalHostname} are in private/reserved ranges`,
+ );
+ }
+
+ const resolved = safeResults[0]!;
+ return {
+ parsedUrl: parsed,
+ resolvedAddress: resolved.address,
+ hostHeader,
+ tlsServername: parsed.protocol === "https:" && isIP(originalHostname) === 0
+ ? originalHostname
+ : undefined,
+ useTls: parsed.protocol === "https:",
+ };
+ } catch (err) {
+ // Re-throw our own errors; wrap DNS failures
+ if (err instanceof Error && (
+ err.message.startsWith("All resolved IPs") ||
+ err.message.startsWith("DNS resolution returned") ||
+ err.message.startsWith("DNS lookup timed out")
+ )) throw err;
+ throw new Error(`DNS resolution failed for ${originalHostname}: ${(err as Error).message}`);
+ }
+}
+
+function buildPinnedRequestOptions(
+ target: ValidatedFetchTarget,
+ init?: RequestInit,
+): { options: HttpRequestOptions & { servername?: string }; body: string | undefined } {
+ const headers = new Headers(init?.headers);
+ const method = init?.method ?? "GET";
+ const body = init?.body === undefined || init?.body === null
+ ? undefined
+ : typeof init.body === "string"
+ ? init.body
+ : String(init.body);
+
+ headers.set("Host", target.hostHeader);
+ if (body !== undefined && !headers.has("content-length") && !headers.has("transfer-encoding")) {
+ headers.set("content-length", String(Buffer.byteLength(body)));
+ }
+
+ const pathname = `${target.parsedUrl.pathname}${target.parsedUrl.search}`;
+ const auth = target.parsedUrl.username || target.parsedUrl.password
+ ? `${decodeURIComponent(target.parsedUrl.username)}:${decodeURIComponent(target.parsedUrl.password)}`
+ : undefined;
+
+ return {
+ options: {
+ protocol: target.parsedUrl.protocol,
+ host: target.resolvedAddress,
+ port: target.parsedUrl.port
+ ? Number(target.parsedUrl.port)
+ : target.useTls
+ ? 443
+ : 80,
+ path: pathname,
+ method,
+ headers: Object.fromEntries(headers.entries()),
+ auth,
+ servername: target.tlsServername,
+ },
+ body,
+ };
+}
+
+async function executePinnedHttpRequest(
+ target: ValidatedFetchTarget,
+ init: RequestInit | undefined,
+ signal: AbortSignal,
+): Promise<{ status: number; statusText: string; headers: Record<string, string>; body: string }> {
+ const { options, body } = buildPinnedRequestOptions(target, init);
+
+ const response = await new Promise<IncomingMessage>((resolve, reject) => {
+ const requestFn = target.useTls ? httpsRequest : httpRequest;
+ const req = requestFn({ ...options, signal }, resolve);
+
+ req.on("error", reject);
+
+ if (body !== undefined) {
+ req.write(body);
+ }
+ req.end();
+ });
+
+ const MAX_RESPONSE_BODY_BYTES = 200 * 1024 * 1024; // 200 MB
+ const chunks: Buffer[] = [];
+ let totalBytes = 0;
+ await new Promise<void>((resolve, reject) => {
+ response.on("data", (chunk: Buffer | string) => {
+ const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+ totalBytes += buf.length;
+ if (totalBytes > MAX_RESPONSE_BODY_BYTES) {
+ chunks.length = 0;
+ response.destroy(new Error(`Response body exceeded ${MAX_RESPONSE_BODY_BYTES} bytes`));
+ return;
+ }
+ chunks.push(buf);
+ });
+ response.on("end", resolve);
+ response.on("error", reject);
+ });
+
+ const headers: Record<string, string> = {};
+ for (const [key, value] of Object.entries(response.headers)) {
+ if (Array.isArray(value)) {
+ headers[key] = value.join(", ");
+ } else if (value !== undefined) {
+ headers[key] = value;
+ }
+ }
+
+ return {
+ status: response.statusCode ?? 500,
+ statusText: response.statusMessage ?? "",
+ headers,
+ body: Buffer.concat(chunks).toString("utf8"),
+ };
+}
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const PATH_LIKE_PATTERN = /[\\/]/;
+const WINDOWS_DRIVE_PATH_PATTERN = /^[A-Za-z]:[\\/]/;
+
+function looksLikePath(value: string): boolean {
+ const normalized = value.trim();
+ return (
+ PATH_LIKE_PATTERN.test(normalized)
+ || WINDOWS_DRIVE_PATH_PATTERN.test(normalized)
+ ) && !UUID_PATTERN.test(normalized);
+}
+
+function sanitizeWorkspaceText(value: string): string {
+ const trimmed = value.trim();
+ if (!trimmed || UUID_PATTERN.test(trimmed)) return "";
+ return trimmed;
+}
+
+function sanitizeWorkspacePath(cwd: string | null): string {
+ if (!cwd) return "";
+ return looksLikePath(cwd) ? cwd.trim() : "";
+}
+
+function sanitizeWorkspaceName(name: string, fallbackPath: string): string {
+ const safeName = sanitizeWorkspaceText(name);
+ if (safeName && !looksLikePath(safeName)) {
+ return safeName;
+ }
+ const normalized = fallbackPath.trim().replace(/[\\/]+$/, "");
+ const segments = normalized.split(/[\\/]/).filter(Boolean);
+ return segments[segments.length - 1] ?? "Workspace";
+}
+
+// ---------------------------------------------------------------------------
+// Buffered plugin log writes
+// ---------------------------------------------------------------------------
+
+/** How many buffered log entries trigger an immediate flush. */
+const LOG_BUFFER_FLUSH_SIZE = 100;
+
+/** How often (ms) the buffer is flushed regardless of size. */
+const LOG_BUFFER_FLUSH_INTERVAL_MS = 5_000;
+
+/** Max length for a single plugin log message (bytes/chars). */
+const MAX_LOG_MESSAGE_LENGTH = 10_000;
+
+/** Max serialised JSON size for plugin log meta objects. */
+const MAX_LOG_META_JSON_LENGTH = 50_000;
+
+/** Max length for a metric name. */
+const MAX_METRIC_NAME_LENGTH = 500;
+
+/** Pino reserved field names that plugins must not overwrite. */
+const PINO_RESERVED_KEYS = new Set([
+ "level",
+ "time",
+ "pid",
+ "hostname",
+ "msg",
+ "v",
+]);
+
+/** Truncate a string to `max` characters, appending a marker if truncated. */
+function truncStr(s: string, max: number): string {
+ if (s.length <= max) return s;
+ return s.slice(0, max) + "...[truncated]";
+}
+
+/** Sanitise a plugin-supplied meta object: enforce size limit and strip reserved keys. */
+function sanitiseMeta(meta: Record<string, unknown> | null | undefined): Record<string, unknown> | null {
+ if (meta == null) return null;
+ // Strip pino reserved keys
+ const cleaned: Record<string, unknown> = {};
+ for (const [k, v] of Object.entries(meta)) {
+ if (!PINO_RESERVED_KEYS.has(k)) {
+ cleaned[k] = v;
+ }
+ }
+ // Enforce total serialised size
+ let json: string;
+ try {
+ json = JSON.stringify(cleaned);
+ } catch {
+ return { _sanitised: true, _error: "meta was not JSON-serialisable" };
+ }
+ if (json.length > MAX_LOG_META_JSON_LENGTH) {
+ return { _sanitised: true, _error: `meta exceeded ${MAX_LOG_META_JSON_LENGTH} chars` };
+ }
+ return cleaned;
+}
+
+interface BufferedLogEntry {
+ db: Db;
+ pluginId: string;
+ level: string;
+ message: string;
+ meta: Record<string, unknown> | null;
+}
+
+const _logBuffer: BufferedLogEntry[] = [];
+
+/**
+ * Flush all buffered log entries to the database in a single batch insert per
+ * unique db instance. Errors are swallowed with a console.error fallback so
+ * flushing never crashes the process.
+ */
+export async function flushPluginLogBuffer(): Promise<void> {
+ if (_logBuffer.length === 0) return;
+
+ // Drain the buffer atomically so concurrent flushes don't double-insert.
+ const entries = _logBuffer.splice(0, _logBuffer.length);
+
+ // Group entries by db identity so multi-db scenarios are handled correctly.
+ const byDb = new Map<Db, BufferedLogEntry[]>();
+ for (const entry of entries) {
+ const group = byDb.get(entry.db);
+ if (group) {
+ group.push(entry);
+ } else {
+ byDb.set(entry.db, [entry]);
+ }
+ }
+
+ for (const [dbInstance, group] of byDb) {
+ const values = group.map((e) => ({
+ pluginId: e.pluginId,
+ level: e.level,
+ message: e.message,
+ meta: e.meta,
+ }));
+ try {
+ await dbInstance.insert(pluginLogs).values(values);
+ } catch (err) {
+ try {
+ logger.warn({ err, count: values.length }, "Failed to batch-persist plugin logs to DB");
+ } catch {
+ console.error("[plugin-host-services] Batch log flush failed:", err);
+ }
+ }
+ }
+}
+
+/** Interval handle for the periodic log flush. */
+const _logFlushInterval = setInterval(() => {
+ flushPluginLogBuffer().catch((err) => {
+ console.error("[plugin-host-services] Periodic log flush error:", err);
+ });
+}, LOG_BUFFER_FLUSH_INTERVAL_MS);
+
+// Allow the interval to be unref'd so it doesn't keep the process alive in tests.
+if (_logFlushInterval.unref) _logFlushInterval.unref();
+
+/**
+ * buildHostServices — creates a concrete implementation of the `HostServices`
+ * interface for a specific plugin.
+ *
+ * This implementation delegates to the core Paperclip domain services,
+ * providing the bridge between the plugin worker's SDK and the host platform.
+ *
+ * @param db - Database connection instance.
+ * @param pluginId - The UUID of the plugin installation record.
+ * @param pluginKey - The unique identifier from the plugin manifest (e.g., "acme.linear").
+ * @param eventBus - The system-wide event bus for publishing plugin events.
+ * @returns An object implementing the HostServices interface for the plugin SDK.
+ */
+/** Maximum time (ms) to keep a session event subscription alive before forcing cleanup. */
+const SESSION_EVENT_SUBSCRIPTION_TIMEOUT_MS = 30 * 60 * 1_000; // 30 minutes
+
+export function buildHostServices(
+ db: Db,
+ pluginId: string,
+ pluginKey: string,
+ eventBus: PluginEventBus,
+ notifyWorker?: (method: string, params: unknown) => void,
+): HostServices & { dispose(): void } {
+ const registry = pluginRegistryService(db);
+ const stateStore = pluginStateStore(db);
+ const secretsHandler = createPluginSecretsHandler({ db, pluginId });
+ const companies = companyService(db);
+ const agents = agentService(db);
+ const heartbeat = heartbeatService(db);
+ const projects = projectService(db);
+ const issues = issueService(db);
+ const goals = goalService(db);
+ const activity = activityService(db);
+ const costs = costService(db);
+ const assets = assetService(db);
+ const scopedBus = eventBus.forPlugin(pluginKey);
+
+ // Track active session event subscriptions for cleanup
+ const activeSubscriptions = new Set<{ unsubscribe: () => void; timer: ReturnType<typeof setTimeout> }>();
+ let disposed = false;
+
+ const ensureCompanyId = (companyId?: string) => {
+ if (!companyId) throw new Error("companyId is required for this operation");
+ return companyId;
+ };
+
+ /**
+ * Verify that this plugin is enabled for the given company.
+ * Throws if the plugin is disabled or unavailable, preventing
+ * worker-driven access to companies that have not opted in.
+ */
+ const ensurePluginAvailableForCompany = async (companyId: string) => {
+ const availability = await registry.getCompanyAvailability(companyId, pluginId);
+ if (!availability || !availability.available) {
+ throw new Error(
+ `Plugin "${pluginKey}" is not enabled for company "${companyId}"`,
+ );
+ }
+ };
+
+ const inCompany = <T extends { companyId: string | null | undefined }>(
+ record: T | null | undefined,
+ companyId: string,
+ ): record is T => Boolean(record && record.companyId === companyId);
+
+ const requireInCompany = <T extends { companyId: string | null | undefined }>(
+ entityName: string,
+ record: T | null | undefined,
+ companyId: string,
+ ): T => {
+ if (!inCompany(record, companyId)) {
+ throw new Error(`${entityName} not found`);
+ }
+ return record;
+ };
+
+ return {
+ config: {
+ async get() {
+ const configRow = await registry.getConfig(pluginId);
+ return configRow?.configJson ?? {};
+ },
+ },
+
+ state: {
+ async get(params) {
+ return stateStore.get(pluginId, params.scopeKind as any, params.stateKey, {
+ scopeId: params.scopeId,
+ namespace: params.namespace,
+ });
+ },
+ async set(params) {
+ await stateStore.set(pluginId, {
+ scopeKind: params.scopeKind as any,
+ scopeId: params.scopeId,
+ namespace: params.namespace,
+ stateKey: params.stateKey,
+ value: params.value,
+ });
+ },
+ async delete(params) {
+ await stateStore.delete(pluginId, params.scopeKind as any, params.stateKey, {
+ scopeId: params.scopeId,
+ namespace: params.namespace,
+ });
+ },
+ },
+
+ entities: {
+ async upsert(params) {
+ return registry.upsertEntity(pluginId, params as any) as any;
+ },
+ async list(params) {
+ return registry.listEntities(pluginId, params as any) as any;
+ },
+ },
+
+ events: {
+ async emit(params) {
+ if (params.companyId) {
+ await ensurePluginAvailableForCompany(params.companyId);
+ }
+ await scopedBus.emit(params.name, params.companyId, params.payload);
+ },
+ },
+
+ http: {
+ async fetch(params) {
+ // SSRF protection: validate protocol whitelist + block private IPs.
+ // Resolve once, then connect directly to that IP to prevent DNS rebinding.
+ const target = await validateAndResolveFetchUrl(params.url);
+
+ const controller = new AbortController();
+ const timeout = setTimeout(() => controller.abort(), PLUGIN_FETCH_TIMEOUT_MS);
+
+ try {
+ const init = params.init as RequestInit | undefined;
+ return await executePinnedHttpRequest(target, init, controller.signal);
+ } finally {
+ clearTimeout(timeout);
+ }
+ },
+ },
+
+ secrets: {
+ async resolve(params) {
+ return secretsHandler.resolve(params);
+ },
+ },
+
+ assets: {
+ async upload(params) {
+ void params;
+ throw new Error("Plugin asset uploads are not supported in this build.");
+ },
+ async getUrl(params) {
+ void params;
+ throw new Error("Plugin asset URLs are not supported in this build.");
+ },
+ },
+
+ activity: {
+ async log(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ await logActivity(db, {
+ companyId,
+ actorType: "system",
+ actorId: pluginId,
+ action: params.message,
+ entityType: params.entityType ?? "plugin",
+ entityId: params.entityId ?? pluginId,
+ details: params.metadata,
+ });
+ },
+ },
+
+ metrics: {
+ async write(params) {
+ const safeName = truncStr(String(params.name ?? ""), MAX_METRIC_NAME_LENGTH);
+ logger.debug({ pluginId, name: safeName, value: params.value, tags: params.tags }, "Plugin metric write");
+
+ // Persist metrics to plugin_logs via the batch buffer (same path as
+ // logger.log) so they benefit from batched writes and are flushed
+ // reliably on shutdown. Using level "metric" makes them queryable
+ // alongside regular logs via the same API (§26).
+ _logBuffer.push({
+ db,
+ pluginId,
+ level: "metric",
+ message: safeName,
+ meta: sanitiseMeta({ value: params.value, tags: params.tags ?? null }),
+ });
+ if (_logBuffer.length >= LOG_BUFFER_FLUSH_SIZE) {
+ flushPluginLogBuffer().catch((err) => {
+ console.error("[plugin-host-services] Triggered metric flush failed:", err);
+ });
+ }
+ },
+ },
+
+ logger: {
+ async log(params) {
+ const { level, meta } = params;
+ const safeMessage = truncStr(String(params.message ?? ""), MAX_LOG_MESSAGE_LENGTH);
+ const safeMeta = sanitiseMeta(meta);
+ const pluginLogger = logger.child({ service: "plugin-worker", pluginId });
+ const logFields = {
+ ...safeMeta,
+ pluginLogLevel: level,
+ pluginTimestamp: new Date().toISOString(),
+ };
+
+ if (level === "error") pluginLogger.error(logFields, `[plugin] ${safeMessage}`);
+ else if (level === "warn") pluginLogger.warn(logFields, `[plugin] ${safeMessage}`);
+ else if (level === "debug") pluginLogger.debug(logFields, `[plugin] ${safeMessage}`);
+ else pluginLogger.info(logFields, `[plugin] ${safeMessage}`);
+
+ // Persist to plugin_logs table via the module-level batch buffer (§26.1).
+ // Fire-and-forget — logging should never block the worker.
+ _logBuffer.push({
+ db,
+ pluginId,
+ level: level ?? "info",
+ message: safeMessage,
+ meta: safeMeta,
+ });
+ if (_logBuffer.length >= LOG_BUFFER_FLUSH_SIZE) {
+ flushPluginLogBuffer().catch((err) => {
+ console.error("[plugin-host-services] Triggered log flush failed:", err);
+ });
+ }
+ },
+ },
+
+ companies: {
+ async list(_params) {
+ const allCompanies = (await companies.list()) as Company[];
+ if (allCompanies.length === 0) return [];
+
+ // Batch query: fetch all company settings for this plugin in one query
+ // instead of N+1 individual getCompanyAvailability() calls.
+ const companyIds = allCompanies.map((c) => c.id);
+ const disabledCompanyIds = await registry.getDisabledCompanyIds(companyIds, pluginId);
+ return allCompanies.filter((c) => !disabledCompanyIds.has(c.id));
+ },
+ async get(params) {
+ await ensurePluginAvailableForCompany(params.companyId);
+ return (await companies.getById(params.companyId)) as Company;
+ },
+ },
+
+ projects: {
+ async list(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ return (await projects.list(companyId)) as Project[];
+ },
+ async get(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const project = await projects.getById(params.projectId);
+ return (inCompany(project, companyId) ? project : null) as Project | null;
+ },
+ async listWorkspaces(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const project = await projects.getById(params.projectId);
+ if (!inCompany(project, companyId)) return [];
+ const rows = await projects.listWorkspaces(params.projectId);
+ return rows.map((row) => {
+ const path = sanitizeWorkspacePath(row.cwd);
+ const name = sanitizeWorkspaceName(row.name, path);
+ return {
+ id: row.id,
+ projectId: row.projectId,
+ name,
+ path,
+ isPrimary: row.isPrimary,
+ createdAt: row.createdAt.toISOString(),
+ updatedAt: row.updatedAt.toISOString(),
+ };
+ });
+ },
+ async getPrimaryWorkspace(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const project = await projects.getById(params.projectId);
+ if (!inCompany(project, companyId)) return null;
+ const row = project.primaryWorkspace;
+ if (!row) return null;
+ const path = sanitizeWorkspacePath(row.cwd);
+ const name = sanitizeWorkspaceName(row.name, path);
+ return {
+ id: row.id,
+ projectId: row.projectId,
+ name,
+ path,
+ isPrimary: row.isPrimary,
+ createdAt: row.createdAt.toISOString(),
+ updatedAt: row.updatedAt.toISOString(),
+ };
+ },
+
+ async getWorkspaceForIssue(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const issue = await issues.getById(params.issueId);
+ if (!inCompany(issue, companyId)) return null;
+ const projectId = (issue as Record<string, unknown>).projectId as string | null;
+ if (!projectId) return null;
+ const project = await projects.getById(projectId);
+ if (!inCompany(project, companyId)) return null;
+ const row = project.primaryWorkspace;
+ if (!row) return null;
+ const path = sanitizeWorkspacePath(row.cwd);
+ const name = sanitizeWorkspaceName(row.name, path);
+ return {
+ id: row.id,
+ projectId: row.projectId,
+ name,
+ path,
+ isPrimary: row.isPrimary,
+ createdAt: row.createdAt.toISOString(),
+ updatedAt: row.updatedAt.toISOString(),
+ };
+ },
+ },
+
+ issues: {
+ async list(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ return (await issues.list(companyId, params as any)) as Issue[];
+ },
+ async get(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const issue = await issues.getById(params.issueId);
+ return (inCompany(issue, companyId) ? issue : null) as Issue | null;
+ },
+ async create(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ return (await issues.create(companyId, params as any)) as Issue;
+ },
+ async update(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ requireInCompany("Issue", await issues.getById(params.issueId), companyId);
+ return (await issues.update(params.issueId, params.patch as any)) as Issue;
+ },
+ async listComments(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ if (!inCompany(await issues.getById(params.issueId), companyId)) return [];
+ return (await issues.listComments(params.issueId)) as IssueComment[];
+ },
+ async createComment(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ requireInCompany("Issue", await issues.getById(params.issueId), companyId);
+ return (await issues.addComment(
+ params.issueId,
+ params.body,
+ {},
+ )) as IssueComment;
+ },
+ },
+
+ agents: {
+ async list(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const rows = await agents.list(companyId);
+ return rows.filter((agent) => !params.status || agent.status === params.status) as Agent[];
+ },
+ async get(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const agent = await agents.getById(params.agentId);
+ return (inCompany(agent, companyId) ? agent : null) as Agent | null;
+ },
+ async pause(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const agent = await agents.getById(params.agentId);
+ requireInCompany("Agent", agent, companyId);
+ return (await agents.pause(params.agentId)) as Agent;
+ },
+ async resume(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const agent = await agents.getById(params.agentId);
+ requireInCompany("Agent", agent, companyId);
+ return (await agents.resume(params.agentId)) as Agent;
+ },
+ async invoke(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const agent = await agents.getById(params.agentId);
+ requireInCompany("Agent", agent, companyId);
+ const run = await heartbeat.wakeup(params.agentId, {
+ source: "automation",
+ triggerDetail: "system",
+ reason: params.reason ?? null,
+ payload: { prompt: params.prompt },
+ requestedByActorType: "system",
+ requestedByActorId: pluginId,
+ });
+ if (!run) throw new Error("Agent wakeup was skipped by heartbeat policy");
+ return { runId: run.id };
+ },
+ },
+
+ goals: {
+ async list(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const rows = await goals.list(companyId);
+ return rows.filter((goal) =>
+ (!params.level || goal.level === params.level) &&
+ (!params.status || goal.status === params.status),
+ ) as Goal[];
+ },
+ async get(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const goal = await goals.getById(params.goalId);
+ return (inCompany(goal, companyId) ? goal : null) as Goal | null;
+ },
+ async create(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ return (await goals.create(companyId, {
+ title: params.title,
+ description: params.description,
+ level: params.level as any,
+ status: params.status as any,
+ parentId: params.parentId,
+ ownerAgentId: params.ownerAgentId,
+ })) as Goal;
+ },
+ async update(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ requireInCompany("Goal", await goals.getById(params.goalId), companyId);
+ return (await goals.update(params.goalId, params.patch as any)) as Goal;
+ },
+ },
+
+ agentSessions: {
+ async create(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const agent = await agents.getById(params.agentId);
+ requireInCompany("Agent", agent, companyId);
+ const taskKey = params.taskKey ?? `plugin:${pluginKey}:session:${randomUUID()}`;
+
+ const row = await db
+ .insert(agentTaskSessionsTable)
+ .values({
+ companyId,
+ agentId: params.agentId,
+ adapterType: agent!.adapterType,
+ taskKey,
+ sessionParamsJson: null,
+ sessionDisplayId: null,
+ lastRunId: null,
+ lastError: null,
+ })
+ .returning()
+ .then((rows) => rows[0]);
+
+ return {
+ sessionId: row!.id,
+ agentId: params.agentId,
+ companyId,
+ status: "active" as const,
+ createdAt: row!.createdAt.toISOString(),
+ };
+ },
+
+ async list(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const rows = await db
+ .select()
+ .from(agentTaskSessionsTable)
+ .where(
+ and(
+ eq(agentTaskSessionsTable.agentId, params.agentId),
+ eq(agentTaskSessionsTable.companyId, companyId),
+ like(agentTaskSessionsTable.taskKey, `plugin:${pluginKey}:session:%`),
+ ),
+ )
+ .orderBy(desc(agentTaskSessionsTable.createdAt));
+
+ return rows.map((row) => ({
+ sessionId: row.id,
+ agentId: row.agentId,
+ companyId: row.companyId,
+ status: "active" as const,
+ createdAt: row.createdAt.toISOString(),
+ }));
+ },
+
+ async sendMessage(params) {
+ if (disposed) {
+ throw new Error("Host services have been disposed");
+ }
+
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+
+ // Verify session exists and belongs to this plugin
+ const session = await db
+ .select()
+ .from(agentTaskSessionsTable)
+ .where(
+ and(
+ eq(agentTaskSessionsTable.id, params.sessionId),
+ eq(agentTaskSessionsTable.companyId, companyId),
+ like(agentTaskSessionsTable.taskKey, `plugin:${pluginKey}:session:%`),
+ ),
+ )
+ .then((rows) => rows[0] ?? null);
+ if (!session) throw new Error(`Session not found: ${params.sessionId}`);
+
+ const run = await heartbeat.wakeup(session.agentId, {
+ source: "automation",
+ triggerDetail: "system",
+ reason: params.reason ?? null,
+ payload: { prompt: params.prompt },
+ contextSnapshot: {
+ taskKey: session.taskKey,
+ wakeSource: "automation",
+ wakeTriggerDetail: "system",
+ },
+ requestedByActorType: "system",
+ requestedByActorId: pluginId,
+ });
+ if (!run) throw new Error("Agent wakeup was skipped by heartbeat policy");
+
+ // Subscribe to live events and forward to the plugin worker as notifications.
+ // Track the subscription so it can be cleaned up on dispose() if the run
+ // never reaches a terminal status (hang, crash, network partition).
+ if (notifyWorker) {
+ const TERMINAL_STATUSES = new Set(["succeeded", "failed", "cancelled", "timed_out"]);
+
+ const cleanup = () => {
+ unsubscribe();
+ clearTimeout(timeoutTimer);
+ activeSubscriptions.delete(entry);
+ };
+
+ const unsubscribe = subscribeCompanyLiveEvents(companyId, (event) => {
+ const payload = event.payload as Record<string, unknown> | undefined;
+ if (!payload || payload.runId !== run.id) return;
+
+ if (event.type === "heartbeat.run.log" || event.type === "heartbeat.run.event") {
+ notifyWorker("agents.sessions.event", {
+ sessionId: params.sessionId,
+ runId: run.id,
+ seq: (payload.seq as number) ?? 0,
+ eventType: "chunk",
+ stream: (payload.stream as string) ?? null,
+ message: (payload.chunk as string) ?? (payload.message as string) ?? null,
+ payload: payload,
+ });
+ } else if (event.type === "heartbeat.run.status") {
+ const status = payload.status as string;
+ if (TERMINAL_STATUSES.has(status)) {
+ notifyWorker("agents.sessions.event", {
+ sessionId: params.sessionId,
+ runId: run.id,
+ seq: 0,
+ eventType: status === "succeeded" ? "done" : "error",
+ stream: "system",
+ message: status === "succeeded" ? "Run completed" : `Run ${status}`,
+ payload: payload,
+ });
+ cleanup();
+ } else {
+ notifyWorker("agents.sessions.event", {
+ sessionId: params.sessionId,
+ runId: run.id,
+ seq: 0,
+ eventType: "status",
+ stream: "system",
+ message: `Run status: ${status}`,
+ payload: payload,
+ });
+ }
+ }
+ });
+
+ // Safety-net timeout: if the run never reaches a terminal status,
+ // force-cleanup the subscription to prevent unbounded leaks.
+ const timeoutTimer = setTimeout(() => {
+ logger.warn(
+ { pluginId, pluginKey, runId: run.id },
+ "session event subscription timed out — forcing cleanup",
+ );
+ cleanup();
+ }, SESSION_EVENT_SUBSCRIPTION_TIMEOUT_MS);
+
+ const entry = { unsubscribe, timer: timeoutTimer };
+ activeSubscriptions.add(entry);
+ }
+
+ return { runId: run.id };
+ },
+
+ async close(params) {
+ const companyId = ensureCompanyId(params.companyId);
+ await ensurePluginAvailableForCompany(companyId);
+ const deleted = await db
+ .delete(agentTaskSessionsTable)
+ .where(
+ and(
+ eq(agentTaskSessionsTable.id, params.sessionId),
+ eq(agentTaskSessionsTable.companyId, companyId),
+ like(agentTaskSessionsTable.taskKey, `plugin:${pluginKey}:session:%`),
+ ),
+ )
+ .returning()
+ .then((rows) => rows.length);
+ if (deleted === 0) throw new Error(`Session not found: ${params.sessionId}`);
+ },
+ },
+
+ /**
+ * Clean up all active session event subscriptions and flush any buffered
+ * log entries. Must be called when the plugin worker is stopped, crashed,
+ * or unloaded to prevent leaked listeners and lost log entries.
+ */
+ dispose() {
+ disposed = true;
+
+ // Snapshot to avoid iterator invalidation from concurrent sendMessage() calls
+ const snapshot = Array.from(activeSubscriptions);
+ activeSubscriptions.clear();
+
+ for (const entry of snapshot) {
+ clearTimeout(entry.timer);
+ entry.unsubscribe();
+ }
+
+ // Flush any buffered log entries synchronously-as-possible on dispose.
+ flushPluginLogBuffer().catch((err) => {
+ console.error("[plugin-host-services] dispose() log flush failed:", err);
+ });
+ },
+ };
+}
diff --git a/server/src/services/plugin-job-coordinator.ts b/server/src/services/plugin-job-coordinator.ts
new file mode 100644
index 0000000000..bb0df0836e
--- /dev/null
+++ b/server/src/services/plugin-job-coordinator.ts
@@ -0,0 +1,260 @@
+/**
+ * PluginJobCoordinator — bridges the plugin lifecycle manager with the
+ * job scheduler and job store.
+ *
+ * This service listens to lifecycle events and performs the corresponding
+ * scheduler and job store operations:
+ *
+ * - **plugin.loaded** → sync job declarations from manifest, then register
+ * the plugin with the scheduler (computes `nextRunAt` for active jobs).
+ *
+ * - **plugin.disabled / plugin.unloaded** → unregister the plugin from the
+ * scheduler (cancels in-flight runs, clears tracking state).
+ *
+ * ## Why a separate coordinator?
+ *
+ * The lifecycle manager, scheduler, and job store are independent services
+ * with clean single-responsibility boundaries. The coordinator provides
+ * the "glue" between them without adding coupling. This pattern is used
+ * throughout Paperclip (e.g. heartbeat service coordinates timers + runs).
+ *
+ * @see PLUGIN_SPEC.md §17 — Scheduled Jobs
+ * @see ./plugin-job-scheduler.ts — Scheduler service
+ * @see ./plugin-job-store.ts — Persistence layer
+ * @see ./plugin-lifecycle.ts — Plugin state machine
+ */
+
+import type { PluginLifecycleManager } from "./plugin-lifecycle.js";
+import type { PluginJobScheduler } from "./plugin-job-scheduler.js";
+import type { PluginJobStore } from "./plugin-job-store.js";
+import { pluginRegistryService } from "./plugin-registry.js";
+import type { Db } from "@paperclipai/db";
+import { logger } from "../middleware/logger.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for creating a PluginJobCoordinator.
+ */
+export interface PluginJobCoordinatorOptions {
+ /** Drizzle database instance. */
+ db: Db;
+ /** The plugin lifecycle manager to listen to. */
+ lifecycle: PluginLifecycleManager;
+ /** The job scheduler to register/unregister plugins with. */
+ scheduler: PluginJobScheduler;
+ /** The job store for syncing declarations. */
+ jobStore: PluginJobStore;
+}
+
+/**
+ * The public interface of the job coordinator.
+ */
+export interface PluginJobCoordinator {
+ /**
+ * Start listening to lifecycle events.
+ *
+ * This wires up the `plugin.loaded`, `plugin.disabled`, and
+ * `plugin.unloaded` event handlers.
+ */
+ start(): void;
+
+ /**
+ * Stop listening to lifecycle events.
+ *
+ * Removes all event subscriptions added by `start()`.
+ */
+ stop(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a PluginJobCoordinator.
+ *
+ * @example
+ * ```ts
+ * const coordinator = createPluginJobCoordinator({
+ * db,
+ * lifecycle,
+ * scheduler,
+ * jobStore,
+ * });
+ *
+ * // Start listening to lifecycle events
+ * coordinator.start();
+ *
+ * // On server shutdown
+ * coordinator.stop();
+ * ```
+ */
+export function createPluginJobCoordinator(
+ options: PluginJobCoordinatorOptions,
+): PluginJobCoordinator {
+ const { db, lifecycle, scheduler, jobStore } = options;
+ const log = logger.child({ service: "plugin-job-coordinator" });
+ const registry = pluginRegistryService(db);
+
+ // -----------------------------------------------------------------------
+ // Event handlers
+ // -----------------------------------------------------------------------
+
+ /**
+ * When a plugin is loaded (transitions to `ready`):
+ * 1. Look up the manifest from the registry
+ * 2. Sync job declarations from the manifest into the DB
+ * 3. Register the plugin with the scheduler (computes nextRunAt)
+ */
+ async function onPluginLoaded(payload: { pluginId: string; pluginKey: string }): Promise<void> {
+ const { pluginId, pluginKey } = payload;
+ log.info({ pluginId, pluginKey }, "plugin loaded — syncing jobs and registering with scheduler");
+
+ try {
+ // Get the manifest from the registry
+ const plugin = await registry.getById(pluginId);
+ if (!plugin?.manifestJson) {
+ log.warn({ pluginId, pluginKey }, "plugin loaded but no manifest found — skipping job sync");
+ return;
+ }
+
+ // Sync job declarations from the manifest
+ const manifest = plugin.manifestJson;
+ const jobDeclarations = manifest.jobs ?? [];
+
+ if (jobDeclarations.length > 0) {
+ log.info(
+ { pluginId, pluginKey, jobCount: jobDeclarations.length },
+ "syncing job declarations from manifest",
+ );
+ await jobStore.syncJobDeclarations(pluginId, jobDeclarations);
+ }
+
+ // Register with the scheduler (computes nextRunAt for active jobs)
+ await scheduler.registerPlugin(pluginId);
+ } catch (err) {
+ log.error(
+ {
+ pluginId,
+ pluginKey,
+ err: err instanceof Error ? err.message : String(err),
+ },
+ "failed to sync jobs or register plugin with scheduler",
+ );
+ }
+ }
+
+ /**
+ * When a plugin is disabled (transitions to `error` with "disabled by
+ * operator" or genuine error): unregister from the scheduler.
+ */
+ async function onPluginDisabled(payload: {
+ pluginId: string;
+ pluginKey: string;
+ reason?: string;
+ }): Promise<void> {
+ const { pluginId, pluginKey, reason } = payload;
+ log.info(
+ { pluginId, pluginKey, reason },
+ "plugin disabled — unregistering from scheduler",
+ );
+
+ try {
+ await scheduler.unregisterPlugin(pluginId);
+ } catch (err) {
+ log.error(
+ {
+ pluginId,
+ pluginKey,
+ err: err instanceof Error ? err.message : String(err),
+ },
+ "failed to unregister plugin from scheduler",
+ );
+ }
+ }
+
+ /**
+ * When a plugin is unloaded (uninstalled): unregister from the scheduler.
+ */
+ async function onPluginUnloaded(payload: {
+ pluginId: string;
+ pluginKey: string;
+ removeData: boolean;
+ }): Promise<void> {
+ const { pluginId, pluginKey, removeData } = payload;
+ log.info(
+ { pluginId, pluginKey, removeData },
+ "plugin unloaded — unregistering from scheduler",
+ );
+
+ try {
+ await scheduler.unregisterPlugin(pluginId);
+
+ // If data is being purged, also delete all job definitions and runs
+ if (removeData) {
+ log.info({ pluginId, pluginKey }, "purging job data for uninstalled plugin");
+ await jobStore.deleteAllJobs(pluginId);
+ }
+ } catch (err) {
+ log.error(
+ {
+ pluginId,
+ pluginKey,
+ err: err instanceof Error ? err.message : String(err),
+ },
+ "failed to unregister plugin from scheduler during unload",
+ );
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ // State
+ // -----------------------------------------------------------------------
+
+ let attached = false;
+
+ // We need stable references for on/off since the lifecycle manager
+ // uses them for matching. We wrap the async handlers in sync wrappers
+ // that fire-and-forget (swallowing unhandled rejections via the try/catch
+ // inside each handler).
+ const boundOnLoaded = (payload: { pluginId: string; pluginKey: string }) => {
+ void onPluginLoaded(payload);
+ };
+ const boundOnDisabled = (payload: { pluginId: string; pluginKey: string; reason?: string }) => {
+ void onPluginDisabled(payload);
+ };
+ const boundOnUnloaded = (payload: { pluginId: string; pluginKey: string; removeData: boolean }) => {
+ void onPluginUnloaded(payload);
+ };
+
+ // -----------------------------------------------------------------------
+ // Public API
+ // -----------------------------------------------------------------------
+
+ return {
+ start(): void {
+ if (attached) return;
+ attached = true;
+
+ lifecycle.on("plugin.loaded", boundOnLoaded);
+ lifecycle.on("plugin.disabled", boundOnDisabled);
+ lifecycle.on("plugin.unloaded", boundOnUnloaded);
+
+ log.info("plugin job coordinator started — listening to lifecycle events");
+ },
+
+ stop(): void {
+ if (!attached) return;
+ attached = false;
+
+ lifecycle.off("plugin.loaded", boundOnLoaded);
+ lifecycle.off("plugin.disabled", boundOnDisabled);
+ lifecycle.off("plugin.unloaded", boundOnUnloaded);
+
+ log.info("plugin job coordinator stopped");
+ },
+ };
+}
diff --git a/server/src/services/plugin-job-scheduler.ts b/server/src/services/plugin-job-scheduler.ts
new file mode 100644
index 0000000000..09a6b8782b
--- /dev/null
+++ b/server/src/services/plugin-job-scheduler.ts
@@ -0,0 +1,752 @@
+/**
+ * PluginJobScheduler — tick-based scheduler for plugin scheduled jobs.
+ *
+ * The scheduler is the central coordinator for all plugin cron jobs. It
+ * periodically ticks (default every 30 seconds), queries the `plugin_jobs`
+ * table for jobs whose `nextRunAt` has passed, dispatches `runJob` RPC calls
+ * to the appropriate worker processes, records each execution in the
+ * `plugin_job_runs` table, and advances the scheduling pointer.
+ *
+ * ## Responsibilities
+ *
+ * 1. **Tick loop** — A `setInterval`-based loop fires every `tickIntervalMs`
+ * (default 30s). Each tick scans for due jobs and dispatches them.
+ *
+ * 2. **Cron parsing & next-run calculation** — Uses the lightweight built-in
+ * cron parser ({@link parseCron}, {@link nextCronTick}) to compute the
+ * `nextRunAt` timestamp after each run or when a new job is registered.
+ *
+ * 3. **Overlap prevention** — Before dispatching a job, the scheduler checks
+ * for an existing `running` run for the same job. If one exists, the job
+ * is skipped for that tick.
+ *
+ * 4. **Job run recording** — Every execution creates a `plugin_job_runs` row:
+ * `queued` → `running` → `succeeded` | `failed`. Duration and error are
+ * captured.
+ *
+ * 5. **Lifecycle integration** — The scheduler exposes `registerPlugin()` and
+ * `unregisterPlugin()` so the host lifecycle manager can wire up job
+ * scheduling when plugins start/stop. On registration, the scheduler
+ * computes `nextRunAt` for all active jobs that don't already have one.
+ *
+ * @see PLUGIN_SPEC.md §17 — Scheduled Jobs
+ * @see ./plugin-job-store.ts — Persistence layer
+ * @see ./cron.ts — Cron parsing utilities
+ */
+
+import { and, eq, lte, or } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import { pluginJobs, pluginJobRuns } from "@paperclipai/db";
+import type { PluginJobStore } from "./plugin-job-store.js";
+import type { PluginWorkerManager } from "./plugin-worker-manager.js";
+import { parseCron, nextCronTick, validateCron } from "./cron.js";
+import { logger } from "../middleware/logger.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default interval between scheduler ticks (30 seconds). */
+const DEFAULT_TICK_INTERVAL_MS = 30_000;
+
+/** Default timeout for a runJob RPC call (5 minutes). */
+const DEFAULT_JOB_TIMEOUT_MS = 5 * 60 * 1_000;
+
+/** Maximum number of concurrent job executions across all plugins. */
+const DEFAULT_MAX_CONCURRENT_JOBS = 10;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for creating a PluginJobScheduler.
+ */
+export interface PluginJobSchedulerOptions {
+ /** Drizzle database instance. */
+ db: Db;
+ /** Persistence layer for jobs and runs. */
+ jobStore: PluginJobStore;
+ /** Worker process manager for RPC calls. */
+ workerManager: PluginWorkerManager;
+ /** Interval between scheduler ticks in ms (default: 30s). */
+ tickIntervalMs?: number;
+ /** Timeout for individual job RPC calls in ms (default: 5min). */
+ jobTimeoutMs?: number;
+ /** Maximum number of concurrent job executions (default: 10). */
+ maxConcurrentJobs?: number;
+}
+
+/**
+ * Result of a manual job trigger.
+ */
+export interface TriggerJobResult {
+ /** The created run ID. */
+ runId: string;
+ /** The job ID that was triggered. */
+ jobId: string;
+}
+
+/**
+ * Diagnostic information about the scheduler.
+ */
+export interface SchedulerDiagnostics {
+ /** Whether the tick loop is running. */
+ running: boolean;
+ /** Number of jobs currently executing. */
+ activeJobCount: number;
+ /** Set of job IDs currently in-flight. */
+ activeJobIds: string[];
+ /** Total number of ticks executed since start. */
+ tickCount: number;
+ /** Timestamp of the last tick (ISO 8601). */
+ lastTickAt: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Scheduler
+// ---------------------------------------------------------------------------
+
+/**
+ * The public interface of the job scheduler.
+ */
+export interface PluginJobScheduler {
+ /**
+ * Start the scheduler tick loop.
+ *
+ * Safe to call multiple times — subsequent calls are no-ops.
+ */
+ start(): void;
+
+ /**
+ * Stop the scheduler tick loop.
+ *
+ * In-flight job runs are NOT cancelled — they are allowed to finish
+ * naturally. The tick loop simply stops firing.
+ */
+ stop(): void;
+
+ /**
+ * Register a plugin with the scheduler.
+ *
+ * Computes `nextRunAt` for all active jobs that are missing it. This is
+ * typically called after a plugin's worker process starts and
+ * `syncJobDeclarations()` has been called.
+ *
+ * @param pluginId - UUID of the plugin
+ */
+ registerPlugin(pluginId: string): Promise<void>;
+
+ /**
+ * Unregister a plugin from the scheduler.
+ *
+ * Cancels any in-flight runs for the plugin and removes tracking state.
+ *
+ * @param pluginId - UUID of the plugin
+ */
+ unregisterPlugin(pluginId: string): Promise<void>;
+
+ /**
+ * Manually trigger a specific job (outside of the cron schedule).
+ *
+ * Creates a run with `trigger: "manual"` and dispatches immediately,
+ * respecting the overlap prevention check.
+ *
+ * @param jobId - UUID of the job to trigger
+ * @param trigger - What triggered this run (default: "manual")
+ * @returns The created run info
+ * @throws {Error} if the job is not found, not active, or already running
+ */
+ triggerJob(jobId: string, trigger?: "manual" | "retry"): Promise<TriggerJobResult>;
+
+ /**
+ * Run a single scheduler tick immediately (for testing).
+ *
+ * @internal
+ */
+ tick(): Promise<void>;
+
+ /**
+ * Get diagnostic information about the scheduler state.
+ */
+ diagnostics(): SchedulerDiagnostics;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new PluginJobScheduler.
+ *
+ * @example
+ * ```ts
+ * const scheduler = createPluginJobScheduler({
+ * db,
+ * jobStore,
+ * workerManager,
+ * });
+ *
+ * // Start the tick loop
+ * scheduler.start();
+ *
+ * // When a plugin comes online, register it
+ * await scheduler.registerPlugin(pluginId);
+ *
+ * // Manually trigger a job
+ * const { runId } = await scheduler.triggerJob(jobId);
+ *
+ * // On server shutdown
+ * scheduler.stop();
+ * ```
+ */
+export function createPluginJobScheduler(
+ options: PluginJobSchedulerOptions,
+): PluginJobScheduler {
+ const {
+ db,
+ jobStore,
+ workerManager,
+ tickIntervalMs = DEFAULT_TICK_INTERVAL_MS,
+ jobTimeoutMs = DEFAULT_JOB_TIMEOUT_MS,
+ maxConcurrentJobs = DEFAULT_MAX_CONCURRENT_JOBS,
+ } = options;
+
+ const log = logger.child({ service: "plugin-job-scheduler" });
+
+ // -----------------------------------------------------------------------
+ // State
+ // -----------------------------------------------------------------------
+
+ /** Timer handle for the tick loop. */
+ let tickTimer: ReturnType<typeof setInterval> | null = null;
+
+ /** Whether the scheduler is running. */
+ let running = false;
+
+ /** Set of job IDs currently being executed (for overlap prevention). */
+ const activeJobs = new Set<string>();
+
+ /** Total number of ticks since start. */
+ let tickCount = 0;
+
+ /** Timestamp of the last tick. */
+ let lastTickAt: Date | null = null;
+
+ /** Guard against concurrent tick execution. */
+ let tickInProgress = false;
+
+ // -----------------------------------------------------------------------
+ // Core: tick
+ // -----------------------------------------------------------------------
+
+ /**
+ * A single scheduler tick. Queries for due jobs and dispatches them.
+ */
+ async function tick(): Promise<void> {
+ // Prevent overlapping ticks (in case a tick takes longer than the interval)
+ if (tickInProgress) {
+ log.debug("skipping tick — previous tick still in progress");
+ return;
+ }
+
+ tickInProgress = true;
+ tickCount++;
+ lastTickAt = new Date();
+
+ try {
+ const now = new Date();
+
+ // Query for jobs whose nextRunAt has passed and are active.
+ // We include jobs with null nextRunAt since they may have just been
+ // registered and need their first run calculated.
+ const dueJobs = await db
+ .select()
+ .from(pluginJobs)
+ .where(
+ and(
+ eq(pluginJobs.status, "active"),
+ lte(pluginJobs.nextRunAt, now),
+ ),
+ );
+
+ if (dueJobs.length === 0) {
+ return;
+ }
+
+ log.debug({ count: dueJobs.length }, "found due jobs");
+
+ // Dispatch each due job (respecting concurrency limits)
+ const dispatches: Promise<void>[] = [];
+
+ for (const job of dueJobs) {
+ // Concurrency limit
+ if (activeJobs.size >= maxConcurrentJobs) {
+ log.warn(
+ { maxConcurrentJobs, activeJobCount: activeJobs.size },
+ "max concurrent jobs reached, deferring remaining jobs",
+ );
+ break;
+ }
+
+ // Overlap prevention: skip if this job is already running
+ if (activeJobs.has(job.id)) {
+ log.debug(
+ { jobId: job.id, jobKey: job.jobKey, pluginId: job.pluginId },
+ "skipping job — already running (overlap prevention)",
+ );
+ continue;
+ }
+
+ // Check if the worker is available
+ if (!workerManager.isRunning(job.pluginId)) {
+ log.debug(
+ { jobId: job.id, pluginId: job.pluginId },
+ "skipping job — worker not running",
+ );
+ continue;
+ }
+
+ // Validate cron expression before dispatching
+ if (!job.schedule) {
+ log.warn(
+ { jobId: job.id, jobKey: job.jobKey },
+ "skipping job — no schedule defined",
+ );
+ continue;
+ }
+
+ dispatches.push(dispatchJob(job));
+ }
+
+ if (dispatches.length > 0) {
+ await Promise.allSettled(dispatches);
+ }
+ } catch (err) {
+ log.error(
+ { err: err instanceof Error ? err.message : String(err) },
+ "scheduler tick error",
+ );
+ } finally {
+ tickInProgress = false;
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ // Core: dispatch a single job
+ // -----------------------------------------------------------------------
+
+ /**
+ * Dispatch a single job run — create the run record, call the worker,
+ * record the result, and advance the schedule pointer.
+ */
+ async function dispatchJob(
+ job: typeof pluginJobs.$inferSelect,
+ ): Promise<void> {
+ const { id: jobId, pluginId, jobKey, schedule } = job;
+ const jobLog = log.child({ jobId, pluginId, jobKey });
+
+ // Mark as active (overlap prevention)
+ activeJobs.add(jobId);
+
+ let runId: string | undefined;
+ const startedAt = Date.now();
+
+ try {
+ // 1. Create run record
+ const run = await jobStore.createRun({
+ jobId,
+ pluginId,
+ trigger: "schedule",
+ });
+ runId = run.id;
+
+ jobLog.info({ runId }, "dispatching scheduled job");
+
+ // 2. Mark run as running
+ await jobStore.markRunning(runId);
+
+ // 3. Call worker via RPC
+ await workerManager.call(
+ pluginId,
+ "runJob",
+ {
+ job: {
+ jobKey,
+ runId,
+ trigger: "schedule" as const,
+ scheduledAt: (job.nextRunAt ?? new Date()).toISOString(),
+ },
+ },
+ jobTimeoutMs,
+ );
+
+ // 4. Mark run as succeeded
+ const durationMs = Date.now() - startedAt;
+ await jobStore.completeRun(runId, {
+ status: "succeeded",
+ durationMs,
+ });
+
+ jobLog.info({ runId, durationMs }, "job completed successfully");
+ } catch (err) {
+ const durationMs = Date.now() - startedAt;
+ const errorMessage = err instanceof Error ? err.message : String(err);
+
+ jobLog.error(
+ { runId, durationMs, err: errorMessage },
+ "job execution failed",
+ );
+
+ // Record the failure
+ if (runId) {
+ try {
+ await jobStore.completeRun(runId, {
+ status: "failed",
+ error: errorMessage,
+ durationMs,
+ });
+ } catch (completeErr) {
+ jobLog.error(
+ {
+ runId,
+ err: completeErr instanceof Error ? completeErr.message : String(completeErr),
+ },
+ "failed to record job failure",
+ );
+ }
+ }
+ } finally {
+ // Remove from active set
+ activeJobs.delete(jobId);
+
+ // 5. Always advance the schedule pointer (even on failure)
+ try {
+ await advanceSchedulePointer(job);
+ } catch (err) {
+ jobLog.error(
+ { err: err instanceof Error ? err.message : String(err) },
+ "failed to advance schedule pointer",
+ );
+ }
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ // Core: manual trigger
+ // -----------------------------------------------------------------------
+
+ async function triggerJob(
+ jobId: string,
+ trigger: "manual" | "retry" = "manual",
+ ): Promise<TriggerJobResult> {
+ const job = await jobStore.getJobById(jobId);
+ if (!job) {
+ throw new Error(`Job not found: ${jobId}`);
+ }
+
+ if (job.status !== "active") {
+ throw new Error(
+ `Job "${job.jobKey}" is not active (status: ${job.status})`,
+ );
+ }
+
+ // Overlap prevention
+ if (activeJobs.has(jobId)) {
+ throw new Error(
+ `Job "${job.jobKey}" is already running — cannot trigger while in progress`,
+ );
+ }
+
+ // Also check DB for running runs (defensive — covers multi-instance)
+ const existingRuns = await db
+ .select()
+ .from(pluginJobRuns)
+ .where(
+ and(
+ eq(pluginJobRuns.jobId, jobId),
+ eq(pluginJobRuns.status, "running"),
+ ),
+ );
+
+ if (existingRuns.length > 0) {
+ throw new Error(
+ `Job "${job.jobKey}" already has a running execution — cannot trigger while in progress`,
+ );
+ }
+
+ // Check worker availability
+ if (!workerManager.isRunning(job.pluginId)) {
+ throw new Error(
+ `Worker for plugin "${job.pluginId}" is not running — cannot trigger job`,
+ );
+ }
+
+ // Create the run and dispatch (non-blocking)
+ const run = await jobStore.createRun({
+ jobId,
+ pluginId: job.pluginId,
+ trigger,
+ });
+
+ // Dispatch in background — don't block the caller
+ void dispatchManualRun(job, run.id, trigger);
+
+ return { runId: run.id, jobId };
+ }
+
+ /**
+ * Dispatch a manually triggered job run.
+ */
+ async function dispatchManualRun(
+ job: typeof pluginJobs.$inferSelect,
+ runId: string,
+ trigger: "manual" | "retry",
+ ): Promise<void> {
+ const { id: jobId, pluginId, jobKey } = job;
+ const jobLog = log.child({ jobId, pluginId, jobKey, runId, trigger });
+
+ activeJobs.add(jobId);
+ const startedAt = Date.now();
+
+ try {
+ await jobStore.markRunning(runId);
+
+ await workerManager.call(
+ pluginId,
+ "runJob",
+ {
+ job: {
+ jobKey,
+ runId,
+ trigger,
+ scheduledAt: new Date().toISOString(),
+ },
+ },
+ jobTimeoutMs,
+ );
+
+ const durationMs = Date.now() - startedAt;
+ await jobStore.completeRun(runId, {
+ status: "succeeded",
+ durationMs,
+ });
+
+ jobLog.info({ durationMs }, "manual job completed successfully");
+ } catch (err) {
+ const durationMs = Date.now() - startedAt;
+ const errorMessage = err instanceof Error ? err.message : String(err);
+ jobLog.error({ durationMs, err: errorMessage }, "manual job failed");
+
+ try {
+ await jobStore.completeRun(runId, {
+ status: "failed",
+ error: errorMessage,
+ durationMs,
+ });
+ } catch (completeErr) {
+ jobLog.error(
+ {
+ err: completeErr instanceof Error ? completeErr.message : String(completeErr),
+ },
+ "failed to record manual job failure",
+ );
+ }
+ } finally {
+ activeJobs.delete(jobId);
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ // Schedule pointer management
+ // -----------------------------------------------------------------------
+
+ /**
+ * Advance the `lastRunAt` and `nextRunAt` timestamps on a job after a run.
+ */
+ async function advanceSchedulePointer(
+ job: typeof pluginJobs.$inferSelect,
+ ): Promise<void> {
+ const now = new Date();
+ let nextRunAt: Date | null = null;
+
+ if (job.schedule) {
+ const validationError = validateCron(job.schedule);
+ if (validationError) {
+ log.warn(
+ { jobId: job.id, schedule: job.schedule, error: validationError },
+ "invalid cron schedule — cannot compute next run",
+ );
+ } else {
+ const cron = parseCron(job.schedule);
+ nextRunAt = nextCronTick(cron, now);
+ }
+ }
+
+ await jobStore.updateRunTimestamps(job.id, now, nextRunAt);
+ }
+
+ /**
+ * Ensure all active jobs for a plugin have a `nextRunAt` value.
+ * Called when a plugin is registered with the scheduler.
+ */
+ async function ensureNextRunTimestamps(pluginId: string): Promise<void> {
+ const jobs = await jobStore.listJobs(pluginId, "active");
+
+ for (const job of jobs) {
+ // Skip jobs that already have a valid nextRunAt in the future
+ if (job.nextRunAt && job.nextRunAt.getTime() > Date.now()) {
+ continue;
+ }
+
+ // Skip jobs without a schedule
+ if (!job.schedule) {
+ continue;
+ }
+
+ const validationError = validateCron(job.schedule);
+ if (validationError) {
+ log.warn(
+ { jobId: job.id, jobKey: job.jobKey, schedule: job.schedule, error: validationError },
+ "skipping job with invalid cron schedule",
+ );
+ continue;
+ }
+
+ const cron = parseCron(job.schedule);
+ const nextRunAt = nextCronTick(cron, new Date());
+
+ if (nextRunAt) {
+ await jobStore.updateRunTimestamps(
+ job.id,
+ job.lastRunAt ?? new Date(0),
+ nextRunAt,
+ );
+ log.debug(
+ { jobId: job.id, jobKey: job.jobKey, nextRunAt: nextRunAt.toISOString() },
+ "computed nextRunAt for job",
+ );
+ }
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ // Plugin registration
+ // -----------------------------------------------------------------------
+
+ async function registerPlugin(pluginId: string): Promise<void> {
+ log.info({ pluginId }, "registering plugin with job scheduler");
+ await ensureNextRunTimestamps(pluginId);
+ }
+
+ async function unregisterPlugin(pluginId: string): Promise<void> {
+ log.info({ pluginId }, "unregistering plugin from job scheduler");
+
+ // Cancel any in-flight run records for this plugin that are still
+ // queued or running. Active jobs in-memory will finish naturally.
+ try {
+ const runningRuns = await db
+ .select()
+ .from(pluginJobRuns)
+ .where(
+ and(
+ eq(pluginJobRuns.pluginId, pluginId),
+ or(
+ eq(pluginJobRuns.status, "running"),
+ eq(pluginJobRuns.status, "queued"),
+ ),
+ ),
+ );
+
+ for (const run of runningRuns) {
+ await jobStore.completeRun(run.id, {
+ status: "cancelled",
+ error: "Plugin unregistered",
+ durationMs: run.startedAt
+ ? Date.now() - run.startedAt.getTime()
+ : null,
+ });
+ }
+ } catch (err) {
+ log.error(
+ {
+ pluginId,
+ err: err instanceof Error ? err.message : String(err),
+ },
+ "error cancelling in-flight runs during unregister",
+ );
+ }
+
+ // Remove any active tracking for jobs owned by this plugin
+ const jobs = await jobStore.listJobs(pluginId);
+ for (const job of jobs) {
+ activeJobs.delete(job.id);
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ // Lifecycle: start / stop
+ // -----------------------------------------------------------------------
+
+ function start(): void {
+ if (running) {
+ log.debug("scheduler already running");
+ return;
+ }
+
+ running = true;
+ tickTimer = setInterval(() => {
+ void tick();
+ }, tickIntervalMs);
+
+ log.info(
+ { tickIntervalMs, maxConcurrentJobs },
+ "plugin job scheduler started",
+ );
+ }
+
+ function stop(): void {
+ // Always clear the timer defensively, even if `running` is already false,
+ // to prevent leaked interval timers.
+ if (tickTimer !== null) {
+ clearInterval(tickTimer);
+ tickTimer = null;
+ }
+
+ if (!running) return;
+ running = false;
+
+ log.info(
+ { activeJobCount: activeJobs.size },
+ "plugin job scheduler stopped",
+ );
+ }
+
+ // -----------------------------------------------------------------------
+ // Diagnostics
+ // -----------------------------------------------------------------------
+
+ function diagnostics(): SchedulerDiagnostics {
+ return {
+ running,
+ activeJobCount: activeJobs.size,
+ activeJobIds: [...activeJobs],
+ tickCount,
+ lastTickAt: lastTickAt?.toISOString() ?? null,
+ };
+ }
+
+ // -----------------------------------------------------------------------
+ // Public API
+ // -----------------------------------------------------------------------
+
+ return {
+ start,
+ stop,
+ registerPlugin,
+ unregisterPlugin,
+ triggerJob,
+ tick,
+ diagnostics,
+ };
+}
diff --git a/server/src/services/plugin-job-store.ts b/server/src/services/plugin-job-store.ts
new file mode 100644
index 0000000000..f5fdbce1a4
--- /dev/null
+++ b/server/src/services/plugin-job-store.ts
@@ -0,0 +1,465 @@
+/**
+ * Plugin Job Store — persistence layer for scheduled plugin jobs and their
+ * execution history.
+ *
+ * This service manages the `plugin_jobs` and `plugin_job_runs` tables. It is
+ * the server-side backing store for the `ctx.jobs` SDK surface exposed to
+ * plugin workers.
+ *
+ * ## Responsibilities
+ *
+ * 1. **Sync job declarations** — When a plugin is installed or started, the
+ * host calls `syncJobDeclarations()` to upsert the manifest's declared jobs
+ * into the `plugin_jobs` table. Jobs removed from the manifest are marked
+ * `paused` (not deleted) to preserve history.
+ *
+ * 2. **Job CRUD** — List, get, pause, and resume jobs for a given plugin.
+ *
+ * 3. **Run lifecycle** — Create job run records, update their status, and
+ * record results (duration, errors, logs).
+ *
+ * 4. **Next-run calculation** — After a run completes the host should call
+ * `updateNextRunAt()` with the next cron tick so the scheduler knows when
+ * to fire next.
+ *
+ * The capability check (`jobs.schedule`) is enforced upstream by the host
+ * client factory and manifest validator — this store trusts that the caller
+ * has already been authorised.
+ *
+ * @see PLUGIN_SPEC.md §17 — Scheduled Jobs
+ * @see PLUGIN_SPEC.md §21.3 — `plugin_jobs` / `plugin_job_runs` tables
+ */
+
+import { and, desc, eq } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import { plugins, pluginJobs, pluginJobRuns } from "@paperclipai/db";
+import type {
+ PluginJobDeclaration,
+ PluginJobRunStatus,
+ PluginJobRunTrigger,
+ PluginJobRecord,
+} from "@paperclipai/shared";
+import { notFound } from "../errors.js";
+
+/**
+ * The statuses used for job *definitions* in the `plugin_jobs` table.
+ * Aliased from `PluginJobRecord` to keep the store API aligned with
+ * the domain type (`"active" | "paused" | "failed"`).
+ */
+type JobDefinitionStatus = PluginJobRecord["status"];
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Input for creating a job run record.
+ */
+export interface CreateJobRunInput {
+ /** FK to the plugin_jobs row. */
+ jobId: string;
+ /** FK to the plugins row. */
+ pluginId: string;
+ /** What triggered this run. */
+ trigger: PluginJobRunTrigger;
+}
+
+/**
+ * Input for completing (or failing) a job run.
+ */
+export interface CompleteJobRunInput {
+ /** Final run status. */
+ status: PluginJobRunStatus;
+ /** Error message if the run failed. */
+ error?: string | null;
+ /** Run duration in milliseconds. */
+ durationMs?: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a PluginJobStore backed by the given Drizzle database instance.
+ *
+ * @example
+ * ```ts
+ * const jobStore = pluginJobStore(db);
+ *
+ * // On plugin install/start — sync declared jobs into the DB
+ * await jobStore.syncJobDeclarations(pluginId, manifest.jobs ?? []);
+ *
+ * // Before dispatching a runJob RPC — create a run record
+ * const run = await jobStore.createRun({ jobId, pluginId, trigger: "schedule" });
+ *
+ * // After the RPC completes — record the result
+ * await jobStore.completeRun(run.id, {
+ * status: "succeeded",
+ * durationMs: Date.now() - startedAt,
+ * });
+ * ```
+ */
+export function pluginJobStore(db: Db) {
+ // -----------------------------------------------------------------------
+ // Internal helpers
+ // -----------------------------------------------------------------------
+
+ async function assertPluginExists(pluginId: string): Promise<void> {
+ const rows = await db
+ .select({ id: plugins.id })
+ .from(plugins)
+ .where(eq(plugins.id, pluginId));
+ if (rows.length === 0) {
+ throw notFound(`Plugin not found: ${pluginId}`);
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ // Public API
+ // -----------------------------------------------------------------------
+
+ return {
+ // =====================================================================
+ // Job declarations (plugin_jobs)
+ // =====================================================================
+
+ /**
+ * Sync declared jobs from a plugin manifest into the `plugin_jobs` table.
+ *
+ * This is called at plugin install and on each worker startup so the DB
+ * always reflects the manifest's declared jobs:
+ *
+ * - **New jobs** are inserted with status `active`.
+ * - **Existing jobs** have their `schedule` updated if it changed.
+ * - **Removed jobs** (present in DB but absent from the manifest) are
+ * set to `paused` so their history is preserved.
+ *
+ * The unique constraint `(pluginId, jobKey)` is used for conflict
+ * resolution.
+ *
+ * @param pluginId - UUID of the owning plugin
+ * @param declarations - Job declarations from the plugin manifest
+ */
+ async syncJobDeclarations(
+ pluginId: string,
+ declarations: PluginJobDeclaration[],
+ ): Promise<void> {
+ await assertPluginExists(pluginId);
+
+ // Fetch existing jobs for this plugin
+ const existingJobs = await db
+ .select()
+ .from(pluginJobs)
+ .where(eq(pluginJobs.pluginId, pluginId));
+
+ const existingByKey = new Map(
+ existingJobs.map((j) => [j.jobKey, j]),
+ );
+
+ const declaredKeys = new Set<string>();
+
+ // Upsert each declared job
+ for (const decl of declarations) {
+ declaredKeys.add(decl.jobKey);
+
+ const existing = existingByKey.get(decl.jobKey);
+ const schedule = decl.schedule ?? "";
+
+ if (existing) {
+ // Update schedule if it changed; re-activate if it was paused
+ const updates: Record<string, unknown> = {
+ updatedAt: new Date(),
+ };
+ if (existing.schedule !== schedule) {
+ updates.schedule = schedule;
+ }
+ if (existing.status === "paused") {
+ updates.status = "active";
+ }
+
+ await db
+ .update(pluginJobs)
+ .set(updates)
+ .where(eq(pluginJobs.id, existing.id));
+ } else {
+ // Insert new job
+ await db.insert(pluginJobs).values({
+ pluginId,
+ jobKey: decl.jobKey,
+ schedule,
+ status: "active",
+ });
+ }
+ }
+
+ // Pause jobs that are no longer declared in the manifest
+ for (const existing of existingJobs) {
+ if (!declaredKeys.has(existing.jobKey) && existing.status !== "paused") {
+ await db
+ .update(pluginJobs)
+ .set({ status: "paused", updatedAt: new Date() })
+ .where(eq(pluginJobs.id, existing.id));
+ }
+ }
+ },
+
+ /**
+ * List all jobs for a plugin, optionally filtered by status.
+ *
+ * @param pluginId - UUID of the owning plugin
+ * @param status - Optional status filter
+ */
+ async listJobs(
+ pluginId: string,
+ status?: JobDefinitionStatus,
+ ): Promise<(typeof pluginJobs.$inferSelect)[]> {
+ const conditions = [eq(pluginJobs.pluginId, pluginId)];
+ if (status) {
+ conditions.push(eq(pluginJobs.status, status));
+ }
+ return db
+ .select()
+ .from(pluginJobs)
+ .where(and(...conditions));
+ },
+
+ /**
+ * Get a single job by its composite key `(pluginId, jobKey)`.
+ *
+ * @param pluginId - UUID of the owning plugin
+ * @param jobKey - Stable job identifier from the manifest
+ * @returns The job row, or `null` if not found
+ */
+ async getJobByKey(
+ pluginId: string,
+ jobKey: string,
+ ): Promise<(typeof pluginJobs.$inferSelect) | null> {
+ const rows = await db
+ .select()
+ .from(pluginJobs)
+ .where(
+ and(
+ eq(pluginJobs.pluginId, pluginId),
+ eq(pluginJobs.jobKey, jobKey),
+ ),
+ );
+ return rows[0] ?? null;
+ },
+
+ /**
+ * Get a single job by its primary key (UUID).
+ *
+ * @param jobId - UUID of the job row
+ * @returns The job row, or `null` if not found
+ */
+ async getJobById(
+ jobId: string,
+ ): Promise<(typeof pluginJobs.$inferSelect) | null> {
+ const rows = await db
+ .select()
+ .from(pluginJobs)
+ .where(eq(pluginJobs.id, jobId));
+ return rows[0] ?? null;
+ },
+
+ /**
+ * Fetch a single job by ID, scoped to a specific plugin.
+ *
+ * Returns `null` if the job does not exist or does not belong to the
+ * given plugin — callers should treat both cases as "not found".
+ */
+ async getJobByIdForPlugin(
+ pluginId: string,
+ jobId: string,
+ ): Promise<(typeof pluginJobs.$inferSelect) | null> {
+ const rows = await db
+ .select()
+ .from(pluginJobs)
+ .where(and(eq(pluginJobs.id, jobId), eq(pluginJobs.pluginId, pluginId)));
+ return rows[0] ?? null;
+ },
+
+ /**
+ * Update a job's status.
+ *
+ * @param jobId - UUID of the job row
+ * @param status - New status
+ */
+ async updateJobStatus(
+ jobId: string,
+ status: JobDefinitionStatus,
+ ): Promise<void> {
+ await db
+ .update(pluginJobs)
+ .set({ status, updatedAt: new Date() })
+ .where(eq(pluginJobs.id, jobId));
+ },
+
+ /**
+ * Update the `lastRunAt` and `nextRunAt` timestamps on a job.
+ *
+ * Called by the scheduler after a run completes to advance the
+ * scheduling pointer.
+ *
+ * @param jobId - UUID of the job row
+ * @param lastRunAt - When the last run started
+ * @param nextRunAt - When the next run should fire
+ */
+ async updateRunTimestamps(
+ jobId: string,
+ lastRunAt: Date,
+ nextRunAt: Date | null,
+ ): Promise<void> {
+ await db
+ .update(pluginJobs)
+ .set({
+ lastRunAt,
+ nextRunAt,
+ updatedAt: new Date(),
+ })
+ .where(eq(pluginJobs.id, jobId));
+ },
+
+ /**
+ * Delete all jobs (and cascaded runs) owned by a plugin.
+ *
+ * Called during plugin uninstall when `removeData = true`.
+ *
+ * @param pluginId - UUID of the owning plugin
+ */
+ async deleteAllJobs(pluginId: string): Promise<void> {
+ await db
+ .delete(pluginJobs)
+ .where(eq(pluginJobs.pluginId, pluginId));
+ },
+
+ // =====================================================================
+ // Job runs (plugin_job_runs)
+ // =====================================================================
+
+ /**
+ * Create a new job run record with status `queued`.
+ *
+ * The caller should create the run record *before* dispatching the
+ * `runJob` RPC to the worker, then update it to `running` once the
+ * worker begins execution.
+ *
+ * @param input - Job run input (jobId, pluginId, trigger)
+ * @returns The newly created run row
+ */
+ async createRun(
+ input: CreateJobRunInput,
+ ): Promise<typeof pluginJobRuns.$inferSelect> {
+ const rows = await db
+ .insert(pluginJobRuns)
+ .values({
+ jobId: input.jobId,
+ pluginId: input.pluginId,
+ trigger: input.trigger,
+ status: "queued",
+ })
+ .returning();
+
+ return rows[0]!;
+ },
+
+ /**
+ * Mark a run as `running` and set its `startedAt` timestamp.
+ *
+ * @param runId - UUID of the run row
+ */
+ async markRunning(runId: string): Promise<void> {
+ await db
+ .update(pluginJobRuns)
+ .set({
+ status: "running" as PluginJobRunStatus,
+ startedAt: new Date(),
+ })
+ .where(eq(pluginJobRuns.id, runId));
+ },
+
+ /**
+ * Complete a run — set its final status, error, duration, and
+ * `finishedAt` timestamp.
+ *
+ * @param runId - UUID of the run row
+ * @param input - Completion details
+ */
+ async completeRun(
+ runId: string,
+ input: CompleteJobRunInput,
+ ): Promise<void> {
+ await db
+ .update(pluginJobRuns)
+ .set({
+ status: input.status,
+ error: input.error ?? null,
+ durationMs: input.durationMs ?? null,
+ finishedAt: new Date(),
+ })
+ .where(eq(pluginJobRuns.id, runId));
+ },
+
+ /**
+ * Get a run by its primary key.
+ *
+ * @param runId - UUID of the run row
+ * @returns The run row, or `null` if not found
+ */
+ async getRunById(
+ runId: string,
+ ): Promise<(typeof pluginJobRuns.$inferSelect) | null> {
+ const rows = await db
+ .select()
+ .from(pluginJobRuns)
+ .where(eq(pluginJobRuns.id, runId));
+ return rows[0] ?? null;
+ },
+
+ /**
+ * List runs for a specific job, ordered by creation time descending.
+ *
+ * @param jobId - UUID of the job
+ * @param limit - Maximum number of rows to return (default: 50)
+ */
+ async listRunsByJob(
+ jobId: string,
+ limit = 50,
+ ): Promise<(typeof pluginJobRuns.$inferSelect)[]> {
+ return db
+ .select()
+ .from(pluginJobRuns)
+ .where(eq(pluginJobRuns.jobId, jobId))
+ .orderBy(desc(pluginJobRuns.createdAt))
+ .limit(limit);
+ },
+
+ /**
+ * List runs for a plugin, optionally filtered by status.
+ *
+ * @param pluginId - UUID of the owning plugin
+ * @param status - Optional status filter
+ * @param limit - Maximum number of rows to return (default: 50)
+ */
+ async listRunsByPlugin(
+ pluginId: string,
+ status?: PluginJobRunStatus,
+ limit = 50,
+ ): Promise<(typeof pluginJobRuns.$inferSelect)[]> {
+ const conditions = [eq(pluginJobRuns.pluginId, pluginId)];
+ if (status) {
+ conditions.push(eq(pluginJobRuns.status, status));
+ }
+ return db
+ .select()
+ .from(pluginJobRuns)
+ .where(and(...conditions))
+ .orderBy(desc(pluginJobRuns.createdAt))
+ .limit(limit);
+ },
+ };
+}
+
+/** Type alias for the return value of `pluginJobStore()`. */
+export type PluginJobStore = ReturnType<typeof pluginJobStore>;
diff --git a/server/src/services/plugin-lifecycle.ts b/server/src/services/plugin-lifecycle.ts
new file mode 100644
index 0000000000..d3e9367785
--- /dev/null
+++ b/server/src/services/plugin-lifecycle.ts
@@ -0,0 +1,807 @@
+/**
+ * PluginLifecycleManager — state-machine controller for plugin status
+ * transitions and worker process coordination.
+ *
+ * Each plugin moves through a well-defined state machine:
+ *
+ * ```
+ * installed ──→ ready ──→ disabled
+ * │ │ │
+ * │ ├──→ error│
+ * │ ↓ │
+ * │ upgrade_pending │
+ * │ │ │
+ * ↓ ↓ ↓
+ * uninstalled
+ * ```
+ *
+ * The lifecycle manager:
+ *
+ * 1. **Validates transitions** — Only transitions defined in
+ * `VALID_TRANSITIONS` are allowed; invalid transitions throw.
+ *
+ * 2. **Coordinates workers** — When a plugin moves to `ready`, its
+ * worker process is started. When it moves out of `ready`, the
+ * worker is stopped gracefully.
+ *
+ * 3. **Emits events** — `plugin.loaded`, `plugin.enabled`,
+ * `plugin.disabled`, `plugin.unloaded`, `plugin.status_changed`
+ * events are emitted so that other services (job coordinator,
+ * tool dispatcher, event bus) can react accordingly.
+ *
+ * 4. **Persists state** — Status changes are written to the database
+ * through the plugin registry service.
+ *
+ * @see PLUGIN_SPEC.md §12 — Process Model
+ * @see PLUGIN_SPEC.md §12.5 — Graceful Shutdown Policy
+ */
+import { EventEmitter } from "node:events";
+import type { Db } from "@paperclipai/db";
+import type {
+ PluginStatus,
+ PluginRecord,
+ PaperclipPluginManifestV1,
+} from "@paperclipai/shared";
+import { pluginRegistryService } from "./plugin-registry.js";
+import { pluginLoader, type PluginLoader } from "./plugin-loader.js";
+import type { PluginWorkerManager, WorkerStartOptions } from "./plugin-worker-manager.js";
+import { badRequest, notFound } from "../errors.js";
+import { logger } from "../middleware/logger.js";
+
+// ---------------------------------------------------------------------------
+// Lifecycle state machine
+// ---------------------------------------------------------------------------
+
+/**
+ * Valid state transitions for the plugin lifecycle.
+ *
+ * installed → ready (initial load succeeds)
+ * installed → error (initial load fails)
+ * installed → uninstalled (abort installation)
+ *
+ * ready → disabled (operator disables plugin)
+ * ready → error (runtime failure)
+ * ready → upgrade_pending (upgrade with new capabilities)
+ * ready → uninstalled (uninstall)
+ *
+ * disabled → ready (operator re-enables plugin)
+ * disabled → uninstalled (uninstall while disabled)
+ *
+ * error → ready (retry / recovery)
+ * error → uninstalled (give up and uninstall)
+ *
+ * upgrade_pending → ready (operator approves new capabilities)
+ * upgrade_pending → error (upgrade worker fails)
+ * upgrade_pending → uninstalled (reject upgrade and uninstall)
+ *
+ * uninstalled → installed (reinstall)
+ */
+const VALID_TRANSITIONS: Record<string, readonly PluginStatus[]> = {
+ installed: ["ready", "error", "uninstalled"],
+ ready: ["ready", "disabled", "error", "upgrade_pending", "uninstalled"],
+ disabled: ["ready", "uninstalled"],
+ error: ["ready", "uninstalled"],
+ upgrade_pending: ["ready", "error", "uninstalled"],
+ uninstalled: ["installed"], // reinstall
+};
+
+/**
+ * Check whether a transition from `from` → `to` is valid.
+ */
+function isValidTransition(from: PluginStatus, to: PluginStatus): boolean {
+ return VALID_TRANSITIONS[from]?.includes(to) ?? false;
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle events
+// ---------------------------------------------------------------------------
+
+/**
+ * Events emitted by the PluginLifecycleManager.
+ * Consumers can subscribe to these for routing-table updates, UI refresh
+ * notifications, and observability.
+ */
+export interface PluginLifecycleEvents {
+ /** Emitted after a plugin is loaded (installed → ready). */
+ "plugin.loaded": { pluginId: string; pluginKey: string };
+ /** Emitted after a plugin transitions to ready (enabled). */
+ "plugin.enabled": { pluginId: string; pluginKey: string };
+ /** Emitted after a plugin is disabled (ready → disabled). */
+ "plugin.disabled": { pluginId: string; pluginKey: string; reason?: string };
+ /** Emitted after a plugin is unloaded (any → uninstalled). */
+ "plugin.unloaded": { pluginId: string; pluginKey: string; removeData: boolean };
+ /** Emitted on any status change. */
+ "plugin.status_changed": {
+ pluginId: string;
+ pluginKey: string;
+ previousStatus: PluginStatus;
+ newStatus: PluginStatus;
+ };
+ /** Emitted when a plugin enters an error state. */
+ "plugin.error": { pluginId: string; pluginKey: string; error: string };
+ /** Emitted when a plugin enters upgrade_pending. */
+ "plugin.upgrade_pending": { pluginId: string; pluginKey: string };
+ /** Emitted when a plugin worker process has been started. */
+ "plugin.worker_started": { pluginId: string; pluginKey: string };
+ /** Emitted when a plugin worker process has been stopped. */
+ "plugin.worker_stopped": { pluginId: string; pluginKey: string };
+}
+
+type LifecycleEventName = keyof PluginLifecycleEvents;
+type LifecycleEventPayload<K extends LifecycleEventName> = PluginLifecycleEvents[K];
+
+// ---------------------------------------------------------------------------
+// PluginLifecycleManager
+// ---------------------------------------------------------------------------
+
+export interface PluginLifecycleManager {
+ /**
+ * Load a newly installed plugin – transitions `installed` → `ready`.
+ *
+ * This is called after the registry has persisted the initial install record.
+ * The caller should have already spawned the worker and performed health
+ * checks before calling this. If the worker fails, call `markError` instead.
+ */
+ load(pluginId: string): Promise<PluginRecord>;
+
+ /**
+ * Enable a plugin that is in `disabled`, `error`, or `upgrade_pending` state.
+ * Transitions → `ready`.
+ */
+ enable(pluginId: string): Promise<PluginRecord>;
+
+ /**
+ * Disable a running plugin.
+ * Transitions `ready` → `disabled`.
+ */
+ disable(pluginId: string, reason?: string): Promise<PluginRecord>;
+
+ /**
+ * Unload (uninstall) a plugin from any active state.
+ * Transitions → `uninstalled`.
+ *
+ * When `removeData` is true, the plugin row and cascaded config are
+ * hard-deleted. Otherwise a soft-delete sets status to `uninstalled`.
+ */
+ unload(pluginId: string, removeData?: boolean): Promise<PluginRecord | null>;
+
+ /**
+ * Mark a plugin as errored (e.g. worker crash, health-check failure).
+ * Transitions → `error`.
+ */
+ markError(pluginId: string, error: string): Promise<PluginRecord>;
+
+ /**
+ * Mark a plugin as requiring upgrade approval.
+ * Transitions `ready` → `upgrade_pending`.
+ */
+ markUpgradePending(pluginId: string): Promise<PluginRecord>;
+
+ /**
+ * Upgrade a plugin to a newer version.
+ * This is a placeholder that handles the lifecycle state transition.
+ * The actual package installation is handled by plugin-loader.
+ *
+ * If the upgrade adds new capabilities, transitions to `upgrade_pending`.
+ * Otherwise, transitions to `ready` directly.
+ */
+ upgrade(pluginId: string, version?: string): Promise<PluginRecord>;
+
+ /**
+ * Start the worker process for a plugin that is already in `ready` state.
+ *
+ * This is used by the server startup orchestration to start workers for
+ * plugins that were persisted as `ready`. It requires a `PluginWorkerManager`
+ * to have been provided at construction time.
+ *
+ * @param pluginId - The UUID of the plugin to start
+ * @param options - Worker start options (entrypoint path, config, etc.)
+ * @throws if no worker manager is configured or the plugin is not ready
+ */
+ startWorker(pluginId: string, options: WorkerStartOptions): Promise<void>;
+
+ /**
+ * Stop the worker process for a plugin without changing lifecycle state.
+ *
+ * This is used during server shutdown to gracefully stop all workers.
+ * It does not transition the plugin state — plugins remain in their
+ * current status so they can be restarted on next server boot.
+ *
+ * @param pluginId - The UUID of the plugin to stop
+ */
+ stopWorker(pluginId: string): Promise<void>;
+
+ /**
+ * Restart the worker process for a running plugin.
+ *
+ * Stops and re-starts the worker process. The plugin remains in `ready`
+ * state throughout. This is typically called after a config change.
+ *
+ * @param pluginId - The UUID of the plugin to restart
+ * @throws if no worker manager is configured or the plugin is not ready
+ */
+ restartWorker(pluginId: string): Promise<void>;
+
+ /**
+ * Get the current lifecycle state for a plugin.
+ */
+ getStatus(pluginId: string): Promise<PluginStatus | null>;
+
+ /**
+ * Check whether a transition is allowed from the plugin's current state.
+ */
+ canTransition(pluginId: string, to: PluginStatus): Promise<boolean>;
+
+ /**
+ * Subscribe to lifecycle events.
+ */
+ on<K extends LifecycleEventName>(
+ event: K,
+ listener: (payload: LifecycleEventPayload<K>) => void,
+ ): void;
+
+ /**
+ * Unsubscribe from lifecycle events.
+ */
+ off<K extends LifecycleEventName>(
+ event: K,
+ listener: (payload: LifecycleEventPayload<K>) => void,
+ ): void;
+
+ /**
+ * Subscribe to a lifecycle event once.
+ */
+ once<K extends LifecycleEventName>(
+ event: K,
+ listener: (payload: LifecycleEventPayload<K>) => void,
+ ): void;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for constructing a PluginLifecycleManager.
+ */
+export interface PluginLifecycleManagerOptions {
+ /** Plugin loader instance. Falls back to the default if omitted. */
+ loader?: PluginLoader;
+
+ /**
+ * Worker process manager. When provided, lifecycle transitions that bring
+ * a plugin online (load, enable, upgrade-to-ready) will start the worker
+ * process, and transitions that take a plugin offline (disable, unload,
+ * markError) will stop it.
+ *
+ * When omitted the lifecycle manager operates in state-only mode — the
+ * caller is responsible for managing worker processes externally.
+ */
+ workerManager?: PluginWorkerManager;
+}
+
+/**
+ * Create a PluginLifecycleManager.
+ *
+ * This service orchestrates plugin state transitions on top of the
+ * `pluginRegistryService` (which handles raw DB persistence). It enforces
+ * the lifecycle state machine, emits events for downstream consumers
+ * (routing tables, UI, observability), and manages worker processes via
+ * the `PluginWorkerManager` when one is provided.
+ *
+ * Usage:
+ * ```ts
+ * const lifecycle = pluginLifecycleManager(db, {
+ * workerManager: createPluginWorkerManager(),
+ * });
+ * lifecycle.on("plugin.enabled", ({ pluginId }) => { ... });
+ * await lifecycle.load(pluginId);
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §21.3 — `plugins.status` column
+ * @see PLUGIN_SPEC.md §12 — Process Model
+ */
+export function pluginLifecycleManager(
+ db: Db,
+ options?: PluginLoader | PluginLifecycleManagerOptions,
+): PluginLifecycleManager {
+ // Support the legacy signature: pluginLifecycleManager(db, loader)
+ // as well as the new options object form.
+ let loaderArg: PluginLoader | undefined;
+ let workerManager: PluginWorkerManager | undefined;
+
+ if (options && typeof options === "object" && "discoverAll" in options) {
+ // Legacy: second arg is a PluginLoader directly
+ loaderArg = options as PluginLoader;
+ } else if (options && typeof options === "object") {
+ const opts = options as PluginLifecycleManagerOptions;
+ loaderArg = opts.loader;
+ workerManager = opts.workerManager;
+ }
+
+ const registry = pluginRegistryService(db);
+ const pluginLoaderInstance = loaderArg ?? pluginLoader(db);
+ const emitter = new EventEmitter();
+ emitter.setMaxListeners(100); // plugins may have many listeners; 100 is a safe upper bound
+
+ const log = logger.child({ service: "plugin-lifecycle" });
+
+ // -----------------------------------------------------------------------
+ // Internal helpers
+ // -----------------------------------------------------------------------
+
+ async function requirePlugin(pluginId: string): Promise<PluginRecord> {
+ const plugin = await registry.getById(pluginId);
+ if (!plugin) throw notFound(`Plugin not found: ${pluginId}`);
+ return plugin as PluginRecord;
+ }
+
+ function assertTransition(plugin: PluginRecord, to: PluginStatus): void {
+ if (!isValidTransition(plugin.status, to)) {
+ throw badRequest(
+ `Invalid lifecycle transition: ${plugin.status} → ${to} for plugin ${plugin.pluginKey}`,
+ );
+ }
+ }
+
+ async function transition(
+ pluginId: string,
+ to: PluginStatus,
+ lastError: string | null = null,
+ existingPlugin?: PluginRecord,
+ ): Promise<PluginRecord> {
+ const plugin = existingPlugin ?? await requirePlugin(pluginId);
+ assertTransition(plugin, to);
+
+ const previousStatus = plugin.status;
+
+ const updated = await registry.updateStatus(pluginId, {
+ status: to,
+ lastError,
+ });
+
+ if (!updated) throw notFound(`Plugin not found after status update: ${pluginId}`);
+ const result = updated as PluginRecord;
+
+ log.info(
+ { pluginId, pluginKey: result.pluginKey, from: previousStatus, to },
+ `plugin lifecycle: ${previousStatus} → ${to}`,
+ );
+
+ // Emit the generic status_changed event
+ emitter.emit("plugin.status_changed", {
+ pluginId,
+ pluginKey: result.pluginKey,
+ previousStatus,
+ newStatus: to,
+ });
+
+ return result;
+ }
+
+ function emitDomain(
+ event: LifecycleEventName,
+ payload: PluginLifecycleEvents[LifecycleEventName],
+ ): void {
+ emitter.emit(event, payload);
+ }
+
+ // -----------------------------------------------------------------------
+ // Worker management helpers
+ // -----------------------------------------------------------------------
+
+ /**
+ * Stop the worker for a plugin if one is running.
+ * This is a best-effort operation — if no worker manager is configured
+ * or no worker is running, it silently succeeds.
+ */
+ async function stopWorkerIfRunning(
+ pluginId: string,
+ pluginKey: string,
+ ): Promise<void> {
+ if (!workerManager) return;
+ if (!workerManager.isRunning(pluginId) && !workerManager.getWorker(pluginId)) return;
+
+ try {
+ await workerManager.stopWorker(pluginId);
+ log.info({ pluginId, pluginKey }, "plugin lifecycle: worker stopped");
+ emitDomain("plugin.worker_stopped", { pluginId, pluginKey });
+ } catch (err) {
+ log.warn(
+ { pluginId, pluginKey, err: err instanceof Error ? err.message : String(err) },
+ "plugin lifecycle: failed to stop worker (best-effort)",
+ );
+ }
+ }
+
+ async function activateReadyPlugin(pluginId: string): Promise<void> {
+ const supportsRuntimeActivation =
+ typeof pluginLoaderInstance.hasRuntimeServices === "function"
+ && typeof pluginLoaderInstance.loadSingle === "function";
+ if (!supportsRuntimeActivation || !pluginLoaderInstance.hasRuntimeServices()) {
+ return;
+ }
+
+ const loadResult = await pluginLoaderInstance.loadSingle(pluginId);
+ if (!loadResult.success) {
+ throw new Error(
+ loadResult.error
+ ?? `Failed to activate plugin ${loadResult.plugin.pluginKey}`,
+ );
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ // Public API
+ // -----------------------------------------------------------------------
+
+ return {
+ // -- load -------------------------------------------------------------
+ /**
+ * load — Transitions a plugin to 'ready' status and starts its worker.
+ *
+ * This method is called after a plugin has been successfully installed and
+ * validated. It marks the plugin as ready in the database and immediately
+ * triggers the plugin loader to start the worker process.
+ *
+ * @param pluginId - The UUID of the plugin to load.
+ * @returns The updated plugin record.
+ */
+ async load(pluginId: string): Promise<PluginRecord> {
+ const result = await transition(pluginId, "ready");
+ await activateReadyPlugin(pluginId);
+
+ emitDomain("plugin.loaded", {
+ pluginId,
+ pluginKey: result.pluginKey,
+ });
+ emitDomain("plugin.enabled", {
+ pluginId,
+ pluginKey: result.pluginKey,
+ });
+ return result;
+ },
+
+ // -- enable -----------------------------------------------------------
+ /**
+ * enable — Re-enables a plugin that was previously in an error or upgrade state.
+ *
+ * Similar to load(), this method transitions the plugin to 'ready' and starts
+ * its worker, but it specifically targets plugins that are currently disabled.
+ *
+ * @param pluginId - The UUID of the plugin to enable.
+ * @returns The updated plugin record.
+ */
+ async enable(pluginId: string): Promise<PluginRecord> {
+ const plugin = await requirePlugin(pluginId);
+
+ // Only allow enabling from disabled, error, or upgrade_pending states
+ if (plugin.status !== "disabled" && plugin.status !== "error" && plugin.status !== "upgrade_pending") {
+ throw badRequest(
+ `Cannot enable plugin in status '${plugin.status}'. ` +
+ `Plugin must be in 'disabled', 'error', or 'upgrade_pending' status to be enabled.`,
+ );
+ }
+
+ const result = await transition(pluginId, "ready", null, plugin);
+ await activateReadyPlugin(pluginId);
+ emitDomain("plugin.enabled", {
+ pluginId,
+ pluginKey: result.pluginKey,
+ });
+ return result;
+ },
+
+ // -- disable ----------------------------------------------------------
+ async disable(pluginId: string, reason?: string): Promise<PluginRecord> {
+ const plugin = await requirePlugin(pluginId);
+
+ // Only allow disabling from ready state
+ if (plugin.status !== "ready") {
+ throw badRequest(
+ `Cannot disable plugin in status '${plugin.status}'. ` +
+ `Plugin must be in 'ready' status to be disabled.`,
+ );
+ }
+
+ // Stop the worker before transitioning state
+ await stopWorkerIfRunning(pluginId, plugin.pluginKey);
+
+ const result = await transition(pluginId, "disabled", reason ?? null, plugin);
+ emitDomain("plugin.disabled", {
+ pluginId,
+ pluginKey: result.pluginKey,
+ reason,
+ });
+ return result;
+ },
+
+ // -- unload -----------------------------------------------------------
+ async unload(
+ pluginId: string,
+ removeData = false,
+ ): Promise<PluginRecord | null> {
+ const plugin = await requirePlugin(pluginId);
+
+ // If already uninstalled and removeData, hard-delete
+ if (plugin.status === "uninstalled") {
+ if (removeData) {
+ const deleted = await registry.uninstall(pluginId, true);
+ log.info(
+ { pluginId, pluginKey: plugin.pluginKey },
+ "plugin lifecycle: hard-deleted already-uninstalled plugin",
+ );
+ emitDomain("plugin.unloaded", {
+ pluginId,
+ pluginKey: plugin.pluginKey,
+ removeData: true,
+ });
+ return deleted as PluginRecord | null;
+ }
+ throw badRequest(
+ `Plugin ${plugin.pluginKey} is already uninstalled. ` +
+ `Use removeData=true to permanently delete it.`,
+ );
+ }
+
+ // Stop the worker before uninstalling
+ await stopWorkerIfRunning(pluginId, plugin.pluginKey);
+
+ // Perform the uninstall via registry (handles soft/hard delete)
+ const result = await registry.uninstall(pluginId, removeData);
+
+ log.info(
+ { pluginId, pluginKey: plugin.pluginKey, removeData },
+ `plugin lifecycle: ${plugin.status} → uninstalled${removeData ? " (hard delete)" : ""}`,
+ );
+
+ emitter.emit("plugin.status_changed", {
+ pluginId,
+ pluginKey: plugin.pluginKey,
+ previousStatus: plugin.status,
+ newStatus: "uninstalled" as PluginStatus,
+ });
+
+ emitDomain("plugin.unloaded", {
+ pluginId,
+ pluginKey: plugin.pluginKey,
+ removeData,
+ });
+
+ return result as PluginRecord | null;
+ },
+
+ // -- markError --------------------------------------------------------
+ async markError(pluginId: string, error: string): Promise<PluginRecord> {
+ // Stop the worker — the plugin is in an error state and should not
+ // continue running. The worker manager's auto-restart is disabled
+ // because we are intentionally taking the plugin offline.
+ const plugin = await requirePlugin(pluginId);
+ await stopWorkerIfRunning(pluginId, plugin.pluginKey);
+
+ const result = await transition(pluginId, "error", error, plugin);
+ emitDomain("plugin.error", {
+ pluginId,
+ pluginKey: result.pluginKey,
+ error,
+ });
+ return result;
+ },
+
+ // -- markUpgradePending -----------------------------------------------
+ async markUpgradePending(pluginId: string): Promise<PluginRecord> {
+ // Stop the worker while waiting for operator approval of new capabilities
+ const plugin = await requirePlugin(pluginId);
+ await stopWorkerIfRunning(pluginId, plugin.pluginKey);
+
+ const result = await transition(pluginId, "upgrade_pending", null, plugin);
+ emitDomain("plugin.upgrade_pending", {
+ pluginId,
+ pluginKey: result.pluginKey,
+ });
+ return result;
+ },
+
+ // -- upgrade ----------------------------------------------------------
+ /**
+ * Upgrade a plugin to a newer version by performing a package update and
+ * managing the lifecycle state transition.
+ *
+ * Following PLUGIN_SPEC.md §25.3, the upgrade process:
+ * 1. Stops the current worker process (if running).
+ * 2. Fetches and validates the new plugin package via the `PluginLoader`.
+ * 3. Compares the capabilities declared in the new manifest against the old one.
+ * 4. If new capabilities are added, transitions the plugin to `upgrade_pending`
+ * to await operator approval (worker stays stopped).
+ * 5. If no new capabilities are added, transitions the plugin back to `ready`
+ * with the updated version and manifest metadata.
+ *
+ * @param pluginId - The UUID of the plugin to upgrade.
+ * @param version - Optional target version specifier.
+ * @returns The updated `PluginRecord`.
+ * @throws {BadRequest} If the plugin is not in a ready or upgrade_pending state.
+ */
+ async upgrade(pluginId: string, version?: string): Promise<PluginRecord> {
+ const plugin = await requirePlugin(pluginId);
+
+ // Can only upgrade plugins that are ready or already in upgrade_pending
+ if (plugin.status !== "ready" && plugin.status !== "upgrade_pending") {
+ throw badRequest(
+ `Cannot upgrade plugin in status '${plugin.status}'. ` +
+ `Plugin must be in 'ready' or 'upgrade_pending' status to be upgraded.`,
+ );
+ }
+
+ log.info(
+ { pluginId, pluginKey: plugin.pluginKey, targetVersion: version },
+ "plugin lifecycle: upgrade requested",
+ );
+
+ // Stop the current worker before upgrading on disk
+ await stopWorkerIfRunning(pluginId, plugin.pluginKey);
+
+ // 1. Download and validate new package via loader
+ const { oldManifest, newManifest, discovered } =
+ await pluginLoaderInstance.upgradePlugin(pluginId, { version });
+
+ log.info(
+ {
+ pluginId,
+ pluginKey: plugin.pluginKey,
+ oldVersion: oldManifest.version,
+ newVersion: newManifest.version,
+ },
+ "plugin lifecycle: package upgraded on disk",
+ );
+
+ // 2. Compare capabilities
+ const addedCaps = newManifest.capabilities.filter(
+ (cap) => !oldManifest.capabilities.includes(cap),
+ );
+
+ // 3. Transition state
+ if (addedCaps.length > 0) {
+ // New capabilities require operator approval — worker stays stopped
+ log.info(
+ { pluginId, pluginKey: plugin.pluginKey, addedCaps },
+ "plugin lifecycle: new capabilities detected, transitioning to upgrade_pending",
+ );
+ // Skip the inner stopWorkerIfRunning since we already stopped above
+ const result = await transition(pluginId, "upgrade_pending", null, plugin);
+ emitDomain("plugin.upgrade_pending", {
+ pluginId,
+ pluginKey: result.pluginKey,
+ });
+ return result;
+ } else {
+ const result = await transition(pluginId, "ready", null, {
+ ...plugin,
+ version: discovered.version,
+ manifestJson: newManifest,
+ } as PluginRecord);
+ await activateReadyPlugin(pluginId);
+
+ emitDomain("plugin.loaded", {
+ pluginId,
+ pluginKey: result.pluginKey,
+ });
+ emitDomain("plugin.enabled", {
+ pluginId,
+ pluginKey: result.pluginKey,
+ });
+
+ return result;
+ }
+ },
+
+ // -- startWorker ------------------------------------------------------
+ async startWorker(
+ pluginId: string,
+ options: WorkerStartOptions,
+ ): Promise<void> {
+ if (!workerManager) {
+ throw badRequest(
+ "Cannot start worker: no PluginWorkerManager is configured. " +
+ "Provide a workerManager option when constructing the lifecycle manager.",
+ );
+ }
+
+ const plugin = await requirePlugin(pluginId);
+ if (plugin.status !== "ready") {
+ throw badRequest(
+ `Cannot start worker for plugin in status '${plugin.status}'. ` +
+ `Plugin must be in 'ready' status.`,
+ );
+ }
+
+ log.info(
+ { pluginId, pluginKey: plugin.pluginKey },
+ "plugin lifecycle: starting worker",
+ );
+
+ await workerManager.startWorker(pluginId, options);
+ emitDomain("plugin.worker_started", {
+ pluginId,
+ pluginKey: plugin.pluginKey,
+ });
+
+ log.info(
+ { pluginId, pluginKey: plugin.pluginKey },
+ "plugin lifecycle: worker started",
+ );
+ },
+
+ // -- stopWorker -------------------------------------------------------
+ async stopWorker(pluginId: string): Promise<void> {
+ if (!workerManager) return; // No worker manager — nothing to stop
+
+ const plugin = await requirePlugin(pluginId);
+ await stopWorkerIfRunning(pluginId, plugin.pluginKey);
+ },
+
+ // -- restartWorker ----------------------------------------------------
+ async restartWorker(pluginId: string): Promise<void> {
+ if (!workerManager) {
+ throw badRequest(
+ "Cannot restart worker: no PluginWorkerManager is configured.",
+ );
+ }
+
+ const plugin = await requirePlugin(pluginId);
+ if (plugin.status !== "ready") {
+ throw badRequest(
+ `Cannot restart worker for plugin in status '${plugin.status}'. ` +
+ `Plugin must be in 'ready' status.`,
+ );
+ }
+
+ const handle = workerManager.getWorker(pluginId);
+ if (!handle) {
+ throw badRequest(
+ `Cannot restart worker for plugin "${plugin.pluginKey}": no worker is running.`,
+ );
+ }
+
+ log.info(
+ { pluginId, pluginKey: plugin.pluginKey },
+ "plugin lifecycle: restarting worker",
+ );
+
+ await handle.restart();
+
+ emitDomain("plugin.worker_stopped", { pluginId, pluginKey: plugin.pluginKey });
+ emitDomain("plugin.worker_started", { pluginId, pluginKey: plugin.pluginKey });
+
+ log.info(
+ { pluginId, pluginKey: plugin.pluginKey },
+ "plugin lifecycle: worker restarted",
+ );
+ },
+
+ // -- getStatus --------------------------------------------------------
+ async getStatus(pluginId: string): Promise<PluginStatus | null> {
+ const plugin = await registry.getById(pluginId);
+ return plugin?.status ?? null;
+ },
+
+ // -- canTransition ----------------------------------------------------
+ async canTransition(pluginId: string, to: PluginStatus): Promise<boolean> {
+ const plugin = await registry.getById(pluginId);
+ if (!plugin) return false;
+ return isValidTransition(plugin.status, to);
+ },
+
+ // -- Event subscriptions ----------------------------------------------
+ on(event, listener) {
+ emitter.on(event, listener);
+ },
+
+ off(event, listener) {
+ emitter.off(event, listener);
+ },
+
+ once(event, listener) {
+ emitter.once(event, listener);
+ },
+ };
+}
diff --git a/server/src/services/plugin-loader.ts b/server/src/services/plugin-loader.ts
new file mode 100644
index 0000000000..7041bc233e
--- /dev/null
+++ b/server/src/services/plugin-loader.ts
@@ -0,0 +1,1852 @@
+/**
+ * PluginLoader — discovery, installation, and runtime activation of plugins.
+ *
+ * This service is the entry point for the plugin system's I/O boundary:
+ *
+ * 1. **Discovery** — Scans the local plugin directory
+ * (`~/.paperclip/plugins/`) and `node_modules` for packages matching
+ * the `paperclip-plugin-*` naming convention. Aggregates results with
+ * path-based deduplication.
+ *
+ * 2. **Installation** — `installPlugin()` downloads from npm (or reads a
+ * local path), validates the manifest, checks capability consistency,
+ * and persists the install record.
+ *
+ * 3. **Runtime activation** — `activatePlugin()` wires up a loaded plugin
+ * with all runtime services: resolves its entrypoint, builds
+ * capability-gated host handlers, spawns a worker process, syncs job
+ * declarations, registers event subscriptions, and discovers tools.
+ *
+ * 4. **Shutdown** — `shutdownAll()` gracefully stops all active workers
+ * and unregisters runtime hooks.
+ *
+ * @see PLUGIN_SPEC.md §8 — Plugin Discovery
+ * @see PLUGIN_SPEC.md §10 — Package Contract
+ * @see PLUGIN_SPEC.md §12 — Process Model
+ */
+import { existsSync } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import type { Db } from "@paperclipai/db";
+import type {
+ PaperclipPluginManifestV1,
+ PluginLauncherDeclaration,
+ PluginRecord,
+ PluginUiSlotDeclaration,
+} from "@paperclipai/shared";
+import { logger } from "../middleware/logger.js";
+import { pluginManifestValidator } from "./plugin-manifest-validator.js";
+import { pluginCapabilityValidator } from "./plugin-capability-validator.js";
+import { pluginRegistryService } from "./plugin-registry.js";
+import type { PluginWorkerManager, WorkerStartOptions, WorkerToHostHandlers } from "./plugin-worker-manager.js";
+import type { PluginEventBus } from "./plugin-event-bus.js";
+import type { PluginJobScheduler } from "./plugin-job-scheduler.js";
+import type { PluginJobStore } from "./plugin-job-store.js";
+import type { PluginToolDispatcher } from "./plugin-tool-dispatcher.js";
+import type { PluginLifecycleManager } from "./plugin-lifecycle.js";
+
+const execFileAsync = promisify(execFile);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Naming convention for npm-published Paperclip plugins.
+ * Packages matching this pattern are considered Paperclip plugins.
+ *
+ * @see PLUGIN_SPEC.md §10 — Package Contract
+ */
+export const NPM_PLUGIN_PACKAGE_PREFIX = "paperclip-plugin-";
+
+/**
+ * Default local plugin directory. The loader scans this directory for
+ * locally-installed plugin packages.
+ *
+ * @see PLUGIN_SPEC.md §8.1 — On-Disk Layout
+ */
+export const DEFAULT_LOCAL_PLUGIN_DIR = path.join(
+ os.homedir(),
+ ".paperclip",
+ "plugins",
+);
+
+const DEV_TSX_LOADER_PATH = path.resolve(__dirname, "../../../cli/node_modules/tsx/dist/loader.mjs");
+
+// ---------------------------------------------------------------------------
+// Discovery result types
+// ---------------------------------------------------------------------------
+
+/**
+ * A plugin package found during discovery from any source.
+ */
+export interface DiscoveredPlugin {
+ /** Absolute path to the root of the npm package directory. */
+ packagePath: string;
+ /** The npm package name as declared in package.json. */
+ packageName: string;
+ /** Semver version from package.json. */
+ version: string;
+ /** Source that found this package. */
+ source: PluginSource;
+ /** The parsed and validated manifest if available, null if discovery-only. */
+ manifest: PaperclipPluginManifestV1 | null;
+}
+
+/**
+ * Sources from which plugins can be discovered.
+ *
+ * @see PLUGIN_SPEC.md §8.1 — On-Disk Layout
+ */
+export type PluginSource =
+ | "local-filesystem" // ~/.paperclip/plugins/ local directory
+ | "npm" // npm packages matching paperclip-plugin-* convention
+ | "registry"; // future: remote plugin registry URL
+
+type ParsedSemver = {
+ major: number;
+ minor: number;
+ patch: number;
+ prerelease: string[];
+};
+
+/**
+ * Result of a discovery scan.
+ */
+export interface PluginDiscoveryResult {
+ /** Plugins successfully discovered and validated. */
+ discovered: DiscoveredPlugin[];
+ /** Packages found but with validation errors. */
+ errors: Array<{ packagePath: string; packageName: string; error: string }>;
+ /** Source(s) that were scanned. */
+ sources: PluginSource[];
+}
+
+// ---------------------------------------------------------------------------
+// Loader options
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for the plugin loader service.
+ */
+export interface PluginLoaderOptions {
+ /**
+ * Path to the local plugin directory to scan.
+ * Defaults to ~/.paperclip/plugins/
+ */
+ localPluginDir?: string;
+
+ /**
+ * Whether to scan the local filesystem directory for plugins.
+ * Defaults to true.
+ */
+ enableLocalFilesystem?: boolean;
+
+ /**
+ * Whether to discover installed npm packages matching the paperclip-plugin-*
+ * naming convention.
+ * Defaults to true.
+ */
+ enableNpmDiscovery?: boolean;
+
+ /**
+ * Future: URL of the remote plugin registry to query.
+ * When set, the loader will also fetch available plugins from this endpoint.
+ * Registry support is not yet implemented; this field is reserved.
+ */
+ registryUrl?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Install options
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for installing a single plugin package.
+ */
+export interface PluginInstallOptions {
+ /**
+ * npm package name to install (e.g. "paperclip-plugin-linear" or "@acme/plugin-linear").
+ * Either packageName or localPath must be set.
+ */
+ packageName?: string;
+
+ /**
+ * Absolute or relative path to a local plugin directory for development installs.
+ * When set, the plugin is loaded from this path without npm install.
+ * Either packageName or localPath must be set.
+ */
+ localPath?: string;
+
+ /**
+ * Version specifier passed to npm install (e.g. "^1.2.0", "latest").
+ * Ignored when localPath is set.
+ */
+ version?: string;
+
+ /**
+ * Plugin install directory where packages are managed.
+ * Defaults to the localPluginDir configured on the service.
+ */
+ installDir?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Runtime options — services needed for initializing loaded plugins
+// ---------------------------------------------------------------------------
+
+/**
+ * Runtime services passed to the loader for plugin initialization.
+ *
+ * When these are provided, the loader can fully activate plugins (spawn
+ * workers, register event subscriptions, sync jobs, register tools).
+ * When omitted, the loader operates in discovery/install-only mode.
+ *
+ * @see PLUGIN_SPEC.md §8.3 — Install Process
+ * @see PLUGIN_SPEC.md §12 — Process Model
+ */
+export interface PluginRuntimeServices {
+ /** Worker process manager for spawning and managing plugin workers. */
+ workerManager: PluginWorkerManager;
+ /** Event bus for registering plugin event subscriptions. */
+ eventBus: PluginEventBus;
+ /** Job scheduler for registering plugin cron jobs. */
+ jobScheduler: PluginJobScheduler;
+ /** Job store for syncing manifest job declarations to the DB. */
+ jobStore: PluginJobStore;
+ /** Tool dispatcher for registering plugin-contributed agent tools. */
+ toolDispatcher: PluginToolDispatcher;
+ /** Lifecycle manager for state transitions and worker lifecycle events. */
+ lifecycleManager: PluginLifecycleManager;
+ /**
+ * Factory that creates worker-to-host RPC handlers for a given plugin.
+ *
+ * The returned handlers service worker→host calls (e.g. state.get,
+ * events.emit, config.get). Each plugin gets its own set of handlers
+ * scoped to its capabilities and plugin ID.
+ */
+ buildHostHandlers: (pluginId: string, manifest: PaperclipPluginManifestV1) => WorkerToHostHandlers;
+ /**
+ * Host instance information passed to the worker during initialization.
+ * Includes the instance ID and host version.
+ */
+ instanceInfo: {
+ instanceId: string;
+ hostVersion: string;
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Load results
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of activating (loading) a single plugin at runtime.
+ *
+ * Contains the plugin record, activation status, and any error that
+ * occurred during the process.
+ */
+export interface PluginLoadResult {
+ /** The plugin record from the database. */
+ plugin: PluginRecord;
+ /** Whether the plugin was successfully activated. */
+ success: boolean;
+ /** Error message if activation failed. */
+ error?: string;
+ /** Which subsystems were registered during activation. */
+ registered: {
+ /** True if the worker process was started. */
+ worker: boolean;
+ /** Number of event subscriptions registered (from manifest event declarations). */
+ eventSubscriptions: number;
+ /** Number of job declarations synced to the database. */
+ jobs: number;
+ /** Number of webhook endpoints declared in manifest. */
+ webhooks: number;
+ /** Number of agent tools registered. */
+ tools: number;
+ };
+}
+
+/**
+ * Result of activating all ready plugins at server startup.
+ */
+export interface PluginLoadAllResult {
+ /** Total number of plugins that were attempted. */
+ total: number;
+ /** Number of plugins successfully activated. */
+ succeeded: number;
+ /** Number of plugins that failed to activate. */
+ failed: number;
+ /** Per-plugin results. */
+ results: PluginLoadResult[];
+}
+
+/**
+ * Normalized UI contribution metadata extracted from a plugin manifest.
+ *
+ * The host serves all plugin UI bundles from the manifest's `entrypoints.ui`
+ * directory and currently expects the bundle entry module to be `index.js`.
+ */
+export interface PluginUiContributionMetadata {
+ uiEntryFile: string;
+ slots: PluginUiSlotDeclaration[];
+ launchers: PluginLauncherDeclaration[];
+}
+
+// ---------------------------------------------------------------------------
+// Service interface
+// ---------------------------------------------------------------------------
+
+export interface PluginLoader {
+ /**
+ * Discover all available plugins from configured sources.
+ *
+ * This performs a non-destructive scan of all enabled sources and returns
+ * the discovered plugins with their parsed manifests. No installs or DB
+ * writes happen during discovery.
+ *
+ * @param npmSearchDirs - Optional override for node_modules directories to search.
+ * Passed through to discoverFromNpm. When omitted the defaults are used.
+ *
+ * @see PLUGIN_SPEC.md §8.1 — On-Disk Layout
+ * @see PLUGIN_SPEC.md §8.3 — Install Process
+ */
+ discoverAll(npmSearchDirs?: string[]): Promise<PluginDiscoveryResult>;
+
+ /**
+ * Scan the local filesystem plugin directory for installed plugin packages.
+ *
+ * Reads the plugin directory, attempts to load each subdirectory as an npm
+ * package, and validates the plugin manifest.
+ *
+ * @param dir - Directory to scan (defaults to configured localPluginDir).
+ */
+ discoverFromLocalFilesystem(dir?: string): Promise<PluginDiscoveryResult>;
+
+ /**
+ * Discover Paperclip plugins installed as npm packages in the current
+ * Node.js environment matching the "paperclip-plugin-*" naming convention.
+ *
+ * Looks for packages in node_modules that match the naming convention.
+ *
+ * @param searchDirs - node_modules directories to search (defaults to process cwd resolution).
+ */
+ discoverFromNpm(searchDirs?: string[]): Promise<PluginDiscoveryResult>;
+
+ /**
+ * Load and parse the plugin manifest from a package directory.
+ *
+ * Reads the package.json, finds the manifest entrypoint declared under
+ * the "paperclipPlugin.manifest" key, loads the manifest module, and
+ * validates it against the plugin manifest schema.
+ *
+ * Returns null if the package is not a Paperclip plugin.
+ * Throws if the package is a Paperclip plugin but the manifest is invalid.
+ *
+ * @see PLUGIN_SPEC.md §10 — Package Contract
+ */
+ loadManifest(packagePath: string): Promise<PaperclipPluginManifestV1 | null>;
+
+ /**
+ * Install a plugin package and register it in the database.
+ *
+ * Follows the install process described in PLUGIN_SPEC.md §8.3:
+ * 1. Resolve npm package / local path.
+ * 2. Install into the plugin directory (npm install).
+ * 3. Read and validate plugin manifest.
+ * 4. Reject incompatible plugin API versions.
+ * 5. Validate manifest capabilities.
+ * 6. Persist install record in Postgres.
+ * 7. Return the discovered plugin for the caller to use.
+ *
+ * Worker spawning and lifecycle management are handled by the caller
+ * (pluginLifecycleManager and the server startup orchestration).
+ *
+ * @see PLUGIN_SPEC.md §8.3 — Install Process
+ */
+ installPlugin(options: PluginInstallOptions): Promise<DiscoveredPlugin>;
+
+ /**
+ * Upgrade an already-installed plugin to a newer version.
+ *
+ * Similar to installPlugin, but:
+ * 1. Requires the plugin to already exist in the database.
+ * 2. Uses the existing packageName if not provided in options.
+ * 3. Updates the existing plugin record instead of creating a new one.
+ * 4. Returns the old and new manifests for capability comparison.
+ *
+ * @see PLUGIN_SPEC.md §25.3 — Upgrade Lifecycle
+ */
+ upgradePlugin(pluginId: string, options: Omit<PluginInstallOptions, "installDir">): Promise<{
+ oldManifest: PaperclipPluginManifestV1;
+ newManifest: PaperclipPluginManifestV1;
+ discovered: DiscoveredPlugin;
+ }>;
+
+ /**
+ * Check whether a plugin API version is supported by this host.
+ */
+ isSupportedApiVersion(apiVersion: number): boolean;
+
+ /**
+ * Get the local plugin directory this loader is configured to use.
+ */
+ getLocalPluginDir(): string;
+
+ // -----------------------------------------------------------------------
+ // Runtime initialization (requires PluginRuntimeServices)
+ // -----------------------------------------------------------------------
+
+ /**
+ * Load and activate all plugins that are in `ready` status.
+ *
+ * This is the main server-startup orchestration method. For each plugin
+ * that is persisted as `ready`, it:
+ * 1. Resolves the worker entrypoint from the manifest.
+ * 2. Spawns the worker process via the worker manager.
+ * 3. Syncs job declarations from the manifest to the `plugin_jobs` table.
+ * 4. Registers the plugin with the job scheduler.
+ * 5. Registers event subscriptions declared in the manifest (scoped via the event bus).
+ * 6. Registers agent tools from the manifest via the tool dispatcher.
+ *
+ * Plugins that fail to activate are marked as `error` in the database.
+ * Activation failures are non-fatal — other plugins continue loading.
+ *
+ * **Requires** `PluginRuntimeServices` to have been provided at construction.
+ * Throws if runtime services are not available.
+ *
+ * @returns Aggregated results for all attempted plugin loads.
+ *
+ * @see PLUGIN_SPEC.md §8.4 — Server-Start Plugin Loading
+ * @see PLUGIN_SPEC.md §12 — Process Model
+ */
+ loadAll(): Promise<PluginLoadAllResult>;
+
+ /**
+ * Activate a single plugin that is in `installed` or `ready` status.
+ *
+ * Used after a fresh install (POST /api/plugins/install) or after
+ * enabling a previously disabled plugin. Performs the same subsystem
+ * registration as `loadAll()` but for a single plugin.
+ *
+ * If the plugin is in `installed` status, transitions it to `ready`
+ * via the lifecycle manager before spawning the worker.
+ *
+ * **Requires** `PluginRuntimeServices` to have been provided at construction.
+ *
+ * @param pluginId - UUID of the plugin to activate
+ * @returns The activation result for this plugin
+ *
+ * @see PLUGIN_SPEC.md §8.3 — Install Process
+ */
+ loadSingle(pluginId: string): Promise<PluginLoadResult>;
+
+ /**
+ * Deactivate a single plugin — stop its worker and unregister all
+ * subsystem registrations (events, jobs, tools).
+ *
+ * Used during plugin disable, uninstall, and before upgrade. Does NOT
+ * change the plugin's status in the database — that is the caller's
+ * responsibility (via the lifecycle manager).
+ *
+ * **Requires** `PluginRuntimeServices` to have been provided at construction.
+ *
+ * @param pluginId - UUID of the plugin to deactivate
+ * @param pluginKey - The plugin key (manifest ID) for scoped cleanup
+ *
+ * @see PLUGIN_SPEC.md §8.5 — Uninstall Process
+ */
+ unloadSingle(pluginId: string, pluginKey: string): Promise<void>;
+
+ /**
+ * Stop all managed plugin workers. Called during server shutdown.
+ *
+ * Stops the job scheduler and then stops all workers via the worker
+ * manager. Does NOT change plugin statuses in the database — plugins
+ * remain in `ready` so they are restarted on next boot.
+ *
+ * **Requires** `PluginRuntimeServices` to have been provided at construction.
+ */
+ shutdownAll(): Promise<void>;
+
+ /**
+ * Whether runtime services are available for plugin activation.
+ */
+ hasRuntimeServices(): boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a package name matches the Paperclip plugin naming convention.
+ * Accepts both the "paperclip-plugin-" prefix and scoped "@scope/plugin-" packages.
+ *
+ * @see PLUGIN_SPEC.md §10 — Package Contract
+ */
+export function isPluginPackageName(name: string): boolean {
+ if (name.startsWith(NPM_PLUGIN_PACKAGE_PREFIX)) return true;
+ // Also accept scoped packages like @acme/plugin-linear or @paperclipai/plugin-*
+ if (name.includes("/")) {
+ const localPart = name.split("/")[1] ?? "";
+ return localPart.startsWith("plugin-");
+ }
+ return false;
+}
+
+/**
+ * Read and parse a package.json from a directory path.
+ * Returns null if no package.json exists.
+ */
+async function readPackageJson(
+ dir: string,
+): Promise<Record<string, unknown> | null> {
+ const pkgPath = path.join(dir, "package.json");
+ if (!existsSync(pkgPath)) return null;
+
+ try {
+ const raw = await readFile(pkgPath, "utf-8");
+ return JSON.parse(raw) as Record<string, unknown>;
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * Resolve the manifest entrypoint from a package.json and package root.
+ *
+ * The spec defines a "paperclipPlugin" key in package.json with a "manifest"
+ * subkey pointing to the manifest module. This helper resolves the path.
+ *
+ * @see PLUGIN_SPEC.md §10 — Package Contract
+ */
+function resolveManifestPath(
+ packageRoot: string,
+ pkgJson: Record<string, unknown>,
+): string | null {
+ const paperclipPlugin = pkgJson["paperclipPlugin"];
+ if (
+ paperclipPlugin !== null &&
+ typeof paperclipPlugin === "object" &&
+ !Array.isArray(paperclipPlugin)
+ ) {
+ const manifestRelPath = (paperclipPlugin as Record<string, unknown>)[
+ "manifest"
+ ];
+ if (typeof manifestRelPath === "string") {
+ // NOTE: the resolved path is returned as-is even if the file does not yet
+ // exist on disk (e.g. the package has not been built). Callers MUST guard
+ // with existsSync() before passing the path to loadManifestFromPath().
+ return path.resolve(packageRoot, manifestRelPath);
+ }
+ }
+
+ // Fallback: look for dist/manifest.js as a convention
+ const conventionalPath = path.join(packageRoot, "dist", "manifest.js");
+ if (existsSync(conventionalPath)) {
+ return conventionalPath;
+ }
+
+ // Fallback: look for manifest.js at package root
+ const rootManifestPath = path.join(packageRoot, "manifest.js");
+ if (existsSync(rootManifestPath)) {
+ return rootManifestPath;
+ }
+
+ return null;
+}
+
+function parseSemver(version: string): ParsedSemver | null {
+ const match = version.match(
+ /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/,
+ );
+ if (!match) return null;
+
+ return {
+ major: Number(match[1]),
+ minor: Number(match[2]),
+ patch: Number(match[3]),
+ prerelease: match[4] ? match[4].split(".") : [],
+ };
+}
+
+function compareIdentifiers(left: string, right: string): number {
+ const leftIsNumeric = /^\d+$/.test(left);
+ const rightIsNumeric = /^\d+$/.test(right);
+
+ if (leftIsNumeric && rightIsNumeric) {
+ return Number(left) - Number(right);
+ }
+
+ if (leftIsNumeric) return -1;
+ if (rightIsNumeric) return 1;
+ return left.localeCompare(right);
+}
+
+function compareSemver(left: string, right: string): number {
+ const leftParsed = parseSemver(left);
+ const rightParsed = parseSemver(right);
+
+ if (!leftParsed || !rightParsed) {
+ throw new Error(`Invalid semver comparison: '${left}' vs '${right}'`);
+ }
+
+ const coreOrder = (
+ ["major", "minor", "patch"] as const
+ ).map((key) => leftParsed[key] - rightParsed[key]).find((delta) => delta !== 0);
+ if (coreOrder) {
+ return coreOrder;
+ }
+
+ if (leftParsed.prerelease.length === 0 && rightParsed.prerelease.length === 0) {
+ return 0;
+ }
+ if (leftParsed.prerelease.length === 0) return 1;
+ if (rightParsed.prerelease.length === 0) return -1;
+
+ const maxLength = Math.max(leftParsed.prerelease.length, rightParsed.prerelease.length);
+ for (let index = 0; index < maxLength; index += 1) {
+ const leftId = leftParsed.prerelease[index];
+ const rightId = rightParsed.prerelease[index];
+ if (leftId === undefined) return -1;
+ if (rightId === undefined) return 1;
+
+ const diff = compareIdentifiers(leftId, rightId);
+ if (diff !== 0) return diff;
+ }
+
+ return 0;
+}
+
+function getMinimumHostVersion(manifest: PaperclipPluginManifestV1): string | undefined {
+ return manifest.minimumHostVersion ?? manifest.minimumPaperclipVersion;
+}
+
+/**
+ * Extract UI contribution metadata from a manifest for route serialization.
+ *
+ * Returns `null` when the plugin does not declare any UI slots or launchers.
+ * Launcher declarations are aggregated from both the legacy top-level
+ * `launchers` field and the preferred `ui.launchers` field.
+ */
+export function getPluginUiContributionMetadata(
+ manifest: PaperclipPluginManifestV1,
+): PluginUiContributionMetadata | null {
+ const slots = manifest.ui?.slots ?? [];
+ const launchers = [
+ ...(manifest.launchers ?? []),
+ ...(manifest.ui?.launchers ?? []),
+ ];
+
+ if (slots.length === 0 && launchers.length === 0) {
+ return null;
+ }
+
+ return {
+ uiEntryFile: "index.js",
+ slots,
+ launchers,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a PluginLoader service.
+ *
+ * The loader is responsible for plugin discovery, installation, and runtime
+ * activation. It reads plugin packages from the local filesystem and npm,
+ * validates their manifests, registers them in the database, and — when
+ * runtime services are provided — initialises worker processes, event
+ * subscriptions, job schedules, webhook endpoints, and agent tools.
+ *
+ * Usage (discovery & install only):
+ * ```ts
+ * const loader = pluginLoader(db, { enableLocalFilesystem: true });
+ *
+ * // Discover all available plugins
+ * const result = await loader.discoverAll();
+ * for (const plugin of result.discovered) {
+ * console.log(plugin.packageName, plugin.manifest?.id);
+ * }
+ *
+ * // Install a specific plugin
+ * const discovered = await loader.installPlugin({
+ * packageName: "paperclip-plugin-linear",
+ * version: "^1.0.0",
+ * });
+ * ```
+ *
+ * Usage (full runtime activation at server startup):
+ * ```ts
+ * const loader = pluginLoader(db, loaderOpts, {
+ * workerManager,
+ * eventBus,
+ * jobScheduler,
+ * jobStore,
+ * toolDispatcher,
+ * lifecycleManager,
+ * buildHostHandlers: (pluginId, manifest) => ({ ... }),
+ * instanceInfo: { instanceId: "inst-1", hostVersion: "1.0.0" },
+ * });
+ *
+ * // Load all ready plugins at startup
+ * const loadResult = await loader.loadAll();
+ * console.log(`Loaded ${loadResult.succeeded}/${loadResult.total} plugins`);
+ *
+ * // Load a single plugin after install
+ * const singleResult = await loader.loadSingle(pluginId);
+ *
+ * // Shutdown all plugin workers on server exit
+ * await loader.shutdownAll();
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §8.1 — On-Disk Layout
+ * @see PLUGIN_SPEC.md §8.3 — Install Process
+ * @see PLUGIN_SPEC.md §12 — Process Model
+ */
+export function pluginLoader(
+ db: Db,
+ options: PluginLoaderOptions = {},
+ runtimeServices?: PluginRuntimeServices,
+): PluginLoader {
+ const {
+ localPluginDir = DEFAULT_LOCAL_PLUGIN_DIR,
+ enableLocalFilesystem = true,
+ enableNpmDiscovery = true,
+ } = options;
+
+ const registry = pluginRegistryService(db);
+ const manifestValidator = pluginManifestValidator();
+ const capabilityValidator = pluginCapabilityValidator();
+ const log = logger.child({ service: "plugin-loader" });
+ const hostVersion = runtimeServices?.instanceInfo.hostVersion;
+
+ // -------------------------------------------------------------------------
+ // Internal helpers
+ // -------------------------------------------------------------------------
+
+ /**
+ * Fetch a plugin from npm or local path, then parse and validate its manifest.
+ *
+ * This internal helper encapsulates the core plugin retrieval and validation
+ * logic used by both install and upgrade operations. It handles:
+ * 1. Resolving the package from npm or local filesystem.
+ * 2. Installing the package via npm if necessary.
+ * 3. Reading and parsing the plugin manifest.
+ * 4. Validating API version compatibility.
+ * 5. Validating manifest capabilities.
+ *
+ * @param installOptions - Options specifying the package to fetch.
+ * @returns A `DiscoveredPlugin` object containing the validated manifest.
+ */
+ async function fetchAndValidate(
+ installOptions: PluginInstallOptions,
+ ): Promise<DiscoveredPlugin> {
+ const { packageName, localPath, version, installDir } = installOptions;
+
+ if (!packageName && !localPath) {
+ throw new Error("Either packageName or localPath must be provided");
+ }
+
+ const targetInstallDir = installDir ?? localPluginDir;
+
+ // Step 1 & 2: Resolve and install package
+ let resolvedPackagePath: string;
+ let resolvedPackageName: string;
+
+ if (localPath) {
+ // Local path install — validate the directory exists
+ const absLocalPath = path.resolve(localPath);
+ if (!existsSync(absLocalPath)) {
+ throw new Error(`Local plugin path does not exist: ${absLocalPath}`);
+ }
+ resolvedPackagePath = absLocalPath;
+ const pkgJson = await readPackageJson(absLocalPath);
+ resolvedPackageName =
+ typeof pkgJson?.["name"] === "string"
+ ? pkgJson["name"]
+ : path.basename(absLocalPath);
+
+ log.info(
+ { localPath: absLocalPath, packageName: resolvedPackageName },
+ "plugin-loader: fetching plugin from local path",
+ );
+ } else {
+ // npm install
+ const spec = version ? `${packageName}@${version}` : packageName!;
+
+ log.info(
+ { spec, installDir: targetInstallDir },
+ "plugin-loader: fetching plugin from npm",
+ );
+
+ try {
+ // Use execFile (not exec) to avoid shell injection from package name/version.
+ // --ignore-scripts prevents preinstall/install/postinstall hooks from
+ // executing arbitrary code on the host before manifest validation.
+ await execFileAsync(
+ "npm",
+ ["install", spec, "--prefix", targetInstallDir, "--save", "--ignore-scripts"],
+ { timeout: 120_000 }, // 2 minute timeout for npm install
+ );
+ } catch (err) {
+ throw new Error(`npm install failed for ${spec}: ${String(err)}`);
+ }
+
+ // Resolve the package path after installation
+ const nodeModulesPath = path.join(targetInstallDir, "node_modules");
+ resolvedPackageName = packageName!;
+
+ // Handle scoped packages
+ if (resolvedPackageName.startsWith("@")) {
+ const [scope, name] = resolvedPackageName.split("/");
+ resolvedPackagePath = path.join(nodeModulesPath, scope!, name!);
+ } else {
+ resolvedPackagePath = path.join(nodeModulesPath, resolvedPackageName);
+ }
+
+ if (!existsSync(resolvedPackagePath)) {
+ throw new Error(
+ `Package directory not found after installation: ${resolvedPackagePath}`,
+ );
+ }
+ }
+
+ // Step 3: Read and validate plugin manifest
+ // Note: this.loadManifest (used via current context)
+ const pkgJson = await readPackageJson(resolvedPackagePath);
+ if (!pkgJson) throw new Error(`Missing package.json at ${resolvedPackagePath}`);
+
+ const manifestPath = resolveManifestPath(resolvedPackagePath, pkgJson);
+ if (!manifestPath || !existsSync(manifestPath)) {
+ throw new Error(
+ `Package ${resolvedPackageName} at ${resolvedPackagePath} does not appear to be a Paperclip plugin (no manifest found).`,
+ );
+ }
+
+ const manifest = await loadManifestFromPath(manifestPath);
+
+ // Step 4: Reject incompatible plugin API versions
+ if (!manifestValidator.getSupportedVersions().includes(manifest.apiVersion)) {
+ throw new Error(
+ `Plugin ${manifest.id} declares apiVersion ${manifest.apiVersion} which is not supported by this host. ` +
+ `Supported versions: ${manifestValidator.getSupportedVersions().join(", ")}`,
+ );
+ }
+
+ // Step 5: Validate manifest capabilities are consistent
+ const capResult = capabilityValidator.validateManifestCapabilities(manifest);
+ if (!capResult.allowed) {
+ throw new Error(
+ `Plugin ${manifest.id} manifest has inconsistent capabilities. ` +
+ `Missing required capabilities for declared features: ${capResult.missing.join(", ")}`,
+ );
+ }
+
+ // Step 6: Reject plugins that require a newer host than the running server
+ const minimumHostVersion = getMinimumHostVersion(manifest);
+ if (minimumHostVersion && hostVersion) {
+ if (compareSemver(hostVersion, minimumHostVersion) < 0) {
+ throw new Error(
+ `Plugin ${manifest.id} requires host version ${minimumHostVersion} or newer, ` +
+ `but this server is running ${hostVersion}`,
+ );
+ }
+ }
+
+ // Use the version declared in the manifest (required field per the spec)
+ const resolvedVersion = manifest.version;
+
+ return {
+ packagePath: resolvedPackagePath,
+ packageName: resolvedPackageName,
+ version: resolvedVersion,
+ source: localPath ? "local-filesystem" : "npm",
+ manifest,
+ };
+ }
+
+ /**
+ * Attempt to load and validate a plugin manifest from a resolved path.
+ * Returns the manifest on success or throws with a descriptive error.
+ */
+ async function loadManifestFromPath(
+ manifestPath: string,
+ ): Promise<PaperclipPluginManifestV1> {
+ let raw: unknown;
+
+ try {
+ // Dynamic import works for both .js (ESM) and .cjs (CJS) manifests
+ const mod = await import(manifestPath) as Record<string, unknown>;
+ // The manifest may be the default export or the module itself
+ raw = mod["default"] ?? mod;
+ } catch (err) {
+ throw new Error(
+ `Failed to load manifest module at ${manifestPath}: ${String(err)}`,
+ );
+ }
+
+ return manifestValidator.parseOrThrow(raw);
+ }
+
+ /**
+ * Build a DiscoveredPlugin from a resolved package directory, or null
+ * if the package is not a Paperclip plugin.
+ */
+ async function buildDiscoveredPlugin(
+ packagePath: string,
+ source: PluginSource,
+ ): Promise<DiscoveredPlugin | null> {
+ const pkgJson = await readPackageJson(packagePath);
+ if (!pkgJson) return null;
+
+ const packageName = typeof pkgJson["name"] === "string" ? pkgJson["name"] : "";
+ const version = typeof pkgJson["version"] === "string" ? pkgJson["version"] : "0.0.0";
+
+ // Determine if this is a plugin package at all
+ const hasPaperclipPlugin = "paperclipPlugin" in pkgJson;
+ const nameMatchesConvention = isPluginPackageName(packageName);
+
+ if (!hasPaperclipPlugin && !nameMatchesConvention) {
+ return null;
+ }
+
+ const manifestPath = resolveManifestPath(packagePath, pkgJson);
+ if (!manifestPath || !existsSync(manifestPath)) {
+ // Found a potential plugin package but no manifest entry point — treat
+ // as a discovery-only result with no manifest
+ return {
+ packagePath,
+ packageName,
+ version,
+ source,
+ manifest: null,
+ };
+ }
+
+ try {
+ const manifest = await loadManifestFromPath(manifestPath);
+ return {
+ packagePath,
+ packageName,
+ version,
+ source,
+ manifest,
+ };
+ } catch (err) {
+ // Rethrow with context — callers catch and route to the errors array
+ throw new Error(
+ `Plugin ${packageName}: ${String(err)}`,
+ );
+ }
+ }
+
+ // -------------------------------------------------------------------------
+ // Public API
+ // -------------------------------------------------------------------------
+
+ return {
+ // -----------------------------------------------------------------------
+ // discoverAll
+ // -----------------------------------------------------------------------
+
+ async discoverAll(npmSearchDirs?: string[]): Promise<PluginDiscoveryResult> {
+ const allDiscovered: DiscoveredPlugin[] = [];
+ const allErrors: Array<{ packagePath: string; packageName: string; error: string }> = [];
+ const sources: PluginSource[] = [];
+
+ if (enableLocalFilesystem) {
+ sources.push("local-filesystem");
+ const fsResult = await this.discoverFromLocalFilesystem();
+ allDiscovered.push(...fsResult.discovered);
+ allErrors.push(...fsResult.errors);
+ }
+
+ if (enableNpmDiscovery) {
+ sources.push("npm");
+ const npmResult = await this.discoverFromNpm(npmSearchDirs);
+ // Deduplicate against already-discovered packages (same package path)
+ const existingPaths = new Set(allDiscovered.map((d) => d.packagePath));
+ for (const plugin of npmResult.discovered) {
+ if (!existingPaths.has(plugin.packagePath)) {
+ allDiscovered.push(plugin);
+ }
+ }
+ allErrors.push(...npmResult.errors);
+ }
+
+ // Future: registry source (options.registryUrl)
+ if (options.registryUrl) {
+ sources.push("registry");
+ log.warn(
+ { registryUrl: options.registryUrl },
+ "plugin-loader: remote registry discovery is not yet implemented",
+ );
+ }
+
+ log.info(
+ {
+ discovered: allDiscovered.length,
+ errors: allErrors.length,
+ sources,
+ },
+ "plugin-loader: discovery complete",
+ );
+
+ return { discovered: allDiscovered, errors: allErrors, sources };
+ },
+
+ // -----------------------------------------------------------------------
+ // discoverFromLocalFilesystem
+ // -----------------------------------------------------------------------
+
+ async discoverFromLocalFilesystem(dir?: string): Promise<PluginDiscoveryResult> {
+ const scanDir = dir ?? localPluginDir;
+ const discovered: DiscoveredPlugin[] = [];
+ const errors: Array<{ packagePath: string; packageName: string; error: string }> = [];
+
+ if (!existsSync(scanDir)) {
+ log.debug(
+ { dir: scanDir },
+ "plugin-loader: local plugin directory does not exist, skipping",
+ );
+ return { discovered, errors, sources: ["local-filesystem"] };
+ }
+
+ let entries: string[];
+ try {
+ entries = await readdir(scanDir);
+ } catch (err) {
+ log.warn({ dir: scanDir, err }, "plugin-loader: failed to read local plugin directory");
+ return { discovered, errors, sources: ["local-filesystem"] };
+ }
+
+ for (const entry of entries) {
+ const entryPath = path.join(scanDir, entry);
+
+ // Check if entry is a directory
+ let entryStat;
+ try {
+ entryStat = await stat(entryPath);
+ } catch {
+ continue;
+ }
+ if (!entryStat.isDirectory()) continue;
+
+ // Handle scoped packages: @scope/plugin-name is a subdirectory
+ if (entry.startsWith("@")) {
+ let scopedEntries: string[];
+ try {
+ scopedEntries = await readdir(entryPath);
+ } catch {
+ continue;
+ }
+ for (const scopedEntry of scopedEntries) {
+ const scopedPath = path.join(entryPath, scopedEntry);
+ try {
+ const scopedStat = await stat(scopedPath);
+ if (!scopedStat.isDirectory()) continue;
+ const plugin = await buildDiscoveredPlugin(scopedPath, "local-filesystem");
+ if (plugin) discovered.push(plugin);
+ } catch (err) {
+ errors.push({
+ packagePath: scopedPath,
+ packageName: `${entry}/${scopedEntry}`,
+ error: String(err),
+ });
+ }
+ }
+ continue;
+ }
+
+ try {
+ const plugin = await buildDiscoveredPlugin(entryPath, "local-filesystem");
+ if (plugin) discovered.push(plugin);
+ } catch (err) {
+ const pkgJson = await readPackageJson(entryPath);
+ const packageName =
+ typeof pkgJson?.["name"] === "string" ? pkgJson["name"] : entry;
+ errors.push({ packagePath: entryPath, packageName, error: String(err) });
+ }
+ }
+
+ log.debug(
+ { dir: scanDir, discovered: discovered.length, errors: errors.length },
+ "plugin-loader: local filesystem scan complete",
+ );
+
+ return { discovered, errors, sources: ["local-filesystem"] };
+ },
+
+ // -----------------------------------------------------------------------
+ // discoverFromNpm
+ // -----------------------------------------------------------------------
+
+ async discoverFromNpm(searchDirs?: string[]): Promise<PluginDiscoveryResult> {
+ const discovered: DiscoveredPlugin[] = [];
+ const errors: Array<{ packagePath: string; packageName: string; error: string }> = [];
+
+ // Determine the node_modules directories to search.
+ // When searchDirs is undefined OR empty, fall back to the conventional
+ // defaults (cwd/node_modules and localPluginDir/node_modules).
+ // To search nowhere explicitly, pass a non-empty array of non-existent paths.
+ const dirsToSearch: string[] = searchDirs && searchDirs.length > 0 ? searchDirs : [];
+
+ if (dirsToSearch.length === 0) {
+ // Default: search node_modules relative to the process working directory
+ // and also the local plugin dir's node_modules
+ const cwdNodeModules = path.join(process.cwd(), "node_modules");
+ const localNodeModules = path.join(localPluginDir, "node_modules");
+
+ if (existsSync(cwdNodeModules)) dirsToSearch.push(cwdNodeModules);
+ if (existsSync(localNodeModules)) dirsToSearch.push(localNodeModules);
+ }
+
+ for (const nodeModulesDir of dirsToSearch) {
+ if (!existsSync(nodeModulesDir)) continue;
+
+ let entries: string[];
+ try {
+ entries = await readdir(nodeModulesDir);
+ } catch {
+ continue;
+ }
+
+ for (const entry of entries) {
+ const entryPath = path.join(nodeModulesDir, entry);
+
+ // Handle scoped packages (@scope/*)
+ if (entry.startsWith("@")) {
+ let scopedEntries: string[];
+ try {
+ scopedEntries = await readdir(entryPath);
+ } catch {
+ continue;
+ }
+ for (const scopedEntry of scopedEntries) {
+ const fullName = `${entry}/${scopedEntry}`;
+ if (!isPluginPackageName(fullName)) continue;
+
+ const scopedPath = path.join(entryPath, scopedEntry);
+ try {
+ const plugin = await buildDiscoveredPlugin(scopedPath, "npm");
+ if (plugin) discovered.push(plugin);
+ } catch (err) {
+ errors.push({
+ packagePath: scopedPath,
+ packageName: fullName,
+ error: String(err),
+ });
+ }
+ }
+ continue;
+ }
+
+ // Non-scoped packages: check naming convention
+ if (!isPluginPackageName(entry)) continue;
+
+ let entryStat;
+ try {
+ entryStat = await stat(entryPath);
+ } catch {
+ continue;
+ }
+ if (!entryStat.isDirectory()) continue;
+
+ try {
+ const plugin = await buildDiscoveredPlugin(entryPath, "npm");
+ if (plugin) discovered.push(plugin);
+ } catch (err) {
+ const pkgJson = await readPackageJson(entryPath);
+ const packageName =
+ typeof pkgJson?.["name"] === "string" ? pkgJson["name"] : entry;
+ errors.push({ packagePath: entryPath, packageName, error: String(err) });
+ }
+ }
+ }
+
+ log.debug(
+ { searchDirs: dirsToSearch, discovered: discovered.length, errors: errors.length },
+ "plugin-loader: npm discovery scan complete",
+ );
+
+ return { discovered, errors, sources: ["npm"] };
+ },
+
+ // -----------------------------------------------------------------------
+ // loadManifest
+ // -----------------------------------------------------------------------
+
+ async loadManifest(packagePath: string): Promise<PaperclipPluginManifestV1 | null> {
+ const pkgJson = await readPackageJson(packagePath);
+ if (!pkgJson) return null;
+
+ const hasPaperclipPlugin = "paperclipPlugin" in pkgJson;
+ const packageName = typeof pkgJson["name"] === "string" ? pkgJson["name"] : "";
+ const nameMatchesConvention = isPluginPackageName(packageName);
+
+ if (!hasPaperclipPlugin && !nameMatchesConvention) {
+ return null;
+ }
+
+ const manifestPath = resolveManifestPath(packagePath, pkgJson);
+ if (!manifestPath || !existsSync(manifestPath)) return null;
+
+ return loadManifestFromPath(manifestPath);
+ },
+
+ // -----------------------------------------------------------------------
+ // installPlugin
+ // -----------------------------------------------------------------------
+
+ async installPlugin(installOptions: PluginInstallOptions): Promise<DiscoveredPlugin> {
+ const discovered = await fetchAndValidate(installOptions);
+
+ // Step 6: Persist install record in Postgres (include packagePath for local installs so the worker can be resolved)
+ await registry.install(
+ {
+ packageName: discovered.packageName,
+ packagePath: discovered.source === "local-filesystem" ? discovered.packagePath : undefined,
+ },
+ discovered.manifest!,
+ );
+
+ log.info(
+ {
+ pluginId: discovered.manifest!.id,
+ packageName: discovered.packageName,
+ version: discovered.version,
+ capabilities: discovered.manifest!.capabilities,
+ },
+ "plugin-loader: plugin installed successfully",
+ );
+
+ return discovered;
+ },
+
+ // -----------------------------------------------------------------------
+ // upgradePlugin
+ // -----------------------------------------------------------------------
+
+ /**
+ * Upgrade an already-installed plugin to a newer version.
+ *
+ * This method:
+ * 1. Fetches and validates the new plugin package using `fetchAndValidate`.
+ * 2. Ensures the new manifest ID matches the existing plugin ID for safety.
+ * 3. Updates the plugin record in the registry with the new version and manifest.
+ *
+ * @param pluginId - The UUID of the plugin to upgrade.
+ * @param upgradeOptions - Options for the upgrade (packageName, localPath, version).
+ * @returns The old and new manifests, along with the discovery metadata.
+ * @throws {Error} If the plugin is not found or if the new manifest ID differs.
+ */
+ async upgradePlugin(
+ pluginId: string,
+ upgradeOptions: Omit<PluginInstallOptions, "installDir">,
+ ): Promise<{
+ oldManifest: PaperclipPluginManifestV1;
+ newManifest: PaperclipPluginManifestV1;
+ discovered: DiscoveredPlugin;
+ }> {
+ const plugin = (await registry.getById(pluginId)) as {
+ id: string;
+ packageName: string;
+ manifestJson: PaperclipPluginManifestV1;
+ } | null;
+ if (!plugin) throw new Error(`Plugin not found: ${pluginId}`);
+
+ const oldManifest = plugin.manifestJson;
+ const {
+ packageName = plugin.packageName,
+ localPath,
+ version,
+ } = upgradeOptions;
+
+ log.info(
+ { pluginId, packageName, version, localPath },
+ "plugin-loader: upgrading plugin",
+ );
+
+ // 1. Fetch/Install the new version
+ const discovered = await fetchAndValidate({
+ packageName,
+ localPath,
+ version,
+ installDir: localPluginDir,
+ });
+
+ const newManifest = discovered.manifest!;
+
+ // 2. Validate it's the same plugin ID
+ if (newManifest.id !== oldManifest.id) {
+ throw new Error(
+ `Upgrade failed: new manifest ID '${newManifest.id}' does not match existing plugin ID '${oldManifest.id}'`,
+ );
+ }
+
+ // 3. Detect capability escalation — new capabilities not in the old manifest
+ const oldCaps = new Set(oldManifest.capabilities ?? []);
+ const newCaps = newManifest.capabilities ?? [];
+ const escalated = newCaps.filter((c) => !oldCaps.has(c));
+
+ if (escalated.length > 0) {
+ log.warn(
+ { pluginId, escalated, oldVersion: oldManifest.version, newVersion: newManifest.version },
+ "plugin-loader: upgrade introduces new capabilities — requires admin approval",
+ );
+ throw new Error(
+ `Upgrade for "${pluginId}" introduces new capabilities that require approval: ${escalated.join(", ")}. ` +
+ `The previous version declared [${[...oldCaps].join(", ")}]. ` +
+ `Please review and approve the capability escalation before upgrading.`,
+ );
+ }
+
+ // 4. Update the existing record
+ await registry.update(pluginId, {
+ packageName: discovered.packageName,
+ version: discovered.version,
+ manifest: newManifest,
+ });
+
+ return {
+ oldManifest,
+ newManifest,
+ discovered,
+ };
+ },
+
+ // -----------------------------------------------------------------------
+ // isSupportedApiVersion
+ // -----------------------------------------------------------------------
+
+ isSupportedApiVersion(apiVersion: number): boolean {
+ return manifestValidator.getSupportedVersions().includes(apiVersion);
+ },
+
+ // -----------------------------------------------------------------------
+ // getLocalPluginDir
+ // -----------------------------------------------------------------------
+
+ getLocalPluginDir(): string {
+ return localPluginDir;
+ },
+
+ // -----------------------------------------------------------------------
+ // hasRuntimeServices
+ // -----------------------------------------------------------------------
+
+ hasRuntimeServices(): boolean {
+ return runtimeServices !== undefined;
+ },
+
+ // -----------------------------------------------------------------------
+ // -----------------------------------------------------------------------
+ // loadAll
+ // -----------------------------------------------------------------------
+
+ /**
+ * loadAll — Loads and activates all plugins that are currently in 'ready' status.
+ *
+ * This method is typically called during server startup. It fetches all ready
+ * plugins from the registry and attempts to activate them in parallel using
+ * Promise.allSettled. Failures in individual plugins do not prevent others from loading.
+ *
+ * @returns A promise that resolves with summary statistics of the load operation.
+ */
+ async loadAll(): Promise<PluginLoadAllResult> {
+ if (!runtimeServices) {
+ throw new Error(
+ "Cannot loadAll: no PluginRuntimeServices provided. " +
+ "Pass runtime services as the third argument to pluginLoader().",
+ );
+ }
+
+ log.info("plugin-loader: loading all ready plugins");
+
+ // Fetch all plugins in ready status, ordered by installOrder
+ const readyPlugins = (await registry.listByStatus("ready")) as PluginRecord[];
+
+ if (readyPlugins.length === 0) {
+ log.info("plugin-loader: no ready plugins to load");
+ return { total: 0, succeeded: 0, failed: 0, results: [] };
+ }
+
+ log.info(
+ { count: readyPlugins.length },
+ "plugin-loader: found ready plugins to load",
+ );
+
+ // Load plugins in parallel
+ const results = await Promise.allSettled(
+ readyPlugins.map((plugin) => activatePlugin(plugin))
+ );
+
+ const loadResults = results.map((r, i) => {
+ if (r.status === "fulfilled") return r.value;
+ return {
+ plugin: readyPlugins[i]!,
+ success: false,
+ error: String(r.reason),
+ registered: { worker: false, eventSubscriptions: 0, jobs: 0, webhooks: 0, tools: 0 },
+ };
+ });
+
+ const succeeded = loadResults.filter((r) => r.success).length;
+ const failed = loadResults.filter((r) => !r.success).length;
+
+ log.info(
+ {
+ total: readyPlugins.length,
+ succeeded,
+ failed,
+ },
+ "plugin-loader: loadAll complete",
+ );
+
+ return {
+ total: readyPlugins.length,
+ succeeded,
+ failed,
+ results: loadResults,
+ };
+ },
+
+ // -----------------------------------------------------------------------
+ // loadSingle
+ // -----------------------------------------------------------------------
+
+ /**
+ * loadSingle — Loads and activates a single plugin by its ID.
+ *
+ * This method retrieves the plugin from the registry, ensures it's in a valid
+ * state, and then calls activatePlugin to start its worker and register its
+ * capabilities (tools, jobs, etc.).
+ *
+ * @param pluginId - The UUID of the plugin to load.
+ * @returns A promise that resolves with the result of the activation.
+ */
+ async loadSingle(pluginId: string): Promise<PluginLoadResult> {
+ if (!runtimeServices) {
+ throw new Error(
+ "Cannot loadSingle: no PluginRuntimeServices provided. " +
+ "Pass runtime services as the third argument to pluginLoader().",
+ );
+ }
+
+ const plugin = (await registry.getById(pluginId)) as PluginRecord | null;
+ if (!plugin) {
+ throw new Error(`Plugin not found: ${pluginId}`);
+ }
+
+ // If the plugin is in 'installed' status, transition it to 'ready' first.
+ // lifecycleManager.load() transitions the status AND activates the plugin
+ // via activateReadyPlugin() → loadSingle() (recursive call with 'ready'
+ // status) → activatePlugin(). We must NOT call activatePlugin() again here,
+ // as that would double-start the worker and duplicate registrations.
+ if (plugin.status === "installed") {
+ await runtimeServices.lifecycleManager.load(pluginId);
+ const updated = (await registry.getById(pluginId)) as PluginRecord | null;
+ if (!updated) throw new Error(`Plugin not found after status update: ${pluginId}`);
+ return {
+ plugin: updated,
+ success: true,
+ registered: { worker: true, eventSubscriptions: 0, jobs: 0, webhooks: 0, tools: 0 },
+ };
+ }
+
+ if (plugin.status !== "ready") {
+ throw new Error(
+ `Cannot load plugin in status '${plugin.status}'. ` +
+ `Plugin must be in 'installed' or 'ready' status.`,
+ );
+ }
+
+ return activatePlugin(plugin);
+ },
+
+ // -----------------------------------------------------------------------
+ // unloadSingle
+ // -----------------------------------------------------------------------
+
+ async unloadSingle(pluginId: string, pluginKey: string): Promise<void> {
+ if (!runtimeServices) {
+ throw new Error(
+ "Cannot unloadSingle: no PluginRuntimeServices provided.",
+ );
+ }
+
+ log.info(
+ { pluginId, pluginKey },
+ "plugin-loader: unloading single plugin",
+ );
+
+ const {
+ workerManager,
+ eventBus,
+ jobScheduler,
+ toolDispatcher,
+ } = runtimeServices;
+
+ // 1. Unregister from job scheduler (cancels in-flight runs)
+ try {
+ await jobScheduler.unregisterPlugin(pluginId);
+ } catch (err) {
+ log.warn(
+ { pluginId, err: err instanceof Error ? err.message : String(err) },
+ "plugin-loader: failed to unregister from job scheduler (best-effort)",
+ );
+ }
+
+ // 2. Clear event subscriptions
+ eventBus.clearPlugin(pluginKey);
+
+ // 3. Unregister agent tools
+ toolDispatcher.unregisterPluginTools(pluginKey);
+
+ // 4. Stop the worker process
+ try {
+ if (workerManager.isRunning(pluginId)) {
+ await workerManager.stopWorker(pluginId);
+ }
+ } catch (err) {
+ log.warn(
+ { pluginId, err: err instanceof Error ? err.message : String(err) },
+ "plugin-loader: failed to stop worker during unload (best-effort)",
+ );
+ }
+
+ log.info(
+ { pluginId, pluginKey },
+ "plugin-loader: plugin unloaded successfully",
+ );
+ },
+
+ // -----------------------------------------------------------------------
+ // shutdownAll
+ // -----------------------------------------------------------------------
+
+ async shutdownAll(): Promise<void> {
+ if (!runtimeServices) {
+ throw new Error(
+ "Cannot shutdownAll: no PluginRuntimeServices provided.",
+ );
+ }
+
+ log.info("plugin-loader: shutting down all plugins");
+
+ const { workerManager, jobScheduler } = runtimeServices;
+
+ // 1. Stop the job scheduler tick loop
+ jobScheduler.stop();
+
+ // 2. Stop all worker processes
+ await workerManager.stopAll();
+
+ log.info("plugin-loader: all plugins shut down");
+ },
+ };
+
+ // -------------------------------------------------------------------------
+ // Internal: activatePlugin — shared logic for loadAll and loadSingle
+ // -------------------------------------------------------------------------
+
+ /**
+ * Activate a single plugin: spawn its worker, register event subscriptions,
+ * sync jobs, register tools.
+ *
+ * This is the core orchestration logic shared by `loadAll()` and `loadSingle()`.
+ * Failures are caught and reported in the result; the plugin is marked as
+ * `error` in the database when activation fails.
+ */
+ async function activatePlugin(plugin: PluginRecord): Promise<PluginLoadResult> {
+ const manifest = plugin.manifestJson;
+ const pluginId = plugin.id;
+ const pluginKey = plugin.pluginKey;
+
+ const registered: PluginLoadResult["registered"] = {
+ worker: false,
+ eventSubscriptions: 0,
+ jobs: 0,
+ webhooks: 0,
+ tools: 0,
+ };
+
+ // Guard: runtime services must exist (callers already checked)
+ if (!runtimeServices) {
+ return {
+ plugin,
+ success: false,
+ error: "No runtime services available",
+ registered,
+ };
+ }
+
+ const {
+ workerManager,
+ eventBus,
+ jobScheduler,
+ jobStore,
+ toolDispatcher,
+ lifecycleManager,
+ buildHostHandlers,
+ instanceInfo,
+ } = runtimeServices;
+
+ try {
+ log.info(
+ { pluginId, pluginKey, version: plugin.version },
+ "plugin-loader: activating plugin",
+ );
+
+ // ------------------------------------------------------------------
+ // 1. Resolve worker entrypoint
+ // ------------------------------------------------------------------
+ const workerEntrypoint = resolveWorkerEntrypoint(plugin, localPluginDir);
+
+ // ------------------------------------------------------------------
+ // 2. Build host handlers for this plugin
+ // ------------------------------------------------------------------
+ const hostHandlers = buildHostHandlers(pluginId, manifest);
+
+ // ------------------------------------------------------------------
+ // 3. Retrieve plugin config (if any)
+ // ------------------------------------------------------------------
+ let config: Record<string, unknown> = {};
+ try {
+ const configRow = await registry.getConfig(pluginId);
+ if (configRow && typeof configRow === "object" && "configJson" in configRow) {
+ config = (configRow as { configJson: Record<string, unknown> }).configJson ?? {};
+ }
+ } catch {
+ // Config may not exist yet — use empty object
+ log.debug({ pluginId }, "plugin-loader: no config found, using empty config");
+ }
+
+ // ------------------------------------------------------------------
+ // 4. Spawn worker process
+ // ------------------------------------------------------------------
+ const workerOptions: WorkerStartOptions = {
+ entrypointPath: workerEntrypoint,
+ manifest,
+ config,
+ instanceInfo,
+ apiVersion: manifest.apiVersion,
+ hostHandlers,
+ autoRestart: true,
+ };
+
+ // Repo-local plugin installs can resolve workspace TS sources at runtime
+ // (for example @paperclipai/shared exports). Run those workers through
+ // the tsx loader so first-party example plugins work in development.
+ if (plugin.packagePath && existsSync(DEV_TSX_LOADER_PATH)) {
+ workerOptions.execArgv = ["--import", DEV_TSX_LOADER_PATH];
+ }
+
+ await workerManager.startWorker(pluginId, workerOptions);
+ registered.worker = true;
+
+ log.info(
+ { pluginId, pluginKey },
+ "plugin-loader: worker started",
+ );
+
+ // ------------------------------------------------------------------
+ // 5. Sync job declarations and register with scheduler
+ // ------------------------------------------------------------------
+ const jobDeclarations = manifest.jobs ?? [];
+ if (jobDeclarations.length > 0) {
+ await jobStore.syncJobDeclarations(pluginId, jobDeclarations);
+ await jobScheduler.registerPlugin(pluginId);
+ registered.jobs = jobDeclarations.length;
+
+ log.info(
+ { pluginId, pluginKey, jobs: jobDeclarations.length },
+ "plugin-loader: job declarations synced and plugin registered with scheduler",
+ );
+ }
+
+ // ------------------------------------------------------------------
+ // 6. Register event subscriptions
+ //
+ // Note: Event subscriptions are declared at runtime by the plugin
+ // worker via the SDK's ctx.events.on() calls. The event bus manages
+ // per-plugin subscription scoping. Here we ensure the event bus has
+ // a scoped handle ready for this plugin — the actual subscriptions
+ // are registered by the host handler layer when the worker calls
+ // events.subscribe via RPC.
+ //
+ // The bus.forPlugin() call creates the scoped handle if needed;
+ // any previous subscriptions for this plugin are preserved if the
+ // worker is restarting.
+ // ------------------------------------------------------------------
+ const _scopedBus = eventBus.forPlugin(pluginKey);
+ registered.eventSubscriptions = eventBus.subscriptionCount(pluginKey);
+
+ log.debug(
+ { pluginId, pluginKey },
+ "plugin-loader: event bus scoped handle ready",
+ );
+
+ // ------------------------------------------------------------------
+ // 7. Register webhook endpoints (manifest-declared)
+ //
+ // Webhooks are statically declared in the manifest. The actual
+ // endpoint routing is handled by the plugin routes module which
+ // checks the manifest for declared webhooks. No explicit
+ // registration step is needed here — the manifest is persisted
+ // in the DB and the route handler reads it at request time.
+ //
+ // We track the count for the result reporting.
+ // ------------------------------------------------------------------
+ const webhookDeclarations = manifest.webhooks ?? [];
+ registered.webhooks = webhookDeclarations.length;
+
+ if (webhookDeclarations.length > 0) {
+ log.info(
+ { pluginId, pluginKey, webhooks: webhookDeclarations.length },
+ "plugin-loader: webhook endpoints declared in manifest",
+ );
+ }
+
+ // ------------------------------------------------------------------
+ // 8. Register agent tools
+ // ------------------------------------------------------------------
+ const toolDeclarations = manifest.tools ?? [];
+ if (toolDeclarations.length > 0) {
+ toolDispatcher.registerPluginTools(pluginKey, manifest);
+ registered.tools = toolDeclarations.length;
+
+ log.info(
+ { pluginId, pluginKey, tools: toolDeclarations.length },
+ "plugin-loader: agent tools registered",
+ );
+ }
+
+ // ------------------------------------------------------------------
+ // Done — plugin fully activated
+ // ------------------------------------------------------------------
+ log.info(
+ {
+ pluginId,
+ pluginKey,
+ version: plugin.version,
+ registered,
+ },
+ "plugin-loader: plugin activated successfully",
+ );
+
+ return { plugin, success: true, registered };
+ } catch (err) {
+ const errorMessage = err instanceof Error ? err.message : String(err);
+
+ log.error(
+ { pluginId, pluginKey, err: errorMessage },
+ "plugin-loader: failed to activate plugin",
+ );
+
+ // Mark the plugin as errored in the database so it is not retried
+ // automatically on next startup without operator intervention.
+ try {
+ await lifecycleManager.markError(pluginId, `Activation failed: ${errorMessage}`);
+ } catch (markErr) {
+ log.error(
+ {
+ pluginId,
+ err: markErr instanceof Error ? markErr.message : String(markErr),
+ },
+ "plugin-loader: failed to mark plugin as error after activation failure",
+ );
+ }
+
+ return {
+ plugin,
+ success: false,
+ error: errorMessage,
+ registered,
+ };
+ }
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Worker entrypoint resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the absolute path to a plugin's worker entrypoint from its manifest
+ * and known install locations.
+ *
+ * The manifest `entrypoints.worker` field is relative to the package root.
+ * We check the local plugin directory (where the package was installed) and
+ * also the package directory if it was a local-path install.
+ *
+ * @see PLUGIN_SPEC.md §10 — Package Contract
+ */
+function resolveWorkerEntrypoint(
+ plugin: PluginRecord & { packagePath?: string | null },
+ localPluginDir: string,
+): string {
+ const manifest = plugin.manifestJson;
+ const workerRelPath = manifest.entrypoints.worker;
+
+ // For local-path installs we persist the resolved package path; use it first
+ if (plugin.packagePath && existsSync(plugin.packagePath)) {
+ const entrypoint = path.resolve(plugin.packagePath, workerRelPath);
+ if (entrypoint.startsWith(path.resolve(plugin.packagePath)) && existsSync(entrypoint)) {
+ return entrypoint;
+ }
+ }
+
+ // Try the local plugin directory (standard npm install location)
+ const packageName = plugin.packageName;
+ let packageDir: string;
+
+ if (packageName.startsWith("@")) {
+ // Scoped package: @scope/plugin-name → localPluginDir/node_modules/@scope/plugin-name
+ const [scope, name] = packageName.split("/");
+ packageDir = path.join(localPluginDir, "node_modules", scope!, name!);
+ } else {
+ packageDir = path.join(localPluginDir, "node_modules", packageName);
+ }
+
+ // Also check if the package exists directly under localPluginDir
+ // (for direct local-path installs or symlinked packages)
+ const directDir = path.join(localPluginDir, packageName);
+
+ // Try in order: node_modules path, direct path
+ for (const dir of [packageDir, directDir]) {
+ const entrypoint = path.resolve(dir, workerRelPath);
+
+ // Security: ensure entrypoint is actually inside the directory (prevent path traversal)
+ if (!entrypoint.startsWith(path.resolve(dir))) {
+ continue;
+ }
+
+ if (existsSync(entrypoint)) {
+ return entrypoint;
+ }
+ }
+
+ // Fallback: try the worker path as-is (absolute or relative to cwd)
+ // ONLY if it's already an absolute path and we trust the manifest (which we've already validated)
+ if (path.isAbsolute(workerRelPath) && existsSync(workerRelPath)) {
+ return workerRelPath;
+ }
+
+ throw new Error(
+ `Worker entrypoint not found for plugin "${plugin.pluginKey}". ` +
+ `Checked: ${path.resolve(packageDir, workerRelPath)}, ` +
+ `${path.resolve(directDir, workerRelPath)}`,
+ );
+}
diff --git a/server/src/services/plugin-log-retention.ts b/server/src/services/plugin-log-retention.ts
new file mode 100644
index 0000000000..832ddfd124
--- /dev/null
+++ b/server/src/services/plugin-log-retention.ts
@@ -0,0 +1,86 @@
+import { lt, sql } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import { pluginLogs } from "@paperclipai/db";
+import { logger } from "../middleware/logger.js";
+
+/** Default retention period: 7 days. */
+const DEFAULT_RETENTION_DAYS = 7;
+
+/** Maximum rows to delete per sweep to avoid long-running transactions. */
+const DELETE_BATCH_SIZE = 5_000;
+
+/** Maximum number of batches per sweep to guard against unbounded loops. */
+const MAX_ITERATIONS = 100;
+
+/**
+ * Delete plugin log rows older than `retentionDays`.
+ *
+ * Deletes in batches of `DELETE_BATCH_SIZE` to keep transaction sizes
+ * bounded and avoid holding locks for extended periods.
+ *
+ * @returns The total number of rows deleted.
+ */
+export async function prunePluginLogs(
+ db: Db,
+ retentionDays: number = DEFAULT_RETENTION_DAYS,
+): Promise<number> {
+ const cutoff = new Date();
+ cutoff.setDate(cutoff.getDate() - retentionDays);
+
+ let totalDeleted = 0;
+ let iterations = 0;
+
+ // Delete in batches to avoid long-running transactions
+ while (iterations < MAX_ITERATIONS) {
+ const deleted = await db
+ .delete(pluginLogs)
+ .where(lt(pluginLogs.createdAt, cutoff))
+ .returning({ id: pluginLogs.id })
+ .then((rows) => rows.length);
+
+ totalDeleted += deleted;
+ iterations++;
+
+ if (deleted < DELETE_BATCH_SIZE) break;
+ }
+
+ if (iterations >= MAX_ITERATIONS) {
+ logger.warn(
+ { totalDeleted, iterations, cutoffDate: cutoff },
+ "Plugin log retention hit iteration limit; some logs may remain",
+ );
+ }
+
+ if (totalDeleted > 0) {
+ logger.info({ totalDeleted, retentionDays }, "Pruned expired plugin logs");
+ }
+
+ return totalDeleted;
+}
+
+/**
+ * Start a periodic plugin log cleanup interval.
+ *
+ * @param db - Database connection
+ * @param intervalMs - How often to run (default: 1 hour)
+ * @param retentionDays - How many days of logs to keep (default: 7)
+ * @returns A cleanup function that stops the interval
+ */
+export function startPluginLogRetention(
+ db: Db,
+ intervalMs: number = 60 * 60 * 1_000,
+ retentionDays: number = DEFAULT_RETENTION_DAYS,
+): () => void {
+ const timer = setInterval(() => {
+ prunePluginLogs(db, retentionDays).catch((err) => {
+ logger.warn({ err }, "Plugin log retention sweep failed");
+ });
+ }, intervalMs);
+
+ // Run once immediately on startup
+ prunePluginLogs(db, retentionDays).catch((err) => {
+ logger.warn({ err }, "Initial plugin log retention sweep failed");
+ });
+
+ return () => clearInterval(timer);
+}
diff --git a/server/src/services/plugin-manifest-validator.ts b/server/src/services/plugin-manifest-validator.ts
new file mode 100644
index 0000000000..9af6b61c3c
--- /dev/null
+++ b/server/src/services/plugin-manifest-validator.ts
@@ -0,0 +1,163 @@
+/**
+ * PluginManifestValidator — schema validation for plugin manifest files.
+ *
+ * Uses the shared Zod schema (`pluginManifestV1Schema`) to validate
+ * manifest payloads. Provides both a safe `parse()` variant (returns
+ * a result union) and a throwing `parseOrThrow()` for HTTP error
+ * propagation at install time.
+ *
+ * @see PLUGIN_SPEC.md §10 — Plugin Manifest
+ * @see packages/shared/src/validators/plugin.ts — Zod schema definition
+ */
+import { pluginManifestV1Schema } from "@paperclipai/shared";
+import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";
+import { PLUGIN_API_VERSION } from "@paperclipai/shared";
+import { badRequest } from "../errors.js";
+
+// ---------------------------------------------------------------------------
+// Supported manifest API versions
+// ---------------------------------------------------------------------------
+
+/**
+ * The set of plugin API versions this host can accept.
+ * When a new API version is introduced, add it here. Old versions should be
+ * retained until the host drops support for them.
+ */
+const SUPPORTED_VERSIONS = [PLUGIN_API_VERSION] as const;
+
+// ---------------------------------------------------------------------------
+// Parse result types
+// ---------------------------------------------------------------------------
+
+/**
+ * Successful parse result.
+ */
+export interface ManifestParseSuccess {
+ success: true;
+ manifest: PaperclipPluginManifestV1;
+}
+
+/**
+ * Failed parse result. `errors` is a human-readable description of what went
+ * wrong; `details` is the raw Zod error list for programmatic inspection.
+ */
+export interface ManifestParseFailure {
+ success: false;
+ errors: string;
+ details: Array<{ path: (string | number)[]; message: string }>;
+}
+
+/** Union of parse outcomes. */
+export type ManifestParseResult = ManifestParseSuccess | ManifestParseFailure;
+
+// ---------------------------------------------------------------------------
+// PluginManifestValidator interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Service for parsing and validating plugin manifests.
+ *
+ * @see PLUGIN_SPEC.md §10 — Plugin Manifest
+ */
+export interface PluginManifestValidator {
+ /**
+ * Try to parse `input` as a plugin manifest.
+ *
+ * Returns a {@link ManifestParseSuccess} when the input passes all
+ * validation rules, or a {@link ManifestParseFailure} with human-readable
+ * error messages when it does not.
+ *
+ * This is the "safe" variant — it never throws.
+ */
+ parse(input: unknown): ManifestParseResult;
+
+ /**
+ * Parse `input` as a plugin manifest, throwing a 400 HttpError on failure.
+ *
+ * Use this at install time when an invalid manifest should surface as an
+ * HTTP error to the caller.
+ *
+ * @throws {HttpError} 400 Bad Request if the manifest is invalid.
+ */
+ parseOrThrow(input: unknown): PaperclipPluginManifestV1;
+
+ /**
+ * Return the list of plugin API versions supported by this host.
+ *
+ * Callers can use this to present the supported version range to operators
+ * or to decide whether a candidate plugin can be installed.
+ */
+ getSupportedVersions(): readonly number[];
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a {@link PluginManifestValidator}.
+ *
+ * Usage:
+ * ```ts
+ * const validator = pluginManifestValidator();
+ *
+ * // Safe parse — inspect the result
+ * const result = validator.parse(rawManifest);
+ * if (!result.success) {
+ * console.error(result.errors);
+ * return;
+ * }
+ * const manifest = result.manifest;
+ *
+ * // Throwing parse — use at install time
+ * const manifest = validator.parseOrThrow(rawManifest);
+ *
+ * // Check supported versions
+ * const versions = validator.getSupportedVersions(); // [1]
+ * ```
+ */
+export function pluginManifestValidator(): PluginManifestValidator {
+ return {
+ parse(input: unknown): ManifestParseResult {
+ const result = pluginManifestV1Schema.safeParse(input);
+
+ if (result.success) {
+ return {
+ success: true,
+ manifest: result.data as PaperclipPluginManifestV1,
+ };
+ }
+
+ const details = result.error.errors.map((issue) => ({
+ path: issue.path,
+ message: issue.message,
+ }));
+
+ const errors = details
+ .map(({ path, message }) =>
+ path.length > 0 ? `${path.join(".")}: ${message}` : message,
+ )
+ .join("; ");
+
+ return {
+ success: false,
+ errors,
+ details,
+ };
+ },
+
+ parseOrThrow(input: unknown): PaperclipPluginManifestV1 {
+ const result = this.parse(input);
+
+ if (!result.success) {
+ throw badRequest(`Invalid plugin manifest: ${result.errors}`, result.details);
+ }
+
+ return result.manifest;
+ },
+
+ getSupportedVersions(): readonly number[] {
+ return SUPPORTED_VERSIONS;
+ },
+ };
+}
diff --git a/server/src/services/plugin-registry.ts b/server/src/services/plugin-registry.ts
new file mode 100644
index 0000000000..eb4495a5f8
--- /dev/null
+++ b/server/src/services/plugin-registry.ts
@@ -0,0 +1,963 @@
+import { asc, eq, ne, sql, and, inArray } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import {
+ plugins,
+ companies,
+ pluginConfig,
+ pluginCompanySettings,
+ pluginEntities,
+ pluginJobs,
+ pluginJobRuns,
+ pluginWebhookDeliveries,
+} from "@paperclipai/db";
+import type {
+ PaperclipPluginManifestV1,
+ PluginStatus,
+ InstallPlugin,
+ UpdatePluginStatus,
+ UpsertPluginConfig,
+ PatchPluginConfig,
+ PluginCompanySettings,
+ CompanyPluginAvailability,
+ UpsertPluginCompanySettings,
+ UpdateCompanyPluginAvailability,
+ PluginEntityRecord,
+ PluginEntityQuery,
+ PluginJobRecord,
+ PluginJobRunRecord,
+ PluginWebhookDeliveryRecord,
+ PluginJobStatus,
+ PluginJobRunStatus,
+ PluginJobRunTrigger,
+ PluginWebhookDeliveryStatus,
+} from "@paperclipai/shared";
+import { conflict, notFound } from "../errors.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect if a Postgres error is a unique-constraint violation on the
+ * `plugins_plugin_key_idx` unique index.
+ */
+function isPluginKeyConflict(error: unknown): boolean {
+ if (typeof error !== "object" || error === null) return false;
+ const err = error as { code?: string; constraint?: string; constraint_name?: string };
+ const constraint = err.constraint ?? err.constraint_name;
+ return err.code === "23505" && constraint === "plugins_plugin_key_idx";
+}
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+/**
+ * PluginRegistry – CRUD operations for the `plugins` and `plugin_config`
+ * tables. Follows the same factory-function pattern used by the rest of
+ * the Paperclip service layer.
+ *
+ * This is the lowest-level persistence layer for plugins. Higher-level
+ * concerns such as lifecycle state-machine enforcement and capability
+ * gating are handled by {@link pluginLifecycleManager} and
+ * {@link pluginCapabilityValidator} respectively.
+ *
+ * @see PLUGIN_SPEC.md §21.3 — Required Tables
+ */
+export function pluginRegistryService(db: Db) {
+ // -----------------------------------------------------------------------
+ // Internal helpers
+ // -----------------------------------------------------------------------
+
+ async function getById(id: string) {
+ return db
+ .select()
+ .from(plugins)
+ .where(eq(plugins.id, id))
+ .then((rows) => rows[0] ?? null);
+ }
+
+ async function getByKey(pluginKey: string) {
+ return db
+ .select()
+ .from(plugins)
+ .where(eq(plugins.pluginKey, pluginKey))
+ .then((rows) => rows[0] ?? null);
+ }
+
+ async function nextInstallOrder(): Promise<number> {
+ const result = await db
+ .select({ maxOrder: sql<number>`coalesce(max(${plugins.installOrder}), 0)` })
+ .from(plugins);
+ return (result[0]?.maxOrder ?? 0) + 1;
+ }
+
+ /**
+ * Load the persisted company override row for a plugin, if one exists.
+ *
+ * Missing rows are meaningful: the company inherits the default-enabled
+ * behavior and the caller should treat the plugin as available.
+ */
+ async function getCompanySettingsRow(companyId: string, pluginId: string) {
+ return db
+ .select()
+ .from(pluginCompanySettings)
+ .where(and(
+ eq(pluginCompanySettings.companyId, companyId),
+ eq(pluginCompanySettings.pluginId, pluginId),
+ ))
+ .then((rows) => rows[0] ?? null);
+ }
+
+ /**
+ * Normalize registry records into the API response returned by company
+ * plugin availability routes.
+ *
+ * The key business rule is captured here: plugins are enabled for a company
+ * unless an explicit `plugin_company_settings.enabled = false` override says
+ * otherwise.
+ */
+ function toCompanyAvailability(
+ companyId: string,
+ plugin: Awaited<ReturnType<typeof getById>>,
+ settings: PluginCompanySettings | null,
+ ): CompanyPluginAvailability {
+ if (!plugin) {
+ throw notFound("Plugin not found");
+ }
+
+ return {
+ companyId,
+ pluginId: plugin.id,
+ pluginKey: plugin.pluginKey,
+ pluginDisplayName: plugin.manifestJson.displayName,
+ pluginStatus: plugin.status,
+ available: settings?.enabled ?? true,
+ settingsJson: settings?.settingsJson ?? {},
+ lastError: settings?.lastError ?? null,
+ createdAt: settings?.createdAt ?? null,
+ updatedAt: settings?.updatedAt ?? null,
+ };
+ }
+
+ // -----------------------------------------------------------------------
+ // Public API
+ // -----------------------------------------------------------------------
+
+ return {
+ // ----- Read -----------------------------------------------------------
+
+ /** List all registered plugins ordered by install order. */
+ list: () =>
+ db
+ .select()
+ .from(plugins)
+ .orderBy(asc(plugins.installOrder)),
+
+ /**
+ * List installed plugins (excludes soft-deleted/uninstalled).
+ * Use for Plugin Manager and default API list so uninstalled plugins do not appear.
+ */
+ listInstalled: () =>
+ db
+ .select()
+ .from(plugins)
+ .where(ne(plugins.status, "uninstalled"))
+ .orderBy(asc(plugins.installOrder)),
+
+ /** List plugins filtered by status. */
+ listByStatus: (status: PluginStatus) =>
+ db
+ .select()
+ .from(plugins)
+ .where(eq(plugins.status, status))
+ .orderBy(asc(plugins.installOrder)),
+
+ /** Get a single plugin by primary key. */
+ getById,
+
+ /** Get a single plugin by its unique `pluginKey`. */
+ getByKey,
+
+ // ----- Install / Register --------------------------------------------
+
+ /**
+ * Register (install) a new plugin.
+ *
+ * The caller is expected to have already resolved and validated the
+ * manifest from the package. This method persists the plugin row and
+ * assigns the next install order.
+ */
+ install: async (input: InstallPlugin, manifest: PaperclipPluginManifestV1) => {
+ const existing = await getByKey(manifest.id);
+ if (existing) {
+ if (existing.status !== "uninstalled") {
+ throw conflict(`Plugin already installed: ${manifest.id}`);
+ }
+
+ // Reinstall after soft-delete: reactivate the existing row so plugin-scoped
+ // data and references remain stable across uninstall/reinstall cycles.
+ return db
+ .update(plugins)
+ .set({
+ packageName: input.packageName,
+ packagePath: input.packagePath ?? null,
+ version: manifest.version,
+ apiVersion: manifest.apiVersion,
+ categories: manifest.categories,
+ manifestJson: manifest,
+ status: "installed" as PluginStatus,
+ lastError: null,
+ updatedAt: new Date(),
+ })
+ .where(eq(plugins.id, existing.id))
+ .returning()
+ .then((rows) => rows[0] ?? null);
+ }
+
+ const installOrder = await nextInstallOrder();
+
+ try {
+ const rows = await db
+ .insert(plugins)
+ .values({
+ pluginKey: manifest.id,
+ packageName: input.packageName,
+ version: manifest.version,
+ apiVersion: manifest.apiVersion,
+ categories: manifest.categories,
+ manifestJson: manifest,
+ status: "installed" as PluginStatus,
+ installOrder,
+ packagePath: input.packagePath ?? null,
+ })
+ .returning();
+ return rows[0];
+ } catch (error) {
+ if (isPluginKeyConflict(error)) {
+ throw conflict(`Plugin already installed: ${manifest.id}`);
+ }
+ throw error;
+ }
+ },
+
+ // ----- Update ---------------------------------------------------------
+
+ /**
+ * Update a plugin's manifest and version (e.g. on upgrade).
+ * The plugin must already exist.
+ */
+ update: async (
+ id: string,
+ data: {
+ packageName?: string;
+ version?: string;
+ manifest?: PaperclipPluginManifestV1;
+ },
+ ) => {
+ const plugin = await getById(id);
+ if (!plugin) throw notFound("Plugin not found");
+
+ const setClause: Partial<typeof plugins.$inferInsert> & { updatedAt: Date } = {
+ updatedAt: new Date(),
+ };
+ if (data.packageName !== undefined) setClause.packageName = data.packageName;
+ if (data.version !== undefined) setClause.version = data.version;
+ if (data.manifest !== undefined) {
+ setClause.manifestJson = data.manifest;
+ setClause.apiVersion = data.manifest.apiVersion;
+ setClause.categories = data.manifest.categories;
+ }
+
+ return db
+ .update(plugins)
+ .set(setClause)
+ .where(eq(plugins.id, id))
+ .returning()
+ .then((rows) => rows[0] ?? null);
+ },
+
+ // ----- Status ---------------------------------------------------------
+
+ /** Update a plugin's lifecycle status and optional error message. */
+ updateStatus: async (id: string, input: UpdatePluginStatus) => {
+ const plugin = await getById(id);
+ if (!plugin) throw notFound("Plugin not found");
+
+ return db
+ .update(plugins)
+ .set({
+ status: input.status,
+ lastError: input.lastError ?? null,
+ updatedAt: new Date(),
+ })
+ .where(eq(plugins.id, id))
+ .returning()
+ .then((rows) => rows[0] ?? null);
+ },
+
+ // ----- Uninstall / Remove --------------------------------------------
+
+ /**
+ * Uninstall a plugin.
+ *
+ * When `removeData` is true the plugin row (and cascaded config) is
+ * hard-deleted. Otherwise the status is set to `"uninstalled"` for
+ * a soft-delete that preserves the record.
+ */
+ uninstall: async (id: string, removeData = false) => {
+ const plugin = await getById(id);
+ if (!plugin) throw notFound("Plugin not found");
+
+ if (removeData) {
+ // Hard delete – plugin_config cascades via FK onDelete
+ return db
+ .delete(plugins)
+ .where(eq(plugins.id, id))
+ .returning()
+ .then((rows) => rows[0] ?? null);
+ }
+
+ // Soft delete – mark as uninstalled
+ return db
+ .update(plugins)
+ .set({
+ status: "uninstalled" as PluginStatus,
+ updatedAt: new Date(),
+ })
+ .where(eq(plugins.id, id))
+ .returning()
+ .then((rows) => rows[0] ?? null);
+ },
+
+ // ----- Config ---------------------------------------------------------
+
+ /** Retrieve a plugin's instance configuration. */
+ getConfig: (pluginId: string) =>
+ db
+ .select()
+ .from(pluginConfig)
+ .where(eq(pluginConfig.pluginId, pluginId))
+ .then((rows) => rows[0] ?? null),
+
+ /**
+ * Create or fully replace a plugin's instance configuration.
+ * If a config row already exists for the plugin it is replaced;
+ * otherwise a new row is inserted.
+ */
+ upsertConfig: async (pluginId: string, input: UpsertPluginConfig) => {
+ const plugin = await getById(pluginId);
+ if (!plugin) throw notFound("Plugin not found");
+
+ const existing = await db
+ .select()
+ .from(pluginConfig)
+ .where(eq(pluginConfig.pluginId, pluginId))
+ .then((rows) => rows[0] ?? null);
+
+ if (existing) {
+ return db
+ .update(pluginConfig)
+ .set({
+ configJson: input.configJson,
+ lastError: null,
+ updatedAt: new Date(),
+ })
+ .where(eq(pluginConfig.pluginId, pluginId))
+ .returning()
+ .then((rows) => rows[0]);
+ }
+
+ return db
+ .insert(pluginConfig)
+ .values({
+ pluginId,
+ configJson: input.configJson,
+ })
+ .returning()
+ .then((rows) => rows[0]);
+ },
+
+ /**
+ * Partially update a plugin's instance configuration via shallow merge.
+ * If no config row exists yet one is created with the supplied values.
+ */
+ patchConfig: async (pluginId: string, input: PatchPluginConfig) => {
+ const plugin = await getById(pluginId);
+ if (!plugin) throw notFound("Plugin not found");
+
+ const existing = await db
+ .select()
+ .from(pluginConfig)
+ .where(eq(pluginConfig.pluginId, pluginId))
+ .then((rows) => rows[0] ?? null);
+
+ if (existing) {
+ const merged = { ...existing.configJson, ...input.configJson };
+ return db
+ .update(pluginConfig)
+ .set({
+ configJson: merged,
+ lastError: null,
+ updatedAt: new Date(),
+ })
+ .where(eq(pluginConfig.pluginId, pluginId))
+ .returning()
+ .then((rows) => rows[0]);
+ }
+
+ return db
+ .insert(pluginConfig)
+ .values({
+ pluginId,
+ configJson: input.configJson,
+ })
+ .returning()
+ .then((rows) => rows[0]);
+ },
+
+ // ----- Company-scoped settings ----------------------------------------
+
+ /** Retrieve a plugin's company-scoped settings row, if any. */
+ getCompanySettings: (companyId: string, pluginId: string) =>
+ getCompanySettingsRow(companyId, pluginId),
+
+ /** Create or replace the company-scoped settings row for a plugin. */
+ upsertCompanySettings: async (
+ companyId: string,
+ pluginId: string,
+ input: UpsertPluginCompanySettings,
+ ) => {
+ const plugin = await getById(pluginId);
+ if (!plugin) throw notFound("Plugin not found");
+
+ const existing = await getCompanySettingsRow(companyId, pluginId);
+ if (existing) {
+ return db
+ .update(pluginCompanySettings)
+ .set({
+ enabled: true,
+ settingsJson: input.settingsJson ?? {},
+ lastError: input.lastError ?? null,
+ updatedAt: new Date(),
+ })
+ .where(eq(pluginCompanySettings.id, existing.id))
+ .returning()
+ .then((rows) => rows[0]);
+ }
+
+ return db
+ .insert(pluginCompanySettings)
+ .values({
+ companyId,
+ pluginId,
+ enabled: true,
+ settingsJson: input.settingsJson ?? {},
+ lastError: input.lastError ?? null,
+ })
+ .returning()
+ .then((rows) => rows[0]);
+ },
+
+ /** Delete the company-scoped settings row for a plugin if it exists. */
+ deleteCompanySettings: async (companyId: string, pluginId: string) => {
+ const plugin = await getById(pluginId);
+ if (!plugin) throw notFound("Plugin not found");
+
+ const existing = await getCompanySettingsRow(companyId, pluginId);
+ if (!existing) return null;
+
+ return db
+ .delete(pluginCompanySettings)
+ .where(eq(pluginCompanySettings.id, existing.id))
+ .returning()
+ .then((rows) => rows[0] ?? null);
+ },
+
+ /** List normalized company-plugin availability records across installed plugins. */
+ listCompanyAvailability: async (
+ companyId: string,
+ filter?: { available?: boolean },
+ ) => {
+ const installed = await db
+ .select()
+ .from(plugins)
+ .where(ne(plugins.status, "uninstalled"))
+ .orderBy(asc(plugins.installOrder));
+
+ const settingsRows = await db
+ .select()
+ .from(pluginCompanySettings)
+ .where(eq(pluginCompanySettings.companyId, companyId));
+
+ const settingsByPluginId = new Map(settingsRows.map((row) => [row.pluginId, row]));
+ const availability = installed.map((plugin) => {
+ const row = settingsByPluginId.get(plugin.id) ?? null;
+ return {
+ ...toCompanyAvailability(companyId, plugin, row),
+ };
+ });
+
+ if (filter?.available === undefined) return availability;
+ return availability.filter((item) => item.available === filter.available);
+ },
+
+ /**
+ * Batch-check which companies have this plugin explicitly disabled.
+ * Returns a Set of companyIds where `enabled = false`. Companies with
+ * no settings row default to enabled, so they are NOT in the result set.
+ */
+ getDisabledCompanyIds: async (companyIds: string[], pluginId: string): Promise<Set<string>> => {
+ if (companyIds.length === 0) return new Set();
+ const rows = await db
+ .select({
+ companyId: pluginCompanySettings.companyId,
+ enabled: pluginCompanySettings.enabled,
+ })
+ .from(pluginCompanySettings)
+ .where(and(
+ inArray(pluginCompanySettings.companyId, companyIds),
+ eq(pluginCompanySettings.pluginId, pluginId),
+ ));
+ const disabled = new Set<string>();
+ for (const row of rows) {
+ if (!row.enabled) disabled.add(row.companyId);
+ }
+ return disabled;
+ },
+
+ /** Get the normalized availability record for a single company/plugin pair. */
+ getCompanyAvailability: async (companyId: string, pluginId: string) => {
+ const plugin = await getById(pluginId);
+ if (!plugin || plugin.status === "uninstalled") return null;
+
+ const settings = await getCompanySettingsRow(companyId, pluginId);
+ return toCompanyAvailability(companyId, plugin, settings);
+ },
+
+ /** Update normalized company availability, persisting or deleting settings as needed. */
+ updateCompanyAvailability: async (
+ companyId: string,
+ pluginId: string,
+ input: UpdateCompanyPluginAvailability,
+ ) => {
+ const plugin = await getById(pluginId);
+ if (!plugin || plugin.status === "uninstalled") throw notFound("Plugin not found");
+
+ const existing = await getCompanySettingsRow(companyId, pluginId);
+
+ if (!input.available) {
+ const row = await (existing
+ ? db
+ .update(pluginCompanySettings)
+ .set({
+ enabled: false,
+ settingsJson: input.settingsJson ?? existing.settingsJson,
+ lastError: input.lastError ?? existing.lastError ?? null,
+ updatedAt: new Date(),
+ })
+ .where(eq(pluginCompanySettings.id, existing.id))
+ .returning()
+ .then((rows) => rows[0])
+ : db
+ .insert(pluginCompanySettings)
+ .values({
+ companyId,
+ pluginId,
+ enabled: false,
+ settingsJson: input.settingsJson ?? {},
+ lastError: input.lastError ?? null,
+ })
+ .returning()
+ .then((rows) => rows[0]));
+
+ return {
+ ...toCompanyAvailability(companyId, plugin, row),
+ };
+ }
+
+ const row = await (existing
+ ? db
+ .update(pluginCompanySettings)
+ .set({
+ enabled: true,
+ settingsJson: input.settingsJson ?? existing.settingsJson,
+ lastError: input.lastError ?? existing.lastError ?? null,
+ updatedAt: new Date(),
+ })
+ .where(eq(pluginCompanySettings.id, existing.id))
+ .returning()
+ .then((rows) => rows[0])
+ : db
+ .insert(pluginCompanySettings)
+ .values({
+ companyId,
+ pluginId,
+ enabled: true,
+ settingsJson: input.settingsJson ?? {},
+ lastError: input.lastError ?? null,
+ })
+ .returning()
+ .then((rows) => rows[0]));
+
+ return {
+ ...toCompanyAvailability(companyId, plugin, row),
+ };
+ },
+
+ /**
+ * Ensure all companies have an explicit enabled row for this plugin.
+ *
+ * Company availability defaults to enabled when no row exists, but this
+ * helper persists explicit `enabled=true` rows so newly-installed plugins
+ * appear as enabled immediately and consistently in company-scoped views.
+ */
+ seedEnabledForAllCompanies: async (pluginId: string) => {
+ const plugin = await getById(pluginId);
+ if (!plugin || plugin.status === "uninstalled") throw notFound("Plugin not found");
+
+ const companyRows = await db
+ .select({ id: companies.id })
+ .from(companies);
+
+ if (companyRows.length === 0) return 0;
+
+ const now = new Date();
+ await db
+ .insert(pluginCompanySettings)
+ .values(
+ companyRows.map((company) => ({
+ companyId: company.id,
+ pluginId,
+ enabled: true,
+ settingsJson: {},
+ lastError: null,
+ createdAt: now,
+ updatedAt: now,
+ })),
+ )
+ .onConflictDoNothing({
+ target: [pluginCompanySettings.companyId, pluginCompanySettings.pluginId],
+ });
+
+ return companyRows.length;
+ },
+
+ /**
+ * Record an error against a plugin's config (e.g. validation failure
+ * against the plugin's instanceConfigSchema).
+ */
+ setConfigError: async (pluginId: string, lastError: string | null) => {
+ const rows = await db
+ .update(pluginConfig)
+ .set({ lastError, updatedAt: new Date() })
+ .where(eq(pluginConfig.pluginId, pluginId))
+ .returning();
+
+ if (rows.length === 0) throw notFound("Plugin config not found");
+ return rows[0];
+ },
+
+ /** Delete a plugin's config row. */
+ deleteConfig: async (pluginId: string) => {
+ const rows = await db
+ .delete(pluginConfig)
+ .where(eq(pluginConfig.pluginId, pluginId))
+ .returning();
+
+ return rows[0] ?? null;
+ },
+
+ // ----- Entities -------------------------------------------------------
+
+ /**
+ * List persistent entity mappings owned by a specific plugin, with filtering and pagination.
+ *
+ * @param pluginId - The UUID of the plugin.
+ * @param query - Optional filters (type, externalId) and pagination (limit, offset).
+ * @returns A list of matching `PluginEntityRecord` objects.
+ */
+ listEntities: (pluginId: string, query?: PluginEntityQuery) => {
+ const conditions = [eq(pluginEntities.pluginId, pluginId)];
+ if (query?.entityType) conditions.push(eq(pluginEntities.entityType, query.entityType));
+ if (query?.externalId) conditions.push(eq(pluginEntities.externalId, query.externalId));
+
+ return db
+ .select()
+ .from(pluginEntities)
+ .where(and(...conditions))
+ .orderBy(asc(pluginEntities.createdAt))
+ .limit(query?.limit ?? 100)
+ .offset(query?.offset ?? 0);
+ },
+
+ /**
+ * Look up a plugin-owned entity mapping by its external identifier.
+ *
+ * @param pluginId - The UUID of the plugin.
+ * @param entityType - The type of entity (e.g., 'project', 'issue').
+ * @param externalId - The identifier in the external system.
+ * @returns The matching `PluginEntityRecord` or null.
+ */
+ getEntityByExternalId: (
+ pluginId: string,
+ entityType: string,
+ externalId: string,
+ ) =>
+ db
+ .select()
+ .from(pluginEntities)
+ .where(
+ and(
+ eq(pluginEntities.pluginId, pluginId),
+ eq(pluginEntities.entityType, entityType),
+ eq(pluginEntities.externalId, externalId),
+ ),
+ )
+ .then((rows) => rows[0] ?? null),
+
+ /**
+ * Create or update a persistent mapping between a Paperclip object and an
+ * external entity.
+ *
+ * @param pluginId - The UUID of the plugin.
+ * @param input - The entity data to persist.
+ * @returns The newly created or updated `PluginEntityRecord`.
+ */
+ upsertEntity: async (
+ pluginId: string,
+ input: Omit<typeof pluginEntities.$inferInsert, "id" | "pluginId" | "createdAt" | "updatedAt">,
+ ) => {
+ // Drizzle doesn't support pg-specific onConflictDoUpdate easily in the insert() call
+ // with complex where clauses, so we do it manually.
+ const existing = await db
+ .select()
+ .from(pluginEntities)
+ .where(
+ and(
+ eq(pluginEntities.pluginId, pluginId),
+ eq(pluginEntities.entityType, input.entityType),
+ eq(pluginEntities.externalId, input.externalId ?? ""),
+ ),
+ )
+ .then((rows) => rows[0] ?? null);
+
+ if (existing) {
+ return db
+ .update(pluginEntities)
+ .set({
+ ...input,
+ updatedAt: new Date(),
+ })
+ .where(eq(pluginEntities.id, existing.id))
+ .returning()
+ .then((rows) => rows[0]);
+ }
+
+ return db
+ .insert(pluginEntities)
+ .values({
+ ...input,
+ pluginId,
+ } as any)
+ .returning()
+ .then((rows) => rows[0]);
+ },
+
+ /**
+ * Delete a specific plugin-owned entity mapping by its internal UUID.
+ *
+ * @param id - The UUID of the entity record.
+ * @returns The deleted record, or null if not found.
+ */
+ deleteEntity: async (id: string) => {
+ const rows = await db
+ .delete(pluginEntities)
+ .where(eq(pluginEntities.id, id))
+ .returning();
+ return rows[0] ?? null;
+ },
+
+ // ----- Jobs -----------------------------------------------------------
+
+ /**
+ * List all scheduled jobs registered for a specific plugin.
+ *
+ * @param pluginId - The UUID of the plugin.
+ * @returns A list of `PluginJobRecord` objects.
+ */
+ listJobs: (pluginId: string) =>
+ db
+ .select()
+ .from(pluginJobs)
+ .where(eq(pluginJobs.pluginId, pluginId))
+ .orderBy(asc(pluginJobs.jobKey)),
+
+ /**
+ * Look up a plugin job by its unique job key.
+ *
+ * @param pluginId - The UUID of the plugin.
+ * @param jobKey - The key defined in the plugin manifest.
+ * @returns The matching `PluginJobRecord` or null.
+ */
+ getJobByKey: (pluginId: string, jobKey: string) =>
+ db
+ .select()
+ .from(pluginJobs)
+ .where(and(eq(pluginJobs.pluginId, pluginId), eq(pluginJobs.jobKey, jobKey)))
+ .then((rows) => rows[0] ?? null),
+
+ /**
+ * Register or update a scheduled job for a plugin.
+ *
+ * @param pluginId - The UUID of the plugin.
+ * @param jobKey - The unique key for the job.
+ * @param input - The schedule (cron) and optional status.
+ * @returns The updated or created `PluginJobRecord`.
+ */
+ upsertJob: async (
+ pluginId: string,
+ jobKey: string,
+ input: { schedule: string; status?: PluginJobStatus },
+ ) => {
+ const existing = await db
+ .select()
+ .from(pluginJobs)
+ .where(and(eq(pluginJobs.pluginId, pluginId), eq(pluginJobs.jobKey, jobKey)))
+ .then((rows) => rows[0] ?? null);
+
+ if (existing) {
+ return db
+ .update(pluginJobs)
+ .set({
+ schedule: input.schedule,
+ status: input.status ?? existing.status,
+ updatedAt: new Date(),
+ })
+ .where(eq(pluginJobs.id, existing.id))
+ .returning()
+ .then((rows) => rows[0]);
+ }
+
+ return db
+ .insert(pluginJobs)
+ .values({
+ pluginId,
+ jobKey,
+ schedule: input.schedule,
+ status: input.status ?? "active",
+ })
+ .returning()
+ .then((rows) => rows[0]);
+ },
+
+ /**
+ * Record the start of a specific job execution.
+ *
+ * @param pluginId - The UUID of the plugin.
+ * @param jobId - The UUID of the parent job record.
+ * @param trigger - What triggered this run (e.g., 'schedule', 'manual').
+ * @returns The newly created `PluginJobRunRecord` in 'pending' status.
+ */
+ createJobRun: async (
+ pluginId: string,
+ jobId: string,
+ trigger: PluginJobRunTrigger,
+ ) => {
+ return db
+ .insert(pluginJobRuns)
+ .values({
+ pluginId,
+ jobId,
+ trigger,
+ status: "pending",
+ })
+ .returning()
+ .then((rows) => rows[0]);
+ },
+
+ /**
+ * Update the status, duration, and logs of a job execution record.
+ *
+ * @param runId - The UUID of the job run.
+ * @param input - The update fields (status, error, duration, etc.).
+ * @returns The updated `PluginJobRunRecord`.
+ */
+ updateJobRun: async (
+ runId: string,
+ input: {
+ status: PluginJobRunStatus;
+ durationMs?: number;
+ error?: string;
+ logs?: string[];
+ startedAt?: Date;
+ finishedAt?: Date;
+ },
+ ) => {
+ return db
+ .update(pluginJobRuns)
+ .set(input)
+ .where(eq(pluginJobRuns.id, runId))
+ .returning()
+ .then((rows) => rows[0] ?? null);
+ },
+
+ // ----- Webhooks -------------------------------------------------------
+
+ /**
+ * Create a record for an incoming webhook delivery.
+ *
+ * @param pluginId - The UUID of the receiving plugin.
+ * @param webhookKey - The endpoint key defined in the manifest.
+ * @param input - The payload, headers, and optional external ID.
+ * @returns The newly created `PluginWebhookDeliveryRecord` in 'pending' status.
+ */
+ createWebhookDelivery: async (
+ pluginId: string,
+ webhookKey: string,
+ input: {
+ externalId?: string;
+ payload: Record<string, unknown>;
+ headers?: Record<string, string>;
+ },
+ ) => {
+ return db
+ .insert(pluginWebhookDeliveries)
+ .values({
+ pluginId,
+ webhookKey,
+ externalId: input.externalId,
+ payload: input.payload,
+ headers: input.headers ?? {},
+ status: "pending",
+ })
+ .returning()
+ .then((rows) => rows[0]);
+ },
+
+ /**
+ * Update the status and processing metrics of a webhook delivery.
+ *
+ * @param deliveryId - The UUID of the delivery record.
+ * @param input - The update fields (status, error, duration, etc.).
+ * @returns The updated `PluginWebhookDeliveryRecord`.
+ */
+ updateWebhookDelivery: async (
+ deliveryId: string,
+ input: {
+ status: PluginWebhookDeliveryStatus;
+ durationMs?: number;
+ error?: string;
+ startedAt?: Date;
+ finishedAt?: Date;
+ },
+ ) => {
+ return db
+ .update(pluginWebhookDeliveries)
+ .set(input)
+ .where(eq(pluginWebhookDeliveries.id, deliveryId))
+ .returning()
+ .then((rows) => rows[0] ?? null);
+ },
+ };
+}
diff --git a/server/src/services/plugin-runtime-sandbox.ts b/server/src/services/plugin-runtime-sandbox.ts
new file mode 100644
index 0000000000..0ffe4a3f26
--- /dev/null
+++ b/server/src/services/plugin-runtime-sandbox.ts
@@ -0,0 +1,221 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import vm from "node:vm";
+import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";
+import type { PluginCapabilityValidator } from "./plugin-capability-validator.js";
+
+export class PluginSandboxError extends Error {
+ constructor(message: string) {
+ super(message);
+ this.name = "PluginSandboxError";
+ }
+}
+
+/**
+ * Sandbox runtime options used when loading a plugin worker module.
+ *
+ * `allowedModuleSpecifiers` controls which bare module specifiers are permitted.
+ * `allowedModules` provides concrete host-provided bindings for those specifiers.
+ */
+export interface PluginSandboxOptions {
+ entrypointPath: string;
+ allowedModuleSpecifiers?: ReadonlySet<string>;
+ allowedModules?: Readonly<Record<string, Record<string, unknown>>>;
+ allowedGlobals?: Record<string, unknown>;
+ timeoutMs?: number;
+}
+
+/**
+ * Operation-level runtime gate for plugin host API calls.
+ * Every host operation must be checked against manifest capabilities before execution.
+ */
+export interface CapabilityScopedInvoker {
+ invoke<T>(operation: string, fn: () => Promise<T> | T): Promise<T>;
+}
+
+interface LoadedModule {
+ namespace: Record<string, unknown>;
+}
+
+const DEFAULT_TIMEOUT_MS = 2_000;
+const MODULE_PATH_SUFFIXES = ["", ".js", ".mjs", ".cjs", "/index.js", "/index.mjs", "/index.cjs"];
+const DEFAULT_GLOBALS: Record<string, unknown> = {
+ console,
+ setTimeout,
+ clearTimeout,
+ setInterval,
+ clearInterval,
+ URL,
+ URLSearchParams,
+ TextEncoder,
+ TextDecoder,
+ AbortController,
+ AbortSignal,
+};
+
+export function createCapabilityScopedInvoker(
+ manifest: PaperclipPluginManifestV1,
+ validator: PluginCapabilityValidator,
+): CapabilityScopedInvoker {
+ return {
+ async invoke<T>(operation: string, fn: () => Promise<T> | T): Promise<T> {
+ validator.assertOperation(manifest, operation);
+ return await fn();
+ },
+ };
+}
+
+/**
+ * Load a CommonJS plugin module in a VM context with explicit module import allow-listing.
+ *
+ * Security properties:
+ * - no implicit access to host globals like `process`
+ * - no unrestricted built-in module imports
+ * - relative imports are resolved only inside the plugin root directory
+ */
+export async function loadPluginModuleInSandbox(
+ options: PluginSandboxOptions,
+): Promise<LoadedModule> {
+ const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+ const allowedSpecifiers = options.allowedModuleSpecifiers ?? new Set<string>();
+ const entrypointPath = path.resolve(options.entrypointPath);
+ const pluginRoot = path.dirname(entrypointPath);
+
+ const context = vm.createContext({
+ ...DEFAULT_GLOBALS,
+ ...options.allowedGlobals,
+ });
+
+ const moduleCache = new Map<string, Record<string, unknown>>();
+ const allowedModules = options.allowedModules ?? {};
+
+ const realPluginRoot = realpathSync(pluginRoot);
+
+ const loadModuleSync = (modulePath: string): Record<string, unknown> => {
+ const resolvedPath = resolveModulePathSync(path.resolve(modulePath));
+ const realPath = realpathSync(resolvedPath);
+
+ if (!isWithinRoot(realPath, realPluginRoot)) {
+ throw new PluginSandboxError(
+ `Import '${modulePath}' escapes plugin root and is not allowed`,
+ );
+ }
+
+ const cached = moduleCache.get(realPath);
+ if (cached) return cached;
+
+ const code = readModuleSourceSync(realPath);
+
+ if (looksLikeEsm(code)) {
+ throw new PluginSandboxError(
+ "Sandbox loader only supports CommonJS modules. Build plugin worker entrypoints as CJS for sandboxed loading.",
+ );
+ }
+
+ const module = { exports: {} as Record<string, unknown> };
+ // Cache the module before execution to preserve CommonJS cycle semantics.
+ moduleCache.set(realPath, module.exports);
+
+ const requireInSandbox = (specifier: string): Record<string, unknown> => {
+ if (!specifier.startsWith(".") && !specifier.startsWith("/")) {
+ if (!allowedSpecifiers.has(specifier)) {
+ throw new PluginSandboxError(
+ `Import denied for module '${specifier}'. Add an explicit sandbox allow-list entry.`,
+ );
+ }
+
+ const binding = allowedModules[specifier];
+ if (!binding) {
+ throw new PluginSandboxError(
+ `Bare module '${specifier}' is allow-listed but no host binding is registered.`,
+ );
+ }
+
+ return binding;
+ }
+
+ const candidatePath = path.resolve(path.dirname(realPath), specifier);
+ return loadModuleSync(candidatePath);
+ };
+
+ // Inject the CJS module arguments into the context so the script can call
+ // the wrapper immediately. This is critical: the timeout in runInContext
+ // only applies during script evaluation. By including the self-invocation
+ // `(fn)(exports, module, ...)` in the script text, the timeout also covers
+ // the actual module body execution — preventing infinite loops from hanging.
+ const sandboxArgs = {
+ __paperclip_exports: module.exports,
+ __paperclip_module: module,
+ __paperclip_require: requireInSandbox,
+ __paperclip_filename: realPath,
+ __paperclip_dirname: path.dirname(realPath),
+ };
+ // Temporarily inject args into the context, run, then remove to avoid pollution.
+ Object.assign(context, sandboxArgs);
+ const wrapped = `(function (exports, module, require, __filename, __dirname) {\n${code}\n})(__paperclip_exports, __paperclip_module, __paperclip_require, __paperclip_filename, __paperclip_dirname)`;
+ const script = new vm.Script(wrapped, { filename: realPath });
+ try {
+ script.runInContext(context, { timeout: timeoutMs });
+ } finally {
+ for (const key of Object.keys(sandboxArgs)) {
+ // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+ delete (context as Record<string, unknown>)[key];
+ }
+ }
+
+ const normalizedExports = normalizeModuleExports(module.exports);
+ moduleCache.set(realPath, normalizedExports);
+ return normalizedExports;
+ };
+
+ const entryExports = loadModuleSync(entrypointPath);
+
+ return {
+ namespace: { ...entryExports },
+ };
+}
+
+function resolveModulePathSync(candidatePath: string): string {
+ for (const suffix of MODULE_PATH_SUFFIXES) {
+ const fullPath = `${candidatePath}${suffix}`;
+ if (existsSync(fullPath)) {
+ return fullPath;
+ }
+ }
+
+ throw new PluginSandboxError(`Unable to resolve module import at path '${candidatePath}'`);
+}
+
+/**
+ * True when `targetPath` is inside `rootPath` (or equals rootPath), false otherwise.
+ * Uses `path.relative` so sibling-prefix paths (e.g. `/root-a` vs `/root`) cannot bypass checks.
+ */
+function isWithinRoot(targetPath: string, rootPath: string): boolean {
+ const relative = path.relative(rootPath, targetPath);
+ return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function readModuleSourceSync(modulePath: string): string {
+ try {
+ return readFileSync(modulePath, "utf8");
+ } catch (error) {
+ throw new PluginSandboxError(
+ `Failed to read sandbox module '${modulePath}': ${error instanceof Error ? error.message : String(error)}`,
+ );
+ }
+}
+
+function normalizeModuleExports(exportsValue: unknown): Record<string, unknown> {
+ if (typeof exportsValue === "object" && exportsValue !== null) {
+ return exportsValue as Record<string, unknown>;
+ }
+
+ return { default: exportsValue };
+}
+
+/**
+ * Lightweight guard to reject ESM syntax in the VM CommonJS loader.
+ */
+function looksLikeEsm(code: string): boolean {
+ return /(^|\n)\s*import\s+/m.test(code) || /(^|\n)\s*export\s+/m.test(code);
+}
diff --git a/server/src/services/plugin-secrets-handler.ts b/server/src/services/plugin-secrets-handler.ts
new file mode 100644
index 0000000000..a2156b3817
--- /dev/null
+++ b/server/src/services/plugin-secrets-handler.ts
@@ -0,0 +1,367 @@
+/**
+ * Plugin secrets host-side handler — resolves secret references through the
+ * Paperclip secret provider system.
+ *
+ * When a plugin worker calls `ctx.secrets.resolve(secretRef)`, the JSON-RPC
+ * request arrives at the host with `{ secretRef }`. This module provides the
+ * concrete `HostServices.secrets` adapter that:
+ *
+ * 1. Parses the `secretRef` string to identify the secret.
+ * 2. Looks up the secret record and its latest version in the database.
+ * 3. Delegates to the configured `SecretProviderModule` to decrypt /
+ * resolve the raw value.
+ * 4. Returns the resolved plaintext value to the worker.
+ *
+ * ## Secret Reference Format
+ *
+ * A `secretRef` is a **secret UUID** — the primary key (`id`) of a row in
+ * the `company_secrets` table. Operators place these UUIDs into plugin
+ * config values; plugin workers resolve them at execution time via
+ * `ctx.secrets.resolve(secretId)`.
+ *
+ * ## Security Invariants
+ *
+ * - Resolved values are **never** logged, persisted, or included in error
+ * messages (per PLUGIN_SPEC.md §22).
+ * - The handler is capability-gated: only plugins with `secrets.read-ref`
+ * declared in their manifest may call it (enforced by `host-client-factory`).
+ * - The host handler itself does not cache resolved values. Each call goes
+ * through the secret provider to honour rotation.
+ *
+ * @see PLUGIN_SPEC.md §22 — Secrets
+ * @see host-client-factory.ts — capability gating
+ * @see services/secrets.ts — secretService used by agent env bindings
+ */
+
+import { eq, and, desc } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import { companySecrets, companySecretVersions, pluginConfig } from "@paperclipai/db";
+import type { SecretProvider } from "@paperclipai/shared";
+import { getSecretProvider } from "../secrets/provider-registry.js";
+import { pluginRegistryService } from "./plugin-registry.js";
+
+// ---------------------------------------------------------------------------
+// Error helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a sanitised error that never leaks secret material.
+ * Only the ref identifier is included; never the resolved value.
+ */
+function secretNotFound(secretRef: string): Error {
+ const err = new Error(`Secret not found: ${secretRef}`);
+ err.name = "SecretNotFoundError";
+ return err;
+}
+
+function secretVersionNotFound(secretRef: string): Error {
+ const err = new Error(`No version found for secret: ${secretRef}`);
+ err.name = "SecretVersionNotFoundError";
+ return err;
+}
+
+function invalidSecretRef(secretRef: string): Error {
+ const err = new Error(`Invalid secret reference: ${secretRef}`);
+ err.name = "InvalidSecretRefError";
+ return err;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/** UUID v4 regex for validating secretRef format. */
+const UUID_RE =
+ /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Check whether a secretRef looks like a valid UUID.
+ */
+function isUuid(value: string): boolean {
+ return UUID_RE.test(value);
+}
+
+/**
+ * Collect the property paths (dot-separated keys) whose schema node declares
+ * `format: "secret-ref"`. Only top-level and nested `properties` are walked —
+ * this mirrors the flat/nested object shapes that `JsonSchemaForm` renders.
+ */
+function collectSecretRefPaths(
+ schema: Record<string, unknown> | null | undefined,
+): Set<string> {
+ const paths = new Set<string>();
+ if (!schema || typeof schema !== "object") return paths;
+
+ function walk(node: Record<string, unknown>, prefix: string): void {
+ const props = node.properties as Record<string, Record<string, unknown>> | undefined;
+ if (!props || typeof props !== "object") return;
+ for (const [key, propSchema] of Object.entries(props)) {
+ if (!propSchema || typeof propSchema !== "object") continue;
+ const path = prefix ? `${prefix}.${key}` : key;
+ if (propSchema.format === "secret-ref") {
+ paths.add(path);
+ }
+ // Recurse into nested object schemas
+ if (propSchema.type === "object") {
+ walk(propSchema, path);
+ }
+ }
+ }
+
+ walk(schema, "");
+ return paths;
+}
+
+/**
+ * Extract secret reference UUIDs from a plugin's configJson, scoped to only
+ * the fields annotated with `format: "secret-ref"` in the schema.
+ *
+ * When no schema is provided, falls back to collecting all UUID-shaped strings
+ * (backwards-compatible for plugins without a declared instanceConfigSchema).
+ */
+export function extractSecretRefsFromConfig(
+ configJson: unknown,
+ schema?: Record<string, unknown> | null,
+): Set<string> {
+ const refs = new Set<string>();
+ if (configJson == null || typeof configJson !== "object") return refs;
+
+ const secretPaths = collectSecretRefPaths(schema);
+
+ // If schema declares secret-ref paths, extract only those values.
+ if (secretPaths.size > 0) {
+ for (const dotPath of secretPaths) {
+ const keys = dotPath.split(".");
+ let current: unknown = configJson;
+ for (const k of keys) {
+ if (current == null || typeof current !== "object") { current = undefined; break; }
+ current = (current as Record<string, unknown>)[k];
+ }
+ if (typeof current === "string" && isUuid(current)) {
+ refs.add(current);
+ }
+ }
+ return refs;
+ }
+
+ // Fallback: no schema or no secret-ref annotations — collect all UUIDs.
+ // This preserves backwards compatibility for plugins that omit
+ // instanceConfigSchema.
+ function walkAll(value: unknown): void {
+ if (typeof value === "string") {
+ if (isUuid(value)) refs.add(value);
+ } else if (Array.isArray(value)) {
+ for (const item of value) walkAll(item);
+ } else if (value !== null && typeof value === "object") {
+ for (const v of Object.values(value as Record<string, unknown>)) walkAll(v);
+ }
+ }
+
+ walkAll(configJson);
+ return refs;
+}
+
+// ---------------------------------------------------------------------------
+// Handler factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Input shape for the `secrets.resolve` handler.
+ *
+ * Matches `WorkerToHostMethods["secrets.resolve"][0]` from `protocol.ts`.
+ */
+export interface PluginSecretsResolveParams {
+ /** The secret reference string (a secret UUID). */
+ secretRef: string;
+}
+
+/**
+ * Options for creating the plugin secrets handler.
+ */
+export interface PluginSecretsHandlerOptions {
+ /** Database connection. */
+ db: Db;
+ /**
+ * The plugin ID using this handler.
+ * Used for logging context only; never included in error payloads
+ * that reach the plugin worker.
+ */
+ pluginId: string;
+}
+
+/**
+ * The `HostServices.secrets` adapter for the plugin host-client factory.
+ */
+export interface PluginSecretsService {
+ /**
+ * Resolve a secret reference to its current plaintext value.
+ *
+ * @param params - Contains the `secretRef` (UUID of the secret)
+ * @returns The resolved secret value
+ * @throws {Error} If the secret is not found, has no versions, or
+ * the provider fails to resolve
+ */
+ resolve(params: PluginSecretsResolveParams): Promise<string>;
+}
+
+/**
+ * Create a `HostServices.secrets` adapter for a specific plugin.
+ *
+ * The returned service looks up secrets by UUID, fetches the latest version
+ * material, and delegates to the appropriate `SecretProviderModule` for
+ * decryption.
+ *
+ * @example
+ * ```ts
+ * const secretsHandler = createPluginSecretsHandler({ db, pluginId });
+ * const handlers = createHostClientHandlers({
+ * pluginId,
+ * capabilities: manifest.capabilities,
+ * services: {
+ * secrets: secretsHandler,
+ * // ...
+ * },
+ * });
+ * ```
+ *
+ * @param options - Database connection and plugin identity
+ * @returns A `PluginSecretsService` suitable for `HostServices.secrets`
+ */
+/** Simple sliding-window rate limiter for secret resolution attempts. */
+function createRateLimiter(maxAttempts: number, windowMs: number) {
+ const attempts = new Map<string, number[]>();
+
+ return {
+ check(key: string): boolean {
+ const now = Date.now();
+ const windowStart = now - windowMs;
+ const existing = (attempts.get(key) ?? []).filter((ts) => ts > windowStart);
+ if (existing.length >= maxAttempts) return false;
+ existing.push(now);
+ attempts.set(key, existing);
+ return true;
+ },
+ };
+}
+
+export function createPluginSecretsHandler(
+ options: PluginSecretsHandlerOptions,
+): PluginSecretsService {
+ const { db, pluginId } = options;
+ const registry = pluginRegistryService(db);
+
+ // Rate limit: max 30 resolution attempts per plugin per minute
+ const rateLimiter = createRateLimiter(30, 60_000);
+
+ let cachedAllowedRefs: Set<string> | null = null;
+ let cachedAllowedRefsExpiry = 0;
+ const CONFIG_CACHE_TTL_MS = 30_000; // 30 seconds, matches event bus TTL
+
+ return {
+ async resolve(params: PluginSecretsResolveParams): Promise<string> {
+ const { secretRef } = params;
+
+ // ---------------------------------------------------------------
+ // 0. Rate limiting — prevent brute-force UUID enumeration
+ // ---------------------------------------------------------------
+ if (!rateLimiter.check(pluginId)) {
+ const err = new Error("Rate limit exceeded for secret resolution");
+ err.name = "RateLimitExceededError";
+ throw err;
+ }
+
+ // ---------------------------------------------------------------
+ // 1. Validate the ref format
+ // ---------------------------------------------------------------
+ if (!secretRef || typeof secretRef !== "string" || secretRef.trim().length === 0) {
+ throw invalidSecretRef(secretRef ?? "<empty>");
+ }
+
+ const trimmedRef = secretRef.trim();
+
+ if (!isUuid(trimmedRef)) {
+ throw invalidSecretRef(trimmedRef);
+ }
+
+ // ---------------------------------------------------------------
+ // 1b. Scope check — only allow secrets referenced in this plugin's config
+ // ---------------------------------------------------------------
+ const now = Date.now();
+ if (!cachedAllowedRefs || now > cachedAllowedRefsExpiry) {
+ const [configRow, plugin] = await Promise.all([
+ db
+ .select()
+ .from(pluginConfig)
+ .where(eq(pluginConfig.pluginId, pluginId))
+ .then((rows) => rows[0] ?? null),
+ registry.getById(pluginId),
+ ]);
+
+ const schema = (plugin?.manifestJson as unknown as Record<string, unknown> | null)
+ ?.instanceConfigSchema as Record<string, unknown> | undefined;
+ cachedAllowedRefs = extractSecretRefsFromConfig(configRow?.configJson, schema);
+ cachedAllowedRefsExpiry = now + CONFIG_CACHE_TTL_MS;
+ }
+
+ if (!cachedAllowedRefs.has(trimmedRef)) {
+ // Return "not found" to avoid leaking whether the secret exists
+ throw secretNotFound(trimmedRef);
+ }
+
+ // ---------------------------------------------------------------
+ // 2. Look up the secret record by UUID
+ // ---------------------------------------------------------------
+ const secret = await db
+ .select()
+ .from(companySecrets)
+ .where(eq(companySecrets.id, trimmedRef))
+ .then((rows) => rows[0] ?? null);
+
+ if (!secret) {
+ throw secretNotFound(trimmedRef);
+ }
+
+ // ---------------------------------------------------------------
+ // 2b. Verify the plugin is available for the secret's company.
+ // This prevents cross-company secret access via UUID guessing.
+ // ---------------------------------------------------------------
+ const companyId = (secret as { companyId?: string }).companyId;
+ if (companyId) {
+ const availability = await registry.getCompanyAvailability(companyId, pluginId);
+ if (!availability || !availability.available) {
+ // Return the same error as "not found" to avoid leaking existence
+ throw secretNotFound(trimmedRef);
+ }
+ }
+
+ // ---------------------------------------------------------------
+ // 3. Fetch the latest version's material
+ // ---------------------------------------------------------------
+ const versionRow = await db
+ .select()
+ .from(companySecretVersions)
+ .where(
+ and(
+ eq(companySecretVersions.secretId, secret.id),
+ eq(companySecretVersions.version, secret.latestVersion),
+ ),
+ )
+ .then((rows) => rows[0] ?? null);
+
+ if (!versionRow) {
+ throw secretVersionNotFound(trimmedRef);
+ }
+
+ // ---------------------------------------------------------------
+ // 4. Resolve through the appropriate secret provider
+ // ---------------------------------------------------------------
+ const provider = getSecretProvider(secret.provider as SecretProvider);
+ const resolved = await provider.resolveVersion({
+ material: versionRow.material as Record<string, unknown>,
+ externalRef: secret.externalRef,
+ });
+
+ return resolved;
+ },
+ };
+}
diff --git a/server/src/services/plugin-state-store.ts b/server/src/services/plugin-state-store.ts
new file mode 100644
index 0000000000..94377dc045
--- /dev/null
+++ b/server/src/services/plugin-state-store.ts
@@ -0,0 +1,237 @@
+import { and, eq, isNull } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import { plugins, pluginState } from "@paperclipai/db";
+import type {
+ PluginStateScopeKind,
+ SetPluginState,
+ ListPluginState,
+} from "@paperclipai/shared";
+import { notFound } from "../errors.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Default namespace used when the plugin does not specify one. */
+const DEFAULT_NAMESPACE = "default";
+
+/**
+ * Build the WHERE clause conditions for a scoped state lookup.
+ *
+ * The five-part composite key is:
+ * `(pluginId, scopeKind, scopeId, namespace, stateKey)`
+ *
+ * `scopeId` may be null (for `instance` scope) or a non-empty string.
+ */
+function scopeConditions(
+ pluginId: string,
+ scopeKind: PluginStateScopeKind,
+ scopeId: string | undefined | null,
+ namespace: string,
+ stateKey: string,
+) {
+ const conditions = [
+ eq(pluginState.pluginId, pluginId),
+ eq(pluginState.scopeKind, scopeKind),
+ eq(pluginState.namespace, namespace),
+ eq(pluginState.stateKey, stateKey),
+ ];
+
+ if (scopeId != null && scopeId !== "") {
+ conditions.push(eq(pluginState.scopeId, scopeId));
+ } else {
+ conditions.push(isNull(pluginState.scopeId));
+ }
+
+ return and(...conditions);
+}
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+/**
+ * Plugin State Store — scoped key-value persistence for plugin workers.
+ *
+ * Provides `get`, `set`, `delete`, and `list` operations over the
+ * `plugin_state` table. Each plugin's data is strictly namespaced by
+ * `pluginId` so plugins cannot read or write each other's state.
+ *
+ * This service implements the server-side backing for the `ctx.state` SDK
+ * client exposed to plugin workers. The host is responsible for:
+ * - enforcing `plugin.state.read` capability before calling `get` / `list`
+ * - enforcing `plugin.state.write` capability before calling `set` / `delete`
+ *
+ * @see PLUGIN_SPEC.md §14 — SDK Surface (`ctx.state`)
+ * @see PLUGIN_SPEC.md §15.1 — Capabilities: Plugin State
+ * @see PLUGIN_SPEC.md §21.3 — `plugin_state` table
+ */
+export function pluginStateStore(db: Db) {
+ // -----------------------------------------------------------------------
+ // Internal helpers
+ // -----------------------------------------------------------------------
+
+ async function assertPluginExists(pluginId: string): Promise<void> {
+ const rows = await db
+ .select({ id: plugins.id })
+ .from(plugins)
+ .where(eq(plugins.id, pluginId));
+ if (rows.length === 0) {
+ throw notFound(`Plugin not found: ${pluginId}`);
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ // Public API
+ // -----------------------------------------------------------------------
+
+ return {
+ /**
+ * Read a state value.
+ *
+ * Returns the stored JSON value, or `null` if no entry exists for the
+ * given scope and key.
+ *
+ * Requires `plugin.state.read` capability (enforced by the caller).
+ *
+ * @param pluginId - UUID of the owning plugin
+ * @param scopeKind - Granularity of the scope
+ * @param scopeId - Identifier for the scoped entity (null for `instance` scope)
+ * @param stateKey - The key to read
+ * @param namespace - Sub-namespace (defaults to `"default"`)
+ */
+ get: async (
+ pluginId: string,
+ scopeKind: PluginStateScopeKind,
+ stateKey: string,
+ {
+ scopeId,
+ namespace = DEFAULT_NAMESPACE,
+ }: { scopeId?: string; namespace?: string } = {},
+ ): Promise<unknown> => {
+ const rows = await db
+ .select()
+ .from(pluginState)
+ .where(scopeConditions(pluginId, scopeKind, scopeId, namespace, stateKey));
+
+ return rows[0]?.valueJson ?? null;
+ },
+
+ /**
+ * Write (create or replace) a state value.
+ *
+ * Uses an upsert so the caller does not need to check for prior existence.
+ * On conflict (same composite key) the existing row's `value_json` and
+ * `updated_at` are overwritten.
+ *
+ * Requires `plugin.state.write` capability (enforced by the caller).
+ *
+ * @param pluginId - UUID of the owning plugin
+ * @param input - Scope key and value to store
+ */
+ set: async (pluginId: string, input: SetPluginState): Promise<void> => {
+ await assertPluginExists(pluginId);
+
+ const namespace = input.namespace ?? DEFAULT_NAMESPACE;
+ const scopeId = input.scopeId ?? null;
+
+ await db
+ .insert(pluginState)
+ .values({
+ pluginId,
+ scopeKind: input.scopeKind,
+ scopeId,
+ namespace,
+ stateKey: input.stateKey,
+ valueJson: input.value,
+ updatedAt: new Date(),
+ })
+ .onConflictDoUpdate({
+ target: [
+ pluginState.pluginId,
+ pluginState.scopeKind,
+ pluginState.scopeId,
+ pluginState.namespace,
+ pluginState.stateKey,
+ ],
+ set: {
+ valueJson: input.value,
+ updatedAt: new Date(),
+ },
+ });
+ },
+
+ /**
+ * Delete a state value.
+ *
+ * No-ops silently if the entry does not exist (idempotent by design).
+ *
+ * Requires `plugin.state.write` capability (enforced by the caller).
+ *
+ * @param pluginId - UUID of the owning plugin
+ * @param scopeKind - Granularity of the scope
+ * @param stateKey - The key to delete
+ * @param scopeId - Identifier for the scoped entity (null for `instance` scope)
+ * @param namespace - Sub-namespace (defaults to `"default"`)
+ */
+ delete: async (
+ pluginId: string,
+ scopeKind: PluginStateScopeKind,
+ stateKey: string,
+ {
+ scopeId,
+ namespace = DEFAULT_NAMESPACE,
+ }: { scopeId?: string; namespace?: string } = {},
+ ): Promise<void> => {
+ await db
+ .delete(pluginState)
+ .where(scopeConditions(pluginId, scopeKind, scopeId, namespace, stateKey));
+ },
+
+ /**
+ * List all state entries for a plugin, optionally filtered by scope.
+ *
+ * Returns all matching rows as `PluginStateRecord`-shaped objects.
+ * The `valueJson` field contains the stored value.
+ *
+ * Requires `plugin.state.read` capability (enforced by the caller).
+ *
+ * @param pluginId - UUID of the owning plugin
+ * @param filter - Optional scope filters (scopeKind, scopeId, namespace)
+ */
+ list: async (pluginId: string, filter: ListPluginState = {}): Promise<typeof pluginState.$inferSelect[]> => {
+ const conditions = [eq(pluginState.pluginId, pluginId)];
+
+ if (filter.scopeKind !== undefined) {
+ conditions.push(eq(pluginState.scopeKind, filter.scopeKind));
+ }
+ if (filter.scopeId !== undefined) {
+ conditions.push(eq(pluginState.scopeId, filter.scopeId));
+ }
+ if (filter.namespace !== undefined) {
+ conditions.push(eq(pluginState.namespace, filter.namespace));
+ }
+
+ return db
+ .select()
+ .from(pluginState)
+ .where(and(...conditions));
+ },
+
+ /**
+ * Delete all state entries owned by a plugin.
+ *
+ * Called during plugin uninstall when `removeData = true`. Also useful
+ * for resetting a plugin's state during testing.
+ *
+ * @param pluginId - UUID of the owning plugin
+ */
+ deleteAll: async (pluginId: string): Promise<void> => {
+ await db
+ .delete(pluginState)
+ .where(eq(pluginState.pluginId, pluginId));
+ },
+ };
+}
+
+export type PluginStateStore = ReturnType<typeof pluginStateStore>;
diff --git a/server/src/services/plugin-stream-bus.ts b/server/src/services/plugin-stream-bus.ts
new file mode 100644
index 0000000000..e39aca5ef1
--- /dev/null
+++ b/server/src/services/plugin-stream-bus.ts
@@ -0,0 +1,81 @@
+/**
+ * In-memory pub/sub bus for plugin SSE streams.
+ *
+ * Workers emit stream events via JSON-RPC notifications. The bus fans out
+ * each event to all connected SSE clients that match the (pluginId, channel,
+ * companyId) tuple.
+ *
+ * @see PLUGIN_SPEC.md §19.8 — Real-Time Streaming
+ */
+
+/** Valid SSE event types for plugin streams. */
+export type StreamEventType = "message" | "open" | "close" | "error";
+
+export type StreamSubscriber = (event: unknown, eventType: StreamEventType) => void;
+
+/**
+ * Composite key for stream subscriptions: pluginId:channel:companyId
+ */
+function streamKey(pluginId: string, channel: string, companyId: string): string {
+ return `${pluginId}:${channel}:${companyId}`;
+}
+
+export interface PluginStreamBus {
+ /**
+ * Subscribe to stream events for a specific (pluginId, channel, companyId).
+ * Returns an unsubscribe function.
+ */
+ subscribe(
+ pluginId: string,
+ channel: string,
+ companyId: string,
+ listener: StreamSubscriber,
+ ): () => void;
+
+ /**
+ * Publish an event to all subscribers of (pluginId, channel, companyId).
+ * Called by the worker manager when it receives a stream notification.
+ */
+ publish(
+ pluginId: string,
+ channel: string,
+ companyId: string,
+ event: unknown,
+ eventType?: StreamEventType,
+ ): void;
+}
+
+/**
+ * Create a new PluginStreamBus instance.
+ */
+export function createPluginStreamBus(): PluginStreamBus {
+ const subscribers = new Map<string, Set<StreamSubscriber>>();
+
+ return {
+ subscribe(pluginId, channel, companyId, listener) {
+ const key = streamKey(pluginId, channel, companyId);
+ let set = subscribers.get(key);
+ if (!set) {
+ set = new Set();
+ subscribers.set(key, set);
+ }
+ set.add(listener);
+
+ return () => {
+ set!.delete(listener);
+ if (set!.size === 0) {
+ subscribers.delete(key);
+ }
+ };
+ },
+
+ publish(pluginId, channel, companyId, event, eventType: StreamEventType = "message") {
+ const key = streamKey(pluginId, channel, companyId);
+ const set = subscribers.get(key);
+ if (!set) return;
+ for (const listener of set) {
+ listener(event, eventType);
+ }
+ },
+ };
+}
diff --git a/server/src/services/plugin-tool-dispatcher.ts b/server/src/services/plugin-tool-dispatcher.ts
new file mode 100644
index 0000000000..18ea075b19
--- /dev/null
+++ b/server/src/services/plugin-tool-dispatcher.ts
@@ -0,0 +1,448 @@
+/**
+ * PluginToolDispatcher — orchestrates plugin tool discovery, lifecycle
+ * integration, and execution routing for the agent service.
+ *
+ * This service sits between the agent service and the lower-level
+ * `PluginToolRegistry` + `PluginWorkerManager`, providing a clean API that:
+ *
+ * - Discovers tools from loaded plugin manifests and registers them
+ * in the tool registry.
+ * - Hooks into `PluginLifecycleManager` events to automatically register
+ * and unregister tools when plugins are enabled or disabled.
+ * - Exposes the tool list in an agent-friendly format (with namespaced
+ * names, descriptions, parameter schemas).
+ * - Routes `executeTool` calls to the correct plugin worker and returns
+ * structured results.
+ * - Validates tool parameters against declared schemas before dispatch.
+ *
+ * The dispatcher is created once at server startup and shared across
+ * the application.
+ *
+ * @see PLUGIN_SPEC.md §11 — Agent Tools
+ * @see PLUGIN_SPEC.md §13.10 — `executeTool`
+ */
+
+import type { Db } from "@paperclipai/db";
+import type {
+ PaperclipPluginManifestV1,
+ PluginRecord,
+} from "@paperclipai/shared";
+import type { ToolRunContext, ToolResult } from "@paperclipai/plugin-sdk";
+import type { PluginWorkerManager } from "./plugin-worker-manager.js";
+import type { PluginLifecycleManager } from "./plugin-lifecycle.js";
+import {
+ createPluginToolRegistry,
+ type PluginToolRegistry,
+ type RegisteredTool,
+ type ToolListFilter,
+ type ToolExecutionResult,
+} from "./plugin-tool-registry.js";
+import { pluginRegistryService } from "./plugin-registry.js";
+import { logger } from "../middleware/logger.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * An agent-facing tool descriptor — the shape returned when agents
+ * query for available tools.
+ *
+ * This is intentionally simpler than `RegisteredTool`, exposing only
+ * what agents need to decide whether and how to call a tool.
+ */
+export interface AgentToolDescriptor {
+ /** Fully namespaced tool name (e.g. `"acme.linear:search-issues"`). */
+ name: string;
+ /** Human-readable display name. */
+ displayName: string;
+ /** Description for the agent — explains when and how to use this tool. */
+ description: string;
+ /** JSON Schema describing the tool's input parameters. */
+ parametersSchema: Record<string, unknown>;
+ /** The plugin that provides this tool. */
+ pluginId: string;
+}
+
+/**
+ * Options for creating the plugin tool dispatcher.
+ */
+export interface PluginToolDispatcherOptions {
+ /** The worker manager used to dispatch RPC calls to plugin workers. */
+ workerManager?: PluginWorkerManager;
+ /** The lifecycle manager to listen for plugin state changes. */
+ lifecycleManager?: PluginLifecycleManager;
+ /** Database connection for looking up plugin records. */
+ db?: Db;
+}
+
+// ---------------------------------------------------------------------------
+// PluginToolDispatcher interface
+// ---------------------------------------------------------------------------
+
+/**
+ * The plugin tool dispatcher — the primary integration point between the
+ * agent service and the plugin tool system.
+ *
+ * Agents use this service to:
+ * 1. List all available tools (for prompt construction / tool choice)
+ * 2. Execute a specific tool by its namespaced name
+ *
+ * The dispatcher handles lifecycle management internally — when a plugin
+ * is loaded or unloaded, its tools are automatically registered or removed.
+ */
+export interface PluginToolDispatcher {
+ /**
+ * Initialize the dispatcher — load tools from all currently-ready plugins
+ * and start listening for lifecycle events.
+ *
+ * Must be called once at server startup after the lifecycle manager
+ * and worker manager are ready.
+ */
+ initialize(): Promise<void>;
+
+ /**
+ * Tear down the dispatcher — unregister lifecycle event listeners
+ * and clear all tool registrations.
+ *
+ * Called during server shutdown.
+ */
+ teardown(): void;
+
+ /**
+ * List all available tools for agents, optionally filtered.
+ *
+ * Returns tool descriptors in an agent-friendly format.
+ *
+ * @param filter - Optional filter criteria
+ * @returns Array of agent tool descriptors
+ */
+ listToolsForAgent(filter?: ToolListFilter): AgentToolDescriptor[];
+
+ /**
+ * Look up a tool by its namespaced name.
+ *
+ * @param namespacedName - e.g. `"acme.linear:search-issues"`
+ * @returns The registered tool, or `null` if not found
+ */
+ getTool(namespacedName: string): RegisteredTool | null;
+
+ /**
+ * Execute a tool by its namespaced name, routing to the correct
+ * plugin worker.
+ *
+ * @param namespacedName - Fully qualified tool name
+ * @param parameters - Input parameters matching the tool's schema
+ * @param runContext - Agent run context
+ * @returns The execution result with routing metadata
+ * @throws {Error} if the tool is not found, the worker is not running,
+ * or the tool execution fails
+ */
+ executeTool(
+ namespacedName: string,
+ parameters: unknown,
+ runContext: ToolRunContext,
+ ): Promise<ToolExecutionResult>;
+
+ /**
+ * Register all tools from a plugin manifest.
+ *
+ * This is called automatically when a plugin transitions to `ready`.
+ * Can also be called manually for testing or recovery scenarios.
+ *
+ * @param pluginId - The plugin's unique identifier
+ * @param manifest - The plugin manifest containing tool declarations
+ */
+ registerPluginTools(
+ pluginId: string,
+ manifest: PaperclipPluginManifestV1,
+ ): void;
+
+ /**
+ * Unregister all tools for a plugin.
+ *
+ * Called automatically when a plugin is disabled or unloaded.
+ *
+ * @param pluginId - The plugin to unregister
+ */
+ unregisterPluginTools(pluginId: string): void;
+
+ /**
+ * Get the total number of registered tools, optionally scoped to a plugin.
+ *
+ * @param pluginId - If provided, count only this plugin's tools
+ */
+ toolCount(pluginId?: string): number;
+
+ /**
+ * Access the underlying tool registry for advanced operations.
+ *
+ * This escape hatch exists for internal use (e.g. diagnostics).
+ * Prefer the dispatcher's own methods for normal operations.
+ */
+ getRegistry(): PluginToolRegistry;
+}
+
+// ---------------------------------------------------------------------------
+// Factory: createPluginToolDispatcher
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new `PluginToolDispatcher`.
+ *
+ * The dispatcher:
+ * 1. Creates and owns a `PluginToolRegistry` backed by the given worker manager.
+ * 2. Listens for lifecycle events (plugin.enabled, plugin.disabled, plugin.unloaded)
+ * to automatically register and unregister tools.
+ * 3. On `initialize()`, loads tools from all currently-ready plugins via the DB.
+ *
+ * @param options - Configuration options
+ *
+ * @example
+ * ```ts
+ * // At server startup
+ * const dispatcher = createPluginToolDispatcher({
+ * workerManager,
+ * lifecycleManager,
+ * db,
+ * });
+ * await dispatcher.initialize();
+ *
+ * // In agent service — list tools for prompt construction
+ * const tools = dispatcher.listToolsForAgent();
+ *
+ * // In agent service — execute a tool
+ * const result = await dispatcher.executeTool(
+ * "acme.linear:search-issues",
+ * { query: "auth bug" },
+ * { agentId: "a-1", runId: "r-1", companyId: "c-1", projectId: "p-1" },
+ * );
+ * ```
+ */
+export function createPluginToolDispatcher(
+ options: PluginToolDispatcherOptions = {},
+): PluginToolDispatcher {
+ const { workerManager, lifecycleManager, db } = options;
+ const log = logger.child({ service: "plugin-tool-dispatcher" });
+
+ // Create the underlying tool registry, backed by the worker manager
+ const registry = createPluginToolRegistry(workerManager);
+
+ // Track lifecycle event listeners so we can remove them on teardown
+ let enabledListener: ((payload: { pluginId: string; pluginKey: string }) => void) | null = null;
+ let disabledListener: ((payload: { pluginId: string; pluginKey: string; reason?: string }) => void) | null = null;
+ let unloadedListener: ((payload: { pluginId: string; pluginKey: string; removeData: boolean }) => void) | null = null;
+
+ let initialized = false;
+
+ // -----------------------------------------------------------------------
+ // Internal helpers
+ // -----------------------------------------------------------------------
+
+ /**
+ * Attempt to register tools for a plugin by looking up its manifest
+ * from the DB. No-ops gracefully if the plugin or manifest is missing.
+ */
+ async function registerFromDb(pluginId: string): Promise<void> {
+ if (!db) {
+ log.warn(
+ { pluginId },
+ "cannot register tools from DB — no database connection configured",
+ );
+ return;
+ }
+
+ const pluginRegistry = pluginRegistryService(db);
+ const plugin = await pluginRegistry.getById(pluginId) as PluginRecord | null;
+
+ if (!plugin) {
+ log.warn({ pluginId }, "plugin not found in registry, cannot register tools");
+ return;
+ }
+
+ const manifest = plugin.manifestJson;
+ if (!manifest) {
+ log.warn({ pluginId }, "plugin has no manifest, cannot register tools");
+ return;
+ }
+
+ registry.registerPlugin(plugin.pluginKey, manifest, plugin.id);
+ }
+
+ /**
+ * Convert a `RegisteredTool` to an `AgentToolDescriptor`.
+ */
+ function toAgentDescriptor(tool: RegisteredTool): AgentToolDescriptor {
+ return {
+ name: tool.namespacedName,
+ displayName: tool.displayName,
+ description: tool.description,
+ parametersSchema: tool.parametersSchema,
+ pluginId: tool.pluginDbId,
+ };
+ }
+
+ // -----------------------------------------------------------------------
+ // Lifecycle event handlers
+ // -----------------------------------------------------------------------
+
+ function handlePluginEnabled(payload: { pluginId: string; pluginKey: string }): void {
+ log.debug({ pluginId: payload.pluginId, pluginKey: payload.pluginKey }, "plugin enabled — registering tools");
+ // Async registration from DB — we fire-and-forget since the lifecycle
+ // event handler must be synchronous. Any errors are logged.
+ void registerFromDb(payload.pluginId).catch((err) => {
+ log.error(
+ { pluginId: payload.pluginId, err: err instanceof Error ? err.message : String(err) },
+ "failed to register tools after plugin enabled",
+ );
+ });
+ }
+
+ function handlePluginDisabled(payload: { pluginId: string; pluginKey: string; reason?: string }): void {
+ log.debug({ pluginId: payload.pluginId, pluginKey: payload.pluginKey }, "plugin disabled — unregistering tools");
+ registry.unregisterPlugin(payload.pluginKey);
+ }
+
+ function handlePluginUnloaded(payload: { pluginId: string; pluginKey: string; removeData: boolean }): void {
+ log.debug({ pluginId: payload.pluginId, pluginKey: payload.pluginKey }, "plugin unloaded — unregistering tools");
+ registry.unregisterPlugin(payload.pluginKey);
+ }
+
+ // -----------------------------------------------------------------------
+ // Public API
+ // -----------------------------------------------------------------------
+
+ return {
+ async initialize(): Promise<void> {
+ if (initialized) {
+ log.warn("dispatcher already initialized, skipping");
+ return;
+ }
+
+ log.info("initializing plugin tool dispatcher");
+
+ // Step 1: Load tools from all currently-ready plugins
+ if (db) {
+ const pluginRegistry = pluginRegistryService(db);
+ const readyPlugins = await pluginRegistry.listByStatus("ready") as PluginRecord[];
+
+ let totalTools = 0;
+ for (const plugin of readyPlugins) {
+ const manifest = plugin.manifestJson;
+ if (manifest?.tools && manifest.tools.length > 0) {
+ registry.registerPlugin(plugin.pluginKey, manifest, plugin.id);
+ totalTools += manifest.tools.length;
+ }
+ }
+
+ log.info(
+ { readyPlugins: readyPlugins.length, registeredTools: totalTools },
+ "loaded tools from ready plugins",
+ );
+ }
+
+ // Step 2: Subscribe to lifecycle events for dynamic updates
+ if (lifecycleManager) {
+ enabledListener = handlePluginEnabled;
+ disabledListener = handlePluginDisabled;
+ unloadedListener = handlePluginUnloaded;
+
+ lifecycleManager.on("plugin.enabled", enabledListener);
+ lifecycleManager.on("plugin.disabled", disabledListener);
+ lifecycleManager.on("plugin.unloaded", unloadedListener);
+
+ log.debug("subscribed to lifecycle events");
+ } else {
+ log.warn("no lifecycle manager provided — tools will not auto-update on plugin state changes");
+ }
+
+ initialized = true;
+ log.info(
+ { totalTools: registry.toolCount() },
+ "plugin tool dispatcher initialized",
+ );
+ },
+
+ teardown(): void {
+ if (!initialized) return;
+
+ // Unsubscribe from lifecycle events
+ if (lifecycleManager) {
+ if (enabledListener) lifecycleManager.off("plugin.enabled", enabledListener);
+ if (disabledListener) lifecycleManager.off("plugin.disabled", disabledListener);
+ if (unloadedListener) lifecycleManager.off("plugin.unloaded", unloadedListener);
+
+ enabledListener = null;
+ disabledListener = null;
+ unloadedListener = null;
+ }
+
+ // Note: we do NOT clear the registry here because teardown may be
+ // called during graceful shutdown where in-flight tool calls should
+ // still be able to resolve their tool entries.
+
+ initialized = false;
+ log.info("plugin tool dispatcher torn down");
+ },
+
+ listToolsForAgent(filter?: ToolListFilter): AgentToolDescriptor[] {
+ return registry.listTools(filter).map(toAgentDescriptor);
+ },
+
+ getTool(namespacedName: string): RegisteredTool | null {
+ return registry.getTool(namespacedName);
+ },
+
+ async executeTool(
+ namespacedName: string,
+ parameters: unknown,
+ runContext: ToolRunContext,
+ ): Promise<ToolExecutionResult> {
+ log.debug(
+ {
+ tool: namespacedName,
+ agentId: runContext.agentId,
+ runId: runContext.runId,
+ },
+ "dispatching tool execution",
+ );
+
+ const result = await registry.executeTool(
+ namespacedName,
+ parameters,
+ runContext,
+ );
+
+ log.debug(
+ {
+ tool: namespacedName,
+ pluginId: result.pluginId,
+ hasContent: !!result.result.content,
+ hasError: !!result.result.error,
+ },
+ "tool execution completed",
+ );
+
+ return result;
+ },
+
+ registerPluginTools(
+ pluginId: string,
+ manifest: PaperclipPluginManifestV1,
+ ): void {
+ registry.registerPlugin(pluginId, manifest);
+ },
+
+ unregisterPluginTools(pluginId: string): void {
+ registry.unregisterPlugin(pluginId);
+ },
+
+ toolCount(pluginId?: string): number {
+ return registry.toolCount(pluginId);
+ },
+
+ getRegistry(): PluginToolRegistry {
+ return registry;
+ },
+ };
+}
diff --git a/server/src/services/plugin-tool-registry.ts b/server/src/services/plugin-tool-registry.ts
new file mode 100644
index 0000000000..cde0cf2786
--- /dev/null
+++ b/server/src/services/plugin-tool-registry.ts
@@ -0,0 +1,449 @@
+/**
+ * PluginToolRegistry — host-side registry for plugin-contributed agent tools.
+ *
+ * Responsibilities:
+ * - Store tool declarations (from plugin manifests) alongside routing metadata
+ * so the host can resolve namespaced tool names to the owning plugin worker.
+ * - Namespace tools automatically: a tool `"search-issues"` from plugin
+ * `"acme.linear"` is exposed to agents as `"acme.linear:search-issues"`.
+ * - Route `executeTool` calls to the correct plugin worker via the
+ * `PluginWorkerManager`.
+ * - Provide tool discovery queries so agents can list available tools.
+ * - Clean up tool registrations when a plugin is unloaded or its worker stops.
+ *
+ * The registry is an in-memory structure — tool declarations are derived from
+ * the plugin manifest at load time and do not need persistence. When a plugin
+ * worker restarts, the host re-registers its manifest tools.
+ *
+ * @see PLUGIN_SPEC.md §11 — Agent Tools
+ * @see PLUGIN_SPEC.md §13.10 — `executeTool`
+ */
+
+import type {
+ PaperclipPluginManifestV1,
+ PluginToolDeclaration,
+} from "@paperclipai/shared";
+import type { ToolRunContext, ToolResult, ExecuteToolParams } from "@paperclipai/plugin-sdk";
+import type { PluginWorkerManager } from "./plugin-worker-manager.js";
+import { logger } from "../middleware/logger.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Separator between plugin ID and tool name in the namespaced tool identifier.
+ *
+ * Example: `"acme.linear:search-issues"`
+ */
+export const TOOL_NAMESPACE_SEPARATOR = ":";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A registered tool entry stored in the registry.
+ *
+ * Combines the manifest-level declaration with routing metadata so the host
+ * can resolve a namespaced tool name → plugin worker in O(1).
+ */
+export interface RegisteredTool {
+ /** The plugin key used for namespacing (e.g. `"acme.linear"`). */
+ pluginId: string;
+ /**
+ * The plugin's database UUID, used for worker routing and availability
+ * checks. Falls back to `pluginId` when not provided (e.g. in tests
+ * where `id === pluginKey`).
+ */
+ pluginDbId: string;
+ /** The tool's bare name (without namespace prefix). */
+ name: string;
+ /** Fully namespaced identifier: `"<pluginId>:<toolName>"`. */
+ namespacedName: string;
+ /** Human-readable display name. */
+ displayName: string;
+ /** Description provided to the agent so it knows when to use this tool. */
+ description: string;
+ /** JSON Schema describing the tool's input parameters. */
+ parametersSchema: Record<string, unknown>;
+}
+
+/**
+ * Filter criteria for listing available tools.
+ */
+export interface ToolListFilter {
+ /** Only return tools owned by this plugin. */
+ pluginId?: string;
+}
+
+/**
+ * Result of executing a tool, extending `ToolResult` with routing metadata.
+ */
+export interface ToolExecutionResult {
+ /** The plugin that handled the tool call. */
+ pluginId: string;
+ /** The bare tool name that was executed. */
+ toolName: string;
+ /** The result returned by the plugin's tool handler. */
+ result: ToolResult;
+}
+
+// ---------------------------------------------------------------------------
+// PluginToolRegistry interface
+// ---------------------------------------------------------------------------
+
+/**
+ * The host-side tool registry — held by the host process.
+ *
+ * Created once at server startup and shared across the application. Plugins
+ * register their tools when their worker starts, and unregister when the
+ * worker stops or the plugin is uninstalled.
+ */
+export interface PluginToolRegistry {
+ /**
+ * Register all tools declared in a plugin's manifest.
+ *
+ * Called when a plugin worker starts and its manifest is loaded. Any
+ * previously registered tools for the same plugin are replaced (idempotent).
+ *
+ * @param pluginId - The plugin's unique identifier (e.g. `"acme.linear"`)
+ * @param manifest - The plugin manifest containing the `tools` array
+ * @param pluginDbId - The plugin's database UUID, used for worker routing
+ * and availability checks. If omitted, `pluginId` is used (backwards-compat).
+ */
+ registerPlugin(pluginId: string, manifest: PaperclipPluginManifestV1, pluginDbId?: string): void;
+
+ /**
+ * Remove all tool registrations for a plugin.
+ *
+ * Called when a plugin worker stops, crashes, or is uninstalled.
+ *
+ * @param pluginId - The plugin to clear
+ */
+ unregisterPlugin(pluginId: string): void;
+
+ /**
+ * Look up a registered tool by its namespaced name.
+ *
+ * @param namespacedName - Fully qualified name, e.g. `"acme.linear:search-issues"`
+ * @returns The registered tool entry, or `null` if not found
+ */
+ getTool(namespacedName: string): RegisteredTool | null;
+
+ /**
+ * Look up a registered tool by plugin ID and bare tool name.
+ *
+ * @param pluginId - The owning plugin
+ * @param toolName - The bare tool name (without namespace prefix)
+ * @returns The registered tool entry, or `null` if not found
+ */
+ getToolByPlugin(pluginId: string, toolName: string): RegisteredTool | null;
+
+ /**
+ * List all registered tools, optionally filtered.
+ *
+ * @param filter - Optional filter criteria
+ * @returns Array of registered tool entries
+ */
+ listTools(filter?: ToolListFilter): RegisteredTool[];
+
+ /**
+ * Parse a namespaced tool name into plugin ID and bare tool name.
+ *
+ * @param namespacedName - e.g. `"acme.linear:search-issues"`
+ * @returns `{ pluginId, toolName }` or `null` if the format is invalid
+ */
+ parseNamespacedName(namespacedName: string): { pluginId: string; toolName: string } | null;
+
+ /**
+ * Build a namespaced tool name from a plugin ID and bare tool name.
+ *
+ * @param pluginId - e.g. `"acme.linear"`
+ * @param toolName - e.g. `"search-issues"`
+ * @returns The namespaced name, e.g. `"acme.linear:search-issues"`
+ */
+ buildNamespacedName(pluginId: string, toolName: string): string;
+
+ /**
+ * Execute a tool by its namespaced name, routing to the correct plugin worker.
+ *
+ * Resolves the namespaced name to the owning plugin, validates the tool
+ * exists, and dispatches the `executeTool` RPC call to the worker.
+ *
+ * @param namespacedName - Fully qualified tool name (e.g. `"acme.linear:search-issues"`)
+ * @param parameters - The parsed parameters matching the tool's schema
+ * @param runContext - Agent run context
+ * @returns The execution result with routing metadata
+ * @throws {Error} if the tool is not found or the worker is not running
+ */
+ executeTool(
+ namespacedName: string,
+ parameters: unknown,
+ runContext: ToolRunContext,
+ ): Promise<ToolExecutionResult>;
+
+ /**
+ * Get the number of registered tools, optionally scoped to a plugin.
+ *
+ * @param pluginId - If provided, count only this plugin's tools
+ */
+ toolCount(pluginId?: string): number;
+}
+
+// ---------------------------------------------------------------------------
+// Factory: createPluginToolRegistry
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new `PluginToolRegistry`.
+ *
+ * The registry is backed by two in-memory maps:
+ * - `byNamespace`: namespaced name → `RegisteredTool` for O(1) lookups.
+ * - `byPlugin`: pluginId → Set of namespaced names for efficient per-plugin ops.
+ *
+ * @param workerManager - The worker manager used to dispatch `executeTool` RPC
+ * calls to plugin workers. If not provided, `executeTool` will throw.
+ *
+ * @example
+ * ```ts
+ * const toolRegistry = createPluginToolRegistry(workerManager);
+ *
+ * // Register tools from a plugin manifest
+ * toolRegistry.registerPlugin("acme.linear", linearManifest);
+ *
+ * // List all available tools for agents
+ * const tools = toolRegistry.listTools();
+ * // → [{ namespacedName: "acme.linear:search-issues", ... }]
+ *
+ * // Execute a tool
+ * const result = await toolRegistry.executeTool(
+ * "acme.linear:search-issues",
+ * { query: "auth bug" },
+ * { agentId: "agent-1", runId: "run-1", companyId: "co-1", projectId: "proj-1" },
+ * );
+ * ```
+ */
+export function createPluginToolRegistry(
+ workerManager?: PluginWorkerManager,
+): PluginToolRegistry {
+ const log = logger.child({ service: "plugin-tool-registry" });
+
+ // Primary index: namespaced name → tool entry
+ const byNamespace = new Map<string, RegisteredTool>();
+
+ // Secondary index: pluginId → set of namespaced names (for bulk operations)
+ const byPlugin = new Map<string, Set<string>>();
+
+ // -----------------------------------------------------------------------
+ // Internal helpers
+ // -----------------------------------------------------------------------
+
+ function buildName(pluginId: string, toolName: string): string {
+ return `${pluginId}${TOOL_NAMESPACE_SEPARATOR}${toolName}`;
+ }
+
+ function parseName(namespacedName: string): { pluginId: string; toolName: string } | null {
+ const sepIndex = namespacedName.lastIndexOf(TOOL_NAMESPACE_SEPARATOR);
+ if (sepIndex <= 0 || sepIndex >= namespacedName.length - 1) {
+ return null;
+ }
+ return {
+ pluginId: namespacedName.slice(0, sepIndex),
+ toolName: namespacedName.slice(sepIndex + 1),
+ };
+ }
+
+ function addTool(pluginId: string, decl: PluginToolDeclaration, pluginDbId: string): void {
+ const namespacedName = buildName(pluginId, decl.name);
+
+ const entry: RegisteredTool = {
+ pluginId,
+ pluginDbId,
+ name: decl.name,
+ namespacedName,
+ displayName: decl.displayName,
+ description: decl.description,
+ parametersSchema: decl.parametersSchema,
+ };
+
+ byNamespace.set(namespacedName, entry);
+
+ let pluginTools = byPlugin.get(pluginId);
+ if (!pluginTools) {
+ pluginTools = new Set();
+ byPlugin.set(pluginId, pluginTools);
+ }
+ pluginTools.add(namespacedName);
+ }
+
+ function removePluginTools(pluginId: string): number {
+ const pluginTools = byPlugin.get(pluginId);
+ if (!pluginTools) return 0;
+
+ const count = pluginTools.size;
+ for (const name of pluginTools) {
+ byNamespace.delete(name);
+ }
+ byPlugin.delete(pluginId);
+
+ return count;
+ }
+
+ // -----------------------------------------------------------------------
+ // Public API
+ // -----------------------------------------------------------------------
+
+ return {
+ registerPlugin(pluginId: string, manifest: PaperclipPluginManifestV1, pluginDbId?: string): void {
+ const dbId = pluginDbId ?? pluginId;
+
+ // Remove any previously registered tools for this plugin (idempotent)
+ const previousCount = removePluginTools(pluginId);
+ if (previousCount > 0) {
+ log.debug(
+ { pluginId, previousCount },
+ "cleared previous tool registrations before re-registering",
+ );
+ }
+
+ const tools = manifest.tools ?? [];
+ if (tools.length === 0) {
+ log.debug({ pluginId }, "plugin declares no tools");
+ return;
+ }
+
+ for (const decl of tools) {
+ addTool(pluginId, decl, dbId);
+ }
+
+ log.info(
+ {
+ pluginId,
+ toolCount: tools.length,
+ tools: tools.map((t) => buildName(pluginId, t.name)),
+ },
+ `registered ${tools.length} tool(s) for plugin`,
+ );
+ },
+
+ unregisterPlugin(pluginId: string): void {
+ const removed = removePluginTools(pluginId);
+ if (removed > 0) {
+ log.info(
+ { pluginId, removedCount: removed },
+ `unregistered ${removed} tool(s) for plugin`,
+ );
+ }
+ },
+
+ getTool(namespacedName: string): RegisteredTool | null {
+ return byNamespace.get(namespacedName) ?? null;
+ },
+
+ getToolByPlugin(pluginId: string, toolName: string): RegisteredTool | null {
+ const namespacedName = buildName(pluginId, toolName);
+ return byNamespace.get(namespacedName) ?? null;
+ },
+
+ listTools(filter?: ToolListFilter): RegisteredTool[] {
+ if (filter?.pluginId) {
+ const pluginTools = byPlugin.get(filter.pluginId);
+ if (!pluginTools) return [];
+ const result: RegisteredTool[] = [];
+ for (const name of pluginTools) {
+ const tool = byNamespace.get(name);
+ if (tool) result.push(tool);
+ }
+ return result;
+ }
+
+ return Array.from(byNamespace.values());
+ },
+
+ parseNamespacedName(namespacedName: string): { pluginId: string; toolName: string } | null {
+ return parseName(namespacedName);
+ },
+
+ buildNamespacedName(pluginId: string, toolName: string): string {
+ return buildName(pluginId, toolName);
+ },
+
+ async executeTool(
+ namespacedName: string,
+ parameters: unknown,
+ runContext: ToolRunContext,
+ ): Promise<ToolExecutionResult> {
+ // 1. Resolve the namespaced name
+ const parsed = parseName(namespacedName);
+ if (!parsed) {
+ throw new Error(
+ `Invalid tool name "${namespacedName}". Expected format: "<pluginId>${TOOL_NAMESPACE_SEPARATOR}<toolName>"`,
+ );
+ }
+
+ const { pluginId, toolName } = parsed;
+
+ // 2. Verify the tool is registered
+ const tool = byNamespace.get(namespacedName);
+ if (!tool) {
+ throw new Error(
+ `Tool "${namespacedName}" is not registered. ` +
+ `The plugin may not be installed or its worker may not be running.`,
+ );
+ }
+
+ // 3. Verify the worker manager is available
+ if (!workerManager) {
+ throw new Error(
+ `Cannot execute tool "${namespacedName}" — no worker manager configured. ` +
+ `Tool execution requires a PluginWorkerManager.`,
+ );
+ }
+
+ // 4. Verify the plugin worker is running (use DB UUID for worker lookup)
+ const dbId = tool.pluginDbId;
+ if (!workerManager.isRunning(dbId)) {
+ throw new Error(
+ `Cannot execute tool "${namespacedName}" — ` +
+ `worker for plugin "${pluginId}" is not running.`,
+ );
+ }
+
+ // 5. Dispatch the executeTool RPC call to the worker
+ log.debug(
+ { pluginId, pluginDbId: dbId, toolName, namespacedName, agentId: runContext.agentId, runId: runContext.runId },
+ "executing tool via plugin worker",
+ );
+
+ const rpcParams: ExecuteToolParams = {
+ toolName,
+ parameters,
+ runContext,
+ };
+
+ const result = await workerManager.call(dbId, "executeTool", rpcParams);
+
+ log.debug(
+ {
+ pluginId,
+ toolName,
+ namespacedName,
+ hasContent: !!result.content,
+ hasData: result.data !== undefined,
+ hasError: !!result.error,
+ },
+ "tool execution completed",
+ );
+
+ return { pluginId, toolName, result };
+ },
+
+ toolCount(pluginId?: string): number {
+ if (pluginId !== undefined) {
+ return byPlugin.get(pluginId)?.size ?? 0;
+ }
+ return byNamespace.size;
+ },
+ };
+}
diff --git a/server/src/services/plugin-worker-manager.ts b/server/src/services/plugin-worker-manager.ts
new file mode 100644
index 0000000000..b55ba1bcdf
--- /dev/null
+++ b/server/src/services/plugin-worker-manager.ts
@@ -0,0 +1,1342 @@
+/**
+ * PluginWorkerManager — spawns and manages out-of-process plugin worker child
+ * processes, routes JSON-RPC 2.0 calls over stdio, and handles lifecycle
+ * management including crash recovery with exponential backoff.
+ *
+ * Each installed plugin gets one dedicated worker process. The host sends
+ * JSON-RPC requests over the child's stdin and reads responses from stdout.
+ * Worker stderr is captured and forwarded to the host logger.
+ *
+ * Process Model (from PLUGIN_SPEC.md §12):
+ * - One worker process per installed plugin
+ * - Failure isolation: plugin crashes do not affect the host
+ * - Graceful shutdown: 10-second drain, then SIGTERM, then SIGKILL
+ * - Automatic restart with exponential backoff on unexpected exits
+ *
+ * @see PLUGIN_SPEC.md §12 — Process Model
+ * @see PLUGIN_SPEC.md §12.5 — Graceful Shutdown Policy
+ * @see PLUGIN_SPEC.md §13 — Host-Worker Protocol
+ */
+
+import { fork, type ChildProcess } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { createInterface, type Interface as ReadlineInterface } from "node:readline";
+import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";
+import {
+ JSONRPC_VERSION,
+ JSONRPC_ERROR_CODES,
+ PLUGIN_RPC_ERROR_CODES,
+ createRequest,
+ createErrorResponse,
+ parseMessage,
+ serializeMessage,
+ isJsonRpcResponse,
+ isJsonRpcRequest,
+ isJsonRpcNotification,
+ isJsonRpcSuccessResponse,
+ JsonRpcParseError,
+ JsonRpcCallError,
+} from "@paperclipai/plugin-sdk";
+import type {
+ JsonRpcId,
+ JsonRpcResponse,
+ JsonRpcRequest,
+ JsonRpcNotification,
+ HostToWorkerMethodName,
+ HostToWorkerMethods,
+ WorkerToHostMethodName,
+ WorkerToHostMethods,
+ InitializeParams,
+} from "@paperclipai/plugin-sdk";
+import { logger } from "../middleware/logger.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default timeout for RPC calls in milliseconds. */
+const DEFAULT_RPC_TIMEOUT_MS = 30_000;
+
+/** Hard upper bound for any RPC timeout (5 minutes). Prevents unbounded waits. */
+const MAX_RPC_TIMEOUT_MS = 5 * 60 * 1_000;
+
+/** Timeout for the initialize RPC call. */
+const INITIALIZE_TIMEOUT_MS = 15_000;
+
+/** Timeout for the shutdown RPC call before escalating to SIGTERM. */
+const SHUTDOWN_DRAIN_MS = 10_000;
+
+/** Time to wait after SIGTERM before sending SIGKILL. */
+const SIGTERM_GRACE_MS = 5_000;
+
+/** Minimum backoff delay for crash recovery (1 second). */
+const MIN_BACKOFF_MS = 1_000;
+
+/** Maximum backoff delay for crash recovery (5 minutes). */
+const MAX_BACKOFF_MS = 5 * 60 * 1_000;
+
+/** Backoff multiplier on each consecutive crash. */
+const BACKOFF_MULTIPLIER = 2;
+
+/** Maximum number of consecutive crashes before giving up on auto-restart. */
+const MAX_CONSECUTIVE_CRASHES = 10;
+
+/** Time window in which crashes are considered consecutive (10 minutes). */
+const CRASH_WINDOW_MS = 10 * 60 * 1_000;
+
+/** Maximum number of stderr characters retained for worker failure context. */
+const MAX_STDERR_EXCERPT_CHARS = 8_000;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Status of a managed worker process.
+ */
+export type WorkerStatus =
+ | "stopped"
+ | "starting"
+ | "running"
+ | "stopping"
+ | "crashed"
+ | "backoff";
+
+/**
+ * Worker-to-host method handler. The host registers these to service calls
+ * that the plugin worker makes back to the host (e.g. state.get, events.emit).
+ */
+export type WorkerToHostHandler<M extends WorkerToHostMethodName> = (
+ params: WorkerToHostMethods[M][0],
+) => Promise<WorkerToHostMethods[M][1]>;
+
+/**
+ * A map of all worker-to-host method handlers provided by the host.
+ */
+export type WorkerToHostHandlers = {
+ [M in WorkerToHostMethodName]?: WorkerToHostHandler<M>;
+};
+
+/**
+ * Events emitted by a PluginWorkerHandle.
+ */
+export interface WorkerHandleEvents {
+ /** Worker process started and is ready (initialize succeeded). */
+ "ready": { pluginId: string };
+ /** Worker process exited. */
+ "exit": { pluginId: string; code: number | null; signal: NodeJS.Signals | null };
+ /** Worker process crashed unexpectedly. */
+ "crash": { pluginId: string; code: number | null; signal: NodeJS.Signals | null; willRestart: boolean };
+ /** Worker process errored (e.g. spawn failure). */
+ "error": { pluginId: string; error: Error };
+ /** Worker status changed. */
+ "status": { pluginId: string; status: WorkerStatus; previousStatus: WorkerStatus };
+}
+
+type WorkerHandleEventName = keyof WorkerHandleEvents;
+
+export function appendStderrExcerpt(current: string, chunk: string): string {
+ const next = current ? `${current}\n${chunk}` : chunk;
+ return next.length <= MAX_STDERR_EXCERPT_CHARS
+ ? next
+ : next.slice(-MAX_STDERR_EXCERPT_CHARS);
+}
+
+export function formatWorkerFailureMessage(message: string, stderrExcerpt: string): string {
+ const excerpt = stderrExcerpt.trim();
+ if (!excerpt) return message;
+ if (message.includes(excerpt)) return message;
+ return `${message}\n\nWorker stderr:\n${excerpt}`;
+}
+
+/**
+ * Options for starting a worker process.
+ */
+export interface WorkerStartOptions {
+ /** Absolute path to the plugin worker entrypoint (CJS bundle). */
+ entrypointPath: string;
+ /** Plugin manifest. */
+ manifest: PaperclipPluginManifestV1;
+ /** Resolved plugin configuration. */
+ config: Record<string, unknown>;
+ /** Host instance information for the initialize call. */
+ instanceInfo: {
+ instanceId: string;
+ hostVersion: string;
+ };
+ /** Host API version. */
+ apiVersion: number;
+ /** Handlers for worker→host RPC calls. */
+ hostHandlers: WorkerToHostHandlers;
+ /** Default timeout for RPC calls (ms). Defaults to 30s. */
+ rpcTimeoutMs?: number;
+ /** Whether to auto-restart on crash. Defaults to true. */
+ autoRestart?: boolean;
+ /** Node.js execArgv passed to the child process. */
+ execArgv?: string[];
+ /** Environment variables passed to the child process. */
+ env?: Record<string, string>;
+ /**
+ * Callback for stream notifications from the worker (streams.open/emit/close).
+ * The host wires this to the PluginStreamBus to fan out events to SSE clients.
+ */
+ onStreamNotification?: (method: string, params: Record<string, unknown>) => void;
+}
+
+/**
+ * A pending RPC call waiting for a response from the worker.
+ */
+interface PendingRequest {
+ /** The request ID. */
+ id: JsonRpcId;
+ /** Method name (for logging). */
+ method: string;
+ /** Resolve the promise with the response. */
+ resolve: (response: JsonRpcResponse) => void;
+ /** Timeout timer handle. */
+ timer: ReturnType<typeof setTimeout>;
+ /** Timestamp when the request was sent. */
+ sentAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// PluginWorkerHandle — manages a single worker process
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle for a single plugin worker process.
+ *
+ * Callers use `start()` to spawn the worker, `call()` to send RPC requests,
+ * and `stop()` to gracefully shut down. The handle manages crash recovery
+ * with exponential backoff automatically when `autoRestart` is enabled.
+ */
+export interface PluginWorkerHandle {
+ /** The plugin ID this worker serves. */
+ readonly pluginId: string;
+
+ /** Current worker status. */
+ readonly status: WorkerStatus;
+
+ /** Start the worker process. Resolves when initialize completes. */
+ start(): Promise<void>;
+
+ /**
+ * Stop the worker process gracefully.
+ *
+ * Sends a `shutdown` RPC call, waits up to 10 seconds for the worker to
+ * exit, then escalates to SIGTERM, and finally SIGKILL if needed.
+ */
+ stop(): Promise<void>;
+
+ /**
+ * Restart the worker process (stop + start).
+ */
+ restart(): Promise<void>;
+
+ /**
+ * Send a typed host→worker RPC call.
+ *
+ * @param method - The RPC method name
+ * @param params - Method parameters
+ * @param timeoutMs - Optional per-call timeout override
+ * @returns The method result
+ * @throws {JsonRpcCallError} if the worker returns an error response
+ * @throws {Error} if the worker is not running or the call times out
+ */
+ call<M extends HostToWorkerMethodName>(
+ method: M,
+ params: HostToWorkerMethods[M][0],
+ timeoutMs?: number,
+ ): Promise<HostToWorkerMethods[M][1]>;
+
+ /**
+ * Send a fire-and-forget notification to the worker (no response expected).
+ */
+ notify(method: string, params: unknown): void;
+
+ /** Subscribe to worker events. */
+ on<K extends WorkerHandleEventName>(
+ event: K,
+ listener: (payload: WorkerHandleEvents[K]) => void,
+ ): void;
+
+ /** Unsubscribe from worker events. */
+ off<K extends WorkerHandleEventName>(
+ event: K,
+ listener: (payload: WorkerHandleEvents[K]) => void,
+ ): void;
+
+ /** Optional methods the worker reported during initialization. */
+ readonly supportedMethods: string[];
+
+ /** Get diagnostic info about the worker. */
+ diagnostics(): WorkerDiagnostics;
+}
+
+/**
+ * Diagnostic information about a worker process.
+ */
+export interface WorkerDiagnostics {
+ pluginId: string;
+ status: WorkerStatus;
+ pid: number | null;
+ uptime: number | null;
+ consecutiveCrashes: number;
+ totalCrashes: number;
+ pendingRequests: number;
+ lastCrashAt: number | null;
+ nextRestartAt: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// PluginWorkerManager — manages all plugin workers
+// ---------------------------------------------------------------------------
+
+/**
+ * The top-level manager that holds all plugin worker handles.
+ *
+ * Provides a registry of workers keyed by plugin ID, with convenience methods
+ * for starting/stopping all workers and routing RPC calls.
+ */
+export interface PluginWorkerManager {
+ /**
+ * Register and start a worker for a plugin.
+ *
+ * @returns The worker handle
+ * @throws if a worker is already registered for this plugin
+ */
+ startWorker(pluginId: string, options: WorkerStartOptions): Promise<PluginWorkerHandle>;
+
+ /**
+ * Stop and unregister a specific plugin worker.
+ */
+ stopWorker(pluginId: string): Promise<void>;
+
+ /**
+ * Get the worker handle for a plugin.
+ */
+ getWorker(pluginId: string): PluginWorkerHandle | undefined;
+
+ /**
+ * Check if a worker is registered and running for a plugin.
+ */
+ isRunning(pluginId: string): boolean;
+
+ /**
+ * Stop all managed workers. Called during server shutdown.
+ */
+ stopAll(): Promise<void>;
+
+ /**
+ * Get diagnostic info for all workers.
+ */
+ diagnostics(): WorkerDiagnostics[];
+
+ /**
+ * Send an RPC call to a specific plugin worker.
+ *
+ * @throws if the worker is not running
+ */
+ call<M extends HostToWorkerMethodName>(
+ pluginId: string,
+ method: M,
+ params: HostToWorkerMethods[M][0],
+ timeoutMs?: number,
+ ): Promise<HostToWorkerMethods[M][1]>;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation: createPluginWorkerHandle
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a handle for a single plugin worker process.
+ *
+ * @internal Exported for testing; consumers should use `createPluginWorkerManager`.
+ */
+export function createPluginWorkerHandle(
+ pluginId: string,
+ options: WorkerStartOptions,
+): PluginWorkerHandle {
+ const log = logger.child({ service: "plugin-worker", pluginId });
+ const emitter = new EventEmitter();
+ /**
+ * Higher than default (10) to accommodate multiple subscribers to
+ * crash/ready/exit events during integration tests and runtime monitoring.
+ */
+ emitter.setMaxListeners(50);
+
+ // Worker process state
+ let childProcess: ChildProcess | null = null;
+ let readline: ReadlineInterface | null = null;
+ let stderrReadline: ReadlineInterface | null = null;
+ let status: WorkerStatus = "stopped";
+ let startedAt: number | null = null;
+ let stderrExcerpt = "";
+
+ // Pending RPC requests awaiting a response
+ const pendingRequests = new Map<string | number, PendingRequest>();
+ let nextRequestId = 1;
+
+ // Optional methods reported by the worker during initialization
+ let supportedMethods: string[] = [];
+
+ // Crash tracking for exponential backoff
+ let consecutiveCrashes = 0;
+ let totalCrashes = 0;
+ let lastCrashAt: number | null = null;
+ let backoffTimer: ReturnType<typeof setTimeout> | null = null;
+ let nextRestartAt: number | null = null;
+
+ // Track open stream channels so we can emit synthetic close on crash.
+ // Maps channel → companyId.
+ const openStreamChannels = new Map<string, string>();
+
+ // Shutdown coordination
+ let intentionalStop = false;
+
+ const rpcTimeoutMs = options.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS;
+ const autoRestart = options.autoRestart ?? true;
+
+ // -----------------------------------------------------------------------
+ // Status management
+ // -----------------------------------------------------------------------
+
+ function setStatus(newStatus: WorkerStatus): void {
+ const prev = status;
+ if (prev === newStatus) return;
+ status = newStatus;
+ log.debug({ from: prev, to: newStatus }, "worker status change");
+ emitter.emit("status", { pluginId, status: newStatus, previousStatus: prev });
+ }
+
+ // -----------------------------------------------------------------------
+ // JSON-RPC message sending
+ // -----------------------------------------------------------------------
+
+ function sendMessage(message: unknown): void {
+ if (!childProcess?.stdin?.writable) {
+ throw new Error(`Worker process for plugin "${pluginId}" is not writable`);
+ }
+ const serialized = serializeMessage(message as any);
+ childProcess.stdin.write(serialized);
+ }
+
+ // -----------------------------------------------------------------------
+ // Incoming message handling
+ // -----------------------------------------------------------------------
+
+ function handleLine(line: string): void {
+ if (!line.trim()) return;
+
+ let message: unknown;
+ try {
+ message = parseMessage(line);
+ } catch (err) {
+ if (err instanceof JsonRpcParseError) {
+ log.warn({ rawLine: line.slice(0, 200) }, "unparseable message from worker");
+ } else {
+ log.warn({ err }, "error parsing worker message");
+ }
+ return;
+ }
+
+ if (isJsonRpcResponse(message)) {
+ handleResponse(message);
+ } else if (isJsonRpcRequest(message)) {
+ handleWorkerRequest(message as JsonRpcRequest);
+ } else if (isJsonRpcNotification(message)) {
+ handleWorkerNotification(message as JsonRpcNotification);
+ } else {
+ log.warn("unknown message type from worker");
+ }
+ }
+
+ /**
+ * Handle a JSON-RPC response from the worker (matching a pending request).
+ */
+ function handleResponse(response: JsonRpcResponse): void {
+ const id = response.id;
+ if (id === null || id === undefined) {
+ log.warn("received response with null/undefined id");
+ return;
+ }
+
+ const pending = pendingRequests.get(id);
+ if (!pending) {
+ log.warn({ id }, "received response for unknown request id");
+ return;
+ }
+
+ clearTimeout(pending.timer);
+ pendingRequests.delete(id);
+ pending.resolve(response);
+ }
+
+ /**
+ * Handle a JSON-RPC request from the worker (worker→host call).
+ */
+ async function handleWorkerRequest(request: JsonRpcRequest): Promise<void> {
+ const method = request.method as WorkerToHostMethodName;
+ const handler = options.hostHandlers[method] as
+ | ((params: unknown) => Promise<unknown>)
+ | undefined;
+
+ if (!handler) {
+ log.warn({ method }, "worker called unregistered host method");
+ try {
+ sendMessage(
+ createErrorResponse(
+ request.id,
+ JSONRPC_ERROR_CODES.METHOD_NOT_FOUND,
+ `Host does not handle method "${method}"`,
+ ),
+ );
+ } catch {
+ // Worker may have exited, ignore send error
+ }
+ return;
+ }
+
+ try {
+ const result = await handler(request.params);
+ sendMessage({
+ jsonrpc: JSONRPC_VERSION,
+ id: request.id,
+ result: result ?? null,
+ });
+ } catch (err) {
+ const errorMessage = err instanceof Error ? err.message : String(err);
+ log.error({ method, err: errorMessage }, "host handler error");
+ try {
+ sendMessage(
+ createErrorResponse(
+ request.id,
+ JSONRPC_ERROR_CODES.INTERNAL_ERROR,
+ errorMessage,
+ ),
+ );
+ } catch {
+ // Worker may have exited, ignore send error
+ }
+ }
+ }
+
+ /**
+ * Handle a JSON-RPC notification from the worker (fire-and-forget).
+ *
+ * The `log` notification is the primary case — worker `ctx.logger` calls
+ * arrive here. We append structured plugin context (pluginId, timestamp,
+ * level) so that every log entry is queryable per the spec (§26.1).
+ */
+ function handleWorkerNotification(notification: JsonRpcNotification): void {
+ if (notification.method === "log") {
+ const params = notification.params as {
+ level?: string;
+ message?: string;
+ meta?: Record<string, unknown>;
+ } | null;
+ const level = params?.level ?? "info";
+ const msg = params?.message ?? "";
+ const meta = params?.meta;
+
+ // Build a structured log object that includes the plugin context fields
+ // required by §26.1: pluginId, timestamp, level, message, and metadata.
+ // The child logger already carries `pluginId` in its bindings, but we
+ // add explicit `pluginLogLevel` and `pluginTimestamp` so downstream
+ // consumers (log storage, UI queries) can filter without parsing.
+ const logFields: Record<string, unknown> = {
+ ...meta,
+ pluginLogLevel: level,
+ pluginTimestamp: new Date().toISOString(),
+ };
+
+ if (level === "error") {
+ log.error(logFields, `[plugin] ${msg}`);
+ } else if (level === "warn") {
+ log.warn(logFields, `[plugin] ${msg}`);
+ } else if (level === "debug") {
+ log.debug(logFields, `[plugin] ${msg}`);
+ } else {
+ log.info(logFields, `[plugin] ${msg}`);
+ }
+ return;
+ }
+
+ // Stream notifications: forward to the stream bus via callback
+ if (
+ notification.method === "streams.open" ||
+ notification.method === "streams.emit" ||
+ notification.method === "streams.close"
+ ) {
+ const params = (notification.params ?? {}) as Record<string, unknown>;
+
+ // Track open channels so we can emit synthetic close on crash
+ if (notification.method === "streams.open") {
+ const ch = String(params.channel ?? "");
+ const co = String(params.companyId ?? "");
+ if (ch) openStreamChannels.set(ch, co);
+ } else if (notification.method === "streams.close") {
+ openStreamChannels.delete(String(params.channel ?? ""));
+ }
+
+ if (options.onStreamNotification) {
+ try {
+ options.onStreamNotification(notification.method, params);
+ } catch (err) {
+ log.error(
+ {
+ method: notification.method,
+ err: err instanceof Error ? err.message : String(err),
+ },
+ "stream notification handler failed",
+ );
+ }
+ }
+ return;
+ }
+
+ log.debug({ method: notification.method }, "received notification from worker");
+ }
+
+ // -----------------------------------------------------------------------
+ // Process lifecycle
+ // -----------------------------------------------------------------------
+
+ function spawnProcess(): ChildProcess {
+ // Security: Do NOT spread process.env into the worker. Plugins should only
+ // receive a minimal, controlled environment to prevent leaking host
+ // secrets (like DATABASE_URL, internal API keys, etc.).
+ const workerEnv: Record<string, string> = {
+ ...options.env,
+ PATH: process.env.PATH ?? "",
+ NODE_PATH: process.env.NODE_PATH ?? "",
+ PAPERCLIP_PLUGIN_ID: pluginId,
+ NODE_ENV: process.env.NODE_ENV ?? "production",
+ TZ: process.env.TZ ?? "UTC",
+ };
+
+ const child = fork(options.entrypointPath, [], {
+ stdio: ["pipe", "pipe", "pipe", "ipc"],
+ execArgv: options.execArgv ?? [],
+ env: workerEnv,
+ // Don't let the child keep the parent alive
+ detached: false,
+ });
+
+ return child;
+ }
+
+ function attachStdioHandlers(child: ChildProcess): void {
+ // Read NDJSON from stdout
+ if (child.stdout) {
+ readline = createInterface({ input: child.stdout });
+ readline.on("line", handleLine);
+ }
+
+ // Capture stderr for logging
+ if (child.stderr) {
+ stderrReadline = createInterface({ input: child.stderr });
+ stderrReadline.on("line", (line: string) => {
+ stderrExcerpt = appendStderrExcerpt(stderrExcerpt, line);
+ log.warn({ stream: "stderr" }, `[plugin stderr] ${line}`);
+ });
+ }
+
+ // Handle process exit
+ child.on("exit", (code, signal) => {
+ handleProcessExit(code, signal);
+ });
+
+ // Handle process errors (e.g. spawn failure)
+ child.on("error", (err) => {
+ log.error({ err: err.message }, "worker process error");
+ emitter.emit("error", { pluginId, error: err });
+ if (status === "starting") {
+ setStatus("crashed");
+ rejectAllPending(
+ new Error(formatWorkerFailureMessage(
+ `Worker process failed to start: ${err.message}`,
+ stderrExcerpt,
+ )),
+ );
+ }
+ });
+ }
+
+ function handleProcessExit(
+ code: number | null,
+ signal: NodeJS.Signals | null,
+ ): void {
+ const wasIntentional = intentionalStop;
+
+ // Clean up readline interfaces
+ if (readline) {
+ readline.close();
+ readline = null;
+ }
+ if (stderrReadline) {
+ stderrReadline.close();
+ stderrReadline = null;
+ }
+ childProcess = null;
+ startedAt = null;
+
+ // Reject all pending requests
+ rejectAllPending(
+ new Error(formatWorkerFailureMessage(
+ `Worker process exited (code=${code}, signal=${signal})`,
+ stderrExcerpt,
+ )),
+ );
+
+ // Emit synthetic close for any orphaned stream channels so SSE clients
+ // are notified instead of hanging indefinitely.
+ if (openStreamChannels.size > 0 && options.onStreamNotification) {
+ for (const [channel, companyId] of openStreamChannels) {
+ try {
+ options.onStreamNotification("streams.close", { channel, companyId });
+ } catch {
+ // Best-effort cleanup — don't let it interfere with exit handling
+ }
+ }
+ openStreamChannels.clear();
+ }
+
+ emitter.emit("exit", { pluginId, code, signal });
+
+ if (wasIntentional) {
+ // Graceful stop — status is already "stopping" or will be set to "stopped"
+ setStatus("stopped");
+ log.info({ code, signal }, "worker process stopped");
+ return;
+ }
+
+ // Unexpected exit — crash recovery
+ totalCrashes++;
+ const now = Date.now();
+
+ // Reset consecutive crash counter if enough time passed
+ if (lastCrashAt !== null && now - lastCrashAt > CRASH_WINDOW_MS) {
+ consecutiveCrashes = 0;
+ }
+ consecutiveCrashes++;
+ lastCrashAt = now;
+
+ log.error(
+ { code, signal, consecutiveCrashes, totalCrashes },
+ "worker process crashed",
+ );
+
+ const willRestart =
+ autoRestart && consecutiveCrashes <= MAX_CONSECUTIVE_CRASHES;
+
+ setStatus("crashed");
+ emitter.emit("crash", { pluginId, code, signal, willRestart });
+
+ if (willRestart) {
+ scheduleRestart();
+ } else {
+ log.error(
+ { consecutiveCrashes, maxCrashes: MAX_CONSECUTIVE_CRASHES },
+ "max consecutive crashes reached, not restarting",
+ );
+ }
+ }
+
+ function rejectAllPending(error: Error): void {
+ for (const [id, pending] of pendingRequests) {
+ clearTimeout(pending.timer);
+ pending.resolve(
+ createErrorResponse(
+ pending.id,
+ PLUGIN_RPC_ERROR_CODES.WORKER_UNAVAILABLE,
+ error.message,
+ ) as JsonRpcResponse,
+ );
+ }
+ pendingRequests.clear();
+ }
+
+ // -----------------------------------------------------------------------
+ // Crash recovery with exponential backoff
+ // -----------------------------------------------------------------------
+
+ function computeBackoffMs(): number {
+ // Exponential backoff: MIN_BACKOFF * MULTIPLIER^(consecutiveCrashes - 1)
+ const delay =
+ MIN_BACKOFF_MS * Math.pow(BACKOFF_MULTIPLIER, consecutiveCrashes - 1);
+ // Add jitter: ±25%
+ const jitter = delay * 0.25 * (Math.random() * 2 - 1);
+ return Math.min(Math.round(delay + jitter), MAX_BACKOFF_MS);
+ }
+
+ function scheduleRestart(): void {
+ const delay = computeBackoffMs();
+ nextRestartAt = Date.now() + delay;
+
+ setStatus("backoff");
+
+ log.info(
+ { delayMs: delay, consecutiveCrashes },
+ "scheduling restart with backoff",
+ );
+
+ backoffTimer = setTimeout(async () => {
+ backoffTimer = null;
+ nextRestartAt = null;
+ try {
+ await startInternal();
+ } catch (err) {
+ log.error(
+ { err: err instanceof Error ? err.message : String(err) },
+ "restart after backoff failed",
+ );
+ }
+ }, delay);
+ }
+
+ function cancelPendingRestart(): void {
+ if (backoffTimer !== null) {
+ clearTimeout(backoffTimer);
+ backoffTimer = null;
+ nextRestartAt = null;
+ }
+ }
+
+ // -----------------------------------------------------------------------
+ // Start / Stop
+ // -----------------------------------------------------------------------
+
+ async function startInternal(): Promise<void> {
+ if (status === "running" || status === "starting") {
+ throw new Error(`Worker for plugin "${pluginId}" is already ${status}`);
+ }
+
+ intentionalStop = false;
+ setStatus("starting");
+ stderrExcerpt = "";
+
+ const child = spawnProcess();
+ childProcess = child;
+ attachStdioHandlers(child);
+ startedAt = Date.now();
+
+ // Send the initialize RPC call
+ const initParams: InitializeParams = {
+ manifest: options.manifest,
+ config: options.config,
+ instanceInfo: options.instanceInfo,
+ apiVersion: options.apiVersion,
+ };
+
+ try {
+ const result = await callInternal(
+ "initialize",
+ initParams,
+ INITIALIZE_TIMEOUT_MS,
+ ) as { ok?: boolean; supportedMethods?: string[] } | undefined;
+ if (!result || !result.ok) {
+ throw new Error("Worker initialize returned ok=false");
+ }
+ supportedMethods = result.supportedMethods ?? [];
+ } catch (err) {
+ // Initialize failed — kill the process and propagate
+ const msg = err instanceof Error ? err.message : String(err);
+ log.error({ err: msg }, "worker initialize failed");
+ await killProcess();
+ setStatus("crashed");
+ throw new Error(`Worker initialize failed for "${pluginId}": ${msg}`);
+ }
+
+ // Reset crash counter on successful start
+ consecutiveCrashes = 0;
+ setStatus("running");
+ emitter.emit("ready", { pluginId });
+ log.info({ pid: child.pid }, "worker process started and initialized");
+ }
+
+ async function stopInternal(): Promise<void> {
+ cancelPendingRestart();
+
+ if (status === "stopped" || status === "stopping") {
+ return;
+ }
+
+ intentionalStop = true;
+ setStatus("stopping");
+
+ if (!childProcess) {
+ setStatus("stopped");
+ return;
+ }
+
+ // Step 1: Send shutdown RPC and wait for the worker to exit gracefully.
+ // We race the shutdown call against a timeout. The worker should process
+ // the shutdown and exit on its own within the drain period.
+ try {
+ await Promise.race([
+ callInternal("shutdown", {} as Record<string, never>, SHUTDOWN_DRAIN_MS),
+ waitForExit(SHUTDOWN_DRAIN_MS),
+ ]);
+ } catch {
+ // Shutdown call failed or timed out — proceed to kill
+ log.warn("shutdown RPC failed or timed out, escalating to SIGTERM");
+ }
+
+ // Give the process a brief moment to exit after the shutdown response
+ if (childProcess) {
+ await waitForExit(500);
+ }
+
+ // Check if process already exited
+ if (!childProcess) {
+ setStatus("stopped");
+ return;
+ }
+
+ // Step 2: Send SIGTERM and wait
+ log.info("worker did not exit after shutdown RPC, sending SIGTERM");
+ await killWithSignal("SIGTERM", SIGTERM_GRACE_MS);
+
+ if (!childProcess) {
+ setStatus("stopped");
+ return;
+ }
+
+ // Step 3: Forcefully kill with SIGKILL
+ log.warn("worker did not exit after SIGTERM, sending SIGKILL");
+ await killWithSignal("SIGKILL", 2_000);
+
+ if (childProcess) {
+ log.error("worker process still alive after SIGKILL — this should not happen");
+ }
+
+ setStatus("stopped");
+ }
+
+ /**
+ * Wait for the child process to exit, up to `timeoutMs`.
+ * Resolves immediately if the process is already gone.
+ */
+ function waitForExit(timeoutMs: number): Promise<void> {
+ return new Promise<void>((resolve) => {
+ if (!childProcess) {
+ resolve();
+ return;
+ }
+
+ let settled = false;
+ const timer = setTimeout(() => {
+ if (settled) return;
+ settled = true;
+ resolve();
+ }, timeoutMs);
+
+ childProcess.once("exit", () => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ resolve();
+ });
+ });
+ }
+
+ function killWithSignal(
+ signal: NodeJS.Signals,
+ waitMs: number,
+ ): Promise<void> {
+ return new Promise<void>((resolve) => {
+ if (!childProcess) {
+ resolve();
+ return;
+ }
+
+ const timer = setTimeout(() => {
+ resolve();
+ }, waitMs);
+
+ childProcess.once("exit", () => {
+ clearTimeout(timer);
+ resolve();
+ });
+
+ try {
+ childProcess.kill(signal);
+ } catch {
+ clearTimeout(timer);
+ resolve();
+ }
+ });
+ }
+
+ async function killProcess(): Promise<void> {
+ if (!childProcess) return;
+ intentionalStop = true;
+ try {
+ childProcess.kill("SIGKILL");
+ } catch {
+ // Process may already be dead
+ }
+ // Wait briefly for exit event
+ await new Promise<void>((resolve) => {
+ if (!childProcess) {
+ resolve();
+ return;
+ }
+ const timer = setTimeout(() => {
+ resolve();
+ }, 1_000);
+ childProcess.once("exit", () => {
+ clearTimeout(timer);
+ resolve();
+ });
+ });
+ }
+
+ // -----------------------------------------------------------------------
+ // RPC call implementation
+ // -----------------------------------------------------------------------
+
+ function callInternal<M extends HostToWorkerMethodName>(
+ method: M,
+ params: HostToWorkerMethods[M][0],
+ timeoutMs?: number,
+ ): Promise<HostToWorkerMethods[M][1]> {
+ return new Promise<HostToWorkerMethods[M][1]>((resolve, reject) => {
+ if (!childProcess?.stdin?.writable) {
+ reject(
+ new Error(
+ `Cannot call "${method}" — worker for "${pluginId}" is not running`,
+ ),
+ );
+ return;
+ }
+
+ const id = nextRequestId++;
+ const timeout = Math.min(timeoutMs ?? rpcTimeoutMs, MAX_RPC_TIMEOUT_MS);
+
+ // Guard against double-settlement. When a process exits all pending
+ // requests are rejected via rejectAllPending(), but the timeout timer
+ // may still be running. Without this guard the timer's reject fires on
+ // an already-settled promise, producing an unhandled rejection.
+ let settled = false;
+
+ const settle = <T>(fn: (value: T) => void, value: T): void => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ pendingRequests.delete(id);
+ fn(value);
+ };
+
+ const timer = setTimeout(() => {
+ settle(
+ reject,
+ new JsonRpcCallError({
+ code: PLUGIN_RPC_ERROR_CODES.TIMEOUT,
+ message: `RPC call "${method}" timed out after ${timeout}ms`,
+ }),
+ );
+ }, timeout);
+
+ const pending: PendingRequest = {
+ id,
+ method,
+ resolve: (response: JsonRpcResponse) => {
+ if (isJsonRpcSuccessResponse(response)) {
+ settle(resolve, response.result as HostToWorkerMethods[M][1]);
+ } else if ("error" in response && response.error) {
+ settle(reject, new JsonRpcCallError(response.error));
+ } else {
+ settle(reject, new Error(`Unexpected response format for "${method}"`));
+ }
+ },
+ timer,
+ sentAt: Date.now(),
+ };
+
+ pendingRequests.set(id, pending);
+
+ try {
+ const request = createRequest(method, params, id);
+ sendMessage(request);
+ } catch (err) {
+ clearTimeout(timer);
+ pendingRequests.delete(id);
+ reject(
+ new Error(
+ `Failed to send "${method}" to worker: ${
+ err instanceof Error ? err.message : String(err)
+ }`,
+ ),
+ );
+ }
+ });
+ }
+
+ // -----------------------------------------------------------------------
+ // Public API
+ // -----------------------------------------------------------------------
+
+ const handle: PluginWorkerHandle = {
+ get pluginId() {
+ return pluginId;
+ },
+
+ get status() {
+ return status;
+ },
+
+ get supportedMethods() {
+ return supportedMethods;
+ },
+
+ async start() {
+ await startInternal();
+ },
+
+ async stop() {
+ await stopInternal();
+ },
+
+ async restart() {
+ await stopInternal();
+ await startInternal();
+ },
+
+ call<M extends HostToWorkerMethodName>(
+ method: M,
+ params: HostToWorkerMethods[M][0],
+ timeoutMs?: number,
+ ): Promise<HostToWorkerMethods[M][1]> {
+ if (status !== "running" && status !== "starting") {
+ return Promise.reject(
+ new Error(
+ `Cannot call "${method}" — worker for "${pluginId}" is ${status}`,
+ ),
+ );
+ }
+ return callInternal(method, params, timeoutMs);
+ },
+
+ notify(method: string, params: unknown) {
+ if (status !== "running") return;
+ try {
+ sendMessage({
+ jsonrpc: JSONRPC_VERSION,
+ method,
+ params,
+ });
+ } catch {
+ log.warn({ method }, "failed to send notification to worker");
+ }
+ },
+
+ on<K extends WorkerHandleEventName>(
+ event: K,
+ listener: (payload: WorkerHandleEvents[K]) => void,
+ ) {
+ emitter.on(event, listener);
+ },
+
+ off<K extends WorkerHandleEventName>(
+ event: K,
+ listener: (payload: WorkerHandleEvents[K]) => void,
+ ) {
+ emitter.off(event, listener);
+ },
+
+ diagnostics(): WorkerDiagnostics {
+ return {
+ pluginId,
+ status,
+ pid: childProcess?.pid ?? null,
+ uptime:
+ startedAt !== null && status === "running"
+ ? Date.now() - startedAt
+ : null,
+ consecutiveCrashes,
+ totalCrashes,
+ pendingRequests: pendingRequests.size,
+ lastCrashAt,
+ nextRestartAt,
+ };
+ },
+ };
+
+ return handle;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation: createPluginWorkerManager
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for creating a PluginWorkerManager.
+ */
+export interface PluginWorkerManagerOptions {
+ /**
+ * Optional callback invoked when a worker emits a lifecycle event
+ * (crash, restart). Used by the server to publish global live events.
+ */
+ onWorkerEvent?: (event: {
+ type: "plugin.worker.crashed" | "plugin.worker.restarted";
+ pluginId: string;
+ code?: number | null;
+ signal?: string | null;
+ willRestart?: boolean;
+ }) => void;
+}
+
+/**
+ * Create a new PluginWorkerManager.
+ *
+ * The manager holds all plugin worker handles and provides a unified API for
+ * starting, stopping, and communicating with plugin workers.
+ *
+ * @example
+ * ```ts
+ * const manager = createPluginWorkerManager();
+ *
+ * const handle = await manager.startWorker("acme.linear", {
+ * entrypointPath: "/path/to/worker.cjs",
+ * manifest,
+ * config: resolvedConfig,
+ * instanceInfo: { instanceId: "inst-1", hostVersion: "1.0.0" },
+ * apiVersion: 1,
+ * hostHandlers: { "config.get": async () => resolvedConfig, ... },
+ * });
+ *
+ * // Send RPC call to the worker
+ * const health = await manager.call("acme.linear", "health", {});
+ *
+ * // Shutdown all workers on server exit
+ * await manager.stopAll();
+ * ```
+ */
+export function createPluginWorkerManager(
+ managerOptions?: PluginWorkerManagerOptions,
+): PluginWorkerManager {
+ const log = logger.child({ service: "plugin-worker-manager" });
+ const workers = new Map<string, PluginWorkerHandle>();
+ /** Per-plugin startup locks to prevent concurrent spawn races. */
+ const startupLocks = new Map<string, Promise<PluginWorkerHandle>>();
+
+ return {
+ async startWorker(
+ pluginId: string,
+ options: WorkerStartOptions,
+ ): Promise<PluginWorkerHandle> {
+ // Mutex: if a start is already in-flight for this plugin, wait for it
+ const inFlight = startupLocks.get(pluginId);
+ if (inFlight) {
+ log.warn({ pluginId }, "concurrent startWorker call — waiting for in-flight start");
+ return inFlight;
+ }
+
+ const existing = workers.get(pluginId);
+ if (existing && existing.status !== "stopped") {
+ throw new Error(
+ `Worker already registered for plugin "${pluginId}" (status: ${existing.status})`,
+ );
+ }
+
+ const handle = createPluginWorkerHandle(pluginId, options);
+ workers.set(pluginId, handle);
+
+ // Subscribe to crash/ready events for live event forwarding
+ if (managerOptions?.onWorkerEvent) {
+ const notify = managerOptions.onWorkerEvent;
+ handle.on("crash", (payload) => {
+ notify({
+ type: "plugin.worker.crashed",
+ pluginId: payload.pluginId,
+ code: payload.code,
+ signal: payload.signal,
+ willRestart: payload.willRestart,
+ });
+ });
+ handle.on("ready", (payload) => {
+ // Only emit restarted if this was a crash recovery (totalCrashes > 0)
+ const diag = handle.diagnostics();
+ if (diag.totalCrashes > 0) {
+ notify({
+ type: "plugin.worker.restarted",
+ pluginId: payload.pluginId,
+ });
+ }
+ });
+ }
+
+ log.info({ pluginId }, "starting plugin worker");
+
+ // Set the lock before awaiting start() to prevent concurrent spawns
+ const startPromise = handle.start().then(() => handle).finally(() => {
+ startupLocks.delete(pluginId);
+ });
+ startupLocks.set(pluginId, startPromise);
+
+ return startPromise;
+ },
+
+ async stopWorker(pluginId: string): Promise<void> {
+ const handle = workers.get(pluginId);
+ if (!handle) {
+ log.warn({ pluginId }, "no worker registered for plugin, nothing to stop");
+ return;
+ }
+
+ log.info({ pluginId }, "stopping plugin worker");
+ await handle.stop();
+ workers.delete(pluginId);
+ },
+
+ getWorker(pluginId: string): PluginWorkerHandle | undefined {
+ return workers.get(pluginId);
+ },
+
+ isRunning(pluginId: string): boolean {
+ const handle = workers.get(pluginId);
+ return handle?.status === "running";
+ },
+
+ async stopAll(): Promise<void> {
+ log.info({ count: workers.size }, "stopping all plugin workers");
+ const promises = Array.from(workers.values()).map(async (handle) => {
+ try {
+ await handle.stop();
+ } catch (err) {
+ log.error(
+ {
+ pluginId: handle.pluginId,
+ err: err instanceof Error ? err.message : String(err),
+ },
+ "error stopping worker during shutdown",
+ );
+ }
+ });
+ await Promise.all(promises);
+ workers.clear();
+ },
+
+ diagnostics(): WorkerDiagnostics[] {
+ return Array.from(workers.values()).map((h) => h.diagnostics());
+ },
+
+ call<M extends HostToWorkerMethodName>(
+ pluginId: string,
+ method: M,
+ params: HostToWorkerMethods[M][0],
+ timeoutMs?: number,
+ ): Promise<HostToWorkerMethods[M][1]> {
+ const handle = workers.get(pluginId);
+ if (!handle) {
+ return Promise.reject(
+ new Error(`No worker registered for plugin "${pluginId}"`),
+ );
+ }
+ return handle.call(method, params, timeoutMs);
+ },
+ };
+}
diff --git a/ui/src/App.tsx b/ui/src/App.tsx
index 1cfdd9dfdd..a05bbcec76 100644
--- a/ui/src/App.tsx
+++ b/ui/src/App.tsx
@@ -24,6 +24,9 @@ import { Inbox } from "./pages/Inbox";
import { CompanySettings } from "./pages/CompanySettings";
import { DesignGuide } from "./pages/DesignGuide";
import { InstanceSettings } from "./pages/InstanceSettings";
+import { PluginManager } from "./pages/PluginManager";
+import { PluginSettings } from "./pages/PluginSettings";
+import { PluginPage } from "./pages/PluginPage";
import { RunTranscriptUxLab } from "./pages/RunTranscriptUxLab";
import { OrgChart } from "./pages/OrgChart";
import { NewAgent } from "./pages/NewAgent";
@@ -113,6 +116,7 @@ function boardRoutes() {
<Route path="company/settings" element={<CompanySettings />} />
<Route path="settings" element={<LegacySettingsRedirect />} />
<Route path="settings/*" element={<LegacySettingsRedirect />} />
+ <Route path="plugins/:pluginId" element={<PluginPage />} />
<Route path="org" element={<OrgChart />} />
<Route path="agents" element={<Navigate to="/agents/all" replace />} />
<Route path="agents/all" element={<Agents />} />
@@ -162,7 +166,7 @@ function InboxRootRedirect() {
function LegacySettingsRedirect() {
const location = useLocation();
- return <Navigate to={`/instance/settings${location.search}${location.hash}`} replace />;
+ return <Navigate to={`/instance/settings/heartbeats${location.search}${location.hash}`} replace />;
}
function OnboardingRoutePage() {
@@ -295,9 +299,12 @@ export function App() {
<Route element={<CloudAccessGate />}>
<Route index element={<CompanyRootRedirect />} />
<Route path="onboarding" element={<OnboardingRoutePage />} />
- <Route path="instance" element={<Navigate to="/instance/settings" replace />} />
+ <Route path="instance" element={<Navigate to="/instance/settings/heartbeats" replace />} />
<Route path="instance/settings" element={<Layout />}>
- <Route index element={<InstanceSettings />} />
+ <Route index element={<Navigate to="heartbeats" replace />} />
+ <Route path="heartbeats" element={<InstanceSettings />} />
+ <Route path="plugins" element={<PluginManager />} />
+ <Route path="plugins/:pluginId" element={<PluginSettings />} />
</Route>
<Route path="companies" element={<UnprefixedBoardRedirect />} />
<Route path="issues" element={<UnprefixedBoardRedirect />} />
diff --git a/ui/src/api/client.ts b/ui/src/api/client.ts
index b1b4f6488d..1071ba8f69 100644
--- a/ui/src/api/client.ts
+++ b/ui/src/api/client.ts
@@ -41,6 +41,8 @@ export const api = {
request<T>(path, { method: "POST", body: JSON.stringify(body) }),
postForm: <T>(path: string, body: FormData) =>
request<T>(path, { method: "POST", body }),
+ put: <T>(path: string, body: unknown) =>
+ request<T>(path, { method: "PUT", body: JSON.stringify(body) }),
patch: <T>(path: string, body: unknown) =>
request<T>(path, { method: "PATCH", body: JSON.stringify(body) }),
delete: <T>(path: string) => request<T>(path, { method: "DELETE" }),
diff --git a/ui/src/api/plugins.ts b/ui/src/api/plugins.ts
new file mode 100644
index 0000000000..f2b7d31bf6
--- /dev/null
+++ b/ui/src/api/plugins.ts
@@ -0,0 +1,469 @@
+/**
+ * @fileoverview Frontend API client for the Paperclip plugin system.
+ *
+ * All functions in `pluginsApi` map 1:1 to REST endpoints on
+ * `server/src/routes/plugins.ts`. Call sites should consume these functions
+ * through React Query hooks (`useQuery` / `useMutation`) and reference cache
+ * keys from `queryKeys.plugins.*`.
+ *
+ * @see ui/src/lib/queryKeys.ts for cache key definitions.
+ * @see server/src/routes/plugins.ts for endpoint implementation details.
+ */
+
+import type {
+ PluginLauncherDeclaration,
+ PluginLauncherRenderContextSnapshot,
+ PluginUiSlotDeclaration,
+ PluginRecord,
+ PluginConfig,
+ PluginStatus,
+ CompanyPluginAvailability,
+} from "@paperclipai/shared";
+import { api } from "./client";
+
+/**
+ * Normalized UI contribution record returned by `GET /api/plugins/ui-contributions`.
+ *
+ * Only populated for plugins in `ready` state that declare at least one UI slot
+ * or launcher. The `slots` array is sourced from `manifest.ui.slots`. The
+ * `launchers` array aggregates both legacy `manifest.launchers` and
+ * `manifest.ui.launchers`.
+ */
+export type PluginUiContribution = {
+ pluginId: string;
+ pluginKey: string;
+ displayName: string;
+ version: string;
+ updatedAt?: string;
+ /**
+ * Relative filename of the UI entry module within the plugin's UI directory.
+ * The host constructs the full import URL as
+ * `/_plugins/${pluginId}/ui/${uiEntryFile}`.
+ */
+ uiEntryFile: string;
+ slots: PluginUiSlotDeclaration[];
+ launchers: PluginLauncherDeclaration[];
+};
+
+/**
+ * Health check result returned by `GET /api/plugins/:pluginId/health`.
+ *
+ * The `healthy` flag summarises whether all checks passed. Individual check
+ * results are available in `checks` for detailed diagnostics display.
+ */
+export interface PluginHealthCheckResult {
+ pluginId: string;
+ /** The plugin's current lifecycle status at time of check. */
+ status: string;
+ /** True if all health checks passed. */
+ healthy: boolean;
+ /** Individual diagnostic check results. */
+ checks: Array<{
+ name: string;
+ passed: boolean;
+ /** Human-readable description of a failure, if any. */
+ message?: string;
+ }>;
+ /** The most recent error message if the plugin is in `error` state. */
+ lastError?: string;
+}
+
+/**
+ * Worker diagnostics returned as part of the dashboard response.
+ */
+export interface PluginWorkerDiagnostics {
+ status: string;
+ pid: number | null;
+ uptime: number | null;
+ consecutiveCrashes: number;
+ totalCrashes: number;
+ pendingRequests: number;
+ lastCrashAt: number | null;
+ nextRestartAt: number | null;
+}
+
+/**
+ * A recent job run entry returned in the dashboard response.
+ */
+export interface PluginDashboardJobRun {
+ id: string;
+ jobId: string;
+ jobKey?: string;
+ trigger: string;
+ status: string;
+ durationMs: number | null;
+ error: string | null;
+ startedAt: string | null;
+ finishedAt: string | null;
+ createdAt: string;
+}
+
+/**
+ * A recent webhook delivery entry returned in the dashboard response.
+ */
+export interface PluginDashboardWebhookDelivery {
+ id: string;
+ webhookKey: string;
+ status: string;
+ durationMs: number | null;
+ error: string | null;
+ startedAt: string | null;
+ finishedAt: string | null;
+ createdAt: string;
+}
+
+/**
+ * Aggregated health dashboard data returned by `GET /api/plugins/:pluginId/dashboard`.
+ *
+ * Contains worker diagnostics, recent job runs, recent webhook deliveries,
+ * and the current health check result — all in a single response.
+ */
+export interface PluginDashboardData {
+ pluginId: string;
+ /** Worker process diagnostics, or null if no worker is registered. */
+ worker: PluginWorkerDiagnostics | null;
+ /** Recent job execution history (newest first, max 10). */
+ recentJobRuns: PluginDashboardJobRun[];
+ /** Recent inbound webhook deliveries (newest first, max 10). */
+ recentWebhookDeliveries: PluginDashboardWebhookDelivery[];
+ /** Current health check results. */
+ health: PluginHealthCheckResult;
+ /** ISO 8601 timestamp when the dashboard data was generated. */
+ checkedAt: string;
+}
+
+export interface AvailablePluginExample {
+ packageName: string;
+ pluginKey: string;
+ displayName: string;
+ description: string;
+ localPath: string;
+ tag: "example";
+}
+
+/**
+ * Plugin management API client.
+ *
+ * All methods are thin wrappers around the `api` base client. They return
+ * promises that resolve to typed JSON responses or throw on HTTP errors.
+ *
+ * @example
+ * ```tsx
+ * // In a component:
+ * const { data: plugins } = useQuery({
+ * queryKey: queryKeys.plugins.all,
+ * queryFn: () => pluginsApi.list(),
+ * });
+ * ```
+ */
+export const pluginsApi = {
+ /**
+ * List all installed plugins, optionally filtered by lifecycle status.
+ *
+ * @param status - Optional filter; must be a valid `PluginStatus` value.
+ * Invalid values are rejected by the server with HTTP 400.
+ */
+ list: (status?: PluginStatus) =>
+ api.get<PluginRecord[]>(`/plugins${status ? `?status=${status}` : ""}`),
+
+ /**
+ * List bundled example plugins available from the current repo checkout.
+ */
+ listExamples: () =>
+ api.get<AvailablePluginExample[]>("/plugins/examples"),
+
+ /**
+ * Fetch a single plugin record by its UUID or plugin key.
+ *
+ * @param pluginId - The plugin's UUID (from `PluginRecord.id`) or plugin key.
+ */
+ get: (pluginId: string) =>
+ api.get<PluginRecord>(`/plugins/${pluginId}`),
+
+ /**
+ * Install a plugin from npm or a local path.
+ *
+ * On success, the plugin is registered in the database and transitioned to
+ * `ready` state. The response is the newly created `PluginRecord`.
+ *
+ * @param params.packageName - npm package name (e.g. `@paperclip/plugin-linear`)
+ * or a filesystem path when `isLocalPath` is `true`.
+ * @param params.version - Target npm version tag/range (optional; defaults to latest).
+ * @param params.isLocalPath - Set to `true` when `packageName` is a local path.
+ */
+ install: (params: { packageName: string; version?: string; isLocalPath?: boolean }) =>
+ api.post<PluginRecord>("/plugins/install", params),
+
+ /**
+ * Uninstall a plugin.
+ *
+ * @param pluginId - UUID of the plugin to remove.
+ * @param purge - If `true`, permanently delete all plugin data (hard delete).
+ * Otherwise the plugin is soft-deleted with a 30-day data retention window.
+ */
+ uninstall: (pluginId: string, purge?: boolean) =>
+ api.delete<{ ok: boolean }>(`/plugins/${pluginId}${purge ? "?purge=true" : ""}`),
+
+ /**
+ * Transition a plugin from `error` state back to `ready`.
+ * No-ops if the plugin is already enabled.
+ *
+ * @param pluginId - UUID of the plugin to enable.
+ */
+ enable: (pluginId: string) =>
+ api.post<{ ok: boolean }>(`/plugins/${pluginId}/enable`, {}),
+
+ /**
+ * Disable a plugin (transition to `error` state with an operator sentinel).
+ * The plugin's worker is stopped; it will not process events until re-enabled.
+ *
+ * @param pluginId - UUID of the plugin to disable.
+ * @param reason - Optional human-readable reason stored in `lastError`.
+ */
+ disable: (pluginId: string, reason?: string) =>
+ api.post<{ ok: boolean }>(`/plugins/${pluginId}/disable`, reason ? { reason } : {}),
+
+ /**
+ * Run health diagnostics for a plugin.
+ *
+ * Only meaningful for plugins in `ready` state. Returns the result of all
+ * registered health checks. Called on a 30-second polling interval by
+ * {@link PluginSettings}.
+ *
+ * @param pluginId - UUID of the plugin to health-check.
+ */
+ health: (pluginId: string) =>
+ api.get<PluginHealthCheckResult>(`/plugins/${pluginId}/health`),
+
+ /**
+ * Fetch aggregated health dashboard data for a plugin.
+ *
+ * Returns worker diagnostics, recent job runs, recent webhook deliveries,
+ * and the current health check result in a single request. Used by the
+ * {@link PluginSettings} page to render the runtime dashboard section.
+ *
+ * @param pluginId - UUID of the plugin.
+ */
+ dashboard: (pluginId: string) =>
+ api.get<PluginDashboardData>(`/plugins/${pluginId}/dashboard`),
+
+ /**
+ * Fetch recent log entries for a plugin.
+ *
+ * @param pluginId - UUID of the plugin.
+ * @param options - Optional filters: limit, level, since.
+ */
+ logs: (pluginId: string, options?: { limit?: number; level?: string; since?: string }) => {
+ const params = new URLSearchParams();
+ if (options?.limit) params.set("limit", String(options.limit));
+ if (options?.level) params.set("level", options.level);
+ if (options?.since) params.set("since", options.since);
+ const qs = params.toString();
+ return api.get<Array<{ id: string; pluginId: string; level: string; message: string; meta: Record<string, unknown> | null; createdAt: string }>>(
+ `/plugins/${pluginId}/logs${qs ? `?${qs}` : ""}`,
+ );
+ },
+
+ /**
+ * Upgrade a plugin to a newer version.
+ *
+ * If the new version declares additional capabilities, the plugin is
+ * transitioned to `upgrade_pending` state awaiting operator approval.
+ *
+ * @param pluginId - UUID of the plugin to upgrade.
+ * @param version - Target version (optional; defaults to latest published).
+ */
+ upgrade: (pluginId: string, version?: string) =>
+ api.post<{ ok: boolean }>(`/plugins/${pluginId}/upgrade`, version ? { version } : {}),
+
+ /**
+ * Returns normalized UI contribution declarations for ready plugins.
+ * Used by the slot host runtime and launcher discovery surfaces.
+ *
+ * When `companyId` is provided, the server filters out plugins that are
+ * disabled for that company before returning contributions.
+ *
+ * Response shape:
+ * - `slots`: concrete React mount declarations from `manifest.ui.slots`
+ * - `launchers`: host-owned entry points from `manifest.ui.launchers` plus
+ * the legacy top-level `manifest.launchers`
+ *
+ * @example
+ * ```ts
+ * const rows = await pluginsApi.listUiContributions(companyId);
+ * const toolbarLaunchers = rows.flatMap((row) =>
+ * row.launchers.filter((launcher) => launcher.placementZone === "toolbarButton"),
+ * );
+ * ```
+ */
+ listUiContributions: (companyId?: string) =>
+ api.get<PluginUiContribution[]>(
+ `/plugins/ui-contributions${companyId ? `?companyId=${encodeURIComponent(companyId)}` : ""}`,
+ ),
+
+ /**
+ * List plugin availability/settings for a specific company.
+ *
+ * @param companyId - UUID of the company.
+ * @param available - Optional availability filter.
+ */
+ listForCompany: (companyId: string, available?: boolean) =>
+ api.get<CompanyPluginAvailability[]>(
+ `/companies/${companyId}/plugins${available === undefined ? "" : `?available=${available}`}`,
+ ),
+
+ /**
+ * Fetch a single company-scoped plugin availability/settings record.
+ *
+ * @param companyId - UUID of the company.
+ * @param pluginId - Plugin UUID or plugin key.
+ */
+ getForCompany: (companyId: string, pluginId: string) =>
+ api.get<CompanyPluginAvailability>(`/companies/${companyId}/plugins/${pluginId}`),
+
+ /**
+ * Create, update, or clear company-scoped plugin settings.
+ *
+ * Company availability is enabled by default. This endpoint stores explicit
+ * overrides in `plugin_company_settings` so the selected company can be
+ * disabled without affecting the global plugin installation.
+ */
+ saveForCompany: (
+ companyId: string,
+ pluginId: string,
+ params: {
+ available: boolean;
+ settingsJson?: Record<string, unknown>;
+ lastError?: string | null;
+ },
+ ) =>
+ api.put<CompanyPluginAvailability>(`/companies/${companyId}/plugins/${pluginId}`, params),
+
+ // ===========================================================================
+ // Plugin configuration endpoints
+ // ===========================================================================
+
+ /**
+ * Fetch the current configuration for a plugin.
+ *
+ * Returns the `PluginConfig` record if one exists, or `null` if the plugin
+ * has not yet been configured.
+ *
+ * @param pluginId - UUID of the plugin.
+ */
+ getConfig: (pluginId: string) =>
+ api.get<PluginConfig | null>(`/plugins/${pluginId}/config`),
+
+ /**
+ * Save (create or update) the configuration for a plugin.
+ *
+ * The server validates `configJson` against the plugin's `instanceConfigSchema`
+ * and returns the persisted `PluginConfig` record on success.
+ *
+ * @param pluginId - UUID of the plugin.
+ * @param configJson - Configuration values matching the plugin's `instanceConfigSchema`.
+ */
+ saveConfig: (pluginId: string, configJson: Record<string, unknown>) =>
+ api.post<PluginConfig>(`/plugins/${pluginId}/config`, { configJson }),
+
+ /**
+ * Call the plugin's `validateConfig` RPC method to test the configuration
+ * without persisting it.
+ *
+ * Returns `{ valid: true }` on success, or `{ valid: false, message: string }`
+ * when the plugin reports a validation failure.
+ *
+ * Only available when the plugin declares a `validateConfig` RPC handler.
+ *
+ * @param pluginId - UUID of the plugin.
+ * @param configJson - Configuration values to validate.
+ */
+ testConfig: (pluginId: string, configJson: Record<string, unknown>) =>
+ api.post<{ valid: boolean; message?: string }>(`/plugins/${pluginId}/config/test`, { configJson }),
+
+ // ===========================================================================
+ // Bridge proxy endpoints — used by the plugin UI bridge runtime
+ // ===========================================================================
+
+ /**
+ * Proxy a `getData` call from a plugin UI component to its worker backend.
+ *
+ * This is the HTTP transport for `usePluginData(key, params)`. The bridge
+ * runtime calls this method and maps the response into `PluginDataResult<T>`.
+ *
+ * On success, the response is `{ data: T }`.
+ * On failure, the response body is a `PluginBridgeError`-shaped object
+ * with `code`, `message`, and optional `details`.
+ *
+ * @param pluginId - UUID of the plugin whose worker should handle the request
+ * @param key - Plugin-defined data key (e.g. `"sync-health"`)
+ * @param params - Optional query parameters forwarded to the worker handler
+ * @param companyId - Optional company scope. When present, the server rejects
+ * the call with HTTP 403 if the plugin is disabled for that company.
+ * @param renderEnvironment - Optional launcher/page snapshot forwarded for
+ * launcher-backed UI so workers can distinguish modal, drawer, popover, and
+ * page execution.
+ *
+ * Error responses:
+ * - `401`/`403` when auth or company access checks fail
+ * - `404` when the plugin or handler key does not exist
+ * - `409` when the plugin is not in a callable runtime state
+ * - `5xx` with a `PluginBridgeError`-shaped body when the worker throws
+ *
+ * @see PLUGIN_SPEC.md §13.8 — `getData`
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+ bridgeGetData: (
+ pluginId: string,
+ key: string,
+ params?: Record<string, unknown>,
+ companyId?: string | null,
+ renderEnvironment?: PluginLauncherRenderContextSnapshot | null,
+ ) =>
+ api.post<{ data: unknown }>(`/plugins/${pluginId}/data/${encodeURIComponent(key)}`, {
+ companyId: companyId ?? undefined,
+ params,
+ renderEnvironment: renderEnvironment ?? undefined,
+ }),
+
+ /**
+ * Proxy a `performAction` call from a plugin UI component to its worker backend.
+ *
+ * This is the HTTP transport for `usePluginAction(key)`. The bridge runtime
+ * calls this method when the action function is invoked.
+ *
+ * On success, the response is `{ data: T }`.
+ * On failure, the response body is a `PluginBridgeError`-shaped object
+ * with `code`, `message`, and optional `details`.
+ *
+ * @param pluginId - UUID of the plugin whose worker should handle the request
+ * @param key - Plugin-defined action key (e.g. `"resync"`)
+ * @param params - Optional parameters forwarded to the worker handler
+ * @param companyId - Optional company scope. When present, the server rejects
+ * the call with HTTP 403 if the plugin is disabled for that company.
+ * @param renderEnvironment - Optional launcher/page snapshot forwarded for
+ * launcher-backed UI so workers can distinguish modal, drawer, popover, and
+ * page execution.
+ *
+ * Error responses:
+ * - `401`/`403` when auth or company access checks fail
+ * - `404` when the plugin or handler key does not exist
+ * - `409` when the plugin is not in a callable runtime state
+ * - `5xx` with a `PluginBridgeError`-shaped body when the worker throws
+ *
+ * @see PLUGIN_SPEC.md §13.9 — `performAction`
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+ bridgePerformAction: (
+ pluginId: string,
+ key: string,
+ params?: Record<string, unknown>,
+ companyId?: string | null,
+ renderEnvironment?: PluginLauncherRenderContextSnapshot | null,
+ ) =>
+ api.post<{ data: unknown }>(`/plugins/${pluginId}/actions/${encodeURIComponent(key)}`, {
+ companyId: companyId ?? undefined,
+ params,
+ renderEnvironment: renderEnvironment ?? undefined,
+ }),
+};
diff --git a/ui/src/components/InstanceSidebar.tsx b/ui/src/components/InstanceSidebar.tsx
index ac933aa1d0..0b396ef9c4 100644
--- a/ui/src/components/InstanceSidebar.tsx
+++ b/ui/src/components/InstanceSidebar.tsx
@@ -1,4 +1,4 @@
-import { Clock3, Settings } from "lucide-react";
+import { Clock3, Puzzle, Settings } from "lucide-react";
import { SidebarNavItem } from "./SidebarNavItem";
export function InstanceSidebar() {
@@ -13,7 +13,8 @@ export function InstanceSidebar() {
<nav className="flex-1 min-h-0 overflow-y-auto scrollbar-auto-hide flex flex-col gap-4 px-3 py-2">
<div className="flex flex-col gap-0.5">
- <SidebarNavItem to="/instance/settings" label="Heartbeats" icon={Clock3} />
+ <SidebarNavItem to="/instance/settings/heartbeats" label="Heartbeats" icon={Clock3} end />
+ <SidebarNavItem to="/instance/settings/plugins" label="Plugins" icon={Puzzle} />
</div>
</nav>
</aside>
diff --git a/ui/src/components/JsonSchemaForm.tsx b/ui/src/components/JsonSchemaForm.tsx
new file mode 100644
index 0000000000..e185bf4b3e
--- /dev/null
+++ b/ui/src/components/JsonSchemaForm.tsx
@@ -0,0 +1,1048 @@
+import React, { useCallback, useMemo, useState } from "react";
+import {
+ ChevronDown,
+ ChevronRight,
+ Eye,
+ EyeOff,
+ Plus,
+ Trash2,
+} from "lucide-react";
+import { cn } from "@/lib/utils";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import { Label } from "@/components/ui/label";
+import { Checkbox } from "@/components/ui/checkbox";
+import { Button } from "@/components/ui/button";
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from "@/components/ui/select";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Threshold for string length above which a Textarea is used instead of a standard Input.
+ */
+const TEXTAREA_THRESHOLD = 200;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Subset of JSON Schema properties we understand for form rendering.
+ * We intentionally keep this loose (`Record<string, unknown>`) at the top
+ * level to match the `JsonSchema` type in shared, but narrow internally.
+ */
+export interface JsonSchemaNode {
+ type?: string | string[];
+ title?: string;
+ description?: string;
+ default?: unknown;
+ enum?: unknown[];
+ const?: unknown;
+ format?: string;
+
+ // String constraints
+ minLength?: number;
+ maxLength?: number;
+ pattern?: string;
+
+ // Number constraints
+ minimum?: number;
+ maximum?: number;
+ exclusiveMinimum?: number;
+ exclusiveMaximum?: number;
+ multipleOf?: number;
+
+ // Object
+ properties?: Record<string, JsonSchemaNode>;
+ required?: string[];
+ additionalProperties?: boolean | JsonSchemaNode;
+
+ // Array
+ items?: JsonSchemaNode;
+ minItems?: number;
+ maxItems?: number;
+
+ // Metadata
+ readOnly?: boolean;
+ writeOnly?: boolean;
+
+ // Allow extra keys
+ [key: string]: unknown;
+}
+
+export interface JsonSchemaFormProps {
+ /** The JSON Schema to render. */
+ schema: JsonSchemaNode;
+ /** Current form values. */
+ values: Record<string, unknown>;
+ /** Called whenever any field value changes. */
+ onChange: (values: Record<string, unknown>) => void;
+ /** Validation errors keyed by JSON pointer path (e.g. "/apiKey"). */
+ errors?: Record<string, string>;
+ /** If true, all fields are disabled. */
+ disabled?: boolean;
+ /** Additional CSS class for the root container. */
+ className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Resolve the primary type string from a schema node. */
+export function resolveType(schema: JsonSchemaNode): string {
+ if (schema.enum) return "enum";
+ if (schema.const !== undefined) return "const";
+ if (schema.format === "secret-ref") return "secret-ref";
+ if (Array.isArray(schema.type)) {
+ // Use the first non-null type
+ return schema.type.find((t) => t !== "null") ?? "string";
+ }
+ return schema.type ?? "string";
+}
+
+/** Human-readable label from schema title or property key. */
+export function labelFromKey(key: string, schema: JsonSchemaNode): string {
+ if (schema.title) return schema.title;
+ // Convert camelCase / snake_case to Title Case
+ return key
+ .replace(/([a-z])([A-Z])/g, "$1 $2")
+ .replace(/[_-]+/g, " ")
+ .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/** Produce a sensible default value for a schema node. */
+export function getDefaultForSchema(schema: JsonSchemaNode): unknown {
+ if (schema.default !== undefined) return schema.default;
+
+ const type = resolveType(schema);
+ switch (type) {
+ case "string":
+ case "secret-ref":
+ return "";
+ case "number":
+ case "integer":
+ return schema.minimum ?? 0;
+ case "boolean":
+ return false;
+ case "enum":
+ return schema.enum?.[0] ?? "";
+ case "array":
+ return [];
+ case "object": {
+ if (!schema.properties) return {};
+ const obj: Record<string, unknown> = {};
+ for (const [key, propSchema] of Object.entries(schema.properties)) {
+ obj[key] = getDefaultForSchema(propSchema);
+ }
+ return obj;
+ }
+ default:
+ return "";
+ }
+}
+
+/** Validate a single field value against schema constraints. Returns error string or null. */
+export function validateField(
+ value: unknown,
+ schema: JsonSchemaNode,
+ isRequired: boolean,
+): string | null {
+ const type = resolveType(schema);
+
+ // Required check
+ if (isRequired && (value === undefined || value === null || value === "")) {
+ return "This field is required";
+ }
+
+ // Skip further validation if empty and not required
+ if (value === undefined || value === null || value === "") return null;
+
+ if (type === "string" || type === "secret-ref") {
+ const str = String(value);
+ if (schema.minLength != null && str.length < schema.minLength) {
+ return `Must be at least ${schema.minLength} characters`;
+ }
+ if (schema.maxLength != null && str.length > schema.maxLength) {
+ return `Must be at most ${schema.maxLength} characters`;
+ }
+ if (schema.pattern) {
+ // Guard against ReDoS: reject overly complex patterns from plugin JSON Schemas.
+ // Limit pattern length and run the regex with a defensive try/catch.
+ const MAX_PATTERN_LENGTH = 512;
+ if (schema.pattern.length <= MAX_PATTERN_LENGTH) {
+ try {
+ const re = new RegExp(schema.pattern);
+ if (!re.test(str)) {
+ return `Must match pattern: ${schema.pattern}`;
+ }
+ } catch {
+ // Invalid regex in schema — skip
+ }
+ }
+ }
+ }
+
+ if (type === "number" || type === "integer") {
+ const num = Number(value);
+ if (isNaN(num)) return "Must be a valid number";
+ if (schema.minimum != null && num < schema.minimum) {
+ return `Must be at least ${schema.minimum}`;
+ }
+ if (schema.maximum != null && num > schema.maximum) {
+ return `Must be at most ${schema.maximum}`;
+ }
+ if (schema.exclusiveMinimum != null && num <= schema.exclusiveMinimum) {
+ return `Must be greater than ${schema.exclusiveMinimum}`;
+ }
+ if (schema.exclusiveMaximum != null && num >= schema.exclusiveMaximum) {
+ return `Must be less than ${schema.exclusiveMaximum}`;
+ }
+ if (type === "integer" && !Number.isInteger(num)) {
+ return "Must be a whole number";
+ }
+ if (schema.multipleOf != null && num % schema.multipleOf !== 0) {
+ return `Must be a multiple of ${schema.multipleOf}`;
+ }
+ }
+
+ if (type === "array") {
+ const arr = value as unknown[];
+ if (schema.minItems != null && arr.length < schema.minItems) {
+ return `Must have at least ${schema.minItems} items`;
+ }
+ if (schema.maxItems != null && arr.length > schema.maxItems) {
+ return `Must have at most ${schema.maxItems} items`;
+ }
+ }
+
+ return null;
+}
+
+/** Public API for validation */
+export function validateJsonSchemaForm(
+ schema: JsonSchemaNode,
+ values: Record<string, unknown>,
+ path: string[] = [],
+): Record<string, string> {
+ const errors: Record<string, string> = {};
+ const properties = schema.properties ?? {};
+ const requiredFields = new Set(schema.required ?? []);
+
+ for (const [key, propSchema] of Object.entries(properties)) {
+ const fieldPath = [...path, key];
+ const errorKey = `/${fieldPath.join("/")}`;
+ const value = values[key];
+ const isRequired = requiredFields.has(key);
+ const type = resolveType(propSchema);
+
+ // Per-field validation
+ const fieldErr = validateField(value, propSchema, isRequired);
+ if (fieldErr) {
+ errors[errorKey] = fieldErr;
+ }
+
+ // Recurse into objects
+ if (type === "object" && propSchema.properties && typeof value === "object" && value !== null) {
+ Object.assign(
+ errors,
+ validateJsonSchemaForm(propSchema, value as Record<string, unknown>, fieldPath),
+ );
+ }
+
+ // Recurse into arrays
+ if (type === "array" && propSchema.items && Array.isArray(value)) {
+ const itemSchema = propSchema.items as JsonSchemaNode;
+ const isObjectItem = resolveType(itemSchema) === "object";
+
+ value.forEach((item, index) => {
+ const itemPath = [...fieldPath, String(index)];
+ const itemErrorKey = `/${itemPath.join("/")}`;
+
+ if (isObjectItem) {
+ Object.assign(
+ errors,
+ validateJsonSchemaForm(
+ itemSchema,
+ item as Record<string, unknown>,
+ itemPath,
+ ),
+ );
+ } else {
+ const itemErr = validateField(item, itemSchema, false);
+ if (itemErr) {
+ errors[itemErrorKey] = itemErr;
+ }
+ }
+ });
+ }
+ }
+
+ return errors;
+}
+
+/** Public API for default values */
+export function getDefaultValues(schema: JsonSchemaNode): Record<string, unknown> {
+ const result: Record<string, unknown> = {};
+ const properties = schema.properties ?? {};
+
+ for (const [key, propSchema] of Object.entries(properties)) {
+ const def = getDefaultForSchema(propSchema);
+ if (def !== undefined) {
+ result[key] = def;
+ }
+ }
+
+ return result;
+}
+
+// ---------------------------------------------------------------------------
+// Internal Components
+// ---------------------------------------------------------------------------
+
+interface FieldWrapperProps {
+ label: string;
+ description?: string;
+ required?: boolean;
+ error?: string;
+ disabled?: boolean;
+ children: React.ReactNode;
+}
+
+/**
+ * Common wrapper for form fields that handles labels, descriptions, and error messages.
+ */
+const FieldWrapper = React.memo(({
+ label,
+ description,
+ required,
+ error,
+ disabled,
+ children,
+}: FieldWrapperProps) => {
+ return (
+ <div className={cn("space-y-2", disabled && "opacity-60")}>
+ <div className="flex items-center justify-between">
+ {label && (
+ <Label className="text-sm font-medium">
+ {label}
+ {required && <span className="ml-1 text-destructive">*</span>}
+ </Label>
+ )}
+ </div>
+ {children}
+ {description && (
+ <p className="text-[12px] text-muted-foreground leading-relaxed">
+ {description}
+ </p>
+ )}
+ {error && (
+ <p className="text-[12px] font-medium text-destructive">{error}</p>
+ )}
+ </div>
+ );
+});
+
+FieldWrapper.displayName = "FieldWrapper";
+
+interface FormFieldProps {
+ propSchema: JsonSchemaNode;
+ value: unknown;
+ onChange: (val: unknown) => void;
+ error?: string;
+ disabled?: boolean;
+ label: string;
+ isRequired?: boolean;
+ errors: Record<string, string>; // needed for recursion
+ path: string; // needed for recursion error filtering
+}
+
+/**
+ * Specialized field for boolean (checkbox) values.
+ */
+const BooleanField = React.memo(({
+ id,
+ value,
+ onChange,
+ disabled,
+ label,
+ isRequired,
+ description,
+ error,
+}: {
+ id: string;
+ value: unknown;
+ onChange: (val: unknown) => void;
+ disabled: boolean;
+ label: string;
+ isRequired?: boolean;
+ description?: string;
+ error?: string;
+}) => (
+ <div className="flex items-start space-x-3 space-y-0">
+ <Checkbox
+ id={id}
+ checked={!!value}
+ onCheckedChange={onChange}
+ disabled={disabled}
+ />
+ <div className="grid gap-1.5 leading-none">
+ {label && (
+ <Label
+ htmlFor={id}
+ className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
+ >
+ {label}
+ {isRequired && <span className="ml-1 text-destructive">*</span>}
+ </Label>
+ )}
+ {description && (
+ <p className="text-xs text-muted-foreground">{description}</p>
+ )}
+ {error && (
+ <p className="text-xs font-medium text-destructive">{error}</p>
+ )}
+ </div>
+ </div>
+));
+
+BooleanField.displayName = "BooleanField";
+
+/**
+ * Specialized field for enum (select) values.
+ */
+const EnumField = React.memo(({
+ value,
+ onChange,
+ disabled,
+ label,
+ isRequired,
+ description,
+ error,
+ options,
+}: {
+ value: unknown;
+ onChange: (val: unknown) => void;
+ disabled: boolean;
+ label: string;
+ isRequired?: boolean;
+ description?: string;
+ error?: string;
+ options: unknown[];
+}) => (
+ <FieldWrapper
+ label={label}
+ description={description}
+ required={isRequired}
+ error={error}
+ disabled={disabled}
+ >
+ <Select
+ value={String(value ?? "")}
+ onValueChange={onChange}
+ disabled={disabled}
+ >
+ <SelectTrigger className="w-full">
+ <SelectValue placeholder="Select an option" />
+ </SelectTrigger>
+ <SelectContent>
+ {options.map((option) => (
+ <SelectItem key={String(option)} value={String(option)}>
+ {String(option)}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </FieldWrapper>
+));
+
+EnumField.displayName = "EnumField";
+
+/**
+ * Specialized field for secret-ref values, providing a toggleable password input.
+ */
+const SecretField = React.memo(({
+ value,
+ onChange,
+ disabled,
+ label,
+ isRequired,
+ description,
+ error,
+ defaultValue,
+}: {
+ value: unknown;
+ onChange: (val: unknown) => void;
+ disabled: boolean;
+ label: string;
+ isRequired?: boolean;
+ description?: string;
+ error?: string;
+ defaultValue?: unknown;
+}) => {
+ const [isVisible, setIsVisible] = useState(false);
+ return (
+ <FieldWrapper
+ label={label}
+ description={
+ description ||
+ "This secret is stored securely via the Paperclip secret provider."
+ }
+ required={isRequired}
+ error={error}
+ disabled={disabled}
+ >
+ <div className="relative">
+ <Input
+ type={isVisible ? "text" : "password"}
+ value={String(value ?? "")}
+ onChange={(e) => onChange(e.target.value)}
+ placeholder={String(defaultValue ?? "")}
+ disabled={disabled}
+ className="pr-10"
+ aria-invalid={!!error}
+ />
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ className="absolute right-0 top-0 h-full px-3 py-2 hover:bg-transparent"
+ onClick={() => setIsVisible(!isVisible)}
+ disabled={disabled}
+ >
+ {isVisible ? (
+ <EyeOff className="h-4 w-4 text-muted-foreground" />
+ ) : (
+ <Eye className="h-4 w-4 text-muted-foreground" />
+ )}
+ <span className="sr-only">
+ {isVisible ? "Hide secret" : "Show secret"}
+ </span>
+ </Button>
+ </div>
+ </FieldWrapper>
+ );
+});
+
+SecretField.displayName = "SecretField";
+
+/**
+ * Specialized field for numeric (number/integer) values.
+ */
+const NumberField = React.memo(({
+ value,
+ onChange,
+ disabled,
+ label,
+ isRequired,
+ description,
+ error,
+ defaultValue,
+ type,
+}: {
+ value: unknown;
+ onChange: (val: unknown) => void;
+ disabled: boolean;
+ label: string;
+ isRequired?: boolean;
+ description?: string;
+ error?: string;
+ defaultValue?: unknown;
+ type: "number" | "integer";
+}) => (
+ <FieldWrapper
+ label={label}
+ description={description}
+ required={isRequired}
+ error={error}
+ disabled={disabled}
+ >
+ <Input
+ type="number"
+ step={type === "integer" ? "1" : "any"}
+ value={value !== undefined ? String(value) : ""}
+ onChange={(e) => {
+ const val = e.target.value;
+ onChange(val === "" ? undefined : Number(val));
+ }}
+ placeholder={String(defaultValue ?? "")}
+ disabled={disabled}
+ aria-invalid={!!error}
+ />
+ </FieldWrapper>
+));
+
+NumberField.displayName = "NumberField";
+
+/**
+ * Specialized field for string values, rendering either an Input or Textarea based on length or format.
+ */
+const StringField = React.memo(({
+ value,
+ onChange,
+ disabled,
+ label,
+ isRequired,
+ description,
+ error,
+ defaultValue,
+ format,
+ maxLength,
+}: {
+ value: unknown;
+ onChange: (val: unknown) => void;
+ disabled: boolean;
+ label: string;
+ isRequired?: boolean;
+ description?: string;
+ error?: string;
+ defaultValue?: unknown;
+ format?: string;
+ maxLength?: number;
+}) => {
+ const isTextArea = format === "textarea" || (maxLength && maxLength > TEXTAREA_THRESHOLD);
+ return (
+ <FieldWrapper
+ label={label}
+ description={description}
+ required={isRequired}
+ error={error}
+ disabled={disabled}
+ >
+ {isTextArea ? (
+ <Textarea
+ value={String(value ?? "")}
+ onChange={(e) => onChange(e.target.value)}
+ placeholder={String(defaultValue ?? "")}
+ disabled={disabled}
+ className="min-h-[100px]"
+ aria-invalid={!!error}
+ />
+ ) : (
+ <Input
+ type="text"
+ value={String(value ?? "")}
+ onChange={(e) => onChange(e.target.value)}
+ placeholder={String(defaultValue ?? "")}
+ disabled={disabled}
+ aria-invalid={!!error}
+ />
+ )}
+ </FieldWrapper>
+ );
+});
+
+StringField.displayName = "StringField";
+
+/**
+ * Specialized field for array values, handling dynamic addition and removal of items.
+ */
+const ArrayField = React.memo(({
+ propSchema,
+ value,
+ onChange,
+ error,
+ disabled,
+ label,
+ errors,
+ path,
+}: {
+ propSchema: JsonSchemaNode;
+ value: unknown;
+ onChange: (val: unknown) => void;
+ error?: string;
+ disabled: boolean;
+ label: string;
+ errors: Record<string, string>;
+ path: string;
+}) => {
+ const items = Array.isArray(value) ? value : [];
+ const itemSchema = propSchema.items as JsonSchemaNode;
+ const isComplex = resolveType(itemSchema) === "object";
+
+ return (
+ <div className="space-y-4">
+ <div className="flex items-center justify-between">
+ <div>
+ <Label className="text-sm font-medium">{label}</Label>
+ {propSchema.description && (
+ <p className="text-xs text-muted-foreground">
+ {propSchema.description}
+ </p>
+ )}
+ </div>
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ disabled={
+ disabled ||
+ (propSchema.maxItems !== undefined &&
+ items.length >= (propSchema.maxItems as number))
+ }
+ onClick={() => {
+ const newItem = getDefaultForSchema(itemSchema);
+ onChange([...items, newItem]);
+ }}
+ >
+ <Plus className="mr-2 h-4 w-4" />
+ {isComplex ? "Add item" : "Add"}
+ </Button>
+ </div>
+
+ <div className="space-y-3">
+ {items.map((item, index) => (
+ <div
+ key={index}
+ className="group relative flex items-start space-x-2 rounded-lg border p-3"
+ >
+ <div className="flex-1">
+ <div className="mb-2 text-xs font-medium text-muted-foreground">
+ Item {index + 1}
+ </div>
+ <FormField
+ propSchema={itemSchema}
+ value={item}
+ label=""
+ path={`${path}/${index}`}
+ onChange={(newVal) => {
+ const newItems = [...items];
+ newItems[index] = newVal;
+ onChange(newItems);
+ }}
+ disabled={disabled}
+ errors={errors}
+ />
+ </div>
+ <Button
+ type="button"
+ variant="ghost"
+ size="icon"
+ className="h-8 w-8 text-muted-foreground hover:text-destructive"
+ disabled={
+ disabled ||
+ (propSchema.minItems !== undefined &&
+ items.length <= (propSchema.minItems as number))
+ }
+ onClick={() => {
+ const newItems = [...items];
+ newItems.splice(index, 1);
+ onChange(newItems);
+ }}
+ >
+ <Trash2 className="h-4 w-4" />
+ <span className="sr-only">Remove item</span>
+ </Button>
+ </div>
+ ))}
+ {items.length === 0 && (
+ <div className="rounded-lg border border-dashed p-4 text-center text-xs text-muted-foreground">
+ No items added yet.
+ </div>
+ )}
+ </div>
+ {error && (
+ <p className="text-xs font-medium text-destructive">{error}</p>
+ )}
+ </div>
+ );
+});
+
+ArrayField.displayName = "ArrayField";
+
+/**
+ * Specialized field for object values, handling recursive rendering of nested properties.
+ */
+const ObjectField = React.memo(({
+ propSchema,
+ value,
+ onChange,
+ disabled,
+ label,
+ errors,
+ path,
+}: {
+ propSchema: JsonSchemaNode;
+ value: unknown;
+ onChange: (val: unknown) => void;
+ disabled: boolean;
+ label: string;
+ errors: Record<string, string>;
+ path: string;
+}) => {
+ const [isCollapsed, setIsCollapsed] = useState(false);
+ const handleObjectChange = (newVal: Record<string, unknown>) => {
+ onChange(newVal);
+ };
+
+ return (
+ <div className="space-y-3 rounded-lg border p-4">
+ <button
+ type="button"
+ className="flex w-full items-center justify-between"
+ onClick={() => setIsCollapsed(!isCollapsed)}
+ >
+ <div className="text-left">
+ <Label className="cursor-pointer text-sm font-semibold">
+ {label}
+ </Label>
+ {propSchema.description && (
+ <p className="text-xs text-muted-foreground">
+ {propSchema.description}
+ </p>
+ )}
+ </div>
+ {isCollapsed ? (
+ <ChevronRight className="h-4 w-4 text-muted-foreground" />
+ ) : (
+ <ChevronDown className="h-4 w-4 text-muted-foreground" />
+ )}
+ </button>
+
+ {!isCollapsed && (
+ <div className="pt-2">
+ <JsonSchemaForm
+ schema={propSchema}
+ values={(value as Record<string, unknown>) ?? {}}
+ onChange={handleObjectChange}
+ disabled={disabled}
+ errors={Object.fromEntries(
+ Object.entries(errors)
+ .filter(([errPath]) => errPath.startsWith(`${path}/`))
+ .map(([errPath, err]) => [errPath.replace(path, ""), err]),
+ )}
+ />
+ </div>
+ )}
+ </div>
+ );
+});
+
+ObjectField.displayName = "ObjectField";
+
+/**
+ * Orchestrator component that selects and renders the appropriate field type based on the schema node.
+ */
+const FormField = React.memo(({
+ propSchema,
+ value,
+ onChange,
+ error,
+ disabled,
+ label,
+ isRequired,
+ errors,
+ path,
+}: FormFieldProps) => {
+ const type = resolveType(propSchema);
+ const isReadOnly = disabled || propSchema.readOnly === true;
+
+ switch (type) {
+ case "boolean":
+ return (
+ <BooleanField
+ id={path}
+ value={value}
+ onChange={onChange}
+ disabled={isReadOnly}
+ label={label}
+ isRequired={isRequired}
+ description={propSchema.description}
+ error={error}
+ />
+ );
+
+ case "enum":
+ return (
+ <EnumField
+ value={value}
+ onChange={onChange}
+ disabled={isReadOnly}
+ label={label}
+ isRequired={isRequired}
+ description={propSchema.description}
+ error={error}
+ options={propSchema.enum ?? []}
+ />
+ );
+
+ case "secret-ref":
+ return (
+ <SecretField
+ value={value}
+ onChange={onChange}
+ disabled={isReadOnly}
+ label={label}
+ isRequired={isRequired}
+ description={propSchema.description}
+ error={error}
+ defaultValue={propSchema.default}
+ />
+ );
+
+ case "number":
+ case "integer":
+ return (
+ <NumberField
+ value={value}
+ onChange={onChange}
+ disabled={isReadOnly}
+ label={label}
+ isRequired={isRequired}
+ description={propSchema.description}
+ error={error}
+ defaultValue={propSchema.default}
+ type={type as "number" | "integer"}
+ />
+ );
+
+ case "array":
+ return (
+ <ArrayField
+ propSchema={propSchema}
+ value={value}
+ onChange={onChange}
+ error={error}
+ disabled={isReadOnly}
+ label={label}
+ errors={errors}
+ path={path}
+ />
+ );
+
+ case "object":
+ return (
+ <ObjectField
+ propSchema={propSchema}
+ value={value}
+ onChange={onChange}
+ disabled={isReadOnly}
+ label={label}
+ errors={errors}
+ path={path}
+ />
+ );
+
+ default: // string
+ return (
+ <StringField
+ value={value}
+ onChange={onChange}
+ disabled={isReadOnly}
+ label={label}
+ isRequired={isRequired}
+ description={propSchema.description}
+ error={error}
+ defaultValue={propSchema.default}
+ format={propSchema.format}
+ maxLength={propSchema.maxLength}
+ />
+ );
+ }
+});
+
+FormField.displayName = "FormField";
+
+// ---------------------------------------------------------------------------
+// Main Component
+// ---------------------------------------------------------------------------
+
+/**
+ * Main JsonSchemaForm component.
+ * Renders a form based on a subset of JSON Schema specification.
+ * Supports primitive types, enums, secrets, objects, and arrays with recursion.
+ */
+export function JsonSchemaForm({
+ schema,
+ values,
+ onChange,
+ errors = {},
+ disabled,
+ className,
+}: JsonSchemaFormProps) {
+ const type = resolveType(schema);
+
+ const handleRootScalarChange = useCallback((newVal: unknown) => {
+ // If root is a scalar, values IS the value
+ onChange(newVal as Record<string, unknown>);
+ }, [onChange]);
+
+ // If it's a scalar at root, render a single FormField
+ if (type !== "object") {
+ return (
+ <div className={className}>
+ <FormField
+ propSchema={schema}
+ value={values}
+ label=""
+ path=""
+ onChange={handleRootScalarChange}
+ disabled={disabled}
+ errors={errors}
+ />
+ </div>
+ );
+ }
+
+ // Memoize to avoid re-renders when parent provides new object references
+ const properties = useMemo(() => schema.properties ?? {}, [schema.properties]);
+ const requiredFields = useMemo(
+ () => new Set(schema.required ?? []),
+ [schema.required],
+ );
+
+ const handleFieldChange = useCallback(
+ (key: string, value: unknown) => {
+ onChange({ ...values, [key]: value });
+ },
+ [onChange, values],
+ );
+
+ if (Object.keys(properties).length === 0) {
+ return (
+ <div
+ className={cn(
+ "py-4 text-center text-sm text-muted-foreground",
+ className,
+ )}
+ >
+ No configuration options available.
+ </div>
+ );
+ }
+
+ return (
+ <div className={cn("space-y-6", className)}>
+ {Object.entries(properties).map(([key, propSchema]) => {
+ const value = values[key];
+ const isRequired = requiredFields.has(key);
+ const error = errors[`/${key}`];
+ const label = labelFromKey(key, propSchema);
+ const path = `/${key}`;
+
+ return (
+ <FormField
+ key={key}
+ propSchema={propSchema}
+ value={value}
+ onChange={(val) => handleFieldChange(key, val)}
+ error={error}
+ disabled={disabled}
+ label={label}
+ isRequired={isRequired}
+ errors={errors}
+ path={path}
+ />
+ );
+ })}
+ </div>
+ );
+}
diff --git a/ui/src/components/Layout.tsx b/ui/src/components/Layout.tsx
index 43094b51c3..e6aaf22aed 100644
--- a/ui/src/components/Layout.tsx
+++ b/ui/src/components/Layout.tsx
@@ -29,6 +29,37 @@ import { cn } from "../lib/utils";
import { NotFoundPage } from "../pages/NotFound";
import { Button } from "@/components/ui/button";
+const INSTANCE_SETTINGS_MEMORY_KEY = "paperclip.lastInstanceSettingsPath";
+const DEFAULT_INSTANCE_SETTINGS_PATH = "/instance/settings/heartbeats";
+
+function normalizeRememberedInstanceSettingsPath(rawPath: string | null): string {
+ if (!rawPath) return DEFAULT_INSTANCE_SETTINGS_PATH;
+
+ const match = rawPath.match(/^([^?#]*)(\?[^#]*)?(#.*)?$/);
+ const pathname = match?.[1] ?? rawPath;
+ const search = match?.[2] ?? "";
+ const hash = match?.[3] ?? "";
+
+ if (pathname === "/instance/settings/heartbeats" || pathname === "/instance/settings/plugins") {
+ return `${pathname}${search}${hash}`;
+ }
+
+ if (/^\/instance\/settings\/plugins\/[^/?#]+$/.test(pathname)) {
+ return `${pathname}${search}${hash}`;
+ }
+
+ return DEFAULT_INSTANCE_SETTINGS_PATH;
+}
+
+function readRememberedInstanceSettingsPath(): string {
+ if (typeof window === "undefined") return DEFAULT_INSTANCE_SETTINGS_PATH;
+ try {
+ return normalizeRememberedInstanceSettingsPath(window.localStorage.getItem(INSTANCE_SETTINGS_MEMORY_KEY));
+ } catch {
+ return DEFAULT_INSTANCE_SETTINGS_PATH;
+ }
+}
+
export function Layout() {
const { sidebarOpen, setSidebarOpen, toggleSidebar, isMobile } = useSidebar();
const { openNewIssue, openOnboarding } = useDialog();
@@ -49,6 +80,7 @@ export function Layout() {
const onboardingTriggered = useRef(false);
const lastMainScrollTop = useRef(0);
const [mobileNavVisible, setMobileNavVisible] = useState(true);
+ const [instanceSettingsTarget, setInstanceSettingsTarget] = useState<string>(() => readRememberedInstanceSettingsPath());
const nextTheme = theme === "dark" ? "light" : "dark";
const matchedCompany = useMemo(() => {
if (!companyPrefix) return null;
@@ -220,6 +252,21 @@ export function Layout() {
};
}, [isMobile]);
+ useEffect(() => {
+ if (!location.pathname.startsWith("/instance/settings/")) return;
+
+ const nextPath = normalizeRememberedInstanceSettingsPath(
+ `${location.pathname}${location.search}${location.hash}`,
+ );
+ setInstanceSettingsTarget(nextPath);
+
+ try {
+ window.localStorage.setItem(INSTANCE_SETTINGS_MEMORY_KEY, nextPath);
+ } catch {
+ // Ignore storage failures in restricted environments.
+ }
+ }, [location.hash, location.pathname, location.search]);
+
return (
<div
className={cn(
@@ -235,7 +282,6 @@ export function Layout() {
</a>
<WorktreeBanner />
<div className={cn("min-h-0 flex-1", isMobile ? "w-full" : "flex overflow-hidden")}>
- {/* Mobile backdrop */}
{isMobile && sidebarOpen && (
<button
type="button"
@@ -245,7 +291,6 @@ export function Layout() {
/>
)}
- {/* Combined sidebar area: company rail + inner sidebar + docs bar */}
{isMobile ? (
<div
className={cn(
@@ -270,7 +315,7 @@ export function Layout() {
</a>
<Button variant="ghost" size="icon-sm" className="text-muted-foreground shrink-0" asChild>
<Link
- to="/instance/settings"
+ to={instanceSettingsTarget}
aria-label="Instance settings"
title="Instance settings"
onClick={() => {
@@ -320,7 +365,7 @@ export function Layout() {
</a>
<Button variant="ghost" size="icon-sm" className="text-muted-foreground shrink-0" asChild>
<Link
- to="/instance/settings"
+ to={instanceSettingsTarget}
aria-label="Instance settings"
title="Instance settings"
onClick={() => {
@@ -346,7 +391,6 @@ export function Layout() {
</div>
)}
- {/* Main content */}
<div className={cn("flex min-w-0 flex-col", isMobile ? "w-full" : "h-full flex-1")}>
<div
className={cn(
diff --git a/ui/src/components/SidebarProjects.tsx b/ui/src/components/SidebarProjects.tsx
index 17fc1101ac..72d0a217b0 100644
--- a/ui/src/components/SidebarProjects.tsx
+++ b/ui/src/components/SidebarProjects.tsx
@@ -25,17 +25,26 @@ import {
CollapsibleContent,
CollapsibleTrigger,
} from "@/components/ui/collapsible";
+import { PluginSlotMount, usePluginSlots } from "@/plugins/slots";
import type { Project } from "@paperclipai/shared";
+type ProjectSidebarSlot = ReturnType<typeof usePluginSlots>["slots"][number];
+
function SortableProjectItem({
activeProjectRef,
+ companyId,
+ companyPrefix,
isMobile,
project,
+ projectSidebarSlots,
setSidebarOpen,
}: {
activeProjectRef: string | null;
+ companyId: string | null;
+ companyPrefix: string | null;
isMobile: boolean;
project: Project;
+ projectSidebarSlots: ProjectSidebarSlot[];
setSidebarOpen: (open: boolean) => void;
}) {
const {
@@ -61,31 +70,52 @@ function SortableProjectItem({
{...attributes}
{...listeners}
>
- <NavLink
- to={`/projects/${routeRef}/issues`}
- onClick={() => {
- if (isMobile) setSidebarOpen(false);
- }}
- className={cn(
- "flex items-center gap-2.5 px-3 py-1.5 text-[13px] font-medium transition-colors",
- activeProjectRef === routeRef || activeProjectRef === project.id
- ? "bg-accent text-foreground"
- : "text-foreground/80 hover:bg-accent/50 hover:text-foreground",
+ <div className="flex flex-col gap-0.5">
+ <NavLink
+ to={`/projects/${routeRef}/issues`}
+ onClick={() => {
+ if (isMobile) setSidebarOpen(false);
+ }}
+ className={cn(
+ "flex items-center gap-2.5 px-3 py-1.5 text-[13px] font-medium transition-colors",
+ activeProjectRef === routeRef || activeProjectRef === project.id
+ ? "bg-accent text-foreground"
+ : "text-foreground/80 hover:bg-accent/50 hover:text-foreground",
+ )}
+ >
+ <span
+ className="shrink-0 h-3.5 w-3.5 rounded-sm"
+ style={{ backgroundColor: project.color ?? "#6366f1" }}
+ />
+ <span className="flex-1 truncate">{project.name}</span>
+ </NavLink>
+ {projectSidebarSlots.length > 0 && (
+ <div className="ml-5 flex flex-col gap-0.5">
+ {projectSidebarSlots.map((slot) => (
+ <PluginSlotMount
+ key={`${project.id}:${slot.pluginKey}:${slot.id}`}
+ slot={slot}
+ context={{
+ companyId,
+ companyPrefix,
+ projectId: project.id,
+ projectRef: routeRef,
+ entityId: project.id,
+ entityType: "project",
+ }}
+ missingBehavior="placeholder"
+ />
+ ))}
+ </div>
)}
- >
- <span
- className="shrink-0 h-3.5 w-3.5 rounded-sm"
- style={{ backgroundColor: project.color ?? "#6366f1" }}
- />
- <span className="flex-1 truncate">{project.name}</span>
- </NavLink>
+ </div>
</div>
);
}
export function SidebarProjects() {
const [open, setOpen] = useState(true);
- const { selectedCompanyId } = useCompany();
+ const { selectedCompany, selectedCompanyId } = useCompany();
const { openNewProject } = useDialog();
const { isMobile, setSidebarOpen } = useSidebar();
const location = useLocation();
@@ -99,6 +129,12 @@ export function SidebarProjects() {
queryKey: queryKeys.auth.session,
queryFn: () => authApi.getSession(),
});
+ const { slots: projectSidebarSlots } = usePluginSlots({
+ slotTypes: ["projectSidebarItem"],
+ entityType: "project",
+ companyId: selectedCompanyId,
+ enabled: !!selectedCompanyId,
+ });
const currentUserId = session?.user?.id ?? session?.session?.userId ?? null;
@@ -178,8 +214,11 @@ export function SidebarProjects() {
<SortableProjectItem
key={project.id}
activeProjectRef={activeProjectRef}
+ companyId={selectedCompanyId}
+ companyPrefix={selectedCompany?.issuePrefix ?? null}
isMobile={isMobile}
project={project}
+ projectSidebarSlots={projectSidebarSlots}
setSidebarOpen={setSidebarOpen}
/>
))}
diff --git a/ui/src/lib/queryKeys.ts b/ui/src/lib/queryKeys.ts
index c500afdc5f..a41c5d3195 100644
--- a/ui/src/lib/queryKeys.ts
+++ b/ui/src/lib/queryKeys.ts
@@ -75,4 +75,20 @@ export const queryKeys = {
liveRuns: (companyId: string) => ["live-runs", companyId] as const,
runIssues: (runId: string) => ["run-issues", runId] as const,
org: (companyId: string) => ["org", companyId] as const,
+ plugins: {
+ all: ["plugins"] as const,
+ examples: ["plugins", "examples"] as const,
+ detail: (pluginId: string) => ["plugins", pluginId] as const,
+ health: (pluginId: string) => ["plugins", pluginId, "health"] as const,
+ uiContributions: (companyId?: string | null) =>
+ ["plugins", "ui-contributions", companyId ?? "global"] as const,
+ config: (pluginId: string) => ["plugins", pluginId, "config"] as const,
+ dashboard: (pluginId: string) => ["plugins", pluginId, "dashboard"] as const,
+ logs: (pluginId: string) => ["plugins", pluginId, "logs"] as const,
+ company: (companyId: string) => ["plugins", "company", companyId] as const,
+ companyList: (companyId: string, available?: boolean) =>
+ ["plugins", "company", companyId, "list", available ?? "all"] as const,
+ companyDetail: (companyId: string, pluginId: string) =>
+ ["plugins", "company", companyId, pluginId] as const,
+ },
};
diff --git a/ui/src/main.tsx b/ui/src/main.tsx
index 33fd6c81d0..4fe0da4883 100644
--- a/ui/src/main.tsx
+++ b/ui/src/main.tsx
@@ -1,4 +1,6 @@
+import * as React from "react";
import { StrictMode } from "react";
+import * as ReactDOM from "react-dom";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "@/lib/router";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
@@ -12,9 +14,12 @@ import { DialogProvider } from "./context/DialogContext";
import { ToastProvider } from "./context/ToastContext";
import { ThemeProvider } from "./context/ThemeContext";
import { TooltipProvider } from "@/components/ui/tooltip";
+import { initPluginBridge } from "./plugins/bridge-init";
import "@mdxeditor/editor/style.css";
import "./index.css";
+initPluginBridge(React, ReactDOM);
+
if ("serviceWorker" in navigator) {
window.addEventListener("load", () => {
navigator.serviceWorker.register("/sw.js");
diff --git a/ui/src/pages/Dashboard.tsx b/ui/src/pages/Dashboard.tsx
index 051fc053a0..46589760d5 100644
--- a/ui/src/pages/Dashboard.tsx
+++ b/ui/src/pages/Dashboard.tsx
@@ -24,6 +24,7 @@ import { ActiveAgentsPanel } from "../components/ActiveAgentsPanel";
import { ChartCard, RunActivityChart, PriorityChart, IssueStatusChart, SuccessRateChart } from "../components/ActivityCharts";
import { PageSkeleton } from "../components/PageSkeleton";
import type { Agent, Issue } from "@paperclipai/shared";
+import { PluginSlotOutlet } from "@/plugins/slots";
function getRecentIssues(issues: Issue[]): Issue[] {
return [...issues]
@@ -276,6 +277,13 @@ export function Dashboard() {
</ChartCard>
</div>
+ <PluginSlotOutlet
+ slotTypes={["dashboardWidget"]}
+ context={{ companyId: selectedCompanyId }}
+ className="grid gap-4 md:grid-cols-2"
+ itemClassName="rounded-lg border bg-card p-4 shadow-sm"
+ />
+
<div className="grid md:grid-cols-2 gap-4">
{/* Recent Activity */}
{recentActivity.length > 0 && (
diff --git a/ui/src/pages/PluginManager.tsx b/ui/src/pages/PluginManager.tsx
new file mode 100644
index 0000000000..de36f658a4
--- /dev/null
+++ b/ui/src/pages/PluginManager.tsx
@@ -0,0 +1,512 @@
+/**
+ * @fileoverview Plugin Manager page — admin UI for discovering,
+ * installing, enabling/disabling, and uninstalling plugins.
+ *
+ * @see PLUGIN_SPEC.md §9 — Plugin Marketplace / Manager
+ */
+import { useEffect, useMemo, useState } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import type { PluginRecord } from "@paperclipai/shared";
+import { Link } from "@/lib/router";
+import { AlertTriangle, FlaskConical, Plus, Power, Puzzle, Settings, Trash } from "lucide-react";
+import { useCompany } from "@/context/CompanyContext";
+import { useBreadcrumbs } from "@/context/BreadcrumbContext";
+import { pluginsApi } from "@/api/plugins";
+import { queryKeys } from "@/lib/queryKeys";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Card, CardContent } from "@/components/ui/card";
+import { Badge } from "@/components/ui/badge";
+import {
+ Dialog,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+ DialogTrigger,
+} from "@/components/ui/dialog";
+import { useToast } from "@/context/ToastContext";
+import { cn } from "@/lib/utils";
+
+function firstNonEmptyLine(value: string | null | undefined): string | null {
+ if (!value) return null;
+ const line = value
+ .split(/\r?\n/)
+ .map((entry) => entry.trim())
+ .find(Boolean);
+ return line ?? null;
+}
+
+function getPluginErrorSummary(plugin: PluginRecord): string {
+ return firstNonEmptyLine(plugin.lastError) ?? "Plugin entered an error state without a stored error message.";
+}
+
+/**
+ * PluginManager page component.
+ *
+ * Provides a management UI for the Paperclip plugin system:
+ * - Lists all installed plugins with their status, version, and category badges.
+ * - Allows installing new plugins by npm package name.
+ * - Provides per-plugin actions: enable, disable, navigate to settings.
+ * - Uninstall with a two-step confirmation dialog to prevent accidental removal.
+ *
+ * Data flow:
+ * - Reads from `GET /api/plugins` via `pluginsApi.list()`.
+ * - Mutations (install / uninstall / enable / disable) invalidate
+ * `queryKeys.plugins.all` so the list refreshes automatically.
+ *
+ * @see PluginSettings — linked from the Settings icon on each plugin row.
+ * @see doc/plugins/PLUGIN_SPEC.md §3 — Plugin Lifecycle for status semantics.
+ */
+export function PluginManager() {
+ const { selectedCompany, selectedCompanyId } = useCompany();
+ const { setBreadcrumbs } = useBreadcrumbs();
+ const queryClient = useQueryClient();
+ const { pushToast } = useToast();
+
+ const [installPackage, setInstallPackage] = useState("");
+ const [installDialogOpen, setInstallDialogOpen] = useState(false);
+ const [uninstallPluginId, setUninstallPluginId] = useState<string | null>(null);
+ const [uninstallPluginName, setUninstallPluginName] = useState<string>("");
+ const [errorDetailsPlugin, setErrorDetailsPlugin] = useState<PluginRecord | null>(null);
+
+ useEffect(() => {
+ setBreadcrumbs([
+ { label: selectedCompany?.name ?? "Company", href: "/dashboard" },
+ { label: "Settings", href: "/instance/settings/heartbeats" },
+ { label: "Plugins" },
+ ]);
+ }, [selectedCompany?.name, setBreadcrumbs]);
+
+ const { data: plugins, isLoading, error } = useQuery({
+ queryKey: queryKeys.plugins.all,
+ queryFn: () => pluginsApi.list(),
+ });
+
+ const examplesQuery = useQuery({
+ queryKey: queryKeys.plugins.examples,
+ queryFn: () => pluginsApi.listExamples(),
+ });
+
+ const invalidatePluginQueries = () => {
+ queryClient.invalidateQueries({ queryKey: queryKeys.plugins.all });
+ queryClient.invalidateQueries({ queryKey: queryKeys.plugins.examples });
+ queryClient.invalidateQueries({ queryKey: ["plugins", "ui-contributions"] });
+ if (selectedCompanyId) {
+ queryClient.invalidateQueries({ queryKey: queryKeys.plugins.companyList(selectedCompanyId) });
+ }
+ };
+
+ const installMutation = useMutation({
+ mutationFn: (params: { packageName: string; version?: string; isLocalPath?: boolean }) =>
+ pluginsApi.install(params),
+ onSuccess: () => {
+ invalidatePluginQueries();
+ setInstallDialogOpen(false);
+ setInstallPackage("");
+ pushToast({ title: "Plugin installed successfully", tone: "success" });
+ },
+ onError: (err: Error) => {
+ pushToast({ title: "Failed to install plugin", body: err.message, tone: "error" });
+ },
+ });
+
+ const uninstallMutation = useMutation({
+ mutationFn: (pluginId: string) => pluginsApi.uninstall(pluginId),
+ onSuccess: () => {
+ invalidatePluginQueries();
+ pushToast({ title: "Plugin uninstalled successfully", tone: "success" });
+ },
+ onError: (err: Error) => {
+ pushToast({ title: "Failed to uninstall plugin", body: err.message, tone: "error" });
+ },
+ });
+
+ const enableMutation = useMutation({
+ mutationFn: (pluginId: string) => pluginsApi.enable(pluginId),
+ onSuccess: () => {
+ invalidatePluginQueries();
+ pushToast({ title: "Plugin enabled", tone: "success" });
+ },
+ onError: (err: Error) => {
+ pushToast({ title: "Failed to enable plugin", body: err.message, tone: "error" });
+ },
+ });
+
+ const disableMutation = useMutation({
+ mutationFn: (pluginId: string) => pluginsApi.disable(pluginId),
+ onSuccess: () => {
+ invalidatePluginQueries();
+ pushToast({ title: "Plugin disabled", tone: "info" });
+ },
+ onError: (err: Error) => {
+ pushToast({ title: "Failed to disable plugin", body: err.message, tone: "error" });
+ },
+ });
+
+ const installedPlugins = plugins ?? [];
+ const examples = examplesQuery.data ?? [];
+ const installedByPackageName = new Map(installedPlugins.map((plugin) => [plugin.packageName, plugin]));
+ const examplePackageNames = new Set(examples.map((example) => example.packageName));
+ const errorSummaryByPluginId = useMemo(
+ () =>
+ new Map(
+ installedPlugins.map((plugin) => [plugin.id, getPluginErrorSummary(plugin)])
+ ),
+ [installedPlugins]
+ );
+
+ if (isLoading) return <div className="p-4 text-sm text-muted-foreground">Loading plugins...</div>;
+ if (error) return <div className="p-4 text-sm text-destructive">Failed to load plugins.</div>;
+
+ return (
+ <div className="space-y-6 max-w-5xl">
+ <div className="flex items-center justify-between">
+ <div className="flex items-center gap-2">
+ <Puzzle className="h-6 w-6 text-muted-foreground" />
+ <h1 className="text-xl font-semibold">Plugin Manager</h1>
+ </div>
+
+ <Dialog open={installDialogOpen} onOpenChange={setInstallDialogOpen}>
+ <DialogTrigger asChild>
+ <Button size="sm" className="gap-2">
+ <Plus className="h-4 w-4" />
+ Install Plugin
+ </Button>
+ </DialogTrigger>
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>Install Plugin</DialogTitle>
+ <DialogDescription>
+ Enter the npm package name of the plugin you wish to install.
+ </DialogDescription>
+ </DialogHeader>
+ <div className="grid gap-4 py-4">
+ <div className="grid gap-2">
+ <Label htmlFor="packageName">npm Package Name</Label>
+ <Input
+ id="packageName"
+ placeholder="@paperclipai/plugin-example"
+ value={installPackage}
+ onChange={(e) => setInstallPackage(e.target.value)}
+ />
+ </div>
+ </div>
+ <DialogFooter>
+ <Button variant="outline" onClick={() => setInstallDialogOpen(false)}>Cancel</Button>
+ <Button
+ onClick={() => installMutation.mutate({ packageName: installPackage })}
+ disabled={!installPackage || installMutation.isPending}
+ >
+ {installMutation.isPending ? "Installing..." : "Install"}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ </div>
+
+ <div className="rounded-lg border border-amber-500/30 bg-amber-500/5 px-4 py-3">
+ <div className="flex items-start gap-3">
+ <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0 text-amber-700" />
+ <div className="space-y-1 text-sm">
+ <p className="font-medium text-foreground">Plugins are alpha.</p>
+ <p className="text-muted-foreground">
+ The plugin runtime and API surface are still changing. Expect breaking changes while this feature settles.
+ </p>
+ </div>
+ </div>
+ </div>
+
+ <section className="space-y-3">
+ <div className="flex items-center gap-2">
+ <FlaskConical className="h-5 w-5 text-muted-foreground" />
+ <h2 className="text-base font-semibold">Available Plugins</h2>
+ <Badge variant="outline">Examples</Badge>
+ </div>
+
+ {examplesQuery.isLoading ? (
+ <div className="text-sm text-muted-foreground">Loading bundled examples...</div>
+ ) : examplesQuery.error ? (
+ <div className="text-sm text-destructive">Failed to load bundled examples.</div>
+ ) : examples.length === 0 ? (
+ <div className="rounded-md border border-dashed px-4 py-3 text-sm text-muted-foreground">
+ No bundled example plugins were found in this checkout.
+ </div>
+ ) : (
+ <ul className="divide-y rounded-md border bg-card">
+ {examples.map((example) => {
+ const installedPlugin = installedByPackageName.get(example.packageName);
+ const installPending =
+ installMutation.isPending &&
+ installMutation.variables?.isLocalPath &&
+ installMutation.variables.packageName === example.localPath;
+
+ return (
+ <li key={example.packageName}>
+ <div className="flex items-center gap-4 px-4 py-3">
+ <div className="min-w-0 flex-1">
+ <div className="flex flex-wrap items-center gap-2">
+ <span className="font-medium">{example.displayName}</span>
+ <Badge variant="outline">Example</Badge>
+ {installedPlugin ? (
+ <Badge
+ variant={installedPlugin.status === "ready" ? "default" : "secondary"}
+ className={installedPlugin.status === "ready" ? "bg-green-600 hover:bg-green-700" : ""}
+ >
+ {installedPlugin.status}
+ </Badge>
+ ) : (
+ <Badge variant="secondary">Not installed</Badge>
+ )}
+ </div>
+ <p className="mt-1 text-sm text-muted-foreground">{example.description}</p>
+ <p className="mt-1 text-xs text-muted-foreground">{example.packageName}</p>
+ </div>
+ <div className="flex items-center gap-2 shrink-0">
+ {installedPlugin ? (
+ <>
+ {installedPlugin.status !== "ready" && (
+ <Button
+ variant="outline"
+ size="sm"
+ disabled={enableMutation.isPending}
+ onClick={() => enableMutation.mutate(installedPlugin.id)}
+ >
+ Enable
+ </Button>
+ )}
+ <Button variant="outline" size="sm" asChild>
+ <Link to={`/instance/settings/plugins/${installedPlugin.id}`}>
+ {installedPlugin.status === "ready" ? "Open Settings" : "Review"}
+ </Link>
+ </Button>
+ </>
+ ) : (
+ <Button
+ size="sm"
+ disabled={installPending || installMutation.isPending}
+ onClick={() =>
+ installMutation.mutate({
+ packageName: example.localPath,
+ isLocalPath: true,
+ })
+ }
+ >
+ {installPending ? "Installing..." : "Install Example"}
+ </Button>
+ )}
+ </div>
+ </div>
+ </li>
+ );
+ })}
+ </ul>
+ )}
+ </section>
+
+ <section className="space-y-3">
+ <div className="flex items-center gap-2">
+ <Puzzle className="h-5 w-5 text-muted-foreground" />
+ <h2 className="text-base font-semibold">Installed Plugins</h2>
+ </div>
+
+ {!installedPlugins.length ? (
+ <Card className="bg-muted/30">
+ <CardContent className="flex flex-col items-center justify-center py-10">
+ <Puzzle className="h-10 w-10 text-muted-foreground mb-4" />
+ <p className="text-sm font-medium">No plugins installed</p>
+ <p className="text-xs text-muted-foreground mt-1">
+ Install a plugin to extend functionality.
+ </p>
+ </CardContent>
+ </Card>
+ ) : (
+ <ul className="divide-y rounded-md border bg-card">
+ {installedPlugins.map((plugin) => (
+ <li key={plugin.id}>
+ <div className="flex items-start gap-4 px-4 py-3">
+ <div className="min-w-0 flex-1">
+ <div className="flex flex-wrap items-center gap-2">
+ <Link
+ to={`/instance/settings/plugins/${plugin.id}`}
+ className="font-medium hover:underline truncate block"
+ title={plugin.manifestJson.displayName ?? plugin.packageName}
+ >
+ {plugin.manifestJson.displayName ?? plugin.packageName}
+ </Link>
+ {examplePackageNames.has(plugin.packageName) && (
+ <Badge variant="outline">Example</Badge>
+ )}
+ </div>
+ <div>
+ <p className="text-xs text-muted-foreground mt-0.5 truncate" title={plugin.packageName}>
+ {plugin.packageName} · v{plugin.manifestJson.version ?? plugin.version}
+ </p>
+ </div>
+ <p className="text-sm text-muted-foreground truncate mt-0.5" title={plugin.manifestJson.description}>
+ {plugin.manifestJson.description || "No description provided."}
+ </p>
+ {plugin.status === "error" && (
+ <div className="mt-3 rounded-md border border-red-500/25 bg-red-500/[0.06] px-3 py-2">
+ <div className="flex flex-wrap items-start gap-3">
+ <div className="min-w-0 flex-1">
+ <div className="flex items-center gap-2 text-sm font-medium text-red-700 dark:text-red-300">
+ <AlertTriangle className="h-4 w-4 shrink-0" />
+ <span>Plugin error</span>
+ </div>
+ <p
+ className="mt-1 text-sm text-red-700/90 dark:text-red-200/90 break-words"
+ title={plugin.lastError ?? undefined}
+ >
+ {errorSummaryByPluginId.get(plugin.id)}
+ </p>
+ </div>
+ <Button
+ variant="outline"
+ size="sm"
+ className="border-red-500/30 bg-background/60 text-red-700 hover:bg-red-500/10 hover:text-red-800 dark:text-red-200 dark:hover:text-red-100"
+ onClick={() => setErrorDetailsPlugin(plugin)}
+ >
+ View full error
+ </Button>
+ </div>
+ </div>
+ )}
+ </div>
+ <div className="flex shrink-0 self-center">
+ <div className="flex flex-col items-end gap-2">
+ <div className="flex items-center gap-2">
+ <Badge
+ variant={
+ plugin.status === "ready"
+ ? "default"
+ : plugin.status === "error"
+ ? "destructive"
+ : "secondary"
+ }
+ className={cn(
+ "shrink-0",
+ plugin.status === "ready" ? "bg-green-600 hover:bg-green-700" : ""
+ )}
+ >
+ {plugin.status}
+ </Badge>
+ <Button
+ variant="outline"
+ size="icon-sm"
+ className="h-8 w-8"
+ title={plugin.status === "ready" ? "Disable" : "Enable"}
+ onClick={() => {
+ if (plugin.status === "ready") {
+ disableMutation.mutate(plugin.id);
+ } else {
+ enableMutation.mutate(plugin.id);
+ }
+ }}
+ disabled={enableMutation.isPending || disableMutation.isPending}
+ >
+ <Power className={cn("h-4 w-4", plugin.status === "ready" ? "text-green-600" : "")} />
+ </Button>
+ <Button
+ variant="outline"
+ size="icon-sm"
+ className="h-8 w-8 text-destructive hover:text-destructive"
+ title="Uninstall"
+ onClick={() => {
+ setUninstallPluginId(plugin.id);
+ setUninstallPluginName(plugin.manifestJson.displayName ?? plugin.packageName);
+ }}
+ disabled={uninstallMutation.isPending}
+ >
+ <Trash className="h-4 w-4" />
+ </Button>
+ </div>
+ <Button variant="outline" size="sm" className="mt-2 h-8" asChild>
+ <Link to={`/instance/settings/plugins/${plugin.id}`}>
+ <Settings className="h-4 w-4" />
+ Configure
+ </Link>
+ </Button>
+ </div>
+ </div>
+ </div>
+ </li>
+ ))}
+ </ul>
+ )}
+ </section>
+
+ <Dialog
+ open={uninstallPluginId !== null}
+ onOpenChange={(open) => { if (!open) setUninstallPluginId(null); }}
+ >
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>Uninstall Plugin</DialogTitle>
+ <DialogDescription>
+ Are you sure you want to uninstall <strong>{uninstallPluginName}</strong>? This action cannot be undone.
+ </DialogDescription>
+ </DialogHeader>
+ <DialogFooter>
+ <Button variant="outline" onClick={() => setUninstallPluginId(null)}>Cancel</Button>
+ <Button
+ variant="destructive"
+ disabled={uninstallMutation.isPending}
+ onClick={() => {
+ if (uninstallPluginId) {
+ uninstallMutation.mutate(uninstallPluginId, {
+ onSettled: () => setUninstallPluginId(null),
+ });
+ }
+ }}
+ >
+ {uninstallMutation.isPending ? "Uninstalling..." : "Uninstall"}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+
+ <Dialog
+ open={errorDetailsPlugin !== null}
+ onOpenChange={(open) => { if (!open) setErrorDetailsPlugin(null); }}
+ >
+ <DialogContent className="sm:max-w-2xl">
+ <DialogHeader>
+ <DialogTitle>Error Details</DialogTitle>
+ <DialogDescription>
+ {errorDetailsPlugin?.manifestJson.displayName ?? errorDetailsPlugin?.packageName ?? "Plugin"} hit an error state.
+ </DialogDescription>
+ </DialogHeader>
+ <div className="space-y-4">
+ <div className="rounded-md border border-red-500/25 bg-red-500/[0.06] px-4 py-3">
+ <div className="flex items-start gap-3">
+ <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0 text-red-700 dark:text-red-300" />
+ <div className="space-y-1 text-sm">
+ <p className="font-medium text-red-700 dark:text-red-300">
+ What errored
+ </p>
+ <p className="text-red-700/90 dark:text-red-200/90 break-words">
+ {errorDetailsPlugin ? getPluginErrorSummary(errorDetailsPlugin) : "No error summary available."}
+ </p>
+ </div>
+ </div>
+ </div>
+ <div className="space-y-2">
+ <p className="text-sm font-medium">Full error output</p>
+ <pre className="max-h-[50vh] overflow-auto rounded-md border bg-muted/40 p-3 text-xs leading-5 whitespace-pre-wrap break-words">
+ {errorDetailsPlugin?.lastError ?? "No stored error message."}
+ </pre>
+ </div>
+ </div>
+ <DialogFooter>
+ <Button variant="outline" onClick={() => setErrorDetailsPlugin(null)}>
+ Close
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ </div>
+ );
+}
diff --git a/ui/src/pages/PluginPage.tsx b/ui/src/pages/PluginPage.tsx
new file mode 100644
index 0000000000..5813fd0742
--- /dev/null
+++ b/ui/src/pages/PluginPage.tsx
@@ -0,0 +1,113 @@
+import { useEffect, useMemo } from "react";
+import { Link, Navigate, useParams } from "@/lib/router";
+import { useQuery } from "@tanstack/react-query";
+import { useCompany } from "@/context/CompanyContext";
+import { useBreadcrumbs } from "@/context/BreadcrumbContext";
+import { pluginsApi } from "@/api/plugins";
+import { queryKeys } from "@/lib/queryKeys";
+import { PluginSlotMount } from "@/plugins/slots";
+import { Button } from "@/components/ui/button";
+import { ArrowLeft } from "lucide-react";
+
+/**
+ * Company-context plugin page. Renders a plugin's `page` slot at
+ * `/:companyPrefix/plugins/:pluginId` when the plugin declares a page slot
+ * and is enabled for that company.
+ *
+ * @see doc/plugins/PLUGIN_SPEC.md §19.2 — Company-Context Routes
+ * @see doc/plugins/PLUGIN_SPEC.md §24.4 — Company-Context Plugin Page
+ */
+export function PluginPage() {
+ const { companyPrefix: routeCompanyPrefix, pluginId } = useParams<{
+ companyPrefix?: string;
+ pluginId: string;
+ }>();
+ const { companies, selectedCompanyId } = useCompany();
+ const { setBreadcrumbs } = useBreadcrumbs();
+
+ const resolvedCompanyId = useMemo(() => {
+ if (!routeCompanyPrefix) return selectedCompanyId ?? null;
+ const requested = routeCompanyPrefix.toUpperCase();
+ return companies.find((c) => c.issuePrefix.toUpperCase() === requested)?.id ?? selectedCompanyId ?? null;
+ }, [companies, routeCompanyPrefix, selectedCompanyId]);
+
+ const companyPrefix = useMemo(
+ () => (resolvedCompanyId ? companies.find((c) => c.id === resolvedCompanyId)?.issuePrefix ?? null : null),
+ [companies, resolvedCompanyId],
+ );
+
+ const { data: contributions } = useQuery({
+ queryKey: queryKeys.plugins.uiContributions(resolvedCompanyId ?? undefined),
+ queryFn: () => pluginsApi.listUiContributions(resolvedCompanyId ?? undefined),
+ enabled: !!resolvedCompanyId && !!pluginId,
+ });
+
+ const pageSlot = useMemo(() => {
+ if (!pluginId || !contributions) return null;
+ const contribution = contributions.find((c) => c.pluginId === pluginId);
+ if (!contribution) return null;
+ const slot = contribution.slots.find((s) => s.type === "page");
+ if (!slot) return null;
+ return {
+ ...slot,
+ pluginId: contribution.pluginId,
+ pluginKey: contribution.pluginKey,
+ pluginDisplayName: contribution.displayName,
+ pluginVersion: contribution.version,
+ };
+ }, [pluginId, contributions]);
+
+ const context = useMemo(
+ () => ({
+ companyId: resolvedCompanyId ?? null,
+ companyPrefix,
+ }),
+ [resolvedCompanyId, companyPrefix],
+ );
+
+ useEffect(() => {
+ if (pageSlot) {
+ setBreadcrumbs([
+ { label: "Plugins", href: "/instance/settings/plugins" },
+ { label: pageSlot.pluginDisplayName },
+ ]);
+ }
+ }, [pageSlot, companyPrefix, setBreadcrumbs]);
+
+ if (!resolvedCompanyId) {
+ return (
+ <div className="space-y-4">
+ <p className="text-sm text-muted-foreground">Select a company to view this page.</p>
+ </div>
+ );
+ }
+
+ if (!contributions) {
+ return <div className="text-sm text-muted-foreground">Loading…</div>;
+ }
+
+ if (!pageSlot) {
+ // No page slot: redirect to plugin settings where plugin info is always shown
+ const settingsPath = `/instance/settings/plugins/${pluginId}`;
+ return <Navigate to={settingsPath} replace />;
+ }
+
+ return (
+ <div className="space-y-4">
+ <div className="flex items-center gap-2">
+ <Button variant="ghost" size="sm" asChild>
+ <Link to={companyPrefix ? `/${companyPrefix}/dashboard` : "/dashboard"}>
+ <ArrowLeft className="h-4 w-4 mr-1" />
+ Back
+ </Link>
+ </Button>
+ </div>
+ <PluginSlotMount
+ slot={pageSlot}
+ context={context}
+ className="min-h-[200px]"
+ missingBehavior="placeholder"
+ />
+ </div>
+ );
+}
diff --git a/ui/src/pages/PluginSettings.tsx b/ui/src/pages/PluginSettings.tsx
new file mode 100644
index 0000000000..0d36b3d88b
--- /dev/null
+++ b/ui/src/pages/PluginSettings.tsx
@@ -0,0 +1,836 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { Puzzle, ArrowLeft, ShieldAlert, ActivitySquare, CheckCircle, XCircle, Loader2, Clock, Cpu, Webhook, CalendarClock, AlertTriangle } from "lucide-react";
+import { useCompany } from "@/context/CompanyContext";
+import { useBreadcrumbs } from "@/context/BreadcrumbContext";
+import { Link, Navigate, useParams } from "@/lib/router";
+import { PluginSlotMount, usePluginSlots } from "@/plugins/slots";
+import { pluginsApi } from "@/api/plugins";
+import { queryKeys } from "@/lib/queryKeys";
+import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
+import {
+ Card,
+ CardContent,
+ CardDescription,
+ CardHeader,
+ CardTitle,
+} from "@/components/ui/card";
+import { Separator } from "@/components/ui/separator";
+import { Tabs, TabsContent } from "@/components/ui/tabs";
+import { PageTabBar } from "@/components/PageTabBar";
+import {
+ JsonSchemaForm,
+ validateJsonSchemaForm,
+ getDefaultValues,
+ type JsonSchemaNode,
+} from "@/components/JsonSchemaForm";
+
+/**
+ * PluginSettings page component.
+ *
+ * Detailed settings and diagnostics page for a single installed plugin.
+ * Navigated to from {@link PluginManager} via the Settings gear icon.
+ *
+ * Displays:
+ * - Plugin identity: display name, id, version, description, categories.
+ * - Manifest-declared capabilities (what data and features the plugin can access).
+ * - Health check results (only for `ready` plugins; polled every 30 seconds).
+ * - Runtime dashboard: worker status/uptime, recent job runs, webhook deliveries.
+ * - Auto-generated config form from `instanceConfigSchema` (when no custom settings page).
+ * - Plugin-contributed settings UI via `<PluginSlotOutlet type="settingsPage" />`.
+ *
+ * Data flow:
+ * - `GET /api/plugins/:pluginId` — plugin record (refreshes on mount).
+ * - `GET /api/plugins/:pluginId/health` — health diagnostics (polling).
+ * Only fetched when `plugin.status === "ready"`.
+ * - `GET /api/plugins/:pluginId/dashboard` — aggregated runtime dashboard data (polling).
+ * - `GET /api/plugins/:pluginId/config` — current config values.
+ * - `POST /api/plugins/:pluginId/config` — save config values.
+ * - `POST /api/plugins/:pluginId/config/test` — test configuration.
+ *
+ * URL params:
+ * - `companyPrefix` — the company slug (for breadcrumb links).
+ * - `pluginId` — UUID of the plugin to display.
+ *
+ * @see PluginManager — parent list page.
+ * @see doc/plugins/PLUGIN_SPEC.md §13 — Plugin Health Checks.
+ * @see doc/plugins/PLUGIN_SPEC.md §19.8 — Plugin Settings UI.
+ */
+export function PluginSettings() {
+ const { selectedCompany, selectedCompanyId } = useCompany();
+ const { setBreadcrumbs } = useBreadcrumbs();
+ const { companyPrefix, pluginId } = useParams<{ companyPrefix?: string; pluginId: string }>();
+ const [activeTab, setActiveTab] = useState<"configuration" | "status">("configuration");
+
+ const { data: plugin, isLoading: pluginLoading } = useQuery({
+ queryKey: queryKeys.plugins.detail(pluginId!),
+ queryFn: () => pluginsApi.get(pluginId!),
+ enabled: !!pluginId,
+ });
+
+ const { data: healthData, isLoading: healthLoading } = useQuery({
+ queryKey: queryKeys.plugins.health(pluginId!),
+ queryFn: () => pluginsApi.health(pluginId!),
+ enabled: !!pluginId && plugin?.status === "ready",
+ refetchInterval: 30000,
+ });
+
+ const { data: dashboardData } = useQuery({
+ queryKey: queryKeys.plugins.dashboard(pluginId!),
+ queryFn: () => pluginsApi.dashboard(pluginId!),
+ enabled: !!pluginId,
+ refetchInterval: 30000,
+ });
+
+ const { data: recentLogs } = useQuery({
+ queryKey: queryKeys.plugins.logs(pluginId!),
+ queryFn: () => pluginsApi.logs(pluginId!, { limit: 50 }),
+ enabled: !!pluginId && plugin?.status === "ready",
+ refetchInterval: 30000,
+ });
+
+ // Fetch existing config for the plugin
+ const configSchema = plugin?.manifestJson?.instanceConfigSchema as JsonSchemaNode | undefined;
+ const hasConfigSchema = configSchema && configSchema.properties && Object.keys(configSchema.properties).length > 0;
+
+ const { data: configData, isLoading: configLoading } = useQuery({
+ queryKey: queryKeys.plugins.config(pluginId!),
+ queryFn: () => pluginsApi.getConfig(pluginId!),
+ enabled: !!pluginId && !!hasConfigSchema,
+ });
+
+ const { slots } = usePluginSlots({
+ slotTypes: ["settingsPage"],
+ companyId: selectedCompanyId,
+ enabled: !!selectedCompanyId,
+ });
+
+ // Filter slots to only show settings pages for this specific plugin
+ const pluginSlots = slots.filter((slot) => slot.pluginId === pluginId);
+
+ // If the plugin has a custom settingsPage slot, prefer that over auto-generated form
+ const hasCustomSettingsPage = pluginSlots.length > 0;
+
+ useEffect(() => {
+ setBreadcrumbs([
+ { label: selectedCompany?.name ?? "Company", href: "/dashboard" },
+ { label: "Settings", href: "/instance/settings/heartbeats" },
+ { label: "Plugins", href: "/instance/settings/plugins" },
+ { label: plugin?.manifestJson?.displayName ?? plugin?.packageName ?? "Plugin Details" },
+ ]);
+ }, [selectedCompany?.name, setBreadcrumbs, companyPrefix, plugin]);
+
+ useEffect(() => {
+ setActiveTab("configuration");
+ }, [pluginId]);
+
+ if (pluginLoading) {
+ return <div className="p-4 text-sm text-muted-foreground">Loading plugin details...</div>;
+ }
+
+ if (!plugin) {
+ return <Navigate to="/instance/settings/plugins" replace />;
+ }
+
+ const displayStatus = plugin.status;
+ const statusVariant =
+ plugin.status === "ready"
+ ? "default"
+ : plugin.status === "error"
+ ? "destructive"
+ : "secondary";
+ const pluginDescription = plugin.manifestJson.description || "No description provided.";
+ const pluginCapabilities = plugin.manifestJson.capabilities ?? [];
+
+ return (
+ <div className="space-y-6 max-w-5xl">
+ <div className="flex items-center gap-4">
+ <Link to="/instance/settings/plugins">
+ <Button variant="outline" size="icon" className="h-8 w-8">
+ <ArrowLeft className="h-4 w-4" />
+ </Button>
+ </Link>
+ <div className="flex items-center gap-2">
+ <Puzzle className="h-6 w-6 text-muted-foreground" />
+ <h1 className="text-xl font-semibold">{plugin.manifestJson.displayName ?? plugin.packageName}</h1>
+ <Badge variant={statusVariant} className="ml-2">
+ {displayStatus}
+ </Badge>
+ <Badge variant="outline" className="ml-1">
+ v{plugin.manifestJson.version ?? plugin.version}
+ </Badge>
+ </div>
+ </div>
+
+ <Tabs value={activeTab} onValueChange={(value) => setActiveTab(value as "configuration" | "status")} className="space-y-6">
+ <PageTabBar
+ align="start"
+ items={[
+ { value: "configuration", label: "Configuration" },
+ { value: "status", label: "Status" },
+ ]}
+ value={activeTab}
+ onValueChange={(value) => setActiveTab(value as "configuration" | "status")}
+ />
+
+ <TabsContent value="configuration" className="space-y-6">
+ <div className="space-y-8">
+ <section className="space-y-5">
+ <h2 className="text-base font-semibold">About</h2>
+ <div className="grid gap-8 lg:grid-cols-[minmax(0,1.4fr)_minmax(220px,0.8fr)]">
+ <div className="space-y-2">
+ <h3 className="text-sm font-medium text-muted-foreground">Description</h3>
+ <p className="text-sm leading-6 text-foreground/90">{pluginDescription}</p>
+ </div>
+ <div className="space-y-4 text-sm">
+ <div className="space-y-1.5">
+ <h3 className="font-medium text-muted-foreground">Author</h3>
+ <p className="text-foreground">{plugin.manifestJson.author}</p>
+ </div>
+ <div className="space-y-2">
+ <h3 className="font-medium text-muted-foreground">Categories</h3>
+ <div className="flex flex-wrap gap-2">
+ {plugin.categories.length > 0 ? (
+ plugin.categories.map((category) => (
+ <Badge key={category} variant="outline" className="capitalize">
+ {category}
+ </Badge>
+ ))
+ ) : (
+ <span className="text-foreground">None</span>
+ )}
+ </div>
+ </div>
+ </div>
+ </div>
+ </section>
+
+ <Separator />
+
+ <section className="space-y-4">
+ <div className="space-y-1">
+ <h2 className="text-base font-semibold">Settings</h2>
+ </div>
+ {hasCustomSettingsPage ? (
+ <div className="space-y-3">
+ {pluginSlots.map((slot) => (
+ <PluginSlotMount
+ key={`${slot.pluginKey}:${slot.id}`}
+ slot={slot}
+ context={{
+ companyId: selectedCompanyId,
+ companyPrefix: companyPrefix ?? null,
+ }}
+ missingBehavior="placeholder"
+ />
+ ))}
+ </div>
+ ) : hasConfigSchema ? (
+ <PluginConfigForm
+ pluginId={pluginId!}
+ schema={configSchema!}
+ initialValues={configData?.configJson}
+ isLoading={configLoading}
+ pluginStatus={plugin.status}
+ supportsConfigTest={(plugin as unknown as { supportsConfigTest?: boolean }).supportsConfigTest === true}
+ />
+ ) : (
+ <p className="text-sm text-muted-foreground">
+ This plugin does not require any settings.
+ </p>
+ )}
+ </section>
+ </div>
+ </TabsContent>
+
+ <TabsContent value="status" className="space-y-6">
+ <div className="grid gap-6 xl:grid-cols-[minmax(0,1.2fr)_320px]">
+ <div className="space-y-6">
+ <Card>
+ <CardHeader>
+ <CardTitle className="text-base flex items-center gap-1.5">
+ <Cpu className="h-4 w-4" />
+ Runtime Dashboard
+ </CardTitle>
+ <CardDescription>
+ Worker process, scheduled jobs, and webhook deliveries
+ </CardDescription>
+ </CardHeader>
+ <CardContent className="space-y-6">
+ {dashboardData ? (
+ <>
+ <div>
+ <h3 className="text-sm font-medium mb-3 flex items-center gap-1.5">
+ <Cpu className="h-3.5 w-3.5 text-muted-foreground" />
+ Worker Process
+ </h3>
+ {dashboardData.worker ? (
+ <div className="grid grid-cols-2 gap-3 text-sm">
+ <div className="flex justify-between">
+ <span className="text-muted-foreground">Status</span>
+ <Badge variant={dashboardData.worker.status === "running" ? "default" : "secondary"}>
+ {dashboardData.worker.status}
+ </Badge>
+ </div>
+ <div className="flex justify-between">
+ <span className="text-muted-foreground">PID</span>
+ <span className="font-mono text-xs">{dashboardData.worker.pid ?? "—"}</span>
+ </div>
+ <div className="flex justify-between">
+ <span className="text-muted-foreground">Uptime</span>
+ <span className="text-xs">{formatUptime(dashboardData.worker.uptime)}</span>
+ </div>
+ <div className="flex justify-between">
+ <span className="text-muted-foreground">Pending RPCs</span>
+ <span className="text-xs">{dashboardData.worker.pendingRequests}</span>
+ </div>
+ {dashboardData.worker.totalCrashes > 0 && (
+ <>
+ <div className="flex justify-between col-span-2">
+ <span className="text-muted-foreground flex items-center gap-1">
+ <AlertTriangle className="h-3 w-3 text-amber-500" />
+ Crashes
+ </span>
+ <span className="text-xs">
+ {dashboardData.worker.consecutiveCrashes} consecutive / {dashboardData.worker.totalCrashes} total
+ </span>
+ </div>
+ {dashboardData.worker.lastCrashAt && (
+ <div className="flex justify-between col-span-2">
+ <span className="text-muted-foreground">Last Crash</span>
+ <span className="text-xs">{formatTimestamp(dashboardData.worker.lastCrashAt)}</span>
+ </div>
+ )}
+ </>
+ )}
+ </div>
+ ) : (
+ <p className="text-sm text-muted-foreground italic">No worker process registered.</p>
+ )}
+ </div>
+
+ <Separator />
+
+ <div>
+ <h3 className="text-sm font-medium mb-3 flex items-center gap-1.5">
+ <CalendarClock className="h-3.5 w-3.5 text-muted-foreground" />
+ Recent Job Runs
+ </h3>
+ {dashboardData.recentJobRuns.length > 0 ? (
+ <div className="space-y-2">
+ {dashboardData.recentJobRuns.map((run) => (
+ <div
+ key={run.id}
+ className="flex items-center justify-between gap-2 rounded-md bg-muted/50 px-2 py-1.5 text-sm"
+ >
+ <div className="flex min-w-0 items-center gap-2">
+ <JobStatusDot status={run.status} />
+ <span className="truncate font-mono text-xs" title={run.jobKey ?? run.jobId}>
+ {run.jobKey ?? run.jobId.slice(0, 8)}
+ </span>
+ <Badge variant="outline" className="px-1 py-0 text-[10px]">
+ {run.trigger}
+ </Badge>
+ </div>
+ <div className="flex shrink-0 items-center gap-2 text-xs text-muted-foreground">
+ {run.durationMs != null ? <span>{formatDuration(run.durationMs)}</span> : null}
+ <span title={run.createdAt}>{formatRelativeTime(run.createdAt)}</span>
+ </div>
+ </div>
+ ))}
+ </div>
+ ) : (
+ <p className="text-sm text-muted-foreground italic">No job runs recorded yet.</p>
+ )}
+ </div>
+
+ <Separator />
+
+ <div>
+ <h3 className="text-sm font-medium mb-3 flex items-center gap-1.5">
+ <Webhook className="h-3.5 w-3.5 text-muted-foreground" />
+ Recent Webhook Deliveries
+ </h3>
+ {dashboardData.recentWebhookDeliveries.length > 0 ? (
+ <div className="space-y-2">
+ {dashboardData.recentWebhookDeliveries.map((delivery) => (
+ <div
+ key={delivery.id}
+ className="flex items-center justify-between gap-2 rounded-md bg-muted/50 px-2 py-1.5 text-sm"
+ >
+ <div className="flex min-w-0 items-center gap-2">
+ <DeliveryStatusDot status={delivery.status} />
+ <span className="truncate font-mono text-xs" title={delivery.webhookKey}>
+ {delivery.webhookKey}
+ </span>
+ </div>
+ <div className="flex shrink-0 items-center gap-2 text-xs text-muted-foreground">
+ {delivery.durationMs != null ? <span>{formatDuration(delivery.durationMs)}</span> : null}
+ <span title={delivery.createdAt}>{formatRelativeTime(delivery.createdAt)}</span>
+ </div>
+ </div>
+ ))}
+ </div>
+ ) : (
+ <p className="text-sm text-muted-foreground italic">No webhook deliveries recorded yet.</p>
+ )}
+ </div>
+
+ <div className="flex items-center gap-1.5 border-t border-border/50 pt-2 text-xs text-muted-foreground">
+ <Clock className="h-3 w-3" />
+ Last checked: {new Date(dashboardData.checkedAt).toLocaleTimeString()}
+ </div>
+ </>
+ ) : (
+ <p className="text-sm text-muted-foreground">
+ Runtime diagnostics are unavailable right now.
+ </p>
+ )}
+ </CardContent>
+ </Card>
+
+ {recentLogs && recentLogs.length > 0 ? (
+ <Card>
+ <CardHeader>
+ <CardTitle className="text-base flex items-center gap-1.5">
+ <ActivitySquare className="h-4 w-4" />
+ Recent Logs
+ </CardTitle>
+ <CardDescription>Last {recentLogs.length} log entries</CardDescription>
+ </CardHeader>
+ <CardContent>
+ <div className="max-h-64 space-y-1 overflow-y-auto font-mono text-xs">
+ {recentLogs.map((entry) => (
+ <div
+ key={entry.id}
+ className={`flex gap-2 py-0.5 ${
+ entry.level === "error"
+ ? "text-destructive"
+ : entry.level === "warn"
+ ? "text-yellow-600 dark:text-yellow-400"
+ : entry.level === "debug"
+ ? "text-muted-foreground/60"
+ : "text-muted-foreground"
+ }`}
+ >
+ <span className="shrink-0 text-muted-foreground/50">{new Date(entry.createdAt).toLocaleTimeString()}</span>
+ <Badge variant="outline" className="h-4 shrink-0 px-1 text-[10px]">{entry.level}</Badge>
+ <span className="truncate" title={entry.message}>{entry.message}</span>
+ </div>
+ ))}
+ </div>
+ </CardContent>
+ </Card>
+ ) : null}
+ </div>
+
+ <div className="space-y-6">
+ <Card>
+ <CardHeader>
+ <CardTitle className="text-base flex items-center gap-1.5">
+ <ActivitySquare className="h-4 w-4" />
+ Health Status
+ </CardTitle>
+ </CardHeader>
+ <CardContent>
+ {healthLoading ? (
+ <p className="text-sm text-muted-foreground">Checking health...</p>
+ ) : healthData ? (
+ <div className="space-y-4 text-sm">
+ <div className="flex items-center justify-between">
+ <span className="text-muted-foreground">Overall</span>
+ <Badge variant={healthData.healthy ? "default" : "destructive"}>
+ {healthData.status}
+ </Badge>
+ </div>
+
+ {healthData.checks.length > 0 ? (
+ <div className="space-y-2 border-t border-border/50 pt-2">
+ {healthData.checks.map((check, i) => (
+ <div key={i} className="flex items-start justify-between gap-2">
+ <span className="truncate text-muted-foreground" title={check.name}>
+ {check.name}
+ </span>
+ {check.passed ? (
+ <CheckCircle className="h-4 w-4 shrink-0 text-green-500" />
+ ) : (
+ <XCircle className="h-4 w-4 shrink-0 text-destructive" />
+ )}
+ </div>
+ ))}
+ </div>
+ ) : null}
+
+ {healthData.lastError ? (
+ <div className="break-words rounded border border-destructive/20 bg-destructive/10 p-2 text-xs text-destructive">
+ {healthData.lastError}
+ </div>
+ ) : null}
+ </div>
+ ) : (
+ <div className="space-y-3 text-sm text-muted-foreground">
+ <div className="flex items-center justify-between">
+ <span>Lifecycle</span>
+ <Badge variant={statusVariant}>{displayStatus}</Badge>
+ </div>
+ <p>Health checks run once the plugin is ready.</p>
+ {plugin.lastError ? (
+ <div className="break-words rounded border border-destructive/20 bg-destructive/10 p-2 text-xs text-destructive">
+ {plugin.lastError}
+ </div>
+ ) : null}
+ </div>
+ )}
+ </CardContent>
+ </Card>
+
+ <Card>
+ <CardHeader>
+ <CardTitle className="text-base">Details</CardTitle>
+ </CardHeader>
+ <CardContent className="space-y-3 text-sm text-muted-foreground">
+ <div className="flex justify-between gap-3">
+ <span>Plugin ID</span>
+ <span className="font-mono text-xs text-right">{plugin.id}</span>
+ </div>
+ <div className="flex justify-between gap-3">
+ <span>Plugin Key</span>
+ <span className="font-mono text-xs text-right">{plugin.pluginKey}</span>
+ </div>
+ <div className="flex justify-between gap-3">
+ <span>NPM Package</span>
+ <span className="max-w-[170px] truncate text-right text-xs" title={plugin.packageName}>
+ {plugin.packageName}
+ </span>
+ </div>
+ <div className="flex justify-between gap-3">
+ <span>Version</span>
+ <span className="text-right text-foreground">v{plugin.manifestJson.version ?? plugin.version}</span>
+ </div>
+ </CardContent>
+ </Card>
+
+ <Card>
+ <CardHeader>
+ <CardTitle className="text-base flex items-center gap-1.5">
+ <ShieldAlert className="h-4 w-4" />
+ Permissions
+ </CardTitle>
+ </CardHeader>
+ <CardContent>
+ {pluginCapabilities.length > 0 ? (
+ <ul className="space-y-2 text-sm text-muted-foreground">
+ {pluginCapabilities.map((cap) => (
+ <li key={cap} className="rounded-md bg-muted/40 px-2.5 py-2 font-mono text-xs text-foreground/85">
+ {cap}
+ </li>
+ ))}
+ </ul>
+ ) : (
+ <p className="text-sm text-muted-foreground italic">No special permissions requested.</p>
+ )}
+ </CardContent>
+ </Card>
+ </div>
+ </div>
+ </TabsContent>
+ </Tabs>
+ </div>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// PluginConfigForm — auto-generated form for instanceConfigSchema
+// ---------------------------------------------------------------------------
+
+interface PluginConfigFormProps {
+ pluginId: string;
+ schema: JsonSchemaNode;
+ initialValues?: Record<string, unknown>;
+ isLoading?: boolean;
+ /** Current plugin lifecycle status — "Test Configuration" only available when `ready`. */
+ pluginStatus?: string;
+ /** Whether the plugin worker implements `validateConfig`. */
+ supportsConfigTest?: boolean;
+}
+
+/**
+ * Inner component that manages form state, validation, save, and "Test Configuration"
+ * for the auto-generated plugin config form.
+ *
+ * Separated from PluginSettings to isolate re-render scope — only the form
+ * re-renders on field changes, not the entire page.
+ */
+function PluginConfigForm({ pluginId, schema, initialValues, isLoading, pluginStatus, supportsConfigTest }: PluginConfigFormProps) {
+ const queryClient = useQueryClient();
+
+ // Form values: start with saved values, fall back to schema defaults
+ const [values, setValues] = useState<Record<string, unknown>>(() => ({
+ ...getDefaultValues(schema),
+ ...(initialValues ?? {}),
+ }));
+
+ // Sync when saved config loads asynchronously — only on first load so we
+ // don't overwrite in-progress user edits if the query refetches (e.g. on
+ // window focus).
+ const hasHydratedRef = useRef(false);
+ useEffect(() => {
+ if (initialValues && !hasHydratedRef.current) {
+ hasHydratedRef.current = true;
+ setValues({
+ ...getDefaultValues(schema),
+ ...initialValues,
+ });
+ }
+ }, [initialValues, schema]);
+
+ const [errors, setErrors] = useState<Record<string, string>>({});
+ const [saveMessage, setSaveMessage] = useState<{ type: "success" | "error"; text: string } | null>(null);
+ const [testResult, setTestResult] = useState<{ type: "success" | "error"; text: string } | null>(null);
+
+ // Dirty tracking: compare against initial values
+ const isDirty = JSON.stringify(values) !== JSON.stringify({
+ ...getDefaultValues(schema),
+ ...(initialValues ?? {}),
+ });
+
+ // Save mutation
+ const saveMutation = useMutation({
+ mutationFn: (configJson: Record<string, unknown>) =>
+ pluginsApi.saveConfig(pluginId, configJson),
+ onSuccess: () => {
+ setSaveMessage({ type: "success", text: "Configuration saved." });
+ setTestResult(null);
+ queryClient.invalidateQueries({ queryKey: queryKeys.plugins.config(pluginId) });
+ // Clear success message after 3s
+ setTimeout(() => setSaveMessage(null), 3000);
+ },
+ onError: (err: Error) => {
+ setSaveMessage({ type: "error", text: err.message || "Failed to save configuration." });
+ },
+ });
+
+ // Test configuration mutation
+ const testMutation = useMutation({
+ mutationFn: (configJson: Record<string, unknown>) =>
+ pluginsApi.testConfig(pluginId, configJson),
+ onSuccess: (result) => {
+ if (result.valid) {
+ setTestResult({ type: "success", text: "Configuration test passed." });
+ } else {
+ setTestResult({ type: "error", text: result.message || "Configuration test failed." });
+ }
+ },
+ onError: (err: Error) => {
+ setTestResult({ type: "error", text: err.message || "Configuration test failed." });
+ },
+ });
+
+ const handleChange = useCallback((newValues: Record<string, unknown>) => {
+ setValues(newValues);
+ // Clear field-level errors as the user types
+ setErrors({});
+ setSaveMessage(null);
+ }, []);
+
+ const handleSave = useCallback(() => {
+ // Validate before saving
+ const validationErrors = validateJsonSchemaForm(schema, values);
+ if (Object.keys(validationErrors).length > 0) {
+ setErrors(validationErrors);
+ return;
+ }
+ setErrors({});
+ saveMutation.mutate(values);
+ }, [schema, values, saveMutation]);
+
+ const handleTestConnection = useCallback(() => {
+ // Validate before testing
+ const validationErrors = validateJsonSchemaForm(schema, values);
+ if (Object.keys(validationErrors).length > 0) {
+ setErrors(validationErrors);
+ return;
+ }
+ setErrors({});
+ setTestResult(null);
+ testMutation.mutate(values);
+ }, [schema, values, testMutation]);
+
+ if (isLoading) {
+ return (
+ <div className="flex items-center gap-2 text-sm text-muted-foreground py-4">
+ <Loader2 className="h-4 w-4 animate-spin" />
+ Loading configuration...
+ </div>
+ );
+ }
+
+ return (
+ <div className="space-y-4">
+ <JsonSchemaForm
+ schema={schema}
+ values={values}
+ onChange={handleChange}
+ errors={errors}
+ disabled={saveMutation.isPending}
+ />
+
+ {/* Status messages */}
+ {saveMessage && (
+ <div
+ className={`text-sm p-2 rounded border ${
+ saveMessage.type === "success"
+ ? "text-green-700 bg-green-50 border-green-200 dark:text-green-400 dark:bg-green-950/30 dark:border-green-900"
+ : "text-destructive bg-destructive/10 border-destructive/20"
+ }`}
+ >
+ {saveMessage.text}
+ </div>
+ )}
+
+ {testResult && (
+ <div
+ className={`text-sm p-2 rounded border ${
+ testResult.type === "success"
+ ? "text-green-700 bg-green-50 border-green-200 dark:text-green-400 dark:bg-green-950/30 dark:border-green-900"
+ : "text-destructive bg-destructive/10 border-destructive/20"
+ }`}
+ >
+ {testResult.text}
+ </div>
+ )}
+
+ {/* Action buttons */}
+ <div className="flex items-center gap-2 pt-2">
+ <Button
+ onClick={handleSave}
+ disabled={saveMutation.isPending || !isDirty}
+ size="sm"
+ >
+ {saveMutation.isPending ? (
+ <>
+ <Loader2 className="h-3.5 w-3.5 animate-spin" />
+ Saving...
+ </>
+ ) : (
+ "Save Configuration"
+ )}
+ </Button>
+ {pluginStatus === "ready" && supportsConfigTest && (
+ <Button
+ variant="outline"
+ onClick={handleTestConnection}
+ disabled={testMutation.isPending}
+ size="sm"
+ >
+ {testMutation.isPending ? (
+ <>
+ <Loader2 className="h-3.5 w-3.5 animate-spin" />
+ Testing...
+ </>
+ ) : (
+ "Test Configuration"
+ )}
+ </Button>
+ )}
+ </div>
+ </div>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Dashboard helper components and formatting utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Format an uptime value (in milliseconds) to a human-readable string.
+ */
+function formatUptime(uptimeMs: number | null): string {
+ if (uptimeMs == null) return "—";
+ const totalSeconds = Math.floor(uptimeMs / 1000);
+ if (totalSeconds < 60) return `${totalSeconds}s`;
+ const minutes = Math.floor(totalSeconds / 60);
+ if (minutes < 60) return `${minutes}m ${totalSeconds % 60}s`;
+ const hours = Math.floor(minutes / 60);
+ if (hours < 24) return `${hours}h ${minutes % 60}m`;
+ const days = Math.floor(hours / 24);
+ return `${days}d ${hours % 24}h`;
+}
+
+/**
+ * Format a duration in milliseconds to a compact display string.
+ */
+function formatDuration(ms: number): string {
+ if (ms < 1000) return `${ms}ms`;
+ if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+ return `${(ms / 60000).toFixed(1)}m`;
+}
+
+/**
+ * Format an ISO timestamp to a relative time string (e.g., "2m ago").
+ */
+function formatRelativeTime(isoString: string): string {
+ const now = Date.now();
+ const then = new Date(isoString).getTime();
+ const diffMs = now - then;
+
+ if (diffMs < 0) return "just now";
+ const seconds = Math.floor(diffMs / 1000);
+ if (seconds < 60) return `${seconds}s ago`;
+ const minutes = Math.floor(seconds / 60);
+ if (minutes < 60) return `${minutes}m ago`;
+ const hours = Math.floor(minutes / 60);
+ if (hours < 24) return `${hours}h ago`;
+ const days = Math.floor(hours / 24);
+ return `${days}d ago`;
+}
+
+/**
+ * Format a unix timestamp (ms since epoch) to a locale string.
+ */
+function formatTimestamp(epochMs: number): string {
+ return new Date(epochMs).toLocaleString();
+}
+
+/**
+ * Status indicator dot for job run statuses.
+ */
+function JobStatusDot({ status }: { status: string }) {
+ const colorClass =
+ status === "success" || status === "succeeded"
+ ? "bg-green-500"
+ : status === "failed"
+ ? "bg-red-500"
+ : status === "running"
+ ? "bg-blue-500 animate-pulse"
+ : status === "cancelled"
+ ? "bg-gray-400"
+ : "bg-amber-500"; // queued, pending
+ return (
+ <span
+ className={`inline-block h-2 w-2 rounded-full shrink-0 ${colorClass}`}
+ title={status}
+ />
+ );
+}
+
+/**
+ * Status indicator dot for webhook delivery statuses.
+ */
+function DeliveryStatusDot({ status }: { status: string }) {
+ const colorClass =
+ status === "processed" || status === "success"
+ ? "bg-green-500"
+ : status === "failed"
+ ? "bg-red-500"
+ : status === "received"
+ ? "bg-blue-500"
+ : "bg-amber-500"; // pending
+ return (
+ <span
+ className={`inline-block h-2 w-2 rounded-full shrink-0 ${colorClass}`}
+ title={status}
+ />
+ );
+}
diff --git a/ui/src/pages/ProjectDetail.tsx b/ui/src/pages/ProjectDetail.tsx
index 84311852d1..8b8c027db2 100644
--- a/ui/src/pages/ProjectDetail.tsx
+++ b/ui/src/pages/ProjectDetail.tsx
@@ -19,10 +19,17 @@ import { PageSkeleton } from "../components/PageSkeleton";
import { PageTabBar } from "../components/PageTabBar";
import { projectRouteRef, cn } from "../lib/utils";
import { Tabs } from "@/components/ui/tabs";
+import { PluginSlotMount, usePluginSlots } from "@/plugins/slots";
/* ── Top-level tab types ── */
-type ProjectTab = "overview" | "list" | "configuration";
+type ProjectBaseTab = "overview" | "list" | "configuration";
+type ProjectPluginTab = `plugin:${string}`;
+type ProjectTab = ProjectBaseTab | ProjectPluginTab;
+
+function isProjectPluginTab(value: string | null): value is ProjectPluginTab {
+ return typeof value === "string" && value.startsWith("plugin:");
+}
function resolveProjectTab(pathname: string, projectId: string): ProjectTab | null {
const segments = pathname.split("/").filter(Boolean);
@@ -213,8 +220,12 @@ export function ProjectDetail() {
}, [companies, companyPrefix]);
const lookupCompanyId = routeCompanyId ?? selectedCompanyId ?? undefined;
const canFetchProject = routeProjectRef.length > 0 && (isUuidLike(routeProjectRef) || Boolean(lookupCompanyId));
-
- const activeTab = routeProjectRef ? resolveProjectTab(location.pathname, routeProjectRef) : null;
+ const activeRouteTab = routeProjectRef ? resolveProjectTab(location.pathname, routeProjectRef) : null;
+ const pluginTabFromSearch = useMemo(() => {
+ const tab = new URLSearchParams(location.search).get("tab");
+ return isProjectPluginTab(tab) ? tab : null;
+ }, [location.search]);
+ const activeTab = activeRouteTab ?? pluginTabFromSearch;
const { data: project, isLoading, error } = useQuery({
queryKey: [...queryKeys.projects.detail(routeProjectRef), lookupCompanyId ?? null],
@@ -224,6 +235,24 @@ export function ProjectDetail() {
const canonicalProjectRef = project ? projectRouteRef(project) : routeProjectRef;
const projectLookupRef = project?.id ?? routeProjectRef;
const resolvedCompanyId = project?.companyId ?? selectedCompanyId;
+ const {
+ slots: pluginDetailSlots,
+ isLoading: pluginDetailSlotsLoading,
+ } = usePluginSlots({
+ slotTypes: ["detailTab"],
+ entityType: "project",
+ companyId: resolvedCompanyId,
+ enabled: !!resolvedCompanyId,
+ });
+ const pluginTabItems = useMemo(
+ () => pluginDetailSlots.map((slot) => ({
+ value: `plugin:${slot.pluginKey}:${slot.id}` as ProjectPluginTab,
+ label: slot.displayName,
+ slot,
+ })),
+ [pluginDetailSlots],
+ );
+ const activePluginTab = pluginTabItems.find((item) => item.value === activeTab) ?? null;
useEffect(() => {
if (!project?.companyId || project.companyId === selectedCompanyId) return;
@@ -261,6 +290,10 @@ export function ProjectDetail() {
useEffect(() => {
if (!project) return;
if (routeProjectRef === canonicalProjectRef) return;
+ if (isProjectPluginTab(activeTab)) {
+ navigate(`/projects/${canonicalProjectRef}?tab=${encodeURIComponent(activeTab)}`, { replace: true });
+ return;
+ }
if (activeTab === "overview") {
navigate(`/projects/${canonicalProjectRef}/overview`, { replace: true });
return;
@@ -328,6 +361,10 @@ export function ProjectDetail() {
}
}, [invalidateProject, lookupCompanyId, projectLookupRef, resolvedCompanyId, scheduleFieldReset, setFieldState]);
+ if (pluginTabFromSearch && !pluginDetailSlotsLoading && !activePluginTab) {
+ return <Navigate to={`/projects/${canonicalProjectRef}/issues`} replace />;
+ }
+
// Redirect bare /projects/:id to /projects/:id/issues
if (routeProjectRef && activeTab === null) {
return <Navigate to={`/projects/${canonicalProjectRef}/issues`} replace />;
@@ -338,6 +375,10 @@ export function ProjectDetail() {
if (!project) return null;
const handleTabChange = (tab: ProjectTab) => {
+ if (isProjectPluginTab(tab)) {
+ navigate(`/projects/${canonicalProjectRef}?tab=${encodeURIComponent(tab)}`);
+ return;
+ }
if (tab === "overview") {
navigate(`/projects/${canonicalProjectRef}/overview`);
} else if (tab === "configuration") {
@@ -370,6 +411,10 @@ export function ProjectDetail() {
{ value: "overview", label: "Overview" },
{ value: "list", label: "List" },
{ value: "configuration", label: "Configuration" },
+ ...pluginTabItems.map((item) => ({
+ value: item.value,
+ label: item.label,
+ })),
]}
align="start"
value={activeTab ?? "list"}
@@ -402,6 +447,21 @@ export function ProjectDetail() {
/>
</div>
)}
+
+ {activePluginTab && (
+ <PluginSlotMount
+ slot={activePluginTab.slot}
+ context={{
+ companyId: resolvedCompanyId,
+ companyPrefix: companyPrefix ?? null,
+ projectId: project.id,
+ projectRef: canonicalProjectRef,
+ entityId: project.id,
+ entityType: "project",
+ }}
+ missingBehavior="placeholder"
+ />
+ )}
</div>
);
}
diff --git a/ui/src/plugins/bridge-init.ts b/ui/src/plugins/bridge-init.ts
new file mode 100644
index 0000000000..6b0eb2bedd
--- /dev/null
+++ b/ui/src/plugins/bridge-init.ts
@@ -0,0 +1,116 @@
+/**
+ * Plugin bridge initialization.
+ *
+ * Registers the host's React instances and bridge hook implementations
+ * on a global object so that the plugin module loader can inject them
+ * into plugin UI bundles at load time.
+ *
+ * Call `initPluginBridge()` once during app startup (in `main.tsx`), before
+ * any plugin UI modules are loaded.
+ *
+ * @see PLUGIN_SPEC.md §19.0.1 — Plugin UI SDK
+ * @see PLUGIN_SPEC.md §19.0.2 — Bundle Isolation
+ */
+
+import type { ReactNode } from "react";
+import {
+ usePluginData,
+ usePluginAction,
+ useHostContext,
+} from "./bridge.js";
+
+// ---------------------------------------------------------------------------
+// Global bridge registry
+// ---------------------------------------------------------------------------
+
+/**
+ * The global bridge registry shape.
+ *
+ * This is placed on `globalThis.__paperclipPluginBridge__` and consumed by
+ * the plugin module loader to provide implementations for external imports.
+ */
+export interface PluginBridgeRegistry {
+ react: unknown;
+ reactDom: unknown;
+ sdkUi: Record<string, unknown>;
+}
+
+declare global {
+ // eslint-disable-next-line no-var
+ var __paperclipPluginBridge__: PluginBridgeRegistry | undefined;
+}
+
+/**
+ * Initialize the plugin bridge global registry.
+ *
+ * Registers the host's React, ReactDOM, and SDK UI bridge implementations
+ * on `globalThis.__paperclipPluginBridge__` so the plugin module loader
+ * can provide them to plugin bundles.
+ *
+ * @param react - The host's React module
+ * @param reactDom - The host's ReactDOM module
+ */
+export function initPluginBridge(
+ react: typeof import("react"),
+ reactDom: typeof import("react-dom"),
+): void {
+ globalThis.__paperclipPluginBridge__ = {
+ react,
+ reactDom,
+ sdkUi: {
+ // Bridge hooks
+ usePluginData,
+ usePluginAction,
+ useHostContext,
+
+ // Placeholder shared UI components — plugins that use these will get
+ // functional stubs. Full implementations matching the host's design
+ // system can be added later.
+ MetricCard: createStubComponent("MetricCard"),
+ StatusBadge: createStubComponent("StatusBadge"),
+ DataTable: createStubComponent("DataTable"),
+ TimeseriesChart: createStubComponent("TimeseriesChart"),
+ MarkdownBlock: createStubComponent("MarkdownBlock"),
+ KeyValueList: createStubComponent("KeyValueList"),
+ ActionBar: createStubComponent("ActionBar"),
+ LogView: createStubComponent("LogView"),
+ JsonTree: createStubComponent("JsonTree"),
+ Spinner: createStubComponent("Spinner"),
+ ErrorBoundary: createPassthroughComponent("ErrorBoundary"),
+ },
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Stub component helpers
+// ---------------------------------------------------------------------------
+
+function createStubComponent(name: string): unknown {
+ const fn = (props: Record<string, unknown>) => {
+ // Import React from the registry to avoid import issues
+ const React = globalThis.__paperclipPluginBridge__?.react as typeof import("react") | undefined;
+ if (!React) return null;
+ return React.createElement("div", {
+ "data-plugin-component": name,
+ style: {
+ padding: "8px",
+ border: "1px dashed #666",
+ borderRadius: "4px",
+ fontSize: "12px",
+ color: "#888",
+ },
+ }, `[${name}]`);
+ };
+ Object.defineProperty(fn, "name", { value: name });
+ return fn;
+}
+
+function createPassthroughComponent(name: string): unknown {
+ const fn = (props: { children?: ReactNode }) => {
+ const ReactLib = globalThis.__paperclipPluginBridge__?.react as typeof import("react") | undefined;
+ if (!ReactLib) return null;
+ return ReactLib.createElement(ReactLib.Fragment, null, props.children);
+ };
+ Object.defineProperty(fn, "name", { value: name });
+ return fn;
+}
diff --git a/ui/src/plugins/bridge.ts b/ui/src/plugins/bridge.ts
new file mode 100644
index 0000000000..f5f1b30e6f
--- /dev/null
+++ b/ui/src/plugins/bridge.ts
@@ -0,0 +1,361 @@
+/**
+ * Plugin UI bridge runtime — concrete implementations of the bridge hooks.
+ *
+ * Plugin UI bundles import `usePluginData`, `usePluginAction`, and
+ * `useHostContext` from `@paperclipai/plugin-sdk/ui`. Those are type-only
+ * declarations in the SDK package. The host provides the real implementations
+ * by injecting this bridge runtime into the plugin's module scope.
+ *
+ * The bridge runtime communicates with plugin workers via HTTP REST endpoints:
+ * - `POST /api/plugins/:pluginId/data/:key` — proxies `getData` RPC
+ * - `POST /api/plugins/:pluginId/actions/:key` — proxies `performAction` RPC
+ *
+ * ## How it works
+ *
+ * 1. Before loading a plugin's UI module, the host creates a scoped bridge via
+ * `createPluginBridge(pluginId)`.
+ * 2. The bridge's hook implementations are registered in a global bridge
+ * registry keyed by `pluginId`.
+ * 3. The "ambient" hooks (`usePluginData`, `usePluginAction`, `useHostContext`)
+ * look up the current plugin context from a React context provider and
+ * delegate to the appropriate bridge instance.
+ *
+ * @see PLUGIN_SPEC.md §13.8 — `getData`
+ * @see PLUGIN_SPEC.md §13.9 — `performAction`
+ * @see PLUGIN_SPEC.md §19.7 — Error Propagation Through The Bridge
+ */
+
+import { createContext, useCallback, useContext, useRef, useState, useEffect } from "react";
+import type {
+ PluginBridgeErrorCode,
+ PluginLauncherBounds,
+ PluginLauncherRenderContextSnapshot,
+ PluginLauncherRenderEnvironment,
+} from "@paperclipai/shared";
+import { pluginsApi } from "@/api/plugins";
+import { ApiError } from "@/api/client";
+
+// ---------------------------------------------------------------------------
+// Bridge error type (mirrors the SDK's PluginBridgeError)
+// ---------------------------------------------------------------------------
+
+/**
+ * Structured error from the bridge, matching the SDK's `PluginBridgeError`.
+ */
+export interface PluginBridgeError {
+ code: PluginBridgeErrorCode;
+ message: string;
+ details?: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Bridge data result type (mirrors the SDK's PluginDataResult)
+// ---------------------------------------------------------------------------
+
+export interface PluginDataResult<T = unknown> {
+ data: T | null;
+ loading: boolean;
+ error: PluginBridgeError | null;
+ refresh(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Host context type (mirrors the SDK's PluginHostContext)
+// ---------------------------------------------------------------------------
+
+export interface PluginHostContext {
+ companyId: string | null;
+ companyPrefix: string | null;
+ projectId: string | null;
+ entityId: string | null;
+ entityType: string | null;
+ parentEntityId?: string | null;
+ userId: string | null;
+ renderEnvironment?: PluginRenderEnvironmentContext | null;
+}
+
+export interface PluginModalBoundsRequest {
+ bounds: PluginLauncherBounds;
+ width?: number;
+ height?: number;
+ minWidth?: number;
+ minHeight?: number;
+ maxWidth?: number;
+ maxHeight?: number;
+}
+
+export interface PluginRenderCloseEvent {
+ reason:
+ | "escapeKey"
+ | "backdrop"
+ | "hostNavigation"
+ | "programmatic"
+ | "submit"
+ | "unknown";
+ nativeEvent?: unknown;
+}
+
+export type PluginRenderCloseHandler = (
+ event: PluginRenderCloseEvent,
+) => void | Promise<void>;
+
+export interface PluginRenderCloseLifecycle {
+ onBeforeClose?(handler: PluginRenderCloseHandler): () => void;
+ onClose?(handler: PluginRenderCloseHandler): () => void;
+}
+
+export interface PluginRenderEnvironmentContext {
+ environment: PluginLauncherRenderEnvironment | null;
+ launcherId: string | null;
+ bounds: PluginLauncherBounds | null;
+ requestModalBounds?(request: PluginModalBoundsRequest): Promise<void>;
+ closeLifecycle?: PluginRenderCloseLifecycle | null;
+}
+
+// ---------------------------------------------------------------------------
+// Bridge context — React context for plugin identity and host scope
+// ---------------------------------------------------------------------------
+
+export type PluginBridgeContextValue = {
+ pluginId: string;
+ hostContext: PluginHostContext;
+};
+
+/**
+ * React context that carries the active plugin identity and host scope.
+ *
+ * The slot/launcher mount wraps plugin components in a Provider so that
+ * bridge hooks (`usePluginData`, `usePluginAction`, `useHostContext`) can
+ * resolve the current plugin without ambient mutable globals.
+ *
+ * Because plugin bundles share the host's React instance (via the bridge
+ * registry on `globalThis.__paperclipPluginBridge__`), context propagation
+ * works correctly across the host/plugin boundary.
+ */
+export const PluginBridgeContext =
+ createContext<PluginBridgeContextValue | null>(null);
+
+function usePluginBridgeContext(): PluginBridgeContextValue {
+ const ctx = useContext(PluginBridgeContext);
+ if (!ctx) {
+ throw new Error(
+ "Plugin bridge hook called outside of a <PluginBridgeContext.Provider>. " +
+ "Ensure the plugin component is rendered within a PluginBridgeScope.",
+ );
+ }
+ return ctx;
+}
+
+// ---------------------------------------------------------------------------
+// Error extraction helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Attempt to extract a structured PluginBridgeError from an API error.
+ *
+ * The bridge proxy endpoints return error bodies shaped as
+ * `{ code: PluginBridgeErrorCode, message: string, details?: unknown }`.
+ * This helper extracts that structure from the ApiError thrown by the client.
+ */
+function extractBridgeError(err: unknown): PluginBridgeError {
+ if (err instanceof ApiError && err.body && typeof err.body === "object") {
+ const body = err.body as Record<string, unknown>;
+ if (typeof body.code === "string" && typeof body.message === "string") {
+ return {
+ code: body.code as PluginBridgeErrorCode,
+ message: body.message,
+ details: body.details,
+ };
+ }
+ // Fallback: the server returned a plain { error: string } body
+ if (typeof body.error === "string") {
+ return {
+ code: "UNKNOWN",
+ message: body.error,
+ };
+ }
+ }
+
+ return {
+ code: "UNKNOWN",
+ message: err instanceof Error ? err.message : String(err),
+ };
+}
+
+// ---------------------------------------------------------------------------
+// usePluginData — concrete implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Stable serialization of params for use as a dependency key.
+ * Returns a string that changes only when the params object content changes.
+ */
+function serializeParams(params?: Record<string, unknown>): string {
+ if (!params) return "";
+ try {
+ return JSON.stringify(params, Object.keys(params).sort());
+ } catch {
+ return "";
+ }
+}
+
+function serializeRenderEnvironment(
+ renderEnvironment?: PluginRenderEnvironmentContext | null,
+): PluginLauncherRenderContextSnapshot | null {
+ if (!renderEnvironment) return null;
+ return {
+ environment: renderEnvironment.environment,
+ launcherId: renderEnvironment.launcherId,
+ bounds: renderEnvironment.bounds,
+ };
+}
+
+function serializeRenderEnvironmentSnapshot(
+ snapshot: PluginLauncherRenderContextSnapshot | null,
+): string {
+ return snapshot ? JSON.stringify(snapshot) : "";
+}
+
+/**
+ * Concrete implementation of `usePluginData<T>(key, params)`.
+ *
+ * Makes an HTTP POST to `/api/plugins/:pluginId/data/:key` and returns
+ * a reactive `PluginDataResult<T>` matching the SDK type contract.
+ *
+ * Re-fetches automatically when `key` or `params` change. Provides a
+ * `refresh()` function for manual re-fetch.
+ */
+export function usePluginData<T = unknown>(
+ key: string,
+ params?: Record<string, unknown>,
+): PluginDataResult<T> {
+ const { pluginId, hostContext } = usePluginBridgeContext();
+ const companyId = hostContext.companyId;
+ const renderEnvironmentSnapshot = serializeRenderEnvironment(hostContext.renderEnvironment);
+ const renderEnvironmentKey = serializeRenderEnvironmentSnapshot(renderEnvironmentSnapshot);
+
+ const [data, setData] = useState<T | null>(null);
+ const [loading, setLoading] = useState(true);
+ const [error, setError] = useState<PluginBridgeError | null>(null);
+ const [refreshCounter, setRefreshCounter] = useState(0);
+
+ // Stable serialization for params change detection
+ const paramsKey = serializeParams(params);
+
+ useEffect(() => {
+ let cancelled = false;
+ let retryTimer: ReturnType<typeof setTimeout> | null = null;
+ let retryCount = 0;
+ const maxRetryCount = 2;
+ const retryableCodes: PluginBridgeErrorCode[] = ["WORKER_UNAVAILABLE", "TIMEOUT"];
+ setLoading(true);
+ const request = () => {
+ pluginsApi
+ .bridgeGetData(
+ pluginId,
+ key,
+ params,
+ companyId,
+ renderEnvironmentSnapshot,
+ )
+ .then((response) => {
+ if (!cancelled) {
+ setData(response.data as T);
+ setError(null);
+ setLoading(false);
+ }
+ })
+ .catch((err: unknown) => {
+ if (cancelled) return;
+
+ const bridgeError = extractBridgeError(err);
+ if (retryableCodes.includes(bridgeError.code) && retryCount < maxRetryCount) {
+ retryCount += 1;
+ retryTimer = setTimeout(() => {
+ retryTimer = null;
+ if (!cancelled) request();
+ }, 150 * retryCount);
+ return;
+ }
+
+ setError(bridgeError);
+ setData(null);
+ setLoading(false);
+ });
+ };
+
+ request();
+
+ return () => {
+ cancelled = true;
+ if (retryTimer) clearTimeout(retryTimer);
+ };
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [pluginId, key, paramsKey, refreshCounter, companyId, renderEnvironmentKey]);
+
+ const refresh = useCallback(() => {
+ setRefreshCounter((c) => c + 1);
+ }, []);
+
+ return { data, loading, error, refresh };
+}
+
+// ---------------------------------------------------------------------------
+// usePluginAction — concrete implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Action function type matching the SDK's `PluginActionFn`.
+ */
+export type PluginActionFn = (params?: Record<string, unknown>) => Promise<unknown>;
+
+/**
+ * Concrete implementation of `usePluginAction(key)`.
+ *
+ * Returns a stable async function that, when called, sends a POST to
+ * `/api/plugins/:pluginId/actions/:key` and returns the worker result.
+ *
+ * On failure, the function throws a `PluginBridgeError`.
+ */
+export function usePluginAction(key: string): PluginActionFn {
+ const bridgeContext = usePluginBridgeContext();
+ const contextRef = useRef(bridgeContext);
+ contextRef.current = bridgeContext;
+
+ return useCallback(
+ async (params?: Record<string, unknown>): Promise<unknown> => {
+ const { pluginId, hostContext } = contextRef.current;
+ const companyId = hostContext.companyId;
+ const renderEnvironment = serializeRenderEnvironment(hostContext.renderEnvironment);
+
+ try {
+ const response = await pluginsApi.bridgePerformAction(
+ pluginId,
+ key,
+ params,
+ companyId,
+ renderEnvironment,
+ );
+ return response.data;
+ } catch (err) {
+ throw extractBridgeError(err);
+ }
+ },
+ [key],
+ );
+}
+
+// ---------------------------------------------------------------------------
+// useHostContext — concrete implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Concrete implementation of `useHostContext()`.
+ *
+ * Returns the current host context (company, project, entity, user)
+ * from the enclosing `PluginBridgeContext.Provider`.
+ */
+export function useHostContext(): PluginHostContext {
+ const { hostContext } = usePluginBridgeContext();
+ return hostContext;
+}
diff --git a/ui/src/plugins/launchers.tsx b/ui/src/plugins/launchers.tsx
new file mode 100644
index 0000000000..b03b527a78
--- /dev/null
+++ b/ui/src/plugins/launchers.tsx
@@ -0,0 +1,829 @@
+import {
+ Component,
+ createContext,
+ createElement,
+ useCallback,
+ useContext,
+ useEffect,
+ useId,
+ useMemo,
+ useRef,
+ useState,
+ type CSSProperties,
+ type ErrorInfo,
+ type KeyboardEvent as ReactKeyboardEvent,
+ type MouseEvent as ReactMouseEvent,
+ type ReactNode,
+} from "react";
+import { useQuery } from "@tanstack/react-query";
+import { PLUGIN_LAUNCHER_BOUNDS } from "@paperclipai/shared";
+import type {
+ PluginLauncherBounds,
+ PluginLauncherDeclaration,
+ PluginLauncherPlacementZone,
+ PluginUiSlotEntityType,
+} from "@paperclipai/shared";
+import { pluginsApi, type PluginUiContribution } from "@/api/plugins";
+import { authApi } from "@/api/auth";
+import { Button } from "@/components/ui/button";
+import { useNavigate, useLocation } from "@/lib/router";
+import { queryKeys } from "@/lib/queryKeys";
+import { cn } from "@/lib/utils";
+import {
+ PluginBridgeContext,
+ type PluginHostContext,
+ type PluginModalBoundsRequest,
+ type PluginRenderCloseEvent,
+ type PluginRenderCloseHandler,
+ type PluginRenderEnvironmentContext,
+} from "./bridge";
+import {
+ ensurePluginContributionLoaded,
+ resolveRegisteredPluginComponent,
+ type RegisteredPluginComponent,
+} from "./slots";
+
+export type PluginLauncherContext = {
+ companyId?: string | null;
+ companyPrefix?: string | null;
+ projectId?: string | null;
+ projectRef?: string | null;
+ entityId?: string | null;
+ entityType?: PluginUiSlotEntityType | null;
+};
+
+export type ResolvedPluginLauncher = PluginLauncherDeclaration & {
+ pluginId: string;
+ pluginKey: string;
+ pluginDisplayName: string;
+ pluginVersion: string;
+ uiEntryFile: string;
+};
+
+type UsePluginLaunchersFilters = {
+ placementZones: PluginLauncherPlacementZone[];
+ entityType?: PluginUiSlotEntityType | null;
+ companyId?: string | null;
+ enabled?: boolean;
+};
+
+type UsePluginLaunchersResult = {
+ launchers: ResolvedPluginLauncher[];
+ contributionsByPluginId: Map<string, PluginUiContribution>;
+ isLoading: boolean;
+ errorMessage: string | null;
+};
+
+type PluginLauncherRuntimeContextValue = {
+ /**
+ * Open a launcher using already-discovered contribution metadata.
+ *
+ * The runtime accepts the normalized `PluginUiContribution` so callers can
+ * reuse the `/api/plugins/ui-contributions` payload they already fetched
+ * instead of issuing another request for each launcher activation.
+ */
+ activateLauncher(
+ launcher: ResolvedPluginLauncher,
+ hostContext: PluginLauncherContext,
+ contribution: PluginUiContribution,
+ sourceEl?: HTMLElement | null,
+ ): Promise<void>;
+};
+
+type LauncherInstance = {
+ key: string;
+ launcher: ResolvedPluginLauncher;
+ hostContext: PluginLauncherContext;
+ contribution: PluginUiContribution;
+ component: RegisteredPluginComponent | null;
+ sourceElement: HTMLElement | null;
+ sourceRect: DOMRect | null;
+ bounds: PluginLauncherBounds | null;
+ beforeCloseHandlers: Set<PluginRenderCloseHandler>;
+ closeHandlers: Set<PluginRenderCloseHandler>;
+};
+
+const entityScopedZones = new Set<PluginLauncherPlacementZone>([
+ "detailTab",
+ "taskDetailView",
+ "contextMenuItem",
+ "commentAnnotation",
+ "commentContextMenuItem",
+ "projectSidebarItem",
+]);
+const focusableElementSelector = [
+ "button:not([disabled])",
+ "[href]",
+ "input:not([disabled])",
+ "select:not([disabled])",
+ "textarea:not([disabled])",
+ "[tabindex]:not([tabindex='-1'])",
+].join(",");
+const launcherOverlayBaseZIndex = 1000;
+const supportedLauncherBounds = new Set<PluginLauncherBounds>(
+ PLUGIN_LAUNCHER_BOUNDS,
+);
+
+const PluginLauncherRuntimeContext = createContext<PluginLauncherRuntimeContextValue | null>(null);
+
+function getErrorMessage(error: unknown): string {
+ if (error instanceof Error && error.message) return error.message;
+ return "Unknown error";
+}
+
+function buildLauncherHostContext(
+ context: PluginLauncherContext,
+ renderEnvironment: PluginRenderEnvironmentContext | null,
+ userId: string | null,
+): PluginHostContext {
+ return {
+ companyId: context.companyId ?? null,
+ companyPrefix: context.companyPrefix ?? null,
+ projectId: context.projectId ?? (context.entityType === "project" ? context.entityId ?? null : null),
+ entityId: context.entityId ?? null,
+ entityType: context.entityType ?? null,
+ userId,
+ renderEnvironment,
+ };
+}
+
+function focusFirstElement(container: HTMLElement | null): void {
+ if (!container) return;
+ const firstFocusable = container.querySelector<HTMLElement>(focusableElementSelector);
+ if (firstFocusable) {
+ firstFocusable.focus();
+ return;
+ }
+ container.focus();
+}
+
+function trapFocus(container: HTMLElement, event: KeyboardEvent): void {
+ if (event.key !== "Tab") return;
+ const focusable = Array.from(
+ container.querySelectorAll<HTMLElement>(focusableElementSelector),
+ ).filter((el) => !el.hasAttribute("disabled") && el.tabIndex !== -1);
+
+ if (focusable.length === 0) {
+ event.preventDefault();
+ container.focus();
+ return;
+ }
+
+ const first = focusable[0];
+ const last = focusable[focusable.length - 1];
+ const active = document.activeElement as HTMLElement | null;
+
+ if (event.shiftKey && active === first) {
+ event.preventDefault();
+ last.focus();
+ return;
+ }
+
+ if (!event.shiftKey && active === last) {
+ event.preventDefault();
+ first.focus();
+ }
+}
+
+function launcherTriggerClassName(placementZone: PluginLauncherPlacementZone): string {
+ switch (placementZone) {
+ case "projectSidebarItem":
+ return "justify-start h-auto px-3 py-1 text-[12px] font-normal text-muted-foreground hover:text-foreground";
+ case "contextMenuItem":
+ case "commentContextMenuItem":
+ return "justify-start h-7 w-full px-2 text-xs font-normal";
+ case "sidebar":
+ case "sidebarPanel":
+ return "justify-start h-8 w-full";
+ default:
+ return "h-8";
+ }
+}
+
+function launcherShellBoundsStyle(bounds: PluginLauncherBounds | null): CSSProperties {
+ switch (bounds) {
+ case "compact":
+ return { width: "min(28rem, calc(100vw - 2rem))" };
+ case "wide":
+ return { width: "min(64rem, calc(100vw - 2rem))" };
+ case "full":
+ return { width: "calc(100vw - 2rem)", height: "calc(100vh - 2rem)" };
+ case "inline":
+ return { width: "min(24rem, calc(100vw - 2rem))" };
+ case "default":
+ default:
+ return { width: "min(40rem, calc(100vw - 2rem))" };
+ }
+}
+
+function launcherPopoverStyle(instance: LauncherInstance): CSSProperties {
+ const rect = instance.sourceRect;
+ const baseWidth = launcherShellBoundsStyle(instance.bounds).width ?? "min(24rem, calc(100vw - 2rem))";
+ if (!rect) {
+ return {
+ width: baseWidth,
+ maxHeight: "min(70vh, 36rem)",
+ top: "4rem",
+ left: "50%",
+ transform: "translateX(-50%)",
+ };
+ }
+
+ const top = Math.min(rect.bottom + 8, window.innerHeight - 32);
+ const left = Math.min(
+ Math.max(rect.left, 16),
+ Math.max(16, window.innerWidth - 360),
+ );
+
+ return {
+ width: baseWidth,
+ maxHeight: "min(70vh, 36rem)",
+ top,
+ left,
+ };
+}
+
+function isPluginLauncherBounds(value: unknown): value is PluginLauncherBounds {
+ return typeof value === "string" && supportedLauncherBounds.has(value as PluginLauncherBounds);
+}
+
+/**
+ * Discover launchers for the requested host placement zones from the normalized
+ * `/api/plugins/ui-contributions` response.
+ *
+ * This is the shared discovery path for toolbar, sidebar, detail-view, and
+ * context-menu launchers. The hook applies host-side entity filtering and
+ * returns both the sorted launcher list and a contribution map so activation
+ * can stay on cached metadata.
+ */
+export function usePluginLaunchers(
+ filters: UsePluginLaunchersFilters,
+): UsePluginLaunchersResult {
+ const queryEnabled = filters.enabled ?? true;
+ const { data, isLoading, error } = useQuery({
+ queryKey: queryKeys.plugins.uiContributions(filters.companyId),
+ queryFn: () => pluginsApi.listUiContributions(filters.companyId ?? undefined),
+ enabled: queryEnabled,
+ });
+
+ const placementZonesKey = useMemo(
+ () => [...filters.placementZones].sort().join("|"),
+ [filters.placementZones],
+ );
+
+ const contributionsByPluginId = useMemo(() => {
+ const byPluginId = new Map<string, PluginUiContribution>();
+ for (const contribution of data ?? []) {
+ byPluginId.set(contribution.pluginId, contribution);
+ }
+ return byPluginId;
+ }, [data]);
+
+ const launchers = useMemo(() => {
+ const placementZones = new Set(
+ placementZonesKey.split("|").filter(Boolean) as PluginLauncherPlacementZone[],
+ );
+ const rows: ResolvedPluginLauncher[] = [];
+ for (const contribution of data ?? []) {
+ for (const launcher of contribution.launchers) {
+ if (!placementZones.has(launcher.placementZone)) continue;
+ if (entityScopedZones.has(launcher.placementZone)) {
+ if (!filters.entityType) continue;
+ if (!launcher.entityTypes?.includes(filters.entityType)) continue;
+ }
+ rows.push({
+ ...launcher,
+ pluginId: contribution.pluginId,
+ pluginKey: contribution.pluginKey,
+ pluginDisplayName: contribution.displayName,
+ pluginVersion: contribution.version,
+ uiEntryFile: contribution.uiEntryFile,
+ });
+ }
+ }
+
+ rows.sort((a, b) => {
+ const ao = a.order ?? Number.MAX_SAFE_INTEGER;
+ const bo = b.order ?? Number.MAX_SAFE_INTEGER;
+ if (ao !== bo) return ao - bo;
+ const pluginCmp = a.pluginDisplayName.localeCompare(b.pluginDisplayName);
+ if (pluginCmp !== 0) return pluginCmp;
+ return a.displayName.localeCompare(b.displayName);
+ });
+
+ return rows;
+ }, [data, filters.entityType, placementZonesKey]);
+
+ return {
+ launchers,
+ contributionsByPluginId,
+ isLoading: queryEnabled && isLoading,
+ errorMessage: error ? getErrorMessage(error) : null,
+ };
+}
+
+async function resolveLauncherComponent(
+ contribution: PluginUiContribution,
+ launcher: ResolvedPluginLauncher,
+): Promise<RegisteredPluginComponent | null> {
+ const exportName = launcher.action.target;
+ const existing = resolveRegisteredPluginComponent(launcher.pluginKey, exportName);
+ if (existing) return existing;
+ await ensurePluginContributionLoaded(contribution);
+ return resolveRegisteredPluginComponent(launcher.pluginKey, exportName);
+}
+
+/**
+ * Scope bridge calls to the currently rendered launcher host context.
+ *
+ * Hooks such as `useHostContext()`, `usePluginData()`, and `usePluginAction()`
+ * consume this ambient context so the bridge can forward company/entity scope
+ * and render-environment metadata to the plugin worker.
+ */
+function PluginLauncherBridgeScope({
+ pluginId,
+ hostContext,
+ children,
+}: {
+ pluginId: string;
+ hostContext: PluginHostContext;
+ children: ReactNode;
+}) {
+ const value = useMemo(() => ({ pluginId, hostContext }), [pluginId, hostContext]);
+
+ return (
+ <PluginBridgeContext.Provider value={value}>
+ {children}
+ </PluginBridgeContext.Provider>
+ );
+}
+
+type LauncherErrorBoundaryProps = {
+ launcher: ResolvedPluginLauncher;
+ children: ReactNode;
+};
+
+type LauncherErrorBoundaryState = {
+ hasError: boolean;
+};
+
+class LauncherErrorBoundary extends Component<LauncherErrorBoundaryProps, LauncherErrorBoundaryState> {
+ override state: LauncherErrorBoundaryState = { hasError: false };
+
+ static getDerivedStateFromError(): LauncherErrorBoundaryState {
+ return { hasError: true };
+ }
+
+ override componentDidCatch(error: unknown, info: ErrorInfo): void {
+ console.error("Plugin launcher render failed", {
+ pluginKey: this.props.launcher.pluginKey,
+ launcherId: this.props.launcher.id,
+ error,
+ info: info.componentStack,
+ });
+ }
+
+ override render() {
+ if (this.state.hasError) {
+ return (
+ <div className="rounded-md border border-destructive/30 bg-destructive/5 p-3 text-sm text-destructive">
+ {this.props.launcher.pluginDisplayName}: failed to render
+ </div>
+ );
+ }
+ return this.props.children;
+ }
+}
+
+function LauncherRenderContent({
+ instance,
+ renderEnvironment,
+}: {
+ instance: LauncherInstance;
+ renderEnvironment: PluginRenderEnvironmentContext;
+}) {
+ const component = instance.component;
+ const { data: session } = useQuery({
+ queryKey: queryKeys.auth.session,
+ queryFn: () => authApi.getSession(),
+ });
+ const userId = session?.user?.id ?? session?.session?.userId ?? null;
+ const hostContext = useMemo(
+ () => buildLauncherHostContext(instance.hostContext, renderEnvironment, userId),
+ [instance.hostContext, renderEnvironment, userId],
+ );
+
+ if (!component) {
+ if (renderEnvironment.environment === "iframe") {
+ return (
+ <iframe
+ src={`/_plugins/${encodeURIComponent(instance.launcher.pluginId)}/ui/${instance.launcher.action.target}`}
+ title={`${instance.launcher.pluginDisplayName} ${instance.launcher.displayName}`}
+ className="h-full min-h-[24rem] w-full rounded-md border border-border bg-background"
+ />
+ );
+ }
+
+ return (
+ <div className="rounded-md border border-destructive/30 bg-destructive/5 p-3 text-sm text-destructive">
+ {instance.launcher.pluginDisplayName}: could not resolve launcher target "{instance.launcher.action.target}".
+ </div>
+ );
+ }
+
+ if (component.kind === "web-component") {
+ return createElement(component.tagName, {
+ className: "block w-full",
+ pluginLauncher: instance.launcher,
+ pluginContext: hostContext,
+ });
+ }
+
+ const node = createElement(component.component as never, {
+ launcher: instance.launcher,
+ context: hostContext,
+ } as never);
+
+ return (
+ <LauncherErrorBoundary launcher={instance.launcher}>
+ <PluginLauncherBridgeScope pluginId={instance.launcher.pluginId} hostContext={hostContext}>
+ {node}
+ </PluginLauncherBridgeScope>
+ </LauncherErrorBoundary>
+ );
+}
+
+function LauncherModalShell({
+ instance,
+ stackIndex,
+ isTopmost,
+ requestBounds,
+ closeLauncher,
+}: {
+ instance: LauncherInstance;
+ stackIndex: number;
+ isTopmost: boolean;
+ requestBounds: (key: string, request: PluginModalBoundsRequest) => Promise<void>;
+ closeLauncher: (key: string, event: PluginRenderCloseEvent) => Promise<void>;
+}) {
+ const contentRef = useRef<HTMLDivElement | null>(null);
+ const titleId = useId();
+
+ useEffect(() => {
+ if (!isTopmost) return;
+ const frame = requestAnimationFrame(() => {
+ focusFirstElement(contentRef.current);
+ });
+ return () => cancelAnimationFrame(frame);
+ }, [isTopmost]);
+
+ useEffect(() => {
+ if (!isTopmost) return;
+ const handleKeyDown = (event: KeyboardEvent) => {
+ if (!contentRef.current) return;
+ if (event.key === "Escape") {
+ event.preventDefault();
+ void closeLauncher(instance.key, { reason: "escapeKey", nativeEvent: event });
+ return;
+ }
+ trapFocus(contentRef.current, event);
+ };
+ document.addEventListener("keydown", handleKeyDown);
+ return () => document.removeEventListener("keydown", handleKeyDown);
+ }, [closeLauncher, instance.key, isTopmost]);
+
+ const renderEnvironment = useMemo<PluginRenderEnvironmentContext>(() => ({
+ environment: instance.launcher.render?.environment ?? "hostOverlay",
+ launcherId: instance.launcher.id,
+ bounds: instance.bounds,
+ requestModalBounds: (request) => requestBounds(instance.key, request),
+ closeLifecycle: {
+ onBeforeClose: (handler) => {
+ instance.beforeCloseHandlers.add(handler);
+ return () => instance.beforeCloseHandlers.delete(handler);
+ },
+ onClose: (handler) => {
+ instance.closeHandlers.add(handler);
+ return () => instance.closeHandlers.delete(handler);
+ },
+ },
+ }), [instance, requestBounds]);
+
+ const baseZ = launcherOverlayBaseZIndex + stackIndex * 20;
+ // Keep each launcher in a deterministic z-index band so every stacked modal,
+ // drawer, or popover retains its own backdrop/panel pairing.
+ const shellType = instance.launcher.action.type;
+ const containerStyle = shellType === "openPopover"
+ ? launcherPopoverStyle(instance)
+ : launcherShellBoundsStyle(instance.bounds);
+
+ const panelClassName = shellType === "openDrawer"
+ ? "fixed right-0 top-0 h-full max-w-[min(44rem,100vw)] overflow-hidden border-l border-border bg-background shadow-2xl"
+ : shellType === "openPopover"
+ ? "fixed overflow-hidden rounded-xl border border-border bg-background shadow-2xl"
+ : "fixed left-1/2 top-1/2 max-h-[calc(100vh-2rem)] -translate-x-1/2 -translate-y-1/2 overflow-hidden rounded-2xl border border-border bg-background shadow-2xl";
+
+ return (
+ <>
+ <div
+ className="fixed inset-0 bg-black/45"
+ style={{ zIndex: baseZ }}
+ aria-hidden="true"
+ onMouseDown={(event) => {
+ if (!isTopmost) return;
+ if (event.target !== event.currentTarget) return;
+ void closeLauncher(instance.key, { reason: "backdrop", nativeEvent: event });
+ }}
+ />
+ <div
+ ref={contentRef}
+ role="dialog"
+ aria-modal="true"
+ aria-labelledby={titleId}
+ tabIndex={-1}
+ className={panelClassName}
+ style={{
+ zIndex: baseZ + 1,
+ ...(shellType === "openDrawer"
+ ? { width: containerStyle.width ?? "min(44rem, 100vw)" }
+ : containerStyle),
+ }}
+ onMouseDown={(event) => event.stopPropagation()}
+ >
+ <div className="flex items-center gap-3 border-b border-border px-4 py-3">
+ <div className="min-w-0">
+ <h2 id={titleId} className="truncate text-sm font-semibold">
+ {instance.launcher.displayName}
+ </h2>
+ <p className="truncate text-xs text-muted-foreground">
+ {instance.launcher.pluginDisplayName}
+ </p>
+ </div>
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ className="ml-auto"
+ onClick={() => void closeLauncher(instance.key, { reason: "programmatic" })}
+ >
+ Close
+ </Button>
+ </div>
+ <div
+ className={cn(
+ "overflow-auto p-4",
+ shellType === "openDrawer" ? "h-[calc(100%-3.5rem)]" : "max-h-[calc(100vh-7rem)]",
+ )}
+ >
+ <LauncherRenderContent instance={instance} renderEnvironment={renderEnvironment} />
+ </div>
+ </div>
+ </>
+ );
+}
+
+export function PluginLauncherProvider({ children }: { children: ReactNode }) {
+ const [stack, setStack] = useState<LauncherInstance[]>([]);
+ const stackRef = useRef(stack);
+ stackRef.current = stack;
+ const location = useLocation();
+ const navigate = useNavigate();
+
+ const closeLauncher = useCallback(
+ async (key: string, event: PluginRenderCloseEvent) => {
+ const instance = stackRef.current.find((entry) => entry.key === key);
+ if (!instance) return;
+
+ for (const handler of [...instance.beforeCloseHandlers]) {
+ await handler(event);
+ }
+
+ setStack((current) => current.filter((entry) => entry.key !== key));
+
+ queueMicrotask(() => {
+ for (const handler of [...instance.closeHandlers]) {
+ void handler(event);
+ }
+ if (instance.sourceElement && document.contains(instance.sourceElement)) {
+ instance.sourceElement.focus();
+ }
+ });
+ },
+ [],
+ );
+
+ useEffect(() => {
+ if (stack.length === 0) return;
+ void Promise.all(
+ stack.map((entry) => closeLauncher(entry.key, { reason: "hostNavigation" })),
+ );
+ // Only react to navigation changes, not stack churn.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [location.key]);
+
+ const requestBounds = useCallback(
+ async (key: string, request: PluginModalBoundsRequest) => {
+ // Bounds changes are host-validated. Unsupported presets are ignored so
+ // plugin UI cannot push the shell into an undefined layout state.
+ if (!isPluginLauncherBounds(request.bounds)) {
+ return;
+ }
+ setStack((current) =>
+ current.map((entry) =>
+ entry.key === key
+ ? { ...entry, bounds: request.bounds }
+ : entry,
+ ),
+ );
+ },
+ [],
+ );
+
+ const activateLauncher = useCallback(
+ async (
+ launcher: ResolvedPluginLauncher,
+ hostContext: PluginLauncherContext,
+ contribution: PluginUiContribution,
+ sourceEl?: HTMLElement | null,
+ ) => {
+ switch (launcher.action.type) {
+ case "navigate":
+ navigate(launcher.action.target);
+ return;
+ case "deepLink":
+ if (/^https?:\/\//.test(launcher.action.target)) {
+ window.open(launcher.action.target, "_blank", "noopener,noreferrer");
+ } else {
+ navigate(launcher.action.target);
+ }
+ return;
+ case "performAction":
+ await pluginsApi.bridgePerformAction(
+ launcher.pluginId,
+ launcher.action.target,
+ launcher.action.params,
+ hostContext.companyId ?? null,
+ );
+ return;
+ case "openModal":
+ case "openDrawer":
+ case "openPopover": {
+ const component = await resolveLauncherComponent(contribution, launcher);
+ const sourceRect = sourceEl?.getBoundingClientRect() ?? null;
+ const nextEntry: LauncherInstance = {
+ key: `${launcher.pluginId}:${launcher.id}:${Date.now()}:${Math.random().toString(36).slice(2, 8)}`,
+ launcher,
+ hostContext,
+ contribution,
+ component,
+ sourceElement: sourceEl ?? null,
+ sourceRect,
+ bounds: launcher.render?.bounds ?? "default",
+ beforeCloseHandlers: new Set(),
+ closeHandlers: new Set(),
+ };
+ setStack((current) => [...current, nextEntry]);
+ return;
+ }
+ }
+ },
+ [navigate],
+ );
+
+ const value = useMemo<PluginLauncherRuntimeContextValue>(
+ () => ({ activateLauncher }),
+ [activateLauncher],
+ );
+
+ return (
+ <PluginLauncherRuntimeContext.Provider value={value}>
+ {children}
+ {stack.map((instance, index) => (
+ <LauncherModalShell
+ key={instance.key}
+ instance={instance}
+ stackIndex={index}
+ isTopmost={index === stack.length - 1}
+ requestBounds={requestBounds}
+ closeLauncher={closeLauncher}
+ />
+ ))}
+ </PluginLauncherRuntimeContext.Provider>
+ );
+}
+
+export function usePluginLauncherRuntime(): PluginLauncherRuntimeContextValue {
+ const value = useContext(PluginLauncherRuntimeContext);
+ if (!value) {
+ throw new Error("usePluginLauncherRuntime must be used within PluginLauncherProvider");
+ }
+ return value;
+}
+
+function DefaultLauncherTrigger({
+ launcher,
+ placementZone,
+ onClick,
+}: {
+ launcher: ResolvedPluginLauncher;
+ placementZone: PluginLauncherPlacementZone;
+ onClick: (event: ReactMouseEvent<HTMLButtonElement>) => void;
+}) {
+ return (
+ <Button
+ type="button"
+ variant={placementZone === "toolbarButton" ? "outline" : "ghost"}
+ size="sm"
+ className={launcherTriggerClassName(placementZone)}
+ onClick={onClick}
+ >
+ {launcher.displayName}
+ </Button>
+ );
+}
+
+type PluginLauncherOutletProps = {
+ placementZones: PluginLauncherPlacementZone[];
+ context: PluginLauncherContext;
+ entityType?: PluginUiSlotEntityType | null;
+ className?: string;
+ itemClassName?: string;
+ errorClassName?: string;
+};
+
+export function PluginLauncherOutlet({
+ placementZones,
+ context,
+ entityType,
+ className,
+ itemClassName,
+ errorClassName,
+}: PluginLauncherOutletProps) {
+ const { activateLauncher } = usePluginLauncherRuntime();
+ const { launchers, contributionsByPluginId, errorMessage } = usePluginLaunchers({
+ placementZones,
+ entityType,
+ companyId: context.companyId,
+ enabled: !!context.companyId,
+ });
+
+ if (errorMessage) {
+ return (
+ <div className={cn("rounded-md border border-destructive/30 bg-destructive/5 px-2 py-1 text-xs text-destructive", errorClassName)}>
+ Plugin launchers unavailable: {errorMessage}
+ </div>
+ );
+ }
+
+ if (launchers.length === 0) return null;
+
+ return (
+ <div className={className}>
+ {launchers.map((launcher) => (
+ <div key={`${launcher.pluginKey}:${launcher.id}`} className={itemClassName}>
+ <DefaultLauncherTrigger
+ launcher={launcher}
+ placementZone={launcher.placementZone}
+ onClick={(event) => {
+ const contribution = contributionsByPluginId.get(launcher.pluginId);
+ if (!contribution) return;
+ void activateLauncher(launcher, context, contribution, event.currentTarget);
+ }}
+ />
+ </div>
+ ))}
+ </div>
+ );
+}
+
+type PluginLauncherButtonProps = {
+ launcher: ResolvedPluginLauncher;
+ context: PluginLauncherContext;
+ contribution: PluginUiContribution;
+ className?: string;
+ onActivated?: () => void;
+};
+
+export function PluginLauncherButton({
+ launcher,
+ context,
+ contribution,
+ className,
+ onActivated,
+}: PluginLauncherButtonProps) {
+ const { activateLauncher } = usePluginLauncherRuntime();
+
+ return (
+ <div className={className}>
+ <DefaultLauncherTrigger
+ launcher={launcher}
+ placementZone={launcher.placementZone}
+ onClick={(event) => {
+ event.preventDefault();
+ onActivated?.();
+ void activateLauncher(launcher, context, contribution, event.currentTarget);
+ }}
+ />
+ </div>
+ );
+}
diff --git a/ui/src/plugins/slots.tsx b/ui/src/plugins/slots.tsx
new file mode 100644
index 0000000000..af800c9167
--- /dev/null
+++ b/ui/src/plugins/slots.tsx
@@ -0,0 +1,862 @@
+/**
+ * @fileoverview Plugin UI slot system — dynamic loading, error isolation,
+ * and rendering of plugin-contributed UI extensions.
+ *
+ * Provides:
+ * - `usePluginSlots(type, context?)` — React hook that discovers and
+ * filters plugin UI contributions for a given slot type.
+ * - `PluginSlotOutlet` — renders all matching slots inline with error
+ * boundary isolation per plugin.
+ * - `PluginBridgeScope` — wraps each plugin's component tree to inject
+ * the bridge context (`pluginId`, host context) needed by bridge hooks.
+ *
+ * Plugin UI modules are loaded via dynamic ESM `import()` from the host's
+ * static file server (`/_plugins/:pluginId/ui/:entryFile`). Each module
+ * exports named React components that correspond to `ui.slots[].exportName`
+ * in the manifest.
+ *
+ * @see PLUGIN_SPEC.md §19 — UI Extension Model
+ * @see PLUGIN_SPEC.md §19.0.3 — Bundle Serving
+ */
+import {
+ Component,
+ createElement,
+ useEffect,
+ useMemo,
+ useRef,
+ useState,
+ type ErrorInfo,
+ type ReactNode,
+ type ComponentType,
+} from "react";
+import { useQuery } from "@tanstack/react-query";
+import type {
+ PluginLauncherDeclaration,
+ PluginUiSlotDeclaration,
+ PluginUiSlotEntityType,
+ PluginUiSlotType,
+} from "@paperclipai/shared";
+import { pluginsApi, type PluginUiContribution } from "@/api/plugins";
+import { authApi } from "@/api/auth";
+import { queryKeys } from "@/lib/queryKeys";
+import { cn } from "@/lib/utils";
+import {
+ PluginBridgeContext,
+ type PluginHostContext,
+} from "./bridge";
+
+export type PluginSlotContext = {
+ companyId?: string | null;
+ companyPrefix?: string | null;
+ projectId?: string | null;
+ entityId?: string | null;
+ entityType?: PluginUiSlotEntityType | null;
+ /** Parent entity ID for nested slots (e.g. comment annotations within an issue). */
+ parentEntityId?: string | null;
+ projectRef?: string | null;
+};
+
+export type ResolvedPluginSlot = PluginUiSlotDeclaration & {
+ pluginId: string;
+ pluginKey: string;
+ pluginDisplayName: string;
+ pluginVersion: string;
+};
+
+type PluginSlotComponentProps = {
+ slot: ResolvedPluginSlot;
+ context: PluginSlotContext;
+};
+
+export type RegisteredPluginComponent =
+ | {
+ kind: "react";
+ component: ComponentType<PluginSlotComponentProps>;
+ }
+ | {
+ kind: "web-component";
+ tagName: string;
+ };
+
+type SlotFilters = {
+ slotTypes: PluginUiSlotType[];
+ entityType?: PluginUiSlotEntityType | null;
+ companyId?: string | null;
+ enabled?: boolean;
+};
+
+type UsePluginSlotsResult = {
+ slots: ResolvedPluginSlot[];
+ isLoading: boolean;
+ errorMessage: string | null;
+};
+
+/**
+ * In-memory registry for plugin UI exports loaded by the host page.
+ * Keys are `${pluginKey}:${exportName}` to match manifest slot declarations.
+ */
+const registry = new Map<string, RegisteredPluginComponent>();
+
+function buildRegistryKey(pluginKey: string, exportName: string): string {
+ return `${pluginKey}:${exportName}`;
+}
+
+function requiresEntityType(slotType: PluginUiSlotType): boolean {
+ return slotType === "detailTab" || slotType === "taskDetailView" || slotType === "contextMenuItem" || slotType === "commentAnnotation" || slotType === "commentContextMenuItem" || slotType === "projectSidebarItem";
+}
+
+function getErrorMessage(error: unknown): string {
+ if (error instanceof Error && error.message) return error.message;
+ return "Unknown error";
+}
+
+/**
+ * Registers a React component export for a plugin UI slot.
+ */
+export function registerPluginReactComponent(
+ pluginKey: string,
+ exportName: string,
+ component: ComponentType<PluginSlotComponentProps>,
+): void {
+ registry.set(buildRegistryKey(pluginKey, exportName), {
+ kind: "react",
+ component,
+ });
+}
+
+/**
+ * Registers a custom element tag for a plugin UI slot.
+ */
+export function registerPluginWebComponent(
+ pluginKey: string,
+ exportName: string,
+ tagName: string,
+): void {
+ registry.set(buildRegistryKey(pluginKey, exportName), {
+ kind: "web-component",
+ tagName,
+ });
+}
+
+function resolveRegisteredComponent(slot: ResolvedPluginSlot): RegisteredPluginComponent | null {
+ return registry.get(buildRegistryKey(slot.pluginKey, slot.exportName)) ?? null;
+}
+
+export function resolveRegisteredPluginComponent(
+ pluginKey: string,
+ exportName: string,
+): RegisteredPluginComponent | null {
+ return registry.get(buildRegistryKey(pluginKey, exportName)) ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin module dynamic import loader
+// ---------------------------------------------------------------------------
+
+type PluginLoadState = "idle" | "loading" | "loaded" | "error";
+
+/**
+ * Tracks the load state for each plugin's UI module by contribution cache key.
+ *
+ * Once a plugin module is loaded, all its named exports are inspected and
+ * registered into the component `registry` so that `resolveRegisteredComponent`
+ * can find them when slots render.
+ */
+const pluginLoadStates = new Map<string, PluginLoadState>();
+
+/**
+ * Promise cache to prevent concurrent duplicate imports for the same plugin.
+ */
+const inflightImports = new Map<string, Promise<void>>();
+
+/**
+ * Build the full URL for a plugin's UI entry module.
+ *
+ * The server serves plugin UI bundles at `/_plugins/:pluginId/ui/*`.
+ * The `uiEntryFile` from the contribution (typically `"index.js"`) is
+ * appended to form the complete import path.
+ */
+function buildPluginModuleKey(contribution: PluginUiContribution): string {
+ const cacheHint = contribution.updatedAt ?? contribution.version ?? "0";
+ return `${contribution.pluginId}:${cacheHint}`;
+}
+
+function buildPluginUiUrl(contribution: PluginUiContribution): string {
+ const cacheHint = encodeURIComponent(contribution.updatedAt ?? contribution.version ?? "0");
+ return `/_plugins/${encodeURIComponent(contribution.pluginId)}/ui/${contribution.uiEntryFile}?v=${cacheHint}`;
+}
+
+/**
+ * Import a plugin's UI entry module with bare-specifier rewriting.
+ *
+ * Plugin bundles are built with `external: ["@paperclipai/plugin-sdk/ui", "react", "react-dom"]`,
+ * so their ESM output contains bare specifier imports like:
+ *
+ * ```js
+ * import { usePluginData } from "@paperclipai/plugin-sdk/ui";
+ * import React from "react";
+ * ```
+ *
+ * Browsers cannot resolve bare specifiers without an import map. Rather than
+ * fighting import map timing constraints, we:
+ * 1. Fetch the module source text
+ * 2. Rewrite bare specifier imports to use blob URLs that re-export from the
+ * host's global bridge registry (`globalThis.__paperclipPluginBridge__`)
+ * 3. Import the rewritten module via a blob URL
+ *
+ * This approach is compatible with all modern browsers and avoids import map
+ * ordering issues.
+ */
+const shimBlobUrls: Record<string, string> = {};
+
+function applyJsxRuntimeKey(
+ props: Record<string, unknown> | null | undefined,
+ key: string | number | undefined,
+): Record<string, unknown> {
+ if (key === undefined) return props ?? {};
+ return { ...(props ?? {}), key };
+}
+
+function getShimBlobUrl(specifier: "react" | "react-dom" | "react-dom/client" | "react/jsx-runtime" | "sdk-ui"): string {
+ if (shimBlobUrls[specifier]) return shimBlobUrls[specifier];
+
+ let source: string;
+ switch (specifier) {
+ case "react":
+ source = `
+ const R = globalThis.__paperclipPluginBridge__?.react;
+ export default R;
+ const { useState, useEffect, useCallback, useMemo, useRef, useContext,
+ createContext, createElement, Fragment, Component, forwardRef,
+ memo, lazy, Suspense, StrictMode, cloneElement, Children,
+ isValidElement, createRef } = R;
+ export { useState, useEffect, useCallback, useMemo, useRef, useContext,
+ createContext, createElement, Fragment, Component, forwardRef,
+ memo, lazy, Suspense, StrictMode, cloneElement, Children,
+ isValidElement, createRef };
+ `;
+ break;
+ case "react/jsx-runtime":
+ source = `
+ const R = globalThis.__paperclipPluginBridge__?.react;
+ const withKey = ${applyJsxRuntimeKey.toString()};
+ export const jsx = (type, props, key) => R.createElement(type, withKey(props, key));
+ export const jsxs = (type, props, key) => R.createElement(type, withKey(props, key));
+ export const Fragment = R.Fragment;
+ `;
+ break;
+ case "react-dom":
+ case "react-dom/client":
+ source = `
+ const RD = globalThis.__paperclipPluginBridge__?.reactDom;
+ export default RD;
+ const { createRoot, hydrateRoot, createPortal, flushSync } = RD ?? {};
+ export { createRoot, hydrateRoot, createPortal, flushSync };
+ `;
+ break;
+ case "sdk-ui":
+ source = `
+ const SDK = globalThis.__paperclipPluginBridge__?.sdkUi ?? {};
+ const { usePluginData, usePluginAction, useHostContext,
+ MetricCard, StatusBadge, DataTable, TimeseriesChart,
+ MarkdownBlock, KeyValueList, ActionBar, LogView, JsonTree,
+ Spinner, ErrorBoundary } = SDK;
+ export { usePluginData, usePluginAction, useHostContext,
+ MetricCard, StatusBadge, DataTable, TimeseriesChart,
+ MarkdownBlock, KeyValueList, ActionBar, LogView, JsonTree,
+ Spinner, ErrorBoundary };
+ `;
+ break;
+ }
+
+ const blob = new Blob([source], { type: "application/javascript" });
+ const url = URL.createObjectURL(blob);
+ shimBlobUrls[specifier] = url;
+ return url;
+}
+
+/**
+ * Rewrite bare specifier imports in an ESM source string to use blob URLs.
+ *
+ * This handles the standard import patterns emitted by esbuild/rollup:
+ * - `import { ... } from "react";`
+ * - `import React from "react";`
+ * - `import * as React from "react";`
+ * - `import { ... } from "@paperclipai/plugin-sdk/ui";`
+ *
+ * Also handles re-exports:
+ * - `export { ... } from "react";`
+ */
+function rewriteBareSpecifiers(source: string): string {
+ // Build a mapping of bare specifiers to blob URLs.
+ const rewrites: Record<string, string> = {
+ '"@paperclipai/plugin-sdk/ui"': `"${getShimBlobUrl("sdk-ui")}"`,
+ "'@paperclipai/plugin-sdk/ui'": `'${getShimBlobUrl("sdk-ui")}'`,
+ '"@paperclipai/plugin-sdk/ui/hooks"': `"${getShimBlobUrl("sdk-ui")}"`,
+ "'@paperclipai/plugin-sdk/ui/hooks'": `'${getShimBlobUrl("sdk-ui")}'`,
+ '"@paperclipai/plugin-sdk/ui/components"': `"${getShimBlobUrl("sdk-ui")}"`,
+ "'@paperclipai/plugin-sdk/ui/components'": `'${getShimBlobUrl("sdk-ui")}'`,
+ '"react/jsx-runtime"': `"${getShimBlobUrl("react/jsx-runtime")}"`,
+ "'react/jsx-runtime'": `'${getShimBlobUrl("react/jsx-runtime")}'`,
+ '"react-dom/client"': `"${getShimBlobUrl("react-dom/client")}"`,
+ "'react-dom/client'": `'${getShimBlobUrl("react-dom/client")}'`,
+ '"react-dom"': `"${getShimBlobUrl("react-dom")}"`,
+ "'react-dom'": `'${getShimBlobUrl("react-dom")}'`,
+ '"react"': `"${getShimBlobUrl("react")}"`,
+ "'react'": `'${getShimBlobUrl("react")}'`,
+ };
+
+ let result = source;
+ for (const [from, to] of Object.entries(rewrites)) {
+ // Only rewrite in import/export from contexts, not in arbitrary strings.
+ // The regex matches `from "..."` or `from '...'` patterns.
+ result = result.replaceAll(` from ${from}`, ` from ${to}`);
+ // Also handle `import "..."` (side-effect imports)
+ result = result.replaceAll(`import ${from}`, `import ${to}`);
+ }
+
+ return result;
+}
+
+/**
+ * Fetch, rewrite, and import a plugin UI module.
+ *
+ * @param url - The URL to the plugin's UI entry module
+ * @returns The module's exports
+ */
+async function importPluginModule(url: string): Promise<Record<string, unknown>> {
+ // Check if the bridge registry is available. If not, fall back to direct
+ // import (which will fail on bare specifiers but won't crash the loader).
+ if (!globalThis.__paperclipPluginBridge__) {
+ console.warn("[plugin-loader] Bridge registry not initialized, falling back to direct import");
+ return import(/* @vite-ignore */ url);
+ }
+
+ // Fetch the module source text
+ const response = await fetch(url);
+ if (!response.ok) {
+ throw new Error(`Failed to fetch plugin module: ${response.status} ${response.statusText}`);
+ }
+
+ const source = await response.text();
+
+ // Rewrite bare specifier imports to blob URLs
+ const rewritten = rewriteBareSpecifiers(source);
+
+ // Create a blob URL from the rewritten source and import it
+ const blob = new Blob([rewritten], { type: "application/javascript" });
+ const blobUrl = URL.createObjectURL(blob);
+
+ try {
+ const mod = await import(/* @vite-ignore */ blobUrl);
+ return mod;
+ } finally {
+ // Clean up the blob URL after import (the module is already loaded)
+ URL.revokeObjectURL(blobUrl);
+ }
+}
+
+/**
+ * Dynamically import a plugin's UI entry module and register all named
+ * exports that look like React components (functions or classes) into the
+ * component registry.
+ *
+ * This replaces the previous approach where plugin bundles had to
+ * self-register via `window.paperclipPlugins.registerReactComponent()`.
+ * Now the host is responsible for importing the module and binding
+ * exports to the correct `pluginKey:exportName` registry keys.
+ *
+ * Plugin modules are loaded with bare-specifier rewriting so that imports
+ * of `@paperclipai/plugin-sdk/ui`, `react`, and `react-dom` resolve to the
+ * host-provided implementations via the bridge registry.
+ *
+ * Web-component registrations still work: if the module has a named export
+ * that matches an `exportName` declared in a slot AND that export is a
+ * string (the custom element tag name), it's registered as a web component.
+ */
+async function loadPluginModule(contribution: PluginUiContribution): Promise<void> {
+ const { pluginId, pluginKey, slots, launchers } = contribution;
+ const moduleKey = buildPluginModuleKey(contribution);
+
+ // Already loaded or loading — return early.
+ const state = pluginLoadStates.get(moduleKey);
+ if (state === "loaded" || state === "loading") {
+ // If currently loading, wait for the inflight promise.
+ const inflight = inflightImports.get(pluginId);
+ if (inflight) await inflight;
+ return;
+ }
+
+ // If another import for this plugin ID is currently in progress, wait for it.
+ const running = inflightImports.get(pluginId);
+ if (running) {
+ await running;
+ const recheckedState = pluginLoadStates.get(moduleKey);
+ if (recheckedState === "loaded") {
+ return;
+ }
+ }
+
+ pluginLoadStates.set(moduleKey, "loading");
+
+ const url = buildPluginUiUrl(contribution);
+
+ const importPromise = (async () => {
+ try {
+ // Dynamic ESM import of the plugin's UI entry module with
+ // bare-specifier rewriting for host-provided dependencies.
+ const mod: Record<string, unknown> = await importPluginModule(url);
+
+ // Collect the set of export names declared across all UI contributions so
+ // we only register what the manifest advertises (ignore extra exports).
+ const declaredExports = new Set<string>();
+ for (const slot of slots) {
+ declaredExports.add(slot.exportName);
+ }
+ for (const launcher of launchers) {
+ if (launcher.exportName) {
+ declaredExports.add(launcher.exportName);
+ }
+ if (isLauncherComponentTarget(launcher)) {
+ declaredExports.add(launcher.action.target);
+ }
+ }
+
+ for (const exportName of declaredExports) {
+ const exported = mod[exportName];
+ if (exported === undefined) {
+ console.warn(
+ `Plugin "${pluginKey}" declares slot export "${exportName}" but the module does not export it.`,
+ );
+ continue;
+ }
+
+ if (typeof exported === "function") {
+ // React component (function component or class component).
+ registerPluginReactComponent(
+ pluginKey,
+ exportName,
+ exported as ComponentType<PluginSlotComponentProps>,
+ );
+ } else if (typeof exported === "string") {
+ // Web component tag name.
+ registerPluginWebComponent(pluginKey, exportName, exported);
+ } else {
+ console.warn(
+ `Plugin "${pluginKey}" export "${exportName}" is neither a function nor a string tag name — skipping.`,
+ );
+ }
+ }
+
+ pluginLoadStates.set(moduleKey, "loaded");
+ } catch (err) {
+ pluginLoadStates.set(moduleKey, "error");
+ console.error(`Failed to load UI module for plugin "${pluginKey}"`, err);
+ } finally {
+ inflightImports.delete(pluginId);
+ }
+ })();
+
+ inflightImports.set(pluginId, importPromise);
+ await importPromise;
+}
+
+function isLauncherComponentTarget(launcher: PluginLauncherDeclaration): boolean {
+ return launcher.action.type === "openModal"
+ || launcher.action.type === "openDrawer"
+ || launcher.action.type === "openPopover";
+}
+
+/**
+ * Load UI modules for a set of plugin contributions.
+ *
+ * Returns a promise that resolves once all modules have been loaded (or
+ * failed). Plugins that are already loaded are skipped.
+ */
+async function ensurePluginModulesLoaded(contributions: PluginUiContribution[]): Promise<void> {
+ await Promise.all(
+ contributions.map((c) => loadPluginModule(c)),
+ );
+}
+
+export async function ensurePluginContributionLoaded(
+ contribution: PluginUiContribution,
+): Promise<void> {
+ await loadPluginModule(contribution);
+}
+
+/**
+ * Returns the aggregate load state across a set of plugin contributions.
+ * - If any plugin is still loading → "loading"
+ * - If all are loaded (or no contributions) → "loaded"
+ * - If all finished but some errored → "loaded" (errors are logged, not fatal)
+ */
+function aggregateLoadState(contributions: PluginUiContribution[]): "loading" | "loaded" {
+ for (const c of contributions) {
+ const state = pluginLoadStates.get(buildPluginModuleKey(c));
+ if (state === "loading" || state === "idle" || state === undefined) {
+ return "loading";
+ }
+ }
+ return "loaded";
+}
+
+// ---------------------------------------------------------------------------
+// React hooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Trigger dynamic loading of plugin UI modules when contributions change.
+ *
+ * This hook is intentionally decoupled from usePluginSlots so that callers
+ * who consume slots via `usePluginSlots()` automatically get module loading
+ * without extra wiring.
+ */
+function usePluginModuleLoader(contributions: PluginUiContribution[] | undefined) {
+ const [, setTick] = useState(0);
+
+ useEffect(() => {
+ if (!contributions || contributions.length === 0) return;
+
+ // Filter to contributions that haven't been loaded yet.
+ const unloaded = contributions.filter((c) => {
+ const state = pluginLoadStates.get(buildPluginModuleKey(c));
+ return state !== "loaded" && state !== "loading";
+ });
+
+ if (unloaded.length === 0) return;
+
+ let cancelled = false;
+ void ensurePluginModulesLoaded(unloaded).then(() => {
+ // Re-render so the slot mount can resolve the newly-registered components.
+ if (!cancelled) setTick((t) => t + 1);
+ });
+
+ return () => {
+ cancelled = true;
+ };
+ }, [contributions]);
+}
+
+/**
+ * Resolves and sorts slots across all ready plugin contributions.
+ *
+ * Filtering rules:
+ * - `slotTypes` must match one of the caller-requested host slot types.
+ * - Entity-scoped slot types (`detailTab`, `taskDetailView`, `contextMenuItem`)
+ * require `entityType` and must include it in `slot.entityTypes`.
+ *
+ * Automatically triggers dynamic import of plugin UI modules for any
+ * newly-discovered contributions. Components render once loading completes.
+ */
+export function usePluginSlots(filters: SlotFilters): UsePluginSlotsResult {
+ const queryEnabled = filters.enabled ?? true;
+ const { data, isLoading: isQueryLoading, error } = useQuery({
+ queryKey: queryKeys.plugins.uiContributions(filters.companyId),
+ queryFn: () => pluginsApi.listUiContributions(filters.companyId ?? undefined),
+ enabled: queryEnabled,
+ });
+
+ // Kick off dynamic imports for any new plugin contributions.
+ usePluginModuleLoader(data);
+
+ const slotTypesKey = useMemo(() => [...filters.slotTypes].sort().join("|"), [filters.slotTypes]);
+
+ const slots = useMemo(() => {
+ const allowedTypes = new Set(slotTypesKey.split("|").filter(Boolean) as PluginUiSlotType[]);
+ const rows: ResolvedPluginSlot[] = [];
+ for (const contribution of data ?? []) {
+ for (const slot of contribution.slots) {
+ if (!allowedTypes.has(slot.type)) continue;
+ if (requiresEntityType(slot.type)) {
+ if (!filters.entityType) continue;
+ if (!slot.entityTypes?.includes(filters.entityType)) continue;
+ }
+ rows.push({
+ ...slot,
+ pluginId: contribution.pluginId,
+ pluginKey: contribution.pluginKey,
+ pluginDisplayName: contribution.displayName,
+ pluginVersion: contribution.version,
+ });
+ }
+ }
+ rows.sort((a, b) => {
+ const ao = a.order ?? Number.MAX_SAFE_INTEGER;
+ const bo = b.order ?? Number.MAX_SAFE_INTEGER;
+ if (ao !== bo) return ao - bo;
+ const pluginCmp = a.pluginDisplayName.localeCompare(b.pluginDisplayName);
+ if (pluginCmp !== 0) return pluginCmp;
+ return a.displayName.localeCompare(b.displayName);
+ });
+ return rows;
+ }, [data, filters.entityType, slotTypesKey]);
+
+ // Consider loading until both query and module imports are done.
+ const modulesLoaded = data ? aggregateLoadState(data) === "loaded" : true;
+ const isLoading = queryEnabled && (isQueryLoading || !modulesLoaded);
+
+ return {
+ slots,
+ isLoading,
+ errorMessage: error ? getErrorMessage(error) : null,
+ };
+}
+
+type PluginSlotErrorBoundaryProps = {
+ slot: ResolvedPluginSlot;
+ className?: string;
+ children: ReactNode;
+};
+
+type PluginSlotErrorBoundaryState = {
+ hasError: boolean;
+};
+
+class PluginSlotErrorBoundary extends Component<PluginSlotErrorBoundaryProps, PluginSlotErrorBoundaryState> {
+ override state: PluginSlotErrorBoundaryState = { hasError: false };
+
+ static getDerivedStateFromError(): PluginSlotErrorBoundaryState {
+ return { hasError: true };
+ }
+
+ override componentDidCatch(error: unknown, info: ErrorInfo): void {
+ // Keep plugin failures isolated while preserving actionable diagnostics.
+ console.error("Plugin slot render failed", {
+ pluginKey: this.props.slot.pluginKey,
+ slotId: this.props.slot.id,
+ error,
+ info: info.componentStack,
+ });
+ }
+
+ override render() {
+ if (this.state.hasError) {
+ return (
+ <div className={cn("rounded-md border border-destructive/30 bg-destructive/5 px-2 py-1 text-xs text-destructive", this.props.className)}>
+ {this.props.slot.pluginDisplayName}: failed to render
+ </div>
+ );
+ }
+ return this.props.children;
+ }
+}
+
+function PluginWebComponentMount({
+ tagName,
+ slot,
+ context,
+ className,
+}: {
+ tagName: string;
+ slot: ResolvedPluginSlot;
+ context: PluginSlotContext;
+ className?: string;
+}) {
+ const ref = useRef<HTMLElement | null>(null);
+
+ useEffect(() => {
+ if (!ref.current) return;
+ // Bridge manifest slot/context metadata onto the custom element instance.
+ const el = ref.current as HTMLElement & {
+ pluginSlot?: ResolvedPluginSlot;
+ pluginContext?: PluginSlotContext;
+ };
+ el.pluginSlot = slot;
+ el.pluginContext = context;
+ }, [context, slot]);
+
+ return createElement(tagName, { ref, className });
+}
+
+type PluginSlotMountProps = {
+ slot: ResolvedPluginSlot;
+ context: PluginSlotContext;
+ className?: string;
+ missingBehavior?: "hidden" | "placeholder";
+};
+
+/**
+ * Maps the slot's `PluginSlotContext` to a `PluginHostContext` for the bridge.
+ *
+ * The bridge hooks need the full host context shape; the slot context carries
+ * the subset available from the rendering location.
+ */
+function slotContextToHostContext(
+ pluginSlotContext: PluginSlotContext,
+ userId: string | null,
+): PluginHostContext {
+ return {
+ companyId: pluginSlotContext.companyId ?? null,
+ companyPrefix: pluginSlotContext.companyPrefix ?? null,
+ projectId: pluginSlotContext.projectId ?? (pluginSlotContext.entityType === "project" ? pluginSlotContext.entityId ?? null : null),
+ entityId: pluginSlotContext.entityId ?? null,
+ entityType: pluginSlotContext.entityType ?? null,
+ parentEntityId: pluginSlotContext.parentEntityId ?? null,
+ userId,
+ renderEnvironment: null,
+ };
+}
+
+/**
+ * Wrapper component that sets the active bridge context around plugin renders.
+ *
+ * This ensures that `usePluginData()`, `usePluginAction()`, and `useHostContext()`
+ * have access to the current plugin ID and host context during the render phase.
+ */
+function PluginBridgeScope({
+ pluginId,
+ context,
+ children,
+}: {
+ pluginId: string;
+ context: PluginSlotContext;
+ children: ReactNode;
+}) {
+ const { data: session } = useQuery({
+ queryKey: queryKeys.auth.session,
+ queryFn: () => authApi.getSession(),
+ });
+ const userId = session?.user?.id ?? session?.session?.userId ?? null;
+ const hostContext = useMemo(() => slotContextToHostContext(context, userId), [context, userId]);
+ const value = useMemo(() => ({ pluginId, hostContext }), [pluginId, hostContext]);
+
+ return (
+ <PluginBridgeContext.Provider value={value}>
+ {children}
+ </PluginBridgeContext.Provider>
+ );
+}
+
+export function PluginSlotMount({
+ slot,
+ context,
+ className,
+ missingBehavior = "hidden",
+}: PluginSlotMountProps) {
+ const [, forceRerender] = useState(0);
+ const component = resolveRegisteredComponent(slot);
+
+ useEffect(() => {
+ if (component) return;
+ const inflight = inflightImports.get(slot.pluginId);
+ if (!inflight) return;
+
+ let cancelled = false;
+ void inflight.finally(() => {
+ if (!cancelled) {
+ forceRerender((tick) => tick + 1);
+ }
+ });
+
+ return () => {
+ cancelled = true;
+ };
+ }, [component, slot.pluginId]);
+
+ if (!component) {
+ if (missingBehavior === "hidden") return null;
+ return (
+ <div className={cn("rounded-md border border-dashed border-border px-2 py-1 text-xs text-muted-foreground", className)}>
+ {slot.pluginDisplayName}: {slot.displayName}
+ </div>
+ );
+ }
+
+ if (component.kind === "react") {
+ const node = createElement(component.component, { slot, context });
+ return (
+ <PluginSlotErrorBoundary slot={slot} className={className}>
+ <PluginBridgeScope pluginId={slot.pluginId} context={context}>
+ {className ? <div className={className}>{node}</div> : node}
+ </PluginBridgeScope>
+ </PluginSlotErrorBoundary>
+ );
+ }
+
+ return (
+ <PluginSlotErrorBoundary slot={slot} className={className}>
+ <PluginWebComponentMount
+ tagName={component.tagName}
+ slot={slot}
+ context={context}
+ className={className}
+ />
+ </PluginSlotErrorBoundary>
+ );
+}
+
+type PluginSlotOutletProps = {
+ slotTypes: PluginUiSlotType[];
+ context: PluginSlotContext;
+ entityType?: PluginUiSlotEntityType | null;
+ className?: string;
+ itemClassName?: string;
+ errorClassName?: string;
+ missingBehavior?: "hidden" | "placeholder";
+};
+
+export function PluginSlotOutlet({
+ slotTypes,
+ context,
+ entityType,
+ className,
+ itemClassName,
+ errorClassName,
+ missingBehavior = "hidden",
+}: PluginSlotOutletProps) {
+ const { slots, errorMessage } = usePluginSlots({
+ slotTypes,
+ entityType,
+ companyId: context.companyId,
+ });
+
+ if (errorMessage) {
+ return (
+ <div className={cn("rounded-md border border-destructive/30 bg-destructive/5 px-2 py-1 text-xs text-destructive", errorClassName)}>
+ Plugin extensions unavailable: {errorMessage}
+ </div>
+ );
+ }
+
+ if (slots.length === 0) return null;
+
+ return (
+ <div className={className}>
+ {slots.map((slot) => (
+ <PluginSlotMount
+ key={`${slot.pluginKey}:${slot.id}`}
+ slot={slot}
+ context={context}
+ className={itemClassName}
+ missingBehavior={missingBehavior}
+ />
+ ))}
+ </div>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers — exported for use in test suites only.
+// ---------------------------------------------------------------------------
+
+/**
+ * Reset the module loader state. Only use in tests.
+ * @internal
+ */
+export function _resetPluginModuleLoader(): void {
+ pluginLoadStates.clear();
+ inflightImports.clear();
+ registry.clear();
+ if (typeof URL.revokeObjectURL === "function") {
+ for (const url of Object.values(shimBlobUrls)) {
+ URL.revokeObjectURL(url);
+ }
+ }
+ for (const key of Object.keys(shimBlobUrls)) {
+ delete shimBlobUrls[key];
+ }
+}
+
+export const _applyJsxRuntimeKeyForTests = applyJsxRuntimeKey;
+export const _rewriteBareSpecifiersForTests = rewriteBareSpecifiers;