mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +01:00
fix(connections): show the setup card unless the person asked to set up the connection (#21400)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents find and request app connections with `connections_search` and `connection_request` > - For one unconnected match, the search told the agent "The user asked to connect" and said to configure the connection with `call_api` > - That text was given for every search, also when the person only asked a question or asked for app data > - The agent then created a draft connection itself and sent an absolute `http://127.0.0.1:<port>` link, and the person got no setup card to accept or decline > - This pull request gives the configure instruction only when the person's own message asks to set the connection up, and makes the agent's sign-in handoff link a relative app route > - The benefit is that a question or a data request shows the setup card, and setup links open on the host the person uses ## Linked Issues or Issue Description **What happened?** In chat eval cohort 12 (OpenCode with DeepSeek V4.1 Flash), the person wrote "Read my Notion and tell me the latest on the launch". `connections_search("Notion")` returned one result with the instruction "The user asked to connect. If method.management.allowed, use search_api/call_api ... to configure it". The agent called `POST tools/apps/connect` twice and replied with `http://127.0.0.1:<port>/COM/apps/connect?resume=...`. No setup card was shown, so the person could not decline. The same happened for "What is the easiest way to connect Notion here?". **Expected behavior** When the person asks about an app or needs its data, the agent shows the setup card (`connection_request`) and answers in plain words. The agent configures a connection itself only when the person asks for that setup. Links the agent gives are relative app routes. **Steps to reproduce** 1. Have no Notion connection. 2. In chat, write "Read my Notion and tell me the latest on the launch". 3. See that the agent creates a draft connection and links an absolute URL, with no setup card. ## What Changed - `server/src/services/connection-intents.ts`: for a single unconnected tool match, read the latest human message on the task. Give the configure instruction only when its first clause opens with a setup verb and names the matched app ("Connect Notion, then ...", "Can you set up Notion?"). "Connect Slack, then read my Notion" does not count for Notion. Otherwise tell the agent not to create a connection or draft. For a setup question, the agent answers in plain words and links the catalog setup page `/<prefix>/apps/connect?source=<app>`, because `connection_request` ends the turn before any answer text is shown. For a data request, the agent calls `connection_request` to show the setup card. A saved custom connection always uses the card. The check is conservative: a miss never configures anything. - `server/src/services/tool-access/oauth/authorization-start.ts`: the agent handoff link (`authorizationUrl`, also `requiredUserAction.setupPath`) is now a relative app route, not built from the server's redirect origin. - Tests: a red/green service test for the three messages, and the handoff test now requires a relative link. ## Verification - `cd server && npx vitest run src/__tests__/connection-intents-service.test.ts -t "configure a single match"`: passes for a data request, a setup question, a mixed-app request and an explicit setup request. With the old `connection-intents.ts` it fails (`expected 'The user asked to connect. ...' to contain 'connection_request with service notion'`). - `cd server && npx vitest run src/__tests__/connection-management.integration.test.ts -t "generic app authentication"`: passes. - A narrow paid eval run of `connection-setup.notion-declined` and `connection-setup.choose-provider` follows on this branch. ## Risks - A person who asks for setup with other words ("I'd like Notion hooked in") now gets the setup card instead of agent-side configuration. The card still completes the setup. - One small indexed read of the latest human message per single-result search. There is no change to agent boot or time to first token. ## Model Used - Claude, claude-opus-5-5, with tool use and code execution in Claude Code. ## 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 - [x] All Paperclip CI gates are green - [x] 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
e40a16e5c5
commit
b0e99dfcfa
4 files changed
+74
-12
No files matched your search
@@ -1,7 +1,7 @@
|
||||
import { subscribeDeliveryWork } from "../services/delivery-work-notifications.js";
|
||||
import { DELIVERY_QUEUES } from "../services/delivery-work-notifications.js";
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { and, eq, sql } from "drizzle-orm";
|
||||
import { and, eq, inArray, sql } from "drizzle-orm";
|
||||
import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
agents,
|
||||
@@ -203,6 +203,33 @@ describeEmbeddedPostgres("connectionIntentService", () => {
|
||||
expect(serialized).not.toContain(claims.sub);
|
||||
});
|
||||
|
||||
it("tells the agent to configure a single match only when the person asked to set it up", async () => {
|
||||
const [run] = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, runId));
|
||||
const issueId = String(run!.contextSnapshot?.issueId);
|
||||
const say = (body: string) => db.insert(issueComments).values({
|
||||
companyId: claims.company_id, issueId, authorUserId: "responsible-user", body,
|
||||
createdAt: new Date(Date.now() + 1000),
|
||||
}).returning().then(rows => rows[0]!);
|
||||
const said: string[] = [];
|
||||
try {
|
||||
for (const body of ["Read my Notion and tell me the latest on the launch.", "What is the easiest way to connect Notion here?",
|
||||
"Connect Slack, then read my Notion."]) {
|
||||
said.push((await say(body)).id);
|
||||
const result = await connectionIntentService(db).search(claims, "Notion");
|
||||
expect(result.results).toEqual([expect.objectContaining({ service: "notion", state: "available" })]);
|
||||
expect(result.instruction).not.toMatch(/^The person asked you to set up/);
|
||||
expect(result.instruction).toContain("call connection_request with service notion");
|
||||
expect(result.instruction).toMatch(/\[Connect Notion\]\(\/[A-Z0-9]+\/apps\/connect\?source=notion\)/);
|
||||
expect(result.instruction).toContain("Do not create a connection or a saved draft yourself");
|
||||
}
|
||||
said.push((await say("Connect Notion, then continue the launch summary here.")).id);
|
||||
const requested = await connectionIntentService(db).search(claims, "Notion");
|
||||
expect(requested.instruction).toMatch(/^The person asked you to set up this connection\. If method\.management\.allowed, use search_api\/call_api/);
|
||||
} finally {
|
||||
await db.delete(issueComments).where(inArray(issueComments.id, said));
|
||||
}
|
||||
});
|
||||
|
||||
it("discovers GitHub review bots independently from chat connectors", async () => {
|
||||
const settings = instanceSettingsService(db);
|
||||
const previous = await settings.getExperimental();
|
||||
|
||||
@@ -895,7 +895,10 @@ describe("connection management with production default agents", () => {
|
||||
expect(started, JSON.stringify(started)).toMatchObject({ status: 200, body: {
|
||||
expiresAt: null, requiredUserAction: { userId: f.userId, resource: { id: created.body.id } },
|
||||
} });
|
||||
expect(new URL(started.body.authorizationUrl).searchParams.get("resume")).toBe(created.body.id);
|
||||
// The agent links this in chat, so it is a relative app route, never the server's own origin.
|
||||
expect(started.body.authorizationUrl).toMatch(/^\/[^/]/);
|
||||
expect(started.body.requiredUserAction.setupPath).toBe(started.body.authorizationUrl);
|
||||
expect(new URL(started.body.authorizationUrl, "https://paperclip.example").searchParams.get("resume")).toBe(created.body.id);
|
||||
expect(await f.request("POST", path, { asCurrentUser: true })).toMatchObject({ status: 200, body: { authorizationUrl: started.body.authorizationUrl } });
|
||||
expect(await server.db.select().from(toolOauthStates).where(eq(toolOauthStates.connectionId, created.body.id))).toHaveLength(0);
|
||||
});
|
||||
|
||||
@@ -133,6 +133,10 @@ function availableToolConnectionMethods(
|
||||
// Large enough for first-party catalogs such as GitHub's; aggregator catalogs
|
||||
// stay bounded and still report their total.
|
||||
const MAX_SCOPED_REQUEST_TOOL_NAMES = 100;
|
||||
// A message that opens with a setup verb, such as "Connect Notion" or "Can you
|
||||
// set up Slack?". Questions and data requests ("What is the easiest way to
|
||||
// connect Notion?", "Read my Notion") do not match and get the setup card.
|
||||
const SETUP_REQUEST_PATTERN = /^(?:please\s+)?(?:(?:can|could|would|will)\s+you\s+(?:please\s+)?)?(?:connect|reconnect|set\s*up|configure|install|link|hook\s+up)\b/i;
|
||||
|
||||
/** Tells an agent outside a connection's grant how to request scoped access to it. */
|
||||
function scopedToolRequestGuidance(connectionId: string, catalog: ReadonlyArray<{ toolName: string }>) {
|
||||
@@ -640,9 +644,13 @@ export function connectionIntentService(db: Db) {
|
||||
const ranked = () => [...candidates, ...yieldedRoutes].sort((a, b) => b.score - a.score || a.item.name.localeCompare(b.item.name))
|
||||
.slice(0, 40).map(({ item }) => item);
|
||||
// Aggregator routes need a recorded provider choice before connection_request.
|
||||
const rankedResult = (suggestions = false) => {
|
||||
const rankedResult = async (suggestions = false) => {
|
||||
const results = ranked();
|
||||
return results.some(item => item.source === "aggregator") ? discoverySuggestions(results) : directSearchResult(query, results, company.prefix, suggestions);
|
||||
if (results.some(item => item.source === "aggregator")) return discoverySuggestions(results);
|
||||
// Only a single unconnected tool result can tell the agent to configure it.
|
||||
const setupRequested = !suggestions && results.length === 1
|
||||
&& await latestHumanMessageRequestsSetup(run.companyId, issue.id, run.responsibleUserId!, results[0]!);
|
||||
return directSearchResult(query, results, company.prefix, suggestions, setupRequested);
|
||||
};
|
||||
const targetService = publicService?.slug ?? (indexedMatches.length === 1 ? indexedMatches[0]!.slug : normalizeConnectionQuery(serviceQuery).replaceAll(" ", "-"));
|
||||
// Indexed-only app labels must be identical when requests re-search the slug.
|
||||
@@ -753,7 +761,7 @@ export function connectionIntentService(db: Db) {
|
||||
}
|
||||
}
|
||||
|
||||
function directSearchResult(query: string, results: ConnectionSearchResultItem[], prefix: string, suggestions = false): ConnectionsSearchResult {
|
||||
function directSearchResult(query: string, results: ConnectionSearchResultItem[], prefix: string, suggestions = false, setupRequested = false): ConnectionsSearchResult {
|
||||
const ownServer = `the person adds it as their own MCP server on [Connect your own MCP server](/${prefix}/apps/byo): they enter the URL and type any API key into that page's secure field themselves. `
|
||||
+ "An agent cannot enter the key. Do not create the connection yourself, ask for the key in chat or search for another route; link that page and reply.";
|
||||
return { version: 1, query, results, instruction: !results.length
|
||||
@@ -771,7 +779,31 @@ export function connectionIntentService(db: Db) {
|
||||
: results[0]!.methods.every(method => method.purpose && method.purpose !== "tool")
|
||||
? "Choose the method relevant to the task using its purpose and label. If method.management.allowed, configure through search_api/call_api using nextApiOperation. Hand off only required human authentication or consent at the saved setupPath. These methods do not use the tool connection_request card. Do not claim tools or an inbox are ready before setup finishes."
|
||||
: results[0]!.state === "ready" ? "Use the installed connection. Do not create another connection request."
|
||||
: "The user asked to connect. If method.management.allowed, use search_api/call_api with nextApiOperation to configure it. Reuse a saved draft. Use connection_request only for required human input or access. Do not ask a generic confirmation or silently change policy to bypass a failed tool call." };
|
||||
: setupRequested
|
||||
? "The person asked you to set up this connection. If method.management.allowed, use search_api/call_api with nextApiOperation to configure it. Reuse a saved draft. Use connection_request only for required human input or access. Do not ask a generic confirmation or silently change policy to bypass a failed tool call."
|
||||
: results[0]!.service.startsWith("connection:")
|
||||
? `The person has not asked you to set up this connection. Do not create a connection or a saved draft yourself. Call connection_request with service ${results[0]!.service} to show the inline setup card, and until the connection is ready, do not claim access to ${results[0]!.name} or report its data.`
|
||||
: `The person has not asked you to set up this connection. Do not create a connection or a saved draft yourself. If they asked how to connect ${results[0]!.name} or about its setup options, answer in plain words from these results, naming each method and any prerequisite, and link its setup page as [Connect ${results[0]!.name}](/${prefix}/apps/connect?${new URLSearchParams({ source: results[0]!.service })}); do not call connection_request for that, because its card ends your turn before your answer is shown. If they need ${results[0]!.name} data for their request, call connection_request with service ${results[0]!.service} to show the inline setup card, which lets them connect or decline. Until the connection is ready, do not claim access to ${results[0]!.name} or report its data.` };
|
||||
}
|
||||
|
||||
/** Conservative: a false negative only shows the setup card instead of configuring. */
|
||||
async function latestHumanMessageRequestsSetup(companyId: string, issueId: string, userId: string, target: Pick<ConnectionSearchResultItem, "service" | "name">) {
|
||||
// Use a persisted human-authored message, never the agent-supplied query.
|
||||
const [message] = await db.select({ body: issueComments.body }).from(issueComments).where(and(
|
||||
eq(issueComments.companyId, companyId), eq(issueComments.issueId, issueId),
|
||||
eq(issueComments.authorUserId, userId), isNull(issueComments.authorAgentId),
|
||||
isNull(issueComments.createdByRunId), isNull(issueComments.derivedAuthorAgentId), isNull(issueComments.deletedAt),
|
||||
)).orderBy(desc(issueComments.createdAt), desc(issueComments.id)).limit(1);
|
||||
if (!message) return false;
|
||||
// The setup verb must govern this app: "Connect Slack, then read my Notion"
|
||||
// asks to set up Slack, so a Notion result still gets the setup card.
|
||||
const clause = message.body.trim().split(/[,.;:!?\n]|\s+(?:then|and|but)\s+/i)[0] ?? "";
|
||||
if (!SETUP_REQUEST_PATTERN.test(clause)) return false;
|
||||
const words = ` ${normalizeConnectionQuery(clause)} `;
|
||||
return [target.name, target.service].some(name => {
|
||||
const normalized = normalizeConnectionQuery(name);
|
||||
return !!normalized && words.includes(` ${normalized} `);
|
||||
});
|
||||
}
|
||||
|
||||
async function providerSelections(companyId: string, issueId: string, agentId: string, userId: string, questionId: string) {
|
||||
|
||||
@@ -213,13 +213,13 @@ export function createOAuthAuthorizationStart(db: Db, dependencies: Dependencies
|
||||
}
|
||||
const [company] = await db.select({ prefix: companies.issuePrefix }).from(companies).where(eq(companies.id, companyId));
|
||||
if (!company) throw notFound("Company not found");
|
||||
const destination = new URL(input.redirectUri);
|
||||
destination.pathname = `/${encodeURIComponent(company.prefix)}/apps/${connection.credentialSource === "vercel_connect" ? "vercel-connect" : "connect"}`;
|
||||
destination.search = new URLSearchParams({ [connection.status === "draft" ? "resume" : "reconnect"]: connection.id,
|
||||
...(sourceTemplateKey ? { source: sourceTemplateKey } : {}), ...(intentLink ? { intent: intentLink.id } : {}) }).toString();
|
||||
destination.hash = "";
|
||||
// A relative app route: the agent links it in chat, where it opens on
|
||||
// whichever host the person uses, never the server's own listen address.
|
||||
const destination = `/${encodeURIComponent(company.prefix)}/apps/${connection.credentialSource === "vercel_connect" ? "vercel-connect" : "connect"}?${new URLSearchParams({
|
||||
[connection.status === "draft" ? "resume" : "reconnect"]: connection.id,
|
||||
...(sourceTemplateKey ? { source: sourceTemplateKey } : {}), ...(intentLink ? { intent: intentLink.id } : {}) })}`;
|
||||
return { connectionId: connection.id, provider: sourceTemplateKey ?? "oauth",
|
||||
authorizationUrl: destination.toString(), expiresAt: null };
|
||||
authorizationUrl: destination, expiresAt: null };
|
||||
}
|
||||
if (sourceTemplateKey === "google-workspace" && connection.status === "draft") {
|
||||
const workspaceSetup = { version: 1, ...workspaceDraftBinding, requestedScopes };
|
||||
|
||||
Reference in new issue
Block a user