Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

64.1 KB
Raw Blame
/**
 * What the runtime can do. There is exactly one answer because CopilotKit Intelligence is required
 * for durable threads and memory. Configuration the product cannot function without belongs at the
 * boot boundary.
 */
import { intelligenceApiKey } from "@openbot/shared/intelligence-key";
import {
  isLearningContainerId,
  type LearningTarget,
} from "@openbot/shared/learning";
import {
  BROWSER_ABSENT_ENV,
  BROWSER_URL_ENV,
  type BrowserAbsence,
  isBrowserAbsence,
} from "@openbot/shared/openbot-browser";
import { singleUserEnabled } from "./auth/dev-actor";
import { normalizeDomain } from "./auth/email-domain";
import { organizationAuthority } from "./auth/organization";
import type { ActionPolicy } from "./computer/policy";
import { parseActionPolicy } from "./computer/policy-store";
import {
  type TranscriptionConfig,
  transcriptionConfig,
} from "./dictation/config";
import type { BrokerProvider } from "./plugins/access";
import { type VoiceConfig, voiceConfig } from "./voice/config";
import { type WebBotAuth, webBotAuthFromEnv } from "./web-bot-auth";

export type RuntimeCapabilities = {
  mode: "intelligence";
  durableHistory: true;
  intelligence: IntelligenceSettings;
};

/**
 * The Intelligence contract. Three values are required; see runtimeCapabilities.
 *
 * `licenseToken` is optional. Managed Intelligence derives entitlement from the project key, and
 * `@copilotkit/runtime` declares `licenseToken` optional with a `COPILOTKIT_LICENSE_TOKEN` fallback
 * of its own. A deployment that still holds one keeps passing it; nothing here requires it.
 */
export type IntelligenceSettings = {
  apiUrl: string;
  gatewayWsUrl: string;
  apiKey: string;
  licenseToken?: string;
  /**
   * The gateway as the browser reaches it, when that is not where this server reaches it. See
   * `INTELLIGENCE_BROWSER_GATEWAY_WS_URL` in `runtimeCapabilities`.
   */
  browserGatewayWsUrl?: string;
};

export type DockerComputerConfig = {
  provider: "docker";
  baseUrl: string;
  supervisorToken?: string;
  token?: string;
  allowPrivateHosts: boolean;
  policy?: ActionPolicy;
};

export type SharedComputerConfig = {
  provider: "shared";
  baseUrl: string;
  token?: string;
  allowPrivateHosts: boolean;
  policy?: ActionPolicy;
};

/**
 * A computer each, created by the cluster.
 *
 * The namespace is the whole scope: the service account this runs under may manage Sandboxes there
 * and nowhere else, which is a smaller blast radius than the Docker supervisor's, since that one
 * holds a socket that is root-equivalent on its host.
 */
export type SandboxComputerConfig = {
  provider: "sandbox";
  namespace: string;
  idleAfterMs: number;
  /** Where the chart mounted the shape of a computer. */
  templateFile: string;
  token?: string;
  allowPrivateHosts: boolean;
  policy?: ActionPolicy;
};

export type ComputerConfig =
  | DockerComputerConfig
  | SharedComputerConfig
  | SandboxComputerConfig;

/**
 * Who a deployment lets in, and through which front door.
 *
 * One identity provider is a product decision somebody else already made. A company running this
 * has Google or Entra or Okta and is not going to acquire another, so the shape here is a set of
 * optional providers rather than one required one, and the deployment turns on whichever it has.
 */
export type AuthProviderId = "google" | "microsoft" | "okta";

/** An OAuth client, as every provider here needs one. */
export type OAuthClient = { clientId: string; clientSecret: string };

export type GithubAppConfig = {
  clientId: string;
  clientSecret: string;
};

export type AuthConfig = {
  baseUrl: string;
  secret: string;
  trustedOrigins: string[];
  initialAdminEmails: string[];
  /**
   * Email domains this deployment admits, on top of whatever the provider decided.
   *
   * Empty means no opinion, which is what every deployment running today already does. See
   * `auth/email-domain.ts` for why the provider's own answer is not this question.
   */
  allowedEmailDomains: string[];
  google?: OAuthClient;
  /**
   * `tenantId` decides who may sign in at all, so it is not a detail. `common` admits any Microsoft
   * account including personal ones, `organizations` any work or school account anywhere, and a GUID
   * admits one directory. A deployment that wants only its own company needs the GUID.
   */
  microsoft?: OAuthClient & { tenantId: string };
  /** Okta is an OIDC provider rather than a named one, so it is identified by its issuer. */
  okta?: OAuthClient & { issuer: string };
};

/**
 * The providers this deployment can actually sign somebody in with.
 *
 * Ordered, and deliberately not alphabetically: this is the order the buttons appear in, and it is
 * fixed here rather than left to object key order so the sign-in screen cannot change shape because
 * of how a configuration happened to be written.
 */
export function configuredAuthProviders(
  auth: AuthConfig | undefined,
): AuthProviderId[] {
  if (!auth) return [];
  const providers: AuthProviderId[] = [];
  if (auth.google) providers.push("google");
  if (auth.microsoft) providers.push("microsoft");
  if (auth.okta) providers.push("okta");
  return providers;
}

export type ManagedAgentConfig = {
  /** The bundled Bot, absent when this deployment's provider cannot run it. */
  endpoint?: URL;
  /** Secret sent only to endpoints this deployment runs. Never stored in an agent row. */
  token: string;
  /**
   * The harness picked during setup, when there is one.
   *
   * Also an endpoint this deployment runs: its container was started by this deployment, on a port
   * it chose, holding this token. It gets the same header for the same reason.
   */
  alsoRun?: URL;
};

/**
 * How far one Bot handing work to another may go.
 *
 * NUMBERS A DEPLOYMENT CHOOSES, not constants. A small team and a company running this across
 * departments want different answers, and neither should have to edit code to get one.
 *
 * Both defaults are deliberately mean. A hop costs a whole agent turn at the other end, fan-out
 * shapes cost several times a single run because each Bot spends its own full budget, and on a
 * cluster a hop to a Bot whose computer is asleep also pays a pod resume. One level of delegation is
 * what most systems allow by default, and a deployment that wants more can say so.
 */
export type HandoffCaps = {
  /** How many Bots deep a chain may go. `0` switches the whole capability off. */
  maxDepth: number;
  /** How many other Bots one run may address. */
  maxPerRun: number;
};

export type DeploymentConfig = {
  /**
   * Browser extension ids OpenBot trusts as the Recorder besides its own fixed id, for a fork or a
   * build signed with another key. From OPENBOT_RECORDER_EXTRA_EXTENSION_IDS, never from NODE_ENV.
   */
  recorder: { extraExtensionIds: string[] };
  /** Optional environment default. A saved Admin setting takes precedence. */
  learning?: LearningTarget;
  /**
   * Whether OpenBot assigns the Intelligence project's `openbot` Learning container as the default
   * when nobody has chosen one (learning/auto-assign.ts). On unless OPENBOT_LEARNING_AUTO_ASSIGN is
   * "false" or "0", and off whenever CPK_INTELLIGENCE_LEARNING_CONTAINER_ID names a container. It
   * never overrides a saved Admin setting. It creates the container only with a credential that can
   * (see `learningSetup`), never with the runtime key.
   */
  learningAutoAssign: boolean;
  /**
   * A credential that can create Learning containers, for a deployment whose operator supplied one.
   *
   * The runtime key cannot: Intelligence creates containers for a person's session, a CopilotKit CLI
   * login, or, on a CopilotKit local evaluation install only, a service token. The server holds
   * neither of the first two, so this is the service token, sent as `x-copilotkit-ei-service-token`
   * to `/api/learning/projects/:projectId/containers` with the project it belongs to. Both or
   * neither: a token without its project is refused at startup.
   */
  learningSetup?: { serviceToken: string; projectId: string };
  /**
   * Memory sources and background research OpenBot switches on for each person (memory/defaults.ts).
   * Both on unless OPENBOT_MEMORY_SOURCE_DEFAULTS or OPENBOT_PROACTIVE_DEFAULTS is "false" or "0".
   * Switching either off stops new defaults and leaves every existing row as it is.
   */
  memoryDefaults: { sources: boolean; research: boolean };
  /** Audio configuration is independent of agent model providers. */
  transcription?: TranscriptionConfig;
  voice?: VoiceConfig;
  /** The port the API listens on. Named `PORT` or `SERVER_PORT`; see `serverPort`. */
  port: number;
  databaseUrl: string;
  keyEncryptionKey: string;
  /**
   * Authentication for the bundled Bot and/or the installed picked harness.
   *
   * The bundled endpoint is optional: plan credentials can run a picked harness without it.
   * Its presence, not this auth configuration, determines whether a bundled Bot is available.
   */
  managedAgent?: ManagedAgentConfig;
  /**
   * Private addresses an agent may be registered at, named one at a time.
   *
   * WHY THIS EXISTS. `AGENT_COMPUTER_ALLOW_PRIVATE_HOSTS` is a floor, not a permission: it opens this
   * deployment's whole network, to browsing and to agent endpoints alike, which is why a production
   * deployment refuses to start with it on. That left bring-your-own-agent — a headline capability —
   * unusable in the image people are told to deploy, because a company's own agent legitimately lives
   * at an internal address and the only way to reach it was to drop the floor.
   *
   * So the address is named instead. Nothing else is opened, browsing is not widened, and the
   * never-allowed list is still checked first, so the metadata address cannot be named back in.
   * Empty by default, which is the same posture as before for anybody who does not set it.
   */
  agentEndpointAllowedHosts: ReadonlySet<string>;
  /**
   * What this deployment calls itself, when more than one shares an Intelligence project.
   *
   * Absent, the tenant package's id stands in, which separates deployments running different
   * packages but not a copy of one running alongside the original. See channels/thread-identity.ts.
   */
  deploymentId: string | undefined;
  /**
   * The key this deployment talks to Composio with, the broker that holds people's accounts for a
   * few hundred apps so a Bot can act in Gmail or Slack without an OAuth client of this
   * deployment's own registered with each of them.
   *
   * Optional, and undefined is the ordinary state rather than a degraded one. A deployment that has
   * not bought Composio is not a deployment missing something: there is nothing to connect, nothing
   * to grant and no Composio tool for a Bot to call, what remains on screen is one row that goes
   * nowhere under More apps on the admin Plugins page naming this variable, and nothing else it does
   * is any worse for that.
   *
   * Nothing here validates the key. There is no shape to check it against and no call worth making
   * at boot to find out, so the first real request is what says whether it works — which is also
   * where a key that was revoked last week would have surfaced regardless.
   */
  composioApiKey: string | undefined;
  /** GitHub App user sign-in, so people can link their GitHub account. Both or neither of GITHUB_APP_CLIENT_ID / GITHUB_APP_CLIENT_SECRET. */
  githubApp?: GithubAppConfig;
  /**
   * The Arcade API key, from `ARCADE_API_KEY`. Unset is the ordinary state. Trimmed and never
   * validated here, for the same reason as `composioApiKey`.
   */
  arcadeApiKey: string | undefined;
  /**
   * Which tool broker the operator asked for, from `OPENBOT_BROKER_PROVIDER`. Only read and
   * validated here: which provider is active is decided elsewhere. Unset is `undefined`.
   */
  brokerProvider: BrokerProvider | undefined;
  /**
   * Where this deployment is reached from outside, with no trailing slash.
   *
   * Needed because an OAuth redirect URI has to match what an administrator registered with the
   * vendor character for character, and it is shown on the Plugins page for them to copy. Built from
   * configuration rather than from the incoming request: a redirect URI assembled out of a Host
   * header is one an attacker has a say in.
   *
   * `OPENBOT_PUBLIC_URL` when set, otherwise `BETTER_AUTH_URL`, which is the same public address for
   * every deployment that has real sign-in. Undefined only where neither exists, which is a local
   * deployment running without authentication — and there is nothing to connect there anyway.
   */
  publicUrl: string | undefined;
  /**
   * The key Bots' browsers sign their requests with, and the address its public half is published
   * under. Undefined when Web Bot Auth is off; see `web-bot-auth.ts` for when that is.
   */
  webBotAuth?: WebBotAuth;
  /**
   * Where the browser app is served from, with no trailing slash.
   *
   * Separate from {@link DeploymentConfig.publicUrl} because they are genuinely two addresses: the
   * app is a Vite process on its own port locally, and the API is another. An OAuth callback lands on
   * the API and has to send the person back to a page, so a relative redirect would put them on the
   * API's origin, where no page exists.
   *
   * `OPENBOT_APP_URL` when set, otherwise the first `TRUSTED_ORIGINS` entry, which is already defined
   * as where the app is served from. Falls back to the API's own public URL, which is right for a
   * deployment serving both from one origin.
   */
  appUrl: string | undefined;
  tenantPackageDirectory: string;
  runtime: RuntimeCapabilities;
  /**
   * How long a Bot's stream may say nothing before this deployment ends the turn, in milliseconds.
   *
   * Zero means no watchdog, and an unset variable means zero. A turn that is ended is a turn
   * somebody loses, so a deployment that has not said it wants that gets the behaviour it already
   * had. `.env.example` ships a value, so a new clone starts with the watch on and an upgraded
   * deployment does not acquire it without being asked.
   */
  agentStallTimeoutMs: number;
  /**
   * How many days of audit trail this deployment keeps, or undefined to keep everything.
   *
   * Undefined by default. Deleting somebody's audit trail because a default said so is the worse of
   * the two failures, and a deployment that has not thought about retention should keep everything
   * until it has.
   */
  auditRetentionDays: number | undefined;
  oauth: {
    google?: { clientId: string; clientSecret: string };
  };
  auth?: AuthConfig;
  /** Customer OpenBot authority for employee desktop sessions, separate from Intelligence. */
  organizationAuthUrl?: string;
  /**
   * Admit everybody as one fixed administrator instead of requiring sign-in.
   *
   * True only when no identity provider is configured. See auth/dev-actor.ts for what stops this
   * reaching somewhere other people can get to.
   */
  singleUser: boolean;
  /** Names OpenBot on the analytics the runtime already sends. Off with OPENBOT_ACCESSIBILITY_DISABLED. */
  accessibility: boolean;
  /**
   * Whether a Bot may answer with an interface it wrote itself.
   *
   * This is not the component catalogue. A component is something this deployment holds: it was
   * either compiled into the build or authored in the playground, an administrator granted it to a
   * Bot, and all a Bot decides is which of them to draw. Here there is nothing to grant, because
   * there is nothing yet — the Bot writes the markup, the styles and the script for this one answer,
   * and they are gone when the conversation moves on.
   *
   * A deployment switch rather than a per-Bot grant because the SDK offers no seam for one. The
   * interface is painted from activity events that only the runtime middleware emits, and the tool
   * the model calls is registered by the browser for every Bot the moment that middleware is on.
   * Narrowing the middleware to some Bots would leave the rest able to call the tool and draw
   * nothing at all, which is a worse answer than never offering it.
   *
   * On by default. A deployment that cannot allow generated interfaces can explicitly opt out with
   * OPENBOT_GENERATIVE_UI=false or OPENBOT_GENERATIVE_UI=0.
   *
   * What it runs is sandboxed by the SDK, in an iframe with no same-origin access to this app, so a
   * generated interface reaches this deployment's data only through what the host hands it. This
   * deployment hands it nothing. It can load libraries from a CDN, which is the part a deployment
   * that must not reach the public internet from a browser tab needs to weigh.
   */
  generativeUi: boolean;
  /**
   * Whether the signed-in app shows the banner offering help self-hosting OpenBot.
   *
   * On by default, because a fresh clone is somebody evaluating the template. A fork that runs
   * OpenBot for its own organization turns it off with OPENBOT_SELF_HOST_BANNER=false or
   * OPENBOT_SELF_HOST_BANNER=0, since its people have nothing to self-host. This is the operator's
   * switch only; a deployment on a paid Intelligence plan hides the bar too (self-host-banner.ts).
   */
  selfHostBanner: boolean;
  /**
   * Where the built app is, when this process serves it.
   *
   * Set in a container image that carries both. Unset in development, where Vite serves the app and
   * proxies the API here, so the server stays an API and nothing shadows a route.
   */
  appDistDir?: string;
  /**
   * The Bot computer. Absent means the feature is off and its routes are not mounted, rather than
   * mounted and failing: a capability that is not configured should be missing, not broken.
   */
  computer?: ComputerConfig;
  /**
   * The computer that runs people's own OpenBot browsers here when it is not the Bots' (`OPENBOT_BROWSER_URL`): OpenBot
   * Desktop's host-side local Chrome computer, so a person's browser is a window on their own desktop while Bots'
   * computers stay where they are. Called with the same COMPUTER_TOKEN as every computer. Absent, the Bots' computer
   * provider runs people's browsers too.
   */
  browser?: { url: string; token?: string };
  /**
   * Why OpenBot Desktop found no browser of the person's own to run on this machine (`OPENBOT_BROWSER_ABSENT`), which
   * the person is told beside whatever browser runs for them instead. A name this server does not know is left out:
   * Desktop and the deployment it runs are released apart, and an explanation is no reason to refuse to start.
   */
  browserAbsent?: BrowserAbsence;
  /** How far one Bot handing work to another may go. */
  handoff: HandoffCaps;
  /**
   * The secret a Bot presents when it calls a tool back through this server.
   *
   * A framework Bot runs its own tool loop, in its own process, which is what makes it a real
   * harness rather than a shape the browser drives. It still may not reach a vendor directly: it
   * calls here, and here is where the grant, the policy and the audit row are. This is what tells
   * that call apart from anybody else on the network.
   *
   * Absent means no Bot may call tools back, and a deployment that wanted them gets a refusal rather
   * than an open door.
   */
  agentToolToken?: string;
  /**
   * The secret the worker presents when it hands a routine run back to this server.
   *
   * Absent means the internal routines endpoint refuses everything, which is the correct state of a
   * deployment with no worker — a deployment that has not asked for scheduled turns should not have a
   * door for them standing open.
   */
  workerSharedSecret?: string;
};

type Environment = Record<string, string | undefined>;

/**
 * The caps, read from the environment, refusing anything that is not a whole number at least zero.
 *
 * Refused rather than coerced. A cap is a safety number, and a deployment that typed `two` and got
 * the default would believe it had set one: the failure has to be at start-up where somebody is
 * looking, not at the first loop.
 */
function handoffCaps(environment: Environment): HandoffCaps {
  const read = (name: string, fallback: number): number => {
    const raw = optional(environment, name);
    if (raw === undefined) return fallback;
    const value = Number(raw);
    if (!Number.isInteger(value) || value < 0) {
      throw new Error(`${name} must be a whole number of zero or more`);
    }
    return value;
  };
  return {
    // One level of delegation, which is what most systems allow before anybody asks for more.
    maxDepth: read("BOT_HANDOFF_MAX_DEPTH", 1),
    maxPerRun: read("BOT_HANDOFF_MAX_PER_RUN", 3),
  };
}

function required(environment: Environment, name: string): string {
  const value = environment[name]?.trim();
  if (!value) {
    throw new Error(`${name} must be configured`);
  }
  return value;
}

function optional(environment: Environment, name: string): string | undefined {
  return environment[name]?.trim() || undefined;
}

function brokerProvider(environment: Environment): BrokerProvider | undefined {
  const raw = optional(environment, "OPENBOT_BROKER_PROVIDER");
  if (raw === undefined) return undefined;
  if (raw !== "composio" && raw !== "arcade") {
    throw new Error(
      `OPENBOT_BROKER_PROVIDER must be "composio" or "arcade", got "${raw}". Leave it unset to choose by which API key is configured.`,
    );
  }
  return raw;
}

/**
 * Whether this deployment says it is in production, which is what the two hard refusals turn on.
 *
 * ONE PLACE, BECAUSE THE TWO GATES DID NOT AGREE. Both refuse a local-only setting on a deployed
 * server — the example encryption key, and private-host browsing — and both compare `NODE_ENV`
 * against `"production"`. The private-hosts gate read it through `optional`, so the comparison
 * trimmed; the key gate compared `environment.NODE_ENV` raw.
 *
 * Both sides of that comparison come out of the same file. `NODE_ENV=production ` with a trailing
 * space — invisible in an env file, and preserved verbatim by Docker's `env_file` and by every
 * hosting dashboard with a text box — therefore tripped one refusal and slipped past the other. The
 * one it slipped past is the one that decides whether the credential vault may be encrypted with a
 * key printed in this repository.
 *
 * A helper rather than a second `optional` call, so the next gate that needs this question cannot
 * pick the wrong way to ask it.
 */
function isProduction(environment: Environment): boolean {
  return optional(environment, "NODE_ENV") === "production";
}

/**
 * The key in `.env.example`, which every clone of this repository starts with.
 *
 * It is a valid key, which is the whole problem: it is the right length and the right encoding, so
 * nothing about it fails a check. A deployment that never changed it encrypts its credential vault
 * with a key printed in a public repository, and looks exactly like one that did.
 */
const PLACEHOLDER_KEY = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";

function keyEncryptionKey(environment: Environment): string {
  const value = required(environment, "KEY_ENCRYPTION_KEY");
  const decoded = Buffer.from(value, "base64");

  if (decoded.byteLength !== 32 || decoded.toString("base64") !== value) {
    throw new Error("KEY_ENCRYPTION_KEY must be a base64-encoded 32-byte key");
  }

  /**
   * Refused in production, warned everywhere else. The placeholder is convenient locally and public
   * in any deployment.
   */
  if (value === PLACEHOLDER_KEY) {
    if (isProduction(environment)) {
      throw new Error(
        "KEY_ENCRYPTION_KEY is still the example key from .env.example, which is public. Generate one with: openssl rand -base64 32",
      );
    }
    console.warn(
      "KEY_ENCRYPTION_KEY is the example key from .env.example, which is public. Fine locally. Generate a real one before deploying: openssl rand -base64 32",
    );
  }

  return value;
}

/**
 * Whether this deployment may run with no sign-in at all.
 *
 * {@link singleUserEnabled} answers whether somebody ASKED for it, and the flag is how they say so.
 * That design is deliberate and stays: `single-user.test.ts` pins it, and the boot comment in
 * `.github/workflows/ci.yml` says the same thing in the same words. This asks the second question
 * the flag cannot answer, which is not "is this production" but "can anybody else reach it".
 *
 * NOT `NODE_ENV`. It looks like the signal and is not one here: `Dockerfile` sets
 * `NODE_ENV=production` for every container and `openbot.commonEnv` sets it for every chart
 * install, including the local trial the chart's own `validation.yaml` offers. Gating on it would
 * refuse a mode the chart advertises and would fail the image-boot job in CI, which runs exactly
 * this combination on purpose.
 *
 * The chart already asks the right question twice, and this is the same question moved to where a
 * deployment that never goes near Helm is also asked it:
 *
 *   config.singleUser + a LoadBalancer with no source ranges -> refused
 *   config.singleUser + config.publicUrl                     -> refused
 *
 * So: one administrator and no sign-in is a thing you run where only you can reach it. A public
 * URL, or a trusted origin that is not loopback, says somebody else can. `.env.example` ships the
 * flag on so a clone runs, and README's "Deploy it" hands that same `.env` to `docker run`; what
 * separates those two is an address, which is what this reads.
 */
function singleUserAllowed(
  environment: Environment,
  hasProvider: boolean,
): boolean {
  if (!singleUserEnabled(environment, hasProvider)) return false;

  const reachable = [
    optional(environment, "OPENBOT_PUBLIC_URL"),
    optional(environment, "OPENBOT_APP_URL"),
    ...commaSeparated(environment, "TRUSTED_ORIGINS"),
  ].filter((value): value is string => value !== undefined);

  const published = reachable.filter((value) => reachOf(value) === "public");
  if (published.length > 0) {
    throw new Error(
      `OPENBOT_SINGLE_USER admits every request as one administrator with no sign-in, so it cannot be combined with an address the public internet reaches: ${published.join(", ")}. Configure GOOGLE_OAUTH_*, MICROSOFT_OAUTH_* or OKTA_OAUTH_* with BETTER_AUTH_SECRET and BETTER_AUTH_URL, or serve it somewhere only you reach.`,
    );
  }

  /*
   * A private address is allowed and said out loud. index.ts already warns every boot that there is
   * no sign-in; what it cannot say, because it never reads an address, is that this one is carried
   * beyond the machine. Whoever is on that network is an administrator here.
   */
  const shared = reachable.filter((value) => reachOf(value) === "private");
  if (shared.length > 0) {
    console.warn(
      `OPENBOT_SINGLE_USER admits every request as one administrator with no sign-in, and this deployment answers on an address beyond this machine: ${shared.join(", ")}. Anybody on that network is that administrator. Configure a sign-in provider before anybody else is on it.`,
    );
  }

  return true;
}

/**
 * How far an address reaches, which is the question `OPENBOT_SINGLE_USER` actually turns on.
 *
 * Not two answers but three, because the middle one is most of the deployments this flag exists
 * for. "No sign-in, one administrator" is a thing people run on a home server at `192.168.1.10`,
 * over Tailscale at `100.something`, on a VPN, or at `openbot.local`. None of those is loopback and
 * none of them is a stranger's to reach, so refusing them would refuse the feature's own audience
 * while the operator's only recourse is to turn off the flag that describes what they are doing.
 *
 * A routable public address is the different thing, and it is the one that refuses.
 *
 * UNPARSEABLE COUNTS AS PUBLIC, and so does an unrecognised name. A value nobody could read is not
 * a value anybody checked, and the safe reading of "I cannot tell" is never "it is fine".
 */
type Reach = "loopback" | "private" | "public";

function reachOf(raw: string): Reach {
  let bare: string;
  try {
    bare = new URL(raw).hostname.toLowerCase();
  } catch {
    return "public";
  }
  bare = bare.replace(/^\[|\]$/g, "").replace(/\.+$/, "");
  if (!bare) return "public";

  if (
    bare === "localhost" ||
    bare === "::1" ||
    bare === "0:0:0:0:0:0:0:1" ||
    /^127(\.\d{1,3}){3}$/.test(bare)
  ) {
    return "loopback";
  }

  if (bare.includes(":")) {
    // fc00::/7 is the unique local range and fe80::/10 the link-local one. Both are unroutable on
    // the public internet, which is the only property being asked about here.
    return /^f[cd]/.test(bare) || /^fe[89ab]/.test(bare) ? "private" : "public";
  }

  const octets = bare.split(".");
  if (octets.length === 4 && octets.every((part) => /^\d{1,3}$/.test(part))) {
    const [a, b] = octets.map(Number) as [number, number, number, number];
    const privateV4 =
      a === 10 ||
      (a === 172 && b >= 16 && b <= 31) ||
      (a === 192 && b === 168) ||
      // 169.254/16 is link-local, and 100.64/10 is the carrier-grade NAT range Tailscale hands out.
      (a === 169 && b === 254) ||
      (a === 100 && b >= 64 && b <= 127);
    return privateV4 ? "private" : "public";
  }

  // A name rather than an address. `.local` is mDNS, `.internal` and `.home.arpa` are reserved for
  // exactly this, and a single label with no dot at all is a LAN name that no public resolver
  // answers. Anything else is a name somebody could look up.
  const privateName =
    !bare.includes(".") ||
    bare.endsWith(".local") ||
    bare.endsWith(".internal") ||
    bare.endsWith(".lan") ||
    bare.endsWith(".home.arpa");
  return privateName ? "private" : "public";
}

function url(environment: Environment, name: string): string | undefined {
  const value = optional(environment, name);
  if (!value) {
    return undefined;
  }

  try {
    new URL(value);
  } catch {
    throw new Error(`${name} must be a valid URL`);
  }
  return value;
}

function optionalHttpUrl(
  environment: Environment,
  name: string,
): URL | undefined {
  const value = optional(environment, name);
  if (!value) {
    return undefined;
  }

  let parsed: URL;
  try {
    parsed = new URL(value);
  } catch {
    throw new Error(`${name} must be a valid HTTP(S) URL`);
  }

  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
    throw new Error(`${name} must be a valid HTTP(S) URL`);
  }

  return parsed;
}

/**
 * The Bot in the box, if this deployment has one.
 *
 * A URL with no token would send unauthenticated calls to a Bot that refuses them, so that half
 * alone refuses to start. A token with no URL is the leftover `scripts/start.sh` writes into
 * `.env`; it names nothing and is ignored, so a one-container image can boot from that file.
 */
function managedAgentConfig(
  environment: Environment,
): ManagedAgentConfig | undefined {
  const endpoint = optionalHttpUrl(environment, "MANAGED_AGENT_AG_UI_URL");
  // BYO writes a URL too, but does not run our image or hold our deployment token.
  const alsoRun = optional(environment, "PICKED_HARNESS_IMAGE")
    ? optionalHttpUrl(environment, "PICKED_HARNESS_URL")
    : undefined;
  const token = optional(environment, "MANAGED_AGENT_TOKEN");
  if (endpoint && !token) {
    throw new Error(
      "MANAGED_AGENT_TOKEN must be set when MANAGED_AGENT_AG_UI_URL is set",
    );
  }
  if (alsoRun && !token) {
    throw new Error(
      "MANAGED_AGENT_TOKEN must be set when an installed PICKED_HARNESS_URL is set",
    );
  }
  if ((!endpoint && !alsoRun) || !token) {
    return undefined;
  }
  /*
   * The harness somebody picked during setup is also an endpoint this deployment runs.
   *
   * It is a container this deployment started, on a port this deployment chose, holding the token
   * this deployment generated — the same relationship the Bot in the box has. It was not getting
   * the token because that was attached by matching one endpoint exactly, so the picked Bot was
   * registered, addressable, routed to, and answered every call with 401. Only visible by asking it
   * something in the window.
   */
  return {
    ...(endpoint ? { endpoint } : {}),
    token,
    ...(alsoRun ? { alsoRun } : {}),
  };
}

function oauthClient(
  environment: Environment,
  provider: "GOOGLE" | "MICROSOFT" | "OKTA",
): OAuthClient | undefined {
  const clientId = optional(environment, `${provider}_OAUTH_CLIENT_ID`);
  const clientSecret = optional(environment, `${provider}_OAUTH_CLIENT_SECRET`);

  // Both or neither. One alone is a half-configured sign-in that fails at the first attempt rather
  // than at start-up, which is the worst moment to discover it.
  if (Boolean(clientId) !== Boolean(clientSecret)) {
    throw new Error(
      `${provider}_OAUTH_CLIENT_ID and ${provider}_OAUTH_CLIENT_SECRET must be set together`,
    );
  }

  return clientId && clientSecret ? { clientId, clientSecret } : undefined;
}

function githubAppConfig(
  environment: Environment,
): GithubAppConfig | undefined {
  const clientId = optional(environment, "GITHUB_APP_CLIENT_ID");
  const clientSecret = optional(environment, "GITHUB_APP_CLIENT_SECRET");

  // Both or neither. One alone is a half-configured sign-in that fails at the first attempt rather
  // than at start-up, which is the worst moment to discover it.
  if (Boolean(clientId) !== Boolean(clientSecret)) {
    throw new Error(
      "GITHUB_APP_CLIENT_ID and GITHUB_APP_CLIENT_SECRET must be set together",
    );
  }

  return clientId && clientSecret ? { clientId, clientSecret } : undefined;
}

function commaSeparated(environment: Environment, name: string): string[] {
  return (optional(environment, name) ?? "")
    .split(",")
    .map((value) => value.trim())
    .filter(Boolean);
}

/**
 * Microsoft's three multi-tenant audiences, which name no directory.
 *
 * Anything else is a directory this deployment's administrators control, named by GUID or by a
 * verified domain. `organizations` matters as much as `common` here and is the one a hand-written
 * check forgets: Microsoft's own description is that it admits any work or school account in any
 * directory, so a domain allowlist is no more enforceable under it than under `common`.
 *
 * Compared folded, because these arrive from an environment variable and `Common` is the same
 * audience as `common` to Microsoft.
 */
const MULTI_TENANT_AUDIENCES = new Set([
  "common",
  "organizations",
  "consumers",
]);

function namesNoDirectory(tenantId: string | undefined): boolean {
  return (
    tenantId !== undefined &&
    MULTI_TENANT_AUDIENCES.has(tenantId.trim().toLowerCase())
  );
}

/**
 * Sign-in, if this deployment has an identity provider to sign people in with.
 *
 * Any one of the three turns authentication on. More than one is allowed and is the normal shape
 * for a company mid-migration, where some people are on Entra and some are still on Okta.
 *
 * Every combination that cannot work refuses at start-up rather than at somebody's first attempt to
 * sign in, which is the worst moment to discover it: a provider with half its credentials, a
 * provider with no session secret to mint against, or a session secret configured with no provider
 * to use it.
 */
function authConfig(
  environment: Environment,
  google: OAuthClient | undefined,
): AuthConfig | undefined {
  const microsoft = microsoftAuth(environment);
  const okta = oktaAuth(environment);

  const secret = optional(environment, "BETTER_AUTH_SECRET");
  const baseUrl = url(environment, "BETTER_AUTH_URL");

  if (!google && !microsoft && !okta) {
    if (secret || baseUrl) {
      throw new Error(
        "BETTER_AUTH_SECRET or BETTER_AUTH_URL is set but no identity provider is. Configure GOOGLE_OAUTH_*, MICROSOFT_OAUTH_* or OKTA_OAUTH_*, or unset both",
      );
    }
    return undefined;
  }
  if (!secret) {
    throw new Error("Sign-in requires BETTER_AUTH_SECRET");
  }
  if (secret.length < 32) {
    throw new Error("BETTER_AUTH_SECRET must be at least 32 characters");
  }
  if (!baseUrl) {
    throw new Error("Sign-in requires BETTER_AUTH_URL");
  }

  /*
   * Somebody has to be an administrator, and only this says who.
   *
   * The role is written from this list and there is no route anywhere that changes one, so a
   * deployment that configures sign-in without it admits everybody as a plain user, shows nobody
   * the admin screens, and offers no way to promote anyone. Refusing at start-up is the only cheap
   * moment to catch that; the expensive one is after the first person has signed in.
   */
  const initialAdminEmails = commaSeparated(
    environment,
    "INITIAL_ADMIN_EMAILS",
  );
  if (initialAdminEmails.length === 0) {
    throw new Error(
      "Sign-in requires INITIAL_ADMIN_EMAILS naming at least one administrator. Nothing else grants the role, and no screen can promote somebody once the deployment is running",
    );
  }

  /**
   * Who may sign in, as distinct from who is an administrator once they have.
   *
   * Normalised through the same function the matcher uses, so a rule cannot mean one thing when
   * written and another when matched.
   */
  const namedDomains = commaSeparated(
    environment,
    "SIGNIN_ALLOWED_EMAIL_DOMAINS",
  );
  const allowedEmailDomains = namedDomains
    .map(normalizeDomain)
    .filter((domain): domain is string => domain !== undefined);

  /*
   * A list that names nothing is not an empty list, and the difference is every sign-in.
   *
   * `commaSeparated` drops blank entries BEFORE this normalisation rather than after it, so `@`,
   * `.` and `@.` each survive it and then normalise to nothing. That leaves a non-empty list no
   * address can ever match, every visitor refused at the door, and nothing said at boot. The same
   * reasoning INITIAL_ADMIN_EMAILS gives three lines up applies: start-up is the cheap moment to
   * catch it, and somebody's sign-in is the expensive one.
   */
  if (namedDomains.length > 0 && allowedEmailDomains.length === 0) {
    throw new Error(
      "SIGNIN_ALLOWED_EMAIL_DOMAINS is set but names no domain, so every sign-in would be refused. Write it as example.com,example.co.uk",
    );
  }

  /*
   * A list this deployment cannot enforce is worse than no list.
   *
   * `common` is multi-tenant, and OpenBot never sets `requireEmailVerification` or reads
   * `users.emailVerified`, so the address a rule is applied to is one the signing-in tenant's own
   * administrator wrote. Anybody may create a tenant. So an allowlist under `common` refuses the
   * honest and admits the rest, while reading on the Boundaries page as though it were a control.
   *
   * Refused rather than warned BECAUSE the operator has said what they want: they named domains.
   * The warning below is for the deployment that has said nothing, where multi-tenant may well be
   * the intent.
   */
  if (allowedEmailDomains.length > 0 && namesNoDirectory(microsoft?.tenantId)) {
    throw new Error(
      `SIGNIN_ALLOWED_EMAIL_DOMAINS names domains, but MICROSOFT_OAUTH_TENANT_ID is \`${microsoft?.tenantId}\`, which names no directory and admits accounts from any of them: the address the list is checked against is one the signing-in tenant writes for itself, so the list cannot hold. Set your directory GUID.`,
    );
  }

  /*
   * Nothing at all deciding who may sign in, on a deployment that is deployed. A warning rather
   * than a refusal, because a genuinely multi-tenant deployment is a real thing; arriving there by
   * setting nothing is the case worth naming.
   */
  if (
    isProduction(environment) &&
    allowedEmailDomains.length === 0 &&
    namesNoDirectory(microsoft?.tenantId)
  ) {
    console.warn(
      "MICROSOFT_OAUTH_TENANT_ID is unset, so it is `common` and any Microsoft account may sign in, including personal ones, and SIGNIN_ALLOWED_EMAIL_DOMAINS names no domain either. Set your directory GUID, or name the domains you admit.",
    );
  }

  return {
    baseUrl,
    secret,
    trustedOrigins: commaSeparated(environment, "TRUSTED_ORIGINS").length
      ? commaSeparated(environment, "TRUSTED_ORIGINS")
      : /*
         * All three spellings of the same place, because this is an allowlist of what a browser
         * sends and not an address anything dials. `localhost` alone refused a browser pointed at
         * `127.0.0.1:3010`, which is the address the rest of this deployment hands out.
         */
        ["http://127.0.0.1:3010", "http://[::1]:3010", "http://localhost:3010"],
    initialAdminEmails,
    allowedEmailDomains,
    ...(google ? { google } : {}),
    ...(microsoft ? { microsoft } : {}),
    ...(okta ? { okta } : {}),
  };
}

/**
 * Entra ID, and which directory it admits.
 *
 * `common` by default, matching Microsoft's own default, and said out loud in `.env.example` because
 * it admits personal Microsoft accounts as well as work ones. A company that means "our staff"
 * wants its directory GUID here.
 */
function microsoftAuth(
  environment: Environment,
): (OAuthClient & { tenantId: string }) | undefined {
  const client = oauthClient(environment, "MICROSOFT");
  if (!client) return undefined;
  return {
    ...client,
    tenantId: optional(environment, "MICROSOFT_OAUTH_TENANT_ID") ?? "common",
  };
}

/**
 * Okta, which is an OIDC provider rather than a named one.
 *
 * The issuer is what makes it a particular Okta rather than Okta in general, so it is required
 * alongside the credentials rather than defaulted to anything.
 */
function oktaAuth(
  environment: Environment,
): (OAuthClient & { issuer: string }) | undefined {
  const client = oauthClient(environment, "OKTA");
  const issuer = url(environment, "OKTA_OAUTH_ISSUER");
  if (!client) {
    if (issuer) {
      throw new Error(
        "OKTA_OAUTH_ISSUER is set but OKTA_OAUTH_CLIENT_ID and OKTA_OAUTH_CLIENT_SECRET are not",
      );
    }
    return undefined;
  }
  if (!issuer) {
    throw new Error(
      "Okta sign-in requires OKTA_OAUTH_ISSUER, such as https://example.okta.com/oauth2/default",
    );
  }
  return { ...client, issuer };
}

/**
 * Resolve the Intelligence contract, or refuse to start.
 *
 * The three addressing values are required together. A partial set is the more dangerous shape than
 * none at all: it means somebody intended to configure Intelligence and got it wrong, so failing on
 * the partial set alone (as this did) let a completely unconfigured deployment through as if that
 * were a choice.
 *
 * COPILOTKIT_LICENSE_TOKEN IS NO LONGER ONE OF THEM. Managed Intelligence issues a single project
 * key and derives entitlement from it, and requiring a second credential here sent people hunting
 * for a token the platform had stopped handing out. It is still read and still forwarded when a
 * deployment sets one, which is what a self-hosted Intelligence with its own licence needs.
 */
function runtimeCapabilities(environment: Environment): RuntimeCapabilities {
  const settings = {
    apiUrl: url(environment, "INTELLIGENCE_API_URL"),
    gatewayWsUrl: url(environment, "INTELLIGENCE_GATEWAY_WS_URL"),
    apiKey: intelligenceApiKey(environment),
    licenseToken: optional(environment, "COPILOTKIT_LICENSE_TOKEN"),
  };

  const missing = Object.entries({
    INTELLIGENCE_API_URL: settings.apiUrl,
    INTELLIGENCE_GATEWAY_WS_URL: settings.gatewayWsUrl,
    "CPK_INTELLIGENCE_API_KEY (or INTELLIGENCE_API_KEY)": settings.apiKey,
  })
    .filter(([, value]) => !value)
    .map(([name]) => name);

  if (missing.length > 0) {
    throw new Error(
      `CopilotKit Intelligence is required and is not configured. Missing: ${missing.join(", ")}`,
    );
  }

  /*
   * Optional, and only ever a second address for the same gateway. The browser opens the gateway
   * itself, at the address `/info` gives it, so a server that reaches Intelligence somewhere the
   * browser cannot follow names the browser's address here. The server in OpenBot Desktop's
   * container does: it reaches local Intelligence at `host.docker.internal`, and the window on the
   * host reaches the same gateway at `localhost`. Unset, the browser is given `gatewayWsUrl`, as
   * before.
   */
  const browserGatewayWsUrl = url(
    environment,
    "INTELLIGENCE_BROWSER_GATEWAY_WS_URL",
  );

  return {
    mode: "intelligence",
    durableHistory: true,
    intelligence: {
      ...(settings as IntelligenceSettings),
      ...(browserGatewayWsUrl ? { browserGatewayWsUrl } : {}),
    },
  };
}

/**
 * Whether a Bot may reach addresses inside this deployment's own network.
 *
 * Off unless asked for, and the asking is only allowed on a laptop. The switch exists so that a
 * local deployment can browse the services running beside it; what it turns off is not one rule but
 * the whole private-address floor, in navigation and in the endpoint a Bot may be registered
 * against, so with it on a signed-in person can point a Bot at a link-local address.
 *
 * Refused in production for the reason the example encryption key is: the way a deployment ends up
 * with it is not forgetting to set something, it is copying `.env.example`, which shipped it on. The
 * cloud metadata addresses are refused underneath this either way — see `computer/target.ts` — but
 * that floor is the last one, not the only one worth keeping.
 */
/**
 * The private addresses this deployment will let an agent be registered at.
 *
 * A comma-separated list of hosts, each optionally with a port: `agents.internal`,
 * `10.0.0.42:9000`. Matching is exact, so a name with a port pins that port and a name without one
 * covers any port on that host. No suffixes and no wildcards, because a pattern that widens by
 * accident is the usual way a host check fails, and naming three addresses is not onerous.
 *
 * A scheme or a path is a mistake worth catching here rather than at the first registration that
 * silently never matches, so both are refused with the offending entry named.
 */
function agentEndpointAllowedHosts(
  environment: NodeJS.ProcessEnv,
): ReadonlySet<string> {
  const named = commaSeparated(environment, "AGENT_ENDPOINT_ALLOWED_HOSTS");
  const hosts = new Set<string>();
  for (const entry of named) {
    const host = entry.trim().toLowerCase();
    if (!host) continue;
    if (host.includes("/") || host.includes("://")) {
      throw new Error(
        `AGENT_ENDPOINT_ALLOWED_HOSTS entry "${entry}" must be a host, optionally with a port, and not a URL.`,
      );
    }
    if (host.includes("*")) {
      throw new Error(
        `AGENT_ENDPOINT_ALLOWED_HOSTS entry "${entry}" must name one host. Patterns are not accepted: list each address instead.`,
      );
    }
    hosts.add(normalizeAllowedHost(entry, host));
  }
  return hosts;
}

/**
 * An IPv6 entry, spelled the way the endpoint check will see it.
 *
 * `namedAsAllowed` compares against `URL.hostname`, which the parser canonicalises: compressed,
 * lower-case, in brackets. An entry kept as written matched only when the operator happened to
 * write it that way, so `[0:0:0:0:0:0:0:1]:8443` was a line that silently never matched, which is
 * the failure the URL and wildcard refusals above exist to prevent. Stripping the brackets instead
 * folded two different names into one: `[::1]:8443`, an address and a port, and `[::1:8443]`, an
 * address, both became `::1:8443`, so naming either admitted the other.
 *
 * The address goes through the URL parser rather than a hand-written normaliser, so the spelling
 * here is the parser's own and cannot drift from it. The port is kept as written, since the parser
 * drops a scheme's default port and an operator who wrote `:80` meant that port. A bracketed entry
 * the parser refuses is not an address, and is refused the way a URL is: at boot, naming the entry.
 */
function normalizeAllowedHost(entry: string, host: string): string {
  if (!host.startsWith("[")) return host;
  const close = host.indexOf("]");
  const address = close === -1 ? host : host.slice(0, close + 1);
  const port = close === -1 ? "" : host.slice(close + 1);
  const refusal = () =>
    new Error(
      `AGENT_ENDPOINT_ALLOWED_HOSTS entry "${entry}" must be a host, optionally with a port, and not a URL.`,
    );
  if (port && !/^:\d{1,5}$/.test(port)) throw refusal();
  let hostname: string;
  try {
    hostname = new URL(`http://${address}`).hostname;
  } catch {
    throw refusal();
  }
  return `${hostname}${port}`;
}

function privateHostsAllowed(environment: Environment): boolean {
  if (optional(environment, "AGENT_COMPUTER_ALLOW_PRIVATE_HOSTS") !== "true") {
    return false;
  }

  // Through `isProduction`, so the comparison trims. Read raw, `NODE_ENV="production "` out of an
  // env file would slip past a gate that the switch beside it, which does trim, would still trip.
  if (isProduction(environment)) {
    throw new Error(
      "AGENT_COMPUTER_ALLOW_PRIVATE_HOSTS=true is for local development only: it lets a Bot reach this deployment's own network. Remove it from this deployment's environment.",
    );
  }
  console.warn(
    "AGENT_COMPUTER_ALLOW_PRIVATE_HOSTS=true lets a Bot reach this machine's own services. Fine locally, and for local development only. Remove it before deploying.",
  );

  return true;
}

/**
 * A duration a person would write, as milliseconds.
 *
 * `30m` rather than `1800000`, because this one is read and edited by whoever is deciding how long a
 * computer may sit idle, and a wrong number of zeroes there is either a computer that never sleeps
 * or one that vanishes mid-task. Plain digits are still milliseconds, so anything already set keeps
 * its meaning.
 */
export function durationMs(value: string): number {
  const match = /^(\d+)\s*(ms|s|m|h)?$/i.exec(value.trim());
  if (!match) {
    throw new Error(
      `"${value}" is not a duration. Write it as 30s, 30m, 2h, or a plain number of milliseconds.`,
    );
  }
  const amount = Number(match[1]);
  switch (match[2]?.toLowerCase()) {
    case "h":
      return amount * 3_600_000;
    case "m":
      return amount * 60_000;
    case "s":
      return amount * 1_000;
    default:
      return amount;
  }
}

function browserConfig(
  environment: Environment,
): Pick<DeploymentConfig, "browser" | "browserAbsent"> {
  const address = url(environment, BROWSER_URL_ENV);
  if (!address) {
    // Only where there is no browser of the person's own: one that runs needs no reason why it does not.
    const absent = optional(environment, BROWSER_ABSENT_ENV);
    return absent && isBrowserAbsence(absent) ? { browserAbsent: absent } : {};
  }
  const token = optional(environment, "COMPUTER_TOKEN");
  return { browser: { url: address, ...(token ? { token } : {}) } };
}

function computerConfig(environment: Environment): ComputerConfig | undefined {
  const supervisorAddress = optional(environment, "COMPUTER_SUPERVISOR_URL");
  const sharedAddress = optional(environment, "AGENT_COMPUTER_URL");
  const sandboxNamespace = optional(environment, "COMPUTER_SANDBOX_NAMESPACE");
  if (!supervisorAddress && !sharedAddress && !sandboxNamespace) {
    return undefined;
  }

  /*
   * The secret the computers require. Without it every call to a computer is refused, and that is the
   * intended failure: `agent-computer` drives a browser holding real logins and must not answer
   * unauthenticated callers that can reach its port.
   */
  const computerToken = optional(environment, "COMPUTER_TOKEN");

  const allowPrivateHosts = privateHostsAllowed(environment);
  const policy = actionPolicy(environment);

  /*
   * Checked before the other two, because a deployment that named a namespace means the cluster to
   * make the computers, and a stray `AGENT_COMPUTER_URL` left in an environment would otherwise
   * quietly put every Bot back on one shared browser.
   */
  if (sandboxNamespace) {
    return {
      provider: "sandbox",
      namespace: sandboxNamespace,
      idleAfterMs: durationMs(
        optional(environment, "COMPUTER_SANDBOX_IDLE_AFTER") ?? "30m",
      ),
      templateFile:
        optional(environment, "COMPUTER_SANDBOX_TEMPLATE_FILE") ??
        "/etc/openbot/sandbox-template.json",
      allowPrivateHosts,
      ...(computerToken ? { token: computerToken } : {}),
      ...(policy ? { policy } : {}),
    };
  }

  const supervisorUrl = url(environment, "COMPUTER_SUPERVISOR_URL");
  if (supervisorUrl) {
    const supervisorToken = optional(environment, "SUPERVISOR_TOKEN");
    return {
      provider: "docker",
      baseUrl: supervisorUrl,
      allowPrivateHosts,
      ...(supervisorToken ? { supervisorToken } : {}),
      ...(computerToken ? { token: computerToken } : {}),
      ...(policy ? { policy } : {}),
    };
  }

  const baseUrl = url(environment, "AGENT_COMPUTER_URL");
  if (!baseUrl) {
    return undefined;
  }

  return {
    provider: "shared",
    baseUrl,
    allowPrivateHosts,
    ...(computerToken ? { token: computerToken } : {}),
    ...(policy ? { policy } : {}),
  };
}

/**
 * The action policy, as JSON in one variable.
 *
 * Refuses to start on malformed JSON or a policy of the wrong shape, rather than falling back to the
 * default. An operator who wrote a rule and mistyped it would otherwise get a running deployment that
 * silently permits what they had just tried to forbid, and no indication that anything was wrong.
 * Configuration the product cannot honour belongs at the boot boundary; see the note at the top.
 */
function actionPolicy(environment: Environment): ActionPolicy | undefined {
  const raw = optional(environment, "AGENT_COMPUTER_POLICY");
  if (!raw) {
    return undefined;
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch {
    throw new Error("AGENT_COMPUTER_POLICY must be valid JSON");
  }

  const result = parseActionPolicy(parsed);
  if (!result.ok) {
    throw new Error(`AGENT_COMPUTER_POLICY is invalid: ${result.error}`);
  }
  return result.policy;
}

/**
 * How long silence on a Bot's stream is allowed to last.
 *
 * Refuses to start on anything that is not a whole number of milliseconds, rather than falling back
 * to the default. Same reasoning as the action policy above it: an operator who meant to write a
 * two-minute timeout and typed something else would otherwise get a running deployment with a
 * silently different boundary, and no indication that anything was wrong.
 *
 * Zero is a legitimate value and means off. It is not the same as a malformed one.
 */
function accessibilityEnabled(environment: Environment): boolean {
  const off = optional(environment, "OPENBOT_ACCESSIBILITY_DISABLED");
  return off !== "true" && off !== "1";
}

/**
 * Whether a Bot may draw an interface it wrote itself.
 *
 * Default-on, matching the product capability the browser can already render. Operators who cannot
 * allow generated interfaces can explicitly opt out. `false` is the documented spelling and `0` is
 * accepted alongside it as the conventional off value used by environment-driven switches.
 *
 * Anything else leaves the capability on. A typo should not silently become an opt-out, and the
 * capability must stay consistent between runtime and browser projection.
 *
 * The answer has to reach the browser as well as the runtime, which is why it ends up on
 * /api/capabilities rather than staying server-side. Enabling only the runtime half would leave the
 * browser never offering the tool; enabling only the browser half would have a Bot generate a whole
 * interface that nothing renders. See DeploymentConfig.generativeUi.
 */
function generativeUiEnabled(environment: Environment): boolean {
  const value = optional(environment, "OPENBOT_GENERATIVE_UI");
  return value !== "false" && value !== "0";
}

/** Same rule as generated interfaces: on unless explicitly "false" or "0". */
function selfHostBannerEnabled(environment: Environment): boolean {
  const value = optional(environment, "OPENBOT_SELF_HOST_BANNER");
  return value !== "false" && value !== "0";
}

/**
 * How long the audit trail is kept.
 *
 * Refused rather than coerced, like everything else here. "We accepted your retention policy but not
 * the one you wrote" is a bad answer about a control an auditor will ask to see, and a typo that
 * silently became 0 would delete the trail rather than keep it.
 */
function auditRetentionDays(environment: Environment): number | undefined {
  const raw = optional(environment, "AUDIT_RETENTION_DAYS");
  if (!raw) return undefined;

  const days = Number(raw);
  if (!Number.isInteger(days) || days < 1) {
    throw new Error(
      "AUDIT_RETENTION_DAYS must be a whole number of days, at least 1. Leave it unset to keep the audit trail forever.",
    );
  }
  return days;
}

function agentStallTimeoutMs(environment: Environment): number {
  const raw = optional(environment, "AGENT_STALL_TIMEOUT_MS");
  if (!raw) {
    return 0;
  }

  const milliseconds = Number(raw);
  if (!Number.isInteger(milliseconds) || milliseconds < 0) {
    throw new Error(
      "AGENT_STALL_TIMEOUT_MS must be a whole number of milliseconds, or 0 to switch the watchdog off",
    );
  }
  return milliseconds;
}

/** Where the API listens when nothing says otherwise: what `.env.example` and the image ship. */
const DEFAULT_PORT = 3001;

/**
 * The port the API listens on, from either of its two names.
 *
 * `PORT` and `SERVER_PORT` name one number: either moves the server, and two that disagree are
 * refused at boot rather than half-applied. Read through `optional` like every other setting here,
 * and that is the point. An unset variable declared in a compose file, or left as `PORT=` in a
 * `.env`, arrives as an empty string rather than as absent, so `process.env.PORT ??
 * process.env.SERVER_PORT` never fell through to the second name, and `Number.parseInt("")` is
 * `NaN`. Given `NaN`, `Bun.serve` binds an ephemeral port: the server came up somewhere nobody had
 * asked for, `SERVER_PORT` ignored, and the script polling it reported a server that never
 * started — the failure #312 set out to remove, back through the other name.
 *
 * A value that is not a whole port number is refused for the reason the caps above are: `30o1`
 * used to start the server on port 30, and a typo has to fail where somebody is looking.
 */
function serverPort(environment: Environment): number {
  const read = (name: string): number | undefined => {
    const raw = optional(environment, name);
    if (raw === undefined) return undefined;
    const value = Number(raw);
    if (!Number.isInteger(value) || value < 1 || value > 65535) {
      throw new Error(`${name} must be a whole number between 1 and 65535`);
    }
    return value;
  };
  const port = read("PORT");
  const serverPort = read("SERVER_PORT");
  if (port !== undefined && serverPort !== undefined && port !== serverPort) {
    throw new Error(
      `PORT (${port}) and SERVER_PORT (${serverPort}) disagree: set one or set both to the same value`,
    );
  }
  return port ?? serverPort ?? DEFAULT_PORT;
}

export function loadConfig(
  environment: Environment = process.env,
): DeploymentConfig {
  const google = oauthClient(environment, "GOOGLE");
  const auth = authConfig(environment, google);
  const organizationAuthValue = optional(
    environment,
    "OPENBOT_ORGANIZATION_AUTH_URL",
  );
  const organizationAuthUrl = organizationAuthValue
    ? organizationAuthority(organizationAuthValue)
    : undefined;
  const managedAgent = managedAgentConfig(environment);
  const githubApp = githubAppConfig(environment);
  const publicUrl = (
    optional(environment, "OPENBOT_PUBLIC_URL") ?? auth?.baseUrl
  )?.replace(/\/+$/, "");
  // GitHub sends people back to this address after they approve. Without it linking is silently
  // switched off, so say so at start-up instead.
  if (githubApp && !publicUrl) {
    throw new Error(
      "GITHUB_APP_CLIENT_ID needs OPENBOT_PUBLIC_URL (or BETTER_AUTH_URL) so GitHub can send people back to this server.",
    );
  }
  const workerSharedSecret = optional(environment, "WORKER_SHARED_SECRET");
  const deploymentKey = keyEncryptionKey(environment);
  const webBotAuth = webBotAuthFromEnv(environment, {
    publicUrl,
    keyEncryptionKey: deploymentKey,
  });

  return {
    port: serverPort(environment),
    transcription: transcriptionConfig(environment),
    voice: voiceConfig(environment),
    databaseUrl: required(environment, "DATABASE_URL"),
    keyEncryptionKey: deploymentKey,
    ...(webBotAuth ? { webBotAuth } : {}),
    ...(managedAgent ? { managedAgent } : {}),
    ...(githubApp ? { githubApp } : {}),
    agentEndpointAllowedHosts: agentEndpointAllowedHosts(environment),
    deploymentId: optional(environment, "DEPLOYMENT_ID"),
    composioApiKey: optional(environment, "COMPOSIO_API_KEY"),
    arcadeApiKey: optional(environment, "ARCADE_API_KEY"),
    brokerProvider: brokerProvider(environment),
    publicUrl,
    appUrl: (
      optional(environment, "OPENBOT_APP_URL") ??
      commaSeparated(environment, "TRUSTED_ORIGINS")[0] ??
      optional(environment, "OPENBOT_PUBLIC_URL") ??
      auth?.baseUrl
    )?.replace(/\/+$/, ""),
    tenantPackageDirectory:
      optional(environment, "TENANT_PACKAGE_DIR") ?? "../examples/fintech",
    runtime: runtimeCapabilities(environment),
    recorder: { extraExtensionIds: recorderExtraExtensionIds(environment) },
    learning: learningDefault(environment),
    learningAutoAssign: learningAutoAssignEnabled(environment),
    ...learningSetupCredential(environment),
    memoryDefaults: {
      sources: switchedOn(environment, "OPENBOT_MEMORY_SOURCE_DEFAULTS"),
      research: switchedOn(environment, "OPENBOT_PROACTIVE_DEFAULTS"),
    },
    agentStallTimeoutMs: agentStallTimeoutMs(environment),
    auditRetentionDays: auditRetentionDays(environment),
    oauth: { google },
    auth,
    ...(organizationAuthUrl ? { organizationAuthUrl } : {}),
    /*
     * The authority short-circuits this, and that ordering is load-bearing: a white-label
     * deployment naming an external authority lets it win, and `singleUserAllowed` is never
     * reached and so cannot refuse a combination that already resolves.
     */
    singleUser:
      !organizationAuthUrl &&
      singleUserAllowed(environment, configuredAuthProviders(auth).length > 0),
    accessibility: accessibilityEnabled(environment),
    generativeUi: generativeUiEnabled(environment),
    selfHostBanner: selfHostBannerEnabled(environment),
    ...(optional(environment, "APP_DIST_DIR")
      ? { appDistDir: optional(environment, "APP_DIST_DIR") as string }
      : {}),
    computer: computerConfig(environment),
    ...browserConfig(environment),
    handoff: handoffCaps(environment),
    ...(optional(environment, "AGENT_TOOL_TOKEN")
      ? { agentToolToken: optional(environment, "AGENT_TOOL_TOKEN") as string }
      : {}),
    ...(workerSharedSecret ? { workerSharedSecret } : {}),
  };
}

/**
 * Same rule as generated interfaces: on unless explicitly "false" or "0". A container named in the
 * environment is a choice, so there is nothing to assign.
 */
function learningAutoAssignEnabled(environment: Environment): boolean {
  if (optional(environment, "CPK_INTELLIGENCE_LEARNING_CONTAINER_ID"))
    return false;
  const value = optional(environment, "OPENBOT_LEARNING_AUTO_ASSIGN");
  return value !== "false" && value !== "0";
}

/** Comma separated, each trimmed, each a Chrome extension id (32 letters a to p). */
function recorderExtraExtensionIds(environment: Environment): string[] {
  const value = optional(environment, "OPENBOT_RECORDER_EXTRA_EXTENSION_IDS");
  if (!value) return [];
  const ids = value.split(",").map((id) => id.trim());
  for (const id of ids) {
    if (!/^[a-p]{32}$/.test(id))
      throw new Error(
        `OPENBOT_RECORDER_EXTRA_EXTENSION_IDS lists "${id}", which is not an extension id. An id is 32 letters from a to p; separate several with commas.`,
      );
  }
  return ids;
}

/** On unless the variable is "false" or "0", the rule every default-on switch here follows. */
function switchedOn(environment: Environment, name: string): boolean {
  const value = optional(environment, name);
  return value !== "false" && value !== "0";
}

/** The service token and its project, both or neither. See `DeploymentConfig.learningSetup`. */
function learningSetupCredential(environment: Environment): {
  learningSetup?: { serviceToken: string; projectId: string };
} {
  const serviceToken = optional(environment, "INTELLIGENCE_SERVICE_TOKEN");
  const projectId = optional(environment, "INTELLIGENCE_PROJECT_ID");
  if (!serviceToken && !projectId) return {};
  if (!serviceToken || !projectId)
    throw new Error(
      "INTELLIGENCE_SERVICE_TOKEN and INTELLIGENCE_PROJECT_ID go together: the token creates the openbot Learning container in that project. Set both, or neither.",
    );
  if (!/^[1-9][0-9]{0,15}$/.test(projectId))
    throw new Error(
      "INTELLIGENCE_PROJECT_ID must be the Intelligence project's numeric ID.",
    );
  return { learningSetup: { serviceToken, projectId } };
}

/** Optional container default; the enabled preference alone does not collect or deliver. */
function learningDefault(environment: Environment): LearningTarget | undefined {
  const containerId = optional(
    environment,
    "CPK_INTELLIGENCE_LEARNING_CONTAINER_ID",
  );
  if (!containerId) return undefined;
  if (!isLearningContainerId(containerId))
    throw new TypeError(
      "CPK_INTELLIGENCE_LEARNING_CONTAINER_ID must use 1–64 lowercase letters, numbers, and single hyphens.",
    );
  const revision = optional(environment, "CPK_INTELLIGENCE_SKILLS_REVISION");
  return { containerId, ...(revision ? { revision } : {}) };
}