inngest 4.7.0 → 4.9.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # inngest
 
+## 4.9.0
+
+### Minor Changes
+
+- [#1594](https://github.com/inngest/inngest-js/pull/1594) [`124e55f8`](https://github.com/inngest/inngest-js/commit/124e55f8d159af9145a073c9756a6281da60185b) Thanks [@scottnuma](https://github.com/scottnuma)! - Expand AI step metadata extraction to more OTel GenAI span attributes. The SDK now records additional model, provider, response id, token, and request parameter fields from OTel GenAI spans while continuing to ignore prompt and response content.
+
+  This removes the previous metadata extraction for Open Inference, Vercel AI SDK-specific, and Langfuse-specific span attributes.
+
+## 4.8.0
+
+### Minor Changes
+
+- [#1595](https://github.com/inngest/inngest-js/pull/1595) [`aa315c7e`](https://github.com/inngest/inngest-js/commit/aa315c7ec9b99a69a7f85720e2805991b3e23841) Thanks [@amh4r](https://github.com/amh4r)! - Add opt-out for AI metadata extraction
+
+- [#1521](https://github.com/inngest/inngest-js/pull/1521) [`a69ec0e2`](https://github.com/inngest/inngest-js/commit/a69ec0e25acbf5c3a45b547ccf9d4d6819580a86) Thanks [@jakobevangelista](https://github.com/jakobevangelista)! - Add experimental createScorer function
+
+- [#1521](https://github.com/inngest/inngest-js/pull/1521) [`a69ec0e2`](https://github.com/inngest/inngest-js/commit/a69ec0e25acbf5c3a45b547ccf9d4d6819580a86) Thanks [@jakobevangelista](https://github.com/jakobevangelista)! - Add experimental scoring primitives for writing run- and step-scoped `inngest.score` metadata via `inngest.score()` and `scoreMiddleware()`-gated `step.score()`.
+
+### Patch Changes
+
+- [#1592](https://github.com/inngest/inngest-js/pull/1592) [`748c6cc4`](https://github.com/inngest/inngest-js/commit/748c6cc4fb167af9223c2b87d6c6543245d1428b) Thanks [@amh4r](https://github.com/amh4r)! - Deprecate Extended Traces provider creation. `behaviour: "createProvider"` and the `"auto"` fallback remain functional, but now direct users to preload `@inngest/otel/node` and extend that provider instead.
+
 ## 4.7.0
 
 ### Minor Changes

package/components/DeferredFunction.cjs

@@ -1,10 +1,39 @@
 const require_consts = require('../helpers/consts.cjs');
+const require_errors = require('../helpers/errors.cjs');
+const require_types = require('../helpers/types.cjs');
 const require_marker = require('../helpers/marker.cjs');
 const require_InngestFunction = require('./InngestFunction.cjs');
 
 //#region src/components/DeferredFunction.ts
 const idDenyRegex = /['\\\n\r]/;
 /**
+* Validates the reserved experiment-ref input key into an `ExperimentRef`, or
+* `undefined` when it's absent or malformed.
+*/
+function parseExperimentRef(value) {
+	if (require_types.isRecord(value) && typeof value.experimentName === "string" && typeof value.variant === "string") return {
+		experimentName: value.experimentName,
+		variant: value.variant
+	};
+}
+/**
+* Strips our `_inngest` metadata off an event's `data` in place and returns the
+* parent routing metadata extracted from it.
+*/
+function stripInngestMetadata(event) {
+	const { _inngest, [require_consts.deferExperimentKey]: experiment, ...input } = event.data ?? {};
+	if (!require_types.isRecord(_inngest)) throw new require_errors.UnreachableError("deferred event is missing _inngest metadata");
+	const { parent_fn_slug, parent_run_id } = _inngest;
+	if (typeof parent_fn_slug !== "string") throw new require_errors.UnreachableError("deferred event _inngest metadata is missing parent_fn_slug");
+	if (typeof parent_run_id !== "string") throw new require_errors.UnreachableError("deferred event _inngest metadata is missing parent_run_id");
+	event.data = input;
+	return {
+		fnSlug: parent_fn_slug,
+		runId: parent_run_id,
+		experiment: parseExperimentRef(experiment)
+	};
+}
+/**
 * EXPERIMENTAL: This API is not yet stable and may change in the future without
 * a major version bump.
 *
@@ -37,6 +66,29 @@ var DeferredFunction = class extends require_InngestFunction.InngestFunction {
 			expression: `event.data._inngest.fn_slug == '${fnId}'`
 		}];
 	}
+	/**
+	* Installs a `transformCtx` hook that runs before middleware and user code:
+	* - Strips our `_inngest` metadata off each event's `data`, ensuring it
+	*   matches what the user expects.
+	* - Collects the parent function's slug and run ID from that metadata into
+	*   `ctx.parents`, so the handler can correlate each event to its parent.
+	*/
+	createExecution(opts) {
+		return super.createExecution({
+			...opts,
+			partialOptions: {
+				...opts.partialOptions,
+				transformCtx: (ctx) => {
+					const parents = ctx.events.map(stripInngestMetadata);
+					stripInngestMetadata(ctx.event);
+					return {
+						...ctx,
+						parents
+					};
+				}
+			}
+		});
+	}
 };
 /**
 * EXPERIMENTAL: This API is not yet stable and may change in the future without

package/components/DeferredFunction.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"DeferredFunction.cjs","names":["InngestFunction","markerKey","internalEvents"],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { internalEvents } from \"../helpers/consts.ts\";\nimport { type Marker, markerKey } from \"../helpers/marker.ts\";\nimport type {\n  ApplyAllMiddlewareCtxExtensions,\n  ApplyAllMiddlewareStepExtensions,\n  BaseContext,\n  FunctionConfig,\n  Handler,\n} from \"../types.ts\";\nimport type {\n  builtInMiddleware,\n  ClientOptionsFromInngest,\n  Inngest,\n} from \"./Inngest.ts\";\nimport { InngestFunction } from \"./InngestFunction.ts\";\nimport type { createStepTools } from \"./InngestStepTools.ts\";\nimport type { Middleware } from \"./middleware/index.ts\";\n\nconst idDenyRegex = /['\\\\\\n\\r]/;\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * A defer (companion) function created via `createDefer(...)`. Real\n * `InngestFunction` at runtime, but with the trigger pinned to\n * `inngest/deferred.schedule` (see `getConfigTriggers`), `triggers` and\n * `onFailure` disallowed, and the schema carried as a typed instance\n * property so callers of `defer(id, { function, data })` can extract it.\n *\n * Identify a defer function at runtime via `isDeferredFunction(value)` from\n * `helpers/marker.ts`. Prefer that over `instanceof`, which fails across\n * duplicate SDK copies in the same process.\n *\n * @public\n */\nexport class DeferredFunction<\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n> extends InngestFunction<\n  InngestFunction.Options<[], never>,\n  Handler.Any,\n  never,\n  Inngest.Any,\n  []\n> {\n  readonly schema: TSchema;\n  readonly [markerKey]: Marker = { kind: \"DeferredFunction\" };\n\n  constructor(\n    client: Inngest.Any,\n    opts: DeferredFunction.Options,\n    handler: Handler.Any,\n    schema: TSchema,\n  ) {\n    // The id is interpolated into a CEL trigger expression\n    // (`event.data._inngest.fn_slug == '${fnId}'`). Reject characters that\n    // would break the single-quoted string literal.\n    if (idDenyRegex.test(opts.id)) {\n      throw new Error(\n        `invalid id \"${opts.id}\"; must match ${idDenyRegex.source}`,\n      );\n    }\n    super(\n      client,\n      { ...opts, triggers: [] } as InngestFunction.Options<[], never>,\n      handler,\n    );\n    this.schema = schema;\n  }\n\n  protected override getConfigTriggers(\n    fnId: string,\n  ): FunctionConfig[\"triggers\"] {\n    return [\n      {\n        event: internalEvents.DeferredSchedule,\n        expression: `event.data._inngest.fn_slug == '${fnId}'`,\n      },\n    ];\n  }\n}\n\n/**\n * @public\n */\nexport namespace DeferredFunction {\n  /**\n   * Matches any `DeferredFunction` regardless of its schema. Use as the\n   * constraint for the `function` argument of `defer()`.\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: widest schema constraint for inference\n  export type Any = DeferredFunction<StandardSchemaV1<any> | undefined>;\n\n  /**\n   * The user-facing options accepted by `createDefer(client, opts, handler)`.\n   * Mirrors `InngestFunction.Options` minus `triggers` (implicit), `onFailure`\n   * (not yet supported), and `batchEvents` (each `defer(...)` is its own run).\n   */\n  export type Options = Omit<\n    InngestFunction.Options<[], never>,\n    \"triggers\" | \"onFailure\" | \"batchEvents\"\n  >;\n}\n\n/**\n * The `event` shape a defer handler receives. With a schema, `data`\n * narrows to its inferred type; without one, it falls back to\n * `Record<string, any>`.\n */\ntype DeferEvent<TSchema> = {\n  name: internalEvents.DeferredSchedule;\n  data: TSchema extends StandardSchemaV1<\n    infer D extends Record<string, unknown>\n  >\n    ? D\n    : // biome-ignore lint/suspicious/noExplicitAny: no schema = any\n      Record<string, any>;\n};\n\n/**\n * Base ctx shape for a defer handler: the standard function context\n * (`runId`, `attempt`, `group`, `step` with middleware step extensions)\n * with `event`/`events` pinned to `inngest/deferred.schedule` and the\n * schema-typed payload.\n */\ntype BaseDeferCtx<\n  TClient extends Inngest.Any,\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = Omit<BaseContext<TClient>, \"event\" | \"events\" | \"step\"> & {\n  event: DeferEvent<TSchema>;\n  events: [DeferEvent<TSchema>];\n  step: ReturnType<typeof createStepTools<TClient, TFnMiddleware>> &\n    ApplyAllMiddlewareStepExtensions<\n      ClientOptionsFromInngest<TClient>[\"middleware\"]\n    > &\n    ApplyAllMiddlewareStepExtensions<TFnMiddleware>;\n};\n\n/**\n * Input type for `createDefer`. Same shape as `DeferredFunction.Options`\n * plus `schema` (the StandardSchema describing `event.data` that flows\n * to caller `defer(id, { function, data })` call sites) and `middleware`.\n */\nexport type CreateDeferInput<\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = DeferredFunction.Options & {\n  schema?: TSchema;\n  middleware?: TFnMiddleware;\n};\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * Create a typed defer function. One `createDefer` call = one Inngest\n * function. Returns a `DeferredFunction<TSchema>` so callers of `defer(id,\n * { function, data })` get the data type inferred from the schema.\n *\n * Mirrors `inngest.createFunction(opts, handler)`, with three differences:\n * the client is the first positional arg, `triggers` is not accepted (the\n * SDK emits an implicit `inngest/deferred.schedule` trigger), and `schema`\n * describes the payload that callers will send via `defer(id, { function,\n * data })`.\n *\n * Pass the result to `serve()` alongside regular functions so the SDK\n * registers it.\n */\nexport function createDefer<\n  TClient extends Inngest.Any,\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n  const TFnMiddleware extends Middleware.Class[] | undefined = undefined,\n  THandler extends Handler.Any = (\n    ctx: BaseDeferCtx<TClient, TFnMiddleware, TSchema> &\n      ApplyAllMiddlewareCtxExtensions<\n        [...ReturnType<typeof builtInMiddleware>]\n      > &\n      ApplyAllMiddlewareCtxExtensions<\n        ClientOptionsFromInngest<TClient>[\"middleware\"]\n      > &\n      ApplyAllMiddlewareCtxExtensions<TFnMiddleware>,\n  ) => unknown,\n>(\n  client: TClient,\n  options: CreateDeferInput<TFnMiddleware, TSchema>,\n  handler: THandler,\n): DeferredFunction<TSchema> {\n  const { schema, ...rest } = options;\n  return new DeferredFunction<TSchema>(\n    client,\n    rest,\n    handler as Handler.Any,\n    schema as TSchema,\n  );\n}\n"],"mappings":";;;;;AAmBA,MAAM,cAAc;;;;;;;;;;;;;;;;;AAkBpB,IAAa,mBAAb,cAIUA,wCAMR;CACA,AAAS;CACT,CAAUC,4BAAqB,EAAE,MAAM,oBAAoB;CAE3D,YACE,QACA,MACA,SACA,QACA;AAIA,MAAI,YAAY,KAAK,KAAK,GAAG,CAC3B,OAAM,IAAI,MACR,eAAe,KAAK,GAAG,gBAAgB,YAAY,SACpD;AAEH,QACE,QACA;GAAE,GAAG;GAAM,UAAU,EAAE;GAAE,EACzB,QACD;AACD,OAAK,SAAS;;CAGhB,AAAmB,kBACjB,MAC4B;AAC5B,SAAO,CACL;GACE,OAAOC,8BAAe;GACtB,YAAY,mCAAmC,KAAK;GACrD,CACF;;;;;;;;;;;;;;;;;;;;AA2FL,SAAgB,YAiBd,QACA,SACA,SAC2B;CAC3B,MAAM,EAAE,QAAQ,GAAG,SAAS;AAC5B,QAAO,IAAI,iBACT,QACA,MACA,SACA,OACD"}
+{"version":3,"file":"DeferredFunction.cjs","names":["isRecord","deferExperimentKey","UnreachableError","InngestFunction","markerKey","internalEvents"],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { deferExperimentKey, internalEvents } from \"../helpers/consts.ts\";\nimport { UnreachableError } from \"../helpers/errors.ts\";\nimport { type Marker, markerKey } from \"../helpers/marker.ts\";\nimport { isRecord } from \"../helpers/types.ts\";\nimport type {\n  ApplyAllMiddlewareCtxExtensions,\n  ApplyAllMiddlewareStepExtensions,\n  BaseContext,\n  ExperimentRef,\n  FunctionConfig,\n  Handler,\n} from \"../types.ts\";\nimport type { IInngestExecution } from \"./execution/InngestExecution.ts\";\nimport type {\n  builtInMiddleware,\n  ClientOptionsFromInngest,\n  Inngest,\n} from \"./Inngest.ts\";\nimport {\n  type CreateExecutionOptions,\n  InngestFunction,\n} from \"./InngestFunction.ts\";\nimport type { createStepTools } from \"./InngestStepTools.ts\";\nimport type { Middleware } from \"./middleware/index.ts\";\n\nconst idDenyRegex = /['\\\\\\n\\r]/;\n\n/**\n * Validates the reserved experiment-ref input key into an `ExperimentRef`, or\n * `undefined` when it's absent or malformed.\n */\nfunction parseExperimentRef(value: unknown): ExperimentRef | undefined {\n  if (\n    isRecord(value) &&\n    typeof value.experimentName === \"string\" &&\n    typeof value.variant === \"string\"\n  ) {\n    return { experimentName: value.experimentName, variant: value.variant };\n  }\n  return undefined;\n}\n\n/**\n * Strips our `_inngest` metadata off an event's `data` in place and returns the\n * parent routing metadata extracted from it.\n */\nfunction stripInngestMetadata(event: {\n  data?: Record<string, unknown>;\n}): DeferredFunction.Parent {\n  const data = event.data ?? {};\n  const { _inngest, [deferExperimentKey]: experiment, ...input } = data;\n\n  if (!isRecord(_inngest)) {\n    throw new UnreachableError(\"deferred event is missing _inngest metadata\");\n  }\n  const { parent_fn_slug, parent_run_id } = _inngest;\n  if (typeof parent_fn_slug !== \"string\") {\n    throw new UnreachableError(\n      \"deferred event _inngest metadata is missing parent_fn_slug\",\n    );\n  }\n  if (typeof parent_run_id !== \"string\") {\n    throw new UnreachableError(\n      \"deferred event _inngest metadata is missing parent_run_id\",\n    );\n  }\n\n  // Mutate in place\n  event.data = input;\n\n  return {\n    fnSlug: parent_fn_slug,\n    runId: parent_run_id,\n    experiment: parseExperimentRef(experiment),\n  };\n}\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * A defer (companion) function created via `createDefer(...)`. Real\n * `InngestFunction` at runtime, but with the trigger pinned to\n * `inngest/deferred.schedule` (see `getConfigTriggers`), `triggers` and\n * `onFailure` disallowed, and the schema carried as a typed instance\n * property so callers of `defer(id, { function, data })` can extract it.\n *\n * Identify a defer function at runtime via `isDeferredFunction(value)` from\n * `helpers/marker.ts`. Prefer that over `instanceof`, which fails across\n * duplicate SDK copies in the same process.\n *\n * @public\n */\nexport class DeferredFunction<\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n> extends InngestFunction<\n  InngestFunction.Options<[], never>,\n  Handler.Any,\n  never,\n  Inngest.Any,\n  []\n> {\n  readonly schema: TSchema;\n  readonly [markerKey]: Marker = { kind: \"DeferredFunction\" };\n\n  constructor(\n    client: Inngest.Any,\n    opts: DeferredFunction.Options,\n    handler: Handler.Any,\n    schema: TSchema,\n  ) {\n    // The id is interpolated into a CEL trigger expression\n    // (`event.data._inngest.fn_slug == '${fnId}'`). Reject characters that\n    // would break the single-quoted string literal.\n    if (idDenyRegex.test(opts.id)) {\n      throw new Error(\n        `invalid id \"${opts.id}\"; must match ${idDenyRegex.source}`,\n      );\n    }\n    super(\n      client,\n      { ...opts, triggers: [] } as InngestFunction.Options<[], never>,\n      handler,\n    );\n    this.schema = schema;\n  }\n\n  protected override getConfigTriggers(\n    fnId: string,\n  ): FunctionConfig[\"triggers\"] {\n    return [\n      {\n        event: internalEvents.DeferredSchedule,\n        expression: `event.data._inngest.fn_slug == '${fnId}'`,\n      },\n    ];\n  }\n\n  /**\n   * Installs a `transformCtx` hook that runs before middleware and user code:\n   * - Strips our `_inngest` metadata off each event's `data`, ensuring it\n   *   matches what the user expects.\n   * - Collects the parent function's slug and run ID from that metadata into\n   *   `ctx.parents`, so the handler can correlate each event to its parent.\n   */\n  protected override createExecution(\n    opts: CreateExecutionOptions,\n  ): IInngestExecution {\n    return super.createExecution({\n      ...opts,\n      partialOptions: {\n        ...opts.partialOptions,\n        transformCtx: (ctx) => {\n          // Get the parent info from each event. Also removes our internal\n          // metadata from each event (mutates in place).\n          const parents = ctx.events.map(stripInngestMetadata);\n\n          // Removes our internal metadata from the event (mutates in place).\n          stripInngestMetadata(ctx.event);\n\n          return {\n            ...ctx,\n            parents,\n          };\n        },\n      },\n    });\n  }\n}\n\n/**\n * @public\n */\nexport namespace DeferredFunction {\n  /**\n   * Matches any `DeferredFunction` regardless of its schema. Use as the\n   * constraint for the `function` argument of `defer()`.\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: widest schema constraint for inference\n  export type Any = DeferredFunction<StandardSchemaV1<any> | undefined>;\n\n  /**\n   * The user-facing options accepted by `createDefer(client, opts, handler)`.\n   * Mirrors `InngestFunction.Options` minus `triggers` (implicit), `onFailure`\n   * (not yet supported), and `batchEvents` (each `defer(...)` is its own run).\n   */\n  export type Options = Omit<\n    InngestFunction.Options<[], never>,\n    \"triggers\" | \"onFailure\" | \"batchEvents\"\n  >;\n\n  /**\n   * Metadata describing the parent run that triggered the deferred run. Derived\n   * from `event.data._inngest` and surfaced on the handler ctx as `parents[i]`,\n   * aligned with `events[i]`.\n   */\n  export type Parent = {\n    fnSlug: string;\n    runId: string;\n    experiment?: ExperimentRef;\n  };\n}\n\n/**\n * The `event` shape a defer handler receives. `data` carries the user payload\n * directly, narrowed by the schema if one is set (otherwise\n * `Record<string, any>`). Parent metadata is exposed separately on\n * `ctx.parents` so events and parents can be matched by index.\n */\ntype DeferEvent<TSchema> = {\n  name: internalEvents.DeferredSchedule;\n  data: TSchema extends StandardSchemaV1<\n    infer D extends Record<string, unknown>\n  >\n    ? D\n    : // biome-ignore lint/suspicious/noExplicitAny: no schema = any\n      Record<string, any>;\n};\n\n/**\n * Base ctx shape for a defer handler: the standard function context\n * (`runId`, `attempt`, `group`, `step` with middleware step extensions)\n * with `event`/`events` pinned to `inngest/deferred.schedule` and the\n * schema-typed payload, plus `parents` aligned with `events` by index.\n */\ntype BaseDeferCtx<\n  TClient extends Inngest.Any,\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = Omit<BaseContext<TClient>, \"event\" | \"events\" | \"step\"> & {\n  event: DeferEvent<TSchema>;\n  events: [DeferEvent<TSchema>];\n  parents: [DeferredFunction.Parent];\n  step: ReturnType<typeof createStepTools<TClient, TFnMiddleware>> &\n    ApplyAllMiddlewareStepExtensions<\n      ClientOptionsFromInngest<TClient>[\"middleware\"]\n    > &\n    ApplyAllMiddlewareStepExtensions<TFnMiddleware>;\n};\n\n/**\n * Input type for `createDefer`. Same shape as `DeferredFunction.Options`\n * plus `schema` (the StandardSchema describing `event.data` that flows\n * to caller `defer(id, { function, data })` call sites) and `middleware`.\n */\nexport type CreateDeferInput<\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = DeferredFunction.Options & {\n  schema?: TSchema;\n  middleware?: TFnMiddleware;\n};\n\n/**\n * Full handler context for a defer function: `BaseDeferCtx` plus every\n * middleware ctx extension that applies (built-in, client, function-level).\n */\nexport type DeferContext<\n  TClient extends Inngest.Any,\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = BaseDeferCtx<TClient, TFnMiddleware, TSchema> &\n  ApplyAllMiddlewareCtxExtensions<[...ReturnType<typeof builtInMiddleware>]> &\n  ApplyAllMiddlewareCtxExtensions<\n    ClientOptionsFromInngest<TClient>[\"middleware\"]\n  > &\n  ApplyAllMiddlewareCtxExtensions<TFnMiddleware>;\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * Create a typed defer function. One `createDefer` call = one Inngest\n * function. Returns a `DeferredFunction<TSchema>` so callers of `defer(id,\n * { function, data })` get the data type inferred from the schema.\n *\n * Mirrors `inngest.createFunction(opts, handler)`, with three differences:\n * the client is the first positional arg, `triggers` is not accepted (the\n * SDK emits an implicit `inngest/deferred.schedule` trigger), and `schema`\n * describes the payload that callers will send via `defer(id, { function,\n * data })`.\n *\n * Pass the result to `serve()` alongside regular functions so the SDK\n * registers it.\n */\nexport function createDefer<\n  TClient extends Inngest.Any,\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n  const TFnMiddleware extends Middleware.Class[] | undefined = undefined,\n  THandler extends Handler.Any = (\n    ctx: DeferContext<TClient, TFnMiddleware, TSchema>,\n  ) => unknown,\n>(\n  client: TClient,\n  options: CreateDeferInput<TFnMiddleware, TSchema>,\n  handler: THandler,\n): DeferredFunction<TSchema> {\n  const { schema, ...rest } = options;\n  return new DeferredFunction<TSchema>(\n    client,\n    rest,\n    handler as Handler.Any,\n    schema as TSchema,\n  );\n}\n"],"mappings":";;;;;;;AA0BA,MAAM,cAAc;;;;;AAMpB,SAAS,mBAAmB,OAA2C;AACrE,KACEA,uBAAS,MAAM,IACf,OAAO,MAAM,mBAAmB,YAChC,OAAO,MAAM,YAAY,SAEzB,QAAO;EAAE,gBAAgB,MAAM;EAAgB,SAAS,MAAM;EAAS;;;;;;AAS3E,SAAS,qBAAqB,OAEF;CAE1B,MAAM,EAAE,WAAWC,oCAAqB,YAAY,GAAG,UAD1C,MAAM,QAAQ,EAAE;AAG7B,KAAI,CAACD,uBAAS,SAAS,CACrB,OAAM,IAAIE,gCAAiB,8CAA8C;CAE3E,MAAM,EAAE,gBAAgB,kBAAkB;AAC1C,KAAI,OAAO,mBAAmB,SAC5B,OAAM,IAAIA,gCACR,6DACD;AAEH,KAAI,OAAO,kBAAkB,SAC3B,OAAM,IAAIA,gCACR,4DACD;AAIH,OAAM,OAAO;AAEb,QAAO;EACL,QAAQ;EACR,OAAO;EACP,YAAY,mBAAmB,WAAW;EAC3C;;;;;;;;;;;;;;;;;;AAmBH,IAAa,mBAAb,cAIUC,wCAMR;CACA,AAAS;CACT,CAAUC,4BAAqB,EAAE,MAAM,oBAAoB;CAE3D,YACE,QACA,MACA,SACA,QACA;AAIA,MAAI,YAAY,KAAK,KAAK,GAAG,CAC3B,OAAM,IAAI,MACR,eAAe,KAAK,GAAG,gBAAgB,YAAY,SACpD;AAEH,QACE,QACA;GAAE,GAAG;GAAM,UAAU,EAAE;GAAE,EACzB,QACD;AACD,OAAK,SAAS;;CAGhB,AAAmB,kBACjB,MAC4B;AAC5B,SAAO,CACL;GACE,OAAOC,8BAAe;GACtB,YAAY,mCAAmC,KAAK;GACrD,CACF;;;;;;;;;CAUH,AAAmB,gBACjB,MACmB;AACnB,SAAO,MAAM,gBAAgB;GAC3B,GAAG;GACH,gBAAgB;IACd,GAAG,KAAK;IACR,eAAe,QAAQ;KAGrB,MAAM,UAAU,IAAI,OAAO,IAAI,qBAAqB;AAGpD,0BAAqB,IAAI,MAAM;AAE/B,YAAO;MACL,GAAG;MACH;MACD;;IAEJ;GACF,CAAC;;;;;;;;;;;;;;;;;;;;AAuHN,SAAgB,YAUd,QACA,SACA,SAC2B;CAC3B,MAAM,EAAE,QAAQ,GAAG,SAAS;AAC5B,QAAO,IAAI,iBACT,QACA,MACA,SACA,OACD"}

package/components/DeferredFunction.d.cts

@@ -1,9 +1,10 @@
 import { internalEvents } from "../helpers/consts.cjs";
 import { Marker, markerKey } from "../helpers/marker.cjs";
-import { Middleware } from "./middleware/middleware.cjs";
 import { createStepTools } from "./InngestStepTools.cjs";
-import { InngestFunction } from "./InngestFunction.cjs";
-import { ApplyAllMiddlewareCtxExtensions, ApplyAllMiddlewareStepExtensions, BaseContext, FunctionConfig, Handler } from "../types.cjs";
+import { Middleware } from "./middleware/middleware.cjs";
+import { CreateExecutionOptions, InngestFunction } from "./InngestFunction.cjs";
+import { IInngestExecution } from "./execution/InngestExecution.cjs";
+import { ApplyAllMiddlewareCtxExtensions, ApplyAllMiddlewareStepExtensions, BaseContext, ExperimentRef, FunctionConfig, Handler } from "../types.cjs";
 import { ClientOptionsFromInngest, Inngest, builtInMiddleware } from "./Inngest.cjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
@@ -30,6 +31,14 @@ declare class DeferredFunction<TSchema extends StandardSchemaV1<Record<string, u
   readonly [markerKey]: Marker;
   constructor(client: Inngest.Any, opts: DeferredFunction.Options, handler: Handler.Any, schema: TSchema);
   protected getConfigTriggers(fnId: string): FunctionConfig["triggers"];
+  /**
+   * Installs a `transformCtx` hook that runs before middleware and user code:
+   * - Strips our `_inngest` metadata off each event's `data`, ensuring it
+   *   matches what the user expects.
+   * - Collects the parent function's slug and run ID from that metadata into
+   *   `ctx.parents`, so the handler can correlate each event to its parent.
+   */
+  protected createExecution(opts: CreateExecutionOptions): IInngestExecution;
 }
 /**
  * @public
@@ -46,11 +55,22 @@ declare namespace DeferredFunction {
    * (not yet supported), and `batchEvents` (each `defer(...)` is its own run).
    */
   type Options = Omit<InngestFunction.Options<[], never>, "triggers" | "onFailure" | "batchEvents">;
+  /**
+   * Metadata describing the parent run that triggered the deferred run. Derived
+   * from `event.data._inngest` and surfaced on the handler ctx as `parents[i]`,
+   * aligned with `events[i]`.
+   */
+  type Parent = {
+    fnSlug: string;
+    runId: string;
+    experiment?: ExperimentRef;
+  };
 }
 /**
- * The `event` shape a defer handler receives. With a schema, `data`
- * narrows to its inferred type; without one, it falls back to
- * `Record<string, any>`.
+ * The `event` shape a defer handler receives. `data` carries the user payload
+ * directly, narrowed by the schema if one is set (otherwise
+ * `Record<string, any>`). Parent metadata is exposed separately on
+ * `ctx.parents` so events and parents can be matched by index.
  */
 type DeferEvent<TSchema> = {
   name: internalEvents.DeferredSchedule;
@@ -60,11 +80,12 @@ type DeferEvent<TSchema> = {
  * Base ctx shape for a defer handler: the standard function context
  * (`runId`, `attempt`, `group`, `step` with middleware step extensions)
  * with `event`/`events` pinned to `inngest/deferred.schedule` and the
- * schema-typed payload.
+ * schema-typed payload, plus `parents` aligned with `events` by index.
  */
 type BaseDeferCtx<TClient extends Inngest.Any, TFnMiddleware extends Middleware.Class[] | undefined, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined> = Omit<BaseContext<TClient>, "event" | "events" | "step"> & {
   event: DeferEvent<TSchema>;
   events: [DeferEvent<TSchema>];
+  parents: [DeferredFunction.Parent];
   step: ReturnType<typeof createStepTools<TClient, TFnMiddleware>> & ApplyAllMiddlewareStepExtensions<ClientOptionsFromInngest<TClient>["middleware"]> & ApplyAllMiddlewareStepExtensions<TFnMiddleware>;
 };
 /**
@@ -76,6 +97,11 @@ type CreateDeferInput<TFnMiddleware extends Middleware.Class[] | undefined, TSch
   schema?: TSchema;
   middleware?: TFnMiddleware;
 };
+/**
+ * Full handler context for a defer function: `BaseDeferCtx` plus every
+ * middleware ctx extension that applies (built-in, client, function-level).
+ */
+type DeferContext<TClient extends Inngest.Any, TFnMiddleware extends Middleware.Class[] | undefined, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined> = BaseDeferCtx<TClient, TFnMiddleware, TSchema> & ApplyAllMiddlewareCtxExtensions<[...ReturnType<typeof builtInMiddleware>]> & ApplyAllMiddlewareCtxExtensions<ClientOptionsFromInngest<TClient>["middleware"]> & ApplyAllMiddlewareCtxExtensions<TFnMiddleware>;
 /**
  * EXPERIMENTAL: This API is not yet stable and may change in the future without
  * a major version bump.
@@ -93,7 +119,7 @@ type CreateDeferInput<TFnMiddleware extends Middleware.Class[] | undefined, TSch
  * Pass the result to `serve()` alongside regular functions so the SDK
  * registers it.
  */
-declare function createDefer<TClient extends Inngest.Any, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined = undefined, const TFnMiddleware extends Middleware.Class[] | undefined = undefined, THandler extends Handler.Any = (ctx: BaseDeferCtx<TClient, TFnMiddleware, TSchema> & ApplyAllMiddlewareCtxExtensions<[...ReturnType<typeof builtInMiddleware>]> & ApplyAllMiddlewareCtxExtensions<ClientOptionsFromInngest<TClient>["middleware"]> & ApplyAllMiddlewareCtxExtensions<TFnMiddleware>) => unknown>(client: TClient, options: CreateDeferInput<TFnMiddleware, TSchema>, handler: THandler): DeferredFunction<TSchema>;
+declare function createDefer<TClient extends Inngest.Any, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined = undefined, const TFnMiddleware extends Middleware.Class[] | undefined = undefined, THandler extends Handler.Any = (ctx: DeferContext<TClient, TFnMiddleware, TSchema>) => unknown>(client: TClient, options: CreateDeferInput<TFnMiddleware, TSchema>, handler: THandler): DeferredFunction<TSchema>;
 //#endregion
-export { DeferredFunction, createDefer };
+export { CreateDeferInput, DeferContext, DeferredFunction, createDefer };
 //# sourceMappingURL=DeferredFunction.d.cts.map

package/components/DeferredFunction.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"DeferredFunction.d.cts","names":[],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"DeferredFunction.d.cts","names":[],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":[],"mappings":"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"}

package/components/DeferredFunction.d.ts

@@ -1,9 +1,10 @@
 import { internalEvents } from "../helpers/consts.js";
 import { Marker, markerKey } from "../helpers/marker.js";
-import { Middleware } from "./middleware/middleware.js";
 import { createStepTools } from "./InngestStepTools.js";
-import { InngestFunction } from "./InngestFunction.js";
-import { ApplyAllMiddlewareCtxExtensions, ApplyAllMiddlewareStepExtensions, BaseContext, FunctionConfig, Handler } from "../types.js";
+import { Middleware } from "./middleware/middleware.js";
+import { CreateExecutionOptions, InngestFunction } from "./InngestFunction.js";
+import { IInngestExecution } from "./execution/InngestExecution.js";
+import { ApplyAllMiddlewareCtxExtensions, ApplyAllMiddlewareStepExtensions, BaseContext, ExperimentRef, FunctionConfig, Handler } from "../types.js";
 import { ClientOptionsFromInngest, Inngest, builtInMiddleware } from "./Inngest.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
@@ -30,6 +31,14 @@ declare class DeferredFunction<TSchema extends StandardSchemaV1<Record<string, u
   readonly [markerKey]: Marker;
   constructor(client: Inngest.Any, opts: DeferredFunction.Options, handler: Handler.Any, schema: TSchema);
   protected getConfigTriggers(fnId: string): FunctionConfig["triggers"];
+  /**
+   * Installs a `transformCtx` hook that runs before middleware and user code:
+   * - Strips our `_inngest` metadata off each event's `data`, ensuring it
+   *   matches what the user expects.
+   * - Collects the parent function's slug and run ID from that metadata into
+   *   `ctx.parents`, so the handler can correlate each event to its parent.
+   */
+  protected createExecution(opts: CreateExecutionOptions): IInngestExecution;
 }
 /**
  * @public
@@ -46,11 +55,22 @@ declare namespace DeferredFunction {
    * (not yet supported), and `batchEvents` (each `defer(...)` is its own run).
    */
   type Options = Omit<InngestFunction.Options<[], never>, "triggers" | "onFailure" | "batchEvents">;
+  /**
+   * Metadata describing the parent run that triggered the deferred run. Derived
+   * from `event.data._inngest` and surfaced on the handler ctx as `parents[i]`,
+   * aligned with `events[i]`.
+   */
+  type Parent = {
+    fnSlug: string;
+    runId: string;
+    experiment?: ExperimentRef;
+  };
 }
 /**
- * The `event` shape a defer handler receives. With a schema, `data`
- * narrows to its inferred type; without one, it falls back to
- * `Record<string, any>`.
+ * The `event` shape a defer handler receives. `data` carries the user payload
+ * directly, narrowed by the schema if one is set (otherwise
+ * `Record<string, any>`). Parent metadata is exposed separately on
+ * `ctx.parents` so events and parents can be matched by index.
  */
 type DeferEvent<TSchema> = {
   name: internalEvents.DeferredSchedule;
@@ -60,11 +80,12 @@ type DeferEvent<TSchema> = {
  * Base ctx shape for a defer handler: the standard function context
  * (`runId`, `attempt`, `group`, `step` with middleware step extensions)
  * with `event`/`events` pinned to `inngest/deferred.schedule` and the
- * schema-typed payload.
+ * schema-typed payload, plus `parents` aligned with `events` by index.
  */
 type BaseDeferCtx<TClient extends Inngest.Any, TFnMiddleware extends Middleware.Class[] | undefined, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined> = Omit<BaseContext<TClient>, "event" | "events" | "step"> & {
   event: DeferEvent<TSchema>;
   events: [DeferEvent<TSchema>];
+  parents: [DeferredFunction.Parent];
   step: ReturnType<typeof createStepTools<TClient, TFnMiddleware>> & ApplyAllMiddlewareStepExtensions<ClientOptionsFromInngest<TClient>["middleware"]> & ApplyAllMiddlewareStepExtensions<TFnMiddleware>;
 };
 /**
@@ -76,6 +97,11 @@ type CreateDeferInput<TFnMiddleware extends Middleware.Class[] | undefined, TSch
   schema?: TSchema;
   middleware?: TFnMiddleware;
 };
+/**
+ * Full handler context for a defer function: `BaseDeferCtx` plus every
+ * middleware ctx extension that applies (built-in, client, function-level).
+ */
+type DeferContext<TClient extends Inngest.Any, TFnMiddleware extends Middleware.Class[] | undefined, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined> = BaseDeferCtx<TClient, TFnMiddleware, TSchema> & ApplyAllMiddlewareCtxExtensions<[...ReturnType<typeof builtInMiddleware>]> & ApplyAllMiddlewareCtxExtensions<ClientOptionsFromInngest<TClient>["middleware"]> & ApplyAllMiddlewareCtxExtensions<TFnMiddleware>;
 /**
  * EXPERIMENTAL: This API is not yet stable and may change in the future without
  * a major version bump.
@@ -93,7 +119,7 @@ type CreateDeferInput<TFnMiddleware extends Middleware.Class[] | undefined, TSch
  * Pass the result to `serve()` alongside regular functions so the SDK
  * registers it.
  */
-declare function createDefer<TClient extends Inngest.Any, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined = undefined, const TFnMiddleware extends Middleware.Class[] | undefined = undefined, THandler extends Handler.Any = (ctx: BaseDeferCtx<TClient, TFnMiddleware, TSchema> & ApplyAllMiddlewareCtxExtensions<[...ReturnType<typeof builtInMiddleware>]> & ApplyAllMiddlewareCtxExtensions<ClientOptionsFromInngest<TClient>["middleware"]> & ApplyAllMiddlewareCtxExtensions<TFnMiddleware>) => unknown>(client: TClient, options: CreateDeferInput<TFnMiddleware, TSchema>, handler: THandler): DeferredFunction<TSchema>;
+declare function createDefer<TClient extends Inngest.Any, TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined = undefined, const TFnMiddleware extends Middleware.Class[] | undefined = undefined, THandler extends Handler.Any = (ctx: DeferContext<TClient, TFnMiddleware, TSchema>) => unknown>(client: TClient, options: CreateDeferInput<TFnMiddleware, TSchema>, handler: THandler): DeferredFunction<TSchema>;
 //#endregion
-export { DeferredFunction, createDefer };
+export { CreateDeferInput, DeferContext, DeferredFunction, createDefer };
 //# sourceMappingURL=DeferredFunction.d.ts.map

package/components/DeferredFunction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DeferredFunction.d.ts","names":[],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"DeferredFunction.d.ts","names":[],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":[],"mappings":"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"}

package/components/DeferredFunction.js

@@ -1,10 +1,39 @@
-import { internalEvents } from "../helpers/consts.js";
+import { deferExperimentKey, internalEvents } from "../helpers/consts.js";
+import { UnreachableError } from "../helpers/errors.js";
+import { isRecord } from "../helpers/types.js";
 import { markerKey } from "../helpers/marker.js";
 import { InngestFunction } from "./InngestFunction.js";
 
 //#region src/components/DeferredFunction.ts
 const idDenyRegex = /['\\\n\r]/;
 /**
+* Validates the reserved experiment-ref input key into an `ExperimentRef`, or
+* `undefined` when it's absent or malformed.
+*/
+function parseExperimentRef(value) {
+	if (isRecord(value) && typeof value.experimentName === "string" && typeof value.variant === "string") return {
+		experimentName: value.experimentName,
+		variant: value.variant
+	};
+}
+/**
+* Strips our `_inngest` metadata off an event's `data` in place and returns the
+* parent routing metadata extracted from it.
+*/
+function stripInngestMetadata(event) {
+	const { _inngest, [deferExperimentKey]: experiment, ...input } = event.data ?? {};
+	if (!isRecord(_inngest)) throw new UnreachableError("deferred event is missing _inngest metadata");
+	const { parent_fn_slug, parent_run_id } = _inngest;
+	if (typeof parent_fn_slug !== "string") throw new UnreachableError("deferred event _inngest metadata is missing parent_fn_slug");
+	if (typeof parent_run_id !== "string") throw new UnreachableError("deferred event _inngest metadata is missing parent_run_id");
+	event.data = input;
+	return {
+		fnSlug: parent_fn_slug,
+		runId: parent_run_id,
+		experiment: parseExperimentRef(experiment)
+	};
+}
+/**
 * EXPERIMENTAL: This API is not yet stable and may change in the future without
 * a major version bump.
 *
@@ -37,6 +66,29 @@ var DeferredFunction = class extends InngestFunction {
 			expression: `event.data._inngest.fn_slug == '${fnId}'`
 		}];
 	}
+	/**
+	* Installs a `transformCtx` hook that runs before middleware and user code:
+	* - Strips our `_inngest` metadata off each event's `data`, ensuring it
+	*   matches what the user expects.
+	* - Collects the parent function's slug and run ID from that metadata into
+	*   `ctx.parents`, so the handler can correlate each event to its parent.
+	*/
+	createExecution(opts) {
+		return super.createExecution({
+			...opts,
+			partialOptions: {
+				...opts.partialOptions,
+				transformCtx: (ctx) => {
+					const parents = ctx.events.map(stripInngestMetadata);
+					stripInngestMetadata(ctx.event);
+					return {
+						...ctx,
+						parents
+					};
+				}
+			}
+		});
+	}
 };
 /**
 * EXPERIMENTAL: This API is not yet stable and may change in the future without

package/components/DeferredFunction.js.map

@@ -1 +1 @@
-{"version":3,"file":"DeferredFunction.js","names":[],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { internalEvents } from \"../helpers/consts.ts\";\nimport { type Marker, markerKey } from \"../helpers/marker.ts\";\nimport type {\n  ApplyAllMiddlewareCtxExtensions,\n  ApplyAllMiddlewareStepExtensions,\n  BaseContext,\n  FunctionConfig,\n  Handler,\n} from \"../types.ts\";\nimport type {\n  builtInMiddleware,\n  ClientOptionsFromInngest,\n  Inngest,\n} from \"./Inngest.ts\";\nimport { InngestFunction } from \"./InngestFunction.ts\";\nimport type { createStepTools } from \"./InngestStepTools.ts\";\nimport type { Middleware } from \"./middleware/index.ts\";\n\nconst idDenyRegex = /['\\\\\\n\\r]/;\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * A defer (companion) function created via `createDefer(...)`. Real\n * `InngestFunction` at runtime, but with the trigger pinned to\n * `inngest/deferred.schedule` (see `getConfigTriggers`), `triggers` and\n * `onFailure` disallowed, and the schema carried as a typed instance\n * property so callers of `defer(id, { function, data })` can extract it.\n *\n * Identify a defer function at runtime via `isDeferredFunction(value)` from\n * `helpers/marker.ts`. Prefer that over `instanceof`, which fails across\n * duplicate SDK copies in the same process.\n *\n * @public\n */\nexport class DeferredFunction<\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n> extends InngestFunction<\n  InngestFunction.Options<[], never>,\n  Handler.Any,\n  never,\n  Inngest.Any,\n  []\n> {\n  readonly schema: TSchema;\n  readonly [markerKey]: Marker = { kind: \"DeferredFunction\" };\n\n  constructor(\n    client: Inngest.Any,\n    opts: DeferredFunction.Options,\n    handler: Handler.Any,\n    schema: TSchema,\n  ) {\n    // The id is interpolated into a CEL trigger expression\n    // (`event.data._inngest.fn_slug == '${fnId}'`). Reject characters that\n    // would break the single-quoted string literal.\n    if (idDenyRegex.test(opts.id)) {\n      throw new Error(\n        `invalid id \"${opts.id}\"; must match ${idDenyRegex.source}`,\n      );\n    }\n    super(\n      client,\n      { ...opts, triggers: [] } as InngestFunction.Options<[], never>,\n      handler,\n    );\n    this.schema = schema;\n  }\n\n  protected override getConfigTriggers(\n    fnId: string,\n  ): FunctionConfig[\"triggers\"] {\n    return [\n      {\n        event: internalEvents.DeferredSchedule,\n        expression: `event.data._inngest.fn_slug == '${fnId}'`,\n      },\n    ];\n  }\n}\n\n/**\n * @public\n */\nexport namespace DeferredFunction {\n  /**\n   * Matches any `DeferredFunction` regardless of its schema. Use as the\n   * constraint for the `function` argument of `defer()`.\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: widest schema constraint for inference\n  export type Any = DeferredFunction<StandardSchemaV1<any> | undefined>;\n\n  /**\n   * The user-facing options accepted by `createDefer(client, opts, handler)`.\n   * Mirrors `InngestFunction.Options` minus `triggers` (implicit), `onFailure`\n   * (not yet supported), and `batchEvents` (each `defer(...)` is its own run).\n   */\n  export type Options = Omit<\n    InngestFunction.Options<[], never>,\n    \"triggers\" | \"onFailure\" | \"batchEvents\"\n  >;\n}\n\n/**\n * The `event` shape a defer handler receives. With a schema, `data`\n * narrows to its inferred type; without one, it falls back to\n * `Record<string, any>`.\n */\ntype DeferEvent<TSchema> = {\n  name: internalEvents.DeferredSchedule;\n  data: TSchema extends StandardSchemaV1<\n    infer D extends Record<string, unknown>\n  >\n    ? D\n    : // biome-ignore lint/suspicious/noExplicitAny: no schema = any\n      Record<string, any>;\n};\n\n/**\n * Base ctx shape for a defer handler: the standard function context\n * (`runId`, `attempt`, `group`, `step` with middleware step extensions)\n * with `event`/`events` pinned to `inngest/deferred.schedule` and the\n * schema-typed payload.\n */\ntype BaseDeferCtx<\n  TClient extends Inngest.Any,\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = Omit<BaseContext<TClient>, \"event\" | \"events\" | \"step\"> & {\n  event: DeferEvent<TSchema>;\n  events: [DeferEvent<TSchema>];\n  step: ReturnType<typeof createStepTools<TClient, TFnMiddleware>> &\n    ApplyAllMiddlewareStepExtensions<\n      ClientOptionsFromInngest<TClient>[\"middleware\"]\n    > &\n    ApplyAllMiddlewareStepExtensions<TFnMiddleware>;\n};\n\n/**\n * Input type for `createDefer`. Same shape as `DeferredFunction.Options`\n * plus `schema` (the StandardSchema describing `event.data` that flows\n * to caller `defer(id, { function, data })` call sites) and `middleware`.\n */\nexport type CreateDeferInput<\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = DeferredFunction.Options & {\n  schema?: TSchema;\n  middleware?: TFnMiddleware;\n};\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * Create a typed defer function. One `createDefer` call = one Inngest\n * function. Returns a `DeferredFunction<TSchema>` so callers of `defer(id,\n * { function, data })` get the data type inferred from the schema.\n *\n * Mirrors `inngest.createFunction(opts, handler)`, with three differences:\n * the client is the first positional arg, `triggers` is not accepted (the\n * SDK emits an implicit `inngest/deferred.schedule` trigger), and `schema`\n * describes the payload that callers will send via `defer(id, { function,\n * data })`.\n *\n * Pass the result to `serve()` alongside regular functions so the SDK\n * registers it.\n */\nexport function createDefer<\n  TClient extends Inngest.Any,\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n  const TFnMiddleware extends Middleware.Class[] | undefined = undefined,\n  THandler extends Handler.Any = (\n    ctx: BaseDeferCtx<TClient, TFnMiddleware, TSchema> &\n      ApplyAllMiddlewareCtxExtensions<\n        [...ReturnType<typeof builtInMiddleware>]\n      > &\n      ApplyAllMiddlewareCtxExtensions<\n        ClientOptionsFromInngest<TClient>[\"middleware\"]\n      > &\n      ApplyAllMiddlewareCtxExtensions<TFnMiddleware>,\n  ) => unknown,\n>(\n  client: TClient,\n  options: CreateDeferInput<TFnMiddleware, TSchema>,\n  handler: THandler,\n): DeferredFunction<TSchema> {\n  const { schema, ...rest } = options;\n  return new DeferredFunction<TSchema>(\n    client,\n    rest,\n    handler as Handler.Any,\n    schema as TSchema,\n  );\n}\n"],"mappings":";;;;;AAmBA,MAAM,cAAc;;;;;;;;;;;;;;;;;AAkBpB,IAAa,mBAAb,cAIU,gBAMR;CACA,AAAS;CACT,CAAU,aAAqB,EAAE,MAAM,oBAAoB;CAE3D,YACE,QACA,MACA,SACA,QACA;AAIA,MAAI,YAAY,KAAK,KAAK,GAAG,CAC3B,OAAM,IAAI,MACR,eAAe,KAAK,GAAG,gBAAgB,YAAY,SACpD;AAEH,QACE,QACA;GAAE,GAAG;GAAM,UAAU,EAAE;GAAE,EACzB,QACD;AACD,OAAK,SAAS;;CAGhB,AAAmB,kBACjB,MAC4B;AAC5B,SAAO,CACL;GACE,OAAO,eAAe;GACtB,YAAY,mCAAmC,KAAK;GACrD,CACF;;;;;;;;;;;;;;;;;;;;AA2FL,SAAgB,YAiBd,QACA,SACA,SAC2B;CAC3B,MAAM,EAAE,QAAQ,GAAG,SAAS;AAC5B,QAAO,IAAI,iBACT,QACA,MACA,SACA,OACD"}
+{"version":3,"file":"DeferredFunction.js","names":[],"sources":["../../src/components/DeferredFunction.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { deferExperimentKey, internalEvents } from \"../helpers/consts.ts\";\nimport { UnreachableError } from \"../helpers/errors.ts\";\nimport { type Marker, markerKey } from \"../helpers/marker.ts\";\nimport { isRecord } from \"../helpers/types.ts\";\nimport type {\n  ApplyAllMiddlewareCtxExtensions,\n  ApplyAllMiddlewareStepExtensions,\n  BaseContext,\n  ExperimentRef,\n  FunctionConfig,\n  Handler,\n} from \"../types.ts\";\nimport type { IInngestExecution } from \"./execution/InngestExecution.ts\";\nimport type {\n  builtInMiddleware,\n  ClientOptionsFromInngest,\n  Inngest,\n} from \"./Inngest.ts\";\nimport {\n  type CreateExecutionOptions,\n  InngestFunction,\n} from \"./InngestFunction.ts\";\nimport type { createStepTools } from \"./InngestStepTools.ts\";\nimport type { Middleware } from \"./middleware/index.ts\";\n\nconst idDenyRegex = /['\\\\\\n\\r]/;\n\n/**\n * Validates the reserved experiment-ref input key into an `ExperimentRef`, or\n * `undefined` when it's absent or malformed.\n */\nfunction parseExperimentRef(value: unknown): ExperimentRef | undefined {\n  if (\n    isRecord(value) &&\n    typeof value.experimentName === \"string\" &&\n    typeof value.variant === \"string\"\n  ) {\n    return { experimentName: value.experimentName, variant: value.variant };\n  }\n  return undefined;\n}\n\n/**\n * Strips our `_inngest` metadata off an event's `data` in place and returns the\n * parent routing metadata extracted from it.\n */\nfunction stripInngestMetadata(event: {\n  data?: Record<string, unknown>;\n}): DeferredFunction.Parent {\n  const data = event.data ?? {};\n  const { _inngest, [deferExperimentKey]: experiment, ...input } = data;\n\n  if (!isRecord(_inngest)) {\n    throw new UnreachableError(\"deferred event is missing _inngest metadata\");\n  }\n  const { parent_fn_slug, parent_run_id } = _inngest;\n  if (typeof parent_fn_slug !== \"string\") {\n    throw new UnreachableError(\n      \"deferred event _inngest metadata is missing parent_fn_slug\",\n    );\n  }\n  if (typeof parent_run_id !== \"string\") {\n    throw new UnreachableError(\n      \"deferred event _inngest metadata is missing parent_run_id\",\n    );\n  }\n\n  // Mutate in place\n  event.data = input;\n\n  return {\n    fnSlug: parent_fn_slug,\n    runId: parent_run_id,\n    experiment: parseExperimentRef(experiment),\n  };\n}\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * A defer (companion) function created via `createDefer(...)`. Real\n * `InngestFunction` at runtime, but with the trigger pinned to\n * `inngest/deferred.schedule` (see `getConfigTriggers`), `triggers` and\n * `onFailure` disallowed, and the schema carried as a typed instance\n * property so callers of `defer(id, { function, data })` can extract it.\n *\n * Identify a defer function at runtime via `isDeferredFunction(value)` from\n * `helpers/marker.ts`. Prefer that over `instanceof`, which fails across\n * duplicate SDK copies in the same process.\n *\n * @public\n */\nexport class DeferredFunction<\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n> extends InngestFunction<\n  InngestFunction.Options<[], never>,\n  Handler.Any,\n  never,\n  Inngest.Any,\n  []\n> {\n  readonly schema: TSchema;\n  readonly [markerKey]: Marker = { kind: \"DeferredFunction\" };\n\n  constructor(\n    client: Inngest.Any,\n    opts: DeferredFunction.Options,\n    handler: Handler.Any,\n    schema: TSchema,\n  ) {\n    // The id is interpolated into a CEL trigger expression\n    // (`event.data._inngest.fn_slug == '${fnId}'`). Reject characters that\n    // would break the single-quoted string literal.\n    if (idDenyRegex.test(opts.id)) {\n      throw new Error(\n        `invalid id \"${opts.id}\"; must match ${idDenyRegex.source}`,\n      );\n    }\n    super(\n      client,\n      { ...opts, triggers: [] } as InngestFunction.Options<[], never>,\n      handler,\n    );\n    this.schema = schema;\n  }\n\n  protected override getConfigTriggers(\n    fnId: string,\n  ): FunctionConfig[\"triggers\"] {\n    return [\n      {\n        event: internalEvents.DeferredSchedule,\n        expression: `event.data._inngest.fn_slug == '${fnId}'`,\n      },\n    ];\n  }\n\n  /**\n   * Installs a `transformCtx` hook that runs before middleware and user code:\n   * - Strips our `_inngest` metadata off each event's `data`, ensuring it\n   *   matches what the user expects.\n   * - Collects the parent function's slug and run ID from that metadata into\n   *   `ctx.parents`, so the handler can correlate each event to its parent.\n   */\n  protected override createExecution(\n    opts: CreateExecutionOptions,\n  ): IInngestExecution {\n    return super.createExecution({\n      ...opts,\n      partialOptions: {\n        ...opts.partialOptions,\n        transformCtx: (ctx) => {\n          // Get the parent info from each event. Also removes our internal\n          // metadata from each event (mutates in place).\n          const parents = ctx.events.map(stripInngestMetadata);\n\n          // Removes our internal metadata from the event (mutates in place).\n          stripInngestMetadata(ctx.event);\n\n          return {\n            ...ctx,\n            parents,\n          };\n        },\n      },\n    });\n  }\n}\n\n/**\n * @public\n */\nexport namespace DeferredFunction {\n  /**\n   * Matches any `DeferredFunction` regardless of its schema. Use as the\n   * constraint for the `function` argument of `defer()`.\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: widest schema constraint for inference\n  export type Any = DeferredFunction<StandardSchemaV1<any> | undefined>;\n\n  /**\n   * The user-facing options accepted by `createDefer(client, opts, handler)`.\n   * Mirrors `InngestFunction.Options` minus `triggers` (implicit), `onFailure`\n   * (not yet supported), and `batchEvents` (each `defer(...)` is its own run).\n   */\n  export type Options = Omit<\n    InngestFunction.Options<[], never>,\n    \"triggers\" | \"onFailure\" | \"batchEvents\"\n  >;\n\n  /**\n   * Metadata describing the parent run that triggered the deferred run. Derived\n   * from `event.data._inngest` and surfaced on the handler ctx as `parents[i]`,\n   * aligned with `events[i]`.\n   */\n  export type Parent = {\n    fnSlug: string;\n    runId: string;\n    experiment?: ExperimentRef;\n  };\n}\n\n/**\n * The `event` shape a defer handler receives. `data` carries the user payload\n * directly, narrowed by the schema if one is set (otherwise\n * `Record<string, any>`). Parent metadata is exposed separately on\n * `ctx.parents` so events and parents can be matched by index.\n */\ntype DeferEvent<TSchema> = {\n  name: internalEvents.DeferredSchedule;\n  data: TSchema extends StandardSchemaV1<\n    infer D extends Record<string, unknown>\n  >\n    ? D\n    : // biome-ignore lint/suspicious/noExplicitAny: no schema = any\n      Record<string, any>;\n};\n\n/**\n * Base ctx shape for a defer handler: the standard function context\n * (`runId`, `attempt`, `group`, `step` with middleware step extensions)\n * with `event`/`events` pinned to `inngest/deferred.schedule` and the\n * schema-typed payload, plus `parents` aligned with `events` by index.\n */\ntype BaseDeferCtx<\n  TClient extends Inngest.Any,\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = Omit<BaseContext<TClient>, \"event\" | \"events\" | \"step\"> & {\n  event: DeferEvent<TSchema>;\n  events: [DeferEvent<TSchema>];\n  parents: [DeferredFunction.Parent];\n  step: ReturnType<typeof createStepTools<TClient, TFnMiddleware>> &\n    ApplyAllMiddlewareStepExtensions<\n      ClientOptionsFromInngest<TClient>[\"middleware\"]\n    > &\n    ApplyAllMiddlewareStepExtensions<TFnMiddleware>;\n};\n\n/**\n * Input type for `createDefer`. Same shape as `DeferredFunction.Options`\n * plus `schema` (the StandardSchema describing `event.data` that flows\n * to caller `defer(id, { function, data })` call sites) and `middleware`.\n */\nexport type CreateDeferInput<\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = DeferredFunction.Options & {\n  schema?: TSchema;\n  middleware?: TFnMiddleware;\n};\n\n/**\n * Full handler context for a defer function: `BaseDeferCtx` plus every\n * middleware ctx extension that applies (built-in, client, function-level).\n */\nexport type DeferContext<\n  TClient extends Inngest.Any,\n  TFnMiddleware extends Middleware.Class[] | undefined,\n  TSchema extends StandardSchemaV1<Record<string, unknown>> | undefined,\n> = BaseDeferCtx<TClient, TFnMiddleware, TSchema> &\n  ApplyAllMiddlewareCtxExtensions<[...ReturnType<typeof builtInMiddleware>]> &\n  ApplyAllMiddlewareCtxExtensions<\n    ClientOptionsFromInngest<TClient>[\"middleware\"]\n  > &\n  ApplyAllMiddlewareCtxExtensions<TFnMiddleware>;\n\n/**\n * EXPERIMENTAL: This API is not yet stable and may change in the future without\n * a major version bump.\n *\n * Create a typed defer function. One `createDefer` call = one Inngest\n * function. Returns a `DeferredFunction<TSchema>` so callers of `defer(id,\n * { function, data })` get the data type inferred from the schema.\n *\n * Mirrors `inngest.createFunction(opts, handler)`, with three differences:\n * the client is the first positional arg, `triggers` is not accepted (the\n * SDK emits an implicit `inngest/deferred.schedule` trigger), and `schema`\n * describes the payload that callers will send via `defer(id, { function,\n * data })`.\n *\n * Pass the result to `serve()` alongside regular functions so the SDK\n * registers it.\n */\nexport function createDefer<\n  TClient extends Inngest.Any,\n  TSchema extends\n    | StandardSchemaV1<Record<string, unknown>>\n    | undefined = undefined,\n  const TFnMiddleware extends Middleware.Class[] | undefined = undefined,\n  THandler extends Handler.Any = (\n    ctx: DeferContext<TClient, TFnMiddleware, TSchema>,\n  ) => unknown,\n>(\n  client: TClient,\n  options: CreateDeferInput<TFnMiddleware, TSchema>,\n  handler: THandler,\n): DeferredFunction<TSchema> {\n  const { schema, ...rest } = options;\n  return new DeferredFunction<TSchema>(\n    client,\n    rest,\n    handler as Handler.Any,\n    schema as TSchema,\n  );\n}\n"],"mappings":";;;;;;;AA0BA,MAAM,cAAc;;;;;AAMpB,SAAS,mBAAmB,OAA2C;AACrE,KACE,SAAS,MAAM,IACf,OAAO,MAAM,mBAAmB,YAChC,OAAO,MAAM,YAAY,SAEzB,QAAO;EAAE,gBAAgB,MAAM;EAAgB,SAAS,MAAM;EAAS;;;;;;AAS3E,SAAS,qBAAqB,OAEF;CAE1B,MAAM,EAAE,WAAW,qBAAqB,YAAY,GAAG,UAD1C,MAAM,QAAQ,EAAE;AAG7B,KAAI,CAAC,SAAS,SAAS,CACrB,OAAM,IAAI,iBAAiB,8CAA8C;CAE3E,MAAM,EAAE,gBAAgB,kBAAkB;AAC1C,KAAI,OAAO,mBAAmB,SAC5B,OAAM,IAAI,iBACR,6DACD;AAEH,KAAI,OAAO,kBAAkB,SAC3B,OAAM,IAAI,iBACR,4DACD;AAIH,OAAM,OAAO;AAEb,QAAO;EACL,QAAQ;EACR,OAAO;EACP,YAAY,mBAAmB,WAAW;EAC3C;;;;;;;;;;;;;;;;;;AAmBH,IAAa,mBAAb,cAIU,gBAMR;CACA,AAAS;CACT,CAAU,aAAqB,EAAE,MAAM,oBAAoB;CAE3D,YACE,QACA,MACA,SACA,QACA;AAIA,MAAI,YAAY,KAAK,KAAK,GAAG,CAC3B,OAAM,IAAI,MACR,eAAe,KAAK,GAAG,gBAAgB,YAAY,SACpD;AAEH,QACE,QACA;GAAE,GAAG;GAAM,UAAU,EAAE;GAAE,EACzB,QACD;AACD,OAAK,SAAS;;CAGhB,AAAmB,kBACjB,MAC4B;AAC5B,SAAO,CACL;GACE,OAAO,eAAe;GACtB,YAAY,mCAAmC,KAAK;GACrD,CACF;;;;;;;;;CAUH,AAAmB,gBACjB,MACmB;AACnB,SAAO,MAAM,gBAAgB;GAC3B,GAAG;GACH,gBAAgB;IACd,GAAG,KAAK;IACR,eAAe,QAAQ;KAGrB,MAAM,UAAU,IAAI,OAAO,IAAI,qBAAqB;AAGpD,0BAAqB,IAAI,MAAM;AAE/B,YAAO;MACL,GAAG;MACH;MACD;;IAEJ;GACF,CAAC;;;;;;;;;;;;;;;;;;;;AAuHN,SAAgB,YAUd,QACA,SACA,SAC2B;CAC3B,MAAM,EAAE,QAAQ,GAAG,SAAS;AAC5B,QAAO,IAAI,iBACT,QACA,MACA,SACA,OACD"}

package/components/Inngest.cjs

@@ -14,6 +14,7 @@ const require_metadataProcessor = require('./execution/otel/metadataProcessor.cj
 const require_InngestFunction = require('./InngestFunction.cjs');
 const require_middleware = require('./middleware/middleware.cjs');
 const require_InngestMetadata = require('./InngestMetadata.cjs');
+const require_InngestScore = require('./InngestScore.cjs');
 const require_InngestStepTools = require('./InngestStepTools.cjs');
 const require_utils = require('./middleware/utils.cjs');
 const require_index = require('./realtime/subscribe/index.cjs');
@@ -58,6 +59,12 @@ var Inngest = class Inngest {
 	_cachedFetch;
 	_logger;
 	/**
+	* Whether this client should collect AI metadata from OpenTelemetry spans.
+	*
+	* @internal
+	*/
+	aiMetadataEnabled;
+	/**
 	* Logger for SDK internal messages. Falls back to the user's `logger` if
 	* `internalLogger` is not provided in client options.
 	*
@@ -77,6 +84,11 @@ var Inngest = class Inngest {
 	*/
 	experimentalMetadataEnabled = false;
 	/**
+	* @internal
+	* Flag set by scoreMiddleware to enable step.score().
+	*/
+	experimentalScoreEnabled = false;
+	/**
 	* A dummy Inngest function used in Durable Endpoints. This is necessary
 	* because the vast majority of middleware hooks require the Inngest function.
 	* But for Durable Endpoints, there is no Inngest function. So we need some
@@ -173,6 +185,16 @@ var Inngest = class Inngest {
 		return new require_InngestMetadata.UnscopedMetadataBuilder(this);
 	}
 	/**
+	* Write scores. Call directly to write a live score for a run or step; use
+	* `inngest.score.experiment(...)` to attach a score to a `group.experiment()`
+	* variant.
+	*
+	* For standalone durable score writes, prefer `step.score()`.
+	*/
+	get score() {
+		return Object.assign((options) => require_InngestScore.sendScore(this, options), { experiment: (options) => require_InngestScore.sendScoreExperiment(this, options) });
+	}
+	/**
 	* A client used to interact with the Inngest API by sending or reacting to
 	* events.
 	*
@@ -185,6 +207,7 @@ var Inngest = class Inngest {
 		const { id, logger, middleware, appVersion } = this.options;
 		if (!id) throw new Error("An `id` must be passed to create an Inngest instance.");
 		this.id = id;
+		this.aiMetadataEnabled = this.options.aiMetadata !== false;
 		this._env = require_env.protectEnv({ ...require_env.getProcessEnv() });
 		this._userProvidedFetch = options.fetch;
 		this.inngestApi = new require_api.InngestApi({
@@ -201,7 +224,7 @@ var Inngest = class Inngest {
 			client: this,
 			fn: null
 		});
-		require_metadataProcessor.metadataSpanProcessor.attach();
+		if (this.aiMetadataEnabled) require_metadataProcessor.metadataSpanProcessor.attach();
 		this._appVersion = appVersion;
 	}
 	/**