mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-16 10:50:38 +09:00
Generalize sandbox provider core for plugin-only providers (#4449)
## Thinking Path > - Paperclip is a control plane, so optional execution providers should sit at the plugin edge instead of hardcoding provider-specific behavior into core shared/server/ui layers. > - Sandbox environments are already first-class, and the fake provider proves the built-in path; the remaining gap was that real providers still leaked provider-specific config and runtime assumptions into core. > - That coupling showed up in config normalization, secret persistence, capabilities reporting, lease reconstruction, and the board UI form fields. > - As long as core knew about those provider-shaped details, shipping a provider as a pure third-party plugin meant every new provider would still require host changes. > - This pull request generalizes the sandbox provider seam around schema-driven plugin metadata and generic secret-ref handling. > - The runtime and UI now consume provider metadata generically, so core only special-cases the built-in fake provider while third-party providers can live entirely in plugins. ## What Changed - Added generic sandbox-provider capability metadata so plugin-backed providers can expose `configSchema` through shared environment support and the environments capabilities API. - Reworked sandbox config normalization/persistence/runtime resolution to handle schema-declared secret-ref fields generically, storing them as Paperclip secrets and resolving them for probe/execute/release flows. - Generalized plugin sandbox runtime handling so provider validation, reusable-lease matching, lease reconstruction, and plugin worker calls all operate on provider-agnostic config instead of provider-shaped branches. - Replaced hardcoded sandbox provider form fields in Company Settings with schema-driven rendering and blocked agent environment selection from the built-in fake provider. - Added regression coverage for the generic seam across shared support helpers plus environment config, probe, routes, runtime, and sandbox-provider runtime tests. ## Verification - `pnpm vitest --run packages/shared/src/environment-support.test.ts server/src/__tests__/environment-config.test.ts server/src/__tests__/environment-probe.test.ts server/src/__tests__/environment-routes.test.ts server/src/__tests__/environment-runtime.test.ts server/src/__tests__/sandbox-provider-runtime.test.ts` - `pnpm -r typecheck` ## Risks - Plugin sandbox providers now depend more heavily on accurate `configSchema` declarations; incorrect schemas can misclassify secret-bearing fields or omit required config. - Reusable lease matching is now metadata-driven for plugin-backed providers, so providers that fail to persist stable metadata may reprovision instead of resuming an existing lease. - The UI form is now fully schema-driven for plugin-backed sandbox providers; provider manifests without good defaults or descriptions may produce a rougher operator experience. ## Model Used - OpenAI Codex via `codex_local` - Model ID: `gpt-5.4` - Reasoning effort: `high` - Context window observed in runtime session metadata: `258400` tokens - Capabilities used: terminal tool execution, git, and local code/test inspection ## 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
GitHub
parent
deba60ebb2
commit
5bd0f578fd
18 changed files with 1235 additions and 236 deletions
|
|
@ -16,7 +16,11 @@ import type {
|
|||
} from "@paperclipai/plugin-sdk";
|
||||
import { ensureSshWorkspaceReady, findReachablePaperclipApiUrlOverSsh } from "@paperclipai/adapter-utils/ssh";
|
||||
import { environmentService } from "./environments.js";
|
||||
import { parseEnvironmentDriverConfig, resolveEnvironmentDriverConfigForRuntime } from "./environment-config.js";
|
||||
import {
|
||||
parseEnvironmentDriverConfig,
|
||||
resolveEnvironmentDriverConfigForRuntime,
|
||||
stripSandboxProviderEnvelope,
|
||||
} from "./environment-config.js";
|
||||
import {
|
||||
acquireSandboxProviderLease,
|
||||
findReusableSandboxProviderLeaseId,
|
||||
|
|
@ -31,8 +35,10 @@ import {
|
|||
destroyPluginEnvironmentLease,
|
||||
executePluginEnvironmentCommand,
|
||||
realizePluginEnvironmentWorkspace,
|
||||
resolvePluginSandboxProviderDriverByKey,
|
||||
resumePluginEnvironmentLease,
|
||||
} from "./plugin-environment-driver.js";
|
||||
import { collectSecretRefPaths } from "./json-schema-secret-refs.js";
|
||||
import { buildWorkspaceRealizationRecordFromDriverInput } from "./workspace-realization.js";
|
||||
|
||||
export function buildEnvironmentLeaseContext(input: {
|
||||
|
|
@ -44,6 +50,53 @@ export function buildEnvironmentLeaseContext(input: {
|
|||
};
|
||||
}
|
||||
|
||||
function stripSecretRefValuesFromPluginLeaseMetadata(input: {
|
||||
metadata: Record<string, unknown> | null | undefined;
|
||||
schema: Record<string, unknown> | null | undefined;
|
||||
}): Record<string, unknown> {
|
||||
const sanitized = structuredClone(input.metadata ?? {}) as Record<string, unknown>;
|
||||
|
||||
for (const path of collectSecretRefPaths(input.schema)) {
|
||||
const keys = path.split(".");
|
||||
const parents: Array<{ container: Record<string, unknown>; key: string }> = [];
|
||||
let cursor: Record<string, unknown> | null = sanitized;
|
||||
|
||||
for (let index = 0; index < keys.length - 1; index += 1) {
|
||||
const key = keys[index]!;
|
||||
const next = cursor?.[key];
|
||||
if (!next || typeof next !== "object" || Array.isArray(next)) {
|
||||
cursor = null;
|
||||
break;
|
||||
}
|
||||
parents.push({ container: cursor, key });
|
||||
cursor = next as Record<string, unknown>;
|
||||
}
|
||||
|
||||
if (!cursor) continue;
|
||||
|
||||
const leafKey = keys[keys.length - 1]!;
|
||||
if (!Object.prototype.hasOwnProperty.call(cursor, leafKey)) continue;
|
||||
delete cursor[leafKey];
|
||||
|
||||
for (let index = parents.length - 1; index >= 0; index -= 1) {
|
||||
const { container, key } = parents[index]!;
|
||||
const value = container[key];
|
||||
if (
|
||||
value &&
|
||||
typeof value === "object" &&
|
||||
!Array.isArray(value) &&
|
||||
Object.keys(value as Record<string, unknown>).length === 0
|
||||
) {
|
||||
delete container[key];
|
||||
} else {
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return sanitized;
|
||||
}
|
||||
|
||||
export interface EnvironmentDriverAcquireInput {
|
||||
companyId: string;
|
||||
environment: Environment;
|
||||
|
|
@ -238,33 +291,6 @@ function createSandboxEnvironmentDriver(
|
|||
pluginWorkerManager?: PluginWorkerManager,
|
||||
): EnvironmentRuntimeDriver {
|
||||
const environmentsSvc = environmentService(db);
|
||||
const pluginRegistry = pluginRegistryService(db);
|
||||
|
||||
/**
|
||||
* Resolve a sandbox provider plugin by looking up a plugin whose manifest
|
||||
* declares an environment driver with a matching driverKey. Returns null
|
||||
* if no matching plugin is found or the worker isn't running.
|
||||
*/
|
||||
async function resolvePluginForProvider(
|
||||
provider: string,
|
||||
): Promise<{ pluginId: string; pluginKey: string } | null> {
|
||||
if (!pluginWorkerManager) return null;
|
||||
const plugins = await pluginRegistry.list();
|
||||
for (const plugin of plugins) {
|
||||
if (plugin.status !== "ready") continue;
|
||||
const drivers = plugin.manifestJson.environmentDrivers ?? [];
|
||||
for (const driver of drivers) {
|
||||
if (
|
||||
driver.driverKey === provider &&
|
||||
driver.kind === "sandbox_provider" &&
|
||||
pluginWorkerManager.isRunning(plugin.id)
|
||||
) {
|
||||
return { pluginId: plugin.id, pluginKey: plugin.pluginKey };
|
||||
}
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
async function resolvePluginSandboxRuntimeConfig(input: {
|
||||
environment: Environment;
|
||||
|
|
@ -308,29 +334,64 @@ function createSandboxEnvironmentDriver(
|
|||
driver: "sandbox",
|
||||
|
||||
async acquireRunLease(input) {
|
||||
const storedParsed = parseEnvironmentDriverConfig(input.environment);
|
||||
const parsed = await resolveEnvironmentDriverConfigForRuntime(db, input.companyId, input.environment);
|
||||
if (parsed.driver !== "sandbox") {
|
||||
if (parsed.driver !== "sandbox" || storedParsed.driver !== "sandbox") {
|
||||
throw new Error(`Expected sandbox environment config for driver "${input.environment.driver}".`);
|
||||
}
|
||||
|
||||
// Check if this provider should be handled by a plugin.
|
||||
if (!isBuiltinSandboxProvider(parsed.config.provider)) {
|
||||
const pluginProvider = await resolvePluginForProvider(parsed.config.provider);
|
||||
const pluginProvider = await resolvePluginSandboxProviderDriverByKey({
|
||||
db,
|
||||
driverKey: parsed.config.provider,
|
||||
workerManager: pluginWorkerManager,
|
||||
requireRunning: true,
|
||||
});
|
||||
if (!pluginProvider || !pluginWorkerManager) {
|
||||
throw new Error(
|
||||
`Sandbox provider "${parsed.config.provider}" is not registered as a built-in provider and no matching plugin is available.`,
|
||||
);
|
||||
}
|
||||
|
||||
// Delegate to the plugin worker for lease acquisition.
|
||||
const providerLease = await pluginWorkerManager.call(
|
||||
pluginProvider.pluginId,
|
||||
const workerConfig = stripSandboxProviderEnvelope(parsed.config);
|
||||
const storedConfig = storedParsed.config;
|
||||
const existingLeases = parsed.config.reuseLease
|
||||
? await environmentsSvc.listLeases(input.environment.id)
|
||||
: [];
|
||||
const reusableProviderLeaseId = parsed.config.reuseLease
|
||||
? findReusableSandboxLeaseId({ config: storedConfig, leases: existingLeases })
|
||||
: null;
|
||||
const reusableLease = reusableProviderLeaseId
|
||||
? existingLeases.find((lease) => lease.providerLeaseId === reusableProviderLeaseId)
|
||||
: null;
|
||||
|
||||
const providerLease = reusableLease?.providerLeaseId
|
||||
? await pluginWorkerManager.call(
|
||||
pluginProvider.plugin.id,
|
||||
"environmentResumeLease",
|
||||
{
|
||||
driverKey: parsed.config.provider,
|
||||
companyId: input.companyId,
|
||||
environmentId: input.environment.id,
|
||||
config: workerConfig,
|
||||
providerLeaseId: reusableLease.providerLeaseId,
|
||||
leaseMetadata: reusableLease.metadata ?? undefined,
|
||||
},
|
||||
).then((resumed) =>
|
||||
typeof resumed.providerLeaseId === "string" && resumed.providerLeaseId.length > 0
|
||||
? resumed
|
||||
: null,
|
||||
).catch(() => null)
|
||||
: null;
|
||||
const acquiredLease = providerLease ?? await pluginWorkerManager.call(
|
||||
pluginProvider.plugin.id,
|
||||
"environmentAcquireLease",
|
||||
{
|
||||
driverKey: parsed.config.provider,
|
||||
companyId: input.companyId,
|
||||
environmentId: input.environment.id,
|
||||
config: parsed.config as unknown as Record<string, unknown>,
|
||||
config: workerConfig,
|
||||
runId: input.heartbeatRunId,
|
||||
workspaceMode: input.executionWorkspaceMode ?? undefined,
|
||||
},
|
||||
|
|
@ -348,16 +409,19 @@ function createSandboxEnvironmentDriver(
|
|||
heartbeatRunId: input.heartbeatRunId,
|
||||
leasePolicy: resolvedLeasePolicy,
|
||||
provider: parsed.config.provider,
|
||||
providerLeaseId: providerLease.providerLeaseId,
|
||||
expiresAt: providerLease.expiresAt ? new Date(providerLease.expiresAt) : undefined,
|
||||
providerLeaseId: acquiredLease.providerLeaseId,
|
||||
expiresAt: acquiredLease.expiresAt ? new Date(acquiredLease.expiresAt) : undefined,
|
||||
metadata: {
|
||||
driver: input.environment.driver,
|
||||
executionWorkspaceMode: input.executionWorkspaceMode,
|
||||
pluginId: pluginProvider.pluginId,
|
||||
pluginKey: pluginProvider.pluginKey,
|
||||
pluginId: pluginProvider.plugin.id,
|
||||
pluginKey: pluginProvider.plugin.pluginKey,
|
||||
sandboxProviderPlugin: true,
|
||||
...sandboxConfigForLeaseMetadata(parsed.config),
|
||||
...(providerLease.metadata ?? {}),
|
||||
...sandboxConfigForLeaseMetadata(storedConfig),
|
||||
...stripSecretRefValuesFromPluginLeaseMetadata({
|
||||
metadata: acquiredLease.metadata,
|
||||
schema: pluginProvider.driver.configSchema as Record<string, unknown> | null | undefined,
|
||||
}),
|
||||
},
|
||||
});
|
||||
}
|
||||
|
|
@ -462,7 +526,7 @@ function createSandboxEnvironmentDriver(
|
|||
driverKey: providerKey,
|
||||
companyId: input.lease.companyId,
|
||||
environmentId: input.environment.id,
|
||||
config,
|
||||
config: stripSandboxProviderEnvelope(config as SandboxEnvironmentConfig),
|
||||
lease: {
|
||||
providerLeaseId: input.lease.providerLeaseId,
|
||||
metadata: input.lease.metadata ?? undefined,
|
||||
|
|
@ -505,7 +569,7 @@ function createSandboxEnvironmentDriver(
|
|||
driverKey: providerKey,
|
||||
companyId: input.lease.companyId,
|
||||
environmentId: input.environment.id,
|
||||
config,
|
||||
config: stripSandboxProviderEnvelope(config as SandboxEnvironmentConfig),
|
||||
lease: {
|
||||
providerLeaseId: input.lease.providerLeaseId,
|
||||
metadata: input.lease.metadata ?? undefined,
|
||||
|
|
@ -543,7 +607,7 @@ function createSandboxEnvironmentDriver(
|
|||
driverKey: providerKey,
|
||||
companyId: input.lease.companyId,
|
||||
environmentId: input.environment.id,
|
||||
config,
|
||||
config: stripSandboxProviderEnvelope(config as SandboxEnvironmentConfig),
|
||||
providerLeaseId: input.lease.providerLeaseId,
|
||||
leaseMetadata: metadata,
|
||||
});
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue