mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-19 07:42:38 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents call Paperclip semantic tools (for example `request_human_input`) through the runner, and the ACPX runner sends each refusal back to the agent > - Today the ACPX runner replaces every refusal with the fixed text "Paperclip semantic operation failed" > - The real reason (for example `summary: too big, max 1000`) is only in the run events, so the agent cannot see it > - Agents then retry the same bad input. One agent retried a questions card 5 times with the same too-long prompt > - This pull request adds the stable error code and, for a validation refusal, each failing field path with its rule and limit to the message > - The value the agent sent, free-text messages and server errors (5xx) stay hidden, as before > - The benefit is that agents can fix a refused call on the next try instead of retrying blind ## Linked Issues or Issue Description Refs #20134 (fixes one case of this problem: the advertised `request_human_input` bounds) **What happened?** An agent called a semantic tool with input that failed server validation. The tool result said only "Paperclip semantic operation failed". The agent retried the same input 5 times, and each retry failed the same way. The run events showed the real cause: `summary: too big, max 1000`. **What did you expect to happen?** The tool result should say which field failed and which rule it broke, so the agent can correct the input. It should not echo the input value or internal diagnostics. **Steps to reproduce** 1. Run an agent on an ACPX provider. 2. Call `request_human_input` with a `prompt` of 1,100 characters (before #20134), or any semantic tool with input that fails zod validation. 3. See the generic "Paperclip semantic operation failed" in the tool result. ## What Changed - New `acpx_tool_failure_feedback` module in `runner-core`. It reads a failed tool result and builds a bounded message from: - a stable error code (lowercase words joined by `_`, `.` or `-`, for example `paperclip_runner_agent_not_found`); - zod-style issues: field path, rule name, type and numeric limit, for example `payload.prompt: too_big, string max 1000`. - It reads the result as an object, an issue list, or a `{success:false, contentItems:[{inputText}]}` envelope whose text is JSON or starts with `code:`. - It never copies `message`, `input`, free text or the input value. Path keys and rule names that do not look like names become `*` or `invalid`. It shows at most 5 issues and 8 path segments. - Any result with a status of 500 or more, or with no recognizable code or issue, keeps the generic message. - `AcpxProviderSession` uses this message for non-terminal semantic failures. Reserved terminal tools keep their current feedback. - Fake ACPX sidecar mode `resolutions-error-detail` and an integration test that checks the message crosses the sidecar boundary without the value. ## Verification - `cargo test -p runner-core --lib acpx_tool_failure_feedback` (7 unit tests: issue lists, envelopes, codes, server errors, free text, masking, bounds). - `cargo test -p runner-core --test acpx_provider_resolutions` (new `tells_the_agent_which_field_failed_validation_without_its_value`, and the existing redaction test still gets the generic message). - `cargo fmt --check`. ## Risks - Low to medium. The main risk is data in error text. The module copies only values that match strict name and number patterns, and never a `message` or `input` field. Tests check that sample values do not appear in the output. - Agents see a longer error message for validation refusals. The message still starts with "Paperclip semantic operation failed", so text matches on that prefix keep working. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code execution in an agent harness. ## 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 - [ ] 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: lucktastic <13757243+lucktastic@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>