@opengeni/runtime 0.2.0

package/src/sandbox/providers/blaxel.ts

@@ -0,0 +1,35 @@
+import { BlaxelSandboxClient } from "@openai/agents-extensions/sandbox/blaxel";
+import { CAPABILITY_DESCRIPTORS } from "../capabilities";
+import { SandboxConfigError } from "../errors";
+import type { ProviderRegistration } from "./types";
+
+export const blaxelProvider: ProviderRegistration = {
+  backend: "blaxel",
+  descriptor: CAPABILITY_DESCRIPTORS.blaxel,
+  validateCredentials(settings) {
+    if (!settings.blaxelApiKey) {
+      throw new SandboxConfigError("blaxel", "OPENGENI_BLAXEL_API_KEY is required");
+    }
+  },
+  build({ settings, environment }) {
+    // Blaxel exposes ports ON DEMAND (the only such backend) — its options take
+    // no `exposedPorts: number[]` list; 6080 is resolved at handshake time, so
+    // we do NOT pre-declare it here (this is why the factory's 6080-merge is
+    // gated on !supportsOnDemandPorts).
+    const options: NonNullable<ConstructorParameters<typeof BlaxelSandboxClient>[0]> = {
+      apiKey: settings.blaxelApiKey!,
+      env: environment,
+    };
+    if (settings.blaxelImage) options.image = settings.blaxelImage;
+    if (settings.blaxelRegion) options.region = settings.blaxelRegion;
+    if (settings.blaxelExposedPortPublic !== undefined) {
+      options.exposedPortPublic = settings.blaxelExposedPortPublic;
+    }
+    if (settings.blaxelExposedPortUrlTtlSeconds) {
+      options.exposedPortUrlTtlS = settings.blaxelExposedPortUrlTtlSeconds;
+    }
+    if (settings.blaxelMemoryMb) options.memory = settings.blaxelMemoryMb;
+    if (settings.blaxelTtl) options.ttl = settings.blaxelTtl;
+    return new BlaxelSandboxClient(options);
+  },
+};

package/src/sandbox/providers/cloudflare.ts

@@ -0,0 +1,24 @@
+import { CloudflareSandboxClient } from "@openai/agents-extensions/sandbox/cloudflare";
+import { CAPABILITY_DESCRIPTORS } from "../capabilities";
+import { SandboxConfigError } from "../errors";
+import type { ProviderRegistration } from "./types";
+
+export const cloudflareProvider: ProviderRegistration = {
+  backend: "cloudflare",
+  descriptor: CAPABILITY_DESCRIPTORS.cloudflare,
+  validateCredentials(settings) {
+    // workerUrl is the addressing root for the Cloudflare Sandbox Worker — there
+    // is no construction without it (it is the one non-optional client option).
+    if (!settings.cloudflareWorkerUrl) {
+      throw new SandboxConfigError("cloudflare", "OPENGENI_CLOUDFLARE_WORKER_URL is required");
+    }
+  },
+  build({ settings, exposedPorts }) {
+    const options: NonNullable<ConstructorParameters<typeof CloudflareSandboxClient>[0]> = {
+      workerUrl: settings.cloudflareWorkerUrl!,
+      exposedPorts,
+    };
+    if (settings.cloudflareApiKey) options.apiKey = settings.cloudflareApiKey;
+    return new CloudflareSandboxClient(options);
+  },
+};

package/src/sandbox/providers/daytona.ts

@@ -0,0 +1,34 @@
+import { DaytonaSandboxClient } from "@openai/agents-extensions/sandbox/daytona";
+import { CAPABILITY_DESCRIPTORS } from "../capabilities";
+import { SandboxConfigError } from "../errors";
+import type { ProviderRegistration } from "./types";
+
+export const daytonaProvider: ProviderRegistration = {
+  backend: "daytona",
+  descriptor: CAPABILITY_DESCRIPTORS.daytona,
+  validateCredentials(settings) {
+    if (!settings.daytonaApiKey) {
+      throw new SandboxConfigError("daytona", "OPENGENI_DAYTONA_API_KEY is required");
+    }
+  },
+  build({ settings, environment, exposedPorts }) {
+    const options: NonNullable<ConstructorParameters<typeof DaytonaSandboxClient>[0]> = {
+      apiKey: settings.daytonaApiKey!,
+      env: environment,
+      exposedPorts,
+    };
+    if (settings.daytonaApiUrl) options.apiUrl = settings.daytonaApiUrl;
+    if (settings.daytonaTarget) options.target = settings.daytonaTarget;
+    if (settings.daytonaImage) options.image = settings.daytonaImage;
+    if (settings.daytonaSnapshotName) options.sandboxSnapshotName = settings.daytonaSnapshotName;
+    // autoStopInterval=0 disables the idle-kill, so forward 0 explicitly.
+    if (settings.daytonaAutoStopInterval !== undefined) {
+      options.autoStopInterval = settings.daytonaAutoStopInterval;
+    }
+    if (settings.daytonaTimeoutSeconds) options.timeoutSec = settings.daytonaTimeoutSeconds;
+    if (settings.daytonaExposedPortUrlTtlSeconds) {
+      options.exposedPortUrlTtlS = settings.daytonaExposedPortUrlTtlSeconds;
+    }
+    return new DaytonaSandboxClient(options);
+  },
+};

package/src/sandbox/providers/docker.ts

@@ -0,0 +1,17 @@
+import { DockerSandboxClient } from "@openai/agents/sandbox/local";
+import { CAPABILITY_DESCRIPTORS } from "../capabilities";
+import type { ProviderRegistration } from "./types";
+
+export const dockerProvider: ProviderRegistration = {
+  backend: "docker",
+  descriptor: CAPABILITY_DESCRIPTORS.docker,
+  // Local dev container — no credentials. (The dockerNetwork decoration is
+  // applied by the factory, not here: it wraps the constructed client.)
+  validateCredentials() {},
+  build({ settings, exposedPorts }) {
+    return new DockerSandboxClient({
+      image: settings.dockerImage,
+      exposedPorts,
+    });
+  },
+};

package/src/sandbox/providers/e2b.ts

@@ -0,0 +1,36 @@
+import { E2BSandboxClient } from "@openai/agents-extensions/sandbox/e2b";
+import { CAPABILITY_DESCRIPTORS } from "../capabilities";
+import { SandboxConfigError } from "../errors";
+import type { ProviderRegistration } from "./types";
+
+export const e2bProvider: ProviderRegistration = {
+  backend: "e2b",
+  descriptor: CAPABILITY_DESCRIPTORS.e2b,
+  validateCredentials(settings) {
+    // The underlying e2b SDK reads E2B_API_KEY from process.env; we mirror it to
+    // settings so a misconfigured deployment fails fast here instead of deep in
+    // the SDK at create() time.
+    if (!settings.e2bApiKey) {
+      throw new SandboxConfigError("e2b", "OPENGENI_E2B_API_KEY is required");
+    }
+  },
+  build({ settings, environment, exposedPorts }) {
+    const options: NonNullable<ConstructorParameters<typeof E2BSandboxClient>[0]> = {
+      env: environment,
+      exposedPorts,
+    };
+    if (settings.e2bTemplate) options.template = settings.e2bTemplate;
+    // e2b's `timeout` is in SECONDS (the SDK multiplies by 1000 internally) —
+    // a different unit from Modal's `timeoutMs`.
+    if (settings.e2bTimeoutSeconds) options.timeout = settings.e2bTimeoutSeconds;
+    if (settings.e2bTimeoutAction) options.timeoutAction = settings.e2bTimeoutAction;
+    if (settings.e2bAllowInternetAccess !== undefined) {
+      options.allowInternetAccess = settings.e2bAllowInternetAccess;
+    }
+    if (settings.e2bAutoResume !== undefined) options.autoResume = settings.e2bAutoResume;
+    if (settings.e2bWorkspacePersistence) {
+      options.workspacePersistence = settings.e2bWorkspacePersistence;
+    }
+    return new E2BSandboxClient(options);
+  },
+};

package/src/sandbox/providers/index.ts

@@ -0,0 +1,107 @@
+// The provider registry — PROVIDER_REGISTRY maps each SandboxBackend to its
+// ProviderRegistration. This is the data structure createSandboxClient drives
+// (replacing the old flat if/else chain). The module also owns the
+// descriptor.backendId === SDK client.backendId assertion (deferred from P0.1):
+// it must construct the real SDK clients, so it lives here rather than in the
+// contracts-only capabilities self-test.
+
+import type { Settings } from "@opengeni/config";
+import { SandboxBackend } from "@opengeni/contracts";
+import { assertDescriptorRegistryInvariants } from "../capabilities";
+import { blaxelProvider } from "./blaxel";
+import { cloudflareProvider } from "./cloudflare";
+import { daytonaProvider } from "./daytona";
+import { dockerProvider } from "./docker";
+import { e2bProvider } from "./e2b";
+import { localProvider } from "./local";
+import { modalProvider } from "./modal";
+import { noneProvider } from "./none";
+import { runloopProvider } from "./runloop";
+import { selfhostedProvider } from "./selfhosted";
+import type { ProviderRegistration } from "./types";
+import { vercelProvider } from "./vercel";
+
+export const PROVIDER_REGISTRY: Record<SandboxBackend, ProviderRegistration> = {
+  docker: dockerProvider,
+  modal: modalProvider,
+  local: localProvider,
+  none: noneProvider,
+  daytona: daytonaProvider,
+  runloop: runloopProvider,
+  e2b: e2bProvider,
+  blaxel: blaxelProvider,
+  cloudflare: cloudflareProvider,
+  vercel: vercelProvider,
+  selfhosted: selfhostedProvider,
+};
+
+// Stub settings carrying every per-provider credential, used ONLY by the
+// boot-time backendId assertion to construct each client without tripping
+// validateCredentials. The SDK client constructors are pure option-stores (the
+// underlying provider SDK is required lazily at create()/resume() time, never at
+// construction — verified against @openai/agents-extensions 0.11.6), so this is
+// safe with no provider peer dep installed and no network.
+const ASSERTION_STUB_SETTINGS = {
+  dockerImage: "opengeni-sandbox:local",
+  modalAppName: "opengeni-sandbox",
+  modalTimeoutSeconds: 900,
+  daytonaApiKey: "stub",
+  runloopApiKey: "stub",
+  runloopTunnel: true,
+  e2bApiKey: "stub",
+  blaxelApiKey: "stub",
+  cloudflareWorkerUrl: "https://stub.example.com",
+  vercelToken: "stub",
+  vercelProjectId: "stub",
+} as unknown as Settings;
+
+/**
+ * Assert the descriptor table AND that each registered provider's SDK client
+ * reports the backendId its descriptor claims. The latter is the
+ * deferred-from-P0.1 invariant — it can only run here because it constructs the
+ * real clients. Called once at registry build (and from a unit test).
+ */
+export function assertProviderRegistryInvariants(): void {
+  assertDescriptorRegistryInvariants();
+  for (const backend of SandboxBackend.options) {
+    const registration = PROVIDER_REGISTRY[backend];
+    if (registration.backend !== backend) {
+      throw new Error(`PROVIDER_REGISTRY["${backend}"].backend mismatch (got "${registration.backend}")`);
+    }
+    if (registration.descriptor.backend !== backend) {
+      throw new Error(`PROVIDER_REGISTRY["${backend}"].descriptor.backend mismatch (got "${registration.descriptor.backend}")`);
+    }
+    if (backend === "none") {
+      // "none" has no SDK client (build returns undefined); the descriptor
+      // backendId "none" is self-consistent.
+      if (registration.descriptor.backendId !== "none") {
+        throw new Error(`"none" descriptor.backendId must be "none" (got "${registration.descriptor.backendId}")`);
+      }
+      continue;
+    }
+    const client = registration.build({
+      settings: ASSERTION_STUB_SETTINGS,
+      environment: {},
+      exposedPorts: [],
+    });
+    const sdkBackendId = (client as { backendId?: unknown } | undefined)?.backendId;
+    if (typeof sdkBackendId !== "string") {
+      throw new Error(`Provider "${backend}" SDK client has no string backendId`);
+    }
+    if (sdkBackendId !== registration.descriptor.backendId) {
+      throw new Error(
+        `Provider "${backend}" backendId mismatch: descriptor.backendId="${registration.descriptor.backendId}" but SDK client.backendId="${sdkBackendId}"`,
+      );
+    }
+  }
+}
+
+// Boot-validate the registry once at module load: the descriptor-table self-
+// test PLUS the descriptor.backendId === SDK client.backendId assertion (the
+// deferred-from-P0.1 invariant). The SDK client constructors are pure option-
+// stores (no network, no peer-dep require at construction), so this is a cheap,
+// side-effect-free guard that fails fast on any drift between the static matrix
+// and the installed @openai/agents-extensions.
+assertProviderRegistryInvariants();
+
+export type { ProviderRegistration, ProviderConstructionContext } from "./types";

package/src/sandbox/providers/local.ts

@@ -0,0 +1,13 @@
+import { UnixLocalSandboxClient } from "@openai/agents/sandbox/local";
+import { CAPABILITY_DESCRIPTORS } from "../capabilities";
+import type { ProviderRegistration } from "./types";
+
+export const localProvider: ProviderRegistration = {
+  backend: "local",
+  descriptor: CAPABILITY_DESCRIPTORS.local,
+  // UnixLocalSandboxClient runs in-process — no credentials, no options.
+  validateCredentials() {},
+  build() {
+    return new UnixLocalSandboxClient();
+  },
+};

package/src/sandbox/providers/modal.ts

@@ -0,0 +1,55 @@
+import { ModalImageSelector, ModalSandboxClient } from "@openai/agents-extensions/sandbox/modal";
+import { effectiveModalIdleTimeoutSeconds } from "@opengeni/config";
+import { CAPABILITY_DESCRIPTORS } from "../capabilities";
+import { SandboxConfigError } from "../errors";
+import type { ProviderRegistration } from "./types";
+
+export const modalProvider: ProviderRegistration = {
+  backend: "modal",
+  descriptor: CAPABILITY_DESCRIPTORS.modal,
+  validateCredentials(settings) {
+    // both-or-neither (preserves existing validation at config validateSettings).
+    if (Boolean(settings.modalTokenId) !== Boolean(settings.modalTokenSecret)) {
+      throw new SandboxConfigError(
+        "modal",
+        "OPENGENI_MODAL_TOKEN_ID and OPENGENI_MODAL_TOKEN_SECRET must both be set or both omitted",
+      );
+    }
+    if (!settings.modalAppName) {
+      throw new SandboxConfigError("modal", "OPENGENI_MODAL_APP_NAME is required");
+    }
+  },
+  build({ settings, environment, exposedPorts }) {
+    const options: NonNullable<ConstructorParameters<typeof ModalSandboxClient>[0]> = {
+      appName: settings.modalAppName,
+      timeoutMs: settings.modalTimeoutSeconds * 1000,
+      exposedPorts,
+      env: environment,
+    };
+    // gap-fill (module 03 §4.1): these SDK options were previously unmapped.
+    // ALWAYS pin idleTimeoutMs (sandbox-file-persistence): an UNSET idle timeout
+    // lets the SDK send idleTimeoutSecs=undefined, so Modal applies its short
+    // server-default idle-reap and kills an idle (between-turns) box LONG before
+    // OpenGeni's reaper can resume+snapshot it. effectiveModalIdleTimeoutSeconds
+    // defaults this to the hard lifetime so the box survives its full warm window
+    // and the reaper — not Modal's idle-reap — governs teardown (and snapshots
+    // /workspace first).
+    options.idleTimeoutMs = effectiveModalIdleTimeoutSeconds(settings) * 1000;
+    if (settings.modalWorkspacePersistence) {
+      options.workspacePersistence = settings.modalWorkspacePersistence;
+    }
+    if (settings.modalImageRef) {
+      options.image = ModalImageSelector.fromTag(settings.modalImageRef);
+    }
+    if (settings.modalTokenId) {
+      options.tokenId = settings.modalTokenId;
+    }
+    if (settings.modalTokenSecret) {
+      options.tokenSecret = settings.modalTokenSecret;
+    }
+    if (settings.modalEnvironment) {
+      options.environment = settings.modalEnvironment;
+    }
+    return new ModalSandboxClient(options);
+  },
+};

package/src/sandbox/providers/none.ts

@@ -0,0 +1,13 @@
+import { CAPABILITY_DESCRIPTORS } from "../capabilities";
+import type { ProviderRegistration } from "./types";
+
+export const noneProvider: ProviderRegistration = {
+  backend: "none",
+  descriptor: CAPABILITY_DESCRIPTORS.none,
+  // No sandbox: nothing to validate, and build() returns undefined. The factory
+  // short-circuits on "none" before calling build, but we keep build honest.
+  validateCredentials() {},
+  build() {
+    return undefined;
+  },
+};

package/src/sandbox/providers/runloop.ts

@@ -0,0 +1,32 @@
+import { RunloopSandboxClient } from "@openai/agents-extensions/sandbox/runloop";
+import { CAPABILITY_DESCRIPTORS } from "../capabilities";
+import { SandboxConfigError } from "../errors";
+import type { ProviderRegistration } from "./types";
+
+export const runloopProvider: ProviderRegistration = {
+  backend: "runloop",
+  descriptor: CAPABILITY_DESCRIPTORS.runloop,
+  validateCredentials(settings) {
+    if (!settings.runloopApiKey) {
+      throw new SandboxConfigError("runloop", "OPENGENI_RUNLOOP_API_KEY is required");
+    }
+  },
+  build({ settings, environment, exposedPorts }) {
+    const options: NonNullable<ConstructorParameters<typeof RunloopSandboxClient>[0]> = {
+      apiKey: settings.runloopApiKey!,
+      env: environment,
+      exposedPorts,
+      // Tunnel v2: one tunnel for all ports. Defaults to true in our config.
+      tunnel: settings.runloopTunnel,
+    };
+    if (settings.runloopBaseUrl) options.baseUrl = settings.runloopBaseUrl;
+    if (settings.runloopBlueprintName) options.blueprintName = settings.runloopBlueprintName;
+    if (settings.runloopBlueprintId) options.blueprintId = settings.runloopBlueprintId;
+    // Runloop's keep-alive lives under the timeouts bag (keepAliveTimeoutMs),
+    // NOT a top-level field — the units differ from Modal's idleTimeoutMs.
+    if (settings.runloopKeepAliveSeconds) {
+      options.timeouts = { keepAliveTimeoutMs: settings.runloopKeepAliveSeconds * 1000 };
+    }
+    return new RunloopSandboxClient(options);
+  },
+};

package/src/sandbox/providers/selfhosted.ts

@@ -0,0 +1,96 @@
+// Bring-your-own-compute: the user's own machine, enrolled via the Rust agent,
+// is reached over the NATS request/reply control plane (the agent subscribes to
+// `agent.<workspace>.<agentId>.rpc`; the subject IS the registry). There is NO
+// provider SDK and NO per-box credential — "the agent is the box".
+//
+// M3 ships the REAL `SelfhostedSandboxClient`: its `create()`/`resume()` return a
+// `SelfhostedSession` presenting the structural surface (`exec`/`readFile`/
+// `writeFile`/`resolveExposedPort`/`serializeSessionState`) that Channel-A, the
+// viewer, and computer-use consume unchanged — backed by a `ControlRpc` seam
+// (request/reply encoded via `@opengeni/agent-proto`) instead of a provider SDK.
+// `serializeSessionState`/`deserializeSessionState` round-trip `{agentId}` ONLY:
+// resume = re-address the live subject, never a cold re-create (the machine is
+// not recreatable). The live NATS request/reply transport + Accounts land in M4
+// behind the SAME `ControlRpc`.
+
+import type { Settings } from "@opengeni/config";
+import { CAPABILITY_DESCRIPTORS } from "../capabilities";
+import {
+  NatsControlRpc,
+  type ControlRpc,
+  type NatsRequestConnection,
+} from "../selfhosted/control-rpc";
+import {
+  SelfhostedSandboxClient,
+  type SelfhostedRelayConfig,
+} from "../selfhosted/session";
+import type { ProviderRegistration } from "./types";
+
+/**
+ * Resolve the relay-URL shape config from settings. M8b threads the real relay
+ * deployment URL (`OPENGENI_SELFHOSTED_RELAY_URL`, ops-repo IaC) behind this seam:
+ * `resolveExposedPort` returns `{host, port, tls, path, query}` so `buildStreamUrl`
+ * assembles the relay dial URL. A path-less URL defaults to the relay's `/stream`
+ * route; an unconfigured deployment falls back to a placeholder host (the URL shape
+ * is still well-formed; the relay is simply unreachable until configured).
+ */
+function resolveRelayConfig(settings: Settings): SelfhostedRelayConfig {
+  const raw = settings.selfhostedRelayUrl?.trim();
+  if (!raw) {
+    return { host: "relay.opengeni.local", port: 443, tls: true, path: "/stream" };
+  }
+  try {
+    const url = new URL(raw.includes("://") ? raw : `wss://${raw}`);
+    const tls = url.protocol === "wss:" || url.protocol === "https:";
+    const port = url.port ? Number(url.port) : tls ? 443 : 80;
+    const path = url.pathname && url.pathname !== "/" ? url.pathname : "/stream";
+    return { host: url.hostname, port, tls, path };
+  } catch {
+    return { host: raw, port: 443, tls: true, path: "/stream" };
+  }
+}
+
+/**
+ * The default `ControlRpc` factory for a registry-built client: a
+ * `NatsControlRpc` whose connection factory returns null — there is NO live NATS
+ * connection wired into the agent-loop-free runtime leaf at build() time (the
+ * API/worker inject the live `@opengeni/events` connection per request in M4).
+ * A null connection surfaces `agent_offline` on every op rather than throwing at
+ * construction, so boot never requires a live NATS — exactly the M3 ruling.
+ */
+function defaultControlRpcFactory(): ControlRpc {
+  return new NatsControlRpc(async (): Promise<NatsRequestConnection | null> => null);
+}
+
+export const selfhostedProvider: ProviderRegistration = {
+  backend: "selfhosted",
+  descriptor: CAPABILITY_DESCRIPTORS.selfhosted,
+  /**
+   * No per-box credentials: the machine is reached over the agent's own
+   * enrollment. The enrollment-signing + relay-token secrets are deployment-level
+   * config that lands with the connectivity/enrollment milestones (M4/M5) — and
+   * the whole feature is gated by a `sandboxSelfhostedEnabled` flag (default off)
+   * that does not yet exist in Settings. So validation is LENIENT (no-op) in M3:
+   * boot must never break, and there is nothing per-box to validate. M4/M5 add
+   * the (flag-gated) signing/relay presence checks here behind the same seam.
+   */
+  validateCredentials() {},
+  /**
+   * Build the registry client. `create()`/`resume()` bind a `SelfhostedSession`
+   * to the agent subject; the per-request `{workspaceId, agentId, controlRpc}`
+   * are supplied by the resume path (the lease's enrollment) — the registry
+   * client carries the relay config + the default (offline-until-M4) ControlRpc
+   * factory and a backendId-correct surface for `assertProviderRegistryInvariants`.
+   */
+  build({ settings }) {
+    return new SelfhostedSandboxClient({
+      // The workspaceId is bound per-request by the resume path (the API/worker
+      // construct a request-scoped client with the lease's workspace + a live
+      // ControlRpc). The registry-built client is the boot/assertion shape; an
+      // empty workspaceId is fine until a session is bound with a real one.
+      workspaceId: "",
+      relay: resolveRelayConfig(settings),
+      controlRpcFactory: defaultControlRpcFactory,
+    });
+  },
+};

package/src/sandbox/providers/types.ts

@@ -0,0 +1,38 @@
+// The uniform per-provider registration shape (module 03 §3.1).
+//
+// One file per provider implements ProviderRegistration; PROVIDER_REGISTRY maps
+// each SandboxBackend to its registration. This replaces the flat if/else chain
+// that createSandboxClient used to be.
+
+import type { Settings } from "@opengeni/config";
+import type { CapabilityDescriptor, SandboxBackend } from "@opengeni/contracts";
+
+export interface ProviderConstructionContext {
+  settings: Settings;
+  /** The env map for the box (collectSandboxEnvironment / per-run environment). */
+  environment: Record<string, string>;
+  /**
+   * Parsed exposed ports (config string -> number[]); already includes the
+   * desktop stream port (6080) when this is a desktop tier with desktop enabled
+   * and the provider cannot expose ports on demand (the merge happens in
+   * createSandboxClient before build()).
+   */
+  exposedPorts: number[];
+}
+
+export interface ProviderRegistration {
+  backend: SandboxBackend;
+  descriptor: CapabilityDescriptor;
+  /**
+   * Validate that the settings carry the credentials/config this provider
+   * REQUIRES. Throw SandboxConfigError on any missing/contradictory field.
+   * Pure — no network. Called by both the factory and a deploy-time preflight.
+   * The factory calls this before build(), so build() may assume valid settings.
+   */
+  validateCredentials(settings: Settings): void;
+  /**
+   * Build the raw SDK SandboxClient. Returns undefined ONLY for "none".
+   * The factory calls validateCredentials() first, so build() can assume valid.
+   */
+  build(ctx: ProviderConstructionContext): unknown;
+}

package/src/sandbox/providers/vercel.ts

@@ -0,0 +1,29 @@
+import { VercelSandboxClient } from "@openai/agents-extensions/sandbox/vercel";
+import { CAPABILITY_DESCRIPTORS } from "../capabilities";
+import { SandboxConfigError } from "../errors";
+import type { ProviderRegistration } from "./types";
+
+export const vercelProvider: ProviderRegistration = {
+  backend: "vercel",
+  descriptor: CAPABILITY_DESCRIPTORS.vercel,
+  validateCredentials(settings) {
+    // Vercel needs the access token + the project/team it scopes to.
+    if (!settings.vercelToken) {
+      throw new SandboxConfigError("vercel", "OPENGENI_VERCEL_TOKEN is required");
+    }
+    if (!settings.vercelProjectId) {
+      throw new SandboxConfigError("vercel", "OPENGENI_VERCEL_PROJECT_ID is required");
+    }
+  },
+  build({ settings, environment, exposedPorts }) {
+    const options: NonNullable<ConstructorParameters<typeof VercelSandboxClient>[0]> = {
+      token: settings.vercelToken!,
+      projectId: settings.vercelProjectId!,
+      env: environment,
+      exposedPorts,
+    };
+    if (settings.vercelTeamId) options.teamId = settings.vercelTeamId;
+    if (settings.vercelRuntime) options.runtime = settings.vercelRuntime;
+    return new VercelSandboxClient(options);
+  },
+};