@vercel/factory 0.0.14 → 0.0.16

package/dist/dispatch.mjs

@@ -0,0 +1,199 @@
+import { budgetMonthOf, canReserve, computeMonthSpendUsd } from "./budget.mjs";
+import { InvalidTransitionError } from "./schema/transitions.mjs";
+import { routeKey } from "./agent-routes.mjs";
+import { RecordNotFoundError, VersionConflictError } from "./store/driver.mjs";
+//#region src/dispatch.ts
+/**
+* The provider may have accepted the request, so the running attempt must remain available for
+* recovery with its original launch key. Catchers must not queue a replacement attempt blindly.
+*/
+var ExecutionLaunchPendingError = class extends Error {};
+/** Non-terminal dispatch refusal that identifies the gated Task and retryable reason. */
+var DispatchRefusedError = class extends Error {
+	/** Exact Task whose current dispatch attempt was refused. */
+	taskId;
+	/** Stable gate or race category suitable for branching and telemetry. */
+	code;
+	/** Human-readable refusal context; canonical Task state remains authoritative. */
+	reason;
+	constructor(taskId, code, reason) {
+		super(`dispatch of "${taskId}" refused: ${reason}`);
+		this.name = "DispatchRefusedError";
+		this.taskId = taskId;
+		this.code = code;
+		this.reason = reason;
+	}
+};
+/**
+* An exhausted budget is definitive, not a retryable refusal: the task has
+* already been failed and receipted when this throws, so it never re-enters
+* the sweep. Operator retry recovers it once budget frees up.
+*/
+var BudgetExhaustedError = class extends Error {
+	/** Exact Task already transitioned to `failed` by the exhausted admission. */
+	taskId;
+	/** UTC budget month whose limit refused the reservation. */
+	month;
+	/** Counted settled cost and live reservations observed for that month. */
+	spendUsd;
+	constructor(taskId, month, spendUsd) {
+		super(`dispatch of "${taskId}" refused: budget for ${month} is exhausted at $${spendUsd}`);
+		this.name = "BudgetExhaustedError";
+		this.taskId = taskId;
+		this.month = month;
+		this.spendUsd = spendUsd;
+	}
+};
+/** Default launch-attempt allowance covering delayed identity provisioning. */
+const DEFAULT_MAX_LAUNCH_ATTEMPTS = 45;
+/**
+* Claims one queued Task and starts its exact execution mode.
+*
+* @remarks
+* Dispatch first checks route, approval, dependency, and optional budget gates, then atomically
+* transitions the Task from `queued` to `running`. Only the winner invokes `launch`. A successful
+* provider dispatch returns only after its execution reference is stored; it does not mean the
+* Task completed. `workflowOwned: true` returns the claimed running Task without starting a
+* provider session.
+*
+* An ordinary launch failure is rethrown after a best-effort transition back to `queued`, or to
+* `failed` once `maxLaunchAttempts` is exhausted. `ExecutionLaunchPendingError` instead leaves the
+* attempt running because the provider may have accepted the request; recovery must inspect or
+* repeat the launch with the original idempotency key. Budget exhaustion fails and receipts the
+* Task before throwing `BudgetExhaustedError`. Since compensating transitions are best-effort,
+* callers handling any thrown launch error should reread canonical Task state before deciding
+* whether to schedule another attempt.
+*
+* @param stores - Task, graph, and receipt stores that own the dispatch gates.
+* @param input - Exact Task identity plus either a launcher or workflow-owned marker.
+* @returns The running Task, including its durably recorded execution when a launcher was used.
+* @throws `RecordNotFoundError` when the Task is absent.
+* @throws `DispatchRefusedError` when routing, approval, dependencies, or a budget-admission race refuses dispatch.
+* @throws `InvalidTransitionError` when the Task is no longer queued when this caller claims it.
+* @throws `BudgetExhaustedError` after the Task has been failed because no reservation fits.
+* @throws `ExecutionLaunchPendingError` when provider acceptance is ambiguous and requires recovery.
+* @see The shipped `docs/recipes/eve-agent.md` and `docs/recipes/retry-recovery.md` recipes.
+*
+* @example
+* ```ts
+* import {
+*   DispatchRefusedError,
+*   dispatchTask,
+*   type DispatchStores,
+* } from "@vercel/factory/execution";
+* import type { TaskId } from "@vercel/factory/tasks";
+* import { parseAgentRouteBinding } from "@vercel/factory/workflows";
+*
+* declare const stores: DispatchStores;
+* declare const taskId: TaskId;
+* const route = parseAgentRouteBinding({ id: "worker", version: 1 });
+*
+* try {
+*   await dispatchTask(stores, {
+*     taskId,
+*     route,
+*     launch: async () => ({ provider: "eve", sessionId: "ses_example" }),
+*   });
+* } catch (error) {
+*   if (error instanceof DispatchRefusedError) {
+*     // `error.code` identifies the gate; canonical Task state remains authoritative.
+*   } else {
+*     throw error;
+*   }
+* }
+* ```
+*/
+async function dispatchTask(stores, input) {
+	const { taskId } = input;
+	const options = input;
+	const task = await stores.tasks.get(taskId);
+	if (task === null) throw new RecordNotFoundError("tasks", taskId);
+	const route = task.work.route;
+	if (route !== void 0 && options.workflowOwned === true) throw new DispatchRefusedError(taskId, "route_mismatch", `agent route ${routeKey(route)} requires a launcher`);
+	if (route !== void 0 && (options.route?.id !== route.id || options.route?.version !== route.version)) throw new DispatchRefusedError(taskId, "route_mismatch", `launch requires exact agent route ${routeKey(route)}`);
+	if (task.approval === "required") throw new DispatchRefusedError(taskId, "awaiting_approval", "awaiting human approval");
+	if (task.approval === "denied") throw new DispatchRefusedError(taskId, "approval_denied", "approval was denied");
+	if (!await stores.graphs.dependenciesSatisfied({
+		rootTaskId: task.rootTaskId,
+		taskId: task.id
+	})) throw new DispatchRefusedError(taskId, "dependencies_unsatisfied", "graph dependencies must all be succeeded before dispatch");
+	let reservation;
+	if (options.budget !== void 0 && task.state === "queued") {
+		const budgetNow = (options.budget.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
+		const month = options.budget.month ?? budgetMonthOf(budgetNow);
+		const rows = (options.budget.enforce === false ? [] : options.budget.tasks ?? await stores.tasks.list()).map((row) => row.id === taskId ? {
+			...row,
+			reservedUsd: void 0
+		} : row);
+		const spendUsd = computeMonthSpendUsd(rows, month);
+		const { totalUsd, perTaskReservationUsd } = options.budget.limits;
+		if (options.budget.enforce !== false && !canReserve(spendUsd, options.budget.limits)) {
+			const reason = `budget exhausted: ${month} spend $${spendUsd} cannot fit a $${perTaskReservationUsd} reservation under $${totalUsd}`;
+			try {
+				await stores.tasks.transition(taskId, "failed", {
+					reason,
+					expectFrom: "queued"
+				});
+			} catch (error) {
+				if (error instanceof InvalidTransitionError || error instanceof VersionConflictError) throw new DispatchRefusedError(taskId, "dispatch_race", "another dispatcher took the task");
+				throw error;
+			}
+			await stores.receipts.append({
+				repositoryIds: task.repositoryIds,
+				taskId,
+				kind: task.kind,
+				state: "reservation_refused",
+				phase: "budget",
+				reason,
+				attempt: task.attempt,
+				dedupeKey: `task:${taskId}:reservation_refused:${task.attempt}`
+			}).catch(() => void 0);
+			throw new BudgetExhaustedError(taskId, month, spendUsd);
+		}
+		reservation = {
+			reservedUsd: perTaskReservationUsd,
+			reservedAt: budgetNow
+		};
+	}
+	const running = await stores.tasks.transition(taskId, "running", {
+		expectFrom: "queued",
+		expectAttempt: task.attempt,
+		...reservation === void 0 ? {} : { patch: {
+			reservedUsd: reservation.reservedUsd,
+			reservedAt: reservation.reservedAt
+		} },
+		...task.attempt > 1 ? { phase: options.continuationAttempt === task.attempt ? "workflow" : "retry" } : {}
+	});
+	if (options.workflowOwned === true) return running;
+	let execution;
+	try {
+		execution = await options.launch(running);
+	} catch (error) {
+		if (error instanceof ExecutionLaunchPendingError) throw error;
+		const reason = (error instanceof Error ? error.message : String(error)).slice(0, 500);
+		const limit = options.maxLaunchAttempts ?? 45;
+		if (running.attempt < limit) {
+			const retryReason = `launch failed (attempt ${running.attempt} of ${limit}), will retry: ${reason}`;
+			await stores.tasks.transition(taskId, "queued", {
+				reason: retryReason,
+				phase: "retry",
+				expectFrom: "running",
+				expectAttempt: running.attempt
+			}).catch(() => void 0);
+		} else await stores.tasks.transition(taskId, "failed", {
+			reason: `launch failed after ${running.attempt} attempts: ${reason}`,
+			phase: "retry",
+			expectFrom: "running",
+			expectAttempt: running.attempt
+		}).catch(() => void 0);
+		throw error;
+	}
+	return stores.tasks.recordExecution(taskId, {
+		execution,
+		expectAttempt: running.attempt
+	});
+}
+//#endregion
+export { BudgetExhaustedError, DEFAULT_MAX_LAUNCH_ATTEMPTS, DispatchRefusedError, ExecutionLaunchPendingError, dispatchTask };
+
+//# sourceMappingURL=dispatch.mjs.map

package/dist/dispatch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.mjs","names":[],"sources":["../src/dispatch.ts"],"sourcesContent":["import { budgetMonthOf, canReserve, computeMonthSpendUsd } from \"./budget\";\nimport type { AgentRouteBinding } from \"./agent-routes\";\nimport type { BudgetLimits, BudgetMonth } from \"./schema/budget\";\nimport type { DateClock } from \"./schema/common\";\nimport type { TaskId } from \"./schema/id\";\nimport type { ExecutionReference, Task } from \"./schema/task\";\nimport { routeKey } from \"./agent-routes\";\nimport { InvalidTransitionError } from \"./schema/transitions\";\nimport { RecordNotFoundError, VersionConflictError } from \"./store/driver\";\nimport type { FactoryStores } from \"./store/engine\";\n\n/** Minimal persistence capabilities required to gate and record one dispatch. */\nexport type DispatchStores = Pick<FactoryStores, \"graphs\" | \"receipts\" | \"tasks\">;\n\n/**\n * The provider may have accepted the request, so the running attempt must remain available for\n * recovery with its original launch key. Catchers must not queue a replacement attempt blindly.\n */\nexport class ExecutionLaunchPendingError extends Error {}\n\n/** Stable machine-readable reason a Task could not be dispatched. */\nexport type DispatchRefusalCode =\n  | \"route_mismatch\"\n  | \"awaiting_approval\"\n  | \"approval_denied\"\n  | \"dependencies_unsatisfied\"\n  | \"dispatch_race\";\n\n/** Non-terminal dispatch refusal that identifies the gated Task and retryable reason. */\nexport class DispatchRefusedError extends Error {\n  /** Exact Task whose current dispatch attempt was refused. */\n  readonly taskId: TaskId;\n  /** Stable gate or race category suitable for branching and telemetry. */\n  readonly code: DispatchRefusalCode;\n  /** Human-readable refusal context; canonical Task state remains authoritative. */\n  readonly reason: string;\n\n  constructor(taskId: TaskId, code: DispatchRefusalCode, reason: string) {\n    super(`dispatch of \"${taskId}\" refused: ${reason}`);\n    this.name = \"DispatchRefusedError\";\n    this.taskId = taskId;\n    this.code = code;\n    this.reason = reason;\n  }\n}\n\n/**\n * An exhausted budget is definitive, not a retryable refusal: the task has\n * already been failed and receipted when this throws, so it never re-enters\n * the sweep. Operator retry recovers it once budget frees up.\n */\nexport class BudgetExhaustedError extends Error {\n  /** Exact Task already transitioned to `failed` by the exhausted admission. */\n  readonly taskId: TaskId;\n  /** UTC budget month whose limit refused the reservation. */\n  readonly month: BudgetMonth;\n  /** Counted settled cost and live reservations observed for that month. */\n  readonly spendUsd: number;\n\n  constructor(taskId: TaskId, month: BudgetMonth, spendUsd: number) {\n    super(`dispatch of \"${taskId}\" refused: budget for ${month} is exhausted at $${spendUsd}`);\n    this.name = \"BudgetExhaustedError\";\n    this.taskId = taskId;\n    this.month = month;\n    this.spendUsd = spendUsd;\n  }\n}\n\n/** Factory-wide reservation limits and snapshot used to gate one dispatch. */\nexport interface DispatchBudget {\n  /** Factory-wide monthly ceiling and amount reserved for each admitted Task. */\n  limits: Pick<BudgetLimits, \"totalUsd\" | \"perTaskReservationUsd\">;\n  /** Defaults to true. False records reservations without enforcing the monthly ceiling. */\n  enforce?: boolean;\n  /** Defaults to the current UTC month. */\n  month?: BudgetMonth;\n  /** Clock used only to derive the reservation month and timestamp. Defaults to `new Date()`. */\n  now?: DateClock;\n  /** A dispatcher-wide snapshot used to calculate spend without another list. */\n  tasks?: readonly Task[];\n}\n\ninterface DispatchContext {\n  /** Exact workflow-confirmed continuation attempt; other replacement attempts count as retries. */\n  continuationAttempt?: number;\n  /**\n   * Maximum Task attempt number allowed for launch failure retries. Defaults to 45. A normal\n   * failure below the limit requeues the Task, which increments its attempt for the next sweep.\n   */\n  maxLaunchAttempts?: number;\n  /** Reserve-before-execution policy for this dispatch. */\n  budget?: DispatchBudget;\n}\n\n/** Exact provider launch or explicit workflow-owned execution for one Task dispatch. */\nexport type DispatchOptions = DispatchContext &\n  (\n    | {\n        /** Required exact binding when the Task declares an agent route. */\n        route?: AgentRouteBinding;\n        /**\n         * Starts the durable execution for the task (an Eve agent run). Runs after\n         * the task has won the queued -> running transition. Its provider reference\n         * is mandatory so recovery can always find an accepted run.\n         */\n        launch: (task: Task) => Promise<ExecutionReference>;\n        workflowOwned?: never;\n      }\n    | {\n        /**\n         * Marks route-less work whose workflow advances the running Task without a provider\n         * session. The caller must schedule that workflow after this admission returns.\n         */\n        workflowOwned: true;\n        route?: never;\n        launch?: never;\n      }\n  );\n\n/** Task identity and exact launch mode supplied to one dispatch attempt. */\nexport type DispatchTaskInput = { readonly taskId: TaskId } & DispatchOptions;\n\n// A fresh Vercel project rejects its own agents' sessions until its identity\n// finishes provisioning; at one sweep per minute the budget must outlast that.\n/** Default launch-attempt allowance covering delayed identity provisioning. */\nexport const DEFAULT_MAX_LAUNCH_ATTEMPTS = 45;\n\n/**\n * Claims one queued Task and starts its exact execution mode.\n *\n * @remarks\n * Dispatch first checks route, approval, dependency, and optional budget gates, then atomically\n * transitions the Task from `queued` to `running`. Only the winner invokes `launch`. A successful\n * provider dispatch returns only after its execution reference is stored; it does not mean the\n * Task completed. `workflowOwned: true` returns the claimed running Task without starting a\n * provider session.\n *\n * An ordinary launch failure is rethrown after a best-effort transition back to `queued`, or to\n * `failed` once `maxLaunchAttempts` is exhausted. `ExecutionLaunchPendingError` instead leaves the\n * attempt running because the provider may have accepted the request; recovery must inspect or\n * repeat the launch with the original idempotency key. Budget exhaustion fails and receipts the\n * Task before throwing `BudgetExhaustedError`. Since compensating transitions are best-effort,\n * callers handling any thrown launch error should reread canonical Task state before deciding\n * whether to schedule another attempt.\n *\n * @param stores - Task, graph, and receipt stores that own the dispatch gates.\n * @param input - Exact Task identity plus either a launcher or workflow-owned marker.\n * @returns The running Task, including its durably recorded execution when a launcher was used.\n * @throws `RecordNotFoundError` when the Task is absent.\n * @throws `DispatchRefusedError` when routing, approval, dependencies, or a budget-admission race refuses dispatch.\n * @throws `InvalidTransitionError` when the Task is no longer queued when this caller claims it.\n * @throws `BudgetExhaustedError` after the Task has been failed because no reservation fits.\n * @throws `ExecutionLaunchPendingError` when provider acceptance is ambiguous and requires recovery.\n * @see The shipped `docs/recipes/eve-agent.md` and `docs/recipes/retry-recovery.md` recipes.\n *\n * @example\n * ```ts\n * import {\n *   DispatchRefusedError,\n *   dispatchTask,\n *   type DispatchStores,\n * } from \"@vercel/factory/execution\";\n * import type { TaskId } from \"@vercel/factory/tasks\";\n * import { parseAgentRouteBinding } from \"@vercel/factory/workflows\";\n *\n * declare const stores: DispatchStores;\n * declare const taskId: TaskId;\n * const route = parseAgentRouteBinding({ id: \"worker\", version: 1 });\n *\n * try {\n *   await dispatchTask(stores, {\n *     taskId,\n *     route,\n *     launch: async () => ({ provider: \"eve\", sessionId: \"ses_example\" }),\n *   });\n * } catch (error) {\n *   if (error instanceof DispatchRefusedError) {\n *     // `error.code` identifies the gate; canonical Task state remains authoritative.\n *   } else {\n *     throw error;\n *   }\n * }\n * ```\n */\nexport async function dispatchTask(\n  stores: DispatchStores,\n  input: DispatchTaskInput,\n): Promise<Task> {\n  const { taskId } = input;\n  const options: DispatchOptions = input;\n  const task = await stores.tasks.get(taskId);\n  if (task === null) {\n    throw new RecordNotFoundError(\"tasks\", taskId);\n  }\n  const route = task.work.route;\n  if (route !== undefined && options.workflowOwned === true) {\n    throw new DispatchRefusedError(\n      taskId,\n      \"route_mismatch\",\n      `agent route ${routeKey(route)} requires a launcher`,\n    );\n  }\n  if (\n    route !== undefined &&\n    (options.route?.id !== route.id || options.route?.version !== route.version)\n  ) {\n    throw new DispatchRefusedError(\n      taskId,\n      \"route_mismatch\",\n      `launch requires exact agent route ${routeKey(route)}`,\n    );\n  }\n  if (task.approval === \"required\") {\n    throw new DispatchRefusedError(taskId, \"awaiting_approval\", \"awaiting human approval\");\n  }\n  if (task.approval === \"denied\") {\n    throw new DispatchRefusedError(taskId, \"approval_denied\", \"approval was denied\");\n  }\n  if (\n    !(await stores.graphs.dependenciesSatisfied({\n      rootTaskId: task.rootTaskId,\n      taskId: task.id,\n    }))\n  ) {\n    throw new DispatchRefusedError(\n      taskId,\n      \"dependencies_unsatisfied\",\n      \"graph dependencies must all be succeeded before dispatch\",\n    );\n  }\n\n  // The reservation gates queued -> running only; any other state falls\n  // through to the transition below, which rejects it as invalid.\n  let reservation: { reservedUsd: number; reservedAt: string } | undefined;\n  if (options.budget !== undefined && task.state === \"queued\") {\n    const budgetNow = (options.budget.now ?? (() => new Date()))().toISOString();\n    const month = options.budget.month ?? budgetMonthOf(budgetNow);\n    // This task's own retained reservation from a prior attempt is excluded,\n    // because re-reserving overwrites it. Its settled cost stays counted:\n    // that money was actually spent and a retry must not reopen it.\n    const rows = (\n      options.budget.enforce === false ? [] : (options.budget.tasks ?? (await stores.tasks.list()))\n    ).map((row) => (row.id === taskId ? { ...row, reservedUsd: undefined } : row));\n    const spendUsd = computeMonthSpendUsd(rows, month);\n    const { totalUsd, perTaskReservationUsd } = options.budget.limits;\n    if (options.budget.enforce !== false && !canReserve(spendUsd, options.budget.limits)) {\n      const reason = `budget exhausted: ${month} spend $${spendUsd} cannot fit a $${perTaskReservationUsd} reservation under $${totalUsd}`;\n      // Fail first, so BudgetExhaustedError's contract (task already failed)\n      // holds; losing the task to a concurrent dispatcher surfaces as a\n      // refusal, never as a false exhaustion with a misleading receipt.\n      try {\n        await stores.tasks.transition(taskId, \"failed\", { reason, expectFrom: \"queued\" });\n      } catch (error) {\n        if (error instanceof InvalidTransitionError || error instanceof VersionConflictError) {\n          throw new DispatchRefusedError(\n            taskId,\n            \"dispatch_race\",\n            \"another dispatcher took the task\",\n          );\n        }\n        throw error;\n      }\n      // Best-effort: the failed transition above already wrote its own\n      // receipt carrying this reason, so losing this supplementary one\n      // cannot lose the evidence.\n      await stores.receipts\n        .append({\n          repositoryIds: task.repositoryIds,\n          taskId,\n          kind: task.kind,\n          state: \"reservation_refused\",\n          phase: \"budget\",\n          reason,\n          attempt: task.attempt,\n          dedupeKey: `task:${taskId}:reservation_refused:${task.attempt}`,\n        })\n        .catch(() => undefined);\n      throw new BudgetExhaustedError(taskId, month, spendUsd);\n    }\n    reservation = { reservedUsd: perTaskReservationUsd, reservedAt: budgetNow };\n  }\n\n  const running = await stores.tasks.transition(taskId, \"running\", {\n    expectFrom: \"queued\",\n    expectAttempt: task.attempt,\n    ...(reservation === undefined\n      ? {}\n      : {\n          patch: {\n            reservedUsd: reservation.reservedUsd,\n            reservedAt: reservation.reservedAt,\n          },\n        }),\n    ...(task.attempt > 1\n      ? { phase: options.continuationAttempt === task.attempt ? \"workflow\" : \"retry\" }\n      : {}),\n  });\n  if (options.workflowOwned === true) return running;\n  let execution: ExecutionReference;\n  try {\n    execution = await options.launch(running);\n  } catch (error) {\n    if (error instanceof ExecutionLaunchPendingError) throw error;\n    const reason = (error instanceof Error ? error.message : String(error)).slice(0, 500);\n    const limit = options.maxLaunchAttempts ?? DEFAULT_MAX_LAUNCH_ATTEMPTS;\n    if (running.attempt < limit) {\n      const retryReason = `launch failed (attempt ${running.attempt} of ${limit}), will retry: ${reason}`;\n      await stores.tasks\n        .transition(taskId, \"queued\", {\n          reason: retryReason,\n          phase: \"retry\",\n          expectFrom: \"running\",\n          expectAttempt: running.attempt,\n        })\n        .catch(() => undefined);\n    } else {\n      await stores.tasks\n        .transition(taskId, \"failed\", {\n          reason: `launch failed after ${running.attempt} attempts: ${reason}`,\n          phase: \"retry\",\n          expectFrom: \"running\",\n          expectAttempt: running.attempt,\n        })\n        .catch(() => undefined);\n    }\n    throw error;\n  }\n  // Surface a failed binding so a durable caller can recover the same launch;\n  // never report acceptance with an unrecorded or stale execution.\n  return stores.tasks.recordExecution(taskId, {\n    execution,\n    expectAttempt: running.attempt,\n  });\n}\n"],"mappings":"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"}

package/dist/errors.d.mts

@@ -0,0 +1,15 @@
+//#region src/errors.d.ts
+/** Returns an error message with supplied secrets and recognized credentials removed. */
+declare function redactedErrorMessage(error: unknown, secrets?: readonly (string | undefined)[], fallback?: string): string;
+/** Bounded, recursively redacted diagnostic details safe for structured reporting. */
+interface RedactedErrorDetails {
+  name: string;
+  message: string;
+  stack?: string;
+  cause?: RedactedErrorDetails;
+}
+/** Builds bounded, recursively redacted diagnostic details from an unknown error. */
+declare function redactedErrorDetails(error: unknown, secrets?: readonly (string | undefined)[]): RedactedErrorDetails;
+//#endregion
+export { RedactedErrorDetails, redactedErrorDetails, redactedErrorMessage };
+//# sourceMappingURL=errors.d.mts.map

package/dist/errors.mjs

@@ -0,0 +1,38 @@
+//#region src/errors.ts
+const credentialPatterns = [
+	/github_pat_[A-Za-z0-9_]+/gu,
+	/gh[psoru]_[A-Za-z0-9_]+/gu,
+	/xox[baprs]-[A-Za-z0-9-]+/gu,
+	/Basic [A-Za-z0-9+/=]+/gu,
+	/Bearer [A-Za-z0-9._~+/-]+=*/giu,
+	/vercel_blob_rw_[A-Za-z0-9_]+/gu
+];
+function errorMessage(error, fallback) {
+	return error instanceof Error ? error.message : fallback ?? String(error);
+}
+/** Returns an error message with supplied secrets and recognized credentials removed. */
+function redactedErrorMessage(error, secrets = [], fallback) {
+	let message = errorMessage(error, fallback);
+	for (const secret of secrets) {
+		const value = secret?.trim();
+		if (value) message = message.replaceAll(value, "[REDACTED]");
+	}
+	for (const pattern of credentialPatterns) message = message.replace(pattern, (match) => match.startsWith("Basic ") ? "Basic [REDACTED]" : "[REDACTED]");
+	return message;
+}
+/** Builds bounded, recursively redacted diagnostic details from an unknown error. */
+function redactedErrorDetails(error, secrets = []) {
+	return nestedRedactedErrorDetails(error, secrets, 0);
+}
+function nestedRedactedErrorDetails(error, secrets, depth) {
+	return {
+		name: error instanceof Error ? error.name : "UnknownError",
+		message: redactedErrorMessage(error, secrets, "Unknown error").slice(0, 2e3),
+		...error instanceof Error && error.stack ? { stack: redactedErrorMessage(error.stack, secrets).slice(0, 8e3) } : {},
+		...error instanceof Error && error.cause !== void 0 && depth < 2 ? { cause: nestedRedactedErrorDetails(error.cause, secrets, depth + 1) } : {}
+	};
+}
+//#endregion
+export { redactedErrorDetails, redactedErrorMessage };
+
+//# sourceMappingURL=errors.mjs.map

package/dist/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["const credentialPatterns = [\n  /github_pat_[A-Za-z0-9_]+/gu,\n  /gh[psoru]_[A-Za-z0-9_]+/gu,\n  /xox[baprs]-[A-Za-z0-9-]+/gu,\n  /Basic [A-Za-z0-9+/=]+/gu,\n  /Bearer [A-Za-z0-9._~+/-]+=*/giu,\n  /vercel_blob_rw_[A-Za-z0-9_]+/gu,\n] as const;\n\nfunction errorMessage(error: unknown, fallback?: string): string {\n  return error instanceof Error ? error.message : (fallback ?? String(error));\n}\n\n/** Returns an error message with supplied secrets and recognized credentials removed. */\nexport function redactedErrorMessage(\n  error: unknown,\n  secrets: readonly (string | undefined)[] = [],\n  fallback?: string,\n): string {\n  let message = errorMessage(error, fallback);\n  for (const secret of secrets) {\n    const value = secret?.trim();\n    if (value) message = message.replaceAll(value, \"[REDACTED]\");\n  }\n  for (const pattern of credentialPatterns) {\n    message = message.replace(pattern, (match) =>\n      match.startsWith(\"Basic \") ? \"Basic [REDACTED]\" : \"[REDACTED]\",\n    );\n  }\n  return message;\n}\n\n/** Bounded, recursively redacted diagnostic details safe for structured reporting. */\nexport interface RedactedErrorDetails {\n  name: string;\n  message: string;\n  stack?: string;\n  cause?: RedactedErrorDetails;\n}\n\n/** Builds bounded, recursively redacted diagnostic details from an unknown error. */\nexport function redactedErrorDetails(\n  error: unknown,\n  secrets: readonly (string | undefined)[] = [],\n): RedactedErrorDetails {\n  return nestedRedactedErrorDetails(error, secrets, 0);\n}\n\nfunction nestedRedactedErrorDetails(\n  error: unknown,\n  secrets: readonly (string | undefined)[],\n  depth: number,\n): RedactedErrorDetails {\n  return {\n    name: error instanceof Error ? error.name : \"UnknownError\",\n    message: redactedErrorMessage(error, secrets, \"Unknown error\").slice(0, 2000),\n    ...(error instanceof Error && error.stack\n      ? { stack: redactedErrorMessage(error.stack, secrets).slice(0, 8000) }\n      : {}),\n    ...(error instanceof Error && error.cause !== undefined && depth < 2\n      ? { cause: nestedRedactedErrorDetails(error.cause, secrets, depth + 1) }\n      : {}),\n  };\n}\n"],"mappings":";AAAA,MAAM,qBAAqB;CACzB;CACA;CACA;CACA;CACA;CACA;AACF;AAEA,SAAS,aAAa,OAAgB,UAA2B;CAC/D,OAAO,iBAAiB,QAAQ,MAAM,UAAW,YAAY,OAAO,KAAK;AAC3E;;AAGA,SAAgB,qBACd,OACA,UAA2C,CAAC,GAC5C,UACQ;CACR,IAAI,UAAU,aAAa,OAAO,QAAQ;CAC1C,KAAK,MAAM,UAAU,SAAS;EAC5B,MAAM,QAAQ,QAAQ,KAAK;EAC3B,IAAI,OAAO,UAAU,QAAQ,WAAW,OAAO,YAAY;CAC7D;CACA,KAAK,MAAM,WAAW,oBACpB,UAAU,QAAQ,QAAQ,UAAU,UAClC,MAAM,WAAW,QAAQ,IAAI,qBAAqB,YACpD;CAEF,OAAO;AACT;;AAWA,SAAgB,qBACd,OACA,UAA2C,CAAC,GACtB;CACtB,OAAO,2BAA2B,OAAO,SAAS,CAAC;AACrD;AAEA,SAAS,2BACP,OACA,SACA,OACsB;CACtB,OAAO;EACL,MAAM,iBAAiB,QAAQ,MAAM,OAAO;EAC5C,SAAS,qBAAqB,OAAO,SAAS,eAAe,CAAC,CAAC,MAAM,GAAG,GAAI;EAC5E,GAAI,iBAAiB,SAAS,MAAM,QAChC,EAAE,OAAO,qBAAqB,MAAM,OAAO,OAAO,CAAC,CAAC,MAAM,GAAG,GAAI,EAAE,IACnE,CAAC;EACL,GAAI,iBAAiB,SAAS,MAAM,UAAU,KAAA,KAAa,QAAQ,IAC/D,EAAE,OAAO,2BAA2B,MAAM,OAAO,SAAS,QAAQ,CAAC,EAAE,IACrE,CAAC;CACP;AACF"}