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

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-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";
+import { L as LunoraAiOptions, a as LunoraAi } from "./packem_shared/types.d-F_Q8R8L3.mjs";
+export { A as AI_GATEWAY_ACCOUNT_ID_ENV, b as AI_GATEWAY_ID_ENV, c as AI_GATEWAY_TOKEN_ENV, type d as AiBindingLike, type e as AiGatewayMetadata, type f as AiGatewayOptions, type E as EmbeddingModelInput, type M as ModelInput, type R as ResolvedAiGateway, type W as WorkersAiProviderLike, g as buildAiGatewayMetadataFields, r as resolveAiGateway } from "./packem_shared/types.d-F_Q8R8L3.mjs";
 export { type EmbeddingModel, type LanguageModel, embed, embedMany, generateObject, generateText, hasToolCall, jsonSchema, streamObject, streamText, tool } from 'ai';
 export { createWorkersAI } from 'workers-ai-provider';
 /**
@@ -25,66 +25,4 @@ export { createWorkersAI } from 'workers-ai-provider';
  * @experimental
  */
 declare const createAi: (options: LunoraAiOptions) => LunoraAi;
-/**
- * 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 };
+export { type LunoraAi, type LunoraAiOptions, createAi };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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";
+import { L as LunoraAiOptions, a as LunoraAi } from "./packem_shared/types.d-F_Q8R8L3.js";
+export { A as AI_GATEWAY_ACCOUNT_ID_ENV, b as AI_GATEWAY_ID_ENV, c as AI_GATEWAY_TOKEN_ENV, type d as AiBindingLike, type e as AiGatewayMetadata, type f as AiGatewayOptions, type E as EmbeddingModelInput, type M as ModelInput, type R as ResolvedAiGateway, type W as WorkersAiProviderLike, g as buildAiGatewayMetadataFields, r as resolveAiGateway } from "./packem_shared/types.d-F_Q8R8L3.js";
 export { type EmbeddingModel, type LanguageModel, embed, embedMany, generateObject, generateText, hasToolCall, jsonSchema, streamObject, streamText, tool } from 'ai';
 export { createWorkersAI } from 'workers-ai-provider';
 /**
@@ -25,66 +25,4 @@ export { createWorkersAI } from 'workers-ai-provider';
  * @experimental
  */
 declare const createAi: (options: LunoraAiOptions) => LunoraAi;
-/**
- * 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 };
+export { type LunoraAi, type LunoraAiOptions, createAi };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-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 { default as createAi } from './packem_shared/createAi-Cep3l8Rk.mjs';
+export { AI_GATEWAY_ACCOUNT_ID_ENV, AI_GATEWAY_ID_ENV, AI_GATEWAY_TOKEN_ENV, buildAiGatewayMetadataFields, resolveAiGateway } from './packem_shared/AI_GATEWAY_ACCOUNT_ID_ENV-CIAjehQF.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 → AI_GATEWAY_ACCOUNT_ID_ENV-CIAjehQF.mjs}

@@ -2,7 +2,7 @@ const readEnv = (env, key) => {
   const value = env[key];
   return typeof value === "string" && value.length > 0 ? value : void 0;
 };
-const encodeMetadata = (metadata) => {
+const buildAiGatewayMetadataFields = (metadata) => {
   if (metadata === void 0) {
     return void 0;
   }
@@ -13,7 +13,11 @@ const encodeMetadata = (metadata) => {
   if (typeof metadata.traceId === "string" && metadata.traceId.length > 0) {
     fields["traceId"] = metadata.traceId;
   }
-  return Object.keys(fields).length > 0 ? JSON.stringify(fields) : void 0;
+  return Object.keys(fields).length > 0 ? fields : void 0;
+};
+const encodeMetadata = (metadata) => {
+  const fields = buildAiGatewayMetadataFields(metadata);
+  return fields === void 0 ? void 0 : JSON.stringify(fields);
 };
 const AI_GATEWAY_ACCOUNT_ID_ENV = "LUNORA_AI_GATEWAY_ACCOUNT_ID";
 const AI_GATEWAY_ID_ENV = "LUNORA_AI_GATEWAY_ID";
@@ -41,4 +45,4 @@ const resolveAiGateway = (env, metadata) => {
   };
 };
 
-export { AI_GATEWAY_ACCOUNT_ID_ENV, AI_GATEWAY_ID_ENV, AI_GATEWAY_TOKEN_ENV, resolveAiGateway };
+export { AI_GATEWAY_ACCOUNT_ID_ENV, AI_GATEWAY_ID_ENV, AI_GATEWAY_TOKEN_ENV, buildAiGatewayMetadataFields, resolveAiGateway };

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

@@ -1,24 +1,28 @@
 import { LunoraError } from '@lunora/errors';
 import { createWorkersAI } from 'workers-ai-provider';
-import { resolveAiGateway } from './AI_GATEWAY_ACCOUNT_ID_ENV-2CS2QFH7.mjs';
+import { buildAiGatewayMetadataFields, resolveAiGateway } from './AI_GATEWAY_ACCOUNT_ID_ENV-CIAjehQF.mjs';
 
-const resolveGatewayOption = (gateway, env) => {
+const resolveGatewayOption = (gateway, env, metadata) => {
+  const metadataFields = buildAiGatewayMetadataFields(metadata);
   if (gateway !== void 0) {
-    return gateway;
+    return metadataFields !== void 0 && gateway.metadata === void 0 ? { ...gateway, metadata: metadataFields } : gateway;
   }
   if (env === void 0) {
     return void 0;
   }
-  const resolved = resolveAiGateway(env);
-  return resolved === void 0 ? void 0 : { id: resolved.gatewayId };
+  const resolved = resolveAiGateway(env, metadata);
+  if (resolved === void 0) {
+    return void 0;
+  }
+  return metadataFields === void 0 ? { id: resolved.gatewayId } : { id: resolved.gatewayId, metadata: metadataFields };
 };
 const buildProvider = (binding, gateway) => createWorkersAI({ binding, gateway });
 const createAi = (options) => {
-  const { binding, defaultEmbeddingModel, defaultModel, env, gateway, provider } = options;
+  const { binding, defaultEmbeddingModel, defaultModel, env, gateway, metadata, provider } = options;
   if (!provider && !binding) {
     throw new LunoraError("INTERNAL", "@lunora/ai: createAi requires a `binding` (env.AI) or a pre-built `provider`");
   }
-  const resolvedGateway = resolveGatewayOption(gateway, env);
+  const resolvedGateway = resolveGatewayOption(gateway, env, metadata);
   const workersai = provider ?? buildProvider(binding, resolvedGateway);
   const model = (input) => {
     if (input === void 0) {

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

@@ -1,4 +1,75 @@
 import { EmbeddingModel, LanguageModel } from 'ai';
+/**
+ * Project {@link AiGatewayMetadata} to a plain string-map of only its defined,
+ * non-empty fields, or `undefined` when nothing is set. This is the shared source
+ * of truth behind both gateway-correlation forms: the `cf-aig-metadata` HTTP
+ * header (bring-your-own providers) and the Workers AI binding's native
+ * `gateway.metadata` option — both encode the same `{ functionPath, traceId }`.
+ * @experimental
+ */
+declare const buildAiGatewayMetadataFields: (metadata: AiGatewayMetadata | undefined) => Record<string, string> | undefined;
+/**
+ * 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;
 /**
  * Structural projection of the Cloudflare Workers `AI` binding (`env.AI`).
  * Declared locally so unit tests can pass a plain-object double and the real
@@ -30,6 +101,12 @@ interface WorkersAiProviderLike {
 interface AiGatewayOptions {
   [key: string]: unknown;
   id: string;
+  /**
+   * Custom correlation metadata surfaced in the AI Gateway logs (Cloudflare's
+   * native `gateway.metadata`). `@lunora/ai` folds `{ functionPath, traceId }`
+   * here from {@link LunoraAiOptions.metadata} when a gateway is configured.
+   */
+  metadata?: Record<string, string>;
 }
 /**
  * `LunoraAiOptions` is part of the experimental `@lunora/ai` API and may change without a major version bump.
@@ -71,6 +148,15 @@ interface LunoraAiOptions {
    * value wins over anything derived from {@link LunoraAiOptions.env}.
    */
   gateway?: AiGatewayOptions;
+  /**
+   * Correlation metadata folded into the active gateway call (the Workers AI
+   * binding's native `gateway.metadata`) so an AI Gateway log entry ties back
+   * to the Lunora function + trace that made it. Only applied when a gateway is
+   * actually configured (explicit or env-derived) and only its defined fields
+   * are sent — absent otherwise, so behavior is unchanged. The generated
+   * `ctx.ai` facade threads `{ functionPath, traceId }` here automatically.
+   */
+  metadata?: AiGatewayMetadata;
   /**
    * Pre-built Workers AI provider. When omitted, one is constructed from
    * `binding` via `createWorkersAI`. Supplying it directly is the seam used by
@@ -118,4 +204,4 @@ interface LunoraAi {
   /** The underlying Workers AI provider — `ai.workersai("@cf/...")` for a raw model. */
   workersai: WorkersAiProviderLike;
 }
-export { AiBindingLike as A, EmbeddingModelInput as E, LunoraAiOptions as L, ModelInput as M, WorkersAiProviderLike as W, LunoraAi as a, AiGatewayOptions as b };
+export { AI_GATEWAY_ACCOUNT_ID_ENV as A, EmbeddingModelInput as E, LunoraAiOptions as L, ModelInput as M, ResolvedAiGateway as R, WorkersAiProviderLike as W, LunoraAi as a, AI_GATEWAY_ID_ENV as b, AI_GATEWAY_TOKEN_ENV as c, AiBindingLike as d, AiGatewayMetadata as e, AiGatewayOptions as f, buildAiGatewayMetadataFields as g, resolveAiGateway as r };

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

@@ -1,4 +1,75 @@
 import { EmbeddingModel, LanguageModel } from 'ai';
+/**
+ * Project {@link AiGatewayMetadata} to a plain string-map of only its defined,
+ * non-empty fields, or `undefined` when nothing is set. This is the shared source
+ * of truth behind both gateway-correlation forms: the `cf-aig-metadata` HTTP
+ * header (bring-your-own providers) and the Workers AI binding's native
+ * `gateway.metadata` option — both encode the same `{ functionPath, traceId }`.
+ * @experimental
+ */
+declare const buildAiGatewayMetadataFields: (metadata: AiGatewayMetadata | undefined) => Record<string, string> | undefined;
+/**
+ * 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;
 /**
  * Structural projection of the Cloudflare Workers `AI` binding (`env.AI`).
  * Declared locally so unit tests can pass a plain-object double and the real
@@ -30,6 +101,12 @@ interface WorkersAiProviderLike {
 interface AiGatewayOptions {
   [key: string]: unknown;
   id: string;
+  /**
+   * Custom correlation metadata surfaced in the AI Gateway logs (Cloudflare's
+   * native `gateway.metadata`). `@lunora/ai` folds `{ functionPath, traceId }`
+   * here from {@link LunoraAiOptions.metadata} when a gateway is configured.
+   */
+  metadata?: Record<string, string>;
 }
 /**
  * `LunoraAiOptions` is part of the experimental `@lunora/ai` API and may change without a major version bump.
@@ -71,6 +148,15 @@ interface LunoraAiOptions {
    * value wins over anything derived from {@link LunoraAiOptions.env}.
    */
   gateway?: AiGatewayOptions;
+  /**
+   * Correlation metadata folded into the active gateway call (the Workers AI
+   * binding's native `gateway.metadata`) so an AI Gateway log entry ties back
+   * to the Lunora function + trace that made it. Only applied when a gateway is
+   * actually configured (explicit or env-derived) and only its defined fields
+   * are sent — absent otherwise, so behavior is unchanged. The generated
+   * `ctx.ai` facade threads `{ functionPath, traceId }` here automatically.
+   */
+  metadata?: AiGatewayMetadata;
   /**
    * Pre-built Workers AI provider. When omitted, one is constructed from
    * `binding` via `createWorkersAI`. Supplying it directly is the seam used by
@@ -118,4 +204,4 @@ interface LunoraAi {
   /** The underlying Workers AI provider — `ai.workersai("@cf/...")` for a raw model. */
   workersai: WorkersAiProviderLike;
 }
-export { AiBindingLike as A, EmbeddingModelInput as E, LunoraAiOptions as L, ModelInput as M, WorkersAiProviderLike as W, LunoraAi as a, AiGatewayOptions as b };
+export { AI_GATEWAY_ACCOUNT_ID_ENV as A, EmbeddingModelInput as E, LunoraAiOptions as L, ModelInput as M, ResolvedAiGateway as R, WorkersAiProviderLike as W, LunoraAi as a, AI_GATEWAY_ID_ENV as b, AI_GATEWAY_TOKEN_ENV as c, AiBindingLike as d, AiGatewayMetadata as e, AiGatewayOptions as f, buildAiGatewayMetadataFields as g, resolveAiGateway as r };

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-DGmh5Hq4.mjs";
+import { E as EmbeddingModelInput, a as LunoraAi } from "../packem_shared/types.d-F_Q8R8L3.mjs";
 /**
  * Built-in fixed-window chunker: split into `size`-char windows overlapping by
  * `overlap` chars. Deliberately simple and deterministic — the zero-config

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-DGmh5Hq4.js";
+import { E as EmbeddingModelInput, a as LunoraAi } from "../packem_shared/types.d-F_Q8R8L3.js";
 /**
  * Built-in fixed-window chunker: split into `size`-char windows overlapping by
  * `overlap` chars. Deliberately simple and deterministic — the zero-config

package/package.json

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