mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-22 16:51:28 +02:00
DottaandPaperclip
985d3b12b6
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents use task monitors to resume work after a future check. > - The runner rejects monitor arguments that fail the tool schema. > - It returned a generic error with no field or repair guidance. > - An agent could treat a repairable call as a scheduling outage and block its task. > - This pull request adds safe repair guidance and shows the nested request shape. > - Agents can correct the call and confirm a saved schedule before they yield. ## Linked Issues or Issue Description Refs: #15446, #16686. **What happened?** A rejected native `set_task_monitor` call returned `invalid_tool_call` with only “Paperclip rejected this semantic tool call.” The agent could not identify the invalid field. A retry could fail again and leave unfinished work without a scheduled wake. **Expected behavior** Reject invalid arguments before any mutation. Give the provider bounded schema locations and clear repair guidance. A corrected call must save a monitor and allow one wake without duplicate effects. **Steps to reproduce** 1. Call `set_task_monitor` with `idempotencyKey`, `nextCheckAt`, and `notes` at the top level. 2. The schema rejects the call because scheduling fields belong inside `monitor`. 3. Before this change, the provider received no guidance about the required shape. **Paperclip version or commit** Reproduced against master `35c75b56d4` with a failing Rust regression. **Deployment mode** Source checkout. This affects the native runner tool bridge. ## What Changed - Add monitor-specific repair guidance to the runner's existing safe schema error path. - Keep feedback within 512 bytes and omit submitted values and unknown field names. - Show the nested monitor request in the production tool description. Refresh generated contracts and catalog identities. - Test flat and nested invalid input, private value handling, and unchanged authorization errors. - Test rejection, correction with the same key, saved schedule and audit, receipt replay, and one timer wake with real PostgreSQL and the native tool authority. - Update execution documentation and the task verification recipes. ## Verification - Red/green: the Rust provider error regression failed on master because monitor repair guidance was absent. It passed after the fix. - Passed: 29 PostgreSQL monitor and scheduler integration tests. These use the real tool authority and scheduler, with a no-op process agent for wake delivery. - Passed: the native Codex server vertical-slice test. It runs the rebuilt Runner binary with a fake provider and checks durable results and session resume. - Passed: map structure checks, Rust formatting, and `git diff --check`. - Passed locally: full repository `pnpm -r typecheck`, `pnpm build`, and all 392 Rust library unit tests. - Passed on commit `3b667ad24763c1828edd48f56ef7a10766aeb946`: [CI run 39290889768](https://github.com/paperclipai/paperclip/actions/runs/39290889768), including all server, Runner, serialized, browser, typecheck, build, and canary gates. Across the PR, 56 checks passed and four conditional checks were skipped. No check remains pending or failed. - Greptile: 5/5 on that exact commit. The check concluded success, with no review comments or unresolved threads. - The duplicate local `pnpm test:run` attempt did not complete. It was stopped after the full CI suite passed; it is not counted as a local full-suite pass. - The first PostgreSQL attempt could not bind localhost inside the shell sandbox. It passed with normal localhost access. The first broader Rust attempt had 37 socket-permission failures and 355 passes; all 392 passed with localhost access and no code change. - Live model recovery was not run. Local execution policy did not authorize an extra acceptance run through the signed-in provider account. This PR does not include a deployment or recovery of an existing task. ## Risks - Error feedback must not reveal submitted values. Tests cover private values, unknown keys, nested constraints, length bounds, and unchanged generic authorization errors. - This changes guidance only. It does not relax the schema, retry calls automatically, or change scheduling authority. - A new runner binary and refreshed provider contract must reach the target instance before agents receive this guidance. ## Model Used OpenAI Codex, GPT-6, with reasoning, tool use, and code execution. The exact runtime suffix and context window size are not exposed in 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>
184 lines
8.3 KiB
Markdown
184 lines
8.3 KiB
Markdown
# Task creation and lifecycle — agent access
|
|
|
|
Product map: [Task creation and lifecycle](../feature-map/tasks.md).
|
|
|
|
Review date: 2026-10-12. Source commit: `58e16dbddfc9c8d0cf60867f9d9847f0feda055b`.
|
|
Native REST transport reconciled in this change; see the
|
|
[shared transport contract](README.md#native-rest-transport).
|
|
|
|
This is a source-reviewed baseline of representative operations and known gaps.
|
|
Each capability needs operation-level review before its entire scope can be
|
|
qualified. No live agent execution is claimed. Follow the [map contract](../README.md)
|
|
for format, permission checks, evidence and maintenance.
|
|
|
|
## `create`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `POST /api/companies/{companyId}/issues`.
|
|
|
|
Agent access: `available` — Native create_task; REST / CLI / MCP.
|
|
|
|
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership
|
|
and lifecycle rules. Ordinary Board comments preserve queued/running retries;
|
|
only a parked retry can be superseded. Explicit Stop/Interrupt retain their
|
|
existing actor and execution authority. Agent comment tools do not acquire Board
|
|
identity or cancellation authority through this behavior.
|
|
|
|
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts) at the
|
|
reviewed commit above.
|
|
|
|
Verification: `not-run` — exercise a listed permitted operation with actual agent
|
|
credentials/run context; inspect its result and applicable persistence/attribution.
|
|
Assert the relevant denied actor, owner, company or mode from Policy. Review the
|
|
remaining operations before qualifying the whole capability.
|
|
|
|
Gaps: Creation is implemented; agent/user assignment and attachments may need
|
|
narrower/different APIs.
|
|
|
|
## `organize`
|
|
|
|
`GET /api/companies/{companyId}/issues/summaries?ids=...` reads up to five exact
|
|
UUIDs and returns only navigation summaries. Normal company and task-read
|
|
permissions apply to ordinary agent REST calls; task-bridge keys are denied.
|
|
Hidden, missing, foreign and private inaccessible IDs are omitted without an
|
|
existence disclosure. No dedicated CLI/native tool is added. Embedded database
|
|
route tests cover same-company agent access and company/task-bridge denials;
|
|
this does not establish a live native `call_api` journey.
|
|
|
|
The issue-list API accepts optional `includeAgentCreatedTasks`; false restricts
|
|
independent results to human creation before search/pagination. Omission retains
|
|
existing agent/API behavior. `includeParticipatedTasks=true` requires a board user
|
|
and retains only that authenticated user's existing participation as a creation
|
|
visibility exception. Company/private-task access checks still apply. Collection
|
|
preferences and hierarchy presentation are browser state, not additional authority.
|
|
Source-reviewed behavior; live agent access verification remains separate.
|
|
|
|
All `chat_channel` origins count as bot-created for creation visibility, including
|
|
human-initiated conversations. Existing inbox participation remains independent.
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `GET /api/companies/{companyId}/issues`.
|
|
|
|
Agent access: `available` — Native search_tasks; REST / CLI; UI grouping/navigation
|
|
state separately.
|
|
|
|
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership
|
|
and lifecycle rules.
|
|
|
|
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts) at the
|
|
reviewed commit above.
|
|
|
|
Verification: `not-run` — exercise a listed permitted operation with actual agent
|
|
credentials/run context; inspect its result and applicable persistence/attribution.
|
|
Assert the relevant denied actor, owner, company or mode from Policy. Review the
|
|
remaining operations before qualifying the whole capability.
|
|
|
|
Gaps: Search/filter API exists; sorting/grouping/presentation defaults are not
|
|
necessarily shared server preferences.
|
|
|
|
## `properties`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `PATCH /api/issues/{id}`.
|
|
- `PUT /api/issues/{id}/title`.
|
|
|
|
Agent access: `available` — Native set_task_title/reassign_task/set_dependencies and
|
|
set_task_monitor; `call_api` for REST-authorized fields; agent REST. Monitor
|
|
scheduling is a dedicated native tool, not a generic `call_api` operation.
|
|
|
|
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership
|
|
and lifecycle rules. A legacy run can assign its own task to a human without
|
|
cancelling itself only with its signed run token and matching active run, agent,
|
|
company and task. The outgoing run cannot mutate its human-owned task afterward,
|
|
including through a late update already admitted before the handoff. Agent keys,
|
|
native runs, board reassignment and transfers to
|
|
another agent retain verified-stop requirements.
|
|
|
|
Native monitors require standard work mode and an agent-owned task in progress
|
|
or review. The responsible user's current permissions also apply. A malformed
|
|
request is rejected before mutation; bounded schema guidance lets the provider
|
|
correct it without exposing submitted values. Receipt replay never re-arms a
|
|
consumed schedule.
|
|
|
|
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts) at the
|
|
reviewed commit above.
|
|
|
|
Verification: `not-run` — exercise a listed permitted operation with actual agent
|
|
credentials/run context; inspect its result and applicable persistence/attribution.
|
|
Assert the relevant denied actor, owner, company or mode from Policy. Review the
|
|
remaining operations before qualifying the whole capability. Focused route
|
|
regressions in [ownership tests](../../server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts)
|
|
cover a human handoff and stop enforcement for other actors, runtimes and targets;
|
|
they use mocked services and do not claim live execution proof.
|
|
|
|
Monitor verification: submit flat scheduling fields, observe the schema rejection
|
|
and unchanged task, then retry with the nested `monitor` object and the same
|
|
idempotency key. Inspect the saved schedule and audit, yield, and verify exactly
|
|
one `issue_monitor_due` wake. [Scheduler integration coverage](../../server/src/__tests__/issue-monitor-scheduler.test.ts)
|
|
uses real PostgreSQL, the native tool authority, and the heartbeat scheduler with
|
|
a no-op process agent. It does not prove live model recovery.
|
|
|
|
Gaps: Dedicated tools differ in scope and fields. Generic `call_api` forwards
|
|
status, assignment and dependency fields to existing route authorization.
|
|
|
|
## `discussion`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `POST /api/issues/{id}/comments`.
|
|
- `POST /api/companies/{companyId}/issues/{issueId}/attachments`.
|
|
|
|
Agent access: `available` — Native report_progress/comment_on_task/register_deliverable;
|
|
REST / CLI / MCP.
|
|
|
|
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership
|
|
and lifecycle rules.
|
|
|
|
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts) at the
|
|
reviewed commit above.
|
|
|
|
Verification: `not-run` — exercise a listed permitted operation with actual agent
|
|
credentials/run context; inspect its result and applicable persistence/attribution.
|
|
Assert the relevant denied actor, owner, company or mode from Policy. Review the
|
|
remaining operations before qualifying the whole capability.
|
|
|
|
Gaps: Other-task comments and active-task progress have separate scopes. Generic
|
|
`call_api` forwards explicit reopen/resume/interrupt fields to the existing route
|
|
checks; it cannot impersonate a user.
|
|
|
|
## `completion`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `PATCH /api/issues/{id}`.
|
|
|
|
Agent access: `available` — Native paperclip_finish/paperclip_block through runner
|
|
protocol; agent REST / native `call_api` disposition under route permissions.
|
|
|
|
Policy: Company/task visibility, assignment/change policy, active-run checkout ownership
|
|
and lifecycle rules.
|
|
|
|
Evidence: `source-only` — [implementation](../../server/src/routes/issues.ts) at the
|
|
reviewed commit above.
|
|
|
|
Verification: `not-run` — exercise a listed permitted operation with actual agent
|
|
credentials/run context; inspect its result and applicable persistence/attribution.
|
|
Assert the relevant denied actor, owner, company or mode from Policy. Review the
|
|
remaining operations before qualifying the whole capability.
|
|
|
|
Gaps: The server governs whether a reported result becomes done/review/blocked.
|
|
Generic lifecycle PATCH uses existing REST authorization, checkout and approval rules.
|