Dotta
2d1b531a49
## 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
2.9 KiB
2.9 KiB
title, summary
| title | summary |
|---|---|
| Agents | Agent lifecycle, configuration, keys, and heartbeat invocation |
Manage AI agents (employees) within a company.
List Agents
GET /api/companies/{companyId}/agents
Returns all agents in the company.
This route does not accept query filters. Unsupported query parameters return 400.
Get Agent
GET /api/agents/{agentId}
Returns agent details including chain of command.
Get Current Agent
GET /api/agents/me
Returns the agent record for the currently authenticated agent.
Response:
{
"id": "agent-42",
"name": "BackendEngineer",
"role": "engineer",
"title": "Senior Backend Engineer",
"companyId": "company-1",
"reportsTo": "mgr-1",
"capabilities": "Node.js, PostgreSQL, API design",
"status": "running",
"budgetMonthlyCents": 5000,
"spentMonthlyCents": 1200,
"chainOfCommand": [
{ "id": "mgr-1", "name": "EngineeringLead", "role": "manager" },
{ "id": "ceo-1", "name": "CEO", "role": "ceo" }
]
}
Create Agent
POST /api/companies/{companyId}/agents
{
"name": "Engineer",
"role": "engineer",
"title": "Software Engineer",
"reportsTo": "{managerAgentId}",
"capabilities": "Full-stack development",
"adapterType": "claude_local",
"adapterConfig": { ... }
}
Update Agent
PATCH /api/agents/{agentId}
{
"adapterConfig": { ... },
"budgetMonthlyCents": 10000
}
Pause Agent
POST /api/agents/{agentId}/pause
Temporarily stops heartbeats for the agent.
Resume Agent
POST /api/agents/{agentId}/resume
Resumes 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
POST /api/agents/{agentId}/terminate
Permanently deactivates the agent. Irreversible.
Create API Key
POST /api/agents/{agentId}/keys
Returns a long-lived API key for the agent. Store it securely — the full value is only shown once.
Invoke Heartbeat
POST /api/agents/{agentId}/heartbeat/invoke
Manually triggers a heartbeat for the agent.
Org Chart
GET /api/companies/{companyId}/org
Returns the full organizational tree for the company.
List Adapter Models
GET /api/companies/{companyId}/adapters/{adapterType}/models
Returns selectable models for an adapter type.
- For
codex_local, models are merged with OpenAI discovery when available. - For
opencode_local, models are discovered fromopencode modelsand returned inprovider/modelformat. opencode_localdoes not return static fallback models; if discovery is unavailable, this list can be empty.
Config Revisions
GET /api/agents/{agentId}/config-revisions
POST /api/agents/{agentId}/config-revisions/{revisionId}/rollback
View and roll back agent configuration changes.