@oxygen-agent/cli 1.287.12 → 1.310.0

package/dist/knowledge-mirror.d.ts

@@ -53,6 +53,16 @@ export declare function mirrorConflictsDir(dir: string): string;
 export declare function pageFilePath(dir: string, slug: string): string;
 /** Cheap "does a mirror exist here" check for post-write staleness hooks. */
 export declare function mirrorExists(dir: string): boolean;
+/**
+ * Enumerate the locally mirrored org ids for one API host — the immediate
+ * subdirectory names under `<configDir>/knowledge/<apiHost>/`. Offline (a plain
+ * directory read); tolerant of a missing host directory (returns `[]`). Backs
+ * `knowledge status --all`, which reads each org's `MirrorState` in turn.
+ */
+export declare function listLocalMirrors(input: {
+    configDir: string;
+    apiHost: string;
+}): string[];
 export declare function emptyMirrorState(input: {
     apiHost: string;
     orgId: string;

package/dist/knowledge-mirror.js

@@ -58,6 +58,24 @@ export function pageFilePath(dir, slug) {
 export function mirrorExists(dir) {
     return existsSync(mirrorManifestPath(dir));
 }
+/**
+ * Enumerate the locally mirrored org ids for one API host — the immediate
+ * subdirectory names under `<configDir>/knowledge/<apiHost>/`. Offline (a plain
+ * directory read); tolerant of a missing host directory (returns `[]`). Backs
+ * `knowledge status --all`, which reads each org's `MirrorState` in turn.
+ */
+export function listLocalMirrors(input) {
+    const hostDir = join(input.configDir, "knowledge", safePathSegment(input.apiHost, "API host"));
+    try {
+        return readdirSync(hostDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort((a, b) => a.localeCompare(b));
+    }
+    catch {
+        return [];
+    }
+}
 function safePathSegment(value, label) {
     const cleaned = value.trim().toLowerCase().replace(/[^a-z0-9._-]/g, "_");
     if (!cleaned || /^\.+$/.test(cleaned)) {

package/dist/run-wait.js

@@ -1,4 +1,5 @@
-import { OxygenError } from "@oxygen/shared";
+import { OxygenError, sleep } from "@oxygen/shared";
+import { readPositiveInt, readRecordString } from "./cli-values.js";
 export async function waitForCliRun(config) {
     const timeoutSeconds = readPositiveInt(config.requestedTimeoutSeconds)
         ?? config.defaultTimeoutSeconds;
@@ -30,28 +31,3 @@ export async function waitForCliRun(config) {
         await sleep(Math.min(intervalSeconds * 1000, remainingMs));
     }
 }
-// Local copies of index.ts's tiny readers keep this helper free of an
-// index.ts <-> run-wait.ts import cycle (the MCP run-wait.ts module likewise
-// defines its own sleep rather than importing from a tool file).
-function readPositiveInt(value) {
-    const trimmed = value?.trim();
-    if (!trimmed)
-        return undefined;
-    const parsed = Number(trimmed);
-    if (!Number.isInteger(parsed) || parsed < 1) {
-        throw new OxygenError("invalid_number", "Expected a positive integer.", {
-            details: { value },
-            exitCode: 1,
-        });
-    }
-    return parsed;
-}
-function readRecordString(value, key) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return null;
-    const entry = value[key];
-    return typeof entry === "string" ? entry : null;
-}
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/dist/runtime.d.ts

@@ -1,8 +1,48 @@
 declare const DEV_CLI_BINARY = "oxygen-dev";
 declare const PROD_CLI_BINARY = "oxygen";
+/**
+ * Pins a terminal to a *host*, not to a profile label.
+ *
+ * `OXYGEN_PROFILE=default` was the guard prescribed after the last profile drift
+ * (OXY-4081), and it cannot work: `default` is a name, and `login` writes an
+ * `apiUrl` into whatever name is active — so the profile called `default` became
+ * dev and the pin followed it there (OXY-4109). Every credit balance, ticket, and
+ * whoami then came back from dev looking exactly like a healthy production answer.
+ *
+ * The invariant that a staff runbook actually needs is the host it dialed. Set
+ * `OXYGEN_REQUIRE_API_URL=https://oxygen-agent.com` and any command that resolves
+ * somewhere else refuses to run instead of quietly answering from the wrong
+ * environment.
+ */
+export declare const REQUIRED_API_URL_ENV = "OXYGEN_REQUIRE_API_URL";
+export type CliBinaryName = typeof DEV_CLI_BINARY | typeof PROD_CLI_BINARY;
+/**
+ * Where a command actually sent its request, and what put it there.
+ *
+ * Every number in `cli_update_required: client 1.287.12, server 1.302.36,
+ * minimum_cli_version 1.298.0` is equally true of dev and of prod, so an error
+ * that omits the host is unreadable: a drifted profile made a prod-labelled
+ * binary report dev's floor, and the only available reading was "the shipped CLI
+ * is locked out of production" — a P0 that did not exist (OXY-4091). The host and
+ * the profile are in scope wherever we reject; they now travel with the rejection.
+ */
+export type CliEndpoint = {
+    apiUrl: string | undefined;
+    /** Active credential profile, when one resolved it. */
+    profile?: string | null;
+    /** What put `apiUrl` in force. The fault differs, so the remedy differs. */
+    apiUrlSource?: "env" | "profile" | "default";
+};
 export type CliUpdateGuidance = {
-    binaryName: typeof DEV_CLI_BINARY | typeof PROD_CLI_BINARY;
-    channel: "dev" | "npm";
+    binaryName: CliBinaryName;
+    /**
+     * dev     — the `oxygen-dev` binary: rebuild it from the dev branch.
+     * profile — the npm `oxygen` binary aimed at a non-production API. The endpoint
+     *           is the fault, not the binary: no CLI update can fix it, because npm
+     *           only ever serves the version a non-prod floor is already rejecting.
+     * npm     — the npm `oxygen` binary against production: `oxygen update`.
+     */
+    channel: "dev" | "profile" | "npm";
     warningInstruction: string;
     failureInstruction: string;
     details: {
@@ -10,7 +50,26 @@ export type CliUpdateGuidance = {
         cli_update_instruction?: string;
     };
 };
-export declare function resolveCliBinaryName(env?: NodeJS.ProcessEnv, argv?: readonly string[]): typeof DEV_CLI_BINARY | typeof PROD_CLI_BINARY;
-export declare function resolveCliUpdateGuidance(apiUrl: string | undefined, env?: NodeJS.ProcessEnv, argv?: readonly string[]): CliUpdateGuidance;
+export declare function resolveCliBinaryName(env?: NodeJS.ProcessEnv, argv?: readonly string[]): CliBinaryName;
+export declare function resolveCliUpdateGuidance(endpoint: CliEndpoint, env?: NodeJS.ProcessEnv, argv?: readonly string[]): CliUpdateGuidance;
+/** Human-readable "which host, on whose behalf" — e.g. `https://dev.oxygen-agent.com (profile: dev)`. */
+export declare function describeCliEndpoint(endpoint: CliEndpoint): string;
+/** The same facts, machine-readable, for `error.details`. */
+export declare function cliEndpointDetails(endpoint: CliEndpoint): Record<string, string>;
 export declare function isProdApiUrl(apiUrl: string): boolean;
+/**
+ * Do two API URLs address the same deployment? Compared on origin, so a trailing
+ * slash or a path suffix cannot make prod and dev look like different hosts — or
+ * the same one.
+ */
+export declare function sameApiOrigin(a: string, b: string): boolean;
+/**
+ * Refuse the command when the resolved host is not the one the caller pinned.
+ *
+ * Called from the one place every request funnels through, so a pin covers reads
+ * and writes alike: the failure mode this exists for is a *read* that looks right
+ * (dev's credit balance answering a question about a production customer), not
+ * only a write landing in the wrong environment.
+ */
+export declare function assertResolvedApiUrl(endpoint: CliEndpoint, env?: NodeJS.ProcessEnv): void;
 export {};

package/dist/runtime.js

@@ -1,7 +1,23 @@
 import { basename } from "node:path";
+import { OxygenError } from "@oxygen/shared";
 const PROD_API_HOSTNAME = "oxygen-agent.com";
 const DEV_CLI_BINARY = "oxygen-dev";
 const PROD_CLI_BINARY = "oxygen";
+/**
+ * Pins a terminal to a *host*, not to a profile label.
+ *
+ * `OXYGEN_PROFILE=default` was the guard prescribed after the last profile drift
+ * (OXY-4081), and it cannot work: `default` is a name, and `login` writes an
+ * `apiUrl` into whatever name is active — so the profile called `default` became
+ * dev and the pin followed it there (OXY-4109). Every credit balance, ticket, and
+ * whoami then came back from dev looking exactly like a healthy production answer.
+ *
+ * The invariant that a staff runbook actually needs is the host it dialed. Set
+ * `OXYGEN_REQUIRE_API_URL=https://oxygen-agent.com` and any command that resolves
+ * somewhere else refuses to run instead of quietly answering from the wrong
+ * environment.
+ */
+export const REQUIRED_API_URL_ENV = "OXYGEN_REQUIRE_API_URL";
 export function resolveCliBinaryName(env = process.env, argv = process.argv) {
     const explicit = normalizeBinaryName(env.OXYGEN_CLI_BINARY ?? env.OXYGEN_CLI_NAME);
     if (explicit)
@@ -11,10 +27,9 @@ export function resolveCliBinaryName(env = process.env, argv = process.argv) {
         return invoked;
     return PROD_CLI_BINARY;
 }
-export function resolveCliUpdateGuidance(apiUrl, env = process.env, argv = process.argv) {
+export function resolveCliUpdateGuidance(endpoint, env = process.env, argv = process.argv) {
     const binaryName = resolveCliBinaryName(env, argv);
-    const devLike = binaryName === DEV_CLI_BINARY || (apiUrl ? !isProdApiUrl(apiUrl) : false);
-    if (devLike) {
+    if (binaryName === DEV_CLI_BINARY) {
         return {
             binaryName,
             channel: "dev",
@@ -25,6 +40,20 @@ export function resolveCliUpdateGuidance(apiUrl, env = process.env, argv = proce
             },
         };
     }
+    // The production binary talking to a non-production API. `oxygen update` is a
+    // dead end here — it reinstalls the same npm version the non-prod floor just
+    // rejected — so the guidance names the endpoint, and no update command is
+    // offered at all.
+    if (endpoint.apiUrl && !isProdApiUrl(endpoint.apiUrl)) {
+        const instruction = profileFaultInstruction(endpoint);
+        return {
+            binaryName,
+            channel: "profile",
+            warningInstruction: instruction,
+            failureInstruction: instruction,
+            details: { cli_update_instruction: instruction },
+        };
+    }
     return {
         binaryName,
         channel: "npm",
@@ -35,6 +64,43 @@ export function resolveCliUpdateGuidance(apiUrl, env = process.env, argv = proce
         },
     };
 }
+function profileFaultInstruction(endpoint) {
+    if (endpoint.apiUrlSource === "env") {
+        return "`OXYGEN_API_URL` is pointing this `oxygen` binary at a non-production API — unset it to reach "
+            + "production, or use the `oxygen-dev` binary against a dev API.";
+    }
+    const profile = endpoint.profile?.trim();
+    if (profile) {
+        return `Profile \`${profile}\` is pointing this \`oxygen\` binary at a non-production API — run `
+            + "`oxygen profiles list`, then `oxygen profiles use <profile>` to switch back to production.";
+    }
+    return "This `oxygen` binary is pointed at a non-production API — run `oxygen profiles list` to see the "
+        + "active profile, then `oxygen profiles use <profile>` to switch back to production.";
+}
+/** Human-readable "which host, on whose behalf" — e.g. `https://dev.oxygen-agent.com (profile: dev)`. */
+export function describeCliEndpoint(endpoint) {
+    if (!endpoint.apiUrl)
+        return "";
+    const qualifiers = [];
+    const profile = endpoint.profile?.trim();
+    if (profile)
+        qualifiers.push(`profile: ${profile}`);
+    if (endpoint.apiUrlSource === "env")
+        qualifiers.push("api url from OXYGEN_API_URL");
+    return qualifiers.length > 0 ? `${endpoint.apiUrl} (${qualifiers.join(", ")})` : endpoint.apiUrl;
+}
+/** The same facts, machine-readable, for `error.details`. */
+export function cliEndpointDetails(endpoint) {
+    const details = {};
+    if (endpoint.apiUrl)
+        details.api_url = endpoint.apiUrl;
+    const profile = endpoint.profile?.trim();
+    if (profile)
+        details.profile = profile;
+    if (endpoint.apiUrlSource)
+        details.api_url_source = endpoint.apiUrlSource;
+    return details;
+}
 function normalizeBinaryName(value) {
     const normalized = basename(value ?? "")
         .replace(/\.(?:cmd|ps1|bat|js)$/i, "")
@@ -54,3 +120,47 @@ export function isProdApiUrl(apiUrl) {
         return false;
     }
 }
+/**
+ * Do two API URLs address the same deployment? Compared on origin, so a trailing
+ * slash or a path suffix cannot make prod and dev look like different hosts — or
+ * the same one.
+ */
+export function sameApiOrigin(a, b) {
+    try {
+        return new URL(a).origin === new URL(b).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Refuse the command when the resolved host is not the one the caller pinned.
+ *
+ * Called from the one place every request funnels through, so a pin covers reads
+ * and writes alike: the failure mode this exists for is a *read* that looks right
+ * (dev's credit balance answering a question about a production customer), not
+ * only a write landing in the wrong environment.
+ */
+export function assertResolvedApiUrl(endpoint, env = process.env) {
+    const required = env[REQUIRED_API_URL_ENV]?.trim();
+    if (!required)
+        return;
+    let requiredOrigin;
+    try {
+        requiredOrigin = new URL(required).origin;
+    }
+    catch {
+        throw new OxygenError("invalid_required_api_url", `${REQUIRED_API_URL_ENV} must be an absolute URL (for example https://oxygen-agent.com). It is set to "${required}".`, { details: { required_api_url: required }, exitCode: 1 });
+    }
+    const apiUrl = endpoint.apiUrl;
+    if (apiUrl && sameApiOrigin(apiUrl, requiredOrigin))
+        return;
+    throw new OxygenError("api_url_mismatch", `${REQUIRED_API_URL_ENV} pins this command to ${requiredOrigin}, but it resolved to `
+        + `${describeCliEndpoint(endpoint) || "no API URL"}. Refusing to run against the wrong environment. `
+        + `Run \`oxygen profiles list\` to see which profile carries ${requiredOrigin}, then `
+        + "`oxygen profiles use <profile>` — or `oxygen login --api-url "
+        + `${requiredOrigin} --profile <name>\` if no profile holds it yet.`, {
+        details: { required_api_url: requiredOrigin, ...cliEndpointDetails(endpoint) },
+        exitCode: 1,
+    });
+}

package/node_modules/@oxygen/shared/dist/deprecation-registry.js

@@ -18,24 +18,8 @@
 //     floor must sweep the "floor-bump" entries in the same change.
 export const FLOOR_BUMP_SENTINEL = "floor-bump";
 export const DEPRECATION_REGISTRY = [
-    {
-        surface: "oxygen_templates_* MCP alias tools",
-        deprecated_in: "1.80.0",
-        sunset_version: "1.290.0",
-        note: "Deprecated alias tree of oxygen_prompts_* (packages/mcp-server/src/tools/" +
-            "prompt-template-tools.ts, prefix \"oxygen_templates\"). Removal: drop the " +
-            "alias prefix from the generated tools and the CLI `templates` alias " +
-            "command tree, then update the pinned tool counts.",
-    },
-    {
-        surface: "oxygen.linkedin-inbox widget alias",
-        deprecated_in: "1.226.0",
-        sunset_version: "1.290.0",
-        note: "Legacy alias of oxygen.unibox kept so MCP clients that cached " +
-            "ui://oxygen/linkedin-inbox keep resolving (packages/mcp-server/src/widgets/" +
-            "definitions.ts). Removal: delete the alias widget definition and any " +
-            "bindings that still point at it.",
-    },
+    // v1.290.0 sunsets swept 2026-07-10: oxygen_templates_* MCP alias tools and
+    // the oxygen.linkedin-inbox widget alias were removed with their entries.
     {
         surface: "CLI deepLink/deep_link response keys",
         deprecated_in: "1.8.2",

package/node_modules/@oxygen/shared/dist/error-redaction.d.ts

@@ -0,0 +1,80 @@
+export declare const MAX_ERROR_MESSAGE_LENGTH = 500;
+/** Error code for a Postgres deadlock / serialization failure, made actionable. */
+export declare const CONCURRENT_WRITE_CONFLICT_ERROR_CODE = "concurrent_write_conflict";
+/** Why a customer-facing message was withheld. Drives the operator log. */
+export type CustomerErrorRedactionReason = "sql_query" | "internal_http_path" | "database_error";
+export type RedactedCustomerError = {
+    code: string;
+    message: string;
+    details?: unknown;
+    /**
+     * Non-null when the original message was withheld from the customer. The
+     * caller MUST log it (error level) so the detail survives for operators.
+     */
+    redaction: {
+        reason: CustomerErrorRedactionReason;
+        originalMessage: string;
+    } | null;
+};
+/**
+ * Classify + redact one error payload for customer-visible persistence.
+ *
+ * `error` is optional and only sharpens classification: with the raw error we can
+ * read the SQLSTATE (40P01/40001) instead of guessing from message text.
+ */
+export declare function redactCustomerFacingError(input: {
+    code: string;
+    message: string;
+    details?: unknown;
+    error?: unknown;
+}): RedactedCustomerError;
+/**
+ * Redact a persisted error `details` object. Same structural caps and secret-key
+ * rules as the operation-event redactor, plus the customer-facing string scrub —
+ * a provider body nested in `details` carries the same SQL / internal-path /
+ * credential material the top-level message does.
+ */
+export declare function redactCustomerFacingDetails(value: unknown): unknown;
+/** True when the text is a SQL statement rather than prose. Never throws. */
+export declare function isSqlLikeMessage(message: string): boolean;
+/**
+ * Redact a metadata / details payload for an operation event: cap the structure,
+ * blank secret-named fields, truncate long strings. Extracted verbatim from
+ * apps/web/src/lib/observability.ts so the web and the worker share one
+ * implementation; behavior there is unchanged.
+ */
+export declare function redactForOperationEvent(value: unknown, depth?: number): unknown;
+/** Truncate with an ellipsis, preserving the operation-event writer's semantics. */
+export declare function truncateEventString(value: string | null, maxLength: number): string | null;
+/**
+ * The classified, already-redacted failure of a workflow STEP, carried on the
+ * in-flight error so the RUN that the step failed can persist the step's code
+ * instead of a generic catch-all.
+ *
+ * Why an annotation and not a wrapper: the worker's failure path routes on the
+ * error's identity (`instanceof OxygenError`, `.code`, `.cause.code` — lease
+ * lost, transient persistence, awaiting approval, checkpoint retry). Wrapping the
+ * error would silently re-route every one of those. Marking it leaves the object,
+ * and therefore all of that control flow, byte-identical.
+ */
+export type WorkflowStepFailure = {
+    code: string;
+    message: string;
+    details?: unknown;
+    stepId: string;
+    stepRunId: string;
+};
+/** Mark an in-flight error with the step failure already persisted for it. */
+export declare function attachWorkflowStepFailure<T>(error: T, failure: WorkflowStepFailure): T;
+/** Read the step failure a marked error carries, if any. */
+export declare function readWorkflowStepFailure(error: unknown): WorkflowStepFailure | null;
+/**
+ * captureAutomationActions() is two things at once: the admission GATE (it throws
+ * this code at the monthly cap — a decision the customer must feel) and the
+ * metering WRITE (a control-DB insert that can fail for reasons that have nothing
+ * to do with the customer's work). Only the gate may fail a run; a failed write
+ * must be logged and stepped over. This predicate is the line between them, and
+ * it lives here so both worker call sites classify identically.
+ */
+export declare const AUTOMATION_ACTIONS_EXCEEDED_ERROR_CODE = "automation_actions_exceeded";
+export declare function isAutomationUsageQuotaError(error: unknown): boolean;

package/node_modules/@oxygen/shared/dist/error-redaction.js

@@ -0,0 +1,223 @@
+// The ONE redactor for error payloads we persist and show to a customer.
+//
+// Two callers, one implementation: the web API's operation-event writer
+// (apps/web/src/lib/observability.ts) and the worker's durable-run failure
+// writers (workflow_runs.last_error, workflow_step_runs.last_error,
+// workflow_step_attempts.error). Before this module the worker had no redaction
+// at all and wrote `error.message` verbatim, which put internal detail in front
+// of customers. Measured against prod, 90 days, 476 failed workflow runs:
+//
+//   • 29 runs whose customer-visible error WAS a Postgres query — the raw
+//     `Failed query: with existing_event as (select automation_usage_events...)`
+//     CTE from the automation-usage metering write.
+//   • 51 runs leaking an internal HTTP path plus a provider account id, e.g.
+//     `Cannot GET /api/v2/posts/<id>/comments?account_id=<provider account id>`.
+//   • 5 runs leaking raw Postgres `deadlock detected`.
+//
+// The doctrine: the customer gets a clean, actionable message; the ORIGINAL is
+// preserved for operators via log() at error level (see the `redaction` field on
+// the result — a caller that gets a non-null value MUST log it). Redaction is
+// idempotent, never throws, and never widens a message.
+import { redactSecretsInString } from "./redaction.js";
+import { isRetryableConcurrencyError, redactSqlParameters } from "./sql-error.js";
+// Whole fields whose NAME marks them secret. Unchanged from the operation-event
+// writer this was extracted from; substring credentials (Bearer/sk-/DB URLs) are
+// scrubbed separately by redactSecretsInString.
+const SECRET_KEY_PATTERN = /(api[_-]?key|authorization|bearer|cookie|password|secret|token|ciphertext|connection[_-]?uri|database[_-]?url)/i;
+export const MAX_ERROR_MESSAGE_LENGTH = 500;
+const MAX_STRING_LENGTH = 1000;
+const MAX_ARRAY_LENGTH = 20;
+const MAX_OBJECT_KEYS = 40;
+const MAX_REDACTION_DEPTH = 5;
+/** Error code for a Postgres deadlock / serialization failure, made actionable. */
+export const CONCURRENT_WRITE_CONFLICT_ERROR_CODE = "concurrent_write_conflict";
+const CONCURRENT_WRITE_CONFLICT_MESSAGE = "This run conflicted with another write to the same records and was rolled back. Retry the run.";
+const INTERNAL_DATABASE_ERROR_MESSAGE = "An internal database error interrupted this run. Retry the run; if it keeps failing, contact support with the run link.";
+const PROVIDER_REQUEST_FAILED_MESSAGE = "A provider request failed with an unexpected response. Retry the run; if it keeps failing, contact support with the run link.";
+const SQL_MARKER = "[redacted: internal query]";
+const INTERNAL_PATH_MARKER = "[redacted: internal path]";
+// drizzle always prefixes a failed statement with `Failed query:` — that single
+// marker covers every observed prod leak.
+const SQL_FAILED_QUERY_PATTERN = /failed query:/i;
+// Belt-and-braces for a bare statement with no drizzle prefix. All three must
+// hold, because a *leading SQL verb + a structural keyword* alone also describes
+// ordinary product prose ("Select at least one row from the table."). The third
+// clause demands a marker only machine-generated SQL carries — a quoted
+// identifier, a positional placeholder, or a parenthesized column list — so
+// prose can never trip it.
+const SQL_VERB_PREFIX = /^\s*\(?\s*(?:select|with|insert|update|delete|merge)\s/i;
+const SQL_STRUCTURE_KEYWORD = /\b(?:from|where|into|set|values)\b/i;
+const SQL_MACHINE_MARKER = /"[a-z_][\w$]*"|\$\d+|\(\s*"?[a-z_][\w$]*"?\s*[,)]/i;
+// An Express/provider 404 body: leaks the internal route AND its query string,
+// which is where the provider account id rides.
+const INTERNAL_HTTP_PATH_PATTERN = /\bcannot\s+(?:get|post|put|patch|delete|head|options)\s+\/\S*/gi;
+// Raw Postgres concurrency text, for errors that reached us without a SQLSTATE
+// (e.g. across the recipe sandbox boundary, where only {code, message} survives).
+const PG_CONCURRENCY_MESSAGE = /\bdeadlock detected\b|\bcould not serialize access\b/i;
+/**
+ * Classify + redact one error payload for customer-visible persistence.
+ *
+ * `error` is optional and only sharpens classification: with the raw error we can
+ * read the SQLSTATE (40P01/40001) instead of guessing from message text.
+ */
+export function redactCustomerFacingError(input) {
+    const details = input.details === undefined
+        ? undefined
+        : redactCustomerFacingDetails(input.details);
+    const withDetails = details === undefined ? {} : { details };
+    // Strip drizzle's `params: [...]` tail before anything else: those are SQL
+    // parameter VALUES, i.e. customer row data, and they must not survive even
+    // into the operator log (OXY-46).
+    const message = redactSqlParameters(typeof input.message === "string" ? input.message : String(input.message ?? ""));
+    if (isRetryableConcurrencyError(input.error) || PG_CONCURRENCY_MESSAGE.test(message)) {
+        return {
+            code: CONCURRENT_WRITE_CONFLICT_ERROR_CODE,
+            message: CONCURRENT_WRITE_CONFLICT_MESSAGE,
+            ...withDetails,
+            redaction: { reason: "database_error", originalMessage: message },
+        };
+    }
+    if (isSqlLikeMessage(message)) {
+        return {
+            code: input.code,
+            message: INTERNAL_DATABASE_ERROR_MESSAGE,
+            ...withDetails,
+            redaction: { reason: "sql_query", originalMessage: message },
+        };
+    }
+    if (containsInternalHttpPath(message)) {
+        return {
+            code: input.code,
+            message: PROVIDER_REQUEST_FAILED_MESSAGE,
+            ...withDetails,
+            redaction: { reason: "internal_http_path", originalMessage: message },
+        };
+    }
+    return {
+        code: input.code,
+        message: truncate(redactSecretsInString(message), MAX_ERROR_MESSAGE_LENGTH),
+        ...withDetails,
+        redaction: null,
+    };
+}
+/**
+ * Redact a persisted error `details` object. Same structural caps and secret-key
+ * rules as the operation-event redactor, plus the customer-facing string scrub —
+ * a provider body nested in `details` carries the same SQL / internal-path /
+ * credential material the top-level message does.
+ */
+export function redactCustomerFacingDetails(value) {
+    return redactStructured(value, scrubCustomerFacingString, 0);
+}
+/** True when the text is a SQL statement rather than prose. Never throws. */
+export function isSqlLikeMessage(message) {
+    if (SQL_FAILED_QUERY_PATTERN.test(message))
+        return true;
+    return SQL_VERB_PREFIX.test(message)
+        && SQL_STRUCTURE_KEYWORD.test(message)
+        && SQL_MACHINE_MARKER.test(message);
+}
+function containsInternalHttpPath(message) {
+    INTERNAL_HTTP_PATH_PATTERN.lastIndex = 0;
+    return INTERNAL_HTTP_PATH_PATTERN.test(message);
+}
+// A string inside a details payload: drop SQL parameter values, replace a whole
+// SQL statement, blank internal paths in place (the surrounding text may still be
+// useful), scrub credential substrings, then cap.
+function scrubCustomerFacingString(value) {
+    const withoutParams = redactSqlParameters(value);
+    if (isSqlLikeMessage(withoutParams))
+        return SQL_MARKER;
+    const withoutPaths = withoutParams.replace(INTERNAL_HTTP_PATH_PATTERN, INTERNAL_PATH_MARKER);
+    return truncate(redactSecretsInString(withoutPaths), MAX_STRING_LENGTH);
+}
+/**
+ * Redact a metadata / details payload for an operation event: cap the structure,
+ * blank secret-named fields, truncate long strings. Extracted verbatim from
+ * apps/web/src/lib/observability.ts so the web and the worker share one
+ * implementation; behavior there is unchanged.
+ */
+export function redactForOperationEvent(value, depth = 0) {
+    return redactStructured(value, (entry) => truncate(entry, MAX_STRING_LENGTH), depth);
+}
+/** Truncate with an ellipsis, preserving the operation-event writer's semantics. */
+export function truncateEventString(value, maxLength) {
+    return value === null ? null : truncate(value, maxLength);
+}
+// One structural walk, two string policies: the operation-event redactor only
+// truncates, the customer-facing redactor also scrubs. Keeping a single walker
+// means the caps (depth 5, 20 array entries, 40 object keys) can never drift
+// apart between the two surfaces.
+function redactStructured(value, redactString, depth) {
+    if (depth > MAX_REDACTION_DEPTH)
+        return "[truncated]";
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "string")
+        return redactString(value);
+    if (typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (Array.isArray(value)) {
+        return value.slice(0, MAX_ARRAY_LENGTH).map((entry) => redactStructured(entry, redactString, depth + 1));
+    }
+    if (!isRecord(value))
+        return String(value);
+    const entries = Object.entries(value).slice(0, MAX_OBJECT_KEYS);
+    return Object.fromEntries(entries.map(([key, entry]) => [
+        key,
+        SECRET_KEY_PATTERN.test(key) ? "[redacted]" : redactStructured(entry, redactString, depth + 1),
+    ]));
+}
+const WORKFLOW_STEP_FAILURE_KEY = Symbol.for("oxygen.workflow_step_failure");
+/** Mark an in-flight error with the step failure already persisted for it. */
+export function attachWorkflowStepFailure(error, failure) {
+    if (!error || typeof error !== "object")
+        return error;
+    try {
+        Object.defineProperty(error, WORKFLOW_STEP_FAILURE_KEY, {
+            value: failure,
+            enumerable: false,
+            configurable: true,
+            writable: true,
+        });
+    }
+    catch {
+        // A frozen error cannot carry the mark. The run then falls back to the
+        // generic code — worse, but never worse than losing the failure entirely.
+    }
+    return error;
+}
+/** Read the step failure a marked error carries, if any. */
+export function readWorkflowStepFailure(error) {
+    if (!error || typeof error !== "object")
+        return null;
+    const value = error[WORKFLOW_STEP_FAILURE_KEY];
+    if (!isRecord(value))
+        return null;
+    return typeof value.code === "string" && typeof value.message === "string"
+        ? value
+        : null;
+}
+// ---------------------------------------------------------------------------
+// Automation usage: decision vs. failure
+// ---------------------------------------------------------------------------
+/**
+ * captureAutomationActions() is two things at once: the admission GATE (it throws
+ * this code at the monthly cap — a decision the customer must feel) and the
+ * metering WRITE (a control-DB insert that can fail for reasons that have nothing
+ * to do with the customer's work). Only the gate may fail a run; a failed write
+ * must be logged and stepped over. This predicate is the line between them, and
+ * it lives here so both worker call sites classify identically.
+ */
+export const AUTOMATION_ACTIONS_EXCEEDED_ERROR_CODE = "automation_actions_exceeded";
+export function isAutomationUsageQuotaError(error) {
+    return Boolean(error)
+        && typeof error === "object"
+        && error.code === AUTOMATION_ACTIONS_EXCEEDED_ERROR_CODE;
+}
+function truncate(value, maxLength) {
+    return value.length > maxLength ? `${value.slice(0, maxLength - 3)}...` : value;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}