Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

13.3 KB
Raw Blame
import {
  CustomOpenaiSettings,
  ProviderDriverKind,
  type ServerProvider,
  type ServerProviderModel,
} from "@akeru/contracts";
import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as PubSub from "effect/PubSub";
import * as Ref from "effect/Ref";
import * as Schema from "effect/Schema";
import * as Semaphore from "effect/Semaphore";
import * as Stream from "effect/Stream";
import { HttpClient, HttpClientRequest } from "effect/unstable/http";

import { ServerConfig } from "../../config.ts";
import { mergeSubscriptionInstanceEnvironment } from "../../subscription-auth/runtime.ts";
import { defaultProviderContinuationIdentity, type ProviderDriver } from "../ProviderDriver.ts";
import { explicitProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
import { manualOnlyProviderMaintenanceCapabilities } from "../providerMaintenance.ts";

const DRIVER_KIND = ProviderDriverKind.make("customOpenai");

const decodeSettings = Schema.decodeSync(CustomOpenaiSettings);

/**
 * The API key is an instance environment variable, not a config field: the
 * settings blob is serialized to every client that can read settings, and only
 * sensitive environment variables are stored in the secret store and redacted
 * on the way out. Instance variables win over the process environment, which is
 * deliberately NOT read here — this driver talks to an arbitrary endpoint, so
 * inheriting a process-wide key would send it to whatever URL an instance
 * happens to configure.
 */
const API_KEY_ENV = "CUSTOM_OPENAI_API_KEY";

const BASE_URL_ENV = "CUSTOM_OPENAI_BASE_URL";

/** The whole `/models` probe — request, headers, and body — must fit this budget. */
const MODELS_TIMEOUT_MS = 10_000;

/**
 * OpenAI-compatible `/models` payloads come in two shapes: the standard
 * `{ data: [{ id }] }` envelope and a bare array from smaller gateways.
 * The envelope is validated as a whole so an unreadable body is reported as a
 * failed probe rather than as an endpoint that lists no models; entries are
 * decoded one at a time so a single malformed row cannot discard the catalog.
 *
 * `None` means "not a model list at all".
 */
const EndpointModelEnvelope = Schema.Struct({ data: Schema.Array(Schema.Unknown) });

const EndpointModelArray = Schema.Array(Schema.Unknown);

const EndpointModelList = Schema.Union([EndpointModelEnvelope, EndpointModelArray]);

const EndpointModelEntry = Schema.Union([Schema.String, Schema.Struct({ id: Schema.String })]);

const decodeEndpointModelList = Schema.decodeUnknownOption(EndpointModelList);

const decodeEndpointModelEntry = Schema.decodeUnknownOption(EndpointModelEntry);

function readEndpointModelIds(
  list: typeof EndpointModelList.Type,
): Option.Option<ReadonlyArray<string>> {
  const entries = "data" in list ? list.data : list;
  const ids = new Set<string>();

  for (const entry of entries) {
    const resolved = decodeEndpointModelEntry(entry).pipe(
      Option.map((model) => (Predicate.isString(model) ? model : model.id).trim()),
      Option.filter((value) => value.length > 0),
    );

    if (Option.isSome(resolved)) ids.add(resolved.value);
  }

  return Option.some([...ids]);
}

/**
 * The instance's catalog is whatever the endpoint reports plus every model the
 * user added by hand. Endpoint models are the provider's own list; hand-added
 * ones stay flagged custom so settings can tell them apart.
 */
function models(
  catalog: readonly string[],
  customModels: readonly string[],
): ServerProviderModel[] {
  const custom = customModels.flatMap((model) => {
    const trimmed = model.trim();

    return trimmed.length > 0 ? [trimmed] : [];
  });

  const catalogSlugs = new Set(catalog);

  return [...new Set([...catalog, ...custom])].map((slug, index) => ({
    slug,
    name: slug,
    isCustom: !catalogSlugs.has(slug),
    ...(index === 0 ? { isDefault: true } : {}),
    capabilities: null,
  }));
}

type ProbeResult =
  | { readonly ok: true; readonly catalog: ReadonlyArray<string> }
  | { readonly ok: false; readonly failure: string; readonly rejected: boolean };

export type CustomOpenaiDriverEnv = ServerConfig | HttpClient.HttpClient;

export const CustomOpenaiDriver: ProviderDriver<CustomOpenaiSettings, CustomOpenaiDriverEnv> = {
  driverKind: DRIVER_KIND,
  metadata: { displayName: "Custom API", supportsMultipleInstances: true },
  configSchema: CustomOpenaiSettings,
  defaultConfig: () => decodeSettings({}),
  create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
    Effect.gen(function* () {
      const httpClient = yield* HttpClient.HttpClient;

      const changes = yield* Effect.acquireRelease(
        PubSub.unbounded<ServerProvider>(),
        PubSub.shutdown,
      );

      const catalog = yield* Ref.make<ReadonlyArray<string>>([]);
      const probeFailure = yield* Ref.make<string | null>(null);
      // True after `/models` answered 401 or 403. A scoped key can be refused
      // the listing and still chat, so this only stops the instance reading
      // as connected; it does not block turns.
      const probeRejected = yield* Ref.make(false);
      // False until the first probe settles. The catalog is not authoritative
      // before then, so the registry keeps the models it hydrated from the
      // on-disk cache instead of trusting an empty list.
      const probeSettled = yield* Ref.make(false);
      // One probe at a time: an explicit refresh must not race the startup
      // probe and let the older response land last.
      const probeLock = yield* Semaphore.make(1);
      const effectiveEnabled = enabled && config.enabled;
      const explicitEnvironment = explicitProviderInstanceEnvironment(environment);
      const apiKey = explicitEnvironment[API_KEY_ENV]?.trim() ?? "";
      const baseUrl = explicitEnvironment[BASE_URL_ENV]?.trim() || config.baseUrl.trim();

      const connectionEnvironment: NodeJS.ProcessEnv = {
        ...mergeSubscriptionInstanceEnvironment(environment),
        ...(apiKey.length > 0 ? { [API_KEY_ENV]: apiKey } : {}),
        ...(baseUrl.length > 0 ? { [BASE_URL_ENV]: baseUrl } : {}),
      };

      // Drop anything the process environment supplied for these two names:
      // only the instance's own variables and its configured base URL count.
      if (apiKey.length === 0) delete connectionEnvironment[API_KEY_ENV];

      if (baseUrl.length === 0) delete connectionEnvironment[BASE_URL_ENV];
      // A base URL alone is enough to run turns: plenty of OpenAI-compatible
      // servers (Ollama, llama.cpp, LM Studio) take no API key. `auth.status`
      // is the app-wide "this instance can run" signal, so it follows the base
      // URL rather than the key; the key is only sent when one is configured.
      // A `/models` refusal (401/403) downgrades it to "unknown", which shows
      // the warning without gating turns the way "unauthenticated" does.
      const connected = baseUrl.length > 0;

      // Probe failures are published to every client. The base URL may come
      // from a sensitive variable, so messages name only its origin.
      const endpointLabel = URL.canParse(baseUrl) ? new URL(baseUrl).origin : "the endpoint";

      const continuationIdentity = defaultProviderContinuationIdentity({
        driverKind: DRIVER_KIND,
        instanceId,
      });

      const buildSnapshot = Effect.gen(function* () {
        const endpointModels = yield* Ref.get(catalog);
        const failure = yield* Ref.get(probeFailure);
        const settled = yield* Ref.get(probeSettled);
        const rejected = yield* Ref.get(probeRejected);

        const message = !connected
          ? "Set a base URL in Settings."
          : (failure ?? (settled ? undefined : "Listing models from the endpoint…"));

        // `warning` covers every state whose catalog is not authoritative:
        // disabled, no base URL, an in-flight first probe, and a failed probe
        // that is still serving the last good catalog.
        return {
          instanceId,
          driver: DRIVER_KIND,
          displayName: displayName ?? "Custom API",
          ...(accentColor ? { accentColor } : {}),
          continuation: { groupKey: continuationIdentity.continuationKey },
          enabled: effectiveEnabled,
          installed: true,
          version: null,
          status: !effectiveEnabled
            ? "disabled"
            : connected && failure === null && settled
              ? "ready"
              : "warning",
          auth: {
            status: !connected ? "unauthenticated" : rejected ? "unknown" : "authenticated",
            type: "apiKey",
          },
          checkedAt: DateTime.formatIso(DateTime.nowUnsafe()),
          ...(effectiveEnabled && message !== undefined ? { message } : {}),
          availability: "available",
          models: models(endpointModels, config.customModels),
          slashCommands: [],
          skills: [],
        } satisfies ServerProvider;
      });

      const probeEndpointModels: Effect.Effect<ProbeResult> = Effect.gen(function* () {
        const bare = HttpClientRequest.get(`${baseUrl.replace(/\/+$/, "")}/models`).pipe(
          HttpClientRequest.setHeader("accept", "application/json"),
        );

        const request = apiKey.length > 0 ? HttpClientRequest.bearerToken(apiKey)(bare) : bare;

        // One timeout covers the request, the response headers, and the body:
        // a gateway that answers 200 and then stalls must not hang a refresh.
        const outcome = yield* Effect.gen(function* () {
          const response = yield* httpClient.execute(request);

          if (response.status === 401 || response.status === 403) {
            return {
              ok: false as const,
              failure: `${endpointLabel} refused to list models (HTTP ${response.status}). Check the API key in Settings.`,
              rejected: true,
            } satisfies ProbeResult;
          }

          if (response.status < 200 || response.status >= 300) {
            return {
              ok: false as const,
              failure: `Model list from ${endpointLabel} returned HTTP ${response.status}.`,
              rejected: false,
            } satisfies ProbeResult;
          }

          const ids = yield* response.json.pipe(
            Effect.map((body) =>
              Option.flatMap(decodeEndpointModelList(body), readEndpointModelIds),
            ),
            // A body that is not JSON at all is as unreadable as one with the
            // wrong shape; both mean "this is not a model list".
            Effect.orElseSucceed(() => Option.none()),
          );

          return Option.isSome(ids)
            ? { ok: true as const, catalog: ids.value }
            : {
                ok: false as const,
                failure: `Model list from ${endpointLabel} was not a readable list of models.`,
                rejected: false,
              };
        }).pipe(
          Effect.timeoutOption(MODELS_TIMEOUT_MS),
          Effect.catchCause(() => Effect.succeed(Option.none())),
        );

        return Option.isNone(outcome)
          ? { ok: false, failure: `Could not list models from ${endpointLabel}.`, rejected: false }
          : outcome.value;
      });

      const refresh = probeLock.withPermits(1)(
        Effect.gen(function* () {
          // Disabled instances publish their snapshot without contacting the
          // endpoint, so a configured key is never sent.
          if (!connected || !effectiveEnabled) {
            yield* Ref.set(probeFailure, null);
            yield* Ref.set(probeRejected, false);
            yield* Ref.set(probeSettled, false);
          } else {
            const result = yield* probeEndpointModels;

            if (result.ok) {
              yield* Ref.set(catalog, result.catalog);
              yield* Ref.set(probeFailure, null);
              yield* Ref.set(probeRejected, false);
            } else {
              // Keep the last good catalog: a transient failure must not empty
              // the picker or block models the endpoint still serves.
              yield* Ref.set(probeFailure, result.failure);
              yield* Ref.set(probeRejected, result.rejected);
            }

            yield* Ref.set(probeSettled, true);
          }

          const snapshot = yield* buildSnapshot;
          yield* PubSub.publish(changes, snapshot);

          return snapshot;
        }),
      );

      // Populate the catalog without blocking the registry's layer build.
      yield* Effect.forkScoped(refresh);

      return {
        instanceId,
        driverKind: DRIVER_KIND,
        continuationIdentity,
        displayName,
        accentColor,
        enabled: effectiveEnabled,
        mastraConnection: {
          environment: connectionEnvironment,
          instanceEnvironment: explicitEnvironment,
          // No subscription credential exists for this driver; `true` selects
          // the merged `environment` (which carries the instance key and base
          // URL) in `resolveAkeruMastraModel`.
          useSavedCredential: true,
        },
        adapter: undefined,
        textGeneration: undefined,
        snapshot: {
          maintenanceCapabilities: manualOnlyProviderMaintenanceCapabilities({
            provider: DRIVER_KIND,
            packageName: null,
          }),
          getSnapshot: buildSnapshot,
          refresh,
          streamChanges: Stream.fromPubSub(changes),
        },
      };
    }),
};