@nebutra/agents 1.1.1 → 2.0.0

package/src/gateway.ts

@@ -1,234 +0,0 @@
-import { isRetryableError } from "./fallback";
-
-export type AgentRuntimeGatewayMessageRole = "system" | "user" | "assistant" | "tool";
-
-export interface AgentRuntimeGatewayMessage {
-  readonly role: AgentRuntimeGatewayMessageRole;
-  readonly content: string;
-}
-
-export interface AgentRuntimeGatewayUsage {
-  readonly inputTokens?: number;
-  readonly outputTokens?: number;
-  readonly totalTokens?: number;
-}
-
-export interface AgentRuntimeGatewayCompletion {
-  readonly id: string;
-  readonly provider: string;
-  readonly model: string;
-  readonly text: string;
-  readonly usage?: AgentRuntimeGatewayUsage;
-  readonly raw?: unknown;
-}
-
-export interface AgentRuntimeGatewayProvider {
-  readonly id: string;
-  readonly model: string;
-  readonly capabilities: ReadonlySet<string>;
-  complete(
-    messages: readonly AgentRuntimeGatewayMessage[],
-    options?: AgentRuntimeGatewayCompleteOptions,
-  ): Promise<AgentRuntimeGatewayCompletion>;
-}
-
-export interface AgentRuntimeGatewayCompleteOptions {
-  readonly temperature?: number;
-  readonly maxTokens?: number;
-  readonly signal?: AbortSignal;
-}
-
-export interface AgentRuntimeGatewayRequest extends AgentRuntimeGatewayCompleteOptions {
-  readonly capability: string;
-  readonly messages: readonly AgentRuntimeGatewayMessage[];
-  readonly tenantId?: string;
-  readonly userId?: string;
-  readonly requestId?: string;
-  readonly cacheKey?: string;
-  readonly maxFallbacks?: number;
-}
-
-export interface AgentRuntimeGatewayDecision {
-  readonly provider: string;
-  readonly reason: string;
-  readonly fallbackIndex: number;
-}
-
-export interface AgentRuntimeGatewayDebugEntry {
-  readonly requestId: string;
-  readonly tenantId?: string;
-  readonly userId?: string;
-  readonly decision: AgentRuntimeGatewayDecision;
-  readonly ok: boolean;
-  readonly error?: string;
-}
-
-export interface AgentRuntimeGatewayUsageReport {
-  readonly calls: number;
-  readonly inputTokens: number;
-  readonly outputTokens: number;
-  readonly totalTokens: number;
-  readonly estimatedUsd: number;
-}
-
-export interface AgentRuntimeGatewayOptions {
-  readonly providers: readonly AgentRuntimeGatewayProvider[];
-  readonly estimateUsd?: (usage: Required<AgentRuntimeGatewayUsage>) => number;
-  readonly requestId?: () => string;
-}
-
-interface CacheEntry {
-  readonly response: AgentRuntimeGatewayCompletion;
-}
-
-function capabilityParts(capability: string): string[] {
-  return capability
-    .split(/[+,\s]+/)
-    .map((part) => part.trim())
-    .filter(Boolean);
-}
-
-function cacheKey(request: AgentRuntimeGatewayRequest): string {
-  return (
-    request.cacheKey ??
-    JSON.stringify({
-      capability: request.capability,
-      prefix: request.messages.slice(0, Math.max(1, request.messages.length - 1)),
-      last: request.messages.at(-1),
-    })
-  );
-}
-
-function normalizeUsage(
-  usage: AgentRuntimeGatewayUsage | undefined,
-): Required<AgentRuntimeGatewayUsage> {
-  const inputTokens = usage?.inputTokens ?? 0;
-  const outputTokens = usage?.outputTokens ?? 0;
-  return {
-    inputTokens,
-    outputTokens,
-    totalTokens: usage?.totalTokens ?? inputTokens + outputTokens,
-  };
-}
-
-function defaultRequestId(): string {
-  return `agents-gw-${Date.now()}-${Math.random().toString(16).slice(2)}`;
-}
-
-function defaultCostEstimate(usage: Required<AgentRuntimeGatewayUsage>): number {
-  return usage.totalTokens * 0.000_001;
-}
-
-export class AgentRuntimeGateway {
-  readonly #providers: readonly AgentRuntimeGatewayProvider[];
-  readonly #cache = new Map<string, CacheEntry>();
-  readonly #debug: AgentRuntimeGatewayDebugEntry[] = [];
-  readonly #estimateUsd: (usage: Required<AgentRuntimeGatewayUsage>) => number;
-  readonly #requestId: () => string;
-  #hits = 0;
-  #misses = 0;
-  #usage: AgentRuntimeGatewayUsageReport = {
-    calls: 0,
-    inputTokens: 0,
-    outputTokens: 0,
-    totalTokens: 0,
-    estimatedUsd: 0,
-  };
-
-  constructor(options: AgentRuntimeGatewayOptions) {
-    this.#providers = options.providers;
-    this.#estimateUsd = options.estimateUsd ?? defaultCostEstimate;
-    this.#requestId = options.requestId ?? defaultRequestId;
-  }
-
-  async complete(request: AgentRuntimeGatewayRequest): Promise<AgentRuntimeGatewayCompletion> {
-    const resolvedRequestId = request.requestId ?? this.#requestId();
-    const resolvedCacheKey = cacheKey(request);
-    const cached = this.#cache.get(resolvedCacheKey);
-    if (cached) {
-      this.#hits += 1;
-      return cached.response;
-    }
-    this.#misses += 1;
-
-    const providers = this.route(request);
-    let lastError: unknown;
-    const max = Math.min(request.maxFallbacks ?? providers.length, providers.length);
-
-    for (let index = 0; index < max; index += 1) {
-      const provider = providers[index];
-      if (!provider) continue;
-
-      const decision: AgentRuntimeGatewayDecision = {
-        provider: provider.id,
-        fallbackIndex: index,
-        reason: `matched capability "${request.capability}"`,
-      };
-
-      try {
-        const response = await provider.complete(request.messages, {
-          ...(request.temperature !== undefined && { temperature: request.temperature }),
-          ...(request.maxTokens !== undefined && { maxTokens: request.maxTokens }),
-          ...(request.signal !== undefined && { signal: request.signal }),
-        });
-        this.#recordUsage(response);
-        this.#cache.set(resolvedCacheKey, { response });
-        this.#debug.push({
-          requestId: resolvedRequestId,
-          ...(request.tenantId !== undefined && { tenantId: request.tenantId }),
-          ...(request.userId !== undefined && { userId: request.userId }),
-          decision,
-          ok: true,
-        });
-        return response;
-      } catch (error) {
-        lastError = error;
-        this.#debug.push({
-          requestId: resolvedRequestId,
-          ...(request.tenantId !== undefined && { tenantId: request.tenantId }),
-          ...(request.userId !== undefined && { userId: request.userId }),
-          decision,
-          ok: false,
-          error: error instanceof Error ? error.message : String(error),
-        });
-
-        if (!isRetryableError(error)) throw error;
-      }
-    }
-
-    throw new Error(
-      `All AgentRuntimeGateway providers failed for capability "${request.capability}". Last error: ${String(lastError)}`,
-    );
-  }
-
-  route(request: Pick<AgentRuntimeGatewayRequest, "capability">): AgentRuntimeGatewayProvider[] {
-    const parts = capabilityParts(request.capability);
-    const matched = this.#providers.filter((provider) =>
-      parts.every((part) => provider.capabilities.has(part)),
-    );
-    return matched.length > 0 ? matched : [...this.#providers];
-  }
-
-  cacheStats(): { hits: number; misses: number; size: number } {
-    return { hits: this.#hits, misses: this.#misses, size: this.#cache.size };
-  }
-
-  usageReport(): AgentRuntimeGatewayUsageReport {
-    return { ...this.#usage };
-  }
-
-  debugLog(): readonly AgentRuntimeGatewayDebugEntry[] {
-    return [...this.#debug];
-  }
-
-  #recordUsage(response: AgentRuntimeGatewayCompletion): void {
-    const usage = normalizeUsage(response.usage);
-    this.#usage = {
-      calls: this.#usage.calls + 1,
-      inputTokens: this.#usage.inputTokens + usage.inputTokens,
-      outputTokens: this.#usage.outputTokens + usage.outputTokens,
-      totalTokens: this.#usage.totalTokens + usage.totalTokens,
-      estimatedUsd: Number((this.#usage.estimatedUsd + this.#estimateUsd(usage)).toFixed(6)),
-    };
-  }
-}

package/src/generation/index.ts

@@ -1,157 +0,0 @@
-/**
- * Image / video generation modality — public surface.
- *
- * Mirrors the LLM fallback design (`fallback.ts`): an ordered provider chain,
- * filtered to providers whose `envKey` is present, with `mock` as the
- * guaranteed terminal so a result is always produced. Retryable failures
- * (429 / 5xx / network) rotate to the next provider via `isRetryableError`.
- */
-
-import { logger } from "@nebutra/logger";
-import { isRetryableError } from "../fallback";
-import { mockGenerationProvider } from "./mock-provider";
-import type {
-  GenerationCallOptions,
-  GenerationContext,
-  GenerationModality,
-  GenerationProvider,
-  GenerationResult,
-  ImageGenerationRequest,
-  VideoGenerationRequest,
-} from "./types";
-
-const log = logger.child({ module: "agents/generation" });
-
-// ── Registry ────────────────────────────────────────────────────────────────
-// `mock` is registered last and always available. Real providers register
-// ahead of it (additively) and win whenever their env key is present.
-
-const _registry = new Map<string, GenerationProvider>();
-
-export function registerGenerationProvider(provider: GenerationProvider): void {
-  _registry.set(provider.name, provider);
-}
-
-/** Test helper — restores the registry to just the mock provider. */
-export function _resetGenerationRegistry(): void {
-  _registry.clear();
-  _registry.set(mockGenerationProvider.name, mockGenerationProvider);
-}
-
-_resetGenerationRegistry();
-
-function hasEnvKey(provider: GenerationProvider): boolean {
-  if (provider.envKey === null) return true;
-  return Boolean(globalThis.process?.env?.[provider.envKey]);
-}
-
-/** Provider names available for a modality, in resolved priority order. */
-export function listGenerationProviders(
-  modality: GenerationModality,
-  options: GenerationCallOptions = {},
-): string[] {
-  const envChain = (globalThis.process?.env?.GENERATION_FALLBACK_CHAIN ?? "")
-    .split(",")
-    .map((s) => s.trim())
-    .filter(Boolean);
-  const preferred = options.chain ?? (envChain.length > 0 ? envChain : []);
-
-  // Real providers first (explicit chain wins, then registry order), `mock`
-  // is always demoted to the guaranteed terminal regardless of registry order.
-  const mockName = mockGenerationProvider.name;
-  const all = [...preferred, ..._registry.keys()];
-  const seen = new Set<string>();
-  const resolved: string[] = [];
-  for (const name of all) {
-    if (seen.has(name) || name === mockName) continue;
-    seen.add(name);
-    const provider = _registry.get(name);
-    if (!provider) continue;
-    if (!provider.capabilities.includes(modality)) continue;
-    if (!hasEnvKey(provider)) continue;
-    resolved.push(name);
-  }
-  resolved.push(mockName);
-  return resolved;
-}
-
-async function runChain(
-  modality: GenerationModality,
-  options: GenerationCallOptions,
-  ctx: GenerationContext,
-  invoke: (p: GenerationProvider) => Promise<GenerationResult>,
-): Promise<GenerationResult> {
-  const chain = listGenerationProviders(modality, options);
-  let lastErr: unknown;
-  for (const name of chain) {
-    const provider = _registry.get(name);
-    if (!provider) continue;
-    try {
-      const result = await invoke(provider);
-      log.debug("generation succeeded", {
-        provider: name,
-        modality,
-        tenantId: ctx.tenantId,
-      });
-      return result;
-    } catch (err) {
-      lastErr = err;
-      const retryable = isRetryableError(err);
-      log.warn("generation provider failed", {
-        provider: name,
-        modality,
-        retryable,
-        tenantId: ctx.tenantId,
-      });
-      // Non-retryable from the terminal mock would be a real bug — surface it.
-      if (!retryable && name !== mockGenerationProvider.name) continue;
-      if (!retryable) throw err;
-    }
-  }
-  throw lastErr instanceof Error
-    ? lastErr
-    : new Error("[@nebutra/agents] generation chain exhausted");
-}
-
-/**
- * Generate an image. Always resolves (falls back to the deterministic mock).
- */
-export async function generateImage(
-  req: ImageGenerationRequest,
-  ctx: GenerationContext,
-  options: GenerationCallOptions = {},
-): Promise<GenerationResult> {
-  return runChain("image", options, ctx, (p) => {
-    if (!p.generateImage) {
-      throw new Error(`[@nebutra/agents] provider "${p.name}" lacks image support`);
-    }
-    return p.generateImage(req, ctx);
-  });
-}
-
-/**
- * Generate a video (or, in mock mode, a deterministic poster frame).
- */
-export async function generateVideo(
-  req: VideoGenerationRequest,
-  ctx: GenerationContext,
-  options: GenerationCallOptions = {},
-): Promise<GenerationResult> {
-  return runChain("video", options, ctx, (p) => {
-    if (!p.generateVideo) {
-      throw new Error(`[@nebutra/agents] provider "${p.name}" lacks video support`);
-    }
-    return p.generateVideo(req, ctx);
-  });
-}
-
-export { mockGenerationProvider } from "./mock-provider";
-export type {
-  GenerationCallOptions,
-  GenerationContext,
-  GenerationModality,
-  GenerationProvider,
-  GenerationResult,
-  ImageGenerationRequest,
-  VideoGenerationRequest,
-} from "./types";

package/src/generation/mock-provider.ts

@@ -1,123 +0,0 @@
-/**
- * Deterministic mock generation provider.
- *
- * Always available (`envKey: null`) so CI and flag-gated demos never need a
- * paid secret. Output is a stable, content-addressed SVG `data:` URI: the same
- * prompt + size always yields byte-identical bytes, which makes canvas
- * placement and websocket-sync tests deterministic.
- *
- * Wiring a real provider (Replicate / OpenAI images / Volces) later is purely
- * additive — register it with a non-null `envKey` and it takes priority over
- * `mock` in the fallback chain whenever its key is present.
- */
-
-import type {
-  GenerationContext,
-  GenerationProvider,
-  GenerationResult,
-  ImageGenerationRequest,
-  VideoGenerationRequest,
-} from "./types";
-
-/** FNV-1a — small, stable, no deps. Used to derive a deterministic hue. */
-function hash(input: string): number {
-  let h = 0x811c9dc5;
-  for (let i = 0; i < input.length; i++) {
-    h ^= input.charCodeAt(i);
-    h = Math.imul(h, 0x01000193);
-  }
-  return h >>> 0;
-}
-
-function escapeXml(s: string): string {
-  return s
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}
-
-function svgDataUri(label: string, prompt: string, w: number, h: number): string {
-  const hue = hash(prompt) % 360;
-  const hue2 = (hue + 40) % 360;
-  // Wrap the prompt to ~32 chars/line, max 4 lines, so the placeholder
-  // visibly carries its prompt (useful when eyeballing a canvas demo).
-  const words = prompt.split(/\s+/);
-  const lines: string[] = [];
-  let cur = "";
-  for (const word of words) {
-    if ((cur + " " + word).trim().length > 32) {
-      lines.push(cur.trim());
-      cur = word;
-    } else {
-      cur = `${cur} ${word}`;
-    }
-    if (lines.length === 4) break;
-  }
-  if (cur && lines.length < 4) lines.push(cur.trim());
-
-  const tspans = lines
-    .map((ln, i) => `<tspan x="50%" dy="${i === 0 ? 0 : 26}">${escapeXml(ln)}</tspan>`)
-    .join("");
-
-  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">
-<defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
-<stop offset="0" stop-color="hsl(${hue} 70% 55%)"/>
-<stop offset="1" stop-color="hsl(${hue2} 70% 45%)"/>
-</linearGradient></defs>
-<rect width="${w}" height="${h}" fill="url(#g)"/>
-<text x="50%" y="14%" fill="rgba(255,255,255,.7)" font-family="sans-serif" font-size="20" text-anchor="middle">${escapeXml(label)}</text>
-<text x="50%" y="46%" fill="#fff" font-family="sans-serif" font-size="22" font-weight="600" text-anchor="middle">${tspans}</text>
-</svg>`;
-
-  // base64 keeps the URI well-formed regardless of prompt characters.
-  const b64 =
-    typeof btoa === "function"
-      ? btoa(unescape(encodeURIComponent(svg)))
-      : Buffer.from(svg, "utf8").toString("base64");
-  return `data:image/svg+xml;base64,${b64}`;
-}
-
-export const mockGenerationProvider: GenerationProvider = {
-  name: "mock",
-  envKey: null,
-  capabilities: ["image", "video"],
-
-  async generateImage(
-    req: ImageGenerationRequest,
-    _ctx: GenerationContext,
-  ): Promise<GenerationResult> {
-    const width = req.width ?? 1024;
-    const height = req.height ?? 1024;
-    return {
-      modality: "image",
-      mimeType: "image/svg+xml",
-      url: svgDataUri("mock · image", req.prompt, width, height),
-      width,
-      height,
-      providerName: "mock",
-      model: req.model ?? "mock-image-1",
-      usage: { units: 1 },
-    };
-  },
-
-  async generateVideo(
-    req: VideoGenerationRequest,
-    _ctx: GenerationContext,
-  ): Promise<GenerationResult> {
-    const width = req.width ?? 1280;
-    const height = req.height ?? 720;
-    const seconds = req.durationSeconds ?? 5;
-    // No real codec in mock mode — return a poster frame the canvas can embed.
-    return {
-      modality: "video",
-      mimeType: "image/svg+xml",
-      url: svgDataUri(`mock · video · ${seconds}s`, req.prompt, width, height),
-      width,
-      height,
-      providerName: "mock",
-      model: req.model ?? "mock-video-1",
-      usage: { units: seconds },
-    };
-  },
-};

package/src/generation/types.ts

@@ -1,87 +0,0 @@
-/**
- * Image / video generation modality for `@nebutra/agents`.
- *
- * The text + embedding modalities wrap the Vercel AI SDK. Image / video
- * generation is a *new modality on the same provider layer*: providers are
- * env-key gated exactly like the LLM fallback chain (see `fallback.ts`), so
- * single-provider — or zero-provider (mock) — deploys just work.
- *
- * Generation is tenant-scoped: every call carries a {@link GenerationContext}
- * so downstream metering / audit can attribute units to an organization.
- */
-
-/** What a provider can produce. */
-export type GenerationModality = "image" | "video";
-
-/** Tenant-scoped attribution for a generation call (mirrors AgentContext). */
-export interface GenerationContext {
-  readonly tenantId: string;
-  readonly userId: string;
-  /** Optional logical grouping (e.g. a canvas / conversation id). */
-  readonly conversationId?: string;
-}
-
-export interface ImageGenerationRequest {
-  readonly prompt: string;
-  /** Pixel width — defaults to 1024. */
-  readonly width?: number;
-  /** Pixel height — defaults to 1024. */
-  readonly height?: number;
-  /** Optional model id / preset; provider-specific passthrough. */
-  readonly model?: string;
-  /** Reference images (data: URI or URL) for edit / variation flows. */
-  readonly inputImages?: readonly string[];
-}
-
-export interface VideoGenerationRequest {
-  readonly prompt: string;
-  /** Clip length in seconds — defaults to 5. */
-  readonly durationSeconds?: number;
-  readonly width?: number;
-  readonly height?: number;
-  readonly model?: string;
-  /** Optional first-frame image (data: URI or URL). */
-  readonly inputImage?: string;
-}
-
-export interface GenerationResult {
-  readonly modality: GenerationModality;
-  /** e.g. "image/svg+xml", "image/png", "video/mp4". */
-  readonly mimeType: string;
-  /** `data:` URI (mock / inline) or a remote URL the caller can fetch. */
-  readonly url: string;
-  readonly width: number;
-  readonly height: number;
-  /** Provider that actually produced the asset. */
-  readonly providerName: string;
-  /** Model id reported by the provider. */
-  readonly model: string;
-  /**
-   * Best-effort billable units for `@nebutra/metering` (e.g. 1 image,
-   * N seconds of video). Callers decide the meter mapping.
-   */
-  readonly usage: { readonly units: number };
-}
-
-/**
- * A generation backend. `envKey` mirrors the LLM provider gating: when the
- * variable is absent the provider is filtered out of the chain. `null` means
- * "always available" — reserved for the deterministic mock provider so CI and
- * flag-gated demos never need a paid secret.
- */
-export interface GenerationProvider {
-  readonly name: string;
-  readonly envKey: string | null;
-  readonly capabilities: readonly GenerationModality[];
-  generateImage?(req: ImageGenerationRequest, ctx: GenerationContext): Promise<GenerationResult>;
-  generateVideo?(req: VideoGenerationRequest, ctx: GenerationContext): Promise<GenerationResult>;
-}
-
-export interface GenerationCallOptions {
-  /**
-   * Ordered provider-name preference. Unknown / unavailable names are skipped.
-   * Defaults to `GENERATION_FALLBACK_CHAIN` env (comma-separated) then registry
-   * order, always ending at `mock` so a result is guaranteed.
-   */
-  readonly chain?: readonly string[];
-}