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