The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
[codex] Add clear-error agent action (#7695)
Dotta2d1b531a49a9
diff --git a/docs/api/agents.md b/docs/api/agents.mdindex 70e779a9b2..8de6f7dd12 100644--- a/docs/api/agents.md+++ b/docs/api/agents.md@@ -93,6 +93,15 @@ POST /api/agents/{agentId}/resumeResumes heartbeats for a paused agent.+## Clear Agent Error++```+POST /api/agents/{agentId}/clear-error+```++Moves an agent from `error` back to `idle` without deleting run history or runtime diagnostics.+Only agents currently in `error` can be cleared.+## Terminate Agent```diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.tsindex 3a8e7d7c3c..d7e9889fc4 100644--- a/packages/shared/src/constants.ts+++ b/packages/shared/src/constants.ts@@ -1142,6 +1142,7 @@ export const PLUGIN_EVENT_TYPES = ["agent.created","agent.updated","agent.status_changed",+ "agent.error_cleared","agent.run.started","agent.run.finished","agent.run.failed",diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.tsindex 7744af3936..6468e6e457 100644--- a/packages/shared/src/index.ts+++ b/packages/shared/src/index.ts@@ -403,6 +403,7 @@ export type {AgentAccessState,AgentChainOfCommandEntry,AgentDetail,+ ClearAgentErrorResponse,AgentPermissions,AgentInstructionsBundleMode,AgentInstructionsFileSummary,diff --git a/packages/shared/src/types/agent.ts b/packages/shared/src/types/agent.tsindex 806ebfc91f..7027f00f11 100644--- a/packages/shared/src/types/agent.ts+++ b/packages/shared/src/types/agent.ts@@ -109,6 +109,8 @@ export interface AgentDetail extends Agent {access: AgentAccessState;}+export type ClearAgentErrorResponse = Agent;+export interface AgentKeyCreated {id: string;name: string;diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.tsindex b1ea7661f2..8bc246b865 100644--- a/packages/shared/src/types/index.ts+++ b/packages/shared/src/types/index.ts@@ -128,6 +128,7 @@ export type {AgentAccessState,AgentChainOfCommandEntry,AgentDetail,+ ClearAgentErrorResponse,AgentModelProfileConfig,AgentPermissions,AgentRuntimeConfig,diff --git a/server/src/__tests__/agent-cross-tenant-authz-routes.test.ts b/server/src/__tests__/agent-cross-tenant-authz-routes.test.tsindex 1df94d9035..765f0c507f 100644--- a/server/src/__tests__/agent-cross-tenant-authz-routes.test.ts+++ b/server/src/__tests__/agent-cross-tenant-authz-routes.test.ts@@ -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();+ });});diff --git a/server/src/__tests__/agents-service-clear-error.test.ts b/server/src/__tests__/agents-service-clear-error.test.tsnew file mode 100644index 0000000000..1b26416091--- /dev/null+++ b/server/src/__tests__/agents-service-clear-error.test.ts@@ -0,0 +1,236 @@+import { randomUUID } from "node:crypto";+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";+import { eq } from "drizzle-orm";+import {+ agents,+ agentRuntimeState,+ companies,+ createDb,+ heartbeatRunEvents,+ heartbeatRuns,+} from "@paperclipai/db";+import {+ getEmbeddedPostgresTestSupport,+ startEmbeddedPostgresTestDatabase,+} from "./helpers/embedded-postgres.js";+import { agentService } from "../services/agents.ts";++const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;++if (!embeddedPostgresSupport.supported) {+ console.warn(+ `Skipping embedded Postgres agent service tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,+ );+}++describeEmbeddedPostgres("agent service clearError", () => {+ let db!: ReturnType<typeof createDb>;+ let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;++ beforeAll(async () => {+ tempDb = await startEmbeddedPostgresTestDatabase("paperclip-agent-clear-error-");+ db = createDb(tempDb.connectionString);+ }, 20_000);++ afterEach(async () => {+ await db.delete(heartbeatRunEvents);+ await db.delete(agentRuntimeState);+ await db.delete(heartbeatRuns);+ await db.delete(agents);+ await db.delete(companies);+ });++ afterAll(async () => {+ await tempDb?.cleanup();+ });++ it("moves an error agent to idle without deleting run history or runtime diagnostics", async () => {+ const companyId = randomUUID();+ const agentId = randomUUID();+ const runId = randomUUID();+ const issuePrefix = `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`;++ await db.insert(companies).values({+ id: companyId,+ name: "Paperclip",+ issuePrefix,+ requireBoardApprovalForNewAgents: false,+ });++ await db.insert(agents).values({+ id: agentId,+ companyId,+ name: "CodexCoder",+ role: "engineer",+ status: "error",+ pauseReason: "system",+ pausedAt: new Date("2026-06-07T00:00:00.000Z"),+ adapterType: "codex_local",+ adapterConfig: {},+ runtimeConfig: {},+ permissions: {},+ });++ await db.insert(heartbeatRuns).values({+ id: runId,+ companyId,+ agentId,+ invocationSource: "on_demand",+ status: "failed",+ error: "Adapter exited with code 1",+ stdoutExcerpt: "stdout stays inspectable",+ stderrExcerpt: "stderr stays inspectable",+ logStore: "local_disk",+ logRef: "runs/failed.log",+ resultJson: { sessionId: "codex-session-1" },+ finishedAt: new Date("2026-06-07T00:01:00.000Z"),+ });++ await db.insert(heartbeatRunEvents).values({+ companyId,+ runId,+ agentId,+ seq: 1,+ eventType: "transcript",+ stream: "stderr",+ message: "transcript stays inspectable",+ payload: { itemType: "error" },+ });++ await db.insert(agentRuntimeState).values({+ agentId,+ companyId,+ adapterType: "codex_local",+ sessionId: "codex-session-1",+ stateJson: { taskKey: "issue:test" },+ lastRunId: runId,+ lastRunStatus: "failed",+ lastError: "Adapter exited with code 1",+ });++ const cleared = await agentService(db).clearError(agentId);++ expect(cleared).toMatchObject({+ id: agentId,+ status: "idle",+ pauseReason: null,+ pausedAt: null,+ });++ const [run] = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, runId));+ expect(run).toMatchObject({+ id: runId,+ status: "failed",+ error: "Adapter exited with code 1",+ stdoutExcerpt: "stdout stays inspectable",+ stderrExcerpt: "stderr stays inspectable",+ logStore: "local_disk",+ logRef: "runs/failed.log",+ });++ const transcriptEvents = await db+ .select()+ .from(heartbeatRunEvents)+ .where(eq(heartbeatRunEvents.runId, runId));+ expect(transcriptEvents).toHaveLength(1);+ expect(transcriptEvents[0]).toMatchObject({+ runId,+ eventType: "transcript",+ stream: "stderr",+ message: "transcript stays inspectable",+ payload: { itemType: "error" },+ });++ const [runtimeState] = await db+ .select()+ .from(agentRuntimeState)+ .where(eq(agentRuntimeState.agentId, agentId));+ expect(runtimeState).toMatchObject({+ agentId,+ sessionId: "codex-session-1",+ stateJson: { taskKey: "issue:test" },+ lastRunId: runId,+ lastRunStatus: "failed",+ lastError: "Adapter exited with code 1",+ });+ });++ it("rejects non-error agents with a 409 conflict", async () => {+ const companyId = randomUUID();+ const agentId = randomUUID();+ const issuePrefix = `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`;++ await db.insert(companies).values({+ id: companyId,+ name: "Paperclip",+ issuePrefix,+ requireBoardApprovalForNewAgents: false,+ });++ await db.insert(agents).values({+ id: agentId,+ companyId,+ name: "CodexCoder",+ role: "engineer",+ status: "idle",+ adapterType: "codex_local",+ adapterConfig: {},+ runtimeConfig: {},+ permissions: {},+ });++ await expect(agentService(db).clearError(agentId)).rejects.toMatchObject({+ status: 409,+ message: "Only agents in error status can have their error cleared",+ });+ });++ it("keeps resume-style terminal and pending-approval protections", async () => {+ const companyId = randomUUID();+ const terminatedAgentId = randomUUID();+ const pendingAgentId = randomUUID();+ const issuePrefix = `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`;++ await db.insert(companies).values({+ id: companyId,+ name: "Paperclip",+ issuePrefix,+ requireBoardApprovalForNewAgents: false,+ });++ await db.insert(agents).values([+ {+ id: terminatedAgentId,+ companyId,+ name: "Terminated",+ role: "engineer",+ status: "terminated",+ adapterType: "codex_local",+ adapterConfig: {},+ runtimeConfig: {},+ permissions: {},+ },+ {+ id: pendingAgentId,+ companyId,+ name: "Pending",+ role: "engineer",+ status: "pending_approval",+ adapterType: "codex_local",+ adapterConfig: {},+ runtimeConfig: {},+ permissions: {},+ },+ ]);++ await expect(agentService(db).clearError(terminatedAgentId)).rejects.toMatchObject({+ status: 409,+ message: "Cannot clear error on terminated agent",+ });+ await expect(agentService(db).clearError(pendingAgentId)).rejects.toMatchObject({+ status: 409,+ message: "Pending approval agents cannot have errors cleared",+ });+ });+});diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.tsindex a44aca543d..fb706f8ece 100644--- a/server/src/routes/agents.ts+++ b/server/src/routes/agents.ts@@ -2879,6 +2879,38 @@ export function agentRoutes(res.json(agent);});+ router.post("/agents/:id/clear-error", async (req, res) => {+ assertBoard(req);+ const id = req.params.id as string;+ const existing = await getAccessibleAgent(req, res, id);+ if (!existing) {+ return;+ }+ if (existing.orgChainHealth?.status === "invalid_org_chain") {+ res.status(409).json({+ error: existing.orgChainHealth?.repairGuidance ?? "Repair this agent's reporting chain before clearing its error",+ });+ return;+ }++ const agent = await svc.clearError(id);+ if (!agent) {+ res.status(404).json({ error: "Agent not found" });+ return;+ }++ await logActivity(db, {+ companyId: agent.companyId,+ actorType: "user",+ actorId: req.actor.userId ?? "board",+ action: "agent.error_cleared",+ entityType: "agent",+ entityId: agent.id,+ });++ res.json(agent);+ });+router.post("/agents/:id/approve", async (req, res) => {assertBoard(req);const id = req.params.id as string;diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.tsindex 7a0b8fb682..4e599695d2 100644--- a/server/src/routes/openapi.ts+++ b/server/src/routes/openapi.ts@@ -418,6 +418,10 @@ const responses = {description: "Not found",content: { "application/json": { schema: ErrorSchema } },},+ conflict: {+ description: "Conflict",+ content: { "application/json": { schema: ErrorSchema } },+ },unprocessable: {description: "Unprocessable entity",content: { "application/json": { schema: ErrorSchema } },@@ -1247,6 +1251,15 @@ registry.registerPath({responses: { 200: r.ok(), 401: r.unauthorized },});+registry.registerPath({+ method: "post",+ path: "/api/agents/{id}/clear-error",+ tags: ["agents"],+ summary: "Clear an agent error",+ request: { params: z.object({ id: z.string() }) },+ responses: { 200: r.ok(), 401: r.unauthorized, 403: r.forbidden, 404: r.notFound, 409: r.conflict },+});+registry.registerPath({method: "post",path: "/api/agents/{id}/terminate",diff --git a/server/src/services/agents.ts b/server/src/services/agents.tsindex dd67518d36..f8d37aef40 100644--- a/server/src/services/agents.ts+++ b/server/src/services/agents.ts@@ -526,6 +526,35 @@ export function agentService(db: Db) {return updated ? getById(updated.id) : null;},+ clearError: async (id: string) => {+ const existing = await getById(id);+ if (!existing) return null;+ if (existing.status === "terminated") throw conflict("Cannot clear error on terminated agent");+ if (existing.status === "pending_approval") {+ throw conflict("Pending approval agents cannot have errors cleared");+ }+ if (existing.status !== "error") {+ throw conflict("Only agents in error status can have their error cleared");+ }++ const updated = await db+ .update(agents)+ .set({+ status: "idle",+ pauseReason: null,+ pausedAt: null,+ updatedAt: new Date(),+ })+ .where(and(eq(agents.id, id), eq(agents.status, "error")))+ .returning()+ .then((rows) => rows[0] ?? null);++ if (!updated) {+ throw conflict("Only agents in error status can have their error cleared");+ }+ return getById(updated.id);+ },+terminate: async (id: string) => {const existing = await getById(id);if (!existing) return null;diff --git a/ui/src/api/agents.ts b/ui/src/api/agents.tsindex e9390b64cf..3dc1fae75a 100644--- a/ui/src/api/agents.ts+++ b/ui/src/api/agents.ts@@ -13,6 +13,7 @@ import type {HeartbeatRun,Approval,AgentConfigRevision,+ ClearAgentErrorResponse,} from "@paperclipai/shared";import type {AdapterModelProfileDefinition,@@ -165,6 +166,8 @@ export const agentsApi = {),pause: (id: string, companyId?: string) => api.post<Agent>(agentPath(id, companyId, "/pause"), {}),resume: (id: string, companyId?: string) => api.post<Agent>(agentPath(id, companyId, "/resume"), {}),+ clearError: (id: string, companyId?: string) =>+ api.post<ClearAgentErrorResponse>(agentPath(id, companyId, "/clear-error"), {}),approve: (id: string, companyId?: string) => api.post<Agent>(agentPath(id, companyId, "/approve"), {}),terminate: (id: string, companyId?: string) => api.post<Agent>(agentPath(id, companyId, "/terminate"), {}),remove: (id: string, companyId?: string) => api.delete<{ ok: true }>(agentPath(id, companyId)),diff --git a/ui/src/components/AgentActionButtons.test.tsx b/ui/src/components/AgentActionButtons.test.tsxnew file mode 100644index 0000000000..14fc4f8717--- /dev/null+++ b/ui/src/components/AgentActionButtons.test.tsx@@ -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");+ });+});diff --git a/ui/src/components/AgentActionButtons.tsx b/ui/src/components/AgentActionButtons.tsxindex 48c12c67d9..56435f97ad 100644--- a/ui/src/components/AgentActionButtons.tsx+++ b/ui/src/components/AgentActionButtons.tsx@@ -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} />diff --git a/ui/src/components/AgentProperties.tsx b/ui/src/components/AgentProperties.tsxindex 26942704cc..0b8dbe87d0 100644--- a/ui/src/components/AgentProperties.tsx+++ b/ui/src/components/AgentProperties.tsx@@ -28,6 +28,7 @@ function PropertyRow({ label, children }: { label: string; children: React.Reactexport 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 && (diff --git a/ui/src/lib/activity-format.ts b/ui/src/lib/activity-format.tsindex 2ff3ee02a1..cf6893959b 100644--- a/ui/src/lib/activity-format.ts+++ b/ui/src/lib/activity-format.ts@@ -57,6 +57,7 @@ const ACTIVITY_ROW_VERBS: Record<string, string> = {"agent.updated": "updated","agent.paused": "paused","agent.resumed": "resumed",+ "agent.error_cleared": "cleared error on","agent.terminated": "terminated","agent.key_created": "created API key for","agent.budget_updated": "updated budget for",@@ -119,6 +120,7 @@ const ISSUE_ACTIVITY_LABELS: Record<string, string> = {"agent.updated": "updated the agent","agent.paused": "paused the agent","agent.resumed": "resumed the agent",+ "agent.error_cleared": "cleared the agent error","agent.terminated": "terminated the agent","heartbeat.invoked": "invoked a heartbeat","heartbeat.cancelled": "cancelled a heartbeat",