mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 18:26:40 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Plugins can serve connector tools from their worker (`transport: "plugin"`, added in #22004, #22019 and #22201). > - The tool gateway runs these tools with a fixed 10 s default timeout. > - Some plugin tools call backends that take 12–20 s. These calls fail every time with "Tool execution timed out", even though the plugin's own HTTP client waits much longer. > - The plugin connector design said that the connector, not a fixed gateway constant, sets the timeout. > - This pull request lets a plugin method or a single static tool declare `timeoutMs`, and gives plugin-served tools a 30 s default. > - The benefit is that a plugin connector can serve slow tools like other connectors can, within the same 60 s gateway ceiling. ## Linked Issues or Issue Description Refs #22004, #22019, #22201. Refs #20746. **Relationship to #20746.** This PR builds alongside #20746. It does not supersede it. #20746 changes the default for legacy top-level plugin tools (provider `paperclip_plugin`) to 60 s. This PR changes only plugin-served connector tools (provider `paperclip_plugin_connection`, `transport: "plugin"`). The two PRs touch different branches of the gateway and can merge in either order. This PR does not pin the legacy default in its tests, so #20746 does not break them. **Current behavior** A plugin connector tool always times out after 10 s, unless the caller sends `timeoutMs`. Agents and runners do not send it. The worker RPC also stops at 30 s. **Proposed behavior** A plugin can declare `timeoutMs` (1000–60000 ms) on a `transport: "plugin"` method or on one static tool. The gateway uses that value. If nothing is declared, the gateway waits 30 s. **Reason and benefit** Plugin tools whose backends take longer than 10 s can now work. Plugin authors control the value in the manifest, and the gateway keeps its 60 s ceiling. **Breaking changes** None. Existing manifests stay valid. Only plugin-served tools get the new 30 s default. ## What Changed - `packages/shared`: `timeoutMs` is a new optional field on `ConnectionMethodDef` and on `PluginConnectorToolDef`. The validator accepts integers from 1000 to 60000 only. It rejects `timeoutMs` on methods that do not use `transport: "plugin"`. New exported constants: `PLUGIN_CONNECTOR_TOOL_TIMEOUT_MIN_MS`, `PLUGIN_CONNECTOR_TOOL_TIMEOUT_MAX_MS`, and `PLUGIN_CONNECTOR_TOOL_DEFAULT_TIMEOUT_MS` (30000). - `server/src/services/plugin-connector-runtime.ts`: `pluginConnectionToolTimeoutMs()` resolves the timeout in this order: the tool's value, then the method's value, then 30 s. The worker `executeTool` RPC now gets the gateway timeout plus 1 s. Thus the gateway's `tool_timeout` error is what callers see, and the 30 s RPC default no longer cuts off a longer declared timeout. - `server/src/services/tool-gateway.ts`: `executePluginConnectionTool` now applies the timeout itself, after it loads the connection. All three plugin paths use it: session, assigned-tool and direct calls (`executeTool`), test calls (`executeTestCall`), and approved action execution. If a caller sends `timeoutMs`, that value wins, as before. It is still clamped to 60 s. Approved actions keep their fixed 60 s budget. - Other transports do not change. Remote MCP, local stdio, built-in and legacy plugin tools keep their timeouts. (#20746 separately proposes a 60 s default for legacy plugin tools.) - Docs: `doc/plugins/PLUGIN_SPEC.md` §11A and the plugin SDK README describe the field, its range, and the default. The SDK manifest type gets the field from `@paperclipai/shared`. ### Why 30 s 30 s is the same as the plugin worker manager's default RPC timeout. So, before this change, the worker already allowed 30 s, and only the gateway's 10 s limit stopped the call. With 30 s, the common 12–20 s backend case works without a declaration. It is also well under the 60 s ceiling. Tools that need more time can declare up to 60 s. ## Verification - New `server/src/__tests__/plugin-connector-tool-timeout.test.ts` runs the real gateway invocation path against an embedded Postgres and a fake worker. Fake timers make the 12 s backend free in wall-clock time: - With method `timeoutMs: 30000`, a 12 s tool succeeds through `executeTool` and through `executeTestCall`. The worker RPC timeout is 31000. - With tool `timeoutMs: 5000`, a 12 s tool fails at 5 s with `504 tool_timeout`. - With no declaration, a 12 s tool succeeds (it failed at the old 10 s), and a 45 s tool times out at 30 s. - Manifest values above 60000, below 1000, or not integers are rejected. A caller `timeoutMs: 120000` is clamped to 60 s. - A legacy plugin tool (`paperclip_plugin`, a different provider path) never reaches the connector runtime, and a caller deadline still applies. This test does not pin the legacy default, because #20746 changes it. - Remote MCP, local stdio and REST timeouts do not change in this PR. Their existing timeout tests in `tool-gateway.test.ts` and `google-workspace-rest-transport.test.ts` still apply. - Red/green: with the source change reverted, 4 of these 5 tests fail. The legacy-tool test passes both ways, as expected. - `packages/shared/src/plugin-apps.test.ts`: validation cases for the range, non-integer values, and non-plugin methods. - Commands run: - `pnpm --filter @paperclipai/shared typecheck && pnpm --filter @paperclipai/server typecheck && pnpm --filter @paperclipai/plugin-sdk typecheck` - `cd server && npx vitest run src/__tests__/plugin-connector-tool-timeout.test.ts src/__tests__/plugin-connectors-plugin-transport.test.ts src/__tests__/plugin-connector-agent-grant.test.ts` (20 passed) - `cd packages/shared && npx vitest run src/plugin-apps.test.ts src/app-definitions.test.ts` (76 passed) - `pnpm check:module-boundaries` - Full suite not run locally. CI supplies it. ## Risks - Low risk. Plugin-served tools now wait up to 30 s instead of 10 s by default. An agent turn can wait longer for a slow or stuck plugin tool, but never longer than the existing 60 s ceiling. - The connection row lookup now runs before the timeout timer starts. This is one indexed query. - Dynamic tool lists (`kind: "dynamic"`) use the method's `timeoutMs`. Per-tool values apply to static tools only. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), through Claude Code with tool use (shell, file edits, test runs). ## 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>
210 lines
8.0 KiB
TypeScript
210 lines
8.0 KiB
TypeScript
/**
|
|
* 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_DEFAULT_TIMEOUT_MS,
|
|
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);
|
|
}
|
|
|
|
export function pluginConnectionToolTimeoutMs(
|
|
connection: { config: Record<string, unknown> },
|
|
toolName: string,
|
|
): number {
|
|
const method = pluginConnectionMethod(connection)?.method;
|
|
const tools = method?.tools;
|
|
const tool = tools?.kind === "static" ? tools.list.find((candidate) => candidate.name === toolName) : undefined;
|
|
return tool?.timeoutMs ?? method?.timeoutMs ?? PLUGIN_CONNECTOR_TOOL_DEFAULT_TIMEOUT_MS;
|
|
}
|
|
|
|
const PLUGIN_CONNECTOR_RPC_GRACE_MS = 1_000;
|
|
|
|
/**
|
|
* 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"]> };
|
|
timeoutMs: number;
|
|
},
|
|
): 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,
|
|
}, input.timeoutMs + PLUGIN_CONNECTOR_RPC_GRACE_MS);
|
|
}
|