mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-15 18:30:39 +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
|
|
@ -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[],
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue