@oxygen-agent/cli 1.1014.136 → 1.1014.619

package/dist/commands/action-column.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerActionColumnFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/action-column.js

@@ -0,0 +1,43 @@
+import { readCsvOption } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { Command } from "commander";
+export function registerActionColumnFamily(program, handleAsyncAction) {
+    program
+        .command("action-column")
+        .description("Workspace table action-column setup commands.")
+        .addCommand(new Command("add-provider")
+        .description("Add a catalog-backed provider action picker column to a workspace table.")
+        .argument("[table]", "Table id or slug.")
+        .requiredOption("--provider <provider>", "Provider id, such as attio.")
+        .option("--table <table>", "Table id or slug.")
+        .option("--label <label>", "Display label for the new column.")
+        .option("--key <key>", "Optional stable column key. Defaults to <provider>_actions.")
+        .option("--operation-filter <csv>", "Optional comma-separated operation, tool id, category, or tag filter.")
+        .option("--dry-run", "Preview the provider action column without creating it.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("action-column add-provider", options, () => {
+            const tableId = readOption(table) ?? readOption(options.table);
+            if (!tableId) {
+                throw new OxygenError("invalid_request", "Pass a table argument or --table <table>.", {
+                    exitCode: 1,
+                });
+            }
+            return requestOxygen("/api/cli/action-columns/provider", {
+                method: "POST",
+                body: {
+                    table: tableId,
+                    provider: options.provider,
+                    ...(readOption(options.label) ? { label: readOption(options.label) } : {}),
+                    ...(readOption(options.key) ? { key: readOption(options.key) } : {}),
+                    ...(readOption(options.operationFilter)
+                        ? { operation_filter: readCsvOption(options.operationFilter) }
+                        : {}),
+                    ...(options.dryRun ? { dry_run: true } : {}),
+                },
+            });
+        });
+    }));
+}

package/dist/commands/activation.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerActivationFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/activation.js

@@ -0,0 +1,24 @@
+import { requestOxygen } from "../http-client.js";
+import { Command } from "commander";
+export function registerActivationFamily(program, handleAsyncAction) {
+    const ACTIVATION_DESCRIPTION = "Where this workspace stands in the prescribed activation play (inbound-led outbound) and the ONE thing to do next: each step's state, what blocks a blocked one, the exact CLI / MCP tool / API call for the next step, and an honest pacing note — LinkedIn is read on a metered drip and a sender's warm-up ramp, not the size of your list, sets how fast anyone is contacted. Read-only, 0 credits. Read the play itself with `oxygen recipes list --stage day-1 --json`.";
+    // Bare `oxygen activation` is the spelling a founder guesses; `activation state`
+    // is the exact name discovery routes to (it is a gatewayCommand of the
+    // onboarding-and-copilot capability route). Both call the one read.
+    const activationCommand = program
+        .command("activation", { hidden: true })
+        // Backward-compatible exact invocation only. The fixed play is no longer a
+        // first-touch CLI surface; users choose motions in Recipes or Blueprints.
+        .description(ACTIVATION_DESCRIPTION)
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("activation state", options, () => requestOxygen("/api/cli/activation/state"));
+    });
+    activationCommand.addCommand(new Command("state")
+        .description(ACTIVATION_DESCRIPTION)
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        const outputOptions = { ...options, json: options.json || Boolean(activationCommand.opts().json) };
+        await handleAsyncAction("activation state", outputOptions, () => requestOxygen("/api/cli/activation/state"));
+    }), { hidden: true });
+}

package/dist/commands/admin.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerAdminFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler, binaryName: any): void;

package/dist/commands/admin.js

@@ -0,0 +1,347 @@
+import { renderPrimaryProviderBoard } from "../admin-primary-providers-render.js";
+import { emitCliFailure, emitSuccess } from "../cli-output.js";
+import { readPositiveInt } from "../cli-values.js";
+import { buildDirectoryProfileBody, readCsvOption, readPositiveInteger } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { AGENCY_DIRECTORY_REGIONS, AGENCY_DIRECTORY_SERVICES } from "@oxygen/shared/directory";
+import { Command, Option } from "commander";
+/** A --value for the pricing book: a number, true/false for a charge's active flag, or "none" for no plan limit. */
+function readPriceBookValue(raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = raw.trim();
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (value === "none" || value === "null")
+        return null;
+    const number = Number(value);
+    return value !== "" && Number.isFinite(number) ? number : value;
+}
+/**
+ * A signed, finite number (`--expected-divergence`). Unlike its positive and
+ * non-negative siblings the sign is the payload here — a negative divergence is
+ * the meter counter under-reading its own ledger — so only a non-finite value is
+ * rejected. Parsed client-side so a typo fails before a request that would
+ * otherwise reach a billing ledger is sent at all.
+ */
+function readSignedNumber(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed)) {
+        throw new OxygenError("invalid_number", "Expected a finite number.", {
+            details: { value },
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
+export function registerAdminFamily(program, handleAsyncAction, binaryName) {
+    program
+        .command("admin")
+        .description("Staff-only commands.")
+        .addCommand(new Command("kpis")
+        .description("Show the company conversion funnel (visitors → signups → activation on any surface, web, CLI or MCP → paid, with step rates and agent connected beside it), self-reported signup-channel attribution, new and positive-paid MRR/ARR, and paid churn separated from trial loss. OXYGEN staff only; workspace admin role alone does not grant access.")
+        .addOption(new Option("--range <range>", "Range for acquisition, the funnel's signup cohort, new revenue, and churn; current MRR/ARR and scheduled cancellations remain point-in-time.")
+        .choices(["7d", "30d", "90d"])
+        .default("30d"))
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin kpis", options, () => {
+            const range = readOption(options.range);
+            const suffix = range && range !== "30d" ? `?range=${encodeURIComponent(range)}` : "";
+            return requestOxygen(`/api/cli/admin/kpis${suffix}`);
+        });
+    }))
+        .addCommand(new Command("egress")
+        .description("Read-only Fly email-egress overview: shared IP, dedicated workspace apps and IPs, liveness, image drift, billing, and stuck orders. OXYGEN staff only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin egress", options, () => requestOxygen("/api/cli/admin/egress"));
+    }))
+        .addCommand(new Command("costs")
+        .description("Show provider costs (COGS) per workspace. Staff only.")
+        .option("--top <n>", "Limit number of workspace columns. Defaults to all.")
+        .option("--credential-mode <mode>", "managed (default; real COGS), byok (customer-supplied credentials), or all.", "managed")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin costs", options, () => {
+            const params = new URLSearchParams();
+            const top = readPositiveInt(options.top);
+            if (top)
+                params.set("top", String(top));
+            const credentialMode = readOption(options.credentialMode);
+            if (credentialMode && credentialMode !== "managed") {
+                params.set("credential_mode", credentialMode);
+            }
+            const suffix = params.toString() ? `?${params.toString()}` : "";
+            return requestOxygen(`/api/cli/admin/costs${suffix}`);
+        });
+    }))
+        .addCommand(new Command("price-book")
+        .description("The runtime prices charging reads from the control DB: recurring charges, plan allowances and scalars, each with its committed default and whether staff may edit it. An edit reaches every instance within 60 seconds. Staff only.")
+        .addCommand(new Command("list")
+        .description("List every pricing-book row with its stored value, what charging bills now, the committed default, and who reads it. Read-only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin price-book list", options, () => requestOxygen("/api/cli/admin/costs?section=pricing_book"));
+    }))
+        .addCommand(new Command("set")
+        .description("Set one editable pricing-book field. A charge takes --field credits or active; a plan takes monthly_credits, weekly_credits_limit or rollover_cap (value none for no limit); a scalar takes value. Rows charging does not read from the book are refused.")
+        .requiredOption("--table <table>", "charge, plan, or scalar.")
+        .requiredOption("--key <key>", "The row key, e.g. addon.egress_dedicated_ip, oxygen_499, markup.copilot_inference.")
+        .requiredOption("--field <field>", "credits | active (charge); monthly_credits | weekly_credits_limit | rollover_cap (plan); value (scalar).")
+        .requiredOption("--value <value>", "A non-negative number, true/false for active, or none for no plan limit.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin price-book set", options, () => requestOxygen("/api/cli/admin/costs", {
+            method: "POST",
+            body: {
+                price_table: options.table,
+                price_key: options.key,
+                price_field: options.field,
+                value: readPriceBookValue(options.value),
+            },
+        }));
+    }))
+        .addCommand(new Command("restore")
+        .description("Put a pricing-book row back to its committed default. For a plan, --field restores one allowance field; without it all three are restored.")
+        .requiredOption("--table <table>", "charge, plan, or scalar.")
+        .requiredOption("--key <key>", "The row key.")
+        .option("--field <field>", "Plan only: monthly_credits, weekly_credits_limit or rollover_cap.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin price-book restore", options, () => requestOxygen("/api/cli/admin/costs", {
+            method: "POST",
+            body: {
+                price_table: options.table,
+                price_key: options.key,
+                ...(options.field ? { price_field: options.field } : {}),
+                restore: true,
+            },
+        }));
+    })))
+        .addCommand(new Command("primary-providers")
+        .description("Provider board: primary managed data providers, inference, fallbacks, conditional companions and product services with default/conditional/legacy selection and required configuration. Per provider: health, 7d traffic, stored balance and wallet runway (not subscription quota), 30d/7d COGS, rate policy, spend ceilings, breaker, posture and snapshot freshness. Configured credentials prove neither health nor plan access. Reads stored snapshots without provider calls; --refresh re-runs zero-credit snapshots first. Staff only.")
+        .option("--refresh", "Re-run the zero-credit snapshot work the three crons run (provider health probes, managed balances, cost snapshot) before reading the board. No paid provider call and no credit spend; takes up to a few minutes.")
+        .option("--stages <csv>", "Limit --refresh to these stages: health, balances, costs. Defaults to all three.")
+        .option("--force", "Refresh even inside the server's cooldown on re-probing every managed vendor. Only with --refresh.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        const stages = readCsvOption(options.stages);
+        if (stages.length > 0 && !options.refresh) {
+            // Fail with the envelope rather than reading a board the caller
+            // believes it just refreshed.
+            emitCliFailure("admin primary-providers", new OxygenError("invalid_request", "--stages only applies to --refresh. Add --refresh to re-run those snapshots.", { exitCode: 2 }));
+            return;
+        }
+        if (options.force && !options.refresh) {
+            // Same reason as --stages: --force only relaxes the refresh
+            // cooldown, so on its own it reads the very board the caller
+            // believes it just forced a re-probe of.
+            emitCliFailure("admin primary-providers", new OxygenError("invalid_request", "--force only applies to --refresh. Add --refresh to re-run those snapshots.", { exitCode: 2 }));
+            return;
+        }
+        let failed = false;
+        const board = await requestOxygen("/api/cli/admin/primary-providers", options.refresh
+            ? {
+                method: "POST",
+                // The route budgets maxDuration = 300 and the balance stage
+                // walks every fetcher sequentially at 15s each, so the
+                // default 120s client budget aborts a refresh the server
+                // finishes — the operator reads a failure for work that
+                // succeeded and re-runs the outbound probes.
+                timeoutMs: 300_000,
+                body: {
+                    refresh: true,
+                    ...(stages.length > 0 ? { stages } : {}),
+                    ...(options.force ? { force: true } : {}),
+                },
+            }
+            : undefined).catch((error) => {
+            emitCliFailure("admin primary-providers", error);
+            failed = true;
+            return null;
+        });
+        // Only a transport failure ends the command silently; an empty
+        // payload still gets rendered (or enveloped) rather than exiting 0
+        // with nothing printed.
+        if (failed)
+            return;
+        if (options.json) {
+            emitSuccess("admin primary-providers", board, options);
+            return;
+        }
+        // Without this the default invocation printed ~1,500 lines of raw
+        // JSON while the MCP tool printed a worst-first summary of the same
+        // payload — same board, two different products.
+        process.stdout.write(`${renderPrimaryProviderBoard(board, { binary: binaryName })}\n`);
+    }))
+        .addCommand(new Command("spend")
+        .description("Global managed-provider spend limiter: burn, ceilings, breakers. Staff only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin spend", options, () => requestOxygen("/api/cli/admin/spend"));
+    })
+        .addCommand(new Command("set-limit")
+        .description("Set a ceiling for one scope + window. action=warn meters only; block arms it.")
+        .requiredOption("--scope <kind>", "global, category, provider, organization, or signature.")
+        .option("--key <key>", "Scope key: category/provider/org id, or * for the default.", "*")
+        .requiredOption("--window <seconds>", "Window: 60, 3600, or 86400.")
+        .option("--limit-usd <usd>", "Ceiling in USD of OXYGEN's own provider cost.")
+        .option("--limit-calls <n>", "Ceiling in call count: the signature loop detector, or the only ceiling that bounds a $0-priced provider.")
+        .option("--action <action>", "warn (meter + alert only) or block (enforce).", "warn")
+        .option("--notes <text>", "Why this ceiling is set where it is.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin spend set-limit", options, () => requestOxygen("/api/cli/admin/spend/limits", {
+            method: "POST",
+            body: {
+                scope_kind: readOption(options.scope),
+                scope_key: readOption(options.key) ?? "*",
+                window_seconds: Number(readOption(options.window)),
+                ...(readOption(options.limitUsd) ? { limit_usd: Number(readOption(options.limitUsd)) } : {}),
+                ...(readOption(options.limitCalls) ? { limit_calls: Number(readOption(options.limitCalls)) } : {}),
+                action: readOption(options.action) ?? "warn",
+                ...(readOption(options.notes) ? { notes: readOption(options.notes) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("halt")
+        .description("Force a breaker OPEN — the platform kill switch for managed provider spend. --scope managed_credit --key <provider> benches Oxygen's managed account for one provider (the same bench a vendor 402 opens).")
+        .option("--scope <kind>", "Scope kind to halt: global, category, provider, organization, signature, or managed_credit (key = provider id). Defaults to global.", "global")
+        .option("--key <key>", "Scope key. Defaults to * (everything in that scope). For --scope managed_credit, the provider id (serper, bounceban, ...).", "*")
+        .option("--reason <text>", "Why the halt was applied.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin spend halt", options, () => requestOxygen("/api/cli/admin/spend/breakers", {
+            method: "POST",
+            body: {
+                action: "force_open",
+                scope_kind: readOption(options.scope) ?? "global",
+                scope_key: readOption(options.key) ?? "*",
+                ...(readOption(options.reason) ? { reason: readOption(options.reason) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("resume")
+        .description("Close a breaker and clear its backoff, resuming managed provider spend. After funding a managed provider account, --scope managed_credit --key <provider> closes its credit bench fleet-wide instead of waiting out the window.")
+        .option("--scope <kind>", "Scope kind to resume: global, category, provider, organization, signature, or managed_credit (key = provider id). Defaults to global.", "global")
+        .option("--key <key>", "Scope key. Defaults to *. For --scope managed_credit, the provider id (serper, bounceban, ...).", "*")
+        .option("--reason <text>", "Why the breaker was reset.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin spend resume", options, () => requestOxygen("/api/cli/admin/spend/breakers", {
+            method: "POST",
+            body: {
+                action: "reset",
+                scope_kind: readOption(options.scope) ?? "global",
+                scope_key: readOption(options.key) ?? "*",
+                ...(readOption(options.reason) ? { reason: readOption(options.reason) } : {}),
+            },
+        }));
+    })))
+        .addCommand(new Command("directory")
+        .description("Curate the public agency directory (invite, prefill, delist). Staff only.")
+        .addCommand(new Command("list")
+        .description("List every agency directory listing across all organizations.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin directory list", options, () => requestOxygen("/api/cli/admin/directory"));
+    }))
+        .addCommand(new Command("enable")
+        .description("Invite an organization to the directory, optionally prefilling its profile.")
+        .argument("<organization>", "Organization id, slug, or Clerk org id.")
+        .option("--name <text>", "Agency display name (defaults to the organization name).")
+        .option("--slug <slug>", "Public URL slug (defaults to a slugified name).")
+        .option("--logo-url <url>", "Logo image URL.")
+        .option("--tagline <text>", "One-line pitch shown on the directory card.")
+        .option("--description <text>", "Full profile description (plain text; blank lines separate paragraphs).")
+        .option("--description-file <path>", "Path to a plain-text file with the description.")
+        .option("--website <url>", "Company website URL.")
+        .option("--company-linkedin <url>", "Company LinkedIn page URL.")
+        .option("--founders-json <json>", "JSON array of founding-team members: [{\"name\", \"title\", \"linkedin_url\"}].")
+        .option("--booking-url <url>", "Book-a-call URL (Cal.com, Calendly, ...).")
+        .option("--contact-email <email>", "Public contact email.")
+        .option("--services <csv>", `Comma-separated services from the curated set: ${AGENCY_DIRECTORY_SERVICES.join(", ")}.`)
+        .option("--regions <csv>", `Comma-separated regions from the curated set: ${AGENCY_DIRECTORY_REGIONS.join(", ")}.`)
+        .option("--featured", "Pin the listing to the top of the public directory.")
+        .option("--profile-json <json>", "JSON object with any listing fields; flags override it.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (organization, options) => {
+        await handleAsyncAction("admin directory enable", options, async () => {
+            const profile = await buildDirectoryProfileBody(options);
+            if (options.featured)
+                profile.featured = true;
+            return requestOxygen("/api/cli/admin/directory/enable", {
+                method: "POST",
+                body: { organization, profile },
+            });
+        });
+    }))
+        .addCommand(new Command("delist")
+        .description("Remove an organization's listing from the public directory (kill switch).")
+        .argument("<organization>", "Organization id, slug, or Clerk org id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (organization, options) => {
+        await handleAsyncAction("admin directory delist", options, () => requestOxygen("/api/cli/admin/directory/delist", {
+            method: "POST",
+            body: { organization },
+        }));
+    })))
+        .addCommand(new Command("automation-usage")
+        .description("Automation-actions meter integrity: the windows whose counter disagrees with their event ledger, and the audited adjustment that closes one. Staff only.")
+        .addCommand(new Command("divergences")
+        .description("List every automation-usage window whose counter and event ledger disagree, including windows that have outlived the detector's lookback and can only be cleared by a repair. Writes no state — but the scan IS the detector, so each call re-emits its aged-out divergence log event once per window that has outlived the lookback (tagged surface=cli, so operator reads stay separable from the 2-hourly cron's own emissions); the envelope reports what it emitted. Bounds default to the cron's; narrow them if the scan approaches its budget on a large estate.")
+        .option("--lookback-days <days>", "Narrow the recent-window scan to this many days back. Defaults to the detector's own lookback. The aged-out scan has no time floor either way, so no divergence can hide behind a shorter lookback.")
+        .option("--limit <windows>", "Cap the recent-window scan. Defaults to the detector's own cap. Truncation is reported as `truncated`, never silent.")
+        .option("--aged-out-limit <windows>", "Cap the aged-out scan, which is ordered oldest-first so a cap only ever drops the newest rows. Reported as `aged_out_truncated`.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin automation-usage divergences", options, () => {
+            const params = new URLSearchParams();
+            const lookbackDays = readPositiveInteger(options.lookbackDays);
+            const limit = readPositiveInteger(options.limit);
+            const agedOutLimit = readPositiveInteger(options.agedOutLimit);
+            if (lookbackDays !== undefined)
+                params.set("lookback_days", String(lookbackDays));
+            if (limit !== undefined)
+                params.set("limit", String(limit));
+            if (agedOutLimit !== undefined)
+                params.set("aged_out_limit", String(agedOutLimit));
+            const qs = params.toString() ? `?${params.toString()}` : "";
+            return requestOxygen(`/api/cli/admin/automation-usage${qs}`);
+        });
+    }))
+        .addCommand(new Command("reconcile")
+        .description("Write the one audited adjustment that closes a window's counter/ledger divergence. Deliberate by construction: it needs an actor (your staff identity), a reason, and the divergence you observed — the repair refuses if the live numbers have moved since, derives the delta itself, and replays a retry into the same single ledger row. The raise-only counter is never touched; the ledger is brought to meet it, which for a counter reading BELOW its ledger means appending a negative adjustment that writes those actions off the meter of record. The ledger is append-only: the entry cannot be removed afterwards, only offset by a further adjustment. Run `admin automation-usage divergences` first — that listing's `divergence` is the exact quantity this will append.")
+        .requiredOption("--organization <id>", "Organization id the divergence was reported for.")
+        .requiredOption("--window-start <iso>", "Exact period start of the divergent window, e.g. 2026-07-01T00:00:00Z. A rounded value matches no window rather than repairing a neighbouring one.")
+        .requiredOption("--expected-divergence <actions>", "The divergence you are repairing (counter - ledger), signed, straight from `admin automation-usage divergences`. Required so a repair computed off a stale alert aborts instead of writing the wrong delta.")
+        .requiredOption("--reason <text>", "Why this correction is being made. Recorded on the ledger event — no adjustment enters the books anonymously.")
+        .option("--incident-ref <ref>", "Incident this repairs, e.g. OXY-4100.")
+        .option("--idempotency-key <key>", "Pin the replay key. Defaults to (billing owner, window, divergence), which already makes a retry safe.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin automation-usage reconcile", options, () => {
+            const incidentRef = readOption(options.incidentRef);
+            const idempotencyKey = readOption(options.idempotencyKey);
+            return requestOxygen("/api/cli/admin/automation-usage", {
+                method: "POST",
+                body: {
+                    organization: readOption(options.organization),
+                    window_start: readOption(options.windowStart),
+                    expected_divergence: readSignedNumber(options.expectedDivergence),
+                    reason: readOption(options.reason),
+                    ...(incidentRef ? { incident_ref: incidentRef } : {}),
+                    ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
+                },
+            });
+        });
+    })));
+}

package/dist/commands/ads.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerAdsFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/ads.js

@@ -0,0 +1,62 @@
+import { splitCommaList } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { Command } from "commander";
+export function registerAdsFamily(program, handleAsyncAction) {
+    program
+        .command("ads")
+        .description("Saved Ads intelligence searches. Saving or tagging a query costs nothing; run its platform and query through the matching adyntel.* tool with the normal preview and credit gate.")
+        .addCommand(new Command("searches")
+        .description("Save reusable Ads queries for 0 credits. Saving never runs a provider search. Example: oxygen ads searches save --name 'Competitor ads' --platform facebook_ads --company-domain acme.com --tags competitor-watch.")
+        .addCommand(new Command("list")
+        .description("List saved Ads search definitions, optionally filtered by tag.")
+        .option("--tag <label>", "Only saved searches carrying this tag.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("ads searches list", options, () => requestOxygen(`/api/cli/ads/searches${options.tag ? `?tag=${encodeURIComponent(options.tag)}` : ""}`));
+    }))
+        .addCommand(new Command("get")
+        .description("Read one saved Ads search definition without running it.")
+        .argument("<id>")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("ads searches get", options, () => requestOxygen(`/api/cli/ads/searches/${encodeURIComponent(id)}`));
+    }))
+        .addCommand(new Command("save")
+        .alias("create")
+        .description("Save a named Ads search query for 0 credits; no provider call.")
+        .requiredOption("--name <name>", "Name for the saved search.")
+        .requiredOption("--platform <platform>", "Domain: facebook_ads, google_ads, linkedin_ads (use --company-domain). Keyword: facebook_ad_search, linkedin_keyword_search, tiktok_search (use --keyword).")
+        .option("--company-domain <domain>", "Required for facebook_ads, google_ads, and linkedin_ads; e.g. acme.com.")
+        .option("--keyword <keyword>", "Required for facebook_ad_search, linkedin_keyword_search, and tiktok_search.")
+        .option("--country-code <code>", "Optional two-letter country code, e.g. US.")
+        .option("--tags <labels>", "Comma-separated workspace tags.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("ads searches save", options, () => requestOxygen("/api/cli/ads/searches", { method: "POST", body: {
+                name: options.name, platform: options.platform, company_domain: options.companyDomain,
+                keyword: options.keyword, country_code: options.countryCode, tags: splitCommaList(options.tags),
+            } }));
+    }))
+        .addCommand(new Command("update")
+        .description("Replace a saved search's name or query; keep its tags. No provider call.")
+        .argument("<id>")
+        .requiredOption("--name <name>", "Name for the saved search.")
+        .requiredOption("--platform <platform>", "Domain: facebook_ads, google_ads, linkedin_ads (use --company-domain). Keyword: facebook_ad_search, linkedin_keyword_search, tiktok_search (use --keyword).")
+        .option("--company-domain <domain>", "Required for facebook_ads, google_ads, and linkedin_ads; e.g. acme.com.")
+        .option("--keyword <keyword>", "Required for facebook_ad_search, linkedin_keyword_search, and tiktok_search.")
+        .option("--country-code <code>", "Optional two-letter country code, e.g. US.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("ads searches update", options, () => requestOxygen(`/api/cli/ads/searches/${encodeURIComponent(id)}`, { method: "PATCH", body: {
+                name: options.name, platform: options.platform, company_domain: options.companyDomain,
+                keyword: options.keyword, country_code: options.countryCode,
+            } }));
+    }))
+        .addCommand(new Command("delete")
+        .description("Archive a saved search; hide it from lists and tag footprints.")
+        .argument("<id>")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("ads searches delete", options, () => requestOxygen(`/api/cli/ads/searches/${encodeURIComponent(id)}`, { method: "DELETE" }));
+    })));
+}

package/dist/commands/agent.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerAgentFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;