@oxygen-agent/cli 1.1011.326 → 1.1011.440

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.1011.326
+Version: 1.1011.440

package/dist/command-manifest.js

@@ -1,3 +1,4 @@
+import { OPERATION_SPECS } from "@oxygen/shared/contracts/operations";
 import { CLI_EXIT_CODE_TABLE, OXYGEN_VERSION, inferUserCapabilityRoute, serializeCapabilityRoute, } from "@oxygen/shared";
 const DEFAULT_COMMAND_SEARCH_LIMIT = 10;
 const MAX_COMMAND_SEARCH_LIMIT = 25;
@@ -173,6 +174,13 @@ 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([
+    // /api/cli/find/run treats an omitted mode as dry_run for every Find capability.
+    "find email",
+    "find personal-email",
+    "find phone",
+    "find linkedin",
+    "find person",
+    "find company",
     "inbox delete-message",
     "inbox forget-whatsapp-chat",
     "tables watcher preview",
@@ -334,6 +342,7 @@ function toManifestEntry(command, path) {
     const leafVerb = path[path.length - 1] ?? "";
     const verbPrefix = leafVerb.split("-")[0] ?? leafVerb;
     const commandName = path.join(" ");
+    const operations = OPERATION_SPECS.filter((spec) => spec.cli.path.join(" ") === commandName);
     return {
         name: commandName,
         group: path[0] ?? "",
@@ -348,7 +357,9 @@ function toManifestEntry(command, path) {
             description: option.description,
             required: option.mandatory,
         })),
-        spends_credits: !ZERO_CREDIT_APPROVAL_COMMANDS.has(commandName) &&
+        // Some native commands read without flags and write with an explicit grant.
+        // Their metadata must include every available action's authorization posture.
+        spends_credits: operations.length ? operations.some((spec) => spec.spends) : (!ZERO_CREDIT_APPROVAL_COMMANDS.has(commandName) &&
             (flagStrings.some((flags) => flags.includes("--approved") ||
                 flags.includes("--max-credits") ||
                 // Legacy Copilot compatibility plus any future explicit budget flag.
@@ -361,11 +372,11 @@ function toManifestEntry(command, path) {
                 // cap flag exists for either, so the flag heuristic alone would misreport
                 // them as free.
                 (path[0] === "copilot" &&
-                    (leafVerb === "send" || leafVerb === "approve"))),
-        mutates: !READ_ONLY_COMMANDS.has(commandName)
+                    (leafVerb === "send" || leafVerb === "approve")))),
+        mutates: operations.length ? operations.some((spec) => spec.mutates) : (!READ_ONLY_COMMANDS.has(commandName)
             && (MUTATING_COMMANDS.has(commandName)
                 || MUTATING_VERBS.has(leafVerb)
-                || MUTATING_VERBS.has(verbPrefix)),
+                || MUTATING_VERBS.has(verbPrefix))),
         preview_by_default: flagStrings.some((flags) => flags.includes("--live")) ||
             PREVIEW_BY_DEFAULT_COMMANDS.has(commandName),
         json_supported: flagStrings.some((flags) => flags.includes("--json")),

package/dist/connectors-commands.d.ts

@@ -5,7 +5,10 @@ type JsonOptions = {
 };
 type Handle = (command: string, options: JsonOptions, action: () => Promise<unknown>) => Promise<void>;
 export declare const CONNECTORS_FLAG_OVERLAY: ContractFlagOverlay;
-/** The PATCH body for the flags given; one of the two workspace flags is required. */
+export declare const CONNECTOR_EVENTS_REVOKE_FLAG_OVERLAY: ContractFlagOverlay;
+/** The revoke body for the flags given; --subscription is required. */
+export declare function buildConnectorEventsRevokeBody(options: Record<string, unknown>): Record<string, unknown>;
+/** The PATCH body for the flags given; a workspace or a credit ceiling flag is required. */
 export declare function buildConnectorUpdateBody(options: Record<string, unknown>): Record<string, unknown>;
 export declare function registerConnectorsCommands(program: Command, handle: Handle): void;
 export {};

package/dist/connectors-commands.js

@@ -5,45 +5,117 @@
 // disagree about what can be set.
 import { Command } from "commander";
 import { OxygenError } from "@oxygen/shared/cli-result";
-import { CONNECTOR_UPDATE_OPERATION } from "@oxygen/shared/contracts/connectors";
+import { CONNECTOR_EVENTS_REVOKE_OPERATION, CONNECTOR_UPDATE_OPERATION } from "@oxygen/shared/contracts/connectors";
 import { operationPath } from "@oxygen/shared/contracts/operations";
 import { addContractFlags, readContractFlags } from "./contract-flags.js";
 import { requestOxygen } from "./http-client.js";
 const update = CONNECTOR_UPDATE_OPERATION;
+const revokeEvents = CONNECTOR_EVENTS_REVOKE_OPERATION;
 export const CONNECTORS_FLAG_OVERLAY = {
     default_workspace: {
         help: "The workspace this app should work in without asking: its id, slug or exact name from `orgs list`. You must be a member.",
         valueName: "<workspace>",
     },
+    credit_ceiling: {
+        help: "The most credits this app may spend in any 24 hours while it holds OXYGEN event subscriptions (0 = no paid calls then). --clear-credit-ceiling restores the plan default.",
+        valueName: "<credits>",
+    },
+    approve_above_default: {
+        help: "Approve a --credit-ceiling above your plan's default.",
+        negateHelp: "Do not approve a ceiling above the default (the default behaviour).",
+    },
+};
+export const CONNECTOR_EVENTS_REVOKE_FLAG_OVERLAY = {
+    subscription: {
+        help: "The subscription id from `connectors events get <app>`, or `all` for every live one.",
+        valueName: "<id|all>",
+    },
+    workspace: {
+        help: "Only this workspace's subscriptions (id, slug or exact name). Omit for all your workspaces.",
+        valueName: "<workspace>",
+    },
 };
-/** The PATCH body for the flags given; one of the two workspace flags is required. */
+/** The revoke body for the flags given; --subscription is required. */
+export function buildConnectorEventsRevokeBody(options) {
+    const body = readContractFlags(options, revokeEvents.contract, CONNECTOR_EVENTS_REVOKE_FLAG_OVERLAY);
+    if (typeof body.subscription !== "string") {
+        throw new OxygenError("invalid_request", "Pass --subscription <id> (from `connectors events get <app>`), or --subscription all to revoke every live one.", { exitCode: 1 });
+    }
+    return body;
+}
+/** The PATCH body for the flags given; a workspace or a credit ceiling flag is required. */
 export function buildConnectorUpdateBody(options) {
     const body = readContractFlags(options, update.contract, CONNECTORS_FLAG_OVERLAY);
-    if (!("default_workspace" in body)) {
-        throw new OxygenError("invalid_request", "Pass --default-workspace <workspace> to set where the app works, or --clear-default-workspace to have it ask each time.", { exitCode: 1 });
+    if (!("default_workspace" in body) && !("credit_ceiling" in body)) {
+        throw new OxygenError("invalid_request", "Pass --default-workspace <workspace> (or --clear-default-workspace) to set where the app works, or --credit-ceiling <credits> (or --clear-credit-ceiling) to set what it may spend in 24 hours.", { exitCode: 1 });
+    }
+    if ("approve_above_default" in body && !("credit_ceiling" in body)) {
+        throw new OxygenError("invalid_request", "--approve-above-default only goes with --credit-ceiling (or --clear-credit-ceiling).", { exitCode: 1 });
     }
     return body;
 }
 export function registerConnectorsCommands(program, handle) {
     const connectors = program
         .command("connectors")
-        .description("Connected apps: ChatGPT, Claude, Codex and any other app you connected to OXYGEN with OAuth, and the default workspace each one works in without asking. "
-        + "`connectors list` shows them; `connectors set <app> --default-workspace <workspace>` changes that app only. "
-        + "Picking a workspace inside an app changes the same setting, and the latest choice wins. This CLI keeps its own workspace (`orgs use`). "
-        + "Web: https://oxygen-agent.com/settings/connected-apps.");
+        .description("Connected apps (ChatGPT, Claude, Codex… connected to OXYGEN with OAuth): the workspace each one works in, the OXYGEN events it is subscribed to, and what it may spend. "
+        + "`connectors list` shows them; `connectors events get <app>` shows an app's event subscriptions and what OXYGEN sent it, and `connectors events revoke` stops them. "
+        + "`connectors set <app>` changes one app only: --default-workspace (picking a workspace inside the app changes the same setting; latest wins; this CLI keeps its own, `orgs use`) "
+        + "and --credit-ceiling (while it holds event subscriptions, its paid calls stay under this many credits in any 24 hours; the plan default otherwise). "
+        + "Web: the Connected apps page, /settings/connected-apps; every response carries its `web_url`.");
     connectors.addCommand(new Command("list")
-        .description("List your connected apps with each one's default workspace, when it was last used, and the workspaces you can choose from. Read-only, 0 credits.")
+        .description("List your connected apps with each one's default workspace, its live event subscriptions, its daily credit ceiling and what it spent in the last 24 hours, when it was last used, and the workspaces you can choose from. Read-only, 0 credits.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handle("connectors list", options, () => requestOxygen("/api/cli/connectors"));
     }));
     connectors.addCommand(new Command("get")
-        .description("Show one connected app and its default workspace. Read-only, 0 credits.")
+        .description("Show one connected app: its default workspace, its daily credit ceiling and what it spent in the last 24 hours in each workspace where it spends, and how many event subscriptions it holds. Read-only, 0 credits.")
         .argument("<connection>", update.cli.argument?.description ?? "The app's id or name.")
         .option("--json", "Print a JSON envelope.")
         .action(async (connection, options) => {
         await handle("connectors get", options, () => requestOxygen(`/api/cli/connectors/${encodeURIComponent(connection)}`));
     }));
+    const events = new Command("events")
+        .description("The events OXYGEN sends one connected app: what it subscribed to (a reply was classified, a run settled, an approval is waiting…), "
+        + "each subscription's filters, status and expiry, and what OXYGEN delivered to it and how each delivery went (never the content). "
+        + "`get` reads them; `revoke` stops them. Only apps connected with OAuth, such as ChatGPT, subscribe.");
+    events.addCommand(new Command("get")
+        .description("Show one connected app's event subscriptions (filters, status, granted, renew-by and expiry, workspace) and its recent deliveries (status, attempts, failure category, times; never content). Ended subscriptions stay listed for 7 days; `active_subscriptions` counts the live ones. Read-only, 0 credits.")
+        .argument("<connection>", update.cli.argument?.description ?? "The app's id or name.")
+        .option("--workspace <workspace>", "Only this workspace (id, slug or exact name). Omit for all your workspaces.")
+        .option("--deliveries <n>", "Recent deliveries to show per subscription (0-50, default 10).")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", `
+Examples:
+  oxygen connectors events get ChatGPT
+  oxygen connectors events get ChatGPT --workspace "Acme GTM" --deliveries 20
+`)
+        .action(async (connection, options) => {
+        const query = new URLSearchParams();
+        if (options.workspace?.trim())
+            query.set("workspace", options.workspace.trim());
+        if (options.deliveries?.trim())
+            query.set("deliveries", options.deliveries.trim());
+        const queryString = query.toString();
+        const suffix = queryString ? `?${queryString}` : "";
+        await handle("connectors events get", options, () => requestOxygen(`/api/cli/connectors/${encodeURIComponent(connection)}/events${suffix}`));
+    }));
+    events.addCommand(addContractFlags(new Command(revokeEvents.cli.path.at(-1) ?? "revoke")
+        .description(revokeEvents.cli.summary)
+        .argument(`<${revokeEvents.cli.argument?.name ?? "connection"}>`, revokeEvents.cli.argument?.description), revokeEvents.contract, CONNECTOR_EVENTS_REVOKE_FLAG_OVERLAY)
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", `
+Examples:
+  oxygen connectors events revoke ChatGPT --subscription all
+  oxygen connectors events revoke ChatGPT --subscription <id> --workspace "Acme GTM"
+`)
+        .action(async (connection, options) => {
+        await handle("connectors events revoke", options, () => requestOxygen(operationPath(revokeEvents, { connection }), {
+            method: revokeEvents.method,
+            body: buildConnectorEventsRevokeBody(options),
+        }));
+    }));
+    connectors.addCommand(events);
     connectors.addCommand(addContractFlags(new Command(update.cli.path.at(-1) ?? "set")
         .description(update.cli.summary)
         .argument(`<${update.cli.argument?.name ?? "connection"}>`, update.cli.argument?.description), update.contract, CONNECTORS_FLAG_OVERLAY)
@@ -53,6 +125,8 @@ Examples:
   oxygen connectors list
   oxygen connectors set ChatGPT --default-workspace "Acme GTM"
   oxygen connectors set <id> --clear-default-workspace
+  oxygen connectors set ChatGPT --credit-ceiling 300
+  oxygen connectors set ChatGPT --credit-ceiling 50000 --approve-above-default
 `)
         .action(async (connection, options) => {
         await handle("connectors set", options, () => requestOxygen(operationPath(update, { connection }), {

package/dist/contract-flags.d.ts

@@ -10,6 +10,8 @@ export type ContractFlagOverlayEntry = {
     aliases?: readonly string[];
     /** Boolean: help for the `--no-<flag>` form. */
     negateHelp?: string;
+    /** Boolean: do not generate the `--no-<flag>` form, for a field whose `false` changes nothing. */
+    noNegate?: boolean;
     /**
      * Boolean as two flags, e.g. `--warmup-restart` (true) / `--warmup-disable`
      * (false). When both are given, `off` wins.

package/dist/contract-flags.js

@@ -24,7 +24,7 @@ function attribute(flag) {
     return flag.replace(/-([a-z0-9])/g, (_match, char) => char.toUpperCase());
 }
 function isObject(property) {
-    return "type" in property && property.type === "object" && property.properties !== undefined;
+    return "type" in property && property.type === "object";
 }
 function contractFlagSpecs(properties, overlay, parentPath = [], parentFlag = "") {
     const specs = [];
@@ -37,11 +37,14 @@ function contractFlagSpecs(properties, overlay, parentPath = [], parentFlag = ""
         const flag = entry.flag ?? `${parentFlag}${kebab(name)}`;
         if (isObject(property)) {
             const fields = Object.values(property.properties ?? {});
-            const splat = entry.flatten || (fields.length <= MAX_SPLAT_FIELDS && !fields.some((field) => isObject(unwrapNullable(field).property)));
+            const splat = entry.flatten || (fields.length > 0 && property.additionalProperties !== true && fields.length <= MAX_SPLAT_FIELDS && !fields.some((field) => isObject(unwrapNullable(field).property)));
             if (splat)
                 specs.push(...contractFlagSpecs(property.properties ?? {}, overlay, path, entry.flatten ? "" : `${flag}-`));
             else
-                specs.push({ kind: "json", path, flag: `${flag}-json`, entry });
+                specs.push({ kind: "json", path, flag: `${flag}-json`, property, entry });
+        }
+        else if (!("type" in property) || (property.type === "array" && !("type" in property.items && ["string", "number", "integer", "boolean"].includes(property.items.type)))) {
+            specs.push({ kind: "json", path, flag: `${flag}-json`, property, entry });
         }
         else if ("type" in property && property.type === "boolean") {
             specs.push(entry.pair ? { kind: "pair", path, on: entry.pair.on, off: entry.pair.off, entry } : { kind: "boolean", path, flag, entry });
@@ -84,7 +87,9 @@ export function addContractFlags(command, contract, overlay = {}) {
         }
         if (spec.kind === "boolean") {
             command.addOption(new Option(`--${spec.flag}`, helpFor(spec, property)));
-            command.addOption(new Option(`--no-${spec.flag}`, spec.entry.negateHelp ?? `Sends ${spec.path.join(".")}: false.`));
+            if (!spec.entry.noNegate) {
+                command.addOption(new Option(`--no-${spec.flag}`, spec.entry.negateHelp ?? `Sends ${spec.path.join(".")}: false.`));
+            }
             continue;
         }
         const valueName = spec.entry.valueName ?? (spec.kind === "json" ? "<json>" : "<value>");
@@ -95,7 +100,7 @@ export function addContractFlags(command, contract, overlay = {}) {
     return command;
 }
 function invalid(flag, value, message, code = "invalid_number") {
-    return new OxygenError(code, message, { details: { flag: `--${flag}`, value }, exitCode: 1 });
+    return new OxygenError(code, message, { details: { flag: `--${flag}`, value }, exitCode: 2 });
 }
 function parseScalar(property, raw, flag) {
     if (!("type" in property))
@@ -119,6 +124,13 @@ function parseScalar(property, raw, flag) {
     if (property.type === "string" && property.enum && !property.enum.includes(raw)) {
         throw invalid(flag, raw, `--${flag} must be one of: ${property.enum.join(", ")}.`, "invalid_option");
     }
+    if (property.type === "boolean") {
+        if (raw === "true")
+            return true;
+        if (raw === "false")
+            return false;
+        throw invalid(flag, raw, `--${flag} values must be true or false.`, "invalid_option");
+    }
     return raw;
 }
 function readValue(spec, raw) {
@@ -145,8 +157,8 @@ function setPath(body, path, value) {
 function stringOption(options, flag, aliases = []) {
     for (const name of [flag, ...aliases]) {
         const value = options[attribute(name)];
-        if (typeof value === "string" && value.trim())
-            return value.trim();
+        if (typeof value === "string")
+            return value;
     }
     return undefined;
 }
@@ -175,11 +187,14 @@ export function readContractFlags(options, contract, overlay = {}) {
                 parsed = JSON.parse(raw);
             }
             catch {
-                throw invalid(spec.flag, raw, `--${spec.flag} must be a JSON object.`, "invalid_json");
+                throw invalid(spec.flag, raw, `--${spec.flag} must be valid JSON.`, "invalid_json");
             }
-            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            if ("type" in spec.property && spec.property.type === "object" && (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))) {
                 throw invalid(spec.flag, raw, `--${spec.flag} must be a JSON object.`, "invalid_json");
             }
+            if ("type" in spec.property && spec.property.type === "array" && !Array.isArray(parsed)) {
+                throw invalid(spec.flag, raw, `--${spec.flag} must be a JSON array.`, "invalid_json");
+            }
             setPath(body, spec.path, parsed);
             given.add(spec.flag);
         }
@@ -196,7 +211,7 @@ export function readContractFlags(options, contract, overlay = {}) {
         }
         else if (options[attribute(spec.flag)] === true) {
             if (given.has(spec.target)) {
-                throw new OxygenError("invalid_request", `Pass either --${spec.target} or --${spec.flag}, not both.`, { exitCode: 1 });
+                throw new OxygenError("invalid_request", `Pass either --${spec.target} or --${spec.flag}, not both.`, { exitCode: 2 });
             }
             setPath(body, spec.path, null);
         }
@@ -210,7 +225,7 @@ export function contractFlagNames(contract, overlay = {}) {
             case "pair":
                 return [`--${spec.on}`, `--${spec.off}`];
             case "boolean":
-                return [`--${spec.flag}`, `--no-${spec.flag}`];
+                return spec.entry.noNegate ? [`--${spec.flag}`] : [`--${spec.flag}`, `--no-${spec.flag}`];
             case "clear":
                 return [`--${spec.flag}`];
             default:

package/dist/crm-support-flags.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from "commander";
+/** Existing command names, positional arguments, formatters and actions stay owned by index.ts. */
+export declare function registerCrmSupportFlags(program: Command): void;
+export declare function readCrmNoteEditFields(options: object): Record<string, unknown>;
+export declare function readCrmPhotoFields(options: {
+    live?: boolean;
+    dryRun?: boolean;
+}): Record<string, unknown>;
+export declare function readCrmFileLabel(options: object): Record<string, unknown>;
+export declare function buildCrmObjectsPath(options: object): string;
+export declare function buildCrmConnectionsPath(object: string, rowId: string, options: object): string;

package/dist/crm-support-flags.js

@@ -0,0 +1,60 @@
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { CRM_CONNECTIONS_QUERY_CONTRACT, CRM_NOTE_EDIT_CONTRACT, CRM_OBJECTS_QUERY_CONTRACT, CRM_PHOTOS_CONTRACT, CRM_FILE_COMPLETE_CONTRACT } from "@oxygen/shared/contracts/crm-support";
+import { validateContract } from "@oxygen/shared/contracts/schema";
+import { addContractFlags, readContractFlags } from "./contract-flags.js";
+import { assertModeFlagsExclusive } from "./cli-values.js";
+const NOTE_OVERLAY = { pinned: { pair: { on: "pin", onHelp: "Pin the note.", off: "unpin", offHelp: "Unpin the note." } } };
+function child(parent, name) { return parent?.commands.find((command) => command.name() === name); }
+function replaceFlags(command, attributes, contract, overlay) {
+    if (!command)
+        throw new Error("Register CRM commands before their shared flags.");
+    const retained = command.options.filter((option) => !attributes.includes(option.attributeName()));
+    // Commander exposes this mutable runtime collection as readonly in its types.
+    // Replace only the flags this leaf owns before parsing the existing commands.
+    const options = command.options;
+    options.splice(0, options.length, ...retained);
+    addContractFlags(command, contract, overlay);
+}
+/** Existing command names, positional arguments, formatters and actions stay owned by index.ts. */
+export function registerCrmSupportFlags(program) {
+    const crm = child(program, "crm");
+    replaceFlags(child(crm, "objects"), [], CRM_OBJECTS_QUERY_CONTRACT);
+    replaceFlags(child(crm, "connections"), ["conversationLimit", "sequenceLimit"], CRM_CONNECTIONS_QUERY_CONTRACT);
+    replaceFlags(child(child(crm, "notes"), "update"), ["body", "title", "pin", "unpin"], CRM_NOTE_EDIT_CONTRACT, NOTE_OVERLAY);
+    replaceFlags(child(crm, "photos"), ["limit", "live"], CRM_PHOTOS_CONTRACT);
+    replaceFlags(child(child(crm, "files"), "attach"), ["label"], CRM_FILE_COMPLETE_CONTRACT);
+}
+function checkedFlags(options, contract, overlay) {
+    const value = readContractFlags(options, contract, overlay);
+    const checked = validateContract(contract, value, { unknown: "reject", overMax: "reject" });
+    if (!checked.ok)
+        throw new OxygenError("invalid_request", "Invalid CRM command fields.", { exitCode: 1, details: { fields: checked.issues.map((issue) => issue.path) } });
+    return checked.value;
+}
+export function readCrmNoteEditFields(options) {
+    const value = checkedFlags(options, CRM_NOTE_EDIT_CONTRACT, NOTE_OVERLAY);
+    // Preserve the existing --title "" spelling in addition to --clear-title.
+    if (options.title === "")
+        value.title = null;
+    return value;
+}
+export function readCrmPhotoFields(options) {
+    assertModeFlagsExclusive(options);
+    const value = checkedFlags(options, CRM_PHOTOS_CONTRACT);
+    if (options.dryRun)
+        value.mode = "dry_run";
+    if (value.mode === "dry_run" && value.live === true)
+        throw new OxygenError("invalid_request", "Pass either dry_run or live.", { exitCode: 1 });
+    if (value.mode === undefined && value.live !== true)
+        value.mode = "dry_run";
+    return value;
+}
+export function readCrmFileLabel(options) { return checkedFlags(options, CRM_FILE_COMPLETE_CONTRACT); }
+function queryPath(path, query) {
+    const params = new URLSearchParams(Object.entries(query).map(([key, value]) => [key, String(value)]));
+    return params.size ? `${path}?${params}` : path;
+}
+export function buildCrmObjectsPath(options) { return queryPath("/api/cli/crm/objects", checkedFlags(options, CRM_OBJECTS_QUERY_CONTRACT)); }
+export function buildCrmConnectionsPath(object, rowId, options) {
+    return queryPath(`/api/cli/crm/objects/${encodeURIComponent(object)}/records/${encodeURIComponent(rowId)}/connections`, checkedFlags(options, CRM_CONNECTIONS_QUERY_CONTRACT));
+}

package/dist/customer-operation-commands.d.ts

@@ -0,0 +1,5 @@
+import { Command } from "commander";
+/** Register each domain's selected operation as a native command with exact typed flags. */
+export declare function registerCustomerOperationCommands(program: Command, handle: (command: string, options: {
+    json?: boolean;
+}, action: () => Promise<unknown>) => Promise<void>): void;

package/dist/customer-operation-commands.js

@@ -0,0 +1,101 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { CLI_OPERATIONS, operationFormData, operationInputContract, operationRequest } from "@oxygen/shared/contracts/operations";
+import { unwrapNullable, validateContract } from "@oxygen/shared/contracts/schema";
+import { addContractFlags, readContractFlags } from "./contract-flags.js";
+import { requestOxygen } from "./http-client.js";
+/** Register each domain's selected operation as a native command with exact typed flags. */
+export function registerCustomerOperationCommands(program, handle) {
+    for (const spec of CLI_OPERATIONS) {
+        let parent = program;
+        const words = [...spec.cli.path];
+        const leaf = words.pop();
+        for (const word of words) {
+            let child = parent.commands.find((command) => command.name() === word);
+            if (!child)
+                child = parent.command(word).description(`${word} workspace operations.`);
+            parent = child;
+        }
+        // Never hide an existing owner behind a second Commander command.
+        if (parent.commands.some((command) => command.name() === leaf)) {
+            throw new Error(`Duplicate native operation command ${spec.cli.path.join(" ")}`);
+        }
+        const contract = operationInputContract(spec);
+        const command = addContractFlags(parent.command(leaf).description(spec.cli.summary), contract)
+            .option("--json", "Print a JSON envelope.");
+        if (spec.binary)
+            command.requiredOption("--output <path>", "Write the exact downloaded bytes to this local file.");
+        if (spec.multipart)
+            command.option("--file <path>", "Upload bytes from this local file. Omit the base64 flag; file name and content type default from the path.");
+        for (const name of contract.required ?? []) {
+            const property = contract.properties[name];
+            const flag = `--${name.replace(/_/g, "-")}`;
+            const option = command.options.find((candidate) => candidate.long === flag || candidate.long === `${flag}-json`);
+            const multipartAlternative = spec.multipart && [spec.multipart.contentField, spec.multipart.nameField, spec.multipart.typeField].includes(name);
+            if (multipartAlternative) {
+                if (option)
+                    option.description = `${option.description} Required unless supplied by --file.`.trim();
+            }
+            else if (unwrapNullable(property).nullable) {
+                if (option)
+                    option.description = `${option.description} Required: use this flag or --clear-${name.replace(/_/g, "-")}.`.trim();
+            }
+            else if (option) {
+                // The negative boolean spelling uses the same attribute, so an explicit
+                // false satisfies this requirement just as true does.
+                option.makeOptionMandatory();
+            }
+        }
+        command.action((options, selected) => handle(spec.cli.path.join(" "), { ...options, json: selected.optsWithGlobals().json === true }, async () => {
+            const input = readContractFlags(options, contract);
+            if (spec.multipart && options.file !== undefined) {
+                if (input[spec.multipart.contentField] !== undefined)
+                    throw new OxygenError("invalid_request", "Choose --file or the base64 content flag, not both.", { exitCode: 2 });
+                const filePath = String(options.file);
+                input[spec.multipart.contentField] = (await readFile(filePath)).toString("base64");
+                input[spec.multipart.nameField] ??= basename(filePath);
+                input[spec.multipart.typeField] ??= uploadContentType(filePath);
+            }
+            const validation = validateContract(contract, input, { unknown: "reject", overMax: "reject" });
+            if (!validation.ok)
+                throw new OxygenError("invalid_request", validation.issues.map((issue) => issue.message).join(" "), { exitCode: 2 });
+            const request = operationRequest(spec, input);
+            if (spec.binary) {
+                if (spec.binary.stream)
+                    return requestOxygen(request.path, { method: request.method, binaryOutputPath: resolve(String(options.output)) });
+                const bytes = await requestOxygen(request.path, { method: request.method, binaryMaxBytes: spec.binary.maxBytes });
+                const output = resolve(String(options.output));
+                try {
+                    await writeFile(output, bytes, { flag: "wx" });
+                }
+                catch (error) {
+                    if (error && typeof error === "object" && "code" in error && error.code === "EEXIST") {
+                        throw new OxygenError("output_exists", "The output file already exists. Choose another --output path.", { exitCode: 2 });
+                    }
+                    throw error;
+                }
+                return { path: output, bytes: bytes.byteLength };
+            }
+            if (spec.multipart) {
+                let formData;
+                try {
+                    formData = operationFormData(spec, request.body ?? {});
+                }
+                catch (error) {
+                    throw new OxygenError("invalid_request", error instanceof Error ? error.message : "Invalid upload.", { exitCode: 2 });
+                }
+                return requestOxygen(request.path, { method: request.method, formData });
+            }
+            return requestOxygen(request.path, { method: request.method, ...(request.body ? { body: request.body } : {}) });
+        }));
+    }
+}
+function uploadContentType(filePath) {
+    const types = {
+        ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".svg": "image/svg+xml",
+        ".csv": "text/csv", ".json": "application/json", ".jsonl": "application/x-ndjson",
+        ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    };
+    return types[extname(filePath).toLowerCase()] ?? "application/octet-stream";
+}

package/dist/database-query-flags.d.ts

@@ -0,0 +1,2 @@
+import type { ContractFlagOverlay } from "./contract-flags.js";
+export declare const DATABASE_QUERY_FLAG_OVERLAY: ContractFlagOverlay;

package/dist/database-query-flags.js

@@ -0,0 +1,6 @@
+import { readPositiveInt } from "./cli-values.js";
+export const DATABASE_QUERY_FLAG_OVERLAY = {
+    sql: { omit: true }, // Keep the existing required --sql option.
+    max_rows: { valueName: "<n>", parse: readPositiveInt }, // Preserve legacy coercion/defaults.
+    max_chars: { valueName: "<n>" },
+};

package/dist/help.d.ts

@@ -1,4 +1,4 @@
-import type { Command, CommanderError } from "commander";
+import { CommanderError, type Command } from "commander";
 import { type CliFailure } from "@oxygen/shared/cli-result";
 export declare function applyOxygenHelp(program: Command, binaryName: string): void;
 /**
@@ -12,6 +12,8 @@ export declare function applyOxygenHelp(program: Command, binaryName: string): v
  * `installCommanderExitOverride` recurses.
  */
 export declare function enableCommandSuggestions(command: Command): void;
+/** A declared flag following a value option is a missing value, not literal data. */
+export declare function validateRequiredOptionValues(program: Command, selected: Command): void;
 /**
  * The extra line printed after `error: unknown command '<x>'`.
  *

package/dist/help.js

@@ -1,3 +1,4 @@
+import { CommanderError } from "commander";
 import { CLI_EXIT_CODE_TABLE } from "@oxygen/shared";
 import { exitCodeForErrorCode, failure } from "@oxygen/shared/cli-result";
 // Grouped `--help` for the ~70 top-level command groups: commander's default
@@ -20,6 +21,12 @@ const HELP_GROUPS = [
             "status",
             "home",
             "orgs",
+            // Where each connected app (ChatGPT, Claude…) works by default: read
+            // beside `orgs`, where a founder asking "which workspace" looks first.
+            "connectors",
+            // Workspace settings (the sidebar pages everyone sees): the 2026-09-30
+            // blind baseline typed `oxygen settings --help` before anything else.
+            "settings",
             "commands",
             "skills",
             "session",
@@ -175,6 +182,38 @@ export function enableCommandSuggestions(command) {
     for (const child of command.commands)
         enableCommandSuggestions(child);
 }
+/** A declared flag following a value option is a missing value, not literal data. */
+export function validateRequiredOptionValues(program, selected) {
+    const options = new Map();
+    for (let current = selected; current; current = current.parent) {
+        for (const option of current.options) {
+            if (option.long && !options.has(option.long))
+                options.set(option.long, option);
+            if (option.short && !options.has(option.short))
+                options.set(option.short, option);
+        }
+    }
+    // Installed Commander writes this exact property before command dispatch;
+    // its public typings omit it. Validate only that property at this seam.
+    const rawArgs = Reflect.get(program, "rawArgs");
+    if (!Array.isArray(rawArgs) || !rawArgs.every((value) => typeof value === "string")) {
+        throw new CommanderError(2, "commander.invalidArgument", "Cannot validate the command's original option arguments.");
+    }
+    const argv = rawArgs;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--")
+            break;
+        const option = options.get(token);
+        if (!option?.required)
+            continue;
+        const next = argv[index + 1];
+        if (next === undefined || next === "--" || options.has(next.split("=")[0])) {
+            throw new CommanderError(2, "commander.optionMissingArgument", `option '${option.flags}' argument missing. To use an option name as literal text, pass ${option.long ?? option.short}=<value>.`);
+        }
+        index += 1;
+    }
+}
 /**
  * Verbs a user reaches for that this CLI spells differently.
  *
@@ -205,6 +244,10 @@ const COMMAND_SYNONYMS = {
     exec: ["run", "start", "call"],
     execute: ["run", "start", "call"],
     find: ["search", "query", "list"],
+    // The product's own copy calls a Sequence a campaign; a blind agent's first
+    // guess was `oxygen campaigns` (Plain T-220 baseline, 2026-09-30).
+    campaign: ["sequences"],
+    campaigns: ["sequences"],
 };
 /**
  * The extra line printed after `error: unknown command '<x>'`.

package/dist/http-client.d.ts

@@ -3,6 +3,8 @@ import { type CliEndpoint } from "./runtime.js";
 type RequestOptions = {
     /** Internal bounded file download; never follows a caller-supplied URL. */
     binaryMaxBytes?: number;
+    /** Stream a native authenticated download to an exclusively created file. */
+    binaryOutputPath?: string;
     method?: "GET" | "POST" | "PATCH" | "DELETE";
     body?: Record<string, unknown>;
     formData?: FormData;