mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-07 16:11:46 +02:00
678728f650
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents move issues to `in_review` and rely on a "review path" (an interaction, an approval, a monitor, or a named reviewer) to tell them who decides next. > - That review path can silently disappear. A user comment supersedes the pending interaction, a monitor is exhausted, or a run ends without restoring a path. The issue then sits in `in_review` with nobody reviewing it and no visible action. > - Such issues become invisible zombies. Nobody knows a decision is owed, so the work stalls forever. > - This pull request makes the review path a maintained invariant, exposes a `reviewAttention` surface, and gives every stalled review three inline actions in the UI. > - The benefit is that an `in_review` issue always shows who reviews it, or shows an amber "nobody is reviewing this" notice with one-click Approve, Request changes, and Send back to work. ## Linked Issues or Issue Description This pull request describes the problem inline. The tracking issue is internal. **Subsystem affected** The review and attention loop that agents and humans share: the `in_review` status, the `reviewAttention` surface, the /decisions attention feed, and the issue-page review panel. **Problem or motivation** Agent-owned issues in `in_review` can lose their last review path. A user comment supersedes the pending interaction. A monitor is exhausted. A run ends without restoring a path. The issue then sits in `in_review` with no reviewer and no visible action. It becomes an invisible zombie and the work never progresses. **Proposed solution** Maintain the review path as a server invariant. Expose a `reviewAttention` field that says what is under review, who decides, and since when. Render a persistent review panel on the issue page and inline actions on the /decisions feed. Keep human PATCHes into `in_review` ungated, but record the requesting user so the panel never renders empty. **Alternatives considered** A pure background auto-recovery sweep. This stays opt-in and is not enough on its own, because it is invisible to the human. A bare status banner. This is rejected, because it gives no action to resolve the stall. **Roadmap alignment** This improves the core review and attention loop that both agents and humans use every day. ## What Changed - **Server — maintained review-path invariant:** when an issue enters or sits in `in_review`, the server derives and persists a review path (interaction, approval, monitor, or the requesting user) and recovers a stale path with one bounded wake instead of leaving the issue pathless. - **Server — `reviewAttention` surface:** a new field describes what is under review (bound target with links), who decides, since when, and whether the review is stalled. Stalled agent-assigned reviews are now included in the attention feed. - **Server — inline stalled-review decisions:** secured routes let a permitted responder Approve (→ `done`), Request changes (→ `todo` + wake carrying the note), or Send back to work (→ `todo` + wake) directly from the attention feed. - **Server — resume-intent wake:** an `in_review -> todo` transition now wakes the assigned agent so a resumed review is not dropped. - **Server — user-entry symmetry:** user PATCHes into `in_review` stay ungated (no 422 for humans) and record the requesting user, who becomes the named responder when no other path exists. - **UI — review panel:** a persistent `IssueReviewPanel` renders above the thread whenever status is `in_review`. The covered state shows the bound target, responder, and outcomes and hoists the pending interaction/approval card. The stalled state shows the amber notice plus the three actions. - **UI — decisions card actions:** the same three actions render inline on the /decisions `AttentionQueueRow`. - **UI — responsive fix:** the stalled action row stacks to full-width buttons at phone width and returns to a horizontal row at `sm` and up. New 390px stories capture the phone layout. ## Verification - `cd ui && npx vitest run src/components/IssueReviewPanel.test.tsx src/components/AttentionQueueRow.test.tsx src/lib/attention.test.ts src/api/issues.test.ts` — 91 tests pass. - Server suites added and updated: `issue-review-attention`, `issue-stalled-review-decision-routes`, `review-path-recovery`, `recovery-observability`, and related route/liveness tests (run by CI). - A designer reviewed the UI at 390px and desktop in light and dark themes on both the issue-page panel and the /decisions card. The stalled action row stacks cleanly at phone width with no overlap and keeps the horizontal row on desktop. ## Risks - **Migration:** adds migration `0200` (next after master `0199`, no renumber). It extends the agent-wakeup-requests schema and is additive. - **Behavioral shift:** `in_review -> todo` now dispatches a wake. This is intended (resume intent) and covered by tests. - **Authz:** the inline decision routes are permission-gated. Only a permitted responder sees and can trigger the actions. - Overall risk is moderate and contained to the review and attention loop. ## Model Used - Claude, Opus 4.8 (`claude-opus-4-8`), extended thinking, 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 - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [ ] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
70 lines
4.7 KiB
TypeScript
70 lines
4.7 KiB
TypeScript
export const API_PREFIX = "/api";
|
|
|
|
export const API = {
|
|
health: `${API_PREFIX}/health`,
|
|
companies: `${API_PREFIX}/companies`,
|
|
companyFolders: `${API_PREFIX}/companies/:companyId/folders`,
|
|
companyFolder: `${API_PREFIX}/companies/:companyId/folders/:folderId`,
|
|
companyFolderMove: `${API_PREFIX}/companies/:companyId/folders/:folderId/move`,
|
|
companyFolderItemMove: `${API_PREFIX}/companies/:companyId/folders/items/move`,
|
|
agents: `${API_PREFIX}/agents`,
|
|
projects: `${API_PREFIX}/projects`,
|
|
environments: `${API_PREFIX}/environments`,
|
|
environmentDeleteBlastRadius: `${API_PREFIX}/environments/:id/delete-blast-radius`,
|
|
environmentCustomImageTemplate: `${API_PREFIX}/environments/:environmentId/custom-image-template`,
|
|
environmentCustomImageTemplateDisable: `${API_PREFIX}/environments/:environmentId/custom-image-template`,
|
|
environmentCustomImageTemplateRollback: `${API_PREFIX}/environments/:environmentId/custom-image-template/rollback`,
|
|
environmentCustomImageSetupSessions: `${API_PREFIX}/environments/:environmentId/custom-image-setup-sessions`,
|
|
environmentCustomImageSetupSession: `${API_PREFIX}/environment-custom-image-setup-sessions/:sessionId`,
|
|
environmentCustomImageSetupSessionTerminalToken: `${API_PREFIX}/environment-custom-image-setup-sessions/:sessionId/terminal-session-token`,
|
|
environmentCustomImageSetupSessionTerminalWs: `${API_PREFIX}/environment-custom-image-setup-sessions/:sessionId/terminal/ws`,
|
|
environmentCustomImageSetupSessionFinish: `${API_PREFIX}/environment-custom-image-setup-sessions/:sessionId/finish`,
|
|
environmentCustomImageSetupSessionCancel: `${API_PREFIX}/environment-custom-image-setup-sessions/:sessionId/cancel`,
|
|
issues: `${API_PREFIX}/issues`,
|
|
stalledReviewDecision: `${API_PREFIX}/issues/:issueId/stalled-review-decision`,
|
|
issueWatchdog: `${API_PREFIX}/issues/:issueId/watchdog`,
|
|
issueTreeControl: `${API_PREFIX}/issues/:issueId/tree-control`,
|
|
issueTreeHolds: `${API_PREFIX}/issues/:issueId/tree-holds`,
|
|
summarySlot: `${API_PREFIX}/companies/:companyId/summary-slots/:scopeKind/:slotKey`,
|
|
summarySlotRevisions: `${API_PREFIX}/companies/:companyId/summary-slots/:scopeKind/:slotKey/revisions`,
|
|
summarySlotGenerate: `${API_PREFIX}/companies/:companyId/summary-slots/:scopeKind/:slotKey/generate`,
|
|
goals: `${API_PREFIX}/goals`,
|
|
approvals: `${API_PREFIX}/approvals`,
|
|
secrets: `${API_PREFIX}/secrets`,
|
|
tools: `${API_PREFIX}/companies/:companyId/tools`,
|
|
toolExamples: `${API_PREFIX}/companies/:companyId/tools/examples`,
|
|
toolApplications: `${API_PREFIX}/companies/:companyId/tools/applications`,
|
|
toolConnections: `${API_PREFIX}/companies/:companyId/tools/connections`,
|
|
toolCatalog: `${API_PREFIX}/companies/:companyId/tools/catalog`,
|
|
toolProfiles: `${API_PREFIX}/companies/:companyId/tools/profiles`,
|
|
toolPolicies: `${API_PREFIX}/companies/:companyId/tools/policies`,
|
|
toolAudit: `${API_PREFIX}/companies/:companyId/tools/audit`,
|
|
toolRuntimeSlots: `${API_PREFIX}/companies/:companyId/tools/runtime-slots`,
|
|
toolRuntimeSlotStop: `${API_PREFIX}/companies/:companyId/tools/runtime-slots/:id/stop`,
|
|
toolRuntimeSlotRestart: `${API_PREFIX}/companies/:companyId/tools/runtime-slots/:id/restart`,
|
|
toolRuntimeHealth: `${API_PREFIX}/companies/:companyId/tools/runtime-health`,
|
|
toolGateway: `${API_PREFIX}/tool-gateway`,
|
|
smokeLab: `${API_PREFIX}/companies/:companyId/smoke-lab`,
|
|
smokeLabServices: `${API_PREFIX}/companies/:companyId/smoke-lab/services`,
|
|
smokeLabInstallFixtures: `${API_PREFIX}/companies/:companyId/smoke-lab/install-fixtures`,
|
|
smokeLabRuns: `${API_PREFIX}/companies/:companyId/smoke-lab/runs`,
|
|
smokeLabRunSteps: `${API_PREFIX}/companies/:companyId/smoke-lab/runs/:runId/steps`,
|
|
userSecretDefinitions: `${API_PREFIX}/companies/:companyId/user-secret-definitions`,
|
|
userSecretDefinition: `${API_PREFIX}/companies/:companyId/user-secret-definitions/:definitionId`,
|
|
userSecretDefinitionCoverage: `${API_PREFIX}/companies/:companyId/user-secret-definitions/:definitionId/coverage`,
|
|
myUserSecrets: `${API_PREFIX}/companies/:companyId/me/user-secrets`,
|
|
myUserSecret: `${API_PREFIX}/companies/:companyId/me/user-secrets/:secretId`,
|
|
secretProviderConfigs: `${API_PREFIX}/secret-provider-configs`,
|
|
secretProviderConfigDiscoveryPreview: `${API_PREFIX}/companies/:companyId/secret-provider-configs/discovery/preview`,
|
|
costs: `${API_PREFIX}/costs`,
|
|
activity: `${API_PREFIX}/activity`,
|
|
dashboard: `${API_PREFIX}/dashboard`,
|
|
sidebarBadges: `${API_PREFIX}/sidebar-badges`,
|
|
sidebarPreferences: `${API_PREFIX}/sidebar-preferences`,
|
|
resourceMemberships: `${API_PREFIX}/resource-memberships`,
|
|
invites: `${API_PREFIX}/invites`,
|
|
joinRequests: `${API_PREFIX}/join-requests`,
|
|
members: `${API_PREFIX}/members`,
|
|
admin: `${API_PREFIX}/admin`,
|
|
} as const;
|