@oxygen-agent/cli 1.1014.135 → 1.1014.618

package/dist/commands/observability.js

@@ -0,0 +1,125 @@
+import { readPositiveInt } from "../cli-values.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { Command } from "commander";
+// The observability console caps each source at --limit (default 25, max 100) and
+// reports which hit the cap in sources[].capped. The human (non --json) output is
+// a JSON dump that buries that boolean, so surface it as a one-line stderr notice:
+// the counts shown are only the returned page, and more may sit behind a capped
+// source. Not pagination — raising --limit or filtering --source is the fix.
+function writeObservabilityCapsNotice(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const record = data;
+    const sources = Array.isArray(record.sources) ? record.sources : [];
+    const cappedSources = sources
+        .filter((source) => Boolean(source) && typeof source === "object" && !Array.isArray(source)
+        && source.capped === true)
+        .map((source) => String(source.source));
+    if (cappedSources.length === 0)
+        return;
+    const returned = typeof record.returned === "number"
+        ? record.returned
+        : Array.isArray(record.items) ? record.items.length : 0;
+    process.stderr.write(`note: showing ${returned} item(s); some sources hit the per-source cap (${cappedSources.join(", ")}) — raise --limit (max 100) or filter --source to see more.\n`);
+}
+export function registerObservabilityFamily(program, handleAsyncAction) {
+    program
+        .command("observability")
+        .description("Workspace observability: redacted operation events, plus the cross-primitive runs lens and approvals inbox (list-only — decisions route to the owning primitive).")
+        .addCommand(new Command("events")
+        .description("List recent redacted OXYGEN operation events and failures. Customer support triage and support-event history live in Plain Inbox.")
+        // Keep in sync with OBSERVABILITY_STATUS_FILTERS in
+        // apps/web/src/lib/observability.ts and the MCP tool enum in
+        // packages/mcp-server/src/tools/observability.ts. The API rejects any
+        // other value with invalid_request so a typo fails loudly.
+        .option("--status <status>", "Filter by success, error, completed, failed, completed_with_errors, queued, skipped, or blocked.")
+        // Keep --type / --source values in sync with OBSERVABILITY_TYPE_FILTERS /
+        // OBSERVABILITY_SOURCE_FILTERS in apps/web/src/lib/observability.ts and
+        // the MCP tool enums. The API rejects any other value with
+        // invalid_request so a typo fails loudly.
+        .option("--type <type>", "Filter by operation or provider_request.")
+        .option("--source <source>", "Filter by cli, web, mcp, workflow, or provider.")
+        .option("--trace-id <trace_id>", "Filter by trace id.")
+        .option("--run-id <run_id>", "Filter by workspace run id.")
+        .option("--limit <n>", "Maximum events to return. Defaults to 50.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("observability events", options, () => {
+            const params = new URLSearchParams();
+            const status = readOption(options.status);
+            const type = readOption(options.type);
+            const source = readOption(options.source);
+            const traceId = readOption(options.traceId);
+            const runId = readOption(options.runId);
+            const limit = readPositiveInt(options.limit);
+            if (status)
+                params.set("status", status);
+            if (type)
+                params.set("type", type);
+            if (source)
+                params.set("source", source);
+            if (traceId)
+                params.set("trace_id", traceId);
+            if (runId)
+                params.set("run_id", runId);
+            if (limit)
+                params.set("limit", String(limit));
+            const suffix = params.toString() ? `?${params.toString()}` : "";
+            return requestOxygen(`/api/cli/observability/events${suffix}`);
+        });
+    }))
+        .addCommand(new Command("runs")
+        .description("List active and failed runs across workflows and table action/ingestion runs — the cross-primitive runs lens. Read-only; each failed item carries the command that resolves it.")
+        // Keep --status / --source values in sync with OBSERVABILITY_CONSOLE_STATES
+        // and OBSERVABILITY_RUN_SOURCES in apps/web/src/lib/observability-console.ts
+        // and the MCP tool enums. The API rejects any other value with
+        // invalid_request so a typo fails loudly.
+        .option("--status <statuses>", "Comma-separated normalized states: running, queued, waiting_approval, failed, completed, canceled. Defaults to active + failed.")
+        .option("--source <sources>", "Comma-separated sources: workflow, table_run.")
+        .option("--limit <n>", "Maximum items per source (default 25, max 100). Counts reflect the returned page only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("observability runs", options, async () => {
+            const params = new URLSearchParams();
+            const status = readOption(options.status);
+            const source = readOption(options.source);
+            const limit = readPositiveInt(options.limit);
+            if (status)
+                params.set("status", status);
+            if (source)
+                params.set("source", source);
+            if (limit)
+                params.set("limit", String(limit));
+            const suffix = params.toString() ? `?${params.toString()}` : "";
+            const data = await requestOxygen(`/api/cli/observability/runs${suffix}`);
+            if (!options.json)
+                writeObservabilityCapsNotice(data);
+            return data;
+        });
+    }))
+        .addCommand(new Command("approvals")
+        .description("List everything waiting for a human decision across workflows, publishing, message reviews, inbox reply drafts, and collaboration approval requests — the cross-primitive approvals inbox. Read-only: each item includes the exact command to resolve it and a web link to decide.")
+        // Keep --source values in sync with OBSERVABILITY_APPROVAL_SOURCES in
+        // apps/web/src/lib/observability-console.ts and the MCP tool enum. The API
+        // rejects any other value with invalid_request so a typo fails loudly.
+        .option("--source <sources>", "Comma-separated sources: workflow, publishing, message_review, inbox_draft, collab_request.")
+        .option("--limit <n>", "Maximum items per source (default 25, max 100). Counts reflect the returned page only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("observability approvals", options, async () => {
+            const params = new URLSearchParams();
+            const source = readOption(options.source);
+            const limit = readPositiveInt(options.limit);
+            if (source)
+                params.set("source", source);
+            if (limit)
+                params.set("limit", String(limit));
+            const suffix = params.toString() ? `?${params.toString()}` : "";
+            const data = await requestOxygen(`/api/cli/observability/approvals${suffix}`);
+            if (!options.json)
+                writeObservabilityCapsNotice(data);
+            return data;
+        });
+    }));
+}

package/dist/commands/orgs.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerOrgsFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/orgs.js

@@ -0,0 +1,237 @@
+import { emitCliFailure, emitSuccess, writeJson } from "../cli-output.js";
+import { formatCollabWriteResult, handleCollabAction, persistOrganizationSelection, readPositiveNumber, resolveActiveProfileWithSource } from "../command-support.js";
+import { addContractFlags, readContractFlags } from "../contract-flags.js";
+import { requestOxygen } from "../http-client.js";
+import { isRecord, readOption } from "../util.js";
+import { OxygenError, success } from "@oxygen/shared/cli-result";
+import { BILLING_OWNER_READ_CONTRACT } from "@oxygen/shared/contracts/billing-owner-read";
+import { Command } from "commander";
+// An `oxy_live_` key can only ever answer for the one workspace it is bound to,
+// so `orgs list` returns a single row and `orgs use` refuses — both truthfully,
+// and both indistinguishable from "this account has one workspace" if you only
+// read stdout. The server says which credential answered and whether it can
+// switch; mirror that on stderr, the same split writeDryRunNotice uses, so the
+// machine-read envelope stays clean. This is the line that would have stopped a
+// user from minting a 21st key that also could not switch.
+function writeCredentialNotice(credential) {
+    if (!credential || credential.switchable !== false)
+        return;
+    if (typeof credential.message === "string" && credential.message.trim()) {
+        process.stderr.write(`${credential.message}\n`);
+    }
+}
+async function handleOrgsListAction(options) {
+    try {
+        const data = await requestOxygen("/api/cli/orgs");
+        emitSuccess("orgs list", data, options);
+        writeCredentialNotice(data.credential);
+    }
+    catch (error) {
+        emitCliFailure("orgs list", error);
+    }
+}
+async function handleOrgUseAction(organization, options, command) {
+    try {
+        // Credentials stay ambient here: an OXYGEN_API_KEY in the environment
+        // outranks the stored profile inside requestOxygen, and passing the profile
+        // explicitly would silently select with the wrong one.
+        const data = await requestOxygen("/api/cli/orgs/select", {
+            method: "POST",
+            body: { organization },
+        });
+        const context = await resolveActiveProfileWithSource();
+        const profile = context.resolution.exists ? context.resolution.name : null;
+        const selectionPersisted = await persistOrganizationSelection({
+            profile,
+            credentials: context.resolution.credentials,
+            organization: data.currentOrganization,
+        });
+        // OXYGEN_ORG outranks the stored selection on every later command (the
+        // oxygen-dev wrapper exports one), so a selection it contradicts is saved
+        // but never used. Reported 2026-09-22: three "successful" selects in a row.
+        const envOrganization = process.env.OXYGEN_ORG?.trim();
+        const selected = data.currentOrganization;
+        const environmentOverride = envOrganization && selected
+            && envOrganization !== selected.id && envOrganization !== selected.slug
+            ? {
+                variable: "OXYGEN_ORG",
+                organization: envOrganization,
+                message: `OXYGEN_ORG=${envOrganization} is set, so later commands still use that workspace. Unset it, set it to ${selected.slug ?? selected.id}, or pass --org.`,
+            }
+            : null;
+        const result = {
+            ...data,
+            profile,
+            selection_persisted: selectionPersisted,
+            ...(environmentOverride ? { environment_override: environmentOverride } : {}),
+        };
+        if (options.json) {
+            writeJson(success(command, result));
+        }
+        else {
+            writeJson(result);
+        }
+        writeCredentialNotice(data.credential);
+        if (environmentOverride)
+            process.stderr.write(`${environmentOverride.message}\n`);
+    }
+    catch (error) {
+        emitCliFailure(command, error);
+    }
+}
+// Why each organization cannot pay for another workspace, in the user's words.
+// The codes are the server's; the sentences exist so a blocked `billing-link`
+// says what to fix instead of printing an enum.
+const BILLING_OWNER_INELIGIBLE_REASONS = {
+    not_admin: "You are not an admin of that organization.",
+    no_plan: "It has no active paid plan.",
+    trialing: "It is on a trial, and a trial only covers the workspace it started in.",
+    already_linked: "Its own billing is already covered by another organization.",
+};
+// `--owner` is optional because the case that matters is the plainest one: the
+// user pays for exactly one organization and wants this workspace on it. The
+// eligibility rules (admin seat, active paid plan, no trial) stay on the server
+// — the CLI only picks when the answer is unambiguous, and turns "which one?"
+// into a typed failure rather than a guess.
+async function resolveSoleBillingOwnerRef() {
+    const candidates = readBillingOwnerCandidates(await requestOxygen("/api/cli/orgs/billing-owners"));
+    const eligible = candidates.filter((candidate) => candidate.eligible);
+    if (eligible.length === 1)
+        return eligible[0].id;
+    if (eligible.length > 1) {
+        throw new OxygenError("missing_billing_owner", `${eligible.length} of your organizations can pay for this workspace, so Oxygen will not choose for you. Re-run with --owner <organization>.`, {
+            details: {
+                eligible_billing_owners: eligible.map((candidate) => ({
+                    organization_id: candidate.id,
+                    name: candidate.name,
+                })),
+                next_step: `oxygen orgs billing-link --owner ${eligible[0].id}`,
+            },
+        });
+    }
+    throw new OxygenError("no_eligible_billing_owner", candidates.length === 0
+        ? "You do not belong to another organization, so there is no existing plan to put this workspace on. Start one at https://oxygen-agent.com/billing."
+        : "None of your other organizations can pay for this workspace. Only an organization you administer that is on an active paid plan can cover another workspace — a trial cannot.", {
+        details: {
+            candidates: candidates.map((candidate) => ({
+                organization_id: candidate.id,
+                name: candidate.name,
+                ineligible_reason: candidate.ineligible_reason,
+                reason: candidate.ineligible_reason
+                    ? BILLING_OWNER_INELIGIBLE_REASONS[candidate.ineligible_reason] ?? null
+                    : null,
+            })),
+            next_step: "Start a plan on the organization that should pay at https://oxygen-agent.com/billing, then re-run `oxygen orgs billing-link`.",
+        },
+    });
+}
+// Both spellings of the reason field are read, the same way the billing-link
+// route accepts either spelling of its body keys: the rows come straight out of
+// the billing-ownership library, and a casing change there must not silently
+// downgrade "we picked your plan" into "you have no eligible plan".
+function readBillingOwnerCandidates(payload) {
+    const rows = isRecord(payload) && Array.isArray(payload.candidates) ? payload.candidates : [];
+    const candidates = [];
+    for (const row of rows) {
+        if (!isRecord(row) || typeof row.id !== "string" || !row.id)
+            continue;
+        const reason = row.ineligible_reason ?? row.ineligibleReason;
+        candidates.push({
+            id: row.id,
+            name: typeof row.name === "string" ? row.name : row.id,
+            eligible: row.eligible === true,
+            ineligible_reason: typeof reason === "string" ? reason : null,
+        });
+    }
+    return candidates;
+}
+export function registerOrgsFamily(program, handleAsyncAction) {
+    const billingOwnerReadFlags = { organization: { flag: "expected-organization", valueName: "<organization>" } };
+    program
+        .command("orgs")
+        .description("Switch between the organizations (workspaces) you belong to, and share one paid plan across them. If this workspace has no plan of its own, `orgs billing-link` puts it on a plan you already pay for somewhere else instead of buying a second subscription.")
+        .addCommand(new Command("list")
+        .description("List organizations available to the current CLI identity.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleOrgsListAction(options);
+    }))
+        .addCommand(new Command("use")
+        .description("Select the active organization for this CLI profile. Apps connected with OAuth (ChatGPT, Claude…) keep their own default workspace: `oxygen connectors`.")
+        .argument("<organization>", "Organization id, Clerk org id, or slug returned by orgs list.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (organization, options) => {
+        await handleOrgUseAction(organization, options, "orgs use");
+    }))
+        .addCommand(new Command("select")
+        .description("Alias for orgs use: this CLI profile only. For ChatGPT, Claude or another connected app, use `oxygen connectors set`.")
+        .argument("<organization>", "Organization id, Clerk org id, or slug returned by orgs list.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (organization, options) => {
+        await handleOrgUseAction(organization, options, "orgs select");
+    }))
+        .addCommand(addContractFlags(new Command("billing-owners"), BILLING_OWNER_READ_CONTRACT, billingOwnerReadFlags)
+        .description("Read-only, 0 Oxygen credits; does not reconcile credits. List the organizations that could pay for this workspace: which of the organizations you belong to can cover another workspace's credits, and for each of the rest, why it cannot.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("orgs billing-owners", options, () => {
+            const fields = readContractFlags(options, BILLING_OWNER_READ_CONTRACT, billingOwnerReadFlags);
+            const query = new URLSearchParams(Object.entries(fields).map(([key, value]) => [key, String(value)]));
+            return requestOxygen(`/api/cli/orgs/billing-owners${query.size ? `?${query}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("billing-link")
+        .description("Cover a workspace with another organization's paid plan instead of buying a second subscription. Omit --owner when exactly one owner is eligible; orgs billing-owners lists them. You must administer both organizations, the workspace must not hold its own live subscription, and an org-bound key can link only its workspace. The owner funds credits; data access stays unchanged. billing estimate reports sender_billing: credit_reservations uses the owner's credits, including when plan_tier is free; legacy sending_seats uses the owner's paid plan and seats. Connecting a sending account, BYOK and Instagram/TikTok/YouTube/Facebook publishing still need a paid plan. billing usage --group-by workspace reports each linked workspace's spend.")
+        .option("--owner <organization>", "Billing owner organization id, Clerk org id, or slug. Optional — when omitted, Oxygen uses your one eligible organization, and refuses to pick if there is more than one.")
+        .option("--organization <organization>", "Workspace organization to link. Defaults to the active organization.")
+        .option("--organization-id <id>", "Alias for --organization.")
+        .option("--monthly-credit-cap <credits>", "Optional monthly credit cap for this workspace. Omit it to leave any existing cap untouched.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("orgs billing-link", options, async () => {
+            const billingOwner = readOption(options.owner) ?? await resolveSoleBillingOwnerRef();
+            return requestOxygen("/api/cli/orgs/billing-link", {
+                method: "POST",
+                body: {
+                    billing_owner_organization_id: billingOwner,
+                    ...(readOption(options.organization) || readOption(options.organizationId)
+                        ? { organization_id: readOption(options.organization) ?? readOption(options.organizationId) }
+                        : {}),
+                    // The key is omitted, never sent as null, when the flag is
+                    // absent: the server treats a present key as an explicit write,
+                    // so sending it unconditionally would wipe an agency's
+                    // per-client cap on every re-link.
+                    ...(readOption(options.monthlyCreditCap)
+                        ? { monthly_credit_cap: readPositiveNumber(options.monthlyCreditCap) }
+                        : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("billing-unlink")
+        .description("Return a workspace to its own billing owner and credit balance. Its own subscription state, plan and sender_billing model determine which actions need a plan.")
+        .option("--organization <organization>", "Workspace organization to unlink. Defaults to the active organization.")
+        .option("--organization-id <id>", "Alias for --organization.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("orgs billing-unlink", options, () => requestOxygen("/api/cli/orgs/billing-unlink", {
+            method: "POST",
+            body: {
+                ...(readOption(options.organization) || readOption(options.organizationId)
+                    ? { organization_id: readOption(options.organization) ?? readOption(options.organizationId) }
+                    : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("member-role")
+        .description("Move a member between the admin and member workspace roles. ADMIN ONLY. This is the one Clerk membership change Oxygen makes — inviting people is still done in workspace settings. Use it to demote an admin before `approvals client grant`: a workspace admin's role overrides the restricted client role, so the grant is refused until they are a plain member.")
+        .argument("<email>", "Workspace member's email.")
+        .requiredOption("--role <role>", "admin or member.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (email, options) => {
+        await handleCollabAction("orgs member-role", options, () => requestOxygen("/api/cli/collab/members/workspace-role", {
+            method: "POST",
+            body: { email, role: readOption(options.role) },
+        }), formatCollabWriteResult);
+    }));
+}

package/dist/commands/people.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerPeopleFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;