@lunora/ai 1.0.0-alpha.20 → 1.0.0-alpha.22

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { L as LunoraAiOptions, a as LunoraAi } from "./packem_shared/types.d-BXCiRv1x.mjs";
-export type { A as AiBindingLike, b as AiGatewayOptions, E as EmbeddingModelInput, M as ModelInput, W as WorkersAiProviderLike } from "./packem_shared/types.d-BXCiRv1x.mjs";
+import { L as LunoraAiOptions, a as LunoraAi } from "./packem_shared/types.d-DGmh5Hq4.mjs";
+export type { A as AiBindingLike, b as AiGatewayOptions, E as EmbeddingModelInput, M as ModelInput, W as WorkersAiProviderLike } from "./packem_shared/types.d-DGmh5Hq4.mjs";
 export { type EmbeddingModel, type LanguageModel, embed, embedMany, generateObject, generateText, hasToolCall, jsonSchema, streamObject, streamText, tool } from 'ai';
 export { createWorkersAI } from 'workers-ai-provider';
 /**
@@ -25,4 +25,66 @@ export { createWorkersAI } from 'workers-ai-provider';
  * @experimental
  */
 declare const createAi: (options: LunoraAiOptions) => LunoraAi;
-export { type LunoraAi, type LunoraAiOptions, createAi };
+/**
+ * Correlation metadata folded into the `cf-aig-metadata` request header so a
+ * gateway log entry can be tied back to the Lunora function + trace that made
+ * the call. Every field is optional — only defined ones are sent.
+ * @experimental
+ */
+interface AiGatewayMetadata {
+  /** The Lunora function path that issued the model call (e.g. `messages:send`). */
+  functionPath?: string;
+  /** The 32-hex trace id the call belongs to, so the gateway log joins the trace. */
+  traceId?: string;
+}
+/**
+ * The resolved AI Gateway coordinates.
+ *
+ * `gatewayId`/`accountId` drive the Workers AI provider's native `gateway` option
+ * (Cloudflare routes the binding call internally). `baseURL` + `headers` are for
+ * bring-your-own AI SDK providers (`@ai-sdk/openai`, …): append the provider
+ * slug to `baseURL` and spread `headers` into the provider config, e.g.
+ *
+ * ```ts
+ * const gw = resolveAiGateway(env);
+ * const openai = createOpenAI(gw ? { baseURL: `${gw.baseURL}/openai`, headers: gw.headers } : {});
+ * ```
+ * @experimental
+ */
+interface ResolvedAiGateway {
+  /** The Cloudflare account id owning the gateway. */
+  accountId: string;
+  /**
+   * The universal gateway base URL:
+   * `https://gateway.ai.cloudflare.com/v1/{account}/{gateway}`. Append the
+   * provider slug (`/openai`, `/anthropic`, `/workers-ai`, …) per provider.
+   */
+  baseURL: string;
+  /** The gateway id (slug). */
+  gatewayId: string;
+  /**
+   * Request headers for a gateway-routed call: `cf-aig-authorization` when the
+   * gateway is authenticated, and `cf-aig-metadata` when correlation metadata
+   * was supplied. Empty object when neither applies.
+   */
+  headers: Record<string, string>;
+}
+/** Env var naming the Cloudflare account that owns the gateway. */
+declare const AI_GATEWAY_ACCOUNT_ID_ENV = "LUNORA_AI_GATEWAY_ACCOUNT_ID";
+/** Env var naming the AI Gateway id (the gateway's slug). */
+declare const AI_GATEWAY_ID_ENV = "LUNORA_AI_GATEWAY_ID";
+/** Env var carrying the gateway's authentication token (only for authenticated gateways). */
+declare const AI_GATEWAY_TOKEN_ENV = "LUNORA_AI_GATEWAY_TOKEN";
+/**
+ * Resolve the Cloudflare AI Gateway coordinates from the Worker `env`, or
+ * `undefined` when the gateway is not configured (both `LUNORA_AI_GATEWAY_ACCOUNT_ID`
+ * and `LUNORA_AI_GATEWAY_ID` must be present). Opt-in and backward-compatible:
+ * an unconfigured app gets `undefined` and every caller keeps its direct-provider
+ * behavior.
+ *
+ * Pass optional {@link AiGatewayMetadata} to fold a `cf-aig-metadata` correlation
+ * header into `headers` — only its defined fields are sent.
+ * @experimental
+ */
+declare const resolveAiGateway: (env: Record<string, unknown>, metadata?: AiGatewayMetadata) => ResolvedAiGateway | undefined;
+export { AI_GATEWAY_ACCOUNT_ID_ENV, AI_GATEWAY_ID_ENV, AI_GATEWAY_TOKEN_ENV, type AiGatewayMetadata, type LunoraAi, type LunoraAiOptions, type ResolvedAiGateway, createAi, resolveAiGateway };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { L as LunoraAiOptions, a as LunoraAi } from "./packem_shared/types.d-BXCiRv1x.js";
-export type { A as AiBindingLike, b as AiGatewayOptions, E as EmbeddingModelInput, M as ModelInput, W as WorkersAiProviderLike } from "./packem_shared/types.d-BXCiRv1x.js";
+import { L as LunoraAiOptions, a as LunoraAi } from "./packem_shared/types.d-DGmh5Hq4.js";
+export type { A as AiBindingLike, b as AiGatewayOptions, E as EmbeddingModelInput, M as ModelInput, W as WorkersAiProviderLike } from "./packem_shared/types.d-DGmh5Hq4.js";
 export { type EmbeddingModel, type LanguageModel, embed, embedMany, generateObject, generateText, hasToolCall, jsonSchema, streamObject, streamText, tool } from 'ai';
 export { createWorkersAI } from 'workers-ai-provider';
 /**
@@ -25,4 +25,66 @@ export { createWorkersAI } from 'workers-ai-provider';
  * @experimental
  */
 declare const createAi: (options: LunoraAiOptions) => LunoraAi;
-export { type LunoraAi, type LunoraAiOptions, createAi };
+/**
+ * Correlation metadata folded into the `cf-aig-metadata` request header so a
+ * gateway log entry can be tied back to the Lunora function + trace that made
+ * the call. Every field is optional — only defined ones are sent.
+ * @experimental
+ */
+interface AiGatewayMetadata {
+  /** The Lunora function path that issued the model call (e.g. `messages:send`). */
+  functionPath?: string;
+  /** The 32-hex trace id the call belongs to, so the gateway log joins the trace. */
+  traceId?: string;
+}
+/**
+ * The resolved AI Gateway coordinates.
+ *
+ * `gatewayId`/`accountId` drive the Workers AI provider's native `gateway` option
+ * (Cloudflare routes the binding call internally). `baseURL` + `headers` are for
+ * bring-your-own AI SDK providers (`@ai-sdk/openai`, …): append the provider
+ * slug to `baseURL` and spread `headers` into the provider config, e.g.
+ *
+ * ```ts
+ * const gw = resolveAiGateway(env);
+ * const openai = createOpenAI(gw ? { baseURL: `${gw.baseURL}/openai`, headers: gw.headers } : {});
+ * ```
+ * @experimental
+ */
+interface ResolvedAiGateway {
+  /** The Cloudflare account id owning the gateway. */
+  accountId: string;
+  /**
+   * The universal gateway base URL:
+   * `https://gateway.ai.cloudflare.com/v1/{account}/{gateway}`. Append the
+   * provider slug (`/openai`, `/anthropic`, `/workers-ai`, …) per provider.
+   */
+  baseURL: string;
+  /** The gateway id (slug). */
+  gatewayId: string;
+  /**
+   * Request headers for a gateway-routed call: `cf-aig-authorization` when the
+   * gateway is authenticated, and `cf-aig-metadata` when correlation metadata
+   * was supplied. Empty object when neither applies.
+   */
+  headers: Record<string, string>;
+}
+/** Env var naming the Cloudflare account that owns the gateway. */
+declare const AI_GATEWAY_ACCOUNT_ID_ENV = "LUNORA_AI_GATEWAY_ACCOUNT_ID";
+/** Env var naming the AI Gateway id (the gateway's slug). */
+declare const AI_GATEWAY_ID_ENV = "LUNORA_AI_GATEWAY_ID";
+/** Env var carrying the gateway's authentication token (only for authenticated gateways). */
+declare const AI_GATEWAY_TOKEN_ENV = "LUNORA_AI_GATEWAY_TOKEN";
+/**
+ * Resolve the Cloudflare AI Gateway coordinates from the Worker `env`, or
+ * `undefined` when the gateway is not configured (both `LUNORA_AI_GATEWAY_ACCOUNT_ID`
+ * and `LUNORA_AI_GATEWAY_ID` must be present). Opt-in and backward-compatible:
+ * an unconfigured app gets `undefined` and every caller keeps its direct-provider
+ * behavior.
+ *
+ * Pass optional {@link AiGatewayMetadata} to fold a `cf-aig-metadata` correlation
+ * header into `headers` — only its defined fields are sent.
+ * @experimental
+ */
+declare const resolveAiGateway: (env: Record<string, unknown>, metadata?: AiGatewayMetadata) => ResolvedAiGateway | undefined;
+export { AI_GATEWAY_ACCOUNT_ID_ENV, AI_GATEWAY_ID_ENV, AI_GATEWAY_TOKEN_ENV, type AiGatewayMetadata, type LunoraAi, type LunoraAiOptions, type ResolvedAiGateway, createAi, resolveAiGateway };

package/dist/index.mjs

@@ -1,3 +1,4 @@
-export { default as createAi } from './packem_shared/createAi-CYxQuvEL.mjs';
+export { default as createAi } from './packem_shared/createAi-Dx7n-UJm.mjs';
+export { AI_GATEWAY_ACCOUNT_ID_ENV, AI_GATEWAY_ID_ENV, AI_GATEWAY_TOKEN_ENV, resolveAiGateway } from './packem_shared/AI_GATEWAY_ACCOUNT_ID_ENV-2CS2QFH7.mjs';
 export { embed, embedMany, generateObject, generateText, hasToolCall, jsonSchema, streamObject, streamText, tool } from 'ai';
 export { createWorkersAI } from 'workers-ai-provider';

package/dist/packem_shared/AI_GATEWAY_ACCOUNT_ID_ENV-2CS2QFH7.mjs

@@ -0,0 +1,44 @@
+const readEnv = (env, key) => {
+  const value = env[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+};
+const encodeMetadata = (metadata) => {
+  if (metadata === void 0) {
+    return void 0;
+  }
+  const fields = {};
+  if (typeof metadata.functionPath === "string" && metadata.functionPath.length > 0) {
+    fields["functionPath"] = metadata.functionPath;
+  }
+  if (typeof metadata.traceId === "string" && metadata.traceId.length > 0) {
+    fields["traceId"] = metadata.traceId;
+  }
+  return Object.keys(fields).length > 0 ? JSON.stringify(fields) : void 0;
+};
+const AI_GATEWAY_ACCOUNT_ID_ENV = "LUNORA_AI_GATEWAY_ACCOUNT_ID";
+const AI_GATEWAY_ID_ENV = "LUNORA_AI_GATEWAY_ID";
+const AI_GATEWAY_TOKEN_ENV = "LUNORA_AI_GATEWAY_TOKEN";
+const resolveAiGateway = (env, metadata) => {
+  const accountId = readEnv(env, AI_GATEWAY_ACCOUNT_ID_ENV);
+  const gatewayId = readEnv(env, AI_GATEWAY_ID_ENV);
+  if (accountId === void 0 || gatewayId === void 0) {
+    return void 0;
+  }
+  const token = readEnv(env, AI_GATEWAY_TOKEN_ENV);
+  const headers = {};
+  if (token !== void 0) {
+    headers["cf-aig-authorization"] = `Bearer ${token}`;
+  }
+  const metadataHeader = encodeMetadata(metadata);
+  if (metadataHeader !== void 0) {
+    headers["cf-aig-metadata"] = metadataHeader;
+  }
+  return {
+    accountId,
+    baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}`,
+    gatewayId,
+    headers
+  };
+};
+
+export { AI_GATEWAY_ACCOUNT_ID_ENV, AI_GATEWAY_ID_ENV, AI_GATEWAY_TOKEN_ENV, resolveAiGateway };

package/dist/packem_shared/{createAi-CYxQuvEL.mjs → createAi-Dx7n-UJm.mjs}

@@ -1,13 +1,25 @@
 import { LunoraError } from '@lunora/errors';
 import { createWorkersAI } from 'workers-ai-provider';
+import { resolveAiGateway } from './AI_GATEWAY_ACCOUNT_ID_ENV-2CS2QFH7.mjs';
 
+const resolveGatewayOption = (gateway, env) => {
+  if (gateway !== void 0) {
+    return gateway;
+  }
+  if (env === void 0) {
+    return void 0;
+  }
+  const resolved = resolveAiGateway(env);
+  return resolved === void 0 ? void 0 : { id: resolved.gatewayId };
+};
 const buildProvider = (binding, gateway) => createWorkersAI({ binding, gateway });
 const createAi = (options) => {
-  const { binding, defaultEmbeddingModel, defaultModel, gateway, provider } = options;
+  const { binding, defaultEmbeddingModel, defaultModel, env, gateway, provider } = options;
   if (!provider && !binding) {
     throw new LunoraError("INTERNAL", "@lunora/ai: createAi requires a `binding` (env.AI) or a pre-built `provider`");
   }
-  const workersai = provider ?? buildProvider(binding, gateway);
+  const resolvedGateway = resolveGatewayOption(gateway, env);
+  const workersai = provider ?? buildProvider(binding, resolvedGateway);
   const model = (input) => {
     if (input === void 0) {
       if (!defaultModel) {
@@ -47,7 +59,8 @@ const createAi = (options) => {
         "@lunora/ai: ai.run requires the `binding` (env.AI) — it is unavailable when only a custom `provider` was supplied"
       );
     }
-    return binding.run(modelId, inputs, runOptions);
+    const mergedOptions = resolvedGateway !== void 0 && runOptions?.gateway === void 0 ? { ...runOptions, gateway: resolvedGateway } : runOptions;
+    return binding.run(modelId, inputs, mergedOptions);
   };
   return { embeddingModel, model, run, workersai };
 };

package/dist/packem_shared/{defineRag-DgVXmNGw.mjs → defineRag-CQ3pnKUh.mjs}

@@ -113,6 +113,20 @@ const modelIdOf = (model) => {
   const id = model.modelId;
   return typeof id === "string" && id.length > 0 ? id : void 0;
 };
+const embedCostOf = (providerMetadata) => {
+  if (typeof providerMetadata !== "object" || providerMetadata === null) {
+    return void 0;
+  }
+  for (const bag of Object.values(providerMetadata)) {
+    if (typeof bag === "object" && bag !== null) {
+      const { cost } = bag;
+      if (typeof cost === "number" && Number.isFinite(cost)) {
+        return cost;
+      }
+    }
+  }
+  return void 0;
+};
 const defineRag = (config) => {
   if (typeof config.index !== "string" || config.index.length === 0) {
     throw new LunoraError("BAD_REQUEST", "@lunora/ai/rag: `index` must be a non-empty Vectorize index name");
@@ -151,15 +165,25 @@ const defineRag = (config) => {
     const embedText = async (text) => {
       model ??= resolveEmbeddingModel(config.embeddingModel, context.ai);
       const resolvedModel = model;
-      const run = async () => {
-        const { embedding } = await embed({ model: resolvedModel, value: text });
+      const run = async (span) => {
+        const { embedding, providerMetadata, usage } = await embed({ model: resolvedModel, value: text });
+        if (span !== void 0) {
+          const inputTokens = usage.tokens;
+          if (typeof inputTokens === "number" && Number.isFinite(inputTokens)) {
+            span.setAttribute("gen_ai.usage.input_tokens", inputTokens);
+          }
+          const cost = embedCostOf(providerMetadata);
+          if (cost !== void 0) {
+            span.setAttribute("gen_ai.usage.cost", cost);
+          }
+        }
         return embedding;
       };
       if (tracer === void 0) {
         return run();
       }
       const modelId = modelIdOf(resolvedModel);
-      return tracer("ai.embed", run, {
+      return tracer("ai.embed", (_trace, span) => run(span), {
         "gen_ai.operation.name": "embeddings",
         ...modelId === void 0 ? {} : { "gen_ai.request.model": modelId }
       });

package/dist/packem_shared/{types.d-BXCiRv1x.d.mts → types.d-DGmh5Hq4.d.mts}

@@ -57,7 +57,19 @@ interface LunoraAiOptions {
    * Has no effect on bring-your-own providers.
    */
   defaultModel?: string;
-  /** Route Workers AI inference through a Cloudflare AI Gateway. */
+  /**
+   * The Worker `env`, read for opt-in Cloudflare AI Gateway routing (the
+   * `LUNORA_AI_GATEWAY_*` vars, via `resolveAiGateway`). When it configures a
+   * gateway and no explicit {@link LunoraAiOptions.gateway} is given, the
+   * Workers AI provider is routed through that gateway so token + dollar-cost
+   * telemetry is computed on the app's behalf. Unset, or with no gateway vars,
+   * behavior is unchanged (calls go straight to Workers AI).
+   */
+  env?: Record<string, unknown>;
+  /**
+   * Route Workers AI inference through a Cloudflare AI Gateway. An explicit
+   * value wins over anything derived from {@link LunoraAiOptions.env}.
+   */
   gateway?: AiGatewayOptions;
   /**
    * Pre-built Workers AI provider. When omitted, one is constructed from

package/dist/packem_shared/{types.d-BXCiRv1x.d.ts → types.d-DGmh5Hq4.d.ts}

@@ -57,7 +57,19 @@ interface LunoraAiOptions {
    * Has no effect on bring-your-own providers.
    */
   defaultModel?: string;
-  /** Route Workers AI inference through a Cloudflare AI Gateway. */
+  /**
+   * The Worker `env`, read for opt-in Cloudflare AI Gateway routing (the
+   * `LUNORA_AI_GATEWAY_*` vars, via `resolveAiGateway`). When it configures a
+   * gateway and no explicit {@link LunoraAiOptions.gateway} is given, the
+   * Workers AI provider is routed through that gateway so token + dollar-cost
+   * telemetry is computed on the app's behalf. Unset, or with no gateway vars,
+   * behavior is unchanged (calls go straight to Workers AI).
+   */
+  env?: Record<string, unknown>;
+  /**
+   * Route Workers AI inference through a Cloudflare AI Gateway. An explicit
+   * value wins over anything derived from {@link LunoraAiOptions.env}.
+   */
   gateway?: AiGatewayOptions;
   /**
    * Pre-built Workers AI provider. When omitted, one is constructed from

package/dist/rag/index.d.mts

@@ -1,5 +1,5 @@
 import { Tool } from 'ai';
-import { E as EmbeddingModelInput, a as LunoraAi } from "../packem_shared/types.d-BXCiRv1x.mjs";
+import { E as EmbeddingModelInput, a as LunoraAi } from "../packem_shared/types.d-DGmh5Hq4.mjs";
 /**
  * Built-in fixed-window chunker: split into `size`-char windows overlapping by
  * `overlap` chars. Deliberately simple and deterministic — the zero-config
@@ -112,11 +112,15 @@ interface RagContext {
   /**
    * Optional `ctx.trace` span factory — an `ActionCtx`'s `ctx.trace` satisfies
    * it structurally. When present, `defineRag` wraps each embedding-model
-   * call in a `generation` span (`gen_ai.operation.name: "embeddings"` +
-   * `gen_ai.request.model`), so the embed shows up on the trace waterfall like
-   * any other instrumented sub-operation. `unknown` on purpose — the same
-   * decoupling rationale as `auth`: `defineRag` narrows it to a callable and
-   * runs embeds untraced when it is absent (a hand-built context / test).
+   * call in a `generation` span carrying `gen_ai.operation.name: "embeddings"`
+   * and `gen_ai.request.model` up front, plus — attached post-hoc through the
+   * span handle the tracer hands the body — `gen_ai.usage.input_tokens` (from
+   * the embed result's token usage) and `gen_ai.usage.cost` (probed from the
+   * embed result's provider metadata, e.g. AI Gateway) when those are present.
+   * So the embed shows up on the trace waterfall with its usage like any other
+   * instrumented model call. `unknown` on purpose — the same decoupling
+   * rationale as `auth`: `defineRag` narrows it to a callable and runs embeds
+   * untraced when it is absent (a hand-built context / test).
    */
   trace?: unknown;
   vectors: RagVectors;

package/dist/rag/index.d.ts

@@ -1,5 +1,5 @@
 import { Tool } from 'ai';
-import { E as EmbeddingModelInput, a as LunoraAi } from "../packem_shared/types.d-BXCiRv1x.js";
+import { E as EmbeddingModelInput, a as LunoraAi } from "../packem_shared/types.d-DGmh5Hq4.js";
 /**
  * Built-in fixed-window chunker: split into `size`-char windows overlapping by
  * `overlap` chars. Deliberately simple and deterministic — the zero-config
@@ -112,11 +112,15 @@ interface RagContext {
   /**
    * Optional `ctx.trace` span factory — an `ActionCtx`'s `ctx.trace` satisfies
    * it structurally. When present, `defineRag` wraps each embedding-model
-   * call in a `generation` span (`gen_ai.operation.name: "embeddings"` +
-   * `gen_ai.request.model`), so the embed shows up on the trace waterfall like
-   * any other instrumented sub-operation. `unknown` on purpose — the same
-   * decoupling rationale as `auth`: `defineRag` narrows it to a callable and
-   * runs embeds untraced when it is absent (a hand-built context / test).
+   * call in a `generation` span carrying `gen_ai.operation.name: "embeddings"`
+   * and `gen_ai.request.model` up front, plus — attached post-hoc through the
+   * span handle the tracer hands the body — `gen_ai.usage.input_tokens` (from
+   * the embed result's token usage) and `gen_ai.usage.cost` (probed from the
+   * embed result's provider metadata, e.g. AI Gateway) when those are present.
+   * So the embed shows up on the trace waterfall with its usage like any other
+   * instrumented model call. `unknown` on purpose — the same decoupling
+   * rationale as `auth`: `defineRag` narrows it to a callable and runs embeds
+   * untraced when it is absent (a hand-built context / test).
    */
   trace?: unknown;
   vectors: RagVectors;

package/dist/rag/index.mjs

@@ -1,5 +1,5 @@
 export { default as fixedWindowChunks } from '../packem_shared/fixedWindowChunks-J-WfQDw9.mjs';
-export { default as defineRag } from '../packem_shared/defineRag-DgVXmNGw.mjs';
+export { default as defineRag } from '../packem_shared/defineRag-CQ3pnKUh.mjs';
 export { contentHash, guessMimeTypeFromExtension } from '../packem_shared/contentHash-Cgz5KRGD.mjs';
 export { default as hybridRank } from '../packem_shared/hybridRank-DPC9c2ON.mjs';
 export { default as bm25LexicalStore } from '../packem_shared/bm25LexicalStore-BQzWLMqX.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/ai",
-  "version": "1.0.0-alpha.20",
+  "version": "1.0.0-alpha.22",
   "description": "Workers AI helper for Lunora: provider-agnostic AI SDK access from functions, Workers AI by default",
   "keywords": [
     "ai",