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

server/src/services/plugin-environment-driver.ts

@@ -1,5 +1,9 @@
 import type { Db } from "@paperclipai/db";
-import type { EnvironmentProbeResult, PluginEnvironmentConfig } from "@paperclipai/shared";
+import type {
+  EnvironmentProbeResult,
+  PluginEnvironmentConfig,
+  PluginEnvironmentDriverDeclaration,
+} from "@paperclipai/shared";
 import type {
   PluginEnvironmentExecuteParams,
   PluginEnvironmentExecuteResult,
@@ -42,15 +46,31 @@ export async function resolvePluginEnvironmentDriverByKey(input: {
   workerManager: PluginWorkerManager;
   driverKey: string;
 }) {
+  return await resolvePluginSandboxProviderDriverByKey({
+    db: input.db,
+    driverKey: input.driverKey,
+    workerManager: input.workerManager,
+    requireRunning: true,
+  });
+}
+
+export async function resolvePluginSandboxProviderDriverByKey(input: {
+  db: Db;
+  driverKey: string;
+  workerManager?: PluginWorkerManager;
+  requireRunning?: boolean;
+}): Promise<{ plugin: Awaited<ReturnType<ReturnType<typeof pluginRegistryService>["list"]>>[number]; driver: PluginEnvironmentDriverDeclaration } | null> {
   const pluginRegistry = pluginRegistryService(input.db);
   const plugins = await pluginRegistry.list();
   for (const plugin of plugins) {
-    if (plugin.status !== "ready") continue;
     const driver = plugin.manifestJson.environmentDrivers?.find(
       (candidate) => candidate.driverKey === input.driverKey && candidate.kind === "sandbox_provider",
-    );
+    ) as PluginEnvironmentDriverDeclaration | undefined;
     if (!driver) continue;
-    if (!input.workerManager.isRunning(plugin.id)) continue;
+    if (input.requireRunning) {
+      if (plugin.status !== "ready") continue;
+      if (!input.workerManager?.isRunning(plugin.id)) continue;
+    }
     return { plugin, driver };
   }
   return null;
@@ -73,10 +93,55 @@ export async function listReadyPluginEnvironmentDrivers(input: {
         driverKey: driver.driverKey,
         displayName: driver.displayName,
         description: driver.description,
+        configSchema: driver.configSchema,
       }));
   });
 }
 
+export async function validatePluginSandboxProviderConfig(input: {
+  db: Db;
+  workerManager: PluginWorkerManager;
+  provider: string;
+  config: Record<string, unknown>;
+}): Promise<{
+  normalizedConfig: Record<string, unknown>;
+  pluginId: string;
+  pluginKey: string;
+  driver: PluginEnvironmentDriverDeclaration;
+}> {
+  const resolved = await resolvePluginSandboxProviderDriverByKey({
+    db: input.db,
+    driverKey: input.provider,
+    workerManager: input.workerManager,
+    requireRunning: true,
+  });
+  if (!resolved) {
+    throw unprocessable(`Sandbox provider "${input.provider}" is not installed or its plugin worker is not running.`);
+  }
+
+  const result = await input.workerManager.call(resolved.plugin.id, "environmentValidateConfig", {
+    driverKey: input.provider,
+    config: input.config,
+  });
+
+  if (!result.ok) {
+    throw unprocessable(
+      result.errors?.[0] ?? `Sandbox provider "${input.provider}" rejected its config.`,
+      {
+        errors: result.errors ?? [],
+        warnings: result.warnings ?? [],
+      },
+    );
+  }
+
+  return {
+    normalizedConfig: result.normalizedConfig ?? input.config,
+    pluginId: resolved.plugin.id,
+    pluginKey: resolved.plugin.pluginKey,
+    driver: resolved.driver,
+  };
+}
+
 export async function validatePluginEnvironmentDriverConfig(input: {
   db: Db;
   workerManager: PluginWorkerManager;
@@ -156,11 +221,12 @@ export async function probePluginSandboxProviderDriver(input: {
     };
   }
 
+  const { provider: _provider, ...driverConfig } = input.config;
   const result = await input.workerManager.call(resolved.plugin.id, "environmentProbe", {
     driverKey: input.provider,
     companyId: input.companyId,
     environmentId: input.environmentId,
-    config: input.config,
+    config: driverConfig,
   });
 
   return {