@oxygen-agent/cli 1.948.1 → 1.987.20

package/node_modules/@oxygen/shared/dist/mailbox-import.js

@@ -49,6 +49,27 @@ const MAILBOX_TENANT_HEADERS = new Set([
     "microsofttenantid",
     "tenantid",
 ]);
+const MAILBOX_FIRST_NAME_HEADERS = new Set([
+    "first",
+    "firstname",
+    "givenname",
+]);
+const MAILBOX_LAST_NAME_HEADERS = new Set([
+    "familyname",
+    "last",
+    "lastname",
+    "surname",
+]);
+const MAILBOX_DISPLAY_NAME_HEADERS = new Set([
+    "displayname",
+    "fromname",
+    "name",
+    "sendername",
+]);
+const MAILBOX_SENDER_PROFILE_HEADERS = new Set([
+    "senderprofile",
+    "senderprofileid",
+]);
 const MAILBOX_NON_TRANSFERABLE_SECRET_HEADERS = new Set([
     "accesstoken",
     "applicationsecret",
@@ -328,6 +349,17 @@ function normalizeMailboxExportRow(row, index, mode) {
             ? "microsoft_azure"
             : null);
     const infrastructurePlatform = normalizeMailboxInfrastructurePlatform(infrastructurePlatformRaw, provider, index);
+    // WHO the inbox sends as. Carried through because an inbox always belongs to a
+    // sender (v1.954.0): a file that already names the person is the difference
+    // between a real sender profile and one OXYGEN guesses from the address.
+    const firstName = readMailboxIdentityName(byHeader, MAILBOX_FIRST_NAME_HEADERS, index, "first_name");
+    const lastName = readMailboxIdentityName(byHeader, MAILBOX_LAST_NAME_HEADERS, index, "last_name");
+    const displayName = readMailboxIdentityName(byHeader, MAILBOX_DISPLAY_NAME_HEADERS, index, "display_name");
+    const senderProfileId = readUniqueMailboxExportString(byHeader, MAILBOX_SENDER_PROFILE_HEADERS, index, "sender_profile_id", (value) => value.trim().toLowerCase());
+    if (senderProfileId &&
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(senderProfileId)) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].sender_profile_id must be a sender profile id (UUID). List them with \`oxygen senders profiles list\`, or drop the column and let the row's first/last name name the sender.`, { exitCode: 1 });
+    }
     return {
         email_address: email.trim().toLowerCase(),
         provider,
@@ -338,6 +370,10 @@ function normalizeMailboxExportRow(row, index, mode) {
             ? { infrastructure_platform: infrastructurePlatform }
             : {}),
         ...(tenantId ? { tenant_id: tenantId.trim().toLowerCase() } : {}),
+        ...(firstName ? { first_name: firstName } : {}),
+        ...(lastName ? { last_name: lastName } : {}),
+        ...(displayName ? { display_name: displayName } : {}),
+        ...(senderProfileId ? { sender_profile_id: senderProfileId } : {}),
         ...(mode === "credential" &&
             provider === "google" &&
             distinctPasswords[0] !== undefined
@@ -345,6 +381,23 @@ function normalizeMailboxExportRow(row, index, mode) {
             : {}),
     };
 }
+/**
+ * One identity half off an export row. Header-bound (the From name rides an SMTP
+ * header), so a CR/LF is refused by field name rather than silently stripped — the
+ * caller is usually holding hundreds of rows and needs to know which one.
+ */
+function readMailboxIdentityName(byHeader, headers, index, field) {
+    const value = readUniqueMailboxExportString(byHeader, headers, index, field, (raw) => raw.trim());
+    if (!value)
+        return null;
+    if (value.length > 200) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].${field} must be at most 200 characters.`, { exitCode: 1 });
+    }
+    if (/[\r\n]/.test(value)) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].${field} must be a single line.`, { exitCode: 1 });
+    }
+    return value;
+}
 function normalizeMailboxExportHeader(value) {
     return value
         .replace(/^\uFEFF/, "")

package/node_modules/@oxygen/shared/dist/plan-limits.d.ts

@@ -78,6 +78,14 @@ export type PlanLimits = {
  */
 export declare const TABLE_IMPORT_ROW_LIMIT: 3000000;
 export { VERCEL_REQUEST_BODY_LIMIT_BYTES } from "./import-limits.js";
+/**
+ * OXYGEN's own JSON-body ceiling for every `/api/cli/*` route (enforced by
+ * `assertCliJsonBodyWithinLimit` on the content-length header). Shared so the CLI
+ * pre-splits a row batch by measured bytes instead of learning the number from a
+ * 413. Must stay below VERCEL_REQUEST_BODY_LIMIT_BYTES, and must never be raised
+ * in the CLI alone — an older server would still 413 at the old number.
+ */
+export declare const MAX_CLI_JSON_BODY_BYTES = 2000000;
 /**
  * The per-rung limit matrix. `ai_live` deliberately equals `tool_live` at every
  * rung — one "live actions" mental model; the per-call cost asymmetry between

package/node_modules/@oxygen/shared/dist/plan-limits.js

@@ -21,6 +21,14 @@ export const TABLE_IMPORT_ROW_LIMIT = WORKSPACE_TABLE_CAPACITY.tableRowLimit;
 // ceilings below ("how big can an import be"), but it must stay importable from a
 // browser bundle, so it is defined in ./import-limits and re-exported here.
 export { VERCEL_REQUEST_BODY_LIMIT_BYTES } from "./import-limits.js";
+/**
+ * OXYGEN's own JSON-body ceiling for every `/api/cli/*` route (enforced by
+ * `assertCliJsonBodyWithinLimit` on the content-length header). Shared so the CLI
+ * pre-splits a row batch by measured bytes instead of learning the number from a
+ * 413. Must stay below VERCEL_REQUEST_BODY_LIMIT_BYTES, and must never be raised
+ * in the CLI alone — an older server would still 413 at the old number.
+ */
+export const MAX_CLI_JSON_BODY_BYTES = 2_000_000;
 /**
  * The per-rung limit matrix. `ai_live` deliberately equals `tool_live` at every
  * rung — one "live actions" mental model; the per-call cost asymmetry between

package/node_modules/@oxygen/shared/dist/pricing-sheet.d.ts

@@ -176,7 +176,7 @@ export declare const ENRICHMENT_CREDITS: {
     readonly company_enrich_typical: 99;
     readonly web_search: 5;
     readonly page_scrape: 40;
-    readonly linkedin_profile_scrape: 25.5;
+    readonly linkedin_profile_scrape: 10;
 };
 /** Editable calculator default: blended credits per fully-enriched row. */
 export declare const ENRICHMENT_CREDITS_PER_ROW_TYPICAL = 100;

package/node_modules/@oxygen/shared/dist/pricing-sheet.js

@@ -163,7 +163,7 @@ export const ENRICHMENT_CREDITS = {
     company_enrich_typical: 99,
     web_search: 5, // Serper
     page_scrape: 40, // Firecrawl (wedge price)
-    linkedin_profile_scrape: 25.5, // HarvestAPI Basic full-profile job, exactly 5x COGS
+    linkedin_profile_scrape: 10, // Managed profile credit at $0.002 COGS, exactly 5x
 };
 /** Editable calculator default: blended credits per fully-enriched row. */
 export const ENRICHMENT_CREDITS_PER_ROW_TYPICAL = SNAPSHOT_ENRICHMENT_CREDITS_PER_ROW_TYPICAL;

package/node_modules/@oxygen/shared/dist/product-analytics-events.d.ts

@@ -77,6 +77,30 @@ export declare const PRODUCT_EVENTS: {
     readonly TRIAL_CANCEL_SCHEDULED: "trial_cancel_scheduled";
     readonly TRIAL_CANCEL_RESUMED: "trial_cancel_resumed";
     readonly TRIAL_ENDED_UNCONVERTED: "trial_ended_unconverted";
+    /**
+     * Marketing site. The public hero lookup on oxygen-agent.com: an ANONYMOUS
+     * visitor types their website and OXYGEN spends its own credits profiling it.
+     *
+     * Deliberately absent from the web's KPI_TYPE_TO_EVENT. These describe a
+     * pre-signup funnel step, not a lifecycle moment the company reports, and
+     * mapping one onto a `company_kpi_events` type would redefine a headline
+     * number without anyone editing that number's definition.
+     *
+     * Properties are enums, numbers and the domain HASH only — never the raw
+     * domain. The visitor has no account and never consented to their employer's
+     * name landing in an analytics warehouse (ADR 0021: PostHog stays sanitized).
+     * `hero_lookup_cached` is what says whether the lookup cache is paying for
+     * itself, which is the whole economics of the surface.
+     */
+    readonly HERO_LOOKUP_STARTED: "hero_lookup_started";
+    readonly HERO_PROFILE_COMPLETED: "hero_profile_completed";
+    readonly HERO_LEADS_COMPLETED: "hero_leads_completed";
+    readonly HERO_LOOKUP_CACHED: "hero_lookup_cached";
+    readonly HERO_LOOKUP_DEGRADED: "hero_lookup_degraded";
+    /** Browser-side hero events; props are enums, booleans and counts only. */
+    readonly HERO_LOOKUP_SUBMITTED: "hero_lookup_submitted";
+    readonly HERO_LOOKUP_RENDERED: "hero_lookup_rendered";
+    readonly HERO_SIGNUP_CLICKED: "hero_signup_clicked";
     /** Pipeline heartbeat: proves ingestion is alive when the product is quiet. */
     readonly POSTHOG_CANARY: "posthog_canary";
 };

package/node_modules/@oxygen/shared/dist/product-analytics-events.js

@@ -77,6 +77,30 @@ export const PRODUCT_EVENTS = {
     TRIAL_CANCEL_SCHEDULED: "trial_cancel_scheduled",
     TRIAL_CANCEL_RESUMED: "trial_cancel_resumed",
     TRIAL_ENDED_UNCONVERTED: "trial_ended_unconverted",
+    /**
+     * Marketing site. The public hero lookup on oxygen-agent.com: an ANONYMOUS
+     * visitor types their website and OXYGEN spends its own credits profiling it.
+     *
+     * Deliberately absent from the web's KPI_TYPE_TO_EVENT. These describe a
+     * pre-signup funnel step, not a lifecycle moment the company reports, and
+     * mapping one onto a `company_kpi_events` type would redefine a headline
+     * number without anyone editing that number's definition.
+     *
+     * Properties are enums, numbers and the domain HASH only — never the raw
+     * domain. The visitor has no account and never consented to their employer's
+     * name landing in an analytics warehouse (ADR 0021: PostHog stays sanitized).
+     * `hero_lookup_cached` is what says whether the lookup cache is paying for
+     * itself, which is the whole economics of the surface.
+     */
+    HERO_LOOKUP_STARTED: "hero_lookup_started",
+    HERO_PROFILE_COMPLETED: "hero_profile_completed",
+    HERO_LEADS_COMPLETED: "hero_leads_completed",
+    HERO_LOOKUP_CACHED: "hero_lookup_cached",
+    HERO_LOOKUP_DEGRADED: "hero_lookup_degraded",
+    /** Browser-side hero events; props are enums, booleans and counts only. */
+    HERO_LOOKUP_SUBMITTED: "hero_lookup_submitted",
+    HERO_LOOKUP_RENDERED: "hero_lookup_rendered",
+    HERO_SIGNUP_CLICKED: "hero_signup_clicked",
     /** Pipeline heartbeat: proves ingestion is alive when the product is quiet. */
     POSTHOG_CANARY: "posthog_canary",
 };

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

@@ -16,4 +16,10 @@ export type RecipePrerequisiteKind = typeof RECIPE_PREREQUISITE_KINDS[number];
 export declare const RECIPE_BODY_SECTIONS: readonly ["The Play", "What You Get", "When To Run (And When Not To)", "Before You Start", "Steps", "Ready Assets", "Calibrate", "Troubleshooting", "Operator Notes", "Related"];
 export declare const RECIPE_SLUG_PATTERN: RegExp;
 export declare function recipeWikiSlug(recipeSlug: string): string;
+export declare const RECIPE_KIT_MAX_STAGES = 6;
+export declare const RECIPE_KIT_TABLE_REF_PATTERN: RegExp;
+export declare const RECIPE_KIT_STAGE_STATUSES: readonly ["planned", "installed", "reused", "skipped_active", "blocked", "failed"];
+export type RecipeKitStageStatus = typeof RECIPE_KIT_STAGE_STATUSES[number];
+export type RecipeKitStatus = "not_applied" | "partial" | "applied";
+export declare function recipeKitSourceRef(recipeSlug: string, version: number): string;
 export declare const RECIPE_TRIAL_SAFE_PILOT_CREDIT_CAP = 100;

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

@@ -87,6 +87,29 @@ export const RECIPE_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,119}$/;
 export function recipeWikiSlug(recipeSlug) {
     return `playbook-${recipeSlug}`;
 }
+// ── Kits (ADR 0025) ─────────────────────────────────────────────────────────
+// A recipe carries an ORDERED kit of Blueprint stages. `oxygen recipes apply`
+// preflights every stage into one forecast and installs them all under one
+// approval — 0 credits, no provider call, every installed Workflow disabled.
+// A stage may bind a table created by an earlier stage through a
+// `$stages.<index>.tables.<ref>` reference so later stages graft onto it
+// instead of creating a second table.
+export const RECIPE_KIT_MAX_STAGES = 6;
+export const RECIPE_KIT_TABLE_REF_PATTERN = /^\$stages\.(\d)\.tables\.([a-z][a-z0-9_]*)$/;
+export const RECIPE_KIT_STAGE_STATUSES = [
+    "planned",
+    "installed",
+    "reused",
+    "skipped_active",
+    "blocked",
+    "failed",
+];
+// page_sources ref an apply writes on the recipe's playbook page — one per
+// recipe version, ON CONFLICT DO NOTHING, so first-apply provenance survives
+// reapplies.
+export function recipeKitSourceRef(recipeSlug, version) {
+    return `https://oxygen-agent.com/recipes/${recipeSlug}@v${version}#kit`;
+}
 // trial_safe recipes must keep their pilot path within 10% of the 7-day
 // card-required trial's 1,000 managed credits.
 export const RECIPE_TRIAL_SAFE_PILOT_CREDIT_CAP = 100;

package/node_modules/@oxygen/shared/dist/research-output-contract.d.ts

@@ -14,6 +14,34 @@ export declare function deriveResearchOutputContract(prompt: string, options: {
     evidenceRequired: boolean;
 }): ResearchOutputContract | null;
 export declare function buildResearchOutputSchema(contract: ResearchOutputContract | null): Record<string, unknown>;
+/**
+ * Whether a found answer MUST cite evidence. Shared by the write-path normalizer
+ * (which bakes it into the derived research contract), the runner (which
+ * validates the model output against it) and the output-field reader, so none
+ * of them can disagree.
+ *
+ * Explicit "strict" always requires it. A FETCH column requires it by default —
+ * the evidence is the one page the customer pointed at, so an answer that cites
+ * nothing answered from memory — unless the author chose "estimate".
+ */
+export declare function researchEvidenceRequired(webSearch: unknown): boolean;
+/**
+ * True for a model-facing schema in the research envelope shape — the derived
+ * contract, the legacy broad schema, or a catalog template's typed answer
+ * envelope — as opposed to a hand-authored schema that replaces the envelope
+ * entirely. The output-field reader rewrites only the former into the stored
+ * cell shape (`sources` in, `citations` out); the latter is used verbatim.
+ */
+export declare function isResearchEnvelopeSchema(schema: unknown): boolean;
+/**
+ * The model-facing schema for a research column whose ANSWER is a typed object
+ * (a catalog template such as a pricing summary): the same
+ * `{answer, found, confidence, citations}` envelope the derived contract uses,
+ * with `answer` replaced by the template's own object schema. The runner still
+ * resolves `citations` to real sources on the way to the cell, so a typed
+ * extraction cannot cite a page that was never fetched either.
+ */
+export declare function buildResearchOutputSchemaForAnswer(answerSchema: Record<string, unknown>): Record<string, unknown>;
 /**
  * The schema of the research cell as it is actually STORED — which is not the
  * schema the model answers in.
@@ -27,7 +55,11 @@ export declare function buildResearchOutputSchema(contract: ResearchOutputContra
  * `buildResearchOutputSchema` would offer `citations`, which no cell has, and
  * hide `sources`, which every cell does.
  */
-export declare function buildResearchCellSchema(contract: ResearchOutputContract | null): Record<string, unknown>;
+export declare function buildResearchCellSchema(contract: ResearchOutputContract | null, 
+/** A column's own model-facing schema (a catalog template's typed answer
+ * envelope). When given it replaces the derived one, so the cell shape of a
+ * typed extraction exposes `answer.plan_count`, not a string answer. */
+modelSchemaOverride?: Record<string, unknown> | null): Record<string, unknown>;
 /**
  * Is this research column's output schema OWNED BY THE SERVER, i.e. re-derived
  * from the prompt rather than authored by hand?

package/node_modules/@oxygen/shared/dist/research-output-contract.js

@@ -88,6 +88,64 @@ export function buildResearchOutputSchema(contract) {
         required: ["answer", "found", "confidence", "citations"],
     };
 }
+/**
+ * Whether a found answer MUST cite evidence. Shared by the write-path normalizer
+ * (which bakes it into the derived research contract), the runner (which
+ * validates the model output against it) and the output-field reader, so none
+ * of them can disagree.
+ *
+ * Explicit "strict" always requires it. A FETCH column requires it by default —
+ * the evidence is the one page the customer pointed at, so an answer that cites
+ * nothing answered from memory — unless the author chose "estimate".
+ */
+export function researchEvidenceRequired(webSearch) {
+    if (!isObject(webSearch))
+        return false;
+    if (webSearch.evidenceMode === "strict")
+        return true;
+    if (webSearch.evidenceMode === "estimate")
+        return false;
+    return webSearch.source === "fetch";
+}
+/**
+ * True for a model-facing schema in the research envelope shape — the derived
+ * contract, the legacy broad schema, or a catalog template's typed answer
+ * envelope — as opposed to a hand-authored schema that replaces the envelope
+ * entirely. The output-field reader rewrites only the former into the stored
+ * cell shape (`sources` in, `citations` out); the latter is used verbatim.
+ */
+export function isResearchEnvelopeSchema(schema) {
+    if (!isObject(schema) || schema.type !== "object")
+        return false;
+    const properties = isObject(schema.properties) ? schema.properties : null;
+    if (!properties)
+        return false;
+    return ["answer", "found", "confidence", "citations"].every((key) => isObject(properties[key]));
+}
+/**
+ * The model-facing schema for a research column whose ANSWER is a typed object
+ * (a catalog template such as a pricing summary): the same
+ * `{answer, found, confidence, citations}` envelope the derived contract uses,
+ * with `answer` replaced by the template's own object schema. The runner still
+ * resolves `citations` to real sources on the way to the cell, so a typed
+ * extraction cannot cite a page that was never fetched either.
+ */
+export function buildResearchOutputSchemaForAnswer(answerSchema) {
+    const envelope = buildResearchOutputSchema(null);
+    const properties = isObject(envelope.properties) ? { ...envelope.properties } : {};
+    return {
+        ...envelope,
+        properties: {
+            ...properties,
+            answer: {
+                ...answerSchema,
+                description: typeof answerSchema.description === "string"
+                    ? answerSchema.description
+                    : "The typed answer read from the evidence; unsupported fields are null or empty.",
+            },
+        },
+    };
+}
 /**
  * The schema of the research cell as it is actually STORED — which is not the
  * schema the model answers in.
@@ -101,8 +159,12 @@ export function buildResearchOutputSchema(contract) {
  * `buildResearchOutputSchema` would offer `citations`, which no cell has, and
  * hide `sources`, which every cell does.
  */
-export function buildResearchCellSchema(contract) {
-    const modelSchema = buildResearchOutputSchema(contract);
+export function buildResearchCellSchema(contract, 
+/** A column's own model-facing schema (a catalog template's typed answer
+ * envelope). When given it replaces the derived one, so the cell shape of a
+ * typed extraction exposes `answer.plan_count`, not a string answer. */
+modelSchemaOverride) {
+    const modelSchema = modelSchemaOverride ?? buildResearchOutputSchema(contract);
     const properties = isObject(modelSchema.properties) ? { ...modelSchema.properties } : {};
     delete properties.citations;
     return {

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

@@ -287,5 +287,5 @@ export declare const SEQUENCE_HUBSPOT_EVENT_SYNC_TEMPLATE_ID = "sequencer-hubspo
 export declare const SEQUENCE_WORKFLOW_EVENT_SOURCE = "sequencer";
 export declare const SEQUENCE_CONTACT_ACTIVITY_EVENT = "contact_activity";
 export declare const SEQUENCE_HUBSPOT_LINKEDIN_IDENTITY_PROPERTY = "oxygen_linkedin_url";
-export declare const DEFAULT_SEQUENCE_HUBSPOT_EVENT_MAPPINGS: Readonly<Record<"email_sent" | "meeting_booked" | "email_bounced" | "linkedin_profile_visited" | "linkedin_connection_sent" | "linkedin_connection_accepted" | "linkedin_message_sent" | "linkedin_inmail_sent" | "linkedin_reply_received" | "linkedin_followed" | "linkedin_post_liked" | "linkedin_post_commented" | "linkedin_connection_withdrawn" | "email_campaign_enrolled" | "email_campaign_moved" | "email_campaign_stopped" | "email_opened" | "email_clicked" | "email_reply_received" | "email_unsubscribed" | "email_spam_complaint" | "whatsapp_message_sent" | "whatsapp_reply_received" | "call_task_created" | "call_connected" | "call_no_answer" | "call_voicemail" | "crm_task_created", string>>;
+export declare const DEFAULT_SEQUENCE_HUBSPOT_EVENT_MAPPINGS: Readonly<Record<"call_connected" | "call_no_answer" | "call_task_created" | "call_voicemail" | "crm_task_created" | "email_bounced" | "email_campaign_enrolled" | "email_campaign_moved" | "email_campaign_stopped" | "email_clicked" | "email_opened" | "email_reply_received" | "email_sent" | "email_spam_complaint" | "email_unsubscribed" | "linkedin_connection_accepted" | "linkedin_connection_sent" | "linkedin_connection_withdrawn" | "linkedin_followed" | "linkedin_inmail_sent" | "linkedin_message_sent" | "linkedin_post_commented" | "linkedin_post_liked" | "linkedin_profile_visited" | "linkedin_reply_received" | "meeting_booked" | "whatsapp_message_sent" | "whatsapp_reply_received", string>>;
 export declare function isSequenceCrmEventKey(value: unknown): value is SequenceCrmEventKey;

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

@@ -17,7 +17,7 @@ export declare const HUBSPOT_DEFAULT_LEAD_STATUS_PROPERTY = "hs_lead_status";
 export declare const DEFAULT_HUBSPOT_SEQUENCE_TIMELINE_EVENTS: readonly ["email_sent", "email_reply_received", "email_bounced", "linkedin_message_sent", "linkedin_inmail_sent", "linkedin_reply_received"];
 /** Events for which the HubSpot adapter has a first-class activity object. */
 export declare const HUBSPOT_SEQUENCE_TIMELINE_EVENT_KEYS: readonly ["email_sent", "email_reply_received", "email_bounced", "linkedin_message_sent", "linkedin_inmail_sent", "linkedin_reply_received"];
-export declare const HUBSPOT_CLASSIFIED_REPLY_TIMELINE_EVENTS: Set<"email_sent" | "meeting_booked" | "email_bounced" | "linkedin_profile_visited" | "linkedin_connection_sent" | "linkedin_connection_accepted" | "linkedin_message_sent" | "linkedin_inmail_sent" | "linkedin_reply_received" | "linkedin_followed" | "linkedin_post_liked" | "linkedin_post_commented" | "linkedin_connection_withdrawn" | "email_campaign_enrolled" | "email_campaign_moved" | "email_campaign_stopped" | "email_opened" | "email_clicked" | "email_reply_received" | "email_unsubscribed" | "email_spam_complaint" | "whatsapp_message_sent" | "whatsapp_reply_received" | "call_task_created" | "call_connected" | "call_no_answer" | "call_voicemail" | "crm_task_created">;
+export declare const HUBSPOT_CLASSIFIED_REPLY_TIMELINE_EVENTS: Set<"call_connected" | "call_no_answer" | "call_task_created" | "call_voicemail" | "crm_task_created" | "email_bounced" | "email_campaign_enrolled" | "email_campaign_moved" | "email_campaign_stopped" | "email_clicked" | "email_opened" | "email_reply_received" | "email_sent" | "email_spam_complaint" | "email_unsubscribed" | "linkedin_connection_accepted" | "linkedin_connection_sent" | "linkedin_connection_withdrawn" | "linkedin_followed" | "linkedin_inmail_sent" | "linkedin_message_sent" | "linkedin_post_commented" | "linkedin_post_liked" | "linkedin_profile_visited" | "linkedin_reply_received" | "meeting_booked" | "whatsapp_message_sent" | "whatsapp_reply_received">;
 export type HubSpotSequenceSyncConfig = {
     /** Optional latest-occurrence snapshots on HubSpot contact properties. */
     mappings: Record<SequenceCrmEventKey, string>;

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

@@ -108,8 +108,11 @@ export type EspMatchingMode = (typeof ESP_MATCHING_MODES)[number];
 export declare const DEFAULT_ESP_MATCHING_MODE: EspMatchingMode;
 export declare function isEspMatchingMode(value: unknown): value is EspMatchingMode;
 /**
- * Validate settings.esp_matching before persistence. Absent/null is valid (means
- * DEFAULT_ESP_MATCHING_MODE "off"); any other value must be one of the three
+ * Validate settings.esp_matching before persistence. Absent/null is valid and
+ * means DEFAULT_ESP_MATCHING_MODE, which is "prefer" — an unset sequence still
+ * biases rotation toward a same-provider sender, so a workspace whose senders on
+ * one provider are in bad standing concentrates that provider's recipients on
+ * them until an operator sets "off". Any other value must be one of the three
  * modes. Pure; throws OxygenError("invalid_sequence_settings") on a bad value so
  * the CLI / MCP / API report an identical error. Called from the tenant-db
  * settings validator alongside the budget/prioritization checks.
@@ -128,6 +131,127 @@ export declare function validateEspMatchingSetting(value: unknown): void;
  */
 export declare const RECIPIENT_ESPS: readonly ["google", "microsoft"];
 export type RecipientEsp = (typeof RECIPIENT_ESPS)[number];
+/**
+ * WEIGHTED SENDER ROUTING — the object form of settings.esp_matching.
+ *
+ * The three scalar modes above answer one question ("bias toward the recipient's
+ * own provider, yes or no"), and they bake in the assumption that same-provider
+ * is always better. That assumption fails whenever one provider's senders are in
+ * bad standing: a workspace whose Google-hosted domains are refused by Gmail
+ * wants its Google-hosted RECIPIENTS served from Microsoft senders, which no
+ * scalar mode can express. "off" does not express it either, because free
+ * rotation still hands Google recipients a Google sender in proportion to the
+ * pool.
+ *
+ * So the object form states the routing directly, as SEND SHARES per recipient
+ * provider:
+ *
+ *   { mode: "prefer",
+ *     routes: { google: { microsoft: 100 }, microsoft: { microsoft: 100 } },
+ *     exclude: [{ domain: "burned.example", from_recipients: ["google"] }] }
+ *
+ * `routes` is keyed by the RECIPIENT's resolved provider; the inner map is the
+ * SENDER provider. Weights are relative shares, so { google: 3, microsoft: 1 }
+ * and { google: 75, microsoft: 25 } are the same policy and nothing has to sum
+ * to 100. An omitted weight is zero. A bucket whose entry is explicitly present
+ * but carries no positive weight means "no opinion, rotate freely for this
+ * recipient class"; a bucket the operator never mentioned keeps the historical
+ * same-provider default, so editing Google routing cannot silently change how
+ * Microsoft recipients are served.
+ *
+ * `exclude` is a hard never, not a preference: a sender domain listed here is
+ * removed from the candidate pool for the named recipient buckets (all buckets
+ * when `from_recipients` is absent) in EVERY mode, including "off", and it
+ * survives the prefer-fallback. A deliverability guard that a matching toggle
+ * could disarm would not be a guard.
+ *
+ * The scalar modes remain valid values and are read as policies, so there is one
+ * routing code path rather than two: "prefer" becomes { mode: "prefer" } with no
+ * routes, which resolves to the same-provider default and behaves exactly as it
+ * did before.
+ */
+export declare const ESP_ROUTE_BUCKETS: readonly ["google", "microsoft", "unknown"];
+/** The RECIPIENT side of a route: a matchable provider, or "unknown" when resolution failed. */
+export type EspRouteBucket = (typeof ESP_ROUTE_BUCKETS)[number];
+/** The SENDER side of a route: relative send shares per mailbox provider. */
+export type EspRouteWeights = Partial<Record<RecipientEsp, number>>;
+export type EspSenderExclusion = {
+    domain: string;
+    from_recipients?: EspRouteBucket[];
+};
+export type EspRoutingPolicy = {
+    mode?: EspMatchingMode;
+    routes?: Partial<Record<EspRouteBucket, EspRouteWeights>>;
+    exclude?: EspSenderExclusion[];
+};
+/** settings.esp_matching accepts either the legacy scalar or the routing policy. */
+export type EspMatchingSetting = EspMatchingMode | EspRoutingPolicy;
+/**
+ * A policy with every field present, which is what the dispatcher and the launch
+ * preview consume. Produced only by espPolicyFromSetting so both surfaces answer
+ * identically from the same stored value.
+ */
+export type ResolvedEspPolicy = {
+    mode: EspMatchingMode;
+    routes: Partial<Record<EspRouteBucket, EspRouteWeights>>;
+    exclude: Array<{
+        domain: string;
+        buckets: readonly EspRouteBucket[];
+    }>;
+};
+/** Cap on settings.esp_matching.exclude — a routing policy, not a suppression list. */
+export declare const MAX_ESP_SENDER_EXCLUSIONS = 50;
+/** Upper bound on a single route weight; relative shares never need more. */
+export declare const MAX_ESP_ROUTE_WEIGHT = 1000000;
+export declare function isEspRouteBucket(value: unknown): value is EspRouteBucket;
+/**
+ * A sending domain as the mailbox table stores it: lowercase, no leading "@".
+ * Mirrors lower(split_part(email_address, '@', 2)) in pickEmailMailbox so an
+ * exclusion the operator typed as "@Burned.Example " still matches.
+ */
+export declare function normalizeEspSenderDomain(value: string): string;
+/**
+ * LENIENT read of a persisted settings.esp_matching (never throws — a read must
+ * not break a send). Absent, null, or malformed reads as the default policy, and
+ * a malformed FIELD bails the WHOLE object rather than half-applying a routing
+ * policy, which is the readMailboxRampConfig convention in tenant-db. The strict
+ * counterpart that guards the write path is validateEspMatchingSetting.
+ */
+export declare function espPolicyFromSetting(value: unknown): ResolvedEspPolicy;
+/**
+ * The effective send shares for one recipient bucket. An explicitly-present
+ * entry wins even when it is empty or all-zero (that is the operator saying
+ * "rotate freely here"); a bucket that was never mentioned keeps the historical
+ * same-provider default, and "unknown" has no same-provider to default to.
+ */
+export declare function espRouteWeightsFor(policy: ResolvedEspPolicy, bucket: EspRouteBucket): EspRouteWeights;
+/**
+ * The sender providers to try, best first, for one recipient bucket — a
+ * deterministic weighted shuffle WITHOUT replacement.
+ *
+ * Returning an ORDER rather than a single draw is what makes "prefer" correct:
+ * a 90/10 Google policy over a pool holding no Google mailbox must send 100%
+ * from Microsoft, not defer and not fall through to provider-blind rotation.
+ * An empty result means "no opinion" and the caller rotates freely.
+ *
+ * Deterministic by construction: the seed carries the enrollment and step, never
+ * a clock or Math.random, so a dry-run preview and the later live send choose
+ * the same provider, and a replan after a defer re-derives the same route.
+ * Candidates are enumerated in RECIPIENT_ESPS order rather than object-key
+ * order, because jsonb does not preserve key order and a policy that round-trips
+ * through the database must not reroute the fleet.
+ */
+export declare function espRouteCandidates(input: {
+    policy: ResolvedEspPolicy;
+    recipient: EspRouteBucket;
+    seed: string;
+}): RecipientEsp[];
+/**
+ * Sending domains that must not serve this recipient bucket, normalized and
+ * de-duplicated for pickEmailMailbox. Applies in every mode and survives the
+ * prefer-fallback — see the exclude contract above.
+ */
+export declare function espExcludedSenderDomains(policy: ResolvedEspPolicy, bucket: EspRouteBucket): string[];
 /**
  * The DISPLAY taxonomy: the mail-infrastructure family a recipient domain sits
  * on. Wider than RecipientEsp because "everything that isn't Google or Microsoft"
@@ -795,9 +919,28 @@ export type SequenceLintIssue = {
     path: string;
     message: string;
 };
+/**
+ * A non-blocking fact about how a definition was normalized that its author must
+ * be told, as opposed to an issue that rejects it. Today exactly one:
+ * `email_reply_rewritten`. The retired kind is accepted and rewritten into a
+ * subject-less `email_send`, and a caller that only reads the stored definition
+ * back sees a different `kind` than it wrote with nothing in the response to
+ * explain it — reported as a silent coercion by a customer (Plain T-163).
+ */
+export type SequenceDefinitionNotice = {
+    path: string;
+    code: "email_reply_rewritten";
+    message: string;
+};
 export type ValidateSequenceOptions = {
     /** When provided, every channel-bearing step must use one of these channels. */
     allowedChannels?: SequenceChannel[];
+    /**
+     * Sink for non-blocking normalization notices (see SequenceDefinitionNotice).
+     * Validation never throws for these; a caller that wants to surface them to
+     * the author passes an array and reads it back after the call.
+     */
+    notices?: SequenceDefinitionNotice[];
     /**
      * Whether this sequence has NATIVE open/click tracking enabled (a verified
      * tracking domain + EMAIL_TRACKING_SECRET, so the dispatcher injects a pixel +
@@ -856,6 +999,13 @@ export declare function sequenceStepsMissingCopy(steps: readonly SequenceStep[])
  */
 export declare function validateSequenceDefinition(input: unknown, options?: ValidateSequenceOptions): SequenceDefinition;
 /** Non-throwing variant for lint surfaces. */
+/**
+ * The non-blocking notices normalizing this definition would raise, for a
+ * response `warnings` array. Never throws: an invalid definition yields whatever
+ * notices were collected before validation gave up (the caller's own validate
+ * call reports the failure), so this is safe to run beside a persist.
+ */
+export declare function sequenceDefinitionNotices(input: unknown, options?: Omit<ValidateSequenceOptions, "notices">): SequenceDefinitionNotice[];
 export declare function lintSequenceDefinition(input: unknown, options?: ValidateSequenceOptions): SequenceLintIssue[];
 /** Total base delay in milliseconds a wait step introduces (no jitter). */
 export declare function sequenceWaitStepDelayMs(step: SequenceWaitStep): number;