Let plugin workers serve connector tools (plugin transport) (#22019)

## 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>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-17 18:09:42 +00:00
1 parent ceaf574421
commit f4cb69205e
45 files changed
+2346 -80

No files matched your search

+96 -3
View File
@@ -32,6 +32,7 @@ import {
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. */
@@ -42,16 +43,76 @@ export interface PluginAppCatalog {
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: { capabilities?: readonly string[]; apps?: readonly unknown[] } | null;
manifestJson: PluginManifestFields | null;
}): AppDefinition[] {
const manifest = row.manifestJson;
if (row.status !== "ready" || !manifest?.capabilities?.includes("connectors.provide")) return [];
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
@@ -73,7 +134,7 @@ export async function loadPluginAppCatalog(db: Db): Promise<PluginAppCatalog> {
.from(plugins)
.where(and(
eq(plugins.status, "ready"),
sql`${plugins.manifestJson}->'capabilities' @> '["connectors.provide"]'::jsonb`,
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.
@@ -148,3 +209,35 @@ export async function retirePluginAppConnections(db: Db, pluginKey: string): Pro
}
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;
}
@@ -0,0 +1,97 @@
/**
* Keeps today's agent access to legacy plugin tools.
*
* Before plugin connectors, every agent could use the tools a plugin declared
* with the top-level manifest `tools`. Those tools now belong to the plugin's
* implicit connector, and an agent gets them only from a connection installed
* for it or for the whole company. The migration that introduced connectors
* recorded each plugin installed at that time, per company, in
* `plugin_connector_legacy_access`. This job turns each pending row into one
* connection of the implicit connector, installed for the whole company, so
* those agents keep exactly the tools they had. Plugins installed later have
* no row and follow the normal activation rules.
*
* A row stays pending while its plugin is not ready (for example disabled)
* or its worker is down, and is completed the next time the worker starts.
*/
import { and, eq, isNull, lt, ne, or, sql } from "drizzle-orm";
import { pluginConnectorLegacyAccess, toolConnections, type Db } from "@paperclipai/db";
import { pluginAppSlug } from "@paperclipai/shared";
import { logger } from "../middleware/logger.js";
import { LEGACY_PLUGIN_TOOLS_APP_SLUG, loadPluginAppCatalog } from "./plugin-app-catalog.js";
/** A claim older than this belongs to a server that stopped mid-way. */
const STALE_CLAIM_MS = 10 * 60_000;
/**
* Turn pending rows into connections. Each row is claimed first, so servers
* sharing the database never work on the same row; a failed row is released
* and retried the next time the plugin's worker starts (boot, enable,
* upgrade, reload or restart).
*/
export async function completeLegacyPluginToolAccess(db: Db, pluginKey?: string): Promise<number> {
const pending = await db
.select()
.from(pluginConnectorLegacyAccess)
.where(and(
isNull(pluginConnectorLegacyAccess.completedAt),
pluginKey ? eq(pluginConnectorLegacyAccess.pluginKey, pluginKey) : undefined,
));
if (pending.length === 0) return 0;
const catalog = await loadPluginAppCatalog(db);
const { toolAccessService } = await import("./tool-access.js");
const access = toolAccessService(db);
let completed = 0;
for (const row of pending) {
const slug = pluginAppSlug(row.pluginKey, LEGACY_PLUGIN_TOOLS_APP_SLUG);
if (!catalog.definitions.some((candidate) => candidate.slug === slug)) continue;
const [claimed] = await db
.update(pluginConnectorLegacyAccess)
.set({ claimedAt: new Date() })
.where(and(
eq(pluginConnectorLegacyAccess.id, row.id),
isNull(pluginConnectorLegacyAccess.completedAt),
or(
isNull(pluginConnectorLegacyAccess.claimedAt),
lt(pluginConnectorLegacyAccess.claimedAt, new Date(Date.now() - STALE_CLAIM_MS)),
),
))
.returning({ id: pluginConnectorLegacyAccess.id });
if (!claimed) continue;
try {
// A retry after the connection was made but before completion was
// recorded finishes that same connection instead of adding another.
const [existing] = await db.select({ id: toolConnections.id, status: toolConnections.status }).from(toolConnections).where(and(
eq(toolConnections.companyId, row.companyId),
ne(toolConnections.status, "archived"),
sql`${toolConnections.config}->>'sourceTemplateKey' = ${slug}`,
sql`${toolConnections.config}->>'legacyPluginTools' = 'true'`,
)).limit(1);
const connectionId = existing?.id ?? (await access.connectGalleryApp(row.companyId, {
galleryKey: slug,
connectionMethodKey: LEGACY_PLUGIN_TOOLS_APP_SLUG,
})).connectionId;
// Finish a new connection, or a draft an interrupted attempt left. An
// active connection is already configured (perhaps restricted by an
// operator since); keep its saved permissions as they are.
if (!existing || existing.status === "draft") {
const entries = await access.listCatalog(connectionId);
await access.finishGalleryAppConnection(row.companyId, connectionId, {
enabledCatalogEntryIds: entries.filter((entry) => entry.status === "active").map((entry) => entry.id),
askFirstCatalogEntryIds: [],
access: "all_agents",
});
}
await db
.update(pluginConnectorLegacyAccess)
.set({ connectionId, completedAt: new Date(), claimedAt: null })
.where(eq(pluginConnectorLegacyAccess.id, row.id));
completed += 1;
} catch (error) {
await db.update(pluginConnectorLegacyAccess).set({ claimedAt: null }).where(eq(pluginConnectorLegacyAccess.id, row.id))
.catch(() => undefined);
logger.warn({ err: error, pluginKey: row.pluginKey, companyId: row.companyId }, "Could not keep legacy plugin tool access");
}
}
return completed;
}
@@ -0,0 +1,195 @@
/**
* Calls into plugin workers for plugin-served connectors (`transport: "plugin"`).
*
* The tool gateway and catalog discovery own every decision (grant, policy,
* approval, credential, audit). This module only routes one call to the
* worker of the plugin that provides the connector, and turns "the worker is
* not running" into a retryable unavailable error.
*/
import { and, eq } from "drizzle-orm";
import { plugins, type Db } from "@paperclipai/db";
import {
PLUGIN_CONNECTOR_TOOL_NAME,
getConnectableAppDefinition,
parsePluginAppSlug,
type AppDefinition,
type ConnectionMethodDef,
type PluginConnectorToolDef,
} from "@paperclipai/shared";
import type {
ConnectorToolDescriptor,
ConnectorToolListConnection,
ToolResult,
ToolRunContext,
} from "@paperclipai/plugin-sdk";
import type { PluginWorkerManager } from "./plugin-worker-manager.js";
import { PluginWorkerUnavailableError } from "./plugin-worker-unavailable-error.js";
let workers: PluginWorkerManager | null = null;
/** Called once by the host when its worker manager exists. */
export function setPluginConnectorWorkers(manager: PluginWorkerManager | null): void {
workers = manager;
}
export const PLUGIN_CONNECTOR_UNAVAILABLE_CODE = "plugin_connector_unavailable";
/** The plugin connection's identity, read from the connection config. */
export interface PluginConnectionIdentity {
pluginKey: string;
appSlug: string;
methodKey: string;
settings: Record<string, unknown>;
/** True for the implicit connector of legacy top-level manifest `tools`. */
legacyTools: boolean;
}
export function pluginConnectionIdentity(connection: {
transport: string;
config: Record<string, unknown>;
}): PluginConnectionIdentity | null {
if (connection.transport !== "plugin") return null;
const source = parsePluginAppSlug(connection.config.sourceTemplateKey);
const methodKey = connection.config.connectionMethodKey;
if (!source || typeof methodKey !== "string") return null;
const settings = connection.config.settings;
return {
pluginKey: source.pluginKey,
appSlug: source.appSlug,
methodKey,
settings: settings && typeof settings === "object" && !Array.isArray(settings) ? settings as Record<string, unknown> : {},
legacyTools: connection.config.legacyPluginTools === true,
};
}
/** The method a plugin connection was made with, from the current catalog. */
export function pluginConnectionMethod(connection: { config: Record<string, unknown> }): {
app: AppDefinition;
method: ConnectionMethodDef;
} | null {
const slug = connection.config.sourceTemplateKey;
const app = typeof slug === "string" ? getConnectableAppDefinition(slug) : null;
const method = app?.methods.find((candidate) => candidate.key === connection.config.connectionMethodKey);
return app && method?.transport === "plugin" ? { app, method } : null;
}
async function runningWorker(db: Db, pluginKey: string): Promise<string> {
const [plugin] = await db
.select({ id: plugins.id })
.from(plugins)
.where(and(eq(plugins.pluginKey, pluginKey), eq(plugins.status, "ready")));
if (!plugin || !workers || !workers.isRunning(plugin.id)) {
throw new PluginWorkerUnavailableError({
pluginId: plugin?.id ?? pluginKey,
workerStatus: plugin && workers ? workers.getWorker(plugin.id)?.status ?? null : null,
message: "This connector's plugin is not running right now. Try again shortly.",
});
}
return plugin.id;
}
/**
* Whether a saved catalog entry still matches a static tool declaration of
* the connection's method. After an upgrade changes a tool's risk (or drops
* it), the old entry is hidden until the catalog is refreshed, so policy
* never sees an outdated risk. Dynamic catalogs are current as listed.
*/
export function pluginCatalogEntryCurrent(
connection: { config: Record<string, unknown> },
entry: { toolName: string; riskLevel: string },
): boolean {
const tools = pluginConnectionMethod(connection)?.method.tools;
if (!tools) return false;
if (tools.kind === "dynamic") return true;
return tools.list.some((tool) => tool.name === entry.toolName && tool.risk === entry.riskLevel);
}
/**
* A health check for a plugin connection: its tools run in the plugin's
* worker, so the connection is healthy only while that worker runs (static
* catalogs are readable without it).
*/
export async function assertPluginConnectionWorker(
db: Db,
connection: { transport: string; config: Record<string, unknown> },
): Promise<void> {
const identity = pluginConnectionIdentity(connection);
if (!identity) throw new PluginWorkerUnavailableError({ pluginId: "unknown", workerStatus: null, message: "This connector is not available." });
await runningWorker(db, identity.pluginKey);
}
function toolDescriptor(tool: ConnectorToolDescriptor | PluginConnectorToolDef) {
return {
name: tool.name,
...(tool.displayName ? { title: tool.displayName } : {}),
description: tool.description ?? tool.displayName ?? tool.name,
inputSchema: tool.parametersSchema,
// The declared risk travels with the catalog entry; the connector tool
// policy reads it (see `connectors/tool-policy.ts`).
annotations: {
paperclipRisk: tool.risk,
readOnlyHint: tool.risk === "read",
...(tool.risk === "destructive" ? { destructiveHint: true } : {}),
},
};
}
/** The tools of one plugin connection, for its catalog. */
export async function listPluginConnectionTools(
db: Db,
connection: { id: string; companyId: string; transport: string; config: Record<string, unknown> },
credential?: ConnectorToolListConnection["credential"],
) {
const identity = pluginConnectionIdentity(connection);
const resolved = pluginConnectionMethod(connection);
if (!identity || !resolved?.method.tools) {
throw new PluginWorkerUnavailableError({
pluginId: identity?.pluginKey ?? "unknown",
workerStatus: null,
message: "This connector is not available. Its plugin is disabled or no longer provides it.",
});
}
const tools = resolved.method.tools;
if (tools.kind === "static") return tools.list.map(toolDescriptor);
const pluginDbId = await runningWorker(db, identity.pluginKey);
const result = await workers!.call(pluginDbId, "listConnectorTools", {
companyId: connection.companyId,
appSlug: identity.appSlug,
connection: {
id: connection.id,
appSlug: identity.appSlug,
methodKey: identity.methodKey,
settings: identity.settings,
...(credential ? { credential } : {}),
},
});
const listed = Array.isArray(result?.tools) ? result.tools : [];
return listed
.filter((tool) => typeof tool?.name === "string" && PLUGIN_CONNECTOR_TOOL_NAME.test(tool.name)
&& ["read", "write", "destructive"].includes(tool.risk))
.slice(0, 500)
.map((tool) => toolDescriptor({
...tool,
parametersSchema: tool.parametersSchema && typeof tool.parametersSchema === "object" ? tool.parametersSchema : { type: "object" },
}));
}
/** Run one plugin connector tool in its plugin's worker. */
export async function executePluginConnectionTool(
db: Db,
input: {
pluginKey: string;
appSlug: string;
toolName: string;
parameters: unknown;
runContext: ToolRunContext & { connection: NonNullable<ToolRunContext["connection"]> };
},
): Promise<ToolResult> {
const pluginDbId = await runningWorker(db, input.pluginKey);
return workers!.call(pluginDbId, "executeTool", {
toolName: input.toolName,
appSlug: input.appSlug,
parameters: input.parameters,
runContext: input.runContext,
});
}
+20
View File
@@ -326,6 +326,21 @@ export function pluginLifecycleManager(
const registry = pluginRegistryService(db);
const retireConnectorConnections = (pluginKey: string) => retireConnectorConnectionsFor(db, pluginKey);
/**
* After a plugin's worker starts with possibly new code: refresh its
* connector catalogs so declared tools and risks are current, and finish
* carrying over legacy tool access recorded while it was not running.
*/
function afterConnectorPluginActivated(pluginId: string, pluginKey: string) {
void (async () => {
const [{ refreshPluginConnectionCatalogs }, { completeLegacyPluginToolAccess }] = await Promise.all([
import("./plugin-app-catalog.js"),
import("./plugin-connector-legacy-access.js"),
]);
await refreshPluginConnectionCatalogs(db, pluginKey);
await completeLegacyPluginToolAccess(db, pluginKey);
})().catch((error) => log.warn({ err: error, pluginId }, "Could not update plugin connectors after activation"));
}
const pluginLoaderInstance = loaderArg ?? pluginLoader(db);
const emitter = new EventEmitter();
emitter.setMaxListeners(100); // plugins may have many listeners; 100 is a safe upper bound
@@ -507,6 +522,7 @@ export function pluginLifecycleManager(
const result = await transition(pluginId, "ready", null, plugin);
await activateReadyPlugin(pluginId);
afterConnectorPluginActivated(pluginId, result.pluginKey);
emitDomain("plugin.enabled", {
pluginId,
pluginKey: result.pluginKey,
@@ -710,6 +726,7 @@ export function pluginLifecycleManager(
manifestJson: newManifest,
} as PluginRecord);
await activateReadyPlugin(pluginId);
afterConnectorPluginActivated(pluginId, result.pluginKey);
emitDomain("plugin.loaded", {
pluginId,
@@ -754,6 +771,7 @@ export function pluginLifecycleManager(
pluginId,
pluginKey: plugin.pluginKey,
});
afterConnectorPluginActivated(pluginId, plugin.pluginKey);
log.info(
{ pluginId, pluginKey: plugin.pluginKey },
@@ -818,6 +836,7 @@ export function pluginLifecycleManager(
// migration, which makes downstream queries fail against missing tables.
await deactivatePluginRuntime(pluginId, plugin.pluginKey);
await activateReadyPlugin(pluginId);
afterConnectorPluginActivated(pluginId, plugin.pluginKey);
} else {
// No runtime activation services wired in (e.g. state-only test harness)
// — fall back to a bare worker subprocess bounce.
@@ -828,6 +847,7 @@ export function pluginLifecycleManager(
await handle.restart();
emitDomain("plugin.worker_stopped", { pluginId, pluginKey: plugin.pluginKey });
emitDomain("plugin.worker_started", { pluginId, pluginKey: plugin.pluginKey });
afterConnectorPluginActivated(pluginId, plugin.pluginKey);
}
log.info(
+22 -5
View File
@@ -85,6 +85,7 @@ import { stableHash } from "./tool-catalog-hash.js";
import { NATIVE_PROVIDER_SLUGS, nativeProviderCatalogFor } from "./native-provider-catalogs.js";
import { connectorToolPolicy } from "./connectors/tool-policy.js";
import { loadPluginAppCatalog, pluginAppCatalogFor } from "./plugin-app-catalog.js";
import { validateInstanceConfig } from "./plugin-config-validator.js";
import { notifyChatEndpointWork } from "./chat-work-notifications.js";
@@ -111,7 +112,7 @@ import { and, asc, desc, eq, inArray, max, ne, sql } from "drizzle-orm";
import type { Db } from "@paperclipai/db";
import { agents, connectionGrantMembers, connectionGrants, companyMemberships, principalPermissionGrants, userSecretDefinitions, plugins, toolAccessAuditEvents, toolApplications, toolCatalogEntries, toolConnectionInstalls, toolConnections, toolStdioCommandTemplates, toolCallEvents, toolPolicies, toolProfileBindings, toolProfileEntries, toolProfiles } from "@paperclipai/db";
import type { AppDefinition, ConnectionGrantKind, CreateToolApplication, CreateToolConnection, ConnectToolApp, ConnectToolAppResult, CreateToolStdioCommandTemplate, FinishToolApp, FinishToolAppResult, CreateToolProfileBindingForProfile, CreateToolProfileEntryForProfile, DeploymentExposure, DeploymentMode, ImportMcpJson, McpConnectionCredentialRef, McpJsonImportPreview, ToolApplication, ToolCatalogEntry, ToolCatalogRefreshResult, ToolConnection, ToolConnectionInstall, ToolConnectionHealthCheckResult, ToolConnectionAuthKind, ToolConnectionCredentialPolicy, ToolConnectionCredentialSource, ToolConnectionTransport, ToolAppMetadataPreflightResult, ToolExampleInstallResult, ToolExampleSmokeCheck, ToolExampleSmokeResult, ToolExampleSummary, ToolProfileBinding, ToolProfileEntry, ToolPolicyDecision, ToolStdioCommandTemplate, UpdateToolApplication, UpdateToolConnection, VercelConnectCredentialReference } from "@paperclipai/shared";
import { connectionSourceSlug, isPluginAppSlug, parsePluginAppSlug, getAppDefinitionForUrl, getAvailableConnectionMethods, getConnectableAppDefinition, recommendedDefaultsForApp } from "@paperclipai/shared";
import { connectionSourceSlug, isPluginAppSlug, parsePluginAppSlug, getAppDefinitionForUrl, getAvailableConnectionMethods, getConnectableAppDefinition, recommendedDefaultsForApp, type ConnectionMethodDef } from "@paperclipai/shared";
import {
checkMcpRemoteHeaderName,
checkMcpRemoteHeaderValue,
@@ -1677,6 +1678,19 @@ export function toolAccessService(
return `${base.slice(0, 151).trimEnd()} (${randomUUID().slice(0, 6)})`;
}
/** Per-connection settings of a plugin-served method, validated by its schema. */
function pluginConnectionSettings(method: ConnectionMethodDef, settings: Record<string, unknown>): Record<string, unknown> {
if (!method.settingsSchema) {
if (Object.keys(settings).length > 0) throw badRequest("This connector has no settings");
return {};
}
const result = validateInstanceConfig(settings, method.settingsSchema);
if (!result.valid) {
throw unprocessable("Check this connection's settings", { code: "plugin_connection_settings_invalid", errors: result.errors });
}
return settings;
}
async function connectGalleryApp(
companyId: string,
input: ConnectToolApp,
@@ -1925,7 +1939,8 @@ export function toolAccessService(
const transport = method?.transport ?? "mcp_remote";
const applicationType = transport === "rest_api" ? "rest_api"
: transport === "mcp_remote" ? "mcp_http"
: transport === "local_stdio" ? "mcp_stdio" : null;
: transport === "local_stdio" ? "mcp_stdio"
: transport === "plugin" ? "paperclip_plugin" : null;
if ((retainedConnection && retainedConnection.transport !== transport)
|| (existingApplication && applicationType && existingApplication.type !== applicationType)) {
if (requestedResumeConnection || input.applicationId) {
@@ -2207,8 +2222,9 @@ export function toolAccessService(
transport === "mcp_remote" && input.link
? splitRemoteUrlCredential(input.link)
: null;
const baseConfig =
(transport === "mcp_remote" || transport === "rest_api")
const baseConfig = transport === "plugin" && method
? { settings: pluginConnectionSettings(method, input.settings ?? asRecord(asRecord(retainedConnection?.config).settings)) }
: (transport === "mcp_remote" || transport === "rest_api")
? {
url:
(remoteMcpConnector ? remoteUrlCredential?.publicUrl : undefined) ??
@@ -2241,6 +2257,7 @@ export function toolAccessService(
mcpPreserveAccess: Boolean(retainedConnection && (retainedConnection.status === "active" || asRecord(retainedConnection.config).mcpPreserveAccess === true)),
} : {}),
...(galleryEntry.slug === "posthog" ? { safeDefault: true } : {}),
...(galleryEntry.plugin?.legacyTools ? { legacyPluginTools: true } : {}),
// Telem.AI attributes each search to the Paperclip company, agent,
// run and issue, so its catalog connection forwards those context
// headers by default (the gateway still drops empty values). A
@@ -2569,7 +2586,7 @@ export function toolAccessService(
applicationKey: `app-gallery:${galleryEntry?.slug ?? "link"}:${randomUUID()}`,
name: applicationName,
description: safeApplicationDescription,
type: transport === "rest_api" && (["browser-use-cloud", ...NATIVE_PROVIDER_SLUGS].includes(galleryEntry?.slug ?? "") || Boolean(restConnectorFor({ transport, config }))) ? "rest_api" : transport === "mcp_remote" ? "mcp_http" : "mcp_stdio",
type: transport === "plugin" ? "paperclip_plugin" : transport === "rest_api" && (["browser-use-cloud", ...NATIVE_PROVIDER_SLUGS].includes(galleryEntry?.slug ?? "") || Boolean(restConnectorFor({ transport, config }))) ? "rest_api" : transport === "mcp_remote" ? "mcp_http" : "mcp_stdio",
status: "draft",
metadata: galleryEntry
? {
@@ -63,6 +63,9 @@ import type { OAuthCredentialStore } from "../oauth/credential-store.js";
import type { ConnectionSetupPolicy } from "../connections/setup-policy.js";
import type { ToolRemoteHttp } from "../remote-http.js";
import { normalizeToolDescriptor, type McpToolDescriptor } from "./descriptors.js";
import { listPluginConnectionTools, PLUGIN_CONNECTOR_UNAVAILABLE_CODE } from "../../plugin-connector-runtime.js";
import { findPluginWorkerUnavailableError } from "../../plugin-worker-unavailable-error.js";
import { resolveConnectionGrantSecret } from "../../connection-credentials.js";
import { googleWorkspaceServicesUnavailable, unsupportedToolConnectionTransport } from "./failures.js";
const URL_CREDENTIAL_PARAMETER = /token|secret|passw|api[-_]?key|^key$|auth|signature|^sig$|session|credential/i;
@@ -612,6 +615,25 @@ export function createToolCatalogDiscovery(db: Db, { now, audit, secrets, creden
await agentmailApi(key).whoami();
}
/**
* The credential a dynamic plugin connector may need to list its tools: the
* connection's default grant, resolved for this one call only.
*/
async function pluginListingCredential(connection: typeof toolConnections.$inferSelect, actor?: ActorInfo) {
if (connection.authKind !== "api_key") return undefined;
// The same grant selection (and owner checks) as every other credential
// read for this connection and caller.
const grant = await credentials.vaultGrantForConnection(connection, actor);
const ref = grant?.credentialSecretRefs.find((candidate) => candidate.configPath.startsWith("credentials."));
if (!grant || !ref) return undefined;
const { value } = await resolveConnectionGrantSecret(db, connection, grant, ref, {
consumerType: "tool_connection", consumerId: connection.id,
actorType: actor?.actorType === "agent" ? "agent" : actor?.actorType === "user" ? "user" : "system",
actorId: actor?.actorId ?? null, responsibleUserId: grant.subjectUserId,
});
return { kind: "api_key" as const, value };
}
async function discoverTools(
connection: typeof toolConnections.$inferSelect,
credentialHeaders?: Record<string, string>,
@@ -643,6 +665,16 @@ export function createToolCatalogDiscovery(db: Db, { now, audit, secrets, creden
await validateAgentMailConnection(connection);
return [];
}
if (connection.transport === "plugin") {
try {
return await listPluginConnectionTools(db, connection, await pluginListingCredential(connection, actor));
} catch (error) {
if (findPluginWorkerUnavailableError(error)) {
throw unprocessable(error instanceof Error ? error.message : "This connector's plugin is not running right now.", { code: PLUGIN_CONNECTOR_UNAVAILABLE_CODE, retryable: true });
}
throw error;
}
}
if (connection.transport === "mcp_remote")
return remoteTools(connection, credentialHeaders, actor, undefined, unavailableServices, listOptions);
if (connection.transport !== "local_stdio") {
@@ -1,4 +1,6 @@
import { notifyChatConnectionObservation } from "../../chat-channels/configuration-work-notifications.js";
import { assertPluginConnectionWorker, PLUGIN_CONNECTOR_UNAVAILABLE_CODE } from "../../plugin-connector-runtime.js";
import { findPluginWorkerUnavailableError } from "../../plugin-worker-unavailable-error.js";
import { writeToolConnectionHealthChange } from "../../tool-connection-health-notifications.js";
import { connectionActorUserId } from "../actor.js";
import { assertSupportedConnection } from "../connections/setup-policy.js";
@@ -130,8 +132,19 @@ export function createConnectionHealth(db: Db, { now, audit, getConnectionRow, d
});
for (const grant of grantsToCheck)
await refreshManagedGitHubGrantAccess(connection, grant, actor);
} else if (isBrowserUseConnection(connection) || nativeProviderCatalogFor(connection) || restConnectorFor(connection)) {
} else if (isBrowserUseConnection(connection) || nativeProviderCatalogFor(connection) || restConnectorFor(connection)
|| connection.transport === "plugin") {
// A plugin-served connector is healthy when its tools can be listed
// and its plugin's worker is running to serve them.
await discoverTools(connection, undefined, actor);
if (connection.transport === "plugin") {
try {
await assertPluginConnectionWorker(db, connection);
} catch (error) {
if (!findPluginWorkerUnavailableError(error)) throw error;
throw unprocessable(error instanceof Error ? error.message : "This connector's plugin is not running right now.", { code: PLUGIN_CONNECTOR_UNAVAILABLE_CODE, retryable: true });
}
}
} else if (isAgentMailConnection(connection)) {
await validateAgentMailConnection(connection);
} else if (connection.transport === "mcp_remote") {
@@ -1,5 +1,10 @@
import { writeToolConnectionHealthChange } from "../../tool-connection-health-notifications.js";
import { connectorToolPolicy } from "../../connectors/tool-policy.js";
function pluginDeclaredRisk(descriptor: { annotations?: Record<string, unknown> | null }) {
const declared = descriptor.annotations?.paperclipRisk;
return declared === "read" || declared === "write" || declared === "destructive" ? declared : "write";
}
import { connectionSetupUrl, connectionReconnectUrl } from "../identifiers.js";
import { createToolRuntimeSlots } from "../runtime/slots.js";
import type { ActorInfo, ToolAccessMutationDb } from "../types.js";
@@ -141,7 +146,7 @@ export function createToolCatalogPublication(db: Db, { now, audit, getConnection
existingRows.map((entry) => [entry.toolName, entry]),
);
const nativeProvider = Boolean(nativeProviderCatalogFor(connection) || restConnectorFor(connection));
if (connection.config.sourceTemplateKey === "google-workspace"
if (connection.config.sourceTemplateKey === "google-workspace" || connection.transport === "plugin"
|| nativeProvider || isRemoteMcpConnectorMethod(connection.config.sourceTemplateKey, connection.config.connectionMethodKey)) {
const discoveredNames = new Set(descriptors.map((descriptor) => descriptor.name));
// The catalog is shared, but discovery uses only the caller's grant. A
@@ -214,7 +219,13 @@ export function createToolCatalogPublication(db: Db, { now, audit, getConnection
refreshOptions.quarantineManagedOAuthDraft === true);
const safeDefault = asRecord(connection.config).safeDefault === true;
for (const descriptor of descriptors) {
const riskLevel = classifyRisk(descriptor, connectorPolicy.sourceTemplateKey);
// A plugin-served connection's tools carry the risk its plugin declared
// (statically, or per connection from its worker). Other transports keep
// the reviewed classifier; a remote server cannot set this annotation's
// effect because it is read only for plugin connections.
const riskLevel = connection.transport === "plugin"
? pluginDeclaredRisk(descriptor)
: classifyRisk(descriptor, connectorPolicy.sourceTemplateKey);
const hash = descriptorHash(descriptor, riskLevel);
const schemaHash = stableHash(descriptor.inputSchema ?? {});
const existing = existingByName.get(descriptor.name);
@@ -70,6 +70,7 @@ export function createConnectionTokenBroker(db: Db, { now, secrets, policySvc, a
if (nativeProvider) throw forbidden(`${nativeProvider.name} credentials stay in the governed tool gateway and cannot be exported.`);
if (restConnectorFor(connection)) throw forbidden("Deployment connection credentials stay in the governed tool gateway and cannot be exported.");
if (isBrowserUseConnection(connection)) throw forbidden("Browser Use credentials stay in the governed tool gateway and cannot be exported.");
if (connection.transport === "plugin") throw forbidden("Plugin connector credentials stay in the governed tool gateway and cannot be exported.");
if (connection.connectionPurpose === "ai") throw unprocessable("AI credentials are available only through the runtime resolver");
const application = await getConnectionApplication(connection);
const brokerEnabled = connectionTokenBrokerEnabled(connection);
+219 -34
View File
@@ -76,8 +76,11 @@ import {
} from "./mcp-tasks.js";
import { logger } from "../middleware/logger.js";
import { getAppDefinitionForApplicationKey, isConnectorFeatureEnabled } from "@paperclipai/shared";
import { connectionSourceSlug } from "@paperclipai/shared";
import { connectionSourceSlug, pluginAppSlug } from "@paperclipai/shared";
import { pluginAppCatalogFor } from "./plugin-app-catalog.js";
import { findPluginWorkerUnavailableError } from "./plugin-worker-unavailable-error.js";
import { inferToolRisk } from "./tool-risk-inference.js";
import { executePluginConnectionTool as executePluginConnectionWorkerTool, pluginCatalogEntryCurrent, pluginConnectionIdentity, PLUGIN_CONNECTOR_UNAVAILABLE_CODE } from "./plugin-connector-runtime.js";
import { requestConfirmationPayloadSchema } from "@paperclipai/shared";
import { instanceSettingsService } from "./instance-settings.js";
import { redactSensitiveText } from "../redaction.js";
@@ -126,6 +129,7 @@ import {
toolCallEvents,
toolCatalogEntries,
toolConnections,
toolConnectionInstalls,
toolGatewayRateLimitCounters,
toolGatewaySessions,
toolInvocations,
@@ -386,6 +390,7 @@ export type ToolGatewayProviderType =
| "mcp_local_stdio"
| "paperclip_self"
| "paperclip_plugin"
| "paperclip_plugin_connection"
| "paperclip_virtual"
| "paperclip_github_chat"
| "paperclip_slack_chat"
@@ -397,7 +402,7 @@ export interface ConnectedMcpGatewayMetadata {
applicationDisplayName: string;
connectionId: string;
catalogEntryId: string;
transport: "mcp_remote" | "local_stdio" | "rest_api";
transport: "mcp_remote" | "local_stdio" | "rest_api" | "plugin";
gatewayToolName: string;
upstreamToolName: string;
catalogName: string;
@@ -1035,24 +1040,6 @@ function summarizeResult(result: unknown): Record<string, unknown> {
};
}
function inferToolRisk(toolName: string): ToolGatewayDescriptor["risk"] {
const lower = toolName.toLowerCase();
if (
/\b(delete|destroy|remove|drop|truncate|wipe|purge)\b|(^|[:._-])(delete|destroy|remove|drop|truncate|wipe|purge)([:._-]|$)/.test(
lower,
)
) {
return "destructive";
}
if (
/\b(create|update|write|edit|patch|post|send|publish|merge|commit|apply)\b|(^|[:._-])(create|update|write|edit|patch|post|send|publish|merge|commit|apply)([:._-]|$)/.test(
lower,
)
) {
return "write";
}
return "read";
}
function riskFromCatalogEntry(
entry: Pick<
@@ -1117,7 +1104,7 @@ export function connectionToolNamespace(input: {
const namespaceSource = typeof peerNamespace === "string" && peerNamespace
? peerNamespace
: input.applicationKey ?? input.connectionName ?? input.applicationName;
return `${input.transport === "rest_api" ? "app" : "mcp"}.${slugSegment(namespaceSource, "mcp")}-${shortStableId(input.connectionId)}`;
return `${input.transport === "rest_api" || input.transport === "plugin" ? "app" : "mcp"}.${slugSegment(namespaceSource, "mcp")}-${shortStableId(input.connectionId)}`;
}
function toolRequiresFormalApproval(tool: ToolGatewayDescriptor): boolean {
@@ -1535,9 +1522,73 @@ export function createToolGatewayService(
delegatedGatewayIssuer: issuerId,
} };
}
/**
* The implicit connector of a legacy plugin tool, when it is installed for
* this agent: its connection and the catalog entry for this tool.
*/
async function legacyPluginToolBinding(companyId: string, agentId: string, toolName: string) {
const separator = toolName.indexOf(":");
if (separator <= 0) return null;
const [row] = await db
.select({ connectionId: toolConnections.id, applicationId: toolConnections.applicationId, catalogEntryId: toolCatalogEntries.id })
.from(toolConnections)
.innerJoin(toolConnectionInstalls, and(
eq(toolConnectionInstalls.companyId, toolConnections.companyId),
eq(toolConnectionInstalls.connectionId, toolConnections.id),
))
.innerJoin(toolCatalogEntries, and(
eq(toolCatalogEntries.connectionId, toolConnections.id),
eq(toolCatalogEntries.toolName, toolName.slice(separator + 1)),
))
.where(and(
eq(toolConnections.companyId, companyId),
eq(toolConnections.transport, "plugin"),
eq(toolConnections.status, "active"),
eq(toolConnections.enabled, true),
sql`${toolConnections.config}->>'legacyPluginTools' = 'true'`,
sql`${toolConnections.config}->>'sourceTemplateKey' = ${pluginAppSlug(toolName.slice(0, separator), "default")}`,
or(
and(eq(toolConnectionInstalls.targetType, "company"), eq(toolConnectionInstalls.targetId, companyId)),
and(eq(toolConnectionInstalls.targetType, "agent"), eq(toolConnectionInstalls.targetId, agentId)),
),
))
.limit(1);
return row ?? null;
}
/**
* A legacy plugin tool keeps today's access decision (its name, grants and
* policies), and the action rules saved on its implicit connector can only
* restrict it further: Off hides it and Ask first requires approval. The
* connector check uses a name no existing rule can match, so it never
* grants anything a legacy rule did not.
*/
async function decideWithLegacyPluginRules(
input: ToolAccessDecisionInput,
decisionOptions: Parameters<typeof decideGatewayPolicy>[1] = {},
): Promise<ToolAccessDecision> {
const decision = await decideGatewayPolicy(input, decisionOptions);
const agentId = input.actor.agentId;
if (decision.decision !== "allow" || input.request.providerType !== "paperclip_plugin" || !agentId) return decision;
const binding = await legacyPluginToolBinding(input.companyId, agentId, input.request.toolName);
if (!binding) return decision;
const restricted = await decideGatewayPolicy({
...input,
consumeRateLimit: false,
request: {
...input.request,
toolName: `legacy-plugin-tool:${binding.catalogEntryId}`,
applicationId: binding.applicationId,
connectionId: binding.connectionId,
catalogEntryId: binding.catalogEntryId,
},
}, { ...decisionOptions, cache: undefined });
return restricted.decision === "allow" ? decision : restricted;
}
const policyService = {
...basePolicyService,
decide: decideGatewayPolicy,
decide: decideWithLegacyPluginRules,
admitInvocation(input: ToolAccessDecisionInput, invocationId: string, claim?: ToolApprovalClaim) {
return basePolicyService.admitInvocation(input, invocationId, claim, (policy, admissionInput, transaction) =>
decideGatewayPolicy(admissionInput, { admittedInvocationId: invocationId, requiredGatewayAction: "tools/call" }, policy, transaction));
@@ -1687,10 +1738,62 @@ export function createToolGatewayService(
return [...BUILTIN_TOOLS, ...pluginTools()];
}
/**
* Plugins whose legacy top-level tools this agent may use: a connection of
* the plugin's implicit connector is active and installed for this agent or
* for the whole company. Existing installations got such a connection once
* (see `plugin-connector-legacy-access.ts`); new installs start with none.
*/
async function legacyPluginToolKeys(companyId: string, agentId: string | null | undefined): Promise<Set<string>> {
if (!agentId) return new Set();
const rows = await db
.select({ config: toolConnections.config })
.from(toolConnections)
.innerJoin(toolConnectionInstalls, and(
eq(toolConnectionInstalls.companyId, toolConnections.companyId),
eq(toolConnectionInstalls.connectionId, toolConnections.id),
))
.where(and(
eq(toolConnections.companyId, companyId),
eq(toolConnections.transport, "plugin"),
eq(toolConnections.status, "active"),
eq(toolConnections.enabled, true),
sql`${toolConnections.config}->>'legacyPluginTools' = 'true'`,
or(
and(eq(toolConnectionInstalls.targetType, "company"), eq(toolConnectionInstalls.targetId, companyId)),
and(eq(toolConnectionInstalls.targetType, "agent"), eq(toolConnectionInstalls.targetId, agentId)),
),
));
const keys = new Set<string>();
for (const row of rows) {
const identity = pluginConnectionIdentity({ transport: "plugin", config: row.config });
if (identity?.legacyTools) keys.add(identity.pluginKey);
}
return keys;
}
/**
* The plugin key of a legacy plugin tool, from its namespaced name
* (`<pluginKey>:<tool>`). Descriptors carry the plugin's database id in
* `pluginId`, so the name is the stable key shared with connections.
*/
function legacyToolPluginKey(tool: { name: string }): string | null {
const separator = tool.name.indexOf(":");
return separator > 0 ? tool.name.slice(0, separator) : null;
}
/** Built-in tools plus the legacy plugin tools this agent may use. */
async function toolsForAgent(companyId: string, agentId: string | null | undefined): Promise<ToolGatewayDescriptor[]> {
const plugin = pluginTools();
if (plugin.length === 0) return [...BUILTIN_TOOLS];
const allowed = await legacyPluginToolKeys(companyId, agentId);
return [...BUILTIN_TOOLS, ...plugin.filter((tool) => allowed.has(legacyToolPluginKey(tool) ?? ""))];
}
function connectedMcpConnectionFilter(companyId: string) {
return and(
eq(toolConnections.companyId, companyId),
inArray(toolConnections.transport, ["mcp_remote", "local_stdio", "rest_api"]),
inArray(toolConnections.transport, ["mcp_remote", "local_stdio", "rest_api", "plugin"]),
eq(toolConnections.status, "active"),
eq(toolConnections.enabled, true),
// A personal connection has no company-level credential to probe. A
@@ -1698,12 +1801,16 @@ export function createToolGatewayService(
// while the responsible user's grant is valid. Keep its cached active
// catalog discoverable; execution resolves and validates that user's
// grant, and a successful call restores the shared health indicator.
// A plugin connection's health mostly reflects its worker, which the
// host restarts on its own; each call checks the worker and fails
// retryably while it is down, so a stale error must not hide the tools.
or(
inArray(toolConnections.healthStatus, ["ok", "healthy"]),
eq(toolConnections.credentialPolicy, "per_user"),
eq(toolConnections.transport, "plugin"),
),
eq(toolApplications.companyId, companyId),
inArray(toolApplications.type, ["mcp_http", "mcp_stdio", "rest_api"]),
inArray(toolApplications.type, ["mcp_http", "mcp_stdio", "rest_api", "paperclip_plugin"]),
eq(toolApplications.status, "active"),
);
}
@@ -1794,7 +1901,13 @@ export function createToolGatewayService(
(connection.transport === "mcp_remote" &&
application.type === "mcp_http") ||
(connection.transport === "local_stdio" &&
application.type === "mcp_stdio")),
application.type === "mcp_stdio") ||
// Legacy top-level plugin tools keep their original names and are
// listed by the plugin tool path, gated by this connection's installs.
(connection.transport === "plugin" &&
application.type === "paperclip_plugin" &&
!pluginConnectionIdentity(connection)?.legacyTools &&
pluginCatalogEntryCurrent(connection, catalogEntry))),
);
const baseNames = eligibleRows.map(
({ catalogEntry, connection, application }) => {
@@ -1817,7 +1930,7 @@ export function createToolGatewayService(
({ catalogEntry, connection, application }, index) => {
if (
connection.transport !== "mcp_remote" &&
connection.transport !== "local_stdio" && !isBrowserUseConnection(connection) && !nativeProviderCatalogFor(connection) && !restConnectorFor(connection)
connection.transport !== "local_stdio" && connection.transport !== "plugin" && !isBrowserUseConnection(connection) && !nativeProviderCatalogFor(connection) && !restConnectorFor(connection)
) {
throw new Error(
`Non-MCP connection ${connection.id} cannot be exposed through the MCP gateway`,
@@ -1877,7 +1990,7 @@ export function createToolGatewayService(
parametersSchema: inputSchema,
pluginId: `mcp:${applicationKey ?? application.id}`,
providerType:
connection.transport === "rest_api" ? "provider_rest" : connection.transport === "local_stdio"
connection.transport === "plugin" ? "paperclip_plugin_connection" : connection.transport === "rest_api" ? "provider_rest" : connection.transport === "local_stdio"
? "mcp_local_stdio"
: "mcp_remote_http",
risk,
@@ -3236,7 +3349,7 @@ export function createToolGatewayService(
const hasOnDemandTargets = connectedTools.some(isOnDemandRemoteTool);
const virtualTools = hasOnDemandTargets ? VIRTUAL_TOOLS : [];
const githubBotTools = await githubBotToolsForSession(db, session);
const tool = [...allTools(), ...connectedTools, ...virtualTools, ...githubBotTools, ...await slackToolsForSession(db, session), ...await spekoToolsForSession(db, session)]
const tool = [...await toolsForAgent(session.companyId, session.agentId), ...connectedTools, ...virtualTools, ...githubBotTools, ...await slackToolsForSession(db, session), ...await spekoToolsForSession(db, session)]
.filter(
(candidate) =>
session.agentId ||
@@ -3489,7 +3602,7 @@ export function createToolGatewayService(
const connectionTools = await connectionToolsForContext(session);
const onDemandTargets = connectionTools.filter(isOnDemandRemoteTool);
const tools = [
...allTools(),
...await toolsForAgent(session.companyId, session.agentId),
...connectionTools.filter((tool) => !isOnDemandRemoteTool(tool)),
].filter(
(tool) =>
@@ -4912,6 +5025,66 @@ export function createToolGatewayService(
});
}
/**
* Run a plugin connector tool in its plugin's worker. The gateway already
* decided policy and recorded the invocation; here it resolves the grant
* and credential for this one call. The run context comes only from the
* session, never from tool arguments.
*/
async function executePluginConnectionTool(
session: ToolGatewaySession,
tool: ToolGatewayDescriptor,
parameters: unknown,
) {
const [connection] = await db.select().from(toolConnections).where(and(
eq(toolConnections.companyId, session.companyId),
eq(toolConnections.id, tool.connectionId ?? ""),
));
const identity = connection ? pluginConnectionIdentity(connection) : null;
if (!connection || !identity || !tool.upstreamToolName) {
throw new ToolGatewayHttpError(404, `Tool "${tool.name}" not found`, "tool_not_found", { tool: tool.name });
}
const grant = await resolveConnectionGrant(session, connection);
let credential: { kind: "api_key"; value: string } | undefined;
if (connection.authKind === "api_key") {
const ref = grant.credentialSecretRefs.find((candidate) => candidate.configPath.startsWith("credentials."));
if (!ref) throw new ToolGatewayHttpError(409, "Reconnect this connection to add its credential.", "grant_credential_missing");
credential = { kind: "api_key", value: await resolveGrantSecretValue(session, connection, grant, ref) };
}
let result: Awaited<ReturnType<typeof executePluginConnectionWorkerTool>>;
try {
result = await executePluginConnectionWorkerTool(db, {
pluginKey: identity.pluginKey,
appSlug: identity.appSlug,
toolName: tool.upstreamToolName,
parameters,
runContext: {
agentId: session.agentId ?? "",
runId: session.runId ?? "",
companyId: session.companyId,
projectId: session.projectId ?? "",
connection: {
id: connection.id,
appSlug: identity.appSlug,
methodKey: identity.methodKey,
grantId: grant.id,
settings: identity.settings,
...(credential ? { credential } : {}),
},
},
});
} catch (error) {
const unavailable = findPluginWorkerUnavailableError(error);
if (unavailable) {
throw new ToolGatewayHttpError(503, unavailable.message, PLUGIN_CONNECTOR_UNAVAILABLE_CODE, { retryable: true });
}
throw error;
}
// A worker error is returned, not thrown: callers screen and redact the
// result (error text included) before reporting it.
return result;
}
async function resolveConnectionGrant(
session: ToolGatewaySession,
connection: typeof toolConnections.$inferSelect,
@@ -6419,7 +6592,10 @@ export function createToolGatewayService(
return { endpointId: authority.endpoint.id, userId: authority.userId, revision: authority.revision, identityContextId: authority.identityContextId };
}
if (
(tool.providerType !== "mcp_remote_http" && tool.providerType !== "provider_rest") ||
(tool.providerType !== "mcp_remote_http" && tool.providerType !== "provider_rest"
// A plugin connector's settings and credential are part of what was
// reviewed: a change requires a new review, like a remote connection.
&& tool.providerType !== "paperclip_plugin_connection") ||
!tool.connectionId ||
!tool.catalogEntryId
) {
@@ -9724,7 +9900,10 @@ export function createToolGatewayService(
args.timeoutMs === undefined,
args.invocationId,
)
: null;
: args.tool.providerType === "paperclip_plugin_connection"
// Test calls run plugin connector tools through the same worker path.
? { result: await runWithTimeout(executePluginConnectionTool(args.session, args.tool, args.parameters), executionTimeoutMs) } as unknown as Awaited<ReturnType<typeof executeLocalStdioTool>>
: null;
if (!connectedMcpExecution) {
throw new ToolGatewayHttpError(
404,
@@ -10606,6 +10785,8 @@ export function createToolGatewayService(
: null;
const result = connectedMcpExecution
? connectedMcpExecution.result
: tool.providerType === "paperclip_plugin_connection"
? await runWithTimeout(executePluginConnectionTool(session, tool, parameters), executionTimeoutMs)
: tool.providerType !== "paperclip_plugin"
? await runWithTimeout(
executeBuiltinTool(session, tool, parameters, invocation.id),
@@ -11592,7 +11773,8 @@ export function createToolGatewayService(
agentId: string;
}): Promise<AgentToolDescriptor[]> {
await assertAgentInCompany(input.companyId, input.agentId);
const decisions = await decideToolsForListing(pluginTools(), (tool) =>
const allowed = await legacyPluginToolKeys(input.companyId, input.agentId);
const decisions = await decideToolsForListing(pluginTools().filter((tool) => allowed.has(legacyToolPluginKey(tool) ?? "")), (tool) =>
policyInputForAgentTool({
companyId: input.companyId,
agentId: input.agentId,
@@ -13584,6 +13766,8 @@ export function createToolGatewayService(
: null;
const result = recoveredGitHubPublication ?? (connectedMcpExecution
? connectedMcpExecution.result
: tool.providerType === "paperclip_plugin_connection"
? await runWithTimeout(executePluginConnectionTool(session, tool, effectiveParameters), executionTimeoutMs)
: tool.providerType === "paperclip_plugin"
? await runWithTimeout(
pluginToolDispatcher!.executeTool(
@@ -13610,7 +13794,7 @@ export function createToolGatewayService(
promptInjectionMode: "block", classifier: resultClassifier(session, tool, invocationId, { approvedAction: Boolean(input.approvedActionRequestId), signal: input.signal }),
});
const completedAt = new Date();
const validatedMcpResult = connectedMcpExecution
const validatedMcpResult = connectedMcpExecution || tool.providerType === "paperclip_plugin_connection"
? asRecord(resultValidation.value)
: null;
if (validatedMcpResult?.error) {
@@ -13914,7 +14098,8 @@ export function createToolGatewayService(
const tool = findStaticTool(input.tool);
if (tool.providerType !== "paperclip_plugin") {
if (tool.providerType !== "paperclip_plugin"
|| !(await legacyPluginToolKeys(input.runContext.companyId, input.runContext.agentId)).has(legacyToolPluginKey(tool) ?? "")) {
throw new ToolGatewayHttpError(
404,
`Tool "${input.tool}" is not a plugin tool`,
@@ -0,0 +1,19 @@
/** Risk of a legacy plugin agent tool, inferred from its name. */
export function inferToolRisk(toolName: string): "read" | "write" | "destructive" {
const lower = toolName.toLowerCase();
if (
/\b(delete|destroy|remove|drop|truncate|wipe|purge)\b|(^|[:._-])(delete|destroy|remove|drop|truncate|wipe|purge)([:._-]|$)/.test(
lower,
)
) {
return "destructive";
}
if (
/\b(create|update|write|edit|patch|post|send|publish|merge|commit|apply)\b|(^|[:._-])(create|update|write|edit|patch|post|send|publish|merge|commit|apply)([:._-]|$)/.test(
lower,
)
) {
return "write";
}
return "read";
}