@oxygen-agent/cli 1.948.1 → 1.987.20

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.948.1
+Version: 1.987.20

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

@@ -274,6 +274,13 @@ function renderProvider(row, now, binary) {
     const provider = str(row.provider) ?? "?";
     const level = str(posture.level) ?? "unknown";
     const functions = arr(row.functions).map((fn) => String(fn));
+    // A catch-all escalation lane is the only route to its provider and is
+    // declared outside the chain's steps; name it so the row does not read as a
+    // plain primary for an intent it never leads.
+    const escalations = arr(row.primary_for)
+        .map((role) => obj(role))
+        .filter((role) => role !== null && str(role.role) === "catch_all_escalation")
+        .map((role) => str(role.intent) ?? "?");
     const probe = str(health.probe) ?? "none";
     const healthStatus = str(health.latest_status) ?? (probe === "none" ? "unmonitored" : "no data");
     const healthDetail = [
@@ -284,7 +291,8 @@ function renderProvider(row, now, binary) {
         (num(health.auth_error_pct_96h) ?? 0) > 0 ? `${pct(health.auth_error_pct_96h)} auth-error` : null,
         num(health.last_latency_ms) === null ? null : `${count(health.last_latency_ms)} ms`,
     ].filter((part) => part !== null);
-    lines.push(`  - ${provider} [${level}]${functions.length > 0 ? ` ${functions.join("+")}` : ""} · ` +
+    lines.push(`  - ${provider} [${level}]${functions.length > 0 ? ` ${functions.join("+")}` : ""}` +
+        `${escalations.length > 0 ? ` (catch-all escalation: ${escalations.join(", ")})` : ""} · ` +
         `key ${row.key_configured === false ? `NOT SET (${str(row.managed_key_env_var) ?? "—"})` : str(row.managed_key_env_var) ?? "customer-supplied"} · ` +
         `health ${healthStatus} (${healthDetail.join(", ")})`);
     const scope = str(traffic.scope) ?? "workspace_attributed";

package/dist/cli-values.d.ts

@@ -1,5 +1,19 @@
 /** Parse a `--limit`/`--interval`-style flag into a positive integer, or undefined when absent. */
 export declare function readPositiveInt(value: string | undefined): number | undefined;
+/**
+ * Parse an `--offset`-style flag into a NON-NEGATIVE integer, or undefined when absent.
+ *
+ * Deliberately separate from `readPositiveInt`: for `--limit`/`--interval`, zero is
+ * meaningless and rejecting it is correct, but for an offset zero is the natural
+ * first page. Sharing one reader made `tables query --offset 0` fail with
+ * "Expected a positive integer." — the identity case of the very flag whose help
+ * text says "Skip this many rows" (OXY-4360).
+ *
+ * Callers must test the result with `!== undefined`, never for truthiness: a valid
+ * 0 is falsy, which is how the same flag then went on to be dropped from the
+ * request body it had just been validated for.
+ */
+export declare function readNonNegativeInt(value: string | undefined): number | undefined;
 /** Read a string field from an unknown record-shaped value, or null when it is missing/non-string. */
 export declare function readRecordString(value: unknown, key: string): string | null;
 /**

package/dist/cli-values.js

@@ -20,6 +20,32 @@ export function readPositiveInt(value) {
     }
     return parsed;
 }
+/**
+ * Parse an `--offset`-style flag into a NON-NEGATIVE integer, or undefined when absent.
+ *
+ * Deliberately separate from `readPositiveInt`: for `--limit`/`--interval`, zero is
+ * meaningless and rejecting it is correct, but for an offset zero is the natural
+ * first page. Sharing one reader made `tables query --offset 0` fail with
+ * "Expected a positive integer." — the identity case of the very flag whose help
+ * text says "Skip this many rows" (OXY-4360).
+ *
+ * Callers must test the result with `!== undefined`, never for truthiness: a valid
+ * 0 is falsy, which is how the same flag then went on to be dropped from the
+ * request body it had just been validated for.
+ */
+export function readNonNegativeInt(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isSafeInteger(parsed) || parsed < 0) {
+        throw new OxygenError("invalid_number", "Expected a non-negative integer.", {
+            details: { value },
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
 /** Read a string field from an unknown record-shaped value, or null when it is missing/non-string. */
 export function readRecordString(value, key) {
     if (!value || typeof value !== "object" || Array.isArray(value))

package/dist/command-manifest.js

@@ -88,12 +88,15 @@ const MUTATING_COMMANDS = new Set([
 // zero-credit. Keep those exceptions exact so discovery never invents spend.
 const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
     "tables watcher preview",
+    "knowledge repositories connect",
+    "knowledge repositories resolve",
     // Creator invitation emails need exact send authorization but cost 0 credits.
     "ugc creators invite",
     "ugc creators send-invite",
     // These approvals record an observed outcome or stop future renewal;
     // neither operation buys a service or consumes Oxygen credits.
     "ugc amplification reconcile",
+    "ugc peer-amplification reconcile",
     "ugc sponsorship cancel",
     // A Function binding stores a cap for future runs; creating it executes nothing.
     "functions bind",
@@ -138,6 +141,8 @@ const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
     "ugc sponsorship preview",
     "ugc sponsorship cancel",
     "ugc amplification reconcile",
+    "ugc peer-amplification reconcile",
+    "ugc peer-amplification save",
     // Fenced by --approved, not --live: a bare call resolves the sender, sequence,
     // audience and caps and writes nothing. Without this entry discovery would tell
     // an agent that previewing the play arms it, and the preview would go unrun.
@@ -149,6 +154,7 @@ const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
     "support admin reply",
     // A bare call reads the Plain workspace and prints the plan; --apply writes.
     "support admin setup",
+    "verify email",
     "workflows webhooks rotate",
 ]);
 export function buildCommandManifest(program, binaryName) {

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.\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.")
@@ -21,16 +37,24 @@ export function registerFunctionsCommands(program, handle) {
             function: ref,
             ...(options.expectedDraftHash ? { expected_draft_hash: options.expectedDraftHash } : {}),
         } })));
-    functions.command("publish <function>").description("Publish the inspected draft for every caller's future invocations; preserves captured runs and caller caps.")
+    functions.command("publish <function>").description("Publish the inspected draft for every caller's future invocations; preserves captured runs and caller caps. Until the first publish a draft is addressed by its backing table id; publishing mints the Function id that bindings and runs record, and the table id keeps resolving.")
         .requiredOption("--expected-draft-hash <hash>", "function.draft.contentHash returned by draft or describe; rejects concurrent edits.")
         .option("--json", "Print a JSON envelope.")
         .action((ref, options) => handle("functions publish", options, () => requestOxygen("/api/cli/functions", { method: "POST", body: { operation: "publish", function: ref, expected_draft_hash: options.expectedDraftHash } })));
-    functions.command("runs <function>").description("Inspect a Function's latest 100 invocations and their captured versions.")
+    functions.command("runs <function>").description("Inspect a Function's latest 100 invocations, the table that called each one, and their captured versions. For a call that did not complete, creditsUsed can show the estimate; `table-runs provider-summary <run_id>` reports the credits actually captured.")
         .option("--json", "Print a JSON envelope.")
         .action((ref, options) => handle("functions runs", options, () => requestOxygen(`/api/cli/functions/runs?${new URLSearchParams({ function: ref })}`)));
-    functions.command("bind <table> <function>").description("Add a Function column with explicit input/output mappings and a caller credit cap.")
+    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")
+        .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("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 caller column keys.")
+        .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")
         .option("--key <key>", "Function column key.").option("--label <label>", "Function column label.")

package/dist/help.d.ts

@@ -1,2 +1,23 @@
 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).
+ */
+export declare function unknownCommandHint(program: Command, argv: readonly string[]): string | null;

package/dist/help.js

@@ -139,7 +139,12 @@ 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`,
         `  Provider inventory: ${binaryName} tools search <brand> --json, then ${binaryName} tools search --provider <provider-id> --all --json (Blitz uses blitzapi).`,
         `  Installable systems and recurring monitors: ${binaryName} blueprints list --json.`,
@@ -154,3 +159,92 @@ 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).
+ */
+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}`;
+}