## 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>
6.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.
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:
{
"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 with422and codeprotected_environment_variable. The response details name thekeysand theenvironmentId. - If another active environment protects the key, the save succeeds. The
response includes
configurationWarningsentries with codeprotected_environment_variable, afieldsuch asadapterConfig.env.KEY, and amessagethat 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,truncatedandviolationCountIsLowerBoundaretrue: 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 examplelive_run,pending:queued_wake,waiting:question.violationsandviolationCount: counts by reason (no_pending_path,retry_offered,recovery_block,unknown_block,run_owner_gone,native_run_stalled).native_run_stalledis 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 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.
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.