[codex] feat(watchdog): add task watchdog control plane (#8339)
## 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>
This commit is contained in:
Dotta
@@ -0,0 +1,121 @@
|
||||
import type { Meta, StoryObj } from "@storybook/react-vite";
|
||||
import type { Issue, IssueWatchdogSummary } from "@paperclipai/shared";
|
||||
import { IssueProperties } from "@/components/IssueProperties";
|
||||
import {
|
||||
storybookExecutionWorkspaces,
|
||||
storybookIssueDocuments,
|
||||
storybookIssues,
|
||||
} from "../fixtures/paperclipData";
|
||||
|
||||
const issueDocumentSummaries = storybookIssueDocuments.map(({ body: _body, ...summary }) => summary);
|
||||
|
||||
const baseIssue: Issue = {
|
||||
...storybookIssues[0]!,
|
||||
planDocument: storybookIssueDocuments.find((document) => document.key === "plan") ?? null,
|
||||
documentSummaries: issueDocumentSummaries,
|
||||
currentExecutionWorkspace: storybookExecutionWorkspaces[0]!,
|
||||
watchdog: null,
|
||||
};
|
||||
|
||||
function watchdog(overrides: Partial<IssueWatchdogSummary> = {}): IssueWatchdogSummary {
|
||||
return {
|
||||
id: "watchdog-1",
|
||||
companyId: baseIssue.companyId,
|
||||
issueId: baseIssue.id,
|
||||
watchdogAgentId: "agent-qa",
|
||||
instructions: "Keep this tree moving. Verify stopped leaves against tests and review state before accepting them.",
|
||||
status: "active",
|
||||
watchdogIssueId: null,
|
||||
lastObservedFingerprint: null,
|
||||
lastReviewedFingerprint: null,
|
||||
lastTriggeredAt: null,
|
||||
lastCompletedAt: null,
|
||||
triggerCount: 0,
|
||||
createdAt: new Date(Date.now() - 60 * 60_000),
|
||||
updatedAt: new Date(Date.now() - 60 * 60_000),
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
const emptyWatchdogIssue: Issue = { ...baseIssue, watchdog: null };
|
||||
|
||||
const configuredWatchdogIssue: Issue = { ...baseIssue, watchdog: watchdog() };
|
||||
|
||||
const triggeredWatchdogIssue: Issue = {
|
||||
...baseIssue,
|
||||
watchdog: watchdog({
|
||||
watchdogIssueId: "issue-watchdog-child",
|
||||
lastTriggeredAt: new Date(Date.now() - 10 * 60_000),
|
||||
triggerCount: 2,
|
||||
}),
|
||||
};
|
||||
|
||||
const watchdogChildIssue: Issue = {
|
||||
...baseIssue,
|
||||
id: "issue-watchdog-child",
|
||||
identifier: "PAP-9001",
|
||||
title: "Watchdog: keep the parent tree moving",
|
||||
originKind: "task_watchdog",
|
||||
originId: baseIssue.id,
|
||||
parentId: baseIssue.id,
|
||||
watchdog: null,
|
||||
};
|
||||
|
||||
function WatchdogSurfaceStories() {
|
||||
return (
|
||||
<div className="space-y-8 p-6">
|
||||
<div className="grid gap-6 lg:grid-cols-2">
|
||||
<section className="space-y-2">
|
||||
<div className="text-xs uppercase tracking-wide text-muted-foreground">
|
||||
IssueProperties Watchdog row — empty (Set watchdog)
|
||||
</div>
|
||||
<div className="rounded-lg border border-border bg-background/70 p-4">
|
||||
<IssueProperties issue={emptyWatchdogIssue} onUpdate={() => undefined} inline />
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section className="space-y-2">
|
||||
<div className="text-xs uppercase tracking-wide text-muted-foreground">
|
||||
IssueProperties Watchdog row — configured (agent + instructions)
|
||||
</div>
|
||||
<div className="rounded-lg border border-border bg-background/70 p-4">
|
||||
<IssueProperties issue={configuredWatchdogIssue} onUpdate={() => undefined} inline />
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section className="space-y-2">
|
||||
<div className="text-xs uppercase tracking-wide text-muted-foreground">
|
||||
IssueProperties Watchdog row — triggered, linked to generated task
|
||||
</div>
|
||||
<div className="rounded-lg border border-border bg-background/70 p-4">
|
||||
<IssueProperties
|
||||
issue={triggeredWatchdogIssue}
|
||||
childIssues={[watchdogChildIssue]}
|
||||
onUpdate={() => undefined}
|
||||
inline
|
||||
/>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
const meta = {
|
||||
title: "Product/Task Watchdog surfaces",
|
||||
component: WatchdogSurfaceStories,
|
||||
parameters: {
|
||||
docs: {
|
||||
description: {
|
||||
component:
|
||||
"Surfaces the IssueProperties Watchdog row in empty / configured / triggered-and-linked variants for UX review of the task-watchdog configuration UI (PAP-11294).",
|
||||
},
|
||||
},
|
||||
},
|
||||
} satisfies Meta<typeof WatchdogSurfaceStories>;
|
||||
|
||||
export default meta;
|
||||
|
||||
type Story = StoryObj<typeof meta>;
|
||||
|
||||
export const WatchdogSurfaces: Story = {};
|
||||
Reference in New Issue
Block a user