mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 18:26:40 +01:00
Let plugin connectors declare their tool timeout (#22249)
## 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>
This commit is contained in:
1 parent
d4b7ae5532
commit
c600d69242
10 files changed
+312
-17
No files matched your search
@@ -519,6 +519,16 @@ apps?: AppDefinition[];
|
||||
It declares `tools` (`{ kind: "static", list }` with a `risk` per tool, or
|
||||
`{ kind: "dynamic" }` served by `ctx.connectors.listTools`) and optionally a
|
||||
`settingsSchema` for per-connection settings. Tool names use `[a-z0-9_]`.
|
||||
The method, or a single static tool, can declare `timeoutMs` (an integer
|
||||
from 1000 to 60000) for how long the gateway waits for a tool call; a
|
||||
tool's value overrides its method's. Without one the gateway waits 30000 ms
|
||||
for plugin-served tools. A caller's explicit timeout still wins, capped at
|
||||
the same 60 s ceiling. An "ask first" call that a person has approved runs
|
||||
with the gateway's fixed 60 s approved-execution budget instead of the
|
||||
declared value. The gateway enforces the deadline and gives the worker call
|
||||
1 s more, so callers always see the gateway's `tool_timeout`. Worker calls
|
||||
cannot be cancelled, so a timed-out call may still finish in the worker;
|
||||
write tools should be idempotent on their arguments so a retry is safe.
|
||||
Authentication is `none` or `api_key`. The gateway keeps every decision
|
||||
(grant, policy, approval, rate limit, audit) and calls the worker's
|
||||
`executeTool` with `runContext.connection` (`id`, `appSlug`, `methodKey`,
|
||||
|
||||
@@ -123,8 +123,9 @@ manifest `apps` (requires `connectors.provide`) with a method that uses
|
||||
|
||||
```ts
|
||||
// manifest: apps: [{ slug: "records", ..., methods: [{ key: "default", transport: "plugin",
|
||||
// auth: "none", settingsSchema: {...}, tools: { kind: "static", list: [
|
||||
// { name: "lookup_record", risk: "read", parametersSchema: {...} }] } }] }]
|
||||
// auth: "none", settingsSchema: {...}, timeoutMs: 30000, tools: { kind: "static", list: [
|
||||
// { name: "lookup_record", risk: "read", parametersSchema: {...} },
|
||||
// { name: "build_report", risk: "read", parametersSchema: {...}, timeoutMs: 60000 }] } }] }]
|
||||
ctx.connectors.register("records", "lookup_record", async (params, runCtx) => {
|
||||
// runCtx.connection: { id, appSlug, methodKey, grantId, settings, credential? }
|
||||
return { content: `Record for ${runCtx.connection.settings.region}` };
|
||||
@@ -143,6 +144,13 @@ methods) for each call only, and passes the run context from the gateway
|
||||
session; tool arguments cannot change it. Every static tool needs a
|
||||
registered handler before `setup` returns, or the worker fails to start.
|
||||
|
||||
The gateway waits 30 s for a plugin connector tool by default. If your
|
||||
backend legitimately takes longer, declare `timeoutMs` (1000–60000 ms) on the
|
||||
method, or on a single static tool to override the method's value. Values
|
||||
outside that range fail manifest validation; 60 s is the gateway's ceiling.
|
||||
A call that a person approved under an "ask first" policy always gets the
|
||||
gateway's fixed 60 s approved-execution budget, whatever the tool declares.
|
||||
|
||||
Top-level `tools` with `ctx.tools.register` stay supported as legacy. The host
|
||||
offers them as one implicit connector named after the plugin: installations
|
||||
that existed before connectors keep them for every agent, and new
|
||||
|
||||
@@ -373,6 +373,7 @@ export {
|
||||
} from "./self-serve-mcp-research.js";
|
||||
export * from "./validators/status-card.js";
|
||||
export { appDefinitionSchema, appDefinitionsSchema, connectionMethodDefSchema, reviewedToolsSchema, pluginMethodToolsSchema, PLUGIN_CONNECTOR_TOOL_NAME } from "./validators/app-definition.js";
|
||||
export { PLUGIN_CONNECTOR_TOOL_DEFAULT_TIMEOUT_MS, PLUGIN_CONNECTOR_TOOL_TIMEOUT_MAX_MS, PLUGIN_CONNECTOR_TOOL_TIMEOUT_MIN_MS } from "./types/app-definition.js";
|
||||
export * from "./types/chat-channels.js";
|
||||
export * from "./types/chat-github.js";
|
||||
export * from "./validators/chat-github.js";
|
||||
|
||||
@@ -14,7 +14,7 @@ import {
|
||||
pluginAppSlug,
|
||||
reviewedToolRisk,
|
||||
} from "./plugin-apps.js";
|
||||
import type { AppDefinition } from "./types/app-definition.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";
|
||||
|
||||
@@ -134,6 +134,37 @@ describe("plugin connector settings schemas", () => {
|
||||
});
|
||||
});
|
||||
|
||||
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");
|
||||
|
||||
@@ -4,10 +4,13 @@ export type OAuthRedirectConstraints = "https-or-loopback-http";
|
||||
export const CONNECTION_CREDENTIAL_MINTERS = ["aws_mcp"] as const;
|
||||
export type ConnectionCredentialMinter = (typeof CONNECTION_CREDENTIAL_MINTERS)[number];
|
||||
export interface FieldDef { key:string; label:string; type:"text"|"password"|"textarea"|"datetime"|"select"|"checkbox"; required?:boolean; advanced?:boolean; hidden?:boolean; placeholder?:string; helperMd?:string; secret?:boolean; prefix?:string; defaultValue?:string|boolean; validation?:{pattern?:string;maxLength?:number}; options?:Array<{value:string;label:string}>; transport?:{location:"query"|"header";name:string;format?:"string"|"csv"|"boolean";omitFalse?:boolean} }
|
||||
export const PLUGIN_CONNECTOR_TOOL_TIMEOUT_MIN_MS = 1_000;
|
||||
export const PLUGIN_CONNECTOR_TOOL_TIMEOUT_MAX_MS = 60_000;
|
||||
export const PLUGIN_CONNECTOR_TOOL_DEFAULT_TIMEOUT_MS = 30_000;
|
||||
/** One tool a plugin worker serves for a `transport: "plugin"` method. */
|
||||
export interface PluginConnectorToolDef { name:string; displayName?:string; description?:string; risk:"read"|"write"|"destructive"; parametersSchema:Record<string,unknown> }
|
||||
export interface PluginConnectorToolDef { name:string; displayName?:string; description?:string; risk:"read"|"write"|"destructive"; parametersSchema:Record<string,unknown>; timeoutMs?:number }
|
||||
export type PluginConnectorTools = { kind:"static"; list:PluginConnectorToolDef[] } | { kind:"dynamic" };
|
||||
export interface ConnectionMethodDef { ai?: import("../ai-connections.js").AiConnectionMetadata; key:string; label?:string; purpose?:ToolConnectionPurpose; provider?:"slack"|"github"|"discord"|"microsoft-teams"|"telegram"|"agentmail"|"imessage-photon"|"speko"; transport:ToolConnectionTransport; settingsSchema?:Record<string,unknown>; tools?:PluginConnectorTools; auth:"oauth"|"api_key"|"none"; oauthStrategy?:"paperclip_cloud_connector"|"paperclip_id_connector"; connectorProfile?:string; oauthClientSecretRequired?:boolean; oauthClientRegistration?:"dcr"; capabilityProfile?:{key:string;label:string;description?:string}; grantKinds?:ConnectionGrantKind[]; ownershipModes:ToolConnectionOwnership[]; whenToUse:string; defaults?:{serverUrl?:string;serverUrlTemplate?:string;discoveryUrl?:string|null;serviceHost?:string;templateKey?:string;authorizationEndpoint?:string;tokenEndpoint?:string;metadataUrl?:string;scopesHint?:string[];oauthAuthorizationParams?:{access_type?:"offline";prompt?:"consent"};toolArgumentDefaults?:Record<string,unknown>;mcpSessionRequired?:boolean}; tenantFields?:FieldDef[]; extensionFields?:FieldDef[]; configRequirements?:{atLeastOneOf?:string[]}; credentialFields?:FieldDef[]; keyPlacement?:{location:"header"|"query"|"body_json"|"env";name:string;prefix?:string|null}; /** The control plane mints this method's Authorization header at call time; stored credential fields are minter inputs, never headers. */ credentialMinter?:ConnectionCredentialMinter; credentialSources?:{vercelConnect?:{services:string[];principalModes:VercelConnectPrincipalMode[];scopes:string[];header:{name:string;prefix?:string|null}}}; guidanceMd:string; consoleLinks?:{register?:string;keys?:string;settings?:string;docs?:string}; warnings?:string[]; variants?:Array<{key:string;label:string;whenToUse:string;tenantFields?:FieldDef[]}>; riskTier:"S1"|"S2"|"S3"|"S4"; requiredResourceFilters?:string[] }
|
||||
export interface ConnectionMethodDef { ai?: import("../ai-connections.js").AiConnectionMetadata; key:string; label?:string; purpose?:ToolConnectionPurpose; provider?:"slack"|"github"|"discord"|"microsoft-teams"|"telegram"|"agentmail"|"imessage-photon"|"speko"; transport:ToolConnectionTransport; settingsSchema?:Record<string,unknown>; tools?:PluginConnectorTools; timeoutMs?:number; auth:"oauth"|"api_key"|"none"; oauthStrategy?:"paperclip_cloud_connector"|"paperclip_id_connector"; connectorProfile?:string; oauthClientSecretRequired?:boolean; oauthClientRegistration?:"dcr"; capabilityProfile?:{key:string;label:string;description?:string}; grantKinds?:ConnectionGrantKind[]; ownershipModes:ToolConnectionOwnership[]; whenToUse:string; defaults?:{serverUrl?:string;serverUrlTemplate?:string;discoveryUrl?:string|null;serviceHost?:string;templateKey?:string;authorizationEndpoint?:string;tokenEndpoint?:string;metadataUrl?:string;scopesHint?:string[];oauthAuthorizationParams?:{access_type?:"offline";prompt?:"consent"};toolArgumentDefaults?:Record<string,unknown>;mcpSessionRequired?:boolean}; tenantFields?:FieldDef[]; extensionFields?:FieldDef[]; configRequirements?:{atLeastOneOf?:string[]}; credentialFields?:FieldDef[]; keyPlacement?:{location:"header"|"query"|"body_json"|"env";name:string;prefix?:string|null}; /** The control plane mints this method's Authorization header at call time; stored credential fields are minter inputs, never headers. */ credentialMinter?:ConnectionCredentialMinter; credentialSources?:{vercelConnect?:{services:string[];principalModes:VercelConnectPrincipalMode[];scopes:string[];header:{name:string;prefix?:string|null}}}; guidanceMd:string; consoleLinks?:{register?:string;keys?:string;settings?:string;docs?:string}; warnings?:string[]; variants?:Array<{key:string;label:string;whenToUse:string;tenantFields?:FieldDef[]}>; riskTier:"S1"|"S2"|"S3"|"S4"; requiredResourceFilters?:string[] }
|
||||
export interface AppReviewedTools { reviewedAt:string; sourceUrl?:string; read?:string[]; write?:string[]; destructive?:string[]; unlisted?:"read"|"write"|"destructive"; quarantineNewEntries?:boolean }
|
||||
/** Present only on connectors a plugin provides; `slug` is then namespaced by plugin key. */
|
||||
export interface AppPluginSource { pluginKey:string; appSlug:string; /** The implicit connector of legacy top-level manifest `tools`. */ legacyTools?:true }
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import { z } from "zod";
|
||||
import { jsonSchemaSchema } from "./json-schema.js";
|
||||
import { CONNECTION_CREDENTIAL_MINTERS } from "../types/app-definition.js";
|
||||
import { CONNECTION_CREDENTIAL_MINTERS, PLUGIN_CONNECTOR_TOOL_TIMEOUT_MAX_MS, PLUGIN_CONNECTOR_TOOL_TIMEOUT_MIN_MS } from "../types/app-definition.js";
|
||||
import { INSTANCE_FEATURE_KEYS } from "../feature-catalog.js";
|
||||
import { connectionInstructionTemplateSchema } from "../connection-instructions.js";
|
||||
import { AI_CONNECTION_CAPABILITIES, aiConnectionMetadataSchema } from "../ai-connections.js";
|
||||
@@ -12,12 +12,14 @@ const appBrandAssetUrlSchema=z.string().refine((value)=>{
|
||||
const field=z.object({key:z.string().min(1),label:z.string().min(1),type:z.enum(["text","password","textarea","datetime","select","checkbox"]),required:z.boolean().optional(),advanced:z.boolean().optional(),hidden:z.boolean().optional(),placeholder:z.string().optional(),helperMd:z.string().optional(),secret:z.boolean().optional(),prefix:z.string().optional(),defaultValue:z.union([z.string(),z.boolean()]).optional(),validation:z.object({pattern:z.string().optional(),maxLength:z.number().int().positive().optional()}).optional(),options:z.array(z.object({value:z.string(),label:z.string()})).optional(),transport:z.object({location:z.enum(["query","header"]),name:z.string().min(1),format:z.enum(["string","csv","boolean"]).optional(),omitFalse:z.boolean().optional()}).optional()}).superRefine((v,c)=>{if(v.required&&v.type!=="checkbox"&&!v.placeholder)c.addIssue({code:"custom",message:"Required fields need placeholders",path:["placeholder"]});if(v.type==="select"&&(!v.options||v.options.length===0))c.addIssue({code:"custom",message:"Select fields need options",path:["options"]});if(v.hidden&&v.defaultValue===undefined)c.addIssue({code:"custom",message:"Hidden fields need defaults",path:["defaultValue"]})});
|
||||
/** Tool names a plugin connector serves: lowercase letters, digits and underscores. */
|
||||
export const PLUGIN_CONNECTOR_TOOL_NAME = /^[a-z0-9_]{1,64}$/;
|
||||
const pluginToolTimeoutMsSchema=z.number().int().min(PLUGIN_CONNECTOR_TOOL_TIMEOUT_MIN_MS).max(PLUGIN_CONNECTOR_TOOL_TIMEOUT_MAX_MS);
|
||||
const pluginStaticToolSchema=z.object({
|
||||
name:z.string().regex(PLUGIN_CONNECTOR_TOOL_NAME,"Tool names may contain only a-z, 0-9 and _"),
|
||||
displayName:z.string().min(1).max(200).optional(),
|
||||
description:z.string().min(1).max(4000).optional(),
|
||||
risk:z.enum(["read","write","destructive"]),
|
||||
parametersSchema:jsonSchemaSchema,
|
||||
timeoutMs:pluginToolTimeoutMsSchema.optional(),
|
||||
}).strict();
|
||||
/**
|
||||
* Tools of a method served by a plugin worker (`transport: "plugin"`). Static
|
||||
@@ -60,7 +62,7 @@ export function isSupportedPluginSettingsSchema(schema:Record<string,unknown>):b
|
||||
return typeof record.type==="string"&&SETTINGS_FIELD_TYPES.has(record.type)&&Object.keys(record).every((key)=>SETTINGS_FIELD_KEYS.has(key));
|
||||
});
|
||||
}
|
||||
export const connectionMethodDefSchema=z.object({key:z.string().min(1),label:z.string().min(1).optional(),purpose:z.union([toolConnectionPurposeSchema,z.literal("ai")]).optional(),provider:z.enum(["slack","github","discord","microsoft-teams","telegram","speko","agentmail","imessage-photon"]).optional(),transport:z.union([toolConnectionTransportSchema,z.literal("runtime_auth"),z.literal("plugin")]),settingsSchema:jsonSchemaSchema.optional(),tools:pluginMethodToolsSchema.optional(),ai:aiConnectionMetadataSchema.optional(),auth:z.enum(["oauth","api_key","none"]),oauthStrategy:z.enum(["paperclip_cloud_connector","paperclip_id_connector"]).optional(),connectorProfile:z.string().regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/).optional(),oauthClientSecretRequired:z.boolean().optional(),oauthClientRegistration:z.literal("dcr").optional(),capabilityProfile:z.object({key:z.string().min(1),label:z.string().min(1),description:z.string().min(1).optional()}).optional(),grantKinds:z.array(connectionGrantKindSchema).min(1).optional(),ownershipModes:z.array(toolConnectionOwnershipSchema).min(1),whenToUse:z.string().min(1),defaults:z.object({serverUrl:z.string().url().optional(),serverUrlTemplate:z.string().regex(/^https:\/\//).optional(),discoveryUrl:z.string().url().nullable().optional(),serviceHost:z.string().optional(),templateKey:z.string().optional(),authorizationEndpoint:z.string().url().optional(),tokenEndpoint:z.string().url().optional(),metadataUrl:z.string().url().optional(),scopesHint:z.array(z.string()).optional(),oauthAuthorizationParams:z.object({access_type:z.literal("offline").optional(),prompt:z.literal("consent").optional()}).optional(),toolArgumentDefaults:z.record(z.string(),z.unknown()).optional(),mcpSessionRequired:z.boolean().optional()}).optional(),tenantFields:z.array(field).optional(),extensionFields:z.array(field).optional(),configRequirements:z.object({atLeastOneOf:z.array(z.string().min(1)).min(1).optional()}).optional(),credentialFields:z.array(field).optional(),keyPlacement:z.object({location:z.enum(["header","query","body_json","env"]),name:z.string().min(1),prefix:z.string().nullable().optional()}).optional(),credentialMinter:z.enum(CONNECTION_CREDENTIAL_MINTERS).optional(),credentialSources:z.object({vercelConnect:z.object({services:z.array(z.string().min(1)).min(1),principalModes:z.array(z.enum(["app","user"])).min(1),scopes:z.array(z.string().min(1)).min(1),header:z.object({name:z.string().min(1),prefix:z.string().nullable().optional()})}).optional()}).optional(),guidanceMd:z.string().min(1),consoleLinks:z.object({register:z.string().url().optional(),keys:z.string().url().optional(),settings:z.string().url().optional(),docs:z.string().url().optional()}).optional(),warnings:z.array(z.string()).optional(),variants:z.array(z.object({key:z.string(),label:z.string(),whenToUse:z.string(),tenantFields:z.array(field).optional()})).optional(),riskTier:z.enum(["S1","S2","S3","S4"]),requiredResourceFilters:z.array(z.string()).optional()}).superRefine((v,c)=>{if((v.transport==="runtime_auth")!==Boolean(v.ai))c.addIssue({code:"custom",message:"Runtime authentication requires AI metadata and AI metadata requires runtime_auth",path:["ai"]});if(v.ai&&!AI_CONNECTION_CAPABILITIES[v.ai.provider].methods[v.ai.method])c.addIssue({code:"custom",message:"Unsupported AI sign-in method",path:["ai","method"]});if(v.ai&&v.auth!==(v.ai.method==="subscription"?"oauth":"api_key"))c.addIssue({code:"custom",message:"AI sign-in method must match authentication",path:["auth"]});if(v.oauthClientRegistration&&(v.auth!=="oauth"||v.transport!=="mcp_remote"||!v.ownershipModes.includes("dcr")))c.addIssue({code:"custom",message:"DCR client registration requires a remote MCP OAuth method with DCR ownership",path:["oauthClientRegistration"]});if(v.defaults?.mcpSessionRequired&&v.transport!=="mcp_remote")c.addIssue({code:"custom",message:"MCP session initialization preferences require remote MCP transport",path:["defaults","mcpSessionRequired"]});const purpose=v.purpose??"tool";if((purpose==="ai")!==(v.transport==="runtime_auth"))c.addIssue({code:"custom",message:"AI methods require runtime_auth and runtime_auth requires AI purpose",path:["purpose"]});if(["chat_sdk","voice"].includes(v.transport)&&purpose!=="channel")c.addIssue({code:"custom",message:"Chat SDK methods must be channel connections",path:["purpose"]});if(purpose==="channel"&&!["chat_sdk","voice"].includes(v.transport)&&!(v.provider==="agentmail"&&v.transport==="rest_api"))c.addIssue({code:"custom",message:"Channel connections must use the Chat SDK transport",path:["transport"]});if(purpose==="channel"&&((v.provider==="speko")!==(v.transport==="voice")))c.addIssue({code:"custom",message:"Speko channels require the voice transport",path:["transport"]});if(purpose==="channel"&&!v.provider)c.addIssue({code:"custom",message:"Channel connections require a chat provider",path:["provider"]});if((v.transport==="plugin")!==Boolean(v.tools))c.addIssue({code:"custom",message:"Plugin-servLine truncated
|
||||
export const connectionMethodDefSchema=z.object({key:z.string().min(1),label:z.string().min(1).optional(),purpose:z.union([toolConnectionPurposeSchema,z.literal("ai")]).optional(),provider:z.enum(["slack","github","discord","microsoft-teams","telegram","speko","agentmail","imessage-photon"]).optional(),transport:z.union([toolConnectionTransportSchema,z.literal("runtime_auth"),z.literal("plugin")]),settingsSchema:jsonSchemaSchema.optional(),tools:pluginMethodToolsSchema.optional(),timeoutMs:pluginToolTimeoutMsSchema.optional(),ai:aiConnectionMetadataSchema.optional(),auth:z.enum(["oauth","api_key","none"]),oauthStrategy:z.enum(["paperclip_cloud_connector","paperclip_id_connector"]).optional(),connectorProfile:z.string().regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/).optional(),oauthClientSecretRequired:z.boolean().optional(),oauthClientRegistration:z.literal("dcr").optional(),capabilityProfile:z.object({key:z.string().min(1),label:z.string().min(1),description:z.string().min(1).optional()}).optional(),grantKinds:z.array(connectionGrantKindSchema).min(1).optional(),ownershipModes:z.array(toolConnectionOwnershipSchema).min(1),whenToUse:z.string().min(1),defaults:z.object({serverUrl:z.string().url().optional(),serverUrlTemplate:z.string().regex(/^https:\/\//).optional(),discoveryUrl:z.string().url().nullable().optional(),serviceHost:z.string().optional(),templateKey:z.string().optional(),authorizationEndpoint:z.string().url().optional(),tokenEndpoint:z.string().url().optional(),metadataUrl:z.string().url().optional(),scopesHint:z.array(z.string()).optional(),oauthAuthorizationParams:z.object({access_type:z.literal("offline").optional(),prompt:z.literal("consent").optional()}).optional(),toolArgumentDefaults:z.record(z.string(),z.unknown()).optional(),mcpSessionRequired:z.boolean().optional()}).optional(),tenantFields:z.array(field).optional(),extensionFields:z.array(field).optional(),configRequirements:z.object({atLeastOneOf:z.array(z.string().min(1)).min(1).optional()}).optional(),credentialFields:z.array(field).optional(),keyPlacement:z.object({location:z.enum(["header","query","body_json","env"]),name:z.string().min(1),prefix:z.string().nullable().optional()}).optional(),credentialMinter:z.enum(CONNECTION_CREDENTIAL_MINTERS).optional(),credentialSources:z.object({vercelConnect:z.object({services:z.array(z.string().min(1)).min(1),principalModes:z.array(z.enum(["app","user"])).min(1),scopes:z.array(z.string().min(1)).min(1),header:z.object({name:z.string().min(1),prefix:z.string().nullable().optional()})}).optional()}).optional(),guidanceMd:z.string().min(1),consoleLinks:z.object({register:z.string().url().optional(),keys:z.string().url().optional(),settings:z.string().url().optional(),docs:z.string().url().optional()}).optional(),warnings:z.array(z.string()).optional(),variants:z.array(z.object({key:z.string(),label:z.string(),whenToUse:z.string(),tenantFields:z.array(field).optional()})).optional(),riskTier:z.enum(["S1","S2","S3","S4"]),requiredResourceFilters:z.array(z.string()).optional()}).superRefine((v,c)=>{if((v.transport==="runtime_auth")!==Boolean(v.ai))c.addIssue({code:"custom",message:"Runtime authentication requires AI metadata and AI metadata requires runtime_auth",path:["ai"]});if(v.ai&&!AI_CONNECTION_CAPABILITIES[v.ai.provider].methods[v.ai.method])c.addIssue({code:"custom",message:"Unsupported AI sign-in method",path:["ai","method"]});if(v.ai&&v.auth!==(v.ai.method==="subscription"?"oauth":"api_key"))c.addIssue({code:"custom",message:"AI sign-in method must match authentication",path:["auth"]});if(v.oauthClientRegistration&&(v.auth!=="oauth"||v.transport!=="mcp_remote"||!v.ownershipModes.includes("dcr")))c.addIssue({code:"custom",message:"DCR client registration requires a remote MCP OAuth method with DCR ownership",path:["oauthClientRegistration"]});if(v.defaults?.mcpSessionRequired&&v.transport!=="mcp_remote")c.addIssue({code:"custom",message:"MCP session initialization preferences require remote MCP transport",path:["defaults","mcpSessionRequired"]});const purpose=v.purpose??"tool";if((purpose==="ai")!==(v.transport==="runtime_auth"))c.addIssue({code:"custom",message:"AI methods require runtime_auth and runtime_auth requires AI purpose",path:["purpose"]});if(["chat_sdk","voice"].includes(v.transport)&&purpose!=="channel")c.addIssue({code:"custom",message:"Chat SDK methods must be channel connections",path:["purpose"]});if(purpose==="channel"&&!["chat_sdk","voice"].includes(v.transport)&&!(v.provider==="agentmail"&&v.transport==="rest_api"))c.addIssue({code:"custom",message:"Channel connections must use the Chat SDK transport",path:["transport"]});if(purpose==="channel"&&((v.provider==="speko")!==(v.transport==="voice")))c.addIssue({code:"custom",message:"Speko channels require the voice transport",path:["transport"]});if(purpose==="channel"&&!v.provider)c.addIssue({code:"custom",message:"Channel connections require a chat provider",path:["provider"]});if((v.transport==="plugin")!==Boolean(v.tools)Line truncated
|
||||
const reviewedToolNameListSchema=z.array(z.string().min(1).max(200)).max(1000);
|
||||
/**
|
||||
* A connector's reviewed tool risk, declared as data so any connector (core or
|
||||
|
||||
@@ -0,0 +1,206 @@
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { mkdtemp, rm } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
agents, companies, companyMemberships, createDb, heartbeatRuns, issues, plugins, pluginConnectorLegacyAccess,
|
||||
toolProfileBindings, toolProfileEntries, toolProfiles,
|
||||
} from "@paperclipai/db";
|
||||
import { pluginAppSlug, pluginManifestV1Schema, type PaperclipPluginManifestV1 } from "@paperclipai/shared";
|
||||
import { toolAccessService } from "../services/tool-access.js";
|
||||
import { createToolGatewayService } from "../services/tool-gateway.js";
|
||||
import { setPluginConnectorWorkers } from "../services/plugin-connector-runtime.js";
|
||||
import { completeLegacyPluginToolAccess } from "../services/plugin-connector-legacy-access.js";
|
||||
import type { PluginWorkerManager } from "../services/plugin-worker-manager.js";
|
||||
import type { PluginToolDispatcher } from "../services/plugin-tool-dispatcher.js";
|
||||
import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
|
||||
|
||||
const actor = { actorType: "user" as const, actorId: "plugin-timeout-admin" };
|
||||
const PLUGIN_KEY = "example.slow";
|
||||
const APP = "reports";
|
||||
const SLUG = pluginAppSlug(PLUGIN_KEY, APP);
|
||||
const BACKEND_DELAY_MS = 12_000;
|
||||
|
||||
function slowManifest(method: { timeoutMs?: number; quickTimeoutMs?: number } = {}) {
|
||||
return {
|
||||
id: PLUGIN_KEY, apiVersion: 1, version: "1.0.0", displayName: "Slow reports", description: "Slow backend",
|
||||
author: "Tests", categories: ["connector"], capabilities: ["connectors.provide"], entrypoints: { worker: "worker.js" },
|
||||
apps: [{
|
||||
schemaVersion: 1, slug: APP, name: "Reports", description: "Build reports", categories: ["data"],
|
||||
branding: { logoUrl: "/brands/apps/api-key-generic.svg" }, urlPatterns: [],
|
||||
methods: [{
|
||||
key: "none", transport: "plugin", auth: "none", ownershipModes: ["customer"], whenToUse: "No sign-in.",
|
||||
guidanceMd: "Nothing to set up.", riskTier: "S1",
|
||||
...(method.timeoutMs !== undefined ? { timeoutMs: method.timeoutMs } : {}),
|
||||
tools: { kind: "static", list: [
|
||||
{ name: "build_report", description: "Build a report.", risk: "read", parametersSchema: { type: "object" } },
|
||||
{ name: "quick_check", description: "Check quickly.", risk: "read", parametersSchema: { type: "object" },
|
||||
...(method.quickTimeoutMs !== undefined ? { timeoutMs: method.quickTimeoutMs } : {}) },
|
||||
] },
|
||||
}],
|
||||
}],
|
||||
};
|
||||
}
|
||||
|
||||
function slowWorkers(delayMs: number) {
|
||||
const calls: Array<{ method: string; params: any; timeoutMs?: number }> = [];
|
||||
const manager = {
|
||||
isRunning: () => true,
|
||||
getWorker: () => ({ status: "running" }),
|
||||
call: vi.fn((_id: string, method: string, params: any, timeoutMs?: number) => {
|
||||
calls.push({ method, params: structuredClone(params), timeoutMs });
|
||||
if (method !== "executeTool") return Promise.reject(new Error(`unexpected ${method}`));
|
||||
return new Promise((resolve) => setTimeout(() => resolve({ content: `ran ${params.toolName}` }), delayMs));
|
||||
}),
|
||||
} as unknown as PluginWorkerManager;
|
||||
return { manager, calls };
|
||||
}
|
||||
|
||||
const support = await getEmbeddedPostgresTestSupport();
|
||||
(support.supported ? describe : describe.skip)("plugin connector tool timeouts", () => {
|
||||
let db: ReturnType<typeof createDb>;
|
||||
let temp: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
|
||||
let keyDir: string;
|
||||
beforeAll(async () => {
|
||||
keyDir = await mkdtemp(join(tmpdir(), "plugin-timeout-secrets-"));
|
||||
vi.stubEnv("PAPERCLIP_SECRETS_MASTER_KEY_FILE", join(keyDir, "key"));
|
||||
temp = await startEmbeddedPostgresTestDatabase("paperclip-plugin-timeout-");
|
||||
db = createDb(temp.connectionString);
|
||||
}, 60_000);
|
||||
afterAll(async () => { await temp?.cleanup(); vi.unstubAllEnvs(); if (keyDir) await rm(keyDir, { recursive: true, force: true }); });
|
||||
afterEach(async () => { vi.useRealTimers(); setPluginConnectorWorkers(null); await db.delete(plugins); });
|
||||
|
||||
async function setup(manifestJson: PaperclipPluginManifestV1, options: { delayMs?: number; dispatcher?: PluginToolDispatcher } = {}) {
|
||||
const [company] = await db.insert(companies).values({ name: "Plugin timeouts", issuePrefix: `PO${randomUUID().slice(0, 6)}` }).returning();
|
||||
await db.insert(companyMemberships).values({ companyId: company.id, principalType: "user", principalId: actor.actorId, status: "active", membershipRole: "admin" });
|
||||
const [agent] = await db.insert(agents).values({ companyId: company.id, name: "Reporter", role: "engineer", adapterType: "process" }).returning();
|
||||
await db.insert(plugins).values({ pluginKey: manifestJson.id, packageName: `@test/${manifestJson.id}`, version: "1.0.0", manifestJson, status: "ready" });
|
||||
const workers = slowWorkers(options.delayMs ?? BACKEND_DELAY_MS);
|
||||
setPluginConnectorWorkers(workers.manager);
|
||||
const service = toolAccessService(db);
|
||||
const gateway = createToolGatewayService(db, {
|
||||
toolActionSigningSecret: "plugin-timeout-signing",
|
||||
...(options.dispatcher ? { pluginToolDispatcher: options.dispatcher } : {}),
|
||||
});
|
||||
const [issue] = await db.insert(issues).values({ companyId: company.id, title: "Report", assigneeAgentId: agent.id }).returning();
|
||||
const [run] = await db.insert(heartbeatRuns).values({ companyId: company.id, agentId: agent.id, issueId: issue.id, scopeKind: "issue",
|
||||
invocationSource: "on_demand", status: "running", responsibleUserId: actor.actorId, contextSnapshot: { issueId: issue.id } }).returning();
|
||||
const session = await gateway.createSession({ companyId: company.id, agentId: agent.id, runId: run.id, issueId: issue.id });
|
||||
return { company, agent, workers, service, gateway, token: session.token };
|
||||
}
|
||||
|
||||
async function connectReports(f: Awaited<ReturnType<typeof setup>>) {
|
||||
const connected = await f.service.connectGalleryApp(f.company.id, { galleryKey: SLUG, connectionMethodKey: "none" }, actor);
|
||||
await f.service.finishGalleryAppConnection(f.company.id, connected.connectionId, {
|
||||
enabledCatalogEntryIds: connected.catalog.map(entry => entry.id), askFirstCatalogEntryIds: [], access: { agentIds: [f.agent.id] } }, actor);
|
||||
const tools = (await f.gateway.listToolsForSession(f.token)).filter(tool => tool.providerType === "paperclip_plugin_connection");
|
||||
const tool = (name: string) => tools.find(candidate => candidate.upstreamToolName === name)!;
|
||||
return { connectionId: connected.connectionId, buildReport: tool("build_report"), quickCheck: tool("quick_check") };
|
||||
}
|
||||
|
||||
async function settleAfter<T>(f: { workers: { calls: unknown[] } }, start: () => Promise<T>, advanceMs: number) {
|
||||
const before = f.workers.calls.length;
|
||||
vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"], shouldAdvanceTime: true });
|
||||
const pending = start().then((value) => ({ value }), (error: unknown) => ({ error: error as { status?: number; reasonCode?: string } }));
|
||||
await vi.waitFor(() => expect(f.workers.calls.length).toBe(before + 1), { timeout: 20_000, interval: 5 });
|
||||
await vi.advanceTimersByTimeAsync(advanceMs);
|
||||
const outcome = await pending;
|
||||
vi.useRealTimers();
|
||||
return outcome;
|
||||
}
|
||||
|
||||
const timedOut = { error: expect.objectContaining({ status: 504, reasonCode: "tool_timeout" }) };
|
||||
|
||||
it("waits for the method's declared timeoutMs on session and test calls", async () => {
|
||||
const f = await setup(pluginManifestV1Schema.parse(slowManifest({ timeoutMs: 30_000 })) as PaperclipPluginManifestV1);
|
||||
const { connectionId, buildReport } = await connectReports(f);
|
||||
|
||||
const call = await settleAfter(f, () => f.gateway.executeTool({ sessionToken: f.token, tool: buildReport.name, parameters: {}, idempotencyKey: randomUUID() }), BACKEND_DELAY_MS);
|
||||
expect(call).toMatchObject({ value: { status: "completed" } });
|
||||
expect(f.workers.calls.at(-1)).toMatchObject({ method: "executeTool", timeoutMs: 31_000 });
|
||||
|
||||
const tested = await settleAfter(f, () => f.gateway.executeTestCall({ companyId: f.company.id, agentId: f.agent.id, userId: actor.actorId,
|
||||
connectionId, toolName: buildReport.name, parameters: {} }), BACKEND_DELAY_MS);
|
||||
expect(tested).toMatchObject({ value: { decision: "allowed" } });
|
||||
expect(tested).not.toHaveProperty("value.error");
|
||||
});
|
||||
|
||||
it("times out at a tool's declared timeoutMs when the backend is slower", async () => {
|
||||
const f = await setup(pluginManifestV1Schema.parse(slowManifest({ timeoutMs: 30_000, quickTimeoutMs: 5_000 })) as PaperclipPluginManifestV1);
|
||||
const { quickCheck } = await connectReports(f);
|
||||
const call = await settleAfter(f, () => f.gateway.executeTool({ sessionToken: f.token, tool: quickCheck.name, parameters: {}, idempotencyKey: randomUUID() }), 5_000);
|
||||
expect(call).toMatchObject(timedOut);
|
||||
expect(f.workers.calls.at(-1)).toMatchObject({ timeoutMs: 6_000 });
|
||||
});
|
||||
|
||||
it("prefers an explicit caller timeout below the declared value", async () => {
|
||||
const f = await setup(pluginManifestV1Schema.parse(slowManifest({ timeoutMs: 30_000 })) as PaperclipPluginManifestV1);
|
||||
const { buildReport } = await connectReports(f);
|
||||
const call = await settleAfter(f, () => f.gateway.executeTool({ sessionToken: f.token, tool: buildReport.name, parameters: {},
|
||||
timeoutMs: 5_000, idempotencyKey: randomUUID() }), 5_000);
|
||||
expect(call).toMatchObject(timedOut);
|
||||
expect(f.workers.calls.at(-1)).toMatchObject({ timeoutMs: 6_000 });
|
||||
});
|
||||
|
||||
it("waits 30 s for plugin tools that declare no timeout", async () => {
|
||||
const f = await setup(pluginManifestV1Schema.parse(slowManifest()) as PaperclipPluginManifestV1);
|
||||
const { buildReport } = await connectReports(f);
|
||||
const call = await settleAfter(f, () => f.gateway.executeTool({ sessionToken: f.token, tool: buildReport.name, parameters: {}, idempotencyKey: randomUUID() }), BACKEND_DELAY_MS);
|
||||
expect(call).toMatchObject({ value: { status: "completed" } });
|
||||
expect(f.workers.calls.at(-1)).toMatchObject({ timeoutMs: 31_000 });
|
||||
|
||||
setPluginConnectorWorkers(null);
|
||||
const slower = slowWorkers(45_000);
|
||||
f.workers.calls.length = 0;
|
||||
setPluginConnectorWorkers(slower.manager);
|
||||
const late = await settleAfter({ workers: slower }, () => f.gateway.executeTool({ sessionToken: f.token, tool: buildReport.name, parameters: {}, idempotencyKey: randomUUID() }), 30_000);
|
||||
expect(late).toMatchObject(timedOut);
|
||||
});
|
||||
|
||||
it("rejects declared timeouts outside 1-60 s and clamps caller timeouts to the 60 s ceiling", async () => {
|
||||
expect(pluginManifestV1Schema.safeParse(slowManifest({ timeoutMs: 60_000 })).success).toBe(true);
|
||||
for (const bad of [{ timeoutMs: 60_001 }, { timeoutMs: 120_000 }, { timeoutMs: 999 }, { timeoutMs: 1_500.5 }, { quickTimeoutMs: 90_000 }]) {
|
||||
expect(pluginManifestV1Schema.safeParse(slowManifest(bad)).success).toBe(false);
|
||||
}
|
||||
|
||||
const f = await setup(pluginManifestV1Schema.parse(slowManifest()) as PaperclipPluginManifestV1, { delayMs: 90_000 });
|
||||
const { buildReport } = await connectReports(f);
|
||||
const call = await settleAfter(f, () => f.gateway.executeTool({ sessionToken: f.token, tool: buildReport.name, parameters: {},
|
||||
timeoutMs: 120_000, idempotencyKey: randomUUID() }), 60_000);
|
||||
expect(call).toMatchObject(timedOut);
|
||||
expect(f.workers.calls.at(-1)).toMatchObject({ timeoutMs: 61_000 });
|
||||
});
|
||||
it("leaves legacy plugin tools on their own deadline path", async () => {
|
||||
const legacyManifest = pluginManifestV1Schema.parse({
|
||||
id: "example.legacy-slow", apiVersion: 1, version: "1.0.0", displayName: "Legacy slow", description: "Legacy tools", author: "Tests",
|
||||
categories: ["connector"], capabilities: ["agent.tools.register"], entrypoints: { worker: "worker.js" },
|
||||
tools: [{ name: "read-status", displayName: "Read status", description: "Read status", parametersSchema: { type: "object" } }],
|
||||
}) as PaperclipPluginManifestV1;
|
||||
const legacyPluginDbId = randomUUID();
|
||||
const dispatched: string[] = [];
|
||||
const dispatcher: PluginToolDispatcher = {
|
||||
initialize: async () => {}, teardown: () => {},
|
||||
listToolsForAgent: () => [{ name: "example.legacy-slow:read-status", displayName: "Read status", description: "Read status",
|
||||
parametersSchema: { type: "object" }, pluginId: legacyPluginDbId }],
|
||||
getTool: () => null,
|
||||
executeTool: (toolName) => {
|
||||
dispatched.push(toolName);
|
||||
return new Promise((resolve) => setTimeout(() => resolve({ pluginId: "example.legacy-slow", toolName: "read-status", result: { content: "ok" } }), BACKEND_DELAY_MS));
|
||||
},
|
||||
registerPluginTools: () => {}, unregisterPluginTools: () => {}, toolCount: () => 1, getRegistry: () => { throw new Error("unused"); },
|
||||
};
|
||||
const f = await setup(legacyManifest, { dispatcher });
|
||||
const [profile] = await db.insert(toolProfiles).values({ companyId: f.company.id, profileKey: `legacy-${randomUUID()}`, name: `Legacy ${randomUUID()}`, defaultAction: "deny" }).returning();
|
||||
await db.insert(toolProfileBindings).values({ companyId: f.company.id, profileId: profile.id, targetType: "agent", targetId: f.agent.id });
|
||||
await db.insert(toolProfileEntries).values({ companyId: f.company.id, profileId: profile.id, selectorType: "tool_name", effect: "include", toolName: "example.legacy-slow:read-status" });
|
||||
await db.insert(pluginConnectorLegacyAccess).values({ companyId: f.company.id, pluginKey: "example.legacy-slow" });
|
||||
expect(await completeLegacyPluginToolAccess(db)).toBe(1);
|
||||
const tool = (await f.gateway.listToolsForSession(f.token)).find(candidate => candidate.name === "example.legacy-slow:read-status")!;
|
||||
expect(tool.providerType).toBe("paperclip_plugin");
|
||||
const call = await settleAfter({ workers: { calls: dispatched } }, () => f.gateway.executeTool({ sessionToken: f.token, tool: tool.name, parameters: {},
|
||||
timeoutMs: 5_000, idempotencyKey: randomUUID() }), 5_000);
|
||||
expect(call).toMatchObject(timedOut);
|
||||
expect(f.workers.calls).toEqual([]);
|
||||
});
|
||||
});
|
||||
@@ -9,6 +9,7 @@
|
||||
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,
|
||||
@@ -104,6 +105,18 @@ export function pluginCatalogEntryCurrent(
|
||||
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
|
||||
@@ -183,6 +196,7 @@ export async function executePluginConnectionTool(
|
||||
toolName: string;
|
||||
parameters: unknown;
|
||||
runContext: ToolRunContext & { connection: NonNullable<ToolRunContext["connection"]> };
|
||||
timeoutMs: number;
|
||||
},
|
||||
): Promise<ToolResult> {
|
||||
const pluginDbId = await runningWorker(db, input.pluginKey);
|
||||
@@ -191,5 +205,5 @@ export async function executePluginConnectionTool(
|
||||
appSlug: input.appSlug,
|
||||
parameters: input.parameters,
|
||||
runContext: input.runContext,
|
||||
});
|
||||
}, input.timeoutMs + PLUGIN_CONNECTOR_RPC_GRACE_MS);
|
||||
}
|
||||
@@ -88,7 +88,7 @@ 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 { executePluginConnectionTool as executePluginConnectionWorkerTool, pluginCatalogEntryCurrent, pluginConnectionIdentity, pluginConnectionToolTimeoutMs, 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";
|
||||
@@ -5078,6 +5078,7 @@ export function createToolGatewayService(
|
||||
session: ToolGatewaySession,
|
||||
tool: ToolGatewayDescriptor,
|
||||
parameters: unknown,
|
||||
requestedTimeoutMs: number | undefined,
|
||||
) {
|
||||
const [connection] = await db.select().from(toolConnections).where(and(
|
||||
eq(toolConnections.companyId, session.companyId),
|
||||
@@ -5087,6 +5088,24 @@ export function createToolGatewayService(
|
||||
if (!connection || !identity || !tool.upstreamToolName) {
|
||||
throw new ToolGatewayHttpError(404, `Tool "${tool.name}" not found`, "tool_not_found", { tool: tool.name });
|
||||
}
|
||||
const executionTimeoutMs = timeoutMs(
|
||||
Number.isFinite(requestedTimeoutMs) ? requestedTimeoutMs : pluginConnectionToolTimeoutMs(connection, tool.upstreamToolName),
|
||||
tool,
|
||||
);
|
||||
return runWithTimeout(
|
||||
runPluginConnectionTool(session, tool.upstreamToolName, connection, identity, parameters, executionTimeoutMs),
|
||||
executionTimeoutMs,
|
||||
);
|
||||
}
|
||||
|
||||
async function runPluginConnectionTool(
|
||||
session: ToolGatewaySession,
|
||||
toolName: string,
|
||||
connection: typeof toolConnections.$inferSelect,
|
||||
identity: NonNullable<ReturnType<typeof pluginConnectionIdentity>>,
|
||||
parameters: unknown,
|
||||
executionTimeoutMs: number,
|
||||
) {
|
||||
const grant = await resolveConnectionGrant(session, connection);
|
||||
let credential: { kind: "api_key"; value: string } | undefined;
|
||||
if (connection.authKind === "api_key") {
|
||||
@@ -5099,7 +5118,7 @@ export function createToolGatewayService(
|
||||
result = await executePluginConnectionWorkerTool(db, {
|
||||
pluginKey: identity.pluginKey,
|
||||
appSlug: identity.appSlug,
|
||||
toolName: tool.upstreamToolName,
|
||||
toolName,
|
||||
parameters,
|
||||
runContext: {
|
||||
agentId: session.agentId ?? "",
|
||||
@@ -5115,6 +5134,7 @@ export function createToolGatewayService(
|
||||
...(credential ? { credential } : {}),
|
||||
},
|
||||
},
|
||||
timeoutMs: executionTimeoutMs,
|
||||
});
|
||||
} catch (error) {
|
||||
const unavailable = findPluginWorkerUnavailableError(error);
|
||||
@@ -9973,7 +9993,7 @@ export function createToolGatewayService(
|
||||
)
|
||||
: 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>>
|
||||
? { result: await executePluginConnectionTool(args.session, args.tool, args.parameters, args.timeoutMs) } as unknown as Awaited<ReturnType<typeof executeLocalStdioTool>>
|
||||
: null;
|
||||
if (!connectedMcpExecution) {
|
||||
throw new ToolGatewayHttpError(
|
||||
@@ -10857,7 +10877,7 @@ export function createToolGatewayService(
|
||||
const result = connectedMcpExecution
|
||||
? connectedMcpExecution.result
|
||||
: tool.providerType === "paperclip_plugin_connection"
|
||||
? await runWithTimeout(executePluginConnectionTool(session, tool, parameters), executionTimeoutMs)
|
||||
? await executePluginConnectionTool(session, tool, parameters, executionTimeoutMs)
|
||||
: tool.providerType !== "paperclip_plugin"
|
||||
? await runWithTimeout(
|
||||
executeBuiltinTool(session, tool, parameters, invocation.id),
|
||||
@@ -13838,7 +13858,7 @@ export function createToolGatewayService(
|
||||
const result = recoveredGitHubPublication ?? (connectedMcpExecution
|
||||
? connectedMcpExecution.result
|
||||
: tool.providerType === "paperclip_plugin_connection"
|
||||
? await runWithTimeout(executePluginConnectionTool(session, tool, effectiveParameters), executionTimeoutMs)
|
||||
? await executePluginConnectionTool(session, tool, effectiveParameters, input.timeoutMs)
|
||||
: tool.providerType === "paperclip_plugin"
|
||||
? await runWithTimeout(
|
||||
pluginToolDispatcher!.executeTool(
|
||||
|
||||
@@ -271,7 +271,7 @@
|
||||
"packages/shared/src/home-paths.ts": "fa4f1c440653b76b3dbb7a51026d557287deb45d",
|
||||
"packages/shared/src/humanize-connection.test.ts": "ba9e90a44c63452b0bf9f733adb90241921e8eca",
|
||||
"packages/shared/src/humanize-connection.ts": "fbd414476a0ef7106a7c80d8572208781b091699",
|
||||
"packages/shared/src/index.ts": "aa3cc0be784184791368508977d97d89c2f58530",
|
||||
"packages/shared/src/index.ts": "3a12def1d847e8f153ada018d3926082ce454d59",
|
||||
"packages/shared/src/issue-activity-identity.test.ts": "3dc294640f54c2be67943e3e0149cf4eff2c95ca",
|
||||
"packages/shared/src/issue-activity-identity.ts": "1b0f07ec3fe0506aaaf80a4fa9893f3baf8f0075",
|
||||
"packages/shared/src/issue-attribution.test.ts": "84563685e7f3c48029243cf1cc24a3a09ee3cde9",
|
||||
@@ -310,7 +310,7 @@
|
||||
"packages/shared/src/openrouter-attribution.ts": "b77e887721cbf6bd882004f07df2405b6e58e52c",
|
||||
"packages/shared/src/paperclip-peer.test.ts": "304c9db3bb82871834f4e8970d334cb21bb9de7a",
|
||||
"packages/shared/src/paperclip-peer.ts": "12d38951f28bc4b492e8074f56279ec0da543ec3",
|
||||
"packages/shared/src/plugin-apps.test.ts": "532b54355cb9828be8327d8d4889adbfceff0c9b",
|
||||
"packages/shared/src/plugin-apps.test.ts": "57e9aa8e05d0a00c180e2601ecf620088bf064df",
|
||||
"packages/shared/src/plugin-apps.ts": "59e63a673878e460d4fedebca576eef091dff9b6",
|
||||
"packages/shared/src/portability-fidelity.test.ts": "3cb1d7740cd016d8f2000cf400b87971c571e5ed",
|
||||
"packages/shared/src/portability-fidelity.ts": "3465dc57777f0f74bcc018ecc9fa955d3c92f4a3",
|
||||
@@ -394,7 +394,7 @@
|
||||
"packages/shared/src/types/agent-lifecycle.ts": "dcc5105d57856cc8ca34a122cf54117c950184ea",
|
||||
"packages/shared/src/types/agent.adapter-auth-session.test.ts": "d651511d78cb44b29940252df6138cd202e0ab45",
|
||||
"packages/shared/src/types/agent.ts": "11f5dbdf5b4c16271b5d79e22b159f97be68e896",
|
||||
"packages/shared/src/types/app-definition.ts": "965d93e6671b465d781ee18019798ff99b5819eb",
|
||||
"packages/shared/src/types/app-definition.ts": "f85d917a9389963ad05e76668f12640c0d14bb08",
|
||||
"packages/shared/src/types/approval.ts": "4554d36f804cb74b825b29711ed4c622df07ff6d",
|
||||
"packages/shared/src/types/artifact.ts": "6d022d34a718196df5c109a6164e7a70ede287e8",
|
||||
"packages/shared/src/types/asset.ts": "d148d6cba0e9a8d2e3aa6cb9182df6f59f909fba",
|
||||
@@ -470,7 +470,7 @@
|
||||
"packages/shared/src/validators/agent-commentary.ts": "8242c5b28a77131aefdc00c873ad84c6c6736e4b",
|
||||
"packages/shared/src/validators/agent.test.ts": "d38767b0c1fc1439871855ed55dca3c8c7b645c6",
|
||||
"packages/shared/src/validators/agent.ts": "13ba04317b11c4281b7a2133a34630b4ad446dfd",
|
||||
"packages/shared/src/validators/app-definition.ts": "c97907a348e9278a28588ed7d6a395ec04dde0da",
|
||||
"packages/shared/src/validators/app-definition.ts": "87a60e50f386c8f836d1c5a1576b75a50bc719a2",
|
||||
"packages/shared/src/validators/approval.test.ts": "051d29b27400fdd1e311466587b276264cf072e4",
|
||||
"packages/shared/src/validators/approval.ts": "b8fd4da39568e3b70b767266196ea5303efeef25",
|
||||
"packages/shared/src/validators/artifact.test.ts": "2f0c138a6fa46d68507515d3932e9bc4cef44374",
|
||||
|
||||
Reference in new issue
Block a user