@opengeni/config 0.2.0

package/dist/index.js

@@ -0,0 +1,1728 @@
+// src/index.ts
+import {
+  BillingMode,
+  CAPABILITY_DESCRIPTORS,
+  Entitlements,
+  EntitlementsMode,
+  ProductAccessMode,
+  ReasoningEffort,
+  SandboxBackend,
+  StaticUsageLimits,
+  UsageLimitsMode
+} from "@opengeni/contracts";
+import { CODEX_MODEL_ID_PREFIX } from "@opengeni/codex/constants";
+import { z } from "zod";
+var envName = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var registryId = /^[A-Za-z0-9_-]+$/;
+var EnvBoolean = z.preprocess((value) => {
+  if (typeof value !== "string") {
+    return value;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (["true", "1", "yes", "y", "on"].includes(normalized)) {
+    return true;
+  }
+  if (["false", "0", "no", "n", "off"].includes(normalized)) {
+    return false;
+  }
+  return value;
+}, z.boolean());
+var sandboxPreparationProfiles = {
+  none: {
+    env: [],
+    hooks: []
+  },
+  azure: {
+    env: [
+      "ARM_CLIENT_ID",
+      "ARM_CLIENT_SECRET",
+      "ARM_TENANT_ID",
+      "ARM_SUBSCRIPTION_ID",
+      "AZURE_CLIENT_ID",
+      "AZURE_CLIENT_SECRET",
+      "AZURE_TENANT_ID",
+      "AZURE_SUBSCRIPTION_ID",
+      "AZURE_AUTHORITY_HOST"
+    ],
+    hooks: ["azure-cli-login"]
+  },
+  github: {
+    env: [
+      "GH_TOKEN",
+      "GITHUB_TOKEN",
+      "GIT_AUTHOR_NAME",
+      "GIT_AUTHOR_EMAIL",
+      "GIT_COMMITTER_NAME",
+      "GIT_COMMITTER_EMAIL"
+    ],
+    hooks: []
+  }
+};
+var AGENT_INSTRUCTIONS_CORE_PLACEHOLDER = "{{core}}";
+var DEFAULT_AGENT_INSTRUCTIONS = [
+  "You are an OpenGeni workspace agent.",
+  "Follow the user's task and any enabled pack or skill instructions for the current role.",
+  "Work inside the sandbox workspace and use filesystem and shell tools when useful.",
+  "Repository resources are mounted under repos/<owner>/<repo>.",
+  "File resources are mounted under files/<file-id>/ unless the session specifies another mount path.",
+  "Attached files are mounted read-only; copy them before modifying.",
+  "Bundled skills are under .agents/ and can include infrastructure, marketing, or other role-specific guidance.",
+  "Use Checkov, Terraform, Azure CLI, GitHub CLI, and repository tools when relevant.",
+  "When the Azure sandbox preparation profile is enabled and service-principal variables are present, the sandbox is pre-authenticated with normal Azure CLI before work starts.",
+  "Treat code-changing work as GitOps work: create a focused branch/commit/PR when GitHub credentials are available; otherwise report exact commands and blockers.",
+  "Return concise, factual summaries with files changed, commands run, and remaining blockers.",
+  AGENT_INSTRUCTIONS_CORE_PLACEHOLDER
+].join(" ");
+var SettingsSchema = z.object({
+  serviceName: z.string().default("opengeni"),
+  environment: z.string().default("local"),
+  deploymentRevision: z.string().default("dev"),
+  databaseUrl: z.string().default("postgres://opengeni:opengeni@127.0.0.1:5432/opengeni"),
+  // Step I (§7.8 runtime half). Dedicated Postgres schema for the EMBEDDED
+  // topology. Default "" → standalone: no search_path scoping, server default
+  // (`public`). When set (e.g. "opengeni"), the db handle + the managed-auth
+  // pool send `search_path = "<dbSchema>","opengeni_private","public"` so every
+  // query resolves into the dedicated schema with NO query rewrite (SPIKE-1 F1).
+  dbSchema: z.string().default(""),
+  // Step I (§7.7). RLS posture. "force" (default) = today's FORCE-RLS via the
+  // non-owner `opengeni_app` role. "scoped" = the embedded owner-role path (the
+  // GUC is still emitted defensively, so the query path is identical).
+  rlsStrategy: z.enum(["force", "scoped"]).default("force"),
+  natsUrl: z.string().default("nats://127.0.0.1:4222"),
+  temporalHost: z.string().default("127.0.0.1:7233"),
+  temporalNamespace: z.string().default("default"),
+  temporalTaskQueue: z.string().default("opengeni-runs-ts"),
+  startupDependencyRetryAttempts: z.coerce.number().int().positive().default(30),
+  startupDependencyRetryInitialDelayMs: z.coerce.number().int().positive().default(1e3),
+  startupDependencyRetryMaxDelayMs: z.coerce.number().int().positive().default(5e3),
+  observabilityStructuredLogs: EnvBoolean.default(false),
+  observabilityMetricsEnabled: EnvBoolean.default(true),
+  observabilityOtlpEndpoint: z.string().url().optional(),
+  observabilityOtlpHeaders: z.string().default(""),
+  publicBaseUrl: z.string().url().optional(),
+  // Base URL for the bring-your-own-compute agent release assets the get.<domain>
+  // install routes redirect to. Defaults to this repo's GitHub Releases. The route
+  // appends `/download/agent-v<ver>/<asset>` (or `/latest/download/<asset>`).
+  agentReleasesBaseUrl: z.string().url().default("https://github.com/Cloudgeni-ai/opengeni/releases"),
+  productAccessMode: ProductAccessMode.default("local"),
+  billingMode: BillingMode.default("disabled"),
+  entitlementsMode: EntitlementsMode.default("none"),
+  usageLimitsMode: UsageLimitsMode.default("none"),
+  staticEntitlementsJson: z.string().default("{}"),
+  staticUsageLimitsJson: z.string().default("{}"),
+  delegationSecret: z.string().optional(),
+  // Sandbox-surfacing scoped stream-token HMAC secret (master-spine §C.3 / I8).
+  // When unset, the API falls back to `delegationSecret` (the same HMAC envelope
+  // family, `ogs_` vs `ogd_` prefix). REQUIRED-WHEN-DESKTOP, but the absence of
+  // BOTH while sandboxDesktopEnabled=true is a GRACEFUL DEGRADE (DesktopStream
+  // transport:null + a loud boot warning), NOT a hard boot-fail (I8/OD-8).
+  streamTokenSecret: z.string().optional(),
+  // The desktop input plane (raw stream:control writes) is OFF in v1: even a
+  // holder of stream:control gets 403 until this flips. Keeps stream:control a
+  // declared-but-inert permission so later hardening is a flag flip.
+  streamControlEnabled: EnvBoolean.default(false),
+  environmentsEncryptionKey: z.string().optional(),
+  // Session goal guard rails. Goals are designed for runs that legitimately
+  // span days, so length is bounded by pathology detection (no-progress
+  // streaks, budget exhaustion), never by count. goalMaxAutoContinuations is
+  // therefore UNSET by default (no cap); deployments may configure one, and
+  // it then acts as a hard ceiling that per-goal overrides can only lower.
+  goalMaxAutoContinuations: z.coerce.number().int().positive().optional(),
+  goalNoProgressLimit: z.coerce.number().int().positive().default(3),
+  // Per-segment ceiling on agent loop turns (model calls) within a single
+  // session turn. Effectively unbounded by default for the same reason as
+  // above; the graceful max-turns valve (idle + goal continuation, never a
+  // session failure) remains as inert safety should a deployment set a cap.
+  agentMaxModelCallsPerTurn: z.coerce.number().int().positive().default(1e6),
+  // Where turn-input conversation history comes from (issue #35):
+  // "items" (default) = the session_history_items table (SDK-native,
+  // version-stable conversation truth); "run_state" = the legacy serialized
+  // RunState blob. Items and the sandbox envelope are dual-written
+  // unconditionally; this flag governs the read path only, so flipping back to
+  // "run_state" remains a safe rollback at any time.
+  sessionHistorySource: z.enum(["run_state", "items"]).default("items"),
+  // Provider-aware conversation context management (long-lived sessions
+  // otherwise grow unbounded until they overflow the model context window and
+  // hard-fail every turn). Resolution (see resolveContextCompactionMode):
+  //   "auto" (default) -> "server" when openaiProvider === "openai" (the
+  //     OpenAI platform Responses API honors server-side context_management),
+  //     else "client" (Azure rejects context_management with a 400, so we run
+  //     our own client-side compaction).
+  //   "server" / "client" -> force that path regardless of provider.
+  //   "off" -> neither path (legacy unbounded growth; escape hatch only).
+  contextCompactionMode: z.enum(["auto", "server", "client", "off"]).default("auto"),
+  // The model's real context window in tokens. gpt-5.5's true window is
+  // 1,050,000; it is absent from the SDK's hardcoded compaction window map (it
+  // knows only up to gpt-5.4), so the SDK's DynamicCompactionPolicy would fall
+  // back to a wrong 240k. We pass an explicit StaticCompactionPolicy threshold
+  // derived from these settings on the server path, and use the same numbers to
+  // budget the client path.
+  contextWindowTokens: z.coerce.number().int().positive().default(105e4),
+  // Tokens reserved for model output; subtracted from the window to get the
+  // usable input budget B = contextWindowTokens - contextReservedOutputTokens.
+  contextReservedOutputTokens: z.coerce.number().int().nonnegative().default(128e3),
+  // Server path only: explicit compact_threshold (tokens) handed to the SDK's
+  // StaticCompactionPolicy. Defaults to floor(B * contextCompactSoftFraction)
+  // when unset.
+  contextServerCompactThresholdTokens: z.coerce.number().int().positive().optional(),
+  // Client path: compact pre-turn when the last turn's actual input tokens
+  // reach softFraction*B; hard-force at hardFraction*B.
+  contextCompactSoftFraction: z.coerce.number().positive().max(1).default(0.7),
+  contextCompactHardFraction: z.coerce.number().positive().max(1).default(0.85),
+  // Client path: tokens of the most recent FULL turns kept verbatim after a
+  // compaction (the live working set: recent tool results, not just messages).
+  contextKeepRecentTokens: z.coerce.number().int().positive().default(32e3),
+  // Client path: token ceiling on the generated summary body.
+  contextSummaryMaxTokens: z.coerce.number().int().positive().default(2e4),
+  authRequired: EnvBoolean.default(false),
+  accessKey: z.string().optional(),
+  authAllowHealth: EnvBoolean.default(true),
+  authAllowMetrics: EnvBoolean.default(false),
+  apiHost: z.string().default("0.0.0.0"),
+  apiPort: z.coerce.number().int().positive().default(8e3),
+  opengeniMcpUrl: z.string().url().optional(),
+  corsAllowOriginRegex: z.string().default(String.raw`^https?://(localhost|127\.0\.0\.1)(:\d+)?$`),
+  openaiProvider: z.enum(["openai", "azure"]).default("openai"),
+  openaiApiKey: z.string().optional(),
+  openaiBaseUrl: z.string().optional(),
+  openaiModel: z.string().default("gpt-5.5"),
+  openaiAllowedModels: z.string().default("gpt-5.5,gpt-5.4,gpt-5.4-mini"),
+  modelPricingJson: z.string().default("{}"),
+  // Extra (non-built-in) model providers, declared by the host as a JSON
+  // provider registry. Each entry carries its own base URL, API key, wire API
+  // ("responses" | "chat") and the models it exposes. The models a client may
+  // use are the UNION of the built-in provider's allowed models and every
+  // registry provider's models. validateSettings parses this at boot so a
+  // malformed registry / unresolvable key / id collision fails fast.
+  modelProvidersJson: z.string().default("[]"),
+  // Codex (ChatGPT) subscription: when enabled, a per-workspace connected
+  // subscription is injected as a synthetic "codex-subscription" registry
+  // provider whose models route through the ChatGPT backend (@opengeni/codex).
+  codexSubscriptionEnabled: EnvBoolean.default(false),
+  // OPENGENI_CODEX_SUBSCRIPTION_ENABLED
+  codexProductSku: z.string().optional(),
+  // OPENGENI_CODEX_PRODUCT_SKU (X-OpenAI-Product-Sku, apps only)
+  // Progressive connector disclosure (Codex-CLI-style tool_search): on a codex
+  // turn, flag the ~217 codex_apps connector tools `defer_loading:true` (dropping
+  // their schemas from model context) and add one client-executed tool_search
+  // tool that BM25-discloses only the matching connectors. Default OFF — a codex
+  // turn is byte-for-byte unchanged until enabled. OPENGENI_CODEX_TOOL_SEARCH_ENABLED
+  codexToolSearchEnabled: EnvBoolean.default(false),
+  // Multi-account P3 (auto-rotation): an account is "near exhaustion" — ineligible to be
+  // rotated TO — when EITHER usage window (5h/weekly) is at/over this percent. Default 90 to
+  // match the UI danger flip (UsageBar danger at pct >= 90). OPENGENI_CODEX_ROTATION_NEAR_EXHAUSTION_PCT.
+  codexRotationNearExhaustionPct: z.coerce.number().int().min(1).max(100).default(90),
+  openaiReasoningEffort: ReasoningEffort.default("low"),
+  openaiAllowedReasoningEfforts: z.string().default("low,medium,high,xhigh"),
+  openaiResponsesTransport: z.enum(["http", "websocket"]).default("http"),
+  // Provider-assigned item ids (rs_/msg_/fc_…) in Responses API input are
+  // resolved against the provider's server-side response store. That store is
+  // not durable enough to anchor long runs on: a response that streamed fine
+  // can be missing from the store on the very next model call, which then
+  // fails with 400 "Item with id ... not found". "strip" removes the ids from
+  // every model-call input so requests are self-contained — conversation
+  // truth already lives client-side in session_history_items. "preserve"
+  // keeps the SDK's pass-through behavior.
+  openaiProviderItemIds: z.enum(["strip", "preserve"]).default("strip"),
+  // With ids stripped the provider cannot resolve prior reasoning server-side,
+  // so request reasoning.encrypted_content and send it back with each call:
+  // reasoning continuity without depending on provider-side storage.
+  openaiReasoningEncryptedContent: EnvBoolean.default(true),
+  // Model-call retry budget for transient provider failures (429s and friends).
+  // The openai client default of 2 retries is too small for sustained TPM
+  // backpressure during long autonomous runs.
+  openaiMaxRetries: z.coerce.number().int().nonnegative().default(5),
+  // Native hosted web search. The live Azure Responses path executes the
+  // hosted web_search tool, so this is provider-unconditional: ON by default
+  // on every provider, exposed only so operators can disable it. When true,
+  // buildOpenGeniAgent attaches webSearchTool() to the agent's tools — it is
+  // merged with the MCP-server tools (getAllTools = [...mcpTools, ...tools])
+  // and the sandbox capability tools, never replacing them.
+  webSearchEnabled: EnvBoolean.default(true),
+  // Deployment-default agent persona template (the white-label surface). The
+  // runtime resolves the effective template per turn as
+  // per-session-override > per-workspace override > this default, substitutes
+  // the non-bypassable CORE at AGENT_INSTRUCTIONS_CORE_PLACEHOLDER (or appends
+  // it when the template omits the marker), and uses the result as the agent's
+  // instructions. Defaulting to DEFAULT_AGENT_INSTRUCTIONS keeps the composed
+  // default byte-identical to the historical hardcoded preamble.
+  agentInstructionsTemplate: z.string().default(DEFAULT_AGENT_INSTRUCTIONS),
+  azureOpenaiBaseUrl: z.string().optional(),
+  azureOpenaiEndpoint: z.string().optional(),
+  azureOpenaiDeployment: z.string().optional(),
+  azureOpenaiApiVersion: z.string().optional(),
+  azureOpenaiApiKey: z.string().optional(),
+  azureOpenaiAdToken: z.string().optional(),
+  disableOpenaiTracing: EnvBoolean.default(false),
+  sandboxBackend: SandboxBackend.default("docker"),
+  dockerImage: z.string().default("opengeni-sandbox:local"),
+  dockerExposedPorts: z.string().default(""),
+  dockerNetwork: z.string().optional(),
+  modalAppName: z.string().default("opengeni-sandbox"),
+  modalImageRef: z.string().optional(),
+  // Modal's hard sandbox lifetime (timeoutMs = this * 1000), counted from each
+  // create/resume — it is the BACKSTOP that reclaims a box if the reaper/worker is
+  // down, NOT the warm-window controller (that's sandboxIdleGraceMs). It must
+  // comfortably exceed reaperPeriod + idleGrace so the reaper terminates a
+  // genuinely-idle box FIRST; the boot invariant below enforces that. Default 1h
+  // (was 900s/15min): the 15-min drain grace counts from the user's LAST release,
+  // but Modal's clock starts at the preceding turn's resume — so a 15-min grace on
+  // top of a 900s lifetime would let Modal kill the box mid-warm-window. 3600s
+  // leaves ~45min of headroom for the active turn before the warm window opens.
+  // Knob: OPENGENI_MODAL_TIMEOUT_SECONDS.
+  modalTimeoutSeconds: z.coerce.number().int().positive().default(3600),
+  modalTokenId: z.string().optional(),
+  modalTokenSecret: z.string().optional(),
+  modalEnvironment: z.string().optional(),
+  // modal gap-fill: idleTimeoutMs + workspacePersistence were unmapped (module 03 §4.1).
+  //
+  // CRITICAL (sandbox-file-persistence): when this is UNSET the Modal SDK sends
+  // idleTimeoutSecs=undefined, so Modal applies its OWN short server-default idle
+  // timeout (~minutes) — and a box between turns sits with NO active connection,
+  // so that idle clock runs and Modal idle-reaps the box LONG before OpenGeni's
+  // own reaper waits out sandboxIdleGraceMs (15min) to resume+persist+terminate
+  // it. The observed failure: every drain logs "drainable box already gone
+  // (NotFound on resume)", persistWorkspace() never fires, /workspace is lost.
+  // Modal's idle-reap is a SECOND reaper racing OpenGeni's — and it wins. The fix:
+  // OpenGeni OWNS box lifecycle via its reaper + the hard modalTimeoutSeconds
+  // backstop, so the Modal idle-reap must NOT fire first. We default the effective
+  // idle timeout to the hard lifetime (effectiveModalIdleTimeoutSeconds), making
+  // the box survive its full warm window so the reaper can snapshot it. Set this
+  // explicitly (OPENGENI_MODAL_IDLE_TIMEOUT_SECONDS) only to deliberately idle-reap
+  // SOONER than the hard lifetime; the boot invariant forbids a value that would
+  // reap before reaperPeriod + idleGrace elapses.
+  modalIdleTimeoutSeconds: z.coerce.number().int().positive().optional(),
+  // /workspace FILE PERSISTENCE across warm/cold cycles. Defaults to
+  // `snapshot_filesystem` so EVERY box is created persistence-capable: the reaper
+  // snapshots the live box before it terminates a drained group, and a later
+  // cold-restore hydrates a fresh box from that snapshot (sandbox-file-persistence).
+  // `snapshot_filesystem` requires the manifest declare NO ephemeralPersistencePaths
+  // (buildManifest never sets entry.ephemeral, so it never downgrades to tar). Set
+  // OPENGENI_MODAL_WORKSPACE_PERSISTENCE=tar to opt back out (no native snapshot;
+  // the reaper persists a tar archive — same store+hydrate plumbing, slower).
+  modalWorkspacePersistence: z.enum(["tar", "snapshot_filesystem", "snapshot_directory"]).default("snapshot_filesystem"),
+  // Snapshot GC backstop (sandbox-file-persistence): the reaper keeps ONE latest
+  // filesystem snapshot per lease (delete-prior-on-supersede + delete-on-teardown).
+  // This is the TTL retention floor for the periodic orphan sweep — a snapshot
+  // whose lease is cold and older than this is best-effort deleted so a crashed
+  // persist-then-no-restore never leaks a Modal image. 0 disables the TTL sweep
+  // (delete-on-supersede/teardown still run). Default 7 days.
+  modalSnapshotRetentionSeconds: z.coerce.number().int().nonnegative().default(604800),
+  // Shared desktop toggle: this module reads it for the 6080 port-merge; the
+  // owner module (P4.x) acts on it to launch the display stack.
+  sandboxDesktopEnabled: EnvBoolean.default(false),
+  // Human take-control toggle: when ON (default) the negotiated DesktopStream
+  // cell advertises mode "interactive" — the noVNC viewer can drive mouse+keyboard
+  // into :0 (x11vnc runs without -viewonly). Turn it OFF for a genuinely read-only
+  // deployment: the cell reports mode "read-only" and the client disables the
+  // "Take control" affordance. Independent of computerUseReadOnly (the AGENT
+  // driver); this gates the HUMAN viewer plane.
+  sandboxDesktopInteractive: EnvBoolean.default(true),
+  // REAL PTY terminal toggle (P5.t): gates the ttyd pty-ws plane (7681) the API
+  // mints over the SAME tunnel as the desktop. Defaults ON — the interactive
+  // terminal is a baseline structured-service surface (unlike the heavier desktop
+  // pixel plane); a deployment can turn it off to fall back to the read-only
+  // sse-events command firehose. The 7681 port-merge tracks sandboxDesktopEnabled
+  // (a desktop-capable image is the one that bakes ttyd).
+  sandboxTerminalEnabled: EnvBoolean.default(true),
+  // The desktop framebuffer geometry the pixel plane advertises + launches the
+  // display stack with (P4.2). v1 has no live RANDR resize; a change is a full
+  // down→up restart. Defaults match the proven spike geometry (1280x800).
+  streamResolutionWidth: z.coerce.number().int().positive().default(1280),
+  streamResolutionHeight: z.coerce.number().int().positive().default(800),
+  // P4.3 computer-use: the agent drives the SAME :0 humans watch (xdotool/XTEST +
+  // scrot). Gated by sandboxDesktopEnabled + a desktop-capable backend in
+  // buildAgentCapabilities; computerUseReadOnly:false is the agent-driver default
+  // (it must click/type — the human viewer plane is the read-only one).
+  computerUseEnabled: EnvBoolean.default(true),
+  computerUseReadOnly: EnvBoolean.default(false),
+  // P4.3 recording loop: ffmpeg x11grab of :0 → mp4/webm → @opengeni/storage.
+  // recordingMaxBytes caps the in-memory finalize buffer (≤ storage single-PUT);
+  // recordingMaxSeconds is the ffmpeg -t hard ceiling (bounds a multi-day turn).
+  recordingEnabled: EnvBoolean.default(true),
+  recordingDefaultCodec: z.enum(["h264-mp4", "vp9-webm"]).default("h264-mp4"),
+  recordingFramerate: z.coerce.number().int().positive().default(15),
+  recordingMaxSeconds: z.coerce.number().int().positive().default(600),
+  recordingMaxBytes: z.coerce.number().int().positive().default(268435456),
+  // 256 MB
+  // --- daytona ---
+  daytonaApiKey: z.string().optional(),
+  daytonaApiUrl: z.string().url().optional(),
+  daytonaTarget: z.string().optional(),
+  daytonaImage: z.string().optional(),
+  daytonaSnapshotName: z.string().optional(),
+  daytonaAutoStopInterval: z.coerce.number().int().nonnegative().optional(),
+  // 0 disables idle-kill
+  daytonaTimeoutSeconds: z.coerce.number().int().positive().optional(),
+  daytonaExposedPortUrlTtlSeconds: z.coerce.number().int().positive().optional(),
+  // --- runloop ---
+  runloopApiKey: z.string().optional(),
+  runloopBaseUrl: z.string().url().optional(),
+  runloopBlueprintName: z.string().optional(),
+  runloopBlueprintId: z.string().optional(),
+  runloopTunnel: EnvBoolean.default(true),
+  runloopKeepAliveSeconds: z.coerce.number().int().positive().optional(),
+  // --- e2b (SDK reads E2B_API_KEY from env; mirrored for validation + forwarding) ---
+  e2bApiKey: z.string().optional(),
+  e2bTemplate: z.string().optional(),
+  e2bTimeoutSeconds: z.coerce.number().int().positive().optional(),
+  e2bTimeoutAction: z.enum(["pause", "kill"]).optional(),
+  e2bAllowInternetAccess: EnvBoolean.optional(),
+  e2bAutoResume: EnvBoolean.optional(),
+  e2bWorkspacePersistence: z.enum(["tar", "snapshot"]).optional(),
+  // --- blaxel ---
+  blaxelApiKey: z.string().optional(),
+  blaxelImage: z.string().optional(),
+  blaxelRegion: z.string().optional(),
+  blaxelExposedPortPublic: EnvBoolean.optional(),
+  // public vs bl_preview_token
+  blaxelExposedPortUrlTtlSeconds: z.coerce.number().int().positive().optional(),
+  blaxelMemoryMb: z.coerce.number().int().positive().optional(),
+  blaxelTtl: z.string().optional(),
+  // --- cloudflare (headless) ---
+  cloudflareWorkerUrl: z.string().url().optional(),
+  cloudflareApiKey: z.string().optional(),
+  // --- vercel (headless) ---
+  vercelToken: z.string().optional(),
+  vercelProjectId: z.string().optional(),
+  vercelTeamId: z.string().optional(),
+  vercelRuntime: z.string().optional(),
+  // --- sandbox ownership inversion (P1.2 rollout flag, default OFF) ---
+  // The keystone flag for the stateless resume-by-id model. When FALSE the
+  // agent-turn path is BYTE-FOR-BYTE today's build-and-discard behavior (no
+  // lease acquire, no resume-by-id, no non-owned injection). When TRUE the turn
+  // activity acquires the group lease, resumes the one box by id from the lease
+  // envelope, injects it as a NON-OWNED RunConfig session (the SDK never reaps
+  // it — the proven keystone), and releases the holder in finally. Uses
+  // EnvBoolean (NOT z.coerce.boolean(), which would coerce "false" -> true and
+  // turn the flag ON the moment anyone set the env var to disable it).
+  sandboxOwnershipEnabled: EnvBoolean.default(false),
+  // --- bring-your-own-compute (selfhosted 11th backend) rollout flag, default OFF ---
+  // The keystone flag for the whole selfhosted feature (the enrollment device-flow,
+  // the NATS control plane, the relay stream tier). When FALSE the enrollment routes
+  // 404 (invisible — the surface does not exist for this deployment) and the
+  // selfhosted backend is inert; boot is unaffected. EnvBoolean (NOT
+  // z.coerce.boolean(), which coerces "false" -> true). Flipped per-environment via
+  // the deploy-staging IaC secret/configmap pattern (dossier §17/§25.1).
+  sandboxSelfhostedEnabled: EnvBoolean.default(false),
+  // The HMAC secret the control plane signs the enrollment bearer credential with
+  // (the `oge_` envelope the agent presents back to the control plane). Optional:
+  // when ABSENT and sandboxSelfhostedEnabled is on, the poll route reports the
+  // credential plane disabled (graceful degrade, mirrors streamTokenSecret). NEVER
+  // logged. Lives in the opengeni-runtime secret (Helm-clobbered configmap avoided).
+  enrollmentSigningSecret: z.string().optional(),
+  // Connect-info the EnrollmentCredentials hand the agent: the NATS server URL(s)
+  // the agent dials for the control plane, and the relay edge base URL for streams.
+  // The per-workspace NATS Account creds binding is infra-deferred (M4/relay
+  // milestone) — the poll returns these endpoints + a placeholder creds field.
+  selfhostedNatsUrl: z.string().optional(),
+  selfhostedRelayUrl: z.string().optional(),
+  // The HMAC secret the control plane signs the agent's relay PRODUCER token with
+  // (the `ogr_` envelope threaded into EnrollmentCredentials.relayToken; M8b/dossier
+  // §10.5). The relay verifies the producer token with the SAME secret. Optional:
+  // when ABSENT the poll returns an empty relayToken (graceful degrade — the stream
+  // plane is simply unavailable until configured). Falls back to streamTokenSecret /
+  // delegationSecret (same HMAC family) so a deployment with a stream-token secret
+  // needs no second one. NEVER logged. Lives in the opengeni-runtime secret.
+  selfhostedRelayTokenSecret: z.string().optional(),
+  // The minisign PUBLIC key the agent pins for self-update verification (handed to
+  // the agent in EnrollmentCredentials; the SECRET key lives only in CI).
+  agentUpdatePublicKey: z.string().optional(),
+  // --- NATS auth-callout tenancy boundary (bring-your-own-compute M-AUTH; dossier
+  //     §10.1 NATS Accounts per workspace + §17 the isolation smoke) -------------
+  // nats-server is configured with AUTH CALLOUT: an external agent connects
+  // presenting its `oge_` enrollment bearer as the connect auth-token; the server
+  // issues an authorization request on $SYS.REQ.USER.AUTH to our responder, which
+  // validates the bearer and returns a SIGNED NATS user JWT scoped to pub/sub ONLY
+  // `agent.<ws>.>` (+ `_INBOX.>`). That per-subject scope IS the per-workspace
+  // isolation. These are deployment-level secrets in the opengeni-runtime secret
+  // (Helm-clobbered configmap avoided), all OPTIONAL: when the callout plane is not
+  // configured the responder simply does not start (selfhosted agents cannot
+  // connect — graceful, never a boot-fail).
+  //
+  // The callout account SIGNING SEED (`SA...`). Both the user JWT and the
+  // authorization-response JWT are signed by this account key; its public key
+  // (`A...`) is the `auth_callout.issuer` in the server config. NEVER logged.
+  selfhostedNatsCalloutAccountSeed: z.string().optional(),
+  // The TARGET ACCOUNT NAME the minted user is placed into (the server-config-mode
+  // `auth_callout.account`, e.g. "APP"). The responder writes it as the minted user
+  // JWT `aud` so nats-server binds the agent to this account — the SAME account the
+  // privileged control plane connects into, so `agent.<ws>.<id>.rpc` request/reply
+  // routes. Optional; resolveNatsCalloutConfig defaults it to "APP".
+  selfhostedNatsCalloutAccountName: z.string().optional(),
+  // The callout RESPONDER's own NATS login (one of the `auth_callout.auth_users`
+  // in the AUTH account) — the responder connects with this to subscribe
+  // $SYS.REQ.USER.AUTH. Username/password.
+  selfhostedNatsCalloutUser: z.string().optional(),
+  selfhostedNatsCalloutPassword: z.string().optional(),
+  // The PRIVILEGED control-plane login (api/worker): a static account user that may
+  // request `agent.*.rpc` + receive its inbox replies. The event bus + the
+  // selfhosted control RPC ride THIS connection. Username/password; when unset the
+  // bus connects anonymously (local dev / a NATS with no auth_callout).
+  selfhostedNatsControlUser: z.string().optional(),
+  selfhostedNatsControlPassword: z.string().optional(),
+  // --- sandbox lease cadences (cadence invariant validated at boot below) ---
+  // reaperPeriod < viewerHolderTTL, and reaperPeriod + idleGrace < the EFFECTIVE
+  // box idle timeout (effectiveModalIdleTimeoutSeconds, which defaults to the hard
+  // modalTimeoutSeconds). No keep-alive loop: between turns the box survives on its
+  // idle timeout — which we pin high enough (via the idle-timeout default) that
+  // OpenGeni's reaper, not Modal's idle-reap, governs teardown so /workspace is
+  // snapshotted before the box dies (sandbox-file-persistence).
+  sandboxLeaseReaperPeriodMs: z.coerce.number().int().positive().default(3e4),
+  sandboxViewerHolderTtlMs: z.coerce.number().int().positive().default(9e4),
+  // The DRAIN grace: how long a refcount-0 (draining) lease stays WARM before the
+  // reaper resume-by-ids the box and terminates it. This is the cost-vs-snappiness
+  // dial — when the user navigates away the box keeps refcount 0, but it survives
+  // this whole window so a "glanced away then came back" re-arms the SAME warm box
+  // (acquireLease re-arms draining->warm; the reaper's BEFORE-terminate re-read
+  // skips a re-armed box). Default 15min so a brief detour never cold-creates a
+  // fresh EMPTY box; lower it to trade warm cost for a snappier reclaim. Knob:
+  // OPENGENI_SANDBOX_IDLE_GRACE_MS.
+  sandboxIdleGraceMs: z.coerce.number().int().positive().default(9e5),
+  // expires_at refresh window for a held lease (>> the turn 10s heartbeat so a
+  // single missed heartbeat never TTL-reaps a live turn). The warming TTL is the
+  // window a cold->warming spawner has to commit warm before a reaper resets it.
+  sandboxLeaseTtlMs: z.coerce.number().int().positive().default(9e4),
+  sandboxLeaseWarmingTtlMs: z.coerce.number().int().positive().default(12e4),
+  // --- sandbox warm-time billing (P2.1) ---
+  // Per-backend warm rate (usd_micros/sec), like modelPricingJson: an empty {}
+  // means warm-cost is not debited (warm-seconds are still metered for audit).
+  // Shape: { "modal": 5, "runloop": 4, ... }. Backends absent here meter
+  // warm-seconds but accrue NO warm_cost / debit (rate 0).
+  sandboxWarmRateMicrosPerSecondJson: z.string().default("{}"),
+  // Per-workspace warm cap (cumulative warm-seconds since the start of the UTC
+  // month, summed over sandbox.warm_seconds). 0 = unbounded. A workspace over the
+  // cap force-drains its VIEWER-ONLY boxes (guarded AND turn_holders=0 — a paying
+  // turn is never killed); the reaper then stop()s at refcount 0.
+  sandboxMaxWarmSecondsPerWorkspace: z.coerce.number().int().nonnegative().default(0),
+  sandboxPreparationProfiles: z.string().default("none"),
+  sandboxEnvAllowlist: z.string().default(""),
+  objectStorageEndpoint: z.string().url().optional(),
+  objectStorageSandboxEndpoint: z.string().url().optional(),
+  objectStorageBackend: z.enum(["s3-compatible", "aws-s3", "azure-blob", "gcs"]).default("s3-compatible"),
+  objectStorageBucket: z.string().min(1).default("opengeni-files"),
+  objectStorageRegion: z.string().min(1).default("us-east-1"),
+  objectStorageS3Provider: z.string().min(1).default("Minio"),
+  objectStorageAccessKeyId: z.string().optional(),
+  objectStorageSecretAccessKey: z.string().optional(),
+  objectStorageForcePathStyle: EnvBoolean.default(true),
+  objectStorageAzureConnectionString: z.string().optional(),
+  objectStorageAzureAccountName: z.string().optional(),
+  objectStorageAzureAccountKey: z.string().optional(),
+  objectStorageAzureEndpoint: z.string().url().optional(),
+  objectStorageGcsProjectId: z.string().optional(),
+  objectStorageGcsCredentialsJson: z.string().optional(),
+  objectStorageGcsKeyFilename: z.string().optional(),
+  objectStorageGcsApiEndpoint: z.string().url().optional(),
+  documentParser: z.string().min(1).default("liteparse"),
+  documentChunkSize: z.coerce.number().int().positive().default(1200),
+  documentChunkOverlap: z.coerce.number().int().nonnegative().default(160),
+  documentEmbeddingProvider: z.enum(["openai", "deterministic"]).default("openai"),
+  documentEmbeddingModel: z.string().min(1).default("text-embedding-3-large"),
+  documentEmbeddingDimensions: z.coerce.number().int().positive().default(3072),
+  documentEmbeddingApiKey: z.string().optional(),
+  documentEmbeddingBaseUrl: z.string().url().optional(),
+  gitAuthorName: z.string().optional(),
+  gitAuthorEmail: z.string().optional(),
+  gitCommitterName: z.string().optional(),
+  gitCommitterEmail: z.string().optional(),
+  githubAppManifestBaseUrl: z.string().optional(),
+  githubAppManifestStateSecret: z.string().optional(),
+  githubAppId: z.string().optional(),
+  githubClientId: z.string().optional(),
+  githubClientSecret: z.string().optional(),
+  githubAppSlug: z.string().optional(),
+  githubWebhookSecret: z.string().optional(),
+  githubAppPrivateKey: z.string().optional(),
+  betterAuthSecret: z.string().optional(),
+  betterAuthAllowedHosts: z.string().default(""),
+  betterAuthCookieDomain: z.string().optional(),
+  betterAuthTrustedOrigins: z.string().default(""),
+  resendApiKey: z.string().optional(),
+  emailFrom: z.string().default("OpenGeni <auth@mail.opengeni.ai>"),
+  stripeSecretKey: z.string().optional(),
+  stripePublishableKey: z.string().optional(),
+  stripeWebhookSecret: z.string().optional(),
+  stripeCreditsProductId: z.string().optional(),
+  mcpServers: z.array(z.object({
+    id: z.string().min(1).regex(registryId),
+    name: z.string().min(1).optional(),
+    url: z.string().url(),
+    allowedTools: z.array(z.string().min(1)).optional(),
+    timeoutMs: z.number().int().positive().optional(),
+    cacheToolsList: z.boolean().default(false),
+    /**
+     * Extra request headers sent to this MCP server (credential injection
+     * for workspace-enabled capability MCPs). Populated at runtime from
+     * encrypted capability-installation credentials; do not put secrets in
+     * OPENGENI_MCP_SERVERS.
+     */
+    headers: z.record(z.string(), z.string()).optional()
+  })).default([])
+});
+var ModelPricingSchema = z.object({
+  inputMicrosPerMillionTokens: z.number().int().nonnegative(),
+  cachedInputMicrosPerMillionTokens: z.number().int().nonnegative().optional(),
+  outputMicrosPerMillionTokens: z.number().int().nonnegative(),
+  marginBps: z.number().int().min(0).max(1e5).optional()
+});
+var ModelProviderApi = z.enum(["responses", "chat"]);
+var RegistryProviderKind = z.enum(["api-key", "codex-subscription"]);
+var RegistryModelSchema = z.object({
+  id: z.string().min(1),
+  // model id sent to the provider, e.g. "accounts/fireworks/models/glm-5p2"
+  label: z.string().min(1).optional(),
+  // display name; defaults to id
+  contextWindowTokens: z.number().int().positive().optional(),
+  reasoningEffort: z.boolean().optional(),
+  // model accepts a reasoning-effort control
+  hostedWebSearch: z.boolean().optional(),
+  // provider executes the hosted web_search tool for this model
+  pricing: ModelPricingSchema.optional()
+});
+var RegistryProviderSchema = z.object({
+  kind: RegistryProviderKind.default("api-key"),
+  // "codex-subscription" => per-request token, no static key
+  id: z.string().min(1).regex(registryId),
+  // stable provider id, e.g. "fireworks"
+  label: z.string().min(1).optional(),
+  api: ModelProviderApi.default("chat"),
+  baseUrl: z.string().url(),
+  apiKey: z.string().optional(),
+  // inline key (pragmatic) ...
+  apiKeyEnv: z.string().optional(),
+  // ... OR name of the env var holding the key (preferred)
+  defaultQuery: z.record(z.string(), z.string()).optional(),
+  defaultHeaders: z.record(z.string(), z.string()).optional(),
+  models: z.array(RegistryModelSchema).min(1)
+});
+var defaultModelPricing = {
+  "gpt-5.5": {
+    inputMicrosPerMillionTokens: 5e6,
+    cachedInputMicrosPerMillionTokens: 5e5,
+    outputMicrosPerMillionTokens: 3e7,
+    marginBps: 2500
+  },
+  "gpt-5.4": {
+    inputMicrosPerMillionTokens: 25e5,
+    cachedInputMicrosPerMillionTokens: 25e4,
+    outputMicrosPerMillionTokens: 15e6,
+    marginBps: 2500
+  },
+  "gpt-5.4-mini": {
+    inputMicrosPerMillionTokens: 75e4,
+    cachedInputMicrosPerMillionTokens: 75e3,
+    outputMicrosPerMillionTokens: 45e5,
+    marginBps: 2500
+  },
+  "gpt-5.2": {
+    inputMicrosPerMillionTokens: 175e4,
+    cachedInputMicrosPerMillionTokens: 175e3,
+    outputMicrosPerMillionTokens: 14e6,
+    marginBps: 2500
+  },
+  "gpt-5.2-chat-latest": {
+    inputMicrosPerMillionTokens: 175e4,
+    cachedInputMicrosPerMillionTokens: 175e3,
+    outputMicrosPerMillionTokens: 14e6,
+    marginBps: 2500
+  },
+  "gpt-5.2-codex": {
+    inputMicrosPerMillionTokens: 175e4,
+    cachedInputMicrosPerMillionTokens: 175e3,
+    outputMicrosPerMillionTokens: 14e6,
+    marginBps: 2500
+  },
+  "gpt-5.1": {
+    inputMicrosPerMillionTokens: 125e4,
+    cachedInputMicrosPerMillionTokens: 125e3,
+    outputMicrosPerMillionTokens: 1e7,
+    marginBps: 2500
+  },
+  "gpt-5": {
+    inputMicrosPerMillionTokens: 125e4,
+    cachedInputMicrosPerMillionTokens: 125e3,
+    outputMicrosPerMillionTokens: 1e7,
+    marginBps: 2500
+  },
+  "gpt-5-mini": {
+    inputMicrosPerMillionTokens: 25e4,
+    cachedInputMicrosPerMillionTokens: 25e3,
+    outputMicrosPerMillionTokens: 2e6,
+    marginBps: 2500
+  },
+  "gpt-5-nano": {
+    inputMicrosPerMillionTokens: 5e4,
+    cachedInputMicrosPerMillionTokens: 5e3,
+    outputMicrosPerMillionTokens: 4e5,
+    marginBps: 2500
+  },
+  // Fireworks AI / GLM 5.2 — the first shipped non-OpenAI registry model. A
+  // built-in default pricing entry makes managed billing work out of the box
+  // for hosts that expose this model via OPENGENI_MODEL_PROVIDERS_JSON without
+  // also setting OPENGENI_MODEL_PRICING_JSON.
+  "accounts/fireworks/models/glm-5p2": {
+    inputMicrosPerMillionTokens: 14e5,
+    cachedInputMicrosPerMillionTokens: 26e4,
+    outputMicrosPerMillionTokens: 44e5,
+    marginBps: 2500
+  }
+};
+var SANDBOX_REQUIRED_ENV = {
+  // docker/local/none need no credentials (local dev container / in-process / off).
+  docker: [],
+  local: [],
+  none: [],
+  modal: [
+    { field: "modalAppName", env: "OPENGENI_MODAL_APP_NAME" },
+    { field: "modalTokenId", env: "OPENGENI_MODAL_TOKEN_ID" },
+    { field: "modalTokenSecret", env: "OPENGENI_MODAL_TOKEN_SECRET" }
+  ],
+  daytona: [
+    { field: "daytonaApiKey", env: "OPENGENI_DAYTONA_API_KEY" }
+  ],
+  runloop: [
+    { field: "runloopApiKey", env: "OPENGENI_RUNLOOP_API_KEY" }
+  ],
+  e2b: [
+    { field: "e2bApiKey", env: "OPENGENI_E2B_API_KEY" }
+  ],
+  blaxel: [
+    { field: "blaxelApiKey", env: "OPENGENI_BLAXEL_API_KEY" }
+  ],
+  cloudflare: [
+    { field: "cloudflareWorkerUrl", env: "OPENGENI_CLOUDFLARE_WORKER_URL" }
+  ],
+  vercel: [
+    { field: "vercelToken", env: "OPENGENI_VERCEL_TOKEN" },
+    { field: "vercelProjectId", env: "OPENGENI_VERCEL_PROJECT_ID" }
+  ],
+  // selfhosted needs NO per-box credentials: it is the user's own machine reached
+  // over the agent's own enrollment. The enrollment-signing + relay-token secrets
+  // are deployment-level (a single runtime secret, not per-active-backend creds),
+  // wired in the connectivity/enrollment milestones (M4/M5), not here.
+  selfhosted: []
+};
+function requiredSandboxEnvForBackend(backend) {
+  return (SANDBOX_REQUIRED_ENV[backend] ?? []).map((entry) => entry.env);
+}
+function optional(name) {
+  const value = process.env[name];
+  return value && value.trim().length > 0 ? value : void 0;
+}
+function getSettings() {
+  const raw = {
+    serviceName: optional("OPENGENI_SERVICE_NAME"),
+    environment: optional("OPENGENI_ENVIRONMENT"),
+    deploymentRevision: optional("OPENGENI_DEPLOYMENT_REVISION") ?? optional("SOURCE_VERSION") ?? optional("GITHUB_SHA"),
+    databaseUrl: optional("OPENGENI_DATABASE_URL"),
+    dbSchema: optional("OPENGENI_DB_SCHEMA"),
+    rlsStrategy: optional("OPENGENI_RLS_STRATEGY"),
+    natsUrl: optional("OPENGENI_NATS_URL"),
+    temporalHost: optional("OPENGENI_TEMPORAL_HOST"),
+    temporalNamespace: optional("OPENGENI_TEMPORAL_NAMESPACE"),
+    temporalTaskQueue: optional("OPENGENI_TEMPORAL_TASK_QUEUE"),
+    startupDependencyRetryAttempts: optional("OPENGENI_STARTUP_DEPENDENCY_RETRY_ATTEMPTS"),
+    startupDependencyRetryInitialDelayMs: optional("OPENGENI_STARTUP_DEPENDENCY_RETRY_INITIAL_DELAY_MS"),
+    startupDependencyRetryMaxDelayMs: optional("OPENGENI_STARTUP_DEPENDENCY_RETRY_MAX_DELAY_MS"),
+    observabilityStructuredLogs: optional("OPENGENI_OBSERVABILITY_STRUCTURED_LOGS"),
+    observabilityMetricsEnabled: optional("OPENGENI_OBSERVABILITY_METRICS_ENABLED"),
+    observabilityOtlpEndpoint: optional("OPENGENI_OTEL_EXPORTER_OTLP_ENDPOINT") ?? optional("OTEL_EXPORTER_OTLP_ENDPOINT"),
+    observabilityOtlpHeaders: optional("OPENGENI_OTEL_EXPORTER_OTLP_HEADERS") ?? optional("OTEL_EXPORTER_OTLP_HEADERS"),
+    publicBaseUrl: optional("OPENGENI_PUBLIC_BASE_URL"),
+    agentReleasesBaseUrl: optional("OPENGENI_AGENT_RELEASES_BASE_URL"),
+    productAccessMode: optional("OPENGENI_PRODUCT_ACCESS_MODE"),
+    billingMode: optional("OPENGENI_BILLING_MODE"),
+    entitlementsMode: optional("OPENGENI_ENTITLEMENTS_MODE"),
+    usageLimitsMode: optional("OPENGENI_USAGE_LIMITS_MODE"),
+    staticEntitlementsJson: optional("OPENGENI_STATIC_ENTITLEMENTS_JSON"),
+    staticUsageLimitsJson: optional("OPENGENI_STATIC_USAGE_LIMITS_JSON"),
+    delegationSecret: optional("OPENGENI_DELEGATION_SECRET"),
+    streamTokenSecret: optional("OPENGENI_STREAM_TOKEN_SECRET"),
+    streamControlEnabled: optional("OPENGENI_STREAM_CONTROL_ENABLED"),
+    environmentsEncryptionKey: optional("OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY"),
+    goalMaxAutoContinuations: optional("OPENGENI_GOAL_MAX_AUTO_CONTINUATIONS"),
+    goalNoProgressLimit: optional("OPENGENI_GOAL_NO_PROGRESS_LIMIT"),
+    agentMaxModelCallsPerTurn: optional("OPENGENI_AGENT_MAX_MODEL_CALLS_PER_TURN"),
+    sessionHistorySource: optional("OPENGENI_SESSION_HISTORY_SOURCE"),
+    contextCompactionMode: optional("OPENGENI_CONTEXT_COMPACTION_MODE"),
+    contextWindowTokens: optional("OPENGENI_CONTEXT_WINDOW_TOKENS"),
+    contextReservedOutputTokens: optional("OPENGENI_CONTEXT_RESERVED_OUTPUT_TOKENS"),
+    contextServerCompactThresholdTokens: optional("OPENGENI_CONTEXT_SERVER_COMPACT_THRESHOLD_TOKENS"),
+    contextCompactSoftFraction: optional("OPENGENI_CONTEXT_COMPACT_SOFT_FRACTION"),
+    contextCompactHardFraction: optional("OPENGENI_CONTEXT_COMPACT_HARD_FRACTION"),
+    contextKeepRecentTokens: optional("OPENGENI_CONTEXT_KEEP_RECENT_TOKENS"),
+    contextSummaryMaxTokens: optional("OPENGENI_CONTEXT_SUMMARY_MAX_TOKENS"),
+    authRequired: optional("OPENGENI_AUTH_REQUIRED"),
+    accessKey: optional("OPENGENI_ACCESS_KEY"),
+    authAllowHealth: optional("OPENGENI_AUTH_ALLOW_HEALTH"),
+    authAllowMetrics: optional("OPENGENI_AUTH_ALLOW_METRICS"),
+    apiHost: optional("OPENGENI_API_HOST"),
+    apiPort: optional("OPENGENI_API_PORT"),
+    opengeniMcpUrl: optional("OPENGENI_MCP_URL"),
+    corsAllowOriginRegex: optional("OPENGENI_CORS_ALLOW_ORIGIN_REGEX"),
+    openaiProvider: optional("OPENGENI_OPENAI_PROVIDER"),
+    openaiApiKey: optional("OPENGENI_OPENAI_API_KEY") ?? optional("OPENAI_API_KEY"),
+    openaiBaseUrl: optional("OPENGENI_OPENAI_BASE_URL") ?? optional("OPENAI_BASE_URL"),
+    openaiModel: optional("OPENGENI_OPENAI_MODEL"),
+    openaiAllowedModels: optional("OPENGENI_OPENAI_ALLOWED_MODELS"),
+    modelPricingJson: optional("OPENGENI_MODEL_PRICING_JSON"),
+    modelProvidersJson: optional("OPENGENI_MODEL_PROVIDERS_JSON"),
+    codexSubscriptionEnabled: optional("OPENGENI_CODEX_SUBSCRIPTION_ENABLED"),
+    codexToolSearchEnabled: optional("OPENGENI_CODEX_TOOL_SEARCH_ENABLED"),
+    codexProductSku: optional("OPENGENI_CODEX_PRODUCT_SKU"),
+    codexRotationNearExhaustionPct: optional("OPENGENI_CODEX_ROTATION_NEAR_EXHAUSTION_PCT"),
+    openaiReasoningEffort: optional("OPENGENI_OPENAI_REASONING_EFFORT"),
+    openaiAllowedReasoningEfforts: optional("OPENGENI_OPENAI_ALLOWED_REASONING_EFFORTS"),
+    openaiResponsesTransport: optional("OPENGENI_OPENAI_RESPONSES_TRANSPORT"),
+    openaiProviderItemIds: optional("OPENGENI_OPENAI_PROVIDER_ITEM_IDS"),
+    openaiReasoningEncryptedContent: optional("OPENGENI_OPENAI_REASONING_ENCRYPTED_CONTENT"),
+    openaiMaxRetries: optional("OPENGENI_OPENAI_MAX_RETRIES"),
+    webSearchEnabled: optional("OPENGENI_WEB_SEARCH_ENABLED"),
+    agentInstructionsTemplate: optional("OPENGENI_AGENT_INSTRUCTIONS_TEMPLATE"),
+    azureOpenaiBaseUrl: optional("OPENGENI_AZURE_OPENAI_BASE_URL"),
+    azureOpenaiEndpoint: optional("OPENGENI_AZURE_OPENAI_ENDPOINT"),
+    azureOpenaiDeployment: optional("OPENGENI_AZURE_OPENAI_DEPLOYMENT"),
+    azureOpenaiApiVersion: optional("OPENGENI_AZURE_OPENAI_API_VERSION"),
+    azureOpenaiApiKey: optional("OPENGENI_AZURE_OPENAI_API_KEY"),
+    azureOpenaiAdToken: optional("OPENGENI_AZURE_OPENAI_AD_TOKEN"),
+    disableOpenaiTracing: optional("OPENGENI_DISABLE_OPENAI_TRACING"),
+    sandboxBackend: optional("OPENGENI_SANDBOX_BACKEND"),
+    dockerImage: optional("OPENGENI_DOCKER_IMAGE"),
+    dockerExposedPorts: optional("OPENGENI_DOCKER_EXPOSED_PORTS"),
+    dockerNetwork: optional("OPENGENI_DOCKER_NETWORK"),
+    modalAppName: optional("OPENGENI_MODAL_APP_NAME"),
+    modalImageRef: optional("OPENGENI_MODAL_IMAGE_REF"),
+    modalTimeoutSeconds: optional("OPENGENI_MODAL_TIMEOUT_SECONDS"),
+    modalTokenId: optional("OPENGENI_MODAL_TOKEN_ID"),
+    modalTokenSecret: optional("OPENGENI_MODAL_TOKEN_SECRET"),
+    modalEnvironment: optional("OPENGENI_MODAL_ENVIRONMENT"),
+    modalIdleTimeoutSeconds: optional("OPENGENI_MODAL_IDLE_TIMEOUT_SECONDS"),
+    modalWorkspacePersistence: optional("OPENGENI_MODAL_WORKSPACE_PERSISTENCE"),
+    modalSnapshotRetentionSeconds: optional("OPENGENI_MODAL_SNAPSHOT_RETENTION_SECONDS"),
+    sandboxDesktopEnabled: optional("OPENGENI_SANDBOX_DESKTOP_ENABLED"),
+    sandboxDesktopInteractive: optional("OPENGENI_SANDBOX_DESKTOP_INTERACTIVE"),
+    sandboxTerminalEnabled: optional("OPENGENI_SANDBOX_TERMINAL_ENABLED"),
+    streamResolutionWidth: optional("OPENGENI_STREAM_RESOLUTION_WIDTH"),
+    streamResolutionHeight: optional("OPENGENI_STREAM_RESOLUTION_HEIGHT"),
+    computerUseEnabled: optional("OPENGENI_COMPUTER_USE_ENABLED"),
+    computerUseReadOnly: optional("OPENGENI_COMPUTER_USE_READONLY"),
+    recordingEnabled: optional("OPENGENI_RECORDING_ENABLED"),
+    recordingDefaultCodec: optional("OPENGENI_RECORDING_DEFAULT_CODEC"),
+    recordingFramerate: optional("OPENGENI_RECORDING_FRAMERATE"),
+    recordingMaxSeconds: optional("OPENGENI_RECORDING_MAX_SECONDS"),
+    recordingMaxBytes: optional("OPENGENI_RECORDING_MAX_BYTES"),
+    daytonaApiKey: optional("OPENGENI_DAYTONA_API_KEY"),
+    daytonaApiUrl: optional("OPENGENI_DAYTONA_API_URL"),
+    daytonaTarget: optional("OPENGENI_DAYTONA_TARGET"),
+    daytonaImage: optional("OPENGENI_DAYTONA_IMAGE"),
+    daytonaSnapshotName: optional("OPENGENI_DAYTONA_SNAPSHOT_NAME"),
+    daytonaAutoStopInterval: optional("OPENGENI_DAYTONA_AUTO_STOP_INTERVAL"),
+    daytonaTimeoutSeconds: optional("OPENGENI_DAYTONA_TIMEOUT_SECONDS"),
+    daytonaExposedPortUrlTtlSeconds: optional("OPENGENI_DAYTONA_EXPOSED_PORT_URL_TTL_SECONDS"),
+    runloopApiKey: optional("OPENGENI_RUNLOOP_API_KEY"),
+    runloopBaseUrl: optional("OPENGENI_RUNLOOP_BASE_URL"),
+    runloopBlueprintName: optional("OPENGENI_RUNLOOP_BLUEPRINT_NAME"),
+    runloopBlueprintId: optional("OPENGENI_RUNLOOP_BLUEPRINT_ID"),
+    runloopTunnel: optional("OPENGENI_RUNLOOP_TUNNEL"),
+    runloopKeepAliveSeconds: optional("OPENGENI_RUNLOOP_KEEP_ALIVE_SECONDS"),
+    e2bApiKey: optional("OPENGENI_E2B_API_KEY"),
+    e2bTemplate: optional("OPENGENI_E2B_TEMPLATE"),
+    e2bTimeoutSeconds: optional("OPENGENI_E2B_TIMEOUT_SECONDS"),
+    e2bTimeoutAction: optional("OPENGENI_E2B_TIMEOUT_ACTION"),
+    e2bAllowInternetAccess: optional("OPENGENI_E2B_ALLOW_INTERNET_ACCESS"),
+    e2bAutoResume: optional("OPENGENI_E2B_AUTO_RESUME"),
+    e2bWorkspacePersistence: optional("OPENGENI_E2B_WORKSPACE_PERSISTENCE"),
+    blaxelApiKey: optional("OPENGENI_BLAXEL_API_KEY"),
+    blaxelImage: optional("OPENGENI_BLAXEL_IMAGE"),
+    blaxelRegion: optional("OPENGENI_BLAXEL_REGION"),
+    blaxelExposedPortPublic: optional("OPENGENI_BLAXEL_EXPOSED_PORT_PUBLIC"),
+    blaxelExposedPortUrlTtlSeconds: optional("OPENGENI_BLAXEL_EXPOSED_PORT_URL_TTL_SECONDS"),
+    blaxelMemoryMb: optional("OPENGENI_BLAXEL_MEMORY_MB"),
+    blaxelTtl: optional("OPENGENI_BLAXEL_TTL"),
+    cloudflareWorkerUrl: optional("OPENGENI_CLOUDFLARE_WORKER_URL"),
+    cloudflareApiKey: optional("OPENGENI_CLOUDFLARE_API_KEY"),
+    vercelToken: optional("OPENGENI_VERCEL_TOKEN"),
+    vercelProjectId: optional("OPENGENI_VERCEL_PROJECT_ID"),
+    vercelTeamId: optional("OPENGENI_VERCEL_TEAM_ID"),
+    vercelRuntime: optional("OPENGENI_VERCEL_RUNTIME"),
+    sandboxOwnershipEnabled: optional("OPENGENI_SANDBOX_OWNERSHIP_ENABLED"),
+    sandboxSelfhostedEnabled: optional("OPENGENI_SANDBOX_SELFHOSTED_ENABLED"),
+    enrollmentSigningSecret: optional("OPENGENI_ENROLLMENT_SIGNING_SECRET"),
+    selfhostedNatsUrl: optional("OPENGENI_SELFHOSTED_NATS_URL"),
+    selfhostedRelayUrl: optional("OPENGENI_SELFHOSTED_RELAY_URL"),
+    selfhostedRelayTokenSecret: optional("OPENGENI_SELFHOSTED_RELAY_TOKEN_SECRET"),
+    agentUpdatePublicKey: optional("OPENGENI_AGENT_UPDATE_PUBLIC_KEY"),
+    selfhostedNatsCalloutAccountSeed: optional("OPENGENI_SELFHOSTED_NATS_CALLOUT_ACCOUNT_SEED"),
+    selfhostedNatsCalloutAccountName: optional("OPENGENI_SELFHOSTED_NATS_CALLOUT_ACCOUNT_NAME"),
+    selfhostedNatsCalloutUser: optional("OPENGENI_SELFHOSTED_NATS_CALLOUT_USER"),
+    selfhostedNatsCalloutPassword: optional("OPENGENI_SELFHOSTED_NATS_CALLOUT_PASSWORD"),
+    selfhostedNatsControlUser: optional("OPENGENI_SELFHOSTED_NATS_CONTROL_USER"),
+    selfhostedNatsControlPassword: optional("OPENGENI_SELFHOSTED_NATS_CONTROL_PASSWORD"),
+    sandboxLeaseReaperPeriodMs: optional("OPENGENI_SANDBOX_LEASE_REAPER_PERIOD_MS"),
+    sandboxViewerHolderTtlMs: optional("OPENGENI_SANDBOX_VIEWER_HOLDER_TTL_MS"),
+    sandboxIdleGraceMs: optional("OPENGENI_SANDBOX_IDLE_GRACE_MS"),
+    sandboxLeaseTtlMs: optional("OPENGENI_SANDBOX_LEASE_TTL_MS"),
+    sandboxLeaseWarmingTtlMs: optional("OPENGENI_SANDBOX_LEASE_WARMING_TTL_MS"),
+    sandboxWarmRateMicrosPerSecondJson: optional("OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON"),
+    sandboxMaxWarmSecondsPerWorkspace: optional("OPENGENI_SANDBOX_MAX_WARM_SECONDS_PER_WORKSPACE"),
+    sandboxPreparationProfiles: optional("OPENGENI_SANDBOX_PREPARATION_PROFILES"),
+    sandboxEnvAllowlist: optional("OPENGENI_SANDBOX_ENV_ALLOWLIST"),
+    objectStorageEndpoint: optional("OPENGENI_OBJECT_STORAGE_ENDPOINT"),
+    objectStorageSandboxEndpoint: optional("OPENGENI_OBJECT_STORAGE_SANDBOX_ENDPOINT"),
+    objectStorageBackend: optional("OPENGENI_OBJECT_STORAGE_BACKEND"),
+    objectStorageBucket: optional("OPENGENI_OBJECT_STORAGE_BUCKET"),
+    objectStorageRegion: optional("OPENGENI_OBJECT_STORAGE_REGION"),
+    objectStorageS3Provider: optional("OPENGENI_OBJECT_STORAGE_S3_PROVIDER"),
+    objectStorageAccessKeyId: optional("OPENGENI_OBJECT_STORAGE_ACCESS_KEY_ID"),
+    objectStorageSecretAccessKey: optional("OPENGENI_OBJECT_STORAGE_SECRET_ACCESS_KEY"),
+    objectStorageForcePathStyle: optional("OPENGENI_OBJECT_STORAGE_FORCE_PATH_STYLE"),
+    objectStorageAzureConnectionString: optional("OPENGENI_OBJECT_STORAGE_AZURE_CONNECTION_STRING"),
+    objectStorageAzureAccountName: optional("OPENGENI_OBJECT_STORAGE_AZURE_ACCOUNT_NAME"),
+    objectStorageAzureAccountKey: optional("OPENGENI_OBJECT_STORAGE_AZURE_ACCOUNT_KEY"),
+    objectStorageAzureEndpoint: optional("OPENGENI_OBJECT_STORAGE_AZURE_ENDPOINT"),
+    objectStorageGcsProjectId: optional("OPENGENI_OBJECT_STORAGE_GCS_PROJECT_ID"),
+    objectStorageGcsCredentialsJson: optional("OPENGENI_OBJECT_STORAGE_GCS_CREDENTIALS_JSON"),
+    objectStorageGcsKeyFilename: optional("OPENGENI_OBJECT_STORAGE_GCS_KEY_FILENAME"),
+    objectStorageGcsApiEndpoint: optional("OPENGENI_OBJECT_STORAGE_GCS_API_ENDPOINT"),
+    documentParser: optional("OPENGENI_DOCUMENT_PARSER"),
+    documentChunkSize: optional("OPENGENI_DOCUMENT_CHUNK_SIZE"),
+    documentChunkOverlap: optional("OPENGENI_DOCUMENT_CHUNK_OVERLAP"),
+    documentEmbeddingProvider: optional("OPENGENI_DOCUMENT_EMBEDDING_PROVIDER"),
+    documentEmbeddingModel: optional("OPENGENI_DOCUMENT_EMBEDDING_MODEL"),
+    documentEmbeddingDimensions: optional("OPENGENI_DOCUMENT_EMBEDDING_DIMENSIONS"),
+    documentEmbeddingApiKey: optional("OPENGENI_DOCUMENT_EMBEDDING_API_KEY"),
+    documentEmbeddingBaseUrl: optional("OPENGENI_DOCUMENT_EMBEDDING_BASE_URL"),
+    gitAuthorName: optional("OPENGENI_GIT_AUTHOR_NAME"),
+    gitAuthorEmail: optional("OPENGENI_GIT_AUTHOR_EMAIL"),
+    gitCommitterName: optional("OPENGENI_GIT_COMMITTER_NAME"),
+    gitCommitterEmail: optional("OPENGENI_GIT_COMMITTER_EMAIL"),
+    githubAppManifestBaseUrl: optional("OPENGENI_GITHUB_APP_MANIFEST_BASE_URL"),
+    githubAppManifestStateSecret: optional("OPENGENI_GITHUB_APP_MANIFEST_STATE_SECRET"),
+    githubAppId: optional("OPENGENI_GITHUB_APP_ID"),
+    githubClientId: optional("OPENGENI_GITHUB_CLIENT_ID"),
+    githubClientSecret: optional("OPENGENI_GITHUB_CLIENT_SECRET"),
+    githubAppSlug: optional("OPENGENI_GITHUB_APP_SLUG"),
+    githubWebhookSecret: optional("OPENGENI_GITHUB_WEBHOOK_SECRET"),
+    githubAppPrivateKey: optional("OPENGENI_GITHUB_APP_PRIVATE_KEY"),
+    betterAuthSecret: optional("OPENGENI_BETTER_AUTH_SECRET"),
+    betterAuthAllowedHosts: optional("OPENGENI_BETTER_AUTH_ALLOWED_HOSTS"),
+    betterAuthCookieDomain: optional("OPENGENI_BETTER_AUTH_COOKIE_DOMAIN"),
+    betterAuthTrustedOrigins: optional("OPENGENI_BETTER_AUTH_TRUSTED_ORIGINS"),
+    resendApiKey: optional("OPENGENI_RESEND_API_KEY"),
+    emailFrom: optional("OPENGENI_EMAIL_FROM"),
+    stripeSecretKey: optional("OPENGENI_STRIPE_SECRET_KEY"),
+    stripePublishableKey: optional("OPENGENI_STRIPE_PUBLISHABLE_KEY"),
+    stripeWebhookSecret: optional("OPENGENI_STRIPE_WEBHOOK_SECRET"),
+    stripeCreditsProductId: optional("OPENGENI_STRIPE_CREDITS_PRODUCT_ID"),
+    mcpServers: parseMcpServers(optional("OPENGENI_MCP_SERVERS"))
+  };
+  const parsed = SettingsSchema.parse(raw);
+  const settings = {
+    ...parsed,
+    mcpServers: ensureBuiltInMcpServers(parsed)
+  };
+  validateSettings(settings);
+  return settings;
+}
+function effectiveModalIdleTimeoutSeconds(settings) {
+  return settings.modalIdleTimeoutSeconds ?? settings.modalTimeoutSeconds;
+}
+function collectSandboxEnvironment(settings, source = process.env) {
+  const out = {};
+  for (const name of sandboxEnvironmentVariableNames(settings)) {
+    const value = source[name];
+    if (value) {
+      out[name] = value;
+    }
+  }
+  return out;
+}
+function resolveProviderApiKey(provider, source = process.env) {
+  if (provider.apiKey) {
+    return provider.apiKey;
+  }
+  if (provider.apiKeyEnv) {
+    const value = source[provider.apiKeyEnv];
+    return value && value.trim().length > 0 ? value : void 0;
+  }
+  return void 0;
+}
+function builtinProviderId(settings) {
+  return settings.openaiProvider === "azure" ? "azure" : "openai";
+}
+function builtinProviderLabel(settings) {
+  return settings.openaiProvider === "azure" ? "Azure OpenAI" : "OpenAI";
+}
+function configuredProviders(settings) {
+  const builtin = {
+    id: builtinProviderId(settings),
+    label: builtinProviderLabel(settings),
+    kind: "api-key",
+    api: "responses",
+    builtin: true,
+    compactionMode: resolveContextCompactionMode(settings)
+  };
+  if (settings.openaiProvider === "azure") {
+    builtin.baseUrl = settings.azureOpenaiBaseUrl ?? settings.azureOpenaiEndpoint;
+    builtin.apiKey = settings.azureOpenaiApiKey ?? settings.azureOpenaiAdToken;
+  } else {
+    builtin.baseUrl = settings.openaiBaseUrl;
+    builtin.apiKey = settings.openaiApiKey;
+  }
+  const registry = parseModelProvidersJson(settings.modelProvidersJson).map((provider) => ({
+    id: provider.id,
+    label: provider.label ?? provider.id,
+    kind: provider.kind,
+    api: provider.api,
+    builtin: false,
+    baseUrl: provider.baseUrl,
+    apiKey: resolveProviderApiKey(provider),
+    defaultQuery: provider.defaultQuery,
+    defaultHeaders: provider.defaultHeaders,
+    compactionMode: "client"
+  }));
+  return [builtin, ...registry];
+}
+function configuredModels(settings) {
+  const builtinId = builtinProviderId(settings);
+  const builtinLabel = builtinProviderLabel(settings);
+  const registryOwnedIds = new Set(
+    parseModelProvidersJson(settings.modelProvidersJson).flatMap((provider) => provider.models.map((model) => model.id))
+  );
+  const isRegistryNamespaced = (id) => id.startsWith(CODEX_MODEL_ID_PREFIX) || id.includes("/") && registryOwnedIds.has(id);
+  const out = uniqueValues([settings.openaiModel, ...splitCsv(settings.openaiAllowedModels)]).filter((id) => !isRegistryNamespaced(id)).map((id) => ({
+    id,
+    label: id,
+    providerId: builtinId,
+    providerLabel: builtinLabel,
+    api: "responses",
+    contextWindowTokens: settings.contextWindowTokens,
+    reasoningEffort: true,
+    hostedWebSearch: settings.webSearchEnabled
+  }));
+  for (const provider of parseModelProvidersJson(settings.modelProvidersJson)) {
+    const providerLabel = provider.label ?? provider.id;
+    for (const model of provider.models) {
+      out.push({
+        id: model.id,
+        label: model.label ?? model.id,
+        providerId: provider.id,
+        providerLabel,
+        api: provider.api,
+        ...model.contextWindowTokens === void 0 ? {} : { contextWindowTokens: model.contextWindowTokens },
+        reasoningEffort: model.reasoningEffort ?? false,
+        hostedWebSearch: model.hostedWebSearch ?? false
+      });
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return out.filter((model) => {
+    if (seen.has(model.id)) {
+      return false;
+    }
+    seen.add(model.id);
+    return true;
+  });
+}
+function configuredAllowedModels(settings) {
+  return configuredModels(settings).map((model) => model.id);
+}
+function resolveModelProvider(settings, modelId) {
+  const model = configuredModels(settings).find((candidate) => candidate.id === modelId);
+  if (!model) {
+    return void 0;
+  }
+  const provider = configuredProviders(settings).find((candidate) => candidate.id === model.providerId);
+  if (!provider) {
+    return void 0;
+  }
+  return { provider, model };
+}
+function configuredModelPricing(settings) {
+  const registry = {};
+  for (const provider of parseModelProvidersJson(settings.modelProvidersJson)) {
+    for (const model of provider.models) {
+      if (model.pricing) {
+        registry[model.id] = model.pricing;
+      }
+    }
+  }
+  const configured = parseModelPricingJson(settings.modelPricingJson);
+  return {
+    ...defaultModelPricing,
+    ...registry,
+    ...configured
+  };
+}
+function resolveContextCompactionMode(settings) {
+  switch (settings.contextCompactionMode) {
+    case "server":
+      return "server";
+    case "client":
+      return "client";
+    case "off":
+      return "off";
+    case "auto":
+    default:
+      return settings.openaiProvider === "openai" ? "server" : "client";
+  }
+}
+function contextInputBudgetTokens(settings) {
+  return Math.max(0, settings.contextWindowTokens - settings.contextReservedOutputTokens);
+}
+function contextServerCompactThreshold(settings) {
+  if (settings.contextServerCompactThresholdTokens) {
+    return settings.contextServerCompactThresholdTokens;
+  }
+  return Math.floor(contextInputBudgetTokens(settings) * settings.contextCompactSoftFraction);
+}
+function configuredStaticUsageLimits(settings) {
+  return parseStaticUsageLimitsJson(settings.staticUsageLimitsJson);
+}
+function configuredEntitlements(settings) {
+  if (settings.entitlementsMode === "none") {
+    return {};
+  }
+  const configured = parseStaticEntitlementsJson(settings.staticEntitlementsJson);
+  if (settings.entitlementsMode === "static") {
+    return configured;
+  }
+  return {
+    "managed.auth.email_password": true,
+    "managed.billing.prepaid_credits": settings.billingMode === "stripe",
+    "managed.api_keys": true,
+    "managed.workspaces": true,
+    "managed.github_app": Boolean(settings.githubAppId && settings.githubAppPrivateKey),
+    ...configured
+  };
+}
+function calculateModelUsageCostMicros(settings, model, usage) {
+  const pricing = configuredModelPricing(settings)[model];
+  if (!pricing) {
+    throw new Error(`Missing model pricing for ${model}`);
+  }
+  const entries = usage.requestUsageEntries && usage.requestUsageEntries.length > 0 ? usage.requestUsageEntries : [usage];
+  const rawCost = entries.reduce((sum, entry) => sum + calculateEntryCostMicros(pricing, entry), 0);
+  const marginBps = pricing.marginBps ?? 0;
+  return Math.ceil(rawCost * (1e4 + marginBps) / 1e4);
+}
+function configuredAllowedReasoningEfforts(settings) {
+  return uniqueValues([settings.openaiReasoningEffort, ...splitCsv(settings.openaiAllowedReasoningEfforts)]).map((value) => ReasoningEffort.parse(value));
+}
+function environmentsEncryptionKeyBytes(settings) {
+  if (!settings.environmentsEncryptionKey) {
+    return null;
+  }
+  const decoded = Buffer.from(settings.environmentsEncryptionKey, "base64");
+  if (decoded.length !== 32) {
+    throw new Error("OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY must be base64 for exactly 32 bytes (generate with: openssl rand -base64 32)");
+  }
+  return new Uint8Array(decoded);
+}
+function dbSearchPath(settings) {
+  const schema = settings.dbSchema?.trim();
+  if (!schema) {
+    return void 0;
+  }
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(schema)) {
+    throw new Error(`OPENGENI_DB_SCHEMA is not a valid Postgres identifier: ${schema}`);
+  }
+  return `${schema},opengeni_private,public`;
+}
+function collectGitIdentityEnvironment(settings) {
+  return Object.fromEntries(Object.entries({
+    GIT_AUTHOR_NAME: settings.gitAuthorName,
+    GIT_AUTHOR_EMAIL: settings.gitAuthorEmail,
+    GIT_COMMITTER_NAME: settings.gitCommitterName ?? settings.gitAuthorName,
+    GIT_COMMITTER_EMAIL: settings.gitCommitterEmail ?? settings.gitAuthorEmail
+  }).filter((entry) => typeof entry[1] === "string" && entry[1].trim().length > 0));
+}
+function stableSandboxEnvironmentForRun(settings, workspaceEnvironment = {}) {
+  const environment = {
+    ...collectSandboxEnvironment(settings),
+    ...collectGitIdentityEnvironment(settings),
+    ...workspaceEnvironment
+  };
+  const descriptor = CAPABILITY_DESCRIPTORS[settings.sandboxBackend];
+  if (settings.sandboxBackend !== "none" && settings.sandboxBackend !== "local") {
+    environment.HOME ??= descriptor.workspaceRoot;
+  }
+  environment.OPENGENI_GIT_TOKEN_FILE ??= `${environment.HOME ?? descriptor.workspaceRoot}/.opengeni/git-token`;
+  return environment;
+}
+function hasGitHubRepositorySelection(resources) {
+  const positive = (value) => typeof value === "number" && Number.isInteger(value) && value > 0 || typeof value === "string" && /^\d+$/.test(value) && Number(value) > 0;
+  return resources.some((resource) => resource.kind === "repository" && positive(resource.githubInstallationId) && positive(resource.githubRepositoryId));
+}
+function applyGitAuthPointerEnvironment(environment, identity) {
+  environment.GIT_ASKPASS = `${environment.HOME ?? "/workspace"}/.opengeni/askpass`;
+  environment.GIT_TERMINAL_PROMPT = "0";
+  if (identity) {
+    environment.GIT_AUTHOR_NAME = environment.GIT_AUTHOR_NAME || identity.name;
+    environment.GIT_AUTHOR_EMAIL = environment.GIT_AUTHOR_EMAIL || identity.email;
+    environment.GIT_COMMITTER_NAME = environment.GIT_COMMITTER_NAME || identity.name;
+    environment.GIT_COMMITTER_EMAIL = environment.GIT_COMMITTER_EMAIL || identity.email;
+  }
+  return environment;
+}
+function startupRetryOptions(settings) {
+  return {
+    attempts: settings.startupDependencyRetryAttempts,
+    initialDelayMs: settings.startupDependencyRetryInitialDelayMs,
+    maxDelayMs: settings.startupDependencyRetryMaxDelayMs
+  };
+}
+async function retryStartupDependency(label, operation, options = {}) {
+  const attempts = Math.max(1, Math.floor(options.attempts ?? 30));
+  const initialDelayMs = Math.max(0, Math.floor(options.initialDelayMs ?? 1e3));
+  const maxDelayMs = Math.max(initialDelayMs, Math.floor(options.maxDelayMs ?? 5e3));
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (attempt >= attempts) {
+        throw error;
+      }
+      const delayMs = Math.min(maxDelayMs, initialDelayMs * 2 ** (attempt - 1));
+      options.onRetry?.({ label, attempt, attempts, delayMs, error });
+      await delay(delayMs);
+    }
+  }
+  throw new Error(`unreachable startup retry state for ${label}`);
+}
+function sandboxEnvironmentVariableNames(settings) {
+  const profiles = sandboxPreparationProfileNames(settings);
+  const names = [];
+  for (const profile of profiles) {
+    names.push(...sandboxPreparationProfiles[profile].env);
+  }
+  names.push(...splitCsv(settings.sandboxEnvAllowlist));
+  return uniqueEnvNames(names, "sandbox env");
+}
+function sandboxLifecycleHookIds(settings) {
+  const ids = [];
+  for (const profile of sandboxPreparationProfileNames(settings)) {
+    ids.push(...sandboxPreparationProfiles[profile].hooks);
+  }
+  return uniqueValues(ids);
+}
+function sandboxPreparationProfileNames(settings) {
+  const profiles = splitCsv(settings.sandboxPreparationProfiles).map((value) => value.toLowerCase());
+  if (profiles.includes("none")) {
+    if (profiles.length > 1) {
+      throw new Error("OPENGENI_SANDBOX_PREPARATION_PROFILES cannot combine none with other profiles");
+    }
+    return ["none"];
+  }
+  for (const profile of profiles) {
+    if (!sandboxPreparationProfiles[profile]) {
+      throw new Error(`Unknown sandbox preparation profile ${profile}`);
+    }
+  }
+  return profiles;
+}
+function parseExposedPorts(raw) {
+  return splitCsv(raw).map((value) => {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new Error("OPENGENI_DOCKER_EXPOSED_PORTS must contain TCP port numbers");
+    }
+    return port;
+  });
+}
+function parseMcpServers(raw) {
+  if (!raw) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+      throw new Error("value must be a JSON array");
+    }
+    return parsed;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`OPENGENI_MCP_SERVERS must be a JSON array: ${message}`);
+  }
+}
+function parseModelPricingJson(raw) {
+  if (!raw.trim() || raw.trim() === "{}") {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`OPENGENI_MODEL_PRICING_JSON must be valid JSON: ${message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("OPENGENI_MODEL_PRICING_JSON must be a JSON object keyed by model name");
+  }
+  const out = {};
+  for (const [model, value] of Object.entries(parsed)) {
+    if (!model.trim()) {
+      throw new Error("OPENGENI_MODEL_PRICING_JSON contains an empty model name");
+    }
+    out[model] = ModelPricingSchema.parse(value);
+  }
+  return out;
+}
+function parseSandboxWarmRateJson(raw) {
+  if (!raw.trim() || raw.trim() === "{}") {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON must be valid JSON: ${message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON must be a JSON object keyed by backend name");
+  }
+  const out = {};
+  for (const [backend, value] of Object.entries(parsed)) {
+    if (!backend.trim()) {
+      throw new Error("OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON contains an empty backend name");
+    }
+    const rate = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(rate) || rate < 0) {
+      throw new Error(`OPENGENI_SANDBOX_WARM_RATE_MICROS_PER_SECOND_JSON rate for ${backend} must be a non-negative number`);
+    }
+    out[backend] = rate;
+  }
+  return out;
+}
+function sandboxWarmRateMicrosPerSecond(settings, backend) {
+  const table = parseSandboxWarmRateJson(settings.sandboxWarmRateMicrosPerSecondJson);
+  return table[backend] ?? 0;
+}
+function parseModelProvidersJson(raw) {
+  if (!raw.trim() || raw.trim() === "[]") {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`OPENGENI_MODEL_PROVIDERS_JSON must be valid JSON: ${message}`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error("OPENGENI_MODEL_PROVIDERS_JSON must be a JSON array of providers");
+  }
+  return parsed.map((entry, index) => {
+    const result = RegistryProviderSchema.safeParse(entry);
+    if (!result.success) {
+      throw new Error(`OPENGENI_MODEL_PROVIDERS_JSON provider[${index}] is invalid: ${result.error.message}`);
+    }
+    return result.data;
+  });
+}
+function parseStaticUsageLimitsJson(raw) {
+  if (!raw.trim() || raw.trim() === "{}") {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`OPENGENI_STATIC_USAGE_LIMITS_JSON must be valid JSON: ${message}`);
+  }
+  return StaticUsageLimits.parse(parsed);
+}
+function parseStaticEntitlementsJson(raw) {
+  if (!raw.trim() || raw.trim() === "{}") {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`OPENGENI_STATIC_ENTITLEMENTS_JSON must be valid JSON: ${message}`);
+  }
+  return Entitlements.parse(parsed);
+}
+function calculateEntryCostMicros(pricing, entry) {
+  const inputTokens = positiveInt(entry.inputTokens);
+  const outputTokens = positiveInt(entry.outputTokens);
+  const cachedTokens = Math.min(inputTokens, cachedInputTokens(entry));
+  const uncachedInputTokens = Math.max(0, inputTokens - cachedTokens);
+  const cachedInputRate = pricing.cachedInputMicrosPerMillionTokens ?? pricing.inputMicrosPerMillionTokens;
+  return Math.ceil(uncachedInputTokens * pricing.inputMicrosPerMillionTokens / 1e6) + Math.ceil(cachedTokens * cachedInputRate / 1e6) + Math.ceil(outputTokens * pricing.outputMicrosPerMillionTokens / 1e6);
+}
+function cachedInputTokens(entry) {
+  const details = Array.isArray(entry.inputTokensDetails) ? entry.inputTokensDetails : entry.inputTokensDetails ? [entry.inputTokensDetails] : [];
+  let total = 0;
+  for (const detail of details) {
+    total += positiveInt(detail.cached_tokens) + positiveInt(detail.cachedInputTokens) + positiveInt(detail.cached_input_tokens);
+  }
+  return total;
+}
+function positiveInt(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+function ensureBuiltInMcpServers(settings) {
+  const existing = settings.mcpServers.filter((server) => server.id !== "opengeni");
+  const firstPartyMcpUrl = firstPartyMcpServerUrl(settings);
+  const firstPartyDocsMcpUrl = firstPartyDocumentsMcpServerUrl(firstPartyMcpUrl);
+  const hasFiles = existing.some((server) => server.id === "files");
+  const hasDocs = existing.some((server) => server.id === "docs");
+  return [
+    {
+      id: "opengeni",
+      name: "OpenGeni",
+      url: firstPartyMcpUrl,
+      // The opengeni server's tools/list response is permission-scoped: it
+      // varies by the calling session's delegated grant (e.g. a manager
+      // session sees sessions_*/environment_* tools that a worker session
+      // does not). The OpenAI Agents SDK caches tools/list in a process-global
+      // map keyed only by the MCP server name, which is identical for every
+      // session in the worker process. Caching here would let the first
+      // session to warm the cache dictate what every later session sees,
+      // regardless of permissions. tools/list is a cheap per-turn call, so we
+      // never cache it. (The files server pins allowedTools to a single
+      // permission-invariant tool and docs is already uncached, so both stay
+      // safe to cache / leave as-is.)
+      cacheToolsList: false
+    },
+    ...hasFiles ? [] : [{
+      id: "files",
+      name: "Files",
+      url: firstPartyMcpUrl,
+      allowedTools: ["files_get_download_url"],
+      cacheToolsList: true
+    }],
+    ...hasDocs ? [] : [{
+      id: "docs",
+      name: "Document Search",
+      url: firstPartyDocsMcpUrl,
+      allowedTools: ["search_documents", "fetch_document_chunk", "list_document_bases"],
+      cacheToolsList: false
+    }],
+    ...existing
+  ];
+}
+function firstPartyMcpBaseUrl(settings) {
+  return settings.opengeniMcpUrl ?? `http://127.0.0.1:${settings.apiPort}/v1/workspaces/{workspaceId}/mcp`;
+}
+function firstPartyMcpServerUrl(settings) {
+  return firstPartyMcpBaseUrl(settings);
+}
+function firstPartyDocumentsMcpServerUrl(mcpUrl) {
+  return `${mcpUrl.replace(/\/+$/, "")}/docs`;
+}
+function validateSettings(settings) {
+  if (settings.productAccessMode === "managed") {
+    if (!settings.publicBaseUrl) {
+      throw new Error("OPENGENI_PUBLIC_BASE_URL is required when OPENGENI_PRODUCT_ACCESS_MODE=managed");
+    }
+    if (!settings.betterAuthSecret) {
+      throw new Error("OPENGENI_BETTER_AUTH_SECRET is required when OPENGENI_PRODUCT_ACCESS_MODE=managed");
+    }
+    if (!settings.delegationSecret) {
+      throw new Error("OPENGENI_DELEGATION_SECRET is required when OPENGENI_PRODUCT_ACCESS_MODE=managed");
+    }
+    if (!["local", "test"].includes(settings.environment) && !settings.resendApiKey) {
+      throw new Error("OPENGENI_RESEND_API_KEY is required for managed mode outside local/test");
+    }
+    if (!["local", "test"].includes(settings.environment) && !settings.environmentsEncryptionKey) {
+      throw new Error("OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY is required for managed mode outside local/test");
+    }
+  }
+  environmentsEncryptionKeyBytes(settings);
+  if (settings.productAccessMode === "configured" && !["local", "test"].includes(settings.environment) && !settings.delegationSecret && !settings.authRequired) {
+    throw new Error("OPENGENI_PRODUCT_ACCESS_MODE=configured requires OPENGENI_DELEGATION_SECRET or OPENGENI_AUTH_REQUIRED=true outside local/test");
+  }
+  if (settings.billingMode === "stripe") {
+    if (!settings.stripeSecretKey || !settings.stripeWebhookSecret) {
+      throw new Error("OPENGENI_STRIPE_SECRET_KEY and OPENGENI_STRIPE_WEBHOOK_SECRET are required when OPENGENI_BILLING_MODE=stripe");
+    }
+  }
+  if (settings.productAccessMode !== "managed" && settings.billingMode === "stripe") {
+    throw new Error("OPENGENI_BILLING_MODE=stripe requires OPENGENI_PRODUCT_ACCESS_MODE=managed");
+  }
+  if (settings.billingMode === "stripe" || settings.usageLimitsMode === "managed") {
+    const pricing = configuredModelPricing(settings);
+    const missing = configuredAllowedModels(settings).filter((model) => !pricing[model]);
+    if (missing.length > 0) {
+      throw new Error(`Missing model pricing for managed billing model(s): ${missing.join(", ")}. Set OPENGENI_MODEL_PRICING_JSON.`);
+    }
+  }
+  if (settings.usageLimitsMode === "static") {
+    const limits = configuredStaticUsageLimits(settings);
+    if (Object.keys(limits).length === 0) {
+      throw new Error("OPENGENI_STATIC_USAGE_LIMITS_JSON must define at least one cap when OPENGENI_USAGE_LIMITS_MODE=static");
+    }
+  } else {
+    parseStaticUsageLimitsJson(settings.staticUsageLimitsJson);
+  }
+  if (settings.entitlementsMode === "static") {
+    const entitlements = parseStaticEntitlementsJson(settings.staticEntitlementsJson);
+    if (Object.keys(entitlements).length === 0) {
+      throw new Error("OPENGENI_STATIC_ENTITLEMENTS_JSON must define at least one feature when OPENGENI_ENTITLEMENTS_MODE=static");
+    }
+  } else {
+    parseStaticEntitlementsJson(settings.staticEntitlementsJson);
+  }
+  if (settings.authRequired && !settings.accessKey) {
+    throw new Error("OPENGENI_ACCESS_KEY is required when OPENGENI_AUTH_REQUIRED=true");
+  }
+  if (settings.openaiProvider === "azure") {
+    if (!settings.azureOpenaiBaseUrl && !settings.azureOpenaiEndpoint) {
+      throw new Error("Azure OpenAI requires OPENGENI_AZURE_OPENAI_BASE_URL or OPENGENI_AZURE_OPENAI_ENDPOINT");
+    }
+    if (!settings.azureOpenaiBaseUrl && !settings.azureOpenaiDeployment) {
+      throw new Error("Azure OpenAI endpoint mode requires OPENGENI_AZURE_OPENAI_DEPLOYMENT");
+    }
+    if (!settings.azureOpenaiBaseUrl && !settings.azureOpenaiApiVersion) {
+      throw new Error("Azure OpenAI endpoint mode requires OPENGENI_AZURE_OPENAI_API_VERSION");
+    }
+    if (!settings.azureOpenaiApiKey && !settings.azureOpenaiAdToken) {
+      throw new Error("Azure OpenAI requires an API key or AD token");
+    }
+  }
+  if (Boolean(settings.modalTokenId) !== Boolean(settings.modalTokenSecret)) {
+    throw new Error("OPENGENI_MODAL_TOKEN_ID and OPENGENI_MODAL_TOKEN_SECRET must both be set or both omitted");
+  }
+  for (const required of SANDBOX_REQUIRED_ENV[settings.sandboxBackend] ?? []) {
+    const value = settings[required.field];
+    if (value === void 0 || value === null || typeof value === "string" && value.trim().length === 0) {
+      throw new Error(`${required.env} is required when OPENGENI_SANDBOX_BACKEND=${settings.sandboxBackend}`);
+    }
+  }
+  if (settings.objectStorageBackend === "s3-compatible" || settings.objectStorageBackend === "aws-s3") {
+    if (Boolean(settings.objectStorageAccessKeyId) !== Boolean(settings.objectStorageSecretAccessKey)) {
+      throw new Error("OPENGENI_OBJECT_STORAGE_ACCESS_KEY_ID and OPENGENI_OBJECT_STORAGE_SECRET_ACCESS_KEY must both be set or both omitted");
+    }
+    if (settings.objectStorageBackend === "s3-compatible" && (settings.objectStorageEndpoint || settings.objectStorageSandboxEndpoint) && (!settings.objectStorageAccessKeyId || !settings.objectStorageSecretAccessKey)) {
+      throw new Error("S3-compatible object storage endpoints require OPENGENI_OBJECT_STORAGE_ACCESS_KEY_ID and OPENGENI_OBJECT_STORAGE_SECRET_ACCESS_KEY");
+    }
+    if (settings.objectStorageAzureConnectionString || settings.objectStorageAzureAccountName || settings.objectStorageAzureAccountKey || settings.objectStorageAzureEndpoint) {
+      throw new Error("S3 object storage uses OPENGENI_OBJECT_STORAGE_* S3 settings, not OPENGENI_OBJECT_STORAGE_AZURE_* settings");
+    }
+    if (settings.objectStorageGcsProjectId || settings.objectStorageGcsCredentialsJson || settings.objectStorageGcsKeyFilename || settings.objectStorageGcsApiEndpoint) {
+      throw new Error("S3 object storage uses OPENGENI_OBJECT_STORAGE_* S3 settings, not OPENGENI_OBJECT_STORAGE_GCS_* settings");
+    }
+  } else if (settings.objectStorageBackend === "azure-blob") {
+    if (settings.objectStorageEndpoint || settings.objectStorageSandboxEndpoint || settings.objectStorageAccessKeyId || settings.objectStorageSecretAccessKey) {
+      throw new Error("Azure Blob storage uses OPENGENI_OBJECT_STORAGE_AZURE_* settings, not S3-compatible object storage settings");
+    }
+    if (settings.objectStorageGcsProjectId || settings.objectStorageGcsCredentialsJson || settings.objectStorageGcsKeyFilename || settings.objectStorageGcsApiEndpoint) {
+      throw new Error("Azure Blob storage uses OPENGENI_OBJECT_STORAGE_AZURE_* settings, not OPENGENI_OBJECT_STORAGE_GCS_* settings");
+    }
+    const hasConnectionString = Boolean(settings.objectStorageAzureConnectionString);
+    const hasSharedKey = Boolean(settings.objectStorageAzureAccountName) && Boolean(settings.objectStorageAzureAccountKey);
+    if (!hasConnectionString && !hasSharedKey) {
+      throw new Error("Azure Blob storage requires OPENGENI_OBJECT_STORAGE_AZURE_CONNECTION_STRING or OPENGENI_OBJECT_STORAGE_AZURE_ACCOUNT_NAME plus OPENGENI_OBJECT_STORAGE_AZURE_ACCOUNT_KEY");
+    }
+  } else {
+    if (settings.objectStorageEndpoint || settings.objectStorageSandboxEndpoint || settings.objectStorageAccessKeyId || settings.objectStorageSecretAccessKey) {
+      throw new Error("GCS object storage uses OPENGENI_OBJECT_STORAGE_GCS_* settings, not S3-compatible object storage settings");
+    }
+    if (settings.objectStorageAzureConnectionString || settings.objectStorageAzureAccountName || settings.objectStorageAzureAccountKey || settings.objectStorageAzureEndpoint) {
+      throw new Error("GCS object storage uses OPENGENI_OBJECT_STORAGE_GCS_* settings, not OPENGENI_OBJECT_STORAGE_AZURE_* settings");
+    }
+    if (settings.objectStorageGcsCredentialsJson) {
+      parseGcsCredentialsJson(settings.objectStorageGcsCredentialsJson);
+    }
+  }
+  if (settings.documentChunkOverlap >= settings.documentChunkSize) {
+    throw new Error("OPENGENI_DOCUMENT_CHUNK_OVERLAP must be smaller than OPENGENI_DOCUMENT_CHUNK_SIZE");
+  }
+  parseExposedPorts(settings.dockerExposedPorts);
+  sandboxEnvironmentVariableNames(settings);
+  sandboxLifecycleHookIds(settings);
+  parseSandboxWarmRateJson(settings.sandboxWarmRateMicrosPerSecondJson);
+  const serverIds = /* @__PURE__ */ new Set();
+  for (const server of settings.mcpServers) {
+    if (serverIds.has(server.id)) {
+      throw new Error(`OPENGENI_MCP_SERVERS contains duplicate id ${server.id}`);
+    }
+    serverIds.add(server.id);
+  }
+  {
+    const reaperPeriod = settings.sandboxLeaseReaperPeriodMs;
+    const viewerTtl = settings.sandboxViewerHolderTtlMs;
+    const idleGraceMs = settings.sandboxIdleGraceMs;
+    const providerLifetimeMs = settings.modalTimeoutSeconds * 1e3;
+    const idleTimeoutMs = effectiveModalIdleTimeoutSeconds(settings) * 1e3;
+    if (!(reaperPeriod < viewerTtl)) {
+      throw new Error(
+        `OPENGENI_SANDBOX_LEASE_REAPER_PERIOD_MS (${reaperPeriod}) must be strictly less than OPENGENI_SANDBOX_VIEWER_HOLDER_TTL_MS (${viewerTtl}): the reaper must run more often than the TTL it polices, or stale viewer holders outlive a full reaper period.`
+      );
+    }
+    if (!(idleTimeoutMs <= providerLifetimeMs)) {
+      throw new Error(
+        `OPENGENI_MODAL_IDLE_TIMEOUT_SECONDS*1000 (${idleTimeoutMs}) must not exceed the hard provider lifetime (OPENGENI_MODAL_TIMEOUT_SECONDS*1000 = ${providerLifetimeMs}): the idle timeout is a floor under the hard lifetime, not above it.`
+      );
+    }
+    if (!(viewerTtl < idleTimeoutMs)) {
+      throw new Error(
+        `OPENGENI_SANDBOX_VIEWER_HOLDER_TTL_MS (${viewerTtl}) must be strictly less than the effective box idle timeout (${idleTimeoutMs}): a viewer holder must be reapable before the box idles out from under it (the provider idle-timeout is the backstop).`
+      );
+    }
+    if (!(reaperPeriod + idleGraceMs < idleTimeoutMs)) {
+      throw new Error(
+        `OPENGENI_SANDBOX_LEASE_REAPER_PERIOD_MS + OPENGENI_SANDBOX_IDLE_GRACE_MS (${reaperPeriod} + ${idleGraceMs} = ${reaperPeriod + idleGraceMs}) must be strictly less than the effective box idle timeout (${idleTimeoutMs}): a drained box must SURVIVE its full warm window so the reaper can resume + snapshot /workspace + terminate it on the sweep AFTER the drain grace elapses \u2014 Modal's idle-reap must NOT fire first (or /workspace is lost). Raise OPENGENI_MODAL_IDLE_TIMEOUT_SECONDS (defaults to OPENGENI_MODAL_TIMEOUT_SECONDS) or lower OPENGENI_SANDBOX_IDLE_GRACE_MS.`
+      );
+    }
+  }
+  if (settings.sandboxDesktopEnabled && resolveStreamTokenSecret(settings) === void 0) {
+    console.warn(
+      "[opengeni] OPENGENI_SANDBOX_DESKTOP_ENABLED=true but neither OPENGENI_STREAM_TOKEN_SECRET nor OPENGENI_DELEGATION_SECRET is set: the desktop pixel plane will GRACEFULLY DEGRADE (DesktopStream.transport=null \u2014 no scoped stream tokens can be minted). Set OPENGENI_STREAM_TOKEN_SECRET to enable the live desktop stream."
+    );
+  }
+  const registryProviders = parseModelProvidersJson(settings.modelProvidersJson);
+  const builtinId = builtinProviderId(settings);
+  const providerIds = /* @__PURE__ */ new Set();
+  for (const provider of registryProviders) {
+    if (provider.id === builtinId) {
+      throw new Error(`OPENGENI_MODEL_PROVIDERS_JSON provider id ${provider.id} collides with the built-in provider id`);
+    }
+    if (providerIds.has(provider.id)) {
+      throw new Error(`OPENGENI_MODEL_PROVIDERS_JSON contains duplicate provider id ${provider.id}`);
+    }
+    providerIds.add(provider.id);
+    if (!resolveProviderApiKey(provider)) {
+      throw new Error(`OPENGENI_MODEL_PROVIDERS_JSON provider ${provider.id} requires a resolvable API key (set apiKey or apiKeyEnv)`);
+    }
+  }
+}
+function resolveStreamTokenSecret(settings) {
+  const explicit = settings.streamTokenSecret?.trim();
+  if (explicit) {
+    return explicit;
+  }
+  const delegation = settings.delegationSecret?.trim();
+  return delegation ? delegation : void 0;
+}
+function streamTokenDegraded(settings) {
+  return settings.sandboxDesktopEnabled && resolveStreamTokenSecret(settings) === void 0;
+}
+function resolveEnrollmentSigningSecret(settings) {
+  const explicit = settings.enrollmentSigningSecret?.trim();
+  if (explicit) {
+    return explicit;
+  }
+  const delegation = settings.delegationSecret?.trim();
+  return delegation ? delegation : void 0;
+}
+function resolveRelayTokenSecret(settings) {
+  const explicit = settings.selfhostedRelayTokenSecret?.trim();
+  if (explicit) {
+    return explicit;
+  }
+  const stream = settings.streamTokenSecret?.trim();
+  if (stream) {
+    return stream;
+  }
+  const delegation = settings.delegationSecret?.trim();
+  return delegation ? delegation : void 0;
+}
+function resolveNatsCalloutConfig(settings) {
+  const accountSeed = settings.selfhostedNatsCalloutAccountSeed?.trim();
+  const accountName = settings.selfhostedNatsCalloutAccountName?.trim() || "APP";
+  const user = settings.selfhostedNatsCalloutUser?.trim();
+  const password = settings.selfhostedNatsCalloutPassword?.trim();
+  if (!accountSeed || !user || !password) {
+    return null;
+  }
+  return { accountSeed, accountName, user, password };
+}
+function resolveNatsControlPlaneAuth(settings) {
+  const user = settings.selfhostedNatsControlUser?.trim();
+  const password = settings.selfhostedNatsControlPassword?.trim();
+  if (!user || !password) {
+    return null;
+  }
+  return { user, password };
+}
+function splitCsv(raw) {
+  return raw.split(",").map((value) => value.trim()).filter(Boolean);
+}
+function uniqueEnvNames(raw, fieldName) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const name of raw) {
+    if (!envName.test(name)) {
+      throw new Error(`${fieldName} contains invalid variable name ${name}`);
+    }
+    if (!seen.has(name)) {
+      seen.add(name);
+      out.push(name);
+    }
+  }
+  return out;
+}
+function uniqueValues(raw) {
+  return [...new Set(raw.filter(Boolean))];
+}
+function parseGcsCredentialsJson(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`OPENGENI_OBJECT_STORAGE_GCS_CREDENTIALS_JSON must be valid JSON: ${message}`);
+  }
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export {
+  AGENT_INSTRUCTIONS_CORE_PLACEHOLDER,
+  DEFAULT_AGENT_INSTRUCTIONS,
+  ModelProviderApi,
+  RegistryProviderKind,
+  SANDBOX_REQUIRED_ENV,
+  applyGitAuthPointerEnvironment,
+  calculateModelUsageCostMicros,
+  collectGitIdentityEnvironment,
+  collectSandboxEnvironment,
+  configuredAllowedModels,
+  configuredAllowedReasoningEfforts,
+  configuredEntitlements,
+  configuredModelPricing,
+  configuredModels,
+  configuredProviders,
+  configuredStaticUsageLimits,
+  contextInputBudgetTokens,
+  contextServerCompactThreshold,
+  dbSearchPath,
+  defaultModelPricing,
+  effectiveModalIdleTimeoutSeconds,
+  environmentsEncryptionKeyBytes,
+  firstPartyMcpBaseUrl,
+  getSettings,
+  hasGitHubRepositorySelection,
+  parseExposedPorts,
+  parseMcpServers,
+  parseModelPricingJson,
+  parseModelProvidersJson,
+  parseSandboxWarmRateJson,
+  parseStaticEntitlementsJson,
+  parseStaticUsageLimitsJson,
+  requiredSandboxEnvForBackend,
+  resolveContextCompactionMode,
+  resolveEnrollmentSigningSecret,
+  resolveModelProvider,
+  resolveNatsCalloutConfig,
+  resolveNatsControlPlaneAuth,
+  resolveProviderApiKey,
+  resolveRelayTokenSecret,
+  resolveStreamTokenSecret,
+  retryStartupDependency,
+  sandboxEnvironmentVariableNames,
+  sandboxLifecycleHookIds,
+  sandboxPreparationProfiles,
+  sandboxWarmRateMicrosPerSecond,
+  stableSandboxEnvironmentForRun,
+  startupRetryOptions,
+  streamTokenDegraded
+};
+//# sourceMappingURL=index.js.map