@graphorin/provider 0.5.0

package/dist/middleware/with-cost-tracking.d.ts

@@ -0,0 +1,91 @@
+import * as _graphorin_core2 from "@graphorin/core";
+
+//#region src/middleware/with-cost-tracking.d.ts
+
+/**
+ * `withCostTracking` — reports `tokensUsed` + `cost` per `provider × model`
+ * from the `finish` event of every stream / one-shot generation via the
+ * `onUsage` hook. For a ready-made process-local accumulator, wire
+ * {@link createCostAccumulator}'s `onUsage` and read its `.totals()`; consumers
+ * that prefer the framework's `CostTracker` from `@graphorin/observability`
+ * pass their own delegate.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Aggregated totals for one `provider × model`, returned by
+ * {@link CostAccumulator.totalFor} / {@link CostAccumulator.totals}.
+ *
+ * @stable
+ */
+interface CostTrackingTotals {
+  readonly callCount: number;
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly totalTokens: number;
+  readonly costUsd: number;
+}
+/**
+ * A process-local cost accumulator (PS-8). Wire {@link CostAccumulator.onUsage}
+ * into {@link withCostTracking} and read the running totals — keyed by
+ * `provider × model` — back via {@link CostAccumulator.totals} /
+ * {@link CostAccumulator.totalFor}.
+ *
+ * @stable
+ */
+interface CostAccumulator {
+  /** Pass this to {@link withCostTracking}'s `onUsage`. */
+  readonly onUsage: NonNullable<WithCostTrackingOptions['onUsage']>;
+  /** Snapshot of every tracked `provider::model` → totals. */
+  totals(): ReadonlyMap<string, CostTrackingTotals>;
+  /** Running totals for one `provider × model` (zeros when unseen). */
+  totalFor(providerName: string, modelId: string): CostTrackingTotals;
+  /** Clear all accumulated totals. */
+  reset(): void;
+}
+/**
+ * Create a {@link CostAccumulator} — the process-local accumulator described on
+ * {@link withCostTracking}. Keys totals by `'<providerName>::<modelId>'`.
+ *
+ * @stable
+ */
+declare function createCostAccumulator(): CostAccumulator;
+/**
+ * Options for {@link withCostTracking}.
+ *
+ * @stable
+ */
+interface WithCostTrackingOptions {
+  /**
+   * Hook fired on every `finish` event with the parsed usage. The
+   * hook receives the underlying provider's name + modelId so the
+   * caller can route into a per-model accumulator.
+   */
+  readonly onUsage?: (info: {
+    readonly providerName: string;
+    readonly modelId: string;
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly totalTokens: number;
+    readonly costUsd: number;
+    readonly metadata: Readonly<Record<string, unknown>> | undefined;
+  }) => void;
+  /**
+   * Optional pricing lookup. When set, the middleware computes
+   * `costUsd` from the returned price and surfaces it on the hook.
+   */
+  readonly priceLookup?: (info: {
+    readonly providerName: string;
+    readonly modelId: string;
+  }) => {
+    readonly inputPerMtok?: number;
+    readonly outputPerMtok?: number;
+  } | null;
+}
+/**
+ * @stable
+ */
+declare const withCostTracking: (opts: WithCostTrackingOptions) => _graphorin_core2.ProviderMiddleware;
+//#endregion
+export { CostAccumulator, CostTrackingTotals, WithCostTrackingOptions, createCostAccumulator, withCostTracking };
+//# sourceMappingURL=with-cost-tracking.d.ts.map

package/dist/middleware/with-cost-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-cost-tracking.d.ts","names":[],"sources":["../../src/middleware/with-cost-tracking.ts"],"sourcesContent":[],"mappings":";;;;;;;AAqBA;AAgBA;;;;;;;AAyBA;AA0BA;AA4BA;;;UA/FiB,kBAAA;;;;;;;;;;;;;;;UAgBA,eAAA;;oBAEG,YAAY;;YAEpB,oBAAoB;;mDAEmB;;;;;;;;;;iBAmBnC,qBAAA,CAAA,GAAyB;;;;;;UA0BxB,uBAAA;;;;;;;;;;;;;uBAaM,SAAS;;;;;;;;;;;;;;;;;cAenB,yBAAgB,4BAAA,gBAAA,CAAA"}

package/dist/middleware/with-cost-tracking.js

@@ -0,0 +1,95 @@
+import { defineProviderMiddleware } from "./compose.js";
+
+//#region src/middleware/with-cost-tracking.ts
+const ZERO_TOTALS = Object.freeze({
+	callCount: 0,
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	costUsd: 0
+});
+/**
+* Create a {@link CostAccumulator} — the process-local accumulator described on
+* {@link withCostTracking}. Keys totals by `'<providerName>::<modelId>'`.
+*
+* @stable
+*/
+function createCostAccumulator() {
+	const map = /* @__PURE__ */ new Map();
+	const keyOf = (providerName, modelId) => `${providerName}::${modelId}`;
+	return {
+		onUsage: (info) => {
+			const key = keyOf(info.providerName, info.modelId);
+			const prev = map.get(key) ?? ZERO_TOTALS;
+			map.set(key, {
+				callCount: prev.callCount + 1,
+				promptTokens: prev.promptTokens + info.promptTokens,
+				completionTokens: prev.completionTokens + info.completionTokens,
+				totalTokens: prev.totalTokens + info.totalTokens,
+				costUsd: prev.costUsd + info.costUsd
+			});
+		},
+		totals: () => new Map(map),
+		totalFor: (providerName, modelId) => map.get(keyOf(providerName, modelId)) ?? ZERO_TOTALS,
+		reset: () => map.clear()
+	};
+}
+/**
+* @stable
+*/
+const withCostTracking = defineProviderMiddleware({
+	kind: "withCostTracking",
+	factory: (opts) => {
+		return (next) => ({
+			name: next.name,
+			modelId: next.modelId,
+			capabilities: next.capabilities,
+			...next.acceptsSensitivity !== void 0 ? { acceptsSensitivity: next.acceptsSensitivity } : {},
+			stream(req) {
+				return trackingStream(next, req, opts);
+			},
+			async generate(req) {
+				const result = await next.generate(req);
+				emitUsage(result, next, opts, asRecord(req.metadata));
+				return result;
+			},
+			...next.countTokens ? { countTokens: next.countTokens.bind(next) } : {}
+		});
+	}
+});
+async function* trackingStream(next, req, opts) {
+	const metadata = asRecord(req.metadata);
+	for await (const event of next.stream(req)) {
+		yield event;
+		if (event.type === "finish") emitUsage({
+			usage: event.usage,
+			finishReason: event.finishReason
+		}, next, opts, metadata);
+	}
+}
+function asRecord(value) {
+	if (value === void 0 || value === null) return void 0;
+	return value;
+}
+function emitUsage(result, next, opts, metadata) {
+	if (opts.onUsage === void 0) return;
+	const usage = result.usage;
+	const price = opts.priceLookup?.({
+		providerName: next.name,
+		modelId: next.modelId
+	}) ?? null;
+	const costUsd = price !== null ? usage.promptTokens * (price.inputPerMtok ?? 0) / 1e6 + usage.completionTokens * (price.outputPerMtok ?? 0) / 1e6 : usage.cost?.amount ?? 0;
+	opts.onUsage({
+		providerName: next.name,
+		modelId: next.modelId,
+		promptTokens: usage.promptTokens,
+		completionTokens: usage.completionTokens,
+		totalTokens: usage.totalTokens,
+		costUsd,
+		metadata
+	});
+}
+
+//#endregion
+export { createCostAccumulator, withCostTracking };
+//# sourceMappingURL=with-cost-tracking.js.map

package/dist/middleware/with-cost-tracking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-cost-tracking.js","names":["ZERO_TOTALS: CostTrackingTotals"],"sources":["../../src/middleware/with-cost-tracking.ts"],"sourcesContent":["/**\n * `withCostTracking` — reports `tokensUsed` + `cost` per `provider × model`\n * from the `finish` event of every stream / one-shot generation via the\n * `onUsage` hook. For a ready-made process-local accumulator, wire\n * {@link createCostAccumulator}'s `onUsage` and read its `.totals()`; consumers\n * that prefer the framework's `CostTracker` from `@graphorin/observability`\n * pass their own delegate.\n *\n * @packageDocumentation\n */\n\nimport type { Provider, ProviderEvent, ProviderResponse } from '@graphorin/core';\n\nimport { defineProviderMiddleware } from './compose.js';\n\n/**\n * Aggregated totals for one `provider × model`, returned by\n * {@link CostAccumulator.totalFor} / {@link CostAccumulator.totals}.\n *\n * @stable\n */\nexport interface CostTrackingTotals {\n  readonly callCount: number;\n  readonly promptTokens: number;\n  readonly completionTokens: number;\n  readonly totalTokens: number;\n  readonly costUsd: number;\n}\n\n/**\n * A process-local cost accumulator (PS-8). Wire {@link CostAccumulator.onUsage}\n * into {@link withCostTracking} and read the running totals — keyed by\n * `provider × model` — back via {@link CostAccumulator.totals} /\n * {@link CostAccumulator.totalFor}.\n *\n * @stable\n */\nexport interface CostAccumulator {\n  /** Pass this to {@link withCostTracking}'s `onUsage`. */\n  readonly onUsage: NonNullable<WithCostTrackingOptions['onUsage']>;\n  /** Snapshot of every tracked `provider::model` → totals. */\n  totals(): ReadonlyMap<string, CostTrackingTotals>;\n  /** Running totals for one `provider × model` (zeros when unseen). */\n  totalFor(providerName: string, modelId: string): CostTrackingTotals;\n  /** Clear all accumulated totals. */\n  reset(): void;\n}\n\nconst ZERO_TOTALS: CostTrackingTotals = Object.freeze({\n  callCount: 0,\n  promptTokens: 0,\n  completionTokens: 0,\n  totalTokens: 0,\n  costUsd: 0,\n});\n\n/**\n * Create a {@link CostAccumulator} — the process-local accumulator described on\n * {@link withCostTracking}. Keys totals by `'<providerName>::<modelId>'`.\n *\n * @stable\n */\nexport function createCostAccumulator(): CostAccumulator {\n  const map = new Map<string, CostTrackingTotals>();\n  const keyOf = (providerName: string, modelId: string): string => `${providerName}::${modelId}`;\n  return {\n    onUsage: (info) => {\n      const key = keyOf(info.providerName, info.modelId);\n      const prev = map.get(key) ?? ZERO_TOTALS;\n      map.set(key, {\n        callCount: prev.callCount + 1,\n        promptTokens: prev.promptTokens + info.promptTokens,\n        completionTokens: prev.completionTokens + info.completionTokens,\n        totalTokens: prev.totalTokens + info.totalTokens,\n        costUsd: prev.costUsd + info.costUsd,\n      });\n    },\n    totals: () => new Map(map),\n    totalFor: (providerName, modelId) => map.get(keyOf(providerName, modelId)) ?? ZERO_TOTALS,\n    reset: () => map.clear(),\n  };\n}\n\n/**\n * Options for {@link withCostTracking}.\n *\n * @stable\n */\nexport interface WithCostTrackingOptions {\n  /**\n   * Hook fired on every `finish` event with the parsed usage. The\n   * hook receives the underlying provider's name + modelId so the\n   * caller can route into a per-model accumulator.\n   */\n  readonly onUsage?: (info: {\n    readonly providerName: string;\n    readonly modelId: string;\n    readonly promptTokens: number;\n    readonly completionTokens: number;\n    readonly totalTokens: number;\n    readonly costUsd: number;\n    readonly metadata: Readonly<Record<string, unknown>> | undefined;\n  }) => void;\n  /**\n   * Optional pricing lookup. When set, the middleware computes\n   * `costUsd` from the returned price and surfaces it on the hook.\n   */\n  readonly priceLookup?: (info: {\n    readonly providerName: string;\n    readonly modelId: string;\n  }) => { readonly inputPerMtok?: number; readonly outputPerMtok?: number } | null;\n}\n\n/**\n * @stable\n */\nexport const withCostTracking = defineProviderMiddleware<WithCostTrackingOptions>({\n  kind: 'withCostTracking',\n  factory: (opts: WithCostTrackingOptions) => {\n    return (next: Provider): Provider => ({\n      name: next.name,\n      modelId: next.modelId,\n      capabilities: next.capabilities,\n      ...(next.acceptsSensitivity !== undefined\n        ? { acceptsSensitivity: next.acceptsSensitivity }\n        : {}),\n      stream(req) {\n        return trackingStream(next, req, opts);\n      },\n      async generate(req) {\n        const result = await next.generate(req);\n        emitUsage(result, next, opts, asRecord(req.metadata));\n        return result;\n      },\n      ...(next.countTokens ? { countTokens: next.countTokens.bind(next) } : {}),\n    });\n  },\n});\n\nasync function* trackingStream(\n  next: Provider,\n  req: import('@graphorin/core').ProviderRequest,\n  opts: WithCostTrackingOptions,\n): AsyncIterable<ProviderEvent> {\n  const metadata = asRecord(req.metadata);\n  for await (const event of next.stream(req)) {\n    yield event;\n    if (event.type === 'finish') {\n      emitUsage({ usage: event.usage, finishReason: event.finishReason }, next, opts, metadata);\n    }\n  }\n}\n\nfunction asRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {\n  if (value === undefined || value === null) return undefined;\n  return value as Readonly<Record<string, unknown>>;\n}\n\nfunction emitUsage(\n  result:\n    | ProviderResponse\n    | { usage: ProviderResponse['usage']; finishReason: ProviderResponse['finishReason'] },\n  next: Provider,\n  opts: WithCostTrackingOptions,\n  metadata: Readonly<Record<string, unknown>> | undefined,\n): void {\n  if (opts.onUsage === undefined) return;\n  const usage = result.usage;\n  const price = opts.priceLookup?.({ providerName: next.name, modelId: next.modelId }) ?? null;\n  const costUsd =\n    price !== null\n      ? (usage.promptTokens * (price.inputPerMtok ?? 0)) / 1_000_000 +\n        (usage.completionTokens * (price.outputPerMtok ?? 0)) / 1_000_000\n      : (usage.cost?.amount ?? 0);\n  opts.onUsage({\n    providerName: next.name,\n    modelId: next.modelId,\n    promptTokens: usage.promptTokens,\n    completionTokens: usage.completionTokens,\n    totalTokens: usage.totalTokens,\n    costUsd,\n    metadata,\n  });\n}\n"],"mappings":";;;AAgDA,MAAMA,cAAkC,OAAO,OAAO;CACpD,WAAW;CACX,cAAc;CACd,kBAAkB;CAClB,aAAa;CACb,SAAS;CACV,CAAC;;;;;;;AAQF,SAAgB,wBAAyC;CACvD,MAAM,sBAAM,IAAI,KAAiC;CACjD,MAAM,SAAS,cAAsB,YAA4B,GAAG,aAAa,IAAI;AACrF,QAAO;EACL,UAAU,SAAS;GACjB,MAAM,MAAM,MAAM,KAAK,cAAc,KAAK,QAAQ;GAClD,MAAM,OAAO,IAAI,IAAI,IAAI,IAAI;AAC7B,OAAI,IAAI,KAAK;IACX,WAAW,KAAK,YAAY;IAC5B,cAAc,KAAK,eAAe,KAAK;IACvC,kBAAkB,KAAK,mBAAmB,KAAK;IAC/C,aAAa,KAAK,cAAc,KAAK;IACrC,SAAS,KAAK,UAAU,KAAK;IAC9B,CAAC;;EAEJ,cAAc,IAAI,IAAI,IAAI;EAC1B,WAAW,cAAc,YAAY,IAAI,IAAI,MAAM,cAAc,QAAQ,CAAC,IAAI;EAC9E,aAAa,IAAI,OAAO;EACzB;;;;;AAoCH,MAAa,mBAAmB,yBAAkD;CAChF,MAAM;CACN,UAAU,SAAkC;AAC1C,UAAQ,UAA8B;GACpC,MAAM,KAAK;GACX,SAAS,KAAK;GACd,cAAc,KAAK;GACnB,GAAI,KAAK,uBAAuB,SAC5B,EAAE,oBAAoB,KAAK,oBAAoB,GAC/C,EAAE;GACN,OAAO,KAAK;AACV,WAAO,eAAe,MAAM,KAAK,KAAK;;GAExC,MAAM,SAAS,KAAK;IAClB,MAAM,SAAS,MAAM,KAAK,SAAS,IAAI;AACvC,cAAU,QAAQ,MAAM,MAAM,SAAS,IAAI,SAAS,CAAC;AACrD,WAAO;;GAET,GAAI,KAAK,cAAc,EAAE,aAAa,KAAK,YAAY,KAAK,KAAK,EAAE,GAAG,EAAE;GACzE;;CAEJ,CAAC;AAEF,gBAAgB,eACd,MACA,KACA,MAC8B;CAC9B,MAAM,WAAW,SAAS,IAAI,SAAS;AACvC,YAAW,MAAM,SAAS,KAAK,OAAO,IAAI,EAAE;AAC1C,QAAM;AACN,MAAI,MAAM,SAAS,SACjB,WAAU;GAAE,OAAO,MAAM;GAAO,cAAc,MAAM;GAAc,EAAE,MAAM,MAAM,SAAS;;;AAK/F,SAAS,SAAS,OAA+D;AAC/E,KAAI,UAAU,UAAa,UAAU,KAAM,QAAO;AAClD,QAAO;;AAGT,SAAS,UACP,QAGA,MACA,MACA,UACM;AACN,KAAI,KAAK,YAAY,OAAW;CAChC,MAAM,QAAQ,OAAO;CACrB,MAAM,QAAQ,KAAK,cAAc;EAAE,cAAc,KAAK;EAAM,SAAS,KAAK;EAAS,CAAC,IAAI;CACxF,MAAM,UACJ,UAAU,OACL,MAAM,gBAAgB,MAAM,gBAAgB,KAAM,MAClD,MAAM,oBAAoB,MAAM,iBAAiB,KAAM,MACvD,MAAM,MAAM,UAAU;AAC7B,MAAK,QAAQ;EACX,cAAc,KAAK;EACnB,SAAS,KAAK;EACd,cAAc,MAAM;EACpB,kBAAkB,MAAM;EACxB,aAAa,MAAM;EACnB;EACA;EACD,CAAC"}

package/dist/middleware/with-fallback.d.ts

@@ -0,0 +1,25 @@
+import * as _graphorin_core3 from "@graphorin/core";
+import { Provider } from "@graphorin/core";
+
+//#region src/middleware/with-fallback.d.ts
+
+/**
+ * Options for {@link withFallback}.
+ *
+ * @stable
+ */
+interface WithFallbackOptions {
+  /** Alternate providers tried in order. */
+  readonly fallbacks: ReadonlyArray<Provider>;
+  /** Predicate deciding whether an error should trigger a fallback. */
+  readonly shouldFallback?: (err: unknown) => boolean;
+  /** Optional log sink; defaults to `console.warn`. */
+  readonly logger?: (message: string, meta?: object) => void;
+}
+/**
+ * @stable
+ */
+declare const withFallback: (opts: WithFallbackOptions) => _graphorin_core3.ProviderMiddleware;
+//#endregion
+export { WithFallbackOptions, withFallback };
+//# sourceMappingURL=with-fallback.d.ts.map

package/dist/middleware/with-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-fallback.d.ts","names":[],"sources":["../../src/middleware/with-fallback.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;UAqBiB,mBAAA;;sBAEK,cAAc;;;;;;;;;cAUvB,qBAAY,wBAAA,gBAAA,CAAA"}

package/dist/middleware/with-fallback.js

@@ -0,0 +1,84 @@
+import { defineProviderMiddleware } from "./compose.js";
+import { isAbortError } from "../internal/abort.js";
+
+//#region src/middleware/with-fallback.ts
+/**
+* @stable
+*/
+const withFallback = defineProviderMiddleware({
+	kind: "withFallback",
+	factory: (opts) => {
+		const shouldFallback = opts.shouldFallback ?? defaultShouldFallback;
+		const logger = opts.logger ?? defaultLogger;
+		if (!Array.isArray(opts.fallbacks) || opts.fallbacks.length === 0) throw new TypeError("withFallback: fallbacks array must contain at least one Provider.");
+		return (next) => {
+			const candidates = [next, ...opts.fallbacks];
+			return {
+				name: next.name,
+				modelId: next.modelId,
+				capabilities: next.capabilities,
+				...next.acceptsSensitivity !== void 0 ? { acceptsSensitivity: next.acceptsSensitivity } : {},
+				stream(req) {
+					return fallbackStream(candidates, req, shouldFallback, logger);
+				},
+				async generate(req) {
+					let lastErr;
+					for (let i = 0; i < candidates.length; i++) {
+						const cand = candidates[i];
+						if (cand === void 0) continue;
+						try {
+							return await cand.generate(req);
+						} catch (err) {
+							if (req.signal?.aborted) throw err;
+							lastErr = err;
+							if (i === candidates.length - 1 || !shouldFallback(err)) throw err;
+							logger(`[graphorin/provider] withFallback: '${cand.name}' failed, trying next.`, { error: err.message });
+						}
+					}
+					throw lastErr ?? /* @__PURE__ */ new Error("withFallback: no fallback succeeded.");
+				},
+				...next.countTokens ? { countTokens: next.countTokens.bind(next) } : {}
+			};
+		};
+	}
+});
+async function* fallbackStream(candidates, req, shouldFallback, logger) {
+	let lastErr;
+	for (let i = 0; i < candidates.length; i++) {
+		const cand = candidates[i];
+		if (cand === void 0) continue;
+		let yieldedAny = false;
+		try {
+			for await (const event of cand.stream(req)) {
+				yieldedAny = true;
+				yield event;
+			}
+			return;
+		} catch (err) {
+			if (req.signal?.aborted) throw err;
+			lastErr = err;
+			if (yieldedAny) throw err;
+			if (i === candidates.length - 1 || !shouldFallback(err)) throw err;
+			logger(`[graphorin/provider] withFallback: '${cand.name}' failed, trying next.`, { error: err.message });
+		}
+	}
+	throw lastErr ?? /* @__PURE__ */ new Error("withFallback: no fallback succeeded.");
+}
+function defaultShouldFallback(err) {
+	if (err === null || typeof err !== "object") return false;
+	if (isAbortError(err)) return false;
+	const e = err;
+	if (e.kind === "unauthorized" || e.kind === "invalid-request") return false;
+	if (e.kind === "transient" || e.kind === "rate-limit" || e.kind === "capacity") return true;
+	if (typeof e.status === "number" && e.status >= 500) return true;
+	if (typeof e.status === "number" && e.status === 0) return true;
+	return false;
+}
+function defaultLogger(message, meta) {
+	if (meta !== void 0) console.warn(message, meta);
+	else console.warn(message);
+}
+
+//#endregion
+export { withFallback };
+//# sourceMappingURL=with-fallback.js.map

package/dist/middleware/with-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-fallback.js","names":["candidates: ReadonlyArray<Provider>","lastErr: unknown"],"sources":["../../src/middleware/with-fallback.ts"],"sourcesContent":["/**\n * `withFallback` — request-level fallback chain. When the wrapped\n * provider raises a fallback-eligible error, the middleware retries\n * the same request against each alternate provider in `fallbacks`.\n * The model concept is preserved: callers wire `[primary, alt1, alt2]`\n * pointing at providers serving the same logical model. Cross-model\n * fallbacks are the agent-level concern (Phase 12).\n *\n * @packageDocumentation\n */\n\nimport type { Provider, ProviderEvent, ProviderResponse } from '@graphorin/core';\n\nimport { isAbortError } from '../internal/abort.js';\nimport { defineProviderMiddleware } from './compose.js';\n\n/**\n * Options for {@link withFallback}.\n *\n * @stable\n */\nexport interface WithFallbackOptions {\n  /** Alternate providers tried in order. */\n  readonly fallbacks: ReadonlyArray<Provider>;\n  /** Predicate deciding whether an error should trigger a fallback. */\n  readonly shouldFallback?: (err: unknown) => boolean;\n  /** Optional log sink; defaults to `console.warn`. */\n  readonly logger?: (message: string, meta?: object) => void;\n}\n\n/**\n * @stable\n */\nexport const withFallback = defineProviderMiddleware<WithFallbackOptions>({\n  kind: 'withFallback',\n  factory: (opts: WithFallbackOptions) => {\n    const shouldFallback = opts.shouldFallback ?? defaultShouldFallback;\n    const logger = opts.logger ?? defaultLogger;\n    if (!Array.isArray(opts.fallbacks) || opts.fallbacks.length === 0) {\n      throw new TypeError('withFallback: fallbacks array must contain at least one Provider.');\n    }\n    return (next: Provider): Provider => {\n      const candidates: ReadonlyArray<Provider> = [next, ...opts.fallbacks];\n      return {\n        name: next.name,\n        modelId: next.modelId,\n        capabilities: next.capabilities,\n        ...(next.acceptsSensitivity !== undefined\n          ? { acceptsSensitivity: next.acceptsSensitivity }\n          : {}),\n        stream(req) {\n          return fallbackStream(candidates, req, shouldFallback, logger);\n        },\n        async generate(req) {\n          let lastErr: unknown;\n          for (let i = 0; i < candidates.length; i++) {\n            const cand = candidates[i];\n            if (cand === undefined) continue;\n            try {\n              return await cand.generate(req);\n            } catch (err) {\n              if (req.signal?.aborted) throw err;\n              lastErr = err;\n              if (i === candidates.length - 1 || !shouldFallback(err)) throw err;\n              logger(`[graphorin/provider] withFallback: '${cand.name}' failed, trying next.`, {\n                error: (err as Error).message,\n              });\n            }\n          }\n          throw lastErr ?? new Error('withFallback: no fallback succeeded.');\n        },\n        ...(next.countTokens ? { countTokens: next.countTokens.bind(next) } : {}),\n      };\n    };\n  },\n});\n\nasync function* fallbackStream(\n  candidates: ReadonlyArray<Provider>,\n  req: import('@graphorin/core').ProviderRequest,\n  shouldFallback: (err: unknown) => boolean,\n  logger: (message: string, meta?: object) => void,\n): AsyncIterable<ProviderEvent> {\n  let lastErr: unknown;\n  for (let i = 0; i < candidates.length; i++) {\n    const cand = candidates[i];\n    if (cand === undefined) continue;\n    let yieldedAny = false;\n    try {\n      for await (const event of cand.stream(req)) {\n        yieldedAny = true;\n        yield event;\n      }\n      return;\n    } catch (err) {\n      if (req.signal?.aborted) throw err;\n      lastErr = err;\n      if (yieldedAny) {\n        // Once we have streamed events, falling back would split the\n        // logical response across providers — propagate instead.\n        throw err;\n      }\n      if (i === candidates.length - 1 || !shouldFallback(err)) throw err;\n      logger(`[graphorin/provider] withFallback: '${cand.name}' failed, trying next.`, {\n        error: (err as Error).message,\n      });\n    }\n  }\n  throw lastErr ?? new Error('withFallback: no fallback succeeded.');\n}\n\nfunction defaultShouldFallback(err: unknown): boolean {\n  if (err === null || typeof err !== 'object') return false;\n  // An aborted request must not trigger a fallback, even as a `status: 0`\n  // network error (PS-2). The loop also short-circuits on `req.signal?.aborted`.\n  if (isAbortError(err)) return false;\n  const e = err as { kind?: string; status?: number };\n  if (e.kind === 'unauthorized' || e.kind === 'invalid-request') return false;\n  if (e.kind === 'transient' || e.kind === 'rate-limit' || e.kind === 'capacity') return true;\n  if (typeof e.status === 'number' && e.status >= 500) return true;\n  // PS-2: the headline fallback scenario — the primary provider is down\n  // (a local server refusing connections) surfaces as `status: 0`. Treat a\n  // network failure as fallback-eligible so the chain advances to the next\n  // provider (abort already excluded above).\n  if (typeof e.status === 'number' && e.status === 0) return true;\n  return false;\n}\n\nfunction defaultLogger(message: string, meta?: object): void {\n  if (meta !== undefined) console.warn(message, meta);\n  else console.warn(message);\n}\n\n// Cast to silence the \"declared but unused\" lint when only the types\n// are needed by consumers.\nexport type _FallbackResponseGuard = ProviderResponse;\n"],"mappings":";;;;;;;AAiCA,MAAa,eAAe,yBAA8C;CACxE,MAAM;CACN,UAAU,SAA8B;EACtC,MAAM,iBAAiB,KAAK,kBAAkB;EAC9C,MAAM,SAAS,KAAK,UAAU;AAC9B,MAAI,CAAC,MAAM,QAAQ,KAAK,UAAU,IAAI,KAAK,UAAU,WAAW,EAC9D,OAAM,IAAI,UAAU,oEAAoE;AAE1F,UAAQ,SAA6B;GACnC,MAAMA,aAAsC,CAAC,MAAM,GAAG,KAAK,UAAU;AACrE,UAAO;IACL,MAAM,KAAK;IACX,SAAS,KAAK;IACd,cAAc,KAAK;IACnB,GAAI,KAAK,uBAAuB,SAC5B,EAAE,oBAAoB,KAAK,oBAAoB,GAC/C,EAAE;IACN,OAAO,KAAK;AACV,YAAO,eAAe,YAAY,KAAK,gBAAgB,OAAO;;IAEhE,MAAM,SAAS,KAAK;KAClB,IAAIC;AACJ,UAAK,IAAI,IAAI,GAAG,IAAI,WAAW,QAAQ,KAAK;MAC1C,MAAM,OAAO,WAAW;AACxB,UAAI,SAAS,OAAW;AACxB,UAAI;AACF,cAAO,MAAM,KAAK,SAAS,IAAI;eACxB,KAAK;AACZ,WAAI,IAAI,QAAQ,QAAS,OAAM;AAC/B,iBAAU;AACV,WAAI,MAAM,WAAW,SAAS,KAAK,CAAC,eAAe,IAAI,CAAE,OAAM;AAC/D,cAAO,uCAAuC,KAAK,KAAK,yBAAyB,EAC/E,OAAQ,IAAc,SACvB,CAAC;;;AAGN,WAAM,2BAAW,IAAI,MAAM,uCAAuC;;IAEpE,GAAI,KAAK,cAAc,EAAE,aAAa,KAAK,YAAY,KAAK,KAAK,EAAE,GAAG,EAAE;IACzE;;;CAGN,CAAC;AAEF,gBAAgB,eACd,YACA,KACA,gBACA,QAC8B;CAC9B,IAAIA;AACJ,MAAK,IAAI,IAAI,GAAG,IAAI,WAAW,QAAQ,KAAK;EAC1C,MAAM,OAAO,WAAW;AACxB,MAAI,SAAS,OAAW;EACxB,IAAI,aAAa;AACjB,MAAI;AACF,cAAW,MAAM,SAAS,KAAK,OAAO,IAAI,EAAE;AAC1C,iBAAa;AACb,UAAM;;AAER;WACO,KAAK;AACZ,OAAI,IAAI,QAAQ,QAAS,OAAM;AAC/B,aAAU;AACV,OAAI,WAGF,OAAM;AAER,OAAI,MAAM,WAAW,SAAS,KAAK,CAAC,eAAe,IAAI,CAAE,OAAM;AAC/D,UAAO,uCAAuC,KAAK,KAAK,yBAAyB,EAC/E,OAAQ,IAAc,SACvB,CAAC;;;AAGN,OAAM,2BAAW,IAAI,MAAM,uCAAuC;;AAGpE,SAAS,sBAAsB,KAAuB;AACpD,KAAI,QAAQ,QAAQ,OAAO,QAAQ,SAAU,QAAO;AAGpD,KAAI,aAAa,IAAI,CAAE,QAAO;CAC9B,MAAM,IAAI;AACV,KAAI,EAAE,SAAS,kBAAkB,EAAE,SAAS,kBAAmB,QAAO;AACtE,KAAI,EAAE,SAAS,eAAe,EAAE,SAAS,gBAAgB,EAAE,SAAS,WAAY,QAAO;AACvF,KAAI,OAAO,EAAE,WAAW,YAAY,EAAE,UAAU,IAAK,QAAO;AAK5D,KAAI,OAAO,EAAE,WAAW,YAAY,EAAE,WAAW,EAAG,QAAO;AAC3D,QAAO;;AAGT,SAAS,cAAc,SAAiB,MAAqB;AAC3D,KAAI,SAAS,OAAW,SAAQ,KAAK,SAAS,KAAK;KAC9C,SAAQ,KAAK,QAAQ"}

package/dist/middleware/with-rate-limit.d.ts

@@ -0,0 +1,36 @@
+import * as _graphorin_core4 from "@graphorin/core";
+
+//#region src/middleware/with-rate-limit.d.ts
+
+/**
+ * `withRateLimit` — token-bucket rate limiter keyed per `provider × model`.
+ * Configurable mode: `'throw'` (default) raises
+ * {@link RateLimitExceededError} on overflow; `'queue'` waits for the
+ * next available slot.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Options for {@link withRateLimit}.
+ *
+ * @stable
+ */
+interface WithRateLimitOptions {
+  /** Allowed requests per minute. */
+  readonly requestsPerMinute: number;
+  /** Burst size — defaults to `requestsPerMinute / 4` (rounded up to >= 1). */
+  readonly burst?: number;
+  /** What to do on overflow. Default `'throw'`. */
+  readonly mode?: 'throw' | 'queue';
+  /** Test hook overriding `Date.now`. */
+  readonly nowImpl?: () => number;
+  /** Test hook overriding `setTimeout`-based wait. */
+  readonly sleepImpl?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * @stable
+ */
+declare const withRateLimit: (opts: WithRateLimitOptions) => _graphorin_core4.ProviderMiddleware;
+//#endregion
+export { WithRateLimitOptions, withRateLimit };
+//# sourceMappingURL=with-rate-limit.d.ts.map

package/dist/middleware/with-rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-rate-limit.d.ts","names":[],"sources":["../../src/middleware/with-rate-limit.ts"],"sourcesContent":[],"mappings":";;;;;;;AAmBA;AAgCA;;;;;;;;;UAhCiB,oBAAA;;;;;;;;;;6CAU4B,gBAAgB;;;;;cAsBhD,sBAAa,yBAAA,gBAAA,CAAA"}

package/dist/middleware/with-rate-limit.js

@@ -0,0 +1,141 @@
+import { RateLimitExceededError } from "../errors/errors.js";
+import { defineProviderMiddleware } from "./compose.js";
+
+//#region src/middleware/with-rate-limit.ts
+/**
+* @stable
+*/
+const withRateLimit = defineProviderMiddleware({
+	kind: "withRateLimit",
+	factory: (opts) => {
+		if (!(opts.requestsPerMinute > 0)) throw new RangeError("withRateLimit: requestsPerMinute must be > 0.");
+		const burst = Math.max(opts.burst ?? Math.ceil(opts.requestsPerMinute / 4), 1);
+		const refillPerMs = opts.requestsPerMinute / 6e4;
+		const mode = opts.mode ?? "throw";
+		const now = opts.nowImpl ?? (() => Date.now());
+		const sleep = opts.sleepImpl ?? defaultSleep;
+		const buckets = /* @__PURE__ */ new Map();
+		return (next) => {
+			const key = `${next.name}::${next.modelId}`;
+			const bucketFor = () => {
+				let bucket = buckets.get(key);
+				if (bucket === void 0) {
+					bucket = {
+						tokens: burst,
+						lastRefill: now(),
+						queue: [],
+						draining: false
+					};
+					buckets.set(key, bucket);
+				}
+				return bucket;
+			};
+			const refill = (bucket) => {
+				const ts = now();
+				bucket.tokens = Math.min(burst, bucket.tokens + (ts - bucket.lastRefill) * refillPerMs);
+				bucket.lastRefill = ts;
+			};
+			const drain = (bucket) => {
+				if (bucket.draining) return;
+				bucket.draining = true;
+				(async () => {
+					while (bucket.queue.length > 0) {
+						const head = bucket.queue[0];
+						if (head === void 0) break;
+						if (head.cancelled) {
+							bucket.queue.shift();
+							continue;
+						}
+						refill(bucket);
+						if (bucket.tokens >= 1) {
+							bucket.tokens -= 1;
+							bucket.queue.shift();
+							head.resolve();
+							continue;
+						}
+						const waitMs = Math.ceil((1 - bucket.tokens) / refillPerMs);
+						try {
+							await sleep(waitMs);
+						} catch {}
+					}
+					bucket.draining = false;
+				})();
+			};
+			const acquire = async (signal) => {
+				if (signal?.aborted === true) throw signal.reason ?? /* @__PURE__ */ new Error("aborted");
+				const bucket = bucketFor();
+				refill(bucket);
+				if (bucket.tokens >= 1 && bucket.queue.length === 0) {
+					bucket.tokens -= 1;
+					return;
+				}
+				if (mode === "throw") throw new RateLimitExceededError(Math.ceil((1 - bucket.tokens) / refillPerMs));
+				await new Promise((resolve, reject) => {
+					const waiter = {
+						resolve,
+						reject,
+						...signal ? { signal } : {},
+						cancelled: false
+					};
+					if (signal !== void 0) {
+						const onAbort = () => {
+							waiter.cancelled = true;
+							reject(signal.reason ?? /* @__PURE__ */ new Error("aborted"));
+						};
+						signal.addEventListener("abort", onAbort, { once: true });
+						const settle = resolve;
+						waiter.resolve = () => {
+							signal.removeEventListener("abort", onAbort);
+							settle();
+						};
+					}
+					bucket.queue.push(waiter);
+					drain(bucket);
+				});
+			};
+			return {
+				name: next.name,
+				modelId: next.modelId,
+				capabilities: next.capabilities,
+				...next.acceptsSensitivity !== void 0 ? { acceptsSensitivity: next.acceptsSensitivity } : {},
+				stream(req) {
+					return rateLimitedStream(next, req, acquire);
+				},
+				async generate(req) {
+					await acquire(req.signal);
+					return next.generate(req);
+				},
+				...next.countTokens ? { countTokens: next.countTokens.bind(next) } : {}
+			};
+		};
+	}
+});
+async function* rateLimitedStream(next, req, acquire) {
+	await acquire(req.signal);
+	for await (const event of next.stream(req)) yield event;
+}
+function defaultSleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason ?? /* @__PURE__ */ new Error("aborted"));
+			return;
+		}
+		const timer = setTimeout(() => {
+			cleanup();
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			cleanup();
+			reject(signal?.reason ?? /* @__PURE__ */ new Error("aborted"));
+		};
+		function cleanup() {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+		}
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+//#endregion
+export { withRateLimit };
+//# sourceMappingURL=with-rate-limit.js.map

package/dist/middleware/with-rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-rate-limit.js","names":["waiter: Waiter"],"sources":["../../src/middleware/with-rate-limit.ts"],"sourcesContent":["/**\n * `withRateLimit` — token-bucket rate limiter keyed per `provider × model`.\n * Configurable mode: `'throw'` (default) raises\n * {@link RateLimitExceededError} on overflow; `'queue'` waits for the\n * next available slot.\n *\n * @packageDocumentation\n */\n\nimport type { Provider } from '@graphorin/core';\n\nimport { RateLimitExceededError } from '../errors/errors.js';\nimport { defineProviderMiddleware } from './compose.js';\n\n/**\n * Options for {@link withRateLimit}.\n *\n * @stable\n */\nexport interface WithRateLimitOptions {\n  /** Allowed requests per minute. */\n  readonly requestsPerMinute: number;\n  /** Burst size — defaults to `requestsPerMinute / 4` (rounded up to >= 1). */\n  readonly burst?: number;\n  /** What to do on overflow. Default `'throw'`. */\n  readonly mode?: 'throw' | 'queue';\n  /** Test hook overriding `Date.now`. */\n  readonly nowImpl?: () => number;\n  /** Test hook overriding `setTimeout`-based wait. */\n  readonly sleepImpl?: (ms: number, signal?: AbortSignal) => Promise<void>;\n}\n\ninterface Waiter {\n  resolve: () => void;\n  reject: (err: unknown) => void;\n  signal?: AbortSignal;\n  cancelled: boolean;\n}\n\ninterface BucketState {\n  tokens: number;\n  lastRefill: number;\n  /** FIFO waiters in `'queue'` mode (PS-18). */\n  queue: Waiter[];\n  /** Whether the single drain loop for this bucket is running. */\n  draining: boolean;\n}\n\n/**\n * @stable\n */\nexport const withRateLimit = defineProviderMiddleware<WithRateLimitOptions>({\n  kind: 'withRateLimit',\n  factory: (opts: WithRateLimitOptions) => {\n    if (!(opts.requestsPerMinute > 0)) {\n      throw new RangeError('withRateLimit: requestsPerMinute must be > 0.');\n    }\n    const burst = Math.max(opts.burst ?? Math.ceil(opts.requestsPerMinute / 4), 1);\n    const refillPerMs = opts.requestsPerMinute / 60_000;\n    const mode = opts.mode ?? 'throw';\n    const now = opts.nowImpl ?? (() => Date.now());\n    const sleep = opts.sleepImpl ?? defaultSleep;\n    const buckets = new Map<string, BucketState>();\n    return (next: Provider): Provider => {\n      const key = `${next.name}::${next.modelId}`;\n      const bucketFor = (): BucketState => {\n        let bucket = buckets.get(key);\n        if (bucket === undefined) {\n          bucket = { tokens: burst, lastRefill: now(), queue: [], draining: false };\n          buckets.set(key, bucket);\n        }\n        return bucket;\n      };\n      const refill = (bucket: BucketState): void => {\n        const ts = now();\n        bucket.tokens = Math.min(burst, bucket.tokens + (ts - bucket.lastRefill) * refillPerMs);\n        bucket.lastRefill = ts;\n      };\n      // PS-18: a single drain loop per bucket grants queued waiters ONE token at\n      // a time, sleeping until the next token actually refills. Previously every\n      // concurrent waiter computed the same wait, slept once, and then all\n      // passed — letting N requests through on ~1 token (a burst). FIFO order is\n      // preserved and grants track the real refill schedule.\n      const drain = (bucket: BucketState): void => {\n        if (bucket.draining) return;\n        bucket.draining = true;\n        void (async () => {\n          while (bucket.queue.length > 0) {\n            const head = bucket.queue[0];\n            if (head === undefined) break;\n            if (head.cancelled) {\n              bucket.queue.shift();\n              continue;\n            }\n            refill(bucket);\n            if (bucket.tokens >= 1) {\n              bucket.tokens -= 1;\n              bucket.queue.shift();\n              head.resolve();\n              continue;\n            }\n            const waitMs = Math.ceil((1 - bucket.tokens) / refillPerMs);\n            try {\n              await sleep(waitMs);\n            } catch {\n              // The shared drain sleep carries no per-waiter signal; individual\n              // aborts are handled on the waiter via its listener.\n            }\n          }\n          bucket.draining = false;\n        })();\n      };\n      const acquire = async (signal?: AbortSignal): Promise<void> => {\n        if (signal?.aborted === true) throw signal.reason ?? new Error('aborted');\n        const bucket = bucketFor();\n        refill(bucket);\n        // Fast path: a token is free AND nobody is queued ahead (preserve FIFO).\n        if (bucket.tokens >= 1 && bucket.queue.length === 0) {\n          bucket.tokens -= 1;\n          return;\n        }\n        if (mode === 'throw') {\n          throw new RateLimitExceededError(Math.ceil((1 - bucket.tokens) / refillPerMs));\n        }\n        await new Promise<void>((resolve, reject) => {\n          const waiter: Waiter = {\n            resolve,\n            reject,\n            ...(signal ? { signal } : {}),\n            cancelled: false,\n          };\n          if (signal !== undefined) {\n            const onAbort = (): void => {\n              waiter.cancelled = true;\n              reject(signal.reason ?? new Error('aborted'));\n            };\n            signal.addEventListener('abort', onAbort, { once: true });\n            const settle = resolve;\n            waiter.resolve = (): void => {\n              signal.removeEventListener('abort', onAbort);\n              settle();\n            };\n          }\n          bucket.queue.push(waiter);\n          drain(bucket);\n        });\n      };\n      return {\n        name: next.name,\n        modelId: next.modelId,\n        capabilities: next.capabilities,\n        ...(next.acceptsSensitivity !== undefined\n          ? { acceptsSensitivity: next.acceptsSensitivity }\n          : {}),\n        stream(req) {\n          return rateLimitedStream(next, req, acquire);\n        },\n        async generate(req) {\n          await acquire(req.signal);\n          return next.generate(req);\n        },\n        ...(next.countTokens ? { countTokens: next.countTokens.bind(next) } : {}),\n      };\n    };\n  },\n});\n\nasync function* rateLimitedStream(\n  next: Provider,\n  req: import('@graphorin/core').ProviderRequest,\n  acquire: (signal?: AbortSignal) => Promise<void>,\n): AsyncIterable<import('@graphorin/core').ProviderEvent> {\n  await acquire(req.signal);\n  for await (const event of next.stream(req)) {\n    yield event;\n  }\n}\n\nfunction defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(signal.reason ?? new Error('aborted'));\n      return;\n    }\n    const timer = setTimeout(() => {\n      cleanup();\n      resolve();\n    }, ms);\n    const onAbort = () => {\n      cleanup();\n      reject(signal?.reason ?? new Error('aborted'));\n    };\n    function cleanup(): void {\n      clearTimeout(timer);\n      signal?.removeEventListener('abort', onAbort);\n    }\n    signal?.addEventListener('abort', onAbort, { once: true });\n  });\n}\n"],"mappings":"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"}

package/dist/middleware/with-redaction.d.ts

@@ -0,0 +1,60 @@
+import * as _graphorin_core5 from "@graphorin/core";
+import { LocalProviderTrust } from "@graphorin/core";
+import { RedactionPattern } from "@graphorin/observability/redaction/patterns";
+
+//#region src/middleware/with-redaction.d.ts
+
+/**
+ * Range of fields scanned by the middleware.
+ *
+ * @stable
+ */
+type PromptRedactionScanScope = 'all' | 'untrusted' | 'secret-value-only';
+/**
+ * Sanitized record handed to `onViolation`. Carries metadata only;
+ * never the matched value.
+ *
+ * @stable
+ */
+interface PromptRedactionViolation {
+  readonly patternName: string;
+  readonly fieldPath: string;
+  readonly role?: string;
+  readonly matchLength: number;
+  readonly trustClass?: LocalProviderTrust;
+  readonly action: 'redact' | 'throw' | 'block-and-prompt-user';
+}
+/**
+ * Full prompt-redaction policy.
+ *
+ * @stable
+ */
+interface PromptRedactionPolicy {
+  /** Pattern catalogue. Defaults to the 14 built-in patterns. */
+  readonly patterns?: ReadonlyArray<RedactionPattern>;
+  /** Action on detection. Defaults to `'redact'`. */
+  readonly action?: 'redact' | 'throw' | 'block-and-prompt-user';
+  /** Throw on the first hit instead of redacting in-place. */
+  readonly failClosed?: boolean;
+  /** Range of fields scanned. Defaults to `'all'`. */
+  readonly scanScope?: PromptRedactionScanScope;
+  /** Detect `SecretValue` instances anywhere in the request. */
+  readonly detectSecretValue?: boolean;
+  /** Strip Anthropic-shape `cache_control` markers on hit. */
+  readonly stripCacheControlOnHit?: boolean;
+  /** Per-trust-class override block. */
+  readonly byTrustClass?: Partial<Record<LocalProviderTrust, Partial<PromptRedactionPolicy>>>;
+  /** Sanitised violation hook (audit emission lives downstream). */
+  readonly onViolation?: (violation: PromptRedactionViolation) => void;
+  /** Optional logger override. Defaults to `console.warn`. */
+  readonly logger?: (message: string, meta?: object) => void;
+  /** Test hook — synthetic trust class. */
+  readonly trustClassOverride?: LocalProviderTrust;
+}
+/**
+ * @stable
+ */
+declare const withRedaction: (opts: PromptRedactionPolicy) => _graphorin_core5.ProviderMiddleware;
+//#endregion
+export { PromptRedactionPolicy, PromptRedactionScanScope, PromptRedactionViolation, withRedaction };
+//# sourceMappingURL=with-redaction.d.ts.map

package/dist/middleware/with-redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-redaction.d.ts","names":[],"sources":["../../src/middleware/with-redaction.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;KAmDY,wBAAA;;;;;;;UAQK,wBAAA;;;;;wBAKO;;;;;;;;UAqBP,qBAAA;;sBAEK,cAAc;;;;;;uBAMb;;;;;;0BAMG,QAAQ,OAAO,oBAAoB,QAAQ;;qCAEhC;;;;gCAIL;;;;;cAcnB,sBAAa,0BAAA,gBAAA,CAAA"}