@oxygen-agent/cli 1.334.3 → 1.336.4

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.334.3
+Version: 1.336.4

package/dist/browser-login.d.ts

@@ -3,5 +3,21 @@ export type BrowserLoginSession = {
     waitForToken: () => Promise<string>;
     close: () => Promise<void>;
 };
+export type RelayLoginSession = BrowserLoginSession & {
+    confirmationCode: string;
+};
+/**
+ * Relay browser login (device-flow style): register a login request
+ * server-side, send the user to /settings/cli to approve it, and poll the
+ * claim endpoint until the session token is released. No loopback server is
+ * involved, so it works where the browser→localhost POST cannot: browsers
+ * enforcing the Local Network Access permission, SSH/WSL/remote terminals,
+ * containers. Any failure to CREATE the request (old server without the
+ * endpoint, network policy) is the caller's cue to fall back to the legacy
+ * loopback flow.
+ */
+export declare function createRelayLoginSession(apiUrl: string, options?: {
+    fetch?: typeof fetch;
+}): Promise<RelayLoginSession>;
 export declare function createBrowserLoginSession(apiUrl: string): Promise<BrowserLoginSession>;
 export declare function openBrowser(url: string): boolean;

package/dist/browser-login.js

@@ -1,11 +1,141 @@
 import { execFileSync } from "node:child_process";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
-import { OxygenError } from "@oxygen/shared";
+import { hostname } from "node:os";
+import { OXYGEN_VERSION, OxygenError, deriveCliLoginConfirmationCode } from "@oxygen/shared";
+import { requestOxygen } from "./http-client.js";
 import { readErrorMessage } from "./util.js";
 const CALLBACK_HOST = "127.0.0.1";
 const CALLBACK_PATH = "/cli/login/callback";
 const MAX_CALLBACK_BODY_BYTES = 32_000;
+const RELAY_CREATE_TIMEOUT_MS = 10_000;
+const RELAY_CLAIM_TIMEOUT_MS = 15_000;
+const DEFAULT_RELAY_POLL_INTERVAL_SECONDS = 2;
+const MAX_RELAY_POLL_INTERVAL_SECONDS = 10;
+const MAX_CONSECUTIVE_TRANSIENT_CLAIM_ERRORS = 5;
+// Claim-poll errors that read as infrastructure hiccups rather than a verdict
+// about the login request itself — tolerated a few times before giving up.
+const TRANSIENT_CLAIM_ERROR_CODES = new Set([
+    "network_error",
+    "network_timeout",
+    "invalid_response",
+    "unexpected_error",
+]);
+/**
+ * Relay browser login (device-flow style): register a login request
+ * server-side, send the user to /settings/cli to approve it, and poll the
+ * claim endpoint until the session token is released. No loopback server is
+ * involved, so it works where the browser→localhost POST cannot: browsers
+ * enforcing the Local Network Access permission, SSH/WSL/remote terminals,
+ * containers. Any failure to CREATE the request (old server without the
+ * endpoint, network policy) is the caller's cue to fall back to the legacy
+ * loopback flow.
+ */
+export async function createRelayLoginSession(apiUrl, options = {}) {
+    const state = randomBytes(32).toString("base64url");
+    // Empty token: pins the host to --api-url/profile resolution while sending no
+    // Authorization header — these endpoints are pre-auth by design.
+    const credentials = { token: "", apiUrl };
+    const requestOptions = options.fetch ? { fetch: options.fetch } : {};
+    const created = await requestOxygen("/api/cli/login-requests", {
+        method: "POST",
+        credentials,
+        body: {
+            state,
+            client: {
+                os: process.platform,
+                hostname: safeHostname(),
+                cli_version: OXYGEN_VERSION,
+            },
+        },
+        timeoutMs: RELAY_CREATE_TIMEOUT_MS,
+        ...requestOptions,
+    });
+    const pollIntervalMs = normalizePollIntervalSeconds(created.interval_seconds) * 1000;
+    const redirectParams = new URLSearchParams({
+        cli_state: state,
+        cli_login_request: "1",
+        source: "oxygen_cli",
+    });
+    const verificationUrl = new URL("/auth/sign-in", apiUrl);
+    verificationUrl.searchParams.set("redirect_url", `/settings/cli?${redirectParams.toString()}`);
+    verificationUrl.searchParams.set("source", "oxygen_cli");
+    let closed = false;
+    async function waitForToken() {
+        let transientErrors = 0;
+        while (!closed) {
+            await sleep(pollIntervalMs);
+            if (closed)
+                break;
+            let claim;
+            try {
+                claim = await requestOxygen("/api/cli/login-requests/claim", {
+                    method: "POST",
+                    credentials,
+                    body: { state },
+                    timeoutMs: RELAY_CLAIM_TIMEOUT_MS,
+                    ...requestOptions,
+                });
+            }
+            catch (error) {
+                if (error instanceof OxygenError && error.code === "rate_limit_exceeded") {
+                    await sleep(Math.max(readRetryAfterMs(error), pollIntervalMs));
+                    continue;
+                }
+                if (error instanceof OxygenError && TRANSIENT_CLAIM_ERROR_CODES.has(error.code)) {
+                    transientErrors += 1;
+                    if (transientErrors >= MAX_CONSECUTIVE_TRANSIENT_CLAIM_ERRORS)
+                        throw error;
+                    continue;
+                }
+                // Typed verdicts (login_request_expired / _not_found / _already_claimed)
+                // and anything else surface immediately.
+                throw error;
+            }
+            transientErrors = 0;
+            if (claim.status === "ready" && typeof claim.token === "string" && claim.token) {
+                return claim.token;
+            }
+        }
+        throw new OxygenError("browser_login_closed", "Browser login closed.", { exitCode: 1 });
+    }
+    return {
+        verificationUrl: verificationUrl.toString(),
+        confirmationCode: deriveCliLoginConfirmationCode(state),
+        waitForToken,
+        close: () => {
+            closed = true;
+            return Promise.resolve();
+        },
+    };
+}
+function normalizePollIntervalSeconds(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return DEFAULT_RELAY_POLL_INTERVAL_SECONDS;
+    }
+    return Math.min(MAX_RELAY_POLL_INTERVAL_SECONDS, Math.max(1, Math.trunc(value)));
+}
+function readRetryAfterMs(error) {
+    const details = error.details;
+    if (details && typeof details === "object" && !Array.isArray(details)) {
+        const seconds = details.retry_after_seconds;
+        if (typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0) {
+            return Math.min(seconds, 60) * 1000;
+        }
+    }
+    return DEFAULT_RELAY_POLL_INTERVAL_SECONDS * 1000;
+}
+function safeHostname() {
+    try {
+        return hostname();
+    }
+    catch {
+        return undefined;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 export async function createBrowserLoginSession(apiUrl) {
     const state = randomBytes(32).toString("base64url");
     let settled = false;

package/dist/index.js

@@ -13,7 +13,7 @@ import { AGENCY_DIRECTORY_REGIONS, AGENCY_DIRECTORY_SERVICES, describeWorkflowSt
 import { inferImportColumnLabels, inferRowsFileFormat, normalizeImportColumnKey, normalizeRowsForNewTable, normalizeRowsFormat, parseRowsFileBuffer, } from "@oxygen/shared/file-import";
 import { assertRecipeBundleSafe, assertWorkflowManifest, buildRecipeManifest, compileWorkflowDefinition, isAnyWorkflowManifest, isRecipeManifest, isWorkflowDefinition, isWorkflowManifest, } from "@oxygen/workflows";
 import { isRecipeDefinition } from "@oxygen/recipe-sdk";
-import { createBrowserLoginSession, openBrowser } from "./browser-login.js";
+import { createBrowserLoginSession, createRelayLoginSession, openBrowser } from "./browser-login.js";
 import { clearCredentials, defaultApiUrl, listCredentialProfiles, loadCredentials, normalizeApiUrl, pickProfileNameForIdentity, pickProfileNameForUserSession, resolveActiveProfile, saveCredentials, switchCredentialProfile, updateActiveOrganizationForProfile, } from "./credentials.js";
 import { ensureFreshCliForApiUrl, requestOxygen } from "./http-client.js";
 import { acquireMirrorLock, clearConflictFiles, deletePageFile, emptyMirrorState, findMirrorSlugByPageId, isFileDirty, listConflictFiles, listLocalMirrors, localPageSha256, markMirrorStale, mirrorExists, pageFilePath, planMirrorPush, purgeMirror, resetMirrorForFullResync, quarantineDirtyFile, readMirrorState, releaseMirrorLock, resolveDefaultConfigDir, resolveMirrorDir, writeGeneratedIndexFile, writeGeneratedLogFile, writeMirrorState, writePageFile, } from "./knowledge-mirror.js";
@@ -63,6 +63,7 @@ function buildFindBody(capability, options) {
     return body;
 }
 const BROWSER_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+const BROWSER_LOGIN_FALLBACK_HINT_MS = 15 * 1000;
 const OXYGEN_SPINNER_INTERVAL_MS = 90;
 const INITIAL_OXYGEN_PROFILE_ENV = process.env.OXYGEN_PROFILE?.trim() || null;
 let globalProfileFlag = null;
@@ -1595,7 +1596,7 @@ export function createProgram() {
     });
     program
         .command("login")
-        .description("Connect this terminal to Oxygen.")
+        .description("Connect this terminal to Oxygen. Opens the browser to approve this terminal (matching confirmation code shown in both); paste a token with --token instead if you prefer.")
         .option("--token <token>", "CLI API token created in the Oxygen dashboard.")
         .option("--api-url <url>", "Oxygen API URL. Defaults to OXYGEN_API_URL or https://oxygen-agent.com.")
         .option("--profile <name>", "Store credentials under a named CLI profile and make it active.")
@@ -1607,7 +1608,7 @@ export function createProgram() {
     });
     program
         .command("auth")
-        .description("Authentication helpers.")
+        .description("Authentication helpers for scripts and agents (non-interactive token use). Day to day, `oxygen login` and `oxygen whoami` are all you need.")
         .addCommand(new Command("use-token")
         .description("Store a CLI API token non-interactively.")
         .requiredOption("--token <token>", "CLI API token.")
@@ -1626,7 +1627,7 @@ export function createProgram() {
     }));
     program
         .command("profiles")
-        .description("Manage stored CLI credential profiles.")
+        .description("Manage stored CLI credential profiles (switch between workspaces and hosts). `oxygen login` creates or updates the active profile.")
         .addCommand(new Command("list")
         .description("List stored CLI credential profiles.")
         .option("--json", "Print a JSON envelope.")
@@ -3620,7 +3621,57 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             });
         });
     }));
-    tablesCommand.addCommand(new Command("promote")
+    tablesCommand.addCommand(new Command("relate")
+        .description("Relate two tables: define a relation column on the source that links rows to the target table. Works on ANY table — plain tables are registered under the hood automatically. Defaults to dry-run.")
+        .argument("<table>", "Source table id or slug.")
+        .argument("<slug>", "Relation slug — also the relation column key on the source, such as client.")
+        .requiredOption("--target-table <table>", "Target table id or slug. May also be a CRM object table (companies, people, deals).")
+        .option("--display-name <name>", "Display name for the relation column. Defaults to the slug in Title Case.")
+        .option("--cardinality <cardinality>", "one_to_one, one_to_many, many_to_one, or many_to_many (source:target). Default many_to_many. one_to_many means each source row links many target rows and each target row links back to one source.")
+        .option("--inverse-slug <slug>", "Inverse relation slug on the target; also creates the inverse relation column there.")
+        .option("--inverse-display-name <name>", "Display name for the inverse side.")
+        .option("--dry-run", "Preview the relation plan without writing.")
+        .option("--live", "Apply the relation. Default is dry-run.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, slug, options) => {
+        await handleAsyncAction("tables relate", options, () => requestOxygen("/api/cli/tables/relations", {
+            method: "POST",
+            body: {
+                table,
+                relationship: {
+                    slug,
+                    target_table: options.targetTable,
+                    ...(options.displayName ? { display_name: options.displayName } : {}),
+                    ...(options.cardinality ? { cardinality: options.cardinality } : {}),
+                    ...(options.inverseSlug ? { inverse_slug: options.inverseSlug } : {}),
+                    ...(options.inverseDisplayName ? { inverse_display_name: options.inverseDisplayName } : {}),
+                },
+                mode: options.live ? "live" : "dry_run",
+            },
+        }));
+    }))
+        .addCommand(new Command("link")
+        .description("Link one row to a row in the related table through a relation defined with `tables relate`. Defaults to dry-run.")
+        .argument("<table>", "Source table id or slug.")
+        .argument("<row_id>", "Source row id.")
+        .requiredOption("--relation <slug>", "Relation slug defined on the source table, such as client.")
+        .requiredOption("--target-row-id <row_id>", "Target row id in the related table.")
+        .option("--dry-run", "Preview the link (and any cardinality replacements) without writing.")
+        .option("--live", "Apply the link. Default is dry-run.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, rowId, options) => {
+        await handleAsyncAction("tables link", options, () => requestOxygen("/api/cli/tables/relations/link", {
+            method: "POST",
+            body: {
+                table,
+                row_id: rowId,
+                relation: options.relation,
+                target_row_id: options.targetRowId,
+                mode: options.live ? "live" : "dry_run",
+            },
+        }));
+    }))
+        .addCommand(new Command("promote")
         .description("Write bound rows' columns onto their matched CRM records (Records<->Tables). Free, but a truth write: previews by default, then re-run with --approved to write. Approved runs queue as a background run — watch with `oxygen table-runs wait <run_id>`.")
         .argument("<table>", "Table id or slug whose bound rows to promote.")
         .option("--object <slug>", "CRM object to promote onto (companies, people, deals, ...). Inferred when the table has exactly one bind column.")
@@ -13874,24 +13925,20 @@ async function buildPostLoginHint(activeProfile) {
 }
 async function promptForToken(options) {
     const fallbackLoginUrl = createCliLoginUrl(options.apiUrl);
+    const settingsUrl = cliSettingsUrl(options.apiUrl);
     if (options.json) {
-        throw new OxygenError("missing_token", "Pass a CLI API token with --token when using --json.", {
+        throw new OxygenError("missing_token", `Pass a CLI API token with --token when using --json. Create one at ${settingsUrl}.`, {
             details: { login_url: fallbackLoginUrl },
             exitCode: 1,
         });
     }
     if (!process.stdin.isTTY) {
-        throw new OxygenError("missing_token", "Pass a CLI API token with --token, or run `oxygen login` in an interactive terminal.", {
+        throw new OxygenError("missing_token", `Pass a CLI API token with --token, or run \`oxygen login\` in an interactive terminal. Create a token at ${settingsUrl}.`, {
             details: { login_url: fallbackLoginUrl },
             exitCode: 1,
         });
     }
-    const browserSession = options.browser
-        ? await createBrowserLoginSession(options.apiUrl).catch((error) => {
-            output.write(`Browser login unavailable: ${readErrorMessage(error)}\n`);
-            return null;
-        })
-        : null;
+    const browserSession = options.browser ? await createLoginSession(options.apiUrl) : null;
     if (browserSession) {
         const opened = openBrowser(browserSession.verificationUrl);
         if (opened) {
@@ -13901,7 +13948,19 @@ async function promptForToken(options) {
             output.write("Open this URL in your browser:\n");
             output.write(`${browserSession.verificationUrl}\n`);
         }
-        const spinner = startOxygenSpinner("Waiting for browser authorization");
+        if ("confirmationCode" in browserSession) {
+            output.write(`Confirmation code: ${browserSession.confirmationCode}\n`);
+            output.write("Approve the login in your browser — it must show this exact code.\n");
+        }
+        let spinner = startOxygenSpinner("Waiting for browser authorization");
+        // One-shot fallback hint: after 15s of silence, tell the user how to finish
+        // manually (blocked browsers and remote terminals used to look like a hang).
+        const hintTimer = setTimeout(() => {
+            spinner.stop();
+            output.write(`Still waiting? To finish manually: open ${settingsUrl}, create a session, and paste the \`oxygen login --token <token>\` command it shows.\n`);
+            spinner = startOxygenSpinner("Waiting for browser authorization");
+        }, BROWSER_LOGIN_FALLBACK_HINT_MS);
+        hintTimer.unref?.();
         try {
             const token = (await waitForBrowserToken(browserSession)).trim();
             if (token) {
@@ -13911,15 +13970,38 @@ async function promptForToken(options) {
         }
         catch (error) {
             spinner.fail(`Browser login unavailable: ${readErrorMessage(error)}`);
-            output.write("Paste a CLI API token instead.\n");
+            output.write(`Paste a CLI API token instead (create one at ${settingsUrl}).\n`);
         }
         finally {
+            clearTimeout(hintTimer);
             spinner.stop();
             await browserSession.close();
         }
     }
     return promptForManualToken();
 }
+/**
+ * Relay login first (server-side approve + claim — works in every browser and
+ * for remote/SSH terminals); legacy loopback only when the relay request cannot
+ * even be created (older server without the endpoint, network policy). Any
+ * create failure falls back — an old server answers with an HTML 404 that
+ * surfaces as invalid_response, not not_found.
+ */
+async function createLoginSession(apiUrl) {
+    try {
+        return await createRelayLoginSession(apiUrl);
+    }
+    catch {
+        // Fall through to the legacy loopback handoff.
+    }
+    try {
+        return await createBrowserLoginSession(apiUrl);
+    }
+    catch (error) {
+        output.write(`Browser login unavailable: ${readErrorMessage(error)}\n`);
+        return null;
+    }
+}
 async function promptForManualToken() {
     const restoreEcho = muteTokenEcho();
     const rl = createInterface({ input, output });
@@ -13961,6 +14043,9 @@ function createCliLoginUrl(apiUrl) {
     url.searchParams.set("source", "oxygen_cli");
     return url.toString();
 }
+function cliSettingsUrl(apiUrl) {
+    return new URL("/settings/cli", apiUrl).toString();
+}
 function startOxygenSpinner(message) {
     if (!output.isTTY) {
         output.write(`${message}...\n`);

package/node_modules/@oxygen/shared/dist/cli-login-code.d.ts

@@ -0,0 +1,3 @@
+export declare function isValidCliLoginState(value: string): boolean;
+/** Uppercase first 8 hex chars of sha256(domain + state), formatted XXXX-XXXX. */
+export declare function deriveCliLoginConfirmationCode(state: string): string;

package/node_modules/@oxygen/shared/dist/cli-login-code.js

@@ -0,0 +1,30 @@
+import { createHash } from "node:crypto";
+/**
+ * Confirmation-code derivation for the CLI relay browser login ("login request")
+ * flow. The CLI generates a 32-byte base64url `state`, registers its hash with
+ * POST /api/cli/login-requests, and polls the claim endpoint; the signed-in
+ * /settings/cli page approves the request after the user compares the code it
+ * shows with the code the CLI printed.
+ *
+ * The code is a human-comparable fingerprint of `state` — a guard against
+ * approving the wrong terminal (two logins racing, a stale tab), NOT a security
+ * boundary: approval authority is the signed-in click, and secrecy lives in the
+ * 256-bit state itself, which is stored hash-only server-side. Both consumers
+ * are Node (CLI prints it; the API derives it at create time and returns it to
+ * the panel via lookup), so this stays a plain node:crypto helper — the browser
+ * never computes it.
+ */
+const CLI_LOGIN_CODE_DOMAIN = "oxygen_cli_login_code_v1:";
+/** 32 random bytes, base64url — always 43 chars of [A-Za-z0-9_-]. */
+const CLI_LOGIN_STATE_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+export function isValidCliLoginState(value) {
+    return CLI_LOGIN_STATE_PATTERN.test(value);
+}
+/** Uppercase first 8 hex chars of sha256(domain + state), formatted XXXX-XXXX. */
+export function deriveCliLoginConfirmationCode(state) {
+    const digest = createHash("sha256")
+        .update(`${CLI_LOGIN_CODE_DOMAIN}${state}`, "utf8")
+        .digest("hex");
+    const compact = digest.slice(0, 8).toUpperCase();
+    return `${compact.slice(0, 4)}-${compact.slice(4)}`;
+}

package/node_modules/@oxygen/shared/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from "./billing.js";
 export * from "./budget-scopes.js";
 export * from "./cell-format.js";
 export * from "./cli-envelope.js";
+export * from "./cli-login-code.js";
 export * from "./cli-result.js";
 export * from "./column-types.js";
 export * from "./credit-guidance.js";

package/node_modules/@oxygen/shared/dist/index.js

@@ -5,6 +5,7 @@ export * from "./billing.js";
 export * from "./budget-scopes.js";
 export * from "./cell-format.js";
 export * from "./cli-envelope.js";
+export * from "./cli-login-code.js";
 export * from "./cli-result.js";
 export * from "./column-types.js";
 export * from "./credit-guidance.js";

package/node_modules/@oxygen/shared/dist/version.d.ts

@@ -1,3 +1,3 @@
-export declare const OXYGEN_VERSION = "1.334.3";
+export declare const OXYGEN_VERSION = "1.336.4";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";
 export declare const MANAGED_INBOX_MINIMUM_CLI_VERSION = "1.326.2";

package/node_modules/@oxygen/shared/dist/version.js

@@ -1,4 +1,4 @@
-export const OXYGEN_VERSION = "1.334.3";
+export const OXYGEN_VERSION = "1.336.4";
 // The GLOBAL CLI compatibility floor: the oldest CLI allowed to call any
 // operational route. Raising it hard-rejects every older CLI from the entire
 // product, so it obeys one law, enforced by scripts/ci/cli-min-version-gate.mjs:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxygen-agent/cli",
-  "version": "1.334.3",
+  "version": "1.336.4",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",