mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-15 10:30:37 +09:00
[codex] Add plugin orchestration host APIs (#4114)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - The plugin system is the extension path for optional capabilities that should not require core product changes for every integration. > - Plugins need scoped host APIs for issue orchestration, documents, wakeups, summaries, activity attribution, and isolated database state. > - Without those host APIs, richer plugins either cannot coordinate Paperclip work safely or need privileged core-side special cases. > - This pull request adds the plugin orchestration host surface, scoped route dispatch, a database namespace layer, and a smoke plugin that exercises the contract. > - The benefit is a broader plugin API that remains company-scoped, auditable, and covered by tests. ## What Changed - Added plugin orchestration host APIs for issue creation, document access, wakeups, summaries, plugin-origin activity, and scoped API route dispatch. - Added plugin database namespace tables, schema exports, migration checks, and idempotent replay coverage under migration `0059_plugin_database_namespaces`. - Added shared plugin route/API types and validators used by server and SDK boundaries. - Expanded plugin SDK types, protocol helpers, worker RPC host behavior, and testing utilities for orchestration flows. - Added the `plugin-orchestration-smoke-example` package to exercise scoped routes, restricted database namespaces, issue orchestration, documents, wakeups, summaries, and UI status surfaces. - Kept the new orchestration smoke fixture out of the root pnpm workspace importer so this PR preserves the repository policy of not committing `pnpm-lock.yaml`. - Updated plugin docs and database docs for the new orchestration and database namespace surfaces. - Rebased the branch onto `public-gh/master`, resolved conflicts, and removed `pnpm-lock.yaml` from the final PR diff. ## Verification - `pnpm install --frozen-lockfile` - `pnpm --filter @paperclipai/db typecheck` - `pnpm exec vitest run packages/db/src/client.test.ts` - `pnpm exec vitest run server/src/__tests__/plugin-database.test.ts server/src/__tests__/plugin-orchestration-apis.test.ts server/src/__tests__/plugin-routes-authz.test.ts server/src/__tests__/plugin-scoped-api-routes.test.ts server/src/__tests__/plugin-sdk-orchestration-contract.test.ts` - From `packages/plugins/examples/plugin-orchestration-smoke-example`: `pnpm exec vitest run --config ./vitest.config.ts` - `pnpm --dir packages/plugins/examples/plugin-orchestration-smoke-example run typecheck` - `pnpm --filter @paperclipai/server typecheck` - PR CI on latest head `293fc67c`: `policy`, `verify`, `e2e`, and `security/snyk` all passed. ## Risks - Medium risk: this expands plugin host authority, so route auth, company scoping, and plugin-origin activity attribution need careful review. - Medium risk: database namespace migration behavior must remain idempotent for environments that may have seen earlier branch versions. - Medium risk: the orchestration smoke fixture is intentionally excluded from the root workspace importer to avoid a `pnpm-lock.yaml` PR diff; direct fixture verification remains listed above. - Low operational risk from the PR setup itself: the branch is rebased onto current `master`, the migration is ordered after upstream `0057`/`0058`, and `pnpm-lock.yaml` is not in the final diff. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. Roadmap checked: this work aligns with the completed Plugin system milestone and extends the plugin surface rather than duplicating an unrelated planned core feature. ## Model Used - OpenAI Codex, GPT-5-based coding agent in a tool-enabled CLI environment. Exact hosted model build and context-window size are not exposed by the runtime; reasoning/tool use were enabled for repository inspection, editing, testing, git operations, and PR creation. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots (N/A: no core UI screen change; example plugin UI contract is covered by tests) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
GitHub
parent
16b2b84d84
commit
9c6f551595
53 changed files with 5584 additions and 53 deletions
269
server/src/__tests__/plugin-database.test.ts
Normal file
269
server/src/__tests__/plugin-database.test.ts
Normal file
|
|
@ -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);
|
||||
});
|
||||
});
|
||||
372
server/src/__tests__/plugin-orchestration-apis.test.ts
Normal file
372
server/src/__tests__/plugin-orchestration-apis.test.ts
Normal file
|
|
@ -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,
|
||||
});
|
||||
});
|
||||
});
|
||||
|
|
@ -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: Record
|
|||
req.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);
|
||||
});
|
||||
|
|
|
|||
427
server/src/__tests__/plugin-scoped-api-routes.test.ts
Normal file
427
server/src/__tests__/plugin-scoped-api-routes.test.ts
Normal file
|
|
@ -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",
|
||||
);
|
||||
});
|
||||
});
|
||||
240
server/src/__tests__/plugin-sdk-orchestration-contract.test.ts
Normal file
240
server/src/__tests__/plugin-sdk-orchestration-contract.test.ts
Normal file
|
|
@ -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");
|
||||
});
|
||||
});
|
||||
Loading…
Add table
Add a link
Reference in a new issue