@oxygen-agent/cli 1.275.1 → 1.284.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.275.1
+Version: 1.284.3

package/dist/command-manifest.d.ts

@@ -0,0 +1,30 @@
+import type { Command } from "commander";
+export type CommandManifestFlag = {
+    flags: string;
+    description: string;
+    required: boolean;
+};
+export type CommandManifestArgument = {
+    name: string;
+    required: boolean;
+    description: string;
+};
+export type CommandManifestEntry = {
+    name: string;
+    group: string;
+    description: string;
+    arguments: CommandManifestArgument[];
+    flags: CommandManifestFlag[];
+    spends_credits: boolean;
+    mutates: boolean;
+    json_supported: boolean;
+    hidden: boolean;
+};
+export type CommandManifest = {
+    binary: string;
+    version: string;
+    total: number;
+    exit_codes: Record<string, string>;
+    commands: CommandManifestEntry[];
+};
+export declare function buildCommandManifest(program: Command, binaryName: string): CommandManifest;

package/dist/command-manifest.js

@@ -0,0 +1,70 @@
+import { CLI_EXIT_CODE_TABLE, OXYGEN_VERSION } from "@oxygen/shared";
+const MUTATING_VERBS = new Set([
+    "add", "apply", "approve", "archive", "assign", "buy", "cancel", "clear",
+    "configure", "connect", "create", "delete", "disable", "dispatch", "draft",
+    "emit", "enable", "enroll", "grant", "import", "insert", "invite", "launch",
+    "login", "logout", "materialize", "merge", "migrate", "order", "pause",
+    "publish", "purchase", "push", "record", "register", "remove", "rename",
+    "reorder", "reply", "rerun", "reset", "resolve", "restore", "resume",
+    "retry", "retype", "revoke", "rotate", "run", "save", "schedule", "select",
+    "send", "set", "share", "start", "stop", "subscribe", "sync", "unpublish",
+    "unshare", "unsubscribe", "update", "upload", "upsert", "use", "withdraw",
+    "write",
+]);
+export function buildCommandManifest(program, binaryName) {
+    const commands = [];
+    for (const child of program.commands) {
+        collectCommand(child, [], commands);
+    }
+    commands.sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        binary: binaryName,
+        version: OXYGEN_VERSION,
+        total: commands.length,
+        exit_codes: Object.fromEntries(Object.entries(CLI_EXIT_CODE_TABLE).map(([code, meaning]) => [code, meaning])),
+        commands,
+    };
+}
+function collectCommand(command, ancestors, out) {
+    const path = [...ancestors, command.name()];
+    const children = command.commands;
+    // Group commands (e.g. `oxygen tables`) exist to hold subcommands; only leaf
+    // commands are invocable work, so only leaves become manifest entries.
+    if (children.length === 0) {
+        out.push(toManifestEntry(command, path));
+        return;
+    }
+    for (const child of children) {
+        collectCommand(child, path, out);
+    }
+}
+function toManifestEntry(command, path) {
+    const options = command.options.filter((option) => !option.hidden);
+    const flagStrings = options.map((option) => option.flags);
+    const leafVerb = path[path.length - 1] ?? "";
+    const verbPrefix = leafVerb.split("-")[0] ?? leafVerb;
+    return {
+        name: path.join(" "),
+        group: path[0] ?? "",
+        description: command.description(),
+        arguments: command.registeredArguments.map((argument) => ({
+            name: argument.name(),
+            required: argument.required,
+            description: argument.description,
+        })),
+        flags: options.map((option) => ({
+            flags: option.flags,
+            description: option.description,
+            required: option.mandatory,
+        })),
+        spends_credits: flagStrings.some((flags) => flags.includes("--approved") || flags.includes("--max-credits")),
+        mutates: MUTATING_VERBS.has(leafVerb) || MUTATING_VERBS.has(verbPrefix),
+        json_supported: flagStrings.some((flags) => flags.includes("--json")),
+        hidden: isHiddenCommand(command),
+    };
+}
+function isHiddenCommand(command) {
+    // Commander keeps hidden state private; read it defensively so a library
+    // bump degrades to hidden:false instead of a crash.
+    return Boolean(command._hidden);
+}

package/dist/help.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function applyOxygenHelp(program: Command, binaryName: string): void;

package/dist/help.js

@@ -0,0 +1,79 @@
+import { CLI_EXIT_CODE_TABLE } from "@oxygen/shared";
+// Grouped `--help` for the ~70 top-level command groups: commander's default
+// registration-order wall (login, auth, profiles, ... before any GTM noun) is
+// the first thing every fresh agent reads, so order it by the OXYGEN OS layer
+// a command belongs to and close with an agent quickstart + the reserved
+// exit-code table. Commands missing from the map land in the last group so a
+// new command never disappears from help.
+const HELP_GROUPS = [
+    {
+        heading: "Get started & account:",
+        commands: [
+            "login", "auth", "profiles", "logout", "update", "api-keys", "whoami",
+            "onboarding", "status", "orgs", "commands", "skills", "session",
+            "support", "feedback",
+        ],
+    },
+    {
+        heading: "Knowledge (context, wiki, recipes):",
+        commands: ["context", "knowledge", "prompts", "templates", "blueprints"],
+    },
+    {
+        heading: "Data (tables, CRM, dashboards):",
+        commands: [
+            "tables", "rows", "cells", "columns", "action-column", "enrich-column",
+            "enrichment", "table-runs", "table-ingestions", "runs", "crm",
+            "dashboards", "projects", "signup-leads",
+        ],
+    },
+    {
+        heading: "Sourcing & search:",
+        commands: ["sourcing", "lead-sourcing", "search", "companies", "people", "find", "tools"],
+    },
+    {
+        heading: "Outbound & channels:",
+        commands: [
+            "sequences", "senders", "inbox", "messages", "mailboxes",
+            "managed-inboxes", "deliverability", "domains", "email", "schedules",
+            "suppressions", "egress", "linkedin", "connections", "followers",
+            "viewers", "posts", "engagement", "whatsapp", "publishing", "notetaker",
+            "reviews",
+        ],
+    },
+    {
+        heading: "Automation, billing & admin:",
+        commands: [
+            "workflows", "integrations", "custom-integrations", "billing", "budget",
+            "observability", "worker", "db", "admin", "directory",
+        ],
+    },
+];
+const FALLBACK_HEADING = "Other commands:";
+export function applyOxygenHelp(program, binaryName) {
+    const headingByCommand = new Map();
+    for (const group of HELP_GROUPS) {
+        for (const name of group.commands)
+            headingByCommand.set(name, group.heading);
+    }
+    for (const command of program.commands) {
+        command.helpGroup(headingByCommand.get(command.name()) ?? FALLBACK_HEADING);
+    }
+    const exitCodeLine = Object.entries(CLI_EXIT_CODE_TABLE)
+        .map(([code, meaning]) => `${code} ${meaning.split(" (")[0]}`)
+        .join(" · ");
+    program.addHelpText("afterAll", [
+        "",
+        "Agent quickstart:",
+        `  1. ${binaryName} login                      connect this terminal (or set OXYGEN_API_KEY)`,
+        `  2. ${binaryName} onboarding start --json    load workspace context + the skill that teaches the GTM loops`,
+        `  3. ${binaryName} commands --json            full machine-readable command grammar (this CLI's self-index)`,
+        "",
+        "Conventions:",
+        "  --json prints a stable envelope {ok, data|error, meta}; errors always print it.",
+        "  Commands that spend credits or write to external platforms are gated: live runs",
+        "  require --approved --max-credits <n> and fail with a typed error until approved.",
+        "  State-changing responses include a web_url deep-link to inspect the result.",
+        "",
+        `Exit codes: ${exitCodeLine}`,
+    ].join("\n"));
+}

package/dist/http-client.d.ts

@@ -10,6 +10,7 @@ type RequestOptions = {
     traceId?: string;
     fetch?: typeof fetch;
     selectedOrganization?: string;
+    idempotencyKey?: string;
 };
 export declare function requestOxygen<T>(// skipcq: JS-R1005
 path: string, options?: RequestOptions): Promise<T>;

package/dist/http-client.js

@@ -42,6 +42,17 @@ path, options = {}) {
     if (options.body) {
         headers["Content-Type"] = "application/json";
     }
+    // Every mutating request carries an idempotency key. Routes that support
+    // replay dedupe on it; others ignore the header. On a timeout the key is
+    // echoed in error details so a re-run (OXYGEN_IDEMPOTENCY_KEY=<key>) can
+    // retry without duplicating the write once the route supports replay.
+    const method = options.method ?? "GET";
+    const idempotencyKey = method === "GET"
+        ? undefined
+        : options.idempotencyKey ?? process.env.OXYGEN_IDEMPOTENCY_KEY ?? randomUUID();
+    if (idempotencyKey) {
+        headers["Idempotency-Key"] = idempotencyKey;
+    }
     let response;
     const timeoutMs = resolveRequestTimeoutMs(options.timeoutMs);
     const timeout = createTimeoutSignal(timeoutMs);
@@ -64,6 +75,7 @@ path, options = {}) {
                     path,
                     timeout_ms: timeoutMs,
                     trace_id: traceId,
+                    ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
                 },
                 exitCode: 1,
             });
@@ -72,6 +84,7 @@ path, options = {}) {
             details: {
                 api_url: apiUrl,
                 reason: error instanceof Error ? error.message : "unknown",
+                ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
             },
             exitCode: 1,
         });