@oxygen-agent/cli 1.987.20 → 1.1010.1

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.987.20
+Version: 1.1010.1

package/dist/admin-primary-providers-render.d.ts

@@ -1,5 +1,3 @@
-/** Age of an ISO stamp as a short human span, measured against `now`. */
-export declare function ago(iso: unknown, now?: Date): string;
 export type RenderOptions = {
     /** Binary name to print inside suggested commands. */
     binary?: string;

package/dist/admin-primary-providers-render.js

@@ -47,7 +47,7 @@ function pct(value) {
     return `${Math.round(parsed * 100)}%`;
 }
 /** Age of an ISO stamp as a short human span, measured against `now`. */
-export function ago(iso, now = new Date()) {
+function ago(iso, now = new Date()) {
     const raw = str(iso);
     if (!raw)
         return "never";

package/dist/browser-login.js

@@ -2,7 +2,7 @@ import { execFileSync } from "node:child_process";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import { hostname } from "node:os";
-import { OXYGEN_VERSION, OxygenError, deriveCliLoginConfirmationCode } from "@oxygen/shared";
+import { OXYGEN_VERSION, OxygenError, deriveCliLoginConfirmationCode, sleep } from "@oxygen/shared";
 import { requestOxygen } from "./http-client.js";
 import { readErrorMessage } from "./util.js";
 const CALLBACK_HOST = "127.0.0.1";
@@ -133,9 +133,6 @@ function safeHostname() {
         return undefined;
     }
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
 export async function createBrowserLoginSession(apiUrl) {
     const state = randomBytes(32).toString("base64url");
     let settled = false;

package/dist/column-decision-options.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `columns add` classification flags: `--classify <labels>`, `--yes-no <question>`
+ * and `--score <levels>` author an AI column answered by System One
+ * (`definition.decision`). The server validates the shape; this only turns the
+ * flags into it and refuses combinations that would author something else.
+ */
+export type ColumnDecisionFlagOptions = {
+    classify?: string;
+    yesNo?: string;
+    score?: string;
+    minConfidence?: string;
+    grounding?: string;
+};
+export type ColumnDecisionFlags = {
+    /** The question, when `--yes-no` carried it; `--classify` and `--score` take `--prompt`. */
+    question: string | null;
+    decision: Record<string, unknown>;
+};
+/** Null when no classification flag was passed. */
+export declare function readColumnDecisionFlags(options: ColumnDecisionFlagOptions): ColumnDecisionFlags | null;

package/dist/column-decision-options.js

@@ -0,0 +1,54 @@
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { COLUMN_DECISION_GROUNDINGS, } from "@oxygen/shared/column-decision";
+function readFlag(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function splitList(value) {
+    return value.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
+function invalid(message) {
+    return new OxygenError("invalid_request", message, { exitCode: 1 });
+}
+/** Null when no classification flag was passed. */
+export function readColumnDecisionFlags(options) {
+    const classify = readFlag(options.classify);
+    const yesNo = readFlag(options.yesNo);
+    const scoreLevels = readFlag(options.score);
+    const chosen = [classify ? "--classify" : null, yesNo ? "--yes-no" : null, scoreLevels ? "--score" : null]
+        .filter((flag) => flag !== null);
+    const minConfidenceRaw = readFlag(options.minConfidence);
+    const groundingRaw = readFlag(options.grounding);
+    if (chosen.length === 0) {
+        if (minConfidenceRaw || groundingRaw) {
+            throw invalid("--min-confidence and --grounding apply to a classification column: add --classify, --yes-no or --score.");
+        }
+        return null;
+    }
+    if (chosen.length > 1) {
+        throw invalid(`A classification column has one mode: pass one of ${chosen.join(", ")}, not several.`);
+    }
+    const mode = classify ? "labels" : yesNo ? "yes_no" : "score";
+    const decision = { engine: "system_one", mode };
+    if (classify)
+        decision.labels = splitList(classify);
+    if (scoreLevels)
+        decision.levels = splitList(scoreLevels);
+    if (minConfidenceRaw) {
+        const value = Number(minConfidenceRaw);
+        if (!Number.isFinite(value)) {
+            throw invalid(`--min-confidence must be a number from 0 to 1, e.g. 0.8 (got ${minConfidenceRaw}).`);
+        }
+        decision.minConfidence = value;
+    }
+    if (groundingRaw) {
+        const grounding = groundingRaw.toLowerCase();
+        if (!COLUMN_DECISION_GROUNDINGS.includes(grounding)) {
+            throw invalid(`--grounding must be ${COLUMN_DECISION_GROUNDINGS.join(" or ")} (got ${groundingRaw}).`);
+        }
+        decision.grounding = grounding;
+    }
+    return { question: yesNo, decision };
+}

package/dist/command-manifest.d.ts

@@ -1,10 +1,10 @@
 import type { Command } from "commander";
-export type CommandManifestFlag = {
+type CommandManifestFlag = {
     flags: string;
     description: string;
     required: boolean;
 };
-export type CommandManifestArgument = {
+type CommandManifestArgument = {
     name: string;
     required: boolean;
     description: string;
@@ -46,3 +46,4 @@ export declare function getCommandManifestEntry(manifest: CommandManifest, exact
     invoke: string;
 }) | null;
 export declare function suggestCommandNames(manifest: CommandManifest, query: string, limit?: number): string[];
+export {};

package/dist/command-manifest.js

@@ -26,6 +26,10 @@ const COMMAND_SEARCH_STOP_WORDS = new Set([
 // advertised the most consequential collaboration write as a read.
 const MUTATING_VERBS = new Set([
     "brand-approve", "revoke-invite", "confirm",
+    // Exact leaf: `ugc creators set-target` writes one creator's posting deal.
+    "set-target",
+    // `ugc creators decline` settles an application for good.
+    "decline",
     "accept", "ack", "add", "adopt", "apply", "approve", "archive",
     "assign", "attach",
     // `linkedin intent autoenroll` arms (or revokes) a STANDING grant to contact
@@ -37,6 +41,16 @@ const MUTATING_VERBS = new Set([
     // recurring write, and --run can connect newly eligible mailboxes immediately.
     "auto-enroll",
     "backfill",
+    // `dashboards widgets refresh` calls a provider and bills the workspace. It is
+    // currently the only `refresh` leaf; the default (mutates:false) would
+    // advertise the one dashboard command that spends money as a read, to every
+    // agent and in the public CLI reference.
+    "refresh",
+    // Exact hyphenated leaf, because the `backfill` entry above matches the whole
+    // leaf token and never `crm-backfill`. `suppressions crm-backfill --live`
+    // creates CRM person records for everyone on the do-not-contact list, so the
+    // default (mutates:false) would advertise a bulk workspace write as a read.
+    "crm-backfill",
     // A noun leaf, so the default would advertise `projects color` — a tenant
     // write — to every agent as a read. `decide` is the same case.
     "color",
@@ -54,7 +68,7 @@ const MUTATING_VERBS = new Set([
     // `support chat` starts or continues a customer-authored Plain Thread. The
     // conversational noun is still a real external write.
     "buy", "call", "cancel", "chat", "chat-action", "claim", "clear",
-    "comment", "configure", "connect", "create", "decide", "delete", "delist", "disable",
+    "comment", "configure", "connect", "create", "decide", "delete", "delete-message", "delist", "disable",
     "disconnect", "dispatch", "done", "draft", "duplicate", "edit", "emit", "enable", "enroll",
     // Exact leaf, not a `field` prefix: `support admin field-set` writes a Plain
     // Thread field, while a future `field-get` would be a read.
@@ -63,7 +77,7 @@ const MUTATING_VERBS = new Set([
     "label-add", "label-remove", "launch", "log", "login", "logout", "mark-all-read", "mark-read", "materialize", "merge",
     "migrate",
     "move", "note", "off", "onboard", "order", "pause", "pin", "priority", "provision",
-    "publish", "purchase", "purge", "push", "react", "reconcile", "record", "recover-pending",
+    "publish", "purchase", "purge", "push", "react", "reactivate", "reconcile", "record", "recover-pending",
     "recover-capacity", "register", "reject", "relink", "remove", "rename", "reorder", "reply", "request",
     "replay", "rerun", "rescan", "resend", "reset", "resolve", "restore", "resume",
     "retry", "retype", "revoke", "rotate", "run", "save", "schedule",
@@ -82,11 +96,19 @@ const MUTATING_VERBS = new Set([
 const MUTATING_COMMANDS = new Set([
     "mailboxes warmup status",
     "mailboxes warmup reconnect",
+    // A noun leaf with its own action (not a group), so the default would
+    // advertise a STANDING per-viewer paid-enrichment toggle as a read. `enrichment`
+    // itself is not a MUTATING_VERBS entry because the other two `enrichment`
+    // leaves in this file (`crm enrichment`, `enrichment` catalogue) are groups
+    // whose own subcommands (list/set/enable/disable/backfill, catalog/entries)
+    // already carry their own correctly-classified verbs.
+    "viewers enrichment",
 ]);
 // `--approved` usually identifies a paid or externally mutating execution
 // mode, but a small number of approved operations are explicitly
 // zero-credit. Keep those exceptions exact so discovery never invents spend.
 const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
+    "inbox delete-message",
     "tables watcher preview",
     "knowledge repositories connect",
     "knowledge repositories resolve",
@@ -132,6 +154,7 @@ const READ_ONLY_COMMANDS = new Set([
 // invocation still previews, so machine-readable discovery must not imply that
 // calling the command without its confirmation flag writes anything.
 const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
+    "inbox delete-message",
     "tables watcher preview",
     "ugc creators invite",
     "ugc creators send-invite",

package/dist/credentials.d.ts

@@ -34,7 +34,7 @@ export declare function defaultApiUrl(env?: NodeJS.ProcessEnv): string;
  * look identical, and a drifted profile turns a prod-labelled binary into a report
  * about dev that reads as a production outage (OXY-4091).
  */
-export type CliEndpointContext = {
+type CliEndpointContext = {
     apiUrl: string;
     /** Active profile name, or null when no named profile supplied the credentials. */
     profile: string | null;

package/dist/functions-commands.js

@@ -3,10 +3,10 @@ import { parseJsonObject } from "./cli-values.js";
 import { requestOxygen } from "./http-client.js";
 export function registerFunctionsCommands(program, handle) {
     const functions = program.command("functions")
-        .description("Browse OXYGEN's ready-made Functions (work email, mobile phone, company funding stage, ...), favourite them, bind them to a table, or create, edit and publish your own Functions backed by ordinary Tables.")
-        .addHelpText("after", "\nOXYGEN-managed Functions are pre-built and priced: `functions list --managed` shows each one with its per-row credit estimate before you attach it. Attaching (`functions bind`) is free; only `columns run` spends, after a dry run. A managed Function is read-only; `functions duplicate <function>` gives you an editable copy.\nDraft edits are isolated. Publishing updates future invocations of every caller; queued, in-flight and past runs retain their captured version. Existing caller caps never increase automatically.\nFlow: draft → describe → publish → bind → columns run --dry-run → approved run → runs.\nA bound Function executes on its own published execution table and writes named outputs back to the calling table. The call stays visible from the caller: `table-runs list --table <caller> --status all` lists the run, and the binding column's cell holds the outcome (status, outputs, credits, invocation and run ids). Address a Function by id, slug, or the display name shown by `functions list`.\nWorked example with commands: `oxygen skills install --skill oxygen-gtm --project`, then read its recipes/callable-tables.md.\n");
-    functions.command("list").description("List the Function library: OXYGEN-managed Functions with their per-row credit estimate, plus your workspace's own drafts and published Functions (up to 500).")
-        .option("--managed", "Only OXYGEN-managed Functions (pre-built, priced, read-only; duplicate to customize).")
+        .description("Create, publish and reuse your workspace's Functions backed by ordinary Tables.")
+        .addHelpText("after", "\n`functions list` shows your workspace's drafts and published Functions with per-row credit estimates. Attaching (`functions bind`) is free; only `columns run` spends, after a dry run. Use `functions duplicate <function>` to start an editable copy.\nDraft edits are isolated. Publishing updates future invocations of every caller; queued, in-flight and past runs retain their captured version. Existing caller caps never increase automatically.\nFlow: draft → describe → publish → bind → columns run --dry-run → approved run → runs.\nA bound Function executes on its own published execution table and writes named outputs back to the calling table. The call stays visible from the caller: `table-runs list --table <caller> --status all` lists the run, and the binding column's cell holds the outcome (status, outputs, credits, invocation and run ids). Address a Function by id, slug, or the display name shown by `functions list`.\nWorked example with commands: `oxygen skills install --skill oxygen-gtm --project`, then read its recipes/callable-tables.md.\n");
+    functions.command("list").description("List your workspace's drafts and published Functions with per-row credit estimates (up to 500).")
+        .option("--managed", "Retired compatibility filter; returns an empty list. Use the workspace library without this flag.")
         .option("--favorites", "Only the Functions you favourited (`functions favorite <function>`).")
         .option("--json", "Print a JSON envelope.")
         .action((options) => handle("functions list", options, () => {
@@ -20,11 +20,11 @@ export function registerFunctionsCommands(program, handle) {
             .option("--json", "Print a JSON envelope.")
             .action((ref, options) => handle(`functions ${command}`, options, () => requestOxygen("/api/cli/functions", { method: "POST", body: { operation: command, function: ref } })));
     }
-    functions.command("duplicate <function>").description("Copy a Function's steps into a new editable draft of your own (same inputs and outputs, no rows). The way to customize an OXYGEN-managed Function.")
+    functions.command("duplicate <function>").description("Copy a Function's steps into a new editable draft (same inputs and outputs, no rows).")
         .option("--name <name>", "Display name for the copy. Defaults to '<source> (copy)'.")
         .option("--json", "Print a JSON envelope.")
         .action((ref, options) => handle("functions duplicate", options, () => requestOxygen("/api/cli/functions", { method: "POST", body: { operation: "duplicate", function: ref, ...(options.name ? { display_name: options.name } : {}) } })));
-    functions.command("describe <function>").description("Inspect a Function's inputs, outputs, steps, per-row credit estimate, caps, and whether it is OXYGEN-managed or your own draft/published version.")
+    functions.command("describe <function>").description("Inspect a Function's inputs, outputs, steps, per-row credit estimate, caps, and draft or published version.")
         .option("--json", "Print a JSON envelope.")
         .action((ref, options) => handle("functions describe", options, () => requestOxygen(`/api/cli/functions?${new URLSearchParams({ function: ref })}`)));
     functions.command("draft [function]").description("Create a Function draft, or save an existing Function's draft; executes nothing.")
@@ -47,13 +47,17 @@ export function registerFunctionsCommands(program, handle) {
     functions.command("rename <function> <name>").description("Rename a Function while preserving its identity, callers and published execution.")
         .option("--json", "Print a JSON envelope.")
         .action((ref, name, options) => handle("functions rename", options, () => requestOxygen("/api/cli/functions", { method: "POST", body: { operation: "rename", function: ref, display_name: name } })));
-    functions.command("delete <function>").description("Preview removal from the Function library; preserves backing tables, rows and run history. Connected callers or active runs block deletion.")
-        .addHelpText("after", "\nDeletion is final: there is no restore, unlike `tables delete`. To reuse the logic, `tables duplicate` the backing Table and draft a new Function from the copy.\n")
+    functions.command("delete <function>").description("Preview removal from the Function library, then remove it with --yes; preserves backing tables, rows and run history. Connected callers or active runs block deletion.")
+        .addHelpText("after", "\nDeleting your own Function is final: there is no restore, unlike `tables delete`. To reuse the logic, `tables duplicate` the backing Table and draft a new Function from the copy.\n")
         .option("--yes", "Confirm removal of this Function after reviewing its callers.")
         .option("--json", "Print a JSON envelope.")
         .action((ref, options) => handle("functions delete", options, () => requestOxygen("/api/cli/functions", { method: "POST", body: { operation: "delete", function: ref, approved: options.yes === true } })));
+    functions.command("restore").description("Retired: OXYGEN-provided Functions can no longer be restored. Create a workspace Function instead.")
+        .option("--catalog-id <id...>", "Legacy catalog identifiers; restoration is no longer available.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("functions restore", options, () => requestOxygen("/api/cli/functions", { method: "POST", body: { operation: "restore_managed", ...(options.catalogId?.length ? { catalog_ids: options.catalogId } : {}) } })));
     functions.command("bind <table> <function>").description("Add a Function column with explicit input/output mappings and a caller credit cap. Create each mapped output column on the caller table first with `columns add`; bind rejects an output mapped to a column the caller table does not have.")
-        .requiredOption("--inputs-json <json>", "Object mapping Function input keys to caller column keys.")
+        .requiredOption("--inputs-json <json>", "Map Function input keys to caller columns or nested JSON paths, e.g. profile.company.domain.")
         .requiredOption("--outputs-json <json>", "Object mapping Function output keys to existing caller column keys.")
         .requiredOption("--max-credits-per-item <n>", "Hard credit ceiling for each caller row; future publishes cannot raise it.")
         .option("--overwrite-policy <policy>", "Callback writes: empty_only or overwrite.", "empty_only")

package/dist/help.d.ts

@@ -20,4 +20,12 @@ export declare function enableCommandSuggestions(command: Command): void;
  * lists the real subcommands. Returns null when argv does not describe an
  * unknown subcommand (an unknown OPTION has its own handling).
  */
+/**
+ * Hint for `error: unknown option '--filter'`. Commander's own suggester stops
+ * at three edits, so `--filter` never reaches `--filter-json`; a flag that is a
+ * prefix of exactly one option on that command (or of which exactly one option
+ * is a prefix) names it. Returns null when commander's output already says it
+ * all, or when the flag is not a long option.
+ */
+export declare function unknownOptionHint(program: Command, argv: readonly string[], message: string): string | null;
 export declare function unknownCommandHint(program: Command, argv: readonly string[]): string | null;

package/dist/help.js

@@ -214,6 +214,52 @@ const COMMAND_SYNONYMS = {
  * lists the real subcommands. Returns null when argv does not describe an
  * unknown subcommand (an unknown OPTION has its own handling).
  */
+/**
+ * Hint for `error: unknown option '--filter'`. Commander's own suggester stops
+ * at three edits, so `--filter` never reaches `--filter-json`; a flag that is a
+ * prefix of exactly one option on that command (or of which exactly one option
+ * is a prefix) names it. Returns null when commander's output already says it
+ * all, or when the flag is not a long option.
+ */
+export function unknownOptionHint(program, argv, message) {
+    const flag = /unknown option '(--[^']+)'/.exec(message)?.[1];
+    if (!flag)
+        return null;
+    const [command, path] = resolveCommandPath(program, argv);
+    const longs = new Set();
+    for (let current = command; current; current = current.parent) {
+        for (const option of current.options)
+            if (option.long)
+                longs.add(option.long);
+    }
+    const bare = flag.split("=")[0].toLowerCase();
+    if (longs.has(bare))
+        return null;
+    const candidates = [...longs].filter((long) => long.startsWith(bare) || bare.startsWith(long));
+    const helpLine = `Run \`${path} --help\` for its options.`;
+    if (candidates.length === 1) {
+        return `Hint: \`${path}\` has no \`${bare}\`. Did you mean \`${candidates[0]}\`? ${helpLine}`;
+    }
+    if (candidates.length > 1 && candidates.length <= 4) {
+        return `Hint: \`${path}\` has no \`${bare}\`. Did you mean one of ${candidates.map((c) => `\`${c}\``).join(", ")}? ${helpLine}`;
+    }
+    return `Hint: \`${path}\` has no \`${bare}\`. ${helpLine}`;
+}
+/** Walk the command path in argv (stopping at the first option) and return the deepest command with its printable path. */
+function resolveCommandPath(program, argv) {
+    let current = program;
+    let path = program.name();
+    for (const token of argv) {
+        if (token.startsWith("-"))
+            break;
+        const child = current.commands.find((candidate) => candidate.name() === token || candidate.aliases().includes(token));
+        if (!child)
+            break;
+        current = child;
+        path = `${path} ${token}`;
+    }
+    return [current, path];
+}
 export function unknownCommandHint(program, argv) {
     let current = program;
     let path = program.name();