@oxygen-agent/cli 1.1014.136 → 1.1014.619

package/dist/commands/commands.d.ts

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

package/dist/commands/commands.js

@@ -0,0 +1,45 @@
+import { readPositiveInt } from "../cli-values.js";
+import { buildCommandManifest, getCommandManifestEntry, searchCommandManifest, suggestCommandNames } from "../command-manifest.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { Command } from "commander";
+export function registerCommandsFamily(program, handleAsyncAction, binaryName) {
+    const commandsCommand = program
+        .command("commands")
+        .description("Discover CLI commands. With no subcommand, print the backwards-compatible full manifest.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("commands", options, async () => buildCommandManifest(program, binaryName));
+    });
+    commandsCommand
+        .addCommand(new Command("search")
+        .description("Find a bounded set of CLI commands from a natural-language outcome.")
+        .argument("<query...>", "Outcome or capability to find.")
+        .option("--limit <n>", "Maximum results (default 10, max 25).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (queryParts, options) => {
+        const outputOptions = { ...options, json: options.json || Boolean(commandsCommand.opts().json) };
+        await handleAsyncAction("commands search", outputOptions, async () => {
+            const manifest = buildCommandManifest(program, binaryName);
+            return searchCommandManifest(manifest, queryParts.join(" "), readPositiveInt(options.limit) ?? 10);
+        });
+    }))
+        .addCommand(new Command("get")
+        .description("Hydrate one exact CLI command with its arguments, flags, and safety markers.")
+        .argument("<command...>", "Exact command name returned by commands search.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (commandParts, options) => {
+        const outputOptions = { ...options, json: options.json || Boolean(commandsCommand.opts().json) };
+        await handleAsyncAction("commands get", outputOptions, async () => {
+            const manifest = buildCommandManifest(program, binaryName);
+            const exactName = commandParts.join(" ");
+            const command = getCommandManifestEntry(manifest, exactName);
+            if (!command) {
+                throw new OxygenError("command_not_found", `Unknown Oxygen command: ${exactName}`, {
+                    details: { did_you_mean: suggestCommandNames(manifest, exactName) },
+                    exitCode: 2,
+                });
+            }
+            return command;
+        });
+    }));
+}

package/dist/commands/comments.d.ts

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

package/dist/commands/comments.js

@@ -0,0 +1,188 @@
+import { readPositiveInt } from "../cli-values.js";
+import { COLLAB_BETA_NOTE, COLLAB_SUBJECT_PATH_HELP, COLLAB_SUBJECT_REF_HELP, collabLink, collabSnippet, collabStyles, collabText, collabTrailer, collectRepeatable, formatCollabAge, formatCollabWriteResult, handleCollabAction, readCollabPath, requireCollabSubject } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { isRecord, readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { COLLAB_SUBJECT_KINDS, COLLAB_SUBJECT_KINDS_PROSE, COLLAB_SUBJECT_PROSE } from "@oxygen/shared/collab";
+import { Command } from "commander";
+/** What a thread on each kind is usually about, for the group descriptions. */
+const COLLAB_SUBJECT_GLOSS = COLLAB_SUBJECT_KINDS
+    .map((kind) => `${kind} (${COLLAB_SUBJECT_PROSE[kind]})`)
+    .join("; ");
+/**
+ * `comments add`. Without --reply this is one POST. With --reply the CLI first
+ * resolves which thread owns that id, because the reply endpoint is keyed by
+ * THREAD while the id a user has in hand (from `comments list`, or from the
+ * `next_step` the API prints) is a COMMENT. Passing a thread id works too and
+ * replies at its top level — both ids sit side by side in the list output, and
+ * refusing the wrong one would be pedantry, not safety.
+ */
+async function handleCommentsAddAction(body, options) {
+    await handleCollabAction("comments add", options, async () => {
+        const subject = requireCollabSubject(options.on);
+        const path = readCollabPath(options.path);
+        const mentions = options.mention.map((value) => value.trim()).filter(Boolean);
+        const replyTo = readOption(options.reply);
+        if (!replyTo) {
+            const title = readOption(options.title);
+            return requestOxygen("/api/cli/collab/threads", {
+                method: "POST",
+                body: {
+                    subject_kind: subject.kind,
+                    subject_id: subject.id,
+                    ...(path ? { subject_path: path } : {}),
+                    ...(title ? { title } : {}),
+                    body,
+                    ...(mentions.length > 0 ? { mentions } : {}),
+                },
+            });
+        }
+        const target = await resolveCollabReplyTarget(subject, replyTo);
+        return requestOxygen(`/api/cli/collab/threads/${encodeURIComponent(target.threadId)}/comments`, {
+            method: "POST",
+            body: {
+                body,
+                ...(target.parentCommentId ? { parent_comment_id: target.parentCommentId } : {}),
+                ...(mentions.length > 0 ? { mentions } : {}),
+            },
+        });
+    }, formatCollabWriteResult);
+}
+async function resolveCollabReplyTarget(subject, replyTo) {
+    const params = new URLSearchParams({
+        subject: `${subject.kind}:${subject.id}`,
+        // `all`, not `open`: replying to a resolved thread is how a client reopens
+        // a conversation, and scoping the lookup to open threads would report the
+        // id as missing instead.
+        status: "all",
+    });
+    const listed = await requestOxygen(`/api/cli/collab/threads?${params.toString()}`);
+    const threads = Array.isArray(listed.threads) ? listed.threads.filter(isRecord) : [];
+    for (const thread of threads) {
+        if (thread.id === replyTo)
+            return { threadId: replyTo, parentCommentId: null };
+        const comments = Array.isArray(thread.comments) ? thread.comments.filter(isRecord) : [];
+        if (comments.some((comment) => comment.id === replyTo) && typeof thread.id === "string") {
+            return { threadId: thread.id, parentCommentId: replyTo };
+        }
+    }
+    throw new OxygenError("comment_not_found", `No comment or thread "${replyTo}" on ${subject.kind}:${subject.id}. List them with \`oxygen comments list --on ${subject.kind}:${subject.id} --status all\`.`, { details: { reply: replyTo, subject: `${subject.kind}:${subject.id}` }, exitCode: 4 });
+}
+function formatCollabThreads(data) {
+    const styles = collabStyles();
+    const threads = Array.isArray(data.threads) ? data.threads.filter(isRecord) : [];
+    const subject = collabText(data.subject, "this object");
+    const lines = ["", styles.bold(`Comments on ${subject}`)];
+    if (threads.length === 0) {
+        lines.push(`  ${styles.dim(collabText(data.hint, "No comment threads here yet."))}`);
+    }
+    for (const thread of threads) {
+        const status = collabText(thread.status, "open");
+        const badge = status === "resolved" ? styles.dim("[resolved]") : styles.green("[open]");
+        const title = collabText(thread.title, "");
+        lines.push("", `  ${badge} ${collabText(thread.id)}  ${styles.dim(`${thread.comment_count ?? 0} comment(s) · ${formatCollabAge(thread.created_at)} old`)}`);
+        if (title)
+            lines.push(`    ${styles.bold(title)}`);
+        if (typeof thread.subject_path === "string" && thread.subject_path) {
+            lines.push(`    ${styles.dim(`on ${thread.subject_path}`)}`);
+        }
+        const comments = Array.isArray(thread.comments) ? thread.comments.filter(isRecord) : [];
+        for (const comment of comments) {
+            const author = collabText(comment.author_email, "someone");
+            const marker = comment.parent_comment_id ? "  ↳" : "  •";
+            const edited = comment.edited_at ? styles.dim(" (edited)") : "";
+            const text = comment.deleted === true
+                ? styles.dim("(retracted)")
+                : collabSnippet(comment.body, 72);
+            lines.push(`    ${marker} ${styles.dim(`${formatCollabAge(comment.created_at)} ${author}`)}  ${text}${edited}`);
+            lines.push(`      ${styles.dim(collabText(comment.id))}`);
+        }
+        const threadLink = collabLink(thread);
+        if (threadLink)
+            lines.push(`    ${styles.dim(threadLink)}`);
+    }
+    lines.push(...collabTrailer(data));
+    lines.push("");
+    return lines.join("\n");
+}
+export function registerCommentsFamily(program, handleAsyncAction) {
+    program
+        .command("comments")
+        .description(`Threaded comments on any workspace object — ${COLLAB_SUBJECT_KINDS_PROSE} — so the client's go/no-go stops living in a Google Doc. A comment is state ABOUT a GTM artifact, never the artifact: resolving a thread changes no campaign. Address the subject with --on <kind>:<id>, and one row, cell, or column of a table with --path row:<rowId>[#<columnKey>] | column:<columnKey>. Threads are open until somebody resolves them; any member may resolve. The thing that actually BLOCKS work is an approval gate — see \`oxygen approvals\`. What a thread is usually about, per kind: ${COLLAB_SUBJECT_GLOSS}. ${COLLAB_BETA_NOTE}`)
+        .addCommand(new Command("add")
+        .description("Comment on a workspace object. Without --reply this opens a NEW thread with this comment as its first; with --reply it answers inside the existing one. @email tokens in the body are resolved to workspace members and notified, so --mention is only needed for someone you did not name in the text.")
+        .argument("<body...>", "What you want to say. Quote it, or let the shell pass it as words.")
+        .requiredOption("--on <kind:id>", COLLAB_SUBJECT_REF_HELP)
+        .option("--path <path>", COLLAB_SUBJECT_PATH_HELP)
+        .option("--reply <id>", "Answer inside an existing thread. Pass a comment id to nest under it, or a thread id to reply at that thread's top level.")
+        .option("--mention <email>", "Notify a workspace member. Repeatable.", collectRepeatable, [])
+        .option("--title <text>", "Title for a NEW thread. Ignored when replying.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (body, options) => {
+        await handleCommentsAddAction(body.join(" "), options);
+    }))
+        .addCommand(new Command("list")
+        .description("Every comment thread on one object, newest first, with its comments inline. Defaults to open threads only.")
+        .requiredOption("--on <kind:id>", COLLAB_SUBJECT_REF_HELP)
+        .option("--path <path>", `${COLLAB_SUBJECT_PATH_HELP} Omit to see every thread on the object.`)
+        .option("--status <status>", "open (default), resolved, or all.")
+        .option("--limit <n>", "Maximum threads to return.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleCollabAction("comments list", options, () => {
+            const subject = requireCollabSubject(options.on);
+            const path = readCollabPath(options.path);
+            const params = new URLSearchParams({ subject: `${subject.kind}:${subject.id}` });
+            if (path)
+                params.set("path", path);
+            const status = readOption(options.status);
+            if (status)
+                params.set("status", status);
+            const limit = readPositiveInt(options.limit);
+            if (limit !== undefined)
+                params.set("limit", String(limit));
+            return requestOxygen(`/api/cli/collab/threads?${params.toString()}`);
+        }, formatCollabThreads);
+    }))
+        .addCommand(new Command("show")
+        .description("One thread by its own id, with every comment. This is what to run when all you have is the id out of a notification email or a `/collab/threads/<id>` link — `list` needs the object the thread hangs off, which that link does not tell you.")
+        .argument("<threadId>", "Thread id (from a notification email, a deep-link, or `oxygen comments list`).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (threadId, options) => {
+        await handleCollabAction("comments show", options, () => requestOxygen(`/api/cli/collab/threads/${encodeURIComponent(threadId)}`), 
+        // Same payload shape `comments list` returns, one thread long, so the
+        // renderer is the same one.
+        formatCollabThreads);
+    }))
+        .addCommand(new Command("resolve")
+        .description("Mark a thread settled, or reopen it with --reopen. Idempotent both ways: re-resolving keeps the original resolver and timestamp. This is conversation state only — it never unblocks an approval gate.")
+        .argument("<threadId>", "Thread id (from `oxygen comments list`).")
+        .option("--reopen", "Reopen a resolved thread instead of resolving it.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (threadId, options) => {
+        await handleCollabAction("comments resolve", options, () => requestOxygen(`/api/cli/collab/threads/${encodeURIComponent(threadId)}/resolve`, {
+            method: "POST",
+            body: { resolved: !options.reopen },
+        }), formatCollabWriteResult);
+    }))
+        .addCommand(new Command("edit")
+        .description("Rewrite one of your own comments. AUTHOR ONLY. The edit stamps edited_at — a thread that decided a launch is evidence, and evidence that changes without a trace is not evidence.")
+        .argument("<commentId>", "Comment id (from `oxygen comments list`).")
+        .argument("<body...>", "The replacement text.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (commentId, body, options) => {
+        await handleCollabAction("comments edit", options, () => requestOxygen(`/api/cli/collab/comments/${encodeURIComponent(commentId)}`, {
+            method: "PATCH",
+            body: { body: body.join(" ") },
+        }), formatCollabWriteResult);
+    }))
+        .addCommand(new Command("delete")
+        .description("Retract one of your own comments. AUTHOR ONLY, idempotent. The row stays so the thread remains a complete audit trail; the text is redacted on every read path.")
+        .argument("<commentId>", "Comment id (from `oxygen comments list`).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (commentId, options) => {
+        await handleCollabAction("comments delete", options, () => requestOxygen(`/api/cli/collab/comments/${encodeURIComponent(commentId)}`, {
+            method: "DELETE",
+        }), formatCollabWriteResult);
+    }));
+}

package/dist/commands/companies.d.ts

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

package/dist/commands/companies.js

@@ -0,0 +1,312 @@
+import { parseJsonObject, readJsonObjectOption, readPositiveInt } from "../cli-values.js";
+import { readCsvOption, readFileIfPresent, readFilterSelectionOption, readPositiveNumber, readRangeOption, readSearchPlanJson } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { Command } from "commander";
+function readCompaniesSearchPlanBody(options, promptArg) {
+    // The prompt may arrive as --prompt or as the positional argument; the flag wins.
+    const promptSource = options.prompt ?? promptArg;
+    const targetCount = readPositiveInt(options.targetCount);
+    const filters = readCompanySearchFilters(options);
+    return {
+        // Omit when neither was given so the request still reaches the server, which
+        // answers with a clean `prompt is required.` instead of crashing readFileIfPresent.
+        ...(promptSource !== undefined ? { prompt: readFileIfPresent(promptSource) } : {}),
+        ...(targetCount !== undefined ? { target_count: targetCount } : {}),
+        ...(options.sourceIntent ? { source_intent: options.sourceIntent } : {}),
+        ...(filters ? { filters } : {}),
+        ...(options.estimate ? { estimate: true } : {}),
+        ...(options.materializePreview ? { materialize_preview: true } : {}),
+    };
+}
+function readCompaniesSearchRunBody(options, promptArg) {
+    // The prompt may arrive as --prompt or as the positional argument; the flag wins.
+    const promptSource = options.prompt ?? promptArg;
+    const prompt = promptSource ? readFileIfPresent(promptSource) : null;
+    const plan = options.planJson ? readSearchPlanJson(options.planJson) : null;
+    if (!prompt && !plan && options.source !== "company_search" && options.source !== "hiring" && options.source !== "google_maps") {
+        throw new OxygenError("invalid_request", "Pass --prompt, --plan-json, or --source company_search|hiring|google_maps with --source-filters-json.", { exitCode: 1 });
+    }
+    const maxPages = readPositiveInt(options.maxPages);
+    const maxCredits = readPositiveNumber(options.maxCredits);
+    const targetCount = readPositiveInt(options.targetCount);
+    // With --source the server reads only --source-filters-json. Forward the planner's
+    // filters anyway so the server refuses them by name instead of the CLI dropping
+    // them and the run buying an unfiltered search (OXP-1.39.2 S6).
+    const filters = prompt || options.source ? readCompanySearchFilters(options) : null;
+    return {
+        ...(prompt ? { prompt } : {}),
+        ...(plan ? { plan } : {}),
+        ...(options.source ? { source: options.source } : {}),
+        ...(options.sourceFiltersJson ? { source_filters: parseJsonObject(readFileIfPresent(options.sourceFiltersJson)) } : {}),
+        ...(readOption(options.tableName) ? { table_name: readOption(options.tableName) } : {}),
+        ...(options.routeId ? { route_id: options.routeId } : {}),
+        ...(options.toolId ? { tool_id: options.toolId } : {}),
+        ...(options.table ? { table: options.table } : {}),
+        ...(options.project ? { project: options.project } : {}),
+        ...(options.upsertKey ? { upsert_key: options.upsertKey } : {}),
+        ...(options.mode ? { mode: options.mode } : {}),
+        ...(maxPages !== undefined ? { max_pages: maxPages } : {}),
+        ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+        ...(targetCount !== undefined ? { target_count: targetCount } : {}),
+        ...(options.sourceIntent ? { source_intent: options.sourceIntent } : {}),
+        ...(filters ? { filters } : {}),
+        ...(prompt && options.estimate ? { estimate: true } : {}),
+        ...(options.approved ? { approved: true } : {}),
+    };
+}
+// CompanySearchFilters mirror (structural — the server validates the shape). Builds a
+// filters object from individual --industries/--countries/--employees/etc. flags, then
+// lets --filters-json win per top-level filter path so an agent can pass a precise object
+// while still using convenience flags for the rest.
+function readCompanySearchFilters(options) {
+    const filters = {};
+    const industries = readIncludeExclude(options.industries, options.excludeIndustries);
+    if (industries)
+        filters.industries = industries;
+    const keywords = readIncludeExclude(options.keywords, options.excludeKeywords);
+    if (keywords)
+        filters.keywords = keywords;
+    const countries = readCsvOption(options.countries);
+    if (countries.length > 0)
+        filters.geo = { countries };
+    const employeeCount = readRangeOption(options.employees, "--employees");
+    if (employeeCount)
+        filters.employee_count = employeeCount;
+    const fundingStages = readCsvOption(options.fundingStages);
+    if (fundingStages.length > 0)
+        filters.funding = { stages: fundingStages };
+    const technologies = readIncludeExclude(options.technologies);
+    if (technologies)
+        filters.technologies = technologies;
+    const revenue = readRangeOption(options.revenue, "--revenue");
+    if (revenue)
+        filters.revenue_usd = revenue;
+    const founded = readRangeOption(options.founded, "--founded");
+    if (founded)
+        filters.founded_year = founded;
+    const lookalike = readCsvOption(options.lookalike);
+    if (lookalike.length > 0)
+        filters.lookalike_domains = lookalike;
+    const explicit = options.filtersJson ? parseJsonObject(readFileIfPresent(options.filtersJson)) : null;
+    if (explicit) {
+        for (const [key, value] of Object.entries(explicit)) {
+            filters[key] = value;
+        }
+    }
+    return Object.keys(filters).length > 0 ? filters : null;
+}
+function readIncludeExclude(include, exclude) {
+    const includeValues = readCsvOption(include);
+    const excludeValues = readCsvOption(exclude);
+    const result = {};
+    if (includeValues.length > 0)
+        result.include = includeValues;
+    if (excludeValues.length > 0)
+        result.exclude = excludeValues;
+    return Object.keys(result).length > 0 ? result : null;
+}
+// `source` names the companies table the Employee Finder fans out over. The
+// offset/limit window rides INSIDE `source` when the source is declared here; with
+// a saved plan it rides as `source_overrides`, which the run route applies on top
+// of the plan's own source.
+/** The company lanes that share Company Search's flow; anything else is a typo, not a provider. */
+function readCompanySearchSource(value) {
+    const source = readOption(value) ?? "company_search";
+    if (source !== "company_search" && source !== "hiring" && source !== "google_maps") {
+        throw new OxygenError("invalid_request", "--source must be company_search, hiring or google_maps.", { exitCode: 1 });
+    }
+    return source;
+}
+function readCompanySourceQuery(value) {
+    const source = readCompanySearchSource(value);
+    return source === "company_search" ? "" : `?source=${source}`;
+}
+function readCompaniesEnrichBody(table, options) {
+    const body = { table };
+    const fields = readCsvOption(options.missingFields);
+    const providers = readCsvOption(options.providers);
+    const selection = readCompaniesEnrichSelection(options);
+    const mode = readOption(options.mode);
+    const maxCredits = readPositiveNumber(options.maxCredits);
+    if (fields.length > 0)
+        body.missing_fields = fields;
+    if (providers.length > 0)
+        body.providers = providers;
+    if (selection)
+        body.selection = selection;
+    if (mode)
+        body.mode = mode;
+    if (maxCredits !== undefined)
+        body.max_credits = maxCredits;
+    if (options.approved)
+        body.approved = true;
+    if (options.force !== undefined)
+        body.force = Boolean(options.force);
+    return body;
+}
+function readCompaniesEnrichSelection(options) {
+    const explicitSelection = readJsonObjectOption(options.selectionJson);
+    const hasAll = Boolean(options.all);
+    const limit = readPositiveInt(options.limit);
+    const rowIds = readCsvOption(options.rowIds);
+    const filterSelection = readFilterSelectionOption(options.filterJson);
+    const selectedModes = [
+        Boolean(explicitSelection),
+        hasAll,
+        Boolean(limit),
+        rowIds.length > 0,
+        Boolean(filterSelection),
+    ].filter(Boolean).length;
+    if (selectedModes > 1) {
+        throw new OxygenError("invalid_company_enrichment", "Pass only one row scope option.", { exitCode: 1 });
+    }
+    if (explicitSelection)
+        return explicitSelection;
+    if (hasAll)
+        return { mode: "all" };
+    if (limit)
+        return { mode: "limit", limit };
+    if (rowIds.length > 0)
+        return { mode: "row_ids", row_ids: rowIds };
+    if (filterSelection)
+        return filterSelection;
+    return undefined;
+}
+export function registerCompaniesFamily(program, handleAsyncAction) {
+    program
+        .command("companies")
+        .description("Company prospecting and account enrichment workflows.")
+        .addCommand(new Command("search")
+        .description("Plan, dry-run, or queue provider-backed company search.")
+        .addCommand(new Command("filters")
+        .description("List Company Search filter fields and options without a provider call, including every enum field's full accepted-value list. --source hiring lists the Job postings filters instead (job.* and company.*).")
+        .option("--source <source>", "company_search (default), google_maps, or hiring: live job postings for the roles you name, one row per posting with a link to it.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("companies search filters", options, () => requestOxygen(`/api/cli/companies/search/preview${readCompanySourceQuery(options.source)}`));
+    }))
+        .addCommand(new Command("preview")
+        .description("Preview up to 50 rows free, using native filters from companies search filters. --source google_maps previews 20 businesses with a q business-and-area filter; total_results is unavailable when the API publishes no total. --source hiring previews matching job postings with an exact total. Totals, notes and the priced next step come first and the rows last; each row is compact (name, domain, LinkedIn, headcount, industry, location, a one-line description) unless --view full.")
+        .requiredOption("--filters-json <json-or-file>", 'Native filters as JSON or @file/path. Google Maps requires q, placeId or cid; other sources accept {} for all results.')
+        .option("--source <source>", "company_search (default), hiring or google_maps. Filters for hiring nest under job and company, e.g. {\"job\":{\"title\":{\"include\":[\"Account Executive\"]}}}.")
+        .option("--view <view>", "compact (default) or full: full adds each row's provider record as raw_source, about 2.5 KB a company.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("companies search preview", options, () => requestOxygen("/api/cli/companies/search/preview", {
+            method: "POST",
+            body: {
+                filters: parseJsonObject(readFileIfPresent(options.filtersJson)),
+                ...(readCompanySearchSource(options.source) !== "company_search" ? { source: readCompanySearchSource(options.source) } : {}),
+                ...(options.view !== undefined ? { view: options.view } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("plan")
+        .description("Compile a company-search prompt into ordered provider routes without provider calls. To turn a list of company NAMES into websites or domains, pass --source-intent url_recovery (e.g. --prompt \"Find the websites for these companies: <names>\" --source-intent url_recovery). The plan carries provider_availability: a route on a benched managed provider reads degraded with a next_action.")
+        .argument("[prompt]", "Prompt text or @file (same as --prompt). The --prompt flag wins if both are given.")
+        .option("--prompt <text-or-file>", "Company-search prompt, or a path to a prompt file.")
+        .option("--target-count <n>", "Desired company count. Omit it to plan every match the live route can reach, up to a tenth of the spendable credits. Single-plan ceiling 50,000; larger requests return an explicit clamp warning and segmentation guidance.")
+        .option("--source-intent <intent>", "Override detected intent: sizing, structured, lookalike, technology, hiring, local, known_source, concept, web, url, or fallback.")
+        .option("--filters-json <json-or-file>", "CompanySearchFilters JSON inline or a @file/path; wins over individual flags per top-level filter path.")
+        .option("--industries <csv>", "Comma-separated industries to include.")
+        .option("--exclude-industries <csv>", "Comma-separated industries to exclude.")
+        .option("--keywords <csv>", "Comma-separated keywords to include.")
+        .option("--exclude-keywords <csv>", "Comma-separated keywords to exclude.")
+        .option("--countries <csv>", "Comma-separated ISO 3166-1 alpha-2 country codes.")
+        .option("--employees <range>", "Employee count range: 20-200, 500+, or -50.")
+        .option("--funding-stages <csv>", "Comma-separated funding stages: pre_seed, seed, series_a, ...")
+        .option("--technologies <csv>", "Comma-separated technologies to include.")
+        .option("--revenue <range>", "Annual revenue (USD) range: 1000000-20000000, 1000000+, or -5000000.")
+        .option("--founded <range>", "Founded year range: 2015-2024, 2020+, or -2010.")
+        .option("--lookalike <csv>", "Comma-separated lookalike company domains.")
+        .option("--estimate", "Run a free server-side preflight pass: resolves provider enums and a free count probe for an estimated match count (zero credits).")
+        .option("--materialize-preview", "Create a route-plan table, without company results. For free company rows use companies search preview.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (promptArg, options) => {
+        await handleAsyncAction("companies search plan", options, () => requestOxygen("/api/cli/companies/search/plan", {
+            method: "POST",
+            body: readCompaniesSearchPlanBody(options, promptArg),
+        }));
+    }))
+        .addCommand(new Command("run")
+        .description("Return a dry-run request or queue a live company-search ingestion run.")
+        .option("--source <source>", "Use company_search, hiring or google_maps with --source-filters-json instead of a prompt or plan. hiring sources the live job postings for the roles you name, one row per posting (up to 5,000 per search), each with its posting URL, date and hiring company.")
+        .option("--source-filters-json <json-or-file>", 'Same nested filters as the free preview, e.g. {"employee_count":{"min":10}} or, with --source hiring, {"job":{"title":{"include":["Account Executive"]}}}.')
+        .option("--table-name <name>", "Name the table this run creates. Ignored when --table names an existing table, which must already exist.")
+        .argument("[prompt]", "Prompt text or @file (same as --prompt). The --prompt flag wins if both are given.")
+        .option("--prompt <text-or-file>", "Company-search prompt, or a path to a prompt file.")
+        .option("--plan-json <json-or-file>", "Plan JSON returned by companies search plan, or a path to a JSON file.")
+        .option("--route-id <id>", "Route id from the plan to execute.")
+        .option("--tool-id <tool>", "Tool id from the plan to execute.")
+        .option("--table <table>", "Existing table id or slug to receive rows. If omitted for live, Oxygen creates a table.")
+        .option("--project <project>", "Folder (project) id or slug the created table lands in. Ignored with --table. Defaults to the workspace default folder.")
+        .option("--upsert-key <column>", "Column key used for live upsert. Must match the plan upsert key, usually domain.")
+        .option("--mode <mode>", "dry_run or live. Defaults to dry_run.")
+        .option("--max-pages <n>", "Maximum provider pages to ingest. Defaults to the route estimate, and is itself capped by --target-count: asking for more pages than that many rows needs cannot add rows.")
+        .option("--max-credits <n>", "Required credit ceiling for live runs.")
+        .option("--target-count <n>", "How many rows to source, independently of the free preview size. Omit it to take every match, up to what one query reaches and a tenth of the spendable credits (target_count_default says which bound applied). Maps previews up to 20; page size varies by source. Total matches may be unavailable. This count bounds pagination: --max-pages cannot exceed the pages it needs, and a run that stops because of it reports stopped_by row_target.")
+        .option("--source-intent <intent>", "Override detected intent when planning from --prompt.")
+        .option("--filters-json <json-or-file>", "CompanySearchFilters JSON inline or a @file/path when planning from --prompt; wins over individual flags per top-level filter path.")
+        .option("--industries <csv>", "Comma-separated industries to include when planning from --prompt.")
+        .option("--exclude-industries <csv>", "Comma-separated industries to exclude when planning from --prompt.")
+        .option("--keywords <csv>", "Comma-separated keywords to include when planning from --prompt.")
+        .option("--exclude-keywords <csv>", "Comma-separated keywords to exclude when planning from --prompt.")
+        .option("--countries <csv>", "Comma-separated ISO 3166-1 alpha-2 country codes when planning from --prompt.")
+        .option("--employees <range>", "Employee count range when planning from --prompt: 20-200, 500+, or -50.")
+        .option("--funding-stages <csv>", "Comma-separated funding stages when planning from --prompt.")
+        .option("--technologies <csv>", "Comma-separated technologies to include when planning from --prompt.")
+        .option("--revenue <range>", "Annual revenue (USD) range when planning from --prompt.")
+        .option("--founded <range>", "Founded year range when planning from --prompt.")
+        .option("--lookalike <csv>", "Comma-separated lookalike company domains when planning from --prompt.")
+        .option("--estimate", "Run a free server-side preflight pass when planning from --prompt: resolves provider enums and a free count probe (zero credits).")
+        .option("--approved", "Required for live runs after inspecting dry-run output.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (promptArg, options) => {
+        await handleAsyncAction("companies search run", options, () => requestOxygen("/api/cli/companies/search/run", {
+            method: "POST",
+            body: readCompaniesSearchRunBody(options, promptArg),
+        }));
+    })))
+        .addCommand(new Command("enrich")
+        .description("Preview or run a company enrichment waterfall over an existing table.")
+        .addCommand(new Command("preview")
+        .description("Inspect missing company fields, provider routing, and credit estimates without provider calls.")
+        .argument("<table>", "Table id or slug.")
+        .option("--missing-fields <fields>", "Comma-separated fields to fill; accepts every key `oxygen find company --list-fields` prints, not just the identity set. Derived fields (description, founded_year, hq_country, funding_stage, latest_funding_round, investors, job_openings, parent_company, subsidiaries) are read from a payload the run already fetches and add no provider lane of their own.")
+        .option("--providers <providers>", "Comma-separated provider order pool. Defaults to scraper,blitzapi,apollo,peopledatalabs,theirstack,leadmagic.")
+        .option("--all", "Preview all rows.")
+        .option("--limit <n>", "Preview a limited row scope.")
+        .option("--row-ids <ids>", "Comma-separated row ids.")
+        .option("--filter-json <json>", "Filter object or array for row selection.")
+        .option("--selection-json <json>", "Raw table action selection JSON.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("companies enrich preview", options, () => requestOxygen("/api/cli/company-enrichment/preview", {
+            method: "POST",
+            body: readCompaniesEnrichBody(table, options),
+        }));
+    }))
+        .addCommand(new Command("run")
+        .description("Queue a live company enrichment waterfall after explicit approval, or return a dry-run plan.")
+        .argument("<table>", "Table id or slug.")
+        .option("--missing-fields <fields>", "Comma-separated fields to fill.")
+        .option("--providers <providers>", "Comma-separated provider pool.")
+        .option("--mode <mode>", "dry_run or live. Defaults to live. dry_run returns the same plan as `companies enrich preview` and creates no column; only a live run creates the target columns it fills. To reuse a published workspace Function, inspect `functions list` and attach it with `functions bind` before running the column.")
+        .option("--max-credits <n>", "Required credit ceiling for live runs.")
+        .option("--approved", "Approve this live paid run after inspecting the preview.")
+        .option("--all", "Run on all rows.")
+        .option("--limit <n>", "Run on a limited row scope.")
+        .option("--row-ids <ids>", "Comma-separated row ids.")
+        .option("--filter-json <json>", "Filter object or array for row selection.")
+        .option("--selection-json <json>", "Raw table action selection JSON.")
+        .option("--force", "Re-run the waterfall audit column even when it already has a value.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("companies enrich run", options, () => requestOxygen("/api/cli/company-enrichment/run", {
+            method: "POST",
+            body: readCompaniesEnrichBody(table, options),
+        }));
+    })));
+}

package/dist/commands/connections.d.ts

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

package/dist/commands/connections.js

@@ -0,0 +1,39 @@
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { Command } from "commander";
+export function registerConnectionsFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("connections")
+        .description("Read a LinkedIn account's 1st-degree connections (your network) into a Clay-like workspace table you can enrich, qualify, and enroll from. Imports run as a slow, durable background drip under a dedicated conservative read budget — they never burst and never starve the sequencer's own reads.")
+        .addCommand(new Command("import")
+        .description("Start (or re-arm) a connections import. Connections drip into a workspace table over many ticks; poll `connections status` to watch them accrue. The import keeps the table fresh by periodically re-walking the network in the background (new connections dedupe in). No messages are sent and no Oxygen credits are charged.")
+        .option("--account <ref>", "Sender account to import (sender id, connection id, or Unipile account id). Omit to import every active LinkedIn account.")
+        .option("--table <ref>", "Existing workspace table (id or slug) to import into. Omit to create or reuse a 'LinkedIn Connections' table.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("connections import", options, () => {
+            const account = readOption(options.account);
+            const table = readOption(options.table);
+            return requestOxygen("/api/cli/linkedin/connections/import", {
+                method: "POST",
+                body: {
+                    ...(account ? { account } : {}),
+                    ...(table ? { table } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("status")
+        .description("Show connections-import progress (per-sender drip status, connections ingested, last error) plus a preview of the connections table and a deep-link to open it.")
+        .option("--account <ref>", "Scope to one sender account (sender id, connection id, or Unipile account id).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("connections status", options, () => {
+            const account = readOption(options.account);
+            const params = new URLSearchParams();
+            if (account)
+                params.set("account", account);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/linkedin/connections/status${suffix ? `?${suffix}` : ""}`);
+        });
+    })));
+}

package/dist/commands/context.d.ts

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