mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-07 06:16:06 -10:00
DottaandClaude Opus 5.5
5eac099fbb
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents ask users for input with the `request_human_input` tool or
the `ask_user_questions` interaction. Paperclip shows each call as one
question card.
> - In an onboarding walk, a Codex execution agent asked five
independent questions (name, menu and prices, contact, style, output).
It posted five cards, one after the other. Each card came 20-60 s after
the previous answer.
> - The tool description said: "For one question at a time, ask only the
next unanswered question and wait for its real answer." Agents read this
as a rule. The paperclip skill showed only a one-question example and
did not tell agents to batch.
> - No server cap exists. A question set accepts up to 64 questions.
> - This pull request changes the guidance. Agents now ask independent
inputs together in one card. They use a follow-up card only when a
question depends on an earlier answer. One-at-a-time stays available
when the user asks for it.
> - The benefit is fewer waits for the user: one card and one agent turn
instead of five.
## Linked Issues or Issue Description
**What happened?**
An execution agent asked a user five independent follow-up questions in
five separate question cards. Each card appeared only after the user
answered the previous card and the agent finished another turn (20-60 s
each).
**Expected behavior**
When an agent needs several independent inputs, it asks them together in
one multi-question card. The onboarding interview already does this ("1
of 4" pager).
**Steps to reproduce**
1. Complete onboarding on the Codex API path and hand off a task such as
"Create printable cake menu and logo".
2. Watch the execution agent's first turns.
3. See five sequential single-question cards.
**Paperclip version or commit**
master at 4938a930d6 (local dev server).
**Agent adapter(s) involved**
Codex (gpt-5.6-sol). The guidance is shared by all adapters that use the
Runner `request_human_input` tool or the `paperclip` skill.
## What Changed
-
`packages/paperclip-runner/src/protocol-actions/request-human-input.ts`:
replace the ambiguous "For one question at a time…" sentence. The new
text tells agents to ask independent inputs together in one questions
card. They use a follow-up card only when it depends on an earlier
answer. It keeps one-at-a-time for when the user asks for it.
- `skills/paperclip/SKILL.md` and
`skills/paperclip/references/api-reference.md`: add the same batching
rule to the human-input sections.
- `packages/mcp-server/src/tools.ts`: add the batching hint to the
`paperclipAskUserQuestions` tool description.
- Regenerated runner contracts (`semantic-tool-contracts.json`,
`protocol/manifest.json`, `native-execution-seeded.json`) and updated
the legacy MCP alias semantics in `spec/capability/mcp-tool-map.yaml`.
- New tests: `core-contracts.test.ts` (tool description) and
`paperclip-skill-utils.test.ts` (skill and API reference).
## Verification
Red on master (tests added, source unchanged):
```
packages/paperclip-runner: npx vitest run src/protocol-actions/core-contracts.test.ts -t batch
× tells agents to batch independent questions into one card instead of asking them one by one
AssertionError: expected 'Create a durable human question or ap…' not to contain 'For one question at a time'
Tests 1 failed | 20 skipped (21)
npx vitest run server/src/__tests__/paperclip-skill-utils.test.ts -t batch
× tells agents to batch independent human-input questions into one card
AssertionError: expected ' For an open answer, use a text field…' to contain 'ask them together in one card'
Tests 1 failed | 21 skipped (22)
```
Green after the fix:
```
packages/paperclip-runner: npx vitest run src/protocol-actions src/drivers/runner-tool-bridge.claude-schema.test.ts
Test Files 4 passed (4) Tests 46 passed (46)
npx vitest run server/src/__tests__/paperclip-skill-utils.test.ts Tests 22 passed (22)
npx vitest run server/src/services/native-runtime/paperclip-runner-tool-authority.test.ts Tests 41 passed (41)
node scripts/generate-semantic-contracts.mjs --check / generate-capability-contract --check / generate-semantic-action-catalog --check / generate-replay-goldens --check: current
```
`packages/mcp-server` has one failure ("allows create issue requests to
omit status…"). It also fails on master without this change, so it is
not related.
This is a guidance change. The automated check proves that the guidance
the agent receives tells it to batch. I did not run a live-model eval.
## Risks
- Low risk. The change is text only: tool descriptions and skill docs.
No schema, API, or storage change.
- An agent could put a dependent question into the same card. The text
tells agents to use a follow-up card for dependent questions.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
code execution.
## 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 <[email protected]>
Paperclip MCP Server
Model Context Protocol server for Paperclip.
This package is a thin MCP wrapper over the existing Paperclip REST API. It does not talk to the database directly and it does not reimplement business logic.
Authentication
The server reads its configuration from environment variables:
PAPERCLIP_API_URL- Paperclip base URL, for examplehttp://localhost:3100PAPERCLIP_API_KEY- bearer token used for/apirequestsPAPERCLIP_COMPANY_ID- optional default company for company-scoped toolsPAPERCLIP_AGENT_ID- optional default agent for checkout helpersPAPERCLIP_RUN_ID- optional run id forwarded on mutating requests
Inside an active heartbeat, Paperclip also injects PAPERCLIP_RUNTIME_TOOLS_* variables. They enable the run-scoped connections_search and connection_request tools and expire with the run.
Usage
npx -y @paperclipai/mcp-server
Or locally in this repo:
pnpm --filter @paperclipai/mcp-server build
node packages/mcp-server/dist/stdio.js
Tool Surface
Run-scoped connection tools:
connections_searchconnection_request
Read tools:
paperclipMepaperclipInboxLitepaperclipListAgentspaperclipGetAgentpaperclipListIssuespaperclipGetIssuepaperclipGetHeartbeatContextpaperclipListCommentspaperclipGetCommentpaperclipListIssueApprovalspaperclipListDocumentspaperclipGetDocumentpaperclipListDocumentRevisionspaperclipListProjectspaperclipGetProjectpaperclipGetIssueWorkspaceRuntimepaperclipWaitForIssueWorkspaceServicepaperclipListGoalspaperclipGetGoalpaperclipListApprovalspaperclipGetApprovalpaperclipGetApprovalIssuespaperclipListApprovalComments
Write tools:
paperclipCreateIssuepaperclipUpdateIssuepaperclipCheckoutIssuepaperclipReleaseIssuepaperclipAddCommentpaperclipSuggestTaskspaperclipAskUserQuestionspaperclipRequestConfirmationpaperclipUpsertIssueDocumentpaperclipRestoreIssueDocumentRevisionpaperclipControlIssueWorkspaceServicespaperclipCreateApprovalpaperclipLinkIssueApprovalpaperclipUnlinkIssueApprovalpaperclipApprovalDecisionpaperclipAddApprovalComment
Escape hatch:
paperclipApiRequest
paperclipApiRequest is limited to paths under /api and JSON bodies. It is
meant for endpoints that do not yet have a dedicated MCP tool.