Files
PaperClipAI/docs/api/agents.md
T
DottaandClaude Opus 5.5 e40a16e5c5 fix(heartbeat): let Stop take a task out of the agent's queue (#21407)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Each agent runs a limited number of tasks at once. Other tasks wait
in line as queued runs.
> - An agent can have hundreds of waiting tasks. People need one click
to take a task out of line.
> - Stop already cancelled a queued run, but a task that was in progress
stayed in progress. It still looked busy.
> - The classic task thread also hid Stop until the run started.
> - This pull request makes Stop on a waiting task free the task and
show it as not started, in both thread views.
> - The benefit is that people can clear a long queue one task at a
time, and the agent moves on to its next task.

## Linked Issues or Issue Description

**What happened?**

An agent had many queued runs. A person pressed Stop on a task that
waited in line. The run was cancelled, but the task stayed "in
progress". In the classic thread, Stop did not show until the run
started.

**Expected behavior**

One Stop click takes the task out of line. The queued run and its wake
are cancelled. The task lock is released. The task does not look in
progress. No new run starts for that task. The agent's next waiting task
still starts. An activity entry records the change.

**Steps to reproduce**

1. Give an agent one run slot and keep it busy.
2. Assign two more in-progress tasks to the agent, so their runs wait in
line.
3. Press Stop on one waiting task.
4. See that the task still shows "in progress".

**Paperclip version or commit**

`master` at 30c718e04b.

**Agent adapter(s) involved**

Not adapter-specific (core bug).

## What Changed

- `POST /heartbeat-runs/:runId/cancel`: when the run was queued, the
route calls the new `returnStoppedWaitingTaskToTodo` after the cancel.
- New `server/src/services/heartbeat/stopped-waiting-task.ts`: one
guarded update moves an `in_progress` task to `todo` and logs
`issue.updated` (reason `stopped_while_waiting`). It changes the task
only if the run never started, the task is still assigned to that agent
and not to a person, the task lock is free or held by that run, and no
other live run exists for the task.
- The route keeps its company and run-read checks and still logs
`heartbeat.cancelled`. Recovery already stands down for an operator
stop, so no new run starts for the task.
- `IssueChatThread` (classic view): the composer shows Stop for a queued
run too, in the same place as a running task's Stop. The default
`TaskChatThread` already did this; a test now covers it. The waiting
banner is unchanged.

## Verification

- `server/src/__tests__/heartbeat-stop-queued-task.test.ts` (new,
embedded Postgres, real heartbeat): one busy slot, two waiting tasks.
Stop one waiting task. The run and wake are cancelled, the lock is
released, the task is `todo`, and an activity entry exists for the
in-progress case. After the slot frees, the next task runs. The stopped
task gets no new run, also after `resumeQueuedRuns` and
`reconcileStrandedAssignedIssues`. The in-progress case was red before
the fix.
- `server/src/__tests__/heartbeat-run-privacy-routes.test.ts`: a real
route test. Another user gets 404 and the task does not change. The
task's operator gets 200, the task becomes `todo`, and both activity
entries are recorded. Red without the route change, green with it. The
full file passes (30/30).
- The same route test sends a correlated Stop (`cancellationRequestId`)
to the waiting legacy run. The server returns 409 and the run and task
do not change. Correlated Stop is for native runs only.
`ui/src/api/heartbeats.test.ts` checks that task Stop sends the plain
request (`{}`).
- `ui/src/components/IssueChatThread.test.tsx` and
`TaskChatThread.test.tsx`: Stop shows for a queued run and calls the
stop action. The classic test was red before the fix.
- `pnpm --filter @paperclipai/server typecheck` and `pnpm --filter
@paperclipai/ui typecheck` pass.

## Risks

- Low risk. The status write is one guarded `UPDATE` and changes nothing
if any guard fails. Only the board Stop route calls it, and only for a
run that was queued.
- A task stopped while waiting shows `todo` instead of `in_progress`.
This is intended. A Stop on a running task does not change its status.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, test runs).

## 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 not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [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
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 09:58:54 -06:00

232 lines
7.9 KiB
Markdown

---
title: Agents
summary: 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.
## Read execution environment identity
Board users with organization access can list environments with
`GET /api/companies/{companyId}/environments` or read one with
`GET /api/environments/{environmentId}`. These routes read instance environments.
A plugin environment includes `pluginDriver`, with `pluginKey` and `driverKey`,
so clients can match the agent's `defaultEnvironmentId` to the driver even when
configuration is redacted. This field does not contain driver configuration,
environment variables, or credentials. An agent with no default inherits the
instance default.
## Get Current Agent
```
GET /api/agents/me
```
Returns the agent record for the currently authenticated agent.
**Response:**
```json
{
"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": "cto" },
{ "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
}
```
### Protected environment variables
A plugin environment driver can declare `protectedEnvironmentKeys`: variables
that it sets on its own tasks. Create, hire, update and configuration rollback
check `adapterConfig.env` against them:
- If the agent's environment (its `defaultEnvironmentId`, or the instance
default when it has none) uses a driver that protects a key, the request
fails with `422` and code `protected_environment_variable`. The response
details name the `keys` and the `environmentId`.
- If another active environment protects the key, the save succeeds. The
response includes `configurationWarnings` entries with code
`protected_environment_variable`, a `field` such as `adapterConfig.env.KEY`,
and a `message` that names those environments.
## 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.
## Stop a Run
```
POST /api/heartbeat-runs/{runId}/cancel
```
Board only. Stops a run that is running or still waiting in line (`queued`). The caller must be able to read the run, or the response is 404. The run and its wake are cancelled, the task's execution lock is released, and a `heartbeat.cancelled` activity entry is logged. Paperclip does not start another run for that task by itself. The agent's next waiting task starts as usual.
When the stopped run was still waiting in line, the task also returns from `in_progress` to `todo`, and an `issue.updated` activity entry is logged with the reason `stopped_while_waiting`. The task is left unchanged when any of these is true:
- The run had already started.
- The task is not `in_progress`.
- The task is no longer assigned to that agent, or it is assigned to a person.
- Another run holds the task's execution lock, or another run for the task is queued, running, or scheduled to retry.
Send an empty body. The optional `cancellationRequestId` is only for native runs; for any other run, the response is `409`.
## Assigned-Work Invariant Report
```
GET /api/companies/{companyId}/assigned-work-invariant
```
Board only. Read-only. Classifies every open task assigned to an agent (`todo`, `in_progress`, `blocked`): it has a live run, a pending intent that will start one, a named wait that is someone else's move, or it is a violation. Paperclip continues violations automatically; after a deploy, `violationCount` should return to 0.
The response contains:
- `checked`: the number of tasks classified, newest-updated first. At most 2,000.
- `openTasks`: the number of open agent-assigned tasks the caller may read. When it exceeds 2,000, `truncated` and `violationCountIsLowerBound` are `true`: the counts cover only the 2,000 newest tasks, so the real violation count can be higher, never lower.
- Only tasks the caller may read are counted; private tasks the caller cannot read are left out of every count and sample. On an instance with a worktree execution cutoff, the sweep skips tasks created before the cutoff, but the report still counts them.
- `ok`: counts by clause, for example `live_run`, `pending:queued_wake`, `waiting:question`.
- `violations` and `violationCount`: counts by reason (`no_pending_path`, `retry_offered`, `recovery_block`, `unknown_block`, `run_owner_gone`, `native_run_stalled`). `native_run_stalled` is a native run still marked running whose restart-recovery claim nobody renewed for 5 minutes; native recovery ends it, and it stays counted until then.
- `agentsWithStalledSlots`: up to 20 agents whose run slots are held by such stalled runs, with the number of stalled runs and of queued runs waiting behind them.
- `heldByRecoveryOwner`: violations that are blocked under an active recovery hold, which the hold's owner continues.
- `staleBlocked`: tasks blocked by recovery more than 7 days ago. They are reported, not continued.
- `settling`: tasks whose last run ended moments ago and are checked again shortly.
- `sample`: up to 20 violations with the task identifier, status and reason.
## 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 from `opencode models` and returned in `provider/model` format.
- `opencode_local` does 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.
### Rename an instruction file
Use `PUT /api/agents/{id}/instructions-bundle/file` with `path`, `renameTo`,
`content`, and the source file's current `baseHash`. Use `null` only when the
configured root file is missing; a concurrently created root returns `409`. Renames require the same
instruction configuration permission as file writes. The managed file store
checks the source hash and destination under the agent write lock, then updates
the file and the configured root path together. A stale source or occupied
name returns `409`. External bundles must be migrated to managed storage before
using this operation. A successful response contains the renamed file detail.