Files
PaperClipAI/server/src
DottaandClaude Opus 5.5 b0e99dfcfa 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>
2026-11-13 10:02:36 -06:00
..
…
…
…
…
…
…
…