@oxygen-agent/cli 1.1014.136 → 1.1014.619

package/dist/commands/tags.d.ts

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

package/dist/commands/tags.js

@@ -0,0 +1,147 @@
+import { splitCommaList } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { TAG_COLORS } from "@oxygen/shared/select-options";
+import { TAG_KINDS_PROSE } from "@oxygen/shared/tags";
+import { Command } from "commander";
+/**
+ * Build the registry patch body. An omitted field keeps its stored value; an
+ * explicit null clears it — so a `--clear-*` flag must send null, and a flag the
+ * user did not pass must send nothing at all.
+ */
+function tagRegistryBody(options) {
+    const body = {};
+    const description = readOption(options.description);
+    if (options.clearDescription)
+        body.description = null;
+    else if (description !== undefined)
+        body.description = description;
+    const color = readOption(options.color);
+    if (options.clearColor)
+        body.color = null;
+    else if (color !== undefined)
+        body.color = color;
+    if (options.pinned && options.unpinned) {
+        throw new OxygenError("invalid_request", "Pass either --pinned or --unpinned, not both.", {
+            exitCode: 1,
+        });
+    }
+    if (options.pinned)
+        body.pinned = true;
+    else if (options.unpinned)
+        body.pinned = false;
+    return body;
+}
+export function registerTagsFamily(program, handleAsyncAction) {
+    program
+        .command("tags")
+        .description(`Workspace tags: one vocabulary across ${TAG_KINDS_PROSE}. Tags normalize to lowercase (trimmed, deduped, max 50 per item; any characters — nothing is slugified, so "Q3 Outbound" becomes "q3 outbound"). ATTACH with a carrier's own tag command (e.g. \`oxygen inbox tag\`, \`oxygen tables tag\`) or use \`oxygen tags attach <kind> <ref> --tags <labels>\` for Signal types, saved Dashboards, runtime Agents, and saved Ads searches. Then \`tags get <tag>\` returns every carrier with deep-links. CURATE the vocabulary here: \`tags create\` declares a tag (with a description, color, and pin) before anything carries it, \`tags update\` re-annotates one, and \`tags rename\`/\`merge\`/\`delete\` reshape it everywhere at once. Tags are free, inert metadata: attaching or removing one costs 0 credits, makes no provider call, and changes no sending, routing, or warm-up behaviour.`)
+        .addCommand(new Command("list")
+        .description("List every workspace tag with per-primitive counts, most-used first.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tags list", options, () => requestOxygen("/api/cli/tags"));
+    }))
+        .addCommand(new Command("get")
+        .description(`Everything carrying one tag — ${TAG_KINDS_PROSE} — each with its deep-link. In the result, ad_search_collection means a saved Ads search.`)
+        .argument("<tag>", "The tag (case-insensitive).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (tag, options) => {
+        await handleAsyncAction("tags get", options, () => 
+        // Explicit receivers retain the existing reserved-label read hints;
+        // they are customer reads, not aliases of the normal footprint.
+        requestOxygen(tag === "bulk" ? "/api/cli/tags/bulk"
+            : tag === "rename" ? "/api/cli/tags/rename"
+                : `/api/cli/tags/${encodeURIComponent(tag)}`));
+    }))
+        .addCommand(new Command("rename")
+        .description("Rename one tag EVERYWHERE it appears (every primitive, archived rows included). Preview-first: without --apply, prints per-kind would-change counts and mutates nothing. Idempotent — safe to re-run after a partial failure.")
+        .argument("<from>", "The current tag (case-insensitive).")
+        .argument("<to>", "The new tag (normalized lowercase).")
+        .option("--apply", "Execute the rename. Without this flag, returns a preview of the counts only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (from, to, options) => {
+        await handleAsyncAction("tags rename", options, () => requestOxygen("/api/cli/tags/rename", {
+            method: "POST",
+            body: { from, to, ...(options.apply ? { apply: true } : {}) },
+        }));
+    }))
+        .addCommand(new Command("create")
+        .description("Declare a tag before anything carries it, with an optional description, color, and pin. Idempotent: run it on a tag already in use to annotate it — carriers are never touched.")
+        .argument("<label>", "The tag (normalized to lowercase; spaces are kept, nothing is slugified).")
+        .option("--description <text>", "What this tag means in this workspace.")
+        .option("--color <color>", `Pill color. One of: ${TAG_COLORS.join(", ")}. Omit to derive it from the label.`)
+        .option("--pinned", "Pin it to the top of the tag list and the tag picker.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (label, options) => {
+        await handleAsyncAction("tags create", options, () => requestOxygen(`/api/cli/tags/${encodeURIComponent(label)}`, {
+            method: "POST",
+            body: tagRegistryBody(options),
+        }));
+    }))
+        .addCommand(new Command("update")
+        .description("Change a tag's description, color, or pin. Only the flags you pass change; use the --clear-* flags to remove a value. To change the LABEL use `tags rename`.")
+        .argument("<label>", "The tag (case-insensitive).")
+        .option("--description <text>", "Replace the description.")
+        .option("--clear-description", "Remove the description.")
+        .option("--color <color>", `Replace the color. One of: ${TAG_COLORS.join(", ")}.`)
+        .option("--clear-color", "Remove the color override and derive it from the label again.")
+        // NOT --no-pinned: Commander treats a declared --no-x as making x default
+        // to true, which would silently pin every tag created without a flag.
+        .option("--pinned", "Pin the tag.")
+        .option("--unpinned", "Unpin the tag.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (label, options) => {
+        await handleAsyncAction("tags update", options, () => requestOxygen(`/api/cli/tags/${encodeURIComponent(label)}`, {
+            method: "POST",
+            body: tagRegistryBody(options),
+        }));
+    }))
+        .addCommand(new Command("merge")
+        .description("Merge one or more tags into a single target, EVERYWHERE they appear (archived rows included). Preview-first: without --apply, prints per-kind and per-tag would-change counts and mutates nothing. Idempotent — safe to re-run after a partial failure.")
+        .argument("<from...>", "The tags to merge away (case-insensitive).")
+        .requiredOption("--into <tag>", "The surviving tag.")
+        .option("--apply", "Execute the merge. Without this flag, returns a preview of the counts only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (from, options) => {
+        await handleAsyncAction("tags merge", options, () => requestOxygen("/api/cli/tags/bulk", {
+            method: "POST",
+            body: {
+                action: "merge",
+                tags: from,
+                into: readOption(options.into) ?? "",
+                ...(options.apply ? { apply: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("delete")
+        .description("Delete one or more tags: strips them from EVERY carrier (archived and finished items included) and removes their declaration. IRREVERSIBLE. Preview-first: without --apply, prints per-kind and per-tag counts and mutates nothing. Counts can exceed what `tags list` shows, because the index hides archived items but the delete still cleans them.")
+        .argument("<tags...>", "The tags to delete (case-insensitive).")
+        .option("--apply", "Execute the delete. Without this flag, returns a preview of the counts only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (tags, options) => {
+        await handleAsyncAction("tags delete", options, () => requestOxygen("/api/cli/tags/bulk", {
+            method: "POST",
+            body: { action: "delete", tags, ...(options.apply ? { apply: true } : {}) },
+        }));
+    }))
+        .addCommand(new Command("attach")
+        .description("Replace tags on a Signal type, saved Dashboard, runtime Agent, or saved Ads search. [] clears the item; no provider call is made.")
+        .argument("<kind>", "signal_type, dashboard, agent, or ad_search_collection")
+        .argument("<ref>", "Signal type key, dashboard id/slug, Agent slug, or saved Ads search id")
+        .requiredOption("--tags <labels>", "Comma-separated complete tag list; an empty string clears it.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (kind, ref, options) => {
+        const body = { tags: splitCommaList(options.tags) };
+        await handleAsyncAction("tags attach", options, () => {
+            switch (kind) {
+                case "signal_type": return requestOxygen(`/api/cli/signals/registry/${encodeURIComponent(ref)}/tags`, { method: "POST", body });
+                case "dashboard": return requestOxygen(`/api/cli/dashboards/${encodeURIComponent(ref)}/tags`, { method: "POST", body });
+                case "agent": return requestOxygen(`/api/cli/agent/${encodeURIComponent(ref)}/tags`, { method: "POST", body });
+                case "ad_search_collection": return requestOxygen(`/api/cli/ads/searches/${encodeURIComponent(ref)}/tags`, { method: "POST", body });
+                default: throw new Error("kind must be signal_type, dashboard, agent, or ad_search_collection");
+            }
+        });
+    }));
+}

package/dist/commands/tools.d.ts

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

package/dist/commands/tools.js

@@ -0,0 +1,246 @@
+import { asPayloadRecord } from "../cli-output.js";
+import { parseJsonObject, readPositiveInt } from "../cli-values.js";
+import { readCsvOption, readNonNegativeNumber } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { createToolCatalogDetailCommand } from "../tool-catalog-detail-command.js";
+import { addToolCatalogSearchWindowFlag, readToolCatalogSearchWindow } from "../tool-catalog-search-window.js";
+import { readOption } from "../util.js";
+import { Command } from "commander";
+// A dry run's stdout envelope looks like a successful result — same shape, same
+// `ok: true` — so in a terminal the only tell that nothing was fetched was
+// `meta.mode` buried inside the payload. That is how a working provider key gets
+// reported as broken: the preview comes back empty and reads as a failed live
+// call. Mirror the server's preview banner on stderr, the same stdout/stderr
+// split the credits receipt uses, so the machine-read envelope stays clean.
+/**
+ * Say WHY a preview found nothing, before the preview itself.
+ *
+ * A dry run against a tool the workspace has no connection for comes back as a
+ * clean, successful-looking envelope whose refusal lives several levels down in
+ * `access.status`. Read top-down, that is indistinguishable from "this provider
+ * has nothing for you" — which is how a blind operator concluded a whole
+ * provider could never be reached. When the route states `would_execute: false`
+ * with a `blocked_by` list, put it on stderr in one line, next to the fix.
+ * Absent those fields nothing is printed, so every other tool run is unchanged.
+ */
+function writeToolRunBlockedNotice(data) {
+    const payload = asPayloadRecord(data);
+    if (!payload || payload.would_execute !== false)
+        return;
+    const blockedBy = Array.isArray(payload.blocked_by)
+        ? payload.blocked_by.filter((entry) => typeof entry === "string")
+        : [];
+    if (blockedBy.length === 0)
+        return;
+    const nextAction = typeof payload.next_action === "string" ? payload.next_action : null;
+    process.stderr.write(`Blocked: ${blockedBy.join(", ")}${nextAction ? ` — ${nextAction}` : ""}\n`);
+}
+// `tools search` composes optional catalog sources (composio, custom HTTP,
+// per-tool access checks) behind short timeouts; a timed-out source still
+// yields a success envelope, but `partial_sources` names what's missing and
+// `total_tools` can be silently understated (blind-eval finding: a cold cache
+// reported 1,640 of 7,222 tools). Mirror it to stderr so the undercount is
+// visible in a terminal without polluting the machine-read stdout envelope.
+function writePartialSourcesWarning(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const sources = data.partial_sources;
+    if (!Array.isArray(sources) || sources.length === 0)
+        return;
+    const names = sources.filter((source) => typeof source === "string").join(", ");
+    process.stderr.write(`warning: catalog sources incomplete (${names}) — totals may be understated; rerun in a few seconds for the complete catalog\n`);
+}
+// Distinct from a missing catalog source: the tool IS in the catalog, we just
+// could not determine whether this org may run it. Reported separately so a
+// flaky per-tool check never reads as "a whole vendor is missing".
+function writeAccessCheckFailuresWarning(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const failures = data.access_check_failures;
+    if (!Array.isArray(failures) || failures.length === 0)
+        return;
+    const names = failures.filter((entry) => typeof entry === "string");
+    const shown = names.slice(0, 3).join(", ");
+    const suffix = names.length > 3 ? ` and ${names.length - 3} more` : "";
+    process.stderr.write(`warning: availability unknown for ${names.length} tool(s) (${shown}${suffix}) — rerun 'oxygen tools check-access' for those ids\n`);
+}
+export function registerToolsFamily(program, handleAsyncAction) {
+    program
+        .command("tools")
+        .description("Find provider operations and OXYGEN columns. For one provider operation's effective price on this workspace's credential, use `tools get <tool_id> --view pricing --json`; for a request-specific quote at 0 credits and without a provider call, use `tools run <tool_id> --input-json '{}' --mode dry-run --json`. Use `tools search --for-table <table>` to price a table's enrichment columns per row.")
+        .addCommand(addToolCatalogSearchWindowFlag(new Command("search")
+        .description("Search provider operations and OXYGEN columns for 0 credits; the default list is bounded. Use `tools get <tool_id> --view pricing --json` for one workspace-effective fee, or `tools run <tool_id> --input-json '{}' --mode dry-run --json` for a 0-credit quote without a provider call. With --for-table, suggestions prices enrichments per row. If partial_sources appears, totals may be understated; rerun.")
+        .argument("[query]", "Search text, e.g. `web` for the Web Research Agent column and its modes (each priced in `modes`), or `email`.")
+        .option("--verbosity <verbosity>", "minimal, summary, or full. Defaults to minimal; hydrate one result with tools get.")
+        .option("--terse", "Alias for --verbosity minimal.")
+        .option("--all", "Return the complete matching catalog — with no query that is every provider operation (7,000+ rows). Explicit because the default is bounded to 10; with --for-table the table-scoped answer is `suggestions`, which --all does not change.")
+        .option("--only-runnable", "Only return tools runnable by the active organization.")
+        .option("--workflow-eligible", "Only return tools a hosted workflow step may call, each annotated with the canonical `workflow_effect` its manifest step must declare. This is a narrower set than the table-column catalog — use it when authoring a workflow manifest so lint cannot reject a tool at apply time.")
+        .option("--no-access-check", "Skip workspace availability checks for a fast catalog listing. Prices then show managed list estimates, not this workspace's effective credential fee; use tools get <tool_id> --view pricing for that. Pair with --terse for discovery sweeps.")
+        .option("--category <category>", "Filter by Oxygen tool category, such as company_search, people_search, research, or local.")
+        .option("--capability <tag>", "Filter by capability tag, such as mobile_phone.")
+        .option("--provider <provider>", "Filter to one exact provider id, such as blitzapi.")
+        .option("--limit <n>", "Maximum number of tools to return. Capped at 100.")
+        .option("--providers", "Also return a per-vendor summary (provider id, display name, tool count) alongside the tools.")
+        .option("--for-table <table>", "Table id or slug. Prices Oxygen's own column kinds, presets and waterfalls (native_columns) for that table's columns and lists deterministic suggestions first — what you can enrich here and what each costs per row, before adding anything. The envelope opens with `suggested` (each entry's price and exact add command), then `native_columns`; `tools` comes last and lists only provider operations a column can run, so leave --all off unless you want every one of them.")
+        .option("--favorites", "Only the catalog entries you favourited for this workspace (see tools favorite).")
+        .option("--table-runnable", "Only tools a table column can run.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (query, options) => {
+        await handleAsyncAction("tools search", options, async () => {
+            const params = new URLSearchParams();
+            params.set("query", query ?? "");
+            const window = readToolCatalogSearchWindow(options);
+            if (window.max_chars !== undefined)
+                params.set("max_chars", String(window.max_chars));
+            if (window.include_native !== undefined)
+                params.set("include_native", String(window.include_native));
+            const forTable = readOption(options.forTable);
+            if (forTable)
+                params.set("for_table", forTable);
+            if (options.favorites)
+                params.set("favorites", "true");
+            if (options.tableRunnable)
+                params.set("table_runnable", "true");
+            const verbosity = options.terse ? "minimal" : readOption(options.verbosity);
+            if (verbosity)
+                params.set("verbosity", verbosity);
+            if (options.all)
+                params.set("all", "true");
+            if (options.onlyRunnable)
+                params.set("only_runnable", "true");
+            if (options.workflowEligible)
+                params.set("workflow_eligible", "true");
+            if (options.accessCheck === false)
+                params.set("include_access", "false");
+            if (readOption(options.category))
+                params.set("category", readOption(options.category) ?? "");
+            if (readOption(options.capability))
+                params.set("capability", readOption(options.capability) ?? "");
+            if (readOption(options.provider))
+                params.set("provider", readOption(options.provider) ?? "");
+            if (options.providers)
+                params.set("include_providers", "true");
+            const limit = readPositiveInt(options.limit);
+            if (limit !== undefined)
+                params.set("limit", String(Math.min(limit, 100)));
+            const data = await requestOxygen(`/api/cli/tools/search?${params.toString()}`);
+            writePartialSourcesWarning(data);
+            writeAccessCheckFailuresWarning(data);
+            return data;
+        });
+    })))
+        .addCommand(createToolCatalogDetailCommand(handleAsyncAction))
+        .addCommand(new Command("favorite")
+        .description("Favourite one column-catalog entry for this workspace: a native column (find_email, preset:person_enrich, prompt:icp_fit_score_v1) or a vendor tool (tool:<tool_id>). Favourites lead every table's + Add column panel and `tools search --favorites`.")
+        .argument("<entry_id>", "Catalog entry id, e.g. find_email, preset:person_enrich, prompt:<key>, tool:<tool_id>.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (entryId, options) => {
+        await handleAsyncAction("tools favorite", options, () => requestOxygen("/api/cli/tools/favorites", {
+            method: "POST",
+            body: { entry_id: entryId, favorite: true },
+        }));
+    }))
+        .addCommand(new Command("unfavorite")
+        .description("Remove one column-catalog entry from your favourites for this workspace.")
+        .argument("<entry_id>", "Catalog entry id, as listed by tools favorites.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (entryId, options) => {
+        await handleAsyncAction("tools unfavorite", options, () => requestOxygen("/api/cli/tools/favorites", {
+            method: "POST",
+            body: { entry_id: entryId, favorite: false },
+        }));
+    }))
+        .addCommand(new Command("favorites")
+        .description("List your favourite column-catalog entries for this workspace, with each native entry's per-row price.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tools favorites", options, () => requestOxygen("/api/cli/tools/favorites"));
+    }))
+        .addCommand(new Command("enums")
+        .description("Provider enum catalogs for fields that accept normalized values.")
+        .addCommand(new Command("list")
+        .description("List enum catalogs for a provider (or all providers).")
+        .option("--provider <provider>", "Filter to a single provider, e.g. blitzapi.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tools enums list", options, () => {
+            const params = new URLSearchParams();
+            const provider = readOption(options.provider);
+            if (provider)
+                params.set("provider", provider);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/tools/enums${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("get")
+        .description("Fetch the accepted values for one provider enum catalog. Use this before drafting payloads with enumRef fields.")
+        .argument("<provider>", "Provider name, e.g. blitzapi.")
+        .argument("<enum_ref>", "Enum reference id, e.g. industry, employee_range, country_code.")
+        .option("-q, --query <query>", "Case-insensitive substring or token search across the catalog values.")
+        .option("--limit <limit>", "Maximum number of values to return. Defaults to 100. Maximum 1000.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (provider, enumRef, options) => {
+        await handleAsyncAction("tools enums get", options, () => {
+            const params = new URLSearchParams();
+            const query = readOption(options.query);
+            const limit = readOption(options.limit);
+            if (query)
+                params.set("q", query);
+            if (limit)
+                params.set("limit", limit);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/tools/enums/${encodeURIComponent(provider)}/${encodeURIComponent(enumRef)}${suffix ? `?${suffix}` : ""}`);
+        });
+    })))
+        .addCommand(new Command("run")
+        .description("Preview or run one tool. `--mode dry-run` quotes the exact inputs at 0 credits without a provider call or data write; `--mode live` executes after any required approval and credit ceiling.")
+        .argument("<tool_id>", "Tool id.")
+        .requiredOption("--input-json <json>", "Tool input as a JSON object.")
+        .option("--mode <mode>", "Execution mode: live or dry-run. Dry-run costs 0 credits and makes no provider call or data write; mutating tools default to dry-run.")
+        .option("--credential-mode <mode>", "Credential mode: managed, user_api_key, or user_oauth.")
+        .option("--org <organization_id>", "Optional organization id. Must match the stored CLI token.")
+        .option("--org-id <organization_id>", "Optional organization id. Must match the stored CLI token.")
+        .option("--connection-id <connection_id>", "Specific integration connection id. Defaults to the org's active default connection.")
+        .option("--fields <paths>", "Comma-separated response projection paths for large tool outputs.")
+        .option("--return <mode>", "Legacy response shape: raw, compact, or summary. Defaults to raw.")
+        .option("--return-mode <mode>", "Response shape: raw, compact, or summary. Prefer summary for large search responses.")
+        .option("--oxygen-cursor <cursor>", "Short Oxygen cursor returned as oxygen_next_cursor by a previous tool run.")
+        .option("--max-credits <n>", "Credit ceiling for live paid tools; not needed for no-bill tools. 0 runs no-bill operations, which may call providers, and reuses a managed lookup's cached result for the exact same input for free (the dry run's preview.cache says whether one exists). A paid cache miss at 0 calls and charges nothing.")
+        .option("--approved", "Required for live paid tools and external writes after inspecting dry-run output.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (toolId, options) => {
+        // Zero is a real ceiling here, not a typo: /api/cli/tools/run only
+        // demands a positive max_credits for BILLED tools, so a documented
+        // no-bill operation is legitimately run with --max-credits 0. The
+        // positive-only reader rejected that locally, before the request.
+        //
+        // Non-negative NUMBER, not readPositiveNumberOrZero (a whole seat
+        // count): this command's own dry-run hint prints "--max-credits
+        // 24.94", so an integer reader would refuse the very command the CLI
+        // just told the operator to run.
+        const maxCredits = readNonNegativeNumber(options.maxCredits);
+        await handleAsyncAction("tools run", options, async () => {
+            const data = await requestOxygen("/api/cli/tools/run", {
+                method: "POST",
+                body: {
+                    tool_id: toolId,
+                    input: parseJsonObject(options.inputJson),
+                    ...(readOption(options.mode) ? { mode: readOption(options.mode) } : {}),
+                    ...(readOption(options.credentialMode) ? { credential_mode: readOption(options.credentialMode) } : {}),
+                    ...(readOption(options.org) ? { org_id: readOption(options.org) } : {}),
+                    ...(readOption(options.orgId) ? { org_id: readOption(options.orgId) } : {}),
+                    ...(readOption(options.connectionId) ? { connection_id: readOption(options.connectionId) } : {}),
+                    ...(readOption(options.fields) ? { fields: readCsvOption(options.fields) } : {}),
+                    ...(readOption(options["return"]) ? { return: readOption(options["return"]) } : {}),
+                    ...(readOption(options.returnMode) ? { return_mode: readOption(options.returnMode) } : {}),
+                    ...(readOption(options.oxygenCursor) ? { oxygen_cursor: readOption(options.oxygenCursor) } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            });
+            writeToolRunBlockedNotice(data);
+            return data;
+        });
+    }));
+}

package/dist/commands/update.d.ts

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

package/dist/commands/update.js

@@ -0,0 +1,106 @@
+import { readAutoUpdateStatus, runBackgroundUpdate } from "../auto-update.js";
+import { emitCliFailure, writeJson } from "../cli-output.js";
+import { ansi, formatAutomaticSkillsInstallStatusLines } from "../command-support.js";
+import { runAutomaticSkillsInstall } from "../skills.js";
+import { updateCli } from "../update.js";
+import { OxygenError, success } from "@oxygen/shared/cli-result";
+import { Option } from "commander";
+import { stdout as output } from "node:process";
+async function handleUpdateAction(options) {
+    // The detached daily worker and the post-update skills refresh print nothing:
+    // their parent is gone, and the next run reports the outcome.
+    if (options.background) {
+        await runBackgroundUpdate().catch(() => undefined);
+        return;
+    }
+    if (options.refreshSkills) {
+        await runAutomaticSkillsInstall().catch(() => undefined);
+        return;
+    }
+    try {
+        const modes = [options.status, options.enableAuto, options.disableAuto].filter(Boolean).length;
+        if (modes > 1) {
+            throw new OxygenError("conflicting_flags", "Pass only one of --status, --enable-auto, or --disable-auto.", { exitCode: 2 });
+        }
+        if (modes === 1) {
+            const setting = options.enableAuto ? "on" : options.disableAuto ? "off" : undefined;
+            const status = await readAutoUpdateStatus(setting ? { setting, dryRun: options.dryRun === true } : {});
+            if (options.json) {
+                writeJson(success("update", status));
+                return;
+            }
+            process.stdout.write(formatAutoUpdateStatus(status));
+            return;
+        }
+        const result = await updateCli(options);
+        if (options.json) {
+            writeJson(success("update", result));
+            return;
+        }
+        process.stdout.write(formatUpdateSuccess(result));
+    }
+    catch (error) {
+        emitCliFailure("update", error);
+    }
+}
+function formatUpdateSuccess(result) {
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    return [
+        "",
+        `${styles.green("[OK]")} ${styles.bold(result.dry_run ? "CLI update command ready" : "CLI update completed")}`,
+        "",
+        `  ${styles.dim("Current")}     ${result.current_version}`,
+        `  ${styles.dim("Package")}     ${result.package}`,
+        `  ${styles.dim("Command")}     ${result.command}`,
+        "",
+        ...formatAutomaticSkillsInstallStatusLines(result.skills_install),
+    ].join("\n");
+}
+// skipcq: JS-C1002
+function formatAutoUpdateStatus(status) {
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    const auto = status.auto_update;
+    const latest = status.latest_version
+        ? `${status.latest_version}${status.update_available ? " (newer version available)" : " (up to date)"}`
+        : `unknown (${status.latest_error ?? "npm registry unreachable"})`;
+    const last = auto.last_result
+        ? `${auto.last_result.ok ? "updated" : "failed"} ${auto.last_result.from}${auto.last_result.to ? ` -> ${auto.last_result.to}` : ""} `
+            + `at ${auto.last_result.at}${auto.last_result.error ? ` (${auto.last_result.error})` : ""}`
+        : "none yet";
+    return [
+        "",
+        `${styles.bold(status.dry_run ? `Oxygen CLI updates (dry run: automatic updates would be turned ${auto.setting}; nothing saved)` : "Oxygen CLI updates")}`,
+        "",
+        `  ${styles.dim("Installed")}    ${status.current_version}`,
+        `  ${styles.dim("Latest (npm)")} ${latest}`,
+        `  ${styles.dim("Automatic")}    ${auto.active ? "on (checks daily; updates when the API requires it)" : auto.reason_text ?? "off"}`,
+        `  ${styles.dim("Last update")}  ${last}`,
+        "",
+        auto.active
+            ? `  Turn off: ${auto.disable}`
+            : `  Next step: ${auto.next_step ?? "oxygen update"}`,
+        "",
+    ].join("\n");
+}
+export function registerUpdateFamily(program, handleAsyncAction) {
+    program
+        .command("update")
+        .description("Update the Oxygen CLI from npm, then refresh the Oxygen agent skills in the global skill folders of "
+        + "Codex, Claude Code and Cursor (OXYGEN_SKIP_SKILLS=1 skips that). The CLI also keeps itself current: "
+        + "once a day it installs a newer release in the background, and when the API says it is too old it "
+        + "updates and re-runs your command. Automatic updates need a global npm install (npm install -g "
+        + "@oxygen-agent/cli); they are off for npx and project-local installs, under CI, for development builds, "
+        + "and after --disable-auto or OXYGEN_NO_AUTO_UPDATE=1.")
+        .option("--status", "Show the installed and newest published version and whether automatic updates are on.")
+        .option("--enable-auto", "Turn automatic updates on for this computer.")
+        .option("--disable-auto", "Turn automatic updates off for this computer, e.g. on a build server that must stay pinned.")
+        .option("--package <npm_spec>", "Install this npm spec instead of the latest, e.g. @oxygen-agent/cli@1.1010.721. To pin a build server, "
+        + "install the version you want and turn automatic updates off.")
+        .option("--dry-run", "Print the update command without running it; with --enable-auto or --disable-auto, show the result without saving it.")
+        .option("--json", "Print a JSON envelope.")
+        .addOption(new Option("--background", "Run the daily automatic update check.").hideHelp())
+        .addOption(new Option("--refresh-skills", "Refresh product skills after an automatic update.").hideHelp())
+        .action(async (options) => {
+        await handleUpdateAction(options);
+    });
+}

package/dist/commands/verify.d.ts

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

package/dist/commands/verify.js

@@ -0,0 +1,27 @@
+import { readPositiveNumber } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { Command } from "commander";
+export function registerVerifyFamily(program, handleAsyncAction) {
+    program
+        .command("verify")
+        .description("Check whether emails you already have are safe to send to. dry_run previews the provider chain for free; live spends and needs --max-credits.")
+        .addCommand(new Command("email")
+        .description("Verify one or more email addresses. MillionVerifier answers first; eligible catch-all (accept-all) addresses escalate to BounceBan when available. Returns valid / invalid / catch_all / unknown per address. If escalation cannot run, catch_all stays unconfirmed; escalation_unavailable_reason and next_action explain why. On the managed lane, Oxygen staff own dry provider balances, credential repair and hold release; workspace credits do not fix those blockers. A free preview reports an availability snapshot, not guaranteed live readiness. See https://oxygen-agent.com/docs/providers/email-verification and the oxygen-enrichment skill (`oxygen skills get oxygen-enrichment --file references/verification.md --json`).")
+        .argument("<emails...>", "One or more email addresses to verify.")
+        .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
+        .option("--approved", "Same as --mode live. Accepted because the global help footer names --approved as the way to authorize a credit-spending command.")
+        .option("--max-credits <credits>", "Spend ceiling for the whole run. Required for --mode live. The free dry_run returns estimate.recommended_max_credits, which covers the estimated maximum subject to live provider availability and eligibility; it is a ceiling, not a charge or a guaranteed verdict. Re-verifying the exact same address in this workspace replays MillionVerifier's first pass free for up to 30 days, so a repeat run can report credits_used 0 — catch-all escalation is never cached, and its reservation is released in full when that call returns no verdict.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (emails, options) => {
+        await handleAsyncAction("verify email", options, () => requestOxygen("/api/cli/verify/run", {
+            method: "POST",
+            body: {
+                emails,
+                mode: options.mode === "live" || options.approved === true ? "live" : "dry_run",
+                ...(readPositiveNumber(options.maxCredits) !== undefined
+                    ? { max_credits: readPositiveNumber(options.maxCredits) }
+                    : {}),
+            },
+        }));
+    }));
+}

package/dist/commands/viewers.d.ts

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