feat(plugins): deliver configured environment to plugin Runner tasks (#21280)

## 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>
This commit is contained in:
Nicky LeachandClaude Opus 5.5 authored and GitHub committed 2026-11-13 08:11:23 +00:00
1 parent e73fc71331
commit 2483cb46c2
33 files changed
+650 -62

No files matched your search

+28
View File
@@ -69,6 +69,34 @@ authorized project IDs, and optional launch limits. It can also contain a saved
task ID for session reuse and a typed Codex or Claude credential. Core does not
supply an executable command or a guest path.
## Configured environment
An agent can have environment variables from its execution environment, its
own configuration, its project, and its routine. Core resolves secret
references for each run. It sends the result only to a provider whose
`description` result has `configuredEnvironmentVersion: 1`. An older provider
gets no new fields, and the run continues without the variables. Core writes a
run log line that names the variables it did not set.
- `submit` has `configuredEnvironment`. Set the variables in the Runner's
process environment. Add their names to `PAPERCLIP_CONFIGURED_ENV_KEYS`. The
Runner then gives them to every provider process.
- If a variable has the same name as a variable that the provider sets for its
own launch, use the provider's value. Do not fail the task.
- The values are transient secret input. Do not save them in task state, lease
metadata, journals, or logs.
- A retained Runner keeps the environment that it started with. Core includes
the values in its process reuse key. When a value changes, Core starts a new
task. It does not resume the retained Runner.
- A session handoff starts a new Runner, so its `resume` has
`configuredEnvironment`.
A driver can declare `protectedEnvironmentKeys` in the manifest. These are the
variables that the driver always sets on its tasks. Core rejects a protected
variable in the configuration of an agent or environment that uses the driver.
In other places, such as a project or routine, Core saves the variable and
returns a `protected_environment_variable` notice that names the environments.
## Release and resume
`release` ends Core's active use of an exact, settled Runner session. Core calls
+15
View File
@@ -88,6 +88,21 @@ PATCH /api/agents/{agentId}
}
```
### 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
```
+7
View File
@@ -109,6 +109,13 @@ Workspace storage is fixed at creation. A change of
`executionWorkspacePolicy.storageProviderPluginId` returns `409`
(`project_storage_locked`). Runs use the agent's environment, not a project setting.
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. Agents that run there may see the environment's
value instead.
## Project Workspaces
Workspaces link a project to a repository and directory:
+6
View File
@@ -89,6 +89,12 @@ PATCH /api/routines/{routineId}
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
```
@@ -30,26 +30,26 @@ pub(crate) fn runtime_notification_codex_args(
paths: &[PathBuf; 4],
) -> Vec<String> {
let prefix = "shell_environment_policy.include_only=";
let Some(keys) = args.iter().rev().find_map(|arg| arg.strip_prefix(prefix)) else {
return vec![];
};
let Ok(mut keys) = serde_json::from_str::<Vec<String>>(keys) else {
return vec![];
};
for key in [
crate::runtime_notifications::CONTEXT_ENV,
crate::runtime_notifications::HELPER_ENV,
] {
if !keys.iter().any(|existing| existing == key) {
keys.push(key.into());
let mut extra = Vec::new();
if let Some(keys) = args.iter().rev().find_map(|arg| arg.strip_prefix(prefix)) {
let Ok(mut keys) = serde_json::from_str::<Vec<String>>(keys) else {
return vec![];
};
for key in [
crate::runtime_notifications::CONTEXT_ENV,
crate::runtime_notifications::HELPER_ENV,
] {
if !keys.iter().any(|existing| existing == key) {
keys.push(key.into());
}
}
extra.extend([
"-c".into(),
format!("{prefix}{}", serde_json::to_string(&keys).unwrap()),
"-c".into(),
"shell_environment_policy.inherit=\"all\"".into(),
]);
}
let mut extra = vec![
"-c".into(),
format!("{prefix}{}", serde_json::to_string(&keys).unwrap()),
"-c".into(),
"shell_environment_policy.inherit=\"all\"".into(),
];
for profile in BTreeSet::from([profile, "paperclip-runner-workspace-read-only"]) {
let prefix = format!("permissions.{profile}.filesystem=");
let Some(value) = args.iter().rev().find_map(|arg| arg.strip_prefix(&prefix)) else {
@@ -5200,6 +5200,48 @@ mod tests {
assert!(!proves(page(json!([{"status": "completed"}]), Value::Null)));
}
#[test]
#[cfg(unix)]
fn runtime_notification_grants_file_access_without_an_environment_allowlist() {
let profile = "paperclip-runner-workspace-read-only";
let args = vec![
"shell_environment_policy.inherit=\"all\"".to_string(),
"shell_environment_policy.exclude=[\"OPENAI_API_KEY\"]".to_string(),
format!("permissions.{profile}.filesystem={{\":root\"=\"none\"}}"),
];
let paths = [
PathBuf::from("/runtime/runnerd"),
PathBuf::from("/state/private/runtime-notifications.json"),
PathBuf::from("/tmp/prn-channel/activity.lock"),
PathBuf::from("/tmp/prn-channel/activity.fifo"),
];
let extra = runtime_notification_codex_args(&args, profile, &paths);
assert!(!extra
.iter()
.any(|arg| arg.starts_with("shell_environment_policy.include_only=")));
let prefix = format!("permissions.{profile}.filesystem=");
let value = extra
.iter()
.find_map(|arg| arg.strip_prefix(&prefix))
.unwrap();
let config = format!("filesystem={value}")
.parse::<toml_edit::DocumentMut>()
.unwrap();
let filesystem = config["filesystem"].as_inline_table().unwrap();
assert_eq!(
filesystem
.get("/tmp/prn-channel")
.and_then(toml_edit::Value::as_str),
Some("write")
);
assert_eq!(
filesystem
.get("/runtime/runnerd")
.and_then(toml_edit::Value::as_str),
Some("read")
);
}
#[test]
#[cfg(unix)]
fn runtime_notification_policy_grants_only_discovery_files_and_ipc() {
@@ -1,6 +1,6 @@
import { createRequire } from "node:module";
import { execFileSync } from "node:child_process";
import { mkdtempSync, rmSync } from "node:fs";
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { resolvePinnedCodexCommand } from "./codex-command.js";
@@ -8,6 +8,7 @@ import { evalProviderTransportOptions } from "../../cli/eval-provider-runtime.js
import { describe, expect, it } from "vitest";
import {
CODEX_PROVIDER_CREDENTIAL_ENVIRONMENT_KEYS,
CODEX_UPDATE_PLAN_TOOL_CONFIG,
codexExecutableReadOnlyRoots,
codexNetworkReadOnlyRoots,
@@ -509,6 +510,37 @@ describe("Codex security configuration", () => {
});
});
it("lets externally sandboxed commands inherit the Runner environment except Codex credentials", () => {
const source = { PAPERCLIP_RUNNER_EXTERNAL_SANDBOX: "1", PAPERCLIP_CONFIGURED_ENV_KEYS: '["STRIPE_SECRET_KEY"]', STRIPE_SECRET_KEY: "fixture-secret-value" };
const args = createIsolatedCodexAppServerArgs(source);
const serialized = args.join("\n");
expect(serialized).not.toContain("shell_environment_policy.include_only=");
expect(args).toContain('shell_environment_policy.inherit="all"');
expect(args).toContain("shell_environment_policy.ignore_default_excludes=true");
const exclude = JSON.parse(args.find(arg => arg.startsWith("shell_environment_policy.exclude="))!.split("=").slice(1).join("="));
expect(exclude).toEqual([...CODEX_PROVIDER_CREDENTIAL_ENVIRONMENT_KEYS]);
expect(serialized).not.toContain("fixture-secret-value");
expect(createIsolatedCodexAppServerArgs({ PAPERCLIP_CONFIGURED_ENV_KEYS: '["STRIPE_SECRET_KEY"]', STRIPE_SECRET_KEY: "fixture-secret-value" }).join("\n"))
.toContain('shell_environment_policy.include_only=["STRIPE_SECRET_KEY"]');
});
it("excludes every credential the Runner passes to Codex", () => {
const source = readFileSync(resolve(import.meta.dirname, "../../../runner/crates/runner-core/src/codex_provider.rs"), "utf8");
const block = /const CODEX_PROVIDER_ENVIRONMENT_KEYS: &\[&str\] = &\[([^\]]*)\];/u.exec(source)?.[1];
expect(block).toBeDefined();
const runnerKeys = [...block!.matchAll(/"([A-Z0-9_]+)"/gu)].map(match => match[1]);
const commandVisible = new Set([
"OTEL_EXPORTER_OTLP_LOGS_TIMEOUT", "OTEL_EXPORTER_OTLP_TRACES_TIMEOUT",
"PAPERCLIP_AGENT_KEY_ID", "PAPERCLIP_AGENT_PUBLIC_KEY", "PAPERCLIP_AGENT_PRIVATE_KEY",
"PAPERCLIP_RUNNER_HOME_MODE", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME", "CODEX_HOME",
"PAPERCLIP_RUNNER_EXTERNAL_SANDBOX",
]);
expect(runnerKeys.length).toBeGreaterThan(0);
for (const key of runnerKeys) {
expect(commandVisible.has(key) || CODEX_PROVIDER_CREDENTIAL_ENVIRONMENT_KEYS.includes(key), `${key} must be classified`).toBe(true);
}
});
it("uses the outer sandbox for default-mode commands only when the controller authorizes it", () => {
const source = { PAPERCLIP_RUNNER_EXTERNAL_SANDBOX: "1", PAPERCLIP_RUNNER_NETWORK_ACCESS: "enabled" };
const externalArgs = createIsolatedCodexAppServerArgs(source);
@@ -178,6 +178,11 @@ function gitFilesystemRoots(source: NodeJS.ProcessEnv): { read: string[]; write:
return { read: [...new Set(read)], write: [...new Set(write)] };
}
export const CODEX_PROVIDER_CREDENTIAL_ENVIRONMENT_KEYS: readonly string[] = [
"OPENAI_API_KEY", "CODEX_API_KEY", "PAPERCLIP_AI_PROVIDER_KEY",
"OTEL_EXPORTER_OTLP_LOGS_HEADERS", "OTEL_EXPORTER_OTLP_TRACES_HEADERS",
];
export function usesExternalRunnerSandbox(source: NodeJS.ProcessEnv): boolean {
return source.PAPERCLIP_RUNNER_EXTERNAL_SANDBOX === "1";
}
@@ -361,15 +366,16 @@ export function createIsolatedCodexAppServerArgs(
`permissions.${CODEX_PLANNING_PERMISSION_PROFILE}.filesystem={${planningFilesystemRules}}`,
"-c",
`permissions.${CODEX_PLANNING_PERMISSION_PROFILE}.network.enabled=${networkAccess}`,
"-c",
`shell_environment_policy.inherit=${tomlString(hasProjectedEnvironment ? "all" : "none")}`,
"-c",
`shell_environment_policy.ignore_default_excludes=${hasProjectedEnvironment}`,
// Codex applies include_only after inheritance. Always emit the bounded
// allowlist: neither host mode nor a broker enables ambient secret access.
// Keep values in the process environment, never in argv/config diagnostics.
"-c",
`shell_environment_policy.include_only=${JSON.stringify(shellEnvironmentKeys)}`,
...(externalRunnerSandbox
? ["-c", 'shell_environment_policy.inherit="all"',
"-c", "shell_environment_policy.ignore_default_excludes=true",
"-c", `shell_environment_policy.exclude=${JSON.stringify(CODEX_PROVIDER_CREDENTIAL_ENVIRONMENT_KEYS)}`]
: ["-c", `shell_environment_policy.inherit=${tomlString(hasProjectedEnvironment ? "all" : "none")}`,
"-c", `shell_environment_policy.ignore_default_excludes=${hasProjectedEnvironment}`,
// Codex applies include_only after inheritance. Always emit the bounded
// allowlist: neither host mode nor a broker enables ambient secret access.
// Keep values in the process environment, never in argv/config diagnostics.
"-c", `shell_environment_policy.include_only=${JSON.stringify(shellEnvironmentKeys)}`]),
...(commandEnv.length > 0
? ["-c", `shell_environment_policy.set={${commandEnv}}`]
: []),
@@ -28,6 +28,34 @@ const githubBroker = z.object({ url: z.string().url().max(2000).refine(value =>
const claudeCredentialEnvironment = z.object({
CLAUDE_CODE_OAUTH_TOKEN: credentialValue.optional(), ANTHROPIC_API_KEY: credentialValue.optional(),
}).strict().refine(env => Object.values(env).filter(Boolean).length === 1, "Select one Claude credential");
export const MAX_CONFIGURED_ENVIRONMENT_KEYS = 128;
export const MAX_CONFIGURED_ENVIRONMENT_ENTRY_BYTES = 65_536;
export const MAX_CONFIGURED_ENVIRONMENT_BYTES = 262_144;
const utf8 = new TextEncoder();
const utf8Bytes = (value: string) => utf8.encode(value).byteLength;
export const environmentTaskConfiguredEnvironmentSchema = z.record(
z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,127}$/),
z.string().refine(value => !value.includes("\0"), "Expected a NUL-free value"),
).superRefine((environment, ctx) => {
const entries = Object.entries(environment);
if (entries.length > MAX_CONFIGURED_ENVIRONMENT_KEYS) {
ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Too many configured environment variables" });
return;
}
let total = 0;
for (const [name, value] of entries) {
const size = utf8Bytes(name) + utf8Bytes(value);
total += size;
if (size > MAX_CONFIGURED_ENVIRONMENT_ENTRY_BYTES) {
ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Configured environment variable is too large", path: [name] });
}
}
if (total > MAX_CONFIGURED_ENVIRONMENT_BYTES) {
ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Configured environment is too large" });
}
});
export type PluginEnvironmentTaskConfiguredEnvironment = z.infer<typeof environmentTaskConfiguredEnvironmentSchema>;
/** Only provider authentication is transferred. Paths and executable settings remain provider-owned. */
export const environmentTaskCredentialSchema = z.discriminatedUnion("type", [
z.object({ type: z.literal("codex-auth-json"), authJson: credentialValue }).strict(),
@@ -89,6 +117,7 @@ export const environmentTaskOperationSchema = z.discriminatedUnion("kind", [
/** Stable account selection; distinct from its current credential revision. */
accountIdentity: z.string().min(1).max(1024).optional(),
credential: environmentTaskCredentialSchema.optional(),
configuredEnvironment: environmentTaskConfiguredEnvironmentSchema.optional(),
/** Core supplies these protected launch inputs for native agent runs. */
launch: z.object({
runnerVersion: z.string().min(1), runnerDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/),
@@ -117,6 +146,7 @@ export const environmentTaskOperationSchema = z.discriminatedUnion("kind", [
z.object({ kind: z.literal("release"), identity: durableIdentity }).strict(),
z.object({ kind: z.literal("resume"), identity: durableIdentity, bootstrapTicket: credentialValue,
handoffCredential: z.object({ accountIdentity: z.string().min(1).max(1024), environment: claudeCredentialEnvironment }).strict().optional(),
configuredEnvironment: environmentTaskConfiguredEnvironmentSchema.optional(),
}).strict(),
z.object({
kind: z.literal("ensure_ownership"),
@@ -172,6 +202,7 @@ export const environmentTaskResultSchema = z.discriminatedUnion("kind", [
projectAuthCheckVersion: z.literal(1).optional(),
workspaceFileReadVersion: z.literal(1).optional(),
githubCredentialBrokerVersion: z.literal(1).optional(),
configuredEnvironmentVersion: z.literal(1).optional(),
}).strict(),
z.object({
kind: z.literal("status"), taskId: providerId,
+2 -2
View File
@@ -489,8 +489,8 @@ export type { PluginEnvironmentTaskErrorDiagnostic } from "./environment-task-er
export type { AiConnectionPool, AiConnectionPoolConfig, AiConnectionPoolMember, AiConnectionRouterRequest, AiConnectionRouterResult, AiConnectionRouterSelection } from "@paperclipai/shared";
export { MAX_ENVIRONMENT_TASK_FILE_BYTES, environmentRunnerLaunchRequirementsSchema, environmentTaskOperationSchema, environmentTaskResultSchema, environmentTaskCredentialSchema, parseEnvironmentTaskResult } from "./environment-tasks.js";
export type { PluginEnvironmentTaskOperation, PluginEnvironmentTaskParams, PluginEnvironmentTaskResult, PluginEnvironmentTaskCredential, PluginEnvironmentTaskExecutionContext } from "./environment-tasks.js";
export { MAX_ENVIRONMENT_TASK_FILE_BYTES, environmentRunnerLaunchRequirementsSchema, environmentTaskOperationSchema, environmentTaskResultSchema, environmentTaskCredentialSchema, environmentTaskConfiguredEnvironmentSchema, MAX_CONFIGURED_ENVIRONMENT_KEYS, MAX_CONFIGURED_ENVIRONMENT_ENTRY_BYTES, MAX_CONFIGURED_ENVIRONMENT_BYTES, parseEnvironmentTaskResult } from "./environment-tasks.js";
export type { PluginEnvironmentTaskOperation, PluginEnvironmentTaskParams, PluginEnvironmentTaskResult, PluginEnvironmentTaskCredential, PluginEnvironmentTaskConfiguredEnvironment, PluginEnvironmentTaskExecutionContext } from "./environment-tasks.js";
export type { AgentLifecycleRequest, AgentLifecycleResult } from "@paperclipai/shared";
export type { PluginEnvironmentRunnerLaunchRequirements, PluginEnvironmentPreparedLaunch } from "./environment-tasks.js";
@@ -96,3 +96,31 @@ describe("implementation-independent GitHub credential broker", () => {
url: "https://core.example.test", token: "runtime-capability", script: "run-this" } }).success).toBe(false);
});
});
describe("configured environment", () => {
const configured = { ...submit, configuredEnvironment: { STRIPE_SECRET_KEY: "fixture-value", EMPTY_OK: "" } };
it("accepts bounded variables on submit and on a handoff resume", () => {
expect(environmentTaskOperationSchema.parse(configured)).toEqual(configured);
const identity = { runnerInstanceId: "runner", environmentLeaseId: "lease", runId: "run", normalizedSessionId: "session", turnId: "turn", itemId: "item" };
const resume = { kind: "resume", identity, bootstrapTicket: "synthetic", configuredEnvironment: { A: "1" } };
expect(environmentTaskOperationSchema.parse(resume)).toEqual(resume);
});
it.each([
["an invalid name", { "1BAD": "x" }],
["a dashed name", { "BAD-NAME": "x" }],
["a NUL byte", { GOOD: "a\0b" }],
["too many variables", Object.fromEntries(Array.from({ length: 129 }, (_, index) => [`K${index}`, "x"]))],
["an oversized value", { BIG: "x".repeat(65_536) }],
["an oversized total", Object.fromEntries(Array.from({ length: 5 }, (_, index) => [`K${index}`, "x".repeat(60_000)]))],
])("rejects %s", (_label, configuredEnvironment) => {
expect(environmentTaskOperationSchema.safeParse({ ...configured, configuredEnvironment }).success).toBe(false);
});
it("has no digest field", () => {
expect(environmentTaskOperationSchema.safeParse({ ...configured, configuredEnvironmentDigest: `hmac-sha256:${"b".repeat(64)}` }).success).toBe(false);
});
it("lets a provider advertise support", () => {
const description = { kind: "description", taskId: "task", runner: { version: "fixture", digest: `sha256:${"a".repeat(64)}` }, configuredEnvironmentVersion: 1 };
expect(environmentTaskResultSchema.parse(description)).toEqual(description);
expect(environmentTaskResultSchema.safeParse({ ...description, configuredEnvironmentVersion: 2 }).success).toBe(false);
});
});
@@ -1,5 +1,5 @@
export interface AgentConfigurationWarning {
code: "runner_option_ignored";
code: "runner_option_ignored" | "protected_environment_variable";
field: string;
message: string;
}
+1
View File
@@ -202,6 +202,7 @@ export interface PluginEnvironmentDriverDeclaration {
/** Codex task retention and authorized run attachment, version 1. */
warmTaskVersion?: 1;
sessionHandoffVersion?: 1;
protectedEnvironmentKeys?: string[];
/** Stable driver key, unique within the plugin. Namespaced by plugin ID at runtime. */
driverKey: string;
/**
+1
View File
@@ -129,6 +129,7 @@ export interface Project {
id: string;
companyId: string;
urlKey: string;
configurationWarnings?: import("../runner-configuration-warnings.js").AgentConfigurationWarning[];
/** @deprecated Use goalIds / goals instead */
goalId: string | null;
goalIds: string[];
+1
View File
@@ -73,6 +73,7 @@ export interface Routine {
id: string;
companyId: string;
projectId: string | null;
configurationWarnings?: import("../runner-configuration-warnings.js").AgentConfigurationWarning[];
folderId?: string | null;
goalId: string | null;
parentIssueId: string | null;
@@ -55,6 +55,13 @@ describe("plugin manifest validators", () => {
}
expect(pluginManifestV1Schema.safeParse({ ...manifest, capabilities: ["environment.drivers.register"] }).success).toBe(false);
});
it("accepts protected environment keys only as variable names", () => {
expect(pluginManifestV1Schema.parse(buildSandboxProviderManifest({ protectedEnvironmentKeys: ["DESKTOP_SESSION"] }))
.environmentDrivers?.[0]?.protectedEnvironmentKeys).toEqual(["DESKTOP_SESSION"]);
for (const keys of [["BAD-NAME"], ["1BAD"], "DESKTOP_SESSION", Array.from({ length: 65 }, (_, index) => `K${index}`)]) {
expect(pluginManifestV1Schema.safeParse(buildSandboxProviderManifest({ protectedEnvironmentKeys: keys })).success).toBe(false);
}
});
it("retains the agent prerequisite on environment drivers", () => {
const manifest = { ...buildSandboxProviderManifest({ requiresAgent: true }), agentLifecycle: true,
capabilities: ["environment.drivers.register", "agents.lifecycle.manage"] };
+1
View File
@@ -184,6 +184,7 @@ export const pluginEnvironmentDriverDeclarationSchema = z.object({
creationOperationVersion: z.literal(1).optional(),
warmTaskVersion: z.literal(1).optional(),
sessionHandoffVersion: z.literal(1).optional(),
protectedEnvironmentKeys: z.array(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,127}$/)).max(64).optional(),
driverKey: z.string().min(1).regex(
/^[a-z0-9][a-z0-9._-]*$/,
"Environment driver key must start with a lowercase alphanumeric and contain only lowercase letters, digits, dots, hyphens, or underscores",
@@ -65,6 +65,7 @@ const mockApprovalService = vi.hoisted(() => ({
getById: vi.fn(),
}));
const mockCheckProtectedKeys = vi.hoisted(() => vi.fn(async (..._args: unknown[]) => [] as unknown[]));
const mockInstanceSettingsService = vi.hoisted(() => ({
get: vi.fn(async () => ({ defaultEnvironmentId: null })),
getGeneral: vi.fn(async () => ({ censorUsernameInLogs: false })),
@@ -117,6 +118,10 @@ vi.mock("../services/remote-agent-profiles.js", () => ({
}));
function registerModuleMocks() {
vi.doMock("../services/protected-environment-keys.js", async () => ({
...await vi.importActual<typeof import("../services/protected-environment-keys.js")>("../services/protected-environment-keys.js"),
checkAgentProtectedEnvironmentKeys: mockCheckProtectedKeys,
}));
vi.doMock("../services/antigravity-connection-models.js", () => ({ antigravityConnectionModels: mockAntigravityModels }));
vi.doMock("../services/index.js", () => ({
agentService: () => mockAgentService,
@@ -269,6 +274,8 @@ describe("agent routes adapter validation", () => {
mockLogActivity.mockResolvedValue(undefined);
mockSecretService.syncEnvBindingsForTarget.mockResolvedValue(undefined);
mockInstanceSettingsService.get.mockResolvedValue({ defaultEnvironmentId: null });
mockCheckProtectedKeys.mockReset();
mockCheckProtectedKeys.mockResolvedValue([]);
mockInstanceSettingsService.getExperimental.mockResolvedValue({ enableNativeRunner: false });
mockManagedAgentProfileService.requireQualified.mockResolvedValue({
id: "managed-primary",
@@ -1772,6 +1779,34 @@ describe("agent routes adapter validation", () => {
expect(mockAgentService.rollbackConfigRevision).not.toHaveBeenCalled();
});
it.each(["rejected", "warned"] as const)("checks a rollback's restored env and environment for protected keys (%s)", async outcome => {
const existing = await mockAgentService.getById();
const adapterConfig = { ...(existing.adapterConfig as Record<string, unknown>), env: { DESKTOP_SESSION: { type: "plain", value: "mine" } } };
mockAgentService.getConfigRevision.mockResolvedValue({ afterConfig: {
name: existing.name, role: existing.role, adapterType: existing.adapterType, adapterConfig,
runtimeConfig: {}, defaultEnvironmentId: "computer-env", budgetMonthlyCents: existing.budgetMonthlyCents,
} });
mockAgentService.rollbackConfigRevision.mockResolvedValue({ ...existing, adapterConfig });
const warning = { code: "protected_environment_variable", field: "adapterConfig.env.DESKTOP_SESSION", message: "notice" };
if (outcome === "rejected") {
const { unprocessable } = await import("../errors.js");
mockCheckProtectedKeys.mockRejectedValue(unprocessable("protected", { code: "protected_environment_variable" }));
} else mockCheckProtectedKeys.mockResolvedValue([warning]);
const app = await createApp();
const response = await requestApp(app, (baseUrl) =>
request(baseUrl).post("/api/agents/11111111-1111-4111-8111-111111111111/config-revisions/33333333-3333-4333-8333-333333333333/rollback").send({}),
);
expect(mockCheckProtectedKeys).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ env: adapterConfig.env }), "computer-env");
if (outcome === "rejected") {
expect(response.status, JSON.stringify(response.body)).toBe(422);
expect(response.body.details).toMatchObject({ code: "protected_environment_variable" });
expect(mockAgentService.rollbackConfigRevision).not.toHaveBeenCalled();
} else {
expect(response.status, JSON.stringify(response.body)).toBe(200);
expect(response.body.configurationWarnings).toEqual([warning]);
}
});
it("keeps an existing paperclip_runner agent editable after the flag is disabled", async () => {
const existing = await mockAgentService.getById();
mockAgentService.getById.mockResolvedValue({
@@ -22,6 +22,7 @@ const mockEnvironmentService = vi.hoisted(() => ({
}));
const mockWorkspaceOperationService = vi.hoisted(() => ({}));
const mockLogActivity = vi.hoisted(() => vi.fn());
const mockProtectedKeyHolders = vi.hoisted(() => vi.fn());
const mockGetTelemetryClient = vi.hoisted(() => vi.fn());
const mockAccessService = vi.hoisted(() => ({
decide: vi.fn(),
@@ -54,6 +55,10 @@ vi.mock("../services/workspace-runtime.js", () => ({
}));
function registerModuleMocks() {
vi.doMock("../services/protected-environment-keys.js", async () => ({
...await vi.importActual<typeof import("../services/protected-environment-keys.js")>("../services/protected-environment-keys.js"),
listProtectedEnvironmentKeyHolders: mockProtectedKeyHolders,
}));
vi.doMock("../services/activity-log.js", async () => ({
...await vi.importActual<typeof import("../services/activity-log.js")>("../services/activity-log.js"),
persistActivity: async (db: unknown, input: unknown) => { await mockLogActivity(db, input); return { activity: { id: "activity" }, publication: null }; },
@@ -168,6 +173,31 @@ describe("project env routes", () => {
mockProjectService.listWorkspaces.mockResolvedValue([]);
mockEnvironmentService.getById.mockReset();
mockSecretService.normalizeEnvBindingsForPersistence.mockImplementation(async (_companyId, env) => env);
mockProtectedKeyHolders.mockResolvedValue([]);
});
it("saves a protected env key and returns a notice that names the environment", async () => {
const env = { DESKTOP_SESSION: { type: "plain", value: "mine" }, OTHER: { type: "plain", value: "ok" } };
mockProtectedKeyHolders.mockResolvedValue([{ environmentId: "computer", environmentName: "Team Computer", keys: new Set(["DESKTOP_SESSION"]) }]);
mockProjectService.getById.mockResolvedValue(buildProject());
mockProjectService.update.mockResolvedValue(buildProject({ env }));
const app = await createApp();
const res = await request(app).patch("/api/projects/project-1").send({ env });
expect(res.status, JSON.stringify(res.body)).toBe(200);
expect(mockProjectService.update).toHaveBeenCalledWith("project-1", expect.objectContaining({ env }));
expect(res.body.configurationWarnings).toEqual([{ code: "protected_environment_variable", field: "env.DESKTOP_SESSION",
message: "DESKTOP_SESSION is set by Team Computer on its tasks. Agents running there may see the platform's value instead of this one." }]);
});
it("returns no notice when the update does not change env", async () => {
mockProtectedKeyHolders.mockResolvedValue([{ environmentId: "computer", environmentName: "Team Computer", keys: new Set(["DESKTOP_SESSION"]) }]);
mockProjectService.getById.mockResolvedValue(buildProject());
mockProjectService.update.mockResolvedValue(buildProject({ name: "Renamed" }));
const app = await createApp();
const res = await request(app).patch("/api/projects/project-1").send({ name: "Renamed" });
expect(res.status, JSON.stringify(res.body)).toBe(200);
expect(res.body).not.toHaveProperty("configurationWarnings");
expect(mockProtectedKeyHolders).not.toHaveBeenCalled();
});
it('requires workspace-write authority to attach a repository despite project read access', async () => {
+13 -4
View File
@@ -1,4 +1,5 @@
import { resolveLoginEnvironmentTarget } from "../services/login-environment.js";
import { checkAgentProtectedEnvironmentKeys } from "../services/protected-environment-keys.js";
import { assertProviderApiPlacementPolicy, managedCursorApiDefaultEnabled, resolveProviderApiPlacement } from "../services/native-runtime/provider-api-placement.js";
import { isObjectJournalBusyError } from "../services/object-byte-journal.js";
import { readTaskPanelActivations } from "../services/plugin-task-panels.js";
@@ -4378,6 +4379,9 @@ export function agentRoutes(
);
}
const rollbackWarnings = await checkAgentProtectedEnvironmentKeys(db, rollbackAdapterConfig,
typeof rollbackConfig.defaultEnvironmentId === "string" ? rollbackConfig.defaultEnvironmentId : null);
const actor = getActorInfo(req);
const updated = await svc.rollbackConfigRevision(id, revisionId, {
agentId: actor.agentId,
@@ -4401,7 +4405,7 @@ export function agentRoutes(
details: { revisionId },
});
res.json(redactAgentRowForResponse(updated));
res.json({ ...redactAgentRowForResponse(updated), ...(rollbackWarnings.length ? { configurationWarnings: rollbackWarnings } : {}) });
});
router.get("/agents/:id/runtime-state", async (req, res) => {
@@ -4643,6 +4647,7 @@ export function agentRoutes(
allowedDrivers: allowedEnvironmentDriversForAgent(hireInput.adapterType),
allowedSandboxProviders: allowedSandboxProvidersForAgent(hireInput.adapterType),
});
configurationWarnings.push(...await checkAgentProtectedEnvironmentKeys(db, normalizedAdapterConfig, hireInput.defaultEnvironmentId));
// Idempotency within a run: if this run already created a hire from this
// exact request, return that hire instead of creating a duplicate. The
@@ -4963,6 +4968,7 @@ export function agentRoutes(
allowedDrivers: allowedEnvironmentDriversForAgent(createInput.adapterType),
allowedSandboxProviders: allowedSandboxProvidersForAgent(createInput.adapterType),
});
configurationWarnings.push(...await checkAgentProtectedEnvironmentKeys(db, normalizedAdapterConfig, createInput.defaultEnvironmentId));
const managedBinding = normalizedRuntimeConfig.aiConnection ? aiRuntimeConnectionBindingSchema.parse(normalizedRuntimeConfig.aiConnection) : undefined;
const managedConnection = managedBinding && !setupId ? await validateManagedAgentBinding(req, companyId, agentId, createInput.adapterType, normalizedAdapterConfig, managedBinding, createInput.defaultEnvironmentId, "none", true) : undefined;
@@ -5828,16 +5834,19 @@ export function agentRoutes(
}
if (requestedRuntimeConfig) patchData.runtimeConfig = requestedRuntimeConfig;
if (touchesAdapterConfiguration || Object.prototype.hasOwnProperty.call(patchData, "defaultEnvironmentId")) {
const nextDefaultEnvironmentId = Object.prototype.hasOwnProperty.call(patchData, "defaultEnvironmentId")
? (typeof patchData.defaultEnvironmentId === "string" ? patchData.defaultEnvironmentId : null)
: existing.defaultEnvironmentId;
await assertAgentDefaultEnvironmentSelection(
existing.companyId,
Object.prototype.hasOwnProperty.call(patchData, "defaultEnvironmentId")
? (typeof patchData.defaultEnvironmentId === "string" ? patchData.defaultEnvironmentId : null)
: existing.defaultEnvironmentId,
nextDefaultEnvironmentId,
{
allowedDrivers: allowedEnvironmentDriversForAgent(requestedAdapterType),
allowedSandboxProviders: allowedSandboxProvidersForAgent(requestedAdapterType),
},
);
const protectedKeyWarnings = await checkAgentProtectedEnvironmentKeys(db, patchData.adapterConfig ?? existing.adapterConfig, nextDefaultEnvironmentId);
configurationWarnings.push(...protectedKeyWarnings.filter(warning => !configurationWarnings.some(existing => existing.field === warning.field)));
}
const touchesProfileFields = touchesAgentProfileChangeConsentFields(patchData);
const profileOnlyChange = touchesProfileFields && Object.keys(patchData).every((key) =>
+6
View File
@@ -1,4 +1,5 @@
import { Router, type Request } from "express";
import { assertEnvironmentVariablesNotProtected } from "../services/protected-environment-keys.js";
import type { Db } from "@paperclipai/db";
import {
AGENT_ADAPTER_TYPES,
@@ -1097,6 +1098,7 @@ export function environmentRoutes(
pluginWorkerManager: options.pluginWorkerManager,
}),
};
await assertEnvironmentVariablesNotProtected(db, { name: input.name, driver: input.driver, config: input.config }, input.envVars);
// Create the row and its binding rows atomically so an invalid secret
// ref cannot leave an environment persisted without its bindings.
const environment = await db.transaction(async (tx) => {
@@ -1262,6 +1264,10 @@ export function environmentRoutes(
// Persist the config change and its binding rows atomically: a binding
// ref that fails validation (e.g. a deleted secret) must roll the whole
// save back instead of leaving the config re-pointed with stale bindings.
if (patch.envVars !== undefined || patch.config !== undefined || patch.driver !== undefined) {
await assertEnvironmentVariablesNotProtected(db, { id: existing.id, name: nextName, driver: nextDriver,
config: patch.config ?? existing.config }, patch.envVars ?? existing.envVars);
}
if (patch.config !== undefined || patch.driver !== undefined) {
const instanceDefault = (await instanceSettingsService(db).get()).defaultEnvironmentId;
await assertAgentsReadyForEnvironmentChange(db, existing, { driver: nextDriver, config: patch.config ?? existing.config },
+7 -2
View File
@@ -1,4 +1,5 @@
import { projectEnvironmentOptions } from "../services/project-environments.js";
import { listProtectedEnvironmentKeyHolders, protectedEnvironmentKeyWarnings } from "../services/protected-environment-keys.js";
import { projectGitAuthorizationService } from "../services/project-git-authorization.js";
import { skillAccessRequestContext } from "../services/skill-access.js";
import { createHash } from "node:crypto";
@@ -419,6 +420,8 @@ export function projectRoutes(db: Db) {
{ strictMode: strictSecretsMode, fieldPath: "env" },
);
}
const configurationWarnings = projectData.env !== undefined
? protectedEnvironmentKeyWarnings(await listProtectedEnvironmentKeyHolders(db), projectData.env, "env") : [];
if (workspace && (repositoryIds || repositoryUrls)) throw unprocessable("Use either workspace or repositoryIds/repositoryUrls when creating a project");
const urlRepositories = (repositoryUrls ?? []).map(normalizeProjectRepositoryUrl);
const repositories = repositoryIds ? await selectedRepositories(req, companyId, repositoryIds) : null;
@@ -512,7 +515,7 @@ export function projectRoutes(db: Db) {
if (telemetryClient) {
trackProjectCreated(telemetryClient);
}
res.status(result.duplicate ? 200 : 201).json(result.project);
res.status(result.duplicate ? 200 : 201).json({ ...result.project, ...(configurationWarnings.length ? { configurationWarnings } : {}) });
});
router.patch("/projects/:id", validate(updateProjectSchema), async (req, res) => {
@@ -539,6 +542,8 @@ export function projectRoutes(db: Db) {
fieldPath: "env",
});
}
const configurationWarnings = body.env !== undefined
? protectedEnvironmentKeyWarnings(await listProtectedEnvironmentKeyHolders(db), body.env, "env") : [];
const project = await svc.update(id, body);
if (!project) {
res.status(404).json({ error: "Project not found" });
@@ -570,7 +575,7 @@ export function projectRoutes(db: Db) {
},
});
res.json(project);
res.json({ ...project, ...(configurationWarnings.length ? { configurationWarnings } : {}) });
});
router.get("/projects/:id/access-members", async (req, res) => {
+7 -2
View File
@@ -1,4 +1,5 @@
import { Router, type Request } from "express";
import { listProtectedEnvironmentKeyHolders, protectedEnvironmentKeyWarnings } from "../services/protected-environment-keys.js";
import type { Db } from "@paperclipai/db";
import {
createRoutineSchema,
@@ -200,7 +201,9 @@ export function routineRoutes(
changeSummary: "Created routine",
triggerCount: 0,
});
res.status(201).json(created);
const configurationWarnings = req.body.env !== undefined
? protectedEnvironmentKeyWarnings(await listProtectedEnvironmentKeyHolders(db), req.body.env, "env") : [];
res.status(201).json({ ...created, ...(configurationWarnings.length ? { configurationWarnings } : {}) });
});
router.get("/routines/:id", async (req, res) => {
@@ -441,7 +444,9 @@ export function routineRoutes(
}
if (updated) {
const { previousResponsibleUserId: _previousResponsibleUserId, ...response } = updated;
res.json(response);
const configurationWarnings = req.body.env !== undefined
? protectedEnvironmentKeyWarnings(await listProtectedEnvironmentKeyHolders(db), req.body.env, "env") : [];
res.json({ ...response, ...(configurationWarnings.length ? { configurationWarnings } : {}) });
} else {
res.json(null);
}
@@ -16683,10 +16683,11 @@ describe("runnerd provider runtime wiring", () => {
},
);
it.each((["codex", "claude"] as const).flatMap(provider => (["unchanged", "external-checkpoint", "suspension-receipt", "suspension-active-owner", "changed", "changed-external-checkpoint", "runtime-context", "retirement-failed", "stale-owner", "active-owner", "missing-owner", "foreign-environment", "plugin-replaced", "plugin-managed-github"] as const).filter(scenario => provider === "codex" || scenario.startsWith("plugin-")).map(scenario => [provider, scenario] as const)))("rotates an owned warm %s remote runner before checking changed configuration: %s", async (provider, scenario) => {
const plugin = scenario === "plugin-replaced" || scenario === "plugin-managed-github";
it.each((["codex", "claude"] as const).flatMap(provider => (["unchanged", "external-checkpoint", "suspension-receipt", "suspension-active-owner", "changed", "changed-external-checkpoint", "runtime-context", "retirement-failed", "stale-owner", "active-owner", "missing-owner", "foreign-environment", "plugin-replaced", "plugin-managed-github", "plugin-environment-upgrade", "plugin-environment-delivered"] as const).filter(scenario => provider === "codex" || scenario.startsWith("plugin-")).map(scenario => [provider, scenario] as const)))("rotates an owned warm %s remote runner before checking changed configuration: %s", async (provider, scenario) => {
const plugin = scenario.startsWith("plugin-");
const configuredScenario = scenario === "plugin-environment-upgrade" || scenario === "plugin-environment-delivered";
const suspensionReceipt = scenario.startsWith("suspension-");
const reusable = suspensionReceipt || ["unchanged", "external-checkpoint", "plugin-managed-github"].includes(scenario);
const reusable = suspensionReceipt || ["unchanged", "external-checkpoint", "plugin-managed-github", "plugin-environment-delivered"].includes(scenario);
const { permissionPolicy: _permissionPolicy, ...claudeProfile } = QUALIFIED_ACPX_PROFILES.claude;
const first = { ...scopedNativeExecution(`warm-admission-${provider}-${scenario}`),
schema: "paperclip.native-execution-input.v5" as const,
@@ -16695,7 +16696,7 @@ describe("runnerd provider runtime wiring", () => {
if (provider === "claude") first.session.driverKind = "acpx_runtime";
first.session.lifecyclePolicy = { mode: "warm", idleTimeoutMs: 60_000 };
const next = { ...first, binding: { ...first.binding, runId: `${first.binding.runId}-next` },
session: { ...first.session, lifecyclePolicy: { mode: "warm" as const, idleTimeoutMs: suspensionReceipt || ["unchanged", "external-checkpoint", "runtime-context", "stale-owner", "missing-owner", "plugin-replaced", "plugin-managed-github"].includes(scenario) ? 60_000 : 90_000 } } };
session: { ...first.session, lifecyclePolicy: { mode: "warm" as const, idleTimeoutMs: suspensionReceipt || ["unchanged", "external-checkpoint", "runtime-context", "stale-owner", "missing-owner", "plugin-replaced", "plugin-managed-github", "plugin-environment-upgrade", "plugin-environment-delivered"].includes(scenario) ? 60_000 : 90_000 } } };
if (scenario === "runtime-context") {
next.runtimeContext = { ...first.runtimeContext,
mcp: { ...first.runtimeContext.mcp, digest: "1".repeat(64) } };
@@ -16706,11 +16707,12 @@ describe("runnerd provider runtime wiring", () => {
remoteCwd: "/home/daytona/workspace", runner: { execute: vi.fn() } };
const identity = { runId: first.binding.runId, normalizedSessionId: first.session.normalizedSessionId!,
runnerInstanceId: `runner-${scenario}`, environmentLeaseId: first.binding.executionWorkspaceId };
let replacementPending=false;
let replacementPending=false, advertiseEnvironment=false;
const acquisition={outcome:"resumed" as "resumed"|"replacement",providerLeaseId:"task-first"};
const task=vi.fn(async()=>{
if(replacementPending) {acquisition.outcome="replacement";acquisition.providerLeaseId="task-next";replacementPending=false;}
return {kind:"description",taskId:acquisition.providerLeaseId,launchPreparationVersion:1,projectAuthCheckVersion:1,warmTaskVersion:1,
...(advertiseEnvironment ? {configuredEnvironmentVersion:1} : {}),
runner:{version:"fixture",digest:`sha256:${"a".repeat(64)}`}};
});
const pluginTarget=plugin ? {...target,remoteCwd:".",leaseId:identity.environmentLeaseId,
@@ -16719,13 +16721,15 @@ describe("runnerd provider runtime wiring", () => {
if(plugin) {
await mkdir(home,{recursive:true});await writeFile(join(home,"auth.json"),JSON.stringify({OPENAI_API_KEY:"synthetic-fixture"}),{mode:0o600});
}
const pluginOptions=plugin ? {runnerIngressAuthorized:true,runnerEnvironment:provider === "claude" ? {ANTHROPIC_API_KEY:"synthetic-fixture"} : {},managedGitHub:scenario === "plugin-managed-github",managedAiCredentialHome:home,
const configuredVariables=configuredScenario ? {PAPERCLIP_CONFIGURED_ENV_KEYS:'["FEATURE_FLAG"]',FEATURE_FLAG:"on"} : {};
const pluginOptions=plugin ? {runnerIngressAuthorized:true,runnerEnvironment:{...(provider === "claude" ? {ANTHROPIC_API_KEY:"synthetic-fixture"} : {}),...configuredVariables},managedGitHub:scenario === "plugin-managed-github",managedAiCredentialHome:home,
managedAiCredentialIdentity:"revision",managedAiAccountIdentity:"account"} : {};
const resume=scenario === "plugin-replaced" ? vi.spyOn(environmentTaskRuntime,"resolvePluginTaskResume").mockResolvedValue("task-first") : undefined;
const resume=scenario === "plugin-replaced" || scenario === "plugin-environment-upgrade" ? vi.spyOn(environmentTaskRuntime,"resolvePluginTaskResume").mockResolvedValue("task-first") : undefined;
const createOwner = pluginTaskRuntime.createPluginRunnerTaskOwner;
const owners=plugin ? vi.spyOn(pluginTaskRuntime,"createPluginRunnerTaskOwner") : undefined;
const rebind = vi.fn();
if (scenario === "plugin-managed-github") owners!.mockImplementation(input => ({...createOwner(input),rebind}));
if (scenario === "plugin-environment-delivered") owners!.mockImplementation(input => ({...createOwner(input),rebind,configuredEnvironmentDelivered:() => true}));
const root = await initializeScopedRunnerRoot(first, identity.runnerInstanceId);
await writeRunnerAuthority(root, identity, "ready");
@@ -16834,6 +16838,7 @@ describe("runnerd provider runtime wiring", () => {
firstSession.close.mockClear();
}
if(scenario === "plugin-replaced") replacementPending=true;
if(configuredScenario) advertiseEnvironment=true;
const continuation = executePaperclipNativeSession({ db: nextDb, execution: next,
runnerInstanceId: `runner-next-${scenario}`, useRunnerd: true,
runnerExecutionTarget: (scenario === "foreign-environment" ? { ...target, environmentId: `${environmentId}-other` }
@@ -16857,7 +16862,11 @@ describe("runnerd provider runtime wiring", () => {
expect(owners!.mock.calls.at(-1)![0]).toMatchObject({resumeFrom:"task-first"});
expect(owners!.mock.calls.at(-1)![0].adoptIdentity).toBeUndefined();
}
if (scenario === "plugin-managed-github") expect(rebind).toHaveBeenCalledOnce();
if (scenario === "plugin-managed-github" || scenario === "plugin-environment-delivered") expect(rebind).toHaveBeenCalledOnce();
if (scenario === "plugin-environment-upgrade") {
expect(firstSession.close).toHaveBeenCalledWith({ reason: "warm native session configuration changed" });
expect(owners!.mock.calls.at(-1)![0]).toMatchObject({ resumeFrom: "task-first", configuredEnvironmentVersion: 1, configuredEnvironment: { FEATURE_FLAG: "on" } });
}
expect(order).toEqual(reusable ? ["execute-next"] : ["retire", "execute-next"]);
if (scenario === "changed-external-checkpoint") {
expect(launchedJournal?.slice(-2)).toEqual(["runner.drain", "runner.suspend"]);
@@ -18345,7 +18354,7 @@ describe("runnerd provider runtime wiring", () => {
state.toolAuthorityDefinitions.mockImplementation(async binding => binding.readRemoteTaskFile ? [{ name: "register_deliverable" }] as never : []);
const readWorkspaceFile = vi.fn(async () => Buffer.from("proof"));
const release = vi.fn(async () => {}), resume = vi.fn(async () => "resumed" as const);
const owner = vi.spyOn(pluginTaskRuntime, "createPluginRunnerTaskOwner").mockReturnValue({ launcher, registration, driver, readWorkspaceFile, release, resume, isRetired: () => false, retireSupersededTask: async () => false, retiredBeforeClaim: () => false, credentialsUpdated: vi.fn(), rebind:vi.fn() });
const owner = vi.spyOn(pluginTaskRuntime, "createPluginRunnerTaskOwner").mockReturnValue({ launcher, registration, driver, readWorkspaceFile, release, resume, isRetired: () => false, retireSupersededTask: async () => false, retiredBeforeClaim: () => false, configuredEnvironmentDelivered: () => false, credentialsUpdated: vi.fn(), rebind:vi.fn() });
const description = { kind: "description" as const, launchPreparationVersion: 1 as const, projectAuthCheckVersion: 1 as const,
releaseResumeVersion: 1 as const, ...(kind === "codex" ? { workspaceFileReadVersion: 1 as const } : {}),
taskId: "task", runner: { version: "fixture", digest: `sha256:${"a".repeat(64)}` } };
@@ -77,7 +77,7 @@ import {
isKnownNativeSessionRootEntry,
} from "./native-session-root-entries.js";
import { createRunPreparationTiming } from "../execution-preparation-timing.js";
import { configuredEnvironment, PROVIDER_CREDENTIAL_ENVIRONMENT_KEYS } from "../../vendor/paperclip-runner/index.js";
import { CONFIGURED_ENVIRONMENT_KEYS, configuredEnvironment, PROVIDER_CREDENTIAL_ENVIRONMENT_KEYS } from "../../vendor/paperclip-runner/index.js";
import { parseProviderPerformanceSpans } from "../../vendor/paperclip-runner/index.js";
import { apiKeyBillingType } from "@paperclipai/adapter-utils/api-billing-type";
import { agents } from "@paperclipai/db";
@@ -8557,6 +8557,11 @@ function needsCoreGitHubAccess(input: Pick<Parameters<typeof executePaperclipNat
return Boolean(input.managedGitHub && !(target?.kind === "remote" && target.transport === "sandbox" && target.runnerTask));
}
function pluginTaskConfiguredEnvironment(environment: NodeJS.ProcessEnv | undefined): Record<string, string> {
return Object.fromEntries(Object.entries(configuredEnvironment(environment)).flatMap(([key, value]) =>
key !== CONFIGURED_ENVIRONMENT_KEYS && typeof value === "string" ? [[key, value]] : []));
}
function nativeProcessReuseKey(input: Parameters<typeof executePaperclipNativeSession>[0]): string | undefined {
const environment = input.runnerEnvironment;
if (!input.managedGitHub && environment?.PAPERCLIP_GITHUB_BROKER_TOKEN) return undefined;
@@ -11954,6 +11959,9 @@ async function executePaperclipNativeSessionAttempt(
entry.closeOnReleaseReason !== undefined ||
entry.configDigest !== warmConfigDigest ||
!canReuseNativeProcess(input, entry.processConfigDigest) ||
(entry.pluginTaskId !== undefined && pluginTaskDescription?.configuredEnvironmentVersion === 1
&& pluginTaskSessionOwners.get(entry.session)?.configuredEnvironmentDelivered() === false
&& Object.keys(pluginTaskConfiguredEnvironment(input.runnerEnvironment)).length > 0) ||
Boolean(entry.githubAccess) !== needsCoreGitHubAccess(input) ||
entry.githubAccess?.ready === false ||
(entry.githubAccess !== undefined && entry.githubAccess.duplexRequested !== adapterExecutionTargetEnablesSandboxDuplexBridge(input.runnerExecutionTarget))
@@ -16377,6 +16385,11 @@ async function createRunnerdBackendWithinSessionClaim(
await registerPluginTaskCredentialHandoff(input.db, { companyId: input.execution.binding.companyId, leaseId: remoteTarget.leaseId },
credentials.accountIdentity, input.managedAiCredentialWriteback);
}
const taskConfiguredEnvironment = pluginTaskConfiguredEnvironment(input.runnerEnvironment);
if (description.configuredEnvironmentVersion !== 1 && Object.keys(taskConfiguredEnvironment).length > 0) {
await input.onLog?.("stderr", `[paperclip] The environment plugin does not support configured environment variables. These variables were not set: ${
Object.keys(taskConfiguredEnvironment).sort().join(", ")}. Update the plugin to deliver them.\n`);
}
const ownerInput: Parameters<typeof createPluginRunnerTaskOwner>[0] = { ...credentials, taskId: description.taskId,
executionContext: input.executionContext?.pluginSupported ? input.executionContext : undefined,
// Warm retirement can outlive the run's temporary credential home; complete uses the durable handoff.
@@ -16396,6 +16409,8 @@ async function createRunnerdBackendWithinSessionClaim(
}),
warmTaskVersion: description.warmTaskVersion,
githubCredentialBrokerVersion: description.githubCredentialBrokerVersion,
configuredEnvironmentVersion: description.configuredEnvironmentVersion,
configuredEnvironment: taskConfiguredEnvironment,
releaseResumeVersion: description.releaseResumeVersion,
authorityRunId: description.releaseResumeVersion === 1 ? input.execution.binding.runId : undefined,
releasedSource: input.remoteWarmRecovery?.releasedSource,
@@ -914,3 +914,38 @@ it("routes credential notifications to the current warm lease after rebind", asy
expect(successor).toHaveBeenCalledExactlyOnceWith(event);
expect(task).not.toHaveBeenCalled();
});
describe("plugin task configured environment", () => {
const configuredEnvironment = { STRIPE_SECRET_KEY: "fixture-secret", FEATURE_FLAG: "on" };
it.each([1, undefined] as const)("submits the variables only to a provider that supports them (%s)", async version => {
const { task } = provider();
const owner = createPluginRunnerTaskOwner({ taskId: "task", projectAuthCheckVersion: 1, task, projectIds: [], harness: "codex", pollMs: 1,
configuredEnvironmentVersion: version, configuredEnvironment });
await prepare(owner);
ingress.connect.mockReturnValue({ ready: Promise.resolve(), close: async () => {} });
const registration = await owner.registration({} as never, "run");
const handle = owner.launcher(launchSpec());
registration.activate(); await registration.ready();
await registration.release(); await registration.checkpoint("unsettled"); await handle.completion;
const submit = task.mock.calls.find(([op]) => op.kind === "submit")?.[0];
if (version === 1) expect(submit).toMatchObject({ configuredEnvironment });
else expect(submit).not.toHaveProperty("configuredEnvironment");
expect(owner.configuredEnvironmentDelivered()).toBe(version === 1);
expect(task.mock.calls.find(([op]) => op.kind === "prepare")?.[0]).not.toHaveProperty("configuredEnvironment");
});
it.each([true, false])("sends the variables on resume only for a session handoff (%s)", async sessionHandoff => {
const task = vi.fn(async (_operation: any): Promise<unknown> => ({ kind: "resume", taskId: "task", outcome: "resumed" }));
const owner = createPluginRunnerTaskOwner({ taskId: "task", projectIds: ["project"], harness: "codex", task,
warmTaskVersion: 1, releaseResumeVersion: 1, accountIdentity: "selected-account", adoptIdentity: requirements.identity,
authorityRunId: "run", sessionHandoff, configuredEnvironmentVersion: 1, configuredEnvironment });
await expect(owner.resume(requirements.identity, "transient-ticket")).resolves.toBe("resumed");
expect(task).toHaveBeenCalledExactlyOnceWith({
kind: "resume", identity: requirements.identity, bootstrapTicket: "transient-ticket",
...(sessionHandoff ? { configuredEnvironment } : {}),
}, { expectedTaskId: "task" });
expect(owner.configuredEnvironmentDelivered()).toBe(sessionHandoff ? true : undefined);
});
});
@@ -55,6 +55,8 @@ export function createPluginRunnerTaskOwner(input: {
onRetired?: (identity: DurableRecoveryIdentity) => Promise<void>;
githubBroker?: { url: string; token: string };
githubCredentialBrokerVersion?: 1;
configuredEnvironmentVersion?: 1;
configuredEnvironment?: Readonly<Record<string, string>>;
adoptIdentity?: DurableRecoveryIdentity;
}) {
const taskId = input.taskId;
@@ -83,6 +85,9 @@ export function createPluginRunnerTaskOwner(input: {
const running = new Promise<void>((resolve, reject) => { markReady = resolve; failReady = reject; });
void running.catch(() => undefined);
if (input.adoptIdentity) markReady();
const configuredEnvironmentFields = (launchesRunner: boolean) =>
input.configuredEnvironmentVersion === 1 && launchesRunner ? { configuredEnvironment: { ...input.configuredEnvironment } } : {};
let configuredEnvironmentDelivered: boolean | undefined = input.adoptIdentity ? undefined : false;
const call = async (operation: PluginEnvironmentTaskOperation) => {
const phase = ({ prepare: "execution.plugin_prepare", check_project_auth: "execution.plugin_project_auth",
submit: "execution.plugin_submit", connection: "execution.plugin_connection" } as const)[operation.kind as "prepare" | "check_project_auth" | "submit" | "connection"];
@@ -204,6 +209,7 @@ export function createPluginRunnerTaskOwner(input: {
...(input.credentialIdentity ? { credentialIdentity: input.credentialIdentity } : {}),
...(input.accountIdentity ? { accountIdentity: input.accountIdentity } : {}),
...(input.credential ? { credential: input.credential } : {}),
...configuredEnvironmentFields(true),
runner: { protocolMin: RUNNER_PRP_PROTOCOL_MIN, protocolMax: RUNNER_PRP_PROTOCOL_MAX,
harness: input.harness,
runnerId: native.identity.runnerInstanceId, leaseId: native.identity.environmentLeaseId,
@@ -217,6 +223,7 @@ export function createPluginRunnerTaskOwner(input: {
});
launchIdentity = native.identity;
launched = true;
configuredEnvironmentDelivered = "configuredEnvironment" in operation;
const child: RunnerProcessHandle["child"] = { exitCode: null, signalCode: null,
kill: () => {
stopRequested = true;
@@ -426,9 +433,11 @@ export function createPluginRunnerTaskOwner(input: {
: undefined;
const result = await call(environmentTaskOperationSchema.parse({ kind: "resume", identity, bootstrapTicket,
...(handoffCredential ? { handoffCredential } : {}),
...configuredEnvironmentFields(!!input.sessionHandoff),
}));
requireReleaseResume();
if (result.kind !== "resume") throw new Error("Plugin Runner resume result unavailable");
if (result.outcome === "resumed" && input.sessionHandoff) configuredEnvironmentDelivered = input.configuredEnvironmentVersion === 1;
if (result.outcome === "unavailable") {
const state = await call({ kind: "status" }).catch(() => undefined);
retiredBeforeClaim = state?.kind === "status" && state.executionStopped === true && state.sessionStateAvailable === true;
@@ -462,6 +471,7 @@ export function createPluginRunnerTaskOwner(input: {
// stop request. Completion also proves credential/writeback obligations ran.
isRetired: () => stoppedState?.executionStopped === true && completed && !detached,
retiredBeforeClaim: () => retiredBeforeClaim,
configuredEnvironmentDelivered: () => configuredEnvironmentDelivered,
rebind(next: typeof input) {
if (!launched || stopRequested || stoppedState || detached || next.taskId !== taskId || next.harness !== input.harness ||
input.accountIdentity !== next.accountIdentity || input.credentialIdentity !== next.credentialIdentity ||
@@ -0,0 +1,105 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
const driverFor = vi.hoisted(() => vi.fn());
vi.mock("./plugin-runner-ai-connection.js", () => ({ pluginEnvironmentRunnerTaskDriver: driverFor }));
const instanceDefault = vi.hoisted(() => ({ value: null as string | null }));
vi.mock("./instance-settings.js", () => ({ instanceSettingsService: () => ({ get: async () => ({ defaultEnvironmentId: instanceDefault.value }) }) }));
const {
assertEnvironmentVariablesNotProtected,
checkAgentProtectedEnvironmentKeys,
assertNoProtectedEnvironmentKeys,
listProtectedEnvironmentKeyHolders,
protectedEnvironmentKeyWarnings,
} = await import("./protected-environment-keys.js");
const holders = [
{ environmentId: "computer-a", environmentName: "Computer A", keys: new Set(["DESKTOP_SESSION"]) },
{ environmentId: "computer-b", environmentName: "Computer B", keys: new Set(["DESKTOP_SESSION", "DESKTOP_DISPLAY"]) },
];
function fakeDb(...results: unknown[][]) {
const selects = { count: 0 };
const db = { select: () => ({ from: () => ({ where: async () => results[selects.count++] ?? [] }) }) };
return Object.assign(db, { selects }) as never as { selects: { count: number } } & Parameters<typeof listProtectedEnvironmentKeyHolders>[0];
}
beforeEach(() => { driverFor.mockReset(); instanceDefault.value = null; });
describe("protected environment keys", () => {
it("rejects a key that the selected environment sets itself", () => {
expect(() => assertNoProtectedEnvironmentKeys(holders, "computer-a", { DESKTOP_SESSION: "mine", OTHER: "ok" }))
.toThrow(expect.objectContaining({ status: 422, message: expect.stringContaining("DESKTOP_SESSION is set by Computer A on its tasks"),
details: { code: "protected_environment_variable", keys: ["DESKTOP_SESSION"], environmentId: "computer-a" } }));
});
it("allows the key on another environment, or with none selected", () => {
expect(() => assertNoProtectedEnvironmentKeys(holders, "local", { DESKTOP_SESSION: "mine" })).not.toThrow();
expect(() => assertNoProtectedEnvironmentKeys(holders, null, { DESKTOP_SESSION: "mine" })).not.toThrow();
expect(() => assertNoProtectedEnvironmentKeys(holders, "computer-a", { OTHER: "ok" })).not.toThrow();
});
it("names every environment that protects a key in a friendly notice", () => {
expect(protectedEnvironmentKeyWarnings(holders, { DESKTOP_DISPLAY: ":1", DESKTOP_SESSION: "x", OTHER: "ok" }, "env")).toEqual([
{ code: "protected_environment_variable", field: "env.DESKTOP_DISPLAY",
message: "DESKTOP_DISPLAY is set by Computer B on its tasks. Agents running there may see the platform's value instead of this one." },
{ code: "protected_environment_variable", field: "env.DESKTOP_SESSION",
message: "DESKTOP_SESSION is set by Computer A, Computer B on their tasks. Agents running there may see the platform's value instead of this one." },
]);
expect(protectedEnvironmentKeyWarnings(holders, null, "env")).toEqual([]);
});
it("lists only plugin environments whose task driver declares keys, reading the registry once", async () => {
const drivers = [
{ driverKey: "computer", supportsTasks: true, protectedEnvironmentKeys: ["DESKTOP_SESSION"] },
{ driverKey: "plain", supportsTasks: true },
{ driverKey: "storage", protectedEnvironmentKeys: ["IGNORED"] },
];
const db = fakeDb([
{ id: "a", name: "Computer", config: { pluginKey: "p", driverKey: "computer" } },
{ id: "b", name: "Plain", config: { pluginKey: "p", driverKey: "plain" } },
{ id: "c", name: "Second computer", config: { pluginKey: "p", driverKey: "computer" } },
{ id: "d", name: "Storage", config: { pluginKey: "p", driverKey: "storage" } },
{ id: "e", name: "Unregistered", config: { pluginKey: "unregistered", driverKey: "computer" } },
{ id: "f", name: "Missing", config: { pluginKey: "missing", driverKey: "computer" } },
], [
{ pluginKey: "p", manifestJson: { capabilities: ["environment.drivers.register"], environmentDrivers: drivers } },
{ pluginKey: "unregistered", manifestJson: { capabilities: [], environmentDrivers: drivers } },
]);
expect(await listProtectedEnvironmentKeyHolders(db)).toEqual([
{ environmentId: "a", environmentName: "Computer", keys: new Set(["DESKTOP_SESSION"]) },
{ environmentId: "c", environmentName: "Second computer", keys: new Set(["DESKTOP_SESSION"]) },
]);
expect(db.selects.count).toBe(2);
const empty = fakeDb([{ id: "x", name: "No plugin key", config: {} }]);
expect(await listProtectedEnvironmentKeyHolders(empty)).toEqual([]);
expect(empty.selects.count).toBe(1);
});
it("rejects an environment's own variable when its driver protects it", async () => {
driverFor.mockResolvedValue({ protectedEnvironmentKeys: ["DESKTOP_SESSION"] });
await expect(assertEnvironmentVariablesNotProtected(fakeDb([]), { id: "a", name: "Computer", driver: "plugin",
config: { pluginKey: "p", driverKey: "computer" } }, { DESKTOP_SESSION: "x" }))
.rejects.toMatchObject({ status: 422, details: { code: "protected_environment_variable", keys: ["DESKTOP_SESSION"] } });
await expect(assertEnvironmentVariablesNotProtected(fakeDb([]), { name: "Local", driver: "local", config: {} }, { DESKTOP_SESSION: "x" }))
.resolves.toBeUndefined();
expect(driverFor).toHaveBeenCalledTimes(1);
});
it("checks an agent without its own environment against the instance default", async () => {
const environmentRows = [{ id: "computer-env", name: "Team Computer", config: { pluginKey: "p", driverKey: "computer" } }];
const pluginRows = [{ pluginKey: "p", manifestJson: { capabilities: ["environment.drivers.register"],
environmentDrivers: [{ driverKey: "computer", supportsTasks: true, protectedEnvironmentKeys: ["DESKTOP_SESSION"] }] } }];
const db = () => fakeDb(environmentRows, pluginRows);
const config = { env: { DESKTOP_SESSION: { type: "plain", value: "mine" } } };
instanceDefault.value = "computer-env";
await expect(checkAgentProtectedEnvironmentKeys(db(), config, null))
.rejects.toMatchObject({ status: 422, details: { code: "protected_environment_variable", environmentId: "computer-env" } });
await expect(checkAgentProtectedEnvironmentKeys(db(), config, "computer-env")).rejects.toMatchObject({ status: 422 });
expect(await checkAgentProtectedEnvironmentKeys(db(), config, "local-env"))
.toEqual([expect.objectContaining({ field: "adapterConfig.env.DESKTOP_SESSION" })]);
instanceDefault.value = "local-env";
expect(await checkAgentProtectedEnvironmentKeys(db(), config, undefined)).toHaveLength(1);
expect(await checkAgentProtectedEnvironmentKeys(db(), { env: {} }, null)).toEqual([]);
});
});
@@ -0,0 +1,99 @@
import { and, eq, inArray, ne } from "drizzle-orm";
import { environments, plugins as pluginsTable, type Db } from "@paperclipai/db";
import type { AgentConfigurationWarning } from "@paperclipai/shared";
import { unprocessable } from "../errors.js";
import { pluginEnvironmentRunnerTaskDriver } from "./plugin-runner-ai-connection.js";
import { instanceSettingsService } from "./instance-settings.js";
export interface ProtectedEnvironmentKeyHolder {
environmentId: string;
environmentName: string;
keys: ReadonlySet<string>;
}
export async function listProtectedEnvironmentKeyHolders(db: Db): Promise<ProtectedEnvironmentKeyHolder[]> {
const rows = await db.select({ id: environments.id, name: environments.name, config: environments.config })
.from(environments).where(and(eq(environments.driver, "plugin"), eq(environments.status, "active")));
const pluginKeys = [...new Set(rows.flatMap(row => typeof row.config?.pluginKey === "string" ? [row.config.pluginKey] : []))];
if (pluginKeys.length === 0) return [];
const plugins = new Map((await db.select({ pluginKey: pluginsTable.pluginKey, manifestJson: pluginsTable.manifestJson }).from(pluginsTable)
.where(and(inArray(pluginsTable.pluginKey, pluginKeys), ne(pluginsTable.status, "uninstalled")))).map(plugin => [plugin.pluginKey, plugin]));
const holders: ProtectedEnvironmentKeyHolder[] = [];
for (const row of rows) {
const config = row.config ?? {};
const plugin = typeof config.pluginKey === "string" ? plugins.get(config.pluginKey) : undefined;
const driver = plugin?.manifestJson?.capabilities?.includes("environment.drivers.register")
? plugin.manifestJson.environmentDrivers?.find(candidate => candidate.driverKey === config.driverKey && candidate.supportsTasks === true)
: undefined;
const keys = driver?.protectedEnvironmentKeys ?? [];
if (keys.length > 0) holders.push({ environmentId: row.id, environmentName: row.name, keys: new Set(keys) });
}
return holders;
}
function configuredKeys(env: unknown): string[] {
return env !== null && typeof env === "object" && !Array.isArray(env) ? Object.keys(env) : [];
}
function rejectProtectedKeys(holder: { environmentId?: string; environmentName: string; keys: ReadonlySet<string> }, env: unknown): void {
const keys = configuredKeys(env).filter(key => holder.keys.has(key)).sort();
if (keys.length === 0) return;
throw unprocessable(
`${keys.join(", ")} ${keys.length === 1 ? "is" : "are"} set by ${holder.environmentName} on its tasks. `
+ `Remove ${keys.length === 1 ? "it" : "them"} from the environment variables, or choose another environment.`,
{ code: "protected_environment_variable", keys, ...(holder.environmentId ? { environmentId: holder.environmentId } : {}) },
);
}
export function assertNoProtectedEnvironmentKeys(
holders: readonly ProtectedEnvironmentKeyHolder[],
environmentId: string | null | undefined,
env: unknown,
): void {
const holder = environmentId ? holders.find(candidate => candidate.environmentId === environmentId) : undefined;
if (holder) rejectProtectedKeys(holder, env);
}
export async function assertEnvironmentVariablesNotProtected(
db: Db,
environment: { id?: string; name: string; driver: string; config: unknown },
envVars: unknown,
): Promise<void> {
if (environment.driver !== "plugin" || configuredKeys(envVars).length === 0) return;
const config = environment.config !== null && typeof environment.config === "object" && !Array.isArray(environment.config)
? environment.config as Record<string, unknown> : {};
const driver = await pluginEnvironmentRunnerTaskDriver(db, { driver: "plugin", config });
const keys = driver?.protectedEnvironmentKeys ?? [];
if (keys.length > 0) rejectProtectedKeys({ environmentId: environment.id, environmentName: environment.name, keys: new Set(keys) }, envVars);
}
export async function checkAgentProtectedEnvironmentKeys(
db: Db,
adapterConfig: unknown,
environmentId: string | null | undefined,
): Promise<AgentConfigurationWarning[]> {
const env = adapterConfig !== null && typeof adapterConfig === "object" ? (adapterConfig as { env?: unknown }).env : undefined;
if (configuredKeys(env).length === 0) return [];
const holders = await listProtectedEnvironmentKeyHolders(db);
if (holders.length === 0) return [];
const effectiveEnvironmentId = environmentId ?? (await instanceSettingsService(db).get()).defaultEnvironmentId ?? null;
assertNoProtectedEnvironmentKeys(holders, effectiveEnvironmentId, env);
return protectedEnvironmentKeyWarnings(holders, env, "adapterConfig.env");
}
export function protectedEnvironmentKeyWarnings(
holders: readonly ProtectedEnvironmentKeyHolder[],
env: unknown,
field: string,
): AgentConfigurationWarning[] {
return configuredKeys(env).sort().flatMap(key => {
const names = holders.filter(holder => holder.keys.has(key)).map(holder => holder.environmentName);
if (names.length === 0) return [];
return [{
code: "protected_environment_variable" as const,
field: `${field}.${key}`,
message: `${key} is set by ${names.join(", ")} on ${names.length === 1 ? "its" : "their"} tasks. `
+ "Agents running there may see the platform's value instead of this one.",
}];
});
}
@@ -13,11 +13,11 @@
"packages/plugins/sdk/src/environment-stop-error.ts": "b0e03f8aa2b2170ba095da5c7138050fced3f3cb",
"packages/plugins/sdk/src/environment-sync-error.ts": "7d6a51a95da49a7da4525aebbab6382dc5c44ae8",
"packages/plugins/sdk/src/environment-task-error.ts": "98aae8a06743b38884b68cb9a3ec44c57b34c0e4",
"packages/plugins/sdk/src/environment-tasks.ts": "de583d809187f0677e25b95f22c3c42961a9d2e2",
"packages/plugins/sdk/src/environment-tasks.ts": "318915dd6f2f6c86e875bfcb3a87a52b21afba1d",
"packages/plugins/sdk/src/host-client-factory.ts": "e0301c390ea13f2340b669383f07af2455e48c8a",
"packages/plugins/sdk/src/idle-drain.test.ts": "cc59f7881e7d46c89395a1d93d74f6c6b9b0a64a",
"packages/plugins/sdk/src/idle-drain.ts": "ae6e4c6be4657a3d541396922b3bc551b8db557f",
"packages/plugins/sdk/src/index.ts": "4e573c181198ea98442321cc136341741e856ff7",
"packages/plugins/sdk/src/index.ts": "061377861158a1021f74d4101d0453e6751c0cb0",
"packages/plugins/sdk/src/invocation-tracer.ts": "b28ac4aa4bc3e82658abac4a8081ed4508008696",
"packages/plugins/sdk/src/protocol.duplex-channel.test.ts": "18255eb3d63038dc459240c111cbcb29fcba25cc",
"packages/plugins/sdk/src/protocol.ts": "6cbc642412650a511c60b23f5625ac018d189f9d",
@@ -331,7 +331,7 @@
"packages/shared/src/routine-variables.ts": "43d57551aaf8fcd32c10733af3198b6932b0d5d4",
"packages/shared/src/run-failure-cause.test.ts": "68a726ac3e3b9be394ffa32b65acc6119e06424c",
"packages/shared/src/run-failure-cause.ts": "6f7c646d715f384ee0a01805d5507b0c7a0669a2",
"packages/shared/src/runner-configuration-warnings.ts": "81db25b1b3ac273ba9b21911672a659b10129917",
"packages/shared/src/runner-configuration-warnings.ts": "7d8db761ee51bec746c425320d5900ef3505de1b",
"packages/shared/src/runner-goal.test.ts": "05814124d8f592d6bf4ca78541474e6f354411d1",
"packages/shared/src/runner-goal.ts": "dc61b33fd36d2ed9f68fc3a5630a81d1e001333b",
"packages/shared/src/runtime-exposure/loopback-bind.test.ts": "91e49c143f2ec84d369699fbec71d63d763a1ec8",
@@ -412,11 +412,11 @@
"packages/shared/src/types/issue.ts": "725bd6f677b9d461460697d1ce10dee739a66ebe",
"packages/shared/src/types/live.ts": "b90e55e4de8600c6fc17d7fa8d89079d4ae655ec",
"packages/shared/src/types/native-finalization.ts": "c026a73003ae232fea4f7624d561493b383df358",
"packages/shared/src/types/plugin.ts": "22e1e35307f91fdf5c210b86bae7746594669516",
"packages/shared/src/types/project.ts": "78eeea3694ce860d5d0be59c158c399c03368078",
"packages/shared/src/types/plugin.ts": "d009ee12f56e0e168d420cd46bdb8dbea323824c",
"packages/shared/src/types/project.ts": "50b9d9c51cb38d5862e287c1a47726716603f21c",
"packages/shared/src/types/quota.ts": "a0686a9afb3111a4de093f66200dc0c9152e883e",
"packages/shared/src/types/resource-memberships.ts": "9eab6fad50facf3e489f8c40e5bedd92e1d1faf8",
"packages/shared/src/types/routine.ts": "e5e5a93d63233029b9bf258558ad155677a4eca7",
"packages/shared/src/types/routine.ts": "850fdeb686d2dfcab190811cede79ee5d66be689",
"packages/shared/src/types/runtime-exposure.ts": "785f053a7ad5448cde94f36738cdb90585bbc92e",
"packages/shared/src/types/search.ts": "4e208a9b1942991bfe5f29ef58ec71625e2693e9",
"packages/shared/src/types/secrets.ts": "05b07bce0550c1b3a160615bed661bc7f9c26156",
@@ -493,8 +493,8 @@
"packages/shared/src/validators/native-finalization.ts": "d4e674de6ac7d36385e6f6c2172fa16ffc9b1830",
"packages/shared/src/validators/onboarding-seed.ts": "de302a8400d4199053f379d9ed853522a3ac6d32",
"packages/shared/src/validators/partial.ts": "fa60ec7481fc14175365e9e500c814b159f1ab53",
"packages/shared/src/validators/plugin.test.ts": "23bc443850d46d815877a71a44625fd42aebb00a",
"packages/shared/src/validators/plugin.ts": "782e051567729c2eb91a3b80e883b4a8ed996646",
"packages/shared/src/validators/plugin.test.ts": "d125614df25bf325e5627cebb82dd917c3931e77",
"packages/shared/src/validators/plugin.ts": "37dd518f4adcb65bdb9504fae9dfb9df787096cc",
"packages/shared/src/validators/project.ts": "6ea168f5faf3161e6004ea47274f60634c77b219",
"packages/shared/src/validators/provider-trace.ts": "b38b6200a2e51513f5dca0f8b008f2fe68175e82",
"packages/shared/src/validators/resource-memberships.ts": "b124ac8a8f24b4dbb03ae82bcc87541f6b4ecdfd",
+8
View File
@@ -0,0 +1,8 @@
import type { AgentConfigurationWarning } from "@paperclipai/shared";
export function configurationWarningMessages(
result: { configurationWarnings?: AgentConfigurationWarning[] } | null | undefined,
): string | null {
const warnings = result?.configurationWarnings ?? [];
return warnings.length > 0 ? warnings.map(warning => warning.message).join("\n") : null;
}
+8 -3
View File
@@ -1,4 +1,5 @@
import { useShowAgentCreatedTasks } from "../hooks/useShowAgentCreatedTasks";
import { configurationWarningMessages } from "../lib/configuration-warnings";
import { useCallback, useEffect, useMemo, useState, useRef } from "react";
import { Link, useParams, useNavigate, useLocation, Navigate } from "@/lib/router";
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
@@ -467,7 +468,9 @@ export function ProjectDetail() {
const updateProject = useMutation({
mutationFn: (data: Record<string, unknown>) =>
projectsApi.update(projectLookupRef, data, resolvedCompanyId ?? lookupCompanyId),
onSuccess: (_project, data) => {
onSuccess: (updated, data) => {
const notice = configurationWarningMessages(updated);
if (notice) pushToast({ title: "Project saved", body: notice, tone: "warn" });
invalidateProject();
if (data.visibility !== undefined) queryClient.invalidateQueries({ queryKey: ["issues"] });
},
@@ -599,7 +602,9 @@ export function ProjectDetail() {
fieldSaveRequestIds.current[field] = requestId;
setFieldState(field, "saving");
try {
await projectsApi.update(projectLookupRef, data, resolvedCompanyId ?? lookupCompanyId);
const updated = await projectsApi.update(projectLookupRef, data, resolvedCompanyId ?? lookupCompanyId);
const notice = configurationWarningMessages(updated);
if (notice) pushToast({ title: "Project saved", body: notice, tone: "warn" });
invalidateProject();
if (data.visibility !== undefined) queryClient.invalidateQueries({ queryKey: ["issues"] });
if (fieldSaveRequestIds.current[field] !== requestId) return;
@@ -611,7 +616,7 @@ export function ProjectDetail() {
scheduleFieldReset(field, 3000);
throw error;
}
}, [invalidateProject, lookupCompanyId, projectLookupRef, queryClient, resolvedCompanyId, scheduleFieldReset, setFieldState]);
}, [invalidateProject, lookupCompanyId, projectLookupRef, pushToast, queryClient, resolvedCompanyId, scheduleFieldReset, setFieldState]);
const projectBudgetSummary = useMemo(() => {
const matched = budgetOverview?.policies.find(
+4 -1
View File
@@ -1,4 +1,5 @@
import { companyProjectsQuery } from "@/lib/company-projects-query";
import { configurationWarningMessages } from "../lib/configuration-warnings";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { Navigate, useNavigate, useParams } from "@/lib/router";
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
@@ -397,8 +398,10 @@ export function RoutineDetail() {
...(baseRevisionId ? { baseRevisionId } : {}),
});
},
onSuccess: async () => {
onSuccess: async (updated) => {
setSaveConflict(false);
const notice = configurationWarningMessages(updated);
if (notice) pushToast({ title: "Routine saved", body: notice, tone: "warn" });
await Promise.all([
queryClient.invalidateQueries({ queryKey: queryKeys.routines.detail(routineId!) }),
queryClient.invalidateQueries({ queryKey: queryKeys.routines.list(selectedCompanyId!) }),
+4 -1
View File
@@ -1,4 +1,5 @@
import { companyProjectsQuery } from "@/lib/company-projects-query";
import { configurationWarningMessages } from "../lib/configuration-warnings";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { Navigate, useNavigate, useParams, useSearchParams } from "@/lib/router";
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
@@ -376,8 +377,10 @@ export function RoutineDetail() {
...(baseRevisionId ? { baseRevisionId } : {}),
});
},
onSuccess: async () => {
onSuccess: async (updated) => {
setSaveConflict(false);
const notice = configurationWarningMessages(updated);
if (notice) pushToast({ title: "Routine saved", body: notice, tone: "warn" });
await Promise.all([
queryClient.invalidateQueries({ queryKey: queryKeys.routines.detail(routineId!) }),
queryClient.invalidateQueries({ queryKey: queryKeys.routines.list(selectedCompanyId!) }),