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
[codex] Add plugin orchestration host APIs (#4114)
Dotta9c6f55159503
diff --git a/doc/DATABASE.md b/doc/DATABASE.mdindex d2425d14d9..328cdf9fba 100644--- a/doc/DATABASE.md+++ b/doc/DATABASE.md@@ -94,6 +94,16 @@ Set `DATABASE_URL` in your `.env`:DATABASE_URL=postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres```+For hosted deployments that use a pooled runtime URL, set+`DATABASE_MIGRATION_URL` to the direct connection URL. Paperclip uses it for+startup schema checks/migrations and plugin namespace migrations, while the app+continues to use `DATABASE_URL` for runtime queries:++```sh+DATABASE_URL=postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres+DATABASE_MIGRATION_URL=postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres+```+If using connection pooling (port 6543), the `postgres` client must disable prepared statements. Update `packages/db/src/client.ts`:```tsdiff --git a/doc/plugins/PLUGIN_AUTHORING_GUIDE.md b/doc/plugins/PLUGIN_AUTHORING_GUIDE.mdindex 075156fd0f..e3c243783a 100644--- a/doc/plugins/PLUGIN_AUTHORING_GUIDE.md+++ b/doc/plugins/PLUGIN_AUTHORING_GUIDE.md@@ -10,6 +10,9 @@ It is intentionally narrower than [PLUGIN_SPEC.md](./PLUGIN_SPEC.md). The spec i- Plugin UI runs as same-origin JavaScript inside the main Paperclip app.- Worker-side host APIs are capability-gated.- Plugin UI is not sandboxed by manifest capabilities.+- Plugin database migrations are restricted to a host-derived plugin namespace.+- Plugin-owned JSON API routes must be declared in the manifest and are mounted+ only under `/api/plugins/:pluginId/api/*`.- There is no host-provided shared React component kit for plugins yet.- `ctx.assets` is not supported in the current runtime.@@ -77,10 +80,12 @@ Worker:- secrets- activity- state+- database namespace via `ctx.db`+- scoped JSON API routes declared with `apiRoutes`- entities- projects and project workspaces- companies-- issues and comments+- issues, comments, namespaced `plugin:<pluginKey>` origins, blocker relations, checkout assertions, assignment wakeups, and orchestration summaries- agents and agent sessions- goals- data/actions@@ -89,6 +94,55 @@ Worker:- metrics- logger+### Plugin database declarations++First-party or otherwise trusted orchestration plugins can declare:++```ts+database: {+ migrationsDir: "migrations",+ coreReadTables: ["issues"],+}+```++Required capabilities are `database.namespace.migrate` and+`database.namespace.read`; add `database.namespace.write` for runtime mutations.+The host derives `ctx.db.namespace`, runs SQL files in filename order before the+worker starts, records checksums in `plugin_migrations`, and rejects changed+already-applied migrations.++Migration SQL may create or alter objects only inside `ctx.db.namespace`. It may+reference whitelisted `public` core tables for foreign keys or read-only views,+but may not mutate/alter/drop/truncate public tables, create extensions,+triggers, untrusted languages, or runtime multi-statement SQL. Runtime+`ctx.db.query()` is restricted to `SELECT`; runtime `ctx.db.execute()` is+restricted to namespace-local `INSERT`, `UPDATE`, and `DELETE`.++### Scoped plugin API routes++Plugins can expose JSON-only routes under their own namespace:++```ts+apiRoutes: [+ {+ routeKey: "initialize",+ method: "POST",+ path: "/issues/:issueId/smoke",+ auth: "board-or-agent",+ capability: "api.routes.register",+ checkoutPolicy: "required-for-agent-in-progress",+ companyResolution: { from: "issue", param: "issueId" },+ },+]+```++The host resolves the plugin, checks that it is ready, enforces+`api.routes.register`, matches the declared method/path, resolves company access,+and applies checkout policy before dispatching to the worker's `onApiRequest`+handler. The worker receives sanitized headers, route params, query, parsed JSON+body, actor context, and company id. Do not use plugin routes to claim core+paths; they always remain under `/api/plugins/:pluginId/api/*`.+UI:- `usePluginData`diff --git a/doc/plugins/PLUGIN_SPEC.md b/doc/plugins/PLUGIN_SPEC.mdindex f3ec64736b..ed8dea6b2c 100644--- a/doc/plugins/PLUGIN_SPEC.md+++ b/doc/plugins/PLUGIN_SPEC.md@@ -28,6 +28,9 @@ Current limitations to keep in mind:- 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.- The current runtime does not yet ship a real host-provided plugin UI component kit, and it does not support plugin asset uploads/reads. Treat those as future-scope ideas in this spec, not current implementation promises.+- Scoped plugin API routes are JSON-only and must be declared in `apiRoutes`.+ They mount under `/api/plugins/:pluginId/api/*`; plugins cannot shadow core+ API routes.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.@@ -624,7 +627,46 @@ Required SDK clients:Plugins that need filesystem, git, terminal, or process operations handle those directly using standard Node APIs or libraries. The host provides project workspace metadata through `ctx.projects` so plugins can resolve workspace paths, but the host does not proxy low-level OS operations.-## 14.1 Example SDK Shape+## 14.1 Issue Orchestration APIs++Trusted orchestration plugins can create and update Paperclip issues through `ctx.issues` instead of importing server internals. The public issue contract includes parent/project/goal links, board or agent assignees, blocker IDs, labels, billing code, request depth, execution workspace inheritance, and plugin origin metadata.++Origin rules:++- Built-in core issues keep built-in origins such as `manual` and `routine_execution`.+- Plugin-managed issues use `plugin:<pluginKey>` or a sub-kind such as `plugin:<pluginKey>:feature`.+- The host derives the default plugin origin from the installed plugin key and rejects attempts to set `plugin:<otherPluginKey>` origins.+- `originId` is plugin-defined and should be stable for idempotent generated work.++Relation and read helpers:++- `ctx.issues.relations.get(issueId, companyId)`+- `ctx.issues.relations.setBlockedBy(issueId, blockerIssueIds, companyId)`+- `ctx.issues.relations.addBlockers(issueId, blockerIssueIds, companyId)`+- `ctx.issues.relations.removeBlockers(issueId, blockerIssueIds, companyId)`+- `ctx.issues.getSubtree(issueId, companyId, options)`+- `ctx.issues.summaries.getOrchestration({ issueId, companyId, includeSubtree, billingCode })`++Governance helpers:++- `ctx.issues.assertCheckoutOwner({ issueId, companyId, actorAgentId, actorRunId })` lets plugin actions preserve agent-run checkout ownership.+- `ctx.issues.requestWakeup(issueId, companyId, options)` requests assignment wakeups through host heartbeat semantics, including terminal-status, blocker, assignee, and budget hard-stop checks.+- `ctx.issues.requestWakeups(issueIds, companyId, options)` applies the same host-owned wakeup semantics to a batch and may use an idempotency key prefix for stable coordinator retries.++Plugin-originated issue, relation, document, comment, and wakeup mutations must write activity entries with `actorType: "plugin"` and details fields for `sourcePluginId`, `sourcePluginKey`, `initiatingActorType`, `initiatingActorId`, and `initiatingRunId` when a user or agent run initiated the plugin work.++Scoped API routes:++- `apiRoutes[]` declares `routeKey`, `method`, plugin-local `path`, `auth`,+ `capability`, optional checkout policy, and company resolution.+- The host enforces auth, company access, `api.routes.register`, route matching,+ and checkout policy before worker dispatch.+- The worker implements `onApiRequest(input)` and returns a JSON response shape+ `{ status?, headers?, body? }`.+- Only safe request headers are forwarded; auth/cookie headers are never passed+ to the worker.++## 14.2 Example SDK Shape```ts/** Top-level helper for defining a plugin with type checking */@@ -696,16 +738,24 @@ The host enforces capabilities in the SDK layer and refuses calls outside the gr- `project.workspaces.read`- `issues.read`- `issue.comments.read`+- `issue.documents.read`+- `issue.relations.read`+- `issue.subtree.read`- `agents.read`- `goals.read`- `activity.read`- `costs.read`+- `issues.orchestration.read`### Data Write- `issues.create`- `issues.update`- `issue.comments.create`+- `issue.documents.write`+- `issue.relations.write`+- `issues.checkout`+- `issues.wakeup`- `assets.write`- `assets.read`- `activity.log.write`@@ -772,6 +822,13 @@ Minimum event set:- `issue.created`- `issue.updated`- `issue.comment.created`+- `issue.document.created`+- `issue.document.updated`+- `issue.document.deleted`+- `issue.relations.updated`+- `issue.checked_out`+- `issue.released`+- `issue.assignment_wakeup_requested`- `agent.created`- `agent.updated`- `agent.status_changed`@@ -781,6 +838,8 @@ Minimum event set:- `agent.run.cancelled`- `approval.created`- `approval.decided`+- `budget.incident.opened`+- `budget.incident.resolved`- `cost_event.created`- `activity.logged`@@ -1238,6 +1297,8 @@ Plugin-originated mutations should write:- `actor_type = plugin`- `actor_id = <plugin-id>`+- details include `sourcePluginId` and `sourcePluginKey`+- details include `initiatingActorType`, `initiatingActorId`, and `initiatingRunId` when a user or agent run triggered the plugin work## 21.5 Plugin Migrationsdiff --git a/packages/db/src/client.test.ts b/packages/db/src/client.test.tsindex 81cc2acef9..552db3b0d7 100644--- a/packages/db/src/client.test.ts+++ b/packages/db/src/client.test.ts@@ -467,4 +467,78 @@ describeEmbeddedPostgres("applyPendingMigrations", () => {},20_000,);++ it(+ "replays migration 0059 safely when plugin_database_namespaces already exists",+ async () => {+ const connectionString = await createTempDatabase();++ await applyPendingMigrations(connectionString);++ const sql = postgres(connectionString, { max: 1, onnotice: () => {} });+ try {+ const pluginNamespacesHash = await migrationHash(+ "0059_plugin_database_namespaces.sql",+ );++ await sql.unsafe(+ `DELETE FROM "drizzle"."__drizzle_migrations" WHERE hash = '${pluginNamespacesHash}'`,+ );++ const tables = await sql.unsafe<{ table_name: string }[]>(+ `+ SELECT table_name+ FROM information_schema.tables+ WHERE table_schema = 'public'+ AND table_name IN ('plugin_database_namespaces', 'plugin_migrations')+ ORDER BY table_name+ `,+ );+ expect(tables.map((row) => row.table_name)).toEqual([+ "plugin_database_namespaces",+ "plugin_migrations",+ ]);+ } finally {+ await sql.end();+ }++ const pendingState = await inspectMigrations(connectionString);+ expect(pendingState).toMatchObject({+ status: "needsMigrations",+ pendingMigrations: ["0059_plugin_database_namespaces.sql"],+ reason: "pending-migrations",+ });++ await applyPendingMigrations(connectionString);++ const finalState = await inspectMigrations(connectionString);+ expect(finalState.status).toBe("upToDate");++ const verifySql = postgres(connectionString, { max: 1, onnotice: () => {} });+ try {+ const indexes = await verifySql.unsafe<{ indexname: string }[]>(+ `+ SELECT indexname+ FROM pg_indexes+ WHERE schemaname = 'public'+ AND tablename IN ('plugin_database_namespaces', 'plugin_migrations')+ ORDER BY indexname+ `,+ );+ expect(indexes.map((row) => row.indexname)).toEqual(+ expect.arrayContaining([+ "plugin_database_namespaces_namespace_idx",+ "plugin_database_namespaces_plugin_idx",+ "plugin_database_namespaces_status_idx",+ "plugin_migrations_plugin_idx",+ "plugin_migrations_plugin_key_idx",+ "plugin_migrations_status_idx",+ ]),+ );+ } finally {+ await verifySql.end();+ }+ },+ 20_000,+ );});diff --git a/packages/db/src/migrations/0059_plugin_database_namespaces.sql b/packages/db/src/migrations/0059_plugin_database_namespaces.sqlnew file mode 100644index 0000000000..031713b826--- /dev/null+++ b/packages/db/src/migrations/0059_plugin_database_namespaces.sql@@ -0,0 +1,41 @@+CREATE TABLE IF NOT EXISTS "plugin_database_namespaces" (+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,+ "plugin_id" uuid NOT NULL,+ "plugin_key" text NOT NULL,+ "namespace_name" text NOT NULL,+ "namespace_mode" text DEFAULT 'schema' NOT NULL,+ "status" text DEFAULT 'active' 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 IF NOT EXISTS "plugin_migrations" (+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,+ "plugin_id" uuid NOT NULL,+ "plugin_key" text NOT NULL,+ "namespace_name" text NOT NULL,+ "migration_key" text NOT NULL,+ "checksum" text NOT NULL,+ "plugin_version" text NOT NULL,+ "status" text NOT NULL,+ "started_at" timestamp with time zone DEFAULT now() NOT NULL,+ "applied_at" timestamp with time zone,+ "error_message" text+);+--> statement-breakpoint+DO $$ BEGIN+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'plugin_database_namespaces_plugin_id_plugins_id_fk') THEN+ ALTER TABLE "plugin_database_namespaces" ADD CONSTRAINT "plugin_database_namespaces_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;+ END IF;+END $$;--> statement-breakpoint+DO $$ BEGIN+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'plugin_migrations_plugin_id_plugins_id_fk') THEN+ ALTER TABLE "plugin_migrations" ADD CONSTRAINT "plugin_migrations_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE cascade ON UPDATE no action;+ END IF;+END $$;--> statement-breakpoint+CREATE UNIQUE INDEX IF NOT EXISTS "plugin_database_namespaces_plugin_idx" ON "plugin_database_namespaces" USING btree ("plugin_id");--> statement-breakpoint+CREATE UNIQUE INDEX IF NOT EXISTS "plugin_database_namespaces_namespace_idx" ON "plugin_database_namespaces" USING btree ("namespace_name");--> statement-breakpoint+CREATE INDEX IF NOT EXISTS "plugin_database_namespaces_status_idx" ON "plugin_database_namespaces" USING btree ("status");--> statement-breakpoint+CREATE UNIQUE INDEX IF NOT EXISTS "plugin_migrations_plugin_key_idx" ON "plugin_migrations" USING btree ("plugin_id","migration_key");--> statement-breakpoint+CREATE INDEX IF NOT EXISTS "plugin_migrations_plugin_idx" ON "plugin_migrations" USING btree ("plugin_id");--> statement-breakpoint+CREATE INDEX IF NOT EXISTS "plugin_migrations_status_idx" ON "plugin_migrations" USING btree ("status");diff --git a/packages/db/src/migrations/meta/_journal.json b/packages/db/src/migrations/meta/_journal.jsonindex 760e7bc4b7..3a47133a82 100644--- a/packages/db/src/migrations/meta/_journal.json+++ b/packages/db/src/migrations/meta/_journal.json@@ -414,6 +414,13 @@"when": 1776542245004,"tag": "0058_wealthy_starbolt","breakpoints": true+ },+ {+ "idx": 59,+ "version": "7",+ "when": 1776542246000,+ "tag": "0059_plugin_database_namespaces",+ "breakpoints": true}]-}\ No newline at end of file+}diff --git a/packages/db/src/schema/index.ts b/packages/db/src/schema/index.tsindex 4814303cce..54bb5119c7 100644--- a/packages/db/src/schema/index.ts+++ b/packages/db/src/schema/index.ts@@ -60,6 +60,7 @@ 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 { pluginDatabaseNamespaces, pluginMigrations } from "./plugin_database.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_database.ts b/packages/db/src/schema/plugin_database.tsnew file mode 100644index 0000000000..2a279d0771--- /dev/null+++ b/packages/db/src/schema/plugin_database.ts@@ -0,0 +1,75 @@+import {+ pgTable,+ uuid,+ text,+ timestamp,+ index,+ uniqueIndex,+} from "drizzle-orm/pg-core";+import type {+ PluginDatabaseMigrationStatus,+ PluginDatabaseNamespaceMode,+ PluginDatabaseNamespaceStatus,+} from "@paperclipai/shared";+import { plugins } from "./plugins.js";++/**+ * Database namespace allocated to an installed plugin.+ *+ * Namespaces are deterministic and owned by the host. Plugin SQL may create+ * objects only inside its namespace, while selected public core tables remain+ * read-only join targets through runtime checks.+ */+export const pluginDatabaseNamespaces = pgTable(+ "plugin_database_namespaces",+ {+ id: uuid("id").primaryKey().defaultRandom(),+ pluginId: uuid("plugin_id")+ .notNull()+ .references(() => plugins.id, { onDelete: "cascade" }),+ pluginKey: text("plugin_key").notNull(),+ namespaceName: text("namespace_name").notNull(),+ namespaceMode: text("namespace_mode").$type<PluginDatabaseNamespaceMode>().notNull().default("schema"),+ status: text("status").$type<PluginDatabaseNamespaceStatus>().notNull().default("active"),+ createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),+ updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),+ },+ (table) => ({+ pluginIdx: uniqueIndex("plugin_database_namespaces_plugin_idx").on(table.pluginId),+ namespaceIdx: uniqueIndex("plugin_database_namespaces_namespace_idx").on(table.namespaceName),+ statusIdx: index("plugin_database_namespaces_status_idx").on(table.status),+ }),+);++/**+ * Per-plugin migration ledger.+ *+ * Every migration file is recorded with a checksum. A previously applied+ * migration whose checksum changes is rejected during later activation.+ */+export const pluginMigrations = pgTable(+ "plugin_migrations",+ {+ id: uuid("id").primaryKey().defaultRandom(),+ pluginId: uuid("plugin_id")+ .notNull()+ .references(() => plugins.id, { onDelete: "cascade" }),+ pluginKey: text("plugin_key").notNull(),+ namespaceName: text("namespace_name").notNull(),+ migrationKey: text("migration_key").notNull(),+ checksum: text("checksum").notNull(),+ pluginVersion: text("plugin_version").notNull(),+ status: text("status").$type<PluginDatabaseMigrationStatus>().notNull(),+ startedAt: timestamp("started_at", { withTimezone: true }).notNull().defaultNow(),+ appliedAt: timestamp("applied_at", { withTimezone: true }),+ errorMessage: text("error_message"),+ },+ (table) => ({+ pluginMigrationIdx: uniqueIndex("plugin_migrations_plugin_key_idx").on(+ table.pluginId,+ table.migrationKey,+ ),+ pluginIdx: index("plugin_migrations_plugin_idx").on(table.pluginId),+ statusIdx: index("plugin_migrations_status_idx").on(table.status),+ }),+);diff --git a/packages/plugins/examples/plugin-orchestration-smoke-example/.gitignore b/packages/plugins/examples/plugin-orchestration-smoke-example/.gitignorenew file mode 100644index 0000000000..0430cc3560--- /dev/null+++ b/packages/plugins/examples/plugin-orchestration-smoke-example/.gitignore@@ -0,0 +1,3 @@+dist+node_modules+.paperclip-sdkdiff --git a/packages/plugins/examples/plugin-orchestration-smoke-example/README.md b/packages/plugins/examples/plugin-orchestration-smoke-example/README.mdnew file mode 100644index 0000000000..cd4ea091ea--- /dev/null+++ b/packages/plugins/examples/plugin-orchestration-smoke-example/README.md@@ -0,0 +1,48 @@+# Plugin Orchestration Smoke Example++This first-party example validates the orchestration-grade plugin host surface.+It is intentionally small and exists as an acceptance fixture rather than a+product plugin.++## What it exercises++- `apiRoutes` under `/api/plugins/:pluginId/api/*`+- restricted database migrations and runtime `ctx.db`+- plugin-owned rows joined to `public.issues`+- plugin-created child issues with namespaced origin metadata+- billing codes, workspace inheritance, blocker relations, documents, wakeups,+ and orchestration summaries+- issue detail and settings UI slots that surface route, capability, namespace,+ and smoke status++## Development++```bash+pnpm install+pnpm typecheck+pnpm test+pnpm build+```++## Install Into Paperclip++Use an absolute local path during development:++```bash+curl -X POST http://127.0.0.1:3100/api/plugins/install \+ -H "Content-Type: application/json" \+ -d '{"packageName":"/absolute/path/to/paperclip/packages/plugins/examples/plugin-orchestration-smoke-example","isLocalPath":true}'+```++## Scoped Route Smoke++After the plugin is ready, run the scoped route against an existing issue:++```bash+curl -X POST http://127.0.0.1:3100/api/plugins/paperclipai.plugin-orchestration-smoke-example/api/issues/<issue-id>/smoke \+ -H "Content-Type: application/json" \+ -d '{"assigneeAgentId":"<agent-id>"}'+```++The route returns the generated child issue, resolved blocker, billing code,+subtree ids, and wakeup result.diff --git a/packages/plugins/examples/plugin-orchestration-smoke-example/esbuild.config.mjs b/packages/plugins/examples/plugin-orchestration-smoke-example/esbuild.config.mjsnew file mode 100644index 0000000000..b5cfd36ed9--- /dev/null+++ b/packages/plugins/examples/plugin-orchestration-smoke-example/esbuild.config.mjs@@ -0,0 +1,17 @@+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()]);+}diff --git a/packages/plugins/examples/plugin-orchestration-smoke-example/migrations/001_orchestration_smoke.sql b/packages/plugins/examples/plugin-orchestration-smoke-example/migrations/001_orchestration_smoke.sqlnew file mode 100644index 0000000000..6fb6029185--- /dev/null+++ b/packages/plugins/examples/plugin-orchestration-smoke-example/migrations/001_orchestration_smoke.sql@@ -0,0 +1,10 @@+CREATE TABLE plugin_orchestration_smoke_1e8c264c64.smoke_runs (+ id uuid PRIMARY KEY,+ root_issue_id uuid NOT NULL REFERENCES public.issues(id) ON DELETE CASCADE,+ child_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,+ blocker_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,+ billing_code text NOT NULL,+ last_summary jsonb NOT NULL DEFAULT '{}'::jsonb,+ created_at timestamptz NOT NULL DEFAULT now(),+ updated_at timestamptz NOT NULL DEFAULT now()+);diff --git a/packages/plugins/examples/plugin-orchestration-smoke-example/package.json b/packages/plugins/examples/plugin-orchestration-smoke-example/package.jsonnew file mode 100644index 0000000000..fb9985ca3f--- /dev/null+++ b/packages/plugins/examples/plugin-orchestration-smoke-example/package.json@@ -0,0 +1,46 @@+{+ "name": "@paperclipai/plugin-orchestration-smoke-example",+ "version": "0.1.0",+ "type": "module",+ "private": true,+ "description": "First-party smoke plugin for orchestration-grade Paperclip plugin APIs",+ "scripts": {+ "prebuild": "node ../../../../scripts/ensure-plugin-build-deps.mjs",+ "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 --config ./vitest.config.ts",+ "typecheck": "pnpm --filter @paperclipai/plugin-sdk build && tsc --noEmit"+ },+ "paperclipPlugin": {+ "manifest": "./dist/manifest.js",+ "worker": "./dist/worker.js",+ "ui": "./dist/ui/"+ },+ "keywords": [+ "paperclip",+ "plugin",+ "connector"+ ],+ "author": "Paperclip",+ "license": "MIT",+ "dependencies": {+ "@paperclipai/plugin-sdk": "workspace:*"+ },+ "devDependencies": {+ "@paperclipai/shared": "workspace:*",+ "@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"+ }+}diff --git a/packages/plugins/examples/plugin-orchestration-smoke-example/rollup.config.mjs b/packages/plugins/examples/plugin-orchestration-smoke-example/rollup.config.mjsnew file mode 100644index 0000000000..ccee40a744--- /dev/null+++ b/packages/plugins/examples/plugin-orchestration-smoke-example/rollup.config.mjs@@ -0,0 +1,28 @@+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);diff --git a/packages/plugins/examples/plugin-orchestration-smoke-example/src/manifest.ts b/packages/plugins/examples/plugin-orchestration-smoke-example/src/manifest.tsnew file mode 100644index 0000000000..12bf4c2560--- /dev/null+++ b/packages/plugins/examples/plugin-orchestration-smoke-example/src/manifest.ts@@ -0,0 +1,82 @@+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";++const manifest: PaperclipPluginManifestV1 = {+ id: "paperclipai.plugin-orchestration-smoke-example",+ apiVersion: 1,+ version: "0.1.0",+ displayName: "Plugin Orchestration Smoke Example",+ description: "First-party smoke plugin that exercises Paperclip orchestration-grade plugin APIs.",+ author: "Paperclip",+ categories: ["automation", "ui"],+ capabilities: [+ "api.routes.register",+ "database.namespace.migrate",+ "database.namespace.read",+ "database.namespace.write",+ "issues.read",+ "issues.create",+ "issues.wakeup",+ "issue.relations.read",+ "issue.relations.write",+ "issue.documents.read",+ "issue.documents.write",+ "issue.subtree.read",+ "issues.orchestration.read",+ "ui.dashboardWidget.register",+ "ui.detailTab.register",+ "instance.settings.register"+ ],+ entrypoints: {+ worker: "./dist/worker.js",+ ui: "./dist/ui"+ },+ database: {+ namespaceSlug: "orchestration_smoke",+ migrationsDir: "migrations",+ coreReadTables: ["issues"]+ },+ apiRoutes: [+ {+ routeKey: "initialize",+ method: "POST",+ path: "/issues/:issueId/smoke",+ auth: "board-or-agent",+ capability: "api.routes.register",+ checkoutPolicy: "required-for-agent-in-progress",+ companyResolution: { from: "issue", param: "issueId" }+ },+ {+ routeKey: "summary",+ method: "GET",+ path: "/issues/:issueId/smoke",+ auth: "board-or-agent",+ capability: "api.routes.register",+ companyResolution: { from: "issue", param: "issueId" }+ }+ ],+ ui: {+ slots: [+ {+ type: "dashboardWidget",+ id: "health-widget",+ displayName: "Orchestration Smoke Health",+ exportName: "DashboardWidget"+ },+ {+ type: "taskDetailView",+ id: "issue-panel",+ displayName: "Orchestration Smoke",+ exportName: "IssuePanel",+ entityTypes: ["issue"]+ },+ {+ type: "settingsPage",+ id: "settings",+ displayName: "Orchestration Smoke",+ exportName: "SettingsPage"+ }+ ]+ }+};++export default manifest;diff --git a/packages/plugins/examples/plugin-orchestration-smoke-example/src/ui/index.tsx b/packages/plugins/examples/plugin-orchestration-smoke-example/src/ui/index.tsxnew file mode 100644index 0000000000..14075b603a--- /dev/null+++ b/packages/plugins/examples/plugin-orchestration-smoke-example/src/ui/index.tsx@@ -0,0 +1,134 @@+import {+ usePluginAction,+ usePluginData,+ type PluginDetailTabProps,+ type PluginSettingsPageProps,+ type PluginWidgetProps,+} from "@paperclipai/plugin-sdk/ui";+import type React from "react";++type SurfaceStatus = {+ status: "ok" | "degraded" | "error";+ checkedAt: string;+ databaseNamespace: string;+ routeKeys: string[];+ capabilities: string[];+ summary: null | {+ rootIssueId: string;+ childIssueId: string | null;+ blockerIssueId: string | null;+ billingCode: string;+ subtreeIssueIds: string[];+ wakeupQueued: boolean;+ };+};++const panelStyle = {+ display: "grid",+ gap: 10,+ fontSize: 13,+ lineHeight: 1.45,+} satisfies React.CSSProperties;++const rowStyle = {+ display: "flex",+ justifyContent: "space-between",+ gap: 12,+} satisfies React.CSSProperties;++const buttonStyle = {+ border: "1px solid #1f2937",+ background: "#111827",+ color: "#fff",+ borderRadius: 6,+ padding: "6px 10px",+ font: "inherit",+ cursor: "pointer",+} satisfies React.CSSProperties;++function SurfaceRows({ data }: { data: SurfaceStatus }) {+ return (+ <div style={{ display: "grid", gap: 6 }}>+ <div style={rowStyle}><span>Status</span><strong>{data.status}</strong></div>+ <div style={rowStyle}><span>Namespace</span><code>{data.databaseNamespace}</code></div>+ <div style={rowStyle}><span>Routes</span><code>{data.routeKeys.join(", ")}</code></div>+ <div style={rowStyle}><span>Capabilities</span><strong>{data.capabilities.length}</strong></div>+ </div>+ );+}++export function DashboardWidget({ context }: PluginWidgetProps) {+ const { data, loading, error } = usePluginData<SurfaceStatus>("surface-status", {+ companyId: context.companyId,+ });++ if (loading) return <div>Loading orchestration smoke status...</div>;+ if (error) return <div>Orchestration smoke error: {error.message}</div>;+ if (!data) return null;++ return (+ <div style={panelStyle}>+ <strong>Orchestration Smoke</strong>+ <SurfaceRows data={data} />+ <div>Checked {data.checkedAt}</div>+ </div>+ );+}++export function IssuePanel({ context }: PluginDetailTabProps) {+ const { data, loading, error, refresh } = usePluginData<SurfaceStatus>("surface-status", {+ companyId: context.companyId,+ issueId: context.entityId,+ });+ const initialize = usePluginAction("initialize-smoke");++ if (loading) return <div>Loading orchestration smoke...</div>;+ if (error) return <div>Orchestration smoke error: {error.message}</div>;+ if (!data) return null;++ return (+ <div style={panelStyle}>+ <div style={rowStyle}>+ <strong>Orchestration Smoke</strong>+ <button+ style={buttonStyle}+ onClick={async () => {+ await initialize({ companyId: context.companyId, issueId: context.entityId });+ refresh();+ }}+ >+ Run Smoke+ </button>+ </div>+ <SurfaceRows data={data} />+ {data.summary ? (+ <div style={{ display: "grid", gap: 4 }}>+ <div style={rowStyle}><span>Child</span><code>{data.summary.childIssueId ?? "none"}</code></div>+ <div style={rowStyle}><span>Blocker</span><code>{data.summary.blockerIssueId ?? "none"}</code></div>+ <div style={rowStyle}><span>Billing</span><code>{data.summary.billingCode}</code></div>+ <div style={rowStyle}><span>Subtree</span><strong>{data.summary.subtreeIssueIds.length}</strong></div>+ <div style={rowStyle}><span>Wakeup</span><strong>{data.summary.wakeupQueued ? "queued" : "not queued"}</strong></div>+ </div>+ ) : (+ <div>No smoke run recorded for this issue.</div>+ )}+ </div>+ );+}++export function SettingsPage({ context }: PluginSettingsPageProps) {+ const { data, loading, error } = usePluginData<SurfaceStatus>("surface-status", {+ companyId: context.companyId,+ });++ if (loading) return <div>Loading orchestration smoke settings...</div>;+ if (error) return <div>Orchestration smoke settings error: {error.message}</div>;+ if (!data) return null;++ return (+ <div style={panelStyle}>+ <strong>Orchestration Smoke Surface</strong>+ <SurfaceRows data={data} />+ </div>+ );+}diff --git a/packages/plugins/examples/plugin-orchestration-smoke-example/src/worker.ts b/packages/plugins/examples/plugin-orchestration-smoke-example/src/worker.tsnew file mode 100644index 0000000000..e9a567c3db--- /dev/null+++ b/packages/plugins/examples/plugin-orchestration-smoke-example/src/worker.ts@@ -0,0 +1,253 @@+import { randomUUID } from "node:crypto";+import { definePlugin, runWorker, type PluginApiRequestInput } from "@paperclipai/plugin-sdk";++type SmokeInput = {+ companyId: string;+ issueId: string;+ assigneeAgentId?: string | null;+ actorAgentId?: string | null;+ actorUserId?: string | null;+ actorRunId?: string | null;+};++type SmokeSummary = {+ rootIssueId: string;+ childIssueId: string | null;+ blockerIssueId: string | null;+ billingCode: string;+ joinedRows: unknown[];+ subtreeIssueIds: string[];+ wakeupQueued: boolean;+};++let readSmokeSummary: ((companyId: string, issueId: string) => Promise<SmokeSummary | null>) | null = null;+let initializeSmoke: ((input: SmokeInput) => Promise<SmokeSummary>) | null = null;++function tableName(namespace: string) {+ return `${namespace}.smoke_runs`;+}++function stringField(value: unknown): string | null {+ return typeof value === "string" && value.trim().length > 0 ? value : null;+}++const plugin = definePlugin({+ async setup(ctx) {+ readSmokeSummary = async function readSummary(companyId: string, issueId: string): Promise<SmokeSummary | null> {+ const rows = await ctx.db.query<{+ root_issue_id: string;+ child_issue_id: string | null;+ blocker_issue_id: string | null;+ billing_code: string;+ issue_title: string;+ last_summary: unknown;+ }>(+ `SELECT s.root_issue_id, s.child_issue_id, s.blocker_issue_id, s.billing_code, i.title AS issue_title, s.last_summary+ FROM ${tableName(ctx.db.namespace)} s+ JOIN public.issues i ON i.id = s.root_issue_id+ WHERE s.root_issue_id = $1`,+ [issueId],+ );+ const row = rows[0];+ if (!row) return null;+ const orchestration = await ctx.issues.summaries.getOrchestration({+ issueId,+ companyId,+ includeSubtree: true,+ billingCode: row.billing_code,+ });+ return {+ rootIssueId: row.root_issue_id,+ childIssueId: row.child_issue_id,+ blockerIssueId: row.blocker_issue_id,+ billingCode: row.billing_code,+ joinedRows: rows,+ subtreeIssueIds: orchestration.subtreeIssueIds,+ wakeupQueued: Boolean((row.last_summary as { wakeupQueued?: unknown } | null)?.wakeupQueued),+ };+ };++ initializeSmoke = async function runSmoke(input: SmokeInput): Promise<SmokeSummary> {+ const root = await ctx.issues.get(input.issueId, input.companyId);+ if (!root) throw new Error(`Issue not found: ${input.issueId}`);++ const billingCode = `plugin-smoke:${input.issueId}`;+ const actor = {+ actorAgentId: input.actorAgentId ?? null,+ actorUserId: input.actorUserId ?? null,+ actorRunId: input.actorRunId ?? null,+ };+ const blocker = await ctx.issues.create({+ companyId: input.companyId,+ parentId: input.issueId,+ inheritExecutionWorkspaceFromIssueId: input.issueId,+ title: "Orchestration smoke blocker",+ description: "Resolved blocker used to verify plugin relation writes without preventing the smoke wakeup.",+ status: "done",+ priority: "low",+ billingCode,+ originKind: `plugin:${ctx.manifest.id}:blocker`,+ originId: `${input.issueId}:blocker`,+ actor,+ });++ const child = await ctx.issues.create({+ companyId: input.companyId,+ parentId: input.issueId,+ inheritExecutionWorkspaceFromIssueId: input.issueId,+ title: "Orchestration smoke child",+ description: "Generated by the orchestration smoke plugin to verify issue, document, relation, wakeup, and summary APIs.",+ status: "todo",+ priority: "medium",+ assigneeAgentId: input.assigneeAgentId ?? root.assigneeAgentId ?? undefined,+ billingCode,+ originKind: `plugin:${ctx.manifest.id}:child`,+ originId: `${input.issueId}:child`,+ blockedByIssueIds: [blocker.id],+ actor,+ });++ await ctx.issues.relations.setBlockedBy(child.id, [blocker.id], input.companyId, actor);+ await ctx.issues.documents.upsert({+ issueId: child.id,+ companyId: input.companyId,+ key: "orchestration-smoke",+ title: "Orchestration Smoke",+ format: "markdown",+ body: [+ "# Orchestration Smoke",+ "",+ `- Root issue: ${input.issueId}`,+ `- Child issue: ${child.id}`,+ `- Billing code: ${billingCode}`,+ ].join("\n"),+ changeSummary: "Recorded orchestration smoke output",+ });++ const wakeup = await ctx.issues.requestWakeup(child.id, input.companyId, {+ reason: "plugin:orchestration_smoke",+ contextSource: "plugin-orchestration-smoke",+ idempotencyKey: `${input.issueId}:child`,+ ...actor,+ });+ const orchestration = await ctx.issues.summaries.getOrchestration({+ issueId: input.issueId,+ companyId: input.companyId,+ includeSubtree: true,+ billingCode,+ });+ const summarySnapshot = {+ childIssueId: child.id,+ blockerIssueId: blocker.id,+ wakeupQueued: wakeup.queued,+ subtreeIssueIds: orchestration.subtreeIssueIds,+ };++ await ctx.db.execute(+ `INSERT INTO ${tableName(ctx.db.namespace)} (id, root_issue_id, child_issue_id, blocker_issue_id, billing_code, last_summary)+ VALUES ($1, $2, $3, $4, $5, $6::jsonb)+ ON CONFLICT (id) DO UPDATE SET+ child_issue_id = EXCLUDED.child_issue_id,+ blocker_issue_id = EXCLUDED.blocker_issue_id,+ billing_code = EXCLUDED.billing_code,+ last_summary = EXCLUDED.last_summary,+ updated_at = now()`,+ [+ randomUUID(),+ input.issueId,+ child.id,+ blocker.id,+ billingCode,+ JSON.stringify(summarySnapshot),+ ],+ );++ return {+ rootIssueId: input.issueId,+ childIssueId: child.id,+ blockerIssueId: blocker.id,+ billingCode,+ joinedRows: await ctx.db.query(+ `SELECT s.id, s.billing_code, i.title AS root_title+ FROM ${tableName(ctx.db.namespace)} s+ JOIN public.issues i ON i.id = s.root_issue_id+ WHERE s.root_issue_id = $1`,+ [input.issueId],+ ),+ subtreeIssueIds: orchestration.subtreeIssueIds,+ wakeupQueued: wakeup.queued,+ };+ };++ ctx.data.register("surface-status", async (params) => {+ const companyId = stringField(params.companyId);+ const issueId = stringField(params.issueId);+ return {+ status: "ok",+ checkedAt: new Date().toISOString(),+ databaseNamespace: ctx.db.namespace,+ routeKeys: (ctx.manifest.apiRoutes ?? []).map((route) => route.routeKey),+ capabilities: ctx.manifest.capabilities,+ summary: companyId && issueId ? await readSmokeSummary?.(companyId, issueId) ?? null : null,+ };+ });++ ctx.actions.register("initialize-smoke", async (params) => {+ const companyId = stringField(params.companyId);+ const issueId = stringField(params.issueId);+ if (!companyId || !issueId) throw new Error("companyId and issueId are required");+ if (!initializeSmoke) throw new Error("Smoke initializer is not ready");+ return initializeSmoke({+ companyId,+ issueId,+ assigneeAgentId: stringField(params.assigneeAgentId),+ actorAgentId: stringField(params.actorAgentId),+ actorUserId: stringField(params.actorUserId),+ actorRunId: stringField(params.actorRunId),+ });+ });+ },++ async onApiRequest(input: PluginApiRequestInput) {+ if (input.routeKey === "summary") {+ const issueId = input.params.issueId;+ return {+ body: await readSmokeSummary?.(input.companyId, issueId) ?? null,+ };+ }++ if (input.routeKey === "initialize") {+ if (!initializeSmoke) throw new Error("Smoke initializer is not ready");+ const body = input.body as Record<string, unknown> | null;+ return {+ status: 201,+ body: await initializeSmoke({+ companyId: input.companyId,+ issueId: input.params.issueId,+ assigneeAgentId: stringField(body?.assigneeAgentId),+ actorAgentId: input.actor.agentId ?? null,+ actorUserId: input.actor.userId ?? null,+ actorRunId: input.actor.runId ?? null,+ }),+ };+ }++ return {+ status: 404,+ body: { error: `Unknown orchestration smoke route: ${input.routeKey}` },+ };+ },++ async onHealth() {+ return {+ status: "ok",+ message: "Orchestration smoke plugin worker is running",+ details: {+ surfaces: ["database", "scoped-api-route", "issue-panel", "orchestration-apis"],+ },+ };+ }+});++export default plugin;+runWorker(plugin, import.meta.url);diff --git a/packages/plugins/examples/plugin-orchestration-smoke-example/tests/plugin.spec.ts b/packages/plugins/examples/plugin-orchestration-smoke-example/tests/plugin.spec.tsnew file mode 100644index 0000000000..7ac7b8e519--- /dev/null+++ b/packages/plugins/examples/plugin-orchestration-smoke-example/tests/plugin.spec.ts@@ -0,0 +1,162 @@+import { randomUUID } from "node:crypto";+import { describe, expect, it } from "vitest";+import { pluginManifestV1Schema, type Issue } from "@paperclipai/shared";+import { createTestHarness } from "@paperclipai/plugin-sdk/testing";+import manifest from "../src/manifest.js";+import plugin from "../src/worker.js";++function issue(input: Partial<Issue> & Pick<Issue, "id" | "companyId" | "title">): Issue {+ const now = new Date();+ const { id, companyId, title, ...rest } = input;+ return {+ id,+ companyId,+ projectId: null,+ projectWorkspaceId: null,+ goalId: null,+ parentId: null,+ title,+ description: null,+ status: "todo",+ priority: "medium",+ assigneeAgentId: null,+ assigneeUserId: null,+ checkoutRunId: null,+ executionRunId: null,+ executionAgentNameKey: null,+ executionLockedAt: null,+ createdByAgentId: null,+ createdByUserId: null,+ issueNumber: null,+ identifier: null,+ originKind: "manual",+ originId: null,+ originRunId: null,+ requestDepth: 0,+ billingCode: null,+ assigneeAdapterOverrides: null,+ executionWorkspaceId: null,+ executionWorkspacePreference: null,+ executionWorkspaceSettings: null,+ startedAt: null,+ completedAt: null,+ cancelledAt: null,+ hiddenAt: null,+ createdAt: now,+ updatedAt: now,+ ...rest,+ };+}++describe("orchestration smoke plugin", () => {+ it("declares the Phase 1 orchestration surfaces", () => {+ expect(pluginManifestV1Schema.parse(manifest)).toMatchObject({+ id: "paperclipai.plugin-orchestration-smoke-example",+ database: {+ migrationsDir: "migrations",+ coreReadTables: ["issues"],+ },+ apiRoutes: [+ expect.objectContaining({ routeKey: "initialize" }),+ expect.objectContaining({ routeKey: "summary" }),+ ],+ });+ });++ it("creates plugin-owned orchestration rows, issue tree, document, wakeup, and summary reads", async () => {+ const companyId = randomUUID();+ const rootIssueId = randomUUID();+ const agentId = randomUUID();+ const harness = createTestHarness({ manifest });+ harness.seed({+ issues: [+ issue({+ id: rootIssueId,+ companyId,+ title: "Root orchestration issue",+ assigneeAgentId: agentId,+ }),+ ],+ });+ await plugin.definition.setup(harness.ctx);++ const result = await harness.performAction<{+ rootIssueId: string;+ childIssueId: string;+ blockerIssueId: string;+ billingCode: string;+ subtreeIssueIds: string[];+ wakeupQueued: boolean;+ }>("initialize-smoke", {+ companyId,+ issueId: rootIssueId,+ assigneeAgentId: agentId,+ });++ expect(result.rootIssueId).toBe(rootIssueId);+ expect(result.childIssueId).toEqual(expect.any(String));+ expect(result.blockerIssueId).toEqual(expect.any(String));+ expect(result.billingCode).toBe(`plugin-smoke:${rootIssueId}`);+ expect(result.wakeupQueued).toBe(true);+ expect(result.subtreeIssueIds).toEqual(expect.arrayContaining([rootIssueId, result.childIssueId]));+ expect(harness.dbExecutes[0]?.sql).toContain(".smoke_runs");+ expect(harness.dbQueries.some((entry) => entry.sql.includes("JOIN public.issues"))).toBe(true);++ const relations = await harness.ctx.issues.relations.get(result.childIssueId, companyId);+ expect(relations.blockedBy).toEqual([+ expect.objectContaining({+ id: result.blockerIssueId,+ status: "done",+ }),+ ]);+ const docs = await harness.ctx.issues.documents.list(result.childIssueId, companyId);+ expect(docs).toEqual([+ expect.objectContaining({+ key: "orchestration-smoke",+ title: "Orchestration Smoke",+ }),+ ]);+ });++ it("dispatches the scoped API route through the same smoke path", async () => {+ const companyId = randomUUID();+ const rootIssueId = randomUUID();+ const agentId = randomUUID();+ const harness = createTestHarness({ manifest });+ harness.seed({+ issues: [+ issue({+ id: rootIssueId,+ companyId,+ title: "Scoped API root",+ assigneeAgentId: agentId,+ }),+ ],+ });+ await plugin.definition.setup(harness.ctx);++ await expect(plugin.definition.onApiRequest?.({+ routeKey: "initialize",+ method: "POST",+ path: `/issues/${rootIssueId}/smoke`,+ params: { issueId: rootIssueId },+ query: {},+ body: { assigneeAgentId: agentId },+ actor: {+ actorType: "user",+ actorId: "board",+ userId: "board",+ agentId: null,+ runId: null,+ },+ companyId,+ headers: {},+ })).resolves.toMatchObject({+ status: 201,+ body: expect.objectContaining({+ rootIssueId,+ wakeupQueued: true,+ }),+ });+ });+});diff --git a/packages/plugins/examples/plugin-orchestration-smoke-example/tsconfig.json b/packages/plugins/examples/plugin-orchestration-smoke-example/tsconfig.jsonnew file mode 100644index 0000000000..a697519ed9--- /dev/null+++ b/packages/plugins/examples/plugin-orchestration-smoke-example/tsconfig.json@@ -0,0 +1,27 @@+{+ "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": "."+ },+ "include": [+ "src",+ "tests"+ ],+ "exclude": [+ "dist",+ "node_modules"+ ]+}diff --git a/packages/plugins/examples/plugin-orchestration-smoke-example/vitest.config.ts b/packages/plugins/examples/plugin-orchestration-smoke-example/vitest.config.tsnew file mode 100644index 0000000000..649a293ef9--- /dev/null+++ b/packages/plugins/examples/plugin-orchestration-smoke-example/vitest.config.ts@@ -0,0 +1,8 @@+import { defineConfig } from "vitest/config";++export default defineConfig({+ test: {+ include: ["tests/**/*.spec.ts"],+ environment: "node",+ },+});diff --git a/packages/plugins/sdk/README.md b/packages/plugins/sdk/README.mdindex d6424921fa..e785b3eee7 100644--- a/packages/plugins/sdk/README.md+++ b/packages/plugins/sdk/README.md@@ -118,10 +118,13 @@ Subscribe in `setup` with `ctx.events.on(name, handler)` or `ctx.events.on(name,| `project.created`, `project.updated` | project || `project.workspace_created`, `project.workspace_updated`, `project.workspace_deleted` | project_workspace || `issue.created`, `issue.updated`, `issue.comment.created` | issue |+| `issue.document.created`, `issue.document.updated`, `issue.document.deleted` | issue |+| `issue.relations.updated`, `issue.checked_out`, `issue.released`, `issue.assignment_wakeup_requested` | 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 |+| `budget.incident.opened`, `budget.incident.resolved` | budget_incident || `cost_event.created` | cost || `activity.logged` | activity |@@ -301,18 +304,29 @@ Declare in `manifest.capabilities`. Grouped by scope:| | `project.workspaces.read` || | `issues.read` || | `issue.comments.read` |+| | `issue.documents.read` |+| | `issue.relations.read` |+| | `issue.subtree.read` || | `agents.read` || | `goals.read` || | `goals.create` || | `goals.update` || | `activity.read` || | `costs.read` |+| | `issues.orchestration.read` |+| | `database.namespace.read` || | `issues.create` || | `issues.update` |+| | `issues.checkout` |+| | `issues.wakeup` || | `issue.comments.create` |+| | `issue.documents.write` |+| | `issue.relations.write` || | `activity.log.write` || | `metrics.write` || | `telemetry.track` |+| | `database.namespace.migrate` |+| | `database.namespace.write` || **Instance** | `instance.settings.register` || | `plugin.state.read` || | `plugin.state.write` |@@ -320,6 +334,7 @@ Declare in `manifest.capabilities`. Grouped by scope:| | `events.emit` || | `jobs.schedule` || | `webhooks.receive` |+| | `api.routes.register` || | `http.outbound` || | `secrets.read-ref` || **Agent** | `agent.tools.register` |@@ -337,6 +352,144 @@ Declare in `manifest.capabilities`. Grouped by scope:Full list in code: import `PLUGIN_CAPABILITIES` from `@paperclipai/plugin-sdk`.+### Restricted Database Namespace++Trusted orchestration plugins can declare a host-owned PostgreSQL namespace:++```ts+database: {+ migrationsDir: "migrations",+ coreReadTables: ["issues"],+}+```++Declare `database.namespace.migrate` and `database.namespace.read`; add+`database.namespace.write` when the worker needs runtime writes. Migrations run+before worker startup, are checksum-recorded, and may create or alter objects+only inside the plugin namespace. Runtime `ctx.db.query()` allows `SELECT` from+`ctx.db.namespace` plus manifest-whitelisted `public` core tables. Runtime+`ctx.db.execute()` allows `INSERT`, `UPDATE`, and `DELETE` only against the+plugin namespace.++### Scoped API Routes++Manifest-declared `apiRoutes` expose JSON routes under+`/api/plugins/:pluginId/api/*` without letting a plugin claim core paths:++```ts+apiRoutes: [+ {+ routeKey: "initialize",+ method: "POST",+ path: "/issues/:issueId/smoke",+ auth: "board-or-agent",+ capability: "api.routes.register",+ checkoutPolicy: "required-for-agent-in-progress",+ companyResolution: { from: "issue", param: "issueId" },+ },+]+```++Implement `onApiRequest(input)` in the worker to handle the route. The host+performs auth, company access, capability, route matching, and checkout policy+before dispatch. The worker receives route params, query, parsed JSON body,+sanitized headers, actor context, and `companyId`; responses are JSON `{ status?,+headers?, body? }`.++## Issue Orchestration APIs++Workflow plugins can use `ctx.issues` for orchestration-grade issue operations without importing host server internals.++Expanded create/update fields include blockers, billing code, board or agent assignees, labels, namespaced plugin origins, request depth, and safe execution workspace fields:++```ts+const child = await ctx.issues.create({+ companyId,+ parentId: missionIssueId,+ inheritExecutionWorkspaceFromIssueId: missionIssueId,+ title: "Implement feature slice",+ status: "todo",+ assigneeAgentId: workerAgentId,+ billingCode: "mission:alpha",+ originKind: "plugin:paperclip.missions:feature",+ originId: "mission-alpha:feature-1",+ blockedByIssueIds: [planningIssueId],+});+```++If `originKind` is omitted, the host stores `plugin:<pluginKey>`. Plugins may use sub-kinds such as `plugin:<pluginKey>:feature`, but the host rejects attempts to set another plugin's namespace.++Blocker relationships are also exposed as first-class helpers:++```ts+const relations = await ctx.issues.relations.get(child.id, companyId);+await ctx.issues.relations.setBlockedBy(child.id, [planningIssueId], companyId);+await ctx.issues.relations.addBlockers(child.id, [validationIssueId], companyId);+await ctx.issues.relations.removeBlockers(child.id, [planningIssueId], companyId);+```++Subtree reads can include just the issue tree, or compact related data for orchestration dashboards:++```ts+const subtree = await ctx.issues.getSubtree(missionIssueId, companyId, {+ includeRoot: true,+ includeRelations: true,+ includeDocuments: true,+ includeActiveRuns: true,+ includeAssignees: true,+});+```++Agent-run actions can assert checkout ownership before mutating in-progress work:++```ts+await ctx.issues.assertCheckoutOwner({+ issueId,+ companyId,+ actorAgentId: runCtx.agentId,+ actorRunId: runCtx.runId,+});+```++Plugins can request assignment wakeups through the host so budget stops, execution locks, blocker checks, and heartbeat policy still apply:++```ts+await ctx.issues.requestWakeup(child.id, companyId, {+ reason: "mission_advance",+ contextSource: "missions.advance",+});++await ctx.issues.requestWakeups([featureIssueId, validationIssueId], companyId, {+ reason: "mission_advance",+ contextSource: "missions.advance",+ idempotencyKeyPrefix: `mission:${missionIssueId}:advance`,+});+```++Use `ctx.issues.summaries.getOrchestration()` when a workflow needs compact reads across a root issue or subtree:++```ts+const summary = await ctx.issues.summaries.getOrchestration({+ issueId: missionIssueId,+ companyId,+ includeSubtree: true,+ billingCode: "mission:alpha",+});+```++Required capabilities:++| API | Capability |+|-----|------------|+| `ctx.issues.relations.get` | `issue.relations.read` |+| `ctx.issues.relations.setBlockedBy` / `addBlockers` / `removeBlockers` | `issue.relations.write` |+| `ctx.issues.getSubtree` | `issue.subtree.read` |+| `ctx.issues.assertCheckoutOwner` | `issues.checkout` |+| `ctx.issues.requestWakeup` / `requestWakeups` | `issues.wakeup` |+| `ctx.issues.summaries.getOrchestration` | `issues.orchestration.read` |++Plugin-originated mutations are logged with `actorType: "plugin"` and details fields `sourcePluginId`, `sourcePluginKey`, `initiatingActorType`, `initiatingActorId`, and `initiatingRunId` when a user or agent run initiated the plugin work.+## UI quick start```tsxdiff --git a/packages/plugins/sdk/src/define-plugin.ts b/packages/plugins/sdk/src/define-plugin.tsindex 43fefdd281..fc0dd40874 100644--- a/packages/plugins/sdk/src/define-plugin.ts+++ b/packages/plugins/sdk/src/define-plugin.ts@@ -107,6 +107,30 @@ export interface PluginWebhookInput {requestId: string;}+export interface PluginApiRequestInput {+ routeKey: string;+ method: string;+ path: string;+ params: Record<string, string>;+ query: Record<string, string | string[]>;+ body: unknown;+ actor: {+ actorType: "user" | "agent";+ actorId: string;+ agentId?: string | null;+ userId?: string | null;+ runId?: string | null;+ };+ companyId: string;+ headers: Record<string, string>;+}++export interface PluginApiResponse {+ status?: number;+ headers?: Record<string, string>;+ body?: unknown;+}+// ---------------------------------------------------------------------------// Plugin definition// ---------------------------------------------------------------------------@@ -197,6 +221,13 @@ export interface PluginDefinition {* @see PLUGIN_SPEC.md §13.7 — `handleWebhook`*/onWebhook?(input: PluginWebhookInput): Promise<void>;++ /**+ * Called for manifest-declared scoped JSON API routes under+ * `/api/plugins/:pluginId/api/*` after the host has enforced auth, company+ * access, capabilities, and checkout policy.+ */+ onApiRequest?(input: PluginApiRequestInput): Promise<PluginApiResponse>;}// ---------------------------------------------------------------------------diff --git a/packages/plugins/sdk/src/host-client-factory.ts b/packages/plugins/sdk/src/host-client-factory.tsindex 8b98cc87a3..4041745921 100644--- a/packages/plugins/sdk/src/host-client-factory.ts+++ b/packages/plugins/sdk/src/host-client-factory.ts@@ -97,6 +97,13 @@ export interface HostServices {delete(params: WorkerToHostMethods["state.delete"][0]): Promise<void>;};+ /** Provides restricted plugin database namespace methods. */+ db: {+ namespace(params: WorkerToHostMethods["db.namespace"][0]): Promise<WorkerToHostMethods["db.namespace"][1]>;+ query(params: WorkerToHostMethods["db.query"][0]): Promise<WorkerToHostMethods["db.query"][1]>;+ execute(params: WorkerToHostMethods["db.execute"][0]): Promise<WorkerToHostMethods["db.execute"][1]>;+ };+/** Provides `entities.upsert`, `entities.list`. */entities: {upsert(params: WorkerToHostMethods["entities.upsert"][0]): Promise<WorkerToHostMethods["entities.upsert"][1]>;@@ -160,12 +167,21 @@ export interface HostServices {getWorkspaceForIssue(params: WorkerToHostMethods["projects.getWorkspaceForIssue"][0]): Promise<WorkerToHostMethods["projects.getWorkspaceForIssue"][1]>;};- /** Provides `issues.list`, `issues.get`, `issues.create`, `issues.update`, `issues.listComments`, `issues.createComment`. */+ /** Provides issue read/write, relation, checkout, wakeup, summary, comment methods. */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]>;+ getRelations(params: WorkerToHostMethods["issues.relations.get"][0]): Promise<WorkerToHostMethods["issues.relations.get"][1]>;+ setBlockedBy(params: WorkerToHostMethods["issues.relations.setBlockedBy"][0]): Promise<WorkerToHostMethods["issues.relations.setBlockedBy"][1]>;+ addBlockers(params: WorkerToHostMethods["issues.relations.addBlockers"][0]): Promise<WorkerToHostMethods["issues.relations.addBlockers"][1]>;+ removeBlockers(params: WorkerToHostMethods["issues.relations.removeBlockers"][0]): Promise<WorkerToHostMethods["issues.relations.removeBlockers"][1]>;+ assertCheckoutOwner(params: WorkerToHostMethods["issues.assertCheckoutOwner"][0]): Promise<WorkerToHostMethods["issues.assertCheckoutOwner"][1]>;+ getSubtree(params: WorkerToHostMethods["issues.getSubtree"][0]): Promise<WorkerToHostMethods["issues.getSubtree"][1]>;+ requestWakeup(params: WorkerToHostMethods["issues.requestWakeup"][0]): Promise<WorkerToHostMethods["issues.requestWakeup"][1]>;+ requestWakeups(params: WorkerToHostMethods["issues.requestWakeups"][0]): Promise<WorkerToHostMethods["issues.requestWakeups"][1]>;+ getOrchestrationSummary(params: WorkerToHostMethods["issues.summaries.getOrchestration"][0]): Promise<WorkerToHostMethods["issues.summaries.getOrchestration"][1]>;listComments(params: WorkerToHostMethods["issues.listComments"][0]): Promise<WorkerToHostMethods["issues.listComments"][1]>;createComment(params: WorkerToHostMethods["issues.createComment"][0]): Promise<WorkerToHostMethods["issues.createComment"][1]>;};@@ -269,6 +285,10 @@ const METHOD_CAPABILITY_MAP: Record<WorkerToHostMethodName, PluginCapability | n"state.set": "plugin.state.write","state.delete": "plugin.state.write",+ "db.namespace": "database.namespace.read",+ "db.query": "database.namespace.read",+ "db.execute": "database.namespace.write",+// Entities — no specific capability required (plugin-scoped by design)"entities.upsert": null,"entities.list": null,@@ -311,6 +331,15 @@ const METHOD_CAPABILITY_MAP: Record<WorkerToHostMethodName, PluginCapability | n"issues.get": "issues.read","issues.create": "issues.create","issues.update": "issues.update",+ "issues.relations.get": "issue.relations.read",+ "issues.relations.setBlockedBy": "issue.relations.write",+ "issues.relations.addBlockers": "issue.relations.write",+ "issues.relations.removeBlockers": "issue.relations.write",+ "issues.assertCheckoutOwner": "issues.checkout",+ "issues.getSubtree": "issue.subtree.read",+ "issues.requestWakeup": "issues.wakeup",+ "issues.requestWakeups": "issues.wakeup",+ "issues.summaries.getOrchestration": "issues.orchestration.read","issues.listComments": "issue.comments.read","issues.createComment": "issue.comments.create",@@ -419,6 +448,16 @@ export function createHostClientHandlers(return services.state.delete(params);}),+ "db.namespace": gated("db.namespace", async (params) => {+ return services.db.namespace(params);+ }),+ "db.query": gated("db.query", async (params) => {+ return services.db.query(params);+ }),+ "db.execute": gated("db.execute", async (params) => {+ return services.db.execute(params);+ }),+// Entities"entities.upsert": gated("entities.upsert", async (params) => {return services.entities.upsert(params);@@ -503,6 +542,33 @@ export function createHostClientHandlers("issues.update": gated("issues.update", async (params) => {return services.issues.update(params);}),+ "issues.relations.get": gated("issues.relations.get", async (params) => {+ return services.issues.getRelations(params);+ }),+ "issues.relations.setBlockedBy": gated("issues.relations.setBlockedBy", async (params) => {+ return services.issues.setBlockedBy(params);+ }),+ "issues.relations.addBlockers": gated("issues.relations.addBlockers", async (params) => {+ return services.issues.addBlockers(params);+ }),+ "issues.relations.removeBlockers": gated("issues.relations.removeBlockers", async (params) => {+ return services.issues.removeBlockers(params);+ }),+ "issues.assertCheckoutOwner": gated("issues.assertCheckoutOwner", async (params) => {+ return services.issues.assertCheckoutOwner(params);+ }),+ "issues.getSubtree": gated("issues.getSubtree", async (params) => {+ return services.issues.getSubtree(params);+ }),+ "issues.requestWakeup": gated("issues.requestWakeup", async (params) => {+ return services.issues.requestWakeup(params);+ }),+ "issues.requestWakeups": gated("issues.requestWakeups", async (params) => {+ return services.issues.requestWakeups(params);+ }),+ "issues.summaries.getOrchestration": gated("issues.summaries.getOrchestration", async (params) => {+ return services.issues.getOrchestrationSummary(params);+ }),"issues.listComments": gated("issues.listComments", async (params) => {return services.issues.listComments(params);}),diff --git a/packages/plugins/sdk/src/index.ts b/packages/plugins/sdk/src/index.tsindex 69e22c4f11..8232621c4d 100644--- a/packages/plugins/sdk/src/index.ts+++ b/packages/plugins/sdk/src/index.ts@@ -95,6 +95,8 @@ export type {PluginHealthDiagnostics,PluginConfigValidationResult,PluginWebhookInput,+ PluginApiRequestInput,+ PluginApiResponse,} from "./define-plugin.js";export type {TestHarness,@@ -171,6 +173,22 @@ export type {PluginProjectsClient,PluginCompaniesClient,PluginIssuesClient,+ PluginIssueMutationActor,+ PluginIssueRelationsClient,+ PluginIssueRelationSummary,+ PluginIssueCheckoutOwnership,+ PluginIssueWakeupResult,+ PluginIssueWakeupBatchResult,+ PluginIssueRunSummary,+ PluginIssueApprovalSummary,+ PluginIssueCostSummary,+ PluginBudgetIncidentSummary,+ PluginIssueInvocationBlockSummary,+ PluginIssueOrchestrationSummary,+ PluginIssueSubtreeOptions,+ PluginIssueAssigneeSummary,+ PluginIssueSubtree,+ PluginIssueSummariesClient,PluginAgentsClient,PluginAgentSessionsClient,AgentSession,@@ -203,8 +221,10 @@ export type {Project,Issue,IssueComment,+ IssueDocumentSummary,Agent,Goal,+ PluginDatabaseClient,} from "./types.js";// Manifest and constant types re-exported from @paperclipai/shared@@ -221,7 +241,12 @@ export type {PluginLauncherRenderDeclaration,PluginLauncherDeclaration,PluginMinimumHostVersion,+ PluginDatabaseDeclaration,+ PluginApiRouteCompanyResolution,+ PluginApiRouteDeclaration,PluginRecord,+ PluginDatabaseNamespaceRecord,+ PluginMigrationRecord,PluginConfig,JsonSchema,PluginStatus,@@ -238,6 +263,13 @@ export type {PluginJobRunStatus,PluginJobRunTrigger,PluginWebhookDeliveryStatus,+ PluginDatabaseCoreReadTable,+ PluginDatabaseMigrationStatus,+ PluginDatabaseNamespaceMode,+ PluginDatabaseNamespaceStatus,+ PluginApiRouteAuthMode,+ PluginApiRouteCheckoutPolicy,+ PluginApiRouteMethod,PluginEventType,PluginBridgeErrorCode,} from "./types.js";diff --git a/packages/plugins/sdk/src/protocol.ts b/packages/plugins/sdk/src/protocol.tsindex 9d81eb8af7..f96db65bbb 100644--- a/packages/plugins/sdk/src/protocol.ts+++ b/packages/plugins/sdk/src/protocol.ts@@ -34,6 +34,12 @@ export type { PluginLauncherRenderContextSnapshot } from "@paperclipai/shared";import type {PluginEvent,+ PluginIssueCheckoutOwnership,+ PluginIssueOrchestrationSummary,+ PluginIssueRelationSummary,+ PluginIssueSubtree,+ PluginIssueWakeupBatchResult,+ PluginIssueWakeupResult,PluginJobContext,PluginWorkspace,ToolRunContext,@@ -41,6 +47,8 @@ import type {} from "./types.js";import type {PluginHealthDiagnostics,+ PluginApiRequestInput,+ PluginApiResponse,PluginConfigValidationResult,PluginWebhookInput,} from "./define-plugin.js";@@ -219,6 +227,8 @@ export interface InitializeParams {};/** Host API version. */apiVersion: number;+ /** Host-derived plugin database namespace, when the manifest declares database access. */+ databaseNamespace?: string | null;}/**@@ -374,6 +384,8 @@ export interface HostToWorkerMethods {runJob: [params: RunJobParams, result: void];/** @see PLUGIN_SPEC.md §13.7 */handleWebhook: [params: PluginWebhookInput, result: void];+ /** Scoped plugin API route dispatch. */+ handleApiRequest: [params: PluginApiRequestInput, result: PluginApiResponse];/** @see PLUGIN_SPEC.md §13.8 */getData: [params: GetDataParams, result: unknown];/** @see PLUGIN_SPEC.md §13.9 */@@ -399,6 +411,7 @@ export const HOST_TO_WORKER_OPTIONAL_METHODS: readonly HostToWorkerMethodName[]"onEvent","runJob","handleWebhook",+ "handleApiRequest","getData","performAction","executeTool",@@ -432,6 +445,20 @@ export interface WorkerToHostMethods {result: void,];+ // Restricted plugin database namespace+ "db.namespace": [+ params: Record<string, never>,+ result: string,+ ];+ "db.query": [+ params: { sql: string; params?: unknown[] },+ result: unknown[],+ ];+ "db.execute": [+ params: { sql: string; params?: unknown[] },+ result: { rowCount: number },+ ];+// Entities"entities.upsert": [params: {@@ -569,6 +596,8 @@ export interface WorkerToHostMethods {companyId: string;projectId?: string;assigneeAgentId?: string;+ originKind?: string;+ originId?: string;status?: string;limit?: number;offset?: number;@@ -588,8 +617,23 @@ export interface WorkerToHostMethods {inheritExecutionWorkspaceFromIssueId?: string;title: string;description?: string;+ status?: string;priority?: string;assigneeAgentId?: string;+ assigneeUserId?: string | null;+ requestDepth?: number;+ billingCode?: string | null;+ originKind?: string | null;+ originId?: string | null;+ originRunId?: string | null;+ blockedByIssueIds?: string[];+ labelIds?: string[];+ executionWorkspaceId?: string | null;+ executionWorkspacePreference?: string | null;+ executionWorkspaceSettings?: Record<string, unknown> | null;+ actorAgentId?: string | null;+ actorUserId?: string | null;+ actorRunId?: string | null;},result: Issue,];@@ -601,6 +645,99 @@ export interface WorkerToHostMethods {},result: Issue,];+ "issues.relations.get": [+ params: { issueId: string; companyId: string },+ result: PluginIssueRelationSummary,+ ];+ "issues.relations.setBlockedBy": [+ params: {+ issueId: string;+ companyId: string;+ blockedByIssueIds: string[];+ actorAgentId?: string | null;+ actorUserId?: string | null;+ actorRunId?: string | null;+ },+ result: PluginIssueRelationSummary,+ ];+ "issues.relations.addBlockers": [+ params: {+ issueId: string;+ companyId: string;+ blockerIssueIds: string[];+ actorAgentId?: string | null;+ actorUserId?: string | null;+ actorRunId?: string | null;+ },+ result: PluginIssueRelationSummary,+ ];+ "issues.relations.removeBlockers": [+ params: {+ issueId: string;+ companyId: string;+ blockerIssueIds: string[];+ actorAgentId?: string | null;+ actorUserId?: string | null;+ actorRunId?: string | null;+ },+ result: PluginIssueRelationSummary,+ ];+ "issues.assertCheckoutOwner": [+ params: {+ issueId: string;+ companyId: string;+ actorAgentId: string;+ actorRunId: string;+ },+ result: PluginIssueCheckoutOwnership,+ ];+ "issues.getSubtree": [+ params: {+ issueId: string;+ companyId: string;+ includeRoot?: boolean;+ includeRelations?: boolean;+ includeDocuments?: boolean;+ includeActiveRuns?: boolean;+ includeAssignees?: boolean;+ },+ result: PluginIssueSubtree,+ ];+ "issues.requestWakeup": [+ params: {+ issueId: string;+ companyId: string;+ reason?: string;+ contextSource?: string;+ idempotencyKey?: string | null;+ actorAgentId?: string | null;+ actorUserId?: string | null;+ actorRunId?: string | null;+ },+ result: PluginIssueWakeupResult,+ ];+ "issues.requestWakeups": [+ params: {+ issueIds: string[];+ companyId: string;+ reason?: string;+ contextSource?: string;+ idempotencyKeyPrefix?: string | null;+ actorAgentId?: string | null;+ actorUserId?: string | null;+ actorRunId?: string | null;+ },+ result: PluginIssueWakeupBatchResult[],+ ];+ "issues.summaries.getOrchestration": [+ params: {+ issueId: string;+ companyId: string;+ includeSubtree?: boolean;+ billingCode?: string | null;+ },+ result: PluginIssueOrchestrationSummary,+ ];"issues.listComments": [params: { issueId: string; companyId: string },result: IssueComment[],diff --git a/packages/plugins/sdk/src/testing.ts b/packages/plugins/sdk/src/testing.tsindex 41e91d542f..0a04164309 100644--- a/packages/plugins/sdk/src/testing.ts+++ b/packages/plugins/sdk/src/testing.ts@@ -3,10 +3,12 @@ import type {PaperclipPluginManifestV1,PluginCapability,PluginEventType,+ PluginIssueOriginKind,Company,Project,Issue,IssueComment,+ IssueDocument,Agent,Goal,} from "@paperclipai/shared";@@ -72,6 +74,8 @@ export interface TestHarness {activity: Array<{ message: string; entityType?: string; entityId?: string; metadata?: Record<string, unknown> }>;metrics: Array<{ name: string; value: number; tags?: Record<string, string> }>;telemetry: Array<{ eventName: string; dimensions?: Record<string, string | number | boolean> }>;+ dbQueries: Array<{ sql: string; params?: unknown[] }>;+ dbExecutes: Array<{ sql: string; params?: unknown[] }>;}type EventRegistration = {@@ -134,6 +138,8 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {const activity: TestHarness["activity"] = [];const metrics: TestHarness["metrics"] = [];const telemetry: TestHarness["telemetry"] = [];+ const dbQueries: TestHarness["dbQueries"] = [];+ const dbExecutes: TestHarness["dbExecutes"] = [];const state = new Map<string, unknown>();const entities = new Map<string, PluginEntityRecord>();@@ -141,7 +147,9 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {const companies = new Map<string, Company>();const projects = new Map<string, Project>();const issues = new Map<string, Issue>();+ const blockedByIssueIds = new Map<string, string[]>();const issueComments = new Map<string, IssueComment[]>();+ const issueDocuments = new Map<string, IssueDocument>();const agents = new Map<string, Agent>();const goals = new Map<string, Goal>();const projectWorkspaces = new Map<string, PluginWorkspace[]>();@@ -156,6 +164,42 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {const actionHandlers = new Map<string, (params: Record<string, unknown>) => Promise<unknown>>();const toolHandlers = new Map<string, (params: unknown, runCtx: ToolRunContext) => Promise<ToolResult>>();+ function issueRelationSummary(issueId: string) {+ const issue = issues.get(issueId);+ if (!issue) throw new Error(`Issue not found: ${issueId}`);+ const summarize = (candidateId: string) => {+ const related = issues.get(candidateId);+ if (!related || related.companyId !== issue.companyId) return null;+ return {+ id: related.id,+ identifier: related.identifier,+ title: related.title,+ status: related.status,+ priority: related.priority,+ assigneeAgentId: related.assigneeAgentId,+ assigneeUserId: related.assigneeUserId,+ };+ };+ const blockedBy = (blockedByIssueIds.get(issueId) ?? [])+ .map(summarize)+ .filter((value): value is NonNullable<typeof value> => value !== null);+ const blocks = [...blockedByIssueIds.entries()]+ .filter(([, blockers]) => blockers.includes(issueId))+ .map(([blockedIssueId]) => summarize(blockedIssueId))+ .filter((value): value is NonNullable<typeof value> => value !== null);+ return { blockedBy, blocks };+ }++ const defaultPluginOriginKind: PluginIssueOriginKind = `plugin:${manifest.id}`;+ function normalizePluginOriginKind(originKind: unknown = defaultPluginOriginKind): PluginIssueOriginKind {+ if (originKind == null || originKind === "") return defaultPluginOriginKind;+ if (typeof originKind !== "string") throw new Error("Plugin issue originKind must be a string");+ if (originKind === defaultPluginOriginKind || originKind.startsWith(`${defaultPluginOriginKind}:`)) {+ return originKind as PluginIssueOriginKind;+ }+ throw new Error(`Plugin may only use originKind values under ${defaultPluginOriginKind}`);+ }+const ctx: PluginContext = {manifest,config: {@@ -195,6 +239,19 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {launchers.set(launcher.id, launcher);},},+ db: {+ namespace: manifest.database ? `test_${manifest.id.replace(/[^a-z0-9_]+/g, "_")}` : "",+ async query(sql, params) {+ requireCapability(manifest, capabilitySet, "database.namespace.read");+ dbQueries.push({ sql, params });+ return [];+ },+ async execute(sql, params) {+ requireCapability(manifest, capabilitySet, "database.namespace.write");+ dbExecutes.push({ sql, params });+ return { rowCount: 0 };+ },+ },http: {async fetch(url, init) {requireCapability(manifest, capabilitySet, "http.outbound");@@ -338,6 +395,11 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {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?.originKind) {+ if (input.originKind.startsWith("plugin:")) normalizePluginOriginKind(input.originKind);+ out = out.filter((issue) => issue.originKind === input.originKind);+ }+ if (input?.originId) out = out.filter((issue) => issue.originId === input.originId);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);@@ -360,10 +422,10 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {parentId: input.parentId ?? null,title: input.title,description: input.description ?? null,- status: "todo",+ status: input.status ?? "todo",priority: input.priority ?? "medium",assigneeAgentId: input.assigneeAgentId ?? null,- assigneeUserId: null,+ assigneeUserId: input.assigneeUserId ?? null,checkoutRunId: null,executionRunId: null,executionAgentNameKey: null,@@ -372,12 +434,15 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {createdByUserId: null,issueNumber: null,identifier: null,- requestDepth: 0,- billingCode: null,+ originKind: normalizePluginOriginKind(input.originKind),+ originId: input.originId ?? null,+ originRunId: input.originRunId ?? null,+ requestDepth: input.requestDepth ?? 0,+ billingCode: input.billingCode ?? null,assigneeAdapterOverrides: null,- executionWorkspaceId: null,- executionWorkspacePreference: null,- executionWorkspaceSettings: null,+ executionWorkspaceId: input.executionWorkspaceId ?? null,+ executionWorkspacePreference: input.executionWorkspacePreference ?? null,+ executionWorkspaceSettings: input.executionWorkspaceSettings ?? null,startedAt: null,completedAt: null,cancelledAt: null,@@ -386,20 +451,75 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {updatedAt: now,};issues.set(record.id, record);+ if (input.blockedByIssueIds) blockedByIssueIds.set(record.id, [...new Set(input.blockedByIssueIds)]);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 { blockedByIssueIds: nextBlockedByIssueIds, ...issuePatch } = patch;+ if (issuePatch.originKind !== undefined) {+ issuePatch.originKind = normalizePluginOriginKind(issuePatch.originKind);+ }const updated: Issue = {...record,- ...patch,+ ...issuePatch,updatedAt: new Date(),};issues.set(issueId, updated);+ if (nextBlockedByIssueIds !== undefined) {+ blockedByIssueIds.set(issueId, [...new Set(nextBlockedByIssueIds)]);+ }return updated;},+ async assertCheckoutOwner(input) {+ requireCapability(manifest, capabilitySet, "issues.checkout");+ const record = issues.get(input.issueId);+ if (!isInCompany(record, input.companyId)) throw new Error(`Issue not found: ${input.issueId}`);+ if (+ record.status !== "in_progress" ||+ record.assigneeAgentId !== input.actorAgentId ||+ (record.checkoutRunId !== null && record.checkoutRunId !== input.actorRunId)+ ) {+ throw new Error("Issue run ownership conflict");+ }+ return {+ issueId: record.id,+ status: record.status,+ assigneeAgentId: record.assigneeAgentId,+ checkoutRunId: record.checkoutRunId,+ adoptedFromRunId: null,+ };+ },+ async requestWakeup(issueId, companyId) {+ requireCapability(manifest, capabilitySet, "issues.wakeup");+ const record = issues.get(issueId);+ if (!isInCompany(record, companyId)) throw new Error(`Issue not found: ${issueId}`);+ if (!record.assigneeAgentId) throw new Error("Issue has no assigned agent to wake");+ if (["backlog", "done", "cancelled"].includes(record.status)) {+ throw new Error(`Issue is not wakeable in status: ${record.status}`);+ }+ const unresolved = issueRelationSummary(issueId).blockedBy.filter((blocker) => blocker.status !== "done");+ if (unresolved.length > 0) throw new Error("Issue is blocked by unresolved blockers");+ return { queued: true, runId: randomUUID() };+ },+ async requestWakeups(issueIds, companyId) {+ requireCapability(manifest, capabilitySet, "issues.wakeup");+ const results = [];+ for (const issueId of issueIds) {+ const record = issues.get(issueId);+ if (!isInCompany(record, companyId)) throw new Error(`Issue not found: ${issueId}`);+ if (!record.assigneeAgentId) throw new Error("Issue has no assigned agent to wake");+ if (["backlog", "done", "cancelled"].includes(record.status)) {+ throw new Error(`Issue is not wakeable in status: ${record.status}`);+ }+ const unresolved = issueRelationSummary(issueId).blockedBy.filter((blocker) => blocker.status !== "done");+ if (unresolved.length > 0) throw new Error("Issue is blocked by unresolved blockers");+ results.push({ issueId, queued: true, runId: randomUUID() });+ }+ return results;+ },async listComments(issueId, companyId) {requireCapability(manifest, capabilitySet, "issue.comments.read");if (!isInCompany(issues.get(issueId), companyId)) return [];@@ -431,12 +551,14 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {async list(issueId, companyId) {requireCapability(manifest, capabilitySet, "issue.documents.read");if (!isInCompany(issues.get(issueId), companyId)) return [];- return [];+ return [...issueDocuments.values()]+ .filter((document) => document.issueId === issueId && document.companyId === companyId)+ .map(({ body: _body, ...summary }) => summary);},- async get(issueId, _key, companyId) {+ async get(issueId, key, companyId) {requireCapability(manifest, capabilitySet, "issue.documents.read");if (!isInCompany(issues.get(issueId), companyId)) return null;- return null;+ return issueDocuments.get(`${issueId}|${key}`) ?? null;},async upsert(input) {requireCapability(manifest, capabilitySet, "issue.documents.write");@@ -444,7 +566,27 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {if (!isInCompany(parentIssue, input.companyId)) {throw new Error(`Issue not found: ${input.issueId}`);}- throw new Error("documents.upsert is not implemented in test context");+ const now = new Date();+ const existing = issueDocuments.get(`${input.issueId}|${input.key}`);+ const document: IssueDocument = {+ id: existing?.id ?? randomUUID(),+ companyId: input.companyId,+ issueId: input.issueId,+ key: input.key,+ title: input.title ?? existing?.title ?? null,+ format: "markdown",+ latestRevisionId: randomUUID(),+ latestRevisionNumber: (existing?.latestRevisionNumber ?? 0) + 1,+ createdByAgentId: existing?.createdByAgentId ?? null,+ createdByUserId: existing?.createdByUserId ?? null,+ updatedByAgentId: null,+ updatedByUserId: null,+ createdAt: existing?.createdAt ?? now,+ updatedAt: now,+ body: input.body,+ };+ issueDocuments.set(`${input.issueId}|${input.key}`, document);+ return document;},async delete(issueId, _key, companyId) {requireCapability(manifest, capabilitySet, "issue.documents.write");@@ -452,6 +594,104 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {if (!isInCompany(parentIssue, companyId)) {throw new Error(`Issue not found: ${issueId}`);}+ issueDocuments.delete(`${issueId}|${_key}`);+ },+ },+ relations: {+ async get(issueId, companyId) {+ requireCapability(manifest, capabilitySet, "issue.relations.read");+ if (!isInCompany(issues.get(issueId), companyId)) throw new Error(`Issue not found: ${issueId}`);+ return issueRelationSummary(issueId);+ },+ async setBlockedBy(issueId, nextBlockedByIssueIds, companyId) {+ requireCapability(manifest, capabilitySet, "issue.relations.write");+ if (!isInCompany(issues.get(issueId), companyId)) throw new Error(`Issue not found: ${issueId}`);+ blockedByIssueIds.set(issueId, [...new Set(nextBlockedByIssueIds)]);+ return issueRelationSummary(issueId);+ },+ async addBlockers(issueId, blockerIssueIds, companyId) {+ requireCapability(manifest, capabilitySet, "issue.relations.write");+ if (!isInCompany(issues.get(issueId), companyId)) throw new Error(`Issue not found: ${issueId}`);+ const next = new Set(blockedByIssueIds.get(issueId) ?? []);+ for (const blockerIssueId of blockerIssueIds) next.add(blockerIssueId);+ blockedByIssueIds.set(issueId, [...next]);+ return issueRelationSummary(issueId);+ },+ async removeBlockers(issueId, blockerIssueIds, companyId) {+ requireCapability(manifest, capabilitySet, "issue.relations.write");+ if (!isInCompany(issues.get(issueId), companyId)) throw new Error(`Issue not found: ${issueId}`);+ const removals = new Set(blockerIssueIds);+ blockedByIssueIds.set(+ issueId,+ (blockedByIssueIds.get(issueId) ?? []).filter((blockerIssueId) => !removals.has(blockerIssueId)),+ );+ return issueRelationSummary(issueId);+ },+ },+ async getSubtree(issueId, companyId, options) {+ requireCapability(manifest, capabilitySet, "issue.subtree.read");+ const root = issues.get(issueId);+ if (!isInCompany(root, companyId)) throw new Error(`Issue not found: ${issueId}`);+ const includeRoot = options?.includeRoot !== false;+ const allIds = [root.id];+ let frontier = [root.id];+ while (frontier.length > 0) {+ const children = [...issues.values()]+ .filter((issue) => issue.companyId === companyId && frontier.includes(issue.parentId ?? ""))+ .map((issue) => issue.id)+ .filter((id) => !allIds.includes(id));+ allIds.push(...children);+ frontier = children;+ }+ const issueIds = includeRoot ? allIds : allIds.filter((id) => id !== root.id);+ const subtreeIssues = issueIds.map((id) => issues.get(id)).filter((candidate): candidate is Issue => Boolean(candidate));+ return {+ rootIssueId: root.id,+ companyId,+ issueIds,+ issues: subtreeIssues,+ ...(options?.includeRelations+ ? { relations: Object.fromEntries(issueIds.map((id) => [id, issueRelationSummary(id)])) }+ : {}),+ ...(options?.includeDocuments ? { documents: Object.fromEntries(issueIds.map((id) => [id, []])) } : {}),+ ...(options?.includeActiveRuns ? { activeRuns: Object.fromEntries(issueIds.map((id) => [id, []])) } : {}),+ ...(options?.includeAssignees ? { assignees: {} } : {}),+ };+ },+ summaries: {+ async getOrchestration(input) {+ requireCapability(manifest, capabilitySet, "issues.orchestration.read");+ const root = issues.get(input.issueId);+ if (!isInCompany(root, input.companyId)) throw new Error(`Issue not found: ${input.issueId}`);+ const subtreeIssueIds = [root.id];+ if (input.includeSubtree) {+ let frontier = [root.id];+ while (frontier.length > 0) {+ const children = [...issues.values()]+ .filter((issue) => issue.companyId === input.companyId && frontier.includes(issue.parentId ?? ""))+ .map((issue) => issue.id)+ .filter((id) => !subtreeIssueIds.includes(id));+ subtreeIssueIds.push(...children);+ frontier = children;+ }+ }+ return {+ issueId: root.id,+ companyId: input.companyId,+ subtreeIssueIds,+ relations: Object.fromEntries(subtreeIssueIds.map((id) => [id, issueRelationSummary(id)])),+ approvals: [],+ runs: [],+ costs: {+ costCents: 0,+ inputTokens: 0,+ cachedInputTokens: 0,+ outputTokens: 0,+ billingCode: input.billingCode ?? null,+ },+ openBudgetIncidents: [],+ invocationBlocks: [],+ };},},},@@ -660,7 +900,12 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {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.issues ?? []) {+ issues.set(row.id, row);+ if (row.blockedBy) {+ blockedByIssueIds.set(row.id, row.blockedBy.map((blocker) => blocker.id));+ }+ }for (const row of input.issueComments ?? []) {const list = issueComments.get(row.issueId) ?? [];list.push(row);@@ -738,6 +983,8 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {activity,metrics,telemetry,+ dbQueries,+ dbExecutes,};return harness;diff --git a/packages/plugins/sdk/src/types.ts b/packages/plugins/sdk/src/types.tsindex f8a6ca4f9f..4639b73fea 100644--- a/packages/plugins/sdk/src/types.ts+++ b/packages/plugins/sdk/src/types.ts@@ -21,6 +21,8 @@ import type {IssueComment,IssueDocument,IssueDocumentSummary,+ IssueRelationIssueSummary,+ PluginIssueOriginKind,Agent,Goal,} from "@paperclipai/shared";@@ -40,7 +42,12 @@ export type {PluginLauncherRenderDeclaration,PluginLauncherDeclaration,PluginMinimumHostVersion,+ PluginDatabaseDeclaration,+ PluginApiRouteDeclaration,+ PluginApiRouteCompanyResolution,PluginRecord,+ PluginDatabaseNamespaceRecord,+ PluginMigrationRecord,PluginConfig,JsonSchema,PluginStatus,@@ -57,6 +64,13 @@ export type {PluginJobRunStatus,PluginJobRunTrigger,PluginWebhookDeliveryStatus,+ PluginDatabaseCoreReadTable,+ PluginDatabaseMigrationStatus,+ PluginDatabaseNamespaceMode,+ PluginDatabaseNamespaceStatus,+ PluginApiRouteAuthMode,+ PluginApiRouteCheckoutPolicy,+ PluginApiRouteMethod,PluginEventType,PluginBridgeErrorCode,Company,@@ -65,6 +79,8 @@ export type {IssueComment,IssueDocument,IssueDocumentSummary,+ IssueRelationIssueSummary,+ PluginIssueOriginKind,Agent,Goal,} from "@paperclipai/shared";@@ -407,6 +423,17 @@ export interface PluginLaunchersClient {register(launcher: PluginLauncherRegistration): void;}+export interface PluginDatabaseClient {+ /** Host-derived PostgreSQL schema name for this plugin's namespace. */+ namespace: string;++ /** Run a restricted SELECT against the plugin namespace and whitelisted core tables. */+ query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;++ /** Run a restricted INSERT, UPDATE, or DELETE against the plugin namespace. */+ execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }>;+}+/*** `ctx.http` — make outbound HTTP requests.*@@ -867,6 +894,178 @@ export interface PluginIssueDocumentsClient {delete(issueId: string, key: string, companyId: string): Promise<void>;}+export interface PluginIssueMutationActor {+ /** Agent that initiated the plugin operation, when the plugin is acting from an agent run. */+ actorAgentId?: string | null;+ /** Board/user that initiated the plugin operation, when known. */+ actorUserId?: string | null;+ /** Heartbeat run that initiated the operation. Required for checkout-aware agent actions. */+ actorRunId?: string | null;+}++export interface PluginIssueRelationSummary {+ blockedBy: IssueRelationIssueSummary[];+ blocks: IssueRelationIssueSummary[];+}++export interface PluginIssueRelationsClient {+ /** Read blocker relationships for an issue. Requires `issue.relations.read`. */+ get(issueId: string, companyId: string): Promise<PluginIssueRelationSummary>;+ /** Replace the issue's blocked-by relation set. Requires `issue.relations.write`. */+ setBlockedBy(+ issueId: string,+ blockedByIssueIds: string[],+ companyId: string,+ actor?: PluginIssueMutationActor,+ ): Promise<PluginIssueRelationSummary>;+ /** Add one or more blockers while preserving existing blockers. Requires `issue.relations.write`. */+ addBlockers(+ issueId: string,+ blockerIssueIds: string[],+ companyId: string,+ actor?: PluginIssueMutationActor,+ ): Promise<PluginIssueRelationSummary>;+ /** Remove one or more blockers while preserving all other blockers. Requires `issue.relations.write`. */+ removeBlockers(+ issueId: string,+ blockerIssueIds: string[],+ companyId: string,+ actor?: PluginIssueMutationActor,+ ): Promise<PluginIssueRelationSummary>;+}++export interface PluginIssueCheckoutOwnership {+ issueId: string;+ status: Issue["status"];+ assigneeAgentId: string | null;+ checkoutRunId: string | null;+ adoptedFromRunId: string | null;+}++export interface PluginIssueWakeupResult {+ queued: boolean;+ runId: string | null;+}++export interface PluginIssueWakeupBatchResult {+ issueId: string;+ queued: boolean;+ runId: string | null;+}++export interface PluginIssueRunSummary {+ id: string;+ issueId: string | null;+ agentId: string;+ status: string;+ invocationSource: string;+ triggerDetail: string | null;+ startedAt: string | null;+ finishedAt: string | null;+ error: string | null;+ createdAt: string;+}++export interface PluginIssueApprovalSummary {+ issueId: string;+ id: string;+ type: string;+ status: string;+ requestedByAgentId: string | null;+ requestedByUserId: string | null;+ decidedByUserId: string | null;+ decidedAt: string | null;+ createdAt: string;+}++export interface PluginIssueCostSummary {+ costCents: number;+ inputTokens: number;+ cachedInputTokens: number;+ outputTokens: number;+ billingCode: string | null;+}++export interface PluginBudgetIncidentSummary {+ id: string;+ scopeType: string;+ scopeId: string;+ metric: string;+ windowKind: string;+ thresholdType: string;+ amountLimit: number;+ amountObserved: number;+ status: string;+ approvalId: string | null;+ createdAt: string;+}++export interface PluginIssueInvocationBlockSummary {+ issueId: string;+ agentId: string;+ scopeType: "company" | "agent" | "project";+ scopeId: string;+ scopeName: string;+ reason: string;+}++export interface PluginIssueOrchestrationSummary {+ issueId: string;+ companyId: string;+ subtreeIssueIds: string[];+ relations: Record<string, PluginIssueRelationSummary>;+ approvals: PluginIssueApprovalSummary[];+ runs: PluginIssueRunSummary[];+ costs: PluginIssueCostSummary;+ openBudgetIncidents: PluginBudgetIncidentSummary[];+ invocationBlocks: PluginIssueInvocationBlockSummary[];+}++export interface PluginIssueSubtreeOptions {+ /** Include the root issue in the result. Defaults to true. */+ includeRoot?: boolean;+ /** Include blocker relationship summaries keyed by issue ID. */+ includeRelations?: boolean;+ /** Include issue document summaries keyed by issue ID. */+ includeDocuments?: boolean;+ /** Include queued/running heartbeat runs keyed by issue ID. */+ includeActiveRuns?: boolean;+ /** Include assignee summaries keyed by agent ID. */+ includeAssignees?: boolean;+}++export interface PluginIssueAssigneeSummary {+ id: string;+ name: string;+ role: string;+ title: string | null;+ status: Agent["status"];+}++export interface PluginIssueSubtree {+ rootIssueId: string;+ companyId: string;+ issueIds: string[];+ issues: Issue[];+ relations?: Record<string, PluginIssueRelationSummary>;+ documents?: Record<string, IssueDocumentSummary[]>;+ activeRuns?: Record<string, PluginIssueRunSummary[]>;+ assignees?: Record<string, PluginIssueAssigneeSummary>;+}++export interface PluginIssueSummariesClient {+ /**+ * Read the compact orchestration inputs a workflow plugin needs for an+ * issue or issue subtree. Requires `issues.orchestration.read`.+ */+ getOrchestration(input: {+ issueId: string;+ companyId: string;+ includeSubtree?: boolean;+ billingCode?: string | null;+ }): Promise<PluginIssueOrchestrationSummary>;+}+/*** `ctx.issues` — read and mutate issues plus comments.*@@ -874,6 +1073,9 @@ export interface PluginIssueDocumentsClient {* - `issues.read` for read operations* - `issues.create` for create* - `issues.update` for update+ * - `issues.checkout` for checkout ownership assertions+ * - `issues.wakeup` for assignment wakeup requests+ * - `issues.orchestration.read` for orchestration summaries* - `issue.comments.read` for `listComments`* - `issue.comments.create` for `createComment`* - `issue.documents.read` for `documents.list` and `documents.get`@@ -884,6 +1086,8 @@ export interface PluginIssuesClient {companyId: string;projectId?: string;assigneeAgentId?: string;+ originKind?: PluginIssueOriginKind;+ originId?: string;status?: Issue["status"];limit?: number;offset?: number;@@ -897,17 +1101,80 @@ export interface PluginIssuesClient {inheritExecutionWorkspaceFromIssueId?: string;title: string;description?: string;+ status?: Issue["status"];priority?: Issue["priority"];assigneeAgentId?: string;+ assigneeUserId?: string | null;+ requestDepth?: number;+ billingCode?: string | null;+ originKind?: PluginIssueOriginKind;+ originId?: string | null;+ originRunId?: string | null;+ blockedByIssueIds?: string[];+ labelIds?: string[];+ executionWorkspaceId?: string | null;+ executionWorkspacePreference?: string | null;+ executionWorkspaceSettings?: Record<string, unknown> | null;+ actor?: PluginIssueMutationActor;}): Promise<Issue>;update(issueId: string,patch: Partial<Pick<Issue,- "title" | "description" | "status" | "priority" | "assigneeAgentId"- >>,+ | "title"+ | "description"+ | "status"+ | "priority"+ | "assigneeAgentId"+ | "assigneeUserId"+ | "billingCode"+ | "originKind"+ | "originId"+ | "originRunId"+ | "requestDepth"+ | "executionWorkspaceId"+ | "executionWorkspacePreference"+ >> & {+ blockedByIssueIds?: string[];+ labelIds?: string[];+ executionWorkspaceSettings?: Record<string, unknown> | null;+ },companyId: string,+ actor?: PluginIssueMutationActor,): Promise<Issue>;+ assertCheckoutOwner(input: {+ issueId: string;+ companyId: string;+ actorAgentId: string;+ actorRunId: string;+ }): Promise<PluginIssueCheckoutOwnership>;+ /**+ * Read a root issue's descendants with optional relation/document/run/assignee+ * summaries. Requires `issue.subtree.read`.+ */+ getSubtree(+ issueId: string,+ companyId: string,+ options?: PluginIssueSubtreeOptions,+ ): Promise<PluginIssueSubtree>;+ requestWakeup(+ issueId: string,+ companyId: string,+ options?: {+ reason?: string;+ contextSource?: string;+ idempotencyKey?: string | null;+ } & PluginIssueMutationActor,+ ): Promise<PluginIssueWakeupResult>;+ requestWakeups(+ issueIds: string[],+ companyId: string,+ options?: {+ reason?: string;+ contextSource?: string;+ idempotencyKeyPrefix?: string | null;+ } & PluginIssueMutationActor,+ ): Promise<PluginIssueWakeupBatchResult[]>;listComments(issueId: string, companyId: string): Promise<IssueComment[]>;createComment(issueId: string,@@ -917,6 +1184,10 @@ export interface PluginIssuesClient {): Promise<IssueComment>;/** Read and write issue documents. Requires `issue.documents.read` / `issue.documents.write`. */documents: PluginIssueDocumentsClient;+ /** Read and write blocker relationships. */+ relations: PluginIssueRelationsClient;+ /** Read compact orchestration summaries. */+ summaries: PluginIssueSummariesClient;}/**@@ -1138,6 +1409,9 @@ export interface PluginContext {/** Register launcher metadata that the host can surface in plugin UI entry points. */launchers: PluginLaunchersClient;+ /** Restricted plugin-owned database namespace. Requires database namespace capabilities. */+ db: PluginDatabaseClient;+/** Make outbound HTTP requests. Requires `http.outbound`. */http: PluginHttpClient;diff --git a/packages/plugins/sdk/src/worker-rpc-host.ts b/packages/plugins/sdk/src/worker-rpc-host.tsindex 483dbc7082..db3fadb2b9 100644--- a/packages/plugins/sdk/src/worker-rpc-host.ts+++ b/packages/plugins/sdk/src/worker-rpc-host.ts@@ -42,6 +42,7 @@ import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";import type { PaperclipPlugin } from "./define-plugin.js";import type {+ PluginApiRequestInput,PluginHealthDiagnostics,PluginConfigValidationResult,PluginWebhookInput,@@ -250,6 +251,7 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHostlet initialized = false;let manifest: PaperclipPluginManifestV1 | null = null;let currentConfig: Record<string, unknown> = {};+ let databaseNamespace: string | null = null;// Plugin handler registrations (populated during setup())const eventHandlers: EventRegistration[] = [];@@ -416,6 +418,18 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost},},+ db: {+ get namespace() {+ return databaseNamespace ?? "";+ },+ async query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {+ return callHost("db.query", { sql, params }) as Promise<T[]>;+ },+ async execute(sql: string, params?: unknown[]) {+ return callHost("db.execute", { sql, params });+ },+ },+http: {async fetch(url: string, init?: RequestInit): Promise<Response> {const serializedInit: Record<string, unknown> = {};@@ -574,6 +588,8 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHostcompanyId: input.companyId,projectId: input.projectId,assigneeAgentId: input.assigneeAgentId,+ originKind: input.originKind,+ originId: input.originId,status: input.status,limit: input.limit,offset: input.offset,@@ -593,16 +609,78 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHostinheritExecutionWorkspaceFromIssueId: input.inheritExecutionWorkspaceFromIssueId,title: input.title,description: input.description,+ status: input.status,priority: input.priority,assigneeAgentId: input.assigneeAgentId,+ assigneeUserId: input.assigneeUserId,+ requestDepth: input.requestDepth,+ billingCode: input.billingCode,+ originKind: input.originKind,+ originId: input.originId,+ originRunId: input.originRunId,+ blockedByIssueIds: input.blockedByIssueIds,+ labelIds: input.labelIds,+ executionWorkspaceId: input.executionWorkspaceId,+ executionWorkspacePreference: input.executionWorkspacePreference,+ executionWorkspaceSettings: input.executionWorkspaceSettings,+ actorAgentId: input.actor?.actorAgentId,+ actorUserId: input.actor?.actorUserId,+ actorRunId: input.actor?.actorRunId,});},- async update(issueId: string, patch, companyId: string) {+ async update(issueId: string, patch, companyId: string, actor) {return callHost("issues.update", {issueId,- patch: patch as Record<string, unknown>,+ patch: {+ ...(patch as Record<string, unknown>),+ actorAgentId: actor?.actorAgentId,+ actorUserId: actor?.actorUserId,+ actorRunId: actor?.actorRunId,+ },+ companyId,+ });+ },++ async assertCheckoutOwner(input) {+ return callHost("issues.assertCheckoutOwner", input);+ },++ async getSubtree(issueId: string, companyId: string, options) {+ return callHost("issues.getSubtree", {+ issueId,+ companyId,+ includeRoot: options?.includeRoot,+ includeRelations: options?.includeRelations,+ includeDocuments: options?.includeDocuments,+ includeActiveRuns: options?.includeActiveRuns,+ includeAssignees: options?.includeAssignees,+ });+ },++ async requestWakeup(issueId: string, companyId: string, options) {+ return callHost("issues.requestWakeup", {+ issueId,+ companyId,+ reason: options?.reason,+ contextSource: options?.contextSource,+ idempotencyKey: options?.idempotencyKey,+ actorAgentId: options?.actorAgentId,+ actorUserId: options?.actorUserId,+ actorRunId: options?.actorRunId,+ });+ },++ async requestWakeups(issueIds: string[], companyId: string, options) {+ return callHost("issues.requestWakeups", {+ issueIds,companyId,+ reason: options?.reason,+ contextSource: options?.contextSource,+ idempotencyKeyPrefix: options?.idempotencyKeyPrefix,+ actorAgentId: options?.actorAgentId,+ actorUserId: options?.actorUserId,+ actorRunId: options?.actorRunId,});},@@ -639,6 +717,51 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHostreturn callHost("issues.documents.delete", { issueId, key, companyId });},},++ relations: {+ async get(issueId: string, companyId: string) {+ return callHost("issues.relations.get", { issueId, companyId });+ },++ async setBlockedBy(issueId: string, blockedByIssueIds: string[], companyId: string, actor) {+ return callHost("issues.relations.setBlockedBy", {+ issueId,+ companyId,+ blockedByIssueIds,+ actorAgentId: actor?.actorAgentId,+ actorUserId: actor?.actorUserId,+ actorRunId: actor?.actorRunId,+ });+ },++ async addBlockers(issueId: string, blockerIssueIds: string[], companyId: string, actor) {+ return callHost("issues.relations.addBlockers", {+ issueId,+ companyId,+ blockerIssueIds,+ actorAgentId: actor?.actorAgentId,+ actorUserId: actor?.actorUserId,+ actorRunId: actor?.actorRunId,+ });+ },++ async removeBlockers(issueId: string, blockerIssueIds: string[], companyId: string, actor) {+ return callHost("issues.relations.removeBlockers", {+ issueId,+ companyId,+ blockerIssueIds,+ actorAgentId: actor?.actorAgentId,+ actorUserId: actor?.actorUserId,+ actorRunId: actor?.actorRunId,+ });+ },+ },++ summaries: {+ async getOrchestration(input) {+ return callHost("issues.summaries.getOrchestration", input);+ },+ },},agents: {@@ -879,6 +1002,9 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHostcase "handleWebhook":return handleWebhook(params as PluginWebhookInput);+ case "handleApiRequest":+ return handleApiRequest(params as PluginApiRequestInput);+case "getData":return handleGetData(params as GetDataParams);@@ -907,6 +1033,7 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHostmanifest = params.manifest;currentConfig = params.config;+ databaseNamespace = params.databaseNamespace ?? null;// Call the plugin's setup functionawait plugin.definition.setup(ctx);@@ -919,6 +1046,7 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHostif (plugin.definition.onConfigChanged) supportedMethods.push("configChanged");if (plugin.definition.onHealth) supportedMethods.push("health");if (plugin.definition.onShutdown) supportedMethods.push("shutdown");+ if (plugin.definition.onApiRequest) supportedMethods.push("handleApiRequest");return { ok: true, supportedMethods };}@@ -1020,6 +1148,16 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHostawait plugin.definition.onWebhook(params);}+ async function handleApiRequest(params: PluginApiRequestInput): Promise<unknown> {+ if (!plugin.definition.onApiRequest) {+ throw Object.assign(+ new Error("handleApiRequest is not implemented by this plugin"),+ { code: PLUGIN_RPC_ERROR_CODES.METHOD_NOT_IMPLEMENTED },+ );+ }+ return plugin.definition.onApiRequest(params);+ }+async function handleGetData(params: GetDataParams): Promise<unknown> {const handler = dataHandlers.get(params.key);if (!handler) {diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.tsindex 8b74632fdd..035e7bb7ed 100644--- a/packages/shared/src/constants.ts+++ b/packages/shared/src/constants.ts@@ -138,7 +138,9 @@ export const ISSUE_PRIORITIES = ["critical", "high", "medium", "low"] as const;export type IssuePriority = (typeof ISSUE_PRIORITIES)[number];export const ISSUE_ORIGIN_KINDS = ["manual", "routine_execution"] as const;-export type IssueOriginKind = (typeof ISSUE_ORIGIN_KINDS)[number];+export type BuiltInIssueOriginKind = (typeof ISSUE_ORIGIN_KINDS)[number];+export type PluginIssueOriginKind = `plugin:${string}`;+export type IssueOriginKind = BuiltInIssueOriginKind | PluginIssueOriginKind;export const ISSUE_RELATION_TYPES = ["blocks"] as const;export type IssueRelationType = (typeof ISSUE_RELATION_TYPES)[number];@@ -498,6 +500,8 @@ export const PLUGIN_CAPABILITIES = ["projects.read","project.workspaces.read","issues.read",+ "issue.relations.read",+ "issue.subtree.read","issue.comments.read","issue.documents.read","agents.read",@@ -506,9 +510,14 @@ export const PLUGIN_CAPABILITIES = ["goals.update","activity.read","costs.read",+ "issues.orchestration.read",+ "database.namespace.read",// Data Write"issues.create","issues.update",+ "issue.relations.write",+ "issues.checkout",+ "issues.wakeup","issue.comments.create","issue.documents.write","agents.pause",@@ -521,6 +530,8 @@ export const PLUGIN_CAPABILITIES = ["activity.log.write","metrics.write","telemetry.track",+ "database.namespace.migrate",+ "database.namespace.write",// Plugin State"plugin.state.read","plugin.state.write",@@ -529,6 +540,7 @@ export const PLUGIN_CAPABILITIES = ["events.emit","jobs.schedule","webhooks.receive",+ "api.routes.register","http.outbound","secrets.read-ref",// Agent Tools@@ -544,6 +556,51 @@ export const PLUGIN_CAPABILITIES = [] as const;export type PluginCapability = (typeof PLUGIN_CAPABILITIES)[number];+export const PLUGIN_DATABASE_NAMESPACE_MODES = ["schema"] as const;+export type PluginDatabaseNamespaceMode = (typeof PLUGIN_DATABASE_NAMESPACE_MODES)[number];++export const PLUGIN_DATABASE_NAMESPACE_STATUSES = [+ "active",+ "migration_failed",+] as const;+export type PluginDatabaseNamespaceStatus = (typeof PLUGIN_DATABASE_NAMESPACE_STATUSES)[number];++export const PLUGIN_DATABASE_MIGRATION_STATUSES = [+ "applied",+ "failed",+] as const;+export type PluginDatabaseMigrationStatus = (typeof PLUGIN_DATABASE_MIGRATION_STATUSES)[number];++export const PLUGIN_DATABASE_CORE_READ_TABLES = [+ "companies",+ "projects",+ "goals",+ "agents",+ "issues",+ "issue_documents",+ "issue_relations",+ "issue_comments",+ "heartbeat_runs",+ "cost_events",+ "approvals",+ "issue_approvals",+ "budget_incidents",+] as const;+export type PluginDatabaseCoreReadTable = (typeof PLUGIN_DATABASE_CORE_READ_TABLES)[number];++export const PLUGIN_API_ROUTE_METHODS = ["GET", "POST", "PATCH", "DELETE"] as const;+export type PluginApiRouteMethod = (typeof PLUGIN_API_ROUTE_METHODS)[number];++export const PLUGIN_API_ROUTE_AUTH_MODES = ["board", "agent", "board-or-agent", "webhook"] as const;+export type PluginApiRouteAuthMode = (typeof PLUGIN_API_ROUTE_AUTH_MODES)[number];++export const PLUGIN_API_ROUTE_CHECKOUT_POLICIES = [+ "none",+ "required-for-agent-in-progress",+ "always-for-agent",+] as const;+export type PluginApiRouteCheckoutPolicy = (typeof PLUGIN_API_ROUTE_CHECKOUT_POLICIES)[number];+/*** UI extension slot types. Each slot type corresponds to a mount point in the* Paperclip UI where plugin components can be rendered.@@ -742,6 +799,13 @@ export const PLUGIN_EVENT_TYPES = ["issue.created","issue.updated","issue.comment.created",+ "issue.document.created",+ "issue.document.updated",+ "issue.document.deleted",+ "issue.relations.updated",+ "issue.checked_out",+ "issue.released",+ "issue.assignment_wakeup_requested","agent.created","agent.updated","agent.status_changed",@@ -753,6 +817,8 @@ export const PLUGIN_EVENT_TYPES = ["goal.updated","approval.created","approval.decided",+ "budget.incident.opened",+ "budget.incident.resolved","cost_event.created","activity.logged",] as const;diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.tsindex dc8562926d..bddbb76949 100644--- a/packages/shared/src/index.ts+++ b/packages/shared/src/index.ts@@ -83,6 +83,13 @@ export {PLUGIN_JOB_RUN_STATUSES,PLUGIN_JOB_RUN_TRIGGERS,PLUGIN_WEBHOOK_DELIVERY_STATUSES,+ PLUGIN_DATABASE_NAMESPACE_MODES,+ PLUGIN_DATABASE_NAMESPACE_STATUSES,+ PLUGIN_DATABASE_MIGRATION_STATUSES,+ PLUGIN_DATABASE_CORE_READ_TABLES,+ PLUGIN_API_ROUTE_METHODS,+ PLUGIN_API_ROUTE_AUTH_MODES,+ PLUGIN_API_ROUTE_CHECKOUT_POLICIES,PLUGIN_EVENT_TYPES,PLUGIN_BRIDGE_ERROR_CODES,type CompanyStatus,@@ -96,6 +103,8 @@ export {type AgentIconName,type IssueStatus,type IssuePriority,+ type BuiltInIssueOriginKind,+ type PluginIssueOriginKind,type IssueOriginKind,type IssueRelationType,type SystemIssueDocumentKey,@@ -159,6 +168,13 @@ export {type PluginJobRunStatus,type PluginJobRunTrigger,type PluginWebhookDeliveryStatus,+ type PluginDatabaseNamespaceMode,+ type PluginDatabaseNamespaceStatus,+ type PluginDatabaseMigrationStatus,+ type PluginDatabaseCoreReadTable,+ type PluginApiRouteMethod,+ type PluginApiRouteAuthMode,+ type PluginApiRouteCheckoutPolicy,type PluginEventType,type PluginBridgeErrorCode,} from "./constants.js";@@ -397,8 +413,13 @@ export type {PluginLauncherDeclaration,PluginMinimumHostVersion,PluginUiDeclaration,+ PluginDatabaseDeclaration,+ PluginApiRouteCompanyResolution,+ PluginApiRouteDeclaration,PaperclipPluginManifestV1,PluginRecord,+ PluginDatabaseNamespaceRecord,+ PluginMigrationRecord,PluginStateRecord,PluginConfig,PluginEntityRecord,@@ -677,6 +698,8 @@ export {pluginLauncherActionDeclarationSchema,pluginLauncherRenderDeclarationSchema,pluginLauncherDeclarationSchema,+ pluginDatabaseDeclarationSchema,+ pluginApiRouteDeclarationSchema,pluginManifestV1Schema,installPluginSchema,upsertPluginConfigSchema,@@ -693,6 +716,8 @@ export {type PluginLauncherActionDeclarationInput,type PluginLauncherRenderDeclarationInput,type PluginLauncherDeclarationInput,+ type PluginDatabaseDeclarationInput,+ type PluginApiRouteDeclarationInput,type PluginManifestV1Input,type InstallPlugin,type UpsertPluginConfig,diff --git a/packages/shared/src/types/activity.ts b/packages/shared/src/types/activity.tsindex d0232e0090..3bc098b663 100644--- a/packages/shared/src/types/activity.ts+++ b/packages/shared/src/types/activity.ts@@ -1,7 +1,7 @@export interface ActivityEvent {id: string;companyId: string;- actorType: "agent" | "user" | "system";+ actorType: "agent" | "user" | "system" | "plugin";actorId: string;action: string;entityType: string;diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.tsindex 600d97a80b..971bf14faf 100644--- a/packages/shared/src/types/index.ts+++ b/packages/shared/src/types/index.ts@@ -244,8 +244,13 @@ export type {PluginLauncherDeclaration,PluginMinimumHostVersion,PluginUiDeclaration,+ PluginDatabaseDeclaration,+ PluginApiRouteCompanyResolution,+ PluginApiRouteDeclaration,PaperclipPluginManifestV1,PluginRecord,+ PluginDatabaseNamespaceRecord,+ PluginMigrationRecord,PluginStateRecord,PluginConfig,PluginEntityRecord,@@ -253,4 +258,8 @@ export type {PluginJobRecord,PluginJobRunRecord,PluginWebhookDeliveryRecord,+ PluginDatabaseCoreReadTable,+ PluginDatabaseMigrationStatus,+ PluginDatabaseNamespaceMode,+ PluginDatabaseNamespaceStatus,} from "./plugin.js";diff --git a/packages/shared/src/types/plugin.ts b/packages/shared/src/types/plugin.tsindex 5117b501ff..74fdd83d97 100644--- a/packages/shared/src/types/plugin.ts+++ b/packages/shared/src/types/plugin.ts@@ -9,6 +9,13 @@ import type {PluginLauncherAction,PluginLauncherBounds,PluginLauncherRenderEnvironment,+ PluginApiRouteAuthMode,+ PluginApiRouteCheckoutPolicy,+ PluginApiRouteMethod,+ PluginDatabaseCoreReadTable,+ PluginDatabaseMigrationStatus,+ PluginDatabaseNamespaceMode,+ PluginDatabaseNamespaceStatus,} from "../constants.js";// ---------------------------------------------------------------------------@@ -21,6 +28,13 @@ import type {*/export type JsonSchema = Record<string, unknown>;+export type {+ PluginDatabaseCoreReadTable,+ PluginDatabaseMigrationStatus,+ PluginDatabaseNamespaceMode,+ PluginDatabaseNamespaceStatus,+} from "../constants.js";+// ---------------------------------------------------------------------------// Manifest sub-types — nested declarations within PaperclipPluginManifestV1// ---------------------------------------------------------------------------@@ -190,6 +204,44 @@ export interface PluginUiDeclaration {launchers?: PluginLauncherDeclaration[];}+/**+ * Declares restricted database access for trusted orchestration plugins.+ *+ * The host derives the final namespace from the plugin key and optional slug,+ * applies SQL migrations before worker startup, and gates runtime SQL through+ * the `database.namespace.*` capabilities.+ */+export interface PluginDatabaseDeclaration {+ /** Optional stable human-readable slug included in the host-derived namespace. */+ namespaceSlug?: string;+ /** SQL migration directory relative to the plugin package root. */+ migrationsDir: string;+ /** Public core tables this plugin may read or join at runtime. */+ coreReadTables?: PluginDatabaseCoreReadTable[];+}++export type PluginApiRouteCompanyResolution =+ | { from: "body"; key: string }+ | { from: "query"; key: string }+ | { from: "issue"; param: string };++export interface PluginApiRouteDeclaration {+ /** Stable plugin-defined route key passed to the worker. */+ routeKey: string;+ /** HTTP method accepted by this route. */+ method: PluginApiRouteMethod;+ /** Plugin-local path under `/api/plugins/:pluginId/api`, e.g. `/issues/:issueId/smoke`. */+ path: string;+ /** Actor class allowed to call the route. */+ auth: PluginApiRouteAuthMode;+ /** Capability required to expose the route. Currently `api.routes.register`. */+ capability: "api.routes.register";+ /** Optional checkout policy enforced by the host before worker dispatch. */+ checkoutPolicy?: PluginApiRouteCheckoutPolicy;+ /** How the host resolves company access for this route. */+ companyResolution?: PluginApiRouteCompanyResolution;+}+// ---------------------------------------------------------------------------// Plugin Manifest V1// ---------------------------------------------------------------------------@@ -240,6 +292,10 @@ export interface PaperclipPluginManifestV1 {webhooks?: PluginWebhookDeclaration[];/** Agent tools this plugin contributes. Requires `agent.tools.register` capability. */tools?: PluginToolDeclaration[];+ /** Restricted plugin-owned database namespace declaration. */+ database?: PluginDatabaseDeclaration;+ /** Scoped JSON API routes mounted under `/api/plugins/:pluginId/api/*`. */+ apiRoutes?: PluginApiRouteDeclaration[];/*** Legacy top-level launcher declarations.* Prefer `ui.launchers` for new manifests.@@ -286,6 +342,31 @@ export interface PluginRecord {updatedAt: Date;}+export interface PluginDatabaseNamespaceRecord {+ id: string;+ pluginId: string;+ pluginKey: string;+ namespaceName: string;+ namespaceMode: PluginDatabaseNamespaceMode;+ status: PluginDatabaseNamespaceStatus;+ createdAt: Date;+ updatedAt: Date;+}++export interface PluginMigrationRecord {+ id: string;+ pluginId: string;+ pluginKey: string;+ namespaceName: string;+ migrationKey: string;+ checksum: string;+ pluginVersion: string;+ status: PluginDatabaseMigrationStatus;+ startedAt: Date;+ appliedAt: Date | null;+ errorMessage: string | null;+}+// ---------------------------------------------------------------------------// Plugin State – represents a row in the `plugin_state` table// ---------------------------------------------------------------------------diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.tsindex 4a2a42321d..997203890e 100644--- a/packages/shared/src/validators/index.ts+++ b/packages/shared/src/validators/index.ts@@ -299,6 +299,8 @@ export {pluginLauncherActionDeclarationSchema,pluginLauncherRenderDeclarationSchema,pluginLauncherDeclarationSchema,+ pluginDatabaseDeclarationSchema,+ pluginApiRouteDeclarationSchema,pluginManifestV1Schema,installPluginSchema,upsertPluginConfigSchema,@@ -315,6 +317,8 @@ export {type PluginLauncherActionDeclarationInput,type PluginLauncherRenderDeclarationInput,type PluginLauncherDeclarationInput,+ type PluginDatabaseDeclarationInput,+ type PluginApiRouteDeclarationInput,type PluginManifestV1Input,type InstallPlugin,type UpsertPluginConfig,diff --git a/packages/shared/src/validators/plugin.ts b/packages/shared/src/validators/plugin.tsindex 92438fb9c0..b4c561b120 100644--- a/packages/shared/src/validators/plugin.ts+++ b/packages/shared/src/validators/plugin.ts@@ -11,6 +11,10 @@ import {PLUGIN_LAUNCHER_BOUNDS,PLUGIN_LAUNCHER_RENDER_ENVIRONMENTS,PLUGIN_STATE_SCOPE_KINDS,+ PLUGIN_DATABASE_CORE_READ_TABLES,+ PLUGIN_API_ROUTE_AUTH_MODES,+ PLUGIN_API_ROUTE_CHECKOUT_POLICIES,+ PLUGIN_API_ROUTE_METHODS,} from "../constants.js";// ---------------------------------------------------------------------------@@ -336,6 +340,48 @@ export const pluginLauncherDeclarationSchema = z.object({export type PluginLauncherDeclarationInput = z.infer<typeof pluginLauncherDeclarationSchema>;+export const pluginDatabaseDeclarationSchema = z.object({+ namespaceSlug: z.string().regex(/^[a-z0-9][a-z0-9_]*$/, {+ message: "namespaceSlug must be lowercase letters, digits, or underscores and start with a letter or digit",+ }).max(40).optional(),+ migrationsDir: z.string().min(1).refine(+ (value) => !value.startsWith("/") && !value.includes("..") && !/[\\]/.test(value),+ { message: "migrationsDir must be a relative package path without '..' or backslashes" },+ ),+ coreReadTables: z.array(z.enum(PLUGIN_DATABASE_CORE_READ_TABLES)).optional(),+});++export type PluginDatabaseDeclarationInput = z.infer<typeof pluginDatabaseDeclarationSchema>;++export const pluginApiRouteDeclarationSchema = z.object({+ routeKey: z.string().min(1).max(100).regex(/^[a-z0-9][a-z0-9._:-]*$/, {+ message: "routeKey must be lowercase letters, digits, dots, colons, underscores, or hyphens",+ }),+ method: z.enum(PLUGIN_API_ROUTE_METHODS),+ path: z.string().min(1).regex(/^\/[a-zA-Z0-9:_./-]*$/, {+ message: "path must start with / and contain only path-safe literal or :param segments",+ }).refine(+ (value) =>+ !value.includes("..") &&+ !value.includes("//") &&+ value !== "/api" &&+ !value.startsWith("/api/") &&+ value !== "/plugins" &&+ !value.startsWith("/plugins/"),+ { message: "path must stay inside the plugin api namespace" },+ ),+ auth: z.enum(PLUGIN_API_ROUTE_AUTH_MODES),+ capability: z.literal("api.routes.register"),+ checkoutPolicy: z.enum(PLUGIN_API_ROUTE_CHECKOUT_POLICIES).optional(),+ companyResolution: z.discriminatedUnion("from", [+ z.object({ from: z.literal("body"), key: z.string().min(1) }),+ z.object({ from: z.literal("query"), key: z.string().min(1) }),+ z.object({ from: z.literal("issue"), param: z.string().min(1) }),+ ]).optional(),+});++export type PluginApiRouteDeclarationInput = z.infer<typeof pluginApiRouteDeclarationSchema>;+// ---------------------------------------------------------------------------// Plugin Manifest V1 schema// ---------------------------------------------------------------------------@@ -405,6 +451,8 @@ export const pluginManifestV1Schema = z.object({jobs: z.array(pluginJobDeclarationSchema).optional(),webhooks: z.array(pluginWebhookDeclarationSchema).optional(),tools: z.array(pluginToolDeclarationSchema).optional(),+ database: pluginDatabaseDeclarationSchema.optional(),+ apiRoutes: z.array(pluginApiRouteDeclarationSchema).optional(),launchers: z.array(pluginLauncherDeclarationSchema).optional(),ui: z.object({slots: z.array(pluginUiSlotDeclarationSchema).min(1).optional(),@@ -474,6 +522,42 @@ export const pluginManifestV1Schema = z.object({}}+ if (manifest.apiRoutes && manifest.apiRoutes.length > 0) {+ if (!manifest.capabilities.includes("api.routes.register")) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message: "Capability 'api.routes.register' is required when apiRoutes are declared",+ path: ["capabilities"],+ });+ }+ }++ if (manifest.database) {+ const requiredCapabilities = [+ "database.namespace.migrate",+ "database.namespace.read",+ ] as const;+ for (const capability of requiredCapabilities) {+ if (!manifest.capabilities.includes(capability)) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message: `Capability '${capability}' is required when database migrations are declared`,+ path: ["capabilities"],+ });+ }+ }++ const coreReadTables = manifest.database.coreReadTables ?? [];+ const duplicates = coreReadTables.filter((table, i) => coreReadTables.indexOf(table) !== i);+ if (duplicates.length > 0) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message: `Duplicate database coreReadTables: ${[...new Set(duplicates)].join(", ")}`,+ path: ["database", "coreReadTables"],+ });+ }+ }+// ── 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.@@ -504,6 +588,27 @@ export const pluginManifestV1Schema = z.object({}}+ if (manifest.apiRoutes) {+ const routeKeys = manifest.apiRoutes.map((route) => route.routeKey);+ const duplicateKeys = routeKeys.filter((key, i) => routeKeys.indexOf(key) !== i);+ if (duplicateKeys.length > 0) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message: `Duplicate api route keys: ${[...new Set(duplicateKeys)].join(", ")}`,+ path: ["apiRoutes"],+ });+ }+ const routeSignatures = manifest.apiRoutes.map((route) => `${route.method} ${route.path}`);+ const duplicateRoutes = routeSignatures.filter((sig, i) => routeSignatures.indexOf(sig) !== i);+ if (duplicateRoutes.length > 0) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message: `Duplicate api routes: ${[...new Set(duplicateRoutes)].join(", ")}`,+ path: ["apiRoutes"],+ });+ }+ }+// tool names must be unique within the plugin (namespaced at runtime)if (manifest.tools) {const toolNames = manifest.tools.map((t) => t.name);diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yamlindex 4ac3cfcc5f..dc540f76b2 100644--- a/pnpm-workspace.yaml+++ b/pnpm-workspace.yaml@@ -3,6 +3,9 @@ packages:- packages/adapters/*- packages/plugins/*- packages/plugins/examples/*+ # Keep this smoke fixture installable as a local plugin example without+ # forcing PRs to commit pnpm-lock.yaml for a new workspace importer.+ - "!packages/plugins/examples/plugin-orchestration-smoke-example"- server- ui- clidiff --git a/server/src/__tests__/plugin-database.test.ts b/server/src/__tests__/plugin-database.test.tsnew file mode 100644index 0000000000..9aaca2f15e--- /dev/null+++ b/server/src/__tests__/plugin-database.test.ts@@ -0,0 +1,269 @@+import { randomUUID } from "node:crypto";+import { mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { and, eq, sql } from "drizzle-orm";+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";+import {+ companies,+ createDb,+ issueRelations,+ issues,+ pluginDatabaseNamespaces,+ pluginMigrations,+ plugins,+} from "@paperclipai/db";+import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";+import {+ getEmbeddedPostgresTestSupport,+ startEmbeddedPostgresTestDatabase,+} from "./helpers/embedded-postgres.js";+import {+ derivePluginDatabaseNamespace,+ pluginDatabaseService,+ validatePluginMigrationStatement,+ validatePluginRuntimeExecute,+ validatePluginRuntimeQuery,+} from "../services/plugin-database.js";++const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;++if (!embeddedPostgresSupport.supported) {+ console.warn(+ `Skipping embedded Postgres plugin database tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,+ );+}++describe("plugin database SQL validation", () => {+ it("allows namespace migrations with whitelisted public foreign keys", () => {+ expect(() =>+ validatePluginMigrationStatement(+ "CREATE TABLE plugin_test.rows (id uuid PRIMARY KEY, issue_id uuid REFERENCES public.issues(id))",+ "plugin_test",+ ["issues"],+ )+ ).not.toThrow();+ });++ it("rejects migrations that create public objects", () => {+ expect(() =>+ validatePluginMigrationStatement(+ "CREATE TABLE public.rows (id uuid PRIMARY KEY)",+ "plugin_test",+ ["issues"],+ )+ ).toThrow(/public/i);+ });++ it("allows whitelisted runtime reads but rejects public writes", () => {+ expect(() =>+ validatePluginRuntimeQuery(+ "SELECT r.id FROM plugin_test.rows r JOIN public.issues i ON i.id = r.issue_id",+ "plugin_test",+ ["issues"],+ )+ ).not.toThrow();+ expect(() =>+ validatePluginRuntimeExecute("UPDATE public.issues SET title = $1", "plugin_test")+ ).toThrow(/namespace/i);+ });++ it("targets anonymous DO blocks without rejecting do-prefixed aliases", () => {+ expect(() =>+ validatePluginRuntimeQuery(+ "SELECT EXTRACT(DOW FROM created_at) AS do_flag FROM plugin_test.rows",+ "plugin_test",+ )+ ).not.toThrow();+ expect(() =>+ validatePluginMigrationStatement("DO $$ BEGIN END $$;", "plugin_test")+ ).toThrow(/disallowed/i);+ });+});++describeEmbeddedPostgres("plugin database namespaces", () => {+ let db!: ReturnType<typeof createDb>;+ let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;+ let packageRoots: string[] = [];++ beforeAll(async () => {+ tempDb = await startEmbeddedPostgresTestDatabase("paperclip-plugin-db-");+ db = createDb(tempDb.connectionString);+ }, 20_000);++ afterEach(async () => {+ for (const pluginKey of ["paperclip.dbtest", "paperclip.escape"]) {+ const namespace = derivePluginDatabaseNamespace(pluginKey);+ await db.execute(sql.raw(`DROP SCHEMA IF EXISTS "${namespace}" CASCADE`));+ }+ await db.delete(pluginMigrations);+ await db.delete(pluginDatabaseNamespaces);+ await db.delete(plugins);+ await db.delete(issueRelations);+ await db.delete(issues);+ await db.delete(companies);+ await Promise.all(packageRoots.map((root) => rm(root, { recursive: true, force: true })));+ packageRoots = [];+ });++ afterAll(async () => {+ await tempDb?.cleanup();+ });++ async function createPluginPackage(manifest: PaperclipPluginManifestV1, migrationSql: string) {+ const packageRoot = await mkdtemp(path.join(os.tmpdir(), "paperclip-plugin-package-"));+ packageRoots.push(packageRoot);+ const migrationsDir = path.join(packageRoot, manifest.database!.migrationsDir);+ await mkdir(migrationsDir, { recursive: true });+ await writeFile(path.join(migrationsDir, "001_init.sql"), migrationSql, "utf8");+ return packageRoot;+ }++ async function installPluginRecord(manifest: PaperclipPluginManifestV1) {+ const pluginId = randomUUID();+ await db.insert(plugins).values({+ id: pluginId,+ pluginKey: manifest.id,+ packageName: manifest.id,+ version: manifest.version,+ apiVersion: manifest.apiVersion,+ categories: manifest.categories,+ manifestJson: manifest,+ status: "installed",+ installOrder: 1,+ });+ return pluginId;+ }++ function manifest(pluginKey = "paperclip.dbtest"): PaperclipPluginManifestV1 {+ return {+ id: pluginKey,+ apiVersion: 1,+ version: "1.0.0",+ displayName: "DB Test",+ description: "Exercises restricted plugin database access.",+ author: "Paperclip",+ categories: ["automation"],+ capabilities: [+ "database.namespace.migrate",+ "database.namespace.read",+ "database.namespace.write",+ ],+ entrypoints: { worker: "./dist/worker.js" },+ database: {+ migrationsDir: "migrations",+ coreReadTables: ["issues"],+ },+ };+ }++ it("applies migrations once and allows whitelisted core joins at runtime", async () => {+ const pluginManifest = manifest();+ const namespace = derivePluginDatabaseNamespace(pluginManifest.id);+ const packageRoot = await createPluginPackage(+ pluginManifest,+ `+ CREATE TABLE ${namespace}.mission_rows (+ id uuid PRIMARY KEY,+ issue_id uuid NOT NULL REFERENCES public.issues(id),+ label text NOT NULL+ );+ `,+ );+ const pluginId = await installPluginRecord(pluginManifest);+ const companyId = randomUUID();+ const issueId = randomUUID();+ await db.insert(companies).values({+ id: companyId,+ name: "Paperclip",+ issuePrefix: "TST",+ requireBoardApprovalForNewAgents: false,+ });+ await db.insert(issues).values({+ id: issueId,+ companyId,+ title: "Joined issue",+ status: "todo",+ priority: "medium",+ identifier: "TST-1",+ });++ const pluginDb = pluginDatabaseService(db);+ await pluginDb.applyMigrations(pluginId, pluginManifest, packageRoot);+ await pluginDb.applyMigrations(pluginId, pluginManifest, packageRoot);++ await pluginDb.execute(+ pluginId,+ `INSERT INTO ${namespace}.mission_rows (id, issue_id, label) VALUES ($1, $2, $3)`,+ [randomUUID(), issueId, "alpha"],+ );+ const rows = await pluginDb.query<{ label: string; title: string }>(+ pluginId,+ `SELECT m.label, i.title FROM ${namespace}.mission_rows m JOIN public.issues i ON i.id = m.issue_id`,+ );+ expect(rows).toEqual([{ label: "alpha", title: "Joined issue" }]);++ const migrations = await db+ .select()+ .from(pluginMigrations)+ .where(and(eq(pluginMigrations.pluginId, pluginId), eq(pluginMigrations.status, "applied")));+ expect(migrations).toHaveLength(1);+ });++ it("rejects runtime writes to public core tables", async () => {+ const pluginManifest = manifest();+ const namespace = derivePluginDatabaseNamespace(pluginManifest.id);+ const packageRoot = await createPluginPackage(+ pluginManifest,+ `CREATE TABLE ${namespace}.notes (id uuid PRIMARY KEY, body text NOT NULL);`,+ );+ const pluginId = await installPluginRecord(pluginManifest);+ const pluginDb = pluginDatabaseService(db);+ await pluginDb.applyMigrations(pluginId, pluginManifest, packageRoot);++ await expect(+ pluginDb.execute(pluginId, "UPDATE public.issues SET title = $1", ["bad"]),+ ).rejects.toThrow(/plugin namespace/i);+ });++ it("records a failed migration when SQL escapes the plugin namespace", async () => {+ const pluginManifest = manifest("paperclip.escape");+ const packageRoot = await createPluginPackage(+ pluginManifest,+ "CREATE TABLE public.plugin_escape (id uuid PRIMARY KEY);",+ );+ const pluginId = await installPluginRecord(pluginManifest);++ await expect(+ pluginDatabaseService(db).applyMigrations(pluginId, pluginManifest, packageRoot),+ ).rejects.toThrow(/public\.plugin_escape|public/i);++ const [migration] = await db+ .select()+ .from(pluginMigrations)+ .where(eq(pluginMigrations.pluginId, pluginId));+ expect(migration?.status).toBe("failed");+ });++ it("rejects checksum changes for already applied migrations", async () => {+ const pluginManifest = manifest();+ const namespace = derivePluginDatabaseNamespace(pluginManifest.id);+ const packageRoot = await createPluginPackage(+ pluginManifest,+ `CREATE TABLE ${namespace}.checksum_rows (id uuid PRIMARY KEY);`,+ );+ const pluginId = await installPluginRecord(pluginManifest);+ const pluginDb = pluginDatabaseService(db);+ await pluginDb.applyMigrations(pluginId, pluginManifest, packageRoot);++ await writeFile(+ path.join(packageRoot, "migrations", "001_init.sql"),+ `CREATE TABLE ${namespace}.checksum_rows (id uuid PRIMARY KEY, note text);`,+ "utf8",+ );++ await expect(pluginDb.applyMigrations(pluginId, pluginManifest, packageRoot))+ .rejects.toThrow(/checksum mismatch/i);+ });+});diff --git a/server/src/__tests__/plugin-orchestration-apis.test.ts b/server/src/__tests__/plugin-orchestration-apis.test.tsnew file mode 100644index 0000000000..b8ee02e962--- /dev/null+++ b/server/src/__tests__/plugin-orchestration-apis.test.ts@@ -0,0 +1,372 @@+import { randomUUID } from "node:crypto";+import { and, eq } from "drizzle-orm";+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";+import {+ activityLog,+ agentWakeupRequests,+ agents,+ companies,+ costEvents,+ createDb,+ heartbeatRuns,+ issueRelations,+ issues,+} from "@paperclipai/db";+import {+ getEmbeddedPostgresTestSupport,+ startEmbeddedPostgresTestDatabase,+} from "./helpers/embedded-postgres.js";+import { buildHostServices } from "../services/plugin-host-services.js";++const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;++function createEventBusStub() {+ return {+ forPlugin() {+ return {+ emit: async () => {},+ subscribe: () => {},+ };+ },+ } as any;+}++function issuePrefix(id: string) {+ return `T${id.replace(/-/g, "").slice(0, 6).toUpperCase()}`;+}++if (!embeddedPostgresSupport.supported) {+ console.warn(+ `Skipping embedded Postgres plugin orchestration API tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,+ );+}++describeEmbeddedPostgres("plugin orchestration APIs", () => {+ let db!: ReturnType<typeof createDb>;+ let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;++ beforeAll(async () => {+ tempDb = await startEmbeddedPostgresTestDatabase("paperclip-plugin-orchestration-");+ db = createDb(tempDb.connectionString);+ }, 20_000);++ afterEach(async () => {+ await db.delete(activityLog);+ await db.delete(costEvents);+ await db.delete(heartbeatRuns);+ await db.delete(agentWakeupRequests);+ await db.delete(issueRelations);+ await db.delete(issues);+ await db.delete(agents);+ await db.delete(companies);+ });++ afterAll(async () => {+ await tempDb?.cleanup();+ });++ async function seedCompanyAndAgent() {+ const companyId = randomUUID();+ const agentId = randomUUID();+ await db.insert(companies).values({+ id: companyId,+ name: "Paperclip",+ issuePrefix: issuePrefix(companyId),+ requireBoardApprovalForNewAgents: false,+ });+ await db.insert(agents).values({+ id: agentId,+ companyId,+ name: "Engineer",+ role: "engineer",+ status: "idle",+ adapterType: "process",+ adapterConfig: { command: "true" },+ runtimeConfig: {},+ permissions: {},+ });+ return { companyId, agentId };+ }++ it("creates plugin-origin issues with full orchestration fields and audit activity", async () => {+ const { companyId, agentId } = await seedCompanyAndAgent();+ const blockerIssueId = randomUUID();+ const originRunId = randomUUID();+ await db.insert(heartbeatRuns).values({+ id: originRunId,+ companyId,+ agentId,+ status: "running",+ invocationSource: "assignment",+ contextSnapshot: { issueId: blockerIssueId },+ });+ await db.insert(issues).values({+ id: blockerIssueId,+ companyId,+ title: "Blocker",+ status: "todo",+ priority: "medium",+ identifier: `${issuePrefix(companyId)}-blocker`,+ });++ const services = buildHostServices(db, "plugin-record-id", "paperclip.missions", createEventBusStub());+ const issue = await services.issues.create({+ companyId,+ title: "Plugin child issue",+ status: "todo",+ assigneeAgentId: agentId,+ billingCode: "mission:alpha",+ originId: "mission-alpha",+ blockedByIssueIds: [blockerIssueId],+ actorAgentId: agentId,+ actorRunId: originRunId,+ });++ const [stored] = await db.select().from(issues).where(eq(issues.id, issue.id));+ expect(stored?.originKind).toBe("plugin:paperclip.missions");+ expect(stored?.originId).toBe("mission-alpha");+ expect(stored?.billingCode).toBe("mission:alpha");+ expect(stored?.assigneeAgentId).toBe(agentId);+ expect(stored?.createdByAgentId).toBe(agentId);+ expect(stored?.originRunId).toBe(originRunId);++ const [relation] = await db+ .select()+ .from(issueRelations)+ .where(and(eq(issueRelations.issueId, blockerIssueId), eq(issueRelations.relatedIssueId, issue.id)));+ expect(relation?.type).toBe("blocks");++ const activities = await db+ .select()+ .from(activityLog)+ .where(and(eq(activityLog.entityType, "issue"), eq(activityLog.entityId, issue.id)));+ expect(activities).toEqual(+ expect.arrayContaining([+ expect.objectContaining({+ actorType: "plugin",+ actorId: "plugin-record-id",+ action: "issue.created",+ agentId,+ details: expect.objectContaining({+ sourcePluginId: "plugin-record-id",+ sourcePluginKey: "paperclip.missions",+ initiatingActorType: "agent",+ initiatingActorId: agentId,+ initiatingRunId: originRunId,+ }),+ }),+ ]),+ );+ });++ it("enforces plugin origin namespaces", async () => {+ const { companyId } = await seedCompanyAndAgent();+ const services = buildHostServices(db, "plugin-record-id", "paperclip.missions", createEventBusStub());++ const featureIssue = await services.issues.create({+ companyId,+ title: "Feature issue",+ originKind: "plugin:paperclip.missions:feature",+ originId: "mission-alpha:feature-1",+ });+ expect(featureIssue.originKind).toBe("plugin:paperclip.missions:feature");++ await expect(+ services.issues.create({+ companyId,+ title: "Spoofed issue",+ originKind: "plugin:other.plugin:feature",+ }),+ ).rejects.toThrow("Plugin may only use originKind values under plugin:paperclip.missions");++ await expect(+ services.issues.update({+ issueId: featureIssue.id,+ companyId,+ patch: { originKind: "plugin:other.plugin:feature" },+ }),+ ).rejects.toThrow("Plugin may only use originKind values under plugin:paperclip.missions");+ });++ it("asserts checkout ownership for run-scoped plugin actions", async () => {+ const { companyId, agentId } = await seedCompanyAndAgent();+ const issueId = randomUUID();+ const runId = randomUUID();+ await db.insert(heartbeatRuns).values({+ id: runId,+ companyId,+ agentId,+ status: "running",+ invocationSource: "assignment",+ contextSnapshot: { issueId },+ });+ await db.insert(issues).values({+ id: issueId,+ companyId,+ title: "Checked out issue",+ status: "in_progress",+ priority: "medium",+ assigneeAgentId: agentId,+ checkoutRunId: runId,+ executionRunId: runId,+ });++ const services = buildHostServices(db, "plugin-record-id", "paperclip.missions", createEventBusStub());+ await expect(+ services.issues.assertCheckoutOwner({+ issueId,+ companyId,+ actorAgentId: agentId,+ actorRunId: runId,+ }),+ ).resolves.toMatchObject({+ issueId,+ status: "in_progress",+ assigneeAgentId: agentId,+ checkoutRunId: runId,+ });+ });++ it("refuses plugin wakeups for issues with unresolved blockers", async () => {+ const { companyId, agentId } = await seedCompanyAndAgent();+ const blockerIssueId = randomUUID();+ const blockedIssueId = randomUUID();+ await db.insert(issues).values([+ {+ id: blockerIssueId,+ companyId,+ title: "Unresolved blocker",+ status: "todo",+ priority: "medium",+ },+ {+ id: blockedIssueId,+ companyId,+ title: "Blocked issue",+ status: "todo",+ priority: "medium",+ assigneeAgentId: agentId,+ },+ ]);+ await db.insert(issueRelations).values({+ companyId,+ issueId: blockerIssueId,+ relatedIssueId: blockedIssueId,+ type: "blocks",+ });++ const services = buildHostServices(db, "plugin-record-id", "paperclip.missions", createEventBusStub());+ await expect(+ services.issues.requestWakeup({+ issueId: blockedIssueId,+ companyId,+ reason: "mission_advance",+ }),+ ).rejects.toThrow("Issue is blocked by unresolved blockers");+ });++ it("narrows orchestration cost summaries by subtree and billing code", async () => {+ const { companyId, agentId } = await seedCompanyAndAgent();+ const rootIssueId = randomUUID();+ const childIssueId = randomUUID();+ const unrelatedIssueId = randomUUID();+ await db.insert(issues).values([+ {+ id: rootIssueId,+ companyId,+ title: "Root mission",+ status: "todo",+ priority: "medium",+ billingCode: "mission:alpha",+ },+ {+ id: childIssueId,+ companyId,+ parentId: rootIssueId,+ title: "Child mission",+ status: "todo",+ priority: "medium",+ billingCode: "mission:alpha",+ },+ {+ id: unrelatedIssueId,+ companyId,+ title: "Different mission",+ status: "todo",+ priority: "medium",+ billingCode: "mission:alpha",+ },+ ]);+ await db.insert(costEvents).values([+ {+ companyId,+ agentId,+ issueId: rootIssueId,+ billingCode: "mission:alpha",+ provider: "test",+ model: "unit",+ inputTokens: 10,+ cachedInputTokens: 1,+ outputTokens: 2,+ costCents: 100,+ occurredAt: new Date(),+ },+ {+ companyId,+ agentId,+ issueId: childIssueId,+ billingCode: "mission:alpha",+ provider: "test",+ model: "unit",+ inputTokens: 20,+ cachedInputTokens: 2,+ outputTokens: 4,+ costCents: 200,+ occurredAt: new Date(),+ },+ {+ companyId,+ agentId,+ issueId: childIssueId,+ billingCode: "mission:beta",+ provider: "test",+ model: "unit",+ inputTokens: 30,+ cachedInputTokens: 3,+ outputTokens: 6,+ costCents: 300,+ occurredAt: new Date(),+ },+ {+ companyId,+ agentId,+ issueId: unrelatedIssueId,+ billingCode: "mission:alpha",+ provider: "test",+ model: "unit",+ inputTokens: 40,+ cachedInputTokens: 4,+ outputTokens: 8,+ costCents: 400,+ occurredAt: new Date(),+ },+ ]);++ const services = buildHostServices(db, "plugin-record-id", "paperclip.missions", createEventBusStub());+ const summary = await services.issues.getOrchestrationSummary({+ companyId,+ issueId: rootIssueId,+ includeSubtree: true,+ });++ expect(new Set(summary.subtreeIssueIds)).toEqual(new Set([rootIssueId, childIssueId]));+ expect(summary.costs).toMatchObject({+ billingCode: "mission:alpha",+ costCents: 300,+ inputTokens: 30,+ cachedInputTokens: 3,+ outputTokens: 6,+ });+ });+});diff --git a/server/src/__tests__/plugin-routes-authz.test.ts b/server/src/__tests__/plugin-routes-authz.test.tsindex 4c965b0d8b..95a9281cae 100644--- a/server/src/__tests__/plugin-routes-authz.test.ts+++ b/server/src/__tests__/plugin-routes-authz.test.ts@@ -32,7 +32,11 @@ vi.mock("../services/live-events.js", () => ({publishGlobalLiveEvent: vi.fn(),}));-async function createApp(actor: Record<string, unknown>, loaderOverrides: Record<string, unknown> = {}) {+async function createApp(+ actor: Record<string, unknown>,+ loaderOverrides: Record<string, unknown> = {},+ bridgeDeps?: Record<string, unknown>,+) {const [{ pluginRoutes }, { errorHandler }] = await Promise.all([import("../routes/plugins.js"),import("../middleware/index.js"),@@ -49,7 +53,7 @@ async function createApp(actor: Record<string, unknown>, loaderOverrides: Recordreq.actor = actor as typeof req.actor;next();});- app.use("/api", pluginRoutes({} as never, loader as never));+ app.use("/api", pluginRoutes({} as never, loader as never, undefined, undefined, undefined, bridgeDeps as never));app.use(errorHandler);return { app, loader };@@ -195,3 +199,69 @@ describe("plugin install and upgrade authz", () => {expect(mockLifecycle.upgrade).toHaveBeenCalledWith(pluginId, "1.1.0");}, 20_000);});++describe("scoped plugin API routes", () => {+ beforeEach(() => {+ vi.resetAllMocks();+ });++ it("dispatches manifest-declared scoped routes after company access checks", async () => {+ const pluginId = "11111111-1111-4111-8111-111111111111";+ const workerManager = {+ call: vi.fn().mockResolvedValue({+ status: 202,+ body: { ok: true },+ }),+ };+ mockRegistry.getById.mockResolvedValue(null);+ mockRegistry.getByKey.mockResolvedValue({+ id: pluginId,+ pluginKey: "paperclip.example",+ version: "1.0.0",+ status: "ready",+ manifestJson: {+ id: "paperclip.example",+ capabilities: ["api.routes.register"],+ apiRoutes: [+ {+ routeKey: "smoke",+ method: "GET",+ path: "/smoke",+ auth: "board-or-agent",+ capability: "api.routes.register",+ companyResolution: { from: "query", key: "companyId" },+ },+ ],+ },+ });++ const { app } = await createApp(+ {+ type: "board",+ userId: "admin-1",+ source: "session",+ isInstanceAdmin: false,+ companyIds: ["company-1"],+ },+ {},+ { workerManager },+ );++ const res = await request(app)+ .get("/api/plugins/paperclip.example/api/smoke")+ .query({ companyId: "company-1" });++ expect(res.status).toBe(202);+ expect(res.body).toEqual({ ok: true });+ expect(workerManager.call).toHaveBeenCalledWith(+ pluginId,+ "handleApiRequest",+ expect.objectContaining({+ routeKey: "smoke",+ method: "GET",+ companyId: "company-1",+ query: { companyId: "company-1" },+ }),+ );+ }, 20_000);+});diff --git a/server/src/__tests__/plugin-scoped-api-routes.test.ts b/server/src/__tests__/plugin-scoped-api-routes.test.tsnew file mode 100644index 0000000000..6968e82246--- /dev/null+++ b/server/src/__tests__/plugin-scoped-api-routes.test.ts@@ -0,0 +1,427 @@+import express from "express";+import request from "supertest";+import { beforeEach, describe, expect, it, vi } from "vitest";+import { pluginManifestV1Schema, type PaperclipPluginManifestV1 } from "@paperclipai/shared";++const mockRegistry = vi.hoisted(() => ({+ getById: vi.fn(),+ getByKey: vi.fn(),+}));++const mockLifecycle = vi.hoisted(() => ({+ load: vi.fn(),+ upgrade: vi.fn(),+}));++const mockIssueService = vi.hoisted(() => ({+ getById: vi.fn(),+ assertCheckoutOwner: vi.fn(),+}));++vi.mock("../services/plugin-registry.js", () => ({+ pluginRegistryService: () => mockRegistry,+}));++vi.mock("../services/plugin-lifecycle.js", () => ({+ pluginLifecycleManager: () => mockLifecycle,+}));++vi.mock("../services/issues.js", () => ({+ issueService: () => mockIssueService,+}));++vi.mock("../services/activity-log.js", () => ({+ logActivity: vi.fn(),+}));++vi.mock("../services/live-events.js", () => ({+ publishGlobalLiveEvent: vi.fn(),+}));++function manifest(apiRoutes: NonNullable<PaperclipPluginManifestV1["apiRoutes"]>): PaperclipPluginManifestV1 {+ return {+ id: "paperclip.scoped-api-test",+ apiVersion: 1,+ version: "1.0.0",+ displayName: "Scoped API Test",+ description: "Test plugin for scoped API routes",+ author: "Paperclip",+ categories: ["automation"],+ capabilities: ["api.routes.register"],+ entrypoints: { worker: "dist/worker.js" },+ apiRoutes,+ };+}++async function createApp(input: {+ actor: Record<string, unknown>;+ plugin?: Record<string, unknown> | null;+ workerRunning?: boolean;+ workerResult?: unknown;+}) {+ const [{ pluginRoutes }, { errorHandler }] = await Promise.all([+ import("../routes/plugins.js"),+ import("../middleware/index.js"),+ ]);++ const workerManager = {+ isRunning: vi.fn().mockReturnValue(input.workerRunning ?? true),+ call: vi.fn().mockResolvedValue(input.workerResult ?? { status: 200, body: { ok: true } }),+ };++ mockRegistry.getById.mockResolvedValue(input.plugin ?? null);+ mockRegistry.getByKey.mockResolvedValue(input.plugin ?? null);++ const app = express();+ app.use(express.json());+ app.use((req, _res, next) => {+ req.actor = input.actor as typeof req.actor;+ next();+ });+ app.use(+ "/api",+ pluginRoutes(+ {} as never,+ { installPlugin: vi.fn() } as never,+ undefined,+ undefined,+ undefined,+ { workerManager } as never,+ ),+ );+ app.use(errorHandler);++ return { app, workerManager };+}++describe("plugin scoped API routes", () => {+ const pluginId = "11111111-1111-4111-8111-111111111111";+ const companyId = "22222222-2222-4222-8222-222222222222";+ const agentId = "33333333-3333-4333-8333-333333333333";+ const runId = "44444444-4444-4444-8444-444444444444";+ const issueId = "55555555-5555-4555-8555-555555555555";++ beforeEach(() => {+ vi.resetAllMocks();+ mockIssueService.getById.mockResolvedValue(null);+ mockIssueService.assertCheckoutOwner.mockResolvedValue({+ id: issueId,+ status: "in_progress",+ assigneeAgentId: agentId,+ checkoutRunId: runId,+ adoptedFromRunId: null,+ });+ });++ it("dispatches a board GET route with params, query, actor, and company context", async () => {+ const apiRoutes = manifest([+ {+ routeKey: "summary.get",+ method: "GET",+ path: "/companies/:companySlug/summary",+ auth: "board",+ capability: "api.routes.register",+ companyResolution: { from: "query", key: "companyId" },+ },+ ]);+ const { app, workerManager } = await createApp({+ actor: {+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ isInstanceAdmin: true,+ },+ plugin: {+ id: pluginId,+ pluginKey: apiRoutes.id,+ status: "ready",+ manifestJson: apiRoutes,+ },+ workerResult: { status: 201, body: { handled: true } },+ });++ const res = await request(app)+ .get(`/api/plugins/${pluginId}/api/companies/acme/summary?companyId=${companyId}&view=compact`)+ .set("Authorization", "Bearer should-not-forward");++ expect(res.status).toBe(201);+ expect(res.body).toEqual({ handled: true });+ expect(workerManager.call).toHaveBeenCalledWith(pluginId, "handleApiRequest", expect.objectContaining({+ routeKey: "summary.get",+ method: "GET",+ params: { companySlug: "acme" },+ query: { companyId, view: "compact" },+ companyId,+ actor: expect.objectContaining({ actorType: "user", actorId: "user-1" }),+ }));+ expect(workerManager.call.mock.calls[0]?.[2].headers.authorization).toBeUndefined();+ });++ it("only forwards allowlisted response headers from plugin routes", async () => {+ const apiRoutes = manifest([+ {+ routeKey: "summary.get",+ method: "GET",+ path: "/companies/:companySlug/summary",+ auth: "board",+ capability: "api.routes.register",+ companyResolution: { from: "query", key: "companyId" },+ },+ ]);+ const { app } = await createApp({+ actor: {+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ isInstanceAdmin: true,+ },+ plugin: {+ id: pluginId,+ pluginKey: apiRoutes.id,+ status: "ready",+ manifestJson: apiRoutes,+ },+ workerResult: {+ status: 200,+ body: { handled: true },+ headers: {+ "cache-control": "no-store",+ "content-security-policy": "default-src 'none'",+ location: "https://example.invalid",+ "x-request-id": "plugin-request",+ },+ },+ });++ const res = await request(app)+ .get(`/api/plugins/${pluginId}/api/companies/acme/summary?companyId=${companyId}`);++ expect(res.status).toBe(200);+ expect(res.headers["cache-control"]).toBe("no-store");+ expect(res.headers["x-request-id"]).toBe("plugin-request");+ expect(res.headers["content-security-policy"]).toBeUndefined();+ expect(res.headers.location).toBeUndefined();+ });++ it("enforces agent checkout ownership before dispatching issue-scoped POST routes", async () => {+ const apiRoutes = manifest([+ {+ routeKey: "issue.advance",+ method: "POST",+ path: "/issues/:issueId/advance",+ auth: "agent",+ capability: "api.routes.register",+ checkoutPolicy: "required-for-agent-in-progress",+ companyResolution: { from: "issue", param: "issueId" },+ },+ ]);+ mockIssueService.getById.mockResolvedValue({+ id: issueId,+ companyId,+ status: "in_progress",+ assigneeAgentId: agentId,+ });+ const { app, workerManager } = await createApp({+ actor: {+ type: "agent",+ agentId,+ companyId,+ runId,+ source: "agent_key",+ },+ plugin: {+ id: pluginId,+ pluginKey: apiRoutes.id,+ status: "ready",+ manifestJson: apiRoutes,+ },+ });++ const res = await request(app)+ .post(`/api/plugins/${pluginId}/api/issues/${issueId}/advance`)+ .send({ step: "next" });++ expect(res.status).toBe(200);+ expect(mockIssueService.assertCheckoutOwner).toHaveBeenCalledWith(issueId, agentId, runId);+ expect(workerManager.call).toHaveBeenCalledWith(pluginId, "handleApiRequest", expect.objectContaining({+ routeKey: "issue.advance",+ params: { issueId },+ body: { step: "next" },+ actor: expect.objectContaining({ actorType: "agent", agentId, runId }),+ companyId,+ }));+ });++ it("rejects checkout-protected agent routes without a run id before worker dispatch", async () => {+ const apiRoutes = manifest([+ {+ routeKey: "issue.advance",+ method: "POST",+ path: "/issues/:issueId/advance",+ auth: "agent",+ capability: "api.routes.register",+ checkoutPolicy: "required-for-agent-in-progress",+ companyResolution: { from: "issue", param: "issueId" },+ },+ ]);+ mockIssueService.getById.mockResolvedValue({+ id: issueId,+ companyId,+ status: "in_progress",+ assigneeAgentId: agentId,+ });+ const { app, workerManager } = await createApp({+ actor: {+ type: "agent",+ agentId,+ companyId,+ source: "agent_key",+ },+ plugin: {+ id: pluginId,+ pluginKey: apiRoutes.id,+ status: "ready",+ manifestJson: apiRoutes,+ },+ });++ const res = await request(app)+ .post(`/api/plugins/${pluginId}/api/issues/${issueId}/advance`)+ .send({});++ expect(res.status).toBe(401);+ expect(workerManager.call).not.toHaveBeenCalled();+ });++ it("rejects checkout-protected agent routes when the active checkout belongs to another run", async () => {+ const apiRoutes = manifest([+ {+ routeKey: "issue.advance",+ method: "POST",+ path: "/issues/:issueId/advance",+ auth: "agent",+ capability: "api.routes.register",+ checkoutPolicy: "always-for-agent",+ companyResolution: { from: "issue", param: "issueId" },+ },+ ]);+ mockIssueService.getById.mockResolvedValue({+ id: issueId,+ companyId,+ status: "in_progress",+ assigneeAgentId: agentId,+ });+ const conflict = new Error("Issue run ownership conflict") as Error & { status?: number };+ conflict.status = 409;+ mockIssueService.assertCheckoutOwner.mockRejectedValue(conflict);+ const { app, workerManager } = await createApp({+ actor: {+ type: "agent",+ agentId,+ companyId,+ runId,+ source: "agent_key",+ },+ plugin: {+ id: pluginId,+ pluginKey: apiRoutes.id,+ status: "ready",+ manifestJson: apiRoutes,+ },+ });++ const res = await request(app)+ .post(`/api/plugins/${pluginId}/api/issues/${issueId}/advance`)+ .send({});++ expect(res.status).toBe(409);+ expect(workerManager.call).not.toHaveBeenCalled();+ });++ it("returns a clear error for disabled plugins without worker dispatch", async () => {+ const apiRoutes = manifest([+ {+ routeKey: "summary.get",+ method: "GET",+ path: "/summary",+ auth: "board",+ capability: "api.routes.register",+ companyResolution: { from: "query", key: "companyId" },+ },+ ]);+ const { app, workerManager } = await createApp({+ actor: {+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ isInstanceAdmin: true,+ },+ plugin: {+ id: pluginId,+ pluginKey: apiRoutes.id,+ status: "disabled",+ manifestJson: apiRoutes,+ },+ });++ const res = await request(app)+ .get(`/api/plugins/${pluginId}/api/summary?companyId=${companyId}`);++ expect(res.status).toBe(503);+ expect(res.body.error).toContain("disabled");+ expect(workerManager.call).not.toHaveBeenCalled();+ });++ it("returns a clear error when a ready plugin has no running worker", async () => {+ const apiRoutes = manifest([+ {+ routeKey: "summary.get",+ method: "GET",+ path: "/summary",+ auth: "board",+ capability: "api.routes.register",+ companyResolution: { from: "query", key: "companyId" },+ },+ ]);+ const { app, workerManager } = await createApp({+ actor: {+ type: "board",+ userId: "user-1",+ source: "local_implicit",+ isInstanceAdmin: true,+ },+ plugin: {+ id: pluginId,+ pluginKey: apiRoutes.id,+ status: "ready",+ manifestJson: apiRoutes,+ },+ workerRunning: false,+ });++ const res = await request(app)+ .get(`/api/plugins/${pluginId}/api/summary?companyId=${companyId}`);++ expect(res.status).toBe(503);+ expect(res.body.error).toContain("worker is not running");+ expect(workerManager.call).not.toHaveBeenCalled();+ });++ it("rejects manifest routes that try to claim core API paths", () => {+ const result = pluginManifestV1Schema.safeParse(manifest([+ {+ routeKey: "bad.shadow",+ method: "POST",+ path: "/api/issues/:issueId",+ auth: "board",+ capability: "api.routes.register",+ },+ ]));++ expect(result.success).toBe(false);+ if (result.success) throw new Error("Expected manifest validation to fail");+ expect(result.error.issues.map((issue) => issue.message).join("\n")).toContain(+ "path must stay inside the plugin api namespace",+ );+ });+});diff --git a/server/src/__tests__/plugin-sdk-orchestration-contract.test.ts b/server/src/__tests__/plugin-sdk-orchestration-contract.test.tsnew file mode 100644index 0000000000..d68cb60a53--- /dev/null+++ b/server/src/__tests__/plugin-sdk-orchestration-contract.test.ts@@ -0,0 +1,240 @@+import { randomUUID } from "node:crypto";+import { describe, expect, it } from "vitest";+import type { Issue, PaperclipPluginManifestV1 } from "@paperclipai/shared";+import { createTestHarness } from "../../../packages/plugins/sdk/src/testing.js";++function manifest(capabilities: PaperclipPluginManifestV1["capabilities"]): PaperclipPluginManifestV1 {+ return {+ id: "paperclip.test-orchestration",+ apiVersion: 1,+ version: "0.1.0",+ displayName: "Test Orchestration",+ description: "Test plugin",+ author: "Paperclip",+ categories: ["automation"],+ capabilities,+ entrypoints: { worker: "./dist/worker.js" },+ };+}++function issue(input: Partial<Issue> & Pick<Issue, "id" | "companyId" | "title">): Issue {+ const now = new Date();+ return {+ id: input.id,+ companyId: input.companyId,+ projectId: null,+ projectWorkspaceId: null,+ goalId: null,+ parentId: null,+ title: input.title,+ description: null,+ status: "todo",+ priority: "medium",+ 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,+ executionWorkspaceId: null,+ executionWorkspacePreference: null,+ executionWorkspaceSettings: null,+ startedAt: null,+ completedAt: null,+ cancelledAt: null,+ hiddenAt: null,+ createdAt: now,+ updatedAt: now,+ ...input,+ };+}++describe("plugin SDK orchestration contract", () => {+ it("supports expanded issue create fields and relation helpers", async () => {+ const companyId = randomUUID();+ const blockerIssueId = randomUUID();+ const harness = createTestHarness({+ manifest: manifest(["issues.create", "issue.relations.read", "issue.relations.write", "issue.subtree.read"]),+ });+ harness.seed({+ issues: [issue({ id: blockerIssueId, companyId, title: "Blocker" })],+ });++ const created = await harness.ctx.issues.create({+ companyId,+ title: "Generated issue",+ status: "todo",+ assigneeUserId: "board-user",+ billingCode: "mission:alpha",+ originId: "mission-alpha",+ blockedByIssueIds: [blockerIssueId],+ });++ expect(created.originKind).toBe("plugin:paperclip.test-orchestration");+ expect(created.originId).toBe("mission-alpha");+ expect(created.billingCode).toBe("mission:alpha");+ expect(created.assigneeUserId).toBe("board-user");++ await expect(harness.ctx.issues.relations.get(created.id, companyId)).resolves.toEqual({+ blockedBy: [+ expect.objectContaining({+ id: blockerIssueId,+ title: "Blocker",+ }),+ ],+ blocks: [],+ });++ await expect(harness.ctx.issues.relations.removeBlockers(created.id, [blockerIssueId], companyId)).resolves.toEqual({+ blockedBy: [],+ blocks: [],+ });++ await expect(harness.ctx.issues.relations.addBlockers(created.id, [blockerIssueId], companyId)).resolves.toEqual({+ blockedBy: [expect.objectContaining({ id: blockerIssueId })],+ blocks: [],+ });++ await expect(+ harness.ctx.issues.getSubtree(created.id, companyId, { includeRelations: true }),+ ).resolves.toMatchObject({+ rootIssueId: created.id,+ issueIds: [created.id],+ relations: {+ [created.id]: {+ blockedBy: [expect.objectContaining({ id: blockerIssueId })],+ },+ },+ });+ });++ it("enforces plugin origin namespaces in the test harness", async () => {+ const companyId = randomUUID();+ const harness = createTestHarness({+ manifest: manifest(["issues.create", "issues.update", "issues.read"]),+ });++ const created = await harness.ctx.issues.create({+ companyId,+ title: "Generated issue",+ originKind: "plugin:paperclip.test-orchestration:feature",+ });++ expect(created.originKind).toBe("plugin:paperclip.test-orchestration:feature");+ await expect(+ harness.ctx.issues.list({+ companyId,+ originKind: "plugin:paperclip.test-orchestration:feature",+ }),+ ).resolves.toHaveLength(1);+ await expect(+ harness.ctx.issues.create({+ companyId,+ title: "Spoofed issue",+ originKind: "plugin:other.plugin:feature",+ }),+ ).rejects.toThrow("Plugin may only use originKind values under plugin:paperclip.test-orchestration");+ await expect(+ harness.ctx.issues.update(+ created.id,+ { originKind: "plugin:other.plugin:feature" },+ companyId,+ ),+ ).rejects.toThrow("Plugin may only use originKind values under plugin:paperclip.test-orchestration");+ });++ it("enforces checkout and wakeup capabilities in the test harness", async () => {+ const companyId = randomUUID();+ const agentId = randomUUID();+ const runId = randomUUID();+ const checkedOutIssueId = randomUUID();+ const harness = createTestHarness({+ manifest: manifest(["issues.checkout", "issues.wakeup", "issues.read"]),+ });+ harness.seed({+ issues: [+ issue({+ id: checkedOutIssueId,+ companyId,+ title: "Checked out",+ status: "in_progress",+ assigneeAgentId: agentId,+ checkoutRunId: runId,+ }),+ ],+ });++ await expect(+ harness.ctx.issues.assertCheckoutOwner({+ issueId: checkedOutIssueId,+ companyId,+ actorAgentId: agentId,+ actorRunId: runId,+ }),+ ).resolves.toMatchObject({+ issueId: checkedOutIssueId,+ checkoutRunId: runId,+ });++ await expect(+ harness.ctx.issues.requestWakeup(checkedOutIssueId, companyId, {+ reason: "mission_advance",+ }),+ ).resolves.toMatchObject({ queued: true });++ await expect(+ harness.ctx.issues.requestWakeups([checkedOutIssueId], companyId, {+ reason: "mission_advance",+ idempotencyKeyPrefix: "mission:alpha",+ }),+ ).resolves.toEqual([+ expect.objectContaining({+ issueId: checkedOutIssueId,+ queued: true,+ }),+ ]);+ });++ it("rejects wakeups when blockers are unresolved", async () => {+ const companyId = randomUUID();+ const blockerIssueId = randomUUID();+ const blockedIssueId = randomUUID();+ const harness = createTestHarness({+ manifest: manifest(["issues.wakeup", "issues.read"]),+ });+ harness.seed({+ issues: [+ issue({ id: blockerIssueId, companyId, title: "Unresolved blocker", status: "todo" }),+ issue({+ id: blockedIssueId,+ companyId,+ title: "Blocked work",+ status: "todo",+ assigneeAgentId: randomUUID(),+ blockedBy: [+ {+ id: blockerIssueId,+ identifier: null,+ title: "Unresolved blocker",+ status: "todo",+ priority: "medium",+ assigneeAgentId: null,+ assigneeUserId: null,+ },+ ],+ }),+ ],+ });++ await expect(+ harness.ctx.issues.requestWakeup(blockedIssueId, companyId),+ ).rejects.toThrow("Issue is blocked by unresolved blockers");+ });+});diff --git a/server/src/app.ts b/server/src/app.tsindex b1389b74d4..b1a31401bc 100644--- a/server/src/app.ts+++ b/server/src/app.ts@@ -127,6 +127,7 @@ export async function createApp(instanceId?: string;hostVersion?: string;localPluginDir?: string;+ pluginMigrationDb?: Db;betterAuthHandler?: express.RequestHandler;resolveSession?: (req: ExpressRequest) => Promise<BetterAuthSessionResult | null>;},@@ -231,7 +232,10 @@ export async function createApp(let viteHtmlRenderer: ReturnType<typeof createCachedViteHtmlRenderer> | null = null;const loader = pluginLoader(db,- { localPluginDir: opts.localPluginDir ?? DEFAULT_LOCAL_PLUGIN_DIR },+ {+ localPluginDir: opts.localPluginDir ?? DEFAULT_LOCAL_PLUGIN_DIR,+ migrationDb: opts.pluginMigrationDb,+ },{workerManager,eventBus,diff --git a/server/src/config.ts b/server/src/config.tsindex 21271c980b..77b8a3f0cf 100644--- a/server/src/config.ts+++ b/server/src/config.ts@@ -62,6 +62,7 @@ export interface Config {authDisableSignUp: boolean;databaseMode: DatabaseMode;databaseUrl: string | undefined;+ databaseMigrationUrl: string | undefined;embeddedPostgresDataDir: string;embeddedPostgresPort: number;databaseBackupEnabled: boolean;@@ -297,6 +298,7 @@ export function loadConfig(): Config {authDisableSignUp,databaseMode: fileDatabaseMode,databaseUrl: process.env.DATABASE_URL ?? fileDbUrl,+ databaseMigrationUrl: process.env.DATABASE_MIGRATION_URL,embeddedPostgresDataDir: resolveHomeAwarePath(fileConfig?.database.embeddedPostgresDataDir ?? resolveDefaultEmbeddedPostgresDir(),),diff --git a/server/src/index.ts b/server/src/index.tsindex 870dd013ce..a788364a7c 100644--- a/server/src/index.ts+++ b/server/src/index.ts@@ -258,6 +258,7 @@ export async function startServer(): Promise<StartedServer> {}let db;+ let pluginMigrationDb;let embeddedPostgres: EmbeddedPostgresInstance | null = null;let embeddedPostgresStartedByThisProcess = false;let migrationSummary: MigrationSummary = "skipped";@@ -267,9 +268,11 @@ export async function startServer(): Promise<StartedServer> {| { mode: "external-postgres"; connectionString: string }| { mode: "embedded-postgres"; dataDir: string; port: number };if (config.databaseUrl) {- migrationSummary = await ensureMigrations(config.databaseUrl, "PostgreSQL");+ const migrationUrl = config.databaseMigrationUrl ?? config.databaseUrl;+ migrationSummary = await ensureMigrations(migrationUrl, "PostgreSQL");db = createDb(config.databaseUrl);+ pluginMigrationDb = config.databaseMigrationUrl ? createDb(config.databaseMigrationUrl) : db;logger.info("Using external PostgreSQL via DATABASE_URL/config");activeDatabaseConnectionString = config.databaseUrl;startupDbInfo = { mode: "external-postgres", connectionString: config.databaseUrl };@@ -431,6 +434,7 @@ export async function startServer(): Promise<StartedServer> {});db = createDb(embeddedConnectionString);+ pluginMigrationDb = db;logger.info("Embedded PostgreSQL ready");activeDatabaseConnectionString = embeddedConnectionString;resolvedEmbeddedPostgresPort = port;@@ -606,6 +610,7 @@ export async function startServer(): Promise<StartedServer> {bindHost: config.host,authReady,companyDeletionEnabled: config.companyDeletionEnabled,+ pluginMigrationDb: pluginMigrationDb as any,betterAuthHandler,resolveSession,});diff --git a/server/src/routes/activity.ts b/server/src/routes/activity.tsindex 53083b1b60..b5fd3cb9bf 100644--- a/server/src/routes/activity.ts+++ b/server/src/routes/activity.ts@@ -8,7 +8,7 @@ import { heartbeatService, issueService } from "../services/index.js";import { sanitizeRecord } from "../redaction.js";const createActivitySchema = z.object({- actorType: z.enum(["agent", "user", "system"]).optional().default("system"),+ actorType: z.enum(["agent", "user", "system", "plugin"]).optional().default("system"),actorId: z.string().min(1),action: z.string().min(1),entityType: z.string().min(1),diff --git a/server/src/routes/plugins.ts b/server/src/routes/plugins.tsindex d75912d07c..19a6739161 100644--- a/server/src/routes/plugins.ts+++ b/server/src/routes/plugins.ts@@ -23,11 +23,12 @@ import path from "node:path";import { randomUUID } from "node:crypto";import { fileURLToPath } from "node:url";import { Router } from "express";-import type { Request } 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 {+ PluginApiRouteDeclaration,PluginStatus,PaperclipPluginManifestV1,PluginBridgeErrorCode,@@ -41,6 +42,7 @@ 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 { issueService } from "../services/issues.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";@@ -48,8 +50,16 @@ 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 { assertBoardOrgAccess, assertCompanyAccess, assertInstanceAdmin, getActorInfo } from "./authz.js";+import {+ assertAuthenticated,+ assertBoard,+ assertBoardOrgAccess,+ assertCompanyAccess,+ assertInstanceAdmin,+ getActorInfo,+} from "./authz.js";import { validateInstanceConfig } from "../services/plugin-config-validator.js";+import { forbidden, notFound, unauthorized, unprocessable } from "../errors.js";/** UI slot declaration extracted from plugin manifest */type PluginUiSlotDeclaration = NonNullable<NonNullable<PaperclipPluginManifestV1["ui"]>["slots"]>[number];@@ -112,6 +122,14 @@ interface PluginHealthCheckResult {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 PLUGIN_API_BODY_LIMIT_BYTES = 1_000_000;+const PLUGIN_SCOPED_API_RESPONSE_HEADER_ALLOWLIST = new Set([+ "cache-control",+ "etag",+ "last-modified",+ "x-request-id",+]);+const __dirname = path.dirname(fileURLToPath(import.meta.url));const REPO_ROOT = path.resolve(__dirname, "../../..");@@ -140,6 +158,14 @@ const BUNDLED_PLUGIN_EXAMPLES: AvailablePluginExample[] = [localPath: "packages/plugins/examples/plugin-kitchen-sink-example",tag: "example",},+ {+ packageName: "@paperclipai/plugin-orchestration-smoke-example",+ pluginKey: "paperclipai.plugin-orchestration-smoke-example",+ displayName: "Orchestration Smoke (Example)",+ description: "Acceptance fixture for scoped plugin routes, restricted database namespaces, issue orchestration, documents, wakeups, summaries, and UI status surfaces.",+ localPath: "packages/plugins/examples/plugin-orchestration-smoke-example",+ tag: "example",+ },];function listBundledPluginExamples(): AvailablePluginExample[] {@@ -246,6 +272,30 @@ export interface PluginRouteBridgeDeps {streamBus?: PluginStreamBus;}+interface PluginScopedApiRequest {+ routeKey: string;+ method: string;+ path: string;+ params: Record<string, string>;+ query: Record<string, string | string[]>;+ body: unknown;+ actor: {+ actorType: "user" | "agent";+ actorId: string;+ agentId?: string | null;+ userId?: string | null;+ runId?: string | null;+ };+ companyId: string;+ headers: Record<string, string>;+}++interface PluginScopedApiResponse {+ status?: number;+ headers?: Record<string, string>;+ body?: unknown;+}+/** Request body for POST /api/plugins/tools/execute */interface PluginToolExecuteRequest {/** Fully namespaced tool name (e.g., "acme.linear:search-issues"). */@@ -314,6 +364,146 @@ export function pluginRoutes(loader,workerManager: bridgeDeps?.workerManager ?? webhookDeps?.workerManager,});+ const issuesSvc = issueService(db);++ function matchScopedApiRoute(route: PluginApiRouteDeclaration, method: string, requestPath: string) {+ if (route.method !== method) return null;+ const normalize = (value: string) => value.replace(/\/+$/, "") || "/";+ const routeSegments = normalize(route.path).split("/").filter(Boolean);+ const requestSegments = normalize(requestPath).split("/").filter(Boolean);+ if (routeSegments.length !== requestSegments.length) return null;+ const params: Record<string, string> = {};+ for (let i = 0; i < routeSegments.length; i += 1) {+ const routeSegment = routeSegments[i]!;+ const requestSegment = requestSegments[i]!;+ if (routeSegment.startsWith(":")) {+ params[routeSegment.slice(1)] = decodeURIComponent(requestSegment);+ continue;+ }+ if (routeSegment !== requestSegment) return null;+ }+ return params;+ }++ function sanitizePluginRequestHeaders(req: Request): Record<string, string> {+ const safeHeaderNames = new Set([+ "accept",+ "content-type",+ "user-agent",+ "x-paperclip-run-id",+ "x-request-id",+ ]);+ const headers: Record<string, string> = {};+ for (const [name, value] of Object.entries(req.headers)) {+ const lower = name.toLowerCase();+ if (!safeHeaderNames.has(lower)) continue;+ if (Array.isArray(value)) {+ headers[lower] = value.join(", ");+ } else if (typeof value === "string") {+ headers[lower] = value;+ }+ }+ return headers;+ }++ function applyPluginScopedApiResponseHeaders(+ res: Response,+ headers: Record<string, string> | undefined,+ ): void {+ for (const [name, value] of Object.entries(headers ?? {})) {+ const lower = name.toLowerCase();+ if (!PLUGIN_SCOPED_API_RESPONSE_HEADER_ALLOWLIST.has(lower)) continue;+ res.setHeader(lower, value);+ }+ }++ function normalizeQuery(query: Request["query"]): Record<string, string | string[]> {+ const normalized: Record<string, string | string[]> = {};+ for (const [key, value] of Object.entries(query)) {+ if (typeof value === "string") {+ normalized[key] = value;+ } else if (Array.isArray(value)) {+ normalized[key] = value.map((entry) => String(entry));+ }+ }+ return normalized;+ }++ async function resolveScopedApiCompanyId(+ route: PluginApiRouteDeclaration,+ params: Record<string, string>,+ req: Request,+ ) {+ const resolution = route.companyResolution;+ if (!resolution) {+ if (req.actor.type === "agent" && req.actor.companyId) return req.actor.companyId;+ return null;+ }++ if (resolution.from === "body") {+ const body = req.body as Record<string, unknown> | undefined;+ const companyId = body?.[resolution.key ?? ""];+ return typeof companyId === "string" ? companyId : null;+ }++ if (resolution.from === "query") {+ const value = req.query[resolution.key ?? ""];+ return typeof value === "string" ? value : null;+ }++ const issueId = params[resolution.param ?? ""];+ if (!issueId) return null;+ const issue = await issuesSvc.getById(issueId);+ return issue?.companyId ?? null;+ }++ function assertScopedApiAuth(req: Request, route: PluginApiRouteDeclaration) {+ if (route.auth === "board") {+ assertBoard(req);+ return;+ }+ if (route.auth === "agent") {+ assertAuthenticated(req);+ if (req.actor.type !== "agent") throw forbidden("Agent access required");+ return;+ }+ if (route.auth === "webhook") {+ throw unprocessable("Webhook-scoped plugin API routes require a signature verifier and are not enabled");+ }+ assertAuthenticated(req);+ if (req.actor.type !== "board" && req.actor.type !== "agent") {+ throw forbidden("Board or agent access required");+ }+ }++ async function enforceScopedApiCheckout(+ req: Request,+ route: PluginApiRouteDeclaration,+ params: Record<string, string>,+ companyId: string,+ ) {+ const policy = route.checkoutPolicy ?? "none";+ if (policy === "none" || req.actor.type !== "agent") return;+ const issueId = params.issueId;+ if (!issueId) {+ throw unprocessable("Checkout-protected plugin API routes require an issueId route parameter");+ }+ const issue = await issuesSvc.getById(issueId);+ if (!issue || issue.companyId !== companyId) {+ throw notFound("Issue not found");+ }+ if (policy === "required-for-agent-in-progress") {+ if (issue.status !== "in_progress" || issue.assigneeAgentId !== req.actor.agentId) return;+ }+ const runId = req.actor.runId?.trim();+ if (!runId) {+ throw unauthorized("Agent run id required");+ }+ if (!req.actor.agentId) {+ throw forbidden("Agent authentication required");+ }+ await issuesSvc.assertCheckoutOwner(issueId, req.actor.agentId, runId);+ }async function resolvePluginAuditCompanyIds(req: Request): Promise<string[]> {if (typeof (db as { select?: unknown }).select === "function") {@@ -1189,6 +1379,113 @@ export function pluginRoutes(res.on("error", safeUnsubscribe);});+ router.use("/plugins/:pluginId/api", async (req, res) => {+ if (!bridgeDeps) {+ res.status(501).json({ error: "Plugin scoped API routes are 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(503).json({ error: `Plugin is not ready (current status: ${plugin.status})` });+ return;+ }+ const isWorkerRunning = typeof bridgeDeps.workerManager.isRunning === "function"+ ? bridgeDeps.workerManager.isRunning(plugin.id)+ : true;+ if (!isWorkerRunning) {+ res.status(503).json({ error: "Plugin worker is not running" });+ return;+ }+ if (!plugin.manifestJson.capabilities.includes("api.routes.register")) {+ res.status(404).json({ error: "Plugin does not expose scoped API routes" });+ return;+ }++ const requestPath = req.path || "/";+ const routes = plugin.manifestJson.apiRoutes ?? [];+ const match = routes+ .map((route) => ({ route, params: matchScopedApiRoute(route, req.method, requestPath) }))+ .find((candidate) => candidate.params !== null);+ if (!match || !match.params) {+ res.status(404).json({ error: "Plugin API route not found" });+ return;+ }++ try {+ assertScopedApiAuth(req, match.route);+ const companyId = await resolveScopedApiCompanyId(match.route, match.params, req);+ if (!companyId) {+ res.status(400).json({ error: "Unable to resolve company for plugin API route" });+ return;+ }+ assertCompanyAccess(req, companyId);+ await enforceScopedApiCheckout(req, match.route, match.params, companyId);+ if (req.method !== "GET" && req.headers["content-type"] && !req.is("application/json")) {+ res.status(415).json({ error: "Plugin API routes accept JSON requests only" });+ return;+ }+ const requestBody = req.body ?? null;+ const bodySize = Buffer.byteLength(JSON.stringify(requestBody));+ if (bodySize > PLUGIN_API_BODY_LIMIT_BYTES) {+ res.status(413).json({ error: "Plugin API request body is too large" });+ return;+ }++ const actor = getActorInfo(req);+ const input: PluginScopedApiRequest = {+ routeKey: match.route.routeKey,+ method: req.method,+ path: requestPath,+ params: match.params,+ query: normalizeQuery(req.query),+ body: requestBody,+ actor: {+ actorType: actor.actorType,+ actorId: actor.actorId,+ agentId: actor.agentId,+ userId: actor.actorType === "user" ? actor.actorId : null,+ runId: actor.runId,+ },+ companyId,+ headers: sanitizePluginRequestHeaders(req),+ };++ const result = await bridgeDeps.workerManager.call(+ plugin.id,+ "handleApiRequest",+ input,+ ) as PluginScopedApiResponse;+ const status = Number.isInteger(result.status) && Number(result.status) >= 200 && Number(result.status) <= 599+ ? Number(result.status)+ : 200;+ applyPluginScopedApiResponseHeaders(res, result.headers);+ if (status === 204) {+ res.status(status).end();+ } else {+ res.status(status).json(result.body ?? null);+ }+ } catch (err) {+ const status = typeof (err as { status?: unknown }).status === "number"+ ? (err as { status: number }).status+ : err instanceof JsonRpcCallError && err.code === PLUGIN_RPC_ERROR_CODES.CAPABILITY_DENIED+ ? 403+ : err instanceof JsonRpcCallError && err.code === PLUGIN_RPC_ERROR_CODES.METHOD_NOT_IMPLEMENTED+ ? 501+ : err instanceof JsonRpcCallError+ ? 502+ : 500;+ res.status(status).json({+ error: err instanceof Error ? err.message : String(err),+ });+ }+ });+/*** GET /api/plugins/:pluginId*diff --git a/server/src/services/activity-log.ts b/server/src/services/activity-log.tsindex cc608a7454..473a1d787b 100644--- a/server/src/services/activity-log.ts+++ b/server/src/services/activity-log.ts@@ -11,6 +11,20 @@ import type { PluginEventBus } from "./plugin-event-bus.js";import { instanceSettingsService } from "./instance-settings.js";const PLUGIN_EVENT_SET: ReadonlySet<string> = new Set(PLUGIN_EVENT_TYPES);+const ACTIVITY_ACTION_TO_PLUGIN_EVENT: Readonly<Record<string, PluginEventType>> = {+ issue_comment_added: "issue.comment.created",+ issue_comment_created: "issue.comment.created",+ issue_document_created: "issue.document.created",+ issue_document_updated: "issue.document.updated",+ issue_document_deleted: "issue.document.deleted",+ issue_blockers_updated: "issue.relations.updated",+ approval_approved: "approval.decided",+ approval_rejected: "approval.decided",+ approval_revision_requested: "approval.decided",+ budget_soft_threshold_crossed: "budget.incident.opened",+ budget_hard_threshold_crossed: "budget.incident.opened",+ budget_incident_resolved: "budget.incident.resolved",+};let _pluginEventBus: PluginEventBus | null = null;@@ -22,9 +36,23 @@ export function setPluginEventBus(bus: PluginEventBus): void {_pluginEventBus = bus;}+function eventTypeForActivityAction(action: string): PluginEventType | null {+ if (PLUGIN_EVENT_SET.has(action)) return action as PluginEventType;+ return ACTIVITY_ACTION_TO_PLUGIN_EVENT[action.replaceAll(".", "_")] ?? null;+}++export function publishPluginDomainEvent(event: PluginEvent): void {+ if (!_pluginEventBus) return;+ void _pluginEventBus.emit(event).then(({ errors }) => {+ for (const { pluginId, error } of errors) {+ logger.warn({ pluginId, eventType: event.eventType, err: error }, "plugin event handler failed");+ }+ }).catch(() => {});+}+export interface LogActivityInput {companyId: string;- actorType: "agent" | "user" | "system";+ actorType: "agent" | "user" | "system" | "plugin";actorId: string;action: string;entityType: string;@@ -69,10 +97,11 @@ export async function logActivity(db: Db, input: LogActivityInput) {},});- if (_pluginEventBus && PLUGIN_EVENT_SET.has(input.action)) {+ const pluginEventType = eventTypeForActivityAction(input.action);+ if (pluginEventType) {const event: PluginEvent = {eventId: randomUUID(),- eventType: input.action as PluginEventType,+ eventType: pluginEventType,occurredAt: new Date().toISOString(),actorId: input.actorId,actorType: input.actorType,@@ -85,10 +114,6 @@ export async function logActivity(db: Db, input: LogActivityInput) {runId: input.runId ?? null,},};- void _pluginEventBus.emit(event).then(({ errors }) => {- for (const { pluginId, error } of errors) {- logger.warn({ pluginId, eventType: event.eventType, err: error }, "plugin event handler failed");- }- }).catch(() => {});+ publishPluginDomainEvent(event);}}diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.tsindex 75987703a6..bfc1c79fca 100644--- a/server/src/services/heartbeat.ts+++ b/server/src/services/heartbeat.ts@@ -2,6 +2,7 @@ import fs from "node:fs/promises";import path from "node:path";import { execFile as execFileCallback } from "node:child_process";import { promisify } from "node:util";+import { randomUUID } from "node:crypto";import { and, asc, desc, eq, getTableColumns, gt, inArray, isNull, or, sql } from "drizzle-orm";import type { Db } from "@paperclipai/db";import {@@ -60,7 +61,7 @@ import {classifyRunLiveness,type RunLivenessClassificationInput,} from "./run-liveness.js";-import { logActivity, type LogActivityInput } from "./activity-log.js";+import { logActivity, publishPluginDomainEvent, type LogActivityInput } from "./activity-log.js";import {buildWorkspaceReadyComment,cleanupExecutionWorkspaceArtifacts,@@ -2377,11 +2378,50 @@ export function heartbeatService(db: Db) {finishedAt: updated.finishedAt ? new Date(updated.finishedAt).toISOString() : null,},});+ publishRunLifecyclePluginEvent(updated);}return updated;}+ function publishRunLifecyclePluginEvent(run: typeof heartbeatRuns.$inferSelect) {+ const eventType =+ run.status === "running"+ ? "agent.run.started"+ : run.status === "succeeded"+ ? "agent.run.finished"+ : run.status === "failed" || run.status === "timed_out"+ ? "agent.run.failed"+ : run.status === "cancelled"+ ? "agent.run.cancelled"+ : null;+ if (!eventType) return;+ publishPluginDomainEvent({+ eventId: randomUUID(),+ eventType,+ occurredAt: new Date().toISOString(),+ actorId: run.agentId,+ actorType: "agent",+ entityId: run.id,+ entityType: "heartbeat_run",+ companyId: run.companyId,+ payload: {+ runId: run.id,+ agentId: run.agentId,+ status: run.status,+ invocationSource: run.invocationSource,+ triggerDetail: run.triggerDetail,+ error: run.error ?? null,+ errorCode: run.errorCode ?? null,+ issueId: typeof run.contextSnapshot === "object" && run.contextSnapshot !== null+ ? (run.contextSnapshot as Record<string, unknown>).issueId ?? null+ : null,+ startedAt: run.startedAt ? new Date(run.startedAt).toISOString() : null,+ finishedAt: run.finishedAt ? new Date(run.finishedAt).toISOString() : null,+ },+ });+ }+async function setWakeupStatus(wakeupRequestId: string | null | undefined,status: string,@@ -3054,6 +3094,7 @@ export function heartbeatService(db: Db) {finishedAt: claimed.finishedAt ? new Date(claimed.finishedAt).toISOString() : null,},});+ publishRunLifecyclePluginEvent(claimed);await setWakeupStatus(claimed.wakeupRequestId, "claimed", { claimedAt });diff --git a/server/src/services/plugin-capability-validator.ts b/server/src/services/plugin-capability-validator.tsindex 0d4bb2a739..f064719219 100644--- a/server/src/services/plugin-capability-validator.ts+++ b/server/src/services/plugin-capability-validator.ts@@ -51,6 +51,7 @@ const OPERATION_CAPABILITIES: Record<string, readonly PluginCapability[]> = {"project.workspaces.get": ["project.workspaces.read"],"issues.list": ["issues.read"],"issues.get": ["issues.read"],+ "issues.relations.get": ["issue.relations.read"],"issue.comments.list": ["issue.comments.read"],"issue.comments.get": ["issue.comments.read"],"agents.list": ["agents.read"],@@ -61,14 +62,26 @@ const OPERATION_CAPABILITIES: Record<string, readonly PluginCapability[]> = {"activity.get": ["activity.read"],"costs.list": ["costs.read"],"costs.get": ["costs.read"],+ "issues.summaries.getOrchestration": ["issues.orchestration.read"],+ "db.namespace": ["database.namespace.read"],+ "db.query": ["database.namespace.read"],// Data write operations"issues.create": ["issues.create"],"issues.update": ["issues.update"],+ "issues.relations.setBlockedBy": ["issue.relations.write"],+ "issues.relations.addBlockers": ["issue.relations.write"],+ "issues.relations.removeBlockers": ["issue.relations.write"],+ "issues.assertCheckoutOwner": ["issues.checkout"],+ "issues.getSubtree": ["issue.subtree.read"],+ "issues.requestWakeup": ["issues.wakeup"],+ "issues.requestWakeups": ["issues.wakeup"],"issue.comments.create": ["issue.comments.create"],"activity.log": ["activity.log.write"],"metrics.write": ["metrics.write"],"telemetry.track": ["telemetry.track"],+ "db.migrate": ["database.namespace.migrate"],+ "db.execute": ["database.namespace.write"],// Plugin state operations"plugin.state.get": ["plugin.state.read"],@@ -141,6 +154,7 @@ const FEATURE_CAPABILITIES: Record<string, PluginCapability> = {tools: "agent.tools.register",jobs: "jobs.schedule",webhooks: "webhooks.receive",+ database: "database.namespace.migrate",};// ---------------------------------------------------------------------------diff --git a/server/src/services/plugin-database.ts b/server/src/services/plugin-database.tsnew file mode 100644index 0000000000..e1822e45cd--- /dev/null+++ b/server/src/services/plugin-database.ts@@ -0,0 +1,498 @@+import { createHash } from "node:crypto";+import { readdir, readFile } from "node:fs/promises";+import path from "node:path";+import { and, eq, sql } from "drizzle-orm";+import type { SQL } from "drizzle-orm";+import type { Db } from "@paperclipai/db";+import {+ pluginDatabaseNamespaces,+ pluginMigrations,+ plugins,+} from "@paperclipai/db";+import type {+ PaperclipPluginManifestV1,+ PluginDatabaseCoreReadTable,+ PluginMigrationRecord,+} from "@paperclipai/shared";++const IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;+const MAX_POSTGRES_IDENTIFIER_LENGTH = 63;++type SqlRef = { schema: string; table: string; keyword: string };++export type PluginDatabaseRuntimeResult<T = Record<string, unknown>> = {+ rows?: T[];+ rowCount?: number;+};++export function derivePluginDatabaseNamespace(+ pluginKey: string,+ namespaceSlug?: string,+): string {+ const hash = createHash("sha256").update(pluginKey).digest("hex").slice(0, 10);+ const slug = (namespaceSlug ?? pluginKey)+ .toLowerCase()+ .replace(/[^a-z0-9_]+/g, "_")+ .replace(/^_+|_+$/g, "")+ .replace(/_+/g, "_")+ .slice(0, 36) || "plugin";+ const namespace = `plugin_${slug}_${hash}`;+ return namespace.slice(0, MAX_POSTGRES_IDENTIFIER_LENGTH);+}++function assertIdentifier(value: string, label = "identifier"): string {+ if (!IDENTIFIER_RE.test(value)) {+ throw new Error(`Unsafe SQL ${label}: ${value}`);+ }+ return value;+}++function quoteIdentifier(value: string): string {+ return `"${assertIdentifier(value).replaceAll("\"", "\"\"")}"`;+}++function splitSqlStatements(input: string): string[] {+ const statements: string[] = [];+ let start = 0;+ let quote: "'" | "\"" | null = null;+ let lineComment = false;+ let blockComment = false;++ for (let i = 0; i < input.length; i += 1) {+ const char = input[i]!;+ const next = input[i + 1];++ if (lineComment) {+ if (char === "\n") lineComment = false;+ continue;+ }+ if (blockComment) {+ if (char === "*" && next === "/") {+ blockComment = false;+ i += 1;+ }+ continue;+ }+ if (quote) {+ if (char === quote) {+ if (next === quote) {+ i += 1;+ } else {+ quote = null;+ }+ }+ continue;+ }+ if (char === "-" && next === "-") {+ lineComment = true;+ i += 1;+ continue;+ }+ if (char === "/" && next === "*") {+ blockComment = true;+ i += 1;+ continue;+ }+ if (char === "'" || char === "\"") {+ quote = char;+ continue;+ }+ if (char === ";") {+ const statement = input.slice(start, i).trim();+ if (statement) statements.push(statement);+ start = i + 1;+ }+ }++ const trailing = input.slice(start).trim();+ if (trailing) statements.push(trailing);+ return statements;+}++function stripSqlForKeywordScan(input: string): string {+ return input+ .replace(/'([^']|'')*'/g, "''")+ .replace(/"([^"]|"")*"/g, "\"\"")+ .replace(/--.*$/gm, "")+ .replace(/\/\*[\s\S]*?\*\//g, "");+}++function normaliseSql(input: string): string {+ return stripSqlForKeywordScan(input).replace(/\s+/g, " ").trim().toLowerCase();+}++function extractQualifiedRefs(statement: string): SqlRef[] {+ const refs: SqlRef[] = [];+ const patterns = [+ /\b(from|join|references|into|update)\s+"?([A-Za-z_][A-Za-z0-9_]*)"?\."?([A-Za-z_][A-Za-z0-9_]*)"?/gi,+ /\b(alter\s+table|create\s+table|create\s+view|drop\s+table|truncate\s+table)\s+(?:if\s+(?:not\s+)?exists\s+)?"?([A-Za-z_][A-Za-z0-9_]*)"?\."?([A-Za-z_][A-Za-z0-9_]*)"?/gi,+ ];++ for (const pattern of patterns) {+ for (const match of statement.matchAll(pattern)) {+ refs.push({ keyword: match[1]!.toLowerCase(), schema: match[2]!, table: match[3]! });+ }+ }+ return refs;+}++function assertAllowedPublicRead(+ ref: SqlRef,+ allowedCoreReadTables: ReadonlySet<string>,+): void {+ if (ref.schema !== "public") return;+ if (!allowedCoreReadTables.has(ref.table)) {+ throw new Error(`Plugin SQL references public.${ref.table}, which is not whitelisted`);+ }+ if (!["from", "join", "references"].includes(ref.keyword)) {+ throw new Error(`Plugin SQL cannot mutate or define objects in public.${ref.table}`);+ }+}++function assertNoBannedSql(statement: string): void {+ const normalized = normaliseSql(statement);+ const banned = [+ /\bcreate\s+extension\b/,+ /\bcreate\s+(?:event\s+)?trigger\b/,+ /\bcreate\s+(?:or\s+replace\s+)?function\b/,+ /\bcreate\s+language\b/,+ /\bgrant\b/,+ /\brevoke\b/,+ /\bsecurity\s+definer\b/,+ /\bcopy\b/,+ /\bcall\b/,+ /\bdo\s+(?:\$\$|language\b)/,+ ];+ const matched = banned.find((pattern) => pattern.test(normalized));+ if (matched) {+ throw new Error(`Plugin SQL contains a disallowed statement or clause: ${matched.source}`);+ }+}++export function validatePluginMigrationStatement(+ statement: string,+ namespace: string,+ coreReadTables: readonly PluginDatabaseCoreReadTable[] = [],+): void {+ assertIdentifier(namespace, "namespace");+ assertNoBannedSql(statement);++ const normalized = normaliseSql(statement);+ if (/^\s*(drop|truncate)\b/.test(normalized)) {+ throw new Error("Destructive plugin migrations are not allowed in Phase 1");+ }++ const ddlAllowed = /^(create|alter|comment)\b/.test(normalized);+ if (!ddlAllowed) {+ throw new Error("Plugin migrations may contain DDL statements only");+ }++ const refs = extractQualifiedRefs(statement);+ if (refs.length === 0 && !normalized.startsWith("comment ")) {+ throw new Error("Plugin migration objects must use fully qualified schema names");+ }++ const allowedCoreReadTables = new Set(coreReadTables);+ for (const ref of refs) {+ if (ref.schema === namespace) continue;+ if (ref.schema === "public") {+ assertAllowedPublicRead(ref, allowedCoreReadTables);+ continue;+ }+ throw new Error(`Plugin SQL references schema "${ref.schema}" outside namespace "${namespace}"`);+ }+}++export function validatePluginRuntimeQuery(+ query: string,+ namespace: string,+ coreReadTables: readonly PluginDatabaseCoreReadTable[] = [],+): void {+ const statements = splitSqlStatements(query);+ if (statements.length !== 1) {+ throw new Error("Plugin runtime SQL must contain exactly one statement");+ }+ const statement = statements[0]!;+ assertNoBannedSql(statement);+ const normalized = normaliseSql(statement);+ if (!normalized.startsWith("select ") && !normalized.startsWith("with ")) {+ throw new Error("ctx.db.query only allows SELECT statements");+ }+ if (/\b(insert|update|delete|alter|create|drop|truncate)\b/.test(normalized)) {+ throw new Error("ctx.db.query cannot contain mutation or DDL keywords");+ }++ const allowedCoreReadTables = new Set(coreReadTables);+ for (const ref of extractQualifiedRefs(statement)) {+ if (ref.schema === namespace) continue;+ if (ref.schema === "public") {+ assertAllowedPublicRead(ref, allowedCoreReadTables);+ continue;+ }+ throw new Error(`ctx.db.query cannot read schema "${ref.schema}"`);+ }+}++export function validatePluginRuntimeExecute(query: string, namespace: string): void {+ const statements = splitSqlStatements(query);+ if (statements.length !== 1) {+ throw new Error("Plugin runtime SQL must contain exactly one statement");+ }+ const statement = statements[0]!;+ assertNoBannedSql(statement);+ const normalized = normaliseSql(statement);+ if (!/^(insert\s+into|update|delete\s+from)\b/.test(normalized)) {+ throw new Error("ctx.db.execute only allows INSERT, UPDATE, or DELETE");+ }+ if (/\b(alter|create|drop|truncate)\b/.test(normalized)) {+ throw new Error("ctx.db.execute cannot contain DDL keywords");+ }++ const refs = extractQualifiedRefs(statement);+ const target = refs.find((ref) => ["into", "update", "from"].includes(ref.keyword));+ if (!target || target.schema !== namespace) {+ throw new Error(`ctx.db.execute target must be inside plugin namespace "${namespace}"`);+ }+ for (const ref of refs) {+ if (ref.schema !== namespace) {+ throw new Error("ctx.db.execute cannot reference public or other non-plugin schemas");+ }+ }+}++function bindSql(statement: string, params: readonly unknown[] = []): SQL {+ // Safe only after callers run the plugin SQL validators above.+ if (params.length === 0) return sql.raw(statement);+ const chunks: SQL[] = [];+ let cursor = 0;+ const placeholderPattern = /\$(\d+)/g;+ const seen = new Set<number>();++ for (const match of statement.matchAll(placeholderPattern)) {+ const index = Number(match[1]);+ if (!Number.isInteger(index) || index < 1 || index > params.length) {+ throw new Error(`SQL placeholder $${match[1]} has no matching parameter`);+ }+ chunks.push(sql.raw(statement.slice(cursor, match.index)));+ chunks.push(sql`${params[index - 1]}`);+ seen.add(index);+ cursor = match.index! + match[0].length;+ }+ chunks.push(sql.raw(statement.slice(cursor)));+ if (seen.size !== params.length) {+ throw new Error("Every ctx.db parameter must be referenced by a $n placeholder");+ }+ return sql.join(chunks, sql.raw(""));+}++async function listSqlMigrationFiles(migrationsDir: string): Promise<string[]> {+ const entries = await readdir(migrationsDir, { withFileTypes: true });+ return entries+ .filter((entry) => entry.isFile() && entry.name.endsWith(".sql"))+ .map((entry) => entry.name)+ .sort((a, b) => a.localeCompare(b));+}++function resolveMigrationsDir(packageRoot: string, migrationsDir: string): string {+ const resolvedRoot = path.resolve(packageRoot);+ const resolvedDir = path.resolve(resolvedRoot, migrationsDir);+ const relative = path.relative(resolvedRoot, resolvedDir);+ if (relative.startsWith("..") || path.isAbsolute(relative)) {+ throw new Error(`Plugin migrationsDir escapes package root: ${migrationsDir}`);+ }+ return resolvedDir;+}++export function pluginDatabaseService(db: Db) {+ async function getPluginRecord(pluginId: string) {+ const rows = await db.select().from(plugins).where(eq(plugins.id, pluginId)).limit(1);+ const plugin = rows[0];+ if (!plugin) throw new Error(`Plugin not found: ${pluginId}`);+ return plugin;+ }++ async function ensureNamespace(pluginId: string, manifest: PaperclipPluginManifestV1) {+ if (!manifest.database) return null;+ const namespaceName = derivePluginDatabaseNamespace(+ manifest.id,+ manifest.database.namespaceSlug,+ );+ await db.execute(sql.raw(`CREATE SCHEMA IF NOT EXISTS ${quoteIdentifier(namespaceName)}`));+ const rows = await db+ .insert(pluginDatabaseNamespaces)+ .values({+ pluginId,+ pluginKey: manifest.id,+ namespaceName,+ namespaceMode: "schema",+ status: "active",+ })+ .onConflictDoUpdate({+ target: pluginDatabaseNamespaces.pluginId,+ set: {+ pluginKey: manifest.id,+ namespaceName,+ namespaceMode: "schema",+ status: "active",+ updatedAt: new Date(),+ },+ })+ .returning();+ return rows[0] ?? null;+ }++ async function getNamespace(pluginId: string) {+ const rows = await db+ .select()+ .from(pluginDatabaseNamespaces)+ .where(eq(pluginDatabaseNamespaces.pluginId, pluginId))+ .limit(1);+ return rows[0] ?? null;+ }++ async function getRuntimeNamespace(pluginId: string) {+ const namespace = await getNamespace(pluginId);+ if (!namespace || namespace.status !== "active") {+ throw new Error("Plugin database namespace is not active");+ }+ return namespace.namespaceName;+ }++ async function recordMigrationFailure(input: {+ pluginId: string;+ pluginKey: string;+ namespaceName: string;+ migrationKey: string;+ checksum: string;+ pluginVersion: string;+ error: unknown;+ }): Promise<void> {+ const message = input.error instanceof Error ? input.error.message : String(input.error);+ await db+ .insert(pluginMigrations)+ .values({+ pluginId: input.pluginId,+ pluginKey: input.pluginKey,+ namespaceName: input.namespaceName,+ migrationKey: input.migrationKey,+ checksum: input.checksum,+ pluginVersion: input.pluginVersion,+ status: "failed",+ errorMessage: message,+ })+ .onConflictDoUpdate({+ target: [pluginMigrations.pluginId, pluginMigrations.migrationKey],+ set: {+ checksum: input.checksum,+ pluginVersion: input.pluginVersion,+ status: "failed",+ errorMessage: message,+ startedAt: new Date(),+ appliedAt: null,+ },+ });+ await db+ .update(pluginDatabaseNamespaces)+ .set({ status: "migration_failed", updatedAt: new Date() })+ .where(eq(pluginDatabaseNamespaces.pluginId, input.pluginId));+ }++ return {+ ensureNamespace,++ async applyMigrations(pluginId: string, manifest: PaperclipPluginManifestV1, packageRoot: string) {+ if (!manifest.database) return null;+ const namespace = await ensureNamespace(pluginId, manifest);+ if (!namespace) return null;++ const migrationDir = resolveMigrationsDir(packageRoot, manifest.database.migrationsDir);+ const migrationFiles = await listSqlMigrationFiles(migrationDir);+ const coreReadTables = manifest.database.coreReadTables ?? [];+ const lockKey = Number.parseInt(createHash("sha256").update(pluginId).digest("hex").slice(0, 12), 16);++ await db.transaction(async (tx) => {+ await tx.execute(sql`SELECT pg_advisory_xact_lock(${lockKey})`);+ for (const migrationKey of migrationFiles) {+ const content = await readFile(path.join(migrationDir, migrationKey), "utf8");+ const checksum = createHash("sha256").update(content).digest("hex");+ const existingRows = await tx+ .select()+ .from(pluginMigrations)+ .where(and(eq(pluginMigrations.pluginId, pluginId), eq(pluginMigrations.migrationKey, migrationKey)))+ .limit(1);+ const existing = existingRows[0] as PluginMigrationRecord | undefined;+ if (existing?.status === "applied") {+ if (existing.checksum !== checksum) {+ throw new Error(`Plugin migration checksum mismatch for ${migrationKey}`);+ }+ continue;+ }++ const statements = splitSqlStatements(content);+ try {+ if (statements.length === 0) {+ throw new Error(`Plugin migration ${migrationKey} is empty`);+ }+ for (const statement of statements) {+ validatePluginMigrationStatement(statement, namespace.namespaceName, coreReadTables);+ await tx.execute(sql.raw(statement));+ }+ await tx+ .insert(pluginMigrations)+ .values({+ pluginId,+ pluginKey: manifest.id,+ namespaceName: namespace.namespaceName,+ migrationKey,+ checksum,+ pluginVersion: manifest.version,+ status: "applied",+ appliedAt: new Date(),+ })+ .onConflictDoUpdate({+ target: [pluginMigrations.pluginId, pluginMigrations.migrationKey],+ set: {+ checksum,+ pluginVersion: manifest.version,+ status: "applied",+ errorMessage: null,+ startedAt: new Date(),+ appliedAt: new Date(),+ },+ });+ } catch (error) {+ await recordMigrationFailure({+ pluginId,+ pluginKey: manifest.id,+ namespaceName: namespace.namespaceName,+ migrationKey,+ checksum,+ pluginVersion: manifest.version,+ error,+ });+ throw error;+ }+ }+ });++ return namespace;+ },++ getRuntimeNamespace,++ async query<T = Record<string, unknown>>(pluginId: string, statement: string, params?: unknown[]): Promise<T[]> {+ const plugin = await getPluginRecord(pluginId);+ const namespace = await getRuntimeNamespace(pluginId);+ validatePluginRuntimeQuery(statement, namespace, plugin.manifestJson.database?.coreReadTables ?? []);+ const result = await db.execute(bindSql(statement, params));+ return Array.from(result as Iterable<T>);+ },++ async execute(pluginId: string, statement: string, params?: unknown[]): Promise<{ rowCount: number }> {+ const namespace = await getRuntimeNamespace(pluginId);+ validatePluginRuntimeExecute(statement, namespace);+ const result = await db.execute(bindSql(statement, params));+ return { rowCount: Number((result as { count?: number | string }).count ?? 0) };+ },+ };+}diff --git a/server/src/services/plugin-host-services.ts b/server/src/services/plugin-host-services.tsindex 22ccb01708..6a8ba88ef8 100644--- a/server/src/services/plugin-host-services.ts+++ b/server/src/services/plugin-host-services.ts@@ -1,6 +1,14 @@import type { Db } from "@paperclipai/db";-import { pluginLogs, agentTaskSessions as agentTaskSessionsTable } from "@paperclipai/db";-import { eq, and, like, desc } from "drizzle-orm";+import {+ agentTaskSessions as agentTaskSessionsTable,+ agents as agentsTable,+ budgetIncidents,+ costEvents,+ heartbeatRuns,+ issues as issuesTable,+ pluginLogs,+} from "@paperclipai/db";+import { eq, and, like, desc, inArray, sql } from "drizzle-orm";import type {HostServices,Company,@@ -10,7 +18,10 @@ import type {Goal,PluginWorkspace,IssueComment,+ PluginIssueAssigneeSummary,+ PluginIssueOrchestrationSummary,} from "@paperclipai/plugin-sdk";+import type { IssueDocumentSummary } from "@paperclipai/shared";import { companyService } from "./companies.js";import { agentService } from "./agents.js";import { projectService } from "./projects.js";@@ -18,6 +29,8 @@ import { issueService } from "./issues.js";import { goalService } from "./goals.js";import { documentService } from "./documents.js";import { heartbeatService } from "./heartbeat.js";+import { budgetService } from "./budgets.js";+import { issueApprovalService } from "./issue-approvals.js";import { subscribeCompanyLiveEvents } from "./live-events.js";import { randomUUID } from "node:crypto";import { activityService } from "./activity.js";@@ -25,6 +38,7 @@ import { costService } from "./costs.js";import { assetService } from "./assets.js";import { pluginRegistryService } from "./plugin-registry.js";import { pluginStateStore } from "./plugin-state-store.js";+import { pluginDatabaseService } from "./plugin-database.js";import { createPluginSecretsHandler } from "./plugin-secrets-handler.js";import { logActivity } from "./activity-log.js";import type { PluginEventBus } from "./plugin-event-bus.js";@@ -447,6 +461,7 @@ export function buildHostServices(): HostServices & { dispose(): void } {const registry = pluginRegistryService(db);const stateStore = pluginStateStore(db);+ const pluginDb = pluginDatabaseService(db);const secretsHandler = createPluginSecretsHandler({ db, pluginId });const companies = companyService(db);const agents = agentService(db);@@ -457,6 +472,8 @@ export function buildHostServices(const goals = goalService(db);const activity = activityService(db);const costs = costService(db);+ const budgets = budgetService(db);+ const issueApprovals = issueApprovalService(db);const assets = assetService(db);const scopedBus = eventBus.forPlugin(pluginKey);@@ -512,6 +529,216 @@ export function buildHostServices(return record;};+ const pluginActivityDetails = (+ details: Record<string, unknown> | null | undefined,+ actor?: { actorAgentId?: string | null; actorUserId?: string | null; actorRunId?: string | null },+ ) => {+ const initiatingActorType = actor?.actorAgentId ? "agent" : actor?.actorUserId ? "user" : null;+ const initiatingActorId = actor?.actorAgentId ?? actor?.actorUserId ?? null;+ return {+ ...(details ?? {}),+ sourcePluginId: pluginId,+ sourcePluginKey: pluginKey,+ initiatingActorType,+ initiatingActorId,+ initiatingAgentId: actor?.actorAgentId ?? null,+ initiatingUserId: actor?.actorUserId ?? null,+ initiatingRunId: actor?.actorRunId ?? null,+ pluginId,+ pluginKey,+ };+ };++ const defaultPluginOriginKind = `plugin:${pluginKey}`;+ const normalizePluginOriginKind = (originKind: unknown = defaultPluginOriginKind) => {+ if (originKind == null || originKind === "") return defaultPluginOriginKind;+ if (typeof originKind !== "string") {+ throw new Error("Plugin issue originKind must be a string");+ }+ if (originKind === defaultPluginOriginKind || originKind.startsWith(`${defaultPluginOriginKind}:`)) {+ return originKind;+ }+ throw new Error(`Plugin may only use originKind values under ${defaultPluginOriginKind}`);+ };++ const assertReadableOriginFilter = (originKind: unknown) => {+ if (typeof originKind !== "string" || !originKind.startsWith("plugin:")) return;+ normalizePluginOriginKind(originKind);+ };++ const logPluginActivity = async (input: {+ companyId: string;+ action: string;+ entityType: string;+ entityId: string;+ details?: Record<string, unknown> | null;+ actor?: { actorAgentId?: string | null; actorUserId?: string | null; actorRunId?: string | null };+ }) => {+ await logActivity(db, {+ companyId: input.companyId,+ actorType: "plugin",+ actorId: pluginId,+ agentId: input.actor?.actorAgentId ?? null,+ runId: input.actor?.actorRunId ?? null,+ action: input.action,+ entityType: input.entityType,+ entityId: input.entityId,+ details: pluginActivityDetails(input.details, input.actor),+ });+ };++ const collectIssueSubtreeIds = async (companyId: string, rootIssueId: string) => {+ const seen = new Set<string>([rootIssueId]);+ let frontier = [rootIssueId];++ while (frontier.length > 0) {+ const children = await db+ .select({ id: issuesTable.id })+ .from(issuesTable)+ .where(and(eq(issuesTable.companyId, companyId), inArray(issuesTable.parentId, frontier)));+ frontier = children.map((child) => child.id).filter((id) => !seen.has(id));+ for (const id of frontier) seen.add(id);+ }++ return [...seen];+ };++ const getIssueRunSummaries = async (+ companyId: string,+ issueIds: string[],+ options: { activeOnly?: boolean } = {},+ ) => {+ if (issueIds.length === 0) return [];+ const issueIdExpr = sql<string | null>`${heartbeatRuns.contextSnapshot} ->> 'issueId'`;+ const statusCondition = options.activeOnly+ ? inArray(heartbeatRuns.status, ["queued", "running"])+ : undefined;+ const rows = await db+ .select({+ id: heartbeatRuns.id,+ issueId: issueIdExpr,+ agentId: heartbeatRuns.agentId,+ status: heartbeatRuns.status,+ invocationSource: heartbeatRuns.invocationSource,+ triggerDetail: heartbeatRuns.triggerDetail,+ startedAt: heartbeatRuns.startedAt,+ finishedAt: heartbeatRuns.finishedAt,+ error: heartbeatRuns.error,+ createdAt: heartbeatRuns.createdAt,+ })+ .from(heartbeatRuns)+ .where(and(eq(heartbeatRuns.companyId, companyId), inArray(issueIdExpr, issueIds), statusCondition))+ .orderBy(desc(heartbeatRuns.createdAt))+ .limit(100);++ return rows.map((row) => ({+ ...row,+ startedAt: row.startedAt?.toISOString() ?? null,+ finishedAt: row.finishedAt?.toISOString() ?? null,+ createdAt: row.createdAt.toISOString(),+ }));+ };++ const setBlockedByWithActivity = async (params: {+ issueId: string;+ companyId: string;+ blockedByIssueIds: string[];+ mutation: "set" | "add" | "remove";+ actorAgentId?: string | null;+ actorUserId?: string | null;+ actorRunId?: string | null;+ }) => {+ const existing = requireInCompany("Issue", await issues.getById(params.issueId), params.companyId);+ const previous = await issues.getRelationSummaries(params.issueId);+ await issues.update(params.issueId, {+ blockedByIssueIds: params.blockedByIssueIds,+ actorAgentId: params.actorAgentId ?? null,+ actorUserId: params.actorUserId ?? null,+ } as any);+ const relations = await issues.getRelationSummaries(params.issueId);+ await logPluginActivity({+ companyId: params.companyId,+ action: "issue.relations.updated",+ entityType: "issue",+ entityId: params.issueId,+ actor: {+ actorAgentId: params.actorAgentId,+ actorUserId: params.actorUserId,+ actorRunId: params.actorRunId,+ },+ details: {+ identifier: existing.identifier,+ mutation: params.mutation,+ blockedByIssueIds: params.blockedByIssueIds,+ previousBlockedByIssueIds: previous.blockedBy.map((relation) => relation.id),+ },+ });+ return relations;+ };++ const getIssueCostSummary = async (+ companyId: string,+ issueIds: string[],+ billingCode?: string | null,+ ) => {+ const scopeConditions = [+ issueIds.length > 0 ? inArray(costEvents.issueId, issueIds) : undefined,+ billingCode ? eq(costEvents.billingCode, billingCode) : undefined,+ ].filter((condition): condition is NonNullable<typeof condition> => Boolean(condition));+ if (scopeConditions.length === 0) {+ return {+ costCents: 0,+ inputTokens: 0,+ cachedInputTokens: 0,+ outputTokens: 0,+ billingCode: billingCode ?? null,+ };+ }+ const scopeCondition = scopeConditions.length === 1 ? scopeConditions[0]! : and(...scopeConditions);+ const [row] = await db+ .select({+ costCents: sql<number>`coalesce(sum(${costEvents.costCents}), 0)::double precision`,+ inputTokens: sql<number>`coalesce(sum(${costEvents.inputTokens}), 0)::double precision`,+ cachedInputTokens: sql<number>`coalesce(sum(${costEvents.cachedInputTokens}), 0)::double precision`,+ outputTokens: sql<number>`coalesce(sum(${costEvents.outputTokens}), 0)::double precision`,+ })+ .from(costEvents)+ .where(and(eq(costEvents.companyId, companyId), scopeCondition));++ return {+ costCents: Number(row?.costCents ?? 0),+ inputTokens: Number(row?.inputTokens ?? 0),+ cachedInputTokens: Number(row?.cachedInputTokens ?? 0),+ outputTokens: Number(row?.outputTokens ?? 0),+ billingCode: billingCode ?? null,+ };+ };++ const getOpenBudgetIncidents = async (companyId: string) => {+ const rows = await db+ .select({+ id: budgetIncidents.id,+ scopeType: budgetIncidents.scopeType,+ scopeId: budgetIncidents.scopeId,+ metric: budgetIncidents.metric,+ windowKind: budgetIncidents.windowKind,+ thresholdType: budgetIncidents.thresholdType,+ amountLimit: budgetIncidents.amountLimit,+ amountObserved: budgetIncidents.amountObserved,+ status: budgetIncidents.status,+ approvalId: budgetIncidents.approvalId,+ createdAt: budgetIncidents.createdAt,+ })+ .from(budgetIncidents)+ .where(and(eq(budgetIncidents.companyId, companyId), eq(budgetIncidents.status, "open")))+ .orderBy(desc(budgetIncidents.createdAt));++ return rows.map((row) => ({+ ...row,+ createdAt: row.createdAt.toISOString(),+ }));+ };+return {config: {async get() {@@ -544,6 +771,18 @@ export function buildHostServices(},},+ db: {+ async namespace() {+ return pluginDb.getRuntimeNamespace(pluginId);+ },+ async query(params) {+ return pluginDb.query(pluginId, params.sql, params.params);+ },+ async execute(params) {+ return pluginDb.execute(pluginId, params.sql, params.params);+ },+ },+entities: {async upsert(params) {return registry.upsertEntity(pluginId, params as any) as any;@@ -604,12 +843,12 @@ export function buildHostServices(await ensurePluginAvailableForCompany(companyId);await logActivity(db, {companyId,- actorType: "system",+ actorType: "plugin",actorId: pluginId,action: params.message,entityType: params.entityType ?? "plugin",entityId: params.entityId ?? pluginId,- details: params.metadata,+ details: pluginActivityDetails(params.metadata),});},},@@ -775,6 +1014,7 @@ export function buildHostServices(async list(params) {const companyId = ensureCompanyId(params.companyId);await ensurePluginAvailableForCompany(companyId);+ assertReadableOriginFilter(params.originKind);return applyWindow((await issues.list(companyId, params as any)) as Issue[], params);},async get(params) {@@ -786,13 +1026,456 @@ export function buildHostServices(async create(params) {const companyId = ensureCompanyId(params.companyId);await ensurePluginAvailableForCompany(companyId);- return (await issues.create(companyId, params as any)) as Issue;+ const { actorAgentId, actorUserId, actorRunId, originKind, ...issueInput } = params;+ const normalizedOriginKind = normalizePluginOriginKind(originKind);+ const issue = (await issues.create(companyId, {+ ...(issueInput as any),+ originKind: normalizedOriginKind,+ originId: params.originId ?? null,+ originRunId: params.originRunId ?? actorRunId ?? null,+ createdByAgentId: actorAgentId ?? null,+ createdByUserId: actorUserId ?? null,+ })) as Issue;+ await logPluginActivity({+ companyId,+ action: "issue.created",+ entityType: "issue",+ entityId: issue.id,+ actor: { actorAgentId, actorUserId, actorRunId },+ details: {+ title: issue.title,+ identifier: issue.identifier,+ originKind: normalizedOriginKind,+ originId: issue.originId,+ billingCode: issue.billingCode,+ blockedByIssueIds: params.blockedByIssueIds ?? [],+ },+ });+ return issue;},async update(params) {+ const companyId = ensureCompanyId(params.companyId);+ await ensurePluginAvailableForCompany(companyId);+ const existing = requireInCompany("Issue", await issues.getById(params.issueId), companyId);+ const patch = { ...(params.patch as Record<string, unknown>) };+ const actorAgentId = typeof patch.actorAgentId === "string" ? patch.actorAgentId : null;+ const actorUserId = typeof patch.actorUserId === "string" ? patch.actorUserId : null;+ const actorRunId = typeof patch.actorRunId === "string" ? patch.actorRunId : null;+ delete patch.actorAgentId;+ delete patch.actorUserId;+ delete patch.actorRunId;+ if (patch.originKind !== undefined) {+ patch.originKind = normalizePluginOriginKind(patch.originKind);+ }+ const updated = (await issues.update(params.issueId, {+ ...(patch as any),+ actorAgentId,+ actorUserId,+ })) as Issue;+ await logPluginActivity({+ companyId,+ action: "issue.updated",+ entityType: "issue",+ entityId: updated.id,+ actor: { actorAgentId, actorUserId, actorRunId },+ details: {+ identifier: updated.identifier,+ patch,+ _previous: {+ status: existing.status,+ assigneeAgentId: existing.assigneeAgentId,+ assigneeUserId: existing.assigneeUserId,+ },+ },+ });+ return updated;+ },+ async getRelations(params) {+ const companyId = ensureCompanyId(params.companyId);+ await ensurePluginAvailableForCompany(companyId);+ requireInCompany("Issue", await issues.getById(params.issueId), companyId);+ return await issues.getRelationSummaries(params.issueId);+ },+ async setBlockedBy(params) {+ const companyId = ensureCompanyId(params.companyId);+ await ensurePluginAvailableForCompany(companyId);+ return setBlockedByWithActivity({+ companyId,+ issueId: params.issueId,+ blockedByIssueIds: params.blockedByIssueIds,+ mutation: "set",+ actorAgentId: params.actorAgentId,+ actorUserId: params.actorUserId,+ actorRunId: params.actorRunId,+ });+ },+ async addBlockers(params) {+ const companyId = ensureCompanyId(params.companyId);+ await ensurePluginAvailableForCompany(companyId);+ requireInCompany("Issue", await issues.getById(params.issueId), companyId);+ const previous = await issues.getRelationSummaries(params.issueId);+ const nextBlockedByIssueIds = [+ ...new Set([+ ...previous.blockedBy.map((relation) => relation.id),+ ...params.blockerIssueIds,+ ]),+ ];+ return setBlockedByWithActivity({+ companyId,+ issueId: params.issueId,+ blockedByIssueIds: nextBlockedByIssueIds,+ mutation: "add",+ actorAgentId: params.actorAgentId,+ actorUserId: params.actorUserId,+ actorRunId: params.actorRunId,+ });+ },+ async removeBlockers(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;+ const previous = await issues.getRelationSummaries(params.issueId);+ const removals = new Set(params.blockerIssueIds);+ const nextBlockedByIssueIds = previous.blockedBy+ .map((relation) => relation.id)+ .filter((issueId) => !removals.has(issueId));+ return setBlockedByWithActivity({+ companyId,+ issueId: params.issueId,+ blockedByIssueIds: nextBlockedByIssueIds,+ mutation: "remove",+ actorAgentId: params.actorAgentId,+ actorUserId: params.actorUserId,+ actorRunId: params.actorRunId,+ });+ },+ async assertCheckoutOwner(params) {+ const companyId = ensureCompanyId(params.companyId);+ await ensurePluginAvailableForCompany(companyId);+ requireInCompany("Issue", await issues.getById(params.issueId), companyId);+ const ownership = await issues.assertCheckoutOwner(+ params.issueId,+ params.actorAgentId,+ params.actorRunId,+ );+ if (ownership.adoptedFromRunId) {+ await logPluginActivity({+ companyId,+ action: "issue.checkout_lock_adopted",+ entityType: "issue",+ entityId: params.issueId,+ actor: {+ actorAgentId: params.actorAgentId,+ actorRunId: params.actorRunId,+ },+ details: {+ previousCheckoutRunId: ownership.adoptedFromRunId,+ checkoutRunId: params.actorRunId,+ reason: "stale_checkout_run",+ },+ });+ }+ return {+ issueId: ownership.id,+ status: ownership.status as Issue["status"],+ assigneeAgentId: ownership.assigneeAgentId,+ checkoutRunId: ownership.checkoutRunId,+ adoptedFromRunId: ownership.adoptedFromRunId,+ };+ },+ async getSubtree(params) {+ const companyId = ensureCompanyId(params.companyId);+ await ensurePluginAvailableForCompany(companyId);+ const rootIssue = requireInCompany("Issue", await issues.getById(params.issueId), companyId);+ const includeRoot = params.includeRoot !== false;+ const subtreeIssueIds = await collectIssueSubtreeIds(companyId, rootIssue.id);+ const issueIds = includeRoot ? subtreeIssueIds : subtreeIssueIds.filter((issueId) => issueId !== rootIssue.id);+ const issueRows = issueIds.length > 0+ ? await db+ .select()+ .from(issuesTable)+ .where(and(eq(issuesTable.companyId, companyId), inArray(issuesTable.id, issueIds)))+ : [];+ const issuesById = new Map(issueRows.map((issue) => [issue.id, issue as Issue]));+ const outputIssues = issueIds+ .map((issueId) => issuesById.get(issueId))+ .filter((issue): issue is Issue => Boolean(issue));++ const assigneeAgentIds = [+ ...new Set(outputIssues.map((issue) => issue.assigneeAgentId).filter((id): id is string => Boolean(id))),+ ];++ const [relationPairs, documentPairs, activeRunRows, assigneeRows] = await Promise.all([+ params.includeRelations+ ? Promise.all(issueIds.map(async (issueId) => [issueId, await issues.getRelationSummaries(issueId)] as const))+ : Promise.resolve(null),+ params.includeDocuments+ ? Promise.all(+ issueIds.map(async (issueId) => {+ const docs = await documents.listIssueDocuments(issueId);+ const summaries: IssueDocumentSummary[] = docs.map((document) => {+ const { body: _body, ...summary } = document as typeof document & { body?: string };+ return { ...summary, format: "markdown" as const };+ });+ return [+ issueId,+ summaries,+ ] as const;+ }),+ )+ : Promise.resolve(null),+ params.includeActiveRuns+ ? getIssueRunSummaries(companyId, issueIds, { activeOnly: true })+ : Promise.resolve(null),+ params.includeAssignees && assigneeAgentIds.length > 0+ ? db+ .select({+ id: agentsTable.id,+ name: agentsTable.name,+ role: agentsTable.role,+ title: agentsTable.title,+ status: agentsTable.status,+ })+ .from(agentsTable)+ .where(and(eq(agentsTable.companyId, companyId), inArray(agentsTable.id, assigneeAgentIds)))+ : Promise.resolve(params.includeAssignees ? [] : null),+ ]);++ const activeRuns = activeRunRows+ ? Object.fromEntries(issueIds.map((issueId) => [+ issueId,+ activeRunRows.filter((run) => run.issueId === issueId),+ ]))+ : undefined;++ return {+ rootIssueId: rootIssue.id,+ companyId,+ issueIds,+ issues: outputIssues,+ ...(relationPairs ? { relations: Object.fromEntries(relationPairs) } : {}),+ ...(documentPairs ? { documents: Object.fromEntries(documentPairs) } : {}),+ ...(activeRuns ? { activeRuns } : {}),+ ...(assigneeRows+ ? {+ assignees: Object.fromEntries(assigneeRows.map((agent) => [+ agent.id,+ { ...agent, status: agent.status as Agent["status"] } as PluginIssueAssigneeSummary,+ ])),+ }+ : {}),+ };+ },+ async requestWakeup(params) {+ const companyId = ensureCompanyId(params.companyId);+ await ensurePluginAvailableForCompany(companyId);+ const issue = requireInCompany("Issue", await issues.getById(params.issueId), companyId);+ if (!issue.assigneeAgentId) {+ throw new Error("Issue has no assigned agent to wake");+ }+ if (["backlog", "done", "cancelled"].includes(issue.status)) {+ throw new Error(`Issue is not wakeable in status: ${issue.status}`);+ }+ const relations = await issues.getRelationSummaries(issue.id);+ const unresolvedBlockers = relations.blockedBy.filter((blocker) => blocker.status !== "done");+ if (unresolvedBlockers.length > 0) {+ throw new Error("Issue is blocked by unresolved blockers");+ }+ const budgetBlock = await budgets.getInvocationBlock(companyId, issue.assigneeAgentId, {+ issueId: issue.id,+ projectId: issue.projectId,+ });+ if (budgetBlock) {+ throw new Error(budgetBlock.reason);+ }+ const contextSource = params.contextSource ?? "plugin.issue.requestWakeup";+ const run = await heartbeat.wakeup(issue.assigneeAgentId, {+ source: "assignment",+ triggerDetail: "system",+ reason: params.reason ?? "plugin_issue_wakeup_requested",+ payload: {+ issueId: issue.id,+ mutation: "plugin_wakeup",+ pluginId,+ pluginKey,+ contextSource,+ },+ idempotencyKey: params.idempotencyKey ?? null,+ requestedByActorType: "system",+ requestedByActorId: pluginId,+ contextSnapshot: {+ issueId: issue.id,+ taskId: issue.id,+ wakeReason: params.reason ?? "plugin_issue_wakeup_requested",+ source: contextSource,+ pluginId,+ pluginKey,+ },+ });+ await logPluginActivity({+ companyId,+ action: "issue.assignment_wakeup_requested",+ entityType: "issue",+ entityId: issue.id,+ actor: {+ actorAgentId: params.actorAgentId,+ actorUserId: params.actorUserId,+ actorRunId: params.actorRunId,+ },+ details: {+ identifier: issue.identifier,+ assigneeAgentId: issue.assigneeAgentId,+ runId: run?.id ?? null,+ reason: params.reason ?? "plugin_issue_wakeup_requested",+ contextSource,+ },+ });+ return { queued: Boolean(run), runId: run?.id ?? null };+ },+ async requestWakeups(params) {+ const companyId = ensureCompanyId(params.companyId);+ await ensurePluginAvailableForCompany(companyId);+ const results = [];+ for (const issueId of [...new Set(params.issueIds)]) {+ const issue = requireInCompany("Issue", await issues.getById(issueId), companyId);+ if (!issue.assigneeAgentId) {+ throw new Error("Issue has no assigned agent to wake");+ }+ if (["backlog", "done", "cancelled"].includes(issue.status)) {+ throw new Error(`Issue is not wakeable in status: ${issue.status}`);+ }+ const relations = await issues.getRelationSummaries(issue.id);+ const unresolvedBlockers = relations.blockedBy.filter((blocker) => blocker.status !== "done");+ if (unresolvedBlockers.length > 0) {+ throw new Error("Issue is blocked by unresolved blockers");+ }+ const budgetBlock = await budgets.getInvocationBlock(companyId, issue.assigneeAgentId, {+ issueId: issue.id,+ projectId: issue.projectId,+ });+ if (budgetBlock) {+ throw new Error(budgetBlock.reason);+ }+ const contextSource = params.contextSource ?? "plugin.issue.requestWakeups";+ const run = await heartbeat.wakeup(issue.assigneeAgentId, {+ source: "assignment",+ triggerDetail: "system",+ reason: params.reason ?? "plugin_issue_wakeup_requested",+ payload: {+ issueId: issue.id,+ mutation: "plugin_wakeup",+ pluginId,+ pluginKey,+ contextSource,+ },+ idempotencyKey: params.idempotencyKeyPrefix ? `${params.idempotencyKeyPrefix}:${issue.id}` : null,+ requestedByActorType: "system",+ requestedByActorId: pluginId,+ contextSnapshot: {+ issueId: issue.id,+ taskId: issue.id,+ wakeReason: params.reason ?? "plugin_issue_wakeup_requested",+ source: contextSource,+ pluginId,+ pluginKey,+ },+ });+ await logPluginActivity({+ companyId,+ action: "issue.assignment_wakeup_requested",+ entityType: "issue",+ entityId: issue.id,+ actor: {+ actorAgentId: params.actorAgentId,+ actorUserId: params.actorUserId,+ actorRunId: params.actorRunId,+ },+ details: {+ identifier: issue.identifier,+ assigneeAgentId: issue.assigneeAgentId,+ runId: run?.id ?? null,+ reason: params.reason ?? "plugin_issue_wakeup_requested",+ contextSource,+ },+ });+ results.push({ issueId: issue.id, queued: Boolean(run), runId: run?.id ?? null });+ }+ return results;+ },+ async getOrchestrationSummary(params): Promise<PluginIssueOrchestrationSummary> {+ const companyId = ensureCompanyId(params.companyId);+ await ensurePluginAvailableForCompany(companyId);+ const rootIssue = requireInCompany("Issue", await issues.getById(params.issueId), companyId);+ const subtreeIssueIds = params.includeSubtree+ ? await collectIssueSubtreeIds(companyId, rootIssue.id)+ : [rootIssue.id];+ const relationPairs = await Promise.all(+ subtreeIssueIds.map(async (issueId) => [issueId, await issues.getRelationSummaries(issueId)] as const),+ );+ const approvalRows = (+ await Promise.all(+ subtreeIssueIds.map(async (issueId) => {+ const rows = await issueApprovals.listApprovalsForIssue(issueId);+ return rows.map((approval) => ({+ issueId,+ id: approval.id,+ type: approval.type,+ status: approval.status,+ requestedByAgentId: approval.requestedByAgentId,+ requestedByUserId: approval.requestedByUserId,+ decidedByUserId: approval.decidedByUserId,+ decidedAt: approval.decidedAt?.toISOString() ?? null,+ createdAt: approval.createdAt.toISOString(),+ }));+ }),+ )+ ).flat();+ const [runs, costsSummary, openBudgetIncidents] = await Promise.all([+ getIssueRunSummaries(companyId, subtreeIssueIds),+ getIssueCostSummary(companyId, subtreeIssueIds, params.billingCode ?? rootIssue.billingCode ?? null),+ getOpenBudgetIncidents(companyId),+ ]);+ const issueRows = await db+ .select({+ id: issuesTable.id,+ assigneeAgentId: issuesTable.assigneeAgentId,+ projectId: issuesTable.projectId,+ })+ .from(issuesTable)+ .where(and(eq(issuesTable.companyId, companyId), inArray(issuesTable.id, subtreeIssueIds)));+ const invocationBlocks = (+ await Promise.all(+ issueRows+ .filter((issueRow) => issueRow.assigneeAgentId)+ .map(async (issueRow) => {+ const block = await budgets.getInvocationBlock(companyId, issueRow.assigneeAgentId!, {+ issueId: issueRow.id,+ projectId: issueRow.projectId,+ });+ return block+ ? {+ issueId: issueRow.id,+ agentId: issueRow.assigneeAgentId!,+ scopeType: block.scopeType,+ scopeId: block.scopeId,+ scopeName: block.scopeName,+ reason: block.reason,+ }+ : null;+ }),+ )+ ).filter((block): block is NonNullable<typeof block> => block !== null);+ return {+ issueId: rootIssue.id,+ companyId,+ subtreeIssueIds,+ relations: Object.fromEntries(relationPairs),+ approvals: approvalRows,+ runs,+ costs: costsSummary,+ openBudgetIncidents,+ invocationBlocks,+ };},async listComments(params) {const companyId = ensureCompanyId(params.companyId);@@ -803,12 +1486,25 @@ export function buildHostServices(async createComment(params) {const companyId = ensureCompanyId(params.companyId);await ensurePluginAvailableForCompany(companyId);- requireInCompany("Issue", await issues.getById(params.issueId), companyId);- return (await issues.addComment(+ const issue = requireInCompany("Issue", await issues.getById(params.issueId), companyId);+ const comment = (await issues.addComment(params.issueId,params.body,{ agentId: params.authorAgentId },)) as IssueComment;+ await logPluginActivity({+ companyId,+ action: "issue.comment.created",+ entityType: "issue",+ entityId: issue.id,+ actor: { actorAgentId: params.authorAgentId ?? null },+ details: {+ identifier: issue.identifier,+ commentId: comment.id,+ bodySnippet: comment.body.slice(0, 120),+ },+ });+ return comment;},},@@ -830,7 +1526,7 @@ export function buildHostServices(async upsert(params) {const companyId = ensureCompanyId(params.companyId);await ensurePluginAvailableForCompany(companyId);- requireInCompany("Issue", await issues.getById(params.issueId), companyId);+ const issue = requireInCompany("Issue", await issues.getById(params.issueId), companyId);const result = await documents.upsertIssueDocument({issueId: params.issueId,key: params.key,@@ -839,13 +1535,35 @@ export function buildHostServices(format: params.format ?? "markdown",changeSummary: params.changeSummary ?? null,});+ await logPluginActivity({+ companyId,+ action: "issue.document_upserted",+ entityType: "issue",+ entityId: issue.id,+ details: {+ identifier: issue.identifier,+ documentKey: params.key,+ title: params.title ?? null,+ format: params.format ?? "markdown",+ },+ });return result.document as any;},async delete(params) {const companyId = ensureCompanyId(params.companyId);await ensurePluginAvailableForCompany(companyId);- requireInCompany("Issue", await issues.getById(params.issueId), companyId);+ const issue = requireInCompany("Issue", await issues.getById(params.issueId), companyId);await documents.deleteIssueDocument(params.issueId, params.key);+ await logPluginActivity({+ companyId,+ action: "issue.document_deleted",+ entityType: "issue",+ entityId: issue.id,+ details: {+ identifier: issue.identifier,+ documentKey: params.key,+ },+ });},},diff --git a/server/src/services/plugin-loader.ts b/server/src/services/plugin-loader.tsindex 1ceadd1917..9580118015 100644--- a/server/src/services/plugin-loader.ts+++ b/server/src/services/plugin-loader.ts@@ -48,6 +48,7 @@ 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";+import { pluginDatabaseService } from "./plugin-database.js";const execFileAsync = promisify(execFile);const __dirname = path.dirname(fileURLToPath(import.meta.url));@@ -147,6 +148,9 @@ export interface PluginLoaderOptions {*/localPluginDir?: string;+ /** Optional direct Postgres connection used for plugin DDL migrations. */+ migrationDb?: Db;+/*** Whether to scan the local filesystem directory for plugins.* Defaults to true.@@ -735,6 +739,7 @@ export function pluginLoader(): PluginLoader {const {localPluginDir = DEFAULT_LOCAL_PLUGIN_DIR,+ migrationDb = db,enableLocalFilesystem = true,enableNpmDiscovery = true,} = options;@@ -1701,14 +1706,22 @@ export function pluginLoader(// 1. Resolve worker entrypoint// ------------------------------------------------------------------const workerEntrypoint = resolveWorkerEntrypoint(plugin, localPluginDir);+ const packageRoot = resolvePluginPackageRoot(plugin, localPluginDir);++ // ------------------------------------------------------------------+ // 2. Apply restricted database migrations before worker startup+ // ------------------------------------------------------------------+ const databaseNamespace = manifest.database+ ? (await pluginDatabaseService(migrationDb).applyMigrations(pluginId, manifest, packageRoot))?.namespaceName ?? null+ : null;// ------------------------------------------------------------------- // 2. Build host handlers for this plugin+ // 3. Build host handlers for this plugin// ------------------------------------------------------------------const hostHandlers = buildHostHandlers(pluginId, manifest);// ------------------------------------------------------------------- // 3. Retrieve plugin config (if any)+ // 4. Retrieve plugin config (if any)// ------------------------------------------------------------------let config: Record<string, unknown> = {};try {@@ -1722,7 +1735,7 @@ export function pluginLoader(}// ------------------------------------------------------------------- // 4. Spawn worker process+ // 5. Spawn worker process// ------------------------------------------------------------------const workerOptions: WorkerStartOptions = {entrypointPath: workerEntrypoint,@@ -1730,6 +1743,7 @@ export function pluginLoader(config,instanceInfo,apiVersion: manifest.apiVersion,+ databaseNamespace,hostHandlers,autoRestart: true,};@@ -1750,7 +1764,7 @@ export function pluginLoader();// ------------------------------------------------------------------- // 5. Sync job declarations and register with scheduler+ // 6. Sync job declarations and register with scheduler// ------------------------------------------------------------------const jobDeclarations = manifest.jobs ?? [];if (jobDeclarations.length > 0) {@@ -1939,6 +1953,26 @@ function resolveWorkerEntrypoint();}+function resolvePluginPackageRoot(+ plugin: PluginRecord & { packagePath?: string | null },+ localPluginDir: string,+): string {+ if (plugin.packagePath && existsSync(plugin.packagePath)) {+ return path.resolve(plugin.packagePath);+ }++ const packageName = plugin.packageName;+ const packageDir = packageName.startsWith("@")+ ? path.join(localPluginDir, "node_modules", ...packageName.split("/"))+ : path.join(localPluginDir, "node_modules", packageName);+ if (existsSync(packageDir)) return packageDir;++ const directDir = path.join(localPluginDir, packageName);+ if (existsSync(directDir)) return directDir;++ throw new Error(`Package root not found for plugin "${plugin.pluginKey}"`);+}+function resolveManagedInstallPackageDir(localPluginDir: string, packageName: string): string {if (packageName.startsWith("@")) {return path.join(localPluginDir, "node_modules", ...packageName.split("/"));diff --git a/server/src/services/plugin-worker-manager.ts b/server/src/services/plugin-worker-manager.tsindex b55ba1bcdf..8413af10d0 100644--- a/server/src/services/plugin-worker-manager.ts+++ b/server/src/services/plugin-worker-manager.ts@@ -166,6 +166,8 @@ export interface WorkerStartOptions {};/** Host API version. */apiVersion: number;+ /** Host-derived plugin database namespace, when declared. */+ databaseNamespace?: string | null;/** Handlers for worker→host RPC calls. */hostHandlers: WorkerToHostHandlers;/** Default timeout for RPC calls (ms). Defaults to 30s. */@@ -828,6 +830,7 @@ export function createPluginWorkerHandle(config: options.config,instanceInfo: options.instanceInfo,apiVersion: options.apiVersion,+ databaseNamespace: options.databaseNamespace ?? null,};try {