mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-16 19:00:38 +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
|
|
@ -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): WorkerRpcHost
|
|||
let 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): WorkerRpcHost
|
|||
companyId: input.companyId,
|
||||
projectId: input.projectId,
|
||||
assigneeAgentId: input.assigneeAgentId,
|
||||
originKind: input.originKind,
|
||||
originId: input.originId,
|
||||
status: input.status,
|
||||
limit: input.limit,
|
||||
offset: input.offset,
|
||||
|
|
@ -593,19 +609,81 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
|
|||
inheritExecutionWorkspaceFromIssueId: 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,
|
||||
});
|
||||
},
|
||||
|
||||
async listComments(issueId: string, companyId: string) {
|
||||
return callHost("issues.listComments", { issueId, companyId });
|
||||
},
|
||||
|
|
@ -639,6 +717,51 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
|
|||
return 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): WorkerRpcHost
|
|||
case "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): WorkerRpcHost
|
|||
|
||||
manifest = params.manifest;
|
||||
currentConfig = params.config;
|
||||
databaseNamespace = params.databaseNamespace ?? null;
|
||||
|
||||
// Call the plugin's setup function
|
||||
await plugin.definition.setup(ctx);
|
||||
|
|
@ -919,6 +1046,7 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
|
|||
if (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): WorkerRpcHost
|
|||
await 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) {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue