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-secrets-handler.ts

@@ -39,6 +39,11 @@ import { companySecrets, companySecretVersions, pluginConfig } from "@paperclipa
 import type { SecretProvider } from "@paperclipai/shared";
 import { getSecretProvider } from "../secrets/provider-registry.js";
 import { pluginRegistryService } from "./plugin-registry.js";
+import {
+  collectSecretRefPaths,
+  isUuidSecretRef,
+  readConfigValueAtPath,
+} from "./json-schema-secret-refs.js";
 
 // ---------------------------------------------------------------------------
 // Error helpers
@@ -70,48 +75,6 @@ function invalidSecretRef(secretRef: string): Error {
 // Validation
 // ---------------------------------------------------------------------------
 
-/** UUID v4 regex for validating secretRef format. */
-const UUID_RE =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-/**
- * Check whether a secretRef looks like a valid UUID.
- */
-function isUuid(value: string): boolean {
-  return UUID_RE.test(value);
-}
-
-/**
- * Collect the property paths (dot-separated keys) whose schema node declares
- * `format: "secret-ref"`. Only top-level and nested `properties` are walked —
- * this mirrors the flat/nested object shapes that `JsonSchemaForm` renders.
- */
-function collectSecretRefPaths(
-  schema: Record<string, unknown> | null | undefined,
-): Set<string> {
-  const paths = new Set<string>();
-  if (!schema || typeof schema !== "object") return paths;
-
-  function walk(node: Record<string, unknown>, prefix: string): void {
-    const props = node.properties as Record<string, Record<string, unknown>> | undefined;
-    if (!props || typeof props !== "object") return;
-    for (const [key, propSchema] of Object.entries(props)) {
-      if (!propSchema || typeof propSchema !== "object") continue;
-      const path = prefix ? `${prefix}.${key}` : key;
-      if (propSchema.format === "secret-ref") {
-        paths.add(path);
-      }
-      // Recurse into nested object schemas
-      if (propSchema.type === "object") {
-        walk(propSchema, path);
-      }
-    }
-  }
-
-  walk(schema, "");
-  return paths;
-}
-
 /**
  * Extract secret reference UUIDs from a plugin's configJson, scoped to only
  * the fields annotated with `format: "secret-ref"` in the schema.
@@ -131,13 +94,8 @@ export function extractSecretRefsFromConfig(
   // If schema declares secret-ref paths, extract only those values.
   if (secretPaths.size > 0) {
     for (const dotPath of secretPaths) {
-      const keys = dotPath.split(".");
-      let current: unknown = configJson;
-      for (const k of keys) {
-        if (current == null || typeof current !== "object") { current = undefined; break; }
-        current = (current as Record<string, unknown>)[k];
-      }
-      if (typeof current === "string" && isUuid(current)) {
+      const current = readConfigValueAtPath(configJson as Record<string, unknown>, dotPath);
+      if (typeof current === "string" && isUuidSecretRef(current)) {
         refs.add(current);
       }
     }
@@ -149,7 +107,7 @@ export function extractSecretRefsFromConfig(
   // instanceConfigSchema.
   function walkAll(value: unknown): void {
     if (typeof value === "string") {
-      if (isUuid(value)) refs.add(value);
+      if (isUuidSecretRef(value)) refs.add(value);
     } else if (Array.isArray(value)) {
       for (const item of value) walkAll(item);
     } else if (value !== null && typeof value === "object") {
@@ -279,7 +237,7 @@ export function createPluginSecretsHandler(
 
       const trimmedRef = secretRef.trim();
 
-      if (!isUuid(trimmedRef)) {
+      if (!isUuidSecretRef(trimmedRef)) {
         throw invalidSecretRef(trimmedRef);
       }