mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 12:44:56 +01:00
## 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>
355 lines
13 KiB
TypeScript
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();
|
|
});
|
|
});
|