mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 02:43:25 +01:00
Let plugin workers serve connector tools (plugin transport) (#22019)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Plugins can now add connector types to the Connectors catalog (#22004), but only for transports the host already runs (remote MCP, local stdio) > - A plugin cannot yet serve a connector's tools itself, and legacy plugin tools (top-level manifest `tools`) still reach every agent without a connection or install > - A plugin should be able to ship a full connector: settings, credentials, tools, grants, policies and audit, like a built-in one > - This pull request adds the `plugin` transport, the SDK API to serve it, and moves legacy plugin tools under the same activation rules without changing today's access > - The benefit is that any connector can live in a plugin, and agents get plugin tools only when an operator enables them ## Linked Issues or Issue Description Refs #22004 **Subsystem affected** Plugins (SDK, worker protocol, manifest), Connectors (tool access, catalog discovery), tool gateway, database. **Problem or motivation** A plugin connector can only describe an existing transport. There is no way for a plugin worker to serve a connector's tools with per-connection settings and credentials. Legacy plugin tools are visible to every agent as soon as the plugin is enabled, which is the opposite of the connector activation rules. **Proposed solution** Add a `plugin` transport. The gateway keeps every decision (grant, policy, approval, rate limit, audit) and calls the plugin worker with the connection, its settings and a per-call credential. Legacy top-level tools become one implicit connector per plugin. Existing installations keep exactly their current access through a one-time migration. **Alternatives considered** Move legacy tools to connection tool names (`app.<connection>:<tool>`). Rejected: names change, so existing tool policies and agent instructions that name `plugin:tool` would stop matching (a possible widening or loss). Legacy tools keep their names and handlers; only their visibility is now gated by an install of the implicit connector. ## What Changed - `packages/db`: migration `0491` widens `tool_connections_transport_check` with `plugin` (`NOT VALID`, annotated `online_compatible`), and adds `plugin_connector_legacy_access`, seeded with one row per installed legacy-tools plugin and company. - `packages/shared`: method schema gains `settingsSchema` and `tools` (`{ kind: "static", list: [{ name, displayName?, description?, risk, parametersSchema }] } | { kind: "dynamic" }`), only for `transport: "plugin"`; tool names must match `[a-z0-9_]`; plugin-served methods use `none` or `api_key`. The connect API accepts `settings`. - `packages/plugins/sdk`: `ToolRunContext.connection` (`id`, `appSlug`, `methodKey`, `grantId`, `settings`, `credential?`); `ctx.connectors.register(appSlug, toolName, fn)` and `ctx.connectors.listTools(appSlug, fn)`; new `listConnectorTools` RPC; `executeTool` routes connector calls by `appSlug`. A worker refuses to start when a declared static tool (or dynamic lister) has no handler. The test harness gains `executeConnectorTool` and `listConnectorTools`. - `server/src/services/plugin-connector-runtime.ts`: routes one call to the plugin's worker; a stopped worker is a `PluginWorkerUnavailableError`. - Connect flow (`tool-access.ts`): a `plugin` method creates a `paperclip_plugin` application and a `plugin` connection with `config = { sourceTemplateKey, connectionMethodKey, settings }`, validated against `settingsSchema`. Credentials, grants, credential policy, installs and profiles use the existing code. - Catalog: static tools come from the definition, dynamic tools from `listConnectorTools`, with the existing version hashing and retirement. Tool risk comes from the declaration. - Gateway: plugin connections join connected-tool discovery and both execution paths (direct and approved actions). For each call the gateway resolves the grant and, for `api_key`, the credential for that call only. The run context comes only from the session. A stopped worker returns `503 plugin_connector_unavailable` with `retryable: true`. The token broker refuses to export plugin connector credentials. - Legacy tools: a plugin with top-level `tools` and no `apps` gets an implicit connector (slug `default`, named after the plugin, no authentication). Its tools keep their names, handlers and today's access decision, and an agent sees them only when a connection of that connector is installed for it or for the company. The connector's saved action rules (Off, Ask first) can only restrict them. `completeLegacyPluginToolAccess` turns each migration row into such a connection with a company install, at boot and when a disabled plugin is enabled again; it is single-flight across servers, resumes a draft left by an interrupted attempt, and never overrides an operator's later changes. - Catalog: tools a dynamic connector stops offering are retired from discovery; `listConnectorTools` carries the connection's `companyId`, and uses the acting person's grant for personal connections. - Board: the setup flow renders `settingsSchema` with the shared JSON Schema form, sends `settings`, and restores saved settings on resume and reconnect. - `create-paperclip-plugin --template connector` now scaffolds a plugin connector (`apps` + `ctx.connectors.register` + a harness test). SDK README and `PLUGIN_SPEC.md` describe connectors; top-level `tools` stay documented as legacy. - `inferToolRisk` moves to `tool-risk-inference.ts` so the catalog can reuse it. Design notes where the spec left room: - OAuth for `plugin`-transport methods is not supported in this PR (`none` and `api_key` only); OAuth plugin connectors can use `mcp_remote` today. Noted as follow-up. - Board "Test" calls on a plugin connection pass an empty `agentId`/`runId`, because there is no agent run. - Companies created after the upgrade get no automatic legacy connection; they follow the normal activation rules. ## Verification - `server`: `npx vitest run src/__tests__/plugin-connectors-plugin-transport.test.ts` (new): - rules 1-3: a ready plugin and configured accounts give no tools; an install for agent A gives only A the tools; agent B is denied on invocation; - the worker receives `runContext.connection` with the right id, method, grant, settings and the call's credential; spoofed arguments do not change it; each account calls with its own key; results do not contain the key; - invalid settings are rejected (422); a stopped worker is `503 plugin_connector_unavailable` (retryable); a disabled plugin hides the tools; - dynamic tools are listed through the worker and a tool it stops offering is retired; - rule 5: a new installation of a legacy-tools plugin gives no tools; an installation recorded by the migration keeps the same tool names for every agent, through one company-wide connection (two concurrent carry-overs make one; an interrupted draft is finished; a retry keeps an operator's restriction), and is not also exposed as connection tools; Ask first and Off on the implicit connector restrict the legacy tools; - the token broker refuses to export a plugin connection's credential. - Existing gateway plugin-tool tests (`tool-gateway`, `tool-gateway-service`, `prompt-injection-gateway`) now set up the legacy grant an existing installation has, and pass unchanged otherwise. - Regression: `plugin-connectors-circleback-parity`, `tool-gateway`, `tool-gateway-service`, `prompt-injection-gateway`, `tool-access-service` (846 passed), plus `connector-tool-policy`, `plugin-lifecycle-restart`, `remote-mcp-connectors`, `ai-connection-router` in an earlier run. - UI: `AppsConnect.test.tsx` covers sending plugin settings from the settings schema. - SDK: `tests/worker-rpc-host.test.ts` (start refusal without handlers, connector routing, tool listing). Scaffold: `entrypoints.test.ts`. - `packages/db`: `pnpm typecheck` including `check:migrations`; server layered typecheck (sources and tests); `tsc --noEmit` for shared, SDK, scaffold and UI. ## Risks - Behavior change for new installations: legacy plugin tools no longer reach agents until an operator connects the plugin's connector. Installations that exist at upgrade time keep their tools through the migration rows. - The migration widens a check constraint (`NOT VALID`) and copies plugin × company rows into a new table. Both are fast; the previous release never writes `plugin`. - Calls depend on the plugin worker; when it is down the agent gets a retryable error. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file editing, test execution). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
ceaf574421
commit
f4cb69205e
45 files changed
+2346
-80
No files matched your search
@@ -71,4 +71,18 @@ describe("create-paperclip-plugin entrypoints", () => {
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it("scaffolds a plugin connector for the connector template", async () => {
|
||||
const { scaffoldPluginProject } = await import("./index.js");
|
||||
const outputDir = scaffoldPluginProject({ pluginName: "records-plugin", outputDir: path.join(makeTempDir(), "records-plugin"), template: "connector" });
|
||||
const manifest = fs.readFileSync(path.join(outputDir, "src", "manifest.ts"), "utf8");
|
||||
const worker = fs.readFileSync(path.join(outputDir, "src", "worker.ts"), "utf8");
|
||||
expect(manifest).toContain('"connectors.provide"');
|
||||
expect(manifest).toContain('transport: "plugin"');
|
||||
expect(manifest).toContain('name: "lookup_record"');
|
||||
expect(worker).toContain('ctx.connectors.register("records", "lookup_record"');
|
||||
expect(worker).toContain("`Record ${id} (${region})`");
|
||||
const defaults = scaffoldPluginProject({ pluginName: "plain-plugin", outputDir: path.join(makeTempDir(), "plain-plugin") });
|
||||
expect(fs.readFileSync(path.join(defaults, "src", "manifest.ts"), "utf8")).not.toContain("connectors.provide");
|
||||
});
|
||||
});
|
||||
@@ -544,12 +544,60 @@ const manifest: PaperclipPluginManifestV1 = {
|
||||
"events.subscribe",
|
||||
"plugin.state.read",
|
||||
"plugin.state.write",
|
||||
"ui.dashboardWidget.register"
|
||||
"ui.dashboardWidget.register"${template === "connector" ? `,
|
||||
"connectors.provide"` : ""}
|
||||
],
|
||||
entrypoints: {
|
||||
worker: "./dist/worker.js",
|
||||
ui: "./dist/ui"
|
||||
},
|
||||
},${template === "connector" ? `
|
||||
// A connector type for the Connectors catalog. It grants no tools by itself:
|
||||
// an operator connects it and chooses which agents (or the whole company)
|
||||
// can use its tools, exactly like a built-in connector.
|
||||
apps: [
|
||||
{
|
||||
schemaVersion: 1,
|
||||
slug: "records",
|
||||
name: ${quote(displayName)},
|
||||
description: "Look up records.",
|
||||
categories: ["data"],
|
||||
branding: { logoUrl: "/brands/apps/api-key-generic.svg" },
|
||||
urlPatterns: [],
|
||||
methods: [
|
||||
{
|
||||
key: "default",
|
||||
label: "Connect",
|
||||
transport: "plugin",
|
||||
auth: "none",
|
||||
ownershipModes: ["customer"],
|
||||
whenToUse: "Look up records from this plugin.",
|
||||
guidanceMd: "No sign-in is needed.",
|
||||
riskTier: "S1",
|
||||
settingsSchema: {
|
||||
type: "object",
|
||||
properties: { region: { type: "string", enum: ["us", "eu"] } },
|
||||
additionalProperties: false
|
||||
},
|
||||
tools: {
|
||||
kind: "static",
|
||||
list: [
|
||||
{
|
||||
name: "lookup_record",
|
||||
displayName: "Look up a record",
|
||||
description: "Return one record by id.",
|
||||
risk: "read",
|
||||
parametersSchema: {
|
||||
type: "object",
|
||||
properties: { id: { type: "string" } },
|
||||
required: ["id"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],` : ""}
|
||||
ui: {
|
||||
slots: [
|
||||
{
|
||||
@@ -585,7 +633,15 @@ const plugin = definePlugin({
|
||||
ctx.actions.register("ping", async () => {
|
||||
ctx.logger.info("Ping action invoked");
|
||||
return { pong: true, at: new Date().toISOString() };
|
||||
});
|
||||
});${template === "connector" ? `
|
||||
|
||||
// Each call runs on one connection. The host passes its settings (and,
|
||||
// for authenticated methods, a credential for this call only).
|
||||
ctx.connectors.register("records", "lookup_record", async (params, runCtx) => {
|
||||
const { id } = params as { id: string };
|
||||
const region = String(runCtx.connection.settings.region ?? "us");
|
||||
return { content: \`Record \${id} (\${region})\`, data: { id, region } };
|
||||
});` : ""}
|
||||
},
|
||||
|
||||
async onHealth() {
|
||||
@@ -651,7 +707,16 @@ describe("plugin scaffold", () => {
|
||||
|
||||
const action = await harness.performAction<{ pong: boolean }>("ping");
|
||||
expect(action.pong).toBe(true);
|
||||
});
|
||||
});${template === "connector" ? `
|
||||
|
||||
it("serves its connector tool on a connection", async () => {
|
||||
const harness = createTestHarness({ manifest });
|
||||
await plugin.definition.setup(harness.ctx);
|
||||
const result = await harness.executeConnectorTool<{ data: { region: string } }>(
|
||||
"records", "lookup_record", { id: "r1" }, { settings: { region: "eu" } },
|
||||
);
|
||||
expect(result.data.region).toBe("eu");
|
||||
});` : ""}
|
||||
});
|
||||
`,
|
||||
);
|
||||
|
||||
@@ -115,6 +115,39 @@ export default plugin;
|
||||
runWorker(plugin, import.meta.url);
|
||||
```
|
||||
|
||||
### Connectors
|
||||
|
||||
Prefer a connector over top-level `tools` for new plugins. Declare it in the
|
||||
manifest `apps` (requires `connectors.provide`) with a method that uses
|
||||
`transport: "plugin"`, then serve its tools from the worker:
|
||||
|
||||
```ts
|
||||
// manifest: apps: [{ slug: "records", ..., methods: [{ key: "default", transport: "plugin",
|
||||
// auth: "none", settingsSchema: {...}, tools: { kind: "static", list: [
|
||||
// { name: "lookup_record", risk: "read", parametersSchema: {...} }] } }] }]
|
||||
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}` };
|
||||
});
|
||||
// For `tools: { kind: "dynamic" }`, list tools per connection:
|
||||
ctx.connectors.listTools("records", async (connection) => [
|
||||
{ name: "lookup_record", risk: "read", parametersSchema: { type: "object" } },
|
||||
]);
|
||||
```
|
||||
|
||||
A connector behaves like a built-in one: enabling the plugin only adds it to
|
||||
the Connectors catalog, and agents get its tools only from a connection
|
||||
installed for them or for the whole company. The host validates settings
|
||||
against `settingsSchema`, resolves the connection's credential (`api_key`
|
||||
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.
|
||||
|
||||
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
|
||||
installations get them through an install of that connector.
|
||||
|
||||
**Note:** `runWorker(plugin, import.meta.url)` must be called so that when the host runs your worker (e.g. `node dist/worker.js`), the RPC host starts and the process stays alive. When the file is imported (e.g. for tests), the main-module check prevents the host from starting.
|
||||
|
||||
### Worker lifecycle and context
|
||||
@@ -461,6 +494,7 @@ Declare in `manifest.capabilities`. Grouped by scope:
|
||||
| | `environment.drivers.register` |
|
||||
| | `local.folders` |
|
||||
| **Agent** | `agent.tools.register` |
|
||||
| **Connectors** | `connectors.provide` |
|
||||
| | `agents.invoke` |
|
||||
| | `access.members.write` |
|
||||
| | `access.invites.write` |
|
||||
|
||||
@@ -162,6 +162,8 @@ export type {
|
||||
PluginPerformActionActorContext,
|
||||
PluginPerformActionContext,
|
||||
ExecuteToolParams,
|
||||
ListConnectorToolsParams,
|
||||
ListConnectorToolsResult,
|
||||
PluginExternalObjectUrlCandidate,
|
||||
PluginExternalObjectSourceContext,
|
||||
DetectExternalObjectsParams,
|
||||
@@ -306,6 +308,12 @@ export type {
|
||||
PluginActionsClient,
|
||||
PluginStreamsClient,
|
||||
PluginToolsClient,
|
||||
PluginConnectorsClient,
|
||||
ConnectionCredential,
|
||||
ToolRunConnection,
|
||||
ConnectorToolListConnection,
|
||||
ConnectorToolDescriptor,
|
||||
ConnectorToolRunContext,
|
||||
PluginMetricsClient,
|
||||
PluginTelemetryClient,
|
||||
PluginLogger,
|
||||
|
||||
@@ -485,6 +485,23 @@ export interface ExecuteToolParams {
|
||||
parameters: unknown;
|
||||
/** Agent run context. */
|
||||
runContext: ToolRunContext;
|
||||
/** For a plugin connector tool: the app slug as declared in the manifest. */
|
||||
appSlug?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Input for the `listConnectorTools` RPC method: the tools a dynamic plugin
|
||||
* connector offers for one connection.
|
||||
*/
|
||||
export interface ListConnectorToolsParams {
|
||||
/** The company of the connection; host calls made while listing are scoped to it. */
|
||||
companyId: string;
|
||||
appSlug: string;
|
||||
connection: import("./types.js").ConnectorToolListConnection;
|
||||
}
|
||||
|
||||
export interface ListConnectorToolsResult {
|
||||
tools: import("./types.js").ConnectorToolDescriptor[];
|
||||
}
|
||||
|
||||
export interface PluginExternalObjectUrlCandidate {
|
||||
@@ -1446,6 +1463,7 @@ export interface HostToWorkerMethods {
|
||||
performAction: [params: PerformActionParams, result: unknown];
|
||||
/** @see PLUGIN_SPEC.md §13.10 */
|
||||
executeTool: [params: ExecuteToolParams, result: ToolResult];
|
||||
listConnectorTools: [params: ListConnectorToolsParams, result: ListConnectorToolsResult];
|
||||
detectExternalObjects: [
|
||||
params: DetectExternalObjectsParams,
|
||||
result: DetectExternalObjectsResult,
|
||||
@@ -1593,6 +1611,7 @@ export const HOST_TO_WORKER_OPTIONAL_METHODS: readonly HostToWorkerMethodName[]
|
||||
"getData",
|
||||
"performAction",
|
||||
"executeTool",
|
||||
"listConnectorTools",
|
||||
"detectExternalObjects",
|
||||
"routeAiConnection",
|
||||
"resolveExternalObject",
|
||||
|
||||
@@ -34,6 +34,10 @@ import type {
|
||||
ScopeKey,
|
||||
ToolResult,
|
||||
ToolRunContext,
|
||||
ToolRunConnection,
|
||||
ConnectorToolRunContext,
|
||||
ConnectorToolListConnection,
|
||||
ConnectorToolDescriptor,
|
||||
PluginWorkspace,
|
||||
PluginExecutionWorkspaceMetadata,
|
||||
AgentSession,
|
||||
@@ -142,6 +146,16 @@ export interface TestHarness {
|
||||
): Promise<T>;
|
||||
/** Execute a registered tool handler via `ctx.tools.execute(...)`. */
|
||||
executeTool<T = ToolResult>(name: string, params: unknown, runCtx?: Partial<ToolRunContext>): Promise<T>;
|
||||
/** Execute a `ctx.connectors.register(...)` handler on a test connection. */
|
||||
executeConnectorTool<T = ToolResult>(
|
||||
appSlug: string,
|
||||
toolName: string,
|
||||
params: unknown,
|
||||
connection?: Partial<ToolRunConnection>,
|
||||
runCtx?: Partial<ToolRunContext>,
|
||||
): Promise<T>;
|
||||
/** Call a `ctx.connectors.listTools(...)` handler for a test connection. */
|
||||
listConnectorTools(appSlug: string, connection?: Partial<ConnectorToolListConnection>): Promise<ConnectorToolDescriptor[]>;
|
||||
/** Read raw in-memory state for assertions. */
|
||||
getState(input: ScopeKey): unknown;
|
||||
/** Simulate a streaming event arriving for an active session. */
|
||||
@@ -596,6 +610,8 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
|
||||
(params: Record<string, unknown>, context: PluginPerformActionContext) => Promise<unknown>
|
||||
>();
|
||||
const toolHandlers = new Map<string, (params: unknown, runCtx: ToolRunContext) => Promise<ToolResult>>();
|
||||
const connectorToolHandlers = new Map<string, (params: unknown, runCtx: ConnectorToolRunContext) => Promise<ToolResult>>();
|
||||
const connectorToolListers = new Map<string, (connection: ConnectorToolListConnection) => Promise<ConnectorToolDescriptor[]>>();
|
||||
|
||||
function localFolderKey(companyId: string, folderKey: string): string {
|
||||
return `${companyId}:${folderKey}`;
|
||||
@@ -2585,6 +2601,16 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
|
||||
toolHandlers.set(name, fn);
|
||||
},
|
||||
},
|
||||
connectors: {
|
||||
register(appSlug, toolName, fn) {
|
||||
requireCapability(manifest, capabilitySet, "connectors.provide");
|
||||
connectorToolHandlers.set(`${appSlug}\u0000${toolName}`, fn);
|
||||
},
|
||||
listTools(appSlug, fn) {
|
||||
requireCapability(manifest, capabilitySet, "connectors.provide");
|
||||
connectorToolListers.set(appSlug, fn);
|
||||
},
|
||||
},
|
||||
metrics: {
|
||||
async write(name, value, tags) {
|
||||
requireCapability(manifest, capabilitySet, "metrics.write");
|
||||
@@ -2722,6 +2748,41 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
|
||||
};
|
||||
return await handler(params, ctxToPass) as T;
|
||||
},
|
||||
async executeConnectorTool<T = ToolResult>(
|
||||
appSlug: string,
|
||||
toolName: string,
|
||||
params: unknown,
|
||||
connection: Partial<ToolRunConnection> = {},
|
||||
runCtx: Partial<ToolRunContext> = {},
|
||||
) {
|
||||
const handler = connectorToolHandlers.get(`${appSlug}\u0000${toolName}`);
|
||||
if (!handler) throw new Error(`No connector tool handler registered for '${appSlug}/${toolName}'`);
|
||||
return await handler(params, {
|
||||
agentId: runCtx.agentId ?? "agent-test",
|
||||
runId: runCtx.runId ?? randomUUID(),
|
||||
companyId: runCtx.companyId ?? "company-test",
|
||||
projectId: runCtx.projectId ?? "project-test",
|
||||
connection: {
|
||||
id: connection.id ?? "connection-test",
|
||||
appSlug,
|
||||
methodKey: connection.methodKey ?? "default",
|
||||
grantId: connection.grantId ?? "grant-test",
|
||||
settings: connection.settings ?? {},
|
||||
...(connection.credential ? { credential: connection.credential } : {}),
|
||||
},
|
||||
}) as T;
|
||||
},
|
||||
async listConnectorTools(appSlug: string, connection: Partial<ConnectorToolListConnection> = {}) {
|
||||
const lister = connectorToolListers.get(appSlug);
|
||||
if (!lister) throw new Error(`No connector tool list handler registered for '${appSlug}'`);
|
||||
return lister({
|
||||
id: connection.id ?? "connection-test",
|
||||
appSlug,
|
||||
methodKey: connection.methodKey ?? "default",
|
||||
settings: connection.settings ?? {},
|
||||
...(connection.credential ? { credential: connection.credential } : {}),
|
||||
});
|
||||
},
|
||||
getState(input) {
|
||||
return state.get(stateMapKey(input));
|
||||
},
|
||||
|
||||
@@ -276,8 +276,56 @@ export interface ToolRunContext {
|
||||
* has no project. Check the value before you use it as a project ID.
|
||||
*/
|
||||
projectId: string;
|
||||
/**
|
||||
* The connection this call runs on. Present only for tools of a plugin
|
||||
* connector (`ctx.connectors.register`). The host resolves it from the
|
||||
* gateway session; tool arguments can never change it.
|
||||
*/
|
||||
connection?: ToolRunConnection;
|
||||
}
|
||||
|
||||
/**
|
||||
* A credential the host resolved for one connector call. It is valid for
|
||||
* that call only; the worker never reads the vault and never sees another
|
||||
* connection's credential.
|
||||
*/
|
||||
export interface ConnectionCredential {
|
||||
kind: "api_key";
|
||||
value: string;
|
||||
}
|
||||
|
||||
/** The connection a plugin connector tool runs on. */
|
||||
export interface ToolRunConnection {
|
||||
/** Connection id. */
|
||||
id: string;
|
||||
/** The app slug as declared in the manifest (not namespaced). */
|
||||
appSlug: string;
|
||||
/** The connection method key from the manifest. */
|
||||
methodKey: string;
|
||||
/** The grant whose credential the host resolved for this call. */
|
||||
grantId: string;
|
||||
/** Per-connection settings, validated against the method's `settingsSchema`. */
|
||||
settings: Record<string, unknown>;
|
||||
/** Present when the method authenticates. */
|
||||
credential?: ConnectionCredential;
|
||||
}
|
||||
|
||||
/** The connection passed to `ctx.connectors.listTools`. */
|
||||
export type ConnectorToolListConnection = Omit<ToolRunConnection, "grantId"> & { grantId?: string };
|
||||
|
||||
/** One tool a dynamic plugin connector offers for a connection. */
|
||||
export interface ConnectorToolDescriptor {
|
||||
/** Lowercase letters, digits and underscores. */
|
||||
name: string;
|
||||
displayName?: string;
|
||||
description?: string;
|
||||
risk: "read" | "write" | "destructive";
|
||||
parametersSchema: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/** Tool run context for a plugin connector tool: `connection` is always present. */
|
||||
export type ConnectorToolRunContext = ToolRunContext & { connection: ToolRunConnection };
|
||||
|
||||
/**
|
||||
* Result returned from a plugin tool handler.
|
||||
*
|
||||
@@ -1054,6 +1102,41 @@ export interface PluginToolsClient {
|
||||
): void;
|
||||
}
|
||||
|
||||
/**
|
||||
* `ctx.connectors` — serve the tools of connectors this plugin declares in
|
||||
* `apps` with `transport: "plugin"`.
|
||||
*
|
||||
* Requires the `connectors.provide` capability. Declaring a connector grants
|
||||
* no tools: agents get them only from a connection installed for them or for
|
||||
* the whole company, exactly like built-in connectors.
|
||||
*/
|
||||
export interface PluginConnectorsClient {
|
||||
/**
|
||||
* Register the handler for one tool of a plugin connector. Every static
|
||||
* tool in the manifest needs a handler before `setup` returns, or the worker
|
||||
* fails to start.
|
||||
*
|
||||
* @param appSlug - App slug as declared in the manifest
|
||||
* @param toolName - Tool name (`[a-z0-9_]`)
|
||||
* @param fn - Handler. `runCtx.connection` identifies the connection, its
|
||||
* settings and the credential the host resolved for this call.
|
||||
*/
|
||||
register(
|
||||
appSlug: string,
|
||||
toolName: string,
|
||||
fn: (params: unknown, runCtx: ConnectorToolRunContext) => Promise<ToolResult>,
|
||||
): void;
|
||||
/**
|
||||
* Provide the tool list of a `tools: { kind: "dynamic" }` connector for one
|
||||
* connection. The host caches the result in the connection's catalog and
|
||||
* refreshes it on connect, on settings change and on request.
|
||||
*/
|
||||
listTools(
|
||||
appSlug: string,
|
||||
fn: (connection: ConnectorToolListConnection) => Promise<ConnectorToolDescriptor[]>,
|
||||
): void;
|
||||
}
|
||||
|
||||
/**
|
||||
* `ctx.logger` — structured logging from the plugin worker.
|
||||
*
|
||||
@@ -2303,6 +2386,9 @@ export interface PluginContext {
|
||||
/** Register agent tool handlers. Requires `agent.tools.register`. */
|
||||
tools: PluginToolsClient;
|
||||
|
||||
/** Serve plugin connector tools. Requires `connectors.provide`. */
|
||||
connectors: PluginConnectorsClient;
|
||||
|
||||
/** Write plugin metrics. Requires `metrics.write`. */
|
||||
metrics: PluginMetricsClient;
|
||||
|
||||
|
||||
@@ -50,7 +50,8 @@ import { createPluginIdleDrain } from "./idle-drain.js";
|
||||
* @see PLUGIN_SPEC.md §14 — SDK Surface
|
||||
*/
|
||||
|
||||
import type { ResourceLifecycleEvent } from "./types.js";
|
||||
import type { ResourceLifecycleEvent, ConnectorToolRunContext, ConnectorToolListConnection, ConnectorToolDescriptor } from "./types.js";
|
||||
import type { ListConnectorToolsParams, ListConnectorToolsResult } from "./protocol.js";
|
||||
import fs from "node:fs";
|
||||
import { AsyncLocalStorage } from "node:async_hooks";
|
||||
import path from "node:path";
|
||||
@@ -384,6 +385,11 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
|
||||
fn: (params: unknown, runCtx: ToolRunContext) => Promise<ToolResult>;
|
||||
}>();
|
||||
|
||||
// Plugin connector handlers, keyed by `${appSlug}\u0000${toolName}` and appSlug.
|
||||
const connectorToolHandlers = new Map<string, (params: unknown, runCtx: ConnectorToolRunContext) => Promise<ToolResult>>();
|
||||
const connectorToolListers = new Map<string, (connection: ConnectorToolListConnection) => Promise<ConnectorToolDescriptor[]>>();
|
||||
const connectorKey = (appSlug: string, toolName: string) => `${appSlug}\u0000${toolName}`;
|
||||
|
||||
// Agent session event callbacks (populated by sendMessage, cleared by close)
|
||||
const sessionEventCallbacks = new Map<string, (event: AgentSessionEvent) => void>();
|
||||
|
||||
@@ -1529,6 +1535,15 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
|
||||
},
|
||||
},
|
||||
|
||||
connectors: {
|
||||
register(appSlug, toolName, fn) {
|
||||
connectorToolHandlers.set(connectorKey(appSlug, toolName), fn);
|
||||
},
|
||||
listTools(appSlug, fn) {
|
||||
connectorToolListers.set(appSlug, fn);
|
||||
},
|
||||
},
|
||||
|
||||
metrics: {
|
||||
async write(name: string, value: number, tags?: Record<string, string>): Promise<void> {
|
||||
await callHost("metrics.write", { name, value, tags });
|
||||
@@ -1723,6 +1738,12 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
|
||||
|
||||
case "executeTool":
|
||||
return handleExecuteTool(params as ExecuteToolParams);
|
||||
case "listConnectorTools": {
|
||||
const input = params as ListConnectorToolsParams;
|
||||
const lister = connectorToolListers.get(input.appSlug);
|
||||
if (!lister) throw methodNotImplemented("listConnectorTools");
|
||||
return { tools: await lister(input.connection) } satisfies ListConnectorToolsResult;
|
||||
}
|
||||
case "detectExternalObjects":
|
||||
return handleDetectExternalObjects(params as DetectExternalObjectsParams);
|
||||
case "workspacePrepare": {
|
||||
@@ -1869,6 +1890,23 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
|
||||
// Call the plugin's setup function
|
||||
await plugin.definition.setup(ctx);
|
||||
|
||||
// A declared static connector tool without a handler would fail every
|
||||
// call; refuse to start instead, so the operator sees it at enable time.
|
||||
for (const app of manifest.apps ?? []) {
|
||||
for (const method of app.methods) {
|
||||
if (method.transport !== "plugin" || !method.tools) continue;
|
||||
if (method.tools.kind === "dynamic") {
|
||||
if (!connectorToolListers.has(app.slug)) throw new Error(`Connector "${app.slug}" declares dynamic tools but registers no ctx.connectors.listTools handler`);
|
||||
continue;
|
||||
}
|
||||
for (const tool of method.tools.list) {
|
||||
if (!connectorToolHandlers.has(connectorKey(app.slug, tool.name))) {
|
||||
throw new Error(`Connector "${app.slug}" declares tool "${tool.name}" but registers no ctx.connectors.register handler for it`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
initialized = true;
|
||||
|
||||
// Report which optional methods this plugin implements
|
||||
@@ -2123,6 +2161,15 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
|
||||
}
|
||||
|
||||
async function handleExecuteTool(params: ExecuteToolParams): Promise<ToolResult> {
|
||||
if (params.appSlug !== undefined || params.runContext.connection) {
|
||||
const connection = params.runContext.connection;
|
||||
if (!connection || !params.appSlug || connection.appSlug !== params.appSlug) {
|
||||
throw new Error("A connector tool call requires its connection");
|
||||
}
|
||||
const handler = connectorToolHandlers.get(connectorKey(params.appSlug, params.toolName));
|
||||
if (!handler) throw new Error(`No connector tool handler registered for "${params.appSlug}/${params.toolName}"`);
|
||||
return handler(params.parameters, { ...params.runContext, connection });
|
||||
}
|
||||
const entry = toolHandlers.get(params.toolName);
|
||||
if (!entry) {
|
||||
throw new Error(`No tool handler registered for "${params.toolName}"`);
|
||||
|
||||
@@ -1245,6 +1245,50 @@ describe("AI connection router RPC", () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe("plugin connector RPC", () => {
|
||||
const connectorManifest = (tools: unknown) => ({ id: "fixture.connector", apiVersion: 1, version: "1.0.0", displayName: "Connector", description: "Fixture",
|
||||
author: "Tests", categories: ["connector"], capabilities: ["connectors.provide"], entrypoints: {},
|
||||
apps: [{ schemaVersion: 1, slug: "records", name: "Records", description: "Records", categories: ["data"], branding: { logoUrl: "/brands/apps/api-key-generic.svg" },
|
||||
urlPatterns: [], methods: [{ key: "default", transport: "plugin", auth: "none", ownershipModes: ["customer"], whenToUse: "Use", guidanceMd: "Use", riskTier: "S1", tools }] }] });
|
||||
async function host(setup: Parameters<typeof definePlugin>[0]["setup"]) {
|
||||
const input = new PassThrough(), output = new PassThrough();
|
||||
const reader = createInterface({ input: output });
|
||||
const worker = startWorkerRpcHost({ plugin: definePlugin({ setup }), stdin: input, stdout: output });
|
||||
let sequence = 0;
|
||||
const pending = new Map<string, (value: unknown) => void>();
|
||||
reader.on("line", line => { const response = parseMessage(line); if (isJsonRpcResponse(response)) { pending.get(String(response.id))?.(response); pending.delete(String(response.id)); } });
|
||||
const call = (method: string, params: unknown) => new Promise<JsonRpcResponse>(resolve => { const id = String(++sequence); pending.set(id, value => resolve(value as JsonRpcResponse)); input.write(serializeMessage(createRequest(method, params, id))); });
|
||||
return { call, stop: () => { worker.stop(); reader.close(); input.destroy(); output.destroy(); } };
|
||||
}
|
||||
const staticTools = { kind: "static", list: [{ name: "lookup", risk: "read", parametersSchema: { type: "object" } }] };
|
||||
|
||||
it("refuses to start when a declared static tool has no handler", async () => {
|
||||
const worker = await host(async () => {});
|
||||
try {
|
||||
const initialized = await worker.call("initialize", { manifest: connectorManifest(staticTools), config: {}, databaseNamespace: null }) as { error?: { message: string } };
|
||||
expect(initialized.error?.message).toContain('declares tool "lookup"');
|
||||
} finally { worker.stop(); }
|
||||
});
|
||||
|
||||
it("routes connector calls and tool lists to their handlers with the connection", async () => {
|
||||
let received: unknown;
|
||||
const worker = await host(async (ctx) => {
|
||||
ctx.connectors.register("records", "lookup", async (params, runCtx) => { received = { params, runCtx }; return { content: "found" }; });
|
||||
ctx.connectors.listTools("records", async (connection) => [{ name: `for_${connection.id}`, risk: "read", parametersSchema: { type: "object" } }]);
|
||||
});
|
||||
try {
|
||||
expect((await worker.call("initialize", { manifest: connectorManifest(staticTools), config: {}, databaseNamespace: null }) as { error?: unknown }).error).toBeUndefined();
|
||||
const connection = { id: "conn", appSlug: "records", methodKey: "default", grantId: "grant", settings: { region: "eu" } };
|
||||
const runContext = { agentId: "agent", runId: "run", companyId: "company", projectId: "", connection };
|
||||
expect((await worker.call("executeTool", { toolName: "lookup", appSlug: "records", parameters: { id: "1" }, runContext }) as { result: unknown }).result).toEqual({ content: "found" });
|
||||
expect(received).toEqual({ params: { id: "1" }, runCtx: runContext });
|
||||
expect((await worker.call("executeTool", { toolName: "lookup", appSlug: "records", parameters: {}, runContext: { ...runContext, connection: undefined } }) as { error?: unknown }).error).toBeTruthy();
|
||||
expect((await worker.call("listConnectorTools", { companyId: "company", appSlug: "records", connection }) as { result: unknown }).result)
|
||||
.toEqual({ tools: [{ name: "for_conn", risk: "read", parametersSchema: { type: "object" } }] });
|
||||
} finally { worker.stop(); }
|
||||
});
|
||||
});
|
||||
|
||||
describe("Durable lifecycle inbox RPC", () => {
|
||||
it("sends company-scoped reads and acknowledgments through the worker SDK", async () => {
|
||||
const input = new PassThrough(), output = new PassThrough();
|
||||
|
||||
Reference in new issue
Block a user