Files
PaperClipAI/ui/src/lib/adapter-test-environment.test.ts
T
Nicky LeachandClaude Opus 5.5 21a1e78852 feat(environments): add managed plugin environment rows (#19490)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A managed instance gets its instance-level environments from the
`PAPERCLIP_MANAGED_CONFIG` document
> - That document cannot declare a plugin environment yet, so a managed
instance cannot get a plugin-provided environment without manual setup
> - The full change is split into three pull requests. This first one
adds the plugin environment rows and their write floor, and nothing
calls them yet
> - The second pull request lets the managed config declare plugin
entries and provisions them at boot. The third sets the instance default
once and advertises the new managed-config capability
> - The benefit is a smaller review for each step, and no instance
changes behavior until the last step lands

## Linked Issues or Issue Description

**Subsystem affected**
Server environments (managed-config environment provisioning,
environment routes) and the board UI's adapter Test target.

**Problem or motivation**
A managed instance cannot get a plugin environment from its managed
config. Company settings cannot create one either. So each managed
instance that needs one requires manual setup.

**Proposed solution**
Over three pull requests, let an `environments` entry in the managed
config declare `driver: "plugin"`. Boot then provisions one locked row
for each plugin entry, and makes one of them the instance default once
on new instances. This pull request adds only the row layer: create or
adopt a marked row, archive it, find it, and keep tenants from editing
it.

**Alternatives considered**
Manual setup on each instance, and a new control-plane endpoint. Both
need a step outside the deploy. The managed config already delivers the
sandbox entry.

**Roadmap alignment**
This extends the existing managed-config `environments` section, which
already provisions the managed sandbox. It adds no new product surface.

## What Changed

- New `server/src/services/managed-plugin-environments.ts`, used through
new `environmentService` methods (`ensureManagedPluginEnvironment`,
`archiveManagedPluginEnvironment`, `findManagedPluginEnvironment`):
- The ensure validates the driver config through
`normalizeEnvironmentConfig` and
`validatePluginEnvironmentDriverConfig`, the same path an
operator-created plugin environment takes.
- It marks the row `managedByPaperclip: true` and
`managedPluginEnvironment: "<pluginKey>:<driverKey>"`.
- It adopts an existing unmarked row for the same plugin and driver
instead of adding a second one, so a hand-made row keeps its agents.
- A row that already matches gets no write. Changes write activity log
entries.
- Archive sets an active marked row to `archived`. The next ensure
reactivates it.
- Migration `0437`: unique index
`environments_managed_plugin_environment_idx` on `metadata ->>
'managedPluginEnvironment'`. This is the only schema change of the three
pull requests. Snapshot `0432` is pruned to keep the five newest.
- `server/src/routes/environments.ts`:
`isPlatformProvisionedEnvironment` also covers the new marker (write
floor and redaction). `managedPluginEnvironment` is a reserved marker
key, so a client cannot stamp it on its own row. Nothing provisions
marked rows yet, so the marker-clear escape hatch stays open for them.
The next pull request refuses it while the managed config declares the
row's entry.
- `ui/src/lib/adapter-test-environment.ts`:
`resolveManagedSandboxEnvironmentId` requires `driver === "sandbox"`.
The plugin row also carries `managedByPaperclip`, so the old "not local"
check could take it for the managed sandbox.

## Verification

- `cd server && npx vitest run
src/__tests__/managed-plugin-environments.test.ts` (embedded Postgres):
- The ensure creates the marked row through the plugin validator. A
second ensure writes nothing and logs nothing.
- A hand-made row for the same plugin and driver is adopted. It keeps
its id and its agents.
  - Archive, then ensure, reactivates the row.
- The ensure refuses while the plugin has no running worker, and refuses
a name that another environment holds.
  - The unique index allows one row per marker.
- `npx vitest run src/__tests__/environment-routes.test.ts`: on a
cloud-managed instance, edit, env-var edit, status change and delete of
a marked plugin row are refused, including for instance admins. The
marker alone keeps the floor. A client cannot stamp the marker. The
marker clear is allowed.
- `npx vitest run src/__tests__/environment-service.test.ts`: passes.
- `cd ui && npx vitest run src/lib/adapter-test-environment.test.ts`:
the plugin row is never taken for the managed sandbox. Under
managed-sandbox-only, an agent on the sandbox tests in the sandbox, and
an agent on the plugin environment tests there.
- `pnpm --filter @paperclipai/server typecheck`, `pnpm --filter
@paperclipai/ui typecheck` and `pnpm --filter @paperclipai/db
check:migrations` pass.
- I did not run the full `pnpm test:run`, `pnpm -r typecheck` or `pnpm
build`. CI covers them. `pnpm verify` asks for broader verification
because of the migration.

## Risks

- Migration: one new partial unique index on a small table. No row
carries the marker before this change, so the index cannot fail on
existing data.
- No caller uses the new ensure yet, so no instance changes behavior.
- The UI change affects only lists that hold a non-sandbox row with
`managedByPaperclip`. Today that is only the local row, which the old
check already excluded.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, through Claude Code
with tool use (file edits, shell, test runs).

## 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
- [ ] All Paperclip CI gates are green
- [ ] 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>
2026-11-06 16:52:43 +00:00

355 lines
13 KiB
TypeScript

import { describe, expect, it } from "vitest";
import type { Environment } from "@paperclipai/shared";
import {
ManagedSandboxUnavailableForTestError,
resolveAdapterTestEnvironmentId,
resolveLocalDefaultEnvironmentId,
resolveManagedSandboxEnvironmentId,
} from "./adapter-test-environment";
function makeEnvironment(overrides: Partial<Environment>): Environment {
return {
id: "env-id",
name: "Env",
description: null,
driver: "sandbox",
status: "active",
config: {},
envVars: {},
metadata: null,
createdAt: new Date(0),
updatedAt: new Date(0),
...overrides,
};
}
describe("resolveAdapterTestEnvironmentId", () => {
it("prefers the agent's own environment", () => {
expect(
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: "agent-env",
instanceDefaultEnvironmentId: "instance-env",
localDefaultEnvironmentId: "local-env",
}),
).toBe("agent-env");
});
it("falls back to the instance default when the agent has none", () => {
// The regression this pins: an agent relying on the instance default
// (e.g. a managed sandbox with extra CLIs baked into its image) must be
// tested inside that environment, not on the Paperclip host where the
// CLI does not exist.
expect(
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: null,
instanceDefaultEnvironmentId: "instance-env",
localDefaultEnvironmentId: "local-env",
}),
).toBe("instance-env");
expect(
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: "",
instanceDefaultEnvironmentId: "instance-env",
localDefaultEnvironmentId: "local-env",
}),
).toBe("instance-env");
});
it("falls back to the local default when neither an agent nor an instance default is set", () => {
// The server resolves a run with no agent or instance default to the local
// default environment. The Test must probe the same environment, not the
// host, so a Test result matches a real run.
expect(
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: null,
instanceDefaultEnvironmentId: null,
localDefaultEnvironmentId: "local-env",
}),
).toBe("local-env");
});
it("returns null (host probe) when no tier is set", () => {
expect(
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: undefined,
instanceDefaultEnvironmentId: undefined,
localDefaultEnvironmentId: undefined,
}),
).toBeNull();
expect(
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: "",
instanceDefaultEnvironmentId: null,
localDefaultEnvironmentId: null,
}),
).toBeNull();
});
it("redirects a local-default resolution to the managed sandbox under managed-sandbox-only", () => {
// The real run redirects a local resolution to the managed sandbox, so the
// Test must probe the managed sandbox, not the local default.
expect(
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: null,
instanceDefaultEnvironmentId: null,
localDefaultEnvironmentId: "local-env",
managedSandboxOnly: true,
managedSandboxEnvironmentId: "managed-env",
}),
).toBe("managed-env");
});
it("redirects a no-tier resolution to the managed sandbox under managed-sandbox-only", () => {
// The policy hides the local tier, so the list holds no local row and the
// resolution lands on no tier. The real run still resolves to local and
// redirects to the managed sandbox, so the Test does the same.
expect(
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: null,
instanceDefaultEnvironmentId: null,
localDefaultEnvironmentId: null,
managedSandboxOnly: true,
managedSandboxEnvironmentId: "managed-env",
}),
).toBe("managed-env");
});
it("fails closed when managed-sandbox-only is on but no managed sandbox exists", () => {
// The real run fails closed, so the Test must not fall back to a local host
// probe that reports a result for a target the run never uses.
expect(() =>
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: null,
instanceDefaultEnvironmentId: null,
localDefaultEnvironmentId: "local-env",
managedSandboxOnly: true,
managedSandboxEnvironmentId: null,
}),
).toThrow(ManagedSandboxUnavailableForTestError);
});
it("leaves a non-local default untouched under managed-sandbox-only", () => {
// The policy hides local; it does not forbid an ssh or a user sandbox that
// an agent or instance default names, so the Test probes that environment.
expect(
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: null,
instanceDefaultEnvironmentId: "ssh-env",
localDefaultEnvironmentId: "local-env",
managedSandboxOnly: true,
managedSandboxEnvironmentId: "managed-env",
}),
).toBe("ssh-env");
});
it("ignores the managed-sandbox redirect when the policy is off", () => {
expect(
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: null,
instanceDefaultEnvironmentId: null,
localDefaultEnvironmentId: "local-env",
managedSandboxOnly: false,
managedSandboxEnvironmentId: "managed-env",
}),
).toBe("local-env");
});
it("redirects an agent default that names the hidden local row to the managed sandbox", () => {
// The policy hides the local environment, so the client list holds no local
// row and the local-default lookup is null. An agent default that still
// names the hidden local row names no visible environment, so the resolver
// treats it as a local resolution and redirects to the managed sandbox.
expect(
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: "hidden-local-env",
instanceDefaultEnvironmentId: null,
localDefaultEnvironmentId: null,
managedSandboxOnly: true,
managedSandboxEnvironmentId: "managed-env",
visibleEnvironmentIds: ["managed-env", "ssh-env"],
}),
).toBe("managed-env");
});
it("fails closed when an agent default names the hidden local row and no managed sandbox exists", () => {
expect(() =>
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: "hidden-local-env",
instanceDefaultEnvironmentId: null,
localDefaultEnvironmentId: null,
managedSandboxOnly: true,
managedSandboxEnvironmentId: null,
visibleEnvironmentIds: ["ssh-env"],
}),
).toThrow(ManagedSandboxUnavailableForTestError);
});
it("leaves a visible non-local default untouched when a visibility list is supplied", () => {
expect(
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId: "ssh-env",
instanceDefaultEnvironmentId: null,
localDefaultEnvironmentId: null,
managedSandboxOnly: true,
managedSandboxEnvironmentId: "managed-env",
visibleEnvironmentIds: ["ssh-env", "managed-env"],
}),
).toBe("ssh-env");
});
});
describe("resolveManagedSandboxEnvironmentId", () => {
it("finds the non-local platform-managed environment", () => {
const environments = [
makeEnvironment({
id: "local-1",
driver: "local",
metadata: { managedByPaperclip: true, defaultForInstance: true },
}),
makeEnvironment({
id: "sandbox-1",
driver: "sandbox",
metadata: { managedByPaperclip: true },
}),
];
// The local-default row also carries the managed stamp, so the resolver must
// exclude the local driver and return the sandbox row.
expect(resolveManagedSandboxEnvironmentId(environments)).toBe("sandbox-1");
});
it("returns null when no managed sandbox environment exists", () => {
const environments = [
makeEnvironment({ id: "sandbox-1", driver: "sandbox", metadata: null }),
makeEnvironment({
id: "local-1",
driver: "local",
metadata: { managedByPaperclip: true, defaultForInstance: true },
}),
];
expect(resolveManagedSandboxEnvironmentId(environments)).toBeNull();
expect(resolveManagedSandboxEnvironmentId([])).toBeNull();
expect(resolveManagedSandboxEnvironmentId(null)).toBeNull();
});
it("skips an archived managed sandbox", () => {
// The server run-time resolver requires an active managed sandbox, so the
// Test resolution must not select an archived one. An archived sandbox row
// still carries the managed stamp, so the status guard is the only filter
// that excludes it. A real run rejects an archived sandbox, so the Test must
// reject it too.
const environments = [
makeEnvironment({
id: "sandbox-archived",
driver: "sandbox",
status: "archived",
metadata: { managedByPaperclip: true },
}),
makeEnvironment({
id: "local-1",
driver: "local",
metadata: { managedByPaperclip: true, defaultForInstance: true },
}),
];
expect(resolveManagedSandboxEnvironmentId(environments)).toBeNull();
});
it("selects the active managed sandbox and skips an archived one", () => {
// When both an archived and an active managed sandbox exist, the resolver
// returns the active row, matching the server run-time resolver.
const environments = [
makeEnvironment({
id: "sandbox-archived",
driver: "sandbox",
status: "archived",
metadata: { managedByPaperclip: true },
}),
makeEnvironment({
id: "sandbox-active",
driver: "sandbox",
status: "active",
metadata: { managedByPaperclip: true },
}),
];
expect(resolveManagedSandboxEnvironmentId(environments)).toBe("sandbox-active");
});
});
describe("managed plugin environments under managed-sandbox-only", () => {
const local = makeEnvironment({
id: "local-env",
driver: "local",
metadata: { managedByPaperclip: true, defaultForInstance: true },
});
// Listed first, so a lookup that only excluded `local` would pick it.
const pluginEnvironment = makeEnvironment({
id: "plugin-env",
name: "Remote Host",
driver: "plugin",
config: { pluginKey: "example.remote-host-plugin", driverKey: "tasks", driverConfig: {} },
metadata: {
managedByPaperclip: true,
managedPluginEnvironment: "example.remote-host-plugin:tasks",
},
});
const sandbox = makeEnvironment({
id: "sandbox-env",
name: "Paperclip Sandbox",
metadata: { managedByPaperclip: true, managedSandboxProvider: "daytona" },
});
const environments = [local, pluginEnvironment, sandbox];
const resolve = (agentDefaultEnvironmentId: string | null, instanceDefaultEnvironmentId: string | null) =>
resolveAdapterTestEnvironmentId({
agentDefaultEnvironmentId,
instanceDefaultEnvironmentId,
localDefaultEnvironmentId: resolveLocalDefaultEnvironmentId(environments),
managedSandboxOnly: true,
managedSandboxEnvironmentId: resolveManagedSandboxEnvironmentId(environments),
visibleEnvironmentIds: [pluginEnvironment.id, sandbox.id],
});
it("never mistakes the plugin row for the managed sandbox", () => {
expect(resolveManagedSandboxEnvironmentId(environments)).toBe("sandbox-env");
expect(resolveManagedSandboxEnvironmentId([local, pluginEnvironment])).toBeNull();
});
it("tests an agent without the plugin environment in the sandbox", () => {
expect(resolve("sandbox-env", "plugin-env")).toBe("sandbox-env");
// An instance that keeps local as its default: the redirect lands on the sandbox.
expect(resolve(null, null)).toBe("sandbox-env");
});
it("tests an agent on the plugin environment there", () => {
expect(resolve("plugin-env", null)).toBe("plugin-env");
expect(resolve(null, "plugin-env")).toBe("plugin-env");
});
});
describe("resolveLocalDefaultEnvironmentId", () => {
it("finds the local-driver instance-default environment", () => {
const environments = [
makeEnvironment({ id: "sandbox-1", driver: "sandbox" }),
makeEnvironment({
id: "local-1",
driver: "local",
metadata: { managedByPaperclip: true, defaultForInstance: true },
}),
];
expect(resolveLocalDefaultEnvironmentId(environments)).toBe("local-1");
});
it("ignores a local environment that is not the instance default", () => {
const environments = [
makeEnvironment({ id: "local-1", driver: "local", metadata: { defaultForInstance: false } }),
makeEnvironment({ id: "local-2", driver: "local", metadata: null }),
];
expect(resolveLocalDefaultEnvironmentId(environments)).toBeNull();
});
it("returns null for an empty or missing list", () => {
expect(resolveLocalDefaultEnvironmentId([])).toBeNull();
expect(resolveLocalDefaultEnvironmentId(null)).toBeNull();
expect(resolveLocalDefaultEnvironmentId(undefined)).toBeNull();
});
});