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.

10.3 KB
Raw Blame
/**
 * Image request routing.
 *
 * Picks the provider for one image request independent of the calling bot's
 * chat model: an explicit `provider` pins the request to that provider, else
 * the bot's `imageProvider` override, else the global default, then the
 * global fallback order. Fallback only follows availability and provider
 * failures (`IMAGE_FALLBACK_FAILURE_KINDS`). Invalid or unsupported requests
 * stop immediately, and an edit never sends the user's input images to a
 * provider other than the intended one without explicit `allowProvider`
 * consent.
 */
import {
  IMAGE_FALLBACK_FAILURE_KINDS,
  type ImageGenerationAttempt,
  type ImageGenerationFailureKind,
  type ImageGenerationRequest,
  type ImageGenerationSettings,
  type ImageProviderId,
} from "@akeru/contracts";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";

import {
  ImageAdapterFailure,
  type ImageAdapterInputImage,
  type ImageAdapterOutput,
  type ImageProviderAdapter,
  unsupportedReason,
} from "./adapters.ts";

export const IMAGE_PROVIDER_LABELS: Readonly<Record<ImageProviderId, string>> = {
  chatgpt: "ChatGPT",
  grok: "Grok",
};

/** Bounded per-provider wait; image calls routinely take tens of seconds. */
export const IMAGE_REQUEST_TIMEOUT = Duration.seconds(150);

export type ImageProviderAvailability =
  | { readonly state: "available" }
  | {
      readonly state: "unavailable";
      readonly kind: "unavailable" | "revoked";
      readonly message: string;
    };

export interface ImageRouteInput {
  readonly request: ImageGenerationRequest;
  readonly inputImages: ReadonlyArray<ImageAdapterInputImage>;
  readonly settings: ImageGenerationSettings;
  readonly botOverride: ImageProviderId | null;
  readonly availability: (provider: ImageProviderId) => ImageProviderAvailability;
  readonly adapters: Readonly<Record<ImageProviderId, ImageProviderAdapter>>;
  readonly timeout?: Duration.Input;
  /** Called after every real provider call, for request health. */
  readonly onAttempt?: (
    provider: ImageProviderId,
    outcome: { readonly ok: true } | { readonly ok: false; readonly failure: ImageAdapterFailure },
  ) => Effect.Effect<void>;
  /** Called once per successful provider request, before another request can fail. */
  readonly onOutput?: (
    provider: ImageProviderId,
    output: ImageAdapterOutput,
    requestIndex: number,
  ) => Effect.Effect<void>;
}

export interface ImageRoutePart {
  readonly provider: ImageProviderId;
  readonly output: ImageAdapterOutput;
}

export type ImageRouteResult =
  | {
      readonly status: "completed";
      readonly provider: ImageProviderId;
      readonly parts: ReadonlyArray<ImageRoutePart>;
      readonly attempts: ReadonlyArray<ImageGenerationAttempt>;
    }
  | {
      readonly status: "failed";
      readonly kind: ImageGenerationFailureKind;
      readonly message: string;
      readonly parts: ReadonlyArray<ImageRoutePart>;
      readonly attempts: ReadonlyArray<ImageGenerationAttempt>;
    }
  | {
      readonly status: "needs-consent";
      readonly provider: ImageProviderId;
      readonly message: string;
      readonly parts: ReadonlyArray<ImageRoutePart>;
      readonly attempts: ReadonlyArray<ImageGenerationAttempt>;
    };

function providerEnabled(settings: ImageGenerationSettings, provider: ImageProviderId): boolean {
  return provider === "chatgpt" ? settings.chatgptEnabled : settings.grokEnabled;
}

/** The provider a request is meant for, and the ordered candidates to try. */
export function imageRoutePlan(input: {
  readonly settings: ImageGenerationSettings;
  readonly botOverride: ImageProviderId | null;
  readonly explicit: ImageProviderId | undefined;
}): ImageRoutePlanResult {
  if (input.explicit) return { intended: input.explicit, candidates: [input.explicit] };

  const ordered = [
    input.botOverride,
    input.settings.defaultProvider,
    ...input.settings.fallbackOrder,
  ].filter((provider): provider is ImageProviderId => provider !== null);

  const candidates = [...new Set(ordered)];

  return { intended: candidates[0] ?? null, candidates };
}

const runAdapter = (
  adapter: ImageProviderAdapter,
  request: Parameters<ImageProviderAdapter["run"]>[0],
  timeout: Duration.Input,
) =>
  Effect.tryPromise({
    try: (signal) => adapter.run(request, signal),
    catch: (cause) =>
      cause instanceof ImageAdapterFailure
        ? cause
        : new ImageAdapterFailure(
            "provider-failed",
            `${IMAGE_PROVIDER_LABELS[adapter.provider]} image request failed.`,
          ),
  }).pipe(
    Effect.timeoutOption(timeout),
    Effect.flatMap((output) =>
      Option.isSome(output)
        ? Effect.succeed(output.value)
        : Effect.fail(
            new ImageAdapterFailure(
              "timeout",
              `${IMAGE_PROVIDER_LABELS[adapter.provider]} did not return an image in time.`,
            ),
          ),
    ),
  );

/**
 * Runs one image request across the routed providers. Interrupting the
 * returned effect aborts the in-flight provider request.
 */
export const routeImageRequest = Effect.fn("routeImageRequest")(function* (
  input: ImageRouteInput,
): Effect.fn.Return<ImageRouteResult> {
  const { request, settings } = input;

  const plan = imageRoutePlan({
    settings,
    botOverride: input.botOverride,
    explicit: request.provider,
  });

  const attempts: ImageGenerationAttempt[] = [];
  const parts: ImageRoutePart[] = [];

  const adapterRequest = {
    operation: request.operation,
    prompt: request.prompt,
    inputImages: input.inputImages,
    aspectRatio: request.aspectRatio,
    quality: request.quality ?? "standard",
    count: request.count ?? 1,
  } as const;

  if (plan.candidates.length === 0 || !plan.candidates.some((p) => providerEnabled(settings, p))) {
    return {
      status: "failed",
      kind: "disabled",
      message: request.provider
        ? `${IMAGE_PROVIDER_LABELS[request.provider]} image generation is turned off in Settings.`
        : "Image generation is turned off. Enable ChatGPT or Grok images in Settings.",
      attempts,
      parts,
    };
  }

  // A consented edit retry goes to the approved provider first instead of repeating the
  // provider that already failed; the rest of the plan still backs it up.
  const consented =
    input.inputImages.length > 0 && request.allowProvider
      ? plan.candidates.filter((provider) => provider === request.allowProvider)
      : [];

  const candidates = [...consented, ...plan.candidates.filter((p) => !consented.includes(p))];
  let lastFailure: { kind: ImageGenerationFailureKind; message: string } | undefined;
  let remainingCount = adapterRequest.count;

  for (const provider of candidates) {
    const label = IMAGE_PROVIDER_LABELS[provider];

    if (!providerEnabled(settings, provider)) continue;

    const availability = input.availability(provider);

    if (availability.state === "unavailable") {
      attempts.push({ provider, outcome: availability.kind });
      // An unavailable fallback cannot hide the failure of a provider that ran the request.
      lastFailure ??= { kind: availability.kind, message: availability.message };
      continue;
    }

    const adapter = input.adapters[provider];
    const providerRequest = { ...adapterRequest, count: remainingCount };
    const unsupported = unsupportedReason(label, adapter.capabilities, providerRequest);

    if (unsupported) {
      attempts.push({ provider, outcome: "unsupported" });

      // The intended provider defines the request's capability. An unsupported
      // fallback cannot erase an earlier availability or provider failure.
      if (provider === plan.intended) {
        return { status: "failed", kind: "unsupported", message: unsupported, attempts, parts };
      }

      lastFailure ??= { kind: "unsupported", message: unsupported };
      continue;
    }

    if (
      input.inputImages.length > 0 &&
      provider !== plan.intended &&
      request.allowProvider !== provider
    ) {
      const intendedLabel = plan.intended
        ? IMAGE_PROVIDER_LABELS[plan.intended]
        : "The selected provider";

      return {
        status: "needs-consent",
        provider,
        message: `${intendedLabel} could not take this edit. Ask the user whether their image may be sent to ${label}; if they agree, retry with allowProvider "${provider}".`,
        attempts,
        parts,
      };
    }

    const callCount = provider === "chatgpt" ? remainingCount : 1;

    for (let index = 0; index < callCount; index += 1) {
      const outcome = yield* runAdapter(
        adapter,
        { ...providerRequest, count: provider === "chatgpt" ? 1 : remainingCount },
        input.timeout ?? IMAGE_REQUEST_TIMEOUT,
      ).pipe(
        Effect.map((output) => ({ ok: true as const, output })),
        Effect.catch((failure: ImageAdapterFailure) =>
          Effect.succeed({ ok: false as const, failure }),
        ),
      );

      if (input.onAttempt) {
        yield* input.onAttempt(
          provider,
          outcome.ok ? { ok: true } : { ok: false, failure: outcome.failure },
        );
      }

      if (!outcome.ok || outcome.output.images.length === 0) {
        const failure = outcome.ok
          ? new ImageAdapterFailure("provider-failed", `${label} returned no image.`)
          : outcome.failure;

        attempts.push({ provider, outcome: failure.kind });
        lastFailure = { kind: failure.kind, message: failure.message };

        if (!IMAGE_FALLBACK_FAILURE_KINDS.has(failure.kind)) {
          return { status: "failed", ...lastFailure, attempts, parts };
        }

        break;
      }

      const output = { ...outcome.output, images: outcome.output.images.slice(0, remainingCount) };

      if (input.onOutput) yield* input.onOutput(provider, output, parts.length);
      parts.push({ provider, output });
      attempts.push({ provider, outcome: "completed" });
      remainingCount -= output.images.length;

      if (remainingCount === 0) {
        return { status: "completed", provider: parts[0]!.provider, parts, attempts };
      }
    }
  }

  return {
    status: "failed",
    kind: lastFailure?.kind ?? "unavailable",
    message: lastFailure?.message ?? "No image provider is available.",
    attempts,
    parts,
  };
});

type ImageRoutePlanResult = {
  readonly intended: ImageProviderId | null;
  readonly candidates: ImageProviderId[];
};