@oxygen-agent/cli 1.936.1 → 1.982.3

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-core.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Product-analytics core — the TRANSPORT-FREE half of PostHog emission.
+ *
+ * Two runtimes emit product events: the web/API runtime (`apps/web/src/lib/
+ * product-analytics.ts`, `posthog-node` on Vercel) and the Fly worker
+ * (`apps/worker/src/product-analytics.ts`, `posthog-node` batching). What they
+ * must agree on lives here, once: property sanitization, the distinct-id
+ * chain, the person-profile posture, org grouping, and the runtime dimensions
+ * every event carries. Two copies of that logic drifted in the past — the
+ * worker would have minted a throwaway person per request while the web side
+ * did not — and PostHog cannot join what the emitters disagree about.
+ *
+ * Deliberately NO `posthog-node`, no fetch, no I/O: `packages/shared` is
+ * vendored into the published `@oxygen-agent/cli` tarball, so every runtime
+ * dependency added here lands on every customer's machine
+ * (`scripts/cli-package-dependencies.mjs`, the langfuse-class guard). The
+ * capture message is a plain object structurally compatible with
+ * `posthog-node`'s `EventMessage`; each runtime owns its own client.
+ */
+export declare const PRODUCT_ANALYTICS_MAX_PROPERTY_KEY_LENGTH = 80;
+export declare const PRODUCT_ANALYTICS_MAX_PROPERTY_STRING_LENGTH = 500;
+/**
+ * Byte ceiling for a structured (object/array) property value.
+ *
+ * Structured values pass through UNTOUCHED — see `sanitizeStructuredValue` — so
+ * this is the only thing standing between a careless caller and an unbounded
+ * ingest payload. Set well above `MCP_PAYLOAD_LIMITS.maxSerializedBytes` (8 KiB,
+ * in apps/web `analytics/mcp-analytics.ts`) so it can never re-cut a payload
+ * that module already bounded and marked; it exists for the callers that bound
+ * nothing.
+ */
+export declare const PRODUCT_ANALYTICS_MAX_STRUCTURED_PROPERTY_BYTES = 32768;
+/**
+ * A JSON value PostHog can index as a structured property.
+ *
+ * PostHog's reserved MCP-Analytics properties (`$mcp_parameters`,
+ * `$mcp_response`, `$mcp_listed_tool_names`) are objects and arrays by vendor
+ * contract, so a scalar-only property type made the entire `$mcp_*` surface
+ * untransmittable: a `.slice(...)` on an array is a `TypeError`, and that throw
+ * escaped `trackProductEvent` — losing the whole event, not just the property.
+ */
+export type ProductAnalyticsJsonValue = string | number | boolean | null | readonly ProductAnalyticsJsonValue[] | {
+    readonly [key: string]: ProductAnalyticsJsonValue;
+};
+export type ProductAnalyticsValue = ProductAnalyticsJsonValue | undefined;
+/** What `sanitizeProductAnalyticsProperties` is allowed to hand the SDK. */
+export type ProductAnalyticsSanitizedValue = string | number | boolean | null | ProductAnalyticsJsonValue;
+export type ProductAnalyticsProperties = Record<string, ProductAnalyticsValue>;
+export type ProductAnalyticsEventInput = {
+    event: string;
+    distinctId?: string | null | undefined;
+    organizationId?: string | null | undefined;
+    userId?: string | null | undefined;
+    properties?: ProductAnalyticsProperties;
+    /**
+     * Ingestion id. PostHog dedupes on it, so a revenue event replayed from a
+     * Stripe webhook redelivery — or a run outcome re-read after a worker
+     * restart — lands once instead of double-counting. Supply a value derived
+     * from the source fact (the KPI event key, the run id), never a random one,
+     * or replay stops being deterministic.
+     */
+    uuid?: string | null | undefined;
+    /** When the fact happened, if that is not "now" (webhook replay, backfill, run settle). */
+    timestamp?: Date | null | undefined;
+};
+/**
+ * The message shape both `posthog-node` capture paths accept. Declared here so
+ * the builder needs no `posthog-node` import; the web/worker clients pass it
+ * straight to `capture` / `captureImmediate`.
+ */
+export type ProductAnalyticsCaptureMessage = {
+    distinctId: string;
+    event: string;
+    properties: Record<string, ProductAnalyticsSanitizedValue>;
+    groups?: Record<string, string>;
+    uuid?: string;
+    timestamp?: Date;
+};
+/**
+ * What the emitting runtime knows about itself. `environment` is the
+ * PROD/MAIN/DEV/LOCAL dimension every insight filters on
+ * (`resolveProductAnalyticsEnvironmentFromEnv`); `runtimeProperties` are the
+ * runtime-specific facts (Vercel env/sha/region on the web, Fly app/region on
+ * the worker) and are set BEFORE the caller's properties so a caller can
+ * override them but never lose them by accident.
+ */
+export type ProductAnalyticsRuntimeContext = {
+    environment: string;
+    oxygenVersion: string;
+    runtimeProperties?: ProductAnalyticsProperties;
+};
+export declare function sanitizeProductAnalyticsProperties(properties: ProductAnalyticsProperties): Record<string, ProductAnalyticsSanitizedValue>;
+export declare function normalizeProductAnalyticsIdentifier(value: ProductAnalyticsValue): string | null;
+/**
+ * Build the capture message every runtime sends. Returns null when no distinct
+ * id can be derived — an event with no subject is dropped, never invented.
+ */
+export declare function buildProductAnalyticsCaptureMessage(input: ProductAnalyticsEventInput, context: ProductAnalyticsRuntimeContext): ProductAnalyticsCaptureMessage | null;

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

@@ -0,0 +1,159 @@
+/**
+ * Product-analytics core — the TRANSPORT-FREE half of PostHog emission.
+ *
+ * Two runtimes emit product events: the web/API runtime (`apps/web/src/lib/
+ * product-analytics.ts`, `posthog-node` on Vercel) and the Fly worker
+ * (`apps/worker/src/product-analytics.ts`, `posthog-node` batching). What they
+ * must agree on lives here, once: property sanitization, the distinct-id
+ * chain, the person-profile posture, org grouping, and the runtime dimensions
+ * every event carries. Two copies of that logic drifted in the past — the
+ * worker would have minted a throwaway person per request while the web side
+ * did not — and PostHog cannot join what the emitters disagree about.
+ *
+ * Deliberately NO `posthog-node`, no fetch, no I/O: `packages/shared` is
+ * vendored into the published `@oxygen-agent/cli` tarball, so every runtime
+ * dependency added here lands on every customer's machine
+ * (`scripts/cli-package-dependencies.mjs`, the langfuse-class guard). The
+ * capture message is a plain object structurally compatible with
+ * `posthog-node`'s `EventMessage`; each runtime owns its own client.
+ */
+export const PRODUCT_ANALYTICS_MAX_PROPERTY_KEY_LENGTH = 80;
+export const PRODUCT_ANALYTICS_MAX_PROPERTY_STRING_LENGTH = 500;
+/**
+ * Byte ceiling for a structured (object/array) property value.
+ *
+ * Structured values pass through UNTOUCHED — see `sanitizeStructuredValue` — so
+ * this is the only thing standing between a careless caller and an unbounded
+ * ingest payload. Set well above `MCP_PAYLOAD_LIMITS.maxSerializedBytes` (8 KiB,
+ * in apps/web `analytics/mcp-analytics.ts`) so it can never re-cut a payload
+ * that module already bounded and marked; it exists for the callers that bound
+ * nothing.
+ */
+export const PRODUCT_ANALYTICS_MAX_STRUCTURED_PROPERTY_BYTES = 32_768;
+export function sanitizeProductAnalyticsProperties(properties) {
+    const sanitized = {};
+    for (const [rawKey, rawValue] of Object.entries(properties)) {
+        const key = sanitizePropertyKey(rawKey);
+        if (!key || rawValue === undefined)
+            continue;
+        const value = sanitizePropertyValue(rawValue);
+        if (value !== undefined)
+            sanitized[key] = value;
+    }
+    return sanitized;
+}
+function sanitizePropertyKey(key) {
+    const normalized = key
+        .trim()
+        .replace(/[^A-Za-z0-9_.$-]/g, "_")
+        .slice(0, PRODUCT_ANALYTICS_MAX_PROPERTY_KEY_LENGTH);
+    return normalized || null;
+}
+function sanitizePropertyValue(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "string")
+        return value.slice(0, PRODUCT_ANALYTICS_MAX_PROPERTY_STRING_LENGTH);
+    return sanitizeStructuredValue(value);
+}
+/**
+ * Objects and arrays pass through UNTOUCHED, or not at all.
+ *
+ * Deliberately not walked, re-keyed, `String()`d, or cut at the string ceiling:
+ * the callers that send structured values (apps/web `analytics/mcp-analytics.ts`)
+ * have already redacted and bounded them, and a second pass here would either
+ * corrupt a payload into invalid JSON — which is exactly what an old
+ * `.slice(0, 500)` did to any array — or silently undo the marked truncation
+ * the first pass recorded.
+ *
+ * The only checks are the two that protect the pipe: it must be JSON-encodable
+ * (a cycle or a BigInt would otherwise throw inside the SDK, and `JSON.stringify`
+ * itself throws HERE, upstream of the emitter's try), and it must be under the
+ * byte ceiling. Failing either drops the one property, never the event.
+ */
+function sanitizeStructuredValue(value) {
+    try {
+        const serialized = JSON.stringify(value);
+        if (typeof serialized !== "string")
+            return undefined;
+        if (Buffer.byteLength(serialized, "utf8") > PRODUCT_ANALYTICS_MAX_STRUCTURED_PROPERTY_BYTES) {
+            return undefined;
+        }
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function normalizeProductAnalyticsIdentifier(value) {
+    if (typeof value === "string" && value.trim()) {
+        return value.trim().slice(0, PRODUCT_ANALYTICS_MAX_PROPERTY_STRING_LENGTH);
+    }
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return null;
+}
+/**
+ * Build the capture message every runtime sends. Returns null when no distinct
+ * id can be derived — an event with no subject is dropped, never invented.
+ */
+export function buildProductAnalyticsCaptureMessage(input, context) {
+    const organizationId = normalizeProductAnalyticsIdentifier(input.organizationId);
+    const distinctIdSource = [
+        { value: input.distinctId, identifiesPerson: true },
+        { value: input.userId, identifiesPerson: true },
+        // Namespaced: a bare org UUID is indistinguishable from a human UUID at
+        // query time, so an unprefixed org fallback silently pollutes person-level
+        // counts (and any "users who…" cohort) with workspace rows. The `groups`
+        // attachment below keeps the RAW id — PostHog resolves group keys by exact
+        // match against the org id the rest of the product uses.
+        { value: organizationId ? `org:${organizationId}` : null, identifiesPerson: false },
+        { value: input.properties?.trace_id, identifiesPerson: false },
+        { value: input.properties?.request_id, identifiesPerson: false },
+    ].find((candidate) => candidate.value !== null && candidate.value !== undefined);
+    const distinctId = normalizeProductAnalyticsIdentifier(distinctIdSource?.value);
+    if (!distinctId)
+        return null;
+    const properties = sanitizeProductAnalyticsProperties({
+        product_analytics_environment: context.environment,
+        oxygen_version: context.oxygenVersion,
+        ...context.runtimeProperties,
+        organization_id: organizationId,
+        user_id: normalizeProductAnalyticsIdentifier(input.userId),
+        ...input.properties,
+        // Person profiles are a per-event decision on backend SDKs, not an init
+        // option. `posthog-node`'s client extends `PostHogCoreStateless`, which has
+        // no person-mode state at all — only the browser's stateful `PostHogCore`
+        // reads `personProfiles`. A `personProfiles: "identified_only"` passed to the
+        // constructor typechecks and is then read by nothing, so every event would
+        // get a person profile regardless.
+        //
+        // Without this, the `trace_id`/`request_id` tail of the distinct-id chain
+        // mints one throwaway person per request. Set last so a caller-supplied
+        // property can never flip the posture.
+        //
+        // `|| organizationId` is load-bearing, not defensive: PostHog cannot run
+        // group analytics on an anonymous event, and `@posthog/core`'s own
+        // `_hasPersonProcessing()` is `isIdentified || hasGroups || enabled` — the
+        // SDK forces person processing ON whenever `$groups` is attached. Emitting
+        // the inverse pairing would silently zero every org-grouped trend, funnel
+        // and retention on exactly the two highest-volume events
+        // (`cli_command_run`, `$mcp_tool_call`), because org-API-key traffic has no
+        // `userId` and falls through to the org-id candidate. The cost this whole
+        // switch targets is the per-REQUEST trace/request-id tail; one profile per
+        // ORG is cheap and is where the group data lives.
+        $process_person_profile: (distinctIdSource?.identifiesPerson ?? false) || Boolean(organizationId),
+    });
+    return {
+        distinctId,
+        event: input.event,
+        properties,
+        ...(organizationId ? { groups: { organization: organizationId } } : {}),
+        ...(input.uuid ? { uuid: input.uuid } : {}),
+        ...(input.timestamp ? { timestamp: input.timestamp } : {}),
+    };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * The PROD / MAIN / DEV / LOCAL dimension stamped on every product event as
+ * `product_analytics_environment`. One resolver for both emitting runtimes:
+ *
+ * - explicit pins win (`POSTHOG_ENVIRONMENT`, its `NEXT_PUBLIC_` twin, and the
+ *   Sentry environment vars the web app already sets);
+ * - the web/API runtime has `VERCEL_ENV` (+ the branch for MAIN-preview);
+ * - the Fly worker has NO `VERCEL_ENV` and `NODE_ENV=production` on BOTH apps,
+ *   so — mirroring `apps/worker/src/worker-env.ts` and the Langfuse resolver —
+ *   the Fly-injected app name is the ground truth (`-dev` marks the dev app; a
+ *   cross-env Doppler drift cannot fake it), then `FLY_ENVIRONMENT`;
+ * - everything else is LOCAL. `NODE_ENV=production` is deliberately NOT read as
+ *   PROD: it is the default for any built Node process, a local one included.
+ */
+export type ProductAnalyticsEnvironment = "PROD" | "MAIN" | "DEV" | "LOCAL";
+type EnvSource = Record<string, string | undefined>;
+export declare function resolveProductAnalyticsEnvironmentFromEnv(env?: EnvSource): ProductAnalyticsEnvironment;
+export {};

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

@@ -0,0 +1,46 @@
+function normalizeProductAnalyticsEnvironment(value) {
+    if (!value)
+        return null;
+    switch (value.trim().toUpperCase()) {
+        case "PROD":
+        case "PRODUCTION":
+            return "PROD";
+        case "MAIN":
+            return "MAIN";
+        case "DEV":
+        case "DEVELOPMENT":
+        case "PREVIEW":
+            return "DEV";
+        case "LOCAL":
+            return "LOCAL";
+        default:
+            return null;
+    }
+}
+export function resolveProductAnalyticsEnvironmentFromEnv(env = process.env) {
+    const explicit = normalizeProductAnalyticsEnvironment(env.POSTHOG_ENVIRONMENT
+        ?? env.NEXT_PUBLIC_POSTHOG_ENVIRONMENT
+        ?? env.SENTRY_ENVIRONMENT
+        ?? env.NEXT_PUBLIC_SENTRY_ENVIRONMENT);
+    if (explicit)
+        return explicit;
+    const vercelEnv = env.VERCEL_ENV ?? env.NEXT_PUBLIC_VERCEL_ENV;
+    if (vercelEnv === "production")
+        return "PROD";
+    const branch = env.VERCEL_GIT_COMMIT_REF ?? env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF;
+    if (vercelEnv === "preview" && branch === "main")
+        return "MAIN";
+    if (vercelEnv === "preview")
+        return "DEV";
+    if (vercelEnv === "development")
+        return "LOCAL";
+    const flyApp = (env.FLY_APP_NAME ?? env.FLY_APP)?.trim();
+    if (flyApp)
+        return flyApp.includes("-dev") ? "DEV" : "PROD";
+    const flyEnvironment = env.FLY_ENVIRONMENT?.trim().toLowerCase();
+    if (flyEnvironment === "production")
+        return "PROD";
+    if (flyEnvironment)
+        return "DEV";
+    return "LOCAL";
+}

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

@@ -0,0 +1,116 @@
+/**
+ * Every product-analytics event name OXYGEN emits, in one place — for BOTH
+ * emitting runtimes. The web/API runtime re-exports this from
+ * `apps/web/src/lib/analytics/event-names.ts` (which also owns PostHog's
+ * reserved `$mcp_*` vocabulary and the KPI-ledger translation); the Fly worker
+ * imports it directly.
+ *
+ * An event name is a contract shared by three things that cannot see each
+ * other: the emitter, its test, and the PostHog insight/funnel built on top. A
+ * literal typed at each call site drifts silently — the rename lands in the
+ * code, the dashboard keeps querying the old string, and the funnel reads zero
+ * without erroring. Import from here instead of typing the string.
+ *
+ * Names are unprefixed `subject_verb` snake_case; the web test pins the exact
+ * set, so adding one is a deliberate edit there too.
+ */
+export declare const PRODUCT_EVENTS: {
+    /** Acquisition. */
+    readonly USER_SIGNED_UP: "user_signed_up";
+    readonly WORKSPACE_CREATED: "workspace_created";
+    /** Activation. */
+    readonly ONBOARDING_COMPLETED: "onboarding_completed";
+    readonly ONBOARDING_RESET: "onboarding_reset";
+    readonly ACTIVATION_PATH_SELECTED: "activation_path_selected";
+    readonly AGENT_CONNECTED: "agent_connected";
+    readonly FIRST_RECORD_CREATED: "first_record_created";
+    /**
+     * The prescribed first play (inbound-led outbound), walked on ANY surface.
+     *
+     * These describe progress through a play, not a lifecycle moment — a founder
+     * who arms capture from the CLI and drafts the sequence in the browser
+     * produces one continuous series. Which is exactly why they are emitted from
+     * one watermark-guarded helper (apps/web `lib/activation/analytics.ts`)
+     * rather than from each surface: the same completed-step count read twice
+     * must emit once.
+     *
+     * Deliberately ABSENT from the web's KPI_TYPE_TO_EVENT. The headline
+     * activation KPI is CLI/MCP-sourced by design; wiring a web-observable play
+     * step into that ledger would silently redefine what the company reports as
+     * activation.
+     */
+    readonly FIRST_PLAY_STARTED: "first_play_started";
+    readonly FIRST_PLAY_STEP_COMPLETED: "first_play_step_completed";
+    readonly FIRST_PLAY_COMPLETED: "first_play_completed";
+    readonly FIRST_PLAY_SKIPPED: "first_play_skipped";
+    /**
+     * Usage — what was ASKED for. `mcp_tool_called` used to sit here as the
+     * second highest-volume event; it was REPLACED (not joined) by the reserved
+     * `$mcp_tool_call` in the web's MCP_ANALYTICS_EVENTS — see that block for why
+     * both cannot be emitted.
+     */
+    readonly CLI_COMMAND_RUN: "cli_command_run";
+    /**
+     * Outcomes — what actually HAPPENED, emitted by the Fly worker when a durable
+     * unit of work reaches a terminal state. `cli_command_run` and `$mcp_tool_call`
+     * see a run being requested; nothing on the web runtime ever sees it finish,
+     * because workflows, column runs, ingestions, agent runs and sequence steps
+     * complete on Fly minutes later. Without these, every "did it work" question
+     * (success rate, duration, credits per run, replies per enrollment) was
+     * unanswerable in PostHog and biased toward optimism — sweeps, repair passes
+     * and lease expiries settle runs invisibly.
+     *
+     * One event per terminal transition, `uuid` = the run/outbox id so a
+     * re-read after a worker restart dedupes, `timestamp` = when it settled.
+     * Properties are ids, enums and numbers only — never row values, prompts,
+     * or lead names (ADR 0021: PostHog stays sanitized).
+     */
+    readonly WORKFLOW_RUN_SETTLED: "workflow_run_settled";
+    readonly TABLE_ACTION_RUN_SETTLED: "table_action_run_settled";
+    readonly TABLE_INGESTION_RUN_SETTLED: "table_ingestion_run_settled";
+    readonly AGENT_RUN_SETTLED: "agent_run_settled";
+    readonly SEQUENCE_ENROLLMENT_SETTLED: "sequence_enrollment_settled";
+    /** Revenue lifecycle. */
+    readonly TRIAL_STARTED: "trial_started";
+    readonly SUBSCRIPTION_ACTIVATED: "subscription_activated";
+    readonly SUBSCRIPTION_CHURNED: "subscription_churned";
+    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";
+};
+export type ProductEventName = (typeof PRODUCT_EVENTS)[keyof typeof PRODUCT_EVENTS];
+/** Every name, for drift checks and dashboard provisioning. */
+export declare const PRODUCT_EVENT_NAMES: readonly ProductEventName[];
+/**
+ * The outcome events the worker emits, as a typed subset — so the worker's
+ * emitter cannot be handed a lifecycle event that only the control plane has
+ * the facts for.
+ */
+export declare const WORKER_RUN_OUTCOME_EVENTS: readonly ["workflow_run_settled", "table_action_run_settled", "table_ingestion_run_settled", "agent_run_settled", "sequence_enrollment_settled"];
+export type WorkerRunOutcomeEventName = (typeof WORKER_RUN_OUTCOME_EVENTS)[number];

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

@@ -0,0 +1,120 @@
+/**
+ * Every product-analytics event name OXYGEN emits, in one place — for BOTH
+ * emitting runtimes. The web/API runtime re-exports this from
+ * `apps/web/src/lib/analytics/event-names.ts` (which also owns PostHog's
+ * reserved `$mcp_*` vocabulary and the KPI-ledger translation); the Fly worker
+ * imports it directly.
+ *
+ * An event name is a contract shared by three things that cannot see each
+ * other: the emitter, its test, and the PostHog insight/funnel built on top. A
+ * literal typed at each call site drifts silently — the rename lands in the
+ * code, the dashboard keeps querying the old string, and the funnel reads zero
+ * without erroring. Import from here instead of typing the string.
+ *
+ * Names are unprefixed `subject_verb` snake_case; the web test pins the exact
+ * set, so adding one is a deliberate edit there too.
+ */
+export const PRODUCT_EVENTS = {
+    /** Acquisition. */
+    USER_SIGNED_UP: "user_signed_up",
+    WORKSPACE_CREATED: "workspace_created",
+    /** Activation. */
+    ONBOARDING_COMPLETED: "onboarding_completed",
+    ONBOARDING_RESET: "onboarding_reset",
+    ACTIVATION_PATH_SELECTED: "activation_path_selected",
+    AGENT_CONNECTED: "agent_connected",
+    FIRST_RECORD_CREATED: "first_record_created",
+    /**
+     * The prescribed first play (inbound-led outbound), walked on ANY surface.
+     *
+     * These describe progress through a play, not a lifecycle moment — a founder
+     * who arms capture from the CLI and drafts the sequence in the browser
+     * produces one continuous series. Which is exactly why they are emitted from
+     * one watermark-guarded helper (apps/web `lib/activation/analytics.ts`)
+     * rather than from each surface: the same completed-step count read twice
+     * must emit once.
+     *
+     * Deliberately ABSENT from the web's KPI_TYPE_TO_EVENT. The headline
+     * activation KPI is CLI/MCP-sourced by design; wiring a web-observable play
+     * step into that ledger would silently redefine what the company reports as
+     * activation.
+     */
+    FIRST_PLAY_STARTED: "first_play_started",
+    FIRST_PLAY_STEP_COMPLETED: "first_play_step_completed",
+    FIRST_PLAY_COMPLETED: "first_play_completed",
+    FIRST_PLAY_SKIPPED: "first_play_skipped",
+    /**
+     * Usage — what was ASKED for. `mcp_tool_called` used to sit here as the
+     * second highest-volume event; it was REPLACED (not joined) by the reserved
+     * `$mcp_tool_call` in the web's MCP_ANALYTICS_EVENTS — see that block for why
+     * both cannot be emitted.
+     */
+    CLI_COMMAND_RUN: "cli_command_run",
+    /**
+     * Outcomes — what actually HAPPENED, emitted by the Fly worker when a durable
+     * unit of work reaches a terminal state. `cli_command_run` and `$mcp_tool_call`
+     * see a run being requested; nothing on the web runtime ever sees it finish,
+     * because workflows, column runs, ingestions, agent runs and sequence steps
+     * complete on Fly minutes later. Without these, every "did it work" question
+     * (success rate, duration, credits per run, replies per enrollment) was
+     * unanswerable in PostHog and biased toward optimism — sweeps, repair passes
+     * and lease expiries settle runs invisibly.
+     *
+     * One event per terminal transition, `uuid` = the run/outbox id so a
+     * re-read after a worker restart dedupes, `timestamp` = when it settled.
+     * Properties are ids, enums and numbers only — never row values, prompts,
+     * or lead names (ADR 0021: PostHog stays sanitized).
+     */
+    WORKFLOW_RUN_SETTLED: "workflow_run_settled",
+    TABLE_ACTION_RUN_SETTLED: "table_action_run_settled",
+    TABLE_INGESTION_RUN_SETTLED: "table_ingestion_run_settled",
+    AGENT_RUN_SETTLED: "agent_run_settled",
+    SEQUENCE_ENROLLMENT_SETTLED: "sequence_enrollment_settled",
+    /** Revenue lifecycle. */
+    TRIAL_STARTED: "trial_started",
+    SUBSCRIPTION_ACTIVATED: "subscription_activated",
+    SUBSCRIPTION_CHURNED: "subscription_churned",
+    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",
+};
+/** Every name, for drift checks and dashboard provisioning. */
+export const PRODUCT_EVENT_NAMES = Object.freeze(Object.values(PRODUCT_EVENTS));
+/**
+ * The outcome events the worker emits, as a typed subset — so the worker's
+ * emitter cannot be handed a lifecycle event that only the control plane has
+ * the facts for.
+ */
+export const WORKER_RUN_OUTCOME_EVENTS = Object.freeze([
+    PRODUCT_EVENTS.WORKFLOW_RUN_SETTLED,
+    PRODUCT_EVENTS.TABLE_ACTION_RUN_SETTLED,
+    PRODUCT_EVENTS.TABLE_INGESTION_RUN_SETTLED,
+    PRODUCT_EVENTS.AGENT_RUN_SETTLED,
+    PRODUCT_EVENTS.SEQUENCE_ENROLLMENT_SETTLED,
+]);

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;