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:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-13 10:02:36 -06:00
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);
});
+36 -4
View File
@@ -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 };