Add sandbox environment support (#4415)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - The environment/runtime layer decides where agent work executes and
how the control plane reaches those runtimes.
> - Today Paperclip can run locally and over SSH, but sandboxed
execution needs a first-class environment model instead of one-off
adapter behavior.
> - We also want sandbox providers to be pluggable so the core does not
hardcode every provider implementation.
> - This branch adds the Sandbox environment path, the provider
contract, and a deterministic fake provider plugin.
> - That required synchronized changes across shared contracts, plugin
SDK surfaces, server runtime orchestration, and the UI
environment/workspace flows.
> - The result is that sandbox execution becomes a core control-plane
capability while keeping provider implementations extensible and
testable.

## What Changed

- Added sandbox runtime support to the environment execution path,
including runtime URL discovery, sandbox execution targeting,
orchestration, and heartbeat integration.
- Added plugin-provider support for sandbox environments so providers
can be supplied via plugins instead of hardcoded server logic.
- Added the fake sandbox provider plugin with deterministic behavior
suitable for local and automated testing.
- Updated shared types, validators, plugin protocol definitions, and SDK
helpers to carry sandbox provider and workspace-runtime contracts across
package boundaries.
- Updated server routes and services so companies can create sandbox
environments, select them for work, and execute work through the sandbox
runtime path.
- Updated the UI environment and workspace surfaces to expose sandbox
environment configuration and selection.
- Added test coverage for sandbox runtime behavior, provider seams,
environment route guards, orchestration, and the fake provider plugin.

## Verification

- Ran locally before the final fixture-only scrub:
  - `pnpm -r typecheck`
  - `pnpm test:run`
  - `pnpm build`
- Ran locally after the final scrub amend:
  - `pnpm vitest run server/src/__tests__/runtime-api.test.ts`
- Reviewer spot checks:
  - create a sandbox environment backed by the fake provider plugin
  - run work through that environment
- confirm sandbox provider execution does not inherit host secrets
implicitly

## Risks

- This touches shared contracts, plugin SDK plumbing, server runtime
orchestration, and UI environment/workspace flows, so regressions would
likely show up as cross-layer mismatches rather than isolated type
errors.
- Runtime URL discovery and sandbox callback selection are sensitive to
host/bind configuration; if that logic is wrong, sandbox-backed
callbacks may fail even when execution succeeds.
- The fake provider plugin is intentionally deterministic and
test-oriented; future providers may expose capability gaps that this
branch does not yet cover.

## Model Used

- OpenAI Codex coding agent on a GPT-5-class backend in the
Paperclip/Codex harness. Exact backend model ID is not exposed
in-session. Tool-assisted workflow with shell execution, file editing,
git history inspection, and local test 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 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
- [x] I will address all Greptile and reviewer comments before
requesting merge
This commit is contained in:
Devin Foley 2026-04-24 12:15:53 -07:00 committed by GitHub
parent 641eb44949
commit 70679a3321
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
91 changed files with 10469 additions and 1498 deletions

View file

@ -38,13 +38,11 @@ import {
approvalService,
companySkillService,
budgetService,
environmentService,
heartbeatService,
ISSUE_LIST_DEFAULT_LIMIT,
issueApprovalService,
issueService,
logActivity,
secretService,
syncInstructionsBundleConfigFromFilePath,
workspaceOperationService,
} from "../services/index.js";
@ -54,6 +52,9 @@ import {
assertNoAgentHostWorkspaceCommandMutation,
collectAgentAdapterWorkspaceCommandPaths,
} from "./workspace-command-authz.js";
import type { PluginWorkerManager } from "../services/plugin-worker-manager.js";
import { environmentService } from "../services/environments.js";
import { secretService } from "../services/secrets.js";
import {
detectAdapterModel,
findActiveServerAdapter,
@ -90,7 +91,10 @@ function readRunLogLimitBytes(value: unknown) {
return Math.max(1, Math.min(RUN_LOG_MAX_LIMIT_BYTES, Math.trunc(parsed)));
}
export function agentRoutes(db: Db) {
export function agentRoutes(
db: Db,
options: { pluginWorkerManager?: PluginWorkerManager } = {},
) {
// Legacy hardcoded maps — used as fallback when adapter module does not
// declare capability flags explicitly.
const DEFAULT_INSTRUCTIONS_PATH_KEYS: Record<string, string> = {
@ -134,7 +138,10 @@ export function agentRoutes(db: Db) {
const access = accessService(db);
const approvalsSvc = approvalService(db);
const budgets = budgetService(db);
const heartbeat = heartbeatService(db);
const environmentsSvc = environmentService(db);
const heartbeat = heartbeatService(db, {
pluginWorkerManager: options.pluginWorkerManager,
});
const issueApprovalsSvc = issueApprovalService(db);
const secretsSvc = secretService(db);
const instructions = agentInstructionsService();
@ -418,6 +425,37 @@ export function agentRoutes(db: Db) {
return adapterType;
}
async function assertAgentDefaultEnvironmentSelection(
companyId: string,
environmentId: string | null | undefined,
options?: { allowedDrivers?: string[]; allowedSandboxProviders?: string[] },
) {
if (environmentId === undefined || environmentId === null) return;
const environment = await environmentsSvc.getById(environmentId);
if (!environment || environment.companyId !== companyId) {
throw unprocessable("Selected environment must belong to the same company");
}
if (options?.allowedDrivers && !options.allowedDrivers.includes(environment.driver)) {
throw unprocessable(`Environment driver "${environment.driver}" is not allowed here`);
}
if (environment.driver === "sandbox" && options?.allowedSandboxProviders) {
const config = environment.config && typeof environment.config === "object"
? environment.config as Record<string, unknown>
: {};
const provider = typeof config.provider === "string" ? config.provider : "";
if (provider === "fake") {
throw unprocessable(
`Selected sandbox provider "${provider}" is not supported for agent defaults yet`,
);
}
if (options.allowedSandboxProviders.length > 0 && !options.allowedSandboxProviders.includes(provider)) {
throw unprocessable(
`Selected sandbox provider "${provider || "unknown"}" is not supported for agent defaults yet`,
);
}
}
}
function hasOwn(value: object, key: string): boolean {
return Object.hasOwn(value, key);
}
@ -426,6 +464,10 @@ export function agentRoutes(db: Db) {
return supportedEnvironmentDriversForAdapter(adapterType);
}
function allowedSandboxProvidersForAgent(adapterType: string): string[] | undefined {
return supportedEnvironmentDriversForAdapter(adapterType).includes("sandbox") ? [] : [];
}
async function resolveCompanyIdForAgentReference(req: Request): Promise<string | null> {
const companyIdQuery = req.query.companyId;
const requestedCompanyId =
@ -1634,6 +1676,10 @@ export function agentRoutes(db: Db) {
normalizedAdapterConfig,
);
await assertAgentEnvironmentSelection(companyId, createInput.adapterType, createInput.defaultEnvironmentId);
await assertAgentDefaultEnvironmentSelection(companyId, createInput.defaultEnvironmentId, {
allowedDrivers: allowedEnvironmentDriversForAgent(createInput.adapterType),
allowedSandboxProviders: allowedSandboxProvidersForAgent(createInput.adapterType),
});
const createdAgent = await svc.create(companyId, {
...createInput,
@ -2091,12 +2137,15 @@ export function agentRoutes(db: Db) {
);
}
if (touchesAdapterConfiguration || Object.prototype.hasOwnProperty.call(patchData, "defaultEnvironmentId")) {
await assertAgentEnvironmentSelection(
await assertAgentDefaultEnvironmentSelection(
existing.companyId,
requestedAdapterType,
Object.prototype.hasOwnProperty.call(patchData, "defaultEnvironmentId")
? (typeof patchData.defaultEnvironmentId === "string" ? patchData.defaultEnvironmentId : null)
: existing.defaultEnvironmentId,
{
allowedDrivers: allowedEnvironmentDriversForAgent(requestedAdapterType),
allowedSandboxProviders: allowedSandboxProvidersForAgent(requestedAdapterType),
},
);
}

View file

@ -18,6 +18,7 @@ import {
} from "../services/index.js";
import { assertBoard, assertCompanyAccess, getActorInfo } from "./authz.js";
import { redactEventPayload } from "../redaction.js";
import type { PluginWorkerManager } from "../services/plugin-worker-manager.js";
function redactApprovalPayload<T extends { payload: Record<string, unknown> }>(approval: T): T {
return {
@ -26,10 +27,15 @@ function redactApprovalPayload<T extends { payload: Record<string, unknown> }>(a
};
}
export function approvalRoutes(db: Db) {
export function approvalRoutes(
db: Db,
options: { pluginWorkerManager?: PluginWorkerManager } = {},
) {
const router = Router();
const svc = approvalService(db);
const heartbeat = heartbeatService(db);
const heartbeat = heartbeatService(db, {
pluginWorkerManager: options.pluginWorkerManager,
});
const issueApprovalsSvc = issueApprovalService(db);
const secretsSvc = secretService(db);
const strictSecretsMode = process.env.PAPERCLIP_SECRETS_STRICT_MODE === "true";

View file

@ -20,6 +20,7 @@ import {
import { assertBoard, assertCompanyAccess, getActorInfo } from "./authz.js";
import { fetchAllQuotaWindows } from "../services/quota-windows.js";
import { badRequest } from "../errors.js";
import type { PluginWorkerManager } from "../services/plugin-worker-manager.js";
export function parseCostDateRange(query: Record<string, unknown>) {
const fromRaw = query.from as string | undefined;
@ -41,9 +42,14 @@ export function parseCostLimit(query: Record<string, unknown>) {
return limit;
}
export function costRoutes(db: Db) {
export function costRoutes(
db: Db,
options: { pluginWorkerManager?: PluginWorkerManager } = {},
) {
const router = Router();
const heartbeat = heartbeatService(db);
const heartbeat = heartbeatService(db, {
pluginWorkerManager: options.pluginWorkerManager,
});
const budgetHooks = {
cancelWorkForScope: heartbeat.cancelBudgetScopeWork,
};

View file

@ -14,6 +14,7 @@ export async function assertEnvironmentSelectionForCompany(
environmentId: string | null | undefined,
options?: {
allowedDrivers?: string[];
allowedSandboxProviders?: string[];
},
) {
if (environmentId === undefined || environmentId === null) return;
@ -29,4 +30,24 @@ export async function assertEnvironmentSelectionForCompany(
`Environment driver "${environment.driver}" is not allowed here. Allowed drivers: ${options.allowedDrivers.join(", ")}`,
);
}
if (environment.driver === "sandbox") {
const config = environment.config && typeof environment.config === "object"
? environment.config as Record<string, unknown>
: {};
const provider = typeof config.provider === "string" ? config.provider : "";
if (provider === "fake") {
throw unprocessable(
`Environment sandbox provider "${provider}" is not allowed here. The built-in fake provider is probe-only and cannot execute runs.`,
);
}
if (
options?.allowedSandboxProviders
&& options.allowedSandboxProviders.length > 0
&& !options.allowedSandboxProviders.includes(provider)
) {
throw unprocessable(
`Environment sandbox provider "${provider || "unknown"}" is not allowed here. Allowed providers: ${options.allowedSandboxProviders.join(", ")}`,
);
}
}
}

View file

@ -12,8 +12,6 @@ import { validate } from "../middleware/validate.js";
import {
accessService,
agentService,
environmentService,
executionWorkspaceService,
issueService,
logActivity,
projectService,
@ -27,9 +25,16 @@ import {
} from "../services/environment-config.js";
import { probeEnvironment } from "../services/environment-probe.js";
import { secretService } from "../services/secrets.js";
import { listReadyPluginEnvironmentDrivers } from "../services/plugin-environment-driver.js";
import { assertCompanyAccess, getActorInfo } from "./authz.js";
import type { PluginWorkerManager } from "../services/plugin-worker-manager.js";
import { environmentService } from "../services/environments.js";
import { executionWorkspaceService } from "../services/execution-workspaces.js";
export function environmentRoutes(db: Db) {
export function environmentRoutes(
db: Db,
options: { pluginWorkerManager?: PluginWorkerManager } = {},
) {
const router = Router();
const agents = agentService(db);
const access = accessService(db);
@ -159,7 +164,30 @@ export function environmentRoutes(db: Db) {
router.get("/companies/:companyId/environments/capabilities", async (req, res) => {
const companyId = req.params.companyId as string;
assertCompanyAccess(req, companyId);
res.json(getEnvironmentCapabilities(AGENT_ADAPTER_TYPES));
const pluginDrivers = await listReadyPluginEnvironmentDrivers({
db,
workerManager: options.pluginWorkerManager,
});
res.json(getEnvironmentCapabilities(
AGENT_ADAPTER_TYPES,
{
sandboxProviders: Object.fromEntries(pluginDrivers.map((driver) => [
driver.driverKey,
{
status: "supported" as const,
supportsSavedProbe: true,
supportsUnsavedProbe: true,
supportsRunExecution: true,
supportsReusableLeases: true,
displayName: driver.displayName,
description: driver.description,
source: "plugin" as const,
pluginKey: driver.pluginKey,
pluginId: driver.pluginId,
},
])),
},
));
});
router.post("/companies/:companyId/environments", validate(createEnvironmentSchema), async (req, res) => {
@ -178,6 +206,7 @@ export function environmentRoutes(db: Db) {
agentId: actor.agentId,
userId: actor.actorType === "user" ? actor.actorId : null,
},
pluginWorkerManager: options.pluginWorkerManager,
}),
};
const environment = await svc.create(companyId, input);
@ -280,6 +309,7 @@ export function environmentRoutes(db: Db) {
agentId: actor.agentId,
userId: actor.actorType === "user" ? actor.actorId : null,
},
pluginWorkerManager: options.pluginWorkerManager,
}),
}
: {}),
@ -351,7 +381,9 @@ export function environmentRoutes(db: Db) {
}
await assertCanMutateEnvironments(req, environment.companyId);
const actor = getActorInfo(req);
const probe = await probeEnvironment(db, environment);
const probe = await probeEnvironment(db, environment, {
pluginWorkerManager: options.pluginWorkerManager,
});
await logActivity(db, {
companyId: environment.companyId,
actorType: actor.actorType,
@ -394,6 +426,7 @@ export function environmentRoutes(db: Db) {
updatedAt: new Date(),
};
const probe = await probeEnvironment(db, environment, {
pluginWorkerManager: options.pluginWorkerManager,
resolvedConfig: {
driver: req.body.driver,
config: normalizedConfig,

View file

@ -39,10 +39,8 @@ import {
accessService,
agentService,
executionWorkspaceService,
feedbackService,
goalService,
heartbeatService,
instanceSettingsService,
issueApprovalService,
issueThreadInteractionService,
ISSUE_LIST_DEFAULT_LIMIT,
@ -55,7 +53,6 @@ import {
projectService,
routineService,
workProductService,
environmentService,
} from "../services/index.js";
import { logger } from "../middleware/logger.js";
import { conflict, forbidden, HttpError, notFound, unauthorized } from "../errors.js";
@ -73,11 +70,16 @@ import {
} from "../attachment-types.js";
import { queueIssueAssignmentWakeup } from "../services/issue-assignment-wakeup.js";
import { assertEnvironmentSelectionForCompany } from "./environment-selection.js";
import { executionWorkspaceService as executionWorkspaceServiceDirect } from "../services/execution-workspaces.js";
import { feedbackService } from "../services/feedback.js";
import { instanceSettingsService } from "../services/instance-settings.js";
import { environmentService } from "../services/environments.js";
import {
applyIssueExecutionPolicyTransition,
normalizeIssueExecutionPolicy,
parseIssueExecutionState,
} from "../services/issue-execution-policy.js";
import type { PluginWorkerManager } from "../services/plugin-worker-manager.js";
const MAX_ISSUE_COMMENT_LIMIT = 500;
const updateIssueRouteSchema = updateIssueSchema.extend({
@ -376,7 +378,7 @@ function buildExecutionStageWakeup(input: {
export function issueRoutes(
db: Db,
storage: StorageService,
opts?: {
opts: {
feedbackExportService?: {
flushPendingFeedbackTraces(input?: {
companyId?: string;
@ -385,24 +387,30 @@ export function issueRoutes(
now?: Date;
}): Promise<unknown>;
};
},
pluginWorkerManager?: PluginWorkerManager;
} = {},
) {
const router = Router();
const svc = issueService(db);
const access = accessService(db);
const heartbeat = heartbeatService(db);
const heartbeat = heartbeatService(db, {
pluginWorkerManager: opts.pluginWorkerManager,
});
const feedback = feedbackService(db);
const instanceSettings = instanceSettingsService(db);
const agentsSvc = agentService(db);
const projectsSvc = projectService(db);
const goalsSvc = goalService(db);
const issueApprovalsSvc = issueApprovalService(db);
const executionWorkspacesSvc = executionWorkspaceService(db);
const executionWorkspacesSvc = executionWorkspaceServiceDirect(db);
const workProductsSvc = workProductService(db);
const documentsSvc = documentService(db);
const issueReferencesSvc = issueReferenceService(db);
const routinesSvc = routineService(db);
const routinesSvc = routineService(db, {
pluginWorkerManager: opts.pluginWorkerManager,
});
const feedbackExportService = opts?.feedbackExportService;
const environmentsSvc = environmentService(db);
const upload = multer({
storage: multer.memoryStorage(),
limits: { fileSize: MAX_ATTACHMENT_BYTES, files: 1 },
@ -425,10 +433,10 @@ export function issueRoutes(
) {
if (environmentId === undefined || environmentId === null) return;
await assertEnvironmentSelectionForCompany(
environmentService(db),
environmentsSvc,
companyId,
environmentId,
{ allowedDrivers: ["local", "ssh"] },
{ allowedDrivers: ["local", "ssh", "sandbox"] },
);
}

View file

@ -13,7 +13,7 @@ import {
import type { WorkspaceRuntimeDesiredState, WorkspaceRuntimeServiceStateMap } from "@paperclipai/shared";
import { trackProjectCreated } from "@paperclipai/shared/telemetry";
import { validate } from "../middleware/validate.js";
import { environmentService, projectService, logActivity, secretService, workspaceOperationService } from "../services/index.js";
import { projectService, logActivity, workspaceOperationService } from "../services/index.js";
import { conflict } from "../errors.js";
import { assertCompanyAccess, getActorInfo } from "./authz.js";
import {
@ -32,6 +32,8 @@ import { assertCanManageProjectWorkspaceRuntimeServices } from "./workspace-runt
import { getTelemetryClient } from "../telemetry.js";
import { appendWithCap } from "../adapters/utils.js";
import { assertEnvironmentSelectionForCompany } from "./environment-selection.js";
import { environmentService } from "../services/environments.js";
import { secretService } from "../services/secrets.js";
const WORKSPACE_CONTROL_OUTPUT_MAX_CHARS = 256 * 1024;
@ -46,7 +48,7 @@ export function projectRoutes(db: Db) {
async function assertProjectEnvironmentSelection(companyId: string, environmentId: string | null | undefined) {
if (environmentId === undefined || environmentId === null) return;
await assertEnvironmentSelectionForCompany(environmentsSvc, companyId, environmentId, {
allowedDrivers: ["local", "ssh"],
allowedDrivers: ["local", "ssh", "sandbox"],
});
}

View file

@ -14,10 +14,16 @@ import { accessService, logActivity, routineService } from "../services/index.js
import { assertCompanyAccess, getActorInfo } from "./authz.js";
import { forbidden, unauthorized } from "../errors.js";
import { getTelemetryClient } from "../telemetry.js";
import type { PluginWorkerManager } from "../services/plugin-worker-manager.js";
export function routineRoutes(db: Db) {
export function routineRoutes(
db: Db,
options: { pluginWorkerManager?: PluginWorkerManager } = {},
) {
const router = Router();
const svc = routineService(db);
const svc = routineService(db, {
pluginWorkerManager: options.pluginWorkerManager,
});
const access = accessService(db);
async function assertBoardCanAssignTasks(req: Request, companyId: string) {