mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - An agent gets environment variables from its execution environment, its own configuration, its project, and its routine. Secrets are resolved for each run. > - A plugin environment can run the agent as a native Runner task on its own host, through the environment task contract. > - That contract has no field for the agent's variables. Runs on a plugin environment get only the variables that the plugin sets itself. > - This pull request adds a versioned contract field for the values, sends them on a session handoff, lets Codex commands inherit the variables in an external sandbox, and lets a plugin protect the variables that it sets itself. > - The benefit is that plain and secret variables work on plugin environments in the same way as on local environments. ## Linked Issues or Issue Description Refs #21233. That pull request by @lucktastic finds the same gap and proposes the same capability and field names (`configuredEnvironmentVersion: 1`, `configuredEnvironment`). This pull request uses the same names, so providers implement one contract. It differs in these places: - Codex commands get the variables through an external-sandbox denylist, not through key names sent at `prepare`. A retained Runner does not need a new preparation when a key is added or removed. - A session handoff `resume` gets the values, because it starts a new Runner on another computer. Value changes on the same computer need no new field: Core's process reuse key includes the values, so Core starts a new task. - A driver can declare `protectedEnvironmentKeys`. Paperclip rejects or warns when one is saved. - The run log names skipped variables only for an older provider. Thank you to @lucktastic for the diagnosis and the contract shape. **What happened?** An agent has environment variables, plain and secret. Its runs on a plugin task environment do not get them. `PAPERCLIP_CONFIGURED_ENV_KEYS` in the run lists only the variables that the plugin sets. **Expected behavior** Each run gets the agent's configured variables. **Steps to reproduce** 1. Set a plain and a secret environment variable on an agent. 2. Assign the agent to a plugin environment that provides Runner tasks. 3. Start a run. Read the names in `PAPERCLIP_CONFIGURED_ENV_KEYS` in a command that the agent runs. 4. The agent's names are not in the list. ## What Changed - **SDK contract** (`packages/plugins/sdk/src/environment-tasks.ts`): - A provider advertises `configuredEnvironmentVersion: 1` on `describe`. - `submit` gets `configuredEnvironment`. `resume` gets it only for a session handoff. - Names, count, and sizes have the same limits as the Runner projection. - **Server**: - `createRunnerdBackendWithinSessionClaim` gives the run's configured projection to the plugin task owner. The projection has no provider credentials and no generated runtime keys. - `createPluginRunnerTaskOwner` sends the fields only to a provider with the capability. An older provider gets no new field, and the run log names the variables that were not set. The log never prints values. - **Codex** (`codex-security-config.ts`): - An externally sandboxed launch uses `inherit="all"`, `ignore_default_excludes=true`, and an `exclude` list of Codex's own credentials, instead of an `include_only` list fixed at preparation time. - A test reads the Runner's Codex environment keys, and fails if a new key is not classified. - Host launches keep the bounded allowlist. - **runnerd** (`codex_provider.rs`): `runtime_notification_codex_args` still grants the notification files to read-only profiles when no allowlist is present. Plan mode in an external sandbox needs these grants. - **Protected keys**: - An environment driver can declare `protectedEnvironmentKeys` in its manifest. - Paperclip rejects a protected key on an agent or environment that uses the driver. The 422 has code `protected_environment_variable`. - On a project, a routine, or another agent, Paperclip saves the key. The response has a `configurationWarnings` notice that names the environments. The project and routine pages show the notice as a toast. The agent pages already show configuration warnings. - **Docs**: `doc/plugins/PLUGIN_ENVIRONMENT_TASKS.md` describes the provider obligations. - `tests/runner-e2e/source-sdk-public-inputs.json`: refresh the reviewed SDK source pin. ## Verification - `packages/plugins/sdk`: `vitest run tests/environment-tasks.test.ts` (38 pass). Accepts bounded values. Rejects bad names, NUL bytes, too many variables, and oversized values. - `server`: `vitest run src/services/native-runtime/plugin-runner-task.test.ts` (95 pass). Values go only to a provider with the capability, never in `prepare`. `resume` sends values only for a handoff. - `server`: `vitest run src/services/protected-environment-keys.test.ts src/__tests__/project-routes-env.test.ts` (10 pass). Rejection, notices, and the project route response. - `server`: all route suites that import the project, routine, environment, or agent routes (45 files, 1689 pass). - `packages/shared`: `vitest run src/validators/plugin.test.ts` (64 pass). - `packages/paperclip-runner`: `vitest run src/drivers/codex src/configured-environment.test.ts src/live/runner-provider-launch.test.ts` (444 pass). - `packages/paperclip-runner/runner`: `cargo test -p paperclip-runner-core --lib runtime_notification` (9 pass, 2 ignored as before). - `pnpm typecheck` in `packages/shared`, `packages/plugins/sdk`, `packages/paperclip-runner`, `server`, and `ui`. - Not run locally: `pnpm verify --full` and browser suites. Required CI covers the final revision. ## Risks - **Existing providers:** low risk. Core sends no new field to a provider without the capability. Their runs behave as before, with one added log line when variables were skipped. - **Codex in an external sandbox:** commands now see every variable in the Runner environment except Codex's own credentials. The execution environment builds that environment from an allowlist. If the Runner gives Codex a new credential, the drift test fails until the key is classified. - **Saving env:** new rejections happen only when an installed driver declares `protectedEnvironmentKeys`. No driver declares them today. - **Providers:** they must keep the values transient and never save or log them. The doc lists these obligations. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, in Claude Code with tool use and code 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 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 - [x] 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
215 lines
6.9 KiB
Markdown
215 lines
6.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.
|
|
|
|
## 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.
|