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>
166 lines
5.4 KiB
TypeScript
166 lines
5.4 KiB
TypeScript
// @vitest-environment jsdom
|
|
|
|
import { flushSync } from "react-dom";
|
|
import { createRoot, type Root } from "react-dom/client";
|
|
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
|
|
import type { InstanceExperimentalSettings as InstanceExperimentalSettingsPayload } from "@paperclipai/shared";
|
|
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
|
import { InstanceExperimentalSettings } from "./InstanceExperimentalSettings";
|
|
|
|
const mockInstanceSettingsApi = vi.hoisted(() => ({
|
|
getExperimental: vi.fn(),
|
|
updateExperimental: vi.fn(),
|
|
previewIssueGraphLivenessAutoRecovery: vi.fn(),
|
|
runIssueGraphLivenessAutoRecovery: vi.fn(),
|
|
}));
|
|
|
|
vi.mock("@/api/instanceSettings", () => ({
|
|
instanceSettingsApi: mockInstanceSettingsApi,
|
|
}));
|
|
|
|
vi.mock("../context/BreadcrumbContext", () => ({
|
|
useBreadcrumbs: () => ({ setBreadcrumbs: vi.fn() }),
|
|
}));
|
|
|
|
async function act(callback: () => void | Promise<void>) {
|
|
let result: void | Promise<void> = undefined;
|
|
flushSync(() => {
|
|
result = callback();
|
|
});
|
|
await result;
|
|
}
|
|
|
|
async function flushReact() {
|
|
for (let index = 0; index < 5; index += 1) {
|
|
await Promise.resolve();
|
|
await new Promise((resolve) => window.setTimeout(resolve, 0));
|
|
}
|
|
flushSync(() => {});
|
|
}
|
|
|
|
const CONFERENCE_TOGGLE_SELECTOR =
|
|
'button[aria-label="Toggle conference room chat experimental setting"]';
|
|
const TASK_WATCHDOGS_TOGGLE_SELECTOR =
|
|
'button[aria-label="Toggle task watchdogs experimental setting"]';
|
|
|
|
function defaultExperimentalSettings(): InstanceExperimentalSettingsPayload {
|
|
return {
|
|
enableEnvironments: false,
|
|
enableIsolatedWorkspaces: false,
|
|
enableStreamlinedLeftNavigation: false,
|
|
enableConferenceRoomChat: false,
|
|
enableIssuePlanDecompositions: false,
|
|
enableExperimentalFileViewer: false,
|
|
enableTaskWatchdogs: false,
|
|
enableCloudSync: false,
|
|
autoRestartDevServerWhenIdle: false,
|
|
enableIssueGraphLivenessAutoRecovery: false,
|
|
issueGraphLivenessAutoRecoveryLookbackHours: 24,
|
|
};
|
|
}
|
|
|
|
describe("InstanceExperimentalSettings — Conference Room Chat card (PAP-11233)", () => {
|
|
let container: HTMLDivElement;
|
|
let root: Root | null = null;
|
|
let currentExperimentalSettings: InstanceExperimentalSettingsPayload;
|
|
|
|
async function renderPage() {
|
|
root = createRoot(container);
|
|
const queryClient = new QueryClient({
|
|
defaultOptions: { queries: { retry: false } },
|
|
});
|
|
flushSync(() => {
|
|
root!.render(
|
|
<QueryClientProvider client={queryClient}>
|
|
<InstanceExperimentalSettings />
|
|
</QueryClientProvider>,
|
|
);
|
|
});
|
|
await flushReact();
|
|
}
|
|
|
|
beforeEach(() => {
|
|
container = document.createElement("div");
|
|
document.body.appendChild(container);
|
|
currentExperimentalSettings = defaultExperimentalSettings();
|
|
mockInstanceSettingsApi.getExperimental.mockImplementation(async () => ({
|
|
...currentExperimentalSettings,
|
|
}));
|
|
mockInstanceSettingsApi.updateExperimental.mockImplementation(async (patch) => {
|
|
currentExperimentalSettings = { ...currentExperimentalSettings, ...patch };
|
|
return { ...currentExperimentalSettings };
|
|
});
|
|
});
|
|
|
|
afterEach(() => {
|
|
flushSync(() => {
|
|
root?.unmount();
|
|
});
|
|
root = null;
|
|
container.remove();
|
|
vi.clearAllMocks();
|
|
});
|
|
|
|
it("does not render the Conference Room Chat experimental setting for now", async () => {
|
|
await renderPage();
|
|
|
|
const headings = [...container.querySelectorAll("section h2")].map((h) => h.textContent);
|
|
expect(headings).toContain("Streamlined Left Navigation Bar");
|
|
expect(headings).not.toContain("Conference Room Chat");
|
|
expect(container.querySelector(CONFERENCE_TOGGLE_SELECTOR)).toBeNull();
|
|
});
|
|
|
|
it("does not render the toggle even when the stored flag is currently enabled", async () => {
|
|
currentExperimentalSettings = {
|
|
...currentExperimentalSettings,
|
|
enableConferenceRoomChat: true,
|
|
};
|
|
await renderPage();
|
|
|
|
const toggle = container.querySelector(CONFERENCE_TOGGLE_SELECTOR);
|
|
expect(toggle).toBeNull();
|
|
expect(mockInstanceSettingsApi.updateExperimental).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("renders and patches the Task Watchdogs experimental toggle on and off", async () => {
|
|
await renderPage();
|
|
|
|
expect(container.textContent).toContain("Task Watchdogs");
|
|
expect(container.textContent).toContain(
|
|
"Show task detail controls for configuring watchdog agents that verify stopped task subtrees and restore live paths when work should continue.",
|
|
);
|
|
|
|
const toggle = container.querySelector<HTMLButtonElement>(TASK_WATCHDOGS_TOGGLE_SELECTOR);
|
|
expect(toggle?.getAttribute("aria-checked")).toBe("false");
|
|
|
|
await act(async () => {
|
|
toggle?.click();
|
|
});
|
|
await flushReact();
|
|
|
|
expect(mockInstanceSettingsApi.updateExperimental).toHaveBeenCalledWith({
|
|
enableTaskWatchdogs: true,
|
|
});
|
|
expect(toggle?.getAttribute("aria-checked")).toBe("true");
|
|
|
|
flushSync(() => {
|
|
root?.unmount();
|
|
});
|
|
root = null;
|
|
container.textContent = "";
|
|
await renderPage();
|
|
|
|
const enabledToggle = container.querySelector<HTMLButtonElement>(TASK_WATCHDOGS_TOGGLE_SELECTOR);
|
|
expect(enabledToggle?.getAttribute("aria-checked")).toBe("true");
|
|
|
|
await act(async () => {
|
|
enabledToggle?.click();
|
|
});
|
|
await flushReact();
|
|
|
|
expect(mockInstanceSettingsApi.updateExperimental).toHaveBeenLastCalledWith({
|
|
enableTaskWatchdogs: false,
|
|
});
|
|
});
|
|
});
|