sailfork / t3code-github / apps/ server/ src/ policy/ managedProviders.ts

import {
  AntigravitySettings,
  ClaudeSettings,
  CodexSettings,
  defaultInstanceIdForDriver,
  disallowedProviderMessage,
  type ManagedProviderInstance,
  type ManagedProviderLimits,
  type ManagedPolicySummary,
  ProviderDriverKind,
  type ProviderInstanceConfig,
  type ProviderInstanceEnvironmentVariable,
  type ProviderInstanceId,
  resolveProviderInstanceEnabled,
  type RuntimeMode,
  type ServerSettings,
} from "@t3tools/contracts";
import { acpRegistryClient } from "@t3tools/provider-acp-registry/client";
import { cursorClient } from "@t3tools/provider-cursor/client";
import { fxClient } from "@t3tools/provider-fx/client";
import { grokClient } from "@t3tools/provider-grok/client";
import { kiroClient } from "@t3tools/provider-kiro/client";
import { museClient } from "@t3tools/provider-muse/client";
import { openCodeClient } from "@t3tools/provider-opencode/client";
import { piClient } from "@t3tools/provider-pi/client";
import type { ProviderClientDefinition } from "@t3tools/provider-core/client";

interface KnownDriver {
  readonly label: string;
  readonly configFields: ReadonlySet<string>;
  readonly hasDefaultInstance: boolean;
}

const known = (
  driverKind: string,
  label: string,
  settingsSchema: { readonly fields: object },
  hasDefaultInstance = true,
) =>
  [
    ProviderDriverKind.make(driverKind),
    { label, configFields: new Set(Object.keys(settingsSchema.fields)), hasDefaultInstance },
  ] as const;

const PACKAGED_CLIENTS: ReadonlyArray<ProviderClientDefinition> = [
  cursorClient,
  grokClient,
  fxClient,
  kiroClient,
  museClient,
  openCodeClient,
  piClient,
  acpRegistryClient,
];

/**
 * Fields that make an instance launch without the settings a pin sets: managed Codex runs T3's own
 * runtime against OpenAI, and a server URL points OpenCode at a server it does not start. A policy
 * that owns a pin owns these too, holding each at the value given here, which clients still send
 * when they add an instance.
 */
const PIN_BYPASS_FIELDS: ReadonlyMap<
  ProviderDriverKind,
  Readonly<Record<string, unknown>>
> = new Map<ProviderDriverKind, Readonly<Record<string, unknown>>>([
  [ProviderDriverKind.make("codex"), { setupMode: "existing" }],
  [ProviderDriverKind.make("opencode"), { serverUrl: "" }],
]);

/** Drivers this build knows, by the names users see; a policy naming any other is refused. */
const KNOWN_DRIVERS: ReadonlyMap<ProviderDriverKind, KnownDriver> = new Map([
  known("codex", "Codex", CodexSettings),
  known("claudeAgent", "Claude", ClaudeSettings),
  known("antigravity", "Antigravity", AntigravitySettings),
  ...PACKAGED_CLIENTS.map((client) =>
    known(client.driverKind, client.label, client.settingsSchema, client.hasDefaultInstance),
  ),
]);

/** Each driver a policy may name, with the label users see. */
export const knownDriverLabels = () =>
  Array.from(KNOWN_DRIVERS, ([driver, { label }]) => ({ driver, label }));

const PINNED_CONFIG_FIELDS = ["binaryPath", "launchArgs"] as const;
type PinnedConfigField = (typeof PINNED_CONFIG_FIELDS)[number];

/**
 * Fields that decide what a provider starts and reads on startup; a driver has those its schema
 * has. Under a ceiling they are the administrator's: a wrapper binary, a skip-permissions flag, or
 * a config directory with allow rules each outrank T3 Code's mode, and no flag filter stops a wrapper.
 */
const LAUNCH_CONFIG_FIELDS = [
  "binaryPath",
  "launchArgs",
  "homePath",
  "shadowHomePath",
  "commandPath",
  "commandArgs",
  "serverUrl",
] as const;

export type ProviderWriteVerdict =
  | { readonly _tag: "Allowed"; readonly settings: ServerSettings }
  | { readonly _tag: "Locked"; readonly path: string }
  | {
      readonly _tag: "Disallowed";
      readonly instanceId: ProviderInstanceId;
      readonly label: string;
    };

/**
 * How a policy's `limits.providers` shapes provider instances. Like settings locks, pinned
 * fields are laid over instances on every read and never written to the user's settings file.
 */
export interface ManagedProviders {
  readonly isDriverAllowed: (driver: ProviderDriverKind) => boolean;
  /** Lay pinned fields over every instance of a pinned driver, its default instance included. */
  readonly applyLimits: (settings: ServerSettings) => ServerSettings;
  /**
   * Vet a write from stored `current` to `next`. Refuses enabling a disallowed driver and moving
   * a locked field off its pinned value. Pinned values a client sends back are dropped, so the
   * user's own values return once the policy is gone.
   */
  readonly vetWrite: (current: ServerSettings, next: ServerSettings) => ProviderWriteVerdict;
  /**
   * Per driver, the instance fields users cannot change, for clients. `environment` alone means
   * every variable.
   */
  readonly lockedInstanceFields: Readonly<Record<string, ReadonlyArray<string>>>;
}

export const unmanagedProviders: ManagedProviders = {
  isDriverAllowed: () => true,
  applyLimits: (settings) => settings,
  vetWrite: (_current, next) => ({ _tag: "Allowed", settings: next }),
  lockedInstanceFields: {},
};

const labelFor = (driver: ProviderDriverKind) => KNOWN_DRIVERS.get(driver)?.label ?? driver;

/** Why the policy clients were told about keeps `driver` from running, or undefined when it may run. */
export const disallowedDriverReason = (
  summary: ManagedPolicySummary | undefined,
  driver: ProviderDriverKind,
): string | undefined => {
  const allowed = summary?.limits?.providers?.allowedDrivers;
  return allowed === undefined || allowed.includes(driver)
    ? undefined
    : disallowedProviderMessage(summary?.organization, labelFor(driver));
};

/**
 * Variables that replace a provider's launch configuration. From the environment that starts the
 * server they are ignored under any policy, which can lock launch arguments in more than one way;
 * from an instance's own variables they are ignored when the policy locks launch arguments.
 */
const LAUNCH_OVERRIDE_VARIABLES = ["T3CODE_CODEX_LAUNCH_ARGS"] as const;

/** The environment provider drivers launch from under the policy clients were told about. */
export const providerHostEnvironment = (
  summary: ManagedPolicySummary | undefined,
  environment: NodeJS.ProcessEnv,
): NodeJS.ProcessEnv => {
  if (summary === undefined) return environment;
  const next = { ...environment };
  for (const name of Object.keys(next)) {
    if (LAUNCH_OVERRIDE_VARIABLES.some((override) => override === name.toUpperCase())) {
      delete next[name];
    }
  }
  return next;
};

/** Each driver's home variable, and the settings that rewrite it at launch. */
const HOME_VARIABLES: ReadonlyMap<
  ProviderDriverKind,
  { readonly variable: string; readonly fields: ReadonlyArray<string> }
> = new Map([
  [ProviderDriverKind.make("claudeAgent"), { variable: "CLAUDE_CONFIG_DIR", fields: ["homePath"] }],
  [
    ProviderDriverKind.make("codex"),
    { variable: "CODEX_HOME", fields: ["homePath", "shadowHomePath"] },
  ],
]);

const configRecord = (instance: ProviderInstanceConfig | undefined): Record<string, unknown> =>
  instance?.config !== null &&
  typeof instance?.config === "object" &&
  !Array.isArray(instance.config)
    ? (instance.config as Record<string, unknown>)
    : {};

/** Empty strings and empty lists are how clients clear a field, so they count as unset. */
const configValue = (instance: ProviderInstanceConfig | undefined, field: string) => {
  const value = configRecord(instance)[field];
  return value === "" || (Array.isArray(value) && value.length === 0) ? undefined : value;
};

const sameValue = (left: unknown, right: unknown) =>
  left === right || JSON.stringify(left) === JSON.stringify(right);

const sameVariable = (
  left: ProviderInstanceEnvironmentVariable | undefined,
  right: ProviderInstanceEnvironmentVariable | undefined,
) =>
  left === right ||
  (left !== undefined &&
    right !== undefined &&
    // A secret reference is an object, and a decoded copy is never the stored one.
    sameValue(left.value, right.value) &&
    left.sensitive === right.sensitive);

const pinnedFields = (pin: ManagedProviderInstance): ReadonlyArray<PinnedConfigField> =>
  PINNED_CONFIG_FIELDS.filter((field) => pin[field] !== undefined);

/**
 * What the administrator owns on one driver's instances. `config` fields take the pin or the
 * default, never the user's value; `fill` fields take the pin only where the user left them empty.
 * `environment`: `all` runs with only pinned variables, `locked` lets them win, `fill` fills gaps.
 */
interface DriverRule {
  readonly pin: ManagedProviderInstance | undefined;
  readonly config: ReadonlyArray<string>;
  readonly fill: ReadonlyArray<PinnedConfigField>;
  readonly environment: "all" | "locked" | "fill";
}

const pinnedValue = (pin: ManagedProviderInstance | undefined, field: string): unknown =>
  pin === undefined ? undefined : (pin as Record<string, unknown>)[field];

const overlayInstance = (
  instance: ProviderInstanceConfig,
  rule: DriverRule,
  variableKey: (name: string) => string,
): ProviderInstanceConfig => {
  const config = { ...configRecord(instance) };
  for (const field of rule.config) {
    const value = pinnedValue(rule.pin, field);
    if (value === undefined) delete config[field];
    else config[field] = value;
  }
  for (const field of rule.fill) {
    if (configValue(instance, field) === undefined) config[field] = rule.pin?.[field];
  }
  const pinnedEnvironment = (rule.pin?.environment ?? []).map((variable) => ({
    name: variable.name,
    value: variable.value,
    sensitive: false,
  }));
  const pinnedByName = new Map(
    pinnedEnvironment.map((variable) => [variableKey(variable.name), variable]),
  );
  const environment: Array<NonNullable<ProviderInstanceConfig["environment"]>[number]> =
    rule.environment === "all" ? pinnedEnvironment : [];
  if (rule.environment !== "all") {
    const seen = new Set<string>();
    // A user's override would replace launch arguments the administrator locked.
    const overrides = rule.config.includes("launchArgs")
      ? new Set(LAUNCH_OVERRIDE_VARIABLES.map(variableKey))
      : new Set<string>();
    // The last entry for a name wins at launch, so a lock replaces every entry with that name.
    for (const variable of instance.environment ?? []) {
      const key = variableKey(variable.name);
      if (overrides.has(key)) continue;
      const pinned = rule.environment === "locked" ? pinnedByName.get(key) : undefined;
      if (pinned === undefined) environment.push(variable);
      else if (!seen.has(key)) environment.push(pinned);
      seen.add(key);
    }
    for (const pinned of pinnedEnvironment) {
      if (!seen.has(variableKey(pinned.name))) environment.push(pinned);
    }
  }
  const { config: _config, environment: _environment, ...envelope } = instance;
  return {
    ...envelope,
    ...(instance.config === undefined && Object.keys(config).length === 0 ? {} : { config }),
    ...(environment.length === 0 ? {} : { environment }),
  };
};

/**
 * Build the overlay for `limits.providers` and `limits.maxRuntimeMode`, or say why it cannot be
 * enforced. A ceiling takes each driver's launch fields and its whole `environment`, which can
 * carry `CLAUDE_CONFIG_DIR`, `PATH`, or `NODE_OPTIONS`; a deny list would miss the next one.
 */
export function makeManagedProviders(
  limits: ManagedProviderLimits,
  maxRuntimeMode: RuntimeMode | undefined,
  platform: NodeJS.Platform,
):
  | { readonly _tag: "Valid"; readonly providers: ManagedProviders }
  | { readonly _tag: "Invalid"; readonly reason: string } {
  // Windows reads a variable name without regard to case, so there a lock covers every spelling.
  const variableKey = (name: string) => (platform === "win32" ? name.toUpperCase() : name);
  for (const driver of limits.allowedDrivers ?? []) {
    if (!KNOWN_DRIVERS.has(driver)) {
      return { _tag: "Invalid", reason: `"${driver}" in allowedDrivers is not a known provider` };
    }
  }
  const pins = new Map<ProviderDriverKind, ManagedProviderInstance>();
  for (const [rawDriver, pin] of Object.entries(limits.instances ?? {})) {
    const driver = ProviderDriverKind.make(rawDriver);
    const known = KNOWN_DRIVERS.get(driver);
    if (known === undefined) {
      return { _tag: "Invalid", reason: `"${driver}" in instances is not a known provider` };
    }
    const unsupported = pinnedFields(pin).find((field) => !known.configFields.has(field));
    if (unsupported !== undefined) {
      return {
        _tag: "Invalid",
        reason: `the ${known.label} provider has no ${unsupported} setting`,
      };
    }
    const names = (pin.environment ?? []).map((variable) => variableKey(variable.name));
    if (new Set(names).size !== names.length) {
      return { _tag: "Invalid", reason: `instances.${driver}.environment repeats a variable` };
    }
    pins.set(driver, pin);
  }

  const rules = new Map<ProviderDriverKind, DriverRule>();
  for (const [driver, known] of KNOWN_DRIVERS) {
    const pin = pins.get(driver);
    const bypasses = pin === undefined ? [] : Object.keys(PIN_BYPASS_FIELDS.get(driver) ?? {});
    if (maxRuntimeMode !== undefined) {
      rules.set(driver, {
        pin,
        config: [
          ...LAUNCH_CONFIG_FIELDS.filter((field) => known.configFields.has(field)),
          ...bypasses,
        ],
        fill: [],
        environment: "all",
      });
    } else if (pin !== undefined) {
      // A home path setting rewrites the provider's home variable at launch, so a lock on that
      // variable owns the setting too.
      const home = HOME_VARIABLES.get(driver);
      const homeLocked =
        home !== undefined &&
        (pin.environment ?? []).some(
          (variable) => variableKey(variable.name) === variableKey(home.variable),
        );
      rules.set(driver, {
        pin,
        config: pin.locked
          ? [...pinnedFields(pin), ...bypasses, ...(homeLocked ? home.fields : [])]
          : [],
        fill: pin.locked ? [] : pinnedFields(pin),
        environment: pin.locked ? "locked" : "fill",
      });
    }
  }

  const allowed =
    limits.allowedDrivers === undefined ? undefined : new Set<string>(limits.allowedDrivers);
  const isDriverAllowed = (driver: ProviderDriverKind) => allowed?.has(driver) ?? true;
  const allowedSelection = (
    settings: ServerSettings,
    selection: { readonly instanceId: ProviderInstanceId } | null | undefined,
  ) =>
    selection == null ||
    isDriverAllowed(
      settings.providerInstances[selection.instanceId]?.driver ??
        ProviderDriverKind.make(selection.instanceId),
    );

  const cache = new WeakMap<ServerSettings, ServerSettings>();
  const applyLimits = (settings: ServerSettings): ServerSettings => {
    const cached = cache.get(settings);
    if (cached !== undefined) return cached;
    const providerInstances: Record<string, ProviderInstanceConfig> = {
      ...settings.providerInstances,
    };
    // Default instances exist without a settings entry until the user edits one; pin them too.
    for (const driver of pins.keys()) {
      const instanceId = defaultInstanceIdForDriver(driver);
      if (KNOWN_DRIVERS.get(driver)?.hasDefaultInstance === false) continue;
      if (providerInstances[instanceId] === undefined) providerInstances[instanceId] = { driver };
    }
    for (const [instanceId, instance] of Object.entries(providerInstances)) {
      const rule = rules.get(instance.driver);
      if (rule !== undefined) {
        providerInstances[instanceId] = overlayInstance(instance, rule, variableKey);
      }
    }
    // A cleared selection falls back to the text generation model, which is resolved afterwards.
    const result: ServerSettings = {
      ...settings,
      providerInstances: providerInstances as ServerSettings["providerInstances"],
      sourceControlWriterModelSelection: allowedSelection(
        settings,
        settings.sourceControlWriterModelSelection,
      )
        ? settings.sourceControlWriterModelSelection
        : null,
      reviewGuideModelSelection: allowedSelection(settings, settings.reviewGuideModelSelection)
        ? settings.reviewGuideModelSelection
        : null,
    };
    cache.set(settings, result);
    return result;
  };

  type Locked = { readonly _tag: "Locked"; readonly path: string };

  /**
   * Vet the environment a client sent. Pinned values it echoes back are dropped; anything else
   * the administrator owns must match what is stored. Returns the environment to store.
   */
  const vetEnvironment = (
    instanceId: string,
    stored: ProviderInstanceConfig | undefined,
    next: ProviderInstanceConfig,
    rule: DriverRule,
  ):
    | Locked
    | {
        readonly _tag: "Kept";
        readonly environment: ReadonlyArray<ProviderInstanceEnvironmentVariable>;
      } => {
    const pinned = rule.pin?.environment ?? [];
    const storedVariable = (name: string) =>
      stored?.environment?.find((existing) => variableKey(existing.name) === variableKey(name));
    const storedUnchanged = (variable: ProviderInstanceEnvironmentVariable) =>
      (stored?.environment ?? []).some((existing) => sameVariable(variable, existing));
    const echoed = (variable: ProviderInstanceEnvironmentVariable) =>
      !variable.sensitive &&
      pinned.some((pin) => pin.name === variable.name && pin.value === variable.value);
    if (rule.environment === "all") {
      // Only the pinned variables were shown, so the user's own stay as stored.
      for (const variable of next.environment ?? []) {
        if (echoed(variable) || storedUnchanged(variable)) continue;
        return { _tag: "Locked", path: `providerInstances.${instanceId}.environment` };
      }
      return { _tag: "Kept", environment: stored?.environment ?? [] };
    }
    let environment: ReadonlyArray<ProviderInstanceEnvironmentVariable> = next.environment ?? [];
    for (const variable of pinned) {
      const sent = environment.find(
        (existing) => variableKey(existing.name) === variableKey(variable.name),
      );
      const kept = storedVariable(variable.name);
      if ((sent !== undefined && echoed(sent)) || sameVariable(sent, kept)) {
        // Put the user's own entries back where it was sent, or drop the echoed policy value.
        const storedEntries = (stored?.environment ?? []).filter(
          (existing) => variableKey(existing.name) === variableKey(variable.name),
        );
        let restored = false;
        environment = environment.flatMap((existing) => {
          if (variableKey(existing.name) !== variableKey(variable.name)) return [existing];
          if (restored) return [];
          restored = true;
          return storedEntries;
        });
      } else if (rule.environment === "locked") {
        return {
          _tag: "Locked",
          path: `providerInstances.${instanceId}.environment.${variable.name}`,
        };
      }
    }
    // The client never saw a launch override the lock hides, so keep the stored one.
    if (rule.config.includes("launchArgs")) {
      const overrides = new Set(LAUNCH_OVERRIDE_VARIABLES.map(variableKey));
      environment = [
        ...environment.filter((variable) => !overrides.has(variableKey(variable.name))),
        ...(stored?.environment ?? []).filter((variable) =>
          overrides.has(variableKey(variable.name)),
        ),
      ];
    }
    return { _tag: "Kept", environment };
  };

  const vetInstance = (
    instanceId: string,
    stored: ProviderInstanceConfig | undefined,
    next: ProviderInstanceConfig,
    rule: DriverRule,
  ): Locked | { readonly _tag: "Kept"; readonly instance: ProviderInstanceConfig | undefined } => {
    const config = { ...configRecord(next) };
    const harmless = PIN_BYPASS_FIELDS.get(next.driver) ?? {};
    for (const field of [...rule.config, ...rule.fill]) {
      const value = configValue(next, field);
      const storedValue = configValue(stored, field);
      if (
        sameValue(value, pinnedValue(rule.pin, field)) ||
        sameValue(value, storedValue) ||
        (field in harmless && sameValue(value, harmless[field]))
      ) {
        if (storedValue === undefined) delete config[field];
        else config[field] = configRecord(stored)[field];
      } else if (rule.config.includes(field)) {
        return { _tag: "Locked", path: `providerInstances.${instanceId}.config.${field}` };
      }
    }
    const vettedEnvironment = vetEnvironment(instanceId, stored, next, rule);
    if (vettedEnvironment._tag === "Locked") return vettedEnvironment;
    const { environment } = vettedEnvironment;
    const { config: _config, environment: _environment, ...envelope } = next;
    const kept: ProviderInstanceConfig = {
      ...envelope,
      ...(Object.keys(config).length === 0 && stored?.config === undefined ? {} : { config }),
      ...(environment.length === 0 ? {} : { environment }),
    };
    // A default instance the client echoed back with only pinned values stays implicit.
    const echoedDefault =
      stored === undefined &&
      instanceId === defaultInstanceIdForDriver(next.driver) &&
      Object.keys(kept).length === 1;
    return { _tag: "Kept", instance: echoedDefault ? undefined : kept };
  };

  const vetWrite = (current: ServerSettings, next: ServerSettings): ProviderWriteVerdict => {
    const providerInstances: Record<string, ProviderInstanceConfig> = {};
    for (const [instanceId, instance] of Object.entries(next.providerInstances)) {
      const stored = current.providerInstances[instanceId as ProviderInstanceId];
      // Clients echo instances with policy fields laid over them, so compare only whether it runs.
      // A driver's default instance runs before it is configured.
      const wasEnabled =
        stored !== undefined
          ? stored.driver === instance.driver && resolveProviderInstanceEnabled(stored)
          : instanceId === defaultInstanceIdForDriver(instance.driver);
      if (
        !isDriverAllowed(instance.driver) &&
        resolveProviderInstanceEnabled(instance) &&
        !wasEnabled
      ) {
        return {
          _tag: "Disallowed",
          instanceId: instanceId as ProviderInstanceId,
          label: labelFor(instance.driver),
        };
      }
      const rule = rules.get(instance.driver);
      if (rule === undefined) {
        providerInstances[instanceId] = instance;
        continue;
      }
      const vetted = vetInstance(
        instanceId,
        stored?.driver === instance.driver ? stored : undefined,
        instance,
        rule,
      );
      if (vetted._tag === "Locked") return vetted;
      if (vetted.instance !== undefined) providerInstances[instanceId] = vetted.instance;
    }
    // A project can switch an instance on for itself; that is enabling it too.
    for (const [projectId, overrides] of Object.entries(next.projectSettingsOverrides)) {
      const storedOverrides =
        current.projectSettingsOverrides[projectId as keyof typeof current.projectSettingsOverrides]
          ?.providerInstances;
      for (const [instanceId, override] of Object.entries(overrides.providerInstances ?? {})) {
        const driver =
          next.providerInstances[instanceId as ProviderInstanceId]?.driver ??
          ProviderDriverKind.make(instanceId);
        if (
          override.enabled === true &&
          storedOverrides?.[instanceId as ProviderInstanceId]?.enabled !== true &&
          !isDriverAllowed(driver)
        ) {
          return {
            _tag: "Disallowed",
            instanceId: instanceId as ProviderInstanceId,
            label: labelFor(driver),
          };
        }
      }
    }
    return {
      _tag: "Allowed",
      settings: {
        ...next,
        providerInstances: providerInstances as ServerSettings["providerInstances"],
      },
    };
  };

  const lockedInstanceFields = Object.fromEntries(
    [...rules].flatMap(([driver, rule]) => {
      const fields = [
        ...rule.config.map((field) => `config.${field}`),
        ...(rule.environment === "all"
          ? ["environment"]
          : rule.environment === "locked"
            ? (rule.pin?.environment ?? []).map((variable) => `environment.${variable.name}`)
            : []),
      ];
      return fields.length === 0 ? [] : [[driver, fields] as const];
    }),
  );

  return {
    _tag: "Valid",
    providers: {
      isDriverAllowed,
      applyLimits,
      vetWrite,
      lockedInstanceFields,
    },
  };
}