@oxygen-agent/cli 1.1011.1091 → 1.1013.15

package/node_modules/@oxygen/shared/dist/external-effect-arming.d.ts

@@ -0,0 +1,54 @@
+import { type DeployTier } from "./deploy-env.js";
+/**
+ * Which background EXTERNAL EFFECTS each deployment is armed to dispatch, declared
+ * here per environment rather than implied by whichever credentials a box holds.
+ *
+ * OXP-1.6.190 (classify-A P-05). Three background families write outside OXYGEN with
+ * no human in the loop: the off-session Stripe writes of `inbox_billing_reconcile`,
+ * the Zapmail writes of `mailbox_connection_repair`, and the dedicated-egress vendor
+ * release (IPRoyal `toggle-auto-extend`) of the egress order reconcile and lifecycle.
+ * Before this table their arming was implicit: present credentials meant armed.
+ *
+ * Chosen design (coordinator, 2026-10-07, "option 2"): every CURRENT default is kept, so
+ * dev billing reconcile, Zapmail repair and egress releases keep working for dev flows,
+ * but the state is now explicit, reviewable and read back, and two mismatches fail
+ * closed outside production-data environments: a LIVE Stripe key, and a vendor release
+ * whose family is not armed here. Production stays armed; nothing here changes a
+ * production default or touches a secret. A default-off posture outside production
+ * was considered and not chosen, because other dev workflows depend on these effects.
+ *
+ * Changing an entry is a reviewed code change. `OXYGEN_WORKER_MAILBOX_CONNECTION_REPAIR`
+ * remains the existing runtime kill switch for the repair family (`false` disarms it).
+ */
+export declare const EXTERNAL_EFFECT_FAMILIES: readonly ["inbox_billing_stripe", "mailbox_connection_repair", "egress_vendor_release"];
+export type ExternalEffectFamily = typeof EXTERNAL_EFFECT_FAMILIES[number];
+export type ExternalEffectArmingState = "armed" | "disarmed";
+/** The checked-in declaration, per deploy tier (see `resolveDeployEnv`). */
+export declare const EXTERNAL_EFFECT_ARMING: Readonly<Record<ExternalEffectFamily, Readonly<Record<DeployTier, ExternalEffectArmingState>>>>;
+export type ExternalEffectArming = {
+    family: ExternalEffectFamily;
+    armed: boolean;
+    declared: ExternalEffectArmingState;
+    /** `declaration` = the table above; `env` = the family's kill switch disarmed it. */
+    source: "declaration" | "env";
+    tier: DeployTier;
+    deploy_env: string;
+    production_data: boolean;
+};
+export declare function resolveExternalEffectArming(family: ExternalEffectFamily, env?: NodeJS.ProcessEnv): ExternalEffectArming;
+/** The readback: every family's effective gate for this process. */
+export declare function describeExternalEffectArming(env?: NodeJS.ProcessEnv): ExternalEffectArming[];
+/**
+ * Throw before an effect is dispatched when this process is not armed for it.
+ * Production-data environments keep their declared state; the refusal names the
+ * family and environment so a skipped effect is never silent.
+ */
+export declare function assertExternalEffectArmed(family: ExternalEffectFamily, env?: NodeJS.ProcessEnv): ExternalEffectArming;
+/** Live-mode Stripe secret or restricted key. Test keys (`sk_test_`/`rk_test_`) never match. */
+export declare function isLiveStripeKey(key: string | null | undefined): boolean;
+/**
+ * Fail closed when a process that does NOT hold production data is about to write to
+ * Stripe with a LIVE key: that is a dev or local box pointed at real money. The key is
+ * never echoed; only its mode is named.
+ */
+export declare function assertStripeKeyMatchesEnvironment(key: string | null | undefined, env?: NodeJS.ProcessEnv): void;

package/node_modules/@oxygen/shared/dist/external-effect-arming.js

@@ -0,0 +1,90 @@
+import { OxygenError } from "./cli-result.js";
+import { isProductionData, resolveDeployEnv } from "./deploy-env.js";
+/**
+ * Which background EXTERNAL EFFECTS each deployment is armed to dispatch, declared
+ * here per environment rather than implied by whichever credentials a box holds.
+ *
+ * OXP-1.6.190 (classify-A P-05). Three background families write outside OXYGEN with
+ * no human in the loop: the off-session Stripe writes of `inbox_billing_reconcile`,
+ * the Zapmail writes of `mailbox_connection_repair`, and the dedicated-egress vendor
+ * release (IPRoyal `toggle-auto-extend`) of the egress order reconcile and lifecycle.
+ * Before this table their arming was implicit: present credentials meant armed.
+ *
+ * Chosen design (coordinator, 2026-10-07, "option 2"): every CURRENT default is kept, so
+ * dev billing reconcile, Zapmail repair and egress releases keep working for dev flows,
+ * but the state is now explicit, reviewable and read back, and two mismatches fail
+ * closed outside production-data environments: a LIVE Stripe key, and a vendor release
+ * whose family is not armed here. Production stays armed; nothing here changes a
+ * production default or touches a secret. A default-off posture outside production
+ * was considered and not chosen, because other dev workflows depend on these effects.
+ *
+ * Changing an entry is a reviewed code change. `OXYGEN_WORKER_MAILBOX_CONNECTION_REPAIR`
+ * remains the existing runtime kill switch for the repair family (`false` disarms it).
+ */
+export const EXTERNAL_EFFECT_FAMILIES = [
+    "inbox_billing_stripe",
+    "mailbox_connection_repair",
+    "egress_vendor_release",
+];
+/** The checked-in declaration, per deploy tier (see `resolveDeployEnv`). */
+export const EXTERNAL_EFFECT_ARMING = {
+    inbox_billing_stripe: { prod: "armed", shadow: "armed", dev: "armed", local: "armed" },
+    mailbox_connection_repair: { prod: "armed", shadow: "armed", dev: "armed", local: "armed" },
+    egress_vendor_release: { prod: "armed", shadow: "armed", dev: "armed", local: "armed" },
+};
+/** Per-family runtime kill switch: an explicit false disarms, nothing arms beyond the declaration. */
+const KILL_SWITCH_ENV = {
+    mailbox_connection_repair: "OXYGEN_WORKER_MAILBOX_CONNECTION_REPAIR",
+};
+function killSwitchDisarms(family, env) {
+    const name = KILL_SWITCH_ENV[family];
+    const raw = name ? env[name]?.trim().toLowerCase() : undefined;
+    // Exactly the worker's readBooleanEnv falsy set, so the readback and the gate agree.
+    return raw === "false" || raw === "0" || raw === "no";
+}
+export function resolveExternalEffectArming(family, env = process.env) {
+    const deploy = resolveDeployEnv(env);
+    const declared = EXTERNAL_EFFECT_ARMING[family][deploy.tier];
+    const disarmedByEnv = declared === "armed" && killSwitchDisarms(family, env);
+    return {
+        family,
+        armed: declared === "armed" && !disarmedByEnv,
+        declared,
+        source: disarmedByEnv ? "env" : "declaration",
+        tier: deploy.tier,
+        deploy_env: deploy.label,
+        production_data: isProductionData(env),
+    };
+}
+/** The readback: every family's effective gate for this process. */
+export function describeExternalEffectArming(env = process.env) {
+    return EXTERNAL_EFFECT_FAMILIES.map((family) => resolveExternalEffectArming(family, env));
+}
+/**
+ * Throw before an effect is dispatched when this process is not armed for it.
+ * Production-data environments keep their declared state; the refusal names the
+ * family and environment so a skipped effect is never silent.
+ */
+export function assertExternalEffectArmed(family, env = process.env) {
+    const arming = resolveExternalEffectArming(family, env);
+    if (!arming.armed) {
+        throw new OxygenError("external_effect_not_armed", `${family} is not armed in ${arming.deploy_env} (${arming.source === "env" ? "disarmed by its kill switch" : "declared disarmed"}), so this external effect was not dispatched.`, { details: { family, deploy_env: arming.deploy_env, source: arming.source }, exitCode: 1 });
+    }
+    return arming;
+}
+/** Live-mode Stripe secret or restricted key. Test keys (`sk_test_`/`rk_test_`) never match. */
+export function isLiveStripeKey(key) {
+    const value = key?.trim() ?? "";
+    return value.startsWith("sk_live_") || value.startsWith("rk_live_");
+}
+/**
+ * Fail closed when a process that does NOT hold production data is about to write to
+ * Stripe with a LIVE key: that is a dev or local box pointed at real money. The key is
+ * never echoed; only its mode is named.
+ */
+export function assertStripeKeyMatchesEnvironment(key, env = process.env) {
+    if (!isLiveStripeKey(key) || isProductionData(env))
+        return;
+    const deploy = resolveDeployEnv(env);
+    throw new OxygenError("external_effect_environment_mismatch", `A live-mode Stripe key is configured in ${deploy.label}, which does not hold production data; refusing the Stripe write. Use a test-mode key outside production.`, { details: { family: "inbox_billing_stripe", deploy_env: deploy.label, key_mode: "live" }, exitCode: 1 });
+}

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

@@ -0,0 +1,264 @@
+export declare const GEO_ENGINES: readonly ["chatgpt", "gemini", "google-ai-mode", "google-ai-overview", "perplexity", "copilot", "claude"];
+export type GeoEngine = (typeof GEO_ENGINES)[number];
+export type GeoMarket = {
+    country: string;
+    language: string;
+};
+export type GeoCompetitor = {
+    name: string;
+    aliases: string[];
+    domains: string[];
+};
+export type GeoProject = GeoCompetitor & {
+    id: string;
+    icp: string;
+    engines: GeoEngine[];
+    markets: GeoMarket[];
+    repetitions: number;
+    schedule: "paused" | "daily" | "weekly";
+    next_run_at: string | null;
+    archived: boolean;
+};
+export type GeoPrompt = {
+    id: string;
+    text: string;
+    topic: string;
+    persona: string;
+    stage: string;
+    source: "hypothesis" | "research" | "customer";
+    evidence_id?: string;
+    enabled: boolean;
+    revision: number;
+};
+export type GeoCitation = {
+    url: string;
+    domain: string;
+    position: number;
+    category: "owned" | "competitor" | "community" | "review" | "editorial" | "other";
+};
+export type GeoMention = {
+    brand: string;
+    present: boolean;
+    evidence: string | null;
+    recommendation_rank: number | null;
+};
+export type GeoMeasurement = {
+    brand: GeoCompetitor;
+    competitors: GeoCompetitor[];
+};
+export type GeoAnswer = {
+    id: string;
+    run_id: string | null;
+    prompt_id: string | null;
+    prompt: string;
+    engine: GeoEngine;
+    provider: string;
+    collection: "consumer" | "import";
+    market: GeoMarket | null;
+    reported_market: GeoMarket | null;
+    captured_at: string;
+    text: string;
+    citations: GeoCitation[];
+    mentions: GeoMention[];
+    fan_out: string[];
+    outcome: "answer" | "no_overview";
+    cost_micros: number;
+    raw: unknown;
+    extraction_version: number;
+    measurement?: GeoMeasurement;
+    cost_basis?: "reported" | "reserved_estimate";
+    prompt_revision?: number;
+    topic?: string;
+};
+export type GeoExportPagination = {
+    returned: number;
+    total: number;
+    next_cursor: string | null;
+    summary_scope: "all_filtered_answers";
+};
+/** Binary exports carry this metadata to web, CLI and MCP, even for CSV/PDF. */
+export declare function readGeoExportPagination(headers: Pick<Headers, "get">): GeoExportPagination | undefined;
+export type GeoDocumentKind = "prompt" | "competitor" | "answer" | "evidence" | "opportunity" | "experiment" | "audit";
+export type GeoDocument = {
+    id: string;
+    project_id: string;
+    kind: GeoDocumentKind;
+    data: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+};
+export type GeoRunItem = {
+    id: string;
+    run_id: string;
+    project_id: string;
+    prompt: GeoPrompt;
+    brand: GeoCompetitor;
+    competitors: GeoCompetitor[];
+    engine: GeoEngine;
+    market: GeoMarket;
+    state: "queued" | "submitting" | "collecting" | "succeeded" | "failed" | "uncertain" | "cancelled";
+    provider_task_id: string | null;
+    provider: string;
+    reserved_micros: number;
+    cost_micros: number;
+    error: string | null;
+    attempt: number;
+    terminal_before_dispatch?: boolean;
+    submission_rejected?: boolean;
+    submission_cost_micros?: number | null;
+};
+export declare const GEO_PILOT_CAP_MICROS = 10000000;
+/** The initial release gate is independent of NODE_ENV and protects shadow data. */
+export declare function isGeoEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function assertGeoEnabled(env?: NodeJS.ProcessEnv): void;
+export declare function geoDomain(value: string): string | null;
+export declare function analyzeGeoAnswer(text: string, brand: GeoCompetitor, competitors: GeoCompetitor[], urls: string[]): {
+    mentions: GeoMention[];
+    citations: GeoCitation[];
+    measurement: GeoMeasurement;
+};
+/** Exact capture-time configuration, canonicalized for matched comparisons. */
+export declare function geoMeasurementKey(answer: Pick<GeoAnswer, "measurement">): string;
+/** A scraper's question heading is not answer prose, including old stored captures. */
+export declare function isGeoPromptEcho(text: string, prompt: string): boolean;
+export declare function isGeoControlledAnswer(answer: GeoAnswer): boolean;
+export declare function summarizeGeoAnswers(answers: GeoAnswer[], brand: string, failedSamples?: number): {
+    successful_samples: number;
+    measurement_contexts: number;
+    failed_samples: number;
+    invalid_answer_samples: number;
+    imported_samples: number;
+    no_overview_samples: number;
+    mentioned_samples: number;
+    visibility: number | null;
+    cited_samples: number;
+    citation_coverage: number | null;
+    share_of_voice: number | null;
+    competitors: {
+        name: string;
+        mentioned_samples: number;
+        share_of_voice: number | null;
+    }[];
+    sources: {
+        domain: string;
+        count: number;
+        category: string;
+        urls: string[];
+    }[];
+};
+/** No fetching or execution: customer wording and citations are evidence only. */
+export declare function parseGeoTranscript(input: string, redactions?: string[]): {
+    messages: {
+        role: "user" | "assistant";
+        text: string;
+    }[];
+    prompts: string[];
+    sources: string[];
+    redacted_text: string;
+};
+/** Compare only common collection cohorts; imports and missing AIOs are excluded. */
+export declare function compareGeoExperiment(before: GeoAnswer[], after: GeoAnswer[], brand: string): {
+    before: {
+        successful_samples: number;
+        measurement_contexts: number;
+        failed_samples: number;
+        invalid_answer_samples: number;
+        imported_samples: number;
+        no_overview_samples: number;
+        mentioned_samples: number;
+        visibility: number | null;
+        cited_samples: number;
+        citation_coverage: number | null;
+        share_of_voice: number | null;
+        competitors: {
+            name: string;
+            mentioned_samples: number;
+            share_of_voice: number | null;
+        }[];
+        sources: {
+            domain: string;
+            count: number;
+            category: string;
+            urls: string[];
+        }[];
+    };
+    after: {
+        successful_samples: number;
+        measurement_contexts: number;
+        failed_samples: number;
+        invalid_answer_samples: number;
+        imported_samples: number;
+        no_overview_samples: number;
+        mentioned_samples: number;
+        visibility: number | null;
+        cited_samples: number;
+        citation_coverage: number | null;
+        share_of_voice: number | null;
+        competitors: {
+            name: string;
+            mentioned_samples: number;
+            share_of_voice: number | null;
+        }[];
+        sources: {
+            domain: string;
+            count: number;
+            category: string;
+            urls: string[];
+        }[];
+    };
+    comparable_cohorts: number;
+    excluded_before: number;
+    excluded_after: number;
+    cohorts: {
+        cohort: any;
+        before: {
+            successful_samples: number;
+            measurement_contexts: number;
+            failed_samples: number;
+            invalid_answer_samples: number;
+            imported_samples: number;
+            no_overview_samples: number;
+            mentioned_samples: number;
+            visibility: number | null;
+            cited_samples: number;
+            citation_coverage: number | null;
+            share_of_voice: number | null;
+            competitors: {
+                name: string;
+                mentioned_samples: number;
+                share_of_voice: number | null;
+            }[];
+            sources: {
+                domain: string;
+                count: number;
+                category: string;
+                urls: string[];
+            }[];
+        };
+        after: {
+            successful_samples: number;
+            measurement_contexts: number;
+            failed_samples: number;
+            invalid_answer_samples: number;
+            imported_samples: number;
+            no_overview_samples: number;
+            mentioned_samples: number;
+            visibility: number | null;
+            cited_samples: number;
+            citation_coverage: number | null;
+            share_of_voice: number | null;
+            competitors: {
+                name: string;
+                mentioned_samples: number;
+                share_of_voice: number | null;
+            }[];
+            sources: {
+                domain: string;
+                count: number;
+                category: string;
+                urls: string[];
+            }[];
+        };
+    }[];
+    interpretation: string;
+};