@nebutra/agents 1.1.1 → 2.0.0

package/dist/chunk-VZPQOXWW.js

@@ -0,0 +1,47 @@
+// src/sdk/payload-guard.ts
+var OPENAI_MAX_PROPERTY_NAME_LENGTH = 256;
+function isObjectLike(value) {
+  return typeof value === "object" && value !== null;
+}
+function pathSegment(key) {
+  const preview = key.length > 32 ? `${key.slice(0, 29)}...` : key;
+  return /^[A-Za-z_$][\w$]*$/.test(preview) ? `.${preview}` : `[${JSON.stringify(preview)}]`;
+}
+function findOversizedPropertyName(value, maxLength = OPENAI_MAX_PROPERTY_NAME_LENGTH) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  function visit(candidate, path) {
+    if (!isObjectLike(candidate)) return null;
+    if (seen.has(candidate)) return null;
+    seen.add(candidate);
+    if (Array.isArray(candidate)) {
+      for (let index = 0; index < candidate.length; index += 1) {
+        const issue = visit(candidate[index], `${path}[${index}]`);
+        if (issue) return issue;
+      }
+      return null;
+    }
+    for (const [key, nested] of Object.entries(candidate)) {
+      const nestedPath = `${path}${pathSegment(key)}`;
+      if (key.length > maxLength) {
+        return { path: nestedPath, length: key.length };
+      }
+      const issue = visit(nested, nestedPath);
+      if (issue) return issue;
+    }
+    return null;
+  }
+  return visit(value, "$");
+}
+function assertSafeOpenAIJsonPayload(label, value) {
+  const issue = findOversizedPropertyName(value);
+  if (!issue) return;
+  throw new Error(
+    `${label} contains an object property name at ${issue.path} that is ${issue.length} characters long; maximum is ${OPENAI_MAX_PROPERTY_NAME_LENGTH}. Put generated text in a string value instead of using it as a JSON key.`
+  );
+}
+
+export {
+  OPENAI_MAX_PROPERTY_NAME_LENGTH,
+  findOversizedPropertyName,
+  assertSafeOpenAIJsonPayload
+};

package/dist/{chunk-NVPE5EDI.js → chunk-YBCIJKC7.js}

@@ -1,13 +1,28 @@
+import {
+  models
+} from "./chunk-HVLFZW6E.js";
+
 // src/sdk/config.ts
 import { z } from "zod";
-var ProviderType = z.enum(["openrouter", "openai", "siliconflow", "gateway"]);
+var ProviderType = z.enum([
+  "openrouter",
+  "openai",
+  "siliconflow",
+  "sensenova",
+  "ai302",
+  "gateway"
+]);
 var NebutraAIConfigSchema = z.object({
   /** Which provider backend to use. Defaults to "openrouter". */
   provider: ProviderType.default("openrouter"),
   /** API key override. Falls back to env vars per provider. */
   apiKey: z.string().optional(),
-  /** Default model identifier. Provider-specific format. */
-  defaultModel: z.string().default("anthropic/claude-sonnet-4"),
+  /**
+   * Default model id. Reads the generated frontier flagship rather than naming
+   * a version, so `pnpm gen:frontier-models` moves it and it cannot go stale
+   * here independently of everywhere else.
+   */
+  defaultModel: z.string().default(models.flagship),
   /** Default temperature for generations. */
   temperature: z.number().min(0).max(2).default(0.7),
   /** Default max tokens for output. */
@@ -23,6 +38,8 @@ function resolveApiKey(config) {
     openrouter: "OPENROUTER_API_KEY",
     openai: "OPENAI_API_KEY",
     siliconflow: "SILICONFLOW_API_KEY",
+    sensenova: "SENSENOVA_API_KEY",
+    ai302: "AI302_API_KEY",
     gateway: "VERCEL_OIDC_TOKEN"
   };
   const envVar = envMap[config.provider];

package/dist/env.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+
+/**
+ * Environment validation for `@nebutra/agents`.
+ *
+ * All variables are OPTIONAL — the package must work with zero new env config.
+ * Provider keys (OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
+ * are validated lazily by the provider resolver, not here.
+ */
+
+/** Comma-separated provider chain. Order = priority. */
+declare const FallbackProviderName: z.ZodEnum<{
+    openrouter: "openrouter";
+    anthropic: "anthropic";
+    openai: "openai";
+    ai302: "ai302";
+}>;
+type FallbackProviderName = z.infer<typeof FallbackProviderName>;
+declare const AgentsEnvSchema: z.ZodObject<{
+    ANTHROPIC_API_KEY: z.ZodOptional<z.ZodString>;
+    LANGFUSE_PUBLIC_KEY: z.ZodOptional<z.ZodString>;
+    LANGFUSE_SECRET_KEY: z.ZodOptional<z.ZodString>;
+    LANGFUSE_HOST: z.ZodDefault<z.ZodString>;
+    LLM_FALLBACK_CHAIN: z.ZodDefault<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, z.ZodArray<z.ZodEnum<{
+        openrouter: "openrouter";
+        anthropic: "anthropic";
+        openai: "openai";
+        ai302: "ai302";
+    }>>>>;
+    LLM_EMBEDDING_FALLBACK_CHAIN: z.ZodDefault<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, z.ZodArray<z.ZodEnum<{
+        openrouter: "openrouter";
+        anthropic: "anthropic";
+        openai: "openai";
+        ai302: "ai302";
+    }>>>>;
+}, z.core.$strip>;
+type AgentsEnv = z.infer<typeof AgentsEnvSchema>;
+/** Returns the validated env (cached). Safe to call from any runtime. */
+declare function getAgentsEnv(): AgentsEnv;
+/** Test helper — clears cache so updated process.env is picked up. */
+declare function _resetAgentsEnvCache(): void;
+/** True iff Langfuse credentials are present. */
+declare function isLangfuseConfigured(): boolean;
+
+export { type AgentsEnv, AgentsEnvSchema, FallbackProviderName, _resetAgentsEnvCache, getAgentsEnv, isLangfuseConfigured };

package/dist/env.js

@@ -0,0 +1,12 @@
+import {
+  AgentsEnvSchema,
+  _resetAgentsEnvCache,
+  getAgentsEnv,
+  isLangfuseConfigured
+} from "./chunk-FCXWOXII.js";
+export {
+  AgentsEnvSchema,
+  _resetAgentsEnvCache,
+  getAgentsEnv,
+  isLangfuseConfigured
+};

package/dist/fallback.d.ts

@@ -0,0 +1,100 @@
+import { EmbeddingModel, LanguageModel } from 'ai';
+export { ModelMessage } from 'ai';
+import { FallbackProviderName } from './env.js';
+import 'zod';
+
+/**
+ * Multi-provider fallback chain + prompt-caching helpers.
+ *
+ * Cost & reliability primitives for production LLM workloads:
+ *
+ * 1. `createFallbackModel()` — picks a primary model and returns a callable
+ *    that retries on retryable errors (429 / 5xx / network) by swapping to
+ *    the next provider in `LLM_FALLBACK_CHAIN`.
+ *
+ * 2. `withCacheControl()` — annotates the system message with Anthropic
+ *    `cacheControl: { type: 'ephemeral' }` for a 90% discount on cached
+ *    prefix tokens. OpenAI auto-caches when the prefix is stable and ≥1024
+ *    tokens — see comment in `generateWithFallback()`.
+ *
+ * Reference: https://sdk.vercel.ai/docs/ai-sdk-providers/anthropic#cache-control
+ */
+
+/**
+ * Filter a chain to providers whose API key is present in env.
+ * Returns the original chain unchanged if NO providers have keys (so callers
+ * still see a meaningful error rather than an empty-chain throw).
+ */
+declare function filterAvailableProviders(chain: readonly FallbackProviderName[]): readonly FallbackProviderName[];
+declare function isRetryableError(error: unknown): boolean;
+interface FallbackResult<T> {
+    result: T;
+    provider: FallbackProviderName;
+    attempts: number;
+}
+interface CreateFallbackModelOptions {
+    /** Override the default chain from env. */
+    chain?: readonly FallbackProviderName[];
+    /** Model preset / id passed to each provider in the chain. */
+    model?: string;
+    /**
+     * If true (default), filter the chain to providers whose API key is present
+     * in env. Set false to keep the original chain (caller wants to surface
+     * "missing key" errors as fallback steps — useful for tests).
+     */
+    filterAvailable?: boolean;
+}
+/**
+ * Run an AI SDK call against the configured fallback chain.
+ *
+ * The caller provides an `invoke(model)` function — usually a closure over
+ * `streamText` or `generateText` — and `runWithFallback` walks the chain,
+ * trying each provider in order until one succeeds or the chain is exhausted.
+ */
+declare function runWithFallback<T>(invoke: (model: LanguageModel) => Promise<T>, options?: CreateFallbackModelOptions): Promise<FallbackResult<T>>;
+/**
+ * Build `providerOptions` that enable prompt caching across providers.
+ *
+ * - Anthropic: explicit `cacheControl: { type: 'ephemeral' }` on the system
+ *   message — 90% cost reduction on cached prefix tokens.
+ * - OpenAI: prompt caching is AUTOMATIC for prompts ≥1024 tokens with a
+ *   stable prefix. No flag needed — but callers MUST keep the system prompt
+ *   + tools FIRST and dynamic user content LAST, otherwise the cache is
+ *   invalidated on every call.
+ * - OpenRouter: passes provider options through transparently.
+ */
+declare function withAnthropicCacheControl(): {
+    anthropic: {
+        cacheControl: {
+            type: "ephemeral";
+        };
+    };
+};
+/**
+ * Wraps the system message in a structured cache-control hint.
+ * Returns the messages array unchanged if no system text is provided.
+ *
+ * IMPORTANT: keep stable content (system prompt + tool defs) FIRST,
+ * dynamic content (user query) LAST — required for both Anthropic explicit
+ * caching AND OpenAI automatic caching to hit.
+ */
+declare function buildSystemWithCache(systemPrompt: string): {
+    role: "system";
+    content: string;
+    providerOptions: ReturnType<typeof withAnthropicCacheControl>;
+};
+interface EmbeddingFallbackOptions {
+    chain?: readonly FallbackProviderName[];
+    model?: string;
+    filterAvailable?: boolean;
+}
+/**
+ * Run an AI SDK embedding call against the configured embedding fallback chain.
+ *
+ * The caller provides an `invoke(model)` function — usually a closure over
+ * `embed` or `embedMany` from the `ai` package — and this helper walks the
+ * embedding-capable chain, trying each provider until one succeeds.
+ */
+declare function runEmbedWithFallback<T>(invoke: (model: EmbeddingModel) => Promise<T>, options?: EmbeddingFallbackOptions): Promise<FallbackResult<T>>;
+
+export { type CreateFallbackModelOptions, type EmbeddingFallbackOptions, type FallbackResult, buildSystemWithCache, filterAvailableProviders, isRetryableError, runEmbedWithFallback, runWithFallback, withAnthropicCacheControl };

package/dist/fallback.js

@@ -0,0 +1,18 @@
+import {
+  buildSystemWithCache,
+  filterAvailableProviders,
+  isRetryableError,
+  runEmbedWithFallback,
+  runWithFallback,
+  withAnthropicCacheControl
+} from "./chunk-C4CC5UEF.js";
+import "./chunk-HVLFZW6E.js";
+import "./chunk-FCXWOXII.js";
+export {
+  buildSystemWithCache,
+  filterAvailableProviders,
+  isRetryableError,
+  runEmbedWithFallback,
+  runWithFallback,
+  withAnthropicCacheControl
+};

package/dist/generation/index.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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. */
+type GenerationModality = "image" | "video";
+/** Tenant-scoped attribution for a generation call (mirrors AgentContext). */
+interface GenerationContext {
+    readonly tenantId: string;
+    readonly userId: string;
+    /** Optional logical grouping (e.g. a canvas / conversation id). */
+    readonly conversationId?: string;
+}
+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[];
+}
+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;
+}
+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.
+ */
+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>;
+}
+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[];
+}
+
+/**
+ * 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.
+ */
+
+declare const mockGenerationProvider: GenerationProvider;
+
+/**
+ * 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`.
+ */
+
+declare function registerGenerationProvider(provider: GenerationProvider): void;
+/** Test helper — restores the registry to just the mock provider. */
+declare function _resetGenerationRegistry(): void;
+/** Provider names available for a modality, in resolved priority order. */
+declare function listGenerationProviders(modality: GenerationModality, options?: GenerationCallOptions): string[];
+/**
+ * Generate an image. Always resolves (falls back to the deterministic mock).
+ */
+declare function generateImage(req: ImageGenerationRequest, ctx: GenerationContext, options?: GenerationCallOptions): Promise<GenerationResult>;
+/**
+ * Generate a video (or, in mock mode, a deterministic poster frame).
+ */
+declare function generateVideo(req: VideoGenerationRequest, ctx: GenerationContext, options?: GenerationCallOptions): Promise<GenerationResult>;
+
+export { type GenerationCallOptions, type GenerationContext, type GenerationModality, type GenerationProvider, type GenerationResult, type ImageGenerationRequest, type VideoGenerationRequest, _resetGenerationRegistry, generateImage, generateVideo, listGenerationProviders, mockGenerationProvider, registerGenerationProvider };

package/dist/generation/index.js

@@ -0,0 +1,19 @@
+import {
+  _resetGenerationRegistry,
+  generateImage,
+  generateVideo,
+  listGenerationProviders,
+  mockGenerationProvider,
+  registerGenerationProvider
+} from "../chunk-HZQXXUKB.js";
+import "../chunk-C4CC5UEF.js";
+import "../chunk-HVLFZW6E.js";
+import "../chunk-FCXWOXII.js";
+export {
+  _resetGenerationRegistry,
+  generateImage,
+  generateVideo,
+  listGenerationProviders,
+  mockGenerationProvider,
+  registerGenerationProvider
+};