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
|
|
@ -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>;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
}),
|
||||
|
|
|
|||
|
|
@ -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";
|
||||
|
|
|
|||
|
|
@ -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[],
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
||||
|
|
|
|||
|
|
@ -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