## 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>
15 KiB
title, summary
| title | summary |
|---|---|
| Routines | Recurring task scheduling, triggers, and run history |
Routines are recurring tasks that fire on a schedule, webhook, or API call and create a heartbeat run for the assigned agent.
List Routines
GET /api/companies/{companyId}/routines
Returns all routines in the company.
Get Routine
GET /api/routines/{routineId}
Returns routine details including triggers.
Routine and trigger resource IDs must be complete UUIDs from the API response.
Short prefixes and malformed IDs return the same 404 as a missing resource.
UUID lookup accepts PostgreSQL's existing input forms, including uppercase,
compact and braced UUIDs; it does not trim whitespace or resolve prefixes.
Company access and routine-assignee permissions still apply. Public trigger
IDs in webhook URLs are separate opaque identifiers, not resource UUIDs.
Create Routine
POST /api/companies/{companyId}/routines
{
"title": "Weekly CEO briefing",
"description": "Compile status report and email Founder",
"assigneeAgentId": "{agentId}",
"projectId": "{projectId}",
"goalId": "{goalId}",
"priority": "medium",
"status": "active",
"concurrencyPolicy": "coalesce_if_active",
"catchUpPolicy": "skip_missed"
}
Agents can only create routines assigned to themselves. Board operators can assign to any agent.
Fields:
| Field | Required | Description |
|---|---|---|
title |
yes | Routine name |
description |
no | Human-readable description of the routine |
assigneeAgentId |
yes | Agent who receives each run |
projectId |
yes | Project this routine belongs to |
goalId |
no | Goal to link runs to |
parentIssueId |
no | Parent issue for created run issues |
priority |
no | critical, high, medium (default), low |
status |
no | active (default), paused, archived |
concurrencyPolicy |
no | Behaviour when a run fires while a previous one is still active |
catchUpPolicy |
no | Behaviour for missed scheduled runs |
Concurrency policies:
| Value | Behaviour |
|---|---|
coalesce_if_active (default) |
Incoming run is immediately finalised as coalesced and linked to the active run — no new issue is created |
skip_if_active |
Incoming run is immediately finalised as skipped and linked to the active run — no new issue is created |
always_enqueue |
Always create a new run regardless of active runs |
Catch-up policies:
| Value | Behaviour |
|---|---|
skip_missed (default) |
Missed scheduled runs are dropped |
enqueue_missed_with_cap |
Missed runs are enqueued up to an internal cap |
Update Routine
PATCH /api/routines/{routineId}
{
"status": "paused",
"baseRevisionId": "{latestRevisionId}"
}
All fields from create are updatable. baseRevisionId is optional for backward compatibility; when provided, stale values return 409 Conflict with the current revision id. Agents can only update routines assigned to themselves and cannot reassign a routine to another agent.
When env contains a variable that an active plugin environment sets on its
own tasks (protectedEnvironmentKeys), create and update still save it. The
response then includes configurationWarnings entries with code
protected_environment_variable, a field such as env.KEY, and a message
that names those environments.
List Revisions
GET /api/routines/{routineId}/revisions
Returns append-only routine definition revisions newest first. Snapshots include routine fields and safe trigger metadata only; webhook secret values and secretId are never returned.
Restore Revision
POST /api/routines/{routineId}/revisions/{revisionId}/restore
Restores a historical routine definition by creating a new latest revision copied from the selected revision. Historical revision rows, routine run history, and activity history are preserved. If restoring a deleted webhook trigger requires recreating it, the response can include one-time replacement secret material for that trigger.
Add Trigger
POST /api/routines/{routineId}/triggers
Three trigger kinds:
Schedule — fires on a cron expression:
{
"kind": "schedule",
"cronExpression": "0 9 * * 1",
"timezone": "Europe/Amsterdam"
}
Webhook — fires on an inbound HTTP POST to a generated URL:
{
"kind": "webhook",
"signingMode": "hmac_sha256",
"replayWindowSec": 300
}
Signing modes: bearer (default), hmac_sha256, github_hmac, and none.
The replay window applies to hmac_sha256 only: 30–86400 seconds (default 300).
Creating a webhook returns trigger and one-time secretMaterial containing
webhookUrl and webhookSecret. Save the secret before closing the dialog.
Routine details retain the URL; rotate the secret if its value is lost.
API — fires only when called explicitly via Manual Run:
{
"kind": "api"
}
A routine can have multiple triggers of different kinds.
Update Trigger
PATCH /api/routine-triggers/{triggerId}
{
"enabled": false,
"cronExpression": "0 10 * * 1"
}
Delete Trigger
DELETE /api/routine-triggers/{triggerId}
Rotate Trigger Secret
POST /api/routine-triggers/{triggerId}/rotate-secret
Generates a new signing secret for webhook triggers. The previous secret is immediately invalidated.
Manual Run
POST /api/routines/{routineId}/run
{
"source": "manual",
"triggerId": "{triggerId}",
"payload": { "context": "..." },
"idempotencyKey": "my-unique-key"
}
Fires a run immediately, bypassing the schedule. Concurrency policy still applies.
A run an agent starts through this endpoint is always recorded with source manual; the server ignores a source value an agent sends. Board callers may send manual or api.
triggerId is optional. When supplied, the server validates the trigger belongs to this routine (403) and is enabled (409), then records the run against that trigger and updates its lastFiredAt. Omit it for a generic manual run with no trigger attribution.
Fire Public Trigger
POST /api/routine-triggers/public/{publicId}/fire
Fires a webhook trigger from an external system without a Paperclip login. Send
Content-Type: application/json and a JSON object. The trigger authenticates the
request using its own secret; an agent or board API key is not a substitute.
| Mode | Headers and signature |
|---|---|
bearer |
Authorization: Bearer <webhookSecret> |
hmac_sha256 |
X-Paperclip-Timestamp (Unix seconds or milliseconds) and X-Paperclip-Signature: sha256=<hex>; HMAC-SHA256 over the timestamp string, a dot, and the exact body bytes |
github_hmac |
X-Hub-Signature-256: sha256=<hex>; HMAC-SHA256 over the exact body bytes, without a timestamp. X-Paperclip-Signature is also accepted. Configure GitHub to send JSON. |
none |
No signature. Anyone with the generated URL can fire the trigger; keep it private. |
For a bearer trigger:
curl --fail-with-body "$WEBHOOK_URL" \
-H "Authorization: Bearer $WEBHOOK_SECRET" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: deployment-123' \
--data-binary '{"event":"deployment","variables":{"environment":"staging"}}'
For a timestamped HMAC trigger, sign and send the same bytes:
import { createHmac } from "node:crypto";
const body = JSON.stringify({ variables: { environment: "staging" } });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", process.env.WEBHOOK_SECRET)
.update(`${timestamp}.`).update(body).digest("hex");
const response = await fetch(process.env.WEBHOOK_URL, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Paperclip-Timestamp": timestamp,
"X-Paperclip-Signature": `sha256=${signature}`,
},
body,
});
console.log(response.status, await response.json());
202 returns the routine run, including its status and linked task. The task
runs asynchronously, so acceptance does not mean the agent has finished.
Concurrency policy can coalesce or skip a delivery while work is active.
Payload fields or a nested variables object supply declared routine variables;
nested values take precedence. The full payload is retained in run history.
For app-webhook triggers, the sender's JSON is also copied into the execution
task. Normal webhook intake does not apply a provider-specific field allowlist
or a general payload scrubber. Send only data suitable for company-readable
routine history; authentication and creation provenance do not certify the
payload's privacy. See the Sentry tutorial
for source-side scrubbing and setup checks.
For bearer, GitHub HMAC, and unsigned triggers, send a stable Idempotency-Key
when retrying a delivery to receive the original run without creating another
task. Timestamped HMAC rejects an identical signed delivery with 409, even
inside the replay window; stale timestamps and invalid secrets/signatures return
401. Disabled triggers and paused/archived routines return 409. Missing
required variables return 422; non-JSON media types return 415 and invalid
JSON objects return 400. Rotating a secret immediately invalidates the old one.
Cloud installations use their canonical public origin for generated URLs.
Self-hosted installations should set PAPERCLIP_PUBLIC_URL to their HTTPS
origin. The reverse proxy must forward this POST endpoint and its authorization,
signature, timestamp, and idempotency headers without requiring a browser login.
For local HTTPS testing, proxy an isolated test instance through Tailscale Serve;
use Funnel only if the sender is outside the tailnet. Existing routine and agent
execution controls still apply, including the isolated-worktree execution gate.
Verified creation provenance
The receiving routine and its run are recorded as the new task's direct origin.
Paperclip can also retain the run that invoked the routine. Authenticated agent
calls to the routine run API record a validated caller run. For an ordinary
public webhook, optionally send X-Paperclip-Source-Run-Token containing a
current, standard Paperclip run JWT from the same instance and company. The
trigger still authenticates with its own secret. Invalid, expired, foreign, or
stopped caller credentials return 401 before dispatch.
The source reference is stored as createdByRunId on the routine run, separate
from triggerPayload. Sender JSON and plain run-ID headers cannot establish
trusted caller ancestry. Without the source credential, a public webhook starts
a new external receiving-routine origin. This metadata grants no additional
execution or source-read authority. A source reference remains recorded after
run retention; unresolved ancestry is unknown, never assumed independent.
Routine-wide execution receipts
Send X-Paperclip-Idempotency-Scope: routine with a stable Idempotency-Key to
deduplicate execution receipts across webhook triggers on one routine. The
default is trigger. Keep the key and scope stable on retries. Routine scope
uses a deterministic receipt identity, so deleting the original trigger does
not let the same occurrence start another task. Scope does not change ordinary
concurrency, pause, company, permission, or budget controls.
Timestamped HMAC always uses trigger-scoped anti-replay receipts and rejects a
routine-scope request with 400. Setup checks create no routine runs; their
content-free test receipts remain associated with the setup trigger.
For a worked example that uses the normal webhook with Sentry, see Repair Failed Runs from Sentry.
List Runs
GET /api/routines/{routineId}/runs?limit=50
Returns recent run history for the routine. Defaults to 50 most recent runs.
Agent Access Rules
Agents can read all routines in their company but can only create and manage routines assigned to themselves:
| Operation | Agent | Board |
|---|---|---|
| List / Get | ✅ any routine | ✅ |
| Create | ✅ own only | ✅ |
| Update / activate | ✅ own only | ✅ |
| Add / update / delete triggers | ✅ own only | ✅ |
| Rotate trigger secret | ✅ own only | ✅ |
| Manual run | ✅ own only | ✅ |
| Reassign to another agent | ❌ | ✅ |
Routine Lifecycle
active -> paused -> active
-> archived
Archived routines do not fire and cannot be reactivated.
Routine detail navigation
The routine detail page keeps Runs and Activity in the routine sidebar. Runs lists the execution issues for that routine using the shared issue list, including issue status, priority, assignee, and search controls. Activity shows the routine, trigger, and run event timeline without leaving the routine page. The overview links to these same local tabs.
Webhook setup and connection checks
Create a webhook trigger with setupPending: true to configure it safely. While setup is pending, authenticated deliveries return 202 with { "status": "test_received", "test": true, "routineStarted": false, "linkedIssueId": null }. They never create a routine run, task, or agent wakeup. This state survives refreshes and server restarts, and connection checks also work while the routine is paused. Invalid authentication still returns 401.
Routine detail exposes setupPending and lastWebhookDelivery (status, receivedAt, and test) so the wizard can show live connection feedback. The secret is only returned at creation or rotation; it is never stored in browser draft storage or included in routine detail.
Finish setup with PATCH /api/routine-triggers/{id} and { "setupPending": false }. Future deliveries use normal routine dispatch and still respect the routine's enabled state. Test events are not dispatched on activation. Retries with the same Idempotency-Key, GitHub X-GitHub-Delivery, or timestamp-HMAC replay key remain test receipts after activation. Send a unique delivery ID per event so a sender's retries can be recognized. Requests without a delivery ID are new events after activation.
For compatibility, API-created triggers without setupPending: true are immediately live. Completed triggers cannot be returned to setup mode. Checking a previously enabled webhook observes real deliveries and can start the routine; the management UI explains this difference.
Trigger cards support removal with Undo. PATCH with { "archived": true } excludes a trigger from routine detail and scheduling, and rejects its webhook deliveries. Setting archived back to false restores the same URL and credentials. DELETE remains the permanent deletion API.
The webhook wizard and saved trigger editor warn about localhost, private-network addresses, Tailscale hostnames, and HTTP URLs without blocking setup. HTTPS does not imply public access: Tailscale Serve is private, while Funnel can expose the same hostname publicly. These warnings inspect the URL only; they do not resolve DNS or test internet reachability. Use the HTTPS setup guide to configure public access when the sender is outside your network.