@oxygen-agent/cli 1.922.14 → 1.948.1

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.922.14
+Version: 1.948.1

package/dist/admin-primary-providers-render.d.ts

@@ -0,0 +1,18 @@
+/** Age of an ISO stamp as a short human span, measured against `now`. */
+export declare function ago(iso: unknown, now?: Date): string;
+export type RenderOptions = {
+    /** Binary name to print inside suggested commands. */
+    binary?: string;
+    now?: Date;
+};
+/**
+ * Render the serialized primary-provider board as a human board.
+ *
+ * Mirrors the field groups `serializePrimaryProviderBoard` emits: freshness,
+ * summary, platform guards, one block per managed provider (posture with EVERY
+ * reason, health, split 7d traffic, 30d recency, balance with staleness and
+ * runway, COGS, rate policy, ceilings, breaker, links), the customer-keyed
+ * rows, routed intents with no primary grouped by why, and unresolved registry
+ * slugs.
+ */
+export declare function renderPrimaryProviderBoard(payload: unknown, options?: RenderOptions): string;

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

@@ -0,0 +1,371 @@
+// Human rendering for `oxygen admin primary-providers`.
+//
+// The board answers three operator questions — does each primary provider work,
+// what does it cost us, and what stops a runaway — and until this file existed
+// the CLI answered them with ~1,500 lines of raw JSON while the MCP tool printed
+// a worst-first summary. Same route, same payload, two completely different
+// things to read. This renders the same facts the MCP text summary and the web
+// board render, so the three surfaces agree in front of a human, not only in
+// JSON.
+//
+// Every field is read defensively: the CLI receives untyped JSON from a server
+// that may be older or newer than the binary, and a board that silently drops a
+// column an operator is looking for is the exact failure this file exists to
+// stop. Unknown/absent reads as "—", never as zero.
+function obj(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function arr(value) {
+    return Array.isArray(value) ? value : [];
+}
+function str(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function count(value) {
+    const parsed = num(value);
+    return parsed === null ? "—" : parsed.toLocaleString("en-US");
+}
+function usd(value) {
+    const parsed = num(value);
+    if (parsed === null)
+        return "—";
+    if (parsed === 0)
+        return "$0";
+    return parsed < 1
+        ? `$${parsed.toFixed(4)}`
+        : `$${parsed.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+function pct(value) {
+    const parsed = num(value);
+    if (parsed === null)
+        return "—";
+    if (parsed > 0 && parsed < 0.01)
+        return "<1%";
+    return `${Math.round(parsed * 100)}%`;
+}
+/** Age of an ISO stamp as a short human span, measured against `now`. */
+export function ago(iso, now = new Date()) {
+    const raw = str(iso);
+    if (!raw)
+        return "never";
+    const at = new Date(raw);
+    if (Number.isNaN(at.getTime()))
+        return "never";
+    const delta = Math.round((now.getTime() - at.getTime()) / 1000);
+    // A reset date is in the future; clamping it to "0s ago" reads as "just
+    // happened", which is the opposite of what it says.
+    const seconds = Math.abs(delta);
+    const suffix = delta < 0 ? "from now" : "ago";
+    if (seconds < 90)
+        return `${seconds}s ${suffix}`;
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 90)
+        return `${minutes}m ${suffix}`;
+    const hours = seconds / 3600;
+    if (hours < 48)
+        return `${hours.toFixed(1)}h ${suffix}`;
+    return `${Math.round(hours / 24)}d ${suffix}`;
+}
+function windowLabel(seconds) {
+    const parsed = num(seconds);
+    if (parsed === 60)
+        return "/min";
+    if (parsed === 3600)
+        return "/h";
+    if (parsed === 86400)
+        return "/day";
+    return parsed === null ? "" : `/${parsed}s`;
+}
+const POSTURE_RANK = { critical: 0, attention: 1, ok: 2, customer_keyed: 3 };
+function postureRank(level) {
+    return level === null ? 4 : (POSTURE_RANK[level] ?? 4);
+}
+/**
+ * One snapshot's freshness as a sentence. `as_of` on the board is render time;
+ * this is how old the data behind a column actually is — the fact `--refresh`
+ * exists to fix, so it prints above the provider table, not in a footnote.
+ */
+function freshnessPhrase(label, block, now) {
+    const row = obj(block);
+    if (!row)
+        return `${label} —`;
+    const asOf = str(row.as_of);
+    if (!asOf)
+        return `${label} never`;
+    const via = str(row.refreshed_via);
+    const level = str(row.level) ?? "";
+    return `${label} as of ${asOf}${via ? ` via ${via}` : ""} (${ago(asOf, now)}${level ? `, ${level}` : ""})`;
+}
+const STAGE_BY_SNAPSHOT = { health: "health", balance: "balances", cost: "costs" };
+/**
+ * Render the serialized primary-provider board as a human board.
+ *
+ * Mirrors the field groups `serializePrimaryProviderBoard` emits: freshness,
+ * summary, platform guards, one block per managed provider (posture with EVERY
+ * reason, health, split 7d traffic, 30d recency, balance with staleness and
+ * runway, COGS, rate policy, ceilings, breaker, links), the customer-keyed
+ * rows, routed intents with no primary grouped by why, and unresolved registry
+ * slugs.
+ */
+export function renderPrimaryProviderBoard(payload, options = {}) {
+    const now = options.now ?? new Date();
+    const binary = options.binary ?? "oxygen";
+    const board = obj(payload);
+    if (!board)
+        return "No board returned.";
+    const lines = [];
+    const out = (line = "") => lines.push(line);
+    out(`Primary managed providers — as of ${str(board.as_of) ?? "—"}`);
+    const freshness = obj(board.freshness);
+    if (freshness) {
+        out(`Snapshots: ${[
+            freshnessPhrase("health", freshness.health, now),
+            freshnessPhrase("balances", freshness.balance, now),
+            freshnessPhrase("costs", freshness.cost, now),
+        ].join(" · ")}`);
+        // Name the stale halves explicitly with the command that fixes them: a
+        // frozen board otherwise keeps announcing itself as current.
+        const stale = Object.entries(STAGE_BY_SNAPSHOT)
+            .filter(([key]) => {
+            const level = str(obj(freshness[key])?.level);
+            return level === "frozen" || level === "never";
+        })
+            .map(([, stage]) => stage);
+        if (stale.length > 0) {
+            out(`  ! ${stale.join(", ")} ${stale.length === 1 ? "is" : "are"} not current — re-run: ` +
+                `${binary} admin primary-providers --refresh --stages ${stale.join(",")}`);
+        }
+    }
+    const refresh = obj(board.refresh);
+    if (refresh) {
+        const ran = arr(refresh.ran).map((stage) => String(stage));
+        const skipped = arr(refresh.skipped).map((stage) => String(stage));
+        const duration = num(refresh.duration_ms);
+        out(`Refreshed: ${ran.length > 0 ? ran.join(", ") : "nothing"}` +
+            (skipped.length > 0 ? ` · skipped ${skipped.join(", ")}` : "") +
+            (duration === null ? "" : ` · ${(duration / 1000).toFixed(1)}s`));
+        for (const entry of arr(refresh.errors)) {
+            const error = obj(entry);
+            if (!error)
+                continue;
+            out(`  ! ${str(error.stage) ?? "stage"} failed: ${str(error.message) ?? "unknown error"}`);
+        }
+    }
+    const summary = obj(board.summary) ?? {};
+    out("");
+    out(`${count(summary.providers)} providers — ${count(summary.managed)} managed, ${count(summary.customer_keyed)} customer-keyed · ` +
+        `${count(summary.critical)} critical, ${count(summary.attention)} attention, ${count(summary.ok)} ok` +
+        ((num(summary.never_probed) ?? 0) > 0 ? `, ${count(summary.never_probed)} never probed` : "") +
+        ((num(summary.traffic_not_instrumented) ?? 0) > 0
+            ? `, ${count(summary.traffic_not_instrumented)} traffic not instrumented`
+            : "") +
+        ((num(summary.fallback_providers) ?? 0) > 0
+            ? ` · ${count(summary.fallback_providers)} default-chain fallback${(num(summary.fallback_providers) ?? 0) === 1 ? "" : "s"}` +
+                ((num(summary.fallback_critical) ?? 0) > 0 ? ` (${count(summary.fallback_critical)} critical)` : "")
+            : ""));
+    out(`COGS (managed primaries): 30d ${usd(summary.cost_30d_usd)} · 7d ${usd(summary.cost_7d_usd)}`);
+    out(renderGuards(obj(board.guards)));
+    const providers = arr(board.providers)
+        .map((row) => obj(row))
+        .filter((row) => row !== null)
+        .sort((a, b) => postureRank(str(obj(a.posture)?.level)) - postureRank(str(obj(b.posture)?.level)) ||
+        (str(a.provider) ?? "").localeCompare(str(b.provider) ?? ""));
+    const managed = providers.filter((row) => str(row.credential) === "managed");
+    const customerKeyed = providers.filter((row) => str(row.credential) !== "managed");
+    out("");
+    out("Managed primaries (worst first):");
+    if (managed.length === 0)
+        out("  (none)");
+    for (const row of managed)
+        out(renderProvider(row, now, binary));
+    if (customerKeyed.length > 0) {
+        out("");
+        out("Primary but customer-keyed (OXYGEN holds no managed key — these lanes run on the workspace's own key):");
+        for (const row of customerKeyed)
+            out(renderProvider(row, now, binary));
+    }
+    // A dry fallback account is invisible until a primary fails, which is
+    // exactly when nobody has time to notice it — so it renders here too.
+    const fallbacks = arr(board.default_chain_fallbacks)
+        .map((row) => obj(row))
+        .filter((row) => row !== null)
+        .sort((a, b) => postureRank(str(obj(a.posture)?.level)) - postureRank(str(obj(b.posture)?.level)) ||
+        (str(a.provider) ?? "").localeCompare(str(b.provider) ?? ""));
+    if (fallbacks.length > 0) {
+        out("");
+        out("Default-chain fallbacks (not primary anywhere — a routed chain reaches them when its primary fails):");
+        for (const row of fallbacks)
+            out(renderProvider(row, now, binary));
+    }
+    const intents = arr(board.intents_without_primary)
+        .map((row) => obj(row))
+        .filter((row) => row !== null);
+    if (intents.length > 0) {
+        out("");
+        out("Routed intents with no declared primary:");
+        for (const [kind, copy] of Object.entries(INTENT_KIND_COPY)) {
+            const group = intents.filter((row) => (str(row.kind) ?? "fallback_only") === kind);
+            if (group.length === 0)
+                continue;
+            out(`  ${copy}`);
+            for (const row of group) {
+                out(`    - ${str(row.function) ?? "?"}/${str(row.intent) ?? "?"} (${str(row.input_shape) ?? "?"})` +
+                    ` → ${str(row.first_routed_tool_id) ?? "nothing routed"}`);
+            }
+        }
+    }
+    const unresolved = arr(board.unresolved_providers)
+        .map((row) => obj(row))
+        .filter((row) => row !== null);
+    if (unresolved.length > 0) {
+        out("");
+        out(`! ${unresolved.length} routing-registry provider slug${unresolved.length === 1 ? "" : "s"} PROVIDER_INFO cannot resolve:`);
+        for (const row of unresolved) {
+            out(`    - ${str(row.provider) ?? "?"} (${str(row.tool_id) ?? "?"}, ${str(row.intent) ?? "?"})`);
+        }
+    }
+    const webUrl = str(board.web_url) ?? str(board.deepLink);
+    if (webUrl) {
+        out("");
+        out(`Open: ${webUrl}`);
+    }
+    return lines.join("\n");
+}
+const INTENT_KIND_COPY = {
+    fallback_only: "fallback only — paid routed steps exist but none is seeded primary (the real gap):",
+    preflight_only: "preflight only — every step is a free sizing/count probe (by design):",
+    no_routed_chain: "no routed chain — a ratified refusal, not a hole:",
+};
+function renderGuards(guards) {
+    if (!guards)
+        return "Guards: —";
+    const spend = obj(guards.managed_spend) ?? {};
+    const loop = arr(spend.loop_detector);
+    const breakerMs = num(guards.managed_provider_credit_breaker_window_ms);
+    const orgDaily = obj(guards.org_daily_guard);
+    const parts = [
+        `spend limiter ${spend.halted ? "HALTED" : spend.enforcing ? "enforcing" : "shadow"} (${count(spend.hard_limits)}/${count(spend.total_limits)} ceilings block, ${count(spend.open_breakers)} breakers open)`,
+        `loop detector ${loop.length === 0
+            ? "not seeded"
+            : loop.some((row) => str(obj(row)?.action) === "block")
+                ? "armed"
+                : "warn only"}`,
+        `credit breaker ${breakerMs === 0 ? "off" : breakerMs === null ? "—" : `${Math.round(breakerMs / 60_000)} min`}`,
+        `trigger caps ${str(obj(guards.trigger_default_caps)?.mode) ?? "—"}`,
+        `BYOK daily caps ${str(obj(guards.byok)?.daily_cap_mode) ?? "—"}`,
+    ];
+    if (orgDaily) {
+        parts.push(`org-daily guard warn ${count(orgDaily.warn_multiple_of_monthly_grant)}× / block ${count(orgDaily.block_multiple_of_monthly_grant)}× monthly grant`);
+    }
+    return `Guards: ${parts.join(" · ")}`;
+}
+function renderProvider(row, now, binary) {
+    const lines = [];
+    const posture = obj(row.posture) ?? {};
+    const health = obj(row.health) ?? {};
+    const traffic = obj(row.traffic_7d) ?? {};
+    const recent = obj(row.recent) ?? {};
+    const cost = obj(row.cost) ?? {};
+    const limits = obj(row.limits) ?? {};
+    const links = obj(row.links) ?? {};
+    const provider = str(row.provider) ?? "?";
+    const level = str(posture.level) ?? "unknown";
+    const functions = arr(row.functions).map((fn) => String(fn));
+    const probe = str(health.probe) ?? "none";
+    const healthStatus = str(health.latest_status) ?? (probe === "none" ? "unmonitored" : "no data");
+    const healthDetail = [
+        `${probe} probe`,
+        ago(health.last_checked_at, now),
+        num(health.uptime_pct_96h) === null ? null : `${pct(health.uptime_pct_96h)} up 96h`,
+        (num(health.degraded_pct_96h) ?? 0) > 0 ? `${pct(health.degraded_pct_96h)} degraded` : null,
+        (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("+")}` : ""} · ` +
+        `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";
+    const trafficLine = row.traffic_7d === undefined
+        ? "7d —"
+        : traffic.instrumented === false
+            ? `7d ${count(traffic.calls)} calls (NOT instrumented — this provider spent money but wrote no request ledger rows)`
+            : `7d ${count(traffic.calls)} calls · ${count(traffic.failures)} fail · ${count(traffic.not_found)} no-match(404) · ` +
+                `${count(traffic.vendor_rate_limited)} vendor-429 · ${count(traffic.self_paced_blocks)} self-paced · ` +
+                `${count(traffic.payment_failures)} 402 · ${count(traffic.credit_refusals)} credit-refused · ` +
+                `${count(traffic.workspaces)} ws · p95 ${num(traffic.duration_p95_ms) === null ? "—" : `${count(traffic.duration_p95_ms)} ms`} · ` +
+                `${count(traffic.credits_estimate)} cr (${scope.replace(/_/g, " ")})`;
+    lines.push(`      ${trafficLine} | last ok ${ago(recent.last_ok_at, now)} · last fail ${ago(recent.last_failure_at, now)} (${count(recent.lookback_days)}d)`);
+    lines.push(`      ${balancePhrase(obj(row.balance), now)} | ${costPhrase(cost)}`);
+    const policies = arr(limits.rate_policies).map((policy) => obj(policy)).filter((p) => p !== null);
+    const firstPolicy = policies[0];
+    const ceilings = arr(limits.ceilings).map((ceiling) => obj(ceiling)).filter((c) => c !== null);
+    const worstCeiling = [...ceilings].sort((a, b) => (num(b.utilization) ?? -1) - (num(a.utilization) ?? -1))[0];
+    const breaker = obj(limits.breaker);
+    lines.push(`      rate ${firstPolicy
+        ? `${count(firstPolicy.limit)}${windowLabel(firstPolicy.window_seconds)}` +
+            `${num(firstPolicy.max_in_flight) === null ? "" : ` · ${count(firstPolicy.max_in_flight)} in flight`}` +
+            ` · ${firstPolicy.window_expired === true ? "idle" : `${count(firstPolicy.current)} this window`}` +
+            `${(num(firstPolicy.rate_limited_hits_24h) ?? 0) > 0 ? ` · ${count(firstPolicy.rate_limited_hits_24h)} 429s/24h` : ""}` +
+            `${policies.length > 1 ? ` · +${policies.length - 1} more` : ""}`
+        : "NONE — unpaced"} | ceiling ${worstCeiling
+        ? `${pct(worstCeiling.utilization)} of ${ceilingLimit(worstCeiling)} (${str(worstCeiling.action) ?? "?"})${ceilings.length > 1 ? ` · +${ceilings.length - 1} more` : ""}`
+        : "none (global + category only)"} | breaker ${str(breaker?.manual_override) ?? str(breaker?.state) ?? "closed"}`);
+    // Every reason, never a slice: the third reason is routinely the one that
+    // explains the posture (a stale balance under a failing key).
+    for (const reason of arr(posture.reasons))
+        lines.push(`      ! ${String(reason)}`);
+    const linkParts = [
+        str(links.pricing_url) ? `pricing ${str(links.pricing_url)}` : null,
+        str(links.rate_limit_url) ? `rate limits ${str(links.rate_limit_url)}` : null,
+        str(links.subscription_url) ? `subscription ${str(links.subscription_url)}` : null,
+    ].filter((part) => part !== null);
+    if (linkParts.length > 0)
+        lines.push(`      ${linkParts.join(" · ")}`);
+    if (level === "critical" || level === "attention") {
+        lines.push(`      halt: ${binary} admin spend halt --scope provider --key ${provider}`);
+    }
+    return lines.join("\n");
+}
+function ceilingLimit(ceiling) {
+    const parts = [
+        num(ceiling.limit_usd) === null ? null : usd(ceiling.limit_usd),
+        num(ceiling.limit_calls) === null ? null : `${count(ceiling.limit_calls)} calls`,
+    ].filter((part) => part !== null);
+    return `${parts.join(" / ") || "—"}${windowLabel(ceiling.window_seconds)}`;
+}
+function balancePhrase(balance, now) {
+    if (!balance)
+        return "balance no balance API";
+    const status = str(balance.status) ?? "unknown";
+    const head = status === "ok"
+        ? num(balance.remaining) === null
+            ? "balance —"
+            : `balance ${count(balance.remaining)} ${str(balance.unit) ?? ""}`.trim()
+        : `balance ${status.replace(/_/g, " ")}`;
+    const detail = [
+        str(balance.plan_name),
+        num(balance.usd) === null ? null : usd(balance.usd),
+        num(balance.runway_days) === null ? null : `${(num(balance.runway_days) ?? 0).toFixed(1)}d runway`,
+        str(balance.resets_at) ? `resets ${ago(balance.resets_at, now)}` : null,
+        // Age is printed even when a reset date exists: a reset stamp says nothing
+        // about how old the number in front of it is.
+        `fetched ${ago(balance.fetched_at, now)}${balance.stale === true ? " (STALE)" : ""}`,
+        str(balance.error_message),
+    ].filter((part) => part !== null && part !== "");
+    return detail.length > 0 ? `${head} (${detail.join(", ")})` : head;
+}
+function costPhrase(cost) {
+    const source30 = str(cost.actual_source_30d);
+    const source7 = str(cost.actual_source_7d);
+    const detail = [
+        `30d ${source30 ? `actual (${source30})` : "modeled"}`,
+        `7d ${source7 ? `actual (${source7})` : "modeled"}`,
+        str(cost.pricing_model),
+        num(cost.monthly_usd) === null ? null : `${usd(cost.monthly_usd)}/mo flat`,
+        num(cost.cost_per_provider_credit_usd) === null ? null : `${usd(cost.cost_per_provider_credit_usd)}/cr`,
+    ].filter((part) => part !== null);
+    return `COGS 30d ${usd(cost.total_30d_usd)} / 7d ${usd(cost.total_7d_usd)} (${detail.join(", ")})`;
+}

package/dist/command-manifest.js

@@ -25,6 +25,7 @@ const COMMAND_SEARCH_STOP_WORDS = new Set([
 // leaf in the tree using that verb, so the default (mutates:false) would have
 // advertised the most consequential collaboration write as a read.
 const MUTATING_VERBS = new Set([
+    "brand-approve", "revoke-invite", "confirm",
     "accept", "ack", "add", "adopt", "apply", "approve", "archive",
     "assign", "attach",
     // `linkedin intent autoenroll` arms (or revokes) a STANDING grant to contact
@@ -83,14 +84,27 @@ 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",
+    // 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 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
     // flag neither authorizes nor caps later inference; only `copilot send` can
     // 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",
@@ -105,11 +119,25 @@ 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",
     // 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.

package/dist/functions-commands.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "commander";
+type JsonOptions = {
+    json?: boolean;
+};
+export declare function registerFunctionsCommands(program: Command, handle: (command: string, options: JsonOptions, action: () => Promise<unknown>) => Promise<void>): void;
+export {};

package/dist/functions-commands.js

@@ -0,0 +1,56 @@
+import { OxygenError } from "@oxygen/shared";
+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).")
+        .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.")
+        .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.")
+        .requiredOption("--definition-json <json>", "Draft object: {table,display_name,description?,inputs:[{column,key,required}],action_columns:[column],outputs:[{column,key,required}],default_max_credits_per_item,default_max_items?}. Saving requires display_name and the full contract.")
+        .option("--expected-draft-hash <hash>", "Reject saving if the draft has changed since inspection.")
+        .option("--json", "Print a JSON envelope.")
+        .action((ref, options) => handle("functions draft", options, () => requestOxygen("/api/cli/functions", { method: "POST", body: {
+            ...parseJsonObject(options.definitionJson),
+            operation: ref ? "save_draft" : "create_draft",
+            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.")
+        .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.")
+        .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.")
+        .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("--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.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, ref, options) => handle("functions bind", options, () => {
+        const cap = Number(options.maxCreditsPerItem);
+        if (!Number.isFinite(cap) || cap <= 0)
+            throw new OxygenError("invalid_number", "Expected a positive credit ceiling.");
+        if (!["empty_only", "overwrite"].includes(options.overwritePolicy))
+            throw new OxygenError("invalid_request", "Overwrite policy must be empty_only or overwrite.");
+        return requestOxygen("/api/cli/callables/bind", { method: "POST", body: {
+                table, callable: ref,
+                input_mapping: parseJsonObject(options.inputsJson), output_mapping: parseJsonObject(options.outputsJson),
+                max_credits_per_item: cap,
+                overwrite_policy: options.overwritePolicy, key: options.key, label: options.label,
+            } });
+    }));
+    for (const [command, status] of [["enable", "active"], ["disable", "disabled"]]) {
+        functions.command(`${command} <function>`).description(`${command === "enable" ? "Enable" : "Disable"} future Function invocations; captured runs are unchanged.`)
+            .option("--json", "Print a JSON envelope.")
+            .action((ref, options) => handle(`functions ${command}`, options, () => requestOxygen("/api/cli/functions", { method: "POST", body: { operation: "set_status", function: ref, status } })));
+    }
+}

package/dist/help.js

@@ -137,6 +137,7 @@ 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`,
         `  5. ${binaryName} recipes list --json       choose a play from the Recipe catalog for your goal`,

package/dist/http-client.d.ts

@@ -1,6 +1,8 @@
 import { type StoredCredentials } from "./credentials.js";
 import { type CliEndpoint } from "./runtime.js";
 type RequestOptions = {
+    /** Internal bounded file download; never follows a caller-supplied URL. */
+    binaryMaxBytes?: number;
     method?: "GET" | "POST" | "PATCH" | "DELETE";
     body?: Record<string, unknown>;
     formData?: FormData;
@@ -8,6 +10,8 @@ type RequestOptions = {
     requireAuth?: boolean;
     enforceMinimumCliVersion?: boolean;
     timeoutMs?: number;
+    /** Caller-owned deadline for multi-request operations such as render waiting. */
+    signal?: AbortSignal;
     traceId?: string;
     fetch?: typeof fetch;
     selectedOrganization?: string;

package/dist/http-client.js

@@ -7,6 +7,7 @@ const CLI_COMPATIBILITY_CHECK_TIMEOUT_MS = 5_000;
 const cliCompatibilityCheckKeys = new Set();
 export async function requestOxygen(// skipcq: JS-R1005
 path, options = {}) {
+    options.signal?.throwIfAborted();
     const loaded = options.credentials === undefined && options.requireAuth !== false
         ? await loadCredentialsWithEndpoint()
         : null;
@@ -25,10 +26,14 @@ path, options = {}) {
     // freshness probe, or the first thing a mispointed prod runbook gets is a
     // version complaint from dev instead of the host mismatch that explains it.
     assertResolvedApiUrl(endpoint);
-    const fetchImpl = options.fetch ?? fetch;
+    const baseFetch = options.fetch ?? fetch;
+    const fetchImpl = options.signal ? (input, init) => baseFetch(input, {
+        ...init, signal: init?.signal ? AbortSignal.any([options.signal, init.signal]) : options.signal,
+    }) : baseFetch;
     if (path !== "/api/health" && shouldCheckCliCompatibility(options)) {
         await ensureFreshCliForApiUrl(apiUrl, { fetch: fetchImpl, endpoint });
     }
+    options.signal?.throwIfAborted();
     const traceId = options.traceId ?? randomUUID();
     const headers = {
         Accept: "application/json",
@@ -68,15 +73,24 @@ path, options = {}) {
     const requestInit = {
         method: options.method ?? "GET",
         headers,
+        ...(options.binaryMaxBytes === undefined ? {} : { redirect: "error" }),
         ...(options.body ? { body: JSON.stringify(options.body) } : {}),
         ...(options.formData ? { body: options.formData } : {}),
     };
-    if (timeout.signal)
+    if (options.signal)
+        requestInit.signal = timeout.signal
+            ? AbortSignal.any([options.signal, timeout.signal]) : options.signal;
+    else if (timeout.signal)
         requestInit.signal = timeout.signal;
     try {
         response = await fetchImpl(`${apiUrl}${path}`, requestInit);
+        if (response.ok && options.binaryMaxBytes !== undefined) {
+            return await readBoundedBinaryResponse(response, options.binaryMaxBytes);
+        }
     }
     catch (error) {
+        if (error instanceof OxygenError)
+            throw error;
         if (timeout.timedOut() || (timeoutMs !== undefined && isAbortError(error))) {
             throw new OxygenError("network_timeout", "Oxygen API request timed out.", {
                 details: {
@@ -116,6 +130,39 @@ path, options = {}) {
     }
     return envelope.data;
 }
+async function readBoundedBinaryResponse(response, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 50 * 1024 * 1024)
+        throw new OxygenError("invalid_request", "Invalid file download limit.");
+    const length = response.headers.get("content-length");
+    if (length && Number(length) > maxBytes)
+        throw new OxygenError("file_too_large", "The file exceeds its download limit.");
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new OxygenError("invalid_response", "The download had no body.");
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > maxBytes)
+                throw new OxygenError("file_too_large", "The file exceeds its download limit.");
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
 export async function ensureFreshCliForApiUrl(apiUrl, options = {}) {
     const checkKey = `${apiUrl}|${OXYGEN_VERSION}`;
     if (cliCompatibilityCheckKeys.has(checkKey))