0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-10 12:07:09 +02:00

Files

T

DottaandPaperclip d034ba7491 fix(interactions): derive question storage from canonical forms (#14946 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents request human input through durable issue interactions.
> - A question form has a canonical presentation and a compatibility
storage format.
> - The creation API required agents to write both formats.
> - Tool guidance told agents to split text and choice questions across
those formats.
> - This pull request accepts one complete canonical form and derives
storage fields on the server.
> - The benefit is a complete question card with stable answer and retry
behavior.

## Linked Issues or Issue Description

Related work: Refs #13630 and #14430. PR #13630 addresses the display of
historical partial forms. This change fixes creation and keeps the check
that rejects conflicting new forms.

**What happened?**

A question save supplied three compatibility questions and one canonical
text question. The API correctly rejected the incomplete canonical form.
The Runner's tool description encouraged this split. Sending only a
complete canonical form also failed because the API required
compatibility questions.

**Expected behavior**

An agent sends one complete `payload.questionSet` with every text and
choice question. Paperclip derives `payload.questions` for storage and
answer compatibility. Existing legacy requests remain valid. Explicitly
conflicting dual forms remain invalid.

**Steps to reproduce**

1. Call `paperclip_request_human_input` with `interactionKind:
"questions"`.
2. Send `payload: { version: 1, questionSet: ... }` with a required text
question and a required choice question.
3. The old API rejects the missing compatibility questions. With this
change, it stores both questions and preserves the canonical form.
4. Retry with the same idempotency key. Confirm that only one
interaction exists.
5. Submit both answers. Confirm that the normal resolver and
continuation rules apply.

**Paperclip version or commit**

The branch is based on `cf8ad63c8`. The problem affects the native
Runner and the interaction creation API.

**Deployment mode**

Server deployment with the native Paperclip Runner. Integration tests
use the real interaction service and an embedded test database.

## What Changed

- Add one shared canonical-to-storage projection. Reuse it for native
harness question requests.
- Accept canonical-only question creation at the shared validator and
server boundary.
- Export the input type and update the plugin SDK and its RPC contract.
- Advertise a typed, complete question form in the live and scenario
tool schemas.
- Enforce canonical text and custom-answer constraints before ordinary
or native resolution. Preserve harmless display whitespace.
- Run regex matching in isolated workers with a deadline and resource
limits. Both answer paths await the result before persistence. Saved
native delivery uses the validated answer without taking another worker
slot.
- Update agent guidance and generated Runner contracts.
- Test mixed forms, option-ID collisions, retries, answers, legacy
requests, and conflicting forms.

## Verification

- Interaction service, HTTP route, native bridge, and Runner authority
suites: 221 tests passed after correcting an obsolete tool-description
assertion.
- Shared validator, plugin SDK, CLI, and UI compatibility suites: 67
tests passed.
- Runner core tool-contract suite: 20 tests passed. AJV validates live
and scenario schemas.
- Final review regressions: 172 shared, service, native bridge, and
authority tests passed. These cover text length, pattern, numeric
limits, whitespace, custom option IDs, and historical pending cards.
- Runner session suites: 67 tests passed. Published example tests: 4
tests passed.
- Server typecheck and the shared/server builds passed after the
compatibility fixes.
- Final delivery verification: 35 response-delivery tests passed. The
native delivery regression proves saved answers do not enter pattern
workers; server typecheck and build passed.
- Pattern security and answer-flow verification: 205 tests passed after
repairing the child fixture loader. These cover pathological matching,
event-loop responsiveness, worker concurrency, slot cleanup, HTTP
routes, native delivery, and the full helper in a child process.
- `pnpm -r typecheck` passed on the bounded-worker revision.
- `pnpm build` passed on the bounded-worker revision.
- All 55 GitHub checks passed on `fe457af`; four optional jobs were
skipped. An unchanged Cursor adapter test timed out once in CI, passed
locally, and passed on one failed-job rerun.
- Reviewers can send the canonical-only mixed form above and verify that
the saved interaction contains both canonical and compatibility
questions.

## Risks

- The creation API accepts a new input shape. Stored rows and answer
contracts keep the existing shape.
- The shared projection must preserve synthetic free-text option IDs.
Collision and native round-trip tests cover this behavior.
- Historical partial rows remain readable. New conflicting dual forms,
including written-answer mismatches, remain rejected.
- Existing pending cards retain the written-answer paths offered by
their stored options. Canonical text constraints still apply.
- Ordinary answers now enforce declared canonical constraints before
persistence. Invalid answers leave the card pending.
- Regex validation has a one-second deadline and a four-worker capacity
limit. A complex pattern or capacity error leaves the card pending with
a validation error.
- No database migration or change to company authorization is required.

## Model Used

- OpenAI GPT-6 through Codex. The session exposes the GPT-6 model
family; its exact runtime model identifier and context window size are
not exposed. Used reasoning, 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
- [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

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

2026-10-02 14:21:11 -05:00

29 KiB

Raw Permalink Blame History

Capability Capability Contract

This generated contract is a self-contained derivative of the Paperclip skill, its seven references, the Paperclip Evals corpus, and the legacy MCP tool surface. It does not import or contact the Paperclip control plane.

The skill/reference inventory and eval cases are the only normative behavior sources. Paperclip does not use the legacy MCP calls as a production capability surface; all MCP names below are traceability aliases folded into normative eval rows. Their disposition, grants, assertions, and evidence contract are inherited from the target row rather than classified independently.

Baseline Counts

Skill/reference headings: 157
Eval cases: 106 across 16 groups
Total normative rows: 263
Legacy MCP aliases folded into normative rows: 42

Eval group	Cases
hb	5
co	6
st	8
cm	6
se	4
su	4
bl	5
dp	3
ix	9
ap	6
ar	4
er	9
rf	22
mh	4
rs	3
wk	8

Regeneration

pnpm --dir packages/paperclip-runner generate:capability-inventory imports the canonical baselines and rewrites every generated file.
pnpm --dir packages/paperclip-runner check:capability-inventory validates counts, uniqueness, normative dispositions, one-to-one MCP folds, required fields, and generated-file drift without requiring the external eval repository.

Skill / Reference Rows

Legacy MCP Alias Index

This is a compatibility/traceability index, not a tool catalog. “Inherited disposition” is shown only to make the normative target easy to audit.

Legacy MCP name	Folded into normative row	Inherited disposition	Source anchor
paperclipMe	eval:hb-inbox-lite-01	control_plane_owned	packages/mcp-server/src/tools.ts:290
paperclipInboxLite	eval:hb-inbox-lite-01	control_plane_owned	packages/mcp-server/src/tools.ts:296
paperclipListAgents	eval:rf-api-mgr-heartbeat-01	optional_agent_tool	packages/mcp-server/src/tools.ts:302
paperclipListSkills	eval:rf-cskill-audit-01	optional_agent_tool	packages/mcp-server/src/tools.ts:308
paperclipGetAgent	eval:rf-api-mgr-heartbeat-01	optional_agent_tool	packages/mcp-server/src/tools.ts:314
paperclipListIssues	eval:se-q-filters-01	optional_agent_tool	packages/mcp-server/src/tools.ts:323
paperclipGetIssue	eval:se-get-issue-01	optional_agent_tool	packages/mcp-server/src/tools.ts:338
paperclipGetHeartbeatContext	eval:hb-context-01	control_plane_owned	packages/mcp-server/src/tools.ts:344
paperclipListComments	eval:se-get-issue-01	optional_agent_tool	packages/mcp-server/src/tools.ts:353
paperclipGetComment	eval:hb-wake-comment-01	control_plane_owned	packages/mcp-server/src/tools.ts:366
paperclipListIssueApprovals	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:373
paperclipListDocuments	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:379
paperclipGetDocument	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:385
paperclipListDocumentRevisions	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:392
paperclipListProjects	eval:rf-wf-project-setup-01	optional_agent_tool	packages/mcp-server/src/tools.ts:402
paperclipGetProject	eval:rf-wf-project-setup-01	optional_agent_tool	packages/mcp-server/src/tools.ts:408
paperclipGetIssueWorkspaceRuntime	eval:rf-iws-start-url-01	optional_agent_tool	packages/mcp-server/src/tools.ts:417
paperclipControlIssueWorkspaceServices	eval:rf-iws-start-url-01	optional_agent_tool	packages/mcp-server/src/tools.ts:423
paperclipWaitForIssueWorkspaceService	eval:rf-iws-target-restart-01	optional_agent_tool	packages/mcp-server/src/tools.ts:440
paperclipListGoals	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:466
paperclipGetGoal	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:472
paperclipListApprovals	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:478
paperclipCreateApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:487
paperclipGetApproval	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:496
paperclipGetApprovalIssues	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:502
paperclipListApprovalComments	eval:ap-approval-deny-01	optional_agent_tool	packages/mcp-server/src/tools.ts:508
paperclipCreateIssue	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:514
paperclipUpdateIssue	eval:st-done-comment-01	always_agent_tool	packages/mcp-server/src/tools.ts:521
paperclipCheckoutIssue	eval:co-body-contract-01	control_plane_owned	packages/mcp-server/src/tools.ts:528
paperclipReleaseIssue	eval:er-release-01	control_plane_owned	packages/mcp-server/src/tools.ts:540
paperclipAddComment	eval:cm-multiline-01	always_agent_tool	packages/mcp-server/src/tools.ts:546
paperclipSuggestTasks	eval:ix-suggest-tasks-01	always_agent_tool	packages/mcp-server/src/tools.ts:553
paperclipAskUserQuestions	eval:ix-questions-01	always_agent_tool	packages/mcp-server/src/tools.ts:565
paperclipRequestConfirmation	eval:ix-confirmation-plan-01	always_agent_tool	packages/mcp-server/src/tools.ts:577
paperclipRequestCheckboxConfirmation	eval:ix-checkbox-01	always_agent_tool	packages/mcp-server/src/tools.ts:589
paperclipUpsertIssueDocument	eval:dp-plan-doc-01	always_agent_tool	packages/mcp-server/src/tools.ts:601
paperclipRestoreIssueDocumentRevision	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:612
paperclipLinkIssueApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:627
paperclipUnlinkIssueApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:636
paperclipApprovalDecision	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:646
paperclipAddApprovalComment	eval:ap-approval-deny-01	optional_agent_tool	packages/mcp-server/src/tools.ts:668
paperclipApiRequest	eval:rf-api-404-report-01	optional_agent_tool	packages/mcp-server/src/tools.ts:677

Capability	Primary disposition	Source anchor
skill:skills/paperclip/SKILL.md:paperclip-skill:10	optional_agent_tool	skills/paperclip/SKILL.md:10
skill:skills/paperclip/SKILL.md:terminology:14	optional_agent_tool	skills/paperclip/SKILL.md:14
skill:skills/paperclip/SKILL.md:authentication:18	control_plane_owned	skills/paperclip/SKILL.md:18
skill:skills/paperclip/SKILL.md:conversation-tasks:30	optional_agent_tool	skills/paperclip/SKILL.md:30
skill:skills/paperclip/SKILL.md:server-verified-external-chat-turns:47	control_plane_owned	skills/paperclip/SKILL.md:47
skill:skills/paperclip/SKILL.md:the-heartbeat-procedure:87	optional_agent_tool	skills/paperclip/SKILL.md:87
skill:skills/paperclip/SKILL.md:generated-artifacts-and-work-products:196	always_agent_tool	skills/paperclip/SKILL.md:196
skill:skills/paperclip/SKILL.md:status-quick-guide:244	control_plane_owned	skills/paperclip/SKILL.md:244
skill:skills/paperclip/SKILL.md:monitors-and-watchers-say-only-what-you-actually-scheduled:254	optional_agent_tool	skills/paperclip/SKILL.md:254
skill:skills/paperclip/SKILL.md:delegating-review-tasks:267	always_agent_tool	skills/paperclip/SKILL.md:267
skill:skills/paperclip/SKILL.md:managing-a-user-s-inbox:278	control_plane_owned	skills/paperclip/SKILL.md:278
skill:skills/paperclip/SKILL.md:issue-dependencies-blockers:286	control_plane_owned	skills/paperclip/SKILL.md:286
skill:skills/paperclip/SKILL.md:requesting-board-approval:311	optional_agent_tool	skills/paperclip/SKILL.md:311
skill:skills/paperclip/SKILL.md:issue-thread-interactions:332	optional_agent_tool	skills/paperclip/SKILL.md:332
skill:skills/paperclip/SKILL.md:standalone-decisions:361	optional_agent_tool	skills/paperclip/SKILL.md:361
skill:skills/paperclip/SKILL.md:mcp-tool-approval-gates:465	optional_agent_tool	skills/paperclip/SKILL.md:465
skill:skills/paperclip/SKILL.md:niche-workflow-pointers:507	optional_agent_tool	skills/paperclip/SKILL.md:507
skill:skills/paperclip/SKILL.md:cases:517	optional_agent_tool	skills/paperclip/SKILL.md:517
skill:skills/paperclip/SKILL.md:company-skills-workflow:522	optional_agent_tool	skills/paperclip/SKILL.md:522
skill:skills/paperclip/SKILL.md:routines:533	optional_agent_tool	skills/paperclip/SKILL.md:533
skill:skills/paperclip/SKILL.md:issue-workspace-runtime-controls:544	optional_agent_tool	skills/paperclip/SKILL.md:544
skill:skills/paperclip/SKILL.md:proposing-credentials-safely:551	optional_agent_tool	skills/paperclip/SKILL.md:551
skill:skills/paperclip/SKILL.md:reading-granted-secrets:558	optional_agent_tool	skills/paperclip/SKILL.md:558
skill:skills/paperclip/SKILL.md:critical-rules:584	optional_agent_tool	skills/paperclip/SKILL.md:584
skill:skills/paperclip/SKILL.md:comment-style-required:605	always_agent_tool	skills/paperclip/SKILL.md:605
skill:skills/paperclip/SKILL.md:update:637	optional_agent_tool	skills/paperclip/SKILL.md:637
skill:skills/paperclip/SKILL.md:planning-required-when-planning-requested:647	optional_agent_tool	skills/paperclip/SKILL.md:647
skill:skills/paperclip/SKILL.md:key-endpoints-hot-routes:680	optional_agent_tool	skills/paperclip/SKILL.md:680
skill:skills/paperclip/SKILL.md:searching-issues:709	optional_agent_tool	skills/paperclip/SKILL.md:709
skill:skills/paperclip/SKILL.md:full-reference:719	optional_agent_tool	skills/paperclip/SKILL.md:719
skill:skills/paperclip/SKILL.md:conversational-confirmation-answers:723	always_agent_tool	skills/paperclip/SKILL.md:723
skill:skills/paperclip/references/artifacts.md:generated-artifacts-and-work-products:1	always_agent_tool	skills/paperclip/references/artifacts.md:1
skill:skills/paperclip/references/artifacts.md:workspace-only-file-references:15	optional_agent_tool	skills/paperclip/references/artifacts.md:15
skill:skills/paperclip/references/cases.md:cases:1	optional_agent_tool	skills/paperclip/references/cases.md:1
skill:skills/paperclip/references/cases.md:core-model:12	optional_agent_tool	skills/paperclip/references/cases.md:12
skill:skills/paperclip/references/cases.md:upsert-semantics:29	optional_agent_tool	skills/paperclip/references/cases.md:29
skill:skills/paperclip/references/cases.md:read-and-search:67	optional_agent_tool	skills/paperclip/references/cases.md:67
skill:skills/paperclip/references/cases.md:documents:90	always_agent_tool	skills/paperclip/references/cases.md:90
skill:skills/paperclip/references/cases.md:fields:118	optional_agent_tool	skills/paperclip/references/cases.md:118
skill:skills/paperclip/references/cases.md:issue-links:151	optional_agent_tool	skills/paperclip/references/cases.md:151

29 KiB Raw Permalink Blame History