@oxygen-agent/cli 1.813.1 → 1.830.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.813.1
+Version: 1.830.1

package/dist/http-client.js

@@ -205,7 +205,7 @@ function warnIfCliIsOlderThanApi(serverVersion, endpoint) {
         return;
     staleCliWarningVersions.add(warningKey);
     process.stderr.write(`[${guidance.binaryName}] CLI version ${OXYGEN_VERSION} is older than Oxygen API version ${serverVersion}. `
-        + `${guidance.warningInstruction}\n`);
+        + `This compatible skew is non-blocking; the command can proceed. ${guidance.warningInstruction}\n`);
 }
 function isPatchOnlyVersionSkew(serverVersion, clientVersion) {
     const server = parseSemver(serverVersion);

package/dist/index.js

@@ -247,6 +247,7 @@ const OXYGEN_WORDMARK = [
     "  \\___/ /_/\\_\\   |_|   \\____|_____|_| \\_|",
 ].join("\n");
 const LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD = 500;
+const SAFE_IMPORT_WRITE_BATCH_SIZE = 500;
 // The only numbers on `tables import --help` used to be --batch-size (a
 // per-request chunk) and the background threshold, so users read 500 as a
 // per-file cap. Echo the real PLAN_LIMITS ceilings instead of restating them.
@@ -4715,7 +4716,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .command("tables")
         .description("Tenant workspace table commands.")
         .addCommand(new Command("create")
-        .description("Create a real Postgres-backed workspace table.")
+        .description("Create a real Postgres-backed workspace table. Free — 0 Oxygen credits. To create a table and import a file in one step, use `tables import --create <name>`.")
         .argument("<name>", "Display name for the table.")
         .requiredOption("--columns-json <json>", 'JSON array of column definitions, e.g. [{"key":"name","label":"Name","dataType":"text"},{"key":"domain","label":"Domain","dataType":"text"}]. Inspect an existing shape with `oxygen tables describe <table>`.')
         .option("--project <project>", "Project id or slug. Defaults to General.")
@@ -4750,6 +4751,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .description("Insert rows into a workspace table.")
         .argument("<table>", "Table id or slug.")
         .requiredOption("--rows-json <json>", 'JSON array of row objects keyed by column key, e.g. [{"name":"Acme","domain":"acme.test"},{"name":"Globex","domain":"globex.test"}].')
+        .option("--request-id <id>", "Stable retry key. Reuse it after a timeout to return the committed write without duplicating rows.")
         .option("--json", "Print a JSON envelope.")
         .action(async (table, options) => {
         await handleAsyncAction("tables insert", options, () => requestOxygen("/api/cli/tables/rows", {
@@ -4757,6 +4759,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             body: {
                 table,
                 rows: parseJsonArray(options.rowsJson),
+                ...(readOption(options.requestId) ? { request_id: readOption(options.requestId) } : {}),
             },
         }));
     }))
@@ -4832,7 +4835,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("import")
-        .description(`Import JSON, JSONL, CSV, or XLSX rows into a workspace table. Files over ${LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD} rows load durably in the background: the command returns a queued envelope and rows keep landing after it exits, so wait with the printed 'table-ingestions wait <id>' before reading row counts. ${IMPORT_FILE_LIMIT_HELP}`)
+        .description(`Import JSON, JSONL, CSV, or XLSX rows into a workspace table. The table write is free — 0 Oxygen credits. Files over ${LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD} rows load durably in the background: the command returns a queued envelope and rows keep landing after it exits, so wait with the printed 'table-ingestions wait <id>' before reading row counts. ${IMPORT_FILE_LIMIT_HELP}`)
         .argument("[table]", "Table id or slug. Omit when using --create.")
         .requiredOption("--file <path>", "Input file path.")
         .option("--format <format>", "json, jsonl, csv, or xlsx. Defaults from file extension.")
@@ -4840,7 +4843,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--create <name>", "Create a new table with columns inferred from the file before importing.")
         .option("--project <project>", "Project id or slug for --create. Defaults to General.")
         .option("--upsert-key <key>", "Column key used to upsert instead of inserting.")
-        .option("--batch-size <n>", "How many rows travel in one API request - a chunking knob, not a limit on the file. Defaults to 500; paid orgs may use up to 5000.")
+        .option("--batch-size <n>", "Requested rows per import chunk, not a limit on the file. Defaults to 500; values up to 5000 are accepted, but Oxygen splits writes to at most 500 rows (and smaller for wide rows) so they fit request and worker lease budgets.")
         .option("--background", "Enqueue durable import chunks for the background worker.")
         .option("--sync", `Force foreground import even for files above ${LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD} rows. That threshold picks foreground vs background; it does not cap how many rows a file may hold.`)
         .option("--max-concurrency <n>", "Maximum concurrent import chunks for background mode. Defaults to 5.")
@@ -4874,7 +4877,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--project <project>", "Project id or slug for the new table. Defaults to General. Ignored with --into.")
         .option("--into <table>", "Resume into an existing table (id or slug) instead of creating a new one. Requires --key. Use the table id printed by the failed run.")
         .option("--key <column>", "Upsert key column. When set, rows are matched by this key instead of blindly inserted, so re-running the import is idempotent (no duplicates). Required with --into.")
-        .option("--batch-size <n>", "Rows per write request. Defaults to 500; paid orgs may use up to 5000.")
+        .option("--batch-size <n>", "Requested rows per write group. Defaults to 500; values up to 5000 are accepted and split into safe writes of at most 500 rows.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("tables import-bundle", options, () => importTableBundle(options));
@@ -4909,6 +4912,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--fields <columns>", "Comma-separated column keys or ids to include.")
         .option("--filter-json <json>", "Legacy filter object or array, e.g. '{\"column\":\"mobile_phone_e164\",\"op\":\"is_null\"}'. Mutually exclusive with --filter-tree-json/--sort-json.")
         .option("--filter-tree-json <json>", "Airtable-style filter group, e.g. '{\"type\":\"group\",\"conjunction\":\"and\",\"children\":[{\"type\":\"leaf\",\"columnKey\":\"stage\",\"operator\":\"is\",\"value\":\"won\"}]}'. Mutually exclusive with --filter-json.")
+        .option("--formula-values <mode>", "Formula filters are refused by default because displayed formulas are evaluated live. Refresh the formula's stored cells with `columns run <table> <column> --force` (0 credits), then pass 'materialized'; filtering uses that stored snapshot and returns a freshness note.")
         .option("--sort-json <json>", "Ordered sort rules, e.g. '[{\"columnKey\":\"_created_at\",\"direction\":\"desc\"}]'. Earlier rules dominate. Mutually exclusive with --filter-json.")
         .option("--no-system-fields", "Omit _row_id, _created_at, and _updated_at from returned rows (included by default).")
         .option("--json", "Print a JSON envelope.")
@@ -4917,11 +4921,15 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             const limit = readPositiveInt(options.limit);
             const filters = readFilterJsonOption(options.filterJson);
             const filterTree = readJsonObjectOption(options.filterTreeJson);
+            const formulaValues = readFormulaValuesOption(options.formulaValues);
             const sorts = readSortJsonOption(options.sortJson);
             const offset = readPositiveInt(options.offset);
             if (filters && (filterTree || sorts)) {
                 throw new OxygenError("invalid_filter", "Pass either --filter-json (legacy) or --filter-tree-json/--sort-json, not both.", { exitCode: 1 });
             }
+            if (formulaValues && !filters && !filterTree) {
+                throw new OxygenError("invalid_filter", "--formula-values requires --filter-json or --filter-tree-json.", { exitCode: 1 });
+            }
             if (readOption(options.cursor) && offset) {
                 throw new OxygenError("invalid_request", "Pass either --cursor or --offset, not both.", { exitCode: 1 });
             }
@@ -4935,6 +4943,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                     ...(readOption(options.fields) ? { fields: readCsvOption(options.fields) } : {}),
                     ...(filters ? { filters } : {}),
                     ...(filterTree ? { filterTree } : {}),
+                    ...(formulaValues ? { formula_values: formulaValues } : {}),
                     ...(sorts ? { sorts } : {}),
                     ...(options.systemFields === false ? { include_system_fields: false } : {}),
                 },
@@ -7158,6 +7167,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--limit <n>", "Run the next N rows whose target cell is still empty (--force runs the first N regardless). Repeat until rowCount is 0 to page through a table. Defaults to 10; inline deterministic runs have a hard cap of 25.")
         .option("--all", "Run all rows. Requires --background.")
         .option("--filter-json <json>", "Row selector filter object or array for background runs. Do not combine with --all, --limit, or --row-id.")
+        .option("--formula-values <mode>", "With --filter-json on a formula column, first refresh that selector with `columns run <table> <column> --force` (0 credits), then pass 'materialized'. The run filters the stored snapshot and persists this freshness acknowledgement.")
         .option("--force", "Run even when the target cell already has a value.")
         .option("--connection-id <connection_id>", "Optional provider integration connection id.")
         .option("--background", "Create a durable background run for a free deterministic column. Paid AI/tool/enrichment/custom-HTTP server runs are always backgrounded.")
@@ -7174,11 +7184,18 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         const maxCredits = readPositiveNumber(options.maxCredits);
         const maxConcurrency = readPositiveInt(options.maxConcurrency);
         const filterSelection = readFilterSelectionOption(options.filterJson);
+        const formulaValues = readFormulaValuesOption(options.formulaValues);
+        if (formulaValues && !filterSelection) {
+            throw new OxygenError("invalid_selection", "--formula-values requires --filter-json on columns run.", { exitCode: 1 });
+        }
+        const effectiveFilterSelection = filterSelection
+            ? { ...filterSelection, ...(formulaValues ? { formula_values: formulaValues } : {}) }
+            : undefined;
         const selectedModes = [
             Boolean(options.all),
             limit !== undefined,
             Boolean(readOption(options.rowId)),
-            Boolean(filterSelection),
+            Boolean(effectiveFilterSelection),
         ].filter(Boolean).length;
         if (selectedModes > 1) {
             throw new OxygenError("invalid_selection", "Pass only one of --all, --limit, --row-id, or --filter-json.", {
@@ -7198,7 +7215,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                         exitCode: 1,
                     });
                 }
-                if (filterSelection) {
+                if (effectiveFilterSelection) {
                     throw new OxygenError("invalid_column_run", "--filter-json requires --background for columns run.", {
                         exitCode: 1,
                     });
@@ -7214,7 +7231,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 table,
                 column,
                 ...(options.all ? { selection: { mode: "all" } } : {}),
-                ...(filterSelection ? { selection: filterSelection } : {}),
+                ...(effectiveFilterSelection ? { selection: effectiveFilterSelection } : {}),
                 ...(!options.all && readOption(options.rowId) ? { row_id: readOption(options.rowId) } : {}),
                 ...(!options.all && !filterSelection && limit ? { limit } : {}),
                 ...(options.force ? { force: true } : {}),
@@ -7568,6 +7585,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--all", "Run against all rows, up to the server cap.")
         .option("--row-ids <csv>", "Comma-separated row UUIDs to run.")
         .option("--filter-json <json>", "Filter object or array for server-side row selection.")
+        .option("--formula-values <mode>", "With --filter-json on a formula column, first refresh that selector with `columns run <table> <column> --force` (0 credits), then pass 'materialized'; the durable row scope filters the stored snapshot and records this freshness acknowledgement.")
         .option("--force", "Run even when the target cell already has a value.")
         .option("--connection-id <connection_id>", "Optional provider integration connection id.")
         .option("--approved", "Confirm the paid table action run after inspecting a dry run or preview.")
@@ -9719,8 +9737,8 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--return <mode>", "Legacy response shape: raw, compact, or summary. Defaults to raw.")
         .option("--return-mode <mode>", "Response shape: raw, compact, or summary. Prefer summary for large search responses.")
         .option("--oxygen-cursor <cursor>", "Short Oxygen cursor returned as oxygen_next_cursor by a previous tool run.")
-        .option("--max-credits <n>", "Required credit ceiling for live runs of paid tools.")
-        .option("--approved", "Required for live runs of paid tools after inspecting dry-run output.")
+        .option("--max-credits <n>", "Credit ceiling for live paid tools; not needed for no-bill tools.")
+        .option("--approved", "Required for live paid tools and external writes after inspecting dry-run output.")
         .option("--json", "Print a JSON envelope.")
         .action(async (toolId, options) => {
         const maxCredits = readPositiveNumber(options.maxCredits);
@@ -13370,7 +13388,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     program.addCommand(new Command("mailboxes")
         .description("Native email sending pool: register/refresh Google/Microsoft mailboxes (including secure local credential-file transfer), pause/disable inboxes, connect EmailGuard monitoring, and inspect/control OXYGEN Warm-up. Fresh managed InboxKit Google/Microsoft/Azure orders activate exact-scope warm-up automatically after provisioning under their approved default-on add-on. Google reuses the managed credential just in time; Microsoft/Azure uses native export. Standalone warm-up plans and credit caps are for BYOK/imported mailboxes, managed opt-outs, or later separate enrollment. OXYGEN Warm-up never owns campaign dispatch. Safe import preflight: run `oxygen mailboxes compatibility --catalog-only --json`, then `oxygen mailboxes import --file <path> --validate-only --json` (add the credential source flags shown by import help when the file contains credentials).")
         .addCommand(new Command("list")
-        .description("List the org's sending mailboxes with provider, status, warmup state, source (managed = bought through Oxygen, byok = bring-your-own), and a pool overview (including counts by source). To see only Google/Microsoft mailboxes that still need OAuth connection and the right remedy for each, use `oxygen mailboxes oauth-health --json`.")
+        .description("List the org's sending mailboxes with provider, status, warmup state, source (managed = bought through Oxygen, byok = bring-your-own), worker-owned connectionRepair and warmupRepair state, and a pool overview (including counts by source). mode=automatic means OXYGEN owns the next bounded retry — do not ask for browser consent or disable/re-enable an existing warm-up seat. To see only Google/Microsoft mailboxes that still need OAuth connection, including attempt budgets and manual remedies, use `oxygen mailboxes oauth-health --json`.")
         .option("--status <status>", "Filter by status: active, paused, disabled, or provisioning (ordered, still being set up).")
         .option("--tag <tags>", "Comma-separated workspace tags — matches mailboxes carrying ANY of these tags (see `oxygen tags list`).")
         .option("--json", "Print a JSON envelope.")
@@ -13430,7 +13448,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         await handleAsyncAction("mailboxes health", options, () => requestOxygen("/api/cli/mailboxes/health"));
     }))
         .addCommand(new Command("compatibility")
-        .description("Read-only compatibility report for every selected mailbox: generic origin class, real infrastructure tier (including InboxKit Azure), OXYGEN native-send connection quality, OXYGEN Warm-up path, EmailGuard monitoring path, and exact next actions. Native send distinguishes destination-bound OAuth, provider-managed API transport, admin delegation, and authorization_required. Use --catalog-only for the compact workspace-independent import contract. JSON data.compatibility contains checked rows; data.import_methods and data.import_fields describe accepted transfer inputs; data.provider_matrix is the current public product matrix; data.non_transferable_auth names credentials that must be reconnected; data.summary rolls up states; data.web_url opens the pool. Downstream states distinguish credential_required, consent_required, and vendor_blocked. Never decrypts a credential or calls a downstream provider.")
+        .description("Read-only compatibility report for every selected mailbox: generic origin class, real infrastructure tier (including InboxKit Azure), OXYGEN native-send connection quality, OXYGEN Warm-up path, EmailGuard monitoring path, and exact next actions. Read automatic_repair for native send and warmup_automatic_repair for an existing warm-up seat: mode=automatic means OXYGEN owns the next bounded retry. Native send distinguishes destination-bound OAuth, provider-managed API transport, admin delegation, and authorization_required. Use --catalog-only for the compact workspace-independent import contract. JSON data.compatibility contains checked rows; data.import_methods and data.import_fields describe accepted transfer inputs; data.provider_matrix is the current public product matrix; data.non_transferable_auth names credentials that must be reconnected; data.summary rolls up states; data.web_url opens the pool. Downstream states distinguish credential_required, consent_required, and vendor_blocked. Never decrypts a credential or calls a downstream provider.")
         .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
         .option("--catalog-only", "Return only the bounded import-method, field, auth-boundary, and public provider catalogs; do not read or return workspace mailbox rows.")
         .option("--json", "Print a JSON envelope.")
@@ -13722,7 +13740,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("oauth-health")
-        .description("Show every Google/Microsoft inbox with neither a usable per-mailbox OAuth token nor verified delegation/application access. Results name connect_oauth_oxygen for imported/manual mailboxes and connect_oauth_inboxkit for that managed path. Microsoft can use one-admin tenant authorization for exact selected addresses or individual OAuth. Read-only — 0 Oxygen credits.")
+        .description("Show every Google/Microsoft inbox with neither a usable per-mailbox OAuth token nor verified delegation/application access. automatic_repair marks Zapmail-linked rows whose safe retries OXYGEN owns in the background; browser-consent rows remain explicit. Results name connect_oauth_oxygen for imported/manual mailboxes and connect_oauth_inboxkit for that managed path. Microsoft can use one-admin tenant authorization for exact selected addresses or individual OAuth. Read-only — 0 Oxygen credits; it can pause no mailbox and sends no email.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("mailboxes oauth-health", options, () => requestOxygen("/api/cli/mailboxes/oauth-health"));
@@ -16422,6 +16440,10 @@ function readTableRunSelection(options) {
     const limit = readPositiveInt(options.limit);
     const rowIds = readCsvOption(options.rowIds);
     const filterSelection = readFilterSelectionOption(options.filterJson);
+    const formulaValues = readFormulaValuesOption(options.formulaValues);
+    if (formulaValues && !filterSelection) {
+        throw new OxygenError("invalid_table_run", "--formula-values requires --filter-json on table-runs create.", { exitCode: 1 });
+    }
     const selectedModes = [hasAll, Boolean(limit), rowIds.length > 0, Boolean(filterSelection)].filter(Boolean).length;
     if (selectedModes > 1) {
         throw new OxygenError("invalid_table_run", "Pass only one of --all, --limit, --row-ids, or --filter-json.", {
@@ -16434,8 +16456,9 @@ function readTableRunSelection(options) {
         return { mode: "limit", limit };
     if (rowIds.length > 0)
         return { mode: "row_ids", row_ids: rowIds };
-    if (filterSelection)
-        return filterSelection;
+    if (filterSelection) {
+        return { ...filterSelection, ...(formulaValues ? { formula_values: formulaValues } : {}) };
+    }
     throw new OxygenError("invalid_table_run", "Pass --all, --limit, --row-ids, or --filter-json.", {
         exitCode: 1,
     });
@@ -17742,6 +17765,15 @@ function readSortJsonOption(value) {
     }
     return parsed;
 }
+function readFormulaValuesOption(value) {
+    const raw = readOption(value);
+    if (raw === null)
+        return null;
+    if (raw !== "materialized") {
+        throw new OxygenError("invalid_filter", "--formula-values must be 'materialized' when provided.", { details: { formula_values: raw }, exitCode: 1 });
+    }
+    return raw;
+}
 function parseStringArray(value) {
     const parsed = parseJsonArray(value);
     const labels = parsed
@@ -17778,6 +17810,7 @@ async function importRows(table, options) {
         });
     }
     const batchSize = normalizeImportBatchSize(options.batchSize);
+    const effectiveBatchSize = Math.min(batchSize, SAFE_IMPORT_WRITE_BATCH_SIZE);
     const sourceHash = hashImportFile(options.file);
     const shouldUseBackground = options.background
         || (!options.sync && parsedRows.length > LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD);
@@ -17791,6 +17824,7 @@ async function importRows(table, options) {
         const staged = await tryEnqueueStagedFileImport(table, options, format, parsedRows, {
             autoBackground: !options.background,
             sourceHash,
+            batchSize,
         }, preparedBackgroundTarget);
         if (staged)
             return withImportWaitNextStep(staged);
@@ -17810,11 +17844,14 @@ async function importRows(table, options) {
     let writeRequestCount = 0;
     let requestTooLargeRetries = 0;
     let minimumBatchSizeUsed = null;
-    for (const batch of chunk(target.rows, batchSize)) {
+    for (const [batchIndex, batch] of chunk(target.rows, effectiveBatchSize).entries()) {
         const result = await writeImportBatchWithAutoSplit({
             tableRef: target.tableRef,
             upsertKey: target.upsertKey,
             rows: batch,
+            ...(!target.upsertKey
+                ? { requestId: `tables-import:${sourceHash}:${batchIndex}` }
+                : {}),
         });
         rowCount += result.rowCount;
         insertedCount += result.insertedCount;
@@ -17844,7 +17881,8 @@ async function importRows(table, options) {
             ...(warningsTruncated ? { warningsTruncated: true } : {}),
         } : {}),
         batchCount: writeRequestCount,
-        batchSize,
+        batchSize: effectiveBatchSize,
+        ...(effectiveBatchSize !== batchSize ? { requestedBatchSize: batchSize } : {}),
         ...(requestTooLargeRetries > 0 ? {
             requestTooLargeRetries,
             minimumBatchSizeUsed,
@@ -17985,6 +18023,7 @@ async function writeImportBatchWithAutoSplit(input) {
                 table: input.tableRef,
                 rows: input.rows,
                 ...(input.upsertKey ? { key: input.upsertKey } : {}),
+                ...(!input.upsertKey && input.requestId ? { request_id: input.requestId } : {}),
             },
         });
         return summarizeImportBatchWrite(result, input.rows.length);
@@ -17998,10 +18037,12 @@ async function writeImportBatchWithAutoSplit(input) {
         const first = await writeImportBatchWithAutoSplit({
             ...input,
             rows: input.rows.slice(0, midpoint),
+            ...(input.requestId ? { requestId: `${input.requestId}:0` } : {}),
         });
         const second = await writeImportBatchWithAutoSplit({
             ...input,
             rows: input.rows.slice(midpoint),
+            ...(input.requestId ? { requestId: `${input.requestId}:1` } : {}),
         });
         return combineImportBatchWriteSummaries(first, second, 1);
     }
@@ -18055,47 +18096,55 @@ table, options, format, parsedRows, context, preparedTarget = null) {
     }
     const fileBuffer = readFileSync(options.file);
     const filename = basename(options.file);
+    const contentType = importFileContentType(format);
+    const traceId = randomUUID();
     // Probe for a presigned upload URL. If object storage isn't configured the
     // server returns object_storage_not_configured; signal the caller to fall
     // back to the inline multipart import by returning null.
-    let presigned;
-    try {
-        presigned = await requestOxygen("/api/cli/tables/import-url", {
-            method: "POST",
-            body: { file_name: filename, byte_length: fileBuffer.byteLength },
-        });
-    }
-    catch (error) {
-        if (error instanceof OxygenError && error.code === "object_storage_not_configured") {
-            return null;
+    const requestPresign = async () => {
+        try {
+            return await requestOxygen("/api/cli/tables/import-url", {
+                method: "POST",
+                body: {
+                    file_name: filename,
+                    content_type: contentType,
+                    byte_length: fileBuffer.byteLength,
+                    trace_id: traceId,
+                },
+            });
         }
-        throw error;
-    }
-    const uploadUrl = readRecordString(presigned, "upload_url");
-    const storageKey = readRecordString(presigned, "storage_key");
-    const storageBucket = readRecordString(presigned, "storage_bucket");
-    const storageProvider = readRecordString(presigned, "storage_provider") ?? "s3";
-    if (!uploadUrl || !storageKey)
+        catch (error) {
+            if (error instanceof OxygenError && error.code === "object_storage_not_configured") {
+                return null;
+            }
+            throw error;
+        }
+    };
+    let presigned = await requestPresign();
+    if (!presigned)
         return null;
     // Create the table for --create (or resolve the existing ref) before the
     // upload so a presign success always pairs with a real target.
     const target = preparedTarget ?? await prepareImportTarget(table, options, parsedRows);
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 300_000);
-    let putResponse;
-    try {
-        putResponse = await fetch(uploadUrl, {
-            method: "PUT",
-            body: new Uint8Array(fileBuffer),
-            signal: controller.signal,
-        });
-    }
-    finally {
-        clearTimeout(timer);
+    let putResponse = await putImportFile(presigned, fileBuffer, contentType);
+    // A direct-upload 403 most commonly means a stale/mismatched signature.
+    // Refresh once under the same client trace so a transient presign never
+    // strands a durable import, while persistent policy failures stay explicit.
+    if (putResponse.status === 403) {
+        const refreshed = await requestPresign();
+        if (refreshed) {
+            presigned = refreshed;
+            putResponse = await putImportFile(presigned, fileBuffer, contentType);
+        }
     }
     if (!putResponse.ok) {
-        throw new OxygenError("import_upload_failed", `Uploading the import file to object storage failed (HTTP ${putResponse.status}).`, { details: { status: putResponse.status }, exitCode: 1 });
+        throw new OxygenError("import_upload_failed", `Uploading the import file to object storage failed (HTTP ${putResponse.status}).`, { details: { status: putResponse.status, trace_id: traceId }, exitCode: 1 });
     }
+    const storageKey = readRecordString(presigned, "storage_key");
+    const storageBucket = readRecordString(presigned, "storage_bucket");
+    const storageProvider = readRecordString(presigned, "storage_provider") ?? "s3";
+    if (!storageKey)
+        return null;
     const result = await requestOxygen("/api/cli/tables/import-staged", {
         method: "POST",
         timeoutMs: 120_000,
@@ -18109,6 +18158,10 @@ table, options, format, parsedRows, context, preparedTarget = null) {
             byte_length: fileBuffer.byteLength,
             sha256: context.sourceHash,
             row_count: parsedRows.length,
+            batch_size: context.batchSize,
+            ...(readPositiveInt(options.maxConcurrency)
+                ? { max_concurrency: readPositiveInt(options.maxConcurrency) }
+                : {}),
             ...(target.upsertKey ? { upsert_key: target.upsertKey } : {}),
             ...(target.sourceKeyMap ? { source_key_map: target.sourceKeyMap } : {}),
         },
@@ -18120,10 +18173,40 @@ table, options, format, parsedRows, context, preparedTarget = null) {
         ...(target.tableWebUrl ? { table_web_url: target.tableWebUrl } : {}),
         background: true,
         autoBackground: context.autoBackground,
-        import_engine: "bulk_file_v1",
+        import_engine: "chunked_file_v2",
         storage_provider: storageProvider,
     };
 }
+async function putImportFile(presigned, fileBuffer, contentType) {
+    const uploadUrl = readRecordString(presigned, "upload_url");
+    if (!uploadUrl)
+        return new Response(null, { status: 500 });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 300_000);
+    try {
+        return await fetch(uploadUrl, {
+            method: "PUT",
+            headers: {
+                "content-type": contentType,
+                "content-length": String(fileBuffer.byteLength),
+            },
+            body: new Uint8Array(fileBuffer),
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function importFileContentType(format) {
+    if (format === "csv")
+        return "text/csv";
+    if (format === "xlsx")
+        return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    if (format === "jsonl")
+        return "application/x-ndjson";
+    return "application/json";
+}
 async function enqueueImportFile(table, options, format, batchSize, context, preparedTarget = null) {
     if (options.create && table) {
         throw new OxygenError("invalid_import_target", "Pass either a table argument or --create, not both.", {
@@ -18643,6 +18726,7 @@ options) {
         throw new OxygenError("invalid_input", "--file is required.", { exitCode: 1 });
     }
     const batchSize = normalizeImportBatchSize(options.batchSize);
+    const effectiveBatchSize = Math.min(batchSize, SAFE_IMPORT_WRITE_BATCH_SIZE);
     const raw = readFileSync(resolve(path), "utf8");
     const bundle = parseBundleFile(raw);
     const columns = bundle.columns.map(bundleColumnToCreateInput);
@@ -18721,13 +18805,13 @@ options) {
         file: path,
         tableId: newTableId,
         key: upsertKey ?? null,
-        batchSize,
+        batchSize: effectiveBatchSize,
     });
     let processed = 0;
     let insertedCount = 0;
     let updatedCount = 0;
-    for (let offset = 0; offset < stagedRows.length; offset += batchSize) {
-        const batch = stagedRows.slice(offset, offset + batchSize);
+    for (let offset = 0; offset < stagedRows.length; offset += effectiveBatchSize) {
+        const batch = stagedRows.slice(offset, offset + effectiveBatchSize);
         if (batch.length === 0)
             continue;
         try {

package/dist/runtime.js

@@ -43,7 +43,7 @@ export function resolveCliUpdateGuidance(endpoint, env = process.env, argv = pro
         return {
             binaryName,
             channel: "dev",
-            warningInstruction: "Rebuild `oxygen-dev` from the latest dev branch (`npm run install-dev-cli`) before using operational commands.",
+            warningInstruction: "Rebuild `oxygen-dev` from the latest dev branch (`npm run install-dev-cli`) to pick up the latest behavior.",
             failureInstruction: "Rebuild `oxygen-dev` from the latest dev branch (`npm run install-dev-cli`) before using this command.",
             details: {
                 cli_update_instruction: "Rebuild `oxygen-dev` from the latest dev branch (`npm run install-dev-cli`).",
@@ -67,7 +67,7 @@ export function resolveCliUpdateGuidance(endpoint, env = process.env, argv = pro
     return {
         binaryName,
         channel: "npm",
-        warningInstruction: "Run `oxygen update` before using operational commands.",
+        warningInstruction: "Run `oxygen update` to pick up the latest behavior.",
         failureInstruction: "Run `oxygen update` before using this command.",
         details: {
             cli_update_command: "oxygen update",

package/node_modules/@oxygen/shared/dist/capability-discovery.js

@@ -426,15 +426,15 @@ export const OXYGEN_CAPABILITY_ROUTES = [
         id: "connected-linkedin",
         layer: "External",
         primitive: null,
-        owns: "The workspace LinkedIn account network/private data and connected-account writes used by Signals, Messages, Sequences, and Publishing.",
+        owns: "The workspace LinkedIn account network/private data, relationship context such as mutual connections, and connected-account writes used by Signals, Messages, Sequences, and Publishing.",
         notFor: "Ordinary public or third-party LinkedIn research; use the cookieless native scraper.",
-        execution: "Use the owning primitive gateway; the connected account provides identity and transport, not a competing product runtime.",
+        execution: "For mutual/shared connection counts, resolve the connected account with `oxygen senders list --json`, inspect `oxygen tools get linkedin.users_get --json`, then run `oxygen tools run linkedin.users_get --input-json '{\"identifier\":\"<profile-url>\",\"account_id\":\"<connected-account-id>\",\"notify\":false}' --mode live --json`. This read is non-notifying and no-bill. An unavailable count is explicit and never means zero; retrying the same account/profile pair is not expected to reveal a provider-hidden count. Otherwise use the owning primitive gateway; the connected account provides identity and transport, not a competing product runtime.",
         posture: "mixed",
         gatewayTools: ["oxygen_senders_list", "oxygen_linkedin_connections_import", "oxygen_inbox_list"],
         gatewayCommands: ["senders list", "connections import", "inbox list"],
         skills: ["oxygen-linkedin-marketing", "oxygen-sequencer", "oxygen-unibox"],
         endpointSections: ["linkedin"],
-        intentTerms: ["my linkedin", "our linkedin", "own linkedin", "connected linkedin", "connections", "followers", "profile viewers", "sales navigator", "recruiter", "linkedin inbox"],
+        intentTerms: ["my linkedin", "our linkedin", "own linkedin", "connected linkedin", "connections", "mutual connections", "shared connections", "connections in common", "followers", "profile viewers", "sales navigator", "recruiter", "linkedin inbox"],
     },
     {
         id: "connected-whatsapp",
@@ -540,6 +540,13 @@ function explicitCapabilityIntent(query) {
     // published post still routes to Posts.
     if (isSecondPartyDecisionIntent(query))
         return ROUTE_BY_ID.get("collaboration") ?? null;
+    // A mutual/shared-connection count is relationship context that only a
+    // connected account can expose. Route it before the generic public-profile
+    // rule, which otherwise sees "LinkedIn profile" and sends the user to the
+    // cookieless research catalog that cannot answer this question.
+    if (isMutualLinkedInConnectionsIntent(query)) {
+        return ROUTE_BY_ID.get("connected-linkedin") ?? null;
+    }
     // A deferred acquisition motion starts with the public-data owner. This keeps
     // "find/qualify now, contact later" from skipping straight to the final write
     // step; the recommendation still hands the eventual initiation to Sequences.
@@ -617,6 +624,12 @@ function highestScoringRoute(query) {
     return best?.card ?? null;
 }
 function recommendationsFor(card, query) {
+    if (card.id === "connected-linkedin" && isMutualLinkedInConnectionsIntent(query)) {
+        return {
+            tools: ["oxygen_tools_get", "oxygen_tools_run_live", "oxygen_senders_list"],
+            commands: ["tools get", "tools run", "senders list"],
+        };
+    }
     if (card.id === "sending-infrastructure" && isMailboxDeleteIntent(query)) {
         return {
             tools: [
@@ -826,6 +839,12 @@ function recommendationsFor(card, query) {
     }
     return { tools: [...card.gatewayTools], commands: [...card.gatewayCommands] };
 }
+function isMutualLinkedInConnectionsIntent(query) {
+    const linkedInContext = /\blinkedin\b|\bprofiles?\b/.test(query);
+    const mutualContext = /\b(mutual|shared|in common)\b.{0,48}\b(connections?|relations?)\b/.test(query)
+        || /\b(connections?|relations?)\b.{0,48}\b(mutual|shared|in common)\b/.test(query);
+    return linkedInContext && mutualContext;
+}
 function isMailboxOnboardingIntent(query) {
     const operation = /\b(import|migrat\w*|onboard|register|upload|bring|connect existing|add existing)\b/.test(query);
     const mailboxScope = /\b(mailbox(?:es)?|inbox(?:es)?|sender accounts?|email accounts?|sending pool)\b/.test(query);

package/node_modules/@oxygen/shared/dist/sql-error.d.ts

@@ -1,5 +1,5 @@
 /** Normalized failure category, derived from SQLSTATE first, then errno/message. */
-export type SqlErrorCause = "connect_timeout" | "connection" | "statement_timeout" | "admin_shutdown" | "too_many_connections" | "insufficient_resources" | "auth" | "schema_drift" | "data_exception" | "integrity_constraint" | "serialization" | "deadlock" | "transaction_rollback" | "read_only" | "syntax_or_access" | "internal" | "unknown";
+export type SqlErrorCause = "connect_timeout" | "connection" | "lock_timeout" | "statement_timeout" | "admin_shutdown" | "too_many_connections" | "insufficient_resources" | "auth" | "schema_drift" | "data_exception" | "integrity_constraint" | "serialization" | "deadlock" | "transaction_rollback" | "read_only" | "syntax_or_access" | "internal" | "unknown";
 export type SqlErrorAttribution = {
     /** Postgres SQLSTATE (5 chars) when present; null for connection-level errnos. */
     pgCode: string | null;
@@ -53,6 +53,13 @@ export declare function redactSqlParameters(text: string): string;
  * 40001/40P01 knowledge lives in one place. Never throws.
  */
 export declare function isRetryableConcurrencyError(error?: unknown): boolean;
+/**
+ * True when a raw pg or drizzle-wrapped database failure is transient and a
+ * later durable-work attempt can safely try the transaction again. Unlike the
+ * narrower concurrency helper above, this includes lock/statement timeouts,
+ * connection failures, capacity pressure, and a temporarily read-only primary.
+ */
+export declare function isRetryableSqlError(error?: unknown): boolean;
 /**
  * True when a write lost a concurrency race and is safe to re-read / retry: a
  * serialization (40001) or deadlock (40P01) transaction abort, OR the XX000

package/node_modules/@oxygen/shared/dist/sql-error.js

@@ -55,6 +55,7 @@ const CONNECTION_MESSAGE = /connection terminated|connection reset|socket hang u
 const TRANSIENT_CAUSES = new Set([
     "connect_timeout",
     "connection",
+    "lock_timeout",
     "statement_timeout",
     "admin_shutdown",
     "too_many_connections",
@@ -170,6 +171,15 @@ export function isRetryableConcurrencyError(error) {
     const cause = describeSqlError(error)?.cause;
     return cause === "serialization" || cause === "deadlock";
 }
+/**
+ * True when a raw pg or drizzle-wrapped database failure is transient and a
+ * later durable-work attempt can safely try the transaction again. Unlike the
+ * narrower concurrency helper above, this includes lock/statement timeouts,
+ * connection failures, capacity pressure, and a temporarily read-only primary.
+ */
+export function isRetryableSqlError(error) {
+    return describeSqlError(error)?.transient === true;
+}
 /**
  * True when a write lost a concurrency race and is safe to re-read / retry: a
  * serialization (40001) or deadlock (40P01) transaction abort, OR the XX000
@@ -217,6 +227,7 @@ export function sqlErrorTelemetryAttributes(error) {
 // Specific SQLSTATEs that must resolve before the coarser class-prefix lookup
 // (e.g. 40001 serialization / 40P01 deadlock are more precise than class 40).
 const EXACT_SQLSTATE_CAUSES = new Map([
+    ["55P03", "lock_timeout"],
     ["57014", "statement_timeout"],
     ["53300", "too_many_connections"],
     ["40001", "serialization"],

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

@@ -1,4 +1,4 @@
-export declare const OXYGEN_VERSION = "1.813.1";
+export declare const OXYGEN_VERSION = "1.830.1";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";
 export declare const MANAGED_INBOX_MINIMUM_CLI_VERSION = "1.326.2";
 export declare const SUPPORT_AGENT_REPLY_MINIMUM_CLI_VERSION = "1.747.0";

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

@@ -1,4 +1,4 @@
-export const OXYGEN_VERSION = "1.813.1";
+export const OXYGEN_VERSION = "1.830.1";
 // 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.813.1",
+  "version": "1.830.1",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",