67b22d872f
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The issue thread is the operator surface where comments, assignee changes, pauses, resumes, and wakeups turn human intent into agent execution. > - Interrupting a live run and handing work to another assignee needs clear semantics so the product does not accidentally keep work alive, wake the wrong participant, or hide why an agent stopped. > - Comment-driven wakes also need strict boundaries so closed, blocked, and dependency-driven work only resumes when there is real actionable input. > - This pull request codifies the interrupt handoff contract, implements backend scheduling behavior, and gives the UI clearer handoff/pause language. > - The benefit is a more inspectable and predictable task lifecycle for both operators and agents. ## Linked Issues or Issue Description Paperclip issue: `PAP-10664` / `PAP-10751`. Problem: interrupting or reassigning live agent work could be ambiguous in the UI and backend. Operators needed clearer feedback about whether a handoff wakes an agent, what pause/cancel affects, and when comments should revive execution. The backend also needed stronger tests around comment wake boundaries, retry supersession, and structured agent mention dispatch. Related GitHub PR search found broad workflow-adjacent PRs #5082, #6359, and #4083, but no exact duplicate for this head branch or interrupt-handoff scope. ## What Changed - Added an interrupt handoff semantics document covering destination behavior, wake expectations, and live-run interruption states. - Implemented backend interrupt handoff behavior and comment wake/reopen handling in issue routes/services and heartbeat scheduling. - Hardened structured agent mention dispatch so mentions resolve through the intended dispatch path. - Added UI helpers and components for handoff chips, wake rows, interrupt banners, pause-affects summaries, and composer guidance. - Updated the issue properties assignee picker and issue chat/composer surfaces to make interrupt/reassign behavior clearer. - Added backend, UI utility, component, and Storybook coverage for the new behavior. - Stabilized the new UI component tests with a local `flushSync`-backed act helper matching existing repo practice in this dependency set. - Addressed Greptile feedback by threading historical run `errorCode` through issue-run data and operator-interrupted chat labels. - Addressed Greptile's cancel ordering concern by terminating/deleting in-memory heartbeat processes before cancellation status persistence, with regression coverage for DB update failure. ## Verification - `git diff --check $(git merge-base HEAD origin/master)..HEAD` - `pnpm --filter @paperclipai/ui exec vitest run src/lib/interrupt-handoff.test.ts src/lib/issue-chat-messages.test.ts src/components/IssueProperties.test.tsx src/components/interrupt-handoff/InterruptHandoffViews.test.tsx --no-file-parallelism --maxWorkers=1` — 4 files / 91 tests passed before the Greptile follow-ups. - `pnpm run preflight:workspace-links && pnpm exec vitest run server/src/__tests__/heartbeat-process-recovery.test.ts server/src/__tests__/heartbeat-retry-scheduling.test.ts server/src/__tests__/issue-comment-reopen-routes.test.ts server/src/__tests__/issue-tree-control-service.test.ts server/src/__tests__/issue-update-comment-wakeup-routes.test.ts server/src/__tests__/issues-service.test.ts --no-file-parallelism --maxWorkers=1` — 6 files / 191 tests passed before the Greptile follow-ups. - `pnpm --filter @paperclipai/ui exec vitest run src/lib/issue-chat-messages.test.ts --no-file-parallelism --maxWorkers=1` — 1 file / 24 tests passed after the historical `errorCode` follow-up. - `pnpm exec vitest run server/src/__tests__/activity-service.test.ts server/src/__tests__/activity-routes.test.ts --no-file-parallelism --maxWorkers=1` — 2 files / 11 tests passed after the historical `errorCode` follow-up. - `pnpm exec vitest run server/src/__tests__/heartbeat-process-recovery.test.ts --no-file-parallelism --maxWorkers=1` — 1 file / 52 tests passed after the cancel ordering follow-up. - Greptile is green for head `272647636287d034bab8d981eaf5305865aa0f96`; the old inline P2 is resolved/outdated. - GitHub Actions, Socket, security-review, and Greptile checks are green for head `272647636287d034bab8d981eaf5305865aa0f96`. The external `security/snyk (cryppadotta)` status was still pending at `https://app.snyk.io/org/cryppadotta/pr-checks/85b3e8f4-04e1-4f8e-9362-899c8148c23c` after a bounded wait. ## Risks - Medium: changes touch issue comments, wake scheduling, and live-run interruption semantics, so regressions could affect when agents resume or stay stopped. - Medium: UI copy and state grouping for assignee changes may need reviewer tuning after product review. - Low migration risk: no database schema migration is included. - The branch was created before the latest `origin/master` commits; reviewers should confirm CI merge-base behavior and resolve any merge conflicts if GitHub reports them. > 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-based coding agent, tool use and local command execution enabled. Exact hosted model build and context window were not exposed by the runtime. ## 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 - [ ] If this change affects the UI, I have included before/after screenshots - [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 Screenshot note: this PR includes Storybook coverage for the new interrupt handoff UI states rather than captured before/after browser screenshots in this PR-creation heartbeat. --------- Co-authored-by: Paperclip <noreply@paperclip.ing> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
259 lines
10 KiB
TypeScript
259 lines
10 KiB
TypeScript
// @vitest-environment jsdom
|
|
|
|
import type { ReactNode } from "react";
|
|
import { flushSync } from "react-dom";
|
|
import { createRoot, type Root } from "react-dom/client";
|
|
import { afterEach, describe, expect, it, vi } from "vitest";
|
|
import {
|
|
AssigneeChip,
|
|
AssigneeRunningBanner,
|
|
ComposerHandoffPreviewRow,
|
|
ComposerMentionCoach,
|
|
HandoffWakeRow,
|
|
InterruptAssignConfirm,
|
|
PauseAffectsSummaryView,
|
|
RunStatusBadge,
|
|
type HandoffChipResolvers,
|
|
} from "./InterruptHandoffViews";
|
|
import {
|
|
computeComposerHandoffPreview,
|
|
computePauseAffectsSummary,
|
|
describeReassignInterrupt,
|
|
} from "../../lib/interrupt-handoff";
|
|
|
|
const resolvers: HandoffChipResolvers = {
|
|
agentMap: new Map([
|
|
["agent-qa", { name: "QA", icon: null }],
|
|
["agent-claude", { name: "ClaudeCoder", icon: null }],
|
|
]),
|
|
resolveUserLabel: (id) => (id === "user-board" ? "Riley Board" : null),
|
|
currentUserId: "user-board",
|
|
};
|
|
|
|
async function act(callback: () => void | Promise<void>) {
|
|
let result: void | Promise<void> = undefined;
|
|
flushSync(() => {
|
|
result = callback();
|
|
});
|
|
await result;
|
|
}
|
|
|
|
let activeRoot: Root | null = null;
|
|
let activeHost: HTMLDivElement | null = null;
|
|
|
|
function mount(node: ReactNode): HTMLDivElement {
|
|
const host = document.createElement("div");
|
|
document.body.appendChild(host);
|
|
const root = createRoot(host);
|
|
act(() => {
|
|
root.render(node);
|
|
});
|
|
activeRoot = root;
|
|
activeHost = host;
|
|
return host;
|
|
}
|
|
|
|
afterEach(() => {
|
|
if (activeRoot) {
|
|
const root = activeRoot;
|
|
act(() => root.unmount());
|
|
}
|
|
activeHost?.remove();
|
|
activeRoot = null;
|
|
activeHost = null;
|
|
});
|
|
|
|
describe("AssigneeChip", () => {
|
|
it("renders an agent chip with a screen-reader 'Agent' prefix", () => {
|
|
const host = mount(<AssigneeChip assignee={{ agentId: "agent-qa", userId: null }} resolvers={resolvers} />);
|
|
const chip = host.querySelector<HTMLElement>("[data-testid='handoff-assignee-chip']")!;
|
|
expect(chip.dataset.kind).toBe("agent");
|
|
expect(chip.textContent).toContain("Agent");
|
|
expect(chip.textContent).toContain("QA");
|
|
});
|
|
|
|
it("renders a user chip with '(you)' and a 'User' prefix — never an agent look", () => {
|
|
const host = mount(<AssigneeChip assignee={{ agentId: null, userId: "user-board" }} resolvers={resolvers} />);
|
|
const chip = host.querySelector<HTMLElement>("[data-testid='handoff-assignee-chip']")!;
|
|
expect(chip.dataset.kind).toBe("user");
|
|
expect(chip.textContent).toContain("User");
|
|
expect(chip.textContent).toContain("Riley Board (you)");
|
|
});
|
|
|
|
it("renders unassigned as italic text, not a chip", () => {
|
|
const host = mount(<AssigneeChip assignee={{ agentId: null, userId: null }} resolvers={resolvers} />);
|
|
const chip = host.querySelector<HTMLElement>("[data-testid='handoff-assignee-chip']")!;
|
|
expect(chip.dataset.kind).toBe("unassigned");
|
|
expect(chip.textContent).toContain("Unassigned");
|
|
});
|
|
});
|
|
|
|
describe("HandoffWakeRow", () => {
|
|
it("A. agent destination = queued wake", () => {
|
|
const host = mount(
|
|
<HandoffWakeRow to={{ agentId: "agent-qa", userId: null }} resolvers={resolvers} interruptedRunAttached />,
|
|
);
|
|
const row = host.querySelector<HTMLElement>("[data-testid='handoff-wake-row']")!;
|
|
expect(row.dataset.kind).toBe("agent_wake");
|
|
expect(row.textContent).toContain("queued for QA");
|
|
expect(row.textContent).toContain("interrupted run attached");
|
|
});
|
|
|
|
it("B. user destination = no wake", () => {
|
|
const host = mount(<HandoffWakeRow to={{ agentId: null, userId: "user-board" }} resolvers={resolvers} />);
|
|
const row = host.querySelector<HTMLElement>("[data-testid='handoff-wake-row']")!;
|
|
expect(row.dataset.kind).toBe("user_handoff");
|
|
expect(row.textContent).toContain("not created");
|
|
});
|
|
|
|
it("C. unassigned = no agent selected", () => {
|
|
const host = mount(<HandoffWakeRow to={{ agentId: null, userId: null }} resolvers={resolvers} />);
|
|
const row = host.querySelector<HTMLElement>("[data-testid='handoff-wake-row']")!;
|
|
expect(row.dataset.kind).toBe("unassigned");
|
|
expect(row.textContent).toContain("no agent selected");
|
|
});
|
|
});
|
|
|
|
describe("RunStatusBadge", () => {
|
|
it("shows amber 'interrupted' for an operator interrupt", () => {
|
|
const host = mount(<RunStatusBadge status="cancelled" operatorInterrupted />);
|
|
const badge = host.querySelector<HTMLElement>("[data-testid='run-status-badge']")!;
|
|
expect(badge.textContent).toContain("interrupted");
|
|
expect(badge.className).toContain("amber");
|
|
expect(badge.dataset.interrupted).toBe("true");
|
|
});
|
|
|
|
it("shows muted 'cancelled' for a plain cancel", () => {
|
|
const host = mount(<RunStatusBadge status="cancelled" />);
|
|
const badge = host.querySelector<HTMLElement>("[data-testid='run-status-badge']")!;
|
|
expect(badge.textContent).toContain("cancelled");
|
|
expect(badge.className).toContain("muted");
|
|
});
|
|
});
|
|
|
|
describe("ComposerHandoffPreviewRow", () => {
|
|
it("renders the interrupt+handoff intent with an agent chip", () => {
|
|
const preview = computeComposerHandoffPreview({
|
|
reassignTarget: "agent:agent-qa",
|
|
currentAssigneeValue: "agent:agent-claude",
|
|
hasActiveRun: true,
|
|
bodyHasAgentMention: false,
|
|
plainNameCandidate: null,
|
|
});
|
|
const host = mount(<ComposerHandoffPreviewRow preview={preview} resolvers={resolvers} />);
|
|
const row = host.querySelector<HTMLElement>("[data-testid='composer-handoff-preview']")!;
|
|
expect(row.dataset.kind).toBe("interrupt_handoff_agent");
|
|
expect(row.textContent).toContain("Interrupt current run, hand off to");
|
|
expect(row.textContent).toContain("QA");
|
|
});
|
|
|
|
it("renders the amber plain-text warning with no chip", () => {
|
|
const preview = computeComposerHandoffPreview({
|
|
reassignTarget: "agent:agent-claude",
|
|
currentAssigneeValue: "agent:agent-claude",
|
|
hasActiveRun: true,
|
|
bodyHasAgentMention: false,
|
|
plainNameCandidate: { agentId: "agent-qa", matchedText: "QA" },
|
|
});
|
|
const host = mount(<ComposerHandoffPreviewRow preview={preview} resolvers={resolvers} />);
|
|
const row = host.querySelector<HTMLElement>("[data-testid='composer-handoff-preview']")!;
|
|
expect(row.dataset.kind).toBe("plain_text_only");
|
|
expect(row.className).toContain("amber");
|
|
expect(host.querySelector("[data-testid='handoff-assignee-chip']")).toBeNull();
|
|
});
|
|
|
|
it("renders nothing for the 'none' state", () => {
|
|
const preview = computeComposerHandoffPreview({
|
|
reassignTarget: "agent:agent-claude",
|
|
currentAssigneeValue: "agent:agent-claude",
|
|
hasActiveRun: true,
|
|
bodyHasAgentMention: false,
|
|
plainNameCandidate: null,
|
|
});
|
|
const host = mount(<ComposerHandoffPreviewRow preview={preview} resolvers={resolvers} />);
|
|
expect(host.querySelector("[data-testid='composer-handoff-preview']")).toBeNull();
|
|
});
|
|
});
|
|
|
|
describe("ComposerMentionCoach", () => {
|
|
it("offers an Insert mention action and is dismissible", () => {
|
|
const onInsert = vi.fn();
|
|
const onDismiss = vi.fn();
|
|
const host = mount(
|
|
<ComposerMentionCoach
|
|
candidate={{ agentId: "agent-qa", matchedText: "QA" }}
|
|
agentDisplayName="QA"
|
|
onInsert={onInsert}
|
|
onDismiss={onDismiss}
|
|
/>,
|
|
);
|
|
const insertBtn = host.querySelector<HTMLButtonElement>("[aria-label^='Insert mention for QA']")!;
|
|
act(() => insertBtn.click());
|
|
expect(onInsert).toHaveBeenCalledOnce();
|
|
const dismissBtn = host.querySelector<HTMLButtonElement>("[aria-label='Dismiss suggestion']")!;
|
|
act(() => dismissBtn.click());
|
|
expect(onDismiss).toHaveBeenCalledOnce();
|
|
});
|
|
});
|
|
|
|
describe("AssigneeRunningBanner", () => {
|
|
it("announces the interrupt as a status with the running agent name", () => {
|
|
const host = mount(
|
|
<AssigneeRunningBanner copy={describeReassignInterrupt({ runningAgentName: "ClaudeCoder" })} />,
|
|
);
|
|
const banner = host.querySelector<HTMLElement>("[data-testid='assignee-running-banner']")!;
|
|
expect(banner.getAttribute("role")).toBe("status");
|
|
expect(banner.textContent).toContain("ClaudeCoder is running");
|
|
});
|
|
});
|
|
|
|
describe("InterruptAssignConfirm", () => {
|
|
it("renders the target chip and wires confirm/cancel", () => {
|
|
const onConfirm = vi.fn();
|
|
const onCancel = vi.fn();
|
|
const host = mount(
|
|
<InterruptAssignConfirm
|
|
copy={describeReassignInterrupt({ runningAgentName: "ClaudeCoder" })}
|
|
to={{ agentId: "agent-qa", userId: null }}
|
|
resolvers={resolvers}
|
|
onConfirm={onConfirm}
|
|
onCancel={onCancel}
|
|
/>,
|
|
);
|
|
expect(host.querySelector("[data-testid='handoff-assignee-chip']")?.textContent).toContain("QA");
|
|
const confirmBtn = host.querySelector<HTMLButtonElement>("[data-testid='interrupt-assign-confirm-action']")!;
|
|
act(() => confirmBtn.click());
|
|
expect(onConfirm).toHaveBeenCalledOnce();
|
|
const cancelBtn = Array.from(host.querySelectorAll<HTMLButtonElement>("button")).find(
|
|
(b) => b.textContent === "Cancel",
|
|
)!;
|
|
act(() => cancelBtn.click());
|
|
expect(onCancel).toHaveBeenCalledOnce();
|
|
});
|
|
});
|
|
|
|
describe("PauseAffectsSummaryView", () => {
|
|
it("renders only non-zero buckets with counts", () => {
|
|
const summary = computePauseAffectsSummary([
|
|
{ assigneeAgentId: "a1", assigneeUserId: null, activeRun: { status: "running" } },
|
|
{ assigneeAgentId: null, assigneeUserId: "u1", activeRun: null },
|
|
]);
|
|
const host = mount(<PauseAffectsSummaryView summary={summary} />);
|
|
expect(host.querySelector("[data-bucket='live_runs']")?.textContent).toContain("1");
|
|
expect(host.querySelector("[data-bucket='human_owned']")?.textContent).toContain("1");
|
|
// Empty buckets are hidden.
|
|
expect(host.querySelector("[data-bucket='static']")).toBeNull();
|
|
expect(host.querySelector("[data-testid='pause-nothing-live']")).toBeNull();
|
|
});
|
|
|
|
it("shows the 'Nothing live to pause' status when no run is live", () => {
|
|
const summary = computePauseAffectsSummary([
|
|
{ assigneeAgentId: null, assigneeUserId: "u1", activeRun: null },
|
|
]);
|
|
const host = mount(<PauseAffectsSummaryView summary={summary} />);
|
|
const note = host.querySelector<HTMLElement>("[data-testid='pause-nothing-live']")!;
|
|
expect(note.getAttribute("role")).toBe("status");
|
|
expect(note.textContent).toContain("Nothing live to pause");
|
|
});
|
|
});
|