From adb2bcf8968130a39eda4a6ae4a29fb7958dcc07 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Wed, 18 Nov 2026 11:25:25 -0600 Subject: [PATCH] fix(connectors): activate plugin connectors with agent grants and no sign-in (#22201) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Plugins can now add connector types (#22004) and serve their tools with the `plugin` transport (#22019) > - A plugin connector method can declare `grantKinds: ["agent"]` with `auth: "none"` or `"api_key"` > - Such a connector cannot reach its agent: the connect form cannot name the agent, connect creates no agent grant, and Paperclip Runner runs never list plugin-transport tools > - The product rule is that a plugin connector behaves exactly like any existing connector > - This pull request fixes the connect form, creates the agent grant at connect, and lets runner runs list plugin-transport tools > - The benefit is that an operator can activate a per-agent plugin connector, and only the chosen agent gets its tools ## Linked Issues or Issue Description Refs #22004 Refs #22019 **Subsystem affected** Connectors (connect wizard, tool access service), Paperclip Runner assigned-tool gateway. **Problem or motivation** A plugin connector with agent grants and no sign-in cannot be activated: 1. Connect form: it says "No sign-in needed, available to all agents". "Change" shows "No identity required" and "Which agent owns this GitHub account?", with no agent picker. Connect sends `grantKind: "agent"` without `subjectAgentId`, and the server rejects it with a validation error. The "Finish setup" resume form has the same problem. 2. Grant: connect with `subjectAgentId` saves a `per_agent` connection with zero grants. Finish adds the agent install, but there is still no grant. Only the OAuth callback writes agent grants, and these methods have no OAuth step. For `api_key` methods connect fails, because the health check finds no agent grant, and the key has nowhere to go. 3. Runner: a Paperclip Runner run builds its assigned-tool gateway from an allowlist of transports (`mcp_remote`, `local_stdio`, REST, Browser Use, GitHub bot, voice). `plugin` is not in it, so the run sees no plugin-transport tools, even when the install, profile and grant allow them. **Proposed solution** Create the agent grant at connect for curated methods without sign-in. Add `plugin` to the runner assignment and its digest. Show a one-agent picker with connector-neutral copy. **Expected behavior** Connecting alone grants no tools. Finish with agent A gives only agent A the tools, in gateway discovery and in a runner run. The connection has exactly one active agent grant, for A. ## What Changed - `server/src/services/tool-access.ts`: `connectGalleryApp` writes an active agent grant for `subjectAgentId` when a curated method with `auth` `none` or `api_key` uses `grantKind: "agent"`. The API key goes on that grant, not on the connection. A resume without `subjectAgentId` keeps the agent of the existing grant and keeps its saved key. A second agent on the same connection is a 409 conflict. The grant write is audited and joins the existing revive rollback. - Finish does not create agent grants. Finish carries no credential, and it can list many agents while a per-agent connection has one identity. A credential-less grant would also claim a connected OAuth identity that does not exist. The grant comes from connect (or the OAuth callback). Finish creates only the install. - `server/src/services/heartbeat/run-preparation.ts` and `native-runtime/runtime-context.ts`: include the `plugin` transport in the runner assignment and in its digest (the two lists must match). - `ui/src/features/connections/ConnectionSetupFlow.tsx`: for an agent grant, show the agent picker (exactly one agent), keep the install choice on "specific", open the "Change" panel and disable Connect until one agent is chosen, and send `subjectAgentId`. Copy is neutral ("Which agent uses this connection?"); the GitHub copy stays for GitHub. The summary no longer says "available to all agents" for an agent grant. Finish sends the chosen agent, never `all_agents`, for an agent grant. - `doc/connections/CONNECTOR-PLAYBOOK.md`: document agent grants for methods without sign-in. ## Verification Each new test failed before its fix and passes after it: - `server/src/__tests__/plugin-connector-agent-grant.test.ts` (embedded Postgres, real routes and gateway): - `auth: "none"` + agent grants: after connect, no agent has tools; after finish with agent A, A's discovery lists the tools and B's lists none; exactly one active agent grant, for A. (Red: zero grants.) - `auth: "api_key"` + agent grants: same, the key is on A's grant, and a tool call receives it. (Red: connect returned 422.) - A second agent on the same connection is a 409. (Red: 201.) - Resume of an API-key draft without the key keeps the key on the grant. - Paperclip Runner session: `buildPaperclipRuntimeMcpServers` + `createAssignedMcpTools` list the installed plugin tools for A, and search by the manifest tool name (`update_record`) finds the gateway tool. B gets none. (Red: no tools.) - Regression: an organization-grant method keeps one default organization grant, and both agents get the tools with `all_agents`. - `ui/src/pages/apps/AppsConnect.test.tsx`: for `none` and `api_key` agent-grant plugin methods, the form shows the picker, has no GitHub or "available to all agents" copy, blocks Connect until an agent is chosen, and sends `subjectAgentId`. (Red: "available to all agents" shown.) - Regression suites: `plugin-connectors-plugin-transport`, `plugin-connectors-circleback-parity`, `heartbeat-runtime-mcp-servers`, `run-preparation`, `tool-access-service`, `tool-access-oauth-protocol.integration`, `generic-mcp-connection` (OAuth, GitHub per-agent and organization flows) pass. UI: `src/features/connections`, `src/pages/apps`, `App.deep-link-routing` pass (66 files, 1103 tests). - `tsc --noEmit` passes for `server` and `ui` source. `pnpm check:module-boundaries` passes. ## Risks - Low. The grant change applies only to curated methods with agent grants and no OAuth. Organization, personal and OAuth flows keep their code paths. - The runner change makes plugin-transport tools visible to runner runs. Access still needs an install, a profile and a grant, and every call is re-authorized by the gateway. - Connections created before this fix have no agent grant. Connecting again (or "Finish setup") with the agent creates it. - No migration. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used 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 --- doc/connections/CONNECTOR-PLAYBOOK.md | 10 +- .../plugin-connector-agent-grant.test.ts | 301 ++++++++++++++++++ .../src/services/heartbeat/run-preparation.ts | 10 +- .../native-runtime/runtime-context.ts | 4 +- server/src/services/tool-access.ts | 77 ++++- .../tool-access/connections/agent-grant.ts | 112 +++++++ .../connections/ConnectionSetupFlow.tsx | 37 ++- ui/src/pages/apps/AppsConnect.test.tsx | 42 +++ 8 files changed, 573 insertions(+), 20 deletions(-) create mode 100644 server/src/__tests__/plugin-connector-agent-grant.test.ts create mode 100644 server/src/services/tool-access/connections/agent-grant.ts diff --git a/doc/connections/CONNECTOR-PLAYBOOK.md b/doc/connections/CONNECTOR-PLAYBOOK.md index cabbcdad193..853a75c89fe 100644 --- a/doc/connections/CONNECTOR-PLAYBOOK.md +++ b/doc/connections/CONNECTOR-PLAYBOOK.md @@ -186,7 +186,13 @@ catalog and health work may use a single active grant for that connection and company. An agent caller must use its own grant. Missing, revoked, or ambiguous agent authorizations fail before provider requests; they never fall back to a personal, organization, or connection-owned credential. Renaming or pausing the -connection must preserve the grant and its secret bindings. A later successful +connection must preserve the grant and its secret bindings. OAuth methods +create the agent grant in the callback. Methods without sign-in (`none` or +`api_key`) create it when connect names `subjectAgentId`, with the API key on +that grant; one connection serves exactly one agent, so connecting it for a +second agent is a conflict. Finish never creates agent grants: the grant still +gives no tools until finish or the installs API adds that agent's install. +A later successful catalog refresh clears an earlier connection-health error without new consent. An agent caller denied for lacking its own grant must not change shared health or the catalog, including when that agent has permission to manage the connection. @@ -1683,7 +1689,7 @@ Suggested PR verification block: | `oauthStrategy` | Managed broker strategy. New definitions use `paperclip_cloud_connector`; `paperclip_id_connector` is recognized only to require migration when an old grant expires. The protocols and provider clients are not interchangeable. Only valid for OAuth. | | `connectorProfile` | Managed connector capability/scope profile, required with `oauthStrategy`. | | `capabilityProfile` | User-facing read/write/mode grouping used for method selection. | -| `grantKinds` | Restricts identity to `organization` and/or `user`; omit for flexible methods. | +| `grantKinds` | Restricts identity to `organization`, `user` and/or `agent`; omit for flexible methods. An `agent` method connects for exactly one chosen agent. | | `whenToUse` | One sentence distinguishing this method from alternatives. | | `defaults.serverUrl` | Exact fixed endpoint. For discovery-capable OAuth, omit fixed auth endpoints. | | `defaults.serverUrlTemplate` | HTTPS endpoint with placeholders supplied by declared tenant/extension fields. Mutually exclusive with `serverUrl`. | diff --git a/server/src/__tests__/plugin-connector-agent-grant.test.ts b/server/src/__tests__/plugin-connector-agent-grant.test.ts new file mode 100644 index 00000000000..9f2c32e054a --- /dev/null +++ b/server/src/__tests__/plugin-connector-agent-grant.test.ts @@ -0,0 +1,301 @@ +/** + * A plugin connector method that declares agent grants and has no sign-in step + * (`auth: "none"` or `"api_key"`) must work like any per-agent connector when + * an operator connects it through the real routes: + * - connect for one agent creates that agent's grant (with the API key for + * `api_key`) but exposes no tools; + * - finish with that agent creates the install, and only that agent's + * gateway discovery lists the tools; + * - organization-grant methods keep their default organization grant; + * - a Paperclip Runner session (the run-scoped assigned-tool gateway) lists + * installed plugin-transport tools, like it does for MCP connections. + */ +import { randomUUID } from "node:crypto"; +import { mkdtemp, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { and, eq } from "drizzle-orm"; +import express from "express"; +import request from "supertest"; +import { afterAll, beforeAll, describe, expect, it, vi } from "vitest"; +import { + agents, companies, companyMemberships, connectionGrants, createDb, heartbeatRuns, issues, plugins, toolConnectionInstalls, toolConnections, +} from "@paperclipai/db"; +import { pluginAppSlug, pluginManifestV1Schema, type PaperclipPluginManifestV1 } from "@paperclipai/shared"; +import { toolAccessRoutes } from "../routes/tool-access.js"; +import { errorHandler } from "../middleware/index.js"; +import { createToolGatewayService } from "../services/tool-gateway.js"; +import { buildPaperclipRuntimeMcpServers } from "../services/heartbeat.js"; +import { createAssignedMcpTools } from "../services/native-runtime/assigned-mcp-tools.js"; +import { resolveNativeRuntimeMcpSnapshot } from "../services/native-runtime/runtime-context.js"; +import { setPluginConnectorWorkers } from "../services/plugin-connector-runtime.js"; +import type { PluginWorkerManager } from "../services/plugin-worker-manager.js"; +import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js"; + +const PLUGIN_KEY = "example.agent-grants"; +const NO_SIGN_IN = pluginAppSlug(PLUGIN_KEY, "open"); +const API_KEY = pluginAppSlug(PLUGIN_KEY, "keyed"); +const SHARED = pluginAppSlug(PLUGIN_KEY, "shared"); +const staticTools = { + kind: "static" as const, + list: [ + { name: "lookup", description: "Look up a record.", risk: "read" as const, parametersSchema: { type: "object" } }, + { name: "update_record", description: "Update a record.", risk: "write" as const, parametersSchema: { type: "object" } }, + ], +}; +const app = (slug: string, name: string, method: Record) => ({ + schemaVersion: 1, slug, name, description: `${name} records`, categories: ["developer"], + branding: { logoUrl: "/brands/apps/api-key-generic.svg" }, urlPatterns: [], + methods: [{ transport: "plugin", ownershipModes: ["customer"], whenToUse: "Use it.", guidanceMd: "Connect it.", + riskTier: "S1", tools: staticTools, ...method }], +}); +const manifest = pluginManifestV1Schema.parse({ + id: PLUGIN_KEY, apiVersion: 1, version: "1.0.0", displayName: "Agent grants", description: "Per-agent connectors", + author: "Tests", categories: ["connector"], capabilities: ["connectors.provide"], entrypoints: { worker: "worker.js" }, + apps: [ + app("open", "Open records", { key: "none", auth: "none", grantKinds: ["agent"] }), + app("keyed", "Keyed records", { + key: "api-key", auth: "api_key", grantKinds: ["agent"], + credentialFields: [{ key: "apiKey", label: "API key", type: "password", required: true, placeholder: "key", secret: true }], + }), + app("shared", "Shared records", { key: "none", auth: "none" }), + ], +}) as PaperclipPluginManifestV1; + +const support = await getEmbeddedPostgresTestSupport(); +(support.supported ? describe : describe.skip)("plugin connector with agent grants and no sign-in", () => { + let db: ReturnType; + let temp: Awaited>; + let keyDir: string; + const workerCalls: Array<{ method: string; params: any }> = []; + + beforeAll(async () => { + keyDir = await mkdtemp(join(tmpdir(), "plugin-agent-grant-secrets-")); + vi.stubEnv("PAPERCLIP_SECRETS_MASTER_KEY_FILE", join(keyDir, "key")); + vi.stubEnv("PAPERCLIP_API_URL", "http://127.0.0.1:3100"); + temp = await startEmbeddedPostgresTestDatabase("paperclip-plugin-agent-grant-"); + db = createDb(temp.connectionString); + await db.insert(plugins).values({ pluginKey: PLUGIN_KEY, packageName: `@test/${PLUGIN_KEY}`, version: "1.0.0", manifestJson: manifest, status: "ready" }); + setPluginConnectorWorkers({ + isRunning: () => true, + getWorker: () => ({ status: "running" }), + call: vi.fn(async (_id: string, method: string, params: any) => { + workerCalls.push({ method, params: structuredClone(params) }); + if (method === "executeTool") return { content: `ran ${params.toolName}` }; + throw new Error(`unexpected ${method}`); + }), + } as unknown as PluginWorkerManager); + }, 60_000); + afterAll(async () => { + setPluginConnectorWorkers(null); + await temp?.cleanup(); + vi.unstubAllEnvs(); + if (keyDir) await rm(keyDir, { recursive: true, force: true }); + }); + + async function setup() { + const [company] = await db.insert(companies).values({ name: "Agent grants", issuePrefix: `AG${randomUUID().slice(0, 6).toUpperCase()}` }).returning(); + await db.insert(companyMemberships).values({ companyId: company!.id, principalType: "user", principalId: "board-user", status: "active", membershipRole: "admin" }); + const [agentA, agentB] = await db.insert(agents).values([ + { companyId: company!.id, name: "Owner", role: "engineer", adapterType: "process" }, + { companyId: company!.id, name: "Other", role: "engineer", adapterType: "process" }, + ]).returning(); + const routes = express(); + routes.use(express.json()); + routes.use((req, _res, next) => { + req.actor = { type: "board", userId: "board-user", userName: "Board User", userEmail: null, isInstanceAdmin: true, source: "local_implicit" }; + next(); + }); + routes.use("/api", toolAccessRoutes(db, {})); + routes.use(errorHandler); + const gateway = createToolGatewayService(db, { toolActionSigningSecret: "plugin-agent-grant-signing" }); + const session = async (agentId: string) => { + const [issue] = await db.insert(issues).values({ companyId: company!.id, title: "Use records", assigneeAgentId: agentId }).returning(); + const [run] = await db.insert(heartbeatRuns).values({ companyId: company!.id, agentId, issueId: issue!.id, scopeKind: "issue", + invocationSource: "on_demand", status: "running", responsibleUserId: "board-user", contextSnapshot: { issueId: issue!.id } }).returning(); + runIds.set(agentId, run!.id); + return (await gateway.createSession({ companyId: company!.id, agentId, runId: run!.id, issueId: issue!.id })).token; + }; + const runIds = new Map(); + const tools = async (token: string) => + (await gateway.listToolsForSession(token)).filter((tool) => tool.providerType === "paperclip_plugin_connection"); + const tokenA = await session(agentA!.id); + const tokenB = await session(agentB!.id); + /** The tools a Paperclip Runner run sees: the run-scoped assigned-tool gateway built at run start. */ + const runnerTools = async (agent: typeof agentA) => { + const runId = runIds.get(agent!.id)!; + const snapshot = await resolveNativeRuntimeMcpSnapshot({ db, agent: agent!, runId }); + const servers = await buildPaperclipRuntimeMcpServers({ db, agent: agent!, runId, expectedAssignmentDigest: snapshot.digest }); + if (servers.length === 0) return { definitions: [] as Array<{ name: string }>, search: async () => [] as string[] }; + const assigned = await createAssignedMcpTools({ gateway, companyId: company!.id, + gatewayPublicId: servers[0]!.url.split("/").at(-1)!, bearerToken: servers[0]!.token }); + return { + definitions: assigned.definitions(), + search: async (query: string) => ((await assigned.execute({ tool: "paperclip_search_assigned_tools", arguments: { query } })) as { tools: Array<{ name: string }> }) + .tools.map((tool) => tool.name), + }; + }; + return { company: company!, agentA: agentA!, agentB: agentB!, routes, gateway, tools, runnerTools, tokenA, tokenB }; + } + + async function connectAndFinish(f: Awaited>, body: Record, access: unknown) { + const connected = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`).send(body); + expect(connected.status, JSON.stringify(connected.body)).toBe(201); + // Rule 2: a configured connection alone gives no agent any tool. + expect(await f.tools(f.tokenA)).toEqual([]); + expect(await f.tools(f.tokenB)).toEqual([]); + const connectionId = connected.body.connectionId as string; + const catalogIds = (connected.body.catalog as Array<{ id: string }>).map((entry) => entry.id); + expect(catalogIds).toHaveLength(2); + const finished = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/${connectionId}/finish`) + .send({ enabledCatalogEntryIds: catalogIds, askFirstCatalogEntryIds: [], access }); + expect(finished.status, JSON.stringify(finished.body)).toBe(200); + expect(finished.body.connection).toMatchObject({ status: "active", enabled: true }); + const grants = await db.select().from(connectionGrants).where(eq(connectionGrants.connectionId, connectionId)); + const installs = await db.select().from(toolConnectionInstalls).where(eq(toolConnectionInstalls.connectionId, connectionId)); + return { connectionId, connectBody: connected.body, grants, installs }; + } + + it("gives only the chosen agent the tools of a no-sign-in method", async () => { + const f = await setup(); + const result = await connectAndFinish(f, { galleryKey: NO_SIGN_IN, connectionMethodKey: "none", grantKind: "agent", subjectAgentId: f.agentA.id }, + { agentIds: [f.agentA.id] }); + expect(result.connectBody.connection).toMatchObject({ credentialPolicy: "per_agent" }); + expect(result.grants.map((grant) => ({ kind: grant.kind, subjectAgentId: grant.subjectAgentId, status: grant.status }))) + .toEqual([{ kind: "agent", subjectAgentId: f.agentA.id, status: "active" }]); + expect(result.installs.map((install) => [install.targetType, install.targetId])).toEqual([["agent", f.agentA.id]]); + expect((await f.tools(f.tokenA)).map((tool) => tool.upstreamToolName).sort()).toEqual(["lookup", "update_record"]); + expect(await f.tools(f.tokenB)).toEqual([]); + }); + + it("stores the API key on the chosen agent's grant and serves the tools only to that agent", async () => { + const f = await setup(); + const result = await connectAndFinish(f, { galleryKey: API_KEY, connectionMethodKey: "api-key", grantKind: "agent", subjectAgentId: f.agentA.id, + credentialValues: { "credentials.apiKey": "agent-key-1" } }, { agentIds: [f.agentA.id] }); + expect(result.grants).toHaveLength(1); + expect(result.grants[0]).toMatchObject({ kind: "agent", subjectAgentId: f.agentA.id, status: "active" }); + expect(result.grants[0]!.credentialSecretRefs.map((ref) => ref.configPath)).toEqual(["credentials.apiKey"]); + // The key belongs to the agent's grant, never to a shared connection credential. + expect(result.connectBody.connection.credentialSecretRefs ?? []).toEqual([]); + const toolsA = await f.tools(f.tokenA); + expect(toolsA.map((tool) => tool.upstreamToolName).sort()).toEqual(["lookup", "update_record"]); + expect(await f.tools(f.tokenB)).toEqual([]); + + const lookup = toolsA.find((tool) => tool.upstreamToolName === "lookup")!; + await f.gateway.executeTool({ sessionToken: f.tokenA, tool: lookup.name, parameters: {}, idempotencyKey: randomUUID() }); + expect(workerCalls.filter((call) => call.method === "executeTool").at(-1)!.params.runContext).toMatchObject({ + agentId: f.agentA.id, + connection: { id: result.connectionId, grantId: result.grants[0]!.id, credential: { kind: "api_key", value: "agent-key-1" } }, + }); + }); + + it("refuses a second agent's identity on the same connection and an agent grant without an agent", async () => { + const f = await setup(); + const missing = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: NO_SIGN_IN, connectionMethodKey: "none", grantKind: "agent" }); + expect(missing.status).toBe(400); + const connected = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: NO_SIGN_IN, connectionMethodKey: "none", grantKind: "agent", subjectAgentId: f.agentA.id }); + expect(connected.status).toBe(201); + const resumed = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: NO_SIGN_IN, connectionMethodKey: "none", resumeConnectionId: connected.body.connectionId, grantKind: "agent", subjectAgentId: f.agentB.id }); + expect(resumed.status).toBe(409); + const grants = await db.select().from(connectionGrants).where(and( + eq(connectionGrants.connectionId, connected.body.connectionId), eq(connectionGrants.kind, "agent"))); + expect(grants.map((grant) => grant.subjectAgentId)).toEqual([f.agentA.id]); + }); + + it("resumes an API-key draft for the same agent without asking for the key again", async () => { + const f = await setup(); + const connected = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: API_KEY, connectionMethodKey: "api-key", grantKind: "agent", subjectAgentId: f.agentA.id, + credentialValues: { "credentials.apiKey": "agent-key-2" } }); + expect(connected.status).toBe(201); + const resumed = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: API_KEY, connectionMethodKey: "api-key", resumeConnectionId: connected.body.connectionId }); + expect(resumed.status, JSON.stringify(resumed.body)).toBe(201); + const grants = await db.select().from(connectionGrants).where(eq(connectionGrants.connectionId, connected.body.connectionId)); + expect(grants).toHaveLength(1); + expect(grants[0]).toMatchObject({ kind: "agent", subjectAgentId: f.agentA.id, status: "active" }); + expect(grants[0]!.credentialSecretRefs.map((ref) => ref.configPath)).toEqual(["credentials.apiKey"]); + }); + + it("lets only one of two concurrent resumes claim a grant-less agent draft", async () => { + const f = await setup(); + const connected = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: NO_SIGN_IN, connectionMethodKey: "none", grantKind: "agent", subjectAgentId: f.agentA.id }); + expect(connected.status).toBe(201); + const connectionId = connected.body.connectionId as string; + // A draft saved before connect created agent grants has none. + await db.delete(connectionGrants).where(eq(connectionGrants.connectionId, connectionId)); + const resume = (agentId: string) => request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: NO_SIGN_IN, connectionMethodKey: "none", resumeConnectionId: connectionId, grantKind: "agent", subjectAgentId: agentId }); + const results = await Promise.all([resume(f.agentA.id), resume(f.agentB.id)]); + expect(results.filter((result) => result.status === 201)).toHaveLength(1); + const active = await db.select().from(connectionGrants).where(and( + eq(connectionGrants.connectionId, connectionId), eq(connectionGrants.status, "active"))); + expect(active).toHaveLength(1); + }); + + it("replaces a dedicated agent's API key on that agent's grant", async () => { + const f = await setup(); + const result = await connectAndFinish(f, { galleryKey: API_KEY, connectionMethodKey: "api-key", grantKind: "agent", subjectAgentId: f.agentA.id, + credentialValues: { "credentials.apiKey": "agent-key-old" } }, { agentIds: [f.agentA.id] }); + const replaced = await request(f.routes).post(`/api/tool-connections/${result.connectionId}/reconnect`) + .send({ credentialValues: { "credentials.apiKey": "agent-key-new" } }); + expect(replaced.status, JSON.stringify(replaced.body)).toBe(200); + const [connection] = await db.select().from(toolConnections).where(eq(toolConnections.id, result.connectionId)); + expect(connection!.credentialSecretRefs).toEqual([]); + const lookup = (await f.tools(f.tokenA)).find((tool) => tool.upstreamToolName === "lookup")!; + await f.gateway.executeTool({ sessionToken: f.tokenA, tool: lookup.name, parameters: {}, idempotencyKey: randomUUID() }); + expect(workerCalls.filter((call) => call.method === "executeTool").at(-1)!.params.runContext.connection.credential) + .toMatchObject({ value: "agent-key-new" }); + }); + + it("does not revive a removed agent identity for a connect that names no agent", async () => { + const f = await setup(); + const result = await connectAndFinish(f, { galleryKey: NO_SIGN_IN, connectionMethodKey: "none", grantKind: "agent", subjectAgentId: f.agentA.id }, + { agentIds: [f.agentA.id] }); + const removed = await request(f.routes).delete(`/api/tool-connections/${result.connectionId}`); + expect(removed.status, JSON.stringify(removed.body)).toBe(200); + const again = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: NO_SIGN_IN, connectionMethodKey: "none" }); + expect(again.status).toBe(400); + const active = await db.select().from(connectionGrants).where(and( + eq(connectionGrants.connectionId, result.connectionId), eq(connectionGrants.status, "active"))); + expect(active).toEqual([]); + expect(await f.tools(f.tokenA)).toEqual([]); + }); + + it("keeps the default organization grant for a method without agent grants", async () => { + const f = await setup(); + const result = await connectAndFinish(f, { galleryKey: SHARED, connectionMethodKey: "none" }, "all_agents"); + expect(result.connectBody.connection).toMatchObject({ credentialPolicy: "shared" }); + expect(result.grants.map((grant) => ({ kind: grant.kind, isDefault: grant.isDefault, status: grant.status }))) + .toEqual([{ kind: "organization", isDefault: true, status: "active" }]); + expect((await f.tools(f.tokenA)).map((tool) => tool.upstreamToolName).sort()).toEqual(["lookup", "update_record"]); + expect((await f.tools(f.tokenB)).map((tool) => tool.upstreamToolName).sort()).toEqual(["lookup", "update_record"]); + }); + + it("lists installed plugin-transport tools in a Paperclip Runner session", async () => { + const f = await setup(); + expect((await f.runnerTools(f.agentA)).definitions).toEqual([]); + await connectAndFinish(f, { galleryKey: SHARED, connectionMethodKey: "none" }, { agentIds: [f.agentA.id] }); + const runnerA = await f.runnerTools(f.agentA); + expect(runnerA.definitions).toHaveLength(2); + // Search by the tool's manifest name finds the gateway tool. + expect(await runnerA.search("update_record")).toHaveLength(1); + expect((await f.runnerTools(f.agentB)).definitions).toEqual([]); + }); + + it("keeps plugin-transport tools in a Paperclip Runner session after a stale health error", async () => { + const f = await setup(); + const { connectionId } = await connectAndFinish(f, { galleryKey: SHARED, connectionMethodKey: "none" }, { agentIds: [f.agentA.id] }); + // A health check that ran while the worker was down saved an error; the + // worker is running again, so each call can succeed. + await db.update(toolConnections).set({ healthStatus: "error", healthMessage: "Plugin worker unavailable" }) + .where(eq(toolConnections.id, connectionId)); + expect(await f.tools(f.tokenA)).toHaveLength(2); + expect((await f.runnerTools(f.agentA)).definitions).toHaveLength(2); + }); +}); diff --git a/server/src/services/heartbeat/run-preparation.ts b/server/src/services/heartbeat/run-preparation.ts index 796237196c7..768e4912eb1 100644 --- a/server/src/services/heartbeat/run-preparation.ts +++ b/server/src/services/heartbeat/run-preparation.ts @@ -967,7 +967,7 @@ export async function buildPaperclipRuntimeMcpServers(input: { .filter( (connection) => (connection.transport === "mcp_remote" || - connection.transport === "local_stdio" || isBrowserUseConnection(connection) || restConnectorFor(connection)) && + connection.transport === "local_stdio" || connection.transport === "plugin" || isBrowserUseConnection(connection) || restConnectorFor(connection)) && !allInstalledConnectionIds.has(connection.id), ) .map(({ id, name }) => ({ id, name })) @@ -991,9 +991,15 @@ export async function buildPaperclipRuntimeMcpServers(input: { (connection.config?.sourceTemplateKey === "github" || connection.transportConfig?.sourceTemplateKey === "github")) || connection.credentialPolicy === "per_user" || + // A plugin connection's health mostly reflects its worker, which the + // host restarts; calls fail retryably while it is down. Match the + // gateway, which keeps these tools discoverable. + connection.transport === "plugin" || !isToolConnectionAttentionHealth(connection.healthStatus)) && + // Keep this transport list equal to the native runtime assignment + // digest in native-runtime/runtime-context.ts. (connection.transport === "mcp_remote" || - connection.transport === "local_stdio" || isBrowserUseConnection(connection) || restConnectorFor(connection) || githubBotConnectionIds.has(connection.id) || spekoConnectionIds.has(connection.id)), + connection.transport === "local_stdio" || connection.transport === "plugin" || isBrowserUseConnection(connection) || restConnectorFor(connection) || githubBotConnectionIds.has(connection.id) || spekoConnectionIds.has(connection.id)), ); const assignedConnectionIds = new Set( assignedConnections.map((connection) => connection.id), diff --git a/server/src/services/native-runtime/runtime-context.ts b/server/src/services/native-runtime/runtime-context.ts index 74b22dac3b2..044130f2c96 100644 --- a/server/src/services/native-runtime/runtime-context.ts +++ b/server/src/services/native-runtime/runtime-context.ts @@ -377,8 +377,10 @@ export async function resolveNativeRuntimeMcpSnapshot(input: { db: Db; agent: Pi && connection.enabled && (Boolean(runIdentity?.activeIdentityContextId) && (connection.config?.sourceTemplateKey === "github" || connection.transportConfig?.sourceTemplateKey === "github") || connection.credentialPolicy === "per_user" + || connection.transport === "plugin" || !isToolConnectionAttentionHealth(connection.healthStatus)) - && (["mcp_remote", "local_stdio"].includes(connection.transport) || isBrowserUseConnection(connection) || restConnectorFor(connection) || githubBotConnectionIds.has(connection.id) || spekoConnectionIds.has(connection.id)) + // Keep this transport list equal to buildPaperclipRuntimeMcpServers. + && (["mcp_remote", "local_stdio", "plugin"].includes(connection.transport) || isBrowserUseConnection(connection) || restConnectorFor(connection) || githubBotConnectionIds.has(connection.id) || spekoConnectionIds.has(connection.id)) ).map((connection) => connection.id)); const assignment = { version: 1, diff --git a/server/src/services/tool-access.ts b/server/src/services/tool-access.ts index f08fa43240a..d4b5bbb56d0 100644 --- a/server/src/services/tool-access.ts +++ b/server/src/services/tool-access.ts @@ -29,6 +29,7 @@ import { toApplication } from "./tool-access/applications/projection.js"; import { groupedActions } from "./tool-access/catalog/action-summary.js"; import { createConnectionSetupPolicy, assertSupportedConnection } from "./tool-access/connections/setup-policy.js"; import { createOrganizationGrantStore } from "./tool-access/connections/organization-grant.js"; +import { createAgentGrantStore } from "./tool-access/connections/agent-grant.js"; import { createPersonalConnectionIdentity } from "./tool-access/connections/personal-identity.js"; import { createOAuthStateStore } from "./tool-access/oauth/state.js"; import { createOAuthCatalogCompletion } from "./tool-access/oauth/catalog-completion.js"; @@ -750,6 +751,7 @@ export function toolAccessService( const { resolveInstalledConnectionsForAgent, listConnectionInstalls } = connectionInstalls; const audit = createToolAccessAudit(db); const ensureDefaultOrganizationGrant = createOrganizationGrantStore(db); + const agentGrants = createAgentGrantStore(db); const { mintConnectionTokenForAgent, loadBrokerRunContext } = createConnectionTokenBroker(db, { now, secrets, policySvc, audit, getConnectionRow, ensureDefaultOrganizationGrant }); const profileService = createToolProfileService(db, now); const profileDetails = profileService.getProfile; @@ -2075,8 +2077,28 @@ export function toolAccessService( `${galleryEntry?.name ?? "This app"} supports only ${method.grantKinds.join(" or ")} credentials`, ); } - const dedicatedAgentId = + // OAuth names the agent in its state and the callback writes that agent's + // grant. A curated method without sign-in (`none` or `api_key`) has no + // callback, so connect itself must create the agent's grant. + const createsAgentGrantAtConnect = Boolean( + requestedGrantKind === "agent" && galleryEntry && method && method.auth !== "oauth" && !remoteMcpConnector, + ); + let dedicatedAgentId = requestedGrantKind === "agent" ? (input.subjectAgentId ?? null) : null; + if (createsAgentGrantAtConnect && !dedicatedAgentId) { + // Continuing the same identity (resume or reconnect) without naming the + // agent keeps its one active agent. A fresh connect that only recovered + // an archived row is a new identity decision and must name the agent. + const retainedAgentGrant = retainsIdentity && retainedConnection + ? await agentGrants.activeAgentGrant(companyId, retainedConnection.id) + : null; + dedicatedAgentId = retainedAgentGrant?.subjectAgentId ?? null; + if (!dedicatedAgentId) { + throw badRequest("Choose the agent that uses this connection", { + code: "connection_subject_agent_required", + }); + } + } if (dedicatedAgentId) { const [subjectAgent] = await db .select({ id: agents.id }) @@ -2087,7 +2109,7 @@ export function toolAccessService( .limit(1); if (!subjectAgent) throw badRequest( - "Dedicated GitHub identity requires an agent in this company", + "A dedicated agent identity requires an agent in this company", ); } const credentialSource: ToolConnectionCredentialSource = @@ -2393,8 +2415,22 @@ export function toolAccessService( retainedMethodKey === method?.key && (!remoteMcpConnector || (baseConfig.url === retainedConfig.url && genericAuthKind === retainedConnection.authKind)), ); + // A dedicated agent's API key lives on its grant, not on the connection. + const [retainedAgentGrant] = canRetainCredentialMaterial && createsAgentGrantAtConnect && retainedConnection && dedicatedAgentId + ? await db + .select({ credentialSecretRefs: connectionGrants.credentialSecretRefs }) + .from(connectionGrants) + .where(and( + eq(connectionGrants.companyId, companyId), + eq(connectionGrants.connectionId, retainedConnection.id), + eq(connectionGrants.kind, "agent"), + eq(connectionGrants.subjectAgentId, dedicatedAgentId), + )) + .limit(1) + : []; const retainedCredentialSecretRefs = canRetainCredentialMaterial ? (retainedPersonalIdentity?.grant?.credentialSecretRefs ?? + retainedAgentGrant?.credentialSecretRefs ?? retainedConnection?.credentialSecretRefs ?? []) : []; @@ -2803,6 +2839,19 @@ export function toolAccessService( } else if (dedicatedAgentId) { // Managed OAuth creates the credential-bearing grant in the callback. // Keep the connection free of organization secrets from the outset. + // Without sign-in, the agent's grant is written here, carrying the + // API key when the method has one. The grant alone gives no tools: + // the agent still needs an install of the active connection. + if (createsAgentGrantAtConnect) { + const mutation = await agentGrants.upsertConnectAgentGrant({ + companyId, + connectionId: connectionRow.id, + subjectAgentId: dedicatedAgentId, + credentialSecretRefs, + actor, + }); + if (revivedConnectionPrevious) revivedGrantMutation = mutation; + } } else { const organizationGrant = await ensureDefaultOrganizationGrant( connectionRow, @@ -3783,8 +3832,20 @@ export function toolAccessService( undefined, actor, ); + // A dedicated agent's key lives on its grant, which is what the gateway + // reads for a per-agent connection. Rotate it there. + const agentGrant = connection.credentialPolicy === "per_agent" + ? await agentGrants.activeAgentGrant(companyId, connection.id) + : null; + if (connection.credentialPolicy === "per_agent" && !agentGrant) { + throw conflict("This connection has no agent to update. Connect it again and choose its agent.", { + code: "connection_subject_agent_required", + }); + } + const grantIdentity = Boolean(personalIdentity || agentGrant); const credentialSecretRefs = [ ...(personalIdentity?.grant?.credentialSecretRefs ?? + agentGrant?.credentialSecretRefs ?? connection.credentialSecretRefs), ]; const credentialRefs: McpConnectionCredentialRef[] = [ @@ -3866,13 +3927,19 @@ export function toolAccessService( }); } } + if (agentGrant) { + await tx + .update(connectionGrants) + .set({ credentialSecretRefs, updatedAt }) + .where(eq(connectionGrants.id, agentGrant.id)); + } const [nextConnection] = await tx .update(toolConnections) .set({ credentialRefs, - // Personal reconnect rotates the existing user's grant. The + // Personal and agent reconnects rotate that identity's grant. The // connection-level organization slot stays exactly as it was. - credentialSecretRefs: personalIdentity + credentialSecretRefs: grantIdentity ? connection.credentialSecretRefs : credentialSecretRefs, lastError: null, @@ -3881,7 +3948,7 @@ export function toolAccessService( .where(eq(toolConnections.id, connection.id)) .returning(); await syncConnectionCredentialBindings(tx, nextConnection, - personalIdentity ? credentialSecretRefs : []); + grantIdentity ? credentialSecretRefs : []); return nextConnection; }); const health = await checkConnectionHealth(updated.id, actor); diff --git a/server/src/services/tool-access/connections/agent-grant.ts b/server/src/services/tool-access/connections/agent-grant.ts new file mode 100644 index 00000000000..67e6262a824 --- /dev/null +++ b/server/src/services/tool-access/connections/agent-grant.ts @@ -0,0 +1,112 @@ +import { and, eq } from "drizzle-orm"; +import type { Db } from "@paperclipai/db"; +import { connectionGrants, toolAccessAuditEvents, toolConnections } from "@paperclipai/db"; +import type { CreateToolConnection } from "@paperclipai/shared"; +import { conflict } from "../../../errors.js"; +import { connectionActorUserId } from "../actor.js"; +import type { ActorInfo } from "../types.js"; + +type ConnectionGrant = typeof connectionGrants.$inferSelect; + +/** + * Dedicated-agent identities. A per-agent connection serves exactly one + * agent: its credential lives on that agent's grant, never on the connection. + * OAuth methods write the grant in their callback; methods without sign-in + * write it here when connect names the agent. + */ +export function createAgentGrantStore(db: Db) { + /** Upsert the one active agent grant; a grant for another agent is a conflict. */ + async function upsertConnectAgentGrant(input: { + companyId: string; + connectionId: string; + subjectAgentId: string; + credentialSecretRefs: CreateToolConnection["credentialSecretRefs"]; + actor?: ActorInfo; + }): Promise<{ previous: ConnectionGrant | null; current: ConnectionGrant }> { + return db.transaction(async (tx) => { + // Lock the connection first: with no grant rows yet, locking grants + // alone would let two concurrent connects each add a different agent. + await tx + .select({ id: toolConnections.id }) + .from(toolConnections) + .where(and(eq(toolConnections.id, input.connectionId), eq(toolConnections.companyId, input.companyId))) + .for("update"); + const grants = await tx + .select() + .from(connectionGrants) + .where(and( + eq(connectionGrants.companyId, input.companyId), + eq(connectionGrants.connectionId, input.connectionId), + eq(connectionGrants.kind, "agent"), + )) + .for("update"); + if (grants.some((grant) => grant.status === "active" && grant.subjectAgentId !== input.subjectAgentId)) { + throw conflict( + "This connection already belongs to another agent. Add a separate connection for this agent.", + { code: "connection_agent_identity_in_use" }, + ); + } + const previous = grants.find((grant) => grant.subjectAgentId === input.subjectAgentId) ?? null; + const [current] = previous + ? await tx + .update(connectionGrants) + .set({ + credentialSecretRefs: input.credentialSecretRefs, + status: "active", + revokedAt: null, + revokedByAgentId: null, + revokedByUserId: null, + updatedAt: new Date(), + }) + .where(eq(connectionGrants.id, previous.id)) + .returning() + : await tx + .insert(connectionGrants) + .values({ + companyId: input.companyId, + connectionId: input.connectionId, + kind: "agent", + subjectAgentId: input.subjectAgentId, + credentialSecretRefs: input.credentialSecretRefs, + status: "active", + isDefault: false, + createdByAgentId: input.actor?.actorType === "agent" ? (input.actor.actorId ?? null) : null, + createdByUserId: connectionActorUserId(input.actor), + }) + .returning(); + if (!current) throw new Error("Failed to save the agent connection grant"); + await tx.insert(toolAccessAuditEvents).values({ + companyId: input.companyId, + connectionId: input.connectionId, + actorType: input.actor?.actorType ?? "system", + actorId: input.actor?.actorId ?? null, + action: previous ? "connection_grant.updated" : "connection_grant.created", + outcome: "success", + reasonCode: previous ? "agent_identity_reconnected" : "agent_identity_created", + details: { + kind: "agent", + subjectAgentId: input.subjectAgentId, + credentialSecretRefCount: input.credentialSecretRefs.length, + }, + }); + return { previous, current }; + }); + } + + /** The connection's single active agent grant, or null when there is none or more than one. */ + async function activeAgentGrant(companyId: string, connectionId: string): Promise { + const grants = await db + .select() + .from(connectionGrants) + .where(and( + eq(connectionGrants.companyId, companyId), + eq(connectionGrants.connectionId, connectionId), + eq(connectionGrants.kind, "agent"), + eq(connectionGrants.status, "active"), + )) + .limit(2); + return grants.length === 1 ? grants[0]! : null; + } + + return { upsertConnectAgentGrant, activeAgentGrant }; +} diff --git a/ui/src/features/connections/ConnectionSetupFlow.tsx b/ui/src/features/connections/ConnectionSetupFlow.tsx index 0df8d032037..3df55a4998c 100644 --- a/ui/src/features/connections/ConnectionSetupFlow.tsx +++ b/ui/src/features/connections/ConnectionSetupFlow.tsx @@ -379,7 +379,8 @@ function defaultGrantKindFor(method: ConnectionMethodDef | null, preferPersonal } function defaultInstallChoiceFor(method: ConnectionMethodDef | null, requestedAgentId?: string): "specific" | "all" { - return requestedAgentId || method?.ai?.provider === "github" ? "specific" : "all"; + // A dedicated agent identity belongs to exactly one chosen agent. + return requestedAgentId || method?.ai?.provider === "github" || defaultGrantKindFor(method) === "agent" ? "specific" : "all"; } function configuredAgentIdentity(connection: ToolConnection): string | undefined { @@ -1467,6 +1468,11 @@ function StandardConnectionSetupFlow({ }; const effectiveGrantKind = fixedGrantKind ?? grantKind; + // A dedicated agent identity is never "all agents": keep the picker on so + // the connect request can name its one agent. + useEffect(() => { + if (effectiveGrantKind === "agent" && installChoice !== "specific") setInstallChoice("specific"); + }, [effectiveGrantKind, installChoice]); // A connected result (from the link probe or machine sign-in) goes straight to // review with every discovered action enabled by default. function acceptConnectedResult(result: ConnectToolAppResult) { @@ -1959,7 +1965,7 @@ function StandardConnectionSetupFlow({ // The Access step asks one question about agent reach, so profile access // and installs are committed to the same target set instead of drifting // apart behind two separate wizard screens. - const selection: AppAccessSelection = installChoice === "all" + const selection: AppAccessSelection = installChoice === "all" && effectiveGrantKind !== "agent" ? "all_agents" : { agentIds: Array.from(installAgentIds) }; const finished = await toolsApi.finishApp(selectedCompanyId!, connected.connectionId, { @@ -2223,13 +2229,17 @@ function StandardConnectionSetupFlow({ : "api_key"; // PAP-659 C0: the resolved default is stated, not asked. `Change` opens the // same controls the deleted Access step owned, inline and never blocking. + // Reconnecting a signed-in account keeps its agent; any other dedicated + // agent identity must name exactly one agent before it can connect. + const preservesAgentAccess = Boolean((automaticOAuthEntry && (resumableOAuthConnection || reconnectConnection)) || reconnectConnection?.connectionPurpose === "ai"); + const dedicatedAgentMissing = effectiveGrantKind === "agent" && !requestedAgentId && !preservesAgentAccess && installAgentIds.size !== 1; const renderConnectionDefaults = step === "key" ? ( (extra?: ReactNode, forceOpen?: boolean) => ( <> {entry && instructionTemplate && instructionValue &&
setInstructionDraft({ slug: entry.slug, value })} disabled={connectMutation.isPending || oauthStartMutation.isPending} />
} @@ -2698,7 +2708,7 @@ function StandardConnectionSetupFlow({ ) : step === "key" && entry && credentialStep !== undefined ? credentialStep : step === "key" && entry ? ( agent.id === lockedAgentId)?.name ?? "the requesting agent" : null; - const identityHeading = githubIdentity ? "Connect GitHub as" : "Which humans can use this credential?"; + const identityHeading = githubIdentity + ? "Connect GitHub as" + : allowedGrantKinds.length === 1 && allowedGrantKinds[0] === "agent" + ? "Who this connection acts as" + : "Which humans can use this credential?"; const agentAccessHeading = grantKind === "agent" - ? "Which agent owns this GitHub account?" + ? githubIdentity ? "Which agent owns this GitHub account?" : "Which agent uses this connection?" : githubIdentity && grantKind === "user" ? "Which agents may use your GitHub when you’re responsible?" : githubIdentity @@ -4292,7 +4307,7 @@ export function AccessStepContent({ ]} /> )} - {!preserveAgentAccess && !lockedAgentId && installChoice === "specific" ? ( + {!preserveAgentAccess && !lockedAgentId && (installChoice === "specific" || grantKind === "agent") ? (
{ - const identity = input.authKind === "none" + const identity = input.authKind === "none" && input.grantKind !== "agent" ? "No identity required" : input.grantKind === "user" ? "Your identity" diff --git a/ui/src/pages/apps/AppsConnect.test.tsx b/ui/src/pages/apps/AppsConnect.test.tsx index 47038ea83c8..d0800e4c4ff 100644 --- a/ui/src/pages/apps/AppsConnect.test.tsx +++ b/ui/src/pages/apps/AppsConnect.test.tsx @@ -487,6 +487,48 @@ describe("AppsConnect — Connect with a link (M4 frame)", () => { } }); + it.each([ + { auth: "none" as const, credentialValues: {} }, + { auth: "api_key" as const, credentialValues: { "credentials.apiKey": "records-key" } }, + ])("asks which one agent uses a plugin connector with agent grants ($auth)", async ({ auth, credentialValues }) => { + const app = pluginAppDefinition("example.records", { + schemaVersion: 1, slug: "records", name: "Records", description: "Look up records", categories: ["data"], + branding: { logoUrl: "/brands/apps/api-key-generic.svg" }, urlPatterns: [], + methods: [{ key: "agent", label: "Agent", transport: "plugin", auth, grantKinds: ["agent"], ownershipModes: ["customer"], + whenToUse: "One agent uses it.", guidanceMd: "Pick the agent.", riskTier: "S1", + ...(auth === "api_key" + ? { credentialFields: [{ key: "apiKey", label: "API key", type: "password" as const, required: true, placeholder: "key", secret: true }] } + : {}), + tools: { kind: "static", list: [{ name: "lookup", risk: "read", parametersSchema: { type: "object" } }] } }], + }); + setPluginAppDefinitions([app]); + try { + listGalleryMock.mockResolvedValue({ apps: [app] }); + await render(undefined, false, ); + // The stated default must not promise every agent, and the picker is + // already open because the connection needs its one agent. + expect(container.textContent).not.toContain("available to all agents"); + expect(container.textContent).toContain("Which agent uses this connection?"); + expect(container.textContent).not.toContain("GitHub"); + expect(container.textContent).not.toContain("No identity required"); + expect(buttonByText("Connect")?.disabled).toBe(true); + const key = container.querySelector('input[type="password"]'); + if (auth === "api_key") await act(async () => setInputValue(key!, "records-key")); + await act(async () => buttonByText("Select agents")!.click()); + await flushReact(); + await act(async () => document.body.querySelector('[aria-label="Allow Ada"]')!.click()); + await flushReact(); + expect(container.textContent).toContain("available only to the chosen agent"); + await act(async () => buttonByText("Connect")?.click()); + await flushReact(); + expect(connectAppMock).toHaveBeenCalledWith("company-1", expect.objectContaining({ galleryKey: app.slug, + connectionMethodKey: "agent", grantKind: "agent", subjectAgentId: "agent-1", + ...(auth === "api_key" ? { credentialValues } : {}) })); + } finally { + setPluginAppDefinitions([]); + } + }); + it("opens the saved AI sign-in and reuses a completed account", async () => { mockSearch.value = "aiLogin=saved-login"; const setup = vi.spyOn(aiConnectionsApi, "loginSetup").mockResolvedValue({