mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-14 00:26:28 +01:00
DottaandClaude Opus 5.5
15b0746340
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - When an agent needs a person to connect a service, it creates a
connection request card. The card is addressed to one person, and only
that person can complete or decline it. The server enforces this
> - Agents learn how connection requests work from the shared connection
guidance (`CONNECTION_INTENT_AGENT_GUIDANCE`). The `get_task_context`
tool returns it as `connectionGuidance`
> - That guidance did not say who can resolve a card. In chat-eval
cohort 4 (`connection-setup.wrong-person-resolves`), another member said
"I will finish Alex's connection request for them". The CEO agent read
only the task context and replied that "completing it there is the right
move"
> - The product still refused the other member, but the agent encouraged
an action that cannot succeed
> - This pull request adds one line to the shared guidance: a request
card is addressed to one person, only that person can complete or
decline it, and the agent says whose action it waits on
> - The benefit is that agents give the correct next step instead of
sending people to a control they cannot use
## Linked Issues or Issue Description
**What happened?**
A company member told the CEO agent "I will finish Alex's connection
request for them." The request card was addressed to Alex. The agent
replied "Alex's Notion connection request is on COM-1, so completing it
there is the right move. I'll leave the connection approval to you." The
server correctly refused the other member's setup, completion and
decline requests (403).
**Expected behavior**
The agent tells the person that the request waits on Alex, and that only
Alex can complete or decline it.
**Steps to reproduce**
1. Have an agent create a Notion connection request card addressed to
Alex on a task.
2. As another company member, tell the agent in chat that you will
finish Alex's connection request.
3. Read the agent's reply.
**Paperclip version or commit**
master at f1aef0cb58.
## What Changed
- `packages/shared/src/connection-intent-guidance.ts`: one new guidance
line. A connection or access request card is addressed to one person;
only that person can complete or decline it; another member and the
agent cannot finish it for them; when someone else offers to, the agent
says whose action it waits on and points to the request.
- `packages/shared/src/connection-intent-guidance.test.ts`: a test that
the guidance states the addressee rule.
## Verification
- `cd packages/shared && npx vitest run
src/connection-intent-guidance.test.ts`: 4 tests pass. Red/green: the
new test fails without the guidance line.
- `npx vitest run --config tests/runner-e2e/vitest.config.ts
tests/runner-e2e/connection-guidance.test.ts`: 17 tests pass.
`server/src/adapters/http/execute.test.ts`: 3 tests pass.
- `packages/adapter-utils/src/server-utils.test.ts` has one local
failure ("does not crash when the child closes stdin before a delayed
write", 5 s timeout). It fails the same way on `origin/master` on this
machine, so it is not caused by this change. CI runs it.
- A paid chat-eval run of `connection-setup.wrong-person-resolves` with
this change is linked in a comment below.
## Risks
- Low risk. The guidance text grows by one line in every prompt that
includes connection guidance. The rule restates what the server already
enforces.
- Model behavior is not guaranteed by guidance. The server boundary
stays the enforcement.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, 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
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
29 lines
4.4 KiB
TypeScript
29 lines
4.4 KiB
TypeScript
/**
|
|
* Canonical instructions for the run-scoped connection tools.
|
|
*
|
|
* Keep this text provider-neutral and free of run identity, credentials, URLs,
|
|
* or bearer tokens: it is reused in prompts, adapter descriptors, CLI help,
|
|
* environment delivery, and MCP tool descriptions.
|
|
*/
|
|
export const CONNECTION_INTENT_AGENT_GUIDANCE = [
|
|
"Connection tools:",
|
|
"- Storing a company or personal credential in Paperclip Secrets is distinct from connecting an external service. Use `search_api` to discover secret metadata and secure human-entry guidance; do not require an external provider choice merely to store an already-requested credential. Values stay in the human's secure entry surface, never in comments; personal values belong to the signed-in person.",
|
|
"- When the user asks to connect a service, call `connections_search` before any service tool, even if already installed. Also search when a task needs a service and usable access is uncertain. Search by its name or capability and follow the returned `instruction`.",
|
|
"- Distinguish tool, chat/channel, and AI account purposes. Use `search_api` and `call_api` for authorized connection configuration requested by the user. Standard agents can manage connections under their responsible user's authority; inspect the returned capabilities and respect explicit restrictions. Reuse saved accounts and setup drafts.",
|
|
"- Suggest a relevant connection when it would help the task and usable access is missing. Respect recorded declines and provider choices. Ask only for missing decisions, consent, credentials, or authority; never ask for credentials in comments. Hand off the exact required human action at the saved setup link, then inspect status and continue through the API.",
|
|
"- If a tool call is blocked by Off/Ask first or missing installation access, use `connection_request` with the saved connectionId and required toolNames. Do not silently relax policy to work around a failed call. You may perform an access-policy change explicitly requested by the user when authorized; never approve your own governed action or change your own principal permissions.",
|
|
"- A connection or access request card is addressed to one person. Only that person can complete or decline it; another member, and you, cannot finish it for them. When someone else offers to, say whose action it is waiting on and point to the request instead of encouraging them.",
|
|
"- Report saved, authenticated, usable, and verified as separate states. A saved connection is not proof of successful authentication or a verified provider action.",
|
|
"- When waiting for user action, finish independent work, then yield without retrying or polling. On continuation, follow the recorded outcome and use the installed connection.",
|
|
"- Do not use connection tools for arbitrary MCP URLs or unrelated work.",
|
|
].join("\n");
|
|
|
|
export const CONNECTIONS_SEARCH_TOOL_DESCRIPTION = "Search connections across tool, channel/email, and AI purposes with a service name or natural-language description (up to 4000 characters). Storing a company or personal credential in Paperclip Secrets is a separate operation: use search_api for secret metadata and secure human-entry guidance, not external provider discovery. Choose the relevant method and inspect its management capabilities. For user-requested configuration, discover and call the existing REST operation with search_api/call_api; reuse saved drafts and hand off only required human authentication or consent. Use connection_request for missing access or required user input. Also discovers verified external aggregator apps. Use first when asked to connect a service or usable access is uncertain; respect the returned instruction, recorded declines, and exact providerQuestion. Do not use for arbitrary MCP URLs. Search is read-only.";
|
|
|
|
export const CONNECTION_REQUEST_TOOL_DESCRIPTION = "Request the service identifier returned by connections_search. For an existing connection with missing agent access, pass connectionId and the exact required toolNames to create an embedded Grant access card; only the human can approve it. Follow the search instruction; aggregator routes require the saved provider-selection interaction ID. Only this tool creates the real setup card. If user action is needed, finish independent work, then yield without retrying or asking for credentials in comments.";
|
|
|
|
export const CONNECTION_RUNTIME_TOOL_NAMES = [
|
|
"connections_search",
|
|
"connection_request",
|
|
] as const;
|