@lunora/ai 1.0.0-alpha.21 → 1.0.0-alpha.23

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-CQ3pnKUh.mjs → defineRag-DmczmIDj.mjs}

@@ -183,9 +183,12 @@ const defineRag = (config) => {
         return run();
       }
       const modelId = modelIdOf(resolvedModel);
+      const conversationId = typeof context.conversationId === "string" && context.conversationId.length > 0 ? context.conversationId : void 0;
       return tracer("ai.embed", (_trace, span) => run(span), {
         "gen_ai.operation.name": "embeddings",
-        ...modelId === void 0 ? {} : { "gen_ai.request.model": modelId }
+        ...modelId === void 0 ? {} : { "gen_ai.request.model": modelId },
+        // Session/thread grouping — absent unless a conversation id was set.
+        ...conversationId === void 0 ? {} : { "gen_ai.conversation.id": conversationId }
       });
     };
     const checkNamespace = (namespace) => {

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
@@ -109,6 +109,14 @@ interface RagContext {
    * stays decoupled from `@lunora/server`'s identity type; `rlsFilter` narrows.
    */
   auth?: unknown;
+  /**
+   * Optional conversation / session id. When set (and `trace` is present), each
+   * embedding-model span additionally carries `gen_ai.conversation.id`, so a
+   * RAG embed done inside a multi-turn conversation groups with that
+   * conversation's other generation spans in the trace store. Omitted → the
+   * attribute is absent (backward-compatible).
+   */
+  conversationId?: string;
   /**
    * Optional `ctx.trace` span factory — an `ActionCtx`'s `ctx.trace` satisfies
    * it structurally. When present, `defineRag` wraps each embedding-model

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
@@ -109,6 +109,14 @@ interface RagContext {
    * stays decoupled from `@lunora/server`'s identity type; `rlsFilter` narrows.
    */
   auth?: unknown;
+  /**
+   * Optional conversation / session id. When set (and `trace` is present), each
+   * embedding-model span additionally carries `gen_ai.conversation.id`, so a
+   * RAG embed done inside a multi-turn conversation groups with that
+   * conversation's other generation spans in the trace store. Omitted → the
+   * attribute is absent (backward-compatible).
+   */
+  conversationId?: string;
   /**
    * Optional `ctx.trace` span factory — an `ActionCtx`'s `ctx.trace` satisfies
    * it structurally. When present, `defineRag` wraps each embedding-model

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-CQ3pnKUh.mjs';
+export { default as defineRag } from '../packem_shared/defineRag-DmczmIDj.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.21",
+  "version": "1.0.0-alpha.23",
   "description": "Workers AI helper for Lunora: provider-agnostic AI SDK access from functions, Workers AI by default",
   "keywords": [
     "ai",