1 Commits

Include renames

Author	SHA1	Message	Date
3 people	faae6b919f	fix(runner): explain task scope on missing tool inputs (#19774) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents read saved task documents through native tools. > - Active-task tools use the task bound to the run. Other task tools require a task UUID. > - Agents sometimes call the second set with only a document key. > - The validator rejects the call, but gives no instruction about the active-task tool. > - This pull request adds scope instructions to the tool schemas and returns them for missing required fields. > - Agents can correct a rejected call. Task selection and permission checks stay in place. ## Linked Issues or Issue Description **What happened?** Two observed document reads sent only `{"key":"sentry-case"}` to `read_task_document`. Each returned `Invalid tool input: / must have required property 'taskId'`. Each later retry with a task UUID returned without an error. Pattern: [Task reads fail when agents omit taskId](https://www.braintrust.dev/app/Paperclip/p/Paperclip%20Staging/patterns/703d8c29-6a40-4aa2-b2c6-e2c5c36b5657). Related PR: #18824 changed document key validation. It does not address task scope. **Expected behavior** The tool contract must state which task it reads. A missing-field error must include the schema owner's recovery instructions. A retry must still pass validation and task permission checks. **Steps to reproduce** 1. Call `read_task_document` through the MCP bridge with only a document key. 2. Inspect the error sent to the caller. 3. Retry with an authorized task UUID. Confirm the returned document belongs to that task. ### Hypothesis and thesis for a fix Hypothesis: generic tool descriptions contribute to confusion between active-task and explicit-task tools. An agent can also ignore a correct schema. These tests do not measure the rate of model mistakes. Thesis: Paperclip owns task scope instructions. Its five explicit-task tools now describe the required UUID and the active-task alternative. The two MCP transports return direct missing-property descriptions from the admitted schema. The transports do not infer task IDs or apply Paperclip task policy. Proof: the same HTTP MCP regression fails on baseline `f673bd3cb5b5b65ec51781e37355e168c3fe8ae4` and passes with the fix. It still rejects before handler dispatch. An explicit retry reaches the requested task. An isolated real API and PostgreSQL test checks the saved revision, active-task selection, malformed UUIDs, and cross-company denial through both transports. ## What Changed - Add UUID and active-task guidance to `get_task`, `comment_on_task`, and the three explicit-task document tools. - Return bounded, distinct descriptions for up to three direct missing required fields. Keep ordinary validation errors unchanged. - Share this formatter between the Runner and OpenCode MCP bridges. - Add transport regressions, real route and database checks, and tool documentation. ## Verification - Baseline red: both transport regressions return only the required-property error and fail the recovery instruction assertion. - Candidate green: 58 Runner and OpenCode transport and error formatter tests pass on Linux with Node 24.22.2. - Final-head server verification passed all 115 tests: 113 document-key checks and two real API integration cases. - The two local integration cases use real MCP HTTP, agent authority, API routes, and disposable PostgreSQL. They read a selected other task and its saved revision, read the active task separately, reject missing IDs for all five tools, reject malformed UUIDs, and return 404 for a foreign company task. - Runner TypeScript typecheck and build pass. - The full server typecheck passed on head `03a37e9e50896416cfd45be33bf6dbe3e13169df` with `PAPERCLIP_TYPECHECK_LOW_MEMORY=1 node scripts/typecheck-layers.mjs`. The first run ended without a compiler diagnostic. Final-head CI passes and Greptile is 5/5. - Full preflight stops because cargo is absent. Rust checks were not run locally. - One existing delayed-body fetch test failed with a Node 25 fetch runtime error. All transport tests pass on Node 24. The first integration attempt used the wrong fixture return shape; the test was corrected before the passing run. - CI follow-up: the Runner test program reported four TS18046 errors because `Response.json()` returns `unknown` under CI typings. Both tests now declare the response type. `pnpm exec tsc -p tsconfig.test.json --noEmit` passes, and both transport suites pass again (56 tests). Final head `ffccebca19fe9e21a097829adc020679ffa7d86c` passes CI and Greptile 5/5. - Review follow-up: the foreign task now has a saved document with a distinct body. Both integration cases passed again after this test-only change. The read must return 404 and must not return that body. Current-head CI passes and Greptile is 5/5. - Final CI: https://github.com/paperclipai/paperclip/actions/runs/42352822739 . All required jobs passed for `ffccebca19fe9e21a097829adc020679ffa7d86c`. Greptile is 5/5 with no unresolved review thread. - Real local API behavior is verified. External model behavior and deployed recovery are not verified. No merge or deployment is included. ## Risks - Missing-field errors now contain schema descriptions. The text is limited to direct properties in the admitted schema, at most three distinct descriptions and 1,000 characters each. - Nested schemas and references do not get recovery text. Their validation errors remain intact. - Clearer instructions can help callers recover. They do not guarantee that a model will choose the correct tool. ## Model Used - OpenAI GPT-6 via Codex, with tool use and code execution. The exact deployment model ID and context window are not exposed to this session. ## 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> Co-authored-by: Claude <noreply@anthropic.com>	2026-11-10 09:07:11 -06:00