mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-06 21:05:21 +02:00
DottaandPaperclip
ae6761e2b0
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Paperclip keeps agent lifecycle changes behind control-plane authorization > - Plugins can create agents in a paused state until an operator activates them > - An agent with a direct configuration grant could not resume these agents > - A paused plugin-managed agent also had no stable provenance in its pause reason > - This pull request adds one protected resume path and preserves every other lifecycle gate > - The benefit is safe recovery from plugin provisioning without a broad permission change ## Linked Issues or Issue Description Refs #8168. That pull request uses a role capability and also opens clear-error. This change uses the current grant system and keeps clear-error closed. **What happened?** A plugin can create a paused managed agent. An agent actor cannot resume that agent, even when the actor has a direct `agents:configure` grant. The paused agent can also have a null pause reason. **Expected behavior** An agent with a direct `agents:configure` grant can resume an accessible paused agent. An agent without that grant cannot resume it. Plugin-managed paused agents show stable plugin provenance. A completed resume stays in effect after reconcile. **Steps to reproduce** 1. Install a plugin that declares a managed agent with `status: paused`. 2. Give a same-company agent a direct `agents:configure` grant. 3. Call `POST /api/agents/{id}/resume` with the granted agent key. 4. On the base revision, observe a board-only authorization error. **Paperclip version or commit** `master` at `63df7ad2b3`. **Deployment mode** All deployment modes. This is a server authorization and reconcile behavior. ## What Changed - The resume route now uses the protected `agent_config:update` decision with `requiresChangeGrant: true` for agent actors. - The route keeps board access, tenant non-disclosure, and invalid organization-chain protection. - Resume activity now records the real user or agent actor, run, and API key. - Plugin-managed paused agents now receive a stable provenance reason and pause time at creation. - Reconcile backfills only a null reason on an agent that is still declared and stored as paused. - Reconcile preserves manual, budget, system, and other pause reasons. It does not pause a resumed agent again. - The implementation specification now records the narrow resume exception. ## Verification - `pnpm exec vitest run server/src/__tests__/agent-cross-tenant-authz-routes.test.ts server/src/__tests__/plugin-managed-agents.test.ts` passed: 2 files and 26 tests. - `pnpm --filter @paperclipai/server typecheck` passed. - `pnpm -r typecheck` passed. - `pnpm build` passed. - GitHub CI passed all policy, typecheck, build, test, e2e, canary, and security gates on commit `306edf469c`. - Greptile reviewed all 5 changed files. Its check passed with 0 comments and 0 unresolved threads. - The host uses Node 22.22.2. The repository requests Node 24.11 or newer, so pnpm printed engine warnings. - A broad `pnpm test:run` attempt did not complete its general-server group. Runtime port fixtures failed because host port `52000` was already bound. The isolated failing fixture reproduced the same port conflict. The focused feature tests passed before and after the final commit. ## Risks The main risk is an unintended lifecycle permission increase. The change limits agent access to resume only. It requires a protected direct-change decision. It does not open pause, clear-error, terminate, approval, or key-management routes. Tests cover denial, self-denial, tenant isolation, organization-chain checks, and activity attribution. There is no database migration. > This change fixes a narrow gap in the completed plugin, approval, and activity-log roadmap areas. It does not add a new roadmap feature. ## Model Used OpenAI Codex `gpt-5.6-sol`, with xhigh reasoning, tool use, and code execution. The runtime did not expose its context-window size. ## 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>