@oxygen-agent/cli 1.861.1 → 1.879.0

package/node_modules/@oxygen/shared/dist/sequence-failures.d.ts

@@ -0,0 +1,47 @@
+export declare const SEQUENCE_FAILURE_SCHEMA_VERSION = 1;
+export declare const SEQUENCE_FAILURE_RETRY_AFTER_MAX_MS: number;
+export declare const SEQUENCE_FAILURE_CLASSES: readonly ["capacity", "recipient", "authorization_scope", "funding", "validation", "provider", "internal", "effect_unknown", "unknown"];
+export type SequenceFailureClass = (typeof SEQUENCE_FAILURE_CLASSES)[number];
+export type SequenceFailureEffectOutcome = "not_applied" | "applied" | "unknown";
+export type SequenceFailureEnvelope = {
+    failure_schema_version: typeof SEQUENCE_FAILURE_SCHEMA_VERSION;
+    failure_class: SequenceFailureClass;
+    code: string;
+    message: string;
+    provider?: string;
+    operation?: string;
+    provider_subtype?: string;
+    http_status?: number;
+    retryable?: boolean;
+    effect_outcome?: SequenceFailureEffectOutcome;
+    retry_after_ms?: number;
+    hard_bounce?: boolean;
+};
+export type SequenceFailureOverrides = {
+    code?: string | null;
+    provider?: string | null;
+    operation?: string | null;
+    providerSubtype?: string | null;
+    httpStatus?: number | null;
+    retryable?: boolean | null;
+    effectOutcome?: SequenceFailureEffectOutcome | null;
+    retryAfterMs?: number | null;
+    hardBounce?: boolean | null;
+    /** Existing safe diagnostic fields to retain while adopting the envelope. */
+    legacyFields?: Record<string, unknown>;
+};
+/**
+ * Return one canonical, redacted Sequence action failure while retaining the
+ * legacy fields current readers may still consume. Canonical fields always win
+ * over legacy collisions, so future SQL can depend on one stable shape.
+ *
+ * This function classifies provenance only. It never decides whether an action
+ * retries, defers, fails, consumes credits, or advances an enrollment.
+ */
+export declare function serializeSequenceFailure(error: unknown, overrides?: SequenceFailureOverrides): Record<string, unknown> & SequenceFailureEnvelope;
+/**
+ * Read both the versioned envelope and historical Sequence error shapes. A
+ * missing fact stays missing: in particular, this reader never manufactures a
+ * `not_applied` outcome from retryability, status, or error text.
+ */
+export declare function readSequenceFailure(error: unknown, overrides?: SequenceFailureOverrides): SequenceFailureEnvelope;

package/node_modules/@oxygen/shared/dist/sequence-failures.js

@@ -0,0 +1,301 @@
+import { redactCustomerFacingDetails, redactCustomerFacingError, } from "./error-redaction.js";
+import { isProviderFundingErrorCode, isProviderRateLimitErrorCode, } from "./provider-funding-errors.js";
+export const SEQUENCE_FAILURE_SCHEMA_VERSION = 1;
+export const SEQUENCE_FAILURE_RETRY_AFTER_MAX_MS = 24 * 60 * 60 * 1000;
+export const SEQUENCE_FAILURE_CLASSES = [
+    "capacity",
+    "recipient",
+    "authorization_scope",
+    "funding",
+    "validation",
+    "provider",
+    "internal",
+    "effect_unknown",
+    "unknown",
+];
+const FAILURE_CLASS_SET = new Set(SEQUENCE_FAILURE_CLASSES);
+const EFFECT_OUTCOME_SET = new Set([
+    "not_applied",
+    "applied",
+    "unknown",
+]);
+/**
+ * Return one canonical, redacted Sequence action failure while retaining the
+ * legacy fields current readers may still consume. Canonical fields always win
+ * over legacy collisions, so future SQL can depend on one stable shape.
+ *
+ * This function classifies provenance only. It never decides whether an action
+ * retries, defers, fails, consumes credits, or advances an enrollment.
+ */
+export function serializeSequenceFailure(error, overrides = {}) {
+    const base = redactRecord({
+        ...legacyRecord(error),
+        ...(overrides.legacyFields ?? {}),
+    });
+    const failure = readSequenceFailure(error, overrides);
+    const output = { ...base };
+    // A legacy payload may already carry malformed or unbounded values under the
+    // new keys. Remove them before projecting the validated canonical envelope.
+    for (const key of [
+        "failure_schema_version",
+        "failure_class",
+        "code",
+        "message",
+        "provider",
+        "operation",
+        "provider_subtype",
+        "http_status",
+        "retryable",
+        "effect_outcome",
+        "retry_after_ms",
+        "hard_bounce",
+    ]) {
+        delete output[key];
+    }
+    Object.assign(output, failure, { error_message: failure.message });
+    return output;
+}
+/**
+ * Read both the versioned envelope and historical Sequence error shapes. A
+ * missing fact stays missing: in particular, this reader never manufactures a
+ * `not_applied` outcome from retryability, status, or error text.
+ */
+export function readSequenceFailure(error, overrides = {}) {
+    const records = failureRecords(error);
+    const sourceCode = overrides.code ?? firstString(records, ["code", "error_code", "errorCode"]);
+    const rawCode = redactCanonicalString(sourceCode) ?? "unknown_error";
+    const rawMessage = firstString(records, ["message", "error_message", "errorMessage"]) ??
+        (error instanceof Error ? error.message : null) ??
+        "Sequence action failed.";
+    const redacted = redactCustomerFacingError({
+        code: rawCode,
+        message: rawMessage,
+        error,
+    });
+    const provider = redactCanonicalString(overrides.provider ??
+        firstString(records, ["provider", "provider_id", "providerId"]));
+    const operation = redactCanonicalString(overrides.operation ??
+        firstString(records, [
+            "operation",
+            "provider_operation",
+            "providerOperation",
+        ]));
+    const providerSubtype = redactCanonicalString(overrides.providerSubtype ??
+        firstString(records, [
+            "provider_subtype",
+            "source_code",
+            "sourceCode",
+            "provider_error_code",
+        ]));
+    const httpStatus = normalizeHttpStatus(overrides.httpStatus ??
+        firstNumber(records, [
+            "http_status",
+            "httpStatus",
+            "status",
+            "status_code",
+            "statusCode",
+            "provider_status",
+            "providerStatus",
+        ]));
+    const retryable = overrides.retryable ?? firstBoolean(records, ["retryable"]);
+    const effectOutcome = overrides.effectOutcome ?? readEffectOutcome(records);
+    const retryAfterMs = normalizeRetryAfterMs(overrides.retryAfterMs ?? readRetryAfterMs(records));
+    const hardBounce = overrides.hardBounce ??
+        firstBoolean(records, ["hard_bounce", "hardBounce"]);
+    const existingClass = firstString(records, ["failure_class"]);
+    const existingVersion = firstNumber(records, ["failure_schema_version"]);
+    const classified = classifySequenceFailure({
+        code: redacted.code,
+        providerSubtype,
+        provider,
+        httpStatus,
+        retryable,
+        effectOutcome,
+        hardBounce,
+        errorName: firstString(records, ["error_name", "name"]),
+    });
+    // A supported, versioned envelope owns its classification. Legacy payloads
+    // do not: their stray `failure_class` fields are mapped from the underlying
+    // facts. Effect-unknown remains the fail-safe exception even for a malformed
+    // v1 envelope, because it must never be made replay-safe by a stale class.
+    const failureClass = effectOutcome === "unknown"
+        ? "effect_unknown"
+        : existingVersion === SEQUENCE_FAILURE_SCHEMA_VERSION &&
+            existingClass &&
+            FAILURE_CLASS_SET.has(existingClass)
+            ? existingClass
+            : classified;
+    return {
+        failure_schema_version: SEQUENCE_FAILURE_SCHEMA_VERSION,
+        failure_class: failureClass,
+        code: redacted.code,
+        message: redacted.message,
+        ...(provider ? { provider } : {}),
+        ...(operation ? { operation } : {}),
+        ...(providerSubtype ? { provider_subtype: providerSubtype } : {}),
+        ...(httpStatus !== null ? { http_status: httpStatus } : {}),
+        ...(retryable !== null ? { retryable } : {}),
+        ...(effectOutcome ? { effect_outcome: effectOutcome } : {}),
+        ...(retryAfterMs !== null ? { retry_after_ms: retryAfterMs } : {}),
+        ...(hardBounce !== null ? { hard_bounce: hardBounce } : {}),
+    };
+}
+function classifySequenceFailure(input) {
+    const codes = [input.code, input.providerSubtype]
+        .filter(Boolean)
+        .join(" ")
+        .toLowerCase();
+    // Ambiguous effects win every other classification. A 429-shaped code or a
+    // provider name must never make a possibly-applied write safe to replay.
+    if (input.effectOutcome === "unknown" ||
+        /(?:effect|outcome)[_-]?unknown|ambiguous[_-]?(?:effect|write)/i.test(codes)) {
+        return "effect_unknown";
+    }
+    if ([input.code, input.providerSubtype].some((code) => isProviderFundingErrorCode(code)))
+        return "funding";
+    if (input.httpStatus === 429 ||
+        [input.code, input.providerSubtype].some((code) => isProviderRateLimitErrorCode(code))) {
+        return "capacity";
+    }
+    if (input.httpStatus === 401 ||
+        input.httpStatus === 403 ||
+        /auth|permission|scope|credential|forbidden|unauthori[sz]ed|not[_-]?connected|connection[_-]?(?:invalid|expired)/i.test(codes)) {
+        return "authorization_scope";
+    }
+    if (input.hardBounce === true ||
+        /recipient|hard[_-]?bounce|invalid[_-]?(?:profile|recipient|member)|lead[_-]?not[_-]?found|already[_-]?(?:connected|invited)|not[_-]?eligible|cannot[_-]?(?:message|invite)/i.test(codes)) {
+        return "recipient";
+    }
+    if (input.httpStatus === 400 ||
+        input.httpStatus === 422 ||
+        /validation|invalid[_-]?request|bad[_-]?request|malformed|required[_-]?field|unsupported[_-]?(?:input|value)/i.test(codes)) {
+        return "validation";
+    }
+    if ((input.httpStatus !== null && input.httpStatus >= 500) ||
+        (input.httpStatus === 404 && input.retryable === true) ||
+        input.provider !== null ||
+        /provider|upstream|tool[_-]?unavailable|network|timeout|temporar(?:y|ily)[_-]?unavailable/i.test(codes)) {
+        return "provider";
+    }
+    if (/^(?:TypeError|ReferenceError|RangeError|SyntaxError)$/i.test(input.errorName ?? "") ||
+        /internal|database|persistence|bookkeeping|invariant|concurrent[_-]?write/i.test(codes)) {
+        return "internal";
+    }
+    return "unknown";
+}
+function failureRecords(value) {
+    const direct = asRecord(value);
+    const nestedError = asRecord(direct?.error);
+    const directDetails = asRecord(direct?.details);
+    const nestedDetails = asRecord(nestedError?.details);
+    const body = asRecord(direct?.body);
+    const nestedBody = asRecord(nestedError?.body);
+    const providerError = asRecord(directDetails?.provider_error) ??
+        asRecord(nestedDetails?.provider_error);
+    return [
+        direct,
+        nestedError,
+        directDetails,
+        nestedDetails,
+        body,
+        nestedBody,
+        providerError,
+    ].filter((entry) => entry !== null);
+}
+function legacyRecord(value) {
+    const direct = asRecord(value);
+    if (value instanceof Error) {
+        return {
+            ...(direct ? Object.fromEntries(Object.entries(direct)) : {}),
+            error_name: value.name,
+            error_message: value.message,
+        };
+    }
+    if (direct)
+        return direct;
+    return { error_id: "non_error", error_message: String(value) };
+}
+function redactRecord(value) {
+    const redacted = redactCustomerFacingDetails(value);
+    return asRecord(redacted) ?? {};
+}
+function redactCanonicalString(value) {
+    if (value === null)
+        return null;
+    const redacted = redactCustomerFacingDetails(value);
+    return typeof redacted === "string" && redacted.trim()
+        ? redacted.trim()
+        : null;
+}
+function readEffectOutcome(records) {
+    const value = firstString(records, [
+        "effect_outcome",
+        "effectOutcome",
+        "outcome",
+    ]);
+    if (value === "effect_unknown")
+        return "unknown";
+    return value && EFFECT_OUTCOME_SET.has(value)
+        ? value
+        : null;
+}
+function readRetryAfterMs(records) {
+    const milliseconds = firstNumber(records, ["retry_after_ms", "retryAfterMs"]);
+    if (milliseconds !== null)
+        return milliseconds;
+    const seconds = firstNumber(records, [
+        "retry_after_seconds",
+        "retryAfterSeconds",
+        "retry_after",
+    ]);
+    return seconds === null ? null : seconds * 1000;
+}
+function normalizeRetryAfterMs(value) {
+    if (value === null || !Number.isFinite(value) || value <= 0)
+        return null;
+    return Math.max(1_000, Math.min(SEQUENCE_FAILURE_RETRY_AFTER_MAX_MS, Math.ceil(value)));
+}
+function normalizeHttpStatus(value) {
+    if (value === null || !Number.isInteger(value) || value < 100 || value > 599)
+        return null;
+    return value;
+}
+function firstString(records, keys) {
+    for (const record of records) {
+        for (const key of keys) {
+            const value = record[key];
+            if (typeof value === "string" && value.trim())
+                return value.trim();
+        }
+    }
+    return null;
+}
+function firstNumber(records, keys) {
+    for (const record of records) {
+        for (const key of keys) {
+            const value = record[key];
+            if (typeof value === "number" && Number.isFinite(value))
+                return value;
+            if (typeof value === "string" && value.trim()) {
+                const parsed = Number(value);
+                if (Number.isFinite(parsed))
+                    return parsed;
+            }
+        }
+    }
+    return null;
+}
+function firstBoolean(records, keys) {
+    for (const record of records) {
+        for (const key of keys) {
+            if (typeof record[key] === "boolean")
+                return record[key];
+        }
+    }
+    return null;
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}

package/node_modules/@oxygen/shared/dist/telemetry.d.ts

@@ -8,3 +8,4 @@ export declare function markActiveTelemetryError(message: string, attributes?: T
 export declare function recordTelemetryCounter(name: string, value?: number, attributes?: TelemetryAttributes): void;
 export declare function recordTelemetryHistogram(name: string, value: number, attributes?: TelemetryAttributes): void;
 export declare function commonTelemetryAttributes(attributes?: TelemetryAttributes): TelemetryAttributes;
+export declare function metricSafeAttributes(attributes?: TelemetryAttributes): TelemetryAttributes;

package/node_modules/@oxygen/shared/dist/telemetry.js

@@ -57,13 +57,13 @@ export function recordTelemetryCounter(name, value = 1, attributes) {
     if (!Number.isFinite(value))
         return;
     const counter = getCounter(name);
-    counter.add(value, normalizeTelemetryAttributes(commonTelemetryAttributes(attributes)));
+    counter.add(value, normalizeTelemetryAttributes(metricSafeAttributes(commonTelemetryAttributes(attributes))));
 }
 export function recordTelemetryHistogram(name, value, attributes) {
     if (!Number.isFinite(value))
         return;
     const histogram = getHistogram(name);
-    histogram.record(value, normalizeTelemetryAttributes(commonTelemetryAttributes(attributes)));
+    histogram.record(value, normalizeTelemetryAttributes(metricSafeAttributes(commonTelemetryAttributes(attributes))));
 }
 export function commonTelemetryAttributes(attributes) {
     const workerProcess = isWorkerProcess();
@@ -85,6 +85,123 @@ export function commonTelemetryAttributes(attributes) {
         ...attributes,
     };
 }
+// Metrics are billed by *series count*, not by call volume. The OTLP exporter
+// defaults to CUMULATIVE temporality, which means every series a process has
+// ever recorded is re-sent — uncompressed, in full — on every 60s export tick
+// for the entire lifetime of the process. Series never retire. So one attribute
+// whose value varies per request (`trace.id` above all) does not add a label:
+// it turns a single metric into an unbounded, permanently growing set of series,
+// and a histogram multiplies that by ~20 bucket datapoints per series.
+//
+// This is not theoretical. Measured on the Fly worker, outbound traffic GREW
+// with process uptime — 1.70 MB/s at 6.5min, 2.36 MB/s at 8min, 5.56 MB/s
+// averaged over 2.5h — against a flat ~0.4-1.0 MB/s inbound, which is exactly
+// the shape of a re-export set that only ever gets bigger. Fly bills egress at
+// $0.02/GB with no free allowance, putting this one leak at ~$125-290/month.
+// Corroboration: the oxygen-metrics-dev Axiom dataset held 860,493,157
+// datapoints / 935.79 GB from ONE otherwise-idle dev worker, against 36.95 GB
+// for all traces and 12.21 GB for all logs combined.
+//
+// Hence an ALLOW-LIST rather than a deny-list: a future call site that hands a
+// recorder a fresh id-shaped attribute must be structurally unable to
+// reintroduce unbounded series without someone editing this set on purpose.
+// Every key below has a small, closed value domain. Ids and free-form paths
+// (`trace.id`, `run.id`, `org.id`, `tool.id`, `url.path`, `retry.after_ms`)
+// are dropped here and here only — they stay on SPANS, which carry the full
+// attribute set, are written once, and are never re-exported. Do not add an id
+// to this list; if you need to slice a metric by one, you want a span or a log.
+//
+// The same rule kills a subtler case: several worker call sites pass a
+// *measurement* as an attribute (table_action.claimed, queue.probed_tenant_count,
+// workflow.completed, table_ingestion.item_count, worker.tenant_count, ...).
+// An arbitrary integer is not a dimension — each distinct count minted its own
+// permanent series. Those are dropped here too; a count belongs in the metric's
+// VALUE, not in its labels.
+//
+// One exclusion is worth naming because it reads bounded and is not: `route`
+// from apps/web/src/lib/cli-http.ts is `new URL(request.url).pathname` (:1067),
+// the RAW path — so /api/cli/tables/<tableId>/rows carries a table id and mints
+// a series per table. `command` covers the same question without the ids.
+const METRIC_SAFE_ATTRIBUTE_KEYS = new Set([
+    // Bounded dimensions supplied by call sites. This list was derived by walking
+    // all 123 recordTelemetry* call sites, not from one call site's vocabulary:
+    // the same concept is spelled differently in different surfaces (`method` in
+    // apps/web/src/lib/cli-http.ts vs `http.request.method` in provider-fetch,
+    // `role` in supervisor.ts vs `worker.role` in worker-step.ts), and an
+    // allow-list that knows only one spelling silently strips the other.
+    "surface",
+    "outcome",
+    "status",
+    "provider.name",
+    "provider.operation",
+    "credential.mode",
+    "http.request.method",
+    "http.response.status_code",
+    "error.code",
+    "retry.attempt",
+    "rate_limit.source",
+    // apps/web/src/lib/cli-http.ts builds oxygen.cli.commands /
+    // oxygen.cli.command.duration_ms from snake_case keys. `command` is the whole
+    // point of that counter — "which command is failing" is the only question it
+    // exists to answer — so these must survive.
+    "command",
+    "method",
+    "ok",
+    "error_code",
+    "auth_type",
+    // Bounded worker/lane dimensions. These are the natural breakdowns for the
+    // oxygen.worker.* instruments (a step name, a lifecycle phase, a queue lane),
+    // and every one of them is a closed enum defined in this repo, not a value
+    // derived from customer data. They are what makes a worker metric readable at
+    // all, so they are kept deliberately — dropping them would have traded an
+    // unbounded series count for a useless one.
+    //
+    // Note what is NOT here: `worker.id`. Per-Machine slicing already survives via
+    // the OTel *resource* attributes (resource.host.name / resource.process.pid),
+    // which are attached once per export rather than multiplied into every series,
+    // so adding it here would multiply the whole metric set by the fleet size for
+    // a breakdown that is already available.
+    "worker.role",
+    "role",
+    "worker.phase",
+    "worker.step",
+    "worker.step.effect",
+    "worker.advisory_loop",
+    "worker.once",
+    "worker.cycle.kind",
+    "worker.cycle.phase",
+    "worker.cycle.slow",
+    "table_action.lane",
+    "tenant.ticket_reason",
+    "queue.stalled",
+    "scope",
+    "rail",
+    "overall_status",
+    "provider",
+    "provider_status",
+    // Bounded per-process dimensions injected by commonTelemetryAttributes. These
+    // are constant for the lifetime of a process, so they cost one series each.
+    "oxygen.version",
+    "deployment.environment",
+    "deployment.sha",
+    "deployment.git_sha",
+    "cloud.region",
+]);
+// Narrows an attribute bag to METRIC_SAFE_ATTRIBUTE_KEYS. Applied only by
+// recordTelemetryCounter / recordTelemetryHistogram — withTelemetrySpan,
+// setActiveTelemetryAttributes and markActiveTelemetryError deliberately keep
+// every attribute they are given, because spans are what engineers debug with
+// and cost one write rather than one series re-sent every minute forever.
+export function metricSafeAttributes(attributes) {
+    if (!attributes)
+        return {};
+    const output = {};
+    for (const [key, value] of Object.entries(attributes)) {
+        if (METRIC_SAFE_ATTRIBUTE_KEYS.has(key))
+            output[key] = value;
+    }
+    return output;
+}
 // Picks the env-var fallback list for the active surface (worker vs web), then
 // returns the first env var in that list that is set, else null. Preserves the
 // original `a ?? b ?? null` semantics exactly: only an unset (`undefined`) env

package/node_modules/@oxygen/shared/dist/version.d.ts

@@ -1,4 +1,4 @@
-export declare const OXYGEN_VERSION = "1.861.1";
+export declare const OXYGEN_VERSION = "1.879.0";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";
 export declare const MANAGED_INBOX_MINIMUM_CLI_VERSION = "1.326.2";
 export declare const SUPPORT_AGENT_REPLY_MINIMUM_CLI_VERSION = "1.747.0";

package/node_modules/@oxygen/shared/dist/version.js

@@ -1,4 +1,4 @@
-export const OXYGEN_VERSION = "1.861.1";
+export const OXYGEN_VERSION = "1.879.0";
 // The GLOBAL CLI compatibility floor: the oldest CLI allowed to call any
 // operational route. Raising it hard-rejects every older CLI from the entire
 // product, so it obeys one law, enforced by scripts/ci/cli-min-version-gate.mjs:

package/node_modules/@oxygen/shared/package.json

@@ -56,6 +56,21 @@
       "import": "./dist/column-types.js",
       "default": "./dist/column-types.js"
     },
+    "./json-path": {
+      "types": "./dist/json-path.d.ts",
+      "import": "./dist/json-path.js",
+      "default": "./dist/json-path.js"
+    },
+    "./column-output-fields": {
+      "types": "./dist/column-output-fields.d.ts",
+      "import": "./dist/column-output-fields.js",
+      "default": "./dist/column-output-fields.js"
+    },
+    "./research-output-contract": {
+      "types": "./dist/research-output-contract.d.ts",
+      "import": "./dist/research-output-contract.js",
+      "default": "./dist/research-output-contract.js"
+    },
     "./object-storage": {
       "types": "./dist/object-storage.d.ts",
       "import": "./dist/object-storage.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxygen-agent/cli",
-  "version": "1.861.1",
+  "version": "1.879.0",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",