mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 02:43:25 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Plugins can now add connector types to the Connectors catalog (#22004), but only for transports the host already runs (remote MCP, local stdio) > - A plugin cannot yet serve a connector's tools itself, and legacy plugin tools (top-level manifest `tools`) still reach every agent without a connection or install > - A plugin should be able to ship a full connector: settings, credentials, tools, grants, policies and audit, like a built-in one > - This pull request adds the `plugin` transport, the SDK API to serve it, and moves legacy plugin tools under the same activation rules without changing today's access > - The benefit is that any connector can live in a plugin, and agents get plugin tools only when an operator enables them ## Linked Issues or Issue Description Refs #22004 **Subsystem affected** Plugins (SDK, worker protocol, manifest), Connectors (tool access, catalog discovery), tool gateway, database. **Problem or motivation** A plugin connector can only describe an existing transport. There is no way for a plugin worker to serve a connector's tools with per-connection settings and credentials. Legacy plugin tools are visible to every agent as soon as the plugin is enabled, which is the opposite of the connector activation rules. **Proposed solution** Add a `plugin` transport. The gateway keeps every decision (grant, policy, approval, rate limit, audit) and calls the plugin worker with the connection, its settings and a per-call credential. Legacy top-level tools become one implicit connector per plugin. Existing installations keep exactly their current access through a one-time migration. **Alternatives considered** Move legacy tools to connection tool names (`app.<connection>:<tool>`). Rejected: names change, so existing tool policies and agent instructions that name `plugin:tool` would stop matching (a possible widening or loss). Legacy tools keep their names and handlers; only their visibility is now gated by an install of the implicit connector. ## What Changed - `packages/db`: migration `0491` widens `tool_connections_transport_check` with `plugin` (`NOT VALID`, annotated `online_compatible`), and adds `plugin_connector_legacy_access`, seeded with one row per installed legacy-tools plugin and company. - `packages/shared`: method schema gains `settingsSchema` and `tools` (`{ kind: "static", list: [{ name, displayName?, description?, risk, parametersSchema }] } | { kind: "dynamic" }`), only for `transport: "plugin"`; tool names must match `[a-z0-9_]`; plugin-served methods use `none` or `api_key`. The connect API accepts `settings`. - `packages/plugins/sdk`: `ToolRunContext.connection` (`id`, `appSlug`, `methodKey`, `grantId`, `settings`, `credential?`); `ctx.connectors.register(appSlug, toolName, fn)` and `ctx.connectors.listTools(appSlug, fn)`; new `listConnectorTools` RPC; `executeTool` routes connector calls by `appSlug`. A worker refuses to start when a declared static tool (or dynamic lister) has no handler. The test harness gains `executeConnectorTool` and `listConnectorTools`. - `server/src/services/plugin-connector-runtime.ts`: routes one call to the plugin's worker; a stopped worker is a `PluginWorkerUnavailableError`. - Connect flow (`tool-access.ts`): a `plugin` method creates a `paperclip_plugin` application and a `plugin` connection with `config = { sourceTemplateKey, connectionMethodKey, settings }`, validated against `settingsSchema`. Credentials, grants, credential policy, installs and profiles use the existing code. - Catalog: static tools come from the definition, dynamic tools from `listConnectorTools`, with the existing version hashing and retirement. Tool risk comes from the declaration. - Gateway: plugin connections join connected-tool discovery and both execution paths (direct and approved actions). For each call the gateway resolves the grant and, for `api_key`, the credential for that call only. The run context comes only from the session. A stopped worker returns `503 plugin_connector_unavailable` with `retryable: true`. The token broker refuses to export plugin connector credentials. - Legacy tools: a plugin with top-level `tools` and no `apps` gets an implicit connector (slug `default`, named after the plugin, no authentication). Its tools keep their names, handlers and today's access decision, and an agent sees them only when a connection of that connector is installed for it or for the company. The connector's saved action rules (Off, Ask first) can only restrict them. `completeLegacyPluginToolAccess` turns each migration row into such a connection with a company install, at boot and when a disabled plugin is enabled again; it is single-flight across servers, resumes a draft left by an interrupted attempt, and never overrides an operator's later changes. - Catalog: tools a dynamic connector stops offering are retired from discovery; `listConnectorTools` carries the connection's `companyId`, and uses the acting person's grant for personal connections. - Board: the setup flow renders `settingsSchema` with the shared JSON Schema form, sends `settings`, and restores saved settings on resume and reconnect. - `create-paperclip-plugin --template connector` now scaffolds a plugin connector (`apps` + `ctx.connectors.register` + a harness test). SDK README and `PLUGIN_SPEC.md` describe connectors; top-level `tools` stay documented as legacy. - `inferToolRisk` moves to `tool-risk-inference.ts` so the catalog can reuse it. Design notes where the spec left room: - OAuth for `plugin`-transport methods is not supported in this PR (`none` and `api_key` only); OAuth plugin connectors can use `mcp_remote` today. Noted as follow-up. - Board "Test" calls on a plugin connection pass an empty `agentId`/`runId`, because there is no agent run. - Companies created after the upgrade get no automatic legacy connection; they follow the normal activation rules. ## Verification - `server`: `npx vitest run src/__tests__/plugin-connectors-plugin-transport.test.ts` (new): - rules 1-3: a ready plugin and configured accounts give no tools; an install for agent A gives only A the tools; agent B is denied on invocation; - the worker receives `runContext.connection` with the right id, method, grant, settings and the call's credential; spoofed arguments do not change it; each account calls with its own key; results do not contain the key; - invalid settings are rejected (422); a stopped worker is `503 plugin_connector_unavailable` (retryable); a disabled plugin hides the tools; - dynamic tools are listed through the worker and a tool it stops offering is retired; - rule 5: a new installation of a legacy-tools plugin gives no tools; an installation recorded by the migration keeps the same tool names for every agent, through one company-wide connection (two concurrent carry-overs make one; an interrupted draft is finished; a retry keeps an operator's restriction), and is not also exposed as connection tools; Ask first and Off on the implicit connector restrict the legacy tools; - the token broker refuses to export a plugin connection's credential. - Existing gateway plugin-tool tests (`tool-gateway`, `tool-gateway-service`, `prompt-injection-gateway`) now set up the legacy grant an existing installation has, and pass unchanged otherwise. - Regression: `plugin-connectors-circleback-parity`, `tool-gateway`, `tool-gateway-service`, `prompt-injection-gateway`, `tool-access-service` (846 passed), plus `connector-tool-policy`, `plugin-lifecycle-restart`, `remote-mcp-connectors`, `ai-connection-router` in an earlier run. - UI: `AppsConnect.test.tsx` covers sending plugin settings from the settings schema. - SDK: `tests/worker-rpc-host.test.ts` (start refusal without handlers, connector routing, tool listing). Scaffold: `entrypoints.test.ts`. - `packages/db`: `pnpm typecheck` including `check:migrations`; server layered typecheck (sources and tests); `tsc --noEmit` for shared, SDK, scaffold and UI. ## Risks - Behavior change for new installations: legacy plugin tools no longer reach agents until an operator connects the plugin's connector. Installations that exist at upgrade time keep their tools through the migration rows. - The migration widens a check constraint (`NOT VALID`) and copies plugin × company rows into a new table. Both are fast; the previous release never writes `plugin`. - Calls depend on the plugin worker; when it is down the agent gets a retryable error. > 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`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file editing, test execution). ## 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 searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
244 lines
10 KiB
TypeScript
244 lines
10 KiB
TypeScript
/**
|
|
* Connector types provided by plugins.
|
|
*
|
|
* A plugin with the `connectors.provide` capability declares `apps` in its
|
|
* manifest using the built-in app-definition schema. This module turns the
|
|
* apps of every *ready* plugin into namespaced catalog entries and answers one
|
|
* question for the Connectors APIs and the tool gateway: is the connector a
|
|
* connection was made from still available?
|
|
*
|
|
* The plugins table is the source of truth. Several plugin lifecycle managers
|
|
* can exist in one process (and several processes can share one database), so
|
|
* no in-memory event is relied on: every reader that needs an answer reads the
|
|
* plugin rows, and the shared lookup table used by synchronous helpers such as
|
|
* `getConnectableAppDefinition` is replaced from that same read.
|
|
*
|
|
* Disabling a plugin (or removing an app in an upgrade) only hides its apps
|
|
* and connections. Nothing is deleted, so settings, credentials, installs and
|
|
* grants come back unchanged when the plugin is enabled again. Uninstalling
|
|
* retires the connections through the normal connection removal path.
|
|
*/
|
|
import { createHash } from "node:crypto";
|
|
import { and, eq, like, or, sql } from "drizzle-orm";
|
|
import { plugins, toolConnections, type Db } from "@paperclipai/db";
|
|
import {
|
|
appDefinitionSchema,
|
|
connectionSourceSlug,
|
|
isPluginAppSlug,
|
|
parsePluginAppSlug,
|
|
pluginAppDefinition,
|
|
pluginAppSlug,
|
|
setPluginAppDefinitions,
|
|
type AppDefinition,
|
|
} from "@paperclipai/shared";
|
|
import { logger } from "../middleware/logger.js";
|
|
import { inferToolRisk } from "./tool-risk-inference.js";
|
|
|
|
export interface PluginAppCatalog {
|
|
/** Catalog entries for every app of every ready plugin, namespaced. */
|
|
definitions: AppDefinition[];
|
|
/** False only for a plugin connector whose plugin or app is not available. */
|
|
isAvailable(sourceSlug: string | null | undefined): boolean;
|
|
}
|
|
|
|
const parsedDefinitions = new Map<string, AppDefinition[]>();
|
|
|
|
type PluginManifestFields = {
|
|
displayName?: string;
|
|
description?: string;
|
|
capabilities?: readonly string[];
|
|
apps?: readonly unknown[];
|
|
tools?: ReadonlyArray<{ name: string; displayName: string; description: string; parametersSchema?: Record<string, unknown> }>;
|
|
};
|
|
|
|
const ALL_AVAILABLE: PluginAppCatalog = { definitions: [], isAvailable: () => true };
|
|
|
|
export const LEGACY_PLUGIN_TOOLS_APP_SLUG = "default";
|
|
|
|
/**
|
|
* A plugin that declares agent tools with the legacy top-level manifest
|
|
* `tools` (and no `apps`) gets one implicit connector. Its tools keep their
|
|
* original names and handlers; a connection of this connector, installed for
|
|
* an agent or the whole company, is what gives agents those tools.
|
|
*/
|
|
export function legacyToolsAppDefinition(row: {
|
|
pluginKey: string;
|
|
manifestJson: PluginManifestFields | null;
|
|
}): AppDefinition | null {
|
|
const manifest = row.manifestJson;
|
|
const tools = Array.isArray(manifest?.tools) ? manifest.tools : [];
|
|
if (!manifest || tools.length === 0 || (manifest.apps?.length ?? 0) > 0
|
|
|| !manifest.capabilities?.includes("agent.tools.register")) return null;
|
|
const name = typeof manifest.displayName === "string" && manifest.displayName ? manifest.displayName : row.pluginKey;
|
|
return {
|
|
schemaVersion: 1,
|
|
slug: pluginAppSlug(row.pluginKey, LEGACY_PLUGIN_TOOLS_APP_SLUG),
|
|
plugin: { pluginKey: row.pluginKey, appSlug: LEGACY_PLUGIN_TOOLS_APP_SLUG, legacyTools: true },
|
|
name,
|
|
description: typeof manifest.description === "string" && manifest.description ? manifest.description : `Tools from the ${name} plugin.`,
|
|
categories: ["other"],
|
|
branding: { logoUrl: "/brands/apps/api-key-generic.svg" },
|
|
urlPatterns: [],
|
|
methods: [{
|
|
key: LEGACY_PLUGIN_TOOLS_APP_SLUG,
|
|
label: `Use ${name}`,
|
|
transport: "plugin",
|
|
auth: "none",
|
|
ownershipModes: ["customer"],
|
|
whenToUse: `Give agents the tools of the ${name} plugin.`,
|
|
guidanceMd: `The ${name} plugin runs these tools on this Paperclip instance. Choose which agents can use them.`,
|
|
riskTier: "S2",
|
|
tools: {
|
|
kind: "static",
|
|
list: tools.map((tool) => ({
|
|
name: tool.name,
|
|
displayName: tool.displayName,
|
|
description: tool.description,
|
|
risk: inferToolRisk(tool.name),
|
|
parametersSchema: tool.parametersSchema ?? { type: "object" },
|
|
})),
|
|
},
|
|
}],
|
|
};
|
|
}
|
|
|
|
/** The apps a ready plugin row contributes. Invalid entries are skipped. */
|
|
export function pluginRowAppDefinitions(row: {
|
|
pluginKey: string;
|
|
status: string;
|
|
manifestJson: PluginManifestFields | null;
|
|
}): AppDefinition[] {
|
|
const manifest = row.manifestJson;
|
|
if (row.status !== "ready") return [];
|
|
const legacy = legacyToolsAppDefinition(row);
|
|
if (legacy) return [legacy];
|
|
if (!manifest?.capabilities?.includes("connectors.provide")) return [];
|
|
const definitions: AppDefinition[] = [];
|
|
for (const declared of manifest.apps ?? []) {
|
|
// Manifests are validated at install and upgrade; parse again so a row
|
|
// written by an older host can never put a malformed entry in the catalog.
|
|
const parsed = appDefinitionSchema.safeParse(declared);
|
|
if (!parsed.success) {
|
|
logger.warn({ pluginKey: row.pluginKey }, "Skipping an invalid plugin connector definition");
|
|
continue;
|
|
}
|
|
definitions.push(pluginAppDefinition(row.pluginKey, parsed.data as AppDefinition));
|
|
}
|
|
return definitions;
|
|
}
|
|
|
|
/** Read every ready plugin's apps and refresh the shared catalog lookups. */
|
|
export async function loadPluginAppCatalog(db: Db): Promise<PluginAppCatalog> {
|
|
const rows = await db
|
|
.select({ pluginKey: plugins.pluginKey, status: plugins.status, manifestJson: plugins.manifestJson })
|
|
.from(plugins)
|
|
.where(and(
|
|
eq(plugins.status, "ready"),
|
|
sql`(${plugins.manifestJson}->'capabilities' @> '["connectors.provide"]'::jsonb or ${plugins.manifestJson}->'capabilities' @> '["agent.tools.register"]'::jsonb)`,
|
|
));
|
|
const definitions = rows.flatMap((row) => {
|
|
// Parsing is the costly part; reuse it while the manifest is unchanged.
|
|
const key = `${row.pluginKey}\u0000${createHash("sha256").update(JSON.stringify(row.manifestJson)).digest("hex")}`;
|
|
let cached = parsedDefinitions.get(key);
|
|
if (!cached) {
|
|
cached = pluginRowAppDefinitions(row);
|
|
if (parsedDefinitions.size > 500) parsedDefinitions.clear();
|
|
parsedDefinitions.set(key, cached);
|
|
}
|
|
return cached;
|
|
});
|
|
setPluginAppDefinitions(definitions);
|
|
const available = new Set(definitions.map((app) => app.slug));
|
|
return {
|
|
definitions,
|
|
isAvailable: (sourceSlug) => !isPluginAppSlug(sourceSlug) || available.has(sourceSlug!),
|
|
};
|
|
}
|
|
|
|
/**
|
|
* The availability check for a set of saved rows. Rows that were not made
|
|
* from a plugin connector need no plugin read, so built-in connections pay
|
|
* nothing for this check.
|
|
*/
|
|
export async function pluginAppCatalogFor(
|
|
db: Db,
|
|
rows: Iterable<Parameters<typeof connectionSourceSlug>[0]>,
|
|
): Promise<PluginAppCatalog> {
|
|
for (const row of rows) {
|
|
if (isPluginAppSlug(connectionSourceSlug(row))) return loadPluginAppCatalog(db);
|
|
}
|
|
return ALL_AVAILABLE;
|
|
}
|
|
|
|
export function pluginKeyForConnectionSource(sourceSlug: string | null | undefined): string | null {
|
|
return parsePluginAppSlug(sourceSlug)?.pluginKey ?? null;
|
|
}
|
|
|
|
/**
|
|
* Retire every connection made from a plugin's apps when it is uninstalled.
|
|
* Uses the standard connection removal, so rows stay (archived) for audit
|
|
* while grants are revoked and connection-owned credentials are deleted.
|
|
* Removal is idempotent, so archived rows are retried too: a removal that
|
|
* failed part-way finishes on the next attempt. Any failure is thrown, so
|
|
* the uninstall is not reported as done while credentials remain.
|
|
*/
|
|
export async function retirePluginAppConnections(db: Db, pluginKey: string): Promise<number> {
|
|
const prefix = `${pluginAppSlug(pluginKey, "x").slice(0, -1)}%`;
|
|
const rows = await db
|
|
.select({ id: toolConnections.id, companyId: toolConnections.companyId, config: toolConnections.config, transportConfig: toolConnections.transportConfig })
|
|
.from(toolConnections)
|
|
.where(or(
|
|
like(sql<string>`${toolConnections.config}->>'sourceTemplateKey'`, prefix),
|
|
like(sql<string>`${toolConnections.transportConfig}->>'sourceTemplateKey'`, prefix),
|
|
));
|
|
const owned = rows.filter((row) => pluginKeyForConnectionSource(connectionSourceSlug(row)) === pluginKey);
|
|
if (owned.length === 0) return 0;
|
|
const { toolAccessService } = await import("./tool-access.js");
|
|
const access = toolAccessService(db);
|
|
const failures: unknown[] = [];
|
|
for (const row of owned) {
|
|
try {
|
|
await access.archiveConnection(row.id, row.companyId);
|
|
} catch (error) {
|
|
logger.warn({ err: error, pluginKey, connectionId: row.id }, "Could not retire a plugin connector connection");
|
|
failures.push(error);
|
|
}
|
|
}
|
|
if (failures.length > 0) {
|
|
throw new Error(`Could not remove ${failures.length} connection(s) of this plugin's connectors. Try uninstalling again.`);
|
|
}
|
|
return owned.length;
|
|
}
|
|
|
|
/**
|
|
* Refresh the catalogs of a plugin's connector connections after its worker
|
|
* (re)starts, for example after an upgrade, so tool declarations and risk
|
|
* labels follow the running code. Best effort per connection; the gateway
|
|
* also hides catalog entries that no longer match a static declaration.
|
|
*/
|
|
export async function refreshPluginConnectionCatalogs(db: Db, pluginKey: string): Promise<number> {
|
|
const prefix = `${pluginAppSlug(pluginKey, "x").slice(0, -1)}%`;
|
|
const rows = await db
|
|
.select({ id: toolConnections.id, config: toolConnections.config })
|
|
.from(toolConnections)
|
|
.where(and(
|
|
eq(toolConnections.transport, "plugin"),
|
|
eq(toolConnections.status, "active"),
|
|
like(sql<string>`${toolConnections.config}->>'sourceTemplateKey'`, prefix),
|
|
));
|
|
const owned = rows.filter((row) => pluginKeyForConnectionSource(connectionSourceSlug(row)) === pluginKey);
|
|
if (owned.length === 0) return 0;
|
|
const { toolAccessService } = await import("./tool-access.js");
|
|
const access = toolAccessService(db);
|
|
let refreshed = 0;
|
|
for (const row of owned) {
|
|
try {
|
|
await access.refreshCatalog(row.id);
|
|
refreshed += 1;
|
|
} catch (error) {
|
|
logger.warn({ err: error, pluginKey, connectionId: row.id }, "Could not refresh a plugin connector catalog");
|
|
}
|
|
}
|
|
return refreshed;
|
|
}
|