@oxygen-agent/cli 1.987.20 → 1.1010.1

package/node_modules/@oxygen/shared/dist/cutover-freeze.js

@@ -0,0 +1,52 @@
+// The cutover write freeze, and the one place that reads `OXYGEN_CUTOVER_FREEZE`.
+//
+// WHY THIS EXISTS. Moving production between database hosts has a short window
+// in which every committed write must already be on the source when the final
+// checkpoint is taken, and nothing may commit on the source afterwards. The
+// operator sets `OXYGEN_CUTOVER_FREEZE=1` on the stack being retired; every
+// writer asks this module and stands down (`ops/selfhost/cutover/RUNBOOK.md`).
+//
+// UNSET MEANS NOT FROZEN, deliberately and permanently: a variable nobody set
+// must never take production into maintenance. The recognised truthy values are
+// the ones the three pre-existing readers accepted (`1`, `true`, `yes`, `on`,
+// `enabled`), so consolidating them here changes no environment's behaviour.
+//
+// Read per call rather than memoized at module load: tests drive both states,
+// and a snapshot taken at import would make the freeze untestable.
+import { OxygenError } from "./cli-result.js";
+export const CUTOVER_FREEZE_ENV_VAR = "OXYGEN_CUTOVER_FREEZE";
+/**
+ * The machine code every maintenance refusal carries, on every surface (web,
+ * CLI, MCP, public webhooks). Retryable by contract: nothing the caller sent was
+ * wrong, and the same request succeeds once the window closes.
+ */
+export const MAINTENANCE_IN_PROGRESS_CODE = "maintenance_in_progress";
+/** What `Retry-After` says during the window. Short enough that an agent loop resumes promptly. */
+export const MAINTENANCE_RETRY_AFTER_SECONDS = 120;
+/**
+ * Fixed customer copy (ADR 0023): says what is happening and what to do, names
+ * no host, database or vendor, and promises nothing about the exact end time.
+ */
+export const MAINTENANCE_IN_PROGRESS_MESSAGE = "OXYGEN is in a short scheduled maintenance window. Nothing was changed; retry in a few minutes.";
+const TRUTHY = new Set(["1", "true", "yes", "on", "enabled"]);
+export function isCutoverFreezeActive(env = process.env) {
+    const value = env[CUTOVER_FREEZE_ENV_VAR]?.trim().toLowerCase();
+    return value !== undefined && TRUTHY.has(value);
+}
+/**
+ * The typed maintenance fault. `reason` is a stable machine token (never prose)
+ * that tells an operator which fenced path refused, e.g.
+ * `tenant_schema_migration_pending` or `tenant_database_suspended`.
+ */
+export function maintenanceInProgressError(reason, details = {}) {
+    return new OxygenError(MAINTENANCE_IN_PROGRESS_CODE, MAINTENANCE_IN_PROGRESS_MESSAGE, {
+        details: {
+            reason,
+            retryable: true,
+            retry_after_seconds: MAINTENANCE_RETRY_AFTER_SECONDS,
+            next_step: "Retry the same request after the maintenance window; nothing needs to change.",
+            ...details,
+        },
+        exitCode: 1,
+    });
+}

package/node_modules/@oxygen/shared/dist/data-suppliers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The companies that supply OXYGEN's managed data, keyed by OXYGEN provider id.
+ *
+ * Founder decision (Philipp, 2026-09-25, reversing the 2026-09-11 rule that hid
+ * the managed LinkedIn rail's backend): data suppliers are NAMED — on
+ * /subprocessors, in provider labels, and in run provenance. What stays out of
+ * every customer surface is unchanged (ADR 0023): vendor hosts, keys, internal
+ * COGS, and upstream error text. Name the supplier from this map; never copy a
+ * vendor string into a label, descriptor, or help text by hand.
+ *
+ * Dependency-free on purpose: browser bundles (the picker, the record page)
+ * import it.
+ */
+export declare const MANAGED_DATA_SUPPLIERS: {
+    /** The managed `scraper.*` LinkedIn rail. HarvestAPI is BYOK only and is not listed. */
+    readonly scraper: "Up2Data";
+    /** Company-page follower audiences, fulfilled by the vendor. */
+    readonly scrapeli: "ScrapeLi";
+    /** LinkedIn post datasets on OXYGEN's managed key. */
+    readonly brightdata: "Bright Data";
+    /** Indexed company and people data on OXYGEN's managed key. */
+    readonly crustdata: "Crustdata";
+};
+export type ManagedDataSupplierProvider = keyof typeof MANAGED_DATA_SUPPLIERS;
+/**
+ * Customer-visible name of the managed LinkedIn data rail (`scraper.*`). Founder
+ * decision 2026-09-25: data-extraction labels say "Professional Network", while
+ * ids, routes and operation names keep `linkedin`.
+ */
+export declare const PROFESSIONAL_NETWORK_DATA_NAME = "Professional Network Data";
+/** The supplier behind a provider's MANAGED lane, or null when OXYGEN names none. */
+export declare function managedDataSupplier(provider: string | null | undefined): string | null;
+/**
+ * `name · supplied by <supplier>` for a provider whose supplier is not already
+ * its name; the name unchanged otherwise ("Bright Data" never reads "Bright Data
+ * · supplied by Bright Data").
+ */
+export declare function suppliedByLabel(name: string, provider: string | null | undefined): string;
+/** "Professional Network Data · supplied by Up2Data" — the managed LinkedIn rail's label. */
+export declare const PROFESSIONAL_NETWORK_DATA_LABEL: string;
+/**
+ * How a supplier obtains an operation's data. Informational only: it never gates,
+ * prices, or routes anything.
+ *
+ * - `supplier_collected`: the supplier collects and provides the data.
+ * - `supplier_may_use_logged_in_sessions`: the data is reachable only while
+ *   signed in (engagers, activity feeds, search, admin-only lists), so the
+ *   supplier may use logged-in sessions it operates. No customer account is used.
+ */
+export type DataSourcingMethod = "supplier_collected" | "supplier_may_use_logged_in_sessions";
+export type DataSourcing = {
+    supplier: string;
+    method: DataSourcingMethod;
+    note: string;
+};
+/** The disclosure an operation carries, in one sentence per method. */
+export declare function dataSourcingFor(provider: ManagedDataSupplierProvider, method: DataSourcingMethod): DataSourcing;

package/node_modules/@oxygen/shared/dist/data-suppliers.js

@@ -0,0 +1,59 @@
+/**
+ * The companies that supply OXYGEN's managed data, keyed by OXYGEN provider id.
+ *
+ * Founder decision (Philipp, 2026-09-25, reversing the 2026-09-11 rule that hid
+ * the managed LinkedIn rail's backend): data suppliers are NAMED — on
+ * /subprocessors, in provider labels, and in run provenance. What stays out of
+ * every customer surface is unchanged (ADR 0023): vendor hosts, keys, internal
+ * COGS, and upstream error text. Name the supplier from this map; never copy a
+ * vendor string into a label, descriptor, or help text by hand.
+ *
+ * Dependency-free on purpose: browser bundles (the picker, the record page)
+ * import it.
+ */
+export const MANAGED_DATA_SUPPLIERS = {
+    /** The managed `scraper.*` LinkedIn rail. HarvestAPI is BYOK only and is not listed. */
+    scraper: "Up2Data",
+    /** Company-page follower audiences, fulfilled by the vendor. */
+    scrapeli: "ScrapeLi",
+    /** LinkedIn post datasets on OXYGEN's managed key. */
+    brightdata: "Bright Data",
+    /** Indexed company and people data on OXYGEN's managed key. */
+    crustdata: "Crustdata",
+};
+/**
+ * Customer-visible name of the managed LinkedIn data rail (`scraper.*`). Founder
+ * decision 2026-09-25: data-extraction labels say "Professional Network", while
+ * ids, routes and operation names keep `linkedin`.
+ */
+export const PROFESSIONAL_NETWORK_DATA_NAME = "Professional Network Data";
+/** The supplier behind a provider's MANAGED lane, or null when OXYGEN names none. */
+export function managedDataSupplier(provider) {
+    if (!provider || !Object.hasOwn(MANAGED_DATA_SUPPLIERS, provider))
+        return null;
+    return MANAGED_DATA_SUPPLIERS[provider];
+}
+/**
+ * `name · supplied by <supplier>` for a provider whose supplier is not already
+ * its name; the name unchanged otherwise ("Bright Data" never reads "Bright Data
+ * · supplied by Bright Data").
+ */
+export function suppliedByLabel(name, provider) {
+    const supplier = managedDataSupplier(provider);
+    if (!supplier || name.toLowerCase().includes(supplier.toLowerCase()))
+        return name;
+    return `${name} · supplied by ${supplier}`;
+}
+/** "Professional Network Data · supplied by Up2Data" — the managed LinkedIn rail's label. */
+export const PROFESSIONAL_NETWORK_DATA_LABEL = suppliedByLabel(PROFESSIONAL_NETWORK_DATA_NAME, "scraper");
+/** The disclosure an operation carries, in one sentence per method. */
+export function dataSourcingFor(provider, method) {
+    const supplier = MANAGED_DATA_SUPPLIERS[provider];
+    return {
+        supplier,
+        method,
+        note: method === "supplier_collected"
+            ? `Collected and provided by ${supplier}. No account of yours is used.`
+            : `Collected by ${supplier}, which may use signed-in sessions it operates. No account of yours is used.`,
+    };
+}

package/node_modules/@oxygen/shared/dist/deploy-env.d.ts

@@ -0,0 +1,74 @@
+/**
+ * One answer to "which deployment is this, and is it holding production data".
+ *
+ * Before this module the repo had at least four: `VERCEL_ENV === "production" ||
+ * NODE_ENV === "production"` (the recipe sandbox guard), `FLY_ENVIRONMENT ===
+ * "production" || NODE_ENV === "production"` (the worker health guard), the
+ * Fly-app-name chain in `apps/worker/src/worker-env.ts`, and the
+ * product-analytics / Langfuse environment pickers. Self-hosting adds
+ * environments that are neither the managed prod nor the managed dev app while
+ * carrying production-shaped data (`selfhost-shadow`), which is exactly the case
+ * every one of those expressions answers wrong.
+ *
+ * `OXYGEN_DEPLOY_ENV` is the discriminator. Unset means managed: every caller
+ * falls back to the legacy signals byte-identically, so a managed environment
+ * that sets nothing behaves precisely as production does today
+ * (`.agents/skills/oxygen-platform-portability/SKILL.md` rule 1).
+ *
+ * Deliberately dependency-free apart from `OxygenError`: the log shipper, the
+ * OTel registration and the worker boot guard all read it before any heavier
+ * module is loaded.
+ */
+export type DeployPlatform = "managed" | "selfhost";
+/**
+ * `shadow` is a self-hosted environment running against production-shaped data
+ * during the cutover rehearsal. It is NOT production traffic, but it is
+ * production data — hence `isProductionData()` covers it while the telemetry
+ * environment keeps it out of the production dataset.
+ */
+export type DeployTier = "prod" | "shadow" | "dev" | "local";
+export type DeployEnvSource = "OXYGEN_DEPLOY_ENV" | "VERCEL_ENV" | "FLY_APP_NAME" | "NODE_ENV" | "none";
+export type DeployEnv = {
+    platform: DeployPlatform;
+    tier: DeployTier;
+    /** Stable human/telemetry label: the raw selector on self-hosted, `managed-<tier>` otherwise. */
+    label: string;
+    /** Which signal decided the tier — the field to print when an operator disputes the answer. */
+    source: DeployEnvSource;
+};
+/**
+ * Resolves the deployment identity of this process.
+ *
+ * Throws `invalid_deploy_env` on any non-empty `OXYGEN_DEPLOY_ENV` that is not
+ * one of the three self-hosted values. A typo must fail the process, never fall
+ * through to the managed chain: falling through would silently resolve a
+ * self-hosted box holding production data as `local`, which is the exact shape
+ * of the sandbox-guard landmine this module exists to close.
+ */
+export declare function resolveDeployEnv(env?: NodeJS.ProcessEnv): DeployEnv;
+/**
+ * True when this process may touch production data, i.e. when an unsandboxed
+ * executor, a duplicated sweep or an external write would hit real customers.
+ *
+ * With `OXYGEN_DEPLOY_ENV` set this is the tier (`prod` or `shadow`). With it
+ * unset this is EXACTLY the legacy expression the recipe sandbox guard has
+ * always used — not the resolved tier — because the tier chain reads
+ * `FLY_APP_NAME` before `NODE_ENV` and would therefore disengage the guard on a
+ * Fly dev app that a Doppler secret had put into `NODE_ENV=production`. Unset
+ * means managed, and managed means byte-identical.
+ */
+export declare function isProductionData(env?: NodeJS.ProcessEnv): boolean;
+/** True when this process runs on self-hosted infrastructure. */
+export declare function isSelfhost(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The `deployment.environment` / tracing-environment value implied by
+ * `OXYGEN_DEPLOY_ENV`, or `null` when it is unset so the caller keeps its own
+ * managed chain untouched.
+ *
+ * `selfhost-shadow` maps to `development`: it carries production-shaped data but
+ * must never land in the production telemetry dataset, where it would be read as
+ * real customer traffic.
+ */
+export declare function deployEnvTelemetryEnvironment(env?: NodeJS.ProcessEnv): "production" | "development" | null;
+/** The `oxygen.platform` telemetry attribute: `managed` or `selfhost`. */
+export declare function deployPlatformAttribute(env?: NodeJS.ProcessEnv): DeployPlatform;

package/node_modules/@oxygen/shared/dist/deploy-env.js

@@ -0,0 +1,82 @@
+import { OxygenError } from "./cli-result.js";
+const SELFHOST_TIERS = new Map([
+    ["selfhost-prod", "prod"],
+    ["selfhost-shadow", "shadow"],
+    ["selfhost-dev", "dev"],
+]);
+function managed(tier, source) {
+    return { platform: "managed", tier, label: `managed-${tier}`, source };
+}
+/**
+ * Resolves the deployment identity of this process.
+ *
+ * Throws `invalid_deploy_env` on any non-empty `OXYGEN_DEPLOY_ENV` that is not
+ * one of the three self-hosted values. A typo must fail the process, never fall
+ * through to the managed chain: falling through would silently resolve a
+ * self-hosted box holding production data as `local`, which is the exact shape
+ * of the sandbox-guard landmine this module exists to close.
+ */
+export function resolveDeployEnv(env = process.env) {
+    const configured = env.OXYGEN_DEPLOY_ENV?.trim();
+    if (configured) {
+        const tier = SELFHOST_TIERS.get(configured.toLowerCase());
+        if (!tier) {
+            throw new OxygenError("invalid_deploy_env", `OXYGEN_DEPLOY_ENV must be one of selfhost-prod, selfhost-shadow, selfhost-dev (received '${configured}').`, { details: { oxygen_deploy_env: configured }, exitCode: 1 });
+        }
+        return { platform: "selfhost", tier, label: `selfhost-${tier}`, source: "OXYGEN_DEPLOY_ENV" };
+    }
+    const vercelEnv = env.VERCEL_ENV?.trim();
+    if (vercelEnv === "production")
+        return managed("prod", "VERCEL_ENV");
+    if (vercelEnv === "preview" || vercelEnv === "development")
+        return managed("dev", "VERCEL_ENV");
+    const flyApp = env.FLY_APP_NAME?.trim();
+    if (flyApp)
+        return managed(flyApp.includes("-dev") ? "dev" : "prod", "FLY_APP_NAME");
+    const nodeEnv = env.NODE_ENV?.trim();
+    if (nodeEnv === "production")
+        return managed("prod", "NODE_ENV");
+    if (nodeEnv)
+        return managed("local", "NODE_ENV");
+    return managed("local", "none");
+}
+/**
+ * True when this process may touch production data, i.e. when an unsandboxed
+ * executor, a duplicated sweep or an external write would hit real customers.
+ *
+ * With `OXYGEN_DEPLOY_ENV` set this is the tier (`prod` or `shadow`). With it
+ * unset this is EXACTLY the legacy expression the recipe sandbox guard has
+ * always used — not the resolved tier — because the tier chain reads
+ * `FLY_APP_NAME` before `NODE_ENV` and would therefore disengage the guard on a
+ * Fly dev app that a Doppler secret had put into `NODE_ENV=production`. Unset
+ * means managed, and managed means byte-identical.
+ */
+export function isProductionData(env = process.env) {
+    if (env.OXYGEN_DEPLOY_ENV?.trim()) {
+        const { tier } = resolveDeployEnv(env);
+        return tier === "prod" || tier === "shadow";
+    }
+    return env.VERCEL_ENV === "production" || env.NODE_ENV === "production";
+}
+/** True when this process runs on self-hosted infrastructure. */
+export function isSelfhost(env = process.env) {
+    return resolveDeployEnv(env).platform === "selfhost";
+}
+/**
+ * The `deployment.environment` / tracing-environment value implied by
+ * `OXYGEN_DEPLOY_ENV`, or `null` when it is unset so the caller keeps its own
+ * managed chain untouched.
+ *
+ * `selfhost-shadow` maps to `development`: it carries production-shaped data but
+ * must never land in the production telemetry dataset, where it would be read as
+ * real customer traffic.
+ */
+export function deployEnvTelemetryEnvironment(env = process.env) {
+    if (!env.OXYGEN_DEPLOY_ENV?.trim())
+        return null;
+    return resolveDeployEnv(env).tier === "prod" ? "production" : "development";
+}
+/** The `oxygen.platform` telemetry attribute: `managed` or `selfhost`. */
+export function deployPlatformAttribute(env = process.env) {
+    return resolveDeployEnv(env).platform;
+}

package/node_modules/@oxygen/shared/dist/dnc-rules.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The workspace do-not-contact RULE CATALOG: which events may put somebody on the
+ * DNC list, and what the workspace has decided each one should do.
+ *
+ * WHY THIS EXISTS. Suppression ENFORCEMENT has always been absolute and layered —
+ * enrollment, plan and a dispatch-time re-check per channel — and none of that is
+ * configurable, on purpose: once an identity is on a ledger it always blocks. What
+ * was equally hardcoded, and should not have been, is ENTRY. Six writers decided
+ * unilaterally who lands on the list, and one of them was blunt enough to be a
+ * product complaint in its own right: ANY inbound LinkedIn message suppressed that
+ * person org-wide, forever, so a lead who replied "sure, send me pricing" could
+ * never be enrolled in another campaign again.
+ *
+ * The split this module draws is therefore: the workspace owns WHO GETS ON the
+ * list; the platform still owns WHAT A LIST ENTRY DOES. A rule resolves to one of
+ * three effects:
+ *
+ *   off       — the event is observed and recorded as it always was, but writes no
+ *               suppression. Nothing else about the event changes.
+ *   stop_only — end THIS enrollment, do not write the permanent ledger row. The
+ *               missing middle: "a reply stops the cadence" without "blacklist this
+ *               human from every future campaign".
+ *   suppress  — stop and write the ledger row. The default for every rule that
+ *               shipped before this catalog existed, which is what makes the
+ *               defaults a byte-for-byte reproduction of previous behaviour.
+ *
+ * DEFAULTS ARE THE OLD BEHAVIOUR. Every pre-existing rule defaults to `suppress`
+ * with the exact reason its writer used to hardcode, and every rule introduced with
+ * this catalog defaults to `off`. A workspace that never opens the Rules page keeps
+ * precisely the product it had, and a policy read that fails resolves to these
+ * defaults rather than dropping a suppression on the floor.
+ *
+ * COMPLIANCE RULES ARE CONFIGURABLE, AND FLAGGED. `email_unsubscribe_click` and
+ * `email_hard_bounce` carry `compliance: true`. That flag does not lock them — the
+ * product owner's decision (2026-09-19) is that a workspace may set any rule to any
+ * allowed effect — it marks the two whose surfaces must say plainly what turning
+ * them down means: an explicit unsubscribe request that is not honoured, and a
+ * hard-bounced address that keeps being mailed from the shared pool (which is also
+ * the numerator of the mailbox auto-pause). The warning is the product's job; the
+ * decision is the customer's.
+ */
+/** What a rule does when its event fires. */
+export declare const DNC_RULE_EFFECTS: readonly ["off", "stop_only", "suppress"];
+export type DncRuleEffect = (typeof DNC_RULE_EFFECTS)[number];
+export declare const DNC_RULE_EFFECT_LABELS: Record<DncRuleEffect, string>;
+/**
+ * Which ledger a rule writes when it resolves to `suppress`. This decides which
+ * reason enum the configured reason is validated against, so a rule can never be
+ * saved with a reason its target table's CHECK constraint would reject at write
+ * time — the failure has to land on the person changing the setting, not on the
+ * inbound webhook hours later.
+ */
+export declare const DNC_RULE_LEDGERS: readonly ["email", "contact", "phone"];
+export type DncRuleLedger = (typeof DNC_RULE_LEDGERS)[number];
+export type DncRuleDefinition = {
+    key: string;
+    /** Short label for a list row. */
+    label: string;
+    /** One sentence naming the exact event, in customer words. */
+    description: string;
+    /** Which DNC ledger a `suppress` writes. */
+    ledger: DncRuleLedger;
+    /** Effect when the workspace has not overridden the rule. */
+    defaultEffect: DncRuleEffect;
+    /** Reason stamped on the ledger row when the rule suppresses. */
+    defaultReason: string;
+    /**
+     * The effects this rule can actually express. A call disposition has no cadence
+     * step to stop, so `stop_only` is omitted rather than offered and silently
+     * behaving like `off`.
+     */
+    allowedEffects: readonly DncRuleEffect[];
+    /** Surfaces must warn before this rule is set below `suppress`. See the header. */
+    compliance?: boolean;
+    /** Grouping for the surfaces. */
+    group: "automatic" | "reply_classification";
+};
+/**
+ * The writers that existed before this catalog, each pinned to the reason and
+ * ledger it used to hardcode. Changing a `defaultEffect` or `defaultReason` here
+ * silently changes every workspace that has not overridden that rule, which is why
+ * `dnc-rules.test.ts` pins every one of them.
+ *
+ * `whatsapp_reply` is the LinkedIn rule's twin and was found the same way: an
+ * inbound WhatsApp message suppressed the lead org-wide with no way to say
+ * otherwise. Its DNC identity is the normalized chat JID rather than a lead
+ * provider id, because `whatsapp_message` is excluded from lead resolution — see
+ * the note in whatsapp-inbox-service.ts about why it is deliberately NOT the
+ * phone ledger.
+ */
+export declare const DNC_BUILTIN_RULES: readonly DncRuleDefinition[];
+/**
+ * Reply-classification rules are addressed by label key, so an org's own inbox
+ * labels get rules on exactly the same footing as the shipped ones. The prefix
+ * keeps that namespace from ever colliding with a builtin key.
+ */
+export declare const DNC_REPLY_STATUS_RULE_PREFIX = "reply_status:";
+export declare function replyStatusRuleKey(labelKey: string): string;
+export declare function replyStatusLabelKey(ruleKey: string): string | null;
+/**
+ * Build the rule definition for one inbox label. `ledger: "email"` is not a claim
+ * that the rule is email-only — it names which reason enum the reason is validated
+ * against. The applier picks the ledger per identity at write time, because the
+ * same classified conversation can carry an email address, a LinkedIn person, or
+ * both, and a classified LinkedIn DM must be able to suppress the LinkedIn person.
+ */
+export declare function replyStatusRule(label: {
+    key: string;
+    name?: string | null;
+}): DncRuleDefinition;
+/** The builtin definition for a key, or null when the key is not a builtin. */
+export declare function builtinDncRule(key: string): DncRuleDefinition | null;
+export declare function isDncRuleEffect(value: unknown): value is DncRuleEffect;
+/**
+ * Resolve a stored rule key to its definition. A `reply_status:*` key resolves even
+ * when the org has since renamed or archived the label, so an override never
+ * becomes unreadable (and therefore unresettable) because a label moved.
+ */
+export declare function resolveDncRuleDefinition(key: string, labels?: ReadonlyArray<{
+    key: string;
+    name?: string | null;
+}>): DncRuleDefinition | null;
+/**
+ * The full catalog a surface renders: the six builtins, then one rule per inbox
+ * label the workspace can classify a reply as.
+ */
+export declare function dncRuleCatalog(labels?: ReadonlyArray<{
+    key: string;
+    name?: string | null;
+}>): DncRuleDefinition[];