@oxygen-agent/cli 1.1010.721 → 1.1010.950

package/dist/run-wait.d.ts

@@ -8,7 +8,9 @@ export interface CliRunWaitConfig {
     defaultTimeoutSeconds: number;
     defaultIntervalSeconds: number;
     /** Fetches the latest run snapshot to inspect this poll. */
-    fetchRun: () => Promise<Record<string, unknown>>;
+    fetchRun: (signal?: AbortSignal) => Promise<Record<string, unknown>>;
+    /** Opt in only for read-only polls; retries share the original deadline. */
+    retryTransientNetworkErrors?: boolean;
     /** True when the run status is terminal for this resource. */
     isTerminal: (status: string | null) => boolean;
     /** Builds the response once a terminal status is observed. */

package/dist/run-wait.js

@@ -8,12 +8,26 @@ export async function waitForCliRun(config) {
     const startedAt = Date.now();
     const deadline = startedAt + timeoutSeconds * 1000;
     let polls = 0;
+    let latestRun = null;
+    let status = null;
     while (true) {
-        polls += 1;
-        const latestRun = await config.fetchRun();
-        const status = readRecordString(latestRun, "status");
-        if (config.isTerminal(status)) {
-            return config.shapeTerminal(latestRun, status, polls, Date.now() - startedAt);
+        if (Date.now() < deadline) {
+            polls += 1;
+            const signal = config.retryTransientNetworkErrors
+                ? AbortSignal.timeout(Math.max(1, deadline - Date.now())) : undefined;
+            try {
+                latestRun = await config.fetchRun(signal);
+                status = readRecordString(latestRun, "status");
+                if (config.isTerminal(status)) {
+                    return config.shapeTerminal(latestRun, status, polls, Date.now() - startedAt);
+                }
+            }
+            catch (error) {
+                const transient = error instanceof OxygenError
+                    && (error.code === "network_error" || error.code === "network_timeout");
+                if (!config.retryTransientNetworkErrors || (!transient && !signal?.aborted))
+                    throw error;
+            }
         }
         const remainingMs = deadline - Date.now();
         if (remainingMs <= 0) {

package/dist/sender-limits-flags.d.ts

@@ -0,0 +1,14 @@
+import { type ContractFlagOverlay } from "./contract-flags.js";
+/**
+ * `--working-days` → ISO weekday numbers. Accepts day names or 1-7, comma
+ * separated, and ranges (`mon-fri`, `1-5`). A token it cannot read is sent as
+ * given so the server's invalid_working_hours error names it.
+ */
+export declare function parseWorkingDaysOption(value: string): unknown[];
+export declare const SENDER_LIMITS_FLAG_OVERLAY: ContractFlagOverlay;
+/**
+ * The limits PATCH body for the flags given. A warm-up start date wins over
+ * --warmup-restart/--warmup-disable (the route reads it first anyway), so the
+ * body carries only the one it will act on. Throws when no flag was given.
+ */
+export declare function buildSenderLimitsBody(options: Record<string, unknown>): Record<string, unknown>;

package/dist/sender-limits-flags.js

@@ -0,0 +1,157 @@
+// `oxygen senders limits set` (and `whatsapp limits set`, which shares the body
+// builder): flags generated from SENDER_LIMITS_PATCH_CONTRACT, the contract the
+// MCP tool and the route use too. This overlay only keeps the flag names and
+// help text the command shipped with before the contract existed.
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { LINKEDIN_SENDER_LIMIT_DEFAULTS, LINKEDIN_SENDER_LIMIT_MAXIMUMS, } from "@oxygen/shared/linkedin-sequences";
+import { SENDER_LIMITS_PATCH_CONTRACT } from "@oxygen/shared/contracts/sender-limits";
+import { readContractFlags } from "./contract-flags.js";
+/** "<text> (default N, max M)." for a LinkedIn sender limit flag, from the enforced constants. */
+function linkedInLimitHelp(key, text) {
+    return `${text} (default ${LINKEDIN_SENDER_LIMIT_DEFAULTS[key]}, max ${LINKEDIN_SENDER_LIMIT_MAXIMUMS[key]}).`;
+}
+const LIMIT_FLAG_HELP = {
+    invites_per_day: "Daily LinkedIn connection invites cap",
+    invites_per_week: "Weekly LinkedIn connection invites cap",
+    messages_per_day: "Daily direct messages cap",
+    inmails_per_day: "Daily InMail cap",
+    inmails_per_month: "InMail cap over a rolling 30 days",
+    profile_views_per_day: "Daily profile views cap; the member is notified",
+    profile_lookups_per_day: "Daily invisible profile and company lookups cap",
+    endorsements_per_day: "Daily skill endorsements cap",
+    withdrawals_per_day: "Daily cap on withdrawing sent invitations; reading the sent list uses the read budgets",
+    posts_per_day: "Daily posts to the account's own feed, from every caller; not counted in the total",
+    follows_per_day: "Daily follows cap",
+    likes_per_day: "Daily likes cap",
+    comments_per_day: "Daily comments cap",
+    total_actions_per_day: "Daily cap across all send/action types except posts",
+    relations_reads_per_day: "Daily cap on relations/connections list reads, the scrape ban vector",
+    messages_reads_per_day: "Daily cap on chat and message-history reads",
+    searches_per_day: "Daily cap on LinkedIn search executions",
+    sales_nav_search_results_per_day: "Daily cap on Sales Navigator search result rows fetched",
+    api_reads_per_day: "Daily cap on all other LinkedIn API reads",
+    total_reads_per_day: "Daily cap across all read units",
+    min_action_spacing_seconds: "Minimum seconds between actions",
+    action_spacing_jitter_seconds: "Random jitter seconds added to action spacing",
+    interactive_min_spacing_seconds: "Minimum seconds between human-sent Unibox actions",
+    interactive_spacing_jitter_seconds: "Random jitter seconds added to human-sent Unibox action spacing",
+    interactive_sends_per_hour: "Hourly cap on human-sent Unibox actions",
+    relations_ingest_reads_per_day: "Daily cap on background connection, follower and sent-invite list reads (imports and the withdrawal drip)",
+    api_ingest_reads_per_day: "Daily cap on background engagement, post-metric and profile-viewer reads",
+    messages_ingest_reads_per_day: "Daily cap on background message-history backfill reads",
+    network_backfill_reads_per_day: "Daily network-capture reads while the first walk of connections and followers runs",
+    network_delta_reads_per_day: "Daily network-capture reads once that first walk is done",
+};
+const LIMIT_FLAG_NAMES = {
+    min_action_spacing_seconds: "min-spacing-seconds",
+    action_spacing_jitter_seconds: "spacing-jitter-seconds",
+};
+const WORKING_DAY_NAMES = {
+    mon: 1, monday: 1, tue: 2, tues: 2, tuesday: 2, wed: 3, wednesday: 3, thu: 4, thur: 4, thurs: 4, thursday: 4,
+    fri: 5, friday: 5, sat: 6, saturday: 6, sun: 7, sunday: 7,
+};
+/**
+ * `--working-days` → ISO weekday numbers. Accepts day names or 1-7, comma
+ * separated, and ranges (`mon-fri`, `1-5`). A token it cannot read is sent as
+ * given so the server's invalid_working_hours error names it.
+ */
+export function parseWorkingDaysOption(value) {
+    const day = (token) => {
+        const lower = token.trim().toLowerCase();
+        if (/^[1-7]$/.test(lower))
+            return Number(lower);
+        return WORKING_DAY_NAMES[lower] ?? null;
+    };
+    const days = [];
+    for (const token of value.split(",").map((part) => part.trim()).filter(Boolean)) {
+        const [from, to, ...rest] = token.split("-");
+        const start = from !== undefined ? day(from) : null;
+        const end = to !== undefined ? day(to) : null;
+        if (rest.length === 0 && start !== null && end !== null && start <= end) {
+            for (let current = start; current <= end; current += 1)
+                days.push(current);
+        }
+        else if (to === undefined && start !== null) {
+            days.push(start);
+        }
+        else {
+            days.push(token);
+        }
+    }
+    return days;
+}
+const limitFlags = Object.fromEntries(Object.keys(LIMIT_FLAG_HELP).map((key) => [
+    `limits.${key}`,
+    {
+        ...(LIMIT_FLAG_NAMES[key] ? { flag: LIMIT_FLAG_NAMES[key] } : {}),
+        valueName: "<n>",
+        help: linkedInLimitHelp(key, LIMIT_FLAG_HELP[key]),
+    },
+]));
+export const SENDER_LIMITS_FLAG_OVERLAY = {
+    limits: { flatten: true },
+    ...limitFlags,
+    "working_hours.timezone": {
+        flag: "timezone",
+        valueName: "<tz>",
+        help: "IANA timezone for the working hours and the daily counter reset, e.g. Europe/Berlin. Defaults to the zone of the country chosen at connect.",
+    },
+    "working_hours.days": {
+        flag: "working-days",
+        valueName: "<days>",
+        parse: parseWorkingDaysOption,
+        help: "Days LinkedIn actions may run: mon-fri, mon,wed,fri, or ISO numbers 1-7 (1 = Monday). A weekday-only window leaves a visible two-day gap every week.",
+    },
+    "working_hours.start": { valueName: "<HH:MM>", help: "Local time working hours start, e.g. 09:00." },
+    "working_hours.end": { valueName: "<HH:MM>", help: "Local time working hours end (exclusive), e.g. 18:00. Must be after the start." },
+    "warmup.enabled": {
+        pair: {
+            on: "warmup-restart",
+            onHelp: "Start (or restart) the warm-up ramp now — gradually raises this account's invite + message caps to full over ~2 weeks.",
+            off: "warmup-disable",
+            offHelp: "Turn off warm-up for this account (treat it as already warm and use its full configured caps).",
+        },
+    },
+    // `--warmup-disable` already sends the disable; no separate --clear flag.
+    "warmup.start_date": {
+        valueName: "<date>",
+        noClear: true,
+        help: "Set the warm-up start date (ISO, e.g. 2026-01-31). A past date credits prior warming and advances the ramp.",
+    },
+    read_warmup: {
+        pair: {
+            on: "read-warmup-restart",
+            onHelp: "Restart the READ warm-up ramp from today, so network capture eases back in from 5 reads a day. Also clears --read-warmup-disable.",
+            off: "read-warmup-disable",
+            offHelp: "Turn off the READ warm-up ramp for this account. Network capture (`oxygen linkedin network setup`) eases a newly armed account in at 5 → 10 → 20 reads a day over two weeks; this runs it at the full read budget immediately. Separate from --warmup-disable, which governs invites and messages.",
+        },
+    },
+    warmup_preset: {
+        valueName: "<preset>",
+        help: "Warm-up ramp curve: conservative (~3 weeks), standard (~2 weeks, default), or fast (~1 week for an aged account).",
+    },
+    randomize_daily_caps: {
+        flag: "randomize-caps",
+        help: "Randomise this account's daily send caps to 80-100% of configured so daily volume varies instead of hitting the same cap every day.",
+        negateHelp: "Turn off randomised daily caps (use the exact configured caps every day).",
+    },
+    weekend_full_volume: {
+        help: "Keep full daily send caps on Saturday and Sunday (by default they run at half).",
+        negateHelp: "Run daily send caps at half on Saturday and Sunday again (the default).",
+    },
+};
+/**
+ * The limits PATCH body for the flags given. A warm-up start date wins over
+ * --warmup-restart/--warmup-disable (the route reads it first anyway), so the
+ * body carries only the one it will act on. Throws when no flag was given.
+ */
+export function buildSenderLimitsBody(options) {
+    const body = readContractFlags(options, SENDER_LIMITS_PATCH_CONTRACT, SENDER_LIMITS_FLAG_OVERLAY);
+    const warmup = body.warmup;
+    if (warmup && warmup.start_date !== undefined)
+        delete warmup.enabled;
+    if (Object.keys(body).length === 0) {
+        throw new OxygenError("invalid_request", "Pass at least one limit flag (e.g. --invites-per-day), a working-hours flag (--timezone, --working-days, --working-hours-start, --working-hours-end), a warm-up flag (--warmup-restart / --warmup-disable / --warmup-start-date), --read-warmup-disable / --read-warmup-restart, --warmup-preset, --randomize-caps, or --weekend-full-volume.", { exitCode: 1 });
+    }
+    return body;
+}

package/dist/streamed-file-import.d.ts

@@ -0,0 +1,58 @@
+import { type RowsFileFormat } from "@oxygen/shared/file-import";
+/**
+ * Large-file imports (decision F.8, 2026-09-27: up to 5 GiB on the largest plans).
+ *
+ * The ordinary `tables import --file` path reads the whole file into memory and
+ * parses every row into an object before it uploads anything. That is fine at a
+ * few MiB and impossible at a few GiB: a V8 string tops out near 1 GiB and the
+ * parsed rows weigh many times the file. Above this threshold a CSV or JSONL
+ * file therefore never enters memory whole. One streaming pass counts its rows,
+ * hashes it and collects its columns; the file is then PUT to object storage
+ * straight from disk, and the worker streams it again from there.
+ *
+ * JSON and XLSX cannot stream (a JSON array has no record boundary, an XLSX is a
+ * zip), so they never take this path: they are capped at
+ * MAX_BUFFERED_IMPORT_PARSE_BYTES before anything is read.
+ */
+export declare const STREAMED_FILE_IMPORT_MIN_BYTES: number;
+/** Rows kept from the head of the file to infer a new table's column types from. */
+export declare const STREAMED_IMPORT_SAMPLE_ROWS = 2000;
+/** An upload that moves no bytes for this long is abandoned, whatever its size. */
+export declare const STREAMED_UPLOAD_STALL_TIMEOUT_MS = 120000;
+export declare function shouldStreamFileImport(format: RowsFileFormat, fileBytes: number): boolean;
+export type StreamedImportScan = {
+    rowCount: number;
+    sha256: string;
+    /** Every column the file names, in first-seen order (the whole file, not the sample). */
+    labels: string[];
+    sampleRows: Record<string, unknown>[];
+};
+/**
+ * Read the file once, as a stream: count its rows with the same parser the
+ * worker will use (so a malformed file fails here, before any upload), hash it,
+ * and collect its column labels. JSONL rows may each name different keys, so the
+ * labels come from every row; only the type-inference sample is bounded.
+ */
+export declare function scanStreamedImportFile(path: string, format: RowsFileFormat, options?: {
+    sampleRows?: number;
+}): Promise<StreamedImportScan>;
+/**
+ * The rows a target is prepared from: the sample, plus one empty row naming any
+ * column that first appears after it, so a created table gets every column the
+ * file has and an existing table's mapping sees every header.
+ */
+export declare function rowsForStreamedImportTarget(scan: StreamedImportScan): Record<string, unknown>[];
+/**
+ * PUT a file to a presigned URL straight from disk. Content-Length is sent
+ * explicitly (S3 refuses a chunked PUT, and the presigner signed the length),
+ * and the request is abandoned only when it stops moving, never for being big:
+ * a 5 GiB upload on a slow link is legitimate, a silent socket is not.
+ */
+export declare function putImportFileStream(input: {
+    uploadUrl: string;
+    path: string;
+    byteLength: number;
+    contentType: string;
+    stallTimeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<Response>;

package/dist/streamed-file-import.js

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { Readable } from "node:stream";
+import { iterateRowsFileStreamBatches, } from "@oxygen/shared/file-import";
+/**
+ * Large-file imports (decision F.8, 2026-09-27: up to 5 GiB on the largest plans).
+ *
+ * The ordinary `tables import --file` path reads the whole file into memory and
+ * parses every row into an object before it uploads anything. That is fine at a
+ * few MiB and impossible at a few GiB: a V8 string tops out near 1 GiB and the
+ * parsed rows weigh many times the file. Above this threshold a CSV or JSONL
+ * file therefore never enters memory whole. One streaming pass counts its rows,
+ * hashes it and collects its columns; the file is then PUT to object storage
+ * straight from disk, and the worker streams it again from there.
+ *
+ * JSON and XLSX cannot stream (a JSON array has no record boundary, an XLSX is a
+ * zip), so they never take this path: they are capped at
+ * MAX_BUFFERED_IMPORT_PARSE_BYTES before anything is read.
+ */
+export const STREAMED_FILE_IMPORT_MIN_BYTES = 64 * 1024 * 1024;
+/** Rows kept from the head of the file to infer a new table's column types from. */
+export const STREAMED_IMPORT_SAMPLE_ROWS = 2_000;
+/** An upload that moves no bytes for this long is abandoned, whatever its size. */
+export const STREAMED_UPLOAD_STALL_TIMEOUT_MS = 120_000;
+export function shouldStreamFileImport(format, fileBytes) {
+    return (format === "csv" || format === "jsonl") && fileBytes > STREAMED_FILE_IMPORT_MIN_BYTES;
+}
+/**
+ * Read the file once, as a stream: count its rows with the same parser the
+ * worker will use (so a malformed file fails here, before any upload), hash it,
+ * and collect its column labels. JSONL rows may each name different keys, so the
+ * labels come from every row; only the type-inference sample is bounded.
+ */
+export async function scanStreamedImportFile(path, format, options = {}) {
+    const sampleLimit = options.sampleRows ?? STREAMED_IMPORT_SAMPLE_ROWS;
+    const hash = createHash("sha256");
+    async function* hashedChunks() {
+        for await (const chunk of createReadStream(path)) {
+            const bytes = chunk;
+            hash.update(bytes);
+            yield bytes;
+        }
+    }
+    let rowCount = 0;
+    const labels = [];
+    const seen = new Set();
+    const sampleRows = [];
+    for await (const batch of iterateRowsFileStreamBatches(hashedChunks(), format, { batchSize: 1_000 })) {
+        rowCount += batch.length;
+        for (const row of batch) {
+            if (sampleRows.length < sampleLimit)
+                sampleRows.push(row);
+            for (const key of Object.keys(row)) {
+                if (key.startsWith("_") || seen.has(key))
+                    continue;
+                seen.add(key);
+                labels.push(key);
+            }
+        }
+    }
+    return { rowCount, sha256: hash.digest("hex"), labels, sampleRows };
+}
+/**
+ * The rows a target is prepared from: the sample, plus one empty row naming any
+ * column that first appears after it, so a created table gets every column the
+ * file has and an existing table's mapping sees every header.
+ */
+export function rowsForStreamedImportTarget(scan) {
+    const sampled = new Set(scan.sampleRows.flatMap((row) => Object.keys(row)));
+    const late = scan.labels.filter((label) => !sampled.has(label));
+    if (late.length === 0)
+        return scan.sampleRows;
+    return [...scan.sampleRows, Object.fromEntries(late.map((label) => [label, null]))];
+}
+/**
+ * PUT a file to a presigned URL straight from disk. Content-Length is sent
+ * explicitly (S3 refuses a chunked PUT, and the presigner signed the length),
+ * and the request is abandoned only when it stops moving, never for being big:
+ * a 5 GiB upload on a slow link is legitimate, a silent socket is not.
+ */
+export async function putImportFileStream(input) {
+    const stallTimeoutMs = input.stallTimeoutMs ?? STREAMED_UPLOAD_STALL_TIMEOUT_MS;
+    const controller = new AbortController();
+    let timer = null;
+    const arm = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => controller.abort(new Error("The upload stopped making progress.")), stallTimeoutMs);
+    };
+    async function* progressing() {
+        for await (const chunk of createReadStream(input.path)) {
+            arm();
+            yield chunk;
+        }
+        // The last byte is out; the store now has one stall window to answer.
+        arm();
+    }
+    arm();
+    try {
+        return await (input.fetchImpl ?? fetch)(input.uploadUrl, {
+            method: "PUT",
+            headers: {
+                "content-type": input.contentType,
+                "content-length": String(input.byteLength),
+            },
+            body: Readable.toWeb(Readable.from(progressing())),
+            duplex: "half",
+            signal: controller.signal,
+        });
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/ugc-commands.js

@@ -1,5 +1,19 @@
-import { registerUgcCommands as registerCommands, } from "@oxygen/cli-ugc";
+import { registerUgcCommands as registerCommands, UgcUsageError, } from "@oxygen/cli-ugc";
+import { OxygenError } from "@oxygen/shared/cli-result";
 import { requestOxygen } from "./http-client.js";
 export function registerUgcCommands(program, handle) {
-    registerCommands(program, { request: requestOxygen, handle });
+    registerCommands(program, {
+        request: requestOxygen,
+        // A malformed flag is the caller's input, so it reports as invalid_request.
+        handle: (command, options, action) => handle(command, options, async () => {
+            try {
+                return await action();
+            }
+            catch (error) {
+                if (error instanceof UgcUsageError)
+                    throw new OxygenError("invalid_request", error.message, { exitCode: 1 });
+                throw error;
+            }
+        }),
+    });
 }

package/dist/update.d.ts

@@ -12,9 +12,17 @@ export type UpdateOptions = {
     json?: boolean;
     package?: string;
     dryRun?: boolean;
+    /**
+     * Leave the skills refresh to the newly installed binary. An automatic update
+     * runs inside the OLD process, which the API may be refusing outright — its
+     * own skills request would be rejected for the very version being replaced.
+     */
+    skipSkillsInstall?: boolean;
 };
 type UpdateResult = {
     current_version: string;
+    /** Read back from the installed package after npm finished; null when unknown. */
+    installed_version?: string | null;
     package: string;
     command: string;
     dry_run: boolean;
@@ -24,10 +32,31 @@ type UpdateResult = {
 export declare function updateCli(options: UpdateOptions, runtime?: {
     env?: NodeJS.ProcessEnv;
     platform?: NodeJS.Platform;
+    argv?: readonly string[];
     modulePath?: string;
     spawnSync?: SpawnSyncLike;
     execFileSync?: ExecFileSyncLike;
 } & SkillsSourceRuntime): Promise<UpdateResult>;
+export type CliInstall = 
+/** `npm install -g`: npm can replace it in place with `--prefix`. */
+{
+    kind: "global";
+    prefix: string;
+    packageDir: string;
+}
+/** A project's own node_modules (npx, `npm install` in a directory, a pinned capsule). */
+ | {
+    kind: "local";
+    projectDir: string;
+    packageDir: string;
+}
+/** Running from a source checkout. */
+ | {
+    kind: "source";
+};
+export declare function detectCliInstall(modulePath: string): CliInstall;
 export declare function detectCliInstallPrefixFromPath(modulePath: string): string | null;
+/** The version npm actually left on disk for the running package. */
+export declare function readInstalledCliVersion(packageDir: string): string | null;
 export declare function resolveNpmExecutables(platform?: NodeJS.Platform): string[];
 export {};

package/dist/update.js

@@ -1,7 +1,10 @@
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { OXYGEN_VERSION, OxygenError } from "@oxygen/shared";
 import { runAutomaticSkillsInstall, skippedAutomaticSkillsInstall, } from "./skills.js";
+import { resolveCliBinaryName } from "./runtime.js";
 import { readOption } from "./util.js";
 import { quoteWindowsCmdArg } from "./windows-shim.js";
 const DEFAULT_CLI_PACKAGE_SPEC = "@oxygen-agent/cli@latest";
@@ -11,7 +14,9 @@ export async function updateCli(options, runtime = {}) {
     const platform = runtime.platform ?? process.platform;
     const spawn = runtime.spawnSync ?? spawnSync;
     const packageSpec = readOption(options.package) ?? DEFAULT_CLI_PACKAGE_SPEC;
-    const prefix = detectCliInstallPrefix(runtime.modulePath);
+    const modulePath = runtime.modulePath ?? fileURLToPath(import.meta.url);
+    const install = detectCliInstall(modulePath);
+    const prefix = install.kind === "global" ? install.prefix : null;
     const args = prefix
         ? ["install", "-g", "--prefix", prefix, packageSpec]
         : ["install", "-g", packageSpec];
@@ -19,6 +24,8 @@ export async function updateCli(options, runtime = {}) {
     // output). Quote args that contain shell-significant characters so a
     // copy-paste of the line works on install prefixes with spaces.
     const command = ["npm", ...args].map(quoteForDisplay).join(" ");
+    if (!options.dryRun)
+        assertUpdatableInstall(install, env, runtime.argv ?? process.argv);
     if (options.dryRun) {
         return {
             current_version: OXYGEN_VERSION,
@@ -49,17 +56,20 @@ export async function updateCli(options, runtime = {}) {
         if (!result.error && result.status === 0) {
             return {
                 current_version: OXYGEN_VERSION,
+                installed_version: install.kind === "global" ? readInstalledCliVersion(install.packageDir) : null,
                 package: packageSpec,
                 command,
                 dry_run: false,
                 updated: true,
-                skills_install: await runAutomaticSkillsInstall({
-                    env,
-                    platform,
-                    ...(runtime.credentials !== undefined ? { credentials: runtime.credentials } : {}),
-                    ...(runtime.fetch ? { fetch: runtime.fetch } : {}),
-                    ...(runtime.execFileSync ? { execFileSync: runtime.execFileSync } : {}),
-                }),
+                skills_install: options.skipSkillsInstall
+                    ? skippedAutomaticSkillsInstall("deferred_to_updated_cli")
+                    : await runAutomaticSkillsInstall({
+                        env,
+                        platform,
+                        ...(runtime.credentials !== undefined ? { credentials: runtime.credentials } : {}),
+                        ...(runtime.fetch ? { fetch: runtime.fetch } : {}),
+                        ...(runtime.execFileSync ? { execFileSync: runtime.execFileSync } : {}),
+                    }),
             };
         }
         break;
@@ -77,10 +87,7 @@ export async function updateCli(options, runtime = {}) {
         exitCode: 1,
     });
 }
-function detectCliInstallPrefix(modulePath = fileURLToPath(import.meta.url)) {
-    return detectCliInstallPrefixFromPath(modulePath);
-}
-export function detectCliInstallPrefixFromPath(modulePath) {
+export function detectCliInstall(modulePath) {
     const normalizedPath = modulePath.replace(/\\/g, "/");
     const markers = [
         "/node_modules/@oxygen-agent/cli/dist/",
@@ -91,11 +98,50 @@ export function detectCliInstallPrefixFromPath(modulePath) {
         if (markerIndex === -1)
             continue;
         const packageParent = normalizedPath.slice(0, markerIndex);
-        if (packageParent.endsWith("/lib"))
-            return packageParent.slice(0, -"/lib".length);
-        return packageParent;
+        const packageDir = normalizedPath.slice(0, markerIndex + marker.length - "/dist/".length);
+        if (packageParent.endsWith("/lib")) {
+            return { kind: "global", prefix: packageParent.slice(0, -"/lib".length), packageDir };
+        }
+        // npm's Windows global layout has no lib/: <prefix>\node_modules.
+        if (/^[A-Za-z]:\//.test(normalizedPath))
+            return { kind: "global", prefix: packageParent, packageDir };
+        // Anywhere else, `npm install -g --prefix <dir>` writes <dir>/lib/node_modules — a
+        // different tree from the one running — and reports success while nothing changed.
+        return { kind: "local", projectDir: packageParent, packageDir };
+    }
+    return { kind: "source" };
+}
+export function detectCliInstallPrefixFromPath(modulePath) {
+    const install = detectCliInstall(modulePath);
+    return install.kind === "global" ? install.prefix : null;
+}
+/** The version npm actually left on disk for the running package. */
+export function readInstalledCliVersion(packageDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function assertUpdatableInstall(install, env, argv) {
+    if (resolveCliBinaryName(env, argv) === "oxygen-dev") {
+        throw new OxygenError("cli_update_unsupported_install", "oxygen-dev is built from the dev branch, not installed from npm. "
+            + "Rebuild it with `npm run install-dev-cli` from the latest dev checkout.", { details: { install: "dev_build", update_command: "npm run install-dev-cli" }, exitCode: 1 });
+    }
+    if (install.kind === "local") {
+        throw new OxygenError("cli_update_unsupported_install", `This Oxygen CLI runs from a project-local install in ${install.projectDir}, which \`oxygen update\` cannot replace. `
+            + "Run `npm install @oxygen-agent/cli@latest` in that directory, or install globally with "
+            + "`npm install -g @oxygen-agent/cli`.", {
+            details: {
+                install: "local",
+                install_dir: install.projectDir,
+                update_command: "npm install @oxygen-agent/cli@latest",
+            },
+            exitCode: 1,
+        });
     }
-    return null;
 }
 export function resolveNpmExecutables(platform = process.platform) {
     return platform === "win32" ? ["cmd.exe"] : ["npm"];

package/dist/workflow-plan-limit-notices.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What the plan does to one workflow's trigger, as stderr lines beside the
+ * `workflows get` / `workflows apply` envelope: a cron the scheduler fires at
+ * the plan's minimum interval instead of as written (repricing L4.2, P-47), and
+ * the deliveries a minute a webhook trigger's URL accepts (L4.4). The envelope
+ * carries both as data (`workflow.trigger.slowedToPlanMinimum`, `rate_limit`).
+ */
+export declare function formatWorkflowPlanLimitNotices(data: unknown): string[];

package/dist/workflow-plan-limit-notices.js

@@ -0,0 +1,28 @@
+/**
+ * What the plan does to one workflow's trigger, as stderr lines beside the
+ * `workflows get` / `workflows apply` envelope: a cron the scheduler fires at
+ * the plan's minimum interval instead of as written (repricing L4.2, P-47), and
+ * the deliveries a minute a webhook trigger's URL accepts (L4.4). The envelope
+ * carries both as data (`workflow.trigger.slowedToPlanMinimum`, `rate_limit`).
+ */
+export function formatWorkflowPlanLimitNotices(data) {
+    const block = asRecord(data);
+    const workflow = asRecord(block?.workflow);
+    const trigger = asRecord(workflow?.trigger);
+    if (!block || !trigger)
+        return [];
+    const slug = typeof workflow?.slug === "string" ? workflow.slug : "workflow";
+    const notices = [];
+    const minutes = asRecord(trigger.slowedToPlanMinimum)?.planMinimumIntervalMinutes;
+    if (typeof minutes === "number") {
+        notices.push(`${slug}: schedule slowed — your plan runs a schedule at most every ${minutes} minutes, so this one fires every ${minutes} minutes instead of as written. Upgrade (\`oxygen billing change\`) or change the schedule.`);
+    }
+    const perWindow = asRecord(block.rate_limit)?.requests_per_window;
+    if (trigger.type === "webhook" && typeof perWindow === "number") {
+        notices.push(`${slug}: webhook accepts up to ${perWindow.toLocaleString("en-US")} deliveries a minute on your plan; more get HTTP 429 with Retry-After (\`oxygen limits show\`).`);
+    }
+    return notices;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}