[codex] Add clear-error agent action (#7695)
## Thinking Path > - Paperclip is the open source control plane people use to manage AI agents for work. > - Agent runtime state is surfaced in both the server API and the board UI so operators can tell whether an agent is idle, running, paused, or in error. > - When an agent is already in `error`, the existing pause/resume action slot is not useful because there is no running work to pause. > - Operators need a direct, audited recovery path that clears the stale error state only for agents in the same company. > - This pull request adds a company-scoped clear-error mutation, exposes the shared API contract, and wires the board action cluster to show Clear error in the pause/resume slot for errored agents. > - The benefit is that operators can recover CEO/CTO-style errored agents without resorting to database edits or unrelated session reset actions. ## Linked Issues or Issue Description Refs #4021 Paperclip issue: PAP-10515 — right now the CEO and CTO agents are in error state, but there is no way to clear the error; they appear otherwise fine. ## What Changed - Added shared constants, API path, and agent status type support for a company-scoped clear-error action. - Added the server service and route to clear an agent from `error` back to `idle`, with company access enforcement and activity logging. - Added OpenAPI/docs coverage for the clear-error endpoint. - Added backend coverage for service behavior and cross-tenant authorization. - Updated the board agent action cluster to show a red-tinted Clear error button only when `agent.status === "error"`. - Updated agent properties to show a red active last-error indicator only while the agent is currently errored. - Added UI component tests for the error-state action and the non-error pause/resume behavior. ## Verification Local: - `pnpm exec vitest run server/src/__tests__/agents-service-clear-error.test.ts server/src/__tests__/agent-cross-tenant-authz-routes.test.ts ui/src/components/AgentActionButtons.test.tsx` - `pnpm --filter @paperclipai/ui typecheck` - `pnpm exec vitest run server/src/__tests__/openapi-routes.test.ts` PR checks: - Main Paperclip workflow is green on `a7378e584d50594e7bd507a1a02985bfaaa5abf8`. - Greptile is 5/5 with no files requiring special attention and no new comments on the latest review. - `commitperclip PR Review` is still red because its security-gate step canceled after filing a draft advisory; the linked `security-review` check is neutral and says the draft advisory is not a merge block. Visual artifact: -  ## Risks Low to medium risk. The mutation is intentionally narrow, but reviewers should check that clearing `lastError`/`lastRunError` and returning to `idle` is the desired recovery semantics for every adapter state. The remaining red check is from the external commitperclip security-review workflow, not from the code/test workflow for this PR. > 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-family coding model, tool-assisted with local shell, git, GitHub CLI, and targeted Vitest 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 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 - [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 - [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
This commit is contained in:
Dotta
@@ -0,0 +1,178 @@
|
||||
// @vitest-environment jsdom
|
||||
|
||||
import type { ReactNode } from "react";
|
||||
import { flushSync } from "react-dom";
|
||||
import { createRoot } from "react-dom/client";
|
||||
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
|
||||
import type { Agent } from "@paperclipai/shared";
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { AgentActionButtons } from "./AgentActionButtons";
|
||||
|
||||
const mockNavigate = vi.hoisted(() => vi.fn());
|
||||
const mockOpenNewIssue = vi.hoisted(() => vi.fn());
|
||||
const mockPushToast = vi.hoisted(() => vi.fn());
|
||||
const mockAgentsApi = vi.hoisted(() => ({
|
||||
invoke: vi.fn(),
|
||||
pause: vi.fn(),
|
||||
resume: vi.fn(),
|
||||
clearError: vi.fn(),
|
||||
approve: vi.fn(),
|
||||
terminate: vi.fn(),
|
||||
resetSession: vi.fn(),
|
||||
instructionsBundle: vi.fn(),
|
||||
instructionsFile: vi.fn(),
|
||||
create: vi.fn(),
|
||||
hire: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/router", () => ({
|
||||
Link: ({ children, to, ...props }: { children: ReactNode; to: string }) => (
|
||||
<a href={to} {...props}>{children}</a>
|
||||
),
|
||||
useNavigate: () => mockNavigate,
|
||||
}));
|
||||
|
||||
vi.mock("../context/DialogContext", () => ({
|
||||
useDialogActions: () => ({ openNewIssue: mockOpenNewIssue }),
|
||||
}));
|
||||
|
||||
vi.mock("../context/ToastContext", () => ({
|
||||
useToastActions: () => ({ pushToast: mockPushToast }),
|
||||
}));
|
||||
|
||||
vi.mock("../api/agents", () => ({
|
||||
agentsApi: mockAgentsApi,
|
||||
}));
|
||||
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
|
||||
|
||||
async function act(callback: () => void | Promise<void>) {
|
||||
let result: void | Promise<void> = undefined;
|
||||
flushSync(() => {
|
||||
result = callback();
|
||||
});
|
||||
await result;
|
||||
}
|
||||
|
||||
async function flushReact() {
|
||||
await act(async () => {
|
||||
await Promise.resolve();
|
||||
await new Promise((resolve) => window.setTimeout(resolve, 0));
|
||||
});
|
||||
}
|
||||
|
||||
function makeAgent(overrides: Partial<Agent> = {}): Agent {
|
||||
return {
|
||||
id: "agent-1",
|
||||
companyId: "company-1",
|
||||
name: "Alpha Agent",
|
||||
urlKey: "alpha",
|
||||
role: "engineer",
|
||||
title: null,
|
||||
icon: null,
|
||||
status: "active",
|
||||
reportsTo: null,
|
||||
capabilities: null,
|
||||
adapterType: "codex_local",
|
||||
adapterConfig: {},
|
||||
runtimeConfig: {},
|
||||
budgetMonthlyCents: 0,
|
||||
spentMonthlyCents: 0,
|
||||
pauseReason: null,
|
||||
pausedAt: null,
|
||||
permissions: { canCreateAgents: false },
|
||||
lastHeartbeatAt: null,
|
||||
metadata: null,
|
||||
createdAt: new Date("2026-01-01T00:00:00Z"),
|
||||
updatedAt: new Date("2026-01-01T00:00:00Z"),
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe("AgentActionButtons", () => {
|
||||
let container: HTMLDivElement;
|
||||
let root: ReturnType<typeof createRoot> | null;
|
||||
let queryClient: QueryClient;
|
||||
let invalidateQueries: ReturnType<typeof vi.spyOn>;
|
||||
|
||||
beforeEach(() => {
|
||||
container = document.createElement("div");
|
||||
document.body.appendChild(container);
|
||||
root = null;
|
||||
queryClient = new QueryClient({
|
||||
defaultOptions: { queries: { retry: false } },
|
||||
});
|
||||
invalidateQueries = vi.spyOn(queryClient, "invalidateQueries");
|
||||
mockAgentsApi.clearError.mockResolvedValue(makeAgent({ status: "idle" }));
|
||||
mockAgentsApi.pause.mockResolvedValue(makeAgent({ status: "paused" }));
|
||||
mockAgentsApi.resume.mockResolvedValue(makeAgent({ status: "idle" }));
|
||||
mockAgentsApi.invoke.mockResolvedValue({ id: "run-1" });
|
||||
mockAgentsApi.resetSession.mockResolvedValue(undefined);
|
||||
});
|
||||
|
||||
afterEach(async () => {
|
||||
const currentRoot = root;
|
||||
if (currentRoot) {
|
||||
await act(async () => {
|
||||
currentRoot.unmount();
|
||||
});
|
||||
}
|
||||
queryClient.clear();
|
||||
container.remove();
|
||||
document.body.innerHTML = "";
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
function render(agent: Agent) {
|
||||
root = createRoot(container);
|
||||
root.render(
|
||||
<QueryClientProvider client={queryClient}>
|
||||
<AgentActionButtons agent={agent} companyId="company-1" runLabel="Run Heartbeat" />
|
||||
</QueryClientProvider>,
|
||||
);
|
||||
}
|
||||
|
||||
it("replaces the pause slot with Clear error for error agents", async () => {
|
||||
render(makeAgent({ status: "error" }));
|
||||
await flushReact();
|
||||
|
||||
expect(container.textContent).toContain("Clear error");
|
||||
expect(container.textContent).not.toContain("Pause");
|
||||
expect(container.textContent).toContain("Run Heartbeat");
|
||||
|
||||
await act(async () => {
|
||||
container.querySelector<HTMLButtonElement>('[aria-label="Open actions for Alpha Agent"]')?.click();
|
||||
});
|
||||
await flushReact();
|
||||
|
||||
expect(document.body.textContent).toContain("Reset Sessions");
|
||||
});
|
||||
|
||||
it("calls clearError and refreshes agent-related queries", async () => {
|
||||
render(makeAgent({ status: "error" }));
|
||||
await flushReact();
|
||||
|
||||
await act(async () => {
|
||||
container.querySelector<HTMLButtonElement>('[aria-label="Clear error and return agent to idle"]')?.click();
|
||||
});
|
||||
await flushReact();
|
||||
|
||||
expect(mockAgentsApi.clearError).toHaveBeenCalledWith("agent-1", "company-1");
|
||||
expect(invalidateQueries).toHaveBeenCalledWith({ queryKey: ["agents", "detail", "agent-1"] });
|
||||
expect(invalidateQueries).toHaveBeenCalledWith({ queryKey: ["agents", "detail", "alpha"] });
|
||||
expect(invalidateQueries).toHaveBeenCalledWith({ queryKey: ["agents", "runtime-state", "agent-1"] });
|
||||
expect(invalidateQueries).toHaveBeenCalledWith({ queryKey: ["agents", "task-sessions", "agent-1"] });
|
||||
expect(invalidateQueries).toHaveBeenCalledWith({ queryKey: ["agents", "company-1"] });
|
||||
expect(invalidateQueries).toHaveBeenCalledWith({ queryKey: ["live-runs", "company-1"] });
|
||||
expect(invalidateQueries).toHaveBeenCalledWith({ queryKey: ["heartbeats", "company-1", "agent-1"] });
|
||||
});
|
||||
|
||||
it("keeps the normal pause action for non-error agents", async () => {
|
||||
render(makeAgent({ status: "active" }));
|
||||
await flushReact();
|
||||
|
||||
expect(container.textContent).toContain("Pause");
|
||||
expect(container.textContent).not.toContain("Clear error");
|
||||
});
|
||||
});
|
||||
@@ -10,6 +10,7 @@ import {
|
||||
Copy,
|
||||
RotateCcw,
|
||||
Trash2,
|
||||
CheckCircle2,
|
||||
} from "lucide-react";
|
||||
import { Button } from "@/components/ui/button";
|
||||
import {
|
||||
@@ -85,6 +86,30 @@ export function PauseResumeButton({
|
||||
);
|
||||
}
|
||||
|
||||
export function ClearErrorButton({
|
||||
onClick,
|
||||
disabled,
|
||||
size = "sm",
|
||||
}: {
|
||||
onClick: () => void;
|
||||
disabled?: boolean;
|
||||
size?: "sm" | "default";
|
||||
}) {
|
||||
return (
|
||||
<Button
|
||||
variant="outline"
|
||||
size={size}
|
||||
onClick={onClick}
|
||||
disabled={disabled}
|
||||
className="border-destructive/60 text-destructive hover:bg-destructive/10 hover:text-destructive dark:border-destructive/50"
|
||||
aria-label="Clear error and return agent to idle"
|
||||
>
|
||||
<CheckCircle2 className="h-3.5 w-3.5 sm:mr-1" />
|
||||
<span className="hidden sm:inline">Clear error</span>
|
||||
</Button>
|
||||
);
|
||||
}
|
||||
|
||||
function duplicateInstructionFilePath(
|
||||
_bundle: AgentInstructionsBundle,
|
||||
summary: AgentInstructionsFileSummary,
|
||||
@@ -162,6 +187,7 @@ export function AgentActionButtons({
|
||||
const resolvedCompanyId = companyId ?? agent.companyId;
|
||||
const canonicalAgentRef = agentRouteRef(agent);
|
||||
const isPaused = agent.status === "paused";
|
||||
const isError = agent.status === "error";
|
||||
|
||||
const reportError = useCallback(
|
||||
(message: string) => {
|
||||
@@ -187,11 +213,12 @@ export function AgentActionButtons({
|
||||
}, [agent.id, canonicalAgentRef, queryClient, resolvedCompanyId]);
|
||||
|
||||
const agentAction = useMutation({
|
||||
mutationFn: async (action: "invoke" | "pause" | "resume" | "approve" | "terminate") => {
|
||||
mutationFn: async (action: "invoke" | "pause" | "resume" | "clear_error" | "approve" | "terminate") => {
|
||||
switch (action) {
|
||||
case "invoke": return agentsApi.invoke(agent.id, resolvedCompanyId ?? undefined);
|
||||
case "pause": return agentsApi.pause(agent.id, resolvedCompanyId ?? undefined);
|
||||
case "resume": return agentsApi.resume(agent.id, resolvedCompanyId ?? undefined);
|
||||
case "clear_error": return agentsApi.clearError(agent.id, resolvedCompanyId ?? undefined);
|
||||
case "approve": return agentsApi.approve(agent.id, resolvedCompanyId ?? undefined);
|
||||
case "terminate": return agentsApi.terminate(agent.id, resolvedCompanyId ?? undefined);
|
||||
}
|
||||
@@ -265,6 +292,7 @@ export function AgentActionButtons({
|
||||
const disabled = actionsDisabled || agentAction.isPending;
|
||||
const assignAndRunDisabled = disabled || isPendingApproval || workActionsDisabled;
|
||||
const pauseResumeDisabled = disabled || isPendingApproval || (isPaused && workActionsDisabled);
|
||||
const clearErrorDisabled = disabled;
|
||||
|
||||
return (
|
||||
<div className={className ?? "flex items-center gap-1 sm:gap-2 shrink-0"}>
|
||||
@@ -284,13 +312,21 @@ export function AgentActionButtons({
|
||||
label={runLabel}
|
||||
size={size}
|
||||
/>
|
||||
<PauseResumeButton
|
||||
isPaused={isPaused}
|
||||
onPause={() => agentAction.mutate("pause")}
|
||||
onResume={() => agentAction.mutate("resume")}
|
||||
disabled={pauseResumeDisabled}
|
||||
size={size}
|
||||
/>
|
||||
{isError ? (
|
||||
<ClearErrorButton
|
||||
onClick={() => agentAction.mutate("clear_error")}
|
||||
disabled={clearErrorDisabled}
|
||||
size={size}
|
||||
/>
|
||||
) : (
|
||||
<PauseResumeButton
|
||||
isPaused={isPaused}
|
||||
onPause={() => agentAction.mutate("pause")}
|
||||
onResume={() => agentAction.mutate("resume")}
|
||||
disabled={pauseResumeDisabled}
|
||||
size={size}
|
||||
/>
|
||||
)}
|
||||
{showStatus && (
|
||||
<span className="hidden sm:inline">
|
||||
<AgentStatusBadge status={agent.status} />
|
||||
|
||||
@@ -28,6 +28,7 @@ function PropertyRow({ label, children }: { label: string; children: React.React
|
||||
|
||||
export function AgentProperties({ agent, runtimeState }: AgentPropertiesProps) {
|
||||
const { selectedCompanyId } = useCompany();
|
||||
const lastErrorIsActive = agent.status === "error";
|
||||
|
||||
const { data: agents } = useQuery({
|
||||
queryKey: queryKeys.agents.list(selectedCompanyId!),
|
||||
@@ -67,8 +68,16 @@ export function AgentProperties({ agent, runtimeState }: AgentPropertiesProps) {
|
||||
</PropertyRow>
|
||||
)}
|
||||
{runtimeState?.lastError && (
|
||||
<PropertyRow label="Last error">
|
||||
<span className="text-xs text-red-600 dark:text-red-400 break-words min-w-0">{runtimeState.lastError}</span>
|
||||
<PropertyRow label={lastErrorIsActive ? "Last error" : "Last run error"}>
|
||||
<span
|
||||
className={
|
||||
lastErrorIsActive
|
||||
? "text-xs text-red-600 dark:text-red-400 break-words min-w-0"
|
||||
: "text-xs text-muted-foreground break-words min-w-0"
|
||||
}
|
||||
>
|
||||
{runtimeState.lastError}
|
||||
</span>
|
||||
</PropertyRow>
|
||||
)}
|
||||
{agent.lastHeartbeatAt && (
|
||||
|
||||
Reference in New Issue
Block a user