@oxygen-agent/cli 1.936.1 → 1.982.3

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.936.1
+Version: 1.982.3

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

@@ -84,9 +84,20 @@ const MUTATING_COMMANDS = new Set([
     "mailboxes warmup reconnect",
 ]);
 // `--approved` usually identifies a paid or externally mutating execution
-// mode, but a small number of destructive local operations are explicitly
+// 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([
+    "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",
     // Starting an attended session itself is free. This legacy compatibility
@@ -94,6 +105,9 @@ const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
     // trigger the billed model loop.
     "copilot start",
     "mailboxes delete",
+    // Previews without --approved; with it, removes a program no creator ever
+    // joined. No provider call, no credits.
+    "ugc programs delete",
     // This approval only reopens exact fingerprint-bound tenant rows. It never
     // calls the provider, dispatches an action, or touches the credit ledger.
     "sequences recover-capacity",
@@ -108,14 +122,27 @@ const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
 // Exact noun-style reads whose leaf happens to look like a mutating verb.
 // `workflows run <id>` gets an existing Workflow run; `workflows call` creates
 // one. Keep the exception exact so genuine `run` actions remain mutations.
-const READ_ONLY_COMMANDS = new Set(["workflows run"]);
+const READ_ONLY_COMMANDS = new Set([
+    "workflows run",
+    // Inspect existing creator receipts; never generate or import again.
+    "ugc posts draft-status",
+    "ugc posts history",
+]);
 // Exact commands whose execution fence is not named `--live`. A bare
 // 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([
+    "tables watcher preview",
+    "ugc creators invite",
+    "ugc creators send-invite",
     "ugc posts draft",
+    "ugc programs delete",
     "ugc voice import",
     "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.
@@ -127,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

@@ -4,7 +4,7 @@ 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");
+        .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).")
         .option("--json", "Print a JSON envelope.")
         .action((options) => handle("functions list", options, () => requestOxygen("/api/cli/functions")));
@@ -21,16 +21,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.js

@@ -137,8 +137,10 @@ export function applyOxygenHelp(program, binaryName) {
         // OXYGEN_API_KEY never runs it — without this step nothing on any
         // first-touch surface names the skill that teaches the GTM loops.
         `  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`,
         `  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.`,