@oxygen-agent/cli 1.982.3 → 1.1003.12

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.982.3
+Version: 1.1003.12

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/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

@@ -37,6 +37,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",

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,12 +3,28 @@ import { parseJsonObject } from "./cli-values.js";
 import { requestOxygen } from "./http-client.js";
 export function registerFunctionsCommands(program, handle) {
     const functions = program.command("functions")
-        .description("Create, edit, publish and reuse Functions backed by ordinary Tables.")
-        .addHelpText("after", "\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, including draft and disabled Functions (up to 500).")
+        .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).")
+        .option("--favorites", "Only the Functions you favourited (`functions favorite <function>`).")
         .option("--json", "Print a JSON envelope.")
-        .action((options) => handle("functions list", options, () => requestOxygen("/api/cli/functions")));
-    functions.command("describe <function>").description("Inspect a Function's draft, published version, inputs, outputs and credit caps.")
+        .action((options) => handle("functions list", options, () => {
+        if (options.managed && options.favorites)
+            throw new OxygenError("invalid_request", "Pass --managed or --favorites, not both.", { exitCode: 1 });
+        const filter = options.managed ? "managed" : options.favorites ? "favorites" : null;
+        return requestOxygen(filter ? `/api/cli/functions?${new URLSearchParams({ filter })}` : "/api/cli/functions");
+    }));
+    for (const [command, label] of [["favorite", "Favourite a Function so it appears under `functions list --favorites` and the Favorites tab; per user, per workspace."], ["unfavorite", "Remove a Function from your favourites."]]) {
+        functions.command(`${command} <function>`).description(label)
+            .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.")
+        .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.")
         .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.")
@@ -31,11 +47,15 @@ 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. Works on an OXYGEN-managed Function too: it leaves this workspace's library and is not seeded back.")
+        .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.\nDeleting an OXYGEN-managed Function only removes it from THIS workspace; `functions restore` brings OXYGEN's ready-made Functions back.\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("Put back the OXYGEN-managed Functions this workspace deleted. They are rebuilt at the current catalog version in the background; `functions list --managed` shows them as they land.")
+        .option("--catalog-id <id...>", "Restore only these catalog entries (the managed.catalogId from `functions describe`). Defaults to every removed one.")
+        .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("--outputs-json <json>", "Object mapping Function output keys to existing caller column keys.")

package/dist/help.d.ts

@@ -1,2 +1,31 @@
 import type { Command } from "commander";
 export declare function applyOxygenHelp(program: Command, binaryName: string): void;
+/**
+ * Turn commander's own edit-distance suggester on for EVERY command.
+ *
+ * It defaults to on, but `copyInheritedSettings` only runs for children created
+ * through `.command()`; the hundreds of subcommands this CLI registers with
+ * `.addCommand(new Command(...))` carry whatever their own constructor set.
+ * Walking the tree makes the setting a property of the whole surface rather
+ * than of how each command happened to be built, the same reason
+ * `installCommanderExitOverride` recurses.
+ */
+export declare function enableCommandSuggestions(command: Command): void;
+/**
+ * The extra line printed after `error: unknown command '<x>'`.
+ *
+ * Commander's message names what is wrong and nothing a user can do next. This
+ * resolves the command they were actually inside, offers the synonym or unique
+ * prefix match commander cannot reach, and always names the exact `--help` that
+ * 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

@@ -139,6 +139,10 @@ export function applyOxygenHelp(program, binaryName) {
         `  2. ${binaryName} skills install --json      load the skills that teach the GTM loops (automatic after login)`,
         "     Add --project to keep the skills inside the current project, including confined agent sessions.",
         `  3. ${binaryName} context resolve --json     load workspace context before operating primitives`,
+        // A new workspace's first sessions are onboarding, and the consultant guide is
+        // a served skill an agent has to be TOLD about: nothing else on a first-touch
+        // surface named it (blind eval, 2026-09-16).
+        `     New or thin workspace? load the onboarding consultant first: ${binaryName} skills get oxygen-onboarding --json`,
         `  4. ${binaryName} capabilities search "<goal>" --json   route the goal, then hydrate one exact command`,
         `     ${binaryName} commands search "<term>" --json         find a command by name or purpose instead of dumping the manifest`,
         `  5. ${binaryName} recipes list --json       choose a play from the Recipe catalog for your goal`,
@@ -155,3 +159,138 @@ export function applyOxygenHelp(program, binaryName) {
         `Exit codes: ${exitCodeLine}`,
     ].join("\n"));
 }
+/**
+ * Turn commander's own edit-distance suggester on for EVERY command.
+ *
+ * It defaults to on, but `copyInheritedSettings` only runs for children created
+ * through `.command()`; the hundreds of subcommands this CLI registers with
+ * `.addCommand(new Command(...))` carry whatever their own constructor set.
+ * Walking the tree makes the setting a property of the whole surface rather
+ * than of how each command happened to be built, the same reason
+ * `installCommanderExitOverride` recurses.
+ */
+export function enableCommandSuggestions(command) {
+    command.showSuggestionAfterError(true);
+    for (const child of command.commands)
+        enableCommandSuggestions(child);
+}
+/**
+ * Verbs a user reaches for that this CLI spells differently.
+ *
+ * Commander's suggester is edit distance only, so it fires for a typo
+ * (`describ` → `describe`) and never for a synonym: `get` is seven edits from
+ * `describe`, so `oxygen tables get` answered `error: unknown command 'get'`
+ * and stopped there with nothing to try next (blind user eval, 2026-09-17).
+ * Values are candidate real subcommand names, best first; only names the
+ * command actually has are ever offered.
+ */
+const COMMAND_SYNONYMS = {
+    get: ["describe", "show", "view", "status", "preview"],
+    show: ["describe", "get", "list", "preview"],
+    view: ["describe", "preview", "show", "get"],
+    info: ["describe", "status", "show"],
+    inspect: ["describe", "preview", "show"],
+    read: ["describe", "query", "export", "get"],
+    ls: ["list"],
+    all: ["list"],
+    new: ["create", "add"],
+    make: ["create", "add"],
+    rm: ["delete", "remove", "archive"],
+    del: ["delete", "remove", "archive"],
+    remove: ["delete", "archive"],
+    destroy: ["delete", "archive"],
+    edit: ["update", "set", "rename"],
+    modify: ["update", "set"],
+    exec: ["run", "start", "call"],
+    execute: ["run", "start", "call"],
+    find: ["search", "query", "list"],
+};
+/**
+ * The extra line printed after `error: unknown command '<x>'`.
+ *
+ * Commander's message names what is wrong and nothing a user can do next. This
+ * resolves the command they were actually inside, offers the synonym or unique
+ * prefix match commander cannot reach, and always names the exact `--help` that
+ * 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();
+    for (const token of argv) {
+        // Options and their values are commander's business; only the command path
+        // is walked here.
+        if (token.startsWith("-"))
+            break;
+        const child = current.commands.find((candidate) => candidate.name() === token || candidate.aliases().includes(token));
+        if (child) {
+            current = child;
+            path = `${path} ${token}`;
+            continue;
+        }
+        if (current.commands.length === 0)
+            return null;
+        return buildUnknownCommandHint(current, path, token);
+    }
+    return null;
+}
+function buildUnknownCommandHint(parent, path, token) {
+    const names = parent.commands.map((command) => command.name()).filter((name) => name !== "help");
+    const lower = token.toLowerCase();
+    const synonym = (COMMAND_SYNONYMS[lower] ?? []).find((candidate) => names.includes(candidate));
+    // A unique prefix is the other guess commander cannot make: `tables desc`
+    // scores too far from `describe` on edit distance, but it names exactly one
+    // command.
+    const prefixMatches = names.filter((name) => name.startsWith(lower));
+    const suggestion = synonym ?? (prefixMatches.length === 1 ? prefixMatches[0] : null);
+    const helpLine = `Run \`${path} --help\` for the ${names.length} subcommands of \`${path}\`.`;
+    return suggestion
+        ? `Hint: \`${path}\` has no \`${token}\`. Did you mean \`${path} ${suggestion}\`? ${helpLine}`
+        : `Hint: \`${path}\` has no \`${token}\`. ${helpLine}`;
+}