The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Add plugin framework and settings UI
Dotta80cdbdbd47ce
diff --git a/doc/plugins/PLUGIN_SPEC.md b/doc/plugins/PLUGIN_SPEC.mdindex 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 reaThis 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. ScopeThis 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 CommandsPaperclip 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 PrecedenceLoad order must be deterministic.diff --git a/packages/db/src/migrations/0028_plugin_tables.sql b/packages/db/src/migrations/0028_plugin_tables.sqlnew file mode 100644index 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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.mjsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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 changesdiff --git a/packages/plugins/sdk/package.json b/packages/plugins/sdk/package.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.yamlindex 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- clidiff --git a/scripts/ensure-plugin-build-deps.mjs b/scripts/ensure-plugin-build-deps.mjsnew file mode 100644index 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.jsonindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.tsindex 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.tsnew file mode 100644index 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.tsxindex 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.tsxnew file mode 100644index 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.tsxindex 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 (<divclassName={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 && (<buttontype="button"@@ -245,7 +291,6 @@ export function Layout() {/>)}- {/* Combined sidebar area: company rail + inner sidebar + docs bar */}{isMobile ? (<divclassName={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")}><divclassName={cn(diff --git a/ui/src/components/SidebarProjects.tsx b/ui/src/components/SidebarProjects.tsxindex 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() {<SortableProjectItemkey={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.tsindex 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.tsxindex 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.tsxindex 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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/issuesif (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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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;