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>
227 lines
12 KiB
TypeScript
227 lines
12 KiB
TypeScript
import { afterEach, describe, expect, it } from "vitest";
|
|
import { APP_DEFINITIONS } from "./app-definitions.generated.js";
|
|
import {
|
|
getAppStoreDefinition,
|
|
getConnectableAppDefinition,
|
|
isConnectableAppSlug,
|
|
setPluginAppDefinitions,
|
|
} from "./app-definitions.js";
|
|
import { getAppDefinitionForApplicationKey } from "./connector-identity.js";
|
|
import {
|
|
isPluginAppSlug,
|
|
parsePluginAppSlug,
|
|
pluginAppDefinition,
|
|
pluginAppSlug,
|
|
reviewedToolRisk,
|
|
} from "./plugin-apps.js";
|
|
import { PLUGIN_CONNECTOR_TOOL_TIMEOUT_MAX_MS, PLUGIN_CONNECTOR_TOOL_TIMEOUT_MIN_MS, type AppDefinition } from "./types/app-definition.js";
|
|
import { appDefinitionSchema } from "./validators/app-definition.js";
|
|
import { pluginManifestV1Schema } from "./validators/plugin.js";
|
|
|
|
const circleback = APP_DEFINITIONS.find((app) => app.slug === "circleback") as AppDefinition;
|
|
const manifest = {
|
|
id: "example.meetings",
|
|
apiVersion: 1,
|
|
version: "1.0.0",
|
|
displayName: "Meetings",
|
|
description: "Meeting connectors",
|
|
author: "Tests",
|
|
categories: ["connector"],
|
|
capabilities: ["connectors.provide"],
|
|
entrypoints: { worker: "worker.js" },
|
|
apps: [structuredClone(circleback)],
|
|
};
|
|
|
|
afterEach(() => setPluginAppDefinitions([]));
|
|
|
|
describe("plugin app manifests", () => {
|
|
it("accepts apps that use the built-in app-definition schema with connectors.provide", () => {
|
|
const parsed = pluginManifestV1Schema.parse(manifest);
|
|
expect(parsed.apps?.[0]).toMatchObject({ slug: "circleback", name: "Circleback" });
|
|
});
|
|
|
|
it("requires connectors.provide for apps", () => {
|
|
const result = pluginManifestV1Schema.safeParse({ ...manifest, capabilities: ["agent.tools.register"] });
|
|
expect(result.success).toBe(false);
|
|
expect(JSON.stringify(result.error?.issues)).toContain("connectors.provide");
|
|
});
|
|
|
|
it("rejects duplicate slugs within one plugin", () => {
|
|
const result = pluginManifestV1Schema.safeParse({ ...manifest, apps: [circleback, circleback] });
|
|
expect(result.success).toBe(false);
|
|
expect(JSON.stringify(result.error?.issues)).toContain("Duplicate app slug");
|
|
});
|
|
|
|
it("validates each app with the built-in app-definition schema", () => {
|
|
const { methods: _methods, ...withoutMethods } = circleback;
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, apps: [withoutMethods] }).success).toBe(false);
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, apps: [{ ...circleback, slug: "Not A Slug" }] }).success).toBe(false);
|
|
});
|
|
|
|
it.each(["plugin", "aiConnectionRouter", "experimentalFeatureKey", "availability"])("rejects host-derived field %s", (field) => {
|
|
const values: Record<string, unknown> = {
|
|
plugin: { pluginKey: "other.plugin", appSlug: "circleback" },
|
|
aiConnectionRouter: { pluginKey: "example.meetings" },
|
|
experimentalFeatureKey: "enableMemoryConnectors",
|
|
availability: { available: true },
|
|
};
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, apps: [{ ...circleback, [field]: values[field] }] }).success).toBe(false);
|
|
});
|
|
|
|
it("limits plugin app methods to tool transports a definition can fully describe", () => {
|
|
const method = circleback.methods[0]!;
|
|
for (const changed of [
|
|
{ ...method, transport: "rest_api" },
|
|
{ ...method, transport: "chat_sdk" },
|
|
{ ...method, purpose: "channel" },
|
|
{ ...method, provider: "slack" },
|
|
]) {
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, apps: [{ ...circleback, methods: [changed] }] }).success).toBe(false);
|
|
}
|
|
});
|
|
});
|
|
|
|
describe("plugin app credentials", () => {
|
|
const asana = APP_DEFINITIONS.find((app) => app.slug === "asana") as AppDefinition;
|
|
const managed = asana.methods.find((method) => method.oauthStrategy === "paperclip_cloud_connector")!;
|
|
|
|
it("allows a managed OAuth profile only with the built-in connector's endpoint", () => {
|
|
const copy = { ...structuredClone(asana), methods: [structuredClone(managed)] };
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, apps: [copy] }).success).toBe(true);
|
|
const redirected = structuredClone(copy);
|
|
redirected.methods[0]!.defaults = { ...redirected.methods[0]!.defaults, serverUrl: "https://plugin.example.test/mcp" };
|
|
const result = pluginManifestV1Schema.safeParse({ ...manifest, apps: [redirected] });
|
|
expect(result.success).toBe(false);
|
|
expect(JSON.stringify(result.error?.issues)).toContain("managed OAuth profile");
|
|
});
|
|
|
|
it("rejects Vercel Connect credentials in plugin apps", () => {
|
|
const vercel = APP_DEFINITIONS.flatMap((app) => app.methods).find((method) => method.credentialSources?.vercelConnect);
|
|
expect(vercel).toBeTruthy();
|
|
const app = { ...structuredClone(circleback), methods: [{ ...structuredClone(circleback.methods[0]!), auth: "api_key", ownershipModes: ["customer"],
|
|
keyPlacement: { location: "header", name: "Authorization", prefix: "Bearer " }, credentialSources: vercel!.credentialSources }] };
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, apps: [app] }).success).toBe(false);
|
|
});
|
|
|
|
it("rejects a plugin id and slug too long for the connect API", () => {
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, id: `a${"b".repeat(150)}` }).success).toBe(false);
|
|
});
|
|
});
|
|
|
|
describe("plugin connector settings schemas", () => {
|
|
const method = (settingsSchema: Record<string, unknown>) => ({
|
|
key: "default", transport: "plugin", auth: "none", ownershipModes: ["customer"], whenToUse: "Use", guidanceMd: "Use", riskTier: "S1",
|
|
settingsSchema, tools: { kind: "static", list: [{ name: "lookup", risk: "read", parametersSchema: { type: "object" } }] },
|
|
});
|
|
const app = (settingsSchema: Record<string, unknown>) => ({ ...structuredClone(circleback), methods: [method(settingsSchema)] });
|
|
|
|
it("accepts a flat object of simple fields the board can render", () => {
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, apps: [app({ type: "object", properties: {
|
|
region: { type: "string", enum: ["us", "eu"], title: "Region" }, limit: { type: "integer", minimum: 1 }, verbose: { type: "boolean" },
|
|
}, required: ["region"], additionalProperties: false })] }).success).toBe(true);
|
|
});
|
|
|
|
it.each([
|
|
{ type: "object", properties: { nested: { type: "object", properties: {} } } },
|
|
{ type: "object", properties: { linked: { $ref: "#/definitions/x" } } },
|
|
{ type: "object", allOf: [] },
|
|
{ type: "array" },
|
|
{ type: "object", properties: { a: { type: "string" } }, required: ["missing"] },
|
|
{ type: "object", properties: { flag: { type: "boolean", enum: [true, false] } } },
|
|
{ type: "object", properties: { token: { type: "string", format: "secret-ref" } } },
|
|
])("rejects settings the board cannot render: %j", (settingsSchema) => {
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, apps: [app(settingsSchema)] }).success).toBe(false);
|
|
});
|
|
});
|
|
|
|
describe("plugin connector tool timeouts", () => {
|
|
const pluginMethod = (extra: { timeoutMs?: unknown; toolTimeoutMs?: unknown }) => ({
|
|
key: "default", transport: "plugin", auth: "none", ownershipModes: ["customer"], whenToUse: "Use", guidanceMd: "Use", riskTier: "S1",
|
|
...(extra.timeoutMs !== undefined ? { timeoutMs: extra.timeoutMs } : {}),
|
|
tools: { kind: "static", list: [{ name: "lookup", risk: "read", parametersSchema: { type: "object" },
|
|
...(extra.toolTimeoutMs !== undefined ? { timeoutMs: extra.toolTimeoutMs } : {}) }] },
|
|
});
|
|
const parse = (methodDef: Record<string, unknown>) =>
|
|
pluginManifestV1Schema.safeParse({ ...manifest, apps: [{ ...structuredClone(circleback), methods: [methodDef] }] }).success;
|
|
|
|
it("accepts method and tool timeouts from 1 s to the 60 s gateway ceiling", () => {
|
|
expect(parse(pluginMethod({ timeoutMs: 30_000, toolTimeoutMs: 45_000 }))).toBe(true);
|
|
expect(parse(pluginMethod({ timeoutMs: PLUGIN_CONNECTOR_TOOL_TIMEOUT_MIN_MS, toolTimeoutMs: PLUGIN_CONNECTOR_TOOL_TIMEOUT_MAX_MS }))).toBe(true);
|
|
});
|
|
|
|
it.each([
|
|
{ timeoutMs: PLUGIN_CONNECTOR_TOOL_TIMEOUT_MAX_MS + 1 },
|
|
{ timeoutMs: 999 },
|
|
{ timeoutMs: 1_500.5 },
|
|
{ timeoutMs: "30000" },
|
|
{ toolTimeoutMs: 120_000 },
|
|
{ toolTimeoutMs: 0 },
|
|
])("rejects a timeout outside the gateway's range: %j", (extra) => {
|
|
expect(parse(pluginMethod(extra))).toBe(false);
|
|
});
|
|
|
|
it("rejects timeoutMs on methods the plugin worker does not serve", () => {
|
|
expect(parse({ ...structuredClone(circleback.methods[0]!), timeoutMs: 30_000 })).toBe(false);
|
|
});
|
|
});
|
|
|
|
describe("plugin app slugs", () => {
|
|
it("namespaces by plugin key and reads the owner back from the slug", () => {
|
|
const slug = pluginAppSlug("example.meetings", "circleback");
|
|
expect(slug).not.toBe("circleback");
|
|
expect(slug).toMatch(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
|
|
expect(parsePluginAppSlug(slug)).toEqual({ pluginKey: "example.meetings", appSlug: "circleback" });
|
|
expect(isPluginAppSlug("circleback")).toBe(false);
|
|
expect(isPluginAppSlug(pluginAppSlug("other_plugin-2", "a-b"))).toBe(true);
|
|
expect(parsePluginAppSlug(`plugin-${"zz"}-x`)).toBeNull();
|
|
});
|
|
|
|
it("keeps a plugin copy of a built-in app separate from the built-in one", () => {
|
|
const definition = pluginAppDefinition("example.meetings", circleback);
|
|
expect(appDefinitionSchema.parse(definition)).toMatchObject({ plugin: { pluginKey: "example.meetings", appSlug: "circleback" } });
|
|
expect(getConnectableAppDefinition(definition.slug)).toBeNull();
|
|
|
|
setPluginAppDefinitions([definition]);
|
|
expect(getConnectableAppDefinition(definition.slug)).toEqual(definition);
|
|
expect(getAppStoreDefinition(definition.slug)).toEqual(definition);
|
|
expect(isConnectableAppSlug(definition.slug)).toBe(true);
|
|
expect(getAppDefinitionForApplicationKey(`app-gallery:${definition.slug}:00000000-0000-4000-8000-000000000000`)).toEqual(definition);
|
|
// The built-in app is never shadowed.
|
|
expect(getConnectableAppDefinition("circleback")).toBe(circleback);
|
|
|
|
setPluginAppDefinitions([]);
|
|
expect(getConnectableAppDefinition(definition.slug)).toBeNull();
|
|
});
|
|
});
|
|
|
|
describe("reviewed tool risk", () => {
|
|
const review = circleback.reviewedTools!;
|
|
|
|
it("classifies Circleback's reviewed tools from its definition", () => {
|
|
expect(reviewedToolRisk(review, { name: "SearchMeetings" })).toBe("read");
|
|
expect(reviewedToolRisk(review, { name: "DisplayMeetings" })).toBe("read");
|
|
// The generic classifier reads share and submit verbs as reads.
|
|
expect(reviewedToolRisk(review, { name: "ShareMeeting" })).toBe("write");
|
|
expect(reviewedToolRisk(review, { name: "SubmitFeedback" })).toBe("write");
|
|
expect(reviewedToolRisk(review, { name: "DeleteFolder" })).toBe("destructive");
|
|
expect(reviewedToolRisk(review, { name: "BrandNewTool" })).toBe("write");
|
|
});
|
|
|
|
it("lets provider hints raise risk but never lower it", () => {
|
|
expect(reviewedToolRisk(review, { name: "SearchMeetings", annotations: { readOnlyHint: false } })).toBe("write");
|
|
expect(reviewedToolRisk(review, { name: "SearchMeetings", annotations: { destructiveHint: true } })).toBe("destructive");
|
|
expect(reviewedToolRisk(review, { name: "DeleteTag", annotations: { readOnlyHint: true } })).toBe("destructive");
|
|
expect(reviewedToolRisk(review, { name: "ShareFolder", annotations: { readOnlyHint: true } })).toBe("write");
|
|
});
|
|
|
|
it("never lowers a destructive review because of a write hint", () => {
|
|
const strict = { ...review, unlisted: "destructive" as const };
|
|
expect(reviewedToolRisk(strict, { name: "BrandNewTool", annotations: { readOnlyHint: false } })).toBe("destructive");
|
|
expect(reviewedToolRisk(strict, { name: "BrandNewTool", annotations: { writeHint: true } })).toBe("destructive");
|
|
});
|
|
|
|
it("rejects a tool listed at two risk levels", () => {
|
|
expect(appDefinitionSchema.safeParse({ ...circleback, reviewedTools: { ...review, write: ["SearchMeetings"] } }).success).toBe(false);
|
|
});
|
|
});
|