Dotta
a71c4b6782
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The task lifecycle and recovery subsystems decide when agent work is still productive, stalled, or ready for review. > - Existing recovery paths can observe stopped or incomplete work, but there was no first-class per-task watchdog model with scoped review permissions. > - Watchdog follow-ups also need strict boundaries so recovery/status-only runs cannot mutate approvals or perform deliverable work. > - This pull request adds the task watchdog data model, API/service layer, scheduler/review flow, adapter wake context, UI configuration surfaces, and docs. > - The branch has been rebased onto current `paperclipai/paperclip` `master`; the watchdog migration is now ordered after master's latest migrations as `0104_issue_watchdogs`. > - The benefit is a more explicit task-review loop that preserves Paperclip's single-assignee and governance invariants while making stalled work easier to route. ## Linked Issues or Issue Description No linked GitHub issue. Paperclip task: [PAP-11275](/PAP/issues/PAP-11275). ## Problem or motivation Task recovery needs a first-class watchdog path that can inspect stopped work and create scoped follow-ups without bypassing normal task ownership. Board/UI users need a way to configure watchdogs on tasks and see watchdog-related live work. Recovery/status-only runs must remain limited to status reporting and must not create approvals, link approvals, or submit approval comments. ## Proposed solution Add a task-watchdog data model, scheduler/classifier, scoped mutation guard, adapter wake context, API/UI configuration surfaces, and documentation so watchdog agents can review stopped task subtrees under explicit boundaries. ## Alternatives considered Reuse the existing recovery-action flow only. That would keep stopped-work detection implicit, make per-task watchdog assignment harder to expose in the UI, and would not provide a durable scoped-review issue for stalled task trees. ## Roadmap alignment This is Paperclip control-plane lifecycle infrastructure for task execution and recovery. I checked `ROADMAP.md`; this PR does not duplicate an existing planned core item. ## What Changed - Added issue watchdog schema, migration, shared contracts, validators, CRUD API, and service support. - Added task watchdog scheduler/classifier behavior, scoped mutation enforcement, adapter wake context, and default watchdog mandate guidance. - Added UI surfaces for configuring watchdogs on new/existing tasks, viewing watchdog activity, and exposing the experimental setting. - Added docs for the user-facing task watchdog workflow and implementation semantics. - Gated new-task watchdog setup behind `enableTaskWatchdogs` and blocked cheap status-only recovery runs from approval mutations. - Rebased onto current `master` and renumbered the idempotent watchdog migration from the branch-local `0102_issue_watchdogs` slot to `0104_issue_watchdogs`. - Addressed Greptile feedback by loading watchdog classifier input with a recursive subtree query and centralizing the watchdog origin-kind constant. - Added and updated focused server/UI tests for watchdog routes, scheduler/classifier behavior, scope boundaries, live task visibility, settings, and new issue dialog behavior. ## Verification - `pnpm vitest run server/src/__tests__/task-watchdogs-scheduler.test.ts server/src/__tests__/task-watchdogs-classifier.test.ts` - `pnpm vitest run server/src/__tests__/approval-routes-idempotency.test.ts server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts` - `pnpm vitest run ui/src/components/NewIssueDialog.test.tsx` - `pnpm --filter @paperclipai/server typecheck` - `git diff --check` - Verified the PR diff does not include `pnpm-lock.yaml` or `.github/workflows`. ## Risks - Medium risk: this introduces a new task lifecycle surface touching DB schema, server routes/services, adapter wake context, and UI task configuration. - Watchdog scheduling behavior depends on the new experimental setting and runtime context checks behaving consistently across local and production agents. - The watchdog migration is idempotent (`IF NOT EXISTS` / duplicate-object guards) so users who tried the previous branch-local migration number should not get duplicate-object failures. - CI and the second Greptile pass are pending after the latest review-fix push. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex, GPT-5-class coding agent in the Paperclip workspace. Exact runtime model id and context window were not exposed to the agent; tool use and local command execution were enabled. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots — N/A per Paperclip task instruction: do not add screenshots/images to this PR unless they are specifically part of the work. - [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 - [x] 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>
151 lines
4.1 KiB
JSON
151 lines
4.1 KiB
JSON
{
|
|
"$schema": "https://mintlify.com/docs.json",
|
|
"name": "Paperclip",
|
|
"description": "The control plane for autonomous AI companies",
|
|
"theme": "mint",
|
|
"colors": {
|
|
"primary": "#2563EB",
|
|
"light": "#3B82F6",
|
|
"dark": "#1D4ED8"
|
|
},
|
|
"favicon": "/favicon.svg",
|
|
"logo": {
|
|
"dark": "/images/logo-dark.svg",
|
|
"light": "/images/logo-light.svg"
|
|
},
|
|
"topbarLinks": [
|
|
{
|
|
"name": "GitHub",
|
|
"url": "https://github.com/paperclip-ai/paperclip"
|
|
}
|
|
],
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "Get Started",
|
|
"groups": [
|
|
{
|
|
"group": "Introduction",
|
|
"pages": [
|
|
"start/what-is-paperclip",
|
|
"start/quickstart",
|
|
"start/core-concepts",
|
|
"start/architecture"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"tab": "Guides",
|
|
"groups": [
|
|
{
|
|
"group": "Board Operator",
|
|
"pages": [
|
|
"guides/board-operator/dashboard",
|
|
"guides/board-operator/creating-a-company",
|
|
"guides/board-operator/managing-agents",
|
|
"guides/board-operator/org-structure",
|
|
"guides/board-operator/managing-tasks",
|
|
"guides/board-operator/execution-workspaces-and-runtime-services",
|
|
"guides/board-operator/delegation",
|
|
"guides/board-operator/execution-workspaces-and-runtime-services",
|
|
"guides/board-operator/delegation",
|
|
"guides/board-operator/approvals",
|
|
"guides/board-operator/costs-and-budgets",
|
|
"guides/board-operator/activity-log",
|
|
"guides/board-operator/importing-and-exporting"
|
|
]
|
|
},
|
|
{
|
|
"group": "Agent Developer",
|
|
"pages": [
|
|
"guides/agent-developer/how-agents-work",
|
|
"guides/agent-developer/heartbeat-protocol",
|
|
"guides/agent-developer/writing-a-skill",
|
|
"guides/agent-developer/skills-store",
|
|
"guides/agent-developer/task-workflow",
|
|
"guides/agent-developer/comments-and-communication",
|
|
"guides/agent-developer/handling-approvals",
|
|
"guides/agent-developer/cost-reporting"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"tab": "Deploy",
|
|
"groups": [
|
|
{
|
|
"group": "Deployment",
|
|
"pages": [
|
|
"deploy/overview",
|
|
"deploy/local-development",
|
|
"deploy/tailscale-private-access",
|
|
"deploy/docker",
|
|
"deploy/deployment-modes",
|
|
"deploy/database",
|
|
"deploy/secrets",
|
|
"deploy/storage",
|
|
"deploy/environment-variables"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"tab": "Adapters",
|
|
"groups": [
|
|
{
|
|
"group": "Agent Adapters",
|
|
"pages": [
|
|
"adapters/overview",
|
|
"adapters/claude-local",
|
|
"adapters/codex-local",
|
|
"adapters/process",
|
|
"adapters/http",
|
|
"adapters/external-adapters",
|
|
"adapters/adapter-ui-parser",
|
|
"adapters/creating-an-adapter"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"tab": "API Reference",
|
|
"groups": [
|
|
{
|
|
"group": "REST API",
|
|
"pages": [
|
|
"api/overview",
|
|
"api/authentication",
|
|
"api/companies",
|
|
"api/agents",
|
|
"api/issues",
|
|
"api/approvals",
|
|
"api/goals-and-projects",
|
|
"api/costs",
|
|
"api/secrets",
|
|
"api/activity",
|
|
"api/dashboard"
|
|
]
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"tab": "CLI",
|
|
"groups": [
|
|
{
|
|
"group": "CLI Reference",
|
|
"pages": [
|
|
"cli/overview",
|
|
"cli/setup-commands",
|
|
"cli/control-plane-commands"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
},
|
|
"footerSocials": {
|
|
"github": "https://github.com/paperclip-ai/paperclip"
|
|
}
|
|
}
|