[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
@@ -50,6 +50,7 @@ const mockAgentService = vi.hoisted(() => ({
|
||||
getById: vi.fn(),
|
||||
pause: vi.fn(),
|
||||
resume: vi.fn(),
|
||||
clearError: vi.fn(),
|
||||
terminate: vi.fn(),
|
||||
remove: vi.fn(),
|
||||
listKeys: vi.fn(),
|
||||
@@ -276,6 +277,7 @@ function resetMockDefaults() {
|
||||
mockAgentService.getById.mockImplementation(async () => ({ ...baseAgent }));
|
||||
mockAgentService.pause.mockImplementation(async () => ({ ...baseAgent }));
|
||||
mockAgentService.resume.mockImplementation(async () => ({ ...baseAgent }));
|
||||
mockAgentService.clearError.mockImplementation(async () => ({ ...baseAgent, status: "idle" }));
|
||||
mockAgentService.terminate.mockImplementation(async () => ({ ...baseAgent }));
|
||||
mockAgentService.remove.mockImplementation(async () => ({ ...baseAgent }));
|
||||
mockAgentService.listKeys.mockImplementation(async () => []);
|
||||
@@ -334,6 +336,12 @@ describe.sequential("agent cross-tenant route authorization", () => {
|
||||
requestApp(app, (baseUrl) => request(baseUrl).post(`/api/agents/${agentId}/pause`).send({})),
|
||||
untouched: [mockAgentService.pause, mockHeartbeatService.cancelActiveForAgent],
|
||||
},
|
||||
{
|
||||
label: "clear error",
|
||||
request: (app: express.Express) =>
|
||||
requestApp(app, (baseUrl) => request(baseUrl).post(`/api/agents/${agentId}/clear-error`).send({})),
|
||||
untouched: [mockAgentService.clearError],
|
||||
},
|
||||
{
|
||||
label: "list keys",
|
||||
request: (app: express.Express) =>
|
||||
@@ -386,4 +394,117 @@ describe.sequential("agent cross-tenant route authorization", () => {
|
||||
expect(mockAgentService.getKeyById).toHaveBeenCalledWith(keyId);
|
||||
expect(mockAgentService.revokeKey).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("requires board access before clearing an agent error", async () => {
|
||||
const app = await createApp({
|
||||
type: "agent",
|
||||
agentId,
|
||||
companyId,
|
||||
runId: "run-1",
|
||||
});
|
||||
|
||||
const res = await requestApp(app, (baseUrl) =>
|
||||
request(baseUrl).post(`/api/agents/${agentId}/clear-error`).send({}),
|
||||
);
|
||||
|
||||
expect(res.status).toBe(403);
|
||||
expect(res.body.error).toContain("Board access required");
|
||||
expect(mockAgentService.clearError).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("clears error agents and records a distinct audit action", async () => {
|
||||
const errorAgent = {
|
||||
...baseAgent,
|
||||
status: "error",
|
||||
pauseReason: "system",
|
||||
pausedAt: new Date("2026-04-11T00:02:00.000Z"),
|
||||
};
|
||||
mockAgentService.getById.mockImplementation(async () => ({ ...errorAgent }));
|
||||
mockAgentService.clearError.mockImplementation(async () => ({
|
||||
...errorAgent,
|
||||
status: "idle",
|
||||
pauseReason: null,
|
||||
pausedAt: null,
|
||||
updatedAt: new Date("2026-04-11T00:03:00.000Z"),
|
||||
}));
|
||||
const app = await createApp({
|
||||
type: "board",
|
||||
userId: "board-user",
|
||||
companyIds: [companyId],
|
||||
source: "local_implicit",
|
||||
isInstanceAdmin: true,
|
||||
});
|
||||
|
||||
const res = await requestApp(app, (baseUrl) =>
|
||||
request(baseUrl).post(`/api/agents/${agentId}/clear-error`).send({}),
|
||||
);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.body).toMatchObject({
|
||||
id: agentId,
|
||||
status: "idle",
|
||||
pauseReason: null,
|
||||
pausedAt: null,
|
||||
});
|
||||
expect(mockAgentService.clearError).toHaveBeenCalledWith(agentId);
|
||||
expect(mockLogActivity).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
|
||||
companyId,
|
||||
actorType: "user",
|
||||
actorId: "board-user",
|
||||
action: "agent.error_cleared",
|
||||
entityType: "agent",
|
||||
entityId: agentId,
|
||||
}));
|
||||
});
|
||||
|
||||
it("returns 409 and does not mutate when the agent org chain is invalid", async () => {
|
||||
mockAgentService.getById.mockImplementation(async () => ({
|
||||
...baseAgent,
|
||||
status: "error",
|
||||
orgChainHealth: {
|
||||
status: "invalid_org_chain",
|
||||
reason: "missing_manager",
|
||||
repairGuidance: "Repair the reporting chain first.",
|
||||
},
|
||||
}));
|
||||
const app = await createApp({
|
||||
type: "board",
|
||||
userId: "board-user",
|
||||
companyIds: [companyId],
|
||||
source: "local_implicit",
|
||||
isInstanceAdmin: true,
|
||||
});
|
||||
|
||||
const res = await requestApp(app, (baseUrl) =>
|
||||
request(baseUrl).post(`/api/agents/${agentId}/clear-error`).send({}),
|
||||
);
|
||||
|
||||
expect(res.status).toBe(409);
|
||||
expect(res.body.error).toContain("Repair the reporting chain first");
|
||||
expect(mockAgentService.clearError).not.toHaveBeenCalled();
|
||||
expect(mockLogActivity).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("returns a clear 409 for non-error agents", async () => {
|
||||
const { conflict } = await import("../errors.js");
|
||||
mockAgentService.getById.mockImplementation(async () => ({ ...baseAgent, status: "idle" }));
|
||||
mockAgentService.clearError.mockImplementation(async () => {
|
||||
throw conflict("Only agents in error status can have their error cleared");
|
||||
});
|
||||
const app = await createApp({
|
||||
type: "board",
|
||||
userId: "board-user",
|
||||
companyIds: [companyId],
|
||||
source: "local_implicit",
|
||||
isInstanceAdmin: true,
|
||||
});
|
||||
|
||||
const res = await requestApp(app, (baseUrl) =>
|
||||
request(baseUrl).post(`/api/agents/${agentId}/clear-error`).send({}),
|
||||
);
|
||||
|
||||
expect(res.status).toBe(409);
|
||||
expect(res.body.error).toBe("Only agents in error status can have their error cleared");
|
||||
expect(mockLogActivity).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user