refactor(environments): make execution environments instance-scoped (#8375)
## Thinking Path > - Paperclip is the control plane for AI-agent companies, so execution environment selection has to stay inspectable and predictable across companies, agents, and runs. > - The environment subsystem decides where an agent heartbeat actually runs and how remote sandbox state is realized and restored. > - That subsystem previously mixed company-scoped environment catalogs with issue-level environment stamping, so a reassigned issue could keep executing in the previous assignee's sandbox. > - That behavior breaks the control-plane contract: changing the assignee should change the executing agent/environment path unless there is an explicit current override. > - Fixing it cleanly required more than a narrow patch; the environment model had to move to instance scope with a single inherited default and per-agent override semantics. > - This pull request rewires the schema, server/API surface, runtime resolution, and UI around that model, then adds regression coverage for cross-company inheritance and per-agent isolation. > - The benefit is that environment choice now follows the approved instance/agent configuration path instead of stale issue state, while shared environments only need to be configured once per instance. ## Linked Issues or Issue Description - No directly matching public GitHub issue or PR was found while searching for this refactor. ### What happened? Reassigning work between agents with different execution environments could keep running in the previous sandbox because environment choice was stamped onto the issue and outranked the current assignee. The same subsystem also forced environment catalogs to be duplicated per company even though the underlying execution environments were instance-wide resources. ### Expected behavior Execution should resolve through the current instance and agent configuration path, with one instance-scoped environment catalog, one instance default, optional per-agent override, and no stale issue-level environment authority surviving reassignment. ### Steps to reproduce 1. Configure two agents to use different execution environments. 2. Assign an issue to the first agent so the issue records execution state in that environment. 3. Reassign the same issue to the second agent and run another heartbeat. 4. Observe that the pre-fix runtime can still sync or execute in the original sandbox instead of the second agent's environment. ### Paperclip version or commit Current `master` before this PR. ### Deployment mode Self-hosted server. ### Installation method Built from source (`pnpm dev` / `pnpm build`). ### Agent adapter(s) involved - Claude Code - Not adapter-specific (core bug in environment authority / resolution) ### Database mode External Postgres. ### Access context Both board reassignment and agent heartbeats were involved. ## What Changed - Moved environments and their default selection contract to instance scope in DB/shared types, including the migration that dedupes legacy per-company environments and seeds the instance local default. - Reworked environment CRUD/auth flows to use instance-scoped APIs and added route/service coverage for instance-level environment management. - Changed runtime resolution to prefer `agent default -> instance default -> built-in local`, removed issue-level environment stamping from the active execution path, and isolated sandbox/plugin leases by `(executionWorkspaceId, agentId)`. - Added environment env-var runtime precedence so environment-provided values act as the baseline for agent execution. - Moved the environment UI into instance settings and updated agent configuration surfaces to reflect inherit/override behavior. - Added regression coverage for instance-default inheritance across companies and for the new runtime resolution behavior. - Fixed a rebase-only duplicate `enableTaskWatchdogs` flag regression in instance settings types/validators/services so the branch typechecks cleanly on current `master`. - Updated stale server tests so CI matches the shipped instance-scoped environment contract. ## Verification - `git diff --check` - `pnpm --filter @paperclipai/shared typecheck` - `pnpm --filter @paperclipai/db typecheck` - `pnpm exec vitest run server/src/__tests__/environment-runtime-driver-contract.test.ts server/src/__tests__/agent-permissions-routes.test.ts server/src/__tests__/environment-routes.test.ts server/src/__tests__/environment-instance-routes.test.ts server/src/__tests__/execution-workspace-policy.test.ts server/src/__tests__/heartbeat-plugin-environment.test.ts server/src/__tests__/instance-settings-routes.test.ts` ## Risks - The migration changes environment scope and dedupes existing rows, so installs with unusual legacy environment combinations should be reviewed carefully during upgrade. - Remote execution behavior now depends on instance-default inheritance semantics instead of issue-level stamping, so any remaining code paths that still assume issue-scoped environment authority would surface as follow-up bugs. - This PR includes both server/runtime behavior and UI relocation, so reviewers should watch for authorization edge cases around instance settings and environment management. > I checked [`ROADMAP.md`](ROADMAP.md). This work fits the existing Cloud / Sandbox agents direction as a bug-fix/refactor to current behavior, not a new parallel product surface. ## Model Used - OpenAI Codex coding agent in this Paperclip/Codex session; GPT-5-class tool-using model with code execution and shell access. The exact backend model ID is not exposed to the session runtime. ## 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 - [ ] If this change affects the UI, I have included before/after screenshots - [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
This commit is contained in:
Devin Foley
@@ -3,6 +3,7 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
|
||||
import {
|
||||
AGENT_ADAPTER_TYPES,
|
||||
getAdapterEnvironmentSupport,
|
||||
type EnvBinding,
|
||||
type Environment,
|
||||
type EnvironmentProbeResult,
|
||||
type JsonSchema,
|
||||
@@ -12,6 +13,7 @@ import { environmentsApi } from "@/api/environments";
|
||||
import { instanceSettingsApi } from "@/api/instanceSettings";
|
||||
import { secretsApi } from "@/api/secrets";
|
||||
import { Button } from "@/components/ui/button";
|
||||
import { EnvVarEditor } from "@/components/EnvVarEditor";
|
||||
import { JsonSchemaForm, getDefaultValues, validateJsonSchemaForm } from "@/components/JsonSchemaForm";
|
||||
import { useBreadcrumbs } from "@/context/BreadcrumbContext";
|
||||
import { useCompany } from "@/context/CompanyContext";
|
||||
@@ -37,6 +39,7 @@ type EnvironmentFormState = {
|
||||
sshStrictHostKeyChecking: boolean;
|
||||
sandboxProvider: string;
|
||||
sandboxConfig: Record<string, unknown>;
|
||||
envVars: Record<string, EnvBinding>;
|
||||
};
|
||||
|
||||
const ENVIRONMENT_SUPPORT_ROWS = AGENT_ADAPTER_TYPES.map((adapterType) => ({
|
||||
@@ -49,6 +52,7 @@ function buildEnvironmentPayload(form: EnvironmentFormState) {
|
||||
name: form.name.trim(),
|
||||
description: form.description.trim() || null,
|
||||
driver: form.driver,
|
||||
envVars: form.envVars,
|
||||
config:
|
||||
form.driver === "ssh"
|
||||
? {
|
||||
@@ -88,9 +92,23 @@ function createEmptyEnvironmentForm(): EnvironmentFormState {
|
||||
sshStrictHostKeyChecking: true,
|
||||
sandboxProvider: "",
|
||||
sandboxConfig: {},
|
||||
envVars: {},
|
||||
};
|
||||
}
|
||||
|
||||
function isLocalEnvironment(environment: Environment | null | undefined) {
|
||||
return environment?.driver === "local";
|
||||
}
|
||||
|
||||
function normalizeNonLocalEnvironmentId(
|
||||
environmentId: string | null | undefined,
|
||||
environments: readonly Environment[],
|
||||
): string {
|
||||
if (!environmentId) return "";
|
||||
const environment = environments.find((candidate) => candidate.id === environmentId) ?? null;
|
||||
return isLocalEnvironment(environment) ? "" : environmentId;
|
||||
}
|
||||
|
||||
function readSshConfig(environment: Environment) {
|
||||
const config = environment.config ?? {};
|
||||
return {
|
||||
@@ -159,7 +177,7 @@ function SupportMark({ supported }: { supported: boolean }) {
|
||||
}
|
||||
|
||||
export function CompanyEnvironments() {
|
||||
const { selectedCompany, selectedCompanyId } = useCompany();
|
||||
const { selectedCompanyId } = useCompany();
|
||||
const { setBreadcrumbs } = useBreadcrumbs();
|
||||
const { pushToast } = useToast();
|
||||
const queryClient = useQueryClient();
|
||||
@@ -170,11 +188,17 @@ export function CompanyEnvironments() {
|
||||
|
||||
useEffect(() => {
|
||||
setBreadcrumbs([
|
||||
{ label: selectedCompany?.name ?? "Company", href: "/dashboard" },
|
||||
{ label: "Settings", href: "/company/settings" },
|
||||
{ label: "Instance settings", href: "/company/settings/instance/general" },
|
||||
{ label: "Environments" },
|
||||
]);
|
||||
}, [selectedCompany?.name, setBreadcrumbs]);
|
||||
}, [setBreadcrumbs]);
|
||||
|
||||
const { data: instanceSettings } = useQuery({
|
||||
queryKey: queryKeys.instance.settings,
|
||||
queryFn: () => instanceSettingsApi.get(),
|
||||
retry: false,
|
||||
});
|
||||
|
||||
const { data: experimentalSettings } = useQuery({
|
||||
queryKey: queryKeys.instance.experimentalSettings,
|
||||
@@ -199,6 +223,16 @@ export function CompanyEnvironments() {
|
||||
queryFn: () => secretsApi.list(selectedCompanyId!),
|
||||
enabled: Boolean(selectedCompanyId),
|
||||
});
|
||||
const createSecret = useMutation({
|
||||
mutationFn: (input: { name: string; value: string }) => {
|
||||
if (!selectedCompanyId) throw new Error("Select a company to create secrets");
|
||||
return secretsApi.create(selectedCompanyId, input);
|
||||
},
|
||||
onSuccess: async () => {
|
||||
if (!selectedCompanyId) return;
|
||||
await queryClient.invalidateQueries({ queryKey: queryKeys.secrets.list(selectedCompanyId) });
|
||||
},
|
||||
});
|
||||
|
||||
const environmentMutation = useMutation({
|
||||
mutationFn: async (form: EnvironmentFormState) => {
|
||||
@@ -231,6 +265,26 @@ export function CompanyEnvironments() {
|
||||
},
|
||||
});
|
||||
|
||||
const defaultEnvironmentMutation = useMutation({
|
||||
mutationFn: async (defaultEnvironmentId: string | null) =>
|
||||
await instanceSettingsApi.update({ defaultEnvironmentId }),
|
||||
onSuccess: async () => {
|
||||
await queryClient.invalidateQueries({ queryKey: queryKeys.instance.settings });
|
||||
pushToast({
|
||||
title: "Default environment updated",
|
||||
body: "Agent inheritance now follows the updated instance default.",
|
||||
tone: "success",
|
||||
});
|
||||
},
|
||||
onError: (error) => {
|
||||
pushToast({
|
||||
title: "Failed to update default environment",
|
||||
body: error instanceof Error ? error.message : "Default environment update failed.",
|
||||
tone: "error",
|
||||
});
|
||||
},
|
||||
});
|
||||
|
||||
const environmentProbeMutation = useMutation({
|
||||
mutationFn: async (environmentId: string) => await environmentsApi.probe(environmentId),
|
||||
onMutate: (environmentId) => {
|
||||
@@ -314,6 +368,7 @@ export function CompanyEnvironments() {
|
||||
sshPrivateKeySecretId: ssh.privateKeySecretId,
|
||||
sshKnownHosts: ssh.knownHosts,
|
||||
sshStrictHostKeyChecking: ssh.strictHostKeyChecking,
|
||||
envVars: environment.envVars ?? {},
|
||||
});
|
||||
return;
|
||||
}
|
||||
@@ -327,6 +382,7 @@ export function CompanyEnvironments() {
|
||||
driver: "sandbox",
|
||||
sandboxProvider: sandbox.provider,
|
||||
sandboxConfig: sandbox.config,
|
||||
envVars: environment.envVars ?? {},
|
||||
});
|
||||
return;
|
||||
}
|
||||
@@ -336,6 +392,7 @@ export function CompanyEnvironments() {
|
||||
name: environment.name,
|
||||
description: environment.description ?? "",
|
||||
driver: "local",
|
||||
envVars: environment.envVars ?? {},
|
||||
});
|
||||
}
|
||||
|
||||
@@ -404,8 +461,17 @@ export function CompanyEnvironments() {
|
||||
environmentForm.sandboxProvider !== "fake" &&
|
||||
Object.keys(sandboxConfigErrors).length === 0);
|
||||
|
||||
const savedEnvironments = environments ?? [];
|
||||
const nonLocalEnvironments = savedEnvironments.filter((environment) => !isLocalEnvironment(environment));
|
||||
const instanceDefaultEnvironmentId = normalizeNonLocalEnvironmentId(
|
||||
instanceSettings?.defaultEnvironmentId ?? null,
|
||||
savedEnvironments,
|
||||
);
|
||||
const instanceDefaultEnvironment =
|
||||
nonLocalEnvironments.find((environment) => environment.id === instanceDefaultEnvironmentId) ?? null;
|
||||
|
||||
if (!selectedCompanyId) {
|
||||
return <div className="text-sm text-muted-foreground">Select a company to manage environments.</div>;
|
||||
return <div className="text-sm text-muted-foreground">Select a company context to manage environment secrets and bindings.</div>;
|
||||
}
|
||||
|
||||
if (!environmentsEnabled) {
|
||||
@@ -413,28 +479,59 @@ export function CompanyEnvironments() {
|
||||
<div className="max-w-3xl space-y-4">
|
||||
<div className="flex items-center gap-2">
|
||||
<Settings className="h-5 w-5 text-muted-foreground" />
|
||||
<h1 className="text-lg font-semibold">Company Environments</h1>
|
||||
<h1 className="text-lg font-semibold">Environments</h1>
|
||||
</div>
|
||||
<div className="rounded-md border border-border px-4 py-4 text-sm text-muted-foreground">
|
||||
Enable Environments in instance experimental settings to manage company execution targets.
|
||||
Enable Environments in instance experimental settings to manage shared execution targets.
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
return (
|
||||
<div className="max-w-5xl space-y-6" data-testid="company-settings-environments-section">
|
||||
<div className="max-w-5xl space-y-6" data-testid="instance-settings-environments-section">
|
||||
<div className="space-y-2">
|
||||
<div className="flex items-center gap-2">
|
||||
<Settings className="h-5 w-5 text-muted-foreground" />
|
||||
<h1 className="text-lg font-semibold">Company Environments</h1>
|
||||
<h1 className="text-lg font-semibold">Environments</h1>
|
||||
</div>
|
||||
<p className="max-w-3xl text-sm text-muted-foreground">
|
||||
Define reusable execution targets for projects, task workspaces, and remote-capable adapters.
|
||||
Define reusable execution targets for the instance. The built-in default is <span className="font-medium text-foreground">Local</span>; agents inherit that unless the instance default or an agent override points somewhere else.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div className="space-y-4 rounded-md border border-border px-4 py-4">
|
||||
<div className="rounded-md border border-border/60 bg-muted/20 px-3 py-3">
|
||||
<div className="flex flex-wrap items-start justify-between gap-3">
|
||||
<div className="space-y-1">
|
||||
<div className="text-sm font-medium">Instance default environment</div>
|
||||
<div className="text-xs text-muted-foreground">
|
||||
New agent configurations inherit this target unless they explicitly override it.
|
||||
</div>
|
||||
</div>
|
||||
<div className="min-w-[18rem] flex-1">
|
||||
<select
|
||||
className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"
|
||||
value={instanceDefaultEnvironmentId}
|
||||
onChange={(event) =>
|
||||
defaultEnvironmentMutation.mutate(event.target.value || null)}
|
||||
disabled={defaultEnvironmentMutation.isPending}
|
||||
>
|
||||
<option value="">Local (built-in default)</option>
|
||||
{nonLocalEnvironments.map((environment) => (
|
||||
<option key={environment.id} value={environment.id}>
|
||||
{environment.name} · {environment.driver}
|
||||
</option>
|
||||
))}
|
||||
</select>
|
||||
<div className="mt-1 text-[11px] text-muted-foreground">
|
||||
{instanceDefaultEnvironment
|
||||
? `Agents currently inherit ${instanceDefaultEnvironment.name} unless they override it.`
|
||||
: "Agents currently inherit the built-in Local environment unless they override it."}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div className="rounded-md border border-border/60 bg-muted/20 px-3 py-2 text-xs text-muted-foreground">
|
||||
Environment choices use the same adapter support matrix as agent defaults. SSH is always available for
|
||||
remote-managed adapters, and sandbox environments appear only when a run-capable sandbox provider plugin is
|
||||
@@ -493,10 +590,10 @@ export function CompanyEnvironments() {
|
||||
</div>
|
||||
|
||||
<div className="space-y-3">
|
||||
{(environments ?? []).length === 0 ? (
|
||||
<div className="text-sm text-muted-foreground">No environments saved for this company yet.</div>
|
||||
{savedEnvironments.length === 0 ? (
|
||||
<div className="text-sm text-muted-foreground">No saved environments yet. Local remains the default until you add another target.</div>
|
||||
) : (
|
||||
(environments ?? []).map((environment) => {
|
||||
savedEnvironments.map((environment) => {
|
||||
const probe = probeResults[environment.id] ?? null;
|
||||
const isEditing = editingEnvironmentId === environment.id;
|
||||
return (
|
||||
@@ -762,6 +859,19 @@ export function CompanyEnvironments() {
|
||||
</div>
|
||||
) : null}
|
||||
|
||||
<Field
|
||||
label="Environment variables"
|
||||
hint="Injected into runs that resolve through this environment. Use plain values or company secrets."
|
||||
>
|
||||
<EnvVarEditor
|
||||
value={environmentForm.envVars}
|
||||
secrets={secrets ?? []}
|
||||
onCreateSecret={async (name, value) => await createSecret.mutateAsync({ name, value })}
|
||||
onChange={(env) =>
|
||||
setEnvironmentForm((current) => ({ ...current, envVars: env ?? {} }))}
|
||||
/>
|
||||
</Field>
|
||||
|
||||
<div className="flex flex-wrap items-center gap-2">
|
||||
<Button
|
||||
size="sm"
|
||||
|
||||
@@ -161,13 +161,13 @@ describe("PluginSettings", () => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
it("routes environment-provider plugins to company environments when they have no instance config", async () => {
|
||||
it("routes environment-provider plugins to instance environments when they have no instance config", async () => {
|
||||
const root = await renderSettings(container);
|
||||
|
||||
expect(container.textContent).toContain("Configure this plugin from Company Environments.");
|
||||
expect(container.textContent).toContain("company-scoped instead of instance-global");
|
||||
const link = container.querySelector('a[href="/company/settings/environments"]');
|
||||
expect(link?.textContent).toContain("Open Company Environments");
|
||||
expect(container.textContent).toContain("Configure this plugin from Instance Settings → Environments.");
|
||||
expect(container.textContent).toContain("secret bindings still resolve through the selected company context");
|
||||
const link = container.querySelector('a[href="/company/settings/instance/environments"]');
|
||||
expect(link?.textContent).toContain("Open Environments");
|
||||
|
||||
await act(async () => {
|
||||
root.unmount();
|
||||
|
||||
@@ -254,14 +254,14 @@ export function PluginSettings() {
|
||||
/>
|
||||
) : environmentDrivers.length > 0 ? (
|
||||
<div className="rounded-md border border-border/60 bg-muted/20 px-4 py-3 text-sm">
|
||||
<p className="font-medium text-foreground">Configure this plugin from Company Environments.</p>
|
||||
<p className="font-medium text-foreground">Configure this plugin from Instance Settings → Environments.</p>
|
||||
<p className="mt-1 text-muted-foreground">
|
||||
{driverLabel || "This plugin"} registers environment runtime settings there so credentials stay
|
||||
company-scoped instead of instance-global.
|
||||
{driverLabel || "This plugin"} registers environment runtime settings there so the execution target
|
||||
stays instance-scoped while secret bindings still resolve through the selected company context.
|
||||
</p>
|
||||
<div className="mt-3">
|
||||
<Link to="/company/settings/environments">
|
||||
<Button variant="outline" size="sm">Open Company Environments</Button>
|
||||
<Link to="/company/settings/instance/environments">
|
||||
<Button variant="outline" size="sm">Open Environments</Button>
|
||||
</Link>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Reference in New Issue
Block a user